diff --git a/Documentation/Doxygen/FileSystem/src/FileSystem.md b/Documentation/Doxygen/FileSystem/src/FileSystem.md index b0c94b4c..aa604be8 100644 --- a/Documentation/Doxygen/FileSystem/src/FileSystem.md +++ b/Documentation/Doxygen/FileSystem/src/FileSystem.md @@ -19,7 +19,7 @@ The File System Component is structured as follows: - Flash chips (\ref nand_usage "NAND", \ref nor_usage "NOR") - Memory card interfaces (\ref mc_usage "SD/SDxC/MMC/eMMC") - \ref usb_usage "USB devices" - - On-chip \ref ram_usage "RAM", Flash and external memory interfaces. + - On-chip \ref ram_usage "RAM", Flash and external memory interfaces. ## Documentation Structure {#doc_structure} diff --git a/Documentation/Doxygen/FileSystem/src/create_app.md b/Documentation/Doxygen/FileSystem/src/create_app.md index 47fbf488..abc21e46 100644 --- a/Documentation/Doxygen/FileSystem/src/create_app.md +++ b/Documentation/Doxygen/FileSystem/src/create_app.md @@ -2,8 +2,7 @@ The steps to create a microcontroller application that uses the File System are: --# Select \ref RTE_Component_Selection "RTE Components" along with other components that are - required for your application. +-# Select \ref RTE_Component_Selection "RTE Components" along with other components that are required for your application. -# Configure the \ref fs_configuration "File System". -# Configure the \ref hw_configuration "hardware". -# Implement the \ref User_Code_Implementation "User Code". @@ -16,16 +15,14 @@ Only a few steps are necessary to complete the RTE Component selection: -# From the **File System** Component: - Select **File System:CORE** that provides the basic functionality required for data storage and access. - Select your desired **File System:Drive**. \ref fs_drives gives more details. --# From the **CMSIS Driver** Component select an appropriate driver suitable for your **drive**. \ref fs_drives gives more - details. --# From the **CMSIS-Compiler** Component select **CORE** and **File Interface:MDK-MW File System** to provide - interface for the Standard C Library functions. +-# From the **CMSIS Driver** Component select an appropriate driver suitable for your **drive**. \ref fs_drives gives more details. +-# From the **CMSIS-Compiler** Component select **CORE** and **File Interface:MDK-MW File System** to provide interface for the Standard C Library functions. -# From the **Device** Component: - Additional device specific drivers may be required according to the validation output. -# From the CMSIS Component: - Select the **CMSIS:CORE** to provide the core interface to the processor. - Select a suitable **CMSIS:RTOS** that is a required for the File System Component. - + ![RTE Component for File System](fs_rte_comp_selection.png) ## Using Drives {#fs_drives} @@ -35,18 +32,18 @@ The section \ref drive shows the relationship between drive - memory device - an ### NOR Flash Drive {#nor_usage} For using a NOR Flash drive, a \urlout{Flash-API} driver is required, which encapsulates either the Memory Bus interface or SPI (in which case an \urlout{SPI-API} driver is required in addition): + - Set **File System:Drive:NOR** to at least '1' to use a NOR Flash drive (independently if it is using a memory bus or SPI interface). -- From the **CMSIS-Driver** Component, select an appropriate **Flash (API)** device. If your NOR Flash uses an SPI - interface, select **SPI (API)** additionally. +- From the **CMSIS-Driver** Component, select an appropriate **Flash (API)** device. If your NOR Flash uses an SPI interface, select **SPI (API)** additionally. + +If your NOR Flash device is not listed, use one of the examples as a reference to implement a driver for your specific device: -If your NOR Flash device is not listed, use one of the examples as a reference to implement a driver for your specific -device: - AM29x800BB/[M29W640FB](https://www.farnell.com/datasheets/40281.pdf) (Flash with 16-bit memory bus interface) -- [S29GL064Nx2](https://www.infineon.com/dgdl/Infineon-S29GL064N_S29GL032N_64_Mbit_32_Mbit_3_V_Page_Mode_MirrorBit_Flash-DataSheet-v03_00-EN.pdf?fileId=8ac78c8c7d0d8da4017d0ed556fd548b) (Flash with 32-bit -memory bus interface) -- [AT45DB642D](https://datasheet.octopart.com/AT45DB642D-CNU-Atmel-datasheet-9652374.pdf) (Flash with SPI interface using an SPI -driver) +- [S29GL064Nx2](https://www.infineon.com/dgdl/Infineon-S29GL064N_S29GL032N_64_Mbit_32_Mbit_3_V_Page_Mode_MirrorBit_Flash-DataSheet-v03_00-EN.pdf?fileId=8ac78c8c7d0d8da4017d0ed556fd548b) +(Flash with 32-bit memory bus interface) +- [AT45DB642D](https://datasheet.octopart.com/AT45DB642D-CNU-Atmel-datasheet-9652374.pdf) +(Flash with SPI interface using an SPI driver) ![Flash (API) Drivers shipped with the Middleware Component](fs_flash_drivers.png) @@ -78,11 +75,12 @@ Set the drive characteristics in the `FS_Config_MC_n.h` file: ![Memory Card Drive Configuration File](fs_config_mc_0_h.png) -\note -- If your microcontroller device does not have a **CMSIS-Driver** for the **MCI (API)** or **SPI (API)**, you can try - to develop your own one based on the \urlout{CMSIS-Driver-Ref} documentation. -- The page \ref mc_control_layer lists all supported memory card types and gives further details on how to use these cards. -- General \ref system_configuration requirements apply. +> **Note** +> +> - If your microcontroller device does not have a **CMSIS-Driver** for the **MCI (API)** or **SPI (API)**, you can try +> to develop your own one based on the \urlout{CMSIS-Driver-Ref} documentation. +> - The page \ref mc_control_layer lists all supported memory card types and gives further details on how to use these cards. +> - General \ref system_configuration requirements apply. ### USB Flash Drive {#usb_usage} @@ -94,11 +92,12 @@ Set the drive characteristics in the `FS_Config_USB_n.h` file: ![USB Host Mass Storage Class Drive Configuration File](fs_config_usb_0_h.png) -\note -- If your microcontroller device does not have a **CMSIS-Driver** for the **USB Host (API)**, you can try to develop - your own one based on the - \urlout{CMSIS-Driver-Ref} documentation. -- General \ref system_configuration requirements apply. +> **Note** +> +> - If your microcontroller device does not have a **CMSIS-Driver** for the **USB Host (API)**, you can try to develop +> your own one based on the +> \urlout{CMSIS-Driver-Ref} documentation. +> - General \ref system_configuration requirements apply. ### NAND Flash Drive {#nand_usage} @@ -109,13 +108,14 @@ Set the drive characteristics in the `FS_Config_NAND_n.h` file: ![NAND Flash Drive Configuration File](fs_config_nand_0_h.png) -\note -- If your microcontroller device does not have a **CMSIS-Driver** for the **NAND (API)**, you can try to develop your - own one based on the \urlout{CMSIS-Driver-Ref} documentation. -- The page \ref nand_flash_TL describes additional features specific to these devices. -- Using a **NAND (API)** driver, you can use any NAND Flash device with an 8-/16-bit memory bus interface for data storage. -- NAND Flashes with SPI interface (Serial NAND) are currently *not supported* by the File System Component. -- General \ref system_configuration requirements apply. +> **Note** +> +> - If your microcontroller device does not have a **CMSIS-Driver** for the **NAND (API)**, you can try to develop your +> own one based on the \urlout{CMSIS-Driver-Ref} documentation. +> - The page \ref nand_flash_TL describes additional features specific to these devices. +> - Using a **NAND (API)** driver, you can use any NAND Flash device with an 8-/16-bit memory bus interface for data storage. +> - NAND Flashes with SPI interface (Serial NAND) are currently *not supported* by the File System Component. +> - General \ref system_configuration requirements apply. ## File System Configuration {#fs_configuration} @@ -137,6 +137,7 @@ requirements of your target device. This configuration is done in the `RTE_Devic ## System Resource Configuration {#system_configuration} For proper operation, the File System Component requires some system configuration settings. The requirements are: + - Minimum **heap size of 512 + 96 Bytes for each opened file**. If you want to be able to have three files open at the same time, you need to set a heap size of at least 3 * (512+96) Bytes = 1824 Bytes. This can be configured in the device's `startup_device.s` file (`Heap_Size`). @@ -173,6 +174,7 @@ of the File System Component during application debug. The \ref evr_gr describes The File System Component generates \ref evr_gr "a broad set of Debug Events" for the Event Recorder and implements required infrastructure to interface with it. To use the Event Recorder it is required to create an image with event generation support. The necessary steps are: + 1. \urlout{Event-Recorder-Enable}: in the RTE management dialog enable the software component **CMSIS-View:Event Recorder**. 2. Ensure that Event Recorder is initialized preferably by \urlout{RTX5-Event-Recorder-Config} if CMSIS-RTOS2 RTX v5 is used, or alternatively by calling the function \urlout{Event-Recorder-Initialize-Func} in the application code. @@ -194,6 +196,7 @@ generation configuration for File System core and drivers separately. ![FS_Debug.h file for event generation configuration](fs_debug_h.png) The following settings are available for event generation configuration of each module: + - **Off** means no events will be generated by the module - **Errors** means only error events will be generated by the module - **Errors + API** means error and API call events will be generated by the module diff --git a/Documentation/Doxygen/FileSystem/src/example_file_demo.md b/Documentation/Doxygen/FileSystem/src/example_file_demo.md index 57d022ed..5b4bfd9b 100644 --- a/Documentation/Doxygen/FileSystem/src/example_file_demo.md +++ b/Documentation/Doxygen/FileSystem/src/example_file_demo.md @@ -18,7 +18,7 @@ The File Demo project is available as part of the \ref examples "File System Ref Following files implement application-specific logic in the example: - - `File_Demo.c` contains the main application thread and implementation of commands for user interaction. +- `File_Demo.c` contains the main application thread and implementation of commands for user interaction.

