art_fetch.h File Reference

Fetching a board's drawing: the order of the transactions, without the link underneath them. More...

#include <stdbool.h>
#include <stdint.h>
#include "art_store.h"
#include "link_artxfer.h"

Go to the source code of this file.

Data Structures
struct	art_transport_t
	How the sequence reaches the far end. More...
struct	art_fetch_t
	State of one fetch. More...

Enumerations
enum	art_fetch_state_t { ART_FETCH_IDLE = 0 , ART_FETCH_RUNNING , ART_FETCH_DONE , ART_FETCH_FAILED }
	States of a fetch. More...

Functions
bool	art_fetch_meta (const art_transport_t *t, uint16_t *meta_regs, uint32_t *bytes, const char **why)
	What the far end says its drawing is: LINK_AW_COUNT registers into meta_regs.
bool	art_fetch_key (const uint16_t *meta_regs, uint16_t board, art_entry_t *out)
	The cache entry meta_regs describe for board: the content key a kept drawing has to match field for field (art_store_read_same()) before it is shown.
bool	art_fetch_begin (art_fetch_t *f, const uint16_t *meta_regs, uint8_t *buf, uint32_t cap)
	Get ready to assemble into buf.
art_fetch_state_t	art_fetch_step (art_fetch_t *f, const art_transport_t *t, unsigned blocks)
	Ask for up to blocks of it.
uint16_t	art_fetch_format (const art_fetch_t *f)
	What the drawing is, once it is whole.
uint16_t	art_fetch_width (const art_fetch_t *f)
	The width of the drawing.
uint16_t	art_fetch_height (const art_fetch_t *f)
	The height of the drawing.
uint16_t	art_fetch_crc (const art_fetch_t *f)
	The CRC of the drawing.
uint32_t	art_fetch_hash (const art_fetch_t *f)
	The hash of the drawing.
uint32_t	art_fetch_bytes (const art_fetch_t *f)
	The size of the drawing in bytes.
const char *	art_fetch_why (const art_fetch_t *f)
	Why it stopped, for a log line.

Detailed Description

Fetching a board's drawing: the order of the transactions, without the link underneath them.

The panel asks the IOmcu what its drawing is, then asks for it a block at a time. The sequence is small and the failures are all quiet ones: a block skipped, a reply for a block nobody asked for, a drawing that arrives whole and wrong. Those are worth a test, and the task it runs in cannot be one.

So the transport is passed in. On the panel it is the CAN (Controller Area Network) link; in the suite it is a device answering out of memory, which is how the order can be interrupted on purpose and the result inspected.

Nothing here loops without a bound: a step does the number of blocks it is given and returns. The caller owns how much of its own time to spend, because on the panel that caller also beats the safety line.

SPDX-License-Identifier: MIT

Enumeration Type Documentation

art_fetch_state_t

enum art_fetch_state_t

States of a fetch.

Enumerator
ART_FETCH_IDLE	nothing under way
ART_FETCH_RUNNING	more blocks to ask for
ART_FETCH_DONE	whole, and it is the drawing it claimed
ART_FETCH_FAILED	art_fetch_why() says what stopped it

Function Documentation

art_fetch_begin()

bool art_fetch_begin	(	art_fetch_t *	f,
		const uint16_t *	meta_regs,
		uint8_t *	buf,
		uint32_t	cap )

Get ready to assemble into buf.

False when the metadata cannot describe a drawing that fits.

Parameters

f	Fetch state to start.
meta_regs	Registers from art_fetch_meta().
buf	Buffer to assemble the drawing into.
cap	Size of buf in bytes.

Returns

true when the metadata describes a drawing that fits in buf.

art_fetch_bytes()

uint32_t art_fetch_bytes

(

const art_fetch_t *

f

)

The size of the drawing in bytes.

Parameters

f	Fetch state.

Returns

The value from the fetched metadata; 0 when f is NULL.

art_fetch_crc()

uint16_t art_fetch_crc

(

const art_fetch_t *

f

)

The CRC of the drawing.

Parameters

f	Fetch state.

Returns

The value from the fetched metadata; 0 when f is NULL.

art_fetch_format()

uint16_t art_fetch_format

(

const art_fetch_t *

f

)

What the drawing is, once it is whole.

Parameters

f	Fetch state.

Returns

The value from the fetched metadata; 0 when f is NULL.

art_fetch_hash()

uint32_t art_fetch_hash

(

const art_fetch_t *

f

)

The hash of the drawing.

Parameters

f	Fetch state.

Returns

The value from the fetched metadata; 0 when f is NULL.

art_fetch_height()

uint16_t art_fetch_height

(

const art_fetch_t *

f

)

The height of the drawing.

Parameters

f	Fetch state.

Returns

The value from the fetched metadata; 0 when f is NULL.

art_fetch_key()

bool art_fetch_key	(	const uint16_t *	meta_regs,
		uint16_t	board,
		art_entry_t *	out )

The cache entry meta_regs describe for board: the content key a kept drawing has to match field for field (art_store_read_same()) before it is shown.

False, with out zeroed, when the registers cannot describe a drawing.

Parameters

meta_regs	Registers from art_fetch_meta().
board	Board the drawing is for.
out	Receives the cache entry.

Returns

true when the registers describe a drawing.

art_fetch_meta()

bool art_fetch_meta	(	const art_transport_t *	t,
		uint16_t *	meta_regs,
		uint32_t *	bytes,
		const char **	why )

What the far end says its drawing is: LINK_AW_COUNT registers into meta_regs.

False when it has none, when the page is not there at all – an IOmcu built before it – or when what it says cannot be a drawing. Those are different things to somebody reading a log, so why is set to which; it may be NULL, and it is never left pointing at nothing.

Everything that can be checked without knowing where the drawing would go is checked here, and bytes is left zero when any of it fails: the caller finds room from that number, and a page that cannot be a drawing should not size an allocation first and be refused second.

Parameters

t	Transport to the far end.
meta_regs	Receives LINK_AW_COUNT registers.
bytes	Receives the drawing size in bytes; zero on failure.
why	Receives the reason on failure; may be NULL.

Returns

true when the far end describes a drawing.

art_fetch_step()

art_fetch_state_t art_fetch_step	(	art_fetch_t *	f,
		const art_transport_t *	t,
		unsigned	blocks )

Ask for up to blocks of it.

Returns what to do next. DONE means the whole payload arrived and matched the CRC and the hash the far end declared, so the buffer is the drawing; FAILED means it did not, and nothing should be kept.

Parameters

f	Fetch state.
t	Transport to the far end.
blocks	Most blocks to ask for in this step.

Returns

The state after this step.

art_fetch_why()

const char * art_fetch_why

(

const art_fetch_t *

f

)

Why it stopped, for a log line.

Never NULL.

Parameters

f	Fetch state.

Returns

The reason text.

art_fetch_width()

uint16_t art_fetch_width

(

const art_fetch_t *

f

)

The width of the drawing.

Parameters

f	Fetch state.

Returns

The value from the fetched metadata; 0 when f is NULL.