1This module provides the required STM32cube packages, dtsi files and libraries
2needed to build a Zephyr application running on STM32 silicon.
3
4Packages, dtsi files and libraries are updated regularly in order for STM32
5users to benefit from the latest STM32Cube versions, features and bug fixes.
6Updates are generally done once in each Zephyr release, preferably soon after
7the opening of the merge window to give time to users to use it, potentially
8report issues if some are faced and get them fixed before the new version in
9released.
10
11STM32Cube packages
12******************
13
14How to introduce a new version of stm32cube:
15============================================
16Original STM32Cube tree structure has been modified to a minimum
17structure for a better fit into Zephyr.
18STM32Cube is divided into drivers and soc section, with:
19
20.. code-block:: none
21
22   drivers/
23       include/ contains Cube HAL/LL files from: Drivers/STM32YYxx_HAL_Driver/Inc/*
24       src/ contains: Drivers/STM32YYxx_HAL_Driver/Src/*
25   soc/ contains STM32 CMSIS files from
26       *Drivers/CMSIS/Device/ST/STM32F1xx/Include/*
27       *Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/system_stm32f1xx.c
28
29Additionally ``driver/include/stm32f1xx_hal_conf_template.h`` is renamed into
30``driver/include/stm32f1xx_hal_conf.h``
31
32If there are changes in the number of *.c files the Kconfig file in the
33stm32cube directory and the ``CMakeLists.txt`` files in the stm32yyxx/ directories
34will have to be updated. If *.c have been removed drivers that used them will
35also have to be updated.
36
37IMPORTANT:
38----------
39STM32Cube, as an external library, is not supposed to be modified.
40In practice, it might be required to patch it.
41When updating a STM32Cube package to a new version, please have a look
42to the patch list in dedicated README file, to make sure you don't overwrite
43some earlier modifications of the package. Furthermore, make sure to run the
44``genllheaders.py`` script in order to make sure generic LL API headers are
45up-to-date.
46In case of doubt, contact Zephyr code owner for stm32cube.
47
48
49How to use STM32Cube:
50=====================
51In order to enjoy ST CMSIS definitions, ``CONFIG_HAS_STM32CUBE`` should be defined
52and ``stm32yyxx.h`` should be included in ``soc.h``
53
54.. code-block:: c
55
56   #include <stm32f1xx.h>
57
58Additionally, in order to use STM32Cube LL, you should include the provided
59generic LL headers ``stm32_ll_foo.h`` directly in the file using the LL API:
60
61.. code-block:: c
62
63   #include <stm32_ll_usart.h>
64
65Drivers and applications that need functions from the STM32Cube HAL/LL C-files
66will need to add the appropriate select entries in their Kconfig files.
67For example when functions from ``stm32f4xx_hal_uart.c`` are used, the following
68entry should apear in driver's Kconfig file.
69
70.. code-block:: none
71
72	select USE_STM32_HAL_UART
73
74should be added to the Kconfig file.
75
76
77And if the driver for example needs functions from the LL I2C C-files, the
78driver Kconfig file should include the following entry
79
80.. code-block:: none
81
82	select USE_STM32_LL_I2C
83
84
85Similar to Zephyr, STM32Cube HAL and LL APIs embed asserts which are
86provided for parameters checking. You can benefit from these by enabling
87the following symbols:
88
89.. code-block:: none
90
91     CONFIG_USE_STM32_ASSERT=y
92     CONFIG_ASSERT=y
93
94
95Use STM32Cube in your application:
96==================================
97It may happen that you want to access STM32Cube APIs in your application,
98either because it is not available as a zephyr API or because you want to
99by-pass use of existing Zephyr API.
100In this case, you need to create a Kconfig file in your application which
101contains the following:
102
103.. code-block:: none
104
105   mainmenu "MYAPP"
106
107   source "Kconfig.zephyr"
108   config MYAPP_STM32
109     default y
110     bool
111     select USE_STM32_HAL_FOO
112     select USE_STM32_LL_BAR
113
114Additionally, you need to add the following includes:
115
116.. code-block:: c
117
118   #include <soc.h>
119   #include <stm32_ll_bar.h>
120
121.dtsi files
122***********
123
124In order to provide STM32 boards pin configuration using device tree,
125*-pinctrl.dtsi are made available under dts/st directory. For each STM32 SoC
126package a complete and correct -pcintrl.dtsi is available. Generation use as
127input the `STM32 Open Pin Data <https://github.com/STMicroelectronics/STM32_open_pin_data>`_
128database.
129
130*-pinctrl.dtsi files are generated using generation scripts available in this
131repo under scripts/genpinctrl and can be generated by running::
132
133   python3 scripts/genpinctrl/genpinctrl.py -p /path/to/stm32-open-pin-data-repository
134
135New set of -pinctrl.dtsi files could be generated following availability of a
136new version of STM32 Open Pin Data or a change in the generation script
137configuration files.
138
139STM32Cube based libraries:
140**************************
141
142For some specific features, in order to benefit from already available and
143validated code. Libraries from STM32Cube packages are extracted and made
144available in this module under `lib` folder.
145
146No script is available for these libraries, so update is done manually, but
147it should follow the same rhythm than STM32Cube packages.
148