Skip to content

Commit

Permalink
Documentation update for CMSIS-Toolbox 2.7
Browse files Browse the repository at this point in the history 
Covers also fixes for:
- Open-CMSIS-Pack#209
- Open-CMSIS-Pack/devtools#1549
- Open-CMSIS-Pack/devtools#902
  • Loading branch information
@ReinhardKeil
ReinhardKeil committed Dec 17, 2024
1 parent 717c56b commit a83e840
Show file tree
Hide file tree
Showing 18 changed files with 398 additions and 651 deletions.
78 changes: 68 additions & 10 deletions docs/CreateApplications.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,64 @@ A [template *linker script file*](build-overview.md#linker-script-templates) is
// <i> Note: DMA descriptors and buffers are in this region
```

### Troubleshooting

The following section explains how to fix common linker problems.

**Error: L6236E: No section matches selector - no section to be FIRST/LAST**

Some devices (for example the NXP RT1064) use custom (non-CMSIS) assembly startup code. This is not compatible with the [default linker script](build-overview.md#linker-script-templates) that assume [C Startup code](https://arm-software.github.io/CMSIS_6/v6.0.0/Core/startup_c_pg.html) with standard CMSIS definitions.

This problem can be solved by:

- Using the linker script provided by the device vendor.
- Change the linker script source file `ac6_linker_script.sct.src` that is local in your project, for example as shown below:

```txt
ER_ROM0 __ROM0_BASE __ROM0_SIZE {
*(.isr_vector, +First)
*(InRoot$$Sections)
*(+RO +XO)
}
```

**Using RAM1 .. RAM3 Areas**

Currently there is a problem with the default AC6 linker script template. It does not use by default the RAM1 .. RAM3 area.

A potential solution is discussed [here](https://github.com/Open-CMSIS-Pack/devtools/issues/1778#issuecomment-2356071535). The investigation is currently ongoing.

**Duplicate Heap definition in Assembler startup file**

When using memory allocation functions (i.e. `malloc`), the application ends in a hard fault handler. This is typically caused by different methods of stack and heap definitions.
The Arm Compiler offers [three ways to configure stack and heap](https://developer.arm.com/documentation/100073/0623/The-Arm-C-and-C---Libraries/Stack-and-heap-memory-allocation-and-the-Arm-C-and-C---libraries/Stack-pointer-initialization-and-heap-bounds).

- Use a scatter file to define `ARM_LIB_STACKHEAP`, `ARM_LIB_STACK`, or `ARM_LIB_HEAP` regions.
- Use the symbols `__initial_sp`, `__heap_base`, and `__heap_limit`.
- Implement `__user_setup_stackheap()` or `__user_initial_stackheap()`.

!!! Warning
You have to choose one of these three ways.

The [C startup code](https://arm-software.github.io/CMSIS_6/latest/Core/startup_c_pg.html) recommended by CMSIS Version 6 uses the linker scatter file for stack and heap definition. The C startup code is generic and works across all toolchains that are supported by the CMSIS-Toolbox.

However, some assembler startup files define stack and heap with other methods, for example by using the symbols `__initial_sp`, `__heap_base`, and `__heap_limit`.

There are two options to solve the problem.

1. Remove the stack and heap definition in the assembler startup code.

2. Disable in the [Regions Header File](#regions-header-file) the stack and heap definition by setting `__STACK_SIZE` and `__HEAP_SIZE` to 0 as shown below.

```txt
// <h> Stack / Heap Configuration
// <o0> Stack Size (in Bytes) <0x0-0xFFFFFFFF:8>
// <o1> Heap Size (in Bytes) <0x0-0xFFFFFFFF:8>
#define __STACK_SIZE 0x00000000
#define __HEAP_SIZE 0x00000000
// </h>
```

## Software Components

A software component encapsulates a set of related functions. By offering API headers, it provides interfaces to other software components or to the user application.
Expand Down Expand Up @@ -304,20 +362,20 @@ ToDo: A potential improvement is to use the command `csolution list components`
The steps to create an application based on software components are:

1. Step: **Select software components**
- Install the software pack that provides the required functionality (this could be based on pack datasheets) and identify the required software component(s).
- Add the pack and the component to your `*.cproject.yml` file.
- Run `csolution *.csolution.yml list dependencies` to identify other required software components.
- Run `csolution list components --filter` to identify packs that provide this software components.
- Repeat this step until all software components are part of your project.
- Install the software pack that provides the required functionality (this could be based on pack datasheets) and identify the required software component(s).
- Add the pack and the component to your `*.cproject.yml` file.
- Run `csolution *.csolution.yml list dependencies` to identify other required software components.
- Run `csolution list components --filter` to identify packs that provide this software components.
- Repeat this step until all software components are part of your project.

2. Step: **Configure software components**
- Run `csolution *.csolution.yml update-rte` to copy configuration files into the [RTE directory](./build-overview.md#rte-directory-structure).
- Set the parameters in the configuration files for your application.
- Run `csolution *.csolution.yml update-rte` to copy configuration files into the [RTE directory](./build-overview.md#rte-directory-structure).
- Set the parameters in the configuration files for your application.

3. Step: **Use software components in application program**
- User code templates provide a starting point for your application.
- Copy these template files to your project directory add add it to your `*.cproject.yml` file.
- Adjust the code in the user template files as required.
- User code templates provide a starting point for your application.
- Copy these template files to your project directory add add it to your `*.cproject.yml` file.
- Adjust the code in the user template files as required.

### Example: Network Stack

Expand Down
35 changes: 17 additions & 18 deletions docs/CubeMX.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ Directory `STM32CubeMX/MyBoard` | Content
`STM32CubeMX/GCC` | Project files for GCC; only startup code and linker scripts are used for *csolution projects*.
`STM32CubeMX/MDK-ARM` | Project files for MDK version 5; only startup code and linker scripts are used for *csolution projects*.

[!NOTE]
!!! Note
CubeMX generates only the directory for the selected toolchain which is either `STM32CubeMX/EWARM`, `STM32CubeMX/GCC`, or `STM32CubeMX/MDK-ARM`.

**Content of Generator Import File: `CubeMX.cgen.yml`**
Expand Down Expand Up @@ -157,7 +157,10 @@ Many applications require an RTOS kernel. By default, CubeMX implements interrup

Adding an RTOS kernel requires these steps:

1. **Add the RTOS kernel to application** (in this case RTX)
### Step 1: Add RTOS

The example below adds the [CMSIS-RTX](https://github.com/ARM-software/CMSIS-RTX) RTOS kernel to a project.
Other kernels require different components and packs, but the concept is similar.

**File: `CubeMX.cproject.yml`**

Expand All @@ -176,12 +179,9 @@ project:
- component: CMSIS:OS Tick:SysTick # OS Tick implementation for RTOS
```

!!! Note
The example above uses CMSIS-RTX as the RTOS kernel, other kernels require different components and packs, but the concept is similar.
### Step 2: Configure interrupt handlers

2. **Configure interrupt handlers in CubeMX**

Run CubeMX with:
Configure the interrupt handlers by running CubeMX with:

```bash
csolution CubeMX.csolution.yml run --generator CubeMX --context CubeMX.Debug+MyBoard
Expand Down Expand Up @@ -278,16 +278,15 @@ CMSIS-Driver | Provided by [CMSIS-Driver_STM32](https://gith
To migrate existing projects that where using the previous STM32CubeMX integration (based on `*.gpdsc` files) use the following steps:

1. Remove all `component: Keil::Device:xxx` from the `*.cproject.yml` file.

2. Add the `component: Device:CubeMX` to the `*.cproject.yml` file.
3. Use `csolution run *.csolution.yml -g CubeMX` to initialize the directory structure.
4. Replace the file `STM32CubeMX.ioc` with the file `STCubeGenerated.ioc` from the previous project.
5. Copy source and include files from previous location as they may contain user modifications.
6. Use `csolution run *.csolution.yml -g CubeMX` to generated the output from the previous STM32CubeMX project.
7. Update the configuration in STM32CubeMX:
- In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to match the compiler selection in the csolution project.
- In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`.
- Click `GENERATE CODE` to complete the migration.
- In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to match the compiler selection in the csolution project.
- In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`.
- Click `GENERATE CODE` to complete the migration.

### uVision - Update STM32 DFP Packs

Expand All @@ -302,9 +301,9 @@ New `STM32*_DFP` software packs that contain in the release information **Update
4. Open the dialog *Manage - Run-Time Environment* again.
5. Select the component `Device:CubeMX` and start STM32CubeMX with the `play` button.
6. Update the configuration in STM32CubeMX:
- In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to `MDK-ARM`.
- In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`.
- Click `GENERATE CODE` to complete the migration.
- In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to `MDK-ARM`.
- In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`.
- Click `GENERATE CODE` to complete the migration.

**Starting a new project** works similar with these steps:

Expand All @@ -314,7 +313,7 @@ New `STM32*_DFP` software packs that contain in the release information **Update
2. Open the dialog *Manage - Run-Time Environment*.
3. Select the component `Device:CubeMX` and start STM32CubeMX with the `play` button.
4. Create a new device configuration in STM32CubeMX:
- Follow the instructions of STM32CubeMX and verify settings.
- In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to `MDK-ARM`.
- In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`.
- Click `GENERATE CODE` to complete the migration.
- Follow the instructions of STM32CubeMX and verify settings.
- In the tab `Project Manager - Project` set *Project Settings - Toolchain/IDE* to `MDK-ARM`.
- In the tab `Project Manager - Code Generator` under *STM32Cube MCU packages and embedded software packs* select `Copy only necessary library files`.
- Click `GENERATE CODE` to complete the migration.
Loading

0 comments on commit a83e840

Please sign in to comment.