Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Simplified Generator Proposal, Removed manual file duplicates #1106

Merged
merged 5 commits into from
Sep 5, 2023
Merged

Simplified Generator Proposal, Removed manual file duplicates #1106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1b035d1
Added: Simplify Generator Proposal
ReinhardKeil Sep 1, 2023
387a0e5
Added abs paths for build info files.
ReinhardKeil Sep 1, 2023
c336f00
fixed MarkDown formatting issues
ReinhardKeil Sep 1, 2023
2dd5e8b
Refinement of Simplified Generator Proposal
ReinhardKeil Sep 4, 2023
fd15cf8
clearifications
ReinhardKeil Sep 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 2 additions & 107 deletions tools/projmgr/docs/Manual/Build-Operation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,108 +1,3 @@
# Build Operation
# Note

<!-- markdownlint-disable MD009 -->
<!-- markdownlint-disable MD013 -->
<!-- markdownlint-disable MD036 -->

The following chapter explains the overall build process that of the CMSIS-Toolbox and how to add a new compiler toolchain.

**Table of Contents**

- [Build Operation](#build-operation)
- [Build Process Overview](#build-process-overview)
- [`csolution` tool](#csolution-tool)
- [`cbuild` tool](#cbuild-tool)
- [Add Toolchain to CMSIS-Toolbox](#add-toolchain-to-cmsis-toolbox)
- [Steps](#steps)
- [CMake Variables](#cmake-variables)
- [`BRANCHPROT` Values](#branchprot-values)

## Build Process Overview

The section below describes the overall process to add a new compiler toolchain to the CMSIS-Toolbox.

### `csolution` tool

The [**csolution - CMSIS Project Manager**](Overview.md) processes user [**Input Files** (in YAML format)](YML-Input-Format.md) and the `*.pdsc` metadata files of **Software Packs** and performs the following operations:

- Generate build information in the [**Project Area**](Overview.md#project-area) with the following files: [`*.cbuild-idx.yml`, `*.cbuild.yml`](YML-CBuild-Format.md), and `*.cprj` files for the **cbuild** tool.
- Generate header files in the [**RTE Directory**](Overview.md#rte-directory-structure) for each [context](YML-Input-Format.md#context) with the following files: [RTE_components.h](Overview.md#rte_componentsh) and pre-include files from the `*.pdsc` metadata.
- [Copy the configuration files](Overview.md#plm-of-configuration-files) from selected software components to the [**RTE Directory**](Overview.md#rte-directory-structure).

The picture below outlines these operations.

![Operation of `csolution` tool](./images/csolution-operation.png "Operation of `csolution` tool")

### `cbuild` tool

The [**cbuild - Build Manager**](../../../buildmgr/docs/cbuild.md) uses a `*.cprj` build information files to perform the following operations:

- Generate a `CMakeList.txt` file that includes a `compiler_name.<version>.cmake` file for toolchain specific configuration. This file contains the complete build information for a `*.cproject.yml` file and describes how to build a binary image or a library file.
- This `CMakeList.txt` file is then processed by the `CMake` tool to generate the `build.ninja` file with the actual build commands.
- This `build.ninja` file is then used by the `Ninja` tool to generate the binary image or a library file with the selected toolchain.

The picture below outlines these operations.

![Operation of `csolution` tool](./images/cbuild-operation.png "Operation of `csolution` tool")

## Add Toolchain to CMSIS-Toolbox

The following section explains how to add a compiler toolchain to the CMSIS-Toolbox.

### Steps

The section below describes the steps to add a new compiler toolchain to the CMSIS-Toolbox.

1. Define a `compiler_name` for the new compiler toolchain, i.e. `CLang`.
2. Add this `compiler_name` to the `"CompilerType":` in the schema file [`./tools/projmgr/schemas/common.schema.json`](https://github.com/Open-CMSIS-Pack/devtools/blob/main/tools/projmgr/schemas/common.schema.json).
3. Create a new CMake file in [`./tools/buildmgr/cbuildgen/config`](https://github.com/Open-CMSIS-Pack/devtools/tree/main/tools/buildmgr/cbuildgen/config) with the naming convention `compiler_name.<version>.cmake`.
4. Map with the file `compiler_name.<version>.cmake`. the **CMake** input variables to the **CMake** toolchain variables.
- Use an existing `*.cmake` file, i.e. `GCC.<version>.cmake` as reference.

### CMake Variables

The `CMakeLists.txt` file sets the following **CMake** input variables that should be processed by `compiler_name.<version>.cmake`.

CMake Variable | Possible Values | Description
:------------------------------------------------|:--------------------------|:-----------------------
`BYTE_ORDER` | Little-endian, Big-endian | [Endian processor configuration](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#Dendian)
`CPU` | [DCoreEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DcoreEnum) | Processor core selection
`FPU` | [DfpuEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DfpuEnum) | Floating point unit support
`DSP` | [DdspEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DdspEnum) | DSP instruction set support
`TZ` | [DtzEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DtzEnum) | TrustZone support
`SECURE` | [DsecureEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DsecureEnum) | Software model selection
`MVE` | [DmveEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DmveEnum) | MVE instruction set support
`BRANCHPROT` | [`BRANCHPROT` values](#branchprot-values) | [Branch protection
`OPTIMIZE` | [Optimize values](YML-Input-Format.md#optimize) | Generic optimize levels for code generation
`WARNINGS` | [Warnings values](YML-Input-Format.md#warnings) | Control warning level for compiler diagnostic
`DEBUG` | [Debug values](YML-Input-Format.md#debug) | Control the generation of debug information
`DEFINES` | [Define symbols](YML-Input-Format.md#define) | List of symbol #define statements

#### `BRANCHPROT` Values

The following table lists the possible values for the CMake variable `BRANCHPROT`.

Values | Description
--------------|------------------------------
NO_BRANCHPROT | Branch protection not used
BTI | Using BTI (Branch Target ID)
BTI_SIGNRET | Using BTI + Sign Return

The `compiler_name.<version>.cmake` sets the following **CMake** variables to specify the toolchain and select toolchain options.

CMake Variable | Description
:------------------------------------------------|:-----------------------
`ASM_CPU`, `CC_CPU`, `CXX_CPU` | Device selection set according to the combination of device attributes (`CPU`, `FPU`, `DSP`, `MVE`, etc.)
`AS_LEG_CPU`, `AS_ARM_CPU`, `AS_GNU_CPU` | Similar to the previous item but for assembly dialect variants (if applicable)
`ASM_FLAGS`, `CC_FLAGS`, `CXX_FLAGS`, `LD_FLAGS` | Flags applicable to all modules of the given language
`CC_SECURE`, `LD_SECURE` | Flags applicable only for secure projects
`_PI` | Pre-include option
`_ISYS` | system include option
`LIB_PREFIX` | Generated library name prefix
`LIB_SUFFIX` | Generated library name suffix
`EXE_SUFFIX` | Generated executable name suffix
`ELF2HEX` | Flags for ELF to HEX conversion
`ELF2BIN` | Flags for ELF to BIN conversion
`CMAKE_C_COMPILER_ID` | CMake compiler identifier
`CMAKE_C_COMPILER_VERSION` | CMake compiler version

Document moved to [CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-operation.md)
64 changes: 2 additions & 62 deletions tools/projmgr/docs/Manual/Linker-Script-Management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,63 +1,3 @@
# Linker Script Management
# Note

<!-- markdownlint-disable MD009 -->
<!-- markdownlint-disable MD013 -->
<!-- markdownlint-disable MD036 -->

**Table of Contents**

- [Linker Script Management](#linker-script-management)
- [Overview](#overview)
- [Linker Script Preprocessing](#linker-script-preprocessing)
- [Automatic Linker Script generation](#automatic-linker-script-generation)
- [File locations](#file-locations)
- [User Modifications to Memory Regions](#user-modifications-to-memory-regions)
- [Linker Script Templates](#linker-script-templates)

## Overview

A Linker Script contains a series of Linker directives that specify the available memory and how it should be used by a project. The Linker directives reflect exactly the available memory resources and memory map for the project context.

The following sequence describes the Linker Script management of the **csolution - CMSIS Project Manager**:

1. The [`linker:`](YML-Input-Format.md#linker) node specifies an explicit linker script and/or memory regions header file. This overrules linker scripts that are part of software components or specified using the `file:` notation.

2. If no [`linker:`](YML-Input-Format.md#linker) node is used, a linker script file can be provided as part of software components. The extensions `.sct`, `.scf`, `.ld`, and `.icf` are recognized as Linker Script files.

3. If no Linker script is found, a [Linker Script is generated](#automatic-linker-script-generation) based on information that is provided by the `<memory>` element in Device Family Packs (DFP) and Board Support Packs (BSP).

## Linker Script Preprocessing

A Linker Script file is preprocessed when a `regions:` header file is specified in the [`linker:`](YML-Input-Format.md#linker) node or when the [Linker Script file is automatically generated](#automatic-linker-script-generation). A standard C preprocessor is used to create the final linker script as shown below.

![Linker Script File Generation](./images/linker-script-file.png "Linker Script File Generation")

## Automatic Linker Script generation

If a project context does not specify any linker script a `regions_<device_or_board>.h` is generated and a toolchain specific linker script template is used.

If `regions_<device_or_board>.h` is **not** available, it is generated based on information of the software packs using the:

- [`<device>` - `<memory>` element in the DFP](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_boards_pg.html#element_board_memory)
- [`<board>` - `<memory>` element in the BSP](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_memory)

### File locations

The file `regions_<device_or_board>.h` is generated in the [RTE directory](Overview.md#rte-directory-structure) path `\RTE\Device\<device>`. The actual file name is extended with:

- `Bname` when the `*.cproject.yml` file uses in the project context a [`board:`](YML-Input-Format.md#board-name-conventions) specification, i.e. `regions_IMXRT1050-EVKB.h`
- `Dname` name when the `*.cproject.yml` file uses in the project context only a [`device:`](YML-Input-Format.md#device-name-conventions) specification, i.e. `regions_stm32u585xx.h`.

### User Modifications to Memory Regions

The file `regions_<device_or_board>.h` can be modified by the user as it might be required to adjust the memory regions or give additional attributes (such as `noinit`). Therefore this file should have [Configuration Wizard Annotations](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/configWizard.html).

### Linker Script Templates

The following compiler specific Linker Script files are used when no explicit file is specified. The files are located in the directory `<cmsis-toolbox-installation-dir>/etc` of the CMSIS-Toolbox.

Linker Script Template | Linker control file for ...
:-----------------------|:-----------------------------
ac6_linker_script.sct | Arm Compiler version 6
gcc_linker_script.ld | GCC Compiler
iar_linker_script.icf | IAR Compiler
Content moved to [CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-overview.md#linker-script-management)
Loading
Loading