AT25040B Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Public Member Functions | List of all members
at25040b::AT25040B< Port > Class Template Reference

Driver for one AT25010B, AT25020B or AT25040B on a platform port. More...

#include <at25040b.hpp>

Public Member Functions

 AT25040B (Port &port, const Config &config={}) noexcept
 Bind the driver to a port and store the configuration. No I/O, cannot fail.
 
 AT25040B (const AT25040B &)=delete
 One driver object per chip.
 
AT25040B & operator= (const AT25040B &)=delete
 One driver object per chip.
 
Lifecycle
Result< void > EnsureInitialized () noexcept
 Check that an AT25xxxB answers, once: the only way to initialise the driver.
 
bool IsInitialized () const noexcept
 
Result< void > Deinitialize () noexcept
 Leave the chip safe and mark the driver uninitialised: WRDI, then WP parked.
 
Configuration
Result< void > ApplyConfig (const Config &config) noexcept
 Replace the configuration. Never any I/O: the chip has no setting to write. The variant and the checks apply from the next call; check_write_enable from the next start.
 
const Config & GetConfig () const &noexcept
 
void GetConfig () const &&=delete
 No reference into a temporary driver: it would dangle.
 
std::size_t GetCapacityBytes () const noexcept
 
Memory
Result< void > Read (uint16_t address, std::span< uint8_t > out, Verify verify=Verify::None) noexcept
 Read out.size() bytes from address (sequential READ, section 6, "Read Sequence").
 
Result< void > Write (uint16_t address, std::span< const uint8_t > data, Verify verify=Verify::None) noexcept
 Write data from address: one WRITE and one write cycle per 8-byte page.
 
Status and block protection
Result< Status > ReadStatus () noexcept
 One status read (RDSR), decoded. Does not wait: during a write cycle it returns busy = true.
 
Result< BlockProtect > GetBlockProtection () noexcept
 The block protection level, from the status (Table 6-4). Waits for a running write cycle first.
 
Result< void > SetBlockProtection (BlockProtect level) noexcept
 Set BP1:BP0 (WRSR, section 6, "Write Status Register").
 
uint8_t GetLastStatusByte () const noexcept
 The last status byte the driver read, by any call, for logs: 0xFF before the first. No I/O (handbook KB-CPP-129).
 
Result< uint8_t > ReadRawStatus () noexcept
 Read the status register once: one RDSR transfer, no wait, no retry, no decoding and no check of the byte (handbook KB-CPP-129).
 

Detailed Description

template<SpiPort Port>
class at25040b::AT25040B< Port >

Driver for one AT25010B, AT25020B or AT25040B on a platform port.

Lifecycle: construct with the configuration (no I/O), then EnsureInitialized(), the one way to start (bus up, identity check), use, optionally Deinitialize(). Every call that touches the chip returns Error::NotInitialized until EnsureInitialized() has succeeded; no call starts the chip as a side effect, so a probe happens only when you ask for it.

Every call that reads or writes the array first reads the status and, if a write cycle runs, waits for it (at most Config::write_timeout_us): it never sends an instruction the chip would ignore. Every write and every block-protection change waits for its own write cycle before it returns, so the next call finds the chip ready.

Optional port hooks, found at compile time:

Hook Used for Without it
bool GpioSet(CtrlPin, GpioSignal) noexcept WP: released (high) only while a write, a block-protection change or the identity check runs; parked (low) after, on success and failure WP must be tied high for writes (or low, read-only: set Config::check_write_enable = false)
void Log(LogLevel, const char* message) noexcept One line per lifecycle event or failure Nothing is logged

A hook declared with the wrong signature (for example void GpioSet(...)) is a compile error. The driver never drives HOLD: tie it high (a HOLD strapped to CS makes every status read fail).

Template Parameters
PortYour class derived from SpiInterface<Port>.

Constructor & Destructor Documentation

◆ AT25040B()

template<SpiPort Port>
at25040b::AT25040B< Port >::AT25040B ( Port &  port,
const Config &  config = {} 
)
inlineexplicitnoexcept

Bind the driver to a port and store the configuration. No I/O, cannot fail.

