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

README tweaks #262

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

README tweaks #262

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d0ae99f
README tweaks
robamu Aug 8, 2021
fb13706
Merge remote-tracking branch 'upstream/master' into mueller/readme-tw…
robamu Jun 7, 2022
ee45818
use a link instead of duplication
robamu Jun 8, 2022
6db7c29
use full sentence here
robamu Jun 8, 2022
788b7ab
move CMAKE_TOOLCHAIN_FILE explanation
robamu Jul 8, 2022
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
64 changes: 43 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,9 @@ These configuration options need to be set for the build process to work properl

These configuration variables are optional:

* `CMAKE_TOOLCHAIN_FILE` - Can be `set` in the `CMakeLists.txt` file before the `project` call if
the toolchain file is to be hardcoded for the project instead of being passed as an argument to
the build generation call
* `STM32_TOOLCHAIN_PATH` - where toolchain is located, **default**: `/usr`. Alternatively
you can add the folder containing the toolchain binaries to the system path. If both are given,
the `STM32_TOOLCHAIN_PATH` setting takes precedence
Expand Down Expand Up @@ -90,19 +93,26 @@ $env:TARGET_TRIPLET = arm-none-eabi
$env:STM32_CUBE_<FAMILY>_PATH="<PathToCubeRoot>"
```

## Common usage
## <a id="cmsis"></a> Common usage

First thing that you need to do after toolchain configuration in your `CMakeLists.txt` script is
to find CMSIS package:

First thing that you need to do after toolchain configuration in your `CMakeLists.txt` script is to find CMSIS package:
```cmake
find_package(CMSIS [CMSIS_version] COMPONENTS STM32F4 REQUIRED)
```
You can specify STM32 family or even specific device (`STM32F407VG`) in `COMPONENTS` or omit `COMPONENTS` totally - in that case stm32-cmake will find ALL sources for ALL families and ALL chips (you'll need ALL STM32Cube packages somewhere).
You can specify STM32 family or even specific device (`STM32F407VG`) in `COMPONENTS` or omit
`COMPONENTS` totally - in that case stm32-cmake will find ALL sources for ALL families and
ALL chips (you'll need ALL STM32Cube packages somewhere).

[CMSIS_version] is an optional version requirement. See [find_package documentation](https://cmake.org/cmake/help/v3.13/command/find_package.html?highlight=find%20package#id4). This parameter does not make sense if multiple STM32 families are requested.
[CMSIS_version] is an optional version requirement. See
[find_package documentation](https://cmake.org/cmake/help/v3.13/command/find_package.html?highlight=find%20package#id4).
This parameter does not make sense if multiple STM32 families are requested.

Each STM32 device can be categorized into family and device type groups, for example STM32F407VG is device from `F4` family, with type `F407xx`.
Each STM32 device can be categorized into family and device type groups, for example STM32F407VG
is device from `F4` family, with type `F407xx`.

***Note**: Some devices have two different cores (e.g. STM32H7 has Cortex-M7 and Cortex-M4).
**Note**: Some devices have two different cores (e.g. STM32H7 has Cortex-M7 and Cortex-M4).
For those devices the name used must include the core name e.g STM32H7_M7 and STM32H7_M4.
STM32WB is a multi-cores device even if the second core is not accessible by end user.

Expand All @@ -113,7 +123,10 @@ CMSIS consists of three main components:
* Device-specific linker scripts which requires information about memory sizes (if ASM language is enabled)

stm32-cmake uses modern CMake features notably imported targets and target properties.
Every CMSIS component is CMake's target (aka library), which defines compiler definitions, compiler flags, include dirs, sources, etc. to build and propagate them as dependencies. So in a simple use-case all you need is to link your executable with library `CMSIS::STM32::<device>`:
Every CMSIS component is CMake's target (aka library), which defines compiler definitions,
compiler flags, include dirs, sources, etc. to build and propagate them as dependencies.
So in a simple use-case all you need is to link your executable with library `CMSIS::STM32::<device>`:

```cmake
add_executable(stm32-template main.c)
target_link_libraries(stm32-template CMSIS::STM32::F407VG)
Expand All @@ -126,7 +139,9 @@ CMSIS creates the following targets:
* `CMSIS::STM32::<TYPE>` (e.g. `CMSIS::STM32::F407xx`) - common startup source for device type, depends on `CMSIS::STM32::<FAMILY>`
* `CMSIS::STM32::<DEVICE>` (e.g. `CMSIS::STM32::F407VG`) - linker script for device, depends on `CMSIS::STM32::<TYPE>`

