File System Example Applications#

This section describes the examples that are related to the Micrium OS File System stack.

File System Module Initialization Example#

Description#

This example shows how to initialize the File System stack. It will allow you to accomplish the following tasks:

  • Optionally configure the media polling callbacks

  • Initialize the Storage layer

  • Initialize the Core layer

  • Optionally Create a RAM Disk region

  • Optionally low-level format NAND or NOR media

  • Create a cache instance

  • Optionally format the RAM Disk region as a FAT volume

  • Optionally initialize the Media Polling example

  • Optionally high-level format any media (that is NAND, NOR or SD) as a FAT volume

Configuration#

EX_CFG_FS_ACTIVE_MEDIA_NAME#

The file ex_fs.h offers a global configuration that allows you to choose the media on which any File System examples will run: EX_CFG_FS_ACTIVE_MEDIA_NAME.

The media name must have the following format: "<media-name><number>". The configuration can have the following values:

  • "nand0" for NAND

  • "nor0" for NOR

  • "ram0" for RAM Disk

  • "sd0" for SD Card or SPI

The media name could be any name, in fact. But the File System examples requires that the defined media name matches the one defined in the BSP when the media is registered. Most of the time the media name used in the BSP will be "<media-name>0".

For SCSI devices, you do not need to specify for instance "scsi0". SCSI devices are used only by the Media Polling example and do not require a media name defined. The media name for SCSI device is automatically managed by the Media Polling example.

The default configuration value depends on the media that are available in rtos_description.h. EX_CFG_FS_ACTIVE_MEDIA_NAME default value is determined as shown in listing Listing - EX CFG FS ACTIVE MEDIA NAME Default Configuration Value in the File System Example Applications page.

Listing - EX CFG FS ACTIVE MEDIA NAME Default Configuration Value#
#ifndef  EX_CFG_FS_ACTIVE_MEDIA_NAME                            (1)
#if (defined(RTOS_MODULE_FS_STORAGE_RAM_DISK_AVAIL))
#define  EX_CFG_FS_ACTIVE_MEDIA_NAME            "ram0"
#elif (defined(RTOS_MODULE_FS_STORAGE_NAND_AVAIL))
#define  EX_CFG_FS_ACTIVE_MEDIA_NAME            "nand0"
#elif (defined(RTOS_MODULE_FS_STORAGE_NOR_AVAIL))
#define  EX_CFG_FS_ACTIVE_MEDIA_NAME            "nor0"
#elif (defined(RTOS_MODULE_FS_STORAGE_SD_CARD_AVAIL) || defined(RTOS_MODULE_FS_STORAGE_SD_SPI_AVAIL))
#define  EX_CFG_FS_ACTIVE_MEDIA_NAME            "sd0"
#endif
#endif

(1) If you want to run the File System examples on a specific media, you can define EX_CFG_FS_ACTIVE_MEDIA_NAME before the #ifndef to overwrite the default value. For instance:

#define  EX_CFG_FS_ACTIVE_MEDIA_NAME                "nand0"

EX_CFG_FS_MEDIA_LOW_LEVEL_FMT_EN#

The file ex_fs.c offers a local configuration allowing your application to low-level format a NAND or NOR chip: EX_CFG_FS_MEDIA_LOW_LEVEL_FMT_EN.

If you have a blank NAND or NOR chip, you must low-level format the memory chip prior to accessing the media by the high-level file system API. You may want to low-level format explicitly even if the NAND or NOR chip is already formatted. After a low-level format, you must format the NAND or NOR chip with a high-level format; for instance, high-level formatting as a FAT volume. High-level formatting is controlled by the configuration EX_CFG_FS_MEDIA_HIGH_LEVEL_FMT_EN. Low-level formating does not apply to RAM, SD and SCSI devices.

The configuration can have the following values: DEF_DISABLED or DEF_ENABLED. By default, this configuration is set to DEF_DISABLED.

EX_CFG_FS_MEDIA_HIGH_LEVEL_FMT_EN#

The file ex_fs.c offers a local configuration allowing your application to high-level format any media (NAND, NOR, RAM Disk, SD): EX_CFG_FS_MEDIA_HIGH_LEVEL_FMT_EN.

When enabled, the high-level format will apply to the unique partition that composes your media. If a NAND or NOR chip has been low-level formatted, the high-level format is mandatory.

The configuration can have the following values: DEF_DISABLED or DEF_ENABLED. By default, this configuration is set to DEF_DISABLED.

Location#

The example implementation is located in:

  • /examples/fs/ex_fs.c

  • /examples/fs/ex_fs.h

  • /examples/fs/ex_fs_utils.h