Parameters
portThe port; it must outlive the driver.
configChecked by EnsureInitialized(), before any I/O.

Member Function Documentation

◆ ApplyConfig()

template<SpiPort Port>
Result< void > at25040b::AT25040B< Port >::ApplyConfig ( const Config &  config)
noexcept

Replace the configuration. Never any I/O: the chip has no setting to write. The variant and the checks apply from the next call; check_write_enable from the next start.

Parameters
configChecked with Validate().
Returns
Ok or InvalidArgument (the stored configuration is unchanged).

◆ Deinitialize()

template<SpiPort Port>
Result< void > at25040b::AT25040B< Port >::Deinitialize ( )
noexcept

Leave the chip safe and mark the driver uninitialised: WRDI, then WP parked.

The driver is uninitialised afterwards even if a step failed; the next EnsureInitialized() runs the identity check again, which is how a handler probes the chip again. On an uninitialised driver it does nothing and returns Ok.

Returns
Ok, Bus (WRDI failed) or Pin (WP could not be parked; reported when both steps fail, since WP left released is the state the caller must act on).

◆ EnsureInitialized()

template<SpiPort Port>
Result< void > at25040b::AT25040B< Port >::EnsureInitialized ( )
noexcept

Check that an AT25xxxB answers, once: the only way to initialise the driver.

Brings the bus up, parks WP (with GpioSet()), then checks the identity, strongest test first: the status is read until it is not busy (a write cycle may still run after an MCU reset), then once more, and both reads must be the same idle status (bits 7 to 4 and RDY clear). With Config::check_write_enable (the default) it then releases WP, clears the latch if it was set (WRDI), sends WREN and reads WEN = 1, sends WRDI and reads WEN = 0, and parks WP: a bus whose MISO floats or is stuck cannot pass this, and nothing is programmed. Without it, the first kIdentityReadBytes are read twice and must be equal. After it succeeds, later calls return Ok at once with no I/O; after it fails, the next call starts again from the beginning.

Returns
Ok, InvalidArgument (the configuration fails Validate(); no I/O), Bus, Pin (the WP hook failed), NoDevice (status 0xFF throughout Config::write_timeout_us), DeviceIdMismatch or BusNoise.

◆ GetBlockProtection()

template<SpiPort Port>
Result< BlockProtect > at25040b::AT25040B< Port >::GetBlockProtection ( )
noexcept

The block protection level, from the status (Table 6-4). Waits for a running write cycle first.

Returns
The level, or NotInitialized, Bus, Timeout or BusNoise.

◆ GetCapacityBytes()

template<SpiPort Port>
std::size_t at25040b::AT25040B< Port >::GetCapacityBytes ( ) const
inlinenoexcept
Returns
The array size of the configured variant, in bytes. No I/O.

◆ GetConfig()

template<SpiPort Port>
const Config & at25040b::AT25040B< Port >::GetConfig ( ) const &
inlinenoexcept
Returns
The configuration last applied or stored. No I/O.

◆ GetLastStatusByte()

template<SpiPort Port>
uint8_t at25040b::AT25040B< Port >::GetLastStatusByte ( ) const
inlinenoexcept

The last status byte the driver read, by any call, for logs: 0xFF before the first. No I/O (handbook KB-CPP-129).

Returns
After a failed EnsureInitialized(), 0xFF means MISO floats high (or a write cycle never ended), 0x05 an echo of the RDSR opcode, 0x00 an idle chip or MISO stuck low.

◆ IsInitialized()

template<SpiPort Port>
bool at25040b::AT25040B< Port >::IsInitialized ( ) const
inlinenoexcept
Returns
true after a successful EnsureInitialized() and before Deinitialize(). No I/O.

◆ Read()

template<SpiPort Port>
Result< void > at25040b::AT25040B< Port >::Read ( uint16_t  address,
std::span< uint8_t >  out,
Verify  verify = Verify::None 
)
noexcept

Read out.size() bytes from address (sequential READ, section 6, "Read Sequence").

