Liam Grazier / Mbed OS Final351CWfolderonly

SEND

Fork of Final351CW_FINAL by Liam Grazier

sd-driver/README.md@11:ce2a977dcab0, 2018-01-09 (annotated)

Committer:
liam_grazier
Date:
Tue Jan 09 11:59:10 2018 +0000
Revision:
11:ce2a977dcab0
NEW NON LIB;

Who changed what in which revision?

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