link_artxfer.h File Reference

Assembling a board drawing out of the blocks the link carries it in. More...

#include <stdbool.h>
#include <stdint.h>
#include "link_pages.h"

Go to the source code of this file.

Data Structures
struct	link_art_meta_t
	What the IOmcu says its drawing is, off the ARTWORK page. More...
struct	link_artxfer_t
	State of one board drawing transfer. More...

Functions
bool	link_artxfer_meta_ok (const uint16_t *meta, link_art_meta_t *out)
	Whether these LINK_AW_COUNT registers can describe a drawing at all.
bool	link_artxfer_begin (link_artxfer_t *x, const uint16_t *meta, uint8_t *buf, uint32_t cap)
	Read the metadata and get ready to assemble into buf.
uint16_t	link_artxfer_next (const link_artxfer_t *x)
	Which block to ask for.
bool	link_artxfer_take (link_artxfer_t *x, const uint16_t *data)
	Place one ART_DATA window.
bool	link_artxfer_complete (const link_artxfer_t *x)
	Every block placed.
bool	link_artxfer_verify (const link_artxfer_t *x)
	And they are: the payload matches the CRC and the hash the IOmcu declared.
void	link_artserve_meta (uint16_t *regs, uint16_t format, uint16_t width, uint16_t height, uint32_t bytes, uint16_t crc, uint32_t hash)
	The LINK_AW_COUNT registers ARTWORK answers for bytes of payload, with the CRC and hash the generator emitted beside it.
void	link_artserve_block (uint16_t *regs, const uint8_t *payload, uint32_t bytes, uint16_t block)
	The LINK_AD_COUNT registers ART_DATA answers while LINK_AD_BLOCK holds block: the block number, then its bytes, the low byte of a register first.

Detailed Description

Assembling a board drawing out of the blocks the link carries it in.

The transfer happens once and the result is kept. So the failure that matters is not a slow transfer but a quiet one: a block lost and skipped, or a reply arriving for a block other than the one asked for, assembled into a drawing that is wrong in a way nobody sees until an operator wires a lead by it.

Blocks are therefore taken strictly in order, one at a time, and anything else is refused rather than placed. The whole payload is checked against the CRC (cyclic redundancy check) and the hash the IOmcu declared before any of it counts as the board's drawing.

Nothing here talks to the wire. It is fed register windows and says which block to ask for next.

SPDX-License-Identifier: MIT

Function Documentation

link_artserve_block()

void link_artserve_block	(	uint16_t *	regs,
		const uint8_t *	payload,
		uint32_t	bytes,
		uint16_t	block )

The LINK_AD_COUNT registers ART_DATA answers while LINK_AD_BLOCK holds block: the block number, then its bytes, the low byte of a register first.

A block past the payload carries its number and zeros.

Parameters

regs	Receives the LINK_AD_COUNT registers; NULL is ignored.
payload	The payload bytes; NULL leaves the data zero.
bytes	Payload length in bytes.
block	Block number requested.

link_artserve_meta()

void link_artserve_meta	(	uint16_t *	regs,
		uint16_t	format,
		uint16_t	width,
		uint16_t	height,
		uint32_t	bytes,
		uint16_t	crc,
		uint32_t	hash )

The LINK_AW_COUNT registers ARTWORK answers for bytes of payload, with the CRC and hash the generator emitted beside it.

All zero for no payload: LINK_AW_BLOCKS of zero is how a board says it carries none.

Parameters

regs	Receives the LINK_AW_COUNT registers; NULL is ignored.
format	The format, a link_art_format_t.
width	Outline width, in 0.01mm.
height	Outline height, in 0.01mm.
bytes	Payload length in bytes.
crc	CRC of the payload.
hash	FNV-1a hash of the payload.

link_artxfer_begin()

bool link_artxfer_begin	(	link_artxfer_t *	x,
		const uint16_t *	meta,
		uint8_t *	buf,
		uint32_t	cap )

Read the metadata and get ready to assemble into buf.

Refuses what link_artxfer_meta_ok() refuses, and a length longer than cap. A transfer that cannot end well should not take the link first.

Parameters

x	The transfer state to set up.
meta	The LINK_AW_COUNT registers of the ARTWORK page.
buf	Receives the payload.
cap	Size of buf, in bytes.

Returns

true when the transfer may start, else false.

link_artxfer_complete()

bool link_artxfer_complete

(

const link_artxfer_t *

x

)

Every block placed.

Says nothing about whether they are the right bytes.

Parameters

x	The transfer state.

Returns

true when all payload bytes are placed.

link_artxfer_meta_ok()

bool link_artxfer_meta_ok	(	const uint16_t *	meta,
		link_art_meta_t *	out )

Whether these LINK_AW_COUNT registers can describe a drawing at all.

Everything that does not depend on where the drawing would go: the one format this build reads, LINK_ART_DRAWING; an outline; a length from a drawing header up to LINK_DRAW_MAX_BYTES; and the block count that length implies. Split out because the caller has to know the size before it can find room, and a page that cannot be a drawing should be refused before anything is allocated for it rather than after.

Parameters

meta	The LINK_AW_COUNT registers of the ARTWORK page.
out	Receives the decoded metadata when the test passes.

Returns

true when the registers describe a drawing, else false.

link_artxfer_next()

uint16_t link_artxfer_next

(

const link_artxfer_t *

x

)

Which block to ask for.

Meaningless once the transfer is complete.

Parameters

x	The transfer state.

Returns

The block number, or 0 when x is NULL or not begun.

link_artxfer_take()

bool link_artxfer_take	(	link_artxfer_t *	x,
		const uint16_t *	data )

Place one ART_DATA window.

Refuses a window whose LINK_AD_BLOCK is not the one being waited for, and places nothing: a block out of order is a reply to a question that was not asked, and guessing where it belongs is how a hole is filled with the wrong bytes. The caller asks again.

Parameters

x	The transfer state.
data	The LINK_AD_COUNT registers of the ART_DATA window.

Returns

true when the block was placed, else false.

link_artxfer_verify()

bool link_artxfer_verify

(

const link_artxfer_t *

x

)

And they are: the payload matches the CRC and the hash the IOmcu declared.

Separate from complete() because they fail differently. Incomplete is a transfer to carry on with; complete and wrong is one to throw away, and the difference decides whether anything is written to flash.

Parameters

x	The transfer state.

Returns

true when the transfer is complete and both checks match.