praet_tabula_vexillorum.h File Reference

Every bit of the channel flag word, and the assertions that keep the map from drifting. More...

#include "mmgr.h"

Go to the source code of this file.

Macros
#define	PRAET_SEPARATUS
	Detached: the channel holds no engine and no vector.
#define	PRAET_ADNEXUS
	Attached: the channel holds the engine and will take a transfer.
#define	PRAET_BUSY
	Busy: the engine is moving bytes on this channel.
#define	PRAET_OK
	Ok: the last transfer finished and the channel is still attached.
#define	PRAET_CORE_BITS
	Bits the quaternary core occupies, at the bottom of the word.
#define	PRAET_CORE_MASK
	The two bits the quaternary core occupies.
#define	PRAET_ID_CLAIMED
	Token id of the status set while the channel holds an interrupt vector.
#define	PRAET_ID_SETTLING
	Token id of the status set while the engine is settling.
#define	PRAET_ID_SEPARANS
	Token id of the status set while a detach is asked for and not finished.
#define	PRAET_ID_ERROR
	Token id of the status set where the last transfer ended in an error.
#define	PRAET_ID_STALLED
	Token id of the status set where a running channel went unkicked for a whole window.
#define	PRAET_ID_ABANDONED
	Token id of the status set where a stalled transfer was backed out.
#define	PRAET_ID_SCRUBBED
	Token id of the status set where a stalled transfer's bytes were treated as unsafe.
#define	PRAET_ID_MEASURED
	Token id of the status set where the boundary word was measured during a recovery.
#define	PRAET_STATUS_COUNT
	How many status token ids there are.
#define	PRAET_STATUS_SHIFT
	First bit the statuses occupy, the bit above the core.
#define	PRAET_STATUS_BIT(id_)
	The bit a status token id owns.
#define	PRAET_STATUS_MASK
	Every bit the statuses occupy, derived from how many there are.
#define	PRAET_CLAIMED
	Set while the channel holds an interrupt vector.
#define	PRAET_SETTLING
	Set while the engine is settling and will take no transfer.
#define	PRAET_SEPARANS
	Set where a detach has been asked for and the channel has not finished tearing down.
#define	PRAET_ERROR
	Set where the last transfer ended in an error, clear where it completed.
#define	PRAET_STALLED
	Set where a running channel went a whole keepalive window without being kicked.
#define	PRAET_ABANDONED
	Set where a stalled transfer was backed out and its bytes left as they were.
#define	PRAET_SCRUBBED
	Set where a stalled transfer was resolved by treating its bytes as unsafe.
#define	PRAET_MEASURED
	Set where a recovery measured the word the engine was in the middle of.
#define	PRAET_EVERY_STATUS
	Every status, listed by name.
#define	PRAET_REGION_SHIFT
	First bit of the region descriptor.
#define	PRAET_REGION_BITS
	How wide the region descriptor is.
#define	PRAET_REGION_MAX
	The largest descriptor the region field holds.
#define	PRAET_REGION_MASK
	The bits the region descriptor occupies once shifted into place.
#define	PRAET_REGION_FIELD(region_)
	A region descriptor placed in the field the map gives it.
#define	PRAET_REGION_ID_HIGHEST
	The largest region token id there is.
#define	PRAET_MAP_MASK
	Every bit the map accounts for.

Enumerations
enum	PraetRegion {   PRAET_REGION_INTERNAL ,   PRAET_REGION_EXTERNAL }
	The regions a channel can be attached over. More...

Detailed Description

Every bit of the channel flag word, and the assertions that keep the map from drifting.

Author

dstroy0 (Douglas Quigg) dquig.nosp@m.g123.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

Date

2026-09-01

Note

The map is ours, and for that reason it needs checking. Nothing outside this library assigns these bits. A status added at the wrong offset or a region moved one byte down is a change no compiler would question and no test would necessarily reach. Placing one status on top of the region descriptor already happened once here.

Statuses are named by token id and their bits are derived from it. A name and its bit cannot disagree. What the assertions below check is the id set: that it is dense, that no two ids collide, and that the three fields do not overlap each other.

The map is the same on every build. A status a build never sets still owns its bit, because a flag word read on one part has to mean what it means on another.

Definition in file praet_tabula_vexillorum.h.

Macro Definition Documentation

PRAET_SEPARATUS

#define PRAET_SEPARATUS

Detached: the channel holds no engine and no vector.

Definition at line 33 of file praet_tabula_vexillorum.h.

PRAET_ADNEXUS

#define PRAET_ADNEXUS

Attached: the channel holds the engine and will take a transfer.

Definition at line 38 of file praet_tabula_vexillorum.h.

PRAET_BUSY

