art_fetch.c File Reference

Fetching a board's drawing. More...

#include "art_fetch.h"
#include <stddef.h>
#include <string.h>
#include "link_pages.h"

Functions
static art_fetch_state_t	fail (art_fetch_t *f, const char *why)
	Mark a fetch failed, with the reason.
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.

See art_fetch.h.

SPDX-License-Identifier: MIT

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.

fail()

art_fetch_state_t fail ( art_fetch_t * f, const char * why )

static

Mark a fetch failed, with the reason.

Parameters

f	Fetch state.
why	Reason text; kept as the fetch's reason.

Returns

ART_FETCH_FAILED.