ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
mbed-os/features/filesystem/README.md

285 lines
12 KiB
Markdown
Raw Blame History

# FAT32 Filesystem Support README #
Simon Hughes
20161219
Version 0.02
# Executive Summary
These notes are intended to help the mbed client team adopt the mbedOS POSIX File API support. The notes cover:
- Brief notes on how to setup the mbedOS development environment, including links to other resources.
- How to build the mbedOS test cases.
- How to run the POSIX File API test case.
Note the following:
- The mbedOS FAT32/SDCard support implements a POSIX File API for off-chip, persistent file storage.
- The FAT32/SDCard support was present in mbedOS 2, but was moved to the "unsupported" area of the source tree in mbedOS 5.
This is because there are currently no FAT32/SDCard POSIX API test cases in the public repository, software quality is hence unknown, and the features are therefore unsupported.
- The implementation of new test cases is an active development activity. So far, one test binary (basic.cpp) has been implemented and is available on the mbed-os branch called 'feature-storage'. The test case support
is being enhanced as a matter of urgency.
- The work described here is intended to make the POSIX File API available to the mbed client team before the Christmas holidays.
Further test cases will be implemented and when completed, the work will be merged into the public repository master branch. In the meantime,
the work is available from feature-storage branch.
# Getting Started
This section describes how to build and run the POSIX file API test case. The following steps are covered:
- [Installing the Tools](#installing-the-tools). This section briefly describes how to setup the mbedos development environment.
- [Git Clone the Public mbedOS Repo](#git-clone-the-mbedos-repo). This section describes how to git clone the mbedOS repository containing the FAT32/SDCard and POSIX File API test case of interest.
- [Build the mbedOS Test Cases](#build-the-mbedos-test-cases). This section describes how to build the mbedOS test cases.
- [Run the POSIX File Test Case](#run-the-posix-file-test-cases).This section describes how to run the POSIX file test case basic.cpp.
### <a name="installing-the-tools"></a> Installing the Tools
The following tools should be installed:
- arm-none-eabi-gcc. See [mbedOS Development Environment Setup Howto Notes][MBED_DEVENV_NOTES] for guidance.
- Python 2.7.9 or later. See [mbedOS Development Environment Setup Howto Notes][MBED_DEVENV_NOTES] for guidance.
- mbed Greentea. This is the mbedOS test tool.
- Git Bash. See [mbedOS Development Environment Setup Howto Notes][MBED_DEVENV_NOTES] for guidance.
- mbed-cli. This is the tool used to make mbedOS application and test builds.
Using a Git Bash terminal, setup mbed-cli in the following way:
simhug01@E107851:/d/demo_area$ git clone git@github.com:/armmbed/mbed-cli
<trace removed>
simhug01@E107851:/d/demo_area$ pushd mbed-cli
simhug01@E107851:/d/demo_area/mbed-cli/$ python.exe setup.py install
simhug01@E107851:/d/demo_area/mbed-cli/$ popd
Using a Git Bash terminal, setup Greentea in the following way:
simhug01@E107851:/d/demo_area$ git clone git@github.com:/armmbed/greentea
<trace removed>
simhug01@E107851:/d/demo_area$ pushd greentea
simhug01@E107851:/d/demo_area/greentea/$ python.exe setup.py install
simhug01@E107851:/d/demo_area/greentea/$ popd
simhug01@E107851:/d/demo_area/$
### <a name="git-clone-the-mbedos-repo"></a> Git Clone the Public mbedOS Repo
Get a clone of public mbedOS repository in the following way
simhug01@E107851:/d/demo_area$ mkdir ex_app1
simhug01@E107851:/d/demo_area$ pushd ex_app1
simhug01@E107851:/d/demo_area/ex_app1$ git clone git@github.com:/armmbed/mbed-os
<trace removed>
simhug01@E107851:/d/demo_area/ex_app1$
### <a name="build-the-mbedos-test-cases"></a> Build the mbedOS Test Cases
Switch to the `feature-storage` branch using the following commands:
simhug01@E107851:/d/demo_area/ex_app1$ pushd mbed-os
simhug01@E107851:/d/demo_area/ex_app1$ git branch
* master
feature-storage
<other branches deleted>
simhug01@E107851:/d/demo_area/ex_app1$ git checkout feature-storage
Switched to branch 'feature-storage'
simhug01@E107851:/d/demo_area/ex_app1$ git branch
master
* feature-storage
<other branches deleted>
simhug01@E107851:/d/demo_area/ex_app1$
Build the test cases for the K64F target using the following commands:
simhug01@E107851:/d/demo_area/ex_app1$ mbed -v test --compile -t GCC_ARM -m K64F -DFSFAT_SDCARD_INSTALLED 2>&1 | tee build_tests_gcc_20161219_1007.txt
<trace removed>
simhug01@E107851:/d/demo_area/ex_app1$
The complete [build log][BUILD-TESTS-GCC-20161219-1007] is available for reference.
### <a name="run-the-posix-file-test-cases"></a> Run the POSIX File Test Case
To setup for running the test cases, complete the following steps:
- Insert a micro SDCard into K64F SDCard socket.
- Connect the K64F development board to your PC using a suitable USB cable.
All tests can be run using the following command:
simhug01@E107851:/d/demo_area/ex_app1$ mbedgt -VS
<trace removed>
However, it's possible to run a particular test case using the following .json file:
{
"builds": {
"K64F-GCC_ARM": {
"binary_type": "bootable",
"tests": {
"mbed-os-features-storage-feature_storage-tests-fs-fat-basic": {
"binaries": [
{
"path": "BUILD/tests/K64F/GCC_ARM/mbed-os/features/storage/FEATURE_STORAGE/TESTS/fs-fat/basic/basic.bin"
}
]
}
},
"toolchain": "GCC_ARM",
"base_path": "BUILD/tests/K64F/GCC_ARM",
"baud_rate": 9600,
"platform": "K64F"
}
}
}
Store the above text in a file called `ex_app1_fat_basic_spec.json` in the ex_app1 directory. The test can be run using the following command:
simhug01@E107851:/d/demo_area/ex_app1$ mbedgt -VS --test-spec=ex_app1_fat_basic_spec.json 2>&1 | tee run_tests_master_gcc_ex_app2_fat_basic_20161219_1011.txt
<trace removed>
On a successful run, the following table will be shown at the end of the log:
mbedgt: test suite 'mbed-os-features-storage-feature_storage-tests-fs-fat-basic' ..................... OK in 15.86 sec
test case: 'FSFAT_test_00: fopen()/fgetc()/fprintf()/fclose() test.' ......................... OK in 0.90 sec
test case: 'FSFAT_test_01: fopen()/fseek()/fclose() test.' ................................... OK in 0.32 sec
mbedgt: test case summary: 2 passes, 0 failures
mbedgt: all tests finished!
mbedgt: shuffle seed: 0.7720862854
mbedgt: test suite report:
+--------------+---------------+-------------------------------------------------------------+--------+--------------------+-------------+
| target | platform_name | test suite | result | elapsed_time (sec) | copy_method |
+--------------+---------------+-------------------------------------------------------------+--------+--------------------+-------------+
| K64F-GCC_ARM | K64F | mbed-os-features-storage-feature_storage-tests-fs-fat-basic | OK | 15.86 | shell |
+--------------+---------------+-------------------------------------------------------------+--------+--------------------+-------------+
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 | mbed-os-features-storage-feature_storage-tests-fs-fat-basic | FSFAT_test_00: fopen()/fgetc()/fprintf()/fclose() test. | 1 | 0 | OK | 0.9 |
| K64F-GCC_ARM | K64F | mbed-os-features-storage-feature_storage-tests-fs-fat-basic | FSFAT_test_01: fopen()/fseek()/fclose() test. | 1 | 0 | OK | 0.32 |
+--------------+---------------+-------------------------------------------------------------+---------------------------------------------------------+--------+--------+--------+--------------------+
mbedgt: test case results: 2 OK
mbedgt: completed in 16.53 sec
The full [test output log][RUN-TESTS-GCC-20161219-1011] is available for reference.
# POSIX File API
mbedOS supports a subset of the POSIX File API, as outlined below:
- clearerr()
- STATUS: Basic testing implemented. Working.
- [fclose()][MAN_FCLOSE].
- STATUS: Basic testing implemented. Working.
- ferror()
- STATUS: Basic testing implemented. Working.
- [fgetc()][MAN_FGETS].
- STATUS: Basic testing implemented. Working.
- [fgets()][MAN_FGETS].
- STATUS: Basic testing implemented. Working.
- [fputc()][MAN_FPUTS].
- STATUS: Unknown.
- [fputs()][MAN_FPUTS].
- STATUS: Basic testing implemented. Working.
- fprintf()
- STATUS: Basic testing implemented. Working.
- fopen()
- STATUS: Basic testing implemented. Working.
- freopen()
- STATUS: This is not tested.
- [fread()][MAN_FREAD]
- STATUS: Basic testing implemented. Working.
- ftell()
- STATUS: Basic testing implemented. Working.
- [fwrite()][MAN_FWRITE]
- STATUS: Basic testing implemented. Working.
- [fseek()][MAN_FSEEK]
- STATUS: Basic testing implemented. Working.
- [getc()][MAN_FGETS].
- STATUS: Basic testing implemented. Working.
- [gets()][MAN_FGETS].
- STATUS: Unknown.
- [putc()][MAN_FPUTS].
- STATUS: Unknown.
- [puts()][MAN_FPUTS].
- STATUS: Unknown.
- [remove()][MAN_REMOVE]
- STATUS: Basic testing implemented. Working.
- rewinddir().
- STATUS: Implemented. Not tested.
- stat()
- STATUS: Implemented. Not tested.
- tmpfile()
- STATUS: Not implemented.
- tmpnam()
- STATUS: Not implemented.
Supported directory related operations are as follows:
- closedir().
- STATUS: Implemented. Not tested.
- mkdir().
- STATUS: Basic testing implemented. Working.
- opendir().
- STATUS: Implemented. Not tested.
- readdir().
- STATUS: Implemented. Not tested.
- [remove()][MAN_REMOVE]
- STATUS: Basic testing implemented. Working.
- rename()
- STATUS: Implemented. Not tested.
- [rewind()][MAN_REWIND].
- STATUS: Basic testing implemented. Working.
- seekdir()
- STATUS: Implemented. Not tested.
- telldir().
- STATUS: Implemented. Not tested.
## errno
Basic errno reporting is supported, tested and known to be working. This will be extended
as further test cases are implemented.
## Miscellaneous Information
The FAT32/SDCard support is at the following location in the source code tree:
<mbed-os_src_root>\features\storage\FEATURE_STORAGE\fs
The FAT32/SDCard test cases are at following locations in the source code tree:
<mbed-os_src_root>\features\storage\FEATURE_STORAGE\TESTS\filesystem\basic\basic.cpp
<mbed-os_src_root>\features\storage\FEATURE_STORAGE\TESTS\filesystem\fopen\fopen.cpp
# Further Reading
* The [mbedOS Development Environment Setup Notes][MBED_DEVENV_NOTES].
* The example mbedOS build log [BUILD-TESTS-GCC-20161219-1007][BUILD-TESTS-GCC-20161219-1007] for reference.
* The example mbedOS test run log [RUN-TESTS-GCC-20161219-1011][RUN-TESTS-GCC-20161219-1011] for reference.
[MBED_DEVENV_NOTES]: https://github.com/ARMmbed/meVo/blob/master/docs/ARM_MBED/TN/ARM_MBED_TN_0017/12-mbed_devenv_setup_how_to_notes.docx
[BUILD-TESTS-GCC-20161219-1007]: https://github.com/ARMmbed/meVo/blob/master/docs/ARM_MBED/TN/ARM_MBED_TN_0017/build_tests_gcc_20161219_1007.txt
[RUN-TESTS-GCC-20161219-1011]: https://github.com/ARMmbed/meVo/blob/master/docs/ARM_MBED/TN/ARM_MBED_TN_0017/run_tests_master_gcc_ex_app2_fat_basic_20161219_1011.txt
[MAN_FCLOSE]: https://linux.die.net/man/3/fclose
[MAN_FGETS]: https://linux.die.net/man/3/fgets
[MAN_FPUTS]: https://linux.die.net/man/3/fputs
[MAN_FREAD]: https://linux.die.net/man/3/fread
[MAN_FSEEK]: https://linux.die.net/man/3/fseek
[MAN_FWRITE]: https://linux.die.net/man/3/fwrite
[MAN_REMOVE]: https://linux.die.net/man/3/remove
[MAN_REWIND]: https://linux.die.net/man/3/rewind
Reference in New Issue View Git Blame Copy Permalink