STMicroelectronics STM32G0 HAL User Manual

UM2319

User manual

Description of STM32G0 HAL and low-layer drivers

Introduction

STM32Cube is an STMicroelectronics original initiative to significantly improve developer productivity by reducing development effort, time and cost. STM32Cube covers the STM32 portfolio.

STM32Cube includes:

•STM32CubeMX, a graphical software configuration tool that allows the generation of C initialization code using graphical wizards.

•A comprehensive embedded software platform, delivered per Series (such as STM32CubeG0 for STM32G0 Series)

–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 FAT file system, RTOS, USB and USB PD.

–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 featureoriented 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.

The HALand 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.

The next release will be compliant with MISRA C®:2012 standard.

UM2319 - Rev 2 - October 2020	www.st.com
For further information contact your local STMicroelectronics sales office.

UM2319

This user manual is structured as follows:

•Overview of HAL drivers

•Overview of low-layer drivers

•Cohabiting of HAL and LL drivers

•Detailed description of each peripheral driver: configuration structures, functions, and how to use the given API to build your application

UM2319 - Rev 2	page 2/2202

UM2319

General information

1General information

	The STM32CubeG0 MCU Package runs on STM32G0 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.

UM2319 - Rev 2	page 3/2202

UM2319

Acronyms and definitions

2Acronyms and definitions

	Table 1. Acronyms and definitions

Acronym	Definition
ADC	Analog-to-digital converter

AES	Advanced encryption standard

ANSI	American national standards institute

API	Application programming interface

BSP	Board support package

CAN	Controller area network

CEC	Consumer electronic controller

CMSIS	Cortex microcontroller software interface standard

COMP	Comparator

CORDIC	Trigonometric calculation unit

CPU	Central processing unit

CRC	CRC calculation unit

CRYP	Cryptographic processor

CSS	Clock security system

DAC	Digital to analog converter

DLYB	Delay block

DCMI	Digital camera interface

DFSDM	Digital filter sigma delta modulator

DMA	Direct memory access

DMAMUX	Direct memory access request multiplexer

DSI	Display serial interface

DTS	Digital temperature sensor

ETH	Ethernet controller

EXTI	External interrupt/event controller

FDCAN	Flexible data-rate controller area network unit

FLASH	Flash memory

FMAC	Filtering mathematical calculation unit

FMC	Flexible memory controller

FW	Firewall

GFXMMU	Chrom-GRC

GPIO	General purpose I/Os

GTZC	Global TrustZone® controller
GTZC-MPCBB	GTZC block-based memory protection controller

GTZC-MPCWM	GTZC watermark memory protection controller

GTZC-TZIC	GTZC TrustZone illegal access controller

GTZC-TZSC	GTZC TrustZone security controller

UM2319 - Rev 2	page 4/2202

UM2319

Acronyms and definitions

Acronym	Definition
HAL	Hardware abstraction layer

HASH	Hash processor

HCD	USB host controller driver

HRTIM	High-resolution timer

I2C	Inter-integrated circuit

I2S	Inter-integrated sound

ICACHE	Instruction cache

IRDA	Infrared data association

IWDG	Independent watchdog

JPEG	Joint photographic experts group

LCD	Liquid crystal display controler

LTDC	LCD TFT display controller

LPTIM	Low-power timer

LPUART	Low-power universal asynchronous receiver/transmitter

MCO	Microcontroller clock output

MDIOS	Management data input/output (MDIO) slave

MDMA	Master direct memory access

MMC	MultiMediaCard

MPU	Memory protection unit

MSP	MCU specific package

NAND	NAND Flash memory

NOR	NOR Flash memory

NVIC	Nested vectored interrupt controller

OCTOSPI	Octo-SPI interface

OPAMP	Operational amplifier

OTFDEC	On-the-fly decryption engine

OTG-FS	USB on-the-go full-speed

PKA	Public key accelerator

PCD	USB peripheral controller driver

PPP	STM32 peripheral or block

PSSI	Parallel synchronous slave interface

PWR	Power controller

QSPI	Quad-SPI Flash memory

RAMECC	RAM ECC monitoring

RCC	Reset and clock controller

RNG	Random number generator

RTC	Real-time clock

SAI	Serial audio interface

SD	Secure digital

SDMMC	SD/SDIO/MultiMediaCard card host interface

UM2319 - Rev 2	page 5/2202

UM2319

Acronyms and definitions

Acronym	Definition
SMARTCARD	Smartcard IC

SMBUS	System management bus

SPI	Serial peripheral interface

SPDIFRX	SPDIF-RX Receiver interface

SRAM	SRAM external memory

SWPMI	Serial wire protocol master interface

SysTick	System tick timer

TIM	Advanced-control, general-purpose or basic timer

TSC	Touch sensing controller

TZ	Arm TrustZone-M

TZEN	TrustZone enable Flash user option bit

UART	Universal asynchronous receiver/transmitter

UCPD	USB Type-C® and Power Delivery interface
USART	Universal synchronous receiver/transmitter

VREFBUF	Voltage reference buffer

WWDG	Window watchdog

USB	Universal serial bus

UM2319 - Rev 2	page 6/2202

UM2319

Overview of HAL drivers

3Overview of HAL drivers

The HAL drivers are designed to offer a rich set of APIs and to interact easily with the application upper layers.

Each driver consists of a set of functions covering the most common peripheral features. The development of each driver is driven by a common API which standardizes the driver structure, the functions and the parameter names.

The HAL drivers include a set of driver modules, each module being linked to a standalone peripheral. However, in some cases, the module is linked to a peripheral functional mode. As an example, several modules exist for the USART peripheral: UART driver module, USART driver module, SMARTCARD driver module and IRDA driver module.

The HAL main features are the following:

•Cross-family portable set of APIs covering the common peripheral features as well as extension APIs in case of specific peripheral features.

•Three API programming models: polling, interrupt and DMA.

