Description of STM32F4 HAL and low-layer drivers - User …

1 IntroductionSTM32 Cube is an STMicroelectronics original initiative to significantly improve developer productivity by reducing developmenteffort, time and cost. STM32 Cube covers the STM32 includes: STM32 CubeMX, a graphical software configuration tool that allows the generation of C initialization code using graphicalwizards. A comprehensive embedded software platform, delivered per Series (such as STM32 CubeF4 for STM32F4 Series) The STM32 Cube HAL, STM32 abstraction layer embedded software ensuring maximized portability across theSTM32 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. LLAPIs are available only for a set of peripherals. A consistent set of middleware components such as RTOS, USB, TCP/IP and Graphics.

2 All embedded software utilities, delivered with a full set of HAL driver layer provides a simple, generic multi-instance set of APIs (application programming interfaces) to interactwith the upper layer (application, libraries and stacks). The HAL driver APIs are split into two categories: generic APIs, whichprovide common and generic functions for all the STM32 series and extension APIs, which include specific and customizedfunctions for a given line or part number. The HAL drivers include a complete set of ready-to-use APIs that simplify the userapplication 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 arefeature-oriented 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).

3 The HAL driver layer implements run-time failure detection bychecking the input values of all functions. Such dynamic checking enhances the firmware robustness. Run-time detection is alsosuitable for user application development and LL drivers offer hardware services based on the available features of the STM32 peripherals. These services reflect exactlythe hardware capabilities, and provide atomic operations that must be called by following the programming model described inthe product line reference manual. As a result, the LL services are not based on standalone processes and do not require anyadditional memory resources to save their states, counter or data pointers. All operations are performed by changing the contentof the associated peripheral registers. Unlike the HAL, LL APIs are not provided for peripherals for which optimized access isnot a key feature, or for those requiring heavy software configuration and/or a complex upper-level stack (such as USB).

4 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 peripheralcomplexity from the end-user. The LL offers low-level APIs at register level, with better optimization but less portability. These require deep knowledge ofthe MCU and peripheral HAL- and LL-driver source code is developed in Strict ANSI-C, which makes it independent of the development tools. It ischecked with the CodeSonar static analysis tool. It is fully is compliant with MISRA C :2004 standard. Description of STM32F4 HAL and low-layer driversUM1725 User manualUM1725 - Rev 7 - June 2021 For further information contact your local STMicroelectronics sales 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 buildyour applicationUM1725UM1725 - Rev 7page 2/21231 General informationThe STM32 CubeF4 MCU Package runs on STM32F4 32-bit microcontrollers based on the Arm Cortex :Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or informationUM1725 - Rev 7page 3/21232 Acronyms and definitionsTable 1.

5 Acronyms and definitionsAcronymDefinitionADCA nalog-to-digital converterAESA dvanced encryption standardANSIA merican national standards instituteAPIA pplication programming interfaceBSPB oard support packageCANC ontroller area networkCECC onsumer electronic controllerCMSISC ortex microcontroller software interface standardCOMPC omparatorCORDICT rigonometric calculation unitCPUC entral processing unitCRCCRC calculation unitCRYPC ryptographic processorCSSC lock security systemDACD igital to analog converterDLYBD elay blockDCMID igital camera interfaceDFSDMD igital filter sigma delta modulatorDMAD irect memory accessDMAMUXD irect memory access request multiplexerDSID isplay serial interfaceDTSD igital temperature sensorESES ecurity enable Flash user option bitETHE thernet controllerEXTIE xternal interrupt/event controllerFDCANF lexible data-rate controller area network unitFLASHF lash memoryFMACF iltering mathematical calculation unitFMCF lexible memory controllerFWFirewallGFXMMUC hrom-GRCGPIOG eneral purpose I/OsGTZCG lobal security controllerGTZC-MPCBBGTZC block-based memory protection controllerGTZC-MPCWMGTZC watermark memory protection controllerGTZC-TZICS ecurity illegal access controllerGTZC-TZSCS ecurity access controllerUM1725 Acronyms and definitionsUM1725 - Rev 7page 4/2123 AcronymDefinitionHALH ardware abstraction layerHASHHash processorHCDUSB host controller driverHRTIMHigh-resolution timerI2 CInter-integrated circuitI2 SInter-integrated soundICACHEI nstruction cacheIRDAI nfrared data associationIWDGI ndependent watchdogJPEGJ oint photographic experts groupLCDL iquid crystal display controlerLTDCLCD TFT display controllerLPTIMLow-power timerLPUARTLow-power universal

