sd-driver - sd-driver with adjustable spi freq.

Users » flombella » Code » sd-driver

sd-driver with adjustable spi freq.

README.md@2:7b302d81ede0, 2021-05-05 (annotated)

Committer:: flombella
Date:: Wed May 05 07:18:48 2021 +0000
Revision:: 2:7b302d81ede0
Parent:: 0:f32a15965d96

Esempio utilizzo di file system simulato sulla RAM della scheda

Who changed what in which revision?

User	Revision	Line number	New 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

Repository toolbox

Export to desktop IDE

Repository details

Type:	Library
Created:	05 May 2021
Imports:	2
Forks:	0
Commits:	3
Dependents:	0
Dependencies:	0
Followers:	1

README.md@2:7b302d81ede0, 2021-05-05 (annotated)

Who changed what in which revision?

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning