Architecture¶
How the driver is built: three layers, one of them yours, and what happens in each when you read a channel.
Datasheet sections this page relies on
From Texas Instruments SLAS605 C:
- Frame, reply word, GPIO refresh and alarm timing: 8.1 Overview, p. 28
- Manual mode and the two-frame read latency: 8.4.4 Operating in Manual Mode, Figures 50 and 51, Table 1, p. 31
- Auto-1 mode and its program register: 8.4.5 Operating in Auto-1 Mode, Figures 52 to 54, Tables 2 to 4, p. 34
- The "continue" word: 8.4.7 Continued Operation in a Selected Mode, Table 7, p. 41
All of them, with the driver API for each: Datasheet map.
Figure description and sources
Top to bottom, each arrow is a call. Your application calls one object, whose public calls are listed from the umbrella header in inc/. The core turns each call into register reads and writes and hands them to the port contract (the CRTP base in inc/*_interface.hpp), which forwards them, at compile time, to the hooks of the port class you write; your port moves the bytes on the bus. The notes on the right say which layers stay the same on every MCU and which one you write. A library without a port contract has only the first two layers.
Drawn from: inc/ads7952.hpp public calls; inc/ads7952_spi_interface.hpp SpiInterface; figure module docs/diagrams/figures/driver-layers.py.
Layers¶
| Layer | Files | Owns |
|---|---|---|
| Core | inc/ads7952.hpp, src/ads7952.ipp |
Lifecycle, reset and identity check, the frame pipeline (mode, selected channel, replies in flight), address checks, program sequences and their repair, errors |
| Types and frame format | inc/ads7952_types.hpp, inc/ads7952_registers.hpp |
Error, Result<T>, Variant, Package, Range, Verify, GpioConfig, AlarmThreshold, Bank, Config; the command words and the reply fields |
| Port contract | inc/ads7952_spi_interface.hpp |
The CRTP base, the SpiPort concept, detail::FrameBus (one 16-bit frame per transfer, MSB first) |
| Platform port | Your class | Bus bring-up, transfers and a delay; optionally logging |
| Kconfig layer | inc/ads7952_kconfig.hpp |
Optional: a Config from ESP-IDF menuconfig |
The pipeline the core tracks¶
Figure description and sources
Each column is one 16-bit frame, CS low for 16 SCLK cycles, left to right in time. In each panel the top row is the word the driver sends on SDI, the middle row the channel the multiplexer acquires during that frame, and the bottom row the reply on SDO: the conversion of the channel acquired in the frame before, sampled at this frame's CS falling edge, tagged with its address in DO15:12. In Manual mode (top) ReadChannel(4) selects channel 4 with a Manual word, sends a "continue" word and then the Manual word for channel 4 again (it carries the range once more), and keeps the third reply, whose address must be 4; the two replies before it still belong to the previous channel. In Auto-1 (bottom), entering the mode restarts the sequence at its first channel: with channels 2, 5 and 6 programmed, the first result arrives two frames after the Auto-1 word, and from then on every Auto-1 word without restart (DI11 = 1, the range again) returns the next channel of the sequence, so a pass costs one frame per channel. The timing is the datasheet's Figures 51 and 53; the frame counts come from ReadChannel(), readSelected(), scan() and collect() in src/ads7952.ipp.
Drawn from: src/ads7952.ipp select(); src/ads7952.ipp selectChecked(); src/ads7952.ipp readSelected(); src/ads7952.ipp scan(); inc/ads7952_registers.hpp kContinue; figure module docs/diagrams/figures/frame-pipeline.py.
The chip answers each frame with the result of the channel the frame before last chose (Figures 51 and 53). The core keeps three facts so that each call sends the fewest frames and returns only results that belong to it: the mode the chip is in (Manual, Auto-1, Auto-2, or unknown after a failure), the Manual channel, and how many replies still in flight were acquired before its last change (a select, an Auto entry, a new range or sequence). A read that does not need to choose the channel lets those replies pass; any other read chooses it again, which also sends the range. A reply's address is always checked against the channel it must carry.
One read through the layers¶
sequenceDiagram
participant App as Your code
participant Core as ADS7952<Port>
participant Port as Your port
App->>Core: ReadChannel(4)
Core->>Port: Transfer(0x1A00: Manual, DI11, channel 4)
Port-->>Core: true, reply of an earlier channel
Core->>Port: Transfer(0x0000: continue)
Port-->>Core: true, reply acquired before the select
Core->>Port: Transfer(0x0000: continue)
Port-->>Core: true, 0x4xxx: address 4, the result
Core-->>App: Result<uint16_t>{code, Ok}
App->>Core: ReadChannel(4)
Core->>Port: Transfer(0x0000: continue)
Port-->>Core: true, 0x4xxx
Core-->>App: Result<uint16_t>{code, Ok}
A scan is drawn on the API guide: after the entry, one Auto-1 word (DI11 = 1, no restart) per channel.
Design choices¶
- CRTP, not virtual functions. The port is a template parameter constrained by the
SpiPortconcept, so every call is resolved at compile time and a missing hook is a compile error that names it. - Optional hooks by named concepts.
DelayUsandLogare detected byHasDelayUsandHasLogin one place, which match the hook's address against exactly onenoexceptsignature (detail::ExactHook). A missingDelayUs()fails to compile, and so does a hook declared with another signature; a missingLog()logs nothing. - No I/O in the constructor. Construction cannot fail and clocks nothing, so the driver can be a static or a member of a handler built at boot, before the board is plugged in.
- Key every result on its address. The chip tags each reply with its channel; the driver never infers a channel from frame counting alone. A lost frame, a reset chip or a deaf SDI line becomes an error, not a wrong value.
- Minimum frames, extra checks per call. The hot path sends one mode word per result; the read-backs the chip
allows (GPIO levels, the scanned sequence) are asked for per call with
Verify::ReadBack. - No mode calls. The driver enters Manual, Auto-1 or Auto-2 when a read needs it; the caller never has to keep the chip's mode and the driver's view in step.
- One error type.
Result<T>carries a value and anError; nothing throws and nothing returns a barebool. - No heap, no exceptions, no RTTI, no
std::function, noprintf. The driver is a header-only template with no mutable static state.
Source map¶
| You want | Read |
|---|---|
| The public API | inc/ads7952.hpp |
| How a call is implemented | src/ads7952.ipp |
| Command words and reply fields | inc/ads7952_registers.hpp |
| The port contract and the frame | inc/ads7952_spi_interface.hpp |
Next: Contract.