•APIs are RTOS compliant:

–Fully reentrant APIs

–Systematic usage of timeouts in polling mode

•Support of peripheral multi-instance allowing concurrent API calls for multiple instances of a given peripheral (such as USART1 or USART2)

•All HAL APIs implement user-callback functions mechanism:

–Peripheral Init/DeInit HAL APIs can call user-callback functions to perform peripheral system level Initialization/De-Initialization (clock, GPIOs, interrupt, DMA)

–Peripherals interrupt events

–Error events

•Object locking mechanism: safe hardware access to prevent multiple spurious accesses to shared resources.

•Timeout used for all blocking processes: the timeout can be a simple counter or a timebase.

UM2319 - Rev 2	page 7/2202

UM2319

HAL and user-application files

3.1HAL and user-application files

3.1.1HAL driver files

HAL drivers are composed of the following set of files:

		Table 2. HAL driver files

	File	Description

		Main peripheral/module driver file
	stm32g0xx_hal_ppp.c	It includes the APIs that are common to all STM32 devices.
		Example: stm32g0xx_hal_adc.c, stm32g0xx_hal_irda.c.

		Header file of the main driver C file
	stm32g0xx_hal_ppp.h	It includes common data, handle and enumeration structures, define statements and
	stm32g0xx_hal_ppp.h	macros, as well as the exported generic APIs.
		macros, as well as the exported generic APIs.
		Example:stm32g0xx_hal_adc.h,stm32g0xx_hal_irda.h.

		Extension file of a peripheral/module driver. It includes the specific APIs for a given part
	stm32g0xx_hal_ppp_ex.c	number or family, as well as the newly defined APIs that overwrite the default generic APIs if
	stm32g0xx_hal_ppp_ex.c	the internal process is implemented in different way.
		Example:stm32g0xx_hal_adc_ex.c,stm32g0xx_hal_flash_ex.c.

		Header file of the extension C file
	stm32g0xx_hal_ppp_ex.h	It includes the specific data and enumeration structures, define statements and macros, as
	stm32g0xx_hal_ppp_ex.h	well as the exported device part number specific APIs
		well as the exported device part number specific APIs
		Example: stm32g0xx_hal_adc_ex.h,stm32g0xx_hal_flash_ex.h.

	stm32g0xx_hal.c	This file is used for HAL initialization and contains DBGMCU, Remap and Time Delay based
	stm32g0xx_hal.c	on SysTick APIs.
		on SysTick APIs.

	stm32g0xx_hal.h	stm32g0xx_hal.c header file

		Template file to be copied to the user application folder
	stm32g0xx_hal_msp_template.c	It contains the MSP initialization and de-initialization (main routine and callbacks) of the
		peripheral used in the user application.

	stm32g0xx_hal_conf_template.h	Template file allowing to customize the drivers for a given application

	stm32g0xx_hal_def.h	Common HAL resources such as common define statements, enumerations, structures and
	stm32g0xx_hal_def.h	macros
		macros

3.1.2User-application files

The minimum files required to build an application using the HAL are listed in the table below:

		Table 3. User-application files

	File	Description

		This file contains SystemInit() that is called at startup just after reset and before branching to the
	system_stm32g0xx.c	main program. It does not configure the system clock at startup (contrary to the standard library).
	system_stm32g0xx.c	This is to be done using the HAL APIs in the user files. It allows relocating the vector table in

		internal SRAM.

	startup_stm32g0xx.s	Toolchain specific file that contains reset handler and exception vectors.
	startup_stm32g0xx.s	For some toolchains, it allows adapting the stack/heap size to fit the application requirements.


	stm32g0xx_flash.icf	Linker file for EWARM toolchain allowing mainly adapting the stack/heap size to fit the application
	(optional)	requirements.

	stm32g0xx_hal_msp.c	This file contains the MSP initialization and de-initialization (main routine and callbacks) of the
	stm32g0xx_hal_msp.c	peripheral used in the user application.
		peripheral used in the user application.

UM2319 - Rev 2	page 8/2202

		UM2319
		HAL and user-application files


File		Description
	This file allows the user to customize the HAL drivers for a specific application.
stm32g0xx_hal_conf.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 stm32g0xx_hal.c)
stm32g0xx_it.c/.h	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:
	•	Call to HAL_Init()
main.c/.h	•	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_GetTick()

–System clock configured with the selected device frequency.

Note:

If an existing project is copied to another location, then include paths must be updated.

UM2319 - Rev 2	page 9/2202

UM2319

HAL data structures

Figure 1. Example of project template

3.2HAL data structures

Each HAL driver can contain the following data structures:

•Peripheral handle structures

•Initialization and configuration structures

•Specific process structures.

3.2.1Peripheral handle structures

The APIs have a modular generic multi-instance architecture that enables 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.

UM2319 - Rev 2	page 10/2202

UM2319

HAL data structures

An example of peripheral structure is shown below:

	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;
Note:	1. The multi-instance feature implies that all the APIs used in the application are reentrant and avoid using
	global variables because subroutines can fail to be reentrant if they rely on a global variable to remain
	unchanged but that variable is modified when the subroutine is recursively invoked. For this reason, the
	following rules are respected:

–Reentrant code does not hold any static (or global) non-constant data: reentrant functions can work with global data. For example, a reentrant interrupt service routine can grab a piece of hardware status to work with (for example serial port read buffer) which is not only global, but volatile. Still, typical use of static variables and global data is not advised, in the sense that only atomic read- modify-write instructions should be used in these variables. It should not be possible for an interrupt or signal to occur during the execution of such an instruction.

–Reentrant code does not modify its own code.

2.When a peripheral can manage several processes simultaneously using the DMA (full duplex case), the DMA interface handle for each process is added in the PPP_HandleTypeDef.

3.For the shared and system peripherals, no handle or instance object is used. The peripherals concerned by this exception are the following:

