Improve explanation for adding a new block device

harrisonmutai-arm · evedon · commit a1c7e3cf2a66 · 2020-12-24T09:36:02.000Z
diff --git a/README.md b/README.md
@@ -35,7 +35,7 @@ to set everything up.
 
 From the command-line, import the example:
 
-```
+``` commandline
 mbed import mbed-os-example-blockdevice
 cd mbed-os-example-blockdevice
 ```
@@ -45,14 +45,14 @@ cd mbed-os-example-blockdevice
 Invoke `mbed compile`, and specify the name of your platform and your favorite
 toolchain (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM Compiler 5:
 
-```
+``` commandline
 mbed compile -m K64F -t ARM
 ```
 
 Your PC may take a few minutes to compile your code. At the end, you see the
 following result:
 
-```
+``` commandline
 [snip]
 +--------------------------+-------+-------+-------+
 | Module                   | .text | .data |  .bss |
@@ -90,7 +90,7 @@ Image: ./BUILD/K64F/ARM/mbed-os-example-blockdevice.bin
 
 Expected output:
 
-```
+``` commandline
 --- Block device geometry ---
 read_size:    1 B
 program_size: 1 B
@@ -118,7 +118,7 @@ bd.deinit -> 0
 
 You can also reset the board to see the data persist across boots:
 
-```
+``` commandline
 --- Block device geometry ---
 read_size:    1 B
 program_size: 1 B
@@ -153,12 +153,12 @@ If you have problems, you can review the [documentation](https://os.mbed.com/doc
 for suggestions on what could be wrong and how to fix it.
 
 ## Changing the block device
+Mbed-OS supports a variety of block device types, more information on supported devices can be found [here](https://os.mbed.com/docs/mbed-os/latest/apis/data-storage.html#Default-BlockDevice-configuration).
 
-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.
+Each device is represented by a C++ class that inherits from the interface class [BlockDevice](https://os.mbed.com/docs/mbed-os/latest/apis/blockdevice-apis.html). These classes take their default configuration from the component configuration file. This may be found in `/mbed-os/storage/blockdevice/` under the path corresponding to the block device type—for example [mbed_lib.json](https://github.com/ARMmbed/mbed-os/blob/master/storage/blockdevice/COMPONENT_SPIF/mbed_lib.json). 
 
-``` diff
+In this example, you can determine which block device is used by modifying the type of `bd` in main.cpp. For instance, if instead you wanted to use a SPIF block device you would declare `bd` as an SPIFBlockDevice instance. 
+```diff
 -SPIFBlockDevice bd(
 -        MBED_CONF_SPIF_DRIVER_SPI_MOSI,
 -        MBED_CONF_SPIF_DRIVER_SPI_MISO,
@@ -170,133 +170,28 @@ example by changing the class declared in main.cpp.
 +        MBED_CONF_SD_SPI_CLK,
 +        MBED_CONF_SD_SPI_CS);
 ```
-
-**Note:** Most block devices require pin assignments. Double check that the
-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.
-
-Starting mbed-os 5.10 the SD, SPIF, DATAFLASH and QSPIF block devices are components under mbed-os. In order to add a component to the application use the "components_add" `target_overrides` configuration:
-
+You may need to make modifications to the application configuration file if you're using a physical storage device that isn't included in your target's default configuration (check in `targets.json` for this). To do this, add your physical storage device as a component in `mbed_app.json` as follows:
+``` json
+   "target_overrides": {
+         "K64F": {
+             "target.components_add": ["SPIF"],
+         }
+     }
 ```
+You can also modify the pin assignments for your component as follows:
+``` json
    "target_overrides": {
-         ...
-         "NUCLEO_F429ZI": {
-             "components_add": ["SPIF"],
-             "SPI_MOSI": "PC_12",
-             "SPI_MISO": "PC_11",
-             "SPI_CLK":  "PC_10",
-             "SPI_CS":   "PA_15"
-         },
-         ...
+         "K64F": {
+             "target.components_add": ["SPIF"],
+             "spif-driver.SPI_MOSI": "PC_12",
+             "spif-driver.SPI_MISO": "PC_11",
+             "spif-driver.SPI_CLK":  "PC_10",
+             "spif-driver.SPI_CS":   "PA_15"
+         }
      }
 ```
-
-The components_add param can be "SPIF", "SD" , "DATAFLASH" or "QSPIF" depends on the block devices you need.
-
-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.
-
-  ``` 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);
-  ```
-
-- **QSPIFBlockDevice** - Block device driver for NOR-based Quad SPI flash devices that
-  support SFDP, with QUAD SPI bus support for 4 bits per cycle (4 times the speed of standard SPI) 
-
-  ``` cpp
-  QSPIFBlockDevice bd(
-          QSPI_FLASH1_IO0, 
-          QSPI_FLASH1_IO1, 
-          QSPI_FLASH1_IO2, 
-          QSPI_FLASH1_IO3,
-          QSPI_FLASH1_SCK, 
-          QSPI_FLASH1_CSN, 
-          QSPIF_POLARITY_MODE_0, 
-          MBED_CONF_QSPIF_QSPI_FREQ);          
-  ```
-
-- **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 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.
-  
-  ``` 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/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/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/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
-  separately from outside the application.
-
-- **ReadOnlyBlockDevice** - With the read-only block device, you can wrap a
-  block device in a read-only layer, ensuring that user of the block device does
-  not modify the storage.
-
-- **ProfilingBlockDevice** - With the profiling block device, you can profile
-  the quantity of erase, program and read operations that are incurred on a
-  block device.
-
-- **ObservingBlockDevice** - The observing block device grants the user the
-  ability to register a callback on block device operations. You can use this to
-  inspect the state of the block device, log different metrics or perform some
-  other operation.
-
-- **ExhaustibleBlockDevice** - Useful for evaluating how file systems respond to
-  wear, the exhaustible block device simulates wear on another form of storage.
-  You can configure it to expire blocks as necessary.
-
-## Tested configurations
+Alternatively, you may use the system's default block device `BlockDevice *bd = BlockDevice::get_default_instance()` but this will require more code changes to the example.
+# Tested configurations
 
 - K64F + Heap
 - K64F + SD
