Update documentation for branch main

ARM-software · Oct 7, 2024 · cc5a7ae · cc5a7ae
1 parent 025611b
commit cc5a7ae
Show file tree

Hide file tree

Showing 11 changed files with 128 additions and 95 deletions.
diff --git a/main/FileSystem/File_Demo_Example.html b/main/FileSystem/File_Demo_Example.html
@@ -161,7 +161,8 @@ <h2>Software Components Configuration Files</h2>
 </ul>
 <p>When a board layer is added to the project, corresponding configuration files for the board and device components will become available in the local <code>./Board/</code> directory.</p>
 <h2>Board Layer</h2>
-<p>In order to build the project it shall be extended with a compatible board layer that provides following interfaces as <a href="https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/ReferenceApplications.md#connections">connections</a>:</p><ul>
+<p>In order to build the project it shall be extended with a compatible board layer that provides following interfaces as <a href="https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/ReferenceApplications.md#connections">connections</a>:</p>
+<ul>
 <li><code>CMSIS_MCI</code>: CMSIS-Driver for Memory Card Interface</li>
 <li><code>CMSIS_VIO</code>: CMSIS-Driver for Virtual I/O interface</li>
 <li><code>STDIN</code>: Standard Input redirection</li>

diff --git a/main/FileSystem/create_app.html b/main/FileSystem/create_app.html
@@ -166,11 +166,13 @@ <h1><a class="anchor" id="fs_drives"></a>
 <p>The section <a class="el" href="operation.html#drive">Drives, Memory Devices and Drivers</a> shows the relationship between drive - memory device - and driver/interface.</p>
 <h2><a class="anchor" id="nor_usage"></a>
 NOR Flash Drive</h2>
-<p>For using a NOR Flash drive, a  <script>link_ext('Flash-API');</script> driver is required, which encapsulates either the Memory Bus interface or SPI (in which case an  <script>link_ext('SPI-API');</script> driver is required in addition):</p><ul>
+<p>For using a NOR Flash drive, a  <script>link_ext('Flash-API');</script> driver is required, which encapsulates either the Memory Bus interface or SPI (in which case an  <script>link_ext('SPI-API');</script> driver is required in addition):</p>
+<ul>
 <li>Set <b>File System:Drive:NOR</b> to at least '1' to use a NOR Flash drive (independently if it is using a memory bus or SPI interface).</li>
 <li>From the <b>CMSIS-Driver</b> Component, select an appropriate <b>Flash (API)</b> device. If your NOR Flash uses an SPI interface, select <b>SPI (API)</b> additionally.</li>
 </ul>
-<p>If your NOR Flash device is not listed, use one of the examples as a reference to implement a driver for your specific device:</p><ul>
+<p>If your NOR Flash device is not listed, use one of the examples as a reference to implement a driver for your specific device:</p>
+<ul>
 <li>AM29x800BB/<a href="https://www.farnell.com/datasheets/40281.pdf">M29W640FB</a> (Flash with 16-bit memory bus interface)</li>
 <li><a href="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">S29GL064Nx2</a> (Flash with 32-bit memory bus interface)</li>
 <li><a href="https://datasheet.octopart.com/AT45DB642D-CNU-Atmel-datasheet-9652374.pdf">AT45DB642D</a> (Flash with SPI interface using an SPI driver)</li>
@@ -206,12 +208,14 @@ <h2><a class="anchor" id="mc_usage"></a>
 <img src="fs_config_mc_0_h.png" alt=""/>
 <div class="caption">
 Memory Card Drive Configuration File</div></div>
-    <dl class="section note"><dt>Note</dt><dd><ul>
+    <blockquote class="doxtable">
+<p>&zwj;<b>Note</b></p>
+<ul>
 <li>If your microcontroller device does not have a <b>CMSIS-Driver</b> for the <b>MCI (API)</b> or <b>SPI (API)</b>, you can try to develop your own one based on the  <script>link_ext('CMSIS-Driver-Ref');</script> documentation.</li>
 <li>The page <a class="el" href="operation.html#mc_control_layer">Memory Card Control Layer</a> lists all supported memory card types and gives further details on how to use these cards.</li>
