L VD / Mbed OS mbed-os-example-filesystem-sdio

The Mbed OS file system example with sdio-driver for LPC55S69_NS and DISCO_F746NG targets

Dependencies:   sdio-glue

README.md@3:ebff5971c078, 2020-11-11 (annotated)

Committer:
elelthvd
Date:
Wed Nov 11 11:22:02 2020 +0800
Revision:
3:ebff5971c078
Parent:
0:5db1517e0856 
Add sdio-glue

Who changed what in which revision?

UserRevisionLine numberNew contents of line
elelthvd 0:5db1517e0856 1 ![](./resources/official_armmbed_example_badge.png)
elelthvd 0:5db1517e0856 2 # Getting started with the Mbed OS file system
elelthvd 0:5db1517e0856 3
elelthvd 0:5db1517e0856 4 This example demonstrates how to use the Mbed OS file system.
elelthvd 0:5db1517e0856 5
elelthvd 0:5db1517e0856 6 You can find more information about the Mbed OS file system and other related pieces of the Mbed OS storage stack [in the storage overview](https://os.mbed.com/docs/latest/reference/storage.html).
elelthvd 0:5db1517e0856 7
elelthvd 0:5db1517e0856 8 **Table of contents:**
elelthvd 0:5db1517e0856 9
elelthvd 0:5db1517e0856 10 1. [Hardware requirements](#hardware-requirements)
elelthvd 0:5db1517e0856 11 1. [Usage](#usage)
elelthvd 0:5db1517e0856 12 - [Import the example](#import-the-example)
elelthvd 0:5db1517e0856 13 - [Compile the example](#compile-the-example)
elelthvd 0:5db1517e0856 14 - [Run the example](#run-the-example)
elelthvd 0:5db1517e0856 15 - [Troubleshooting](#troubleshooting)
elelthvd 0:5db1517e0856 16 1. [Changing the file system](#changing-the-file-system)
elelthvd 0:5db1517e0856 17 1. [Changing the block device](#changing-the-block-device)
elelthvd 0:5db1517e0856 18 1. [Tested configurations](#tested-configurations)
elelthvd 0:5db1517e0856 19
elelthvd 0:5db1517e0856 20 ## Hardware requirements
elelthvd 0:5db1517e0856 21
elelthvd 0:5db1517e0856 22 This example uses a block device as storage. This can be one of:
elelthvd 0:5db1517e0856 23
elelthvd 0:5db1517e0856 24 * A built-in SPI flash, such as on the [FRDM-K82F](https://os.mbed.com/platforms/FRDM-K82F/).
elelthvd 0:5db1517e0856 25 * An external block device (one of SPI flash, DataFlash or an SD card).
elelthvd 0:5db1517e0856 26 * Simulated on a heap block device on boards with enough RAM.
elelthvd 0:5db1517e0856 27
elelthvd 0:5db1517e0856 28 This example uses an instance of the LittleFileSystem API (LittleFS) on external SPI flash.
elelthvd 0:5db1517e0856 29 The [changing the block device](#changing-the-block-device) section describes
elelthvd 0:5db1517e0856 30 how to change the file system or block device in the example.
elelthvd 0:5db1517e0856 31
elelthvd 0:5db1517e0856 32 ## Usage
elelthvd 0:5db1517e0856 33
elelthvd 0:5db1517e0856 34 #### Import the example
elelthvd 0:5db1517e0856 35
elelthvd 0:5db1517e0856 36 Make sure you have an Mbed development environment set up. [Get started with Mbed OS](https://os.mbed.com/docs/latest/tutorials/mbed-os-quick-start.html)
elelthvd 0:5db1517e0856 37 to set everything up.
elelthvd 0:5db1517e0856 38
elelthvd 0:5db1517e0856 39 From the command-line, import the example:
elelthvd 0:5db1517e0856 40
elelthvd 0:5db1517e0856 41 ```
elelthvd 0:5db1517e0856 42 mbed import mbed-os-example-filesystem
elelthvd 0:5db1517e0856 43 cd mbed-os-example-filesystem
elelthvd 0:5db1517e0856 44 ```
elelthvd 0:5db1517e0856 45
elelthvd 0:5db1517e0856 46 #### Compile the example
elelthvd 0:5db1517e0856 47
elelthvd 0:5db1517e0856 48 Invoke `mbed compile`, and specify the name of your platform and your favorite
elelthvd 0:5db1517e0856 49 toolchain (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM toolchain:
elelthvd 0:5db1517e0856 50
elelthvd 0:5db1517e0856 51 ```
elelthvd 0:5db1517e0856 52 mbed compile -m K64F -t ARM
elelthvd 0:5db1517e0856 53 ```
elelthvd 0:5db1517e0856 54
elelthvd 0:5db1517e0856 55 Your PC may take a few minutes to compile your code. At the end, you see the
elelthvd 0:5db1517e0856 56 following result:
elelthvd 0:5db1517e0856 57
elelthvd 0:5db1517e0856 58 ```
elelthvd 0:5db1517e0856 59 [snip]
elelthvd 0:5db1517e0856 60 | Module | .text |.data | .bss |
elelthvd 0:5db1517e0856 61 |---------------------|--------|------|--------|
elelthvd 0:5db1517e0856 62 | [lib]/c_w.l | 13137 | 16 | 348 |
elelthvd 0:5db1517e0856 63 | [lib]/fz_wm.l | 34 | 0 | 0 |
elelthvd 0:5db1517e0856 64 | [lib]/libcppabi_w.l | 44 | 0 | 0 |
elelthvd 0:5db1517e0856 65 | [lib]/m_wm.l | 48 | 0 | 0 |
elelthvd 0:5db1517e0856 66 | anon$$obj.o | 32 | 0 | 197888 |
elelthvd 0:5db1517e0856 67 | main.o | 2406 | 0 | 256 |
elelthvd 0:5db1517e0856 68 | mbed-os/components | 5568 | 0 | 0 |
elelthvd 0:5db1517e0856 69 | mbed-os/drivers | 2700 | 0 | 1136 |
elelthvd 0:5db1517e0856 70 | mbed-os/events | 1716 | 0 | 3108 |
elelthvd 0:5db1517e0856 71 | mbed-os/features | 16586 | 0 | 509 |
elelthvd 0:5db1517e0856 72 | mbed-os/hal | 1622 | 4 | 67 |
elelthvd 0:5db1517e0856 73 | mbed-os/platform | 7009 | 64 | 542 |
elelthvd 0:5db1517e0856 74 | mbed-os/rtos | 12132 | 168 | 6634 |
elelthvd 0:5db1517e0856 75 | mbed-os/targets | 19773 | 12 | 985 |
elelthvd 0:5db1517e0856 76 | Subtotals | 82807 | 264 | 211473 |
elelthvd 0:5db1517e0856 77 Total Static RAM memory (data + bss): 211737 bytes
elelthvd 0:5db1517e0856 78 Total Flash memory (text + data): 83071 bytes
elelthvd 0:5db1517e0856 79
elelthvd 0:5db1517e0856 80 Image: ./BUILD/K64F/ARM/mbed-os-example-filesystem.bin
elelthvd 0:5db1517e0856 81 ```
elelthvd 0:5db1517e0856 82
elelthvd 0:5db1517e0856 83 #### Run the example
elelthvd 0:5db1517e0856 84
elelthvd 0:5db1517e0856 85 1. Connect your Mbed Enabled device to the computer over USB.
elelthvd 0:5db1517e0856 86 1. Copy the binary file to the Mbed Enabled device.
elelthvd 0:5db1517e0856 87 1. Press the reset button to start the program.
elelthvd 0:5db1517e0856 88 1. Open the UART of the board in your favorite UART viewing program. For
elelthvd 0:5db1517e0856 89 example, `screen /dev/ttyACM0`.
elelthvd 0:5db1517e0856 90
elelthvd 0:5db1517e0856 91 **Note:** The default serial port baud rate is 9600 bit/s.
elelthvd 0:5db1517e0856 92
elelthvd 0:5db1517e0856 93 Expected output:
elelthvd 0:5db1517e0856 94
elelthvd 0:5db1517e0856 95 ```
elelthvd 0:5db1517e0856 96 --- Mbed OS filesystem example ---
elelthvd 0:5db1517e0856 97 Mounting the filesystem... Fail :(
elelthvd 0:5db1517e0856 98 No filesystem found, formatting... OK
elelthvd 0:5db1517e0856 99 Opening "/fs/numbers.txt"... Fail :(
elelthvd 0:5db1517e0856 100 No file found, creating a new file... OK
elelthvd 0:5db1517e0856 101 Writing numbers (10/10)... OK
elelthvd 0:5db1517e0856 102 Seeking file... OK
elelthvd 0:5db1517e0856 103 Incrementing numbers (10/10)... OK
elelthvd 0:5db1517e0856 104 Closing "/fs/numbers.txt"... OK
elelthvd 0:5db1517e0856 105 Opening the root directory... OK
elelthvd 0:5db1517e0856 106 root directory:
elelthvd 0:5db1517e0856 107 .
elelthvd 0:5db1517e0856 108 ..
elelthvd 0:5db1517e0856 109 numbers.txt
elelthvd 0:5db1517e0856 110 Closing the root directory... OK
elelthvd 0:5db1517e0856 111 Opening "/fs/numbers.txt"...OK
elelthvd 0:5db1517e0856 112 numbers:
elelthvd 0:5db1517e0856 113 1
elelthvd 0:5db1517e0856 114 2
elelthvd 0:5db1517e0856 115 3
elelthvd 0:5db1517e0856 116 4
elelthvd 0:5db1517e0856 117 5
elelthvd 0:5db1517e0856 118 6
elelthvd 0:5db1517e0856 119 7
elelthvd 0:5db1517e0856 120 8
elelthvd 0:5db1517e0856 121 9
elelthvd 0:5db1517e0856 122 10
elelthvd 0:5db1517e0856 123 Closing "/fs/numbers.txt"... OK
elelthvd 0:5db1517e0856 124 Unmounting... OK
elelthvd 0:5db1517e0856 125 Mbed OS filesystem example done!
elelthvd 0:5db1517e0856 126 ```
elelthvd 0:5db1517e0856 127
elelthvd 0:5db1517e0856 128 You can also reset the board to see the data persist across boots. Each boot
elelthvd 0:5db1517e0856 129 increments the numbers stored on disk:
elelthvd 0:5db1517e0856 130
elelthvd 0:5db1517e0856 131 ```
elelthvd 0:5db1517e0856 132 --- Mbed OS filesystem example ---
elelthvd 0:5db1517e0856 133 Mounting the filesystem... OK
elelthvd 0:5db1517e0856 134 Opening "/fs/numbers.txt"... OK
elelthvd 0:5db1517e0856 135 Incrementing numbers (10/10)... OK
elelthvd 0:5db1517e0856 136 Closing "/fs/numbers.txt"... OK
elelthvd 0:5db1517e0856 137 Opening the root directory... OK
elelthvd 0:5db1517e0856 138 root directory:
elelthvd 0:5db1517e0856 139 .
elelthvd 0:5db1517e0856 140 ..
elelthvd 0:5db1517e0856 141 numbers.txt
elelthvd 0:5db1517e0856 142 Closing the root directory... OK
elelthvd 0:5db1517e0856 143 Opening "/fs/numbers.txt"...OK
elelthvd 0:5db1517e0856 144 numbers:
elelthvd 0:5db1517e0856 145 2
elelthvd 0:5db1517e0856 146 3
elelthvd 0:5db1517e0856 147 4
elelthvd 0:5db1517e0856 148 5
elelthvd 0:5db1517e0856 149 6
elelthvd 0:5db1517e0856 150 7
elelthvd 0:5db1517e0856 151 8
elelthvd 0:5db1517e0856 152 9
elelthvd 0:5db1517e0856 153 10
elelthvd 0:5db1517e0856 154 11
elelthvd 0:5db1517e0856 155 Closing "/fs/numbers.txt"... OK
elelthvd 0:5db1517e0856 156 Unmounting... OK
elelthvd 0:5db1517e0856 157 Mbed OS filesystem example done!
elelthvd 0:5db1517e0856 158 ```
elelthvd 0:5db1517e0856 159
elelthvd 0:5db1517e0856 160 If you find yourself with a corrupted file system, you can reset the storage
elelthvd 0:5db1517e0856 161 by pressing BUTTON1:
elelthvd 0:5db1517e0856 162
elelthvd 0:5db1517e0856 163 ```
elelthvd 0:5db1517e0856 164 Initializing the block device... OK
elelthvd 0:5db1517e0856 165 Erasing the block device... OK
elelthvd 0:5db1517e0856 166 Deinitializing the block device... OK
elelthvd 0:5db1517e0856 167 ```
elelthvd 0:5db1517e0856 168
elelthvd 0:5db1517e0856 169 Note that if you press the reset button at the wrong time, you may corrupt
elelthvd 0:5db1517e0856 170 a file system that is not power resilient!
elelthvd 0:5db1517e0856 171
elelthvd 0:5db1517e0856 172 #### Troubleshooting
elelthvd 0:5db1517e0856 173
elelthvd 0:5db1517e0856 174 If you have problems, you can review the [documentation](https://os.mbed.com/docs/latest/tutorials/debugging.html)
elelthvd 0:5db1517e0856 175 for suggestions on what could be wrong and how to fix it.
elelthvd 0:5db1517e0856 176
elelthvd 0:5db1517e0856 177 ## Changing the file system
elelthvd 0:5db1517e0856 178
elelthvd 0:5db1517e0856 179 In Mbed OS, a C++ classes that inherits from the [FileSystem](https://os.mbed.com/docs/latest/reference/storage.html#declaring-a-file-system)
elelthvd 0:5db1517e0856 180 interface represents each file system. You can change the file system in the
elelthvd 0:5db1517e0856 181 example by changing the class declared in main.cpp.
elelthvd 0:5db1517e0856 182
elelthvd 0:5db1517e0856 183 ``` diff
elelthvd 0:5db1517e0856 184 - LittleFileSystem fs("fs");
elelthvd 0:5db1517e0856 185 + FATFileSystem fs("fs");
elelthvd 0:5db1517e0856 186 ```
elelthvd 0:5db1517e0856 187
elelthvd 0:5db1517e0856 188 **Note:** Different file systems require different minimum numbers of storage
elelthvd 0:5db1517e0856 189 blocks to function. For the `FATFileSystem`, this example requires a minimum of
elelthvd 0:5db1517e0856 190 256 blocks, and for the `LittleFileSystem`, this example requires a minimum of 6
elelthvd 0:5db1517e0856 191 blocks. You can find the number of blocks on a block device by dividing the
elelthvd 0:5db1517e0856 192 block device's size by its erase size.
elelthvd 0:5db1517e0856 193
elelthvd 0:5db1517e0856 194 Mbed OS has two options for the file system:
elelthvd 0:5db1517e0856 195
elelthvd 0:5db1517e0856 196 - [**LittleFileSystem**](https://os.mbed.com/docs/latest/reference/littlefilesystem.html) -
elelthvd 0:5db1517e0856 197 The little file system is a fail-safe file system we designed
elelthvd 0:5db1517e0856 198 for embedded systems, specifically for microcontrollers that use flash
elelthvd 0:5db1517e0856 199 storage.
elelthvd 0:5db1517e0856 200
elelthvd 0:5db1517e0856 201 ``` cpp
elelthvd 0:5db1517e0856 202 LittleFileSystem fs("fs");
elelthvd 0:5db1517e0856 203 ```
elelthvd 0:5db1517e0856 204
elelthvd 0:5db1517e0856 205 - **Bounded RAM/ROM** - This file system works with a limited amount of memory.
elelthvd 0:5db1517e0856 206 It avoids recursion and limits dynamic memory to configurable
elelthvd 0:5db1517e0856 207 buffers.
elelthvd 0:5db1517e0856 208
elelthvd 0:5db1517e0856 209 - **Power-loss resilient** - We designed this for operating systems
elelthvd 0:5db1517e0856 210 that may have random power failures. It has strong copy-on-write
elelthvd 0:5db1517e0856 211 guarantees and keeps storage on disk in a valid state.
elelthvd 0:5db1517e0856 212
elelthvd 0:5db1517e0856 213 - **Wear leveling** - Because the most common form of embedded storage is
elelthvd 0:5db1517e0856 214 erodible flash memories, this file system provides a form of dynamic wear
elelthvd 0:5db1517e0856 215 leveling for systems that cannot fit a full flash translation layer.
elelthvd 0:5db1517e0856 216
elelthvd 0:5db1517e0856 217 - **FATFileSystem** - The FAT file system is a well-known file system that you
elelthvd 0:5db1517e0856 218 can find on almost every system, including PCs. The Mbed OS implementation of
elelthvd 0:5db1517e0856 219 the FAT file system is based on ChanFS and is optimized for small embedded systems.
elelthvd 0:5db1517e0856 220
elelthvd 0:5db1517e0856 221 ``` cpp
elelthvd 0:5db1517e0856 222 FATFileSystem fs("fs");
elelthvd 0:5db1517e0856 223 ```
elelthvd 0:5db1517e0856 224
elelthvd 0:5db1517e0856 225 - **Portable** - Almost every operating system supports the FAT file system,
elelthvd 0:5db1517e0856 226 which is the most common file system found on portable storage, such as SD
elelthvd 0:5db1517e0856 227 cards and flash drives. The FAT file system is the easiest way to support
elelthvd 0:5db1517e0856 228 access from a PC.
elelthvd 0:5db1517e0856 229
elelthvd 0:5db1517e0856 230 ## Changing the block device
elelthvd 0:5db1517e0856 231
elelthvd 0:5db1517e0856 232 In Mbed OS, a C++ classes that inherits from the [BlockDevice](https://os.mbed.com/docs/latest/reference/storage.html#block-devices)
elelthvd 0:5db1517e0856 233 interface represents each block device. You can change the filesystem in the
elelthvd 0:5db1517e0856 234 example by changing the class declared in main.cpp.
elelthvd 0:5db1517e0856 235
elelthvd 0:5db1517e0856 236 ``` diff
elelthvd 0:5db1517e0856 237 -SPIFBlockDevice bd(
elelthvd 0:5db1517e0856 238 - MBED_CONF_SPIF_DRIVER_SPI_MOSI,
elelthvd 0:5db1517e0856 239 - MBED_CONF_SPIF_DRIVER_SPI_MISO,
elelthvd 0:5db1517e0856 240 - MBED_CONF_SPIF_DRIVER_SPI_CLK,
elelthvd 0:5db1517e0856 241 - MBED_CONF_SPIF_DRIVER_SPI_CS);
elelthvd 0:5db1517e0856 242 +SDBlockDevice bd(
elelthvd 0:5db1517e0856 243 + MBED_CONF_SD_SPI_MOSI,
elelthvd 0:5db1517e0856 244 + MBED_CONF_SD_SPI_MISO,
elelthvd 0:5db1517e0856 245 + MBED_CONF_SD_SPI_CLK,
elelthvd 0:5db1517e0856 246 + MBED_CONF_SD_SPI_CS);
elelthvd 0:5db1517e0856 247 ```
elelthvd 0:5db1517e0856 248
elelthvd 0:5db1517e0856 249 **Note:** Most block devices require pin assignments. Double check that the
elelthvd 0:5db1517e0856 250 pins in `<driver>/mbed_lib.json` are correct. For example, to change the pins for the SD driver, open `sd-driver/config/mbed_lib.json`, and change your target platform to the correct pin-out in the `target_overrides` configuration:
elelthvd 0:5db1517e0856 251
elelthvd 0:5db1517e0856 252 ```
elelthvd 0:5db1517e0856 253 "target_overrides": {
elelthvd 0:5db1517e0856 254 ...
elelthvd 0:5db1517e0856 255 "NUCLEO_F429ZI": {
elelthvd 0:5db1517e0856 256 "SPI_MOSI": "PC_12",
elelthvd 0:5db1517e0856 257 "SPI_MISO": "PC_11",
elelthvd 0:5db1517e0856 258 "SPI_CLK": "PC_10",
elelthvd 0:5db1517e0856 259 "SPI_CS": "PA_15"
elelthvd 0:5db1517e0856 260 },
elelthvd 0:5db1517e0856 261 ...
elelthvd 0:5db1517e0856 262 }
elelthvd 0:5db1517e0856 263 ```
elelthvd 0:5db1517e0856 264 The pins macros define above can be override at the application configuration file using the driver prefix before the parameter name.
elelthvd 0:5db1517e0856 265 ```
elelthvd 0:5db1517e0856 266 "target_overrides": {
elelthvd 0:5db1517e0856 267 ...
elelthvd 0:5db1517e0856 268 "NUCLEO_F429ZI": {
elelthvd 0:5db1517e0856 269 "spif-driver.SPI_MOSI": "PC_12",
elelthvd 0:5db1517e0856 270 "spif-driver.SPI_MISO": "PC_11",
elelthvd 0:5db1517e0856 271 "spif-driver.SPI_CLK": "PC_10",
elelthvd 0:5db1517e0856 272 "spif-driver.SPI_CS": "PA_15"
elelthvd 0:5db1517e0856 273 },
elelthvd 0:5db1517e0856 274 ...
elelthvd 0:5db1517e0856 275 }
elelthvd 0:5db1517e0856 276 ```
elelthvd 0:5db1517e0856 277 or
elelthvd 0:5db1517e0856 278 ```
elelthvd 0:5db1517e0856 279 "target_overrides": {
elelthvd 0:5db1517e0856 280 ...
elelthvd 0:5db1517e0856 281 "NUCLEO_F429ZI": {
elelthvd 0:5db1517e0856 282 "sd.SPI_MOSI": "PC_12",
elelthvd 0:5db1517e0856 283 "sd.SPI_MISO": "PC_11",
elelthvd 0:5db1517e0856 284 "sd.SPI_CLK": "PC_10",
elelthvd 0:5db1517e0856 285 "sd.SPI_CS": "PA_15"
elelthvd 0:5db1517e0856 286 },
elelthvd 0:5db1517e0856 287 ...
elelthvd 0:5db1517e0856 288 }
elelthvd 0:5db1517e0856 289 ```
elelthvd 0:5db1517e0856 290
elelthvd 0:5db1517e0856 291 Mbed OS has several options for the block device:
elelthvd 0:5db1517e0856 292
elelthvd 0:5db1517e0856 293 - **SPIFBlockDevice** - Block device driver for NOR-based SPI flash devices that
elelthvd 0:5db1517e0856 294 support SFDP. NOR-based SPI flash supports byte-sized read and writes, with an
elelthvd 0:5db1517e0856 295 erase size of about 4kbytes. An erase sets a block to all 1s, with successive
elelthvd 0:5db1517e0856 296 writes clearing set bits.
elelthvd 0:5db1517e0856 297
elelthvd 0:5db1517e0856 298 ``` cpp
elelthvd 0:5db1517e0856 299 SPIFBlockDevice bd(
elelthvd 0:5db1517e0856 300 MBED_CONF_SPIF_DRIVER_SPI_MOSI,
elelthvd 0:5db1517e0856 301 MBED_CONF_SPIF_DRIVER_SPI_MISO,
elelthvd 0:5db1517e0856 302 MBED_CONF_SPIF_DRIVER_SPI_CLK,
elelthvd 0:5db1517e0856 303 MBED_CONF_SPIF_DRIVER_SPI_CS);
elelthvd 0:5db1517e0856 304 ```
elelthvd 0:5db1517e0856 305
elelthvd 0:5db1517e0856 306 Starting mbed-os 5.10 the SPIFBlockDevice is a component under mbed-os. In order to add a component to the application use the following `target_overrides` configuration at the application configuration file:
elelthvd 0:5db1517e0856 307 ```
elelthvd 0:5db1517e0856 308 "target_overrides": {
elelthvd 0:5db1517e0856 309 ...
elelthvd 0:5db1517e0856 310 "NUCLEO_F429ZI": {
elelthvd 0:5db1517e0856 311 "target.components_add": ["SPIF"],
elelthvd 0:5db1517e0856 312 ...
elelthvd 0:5db1517e0856 313 },
elelthvd 0:5db1517e0856 314 ...
elelthvd 0:5db1517e0856 315 }
elelthvd 0:5db1517e0856 316 ```
elelthvd 0:5db1517e0856 317
elelthvd 0:5db1517e0856 318 - **DataFlashBlockDevice** - Block device driver for NOR-based SPI flash devices
elelthvd 0:5db1517e0856 319 that support the DataFlash protocol, such as the Adesto AT45DB series of
elelthvd 0:5db1517e0856 320 devices. DataFlash is a memory protocol that combines flash with SRAM buffers
elelthvd 0:5db1517e0856 321 for a programming interface. DataFlash supports byte-sized read and writes, with
elelthvd 0:5db1517e0856 322 an erase size of about 528 bytes or sometimes 1056 bytes. DataFlash provides
elelthvd 0:5db1517e0856 323 erase sizes with an extra 16 bytes for error correction codes (ECC), so a flash
elelthvd 0:5db1517e0856 324 translation layer (FTL) may still present 512 byte erase sizes.
elelthvd 0:5db1517e0856 325
elelthvd 0:5db1517e0856 326 ``` cpp
elelthvd 0:5db1517e0856 327 DataFlashBlockDevice bd(
elelthvd 0:5db1517e0856 328 MBED_CONF_DATAFLASH_SPI_MOSI,
elelthvd 0:5db1517e0856 329 MBED_CONF_DATAFLASH_SPI_MISO,
elelthvd 0:5db1517e0856 330 MBED_CONF_DATAFLASH_SPI_CLK,
elelthvd 0:5db1517e0856 331 MBED_CONF_DATAFLASH_SPI_CS);
elelthvd 0:5db1517e0856 332 ```
elelthvd 0:5db1517e0856 333
elelthvd 0:5db1517e0856 334 Starting mbed-os 5.10 the DataFlashBlockDevice is a component under mbed-os. In order to add a component to the application use the following `target_overrides` configuration at the application configuration file:
elelthvd 0:5db1517e0856 335 ```
elelthvd 0:5db1517e0856 336 "target_overrides": {
elelthvd 0:5db1517e0856 337 ...
elelthvd 0:5db1517e0856 338 "NUCLEO_F429ZI": {
elelthvd 0:5db1517e0856 339 "target.components_add": ["DATAFLASH"],
elelthvd 0:5db1517e0856 340 ...
elelthvd 0:5db1517e0856 341 },
elelthvd 0:5db1517e0856 342 ...
elelthvd 0:5db1517e0856 343 }
elelthvd 0:5db1517e0856 344 ```
elelthvd 0:5db1517e0856 345
elelthvd 0:5db1517e0856 346 - **SDBlockDevice** - Block device driver for SD cards and eMMC memory chips. SD
elelthvd 0:5db1517e0856 347 cards or eMMC chips offer a full FTL layer on top of NAND flash. This makes the
elelthvd 0:5db1517e0856 348 storage well-suited for systems that require a about 1GB of memory.
elelthvd 0:5db1517e0856 349 Additionally, SD cards are a popular form of portable storage. They are useful
elelthvd 0:5db1517e0856 350 if you want to store data that you can access from a PC.
elelthvd 0:5db1517e0856 351
elelthvd 0:5db1517e0856 352 ``` cpp
elelthvd 0:5db1517e0856 353 SDBlockDevice bd(
elelthvd 0:5db1517e0856 354 MBED_CONF_SD_SPI_MOSI,
elelthvd 0:5db1517e0856 355 MBED_CONF_SD_SPI_MISO,
elelthvd 0:5db1517e0856 356 MBED_CONF_SD_SPI_CLK,
elelthvd 0:5db1517e0856 357 MBED_CONF_SD_SPI_CS);
elelthvd 0:5db1517e0856 358 ```
elelthvd 0:5db1517e0856 359
elelthvd 0:5db1517e0856 360 Starting mbed-os 5.10 the SDBlockDevice is a component under mbed-os. In order to add a component to the application use the following `target_overrides` configuration at the application configuration file:
elelthvd 0:5db1517e0856 361 ```
elelthvd 0:5db1517e0856 362 "target_overrides": {
elelthvd 0:5db1517e0856 363 ...
elelthvd 0:5db1517e0856 364 "NUCLEO_F429ZI": {
elelthvd 0:5db1517e0856 365 "target.components_add": ["SD"],
elelthvd 0:5db1517e0856 366 ...
elelthvd 0:5db1517e0856 367 },
elelthvd 0:5db1517e0856 368 ...
elelthvd 0:5db1517e0856 369 }
elelthvd 0:5db1517e0856 370 ```
elelthvd 0:5db1517e0856 371
elelthvd 0:5db1517e0856 372 - [**HeapBlockDevice**](https://os.mbed.com/docs/v5.6/reference/heapblockdevice.html) -
elelthvd 0:5db1517e0856 373 Block device that simulates storage in RAM using the heap. Do not use the heap
elelthvd 0:5db1517e0856 374 block device for storing data persistently because a power loss causes
elelthvd 0:5db1517e0856 375 complete loss of data. Instead, use it fortesting applications when a storage
elelthvd 0:5db1517e0856 376 device is not available.
elelthvd 0:5db1517e0856 377
elelthvd 0:5db1517e0856 378 ``` cpp
elelthvd 0:5db1517e0856 379 HeapBlockDevice bd(1024*512, 512);
elelthvd 0:5db1517e0856 380 ```
elelthvd 0:5db1517e0856 381
elelthvd 0:5db1517e0856 382 Additionally, Mbed OS contains several utility block devices to give you better
elelthvd 0:5db1517e0856 383 control over the allocation of storage.
elelthvd 0:5db1517e0856 384
elelthvd 0:5db1517e0856 385 - [**SlicingBlockDevice**](https://os.mbed.com/docs/latest/reference/slicingblockdevice.html) -
elelthvd 0:5db1517e0856 386 With the slicing block device, you can partition storage into smaller block
elelthvd 0:5db1517e0856 387 devices that you can use independently.
elelthvd 0:5db1517e0856 388
elelthvd 0:5db1517e0856 389 - [**ChainingBlockDevice**](https://os.mbed.com/docs/latest/reference/chainingblockdevice.html) -
elelthvd 0:5db1517e0856 390 With the chaining block device, you can chain multiple block devices together
elelthvd 0:5db1517e0856 391 and extend the usable amount of storage.
elelthvd 0:5db1517e0856 392
elelthvd 0:5db1517e0856 393 - [**MBRBlockDevice**](https://os.mbed.com/docs/latest/reference/mbrblockdevice.html) -
elelthvd 0:5db1517e0856 394 Mbed OS comes with support for storing partitions on disk with a Master Boot
elelthvd 0:5db1517e0856 395 Record (MBR). The MBRBlockDevice provides this functionality and supports
elelthvd 0:5db1517e0856 396 creating partitions at runtime or using preformatted partitions configured
elelthvd 0:5db1517e0856 397 separately from outside the application.
elelthvd 0:5db1517e0856 398
elelthvd 0:5db1517e0856 399 - **ReadOnlyBlockDevice** - With the read-only block device, you can wrap a
elelthvd 0:5db1517e0856 400 block device in a read-only layer, ensuring that user of the block device does
elelthvd 0:5db1517e0856 401 not modify the storage.
elelthvd 0:5db1517e0856 402
elelthvd 0:5db1517e0856 403 - **ProfilingBlockDevice** - With the profiling block device, you can profile
elelthvd 0:5db1517e0856 404 the quantity of erase, program and read operations that are incurred on a
elelthvd 0:5db1517e0856 405 block device.
elelthvd 0:5db1517e0856 406
elelthvd 0:5db1517e0856 407 - **ObservingBlockDevice** - The observing block device grants the user the
elelthvd 0:5db1517e0856 408 ability to register a callback on block device operations. You can use this to
elelthvd 0:5db1517e0856 409 inspect the state of the block device, log different metrics or perform some
elelthvd 0:5db1517e0856 410 other operation.
elelthvd 0:5db1517e0856 411
elelthvd 0:5db1517e0856 412 - **ExhaustibleBlockDevice** - Useful for evaluating how file systems respond to
elelthvd 0:5db1517e0856 413 wear, the exhaustible block device simulates wear on another form of storage.
elelthvd 0:5db1517e0856 414 You can configure it to expire blocks as necessary.
elelthvd 0:5db1517e0856 415
elelthvd 0:5db1517e0856 416 ## Tested configurations
elelthvd 0:5db1517e0856 417
elelthvd 0:5db1517e0856 418 - K64F + Heap + LittleFS
elelthvd 0:5db1517e0856 419 - K64F + Heap + FATFS
elelthvd 0:5db1517e0856 420 - K64F + SD + LittleFS
elelthvd 0:5db1517e0856 421 - K64F + SD + FATFS
elelthvd 0:5db1517e0856 422 - K64F + SPIF (requires shield) + LittleFS
elelthvd 0:5db1517e0856 423 - K64F + SPIF (requires shield) + FATFS
elelthvd 0:5db1517e0856 424 - K64F + DataFlash (requires shield) + LittleFS
elelthvd 0:5db1517e0856 425 - K64F + DataFlash (requires shield) + FATFS
elelthvd 0:5db1517e0856 426 - UBLOX_EVK_ODIN_W2 \[1\] + Heap + LittleFS
elelthvd 0:5db1517e0856 427 - UBLOX_EVK_ODIN_W2 \[1\] + Heap + FATFS
elelthvd 0:5db1517e0856 428 - UBLOX_EVK_ODIN_W2 \[1\] + SD + LittleFS
elelthvd 0:5db1517e0856 429 - UBLOX_EVK_ODIN_W2 \[1\] + SD + FATFS
elelthvd 0:5db1517e0856 430 - UBLOX_EVK_ODIN_W2 \[1\] + SPIF (requires shield) + LittleFS
elelthvd 0:5db1517e0856 431 - UBLOX_EVK_ODIN_W2 \[1\] + SPIF (requires shield) + FATFS
elelthvd 0:5db1517e0856 432 - UBLOX_EVK_ODIN_W2 \[1\] + DataFlash (requires shield) + LittleFS
elelthvd 0:5db1517e0856 433 - UBLOX_EVK_ODIN_W2 \[1\] + DataFlash (requires shield) + FATFS
elelthvd 0:5db1517e0856 434 - NUCLEO_F429ZI + Heap + LittleFS
elelthvd 0:5db1517e0856 435 - NUCLEO_F429ZI + Heap + FATFS
elelthvd 0:5db1517e0856 436 - NUCLEO_F429ZI + SD (requires shield) + LittleFS
elelthvd 0:5db1517e0856 437 - NUCLEO_F429ZI + SD (requires shield) + FATFS
elelthvd 0:5db1517e0856 438 - NUCLEO_F429ZI + SPIF (requires shield) + LittleFS
elelthvd 0:5db1517e0856 439 - NUCLEO_F429ZI + SPIF (requires shield) + FATFS
elelthvd 0:5db1517e0856 440 - NUCLEO_F429ZI + DataFlash (requires shield) + LittleFS
elelthvd 0:5db1517e0856 441 - NUCLEO_F429ZI + DataFlash (requires shield) + FATFS
elelthvd 0:5db1517e0856 442
elelthvd 0:5db1517e0856 443 \[1\]: Note: The UBLOX_EVK_ODIN_W2 SPI pins conflict with the default serial
elelthvd 0:5db1517e0856 444 pins. A different set of serial pins must be selected to use SPI flash with
elelthvd 0:5db1517e0856 445 serial output.
elelthvd 0:5db1517e0856 446
elelthvd 0:5db1517e0856 447 ```c++
elelthvd 0:5db1517e0856 448 // Connect Tx, Rx, and ground pins to a separte board running the passthrough example:
elelthvd 0:5db1517e0856 449 // https://os.mbed.com/users/sarahmarshy/code/SerialPassthrough/file/2a3a62ee17fa/main.cpp/
elelthvd 0:5db1517e0856 450 Serial pc(TX, RX);
elelthvd 0:5db1517e0856 451
elelthvd 0:5db1517e0856 452 pc.printf("..."); // Replace printf with pc.printf in the example
elelthvd 0:5db1517e0856 453 ```
elelthvd 0:5db1517e0856 454
elelthvd 0:5db1517e0856 455 ### License and contributions
elelthvd 0:5db1517e0856 456
elelthvd 0:5db1517e0856 457 The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. Please see [contributing.md](CONTRIBUTING.md) for more info.
elelthvd 0:5db1517e0856 458
elelthvd 0:5db1517e0856 459 This project contains code from other projects. The original license text is included in those source files. They must comply with our license guide.
elelthvd 0:5db1517e0856 460