Waits for a running write cycle first (two status reads on an idle chip: the idle status is confirmed). The read is split into transfers of at most kReadChunkBytes data bytes. With Verify::None each is read once: 2 + ceil(n / 16) transfers for n bytes. With Verify::ReadBack each is read twice and compared (BusNoise): 2 + 2 x ceil(n / 16) transfers, twice the bus time. The range never wraps: the chip would roll over to address 0, the driver refuses.

Parameters
addressFirst address, below GetCapacityBytes().
outWhere the bytes go: at least 1 byte, address + out.size() at most GetCapacityBytes(). A std::array or a C array converts to it.
verifyVerify::None (the default) or Verify::ReadBack.
Returns
Ok, NotInitialized, InvalidArgument (empty or out-of-range, or verify not an enumerator; nothing sent, out untouched), Bus, Timeout or BusNoise. After a failure past the argument checks, every byte of out is 0: no partial data is left behind.

◆ ReadRawStatus()

template<SpiPort Port>
Result< uint8_t > at25040b::AT25040B< Port >::ReadRawStatus ( )
noexcept

Read the status register once: one RDSR transfer, no wait, no retry, no decoding and no check of the byte (handbook KB-CPP-129).

For bring-up and diagnostics. RDSR has no side effect on the chip (section 6, "Read Status Register") and works during a write cycle (it then reads 0xFF). The byte is also kept for GetLastStatusByte().

Returns
The byte as it came off MISO, or NotInitialized or Bus.

◆ ReadStatus()

template<SpiPort Port>
Result< Status > at25040b::AT25040B< Port >::ReadStatus ( )
noexcept

One status read (RDSR), decoded. Does not wait: during a write cycle it returns busy = true.

Returns
The status, or NotInitialized, Bus, or BusNoise (a byte that is neither idle nor busy).

◆ SetBlockProtection()

template<SpiPort Port>
Result< void > at25040b::AT25040B< Port >::SetBlockProtection ( BlockProtect  level)
noexcept

Set BP1:BP0 (WRSR, section 6, "Write Status Register").

The bits are non-volatile and take a write cycle like a WRITE, so the call waits for it and then reads the level back. When the chip already holds level, nothing is written. WP is released for the call and parked after, as for Write().

Parameters
levelThe new level.
Returns
Ok, NotInitialized, InvalidArgument (not an enumerator; nothing sent), Bus, Pin (the WP hook failed), Timeout, BusNoise, WriteProtected or WriteMismatch (the level read back is not level).

◆ Write()

template<SpiPort Port>
Result< void > at25040b::AT25040B< Port >::Write ( uint16_t  address,
std::span< const uint8_t >  data,
Verify  verify = Verify::None 
)
noexcept

Write data from address: one WRITE and one write cycle per 8-byte page.

Reads the status first and refuses a range that overlaps the block-protected part (BlockProtected) before sending anything else. Then, with WP released: per page WREN, a status read that must show WEN = 1 (WriteProtected otherwise), the WRITE, a wait for the write cycle (Timeout after Config::write_timeout_us), a status that must show WEN = 0 again (WriteMismatch when the chip ignored the WRITE; this reuses the last poll, no extra transfer) and, with Verify::ReadBack, a read back (WriteMismatch). WP is parked after, on success and failure; a failure after WREN sends WRDI, so the latch is not left set.

Cost with Verify::None: 2 status reads, then per page WREN, RDSR, WRITE and the status polls of the write cycle (at least 2: the idle status is confirmed), so 2 + 5 x pages transfers plus one RDSR per extra 100 µs poll. Verify::ReadBack adds one READ per page.

After a failure, the pages before the failing one hold the new data (and were read back, with Verify::ReadBack); the failing page may hold old, new or, after a failed WRITE transfer, partly written data; nothing after it and nothing outside the range is touched.

Parameters
addressFirst address, below GetCapacityBytes().
dataThe bytes to write: at least 1, address + data.size() at most GetCapacityBytes(). A std::array or a C array converts to it.
verifyVerify::None (the default) or Verify::ReadBack.
Returns
Ok, NotInitialized, InvalidArgument (nothing sent; also for a verify that is not an enumerator), Bus, Pin (the WP hook failed), Timeout, BusNoise, BlockProtected, WriteProtected or WriteMismatch.

The documentation for this class was generated from the following file: