Skip to content

Added FAT file system documentation #518

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
May 21, 2018
Merged

Added FAT file system documentation #518

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
835a2ec
Added some FAT file system documentation
geky May 14, 2018
3205975
Copy edit FATFileSystem.md
May 17, 2018
a9d4b99
Copy edit storage.md
May 17, 2018
c96bcb5
Copy edit storage.md
May 17, 2018
a4b1b83
Make changes from comments
May 21, 2018
63416ef
Add link to storage.md
May 21, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 33 additions & 2 deletions docs/reference/api/storage/FATFileSystem.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,43 @@

<span class="images">![](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_f_a_t_file_system.png)<span>FATFileSystem class hierarchy</span></span>

[Add description here.]
The FAT file system is an established disk-oriented file system that you can find on Mbed OS, Windows, Linux and Mac OS X. Due to its age and popularity, the FAT file system has become the standard for portable storage, such as flash drivers and SD cards.

- **Portable** - Due to its nearly universal support across operating systems, the FAT file system provides access to storage from both the embedded system and your PC.

- **Embedded** - Built on the ChanFS project, the FAT file system is optimized for embedded systems.

For additional information, please see the [storage overview page](/docs/development/reference/storage.html#declaring-a-file-system).

### Use cases

The main reason to use the FAT file system is its usefulness on portable storage. Because of this, most applications using FAT in conjunction with an SD card.

The first step to using the FAT file system is formatting storage with FAT. You can do this on a PC with the native format command or on Mbed OS with the `format` function.

<span class="notes">**Note:** The FAT file system requires at minimum 256 erase blocks. You can find the number of blocks on a block device by dividing the block device's size by its erase size.</span>

The FAT file system supports external flash; however, it must allocate a full erase block for internal operations, which can become large for some forms of flash. If RAM consumption becomes a problem, we suggest switching to LittleFileSsystem. The Mbed OS file system APIs make switching file systems a straightforward task. One common strategy is to use the FAT file system for debugging and switch to LittleFileSystem when the application becomes stable.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there's an extra 's' there

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry - where?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LittleFileSsystem


### Usage

Instantiate the `FATFileSystem` class with a block device and file path.

The API that this presents is the standard Mbed OS file system API. Once declared, Mbed OS provides the retargeting layer for the standard C library.

You can swap the FAT file system in place with other Mbed OS file systems, which is a good method for prototyping applications.

### FATFileSystem class reference

[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_f_a_t_file_system.html)

### FATFileSystem example

[Add example here.]
[![View code](https://www.mbed.com/embed/?url=https://github.com/armmbed/mbed-os-example-
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't rendering for me properly, just shows up as the raw text rather than the example button. Could be my browser though.

filesystem)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-filesystem/file/
8e251d9511b8/main.cpp)

### Related content

- [Storage configuration](configuration-storage.html).
- [LittleFileSystem](littlefilesystem.html).
20 changes: 17 additions & 3 deletions docs/reference/api/storage/storage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,15 @@ The `fopen` function is similar to the open function above but associates a stre

- **Wear leveling** - Because the most common form of embedded storage is erodible flash memories, this file system provides a form of dynamic wear leveling for systems that cannot fit a full flash translation layer.

- **FATFileSystem** - The FAT file system is a well-known file system that you can find on almost every system, including PCs. The Mbed OS implementation of the FAT file system is based on ChanFS and is optimized for small embedded systems.
- **FATFileSystem** - The FAT file system is an established disk-oriented file system that you can find on most operating systems, including Windows, Linux, Mac OS X and Mbed OS.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need a link to page with details about FATFileSystem to make it consistent compared to LittleFS.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah good catch, I believe this should link to the FATFileSystem.md also in this PR.

@AnotherButler, are you able to add this link so it will work on the doc site?

- **Portable** - Almost every operating system supports the FAT file system, which is the most common file system found on portable storage, such as SD cards and flash drives. The FAT file system is the easiest way to support access from a PC.
- **Portable** - Due to its support across operating systems, the FAT file system provides access to storage from both the embedded system and your PC.

- **Embedded** - Built on the ChanFS project, the FAT file system is optimized for embedded systems.

The [BlockDevice](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_block_device.html) class provides the underlying API for representing block-based storage that you can use to back a file system. Mbed OS provides standard interfaces for the more common storage media, and you can extend the BlockDevice class to provide support for unsupported storage.

Additionally, two utility block devices give you better control over storage allocation. The [slicing block device](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_slicing_block_device.html) allows you to partition storage into smaller block devices that you can use independently, and the [chaining block device](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_chaining_block_device.html) allows you to chain multiple block devices together and extend the usable amount of storage.
Additionally, two utility block devices give you better control over storage allocation. The [SlicingBlockDevice](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_slicing_block_device.html) allows you to partition storage into smaller block devices that you can use independently, and the [ChainingBlockDevice](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_chaining_block_device.html) allows you to chain multiple block devices together and extend the usable amount of storage.

<span class="notes">**Note:** Some file systems may provide a format function for cleanly initializing a file system on an underlying block device or require external tools to set up the file system before the first use.</span>

Expand Down Expand Up @@ -63,6 +65,18 @@ We optimized this file system to work with a limited amount of RAM and ROM. It a

The "little" in the little file system comes from the focus on both keeping resource usage low and keeping the scope self-contained. Aside from the three targeted issues above, there is a heavy restriction against bloat in this software module. Instead, we push additional features to separate layers in the BlockDevice API that drives the Mbed OS storage stack. This gives Mbed OS a tool for remaining flexible as technology used by IoT devices develops.

#### The FATFileSystem

The FAT file system is an established disk-oriented file system that you can find on Mbed OS, Windows, Linux and Mac OS X. Due to its age and popularity, the FAT file system has become the standard for portable storage, such as flash drives and SD cards.

##### Portable

The primary feature of the FAT file system is its portability. With support across PC operating systems, the FAT file system lets you access storage from both the embedded system your PC. This gives users a way to get information onto and off of the device.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've read some of this content three times now. Instead of duplicating it, let's keep API-specific content on the API reference pages and general concepts on the overview pages.

Copy link
Contributor Author

@geky geky May 17, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still think this causes problems for users, since the general concepts are important to understand the API and the users I've seen don't ever see the overview page.

But feel free to update it so it's consistent.


##### Embedded

The Mbed OS FAT file system is built on the ChanFS project. It is optimized for embedded systems and is one of the smallest FAT file system implementations.

### Partitioning

Partitioning allows you to split a block device among multiple storage users such that the split is portable across multiple systems. Partitioning also allows you to have multiple file systems that you can mount on one disk from both Mbed OS devices and host computers. The primary partitioning scheme that Mbed OS supports is the Master Boot Record (MBR).
Expand Down