|
ADS9324 Driver 0.1.0
API 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 | |
| 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. | |
The ADS9324 driver: everything it declares lives here; internals in detail.
|
strong |
|
strong |
|
constexprnoexcept |
|
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).
|
inlineconstexpr |
true: CS stays low for a whole frame; the chip decodes a frame when CS rises (section 7.5).
|
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.
|
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).