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
STM32 portfolio. HAL APIs are available for all peripherals.
–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
1General 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
2Acronyms and definitions
Table 1. Acronyms and definitions
AcronymDefinition
ADCAnalog-to-digital converter
AESAdvanced encryption standard
ANSIAmerican national standards institute
APIApplication programming interface
BSPBoard support package
CANController area network
CECConsumer electronic controller
CMSISCortex microcontroller software interface standard
COMPComparator
CORDICTrigonometric calculation unit
CPUCentral processing unit
CRCCRC calculation unit
CRYPCryptographic processor
CSSClock security system
DACDigital to analog converter
DLYBDelay block
DCMIDigital camera interface
DFSDMDigital filter sigma delta modulator
DMADirect memory access
DMAMUXDirect memory access request multiplexer
DSIDisplay serial interface
DTSDigital temperature sensor
ETHEthernet controller
EXTIExternal interrupt/event controller
FDCANFlexible data-rate controller area network unit
TIMAdvanced-control, general-purpose or basic timer
TSCTouch sensing controller
TZArm TrustZone-M
TZENTrustZone enable Flash user option bit
UARTUniversal asynchronous receiver/transmitter
UCPD
USARTUniversal synchronous receiver/transmitter
VREFBUFVoltage reference buffer
WWDGWindow watchdog
USBUniversal serial bus
USB Type-C® and Power Delivery interface
UM2217
Acronyms and definitions
UM2217 - Rev 5
page 6/3786
Page 7
3Support 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
4Overview 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
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.
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.2User-application files
The minimum files required to build an application using the HAL are listed in the table below:
FileDescription
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
FileDescription
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.2HAL data structures
Each HAL driver can contain the following data structures:
•Peripheral handle structures
•Initialization and configuration structures
•Specific process structures.
4.2.1Peripheral 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 readmodify-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.2Initialization 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:
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.
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).
•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:
•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.2HAL 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.
•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.
•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 groupCommon API nameDescription
This function initializes the peripheral and configures the low -level
resources (clocks, GPIO, AF..)
This function restores the peripheral default state, frees the lowlevel 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.7HAL extension APIs
4.7.1HAL 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 groupCommon API name
HAL_ADCEx_CalibrationStart()This function is used to start the automatic ADC calibration
4.7.2HAL 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.8File 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:
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:
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 itemDescriptionDefault Value
HSE_VALUE
HSE_STARTUP_TIMEOUTTimeout for HSE start-up, expressed in ms5000
HSI_VALUEDefines the value of the internal oscillator (HSI) expressed in Hz.64 000 000 Hz
LSE_VALUE
LSE_STARTUP_TIMEOUTTimeout for LSE start-up, expressed in ms5000
CSI_VALUEDefines the value of the internal oscillator (CSI) expressed in Hz4 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 itemDescriptionDefault Value
LSI_VALUEDefines the value of the internal oscillator (LSI) expressed in Hz32 000 Hz
VDD_VALUEVDD value3300 (mV)
USE_RTOSEnables 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.11HAL 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.1Clock
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.2GPIOs
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 fieldDescription
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.
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
MacrosDescription
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
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.6DMA
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.1HAL 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.cstm32hxxx_hal_ppp.cServices
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.2HAL initialization
4.12.2.1HAL 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.2System 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:
/* 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;
/*
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.3HAL 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:
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.3HAL 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.1Polling 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 :
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.
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):
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.
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
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:
1. HAL_MAX_DELAY is defined in the stm32h7xx_hal_def.h as 0xFFFFFFFF
HAL_MAX_DELAYInfinite 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.
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).
•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.
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:
The HAL implements run-time failure detection by checking the input values of all HAL driver functions. The runtime 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.
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
5Overview 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.1Low-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.
FileDescription
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.1Peripheral 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_InitErrorStatus
LL_PPP_StructInitvoid
Return
Type
ParametersDescription
•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.
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.
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:
•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
6Cohabiting 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.1Low-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
7HAL System Driver
7.1HAL 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
8HAL ADC Generic Driver
8.1ADC Firmware driver registers structures
8.1.1ADC_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
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.2ADC_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.
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(), ...).
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).
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
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.
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
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
Specify the Oversampling parameters. Caution: this setting overwrites the previous oversampling
configuration if oversampling is already enabled.
8.1.3ADC_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).
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
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.4ADC_AnalogWDGConfTypeDef
ADC_AnalogWDGConfTypeDef is defined in the stm32h7xx_hal_adc.h
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).
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.5ADC_InjectionConfigTypeDef
ADC_InjectionConfigTypeDef is defined in the stm32h7xx_hal_adc.h
Injected channel configuration context: build-up over each HAL_ADCEx_InjectedConfigChannel() call to
finally initialize JSQR register at HAL_ADCEx_InjectedConfigChannel() last call
The following section lists the various functions of the ADC library.
8.2.1ADC 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.
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
–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:
•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:
•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.3Peripheral 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.4Peripheral state and errors functions
This subsection provides functions to get in run-time the status of the peripheral.
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).
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).
•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);
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().
Stop ADC conversion of regular group (and injected group in case of auto_injection mode), disable interrution of
end-of-conversion, disable ADC peripheral.
•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).
"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,
•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.
•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) "
•Prerequisite condition to use this function: ADC conversions must be stopped.
8.3ADC Firmware driver defines
The following section lists the various define and macros of the module.
UM2217
ADC Firmware driver defines
8.3.1ADC
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 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)
•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)