–GPIO

–SYSTICK

–NVIC

–PWR

–RCC

–FLASH

3.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 baudrate.*/ 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 wether the Receive or Transmit mode is enabled or disabled.*/ uint32_t HwFlowCtl; /*!< Specifies wether the hardware flow control mode is enabled or disabled.*/

uint32_t OverSampling; /*!< Specifies wether the Over sampling 8 is enabled or disabled, to achieve higher speed (up to fPCLK/8).*/

}UART_InitTypeDef;

UM2319 - Rev 2	page 11/2202

UM2319

HAL data structures

Note:

The config structure is used to initialize the sub-modules or sub-instances. See below example:

HAL_ADC_ConfigChannel (ADC_HandleTypeDef* hadc, ADC_ChannelConfTypeDef* sConfig)

3.2.3Specific process structures

The specific process structures are used for specific process (common APIs). They are defined in the generic driver header file.

Example:

HAL_PPP_Process (PPP_HandleTypeDef* hadc,PPP_ProcessConfig* sConfig)

UM2319 - Rev 2	page 12/2202

UM2319

API classification

3.3API classification

The HAL APIs are classified into the following categories:

•Generic APIs: common generic APIs applying to all STM32 devices. These APIs are consequently present in the generic HAL driver files of all STM32 microcontrollers.

