Skip to content

Commit 1becbc4

Browse files
author
Amanda Butler
authored
Merge pull request #685 from yossi2le/sd-spif-to-mbed-os
Add default block device support (SD, SPIF and FLASHIAP) documentation
2 parents 2d8d419 + 3759d01 commit 1becbc4

File tree

9 files changed

+359
-5
lines changed

9 files changed

+359
-5
lines changed

‎docs/images/NUCLEO_F429ZI_wiring_with_ci_test_shield.png

502 KB
Loading

‎docs/reference/api/storage/BlockDevice.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The most common types of block-based storage are different forms of flash, but t
88

99
#### Block device operations
1010

11-
A block device can perform three operations:
11+
A block device can perform three operations:
1212

1313
- Read a region of data from storage.
1414
- 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'
3030

3131
![blockdevicesectors](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/blockdevice_erase_block.png)
3232

33+
### BlockDevice get default instance
34+
35+
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.
36+
37+
For details regarding how to configure the default block device please refer to the [storage configuration guide](/docs/development/reference/configuration-storage.html)
38+
3339
### BlockDevice class reference
3440

3541
[![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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# DataFlash block device
2+
3+
DataFlashBlockDevice is a block device driver for I2C-based EEPROM devices, such as the Adesto AT45DB series of devices.
4+
5+
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.
6+
7+
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).
8+
9+
### DataFlashBlockDevice class reference
10+
11+
[![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)
12+
13+
### DataFlashBlockDevice example:
14+
15+
``` cpp
16+
// Here's an example using the AT45DB on the K64F
17+
#include "mbed.h"
18+
#include "DataFlashBlockDevice.h"
19+
20+
// Create DataFlash on SPI bus with PTE5 as chip select
21+
DataFlashBlockDevice dataflash(PTE2, PTE4, PTE1, PTE5);
22+
23+
// Create DataFlash on SPI bus with PTE6 as write-protect
24+
DataFlashBlockDevice dataflash2(PTE2, PTE4, PTE1, PTE5, PTE6);
25+
26+
int main() {
27+
printf("dataflash test\n");
28+
29+
// Initialize the SPI flash device and print the memory layout
30+
dataflash.init();
31+
printf("dataflash size: %llu\n", dataflash.size());
32+
printf("dataflash read size: %llu\n", dataflash.get_read_size());
33+
printf("dataflash program size: %llu\n", dataflash.get_program_size());
34+
printf("dataflash erase size: %llu\n", dataflash.get_erase_size());
35+
36+
// Write "Hello World!" to the first block
37+
char *buffer = (char*)malloc(dataflash.get_erase_size());
38+
sprintf(buffer, "Hello World!\n");
39+
dataflash.erase(0, dataflash.get_erase_size());
40+
dataflash.program(buffer, 0, dataflash.get_erase_size());
41+
42+
// Read back what was stored
43+
dataflash.read(buffer, 0, dataflash.get_erase_size());
44+
printf("%s", buffer);
45+
46+
// Deinitialize the device
47+
dataflash.deinit();
48+
}
49+
```

‎docs/reference/api/storage/FileSystem.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ The main purpose of a FileSystem is to be instantiated. The FileSystem's constru
66

77
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.
88

9+
### File system get default instance
10+
11+
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.
12+
13+
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).
14+
915
### File system class reference
1016

1117
[![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

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
## FlashIAPBlockDevice
2+
3+
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.
4+
5+
Additional notes:
6+
7+
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.
8+
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.
9+
10+
## FlashIAPBlockDevice class reference
11+
12+
[![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)
13+
14+
## FlashIAPBlockDevicesBlockDevice example:
15+
16+
``` cpp
17+
#include "mbed.h"
18+
#include "FlashIAPBlockDevice.h"
19+
20+
// Create flash block device.
21+
FlashIAPBlockDevice bd;
22+
23+
int main() {
24+
printf("FlashIAPBlockDevice test\n");
25+
26+
// Initialize the FLASHIAP device and print the memory layout
27+
bd.init();
28+
printf("Flash block device size: %llu\n", bd.size());
29+
printf("Flash block device read size: %llu\n", bd.get_read_size());
30+
printf("Flash block device program size: %llu\n", bd.get_program_size());
31+
printf("Flash block device erase size: %llu\n", bd.get_erase_size());
32+
33+
// Write "Hello World!" to the first block
34+
char *buffer = (char*)malloc(bd.get_erase_size());
35+
sprintf(buffer, "Hello World!\n");
36+
bd.erase(0, bd.get_erase_size());
37+
bd.program(buffer, 0, bd.get_erase_size());
38+
39+
// Read back what was stored
40+
bd.read(buffer, 0, bd.get_erase_size());
41+
printf("%s", buffer);
42+
43+
// Deinitialize the device
44+
bd.deinit();
45+
}
46+
```

‎docs/reference/api/storage/SDBlockDevice.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
## SDBlockDevice
2+
3+
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.
4+
5+
### Mbed OS file system software componentstack
6+
7+
8+
------------------------
9+
| |
10+
| Application | // This application uses the POSIX File API
11+
| | // to read/write data to persistent storage backends.
12+
------------------------
13+
14+
------------------------ // POSIX File API (ISO).
15+
16+
------------------------
17+
| |
18+
| libc | // The standard c library implementation
19+
| | // for example, newlib.
20+
------------------------
21+
22+
------------------------ // sys_xxx equivalent API.
23+
24+
------------------------
25+
| |
26+
| mbed_retarget.cpp | // Target specific mapping layer.
27+
| |
28+
------------------------
29+
30+
------------------------ // File system Upper Edge API.
31+
32+
------------------------
33+
| |
34+
| File System | // File system wrappers and implementation.
35+
| |
36+
------------------------
37+
38+
------------------------ // FS Lower Edge API (Block Store Interface).
39+
40+
------------------------
41+
| Block API |
42+
| Device Block device | // The SD card block device, for example.
43+
| e.g. SDBlockDevice |
44+
------------------------
45+
46+
------------------------ // SPI.h interface.
47+
48+
------------------------
49+
| |
50+
| SPI | // SPI subsystem (C++ classes and C-HAL implementation).
51+
| |
52+
------------------------
53+
54+
Figure 1. Mbed OS generic architecture of filesystem software stack.
55+
56+
The figure above shows the Mbed OS software component stack used for data storage on the SD card:
57+
58+
- At the top level is the application component, which uses the standard POSIX File API to read and write application data to persistent storage.
59+
- The newlib standard library (libc) `stdio.h` interface (POSIX File API) implementation is optimized for resource-limited embedded systems.
60+
- `mbed_retarget.cpp` implements the libc backend file OS handlers and maps them to the file system.
61+
- 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.
62+
- The Block API. The SDCard block device is a persistent storage block device.
63+
- The SPI module provides the Mbed OS SPI API.
64+
65+
### SDBlockDevice class reference
66+
67+
[![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)
68+
69+
### SDBlockDevice example application
70+
71+
The following sample code illustrates how to use the SD block device API:
72+
73+
``` cpp
74+
#include "mbed.h"
75+
#include "SDBlockDevice.h"
76+
77+
// Instantiate the SDBlockDevice by specifying the SPI pins connected to the SDCard
78+
// socket. The PINS are:
79+
// MOSI (Master Out Slave In)
80+
// MISO (Master In Slave Out)
81+
// SCLK (Serial Clock)
82+
// CS (Chip Select)
83+
SDBlockDevice sd(MBED_CONF_SD_SPI_MOSI, MBED_CONF_SD_SPI_MISO, MBED_CONF_SD_SPI_CLK, MBED_CONF_SD_SPI_CS);
84+
uint8_t block[512] = "Hello World!\n";
85+
86+
int main()
87+
{
88+
// call the SDBlockDevice instance initialisation method.
89+
if ( 0 != sd.init()) {
90+
printf("Init failed \n");
91+
return -1;
92+
}
93+
printf("sd size: %llu\n", sd.size());
94+
printf("sd read size: %llu\n", sd.get_read_size());
95+
printf("sd program size: %llu\n", sd.get_program_size());
96+
printf("sd erase size: %llu\n", sd.get_erase_size());
97+
98+
// set the frequency
99+
if ( 0 != sd.frequency(5000000)) {
100+
printf("Error setting frequency \n");
101+
}
102+
103+
if ( 0 != sd.erase(0, sd.get_erase_size())) {
104+
printf("Error Erasing block \n");
105+
}
106+
107+
// Write some the data block to the device
108+
if ( 0 == sd.program(block, 0, 512)) {
109+
// read the data block from the device
110+
if ( 0 == sd.read(block, 0, 512)) {
111+
// print the contents of the block
112+
printf("%s", block);
113+
}
114+
}
115+
116+
// call the SDBlockDevice instance de-initialisation method.
117+
sd.deinit();
118+
}
119+
```

‎docs/reference/api/storage/SPIFBlockDevice.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
## SPI Flash block device
2+
3+
This API is a block device for NOR-based SPI flash devices that support SFDP.
4+
5+
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.
6+
7+
### SPIFBlockDevice class reference
8+
9+
[![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)
10+
11+
### SPIFBlockDevice example:
12+
13+
``` cpp
14+
// Here's an example using the MX25R SPI flash device on the K82F
15+
#include "mbed.h"
16+
#include "SPIFBlockDevice.h"
17+
18+
// Create flash device on SPI bus with PTE5 as chip select
19+
SPIFBlockDevice spif(PTE2, PTE4, PTE1, PTE5);
20+
21+
int main() {
22+
printf("spif test\n");
23+
24+
// Initialize the SPI flash device and print the memory layout
25+
spif.init();
26+
printf("spif size: %llu\n", spif.size());
27+
printf("spif read size: %llu\n", spif.get_read_size());
28+
printf("spif program size: %llu\n", spif.get_program_size());
29+
printf("spif erase size: %llu\n", spif.get_erase_size());
30+
31+
// Write "Hello World!" to the first block
32+
char *buffer = (char*)malloc(spif.get_erase_size());
33+
sprintf(buffer, "Hello World!\n");
34+
spif.erase(0, spif.get_erase_size());
35+
spif.program(buffer, 0, spif.get_erase_size());
36+
37+
// Read back what was stored
38+
spif.read(buffer, 0, spif.get_erase_size());
39+
printf("%s", buffer);
40+
41+
// Deinitialize the device
42+
spif.deinit();
43+
}
44+
```

0 commit comments

Comments
 (0)