PebbleOS v4.47.0-512-g5285d4236
Loading...
Searching...
No Matches
flash.h File Reference
#include <stdatomic.h>
#include <stddef.h>
#include <stdint.h>
#include <pbl/device.h>
#include <pbl/kernel/mutex.h>
#include <pbl/kernel/sem.h>
#include <pbl/kernel/thread.h>
#include <pbl/kernel/work.h>

Data Structures

struct  pbl_flash_geometry
 Flash geometry. More...
 
struct  pbl_flash_otp_info
 Organization of the user one-time programmable (OTP) area. More...
 
struct  pbl_flash_otp_cell
 A named range of the OTP area. More...
 
struct  pbl_flash_otp_layout
 Named ranges of the OTP area, as laid out by the board. More...
 
struct  pbl_flash_ops
 Flash driver operations. More...
 
struct  pbl_flash
 A flash. More...
 

Macros

#define PAGE_SIZE_BYTES   (0x100)
 
#define SECTOR_SIZE_BYTES   (0x10000)
 
#define SECTOR_ADDR_MASK   (~(SECTOR_SIZE_BYTES - 1))
 
#define SUBSECTOR_SIZE_BYTES   (0x1000)
 
#define SUBSECTOR_ADDR_MASK   (~(SUBSECTOR_SIZE_BYTES - 1))
 
#define PBL_FLASH_OTP_CELL(_name, _offset, _len)    {.name = (_name), .offset = (_offset), .len = (_len)}
 Initializer for a struct pbl_flash_otp_cell.
 
#define PBL_FLASH_STATE_DEFINE(sym)
 Define the class state of flash sym, for the PBL_FLASH_*_DEFINE() macro of a driver.
 
#define PBL_FLASH_INIT(sym, _name, _parent, _ops, _geometry, _otp, _otp_layout)
 Initializer for the struct pbl_flash of flash sym.
 

Typedefs

typedef void(* pbl_flash_erase_cb_t) (int status, void *arg)
 Completion callback of pbl_flash_erase_async().
 
typedef void(* pbl_flash_pm_fn_t) (void *arg)
 Function run while the flash is powered down, see pbl_flash_power_down().
 

Functions

static const struct pbl_flash_geometry * pbl_flash_get_geometry (const struct pbl_flash *flash)
 Get the geometry of a flash.
 
static bool pbl_flash_in_coredump (const struct pbl_flash *flash)
 Check whether the flash runs in coredump mode, for drivers.
 
void pbl_flash_set_map (const struct pbl_flash *flash, const void *ptr, uint32_t len)
 Declare where the CPU reads the flash directly, for drivers.
 
int pbl_flash_read (const struct pbl_flash *flash, uint32_t addr, void *buf, size_t len)
 Read data.
 
int pbl_flash_write (const struct pbl_flash *flash, uint32_t addr, const void *buf, size_t len)
 Program data into an erased range.
 
int pbl_flash_erase (const struct pbl_flash *flash, uint32_t addr, size_t len)
 Erase a range.
 
int pbl_flash_erase_async (const struct pbl_flash *flash, uint32_t addr, size_t len, pbl_flash_erase_cb_t cb, void *arg)
 Erase a range, returning once the erase has started.
 
bool pbl_flash_is_erased (const struct pbl_flash *flash, uint32_t addr, size_t len)
 Check whether a range is erased.
 
int pbl_flash_protect (const struct pbl_flash *flash, uint32_t addr, size_t len)
 Refuse writes and erases in a range, replacing the previous one.
 
int pbl_flash_unprotect (const struct pbl_flash *flash)
 Allow writes and erases everywhere.
 
void pbl_flash_stop (const struct pbl_flash *flash)
 Wait for the erase in progress, if any, and return the hardware to the state the boot code expects, before a reset.
 
int pbl_flash_coredump_init (const struct pbl_flash *flash)
 Re-initialize the flash for use from a fault handler.
 
void pbl_flash_power_down (const struct pbl_flash *flash, pbl_flash_pm_fn_t fn, void *arg)
 Power the flash down while a function runs, with interrupts disabled.
 
int pbl_flash_pm_suspend (const struct pbl_flash *flash)
 Power the flash down until pbl_flash_pm_resume(), with interrupts disabled.
 
void pbl_flash_pm_resume (const struct pbl_flash *flash)
 Power the flash back up after pbl_flash_pm_suspend().
 
uint32_t pbl_flash_crc32 (const struct pbl_flash *flash, uint32_t addr, size_t len)
 CRC-32 of a range.
 
uint32_t pbl_flash_crc32_legacy (const struct pbl_flash *flash, uint32_t addr, size_t len)
 Legacy checksum of a range, as used by firmware images and resources.
 
One-time programmable area

The user OTP area of drivers that select FLASH_OTP: n_regions regions of region_len bytes, region i starting at offset i * region_len.

OTP bits are programmed like the main array, from erased (1) to 0, and a locked region can no longer be programmed or erased. Locking is irreversible: only the recovery firmware builds it, and it is never done implicitly. The board names the ranges it stores data in as cells.

int pbl_flash_otp_get_info (const struct pbl_flash *flash, struct pbl_flash_otp_info *info)
 Get the OTP organization.
 
int pbl_flash_otp_read (const struct pbl_flash *flash, uint32_t offs, void *buf, size_t len)
 Read from the OTP area.
 
int pbl_flash_otp_write (const struct pbl_flash *flash, uint32_t offs, const void *buf, size_t len)
 Program the OTP area.
 
int pbl_flash_otp_is_locked (const struct pbl_flash *flash, uint8_t region, bool *locked)
 Check whether an OTP region is locked.
 
int pbl_flash_otp_lock (const struct pbl_flash *flash, uint8_t region)
 Lock an OTP region forever.
 
int pbl_flash_otp_erase (const struct pbl_flash *flash, uint8_t region)
 Erase an OTP region.
 
const struct pbl_flash_otp_cell * pbl_flash_otp_cell_get (const struct pbl_flash *flash, const char *name)
 Find an OTP cell by name.
 

Variables

const struct pbl_flash *const FLASH
 The board's storage flash.
 

Macro Definition Documentation

◆ PAGE_SIZE_BYTES

#define PAGE_SIZE_BYTES   (0x100)

◆ SECTOR_ADDR_MASK

#define SECTOR_ADDR_MASK   (~(SECTOR_SIZE_BYTES - 1))

◆ SECTOR_SIZE_BYTES

#define SECTOR_SIZE_BYTES   (0x10000)

◆ SUBSECTOR_ADDR_MASK

#define SUBSECTOR_ADDR_MASK   (~(SUBSECTOR_SIZE_BYTES - 1))

◆ SUBSECTOR_SIZE_BYTES

#define SUBSECTOR_SIZE_BYTES   (0x1000)