Skip to content

Porting

Run the driver on a new MCU by writing one class: the port.

Datasheet sections this page relies on

From Texas Instruments SBASB22 -:

  • Pins, package and the data lanes: 4 Pin Configuration and Functions, p. 3
  • SPI and CONVST timing: 5.6 Timing Requirements; 5.7 Switching Characteristics, p. 11
  • Timing diagrams, DRDY and the data frame: 5.8 Timing Diagrams, p. 12
  • Data interface: lanes, word length and channel modes: 7.3.14 Data Interface; 7.3.14.1 ADC Channel Modes, Table 7-12, p. 42
  • Output drive strength and output delay: 7.3.14.6 Digital Output Drive Strength Control; 7.3.14.7 Digital Output Delay Adjustment, p. 48
  • Register write and read frames: 7.5 Programming; 7.5.1 Register Write Operation; 7.5.2 Register Read Operation, p. 50

All of them, with the driver API for each: Datasheet map.

The driver never calls your SDK. It calls hooks on a class you derive from ads9324::SpiInterface<Self> (in inc/ads9324_spi_interface.hpp). The base uses CRTP and declares no hook itself; the driver template is constrained by the ads9324::SpiPort concept, so calls are resolved at compile time (no virtual functions, nothing to allocate) and a missing or misdeclared hook is a compile error at the point of use.

What you implement

Method Required Contract
bool EnsureInitialized() noexcept yes Bring the bus up on the first call; return true at once afterwards. false makes the driver's EnsureInitialized() return Bus
bool Transfer(const uint8_t* tx, uint8_t* rx, std::size_t len) noexcept yes One full-duplex frame of len bytes with CS low for all of them. rx is nullptr for writes. false on any bus error
void DelayUs(uint32_t us) noexcept yes Wait at least us microseconds
bool GpioSet(CtrlPin, GpioSignal) noexcept no Drive RESET and CONVST; false if the pin write failed or the pin is not wired
bool GpioGet(CtrlPin, bool& high) noexcept no Read DRDY/ALARM; set high to the raw level
bool CaptureLanes(uint8_t lanes, uint8_t* rx, std::size_t len) noexcept no Clock a data frame in on 2, 4 or 8 lanes (or 1 lane on D7)
void Log(LogLevel, const char* message) noexcept no Print one line; message is plain text, never a format string

The port

my_port.hpp
class MyPort : public ads9324::SpiInterface<MyPort> {
public:
  // Bring the bus up once; later calls return true at once.
  bool EnsureInitialized() noexcept {
    if (!ready_) {
      ready_ = platform_spi_init();
    }
    return ready_;
  }

  // One frame, CS held low for all `len` bytes (3 for a register, up to 50 for
  // the data). `rx` is nullptr for writes.
  bool Transfer(const uint8_t* tx, uint8_t* rx, std::size_t len) noexcept {
    return platform_spi_transfer(tx, rx, len);
  }

  // Wait at least `us` microseconds: the power-up and reset times depend on it.
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

Rules the transfer must follow:

