link_artxfer.c File Reference

Assembling a board drawing. More...

#include "link_artxfer.h"
#include <stddef.h>
#include <string.h>
#include "link_crc.h"

Functions
static uint32_t	blocks_for (uint32_t bytes)
	How many blocks a payload of this many bytes takes, rounded up.
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.

See link_artxfer.h.

SPDX-License-Identifier: MIT

Function Documentation

blocks_for()

uint32_t blocks_for ( uint32_t bytes )

static

How many blocks a payload of this many bytes takes, rounded up.

Parameters

bytes

Payload length in bytes.

Returns

Blocks of LINK_AD_BYTES needed for bytes.

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.