BlockDevice
BlockDevice class hierarchy
The BlockDevice API provides an interface for access to block-based storage. You can use a block device to back a full file system or write to it directly.
The most common types of block-based storage are different forms of flash, but the BlockDevice API can support many different forms of storage, such as SD cards, spinning disks and heap backed storage.
Block device operations
A block device can perform three operations:
- Read a region of data from storage.
- Erase a region of data in storage.
- Program a region of data that has previously been erased.
A full write to a block device involves first erasing the region of memory you plan to program and then programming the data to the region of memory. The reason for this separation is that block devices can have different limitations for erasing and writing to regions on the device.
Block device blocks
Block devices are byte addressable but operate in units of "blocks". There are three types of blocks for the three types of block device operations: read blocks, erase blocks and program blocks.
Note: For many devices, erase blocks can be large (for example, 4 KiB for SPI flash). As a result, we discourage storing an entire erase block in RAM. Instead, we suggest first erasing a block and then programming in units of the program block.
Erased blocks
The state of an erased block is undefined. The data stored on the block isn't decided until you program the block. This allows the widest range of support for different types of storage.
BlockDevice get default instance
The Mbed OS configuration allows you to add block devices as components using the targets.json
file or target overrides in the application configuration file.
For details regarding how to configure the default block device please refer to the storage configuration guide
BlockDevice class reference
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... |
BlockDevice example
/* mbed Microcontroller Library
* Copyright (c) 2006-2013 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include "mbed.h"
#include "BlockDevice.h"
#include <stdio.h>
#include <algorithm>
// This takes the system's default block device.
BlockDevice *bd = BlockDevice::get_default_instance();
// Instead of the default block device, you can define your own block device.
// For example, HeapBlockDevice with a size of 2048 bytes, read size 1, write size 1, and erase size 512.
// #include "HeapBlockDevice.h"
// BlockDevice *bd = new HeapBlockDevice(2048, 1, 1, 512);
// Entry point for the example:
int main()
{
printf("--- Mbed OS block device example ---\n");
// Initialize the block device.
printf("bd->init()\n");
int err = bd->init();
printf("bd->init -> %d\n", err);
// Get device geometry.
bd_size_t read_size = bd->get_read_size();
bd_size_t program_size = bd->get_program_size();
bd_size_t erase_size = bd->get_erase_size();
bd_size_t size = bd->size();
printf("--- Block device geometry ---\n");
printf("read_size: %lld B\n", read_size);
printf("program_size: %lld B\n", program_size);
printf("erase_size: %lld B\n", erase_size);
printf("size: %lld B\n", size);
printf("---\n");
// Allocate a block with enough space for our data, aligned to the
// nearest program_size. This is the minimum size necessary to write
// data to a block.
size_t buffer_size = sizeof("Hello Storage!") + program_size - 1;
buffer_size = buffer_size - (buffer_size % program_size);
char *buffer = new char[buffer_size];
// Update the buffer with the string we want to store.
strncpy(buffer, "Hello Storage!", buffer_size);
// Write data to the first block. Write occurs in two parts;
// an erase followed by a program.
printf("bd->erase(%d, %lld)\n", 0, erase_size);
err = bd->erase(0, erase_size);
printf("bd->erase -> %d\n", err);
printf("bd->program(%p, %d, %d)\n", buffer, 0, buffer_size);
err = bd->program(buffer, 0, buffer_size);
printf("bd->program -> %d\n", err);
// Clobber the buffer so we don't get old data.
memset(buffer, 0xcc, buffer_size);
// Read the data from the first block. Note that program_size must be
// a multiple of read_size, so we don't have to check for alignment.
printf("bd->read(%p, %d, %d)\n", buffer, 0, buffer_size);
err = bd->read(buffer, 0, buffer_size);
printf("bd->read -> %d\n", err);
printf("--- Stored data ---\n");
for (size_t i = 0; i < buffer_size; i += 16) {
for (size_t j = 0; j < 16; j++) {
if (i + j < buffer_size) {
printf("%02x ", buffer[i + j]);
} else {
printf(" ");
}
}
printf(" %.*s\n", buffer_size - i, &buffer[i]);
}
printf("---\n");
// Deinitialize the block device.
printf("bd->deinit()\n");
err = bd->deinit();
printf("bd->deinit -> %d\n", err);
printf("--- done! ---\n");
}