AT25040B Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Enumerations | Functions | Variables
Driver types

Errors, results, variants and configuration. More...

Classes

struct  at25040b::Result< T >
 The value of a call, or why there is none. More...
 
struct  at25040b::Result< void >
 The result of a call that returns no value. More...
 
struct  at25040b::Status
 The status register, decoded (Tables 6-2 and 6-3). More...
 
struct  at25040b::Config
 What the driver is told about the board. The chip itself has nothing to configure: its only setting, the block protection, is non-volatile and set with SetBlockProtection(). More...
 

Enumerations

enum class  at25040b::Error : uint8_t {
  at25040b::Error::Ok = 0 , at25040b::Error::NotInitialized = 1 , at25040b::Error::InvalidArgument = 2 , at25040b::Error::Bus = 3 ,
  at25040b::Error::Timeout = 4 , at25040b::Error::DeviceIdMismatch = 5 , at25040b::Error::Crc = 6 , at25040b::Error::Busy = 7 ,
  at25040b::Error::DeviceFault = 8 , at25040b::Error::Unsupported = 9 , at25040b::Error::NoDevice = 16 , at25040b::Error::BusNoise = 17 ,
  at25040b::Error::WriteProtected = 18 , at25040b::Error::BlockProtected = 19 , at25040b::Error::WriteMismatch = 20 , at25040b::Error::Pin = 21
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  at25040b::LogLevel : uint8_t { at25040b::LogLevel::Error = 0 , at25040b::LogLevel::Warning , at25040b::LogLevel::Info , at25040b::LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  at25040b::Variant : uint8_t { at25040b::Variant::At25010b = 0 , at25040b::Variant::At25020b = 1 , at25040b::Variant::At25040b = 2 }
 Which part of the family is fitted. The chip cannot tell its size, so it is configured. More...
 
enum class  at25040b::BlockProtect : uint8_t { at25040b::BlockProtect::None = 0 , at25040b::BlockProtect::UpperQuarter = 1 , at25040b::BlockProtect::UpperHalf = 2 , at25040b::BlockProtect::All = 3 }
 Block write protection level, BP1:BP0 in the status register (Table 6-4). More...
 
enum class  at25040b::Verify : uint8_t { at25040b::Verify::None = 0 , at25040b::Verify::ReadBack = 1 }
 Extra verification for one Read() or Write() call, chosen per call. More...
 

Functions

constexpr const char * at25040b::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr std::size_t at25040b::CapacityBytes (Variant variant) noexcept
 Array size of a variant.
 
constexpr std::size_t at25040b::ProtectedFrom (Variant variant, BlockProtect level) noexcept
 First protected address of a protection level (Table 6-4).
 
constexpr Error at25040b::Validate (const Config &config) noexcept
 Check a configuration without touching the chip.
 
constexpr const char * at25040b::GetDriverVersion () noexcept
 
constexpr uint32_t at25040b::GetDriverVersionMajor () noexcept
 
constexpr uint32_t at25040b::GetDriverVersionMinor () noexcept
 
constexpr uint32_t at25040b::GetDriverVersionPatch () noexcept
 

Variables

constexpr std::size_t at25040b::kPageSizeBytes = 8
 Bytes per page: a WRITE never crosses an 8-byte page (section 6, "Write Sequence").
 
constexpr std::size_t at25040b::kReadChunkBytes = 16
 Data bytes per READ transfer: Read() splits longer requests into transfers of at most this many data bytes.
 
constexpr std::size_t at25040b::kMaxTransferBytes = 2 + kReadChunkBytes
 Longest transfer the driver asks of the port: opcode, address byte and kReadChunkBytes.
 
constexpr uint32_t at25040b::kWriteCycleMaxUs = 5000
 Longest self-timed write cycle t_WC, in microseconds (Table 4-3, maximum, every supply).
 
constexpr uint32_t at25040b::kPollIntervalUs = 100
 Time between two status reads while the driver waits for a write cycle, in microseconds.
 
constexpr uint32_t at25040b::kWriteTimeoutMaxUs = 1000000
 Longest Config::write_timeout_us the driver accepts, in microseconds (one second).
 
constexpr std::size_t at25040b::kIdentityReadBytes = 8
 Bytes from address 0 that EnsureInitialized() reads twice when check_write_enable is off.
 

Detailed Description

Errors, results, variants and configuration.

Enumeration Type Documentation

◆ BlockProtect

enum class at25040b::BlockProtect : uint8_t
strong

Block write protection level, BP1:BP0 in the status register (Table 6-4).

The protected part is always at the top of the array; the addresses depend on the variant (ProtectedFrom()).

Enumerator
None 

BP1:BP0 = 00: nothing protected. The value of a new part.

UpperQuarter 

01: the top quarter is read-only (0x180 to 0x1FF on the AT25040B).

UpperHalf 

10: the top half is read-only (0x100 to 0x1FF on the AT25040B).

All 

11: the whole array is read-only.

◆ Error

enum class at25040b::Error : uint8_t
strong

Why a call failed. Every call of the driver returns one of these in its Result.

Values 0 to 9 are the shared base set; chip-specific values start at 16. [[nodiscard]] on the type: a function that returns a bare Error cannot have it ignored either (KB-CPP20-037).

Enumerator
Ok 

The call succeeded.

NotInitialized 

EnsureInitialized() has not succeeded, or Deinitialize() ran since.

InvalidArgument 

An argument or a Config field is out of range; nothing was sent.

Bus 

A transfer hook (Transfer(), EnsureInitialized()) returned false.

Timeout 

After the start, the status read busy (0xFF) for longer than Config::write_timeout_us: a write cycle that does not end, or the chip was unplugged since and MISO floats high.

DeviceIdMismatch 

At start-up, the bus answers but not like an AT25xxxB: the status is neither idle nor busy (0x05 is MOSI echoed onto MISO), or the write enable latch did not follow WREN and WRDI (MISO stuck low, no chip, or WP held low with Config::check_write_enable on).

Crc 

Not returned by this driver (the chip sends no CRC).

Busy 

Not returned by this driver: every call waits for a write cycle.

DeviceFault 

Not returned by this driver (the chip reports no faults).

Unsupported 

Not returned by this driver.

NoDevice 

At start-up, the status read 0xFF for longer than Config::write_timeout_us: nothing drives MISO (pulled or floating high), so no chip answers.

BusNoise 

A reply no working chip gives: two reads of the same thing differed, or after the start a status byte was neither idle nor busy.

WriteProtected 

WREN did not set the write enable latch: the WP pin is low (tied low, or the port's WP hook did not release it), or the WREN frame was lost. Nothing was written.

BlockProtected 

The range lies in the block-protected part of the array (BP1, BP0); only the status was read, nothing was written.

WriteMismatch 

After a write the chip does not hold what was sent: the read-back differed (Verify::ReadBack), the write enable latch was still set after the write (the chip ignored it), or BP1 and BP0 did not take.

Pin 

The port's GpioSet() could not drive WP (release or park); the name and meaning the handbook gives a failed pin hook (KB-CPP-047).

◆ LogLevel

enum class at25040b::LogLevel : uint8_t
strong

Severity passed to the optional Log() hook.

Enumerator
Error 

A call failed.

Warning 

Something unexpected that the driver recovered from.

Info 

Lifecycle events: initialised.

Debug 

Detail for bring-up.

◆ Variant

enum class at25040b::Variant : uint8_t
strong

Which part of the family is fitted. The chip cannot tell its size, so it is configured.

The three parts share the instruction set, the 8-byte page and the status register; only the array size differs, and only the AT25040B uses address bit A8 (datasheet "Description", Table 6-1 note 1).

Enumerator
At25010b 

128 bytes (1 Kbit).

At25020b 

256 bytes (2 Kbit).

At25040b 

512 bytes (4 Kbit), A8 in the opcode. The default.

◆ Verify

enum class at25040b::Verify : uint8_t
strong

Extra verification for one Read() or Write() call, chosen per call.

The datasheet needs neither: Verify::None, the default, sends only what it needs, plus the status reads that keep a call off a busy chip. Verify::ReadBack costs transfers on the bus and is for a caller that has no CRC or signature of its own over the data.

Enumerator
None 

Each chunk read once; no page read back. The default.

ReadBack 

Read(): each chunk read twice and compared (BusNoise), twice the READs. Write(): each page read back and compared (WriteMismatch), one READ more per page.

Function Documentation

◆ CapacityBytes()

constexpr std::size_t at25040b::CapacityBytes ( Variant  variant)
constexprnoexcept

Array size of a variant.

Parameters
variantThe part.
Returns
128, 256 or 512; 0 for a value that is not an enumerator.

◆ GetDriverVersion()

constexpr const char * at25040b::GetDriverVersion ( )
constexprnoexcept
Returns
The driver version, e.g. "0.1.0", from the generated at25040b_version.h. No I/O.

◆ GetDriverVersionMajor()

constexpr uint32_t at25040b::GetDriverVersionMajor ( )
constexprnoexcept
Returns
The major version. No I/O.

◆ GetDriverVersionMinor()

constexpr uint32_t at25040b::GetDriverVersionMinor ( )
constexprnoexcept
Returns
The minor version. No I/O.

◆ GetDriverVersionPatch()

constexpr uint32_t at25040b::GetDriverVersionPatch ( )
constexprnoexcept
Returns
The patch version. No I/O.

◆ ProtectedFrom()

constexpr std::size_t at25040b::ProtectedFrom ( Variant  variant,
BlockProtect  level 
)
constexprnoexcept

First protected address of a protection level (Table 6-4).

Parameters
variantThe part.
levelThe level.
Returns
The lowest read-only address; CapacityBytes(variant) when nothing is protected.

◆ ToString()

constexpr const char * at25040b::ToString ( Error  error)
constexprnoexcept

The name of an error, for logs.

Parameters
errorThe error.
Returns
A static string such as "Timeout"; "Unknown" for a value that is not an enumerator.

◆ Validate()

constexpr Error at25040b::Validate ( const Config &  config)
constexprnoexcept

Check a configuration without touching the chip.

Parameters
configThe configuration.
Returns
Error::Ok, or Error::InvalidArgument when the variant is not an enumerator or the timeout is below kWriteCycleMaxUs or above kWriteTimeoutMaxUs.

Variable Documentation

◆ kReadChunkBytes

constexpr std::size_t at25040b::kReadChunkBytes = 16
inlineconstexpr

Data bytes per READ transfer: Read() splits longer requests into transfers of at most this many data bytes.

The datasheet sets no limit (a READ continues through the array, section 6, "Read Sequence"), so this is a design choice, sized by what it costs:

  • The port: kMaxTransferBytes (18) is the longest transfer a port must take, and the driver object holds two buffers of that size (36 bytes, see detail::EepromBus). A whole-array chunk would make that 2 x 514 bytes in every driver object and every port's DMA descriptor.
  • The bus: CS goes high after each chunk, so a long Read() never holds a shared bus for more than 18 x 8 = 144 SCK cycles: 29 us at the 5 MHz of the full supply range, 7.2 us at 20 MHz.
  • The overhead: 2 command bytes per 16 data bytes (11 %); halving the chunk to 8 would cost 20 %, doubling it to 32 saves 5 % of the bus time and doubles the buffers.
  • Verify::ReadBack: two whole pages per chunk, so the compare buffer is 16 bytes.

Not a Config value: the buffers are sized at compile time from it, and no setting of it changes what the chip does. A port with a smaller transfer limit cannot use this driver as it is.