ADS7952 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
ads7952.hpp
Go to the documentation of this file.
1
13#ifndef ADS7952_HPP
14#define ADS7952_HPP
15
16#include <algorithm>
17#include <array>
18#include <bit>
19#include <concepts>
20#include <cstddef>
21#include <cstdint>
22#include <span>
23
24#include "ads7952_detail.hpp"
25#include "ads7952_registers.hpp"
27#include "ads7952_types.hpp"
28#include "ads7952_version.h"
29
30namespace ads7952 {
31
32namespace detail {
33
34// Optional hooks: a `Declares*` concept only tests the name, the `Has*` concept the exact
35// signature, `noexcept` and the result type; the driver rejects a hook that is declared but does
36// not match (KB-CPP20-007).
37
39template <typename Port>
40concept DeclaresDelayUs = requires(Port& port) { port.DelayUs(1U); };
41
44template <typename Port>
45concept HasDelayUs = requires { ExactHook<Port, void(uint32_t) noexcept>::Take(&Port::DelayUs); };
46
48template <typename Port>
49concept DeclaresLog = requires(Port& port) { port.Log(LogLevel::Info, ""); };
50
52template <typename Port>
53concept HasLog =
54 requires { ExactHook<Port, void(LogLevel, const char*) noexcept>::Take(&Port::Log); };
55
58template <typename Port>
59void DelayUs(Port& port, uint32_t us) noexcept {
60 if constexpr (HasDelayUs<Port>) {
61 port.DelayUs(us);
62 } else {
63 static_assert(kAlwaysFalse<Port>,
64 "ads7952: the port must implement `void DelayUs(uint32_t us) noexcept`");
65 }
66}
67
69template <typename Port>
70void Log(Port& port, [[maybe_unused]] LogLevel level,
71 [[maybe_unused]] const char* message) noexcept {
72 if constexpr (HasLog<Port>) {
73 port.Log(level, message);
74 } else {
75 (void)port;
76 }
77}
78
83[[nodiscard]] constexpr uint8_t NextInSequence(uint16_t mask, uint8_t channel) noexcept {
84 const uint32_t from = (static_cast<uint32_t>(channel) + 1U) & 0x0FU;
85 const auto rotated = std::rotr(mask, static_cast<int>(from));
86 if (rotated == 0U) {
87 return channel;
88 }
89 const auto step = static_cast<uint32_t>(std::countr_zero(rotated));
90 return static_cast<uint8_t>((from + step) & 0x0FU);
91}
92
94[[nodiscard]] constexpr uint8_t CountChannels(uint16_t mask) noexcept {
95 return static_cast<uint8_t>(std::popcount(mask));
96}
97
99[[nodiscard]] constexpr uint16_t Auto2Mask(uint8_t last) noexcept {
100 return static_cast<uint16_t>((uint32_t{2} << (static_cast<uint32_t>(last) & 0x0FU)) - 1U);
101}
102
103// Sections 8.4.5 and 8.4.6: ascending order with wrap-round.
104static_assert((NextInSequence(0x0FFF_u16, 3_u8) == 4U) &&
105 (NextInSequence(0x0FFF_u16, 11_u8) == 0U));
106static_assert((NextInSequence(0x8001_u16, 15_u8) == 0U) &&
107 (NextInSequence(0x8001_u16, 0_u8) == 15U));
108static_assert((NextInSequence(0x0010_u16, 4_u8) == 4U) && (NextInSequence(0x0000_u16, 7_u8) == 7U));
109static_assert((CountChannels(0xFFFF_u16) == 16U) && (CountChannels(0x00A5_u16) == 4U));
110static_assert((Auto2Mask(0_u8) == 0x0001U) && (Auto2Mask(11_u8) == 0x0FFFU) &&
111 (Auto2Mask(15_u8) == 0xFFFFU));
112
115[[nodiscard]] constexpr uint16_t ControlBits(const Config& config) noexcept {
116 return static_cast<uint16_t>(
117 ((config.range == Range::TwoVref) ? static_cast<uint32_t>(reg::kRangeTwoVref) : 0U) |
118 (static_cast<uint32_t>(config.gpio.output_levels) & reg::kGpioDataMask));
119}
120
123[[nodiscard]] constexpr uint16_t GpioProgramWord(const Config& config) noexcept {
124 const GpioConfig& g = config.gpio;
125 const uint32_t qfn = (config.package == Package::Vqfn) ? 0x000EU : 0x0000U;
126 return static_cast<uint16_t>(
127 static_cast<uint32_t>(reg::kGpioProgram) |
128 (g.gpio3_power_down_input ? static_cast<uint32_t>(reg::kGpio3PowerDown) : 0U) |
129 (g.gpio2_range_input ? static_cast<uint32_t>(reg::kGpio2Range) : 0U) |
130 ((static_cast<uint32_t>(ToUnderlying(g.alarm_output)) & 0x07U) << reg::kGpioAlarmShift) |
131 ((static_cast<uint32_t>(g.output_mask) | qfn) & reg::kGpioDirectionMask));
132}
133
136[[nodiscard]] constexpr Config EveryThresholdDiffers(const Config& config) noexcept {
137 Config from = config;
138 for (AlarmThreshold& t : from.alarms) {
139 t.low_code = static_cast<uint16_t>(~static_cast<uint32_t>(t.low_code) & kMaxCode);
140 t.high_code = static_cast<uint16_t>(~static_cast<uint32_t>(t.high_code) & kMaxCode);
141 }
142 return from;
143}
144
145// The reset configuration programs the reset values (Table 11: every pin an input, no function).
146static_assert((ControlBits(Config{}) == 0U) && (GpioProgramWord(Config{}) == reg::kGpioProgram));
147static_assert(GpioProgramWord(Config{.package = Package::Vqfn}) == 0x400EU);
148
151struct IdentityChannels {
152 uint8_t first;
153 uint8_t second;
154};
155
156[[nodiscard]] constexpr IdentityChannels IdentityFor(Variant variant) noexcept {
157 switch (variant) {
158 case Variant::Ads7950:
159 return {.first = 2, .second = 1}; // 10, 01
160 case Variant::Ads7951:
161 return {.first = 5, .second = 2}; // 101, 010
162 case Variant::Ads7952:
163 case Variant::Ads7953:
164 default:
165 break;
166 }
167 return {.first = 10, .second = 5}; // 1010, 0101
168}
169
171[[nodiscard]] constexpr bool IdentityCovers(Variant variant) noexcept {
172 const IdentityChannels ids = IdentityFor(variant);
173 const auto channels = static_cast<uint32_t>(ChannelCount(variant));
174 const uint32_t used = (channels > 8U) ? 0x0FU : (channels - 1U);
175 return (ids.first < channels) && (ids.second < channels) &&
176 (((static_cast<uint32_t>(ids.first) ^ static_cast<uint32_t>(ids.second)) & used) == used);
177}
178
179static_assert(IdentityCovers(Variant::Ads7950) && IdentityCovers(Variant::Ads7951) &&
180 IdentityCovers(Variant::Ads7952) && IdentityCovers(Variant::Ads7953));
181
182} // namespace detail
183
190// clang-format off: the frame-cost table below must keep one row per line.
243// clang-format on
244template <SpiPort Port>
245class ADS7952 {
246 static_assert(
247 !detail::DeclaresDelayUs<Port> || detail::HasDelayUs<Port>,
248 "ads7952: the DelayUs hook must be `void DelayUs(uint32_t us) noexcept`, so that no "
249 "wait is truncated");
250 static_assert(!detail::DeclaresLog<Port> || detail::HasLog<Port>,
251 "ads7952: the optional Log hook must be `void Log(LogLevel, const char* message) "
252 "noexcept`");
253
254public:
260 explicit ADS7952(Port& port, const Config& config = {}) noexcept : bus_(port), config_(config) {}
261
263 ADS7952(const ADS7952&) = delete;
265 ADS7952& operator=(const ADS7952&) = delete;
266
269
293
295 [[nodiscard]] bool IsInitialized() const noexcept {
296 return initialized_;
297 }
298
310
328 Result<void> ApplyConfig(const Config& config) noexcept;
329
341 [[nodiscard]] bool IsConfigUncertain() const noexcept {
342 return config_uncertain_;
343 }
344
346 [[nodiscard]] const Config& GetConfig() const& noexcept {
347 return config_;
348 }
350 void GetConfig() const&& = delete;
351
353 [[nodiscard]] uint8_t GetChannelCount() const noexcept {
354 return ChannelCount(config_.variant);
355 }
356
360
379 Result<uint16_t> ReadChannel(uint8_t channel) noexcept;
380
393 Result<void> ReadChannels(std::span<const uint8_t> channels, std::span<uint16_t> codes) noexcept;
394
414
421 Result<Bank> ReadAuto2() noexcept;
422
436 Result<void> TraceFrames(uint8_t channel, std::span<uint16_t> replies) noexcept;
437
443 [[nodiscard]] uint32_t ToMicrovolts(uint16_t code) const noexcept {
444 return CodeToMicrovolts(code, config_.range, config_.vref_mv);
445 }
446
454 [[nodiscard]] uint32_t ToMicrovolts(const Bank& bank, uint8_t channel) const noexcept {
455 return bank.Has(channel) ? CodeToMicrovolts(bank.code[channel], bank.range, config_.vref_mv)
456 : 0U;
457 }
458
475
482 [[nodiscard]] Error CheckScaleCode(uint16_t code) const noexcept {
483 return ads7952::CheckScaleCode(config_, code);
484 }
485
491 [[nodiscard]] uint16_t GetLastReply() const noexcept {
492 return last_reply_;
493 }
494
498
508 Result<void> SetRange(Range range) noexcept;
509
523 Result<void> SetAuto1Channels(uint16_t mask, Verify verify = Verify::None) noexcept;
524
533 Result<void> SetAuto2LastChannel(uint8_t last, Verify verify = Verify::None) noexcept;
534
543 Result<void> SetAlarmThresholds(uint8_t channel, AlarmThreshold thresholds) noexcept;
544
560 Result<void> SetGpioOutputs(uint8_t levels, Verify verify = Verify::None) noexcept;
561
568
570
571private:
573 enum class Mode : uint8_t { Unknown, Manual, Auto1, Auto2 };
574
575 Result<void> initialize() noexcept;
576 Result<void> programAll() noexcept;
577 Result<void> resetChip() noexcept;
578 Result<void> checkIdentity() noexcept;
579 Result<uint16_t> checkScale() noexcept;
580 Result<void> writeConfig(const Config& to) noexcept;
581 Result<void> writeGpioProgram(const Config& to) noexcept;
582 Result<void> writeAlarms(const Config& from, const Config& to) noexcept;
583 Result<void> writeAlarmGroup(const Config& from, const Config& to, uint8_t group) noexcept;
584 Result<void> writeControl(const Config& to) noexcept;
585 Result<void> programAuto1(uint16_t mask) noexcept;
586 Result<void> programAuto2(uint8_t last) noexcept;
587 Result<uint16_t> readSelected(uint8_t channel, uint8_t rest) noexcept;
588 Result<void> park(uint8_t channel, uint8_t rest) noexcept;
589 Result<void> readPipelined(std::span<const uint8_t> channels, std::span<uint16_t> codes) noexcept;
590 Result<Bank> scan(Mode mode, uint16_t mask) noexcept;
591 Result<Bank> collect(uint16_t mask) noexcept;
592 Result<void> discardStale() noexcept;
593 Result<uint16_t> modeFrame(uint16_t control_bits) noexcept;
594 Result<uint16_t> select(uint8_t channel) noexcept;
595 Result<uint16_t> selectChecked(uint8_t channel) noexcept;
596 [[nodiscard]] uint8_t settledChannel() const noexcept;
597 Error lostTrack(Error mismatch, uint8_t address) noexcept;
598 Result<uint16_t> frame(uint16_t word) noexcept;
600 static constexpr uint8_t kNotAReset = 0xFFU;
601 [[nodiscard]] bool validChannel(uint8_t channel) const noexcept {
602 return channel < ChannelCount(config_.variant);
603 }
604 [[nodiscard]] bool validList(std::span<const uint8_t> channels,
605 std::span<const uint16_t> codes) const noexcept {
606 if (channels.empty() || (channels.size() > kMaxChannels) || (codes.size() < channels.size())) {
607 return false;
608 }
609 return std::all_of(channels.begin(), channels.end(),
610 [this](uint8_t channel) { return validChannel(channel); });
611 }
612 [[nodiscard]] static constexpr bool isVerify(Verify verify) noexcept {
613 return (verify == Verify::None) || (verify == Verify::ReadBack);
614 }
615 template <typename T>
616 Result<T> fail(Error error, const char* message) noexcept;
617 Result<void> failedWrite(Error error, const char* message) noexcept;
618
619 detail::FrameBus<Port> bus_;
620 Config config_{};
621 Mode mode_{Mode::Unknown};
622 uint8_t manual_channel_{0};
623 uint8_t stale_{0};
624 uint16_t last_reply_{0xFFFF};
625 bool initialized_{false};
626 bool config_uncertain_{false};
627};
628
631} // namespace ads7952
632
633// codeql::misra_deviation_next_line(MD-CPP-009)
634#include "../src/ads7952.ipp" // IWYU pragma: export
635
636#endif // ADS7952_HPP
Compile-time helpers of the ADS7952 driver: exact hook matching and enumeration checks.
ADS795x command and reply words: the bit fields of every frame (datasheet SLAS605C,...
The SPI port of the ADS7952 driver: the CRTP base, the SpiPort concept and the 16-bit frame.
Public types of the ADS7952 driver: errors, Result<T>, variants, ranges, GPIO and alarm settings,...
Driver for one ADS7950, ADS7951, ADS7952 or ADS7953 on a platform port.
Definition ads7952.hpp:245
uint32_t ToMicrovolts(uint16_t code) const noexcept
The input voltage a code stands for in the configured range and reference. No I/O.
Definition ads7952.hpp:443
Error CheckScaleCode(uint16_t code) const noexcept
Judge a code of the monitor channel against Config::monitor, with no I/O: use it on every Bank or DMA...
Definition ads7952.hpp:482
Result< void > SetAlarmThresholds(uint8_t channel, AlarmThreshold thresholds) noexcept
Program both alarm thresholds of a channel: the group frame, the low threshold, the high threshold wi...
bool IsInitialized() const noexcept
Definition ads7952.hpp:295
Result< void > ReadChannels(std::span< const uint8_t > channels, std::span< uint16_t > codes) noexcept
One conversion of each listed channel, pipelined in Manual mode (Figure 51): a Manual word per channe...
Result< void > EnsureInitialized() noexcept
Reset the chip, write the configuration and check that an ADS795x answers, once: the only way to init...
uint8_t GetChannelCount() const noexcept
Definition ads7952.hpp:353
ADS7952(const ADS7952 &)=delete
One driver object per chip.
bool IsConfigUncertain() const noexcept
Whether the chip may hold something other than GetConfig(). No I/O.
Definition ads7952.hpp:341
Result< uint16_t > ReadChannel(uint8_t channel) noexcept
One conversion of channel in Manual mode.
void GetConfig() const &&=delete
Not on a temporary driver: the reference would dangle (KB-CPP20-044).
Result< void > SetAuto1Channels(uint16_t mask, Verify verify=Verify::None) noexcept
Program the Auto-1 sequence: two frames (Table 3). In Auto-1 the chip goes on with the next enabled c...
uint32_t ToMicrovolts(const Bank &bank, uint8_t channel) const noexcept
The input voltage of one channel of a scan, in the range that scan was converted in (Bank::range),...
Definition ads7952.hpp:454
ADS7952(Port &port, const Config &config={}) noexcept
Bind the driver to a port and store the configuration. No I/O, cannot fail.
Definition ads7952.hpp:260
Result< Bank > ReadAuto2() noexcept
One pass of the Auto-2 sequence, channel 0 to Config::auto2_last_channel: as ReadAuto1() with the Aut...
Result< void > SetRange(Range range) noexcept
Change the input range: one mode word for the current mode with the new DI06 (Table 1,...
Result< void > SetGpioOutputs(uint8_t levels, Verify verify=Verify::None) noexcept
Drive the GPIO outputs: one mode word with the new DI03:00, then the frame on whose CS falling edge t...
uint16_t GetLastReply() const noexcept
The last reply word the driver received, for logs: 0xFFFF before the first. No I/O.
Definition ads7952.hpp:491
Result< uint8_t > ReadGpio() noexcept
Read the levels of GPIO3:0, inputs and outputs: a mode word with DI04 = 1, then one with DI04 = 0 who...
Result< void > ApplyConfig(const Config &config) noexcept
Replace the configuration.
Result< void > TraceFrames(uint8_t channel, std::span< uint16_t > replies) noexcept
Bring-up trace: select channel in Manual mode (DI11 = 1) and return every reply word unparsed,...
ADS7952 & operator=(const ADS7952 &)=delete
One driver object per chip.
Result< void > Deinitialize() noexcept
Power the chip down and mark the driver uninitialised: one mode word with DI05 = 1,...
Result< void > SetAuto2LastChannel(uint8_t last, Verify verify=Verify::None) noexcept
Program the last channel of the Auto-2 sequence: one frame (Table 6). In Auto-2 the chip starts again...
const Config & GetConfig() const &noexcept
Definition ads7952.hpp:346
Result< Bank > ReadAuto1() noexcept
One pass of the Auto-1 sequence (Config::auto1_channels): the hot path.
Result< uint16_t > CheckScale() noexcept
Prove the scale now: one conversion of the Config::monitor channel, judged by CheckScaleCode()....
constexpr uint16_t kGpio3PowerDown
DI08: GPIO3 is the power-down input.
Definition ads7952_registers.hpp:61
constexpr uint16_t kRangeTwoVref
DI06: 0 to 2 x VREF (Range 2).
Definition ads7952_registers.hpp:50
constexpr uint16_t kGpioProgram
0100: GPIO program register (Table 11).
Definition ads7952_registers.hpp:41
constexpr uint16_t kGpioDirectionMask
DI03:00: 1 = output.
Definition ads7952_registers.hpp:64
constexpr uint32_t kGpioAlarmShift
DI06:04: GPIO0/GPIO1 alarm outputs.
Definition ads7952_registers.hpp:63
constexpr uint16_t kGpioDataMask
DI03:00: GPIO output levels.
Definition ads7952_registers.hpp:53
constexpr uint16_t kGpio2Range
DI07: GPIO2 is the range input.
Definition ads7952_registers.hpp:62
constexpr uint8_t ChannelCount(Variant variant) noexcept
Number of analog inputs of a variant.
Definition ads7952_types.hpp:317
constexpr uint32_t CodeToMicrovolts(uint16_t code, Range range, uint16_t vref_mv) noexcept
Convert a result code to the input voltage it stands for (Table 8: one LSB is full scale / 4096,...
Definition ads7952_types.hpp:653
Range
Input range, DI06 of the mode control word (Tables 1, 2, 5; Table 8).
Definition ads7952_types.hpp:227
Variant
Which 12-bit member of the family is fitted. The chip cannot tell, so it is configured.
Definition ads7952_types.hpp:212
constexpr std::size_t kMaxChannels
Channels of the largest part (ADS7953); arrays indexed by channel have this size.
Definition ads7952_types.hpp:299
constexpr Error CheckScaleCode(const Config &config, uint16_t code) noexcept
Judge one code of the scale monitor's channel. No I/O.
Definition ads7952_types.hpp:504
constexpr uint16_t kMaxCode
Largest result code: 12 bits, straight binary (Table 8).
Definition ads7952_types.hpp:301
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition ads7952_types.hpp:38
LogLevel
Severity passed to the optional Log() hook.
Definition ads7952_types.hpp:197
Verify
Extra verification for one call, chosen per call (handbook KB-ARCH-041).
Definition ads7952_types.hpp:256
@ TwoVref
0 to 2 x VREF (Range 2); specified only while 2 x VREF <= +VA (section 7.6).
@ Ads7953
16 channels.
@ Ads7952
12 channels. The default.
@ Ads7951
8 channels.
@ Ads7950
4 channels.
@ Info
Lifecycle events: initialised.
@ None
No extra frame. The default.
@ ReadBack
Read back what the chip took (GPIO levels, the scanned sequence).
The ADS7952 driver: everything it declares lives here; internals in detail.
Definition ads7952.hpp:30
The two alarm thresholds of one channel, in 12-bit result codes. The chip keeps the upper 10 bits and...
Definition ads7952_types.hpp:293
The result of one Auto-1 or Auto-2 scan: one code per channel of the sequence.
Definition ads7952_types.hpp:354
What the driver is told about the chip and the board. Config{} is an ADS7952 in TSSOP left in its res...
Definition ads7952_types.hpp:402
std::array< AlarmThreshold, kMaxChannels > alarms
Definition ads7952_types.hpp:424
uint16_t vref_mv
Definition ads7952_types.hpp:412
Package package
Definition ads7952_types.hpp:404
Variant variant
The fitted part; every channel is checked against it.
Definition ads7952_types.hpp:403
GpioConfig gpio
GPIO program register and output levels.
Definition ads7952_types.hpp:423
Range range
Definition ads7952_types.hpp:408
The GPIO program register and the GPIO output levels. GpioConfig{} is the reset state: every pin an i...
Definition ads7952_types.hpp:280
uint8_t output_mask
Bit n = 1: GPIOn is a general-purpose output (DI03:00).
Definition ads7952_types.hpp:281
uint8_t output_levels
Levels of the output pins, bit n for GPIOn; only output pins.
Definition ads7952_types.hpp:282
bool gpio2_range_input
GPIO2 selects the range (DI07); DI06 is then ignored.
Definition ads7952_types.hpp:284
bool gpio3_power_down_input
GPIO3 is the active-low power-down input (DI08).
Definition ads7952_types.hpp:285
AlarmOutput alarm_output
GPIO0/GPIO1 alarm functions (DI06:04).
Definition ads7952_types.hpp:283
The value of a call, or why there is none.
Definition ads7952_types.hpp:137