AT25040B Driver 0.1.0
API reference
Loading...
Searching...
No Matches
at25040b_types.hpp
Go to the documentation of this file.
1
12#ifndef AT25040B_TYPES_HPP
13#define AT25040B_TYPES_HPP
14
15#include <cstddef>
16#include <cstdint>
17
18#include "at25040b_detail.hpp"
19#include "at25040b_version.h"
20
22namespace at25040b {
23
36enum class [[nodiscard]] Error : uint8_t {
37 // Base set: the same names and values in every driver of the org (standards/driver.md).
38 Ok = 0,
39 NotInitialized = 1,
40 InvalidArgument = 2,
41 Bus = 3,
42 Timeout = 4,
49 Crc = 6,
50 Busy = 7,
51 DeviceFault = 8,
52 Unsupported = 9,
53 // Chip-specific values start at 16; each one is returned by some call (tests/test_errors.cpp).
54 NoDevice = 16,
57 BusNoise = 17,
59 WriteProtected = 18,
62 BlockProtected = 19,
64 WriteMismatch = 20,
67 Pin = 21,
69};
70
76constexpr const char* ToString(Error error) noexcept {
77 // Every enumerator, and a default for a value that is none (MISRA C++:2023 Rule 9.4.2):
78 // -Wswitch-enum flags a new value without a name (KB-CPP-053).
79 switch (error) {
80 case Error::Ok:
81 return "Ok";
83 return "NotInitialized";
85 return "InvalidArgument";
86 case Error::Bus:
87 return "Bus";
88 case Error::Timeout:
89 return "Timeout";
91 return "DeviceIdMismatch";
92 case Error::Crc:
93 return "Crc";
94 case Error::Busy:
95 return "Busy";
97 return "DeviceFault";
99 return "Unsupported";
100 case Error::NoDevice:
101 return "NoDevice";
102 case Error::BusNoise:
103 return "BusNoise";
105 return "WriteProtected";
107 return "BlockProtected";
109 return "WriteMismatch";
110 case Error::Pin:
111 return "Pin";
112 default:
113 break;
114 }
115 return "Unknown";
116}
117
125template <typename T>
126struct [[nodiscard]] Result {
127 T value{};
128 Error error{Error::Ok};
129
131 [[nodiscard]] constexpr bool ok() const noexcept {
132 return error == Error::Ok;
133 }
135 constexpr explicit operator bool() const noexcept {
136 return ok();
137 }
138
144 static constexpr Result Success(T v) noexcept {
145 return {v, Error::Ok};
146 }
152 static constexpr Result Failure(Error e) noexcept {
153 return {T{}, e};
154 }
155};
156
158template <>
159struct [[nodiscard]] Result<void> {
160 Error error{Error::Ok};
161
163 [[nodiscard]] constexpr bool ok() const noexcept {
164 return error == Error::Ok;
165 }
167 constexpr explicit operator bool() const noexcept {
168 return ok();
169 }
170
172 static constexpr Result Success() noexcept {
173 return {Error::Ok};
174 }
180 static constexpr Result Failure(Error e) noexcept {
181 return {e};
182 }
183};
184
186enum class LogLevel : uint8_t {
187 Error = 0,
188 Warning,
189 Info,
190 Debug,
191};
192
200enum class Variant : uint8_t {
201 At25010b = 0,
202 At25020b = 1,
203 At25040b = 2,
204};
205
212enum class BlockProtect : uint8_t {
213 None = 0,
214 UpperQuarter = 1,
215 UpperHalf = 2,
216 All = 3,
217};
218
226enum class Verify : uint8_t {
227 None = 0,
228 ReadBack = 1,
231};
232
234struct Status {
235 uint8_t raw{0U};
236 bool busy{false};
237 bool write_enabled{false};
240};
241
243inline constexpr std::size_t kPageSizeBytes = 8;
263inline constexpr std::size_t kReadChunkBytes = 16;
265inline constexpr std::size_t kMaxTransferBytes = 2 + kReadChunkBytes;
267inline constexpr uint32_t kWriteCycleMaxUs = 5000;
269inline constexpr uint32_t kPollIntervalUs = 100;
271inline constexpr uint32_t kWriteTimeoutMaxUs = 1000000;
273inline constexpr std::size_t kIdentityReadBytes = 8;
274
275static_assert((kReadChunkBytes >= kPageSizeBytes) && ((kReadChunkBytes % kPageSizeBytes) == 0U),
276 "a chunk is a whole number of pages, so a page read back fits in one READ");
277static_assert(kIdentityReadBytes <= kReadChunkBytes, "the identity read is one READ");
278static_assert(((kWriteCycleMaxUs % kPollIntervalUs) == 0U) &&
280 "the status poll counts whole intervals up to the timeout");
281
287constexpr std::size_t CapacityBytes(Variant variant) noexcept {
288 switch (variant) {
290 return 128U;
292 return 256U;
294 return 512U;
295 default:
296 break;
297 }
298 return 0U;
299}
300
307constexpr std::size_t ProtectedFrom(Variant variant, BlockProtect level) noexcept {
308 const std::size_t size = CapacityBytes(variant);
309 switch (level) {
311 return size;
313 return size - (size / 4U);
315 return size / 2U;
317 return 0U;
318 default:
319 break;
320 }
321 return 0U;
322}
323
324// Table 6-4, the AT25040B column: 180-1FF, 100-1FF, 000-1FF protected.
329static_assert(CapacityBytes(Variant::At25040b) == (static_cast<std::size_t>(0x1FFU) + 1U));
330
331namespace detail {
333template <>
334struct EnumLast<Variant> {
335 static constexpr Variant kValue = Variant::At25040b;
336};
338template <>
339struct EnumLast<BlockProtect> {
340 static constexpr BlockProtect kValue = BlockProtect::All;
341};
343template <>
344struct EnumLast<Verify> {
345 static constexpr Verify kValue = Verify::ReadBack;
346};
347} // namespace detail
348
349// Every value of the two-bit BP field is an enumerator, so decoding it needs no check
350// (KB-CPP20-025).
351static_assert(detail::ToUnderlying(BlockProtect::All) == 3U);
352
373
380constexpr Error Validate(const Config& config) noexcept {
381 if (!detail::IsEnumerator(config.variant)) {
383 }
384 if ((config.write_timeout_us < kWriteCycleMaxUs) ||
385 (config.write_timeout_us > kWriteTimeoutMaxUs)) {
387 }
388 return Error::Ok;
389}
390
391static_assert(Validate(Config{}) == Error::Ok, "the default configuration is valid");
392
394constexpr const char* GetDriverVersion() noexcept {
395 return AT25040B_VERSION_STRING;
396}
398constexpr uint32_t GetDriverVersionMajor() noexcept {
399 return AT25040B_VERSION_MAJOR;
400}
402constexpr uint32_t GetDriverVersionMinor() noexcept {
403 return AT25040B_VERSION_MINOR;
404}
406constexpr uint32_t GetDriverVersionPatch() noexcept {
407 return AT25040B_VERSION_PATCH;
408}
409
412} // namespace at25040b
413
414#endif // AT25040B_TYPES_HPP
Compile-time helpers of the AT25040B driver: exact hook matching, typed register fields and enumerati...
constexpr Error Validate(const Config &config) noexcept
Check a configuration without touching the chip.
Definition at25040b_types.hpp:380
constexpr uint32_t kPollIntervalUs
Time between two status reads while the driver waits for a write cycle, in microseconds.
Definition at25040b_types.hpp:269
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
constexpr const char * GetDriverVersion() noexcept
Definition at25040b_types.hpp:394
constexpr std::size_t CapacityBytes(Variant variant) noexcept
Array size of a variant.
Definition at25040b_types.hpp:287
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition at25040b_types.hpp:36
Verify
Extra verification for one Read() or Write() call, chosen per call.
Definition at25040b_types.hpp:226
LogLevel
Severity passed to the optional Log() hook.
Definition at25040b_types.hpp:186
constexpr std::size_t ProtectedFrom(Variant variant, BlockProtect level) noexcept
First protected address of a protection level (Table 6-4).
Definition at25040b_types.hpp:307
constexpr std::size_t kMaxTransferBytes
Longest transfer the driver asks of the port: opcode, address byte and kReadChunkBytes.
Definition at25040b_types.hpp:265
constexpr uint32_t kWriteCycleMaxUs
Longest self-timed write cycle t_WC, in microseconds (Table 4-3, maximum, every supply).
Definition at25040b_types.hpp:267
constexpr uint32_t GetDriverVersionPatch() noexcept
Definition at25040b_types.hpp:406
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
constexpr uint32_t GetDriverVersionMinor() noexcept
Definition at25040b_types.hpp:402
constexpr uint32_t kWriteTimeoutMaxUs
Longest Config::write_timeout_us the driver accepts, in microseconds (one second).
Definition at25040b_types.hpp:271
constexpr std::size_t kIdentityReadBytes
Bytes from address 0 that EnsureInitialized() reads twice when check_write_enable is off.
Definition at25040b_types.hpp:273
BlockProtect
Block write protection level, BP1:BP0 in the status register (Table 6-4).
Definition at25040b_types.hpp:212
constexpr const char * ToString(Error error) noexcept
The name of an error, for logs.
Definition at25040b_types.hpp:76
constexpr uint32_t GetDriverVersionMajor() noexcept
Definition at25040b_types.hpp:398
Variant
Which part of the family is fitted. The chip cannot tell its size, so it is configured.
Definition at25040b_types.hpp:200
@ InvalidArgument
An argument or a Config field is out of range; nothing was sent.
@ Crc
Not returned by this driver (the chip sends no CRC).
@ Bus
A transfer hook (Transfer(), EnsureInitialized()) returned false.
@ DeviceFault
Not returned by this driver (the chip reports no faults).
@ NotInitialized
EnsureInitialized() has not succeeded, or Deinitialize() ran since.
@ Ok
The call succeeded.
@ Unsupported
Not returned by this driver.
@ Busy
Not returned by this driver: every call waits for a write cycle.
@ Warning
Something unexpected that the driver recovered from.
@ Info
Lifecycle events: initialised.
@ Debug
Detail for bring-up.
@ UpperQuarter
01: the top quarter is read-only (0x180 to 0x1FF on the AT25040B).
@ None
BP1:BP0 = 00: nothing protected. The value of a new part.
@ All
11: the whole array is read-only.
@ UpperHalf
10: the top half is read-only (0x100 to 0x1FF on the AT25040B).
@ At25040b
512 bytes (4 Kbit), A8 in the opcode. The default.
@ At25020b
256 bytes (2 Kbit).
@ At25010b
128 bytes (1 Kbit).
The AT25040B driver: everything it declares lives here; internals in detail.
Definition at25040b.hpp:30
What the driver is told about the board. The chip itself has nothing to configure: its only setting,...
Definition at25040b_types.hpp:361
Variant variant
Definition at25040b_types.hpp:362
bool check_write_enable
Definition at25040b_types.hpp:369
uint32_t write_timeout_us
Longest wait for a write cycle to end, in microseconds; at least kWriteCycleMaxUs.
Definition at25040b_types.hpp:371
constexpr bool ok() const noexcept
Definition at25040b_types.hpp:163
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition at25040b_types.hpp:180
static constexpr Result Success() noexcept
Definition at25040b_types.hpp:172
The value of a call, or why there is none.
Definition at25040b_types.hpp:126
static constexpr Result Success(T v) noexcept
A successful result.
Definition at25040b_types.hpp:144
static constexpr Result Failure(Error e) noexcept
A failed result.
Definition at25040b_types.hpp:152
constexpr bool ok() const noexcept
Definition at25040b_types.hpp:131
The status register, decoded (Tables 6-2 and 6-3).
Definition at25040b_types.hpp:234
bool busy
A write cycle runs: every bit reads 1, the other fields mean nothing.
Definition at25040b_types.hpp:236
BlockProtect block_protect
BP1:BP0.
Definition at25040b_types.hpp:238
bool write_enabled
WEN: the write enable latch is set.
Definition at25040b_types.hpp:237
uint8_t raw
The byte RDSR returned.
Definition at25040b_types.hpp:235