-<li>General <a class="el" href="create_app.html#system_configuration">System Resource Configuration</a> requirements apply.</li>
+<li>General <a class="el" href="create_app.html#system_configuration">System Resource Configuration</a> requirements apply. </li>
 </ul>
-</dd></dl>
+</blockquote>
 <h2><a class="anchor" id="usb_usage"></a>
 USB Flash Drive</h2>
 <ul>
@@ -224,11 +228,13 @@ <h2><a class="anchor" id="usb_usage"></a>
 <img src="fs_config_usb_0_h.png" alt=""/>
 <div class="caption">
 USB Host Mass Storage Class Drive Configuration File</div></div>
-    <dl class="section note"><dt>Note</dt><dd><ul>
+    <blockquote class="doxtable">
+<p>&zwj;<b>Note</b></p>
+<ul>
 <li>If your microcontroller device does not have a <b>CMSIS-Driver</b> for the <b>USB Host (API)</b>, you can try to develop your own one based on the  <script>link_ext('CMSIS-Driver-Ref');</script> documentation.</li>
-<li>General <a class="el" href="create_app.html#system_configuration">System Resource Configuration</a> requirements apply.</li>
+<li>General <a class="el" href="create_app.html#system_configuration">System Resource Configuration</a> requirements apply. </li>
 </ul>
-</dd></dl>
+</blockquote>
 <h2><a class="anchor" id="nand_usage"></a>
 NAND Flash Drive</h2>
 <ul>
@@ -240,14 +246,16 @@ <h2><a class="anchor" id="nand_usage"></a>
 <img src="fs_config_nand_0_h.png" alt=""/>
 <div class="caption">
 NAND Flash Drive Configuration File</div></div>
-    <dl class="section note"><dt>Note</dt><dd><ul>
+    <blockquote class="doxtable">
+<p>&zwj;<b>Note</b></p>
+<ul>
 <li>If your microcontroller device does not have a <b>CMSIS-Driver</b> for the <b>NAND (API)</b>, you can try to develop your own one based on the  <script>link_ext('CMSIS-Driver-Ref');</script> documentation.</li>
 <li>The page <a class="el" href="operation.html#nand_flash_TL">NAND Flash Translation Layer</a> describes additional features specific to these devices.</li>
 <li>Using a <b>NAND (API)</b> driver, you can use any NAND Flash device with an 8-/16-bit memory bus interface for data storage.</li>
 <li>NAND Flashes with SPI interface (Serial NAND) are currently <em>not supported</em> by the File System Component.</li>
-<li>General <a class="el" href="create_app.html#system_configuration">System Resource Configuration</a> requirements apply.</li>
+<li>General <a class="el" href="create_app.html#system_configuration">System Resource Configuration</a> requirements apply. </li>
 </ul>
-</dd></dl>
+</blockquote>
 <h1><a class="anchor" id="fs_configuration"></a>
 File System Configuration</h1>
 <p>The File System configuration file <code>FS_Config.h</code> contains settings for the amount of files that can be open at the same time:</p>
@@ -266,7 +274,8 @@ <h1><a class="anchor" id="hw_configuration"></a>
     <dl class="section note"><dt>Note</dt><dd>Consult the device's user manual or hardware reference guide for more details.</dd></dl>
 <h1><a class="anchor" id="system_configuration"></a>
 System Resource Configuration</h1>
-<p>For proper operation, the File System Component requires some system configuration settings. The requirements are:</p><ul>
+<p>For proper operation, the File System Component requires some system configuration settings. The requirements are:</p>
+<ul>
 <li>Minimum <b>heap size of 512 + 96 Bytes for each opened file</b>. 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 <code>startup_device.s</code> file (<code>Heap_Size</code>).</li>
 <li>As the File System Component is not creating any additional threads, you need to add thread stack size to the calling thread. This calling thread can be the main thread, a thread with a default stack size or a thread with a user provided stack size. Changing the size for these threads can be done in the  <script>link_ext('RTX-Conf-CM5');</script> file.</li>
 <li>Each opened file is protected with a mutex in order to ensure thread-safe operation. When working with file functions from the standard C library, you need to ensure enough mutex objects available for the file stream operations in the standard library system. File System component's <a class="el" href="resource_requirements.html">Resource Requirements</a> section explains how to determine the right setting in detail. Adjusting the number of mutex objects available for standard library system can be done in the  <script>link_ext('RTX-Conf-CM5');</script> file.</li>
