STMicroelectronics STM32H7 User Manual

Page 1
UM2217
User manual
Description of STM32H7 HAL and low-layer drivers
Introduction
STM32Cube is an STMicroelectronics original initiative to significantly improve developer productivity by reducing development effort, time and cost. STM32Cube covers the STM32 portfolio.
STM32Cube includes:
STM32CubeMX, a graphical software configuration tool that allows the generation of C initialization code using graphical wizards.
A comprehensive embedded software platform, delivered per Series (such as STM32CubeH7 for STM32H7)
The STM32Cube HAL, STM32 abstraction layer embedded software ensuring maximized portability across the
Low-layer APIs (LL) offering a fast light-weight expert-oriented layer which is closer to the hardware than the HAL. LL
APIs are available only for a set of peripherals.
A consistent set of middleware components such as RTOS, USB, TCP/IP and Graphics.
All embedded software utilities, delivered with a full set of examples.
The HAL driver layer provides a simple, generic multi-instance set of APIs (application programming interfaces) to interact with the upper layer (application, libraries and stacks).
The HAL driver APIs are split into two categories: generic APIs, which provide common and generic functions for all the STM32 series and extension APIs, which include specific and customized functions for a given line or part number. The HAL drivers include a complete set of ready-to-use APIs that simplify the user application implementation. For example, the communication peripherals contain APIs to initialize and configure the peripheral, manage data transfers in polling mode, handle interrupts or DMA, and manage communication errors.
The HAL drivers are feature-oriented instead of IP-oriented. For example, the timer APIs are split into several categories following the IP functions, such as basic timer, capture and pulse width modulation (PWM). The HAL driver layer implements run-time failure detection by checking the input values of all functions. Such dynamic checking enhances the firmware robustness. Run-time detection is also suitable for user application development and debugging.
The LL drivers offer hardware services based on the available features of the STM32 peripherals. These services reflect exactly the hardware capabilities, and provide atomic operations that must be called by following the programming model described in the product line reference manual. As a result, the LL services are not based on standalone processes and do not require any additional memory resources to save their states, counter or data pointers. All operations are performed by changing the content of the associated peripheral registers. Unlike the HAL, LL APIs are not provided for peripherals for which optimized access is not a key feature, or for those requiring heavy software configuration and/or a complex upper-level stack (such as USB).
The HAL and LL are complementary and cover a wide range of application requirements:
The HAL offers high-level and feature-oriented APIs with a high-portability level. These hide the MCU and peripheral complexity from the end-user.
The LL offers low-level APIs at register level, with better optimization but less portability. These require deep knowledge of the MCU and peripheral specifications.
All STM32H7 single- and dual-core lines are supported by the same STM32CubeH7 HAL and LL drivers.
The HAL- and LL-driver source code is developed in Strict ANSI-C, which makes it independent of the development tools. It is checked with the CodeSonar® static analysis tool. It is fully documented.
It is compliant with MISRA C®:2012 standard.
This user manual is structured as follows:
Supporting dual-core architectures
Overview of HAL drivers
Overview of low-layer drivers
Cohabiting of HAL and LL drivers
UM2217 - Rev 5 - July 2020 For further information contact your local STMicroelectronics sales office.
www.st.com
Page 2
UM2217
Detailed description of each peripheral driver: configuration structures, functions, and how to use the given API to build your application
UM2217 - Rev 5
page 2/3786
Page 3

1 General information

The STM32CubeH7 MCU Package runs on STM32H7 32-bit microcontrollers based on the Arm® Cortex®-M processor.
Note: Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.
UM2217
General information
UM2217 - Rev 5
page 3/3786
Page 4

2 Acronyms and definitions

Table 1. Acronyms and definitions
Acronym Definition
ADC Analog-to-digital converter
AES Advanced encryption standard
ANSI American national standards institute
API Application programming interface
BSP Board support package
CAN Controller area network
CEC Consumer electronic controller
CMSIS Cortex microcontroller software interface standard
COMP Comparator
CORDIC Trigonometric calculation unit
CPU Central processing unit
CRC CRC calculation unit
CRYP Cryptographic processor
CSS Clock security system
DAC Digital to analog converter
DLYB Delay block
DCMI Digital camera interface
DFSDM Digital filter sigma delta modulator
DMA Direct memory access
DMAMUX Direct memory access request multiplexer
DSI Display serial interface
DTS Digital temperature sensor
ETH Ethernet controller
EXTI External interrupt/event controller
FDCAN Flexible data-rate controller area network unit
FLASH Flash memory
FMAC Filtering mathematical calculation unit
FMC Flexible memory controller
FW Firewall
GFXMMU Chrom-GRC
GPIO General purpose I/Os
GTZC
GTZC-MPCBB GTZC block-based memory protection controller
GTZC-MPCWM GTZC watermark memory protection controller
GTZC-TZIC GTZC TrustZone illegal access controller
GTZC-TZSC GTZC TrustZone security controller
UM2217
Acronyms and definitions
Global TrustZone® controller
UM2217 - Rev 5
page 4/3786
Page 5
Acronyms and definitions
Acronym Definition
HAL Hardware abstraction layer
HASH Hash processor
HCD USB host controller driver
HRTIM High-resolution timer
I2C Inter-integrated circuit
I2S Inter-integrated sound
ICACHE Instruction cache
IRDA Infrared data association
IWDG Independent watchdog
JPEG Joint photographic experts group
LCD Liquid crystal display controler
LTDC LCD TFT Display Controller
LPTIM Low-power timer
LPUART Low-power universal asynchronous receiver/transmitter
MCO Microcontroller clock output
MDIOS Management data input/output (MDIO) slave
MDMA Master direct memory access
MMC MultiMediaCard
MPU Memory protection unit
MSP MCU specific package
NAND NAND Flash memory
NOR NOR Flash memory
NVIC Nested vectored interrupt controller
OCTOSPI Octo-SPI interface
OPAMP Operational amplifier
OTFDEC On-the-fly decryption engine
OTG-FS USB on-the-go full-speed
PKA Public key accelerator
PCD USB peripheral controller driver
PPP STM32 peripheral or block
PSSI Parallel synchronous slave interface
PWR Power controller
QSPI Quad-SPI Flash memory
RAMECC RAM ECC monitoring
RCC Reset and clock controller
RNG Random number generator
RTC Real-time clock
SAI Serial audio interface
SD Secure digital
SDMMC SD/SDIO/MultiMediaCard card host interface
UM2217
UM2217 - Rev 5
page 5/3786
Page 6
Acronym Definition
SMARTCARD Smartcard IC
SMBUS System management bus
SPI Serial peripheral interface
SPDIFRX SPDIF-RX Receiver interface
SRAM SRAM external memory
SWPMI Serial wire protocol master interface
SysTick System tick timer
TIM Advanced-control, general-purpose or basic timer
TSC Touch sensing controller
TZ Arm TrustZone-M
TZEN TrustZone enable Flash user option bit
UART Universal asynchronous receiver/transmitter
UCPD
USART Universal synchronous receiver/transmitter
VREFBUF Voltage reference buffer
WWDG Window watchdog
USB Universal serial bus
USB Type-C® and Power Delivery interface
UM2217
Acronyms and definitions
UM2217 - Rev 5
page 6/3786
Page 7

3 Support of dual-core architectures

The STM32H7 microcontrollers come in two product lines:
Single-core lines, based on an Arm® Cortex®-M7 architecture.
Dual-core lines based on an Arm® Cortex®-M7 and Arm® Cortex®-M4 architecture.
Supporting dual-core architectures with STM32H7 HAL and LL drivers
In STM32H7 dual-core lines, all peripherals are available for both Arm® Cortex®-M7 (CM7) and Arm® Cortex®-M4 (CM4) cores. There is no default peripheral allocation to a given core. There is consequently a great advantage to share the same peripheral drivers between the cores. This mainly targets standard peripherals which features must be available for both cores.
However for most system peripheral HAL drivers (such as RCC, GPIO, FLASH, PWR or HSEM), some features can be present in dual-core line but not in single-core lines.
Other features (such as boot sequence, extended interrupt and event handling, power management) may be configured differently in the two lines.
STM32H7 HAL and LL drivers have consequently been built to support both single- and dual-core architectures, with the following considerations:
DUAL_CORE: this define statement is used to delimit the code (such as defines, functions and macros) that is available only in dual-core architectures. This define statement is automatically available through the STM32 CMSIS dual-core device files stm32h7XYxx.h.
UM2217
Support of dual-core architectures
Figure 1. Example of code portion used for dual-core architectures
CORE_CM4: this define statement is used to delimit the code that contains a specific configuration/code portion applying to the Arm® Cortex®-M4 core. This define statement shall be available in the compiler preprocessor define list at application level for the Arm® Cortex®-M4 target configuration.
CORE_CM7: this define statement is used to delimit the code containing a specific configuration/code portion applying to the Arm® Cortex®-M7 core. This define statement shall be available in the compiler preprocessor defines list at application level for the Arm® Cortex®-M7 target configuration.
Dual-core architecture applications
The dual-core examples and applications available within the STM32CubeH7 MCU Package are structured as follows:
One project (one workspace) per example/application, in order to be compatible with the single-core architecture.
Two target project configurations per workspace (one per core), named STM32YYxx_CM7 and STM32YYxx_CM4.
UM2217 - Rev 5
page 7/3786
Page 8
UM2217
Support of dual-core architectures
The target configurations can be configured individually by setting the following options: target device, linker options, read-only (RO) and read/write (RW) zones, preprocessor symbols and defines (CORE_CM7 , CORE_CM4). This allows compiling user code linked and programmed separately for each core, and generating two binaries, CM7 and CM4.
Figure 2. Dual-core project structure
The applicative layer source files of dual-core examples and applications is organized as follows:
Two separate folders, CM4 and CM7 for Arm® Cortex®-M4 and Arm® Cortex®-M7, respectively.
Each CM4 and CM7 folder includes in turns the following subfolders:
\Inc that hosts all the header files for Arm® Cortex®-M4 and -M7.
\Src that hosts the source code files for Arm® Cortex®-M4 and -M7.
A \common folder, with \Inc and \Src subfolders, that hosts the common header and source files for both cores.
UM2217 - Rev 5
page 8/3786
Page 9
Figure 3. Dual-core example structure
UM2217
Support of dual-core architectures
UM2217 - Rev 5
page 9/3786
Page 10

4 Overview of HAL drivers

The HAL drivers are designed to offer a rich set of APIs and to interact easily with the application upper layers.
Each driver consists of a set of functions covering the most common peripheral features. The development of each driver is driven by a common API which standardizes the driver structure, the functions and the parameter names.
The HAL drivers include a set of driver modules, each module being linked to a standalone peripheral. However, in some cases, the module is linked to a peripheral functional mode. As an example, several modules exist for the USART peripheral: UART driver module, USART driver module, SMARTCARD driver module and IRDA driver module.
The HAL main features are the following:
Cross-family portable set of APIs covering the common peripheral features as well as extension APIs in case of specific peripheral features.
Three API programming models: polling, interrupt and DMA.
APIs are RTOS compliant:
Fully reentrant APIs
Systematic usage of timeouts in polling mode
Support of peripheral multi-instance allowing concurrent API calls for multiple instances of a given peripheral (such as USART1 or USART2)
All HAL APIs implement user-callback functions mechanism:
Peripheral Init/DeInit HAL APIs can call user-callback functions to perform peripheral system level
Initialization/De-Initialization (clock, GPIOs, interrupt, DMA)
Peripherals interrupt events
Error events
Object locking mechanism: safe hardware access to prevent multiple spurious accesses to shared resources.
Timeout used for all blocking processes: the timeout can be a simple counter or a timebase.
UM2217
Overview of HAL drivers
UM2217 - Rev 5
page 10/3786
Page 11

4.1 HAL and user-application files

4.1.1 HAL driver files

HAL drivers are composed of the following set of files:
File Description
Main peripheral/module driver file.
stm32h7xx_hal_ppp.c
stm32h7xx_hal_ppp.h
stm32h7xx_hal_ppp_ex.c
stm32h7xx_hal_ppp_ex.h
stm32h7xx_hal.c
stm32h7xx_hal.h stm32h7xx_hal.c header file
stm32h7xx_hal_msp_template.c
stm32h7xx_hal_conf_template.h Template file allowing to customize the drivers for a given application.
stm32h7xx_hal_def.h
It includes the APIs that are common to all STM32 devices.
Example: stm32h7xx_hal_adc.c, stm32h7xx_hal_irda.c.
Header file of the main driver C file
It includes common data, handle and enumeration structures, define statements and macros, as well as the exported generic APIs.
Example:stm32h7xx_hal_adc.h,stm32h7xx_hal_irda.h.
Extension file of a peripheral/module driver. It includes the specific APIs for a given part number or family, as well as the newly defined APIs that overwrite the default generic APIs if the internal process is implemented in different way.
Example:stm32h7xx_hal_adc_ex.c,stm32h7xx_hal_flash_ex.c.
Header file of the extension C file.
It includes the specific data and enumeration structures, define statements and macros, as well as the exported device part number specific APIs
Example: stm32h7xx_hal_adc_ex.h,stm32h7xx_hal_flash_ex.h.
This file is used for HAL initialization and contains DBGMCU, Remap and Time Delay based on SysTick APIs.
Template file to be copied to the user application folder.
It contains the MSP initialization and de-initialization (main routine and callbacks) of the peripheral used in the user application.
Common HAL resources such as common define statements, enumerations, structures and macros.
UM2217
HAL and user-application files
Table 2. HAL driver files

4.1.2 User-application files

The minimum files required to build an application using the HAL are listed in the table below:
File Description
system_stm32h7xx.c
startup_stm32h7xx.s
stm32h7xx_flash.icf
(optional)
stm32h7xx_hal_msp.c
UM2217 - Rev 5
Table 3. User-application files
This file contains SystemInit() that is called at startup just after reset and before branching to the main program. It does not configure the system clock at startup (contrary to the standard library). This is to be done using the HAL APIs in the user files. It allows relocating the vector table in internal SRAM.
Toolchain specific file that contains reset handler and exception vectors.
For some toolchains, it allows adapting the stack/heap size to fit the application requirements.
Linker file for EWARM toolchain allowing mainly adapting the stack/heap size to fit the application requirements.
This file contains the MSP initialization and de-initialization (main routine and callbacks) of the peripheral used in the user application.
page 11/3786
Page 12
File Description
This file allows the user to customize the HAL drivers for a specific application.
stm32h7xx_hal_conf.h
stm32h7xx_it.c/.h
main.c/.h
It is not mandatory to modify this configuration. The application can use the default configuration without any modification.
This file contains the exceptions handler and peripherals interrupt service routine, and calls HAL_IncTick() at regular time intervals to increment a local variable (declared in stm32h7xx_hal.c) used as HAL timebase. By default, this function is called each 1ms in Systick ISR. .
The PPP_IRQHandler() routine must call HAL_PPP_IRQHandler() if an interrupt based process is used within the application.
This file contains the main program routine, mainly:
Arm® Cortex®-M7 instruction and data cache enabling
Call to HAL_Init()
assert_failed() implementation
system clock configuration
peripheral HAL initialization and user application code.
The STM32Cube package comes with ready-to-use project templates, one for each supported board. Each project contains the files listed above and a preconfigured project for the supported toolchains.
Each project template provides empty main loop function and can be used as a starting point to get familiar with project settings for STM32Cube. Its features are the following:
It contains the sources of HAL, CMSIS and BSP drivers which are the minimal components to develop a code on a given board.
It contains the include paths for all the firmware components.
It defines the STM32 device supported, and allows configuring the CMSIS and HAL drivers accordingly.
It provides ready to use user files preconfigured as defined below:
HAL is initialized
SysTick ISR implemented for HAL_Delay()
System clock configured with the maximum device frequency.
Note: If an existing project is copied to another location, then include paths must be updated.
UM2217
HAL and user-application files
Figure 4. Example of project template
UM2217 - Rev 5
page 12/3786
Page 13

4.2 HAL data structures

Each HAL driver can contain the following data structures:
Peripheral handle structures
Initialization and configuration structures
Specific process structures.

4.2.1 Peripheral handle structures

The APIs have a modular generic multi-instance architecture that allows working with several IP instances simultaneously.
PPP_HandleTypeDef *handle is the main structure that is implemented in the HAL drivers. It handles the peripheral/module configuration and registers and embeds all the structures and variables needed to follow the peripheral device flow.
The peripheral handle is used for the following purposes:
Multi-instance support: each peripheral/module instance has its own handle. As a result instance resources are independent.
Peripheral process intercommunication: the handle is used to manage shared data resources between the process routines.
Example: global pointers, DMA handles, state machine.
Storage : this handle is used also to manage global variables within a given HAL driver.
An example of peripheral structure is shown below:
UM2217
HAL data structures
typedef struct { USART_TypeDef *Instance; /* USART registers base address */ USART_InitTypeDef Init; /* Usart communication parameters */ uint8_t *pTxBuffPtr;/* Pointer to Usart Tx transfer Buffer */ uint16_t TxXferSize; /* Usart Tx Transfer size */ __IO uint16_t TxXferCount;/* Usart Tx Transfer Counter */ uint8_t *pRxBuffPtr;/* Pointer to Usart Rx transfer Buffer */ uint16_t RxXferSize; /* Usart Rx Transfer size */ __IO uint16_t RxXferCount; /* Usart Rx Transfer Counter */ DMA_HandleTypeDef *hdmatx; /* Usart Tx DMA Handle parameters */ DMA_HandleTypeDef *hdmarx; /* Usart Rx DMA Handle parameters */ HAL_LockTypeDef Lock; /* Locking object */ __IO HAL_USART_StateTypeDef State; /* Usart communication state */ __IO HAL_USART_ErrorTypeDef ErrorCode;/* USART Error code */ }USART_HandleTypeDef;
UM2217 - Rev 5
page 13/3786
Page 14
UM2217
HAL data structures
Note: 1. The multi-instance feature implies that all the APIs used in the application are reentrant and avoid using
global variables because subroutines can fail to be reentrant if they rely on a global variable to remain unchanged but that variable is modified when the subroutine is recursively invoked. For this reason, the following rules are respected:
Reentrant code does not hold any static (or global) non-constant data: reentrant functions can work
with global data. For example, a reentrant interrupt service routine can grab a piece of hardware status to work with (for example serial port read buffer) which is not only global, but volatile. Still, typical use of static variables and global data is not advised, in the sense that only atomic read­modify-write instructions should be used in these variables. It should not be possible for an interrupt or signal to occur during the execution of such an instruction.
Reentrant code does not modify its own code.
2. When a peripheral can manage several processes simultaneously using the DMA (full duplex case), the DMA interface handle for each process is added in the PPP_HandleTypeDef.
3. For the shared and system peripherals, no handle or instance object is used. The peripherals concerned by this exception are the following:
GPIO
SYSTICK
NVIC
PWR
RCC
FLASH

4.2.2 Initialization and configuration structure

These structures are defined in the generic driver header file when it is common to all part numbers. When they can change from one part number to another, the structures are defined in the extension header file for each part number.
typedef struct { uint32_t BaudRate; /*!< This member configures the UART communication baud rate */ uint32_t WordLength;/*!< Specifies the number of data bits transmitted or received in a frame */ uint32_t StopBits; /*!< Specifies the number of stop bits transmitted */ uint32_t Parity; /*!< Specifies the parity mode */ uint32_t Mode; /*!< Specifies whether the Receive or Transmit mode is enabled or disabled */ uint32_t HwFlowCtl; /*!< Specifies whether the hardware flow control mode is enabled or disabled.*/ uint32_t OverSampling; /*!< Specifies whether the Over sampling 8 is enabled or disabled, to achieve higher speed (up to f_PCLK/8) */ uint32_t OneBitSampling; /*!< Specifies whether a single sample or three samples' majority vote is selected */ uint32_t Prescaler; /*!< Specifies the prescaler value used to divide the UART clock source */ uint32_t FIFOMode; /*!< Specifies if the FIFO mode will be used. This parameter can be a value */ uint32_t TXFIFOThreshold; /*!< Specifies the TXFIFO threshold level */ uint32_t RXFIFOThreshold; /*!< Specifies the RXFIFO threshold level */ }UART_InitTypeDef;
Note: The config structure is used to initialize the sub-modules or sub-instances. See below example:
HAL_ADC_ConfigChannel (ADC_HandleTypeDef* hadc, ADC_ChannelConfTypeDef* sConfig)

4.2.3 Specific process structures

The specific process structures are used for specific process (common APIs). They are defined in the generic driver header file.
Example:
UM2217 - Rev 5
page 14/3786
Page 15
HAL_PPP_Process (PPP_HandleTypeDef* hadc,PPP_ProcessConfig* sConfig)
UM2217
HAL data structures
UM2217 - Rev 5
page 15/3786
Page 16

4.3 API classification

