Diff: README.md

Revision:

1:2bfc377bcc2a

Parent:

0:8e251d9511b8

Child:

2:6a0c72c9d3fb

--- a/README.md	Wed Dec 13 16:20:24 2017 +0000
+++ b/README.md	Fri Dec 15 11:15:18 2017 +0000
@@ -2,18 +2,35 @@
 
 This example demonstrates how to use the Mbed OS file system.
 
-Please install [Mbed CLI](https://os.mbed.com/docs/v5.6/tools/setup.html).
+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).
+
+**Table of contents:**
+
+1. [Hardware requirements](#hardware-requirements)
+1. [Usage](#usage)
+   - [Import the example](#import-the-example)
+   - [Compile the example](#compile-the-example)
+   - [Run the example](#run-the-example)
+   - [Troubleshooting](#troubleshooting)
+1. [Changing the file system](#changing-the-file-system)
+1. [Changing the block device](#changing-the-block-device)
+1. [Tested configurations](#tested-configurations)
 
 ## Hardware requirements
 
 This example uses a block device as storage. This can be either an external
-block device or simulated on a heap block device on boards with enough RAM.
+block device (one of SPI flash, DataFlash or an SD card) or simulated on a
+heap block device on boards with enough RAM.
+
+This example uses an instance of the LittleFileSystem API (LittleFS) on external SPI flash.
+The [changing the block device](#changing-the-block-device) section describes
+how to change the file system or block device in the example.
 
 ## Usage
 
 #### Import the example
 
-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)
+Make sure you have an Mbed development environment set up. [Get started with Mbed OS](https://os.mbed.com/docs/latest/tutorials/your-first-program.html)
 to set everything up.
 
 From the command-line, import the example:
@@ -157,7 +174,7 @@
 
 ## Changing the file system
 
-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)
+In Mbed OS, a C++ classes that inherits from the [FileSystem](https://os.mbed.com/docs/latest/reference/storage.html#declaring-a-file-system)
 interface represents each file system. You can change the file system in the
 example by changing the class declared in main.cpp.
 
@@ -168,10 +185,14 @@
 
 Mbed OS has two options for the file system:
 
-- [**LittleFileSystem**](https://os.mbed.com/docs/v5.6/reference/littlefilesystem.html) -
-  The little file system (LittleFS) is a fail-safe file system we designed
+- [**LittleFileSystem**](https://os.mbed.com/docs/latest/reference/littlefilesystem.html) -
+  The little file system is a fail-safe file system we designed
   for embedded systems, specifically for microcontrollers that use flash
   storage.
+  
+  ``` cpp
+  LittleFileSystem fs("fs");
+  ```
 
   - **Bounded RAM/ROM** - This file system works with a limited amount of memory.
     It avoids recursion and limits dynamic memory to configurable
@@ -188,6 +209,10 @@
 - **FATFileSystem** - The FAT file system is a well-known file system that you
   can find on almost every system, including PCs. The Mbed OS implementation of
   the FAT file system is based on ChanFS and is optimized for small embedded systems.
+  
+  ``` cpp
+  FATFileSystem fs("fs");
+  ```
 
   - **Portable** - Almost every operating system supports the FAT file system,
     which is the most common file system found on portable storage, such as SD
@@ -196,7 +221,7 @@
 
 ## Changing the block device
 
-In Mbed OS, a C++ classes that inherits from the [BlockDevice](https://os.mbed.com/docs/v5.6/reference/storage.html#block-devices)
+In Mbed OS, a C++ classes that inherits from the [BlockDevice](https://os.mbed.com/docs/latest/reference/storage.html#block-devices)
 interface represents each block device. You can change the filesystem in the
 example by changing the class declared in main.cpp.
 
@@ -219,42 +244,70 @@
 Mbed OS has several options for the block device:
 
 - **SPIFBlockDevice** - Block device driver for NOR-based SPI flash devices that
-support SFDP. NOR-based SPI flash supports byte-sized read and writes, with an
-erase size of about 4kbytes. An erase sets a block to all 1s, with successive
-writes clearing set bits.
+  support SFDP. NOR-based SPI flash supports byte-sized read and writes, with an
+  erase size of about 4kbytes. An erase sets a block to all 1s, with successive
+  writes clearing set bits.
+
+  ``` cpp
+  SPIFBlockDevice bd(
+          MBED_CONF_SPIF_DRIVER_SPI_MOSI,
+          MBED_CONF_SPIF_DRIVER_SPI_MISO,
+          MBED_CONF_SPIF_DRIVER_SPI_CLK,
+          MBED_CONF_SPIF_DRIVER_SPI_CS);
+  ```
 
 - **DataFlashBlockDevice** - Block device driver for NOR-based SPI flash devices
-that support the DataFlash protocol, such as the Adesto AT45DB series of
-devices. DataFlash is a memory protocol that combines flash with SRAM buffers
-for a programming interface. DataFlash supports byte-sized read and writes, with
-an erase size of around 528 bytes or sometimes 1056 bytes. DataFlash provides
-erase sizes with and extra 16 bytes for error correction codes (ECC), so a flash
-translation layer (FTL) may still present 512 byte erase sizes.
+  that support the DataFlash protocol, such as the Adesto AT45DB series of
+  devices. DataFlash is a memory protocol that combines flash with SRAM buffers
+  for a programming interface. DataFlash supports byte-sized read and writes, with
+  an erase size of about 528 bytes or sometimes 1056 bytes. DataFlash provides
+  erase sizes with an extra 16 bytes for error correction codes (ECC), so a flash
+  translation layer (FTL) may still present 512 byte erase sizes.
+  
+  ``` cpp
+  DataFlashBlockDevice bd(
+          MBED_CONF_DATAFLASH_SPI_MOSI,
+          MBED_CONF_DATAFLASH_SPI_MISO,
+          MBED_CONF_DATAFLASH_SPI_CLK,
+          MBED_CONF_DATAFLASH_SPI_CS);
+  ```
 
 - **SDBlockDevice** - Block device driver for SD cards and eMMC memory chips. SD
-cards or eMMC chips offer a full FTL layer on top of NAND flash. This makes the
-storage well-suited for systems that require a about 1GB of memory.
-Additionally, SD cards are a popular form of portable storage. They are useful
-if you want to store data that you can access from a PC.
+  cards or eMMC chips offer a full FTL layer on top of NAND flash. This makes the
+  storage well-suited for systems that require a about 1GB of memory.
+  Additionally, SD cards are a popular form of portable storage. They are useful
+  if you want to store data that you can access from a PC.
+  
+  ``` cpp
+  SDBlockDevice bd(
+          MBED_CONF_SD_SPI_MOSI,
+          MBED_CONF_SD_SPI_MISO,
+          MBED_CONF_SD_SPI_CLK,
+          MBED_CONF_SD_SPI_CS);
+  ```
 
 - [**HeapBlockDevice**](https://os.mbed.com/docs/v5.6/reference/heapblockdevice.html) -
   Block device that simulates storage in RAM using the heap. Do not use the heap
   block device for storing data persistently because a power loss causes
   complete loss of data. Instead, use it fortesting applications when a storage
   device is not available.
+  
+  ``` cpp
+  HeapBlockDevice bd(1024*512, 512);
+  ```
 
 Additionally, Mbed OS contains several utility block devices to give you better
 control over the allocation of storage.
 
-- [**SlicingBlockDevice**](https://os.mbed.com/docs/v5.6/reference/slicingblockdevice.html) -
+- [**SlicingBlockDevice**](https://os.mbed.com/docs/latest/reference/slicingblockdevice.html) -
   With the slicing block device, you can partition storage into smaller block
   devices that you can use independently.
 
-- [**ChainingBlockDevice**](https://os.mbed.com/docs/v5.6/reference/chainingblockdevice.html) -
+- [**ChainingBlockDevice**](https://os.mbed.com/docs/latest/reference/chainingblockdevice.html) -
   With the chaining block device, you can chain multiple block devices together
   and extend the usable amount of storage.
 
-- [**MBRBlockDevice**](https://os.mbed.com/docs/v5.6/reference/mbrblockdevice.html) -
+- [**MBRBlockDevice**](https://os.mbed.com/docs/latest/reference/mbrblockdevice.html) -
   Mbed OS comes with support for storing partitions on disk with a Master Boot
   Record (MBR). The MBRBlockDevice provides this functionality and supports
   creating partitions at runtime or using preformatted partitions configured
@@ -277,3 +330,29 @@
   wear, the exhaustible block device simulates wear on another form of storage.
   You can configure it to expire blocks as necessary.
 
+## Tested configurations
+
+- K64F + Heap + LittleFS
+- K64F + Heap + FATFS
+- K64F + SD + LittleFS
+- K64F + SD + FATFS
+- K64F + SPIF (requires shield) + LittleFS
+- K64F + SPIF (requires shield) + FATFS
+- K64F + DataFlash (requires shield) + LittleFS
+- K64F + DataFlash (requires shield) + FATFS
+- UBLOX_EVK_ODIN_W2 + Heap + LittleFS
+- UBLOX_EVK_ODIN_W2 + Heap + FATFS
+- UBLOX_EVK_ODIN_W2 + SD + LittleFS
+- UBLOX_EVK_ODIN_W2 + SD + FATFS
+- UBLOX_EVK_ODIN_W2 + SPIF (requires shield) + LittleFS
+- UBLOX_EVK_ODIN_W2 + SPIF (requires shield) + FATFS
+- UBLOX_EVK_ODIN_W2 + DataFlash (requires shield) + LittleFS
+- UBLOX_EVK_ODIN_W2 + DataFlash (requires shield) + FATFS
+- NUCLEO_F429ZI + Heap + LittleFS
+- NUCLEO_F429ZI + Heap + FATFS
+- NUCLEO_F429ZI + SD (requires shield) + LittleFS
+- NUCLEO_F429ZI + SD (requires shield) + FATFS
+- NUCLEO_F429ZI + SPIF (requires shield) + LittleFS
+- NUCLEO_F429ZI + SPIF (requires shield) + FATFS
+- NUCLEO_F429ZI + DataFlash (requires shield) + LittleFS
+- NUCLEO_F429ZI + DataFlash (requires shield) + FATFS