Add default block device support (SD, SPIF and FLASHIAP) documentation

docs/reference/api/storage/BlockDevice.md

@@ -8,7 +8,7 @@ The most common types of block-based storage are different forms of flash, but t
 
 #### Block device operations
 
-A block device can perform three operations:
+A block device can perform three operations: 
 
 - Read a region of data from storage.
 - Erase a region of data in storage.
@@ -30,6 +30,21 @@ The state of an erased block is **undefined**. The data stored on the block isn'
 
 ![blockdevicesectors](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/blockdevice_erase_block.png)
 
+### BlockDevice get default instance
+Mbed-os configuration allows you to add block devices as components using the targets json file or target overrides in application config file.
+
+When one of the following components is enabled a default block device will be set in the system.
+
+    1. SPIF component.
+    2. DATAFLASH component.
+    3. SD component.
+
+Components can coexist in the system. A device can have SPIF and SD or any combination of block devices enabled but only one default block device.
+
+The list above is in precedence order and show which block device will be the default one if more than one component will be enabled.
+
+For details regarding how to configure the default block device please refer to [storage configuration guide](../../configuration/Storage.md)
+
 ### BlockDevice class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_block_device.html)

docs/reference/api/storage/DataFlashBlockDevice.md

@@ -0,0 +1,49 @@
+# DataFlash block device
+
+DataFlashBlockDevice is a block device driver for I2C-based EEPROM devices, 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 an extra 16 bytes for error correction codes (ECC), so a flash translation layer (FTL) may still present 512 byte erase sizes.
+
+You can configure the DataFlashBlockDevice to force the underlying device to use either the binary size (in other words, 512 bytes) or the raw DataFlash size (in other words, 528 bytes).
+
+### DataFlashBlockDevice class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](<Should be added after doxygen run>)
+
+### DataFlashBlockDevice example:
+
+``` cpp
+// Here's an example using the AT45DB on the K64F
+#include "mbed.h"
+#include "DataFlashBlockDevice.h"
+
+// Create DataFlash on SPI bus with PTE5 as chip select
+DataFlashBlockDevice dataflash(PTE2, PTE4, PTE1, PTE5);
+
+// Create DataFlash on SPI bus with PTE6 as write-protect
+DataFlashBlockDevice dataflash2(PTE2, PTE4, PTE1, PTE5, PTE6);
+
+int main() {
+    printf("dataflash test\n");
+
+    // Initialize the SPI flash device and print the memory layout
+    dataflash.init();
+    printf("dataflash size: %llu\n", dataflash.size());
+    printf("dataflash read size: %llu\n", dataflash.get_read_size());
+    printf("dataflash program size: %llu\n", dataflash.get_program_size());
+    printf("dataflash erase size: %llu\n", dataflash.get_erase_size());
+
+    // Write "Hello World!" to the first block
+    char *buffer = (char*)malloc(dataflash.get_erase_size());
+    sprintf(buffer, "Hello World!\n");
+    dataflash.erase(0, dataflash.get_erase_size());
+    dataflash.program(buffer, 0, dataflash.get_erase_size());
+
+    // Read back what was stored
+    dataflash.read(buffer, 0, dataflash.get_erase_size());
+    printf("%s", buffer);
+
+    // Deinitialize the device
+    dataflash.deinit();
+}
+```

docs/reference/api/storage/FileSystem.md

@@ -6,6 +6,19 @@ The main purpose of a FileSystem is to be instantiated. The FileSystem's constru
 
 The FileSystem's `file` and `dir` functions are protected because you should not use the FileSystem `file` and `dir` functions directly. They are only a convenience for implementors. Instead, the [File](file.html) and [Dir](dir.html) classes provide access to file and directory operations in a C++ class that respects [RAII](/docs/development/introduction/glossary.html#r) and other C++ conventions.
 
+### File system get default instance
+
+Mbed-os configuration allows you to add block devices as components using the targets json file or target overrides in application config file.
+When a component of SPIF, DATAFLASH or SD are configured then the system will support one default file system.
+
+Please note that while a default file system exists an application is not enforced to use it and can create its own one.
+
+The default file system will be created based on the default block device due to performance considerations.
+SPIF and DATAFLASH block devices will support Little file system while SD block device will support FAT file system.
+However this behaviour can be override by the application.
+
+For details regarding how to configure the default file system or override its implemetation please refer to [storage configuration guide](../../configuration/Storage.md)
+
 ### File system class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_file_system.html)