#define PRAET_BUSY

Busy: the engine is moving bytes on this channel.

Note

The DMA busy, not the reader/setter's lock. The two are separate concerns and the lock lives in its own volatile.

Definition at line 46 of file praet_tabula_vexillorum.h.

PRAET_OK

#define PRAET_OK

Ok: the last transfer finished and the channel is still attached.

Note

The transfer's result, not the channel's health. A channel that failed carries PRAET_ERROR alongside, and so the two are separate bits.

Definition at line 54 of file praet_tabula_vexillorum.h.

PRAET_CORE_BITS

#define PRAET_CORE_BITS

Bits the quaternary core occupies, at the bottom of the word.

Definition at line 59 of file praet_tabula_vexillorum.h.

PRAET_CORE_MASK

#define PRAET_CORE_MASK

The two bits the quaternary core occupies.

Note

The core sits at the bottom with every status above it, and so reading the state is a mask and reading a status is a test. Nothing shifts.

Definition at line 67 of file praet_tabula_vexillorum.h.

PRAET_ID_CLAIMED

#define PRAET_ID_CLAIMED

Token id of the status set while the channel holds an interrupt vector.

Definition at line 72 of file praet_tabula_vexillorum.h.

PRAET_ID_SETTLING

#define PRAET_ID_SETTLING

Token id of the status set while the engine is settling.

Definition at line 77 of file praet_tabula_vexillorum.h.

PRAET_ID_SEPARANS

#define PRAET_ID_SEPARANS

Token id of the status set while a detach is asked for and not finished.

Definition at line 82 of file praet_tabula_vexillorum.h.

PRAET_ID_ERROR

#define PRAET_ID_ERROR

Token id of the status set where the last transfer ended in an error.

Definition at line 87 of file praet_tabula_vexillorum.h.

PRAET_ID_STALLED

#define PRAET_ID_STALLED

Token id of the status set where a running channel went unkicked for a whole window.

Definition at line 92 of file praet_tabula_vexillorum.h.

PRAET_ID_ABANDONED

#define PRAET_ID_ABANDONED

Token id of the status set where a stalled transfer was backed out.

Definition at line 97 of file praet_tabula_vexillorum.h.

PRAET_ID_SCRUBBED

#define PRAET_ID_SCRUBBED

Token id of the status set where a stalled transfer's bytes were treated as unsafe.

Definition at line 102 of file praet_tabula_vexillorum.h.

PRAET_ID_MEASURED

#define PRAET_ID_MEASURED

Token id of the status set where the boundary word was measured during a recovery.

Definition at line 107 of file praet_tabula_vexillorum.h.

PRAET_STATUS_COUNT

#define PRAET_STATUS_COUNT

How many status token ids there are.

Note

Raise this when a status is added, and the assertion on PRAET_EVERY_STATUS fails until the new one is listed there too.

Definition at line 115 of file praet_tabula_vexillorum.h.

PRAET_STATUS_SHIFT

#define PRAET_STATUS_SHIFT

First bit the statuses occupy, the bit above the core.

Definition at line 120 of file praet_tabula_vexillorum.h.

PRAET_STATUS_BIT

#define PRAET_STATUS_BIT

(

id_

)

The bit a status token id owns.

Parameters

[in]

id_

Status token id, below PRAET_STATUS_COUNT.

Returns

That id's bit, placed above the core.

Note

Every status below is defined through this, and so no status carries a hand-written bit that could disagree with the id beside it.

Definition at line 130 of file praet_tabula_vexillorum.h.

PRAET_STATUS_MASK

#define PRAET_STATUS_MASK

Every bit the statuses occupy, derived from how many there are.

Definition at line 135 of file praet_tabula_vexillorum.h.

PRAET_CLAIMED

#define PRAET_CLAIMED

Set while the channel holds an interrupt vector.

Note

Claimed at attach and released at detach. There is no reason to hold a vector for a memory mover that is not moving anything, and the claim gives the context one owner.

Definition at line 143 of file praet_tabula_vexillorum.h.

PRAET_SETTLING

#define PRAET_SETTLING

Set while the engine is settling and will take no transfer.

Definition at line 148 of file praet_tabula_vexillorum.h.

PRAET_SEPARANS

#define PRAET_SEPARANS

Set where a detach has been asked for and the channel has not finished tearing down.

Definition at line 153 of file praet_tabula_vexillorum.h.

PRAET_ERROR

#define PRAET_ERROR

Set where the last transfer ended in an error, clear where it completed.

Definition at line 158 of file praet_tabula_vexillorum.h.

PRAET_STALLED

#define PRAET_STALLED

Set where a running channel went a whole keepalive window without being kicked.

