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

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

Namespaces

namespace  reg
 The MAX22200 register map.
 

Classes

struct  ChannelConfig
 One channel's CFG_CHn register, as codes (Table 11). ChannelConfig{} is the reset value: CDR, low side, every code 0 (no current), 25 kHz, every diagnostic off. More...
 
struct  Config
 What the driver is told about the chip and the board. Config{} holds the reset values of STATUS and every CFG_CHn (Register Details, p36, p38-39), for a part declared as Max22200 (correct on both parts) and an RREF not given. CFG_DPM has no reset values in the datasheet (p40-41): dpm is 0, the value the driver writes at start-up, not a known reset state. More...
 
struct  DpmConfig
 The plunger-movement detection settings, CFG_DPM (global, for every channel with ChannelConfig::plunger_detect). DpmConfig{} is all zero. More...
 
struct  DutyLimits
 The duty-cycle limits the chip applies (Table 2), in percent. More...
 
struct  FaultMask
 The fault masks, STATUS[23:17]: a masked fault does not pull FAULT low (its flag is still set). FaultMask{} is the reset value: only COMER masked. More...
 
struct  Faults
 The FAULT register: one byte per fault type, bit n for channel n (Table 12). Also used to say which flags ClearFaults() clears. More...
 
struct  LatchedFaults
 The flags the driver has seen since the last ClearLatchedFaults() (handbook KB-CPP-119): OVT and UVM from every 32-bit STATUS read ("Read Clears All", Register Details), the FAULT flags every FAULT read clears ("Clearing the FAULT Register"), and the summary flags of every fault byte (STATUS[7:0]) any access clocks out, at no extra I/O: the chip clears OLF when a channel switches on (p21) and HHF when it starts a new cycle (p23), so a flag can come and go between two FAULT reads. GetLatchedFaults() returns it with no I/O. More...
 
class  MAX22200
 Driver for one MAX22200 or MAX22200A on a platform port. 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...
 
class  SpiInterface
 CRTP base of the platform SPI port. More...
 
struct  Status
 STATUS as read (ReadStatus()): the channels that are on and the seven flags. 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: EnsureInitialized(), Transfer() and GpioSet() (CMD and ENABLE).
 

Enumerations

enum class  CtrlPin : uint8_t { Enable = 0 , Cmd = 1 , Fault = 2 }
 The chip's control pins the port drives or reads. 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::NoDevice = 16 , Error::Pin = 17 ,
  Error::CommunicationError = 18 , Error::WriteMismatch = 19 , Error::Undervoltage = 20 , Error::ChannelsActive = 21 ,
  Error::DeviceReset = 22 , Error::Uncertain = 23
}
 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 }
 Extra verification for one call, chosen per call (handbook KB-ARCH-041). More...
 
enum class  Variant : uint8_t { Variant::Max22200A = 0 , Variant::Max22200 = 1 }
 Which part is fitted. The chip cannot tell, so it is configured: the two differ only in how a FAULT read clears the flags ("Clearing the FAULT Register", Ordering Information). More...
 
enum class  MasterClock : uint8_t { MasterClock::Khz100 = 0 , MasterClock::Khz80 = 1 }
 The oscillator, STATUS.FREQM (global): the time base of every channel. More...
 
enum class  ChopDivider : uint8_t { ChopDivider::Div4 = 0 , ChopDivider::Div3 = 1 , ChopDivider::Div2 = 2 , ChopDivider::Div1 = 3 }
 A channel's chopping frequency as a division of the oscillator, FREQ_CFG (Table 1). More...
 
enum class  DriveMode : uint8_t { DriveMode::Cdr = 0 , DriveMode::Vdr = 1 }
 How a channel regulates, VDRnCDR. More...
 
enum class  Side : uint8_t { Side::Low = 0 , Side::High = 1 }
 Where the load is tied, HSnLS. More...
 
enum class  PairMode : uint8_t { PairMode::Independent = 0 , PairMode::Parallel = 1 , PairMode::FullBridge = 2 }
 What a channel pair does, CMxy in STATUS ("Supported Driver Configurations"). More...
 
enum class  BridgeState : uint8_t { BridgeState::HiZ = 0 , BridgeState::Forward = 1 , BridgeState::Reverse = 2 , BridgeState::Brake = 3 }
 The state of a pair in PairMode::FullBridge (Table 7). More...
 

Functions

constexpr Config KconfigDefaults () noexcept
 The configuration menuconfig selected, on top of Config{}.
 
constexpr const char * ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr uint32_t EncodeChannel (const ChannelConfig &c) noexcept
 Encode a channel configuration as its CFG_CHn value (Table 11).
 
constexpr ChannelConfig DecodeChannel (uint32_t v) noexcept
 Decode a CFG_CHn value (Table 11).
 