So, if you don't need linker script, you can link only `CMSIS::STM32::<TYPE>` library and provide your own script using `stm32_add_linker_script` function
So, if you don't need the linker script or want to adapt it for your own needs, you can link
only `CMSIS::STM32::<TYPE>` library and provide your own script using `stm32_add_linker_script`
function

***Note**: Because of some families multi-cores architecture, all targets also have a suffix (e.g. STM32H7 has ::M7 or ::M4).
For example, targets created for STM32H747BI will look like `CMSIS::STM32::H7::M7`,
Expand All @@ -144,14 +159,17 @@ newlib-nano by linking against `STM32::Nano::FloatPrint` and/or `STM32::Nano::Fl
It is also possible to combine `STM32::Nano` and `STM32::NoSys`
to have the benefits of reduced code size while not being forced to implement system calls.

## HAL
## <a id="hal"></a> HAL

STM32 HAL can be used similar to CMSIS.

```cmake
find_package(HAL [HAL_version] COMPONENTS STM32F4 REQUIRED)
set(CMAKE_INCLUDE_CURRENT_DIR TRUE)
```
*`CMAKE_INCLUDE_CURRENT_DIR` here because HAL requires `stm32<family>xx_hal_conf.h` file being in include headers path.*

`CMAKE_INCLUDE_CURRENT_DIR` is used here because HAL
requires `stm32<family>xx_hal_conf.h` file being in include headers path.

[HAL_version] is an optional version requirement. See [find_package documentation](https://cmake.org/cmake/help/v3.13/command/find_package.html?highlight=find%20package#id4). This parameter does not make sense if multiple STM32 families are requested.

Expand All @@ -164,29 +182,33 @@ HAL module will search all drivers supported by family and create the following

***Note**: Targets for multi-cores devices will look like `HAL::STM32::<FAMILY>::<CORE>`, `HAL::STM32::<FAMILY>::<CORE>::<DRIVER>`, etc.*

Here is typical usage:
You can find a typical usage of the HAL
[F4 targets here](https://github.com/ObKo/stm32-cmake/blob/master/examples/blinky/CMakeLists.txt#L53).

Here is another usage for a H7 device with the M7 core:

```cmake
add_executable(stm32-blinky-f4 blinky.c stm32f4xx_hal_conf.h)
target_link_libraries(stm32-blinky-f4
HAL::STM32::F4::RCC
HAL::STM32::F4::GPIO
HAL::STM32::F4::CORTEX
CMSIS::STM32::F407VG
target_link_libraries(${TARGET_NAME} PRIVATE
HAL::STM32::H7::M7::RCC
HAL::STM32::H7::M7::GPIO
HAL::STM32::H7::M7::CORTEX
CMSIS::STM32::H743ZI::M7
STM32::NoSys
)
```

### Building

```
$ cmake -DCMAKE_TOOLCHAIN_FILE=<path_to_gcc_stm32.cmake> -DCMAKE_BUILD_TYPE=Debug <path_to_sources>
$ make
```sh
cmake -DCMAKE_TOOLCHAIN_FILE=<path_to_gcc_stm32.cmake> -DCMAKE_BUILD_TYPE=Debug <path_to_sources>
cmake --build .
```

## Linker script & variables

CMSIS package will generate linker script for your device automatically (target `CMSIS::STM32::<DEVICE>`). To specify a custom linker script, use `stm32_add_linker_script` function.
CMSIS package will generate linker script for your device automatically (target
`CMSIS::STM32::<DEVICE>`). To specify a custom linker script, use the
`stm32_add_linker_script` function.

## Useful CMake functions

Expand Down