HAL_StatusTypeDef HAL_ADC_Init(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef HAL_ADC_DeInit(ADC_HandleTypeDef *hadc); HAL_StatusTypeDef HAL_ADC_Start(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef HAL_ADC_Stop(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef HAL_ADC_Start_IT(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef HAL_ADC_Stop_IT(ADC_HandleTypeDef* hadc); void HAL_ADC_IRQHandler(ADC_HandleTypeDef* hadc);

•Extension APIs:

This set of API is divided into two sub-categories :

–Family specific APIs: APIs applying to a given family. They are located in the extension HAL driver file (see example below related to the ADC).

HAL_StatusTypeDef HAL_ADCEx_Calibration_Start(ADC_HandleTypeDef* hadc,uint32_t SingleDiff);

uint32_t HAL_ADCEx_Calibration_GetValue(ADC_HandleTypeDef* hadc, uint32_t SingleDiff);

–Feature/Device specific APIs: these APIs are implemented in the extension file and delimited by specific define statements relative to CMSIS bits or features and depending on device part number.

#if defined(PWR_SHDW_SUPPORT)

void HAL_PWREx_EnterSHUTDOWNMode(void); #endif

Note:	The data structure related to the specific APIs is delimited by the device part number define statement. It is
	located in the corresponding extension header C file.
	The following table summarizes the location of the different categories of HAL APIs in the driver files.
		Table 4. API classification

		Generic file	Extension file
	Common APIs	X	X

	Family specific APIs	-	X

	Device specific APIs	-	X

Note:	Family specific APIs are only related to a given family. This means that if a specific API is implemented in
	another family, and the arguments of this latter family are different, additional structures and arguments might
	need to be added.
Note:	The IRQ handlers are used for common and family specific processes.

UM2319 - Rev 2	page 13/2202

UM2319

Devices supported by HAL drivers

3.4Devices supported by HAL drivers

UM2319 - Rev 2	page 14/2202

<![if ! IE]>

<![endif]>2 Rev - UM2319

<![if ! IE]>

<![endif]>15/2202 page

Table 5. List of devices supported by HAL drivers

IP/module

<![if ! IE]>

<![endif]>STM32G0C1xx

<![if ! IE]>

<![endif]>STM32G0B1xx

<![if ! IE]>

<![endif]>STM32G0B0xx

<![if ! IE]>

<![endif]>STM32G081xx

<![if ! IE]>

<![endif]>STM32G071xx

<![if ! IE]>

<![endif]>STM32G070xx

<![if ! IE]>

<![endif]>STM32G061xx

<![if ! IE]>

<![endif]>STM32G051xx

<![if ! IE]>

<![endif]>STM32G050xx

<![if ! IE]>

<![endif]>STM32G041xx

<![if ! IE]>

<![endif]>STM32G031xx

<![if ! IE]>

<![endif]>STM32G030xx

stm32g0xx_hal.c

Yes

stm32g0xx_hal_adc.c

Yes

stm32g0xx_hal_adc_ex.c

Yes

stm32g0xx_hal_cec.c

Yes

stm32g0xx_hal_comp.c

Yes

stm32g0xx_hal_cortex.c

Yes

stm32g0xx_hal_crc.c

Yes

stm32g0xx_hal_crc_ex.c

Yes

stm32g0xx_hal_cryp.c

Yes

stm32g0xx_hal_cryp_ex.c

Yes

stm32g0xx_hal_dac.c

Yes

stm32g0xx_hal_dac_ex.c

Yes

stm32g0xx_hal_dma.c

Yes

stm32g0xx_hal_dma_ex.c

Yes

stm32g0xx_hal_exti.c

Yes

stm32g0xx_hal_fdcan.c

Yes

stm32g0xx_hal_flash.c

Yes

stm32g0xx_hal_flash_ex.c

Yes

stm32g0xx_hal_gpio.c

Yes

stm32g0xx_hal_hcd.c

Yes

stm32g0xx_hal_i2c.c

Yes

stm32g0xx_hal_i2c_ex.c

Yes

stm32g0xx_hal_i2s.c

Yes

stm32g0xx_hal_irda.c

Yes

stm32g0xx_hal_iwdg.c

Yes

stm32g0xx_hal_lptim.c

Yes

stm32g0xx_hal_msp_template.c

Yes

stm32g0xx_hal_pcd.c

Yes

stm32g0xx_hal_pcd_ex.c

Yes

stm32g0xx_hal_pwr.c

Yes

stm32g0xx_hal_pwr_ex.c

Yes

<![if ! IE]>

<![endif]>UM2319

<![if ! IE]>

<![endif]>drivers HAL by supported Devices

<![if ! IE]>

<![endif]>-2RevUM2319

IP/module

<![if ! IE]>

<![endif]>STM32G0C1xx

<![if ! IE]>

<![endif]>STM32G0B1xx

<![if ! IE]>

<![endif]>STM32G0B0xx

<![if ! IE]>

<![endif]>STM32G081xx

<![if ! IE]>

<![endif]>STM32G071xx

<![if ! IE]>

<![endif]>STM32G070xx

<![if ! IE]>

<![endif]>STM32G061xx

<![if ! IE]>

<![endif]>STM32G051xx

<![if ! IE]>

<![endif]>STM32G050xx

<![if ! IE]>

<![endif]>STM32G041xx

<![if ! IE]>

<![endif]>STM32G031xx

<![if ! IE]>

<![endif]>STM32G030xx

stm32g0xx_hal_rcc.c

Yes

stm32g0xx_hal_rcc_ex.c

Yes

stm32g0xx_hal_rng.c

Yes

stm32g0xx_hal_rtc.c

Yes

stm32g0xx_hal_rtc_ex.c

Yes

stm32g0xx_hal_smartcard.c

Yes

stm32g0xx_hal_smartcard_ex.c

Yes

stm32g0xx_hal_smbus.c

Yes

stm32g0xx_hal_spi.c

Yes

stm32g0xx_hal_spi_ex.c

Yes

stm32g0xx_hal_tim.c

Yes

stm32g0xx_hal_tim_ex.c

Yes

stm32g0xx_hal_uart.c

Yes

stm32g0xx_hal_uart_ex.c

Yes

stm32g0xx_hal_usart.c

Yes

stm32g0xx_hal_usart_ex.c

Yes

stm32g0xx_hal_wwdg.c

Yes

<![if ! IE]>

<![endif]>16/2202 page

<![if ! IE]>

<![endif]>UM2319 drivers HAL by supported Devices

UM2319

HAL driver rules

3.5HAL driver rules

3.5.1HAL API naming rules

The following naming rules are used in HAL drivers:

Table 6. HAL API naming rules

	Generic	Family specific	Device specific

File names	stm32g0xx_hal_ppp (c/h)	stm32g0xx_hal_ppp_ex (c/h)	stm32g0xx_ hal_ppp_ex (c/h)

Module		HAL_PPP_ MODULE
name		HAL_PPP_ MODULE
name

Function	HAL_PPP_Function	HAL_PPPEx_Function	HAL_PPPEx_Function
name	HAL_PPP_FeatureFunction_MODE	HAL_PPPEx_FeatureFunction_MODE	HAL_PPPEx_FeatureFunction_MODE

Handle	PPP_HandleTypedef	NA	NA
name	PPP_HandleTypedef	NA	NA
name

Init
structure	PPP_InitTypeDef	NA	PPP_InitTypeDef
name

Enum name	HAL_PPP_StructnameTypeDef	NA	NA

•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 STM32G0 reference manuals.

•Peripheral registers are declared in the PPP_TypeDef structure (for example ADC_TypeDef) in stm32g0xxx.h header file:

stm32g0xxx.h corresponds to stm32g081xx.h, stm32g071xx.h and stm32g070xx.h.

•Peripheral function names are prefixed by HAL_, then the corresponding peripheral acronym in uppercase followed by an underscore. The first letter of each word is in uppercase (for example HAL_UART_Transmit()). Only one underscore is allowed in a function name to separate the peripheral acronym from the rest of the function name.

•The structure containing the PPP peripheral initialization parameters are named PPP_InitTypeDef (for example ADC_InitTypeDef).

•The structure containing the Specific configuration parameters for the PPP peripheral are named PPP_xxxxConfTypeDef (for example ADC_ChannelConfTypeDef).

•Peripheral handle structures are named PPP_HandleTypedef (e.g DMA_HandleTypeDef)

•The functions used to initialize the PPP peripheral according to parameters specified in PPP_InitTypeDef are named HAL_PPP_Init (for example HAL_TIM_Init()).

•The functions used to reset the PPP peripheral registers to their default values are named HAL_PPP_DeInit (for example HAL_TIM_DeInit()).

•The MODE suffix refers to the process mode, which can be polling, interrupt or DMA. As an example, when the DMA is used in addition to the native resources, the function should be called:

HAL_PPP_Function_DMA().

•The Feature prefix should refer to the new feature.

Example: HAL_ADCEx_InjectedStart()() refers to the injection mode.

UM2319 - Rev 2	page 17/2202

UM2319

HAL driver rules

3.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.

HAL_StatusTypeDef HAL_GPIO_Init (GPIO_TypeDef* GPIOx, GPIO_InitTypeDef *Init)

{

/*GPIO Initialization body */

}

• The macros that handle interrupts and specific clock configurations are defined in each peripheral/module driver. These macros are exported in the peripheral driver header files so that they can be used by the extension file. The list of these macros is defined below:

Note:	This list is not exhaustive and other macros related to peripheral features can be added, so that they can be
	used in the user application.
	Table 7. Macros handling interrupts and specific clock configurations

	Macros	Description

	__HAL_PPP_ENABLE_IT(__HANDLE__, __INTERRUPT__)	Enables a specific peripheral interrupt

	__HAL_PPP_DISABLE_IT(__HANDLE__,	Disables a specific peripheral interrupt
	__INTERRUPT__)	Disables a specific peripheral interrupt
	__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__, __	Checks the source of specified interrupt
	INTERRUPT __)	Checks the source of specified interrupt
	INTERRUPT __)

•NVIC and SYSTICK are two Arm® Cortex® core features. The APIs related to these features are located in the stm32g0xx_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).

•The PPP handles are valid before using the HAL_PPP_Init() API. The init function performs a check before modifying the handle fields.

HAL_PPP_Init(PPP_HandleTypeDef) if(hppp == NULL)

{

return HAL_ERROR;

}

UM2319 - Rev 2	page 18/2202

UM2319

HAL generic APIs

•The macros defined below are used:

– Conditional macro:

#define ABS(x) (((x) > 0) ? (x) : -(x))

–Pseudo-code macro (multiple instructions macro):

#define __HAL_LINKDMA(__HANDLE__, __PPP_DMA_FIELD_, __DMA_HANDLE_) \ do{ \

(__HANDLE__)->__PPP_DMA_FIELD_ = &(__DMA_HANDLE_); \ (__DMA_HANDLE_).Parent = (__HANDLE__); \

}while(0)

