Documentation: clean-up FileSystem source formatting, improve wording…

… and clean-up text (#61)

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}
 

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

Documentation/Doxygen/FileSystem/src/example_file_demo.md

@@ -18,26 +18,27 @@ 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.
 
 <h2>Software Components Configuration Files</h2>
 
 Configuration files for the software components used in the project are available in the `./RTE/` directory and can be modified by users to adjust the operation of related components.
 
 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.
 
 <h2>Board Layer</h2>
 
 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

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.
+
+- \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.

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
       //     <s>Section Name
       //     <i>Define the name of the section for the drive cache and drive buffers.
       //     <i>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
      //     <s>Section Name
      //     <i>Define the name of the section for the file system buffer.
      //     <i>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.