The HAL APIs are classified into three categories:
Generic APIs: common generic APIs applying to all STM32 devices. These APIs are consequently present in the generic HAL driver files of all STM32 microcontrollers.
HAL_StatusTypeDef HAL_ADC_Init(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef HAL_ADC_DeInit(ADC_HandleTypeDef *hadc); HAL_StatusTypeDef HAL_ADC_Start(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef HAL_ADC_Stop(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef HAL_ADC_Start_IT(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef HAL_ADC_Stop_IT(ADC_HandleTypeDef* hadc); void HAL_ADC_IRQHandler(ADC_HandleTypeDef* hadc);
Extension APIs:
This set of APIs are family specific APIs that apply to a given family. They are located in the extension HAL driver file (see example below related to the ADC).
HAL_StatusTypeDef HAL_ADCEx_Calibration_Start(ADC_HandleTypeDef* hadc, uint32_t SingleDiff); uint32_t HAL_ADCEx_Calibration_GetValue(ADC_HandleTypeDef* hadc, uint32_t SingleDiff);
UM2217
API classification
The following table summarizes the location of the different categories of HAL APIs in the driver files.
Table 4. API classification
Generic file
Common APIs X X
Family specific APIs - X
Extension file
Note: Family specific APIs are only related to a given family. This means that if a specific API is implemented in
another family, and the arguments of this latter family are different, additional structures and arguments might need to be added.
Note: The IRQ handlers are used for common and family specific processes.
UM2217 - Rev 5
page 16/3786
Page 17

4.4 Devices supported by HAL drivers

UM2217
Devices supported by HAL drivers
UM2217 - Rev 5
page 17/3786
Page 18
UM2217 - Rev 5
page 18/3786
Table 5. List of devices supported by HAL drivers
IP/module
STM32H742xx
STM32H743xx
STM32H753xx
STM32H750xx
STM32H753xx
STM32H745xx
STM32H755xx
STM32H747xx
STM32H757xx
STM32H7A3xx
stm32h7xx_hal.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_adc.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_adc_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_cec.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_comp.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_cortex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_crc.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_crc_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_cryp.c No No Yes Yes Yes No Yes No Yes No No Yes Yes Yes Yes No Yes No Yes Yes Yes
stm32h7xx_hal_cryp_ex.c No No Yes Yes Yes No Yes No Yes No No Yes Yes Yes Yes No Yes No Yes Yes Yes
stm32h7xx_hal_dac.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_dac_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_dcmi.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_dfsdm.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_dma.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_dma_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7x_hal_dma2d.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7x_hal_dsi.c No No No No No No No Yes Yes No No No No No No No No No No No No
stm32h7xx_hal_dts.c No No No No No No No No No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_eth.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_eth_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_fdcan.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_flash.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_flash_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_gpio.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_gfxmmu.c No No No No No No No No No Yes Yes Yes Yes Yes Yes No No No No No No
stm32h7xx_hal_hash.c No No Yes Yes Yes No Yes No Yes No No Yes Yes Yes Yes No Yes No Yes Yes Yes
stm32h7xx_hal_hash_ex.c No No Yes Yes Yes No Yes No Yes No No Yes Yes Yes Yes No Yes No Yes Yes Yes
stm32h7xx_hal_hcd.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_hrtim.c Yes Yes Yes Yes Yes Yes Yes Yes Yes No No No No No No No No No No No No
stm32h7xx_hal_hsem.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
STM32H7B0xx
STM32H7A3xxQ
STM32H7B3xx
STM32H7B0xxQ
STM32H723xx
STM32H7B3xxQ
STM32H733xx
STM32H725xx
STM32H735xx
STM32H730xx
STM32H730xxQ
Devices supported by HAL drivers
UM2217
Page 19
UM2217 - Rev 5
page 19/3786
IP/module
STM32H742xx
STM32H743xx
STM32H753xx
STM32H750xx
STM32H753xx
STM32H745xx
STM32H755xx
STM32H747xx
STM32H757xx
STM32H7A3xx
stm32h7xx_hal_i2c.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_i2c_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_i2s.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_i2s_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_irda.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_iwdg.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_jpeg.c No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes No No No No No No
stm32h7xx_hal_lptim.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_ltdc.c No Yes Yes No No No No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_mdios.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_mdma.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_mmc.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_mmc_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_nand.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_nor.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_opamp.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_opamp_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_ospi.c No No No No No No No No No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_otfdec.c No No No No No No No No No No No Yes Yes Yes Yes No Yes No Yes Yes Yes
stm32h7xx_hal_pcd.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_pcd_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_pssi.c No No No No No No No No No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_pwr.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_pwr_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_qspi.c Yes Yes Yes Yes Yes Yes Yes Yes Yes No No No No No No No No No No No No
stm32h7xx_hal_rcc.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_rcc_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_rng.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_rtc.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_rtc_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_sai.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_sai_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
STM32H7B0xx
STM32H7A3xxQ
STM32H7B3xx
STM32H7B0xxQ
STM32H723xx
STM32H7B3xxQ
STM32H733xx
STM32H725xx
STM32H735xx
STM32H730xx
STM32H730xxQ
Devices supported by HAL drivers
UM2217
Page 20
UM2217 - Rev 5
IP/module
STM32H742xx
STM32H743xx
STM32H753xx
STM32H750xx
STM32H753xx
STM32H745xx
STM32H755xx
STM32H747xx
STM32H757xx
STM32H7A3xx
stm32h7xx_hal_sd.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_sd_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_sdram.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_smartcard.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_smartcard_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_smbus.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_spdifrx.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_spi.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_spi_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_sram.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_swpmi.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_tim.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_tim_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_uart.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_uart_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_usart.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_hal_wwdg.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_ll_delayblock.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_ll_fmc.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_ll_sdmmc.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
stm32h7xx_ll_usb.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
STM32H7B0xx
STM32H7A3xxQ
STM32H7B3xx
STM32H7B0xxQ
STM32H723xx
STM32H7B3xxQ
STM32H733xx
STM32H725xx
STM32H735xx
STM32H730xx
STM32H730xxQ
page 20/3786
Devices supported by HAL drivers
UM2217
Page 21
HAL driver rules

4.5 HAL driver rules

4.5.1 HAL API naming rules

The following naming rules are used in HAL drivers:
Table 6. HAL API naming rules
Generic Family specific Device specific
File names stm32h7xx_hal_ppp (c/h) stm32h7xx_hal_ppp_ex (c/h) stm32h7xx_ hal_ppp_ex (c/h)
Module
name
Function
name
Handle
name
Init
structure
name
Enum name HAL_PPP_StructnameTypeDef NA NA
HAL_PPP_Function
HAL_PPP_FeatureFunction_MODE
PPP_HandleTypedef NA NA
PPP_InitTypeDef NA PPP_InitTypeDef
HAL_PPPEx_FeatureFunction_MODE
HAL_PPP_ MODULE
HAL_PPPEx_Function
HAL_PPPEx_Function
HAL_PPPEx_FeatureFunction_MODE
UM2217
The PPP prefix refers to the peripheral functional mode and not to the peripheral itself. For example, if the USART, PPP can be USART, IRDA, UART or SMARTCARD depending on the peripheral mode.
The constants used in one file are defined within this file. A constant used in several files is defined in a header file. All constants are written in uppercase, except for peripheral driver function parameters.
typedef variable names should be suffixed with _TypeDef.
Registers are considered as constants. In most cases, their name is in uppercase and uses the same acronyms as in the STM32H7 reference manuals.
Peripheral registers are declared in the PPP_TypeDef structure (for example ADC_TypeDef) in stm32h7xxx.h header file:
stm32h7xxx.h corresponds to stm32h742xx.h, stm32h743xx.h, stm32h745xx.h, stm32h747xx.h, stm32h750xx.h, stm32h753xx.h, stm32h755xx.h, stm32h757xx.h, stm32h7a3xx.h, stm32h7a3xxq.h, stm32h7b3xx.h, stm32h7b3xxq.h stm32h7b0xx.h, stm32h7B0xxq.h, stm32h725xx.h, stm32h723xx.h, stm32h730xx.h, stm32h730xxq.h, stm32h733xx.h and stm32h735xx.h.
Peripheral function names are prefixed by HAL_, then the corresponding peripheral acronym in uppercase followed by an underscore. The first letter of each word is in uppercase (for example HAL_UART_Transmit()). Only one underscore is allowed in a function name to separate the peripheral acronym from the rest of the function name.
The structure containing the PPP peripheral initialization parameters are named PPP_InitTypeDef (for example ADC_InitTypeDef).
The structure containing the Specific configuration parameters for the PPP peripheral are named PPP_xxxxConfTypeDef (for example ADC_ChannelConfTypeDef).
Peripheral handle structures are named PPP_HandleTypedef (e.g DMA_HandleTypeDef)
The functions used to initialize the PPP peripheral according to parameters specified in PPP_InitTypeDef are named HAL_PPP_Init (for example HAL_TIM_Init()).
The functions used to reset the PPP peripheral registers to their default values are named HAL_PPP_DeInit (for example HAL_TIM_DeInit()).
The MODE suffix refers to the process mode, which can be polling, interrupt or DMA. As an example, when the DMA is used in addition to the native resources, the function should be called: HAL_PPP_Function_DMA
().
UM2217 - Rev 5
page 21/3786
Page 22
UM2217
HAL driver rules
The Feature prefix should refer to the new feature.
Example: HAL_ADC_Start() refers to the injection mode

4.5.2 HAL general naming rules

For the shared and system peripherals, no handle or instance object is used. This rule applies to the following peripherals:
GPIO
SYSTICK
NVIC
RCC
FLASH.
Example: The HAL_GPIO_Init() requires only the GPIO address and its configuration parameters.
HAL_StatusTypeDef HAL_GPIO_Init (GPIO_TypeDef* GPIOx, GPIO_InitTypeDef *Init) { /*GPIO Initialization body */ }
The macros that handle interrupts and specific clock configurations are defined in each peripheral/module driver. These macros are exported in the peripheral driver header files so that they can be used by the extension file. The list of these macros is defined below:
Note: This list is not exhaustive and other macros related to peripheral features can be added, so that they can be
used in the user application.
Table 7. Macros handling interrupts and specific clock configurations
Macros
__HAL_PPP_ENABLE_IT(__HANDLE__, __INTERRUPT__) Enables a specific peripheral interrupt
__HAL_PPP_DISABLE_IT(__HANDLE__,
__INTERRUPT__)
__HAL_PPP_GET_IT (__HANDLE__, __ INTERRUPT __) Gets a specific peripheral interrupt status
__HAL_PPP_CLEAR_IT (__HANDLE__, __ INTERRUPT __) Clears a specific peripheral interrupt status
__HAL_PPP_GET_FLAG (__HANDLE__, __FLAG__) Gets a specific peripheral flag status
__HAL_PPP_CLEAR_FLAG (__HANDLE__, __FLAG__) Clears a specific peripheral flag status
__HAL_PPP_ENABLE(__HANDLE__) Enables a peripheral
__HAL_PPP_DISABLE(__HANDLE__) Disables a peripheral
__HAL_PPP_XXXX (__HANDLE__, __PARAM__) Specific PPP HAL driver macro
__HAL_PPP_GET_ IT_SOURCE (__HANDLE__, __
INTERRUPT __)
Disables a specific peripheral interrupt
Checks the source of specified interrupt
Description
NVIC and SYSTICK are two Arm® Cortex® core features. The APIs related to these features are located in the stm32h7xx_hal_cortex.c file.
When a status bit or a flag is read from registers, it is composed of shifted values depending on the number of read values and of their size. In this case, the returned status width is 32 bits. Example : STATUS = XX | (YY << 16) or STATUS = XX | (YY << 8) | (YY << 16) | (YY << 24)".
UM2217 - Rev 5
page 22/3786
Page 23
The PPP handles are valid before using the HAL_PPP_Init() API. The init function performs a check before modifying the handle fields.
HAL_PPP_Init(PPP_HandleTypeDef) if(hppp == NULL) { return HAL_ERROR; }
The macros defined below are used:
Conditional macro:
#define ABS(x) (((x) > 0) ? (x) : -(x))
Pseudo-code macro (multiple instructions macro):
#define __HAL_LINKDMA(__HANDLE__, __PPP_DMA_FIELD_, __DMA_HANDLE_) \ do{ \ (__HANDLE__)->__PPP_DMA_FIELD_ = &(__DMA_HANDLE_); \ (__DMA_HANDLE_).Parent = (__HANDLE__); \ } while(0)

4.5.3 HAL interrupt handler and callback functions

Besides the APIs, HAL peripheral drivers include:
HAL_PPP_IRQHandler() peripheral interrupt handler that should be called from stm32h7xx_it.c
User callback functions.
The user callback functions are defined as empty functions with “weak” attribute. They have to be defined in the user code.
There are three types of user callbacks functions:
Peripheral system level initialization/ de-Initialization callbacks: HAL_PPP_MspInit() and HAL_PPP_MspDeInit
Process complete callbacks : HAL_PPP_ProcessCpltCallback
Error callback: HAL_PPP_ErrorCallback.
UM2217
HAL generic APIs
Callback functions Example
HAL_PPP_MspInit() / _DeInit()
HAL_PPP_ProcessCpltCallback
HAL_PPP_ErrorCallback

4.6 HAL generic APIs

The generic APIs provide common generic functions applying to all STM32 devices. They are composed of four APIs groups:
Initialization and de-initialization functions:HAL_PPP_Init(), HAL_PPP_DeInit()
IO operation functions: HAL_PPP_Read(), HAL_PPP_Write(),HAL_PPP_Transmit(), HAL_PPP_Receive()
Control functions: HAL_PPP_Set (), HAL_PPP_Get ().
State and Errors functions: HAL_PPP_GetState (), HAL_PPP_GetError ().
For some peripheral/module drivers, these groups are modified depending on the peripheral/module implementation.
Table 8. Callback functions
Example: HAL_USART_MspInit()
Called from HAL_PPP_Init() API function to perform peripheral system level initialization (GPIOs, clock, DMA, interrupt)
Example: HAL_USART_TxCpltCallback
Called by peripheral or DMA interrupt handler when the process completes
Example: HAL_USART_ErrorCallback
Called by peripheral or DMA interrupt handler when an error occurs
UM2217 - Rev 5
page 23/3786
Page 24
UM2217
HAL extension APIs
Example: in the timer driver, the API grouping is based on timer features (such as PWM, OC and IC).
The initialization and de-initialization functions allow initializing a peripheral and configuring the low-level resources, mainly clocks, GPIO, alternate functions (AF) and possibly DMA and interrupts. The HAL_DeInit()function restores the peripheral default state, frees the low-level resources and removes any direct dependency with the hardware.
The IO operation functions perform a row access to the peripheral payload data in write and read modes.
The control functions are used to change dynamically the peripheral configuration and set another operating mode.
The peripheral state and errors functions allow retrieving in run time the peripheral and data flow states, and identifying the type of errors that occurred. The example below is based on the ADC peripheral. The list of generic APIs is not exhaustive. It is only given as an example.
Table 9. HAL generic APIs
Function group Common API name Description
This function initializes the peripheral and configures the low -level resources (clocks, GPIO, AF..)
This function restores the peripheral default state, frees the low­level resources and removes any direct dependency with the hardware.
This function starts ADC conversions when the polling method is used
This function stops ADC conversions when the polling method is used
This function allows waiting for the end of conversions when the polling method is used. In this case, a timout value is specified by the user according to the application.
This function starts ADC conversions when the interrupt method is used
This function stops ADC conversions when the interrupt method is used
Callback function called in the IT subroutine to indicate the end of the current process or when a DMA transfer has completed
Callback function called in the IT subroutine if a peripheral error or a DMA transfer error occurred
This function configures the selected ADC regular channel, the corresponding rank in the sequencer and the sample time
This function allows getting in run time the peripheral and the data flow states.
This fuction allows getting in run time the error that occurred during IT routine
Initialization group
IO operation group
Control group
State and Errors
group
HAL_ADC_Init()
HAL_ADC_DeInit()
HAL_ADC_Start ()
HAL_ADC_Stop ()
HAL_ADC_PollForConversion()
HAL_ADC_Start_IT()
HAL_ADC_Stop_IT()
HAL_ADC_IRQHandler() This function handles ADC interrupt requests
HAL_ADC_ConvCpltCallback()
HAL_ADC_ErrorCallback()
HAL_ADC_ConfigChannel()
HAL_ADC_AnalogWDGConfig This function configures the analog watchdog for the selected ADC
HAL_ADC_GetState()
HAL_ADC_GetError()

4.7 HAL extension APIs

4.7.1 HAL extension model overview

The extension APIs provide specific functions or overwrite modified APIs for a specific family (series) or specific part number within the same family.
The extension model consists of an additional file, stm32h7xx_hal_ppp_ex.c, that includes all the specific functions and define statements (stm32h7xx_hal_ppp_ex.h) for a given part number.
Below an example based on the ADC peripheral:
UM2217 - Rev 5
page 24/3786
Page 25
Function group Common API name
HAL_ADCEx_CalibrationStart() This function is used to start the automatic ADC calibration

4.7.2 HAL extension model cases

The specific IP features can be handled by the HAL drivers in five different ways. They are described below.
Adding a family-specific function
In this case, the API is added in the extension driver C file and named HAL_PPPEx_Function ().
UM2217
HAL extension APIs
Table 10. HAL extension APIs
Figure 5. Adding family-specific functions
Adding a new peripheral (specific to a device belonging to a given family)
When a peripheral which is available only in a specific device is required, the APIs corresponding to this new peripheral/module (newPPP) are added in a new stm32h7xx_hal_newppp.c. However the inclusion of this file is selected in the stm32h7xx_hal_conf.h using the macro:
#define HAL_NEWPPP_MODULE_ENABLED
Figure 6. Adding new peripherals
Example: stm32h7xx_hal_adc.c/h
Updating existing common APIs
UM2217 - Rev 5
In this case, the routines are defined with the same names in the stm32h7xx_hal_ppp_ex.c extension file, while the generic API is defined as weak, so that the compiler overwrites the original routine by the new defined function.
page 25/3786
Page 26
Figure 7. Updating existing APIs
UM2217
HAL extension APIs
UM2217 - Rev 5
page 26/3786
Page 27

4.8 File inclusion model

The header of the common HAL driver file (stm32h7xx_hal.h) includes the common configurations for the whole HAL library. It is the only header file that is included in the user sources and the HAL C sources files to be able to use the HAL resources.
UM2217
File inclusion model
Figure 8. File inclusion model
4.9
A PPP driver is a standalone module which is used in a project. The user must enable the corresponding USE_HAL_PPP_MODULE define statement in the configuration file.
/********************************************************************* * @file stm32h7xx_hal_conf.h * @author MCD Application Team * @version VX.Y.Z * @date dd-mm-yyyy * @brief This file contains the modules to be used ********************************************************************** (…) #define USE_HAL_USART_MODULE #define USE_HAL_IRDA_MODULE #define USE_HAL_DMA_MODULE #define USE_HAL_RCC_MODULE (…)

HAL common resources

The common HAL resources, such as common define enumerations, structures and macros, are defined in stm32h7xx_hal_def.h.The main common define enumeration is HAL_StatusTypeDef.
UM2217 - Rev 5
page 27/3786
Page 28

HAL configuration

HAL Status
The HAL status is used by almost all HAL APIs, except for boolean functions and IRQ handler. It returns the status of the current API operations. It has four possible values as described below:
Typedef enum { HAL_OK = 0x00, HAL_ERROR = 0x01, HAL_BUSY = 0x02, HAL_TIMEOUT = 0x03 } HAL_StatusTypeDef;
HAL Locked
The HAL lock is used by all HAL APIs to prevent accessing by accident shared resources.
typedef enum { HAL_UNLOCKED = 0x00, /*!<Resources unlocked */ HAL_LOCKED = 0x01 /*!< Resources locked */ } HAL_LockTypeDef;
In addition to common resources, the stm32h7xx_hal_def.h file calls the stm32h7xx.h file in CMSIS library to get the data structures and the address mapping for all peripherals:
Declarations of peripheral registers and bits definition.
Macros to access peripheral registers hardware (such as Write register or Read register).
Common macros
Macro defining HAL_MAX_DELAY
UM2217
4.10
#define HAL_MAX_DELAY 0xFFFFFFFF
Macro linking a PPP peripheral to a DMA structure pointer:
#define __HAL_LINKDMA(__HANDLE__, __PPP_DMA_FIELD_, __DMA_HANDLE_) \ do{ \ (__HANDLE__)->__PPP_DMA_FIELD_ = &(__DMA_HANDLE_); \ (__DMA_HANDLE_).Parent = (__HANDLE__); \ } while(0)
HAL configuration
The configuration file, stm32h7xx_hal_conf.h, allows customizing the drivers for the user application. Modifying this configuration is not mandatory: the application can use the default configuration without any modification.
To configure these parameters, the user should enable, disable or modify some options by uncommenting, commenting or modifying the values of the related define statements as described in the table below:
Table 11. Define statements used for HAL configuration
Configuration item Description Default Value
HSE_VALUE
HSE_STARTUP_TIMEOUT Timeout for HSE start-up, expressed in ms 5000
HSI_VALUE Defines the value of the internal oscillator (HSI) expressed in Hz. 64 000 000 Hz
LSE_VALUE
LSE_STARTUP_TIMEOUT Timeout for LSE start-up, expressed in ms 5000
CSI_VALUE Defines the value of the internal oscillator (CSI) expressed in Hz 4 000 000 Hz
Defines the value of the external oscillator (HSE) expressed in Hz.
The user must adjust this define statement when using a different
crystal value.
Defines the value of the external oscillator (HSE) expressed in Hz.
The user must adjust this define statement when using a different
crystal value.
25 000 000 Hz
32768 Hz
UM2217 - Rev 5
page 28/3786
Page 29
UM2217
HAL system peripheral handling
Configuration item Description Default Value
LSI_VALUE Defines the value of the internal oscillator (LSI) expressed in Hz 32 000 Hz
VDD_VALUE VDD value 3300 (mV)
USE_RTOS Enables the use of RTOS
FALSE (reserved for
future use)
Note: The stm32h7xx_hal_conf_template.h file is located in the HAL drivers Inc folder. It should be copied to the user
folder, renamed and modified as described above.
Note: By default, the values defined in the stm32h7xx_hal_conf_template.h file are the same as the ones used for the
examples and demonstrations. All HAL include files are enabled so that they can be used in the user code without modifications.

4.11 HAL system peripheral handling

This chapter gives an overview of how the system peripherals are handled by the HAL drivers. The full API list is provided within each peripheral driver description section.

4.11.1 Clock

Two main functions can be used to configure the system clock:
HAL_RCC_OscConfig (RCC_OscInitTypeDef *RCC_OscInitStruct). This function configures/enables multiple clock sources (HSE, HSI, LSE, LSI, PLL).
HAL_RCC_ClockConfig (RCC_ClkInitTypeDef *RCC_ClkInitStruct, uint32_t FLatency). This function
selects the system clock source
configures AHB, APB1, APB2, APB3 and APB4 clock dividers
configures the number of Flash memory wait states
updates the SysTick configuration when HCLK clock changes.
Some peripheral clocks are not derived from the system clock (such as RTC, USB). In this case, the clock configuration is performed by an extended API defined in stm32h7xx_hal_rcc_ex.c: HAL_RCCEx_PeriphCLKConfig(RCC_PeriphCLKInitTypeDef *PeriphClkInit).
Additional RCC HAL driver functions are available:
HAL_RCC_DeInit() Clock de-initialization function that returns clock configuration to reset state
Get clock functions that allow retreiving various clock configurations (such as system clock, HCLK, PCLK1 or PCLK2)
MCO and CSS configuration functions
A set of macros are defined in stm32h7xx_hal_rcc.h and stm32h7xx_hal_rcc_ex.h. They allow executing elementary operations on RCC block registers, such as peripherals clock gating/reset control:
__HAL_RCC_PPP_CLK_ENABLE/__HAL_RCC_PPP_CLK_DISABLE to enable/disable the peripheral clock
__HAL_RCC_PPP_FORCE_RESET/__HAL_RCC_PPP_RELEASE_RESET to force/release peripheral reset
__HAL_RCC_PPP_CLK_SLEEP_ENABLE/__HAL_RCC_PPP_CLK_SLEEP_DISABLE to enable/disable the peripheral clock during Sleep mode

4.11.2 GPIOs

GPIO HAL APIs are the following:
HAL_GPIO_Init() / HAL_GPIO_DeInit()
HAL_GPIO_ReadPin() / HAL_GPIO_WritePin()
HAL_GPIO_TogglePin ().
In addition to standard GPIO modes (input, output, analog), the pin mode can be configured as EXTI with interrupt or event generation.
When selecting EXTI mode with interrupt generation, the user must call HAL_GPIO_EXTI_IRQHandler() from stm32h7xx_it.c and implement HAL_GPIO_EXTI_Callback()
UM2217 - Rev 5
page 29/3786
Page 30
The table below describes the GPIO_InitTypeDef structure field.
Table 12. Description of GPIO_InitTypeDef structure
Structure field Description
Pin
Mode
Pull
Speed
Specifies the GPIO pins to be configured.
Possible values: GPIO_PIN_x or GPIO_PIN_All, where x[0..15]
Specifies the operating mode for the selected pins: GPIO mode or EXTI mode.
Possible values are:
GPIO mode
GPIO_MODE_INPUT : Input floating
GPIO_MODE_OUTPUT_PP : Output push-pull
GPIO_MODE_OUTPUT_OD : Output open drain
GPIO_MODE_AF_PP : Alternate function push-pull
GPIO_MODE_AF_OD : Alternate function open drain
GPIO_MODE_ANALOG : Analog mode
External Interrupt mode
GPIO_MODE_IT_RISING : Rising edge trigger detection
GPIO_MODE_IT_FALLING : Falling edge trigger detection
GPIO_MODE_IT_RISING_FALLING : Rising/Falling edge trigger detection
External Event mode
GPIO_MODE_EVT_RISING : Rising edge trigger detection
GPIO_MODE_EVT_FALLING : Falling edge trigger detection
GPIO_MODE_EVT_RISING_FALLING: Rising/Falling edge trigger detection
Specifies the Pull-up or Pull-down activation for the selected pins.
Possible values are:
GPIO_NOPULL
GPIO_PULLUP
GPIO_PULLDOWN
Specifies the speed for the selected pins
Possible values are:
GPIO_SPEED_FREQ_LOW
GPIO_SPEED_FREQ_MEDIUM
GPIO_SPEED_FREQ_HIGH
GPIO_SPEED_FREQ_VERY_HIGH
UM2217
HAL system peripheral handling
UM2217 - Rev 5
Please find below typical GPIO configuration examples:
Configuring GPIOs as output push-pull to drive external LEDs:
GPIO_InitStruct.Pin = GPIO_PIN_12 | GPIO_PIN_13 | GPIO_PIN_14 | GPIO_PIN_15; GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP; GPIO_InitStruct.Pull = GPIO_PULLUP; GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_MEDIUM; HAL_GPIO_Init(GPIOD, &GPIO_InitStruct);
Configuring PA0 as external interrupt with falling edge sensitivity:
GPIO_InitStructure.Mode = GPIO_MODE_IT_FALLING; GPIO_InitStructure.Pull = GPIO_NOPULL; GPIO_InitStructure.Pin = GPIO_PIN_0; HAL_GPIO_Init(GPIOA, &GPIO_InitStructure);
page 30/3786
Page 31
UM2217
HAL system peripheral handling
4.11.3
Cortex® NVIC and SysTick timer
The Cortex® HAL driver, stm32h7xx_hal_cortex.c, provides APIs to handle NVIC and SysTick. The supported APIs include:
HAL_NVIC_SetPriority()/ HAL_NVIC_SetPriorityGrouping()
HAL_NVIC_GetPriority() / HAL_NVIC_GetPriorityGrouping()
HAL_NVIC_EnableIRQ()/HAL_NVIC_DisableIRQ()
HAL_NVIC_SystemReset()
HAL_SYSTICK_IRQHandler()
HAL_NVIC_GetPendingIRQ() / HAL_NVIC_SetPendingIRQ () / HAL_NVIC_ClearPendingIRQ()
HAL_NVIC_GetActive(IRQn)
HAL_SYSTICK_Config()
HAL_SYSTICK_CLKSourceConfig()
HAL_SYSTICK_Callback()

4.11.4 PWR

The PWR HAL driver handles power management. The features shared between all STM32 Series are listed below:
PVD configuration, enabling/disabling and interrupt handling
Wakeup pin configuration
Low-power mode entry
HAL_PWR_ConfigPVD()
HAL_PWR_EnablePVD() / HAL_PWR_DisablePVD()
HAL_PWR_PVD_IRQHandler()
HAL_PWR_PVDCallback()
HAL_PWR_EnableWakeUpPin() / HAL_PWR_DisableWakeUpPin()
HAL_PWR_EnterSLEEPMode()
HAL_PWR_EnterSTOPMode()
HAL_PWR_EnterSTANDBYMode()

4.11.5 EXTI

The EXTI is not considered as a standalone peripheral but rather as a service used by other peripheral, that are handled through EXTI HAL APIs. In addition, each peripheral HAL driver implements the associated EXTI configuration and function as macros in its header file.
The first 16 EXTI lines connected to the GPIOs are managed within the GPIO driver. The GPIO_InitTypeDef structure allows configuring an I/O as external interrupt or external event.
The EXTI lines connected internally to the PVD, RTC, USB, and Ethernet are configured within the HAL drivers of these peripheral through the macros given in the table below.
The EXTI internal connections depend on the targeted STM32 microcontroller (refer to the product datasheet for more details):
Table 13. Description of EXTI configuration macros
Macros
__HAL_PPP_{SUBLOCK}__EXTI_ENABLE_IT()
__HAL_PPP_{SUBLOCK}__EXTI_DISABLE_IT()
Description
Enables a given EXTI line interrupt
Example:
__HAL_PWR_PVD_EXTI_ENABLE_IT()
Disables a given EXTI line.
Example:
__HAL_PWR_PVD_EXTI_DISABLE_IT()
UM2217 - Rev 5
page 31/3786
Page 32
HAL system peripheral handling
Macros Description
Gets a given EXTI line interrupt flag pending bit status.
__HAL_ PPP_{SUBLOCK}__EXTI_GET_FLAG()
__HAL_ PPP_{SUBLOCK}_EXTI_CLEAR_FLAG()
__HAL_ PPP_{SUBLOCK}_EXTI_GENERATE_SWIT()
__HAL_PPP_SUBBLOCK_EXTI_ENABLE_EVENT()
__HAL_PPP_SUBBLOCK_EXTI_DISABLE_EVENT()
__HAL_ PPP_SUBBLOCK_EXTI_ENABLE_RISING_EDGE() Configure an EXTI Interrupt or Event on rising edge
__HAL_ PPP_SUBBLOCK_EXTI_ENABLE_FALLING_EDGE() Enable an EXTI Interrupt or Event on Falling edge
__HAL_ PPP_SUBBLOCK_EXTI_DISABLE_RISING_EDGE() Disable an EXTI Interrupt or Event on rising edge
__HAL_ PPP_SUBBLOCK_EXTI_DISABLE_FALLING_EDGE() Disable an EXTI Interrupt or Event on Falling edge
__HAL_ PPP_SUBBLOCK_EXTI_ENABLE_RISING_FALLING_EDGE()
Example:
__HAL_PWR_PVD_EXTI_GET_FLAG()
Clears a given EXTI line interrupt flag pending bit.
Example;
__HAL_PWR_PVD_EXTI_CLEAR_FLAG()
Generates a software interrupt for a given EXTI line.
Example:
__HAL_PWR_PVD_EXTI_ GENERATE_SWIT ()
Enable a given EXTI line event
Example:
__HAL_RTC_WAKEUP_EXTI_ENABLE_EVENT()
Disable a given EXTI line event
Example:
__HAL_RTC_WAKEUP_EXTI_DISABLE_EVENT()
Enable an EXTI Interrupt or Event on Rising/Falling edge
UM2217
__HAL_ PPP_SUBBLOCK_EXTI_DISABLE_RISING_FALLING_EDGE()
If the EXTI interrupt mode is selected, the user application must call HAL_PPP_FUNCTION_IRQHandler() (for example HAL_PWR_PVD_IRQHandler()), from stm32h7xx_it.c file, and implement HAL_PPP_FUNCTIONCallback() callback function (for example HAL_PWR_PVDCallback().

4.11.6 DMA

The DMA HAL driver allows enabling and configuring the peripheral to be connected to the DMA Channels (except for internal SRAM/FLASH memory which do not require any initialization). Refer to the product reference manual for details on the DMA request corresponding to each peripheral.
For a given channel, HAL_DMA_Init() API allows programming the required configuration through the following parameters:
Transfer direction
Source and destination data formats
Circular, Normal control mode
Channel priority level
Source and destination Increment mode
Two operating modes are available:
Polling mode I/O operation
Disable an EXTI Interrupt or Event on Rising/Falling edge
1. Use HAL_DMA_Start() to start DMA transfer when the source and destination addresses and the
Length of data to be transferred have been configured.
2. Use HAL_DMA_PollForTransfer() to poll for the end of current transfer. In this case a fixed timeout can
be configured depending on the user application.
UM2217 - Rev 5
page 32/3786
Page 33
UM2217

How to use HAL drivers

Interrupt mode I/O operation
1. Configure the DMA interrupt priority using HAL_NVIC_SetPriority()
2. Enable the DMA IRQ handler using HAL_NVIC_EnableIRQ()
3. Use HAL_DMA_Start_IT() to start DMA transfer when the source and destination addresses and the
length of data to be transferred have been confgured. In this case the DMA interrupt is configured.
4. Use HAL_DMA_IRQHandler() called under DMA_IRQHandler() Interrupt subroutine
5. When data transfer is complete, HAL_DMA_IRQHandler() function is executed and a user function can
be called by customizing XferCpltCallback and XferErrorCallback function pointer (i.e. a member of DMA handle structure).
Additional functions and macros are available to ensure efficient DMA management:
Use HAL_DMA_GetState() function to return the DMA state and HAL_DMA_GetError() in case of error detection.
Use HAL_DMA_Abort() function to abort the current transfer
The most used DMA HAL driver macros are the following:
__HAL_DMA_ENABLE: enables the specified DMA channel.
__HAL_DMA_DISABLE: disables the specified DMA channel.
__HAL_DMA_GET_FLAG: gets the DMA channel pending flags.
__HAL_DMA_CLEAR_FLAG: clears the DMA channel pending flags.
__HAL_DMA_ENABLE_IT: enables the specified DMA channel interrupts.
__HAL_DMA_DISABLE_IT: disables the specified DMA channel interrupts.
__HAL_DMA_GET_IT_SOURCE: checks whether the specified DMA channel interrupt has been enabled or not.
Note: When a peripheral is used in DMA mode, the DMA initialization should be done in the HAL_PPP_MspInit()
callback. In addition, the user application should associate the DMA handle to the PPP handle (refer to section “HAL IO operation functions”).
Note: DMA channel callbacks need to be initialized by the user application only in case of memory-to-memory transfer.
However when peripheral-to-memory transfers are used, these callbacks are automatically initialized by calling a process API function that uses the DMA.
4.12
How to use HAL drivers

4.12.1 HAL usage models

The following figure shows the typical use of the HAL driver and the interaction between the application user, the HAL driver and the interrupts.
UM2217 - Rev 5
page 33/3786
Page 34
Figure 9. HAL driver model
UM2217
How to use HAL drivers
stm32hxxx_it.c
DMAx_IRQHandler
or
PPP_IRQHandler
app.c/main.chal_msp.c stm32hxxx_hal_ppp.c Services
1. Declare PPP handle
2. Init handle Params
3. Call HAL_PPP_init()
HAL_PPP_Mspinit()
Calll HAL_PPP_Process()
Hal_PPP_ProcessCpltCallBack()
Hal_PPP_ErrorCallBack()
Calll HAL_PPP_DeInit()
HAL_PPP_Init()
HAL_PPP_Process()
Interrupt
model
HAL_PPP_DeInit()
stm32hxx_hal_gpio.c/h
stm32hxx_hal_rcc.c/h
stm32hxx_hal_nvic.c/h
stm32hxx_hal_dma.c/h
DMA model
HAL_PPP_MspDeinit()
MS48841
Note: The functions implemented in the HAL driver are shown in green, the functions called from interrupt handlers in
dotted lines, and the msp functions implemented in the user application in red. Non-dotted lines represent the interactions between the user application functions.
Basically, the HAL driver APIs are called from user files and optionally from interrupt handlers file when the APIs based on the DMA or the PPP peripheral dedicated interrupts are used.
When DMA or PPP peripheral interrupts are used, the PPP process complete callbacks are called to inform the user about the process completion in real-time event mode (interrupts). Note that the same process completion callbacks are used for DMA in interrupt mode.

4.12.2 HAL initialization

4.12.2.1 HAL global initialization
In addition to the peripheral initialization and de-initialization functions, a set of APIs are provided to initialize the HAL core implemented in file stm32h7xx_hal.c.
HAL_Init(): this function must be called at application startup to
initialize data/instruction cache and pre-fetch queue
set SysTick timer to generate an interrupt each 1ms (based on HSI clock) with the lowest priority
call HAL_MspInit() user callback function to perform system level initializations (Clock, GPIOs, DMA,
interrupts). HAL_MspInit() is defined as “weak” empty function in the HAL drivers.
HAL_DeInit()
resets all peripherals
calls function HAL_MspDeInit() which is a user callback function to do system level De-Initalizations.
UM2217 - Rev 5
page 34/3786
Page 35
HAL_GetTick(): this function gets current SysTick counter value (incremented in SysTick interrupt) used by peripherals drivers to handle timeouts.
HAL_Delay(). this function implements a delay (expressed in milliseconds) using the SysTick timer.
Care must be taken when using HAL_Delay() since this function provides an accurate delay (expressed in milliseconds) based on a variable incremented in SysTick ISR. This means that if HAL_Delay() is called from a peripheral ISR, then the SysTick interrupt must have highest priority (numerically lower) than the peripheral interrupt, otherwise the caller ISR is blocked.
4.12.2.2 System clock initialization
The clock configuration is done at the beginning of the user code. However the user can change the configuration of the clock in his own code.
Please find below the typical Clock configuration sequence:
UM2217
How to use HAL drivers
UM2217 - Rev 5
page 35/3786
Page 36
How to use HAL drivers
static void SystemClock_Config(void) { RCC_ClkInitTypeDef RCC_ClkInitStruct; RCC_OscInitTypeDef RCC_OscInitStruct; HAL_StatusTypeDef ret = HAL_OK;
/*!< Supply configuration update enable */ HAL_PWREx_ConfigSupply(PWR_LDO_SUPPLY);
/* The voltage scaling allows optimizing the power consumption when the device is clocked below the maximum system frequency, to update the voltage scaling value regarding system frequency refer to product datasheet. */ __HAL_PWR_VOLTAGESCALING_CONFIG(PWR_REGULATOR_VOLTAGE_SCALE1);
while(!__HAL_PWR_GET_FLAG(PWR_FLAG_VOSRDY)) {}
/* Enable HSE Oscillator and activate PLL with HSE as source */ RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_HSE; RCC_OscInitStruct.HSEState = RCC_HSE_ON; RCC_OscInitStruct.HSIState = RCC_HSI_OFF; RCC_OscInitStruct.CSIState = RCC_CSI_OFF; RCC_OscInitStruct.PLL.PLLState = RCC_PLL_ON; RCC_OscInitStruct.PLL.PLLSource = RCC_PLLSOURCE_HSE;
RCC_OscInitStruct.PLL.PLLM = 5; RCC_OscInitStruct.PLL.PLLN = 160; RCC_OscInitStruct.PLL.PLLFRACN = 0; RCC_OscInitStruct.PLL.PLLP = 2; RCC_OscInitStruct.PLL.PLLR = 2; RCC_OscInitStruct.PLL.PLLQ = 4;
UM2217
RCC_OscInitStruct.PLL.PLLVCOSEL = RCC_PLL1VCOWIDE; RCC_OscInitStruct.PLL.PLLRGE = RCC_PLL1VCIRANGE_2; ret = HAL_RCC_OscConfig(&RCC_OscInitStruct); if(ret != HAL_OK) { Error_Handler(); }
/* Select PLL as system clock source and configure bus clocks dividers */ RCC_ClkInitStruct.ClockType = (RCC_CLOCKTYPE_SYSCLK | RCC_CLOCKTYPE_HCLK | RCC_CLOCKTYPE_D1PCLK1 | RCC_CLOCKTYPE_PCLK1 | \ RCC_CLOCKTYPE_PCLK2 | RCC_CLOCKTYPE_D3PCLK1);
RCC_ClkInitStruct.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK; RCC_ClkInitStruct.SYSCLKDivider = RCC_SYSCLK_DIV1; RCC_ClkInitStruct.AHBCLKDivider = RCC_HCLK_DIV2; RCC_ClkInitStruct.APB3CLKDivider = RCC_APB3_DIV2; RCC_ClkInitStruct.APB1CLKDivider = RCC_APB1_DIV2; RCC_ClkInitStruct.APB2CLKDivider = RCC_APB2_DIV2; RCC_ClkInitStruct.APB4CLKDivider = RCC_APB4_DIV2; ret = HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_4); if(ret != HAL_OK) { Error_Handler(); }
/* Note : The activation of the I/O Compensation Cell is recommended with communication interfaces (GPIO, SPI, FMC, QSPI ...) when operating at high frequencies(please refer to product datasheet) The I/O Compensation Cell activation procedure requires :
- The activation of the CSI clock
- The activation of the SYSCFG clock
- Enabling the I/O Compensation Cell : setting bit[0] of register SYSCFG_CCCSR
To do this please uncomment the following code
UM2217 - Rev 5
page 36/3786
Page 37
*/
/* __HAL_RCC_CSI_ENABLE() ;
__HAL_RCC_SYSCFG_CLK_ENABLE() ;
HAL_EnableCompensationCell(); */ }
Caution: Consideration for firmware power configuration versus hardware board configuration
STM32H7 boards are configured either in direct SMPS or in LDO power regulator mode.
Therefore the firmware running on a given board must match its hardware configuration, otherwise a deadlock might occur since ST-LINK will not be able to connect the target after reset. Refer to the corresponding board user manual to check which power configuration is implemented.
The firmware power configuration is performed in SystemClock_Config through the following lines:
In case of “Direct SMPS” hardware configuration:
HAL_PWREx_ConfigSupply(PWR_DIRECT_SMPS_SUPPLY);
In case of “LDO” hardware configuration:
HAL_PWREx_ConfigSupply(PWR_LDO_SUPPLY);
UM2217
How to use HAL drivers
4.12.2.3 HAL MSP initialization process
The peripheral initialization is done through HAL_PPP_Init() while the hardware resources initialization used by a peripheral (PPP) is performed during this initialization by calling MSP callback function HAL_PPP_MspInit().
The MspInit callback performs the low level initialization related to the different additional hardware resources: RCC, GPIO, NVIC and DMA.
All the HAL drivers with handles include two MSP callbacks for initialization and de-initialization:
/** * @brief Initializes the PPP MSP. * @param hppp: PPP handle * @retval None */ void __weak HAL_PPP_MspInit(PPP_HandleTypeDef *hppp) { /* NOTE : This function Should not be modified, when the callback is needed, the HAL_PPP_MspInit could be implemented in the user file */ } /** * @brief DeInitializes PPP MSP. * @param hppp: PPP handle * @retval None */ void __weak HAL_PPP_MspDeInit(PPP_HandleTypeDef *hppp) { /* NOTE : This function Should not be modified, when the callback is needed, the HAL_PPP_MspDeInit could be implemented in the user file */ }
The MSP callbacks are declared empty as weak functions in each peripheral driver. The user can use them to set the low level initialization code or omit them and use his own initialization routine.
The HAL MSP callback is implemented inside the stm32h7xx_hal_msp.c file in the user folders. An stm32h7xx_hal_msp.c file template is located in the HAL folder and should be copied to the user folder. It can be generated automatically by STM32CubeMX tool and further modified. Note that all the routines are declared as weak functions and could be overwritten or removed to use user low level initialization code.
stm32h7xx_hal_msp.c file contains the following functions:
UM2217 - Rev 5
Table 14. MSP functions
Routine
void HAL_MspInit() Global MSP initialization routine
void HAL_MspDeInit() Global MSP de-initialization routine
Description
page 37/3786
Page 38
Routine Description
void HAL_PPP_MspInit() PPP MSP initialization routine
void HAL_PPP_MspDeInit() PPP MSP de-initialization routine
By default, if no peripheral needs to be de-initialized during the program execution, the whole MSP initialization is done in Hal_MspInit() and MSP De-Initialization in the Hal_MspDeInit(). In this case the HAL_PPP_MspInit() and HAL_PPP_MspDeInit() are not implemented.
When one or more peripherals needs to be de-initialized in run time and the low level resources of a given peripheral need to be released and used by another peripheral, HAL_PPP_MspDeInit() and HAL_PPP_MspInit() are implemented for the concerned peripheral and other peripherals initialization and de-Initialization are kept in the global HAL_MspInit() and the HAL_MspDeInit().
If there is nothing to be initialized by the global HAL_MspInit() and HAL_MspDeInit(), the two routines can simply be omitted.

4.12.3 HAL I/O operation process

The HAL functions with internal data processing like transmit, receive, write and read are generally provided with three data processing modes as follows:
Polling mode
Interrupt mode
DMA mode
UM2217
How to use HAL drivers
4.12.3.1 Polling mode
In Polling mode, the HAL functions return the process status when the data processing in blocking mode is complete. The operation is considered complete when the function returns the HAL_OK status, otherwise an error status is returned. The user can get more information through the HAL_PPP_GetState() function. The data processing is handled internally in a loop. A timeout (expressed in ms) is used to prevent process hanging.
The example below shows the typical Polling mode processing sequence :
HAL_StatusTypeDef HAL_PPP_Transmit ( PPP_HandleTypeDef * phandle, uint8_t pData, int16_tSize,uint32_tTimeout) { if((pData == NULL ) || (Size == 0)) { return HAL_ERROR; } (…) while (data processing is running) { if( timeout reached ) { return HAL_TIMEOUT; } } (…) return HAL_OK; }
4.12.3.2 Interrupt mode
In Interrupt mode, the HAL function returns the process status after starting the data processing and enabling the appropriate interruption. The end of the operation is indicated by a callback declared as a weak function. It can be customized by the user to be informed in real-time about the process completion. The user can also get the process status through the HAL_PPP_GetState() function.
In Interrupt mode, four functions are declared in the driver:
HAL_PPP_Process_IT(): launches the process
HAL_PPP_IRQHandler(): global PPP peripheral interruption
__weak HAL_PPP_ProcessCpltCallback (): callback relative to the process completion.
__weak HAL_PPP_ProcessErrorCallback(): callback relative to the process Error.
UM2217 - Rev 5
page 38/3786
Page 39
UM2217
How to use HAL drivers
To use a process in Interrupt mode, HAL_PPP_Process_IT() is called in the user file and HAL_PPP_IRQHandler in stm32h7xx_it.c.
The HAL_PPP_ProcessCpltCallback() function is declared as weak function in the driver. This means that the user can declare it again in the application. The function in the driver is not modified.
An example of use is illustrated below:
main.c file:
UART_HandleTypeDef UartHandle;
int main(void) { /* Set User Parameters */ UartHandle.Init.BaudRate = 9600; UartHandle.Init.WordLength = UART_DATABITS_8; UartHandle.Init.StopBits = UART_STOPBITS_1; UartHandle.Init.Parity = UART_PARITY_NONE; UartHandle.Init.HwFlowCtl = UART_HWCONTROL_NONE; UartHandle.Init.Mode = UART_MODE_TX_RX; UartHandle.Init.Instance = USART1; HAL_UART_Init(&UartHandle); HAL_UART_SendIT(&UartHandle, TxBuffer, sizeof(TxBuffer)); while (1); } void HAL_UART_TxCpltCallback(UART_HandleTypeDef *huart) { } void HAL_UART_ErrorCallback(UART_HandleTypeDef *huart) { }
stm32h7xx_it.cfile:
extern UART_HandleTypeDef UartHandle;
void USART1_IRQHandler(void) { HAL_UART_IRQHandler(&UartHandle); }
4.12.3.3 DMA mode
In DMA mode, the HAL function returns the process status after starting the data processing through the DMA and after enabling the appropriate DMA interruption. The end of the operation is indicated by a callback declared as a weak function and can be customized by the user to be informed in real-time about the process completion. The user can also get the process status through the HAL_PPP_GetState() function. For the DMA mode, three functions are declared in the driver:
HAL_PPP_Process_DMA(): launch the process
HAL_PPP_DMA_IRQHandler(): the DMA interruption used by the PPP peripheral
__weak HAL_PPP_ProcessCpltCallback(): the callback relative to the process completion.
__weak HAL_PPP_ErrorCpltCallback(): the callback relative to the process Error.
To use a process in DMA mode, HAL_PPP_Process_DMA() is called in the user file and the HAL_PPP_DMA_IRQHandler() is placed in the stm32h7xx_it.c. When DMA mode is used, the DMA initialization is done in the HAL_PPP_MspInit() callback. The user should also associate the DMA handle to the PPP handle. For this purpose, the handles of all the peripheral drivers that use the DMA must be declared as follows:
UM2217 - Rev 5
page 39/3786
Page 40
typedef struct { PPP_TypeDef *Instance; /* Register base address */ PPP_InitTypeDef Init; /* PPP communication parameters */ HAL_StateTypeDef State; /* PPP communication state */ (…) DMA_HandleTypeDef *hdma; /* associated DMA handle */ } PPP_HandleTypeDef;
The initialization is done as follows (UART example):
int main(void) { /* Set User Parameters */ UartHandle.Init.BaudRate = 9600; UartHandle.Init.WordLength = UART_DATABITS_8; UartHandle.Init.StopBits = UART_STOPBITS_1; UartHandle.Init.Parity = UART_PARITY_NONE; UartHandle.Init.HwFlowCtl = UART_HWCONTROL_NONE; UartHandle.Init.Mode = UART_MODE_TX_RX; UartHandle.Init.Instance = UART1; HAL_UART_Init(&UartHandle); (..) } void HAL_USART_MspInit (UART_HandleTypeDef * huart) { static DMA_HandleTypeDef hdma_tx; static DMA_HandleTypeDef hdma_rx; (…) __HAL_LINKDMA(UartHandle, DMA_Handle_tx, hdma_tx); __HAL_LINKDMA(UartHandle, DMA_Handle_rx, hdma_rx); (…) }
UM2217
How to use HAL drivers
The HAL_PPP_ProcessCpltCallback() function is declared as weak function in the driver that means, the user can declare it again in the application code. The function in the driver should not be modified.
An example of use is illustrated below:
main.c file:
UART_HandleTypeDef UartHandle; int main(void) { /* Set User Paramaters */ UartHandle.Init.BaudRate = 9600; UartHandle.Init.WordLength = UART_DATABITS_8; UartHandle.Init.StopBits = UART_STOPBITS_1; UartHandle.Init.Parity = UART_PARITY_NONE; UartHandle.Init.HwFlowCtl = UART_HWCONTROL_NONE; UartHandle.Init.Mode = UART_MODE_TX_RX; UartHandle.Init.Instance = USART1; HAL_UART_Init(&UartHandle); HAL_UART_Send_DMA(&UartHandle, TxBuffer, sizeof(TxBuffer)); while (1); } void HAL_UART_TxCpltCallback(UART_HandleTypeDef *phuart) { } void HAL_UART_TxErrorCallback(UART_HandleTypeDef *phuart) { }
stm32h7xx_it.c file:
UM2217 - Rev 5
page 40/3786
Page 41
extern UART_HandleTypeDef UartHandle; void DMAx_IRQHandler(void) { HAL_DMA_IRQHandler(&UartHandle.DMA_Handle_tx); }
HAL_USART_TxCpltCallback() and HAL_USART_ErrorCallback() should be linked in the HAL_PPP_Process_DMA() function to the DMA transfer complete callback and the DMA transfer Error callback
by using the following statement:
HAL_PPP_Process_DMA (PPP_HandleTypeDef *hppp, Params….) { (…) hppp->DMA_Handle->XferCpltCallback = HAL_UART_TxCpltCallback ; hppp->DMA_Handle->XferErrorCallback = HAL_UART_ErrorCallback ; (…) }

4.12.4 Timeout and error management

4.12.4.1 Timeout management
The timeout is often used for the APIs that operate in Polling mode. It defines the delay during which a blocking process should wait till an error is returned. An example is provided below:
UM2217
How to use HAL drivers
HAL_StatusTypeDef HAL_DMA_PollForTransfer(DMA_HandleTypeDef *hdma, uint32_t CompleteLevel, uint32_t Timeout)
The timeout possible values are the following:
Table 15. Timeout values
Timeout value Description
0 No poll : Immediate process check and exit
1 ... (HAL_MAX_DELAY -1)
1. HAL_MAX_DELAY is defined in the stm32h7xx_hal_def.h as 0xFFFFFFFF
HAL_MAX_DELAY Infinite poll till process is successful
(1)
Timeout in ms
However, in some cases, a fixed timeout is used for system peripherals or internal HAL driver processes. In these cases, the timeout has the same meaning and is used in the same way, except when it is defined locally in the drivers and cannot be modified or introduced as an argument in the user application.
Example of fixed timeout:
UM2217 - Rev 5
page 41/3786
Page 42
#define LOCAL_PROCESS_TIMEOUT 100 HAL_StatusTypeDef HAL_PPP_Process(PPP_HandleTypeDef) { (…) timeout = HAL_GetTick() + LOCAL_PROCESS_TIMEOUT; (…) while(ProcessOngoing) { (…) if(HAL_GetTick() ≥ timeout) { /* Process unlocked */ __HAL_UNLOCK(hppp); hppp->State= HAL_PPP_STATE_TIMEOUT; return HAL_PPP_STATE_TIMEOUT; } } (…) }
The following example shows how to use the timeout inside the polling functions:
HAL_PPP_StateTypeDef HAL_PPP_Poll (PPP_HandleTypeDef *hppp, uint32_t Timeout) { (…) timeout = HAL_GetTick() + Timeout; (…) while(ProcessOngoing) { (…) if(Timeout != HAL_MAX_DELAY) { if(HAL_GetTick() ≥ timeout) { /* Process unlocked */ __HAL_UNLOCK(hppp); hppp->State= HAL_PPP_STATE_TIMEOUT; return hppp->State; } } (…) }
UM2217
How to use HAL drivers
4.12.4.2 Error management
The HAL drivers implement a check on the following items:
Valid parameters: for some process the used parameters should be valid and already defined, otherwise the system may crash or go into an undefined state. These critical parameters are checked before being used (see example below).
HAL_StatusTypeDef HAL_PPP_Process(PPP_HandleTypeDef* hppp, uint32_t *pdata, uint32 Size) { if ((pData == NULL ) || (Size == 0)) { return HAL_ERROR; } }
UM2217 - Rev 5
page 42/3786
Page 43
UM2217
How to use HAL drivers
Valid handle: the PPP peripheral handle is the most important argument since it keeps the PPP driver vital parameters. It is always checked in the beginning of the HAL_PPP_Init() function.
HAL_StatusTypeDef HAL_PPP_Init(PPP_HandleTypeDef* hppp) { if (hppp == NULL) //the handle should be already allocated { return HAL_ERROR; } }
Timeout error: the following statement is used when a timeout error occurs:
while (Process ongoing) { timeout = HAL_GetTick() + Timeout; while (data processing is running) { if(timeout) { return HAL_TIMEOUT; } }
When an error occurs during a peripheral process, HAL_PPP_Process () returns with a HAL_ERROR status. The HAL PPP driver implements the HAL_PPP_GetError () to allow retrieving the origin of the error.
HAL_PPP_ErrorTypeDef HAL_PPP_GetError (PPP_HandleTypeDef *hppp);
In all peripheral handles, a HAL_PPP_ErrorTypeDef is defined and used to store the last error code.
typedef struct { PPP_TypeDef * Instance; /* PPP registers base address */ PPP_InitTypeDef Init; /* PPP initialization parameters */ HAL_LockTypeDef Lock; /* PPP locking object */ __IO HAL_PPP_StateTypeDef State; /* PPP state */ __IO HAL_PPP_ErrorTypeDef ErrorCode; /* PPP Error code */ (…) /* PPP specific parameters */ } PPP_HandleTypeDef;
The error state and the peripheral global state are always updated before returning an error:
PPP->State = HAL_PPP_READY; /* Set the peripheral ready */ PP->ErrorCode = HAL_ERRORCODE ; /* Set the error code */ _HAL_UNLOCK(PPP) ; /* Unlock the PPP resources */ return HAL_ERROR; /*return with HAL error */
HAL_PPP_GetError () must be used in interrupt mode in the error callback:
void HAL_PPP_ProcessCpltCallback(PPP_HandleTypeDef *hspi) { ErrorCode = HAL_PPP_GetError (hppp); /* retreive error code */ }
4.12.4.3
UM2217 - Rev 5
Run-time checking
The HAL implements run-time failure detection by checking the input values of all HAL driver functions. The run­time checking is achieved by using an assert_param macro. This macro is used in all the HAL driver functions which have an input parameter. It allows verifying that the input value lies within the parameter allowed values.
To enable the run-time checking, use the assert_param macro, and leave the define USE_FULL_ASSERT uncommented in stm32h7xx_hal_conf.h file.
page 43/3786
Page 44
UM2217
How to use HAL drivers
void HAL_UART_Init(UART_HandleTypeDef *huart) { (..) /* Check the parameters */ assert_param(IS_UART_INSTANCE(huart->Instance)); assert_param(IS_UART_BAUDRATE(huart->Init.BaudRate)); assert_param(IS_UART_WORD_LENGTH(huart->Init.WordLength)); assert_param(IS_UART_STOPBITS(huart->Init.StopBits)); assert_param(IS_UART_PARITY(huart->Init.Parity)); assert_param(IS_UART_MODE(huart->Init.Mode)); assert_param(IS_UART_HARDWARE_FLOW_CONTROL(huart->Init.HwFlowCtl)); (..)
/** @defgroup UART_Word_Length * @{ */ #define UART_WORDLENGTH_8B ((uint32_t)0x00000000) #define UART_WORDLENGTH_9B ((uint32_t)USART_CR1_M) #define IS_UART_WORD_LENGTH(LENGTH) (((LENGTH) == UART_WORDLENGTH_8B) || \ ((LENGTH) == UART_WORDLENGTH_9B))
If the expression passed to the assert_param macro is false, theassert_failed function is called and returns the name of the source file and the source line number of the call that failed. If the expression is true, no value is returned.
The assert_param macro is implemented in stm32h7xx_hal_conf.h:
/* Exported macro ------------------------------------------------------------*/ #ifdef USE_FULL_ASSERT /** * @brief The assert_param macro is used for function's parameters check. * @param expr: If expr is false, it calls assert_failed function * which reports the name of the source file and the source * line number of the call that failed. * If expr is true, it returns no value. * @retval None */ #define assert_param(expr) ((expr)?(void)0:assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions --------------------------------------*/ void assert_failed(uint8_t* file, uint32_t line); #else #define assert_param(expr)((void)0) #endif /* USE_FULL_ASSERT */
The assert_failed function is implemented in the main.c file or in any other user C file:
#ifdef USE_FULL_ASSERT /** * @brief Reports the name of the source file and the source line number * where the assert_param error has occurred. * @param file: pointer to the source file name * @param line: assert_param error line source number * @retval None */ void assert_failed(uint8_t* file, uint32_t line) { /* User can add his own implementation to report the file name and line number, ex: printf("Wrong parameters value: file %s on line %d\r\n", file, line) */ /* Infinite loop */ while (1) { } }
Note: Because of the overhead run-time checking introduces, it is recommended to use it during application
code development and debugging, and to remove it from the final application to improve code size and speed.
UM2217 - Rev 5
page 44/3786
Page 45

5 Overview of low-layer drivers

The low-layer (LL) drivers are designed to offer a fast light-weight expert-oriented layer which is closer to the hardware than the HAL. Contrary to the HAL, LL APIs are not provided for peripherals where optimized access is not a key feature, or those requiring heavy software configuration and/or complex upper-level stack (such as USB).
The LL drivers feature:
A set of functions to initialize peripheral main features according to the parameters specified in data structures
A set of functions used to fill initialization data structures with the reset values of each field
Functions to perform peripheral de-initialization (peripheral registers restored to their default values)
A set of inline functions for direct and atomic register access
Full independence from HAL since LL drivers can be used either in standalone mode (without HAL drivers) or in mixed mode (with HAL drivers)
Full coverage of the supported peripheral features.
The low-layer drivers provide hardware services based on the available features of the STM32 peripherals. These services reflect exactly the hardware capabilities and provide one-shot operations that must be called following the programming model described in the microcontroller line reference manual. As a result, the LL services do not implement any processing and do not require any additional memory resources to save their states, counter or data pointers: all the operations are performed by changing the associated peripheral registers content.
UM2217
Overview of low-layer drivers

5.1 Low-layer files

The low-layer drivers are built around header/C files (one per each supported peripheral) plus five header files for some System and Cortex related features.
File Description
stm32h7xx_ll_bus.h
stm32h7xx_ll_ppp.h/.c
stm32h7xx_ll_cortex.h
stm32h7xx_ll_utils.h/.c
stm32h7xx_ll_system.h
stm32_assert_template.h
Table 16. LL driver files
This is the h-source file for core bus control and peripheral clock activation and deactivation
Example: LL_AHB2_GRP1_EnableClock
stm32h7xx_ll_ppp.c provides peripheral initialization functions such as LL_PPP_Init(), LL_PPP_StructInit(), LL_PPP_DeInit(). All the other APIs are definined within stm32h7xx_ll_ppp.h file.
The low-layer PPP driver is a standalone module. To use it, the application must include it in the stm32h7xx_ll_ppp.h file.
Cortex-M related register operation APIs including the Systick, Low power (such as LL_SYSTICK_xxxxx and LL_LPM_xxxxx "Low Power Mode")
This file covers the generic APIs:
Read of device unique ID and electronic signature
Timebase and delay management
System clock configuration.
System related operations.
Example: LL_SYSCFG_xxx, LL_DBGMCU_xxx and LL_FLASH_xxx and LL_VREFBUF_xxx
Template file allowing to define the assert_param macro, that is used when run-time checking is enabled.
This file is required only when the LL drivers are used in standalone mode (without calling the HAL APIs). It should be copied to the application folder and renamed to stm32_assert.h.
Note: There is no configuration file for the LL drivers.
UM2217 - Rev 5
page 45/3786
Page 46
The low-layer files are located in the same HAL driver folder.
Figure 10. Low-layer driver folders
UM2217
Low-layer files
UM2217 - Rev 5
In general, low-layer drivers include only the STM32 CMSIS device file.
#include "stm32yyxx.h"
page 46/3786
Page 47

Overview of low-layer APIs and naming rules

Figure 11. Low-layer driver CMSIS files
UM2217
Application files have to include only the used low-layer driver header files.
5.2
Overview of low-layer APIs and naming rules

5.2.1 Peripheral initialization functions

The LL drivers offer three sets of initialization functions. They are defined in stm32h7xx_ll_ppp.c file:
Functions to initialize peripheral main features according to the parameters specified in data structures
A set of functions used to fill initialization data structures with the reset values of each field
Function for peripheral de-initialization (peripheral registers restored to their default values)
The definition of these LL initialization functions and associated resources (structure, literals and prototypes) is conditioned by a compilation switch: USE_FULL_LL_DRIVER. To use these functions, this switch must be added in the toolchain compiler preprocessor or to any generic header file which is processed before the LL drivers.
The below table shows the list of the common functions provided for all the supported peripherals:
UM2217 - Rev 5
page 47/3786
Page 48
Overview of low-layer APIs and naming rules
Table 17. Common peripheral initialization functions
UM2217
Functions
LL_PPP_Init ErrorStatus
LL_PPP_StructInit void
Return
Type
Parameters Description
PPP_TypeDef* PPPx
LL_PPP_InitTypeDef*
PPP_InitStruct
LL_PPP_InitTypeDef*
PPP_InitStruct
Initializes the peripheral main features according to the parameters specified in PPP_InitStruct.
Example: LL_USART_Init(USART_TypeDef *USARTx, LL_USART_InitTypeDef *USART_InitStruct)
Fills each PPP_InitStruct member with its default value.
Example. LL_USART_StructInit(LL_USART_InitTypeDef *USART_InitStruct)
De-initializes the peripheral registers, that is restore them
LL_PPP_DeInit ErrorStatus PPP_TypeDef* PPPx
to their default reset values.
Example. LL_USART_DeInit(USART_TypeDef *USARTx)
Additional functions are available for some peripherals (refer to Table 18. Optional peripheral initialization
functions ).
Table 18. Optional peripheral initialization functions
Functions
Return
Type
Parameters Examples
Initializes peripheral features according to the parameters specified in PPP_InitStruct.
LL_PPP{_CATEGORY}_Init ErrorStatus
LL_PPP{_CATEGORY}_StructInit
LL_PPP_CommonInit ErrorStatus
LL_PPP_CommonStructInit void
void
PPP_TypeDef* PPPx
LL_PPP{_CATEGORY}_InitTypeDef*
PPP{_CATEGORY}_InitStruct
LL_PPP{_CATEGORY}_InitTypeDef*
PPP{_CATEGORY}_InitStruct
PPP_TypeDef* PPPx
LL_PPP_CommonInitTypeDef*
PPP_CommonInitStruct
LL_PPP_CommonInitTypeDef*
PPP_CommonInitStruct
Example:
LL_ADC_INJ_Init(ADC_TypeDef *ADCx, LL_ADC_INJ_InitTypeDef *ADC_INJ_InitStruct)
LL_RTC_TIME_Init(RTC_TypeDef *RTCx, uint32_t RTC_Format, LL_RTC_TimeTypeDef *RTC_TimeStruct)
LL_RTC_DATE_Init(RTC_TypeDef *RTCx, uint32_t RTC_Format, LL_RTC_DateTypeDef *RTC_DateStruct)
LL_TIM_IC_Init(TIM_TypeDef* TIMx, uint32_t Channel, LL_TIM_IC_InitTypeDef* TIM_IC_InitStruct)
LL_TIM_ENCODER_Init(TIM_TypeDef* TIMx, LL_TIM_ENCODER_InitTypeDef* TIM_EncoderInitStruct)
Fills each PPP{_CATEGORY}_InitStruct member with its default value.
Example: LL_ADC_INJ_StructInit(LL_ADC_INJ_InitTypeDef *ADC_INJ_InitStruct)
Initializes the common features shared between different instances of the same peripheral.
Example: LL_ADC_CommonInit(ADC_Common_TypeDef *ADCxy_COMMON, LL_ADC_CommonInitTypeDef *ADC_CommonInitStruct)
Fills each PPP_CommonInitStruct member with its default value
Example: LL_ADC_CommonStructInit(LL_ADC_CommonInitTypeDef *ADC_CommonInitStruct)
UM2217 - Rev 5
page 48/3786
Page 49
UM2217
Overview of low-layer APIs and naming rules
Functions
Return
Type
Parameters Examples
PPP_TypeDef* PPPx
LL_PPP_ClockInit
ErrorStatus
LL_PPP_ClockInitTypeDef*
PPP_ClockInitStruct
LL_PPP_ClockStructInit void
LL_PPP_ClockInitTypeDef*
PPP_ClockInitStruct
5.2.1.1 Run-time checking
Like HAL drivers, LL initialization functions implement run-time failure detection by checking the input values of all LL driver functions. For more details please refer to Section 4.12.4.3 Run-time checking.
When using the LL drivers in standalone mode (without calling HAL functions), the following actions are required to use run-time checking:
1. Copy stm32_assert_template.h to the application folder and rename it to stm32_assert.h. This file defines the assert_param macro which is used when run-time checking is enabled.
2. Include stm32_assert.h file within the application main header file.
3. Add the USE_FULL_ASSERT compilation switch in the toolchain compiler preprocessor or in any generic header file which is processed before the stm32_assert.h driver.
Note: Run-time checking is not available for LL inline functions.
Initializes the peripheral clock configuration in synchronous mode.
Example: LL_USART_ClockInit(USART_TypeDef *USARTx, LL_USART_ClockInitTypeDef *USART_ClockInitStruct)
Fills each PPP_ClockInitStruct member with its default value
Example: LL_USART_ClockStructInit(LL_USART_ClockInitTypeDef *USART_ClockInitStruct)

5.2.2 Peripheral register-level configuration functions

On top of the peripheral initialization functions, the LL drivers offer a set of inline functions for direct atomic register access. Their format is as follows:
__STATIC_INLINE return_type LL_PPP_Function (PPPx_TypeDef *PPPx, args)
The “Function” naming is defined depending to the action category:
Specific Interrupt, DMA request and status flags management: Set/Get/Clear/Enable/Disable flags on interrupt and status registers
Table 19. Specific Interrupt, DMA request and status flags management
Name Examples
LL_RCC_IsActiveFlag_LSIRDY
LL_PPP_{_CATEGORY}_ActionItem_BITNAME
LL_PPP{_CATEGORY}_IsItem_BITNAME_Action
Table 20. Available function formats
Item
Flag
Interrupts
DMA
Action Format
Get LL_PPP_IsActiveFlag_BITNAME
Clear LL_PPP_ClearFlag_BITNAME
Enable LL_PPP_EnableIT_BITNAME
Disable LL_PPP_DisableIT_BITNAME
Get LL_PPP_IsEnabledIT_BITNAME
Enable LL_PPP_EnableDMAReq_BITNAME
LL_RCC_IsActiveFlag_FWRST()
LL_ADC_ClearFlag_EOC(ADC1)
LL_DMA_ClearFlag_TCx(DMA_TypeDef* DMAx)
UM2217 - Rev 5
page 49/3786
Page 50
Overview of low-layer APIs and naming rules
Item Action Format
(Continued)
DMA
Disable LL_PPP_DisableDMAReq_BITNAME
Get LL_PPP_IsEnabledDMAReq_BITNAME
Note: BITNAME refers to the peripheral register bit name as described in the product line reference manual.
Peripheral clock activation/deactivation management: Enable/Disable/Reset a peripheral clock
Table 21. Peripheral clock activation/deactivation management
Name Examples
LL_AHB2_GRP1_EnableClock (LL_AHB2_GRP1_PERIPH_GPIOA|
LL_BUS_GRPx_ActionClock{Mode}
LL_AHB2_GRP1_PERIPH_GPIOB)
LL_APB1_GRP1_EnableClockSleep (LL_APB1_GRP1_PERIPH_DAC1)
Note: 'x' corresponds to the group index and refers to the index of the modified register on a given bus. 'bus'
corresponds to the bus name.
Peripheral activation/deactivation management : Enable/disable a peripheral or activate/deactivate specific peripheral features
UM2217
Table 22. Peripheral activation/deactivation management
Name
LL_PPP{_CATEGORY}_Action{Item}
LL_PPP{_CATEGORY}_IsItemAction
LL_ADC_Enable ()
LL_ADC_StartCalibration();
LL_ADC_IsCalibrationOnGoing;
LL_RCC_HSI_Enable ()
LL_RCC_HSI_IsReady()
Examples
Peripheral configuration management : Set/get a peripheral configuration settings
Table 23. Peripheral configuration management
Name
LL_PPP{_CATEGORY}_Set{ or
Get}ConfigItem
Examples
LL_USART_SetBaudRate (USART2, Clock, LL_USART_BAUDRATE_9600)
Peripheral register management : Write/read the content of a register/retrun DMA relative register address
Table 24. Peripheral register management
UM2217 - Rev 5
Name
LL_PPP_WriteReg(__INSTANCE__, __REG__, __VALUE__)
LL_PPP_ReadReg(__INSTANCE__, __REG__)
LL_PPP_DMA_GetRegAddr (PPP_TypeDef *PPPx,{Sub Instance if any ex: Channel} , {uint32_t Propriety})
page 50/3786
Page 51
Overview of low-layer APIs and naming rules
Note: The Propriety is a variable used to identify the DMA transfer direction or the data register type.
UM2217
UM2217 - Rev 5
page 51/3786
Page 52
UM2217
Cohabiting of HAL and LL

6 Cohabiting of HAL and LL

The low-ayer APIs are designed to be used in standalone mode or combined with the HAL. They cannot be automatically used with the HAL for the same peripheral instance. If you use the LL APIs for a specific instance, you can still use the HAL APIs for other instances. Be careful that the low-layer APIs might overwrite some registers which content is mirrored in the HAL handles.

6.1 Low-layer driver used in Standalone mode

The low-layer APIs can be used without calling the HAL driver services. This is done by simply including stm32h7xx_ll_ppp.h in the application files. The LL APIs for a given peripheral are called by executing the same sequence as the one recommended by the programming model in the corresponding product line reference manual. In this case the HAL drivers associated to the used peripheral can be removed from the workspace. However the STM32CubeH7 framework should be used in the same way as in the HAL drivers case which means that System file, startup file and CMSIS should always be used.
Note: When the BSP drivers are included, the used HAL drivers associated with the BSP functions drivers should be
included in the workspace, even if they are not used by the application layer.
6.2
Note: 1. When the HAL Init/DeInit APIs are not used and are replaced by the low-layer macros, the InitMsp()

Mixed use of low-layer APIs and HAL drivers

In this case the low-layer APIs are used in conjunction with the HAL drivers to achieve direct and register level based operations.
Mixed use is allowed, however some consideration should be taken into account:
It is recommended to avoid using simultaneously the HAL APIs and the combination of low-layer APIs for a given peripheral instance. If this is the case, one or more private fields in the HAL PPP handle structure should be updated accordingly.
For operations and processes that do not alter the handle fields including the initialization structure, the HAL driver APIs and the low-layer services can be used together for the same peripheral instance.
The low-layer drivers can be used without any restriction with all the HAL drivers that are not based on handle objects (RCC, common HAL, flash and GPIO).
Several examples showing how to use HAL and LL in the same application are provided within stm32h7 firmware package (refer to Examples_MIX projects).
functions are not called and the MSP initialization should be done in the user application.
2. When process APIs are not used and the corresponding function is performed through the low-layer APIs, the callbacks are not called and post processing or error management should be done by the user application.
3. When the LL APIs is used for process operations, the IRQ handler HAL APIs cannot be called and the IRQ should be implemented by the user application. Each LL driver implements the macros needed to read and clear the associated interrupt flags.
UM2217 - Rev 5
page 52/3786
Page 53

7 HAL System Driver

7.1 HAL Firmware driver defines

The following section lists the various define and macros of the module.
UM2217
HAL System Driver
UM2217 - Rev 5
page 53/3786
Page 54

8 HAL ADC Generic Driver

8.1 ADC Firmware driver registers structures

8.1.1 ADC_OversamplingTypeDef

ADC_OversamplingTypeDef is defined in the stm32h7xx_hal_adc.h
Data Fields
uint32_t Ratio
uint32_t RightBitShift
uint32_t TriggeredMode
uint32_t OversamplingStopReset
Field Documentation
uint32_t ADC_OversamplingTypeDef::Ratio
Configures the oversampling ratio.
uint32_t ADC_OversamplingTypeDef::RightBitShift
Configures the division coefficient for the Oversampler. This parameter can be a value of
ADC_HAL_EC_OVS_SHIFT
uint32_t ADC_OversamplingTypeDef::TriggeredMode
Selects the regular triggered oversampling mode. This parameter can be a value of
ADC_HAL_EC_OVS_DISCONT_MODE
uint32_t ADC_OversamplingTypeDef::OversamplingStopReset
Selects the regular oversampling mode. The oversampling is either temporary stopped or reset upon an injected sequence interruption. If oversampling is enabled on both regular and injected groups, this parameter is discarded and forced to setting "ADC_REGOVERSAMPLING_RESUMED_MODE" (the oversampling buffer is zeroed during injection sequence). This parameter can be a value of
ADC_HAL_EC_OVS_SCOPE_REG
UM2217
HAL ADC Generic Driver

8.1.2 ADC_InitTypeDef

ADC_InitTypeDef is defined in the stm32h7xx_hal_adc.h
Data Fields
uint32_t ClockPrescaler
uint32_t Resolution
uint32_t DataAlign
uint32_t ScanConvMode
uint32_t EOCSelection
FunctionalState LowPowerAutoWait
FunctionalState ContinuousConvMode
uint32_t NbrOfConversion
FunctionalState DiscontinuousConvMode
uint32_t NbrOfDiscConversion
uint32_t ExternalTrigConv
uint32_t ExternalTrigConvEdge
uint32_t ConversionDataManagement
uint32_t SamplingMode
FunctionalState DMAContinuousRequests
uint32_t Overrun
uint32_t LeftBitShift
FunctionalState OversamplingMode
UM2217 - Rev 5
page 54/3786
Page 55
ADC Firmware driver registers structures
ADC_OversamplingTypeDef Oversampling
Field Documentation
uint32_t ADC_InitTypeDef::ClockPrescaler
Select ADC clock source (synchronous clock derived from APB clock or asynchronous clock derived from system clock or PLL (Refer to reference manual for list of clocks available)) and clock prescaler. This parameter can be a value of ADC_HAL_EC_COMMON_CLOCK_SOURCE. Note: The ADC clock configuration is common to all ADC instances. Note: In case of usage of channels on injected group, ADC frequency should be lower than AHB clock frequency /4 for resolution 12 or 10 bits, AHB clock frequency /3 for resolution 8 bits, AHB clock frequency /2 for resolution 6 bits. Note: In case of synchronous clock mode based on HCLK/1, the configuration must be enabled only if the system clock has a 50% duty clock cycle (APB prescaler configured inside RCC must be bypassed and PCLK clock must have 50% duty cycle). Refer to reference manual for details. Note: In case of usage of asynchronous clock, the selected clock must be preliminarily enabled at RCC top level. Note: This parameter can be modified only if all ADC instances are disabled.
uint32_t ADC_InitTypeDef::Resolution
Configure the ADC resolution. This parameter can be a value of ADC_HAL_EC_RESOLUTION
uint32_t ADC_InitTypeDef::DataAlign
Specify ADC data alignment in conversion data register (right or left). Refer to reference manual for alignments formats versus resolutions. This parameter can be a value of ADC_HAL_EC_DATA_ALIGN This parameter is reserved for ADC3 on devices STM32H72xx and STM32H73xx
uint32_t ADC_InitTypeDef::ScanConvMode
Configure the sequencer of ADC groups regular and injected. This parameter can be associated to parameter 'DiscontinuousConvMode' to have main sequence subdivided in successive parts. If disabled: Conversion is performed in single mode (one channel converted, the one defined in rank 1). Parameters 'NbrOfConversion' and 'InjectedNbrOfConversion' are discarded (equivalent to set to 1). If enabled: Conversions are performed in sequence mode (multiple ranks defined by 'NbrOfConversion' or 'InjectedNbrOfConversion' and rank of each channel in sequencer). Scan direction is upward: from rank 1 to rank 'n'. This parameter can be a value of ADC_Scan_mode
uint32_t ADC_InitTypeDef::EOCSelection
Specify which EOC (End Of Conversion) flag is used for conversion by polling and interruption: end of unitary conversion or end of sequence conversions. This parameter can be a value of ADC_EOCSelection.
FunctionalState ADC_InitTypeDef::LowPowerAutoWait
Select the dynamic low power Auto Delay: new conversion start only when the previous conversion (for ADC group regular) or previous sequence (for ADC group injected) has been retrieved by user software, using function HAL_ADC_GetValue() or HAL_ADCEx_InjectedGetValue(). This feature automatically adapts the frequency of ADC conversions triggers to the speed of the system that reads the data. Moreover, this avoids risk of overrun for low frequency applications. This parameter can be set to ENABLE or DISABLE. Note: Do not use with interruption or DMA (HAL_ADC_Start_IT(), HAL_ADC_Start_DMA()) since they clear immediately the EOC flag to free the IRQ vector sequencer. Do use with polling: 1. Start conversion with
HAL_ADC_Start(), 2. Later on, when ADC conversion data is needed: use HAL_ADC_PollForConversion() to ensure that conversion is completed and HAL_ADC_GetValue() to
retrieve conversion result and trig another conversion start. (in case of usage of ADC group injected, use the equivalent functions HAL_ADCExInjected_Start(), HAL_ADCEx_InjectedGetValue(), ...).
FunctionalState ADC_InitTypeDef::ContinuousConvMode
Specify whether the conversion is performed in single mode (one conversion) or continuous mode for ADC group regular, after the first ADC conversion start trigger occurred (software start or external trigger). This parameter can be set to ENABLE or DISABLE.
uint32_t ADC_InitTypeDef::NbrOfConversion
Specify the number of ranks that will be converted within the regular group sequencer. To use the regular group sequencer and convert several ranks, parameter 'ScanConvMode' must be enabled. This parameter must be a number between Min_Data = 1 and Max_Data = 16. Note: This parameter must be modified when no conversion is on going on regular group (ADC disabled, or ADC enabled without continuous mode or external trigger that could launch a conversion).
UM2217
UM2217 - Rev 5
page 55/3786
Page 56
ADC Firmware driver registers structures
FunctionalState ADC_InitTypeDef::DiscontinuousConvMode
Specify whether the conversions sequence of ADC group regular is performed in Complete-sequence/ Discontinuous-sequence (main sequence subdivided in successive parts). Discontinuous mode is used only if sequencer is enabled (parameter 'ScanConvMode'). If sequencer is disabled, this parameter is discarded. Discontinuous mode can be enabled only if continuous mode is disabled. If continuous mode is enabled, this parameter setting is discarded. This parameter can be set to ENABLE or DISABLE.
uint32_t ADC_InitTypeDef::NbrOfDiscConversion
Specifies the number of discontinuous conversions in which the main sequence of ADC group regular (parameter NbrOfConversion) will be subdivided. If parameter 'DiscontinuousConvMode' is disabled, this parameter is discarded. This parameter must be a number between Min_Data = 1 and Max_Data = 8.
uint32_t ADC_InitTypeDef::ExternalTrigConv
Select the external event source used to trigger ADC group regular conversion start. If set to ADC_SOFTWARE_START, external triggers are disabled and software trigger is used instead. This parameter can be a value of ADC_regular_external_trigger_source. Caution: external trigger source is common to all ADC instances.
uint32_t ADC_InitTypeDef::ExternalTrigConvEdge
Select the external event edge used to trigger ADC group regular conversion start. If trigger source is set to ADC_SOFTWARE_START, this parameter is discarded. This parameter can be a value of
ADC_regular_external_trigger_edge
uint32_t ADC_InitTypeDef::ConversionDataManagement
Specifies whether the Data conversion data is managed: using the DMA (oneshot or circular), or stored in the DR register or transfered to DFSDM register. Note: In continuous mode, DMA must be configured in circular mode. Otherwise an overrun will be triggered when DMA buffer maximum pointer is reached. This parameter can be a value of ADC_ConversionDataManagement. Note: This parameter must be modified when no conversion is on going on both regular and injected groups (ADC disabled, or ADC enabled without continuous mode or external trigger that could launch a conversion).
uint32_t ADC_InitTypeDef::SamplingMode
Select the sampling mode to be used for ADC group regular conversion. This parameter can be a value of
ADC_regular_sampling_mode. Note:
On devices STM32H72xx and STM32H73xx, this parameter is specific to ADC3 only.
FunctionalState ADC_InitTypeDef::DMAContinuousRequests
Specify whether the DMA requests are performed in one shot mode (DMA transfer stops when number of conversions is reached) or in continuous mode (DMA transfer unlimited, whatever number of conversions). This parameter can be set to ENABLE or DISABLE. Notes:
In continuous mode, DMA must be configured in circular mode. Otherwise an overrun will be triggered
when DMA buffer maximum pointer is reached.
Specific to ADC3 only on devices STM32H72xx and STM32H73xx
uint32_t ADC_InitTypeDef::Overrun
Select the behavior in case of overrun: data overwritten or preserved (default). This parameter applies to ADC group regular only. This parameter can be a value of ADC_HAL_EC_REG_OVR_DATA_BEHAVIOR. Note: In case of overrun set to data preserved and usage with programming model with interruption (HAL_Start_IT()): ADC IRQ handler has to clear end of conversion flags, this induces the release of the preserved data. If needed, this data can be saved in function HAL_ADC_ConvCpltCallback(), placed in user program code (called before end of conversion flags clear). Note: Error reporting with respect to the conversion mode:
Usage with ADC conversion by polling for event or interruption: Error is reported only if overrun is set to
data preserved. If overrun is set to data overwritten, user can willingly not read all the converted data, this is not considered as an erroneous case.
Usage with ADC conversion by DMA: Error is reported whatever overrun setting (DMA is expected to
process all data from data register).
uint32_t ADC_InitTypeDef::LeftBitShift
Configures the left shifting applied to the final result with or without oversampling. This parameter can be a value of ADCEx_Left_Bit_Shift
UM2217
UM2217 - Rev 5
page 56/3786
Page 57
FunctionalState ADC_InitTypeDef::OversamplingMode
Specify whether the oversampling feature is enabled or disabled. This parameter can be set to ENABLE or DISABLE. Note: This parameter can be modified only if there is no conversion is ongoing on ADC groups regular and injected
ADC_OversamplingTypeDef ADC_InitTypeDef::Oversampling
Specify the Oversampling parameters. Caution: this setting overwrites the previous oversampling configuration if oversampling is already enabled.

8.1.3 ADC_ChannelConfTypeDef

ADC_ChannelConfTypeDef is defined in the stm32h7xx_hal_adc.h
Data Fields
uint32_t Channel
uint32_t Rank
uint32_t SamplingTime
uint32_t SingleDiff
uint32_t OffsetNumber
uint32_t Offset
FunctionalState OffsetRightShift
uint32_t OffsetSign
FunctionalState OffsetSaturation
FunctionalState OffsetSignedSaturation
Field Documentation
uint32_t ADC_ChannelConfTypeDef::Channel
Specify the channel to configure into ADC regular group. This parameter can be a value of
ADC_HAL_EC_CHANNEL Note: Depending on devices and ADC instances, some channels may not be
available on device package pins. Refer to device datasheet for channels availability.
uint32_t ADC_ChannelConfTypeDef::Rank
Specify the rank in the regular group sequencer. This parameter can be a value of
ADC_HAL_EC_REG_SEQ_RANKS Note: to disable a channel or change order of conversion sequencer,
rank containing a previous channel setting can be overwritten by the new channel setting (or parameter number of conversions adjusted)
uint32_t ADC_ChannelConfTypeDef::SamplingTime
Sampling time value to be set for the selected channel. Unit: ADC clock cycles Conversion time is the addition of sampling time and processing time (12.5 ADC clock cycles at ADC resolution 12 bits, 10.5 cycles at 10 bits, 8.5 cycles at 8 bits, 6.5 cycles at 6 bits). This parameter can be a value of
ADC_HAL_EC_CHANNEL_SAMPLINGTIME Caution: This parameter applies to a channel that can be
used into regular and/or injected group. It overwrites the last setting. Note: In case of usage of internal measurement channels (VrefInt/Vbat/TempSensor), sampling time constraints must be respected (sampling time can be adjusted in function of ADC clock frequency and sampling time setting) Refer to device datasheet for timings values.
uint32_t ADC_ChannelConfTypeDef::SingleDiff
Select single-ended or differential input. In differential mode: Differential measurement is carried out between the selected channel 'i' (positive input) and channel 'i+1' (negative input). Only channel 'i' has to be configured, channel 'i+1' is configured automatically. This parameter must be a value of
ADC_HAL_EC_CHANNEL_SINGLE_DIFF_ENDING Caution: This parameter applies to a channel that can
be used in a regular and/or injected group. It overwrites the last setting. Note: Refer to Reference Manual to ensure the selected channel is available in differential mode. Note: When configuring a channel 'i' in differential mode, the channel 'i+1' is not usable separately. Note: This parameter must be modified when ADC is disabled (before ADC start conversion or after ADC stop conversion). If ADC is enabled, this parameter setting is bypassed without error reporting (as it can be the expected behavior in case of another parameter update on the fly)
uint32_t ADC_ChannelConfTypeDef::OffsetNumber
Select the offset number This parameter can be a value of ADC_HAL_EC_OFFSET_NB Caution: Only one offset is allowed per channel. This parameter overwrites the last setting.
UM2217
ADC Firmware driver registers structures
UM2217 - Rev 5
page 57/3786
Page 58
ADC Firmware driver registers structures
uint32_t ADC_ChannelConfTypeDef::Offset
Define the offset to be subtracted from the raw converted data. Offset value must be a positive number. Depending of ADC resolution selected (16, 14, 12, 10, 8 bits), this parameter must be a number between Min_Data = 0x0000 and Max_Data = 0xFFFF, 0x3FFF, 0xFFF, 0x3FF or 0xFF respectively. Note: This parameter must be modified when no conversion is on going on both regular and injected groups (ADC disabled, or ADC enabled without continuous mode or external trigger that could launch a conversion).
FunctionalState ADC_ChannelConfTypeDef::OffsetRightShift
Define the Right-shift data after Offset correction. This parameter is applied only for 16-bit or 8-bit resolution. This parameter can be set to ENABLE or DISABLE.
uint32_t ADC_ChannelConfTypeDef::OffsetSign
Define if the offset should be substracted (negative sign) or added (positive sign) from or to the raw converted data. This parameter can be a value of ADCEx_OffsetSign. Note:
This parameter must be modified when no conversion is on going on both regular and injected groups
(ADC disabled, or ADC enabled without continuous mode or external trigger that could launch a conversion).
Applicable for ADC3 on devices STM32H72xx and STM32H73xx
FunctionalState ADC_ChannelConfTypeDef::OffsetSaturation
Define if the offset should be saturated upon under or over flow. This parameter value can be ENABLE or DISABLE. Note:
This parameter must be modified when no conversion is on going on both regular and injected groups
(ADC disabled, or ADC enabled without continuous mode or external trigger that could launch a conversion).
Applicable for ADC3 on devices STM32H72xx and STM32H73xx
FunctionalState ADC_ChannelConfTypeDef::OffsetSignedSaturation
Specify whether the Signed saturation feature is used or not. This parameter is applied only for 16-bit or 8-bit resolution. This parameter can be set to ENABLE or DISABLE.
UM2217

8.1.4 ADC_AnalogWDGConfTypeDef

ADC_AnalogWDGConfTypeDef is defined in the stm32h7xx_hal_adc.h
Data Fields
uint32_t WatchdogNumber
uint32_t WatchdogMode
uint32_t Channel
FunctionalState ITMode
uint32_t HighThreshold
uint32_t LowThreshold
uint32_t FilteringConfig
Field Documentation
uint32_t ADC_AnalogWDGConfTypeDef::WatchdogNumber
Select which ADC analog watchdog is monitoring the selected channel. For Analog Watchdog 1: Only 1 channel can be monitored (or overall group of channels by setting parameter 'WatchdogMode') For Analog Watchdog 2 and 3: Several channels can be monitored (by successive calls of 'HAL_ADC_AnalogWDGConfig()' for each channel) This parameter can be a value of
ADC_HAL_EC_AWD_NUMBER.
uint32_t ADC_AnalogWDGConfTypeDef::WatchdogMode
Configure the ADC analog watchdog mode: single/all/none channels. For Analog Watchdog 1: Configure the ADC analog watchdog mode: single channel or all channels, ADC groups regular and-or injected. For Analog Watchdog 2 and 3: Several channels can be monitored by applying successively the AWD init structure. Channels on ADC group regular and injected are not differentiated: Set value 'ADC_ANALOGWATCHDOG_SINGLE_xxx' to monitor 1 channel, value 'ADC_ANALOGWATCHDOG_ALL_xxx' to monitor all channels, 'ADC_ANALOGWATCHDOG_NONE' to monitor no channel. This parameter can be a value of ADC_analog_watchdog_mode.
UM2217 - Rev 5
page 58/3786
Page 59
ADC Firmware driver registers structures
uint32_t ADC_AnalogWDGConfTypeDef::Channel
Select which ADC channel to monitor by analog watchdog. For Analog Watchdog 1: this parameter has an effect only if parameter 'WatchdogMode' is configured on single channel (only 1 channel can be monitored). For Analog Watchdog 2 and 3: Several channels can be monitored. To use this feature, call successively the function HAL_ADC_AnalogWDGConfig() for each channel to be added (or removed with value 'ADC_ANALOGWATCHDOG_NONE'). This parameter can be a value of ADC_HAL_EC_CHANNEL.
FunctionalState ADC_AnalogWDGConfTypeDef::ITMode
Specify whether the analog watchdog is configured in interrupt or polling mode. This parameter can be set to ENABLE or DISABLE
uint32_t ADC_AnalogWDGConfTypeDef::HighThreshold
Configure the ADC analog watchdog High threshold value. Depending of ADC resolution selected (16, 14, 12, 10, 8 bits), this parameter must be a number between Min_Data = 0x000 and Max_Data = 0xFFFF, 0x3FFF, 0xFFF, 0x3FF or 0xFF respectively. Note: Analog watchdog 2 and 3 are limited to a resolution of 8 bits: if ADC resolution is 12 bits the 4 LSB are ignored, if ADC resolution is 10 bits the 2 LSB are ignored. Note: If ADC oversampling is enabled, ADC analog watchdog thresholds are impacted: the comparison of analog watchdog thresholds is done on oversampling intermediate computation (after ratio, before shift application): intermediate register bitfield [32:7] (26 most significant bits).
uint32_t ADC_AnalogWDGConfTypeDef::LowThreshold
Configures the ADC analog watchdog Low threshold value. Depending of ADC resolution selected (16, 14, 12, 10, 8 bits), this parameter must be a number between Min_Data = 0x000 and Max_Data = 0xFFFF, 0x3FFF, 0xFFF, 0x3FF or 0xFF respectively. Note: Analog watchdog 2 and 3 are limited to a resolution of 8 bits: if ADC resolution is 12 bits the 4 LSB are ignored, if ADC resolution is 10 bits the 2 LSB are ignored. Note: If ADC oversampling is enabled, ADC analog watchdog thresholds are impacted: the comparison of analog watchdog thresholds is done on oversampling intermediate computation (after ratio, before shift application): intermediate register bitfield [32:7] (26 most significant bits).
uint32_t ADC_AnalogWDGConfTypeDef::FilteringConfig
Specify whether filtering should be use and the number of samples to consider. Before setting flag or raising interrupt, analog watchdog can wait to have several consecutive out-of-window samples. This parameter allows to configure this number. This parameter only applies to Analog watchdog 1. For others, use value ADC_AWD_FILTERING_NONE. This parameter can be a value of
ADC_analog_watchdog_filtering_config. Applicable for ADC3 on devices STM32H72xx and
STM32H73xx.
UM2217

8.1.5 ADC_InjectionConfigTypeDef

ADC_InjectionConfigTypeDef is defined in the stm32h7xx_hal_adc.h
Data Fields
uint32_t ContextQueue
uint32_t ChannelCount
Field Documentation
uint32_t ADC_InjectionConfigTypeDef::ContextQueue
Injected channel configuration context: build-up over each HAL_ADCEx_InjectedConfigChannel() call to finally initialize JSQR register at HAL_ADCEx_InjectedConfigChannel() last call
uint32_t ADC_InjectionConfigTypeDef::ChannelCount
Number of channels in the injected sequence

8.1.6 ADC_HandleTypeDef

ADC_HandleTypeDef is defined in the stm32h7xx_hal_adc.h
Data Fields
ADC_TypeDef * Instance
ADC_InitTypeDef Init
DMA_HandleTypeDef * DMA_Handle
HAL_LockTypeDef Lock
__IO uint32_t State
__IO uint32_t ErrorCode
UM2217 - Rev 5
page 59/3786
Page 60
ADC_InjectionConfigTypeDef InjectionConfig
Field Documentation
ADC_TypeDef* ADC_HandleTypeDef::Instance
Register base address
ADC_InitTypeDef ADC_HandleTypeDef::Init
ADC initialization parameters and regular conversions setting
DMA_HandleTypeDef* ADC_HandleTypeDef::DMA_Handle
Pointer DMA Handler
HAL_LockTypeDef ADC_HandleTypeDef::Lock
ADC locking object
__IO uint32_t ADC_HandleTypeDef::State
ADC communication state (bitmap of ADC states)
__IO uint32_t ADC_HandleTypeDef::ErrorCode
ADC Error code
ADC_InjectionConfigTypeDef ADC_HandleTypeDef::InjectionConfig
ADC injected channel configuration build-up structure

8.2 ADC Firmware driver API description

UM2217
ADC Firmware driver API description
The following section lists the various functions of the ADC library.

8.2.1 ADC peripheral features

16-bit, 14-bit, 12-bit, 10-bit or 8-bit configurable resolution. Note: On devices STM32H72xx and STM32H73xx, these resolution are applicable to instances ADC1 and ADC2. ADC3 is featuring resolutions 12-bit, 10-bit, 8-bit, 6-bit.
Interrupt generation at the end of regular conversion and in case of analog watchdog or overrun events.
Single and continuous conversion modes.
Scan mode for conversion of several channels sequentially.
Data alignment with in-built data coherency.
Programmable sampling time (channel wise)
External trigger (timer or EXTI) with configurable polarity
DMA request generation for transfer of conversions data of regular group.
Configurable delay between conversions in Dual interleaved mode.
ADC channels selectable single/differential input.
ADC offset shared on 4 offset instances.
ADC calibration
ADC conversion of regular group.
ADC supply requirements: 1.62 V to 3.6 V.
ADC input range: from Vref- (connected to Vssa) to Vref+ (connected to Vdda or to an external voltage reference).

8.2.2 How to use this driver

UM2217 - Rev 5
page 60/3786
Page 61
ADC Firmware driver API description
Configuration of top level parameters related to ADC
1. Enable the ADC interface
As prerequisite, ADC clock must be configured at RCC top level.
Two clock settings are mandatory:
ADC clock (core clock, also possibly conversion clock).
ADC clock (conversions clock). Two possible clock sources: synchronous clock derived from AHB
clock or asynchronous clock derived from system clock, the PLL2 or the PLL3 running up to 400MHz.
Example: Into HAL_ADC_MspInit() (recommended code location) or with other device clock
parameters configuration:
__HAL_RCC_ADC_CLK_ENABLE(); (mandatory) RCC_ADCCLKSOURCE_PLL2 enable:
(optional: if asynchronous clock selected)
RCC_PeriphClkInitTypeDef RCC_PeriphClkInit;
PeriphClkInit.PeriphClockSelection = RCC_PERIPHCLK_ADC;
PeriphClkInit.AdcClockSelection = RCC_ADCCLKSOURCE_PLL2;
HAL_RCCEx_PeriphCLKConfig(&PeriphClkInit);
ADC clock source and clock prescaler are configured at ADC level with parameter "ClockPrescaler"
using function HAL_ADC_Init().
2. ADC pins configuration
Enable the clock for the ADC GPIOs using macro __HAL_RCC_GPIOx_CLK_ENABLE()
Configure these ADC pins in analog mode using function HAL_GPIO_Init()
3. Optionally, in case of usage of ADC with interruptions:
Configure the NVIC for ADC using function HAL_NVIC_EnableIRQ(ADCx_IRQn)
Insert the ADC interruption handler function HAL_ADC_IRQHandler() into the function of
corresponding ADC interruption vector ADCx_IRQHandler().
4. Optionally, in case of usage of DMA:
Configure the DMA (DMA channel, mode normal or circular, ...) using function HAL_DMA_Init().
Configure the NVIC for DMA using function HAL_NVIC_EnableIRQ(DMAx_Channelx_IRQn)
Insert the ADC interruption handler function HAL_ADC_IRQHandler() into the function of
corresponding DMA interruption vector DMAx_Channelx_IRQHandler().
UM2217
Configuration of ADC, group regular, channels parameters
1. Configure the ADC parameters (resolution, data alignment, ...) and regular group parameters (conversion trigger, sequencer, ...) using function HAL_ADC_Init().
2. Configure the channels for regular group parameters (channel number, channel rank into sequencer, ..., into regular group) using function HAL_ADC_ConfigChannel().
3. Optionally, configure the analog watchdog parameters (channels monitored, thresholds, ...) using function HAL_ADC_AnalogWDGConfig().
Execution of ADC conversions
1. Optionally, perform an automatic ADC calibration to improve the conversion accuracy using function HAL_ADCEx_Calibration_Start().
UM2217 - Rev 5
page 61/3786
Page 62
2. ADC driver can be used among three modes: polling, interruption, transfer by DMA.
ADC conversion by polling:
Activate the ADC peripheral and start conversions using function HAL_ADC_Start()
Wait for ADC conversion completion using function HAL_ADC_PollForConversion()
Retrieve conversion results using function HAL_ADC_GetValue()
Stop conversion and disable the ADC peripheral using function HAL_ADC_Stop()
ADC conversion by interruption:
Activate the ADC peripheral and start conversions using function HAL_ADC_Start_IT()
Wait for ADC conversion completion by call of function HAL_ADC_ConvCpltCallback() (this
function must be implemented in user program)
Retrieve conversion results using function HAL_ADC_GetValue()
Stop conversion and disable the ADC peripheral using function HAL_ADC_Stop_IT()
ADC conversion with transfer by DMA:
Activate the ADC peripheral and start conversions using function HAL_ADC_Start_DMA()
Wait for ADC conversion completion by call of function HAL_ADC_ConvCpltCallback() or
HAL_ADC_ConvHalfCpltCallback() (these functions must be implemented in user program)
Conversion results are automatically transferred by DMA into destination variable address.
Stop conversion and disable the ADC peripheral using function HAL_ADC_Stop_DMA()
Note: Callback functions must be implemented in user program:
HAL_ADC_ErrorCallback()
HAL_ADC_LevelOutOfWindowCallback() (callback of analog watchdog)
HAL_ADC_ConvCpltCallback()
HAL_ADC_ConvHalfCpltCallback
UM2217
ADC Firmware driver API description
Deinitialization of ADC
1. Disable the ADC interface
ADC clock can be hard reset and disabled at RCC top level.
Hard reset of ADC peripherals using macro __HAL_RCC_ADCx_FORCE_RESET(),
__HAL_RCC_ADCx_RELEASE_RESET().
ADC clock disable using the equivalent macro/functions as configuration step.
Example: Into HAL_ADC_MspDeInit() (recommended code location) or with other device clock
parameters configuration:
__HAL_RCC_ADC_CLK_DISABLE(); (if not used anymore) RCC_ADCCLKSOURCE_CLKP
restore: (optional)
RCC_PeriphClkInitTypeDef RCC_PeriphClkInit;
PeriphClkInit.PeriphClockSelection = RCC_PERIPHCLK_ADC;
PeriphClkInit.AdcClockSelection = RCC_ADCCLKSOURCE_CLKP;
HAL_RCCEx_PeriphCLKConfig(&PeriphClkInit);
2. ADC pins configuration
Disable the clock for the ADC GPIOs using macro __HAL_RCC_GPIOx_CLK_DISABLE()
3. Optionally, in case of usage of ADC with interruptions:
Disable the NVIC for ADC using function HAL_NVIC_EnableIRQ(ADCx_IRQn)
4. Optionally, in case of usage of DMA:
Deinitialize the DMA using function HAL_DMA_Init().
Disable the NVIC for DMA using function HAL_NVIC_EnableIRQ(DMAx_Channelx_IRQn)
UM2217 - Rev 5
Callback registration
The compilation flag USE_HAL_ADC_REGISTER_CALLBACKS, when set to 1, allows the user to configure dynamically the driver callbacks. Use Functions @ref HAL_ADC_RegisterCallback() to register an interrupt callback.
page 62/3786
Page 63
UM2217
ADC Firmware driver API description
Function @ref HAL_ADC_RegisterCallback() allows to register following callbacks:
ConvCpltCallback : ADC conversion complete callback
ConvHalfCpltCallback : ADC conversion DMA half-transfer callback
LevelOutOfWindowCallback : ADC analog watchdog 1 callback
ErrorCallback : ADC error callback
InjectedConvCpltCallback : ADC group injected conversion complete callback
InjectedQueueOverflowCallback : ADC group injected context queue overflow callback
LevelOutOfWindow2Callback : ADC analog watchdog 2 callback
LevelOutOfWindow3Callback : ADC analog watchdog 3 callback
EndOfSamplingCallback : ADC end of sampling callback
MspInitCallback : ADC Msp Init callback
MspDeInitCallback : ADC Msp DeInit callback This function takes as parameters the HAL peripheral handle, the Callback ID and a pointer to the user callback function.
Use function @ref HAL_ADC_UnRegisterCallback to reset a callback to the default weak function.
@ref HAL_ADC_UnRegisterCallback takes as parameters the HAL peripheral handle, and the Callback ID. This function allows to reset following callbacks:
ConvCpltCallback : ADC conversion complete callback
ConvHalfCpltCallback : ADC conversion DMA half-transfer callback
LevelOutOfWindowCallback : ADC analog watchdog 1 callback
ErrorCallback : ADC error callback
InjectedConvCpltCallback : ADC group injected conversion complete callback
InjectedQueueOverflowCallback : ADC group injected context queue overflow callback
LevelOutOfWindow2Callback : ADC analog watchdog 2 callback
LevelOutOfWindow3Callback : ADC analog watchdog 3 callback
EndOfSamplingCallback : ADC end of sampling callback
MspInitCallback : ADC Msp Init callback
MspDeInitCallback : ADC Msp DeInit callback
By default, after the @ref HAL_ADC_Init() and when the state is @ref HAL_ADC_STATE_RESET all callbacks are set to the corresponding weak functions: examples @ref HAL_ADC_ConvCpltCallback(), @ref HAL_ADC_ErrorCallback(). Exception done for MspInit and MspDeInit functions that are reset to the legacy weak functions in the @ref HAL_ADC_Init()/ @ref HAL_ADC_DeInit() only when these callbacks are null (not registered beforehand).
If MspInit or MspDeInit are not null, the @ref HAL_ADC_Init()/ @ref HAL_ADC_DeInit() keep and use the user MspInit/MspDeInit callbacks (registered beforehand) whatever the state.
Callbacks can be registered/unregistered in @ref HAL_ADC_STATE_READY state only. Exception done MspInit/ MspDeInit functions that can be registered/unregistered in @ref HAL_ADC_STATE_READY or @ref HAL_ADC_STATE_RESET state, thus registered (user) MspInit/DeInit callbacks can be used during the Init/ DeInit.
Then, the user first registers the MspInit/MspDeInit user callbacks using @ref HAL_ADC_RegisterCallback() before calling @ref HAL_ADC_DeInit() or @ref HAL_ADC_Init() function.
When the compilation flag USE_HAL_ADC_REGISTER_CALLBACKS is set to 0 or not defined, the callback registration feature is not available and all callbacks are set to the corresponding weak functions.

8.2.3 Peripheral Control functions

This section provides functions allowing to:
Configure channels on regular group
Configure the analog watchdog
This section contains the following APIs:
HAL_ADC_ConfigChannel
HAL_ADC_AnalogWDGConfig
UM2217 - Rev 5
page 63/3786
Page 64

8.2.4 Peripheral state and errors functions

This subsection provides functions to get in run-time the status of the peripheral.
Check the ADC state
Check the ADC error code
This section contains the following APIs:
HAL_ADC_GetState
HAL_ADC_GetError

8.2.5 Detailed description of functions

HAL_ADC_Init
Function name
HAL_StatusTypeDef HAL_ADC_Init (ADC_HandleTypeDef * hadc)
Function description
Initialize the ADC peripheral and regular group according to parameters specified in structure "ADC_InitTypeDef".
Parameters
hadc: ADC handle
UM2217
ADC Firmware driver API description
Return values
HAL: status
Notes
As prerequisite, ADC clock must be configured at RCC top level (refer to description of RCC configuration
Possibility to update parameters on the fly: This function initializes the ADC MSP (HAL_ADC_MspInit())
This function configures the ADC within 2 scopes: scope of entire ADC and scope of regular group. For
Parameters related to common ADC registers (ADC clock mode) are set only if all ADCs are disabled. If
HAL_ADC_DeInit
Function name
HAL_StatusTypeDef HAL_ADC_DeInit (ADC_HandleTypeDef * hadc)
Function description
Deinitialize the ADC peripheral registers to their default reset values, with deinitialization of the ADC MSP.
for ADC in header of this file).
only when coming from ADC state reset. Following calls to this function can be used to reconfigure some parameters of ADC_InitTypeDef structure on the fly, without modifying MSP configuration. If ADC MSP has to be modified again, HAL_ADC_DeInit() must be called before HAL_ADC_Init(). The setting of these parameters is conditioned to ADC state. For parameters constraints, see comments of structure "ADC_InitTypeDef".
parameters details, see comments of structure "ADC_InitTypeDef".
this is not the case, these common parameters setting are bypassed without error reporting: it can be the intended behaviour in case of update of a parameter of ADC_InitTypeDef on the fly, without disabling the other ADCs.
Parameters
Return values
UM2217 - Rev 5
hadc: ADC handle
HAL: status
page 64/3786
Page 65
Notes
For devices with several ADCs: reset of ADC common registers is done only if all ADCs sharing the same
By default, HAL_ADC_DeInit() set ADC in mode deep power-down: this saves more power by reducing
HAL_ADC_MspInit
Function name
void HAL_ADC_MspInit (ADC_HandleTypeDef * hadc)
Function description
Initialize the ADC MSP.
Parameters
hadc: ADC handle
UM2217
ADC Firmware driver API description
common group are disabled. (function "HAL_ADC_MspDeInit()" is also called under the same conditions: all ADC instances use the same core clock at RCC level, disabling the core clock reset all ADC instances). If this is not the case, reset of these common parameters reset is bypassed without error reporting: it can be the intended behavior in case of reset of a single ADC while the other ADCs sharing the same common group is still running.
leakage currents and is particularly interesting before entering MCU low-power modes.
Return values
None:
HAL_ADC_MspDeInit
Function name
void HAL_ADC_MspDeInit (ADC_HandleTypeDef * hadc)
Function description
DeInitialize the ADC MSP.
Parameters
hadc: ADC handle
Return values
None:
Notes
All ADC instances use the same core clock at RCC level, disabling the core clock reset all ADC instances).
HAL_ADC_Start
Function name
HAL_StatusTypeDef HAL_ADC_Start (ADC_HandleTypeDef * hadc)
Function description
Enable ADC, start conversion of regular group.
Parameters
Return values
UM2217 - Rev 5
hadc: ADC handle
HAL: status
page 65/3786
Page 66
Notes
Interruptions enabled in this function: None.
Case of multimode enabled (when multimode feature is available): if ADC is Slave, ADC is enabled but
HAL_ADC_Stop
Function name
HAL_StatusTypeDef HAL_ADC_Stop (ADC_HandleTypeDef * hadc)
Function description
Stop ADC conversion of regular group (and injected channels in case of auto_injection mode), disable ADC peripheral.
Parameters
hadc: ADC handle
Return values
HAL: status.
Notes
: ADC peripheral disable is forcing stop of potential conversion on injected group. If injected group is under
UM2217
ADC Firmware driver API description
conversion is not started, if ADC is master, ADC is enabled and multimode conversion is started.
use, it should be preliminarily stopped using HAL_ADCEx_InjectedStop function.
HAL_ADC_PollForConversion
Function name
HAL_StatusTypeDef HAL_ADC_PollForConversion (ADC_HandleTypeDef * hadc, uint32_t Timeout)
Function description
Wait for regular group conversion to be completed.
Parameters
hadc: ADC handle
Timeout: Timeout value in millisecond.
Return values
HAL: status
Notes
ADC conversion flags EOS (end of sequence) and EOC (end of conversion) are cleared by this function,
This function cannot be used in a particular setup: ADC configured in DMA mode and polling for end of
HAL_ADC_PollForEvent
with an exception: if low power feature "LowPowerAutoWait" is enabled, flags are not cleared to not interfere with this feature until data register is read using function HAL_ADC_GetValue().
each conversion (ADC init parameter "EOCSelection" set to ADC_EOC_SINGLE_CONV). In this case, DMA resets the flag EOC and polling cannot be performed on each conversion. Nevertheless, polling can still be performed on the complete sequence (ADC init parameter "EOCSelection" set to ADC_EOC_SEQ_CONV).
Function name
HAL_StatusTypeDef HAL_ADC_PollForEvent (ADC_HandleTypeDef * hadc, uint32_t EventType, uint32_t Timeout)
Function description
Poll for ADC event.
UM2217 - Rev 5
page 66/3786
Page 67
Parameters
Return values
Notes
UM2217
ADC Firmware driver API description
hadc: ADC handle
EventType: the ADC event type. This parameter can be one of the following values:
ADC_EOSMP_EVENT ADC End of Sampling event
ADC_AWD1_EVENT ADC Analog watchdog 1 event (main analog watchdog, present on all STM32
devices)
ADC_AWD2_EVENT ADC Analog watchdog 2 event (additional analog watchdog, not present on all
STM32 families)
ADC_AWD3_EVENT ADC Analog watchdog 3 event (additional analog watchdog, not present on all
STM32 families)
ADC_OVR_EVENT ADC Overrun event
ADC_JQOVF_EVENT ADC Injected context queue overflow event
Timeout: Timeout value in millisecond.
HAL: status
The relevant flag is cleared if found to be set, except for ADC_FLAG_OVR. Indeed, the latter is reset only if hadc->Init.Overrun field is set to ADC_OVR_DATA_OVERWRITTEN. Otherwise, data register may be potentially overwritten by a new converted data as soon as OVR is cleared. To reset OVR flag once the preserved data is retrieved, the user can resort to macro __HAL_ADC_CLEAR_FLAG(hadc, ADC_FLAG_OVR);
HAL_ADC_Start_IT
Function name
HAL_StatusTypeDef HAL_ADC_Start_IT (ADC_HandleTypeDef * hadc)
Function description
Enable ADC, start conversion of regular group with interruption.
Parameters
hadc: ADC handle
Return values
HAL: status
Notes
Interruptions enabled in this function according to initialization setting : EOC (end of conversion), EOS (end
Case of multimode enabled (when multimode feature is available): HAL_ADC_Start_IT() must be called for
To guarantee a proper reset of all interruptions once all the needed conversions are obtained,
By default, HAL_ADC_Start_IT() does not enable the End Of Sampling interruption. If required (e.g. in case
of sequence), OVR overrun. Each of these interruptions has its dedicated callback function.
ADC Slave first, then for ADC Master. For ADC Slave, ADC is enabled only (conversion is not started). For ADC Master, ADC is enabled and multimode conversion is started.
HAL_ADC_Stop_IT() must be called to ensure a correct stop of the IT-based conversions.
of oversampling with trigger mode), the user must: 1. first clear the EOSMP flag if set with macro __HAL_ADC_CLEAR_FLAG(hadc, ADC_FLAG_EOSMP) 2. then enable the EOSMP interrupt with macro __HAL_ADC_ENABLE_IT(hadc, ADC_IT_EOSMP) before calling HAL_ADC_Start_IT().
Function name
UM2217 - Rev 5
HAL_ADC_Stop_IT
HAL_StatusTypeDef HAL_ADC_Stop_IT (ADC_HandleTypeDef * hadc)
page 67/3786
Page 68
Function description
Stop ADC conversion of regular group (and injected group in case of auto_injection mode), disable interrution of end-of-conversion, disable ADC peripheral.
Parameters
hadc: ADC handle
Return values
HAL: status.
HAL_ADC_Start_DMA
Function name
HAL_StatusTypeDef HAL_ADC_Start_DMA (ADC_HandleTypeDef * hadc, uint32_t * pData, uint32_t Length)
Function description
Enable ADC, start conversion of regular group and transfer result through DMA.
Parameters
hadc: ADC handle
pData: Destination Buffer address.
Length: Number of data to be transferred from ADC peripheral to memory
UM2217
ADC Firmware driver API description
Return values
HAL: status.
Notes
Interruptions enabled in this function: overrun (if applicable), DMA half transfer, DMA transfer complete.
Case of multimode enabled (when multimode feature is available): HAL_ADC_Start_DMA() is designed for
HAL_ADC_Stop_DMA
Function name
HAL_StatusTypeDef HAL_ADC_Stop_DMA (ADC_HandleTypeDef * hadc)
Function description
Stop ADC conversion of regular group (and injected group in case of auto_injection mode), disable ADC DMA transfer, disable ADC peripheral.
Parameters
hadc: ADC handle
Return values
HAL: status.
Notes
: ADC peripheral disable is forcing stop of potential conversion on ADC group injected. If ADC group
Case of multimode enabled (when multimode feature is available): HAL_ADC_Stop_DMA() function is
Each of these interruptions has its dedicated callback function.
single-ADC mode only. For multimode, the dedicated HAL_ADCEx_MultiModeStart_DMA() function must be used.
injected is under use, it should be preliminarily stopped using HAL_ADCEx_InjectedStop function.
dedicated to single-ADC mode only. For multimode, the dedicated HAL_ADCEx_MultiModeStop_DMA() API must be used.
UM2217 - Rev 5
page 68/3786
Page 69
HAL_ADC_GetValue
Function name
uint32_t HAL_ADC_GetValue (ADC_HandleTypeDef * hadc)
Function description
Get ADC regular group conversion result.
Parameters
hadc: ADC handle
Return values
ADC: group regular conversion data
Notes
Reading register DR automatically clears ADC flag EOC (ADC group regular end of unitary conversion).
This function does not clear ADC flag EOS (ADC group regular end of sequence conversion). Occurrence
UM2217
ADC Firmware driver API description
of flag EOS rising: If sequencer is composed of 1 rank, flag EOS is equivalent to flag EOC.If sequencer is composed of several ranks, during the scan sequence flag EOC only is raised, at the end of the scan sequence both flags EOC and EOS are raised. To clear this flag, either use function: in programming model IT: HAL_ADC_IRQHandler(), in programming model polling: HAL_ADC_PollForConversion() or __HAL_ADC_CLEAR_FLAG(&hadc, ADC_FLAG_EOS).
HAL_ADC_IRQHandler
Function name
void HAL_ADC_IRQHandler (ADC_HandleTypeDef * hadc)
Function description
Handle ADC interrupt request.
Parameters
hadc: ADC handle
Return values
None:
HAL_ADC_ConvCpltCallback
Function name
void HAL_ADC_ConvCpltCallback (ADC_HandleTypeDef * hadc)
Function description
Conversion complete callback in non-blocking mode.
Parameters
hadc: ADC handle
Return values
None:
Function name
UM2217 - Rev 5
HAL_ADC_ConvHalfCpltCallback
void HAL_ADC_ConvHalfCpltCallback (ADC_HandleTypeDef * hadc)
page 69/3786
Page 70
Function description
Conversion DMA half-transfer callback in non-blocking mode.
Parameters
hadc: ADC handle
Return values
None:
HAL_ADC_LevelOutOfWindowCallback
Function name
void HAL_ADC_LevelOutOfWindowCallback (ADC_HandleTypeDef * hadc)
Function description
Analog watchdog 1 callback in non-blocking mode.
Parameters
hadc: ADC handle
Return values
None:
UM2217
ADC Firmware driver API description
HAL_ADC_ErrorCallback
Function name
void HAL_ADC_ErrorCallback (ADC_HandleTypeDef * hadc)
Function description
ADC error callback in non-blocking mode (ADC conversion with interruption or transfer by DMA).
Parameters
hadc: ADC handle
Return values
None:
Notes
In case of error due to overrun when using ADC with DMA transfer (HAL ADC handle parameter
HAL_ADC_ConfigChannel
Function name
HAL_StatusTypeDef HAL_ADC_ConfigChannel (ADC_HandleTypeDef * hadc, ADC_ChannelConfTypeDef * sConfig)
"ErrorCode" to state "HAL_ADC_ERROR_OVR"): Reinitialize the DMA using function "HAL_ADC_Stop_DMA()".If needed, restart a new ADC conversion using function "HAL_ADC_Start_DMA()" (this function is also clearing overrun flag)
Function description
Configure a channel to be assigned to ADC group regular.
Parameters
hadc: ADC handle
sConfig: Structure of ADC channel assigned to ADC group regular.
UM2217 - Rev 5
page 70/3786
Page 71
Return values
HAL: status
Notes
In case of usage of internal measurement channels: Vbat/VrefInt/TempSensor. These internal paths can be
Possibility to update parameters on the fly: This function initializes channel into ADC group regular,
HAL_ADC_AnalogWDGConfig
Function name
HAL_StatusTypeDef HAL_ADC_AnalogWDGConfig (ADC_HandleTypeDef * hadc, ADC_AnalogWDGConfTypeDef * AnalogWDGConfig)
Function description
Configure the analog watchdog.
Parameters
hadc: ADC handle
AnalogWDGConfig: Structure of ADC analog watchdog configuration
UM2217
ADC Firmware driver API description
disabled using function HAL_ADC_DeInit().
following calls to this function can be used to reconfigure some parameters of structure "ADC_ChannelConfTypeDef" on the fly, without resetting the ADC. The setting of these parameters is conditioned to ADC state: Refer to comments of structure "ADC_ChannelConfTypeDef".
Return values
HAL: status
Notes
Possibility to update parameters on the fly: This function initializes the selected analog watchdog,
On this STM32 serie, analog watchdog thresholds cannot be modified while ADC conversion is on going.
HAL_ADC_GetState
Function name
uint32_t HAL_ADC_GetState (ADC_HandleTypeDef * hadc)
Function description
Return the ADC handle state.
Parameters
hadc: ADC handle
Return values
ADC: handle state (bitfield on 32 bits)
Notes
ADC state machine is managed by bitfields, ADC status must be compared with states bits. For example: "
successive calls to this function can be used to reconfigure some parameters of structure "ADC_AnalogWDGConfTypeDef" on the fly, without resetting the ADC. The setting of these parameters is conditioned to ADC state. For parameters constraints, see comments of structure "ADC_AnalogWDGConfTypeDef".
if ((HAL_ADC_GetState(hadc1) & HAL_ADC_STATE_REG_BUSY) != 0UL) " " if ((HAL_ADC_GetState(hadc1) & HAL_ADC_STATE_AWD1) != 0UL) "
UM2217 - Rev 5
page 71/3786
Page 72
HAL_ADC_GetError
Function name
uint32_t HAL_ADC_GetError (ADC_HandleTypeDef * hadc)
Function description
Return the ADC error code.
Parameters
hadc: ADC handle
Return values
ADC: error code (bitfield on 32 bits)
ADC_ConversionStop
Function name
HAL_StatusTypeDef ADC_ConversionStop (ADC_HandleTypeDef * hadc, uint32_t ConversionGroup)
Function description
Stop ADC conversion.
UM2217
ADC Firmware driver API description
Parameters
hadc: ADC handle
ConversionGroup: ADC group regular and/or injected. This parameter can be one of the following values:
Return values
HAL: status.
ADC_Enable
Function name
HAL_StatusTypeDef ADC_Enable (ADC_HandleTypeDef * hadc)
Function description
Enable the selected ADC.
Parameters
hadc: ADC handle
Return values
HAL: status.
Notes
Prerequisite condition to use this function: ADC must be disabled and voltage regulator must be enabled
ADC_REGULAR_GROUP ADC regular conversion type.
ADC_INJECTED_GROUP ADC injected conversion type.
ADC_REGULAR_INJECTED_GROUP ADC regular and injected conversion type.
(done into HAL_ADC_Init()).
Function name
UM2217 - Rev 5
ADC_Disable
HAL_StatusTypeDef ADC_Disable (ADC_HandleTypeDef * hadc)
page 72/3786
Page 73
Function description
Disable the selected ADC.
Parameters
hadc: ADC handle
Return values
HAL: status.
Notes
Prerequisite condition to use this function: ADC conversions must be stopped.
ADC_DMAConvCplt
Function name
void ADC_DMAConvCplt (DMA_HandleTypeDef * hdma)
Function description
DMA transfer complete callback.
Parameters
hdma: pointer to DMA handle.
UM2217
ADC Firmware driver API description
Return values
None:
ADC_DMAHalfConvCplt
Function name
void ADC_DMAHalfConvCplt (DMA_HandleTypeDef * hdma)
Function description
DMA half transfer complete callback.
Parameters
hdma: pointer to DMA handle.
Return values
None:
ADC_DMAError
Function name
void ADC_DMAError (DMA_HandleTypeDef * hdma)
Function description
DMA error callback.
Parameters
hdma: pointer to DMA handle.
Return values
UM2217 - Rev 5
None:
page 73/3786
Page 74
ADC_ConfigureBoostMode
Function name
void ADC_ConfigureBoostMode (ADC_HandleTypeDef * hadc)
Function description
Configure boost mode of selected ADC.
Parameters
hadc: ADC handle
Return values
None.:
Notes
Prerequisite condition to use this function: ADC conversions must be stopped.

8.3 ADC Firmware driver defines

The following section lists the various define and macros of the module.
UM2217
ADC Firmware driver defines

8.3.1 ADC

ADC
ADC Analog Watchdog filtering configuration
ADC3_AWD_FILTERING_NONE
ADC analog wathdog no filtering, one out-of-window sample is needed to raise flag or interrupt. Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_AWD_FILTERING_2SAMPLES
ADC analog wathdog 2 consecutives out-of-window samples are needed to raise flag or interrupt. Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_AWD_FILTERING_3SAMPLES
ADC analog wathdog 3 consecutives out-of-window samples are needed to raise flag or interrupt. Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_AWD_FILTERING_4SAMPLES
ADC analog wathdog 4 consecutives out-of-window samples are needed to raise flag or interrupt. Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_AWD_FILTERING_5SAMPLES
ADC analog wathdog 5 consecutives out-of-window samples are needed to raise flag or interrupt. Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_AWD_FILTERING_6SAMPLES
ADC analog wathdog 6 consecutives out-of-window samples are needed to raise flag or interrupt. Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_AWD_FILTERING_7SAMPLES
ADC analog wathdog 7 consecutives out-of-window samples are needed to raise flag or interrupt. Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_AWD_FILTERING_8SAMPLES
ADC analog wathdog 8 consecutives out-of-window samples are needed to raise flag or interrupt. Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC Analog Watchdog Mode
UM2217 - Rev 5
page 74/3786
Page 75
ADC_ANALOGWATCHDOG_NONE
No analog watchdog selected
ADC_ANALOGWATCHDOG_SINGLE_REG
Analog watchdog applied to a regular group single channel
ADC_ANALOGWATCHDOG_SINGLE_INJEC
Analog watchdog applied to an injected group single channel
ADC_ANALOGWATCHDOG_SINGLE_REGINJEC
Analog watchdog applied to a regular and injected groups single channel
ADC_ANALOGWATCHDOG_ALL_REG
Analog watchdog applied to regular group all channels
ADC_ANALOGWATCHDOG_ALL_INJEC
Analog watchdog applied to injected group all channels
ADC_ANALOGWATCHDOG_ALL_REGINJEC
Analog watchdog applied to regular and injected groups all channels
ADCx CFGR fields
UM2217
ADC Firmware driver defines
ADC_CFGR_FIELDS
ADCx CFGR sub fields
ADC_CFGR_FIELDS_2
ADC3_CFGR_FIELDS_2
ADC Conversion Data Management
ADC_CONVERSIONDATA_DR
Regular Conversion data stored in DR register only
ADC_CONVERSIONDATA_DFSDM
DFSDM mode selected
ADC_CONVERSIONDATA_DMA_ONESHOT
DMA one shot mode selected
ADC_CONVERSIONDATA_DMA_CIRCULAR
DMA circular mode selected
ADC sequencer end of unitary conversion or sequence conversions
ADC_EOC_SINGLE_CONV
End of unitary conversion flag
ADC_EOC_SEQ_CONV
End of sequence conversions flag
ADC Error Code
HAL_ADC_ERROR_NONE
No error
HAL_ADC_ERROR_INTERNAL
ADC peripheral internal error (problem of clocking, enable/disable, erroneous state, ...)
UM2217 - Rev 5
page 75/3786
Page 76
HAL_ADC_ERROR_OVR
Overrun error
HAL_ADC_ERROR_DMA
DMA transfer error
HAL_ADC_ERROR_JQOVF
Injected context queue overflow error
ADC Event type
ADC_EOSMP_EVENT
ADC End of Sampling event
ADC_AWD1_EVENT
ADC Analog watchdog 1 event (main analog watchdog, present on all STM32 series)
ADC_AWD2_EVENT
ADC Analog watchdog 2 event (additional analog watchdog, not present on all STM32 series)
ADC_AWD3_EVENT
ADC Analog watchdog 3 event (additional analog watchdog, not present on all STM32 series)
UM2217
ADC Firmware driver defines
ADC_OVR_EVENT
ADC overrun event
ADC_JQOVF_EVENT
ADC Injected Context Queue Overflow event
ADC Exported Constants
ADC_AWD_EVENT
ADC Analog watchdog 1 event: Naming for compatibility with other STM32 devices having only one analog watchdog
ADC flags definition
ADC_FLAG_RDY
ADC Ready flag
ADC_FLAG_EOSMP
ADC End of Sampling flag
ADC_FLAG_EOC
ADC End of Regular Conversion flag
ADC_FLAG_EOS
ADC End of Regular sequence of Conversions flag
ADC_FLAG_OVR
ADC overrun flag
ADC_FLAG_JEOC
ADC End of Injected Conversion flag
ADC_FLAG_JEOS
ADC End of Injected sequence of Conversions flag
UM2217 - Rev 5
page 76/3786
Page 77
ADC_FLAG_AWD1
ADC Analog watchdog 1 flag (main analog watchdog)
ADC_FLAG_AWD2
ADC Analog watchdog 2 flag (additional analog watchdog)
ADC_FLAG_AWD3
ADC Analog watchdog 3 flag (additional analog watchdog)
ADC_FLAG_JQOVF
ADC Injected Context Queue Overflow flag
Analog watchdog - Analog watchdog number
ADC_ANALOGWATCHDOG_1
ADC analog watchdog number 1
ADC_ANALOGWATCHDOG_2
ADC analog watchdog number 2
ADC_ANALOGWATCHDOG_3
ADC analog watchdog number 3
ADC instance - Channel number
UM2217
ADC Firmware driver defines
ADC_CHANNEL_0
ADC external channel (channel connected to GPIO pin) ADCx_IN0
ADC_CHANNEL_1
ADC external channel (channel connected to GPIO pin) ADCx_IN1
ADC_CHANNEL_2
ADC external channel (channel connected to GPIO pin) ADCx_IN2
ADC_CHANNEL_3
ADC external channel (channel connected to GPIO pin) ADCx_IN3
ADC_CHANNEL_4
ADC external channel (channel connected to GPIO pin) ADCx_IN4
ADC_CHANNEL_5
ADC external channel (channel connected to GPIO pin) ADCx_IN5
ADC_CHANNEL_6
ADC external channel (channel connected to GPIO pin) ADCx_IN6
ADC_CHANNEL_7
ADC external channel (channel connected to GPIO pin) ADCx_IN7
ADC_CHANNEL_8
ADC external channel (channel connected to GPIO pin) ADCx_IN8
ADC_CHANNEL_9
ADC external channel (channel connected to GPIO pin) ADCx_IN9
ADC_CHANNEL_10
ADC external channel (channel connected to GPIO pin) ADCx_IN10
UM2217 - Rev 5
page 77/3786
Page 78
ADC_CHANNEL_11
ADC external channel (channel connected to GPIO pin) ADCx_IN11
ADC_CHANNEL_12
ADC external channel (channel connected to GPIO pin) ADCx_IN12
ADC_CHANNEL_13
ADC external channel (channel connected to GPIO pin) ADCx_IN13
ADC_CHANNEL_14
ADC external channel (channel connected to GPIO pin) ADCx_IN14
ADC_CHANNEL_15
ADC external channel (channel connected to GPIO pin) ADCx_IN15
ADC_CHANNEL_16
ADC external channel (channel connected to GPIO pin) ADCx_IN16
ADC_CHANNEL_17
ADC external channel (channel connected to GPIO pin) ADCx_IN17
UM2217
ADC Firmware driver defines
ADC_CHANNEL_18
ADC external channel (channel connected to GPIO pin) ADCx_IN18
ADC_CHANNEL_19
ADC external channel (channel connected to GPIO pin) ADCx_IN19
ADC_CHANNEL_VREFINT
ADC internal channel connected to VrefInt: Internal voltage reference, channel specific to ADC3.
ADC_CHANNEL_TEMPSENSOR
ADC internal channel connected to Temperature sensor, channel specific to ADC3.
ADC_CHANNEL_VBAT
ADC internal channel connected to Vbat/4: Vbat voltage through a divider ladder of factor 1/4 to have Vbat always below Vdda, channel specific to ADC3.
ADC_CHANNEL_DAC1CH1_ADC2
ADC internal channel connected to DAC1 channel 1, channel specific to ADC2
ADC_CHANNEL_DAC1CH2_ADC2
ADC internal channel connected to DAC1 channel 2, channel specific to ADC2
Channel - Sampling time
ADC_SAMPLETIME_1CYCLE_5
Sampling time 1.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC1, ADC2
ADC_SAMPLETIME_2CYCLES_5
Sampling time 2.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC1, ADC2
ADC_SAMPLETIME_8CYCLES_5
Sampling time 8.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC1, ADC2
UM2217 - Rev 5
page 78/3786
Page 79
ADC_SAMPLETIME_16CYCLES_5
Sampling time 16.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC1, ADC2
ADC_SAMPLETIME_32CYCLES_5
Sampling time 32.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC1, ADC2
ADC_SAMPLETIME_64CYCLES_5
Sampling time 64.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC1, ADC2
ADC_SAMPLETIME_387CYCLES_5
Sampling time 387.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC1, ADC2
ADC_SAMPLETIME_810CYCLES_5
Sampling time 810.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC1, ADC2
ADC3_SAMPLETIME_2CYCLES_5
Sampling time 2.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC3
UM2217
ADC Firmware driver defines
ADC3_SAMPLETIME_6CYCLES_5
Sampling time 6.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC3
ADC3_SAMPLETIME_12CYCLES_5
Sampling time 12.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC3
ADC3_SAMPLETIME_24CYCLES_5
Sampling time 24.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC3
ADC3_SAMPLETIME_47CYCLES_5
Sampling time 47.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC3
ADC3_SAMPLETIME_92CYCLES_5
Sampling time 92.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC3
ADC3_SAMPLETIME_247CYCLES_5
Sampling time 247.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC3
ADC3_SAMPLETIME_640CYCLES_5
Sampling time 640.5 ADC clock cycles, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC3
ADC3_SAMPLETIME_3CYCLES_5
Sampling time 3.5 ADC clock cycles. If selected, this sampling time replaces all sampling time 2.5 ADC clock cycles. These 2 sampling times cannot be used simultaneously. On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC3
Channel - Single or differential ending
UM2217 - Rev 5
page 79/3786
Page 80
ADC_SINGLE_ENDED
ADC channel ending set to single ended (literal also used to set calibration mode)
ADC_DIFFERENTIAL_ENDED
ADC channel ending set to differential (literal also used to set calibration mode)
ADC common - Clock source
ADC_CLOCK_SYNC_PCLK_DIV1
ADC synchronous clock derived from AHB clock without prescaler
ADC_CLOCK_SYNC_PCLK_DIV2
ADC synchronous clock derived from AHB clock with prescaler division by 2
ADC_CLOCK_SYNC_PCLK_DIV4
ADC synchronous clock derived from AHB clock with prescaler division by 4
ADC_CLOCK_ASYNC_DIV1
ADC asynchronous clock without prescaler
ADC_CLOCK_ASYNC_DIV2
ADC asynchronous clock with prescaler division by 2
UM2217
ADC Firmware driver defines
ADC_CLOCK_ASYNC_DIV4
ADC asynchronous clock with prescaler division by 4
ADC_CLOCK_ASYNC_DIV6
ADC asynchronous clock with prescaler division by 6
ADC_CLOCK_ASYNC_DIV8
ADC asynchronous clock with prescaler division by 8
ADC_CLOCK_ASYNC_DIV10
ADC asynchronous clock with prescaler division by 10
ADC_CLOCK_ASYNC_DIV12
ADC asynchronous clock with prescaler division by 12
ADC_CLOCK_ASYNC_DIV16
ADC asynchronous clock with prescaler division by 16
ADC_CLOCK_ASYNC_DIV32
ADC asynchronous clock with prescaler division by 32
ADC_CLOCK_ASYNC_DIV64
ADC asynchronous clock with prescaler division by 64
ADC_CLOCK_ASYNC_DIV128
ADC asynchronous clock with prescaler division by 128
ADC_CLOCK_ASYNC_DIV256
ADC asynchronous clock with prescaler division by 256
ADC conversion data alignment
ADC3_DATAALIGN_RIGHT
ADC conversion data alignment: right aligned (alignment on data register LSB bit 0)
UM2217 - Rev 5
page 80/3786
Page 81
ADC3_DATAALIGN_LEFT
ADC conversion data alignment: left aligned (aligment on data register MSB bit 15)
ADC instance - Groups
ADC_REGULAR_GROUP
ADC group regular (available on all STM32 devices)
ADC_INJECTED_GROUP
ADC group injected (not available on all STM32 devices)
ADC_REGULAR_INJECTED_GROUP
ADC both groups regular and injected
Multimode - Mode
ADC_MODE_INDEPENDENT
ADC dual mode disabled (ADC independent mode)
ADC_DUALMODE_REGSIMULT
ADC dual mode enabled: group regular simultaneous
UM2217
ADC Firmware driver defines
ADC_DUALMODE_INTERL
ADC dual mode enabled: Combined group regular interleaved
ADC_DUALMODE_INJECSIMULT
ADC dual mode enabled: group injected simultaneous
ADC_DUALMODE_ALTERTRIG
ADC dual mode enabled: group injected alternate trigger. Works only with external triggers (not internal SW start)
ADC_DUALMODE_REGSIMULT_INJECSIMULT
ADC dual mode enabled: Combined group regular simultaneous + group injected simultaneous
ADC_DUALMODE_REGSIMULT_ALTERTRIG
ADC dual mode enabled: Combined group regular simultaneous + group injected alternate trigger
ADC_DUALMODE_REGINTERL_INJECSIMULT
ADC dual mode enabled: Combined group regular interleaved + group injected simultaneous
Multimode - Delay between two sampling phases
ADC_TWOSAMPLINGDELAY_1CYCLE
ADC multimode delay between two sampling phases: 1 ADC clock cycle
ADC_TWOSAMPLINGDELAY_2CYCLES
ADC multimode delay between two sampling phases: 2 ADC clock cycles
ADC_TWOSAMPLINGDELAY_3CYCLES
ADC multimode delay between two sampling phases: 3 ADC clock cycles
ADC_TWOSAMPLINGDELAY_4CYCLES
ADC multimode delay between two sampling phases: 4 ADC clock cycles
ADC_TWOSAMPLINGDELAY_5CYCLES
ADC multimode delay between two sampling phases: 5 ADC clock cycles
UM2217 - Rev 5
page 81/3786
Page 82
ADC_TWOSAMPLINGDELAY_6CYCLES
ADC multimode delay between two sampling phases: 6 ADC clock cycles
ADC_TWOSAMPLINGDELAY_7CYCLES
ADC multimode delay between two sampling phases: 7 ADC clock cycles
ADC_TWOSAMPLINGDELAY_8CYCLES
ADC multimode delay between two sampling phases: 8 ADC clock cycles
ADC_TWOSAMPLINGDELAY_9CYCLES
ADC multimode delay between two sampling phases: 9 ADC clock cycles
ADC instance - Offset number
ADC_OFFSET_NONE
ADC offset disabled: no offset correction for the selected ADC channel
ADC_OFFSET_1
ADC offset number 1: ADC channel and offset level to which the offset programmed will be applied (independently of channel mapped on ADC group regular or group injected)
ADC_OFFSET_2
ADC offset number 2: ADC channel and offset level to which the offset programmed will be applied (independently of channel mapped on ADC group regular or group injected)
UM2217
ADC Firmware driver defines
ADC_OFFSET_3
ADC offset number 3: ADC channel and offset level to which the offset programmed will be applied (independently of channel mapped on ADC group regular or group injected)
ADC_OFFSET_4
ADC offset number 4: ADC channel and offset level to which the offset programmed will be applied (independently of channel mapped on ADC group regular or group injected)
Oversampling - Discontinuous mode
ADC_TRIGGEREDMODE_SINGLE_TRIGGER
ADC oversampling discontinuous mode: continuous mode (all conversions of oversampling ratio are done from 1 trigger)
ADC_TRIGGEREDMODE_MULTI_TRIGGER
ADC oversampling discontinuous mode: discontinuous mode (each conversion of oversampling ratio needs a trigger)
Oversampling - Ratio
ADC3_OVERSAMPLING_RATIO_2
ADC oversampling ratio of 2 (2 ADC conversions are performed, sum of these conversions data is computed to result as the ADC oversampling conversion data (before potential shift). Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_OVERSAMPLING_RATIO_4
ADC oversampling ratio of 4 (4 ADC conversions are performed, sum of these conversions data is computed to result as the ADC oversampling conversion data (before potential shift). Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_OVERSAMPLING_RATIO_8
ADC oversampling ratio of 8 (8 ADC conversions are performed, sum of these conversions data is computed to result as the ADC oversampling conversion data (before potential shift). Applicable for ADC3 on devices STM32H72xx and STM32H73xx
UM2217 - Rev 5
page 82/3786
Page 83
ADC3_OVERSAMPLING_RATIO_16
ADC oversampling ratio of 16 (16 ADC conversions are performed, sum of these conversions data is computed to result as the ADC oversampling conversion data (before potential shift). Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_OVERSAMPLING_RATIO_32
ADC oversampling ratio of 32 (32 ADC conversions are performed, sum of these conversions data is computed to result as the ADC oversampling conversion data (before potential shift). Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_OVERSAMPLING_RATIO_64
ADC oversampling ratio of 64 (64 ADC conversions are performed, sum of these conversions data is computed to result as the ADC oversampling conversion data (before potential shift). Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_OVERSAMPLING_RATIO_128
ADC oversampling ratio of 128 (128 ADC conversions are performed, sum of these conversions data is computed to result as the ADC oversampling conversion data (before potential shift). Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_OVERSAMPLING_RATIO_256
ADC oversampling ratio of 256 (256 ADC conversions are performed, sum of these conversions data is computed to result as the ADC oversampling conversion data (before potential shift). Applicable for ADC3 on devices STM32H72xx and STM32H73xx
UM2217
ADC Firmware driver defines
ADC3_OVERSAMPLING_RATIO_512
ADC oversampling ratio of 256 (256 ADC conversions are performed, sum of these conversions data is computed to result as the ADC oversampling conversion data (before potential shift). Applicable for ADC3 on devices STM32H72xx and STM32H73xx
ADC3_OVERSAMPLING_RATIO_1024
ADC oversampling ratio of 256 (256 ADC conversions are performed, sum of these conversions data is computed to result as the ADC oversampling conversion data (before potential shift). Applicable for ADC3 on devices STM32H72xx and STM32H73xx
Oversampling - Oversampling scope for ADC group regular
ADC_REGOVERSAMPLING_CONTINUED_MODE
Oversampling buffer maintained during injection sequence
ADC_REGOVERSAMPLING_RESUMED_MODE
Oversampling buffer zeroed during injection sequence
Oversampling - Data shift
ADC_RIGHTBITSHIFT_NONE
ADC oversampling no shift (sum of the ADC conversions data is not divided to result as the ADC oversampling conversion data)
ADC_RIGHTBITSHIFT_1
ADC oversampling shift of 1 (sum of the ADC conversions data is divided by 2 to result as the ADC oversampling conversion data)
ADC_RIGHTBITSHIFT_2
ADC oversampling shift of 2 (sum of the ADC conversions data is divided by 4 to result as the ADC oversampling conversion data)
UM2217 - Rev 5
page 83/3786
Page 84
ADC_RIGHTBITSHIFT_3
ADC oversampling shift of 3 (sum of the ADC conversions data is divided by 8 to result as the ADC oversampling conversion data)
ADC_RIGHTBITSHIFT_4
ADC oversampling shift of 4 (sum of the ADC conversions data is divided by 16 to result as the ADC oversampling conversion data)
ADC_RIGHTBITSHIFT_5
ADC oversampling shift of 5 (sum of the ADC conversions data is divided by 32 to result as the ADC oversampling conversion data)
ADC_RIGHTBITSHIFT_6
ADC oversampling shift of 6 (sum of the ADC conversions data is divided by 64 to result as the ADC oversampling conversion data)
ADC_RIGHTBITSHIFT_7
ADC oversampling shift of 7 (sum of the ADC conversions data is divided by 128 to result as the ADC oversampling conversion data)
ADC_RIGHTBITSHIFT_8
ADC oversampling shift of 8 (sum of the ADC conversions data is divided by 256 to result as the ADC oversampling conversion data)
UM2217
ADC Firmware driver defines
ADC_RIGHTBITSHIFT_9
ADC oversampling shift of 9 (sum of the ADC conversions data is divided by 512 to result as the ADC oversampling conversion data)
ADC_RIGHTBITSHIFT_10
ADC oversampling shift of 10 (sum of the ADC conversions data is divided by 1024 to result as the ADC oversampling conversion data)
ADC_RIGHTBITSHIFT_11
ADC oversampling shift of 11 (sum of the ADC conversions data is divided by 2048 to result as the ADC oversampling conversion data)
ADC group regular - DFSDM transfer of ADC conversion data
ADC_DFSDM_MODE_DISABLE
ADC conversions are not transferred by DFSDM.
ADC_DFSDM_MODE_ENABLE
ADC conversion data are transfered to DFSDM for post processing. The ADC conversion data format must be 16-bit signed and right aligned, refer to reference manual. DFSDM transfer cannot be used if DMA transfer is enabled.
ADC group regular - Overrun behavior on conversion data
ADC_OVR_DATA_PRESERVED
ADC group regular behavior in case of overrun: data preserved
ADC_OVR_DATA_OVERWRITTEN
ADC group regular behavior in case of overrun: data overwritten
ADC group regular - Sequencer ranks
ADC_REGULAR_RANK_1
ADC group regular sequencer rank 1
UM2217 - Rev 5
page 84/3786
Page 85
ADC_REGULAR_RANK_2
ADC group regular sequencer rank 2
ADC_REGULAR_RANK_3
ADC group regular sequencer rank 3
ADC_REGULAR_RANK_4
ADC group regular sequencer rank 4
ADC_REGULAR_RANK_5
ADC group regular sequencer rank 5
ADC_REGULAR_RANK_6
ADC group regular sequencer rank 6
ADC_REGULAR_RANK_7
ADC group regular sequencer rank 7
ADC_REGULAR_RANK_8
ADC group regular sequencer rank 8
UM2217
ADC Firmware driver defines
ADC_REGULAR_RANK_9
ADC group regular sequencer rank 9
ADC_REGULAR_RANK_10
ADC group regular sequencer rank 10
ADC_REGULAR_RANK_11
ADC group regular sequencer rank 11
ADC_REGULAR_RANK_12
ADC group regular sequencer rank 12
ADC_REGULAR_RANK_13
ADC group regular sequencer rank 13
ADC_REGULAR_RANK_14
ADC group regular sequencer rank 14
ADC_REGULAR_RANK_15
ADC group regular sequencer rank 15
ADC_REGULAR_RANK_16
ADC group regular sequencer rank 16
ADC instance - Resolution
ADC_RESOLUTION_16B
ADC resolution 16 bits, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC1, ADC2
ADC_RESOLUTION_14B
ADC resolution 14 bits, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC1, ADC2
ADC_RESOLUTION_12B
ADC resolution 12 bits
UM2217 - Rev 5
page 85/3786
Page 86
ADC_RESOLUTION_10B
ADC resolution 10 bits
ADC_RESOLUTION_8B
ADC resolution 8 bits
ADC_RESOLUTION_6B
ADC resolution 6 bits, On devices STM32H72xx and STM32H73xx, parameter available only on ADC instance: ADC3
HAL ADC macro to manage HAL ADC handle, IT and flags.
__HAL_ADC_RESET_HANDLE_STATE
Description:
Reset ADC handle state.
Parameters:
__HANDLE__: ADC handle
Return value:
None
UM2217
ADC Firmware driver defines
__HAL_ADC_ENABLE_IT
Description:
Enable ADC interrupt.
Parameters:
__HANDLE__: ADC handle
__INTERRUPT__: ADC Interrupt This parameter can be one of the following values:
ADC_IT_RDY ADC Ready interrupt source
ADC_IT_EOSMP ADC End of Sampling interrupt source
ADC_IT_EOC ADC End of Regular Conversion interrupt source
ADC_IT_EOS ADC End of Regular sequence of Conversions interrupt source
ADC_IT_OVR ADC overrun interrupt source
ADC_IT_JEOC ADC End of Injected Conversion interrupt source
ADC_IT_JEOS ADC End of Injected sequence of Conversions interrupt source
ADC_IT_AWD1 ADC Analog watchdog 1 interrupt source (main analog watchdog)
ADC_IT_AWD2 ADC Analog watchdog 2 interrupt source (additional analog watchdog)
ADC_IT_AWD3 ADC Analog watchdog 3 interrupt source (additional analog watchdog)
ADC_IT_JQOVF ADC Injected Context Queue Overflow interrupt source.
Return value:
None
UM2217 - Rev 5
page 86/3786
Page 87
__HAL_ADC_DISABLE_IT
Description:
Disable ADC interrupt.
Parameters:
__HANDLE__: ADC handle
__INTERRUPT__: ADC Interrupt This parameter can be one of the following values:
ADC_IT_RDY ADC Ready interrupt source
ADC_IT_EOSMP ADC End of Sampling interrupt source
ADC_IT_EOC ADC End of Regular Conversion interrupt source
ADC_IT_EOS ADC End of Regular sequence of Conversions interrupt source
ADC_IT_OVR ADC overrun interrupt source
ADC_IT_JEOC ADC End of Injected Conversion interrupt source
ADC_IT_JEOS ADC End of Injected sequence of Conversions interrupt source
ADC_IT_AWD1 ADC Analog watchdog 1 interrupt source (main analog watchdog)
ADC_IT_AWD2 ADC Analog watchdog 2 interrupt source (additional analog watchdog)
ADC_IT_AWD3 ADC Analog watchdog 3 interrupt source (additional analog watchdog)
ADC_IT_JQOVF ADC Injected Context Queue Overflow interrupt source.
Return value:
None
UM2217
ADC Firmware driver defines
__HAL_ADC_GET_IT_SOURCE
Description:
Checks if the specified ADC interrupt source is enabled or disabled.
Parameters:
__HANDLE__: ADC handle
__INTERRUPT__: ADC interrupt source to check This parameter can be one of the following values:
ADC_IT_RDY ADC Ready interrupt source
ADC_IT_EOSMP ADC End of Sampling interrupt source
ADC_IT_EOC ADC End of Regular Conversion interrupt source
ADC_IT_EOS ADC End of Regular sequence of Conversions interrupt source
ADC_IT_OVR ADC overrun interrupt source
ADC_IT_JEOC ADC End of Injected Conversion interrupt source
ADC_IT_JEOS ADC End of Injected sequence of Conversions interrupt source
ADC_IT_AWD1 ADC Analog watchdog 1 interrupt source (main analog watchdog)
ADC_IT_AWD2 ADC Analog watchdog 2 interrupt source (additional analog watchdog)
ADC_IT_AWD3 ADC Analog watchdog 3 interrupt source (additional analog watchdog)
ADC_IT_JQOVF ADC Injected Context Queue Overflow interrupt source.
Return value:
State: of interruption (SET or RESET)
UM2217 - Rev 5
page 87/3786
Page 88
__HAL_ADC_GET_FLAG
Description:
Check whether the specified ADC flag is set or not.
Parameters:
__HANDLE__: ADC handle
__FLAG__: ADC flag This parameter can be one of the following values:
ADC_FLAG_RDY ADC Ready flag
ADC_FLAG_EOSMP ADC End of Sampling flag
ADC_FLAG_EOC ADC End of Regular Conversion flag
ADC_FLAG_EOS ADC End of Regular sequence of Conversions flag
ADC_FLAG_OVR ADC overrun flag
ADC_FLAG_JEOC ADC End of Injected Conversion flag
ADC_FLAG_JEOS ADC End of Injected sequence of Conversions flag
ADC_FLAG_AWD1 ADC Analog watchdog 1 flag (main analog watchdog)
ADC_FLAG_AWD2 ADC Analog watchdog 2 flag (additional analog watchdog)
ADC_FLAG_AWD3 ADC Analog watchdog 3 flag (additional analog watchdog)
ADC_FLAG_JQOVF ADC Injected Context Queue Overflow flag.
Return value:
State: of flag (TRUE or FALSE).
UM2217
ADC Firmware driver defines
__HAL_ADC_CLEAR_FLAG
Description:
Clear the specified ADC flag.
Parameters:
__HANDLE__: ADC handle
__FLAG__: ADC flag This parameter can be one of the following values:
ADC_FLAG_RDY ADC Ready flag
ADC_FLAG_EOSMP ADC End of Sampling flag
ADC_FLAG_EOC ADC End of Regular Conversion flag
ADC_FLAG_EOS ADC End of Regular sequence of Conversions flag
ADC_FLAG_OVR ADC overrun flag
ADC_FLAG_JEOC ADC End of Injected Conversion flag
ADC_FLAG_JEOS ADC End of Injected sequence of Conversions flag
ADC_FLAG_AWD1 ADC Analog watchdog 1 flag (main analog watchdog)
ADC_FLAG_AWD2 ADC Analog watchdog 2 flag (additional analog watchdog)
ADC_FLAG_AWD3 ADC Analog watchdog 3 flag (additional analog watchdog)
ADC_FLAG_JQOVF ADC Injected Context Queue Overflow flag.
Return value:
None
HAL ADC helper macro
UM2217 - Rev 5
page 88/3786
Page 89
__HAL_ADC_CHANNEL_TO_DECIMAL_NB
Description:
Helper macro to get ADC channel number in decimal format from literals ADC_CHANNEL_x.
Parameters:
__CHANNEL__: This parameter can be one of the following values:
ADC_CHANNEL_0 (3)
ADC_CHANNEL_1 (3)
ADC_CHANNEL_2 (3)
ADC_CHANNEL_3 (3)
ADC_CHANNEL_4 (3)
ADC_CHANNEL_5 (3)
ADC_CHANNEL_6
ADC_CHANNEL_7
ADC_CHANNEL_8
ADC_CHANNEL_9
ADC_CHANNEL_10
ADC_CHANNEL_11
ADC_CHANNEL_12
ADC_CHANNEL_13
ADC_CHANNEL_14
ADC_CHANNEL_15
ADC_CHANNEL_16
ADC_CHANNEL_17
ADC_CHANNEL_18
ADC_CHANNEL_VREFINT (1)
ADC_CHANNEL_TEMPSENSOR (1)
ADC_CHANNEL_VBAT (1)
ADC_CHANNEL_DAC1CH1_ADC2 (2)
ADC_CHANNEL_DAC1CH2_ADC2 (2)
Return value:
Value: between Min_Data=0 and Max_Data=18
Notes:
Example: __HAL_ADC_CHANNEL_TO_DECIMAL_NB(ADC_CHANNEL_4) will return decimal number "4". The input can be a value from functions where a channel number is returned, either defined with number or with bitfield (only one bit must be set).
UM2217
ADC Firmware driver defines
UM2217 - Rev 5
page 89/3786
Page 90
__HAL_ADC_DECIMAL_NB_TO_CHANNEL
Description:
Helper macro to get ADC channel in literal format ADC_CHANNEL_x from number in decimal format.
Parameters:
__DECIMAL_NB__: Value between Min_Data=0 and Max_Data=18
Return value:
Returned: value can be one of the following values:
ADC_CHANNEL_0 (3)
ADC_CHANNEL_1 (3)
ADC_CHANNEL_2 (3)
ADC_CHANNEL_3 (3)
ADC_CHANNEL_4 (3)
ADC_CHANNEL_5 (3)
ADC_CHANNEL_6
ADC_CHANNEL_7
ADC_CHANNEL_8
ADC_CHANNEL_9
ADC_CHANNEL_10
ADC_CHANNEL_11
ADC_CHANNEL_12
ADC_CHANNEL_13
ADC_CHANNEL_14
ADC_CHANNEL_15
ADC_CHANNEL_16
ADC_CHANNEL_17
ADC_CHANNEL_18
ADC_CHANNEL_VREFINT (1)
ADC_CHANNEL_TEMPSENSOR (1)
ADC_CHANNEL_VBAT (1)
ADC_CHANNEL_DAC1CH1_ADC2 (2)
ADC_CHANNEL_DAC1CH2_ADC2 (2)
Notes:
Example: __HAL_ADC_DECIMAL_NB_TO_CHANNEL(4) will return a data equivalent to "ADC_CHANNEL_4".
UM2217
ADC Firmware driver defines
UM2217 - Rev 5
page 90/3786
Page 91
__HAL_ADC_IS_CHANNEL_INTERNAL
Description:
Helper macro to determine whether the selected channel corresponds to literal definitions of driver.
Parameters:
__CHANNEL__: This parameter can be one of the following values:
ADC_CHANNEL_0 (3)
ADC_CHANNEL_1 (3)
ADC_CHANNEL_2 (3)
ADC_CHANNEL_3 (3)
ADC_CHANNEL_4 (3)
ADC_CHANNEL_5 (3)
ADC_CHANNEL_6
ADC_CHANNEL_7
ADC_CHANNEL_8
ADC_CHANNEL_9
ADC_CHANNEL_10
ADC_CHANNEL_11
ADC_CHANNEL_12
ADC_CHANNEL_13
ADC_CHANNEL_14
ADC_CHANNEL_15
ADC_CHANNEL_16
ADC_CHANNEL_17
ADC_CHANNEL_18
ADC_CHANNEL_VREFINT (1)
ADC_CHANNEL_TEMPSENSOR (1)
ADC_CHANNEL_VBAT (1)
ADC_CHANNEL_DAC1CH1_ADC2 (2)
ADC_CHANNEL_DAC1CH2_ADC2 (2)
Return value:
Value: "0" if the channel corresponds to a parameter definition of a ADC external channel (channel connected to a GPIO pin). Value "1" if the channel corresponds to a parameter definition of a ADC internal channel.
Notes:
The different literal definitions of ADC channels are: ADC internal channel: ADC_CHANNEL_VREFINT, ADC_CHANNEL_TEMPSENSOR, ...ADC external channel (channel connected to a GPIO pin): ADC_CHANNEL_1, ADC_CHANNEL_2, ... The channel parameter must be a value defined from literal definition of a ADC internal channel (ADC_CHANNEL_VREFINT, ADC_CHANNEL_TEMPSENSOR, ...), ADC external channel (ADC_CHANNEL_1, ADC_CHANNEL_2, ...), must not be a value from functions where a channel number is returned from ADC registers, because internal and external channels share the same channel number in ADC registers. The differentiation is made only with parameters definitions of driver.
UM2217
ADC Firmware driver defines
UM2217 - Rev 5
page 91/3786
Page 92
__HAL_ADC_CHANNEL_INTERNAL_TO_EXTERNAL
Description:
Helper macro to convert a channel defined from parameter definition of a ADC internal channel (ADC_CHANNEL_VREFINT, ADC_CHANNEL_TEMPSENSOR, ...), to its equivalent parameter definition of a ADC external channel (ADC_CHANNEL_1, ADC_CHANNEL_2, ...).
Parameters:
__CHANNEL__: This parameter can be one of the following values:
ADC_CHANNEL_0 (3)
ADC_CHANNEL_1 (3)
ADC_CHANNEL_2 (3)
ADC_CHANNEL_3 (3)
ADC_CHANNEL_4 (3)
ADC_CHANNEL_5 (3)
ADC_CHANNEL_6
ADC_CHANNEL_7
ADC_CHANNEL_8
ADC_CHANNEL_9
ADC_CHANNEL_10
ADC_CHANNEL_11
ADC_CHANNEL_12
ADC_CHANNEL_13
ADC_CHANNEL_14
ADC_CHANNEL_15
ADC_CHANNEL_16
ADC_CHANNEL_17
ADC_CHANNEL_18
ADC_CHANNEL_VREFINT (1)
ADC_CHANNEL_TEMPSENSOR (1)
ADC_CHANNEL_VBAT (1)
ADC_CHANNEL_DAC1CH1_ADC2 (2)
ADC_CHANNEL_DAC1CH2_ADC2 (2)
Return value:
Returned: value can be one of the following values:
ADC_CHANNEL_0
ADC_CHANNEL_1
ADC_CHANNEL_2
ADC_CHANNEL_3
ADC_CHANNEL_4
ADC_CHANNEL_5
ADC_CHANNEL_6
ADC_CHANNEL_7
ADC_CHANNEL_8
ADC_CHANNEL_9
ADC_CHANNEL_10
ADC_CHANNEL_11
ADC_CHANNEL_12
ADC_CHANNEL_13
ADC_CHANNEL_14
ADC_CHANNEL_15
UM2217
ADC Firmware driver defines
UM2217 - Rev 5
page 92/3786
Page 93
ADC_CHANNEL_16
ADC_CHANNEL_17
ADC_CHANNEL_18
Notes:
The channel parameter can be, additionally to a value defined from parameter definition of a ADC internal channel (ADC_CHANNEL_VREFINT, ADC_CHANNEL_TEMPSENSOR, ...), a value defined from parameter definition of ADC external channel (ADC_CHANNEL_1, ADC_CHANNEL_2, ...) or a value from functions where a channel number is returned from ADC registers.
__HAL_ADC_IS_CHANNEL_INTERNAL_AVAILABLE
Description:
Helper macro to determine whether the internal channel selected is available on the ADC instance selected.
Parameters:
__ADC_INSTANCE__: ADC instance
__CHANNEL__: This parameter can be one of the following values:
ADC_CHANNEL_VREFINT (1)
ADC_CHANNEL_TEMPSENSOR (1)
ADC_CHANNEL_VBAT (1)
ADC_CHANNEL_DAC1CH1_ADC2 (2)
ADC_CHANNEL_DAC1CH2_ADC2 (2)
Return value:
Value: "0" if the internal channel selected is not available on the ADC instance selected. Value "1" if the internal channel selected is available on the ADC instance selected.
Notes:
The channel parameter must be a value defined from parameter definition of a ADC internal channel (ADC_CHANNEL_VREFINT, ADC_CHANNEL_TEMPSENSOR, ...), must not be a value defined from parameter definition of ADC external channel (ADC_CHANNEL_1, ADC_CHANNEL_2, ...) or a value from functions where a channel number is returned from ADC registers, because internal and external channels share the same channel number in ADC registers. The differentiation is made only with parameters definitions of driver.
UM2217
ADC Firmware driver defines
__HAL_ADC_MULTI_CONV_DATA_MASTER_SLAVE
Description:
Helper macro to get the ADC multimode conversion data of ADC master or ADC slave from raw value with both ADC conversion data concatenated.
Parameters:
__ADC_MULTI_MASTER_SLAVE__: This parameter can be one of the following values:
LL_ADC_MULTI_MASTER
LL_ADC_MULTI_SLAVE
__ADC_MULTI_CONV_DATA__: Value between Min_Data=0x000 and Max_Data=0xFFF
Return value:
Value: between Min_Data=0x000 and Max_Data=0xFFF
Notes:
This macro is intended to be used when multimode transfer by DMA is enabled: refer to function LL_ADC_SetMultiDMATransfer(). In this case the transferred data need to processed with this macro to separate the conversion data of ADC master and ADC slave.
UM2217 - Rev 5
page 93/3786
Page 94
__HAL_ADC_COMMON_INSTANCE
Description:
Helper macro to select the ADC common instance to which is belonging the selected ADC instance.
Parameters:
__ADCx__: ADC instance
Return value:
ADC: common register instance
Notes:
ADC common register instance can be used for: Set parameters common to several ADC instancesMultimode (for devices with several ADC instances) Refer to functions having argument "ADCxy_COMMON" as parameter.
__HAL_ADC_IS_ENABLED_ALL_COMMON_INSTANCE
Description:
Helper macro to check if all ADC instances sharing the same ADC common instance are disabled.
Parameters:
__ADCXY_COMMON__: ADC common instance (can be set directly from CMSIS definition or by using helper macro __LL_ADC_COMMON_INSTANCE() )
Return value:
Value: "0" if all ADC instances sharing the same ADC common instance are disabled. Value "1" if at least one ADC instance sharing the same ADC common instance is enabled.
Notes:
This check is required by functions with setting conditioned to ADC state: All ADC instances of the ADC common group must be disabled. Refer to functions having argument "ADCxy_COMMON" as parameter. On devices with only 1 ADC common instance, parameter of this macro is useless and can be ignored (parameter kept for compatibility with devices featuring several ADC common instances).
UM2217
ADC Firmware driver defines
__HAL_ADC_DIGITAL_SCALE
Description:
Helper macro to define the ADC conversion data full-scale digital value corresponding to the selected ADC resolution.
Parameters:
__ADC_RESOLUTION__: This parameter can be one of the following values:
ADC_RESOLUTION_16B
ADC_RESOLUTION_14B
ADC_RESOLUTION_12B
ADC_RESOLUTION_10B
ADC_RESOLUTION_8B
Return value:
ADC: conversion data full-scale digital value
Notes:
ADC conversion data full-scale corresponds to voltage range determined by analog voltage references Vref + and Vref- (refer to reference manual).
UM2217 - Rev 5
page 94/3786
Page 95
__HAL_ADC_CONVERT_DATA_RESOLUTION
Description:
Helper macro to convert the ADC conversion data from a resolution to another resolution.
Parameters:
__DATA__: ADC conversion data to be converted
__ADC_RESOLUTION_CURRENT__: Resolution of to the data to be converted This parameter can be one of the following values:
ADC_RESOLUTION_16B
ADC_RESOLUTION_14B
ADC_RESOLUTION_12B
ADC_RESOLUTION_10B
ADC_RESOLUTION_8B
__ADC_RESOLUTION_TARGET__: Resolution of the data after conversion This parameter can be one of the following values:
ADC_RESOLUTION_16B
ADC_RESOLUTION_14B
ADC_RESOLUTION_12B
ADC_RESOLUTION_10B
ADC_RESOLUTION_8B
Return value:
ADC: conversion data to the requested resolution
UM2217
ADC Firmware driver defines
__HAL_ADC_CALC_DATA_TO_VOLTAGE
Description:
Helper macro to calculate the voltage (unit: mVolt) corresponding to a ADC conversion data (unit: digital value).
Parameters:
__VREFANALOG_VOLTAGE__: Analog reference voltage (unit: mV)
__ADC_DATA__: ADC conversion data (resolution 12 bits) (unit: digital value).
__ADC_RESOLUTION__: This parameter can be one of the following values:
ADC_RESOLUTION_16B
ADC_RESOLUTION_14B
ADC_RESOLUTION_12B
ADC_RESOLUTION_10B
ADC_RESOLUTION_8B
Return value:
ADC: conversion data equivalent voltage value (unit: mVolt)
Notes:
Analog reference voltage (Vref+) must be either known from user board environment or can be calculated using ADC measurement and ADC helper macro __LL_ADC_CALC_VREFANALOG_VOLTAGE().
UM2217 - Rev 5
page 95/3786
Page 96
__HAL_ADC_CALC_VREFANALOG_VOLTAGE
Description:
Helper macro to calculate analog reference voltage (Vref+) (unit: mVolt) from ADC conversion data of internal voltage reference VrefInt.
Parameters:
__VREFINT_ADC_DATA__: ADC conversion data (resolution 12 bits) of internal voltage reference VrefInt (unit: digital value).
__ADC_RESOLUTION__: This parameter can be one of the following values:
ADC_RESOLUTION_16B
ADC_RESOLUTION_14B
ADC_RESOLUTION_12B
ADC_RESOLUTION_10B
ADC_RESOLUTION_8B
Return value:
Analog: reference voltage (unit: mV)
Notes:
Computation is using VrefInt calibration value stored in system memory for each device during production. This voltage depends on user board environment: voltage level connected to pin Vref+. On devices with small package, the pin Vref+ is not present and internally bonded to pin Vdda. On this STM32 serie, calibration data of internal voltage reference VrefInt corresponds to a resolution of 12 bits, this is the recommended ADC resolution to convert voltage of internal voltage reference VrefInt. Otherwise, this macro performs the processing to scale ADC conversion data to 12 bits.
UM2217
ADC Firmware driver defines
UM2217 - Rev 5
page 96/3786
Page 97
__HAL_ADC_CALC_TEMPERATURE
Description:
Helper macro to calculate the temperature (unit: degree Celsius) from ADC conversion data of internal temperature sensor.
Parameters:
__VREFANALOG_VOLTAGE__: Analog reference voltage (unit: mV)
__TEMPSENSOR_ADC_DATA__: ADC conversion data of internal temperature sensor (unit: digital value).
__ADC_RESOLUTION__: ADC resolution at which internal temperature sensor voltage has been measured. This parameter can be one of the following values:
ADC_RESOLUTION_16B
ADC_RESOLUTION_14B
ADC_RESOLUTION_12B
ADC_RESOLUTION_10B
ADC_RESOLUTION_8B
Return value:
Temperature: (unit: degree Celsius)
Notes:
Computation is using temperature sensor calibration values stored in system memory for each device during production. Calculation formula: Temperature = ((TS_ADC_DATA - TS_CAL1) * (TS_CAL2_TEMP ­TS_CAL1_TEMP)) / (TS_CAL2 - TS_CAL1) + TS_CAL1_TEMP with TS_ADC_DATA = temperature sensor raw data measured by ADC Avg_Slope = (TS_CAL2 - TS_CAL1) / (TS_CAL2_TEMP - TS_CAL1_TEMP) TS_CAL1 = equivalent TS_ADC_DATA at temperature TEMP_DEGC_CAL1 (calibrated in factory) TS_CAL2 = equivalent TS_ADC_DATA at temperature TEMP_DEGC_CAL2 (calibrated in factory) Caution: Calculation relevancy under reserve that calibration parameters are correct (address and data). To calculate temperature using temperature sensor datasheet typical values (generic values less, therefore less accurate than calibrated values), use helper macro __LL_ADC_CALC_TEMPERATURE_TYP_PARAMS(). As calculation input, the analog reference voltage (Vref+) must be defined as it impacts the ADC LSB equivalent voltage. Analog reference voltage (Vref+) must be either known from user board environment or can be calculated using ADC measurement and ADC helper macro __LL_ADC_CALC_VREFANALOG_VOLTAGE(). On this STM32 serie, calibration data of temperature sensor corresponds to a resolution of 12 bits, this is the recommended ADC resolution to convert voltage of temperature sensor. Otherwise, this macro performs the processing to scale ADC conversion data to 12 bits.
UM2217
ADC Firmware driver defines
UM2217 - Rev 5
page 97/3786
Page 98
__HAL_ADC_CALC_TEMPERATURE_TYP_PARAMS
Description:
Helper macro to calculate the temperature (unit: degree Celsius) from ADC conversion data of internal temperature sensor.
Parameters:
__TEMPSENSOR_TYP_AVGSLOPE__: Device datasheet data: Temperature sensor slope typical value (unit: uV/DegCelsius). On STM32H7, refer to device datasheet parameter "Avg_Slope".
__TEMPSENSOR_TYP_CALX_V__: Device datasheet data: Temperature sensor voltage typical value (at temperature and Vref+ defined in parameters below) (unit: mV). On STM32H7, refer to device datasheet parameter "V30" (corresponding to TS_CAL1).
__TEMPSENSOR_CALX_TEMP__: Device datasheet data: Temperature at which temperature sensor voltage (see parameter above) is corresponding (unit: mV)
__VREFANALOG_VOLTAGE__: Analog voltage reference (Vref+) voltage (unit: mV)
__TEMPSENSOR_ADC_DATA__: ADC conversion data of internal temperature sensor (unit: digital value).
__ADC_RESOLUTION__: ADC resolution at which internal temperature sensor voltage has been measured. This parameter can be one of the following values:
ADC_RESOLUTION_16B
ADC_RESOLUTION_14B
ADC_RESOLUTION_12B
ADC_RESOLUTION_10B
ADC_RESOLUTION_8B
Return value:
Temperature: (unit: degree Celsius)
Notes:
Computation is using temperature sensor typical values (refer to device datasheet). Calculation formula: Temperature = (TS_TYP_CALx_VOLT(uV) - TS_ADC_DATA * Conversion_uV) / Avg_Slope + CALx_TEMP with TS_ADC_DATA = temperature sensor raw data measured by ADC (unit: digital value) Avg_Slope = temperature sensor slope (unit: uV/Degree Celsius) TS_TYP_CALx_VOLT = temperature sensor digital value at temperature CALx_TEMP (unit: mV) Caution: Calculation relevancy under reserve the temperature sensor of the current device has characteristics in line with datasheet typical values. If temperature sensor calibration values are available on on this device (presence of macro __LL_ADC_CALC_TEMPERATURE()), temperature calculation will be more accurate using helper macro __LL_ADC_CALC_TEMPERATURE(). As calculation input, the analog reference voltage (Vref+) must be defined as it impacts the ADC LSB equivalent voltage. Analog reference voltage (Vref+) must be either known from user board environment or can be calculated using ADC measurement and ADC helper macro __LL_ADC_CALC_VREFANALOG_VOLTAGE(). ADC measurement data must correspond to a resolution of 12bits (full scale digital value 4095). If not the case, the data must be preliminarily rescaled to an equivalent resolution of 12 bits.
ADC group injected trigger edge (when external trigger is selected)
UM2217
ADC Firmware driver defines
ADC_EXTERNALTRIGINJECCONV_EDGE_NONE
Injected conversions hardware trigger detection disabled
ADC_EXTERNALTRIGINJECCONV_EDGE_RISING
Injected conversions hardware trigger detection on the rising edge
ADC_EXTERNALTRIGINJECCONV_EDGE_FALLING
Injected conversions hardware trigger detection on the falling edge
ADC_EXTERNALTRIGINJECCONV_EDGE_RISINGFALLING
Injected conversions hardware trigger detection on both the rising and falling edges
ADC group injected trigger source
UM2217 - Rev 5
page 98/3786
Page 99
ADC_INJECTED_SOFTWARE_START
Software triggers injected group conversion start
ADC_EXTERNALTRIGINJEC_T1_TRGO
ADC group injected conversion trigger from external peripheral: TIM1 TRGO event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T1_CC4
ADC group injected conversion trigger from external peripheral: TIM1 channel 4 event (capture compare: input capture or output capture). Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T2_TRGO
ADC group injected conversion trigger from external peripheral: TIM2 TRGO event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T2_CC1
ADC group injected conversion trigger from external peripheral: TIM2 channel 1 event (capture compare: input capture or output capture). Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T3_CC4
ADC group injected conversion trigger from external peripheral: TIM3 channel 4 event (capture compare: input capture or output capture). Trigger edge set to rising edge (default setting).
UM2217
ADC Firmware driver defines
ADC_EXTERNALTRIGINJEC_T4_TRGO
ADC group injected conversion trigger from external peripheral: TIM4 TRGO event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_EXT_IT15
ADC group injected conversion trigger from external peripheral: external interrupt line 15. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T8_CC4
ADC group injected conversion trigger from external peripheral: TIM8 channel 4 event (capture compare: input capture or output capture). Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T1_TRGO2
ADC group injected conversion trigger from external peripheral: TIM1 TRGO2 event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T8_TRGO
ADC group injected conversion trigger from external peripheral: TIM8 TRGO event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T8_TRGO2
ADC group injected conversion trigger from external peripheral: TIM8 TRGO2 event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T3_CC3
ADC group injected conversion trigger from external peripheral: TIM3 channel 3 event (capture compare: input capture or output capture). Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T3_TRGO
ADC group injected conversion trigger from external peripheral: TIM3 TRGO event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T3_CC1
ADC group injected conversion trigger from external peripheral: TIM3 channel 1 event (capture compare: input capture or output capture). Trigger edge set to rising edge (default setting).
UM2217 - Rev 5
page 99/3786
Page 100
ADC_EXTERNALTRIGINJEC_T6_TRGO
ADC group injected conversion trigger from external peripheral: TIM6 TRGO event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_T15_TRGO
ADC group injected conversion trigger from external peripheral: TIM15 TRGO event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_HR1_ADCTRG2
ADC group injected conversion trigger from external peripheral: HRTIM1 TRG2 event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_HR1_ADCTRG4
ADC group injected conversion trigger from external peripheral: HRTIM1 TRG4 event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_LPTIM1_OUT
ADC group injected conversion trigger from external peripheral: LPTIM1 OUT event. Trigger edge set to rising edge (default setting).
ADC_EXTERNALTRIGINJEC_LPTIM2_OUT
ADC group injected conversion trigger from external peripheral: LPTIM2 OUT event. Trigger edge set to rising edge (default setting).
UM2217
ADC Firmware driver defines
ADC_EXTERNALTRIGINJEC_LPTIM3_OUT
ADC group injected conversion trigger from external peripheral: LPTIM3 OUT event. Trigger edge set to rising edge (default setting).
ADC group injected - Sequencer ranks
ADC_INJECTED_RANK_1
ADC group injected sequencer rank 1
ADC_INJECTED_RANK_2
ADC group injected sequencer rank 2
ADC_INJECTED_RANK_3
ADC group injected sequencer rank 3
ADC_INJECTED_RANK_4
ADC group injected sequencer rank 4
ADC interrupts definition
ADC_IT_RDY
ADC Ready interrupt source
ADC_IT_EOSMP
ADC End of sampling interrupt source
ADC_IT_EOC
ADC End of regular conversion interrupt source
ADC_IT_EOS
ADC_IT_OVR
UM2217 - Rev 5
ADC End of regular sequence of conversions interrupt source
ADC overrun interrupt source
page 100/3786
Loading...