Seeed
SD card example code for Seeed Wio 3G
Fork of
Wio_3G-example-sd-driver
by 
Toyomasa Watarai
sd-driver/README.md@0:8eedb2495d52, 2018-08-09 (annotated)
- Committer:
- MACRUM
- Date:
- Thu Aug 09 01:42:53 2018 +0000
- Revision:
- 0:8eedb2495d52
Initial commit
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| MACRUM | 0:8eedb2495d52 | 1 | # mbed OS SDCard Driver (sd-driver) for FAT32 Filesystem Support |
| MACRUM | 0:8eedb2495d52 | 2 | |
| MACRUM | 0:8eedb2495d52 | 3 | |
| MACRUM | 0:8eedb2495d52 | 4 | Simon Hughes |
| MACRUM | 0:8eedb2495d52 | 5 | |
| MACRUM | 0:8eedb2495d52 | 6 | 20170329 |
| MACRUM | 0:8eedb2495d52 | 7 | |
| MACRUM | 0:8eedb2495d52 | 8 | Version 0.1.2 |
| MACRUM | 0:8eedb2495d52 | 9 | |
| MACRUM | 0:8eedb2495d52 | 10 | |
| MACRUM | 0:8eedb2495d52 | 11 | # Executive Summary |
| MACRUM | 0:8eedb2495d52 | 12 | |
| MACRUM | 0:8eedb2495d52 | 13 | The purpose of this document is to describe how to use the mbed OS SDCard |
| MACRUM | 0:8eedb2495d52 | 14 | driver (sd-driver) so applications can read/write |
| MACRUM | 0:8eedb2495d52 | 15 | data to flash storage cards using the standard POSIX File API |
| MACRUM | 0:8eedb2495d52 | 16 | programming interface. The sd-driver uses the SDCard SPI-mode of operation |
| MACRUM | 0:8eedb2495d52 | 17 | which is a subset of possible SDCard functionality. |
| MACRUM | 0:8eedb2495d52 | 18 | |
| MACRUM | 0:8eedb2495d52 | 19 | This repository contains the mbed-os SDCard driver for generic SPI |
| MACRUM | 0:8eedb2495d52 | 20 | SDCard support and other resources, as outlined below: |
| MACRUM | 0:8eedb2495d52 | 21 | |
| MACRUM | 0:8eedb2495d52 | 22 | - `SDBlockDevice.h` and `SDBlockDevice.cpp`. This is the SDCard driver module presenting |
| MACRUM | 0:8eedb2495d52 | 23 | a Block Device API (derived from BlockDevice) to the underlying SDCard. |
| MACRUM | 0:8eedb2495d52 | 24 | - POSIX File API test cases for testing the FAT32 filesystem on SDCard. |
| MACRUM | 0:8eedb2495d52 | 25 | - basic.cpp, a basic set of functional test cases. |
| MACRUM | 0:8eedb2495d52 | 26 | - fopen.cpp, more functional tests reading/writing greater volumes of data to SDCard, for example. |
| MACRUM | 0:8eedb2495d52 | 27 | - `mbed_lib.json` mbed-os application configuration file with SPI pin configurations and overrides for specific targets. |
| MACRUM | 0:8eedb2495d52 | 28 | This file allows the SPI pins to be specified for the target without having to edit the implementation files. |
| MACRUM | 0:8eedb2495d52 | 29 | - This README which includes [Summary of POSIX File API Documentation](#summary-posix-api-documentation) |
| MACRUM | 0:8eedb2495d52 | 30 | including detailed instruction on how to use the FAT filesystem and SDBlockDevice driver. |
| MACRUM | 0:8eedb2495d52 | 31 | |
| MACRUM | 0:8eedb2495d52 | 32 | The SDCard driver is maintained in this repository as a component separate from the main mbed OS repository. |
| MACRUM | 0:8eedb2495d52 | 33 | Hence the 2 repositories (mbed-os and sd-driver) have to be used together |
| MACRUM | 0:8eedb2495d52 | 34 | to deliver the FAT32 Filesystem/SDCard support. This document explains how to do this. |
| MACRUM | 0:8eedb2495d52 | 35 | |
| MACRUM | 0:8eedb2495d52 | 36 | |
| MACRUM | 0:8eedb2495d52 | 37 | # Introduction |
| MACRUM | 0:8eedb2495d52 | 38 | |
| MACRUM | 0:8eedb2495d52 | 39 | ### Overview |
| MACRUM | 0:8eedb2495d52 | 40 | |
| MACRUM | 0:8eedb2495d52 | 41 | The scope of this document is to describe how applications use the FAT filesystem and sd-driver |
| MACRUM | 0:8eedb2495d52 | 42 | components to persistently store data on SDCards. The document is intended to help developers adopt the |
| MACRUM | 0:8eedb2495d52 | 43 | mbed OS POSIX File API support, and in particular to help explain: |
| MACRUM | 0:8eedb2495d52 | 44 | |
| MACRUM | 0:8eedb2495d52 | 45 | - How the software components work together to deliver the storage functionality. |
| MACRUM | 0:8eedb2495d52 | 46 | - How to work with the sd-driver and mbed OS to build the examples. The example code can easily |
| MACRUM | 0:8eedb2495d52 | 47 | be copied into your new application code. |
| MACRUM | 0:8eedb2495d52 | 48 | - How to work with the CI Test Shield, which adds an SDCard slot to those targets that do not have already have one. |
| MACRUM | 0:8eedb2495d52 | 49 | - How to run the POSIX File API mbed Greentea test cases, which provide further example code of how to use |
| MACRUM | 0:8eedb2495d52 | 50 | the POSIX File API. |
| MACRUM | 0:8eedb2495d52 | 51 | |
| MACRUM | 0:8eedb2495d52 | 52 | Section 1 provides an Executive Summary, describing the purpose of the sd-driver, the supporting |
| MACRUM | 0:8eedb2495d52 | 53 | software, examples, test cases and documentation. |
| MACRUM | 0:8eedb2495d52 | 54 | |
| MACRUM | 0:8eedb2495d52 | 55 | Section 2 provides an an overview of the material covered including descriptions of the major sections. |
| MACRUM | 0:8eedb2495d52 | 56 | |
| MACRUM | 0:8eedb2495d52 | 57 | Section 3 provides an overview of the mbed OS filesystem software components, |
| MACRUM | 0:8eedb2495d52 | 58 | including the inter-relationships between the application, POSIX file API, the standard c-library, |
| MACRUM | 0:8eedb2495d52 | 59 | the mbed OS filesystem and the SDCard driver (sd-driver). |
| MACRUM | 0:8eedb2495d52 | 60 | |
| MACRUM | 0:8eedb2495d52 | 61 | Section 4 describes how to build and run an example application for reading |
| MACRUM | 0:8eedb2495d52 | 62 | and writing data to an SDCard using the POSIX File API. The example begins by describing |
| MACRUM | 0:8eedb2495d52 | 63 | the procedure for building and testing on the K64F target. The final sub-sections |
| MACRUM | 0:8eedb2495d52 | 64 | describe how to use the test shield to add an SDCard slot to any mbed target, |
| MACRUM | 0:8eedb2495d52 | 65 | and hence enable the persistent storage of data on any supported target. |
| MACRUM | 0:8eedb2495d52 | 66 | |
| MACRUM | 0:8eedb2495d52 | 67 | Section 5 describes an example application which uses the raw |
| MACRUM | 0:8eedb2495d52 | 68 | BlockDevice API to read and write data to the SDCard. |
| MACRUM | 0:8eedb2495d52 | 69 | |
| MACRUM | 0:8eedb2495d52 | 70 | Section 6 describes how to build and run the SDCard POSIX File API mbed Greentea test cases. |
| MACRUM | 0:8eedb2495d52 | 71 | There are a number of functional test cases demonstrating how to use the |
| MACRUM | 0:8eedb2495d52 | 72 | mbed OS POSIX File API. |
| MACRUM | 0:8eedb2495d52 | 73 | |
| MACRUM | 0:8eedb2495d52 | 74 | Section 7 describes the POSIX File API and provides links to useful API documentation web pages. |
| MACRUM | 0:8eedb2495d52 | 75 | |
| MACRUM | 0:8eedb2495d52 | 76 | |
| MACRUM | 0:8eedb2495d52 | 77 | ### Known mbed-os and sd-driver Compatible Versions |
| MACRUM | 0:8eedb2495d52 | 78 | |
| MACRUM | 0:8eedb2495d52 | 79 | The following versions of the mbed-os and sd-driver repositories are known to work together: |
| MACRUM | 0:8eedb2495d52 | 80 | |
| MACRUM | 0:8eedb2495d52 | 81 | - {mbed-os, sd-driver} = {mbed-os-5.4.0-rc2, sd-driver-0.0.1-mbed-os-5.4.0-rc2}. |
| MACRUM | 0:8eedb2495d52 | 82 | `K64F`, `NUCLEO_F429ZI` and `UBLOX_EVK_ODIN_W2` fopen and basic filesystem tests working. |
| MACRUM | 0:8eedb2495d52 | 83 | - {mbed-os, sd-driver} = {mbed-os-5.4.0, sd-driver-0.0.2-mbed-os-5.4.0}. |
| MACRUM | 0:8eedb2495d52 | 84 | `K64F`, `NUCLEO_F429ZI` and `UBLOX_EVK_ODIN_W2` fopen and basic filesystem tests working. |
| MACRUM | 0:8eedb2495d52 | 85 | - {mbed-os, sd-driver} = {mbed-os-5.4.1, sd-driver-0.0.3-mbed-os-5.4.1}. |
| MACRUM | 0:8eedb2495d52 | 86 | - {mbed-os, sd-driver} = {mbed-os-5.5.1, sd-driver-0.1.0-mbed-os-5.5.1}. |
| MACRUM | 0:8eedb2495d52 | 87 | - {mbed-os, sd-driver} = {mbed-os-5.5.4, sd-driver-0.1.1-mbed-os-5.5.4}. |
| MACRUM | 0:8eedb2495d52 | 88 | - {mbed-os, sd-driver} = {mbed-os-5.6.1, sd-driver-0.1.2-mbed-os-5.6.1}. |
| MACRUM | 0:8eedb2495d52 | 89 | - {mbed-os, sd-driver} = {mbed-os-5.8.0, sd-driver-0.1.3-mbed-os-5.8.0}. |
| MACRUM | 0:8eedb2495d52 | 90 | |
| MACRUM | 0:8eedb2495d52 | 91 | To find the latest compatible versions, use the following command to see the messages attached to the tags |
| MACRUM | 0:8eedb2495d52 | 92 | in the sd-driver repository: |
| MACRUM | 0:8eedb2495d52 | 93 | |
| MACRUM | 0:8eedb2495d52 | 94 | ex_app7/$ cd sd-driver |
| MACRUM | 0:8eedb2495d52 | 95 | ex_app7/sd-driver$ git tag -n |
| MACRUM | 0:8eedb2495d52 | 96 | sd-driver-0.0.1-mbed-os-5.3.4 Version compatible with mbed-os-5.3.4, and private_mbedos_filesystems-0.0.1-mbed-os-5.3.4. |
| MACRUM | 0:8eedb2495d52 | 97 | sd-driver-0.0.2-mbed-os-5.4.0 Updated README.md to include worked exmaples and restructuring of information. |
| MACRUM | 0:8eedb2495d52 | 98 | sd-driver-0.0.3-mbed-os-5.4.1 Version compatible with mbed-os-5.4.1. |
| MACRUM | 0:8eedb2495d52 | 99 | sd-driver-0.1.1-mbed-os-5.5.4 Version compatible with mbed-os-5.5.4 |
| MACRUM | 0:8eedb2495d52 | 100 | sd-driver-0.1.2-mbed-os-5.6.1 Version compatible with mbed-os-5.6.1 |
| MACRUM | 0:8eedb2495d52 | 101 | sd-driver-0.1.3-mbed-os-5.8.0 Version compatible with mbed-os-5.8.0 |
| MACRUM | 0:8eedb2495d52 | 102 | |
| MACRUM | 0:8eedb2495d52 | 103 | ### Known Issues With This Document |
| MACRUM | 0:8eedb2495d52 | 104 | |
| MACRUM | 0:8eedb2495d52 | 105 | There are no known issues with this document. |
| MACRUM | 0:8eedb2495d52 | 106 | |
| MACRUM | 0:8eedb2495d52 | 107 | |
| MACRUM | 0:8eedb2495d52 | 108 | # Overview of mbed OS Filesystem Software Component Stack |
| MACRUM | 0:8eedb2495d52 | 109 | |
| MACRUM | 0:8eedb2495d52 | 110 | |
| MACRUM | 0:8eedb2495d52 | 111 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 112 | | | |
| MACRUM | 0:8eedb2495d52 | 113 | | Application | // This application uses the POSIX File API |
| MACRUM | 0:8eedb2495d52 | 114 | | | // to read/write data to persistent storage backends. |
| MACRUM | 0:8eedb2495d52 | 115 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 116 | |
| MACRUM | 0:8eedb2495d52 | 117 | ------------------------ // POSIX File API (ISO). |
| MACRUM | 0:8eedb2495d52 | 118 | |
| MACRUM | 0:8eedb2495d52 | 119 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 120 | | | |
| MACRUM | 0:8eedb2495d52 | 121 | | libc | // The standard c library implementation |
| MACRUM | 0:8eedb2495d52 | 122 | | | // e.g. newlib. |
| MACRUM | 0:8eedb2495d52 | 123 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 124 | |
| MACRUM | 0:8eedb2495d52 | 125 | ------------------------ // sys_xxx equivalent API. |
| MACRUM | 0:8eedb2495d52 | 126 | |
| MACRUM | 0:8eedb2495d52 | 127 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 128 | | | |
| MACRUM | 0:8eedb2495d52 | 129 | | mbed_retarget.cpp | // Target specific mapping layer. |
| MACRUM | 0:8eedb2495d52 | 130 | | | |
| MACRUM | 0:8eedb2495d52 | 131 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 132 | |
| MACRUM | 0:8eedb2495d52 | 133 | ------------------------ // Filesystem Upper Edge API. |
| MACRUM | 0:8eedb2495d52 | 134 | |
| MACRUM | 0:8eedb2495d52 | 135 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 136 | | | |
| MACRUM | 0:8eedb2495d52 | 137 | | File System | // File system wrappers and implementation. |
| MACRUM | 0:8eedb2495d52 | 138 | | | |
| MACRUM | 0:8eedb2495d52 | 139 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 140 | |
| MACRUM | 0:8eedb2495d52 | 141 | ------------------------ // FS Lower Edge API (Block Store Interface). |
| MACRUM | 0:8eedb2495d52 | 142 | |
| MACRUM | 0:8eedb2495d52 | 143 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 144 | | Block API | |
| MACRUM | 0:8eedb2495d52 | 145 | | Device Driver | // The SDCard driver, for example. |
| MACRUM | 0:8eedb2495d52 | 146 | | e.g. sd-driver | |
| MACRUM | 0:8eedb2495d52 | 147 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 148 | |
| MACRUM | 0:8eedb2495d52 | 149 | ------------------------ // SPI.h interface. |
| MACRUM | 0:8eedb2495d52 | 150 | |
| MACRUM | 0:8eedb2495d52 | 151 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 152 | | | |
| MACRUM | 0:8eedb2495d52 | 153 | | SPI | // SPI subsystem (C++ classes and C-HAL implementation). |
| MACRUM | 0:8eedb2495d52 | 154 | | | |
| MACRUM | 0:8eedb2495d52 | 155 | ------------------------ |
| MACRUM | 0:8eedb2495d52 | 156 | |
| MACRUM | 0:8eedb2495d52 | 157 | Figure 1. mbedOS generic architecture of filesystem software stack. |
| MACRUM | 0:8eedb2495d52 | 158 | |
| MACRUM | 0:8eedb2495d52 | 159 | The figure above shows the mbed OS software component stack used for data |
| MACRUM | 0:8eedb2495d52 | 160 | storage on SDCard: |
| MACRUM | 0:8eedb2495d52 | 161 | |
| MACRUM | 0:8eedb2495d52 | 162 | - At the top level is the application component which uses the standard POSIX File API |
| MACRUM | 0:8eedb2495d52 | 163 | to read and write application data to persistent storage. |
| MACRUM | 0:8eedb2495d52 | 164 | - The newlib standard library (libc) stdio.h interface (POSIX File API) |
| MACRUM | 0:8eedb2495d52 | 165 | implementation is used as it's optimised for resource limited embedded systems. |
| MACRUM | 0:8eedb2495d52 | 166 | - mbed_retarget.cpp implements the libc back-end file OS handlers and maps them |
| MACRUM | 0:8eedb2495d52 | 167 | to the FileSystem. |
| MACRUM | 0:8eedb2495d52 | 168 | - The File System code (hosted in mbed-os) is composed of 2 parts: |
| MACRUM | 0:8eedb2495d52 | 169 | - The mbed OS file system wrapper classes (e.g. FileSystem, File, FileBase classes) |
| MACRUM | 0:8eedb2495d52 | 170 | which are used to present a consistent API to the retarget module for different |
| MACRUM | 0:8eedb2495d52 | 171 | (third-party) file system implementations. |
| MACRUM | 0:8eedb2495d52 | 172 | - The FAT filesystem implementation code. |
| MACRUM | 0:8eedb2495d52 | 173 | The [FATFS: Generic FAT File System Module](http://elm-chan.org/fsw/ff/00index_e.html) |
| MACRUM | 0:8eedb2495d52 | 174 | (ChanFS) has been integrated within mbed-os. |
| MACRUM | 0:8eedb2495d52 | 175 | - The Block API Device Driver. The SDCard driver is an example of a persistent storage driver. |
| MACRUM | 0:8eedb2495d52 | 176 | It's maintained as a separate component from the mbed OS repository (in this repository). |
| MACRUM | 0:8eedb2495d52 | 177 | - The SPI module provides the mbed OS generic SPI API. This functionality is maintained in |
| MACRUM | 0:8eedb2495d52 | 178 | mbed OS. |
| MACRUM | 0:8eedb2495d52 | 179 | |
| MACRUM | 0:8eedb2495d52 | 180 | |
| MACRUM | 0:8eedb2495d52 | 181 | # SDCard POSIX File API Example App for Reading/Writing Data |
| MACRUM | 0:8eedb2495d52 | 182 | |
| MACRUM | 0:8eedb2495d52 | 183 | Refer to [SD driver Example](https://github.com/ARMmbed/mbed-os-example-sd-driver) |
| MACRUM | 0:8eedb2495d52 | 184 | |
| MACRUM | 0:8eedb2495d52 | 185 | |
| MACRUM | 0:8eedb2495d52 | 186 | ### <a name="testing-with-an-sdcard-on-target-xyx"></a> Testing with an SDCard on Target XYZ |
| MACRUM | 0:8eedb2495d52 | 187 | |
| MACRUM | 0:8eedb2495d52 | 188 | The standard way to test is with the mbed CI Test Shield plugged into the |
| MACRUM | 0:8eedb2495d52 | 189 | target board. This pin mapping for this configuration is parameterised in |
| MACRUM | 0:8eedb2495d52 | 190 | the `mbed_lib.json` file. |
| MACRUM | 0:8eedb2495d52 | 191 | |
| MACRUM | 0:8eedb2495d52 | 192 | The following is an example of the `mbed_lib.json` file available in the repository: |
| MACRUM | 0:8eedb2495d52 | 193 | |
| MACRUM | 0:8eedb2495d52 | 194 | { |
| MACRUM | 0:8eedb2495d52 | 195 | "config": { |
| MACRUM | 0:8eedb2495d52 | 196 | "SPI_CS": "NC", |
| MACRUM | 0:8eedb2495d52 | 197 | "SPI_MOSI": "NC", |
| MACRUM | 0:8eedb2495d52 | 198 | "SPI_MISO": "NC", |
| MACRUM | 0:8eedb2495d52 | 199 | "SPI_CLK": "NC", |
| MACRUM | 0:8eedb2495d52 | 200 | "DEVICE_SPI": 1, |
| MACRUM | 0:8eedb2495d52 | 201 | "FSFAT_SDCARD_INSTALLED": 1 |
| MACRUM | 0:8eedb2495d52 | 202 | }, |
| MACRUM | 0:8eedb2495d52 | 203 | "target_overrides": { |
| MACRUM | 0:8eedb2495d52 | 204 | "DISCO_F051R8": { |
| MACRUM | 0:8eedb2495d52 | 205 | "SPI_MOSI": "SPI_MOSI", |
| MACRUM | 0:8eedb2495d52 | 206 | "SPI_MISO": "SPI_MISO", |
| MACRUM | 0:8eedb2495d52 | 207 | "SPI_CLK": "SPI_SCK", |
| MACRUM | 0:8eedb2495d52 | 208 | "SPI_CS": "SPI_CS" |
| MACRUM | 0:8eedb2495d52 | 209 | }, |
| MACRUM | 0:8eedb2495d52 | 210 | "KL46Z": { |
| MACRUM | 0:8eedb2495d52 | 211 | "SPI_MOSI": "PTD6", |
| MACRUM | 0:8eedb2495d52 | 212 | "SPI_MISO": "PTD7", |
| MACRUM | 0:8eedb2495d52 | 213 | "SPI_CLK": "PTD5", |
| MACRUM | 0:8eedb2495d52 | 214 | "SPI_CS": "PTD4" |
| MACRUM | 0:8eedb2495d52 | 215 | }, |
| MACRUM | 0:8eedb2495d52 | 216 | "K64F": { |
| MACRUM | 0:8eedb2495d52 | 217 | "SPI_MOSI": "PTE3", |
| MACRUM | 0:8eedb2495d52 | 218 | "SPI_MISO": "PTE1", |
| MACRUM | 0:8eedb2495d52 | 219 | "SPI_CLK": "PTE2", |
| MACRUM | 0:8eedb2495d52 | 220 | "SPI_CS": "PTE4" |
| MACRUM | 0:8eedb2495d52 | 221 | } |
| MACRUM | 0:8eedb2495d52 | 222 | } |
| MACRUM | 0:8eedb2495d52 | 223 | |
| MACRUM | 0:8eedb2495d52 | 224 | Note the following things about the `mbed_lib.json` file: |
| MACRUM | 0:8eedb2495d52 | 225 | |
| MACRUM | 0:8eedb2495d52 | 226 | - The `mbed_lib.json` file is used to define target specific symbols for the SPI pins connecting the SDCard slot to the target MCU: |
| MACRUM | 0:8eedb2495d52 | 227 | - "SPI\_CS". This is the Chip Select line. |
| MACRUM | 0:8eedb2495d52 | 228 | - "SPI\_MOSI". This is the Master Out Slave In data line. |
| MACRUM | 0:8eedb2495d52 | 229 | - "SPI\_MISO". This is the Master In Slave Out data line. |
| MACRUM | 0:8eedb2495d52 | 230 | - "SPI\_CLK". This is the serial Clock line. |
| MACRUM | 0:8eedb2495d52 | 231 | - The default configuration defined in the "config" section **is not valid for any platform** (will error at runtime). |
| MACRUM | 0:8eedb2495d52 | 232 | The "config" section defines a dictionary mapping functional names to target board pins: |
| MACRUM | 0:8eedb2495d52 | 233 | - "SPI\_CS" causes the MBED\_CONF\_APP\_SPI\_CS symbol to be defined in mbed\_config.h, which is used in the filesystem test implementation. |
| MACRUM | 0:8eedb2495d52 | 234 | - "SPI\_MOSI" causes the MBED\_CONF\_APP\_SPI\_MOSI symbol to be defined in mbed\_config.h. |
| MACRUM | 0:8eedb2495d52 | 235 | - "SPI\_MISO" causes the MBED\_CONF\_APP\_SPI\_MISO symbol to be defined in mbed\_config.h. |
| MACRUM | 0:8eedb2495d52 | 236 | - "SPI\_CLK" causes the MBED\_CONF\_APP\_SPI\_CLK symbol to be defined in mbed\_config.h. |
| MACRUM | 0:8eedb2495d52 | 237 | - The `"target_overrides"` section is used to override the "SPI\_xxx" symbols for specific target boards, which may have an SDCard slot, for example. |
| MACRUM | 0:8eedb2495d52 | 238 | This is the case for the K64F, where the "SPI\_xxx" are mapped to the pin names for the on-board SDCard. |
| MACRUM | 0:8eedb2495d52 | 239 | |
| MACRUM | 0:8eedb2495d52 | 240 | ``` |
| MACRUM | 0:8eedb2495d52 | 241 | "K64F": { |
| MACRUM | 0:8eedb2495d52 | 242 | "SPI_MOSI": "PTE3", |
| MACRUM | 0:8eedb2495d52 | 243 | "SPI_MISO": "PTE1", |
| MACRUM | 0:8eedb2495d52 | 244 | "SPI_CLK": "PTE2", |
| MACRUM | 0:8eedb2495d52 | 245 | "SPI_CS": "PTE4" |
| MACRUM | 0:8eedb2495d52 | 246 | } |
| MACRUM | 0:8eedb2495d52 | 247 | ``` |
| MACRUM | 0:8eedb2495d52 | 248 | - Thus, in the absence of any target specific definitions in the `"target_overrides"` section, all boards will default to |
| MACRUM | 0:8eedb2495d52 | 249 | using the invalid configuration (will error at runtime). For those platforms with a `"target_overrides"` section then this configuration |
| MACRUM | 0:8eedb2495d52 | 250 | will be used in preference. |
| MACRUM | 0:8eedb2495d52 | 251 | - Hence in the case that you want to test a platform with an SDCard inserted into a |
| MACRUM | 0:8eedb2495d52 | 252 | fitted CI test shield (rather than the on-board SDCard slot) |
| MACRUM | 0:8eedb2495d52 | 253 | and there is a `"target_overrides"` section present in the `mbed_lib.json` file, you must provide the correct Arduino pins in the `"target_overrides"` |
| MACRUM | 0:8eedb2495d52 | 254 | section before building. This will result in the default configuration being used (suitable for the CI |
| MACRUM | 0:8eedb2495d52 | 255 | Test Shield). The correct pins for the CI test shield are as follows: |
| MACRUM | 0:8eedb2495d52 | 256 | "<your platform name>": { |
| MACRUM | 0:8eedb2495d52 | 257 | "SPI_MOSI": "D11", |
| MACRUM | 0:8eedb2495d52 | 258 | "SPI_MISO": "D12", |
| MACRUM | 0:8eedb2495d52 | 259 | "SPI_CLK": "D13", |
| MACRUM | 0:8eedb2495d52 | 260 | "SPI_CS": "D10" |
| MACRUM | 0:8eedb2495d52 | 261 | } |
| MACRUM | 0:8eedb2495d52 | 262 | - Note when inserting the v1.0.0 CI Test Shield into the Arduino header of the target platform, the shield pins D0 and |
| MACRUM | 0:8eedb2495d52 | 263 | D1 should be bent to be parallel to the shield PCB so they are not inserted into the Arduino header. This is because |
| MACRUM | 0:8eedb2495d52 | 264 | some boards use the same UART on DAPLINK and D0/D1, which means the serial debug channel breaks and hence the mbed greentea |
| MACRUM | 0:8eedb2495d52 | 265 | test suite will not work correctly. This is mainly on older ST boards and should not be a problem on |
| MACRUM | 0:8eedb2495d52 | 266 | `K64F`, `NUCLEO_F429ZI` and `UBLOX_EVK_ODIN_W2`. Note also that the v2.0.0 CI Test Shield doesn't suffer from this |
| MACRUM | 0:8eedb2495d52 | 267 | problem and the pins don't need to be bent. |
| MACRUM | 0:8eedb2495d52 | 268 | - When inserting the SDCard into the card slot on the CI test shield, make sure the card is fully inserted. |
| MACRUM | 0:8eedb2495d52 | 269 | On insertion, there should be a small clicking sound when the card registers, and the back edge of the card |
| MACRUM | 0:8eedb2495d52 | 270 | should protrude no more than ~1mm over the edge of the CI test shield PCB. If the SDCard fails to register, |
| MACRUM | 0:8eedb2495d52 | 271 | try gently pushing the metal flexible strip in the shape of a spade at the top edge of the SDCard metal slot |
| MACRUM | 0:8eedb2495d52 | 272 | casing with a pair of tweezers, bending it a little to lower it into the slot casing. This helps with the |
| MACRUM | 0:8eedb2495d52 | 273 | insertion mechanism. |
| MACRUM | 0:8eedb2495d52 | 274 | |
| MACRUM | 0:8eedb2495d52 | 275 | ### Wiring instructions for target NUCLEO_F429ZI with CI Test Shield |
| MACRUM | 0:8eedb2495d52 | 276 |  |
| MACRUM | 0:8eedb2495d52 | 277 | |
| MACRUM | 0:8eedb2495d52 | 278 | **Figure 3. The figure shows how to connect the NUCLEO_F429ZI platform with the CI shield.** |
| MACRUM | 0:8eedb2495d52 | 279 | |
| MACRUM | 0:8eedb2495d52 | 280 | The above figure shows how to connect the NUCLEO_F429ZI with the v1.0.0 CI test shield. Note: |
| MACRUM | 0:8eedb2495d52 | 281 | |
| MACRUM | 0:8eedb2495d52 | 282 | - To get the SD Card to work with this platform the CI test shield cannot be connected directly to this board, instead follow the instructions above. |
| MACRUM | 0:8eedb2495d52 | 283 | - Any SD-card adapter will work as long as you connect all the relevant pins (MOSI, MISO, SCLK, CS, 3.3V and GND) as illustrated in figure 3. |
| MACRUM | 0:8eedb2495d52 | 284 | - The SDCard is fully inserted into the slot and overhangs the PCB by ~1mm. |
| MACRUM | 0:8eedb2495d52 | 285 | |
| MACRUM | 0:8eedb2495d52 | 286 | # SDBlockDevice Example Application |
| MACRUM | 0:8eedb2495d52 | 287 | |
| MACRUM | 0:8eedb2495d52 | 288 | The following sample code illustrates how to use the sd-driver Block Device API: |
| MACRUM | 0:8eedb2495d52 | 289 | |
| MACRUM | 0:8eedb2495d52 | 290 | ``` cpp |
| MACRUM | 0:8eedb2495d52 | 291 | #include "mbed.h" |
| MACRUM | 0:8eedb2495d52 | 292 | #include "SDBlockDevice.h" |
| MACRUM | 0:8eedb2495d52 | 293 | |
| MACRUM | 0:8eedb2495d52 | 294 | // Instantiate the SDBlockDevice by specifying the SPI pins connected to the SDCard |
| MACRUM | 0:8eedb2495d52 | 295 | // socket. The PINS are: |
| MACRUM | 0:8eedb2495d52 | 296 | // MOSI (Master Out Slave In) |
| MACRUM | 0:8eedb2495d52 | 297 | // MISO (Master In Slave Out) |
| MACRUM | 0:8eedb2495d52 | 298 | // SCLK (Serial Clock) |
| MACRUM | 0:8eedb2495d52 | 299 | // CS (Chip Select) |
| MACRUM | 0:8eedb2495d52 | 300 | SDBlockDevice sd(MBED_CONF_SD_SPI_MOSI, MBED_CONF_SD_SPI_MISO, MBED_CONF_SD_SPI_CLK, MBED_CONF_SD_SPI_CS); |
| MACRUM | 0:8eedb2495d52 | 301 | uint8_t block[512] = "Hello World!\n"; |
| MACRUM | 0:8eedb2495d52 | 302 | |
| MACRUM | 0:8eedb2495d52 | 303 | int main() |
| MACRUM | 0:8eedb2495d52 | 304 | { |
| MACRUM | 0:8eedb2495d52 | 305 | // call the SDBlockDevice instance initialisation method. |
| MACRUM | 0:8eedb2495d52 | 306 | if ( 0 != sd.init()) { |
| MACRUM | 0:8eedb2495d52 | 307 | printf("Init failed \n"); |
| MACRUM | 0:8eedb2495d52 | 308 | return -1; |
| MACRUM | 0:8eedb2495d52 | 309 | } |
| MACRUM | 0:8eedb2495d52 | 310 | printf("sd size: %llu\n", sd.size()); |
| MACRUM | 0:8eedb2495d52 | 311 | printf("sd read size: %llu\n", sd.get_read_size()); |
| MACRUM | 0:8eedb2495d52 | 312 | printf("sd program size: %llu\n", sd.get_program_size()); |
| MACRUM | 0:8eedb2495d52 | 313 | printf("sd erase size: %llu\n", sd.get_erase_size()); |
| MACRUM | 0:8eedb2495d52 | 314 | |
| MACRUM | 0:8eedb2495d52 | 315 | // set the frequency |
| MACRUM | 0:8eedb2495d52 | 316 | if ( 0 != sd.frequency(5000000)) { |
| MACRUM | 0:8eedb2495d52 | 317 | printf("Error setting frequency \n"); |
| MACRUM | 0:8eedb2495d52 | 318 | } |
| MACRUM | 0:8eedb2495d52 | 319 | |
| MACRUM | 0:8eedb2495d52 | 320 | if ( 0 != sd.erase(0, sd.get_erase_size())) { |
| MACRUM | 0:8eedb2495d52 | 321 | printf("Error Erasing block \n"); |
| MACRUM | 0:8eedb2495d52 | 322 | } |
| MACRUM | 0:8eedb2495d52 | 323 | |
| MACRUM | 0:8eedb2495d52 | 324 | // Write some the data block to the device |
| MACRUM | 0:8eedb2495d52 | 325 | if ( 0 == sd.program(block, 0, 512)) { |
| MACRUM | 0:8eedb2495d52 | 326 | // read the data block from the device |
| MACRUM | 0:8eedb2495d52 | 327 | if ( 0 == sd.read(block, 0, 512)) { |
| MACRUM | 0:8eedb2495d52 | 328 | // print the contents of the block |
| MACRUM | 0:8eedb2495d52 | 329 | printf("%s", block); |
| MACRUM | 0:8eedb2495d52 | 330 | } |
| MACRUM | 0:8eedb2495d52 | 331 | } |
| MACRUM | 0:8eedb2495d52 | 332 | |
| MACRUM | 0:8eedb2495d52 | 333 | // call the SDBlockDevice instance de-initialisation method. |
| MACRUM | 0:8eedb2495d52 | 334 | sd.deinit(); |
| MACRUM | 0:8eedb2495d52 | 335 | } |
| MACRUM | 0:8eedb2495d52 | 336 | ``` |
| MACRUM | 0:8eedb2495d52 | 337 | |
| MACRUM | 0:8eedb2495d52 | 338 | # SDCard POSIX File API mbed Greentea Test Cases |
| MACRUM | 0:8eedb2495d52 | 339 | |
| MACRUM | 0:8eedb2495d52 | 340 | This section describes how to build and run the POSIX file API test cases. |
| MACRUM | 0:8eedb2495d52 | 341 | The following steps are covered: |
| MACRUM | 0:8eedb2495d52 | 342 | |
| MACRUM | 0:8eedb2495d52 | 343 | - [Create the FAT/SDCard Application Project](#create-fat-sdcard-application-project). |
| MACRUM | 0:8eedb2495d52 | 344 | This section describes how to git clone the mbed OS and sd-driver repositories containing the |
| MACRUM | 0:8eedb2495d52 | 345 | code and test cases of interest. |
| MACRUM | 0:8eedb2495d52 | 346 | - [Build the mbed OS Test Cases](#build-the-mbedos-test-cases). This section |
| MACRUM | 0:8eedb2495d52 | 347 | describes how to build the mbed OS test cases. |
| MACRUM | 0:8eedb2495d52 | 348 | - [Insert a microSD Card Into the K64F for Greentea Testing](#greentea-insert-sdcard-into-k64f).This section |
| MACRUM | 0:8eedb2495d52 | 349 | describes how to format (if required) a microSD card prior to running the tests. |
| MACRUM | 0:8eedb2495d52 | 350 | - [Run the POSIX File Test Case](#run-the-posix-file-test-cases).This section |
| MACRUM | 0:8eedb2495d52 | 351 | describes how to run the POSIX file test cases. |
| MACRUM | 0:8eedb2495d52 | 352 | |
| MACRUM | 0:8eedb2495d52 | 353 | |
| MACRUM | 0:8eedb2495d52 | 354 | ### <a name="create-fat-sdcard-application-project"></a> Create the FAT/SDCard Application Project |
| MACRUM | 0:8eedb2495d52 | 355 | |
| MACRUM | 0:8eedb2495d52 | 356 | This section describes how to create an application project combining the mbed-os and |
| MACRUM | 0:8eedb2495d52 | 357 | sd-driver repositories into a single project. |
| MACRUM | 0:8eedb2495d52 | 358 | In summary the following steps will be covered in this section: |
| MACRUM | 0:8eedb2495d52 | 359 | |
| MACRUM | 0:8eedb2495d52 | 360 | - A top level application project directory is created. The directory name is ex_app1. |
| MACRUM | 0:8eedb2495d52 | 361 | - In the ex_app1 directory, the mbed-os repository is cloned. |
| MACRUM | 0:8eedb2495d52 | 362 | - In the ex_app1 directory at the same level as the mbed-os directory, the sd-driver repository is cloned. |
| MACRUM | 0:8eedb2495d52 | 363 | - The `mbed_lib.json` file is copied from the `sd-driver/config/mbed_lib.json` to the ex_app1 directory. |
| MACRUM | 0:8eedb2495d52 | 364 | |
| MACRUM | 0:8eedb2495d52 | 365 | First create the top level application directory ex_app1 and move into it: |
| MACRUM | 0:8eedb2495d52 | 366 | |
| MACRUM | 0:8eedb2495d52 | 367 | shell:/d/demo_area$ mkdir ex_app1 |
| MACRUM | 0:8eedb2495d52 | 368 | shell:/d/demo_area$ pushd ex_app1 |
| MACRUM | 0:8eedb2495d52 | 369 | |
| MACRUM | 0:8eedb2495d52 | 370 | Next, get a clone of public mbed OS repository in the following way: |
| MACRUM | 0:8eedb2495d52 | 371 | |
| MACRUM | 0:8eedb2495d52 | 372 | shell:/d/demo_area/ex_app1$ git clone git@github.com:/armmbed/mbed-os |
| MACRUM | 0:8eedb2495d52 | 373 | <trace removed> |
| MACRUM | 0:8eedb2495d52 | 374 | shell:/d/demo_area/ex_app1$ |
| MACRUM | 0:8eedb2495d52 | 375 | |
| MACRUM | 0:8eedb2495d52 | 376 | Next, get a clone of the sd-driver repository: |
| MACRUM | 0:8eedb2495d52 | 377 | |
| MACRUM | 0:8eedb2495d52 | 378 | shell:/d/demo_area/ex_app1$ git clone git@github.com:/armmbed/sd-driver |
| MACRUM | 0:8eedb2495d52 | 379 | <trace removed> |
| MACRUM | 0:8eedb2495d52 | 380 | shell:/d/demo_area/ex_app1$ |
| MACRUM | 0:8eedb2495d52 | 381 | |
| MACRUM | 0:8eedb2495d52 | 382 | Note: The `mbed_lib.json` file specifies the SPI bus pin configuration for different targets, |
| MACRUM | 0:8eedb2495d52 | 383 | and is discussed in the [Testing with an SDCard on Target XYZ](#testing-with-an-sdcard-on-target-xyx) section. |
| MACRUM | 0:8eedb2495d52 | 384 | |
| MACRUM | 0:8eedb2495d52 | 385 | ### <a name="build-the-mbedos-test-cases"></a> Build the mbed OS Test Cases |
| MACRUM | 0:8eedb2495d52 | 386 | |
| MACRUM | 0:8eedb2495d52 | 387 | Build the test cases for the K64F target using the following command: |
| MACRUM | 0:8eedb2495d52 | 388 | |
| MACRUM | 0:8eedb2495d52 | 389 | shell:/d/demo_area/ex_app1$ mbed -v test --compile -t GCC_ARM -m K64F |
| MACRUM | 0:8eedb2495d52 | 390 | <trace removed> |
| MACRUM | 0:8eedb2495d52 | 391 | shell:/d/demo_area/ex_app1$ |
| MACRUM | 0:8eedb2495d52 | 392 | |
| MACRUM | 0:8eedb2495d52 | 393 | The build trace is quite extensive but on a successful build you should see the following output at the end of the log: |
| MACRUM | 0:8eedb2495d52 | 394 | |
| MACRUM | 0:8eedb2495d52 | 395 | Build successes: |
| MACRUM | 0:8eedb2495d52 | 396 | * K64F::GCC_ARM::MBED-BUILD |
| MACRUM | 0:8eedb2495d52 | 397 | * K64F::GCC_ARM::MBED-OS-FEATURES-FEATURE_LWIP-TESTS-MBEDMICRO-NET-CONNECTIVITY |
| MACRUM | 0:8eedb2495d52 | 398 | <trace removed> |
| MACRUM | 0:8eedb2495d52 | 399 | * K64F::GCC_ARM::MBED-OS-FEATURES-TESTS-FILESYSTEM-FAT_FILE_SYSTEM |
| MACRUM | 0:8eedb2495d52 | 400 | * K64F::GCC_ARM::MBED-OS-FEATURES-TESTS-FILESYSTEM-HEAP_BLOCK_DEVICE |
| MACRUM | 0:8eedb2495d52 | 401 | * K64F::GCC_ARM::MBED-OS-FEATURES-TESTS-FILESYSTEM-UTIL_BLOCK_DEVICE |
| MACRUM | 0:8eedb2495d52 | 402 | <trace removed> |
| MACRUM | 0:8eedb2495d52 | 403 | * K64F::GCC_ARM::SD-DRIVER-TESTS-BLOCK_DEVICE-BASIC |
| MACRUM | 0:8eedb2495d52 | 404 | * K64F::GCC_ARM::SD-DRIVER-TESTS-FILESYSTEM-BASIC |
| MACRUM | 0:8eedb2495d52 | 405 | * K64F::GCC_ARM::SD-DRIVER-TESTS-FILESYSTEM-DIRS |
| MACRUM | 0:8eedb2495d52 | 406 | * K64F::GCC_ARM::SD-DRIVER-TESTS-FILESYSTEM-FILES |
| MACRUM | 0:8eedb2495d52 | 407 | * K64F::GCC_ARM::SD-DRIVER-TESTS-FILESYSTEM-FOPEN |
| MACRUM | 0:8eedb2495d52 | 408 | * K64F::GCC_ARM::SD-DRIVER-TESTS-FILESYSTEM-PARALLEL |
| MACRUM | 0:8eedb2495d52 | 409 | * K64F::GCC_ARM::SD-DRIVER-TESTS-FILESYSTEM-SEEK |
| MACRUM | 0:8eedb2495d52 | 410 | |
| MACRUM | 0:8eedb2495d52 | 411 | Build skips: |
| MACRUM | 0:8eedb2495d52 | 412 | * K64F::GCC_ARM::MBED-OS-FEATURES-FEATURE_LWIP-TESTS-MBEDMICRO-NET-TCP_PACKET_PRESSURE |
| MACRUM | 0:8eedb2495d52 | 413 | <trace removed> |
| MACRUM | 0:8eedb2495d52 | 414 | |
| MACRUM | 0:8eedb2495d52 | 415 | |
| MACRUM | 0:8eedb2495d52 | 416 | Notice the following tests in the sd-driver tree are listed above: |
| MACRUM | 0:8eedb2495d52 | 417 | |
| MACRUM | 0:8eedb2495d52 | 418 | - `SD-DRIVER-TESTS-BLOCK_DEVICE-BASIC` |
| MACRUM | 0:8eedb2495d52 | 419 | - `SD-DRIVER-TESTS-FILESYSTEM-BASIC` |
| MACRUM | 0:8eedb2495d52 | 420 | - `SD-DRIVER-TESTS-FILESYSTEM-DIRS` |
| MACRUM | 0:8eedb2495d52 | 421 | - `SD-DRIVER-TESTS-FILESYSTEM-FILES` |
| MACRUM | 0:8eedb2495d52 | 422 | - `SD-DRIVER-TESTS-FILESYSTEM-FOPEN` |
| MACRUM | 0:8eedb2495d52 | 423 | - `SD-DRIVER-TESTS-FILESYSTEM-PARALLEL` |
| MACRUM | 0:8eedb2495d52 | 424 | - `SD-DRIVER-TESTS-FILESYSTEM-SEEK` |
| MACRUM | 0:8eedb2495d52 | 425 | |
| MACRUM | 0:8eedb2495d52 | 426 | The FAT32/SDCard test cases are at following locations in the source code tree: |
| MACRUM | 0:8eedb2495d52 | 427 | |
| MACRUM | 0:8eedb2495d52 | 428 | /d/demo_area/ex_app1/sd-driver/TESTS/filesystem/basic/basic.cpp |
| MACRUM | 0:8eedb2495d52 | 429 | /d/demo_area/ex_app1/sd-driver/TESTS/filesystem/fopen/fopen.cpp |
| MACRUM | 0:8eedb2495d52 | 430 | /d/demo_area/ex_app1/sd-driver/TESTS/block_device/basic/basic.cpp |
| MACRUM | 0:8eedb2495d52 | 431 | /d/demo_area/ex_app1/sd-driver/TESTS/filesystem/dirs/main.cpp |
| MACRUM | 0:8eedb2495d52 | 432 | /d/demo_area/ex_app1/sd-driver/TESTS/filesystem/files/main.cpp |
| MACRUM | 0:8eedb2495d52 | 433 | /d/demo_area/ex_app1/sd-driver/TESTS/filesystem/parallel/main.cpp |
| MACRUM | 0:8eedb2495d52 | 434 | /d/demo_area/ex_app1/sd-driver/TESTS/filesystem/seek/main.cpp |
| MACRUM | 0:8eedb2495d52 | 435 | |
| MACRUM | 0:8eedb2495d52 | 436 | #### <a name="settting-repos-to-compatible-versions"></a> Setting mbed-os/sd-driver Repositories To Compatible Versions |
| MACRUM | 0:8eedb2495d52 | 437 | |
| MACRUM | 0:8eedb2495d52 | 438 | The sd-driver master HEAD and the mbed-os master HEAD should be compatible |
| MACRUM | 0:8eedb2495d52 | 439 | with one another and therefore no specific tagged versions need to be checked out. |
| MACRUM | 0:8eedb2495d52 | 440 | However, in the case that you experience problems building, checkout out the compatible |
| MACRUM | 0:8eedb2495d52 | 441 | tagged version of each repository, as shown below: |
| MACRUM | 0:8eedb2495d52 | 442 | |
| MACRUM | 0:8eedb2495d52 | 443 | shell:/d/demo_area/ex_app1$ pushd mbed-os |
| MACRUM | 0:8eedb2495d52 | 444 | shell:/d/demo_area/ex_app1$ git checkout tags/mbed-os-5.4.0 |
| MACRUM | 0:8eedb2495d52 | 445 | shell:/d/demo_area/ex_app1$ popd |
| MACRUM | 0:8eedb2495d52 | 446 | shell:/d/demo_area/ex_app1$ pushd sd-driver |
| MACRUM | 0:8eedb2495d52 | 447 | shell:/d/demo_area/ex_app1$ git checkout tags/sd-driver-0.0.2-mbed-os-5.4.0 |
| MACRUM | 0:8eedb2495d52 | 448 | shell:/d/demo_area/ex_app1$ popd |
| MACRUM | 0:8eedb2495d52 | 449 | |
| MACRUM | 0:8eedb2495d52 | 450 | In the above: |
| MACRUM | 0:8eedb2495d52 | 451 | |
| MACRUM | 0:8eedb2495d52 | 452 | - `mbed-os-5.4.0` should be replaced with the latest mbed-os release tag. |
| MACRUM | 0:8eedb2495d52 | 453 | - For an mbed-os release tag `mbed-os-x.y.z`, use the equivalent sd-driver tag `sd-driver-a.b.c-mbed-os-x.y.z` |
| MACRUM | 0:8eedb2495d52 | 454 | where `a.b.c` is the latest version code for the `mbed-os-x.y.z` tag. |
| MACRUM | 0:8eedb2495d52 | 455 | |
| MACRUM | 0:8eedb2495d52 | 456 | ### <a name="greentea-insert-sdcard-into-k64f"></a> Insert SDCard into K64F for Greentea Testing |
| MACRUM | 0:8eedb2495d52 | 457 | |
| MACRUM | 0:8eedb2495d52 | 458 | See the previous section for [Insert SDCard into K64F](#insert-sdcard-into-k64f) for details. |
| MACRUM | 0:8eedb2495d52 | 459 | |
| MACRUM | 0:8eedb2495d52 | 460 | |
| MACRUM | 0:8eedb2495d52 | 461 | ### <a name="run-the-posix-file-test-cases"></a> Run the POSIX File Test Case |
| MACRUM | 0:8eedb2495d52 | 462 | |
| MACRUM | 0:8eedb2495d52 | 463 | To setup for running the test cases, connect the K64F development board to your |
| MACRUM | 0:8eedb2495d52 | 464 | PC using a suitable USB cable. |
| MACRUM | 0:8eedb2495d52 | 465 | |
| MACRUM | 0:8eedb2495d52 | 466 | All tests can be run using the following command: |
| MACRUM | 0:8eedb2495d52 | 467 | |
| MACRUM | 0:8eedb2495d52 | 468 | shell:/d/demo_area/ex_app1$ mbedgt -VS |
| MACRUM | 0:8eedb2495d52 | 469 | <trace removed> |
| MACRUM | 0:8eedb2495d52 | 470 | |
| MACRUM | 0:8eedb2495d52 | 471 | However, it's possible to run a particular test case using the following form of the mbedgt command: |
| MACRUM | 0:8eedb2495d52 | 472 | |
| MACRUM | 0:8eedb2495d52 | 473 | shell:/d/demo_area/ex_app1$ mbedgt -VS --test-by-names=<test-name> |
| MACRUM | 0:8eedb2495d52 | 474 | |
| MACRUM | 0:8eedb2495d52 | 475 | The names of the tests can be listed using: |
| MACRUM | 0:8eedb2495d52 | 476 | |
| MACRUM | 0:8eedb2495d52 | 477 | shell:/d/demo_area/ex_app1$ mbedgt -VS --list |
| MACRUM | 0:8eedb2495d52 | 478 | |
| MACRUM | 0:8eedb2495d52 | 479 | For example, to run the basic test use: |
| MACRUM | 0:8eedb2495d52 | 480 | |
| MACRUM | 0:8eedb2495d52 | 481 | shell:/d/demo_area/ex_app1$ mbedgt -VS --test-by-names=sd-driver-tests-filesystem-basic |
| MACRUM | 0:8eedb2495d52 | 482 | |
| MACRUM | 0:8eedb2495d52 | 483 | To run the fopen test use: |
| MACRUM | 0:8eedb2495d52 | 484 | |
| MACRUM | 0:8eedb2495d52 | 485 | shell:/d/demo_area/ex_app1$ mbedgt -VS --test-by-names=sd-driver-tests-filesystem-fopen |
| MACRUM | 0:8eedb2495d52 | 486 | |
| MACRUM | 0:8eedb2495d52 | 487 | On a successful run, results similar to the following will be shown: |
| MACRUM | 0:8eedb2495d52 | 488 | |
| MACRUM | 0:8eedb2495d52 | 489 | mbedgt: test suite report: |
| MACRUM | 0:8eedb2495d52 | 490 | +--------------+---------------+-------------------------------------------+--------+--------------------+-------------+ |
| MACRUM | 0:8eedb2495d52 | 491 | | target | platform_name | test suite | result | elapsed_time (sec) | copy_method | |
| MACRUM | 0:8eedb2495d52 | 492 | +--------------+---------------+-------------------------------------------+--------+--------------------+-------------+ |
| MACRUM | 0:8eedb2495d52 | 493 | | K64F-GCC_ARM | K64F | sd-driver-features-tests-filesystem-fopen | OK | 151.46 | shell | |
| MACRUM | 0:8eedb2495d52 | 494 | +--------------+---------------+-------------------------------------------+--------+--------------------+-------------+ |
| MACRUM | 0:8eedb2495d52 | 495 | mbedgt: test suite results: 1 OK |
| MACRUM | 0:8eedb2495d52 | 496 | mbedgt: test case report: |
| MACRUM | 0:8eedb2495d52 | 497 | +--------------+---------------+------------------------------------+----------------------------------------------------------------------------------------+--------+--------+--------+--------------------+ |
| MACRUM | 0:8eedb2495d52 | 498 | | target | platform_name | test suite | test case | passed | failed | result | elapsed_time (sec) | |
| MACRUM | 0:8eedb2495d52 | 499 | +--------------+---------------+------------------------------------+----------------------------------------------------------------------------------------+--------+--------+--------+--------------------+ |
| MACRUM | 0:8eedb2495d52 | 500 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_01: fopen()/fwrite()/fclose() directories/file in multi-dir filepath. | 1 | 0 | OK | 7.57 | |
| MACRUM | 0:8eedb2495d52 | 501 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_02: fopen(r) pre-existing file try to write it. | 1 | 0 | OK | 0.2 | |
| MACRUM | 0:8eedb2495d52 | 502 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_03: fopen(w+) pre-existing file try to write it. | 1 | 0 | OK | 0.41 | |
| MACRUM | 0:8eedb2495d52 | 503 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_04: fopen() with a filename exceeding the maximum length. | 1 | 0 | OK | 0.11 | |
| MACRUM | 0:8eedb2495d52 | 504 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_06: fopen() with bad filenames (minimal). | 1 | 0 | OK | 0.1 | |
| MACRUM | 0:8eedb2495d52 | 505 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_07: fopen()/errno handling. | 1 | 0 | OK | 0.07 | |
| MACRUM | 0:8eedb2495d52 | 506 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_08: ferror()/clearerr()/errno handling. | 1 | 0 | OK | 0.1 | |
| MACRUM | 0:8eedb2495d52 | 507 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_09: ftell() handling. | 1 | 0 | OK | 0.17 | |
| MACRUM | 0:8eedb2495d52 | 508 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_10: remove() test. | 1 | 0 | OK | 1.28 | |
| MACRUM | 0:8eedb2495d52 | 509 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_11: rename(). | 1 | 0 | OK | 2.3 | |
| MACRUM | 0:8eedb2495d52 | 510 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_12: opendir(), readdir(), closedir() test. | 1 | 0 | OK | 3.57 | |
| MACRUM | 0:8eedb2495d52 | 511 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_13: mkdir() test. | 1 | 0 | OK | 1.21 | |
| MACRUM | 0:8eedb2495d52 | 512 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_14: stat() test. | 1 | 0 | OK | 1.47 | |
| MACRUM | 0:8eedb2495d52 | 513 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_15: format() test. | 1 | 0 | OK | 26.12 | |
| MACRUM | 0:8eedb2495d52 | 514 | | K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_16: write/check n x 25kB data files. | 1 | 0 | OK | 87.11 | |
| MACRUM | 0:8eedb2495d52 | 515 | +--------------+---------------+------------------------------------+----------------------------------------------------------------------------------------+--------+--------+--------+--------------------+ |
| MACRUM | 0:8eedb2495d52 | 516 | mbedgt: test case results: 15 OK |
| MACRUM | 0:8eedb2495d52 | 517 | mbedgt: completed in 152.35 sec |
| MACRUM | 0:8eedb2495d52 | 518 | |
| MACRUM | 0:8eedb2495d52 | 519 | |
| MACRUM | 0:8eedb2495d52 | 520 | # <a name="summary-posix-api-documentation"></a> Summary of POSIX File API Documentation |
| MACRUM | 0:8eedb2495d52 | 521 | |
| MACRUM | 0:8eedb2495d52 | 522 | ### POSIX File API |
| MACRUM | 0:8eedb2495d52 | 523 | |
| MACRUM | 0:8eedb2495d52 | 524 | mbed OS supports a subset of the POSIX File API, as outlined below: |
| MACRUM | 0:8eedb2495d52 | 525 | |
| MACRUM | 0:8eedb2495d52 | 526 | - [clearerr()](https://linux.die.net/man/3/clearerr). |
| MACRUM | 0:8eedb2495d52 | 527 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 528 | - [fclose()](https://linux.die.net/man/3/fclose). |
| MACRUM | 0:8eedb2495d52 | 529 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 530 | - [ferror()](https://linux.die.net/man/3/clearerr). |
| MACRUM | 0:8eedb2495d52 | 531 | - STATUS: Basic testing implemented. |
| MACRUM | 0:8eedb2495d52 | 532 | - STATUS: GCC_ARM: Working. |
| MACRUM | 0:8eedb2495d52 | 533 | - STATUS: ARMCC: ARMCC has problem with ferror(filep) where filep is NULL. Appears to work for non-NULL pointer. |
| MACRUM | 0:8eedb2495d52 | 534 | - [fgetc()](https://linux.die.net/man/3/fgets). |
| MACRUM | 0:8eedb2495d52 | 535 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 536 | - [fgets()](https://linux.die.net/man/3/fgets). |
| MACRUM | 0:8eedb2495d52 | 537 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 538 | - [fputc()](https://linux.die.net/man/3/fputs). |
| MACRUM | 0:8eedb2495d52 | 539 | - STATUS: Unknown. |
| MACRUM | 0:8eedb2495d52 | 540 | - [fputs()](https://linux.die.net/man/3/fputs). |
| MACRUM | 0:8eedb2495d52 | 541 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 542 | - [fprintf()](https://linux.die.net/man/3/fprintf). |
| MACRUM | 0:8eedb2495d52 | 543 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 544 | - [fopen()](https://linux.die.net/man/3/fopen). |
| MACRUM | 0:8eedb2495d52 | 545 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 546 | - [freopen()](https://linux.die.net/man/3/fopen). |
| MACRUM | 0:8eedb2495d52 | 547 | - STATUS: This is not tested. |
| MACRUM | 0:8eedb2495d52 | 548 | - [fread()](https://linux.die.net/man/3/fread). |
| MACRUM | 0:8eedb2495d52 | 549 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 550 | - STATUS: n x 25kB stress test working. |
| MACRUM | 0:8eedb2495d52 | 551 | - [ftell()](https://linux.die.net/man/3/ftell). |
| MACRUM | 0:8eedb2495d52 | 552 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 553 | - [fwrite()](https://linux.die.net/man/3/fwrite). |
| MACRUM | 0:8eedb2495d52 | 554 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 555 | - STATUS: n x 25kB stress test working. |
| MACRUM | 0:8eedb2495d52 | 556 | - [fseek()](https://linux.die.net/man/3/fseek) |
| MACRUM | 0:8eedb2495d52 | 557 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 558 | - [getc()](https://linux.die.net/man/3/fgets). |
| MACRUM | 0:8eedb2495d52 | 559 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 560 | - [gets()](https://linux.die.net/man/3/fgets). |
| MACRUM | 0:8eedb2495d52 | 561 | - STATUS: Unknown. |
| MACRUM | 0:8eedb2495d52 | 562 | - [putc()](https://linux.die.net/man/3/fputs). |
| MACRUM | 0:8eedb2495d52 | 563 | - STATUS: Unknown. |
| MACRUM | 0:8eedb2495d52 | 564 | - [puts()](https://linux.die.net/man/3/fputs). |
| MACRUM | 0:8eedb2495d52 | 565 | - STATUS: Unknown. |
| MACRUM | 0:8eedb2495d52 | 566 | - [remove()](https://linux.die.net/man/3/remove) |
| MACRUM | 0:8eedb2495d52 | 567 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 568 | - [rewind()](https://linux.die.net/man/3/rewind). |
| MACRUM | 0:8eedb2495d52 | 569 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 570 | - [stat()](https://linux.die.net/man/2/stat) |
| MACRUM | 0:8eedb2495d52 | 571 | - STATUS: Implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 572 | - STATUS: Not supported by ARMCC/IAR libc. |
| MACRUM | 0:8eedb2495d52 | 573 | - [tmpfile()](https://linux.die.net/man/3/tmpfile). |
| MACRUM | 0:8eedb2495d52 | 574 | - STATUS: Not implemented. |
| MACRUM | 0:8eedb2495d52 | 575 | - [tmpnam()](https://linux.die.net/man/3/tmpnam). |
| MACRUM | 0:8eedb2495d52 | 576 | - STATUS: Not implemented. |
| MACRUM | 0:8eedb2495d52 | 577 | |
| MACRUM | 0:8eedb2495d52 | 578 | Supported directory related operations are as follows: |
| MACRUM | 0:8eedb2495d52 | 579 | |
| MACRUM | 0:8eedb2495d52 | 580 | - [closedir()](https://linux.die.net/man/3/closedir). |
| MACRUM | 0:8eedb2495d52 | 581 | - STATUS: Implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 582 | - [mkdir()](https://linux.die.net/man/3/mkdir). |
| MACRUM | 0:8eedb2495d52 | 583 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 584 | - [opendir()](https://linux.die.net/man/3/opendir). |
| MACRUM | 0:8eedb2495d52 | 585 | - STATUS: Implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 586 | - [readdir()](https://linux.die.net/man/3/readdir). |
| MACRUM | 0:8eedb2495d52 | 587 | - STATUS: Implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 588 | - [remove()](https://linux.die.net/man/3/remove). |
| MACRUM | 0:8eedb2495d52 | 589 | - STATUS: Basic testing implemented. Working. |
| MACRUM | 0:8eedb2495d52 | 590 | - [rename()](https://linux.die.net/man/3/rename). |
| MACRUM | 0:8eedb2495d52 | 591 | - STATUS: Implemented. Not tested. |
| MACRUM | 0:8eedb2495d52 | 592 | - [rewinddir()](https://linux.die.net/man/3/rewinddir). |
| MACRUM | 0:8eedb2495d52 | 593 | - STATUS: Implemented. Found not to work. Test case not present in repo. |
| MACRUM | 0:8eedb2495d52 | 594 | - [seekdir()](https://linux.die.net/man/3/seekdir). |
| MACRUM | 0:8eedb2495d52 | 595 | - STATUS: Implemented. Found not to work. Test case not present in repo. |
| MACRUM | 0:8eedb2495d52 | 596 | - [telldir()](https://linux.die.net/man/3/telldir). |
| MACRUM | 0:8eedb2495d52 | 597 | - STATUS: Implemented. Found not to work. Test case not present in repo. |
| MACRUM | 0:8eedb2495d52 | 598 | |
| MACRUM | 0:8eedb2495d52 | 599 | ### errno |
| MACRUM | 0:8eedb2495d52 | 600 | |
| MACRUM | 0:8eedb2495d52 | 601 | Basic errno reporting is supported, tested and known to be working. |
| MACRUM | 0:8eedb2495d52 | 602 | |
| MACRUM | 0:8eedb2495d52 | 603 | |
| MACRUM | 0:8eedb2495d52 | 604 | # Related Projects Resources |
| MACRUM | 0:8eedb2495d52 | 605 | |
| MACRUM | 0:8eedb2495d52 | 606 | The following are related mbed storage projects and useful resources: |
| MACRUM | 0:8eedb2495d52 | 607 | |
| MACRUM | 0:8eedb2495d52 | 608 | - The [mbed-os](https://github.com/ARMmbed/mbed-os) main repository. |
| MACRUM | 0:8eedb2495d52 | 609 | - The [mbed-os-example-fat-filesystem](https://github.com/ARMmbed/mbed-os-example-fat-filesystem) repository. |
| MACRUM | 0:8eedb2495d52 | 610 | This is an example project for the mbed OS FAT filesystem. |
| MACRUM | 0:8eedb2495d52 | 611 | - The [spiflash-driver](https://github.com/armmbed/spiflash-driver) repository. |
| MACRUM | 0:8eedb2495d52 | 612 | - The [i2ceeprom-driver](https://github.com/ARMmbed/i2ceeprom-driver.git) repository. |
| MACRUM | 0:8eedb2495d52 | 613 | - The [ci-test-shield](https://github.com/ARMmbed/ci-test-shield) repository. This is the project describing |
| MACRUM | 0:8eedb2495d52 | 614 | the mbed-os Continuous Integration test shield, together with standard tests. |
| MACRUM | 0:8eedb2495d52 | 615 | - The [mbed-HDK](https://github.com/ARMmbed/mbed-HDK) repository containing Hardware Development Kit resources |
| MACRUM | 0:8eedb2495d52 | 616 | including the schematics for the CI test shield. |
| MACRUM | 0:8eedb2495d52 | 617 | - [POSIX File Interface ISO/IEC 9899:TC2 Documentation](http://www.eng.utah.edu/~cs5785/slides-f10/n1124.pdf). |
| MACRUM | 0:8eedb2495d52 | 618 | - [FATFS: Generic FAT File System Module used in mbed OS](http://elm-chan.org/fsw/ff/00index_e.html) |