You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
Thomas Stranger d49fb6dbe7 scripts: minor fixes to be able to execute series_update on linux 1 year ago
.github/workflows github: add test workflow 2 years ago
dts dts/st: use a pull-down for SPI SCK pin 1 year ago
lib lib/stm32wb: hci: Update lib to V1.9.0 Cube version 2 years ago
scripts scripts: minor fixes to be able to execute series_update on linux 1 year ago
stm32cube stm32cube/common_ll: Update README with latest versions 1 year ago
zephyr zephyr/module.yml: Declare this repo as a dts_root 2 years ago
.gitignore gitignore: add Python and editor files 2 years ago
CMakeLists.txt Licenses: Add Apache-2.0 SPDX when missing 2 years ago
LICENSE LICENSE: License root file should contain explicit licenses 2 years ago
README.rst readme: update pinctrl instructions 2 years ago

README.rst

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.