MAX22200 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
max22200.hpp
Go to the documentation of this file.
1
13#ifndef MAX22200_HPP
14#define MAX22200_HPP
15
16#include <array>
17#include <concepts>
18#include <cstddef>
19#include <cstdint>
20
21#include "max22200_detail.hpp"
24#include "max22200_types.hpp"
25#include "max22200_version.h"
26
27namespace max22200 {
28
29namespace detail {
30
31// Optional hooks: a `Declares*` concept tests that the port has a member of that name (a single
32// member by its address, an overload set by a call with the documented arguments), the `Has*`
33// concept the exact signature, `noexcept` and the result type; the driver rejects a hook that is
34// declared but does not match (KB-CPP20-007).
35
37template <typename Port>
38concept DeclaresGpioRead = requires {
39 &Port::GpioRead;
40} || requires(Port& port, GpioSignal& signal) { port.GpioRead(CtrlPin::Fault, signal); };
41
45template <typename Port>
46concept HasGpioRead =
47 requires { ExactHook<Port, bool(CtrlPin, GpioSignal&) noexcept>::Take(&Port::GpioRead); };
48
50template <typename Port>
51concept DeclaresDelayUs =
52 requires { &Port::DelayUs; } || requires(Port& port) { port.DelayUs(1U); };
53
56template <typename Port>
57concept HasDelayUs = requires { ExactHook<Port, void(uint32_t) noexcept>::Take(&Port::DelayUs); };
58
60template <typename Port>
61concept DeclaresLog =
62 requires { &Port::Log; } || requires(Port& port) { port.Log(LogLevel::Info, ""); };
63
65template <typename Port>
66concept HasLog =
67 requires { ExactHook<Port, void(LogLevel, const char*) noexcept>::Take(&Port::Log); };
68
71template <typename Port>
72void DelayUs(Port& port, uint32_t us) noexcept {
73 if constexpr (HasDelayUs<Port>) {
74 port.DelayUs(us);
75 } else {
76 static_assert(kAlwaysFalse<Port>,
77 "max22200: the port must implement `void DelayUs(uint32_t us) noexcept`");
78 }
79}
80
82template <typename Port>
83void Log(Port& port, [[maybe_unused]] LogLevel level,
84 [[maybe_unused]] const char* message) noexcept {
85 if constexpr (HasLog<Port>) {
86 port.Log(level, message);
87 } else {
88 (void)port;
89 }
90}
91
93constexpr uint8_t PairBits(uint8_t pair) noexcept {
94 return static_cast<uint8_t>(0x03U << (2U * (static_cast<uint32_t>(pair) & 0x03U)));
95}
96
98constexpr uint8_t ChannelBit(uint8_t channel) noexcept {
99 return static_cast<uint8_t>(uint32_t{1} << (static_cast<uint32_t>(channel) & 0x07U));
100}
101
102static_assert((PairBits(3_u8) == 0xC0U) && (ChannelBit(7_u8) == 0x80U),
103 "Table 10: ONCH7 is bit 31");
104
105} // namespace detail
106
113// clang-format off: the tables below must keep one row per line.
189// clang-format on
190template <SpiPort Port>
191class MAX22200 {
192 static_assert(!detail::DeclaresDelayUs<Port> || detail::HasDelayUs<Port>,
193 "max22200: the DelayUs hook must be `void DelayUs(uint32_t us) noexcept`, so that "
194 "no wait is truncated");
195 static_assert(!detail::DeclaresGpioRead<Port> || detail::HasGpioRead<Port>,
196 "max22200: the optional GpioRead hook must be `bool GpioRead(CtrlPin, GpioSignal&) "
197 "noexcept`, so that a failed pin read is reported");
198 static_assert(!detail::DeclaresLog<Port> || detail::HasLog<Port>,
199 "max22200: the optional Log hook must be `void Log(LogLevel, const char* message) "
200 "noexcept`");
201
202public:
208 explicit MAX22200(Port& port, const Config& config = {}) noexcept : bus_(port), config_(config) {}
209
211 MAX22200(const MAX22200&) = delete;
213 MAX22200& operator=(const MAX22200&) = delete;
214
217
260
262 [[nodiscard]] bool IsInitialized() const noexcept {
263 return initialized_;
264 }
265
278
295 Result<void> ApplyConfig(const Config& config) noexcept;
296
298 [[nodiscard]] const Config& GetConfig() const& noexcept {
299 return config_;
300 }
302 void GetConfig() const&& = delete;
303
307
339 Result<void> SetChannelsOn(uint8_t mask, Verify verify = Verify::None) noexcept;
340
356 Result<void> SetChannel(uint8_t channel, bool on, Verify verify = Verify::None) noexcept;
357
367 Result<void> SetBridge(uint8_t pair, BridgeState state, Verify verify = Verify::None) noexcept;
368
377 [[nodiscard]] bool IsMiscountDetectionDegraded() const noexcept {
378 return initialized_ && !comer_clear_;
379 }
380
382 [[nodiscard]] uint8_t GetChannelsOn() const noexcept {
383 return on_mask_;
384 }
385
392
396
418 Result<void> ConfigureChannel(uint8_t channel, const ChannelConfig& config,
419 Verify verify = Verify::None) noexcept;
420
436 Result<void> SetHoldCode(uint8_t channel, uint8_t code, Verify verify = Verify::None) noexcept;
437
451 Result<void> SetPairMode(uint8_t pair, PairMode mode, Verify verify = Verify::None) noexcept;
452
460 Result<void> SetFaultMask(const FaultMask& mask, Verify verify = Verify::None) noexcept;
461
471 Result<void> SetDpm(const DpmConfig& dpm, Verify verify = Verify::None) noexcept;
472
479 Result<ChannelConfig> ReadChannelConfig(uint8_t channel) noexcept;
480
484
498
511
526 Result<Faults> ClearFaults(const Faults& which = Faults::All()) noexcept;
527
533 Result<bool> ReadFaultPin() noexcept;
534
541 [[nodiscard]] uint8_t GetLastStatusByte() const noexcept {
542 return last_status_;
543 }
544
565 [[nodiscard]] LatchedFaults GetLatchedFaults() const noexcept {
566 return latched_;
567 }
568
570 void ClearLatchedFaults() noexcept {
571 latched_ = LatchedFaults{};
572 }
573
580 [[nodiscard]] Faults GetStartupFaults() const noexcept {
581 return startup_faults_;
582 }
583
598 Result<uint32_t> ReadRegister(uint8_t bank) noexcept;
599
601
602private:
603 Result<void> initialize() noexcept;
604 Result<void> attempt() noexcept;
605 Result<void> restartEnable() noexcept;
606 Result<uint32_t> wake() noexcept;
607 Result<void> checkStatus() noexcept;
608 Result<void> checkRegisters() noexcept;
609 Result<void> writeAll() noexcept;
610 Result<void> applyRunning(const Config& next) noexcept;
611 Result<void> writeOnch(uint8_t mask, Verify verify) noexcept;
613 Result<void> verifyOnch(uint8_t mask, uint8_t maybe_on) noexcept;
614 Result<void> writeStatus(const Config& next, Verify verify) noexcept;
616 void settleStatus(uint32_t changed, uint32_t off, bool clock_changed, bool read_back) noexcept;
617 Result<void> writeChannel(uint8_t channel, const ChannelConfig& config, Verify verify) noexcept;
618 Result<detail::Reply> put32(uint8_t bank, uint32_t value) noexcept;
619 Result<void> checkWord(uint8_t bank, uint32_t value, uint32_t mask, uint8_t echo,
620 uint32_t& read) noexcept;
621 Result<void> check8(uint8_t bank, uint8_t want, uint8_t& read) noexcept;
622 void adoptStatus(uint32_t value) noexcept;
623 Result<uint32_t> read32(uint8_t bank, uint32_t sdi = 0) noexcept;
625 bool takeStatus(uint32_t value) noexcept;
626 Result<uint8_t> read8(uint8_t bank) noexcept;
627 Result<void> clearStartupFaults() noexcept;
628 void latchFaults(uint32_t fault, uint32_t cleared) noexcept;
630 [[nodiscard]] bool floatingReply(uint32_t value) const noexcept {
631 return (value == 0xFFFFFFFFU) && (last_status_ == 0xFFU);
632 }
633 [[nodiscard]] bool validOnMask(uint8_t mask) const noexcept;
635 [[nodiscard]] bool modeChangeBlocked(const Config& next, uint8_t rewrite) const noexcept;
636 [[nodiscard]] static constexpr bool isVerify(Verify verify) noexcept {
637 return detail::IsEnumerator(verify);
638 }
641 Error note(const detail::Reply& reply, Error e) noexcept;
642 void latchStatusByte(uint8_t flags) noexcept;
643 void onReset() noexcept;
646 [[nodiscard]] uint8_t maybeOn() const noexcept {
647 return static_cast<uint8_t>(static_cast<uint32_t>(on_mask_) |
648 static_cast<uint32_t>(uncertain_) |
649 static_cast<uint32_t>(unverified_onch_));
650 }
652 void wrote(uint8_t bank, uint8_t onch_changed) noexcept;
654 void failedWrite(uint8_t bank, Error e) noexcept {
655 if (initialized_ && (e != Error::DeviceReset)) {
656 stale_banks_ |= uint32_t{1} << (static_cast<uint32_t>(bank) & 0x0FU);
657 }
658 }
661 [[nodiscard]] bool pairUnknown(uint8_t& mask) const noexcept;
663 bool probeReset() noexcept;
664 Result<void> clearComer() noexcept;
667 [[nodiscard]] bool stopOnComer() const noexcept {
668 return initialized_ && comer_clear_;
669 }
670 [[nodiscard]] bool stale(uint8_t bank) const noexcept {
671 return ((stale_banks_ >> (static_cast<uint32_t>(bank) & 0x0FU)) & 1U) != 0U;
672 }
673 template <typename T>
674 Result<T> report(Result<T> r) noexcept;
675 template <typename T>
676 Result<T> fail(Error error, const char* message) noexcept;
677
678 detail::RegisterBus<Port> bus_;
679 Config config_{};
680 uint8_t on_mask_{0};
681 uint8_t uncertain_{0};
682 uint8_t cfg_uncertain_{0};
683 uint8_t last_status_{0xFF};
684 LatchedFaults latched_{};
685 Faults startup_faults_{};
686 bool latch_uvm_{true};
687 bool comer_seen_{false};
688 bool comer_armed_{false};
689 bool onch_ready_{false};
690 bool echo_bad_{false};
691 bool comer_clear_{false};
692 bool comer_new_{false};
693 uint8_t unverified_onch_{0};
694 uint32_t unverified_banks_{0};
695 uint32_t stale_banks_{0};
698 uint8_t pair_uncertain_{0};
699 bool clock_uncertain_{false};
700 uint8_t unverified_pairs_{0};
701 bool unverified_clock_{false};
702 bool initialized_{false};
703};
704
707} // namespace max22200
708
709// codeql::misra_deviation_next_line(MD-CPP-009)
710#include "../src/max22200.ipp" // IWYU pragma: export
711
712#endif // MAX22200_HPP
Driver for one MAX22200 or MAX22200A on a platform port.
Definition max22200.hpp:191
Result< void > SetHoldCode(uint8_t channel, uint8_t code, Verify verify=Verify::None) noexcept
Change a channel's HOLD code on the fly: one 8-bit write of CFG_CHn[31:24] (HFS and HOLD),...
Result< void > ConfigureChannel(uint8_t channel, const ChannelConfig &config, Verify verify=Verify::None) noexcept
Write one channel's CFG_CHn: 32 bits, 2 transfers. Everything but the drive mode and the side can cha...
Result< ChannelConfig > ReadChannelConfig(uint8_t channel) noexcept
Read one channel's CFG_CHn from the chip: 2 transfers.
void GetConfig() const &&=delete
Not on a temporary driver: the reference would dangle (KB-CPP20-044).
Result< uint8_t > ReadChannelsOn() noexcept
Read ONCH from the chip: one 8-bit read, 2 transfers. Does not change GetChannelsOn(); a channel foun...
Result< Faults > ClearFaults(const Faults &which=Faults::All()) noexcept
Read FAULT and clear the flags in which: 2 transfers. On the MAX22200A only those flags clear (select...
Result< void > SetChannelsOn(uint8_t mask, Verify verify=Verify::None) noexcept
Switch every channel at once: one 8-bit write of STATUS[31:24] (ONCH). A channel with trigger_pin fol...
bool IsInitialized() const noexcept
Definition max22200.hpp:262
Result< Faults > ReadFaults() noexcept
Read FAULT without clearing what can be kept: 2 transfers, SDI all 0.
Result< void > SetFaultMask(const FaultMask &mask, Verify verify=Verify::None) noexcept
Change the fault masks: a 32-bit STATUS write, 2 transfers.
Result< uint32_t > ReadRegister(uint8_t bank) noexcept
Read one register once: one 32-bit read, 2 transfers, no retry, no decoding and no check (handbook KB...
Result< void > EnsureInitialized() noexcept
Start the chip, once: the only way to initialise the driver.
uint8_t GetLastStatusByte() const noexcept
The fault byte, STATUS[7:0], the chip clocked out during the last command byte or the last 8-bit writ...
Definition max22200.hpp:541
void ClearLatchedFaults() noexcept
Empty the latch of GetLatchedFaults(). No I/O; nothing is sent to the chip.
Definition max22200.hpp:570
MAX22200 & operator=(const MAX22200 &)=delete
One driver object per chip.
Result< void > SetBridge(uint8_t pair, BridgeState state, Verify verify=Verify::None) noexcept
Set a full-bridge pair's state (Table 7): the same single write as SetChannelsOn().
Result< Status > ReadStatus() noexcept
Read STATUS: 2 transfers. The read clears OVT and UVM on the chip (Register Details: "Read Clears All...
MAX22200(const MAX22200 &)=delete
One driver object per chip.
MAX22200(Port &port, const Config &config={}) noexcept
Bind the driver to a port and store the configuration. No I/O, cannot fail.
Definition max22200.hpp:208
Result< void > SetDpm(const DpmConfig &dpm, Verify verify=Verify::None) noexcept
Write the DPM settings, CFG_DPM: 32 bits, 2 transfers.
Result< void > ApplyConfig(const Config &config) noexcept
Replace the configuration.
Result< void > SetPairMode(uint8_t pair, PairMode mode, Verify verify=Verify::None) noexcept
Change one pair's mode: a 32-bit STATUS write, 2 transfers. The chip takes CMxy only with both channe...
Faults GetStartupFaults() const noexcept
The FAULT flags the last start-up found and cleared: faults latched before the start (the chip may ke...
Definition max22200.hpp:580
Result< void > SetChannel(uint8_t channel, bool on, Verify verify=Verify::None) noexcept
Switch one channel, keeping the others as the driver last wrote them: the same single write as SetCha...
LatchedFaults GetLatchedFaults() const noexcept
The clear-on-read flags any read of the driver took from the chip since the last ClearLatchedFaults()...
Definition max22200.hpp:565
bool IsMiscountDetectionDegraded() const noexcept
Definition max22200.hpp:377
const Config & GetConfig() const &noexcept
Definition max22200.hpp:298
Result< void > Deinitialize() noexcept
Switch every channel off and the chip to sleep, and mark the driver uninitialised: one STATUS write w...
Result< bool > ReadFaultPin() noexcept
Read the FAULT pin through the optional GpioRead() hook. No SPI.
uint8_t GetChannelsOn() const noexcept
Definition max22200.hpp:382
BridgeState
The state of a pair in PairMode::FullBridge (Table 7).
Definition max22200_types.hpp:279
Verify
Extra verification for one call, chosen per call (handbook KB-ARCH-041).
Definition max22200_types.hpp:224
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition max22200_types.hpp:39
PairMode
What a channel pair does, CMxy in STATUS ("Supported Driver Configurations").
Definition max22200_types.hpp:272
LogLevel
Severity passed to the optional Log() hook.
Definition max22200_types.hpp:210
@ None
No extra transfer and no compare. The default.
@ Info
Lifecycle events: initialised.
Compile-time helpers of the MAX22200 driver: exact hook matching, typed register fields and enumerati...
MAX22200 register map: the Command Register, the 32-bit register banks, their fields,...
The SPI port of the MAX22200 driver: the CRTP base, its pin enums, the SpiPort concept and the two-ph...
Public types of the MAX22200 driver: errors, Result<T>, the channel and chip settings,...
The MAX22200 driver: everything it declares lives here; internals in detail.
Definition max22200.hpp:27
GpioSignal
Logical level of a control pin; the port maps it to the physical polarity.
Definition max22200_spi_interface.hpp:100
CtrlPin
The chip's control pins the port drives or reads.
Definition max22200_spi_interface.hpp:92
One channel's CFG_CHn register, as codes (Table 11). ChannelConfig{} is the reset value: CDR,...
Definition max22200_types.hpp:381
What the driver is told about the chip and the board. Config{} holds the reset values of STATUS and e...
Definition max22200_types.hpp:456
The plunger-movement detection settings, CFG_DPM (global, for every channel with ChannelConfig::plung...
Definition max22200_types.hpp:433
The fault masks, STATUS[23:17]: a masked fault does not pull FAULT low (its flag is still set)....
Definition max22200_types.hpp:411
The FAULT register: one byte per fault type, bit n for channel n (Table 12). Also used to say which f...
Definition max22200_types.hpp:500
The flags the driver has seen since the last ClearLatchedFaults() (handbook KB-CPP-119): OVT and UVM ...
Definition max22200_types.hpp:565
The value of a call, or why there is none.
Definition max22200_types.hpp:150
STATUS as read (ReadStatus()): the channels that are on and the seven flags.
Definition max22200_types.hpp:478