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


SDBlockDevice class hierarchy

You can use the Mbed OS SD card block device, so applications can read and write data to flash storage cards using the standard POSIX File API programming interface. Applications use the FAT filesystem and SD block device components to persistently store data on SDCards. The SD block device uses the SD card SPI-mode of operation, which is a subset of possible SD card functionality.

To configure this class, please see our BlockDevice configuration documentation.

How to wire an external SD-card module to a developer board

How to wire an external SD-card module to a developer board

  1. In mbed_app.json, override the SD pin mapping based on the wiring. For example:

    "sd.SPI_MOSI" : "PC_3",
    "sd.SPI_MISO" : "PC_2",
    "sd.SPI_CLK"  : "PC_7",
    "sd.SPI_CS"   : "PB_9",
  2. Add the SD component to mbed_app.json:

    "target.components_add" : ["SD"],
  3. Ensure your micro SD card is plugged in to your device.

  4. Connect the device to your computer with a USB cable.

The device appears as removable storage.

Tip: You may need to remove and manually format your micro SD card, flash the binary to the device and then reinsert your micro SD card.

Mbed OS file system software component stack

|                      |
|    Application       |        // This application uses the POSIX File API
|                      |        // to read/write data to persistent storage backends.

------------------------        // POSIX File API (ISO).

|                      |
|     libc             |        // The standard c library implementation
|                      |        // for example, newlib.

------------------------        // sys_xxx equivalent API.

|                      |
|  mbed_retarget.cpp   |        // Target specific mapping layer.
|                      |

------------------------        // File system Upper Edge API.

|                      |
|     File System      |        // File system wrappers and implementation.
|                      |

------------------------        // FS Lower Edge API (Block Store Interface).

|    Block API         |
|  Device Block device |        // The SD card block device, for example.
|  e.g. SDBlockDevice  |

------------------------        // SPI.h interface.

|                      |
|       SPI            |        // SPI subsystem (C++ classes and C-HAL implementation).
|                      |

Figure 1. Mbed OS generic architecture of filesystem software stack.

The figure above shows the Mbed OS software component stack used for data storage on the SD card:

  • At the top level is the application component, which uses the standard POSIX File API to read and write application data to persistent storage.
  • The newlib standard library (libc) stdio.h interface (POSIX File API) implementation is optimized for resource-limited embedded systems.
  • mbed_retarget.cpp implements the libc backend file OS handlers and maps them to the file system.
  • The file system code (hosted in mbed-os) is composed of 2 parts: the FAT file system implementation code and the file system classes that present a consistent API to the retarget module for different (third-party) file system implementations.
  • The Block API. The SDCard block device is a persistent storage block device.
  • The SPI module provides the Mbed OS SPI API.

Mbed OS erase for SDBlockDevice

There is a difference between erase as usually defined for SD cards and the definition in Mbed OS: In Mbed OS, erase prepares the block device for writing. Because an SD card doesn't need preparation, erase is not applicable on SDBlockDevice; it's a no-op operation.

SDBlockDevice class reference

Public Member Functions
 SDBlockDevice (PinName mosi=NC, PinName miso=NC, PinName sclk=NC, PinName cs=NC, uint64_t hz=1000000, bool crc_on=0)
 Creates an SDBlockDevice on a SPI bus specified by pins (using dynamic pin-map) More...
 SDBlockDevice (const spi_pinmap_t &spi_pinmap, PinName cs=NC, uint64_t hz=1000000, bool crc_on=0)
 Creates an SDBlockDevice on a SPI bus specified by pins (using static pin-map) More...
virtual int init ()
 Initialize a block device. More...
virtual int deinit ()
 Deinitialize a block device. More...
virtual int read (void *buffer, mbed::bd_addr_t addr, mbed::bd_size_t size)
 Read blocks from a block device. More...
virtual int program (const void *buffer, mbed::bd_addr_t addr, mbed::bd_size_t size)
 Program blocks to a block device. More...
virtual int trim (mbed::bd_addr_t addr, mbed::bd_size_t size)
 Mark blocks as no longer in use. More...
virtual mbed::bd_size_t get_read_size () const
 Get the size of a readable block. More...
virtual mbed::bd_size_t get_program_size () const
 Get the size of a programmable block. More...
virtual mbed::bd_size_t size () const
 Get the total size of the underlying device. More...
virtual void debug (bool dbg)
 Enable or disable debugging. More...
virtual int frequency (uint64_t freq)
 Set the transfer frequency. More...
virtual const char * get_type () const
 Get the BlockDevice class type. More...
virtual int sync ()
 Ensure data on storage is in sync with the driver. More...
virtual int erase (bd_addr_t addr, bd_size_t size)
 Erase blocks on a block device. 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 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...
Static Public Member Functions
static BlockDeviceget_default_instance ()
 Return the default block device. More...

SDBlockDevice example application

#include "mbed.h"
#include "SDBlockDevice.h"

// Instantiate the SDBlockDevice by specifying the SPI pins connected to the SDCard
// socket. The PINS are:
//     MOSI (Master Out Slave In)
//     MISO (Master In Slave Out)
//     SCLK (Serial Clock)
//     CS (Chip Select)
uint8_t block[512] = "Hello World!\n";

int main()
    // Call the SDBlockDevice instance initialisation method
    if (0 != sd.init()) {
        printf("Init failed \n");
        return -1;
    printf("sd size: %llu\n",         sd.size());
    printf("sd read size: %llu\n",    sd.get_read_size());
    printf("sd program size: %llu\n", sd.get_program_size());
    printf("sd erase size: %llu\n",   sd.get_erase_size());

    // Set the frequency
    if (0 != sd.frequency(5000000)) {
        printf("Error setting frequency \n");

    if (0 != sd.erase(0, sd.get_erase_size())) {
        printf("Error Erasing block \n");

    // Write data block to the device
    if (0 == sd.program(block, 0, 512)) {
        // Read the data block from the device
        if (0 == sd.read(block, 0, 512)) {
            // Print the contents of the block
            printf("%s", block);

    // Call the SDBlockDevice instance de-initialisation method

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.