Contract¶
What the TMC9660 driver promises, what it needs, and the rules a caller follows.
The driver inherits the Kokeb Labs driver contract; this page states only what is specific to it. A change to anything here is a breaking change, listed under Breaking in the changelog.
Promises¶
- The constructor is
noexcept, stores the configuration, does no I/O and cannot fail. EnsureInitialized()is the only way to start the driver. Its first call checks the stored configuration (InvalidArgument, nothing sent), brings the bus up, optionally pulses RSTN (Config::hardware_reset, needsGpioSet()), and checks the chip identity in the mode the chip is expected to be in. On any failure the driver stays uninitialised and the next call starts again; once it has succeeded, later calls returnOkwith no I/O.- Every call that touches the chip returns
Error::NotInitializedbeforeEnsureInitialized()succeeds and after a reset the driver detected. No call initialises or resets the chip as a side effect. - A call that belongs to another mode returns
Error::WrongModeand sends nothing. - Every argument is checked against the datasheet tables before a byte is sent; a bad one returns
Error::InvalidArgumentand sends nothing. - A safety guard that says no returns
Error::Refusedand sends nothing, or leaves the chip as it was. - Nothing energises by accident, a stop is never refused, and no write follows a reset the driver could have seen: Safety lists each rule and its test.
- Every port failure propagates as
Error::Bus; no getter returns a stale or zero value after a failed read, and a value from a reply that failed its check is discarded (Error::BadReply,Error::Crc). - Every wait is bounded: the boot wait by
Config::boot_timeout_ms(each failed identity poll is charged the 10 ms pause and, on UART,reply_timeout_us,uart_resync_usand the three 5 ms drains it can take), the SPI reply byConfig::spi_reply_retries, the UART reply byConfig::reply_timeout_us, the PLL by a fixed number of polls. Config{}is the chip's reset configuration.- A missing
DelayUs()is a compile error; a missingGpioSet()makesConfig::hardware_resetreturnError::Unsupported; a missingGpioGet()orLog()does nothing. A misdeclared hook is a compile error. Deinitialize()always sends the full stop (DRV_EN low,COMMUTATION_MODE0 or the register-mode zeroes), also after a reported reset or before any start, and then leaves the driver uninitialised. The stop speaks the protocol the driver last proved (GetMode()): a failedEnsureInitialized()keeps it. Before any start it is the protocol ofConfig::mode; on SPI a parameter-mode stop that reaches a chip in register mode is read by it as a register frame; which registers that frame addresses depends on the register SPI layout (A3: 9-bit offsets in the table, block 1 offset 9 and block 63 offset 0x100; with the wide layout the same bits are MCC offsets 0x104, 0x109 and 0x22b, or RAMDebug 0x300). The datasheet does not say what such a write does, so this is a bench item, not a proved fact. A start of the application whose write fails (a lost, late, corrupt or BUSY reply) is followed as if it happened: the driver adopts the application, or finds the bootloader still answering and stays in it, or leaves the driver uninitialised in the application's protocol. With no proved protocol in bootloader mode and noGpioSet()hook it returnsNotInitialized, never a silentOk. In bootloader mode without a hook it isOkonly when the bootloader still answers its chip type. If it does not (a timeout, a bad frame, a wrong chip type; BUSY, an error status and a seen reset are the bootloader answering and change nothing), the chip may run an application that an unseen restart started: the driver becomes uninitialised, speaks that application's protocol from then on, sends its stop once, best effort, and still returns the error. The application is the one BOOT_MODE names in the configuration read at adoption (nothing was written since the reset, so that is what the OTP loaded, and after a restart the OTP decides) or in the lastBlReadConfig(); with none named it is the protocol ofConfig::mode. A protocol stop is sent before a UART line is resynchronised, so it is never delayed byConfig::uart_resync_us; the bootloader chip-type check is, after an earlier failed exchange. The stop never returnsOkwhile the PWM may still be driven: without aGpioSet()hook it also makes sureIDLE_MOTOR_PWM_BEHAVIORis 1 (PM "System Off"), andSetParam(IDLE_MOTOR_PWM_BEHAVIOR, 0)isRefusedunlessConfig::allow_pwm_in_system_offis set.- UART
Exchange(): a call withtx_len == 0sends nothing and discards what is waiting on the line (at mostrx_lenbytes, withintimeout_us); the driver uses it to drain a late reply after a failed exchange, after waitingConfig::uart_resync_us. A call with data must discard stale received bytes before it sends. The driver passes its own member buffers, so the bytes live for the whole call.
Depends on¶
| Dependency | Version | Why |
|---|---|---|
| A C++20 compiler | GCC 10, Clang 13 or later | Concepts constrain the port |
| CMake | 3.16 or later | Generates tmc9660_version.h |
| Your port | The bus, within the bus requirements; the delay; optionally RSTN, DRV_EN, WAKE and FAULTN; and logging (Porting) |
Nothing else: no RTOS, no SDK, no other repository of the org. The public headers include only <algorithm>,
<array>, <bit>, <concepts>, <cstddef>, <cstdint>, <limits>, <span>, <type_traits> and <utility>.
Threading¶
The driver is not thread-safe and takes no lock. Use each driver object from one task at a time, or guard every call on it with one mutex; the layer that owns the driver owns that lock, and the bus lock when several chips share a bus. Nothing may run in an ISR: every call can block for a bus transfer or a delay. Separate objects share no state.
Errors¶
tmc9660::Error inside tmc9660::Result<T>. Values 0 to 9 are the shared base set; values from 16 are specific to
this driver.
Error |
Value | Returned when |
|---|---|---|
Ok |
0 | The call succeeded |
NotInitialized |
1 | EnsureInitialized() has not succeeded, Deinitialize() ran, or a reset was detected |
InvalidArgument |
2 | A Config field or an argument is out of range; nothing was sent |
Bus |
3 | A port hook returned false or BusStatus::Fault |
Timeout |
4 | No reply, the chip did not become ready, or the PLL did not lock |
DeviceIdMismatch |
5 | The chip ID is not 0x544D0001 |
Crc |
6 | The CRC-8 of a bootloader UART reply does not match |
Busy |
7 | The bootloader answered BUSY and the retries ran out |
DeviceFault |
8 | A latched error flag forbids the call |
Unsupported |
9 | A register offset the SPI layout cannot reach (A3), or hardware_reset without GpioSet() |
UnexpectedReset |
16 | The chip reset since the last validated reply; the driver is uninitialised |
Nack |
17 | The chip answered with an error status |
WrongMode |
18 | The call belongs to another mode than the chip is in |
Refused |
19 | A safety guard said no |
VerifyFailed |
20 | A read back after a write did not match |
BadReply |
21 | A reply failed its checksum, address or opcode check |
The API guide says what to do about each.
Memory¶
No heap, no exceptions, no RTTI, no std::function, no std::string, no printf and no static mutable state. A
driver object holds a reference to the port, a Config, two 9-byte frame buffers and a few flags: 96 bytes on a 64-bit
host (Config is 44 bytes of it). The frame buffers are members, never locals, so a port that hands them to DMA has
them for the whole call. The parameter and register tables are constexpr and live in flash.
Platform¶
Platform-free: the same code runs on any target with a C++20 compiler, including the host tests. The ESP-IDF port
in examples/esp32 is an example, not part of the driver.
Deviations from the standard¶
One. The standard's setters take a trailing Verify verify = Verify::None argument; this driver does not: a parameter
write is checked by the chip's reply, a register write by the energising guard, and a configuration write by reading it
back. The gap is recorded in Ambiguities and unverified items.