HAL Library File Usage Analysis

HAL driver files

File	Description
Stm32f4xx_hal_ppp.c	Main peripheral/module driver file. It includes the APIs that is 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 DEFA Ult Generic APIs If the internal process is a implemented in different.
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 par T number specific APIs
Stm32f4xx_ll_ppp.c	Peripheral low layer driver so 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 is not accessible directly. They is 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 a intrinsic add-on of the HAL driver that Is isn't 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 is 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 A Pplication.
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 are called at startup just after reset and before branching to the main program. It does not configure the system clock in startup (contrary to the standard library). The 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 a 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 ti Me intervals to increment a local variable (declared in Stm32f4x x_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 a 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, allows working with several IP instances simultaneous.

ppp_handletypedef *handle is the main structure, that's 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 have 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 is re-entrant and avoid using global vari Ables because a subroutine can fail to is reentrant if they rely on a global variable to remain unchanged and that variabl E is modified when the subroutine is recursively invoked. For this reason, the following rules is 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 the hardware status to work with (e.g. serial port Rea D buffer) which is isn't only global, but volatile. Still, typical use of the static variables and global data are not advised, in the sense this only atomic read-modify-write ins Tructions should is used in these variables. It should not being possible for a 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 Handl E for each process are 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 is the following:

· GPIO

· SYSTICK

· NVIC

· PWR

· RCC

· FLASH.

Initialization and configuration structure

These structures was defined in the generic driver header file when it was common to all part numbers. When they can change from one part number to another, the structures is defined in the extension header file for each par T 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 is used for specific process (common APIs). They is defined in the generic driver header file.

Example:

Hal_ppp_process (ppp_handletypedef* hadc,ppp_processconfig* sconfig)

API classification

The HAL APIs is classified into three categories:

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

· Extension APIs: This set of APIs is divided into and sub-categories:

- Family specific APIs: APIs applying to a given Family. They is 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 are delimited by the device Part number define statement. It is located in the corresponding extension header C file.

HAL Library File Usage Analysis