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 1 commit
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
57 changes: 43 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,17 +88,22 @@ $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:
```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.
Expand All @@ -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::<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 @@ -124,7 +132,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 @@ -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
## <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.*

[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 @@ -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::<FAMILY>::<CORE>`, `HAL::STM32::<FAMILY>::<CORE>::<DRIVER>`, 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
Expand All @@ -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
)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for all "examples", shouldn't we just link to the example folder ? I mean the readme is here to explain the targets but we have dedicated examples so we should not duplicate the information here.
@Hish15 @robamu what do you think ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's okay if the README has a few examples as well to have a general idea how the targets are used. I added that example because it is one that uses two cores.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for delay, we have had less time to dedicate to this repo.
In my experience duplicating too much information in the documentation often ends with documentation not up to date when the code evolves. This is why I think a link to example is better than a copy.

@Hish15 any thoughts about this ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good. I'll look into it

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I specifically added the dual core example to have at least one simple example for a dual core.
Maybe it would be a good idea to add the H7M7 example to the blinky application?

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

### Building

```sh
cmake -DCMAKE_TOOLCHAIN_FILE=<path_to_gcc_stm32.cmake> -DCMAKE_BUILD_TYPE=Debug <path_to_sources>
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::<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