TLE92466ED Driver 0.1.0
API reference
Loading...
Searching...
No Matches
tle92466ed_spi_interface.hpp
Go to the documentation of this file.
1// clang-format off: the tables below must keep one row per line.
31// clang-format on
32#ifndef TLE92466ED_SPI_INTERFACE_HPP
33#define TLE92466ED_SPI_INTERFACE_HPP
34
35#include <array>
36#include <concepts>
37#include <cstddef>
38#include <cstdint>
39
40#include "tle92466ed_detail.hpp"
42#include "tle92466ed_types.hpp"
43
44namespace tle92466ed {
45
55inline constexpr uint8_t kSpiMode = 1;
57inline constexpr bool kMsbFirst = true;
59inline constexpr uint32_t kMaxClockHz = 8'000'000;
61inline constexpr uint32_t kMinCsHighNs = 600;
63inline constexpr uint32_t kCsSetupNs = 250;
65inline constexpr uint32_t kCsHoldNs = 250;
68inline constexpr bool kContinuousWord = false;
70inline constexpr std::size_t kFrameBytes = 4;
73static_assert((1'000'000'000ULL / kMaxClockHz) == 125ULL, "f_SCK max 8 MHz");
74static_assert(kMinCsHighNs > (kCsSetupNs + kCsHoldNs), "t_CSN_TD is the longest CSN timing");
75
77enum class CtrlPin : uint8_t {
78 Reset = 0,
79 Enable = 1,
80 Drv0 = 2,
81 Drv1 = 3,
82 Fault = 4,
84};
85
87enum class GpioSignal : uint8_t {
88 INACTIVE = 0,
89 ACTIVE = 1,
90};
91
102template <typename Derived>
104public:
106 SpiInterface(const SpiInterface&) = delete;
109
110protected:
112 SpiInterface() noexcept = default;
114 ~SpiInterface() noexcept = default;
115};
116
128template <typename Port>
129concept SpiPort = std::derived_from<Port, SpiInterface<Port>> && requires {
130 detail::ExactHook<Port, bool() noexcept>::Take(&Port::EnsureInitialized);
131 detail::ExactHook<Port, bool(const uint8_t*, uint8_t*, std::size_t) noexcept>::Take(
132 &Port::Transfer);
133};
134
135namespace detail {
136
138enum class Width : uint8_t {
139 Bits16 = 0,
140 Bits22 = 1,
141};
142
144struct Reply {
145 Error error{Error::Ok};
146 uint32_t data{0};
147};
148
151inline constexpr uint32_t kReadFiller = 0x00C0'0000U;
152
154[[nodiscard]] constexpr uint32_t EncodeRead(uint16_t address) noexcept {
155 const uint32_t word = kReadFiller | static_cast<uint32_t>(address);
156 return (static_cast<uint32_t>(reg::FrameCrc(word)) << 24U) | word;
157}
158
160[[nodiscard]] constexpr uint32_t EncodeWrite(uint16_t address, uint16_t data) noexcept {
161 const uint32_t word =
162 ((static_cast<uint32_t>(address) & reg::kWriteAddressMask) << reg::kWriteAddressShift) |
163 reg::kFrameRw | static_cast<uint32_t>(data);
164 return (static_cast<uint32_t>(reg::FrameCrc(word)) << 24U) | word;
165}
166
168[[nodiscard]] constexpr Error StatusError(uint32_t status) noexcept {
169 if (status == 0U) {
170 return Error::Ok;
171 }
172 if (status == reg::kStatusCrcError) {
173 return Error::Crc;
174 }
175 if ((status == reg::kStatusFrameError) || (status == reg::kStatusWriteReadOnly)) {
176 return Error::FrameRejected;
177 }
178 return Error::DeviceFault; // 100B to 110B: internal bus fault
179}
180
192[[nodiscard]] constexpr Reply DecodeReply(uint32_t miso, uint32_t mosi, Width width,
193 bool write) noexcept {
194 if ((miso == 0U) || (miso == 0xFFFF'FFFFU) || (miso == mosi)) {
195 return {.error = Error::NoDevice, .data = 0U};
196 }
197 const uint32_t mode = (miso >> reg::kReplyModeShift) & 0x3U;
198 if (mode == reg::kReplyModeCritical) {
199 return {.error = Error::CriticalFault, .data = miso & 0xFFU};
200 }
201 if (static_cast<uint32_t>(reg::FrameCrc(miso)) != (miso >> 24U)) {
202 return {.error = Error::Crc, .data = 0U};
203 }
204 if (mode == reg::kReplyMode16) {
205 const Error status = StatusError((miso >> reg::kReplyStatusShift) & reg::kReplyStatusMask);
206 if (status != Error::Ok) {
207 return {.error = status, .data = 0U};
208 }
209 const bool rw = (miso & reg::kFrameRw) != 0U;
210 if ((width != Width::Bits16) || (rw != write)) {
211 return {.error = Error::ReplyMismatch, .data = 0U};
212 }
213 return {.error = Error::Ok, .data = miso & reg::kData16Mask};
214 }
215 if ((mode != reg::kReplyMode22) || (width != Width::Bits22) || write) {
216 return {.error = Error::ReplyMismatch, .data = 0U};
217 }
218 return {.error = Error::Ok, .data = miso & reg::kData22Mask};
219}
220
222[[nodiscard]] constexpr uint32_t Reply16(uint32_t data, bool write, uint32_t status) noexcept {
223 const uint32_t word = ((status & reg::kReplyStatusMask) << reg::kReplyStatusShift) |
224 (write ? reg::kFrameRw : 0U) | (data & reg::kData16Mask);
225 return (static_cast<uint32_t>(reg::FrameCrc(word)) << 24U) | word;
226}
227
228// The codec, proved on the datasheet's frame layout (section 5.2.3).
229static_assert(EncodeRead(reg::kIcvid) ==
230 (0x00C0'0200U + (uint32_t{reg::FrameCrc(0xC0'0200U)} << 24U)));
231static_assert((EncodeWrite(reg::kChCtrl, 0x8000U) & 0x00FF'FFFFU) == 0x01'8000U);
232static_assert((EncodeWrite(0x0049U, 0x1234U) & 0x00FE'0000U) == (0x49U << 17U));
233static_assert(DecodeReply(Reply16(0xC1FEU, false, 0U), 0U, Width::Bits16, false).data == 0xC1FEU);
234static_assert(DecodeReply(Reply16(0xC1FEU, false, 0U), 0U, Width::Bits22, false).error ==
235 Error::ReplyMismatch);
236static_assert(DecodeReply(Reply16(0U, true, 2U), 0U, Width::Bits16, true).error == Error::Crc);
237static_assert(DecodeReply(EncodeRead(reg::kIcvid), EncodeRead(reg::kIcvid), Width::Bits16, false)
238 .error == Error::NoDevice);
239static_assert(DecodeReply(0x0080'00E0U, 0U, Width::Bits16, false).error == Error::CriticalFault);
240static_assert(DecodeReply(Reply16(1U, false, 0U) ^ 0x0100'0000U, 0U, Width::Bits16, false).error ==
241 Error::Crc);
242
261template <SpiPort Port>
262class Transport {
263public:
265 explicit Transport(Port& port) noexcept : port_(port) {}
266
268 Port& GetPort() & noexcept {
269 return port_;
270 }
271
277 Result<uint32_t> Access(uint16_t address, bool write, uint16_t data) noexcept {
278 if (!synced_ && !resync()) {
279 return Result<uint32_t>::Failure(Error::Bus);
280 }
281 const Width width = (!write && reg::Is22Bit(address)) ? Width::Bits22 : Width::Bits16;
282 const uint32_t request = write ? EncodeWrite(address, data) : EncodeRead(address);
283 const Width anchor = (width == Width::Bits16) ? Width::Bits22 : Width::Bits16;
284 const uint32_t anchor_frame = EncodeRead(anchorAddress(anchor));
285 const auto first = exchange(request);
286 const auto second = first.ok() ? exchange(anchor_frame) : first;
287 if (!second.ok()) {
288 synced_ = false;
289 return Result<uint32_t>::Failure(Error::Bus);
290 }
291 const Error previous = checkAnchor(first.value, request);
292 const bool same_register = !write && (address == anchorAddress(pending_));
293 const Reply reply = DecodeReply(second.value, anchor_frame, width, write);
294 last_reply_ = second.value;
295 pending_ = anchor;
296 if (reply.error == Error::CriticalFault) {
297 last_critical_ = static_cast<uint8_t>(reply.data);
298 }
299 Error e = choose(previous, repeated(reply.error, first.value, second.value, same_register));
300 if (e == Error::CriticalFault) {
301 e = confirmCritical(); // a critical frame has no CRC: one more frame must show it too
302 }
303 if (e != Error::Ok) {
304 synced_ = false;
305 diagnostics_.rejected_replies++;
306 return Result<uint32_t>::Failure(e);
307 }
308 return Result<uint32_t>::Success(reply.data);
309 }
310
316 Result<uint32_t> Read(uint16_t address, uint32_t retries) noexcept {
317 const uint32_t attempts = ((retries < kMaxRetries) ? retries : kMaxRetries) + 1U;
318 Result<uint32_t> r = Result<uint32_t>::Failure(Error::Bus);
319 for (uint32_t attempt = 0U; attempt < attempts; ++attempt) {
320 r = Access(address, false, 0U);
321 if (r.ok() || (r.error == Error::Bus) || (r.error == Error::CriticalFault) ||
322 (r.error == Error::UnexpectedReset)) {
323 break;
324 }
325 if ((attempt + 1U) < attempts) {
326 diagnostics_.retries++;
327 }
328 }
329 return r;
330 }
331
334 void WatchReset(bool armed) noexcept {
335 watch_reset_ = armed;
336 }
338 void ExpectIdentity(bool on) noexcept {
339 expect_identity_ = on;
340 }
342 void Desync() noexcept {
343 synced_ = false;
344 }
346 [[nodiscard]] uint32_t LastReply() const noexcept {
347 return last_reply_;
348 }
350 [[nodiscard]] uint8_t LastCritical() const noexcept {
351 return last_critical_;
352 }
354 [[nodiscard]] uint32_t LastStatus() const noexcept {
355 return last_status_;
356 }
358 [[nodiscard]] const BusDiagnostics& Diagnostics() const& noexcept {
359 return diagnostics_;
360 }
362 void Diagnostics() const&& = delete;
363
364private:
366 Result<uint32_t> exchange(uint32_t mosi) noexcept {
367 for (uint32_t i = 0U; i < kFrameBytes; ++i) {
368 tx_[i] = static_cast<uint8_t>((mosi >> (24U - (8U * i))) & 0xFFU);
369 }
370 diagnostics_.frames++;
371 if (!port_.Transfer(tx_.data(), rx_.data(), kFrameBytes)) {
372 return Result<uint32_t>::Failure(Error::Bus);
373 }
374 uint32_t miso = 0U;
375 for (const uint8_t byte : rx_) {
376 miso = (miso << 8U) | static_cast<uint32_t>(byte);
377 }
378 return Result<uint32_t>::Success(miso);
379 }
380
382 [[nodiscard]] static constexpr uint16_t anchorAddress(Width width) noexcept {
383 return (width == Width::Bits22) ? reg::kFbStat : reg::kIcvid;
384 }
385
388 [[nodiscard]] static constexpr Error repeated(Error reply, uint32_t first, uint32_t second,
389 bool same_register) noexcept {
390 return ((reply == Error::Ok) && (first == second) && !same_register) ? Error::ReplyMismatch
391 : reply;
392 }
393
397 Error confirmCritical() noexcept {
398 const uint32_t frame = EncodeRead(reg::kIcvid);
399 const auto again = exchange(frame);
400 if (!again.ok()) {
401 return Error::Bus;
402 }
403 const Reply r = DecodeReply(again.value, frame, Width::Bits16, false);
404 if (r.error != Error::CriticalFault) {
405 return Error::ReplyMismatch;
406 }
407 last_critical_ = static_cast<uint8_t>(r.data);
408 return Error::CriticalFault;
409 }
410
412 bool resync() noexcept {
413 diagnostics_.resyncs++;
414 if (!exchange(EncodeRead(reg::kIcvid)).ok()) {
415 return false;
416 }
417 pending_ = Width::Bits16;
418 synced_ = true;
419 return true;
420 }
421
423 Error checkAnchor(uint32_t miso, uint32_t request) noexcept {
424 const Reply r = DecodeReply(miso, request, pending_, false);
425 if (r.error != Error::Ok) {
426 if (r.error == Error::CriticalFault) {
427 last_critical_ = static_cast<uint8_t>(r.data);
428 }
429 return r.error;
430 }
431 if (pending_ == Width::Bits16) {
432 return (!expect_identity_ ||
433 (reg::IcManufacturer::Extract(static_cast<uint16_t>(r.data)) == kManufacturerId))
434 ? Error::Ok
436 }
437 last_status_ = r.data;
438 const bool reset = (r.data & (reg::kStatPorEvent | reg::kStatResEvent)) != 0U;
439 return (watch_reset_ && reset) ? Error::UnexpectedReset : Error::Ok;
440 }
441
444 [[nodiscard]] static constexpr Error choose(Error anchor, Error reply) noexcept {
445 if (reply == Error::NoDevice) {
446 return reply;
447 }
448 if ((anchor == Error::CriticalFault) || (reply == Error::CriticalFault)) {
449 return Error::CriticalFault;
450 }
451 return (anchor != Error::Ok) ? anchor : reply;
452 }
453
454 Port& port_;
455 std::array<uint8_t, kFrameBytes> tx_{};
456 std::array<uint8_t, kFrameBytes> rx_{};
457 BusDiagnostics diagnostics_{};
458 uint32_t last_reply_{0};
459 uint32_t last_status_{0};
460 uint8_t last_critical_{0};
461 Width pending_{Width::Bits16};
462 bool synced_{false};
463 bool watch_reset_{false};
464 bool expect_identity_{false};
465};
466
467} // namespace detail
468
469} // namespace tle92466ed
470
471#endif // TLE92466ED_SPI_INTERFACE_HPP
CRTP base of the platform SPI port.
Definition tle92466ed_spi_interface.hpp:103
SpiInterface & operator=(const SpiInterface &)=delete
Ports are not copied: the driver holds a reference.
SpiInterface(const SpiInterface &)=delete
Ports are not copied: the driver holds a reference.
SpiInterface() noexcept=default
Only the derived port is constructed.
Satisfied by a class that derives from SpiInterface<Port> and implements the required hooks with exac...
Definition tle92466ed_spi_interface.hpp:129
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition tle92466ed_types.hpp:37
constexpr uint8_t kMaxRetries
Highest Config::max_retries.
Definition tle92466ed_types.hpp:464
The TLE92466ED driver: everything it declares lives here; internals in detail.
Definition tle92466ed.hpp:26
GpioSignal
Logical level of a control pin; the port maps it to the physical polarity.
Definition tle92466ed_spi_interface.hpp:87
@ ACTIVE
The pin function is asserted.
@ INACTIVE
The pin function is deasserted.
CtrlPin
The chip's control pins the port drives (GpioSet) or reads (GpioRead).
Definition tle92466ed_spi_interface.hpp:77
@ Enable
EN, active high: ACTIVE lets the channels switch (section 4.2.3).
@ Reset
RESN, active low: ACTIVE holds the chip in reset (section 4.2.3).
@ Drv0
DRV0, active high: the direct-drive input of channels in that mode.
@ Drv1
DRV1, active high: as DRV0.
constexpr uint32_t kMinCsHighNs
Shortest CSN high time between two frames, t_CSN_TD (Table 18).
Definition tle92466ed_spi_interface.hpp:61
constexpr uint32_t kMaxClockHz
Highest SCK frequency, f_SCK max (Table 18).
Definition tle92466ed_spi_interface.hpp:59
constexpr uint32_t kCsHoldNs
Last SCK falling edge to CSN rising, t_CSN_LAG (Table 18).
Definition tle92466ed_spi_interface.hpp:65
constexpr uint32_t kCsSetupNs
CSN falling edge to the first SCK rising edge, t_CSN_LEAD (Table 18).
Definition tle92466ed_spi_interface.hpp:63
constexpr bool kContinuousWord
Definition tle92466ed_spi_interface.hpp:68
constexpr bool kMsbFirst
Each frame is sent most significant bit first, on SI and SO alike (section 5.2.1).
Definition tle92466ed_spi_interface.hpp:57
constexpr uint8_t kSpiMode
Definition tle92466ed_spi_interface.hpp:55
constexpr std::size_t kFrameBytes
Bytes per transfer: one 32-bit frame per CSN low period (section 5.1.1).
Definition tle92466ed_spi_interface.hpp:70
Compile-time helpers of the TLE92466ED driver: typed integer literals, exact hook matching,...
TLE92466ED register map: addresses, bit fields, reset values and the frame CRC (datasheet section 5....
Public types of the TLE92466ED driver: errors, Result<T>, configuration, decoded status and feedback,...