TMC9660 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
tmc9660_bootconfig.hpp
Go to the documentation of this file.
1
14#ifndef TMC9660_BOOTCONFIG_HPP
15#define TMC9660_BOOTCONFIG_HPP
16
17#include <array>
18#include <cstddef>
19#include <cstdint>
20#include <span>
21
22#include "tmc9660_detail.hpp"
23#include "tmc9660_frames.hpp"
24#include "tmc9660_types.hpp"
25
26namespace tmc9660 {
27
107
108namespace detail {
110template <>
111struct EnumLast<BootField> {
113 static constexpr BootField kValue = BootField::MemParameters;
114};
115
118struct BootFieldInfo {
119 uint8_t offset;
120 uint8_t shift;
121 uint8_t width;
122};
123
125inline constexpr std::array<BootFieldInfo, 76> kBootFields{{
126 {.offset = 0, .shift = 0, .width = 2}, {.offset = 0, .shift = 2, .width = 2},
127 {.offset = 0, .shift = 4, .width = 2}, {.offset = 0, .shift = 6, .width = 2},
128 {.offset = 0, .shift = 8, .width = 1}, {.offset = 2, .shift = 0, .width = 8},
129 {.offset = 2, .shift = 8, .width = 8}, {.offset = 4, .shift = 0, .width = 8},
130 {.offset = 4, .shift = 8, .width = 8}, {.offset = 6, .shift = 0, .width = 1},
131 {.offset = 6, .shift = 1, .width = 1}, {.offset = 6, .shift = 2, .width = 1},
132 {.offset = 6, .shift = 3, .width = 1}, {.offset = 6, .shift = 4, .width = 1},
133 {.offset = 6, .shift = 5, .width = 2}, {.offset = 6, .shift = 7, .width = 3},
134 {.offset = 6, .shift = 10, .width = 1}, {.offset = 8, .shift = 0, .width = 2},
135 {.offset = 8, .shift = 2, .width = 1}, {.offset = 8, .shift = 3, .width = 1},
136 {.offset = 8, .shift = 8, .width = 1}, {.offset = 8, .shift = 9, .width = 1},
137 {.offset = 8, .shift = 12, .width = 1}, {.offset = 10, .shift = 0, .width = 1},
138 {.offset = 10, .shift = 3, .width = 5}, {.offset = 10, .shift = 8, .width = 4},
139 {.offset = 12, .shift = 0, .width = 1}, {.offset = 12, .shift = 1, .width = 2},
140 {.offset = 12, .shift = 3, .width = 2}, {.offset = 12, .shift = 5, .width = 3},
141 {.offset = 12, .shift = 8, .width = 3}, {.offset = 14, .shift = 0, .width = 16},
142 {.offset = 16, .shift = 0, .width = 16}, {.offset = 18, .shift = 0, .width = 16},
143 {.offset = 20, .shift = 0, .width = 16}, {.offset = 22, .shift = 0, .width = 3},
144 {.offset = 22, .shift = 3, .width = 3}, {.offset = 22, .shift = 6, .width = 3},
145 {.offset = 22, .shift = 9, .width = 3}, {.offset = 22, .shift = 12, .width = 4},
146 {.offset = 24, .shift = 0, .width = 7}, {.offset = 24, .shift = 8, .width = 1},
147 {.offset = 24, .shift = 9, .width = 3}, {.offset = 24, .shift = 12, .width = 1},
148 {.offset = 24, .shift = 13, .width = 1}, {.offset = 24, .shift = 16, .width = 2},
149 {.offset = 24, .shift = 18, .width = 5}, {.offset = 24, .shift = 23, .width = 2},
150 {.offset = 32, .shift = 0, .width = 1}, {.offset = 32, .shift = 4, .width = 2},
151 {.offset = 32, .shift = 6, .width = 2}, {.offset = 32, .shift = 8, .width = 2},
152 {.offset = 32, .shift = 1, .width = 1}, {.offset = 32, .shift = 10, .width = 2},
153 {.offset = 32, .shift = 12, .width = 2}, {.offset = 32, .shift = 14, .width = 2},
154 {.offset = 34, .shift = 0, .width = 2}, {.offset = 34, .shift = 2, .width = 2},
155 {.offset = 34, .shift = 4, .width = 3}, {.offset = 34, .shift = 8, .width = 1},
156 {.offset = 34, .shift = 9, .width = 2}, {.offset = 34, .shift = 11, .width = 1},
157 {.offset = 34, .shift = 12, .width = 1}, {.offset = 34, .shift = 13, .width = 1},
158 {.offset = 34, .shift = 14, .width = 2}, {.offset = 36, .shift = 4, .width = 1},
159 {.offset = 36, .shift = 5, .width = 5}, {.offset = 36, .shift = 12, .width = 1},
160 {.offset = 36, .shift = 13, .width = 2}, {.offset = 38, .shift = 0, .width = 1},
161 {.offset = 38, .shift = 1, .width = 1}, {.offset = 38, .shift = 2, .width = 2},
162 {.offset = 38, .shift = 4, .width = 4}, {.offset = 38, .shift = 8, .width = 2},
163 {.offset = 40, .shift = 0, .width = 2}, {.offset = 40, .shift = 2, .width = 2},
164}};
165static_assert(kBootFields.size() ==
166 (static_cast<std::size_t>(ToUnderlying(EnumLast<BootField>::kValue)) + 1U));
167} // namespace detail
168
176public:
178 static constexpr std::size_t kBytes = 64;
180 static constexpr std::size_t kWords = 16;
181
183 constexpr BootConfig() noexcept = default;
184
189 explicit constexpr BootConfig(const std::array<uint32_t, kWords>& words) noexcept
190 : words_(words) {}
191
199 [[nodiscard]] constexpr Error Set(BootField field, uint32_t value) noexcept {
200 if (!detail::IsEnumerator(field)) {
202 }
203 const detail::BootFieldInfo info = fieldInfo(field);
204 if (value > maxValue(info)) {
206 }
207 const uint32_t shift = bitShift(info);
208 const uint32_t mask = maxValue(info) << shift;
209 uint32_t& word = words_[wordIndex(info)];
210 word = (word & ~mask) | ((value << shift) & mask);
211 return Error::Ok;
212 }
213
219 [[nodiscard]] constexpr uint32_t Get(BootField field) const noexcept {
220 if (!detail::IsEnumerator(field)) {
221 return 0U;
222 }
223 const detail::BootFieldInfo info = fieldInfo(field);
224 return (words_[wordIndex(info)] >> bitShift(info)) & maxValue(info);
225 }
226
232 [[nodiscard]] static constexpr uint32_t MaxOf(BootField field) noexcept {
233 return detail::IsEnumerator(field) ? maxValue(fieldInfo(field)) : 0U;
234 }
235
241 [[nodiscard]] constexpr uint32_t Word(std::size_t index) const noexcept {
242 return (index < kWords) ? words_[index] : 0U;
243 }
244
251 [[nodiscard]] constexpr Error SetWord(std::size_t index, uint32_t value) noexcept {
252 if (index >= kWords) {
254 }
255 words_[index] = value;
256 return Error::Ok;
257 }
258
260 [[nodiscard]] constexpr const std::array<uint32_t, kWords>& Words() const noexcept {
261 return words_;
262 }
263
270 [[nodiscard]] constexpr Error CheckStart() const noexcept {
271 const uint32_t mode = Get(BootField::BootMode);
272 if (Get(BootField::StartMotorCtrl) == 0U) {
273 return Error::Ok;
274 }
275 if ((mode != static_cast<uint32_t>(BootMode::Register)) &&
276 (mode != static_cast<uint32_t>(BootMode::Parameter))) {
277 return Error::Refused;
278 }
279 if (Get(BootField::ClockPllOutSel) != 1U) {
280 return Error::Refused;
281 }
282 if (Get(BootField::ClockSysClkDiv) != 0U) {
283 return Error::Refused;
284 }
285 return Error::Ok;
286 }
287
294 [[nodiscard]] friend constexpr bool operator==(const BootConfig& lhs,
295 const BootConfig& rhs) noexcept {
296 return lhs.words_ == rhs.words_;
297 }
298
299private:
300 [[nodiscard]] static constexpr detail::BootFieldInfo fieldInfo(BootField f) noexcept {
301 return detail::kBootFields[static_cast<std::size_t>(detail::ToUnderlying(f))];
302 }
303 [[nodiscard]] static constexpr uint32_t maxValue(const detail::BootFieldInfo& i) noexcept {
304 return (uint32_t{1} << i.width) - 1U;
305 }
306 [[nodiscard]] static constexpr std::size_t wordIndex(const detail::BootFieldInfo& i) noexcept {
307 return static_cast<std::size_t>(i.offset / 4U);
308 }
309 [[nodiscard]] static constexpr uint32_t bitShift(const detail::BootFieldInfo& i) noexcept {
310 return (static_cast<uint32_t>(i.offset % 4U) * 8U) + i.shift;
311 }
312
313 std::array<uint32_t, kWords> words_{};
314};
315
317inline constexpr uint32_t kConfigMemAddress = 0x0002'0000U;
319inline constexpr std::size_t kClockWordIndex = 6;
321inline constexpr std::size_t kBootModeWordIndex = 2;
323inline constexpr std::size_t kLdoWordIndex = 0;
324
327 std::array<uint8_t, 12> name{};
328 uint8_t type{2};
329 bool writable{false};
330 uint32_t offset{0};
331 uint32_t size{
332 0};
333};
334
336inline constexpr std::size_t kPartitionHeaderBytes = 16;
338inline constexpr std::size_t kPartitionEntryBytes = 24;
339
340namespace detail {
341
343[[nodiscard]] constexpr bool PartitionsValid(std::span<const PartitionEntry> entries,
344 uint64_t sector) noexcept {
345 for (std::size_t i = 0U; i < entries.size(); ++i) {
346 const PartitionEntry& e = entries[i];
347 if (((e.type != 2U) && (e.type != 4U)) || (e.size == 0U) || ((e.offset % sector) != 0U) ||
348 ((e.size % sector) != 0U) || ((e.type == 2U) && (e.size < 0x400U))) {
349 return false;
350 }
351 for (std::size_t j = 0U; j < i; ++j) {
352 const PartitionEntry& o = entries[j];
353 const uint64_t a0 = e.offset;
354 const uint64_t a1 = a0 + e.size;
355 const uint64_t b0 = o.offset;
356 const uint64_t b1 = b0 + o.size;
357 if ((a0 < b1) && (b0 < a1)) {
358 return false;
359 }
360 }
361 }
362 return true;
363}
364
366constexpr void PutLe32(std::span<uint8_t> out, std::size_t at, uint32_t v) noexcept {
367 out[at] = static_cast<uint8_t>(v);
368 out[at + 1U] = static_cast<uint8_t>(v >> 8U);
369 out[at + 2U] = static_cast<uint8_t>(v >> 16U);
370 out[at + 3U] = static_cast<uint8_t>(v >> 24U);
371}
372
374constexpr void WritePartitionEntries(std::span<const PartitionEntry> entries,
375 std::span<uint8_t> out) noexcept {
376 for (std::size_t i = 0U; i < entries.size(); ++i) {
377 const std::size_t at = kPartitionHeaderBytes + (kPartitionEntryBytes * i);
378 for (std::size_t k = 0U; k < 12U; ++k) {
379 out[at + k] = entries[i].name[k];
380 }
381 out[at + 12U] = static_cast<uint8_t>(entries[i].type | (entries[i].writable ? 0x80U : 0U));
382 PutLe32(out, at + 16U, entries[i].offset);
383 PutLe32(out, at + 20U, entries[i].size);
384 }
385}
386
387} // namespace detail
388
401 std::span<const PartitionEntry> entries, uint8_t size_index, uint8_t sector_index,
402 std::span<uint8_t> out) noexcept {
403 const std::size_t total = kPartitionHeaderBytes + (kPartitionEntryBytes * entries.size());
404 if (entries.empty() || (out.size() < total) || (size_index > 31U) || (sector_index > 31U)) {
406 }
407 const uint64_t sector = (sector_index == 0U) ? 1ULL : (1ULL << sector_index);
408 if (!detail::PartitionsValid(entries, sector)) {
410 }
411 for (std::size_t i = 0U; i < total; ++i) {
412 out[i] = 0U;
413 }
414 detail::PutLe32(out, 0U, static_cast<uint32_t>(total));
415 out[8] = static_cast<uint8_t>(0xFE);
416 out[9] = static_cast<uint8_t>(0xCA);
417 out[10] = static_cast<uint8_t>(1);
418 out[11] = static_cast<uint8_t>(1);
419 out[12] = size_index;
420 out[13] = sector_index;
421 detail::WritePartitionEntries(entries, out);
422 detail::PutLe32(out, 4U, detail::Crc32(std::span<const uint8_t>{out}.subspan(8U, total - 8U)));
423 return Result<std::size_t>::Success(total);
424}
425
426} // namespace tmc9660
427
428#endif // TMC9660_BOOTCONFIG_HPP
The 64-byte configuration memory of the bootloader, as 16 little-endian 32-bit words.
Definition tmc9660_bootconfig.hpp:175
constexpr uint32_t Get(BootField field) const noexcept
The value of a field.
Definition tmc9660_bootconfig.hpp:219
constexpr uint32_t Word(std::size_t index) const noexcept
One raw word.
Definition tmc9660_bootconfig.hpp:241
constexpr const std::array< uint32_t, kWords > & Words() const noexcept
Definition tmc9660_bootconfig.hpp:260
constexpr Error CheckStart() const noexcept
Check the rules that make a configuration unsafe to apply: the application must not start with a rese...
Definition tmc9660_bootconfig.hpp:270
constexpr Error Set(BootField field, uint32_t value) noexcept
Set a field.
Definition tmc9660_bootconfig.hpp:199
constexpr BootConfig() noexcept=default
All zero. A configuration for the chip comes from BlReadConfig(), not from here.
static constexpr uint32_t MaxOf(BootField field) noexcept
The largest value a field holds.
Definition tmc9660_bootconfig.hpp:232
friend constexpr bool operator==(const BootConfig &lhs, const BootConfig &rhs) noexcept
Equality of all words.
Definition tmc9660_bootconfig.hpp:294
static constexpr std::size_t kWords
Number of 32-bit words.
Definition tmc9660_bootconfig.hpp:180
static constexpr std::size_t kBytes
Size of the configuration memory in bytes.
Definition tmc9660_bootconfig.hpp:178
constexpr Error SetWord(std::size_t index, uint32_t value) noexcept
Replace one raw word.
Definition tmc9660_bootconfig.hpp:251
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition tmc9660_types.hpp:35
BootMode
BOOT_MODE of the boot configuration (offset 8, bits 0-1).
Definition tmc9660_types.hpp:218
@ InvalidArgument
An argument or a Config field is out of range; nothing was sent.
@ Ok
The call succeeded.
@ Refused
A safety guard said no; nothing was sent or changed.
@ Register
Register mode.
@ Parameter
Parameter mode.
The TMC9660 driver: everything it declares lives here; internals in detail.
Definition tmc9660.hpp:37
constexpr Result< std::size_t > BuildPartitionTable(std::span< const PartitionEntry > entries, uint8_t size_index, uint8_t sector_index, std::span< uint8_t > out) noexcept
Build a partition table (datasheet Tables 21 and 22): header, entries, CRC-32 over the bytes from the...
Definition tmc9660_bootconfig.hpp:400
constexpr std::size_t kPartitionEntryBytes
Size of one partition entry.
Definition tmc9660_bootconfig.hpp:338
constexpr std::size_t kLdoWordIndex
Word index of the LDO configuration (byte offset 0).
Definition tmc9660_bootconfig.hpp:323
constexpr std::size_t kClockWordIndex
Word index of the clock configuration (byte offset 24).
Definition tmc9660_bootconfig.hpp:319
BootField
Named fields of the configuration memory.
Definition tmc9660_bootconfig.hpp:29
@ HallU
Hall U pin select (bits 4-5).
@ BlUartTxen
Bootloader UART TX-enable pin (bits 5-6).
@ GpioOutEn
Output enable of GPIO 0 to 15 (offset 16).
@ Gpio16To18PullUp
Pull-up of GPIO 16 to 18 (bits 9-11).
@ MemTmclScript
Script storage (offset 40, bits 0-1).
@ StepPin
STEP pin select (bits 9-10).
@ I2cEepromScl
I2C SCL pin select (bits 3-4).
@ BlUartBaudrate
Bootloader UART baud rate (bits 7-9).
@ StepDirEnable
STEP/DIR input enable (bit 8).
@ BlUartRx
Bootloader UART RX pin (bit 3).
@ DirPin
DIR pin select (bit 11).
@ SpiEncEnable
SPI encoder enable (offset 38, bit 0).
@ MemParameters
Parameter storage (bits 2-3).
@ MechBrakeOutput
Mechanical brake output select (bits 13-14).
@ ClockReserved1
Reserved, 99 (offset 24, bits 0-6).
@ LdoShortFault
Signal an LDO short on FAULTN (bit 8).
@ BootMode
BOOT_MODE (offset 8, bits 0-1): see BootMode.
@ BrakeChopperEnable
Brake chopper enable (offset 36, bit 4).
@ LdoVext1
VEXT1 output voltage select (offset 0, bits 0-1).
@ BlReadyFault
Assert FAULTN until the bootloader is ready (bit 2).
@ Abn1N
ABN1 N pin select (bits 14-15).
@ Gpio16To18Out
Output level of GPIO 16 to 18 (offset 22, bits 0-2).
@ RefH
Home switch pin (bits 4-6).
@ LdoVext2
VEXT2 output voltage select (bits 2-3).
@ BlDisableSpi
Disable the bootloader SPI (bit 1).
@ ClockRdiv
PLL input divider: input MHz minus one (bits 18-22).
@ I2cEepromFreq
I2C clock select (bits 8-10).
@ GpioPullUp
Pull-up of GPIO 0 to 15 (offset 18).
@ Abn2Enable
ABN encoder 2 enable (bit 12).
@ RefR
Right reference switch pin (bits 2-3).
@ BlSpiSelect
Bootloader SPI instance (bit 2).
@ BlDisableUart
Disable the bootloader UART (offset 6, bit 0).
@ HostAddress
UART host address (bits 8-15).
@ Abn1A
ABN1 A pin select (bits 10-11).
@ Abn2B
ABN2 B pin select (bits 14-15; ambiguity A10).
@ LdoSsVext1
VEXT1 start-up select (bits 4-5).
@ HallV
Hall V pin select (bits 6-7).
@ Gpio16To18OutEn
Output enable of GPIO 16 to 18 (bits 3-5).
@ ClockXtalCfg
Crystal configuration (bits 9-11).
@ BlSpi0Sck
SPI0 SCK pin (bit 10).
@ Abn1B
ABN1 B pin select (bits 12-13).
@ GpioAnalog2To5
Analog input of GPIO 2 to 5 (bits 12-15).
@ BlConfigFault
Assert FAULTN while a configuration change applies (bit 9).
@ Gpio16To18PullDown
Pull-down of GPIO 16 to 18 (bits 6-8).
@ I2cEepromAddr
I2C EEPROM address bits (bits 5-7).
@ Abn2A
ABN2 A pin select (bit 13).
@ SpiEncMode
SPI encoder mode (bits 2-3).
@ MechBrakeEnable
Mechanical brake enable (bit 12).
@ GpioOut
Output level of GPIO 0 to 15 (offset 14).
@ RefL
Left reference switch pin (offset 34, bits 0-1).
@ SpiFlashCs
SPI flash chip-select GPIO (bits 3-7).
@ SpiEncCsPin
SPI encoder chip-select pin (bits 8-9).
@ ClockSysClkDiv
System clock: 0 is 40 MHz, 3 is 15 MHz (bits 23-24).
@ DeviceAddress
UART device address (offset 2, bits 0-7).
@ LdoSsVext2
VEXT2 start-up select (bits 6-7).
@ HallW
Hall W pin select (bits 8-9).
@ ClockPllOutSel
System clock source: 0 oscillator, 1 PLL (bits 16-17).
@ BrakeChopperOutput
Brake chopper output select (bits 5-9).
@ DisableSelftest
Skip the start-up self-test (bit 8).
@ ClockExtNotInt
External clock instead of the internal oscillator (bit 8).
@ I2cEepromEn
I2C EEPROM enable (offset 12, bit 0).
@ SpiEncFreq
SPI encoder divider: 40 MHz / (N + 4) (bits 4-7).
@ HallEnable
Hall sensor enable (offset 32, bit 0).
@ UartTxenPostDelay
TX-enable release delay (offset 4, bits 0-7).
@ I2cEepromSda
I2C SDA pin select (bits 1-2).
@ SpiFlashEn
SPI flash enable (offset 10, bit 0).
@ UartTxenPreDelay
TX-enable lead (bits 8-15).
@ BlExitFault
Assert FAULTN while leaving the bootloader (bit 3).
@ BlUartTx
Bootloader UART TX pin (bit 4).
@ ClockExtNotXtal
External clock instead of a crystal (bit 13).
@ SpiEncBlock
SPI encoder block (bit 1).
@ GpioPullDown
Pull-down of GPIO 0 to 15 (offset 20).
@ StartMotorCtrl
Start the motor control application (bit 12).
@ Abn1Enable
ABN encoder 1 enable (bit 1).
@ SpiFlashFreq
SPI flash divider: 40 MHz / (N + 1), N of 3 or more (bits 8-11).
@ ClockXtalBoost
Crystal boost (bit 12).
constexpr std::size_t kBootModeWordIndex
Word index of the BOOT_MODE word (byte offset 8): written last.
Definition tmc9660_bootconfig.hpp:321
constexpr std::size_t kPartitionHeaderBytes
Header size of a partition table.
Definition tmc9660_bootconfig.hpp:336
constexpr uint32_t kConfigMemAddress
Address of the configuration memory in the bootloader's address space.
Definition tmc9660_bootconfig.hpp:317
One entry of an external-memory partition table.
Definition tmc9660_bootconfig.hpp:326
bool writable
Hint only: the bootloader can always write.
Definition tmc9660_bootconfig.hpp:329
uint32_t size
Size of the data; a multiple of the sector size (parameters: at least 0x400).
Definition tmc9660_bootconfig.hpp:331
uint32_t offset
Start of the data; a multiple of the sector size.
Definition tmc9660_bootconfig.hpp:330
std::array< uint8_t, 12 > name
UTF-8 name bytes, unused bytes zero.
Definition tmc9660_bootconfig.hpp:327
uint8_t type
2: parameter data, 4: script data.
Definition tmc9660_bootconfig.hpp:328
The value of a call, or why there is none.
Definition tmc9660_types.hpp:112
static constexpr Result Success(T v) noexcept
A successful result.
Definition tmc9660_types.hpp:130
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition tmc9660_types.hpp:138
Compile-time helpers of the TMC9660 driver: byte copy, exact hook matching, typed register fields and...
Pure frame encoders and decoders of the three TMC9660 protocols: bootloader, parameter mode (TMCL) an...
Public types of the TMC9660 driver: errors, Result<T>, the protocol enumerations, Config and its mode...