STM32Cube HAL库：提高开发者效率的全方位解决方案

需积分: 44 76 浏览量更新于2024-07-09 5 收藏 8.36MB PDF 举报

STM32 HAL库使用手册是一份详细的文档，由STMicroelectronics推出，旨在显著提升开发者在STM32系列芯片上的开发效率、时间和成本效益。该文档涵盖了STM32系列产品的核心组件，包括STM32CubeMX图形配置工具，这是一个图形化软件，通过魔术师般的向导帮助生成C语言的初始化代码。 STM32 Cube平台的核心组成部分是STM32 HAL（Hardware Abstraction Layer），这是一种嵌入式软件层，旨在实现跨STM32产品系列的高度可移植性。HAL提供了广泛的API接口，覆盖了所有可用的外设，使得开发者能够以统一的方式访问硬件功能，无需关注底层细节，从而简化了应用程序的开发过程。这些API设计简洁且通用，支持多实例操作，便于与上层应用、库和堆栈进行交互。除了HAL，STM32 Cube还提供了低层API (LL)。LL API更加轻量级且专家导向，它们更接近硬件，但仅针对特定的外设集。这对于对性能有较高要求或对特定功能有深入理解的开发者来说是一个有用的补充。此外，文档还提及了一系列一致的中间件组件，如实时操作系统（RTOS）、USB、TCP/IP和图形处理等，这些都增强了系统的功能性，并为开发者提供了全面的解决方案。 STM32 Cube平台还包括一系列嵌入式软件实用工具，附带了大量的示例代码，有助于新用户快速入门和熟练掌握。通过使用这些工具和库，开发者可以专注于核心业务逻辑，而无需过多关注底层硬件的具体实现，从而提高了开发效率和产品质量。总结来说，STM32 HAL库使用手册为STM32系列的软件开发人员提供了一个强大的工具箱，它通过抽象硬件接口、提供多层API和中间件，降低了编程复杂性，推动了STM32系列产品的广泛应用和创新。无论是初次接触STM32的开发者还是经验丰富的工程师，这份手册都是提高工作效率和项目成功率的重要参考资料。

3.5 HAL driver rules

3.5.1 HAL API naming rules

The following naming rules are used in HAL drivers:

Table 6. HAL API naming rules

Generic Family specific Device specific

File names stm32f4xx_hal_ppp (c/h) stm32f4xx_hal_ppp_ex (c/h) stm32f4xx_ hal_ppp_ex (c/h)

Module

name

HAL_PPP_ MODULE

Function

name

HAL_PPP_Function

HAL_PPP_FeatureFunction_MODE

HAL_PPPEx_Function

HAL_PPPEx_FeatureFunction_MODE

HAL_PPPEx_Function

HAL_PPPEx_FeatureFunction_MODE

Handle

name

PPP_HandleTypedef NA NA

Init

structure

name

PPP_InitTypeDef NA PPP_InitTypeDef

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 STM32F4 reference manuals.

• Peripheral registers are declared in the PPP_TypeDef structure (for example ADC_TypeDef) in the

stm32f2xxx.h header file:

stm32f4xxx.h corresponds to stm32f401xc.h, stm32f401xe.h, stm32f405xx.h, stm32f415xx.h,

stm32f407xx.h, stm32f417xx.h, stm32f427xx.h, stm32f437xx.h, stm32f429xx.h, stm32f439xx.h,

stm32f446xx.h, stm32f469xx.h, stm32f479xx.h, stm32f410cx.h, stm32f410tx.h, stm32f410rx.h,

stm32f412cx.h, stm32f412rx.h, stm32f412vx.h or stm32f412zx.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().

UM1725

HAL driver rules

UM1725 - Rev 7

page 16/2123

• The Feature prefix should refer to the new feature.

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

3.5.2 HAL general naming rules

• For the shared and system peripherals, no handle or instance object is used. This rule applies to the

following peripherals:

– GPIO

– SYSTICK

– NVIC

– RCC

– FLASH

Example: The HAL_GPIO_Init() requires only the GPIO address and its configuration parameters.

HAL_StatusTypeDef HAL_GPIO_Init (GPIO_TypeDef* GPIOx, GPIO_InitTypeDef *Init)

{

/*GPIO Initialization body */

}

• The macros that handle interrupts and specific clock configurations are defined in each peripheral/module

driver. These macros are exported in the peripheral driver header files so that they can be used by the

extension file. The list of these macros is defined below:

Note: This list is not exhaustive and other macros related to peripheral features can be added, so that they can be

used in the user application.

Table 7. Macros handling interrupts and specific clock configurations

Macros

Description

__HAL_PPP_ENABLE_IT(__HANDLE__, __INTERRUPT__) Enables a specific peripheral interrupt