Software Components Configuration Files

@@ -26,18 +26,19 @@ Configuration files for the software components used in the project are availabl Following configuration files are provided with this example: - - For the File System component, in the `./RTE/File_System/` folder: - - `FS_Config.h`: \ref fs_configuration "File System configuration". - - `FS_Config_MC_0.h`: \ref mc_usage "File System Memory Card configuration". - - `FS_Debug.h`: \ref fsEvrConfig "File System Debug configuration". - - For the CMSIS components, in the `./RTE/CMSIS/` folder: - - `RTX_Config.h` and `RTX_Config.c`: [CMSIS-RTX Configuration files](https://arm-software.github.io/CMSIS-RTX/latest/config_rtx5.html) for the RTOS Kernel. +- For the File System component, in the `./RTE/File_System/` folder: + - `FS_Config.h`: \ref fs_configuration "File System configuration". + - `FS_Config_MC_0.h`: \ref mc_usage "File System Memory Card configuration". + - `FS_Debug.h`: \ref fsEvrConfig "File System Debug configuration". +- For the CMSIS components, in the `./RTE/CMSIS/` folder: + - `RTX_Config.h` and `RTX_Config.c`: [CMSIS-RTX Configuration files](https://arm-software.github.io/CMSIS-RTX/latest/config_rtx5.html) for the RTOS Kernel. When a board layer is added to the project, corresponding configuration files for the board and device components will become available in the local `./Board/` directory.

Board Layer

In order to build the project it shall be extended with a compatible board layer that provides following interfaces as [connections](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/ReferenceApplications.md#connections): + - `CMSIS_MCI`: CMSIS-Driver for Memory Card Interface - `CMSIS_VIO`: CMSIS-Driver for Virtual I/O interface - `STDIN`: Standard Input redirection diff --git a/Documentation/Doxygen/FileSystem/src/examples.md b/Documentation/Doxygen/FileSystem/src/examples.md index 48e657a9..05e6a75c 100644 --- a/Documentation/Doxygen/FileSystem/src/examples.md +++ b/Documentation/Doxygen/FileSystem/src/examples.md @@ -3,7 +3,8 @@ The File System Component is used in many different applications and examples. One stand-alone example is available to demonstrate the usage of the File System. Other examples use the File System Component in conjunction with other Components (such as USB or Network for example). - - \subpage File_Demo_Example shows the basic functionality of the File System. - - [USB Device Mass Storage](../USB/usbd_example_msc.html) shows how to create an USB MSC Device that is recognized by an USB Host controller. - - [USB Host Mass Storage](../USB/usbh_example_msc.html) explains how to access file system data from an attached USB memory device. - - [FTP Server](../Network/FTP_Server_Example.html) accesses the device's file system via a network connection. \ No newline at end of file + +- \subpage File_Demo_Example shows the basic functionality of the File System. +- [USB Device Mass Storage](../USB/usbd_example_msc.html) shows how to create an USB MSC Device that is recognized by an USB Host controller. +- [USB Host Mass Storage](../USB/usbh_example_msc.html) explains how to access file system data from an attached USB memory device. +- [FTP Server](../Network/FTP_Server_Example.html) accesses the device's file system via a network connection. diff --git a/Documentation/Doxygen/FileSystem/src/migration_guide.md b/Documentation/Doxygen/FileSystem/src/migration_guide.md index 059ba042..ff7a9896 100644 --- a/Documentation/Doxygen/FileSystem/src/migration_guide.md +++ b/Documentation/Doxygen/FileSystem/src/migration_guide.md @@ -13,14 +13,16 @@ get selected. 1. Bundle **MDK** has replaced bundles **MDK-Pro** and **MDK-Plus** Where applicable replace components: - ``` + + ```txt Keil::File System&MDK-Pro or Keil::File System&MDK-Plus ``` with components that reference bundle **MDK**: - ``` + + ```txt Keil::File System&MDK ``` @@ -30,12 +32,14 @@ get selected. migrating from Compiler to CMSIS-Compiler components is straightforward. To migrate your project replace component: - ``` + + ```txt Keil::Compiler::I/O:File&File System ``` with components from CMSIS-Compiler class: - ``` + + ```txt ARM::CMSIS-Compiler:CORE and ARM::CMSIS-Compiler:File Interface:MDK-MW File System @@ -44,7 +48,8 @@ get selected. Components from **Compiler** and **CMSIS-Compiler** are incompatible and cannot coexist hence all other components from Compiler class must also be migrated to components from CMSIS-Compiler: Migrate components: - ``` + + ```txt Keil::Compiler:I/O:STDERR&{Cvariant} -> ARM::CMSIS-Compiler:STDERR:{Csub} Keil::Compiler:I/O:STDIN&{Cvariant} -> ARM::CMSIS-Compiler:STDIN:{Csub} Keil::Compiler:I/O:STDOUT&{Cvariant} -> ARM::CMSIS-Compiler:STDOUT:{Csub} @@ -54,12 +59,14 @@ get selected. 3. **Event Recorder** component is now part of **CMSIS-View** class If your project is configured for debugging then you need to replace component: - ``` + + ```txt Keil::Compiler:Event Recorder ``` with component from CMSIS-View class: - ``` + + ```txt ARM::CMSIS-View:Event Recorder ``` @@ -71,9 +78,11 @@ how File System gets configured. 1. The core configuration has been moved from C source file to C header file To migrate configuration of an existing project use compare/merge tool on the following files: - ``` + + ```txt FS_Config.c and FS_Config.h ``` + > Note: FS_Config.h does not have configuration for Initial Current Drive anymore. To understand how current drive is set see chapter \ref cur_sys_drive. 2. Drive configuration changed the way how drive cache and drive buffer placement works @@ -83,7 +92,8 @@ how File System gets configured. The latest drive configuration files contain a define named **_CACHE_SECTION** where one can define the section name. For example: - ``` + + ```txt // Section Name // Define the name of the section for the drive cache and drive buffers. // Linker script shall have this section defined. @@ -93,10 +103,12 @@ how File System gets configured. When using RAM drive one can move the file system data buffer (buffer that holds directories, files and files content) into a specific memory. The latest drive configuration file supports this by using define **_SECTION**. The define for RAM drive 0 looks like shown below: - ``` + + ```txt // Section Name // Define the name of the section for the file system buffer. // Linker script shall have this section defined. #define RAM0_SECTION ".filesystem.ram0" ``` + To migrate configuration of an existing project use compare/merge tool on drive configuration files and update toolchain linker script to support defined sections. diff --git a/Documentation/Doxygen/FileSystem/src/operation.md b/Documentation/Doxygen/FileSystem/src/operation.md index bb25b815..324ee0d0 100644 --- a/Documentation/Doxygen/FileSystem/src/operation.md +++ b/Documentation/Doxygen/FileSystem/src/operation.md @@ -7,6 +7,7 @@ processor-based devices and requires an CMSIS-RTOS compliant real-time operating for thread-safe operation. The File System Component consists of two different file systems, placed on top of different layers, depending on the media type: + - \ref fat_fs (using FAT12, FAT16, or FAT32) is used for \ref mc_usage "memory card" devices, \ref usb_usage "USB Memory sticks", \ref nand_usage "NAND Flash" devices, and \ref ram_usage "RAM disks". FAT is a standard file system used on many computers. @@ -39,6 +40,7 @@ The following picture shows the File System's structure from a developer's persp - **Drivers** The File System Core accesses the drives via CMSIS-Drivers that are typically part of the Device Family Pack. Every drive uses dedicated driver. The configuration steps and files that are needed to create applications for the different devices are explained here: + - \ref nor_usage - \ref ram_usage - \ref mc_usage @@ -61,31 +63,32 @@ CMSIS-Drivers. The following table shows the relationship between drive - memory |Drive |File System |Drive Type | CMSIS-Driver/Interface| |:------------|:----------------:|:-----------------------------------|-----------------------| -|"F:" or "F0:"|\ref emb_fs "EFS" |NOR Flash drive 0 | \urlout{Flash-API} (Memory Bus or \urlout{SPI-API} | -|"F1:" |\ref emb_fs "EFS" |NOR Flash drive 1 | \urlout{Flash-API} (Memory Bus or \urlout{SPI-API} | +|"F:" or "F0:"|\ref emb_fs "EFS" |NOR Flash drive 0 | \urlout{Flash-API} (Memory Bus or \urlout{SPI-API}) | +|"F1:" |\ref emb_fs "EFS" |NOR Flash drive 1 | \urlout{Flash-API} (Memory Bus or \urlout{SPI-API}) | |"R:" or "R0:"|\ref fat_fs "FAT" |RAM drive | N/A | |"M:" or "M0:"|\ref fat_fs "FAT" |Memory Card drive 0 | \urlout{MCI-API} or \urlout{SPI-API} | |"M1:" |\ref fat_fs "FAT" |Memory Card drive 1 | \urlout{MCI-API} or \urlout{SPI-API} | |"U:" or "U0:"|\ref fat_fs "FAT" |USB Memory Stick drive 0 | \urlout{USB-API} | |"U1:" |\ref fat_fs "FAT" |USB Memory Stick drive 1 | \urlout{USB-API} | |"N:" or "N0:"|\ref fat_fs "FAT" |NAND Flash drive 0 | \urlout{NAND-API} (Memory Bus) | -|"N1:" |\ref fat_fs "FAT" |NAND Flash drive 1 | \urlout{NAND-API} (Memory Bus) | - -\note -- NOR Flash is typically connected over Memory Bus or SPI. For using a NOR Flash drive, a Flash driver is required which - encapsulates either the Memory Bus interface or SPI (in which case an SPI driver required in addition). -- The Middleware Component contains example drivers for Flash devices that can be used to implement other device drivers if - required. The examples are: - AM29x800BB/[M29W640FB](https://www.farnell.com/datasheets/40281.pdf) - (Flash with 16-bit memory bus interface), - [S29GL064Nx2](https://www.infineon.com/dgdl/Infineon-S29GL064N_S29GL032N_64_Mbit_32_Mbit_3_V_Page_Mode_MirrorBit_Flash-DataSheet-v03_00-EN.pdf) (Flash with 32-bit - memory bus interface), and - [AT45DB642D](https://datasheet.octopart.com/AT45DB642D-CNU-Atmel-datasheet-9652374.pdf) (Flash with SPI interface using an SPI - driver). -- Other drives (memory card, USB memory device, NAND Flash) require appropriate CMSIS-Driver for the microcontroller - device. If no suitable CMSIS-Driver is available for your selected device, you may create the required Flash interface - driver. Refer to the \urlout{CMSIS-Driver-Ref} for details. -- Currently, using NAND Flash devices with SPI interface (Serial NAND) *is not supported*. +|"N1:" |\ref fat_fs "FAT" |NAND Flash drive 1 | \urlout{NAND-API} (Memory Bus) | + +> **Note** +> +> - NOR Flash is typically connected over Memory Bus or SPI. For using a NOR Flash drive, a Flash driver is required which +> encapsulates either the Memory Bus interface or SPI (in which case an SPI driver required in addition). +> - The Middleware Component contains example drivers for Flash devices that can be used to implement other device drivers if +> required. The examples are: +> AM29x800BB/[M29W640FB](https://www.farnell.com/datasheets/40281.pdf) +> (Flash with 16-bit memory bus interface), +> [S29GL064Nx2](https://www.infineon.com/dgdl/Infineon-S29GL064N_S29GL032N_64_Mbit_32_Mbit_3_V_Page_Mode_MirrorBit_Flash-DataSheet-v03_00-EN.pdf) (Flash with 32-bit +> memory bus interface), and +> [AT45DB642D](https://datasheet.octopart.com/AT45DB642D-CNU-Atmel-datasheet-9652374.pdf) (Flash with SPI interface using an SPI +> driver). +> - Other drives (memory card, USB memory device, NAND Flash) require appropriate CMSIS-Driver for the microcontroller +> device. If no suitable CMSIS-Driver is available for your selected device, you may create the required Flash interface +> driver. Refer to the \urlout{CMSIS-Driver-Ref} for details. +> - Currently, using NAND Flash devices with SPI interface (Serial NAND) *is not supported*. ### Current Drive {#cur_sys_drive} @@ -97,9 +100,10 @@ when there are multiple drives enabled, the one with the drive letter that is fi set as the "Current Drive". The \ref cur_sys_drive "Current Drive" can be changed during run-time using the function \ref fchdrive. -\note -- Define `FS_INITIAL_CDRIVE` can be used to define initial current drive at build time. -- Set `FS_INITIAL_CDRIVE` to one of the following values: 0(F0), 1(F1), 2(M0), 3(M1), 4(N0), 5(N1), 6(R0), 9(R1), 7(U0), 8(U1) +> **Note** +> +> - Define `FS_INITIAL_CDRIVE` can be used to define initial current drive at build time. +> - Set `FS_INITIAL_CDRIVE` to one of the following values: 0(F0), 1(F1), 2(M0), 3(M1), 4(N0), 5(N1), 6(R0), 9(R1), 7(U0), 8(U1) ## FAT File System {#fat_fs} @@ -122,6 +126,7 @@ bits: **FAT12**, **FAT16**, and **FAT32**. Each of these variants is is supporte ### Layout {#fat_layout} The actual FAT file system is made up of four different sections: + |Section |Description | |:--------------------|:--------------------------------------------------------------------------------------------------| |Boot sector |Contains machine startup code | @@ -168,16 +173,16 @@ File System Component is provided with the long (LFN) and short (SFN or 8.3) fil Since there is no compulsory algorithm for creating the 8.3 name from an LFN, File System Component uses convention described below. -- Uppercased or lowercased name which is 8.3 valid, is stored uppercased in a single SFN entry +- The name in uppercase or lowercase, which is 8.3 valid, is stored in uppercase in a single SFN entry - Example: "TEXTFILE.TXT" is stored as "TEXTFILE.TXT" (SFN) - Example: "textfile.txt" is stored as "TEXTFILE.TXT" (SFN) -- Mixedcase name which is 8.3 valid, is stored mixed-case in LFN entry and SFN entry is created, +- A mixed-case name, which is 8.3 valid, is stored as mixed-case in LFN entry and SFN entry is created, which is concluded with tilde and a numeric value. - Example: "TextFile.txt" is stored as "TextFile.txt" (LFN) and "TEXTFI~1.TXT" (SFN) -- Name which is not 8.3 valid is stored in LFN entry and SFN entry. Name writen in SFN entry - is uppercased, stripped of invalid 8.3 characters which are replaced with underscore "_" and +- Name which is not 8.3 valid is stored in LFN entry and SFN entry. Name written in SFN entry + is in uppercase, stripped of invalid 8.3 characters, which are replaced with underscore "_" and concluded with tilde and a numeric value. - Example: "Tex+File.txt" is stored as "Tex+File.txt" (LFN) and "TEX_FI~1.TXT (SFN)" @@ -201,13 +206,13 @@ stamps are used. The File System Component supports a proprietary [journaling](https://en.wikipedia.org/wiki/Journaling_file_system) mechanism for FAT which makes file I/O functions robust against system crashes or power failures. When FAT Journaling is enabled, the file -allocation table and directory entries are protected. +allocation table and directory entries are protected. **FAT Journaling** keeps track of the changes in the file system using a **journal** before committing them to the main file system. In the event of a system failure, file system does not become corrupted. Only content of files that are opened in writing mode may be lost. Other files are not affected. -Journaling can be enabled individually for each drive that is using the FAT File System. +Journaling can be enabled individually for each drive that is using the FAT File System. For information on how to enable Journaling refer to: - \ref mc_usage @@ -224,26 +229,26 @@ There requirements for creating a **journal** are: If journaling is enabled, mounting a drive triggers the File System to search for the journal. When journal is found the journaling system is initialized and the journal content is checked for any -incomplete data transactions that may be the result of a system crash. When incomplete data transactions +incomplete data transactions that may be the result of a system crash. When incomplete data transactions are found the file system restores the drive to the last known valid state. -When no journal is found, the journal is automatically created. -The required space (32kB) for journal is reserved by marking the adequate amount of clusters +When no journal is found, the journal is automatically created. +The required space (32kB) for journal is reserved by marking the adequate amount of clusters in the last 1% of the drive partition. This reduces the reported amount of free space on the drive accordingly. -No special drive formatting is required. When a drive is formatted on a different computer +No special drive formatting is required. When a drive is formatted on a different computer (running Window or Linux) free space is typical available at the end of a partition. -Creation of a journal may fail on removable media when above requirements are not meet. -This may happen if the drive is fragmented or there is not enough space. In this case the +Creation of a journal may fail on removable media when above requirements are not meet. +This may happen if the drive is fragmented or there is not enough space. In this case the drive should be defragmented or some files should be deleted. -When using the \ref fformat function of the File System Component, the journal is automatically created on drives with +When using the \ref fformat function of the File System Component, the journal is automatically created on drives with enabled option "Use FAT Journal". #### System failure behavior {#sys_fail_beh} When File System Component experiences a power loss or crashes before a file opened for writing is -successfully closed the content of that file is lost. This results in lost data clusters which +successfully closed the content of that file is lost. This results in lost data clusters which can be restored using a file system repair utility tool such as chkdsk on Windows or fsck on Linux. ### FAT System Design Limitations {#fat_sys_design_limitations} @@ -316,7 +321,7 @@ With appropriately designed hardware and support from the corresponding MCI driv device power supply voltage: - VDD (VCC) and VCCQ power supply is turned **on** when device is \ref fmount "mounted" -- VDD (VCC) and VCCQ power supply is turned **off** when device is \ref funmount "unmounted", +- VDD (VCC) and VCCQ power supply is turned **off** when device is \ref funmount "unmounted", - VCC power supply is turned **on/off** when eMMC device is **switched to/from Sleep state** #### Data Bus Width @@ -371,6 +376,11 @@ When operation executes successfully, password is cleared from device registers. When operation executes successfully, data access protection is activated. All read/write accesses are rejected. +> **Note** +> It is possible to set password and lock the card in a single step: +> +> - define set password and lock the card operation by setting member `.flags` to (\ref FS_DEVICE_SET_PASSWORD | \ref FS_DEVICE_LOCK_UNLOCK) + **Unlock the card:** - assign password buffer to member `.password` @@ -386,16 +396,12 @@ When operation executes successfully, data access protection is deactivated. All When operation executes successfully, all the card data content is erased along with the current password. -\note -It is possible to set password and lock the card in a single step: - -- define set password and lock the card operation by setting member `.flags` to (\ref FS_DEVICE_SET_PASSWORD | \ref FS_DEVICE_LOCK_UNLOCK) - -\note -- SD and MMCA specification also allows to replace the password in a single step. This is not supported by the FileSystem library, - since it is known that various devices have issues with the interpretation of this operation. Therefore, when changing the password, - old one must be first cleared and then new password can be set. -- Is is also recommended to unlock the device before resetting the password. +> **Note** +> +> - SD and MMCA specification also allows to replace the password in a single step. This is not supported by the FileSystem library, +> since it is known that various devices have issues with the interpretation of this operation. Therefore, when changing the password, +> old one must be first cleared and then new password can be set. +> - Is is also recommended to unlock the device before resetting the password. To successfully \ref fmount "mount" locked memory card and gain read/write data access, password management information must be provided from the user application: @@ -475,7 +481,7 @@ by PCB design. To overcome this problem, FileSystem component implements simple determine the maximum bus frequency at which it is still possible to communicate with the memory card. FileSystem component will always attempt to set the highest bus frequency supported by the memory card (usually 25MHz) but if -after that the memory card is not accessible anymore I will lower the bus frequency. The adaptation is performed only during +after that the memory card is not accessible anymore I will lower the bus frequency. The adaptation is performed only during memory card initialization procedure. \cond This_should_be_done_later @@ -490,7 +496,7 @@ memory card initialization procedure. It should be similar to old performance table (\refrlarm{fs_technical_data}, but with updated measurements. \endcond -## NAND Flash Translation Layer {#nand_flash_TL} +## NAND Flash Translation Layer {#nand_flash_TL} **Features** @@ -563,7 +569,7 @@ the data is written, added to the spare area of the page and then stored in flas redundant information is recalculated and compared to those stored in the flash. Error correction codes (ECC) used in the NAND flash memory are block codes. This means that the redundant data bits are -calculated for a fixed size block of used data. NTFL is implementing a +calculated for a fixed size block of used data. NTFL is implementing a [Hamming](https://en.wikipedia.org/wiki/Hamming_code) ECC algorithm which is able to correct 1-bit and detect 2-bit errors for a fixed size of one sector or 512 bytes for SLC NAND Flashes. The redundant information is calculated in a way that a balance of correction power and efficiency is achieved. diff --git a/Documentation/Doxygen/FileSystem/src/resource_requirements.md b/Documentation/Doxygen/FileSystem/src/resource_requirements.md index 0f877c67..fc117b5b 100644 --- a/Documentation/Doxygen/FileSystem/src/resource_requirements.md +++ b/Documentation/Doxygen/FileSystem/src/resource_requirements.md @@ -1,49 +1,53 @@ # Resource Requirements {#resource_requirements} -This section describes the resource requirements of the **File System** component. +This section describes the resource requirements of the **File System** component. The actual requirements depend on the features used in the application. Therefore, the numbers provided here are guidelines -only and the actual numbers may differ. +only and the actual numbers may differ. ## Stack Requirements {#fs_stack_req} The File System component receives events sent from the interrupt service routine (ISR) of the drivers of the different -drives. The stack requirements for the ISR are typically less than 512 Bytes. The stack requirements for ISR are configured -in the `startup_device.s` file located under the **Device** component class. +drives. The stack requirements for the ISR are typically less than 512 Bytes. | Option (under section Stack Configuration) | Increase Value by | :---------------------------------------------------------------- | :---------------------- | Stack Size (in Bytes) | + 512 for Driver of a Drive -\note -- When using a CMSIS-RTOS, the Stack Size in the startup_*device*.s file configures only the stack space that is used by - exception and interrupt service routines of the drivers. The stack size requirements depend on the maximum nesting of - exception and ISR execution and therefore on the priority settings of the various interrupt and exception sources. -- If you have multiple drives configured in your system with the same interrupt priority, you only need to add the stack - of the drive with the largest requirement. If you have drives with nested interrupts (different priorities), you need to - add the sum of all stack requirements. - +> **Note** +> +> - Stack size for the ISRs is typically configured in the application `linker script` or device `startup_device.s`. +> - The stack size for the ISRs configures only the stack space that is used by exception and interrupt service routines +> of the drivers. The stack size requirements depend on the maximum nesting of exception and ISR execution and therefore +> on the priority settings of the various interrupt and exception sources. The stack size of the thread that calls +> FileSystem API function is configured in configuration file specific to the CMSIS-RTOS2 in use. +> - If you have multiple drives configured in your system with the same interrupt priority, you only need to add the stack +> of the drive with the largest requirement. If you have drives with nested interrupts (different priorities), you need to +> add the sum of all stack requirements. + ## Heap Requirements{#fs_heap_req} -Heap is used by memory allocation functions. It is also configured in the `startup_device.s` file located under the **Device** component class. -For every simultaneously opened file, you need to configure 512 + 96 Bytes of additional heap. If you wish to have three files open simultaneously, -you need to configure an additional heap size of 3 x (512 + 96) Bytes. +Heap is used by the standard C library memory allocation functions. The amount of heap required therefore depends on the +toolchain used to build the application image. The table below shows the heap requirements per simultaneously opened file. +If you wish to have three files open simultaneously, the value from the table must be multiplied by three. -| Option (under section Heap Configuration) | Increase Value by -| :---------------------------------------------------------------- | :---------------------- -| Heap Size (in Bytes) | + (512 + 96) for each open file +| Toolchain | Increase Value by +| :-------------- | :-------------------------------- +| Arm Compiler 6 | + (512 + 96) for each open file +| GCC | + (1024 + 64) for each open file + +> **Note** +> +> Heap is used to hold the file descriptor and file data buffer. The size of data buffer can be changed with function +> `setvbuf` which is part of the standard C library. ## CMSIS-RTOS Requirements {#fs_rtos_req} ### Thread Stack Requirements Although the File System component requires a CMSIS-RTOS to be present, it is not creating any additional threads. - -**Using CMSIS-RTOS RTX v5** - -The calling thread can be a thread with a default stack size (dynamic memory) or a thread with -a complete stack or only stack size provided using `osThreadAttr_t` structure (static or dynamic memory). - -For the additional required stack size, please refer to the following table: +Stack consumption depends greatly on the compiler optimization level. The table below shows approximate stack size +required by the FileSystem functions when compiled for production ready application with high optimization level. +For debugging purposes, with low or disabled optimization, the stack value should be increased. @@ -72,42 +76,15 @@ For the additional required stack size, please refer to the following table:
-\note -- The stack in bytes stated is required to work with the files from top level functions like fopen, fclose, …, fdelete, - frename and so on. -- The drivers for the different types of drives require additional stack. This differs from device to device, but in general - the stack usage for MCI, NAND, and Flash should not exceed additional 100 bytes. For USB drive, refer to \urlout{USB-Resource-Req} - for details. -- If your application supports a combination of multiple drives, you need to configure your system to the the combined stack - size for the sum of all drives. - -For \urlout{CMSIS-RTX5}, the threads requirements are configured in the \urlout{RTX-Conf-CM5} file located -under the **CMSIS** component class: - - - - - - - - - - - - - - - - - - - - - - - - -
Option (under section Thread Configuration)Increase Value by
Default Thread stack size [bytes]Stack size from table above
**or**
Main Thread stack size [bytes]Stack size from table above
**or**
Total stack size [bytes]for threads with user-provided stack sizeStack size from table above
+> **Note** +> +> - The stack in bytes stated is required to work with the files from top level functions like fopen, fclose, …, fdelete, +> frename and so on. +> - The drivers for the different types of drives require additional stack. This differs from device to device, but in general +> the stack usage for MCI, NAND, and Flash should not exceed additional 256 bytes. For USB drive, refer to \urlout{USB-Resource-Req} +> for details. +> - If your application supports a combination of multiple drives, you need to configure your system to the the combined stack +> size for the sum of all drives. ### Mutex Requirements @@ -115,14 +92,11 @@ Additionally, you may also need to adjust the memory used to allocate mutex obje Depending on the toolchain used, the total number of mutex objects required for proper operation may differ, but in general every active file stream requires a mutex object. -\note Arm Standard C Library requires the following mutexes: 2 (internal stdio operations) + 3 (stdin, stdout and stderr file streams) + 1 for each active file stream - -**Using CMSIS-RTOS RTX v5** - -Memory for mutex objects is allocated from the dynamic memory pool (RTX_Config.h - System Configuration - Global Dynamic -Memory size [bytes]). The size of dynamic memory pool must be configured so that the control blocks for the mutexes mentioned -above fit inside. The size of a control block for a mutex depends on the RTOS2 implementation. For RTX5 can be found in -rtx_os.h and is equal to the size of `osRtxMutex_t`. +> **Note** +> +> - Arm Standard C Library and GCC Newlib require the following mutexes: 2 (internal stdio operations) + 3 (stdin, stdout and stderr file streams) + 1 for each active file stream +> - [CMSIS-Compiler](https://github.com/ARM-software/CMSIS-Compiler) provides software component `OS Interface:CMSIS-RTOS2` that implements multithreading support +> across different toolchains when using CMSIS-RTOS2. It shall be used when file operation functions get called from multiple threads. ## Memory Requirements {#fs_spec_mem_req} @@ -130,7 +104,7 @@ The following table shows the memory requirements for read-only (Flash) and read These numbers may be used to estimate the total size requirements of the application, but the actual numbers depend on compiler optimizations and target processor and may be therefore slightly different. -| Component | RO Memory [Bytes] | RW Memory (Data) [Bytes] +| Component | RO Memory [Bytes] | RW Memory (Data) [Bytes] | :--------------------------------------------------- | :---------------: | :------------------------ | **C stdio Library** | < 5.0 k | < 0.3 k | **File System:Core** Common | < 3.5 k | 0