ADS9324 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Namespaces | Classes | Concepts | Enumerations | Functions | Variables
ads9324 Namespace Reference

The ADS9324 driver: everything it declares lives here; internals in detail. More...

Namespaces

namespace  reg
 The ADS9324 register map.
 

Classes

class  ADS9324
 Driver for one ADS9324 on a platform port. More...
 
struct  Alarm
 The DRDY/ALARM pin (DRDY_ALARM_SEL, GEN_CFG4). More...
 
struct  Calibration
 Calibration at start-up and the mode RunAdcCalibration() uses. More...
 
struct  ChannelSelect
 Which channels the data frame carries (ANA_CFG2). More...
 
class  CheckedConfig
 A configuration proven valid when the program is built. An invalid one does not compile. More...
 
struct  Config
 Everything EnsureInitialized() and ApplyConfig() write to the chip. More...
 
struct  Correction
 System offset and gain correction stages (GEN_CFG5 of the channel banks). More...
 
struct  DaisyChain
 Daisy chain settings: out of scope in this version, Validate() refuses enabled. More...
 
struct  Filter
 The digital filter in the data path (DIG_FILTER, GEN_CFG5). More...
 
struct  Frame
 One decoded data frame. More...
 
struct  Input
 The configuration of one input channel. More...
 
struct  Interface
 The data interface (GEN_CFG3, XOR_BITS_CTL, GEN_CFG4, DIG_DELAY_CFG1/2). More...
 
struct  Result
 The value of a call, or why there is none. More...
 
struct  Result< void >
 The result of a call that returns no value. More...
 
struct  Sampling
 CONVST timing and the ready wait (section 5.6). More...
 
class  SpiInterface
 CRTP base of the platform port. More...
 
struct  Supply
 Supplies in millivolts for the range checks; 0 means "not stated". More...
 
struct  TestPattern
 A test pattern of one channel group (TP_CFG, TP_AIN). More...
 
struct  Window
 The digital window comparator of one channel (section 7.3.12). More...
 
struct  WindowFlags
 The latched digital window comparator flags, one bit per channel (bit 0 is AIN1). More...
 

Concepts

concept  SpiPort
 Satisfied by a class that derives from SpiInterface<Port> and implements the required hooks with exactly the types above, noexcept and returning bool.
 

Enumerations

enum class  CtrlPin : uint8_t { Reset = 0 , Convst = 1 , DrdyAlarm = 2 }
 Control pins the port may drive or read through the optional hooks. More...
 
enum class  GpioSignal : uint8_t { INACTIVE = 0 , ACTIVE = 1 }
 Logical level of a control pin; the port maps it to the physical polarity. More...
 
