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
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
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
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
3.1HAL and user-application 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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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). |
|
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. |
|
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 |
|
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
Figure 1. Example of project template
3.2HAL data structures
Each HAL driver can contain the following data 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
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)
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
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
3.4Devices supported by HAL drivers
UM2319 - Rev 2 |
page 14/2202 |
|
|
<![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 |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_adc.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_adc_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_cec.c |
Yes |
Yes |
No |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_comp.c |
Yes |
Yes |
No |
Yes |
Yes |
No |
Yes |
Yes |
Yes |
No |
No |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_cortex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_crc.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_crc_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_cryp.c |
Yes |
No |
No |
Yes |
No |
No |
Yes |
No |
No |
Yes |
No |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_cryp_ex.c |
Yes |
No |
No |
Yes |
No |
No |
Yes |
No |
No |
Yes |
No |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_dac.c |
Yes |
Yes |
No |
Yes |
Yes |
No |
Yes |
Yes |
No |
No |
No |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_dac_ex.c |
Yes |
Yes |
No |
Yes |
Yes |
No |
Yes |
Yes |
No |
No |
No |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_dma.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_dma_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_exti.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_fdcan.c |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_flash.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_flash_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_gpio.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_hcd.c |
Yes |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_i2c.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_i2c_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_i2s.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_irda.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_iwdg.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_lptim.c |
Yes |
Yes |
No |
Yes |
Yes |
No |
Yes |
Yes |
No |
Yes |
Yes |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_msp_template.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_pcd.c |
Yes |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_pcd_ex.c |
Yes |
Yes |
Yes |
No |
No |
No |
No |
No |
No |
No |
No |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_pwr.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_pwr_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
<![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 |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_rcc_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_rng.c |
Yes |
No |
No |
Yes |
No |
No |
Yes |
No |
No |
Yes |
No |
No |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_rtc.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_rtc_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_smartcard.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_smartcard_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_smbus.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_spi.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_spi_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_tim.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_tim_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_uart.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_uart_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_usart.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_usart_ex.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
stm32g0xx_hal_wwdg.c |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<![if ! IE]> <![endif]>16/2202 page |
<![if ! IE]> <![endif]>UM2319 drivers HAL by supported Devices |
UM2319
3.5HAL driver 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 |
|
|
||
|
|
|
||
|
|
|
|
|
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 |
||||
|
|
|
||
|
|
|
|
|
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
•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__) |
|
|
|
|
|
|
|
|
__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 __) |
|
|
|
|
|
|
|
•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
•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)
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
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 |
|
|
resources (clocks, GPIO, AF..) |
||
|
|
||
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 |
|
|
used |
||
|
|
||
|
|
|
|
|
HAL_ADC_Stop () |
This function stops ADC conversions when the polling method is |
|
|
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 |
|
used |
|||
|
|||
|
|
|
|
|
HAL_ADC_Stop_IT() |
This function stops ADC conversions when the interrupt method is |
|
|
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 |
|
|
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 |
|
|
DMA transfer error occurred |
||
|
|
||
|
|
|
|
|
HAL_ADC_ConfigChannel() |
This function configures the selected ADC regular channel, the |
|
Control group |
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 |
flow states. |
||
|
|||
|
|
||
group |
HAL_ADC_GetError() |
This fuction allows getting in run time the error that occurred during |
|
|
|||
|
IT routine |
||
|
|
||
|
|
|
3.7HAL extension APIs
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 |
|
|
|
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 |
|
|
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
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
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)
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. |
|
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
Configuration item |
Description |
Default Value |
|
HSI48_VALUE |
Defines the value of the Internal High Speed oscillator for USB |
|
|
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 |
|
expressed in Hz. |
|||
|
|
||
|
|
|
|
LSE_VALUE |
Defines the value of the external oscillator (LSE) expressed in Hz. |
|
|
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) |
|||
|
|
||
|
|
|
|
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.
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.
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. |
|||
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 |
|
|
– |
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: |
|||
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()
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
3.12How to use HAL drivers
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
or
PPP_IRQHandler
hal_msp.c |
|
app.c/main.c |
|
stm32g0xxx_hal_ppp.c |
|
Services |
|
|
|
|
|
|
|
1. Declare PPP handle |
|
stm32g0xx_hal_gpio.c/h |
|
|
|
2. Init handle Params |
|
|
3. Call HAL_PPP_init() |
|
stm32g0xx_hal_rcc.c/h |
|
HAL_PPP_Init() |
|
|
|
|
HAL_PPP_Mspinit() |
|
stm32g0xx_hal_nvic.c/h |
|
|
|
|
|
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. |
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 |
|
|