This example demonstrates how to use the Mbed OS file system on target RHOMBIO_L476DMW1K together with a Rhombio uSD Holder module. The example is based on mbed official mbed-os-example-filesystem with minor modifications.

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

Committer:
galonso@rhomb.io
Date:
Thu Sep 19 13:29:36 2019 +0200
Revision:
5:37e9573e91f6
Parent:
0:91eeaf1003ac
changes in README.md

Who changed what in which revision?

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