diff --git a/README.md b/README.md index a7365f8e..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 @@ -90,19 +93,26 @@ $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: -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. @@ -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::`: +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) @@ -126,7 +139,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`, @@ -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 +## 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.* + +`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. @@ -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::::`, `HAL::STM32::::::`, 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= -DCMAKE_BUILD_TYPE=Debug - $ make +```sh +cmake -DCMAKE_TOOLCHAIN_FILE= -DCMAKE_BUILD_TYPE=Debug +cmake --build . ``` ## 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