October 2015

DOCID028236 Rev 1

1/692

www.st.com

UM1940

User Manual

Description of STM32F2xx HAL drivers

Introduction

STMCube

is an STMicroelectronics original initiative to ease developers life by reducing development

efforts, time and cost. STM32Cube covers STM32 portfolio.

STM32Cube Version 1.x includes:

 The STM32CubeMX, a graphical software configuration tool that allows generating C initialization

code using graphical wizards.

 A comprehensive embedded software platform, delivered per series (such asSTM32CubeF2 for

stm32f2 series)

 The STM32Cube HAL, an STM32 abstraction layer embedded software, ensuring maximized

portability across STM32 portfolio

 A consistent set of middleware components such as RTOS, USB, TCP/IP, Graphics

 All embedded software utilities coming with a full set of examples.

The HAL drivers layer provides a generic multi instance simple set of APIs (application programming

interfaces) to interact with the upper layer (application, libraries and stacks). It is composed of generic

and extension APIs. It is directly built around a generic architecture and allows the built-upon layers,

such as the middleware layer, to implement their functions without knowing in-depth how to use the

MCU. This structure improves the library code reusability and guarantees an easy portability on other

devices.

The HAL drivers include a complete set of ready-to-use APIs which simplify the user application

implementation. As an example, the communication peripherals contain APIs to initialize and configure

the peripheral, to manage data transfers based on polling, to handle interrupts or DMA, and to manage

communication errors.

The HAL drivers 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 family or part number.

The HAL drivers are feature-oriented instead of IP-oriented. As an example, the timer APIs are split into

several categories following the functions offered by the IP: basic timer, capture, pulse width modulation

(PWM), etc..

The drivers source code is developed in Strict ANSI-C which makes it independent from the

development tools. It is checked with CodeSonar

static analysis tool. It is fully documented and is

MISRA-C 2004 compliant.

The HAL drivers layer implements run-time failure detection by checking the input values of all

functions. Such dynamic checking contributes to enhance the firmware robustness. Run-time detection

is also suitable for user application development and debugging.

This user manual is structured as follows:

 Overview of the HAL drivers

 Detailed description of each peripheral driver: configuration structures, functions, and how to use

the given API to build your application.

Contents

UM1940

2/692

DOCID028236 Rev 1

Contents

1 Acronyms and definitions ............................................................. 41

2 Overview of HAL drivers ............................................................... 43

2.1 HAL and user-application files......................................................... 43

2.1.1 HAL driver files ................................................................................. 43

2.1.2 User-application files ........................................................................ 45

2.2 HAL data structures ........................................................................ 46

2.2.1 Peripheral handle structures ............................................................ 46

2.2.2 Initialization and configuration structure ........................................... 48

2.2.3 Specific process structures .............................................................. 48

2.3 API classification ............................................................................. 48

2.4 Devices supported by HAL drivers .................................................. 49

2.5 HAL drivers rules ............................................................................. 50

2.5.1 HAL API naming rules ...................................................................... 50

2.5.2 HAL general naming rules ................................................................ 51

2.5.3 HAL interrupt handler and callback functions ................................... 53

2.6 HAL generic APIs ............................................................................ 53

2.7 HAL extension APIs ........................................................................ 55

2.7.1 HAL extension model overview ........................................................ 55

2.7.2 HAL extension model cases ............................................................. 55

2.8 File inclusion model ......................................................................... 57

2.9 HAL common resources .................................................................. 57

2.10 HAL configuration ............................................................................ 58

2.11 HAL system peripheral handling ..................................................... 60

2.11.1 Clock ................................................................................................. 60

2.11.2 GPIOs ............................................................................................... 60

2.11.3 Cortex NVIC and SysTick timer ........................................................ 62

2.11.4 PWR ................................................................................................. 62

2.11.5 EXTI .................................................................................................. 62

2.11.6 DMA .................................................................................................. 63

2.12 How to use HAL drivers .................................................................. 65

2.12.1 HAL usage models ........................................................................... 65

2.12.2 HAL initialization ............................................................................... 66

2.12.3 HAL IO operation process ................................................................ 68

2.12.4 Timeout and error management ....................................................... 71

3 HAL System Driver ........................................................................ 75