Block Devices
Block devices are the basic building block of storage solutions in Mbed OS.
File systems are backed by blockdevice implementations. The BlockDevice API performs the low-level interactions with the hardware storage. To add your own block device implementation, we recommend you inherit from the BlockDevice class. For details on how to extend the BlockDevice interface, please refer to the and implementing BlockDevice section below.
Assumptions
Defined behavior
- Erase leaves memory as undefined. It does not set memory to a predetermined value.
Undefined behavior
- Programming without erase is undefined behavior.
Notes
Erase, program and read block sizes may not be the same; however, they must be multiples of one another.
Implementing BlockDevice
You can find the BlockDevice class on the master branch under the features/storage/blockdevice path in Mbed OS.
| Public Member Functions | |
| virtual | ~BlockDevice () |
| Lifetime of a block device. More... | |
| virtual int | init ()=0 |
| Initialize a block device. More... | |
| virtual int | deinit ()=0 |
| Deinitialize a block device. More... | |
| virtual int | sync () |
| Ensure data on storage is in sync with the driver. More... | |
| virtual int | read (void *buffer, bd_addr_t addr, bd_size_t size)=0 |
| Read blocks from a block device. More... | |
| virtual int | program (const void *buffer, bd_addr_t addr, bd_size_t size)=0 |
| Program blocks to a block device. More... | |
| virtual int | erase (bd_addr_t addr, bd_size_t size) |
| Erase blocks on a block device. More... | |
| virtual int | trim (bd_addr_t addr, bd_size_t size) |
| Mark blocks as no longer in use. More... | |
| virtual bd_size_t | get_read_size () const =0 |
| Get the size of a readable block. More... | |
| virtual bd_size_t | get_program_size () const =0 |
| Get the size of a programmable block. More... | |
| virtual bd_size_t | get_erase_size () const |
| Get the size of an erasable block. More... | |
| virtual bd_size_t | get_erase_size (bd_addr_t addr) const |
| Get the size of an erasable block given address. More... | |
| virtual int | get_erase_value () const |
| Get the value of storage when erased. More... | |
| virtual bd_size_t | size () const =0 |
| Get the total size of the underlying device. More... | |
| virtual bool | is_valid_read (bd_addr_t addr, bd_size_t size) const |
| Convenience function for checking block read validity. More... | |
| virtual bool | is_valid_program (bd_addr_t addr, bd_size_t size) const |
| Convenience function for checking block program validity. More... | |
| virtual bool | is_valid_erase (bd_addr_t addr, bd_size_t size) const |
| Convenience function for checking block erase validity. More... | |
| virtual const char * | get_type () const =0 |
| Get the BlockDevice class type. More... | |
| Static Public Member Functions | |
| static BlockDevice * | get_default_instance () |
| Return the default block device. More... | |
The primary functions to implement are:
int read(void *buffer, bd_addr_t addr, bd_size_t size);int program(void *buffer, bd_addr_t addr, bd_size_t size);int erase(bd_addr_t addr, bd_size_t size);
Testing
You can run BlockDevice tests for heap, MBR and util block devices with the following command:
mbed test -t <toolchain> -m <target> -n features-tests-filesystem-*_block_device
You can run BlockDevice tests without the file system with the following command:
mbed test -t <toolchain> -m <target> -n mbed-os-features-storage-tests-blockdevice-general_block_device -v
One way to add tests for new block devices is to copy an existing implementation, such as HeapBlockDevice, and change the block device class to your own. You can find tests under the top level TESTS folder in the Mbed OS repository.