out_store_rec.h File Reference

What a record in the IOmcu's output store carries, and how a record an earlier build wrote is read. More...

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

Go to the source code of this file.

Data Structures
struct	out_store_t
	What is kept: the two pages that describe the outputs; the PD mini's wiring – SUPPLY's ENABLE to BAUD – so a module left on can be switched off after a restart before any panel has written the page; and the current monitors' set-up; and the phase tap's set-up; and where the programming ports are and how their pulse is shaped. More...
struct	out_store_hdr_t
	A record's head; the configuration follows it with no padding. More...
struct	out_store_record_t
	A record as the newest version writes it. More...

Macros
#define	OUT_STORE_VERSION   8u
	Record versions. A save writes OUT_STORE_VERSION; the older ones are read from records an earlier build wrote.
#define	OUT_STORE_VERSION_V7   7u
#define	OUT_STORE_VERSION_V6   6u
#define	OUT_STORE_VERSION_V5   5u
#define	OUT_STORE_VERSION_V4   4u
#define	OUT_STORE_VERSION_V3   3u
#define	OUT_STORE_SLOT_BYTES   512u
	The slot a version 8 record is written into, and the one-page slot of versions 3 to 7.
#define	OUT_STORE_SLOT_BYTES_V7   256u
#define	OUT_STORE_MAGIC   0x7263626FuL
	Magic at the start of a record: "rcbo" in ASCII.

Functions
size_t	out_store_cfg_size (uint16_t version)
	How many bytes of configuration a record of version carries, from the start of an out_store_t: 128 for version 3, 136 for 4, 160 for 5, 176 for 6 (two of them the word prog_func), 208 for 7, 288 for 8. 0 for a version this build does not read.
size_t	out_store_rec_size (uint16_t version)
	A whole record of version, head and configuration: 308 bytes for version 8, 228 for 7. 0 for a version not read.
bool	out_store_rec_build (uint8_t *rec, size_t slot, uint16_t version, uint32_t seq, const out_store_t *cfg)
	A record of version for cfg and seq into the slot bytes at rec: the record, then 0xFF to the slot's end, as an erased slot reads, so a program of the whole slot changes nothing past the record. A save writes OUT_STORE_VERSION; an older version is what an earlier build wrote. False, and nothing written, for a version not read or a record longer than slot.
bool	out_store_rec_check (const uint8_t *rec, size_t avail, uint16_t min_version, uint16_t max_version, uint16_t *version, uint32_t *seq)
	Whether the avail bytes at rec start with a whole record of a version this build reads, from min_version to max_version: magic, version, zero count and checksum.
bool	out_store_cfg_read (uint16_t version, const void *cfg, out_store_t *out)
	A record's configuration, as version wrote it at cfg (out_store_cfg_size() bytes), into out at the newest layout.

Detailed Description

What a record in the IOmcu's output store carries, and how a record an earlier build wrote is read.

firmware/iomcu/src/out_store.c puts the record in flash; this file is the part of it that has no flash in it – the configuration's layout by record version, and the defaults a field an older record does not carry starts at – so the host suite holds it.

Versions read:

3 the output bindings: OUTPUTS and CHAN_CFG. 4 and the PD mini's wiring, SUPPLY's ENABLE to BAUD (protocol 4.3). 5 and the current monitors' set-up, SENSE's registers 0 to 11 (protocol 4.7). 6 and the phase tap's set-up, TONE's registers 0 to 6 (protocol 4.8). 7 and the programming ports' pin, slew and endpoints, 4 registers for each of the PROG page's 4 ports (protocol 4.13). From protocol 4.26 the word before them, spare until then, holds each port's function (prog_func) with no version change, in version 7 and 8 records alike; 0 is every port's default function (port 0 SERVO PWM, the others NONE). An image of 4.13 to 4.25 reads the word as spare and writes 0 back, and an image older than 4.25 reads no version 8 record at all and starts with an empty store. A board taken to such an image and back has its ports on their default functions; from 4.25 it keeps their pins, from an older image it keeps nothing. 8 and the INA3221s' map, SENSE_MAP's registers 0 to 25 and whether it is in force (protocol 4.25), and 12 per-channel current limits, 0 until a page carries them. 308 bytes: the first version over one 256-byte flash page.

Each version appends to the one before, so a record's configuration is the version before's with fields after it. A save always writes the newest version.

