| This module provides the required STM32cube packages, dtsi files and libraries |
| needed to build a Zephyr application running on STM32 silicon. |
| |
| Packages, dtsi files and libraries are updated regularly in order for STM32 |
| users to benefit from the latest STM32Cube versions, features and bug fixes. |
| Updates are generally done once in each Zephyr release, preferably soon after |
| the opening of the merge window to give time to users to use it, potentially |
| report issues if some are faced and get them fixed before the new version in |
| released. |
| |
| STM32Cube packages |
| ****************** |
| |
| How to introduce a new version of stm32cube: |
| ============================================ |
| Original STM32Cube tree structure has been modified to a minimum |
| structure for a better fit into Zephyr. |
| STM32Cube is divided into drivers and soc section, with: |
| |
| .. code-block:: none |
| |
| drivers/ |
| include/ contains Cube HAL/LL files from: Drivers/STM32YYxx_HAL_Driver/Inc/* |
| src/ contains: Drivers/STM32YYxx_HAL_Driver/Src/* |
| soc/ contains STM32 CMSIS files from |
| *Drivers/CMSIS/Device/ST/STM32F1xx/Include/* |
| *Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/system_stm32f1xx.c |
| |
| Additionally ``driver/include/stm32f1xx_hal_conf_template.h`` is renamed into |
| ``driver/include/stm32f1xx_hal_conf.h`` |
| |
| If there are changes in the number of *.c files the Kconfig file in the |
| stm32cube directory and the ``CMakeLists.txt`` files in the stm32yyxx/ directories |
| will have to be updated. If *.c have been removed drivers that used them will |
| also have to be updated. |
| |
| IMPORTANT: |
| ---------- |
| STM32Cube, as an external library, is not supposed to be modified. |
| In practice, it might be required to patch it. |
| When updating a STM32Cube package to a new version, please have a look |
| to the patch list in dedicated README file, to make sure you don't overwrite |
| some earlier modifications of the package. Furthermore, make sure to run the |
| ``genllheaders.py`` script in order to make sure generic LL API headers are |
| up-to-date. |
| In case of doubt, contact Zephyr code owner for stm32cube. |
| |
| |
| How to use STM32Cube: |
| ===================== |
| In order to enjoy ST CMSIS definitions, ``CONFIG_HAS_STM32CUBE`` should be defined |
| and ``stm32yyxx.h`` should be included in ``soc.h`` |
| |
| .. code-block:: c |
| |
| #include <stm32f1xx.h> |
| |
| Additionally, in order to use STM32Cube LL, you should include the provided |
| generic LL headers ``stm32_ll_foo.h`` directly in the file using the LL API: |
| |
| .. code-block:: c |
| |
| #include <stm32_ll_usart.h> |
| |
| Drivers and applications that need functions from the STM32Cube HAL/LL C-files |
| will need to add the appropriate select entries in their Kconfig files. |
| For example when functions from ``stm32f4xx_hal_uart.c`` are used, the following |
| entry should apear in driver's Kconfig file. |
| |
| .. code-block:: none |
| |
| select USE_STM32_HAL_UART |
| |
| should be added to the Kconfig file. |
| |
| |
| And if the driver for example needs functions from the LL I2C C-files, the |
| driver Kconfig file should include the following entry |
| |
| .. code-block:: none |
| |
| select USE_STM32_LL_I2C |
| |
| |
| Use STM32Cube in your application: |
| ================================== |
| It may happen that you want to access STM32Cube APIs in your application, |
| either because it is not available as a zephyr API or because you want to |
| by-pass use of existing Zephyr API. |
| In this case, you need to create a Kconfig file in your application which |
| contains the following: |
| |
| .. code-block:: none |
| |
| mainmenu "MYAPP" |
| |
| source "Kconfig.zephyr" |
| config MYAPP_STM32 |
| default y |
| bool |
| select USE_STM32_HAL_FOO |
| select USE_STM32_LL_BAR |
| |
| Additionally, you need to add the following includes: |
| |
| .. code-block:: c |
| |
| #include <soc.h> |
| #include <stm32_ll_bar.h> |
| |
| .dtsi files |
| *********** |
| |
| In order to provide STM32 boards pin configuration using device tree, |
| *-pinctrl.dtsi are made available under dts/st directory. For each STM32 SoC |
| package a complete and correct -pcintrl.dtsi is available. Generation use as |
| input the `STM32 Open Pin Data <https://github.com/STMicroelectronics/STM32_open_pin_data>`_ |
| database. |
| |
| *-pinctrl.dtsi files are generated using generation scripts available in this |
| repo under scripts/genpinctrl and can be generated by running:: |
| |
| python3 scripts/genpinctrl/genpinctrl.py -p /path/to/stm32-open-pin-data-repository |
| |
| New set of -pinctrl.dtsi files could be generated following availability of a |
| new version of STM32 Open Pin Data or a change in the generation script |
| configuration files. |
| |
| STM32Cube based libraries: |
| ************************** |
| |
| For some specific features, in order to benefit from already available and |
| validated code. Libraries from STM32Cube packages are extracted and made |
| available in this module under `lib` folder. |
| |
| No script is available for these libraries, so update is done manually, but |
| it should follow the same rhythm than STM32Cube packages. |