3.5.3HAL interrupt handler and callback functions

Besides the APIs, HAL peripheral drivers include:

•HAL_PPP_IRQHandler() peripheral interrupt handler that should be called from stm32g0xx_it.c

•User callback functions.

The user callback functions are defined as empty functions with “weak” attribute. They have to be defined in the user code.

There are three types of user callbacks functions:

•Peripheral system level initialization/ de-Initialization callbacks: HAL_PPP_MspInit() and HAL_PPP_MspDeInit

•Process complete callbacks : HAL_PPP_ProcessCpltCallback

•Error callback: HAL_PPP_ErrorCallback.

Table 8. Callback functions

Callback functions	Example

Example: HAL_USART_MspInit()

HAL_PPP_MspInit() / _DeInit() Called from HAL_PPP_Init() API function to perform peripheral system level initialization

(GPIOs, clock, DMA, interrupt)

Example: HAL_USART_TxCpltCallback

HAL_PPP_ProcessCpltCallback

Called by peripheral or DMA interrupt handler when the process completes

Example: HAL_USART_ErrorCallback

HAL_PPP_ErrorCallback

Called by peripheral or DMA interrupt handler when an error occurs

3.6HAL generic APIs

The generic APIs provide common generic functions applying to all STM32 devices. They are composed of four APIs groups:

•Initialization and de-initialization functions:HAL_PPP_Init(), HAL_PPP_DeInit()

•IO operation functions: HAL_PPP_Read(), HAL_PPP_Write(),HAL_PPP_Transmit(), HAL_PPP_Receive()

•Control functions: HAL_PPP_Set (), HAL_PPP_Get ().

•State and Errors functions: HAL_PPP_GetState (), HAL_PPP_GetError ().

For some peripheral/module drivers, these groups are modified depending on the peripheral/module implementation.

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.

UM2319 - Rev 2	page 19/2202

UM2319

HAL extension APIs

The control functions are used to change dynamically the peripheral configuration and set another operating mode.

The peripheral state and errors functions allow retrieving in run time the peripheral and data flow states, and identifying the type of errors that occurred. The example below is based on the ADC peripheral. The list of generic APIs is not exhaustive. It is only given as an example.

Table 9. HAL generic APIs

Function group	Common API name	Description

	HAL_ADC_Init()	This function initializes the peripheral and configures the low -level
	HAL_ADC_Init()	resources (clocks, GPIO, AF..)
		resources (clocks, GPIO, AF..)
Initialization group
Initialization group		This function restores the peripheral default state, frees the low-

	HAL_ADC_DeInit()	level resources and removes any direct dependency with the
		hardware.

	HAL_ADC_Start ()	This function starts ADC conversions when the polling method is
	HAL_ADC_Start ()	used
		used

	HAL_ADC_Stop ()	This function stops ADC conversions when the polling method is
	HAL_ADC_Stop ()	used
		used

		This function allows waiting for the end of conversions when the
	HAL_ADC_PollForConversion()	polling method is used. In this case, a timout value is specified by
		the user according to the application.

IO operation group	HAL_ADC_Start_IT()	This function starts ADC conversions when the interrupt method is
	HAL_ADC_Start_IT()	used
		used

	HAL_ADC_Stop_IT()	This function stops ADC conversions when the interrupt method is
	HAL_ADC_Stop_IT()	used
		used

	HAL_ADC_IRQHandler()	This function handles ADC interrupt requests

	HAL_ADC_ConvCpltCallback()	Callback function called in the IT subroutine to indicate the end of
	HAL_ADC_ConvCpltCallback()	the current process or when a DMA transfer has completed
		the current process or when a DMA transfer has completed

	HAL_ADC_ErrorCallback()	Callback function called in the IT subroutine if a peripheral error or a
	HAL_ADC_ErrorCallback()	DMA transfer error occurred
		DMA transfer error occurred

	HAL_ADC_ConfigChannel()	This function configures the selected ADC regular channel, the
Control group	HAL_ADC_ConfigChannel()	corresponding rank in the sequencer and the sample time
		corresponding rank in the sequencer and the sample time

	HAL_ADC_AnalogWDGConfig	This function configures the analog watchdog for the selected ADC

	HAL_ADC_GetState()	This function allows getting in run time the peripheral and the data
State and Errors	HAL_ADC_GetState()	flow states.
		flow states.

group	HAL_ADC_GetError()	This fuction allows getting in run time the error that occurred during

		IT routine
		IT routine

3.7HAL extension APIs

3.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, stm32g0xx_hal_ppp_ex.c, that includes all the specific functions and define statements (stm32g0xx_hal_ppp_ex.h) for a given part number.

Below an example based on the ADC peripheral:

Table 10. HAL extension APIs

Function group	Common API name

HAL_ADCEx_CalibrationStart()	This function is used to start the automatic ADC calibration

UM2319 - Rev 2	page 20/2202

		UM2319
		HAL extension APIs


	Function group	Common API name
	HAL_ADCEx_Calibration_GetValue()	This function is used to get the ADC calibration factor

3.7.2HAL extension model cases

The specific peripheral features can be handled by the HAL drivers in five different ways. They are described below.

Adding a part number-specific function

