add BlockDevices examples

APIs_Storage/ChainingBlockDevice_ex_1/README.md

@@ -0,0 +1,4 @@
+# ChainingBlockDevice example
+
+
+This example shows how to use `ChainingBlockDevice` to format a FATFileSystem on two blocks of storage.

APIs_Storage/ChainingBlockDevice_ex_1/main.cpp

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2017-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mbed.h"
+#include "HeapBlockDevice.h"
+#include "ChainingBlockDevice.h"
+#include "FATFileSystem.h"
+
+#define BLOCKSIZE 512
+
+int main(void)
+{
+    // Create two smaller block devices with
+    // 64 and 32 blocks of size 512 bytes
+    HeapBlockDevice mem1(64 * BLOCKSIZE, BLOCKSIZE);
+    HeapBlockDevice mem2(32 * BLOCKSIZE, BLOCKSIZE);
+
+    // Create a block device backed by mem1 and mem2
+    // contains 96 blocks of size 512 bytes
+    BlockDevice *bds[] = {&mem1, &mem2};
+    ChainingBlockDevice chainmem(bds);
+
+    // Format the new chained block device with a FAT filesystem
+    FATFileSystem::format(&chainmem);
+
+    // Create the FAT filesystem instance, files can now be written to
+    // the FAT filesystem as if to a single 96 x 512 byte storage device
+    FATFileSystem fat("fat", &chainmem);
+}

APIs_Storage/ChainingBlockDevice_ex_2/README.md

@@ -0,0 +1,3 @@
+# ChainingBlockDevice example
+
+This example shows how to use `ChainingBlockDevice` to program and read from a chained group of HeapBlockDevices.

APIs_Storage/ChainingBlockDevice_ex_2/main.cpp

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2017-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mbed.h"
+#include "HeapBlockDevice.h"
+#include "ChainingBlockDevice.h"
+
+#define BLOCKSIZE 512
+char buffer1[BLOCKSIZE];
+char buffer2[BLOCKSIZE];
+
+int main(void)
+{
+    // Create two smaller block devices with
+    // 64 and 32 blocks of size 512 bytes
+    HeapBlockDevice mem1(64 * BLOCKSIZE, BLOCKSIZE);
+    HeapBlockDevice mem2(32 * BLOCKSIZE, BLOCKSIZE);
+
+    // Create a block device backed by mem1 and mem2
+    // contains 96 blocks of size 512 bytes
+    BlockDevice *bds[] = {&mem1, &mem2};
+    ChainingBlockDevice chainmem(bds);
+
+    // Initialize the block devices
+    chainmem.init();
+
+    // Erase the block device to prepare for programming. 64 and 32 refer to
+    // the respective number of blocks in mem1 and mem2
+    chainmem.erase(0, (BLOCKSIZE * (64 + 32)));
+
+    // Program strings to the block device at byte-addressable locations that
+    // span both sub blocks. The second program will write past the end of the
+    // first block
+    chainmem.program("data for block", 0, BLOCKSIZE);
+    chainmem.program("Some more data", (65 * BLOCKSIZE), BLOCKSIZE);
+
+    // Readback the written values
+    chainmem.read(&buffer1, 0, BLOCKSIZE);
+    chainmem.read(&buffer2, (65 * BLOCKSIZE), BLOCKSIZE);
+    printf("Read back: %s, %s\r\n", buffer1, buffer2);
+}

APIs_Storage/HeapBlockDevice_ex_1/README.md

@@ -0,0 +1,3 @@
+# HeapBlockDevice example
+
+This example shows how to initialize and use `HeapBlockDevice`.

APIs_Storage/HeapBlockDevice_ex_1/main.cpp

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2017-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mbed.h"
+#include "HeapBlockDevice.h"
+
+#define BLOCK_SIZE 512
+
+HeapBlockDevice bd(2048, BLOCK_SIZE); // 2048 bytes with a block size of 512 bytes
+uint8_t block[BLOCK_SIZE] = "Hello World!\n";
+
+int main()
+{
+    bd.init();
+    bd.erase(0, BLOCK_SIZE);
+    bd.program(block, 0, BLOCK_SIZE);
+    bd.read(block, 0, BLOCK_SIZE);
+    printf("%s", block);
+    bd.deinit();
+}

APIs_Storage/MBRBlockDevice_ex_1/README.md