API#

This example offers only one API named Ex_FS_Init(). This function performs the different example steps mentioned in the section Description . The function must be called by your application task prior to calling any other file system File System examples.

File Read/Write Example#

Description#

This example shows how to perform a file write and a file read on a given media. This example will allow you to accomplish the following tasks:

  • Set file position at the beginning of the file

  • Write some known data to the specified file

  • Set again file position at the beginning of the file

  • Read data from the specified file

  • Verify the read data integrity

Location#

The example implementation is located in:

  • /examples/fs/ex_fs_file_rd_wr.c

  • /examples/fs/ex_fs_file_rd_wr.h.

The following files are also required:

  • /examples/fs/ex_fs.c

  • /examples/fs/ex_fs.h

  • /examples/fs/ex_fs_utils.h.

API#

This example offers only one API named Ex_FS_FileRdWr(). This function performs the different example steps mentioned in the section Description . The function can be called by your application task by including the associated header file ex_fs_file_rd_wr.h.

File Read/Write with Posix API Example#

Description#

This example shows how to perform a file write and a file read on a given media using the Posix API. This example will allow you to accomplish the following tasks:

  • Set file position at the beginning of the file

  • Write some known data to the specified file

  • Set again file position at the beginning of the file

  • Read data from the specified file

  • Verify the read data integrity

Location#

The example implementation is located in:

  • /examples/fs/ex_fs_file_rd_wr_posix.c

  • /examples/fs/ex_fs_file_rd_wr_posix.h

The following files are also required:

  • /examples/fs/ex_fs.c

  • /examples/fs/ex_fs.h

  • /examples/fs/ex_fs_utils.h

API#

This example offers only one API named Ex_FS_FileRdWr_Posix(). This function performs the different example steps mentioned in the section Description . The function can be called by your application task by including the associated header file ex_fs_file_rd_wr_posix.h.

File Multi-Descriptors Example#

Description#

This example shows how to open the same file with two different file descriptors: one file descriptor has a write access and the other as a read-only access. This example will allow you to accomplish the following tasks:

  • Create a Reader task

  • Writer task writes N logical blocks with a known data pattern to the specified file. The Writer task is represented by the function Ex_FS_FileMultiDesc() called from your application task

  • Writer task writes a few logical blocks to the file and starts the Reader task

  • Reader task reads N logical blocks from the specified file and verifies the read data integrity

Location#

The example implementation is located in:

  • /examples/fs/ex_fs_file_multi_desc.c

  • /examples/fs/ex_fs_file_multi_desc.h

The following files are also required:

  • /examples/fs/ex_fs.c

  • /examples/fs/ex_fs.h

  • /examples/fs/ex_fs_utils.h

API#

This example offers only one API named Ex_FS_FileMultiDesc(). This function performs the different example steps mentioned in the section Description . The function can be called by your application task by including the associated header file ex_fs_file_multi_desc.h.

Entry Path Example#

Description#

This example shows how to open directories and working directories and to use them to navigate a folder tree structure. This example will allow you to accomplish the following tasks:

  • Create a predefined directory/file tree structure

  • Read each entry (sub-directory or file) of each directory of the predefined tree structure using absolute paths

  • Create a working directory associated with a specific directory of the predefined tree structure

  • Read each entry in the directory pointed to by the working directory

  • Create a working directory pointing to the virtual root directory

  • Read each entry of virtual root directory

When using working directories, any path specified with a working directory handle is considered as relative. This is in contrast to absolute paths, which use a NULL working directory handle.

A virtual root directory refers to the media name level. Let's assume for instance the following generic path to a directory:

"nand0/<vol-name>/<root-dir-name>/<sub-dir-name>/<sub-dir-name>/<sub-dir-name>/"

The virtual root directory is "nand0". Thus when reading the virtual directory with FSDir_Rd() , the entry obtained will be a volume name. The volume must have been open with FSVol_Open() prior to reading the virtual root directory. Otherwise no entry is available from the virtual root directory. If several volumes have been open on the same media because it has multiple partitions, several calls to FSDir_Rd() will return all the open volumes.

Configuration#

EX_CFG_FS_ENTRY_PATH_MORE_INFO_EN#

The file ex_fs_entry_path.c offers a local configuration, allowing more messages to be displayed when executing the example: EX_CFG_FS_ENTRY_PATH_MORE_INFO_EN.

When enabled, the full entry path will be displayed for each directory entry read with FSDir_Rd() . If the media read contains plenty of files and folders in the root directory, the output console displaying messages may be flooded.

