Doc: addressed review feedback, and moved Doxygen/ to Documentation/

Co-authored-by: Joachim Krech <[email protected]>
Co-authored-by: Jonatan Antoni <[email protected]>

.github/workflows/pack.yml

@@ -29,9 +29,9 @@ jobs:
         with:
           doxygen-version: 1.9.6
           packchk-version: 1.3.98
-          gen-doc-script: ./CMSIS/DoxyGen/gen_doc.sh
-          check-links-script: ./CMSIS/DoxyGen/check_links.sh
-          doc-path: ./CMSIS/Documentation/
+          gen-doc-script: ./CMSIS/Documentation/Doxygen/gen_doc.sh
+          check-links-script: ./CMSIS/Documentation/Doxygen/check_links.sh
+          doc-path: ./CMSIS/Documentation/html
           gen-pack-script: ./gen_pack.sh --no-preprocess
           gen-pack-output: ./output
           gh-pages-branch: gh-pages

.gitignore

@@ -1,7 +1,7 @@
 *.junit
 **/__pycache__
-CMSIS/Documentation/
-CMSIS/DoxyGen/**/*.dxy
+CMSIS/Documentation/html
+CMSIS/Documentation/Doxygen/**/*.dxy
 CMSIS/Core/Test/*.o
 CMSIS/Core/Test/*.xunit
 CMSIS/Core/Test/.lit_test_times.txt

ARM.CMSIS.pdsc

@@ -406,9 +406,9 @@
     <description Cclass="Board Support">Generic Interfaces for Evaluation and Development Boards</description>
     <description Cclass="Board Part">Drivers that support an external component available on an evaluation board</description>
     <description Cclass="Compiler">Compiler Software Extensions</description>
-    <description Cclass="CMSIS" doc="CMSIS/Documentation/General/html/index.html">Cortex Microcontroller Software Interface Components</description>
-    <description Cclass="CMSIS Driver" doc="CMSIS/Documentation/Driver/html/index.html">Unified Device Drivers compliant to CMSIS-Driver Specifications</description>
-    <description Cclass="Device" doc="CMSIS/Documentation/Core/html/index.html">Startup, System Setup</description>
+    <description Cclass="CMSIS" doc="CMSIS/Documentation/html/General/index.html">Cortex Microcontroller Software Interface Components</description>
+    <description Cclass="CMSIS Driver" doc="CMSIS/Documentation/html/Driver/index.html">Unified Device Drivers compliant to CMSIS-Driver Specifications</description>
+    <description Cclass="Device" doc="CMSIS/Documentation/html/Core/index.html">Startup, System Setup</description>
     <description Cclass="Data Exchange">Data exchange or data formatter</description>
     <description Cclass="Extension Board">Drivers that support an extension board or shield</description>
     <description Cclass="File System">File Drive Support and File System</description>
@@ -442,121 +442,121 @@
     <api Cclass="CMSIS" Cgroup="RTOS2" Capiversion="2.3.0" exclusive="1">
       <description>CMSIS-RTOS API for Cortex-M, SC000, and SC300</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/RTOS2/html/index.html"/>
+        <file category="doc" name="CMSIS/Documentation/html/RTOS2/index.html"/>
         <file category="header" name="CMSIS/RTOS2/Include/cmsis_os2.h"/>
       </files>
     </api>
     <!-- CMSIS Driver API -->
     <api Cclass="CMSIS Driver" Cgroup="USART" Capiversion="2.4.0" exclusive="0">
       <description>USART Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__usart__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__usart__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_USART.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="SPI" Capiversion="2.3.0" exclusive="0">
       <description>SPI Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__spi__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__spi__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_SPI.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="SAI" Capiversion="1.2.0" exclusive="0">
       <description>SAI Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__sai__interface__gr.html"/>
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__sai__interface__gr.html"/>
         <file category="header" name="CMSIS/Driver/Include/Driver_SAI.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="I2C" Capiversion="2.4.0" exclusive="0">
       <description>I2C Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__i2c__interface__gr.html"/>
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__i2c__interface__gr.html"/>
         <file category="header" name="CMSIS/Driver/Include/Driver_I2C.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="CAN" Capiversion="1.3.0" exclusive="0">
       <description>CAN Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__can__interface__gr.html"/>
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__can__interface__gr.html"/>
         <file category="header" name="CMSIS/Driver/Include/Driver_CAN.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="Flash" Capiversion="2.3.0" exclusive="0">
       <description>Flash Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__flash__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__flash__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_Flash.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="MCI" Capiversion="2.4.0" exclusive="0">
       <description>MCI Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__mci__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__mci__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_MCI.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="NAND" Capiversion="2.4.0" exclusive="0">
       <description>NAND Flash Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__nand__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__nand__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_NAND.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="Ethernet" Capiversion="2.2.0" exclusive="0">
       <description>Ethernet MAC and PHY Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__eth__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__eth__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_ETH_MAC.h" />
         <file category="header" name="CMSIS/Driver/Include/Driver_ETH_PHY.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="Ethernet MAC" Capiversion="2.2.0" exclusive="0">
       <description>Ethernet MAC Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__eth__mac__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__eth__mac__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_ETH_MAC.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="Ethernet PHY" Capiversion="2.2.0" exclusive="0">
       <description>Ethernet PHY Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__eth__phy__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__eth__phy__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_ETH_PHY.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="USB Device" Capiversion="2.3.0" exclusive="0">
       <description>USB Device Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__usbd__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__usbd__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_USBD.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="USB Host" Capiversion="2.3.0" exclusive="0">
       <description>USB Host Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__usbh__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__usbh__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_USBH.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="GPIO" Capiversion="1.0.0" exclusive="0">
       <description>GPIO Driver API for Cortex-M</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__gpio__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__gpio__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_GPIO.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="WiFi" Capiversion="1.1.0" exclusive="0">
       <description>WiFi driver</description>
       <files>
-        <file category="doc" name="CMSIS/Documentation/Driver/html/group__wifi__interface__gr.html" />
+        <file category="doc" name="CMSIS/Documentation/html/Driver/group__wifi__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/Include/Driver_WiFi.h" />
       </files>
     </api>
     <api Cclass="CMSIS Driver" Cgroup="VIO" Capiversion="1.0.0" exclusive="1">
       <description>Virtual I/O</description>
       <files>
-        <file category="doc"    name="CMSIS/Documentation/Driver/html/group__vio__interface__gr.html" />
+        <file category="doc"    name="CMSIS/Documentation/html/Driver/group__vio__interface__gr.html" />
         <file category="header" name="CMSIS/Driver/VIO/Include/cmsis_vio.h" />
         <file category="other"  name="CMSIS/Driver/VIO/cmsis_vio.scvd" />
       </files>
@@ -654,7 +654,7 @@
       <description>CMSIS-CORE for Cortex-M, SC000, SC300, Star-MC1, ARMv8-M, ARMv8.1-M</description>
       <files>
         <!-- CPU independent -->
-        <file category="doc"     name="CMSIS/Documentation/Core/html/index.html"/>
+        <file category="doc"     name="CMSIS/Documentation/html/Core/index.html"/>
         <file category="include" name="CMSIS/Core/Include/"/>
         <file category="header"  name="CMSIS/Core/Include/tz_context.h" condition="TrustZone"/>
         <!-- Code template -->
@@ -667,7 +667,7 @@
       <description>CMSIS-CORE for Cortex-A</description>
       <files>
         <!-- CPU independent -->
-        <file category="doc"     name="CMSIS/Documentation/Core_A/html/index.html"/>
+        <file category="doc"     name="CMSIS/Documentation/html/Core_A/index.html"/>
         <file category="include" name="CMSIS/Core/Include/"/>
       </files>
     </component>

CMSIS/DoxyGen/Compiler/Compiler.dxy.in → CMSIS/Documentation/Doxygen/Compiler/Compiler.dxy.in

@@ -67,7 +67,7 @@ PROJECT_LOGO           = ../Doxygen_Templates/cmsis_logo_white_small.png
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = ../../Documentation/Compiler
+OUTPUT_DIRECTORY       = ../../html/Compiler
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format
@@ -1302,7 +1302,7 @@ GENERATE_HTML          = YES
 # The default directory is: html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_OUTPUT            = html
+HTML_OUTPUT            = ./
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).

CMSIS/Documentation/Doxygen/Compiler/src/mainpage.md

@@ -0,0 +1,25 @@
+# CMSIS-Compiler {#mainpage}
+
+**CMSIS-Compiler** provides software components for retargeting I/O operations in standard C run-time libraries. Following interfaces are supported for retargeting:
+
+ - File interface for reading and writing files.
+ - I/O interface for standard I/O stream retargeting (stderr, stdin, stdout).
+ - OS interface for multithread safety using an arbitrary RTOS.
+
+![Overview of CMSIS-Compiler](./images/cmsis_compiler_overview.png)
+
+Standard C library functions are platform independent, but the implementations of the low-level I/O and multithreading support are tailored to the target compiler toolchains.
+
+## Access to CMSIS-Compiler
+
+CMSIS-Compiler is maintained in a GitHub repository and is also released as a standalone package in CMSIS Pack format.
+
+ - [**CMSIS-Compiler GitHub Repo**](https://github.com/Arm-Software/CMSIS-Compiler) provides the full source code as well as releases in CMSIS-Pack format.
+ - [**CMSIS-Compiler Documentation**](https://arm-software.github.io/CMSIS-Compiler/latest/) explains how to use the library and describes the implemented functions in details.
+
+## Key Features and Benefits
+
+ - CMSIS-Compiler allows individual retargeting configuration for common I/O interfaces: file, stderr, stdin, stdout.
+ - Implements several ready-to-use retarget variants: into File, Breakpoint, Event Recorder, ITM, as well as user-specific variant.
+ - Supports common standard C libraries, such as from Arm Compiler and GCC (Newlib) toolchains. IAR support is planned.
+ - Provides implementation templates and examples to get started.

CMSIS/DoxyGen/Core/Core.dxy.in → CMSIS/Documentation/Doxygen/Core/Core.dxy.in

@@ -67,7 +67,7 @@ PROJECT_LOGO           = ../Doxygen_Templates/cmsis_logo_white_small.png
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = ../../Documentation/Core
+OUTPUT_DIRECTORY       = ../../html/Core
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format
@@ -1086,7 +1086,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = ../../Core/Template/Device_M/
+EXAMPLE_PATH           = ../../../Core/Template/Device_M/
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -1339,7 +1339,7 @@ GENERATE_HTML          = YES
 # The default directory is: html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_OUTPUT            = html
+HTML_OUTPUT            = ./
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).
@@ -2458,7 +2458,7 @@ TAGFILES               =
 # tag file that is based on the input files it reads. See section "Linking to
 # external documentation" for more information about the usage of tag files.
 
-GENERATE_TAGFILE       = ../../Documentation/Core/cmsis_core_m.tag
+GENERATE_TAGFILE       = ../../html/Core/cmsis_core_m.tag
 
 # If the ALLEXTERNALS tag is set to YES, all external class will be listed in
 # the class index. If set to NO, only the inherited external classes will be

CMSIS/DoxyGen/Core/src/core_files_in_packs.md → CMSIS/Documentation/Doxygen/Core/src/core_files_in_packs.md

@@ -2,7 +2,7 @@
 
 In simple individual cases the \ref cmsis_core_files can be delivered to developers as part of example projects and SDKs. But the most scalable approach with improved usability is to provide them packaged in [Open-CMSIS-Pack format](https://www.open-cmsis-pack.org), and this page explains how to do this.
 
-The \ref cmsis_standard_files are provided as part of [CMSIS Software pack](../../General/html/cmsis_pack.html) under **CMSIS** class of components and compose there the **CORE** group.
+The \ref cmsis_standard_files are provided as part of [CMSIS Software pack](../General/cmsis_pack.html) under **CMSIS** class of components and compose there the **CORE** group.
 
 The \ref cmsis_device_files are delivered in [CMSIS Device Family Packs (DFPs)](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/cp_PackTutorial.html#createPack_DFP) that provide necessary mechanisms for device support in embedded software. The DFPs are typically maintained by device vendors.
 
@@ -49,7 +49,7 @@ Since the \ref cmsis_device_files require access to implementations from \ref cm
 
 ## Device Examples {#device_examples}
 
-The [CMSIS-DFP pack](https://github.com/ARM-software/CMSIS-DFP) provides generic device definitions for standard Arm Cortex-M cores and contains corresponding \ref cmsis_device_files.
+The [Cortex_DFP pack](https://github.com/ARM-software/Cortex_DFP) provides generic device definitions for standard Arm Cortex-M cores and contains corresponding \ref cmsis_device_files.
 
 These files can be used as a reference for device support in a DFP pack, but can also be used in projects that require standard Arm processors functionality. See \ref using_arm.
 

CMSIS/DoxyGen/Core/src/core_linker_sct.md → CMSIS/Documentation/Doxygen/Core/src/core_linker_sct.md

@@ -3,15 +3,15 @@
 A scatter file for linking is required when using a \ref startup_c_pg.
 
 The \ref linker_sct_pg contains regions for:
+
  - Code (read-only data, execute-only data)
  - RAM (read/write data, zero-initialized data)
  - Stack
  - Heap
  - Stack seal (for Armv8-M/v8.1-M)
  - CMSE veneer (for Armv8-M/v8.1-M)
 
-Within the scatter file, the user needs to specify a set of macros. The scatter file is passed through the
-C preprocessor which uses these macros to calculate the start address and the size of the different regions.
+Within the scatter file, the user needs to specify a set of macros. The scatter file is passed through the C preprocessor which uses these macros to calculate the start address and the size of the different regions.
 
 ```
 /*--------------------- Flash Configuration ----------------------------------
@@ -49,13 +49,13 @@ C preprocessor which uses these macros to calculate the start address and the si
 #define __CMSEVENEER_SIZE    0x200
 ```
 
-\note
-The stack is placed at the end of the available RAM and is growing downwards 
-whereas the Heap is placed after the application data and growing upwards.
+> **Note**
+> - The stack is placed at the end of the available RAM and is growing downwards whereas the Heap is placed after the application data and growing upwards.
 
 ## Preprocessor command {#linker_sct_preproc_sec}
 
 The scatter file uses following preprocessor command for Arm Compiler v6
+
 ```
 #! armclang -E --target=arm-arm-none-eabi -mcpu=<mcpu> -xc
 ```