Porting¶
Run the driver on a new MCU by writing one class: the port.
Datasheet sections this page relies on
From Microchip (Atmel) Atmel-8707 F:
- SPI clock, CS timing and the write cycle time: 4.3 AC Characteristics, Table 4-3, p. 5
- SPI modes, invalid opcodes, HOLD and the WP pin: 5 Serial Interface Description, p. 6
- Instruction timing: 7 Timing Diagrams, Figures 7-1 to 7-8, p. 10
All of them, with the driver API for each: Datasheet map.
The driver never calls your SDK. It calls hooks on a class you derive from at25040b::SpiInterface<Self> (in
inc/at25040b_spi_interface.hpp). The base uses CRTP and declares no hook
itself; the driver template is constrained by the at25040b::SpiPort concept, so calls are resolved at compile
time (no virtual functions, nothing to allocate) and a missing or misdeclared hook is a compile error at the point
of use.
What you implement¶
| Method | Required | Contract |
|---|---|---|
bool EnsureInitialized() noexcept |
yes | Bring the bus up on the first call; return true at once afterwards. false makes the driver's EnsureInitialized() return Bus |
bool Transfer(const uint8_t* tx, uint8_t* rx, std::size_t len) noexcept |
yes | One full-duplex transfer of len bytes (1 to 18) with CS low for all of them and high after. rx is nullptr when the driver needs no reply. false on any bus error |
void DelayUs(uint32_t us) noexcept |
yes | Wait at least us microseconds: the status polls during a write cycle, 100 µs each |
bool GpioSet(CtrlPin, GpioSignal) noexcept |
no | Drive WP (CtrlPin::WriteProtect): ACTIVE is pin low (protected), INACTIVE pin high; false if the pin write failed, which the driver returns as Error::Pin |
void Log(LogLevel, const char* message) noexcept |
no | Print one line; message is plain text, never a format string |
The port¶
// Your board's bus settings, checked against what the chip needs (handbook KB-CPP-123).
inline constexpr uint32_t kMySupplyMv = 3300; // lowest VCC the board sees
inline constexpr uint32_t kMyClockHz = 8'000'000; // what platform_spi_init() programs
inline constexpr uint8_t kMySpiMode = 0; // CPOL 0, CPHA 0
inline constexpr bool kMyMsbFirst = true; // the SDK's bit order
inline constexpr uint32_t kMyCsGapNs = 1000; // CS high between two transfers, as measured
static_assert(kMyClockHz <= at25040b::BusTimingAt(kMySupplyMv).max_clock_hz,
"SCK above f_SCK max at this supply (Table 4-3)");
static_assert(kMySpiMode == at25040b::kSpiMode || kMySpiMode == at25040b::kSpiModeAlternate,
"the chip samples in SPI mode 0 or 3");
static_assert(kMyMsbFirst == at25040b::kMsbFirst, "the chip takes MSB first");
static_assert(kMyCsGapNs >= at25040b::BusTimingAt(kMySupplyMv).min_cs_high_ns,
"CS high time below t_CS (Table 4-3)");
class MyPort : public at25040b::SpiInterface<MyPort> {
public:
// Bring the bus up once; later calls return true at once.
bool EnsureInitialized() noexcept {
if (!ready_) {
ready_ = platform_spi_init();
}
return ready_;
}
// One transfer, CS held low for all `len` bytes. `rx` is nullptr when no reply is needed.
bool Transfer(const uint8_t* tx, uint8_t* rx, std::size_t len) noexcept {
return platform_spi_transfer(tx, rx, len);
}
// Wait at least `us` microseconds: the driver polls the status every 100 us during a write.
void DelayUs(uint32_t us) noexcept {
platform_delay_us(us);
}
private:
bool ready_ = false;
};
Every hook is checked with its exact types and noexcept: a Transfer() with a uint16_t len, a DelayUs(uint16_t)
or a hook without noexcept is a compile error, not a silent truncation.
Bus requirements¶
inc/at25040b_spi_interface.hpp states what the chip needs from the bus as
constexpr values (datasheet "Features", section 4.3 Table 4-3, section 5). The scalar values hold over the whole
supply range, 1.8 V to 5.5 V; BusTimingAt(supply_mv) returns the faster limits of a higher supply. Check your port's
settings against them with static_assert, as the port above and the examples do.
| Constant | Value | Source |
|---|---|---|
kSpiMode, kSpiModeAlternate |
0 (tested), 3 | "Features": modes 0 and 3 |
kMsbFirst |
true |
Section 5, "MSB" |
kMaxClockHz |
5 MHz; BusTimingAt(): 10 MHz from 2.5 V, 20 MHz from 4.5 V |
Table 4-3, fSCK |
kMinCsHighNs |
200 ns; 100 ns from 2.5 V | Table 4-3, tCS |
kCsSetupNs, kCsHoldNs |
200 ns; 100 ns from 2.5 V | Table 4-3, tCSS, tCSH |
kDataSetupNs, kDataHoldNs |
80 ns; 40 ns from 2.5 V, 20 ns from 4.5 V | Table 4-3, tSU, tH |
kContinuousWord |
false: idle SCK between bytes is fine, CS stays low |
Table 4-3 (no tWH/tWL maximum) |
kMaxTransferBytes |
18: opcode, address, 16 data bytes | The driver's read chunk |
Control pins¶
| Pin | Polarity | Idle level | When the driver changes it |
|---|---|---|---|
WP (CtrlPin::WriteProtect) |
Active low: ACTIVE = pin low = writes blocked |
ACTIVE (low) |
Released (INACTIVE, high) only for a write, a block-protection change and the identity check, parked ACTIVE after |
| CS | Active low | High (deselected) | Never by the driver: the port's SPI controller drives it, low for each transfer. Drive it high before any device on the bus is clocked |
| HOLD | Active low | High | Never: tie it high (a HOLD strapped to CS makes every status read fail) |
The port drives WP to its idle level, low, before it enables the pin's output and before the first transfer (handbook KB-HW-018), so the chip never sees WP float high. For this pin the idle level is the asserted one: WP is a protection, and a glitch or a reset must leave the array protected. The driver never drives HOLD: tie it high.
Transfer buffers¶
The port only ever receives the driver's own two 18-byte transfer buffers, which are members of the driver object, never a caller's buffer or a stack array. If your SPI controller uses DMA, place the driver object in memory the DMA can reach (on ESP32, internal RAM, not a PSRAM task stack).
Rules the transfer must follow:
- One call, one instruction. Keep CS low for all
lenbytes and raise it after: every instruction starts on a CS falling edge, and a write cycle starts when CS rises after the WRITE. Never split a transfer into several CS periods, and never join two. - Mode 0 or 3, MSB first. At most
BusTimingAt(supply_mv).max_clock_hz: 20 MHz from 4.5 V, 10 MHz from 2.5 V, 5 MHz from 1.8 V; start at 1 MHz on jumper wires. CS high for at least tCS between transfers. - Raw bytes only. Do not interpret, retry or reorder bytes; the driver owns the framing and decides on retries.
- Return
falsefor a bus error. The driver turns it intoError::Bus(a pin hook intoError::Pin) and never ignores it. - Bounded time-outs. A stuck bus fails the call; it does not block forever.
- Shared bus. If other devices share the bus, take the bus lock in the port around each transfer, or in the handler around each driver call (API guide).
Optional hooks¶
The driver finds the optional hooks at compile time with C++20 requires, in one place (at25040b::detail). A
missing hook falls back in a documented, safe way or fails to compile; it never skips a step silently.
| Hook | Used for | Without it |
|---|---|---|
GpioSet() |
WP: released for a write, a block-protection change and the identity check, parked after | WP is the board's: tie it high for writes, or low for a read-only board (then Config::check_write_enable = false) |
Log() |
One line per lifecycle event or failure | Nothing is logged |
A port with every hook:
class FullPort : public at25040b::SpiInterface<FullPort> {
public:
bool EnsureInitialized() noexcept {
return platform_spi_init();
}
bool Transfer(const uint8_t* tx, uint8_t* rx, std::size_t len) noexcept {
return platform_spi_transfer(tx, rx, len);
}
// Required: write cycles and status polls.
void DelayUs(uint32_t us) noexcept {
platform_delay_us(us);
}
// Optional: WP on a GPIO. ACTIVE means "protected", which is a low level on the pin. The driver
// releases it only around writes and the identity check, and parks it after.
bool GpioSet(at25040b::CtrlPin pin, at25040b::GpioSignal signal) noexcept {
if (pin != at25040b::CtrlPin::WriteProtect) {
return false;
}
return platform_gpio_write(kWpGpio, signal == at25040b::GpioSignal::INACTIVE);
}
// Optional: one line per lifecycle event or failure. The driver never formats; the port does.
void Log(at25040b::LogLevel level, const char* message) noexcept {
if (level > at25040b::LogLevel::Warning) {
return;
}
platform_log(message); // plain text: never use it as a format string
}
private:
static constexpr int kWpGpio = 10;
};
at25040b::Error CheckWpWiring(at25040b::AT25040B<FullPort>& eeprom) {
// With the hook, EnsureInitialized() raises WP for WREN: a WP line that does not reach the chip
// fails the start with DeviceIdMismatch, before any write is attempted.
return eeprom.EnsureInitialized().error;
}
A GpioSet() that returns void, and a port without DelayUs(), are compile errors: the driver must see a failed
pin write, and the write cycle wait is never skipped. The compile-fail tests check both rules.
Reference implementations¶
Every port lives with its example, in examples/<platform>/; the driver has none. Platforms lists
them and how to add one.
examples/host/host_at25040b_port.hpp: any PC, against a simulated chip. Start from it for a host build or a test bench; it is also the smallest complete port.examples/esp32/main/esp32_at25040b_port.hpp: ESP-IDF, with every hook. Start from it for any ESP-IDF target.
Check your port¶
- Build it: the ports on this page are compiled by the host CI from
tests/docs/, with the driver instantiated over them. - Call
EnsureInitialized()with the chip fitted:Okproves that transfers work both ways, that CS frames each instruction and, withGpioSet(), that WP reaches the chip.GetLastStatusByte()is 0x00 on a new part. - Unplug the chip (or lift CS) and call
Deinitialize()thenEnsureInitialized():NoDeviceorDeviceIdMismatch, neverOk. - Write 16 bytes across a page boundary to an unused range and read them back.
Threads¶
The driver is not thread-safe. Give each driver object one owner task, or guard every call with one mutex. When several chips share a bus, the port or the handler must also serialise the bus. See Contract.
Editor setup¶
The clang-format and clang-tidy configuration is in _config/, and the repository root has no copy of it. Tools
that take a path use it directly; CI does the same:
| Tool | Setting |
|---|---|
| Command line | clang-format --style=file:_config/.clang-format, clang-tidy --config-file=_config/.clang-tidy -p build |
| VS Code (C/C++ extension) | "C_Cpp.clang_format_style": "file:${workspaceFolder}/_config/.clang-format" and "C_Cpp.codeAnalysis.clangTidy.args": ["--config-file=${workspaceFolder}/_config/.clang-tidy"] |
| clangd (VS Code clangd, Neovim, Emacs), CLion | These find .clang-format and .clang-tidy only by name, from the file upwards: copy both to the root once (cp _config/.clang-format _config/.clang-tidy .). .gitignore lists the copies, so they never reach a commit; copy again after _config/ changes |
Configure with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON (clangd: --compile-commands-dir=build) so the editor sees the
same flags as the build.