docs/reference/api/storage/FlashIAPBlockDevice.md

@@ -0,0 +1,47 @@
+## FlashIAPBlockDevice
+
+The flash IAP block device is a block device driver built on top of the FlashIAP API. This actually enable using the internal flash memory as a block device. The read size, write size and erase size may defer between different flash chip. use the FlashIAPBlockDevice get function to discover the those size.
+More info can be find in the example below.
+
+Additional concerns:
+    1. This driver should be use on platforms where the FlashIAP implementation uses external flash or in conjunction with a file system with wear leveling, that can operate on a page size granularity.
+
+    2. The FlashIAP may freeze code execution for a long period of time while writing to flash. Not even high-priority IRQs are allowed to run, which may interrupt background processes.
+
+## FlashIAPBlockDevice class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](<Should be added after doxygen run>)
+
+## FlashIAPBlockDevicesBlockDevice example:
+
+``` cpp
+#include "mbed.h"
+#include "FlashIAPBlockDevice.h"
+
+// Create flash block device. 
+FlashIAPBlockDevice bd;
+
+int main() {
+    printf("FlashIAPBlockDevice test\n");
+
+    // Initialize the FLASHIAP device and print the memory layout
+    bd.init();
+    printf("Flash block device size: %llu\n",         bd.size());
+    printf("Flash block device read size: %llu\n",    bd.get_read_size());
+    printf("Flash block device program size: %llu\n", bd.get_program_size());
+    printf("Flash block device erase size: %llu\n",   bd.get_erase_size());
+
+    // Write "Hello World!" to the first block
+    char *buffer = (char*)malloc(bd.get_erase_size());
+    sprintf(buffer, "Hello World!\n");
+    bd.erase(0, bd.get_erase_size());
+    bd.program(buffer, 0, bd.get_erase_size());
+
+    // Read back what was stored
+    bd.read(buffer, 0, bd.get_erase_size());
+    printf("%s", buffer);
+
+    // Deinitialize the device
+    bd.deinit();
+}
+```

docs/reference/api/storage/SDBlockDevice.md

