A block-oriented read/write/erase abstraction: storage is addressed as a fixed number of equally-sized blocks (hw_block_count, hw_block_size), rather than a flat byte stream - the natural shape for media that can only be written a block at a time and, for some backends, must be explicitly erased before it can be rewritten at all (hw_block_erase).
More...
|
| | Flash |
| | A Block I/O backend for the Pico's own on-chip flash - the same physical flash the running program itself is stored in, not an external SPI/QSPI flash chip.
|
| |
A block-oriented read/write/erase abstraction: storage is addressed as a fixed number of equally-sized blocks (hw_block_count, hw_block_size), rather than a flat byte stream - the natural shape for media that can only be written a block at a time and, for some backends, must be explicitly erased before it can be rewritten at all (hw_block_erase).
This module only provides that raw block transport; it's meant to sit underneath higher-level systems that need one - a filesystem - not to be used as a storage format in its own right.
hw_block_t is a generic handle - hw_block_read, hw_block_write, hw_block_erase and hw_block_deinit all dispatch through a backend-supplied hw_block_callbacks_t (see src/picofuse/hw/block/private.h), so the same four calls work regardless of what's actually backing the handle. hw/flash.h's hw_block_flash_init is the only concrete backend today (on-chip flash, reserved outside the running program's own image); the same shape is intended for mass storage (SD/eMMC) and RAM-backed block devices as those get built. Handles come from a small fixed-size pool (BLOCK_MAX_CAPACITY) with a fixed amount of backend-private state embedded in each one (BLOCK_CONTEXT_SIZE), not the heap.
◆ BLOCK_CONTEXT_SIZE
| #define BLOCK_CONTEXT_SIZE 32u |
Size in bytes of backend-private state embedded in each block handle.
Override by defining BLOCK_CONTEXT_SIZE at compile time.
Definition at line 54 of file block.h.
◆ BLOCK_MAX_CAPACITY
| #define BLOCK_MAX_CAPACITY 4u |
Maximum number of concurrently active block handles.
Override by defining BLOCK_MAX_CAPACITY at compile time.
Definition at line 44 of file block.h.
◆ hw_block_count()
| size_t hw_block_count |
( |
const hw_block_t * |
block | ) |
|
Return the number of addressable blocks.
- Parameters
-
- Returns
- Number of blocks, or
0 when invalid.
◆ hw_block_deinit()
| void hw_block_deinit |
( |
hw_block_t * |
block | ) |
|
Deinitialize a block handle.
- Parameters
-
◆ hw_block_erase()
| bool hw_block_erase |
( |
hw_block_t * |
block, |
|
|
size_t |
index |
|
) |
| |
Erase one block.
- Parameters
-
| block | Block handle. |
| index | Block index to erase. |
- Return values
-
| true | Erase succeeded. |
| false | Invalid arguments or backend failure. |
◆ hw_block_read()
| bool hw_block_read |
( |
const hw_block_t * |
block, |
|
|
size_t |
index, |
|
|
void * |
dst |
|
) |
| |
Read one block into dst.
- Parameters
-
| block | Block handle. |
| index | Block index to read. |
| dst | Destination buffer of at least hw_block_size bytes. |
- Return values
-
| true | Read succeeded. |
| false | Invalid arguments or backend failure. |
◆ hw_block_size()
| size_t hw_block_size |
( |
const hw_block_t * |
block | ) |
|
Return the block size in bytes.
- Parameters
-
- Returns
- Block size in bytes, or
0 when invalid.
◆ hw_block_write()
| bool hw_block_write |
( |
hw_block_t * |
block, |
|
|
size_t |
index, |
|
|
const void * |
src |
|
) |
| |
Write one block from src.
- Parameters
-
| block | Block handle. |
| index | Block index to write. |
| src | Source buffer of at least hw_block_size bytes. |
- Return values
-
| true | Write succeeded. |
| false | Invalid arguments or backend failure. |
