Merge pull request #32 from ARMmbed/Readme_update

Update Readme
pull/7774/head
Deepika 2017-08-03 13:01:24 -05:00 committed by GitHub
commit 2d247581c6
1 changed files with 195 additions and 356 deletions

287
README.md
View File

@ -5,7 +5,7 @@ Simon Hughes
20170329
Version 1.00
Version 0.1.1
# Executive Summary
@ -24,7 +24,7 @@ SDCard support and other resources, as outlined below:
- POSIX File API test cases for testing the FAT32 filesystem on SDCard.
- basic.cpp, a basic set of functional test cases.
- fopen.cpp, more functional tests reading/writing greater volumes of data to SDCard, for example.
- `mbed_app.json` mbed-os application configuration file with SPI pin configurations for the CI shield and overrides for specific targets.
- `mbed_lib.json` mbed-os application configuration file with SPI pin configurations for the CI shield and overrides for specific targets.
This file allows the SPI pins to be specified for the target without having to edit the implementation files.
- This README which includes [Summary of POSIX File API Documentation](#summary-posix-api-documentation)
including detailed instruction on how to use the FAT filesystem and SDBlockDevice driver.
@ -83,6 +83,8 @@ The following versions of the mbed-os and sd-driver repositories are known to wo
- {mbed-os, sd-driver} = {mbed-os-5.4.0, sd-driver-0.0.2-mbed-os-5.4.0}.
`K64F`, `NUCLEO_F429ZI` and `UBLOX_EVK_ODIN_W2` fopen and basic filesystem tests working.
- {mbed-os, sd-driver} = {mbed-os-5.4.1, sd-driver-0.0.3-mbed-os-5.4.1}.
- {mbed-os, sd-driver} = {mbed-os-5.5.1, sd-driver-0.1.0-mbed-os-5.5.1}.
- {mbed-os, sd-driver} = {mbed-os-5.5.4, sd-driver-0.1.1-mbed-os-5.5.4}.
To find the latest compatible versions, use the following command to see the messages attached to the tags
in the sd-driver repository:
@ -92,6 +94,7 @@ in the sd-driver repository:
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.
sd-driver-0.0.2-mbed-os-5.4.0 Updated README.md to include worked exmaples and restructuring of information.
sd-driver-0.0.3-mbed-os-5.4.1 Version compatible with mbed-os-5.4.1.
sd-driver-0.1.1-mbed-os-5.5.4 Version compatible with mbed-os-5.5.4
### Known Issues With This Document
@ -174,177 +177,16 @@ storage on SDCard:
# SDCard POSIX File API Example App for Reading/Writing Data
### Overview
This section describes how to build and run an example application that
uses the POSIX File API to read and write data to SDCard. The discussion begins by
descibing how to run the example on the FRDM K64F target, but this is later
generalised to all target platforms that have the standard
Arduino form factor headers. Tthe Continuous Integration (CI) Test Shield
can be inserted into the headers to add a SDCard slot to the target.
The example code is a modified version of the
[mbed-os-example-fat-filesystem](https://github.com/ARMmbed/mbed-os-example-fat-filesystem) example
modified for use with the sd-driver.
The following sub-sections describe the steps for building and running the example:
- The [Pre-Requisites](#pre-requisites) section describes the development environment used for this example.
Other similar development environments can be used.
- The [Create the Example Project](#create-the-example-project) section describes how the application project is created
by including the mbed-os and sd-driver code.
- The [Build the Example Project](#build-the-example-project) section describes how to build the example application.
- The [Insert SDCard into K64F](#insert-sdcard-into-k64f) section describes how to select a card and insert it into the
SDCard slot on the K64F.
- The [Run the Example Binary on the K64F](#run-the-example-binary-on-the-k64f) section describes how to run the
example binary on the target and verify the example has run correctly.
- The [Testing with an SDCard on Target XYZ](#testing-with-an-sdcard-on-target-xyx) section describes the use
of Continuous Integration Test Shield, which hosts an SDCard slot. By inserting the CI test shield into the
Arduino headers of an mbed target platform, the SDCard/FAT Filesystem components can be used to store data
persistently on any standard mbed target development board.
### <a name="pre-requisites"></a> Pre-Requisites
To work through this example, you should have a working development environment on your machine. For example,
the following tools should be installed:
- A compiler e.g. arm-none-eabi-gcc.
- Python 2.7.9 or later.
- [mbed Greentea](https://github.com/armmbed/greentea), the mbed OS test tool.
- Git Bash or a similar git command line tool to interact with the ARM mbed GitHub repositories.
- [mbed-cli](https://github.com/armmbed/mbed-cli), the tool used to make mbed OS application and test builds.
For more information on how to setup a development environment, please review the documentation on the
[mbed documentation site](https://docs.mbed.com).
### <a name="create-the-example-project"></a> Create the Example Project
First create the top level application directory sd_ex1 and move into it:
shell:/d/demo_area$ mkdir sd_ex1
shell:/d/demo_area$ cd sd_ex1
shell:/d/demo_area/sd_ex1$
Next, perform the "mbed new" operation to download the mbed-os repository into this directory:
shell:/d/demo_area/sd_ex1$ mbed new .
[mbed] Creating new program "ex_sdcard" (git)
[mbed] Adding library "mbed-os" from "https://github.com/ARMmbed/mbed-os" at branch latest
[mbed] Updating reference "mbed-os" -> "https://github.com/ARMmbed/mbed-os/#5faf4b26c5954d15c7c1cccac6498e0c690ad101"
warning: LF will be replaced by CRLF in mbed-os.lib.
The file will have its original line endings in your working directory.
shell:/d/demo_area/sd_ex1$ ls -1
mbed-os
mbed-os.lib
mbed_settings.py
shell:/d/demo_area/sd_ex1$
Next, get add the sd-driver component to the application project:
shell:/d/demo_area/sd_ex1$ mbed add sd-driver
<trace removed>
shell:/d/demo_area/sd_ex1$
Next, copy the example1.cpp file and `mbed_app.json` files from inside the sd-driver directory to the top level sd_ex1 directory:
shell:/d/demo_area/sd_ex1$ cp sd-driver/features/TESTS/examples/example1.cpp .
shell:/d/demo_area/sd_ex1$ cp sd-driver/config/mbed_app.json .
shell:/d/demo_area/sd_ex1$
The `mbed_app.json` file specifies the SPI bus pin configuration for different targets.
The file includes a specific configuration of the K64F which is used
because the mbed compile command specifies the K64F build target. The `mbed_app.json` file
is described in more detail in the [Testing with an SDCard on Target XYZ](#testing-with-an-sdcard-on-target-xyx) section.
### <a name="build-the-example-project"></a> Build the Example Project
Next, build the example application:
shell:/d/demo_area/sd_ex1$ mbed compile -m K64F -t GCC_ARM
#### WARNING: "mbed new ." command and possible mbed-os sd-driver versioning incompatibilities
If you experience problems building the example then it may mean the version
of the mbed-os repository created with the "mbed new ." command is not compatible with
the sd-driver repository version created with "mbed add sd-driver" command. This is because:
- The "mbed new ." creates the mbed-os repository at the latest "Release" e.g. `mbed-os-5.4.0`.
- The "mbed add sd-driver" command creates the sd-driver repository at the latest version of
master i.e. the tip of master. Changes may be present that are not compatible with
the latest mbed-os release e.g. in preparation for the next release.
This situation can be resolved by checking out compatible versions of the repositories as
described in the section [Setting mbed-os/sd-driver Repositories To Compatible Versions](#settting-repos-to-compatible-versions)
### <a name="insert-sdcard-into-k64f"></a> Insert SDCard into K64F
The examples and test cases have been run on a K64F with the following pre-formatted microSDHC cards:
- Kingston 2GB mircoSDHC card.
- Kingston 8GB mircoSDHC card.
- SanDisk 16GB mircoSDHC ultra card.
If the card requires formatting then the following procedure is known to work:
- Insert microSD card into SD adapter in USB stick (or similar) so the microSD card can be insert into windows PC.
- Within file explorer, right click/Format on the USB drive.
- Select FAT32, 4096 cluster size, Quick Format.
- Format the drive.
The microSD card should then be ready for use in the K64F. Insert the formatted card
into the SDCard slot on the K64F PCB.
### <a name="run-the-example-binary-on-the-k64f"></a> Run the Example Binary on the K64F
Once the binary is built, copy the binary from `/d/demo_area/sd_ex1/BUILD/K64F/GCC_ARM/example1.bin` to the K64F.
After connecting a serial console and resetting the target, the following trace should be seen:
Welcome to the filesystem example.
Opening a new file, numbers.txt. done.
Writing decimal numbers to a file (20/20) done.
Closing file. done.
Re-opening file read-only. done.
Dumping file to screen.
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
EOF.
Closing file. done.
Opening root directory. done.
Printing all filenames:
numbers.txt
Closeing root directory. done.
Filesystem Demo complete.
Refer to [SD driver Example](https://github.com/ARMmbed/mbed-os-example-sd-driver)
### <a name="testing-with-an-sdcard-on-target-xyx"></a> Testing with an SDCard on Target XYZ
The standard way to test is with the mbed CI Test Shield plugged into the
target board. This pin mapping for this configuration is parameterised in
the `mbed_app.json` file.
the `mbed_lib.json` file.
The following is an example of the `mbed_app.json` file available in the repository:
The following is an example of the `mbed_lib.json` file available in the repository:
{
"config": {
@ -465,9 +307,9 @@ The following is an example of the `mbed_app.json` file available in the reposit
}
}
Note the following things about the `mbed_app.json` file:
Note the following things about the `mbed_lib.json` file:
- The `mbed_app.json` file is used to define target specific symbols for the SPI pins connecting the SDCard slot to the target MCU:
- The `mbed_lib.json` file is used to define target specific symbols for the SPI pins connecting the SDCard slot to the target MCU:
- "SPI\_CS". This is the Chip Select line.
- "SPI\_MOSI". This is the Master Out Slave In data line.
- "SPI\_MISO". This is the Master In Slave Out data line.
@ -495,7 +337,7 @@ Note the following things about the `mbed_app.json` file:
will be used in preference.
- Hence in the case that you want to test a platform with an SDCard inserted into a
fitted CI test shield (rather than the on-board SDCard slot)
and there is a `"target_overrides"` section present in the `mbed_app.json` file, you must then delete the `"target_overrides"`
and there is a `"target_overrides"` section present in the `mbed_lib.json` file, you must then delete the `"target_overrides"`
section before building. This will result in the default configuration being used (suitable for the CI
Test Shield).
- Note when inserting the v1.0.0 CI Test Shield into the Arduino header of the target platform, the shield pins D0 and
@ -511,20 +353,7 @@ Note the following things about the `mbed_app.json` file:
casing with a pair of tweezers, bending it a little to lower it into the slot casing. This helps with the
insertion mechanism.
### Target K64F with CI Test Shield fitted
![alt text](docs/pics/sd_driver_k64_with_ci_test_shield.jpg "unseen title text")
**Figure 2. The figure shows the K64F platform with the CI shield fitted.**
The above figure shows the K64F with the v1.0.0 CI test shield fitted. Note:
- The pins D0/D1 (top right of CI test shield) are bent sideways so as not to insert into the header.
- The SDCard is fully inserted into the slot and overhangs the PCB by ~1mm.
### Wiring instructions for target NUCLEO_F429ZI with CI Test Shield
![alt text](docs/pics/NUCLEO_F429ZI_wiring_with_ci_test_shield.png "unseen title text")
**Figure 3. The figure shows how to connect the NUCLEO_F429ZI platform with the CI shield.**
@ -555,16 +384,32 @@ The following sample code illustrates how to use the sd-driver Block Device API:
int main()
{
// call the SDBlockDevice instance initialisation method.
sd.init();
if ( 0 != sd.init()) {
printf("Init failed \n");
return -1;
}
printf("sd size: %llu\n", sd.size());
printf("sd read size: %llu\n", sd.get_read_size());
printf("sd program size: %llu\n", sd.get_program_size());
printf("sd erase size: %llu\n", sd.get_erase_size());
// set the frequency
if ( 0 != sd.frequency(5000000)) {
printf("Error setting frequency \n");
}
if ( 0 != sd.erase(0, sd.get_erase_size())) {
printf("Error Erasing block \n");
}
// Write some the data block to the device
sd.program(block, 0, 512);
if ( 0 == sd.program(block, 0, 512)) {
// read the data block from the device
sd.read(block, 0, 512);
if ( 0 == sd.read(block, 0, 512)) {
// print the contents of the block
printf("%s", block);
}
}
// call the SDBlockDevice instance de-initialisation method.
sd.deinit();
@ -589,14 +434,14 @@ The following steps are covered:
### <a name="create-fat-sdcard-application-project"></a> Create the FAT/SDCard Application Project
This section describes how to create an application project combining the
mbed-os and sd-driver repositories into a single project.
This section describes how to create an application project combining the mbed-os and
sd-driver repositories into a single project.
In summary the following steps will be covered in this section:
- A top level application project directory is created. The directory name is ex_app1.
- In the ex_app1 directory, the mbed-os repository is cloned.
- In the ex_app1 directory at the same level as the mbed-os directory, the sd-driver repository is cloned.
- The `mbed_app.json` file is copied from the `sd-driver/config/mbed_app.json` to the ex_app1 directory.
- The `mbed_lib.json` file is copied from the `sd-driver/config/mbed_lib.json` to the ex_app1 directory.
First create the top level application directory ex_app1 and move into it:
@ -615,20 +460,14 @@ Next, get a clone of the sd-driver repository:
<trace removed>
shell:/d/demo_area/ex_app1$
Finally, copy the `mbed_app.json` application configuration file from `sd-driver/config/mbed_app.json` to the ex_app1 directory:
shell:/d/demo_area/ex_app1$ cp sd-driver/config/mbed_app.json .
shell:/d/demo_area/ex_app1$
The `mbed_app.json` file specifies the SPI bus pin configuration for different targets,
Note: The `mbed_lib.json` file specifies the SPI bus pin configuration for different targets,
and is discussed in the [Testing with an SDCard on Target XYZ](#testing-with-an-sdcard-on-target-xyx) section.
### <a name="build-the-mbedos-test-cases"></a> Build the mbed OS Test Cases
Build the test cases for the K64F target using the following command:
shell:/d/demo_area/ex_app1$ mbed -v test --compile -t GCC_ARM -m K64F --app-config mbed_app.json
shell:/d/demo_area/ex_app1$ mbed -v test --compile -t GCC_ARM -m K64F
<trace removed>
shell:/d/demo_area/ex_app1$
@ -642,8 +481,8 @@ The build trace is quite extensive but on a successful build you should see the
* K64F::GCC_ARM::MBED-OS-FEATURES-TESTS-FILESYSTEM-HEAP_BLOCK_DEVICE
* K64F::GCC_ARM::MBED-OS-FEATURES-TESTS-FILESYSTEM-UTIL_BLOCK_DEVICE
<trace removed>
* K64F::GCC_ARM::SD-DRIVER-FEATURES-TESTS-FILESYSTEM-BASIC
* K64F::GCC_ARM::SD-DRIVER-FEATURES-TESTS-FILESYSTEM-FOPEN
* K64F::GCC_ARM::SD-DRIVER-TESTS-FILESYSTEM-BASIC
* K64F::GCC_ARM::SD-DRIVER-TESTS-FILESYSTEM-FOPEN
Build skips:
* K64F::GCC_ARM::MBED-OS-FEATURES-FEATURE_LWIP-TESTS-MBEDMICRO-NET-TCP_PACKET_PRESSURE
@ -652,14 +491,14 @@ The build trace is quite extensive but on a successful build you should see the
Notice the following tests in the sd-driver tree are listed above:
- `K64F::GCC_ARM::SD-DRIVER-FEATURES-TESTS-FILESYSTEM-BASIC`
- `K64F::GCC_ARM::SD-DRIVER-FEATURES-TESTS-FILESYSTEM-FOPEN`
- `K64F::GCC_ARM::SD-DRIVER-TESTS-FILESYSTEM-BASIC`
- `K64F::GCC_ARM::SD-DRIVER-TESTS-FILESYSTEM-FOPEN`
The FAT32/SDCard test cases are at following locations in the source code tree:
/d/demo_area/ex_app1/sd-driver/features/TESTS/filesystem/basic/basic.cpp
/d/demo_area/ex_app1/sd-driver/features/TESTS/filesystem/fopen/fopen.cpp
/d/demo_area/ex_app1/sd-driver/TESTS/filesystem/basic/basic.cpp
/d/demo_area/ex_app1/sd-driver/TESTS/filesystem/fopen/fopen.cpp
#### <a name="settting-repos-to-compatible-versions"></a> Setting mbed-os/sd-driver Repositories To Compatible Versions
@ -707,11 +546,11 @@ The names of the tests can be listed using:
For example, to run the basic test use:
shell:/d/demo_area/ex_app1$ mbedgt -VS --test-by-names=sd-driver-features-tests-filesystem-basic
shell:/d/demo_area/ex_app1$ mbedgt -VS --test-by-names=sd-driver-tests-filesystem-basic
To run the fopen test use:
shell:/d/demo_area/ex_app1$ mbedgt -VS --test-by-names=sd-driver-features-tests-filesystem-fopen
shell:/d/demo_area/ex_app1$ mbedgt -VS --test-by-names=sd-driver-tests-filesystem-fopen
On a successful run, results similar to the following will be shown:
@ -723,25 +562,25 @@ On a successful run, results similar to the following will be shown:
+--------------+---------------+-------------------------------------------+--------+--------------------+-------------+
mbedgt: test suite results: 1 OK
mbedgt: test case report:
+--------------+---------------+-------------------------------------------+----------------------------------------------------------------------------------------+--------+--------+--------+--------------------+
+--------------+---------------+------------------------------------+----------------------------------------------------------------------------------------+--------+--------+--------+--------------------+
| target | platform_name | test suite | test case | passed | failed | result | elapsed_time (sec) |
+--------------+---------------+-------------------------------------------+----------------------------------------------------------------------------------------+--------+--------+--------+--------------------+
| 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 |
| 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 |
| 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 |
| 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 |
| K64F-GCC_ARM | K64F | sd-driver-features-tests-filesystem-fopen | FSFAT_FOPEN_TEST_06: fopen() with bad filenames (minimal). | 1 | 0 | OK | 0.1 |
| K64F-GCC_ARM | K64F | sd-driver-features-tests-filesystem-fopen | FSFAT_FOPEN_TEST_07: fopen()/errno handling. | 1 | 0 | OK | 0.07 |
| K64F-GCC_ARM | K64F | sd-driver-features-tests-filesystem-fopen | FSFAT_FOPEN_TEST_08: ferror()/clearerr()/errno handling. | 1 | 0 | OK | 0.1 |
| K64F-GCC_ARM | K64F | sd-driver-features-tests-filesystem-fopen | FSFAT_FOPEN_TEST_09: ftell() handling. | 1 | 0 | OK | 0.17 |
| K64F-GCC_ARM | K64F | sd-driver-features-tests-filesystem-fopen | FSFAT_FOPEN_TEST_10: remove() test. | 1 | 0 | OK | 1.28 |
| K64F-GCC_ARM | K64F | sd-driver-features-tests-filesystem-fopen | FSFAT_FOPEN_TEST_11: rename(). | 1 | 0 | OK | 2.3 |
| K64F-GCC_ARM | K64F | sd-driver-features-tests-filesystem-fopen | FSFAT_FOPEN_TEST_12: opendir(), readdir(), closedir() test. | 1 | 0 | OK | 3.57 |
| K64F-GCC_ARM | K64F | sd-driver-features-tests-filesystem-fopen | FSFAT_FOPEN_TEST_13: mkdir() test. | 1 | 0 | OK | 1.21 |
| K64F-GCC_ARM | K64F | sd-driver-features-tests-filesystem-fopen | FSFAT_FOPEN_TEST_14: stat() test. | 1 | 0 | OK | 1.47 |
| K64F-GCC_ARM | K64F | sd-driver-features-tests-filesystem-fopen | FSFAT_FOPEN_TEST_15: format() test. | 1 | 0 | OK | 26.12 |
| 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 |
+--------------+---------------+-------------------------------------------+----------------------------------------------------------------------------------------+--------+--------+--------+--------------------+
+--------------+---------------+------------------------------------+----------------------------------------------------------------------------------------+--------+--------+--------+--------------------+
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_01: fopen()/fwrite()/fclose() directories/file in multi-dir filepath. | 1 | 0 | OK | 7.57 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_02: fopen(r) pre-existing file try to write it. | 1 | 0 | OK | 0.2 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_03: fopen(w+) pre-existing file try to write it. | 1 | 0 | OK | 0.41 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_04: fopen() with a filename exceeding the maximum length. | 1 | 0 | OK | 0.11 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_06: fopen() with bad filenames (minimal). | 1 | 0 | OK | 0.1 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_07: fopen()/errno handling. | 1 | 0 | OK | 0.07 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_08: ferror()/clearerr()/errno handling. | 1 | 0 | OK | 0.1 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_09: ftell() handling. | 1 | 0 | OK | 0.17 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_10: remove() test. | 1 | 0 | OK | 1.28 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_11: rename(). | 1 | 0 | OK | 2.3 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_12: opendir(), readdir(), closedir() test. | 1 | 0 | OK | 3.57 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_13: mkdir() test. | 1 | 0 | OK | 1.21 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_14: stat() test. | 1 | 0 | OK | 1.47 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_15: format() test. | 1 | 0 | OK | 26.12 |
| K64F-GCC_ARM | K64F | sd-driver-tests-filesystem-fopen | FSFAT_FOPEN_TEST_16: write/check n x 25kB data files. | 1 | 0 | OK | 87.11 |
+--------------+---------------+------------------------------------+----------------------------------------------------------------------------------------+--------+--------+--------+--------------------+
mbedgt: test case results: 15 OK
mbedgt: completed in 152.35 sec