From d0ae99f046412f5ad10a97fb7a893268491c8195 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Sun, 8 Aug 2021 16:11:46 +0200 Subject: [PATCH 1/4] README tweaks 1. Additional example for HAL usage with the H7 family using two cores 2. HTML ID achors for headings added 3. Some minor formatting improvements and line breaks 4. Additional usage example for setting the toolchain file --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 43 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index b40fc373..326759c7 100644 --- a/README.md +++ b/README.md @@ -88,17 +88,22 @@ $env:TARGET_TRIPLET = arm-none-eabi $env:STM32_CUBE__PATH="" ``` -## Common usage +## Common usage 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). For those devices the name used must include the core name e.g STM32H7_M7 and STM32H7_M4. @@ -111,7 +116,10 @@ CMSIS consists of three main components: * Device-specific linker scripts which requires information about memory sizes 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::`: +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::`: + ```cmake add_executable(stm32-template main.c) target_link_libraries(stm32-template CMSIS::STM32::F407VG) @@ -124,7 +132,9 @@ CMSIS creates the following targets: * `CMSIS::STM32::` (e.g. `CMSIS::STM32::F407xx`) - common startup source for device type, depends on `CMSIS::STM32::` * `CMSIS::STM32::` (e.g. `CMSIS::STM32::F407VG`) - linker script for device, depends on `CMSIS::STM32::` -So, if you don't need linker script, you can link only `CMSIS::STM32::` 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::` 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`, @@ -142,13 +152,15 @@ 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 +## 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 `stm32xx_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. @@ -162,11 +174,11 @@ HAL module will search all drivers supported by family and create the following ***Note**: Targets for multi-cores devices will look like `HAL::STM32::::`, `HAL::STM32::::::`, etc.* -Here is typical usage: +Here is typical usage for a F4 device: ```cmake -add_executable(stm32-blinky-f4 blinky.c stm32f4xx_hal_conf.h) -target_link_libraries(stm32-blinky-f4 +add_executable(${TARGET_NAME} blinky.c stm32f4xx_hal_conf.h) +target_link_libraries(${TARGET_NAME} HAL::STM32::F4::RCC HAL::STM32::F4::GPIO HAL::STM32::F4::CORTEX @@ -175,16 +187,33 @@ target_link_libraries(stm32-blinky-f4 ) ``` -### Building +Here is another usage for a H7 device with the M7 core: +```cmake +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 +) ``` - $ cmake -DCMAKE_TOOLCHAIN_FILE= -DCMAKE_BUILD_TYPE=Debug - $ make + +### Building + +```sh +cmake -DCMAKE_TOOLCHAIN_FILE= -DCMAKE_BUILD_TYPE=Debug +cmake --build . ``` +You can also ommit the `-DCMAKE_TOOLCHAIN_FILE` argument and use `set (CMAKE_TOOLCHAIN_FILE ...)` +in your `CMakeLists.txt` file + ## Linker script & variables -CMSIS package will generate linker script for your device automatically (target `CMSIS::STM32::`). 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::`). To specify a custom linker script, use the +`stm32_add_linker_script` function. ## Useful CMake functions From ee45818f2c13b30eb66759332ce89935941c4f86 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Wed, 8 Jun 2022 12:04:24 +0200 Subject: [PATCH 2/4] use a link instead of duplication --- README.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 53e18d70..7128266d 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,9 @@ $env:STM32_CUBE__PATH="" ## 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) ``` @@ -107,7 +109,7 @@ 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`. -***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. @@ -176,18 +178,8 @@ HAL module will search all drivers supported by family and create the following ***Note**: Targets for multi-cores devices will look like `HAL::STM32::::`, `HAL::STM32::::::`, etc.* -Here is typical usage for a F4 device: - -```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 - STM32::NoSys -) -``` +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: From 6db7c298033f4d0207f1af39bbc19fae5e0f3bdd Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Wed, 8 Jun 2022 12:07:21 +0200 Subject: [PATCH 3/4] use full sentence here --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7128266d..093bb2d0 100644 --- a/README.md +++ b/README.md @@ -165,7 +165,8 @@ find_package(HAL [HAL_version] COMPONENTS STM32F4 REQUIRED) set(CMAKE_INCLUDE_CURRENT_DIR TRUE) ``` -*`CMAKE_INCLUDE_CURRENT_DIR` here because HAL requires `stm32xx_hal_conf.h` file being in include headers path.* +`CMAKE_INCLUDE_CURRENT_DIR` is used here because HAL +requires `stm32xx_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. From 788b7ab42d702f06d420dc96045eaa15b1c5c534 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Fri, 8 Jul 2022 20:33:23 +0200 Subject: [PATCH 4/4] move CMAKE_TOOLCHAIN_FILE explanation --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 093bb2d0..fb20ed0a 100644 --- a/README.md +++ b/README.md @@ -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 @@ -201,9 +204,6 @@ cmake -DCMAKE_TOOLCHAIN_FILE= -DCMAKE_BUILD_TYPE=Debug cmake --build . ``` -You can also ommit the `-DCMAKE_TOOLCHAIN_FILE` argument and use `set (CMAKE_TOOLCHAIN_FILE ...)` -in your `CMakeLists.txt` file - ## Linker script & variables CMSIS package will generate linker script for your device automatically (target