-
Notifications
You must be signed in to change notification settings - Fork 26
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Various minor adjustments according to Grammarly check
- Loading branch information
Showing
1 changed file
with
23 additions
and
23 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -28,31 +28,31 @@ Hands-on Tutorial | Description | |
|
|
||
| ## Hints for Pack Creation | ||
|
|
||
| - Use [C startup files](https://arm-software.github.io/CMSIS_6/latest/Core/cmsis_core_files.html) that allows to use a DFP with any toolchain. | ||
| - For elements use a brief description text with less than 128 characters to explain the purpose. When possible link to documentation with detailed information. | ||
| - Use [C startup files](https://arm-software.github.io/CMSIS_6/latest/Core/cmsis_core_files.html) that allows the use of a DFP with any toolchain. | ||
| - For elements, use a brief description text of less than 128 characters to explain the purpose. When possible, link to documentation with detailed information. | ||
| - Example: A component `Device:HAL:ENET` should not have description `ENET HAL Driver`, use `Ethernet HAL driver` instead. | ||
| - Consider adding [project templates](https://github.com/Open-CMSIS-Pack/STM32U5xx_DFP/tree/main/Templates) to help get started with more complex projects. | ||
| - This is useful when devices are are configured using generators or provide multiple linker scripts (i.e. RAM/ROM execution). | ||
| This is useful when devices are configured using generators or provide multiple linker scripts (e.g., RAM/ROM execution). | ||
| - To distribute [toolchain agnostic examples](build-overview.md#toolchain-agnostic-project) as part of packs: | ||
| - Consider to use [`select-compiler`](YML-Input-Format.md#select-compiler) to make projects toolchain independent. | ||
| - To avoid that examples need updates with every pack release, specify the [minium pack version required](https://github.com/Open-CMSIS-Pack/csolution-examples/blob/main/DualCore/HelloWorld.csolution.yml#L9). | ||
| - To avoid that examples need updates with every pack release, specify the [minimum pack version required](https://github.com/Open-CMSIS-Pack/csolution-examples/blob/main/DualCore/HelloWorld.csolution.yml#L9). | ||
| - Use [CI workflows](https://github.com/Open-CMSIS-Pack/STM32H743I-EVAL_BSP/tree/main/.github/workflows) to validate that projects compile correctly. | ||
| - Add an [overview.md file](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/element_package_description.html) that describes the overall usage of the software pack. These files are displayed on [www.keil.arm.com/packs](https://www.keil.arm.com/packs) and index by Web search engines. | ||
| - Add an [overview.md file](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/element_package_description.html) that describes the software pack's overall usage. These files are displayed on [www.keil.arm.com/packs](https://www.keil.arm.com/packs) and indexed by Web search engines. | ||
|
|
||
| ## Project Examples | ||
|
|
||
| Project examples help to get started with new devices, boards, and middleware software components. The CMSIS-Pack format supports therefore different types of project examples: | ||
| Project examples help to get started with new devices, boards, and middleware software components. The CMSIS-Pack format supports, therefore, different types of project examples: | ||
|
|
||
| - [*Template Projects*](#template-projects) are [stub projects](https://github.com/Open-CMSIS-Pack/csolution-examples/tree/main/Templates) that help to get started. Some software packs may contain device specific templates. | ||
| - [*Template Projects*](#template-projects) are [stub projects](https://github.com/Open-CMSIS-Pack/csolution-examples/tree/main/Templates) that help to get started. Some software packs may contain device-specific templates. | ||
| - [*Examples*](#examples) are created for a specific hardware or evaluation board. These are typically complete projects that directly interface with board and device peripherals. | ||
| - [*Reference Applications*](#reference-applications) are hardware agnostic project examples that required [layers](#layers) to add the hardware abstraction of a target (typically a board). | ||
| - [*Reference Applications*](#reference-applications) are hardware-agnostic project examples that required [layers](#layers) to add the hardware abstraction of a target (typically a board). | ||
|
|
||
| In addition packs may contain: | ||
| In addition, packs may contain: | ||
|
|
||
| - [*Layers*](#layers) are pre-configured software components or source code that can be shared across multiple projects. | ||
| - [*Code Templates*](#code-templates) are stub source files for middleware components that can be incorporated into user code. | ||
|
|
||
| The picture below shows the different packs that are used to publish project examples. These examples are available for software developers on web pages and can be directly accessed from IDEs that are for example enabled with the [VS Code Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution) extension. | ||
| The picture below shows the different packs used to publish project examples. These examples are available for software developers on web pages and can be directly accessed from IDEs that are, for example, enabled with the [VS Code Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution) extension. | ||
|
|
||
|  | ||
|
|
||
|
|
@@ -98,7 +98,7 @@ solution: | |
| A *template project* does not define a [`device:`](YML-Input-Format.md#device) or [`board:`](YML-Input-Format.md#board) in the `*.csolution.yml` file. When a IDE starts such an *template* the `device:` and/or `board:` information along with `pack:` information is added depending on user selection. The [`target-types:`](YML-Input-Format.md#target-types) contains a `Name` that may be replaced by a descriptive target name. | ||
|
|
||
| !!! Note | ||
| A *template project* should not specify the DFP or BSP with a `pack:` node as this gets added by the IDE during project start. | ||
| A *template project* should not specify the DFP or BSP with a `pack:` node, as the IDE adds this node during the project start. | ||
|
|
||
| **Simple Template:** | ||
|
|
||
|
|
@@ -116,7 +116,7 @@ solution: | |
|
|
||
| **Multi-Target Template:** | ||
|
|
||
| A multi-target *template* may contain different configurations for the same target, for example a configuration that executes from ROM and another that executes from RAM. The example below shows how this could be achieved using [`variables:`](YML-Input-Format.md#variables). | ||
| A multi-target *template* may contain different configurations for the same target, such as one that executes from ROM and another that executes from RAM. The example below shows how this could be achieved using [`variables:`](YML-Input-Format.md#variables). | ||
|
|
||
| ```yml | ||
| solution: | ||
|
|
@@ -165,21 +165,21 @@ project: | |
|
|
||
| ### Examples | ||
|
|
||
| *Examples* are complete projects that typically run on a board. They should therefore specify a `target-type` with [`board:`](YML-Input-Format.md#board) and list the [`packs:`](YML-Input-Format.md#packs) that are used, specifically the DFP and BSP. | ||
| *Examples* are complete projects that typically run on a board. They should, therefore, specify a `target-type` with [`board:`](YML-Input-Format.md#board) and list the [`packs:`](YML-Input-Format.md#packs) that are used, specifically the DFP and BSP. | ||
|
|
||
| To minimize maintenance of *Examples* that are part of a pack, consider these rules: | ||
|
|
||
| - **IMPORTANT:** Store all files that are part of the [`./RTE` directory](build-overview.md#rte-directory-structure). These files store configuration and are important for [PLM](build-overview.md#plm-of-configuration-files). | ||
| - Use [`select-compiler:`](YML-Input-Format.md#select-compiler) when the *Example* works with several toolchains. Do not specify `compiler:`. | ||
| - Specify [minimum pack version](YML-Input-Format.md#pack-name-conventions). Do not store `*.cbuild-pack.yml`. | ||
| - The tool selects first `target-type` and first `build-type` when `cbuild-set.yml` is missing. For simple projects do not store `*.cbuild-set.yml`. | ||
| - The tool selects first `target-type` and first `build-type` when `cbuild-set.yml` is missing. For simple projects, do not store `*.cbuild-set.yml`. | ||
| - For simple projects, rely on the `cdefault.yml` file that is provided with CMSIS-Toolbox. | ||
|
|
||
| *Examples* that work with several compiler toolchains should use [`select-compiler:`](YML-Input-Format.md#select-compiler) and not define `compiler:` explicit. The `compiler:` node of the available toolchain is added when the *Example* is loaded into the IDE. | ||
| *Examples* that work with several compiler toolchains should use [`select-compiler:`](YML-Input-Format.md#select-compiler) and not define `compiler:` explicitly. The available toolchain's `compiler:` node is added when the *Example* is loaded into the IDE. | ||
|
|
||
| When [minimum pack versions](YML-Input-Format.md#pack-name-conventions) are specified, the semantic versioning of packs should ensure that newer pack versions work also. As the `*.cbuild-pack.yml` file fixes pack versions, this file should be not stored in the pack. | ||
| When [minimum pack versions](YML-Input-Format.md#pack-name-conventions) are specified, the semantic versioning of packs should ensure that newer pack versions work also. As the `*.cbuild-pack.yml` file fixes pack versions, this file should not be stored in the pack. | ||
|
|
||
| *Examples* may contain in the `*.csolution.yml` file multiple related projects that for example cover different aspects of a peripheral or middleware. For such *Examples* it is not required to store the `*.cbuild-set.yml` file as the tools select the first `target-type` and `build-type` of the `*.csolution.yml` file. | ||
| *Examples* may contain multiple related projects in the `*.csolution.yml` file that, for example, cover different aspects of peripheral or middleware. For such *Examples*, it is not required to store the `*.cbuild-set.yml` file as the tools select the first `target-type` and `build-type` of the `*.csolution.yml` file. | ||
|
|
||
| *Examples* that do not require special compiler controls may rely on the [`cdefault.yml` file](build-overview.md#cdefaultyml) that is provided with CMSIS-Toolbox as this file contains reasonable default settings. For more complex *Examples*, provide a local copy of the `cdefault.yml` file in the same directory as the `*.csolution.yml` file. | ||
|
|
||
|
|
@@ -190,7 +190,7 @@ Refer to [Toolchain Agnostic Project](build-overview.md#toolchain-agnostic-proje | |
| ```yml | ||
| solution: | ||
| # Optional: Add a brief description line (recommendation less than 128 characters) | ||
| description: Example that shows the usage of Fault component on an Cortex-M33 with TrustZone | ||
| description: Example that shows the usage of Fault component on a Cortex-M33 with TrustZone | ||
| created-for: [email protected] # minimum CMSIS-Toolbox version, newer versions will work also | ||
| cdefault: | ||
|
|
@@ -230,7 +230,7 @@ solution: | |
| ```xml | ||
| <examples> | ||
| <example name="Fault example" folder="Examples/Fault/B-U585I-IOT02A" doc="README.md"> | ||
| <description>Example that shows the usage of Fault component on an Cortex-M33 with TrustZone</description> | ||
| <description>Example that shows the usage of Fault component on a Cortex-M33 with TrustZone</description> | ||
| <board name="B-U585I-IOT02A" vendor="STMicroelectronics"/> | ||
| <project> | ||
| <environment name="csolution" load="Fault.csolution.yml"/> | ||
|
|
@@ -242,7 +242,7 @@ solution: | |
|
|
||
| ### Reference Applications | ||
|
|
||
| [*Reference applications*](ReferenceApplications.md) can run on many different target hardware boards. Similar to [*template projects*](#template-projects) the `device:` and `board:` along with the required DFP and BSP `pack:` is not specified in the `*.csolution.yml` file. | ||
| [*Reference applications*](ReferenceApplications.md) can run on many different target hardware boards. Similar to [*template projects*](#template-projects), the `device:` and `board:` along with the required DFP and BSP `pack:` is not specified in the `*.csolution.yml` file. | ||
|
|
||
| ```yml | ||
| solution: | ||
|
|
@@ -300,7 +300,7 @@ solution: | |
|
|
||
| ## Code Templates | ||
|
|
||
| *Code templates* are part of the [components files](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#Component_Files) in the PDSC file and can be manually added by the user to a software project. *Code templates* show how a software component is used and the source code can be directly adapted to the requirements of the application program. | ||
| *Code templates* are part of the [components files](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#Component_Files) in the PDSC file and can be manually added by the user to a software project. *Code templates* show how a software component is used, and the source code can be directly adapted to the requirements of the application program. | ||
|
|
||
| **Register *Code Templates* in PDSC File:** | ||
|
|
||
|
|
@@ -319,13 +319,13 @@ solution: | |
| ``` | ||
|
|
||
| !!! Note | ||
| The [CMSIS-RTX](https://github.com/ARM-software/CMSIS-RTX) and [MDK-Middleware](https://github.com/ARM-software/MDK-Middleware) pack contains several *code templates* that exemplify the overall structure. | ||
| The [CMSIS-RTX](https://github.com/ARM-software/CMSIS-RTX) and [MDK-Middleware](https://github.com/ARM-software/MDK-Middleware) packs contain several *code templates* that exemplify the overall structure. | ||
|
|
||
| ## Pack Generation | ||
|
|
||
| Packs should be generated using scripts. Several scripts are available on [github.com/open-cmsis-pack](https://github.com/open-cmsis-pack): | ||
|
|
||
| - [gen-pack](https://github.com/Open-CMSIS-Pack/gen-pack) is library for scripts creating software packs. | ||
| - [gen-pack](https://github.com/Open-CMSIS-Pack/gen-pack) is a library for scripts creating software packs. | ||
| - [gen-pack-action](https://github.com/Open-CMSIS-Pack/gen-pack-action) is a GitHub workflow action generating documentation and software packs. | ||
|
|
||
| To start a pack, add a [`*.PDSC` file](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/packFormat.html) with meta information and configure the above scripts. | ||
|
|
||