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, heap backed storage and so on.

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 class reference

Public Member Functions
virtual ~BlockDevice ()
virtual int init ()=0
virtual int deinit ()=0
virtual int sync ()
virtual int read (void *buffer, bd_addr_t addr, bd_size_t size)=0
virtual int program (const void *buffer, bd_addr_t addr, bd_size_t size)=0
virtual int erase (bd_addr_t addr, bd_size_t size)
virtual int trim (bd_addr_t addr, bd_size_t size)
virtual bd_size_t get_read_size () const =0
virtual bd_size_t get_program_size () const =0
virtual bd_size_t get_erase_size () const
virtual bd_size_t get_erase_size (bd_addr_t addr) const
virtual int get_erase_value () const
virtual bd_size_t size () const =0
bool is_valid_read (bd_addr_t addr, bd_size_t size) const
bool is_valid_program (bd_addr_t addr, bd_size_t size) const
bool is_valid_erase (bd_addr_t addr, bd_size_t size) const

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 <stdio.h>
#include <algorithm>

// Block devices
#include "SPIFBlockDevice.h"
#include "DataFlashBlockDevice.h"
#include "SDBlockDevice.h"
#include "HeapBlockDevice.h"

// Physical block device, can be any device that supports the BlockDevice API
SPIFBlockDevice bd(

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

    // Read what is currently stored on the block device. We haven't written
    // yet so this may be garbage
    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]);

    // Update buffer with our string we want to store
    strncpy(buffer, "Hello Storage!", buffer_size);

    // Write data to 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 the program_size must be
    // a multiple of the 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.