@@ -284,7 +293,8 @@ <h2><a class="anchor" id="fsEvrSupport"></a>
 Event Recorder Support</h2>
 <p> <script>link_ext('Event-Recorder-About');</script> is a powerful tool that provides visibility to the dynamic execution of the program.</p>
 <p>The File System Component generates <a class="el" href="group__evr__gr.html">a broad set of Debug Events</a> for the Event Recorder and implements required infrastructure to interface with it.</p>
-<p>To use the Event Recorder it is required to create an image with event generation support. The necessary steps are:</p><ol type="1">
+<p>To use the Event Recorder it is required to create an image with event generation support. The necessary steps are:</p>
+<ol type="1">
 <li> <script>link_ext('Event-Recorder-Enable');</script>: in the RTE management dialog enable the software component <b>CMSIS-View:Event Recorder</b>.</li>
 <li>Ensure that Event Recorder is initialized preferably by  <script>link_ext('RTX5-Event-Recorder-Config');</script> if CMSIS-RTOS2 RTX v5 is used, or alternatively by calling the function  <script>link_ext('Event-Recorder-Initialize-Func');</script> in the application code.</li>
 <li><a class="el" href="create_app.html#fsEvrConfig">Event Recorder Configuration</a>: if necessary, adjust default Event Recorder configuration.</li>
@@ -301,7 +311,8 @@ <h3><a class="anchor" id="fsEvrConfig"></a>
 <img src="fs_debug_h.png" alt=""/>
 <div class="caption">
 FS_Debug.h file for event generation configuration</div></div>
-    <p>The following settings are available for event generation configuration of each module:</p><ul>
+    <p>The following settings are available for event generation configuration of each module:</p>
+<ul>
 <li><b>Off</b> means no events will be generated by the module</li>
 <li><b>Errors</b> means only error events will be generated by the module</li>
 <li><b>Errors + API</b> means error and API call events will be generated by the module</li>

diff --git a/main/FileSystem/examples.html b/main/FileSystem/examples.html
@@ -128,7 +128,8 @@
   <div class="headertitle"><div class="title">Examples </div></div>
 </div><!--header-->
 <div class="contents">
-<div class="textblock"><p><a class="anchor" id="md_src_examples"></a> 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).</p><ul>
+<div class="textblock"><p><a class="anchor" id="md_src_examples"></a> 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).</p>
+<ul>
 <li><a class="el" href="File_Demo_Example.html">File Demo Example</a> shows the basic functionality of the File System.</li>
 <li><a href="../USB/usbd_example_msc.html">USB Device Mass Storage</a> shows how to create an USB MSC Device that is recognized by an USB Host controller.</li>
 <li><a href="../USB/usbh_example_msc.html">USB Host Mass Storage</a> explains how to access file system data from an attached USB memory device.</li>

diff --git a/main/FileSystem/footer.js b/main/FileSystem/footer.js
@@ -3,5 +3,5 @@ function writeHeader() {
 };
 
 function writeFooter()  {
-    document.write('Generated on Mon Oct  7 2024 10:19:20 for File System Component 8.0.0. Copyright &copy; 2024 Arm Limited (or its affiliates). All rights reserved.');
+    document.write('Generated on Mon Oct  7 2024 10:53:28 for File System Component 8.0.0. Copyright &copy; 2024 Arm Limited (or its affiliates). All rights reserved.');
 };
