HAL 库文件使用分析

HAL driver files

File	Description
stm32f4xx_hal_ppp.c	Main peripheral/module driver file. It includes the APIs that are common to all STM32 devices.
stm32f4xx_hal_ppp.h	Header file of the main driver C file. It includes common data, handle and enumeration structures, define statements and macros, as well as the exported generic APIs.
stm32f4xx_hal_ppp_ex.c	Extension file of a peripheral/module driver. It includes the specific APIs for a given part number or family, as well as the newly defined APIs that overwrite the default generic APIs if the internal process is implemented in different way.
stm32f4xx_hal_ppp_ex.h	Header file of the extension C file. It includes the specific data and enumeration structures, define statements and macros, as well as the exported device part number specific APIs
stm32f4xx_ll_ppp.c	Peripheral low layer driver that can be accessed from one or more HAL drivers. It offers a set of APIs and services used by the upper driver. From the user point of view, low-level drivers are not accessible directly. They are used only by the HAL drivers built upon them.
stm32f4xx_ll_ppp.h	Header file of the low layer C file. It is included in the HAL driver header file, thus making the low-level driver an intrinsic add-on of the HAL driver that is not visible from the application.
stm32f4xx_hal.c	This file is used for HAL initialization and contains DBGMCU, Remap and Time Delay based on systick APIs.
stm32f4xx_hal.h	stm32f4xx_hal.c header file
stm32f4xx_hal_msp_template.c	Template file to be copied to the user application folder. It contains the MSP initialization and de-initialization (main routine and callbacks) of the peripheral used in the user application.
stm32f4xx_hal_conf_template.h	Template file allowing to customize the drivers for a given application.
stm32f4xx_hal_def.h	Common HAL resources such as common define statements, enumerations, structures and macros.

User-application files

File	Description
system_stm32f4xx.c	This file contains SystemInit() which is called at startup just after reset and before branching to the main program. It does not configure the system clock at startup (contrary to the standard library). This is to be done using the HAL APIs in the user files. It allows to : · relocate the vector table in internal SRAM. · configure FSMC/FMC peripheral (when available) to use as data memory the external SRAM or SDRAM mounted on the evaluation board.
startup_stm32f4xx.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.
stm32f4xx_flash.icf (optional)	Linker file for EWARM toolchain allowing mainly to adapt the stack/heap size to fit the application requirements.
stm32f4xx_hal_msp.c	This file contains the MSP initialization and de-initialization (main routine and callbacks) of the peripheral used in the user application.
stm32f4xx_hal_conf.h	This file allows the user to customize the HAL drivers for a specific application. It is not mandatory to modify this configuration. The application can use the default configuration without any modification.
stm32f4xx_it.c/.h	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 stm32f4xx_hal.c) used as HAL timebase. By default, this function is called each 1ms in Systick ISR. . The PPP_IRQHandler() routine must call HAL_PPP_IRQHandler() if an interrupt based process is used within the application.
main.c/.h	This file contains the main program routine, mainly: · the call to HAL_Init() · assert_failed() implementation · system clock configuration · peripheral HAL initialization and user application code.

HAL data structures

Each HAL driver can contain the following data structures:

· Peripheral handle structures

· Initialization and configuration structures

· Specific process structures.

Peripheral handle structures

The APIs have a modular generic multi-instance architecture that allows working with several IP instances simultaneous.

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.

1) The multi-instance feature implies that all the APIs used in the application are re-entrant and avoid using global variables because a subroutine 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:

· Re-entrant code does not hold any static (or global) non-constant data: reentrant functions can work with global data. For example, a re-entrant interrupt service routine can grab a piece of hardware status to work with (e.g. 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.

Initialization and configuration structure

These structures are defined in the generic driver header file when it is common to all part numbers. When they can change from one part number to another, the structures are defined in the extension header file for each part number.

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)

API classification

The HAL APIs are classified into three categories:

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

· 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).

extension file and delimited by specific define statements relative to a given part

number.

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.