  • One call, one frame. Keep CS low for all len bytes; the chip decodes the frame when CS rises. A register frame is 3 bytes; a data frame is up to 50 bytes (kMaxFrameBytes). Never split a frame into several transfers.
  • Buffers. The driver owns the transmit and receive buffers (members of the driver object, no heap, never on the caller's stack), so a DMA that reads them reaches them; a port that needs DMA-capable memory places the driver object there.
  • The bus requirements below: mode 0, MSB first, up to kMaxSdoutClockHz when the port reads SDOUT (kMaxClockHz for writes only). Start at 1 MHz on jumper wires.
  • Raw bytes only. Do not interpret, retry or reorder bytes; the driver owns the framing.
  • Return false for a bus error. The driver turns it into Error::Bus and never ignores it.
  • Bounded time-outs. A stuck bus fails the call; it does not block forever.
  • A transmit buffer of zeros while reading data. The driver sends zeros during a data frame so that no register is written by accident; do not replace them.

Bus requirements

The driver states what the ADS9324 needs from the bus as constexpr values in inc/ads9324_spi_interface.hpp (handbook KB-CPP-123). Check your port's settings against them with static_assert, as the ESP32 example port does, so a port that clocks too fast or in the wrong mode does not compile:

Constant Value Meaning (datasheet 5.6)
kSpiMode 0 CPOL 0, CPHA 0 (derived from the timing diagram: the datasheet names no mode)
kMsbFirst true Most significant bit first
kMaxClockHz 60'000'000 f_SCLK max (section 5.6), for writes
kMaxSdoutClockHz 29'000'000 f_SCLK max when the port reads SDOUT in mode 0: the 17 ns td_CKDO must fit half a period (A2)
kMinCsHighNs 16 CS high between two frames, thi_CS
kContinuousWord false SCLK may pause inside a frame; only CS framing matters
kCsSetupNs, kCsHoldNs 16, 16 CS low to the first SCLK edge, last SCLK edge to CS high
kFrameIsAtomic true CS stays low for a whole frame; the chip decodes it when CS rises
kFrameBits 24 A register frame: 8 address bits and 16 data bits

Control pins

Each control pin has a defined idle level, and the port drives it there before it enables the pin's output and before the driver's first transfer (handbook KB-HW-018). Configuring a pin as an output first and setting its level afterwards gives the chip a pulse it did not ask for, for example a reset or a conversion.

CtrlPin Package pin Polarity Idle level Before the first transfer
Reset RESET active low high (INACTIVE) Set high, then enable the output
Convst CONVST the falling edge samples; ACTIVE is high high (ACTIVE) Set high, then enable the output: the driver leaves CONVST high after each pulse
DrdyAlarm DRDY/ALARM active high, an input Configure as an input

GpioSignal::ACTIVE always means "function asserted"; the port maps it to the electrical level. A pin tied on the board needs no hook. Convert() is one CONVST pulse: ACTIVE, then INACTIVE (the falling edge samples), then ACTIVE again, so CONVST is high before DRDY rises (Figure 5-7).

Optional hooks

The driver finds the optional hooks at compile time with named concepts, in one place (ads9324::detail). A missing hook falls back in a documented, safe way or the call returns Error::Unsupported; it never skips a step silently, and a hook declared with the wrong signature does not compile.

Hook Used for Without it
DelayUs() The power-up and reset times, the timed ready wait, calibration polling Compile error (every port needs it)
GpioSet() RESET (Config::hardware_reset, Reset(Hardware)) and CONVST (Convert(), MeasureOnce(), the SYSREF pulse after a filter change, single-shot calibration) Unsupported from those calls; drive CONVST yourself and use ReadFrame()
GpioGet() The DRDY pin wait (Sampling::ready = ReadySource::Pin) and ReadAlarmPin() The timed wait; ReadAlarmPin() returns Unsupported
CaptureLanes() A data frame on 2, 4 or 8 lanes ReadFrame() returns Unsupported for those lanes; one lane on SDOUT needs no hook
Log() One line per lifecycle event or failure Nothing is logged

CaptureLanes(lanes, rx, len) clocks len bytes of the frame and packs the bits most significant first, so that every lane count returns the byte stream the 1-lane SDOUT mode would (lanes is 1, 2, 4 or 8). With 8 lanes each clock yields one byte with D7 as the most significant bit; with 4 lanes two clocks yield a byte (D7 to D4, the high nibble first); with 2 lanes four clocks (D7 and D6 first). This packing follows the data-interface figures of section 7.3.14 and is not verified on hardware; the host tests check it only against the chip model.

A port with every hook:

class FullPort : public ads9324::SpiInterface<FullPort> {
public:
  bool EnsureInitialized() noexcept {
    return platform_spi_init();
  }
  bool Transfer(const uint8_t* tx, uint8_t* rx, std::size_t len) noexcept {
    return platform_spi_transfer(tx, rx, len);
  }

  // Required by every call that waits (power-up, reset, conversions,
  // calibration).
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

  // Optional: RESET and CONVST on GPIOs. ACTIVE means "asserted": RESET is
  // active low on the pin, so ACTIVE is a low level there; CONVST is a high
  // pulse, so ACTIVE is a high level.
  bool GpioSet(ads9324::CtrlPin pin, ads9324::GpioSignal signal) noexcept {
    const bool active = signal == ads9324::GpioSignal::ACTIVE;
    switch (pin) {
    case ads9324::CtrlPin::Reset:
      return platform_gpio_write(kResetGpio, !active);
    case ads9324::CtrlPin::Convst:
      return platform_gpio_write(kConvstGpio, active);
    default:
      return false;
    }
  }

  // Optional: the DRDY/ALARM pin as an input. Report the raw level; the driver
  // applies the polarity.
  bool GpioGet(ads9324::CtrlPin pin, bool& high) noexcept {
    if (pin != ads9324::CtrlPin::DrdyAlarm) {
      return false;
    }
    high = platform_gpio_read(kDrdyGpio);
    return true;
  }

  // Optional: only for 2, 4 or 8 data lanes. Clock the lanes for `len` bytes of
  // the frame and pack the bits as the Porting page describes.
  bool CaptureLanes(uint8_t lanes, uint8_t* rx, std::size_t len) noexcept {
    return platform_lanes_capture(lanes, rx, len);
  }

  // Optional: one line per lifecycle event or failure. The driver never
  // formats; the port does.
  void Log(ads9324::LogLevel level, const char* message) noexcept {
    if (level > ads9324::LogLevel::Warning) {
      return;
    }
    platform_log(message); // plain text: never use it as a format string
  }

private:
  static constexpr int kResetGpio = 11;
  static constexpr int kConvstGpio = 4;
  static constexpr int kDrdyGpio = 5;
};
ads9324::Error RecoverWithResetPin(ads9324::ADS9324<FullPort>& adc) {
  // With GpioSet() this pulses RESET and writes the stored configuration again;
  // a port without it gets Error::Unsupported.
  return adc.Reset(ads9324::ResetKind::Hardware).error;
}

A GpioSet() that returns void, a GpioGet() that returns void, a CaptureLanes() with a narrowed parameter or a Log() that returns int is a compile error: the driver must see a failed pin write. The compile-fail tests check each rule.

Reference implementations

Every port lives with its example, in examples/<platform>/; the driver has none. Platforms lists them and how to add one.

Check your port

  1. Build it: the ports on this page are compiled by the host CI from tests/docs/, with the driver instantiated over them.
  2. Call EnsureInitialized(): Ok proves that writes and reads work and that DEVICE_ID read 0x0004.
  3. Call RunDataPathSelfTest(): every channel returns its own test pattern, which proves the data lanes, the word format and the channel-to-register mapping of both banks on your wiring.

Threads

The driver is not thread-safe. Give each driver object one owner task, or guard every call with one mutex. When several chips share a bus, the port must also serialise the bus. See Contract.

Editor setup

The clang-format and clang-tidy configuration is in _config/, and the repository root has no copy of it. Tools that take a path use it directly; CI does the same:

Tool Setting
Command line clang-format --style=file:_config/.clang-format, clang-tidy --config-file=_config/.clang-tidy -p build
VS Code (C/C++ extension) "C_Cpp.clang_format_style": "file:${workspaceFolder}/_config/.clang-format" and "C_Cpp.codeAnalysis.clangTidy.args": ["--config-file=${workspaceFolder}/_config/.clang-tidy"]
clangd (VS Code clangd, Neovim, Emacs), CLion These find .clang-format and .clang-tidy only by name, from the file upwards: copy both to the root once (cp _config/.clang-format _config/.clang-tidy .). .gitignore lists the copies, so they never reach a commit; copy again after _config/ changes

Configure with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON (clangd: --compile-commands-dir=build) so the editor sees the same flags as the build.