diff --git a/main/FileSystem/migration_guide.html b/main/FileSystem/migration_guide.html
@@ -138,51 +138,63 @@ <h1><a class="anchor" id="migrate_components"></a>
 <p>There are three major changes in File System version 8 that affect how File System components get selected.</p>
 <ol type="1">
 <li><p class="startli">Bundle <b>MDK</b> has replaced bundles <b>MDK-Pro</b> and <b>MDK-Plus</b></p>
-<p class="startli">Where applicable replace components: </p><div class="fragment"><div class="line">Keil::File System&amp;MDK-Pro</div>
+<p class="startli">Where applicable replace components:</p>
+<div class="fragment"><div class="line">Keil::File System&amp;MDK-Pro</div>
 <div class="line">or</div>
 <div class="line">Keil::File System&amp;MDK-Plus</div>
-</div><!-- fragment --><p class="startli">with components that reference bundle <b>MDK</b>: </p><div class="fragment"><div class="line">Keil::File System&amp;MDK</div>
+</div><!-- fragment --><p class="startli">with components that reference bundle <b>MDK</b>:</p>
+<div class="fragment"><div class="line">Keil::File System&amp;MDK</div>
 </div><!-- fragment --></li>
 <li><p class="startli">Legacy Standard C Library retarget components are no longer supported</p>
 <p class="startli">This means that using components from the CMSIS-Compiler is now mandatory. Nevertheless, migrating from Compiler to CMSIS-Compiler components is straightforward.</p>
-<p class="startli">To migrate your project replace component: </p><div class="fragment"><div class="line">Keil::Compiler::I/O:File&amp;File System</div>
-</div><!-- fragment --><p class="startli">with components from CMSIS-Compiler class: </p><div class="fragment"><div class="line">ARM::CMSIS-Compiler:CORE</div>
+<p class="startli">To migrate your project replace component:</p>
+<div class="fragment"><div class="line">Keil::Compiler::I/O:File&amp;File System</div>
+</div><!-- fragment --><p class="startli">with components from CMSIS-Compiler class:</p>
+<div class="fragment"><div class="line">ARM::CMSIS-Compiler:CORE</div>
 <div class="line">and</div>
 <div class="line">ARM::CMSIS-Compiler:File Interface:MDK-MW File System</div>
 </div><!-- fragment --><p class="startli">Components from <b>Compiler</b> and <b>CMSIS-Compiler</b> are incompatible and cannot coexist hence all other components from Compiler class must also be migrated to components from CMSIS-Compiler:</p>
-<p class="startli">Migrate components: </p><div class="fragment"><div class="line">Keil::Compiler:I/O:STDERR&amp;{Cvariant}  -&gt;  ARM::CMSIS-Compiler:STDERR:{Csub}</div>
+<p class="startli">Migrate components:</p>
+<div class="fragment"><div class="line">Keil::Compiler:I/O:STDERR&amp;{Cvariant}  -&gt;  ARM::CMSIS-Compiler:STDERR:{Csub}</div>
 <div class="line">Keil::Compiler:I/O:STDIN&amp;{Cvariant}   -&gt;  ARM::CMSIS-Compiler:STDIN:{Csub}</div>
 <div class="line">Keil::Compiler:I/O:STDOUT&amp;{Cvariant}  -&gt;  ARM::CMSIS-Compiler:STDOUT:{Csub}</div>
 <div class="line">Keil::Compiler:I/O:TTY&amp;{Cvariant}     -&gt;  ARM::CMSIS-Compiler:TTY:{Csub}</div>
 </div><!-- fragment --></li>
 <li><p class="startli"><b>Event Recorder</b> component is now part of <b>CMSIS-View</b> class</p>
-<p class="startli">If your project is configured for debugging then you need to replace component: </p><div class="fragment"><div class="line">Keil::Compiler:Event Recorder</div>
-</div><!-- fragment --><p class="startli">with component from CMSIS-View class: </p><div class="fragment"><div class="line">ARM::CMSIS-View:Event Recorder</div>
+<p class="startli">If your project is configured for debugging then you need to replace component:</p>
+<div class="fragment"><div class="line">Keil::Compiler:Event Recorder</div>
+</div><!-- fragment --><p class="startli">with component from CMSIS-View class:</p>
+<div class="fragment"><div class="line">ARM::CMSIS-View:Event Recorder</div>
 </div><!-- fragment --></li>
 </ol>
 <h1><a class="anchor" id="migrate_config"></a>
 Configuration</h1>
 <p>In general two major changes were made to the File System version 8 configuration files and affect how File System gets configured.</p>
 <ol type="1">
 <li><p class="startli">The core configuration has been moved from C source file to C header file</p>