@@ -0,0 +1,119 @@
+## SDBlockDevice
+
+You can use the Mbed OS SD card block device, so applications can read and write data to flash storage cards using the standard POSIX File API programming interface. Applications use the FAT filesystem and SD block device components to persistently store data on SDCards. The SD block device uses the SD card SPI-mode of operation, which is a subset of possible SD card functionality.
+
+### Mbed OS file system software componentstack
+
+
+    ------------------------
+    |                      |
+    |    Application       |        // This application uses the POSIX File API
+    |                      |        // to read/write data to persistent storage backends.
+    ------------------------
+
+    ------------------------        // POSIX File API (ISO).
+
+    ------------------------
+    |                      |
+    |     libc             |        // The standard c library implementation
+    |                      |        // for example, newlib.
+    ------------------------
+
+    ------------------------        // sys_xxx equivalent API.
+
+    ------------------------
+    |                      |
+    |  mbed_retarget.cpp   |        // Target specific mapping layer.
+    |                      |
+    ------------------------
+
+    ------------------------        // File system Upper Edge API.
+
+    ------------------------
+    |                      |
+    |     File System      |        // File system wrappers and implementation.
+    |                      |
+    ------------------------
+
+    ------------------------        // FS Lower Edge API (Block Store Interface).
+
+    ------------------------
+    |    Block API         |
+    |  Device Block device |        // The SD card block device, for example.
+    |  e.g. SDBlockDevice  |
+    ------------------------
+
+    ------------------------        // SPI.h interface.
+
+    ------------------------
+    |                      |
+    |       SPI            |        // SPI subsystem (C++ classes and C-HAL implementation).
+    |                      |
+    ------------------------
+
+    Figure 1. Mbed OS generic architecture of filesystem software stack.
+
+The figure above shows the Mbed OS software component stack used for data storage on the SD card:
+
+- At the top level is the application component, which uses the standard POSIX File API to read and write application data to persistent storage.
+- The newlib standard library (libc) `stdio.h` interface (POSIX File API) implementation is optimized for resource-limited embedded systems.
+- `mbed_retarget.cpp` implements the libc backend file OS handlers and maps them to the file system.
+- The file system code (hosted in `mbed-os`) is composed of 2 parts: the FAT file system implementation code and the file system classes that present a consistent API to the retarget module for different (third-party) file system implementations.
+- The Block API. The SDCard block device is a persistent storage block device.
+- The SPI module provides the Mbed OS SPI API.
+
+### SDBlockDevice class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](<Should be added after doxygen run>)
+
+### SDBlockDevice example application
+
+The following sample code illustrates how to use the SD block device API:
+
+``` cpp
+#include "mbed.h"
+#include "SDBlockDevice.h"
+
+// Instantiate the SDBlockDevice by specifying the SPI pins connected to the SDCard
+// socket. The PINS are:
+//     MOSI (Master Out Slave In)
+//     MISO (Master In Slave Out)
+//     SCLK (Serial Clock)
+//     CS (Chip Select)
+SDBlockDevice sd(MBED_CONF_SD_SPI_MOSI, MBED_CONF_SD_SPI_MISO, MBED_CONF_SD_SPI_CLK, MBED_CONF_SD_SPI_CS);
+uint8_t block[512] = "Hello World!\n";
+
+int main()
+{
+    // call the SDBlockDevice instance initialisation method.
+    if ( 0 != sd.init()) {
+        printf("Init failed \n");
+        return -1;
+    }
+    printf("sd size: %llu\n",         sd.size());
+    printf("sd read size: %llu\n",    sd.get_read_size());
+    printf("sd program size: %llu\n", sd.get_program_size());
+    printf("sd erase size: %llu\n",   sd.get_erase_size());
+
+    // set the frequency
+    if ( 0 != sd.frequency(5000000)) {
+        printf("Error setting frequency \n");
+    }
+
+    if ( 0 != sd.erase(0, sd.get_erase_size())) {
+        printf("Error Erasing block \n");
+    }
+
+    // Write some the data block to the device
+    if ( 0 == sd.program(block, 0, 512)) {
+        // read the data block from the device
+        if ( 0 == sd.read(block, 0, 512)) {
+            // print the contents of the block
+            printf("%s", block);
+        }
+    }
+
+    // call the SDBlockDevice instance de-initialisation method.
+    sd.deinit();
+}
+```

docs/reference/api/storage/SPIFBlockDevice.md

@@ -0,0 +1,44 @@
+## SPI Flash block device
+
+This API is a block device for NOR-based SPI flash devices that support SFDP.
+
+NOR-based SPI flash supports byte-sized read and writes, with an erase size of around 4 kbytes. An erase sets a block to all 1s, with successive writes clearing set bits.
+
+### SPIFBlockDevice class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](<Should be added after doxygen run>)
+
+### SPIFBlockDevice example:
+
+``` cpp
+// Here's an example using the MX25R SPI flash device on the K82F
+#include "mbed.h"
+#include "SPIFBlockDevice.h"
+
+// Create flash device on SPI bus with PTE5 as chip select
+SPIFBlockDevice spif(PTE2, PTE4, PTE1, PTE5);
+
+int main() {
+    printf("spif test\n");
+
+    // Initialize the SPI flash device and print the memory layout
+    spif.init();
+    printf("spif size: %llu\n",         spif.size());
+    printf("spif read size: %llu\n",    spif.get_read_size());
+    printf("spif program size: %llu\n", spif.get_program_size());
+    printf("spif erase size: %llu\n",   spif.get_erase_size());
+
+    // Write "Hello World!" to the first block
+    char *buffer = (char*)malloc(spif.get_erase_size());
+    sprintf(buffer, "Hello World!\n");
+    spif.erase(0, spif.get_erase_size());
+    spif.program(buffer, 0, spif.get_erase_size());
+
+    // Read back what was stored
+    spif.read(buffer, 0, spif.get_erase_size());
+    printf("%s", buffer);
+
+    // Deinitialize the device
+    spif.deinit();
+}
+```