When a new feature specific to a given device is required, the new APIs are added in the stm32g0xx_hal_ppp_ex.c extension file. They are named HAL_PPPEx_Function().

Figure 2. Adding device-specific functions

Example: stm32g0xx_hal_pwr_ex.c/h

#if defined(PWR_SHDW_SUPPORT)

void HAL_PWREx_EnterSHUTDOWNMode(void); #endif

Adding a family-specific function

In this case, the API is added in the extension driver C file and named HAL_PPPEx_Function ().

Figure 3. 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 stm32g0xx_hal_newppp.c. However the inclusion of this file is selected in the stm32g0xx_hal_conf.h using the macro:

UM2319 - Rev 2	page 21/2202

STMicroelectronics STM32G0 HAL User Manual

UM2319

HAL extension APIs

#define HAL_NEWPPP_MODULE_ENABLED

Figure 4. Adding new peripherals

Example: stm32g0xx_hal_adc.c/h

Updating existing common APIs

In this case, the routines are defined with the same names in the stm32g0xx_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.

Figure 5. Updating existing APIs

Updating existing data structures

The data structure for a specific device part number (for example PPP_InitTypeDef) can have different fields. In this case, the data structure is defined in the extension header file and delimited by the specific part number define statement.

UM2319 - Rev 2	page 22/2202

UM2319

File inclusion model

3.8File inclusion model

The header of the common HAL driver file (stm32g0xx_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.

Figure 6. File inclusion model

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 stm32g0xx_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 HAL_USART_MODULE_ENABLED #define HAL_IRDA_MODULE_ENABLED #define HAL_DMA_MODULE_ENABLED #define HAL_RCC_MODULE_ENABLED

(…)

UM2319 - Rev 2	page 23/2202

UM2319

HAL common resources

3.9HAL common resources

The common HAL resources, such as common define enumerations, structures and macros, are defined in stm32g0xx_hal_def.h.The main common define enumeration is HAL_StatusTypeDef.

•HAL Status

The HAL status is used by almost all HAL APIs, except for boolean functions and IRQ handler. It returns the status of the current API operations. It has four possible values as described below:

Typedef enum

{

HAL_OK = 0x00, HAL_ERROR = 0x01, HAL_BUSY = 0x02, HAL_TIMEOUT = 0x03

}HAL_StatusTypeDef;

•HAL Locked

The HAL lock is used by all HAL APIs to prevent accessing by accident shared resources.

typedef enum

{

HAL_UNLOCKED = 0x00, /*!<Resources unlocked */ HAL_LOCKED = 0x01 /*!< Resources locked */

} HAL_LockTypeDef;

In addition to common resources, the stm32g0xx_hal_def.h file calls the stm32g0xx.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

#define HAL_MAX_DELAY 0xFFFFFFFF

–Macro linking a PPP peripheral to a DMA structure pointer:

#define __HAL_LINKDMA(__HANDLE__, __PPP_DMA_FIELD_, __DMA_HANDLE_) \ do{ \

(__HANDLE__)->__PPP_DMA_FIELD_ = &(__DMA_HANDLE_); \ (__DMA_HANDLE_).Parent = (__HANDLE__); \

}while(0)

3.10HAL configuration

The configuration file, stm32g0xx_hal_conf.h, allows customizing the drivers for the user application. Modifying this configuration is not mandatory: the application can use the default configuration without any modification.

To configure these parameters, the user should enable, disable or modify some options by uncommenting, commenting or modifying the values of the related define statements as described in the table below:

Table 11. Define statements used for HAL configuration

Configuration item	Description	Default Value
HSE_VALUE	Defines the value of the external oscillator (HSE) expressed in Hz.
HSE_VALUE	The user must adjust this define statement when using a different	8 000 000 Hz
	crystal value.

HSE_STARTUP_TIMEOUT	Timeout for HSE start-up, expressed in ms	100

HSI_VALUE	Defines the value of the internal oscillator (HSI) expressed in Hz.	16 000 000 Hz

UM2319 - Rev 2	page 24/2202

UM2319

HAL system peripheral handling

Configuration item	Description	Default Value
HSI48_VALUE	Defines the value of the Internal High Speed oscillator for USB
HSI48_VALUE	expressed in Hz. The real value may vary depending on the	48 000 000 Hz
	variations in voltage and temperature.

LSI_VALUE	Defines the default value of the Low-speed internal oscillator (LSI)	32000 Hz
LSI_VALUE	expressed in Hz.	32000 Hz
	expressed in Hz.

LSE_VALUE	Defines the value of the external oscillator (LSE) expressed in Hz.
LSE_VALUE	The user must adjust this define statement when using a different	32768 Hz
	crystal value.

LSE_STARTUP_TIMEOUT	Timeout for LSE start-up, expressed in ms	5000

VDD_VALUE	VDD value	3300 (mV)

USE_RTOS	Enables the use of RTOS	FALSE (for future
USE_RTOS	Enables the use of RTOS	use)
		use)

PREFETCH_ENABLE	Enables prefetch feature	FALSE

INSTRUCTION_CACHE_ENABLE	Enables ICACHE feature	TRUE

DATA_CACHE_ENABLE	Enables DCACHE feature	FALSE

Note:	The stm32g0xx_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 stm32g0xx_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.

3.11HAL system peripheral handling

This section 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.

3.11.1Clocks

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 and APB2 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 stm32g0xx_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 stm32g0xx_hal_rcc.h and stm32g0xx_hal_rcc_ex.h. They allow executing elementary operations on RCC block registers, such as peripherals clock gating/reset control:

•__HAL_PPP_CLK_ENABLE/__HAL_PPP_CLK_DISABLE to enable/disable the peripheral clock

•__HAL_PPP_FORCE_RESET/__HAL_PPP_RELEASE_RESET to force/release peripheral reset

UM2319 - Rev 2	page 25/2202

UM2319

HAL system peripheral handling