@@ -1,3 +1,3 @@
-# MBRBlockDevice example 1
+# MBRBlockDevice example
 
-Partition a heap backed block device into two partitions. This example also uses the HeapBlockDevice. To see this example in context, please see its [published documentation](https://os.mbed.com/docs/mbed-os/latest/apis/mbrblockdevice.html).
+This example shows how use `MBRBlockDevice` to partition a heap block device into two partitions. To see this example in context, please see its [published documentation](https://os.mbed.com/docs/mbed-os/latest/apis/mbrblockdevice.html).

APIs_Storage/MBRBlockDevice_ex_1/main.cpp

@@ -1,17 +1,24 @@
+/*
+ * Copyright (c) 2017-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 #include "mbed.h"
 #include "HeapBlockDevice.h"
 #include "MBRBlockDevice.h"
 
+#define BLOCK_SIZE 512
+
 int main(void)
 {
     // Create a block device with 64 blocks of size 512
     printf("Create a block device with 64 blocks of size 512\n");
-    HeapBlockDevice mem(64 * 512, 512);
+    HeapBlockDevice mem(64 * BLOCK_SIZE, BLOCK_SIZE);
 
     // Partition into two partitions with ~half the blocks
     printf("Partition into two partitions with ~half the blocks\n");
-    MBRBlockDevice::partition(&mem, 1, 0x83, 0 * 512, 32 * 512);
-    MBRBlockDevice::partition(&mem, 2, 0x83, 32 * 512);
+    MBRBlockDevice::partition(&mem, 1, 0x83, 0 * BLOCK_SIZE, 32 * BLOCK_SIZE);
+    MBRBlockDevice::partition(&mem, 2, 0x83, 32 * BLOCK_SIZE);
 
     // Create a block device that maps to the first 32 blocks (excluding MBR block)
     printf("Create a block device that maps to the first 32 blocks (excluding MBR block)\n");

APIs_Storage/MBRBlockDevice_ex_2/README.md

@@ -1,4 +1,3 @@
-# MBRBlockDevice example 2
-
-Partition an SD card, and format the new partition with a FAT filesystem. The SD card is now recognizable to devices.
+# MBRBlockDevice example
 
+This example shows how use `MBRBlockDevice` to partition an SD card, and format the new partition with a FAT filesystem. The SD card is now recognizable to devices.

APIs_Storage/MBRBlockDevice_ex_2/main.cpp

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) 2017-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 #include "mbed.h"
 #include "SDBlockDevice.h"
 #include "MBRBlockDevice.h"

APIs_Storage/ProfilingBlockDevice/README.md

@@ -1,3 +1,3 @@
 # ProfilingBlockDevice example
 
-Create a ProfilingBlockDevice, perform storage operations and report back the read, write and erase counts. To see this example in context, please see its [published documentation](https://os.mbed.com/docs/mbed-os/latest/apis/profilingblockdevice.html).
+This example shows how to use a `ProfilingBlockDevice` to perform storage operations and report back the read, write and erase counts. To see this example in context, please see its [published documentation](https://os.mbed.com/docs/mbed-os/latest/apis/profilingblockdevice.html).

APIs_Storage/ProfilingBlockDevice/main.cpp

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) 2017-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 #include "mbed.h"
 #include "HeapBlockDevice.h"
 #include "ProfilingBlockDevice.h"

APIs_Storage/SlicingBlockDevice/README.md

@@ -1,3 +1,3 @@
 # SlicingBlockDevice example
 
-This SlicingBlockDevice example partitions a HeapBlockDevice into three subunits. It showcases programming and reading back data segments, through both the underlying master block device and sliced subunits. To see this example in context, please see its [published documentation](https://os.mbed.com/docs/mbed-os/latest/apis/slicingblockdevice.html).
+This example shows how to use `SlicingBlockDevice` to partition a HeapBlockDevice into three subunits. It showcases programming and reading back data segments, through both the underlying master block device and sliced subunits. To see this example in context, please see its [published documentation](https://os.mbed.com/docs/mbed-os/latest/apis/slicingblockdevice.html).

APIs_Storage/SlicingBlockDevice/main.cpp

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) 2017-2020 Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 #include "mbed.h"
 #include "HeapBlockDevice.h"
 #include "SlicingBlockDevice.h"