Mistake on this page?
Report an issue in GitHub or email us


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 BlockDeviceget_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,
 * 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.
    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);

    // 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]);

    // Deinitialize the block device.
    err = bd->deinit();
    printf("bd->deinit -> %d\n", err);

    printf("--- done! ---\n");

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.