constexpr uint32_t EncodeStatus (const Config &config, uint8_t on_mask, bool active) noexcept
 The STATUS value the driver writes (Table 10): ONCH, the masks, FREQM, CMxy and ACTIVE.
 
constexpr Status DecodeStatus (uint32_t v) noexcept
 Decode a STATUS value.
 
constexpr Result< PairMode > DecodePairMode (uint32_t status, uint8_t pair) noexcept
 Decode one pair's CMxy field of a STATUS value. The field is two bits wide but only 0 to 2 are modes (Register Details); 3 is refused, never stored as a PairMode (KB-CPP20-025).
 
constexpr Faults DecodeFaults (uint32_t v) noexcept
 Decode a FAULT value (Table 12).
 
constexpr uint32_t EncodeDpm (const DpmConfig &d) noexcept
 Encode the DPM settings as the CFG_DPM value; bits 31:15 stay 0.
 
constexpr DpmConfig DecodeDpm (uint32_t v) noexcept
 Decode a CFG_DPM value.
 
constexpr uint32_t ChopPeriodNs (MasterClock clock, ChopDivider chop) noexcept
 One chopping period, in nanoseconds: divider / fMAIN (Table 1). Exact.
 
constexpr DutyLimits DutyLimitsOf (ChopDivider chop, bool slew_rate_control) noexcept
 The duty-cycle limits the chip applies to a channel (Table 2). The chip clamps the codes by itself; the driver never moves a code into these limits, so 0 % and 100 % stay reachable.
 
constexpr Result< uint32_t > HitTimeUs (uint8_t code, MasterClock clock, ChopDivider chop) noexcept
 The HIT time of a code: code x 40 / fCHOP (Table 5). Exact.
 
constexpr Result< uint8_t > HitTimeCode (uint32_t us, MasterClock clock, ChopDivider chop) noexcept
 The HIT_T code nearest to a HIT time (Table 5).
 
constexpr uint32_t DebounceUs (uint8_t code, MasterClock clock, ChopDivider chop) noexcept
 The DPM debounce time of a code: code / fCHOP (CFG_DPM). Exact.
 
constexpr Result< uint32_t > FullScaleUa (uint32_t rref_ohm, bool half_scale) noexcept
 The full-scale current IFS = KFS x 1 V / RREF ("Full-Scale Current Setting"); HFS halves KFS.
 
constexpr Result< uint32_t > CurrentUa (uint8_t code, uint32_t rref_ohm, bool half_scale) noexcept
 The CDR peak current of a code: code / 128 x IFS (Table 4, "/ 2^7").
 
constexpr Result< uint8_t > CurrentCode (uint32_t ma, uint32_t rref_ohm, bool half_scale) noexcept
 The CDR code nearest to a peak current: current x 128 / IFS (Table 4).
 
constexpr Result< uint8_t > DpmCurrentCode (uint32_t ma, uint32_t rref_ohm, uint8_t max_code) noexcept
 The DPM_ISTART or DPM_IPTH code nearest to a current: current x 127 / IFS (CFG_DPM; note 127 here, 128 in Table 4). IFS with HFS = 0: the datasheet does not say that HFS scales DPM.
 
constexpr bool ValidCode (uint8_t code, DriveMode drive) noexcept
 Check a HIT or HOLD code against its channel's drive mode.
 
constexpr bool ValidHighSide (const ChannelConfig &c) noexcept
 Check what the high side lacks ("Low-Side/High-Side Operations (HSnLS)").
 
constexpr Error ValidateChannel (const ChannelConfig &c, MasterClock clock) noexcept
 Check one channel's configuration without touching the chip.
 
constexpr bool ValidLoadDiagnostics (const ChannelConfig &c, uint8_t loaded_channels, uint8_t channel) noexcept
 Check that a channel enables a load-dependent diagnostic only when a load is declared on it (handbook KB-CPP-131).
 
constexpr Error Validate (const Config &config) noexcept
 Check a configuration without touching the chip.
 
constexpr const char * GetDriverVersion () noexcept
 
constexpr uint32_t GetDriverVersionMajor () noexcept
 
constexpr uint32_t GetDriverVersionMinor () noexcept
 
constexpr uint32_t GetDriverVersionPatch () noexcept
 

Variables

constexpr uint8_t kChannels = 8
 Channels of the chip.
 
constexpr uint8_t kPairs = 4
 Channel pairs (0-1, 2-3, 4-5, 6-7).
 
constexpr uint8_t kMaxCdrCode = 126
 
constexpr uint8_t kMaxVdrCode = 100
 Highest VDR duty code: 100 is 100 % (Table 3); 101 to 127 mean the same and are refused.
 
constexpr uint8_t kHitTimeNone = 0
 HIT_T code for no HIT phase (Table 5).
 
