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

.

README.md@0:8e251d9511b8, 2017-12-13 (annotated)

Committer:
mbed_official
Date:
Wed Dec 13 16:20:24 2017 +0000
Revision:
0:8e251d9511b8
Child:
1:2bfc377bcc2a
Merge pull request #6 from ARMmbed/geky-patch-1



Add docs for troubleshooting

.

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 0:8e251d9511b8 5 Please install [Mbed CLI](https://os.mbed.com/docs/v5.6/tools/setup.html).
mbed_official 0:8e251d9511b8 6
mbed_official 0:8e251d9511b8 7 ## Hardware requirements
mbed_official 0:8e251d9511b8 8
mbed_official 0:8e251d9511b8 9 This example uses a block device as storage. This can be either an external
mbed_official 0:8e251d9511b8 10 block device or simulated on a heap block device on boards with enough RAM.
mbed_official 0:8e251d9511b8 11
mbed_official 0:8e251d9511b8 12 ## Usage
mbed_official 0:8e251d9511b8 13
mbed_official 0:8e251d9511b8 14 #### Import the example
mbed_official 0:8e251d9511b8 15
mbed_official 0:8e251d9511b8 16 Make sure you have an Mbed development environment set up. [Get started with Mbed OS](https://os.mbed.com/docs/v5.6/tutorials/your-first-program.html)
mbed_official 0:8e251d9511b8 17 to set everything up.
mbed_official 0:8e251d9511b8 18
mbed_official 0:8e251d9511b8 19 From the command-line, import the example:
mbed_official 0:8e251d9511b8 20
mbed_official 0:8e251d9511b8 21 ```
mbed_official 0:8e251d9511b8 22 mbed import mbed-os-example-filesystem
mbed_official 0:8e251d9511b8 23 cd mbed-os-example-filesystem
mbed_official 0:8e251d9511b8 24 ```
mbed_official 0:8e251d9511b8 25
mbed_official 0:8e251d9511b8 26 #### Compile the example
mbed_official 0:8e251d9511b8 27
mbed_official 0:8e251d9511b8 28 Invoke `mbed compile`, and specify the name of your platform and your favorite
mbed_official 0:8e251d9511b8 29 toolchain (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM Compiler 5:
mbed_official 0:8e251d9511b8 30
mbed_official 0:8e251d9511b8 31 ```
mbed_official 0:8e251d9511b8 32 mbed compile -m K64F -t ARM
mbed_official 0:8e251d9511b8 33 ```
mbed_official 0:8e251d9511b8 34
mbed_official 0:8e251d9511b8 35 Your PC may take a few minutes to compile your code. At the end, you see the
mbed_official 0:8e251d9511b8 36 following result:
mbed_official 0:8e251d9511b8 37
mbed_official 0:8e251d9511b8 38 ```
mbed_official 0:8e251d9511b8 39 [snip]
mbed_official 0:8e251d9511b8 40 +--------------------------+-------+-------+-------+
mbed_official 0:8e251d9511b8 41 | Module | .text | .data | .bss |
mbed_official 0:8e251d9511b8 42 +--------------------------+-------+-------+-------+
mbed_official 0:8e251d9511b8 43 | Fill | 164 | 0 | 2136 |
mbed_official 0:8e251d9511b8 44 | Misc | 54505 | 2556 | 754 |
mbed_official 0:8e251d9511b8 45 | drivers | 640 | 0 | 32 |
mbed_official 0:8e251d9511b8 46 | features/filesystem | 15793 | 0 | 550 |
mbed_official 0:8e251d9511b8 47 | features/storage | 42 | 0 | 184 |
mbed_official 0:8e251d9511b8 48 | hal | 418 | 0 | 8 |
mbed_official 0:8e251d9511b8 49 | platform | 2355 | 20 | 582 |
mbed_official 0:8e251d9511b8 50 | rtos | 135 | 4 | 4 |
mbed_official 0:8e251d9511b8 51 | rtos/rtx | 5861 | 20 | 6870 |
mbed_official 0:8e251d9511b8 52 | targets/TARGET_Freescale | 8382 | 12 | 384 |
mbed_official 0:8e251d9511b8 53 | Subtotals | 88295 | 2612 | 11504 |
mbed_official 0:8e251d9511b8 54 +--------------------------+-------+-------+-------+
mbed_official 0:8e251d9511b8 55 Allocated Heap: 24576 bytes
mbed_official 0:8e251d9511b8 56 Allocated Stack: unknown
mbed_official 0:8e251d9511b8 57 Total Static RAM memory (data + bss): 14116 bytes
mbed_official 0:8e251d9511b8 58 Total RAM memory (data + bss + heap + stack): 38692 bytes
mbed_official 0:8e251d9511b8 59 Total Flash memory (text + data + misc): 91947 bytes
mbed_official 0:8e251d9511b8 60
mbed_official 0:8e251d9511b8 61 Image: ./BUILD/K64F/ARM/mbed-os-example-filesystem.bin
mbed_official 0:8e251d9511b8 62 ```
mbed_official 0:8e251d9511b8 63
mbed_official 0:8e251d9511b8 64 #### Run the example
mbed_official 0:8e251d9511b8 65
mbed_official 0:8e251d9511b8 66 1. Connect your Mbed Enabled device to the computer over USB.
mbed_official 0:8e251d9511b8 67 1. Copy the binary file to the Mbed Enabled device.
mbed_official 0:8e251d9511b8 68 1. Press the reset button to start the program.
mbed_official 0:8e251d9511b8 69 1. Open the UART of the board in your favorite UART viewing program. For
mbed_official 0:8e251d9511b8 70 example, `screen /dev/ttyACM0`.
mbed_official 0:8e251d9511b8 71
mbed_official 0:8e251d9511b8 72 **Note:** The default serial port baud rate is 9600 bit/s.
mbed_official 0:8e251d9511b8 73
mbed_official 0:8e251d9511b8 74 Expected output:
mbed_official 0:8e251d9511b8 75
mbed_official 0:8e251d9511b8 76 ```
mbed_official 0:8e251d9511b8 77 --- Mbed OS filesystem example ---
mbed_official 0:8e251d9511b8 78 Mounting the filesystem... Fail :(
mbed_official 0:8e251d9511b8 79 No filesystem found, formatting... OK
mbed_official 0:8e251d9511b8 80 Opening "/fs/numbers.txt"... Fail :(
mbed_official 0:8e251d9511b8 81 No file found, creating a new file... OK
mbed_official 0:8e251d9511b8 82 Writing numbers (10/10)... OK
mbed_official 0:8e251d9511b8 83 Seeking file... OK
mbed_official 0:8e251d9511b8 84 Incrementing numbers (10/10)... OK
mbed_official 0:8e251d9511b8 85 Closing "/fs/numbers.txt"... OK
mbed_official 0:8e251d9511b8 86 Opening the root directory... OK
mbed_official 0:8e251d9511b8 87 root directory:
mbed_official 0:8e251d9511b8 88 .
mbed_official 0:8e251d9511b8 89 ..
mbed_official 0:8e251d9511b8 90 numbers.txt
mbed_official 0:8e251d9511b8 91 Closing the root directory... OK
mbed_official 0:8e251d9511b8 92 Opening "/fs/numbers.txt"...OK
mbed_official 0:8e251d9511b8 93 numbers:
mbed_official 0:8e251d9511b8 94 1
mbed_official 0:8e251d9511b8 95 2
mbed_official 0:8e251d9511b8 96 3
mbed_official 0:8e251d9511b8 97 4
mbed_official 0:8e251d9511b8 98 5
mbed_official 0:8e251d9511b8 99 6
mbed_official 0:8e251d9511b8 100 7
mbed_official 0:8e251d9511b8 101 8
mbed_official 0:8e251d9511b8 102 9
mbed_official 0:8e251d9511b8 103 10
mbed_official 0:8e251d9511b8 104 Closing "/fs/numbers.txt"... OK
mbed_official 0:8e251d9511b8 105 Unmounting... OK
mbed_official 0:8e251d9511b8 106 Mbed OS filesystem example done!
mbed_official 0:8e251d9511b8 107 ```
mbed_official 0:8e251d9511b8 108
mbed_official 0:8e251d9511b8 109 You can also reset the board to see the data persist across boots. Each boot
mbed_official 0:8e251d9511b8 110 increments the numbers stored on disk:
mbed_official 0:8e251d9511b8 111
mbed_official 0:8e251d9511b8 112 ```
mbed_official 0:8e251d9511b8 113 --- Mbed OS filesystem example ---
mbed_official 0:8e251d9511b8 114 Mounting the filesystem... OK
mbed_official 0:8e251d9511b8 115 Opening "/fs/numbers.txt"... OK
mbed_official 0:8e251d9511b8 116 Incrementing numbers (10/10)... OK
mbed_official 0:8e251d9511b8 117 Closing "/fs/numbers.txt"... OK
mbed_official 0:8e251d9511b8 118 Opening the root directory... OK
mbed_official 0:8e251d9511b8 119 root directory:
mbed_official 0:8e251d9511b8 120 .
mbed_official 0:8e251d9511b8 121 ..
mbed_official 0:8e251d9511b8 122 numbers.txt
mbed_official 0:8e251d9511b8 123 Closing the root directory... OK
mbed_official 0:8e251d9511b8 124 Opening "/fs/numbers.txt"...OK
mbed_official 0:8e251d9511b8 125 numbers:
mbed_official 0:8e251d9511b8 126 2
mbed_official 0:8e251d9511b8 127 3
mbed_official 0:8e251d9511b8 128 4
mbed_official 0:8e251d9511b8 129 5
mbed_official 0:8e251d9511b8 130 6
mbed_official 0:8e251d9511b8 131 7
mbed_official 0:8e251d9511b8 132 8
mbed_official 0:8e251d9511b8 133 9
mbed_official 0:8e251d9511b8 134 10
mbed_official 0:8e251d9511b8 135 11
mbed_official 0:8e251d9511b8 136 Closing "/fs/numbers.txt"... OK
mbed_official 0:8e251d9511b8 137 Unmounting... OK
mbed_official 0:8e251d9511b8 138 Mbed OS filesystem example done!
mbed_official 0:8e251d9511b8 139 ```
mbed_official 0:8e251d9511b8 140
mbed_official 0:8e251d9511b8 141 If you find yourself with a corrupted file system, you can reset the storage
mbed_official 0:8e251d9511b8 142 by pressing BUTTON1:
mbed_official 0:8e251d9511b8 143
mbed_official 0:8e251d9511b8 144 ```
mbed_official 0:8e251d9511b8 145 Initializing the block device... OK
mbed_official 0:8e251d9511b8 146 Erasing the block device... OK
mbed_official 0:8e251d9511b8 147 Deinitializing the block device... OK
mbed_official 0:8e251d9511b8 148 ```
mbed_official 0:8e251d9511b8 149
mbed_official 0:8e251d9511b8 150 Note that if you press the reset button at the wrong time, you may corrupt
mbed_official 0:8e251d9511b8 151 a file system that is not power resilient!
mbed_official 0:8e251d9511b8 152
mbed_official 0:8e251d9511b8 153 #### Troubleshooting
mbed_official 0:8e251d9511b8 154
mbed_official 0:8e251d9511b8 155 If you have problems, you can review the [documentation](https://os.mbed.com/docs/latest/tutorials/debugging.html)
mbed_official 0:8e251d9511b8 156 for suggestions on what could be wrong and how to fix it.
mbed_official 0:8e251d9511b8 157
mbed_official 0:8e251d9511b8 158 ## Changing the file system
mbed_official 0:8e251d9511b8 159
mbed_official 0:8e251d9511b8 160 In Mbed OS, a C++ classes that inherits from the [FileSystem](https://os.mbed.com/docs/v5.6/reference/storage.html#declaring-a-file-system)
mbed_official 0:8e251d9511b8 161 interface represents each file system. You can change the file system in the
mbed_official 0:8e251d9511b8 162 example by changing the class declared in main.cpp.
mbed_official 0:8e251d9511b8 163
mbed_official 0:8e251d9511b8 164 ``` diff
mbed_official 0:8e251d9511b8 165 - LittleFileSystem fs("fs");
mbed_official 0:8e251d9511b8 166 + FATFileSysten fs("fs");
mbed_official 0:8e251d9511b8 167 ```
mbed_official 0:8e251d9511b8 168
mbed_official 0:8e251d9511b8 169 Mbed OS has two options for the file system:
mbed_official 0:8e251d9511b8 170
mbed_official 0:8e251d9511b8 171 - [**LittleFileSystem**](https://os.mbed.com/docs/v5.6/reference/littlefilesystem.html) -
mbed_official 0:8e251d9511b8 172 The little file system (LittleFS) is a fail-safe file system we designed
mbed_official 0:8e251d9511b8 173 for embedded systems, specifically for microcontrollers that use flash
mbed_official 0:8e251d9511b8 174 storage.
mbed_official 0:8e251d9511b8 175
mbed_official 0:8e251d9511b8 176 - **Bounded RAM/ROM** - This file system works with a limited amount of memory.
mbed_official 0:8e251d9511b8 177 It avoids recursion and limits dynamic memory to configurable
mbed_official 0:8e251d9511b8 178 buffers.
mbed_official 0:8e251d9511b8 179
mbed_official 0:8e251d9511b8 180 - **Power-loss resilient** - We designed this for operating systems
mbed_official 0:8e251d9511b8 181 that may have random power failures. It has strong copy-on-write
mbed_official 0:8e251d9511b8 182 guarantees and keeps storage on disk in a valid state.
mbed_official 0:8e251d9511b8 183
mbed_official 0:8e251d9511b8 184 - **Wear leveling** - Because the most common form of embedded storage is
mbed_official 0:8e251d9511b8 185 erodible flash memories, this file system provides a form of dynamic wear
mbed_official 0:8e251d9511b8 186 leveling for systems that cannot fit a full flash translation layer.
mbed_official 0:8e251d9511b8 187
mbed_official 0:8e251d9511b8 188 - **FATFileSystem** - The FAT file system is a well-known file system that you
mbed_official 0:8e251d9511b8 189 can find on almost every system, including PCs. The Mbed OS implementation of
mbed_official 0:8e251d9511b8 190 the FAT file system is based on ChanFS and is optimized for small embedded systems.
mbed_official 0:8e251d9511b8 191
mbed_official 0:8e251d9511b8 192 - **Portable** - Almost every operating system supports the FAT file system,
mbed_official 0:8e251d9511b8 193 which is the most common file system found on portable storage, such as SD
mbed_official 0:8e251d9511b8 194 cards and flash drives. The FAT file system is the easiest way to support
mbed_official 0:8e251d9511b8 195 access from a PC.
mbed_official 0:8e251d9511b8 196
mbed_official 0:8e251d9511b8 197 ## Changing the block device
mbed_official 0:8e251d9511b8 198
mbed_official 0:8e251d9511b8 199 In Mbed OS, a C++ classes that inherits from the [BlockDevice](https://os.mbed.com/docs/v5.6/reference/storage.html#block-devices)
mbed_official 0:8e251d9511b8 200 interface represents each block device. You can change the filesystem in the
mbed_official 0:8e251d9511b8 201 example by changing the class declared in main.cpp.
mbed_official 0:8e251d9511b8 202
mbed_official 0:8e251d9511b8 203 **Note:** Most block devices require pin assignments. Double check that the
mbed_official 0:8e251d9511b8 204 pins in `driver/mbed_lib.json` are correct.
mbed_official 0:8e251d9511b8 205
mbed_official 0:8e251d9511b8 206 ``` diff
mbed_official 0:8e251d9511b8 207 -SPIFBlockDevice bd(
mbed_official 0:8e251d9511b8 208 - MBED_CONF_SPIF_DRIVER_SPI_MOSI,
mbed_official 0:8e251d9511b8 209 - MBED_CONF_SPIF_DRIVER_SPI_MISO,
mbed_official 0:8e251d9511b8 210 - MBED_CONF_SPIF_DRIVER_SPI_CLK,
mbed_official 0:8e251d9511b8 211 - MBED_CONF_SPIF_DRIVER_SPI_CS);
mbed_official 0:8e251d9511b8 212 +SDBlockDevice bd(
mbed_official 0:8e251d9511b8 213 + MBED_CONF_SD_SPI_MOSI,
mbed_official 0:8e251d9511b8 214 + MBED_CONF_SD_SPI_MISO,
mbed_official 0:8e251d9511b8 215 + MBED_CONF_SD_SPI_CLK,
mbed_official 0:8e251d9511b8 216 + MBED_CONF_SD_SPI_CS);
mbed_official 0:8e251d9511b8 217 ```
mbed_official 0:8e251d9511b8 218
mbed_official 0:8e251d9511b8 219 Mbed OS has several options for the block device:
mbed_official 0:8e251d9511b8 220
mbed_official 0:8e251d9511b8 221 - **SPIFBlockDevice** - Block device driver for NOR-based SPI flash devices that
mbed_official 0:8e251d9511b8 222 support SFDP. NOR-based SPI flash supports byte-sized read and writes, with an
mbed_official 0:8e251d9511b8 223 erase size of about 4kbytes. An erase sets a block to all 1s, with successive
mbed_official 0:8e251d9511b8 224 writes clearing set bits.
mbed_official 0:8e251d9511b8 225
mbed_official 0:8e251d9511b8 226 - **DataFlashBlockDevice** - Block device driver for NOR-based SPI flash devices
mbed_official 0:8e251d9511b8 227 that support the DataFlash protocol, such as the Adesto AT45DB series of
mbed_official 0:8e251d9511b8 228 devices. DataFlash is a memory protocol that combines flash with SRAM buffers
mbed_official 0:8e251d9511b8 229 for a programming interface. DataFlash supports byte-sized read and writes, with
mbed_official 0:8e251d9511b8 230 an erase size of around 528 bytes or sometimes 1056 bytes. DataFlash provides
mbed_official 0:8e251d9511b8 231 erase sizes with and extra 16 bytes for error correction codes (ECC), so a flash
mbed_official 0:8e251d9511b8 232 translation layer (FTL) may still present 512 byte erase sizes.
mbed_official 0:8e251d9511b8 233
mbed_official 0:8e251d9511b8 234 - **SDBlockDevice** - Block device driver for SD cards and eMMC memory chips. SD
mbed_official 0:8e251d9511b8 235 cards or eMMC chips offer a full FTL layer on top of NAND flash. This makes the
mbed_official 0:8e251d9511b8 236 storage well-suited for systems that require a about 1GB of memory.
mbed_official 0:8e251d9511b8 237 Additionally, SD cards are a popular form of portable storage. They are useful
mbed_official 0:8e251d9511b8 238 if you want to store data that you can access from a PC.
mbed_official 0:8e251d9511b8 239
mbed_official 0:8e251d9511b8 240 - [**HeapBlockDevice**](https://os.mbed.com/docs/v5.6/reference/heapblockdevice.html) -
mbed_official 0:8e251d9511b8 241 Block device that simulates storage in RAM using the heap. Do not use the heap
mbed_official 0:8e251d9511b8 242 block device for storing data persistently because a power loss causes
mbed_official 0:8e251d9511b8 243 complete loss of data. Instead, use it fortesting applications when a storage
mbed_official 0:8e251d9511b8 244 device is not available.
mbed_official 0:8e251d9511b8 245
mbed_official 0:8e251d9511b8 246 Additionally, Mbed OS contains several utility block devices to give you better
mbed_official 0:8e251d9511b8 247 control over the allocation of storage.
mbed_official 0:8e251d9511b8 248
mbed_official 0:8e251d9511b8 249 - [**SlicingBlockDevice**](https://os.mbed.com/docs/v5.6/reference/slicingblockdevice.html) -
mbed_official 0:8e251d9511b8 250 With the slicing block device, you can partition storage into smaller block
mbed_official 0:8e251d9511b8 251 devices that you can use independently.
mbed_official 0:8e251d9511b8 252
mbed_official 0:8e251d9511b8 253 - [**ChainingBlockDevice**](https://os.mbed.com/docs/v5.6/reference/chainingblockdevice.html) -
mbed_official 0:8e251d9511b8 254 With the chaining block device, you can chain multiple block devices together
mbed_official 0:8e251d9511b8 255 and extend the usable amount of storage.
mbed_official 0:8e251d9511b8 256
mbed_official 0:8e251d9511b8 257 - [**MBRBlockDevice**](https://os.mbed.com/docs/v5.6/reference/mbrblockdevice.html) -
mbed_official 0:8e251d9511b8 258 Mbed OS comes with support for storing partitions on disk with a Master Boot
mbed_official 0:8e251d9511b8 259 Record (MBR). The MBRBlockDevice provides this functionality and supports
mbed_official 0:8e251d9511b8 260 creating partitions at runtime or using preformatted partitions configured
mbed_official 0:8e251d9511b8 261 separately from outside the application.
mbed_official 0:8e251d9511b8 262
mbed_official 0:8e251d9511b8 263 - **ReadOnlyBlockDevice** - With the read-only block device, you can wrap a
mbed_official 0:8e251d9511b8 264 block device in a read-only layer, ensuring that user of the block device does
mbed_official 0:8e251d9511b8 265 not modify the storage.
mbed_official 0:8e251d9511b8 266
mbed_official 0:8e251d9511b8 267 - **ProfilingBlockDevice** - With the profiling block device, you can profile
mbed_official 0:8e251d9511b8 268 the quantity of erase, program and read operations that are incurred on a
mbed_official 0:8e251d9511b8 269 block device.
mbed_official 0:8e251d9511b8 270
mbed_official 0:8e251d9511b8 271 - **ObservingBlockDevice** - The observing block device grants the user the
mbed_official 0:8e251d9511b8 272 ability to register a callback on block device operations. You can use this to
mbed_official 0:8e251d9511b8 273 inspect the state of the block device, log different metrics or perform some
mbed_official 0:8e251d9511b8 274 other operation.
mbed_official 0:8e251d9511b8 275
mbed_official 0:8e251d9511b8 276 - **ExhaustibleBlockDevice** - Useful for evaluating how file systems respond to
mbed_official 0:8e251d9511b8 277 wear, the exhaustible block device simulates wear on another form of storage.
mbed_official 0:8e251d9511b8 278 You can configure it to expire blocks as necessary.
mbed_official 0:8e251d9511b8 279