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,66 @@ 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.
+
+#### configuring component:
+Adding "components": ["???"] in targets.json:
+```
+    "K64F": {
+        "supported_form_factors": ["ARDUINO"],
+        "components": ["SD"],
+        "core": "Cortex-M4F",
+        "supported_toolchains": ["ARM", "GCC_ARM", "IAR"],
+        "extra_labels": ["Freescale", "MCUXpresso_MCUS", "KSDK2_MCUS", "FRDM", "KPSDK_MCUS", "KPSDK_CODE", "MCU_K64F", "Freescale_EMAC"],
+        "is_disk_virtual": true,
+        "macros": ["CPU_MK64FN1M0VMD12", "FSL_RTOS_MBED"],
+        "inherits": ["Target"],
+        "detect_code": ["0240"],
+        "device_has": ["USTICKER", "LPTICKER", "RTC", "CRC", "ANALOGIN", "ANALOGOUT", "EMAC", "I2C", "I2CSLAVE", "INTERRUPTIN", "PORTIN", "PORTINOUT", "PORTOUT", "PWMOUT", "SERIAL", "SERIAL_FC", "SERIAL_ASYNCH", "SLEEP", "SPI", "SPI_ASYNCH", "SPISLAVE", "STDIO_MESSAGES", "STORAGE", "TRNG", "FLASH"],
+        "features": ["STORAGE"],
+        "release_versions": ["2", "5"],
+        "device_name": "MK64FN1M0xxx12",
+        "bootloader_supported": true,
+        "overrides": {
+            "network-default-interface-type": "ETHERNET"
+        }
+    },
+```
+Adding "target.components_add": ["???"] in application config file:
+```     
+       "MTB_ADV_WISE_1570": {
+            "target.components_add": ["SPIF"],
+            "target.features_add": ["LWIP"],
+            "platform.default-serial-baud-rate": 9600
+       }
+```
+
+Please note that while a default block device exists an application is not enforced to use it and can create its own one.
+
+### Overriding default block device implementation 
+The get default instance is implemented as MBED_WEAK at features/storage/system_storage/SystemStorage.cpp. That means that it can be overridden by implementing the function without MBED_WEAK and change the default block device for a given application.
+
+```
+#include "HeapBlockDevice.h"
+
+BlockDevice *BlockDevice::get_default_instance()
+{
+    static HeapBlockDevice default_bd(32 *1024);
+    return &default_bd;
+}
+```
+
 ### 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,61 @@
+# DataFlash block device
+
+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
+simple 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 that a flash translation layer (FTL) may still present 512 byte erase sizes.
+
+The DataFlashBlockDevice can be configured to force the underlying device
+to use either the binary size (ie 512 bytes) or the raw DataFlash size
+(ie 528 bytes).
+
+More info on DataFlash can be found on wikipedia:
+https://en.wikipedia.org/wiki/DataFlash
+
+
+### 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,34 @@ 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.
+
+### Overriding default block device implementation
+
+The get default instance is implemented as MBED_WEAK at features/storage/system_storage/SystemStorage.cpp. That means that it can be overridden by implementing the function without MBED_WEAK and change the default block device for a given application.
+
+The following example will override the get default instance of and will always return a FAT file system regardless of the block device type.
+
+```
+#include "FATFileSystem.h"
+
+FileSystem *FileSystem::get_default_instance()
+{
+    static FATFileSystem default_fs("fs" BlockDevice::get_default_instance());
+
+    return &default_fs;
+}
+
+```
+
 ### 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,21 @@
+# Block Device driver build on top of FlashIAP API
+
+## Warning 
+Improper usage of this block device could kill your board's flash.
+
+This driver should only be used on platforms where the FlashIAP implementation is using external flash or in conjunction with a filesystem with wear leveling, that can operate on a page size granularity.
+
+Additional concerns:
+- The FlashIAP may freeze code execution for a long period of time while writing to flash. Not even high-priority irqs will be 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>)
+
+## Configuration
+None.
+
+## Tested on
+
+* K82F
+* K64F