Every knob this module reads, what it takes when the caller did not set it, and the warning that says so.
More...
Go to the source code of this file.
Every knob this module reads, what it takes when the caller did not set it, and the warning that says so.
- Author
- dstroy0 (Douglas Quigg) dquig.nosp@m.g123.nosp@m.@gmai.nosp@m.l.co.nosp@m.m
- Date
- 2026-09-01
- Note
- A knob that quietly takes a default is how a build breaks in a way nobody traces back. Three knobs get set, two do not, the part misbehaves, and the compiler said nothing.
-
Nothing here stops the build. Every unset knob takes its default, raises a warning naming itself and the value it took, and leaves a flag behind. praet_iudex.h reads those flags at the end and stops once, listing what to go fix.
-
That order is essential. An #error halts its translation unit where it stands. A build missing four knobs reports one, gets fixed, and reports the next - four rounds to learn four facts that were all known on the first. Warning here and stopping at the end hands the whole basket over at once.
-
Nothing about it needs a build system. It is preprocessor directives. A bare gcc or clang on one file behaves the same way as any tree that drives them. A keep-going build reaches across translation units on top of this, which is a separate half of the same idea and not something this depends on.
-
#warning is a GNU and clang directive and is standard from C23. This library targets those two compilers and no others, and so it is available everywhere this builds.
-
Every message is a #warning directive, with no macro over _Pragma. GCC's warning pragma keeps only the first string literal after it. A message written as adjacent literals arrives cut off at the first one - which still reads as a finished sentence and still passes a check written against its opening words. That got past a green sweep column here once. A #warning takes the rest of the line and arrives whole.
- Warning
- A directive cannot come out of a macro expansion, and so this only works where the report sits at file scope. Every knob here does. The one report that fires from inside a macro is the boundary word answer at a declaration, and praet_ordo.h reaches that a different way.
-
No message interpolates a macro. Neither #warning nor the pragma expands one. A name in the middle of a message arrives as the name of the macro, and its value never appears.
Definition in file praet_praefinitum.h.
◆ PRAET_CHANNELS
Logical channels one context carries.
- Note
- Per part, and the caller is the single one who knows which part. There is no number here that is right for everyone.
Definition at line 50 of file praet_praefinitum.h.
◆ PRAET_UNSET_CHANNELS
| #define PRAET_UNSET_CHANNELS |
◆ PRAET_SETTLE_MICROS
| #define PRAET_SETTLE_MICROS |
Microseconds the engine spends settling before it will take a transfer.
- Note
- Microseconds and not milliseconds. DMA timing is tight enough that a millisecond is not a unit anything here can be expressed in.
- Warning
- At EMBED_WORD_BITS=16 a microsecond count wraps at 65535, about 65 milliseconds. No engine takes that long to come up, and so this knob is safe at every width.
Definition at line 65 of file praet_praefinitum.h.
◆ PRAET_UNSET_SETTLE_MICROS
| #define PRAET_UNSET_SETTLE_MICROS |
◆ PRAET_KEEPALIVE_MICROS
| #define PRAET_KEEPALIVE_MICROS |
Microseconds a running channel may go without the port kicking it before it reads stalled.
- Note
- A watchdog window and not a transfer length. The port kicks this whenever the engine shows a sign of life, and a window that goes unkicked says the channel stopped moving - it never says the transfer finished. Completion arrives from the port, because how long a transfer takes is not something this library can know.
-
That is also why the width is not a problem. A watchdog window is short deliberately, and so the 65 millisecond ceiling a 16-bit word puts on a microsecond count is far above any value worth setting here, while a transfer's runtime has no bound at all.
Definition at line 83 of file praet_praefinitum.h.
◆ PRAET_UNSET_KEEPALIVE_MICROS
| #define PRAET_UNSET_KEEPALIVE_MICROS |
◆ PRAET_RECOVERY
Whether a stalled transfer can be backed out or scrubbed.
- Note
- The capability switch. Off is what a caller gets by not answering, because recovery costs three arrays per channel and a caller who never said where the bytes were cannot back anything out of them.
-
With it on, submit takes the start and the length, kick reports how far the engine got, and praet_ordo_resolve exists. With it off none of those members are in the context and none of those entries are declared. A call site that wanted them fails to compile instead of linking against a version that records nothing.
Definition at line 101 of file praet_praefinitum.h.
◆ PRAET_UNSET_RECOVERY
| #define PRAET_UNSET_RECOVERY |