constexpr uint8_t kMaxHitTimeCode = 254
 Highest finite HIT_T code (Table 5).
 
constexpr uint8_t kHitTimeContinuous = 255
 
constexpr uint32_t kMinRrefOhm = 15000
 Smallest RREF of the recommended range, in ohms ("Full-Scale Current Setting").
 
constexpr uint32_t kMaxRrefOhm = 100000
 Largest RREF of the recommended range, in ohms.
 
constexpr uint32_t kNoRref = 0
 
constexpr uint32_t kKfs = 15000
 KFS with HFS = 0, in A/A (Electrical Characteristics, KFS0): IFS = KFS x 1 V / RREF.
 
constexpr uint8_t kStartAttempts = 3
 Start-up attempts when the chip reports COMER (Figure 6: "repeat the procedure").
 
constexpr uint32_t kDefaultWakeTimeoutUs = 100000
 
constexpr uint32_t kMinWakeTimeoutUs = reg::kWakeUpUs
 Shortest Config::wake_timeout_us: one tWU.
 
constexpr uint32_t kMaxWakeTimeoutUs = 10000000
 Longest Config::wake_timeout_us: 10 s.
 
constexpr uint32_t kWakePollUs = 10000
 
Bus requirements

What the MAX22200 needs from the SPI bus ("SPI Detailed Description", p23; Electrical Characteristics, SPI rows, p10; Figure 1, p11). A port and a board configuration check their settings against these with static_assert (handbook KB-CPP-123).

constexpr uint8_t kSpiMode = 0
 SPI mode 0: CPOL = 0, CPHA = 0 ("SPI Detailed Description": the only mode the chip supports).
 
constexpr bool kMsbFirst = true
 
constexpr uint32_t kMaxClockHz = 10'000'000
 
constexpr uint32_t kMinCsHighNs = 30
 Shortest time CSB stays high between two transfers, tCSPW.
 
constexpr uint32_t kCsSetupNs = 30
 CSB falling edge to the first SCK rising edge, tCSS.
 
constexpr uint32_t kCsHoldNs = 30
 Last SCK edge to CSB rising, tCSH.
 
constexpr bool kContinuousWord = false
 
constexpr uint32_t kCmdSetupNs = 20
 
constexpr std::array< std::size_t, 2 > kTransferBytes = {1, 4}
 
constexpr bool kSdoOpenDrain = true
 SDO is open drain (Pin Description): the board fits a pull-up.
 

Detailed Description

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

Enumeration Type Documentation

◆ CtrlPin

enum class max22200::CtrlPin : uint8_t
strong

The chip's control pins the port drives or reads.

Enumerator
Enable 

ENABLE, active high: ACTIVE wakes the chip, INACTIVE puts it to sleep (< 11 µA).

Cmd 

CMD, active high: ACTIVE while the Command Register is written.

Fault 

FAULT, open drain, active low on the pin: read only (GpioRead), ACTIVE while an unmasked fault is present.

◆ GpioSignal

enum class max22200::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 max22200::KconfigDefaults ( )
constexprnoexcept

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

Returns
Config{} with the variant, oscillator and RREF from Kconfig.

Variable Documentation

◆ kCmdSetupNs

constexpr uint32_t max22200::kCmdSetupNs = 20
inlineconstexpr

CMD valid before the CSB falling edge that starts a transfer, tCMS. CMD must also stay high through the CSB rising edge that ends a command byte (p26); the hold time tCMH is drawn in Figure 1 with no value, so the driver changes CMD only after Transfer() has returned.

◆ kContinuousWord

constexpr bool max22200::kContinuousWord = false
inlineconstexpr

false: the datasheet sets no limit on idle SCK time between the bytes of one transfer; the chip counts the clocks while CSB is low (a wrong count of a write sets COMER, p34).

◆ kMaxClockHz

constexpr uint32_t max22200::kMaxClockHz = 10'000'000
inlineconstexpr

Highest SCK frequency: tCLK min 100 ns (Electrical Characteristics). "SPI Detailed Description" also says the interface "can operate up to 5MHz" next to the daisy chain, which this driver does not use; the SDO pull-up's RC can set a lower limit (note 2).

◆ kMsbFirst

constexpr bool max22200::kMsbFirst = true
inlineconstexpr

Each byte is clocked most significant bit first (Figure 1). The byte order differs per frame and is the driver's business: a 32-bit write goes LSB byte first, a 32-bit read comes MSB byte first (Figures 10, 11).

◆ kTransferBytes

constexpr std::array<std::size_t, 2> max22200::kTransferBytes = {1, 4}
inlineconstexpr

The transfer lengths the driver asks for, in bytes: 1 (the Command Register, an 8-bit data phase) and 4 (a 32-bit data phase). Nothing else.