out_stage.h File Reference

A binding prepared beside the one in force, and taken whole. More...

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

Go to the source code of this file.

Data Structures
struct	out_stage_t
	The CHAN_CFG and OUTPUTS pages prepared beside the bank in force. More...
struct	out_stage_ops_t
	What the IOmcu does with a page once the commit has matched. More...

Functions
void	out_stage_init (out_stage_t *st, const uint16_t *cfg, const uint16_t *slots)
	Start from the pages in force; NULL starts from the pages' defaults.
uint8_t	out_stage_cfg_write (out_stage_t *st, uint8_t off, uint8_t n, const uint16_t *in)
	A window of BIND_CFG or BIND_OUT written: 0, or the link_nack_t outputs_chan_cfg_write() and outputs_slots_write() give for the same window, and then nothing of it is stored.
uint8_t	out_stage_slots_write (out_stage_t *st, uint8_t off, uint8_t n, const uint16_t *in)
	A window of BIND_OUT written: 0, or the link_nack_t outputs_slots_write() gives for the same window, and then nothing of it is stored.
void	out_stage_cfg_read (const out_stage_t *st, uint8_t off, uint8_t n, uint16_t *out)
	Copies a window of the prepared CHAN_CFG page.
void	out_stage_slots_read (const out_stage_t *st, uint8_t off, uint8_t n, uint16_t *out)
	Copies a window of the prepared OUTPUTS page.
uint16_t	out_stage_crc (const uint16_t *cfg, const uint16_t *slots)
	The CRC a commit names: CRC-16/CCITT-FALSE (polynomial 0x1021, seed 0xFFFF, link_crc()) over the 32 CHAN_CFG registers and then the 32 OUTPUTS registers, each as its low byte and then its high byte.
uint16_t	out_stage_held_crc (const out_stage_t *st)
	The same of what st holds; 0 for NULL.
uint8_t	out_stage_commit (const out_stage_t *st, uint16_t crc, const uint16_t *cfg_in_force, const out_stage_ops_t *ops, void *ctx)
	A write of LINK_BD_COMMIT.

Detailed Description

A binding prepared beside the one in force, and taken whole.

The IOmcu's half of the BIND_CFG, BIND_OUT and BIND pages (protocol 4.10; see link_pages.h). A CHAN_CFG and an OUTPUTS page are written here a frame at a time and change nothing; a commit that names their CRC (cyclic redundancy check) puts both in force or neither.

The rules that judge a page in force are the IOmcu's and need its bank and its silicon, so the commit calls them through out_stage_ops_t. The order, the comparison and what is put back after a refusal are here and host-tested.

SPDX-License-Identifier: MIT

Function Documentation

out_stage_cfg_read()

void out_stage_cfg_read	(	const out_stage_t *	st,
		uint8_t	off,
		uint8_t	n,
		uint16_t *	out )

Copies a window of the prepared CHAN_CFG page.

Registers at or past LINK_CC_COUNT read as 0. Nothing is done when st or out is NULL.

Parameters

st	The staged pages, not changed.
off	First register of the window.
n	Number of registers to copy.
out	Receives the n register values.

out_stage_cfg_write()

uint8_t out_stage_cfg_write	(	out_stage_t *	st,
		uint8_t	off,
		uint8_t	n,
		const uint16_t *	in )

A window of BIND_CFG or BIND_OUT written: 0, or the link_nack_t outputs_chan_cfg_write() and outputs_slots_write() give for the same window, and then nothing of it is stored.

Parameters

st	The staged pages.
off	First register of the window.
n	Number of registers in the window.
in	The n register values to write.

Returns

0 when stored. LINK_NACK_BAD_RANGE when st is NULL, otherwise the refusal of outputs_chan_cfg_write() for the window.

out_stage_commit()

uint8_t out_stage_commit	(	const out_stage_t *	st,
		uint16_t	crc,
		const uint16_t *	cfg_in_force,
		const out_stage_ops_t *	ops,
		void *	ctx )

A write of LINK_BD_COMMIT.

LINK_NACK_BAD_VALUE, and nothing is called, when crc is not the CRC of what st holds. Otherwise the prepared CHAN_CFG page is taken, then the prepared OUTPUTS page. A refusal of the first changes nothing; a refusal of the second puts the bank and cfg_in_force, the CHAN_CFG page, back as they were before the commit. Either is returned as the reason. 0 when both are in force.

Parameters

st	The prepared pages.
crc	The CRC the host named in the commit.
cfg_in_force	The CHAN_CFG page in force, read before the takes.
ops	The callbacks that judge and store the pages. The pointers take_cfg, take_slots and put_cfg must be set.
ctx	Passed to each callback in ops unchanged.

Returns

0 when both pages are in force. The refusal of take_cfg or take_slots otherwise. LINK_NACK_BAD_VALUE when st, cfg_in_force or ops is NULL, when one of the required callbacks is NULL, or when crc does not match.

out_stage_crc()

uint16_t out_stage_crc	(	const uint16_t *	cfg,
		const uint16_t *	slots )

The CRC a commit names: CRC-16/CCITT-FALSE (polynomial 0x1021, seed 0xFFFF, link_crc()) over the 32 CHAN_CFG registers and then the 32 OUTPUTS registers, each as its low byte and then its high byte.

The panel computes it over the pages it sent, the IOmcu over what it holds prepared.

Parameters

cfg	The CHAN_CFG page, LINK_CC_COUNT registers.
slots	The OUTPUTS page, LINK_OS_COUNT registers.

Returns

The CRC-16 value. 0 when cfg or slots is NULL.

out_stage_held_crc()

uint16_t out_stage_held_crc

(

const out_stage_t *

st

)

The same of what st holds; 0 for NULL.

Parameters

st	The staged pages, not changed.

Returns

The CRC of st->cfg and st->slots, as out_stage_crc() gives it.

out_stage_init()

void out_stage_init	(	out_stage_t *	st,
		const uint16_t *	cfg,
		const uint16_t *	slots )

Start from the pages in force; NULL starts from the pages' defaults.

Does nothing when st is NULL.

Parameters

st	The staged pages, overwritten.
cfg	The CHAN_CFG page in force (LINK_CC_COUNT registers), or NULL.
slots	The OUTPUTS page in force (LINK_OS_COUNT registers), or NULL.

out_stage_slots_read()

void out_stage_slots_read	(	const out_stage_t *	st,
		uint8_t	off,
		uint8_t	n,
		uint16_t *	out )

Copies a window of the prepared OUTPUTS page.

Registers at or past LINK_OS_COUNT read as 0. Nothing is done when st or out is NULL.

Parameters

st	The staged pages, not changed.
off	First register of the window.
n	Number of registers to copy.
out	Receives the n register values.

out_stage_slots_write()

uint8_t out_stage_slots_write	(	out_stage_t *	st,
		uint8_t	off,
		uint8_t	n,
		const uint16_t *	in )

A window of BIND_OUT written: 0, or the link_nack_t outputs_slots_write() gives for the same window, and then nothing of it is stored.

Parameters

st	The staged pages.
off	First register of the window.
n	Number of registers in the window.
in	The n register values to write.

Returns

0 when stored. LINK_NACK_BAD_RANGE when st is NULL, otherwise the refusal of outputs_slots_write() for the window.