enum class  Error : uint8_t {
  Error::Ok = 0 , Error::NotInitialized = 1 , Error::InvalidArgument = 2 , Error::Bus = 3 ,
  Error::Timeout = 4 , Error::DeviceIdMismatch = 5 , Error::Crc = 6 , Error::Busy = 7 ,
  Error::DeviceFault = 8 , Error::Unsupported = 9 , Error::UnexpectedReset = 16 , Error::VerifyFailed = 17 ,
  Error::Refused = 18 , Error::DataMismatch = 19
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  LogLevel : uint8_t { LogLevel::Error = 0 , LogLevel::Warning , LogLevel::Info , LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  Verify : uint8_t { Verify::None = 0 , Verify::ReadBack = 1 }
 Whether a setter reads back what it wrote (costs one two-frame read per register). More...
 
enum class  ResetKind : uint8_t { ResetKind::Software = 0 , ResetKind::Hardware = 1 }
 How Reset() resets the chip. More...
 
enum class  InputType : uint8_t { InputType::Differential = 0 , InputType::SingleEnded = 5 , InputType::SingleEndedOpenWireSafe = 6 }
 Input type of a channel (CM_RANGE_AINn, Table 7-1). More...
 
enum class  InputRange : uint8_t {
  InputRange::V5 = 0 , InputRange::V2_5 = 2 , InputRange::V6_25 = 3 , InputRange::V10 = 4 ,
  InputRange::V12_5 = 5
}
 Input range of a channel (INPUT_RANGE_AINn, Table 7-1). More...
 
enum class  Bandwidth : uint8_t { Bandwidth::Low = 0 , Bandwidth::Wide = 1 }
 Analog low-pass filter of a channel (PGA_BW_SEL_AINn, Table 7-2). More...
 
enum class  Lanes : uint8_t { Lanes::Eight = 0 , Lanes::Four = 1 , Lanes::Two = 2 , Lanes::One = 3 }
 Number of data lanes (DOUT_LANE_SEL, Table 7-11). More...
 
enum class  WordLength : uint8_t { WordLength::Bits16 = 0 , WordLength::Bits24 = 2 }
 Bits per conversion result on the data interface (DOUT_LENGTH). More...
 
enum class  DataFormat : uint8_t { DataFormat::TwosComplement = 0 , DataFormat::OffsetBinary = 1 }
 Coding of the conversion result (EN_OFS_BINARY). More...
 
enum class  DriveStrength : uint8_t { DriveStrength::Normal = 0 , DriveStrength::Half = 1 , DriveStrength::Double = 2 , DriveStrength::OneAndHalf = 3 }
 Drive strength of the digital outputs (DRIVE_STRENGTH, Table 7-15). More...
 
enum class  ReferenceSource : uint8_t { ReferenceSource::Pin = 0 , ReferenceSource::Internal = 1 , ReferenceSource::External = 2 }
 Where the ADC reference comes from (Table 7-3). More...
 
enum class  ChannelCount : uint8_t { ChannelCount::All16 = 0 , ChannelCount::Eight = 1 , ChannelCount::Four = 2 , ChannelCount::Two = 3 }
 How many channels the data frame carries (ADC_NUM_SEL, Table 7-12). More...
 
enum class  AlarmFunction : uint8_t { AlarmFunction::Drdy = 0 , AlarmFunction::WindowAlert = 1 , AlarmFunction::CalDone = 6 , AlarmFunction::OrMasked = 8 }
 What the DRDY/ALARM pin shows (DRDY_ALRM_SEL, Table 7-10). More...
 
enum class  AverageLength : uint8_t {
  None = 0 , X2 , X4 , X6 ,
  X8 , X10 , X12 , X16 ,
  X20 , X32 , X64 , X128
}
 Length of a block or moving average (BLK_AVG_OSR, MVG_AVG_LEN).
 
enum class  FirFilter : uint8_t {
  FirFilter::Fir1 = 1 , FirFilter::Fir2 = 2 , FirFilter::Fir3 = 3 , FirFilter::Fir4 = 4 ,
  FirFilter::Fir5 = 5 , FirFilter::Fir7 = 7
}
 The FIR low-pass filters (FIR_FILT_SEL, Table 7-9). FIR6 is reserved and absent. More...
 
enum class  FilterKind : uint8_t { FilterKind::None = 0 , FilterKind::BlockAverage = 1 , FilterKind::MovingAverage = 2 , FilterKind::Fir = 3 }
 Which one digital filter is in the data path (section 7.3.11). More...
 
enum class  PatternKind : uint8_t { PatternKind::Constant = 0 , PatternKind::Ramp = 2 }
 Kind of a test pattern (TP_MODE, Table 7-14). More...
 
enum class  ReadySource : uint8_t { ReadySource::Time = 0 , ReadySource::Pin = 1 }
 How WaitDataReady() learns that a result is ready. More...
 
enum class  CalibrationMode : uint8_t { CalibrationMode::Offset = 1 , CalibrationMode::Gain = 2 , CalibrationMode::OffsetAndGain = 3 }
 Which errors ADC_CAL removes (ADC_CAL_MODE). More...
 
enum class  CalibrationTrigger : uint8_t { CalibrationTrigger::SingleShot = 0 , CalibrationTrigger::Continuous = 1 }
 How the CONVST clock behaves during ADC calibration (section 7.3.10). More...
 

Functions

constexpr Config KconfigDefaults () noexcept
 The configuration menuconfig selected, on top of the Config{} defaults.
 
constexpr const char * ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr bool IsValid (InputType v) noexcept
 Whether an input type holds a documented code.
 
constexpr bool IsValid (InputRange v) noexcept
 Whether an input range holds a documented code.
 
constexpr bool IsValid (WordLength v) noexcept
 Whether a word length holds a documented code (01b is reserved).
 
constexpr bool IsValid (AlarmFunction v) noexcept
 Whether an alarm function holds a documented code.
 
constexpr bool IsValid (FirFilter v) noexcept
 Whether a FIR filter holds a documented code (110b is reserved).
 
constexpr bool IsValid (PatternKind v) noexcept
 Whether a test pattern kind holds a documented code (only 0 and 2 are reachable).
 
constexpr bool IsValid (CalibrationMode v) noexcept
 Whether a calibration mode holds a documented code.
 
constexpr std::array< Input, 16 > DefaultInputs () noexcept
 The default settings of the 16 inputs, spelled out because GCC skips nested member initialisers in inputs{}.
 
constexpr Config ChipResetConfig () noexcept
 The chip's reset state as a Config: eight lanes on D7 to D0, everything else as Config{}.
 
constexpr Error Validate (const Config &c) noexcept
 Check a configuration against the documented ranges and combinations, with no I/O.
 
constexpr int GetDriverVersionMajor () noexcept
 
constexpr int GetDriverVersionMinor () noexcept
 
constexpr int GetDriverVersionPatch () noexcept
 
constexpr const char * GetDriverVersion () noexcept
 
constexpr uint32_t AverageFactor (AverageLength length) noexcept
 The averaging factor of a length code: 1, 2, 4, 6, 8, 10, 12, 16, 20, 32, 64, 128.
 
constexpr uint32_t FirDecimation (FirFilter fir) noexcept
 The decimation of a FIR filter (Table 7-9).
 
constexpr uint32_t ResultsPerOutput (const Filter &filter) noexcept
 Samples that make one result of the digital filter in the data path.
 
constexpr uint32_t PulsesPerResult (const Filter &filter) noexcept
 CONVST falling edges the chip needs for one result.
 
constexpr uint32_t OutputRateHz (const Config &config) noexcept
 Result rate of the data interface in hertz.
 
constexpr uint32_t ConversionTimeUs (const Config &config) noexcept
 Time from the start of a conversion to a ready result, rounded up to microseconds, at least 2.
 
constexpr int16_t OffsetCorrectionFor (int32_t expected_code, int32_t measured_code) noexcept
 The OFS value that removes a measured offset (equation 1, section 7.3.9).
 
constexpr int16_t GainCorrectionFor (int32_t expected_code, int32_t measured_code) noexcept
 The GAN value that removes a measured gain error (equations 2 to 4, section 7.3.9).
 
constexpr int32_t RangeMillivolts (InputRange range) noexcept
 Full-scale voltage of a range in millivolts.
 
constexpr int32_t CodeToMicrovolts (int32_t code, InputRange range) noexcept
 Microvolts of a signed code: code x full scale / 32768, rounded half away from zero.
 
constexpr int16_t ToSigned16 (uint16_t raw) noexcept
 Reinterpret a 16-bit wire value as a signed code (two's complement).
 
constexpr int16_t WireToCode (uint16_t raw, DataFormat format) noexcept
 The signed code of a wire value.
 
constexpr uint16_t DerandomizeMask (uint8_t prbs) noexcept
 The XOR mask of the randomizer (equations 7 and 8, section 7.3.14.4).
 
constexpr uint32_t FrameChannels (const ChannelSelect &select) noexcept
 Number of channels in a frame.
 
constexpr uint8_t FrameSlotChannel (const ChannelSelect &select, uint32_t slot) noexcept
 Which channel a slot of the frame carries (Table 7-12).
 
constexpr bool HasDiagByte (const Interface &interface) noexcept
 Whether the frame ends with a DIAG byte: asked for, or implied by the randomizer (the datasheet shows the PRBS byte only together with the DIAG byte, assumption A14).
 
constexpr std::size_t FrameBytes (const Interface &interface, const ChannelSelect &select) noexcept
 Bytes of one data frame (section 7.3.14).
 
constexpr bool IsStuckFrame (std::span< const uint8_t > bytes) noexcept
 Whether a data frame could come from a stuck or floating line: every byte 0x00 or every byte 0xFF (hardware lessons, KB-CPP-116).
 

Variables

constexpr uint8_t kAlarmSourceDrdy = 0x01
 Sources of the OR output; bit n of Alarm::sources is the source with code n.
 
constexpr uint8_t kAlarmSourceWindow = 0x02
 Source code 1, window alert.
 
constexpr uint8_t kAlarmSourceCalDone = 0x40
 Source code 6, ADC calibration done.
 
constexpr uint16_t kDeviceId = 0x0004
 DEVICE_ID value of every ADS9324.
 
constexpr uint32_t kPowerUpMs = 30
 Power-up wait before the first access, tPU (section 5.7).
 
constexpr uint32_t kResetMs = 30
 Wait after a reset before the first access (tPU, A3).
 
constexpr uint32_t kResetPulseUs = 1000
 Shortest RESET low pulse the driver drives (a design choice, section 7.4.1).
 
constexpr uint32_t kConvstMinHz = 100'000
 Lowest CONVST frequency, fCONVST (section 5.6).
 
constexpr uint32_t kConvstMaxHz = 1'000'000
 Highest CONVST frequency, fCONVST.
 
constexpr uint32_t kConvstHighMinNs = 50
 Shortest CONVST high time.
 
constexpr uint32_t kConvstLowMinNs = 50
 Shortest CONVST low time.
 
constexpr uint32_t kDrdyLowDelayNs = 350
 Delay from the CONVST falling edge to the DRDY falling edge.
 
constexpr uint32_t kConversionNs = 1250
 Conversion time without oversampling, tCONV.
 
constexpr uint32_t kSclkMaxHz = 60'000'000
 Highest SCLK frequency (section 5.6).
 
constexpr uint32_t kSingleShotCalMs = 125
 The single-shot ADC calibration time, TWAIT (Table 7-7).
 
constexpr uint32_t kCalMarginMs = 25
 Extra time the driver polls CALIB_BUSY after the single-shot wait.
 
constexpr uint32_t kContinuousCalConvst = 100'000
 The free-running ADC calibration time in CONVST periods (Table 7-7).
 
constexpr uint32_t kReadyTimeoutMaxUs = 200'000
 Longest Sampling::ready_timeout_us.
 
constexpr uint32_t kInternalVrefMv = 4096
 Internal reference voltage in millivolts (section 5.5).
 
constexpr uint32_t kInputResistanceOhm = 1'000'000
 Input resistance of each AINnP and AINnM pin in ohms (section 7.3.3).
 
constexpr std::size_t kMaxFrameBytes = 50
 Longest data frame in bytes: 16 channels of 24 bits, DIAG and PRBS.
 
constexpr uint8_t kGlitchMax = 15
 Highest DWC glitch filter count (DWC_GLITCH_FILT, 4 bits).
 
constexpr uint8_t kDelayMaxNs = 5
 Largest output delay in nanoseconds (3 bits, section 8.1.10).
 
constexpr int32_t kOffsetMin = -512
 OFS range in quarter LSBs (10 bits, two's complement).
 
constexpr int32_t kOffsetMax = 511
 OFS range in quarter LSBs.
 
constexpr int32_t kGainMin = -8192
 GAN range (14 bits, two's complement).
 
constexpr int32_t kGainMax = 8191
 GAN range.
 
constexpr uint8_t kDiagWindowAlert = 0x40
 DIAG bit 6, DWC_ALERT_FLAG (Table 7-13).
 
constexpr uint8_t kDiagResetDetect = 0x01
 DIAG bit 0, RESET_DETECT_FLAG.
 
Bus requirements

What the ADS9324 needs from the SPI bus (datasheet sections 5.6, 5.7 and 7.5). A port and a board configuration check their settings against these with static_assert (KB-CPP-123).

constexpr uint8_t kSpiMode = 0
 
constexpr bool kMsbFirst = true
 Each byte is clocked most significant bit first.
 
constexpr uint32_t kMaxClockHz = kSclkMaxHz
 Highest SCLK frequency, f_SCLK (section 5.6), for frames that read nothing back.
 
constexpr uint32_t kMaxSdoutClockHz = 29'000'000
 
constexpr uint32_t kMinCsHighNs = 16
 Shortest time CS stays high between two frames, thi_CS (section 5.6).
 
constexpr uint32_t kCsSetupNs = 16
 CS low to the first SCLK edge, tsu_CSCK.
 
constexpr uint32_t kCsHoldNs = 16
 Last SCLK edge to CS high, tht_CSCK.
 
constexpr bool kFrameIsAtomic = true
 
constexpr bool kContinuousWord = false
 
constexpr uint32_t kFrameBits = 24
 Bits in a register frame: 8 address bits and 16 data bits.
 

Detailed Description

The ADS9324 driver: everything it declares lives here; internals in detail.

Enumeration Type Documentation

◆ CtrlPin

enum class ads9324::CtrlPin : uint8_t
strong

Control pins the port may drive or read through the optional hooks.

Enumerator
Reset 

RESET, active low on the package pin; idles high (INACTIVE).

Convst 

CONVST: ACTIVE is a high level, and the line idles high (ACTIVE) between pulses.

DrdyAlarm 

DRDY/ALARM: an input, read with GpioGet().

◆ GpioSignal

enum class ads9324::GpioSignal : uint8_t
strong

Logical level of a control pin; the port maps it to the physical polarity.

Enumerator
INACTIVE 

The pin function is deasserted.

ACTIVE 

The pin function is asserted.

Function Documentation

◆ KconfigDefaults()

constexpr Config ads9324::KconfigDefaults ( )
constexprnoexcept

The configuration menuconfig selected, on top of the Config{} defaults.

Returns
Config{} with the CONVST frequency, word length, DIAG byte, ready source and DRDY timeout taken from Kconfig.

Variable Documentation

◆ kContinuousWord

constexpr bool ads9324::kContinuousWord = false
inlineconstexpr

false: SCLK may pause between bytes of a frame, so a port need not send a whole frame without gaps (the chip decodes on the rising edge of CS, not on a byte count).

◆ kFrameIsAtomic

constexpr bool ads9324::kFrameIsAtomic = true
inlineconstexpr

true: CS stays low for a whole frame; the chip decodes a frame when CS rises (section 7.5).

◆ kMaxSdoutClockHz

constexpr uint32_t ads9324::kMaxSdoutClockHz = 29'000'000
inlineconstexpr

Highest SCLK frequency when SDOUT is read in mode 0: the 17 ns td_CKDO must fit half a period (assumption A2). A port that reads registers or data checks against this one.

◆ kSpiMode

constexpr uint8_t ads9324::kSpiMode = 0
inlineconstexpr

SPI mode the driver is tested with: CPOL 0, CPHA 0. The datasheet names none (assumption A1, derived from the timing diagram: SDI is sampled on the rising edge).