sd-driver with adjustable spi freq.

Dependents:   K64F-os5-fs HelloWorld_CCA01M1_mbedOS HelloWorld_CCA01M1_mbedOS_semplificato mbed-os-example-blinky ... more

Committer:
coverxit
Date:
Fri May 05 20:13:54 2017 +0000
Revision:
1:0df98d0fd2a5
Parent:
0:f32a15965d96
adjustable spi.

Who changed what in which revision?

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