-<p class="startli">To migrate configuration of an existing project use compare/merge tool on the following files: </p><div class="fragment"><div class="line">FS_Config.c  and  FS_Config.h</div>
-</div><!-- fragment --> <blockquote class="doxtable">
+<p class="startli">To migrate configuration of an existing project use compare/merge tool on the following files:</p>
+<div class="fragment"><div class="line">FS_Config.c  and  FS_Config.h</div>
+</div><!-- fragment --></li>
+</ol>
+<blockquote class="doxtable">
 <p>&zwj;Note: FS_Config.h does not have configuration for Initial Current Drive anymore. To understand how current drive is set see chapter <a class="el" href="operation.html#cur_sys_drive">Current Drive</a>. </p>
 </blockquote>
-</li>
+<ol type="1">
 <li><p class="startli">Drive configuration changed the way how drive cache and drive buffer placement works</p>
 <p class="startli">On microcontrollers where DMA has limited access to memory areas one must place drive buffers into the appropriate memory in order for peripheral driver to work. In File System version 8 this is supported by placing drive buffer in a dedicated section which must be properly located with the toolchain linker script.</p>
 <p class="startli">The latest drive configuration files contain a define named **_CACHE_SECTION** where one can define the section name.</p>
-<p class="startli">For example: </p><div class="fragment"><div class="line">//     &lt;s&gt;Section Name</div>
-<div class="line">//     &lt;i&gt;Define the name of the section for the drive cache and drive buffers.</div>
-<div class="line">//     &lt;i&gt;Linker script shall have this section defined.</div>
-<div class="line">#define MC0_CACHE_SECTION       &quot;.driver.mci0&quot;</div>
+<p class="startli">For example:</p>
+<div class="fragment"><div class="line"><span class="comment">//     &lt;s&gt;Section Name</span></div>
+<div class="line"><span class="comment">//     &lt;i&gt;Define the name of the section for the drive cache and drive buffers.</span></div>
+<div class="line"><span class="comment">//     &lt;i&gt;Linker script shall have this section defined.</span></div>
+<div class="line"><span class="preprocessor">#define MC0_CACHE_SECTION       &quot;.driver.mci0&quot;</span></div>
 </div><!-- fragment --><p class="startli">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**.</p>
-<p class="startli">The define for RAM drive 0 looks like shown below: </p><div class="fragment"><div class="line">//     &lt;s&gt;Section Name</div>
-<div class="line">//     &lt;i&gt;Define the name of the section for the file system buffer.</div>
-<div class="line">//     &lt;i&gt;Linker script shall have this section defined.</div>
-<div class="line">#define RAM0_SECTION           &quot;.filesystem.ram0&quot;</div>
-</div><!-- fragment --><p> To migrate configuration of an existing project use compare/merge tool on drive configuration files and update toolchain linker script to support defined sections. </p>
+<p class="startli">The define for RAM drive 0 looks like shown below:</p>
+<div class="fragment"><div class="line"><span class="comment">//     &lt;s&gt;Section Name</span></div>
+<div class="line"><span class="comment">//     &lt;i&gt;Define the name of the section for the file system buffer.</span></div>
+<div class="line"><span class="comment">//     &lt;i&gt;Linker script shall have this section defined.</span></div>
+<div class="line"><span class="preprocessor">#define RAM0_SECTION           &quot;.filesystem.ram0&quot;</span></div>
+</div><!-- fragment --><p class="startli">To migrate configuration of an existing project use compare/merge tool on drive configuration files and update toolchain linker script to support defined sections. </p>
 </li>
 </ol>
 </div></div><!-- contents -->