Added usage and overview.

Author: KeilChris

ARM.CMSIS-Compiler.pdsc

@@ -2,7 +2,7 @@
 <package schemaVersion="1.7.36" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/v1.7.36/schema/PACK.xsd">
   <vendor>ARM</vendor>
   <name>CMSIS-Compiler</name>
-  <description>CMSIS Compiler extensions for Arm Compiler, GCC, Clang, and IAR Compiler</description>
+  <description overview="overview/README.md">CMSIS Compiler extensions for Arm Compiler, GCC, Clang, and IAR Compiler</description>
   <url>https://www.keil.com/pack/</url>
   <license>LICENSE</license>
   <licenseSets>

documentation/doxygen/compiler.dxy.in

@@ -996,6 +996,7 @@ INPUT                  = ./src/mainpage.md                 \
                          ./src/history.txt                 \
                          ./src/rt_io.md                    \
                          ./src/rt_os.md                    \
+                         ./src/usage.md                    \
                          ./src/rt_example.md               \
                          ./src/templates.md                \
                          ./src/templates_file.md           \

documentation/doxygen/src/images/component-selection.png

@@ -60,11 +60,11 @@ This documentation contains the following sections:
 - \ref rev_hist : lists CMSIS-Compiler releases.
 - \ref rt_io : explains low-level I/O retargeting, list available components and describes available user code templates.
 - \ref rt_os : explains multithreading support retargeting, list available components and describes available user code templates.
+- \ref usage : instructs how to enable and use the CMSIS-Compiler software components.
 - \ref rt_example shows how to retarget the output to a UART on an Arm Virtual Hardware model.
 - \ref rt_templates : contains the user code template files for the different use cases.
 - [**API Reference**](topics.html) describes the API and the functions of the CMSIS-Compiler components in details.
 
-
 ## License {#doc_license}
 
 CMSIS-Compiler is provided free of charge by Arm under the [Apache 2.0 License](https://raw.githubusercontent.com/ARM-software/CMSIS-Compiler/main/LICENSE)

documentation/doxygen/src/mainpage.md

@@ -0,0 +1,35 @@
+# Use CMSIS-Compiler {#usage}
+
+The following steps are required to install the **ARM::CMSIS-Compiler** pack and to use the software components that
+are shipped with the CMSIS-Pack.
+
+> **Note**
+>
+> The installation and usage instructions are assuming you are using a
+> [CMSIS-Toolbox](https://open-cmsis-pack.github.io/cmsis-toolbox/) based environment.
+
+## Pack installation
+
+Add the **ARM::CMSIS-Compiler** pack to your installation:
+
+```sh
+cpackget add ARM::CMSIS-Compiler
+```
+
+Alternatively, you can download the latest version from the
+[CMSIS-Compiler](https://www.keil.arm.com/packs/cmsis-compiler-arm/versions/) page.
+
+## Component selection and usage
+
+1. In your IDE, open the
+   [Manage software components](https://mdk-packs.github.io/vscode-cmsis-solution-docs/create_app.html#software-components)
+   dialog.
+2. If you cannot see the **CMSIS-Compiler** component, select to display **All installed packs**.
+3. You must select the component **CMSIS-Compiler::CORE** and at least one additional **API**.
+
+![Manage software components](./images/component-selection.png)
+
+> **Note**
+>
+> Refer to the sections [Low-level I/O](./rt_io.md) and
+> [Multithreading Support Retarget](./rt_os.md) for more information about the retargeting options.

documentation/doxygen/src/usage.md

@@ -9,7 +9,7 @@ set -o pipefail
 # Set version of gen pack library
 # For available versions see https://github.com/Open-CMSIS-Pack/gen-pack/tags.
 # Use the tag name without the prefix "v", e.g., 0.7.0
-REQUIRED_GEN_PACK_LIB="0.11.3"
+REQUIRED_GEN_PACK_LIB="0.13.0"
 
 # Set default command line arguments
 DEFAULT_ARGS=(-c "v")
@@ -32,6 +32,7 @@ PACK_DIRS="
   documentation
   example
   include
+  overview
   source
   template
 "

gen_pack.sh

@@ -0,0 +1,31 @@
+# Overview
+
+**CMSIS-Compiler** provides software components that simplify retargeting of standard C run-time library functions.
+
+Application code frequently uses standard C library functions, such as `fopen`, `fwrite`, `printf()`, `scanf()` and
+others to perform input/output operations. These functions may as well be used in a multithreaded environment.
+
+The structure of these functions in the standard C run-time library together with the retarget interfaces is:
+
+![Software Structure Overview](./overview.png)
+
+Standard C library functions are platform independent and can be easily ported, while the low-level interfaces needs to
+be tailored to the chosen platform. Generally low-level I/O functions serve to interact with the file system and a
+serial interface, i.e. terminal. Multithreading support is available for applications that run on top of an RTOS kernel.
+
+CMSIS-Compiler enables platform specific retargeting by providing software components that break down into the following interfaces:
+
+- **File interface** that enables reading and writing files
+- **STDIN interface** that enables standard input stream redirection
+- **STDOUT interface** that enables standard output stream redirection
+- **STDERR interface** that enables standard error stream redirection
+- **OS interface** that enables multithread safety using an arbitrary RTOS
+
+Using CMSIS-Compiler developers can retarget standard I/O streams and file operations to specific platform and enable
+thread safe operations using RTOS interface.
+
+## Links
+
+- [Documentation](https://arm-software.github.io/CMSIS-Compiler/latest/index.html)
+- [Repository](https://github.com/ARM-software/CMSIS-Compiler)
+- [Issues](https://github.com/ARM-software/CMSIS-Compiler/issues)