•__HAL_PPP_CLK_SLEEP_ENABLE/__HAL_PPP_CLK_SLEEP_DISABLE to enable/disable the peripheral clock during Sleep mode.

•__HAL_PPP_IS_CLK_ENABLED/__HAL_PPP_IS_CLK_DISABLED to query about the enabled/disabled status of the peripheral clock.

•__HAL_PPP_IS_CLK_SLEEP_ENABLED/__HAL_PPP_IS_CLK_SLEEP_DISABLED to query about the enabled/disabled status of the peripheral clock during Sleep mode.

3.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 stm32g0xx_it.c and implement HAL_GPIO_EXTI_Rising_Callback() and/or HAL_GPIO_EXTI_Falling_Callback().

The table below describes the GPIO_InitTypeDef structure field.

			Table 12. Description of GPIO_InitTypeDef structure

Structure field			Description
Pin	Specifies the GPIO pins to be configured.
Pin	Possible values: GPIO_PIN_x or GPIO_PIN_All, where x[0..15]
	Possible values: GPIO_PIN_x or GPIO_PIN_All, where x[0..15]

	Specifies the operating mode for the selected pins: GPIO mode or EXTI mode.
	Possible values are:
	•	GPIO mode
		–	GPIO_MODE_INPUT : Input floating
		–	GPIO_MODE_OUTPUT_PP : Output push-pull
		–	GPIO_MODE_OUTPUT_OD : Output open drain
		–	GPIO_MODE_AF_PP : Alternate function push-pull
		–	GPIO_MODE_AF_OD : Alternate function open drain
Mode		–	GPIO_MODE_ANALOG : Analog mode
Mode		–	GPIO_MODE_ANALOG_ADC_CONTROL: ADC analog mode
		–	GPIO_MODE_ANALOG_ADC_CONTROL: ADC analog mode
	•	External Interrupt mode
		–	GPIO_MODE_IT_RISING : Rising edge trigger detection
		–	GPIO_MODE_IT_FALLING : Falling edge trigger detection
		–	GPIO_MODE_IT_RISING_FALLING : Rising/Falling edge trigger detection
	•	External Event mode
		–	GPIO_MODE_EVT_RISING : Rising edge trigger detection
		–	GPIO_MODE_EVT_FALLING : Falling edge trigger detection
		–	GPIO_MODE_EVT_RISING_FALLING: Rising/Falling edge trigger detection

	Specifies the Pull-up or Pull-down activation for the selected pins.
	Possible values are:
Pull	GPIO_NOPULL
	GPIO_PULLUP
	GPIO_PULLDOWN

	Specifies the speed for the selected pins
Speed	Possible values are:
Speed	GPIO_SPEED_FREQ_LOW
	GPIO_SPEED_FREQ_LOW
	GPIO_SPEED_FREQ_MEDIUM

UM2319 - Rev 2	page 26/2202

UM2319

HAL system peripheral handling

Structure field	Description

GPIO_SPEED_FREQ_HIGH

GPIO_SPEED_FREQ_VERY_HIGH

Please find below typical GPIO configuration examples:

•Configuring GPIOs as output push-pull to drive external LEDs:

GPIO_InitStruct.Pin = GPIO_PIN_12 | GPIO_PIN_13 | GPIO_PIN_14 | GPIO_PIN_15;

GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;

GPIO_InitStruct.Pull = GPIO_PULLUP;

GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_MEDIUM;

HAL_GPIO_Init(GPIOD, &GPIO_InitStruct);

•Configuring PA0 as external interrupt with falling edge sensitivity:

GPIO_InitStructure.Mode = GPIO_MODE_IT_FALLING;

GPIO_InitStructure.Pull = GPIO_NOPULL;

GPIO_InitStructure.Pin = GPIO_PIN_0;

HAL_GPIO_Init(GPIOA, &GPIO_InitStructure);

3.11.3Cortex® NVIC and SysTick timer

The Cortex® HAL driver, stm32g0xx_hal_cortex.c, provides APIs to handle NVIC and SysTick. The supported APIs include:

•HAL_NVIC_SetPriority()/ HAL_NVIC_SetPriorityGrouping()

•HAL_NVIC_GetPriority() / HAL_NVIC_GetPriorityGrouping()

•HAL_NVIC_EnableIRQ()/HAL_NVIC_DisableIRQ()

•HAL_NVIC_SystemReset()

•HAL_SYSTICK_IRQHandler()

•HAL_NVIC_GetPendingIRQ() / HAL_NVIC_SetPendingIRQ () / HAL_NVIC_ClearPendingIRQ()

•HAL_NVIC_GetActive(IRQn)

•HAL_SYSTICK_Config()

•HAL_SYSTICK_CLKSourceConfig()

•HAL_SYSTICK_Callback()

3.11.4PWR

The PWR HAL driver handles power management. The features shared between all STM32 Series are listed below:

•PVD configuration, enabling/disabling and interrupt handling

–HAL_PWR_ConfigPVD() (kept for compatibility with other Series but identical to HAL_PWREx_ConfigPVD())

–HAL_PWR_EnablePVD() / HAL_PWR_DisablePVD() (kept for compatibility with other Series but identical to HAL_PWREx_EnablePVD() / HAL_PWREx_DisablePVD())

–HAL_PWR_PVD_IRQHandler() (kept for compatibility with other Series but identical to HAL_PWREx_PVD_IRQHandler() and HAL_PWREx_PVD_PVM_IRQHandler() depending on the device used)

•Wakeup pin configuration

–HAL_PWR_EnableWakeUpPin() / HAL_PWR_DisableWakeUpPin()

•Low-power mode entry

–HAL_PWR_EnterSLEEPMode()

–HAL_PWR_EnterSTOPMode()

–HAL_PWR_EnterSTANDBYMode()

UM2319 - Rev 2	page 27/2202

UM2319

HAL system peripheral handling