The configuration can have the following values: DEF_DISABLED or DEF_ENABLED. By default, this configuration is set to DEF_DISABLED to keep the number of messages to a minimum.

Location#

The example implementation is located in:

  • /examples/fs/ex_fs_entry_path.c

  • /examples/fs/ex_fs_entry_path.h

The following files are also required:

  • /examples/fs/ex_fs.c

  • /examples/fs/ex_fs.h

  • /examples/fs/ex_fs_utils.h

API#

This example offers only one API named Ex_FS_EntryPath(). This function performs the different example steps mentioned in the section Description . The function can be called by your application task by including the associated header file ex_fs_entry_path.h.

Block Device Read/Write Example#

Description#

This example shows how to perform raw media accesses using the Block Device API. This example does not pass through the Core layer; it goes directly via the Storage layer. It will allow you to accomplish the following tasks:

  • Write some known data in the N first sectors

  • Read data back from the N first sectors

  • Verify the read data integrity

You should run this example with extra care. The Storage layer is not aware of the file system formatting on the media. The example writes in the first media sectors. Thus any file system formatting information contained in some sectors may be corrupted. The directories and files may also be corrupted. If the media was formatted and the example is executed, you must re-format the media so that other examples (for instance file read/write, file multi-descriptors, etc.) can be run. Refer to section Configuration for more details about low-level and high-level formats in case of media reformatting.

Location#

The example implementation is located in:

  • /examples/fs/ex_fs_blk_dev_rd_wr.c

  • /examples/fs/ex_fs_blk_dev_rd_wr.h

The following files are also required:

  • /examples/fs/ex_fs.c

  • /examples/fs/ex_fs.h

  • /examples/fs/ex_fs_utils.h

API#

This example offers only one API named Ex_FS_BlkDevRdWr(). This function performs the different example steps mentioned in the section Description . The function can be called by your application task by including the associated header file ex_fs_blk_dev_rd_wr.h.

Media Polling Example#

Description#

This example shows how removable media are detected by the Media Poll task (part of the Storage layer), and how an application connection or disconnection callback is called. This example will allow you to accomplish the following tasks:

  • Display information about a removable media upon its connection

  • Notify an application task about the removable media connection. The task will:

    • Open a block device and a FAT volume on the removable media

    • Perform once the File Read/Write example. The steps of the File Read/Write example are described in section Description

    • Close the volume and the block device

  • Display information about the removable media upon its disconnection

The Media Polling example defines the following application callbacks:

  • Ex_FS_MediaPollOnConn() called by the File System stack upon connection of a removable media

  • Ex_FS_MediaPollOnDisonn() called by the File System stack upon disconnection of a removable media

This example targets the SD cards and SCSI devices considered as removable devices. Note that if some fixed media such NAND, NOR and RAM are available, the connection callback will be called only once for those devices. The disconnection callback will never be called for fixed media. When the connection callback is called, some useful information about SD or SCSI devices is displayed.

This example uses the asynchronous handling of the removable media connection/disconnection. You can refer to the page Managing Removable Media for more details about removable media management within Micrium OS File System.

Location#

The example implementation is located in:

  • /examples/fs/ex_fs_media_poll.c

  • /examples/fs/ex_fs_media_poll.h

The following files are also required:

  • /examples/fs/ex_fs.c

  • /examples/fs/ex_fs.h

  • /examples/fs/ex_fs_utils.h

  • /examples/fs/ex_fs_file_rd_wr.c

  • /examples/fs/ex_fs_file_rd_wr.h

API#

This example does not offer any public API. You don't have to call the example from your application task. When calling the function Ex_FS_Init() corresponding to the File System Module Initialization example , some pieces of code will help initialize the Media Polling example. From that point on, the example is independent of any application function, as opposed to the other examples. Thanks to the Media Poll task, the application connection/disconnection callbacks are called appropriately, and the File Read/Write example is executed on the connected media. The Media Poll task is activated via FS_STORAGE_CFG_MEDIA_POLL_TASK_EN defined in fs_storage_cfg.h. If the Media Poll task is disabled, the application connection/disconnection callbacks will still be called when a SCSI device connects. Refer to section SCSI for more details about why SCSI does not need the Media Poll task to work.

If SCSI is available, the Micrium OS USB Host stack and the MSC class must also be present. In the file rtos_description.h, the following #defines must be defined: RTOS_MODULE_USB_HOST_AVAIL and RTOS_MODULE_USB_HOST_MSC_AVAIL. The SCSI storage driver works with a Transport layer that transfer SCSI commands to the device. The recommended Transport layer for File System SCSI is the USB Host MSC class.