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,12 @@ 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
+
+The Mbed OS configuration allows you to add block devices as components using the `targets.json` file or target overrides in the application configuration file.
+
+For details regarding how to configure the default block device please refer to the [storage configuration guide](/docs/development/reference/configuration-storage.html)
+
 ### 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)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_data_flash_block_device.html)
+
+### 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,12 @@ 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
+
+The Mbed OS configuration allows you to add block devices as components using the `targets.json` file or target overrides in the application configuration file.
+
+For details regarding how to configure the default file system or override its implemetation, please refer to the [storage configuration guide](/docs/development/reference/configuration-storage.html).
+
 ### 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,46 @@
+## FlashIAPBlockDevice
+
+The flash IAP block device is a block device driver built on top of the FlashIAP API. This is enabled using the internal flash memory as a block device. The read size, write size and erase size may differ, depending on the flash chip. Use the FlashIAPBlockDevice `get` function to discover those sizes.
+
+Additional notes:
+
+1. Use this driver 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.
+1. 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)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_flash_i_a_p_block_device.html)
+
+## 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)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_s_d_block_device.html)
+
+### 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)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_s_p_i_f_block_device.html)
+
+### 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();
+}
+```