Slots. Version 8 is written into slots of two flash pages (OUT_STORE_SLOT_BYTES, 512 bytes): 8 a 4KiB sector, 16 in the store. Versions 3 to 7 lie in slots of one page (OUT_STORE_SLOT_BYTES_V7), 16 a sector, and are read from that layout while the store holds no version 8 record.

The record. A header – magic, the count of 0 bits from the checksum on and its complement, a CRC-16 from the version on, the version and the sequence number – then the configuration, out_store_cfg_size() bytes. out_store_rec_check() takes a record only when the zero count holds (out_store_intact()) and the checksum agrees, so a program or an erase cut off part way, in either page, reads as no record.

SPDX-License-Identifier: MIT

Function Documentation

out_store_cfg_read()

bool out_store_cfg_read	(	uint16_t	version,
		const void *	cfg,
		out_store_t *	out )

A record's configuration, as version wrote it at cfg (out_store_cfg_size() bytes), into out at the newest layout.

What the version does not carry starts as its page does: the supply disabled at the module's 19200 baud, both current monitors off at their defaults (sense_page_defaults()), the phase tap off at its defaults (tone_page_defaults()), programming port 0 on PROG_PORT_DEFAULT_PIN and the other ports without a pin (prog_port_defaults()).

False for a version this build does not read, and out is untouched.

Parameters

version	Record version the configuration was written with.
cfg	The configuration, out_store_cfg_size() bytes. Not NULL.
out	Receives the configuration in the newest layout. Not NULL.

Returns

true when read, false for a version not read or a NULL pointer.

out_store_cfg_size()

size_t out_store_cfg_size

(

uint16_t

version

)

How many bytes of configuration a record of version carries, from the start of an out_store_t: 128 for version 3, 136 for 4, 160 for 5, 176 for 6 (two of them the word prog_func), 208 for 7, 288 for 8. 0 for a version this build does not read.

Each version appends: its size is where the next version's field starts.

Parameters

version

Record version, one of the OUT_STORE_VERSION values.

Returns

Configuration size in bytes, or 0 for a version not read.

How many bytes of configuration a record of version carries, from the start of an out_store_t: 128 for version 3, 136 for 4, 160 for 5, 176 for 6 (two of them the word prog_func), 208 for 7, 288 for 8. 0 for a version this build does not read.

out_store_rec_build()

bool out_store_rec_build	(	uint8_t *	rec,
		size_t	slot,
		uint16_t	version,
		uint32_t	seq,
		const out_store_t *	cfg )

A record of version for cfg and seq into the slot bytes at rec: the record, then 0xFF to the slot's end, as an erased slot reads, so a program of the whole slot changes nothing past the record. A save writes OUT_STORE_VERSION; an older version is what an earlier build wrote. False, and nothing written, for a version not read or a record longer than slot.

Parameters

rec	Receives the record and the 0xFF fill, slot bytes.
slot	Size of the slot in bytes.
version	Record version, one of the OUT_STORE_VERSION values.
seq	Sequence number stored in the head.
cfg	The configuration to store, out_store_cfg_size() bytes of it.

Returns

true when the record is written, false when rec or cfg is NULL, the version is not read, or the record is longer than slot.

out_store_rec_check()

bool out_store_rec_check	(	const uint8_t *	rec,
		size_t	avail,
		uint16_t	min_version,
		uint16_t	max_version,
		uint16_t *	version,
		uint32_t *	seq )

Whether the avail bytes at rec start with a whole record of a version this build reads, from min_version to max_version: magic, version, zero count and checksum.

On true, its version and sequence number. A record longer than avail is no record. The two-page layout takes version 8 alone: a version 7 record that happens to start a two-page slot is the layout before's, read with the rest of its slots.

Parameters

rec	The bytes to check.
avail	Number of bytes at rec.
min_version	Lowest record version accepted.
max_version	Highest record version accepted.
version	Receives the record's version on true. May be NULL.
seq	Receives the record's sequence number on true. May be NULL.

Returns

true when the record is whole and in range, false otherwise, including when rec is NULL or avail is below the head size.

out_store_rec_size()

size_t out_store_rec_size

(

uint16_t

version

)

A whole record of version, head and configuration: 308 bytes for version 8, 228 for 7. 0 for a version not read.

Parameters

version

Record version, one of the OUT_STORE_VERSION values.

Returns

Record size in bytes, the head plus out_store_cfg_size(), or 0 for a version not read.