Contract¶
What the ADS9324 driver promises, what it needs, and the rules a caller follows.
Datasheet sections this page relies on
From Texas Instruments SBASB22 -:
- Electrical characteristics, power-up and reset times: 5.5 Electrical Characteristics, p. 7
- Timing diagrams, DRDY and the data frame: 5.8 Timing Diagrams, p. 12
- ADC gain and offset error calibration: 7.3.10 ADC Gain and Offset Error Calibration, p. 32
- Diagnostic byte and the randomizer: 7.3.14.3 Diagnostic Flags; 7.3.14.4 ADC Output Data Randomizer, p. 44
- Normal operation and standby: 7.4.2 Normal Operation; 7.4.3 Standby Mode, p. 49
All of them, with the driver API for each: Datasheet map.
The driver inherits the Kokeb Labs driver contract; this page states only what is specific to it. A change to anything here is a breaking change, listed under Breaking in the changelog.
Promises¶
- The constructor is
noexcept, stores the configuration, does no I/O and cannot fail. EnsureInitialized()is the only way to start the driver. Its first call checks the stored configuration (InvalidArgumentorUnsupported, nothing sent), brings the bus up, waits the power-up time, resets the chip (RESET whenConfig::hardware_resetis set, otherwise SW_RST), checks DEVICE_ID and BANK_SEL, waits for the calibration flag to clear and only then writes the configuration. On any failure the driver stays uninitialised and the next call starts again from the beginning; once it has succeeded, later calls returnOkwith no I/O.- Every call that touches the chip returns
Error::NotInitializedbeforeEnsureInitialized()succeeds. No call initialises or resets the chip as a side effect.ApplyConfig()before the start only stores the configuration. - Every port failure propagates as
Error::Bus; no getter returns a stale or zero value after a failed read. - A setter changes the stored configuration only after the chip accepted every write; after a failure the driver
keeps the old configuration. The driver's shadow of the registers equals the chip after every setter that
returns
Ok. - A setter writes only the registers that change, in the order the chip needs: the window thresholds before the window is enabled, and a SYSREF pulse after a filter change.
- Every wait is bounded: the power-up and reset waits are constants, the DRDY wait by
Sampling::ready_timeout_us, the ADC calibration by 125 ms plus 25 ms. - A frame that cannot be a conversion (all bytes
0x00or all0xFF, which is what a stuck or floating SDOUT reads) isDataMismatch, not data.Sampling::reject_stuck_framesturns this off for a test pattern. - A DIAG byte that reports a reset makes the driver uninitialised and returns
UnexpectedReset: the configuration is gone, and the nextEnsureInitialized()writes it again. The DIAG byte is off inConfig{}, so every configuration call (ApplyConfig()and the setters,ClearWindowFlags(),ReadWindowFlags(), the calibration calls,RunDataPathSelfTest(),PowerDown()) first re-sends BANK_SEL, reads DEVICE_ID and DIAG_CTRL, and returnsUnexpectedResetwith nothing else written when RESET_DETECT_FLAG is set. A reset between two frames that no such call has looked at is seen only by the next data frame with the DIAG byte, the next configuration call orWake(). - A register reply is data only when its last byte (SDOUT[7:0]) is
0x00; any other tail isBus. A stuck-low line reads as zeros and passes that check, so every status read that would accept "idle" or "no reset" (IsCalibrationBusy(), the end of a calibration wait,Wake(), the reset probe) also reads DEVICE_ID and returnsBuswhen it is not0x0004. - After a configuration call fails part-way the layout registers (lanes, word length, channel selection) are
unknown:
ReadFrame()andMeasureOnce()returnRefuseduntil a configuration call succeeds. MeasureOnce()sends as many CONVST pulses as one result needs (PulsesPerResult(): the FIR decimation, or the block-average length with the external clock) and waitsConversionTimeUs(), the datasheet's(N - 1) x tCYC + 1.25 us.Convert()leaves CONVST high, as Figure 5-7 requires for the internal oversampling clock.Config{}is the datasheet's initialisation example (Table 7-18), which reads all 16 channels as 16-bit words on SDOUT;ChipResetConfig()is the chip's own reset state (eight lanes on D7 to D0).- A missing
DelayUs()is a compile error; a missingGpioSet()givesError::Unsupportedfrom the calls that need CONVST or RESET; a missingGpioGet()makes the timed wait the only ready source; a missingLog()logs nothing. A misdeclared hook is a compile error. Deinitialize()puts the chip in standby, its lowest-current state, even if that write failed.
Depends on¶
| Dependency | Version | Why |
|---|---|---|
| A C++20 compiler | GCC 10, Clang 13 or later | Concepts constrain the port |
| CMake | 3.16 or later | Generates ads9324_version.h |
| Your port | The bus, within the bus requirements; the delay; optionally CONVST, RESET and DRDY, each at its idle level before the first transfer; lane capture for 2, 4 or 8 lanes; and logging (Porting) |
Nothing else: no RTOS, no SDK, no other repository of the org.
Threading¶
The driver is not thread-safe and takes no lock. Use each driver object from one task at a time, or guard every call on it with one mutex; the layer that owns the driver owns that lock, and the bus lock when several chips share a bus. Nothing may run in an ISR: every call can block for a bus transfer or a delay. Separate objects share no state.
Errors¶
ads9324::Error inside ads9324::Result<T>. Values 0 to 9 are the shared base set; chip-specific values start at
16. Every value is returned by some call, except the three the chip cannot produce, which a test asserts are never
returned.
Error |
Value | Returned when |
|---|---|---|
Ok |
0 | The call succeeded |
NotInitialized |
1 | EnsureInitialized() has not succeeded, or Deinitialize() ran since |
InvalidArgument |
2 | A Config field or argument is out of range (Validate()); nothing was sent |
Bus |
3 | A port hook returned false |
Timeout |
4 | The calibration flag, the DRDY pin or a reset did not finish in time |
DeviceIdMismatch |
5 | DEVICE_ID is not 0x0004 after a reset |
Crc |
6 | Never returned: the chip has no CRC on this interface |
Busy |
7 | Never returned: the chip has no busy reply |
DeviceFault |
8 | Never returned: the chip has no fault flag; kept for the shared set |
Unsupported |
9 | A port hook the call needs is absent, or the daisy chain was requested |
UnexpectedReset |
16 | The DIAG byte or RESET_DETECT_FLAG reports a reset: the chip lost its configuration. The driver is uninitialised afterwards |
VerifyFailed |
17 | A read-back (Verify::ReadBack) or the register check after standby differs from what was written |
Refused |
18 | The call is not allowed in this state (standby, or a calibration with a digital filter on); nothing was sent |
DataMismatch |
19 | A frame is all zeros or all ones, or the data-path self-test read another channel's value |
The API guide says what to do about each.
Memory¶
No heap, no exceptions, no RTTI, no std::function, no std::string, no printf, no floating point and no
static mutable state. A driver object holds a reference to the port, a Config (340 bytes) and a shadow of the
116 registers: 792 bytes in all. The largest stack buffers are two arrays of 50 bytes (the longest data frame).
Platform¶
Platform-free: the same code runs on any target with a C++20 compiler, including the host tests. The ESP-IDF port
in examples/esp32 is an example, not part of the driver.
Deviations from the standard¶
None.