mbed-os-examples / Mbed OS mbed-os-example-mbed5-filesystem

.

README.md@33:3a0681d09e16, 2019-11-22 (annotated)

Committer:
mbed_official
Date:
Fri Nov 22 11:01:47 2019 +0000
Revision:
33:3a0681d09e16
Parent:
32:decaa56b2fd0 
Merge pull request #94 from 0xc0170/fix_license



add contributing file

.

Commit copied from https://github.com/ARMmbed/mbed-os-example-filesystem

Who changed what in which revision?

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