API guide¶
The driver's API by task, with code that compiles: start, operation states, channels, feedback, faults, the watchdog, errors and shut-down. Section numbers refer to the datasheet, Rev. 1.2.
Datasheet sections this page relies on
From Infineon IFX-ntz1491827137291 1.2:
- Reset State, Config Mode, Mission Mode and Critical Fault: 4.3.1 TDS_IC Operation states; Figure 4, p. 19
- Channel modes and the measurement period: 4.4 Channel modes, p. 21
- Parallel channel pairs: 4.5.2 TDS_Parallel channel operation, p. 22
- Integrating current controller, Autolimit and the PWM frequency controller: 4.6.2 Integrating Current Controller (ICC); Equations 4, 5, p. 24
- Setpoint range and accuracy: 4.6.3 Electrical characteristics current control, Table 14, p. 28
- Dither waveform and its update: 4.7.1 TDS_Dither configuration; 4.7.2 TDS_Dither parameter update; Equations 6 to 9, p. 29
- ON-state and OFF-state diagnosis: 4.9.1 TDS_Overview; Figures 14, 15, p. 32
- Open load or short to ground, thresholds and warning: 4.9.2 TDS_Open Load/Short to Ground (OLSG); 4.9.3 TDS_OLSG Warning, p. 34
- Overcurrent and the OFF-state overcurrent check: 4.9.6 TDS_Overcurrent (OC); Equation 17, p. 38
- Register and OTP ECC, the self-test: 4.9.7 TDS_Register/OTP ECC; 4.9.8 TDS_Built in Self Test (BIST), p. 39
- Average current, duty cycle and VBAT feedback: 4.10.2 TDS_Average feedback values; Equations 18 to 22, p. 41
- Feedback freeze and update: 4.10.5 TDS_Update/Freeze Mechanism; Figure 22, p. 43
- Overtemperature and the temperature feedback: 4.11.1 TDS_Overtemperature protection; Equation 32, p. 45
- SPI watchdog: 5.2.2 TDS_SPI watchdog; Equation 33, p. 50
- FB_STAT, the status summary: 5.3.2.21 Feedback Status Register, p. 77
All of them, with the driver API for each: Datasheet map.
The shape of the API¶
| Group | Calls |
|---|---|
| Lifecycle | EnsureInitialized(), IsInitialized(), Deinitialize(), HardwareReset() |
| Configuration | ApplyConfig(), GetConfig(), ConfigureChannel(), SetParallel() |
| Operation state | EnterMissionMode(), EnterConfigMode(), IsMissionMode(), ReadChannelControl() |
| Channels | SetCurrent(), GetCurrentSetpoint(), EnableChannel(), DisableChannel(), SetEnabledChannels(), GetEnabledChannels(), SetDither(), StartOvercurrentCheck(), SetDrivePin() |
| Feedback | ReadChannelFeedback(), ReadSupply() |
| Diagnosis | ReadStatus(), ReadFaults(), ClearFaults(), ClearChannelFaults(), GetLatchedFaults(), ClearLatchedFaults(), GetStartupFaults(), ReadFaultPin(), ReadPinStatus(), RunBist() |
| Watchdog | ReloadWatchdog() |
| Identification | GetIcVersion(), ReadChipId(), tle92466ed::GetDriverVersion() |
| Raw access | ReadRegister(), GetLastReply(), GetLastCriticalFault(), GetBusDiagnostics(), IsResetWatchArmed() |
Every call that touches the chip returns Result<T>: check ok() (or the bool conversion) and read value, or
read error. Result is [[nodiscard]], so an unchecked call is a compiler warning. Setters take a trailing
Verify verify = Verify::None: Verify::ReadBack reads the written register back (two more frames each) and
returns WriteMismatch when the chip did not take the value.
Start and enter Mission Mode¶
tle92466ed::Error BringUp(Driver& driver) {
// The one entry point: starts the chip on the first call, then returns Ok with no I/O. After a
// failure the next call starts again from the beginning. It ends in Config Mode.
if (const auto r = driver.EnsureInitialized(); !r) {
std::printf("TLE92466ED init: %s\n", tle92466ed::ToString(r.error));
return r.error;
}
return driver.EnterMissionMode().error; // MissionBlocked: a supply, clock or watchdog fault
}
The constructor stores the port and the configuration (Config{} unless you pass one) and does no I/O.
EnsureInitialized() is the one way to start the chip (Contract lists its steps); it ends
in Config Mode with every channel off. Once it has succeeded it returns Ok at once with no I/O, so a caller can
call it before every use. After a failure the driver stays uninitialised and the next call starts again.
The chip has four operation states (section 4.3.1, Figure 4):
| State | What works | The driver |
|---|---|---|
| Reset | Nothing; registers return to their reset values | RESN low in EnsureInitialized() and HardwareReset() |
| Config Mode | Registers; every channel off; MODE, GLOBAL_CONFIG, CLK_DIV, CH_PAR and SFF_BIST writable only here | EnsureInitialized() ends here; EnterConfigMode(); ApplyConfig(), ConfigureChannel(), SetParallel(), RunBist() |
| Mission Mode | Channels switch; their diagnosis runs; EN_CH settable only here | EnterMissionMode(); EnableChannel(), StartOvercurrentCheck() |
| Critical Fault | Every reply is a critical fault frame; FAULTN low | A critical fault frame confirmed by a second one is CriticalFault: EN low, the driver uninitialised; EnsureInitialized() (with RESN) or a power cycle leaves it |
EnterMissionMode() checks the entry conditions of Figure 4 first and returns MissionBlocked, writing nothing,
while INIT_DONE is 0 or one fails: FB_STAT (SPI watchdog, clock, central temperature, VDD, VIO, VBAT or an internal
supply), the DIAG_ERR_CHGR and DIAG_WARN_CHGR groups FB_STAT flags (a channel OTE or OTW) and GLOBAL_DIAG2
(REG_ECC_ERR). VPRE_OV blocks entry too, a fail-safe choice beyond Figure 4. Then it drives EN high, sets OP_MODE
and reads CH_CTRL back, always: a chip that refused is MissionBlocked, and IsMissionMode() says what the chip
did. A supply, clock or watchdog fault later drops the chip back to Config Mode on its own and clears every EN_CH
(sections 4.1.2, 4.2.2, 5.2.2); a channel fault clears that channel's EN_CH (4.9.2 to 4.9.6). The driver never
writes CH_CTRL from a copy the chip may have changed: every enable change reads CH_CTRL first.
Drive a channel¶
tle92466ed::Error Energise(Driver& driver, uint32_t microamps) {
const auto set = driver.SetCurrent(Channel::Ch0, microamps); // checked, never clamped
if (!set) {
return set.error; // InvalidArgument above 1.5 A, or with dither above 1.8 A
}
std::printf("programmed %lu uA\n", static_cast<unsigned long>(set.value)); // TARGET rounding
return driver.EnableChannel(Channel::Ch0, tle92466ed::Verify::ReadBack).error;
}
SetCurrent() sets the average current of the integrating current controller (sections 4.6.1, 4.6.2). The value
is checked against the operating range of Table 14 and refused, never clamped: up to 1.5 A, up to 1.8 A with the
configured dither amplitude, and above the dither amplitude when it is not 0 (section 4.7.1). The master of a
parallel pair takes up to 2.43 A with dither (kMaxParallelSetpointUa: Table 14's 2.7 A includes the overshoot,
and the driver keeps the single channel's 90 % headroom), and its TARGET step doubles to 122 µA (section 4.5.2).
SetParallel() sets the master's setpoint to 0 when it joins a pair. The call
returns the current actually programmed, rounded to the TARGET step; GetCurrentSetpoint() returns it with no
I/O. Setpoints may be written in either state: the channel switches once it is enabled in Mission Mode.
EnableChannel(), DisableChannel() and SetEnabledChannels() read CH_CTRL, then write it whole with only the
EN_CH bits they name changed: enabling one channel never switches another off, a channel a fault switched off is
never switched back on, and OP_MODE is never set (only EnterMissionMode() sets it). An enable that finds the chip
back in Config Mode is MissionBlocked. Switching off never depends on that read: when it fails, a disable (or
any mask that only clears) still writes CH_CTRL from the copy with the channels cleared and returns the read's
error, and EnterConfigMode() drives EN low whatever the SPI result. Section 5.2.1 does not say whether a write's reply
carries CH_CTRL before or after the write, so the copy holds an EN_CH or OP_MODE bit only when both the value
written and the reply have it: GetEnabledChannels() can under-report a channel that is on until the next read,
never report one that is off. Channels the driver wrote on that a validated read of CH_CTRL (the read before every
channel call, or Verify::ReadBack) finds off are logged and kept in GetDroppedChannels() until
ClearDroppedChannels() or the next start; a refused EnterMissionMode() drives EN low again. A
channel must be declared loaded in its ChannelConfig and must not be a slave. The chip keeps a channel
switched off by a fault off until its flags are cleared and EN_CH is set again (sections 4.9.2 to 4.9.6);
Verify::ReadBack finds such a channel as WriteMismatch, and the driver's copy then shows it off.
SetDither() changes a channel's dither while it runs: DITHER_CLK_DIV takes effect at once, DITHER_STEP and
DITHER_CTRL at the next dither period after the DITHER_CTRL write (section 4.7.2). The dither period is also the
feedback measurement period in current control and direct drive (section 4.4.2).
Read the feedback¶
void SampleCurrent(Driver& driver) {
const auto fb = driver.ReadChannelFeedback(Channel::Ch0); // freeze, read, release (4.10.5)
if (fb.error == tle92466ed::Error::NotReady) {
return; // no new measurement period yet: never a 0 mA reading
}
if (fb) {
std::printf("%ld uA, duty %lu/10000\n", static_cast<long>(fb.value.average_current_ua),
static_cast<unsigned long>(fb.value.duty_permyriad));
}
}
ReadChannelFeedback() reads one measurement period under the freeze of section 4.10.5: average current (signed,
the pair's sum on a master), duty cycle, VBAT, the measurement period, the minimum and maximum current and PWM
period, and the fast-feedback counters. With no new values since the last read it returns NotReady after two
frames; with no measurement period at all (TP_MANT = 0, as with a dither clock of 0) it returns NotReady too,
never a current of 0. The conversions use f_SYS of the configuration. ReadSupply() reads VIO, VDD, VBAT and the
central temperature (±20 °C uncalibrated, Table 16).
Faults¶
void ServiceFaults(Driver& driver) {
const auto f = driver.ReadFaults(); // every diagnosis register, ORed into the latch
if (!f || !f.value.Any()) {
return;
}
const tle92466ed::ChannelFaults ch0 = f.value.Of(Channel::Ch0);
if (ch0.open_load || ch0.short_to_ground || ch0.olsg) {
std::printf("CH0 load fault\n");
}
// The chip keeps a faulted channel off until its flags are cleared and EN_CH is set again.
if (driver.ClearChannelFaults(Channel::Ch0)) {
(void)driver.EnableChannel(Channel::Ch0);
}
}
| Call | I/O | What it gives |
|---|---|---|
ReadStatus() |
2 frames | FB_STAT: INIT_DONE, the global faults, and a bit per channel group with an error or warning |
ReadFaults() |
18 frames | GLOBAL_DIAG0..2, DIAG_ERR_CHGR0..2, DIAG_WARN_CHGR0..2 as Faults; Has() and Of() decode them |
ClearFaults() |
18 frames, 2 more per register with a flag (4 with OC or OTP_ECC_ERR) | Every register read and latched, then exactly the flags read cleared: rwh flags by a 1, rw flags by a 0, OC and OTP_ECC_ERR twice; OTP_VIRGIN never |
ClearChannelFaults(ch) |
4 frames, 2 more per write | The group read and latched (both channels), then this channel's flags that read 1 cleared |
GetLatchedFaults() |
none | Every flag any read of a diagnosis register saw since ClearLatchedFaults() |
GetStartupFaults() |
none | The diagnosis registers as the start-up found them, before it cleared them |
ReadFaultPin() |
GpioRead() |
FAULTN: low on Critical Fault, RESN low or an unmasked fault |
ReadPinStatus() |
2 frames | PIN_STAT: DRV0, DRV1, EN, the internal fault state and the FAULTN level |
The diagnosis runs only in Mission Mode (section 4.9.1). In ON state the shunt current shows an open load or a
short to ground only together, as OLSG, below the open-load threshold; in OFF state (EN_CH set with setpoint 0, or
a setpoint with EN_CH cleared) the current sources of Figure 14 tell OL from SG. Use both. OLSG_WARN_CHK_NOK is
cleared by reading DIAG_WARN_CHGR (section 4.9.3): the latch keeps it. StartOvercurrentCheck() runs the
OFF-state overcurrent check of section 4.9.6 once, on a channel that is off with setpoint 0 and not asked on since
the last read of CH_CTRL (after a refused enable, call ReadChannelControl() first); read the result with
ReadFaults() after t_OCon. The channel then stays enabled with setpoint 0, the OFF-state diagnosis condition.
RunBist() runs the safety flip-flop self-test in Config Mode (section 4.9.8) and clears the REG_ECC_ERR it sets
on purpose.
The SPI watchdog¶
void ControlTick(Driver& driver) {
// With Config::spi_watchdog, a missed reload ends Mission Mode and turns every channel off.
if (const auto r = driver.ReloadWatchdog(); !r) {
std::printf("watchdog reload: %s\n", tle92466ed::ToString(r.error));
}
}
With Config::spi_watchdog, the chip counts WD_TIME down at f_SYS / 2^14 (0.585 ms per count) and, at 0, sets
SPI_WD_ERR, ends Mission Mode and switches every channel off (section 5.2.2). EnsureInitialized() writes
Config::watchdog_reload to WD_RELOAD before it enables the watchdog, since the reset value of 1 would expire at
once. ReloadWatchdog() writes it again; call it faster than the timeout. WD_TIME is 11 bits: at most 2047 counts,
1.198 s. After an expiry, a reload clears SPI_WD_ERR, ClearFaults() the latched flag, and EnterMissionMode()
works again.
Handle errors¶
const char* Describe(tle92466ed::Error e) {
switch (e) {
case tle92466ed::Error::Bus:
case tle92466ed::Error::NoDevice:
return "check SPI wiring, VIO and the chip select";
case tle92466ed::Error::CriticalFault:
return "internal supply or clock fault: reset the chip";
case tle92466ed::Error::Crc:
case tle92466ed::Error::ReplyMismatch:
return "signal integrity: lower SCK, check CSN high time";
default:
return tle92466ed::ToString(e);
}
}
| Signal | Meaning | What to do |
|---|---|---|
Error::Bus |
The port failed a transfer, a pin write or the bus bring-up | Check the port and the wiring; retry |
Error::NoDevice |
MISO stuck low or high, or MOSI looped back | VIO, SO, CSN and the chip's supplies |
Error::Crc, ReplyMismatch, FrameRejected |
A frame was corrupted, lost or ignored | SPI mode 1, the clock, CSN high time; a shared bus lock |
Error::Timeout |
INIT_DONE never read 1, or the self-test did not finish | VDD, RESN, the clock source |
Error::DeviceIdMismatch |
ICVID is not a TLE92466ED | The part, the chip select |
Error::DeviceFault |
OTP not programmed, or an internal bus fault | Replace the part |
Error::CriticalFault |
Internal supply or clock fault, confirmed by a second frame; EN is low | GetLastCriticalFault(), then EnsureInitialized() (RESN) |
Error::MissionBlocked |
A fault holds the chip in Config Mode, or it left Mission Mode on its own | ReadFaults(), fix the cause, ClearFaults(), EnterMissionMode() |
Error::WrongState |
The call needs the other state, the channel is a slave, or an earlier write failed and the chip may hold either value (see the contract, "Ambiguous writes") | Change state first; after a failed write, repeat it or ReadChannelControl() |
Error::WriteMismatch |
The chip did not take a write | A latched fault, the state, or a lost frame: read the faults |
Error::NotReady |
No feedback to report | Wait one measurement period; configure the dither clock |
Error::UnexpectedReset |
The chip reset behind the driver's back; EN is low | EnsureInitialized() configures it again |
Error::Unsupported |
The port lacks the hook | Add GpioSet() or GpioRead() |
Every value is on the Contract page. tle92466ed::ToString() names an error for a log.
Raw access and counters¶
For bring-up and fault finding (handbook KB-CPP-129):
| Call | I/O | What it gives |
|---|---|---|
ReadRegister(address) |
2 frames, no retry | The 16 or 22 data bits of any register of Tables 19 and 24; a diagnosis register read here feeds the latch, and DIAG_WARN_CHGR clears OLSG_WARN_CHK_NOK on the chip |
GetLastReply() |
none | The last 32-bit word clocked in as a reply, by any call |
GetLastCriticalFault() |
none | The flags byte of the last critical fault frame |
GetBusDiagnostics() |
none | Frames sent, reads retried, replies rejected, resyncs |
GetDroppedChannels() |
none | Channels the chip switched off on its own, bit x for channel x; ClearDroppedChannels() empties it |
IsResetWatchArmed() |
none | Whether every FB_STAT anchor checks for a chip reset |
Shut down¶
void PowerDown(Driver& driver) {
if (auto r = driver.Deinitialize(); !r) { // Config Mode, every channel off, EN low
std::printf("TLE92466ED shutdown write failed: %s\n", tle92466ed::ToString(r.error));
}
}
After Deinitialize() every call returns NotInitialized until the next EnsureInitialized(), which starts the
chip again from the beginning: Deinitialize() then EnsureInitialized() is also the recovery after a fault.
Next: Configuration.