Note

Says the engine stopped moving, and says nothing about whether the transfer finished. A stalled channel is still busy, because nothing has told this library otherwise.

Definition at line 166 of file praet_tabula_vexillorum.h.

PRAET_ABANDONED

#define PRAET_ABANDONED

Set where a stalled transfer was backed out and its bytes left as they were.

Note

Owns its bit on every build. A build with recovery off never sets it, and the bit stays reserved to keep a flag word meaning one thing everywhere.

Definition at line 174 of file praet_tabula_vexillorum.h.

PRAET_SCRUBBED

#define PRAET_SCRUBBED

Set where a stalled transfer was resolved by treating its bytes as unsafe.

Note

The bytes are the caller's and this context has no pointer to them, and so nothing here scrubs anything. The flag records the decision; the caller zeroes its own storage.

Definition at line 182 of file praet_tabula_vexillorum.h.

PRAET_MEASURED

#define PRAET_MEASURED

Set where a recovery measured the word the engine was in the middle of.

Note

What tells a reader that the boundary checksum means anything. A checksum of zero is a legal one. A reader that took the value alone could not tell a measured word from an unmeasured context.

A context whose declaration chose the DISABLE token never sets this, and neither does a recovery whose sample already landed on a word boundary - there is no partial word to measure.

Definition at line 194 of file praet_tabula_vexillorum.h.

PRAET_EVERY_STATUS

#define PRAET_EVERY_STATUS

Every status, listed by name.

Note

Written out by hand, because this is the half of the check that has to come from somewhere other than PRAET_STATUS_COUNT. Comparing a list of names against a count neither one produced is what catches a duplicated id or a status nobody placed.

Definition at line 203 of file praet_tabula_vexillorum.h.

PRAET_REGION_SHIFT

#define PRAET_REGION_SHIFT

First bit of the region descriptor.

Note

A byte on a byte boundary. The descriptor is a number derived from the address space that the region is inferred from, and so nothing here stores an address. Placing it at a byte edge lets a build that wants to compress it to eight bits do so without moving a status.

The third byte and not the second. Statuses grow upward from the core and the region has to start above all of them - at bit 8 it shared a bit with PRAET_SCRUBBED, which reads as a region whose low bit flips when a transfer is scrubbed.

Definition at line 217 of file praet_tabula_vexillorum.h.

PRAET_REGION_BITS

#define PRAET_REGION_BITS

How wide the region descriptor is.

Definition at line 222 of file praet_tabula_vexillorum.h.

PRAET_REGION_MAX

#define PRAET_REGION_MAX

The largest descriptor the region field holds.

Definition at line 227 of file praet_tabula_vexillorum.h.

PRAET_REGION_MASK

#define PRAET_REGION_MASK

The bits the region descriptor occupies once shifted into place.

Definition at line 232 of file praet_tabula_vexillorum.h.

PRAET_REGION_FIELD

#define PRAET_REGION_FIELD

(

region_

)

A region descriptor placed in the field the map gives it.

Parameters

[in]

region_

Region descriptor, narrowed to what the field holds.

Returns

region_ in position, and never a bit outside PRAET_REGION_MASK.

Note

The one way to write the field. Narrowing at the write site instead would put the field's width in two places, and the copy that stops matching is the single one nothing checks.

Definition at line 242 of file praet_tabula_vexillorum.h.

PRAET_REGION_ID_HIGHEST

#define PRAET_REGION_ID_HIGHEST

The largest region token id there is.

Note

Raise this when a region is added, and the assertion below fails until the field is wide enough to hold it.

Definition at line 269 of file praet_tabula_vexillorum.h.

PRAET_MAP_MASK

#define PRAET_MAP_MASK

Every bit the map accounts for.

Note

What a flag word is allowed to carry. A build whose writes stay inside this cannot produce a word with a bit nobody named, and so nothing has to look at a word at run time to find that out.

Definition at line 278 of file praet_tabula_vexillorum.h.

Enumeration Type Documentation

PraetRegion

enum PraetRegion

The regions a channel can be attached over.

Note

Token ids, the same way the statuses above are token ids. A region arrives at an attach as one of these names. A mistyped one is an undeclared identifier carrying the name that was written, and a caller cannot pass a byte that means nothing.

Two of them, because ParsMemoriaeInternae and ParsMemoriaeExternum are the two declarations a pool can be written with. A part with more address spaces than that adds ids here and the assertion below keeps them inside the field.

The values are ordinals. A build wanting a descriptor it can infer an address space from replaces the numbers and changes nothing else, because the field is a byte and everything reading it goes through PRAET_REGION_FIELD.

Definition at line 257 of file praet_tabula_vexillorum.h.