•STM32G0 low-power management features:

–HAL_PWREx_EnableLowPowerRunMode()

–HAL_PWREx_DisableLowPowerRunMode()

–HAL_PWREx_PVD_Rising_Callback() (identical to HAL_PWREx_PVD_PVM_Rising_Callback())

–HAL_PWREx_PVD_Falling_Callback() (identical to HAL_PWREx_PVD_PVM_Falling_Callback())

–HAL_PWREx_EnterSHUTDOWNMode()

3.11.5EXTI

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	Description

	Enables a given EXTI line interrupt
__HAL_PPP_{SUBLOCK}__EXTI_ENABLE_IT()	Example:
	__HAL_PWR_PVD_EXTI_ENABLE_IT()

	Disables a given EXTI line.
__HAL_PPP_{SUBLOCK}__EXTI_DISABLE_IT()	Example:
	__HAL_PWR_PVD_EXTI_DISABLE_IT()

	Gets a given EXTI line interrupt flag pending bit status.
__HAL_ PPP_{SUBLOCK}__EXTI_GET_FLAG()	Example:
	__HAL_PWR_PVD_EXTI_GET_FLAG()

	Clears a given EXTI line interrupt flag pending bit.
__HAL_ PPP_{SUBLOCK}_EXTI_CLEAR_FLAG()	Example;
	__HAL_PWR_PVD_EXTI_CLEAR_FLAG()

	Generates a software interrupt for a given EXTI line.
__HAL_ PPP_{SUBLOCK}_EXTI_GENERATE_SWIT()	Example:
	__HAL_PWR_PVD_EXTI_ GENERATE_SWIT ()

	Enable a given EXTI line event
__HAL_PPP_SUBBLOCK_EXTI_ENABLE_EVENT()	Example:
	__HAL_RTC_WAKEUP_EXTI_ENABLE_EVENT()

	Disable a given EXTI line event
__HAL_PPP_SUBBLOCK_EXTI_DISABLE_EVENT()	Example:
	__HAL_RTC_WAKEUP_EXTI_DISABLE_EVENT()

__HAL_ PPP_SUBBLOCK_EXTI_ENABLE_RISING_EDGE()	Configure an EXTI Interrupt or Event on rising edge

__HAL_ PPP_SUBBLOCK_EXTI_ENABLE_FALLING_EDGE()	Enable an EXTI Interrupt or Event on Falling edge

__HAL_ PPP_SUBBLOCK_EXTI_DISABLE_RISING_EDGE()	Disable an EXTI Interrupt or Event on rising edge

__HAL_ PPP_SUBBLOCK_EXTI_DISABLE_FALLING_EDGE()	Disable an EXTI Interrupt or Event on Falling edge

__HAL_ PPP_SUBBLOCK_EXTI_ENABLE_RISING_FALLING_EDGE()	Enable an EXTI Interrupt or Event on Rising/Falling edge

__HAL_ PPP_SUBBLOCK_EXTI_DISABLE_RISING_FALLING_EDGE()	Disable an EXTI Interrupt or Event on Rising/Falling edge

UM2319 - Rev 2	page 28/2202

UM2319

HAL system peripheral handling

If the EXTI interrupt mode is selected, the user application must call HAL_PPP_FUNCTION_IRQHandler() (for example HAL_PWR_PVD_IRQHandler()), from stm32g0xx_it.c file, and implement HAL_PPP_FUNCTIONCallback() callback function (for example HAL_PWR_PVDCallback().

3.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

•Hardware request connected to the peripheral

Two operating modes are available:

•Polling mode I/O operation

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.

•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 must be done in the HAL_PPP_MspInit()
	callback. In addition, the user application must 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.

UM2319 - Rev 2	page 29/2202

UM2319

How to use HAL drivers

3.12How to use HAL drivers

3.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.

Figure 7. HAL driver model

stm32g0xxx_it.c

DMAx_IRQHandler

PPP_IRQHandler

hal_msp.c		app.c/main.c		stm32g0xxx_hal_ppp.c		Services

1. Declare PPP handle		stm32g0xx_hal_gpio.c/h
1. Declare PPP handle
2. Init handle Params
3. Call HAL_PPP_init()		stm32g0xx_hal_rcc.c/h
	HAL_PPP_Init()	stm32g0xx_hal_rcc.c/h
	HAL_PPP_Init()
HAL_PPP_Mspinit()		stm32g0xx_hal_nvic.c/h
HAL_PPP_Mspinit()
		stm32g0xx_hal_dma.c/h
Calll HAL_PPP_Process()	HAL_PPP_Process()
	Interrupt	DMA model
	model
Hal_PPP_ProcessCpltCallBack()
Hal_PPP_ErrorCallBack()
Calll HAL_PPP_DeInit()
	HAL_PPP_DeInit()
HAL_PPP_MspDeinit()

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.

3.12.2HAL initialization

3.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 stm32g0xx_hal.c.

UM2319 - Rev 2	page 30/2202

+ 2172 hidden pages

STMicroelectronics STM32G0 HAL User Manual

General information

Acronyms and definitions

Overview of HAL drivers

HAL and user-application files

3.1.1HAL driver files

Table 3. User-application files

HAL data structures

•Peripheral handle structures

3.2.2Initialization and configuration structure

3.2.3Specific process structures

API classification

Devices supported by HAL drivers

HAL driver rules

3.5.1HAL API naming rules

3.5.2HAL general naming rules

HAL generic APIs

3.5.3HAL interrupt handler and callback functions

HAL extension APIs

3.7.1HAL extension model overview

3.7.2HAL extension model cases

File inclusion model

HAL common resources

3.10HAL configuration

HAL system peripheral handling

3.11.1Clocks

3.11.2GPIOs

3.11.5EXTI

How to use HAL drivers

3.12.1HAL usage models

3.12.2HAL initialization

3.12.2.1HAL global initialization