ADS9324 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
ads9324.hpp
Go to the documentation of this file.
1
17#ifndef ADS9324_HPP
18#define ADS9324_HPP
19
20#include <array>
21#include <cstddef>
22#include <cstdint>
23#include <span>
24
25#include "ads9324_detail.hpp"
26#include "ads9324_encode.hpp"
27#include "ads9324_registers.hpp"
29#include "ads9324_types.hpp"
30#include "ads9324_version.h"
31
32namespace ads9324 {
33
34namespace detail {
35
36// Optional hooks: a `Declares*` concept only tests the name, the `Has*` concept
37// the exact signature, `noexcept` and the result type; the driver rejects a
38// hook that is declared but does not match (KB-CPP20-007).
39
41template <typename Port>
42concept DeclaresGpioSet =
43 requires(Port& port) { port.GpioSet(CtrlPin::Reset, GpioSignal::ACTIVE); };
44
46template <typename Port>
47concept HasGpioSet =
48 requires { ExactHook<Port, bool(CtrlPin, GpioSignal) noexcept>::Take(&Port::GpioSet); };
49
51template <typename Port>
52concept DeclaresGpioGet =
53 requires(Port& port, bool& level) { port.GpioGet(CtrlPin::DrdyAlarm, level); };
54
56template <typename Port>
57concept HasGpioGet =
58 requires { ExactHook<Port, bool(CtrlPin, bool&) noexcept>::Take(&Port::GpioGet); };
59
61template <typename Port>
62concept DeclaresCaptureLanes =
63 requires(Port& port, uint8_t* rx) { port.CaptureLanes(uint8_t{8}, rx, std::size_t{2}); };
64
67template <typename Port>
68concept HasCaptureLanes = requires {
69 ExactHook<Port, bool(uint8_t, uint8_t*, std::size_t) noexcept>::Take(&Port::CaptureLanes);
70};
71
73template <typename Port>
74concept DeclaresDelayUs = requires(Port& port) { port.DelayUs(1_u32); };
75
78template <typename Port>
79concept HasDelayUs = requires { ExactHook<Port, void(uint32_t) noexcept>::Take(&Port::DelayUs); };
80
82template <typename Port>
83concept DeclaresLog = requires(Port& port) { port.Log(LogLevel::Info, ""); };
84
87template <typename Port>
88concept HasLog =
89 requires { ExactHook<Port, void(LogLevel, const char*) noexcept>::Take(&Port::Log); };
90
94template <typename Port>
95void DelayUs(Port& port, uint32_t us) noexcept {
96 if constexpr (HasDelayUs<Port>) {
97 port.DelayUs(us);
98 } else {
99 static_assert(kAlwaysFalse<Port>, "ads9324: the port must implement `void "
100 "DelayUs(uint32_t us) noexcept`");
101 }
102}
103
106template <typename Port>
107void Log(Port& port, [[maybe_unused]] LogLevel level,
108 [[maybe_unused]] const char* message) noexcept {
109 if constexpr (HasLog<Port>) {
110 port.Log(level, message);
111 } else {
112 (void)port;
113 }
114}
115
117constexpr uint8_t LaneCount(Lanes lanes) noexcept {
118 switch (lanes) {
119 case Lanes::Four:
120 return 4U;
121 case Lanes::Two:
122 return 2U;
123 case Lanes::One:
124 return 1U;
125 case Lanes::Eight:
126 default:
127 break;
128 }
129 return 8U;
130}
131
134constexpr uint32_t FlushPhase(reg::Bank bank, uint8_t address) noexcept {
135 if ((bank == reg::Bank::Common) && (address == reg::kGenCfg5)) {
136 return 0U;
137 }
138 return ((bank != reg::Bank::Common) && (address == reg::kDwcCfg)) ? 2U : 1U;
139}
140
143constexpr bool IsFilterRegister(reg::Bank bank, uint8_t address) noexcept {
144 if (bank == reg::Bank::Common) {
145 return (address == reg::kDigFilter) || (address == reg::kGenCfg5);
146 }
147 return (address >= reg::kPhaseDelay) && (address < (reg::kPhaseDelay + 4U));
148}
149
150static_assert(FlushPhase(reg::Bank::Common, reg::kGenCfg5) == 0U);
151static_assert(FlushPhase(reg::Bank::Ain9To16, reg::kDwcCfg) == 2U);
152static_assert(FlushPhase(reg::Bank::Ain1To8, reg::kDwcTh) == 1U);
153static_assert(IsFilterRegister(reg::Bank::Ain9To16, reg::kPhaseDelay + 3U));
154static_assert(!IsFilterRegister(reg::Bank::Ain9To16, reg::kOffset));
155
156} // namespace detail
157
164// clang-format off: the table below must keep one row per line.
193// clang-format on
194template <SpiPort Port>
195class ADS9324 {
196 static_assert(!detail::DeclaresGpioSet<Port> || detail::HasGpioSet<Port>,
197 "ads9324: the optional GpioSet hook must be `bool "
198 "GpioSet(CtrlPin, GpioSignal) "
199 "noexcept`, so that a failed pin write is reported");
200 static_assert(!detail::DeclaresGpioGet<Port> || detail::HasGpioGet<Port>,
201 "ads9324: the optional GpioGet hook must be `bool "
202 "GpioGet(CtrlPin, bool& high) "
203 "noexcept`");
204 static_assert(!detail::DeclaresCaptureLanes<Port> || detail::HasCaptureLanes<Port>,
205 "ads9324: the optional CaptureLanes hook must be `bool "
206 "CaptureLanes(uint8_t, "
207 "uint8_t*, std::size_t) noexcept`");
208 static_assert(!detail::DeclaresDelayUs<Port> || detail::HasDelayUs<Port>,
209 "ads9324: the DelayUs hook must be `void DelayUs(uint32_t us) "
210 "noexcept`, so that no "
211 "wait is truncated");
212 static_assert(!detail::DeclaresLog<Port> || detail::HasLog<Port>,
213 "ads9324: the optional Log hook must be `void Log(LogLevel, "
214 "const char* message) "
215 "noexcept`");
216
217public:
225 explicit ADS9324(Port& port, const Config& config = {}) noexcept;
226
228 ADS9324(const ADS9324&) = delete;
230 ADS9324& operator=(const ADS9324&) = delete;
231
234
251
254 [[nodiscard]] bool IsInitialized() const noexcept {
255 return initialized_;
256 }
257
259 [[nodiscard]] bool IsPoweredDown() const noexcept {
260 return powered_down_;
261 }
262
269
277 Result<void> Reset(ResetKind kind) noexcept;
278
283 Result<uint16_t> Identify() noexcept;
284
288
299 Result<void> ApplyConfig(const Config& config, Verify verify = Verify::None) noexcept;
300
302 [[nodiscard]] const Config& GetConfig() const& noexcept {
303 return config_;
304 }
307 void GetConfig() const&& = delete;
308
317 Result<void> SetInput(uint8_t channel, const Input& input, Verify verify = Verify::None) noexcept;
318
322 Result<void> SetInterface(const Interface& interface, Verify verify = Verify::None) noexcept;
323
328 Result<void> SetFilter(const Filter& filter, Verify verify = Verify::None) noexcept;
329
333 Result<void> SetChannels(const ChannelSelect& select, Verify verify = Verify::None) noexcept;
334
338 Result<void> SetAlarm(const Alarm& alarm, Verify verify = Verify::None) noexcept;
339
343 Result<void> SetReference(ReferenceSource source, Verify verify = Verify::None) noexcept;
344
352 Result<void> SetTestPattern(uint8_t group, const TestPattern& pattern,
353 Verify verify = Verify::None) noexcept;
354
358
367 Result<void> Convert() noexcept;
368
376 Result<void> WaitDataReady() noexcept;
377
390 Result<Frame> ReadFrame() noexcept;
391
397
404 Result<bool> ReadAlarmPin() noexcept;
405
409
415
421 Result<void> ClearWindowFlags(uint8_t group) noexcept;
422
435 Result<void> RunAdcCalibration() noexcept;
436
442
447 Result<bool> IsCalibrationBusy() noexcept;
448
452
461 Result<void> PowerDown() noexcept;
462
470 Result<void> Wake() noexcept;
471
480 Result<uint16_t> ReadRegister(reg::Bank bank, uint8_t address) noexcept;
481
487 [[nodiscard]] uint16_t GetLastRegisterReply() const noexcept {
488 return last_reply_;
489 }
490
500
507 [[nodiscard]] uint16_t GetShadow(reg::Bank bank, uint8_t address) const noexcept;
508
510
511private:
512 Result<void> startChip(const Config& config, bool hardware) noexcept;
513 Result<void> resetChip(bool hardware) noexcept;
514 Result<void> checkIdentity() noexcept;
515 Result<void> waitCalibrationIdle(uint32_t timeout_ms, bool confirm) noexcept;
516 Result<void> checkReady() const noexcept;
517 Result<void> probeReset() noexcept;
518 Result<void> checkAlive() noexcept;
519 Result<void> confirmIdentity() noexcept;
520 Result<void> applyImage(const Config& config, Verify verify) noexcept;
521 Result<void> flushImage(const detail::RegisterImage& image) noexcept;
522 Result<void> flushPhase(const detail::RegisterImage& image, uint32_t phase) noexcept;
523 Result<void> flushRegister(reg::Bank bank, uint8_t address, uint16_t value) noexcept;
524 Result<void> pulseSysref(uint32_t convst_hz) noexcept;
525 Result<void> verifyWritten() noexcept;
526 Result<void> writeRegister(reg::Bank bank, uint8_t address, uint16_t value) noexcept;
527 Result<uint16_t> readRegister(reg::Bank bank, uint8_t address) noexcept;
528 Result<void> selectBank(reg::Bank bank) noexcept;
529 Result<void> setConvst(GpioSignal level) noexcept;
530 Result<void> pulseConvst() noexcept;
531 Result<void> readFrameBytes(std::span<uint8_t> bytes) noexcept;
532 Result<void> beginCalibration(uint16_t base, uint16_t mode) noexcept;
533 Result<void> finishCalibration(bool single_shot) noexcept;
534 Result<void> calibrate(uint16_t mode, bool single_shot) noexcept;
535 Result<void> runPatternFrame(const Config& test, Frame& frame) noexcept;
536 Result<void> restoreConfig(const Config& saved, Result<void> outcome) noexcept;
537 void resetShadow() noexcept;
538 Result<void> fail(Error error, const char* message) noexcept;
539
540 detail::RegisterBus<Port> bus_;
541 Config config_{};
542 std::array<std::array<uint16_t, reg::kAddressSpace>, reg::kBankCount> shadow_{};
543 std::array<uint64_t, reg::kBankCount> dirty_{};
544 std::array<uint64_t, reg::kBankCount> written_{};
545 uint16_t cal_mode_{0};
547 bool bank_valid_{false};
548 bool filter_touched_{false};
549 bool initialized_{false};
550 bool powered_down_{false};
551 bool chip_live_{false};
552 bool layout_ok_{false};
553 uint16_t last_reply_{0};
554 std::array<uint8_t, kMaxFrameBytes>
555 frame_buffer_{};
556};
557
560} // namespace ads9324
561
562// codeql::misra_deviation_next_line(MD-CPP-009)
563#include "../src/ads9324.ipp" // IWYU pragma: export
564
565#endif // ADS9324_HPP
Compile-time helpers of the ADS9324 driver: typed integer literals, exact hook matching,...
Pure register encoding: a Config becomes the register image the driver writes, and a data frame becom...
ADS9324 register map: banks, addresses, bit fields, reset values and the channel layout (datasheet se...
The port of the ADS9324 driver: the CRTP base, its pin enums, the SpiPort concept and the 24-bit regi...
Public types of the ADS9324 driver: errors, Result<T>, enumerations, configuration,...
Driver for one ADS9324 on a platform port.
Definition ads9324.hpp:195
Result< void > WaitDataReady() noexcept
Wait until a result is ready: the DRDY/ALARM pin (ReadySource::Pin), or the conversion time.
ADS9324 & operator=(const ADS9324 &)=delete
One driver object per chip.
Result< void > Wake() noexcept
Leave standby, wait 30 ms and check that the chip kept its registers.
Result< Frame > ReadFrame() noexcept
Read and decode one data frame.
Result< void > Deinitialize() noexcept
Put the chip in standby and mark the driver uninitialised, even if the write failed.
Result< void > PowerDown() noexcept
Enter standby (PDN_CTL.DEVICE_PDN). Other calls return Refused until Wake(). A switch-off is never re...
Result< void > SetAlarm(const Alarm &alarm, Verify verify=Verify::None) noexcept
Change the DRDY/ALARM pin.
Result< uint16_t > Identify() noexcept
Read DEVICE_ID.
bool IsPoweredDown() const noexcept
Definition ads9324.hpp:259
Result< void > Convert() noexcept
Start one conversion with a pulse on CONVST (high, low, high: the falling edge samples,...
Result< Frame > MeasureOnce() noexcept
Convert(), WaitDataReady() and ReadFrame().
Result< void > ClearWindowFlags(uint8_t group) noexcept
Clear the latched flags of a group (DWC_STAT_RST written 1, then 0).
const Config & GetConfig() const &noexcept
Definition ads9324.hpp:302
Result< void > SetReference(ReferenceSource source, Verify verify=Verify::None) noexcept
Change the reference source (30 ms settle follows).
Result< bool > IsCalibrationBusy() noexcept
Read CALIB_BUSY_FLAG.
Result< bool > ReadAlarmPin() noexcept
The level of the DRDY/ALARM pin as asserted or not, with Alarm::active_low applied.
ADS9324(const ADS9324 &)=delete
One driver object per chip.
Result< void > SetChannels(const ChannelSelect &select, Verify verify=Verify::None) noexcept
Choose the channels in the data frame.
Result< uint16_t > ReadRegister(reg::Bank bank, uint8_t address) noexcept
Read one documented register once: bank select, command and data frame.
Result< WindowFlags > ReadWindowFlags() noexcept
Read the latched window comparator flags of both banks.
void GetConfig() const &&=delete
Not on a temporary driver: the reference would dangle (KB-CPP20-044).
Result< void > SetTestPattern(uint8_t group, const TestPattern &pattern, Verify verify=Verify::None) noexcept
Change the test pattern of one channel group.
Result< void > EnsureInitialized() noexcept
Start the chip, once: the only way to initialise the driver.
Result< void > DisableAdcCalibration() noexcept
Write ADC_CAL_MODE 0: the calibration values are no longer applied.
ADS9324(Port &port, const Config &config={}) noexcept
Bind the driver to a port and store the configuration. No I/O, cannot fail.
Result< void > RunAdcCalibration() noexcept
Run the ADC calibration with Config::calibration.
uint16_t GetShadow(reg::Bank bank, uint8_t address) const noexcept
The register value the driver believes the chip holds. No I/O.
Result< void > SetInterface(const Interface &interface, Verify verify=Verify::None) noexcept
Change the data interface.
Result< void > SetFilter(const Filter &filter, Verify verify=Verify::None) noexcept
Change the digital filter.
bool IsInitialized() const noexcept
Definition ads9324.hpp:254
Result< void > ApplyConfig(const Config &config, Verify verify=Verify::None) noexcept
Change the whole configuration. Before the start it is only stored, with no I/O.
Result< void > RunDataPathSelfTest() noexcept
Check the data path with constant test patterns on all 16 channels: every channel must return its own...
Result< void > SetInput(uint8_t channel, const Input &input, Verify verify=Verify::None) noexcept
Change one channel's input settings (range, type, filter, offset, gain, phase, window).
uint16_t GetLastRegisterReply() const noexcept
The raw value the last register read returned. No bus traffic.
Definition ads9324.hpp:487
constexpr uint8_t kOffset
OFS, 8 registers, 10 bits.
Definition ads9324_registers.hpp:109
constexpr uint8_t kGenCfg5
GEN_CFG5: AVG_MODE gate.
Definition ads9324_registers.hpp:99
constexpr uint8_t kBankCount
Number of register banks.
Definition ads9324_registers.hpp:55
constexpr uint8_t kPhaseDelay
PHASE_DELAY, 4 registers, 8 bits per channel.
Definition ads9324_registers.hpp:108
Bank
A register bank. The value is the index of the bank in the driver's tables.
Definition ads9324_registers.hpp:47
constexpr uint8_t kDigFilter
DIG_FILTER: digital filters and SYSREF.
Definition ads9324_registers.hpp:98
constexpr uint8_t kDwcTh
DWC_TH, 8 registers: high byte, low byte.
Definition ads9324_registers.hpp:112
constexpr uint8_t kDwcCfg
DWC_CFG: enables, glitch filter, flag reset.
Definition ads9324_registers.hpp:111
@ Ain1To8
Channel registers AIN1 to AIN8, BANK_SEL code 010b.
@ Common
The common registers, BANK_SEL code 001b.
LogLevel
Severity passed to the optional Log() hook.
Definition ads9324_types.hpp:172
Verify
Whether a setter reads back what it wrote (costs one two-frame read per register).
Definition ads9324_types.hpp:181
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition ads9324_types.hpp:45
ResetKind
How Reset() resets the chip.
Definition ads9324_types.hpp:187
ReferenceSource
Where the ADC reference comes from (Table 7-3).
Definition ads9324_types.hpp:244
Lanes
Number of data lanes (DOUT_LANE_SEL, Table 7-11).
Definition ads9324_types.hpp:215
@ Info
Lifecycle events.
@ None
No read-back.
@ One
D7, or SDOUT with Interface::data_on_sdout.
@ Four
D7 to D4.
@ Two
D7 and D6.
@ Eight
D7 to D0. Reset value.
The ADS9324 driver: everything it declares lives here; internals in detail.
Definition ads9324.hpp:32
CtrlPin
Control pins the port may drive or read through the optional hooks.
Definition ads9324_spi_interface.hpp:75
@ Reset
RESET, active low on the package pin; idles high (INACTIVE).
@ DrdyAlarm
DRDY/ALARM: an input, read with GpioGet().
GpioSignal
Logical level of a control pin; the port maps it to the physical polarity.
Definition ads9324_spi_interface.hpp:83
@ ACTIVE
The pin function is asserted.
The DRDY/ALARM pin (DRDY_ALARM_SEL, GEN_CFG4).
Definition ads9324_types.hpp:535
Which channels the data frame carries (ANA_CFG2).
Definition ads9324_types.hpp:521
Everything EnsureInitialized() and ApplyConfig() write to the chip.
Definition ads9324_types.hpp:612
The digital filter in the data path (DIG_FILTER, GEN_CFG5).
Definition ads9324_types.hpp:527
One decoded data frame.
Definition ads9324_types.hpp:1232
The configuration of one input channel.
Definition ads9324_types.hpp:496
The data interface (GEN_CFG3, XOR_BITS_CTL, GEN_CFG4, DIG_DELAY_CFG1/2).
Definition ads9324_types.hpp:509
The value of a call, or why there is none.
Definition ads9324_types.hpp:114
A test pattern of one channel group (TP_CFG, TP_AIN).
Definition ads9324_types.hpp:567
The latched digital window comparator flags, one bit per channel (bit 0 is AIN1).
Definition ads9324_types.hpp:632