AT25040B Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Namespaces | Classes | Concepts | Enumerations | Functions | Variables
at25040b Namespace Reference

The AT25040B driver: everything it declares lives here; internals in detail. More...

Namespaces

namespace  reg
 Opcodes and bit masks of the chip, as constexpr values.
 

Classes

class  AT25040B
 Driver for one AT25010B, AT25020B or AT25040B on a platform port. More...
 
struct  BusTiming
 The SPI timing limits of one supply range (Table 4-3). More...
 
struct  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...
 
struct  Result
 The value of a call, or why there is none. More...
 
struct  Result< void >
 The result of a call that returns no value. More...
 
class  SpiInterface
 CRTP base of the platform SPI port. More...
 
struct  Status
 The status register, decoded (Tables 6-2 and 6-3). More...
 

Concepts

concept  SpiPort
 Satisfied by a class that derives from SpiInterface<Port> and implements the required hooks with exactly the types above, noexcept and returning bool. DelayUs() is checked where the driver first waits.
 

Enumerations

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

Functions

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

Variables

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

Bus requirements

What the AT25010B/020B/040B needs from the SPI bus (datasheet "Features", section 4.3 Table 4-3, section 5). A port and a board configuration check their settings against these with static_assert (handbook KB-CPP-123). The scalar limits hold over the whole supply range (1.8 V to 5.5 V); BusTimingAt() gives the faster limits of a higher supply.

constexpr uint8_t kSpiMode = 0
 
constexpr uint8_t kSpiModeAlternate = 3
 The other SPI mode the chip accepts: CPOL 1, CPHA 1 ("Features").
 
constexpr bool kMsbFirst = true
 Each byte is clocked most significant bit first (section 5, "MSB").
 
constexpr uint32_t kMaxClockHz = 5'000'000
 Highest SCK frequency over the whole supply range, f_SCK max at 1.8 V to 5.5 V (Table 4-3).
 
constexpr uint32_t kMinCsHighNs = 200
 Shortest time CS stays high between two transfers, t_CS min at 1.8 V to 5.5 V (Table 4-3).
 
constexpr uint32_t kCsSetupNs = 200
 CS low to the first SCK edge, t_CSS min at 1.8 V to 5.5 V (Table 4-3).
 
constexpr uint32_t kCsHoldNs = 200
 Last SCK edge to CS high, t_CSH min at 1.8 V to 5.5 V (Table 4-3).
 
constexpr uint32_t kDataSetupNs = 80
 SI valid before the sampling SCK edge, t_SU min at 1.8 V to 5.5 V (Table 4-3).
 
constexpr uint32_t kDataHoldNs = 80
 SI held after the sampling SCK edge, t_H min at 1.8 V to 5.5 V (Table 4-3).
 
constexpr bool kContinuousWord = false
 
constexpr uint32_t kMinSupplyMv = 1800
 Lowest supply of the family, in millivolts (Table 4-3).
 
constexpr uint32_t kMaxSupplyMv = 5500
 Highest supply of the family, in millivolts (Table 4-3).
 
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.5 V 10 MHz, 1.8 V to 5.5 V 5 MHz.
 

Detailed Description

The AT25040B driver: everything it declares lives here; internals in detail.

Enumeration Type Documentation

◆ CtrlPin

enum class at25040b::CtrlPin : uint8_t
strong

Control pins the port may drive through the optional GpioSet() hook.

Idle level (handbook KB-HW-018): WP idles ACTIVE (pin low, writes blocked), the safe state of this pin. The port drives it low before it enables the pin's output and before the first transfer, so the chip never sees WP float high; the driver releases it only around a write.

Enumerator
WriteProtect 

WP, active low on the package pin. ACTIVE (pin low) blocks every write.

◆ GpioSignal

enum class at25040b::GpioSignal : uint8_t
strong

Logical level of a control pin; the port maps it to the physical polarity.

Enumerator
INACTIVE 

The pin function is deasserted (WP: pin high, writes allowed).

ACTIVE 

The pin function is asserted (WP: pin low, writes blocked).

Function Documentation

◆ BusTimingAt()

constexpr BusTiming at25040b::BusTimingAt ( uint32_t  supply_mv)
constexprnoexcept

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.5 V 10 MHz, 1.8 V to 5.5 V 5 MHz.

Parameters
supply_mvThe lowest VCC the board can see, in millivolts.
Returns
The limits; all zero for a supply outside 1.8 V to 5.5 V.

◆ KconfigDefaults()

constexpr Config at25040b::KconfigDefaults ( )
constexprnoexcept

The configuration menuconfig selected.

Returns
Config{} with the variant, the identity check and the write timeout taken from Kconfig.

Variable Documentation

◆ kContinuousWord

constexpr bool at25040b::kContinuousWord = false
inlineconstexpr

false: the chip accepts idle SCK time between the bytes of one transfer (a static design: t_WH and t_WL have no maximum, Table 4-3). CS must stay low for the whole instruction.

◆ kSpiMode

constexpr uint8_t at25040b::kSpiMode = 0
inlineconstexpr

SPI mode the driver is tested with: CPOL 0, CPHA 0 ("Features": modes 0 and 3 are supported, the datasheet describes mode 0). The datasheet allows mode 3 as well (not verified on hardware with this driver); nothing else works.