__HAL_PPP_DISABLE_IT(__HANDLE__,

__INTERRUPT__)

Disables a specific peripheral interrupt

__HAL_PPP_GET_IT (__HANDLE__, __ INTERRUPT __) Gets a specific peripheral interrupt status

__HAL_PPP_CLEAR_IT (__HANDLE__, __ INTERRUPT __) Clears a specific peripheral interrupt status

__HAL_PPP_GET_FLAG (__HANDLE__, __FLAG__) Gets a specific peripheral flag status

__HAL_PPP_CLEAR_FLAG (__HANDLE__, __FLAG__) Clears a specific peripheral flag status

__HAL_PPP_ENABLE(__HANDLE__) Enables a peripheral

__HAL_PPP_DISABLE(__HANDLE__) Disables a peripheral

__HAL_PPP_XXXX (__HANDLE__, __PARAM__) Specific PPP HAL driver macro

__HAL_PPP_GET_ IT_SOURCE (__HANDLE__, __

INTERRUPT __)

Checks the source of specified interrupt

• NVIC and SYSTICK are two Arm

Cortex

core features. The APIs related to these features are located in

the stm32f4xx_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;

}

UM1725

HAL driver rules

UM1725 - Rev 7

page 17/2123

• 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.3 HAL interrupt handler and callback functions

Besides the APIs, HAL peripheral drivers include:

• HAL_PPP_IRQHandler() peripheral interrupt handler that should be called from stm32f4xx_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

HAL_PPP_MspInit() / _DeInit()

Example: HAL_USART_MspInit()

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

(GPIOs, clock, DMA, interrupt)

HAL_PPP_ProcessCpltCallback

Example: HAL_USART_TxCpltCallback

Called by peripheral or DMA interrupt handler when the process completes

HAL_PPP_ErrorCallback

Example: HAL_USART_ErrorCallback

Called by peripheral or DMA interrupt handler when an error occurs

3.6 HAL generic APIs

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

APIs groups:

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

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

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

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

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

implementation.

Example: in the timer driver, the API grouping is based on timer features (such as PWM, OC and IC).

The initialization and de-initialization functions allow initializing a peripheral and configuring the low-

level resources, mainly clocks, GPIO, alternate functions (AF) and possibly DMA and interrupts. The

HAL_DeInit()function restores the peripheral default state, frees the low-level resources and removes any direct

dependency with the hardware.

The IO operation functions perform a row access to the peripheral payload data in write and read modes.

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

mode.

UM1725

HAL generic APIs

UM1725 - Rev 7

page 18/2123

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

Initialization group

HAL_ADC_Init()

This function initializes the peripheral and configures the low -level

resources (clocks, GPIO, AF..)

HAL_ADC_DeInit()

This function restores the peripheral default state, frees the low-

level resources and removes any direct dependency with the

hardware.

IO operation group

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

HAL_ADC_PollForConversion()

This function allows waiting for the end of conversions when the

polling method is used. In this case, a timout value is specified by

the user according to the application.

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

Control group

HAL_ADC_ConfigChannel()

This function configures the selected ADC regular channel, the

corresponding rank in the sequencer and the sample time

HAL_ADC_AnalogWDGConfig This function configures the analog watchdog for the selected ADC

State and Errors

group

HAL_ADC_GetState()

This function allows getting in run time the peripheral and the data

flow states.

HAL_ADC_GetError()

This fuction allows getting in run time the error that occurred during

IT routine

3.7 HAL extension APIs

3.7.1 HAL extension model overview

The extension APIs provide specific functions or overwrite modified APIs for a specific family (series) or specific

part number within the same family.

The extension model consists of an additional file, stm32f4xx_hal_ppp_ex.c, that includes all the specific

functions and define statements (stm32f4xx_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_InjectedStart()

This function starts injected channel ADC conversions when

the polling method is used

HAL_ADCEx_InjectedStop()

This function stops injected channel ADC conversions when

the polling method is used

UM1725

HAL extension APIs

UM1725 - Rev 7

page 19/2123

剩余2122页未读，继续阅读

weixin_54445417

粉丝: 0
资源: 1

STM32Cube HAL库：提高开发者效率的全方位解决方案

STM32HAL库函数用户手册.pdf

STM32 HAL库函数说明手册

STM32入门教程(HAL库).pdf

stm32hal库开发手册pdf

stm32f4hal库开发手册pdf

stm32 f1系列hal库使用手册文档翻译.pdf

stm32L476HAL库编程手册和STM32标准库编程手册以及MSP430编程手册下载

stm32f4 hal库中文手册下载

stm32 hal教程 pdf

stm32L476HAL库中文编程手册和STM32标准库中文编程手册以及MSP430中文编程手册下载

最新资源