AT25040B Driver 0.1.0
API reference
Loading...
Searching...
No Matches
at25040b_spi_interface.hpp
Go to the documentation of this file.
1// clang-format off: the hook table below must keep one row per line.
26// clang-format on
27#ifndef AT25040B_SPI_INTERFACE_HPP
28#define AT25040B_SPI_INTERFACE_HPP
29
30#include <array>
31#include <concepts>
32#include <cstddef>
33#include <cstdint>
34#include <span>
35
36#include "at25040b_detail.hpp"
38#include "at25040b_types.hpp"
39
40namespace at25040b {
41
53inline constexpr uint8_t kSpiMode = 0;
55inline constexpr uint8_t kSpiModeAlternate = 3;
57inline constexpr bool kMsbFirst = true;
59inline constexpr uint32_t kMaxClockHz = 5'000'000;
61inline constexpr uint32_t kMinCsHighNs = 200;
63inline constexpr uint32_t kCsSetupNs = 200;
65inline constexpr uint32_t kCsHoldNs = 200;
67inline constexpr uint32_t kDataSetupNs = 80;
69inline constexpr uint32_t kDataHoldNs = 80;
72inline constexpr bool kContinuousWord = false;
73
75struct BusTiming {
76 uint32_t min_supply_mv{0U};
77 uint32_t max_clock_hz{0U};
78 uint32_t min_cs_high_ns{0U};
79 uint32_t cs_setup_ns{0U};
80 uint32_t cs_hold_ns{0U};
81 uint32_t data_setup_ns{0U};
82 uint32_t data_hold_ns{0U};
83};
84
86inline constexpr uint32_t kMinSupplyMv = 1800;
88inline constexpr uint32_t kMaxSupplyMv = 5500;
89
96constexpr BusTiming BusTimingAt(uint32_t supply_mv) noexcept {
97 if ((supply_mv < kMinSupplyMv) || (supply_mv > kMaxSupplyMv)) {
98 return BusTiming{};
99 }
100 if (supply_mv >= 4500U) {
101 return BusTiming{.min_supply_mv = 4500U,
102 .max_clock_hz = 20'000'000U,
103 .min_cs_high_ns = 100U,
104 .cs_setup_ns = 100U,
105 .cs_hold_ns = 100U,
106 .data_setup_ns = 20U,
107 .data_hold_ns = 20U};
108 }
109 if (supply_mv >= 2500U) {
110 return BusTiming{.min_supply_mv = 2500U,
111 .max_clock_hz = 10'000'000U,
112 .min_cs_high_ns = 100U,
113 .cs_setup_ns = 100U,
114 .cs_hold_ns = 100U,
115 .data_setup_ns = 40U,
116 .data_hold_ns = 40U};
117 }
119 .max_clock_hz = kMaxClockHz,
120 .min_cs_high_ns = kMinCsHighNs,
121 .cs_setup_ns = kCsSetupNs,
122 .cs_hold_ns = kCsHoldNs,
123 .data_setup_ns = kDataSetupNs,
124 .data_hold_ns = kDataHoldNs};
125}
126
127using detail::operator""_u32;
128
129static_assert((BusTimingAt(3300_u32).max_clock_hz == 10'000'000U) &&
130 (BusTimingAt(5000_u32).cs_hold_ns == 100U));
131static_assert((BusTimingAt(1800_u32).max_clock_hz == kMaxClockHz) &&
132 (BusTimingAt(1799_u32).max_clock_hz == 0U));
133static_assert(BusTimingAt(5501_u32).max_clock_hz == 0U);
143enum class CtrlPin : uint8_t {
144 WriteProtect = 0,
145};
146
148enum class GpioSignal : uint8_t {
149 INACTIVE = 0,
150 ACTIVE = 1,
151};
152
163template <typename Derived>
165public:
167 SpiInterface(const SpiInterface&) = delete;
170
171protected:
173 SpiInterface() noexcept = default;
175 ~SpiInterface() noexcept = default;
176};
177
190template <typename Port>
191concept SpiPort = std::derived_from<Port, SpiInterface<Port>> && requires {
192 detail::ExactHook<Port, bool() noexcept>::Take(&Port::EnsureInitialized);
193 detail::ExactHook<Port, bool(const uint8_t*, uint8_t*, std::size_t) noexcept>::Take(
194 &Port::Transfer);
195};
196
197namespace detail {
198
201constexpr uint8_t AddressedOpcode(uint8_t opcode, uint16_t address) noexcept {
202 return ((static_cast<uint32_t>(address) & static_cast<uint32_t>(reg::kAddressA8)) != 0U)
203 ? static_cast<uint8_t>(static_cast<uint32_t>(opcode) |
204 static_cast<uint32_t>(reg::kOpcodeA8))
205 : opcode;
206}
207
209constexpr uint8_t AddressByte(uint16_t address) noexcept {
210 return static_cast<uint8_t>(static_cast<uint32_t>(address) &
211 static_cast<uint32_t>(reg::kAddressLowMask));
212}
213
214static_assert((AddressedOpcode(reg::kRead, 0x1FF_u16) == 0x0BU) &&
215 (AddressedOpcode(reg::kWrite, 0xFF_u16) == reg::kWrite));
216static_assert(AddressByte(0x1A5_u16) == 0xA5U);
217
219inline constexpr std::size_t kCommandBytes = 2;
221static_assert(kMaxTransferBytes == (kCommandBytes + kReadChunkBytes));
222static_assert((kCommandBytes + kPageSizeBytes) <= kMaxTransferBytes,
223 "a page write fits the buffer");
224
226template <std::size_t N>
227concept ReadSize = (N >= 1U) && (N <= kReadChunkBytes);
229template <std::size_t N>
230concept WriteSize = (N >= 1U) && (N <= kPageSizeBytes);
231
241template <SpiPort Port>
242class EepromBus {
243public:
244 explicit EepromBus(Port& port) noexcept : port_(port) {}
245
246 Port& GetPort() & noexcept {
247 return port_;
248 }
249
251 Error Instruction(uint8_t opcode) noexcept {
252 tx_[0] = opcode;
253 return port_.Transfer(tx_.data(), nullptr, 1U) ? Error::Ok : Error::Bus;
254 }
255
257 Error ReadStatus(uint8_t& status) noexcept {
258 tx_[0] = reg::kRdsr;
259 tx_[1] = 0x00U;
260 rx_[1] = reg::kStatusBusyByte;
261 if (!port_.Transfer(tx_.data(), rx_.data(), 2U)) {
262 return Error::Bus;
263 }
264 status = rx_[1];
265 return Error::Ok;
266 }
267
269 Error WriteStatus(uint8_t value) noexcept {
270 tx_[0] = reg::kWrsr;
271 tx_[1] = value;
272 return port_.Transfer(tx_.data(), nullptr, 2U) ? Error::Ok : Error::Bus;
273 }
274
276 template <std::size_t N>
277 requires ReadSize<N>
278 Error Read(uint16_t address, std::span<uint8_t, N> out) noexcept {
279 return Read(address, std::span<uint8_t>{out});
280 }
281
283 template <std::size_t N>
284 requires((N != std::dynamic_extent) && !ReadSize<N>)
285 Error Read(uint16_t address, std::span<uint8_t, N> out) noexcept = delete;
286
289 Error Read(uint16_t address, std::span<uint8_t> out) noexcept {
290 if (out.empty() || (out.size() > kReadChunkBytes) || (address > reg::kAddressMax)) {
291 return Error::InvalidArgument;
292 }
293 tx_.fill(0x00U);
294 // MISO idles high: a port that reports success without writing `rx` yields 0xFF, never the
295 // bytes of an earlier transfer (KB-CPP-116).
296 rx_.fill(reg::kStatusBusyByte);
297 tx_[0] = AddressedOpcode(reg::kRead, address);
298 tx_[1] = AddressByte(address);
299 if (!port_.Transfer(tx_.data(), rx_.data(), kCommandBytes + out.size())) {
300 return Error::Bus;
301 }
302 const std::size_t count = out.size();
303 for (std::size_t i = 0U; i < count; ++i) {
304 out[i] = rx_[kCommandBytes + i];
305 }
306 return Error::Ok;
307 }
308
310 template <std::size_t N>
311 requires WriteSize<N>
312 Error Write(uint16_t address, std::span<const uint8_t, N> data) noexcept {
313 return Write(address, std::span<const uint8_t>{data});
314 }
315
317 template <std::size_t N>
318 requires((N != std::dynamic_extent) && !WriteSize<N>)
319 Error Write(uint16_t address, std::span<const uint8_t, N> data) noexcept = delete;
320
325 Error Write(uint16_t address, std::span<const uint8_t> data) noexcept {
326 const std::size_t offset = static_cast<std::size_t>(address) % kPageSizeBytes;
327 if (data.empty() || (data.size() > (kPageSizeBytes - offset)) || (address > reg::kAddressMax)) {
328 return Error::InvalidArgument;
329 }
330 tx_[0] = AddressedOpcode(reg::kWrite, address);
331 tx_[1] = AddressByte(address);
332 const std::size_t count = data.size();
333 for (std::size_t i = 0U; i < count; ++i) {
334 tx_[kCommandBytes + i] = data[i];
335 }
336 return port_.Transfer(tx_.data(), nullptr, kCommandBytes + data.size()) ? Error::Ok
337 : Error::Bus;
338 }
339
340private:
341 Port& port_;
342 std::array<uint8_t, kMaxTransferBytes> tx_{};
343 std::array<uint8_t, kMaxTransferBytes> rx_{};
344};
345
346} // namespace detail
347
348} // namespace at25040b
349
350#endif // AT25040B_SPI_INTERFACE_HPP
Compile-time helpers of the AT25040B driver: exact hook matching, typed register fields and enumerati...
Instruction opcodes and status register bits of the AT25010B, AT25020B and AT25040B.
Public types of the AT25040B driver: errors, Result<T>, variants, block protection and configuration.
CRTP base of the platform SPI port.
Definition at25040b_spi_interface.hpp:164
SpiInterface(const SpiInterface &)=delete
Ports are not copied: the driver holds a reference.
SpiInterface & operator=(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 at25040b_spi_interface.hpp:191
constexpr std::size_t kPageSizeBytes
Bytes per page: a WRITE never crosses an 8-byte page (section 6, "Write Sequence").
Definition at25040b_types.hpp:243
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition at25040b_types.hpp:36
constexpr std::size_t kMaxTransferBytes
Longest transfer the driver asks of the port: opcode, address byte and kReadChunkBytes.
Definition at25040b_types.hpp:265
constexpr std::size_t kReadChunkBytes
Data bytes per READ transfer: Read() splits longer requests into transfers of at most this many data ...
Definition at25040b_types.hpp:263
The AT25040B driver: everything it declares lives here; internals in detail.
Definition at25040b.hpp:30
CtrlPin
Control pins the port may drive through the optional GpioSet() hook.
Definition at25040b_spi_interface.hpp:143
@ WriteProtect
WP, active low on the package pin. ACTIVE (pin low) blocks every write.
constexpr bool kMsbFirst
Each byte is clocked most significant bit first (section 5, "MSB").
Definition at25040b_spi_interface.hpp:57
constexpr BusTiming BusTimingAt(uint32_t supply_mv) noexcept
The SPI limits at a supply voltage (Table 4-3): 4.5 V to 5.5 V allows 20 MHz, 2.5 V to 5....
Definition at25040b_spi_interface.hpp:96
constexpr bool kContinuousWord
Definition at25040b_spi_interface.hpp:72
constexpr uint32_t kMinCsHighNs
Shortest time CS stays high between two transfers, t_CS min at 1.8 V to 5.5 V (Table 4-3).
Definition at25040b_spi_interface.hpp:61
constexpr uint32_t kCsSetupNs
CS low to the first SCK edge, t_CSS min at 1.8 V to 5.5 V (Table 4-3).
Definition at25040b_spi_interface.hpp:63
constexpr uint32_t kMaxSupplyMv
Highest supply of the family, in millivolts (Table 4-3).
Definition at25040b_spi_interface.hpp:88
constexpr uint8_t kSpiMode
Definition at25040b_spi_interface.hpp:53
constexpr uint8_t kSpiModeAlternate
The other SPI mode the chip accepts: CPOL 1, CPHA 1 ("Features").
Definition at25040b_spi_interface.hpp:55
constexpr uint32_t kMaxClockHz
Highest SCK frequency over the whole supply range, f_SCK max at 1.8 V to 5.5 V (Table 4-3).
Definition at25040b_spi_interface.hpp:59
constexpr uint32_t kMinSupplyMv
Lowest supply of the family, in millivolts (Table 4-3).
Definition at25040b_spi_interface.hpp:86
constexpr uint32_t kDataSetupNs
SI valid before the sampling SCK edge, t_SU min at 1.8 V to 5.5 V (Table 4-3).
Definition at25040b_spi_interface.hpp:67
constexpr uint32_t kDataHoldNs
SI held after the sampling SCK edge, t_H min at 1.8 V to 5.5 V (Table 4-3).
Definition at25040b_spi_interface.hpp:69
constexpr uint32_t kCsHoldNs
Last SCK edge to CS high, t_CSH min at 1.8 V to 5.5 V (Table 4-3).
Definition at25040b_spi_interface.hpp:65
GpioSignal
Logical level of a control pin; the port maps it to the physical polarity.
Definition at25040b_spi_interface.hpp:148
@ ACTIVE
The pin function is asserted (WP: pin low, writes blocked).
@ INACTIVE
The pin function is deasserted (WP: pin high, writes allowed).
The SPI timing limits of one supply range (Table 4-3).
Definition at25040b_spi_interface.hpp:75
uint32_t min_supply_mv
Lowest VCC of the range; every range ends at 5.5 V.
Definition at25040b_spi_interface.hpp:76
uint32_t data_setup_ns
t_SU min.
Definition at25040b_spi_interface.hpp:81
uint32_t data_hold_ns
t_H min.
Definition at25040b_spi_interface.hpp:82
uint32_t cs_hold_ns
t_CSH min.
Definition at25040b_spi_interface.hpp:80
uint32_t cs_setup_ns
t_CSS min.
Definition at25040b_spi_interface.hpp:79
uint32_t max_clock_hz
f_SCK max; 0 for a supply outside 1.8 V to 5.5 V.
Definition at25040b_spi_interface.hpp:77
uint32_t min_cs_high_ns
t_CS min.
Definition at25040b_spi_interface.hpp:78