6 Asynchronous receiver/transmitterMCOM icrocontroller clock outputMDIOSM anagement data input/output (MDIO) slaveMDMAM aster direct memory accessMMCM ultiMediaCardMPUM emory protection unitMSPMCU specific packageNANDNAND Flash memoryNORNOR Flash memoryNVICN ested vectored interrupt controllerOCTOSPIOcto-SPI interfaceOPAMPO perational amplifierOTFDECOn-the-fly decryption engineOTG-FSUSB on-the-go full-speedPKAP ublic key acceleratorPCDUSB peripheral controller driverPPPSTM32 peripheral or blockPSSIP arallel synchronous slave interfacePWRP ower controllerQSPIQuad-SPI Flash memoryRAMECCRAM ECC monitoringRCCR eset and clock controllerRNGR andom number generatorRTCReal-time clockSAIS erial audio interfaceSDSecure digitalSDMMCSD/SDIO/MultiMediaCard card host interfaceSMARTCARDS martcard ICUM1725 Acronyms and definitionsUM1725 - Rev 7page 5/2123 AcronymDefinitionSMBUSS ystem management busSPIS erial peripheral interfaceSPDIFRXSPDIF-RX Receiver

7 InterfaceSRAMSRAM external memorySWPMIS erial wire protocol master interfaceSysTickSystem tick timerTIMA dvanced-control, general-purpose or basic timerTSCT ouch sensing controllerUARTU niversal asynchronous receiver/transmitterUCPDUSB Type-C and Power Delivery interfaceUSARTU niversal synchronous receiver/transmitterVREFBUFV oltage reference bufferWWDGW indow watchdogUSBU niversal serial busUM1725 Acronyms and definitionsUM1725 - Rev 7page 6/21233 Overview of HAL driversThe HAL drivers are designed to offer a rich set of APIs and to interact easily with the application upper driver consists of a set of functions covering the most common peripheral features. The development ofeach driver is driven by a common API which standardizes the driver structure, the functions and the HAL drivers include a set of driver modules, each module being linked to a standalone peripheral.

8 However,in some cases, the module is linked to a peripheral functional mode. As an example, several modules exist forthe USART peripheral: UART driver module, USART driver module, SMARTCARD driver module and IRDA HAL main features are the following: Cross-family portable set of APIs covering the common peripheral features as well as extension APIs incase 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 levelInitialization/De-Initialization (clock, GPIOs, interrupt, DMA) Peripherals interrupt events Error events Object locking mechanism: safe hardware access to prevent multiple spurious accesses to sharedresources.

9 Timeout used for all blocking processes: the timeout can be a simple counter or a of HAL driversUM1725 - Rev 7page 7 and user-application driver filesHAL drivers are composed of the following set of files:Table 2. HAL driver peripheral/module driver fileIt includes the APIs that are common to all STM32 : , file of the main driver C fileIt includes common data, handle and enumeration structures, define statements andmacros, as well as the exported generic , file of a peripheral/module driver. It includes the specific APIs for a given partnumber or family, as well as the newly defined APIs that overwrite the default generic APIs ifthe internal process is implemented in different , file of the extension C fileIt includes the specific data and enumeration structures, define statements and macros, aswell as the exported device part number specific APIsExample.

10 , file is used for HAL initialization and contains DBGMCU, Remap and Time Delay basedon SysTick header file to be copied to the user application folderIt contains the MSP initialization and de-initialization (main routine and callbacks) of theperipheral used in the user file allowing to customize the drivers for a given HAL resources such as common define statements, enumerations, structures filesThe minimum files required to build an application using the HAL are listed in the table below:Table 3. User-application file contains SystemInit() that is called at startup just after reset and before branching to themain 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 ininternal SRAM and configuring the FSMC/FMC (when available) to use the external SRAM orSDRAM mounted on the evaluation board as data specific file that contains reset handler and exception some toolchains, it allows adapting the stack/heap size to fit the application (optional)Linker file for EWARM toolchain allowing mainly adapting the stack/heap size to fit the file contains the MSP initialization and de-initialization (main routine and callbacks) of theperipheral used in the user and user-application filesUM1725 - Rev 7page 8 file allows the user to customize the HAL drivers for a specific is not mandatory to modify this configuration.