ADR-0021: EnsureInitialized() is the one start-up entry point¶
- Status: Accepted
- Date: 2026-11-07
- Amends: ADR-0002 (the driver and handler parts)
Context¶
ADR-0002 gave drivers two public ways to start: Initialize(config) and EnsureInitialized(). Moving the first
drivers showed what that costs:
Initialize()can be called again on a running chip. It then resets and reconfigures it, for no reason and in the middle of operation, and nothing in the API discourages it.- Two entry points with different behaviour on the second call are two contracts to test, document and review in every driver and every handler.
- Handlers will be singletons that own hardware and are used from several tasks. They need exactly one idempotent start, with no way to start twice.
The handler standard also allowed a handler method to start the chip itself on first use. That hides start-up traffic (for the AS5047U, 42 SPI frames including writes) inside whatever call comes first, possibly a read in a control loop, and turns a start-up failure into the error of a read.
Decision¶
Drivers¶
- The constructor takes the port, any bus argument, and the configuration last with a default:
explicit Chip(Port& port, ..., const Config& config = {}) noexcept. It stores them, does no I/O and cannot fail. EnsureInitialized()is the only public way to start. Its first call validates the stored configuration (InvalidArgument, no I/O), brings the port up, resets and identifies the chip and applies the configuration, and only then marks the driver initialised. Once it has succeeded, later calls returnOkat once with no I/O. After a failure the driver stays uninitialised and the next call starts again from the beginning.- The start-up sequence itself is a private member (
initialize()). There is no publicInitialize(). Deinitialize()puts the chip in its safe state and marks the driver uninitialised. Recovery after a fault isDeinitialize()thenEnsureInitialized().ApplyConfig(config)validates first. On a running driver it writes the configuration; before the start it only stores it for the firstEnsureInitialized(), with no I/O.- No read or write starts the chip. Before
EnsureInitialized()has succeeded, every call that needs the chip returnsNotInitializedand sends nothing. A read is always the bus traffic it needs and nothing more.
Handlers¶
EnsureInitialized()is the handler's one start-up entry point too: it builds the driver in place and calls the driver'sEnsureInitialized(), and on failure destroys it again so the next call retries.- Handler reads and writes do not call
EnsureInitialized(). They returnNotInitializeduntil the handler has been started. The HAL starts its handlers once, in its fixed start-up order (ADR-0002), and a task that uses a handler before then getsNotInitialized, not a hidden start.
Consequences¶
- One lifecycle contract per layer: construct,
EnsureInitialized(), use, optionallyDeinitialize(). - Calling
EnsureInitialized()before every use is cheap and safe, so code that is unsure whether the chip has started can call it; but the start-up cost is always paid at a call that says it starts something. - Timing of a read is deterministic: it never includes a reset or a configuration write.
- Breaking for code written against ADR-0002:
driver.Initialize(config)becomesChip driver(port, config);thendriver.EnsureInitialized(), and a restart with a new configuration becomesDeinitialize(),ApplyConfig(),EnsureInitialized(). The template and the first two migrated drivers (AS5047U, PCAL9555A) change with this ADR; the HardFOC drivers are migrated onto it.
Alternatives considered¶
- Every read starts the chip on first use. Rejected: start-up traffic and start-up errors inside a read, and a failing chip retried at every read.
- Keep a public
Initialize()for re-configuration. Rejected:ApplyConfig()already changes a running configuration, and a full restart isDeinitialize()thenEnsureInitialized(), so a second entry point adds nothing but a way to restart by accident.