ST STM32F2 Series Manual de usuario

March 2017

DocID028236 Rev 2

1/1371

www.st.com

UM1940

User Manual

Description of STM32F2 HAL and Low Layer drivers

Introduction

STMCubeTM is STMicroelectronics's original initiative to ease developers' life by reducing development

efforts, time and cost. STM32Cube covers the 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

forSTM32F2 series)

The STM32Cube Hardware Abstraction Layer (HAL), an STM32 abstraction layer embedded

software, ensuring maximized portability across the STM32 portfolio

The Low Layer APIs (LL) offering a fast light-weight expert-oriented layer which is closer to the

hardware than the HAL. The LL APIs are available only for a set of peripherals.

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 driver layer provides a generic multi instance simple set of APIs (application programming

interfaces) to interact with the upper layer (application, libraries and stacks).

The HAL driver 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 line or part number. 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, manage data transfers in polling mode, handle interrupts

or DMA, and manage communication errors.

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 such as basic timer, capture, or pulse width

modulation (PWM). The HAL driver 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.

The LL drivers offer hardware services based on the available features of the STM32 peripherals. These

services reflect exactly the hardware capabilities and provide atomic operations that must be called

following the programming model described in the product line reference manual. As a result, the LL

services are not based on standalone processes and do not require any additional memory resources to

save their states, counter or data pointers: all operations are performed by changing the associated

peripheral registers content. Contrary to the HAL, the LL APIs are not provided for peripherals for which

optimized access is not a key feature, or for those requiring heavy software configuration and/or

complex upper level stack (such as FMC, USB, SDMMC).

The HAL and LL are complementary and cover a wide range of applications requirements:

The HAL offers high-level and feature-oriented APIs, with a high-portability level. They hide the

MCU and peripheral complexity to end-user.

The LL offers low-level APIs at registers level, with better optimization but less portability. They

require deep knowledge of the MCU and peripherals specifications.

The source code of HAL and LL drivers 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.

Contents

UM1940

2/1371

DocID028236 Rev 2

Contents

1Acronyms and definitions.............................................................26

2Overview of HAL drivers...............................................................28

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

2.1.1 HAL driver files ................................................................................. 28

2.1.2 User-application files........................................................................ 30

2.2 HAL data structures ........................................................................31

2.2.1 Peripheral handle structures ............................................................ 31

2.2.2 Initialization and configuration structure........................................... 33

2.2.3 Specific process structures .............................................................. 33

2.3 API classification.............................................................................33

2.4 Devices supported by HAL drivers..................................................34

2.5 HAL driver rules ..............................................................................36

2.5.1 HAL API naming rules...................................................................... 36

2.5.2 HAL general naming rules................................................................ 37

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

2.6 HAL generic APIs............................................................................39

2.7 HAL extension APIs........................................................................40

2.7.1 HAL extension model overview........................................................ 40

2.7.2 HAL extension model cases............................................................. 41

2.8 File inclusion model.........................................................................43

2.9 HAL common resources..................................................................43

2.10 HAL configuration............................................................................44

2.11 HAL system peripheral handling .....................................................46

2.11.1 Clock................................................................................................. 46

2.11.2 GPIOs............................................................................................... 46

2.11.3 Cortex NVIC and SysTick timer........................................................ 48

2.11.4 PWR ................................................................................................. 48

2.11.5 EXTI.................................................................................................. 48

2.11.6 DMA.................................................................................................. 49

2.12 How to use HAL drivers ..................................................................51

2.12.1 HAL usage models........................................................................... 51

2.12.2 HAL initialization............................................................................... 52

2.12.3 HAL IO operation process................................................................ 54

2.12.4 Timeout and error management....................................................... 57

3Overview of Low Layer drivers.....................................................61

UM1940

Contents

DocID028236 Rev 2

3/1371

3.1 Low Layer files................................................................................61

3.2 Overview of Low Layer APIs and naming rules...............................63

3.2.1 Peripheral initialization functions...................................................... 63

3.2.2 Peripheral register-level configuration functions .............................. 67

4Cohabiting of HAL and LL ............................................................69

4.1 Low Layer driver used in standalone mode.....................................69

4.2 Mixed use of Low Layer APIs and HAL drivers...............................69

5HAL System Driver........................................................................70

5.1 HAL Firmware driver API description..............................................70

5.1.1 How to use this driver....................................................................... 70

5.1.2 Initialization and de-initialization functions ....................................... 70

5.1.3 HAL Control functions....................................................................... 70

5.1.4 Detailed description of functions ...................................................... 71

5.2 HAL Firmware driver defines...........................................................75

5.2.1 HAL................................................................................................... 75

6HAL ADC Generic Driver...............................................................77

6.1 ADC Firmware driver registers structures .......................................77

6.1.1 ADC_InitTypeDef.............................................................................. 77

6.1.2 ADC_ChannelConfTypeDef ............................................................. 78

6.1.3 ADC_AnalogWDGConfTypeDef....................................................... 79

6.1.4 ADC_HandleTypeDef....................................................................... 80

6.2 ADC Firmware driver API description..............................................80

6.2.1 ADC Peripheral features................................................................... 80

6.2.2 How to use this driver....................................................................... 81

6.2.3 Initialization and de-initialization functions ....................................... 83

6.2.4 IO operation functions ...................................................................... 83

6.2.5 Peripheral Control functions............................................................. 83

6.2.6 Peripheral State and errors functions............................................... 84

6.2.7 Detailed description of functions ...................................................... 84

6.3 ADC Firmware driver defines..........................................................89

6.3.1 ADC.................................................................................................. 89

7HAL ADC Extension Driver...........................................................96

7.1 ADCEx Firmware driver registers structures...................................96

7.1.1 ADC_InjectionConfTypeDef ............................................................. 96

7.1.2 ADC_MultiModeTypeDef.................................................................. 97

7.2 ADCEx Firmware driver API description .........................................98

Contents

UM1940

4/1371

DocID028236 Rev 2

7.2.1 How to use this driver....................................................................... 98

7.2.2 Extended features functions............................................................. 99

7.2.3 Detailed description of functions .................................................... 100

7.3 ADCEx Firmware driver defines....................................................103

7.3.1 ADCEx............................................................................................ 103

8HAL CAN Generic Driver.............................................................105

8.1 CAN Firmware driver registers structures .....................................105

8.1.1 CAN_InitTypeDef............................................................................ 105

8.1.2 CAN_FilterConfTypeDef................................................................. 106

8.1.3 CanTxMsgTypeDef......................................................................... 107

8.1.4 CanRxMsgTypeDef........................................................................ 107

8.1.5 CAN_HandleTypeDef..................................................................... 108

8.2 CAN Firmware driver API description............................................108

8.2.1 How to use this driver..................................................................... 108

8.2.2 Initialization and de-initialization functions ..................................... 109

8.2.3 IO operation functions .................................................................... 110

8.2.4 Peripheral State and Error functions .............................................. 110

8.2.5 Detailed description of functions .................................................... 110

8.3 CAN Firmware driver defines........................................................114

8.3.1 CAN................................................................................................ 114

9HAL CORTEX Generic Driver......................................................122

9.1 CORTEX Firmware driver registers structures..............................122

9.1.1 MPU_Region_InitTypeDef.............................................................. 122

9.2 CORTEX Firmware driver API description ....................................123

9.2.1 How to use this driver..................................................................... 123

9.2.2 Initialization and de-initialization functions ..................................... 123

9.2.3 Peripheral Control functions........................................................... 124

9.2.4 Detailed description of functions .................................................... 124

9.3 CORTEX Firmware driver defines.................................................129

9.3.1 CORTEX......................................................................................... 129

10 HAL CRC Generic Driver.............................................................132

10.1 CRC Firmware driver registers structures.....................................132

10.1.1 CRC_HandleTypeDef..................................................................... 132

10.2 CRC Firmware driver API description ...........................................132

10.2.1 How to use this driver..................................................................... 132

10.2.2 Initialization and de-initialization functions ..................................... 132

10.2.3 Peripheral Control functions........................................................... 133

UM1940

Contents

DocID028236 Rev 2

5/1371

10.2.4 Peripheral State functions .............................................................. 133

10.2.5 Detailed description of functions .................................................... 133

10.3 CRC Firmware driver defines........................................................135

10.3.1 CRC................................................................................................ 135

11 HAL CRYP Generic Driver...........................................................136

11.1 CRYP Firmware driver registers structures...................................136

11.1.1 CRYP_InitTypeDef......................................................................... 136

11.1.2 CRYP_HandleTypeDef................................................................... 136

11.2 CRYP Firmware driver API description .........................................137

11.2.1 How to use this driver..................................................................... 137

11.2.2 Initialization and de-initialization functions ..................................... 138

11.2.3 AES processing functions .............................................................. 138

11.2.4 DES processing functions .............................................................. 139

11.2.5 TDES processing functions............................................................ 139

11.2.6 DMA callback functions.................................................................. 140

11.2.7 CRYP IRQ handler management................................................... 140

11.2.8 Peripheral State functions .............................................................. 140

11.2.9 Detailed description of functions .................................................... 140

11.3 CRYP Firmware driver defines......................................................155

11.3.1 CRYP.............................................................................................. 155

12 HAL DAC Generic Driver.............................................................159

12.1 DAC Firmware driver registers structures .....................................159

12.1.1 DAC_HandleTypeDef..................................................................... 159

12.1.2 DAC_ChannelConfTypeDef ........................................................... 159

12.2 DAC Firmware driver API description............................................160

12.2.1 DAC Peripheral features................................................................. 160

12.2.2 How to use this driver..................................................................... 161

12.2.3 Initialization and de-initialization functions ..................................... 162

12.2.4 IO operation functions .................................................................... 162

12.2.5 Peripheral Control functions........................................................... 162

12.2.6 Peripheral State and Errors functions ............................................ 162

12.2.7 Detailed description of functions .................................................... 163

12.3 DAC Firmware driver defines........................................................167

12.3.1 DAC................................................................................................ 167

13 HAL DAC Extension Driver.........................................................171

13.1 DACEx Firmware driver API description .......................................171

Contents

UM1940

6/1371

DocID028236 Rev 2

13.1.1 How to use this driver..................................................................... 171

13.1.2 Extended features functions........................................................... 171

13.1.3 Detailed description of functions .................................................... 171

13.2 DACEx Firmware driver defines....................................................175

13.2.1 DACEx............................................................................................ 175

14 HAL DCMI Generic Driver ...........................................................177

14.1 DCMI Firmware driver registers structures....................................177

14.1.1 DCMI_CodesInitTypeDef................................................................ 177

14.1.2 DCMI_InitTypeDef.......................................................................... 177

14.1.3 DCMI_HandleTypeDef ................................................................... 178

14.2 DCMI Firmware driver API description..........................................178

14.2.1 How to use this driver..................................................................... 178

14.2.2 Initialization and Configuration functions........................................ 179

14.2.3 IO operation functions .................................................................... 179

14.2.4 Peripheral Control functions........................................................... 180

14.2.5 Peripheral State and Errors functions ............................................ 180

14.2.6 Detailed description of functions .................................................... 180

14.3 DCMI Firmware driver defines.......................................................184

14.3.1 DCMI............................................................................................... 184

15 HAL DMA Generic Driver ............................................................190

15.1 DMA Firmware driver registers structures.....................................190

15.1.1 DMA_InitTypeDef........................................................................... 190

15.1.2 __DMA_HandleTypeDef................................................................. 191

15.2 DMA Firmware driver API description ...........................................192

15.2.1 How to use this driver..................................................................... 192

15.2.2 Initialization and de-initialization functions ..................................... 193

15.2.3 IO operation functions .................................................................... 193

15.2.4 State and Errors functions.............................................................. 194

15.2.5 Detailed description of functions .................................................... 194

15.3 DMA Firmware driver defines........................................................197

15.3.1 DMA................................................................................................ 197

16 HAL DMA Extension Driver.........................................................201

16.1 DMAEx Firmware driver API description.......................................201

16.1.1 How to use this driver..................................................................... 201

16.1.2 Extended features functions........................................................... 201

16.1.3 Detailed description of functions .................................................... 201

17 HAL ETH Generic Driver .............................................................203

UM1940

Contents

DocID028236 Rev 2

7/1371

17.1 ETH Firmware driver registers structures......................................203

17.1.1 ETH_InitTypeDef............................................................................ 203

17.1.2 ETH_MACInitTypeDef.................................................................... 203

17.1.3 ETH_DMAInitTypeDef.................................................................... 206

17.1.4 ETH_DMADescTypeDef................................................................. 207

17.1.5 ETH_DMARxFrameInfos................................................................ 208

17.1.6 ETH_HandleTypeDef ..................................................................... 208

17.2 ETH Firmware driver API description............................................209

17.2.1 How to use this driver..................................................................... 209

17.2.2 Initialization and de-initialization functions ..................................... 209

17.2.3 IO operation functions .................................................................... 210

17.2.4 Peripheral Control functions........................................................... 210

17.2.5 Peripheral State functions .............................................................. 210

17.2.6 Detailed description of functions .................................................... 211

17.3 ETH Firmware driver defines.........................................................215

17.3.1 ETH................................................................................................. 215

18 HAL FLASH Generic Driver.........................................................243

18.1 FLASH Firmware driver registers structures .................................243

18.1.1 FLASH_ProcessTypeDef ............................................................... 243

18.2 FLASH Firmware driver API description........................................243

18.2.1 FLASH peripheral features............................................................. 243

18.2.2 How to use this driver..................................................................... 243

18.2.3 Programming operation functions .................................................. 244

18.2.4 Peripheral Control functions........................................................... 244

18.2.5 Peripheral Errors functions............................................................. 244

18.2.6 Detailed description of functions .................................................... 245

18.3 FLASH Firmware driver defines....................................................247

18.3.1 FLASH............................................................................................ 247

19 HAL FLASH Extension Driver.....................................................253

19.1 FLASHEx Firmware driver registers structures.............................253

19.1.1 FLASH_EraseInitTypeDef.............................................................. 253

19.1.2 FLASH_OBProgramInitTypeDef .................................................... 253

19.2 FLASHEx Firmware driver API description....................................254

19.2.1 Flash Extension features................................................................ 254

19.2.2 How to use this driver..................................................................... 254

19.2.3 Extended programming operation functions .................................. 254

19.2.4 Detailed description of functions .................................................... 254

Contents

UM1940

8/1371

DocID028236 Rev 2

19.3 FLASHEx Firmware driver defines................................................256

19.3.1 FLASHEx........................................................................................ 256

20 HAL GPIO Generic Driver............................................................259

20.1 GPIO Firmware driver registers structures....................................259

20.1.1 GPIO_InitTypeDef.......................................................................... 259

20.2 GPIO Firmware driver API description ..........................................259

20.2.1 GPIO Peripheral features............................................................... 259

20.2.2 How to use this driver..................................................................... 260

20.2.3 Initialization and de-initialization functions ..................................... 260

20.2.4 IO operation functions .................................................................... 260

20.2.5 Detailed description of functions .................................................... 261

20.3 GPIO Firmware driver defines.......................................................263

20.3.1 GPIO............................................................................................... 263

21 HAL GPIO Extension Driver........................................................267

21.1 GPIOEx Firmware driver defines...................................................267

21.1.1 GPIOEx .......................................................................................... 267

22 HAL HASH Generic Driver ..........................................................268

22.1 HASH Firmware driver registers structures...................................268

22.1.1 HASH_InitTypeDef......................................................................... 268

22.1.2 HASH_HandleTypeDef................................................................... 268

22.2 HASH Firmware driver API description .........................................269

22.2.1 How to use this driver..................................................................... 269

22.2.2 HASH processing using polling mode functions ............................ 270

22.2.3 HASH processing using interrupt mode functions.......................... 270

22.2.4 HASH processing using DMA mode functions............................... 270

22.2.5 HMAC processing using polling mode functions............................ 270

22.2.6 HMAC processing using DMA mode functions .............................. 271

22.2.7 Peripheral State functions .............................................................. 271

22.2.8 Initialization and de-initialization functions ..................................... 271

22.2.9 Detailed description of functions .................................................... 271

22.3 HASH Firmware driver defines......................................................278

22.3.1 HASH.............................................................................................. 278

23 HAL HCD Generic Driver.............................................................280

23.1 HCD Firmware driver registers structures.....................................280

23.1.1 HCD_HandleTypeDef..................................................................... 280

23.2 HCD Firmware driver API description ...........................................280

UM1940

Contents

DocID028236 Rev 2

9/1371

23.2.1 How to use this driver..................................................................... 280

23.2.2 Initialization and de-initialization functions ..................................... 281

23.2.3 IO operation functions .................................................................... 281

23.2.4 Peripheral Control functions........................................................... 281

23.2.5 Peripheral State functions .............................................................. 281

23.2.6 Detailed description of functions .................................................... 281

23.3 HCD Firmware driver defines........................................................286

23.3.1 HCD................................................................................................ 286

24 HAL I2C Generic Driver...............................................................288

24.1 I2C Firmware driver registers structures .......................................288

24.1.1 I2C_InitTypeDef.............................................................................. 288

24.1.2 I2C_HandleTypeDef....................................................................... 288

24.2 I2C Firmware driver API description..............................................289

24.2.1 How to use this driver..................................................................... 289

24.2.2 Initialization and de-initialization functions ..................................... 293

24.2.3 IO operation functions .................................................................... 294

24.2.4 Peripheral State, Mode and Error functions................................... 296

24.2.5 Detailed description of functions .................................................... 296

24.3 I2C Firmware driver defines..........................................................308

24.3.1 I2C.................................................................................................. 308

25 HAL I2S Generic Driver...............................................................314

25.1 I2S Firmware driver registers structures .......................................314

25.1.1 I2S_InitTypeDef.............................................................................. 314

25.1.2 I2S_HandleTypeDef....................................................................... 314

25.2 I2S Firmware driver API description..............................................315

25.2.1 How to use this driver..................................................................... 315

25.2.2 Initialization and de-initialization functions ..................................... 317

25.2.3 IO operation functions .................................................................... 317

25.2.4 Peripheral State and Errors functions ............................................ 318

25.2.5 Detailed description of functions .................................................... 318

25.3 I2S Firmware driver defines ..........................................................323

25.3.1 I2S .................................................................................................. 323

26 HAL IRDA Generic Driver............................................................328

26.1 IRDA Firmware driver registers structures ....................................328

26.1.1 IRDA_InitTypeDef........................................................................... 328

26.1.2 IRDA_HandleTypeDef.................................................................... 328

Contents

UM1940

10/1371

DocID028236 Rev 2

26.2 IRDA Firmware driver API description...........................................329

26.2.1 How to use this driver..................................................................... 329

26.2.2 Initialization and Configuration functions........................................ 330

26.2.3 IO operation functions .................................................................... 331

26.2.4 Peripheral State and Errors functions ............................................ 332

26.2.5 Detailed description of functions .................................................... 332

26.3 IRDA Firmware driver defines.......................................................340

26.3.1 IRDA............................................................................................... 340

27 HAL IWDG Generic Driver...........................................................347

27.1 IWDG Firmware driver registers structures...................................347

27.1.1 IWDG_InitTypeDef ......................................................................... 347

27.1.2 IWDG_HandleTypeDef................................................................... 347

27.2 IWDG Firmware driver API description .........................................347

27.2.1 IWDG Generic features.................................................................. 347

27.2.2 How to use this driver..................................................................... 348

27.2.3 Initialization and Start functions...................................................... 348

27.2.4 IO operation functions .................................................................... 348

27.2.5 Detailed description of functions .................................................... 349

27.3 IWDG Firmware driver defines......................................................349

27.3.1 IWDG.............................................................................................. 349

28 HAL MMC Generic Driver............................................................351

28.1 MMC Firmware driver registers structures ....................................351

28.1.1 HAL_MMC_CardInfoTypeDef ........................................................ 351

28.1.2 MMC_HandleTypeDef.................................................................... 351

28.1.3 HAL_MMC_CardCSDTypeDef....................................................... 352

28.1.4 HAL_MMC_CardCIDTypeDef ........................................................ 354

28.1.5 HAL_MMC_CardStatusTypeDef.................................................... 355

28.2 MMC Firmware driver API description...........................................356

28.2.1 How to use this driver..................................................................... 356

28.2.2 Detailed description of functions .................................................... 359

28.3 MMC Firmware driver defines.......................................................362

28.3.1 MMC............................................................................................... 362

29 HAL NAND Generic Driver..........................................................370

29.1 NAND Firmware driver registers structures...................................370

29.1.1 NAND_IDTypeDef.......................................................................... 370

29.1.2 NAND_AddressTypeDef................................................................. 370

29.1.3 NAND_DeviceConfigTypeDef ........................................................ 370

Otros manuales para STM32F2 Series

Tabla de contenidos

Otros manuales de Microcontrolador de ST

ST UM2140 Manual de usuario

ST STM32F4 Series Manual de usuario

ST STM32G0 1 Series Manual de usuario

ST STM32F4DISCOVERY Manual de usuario

ST STM32F446 Series Manual de usuario

ST STM32H5 Nucleo-144 Manual de usuario

ST STM32F0 Series Instrucciones de instalación y funcionamiento

ST STM32F7308-DK Manual de usuario

ST STM32 NUCLEO-F030R8 Manual de usuario

ST STM32H745I-DISCO Manual de usuario

ST STM8A Instrucciones de instalación y funcionamiento

ST STM32F20 Series Instrucciones de instalación y funcionamiento

ST BlueNRG Manual de usuario

ST STMod+ Manual de usuario

ST STEVAL-MKBOXPRO Manual de usuario

ST STM32F410 Manual de usuario

ST STM32L562E-DK Manual de usuario

ST P-NUCLEO-LRWAN2 Manual de usuario

ST STM8AF Series Manual de usuario

ST STEVAL-BFA001V1B Manual de usuario

ST STM32L0x3 Manual de usuario

ST STEVAL-FKI433V1 Manual de usuario

ST ST7232A Manual de usuario

ST STM32F103 series Instrucciones de instalación y funcionamiento

Manuales populares de Microcontrolador de otras marcas

AMS

AMS AS7261 Demo Kit Manual de usuario

Novatek

Novatek NT6861 Manual de usuario

Espressif Systems

Espressif Systems ESP8266 SDK Guía de configuración

Nuvoton

Nuvoton ISD61S00 ChipCorder Guía

STMicrolectronics

STMicrolectronics ST7 Assembler Linker Manual de usuario

Texas Instruments

Texas Instruments Chipcon CC2420DK Manual de usuario

Lantronix

Lantronix Intrinsyc Open-Q 865XR SOM Manual de usuario

NEC

NEC 78GK0S/K 1+ Series Instrucciones de instalación y funcionamiento

Mikroe

Mikroe SEMITECH N-PLC Click Instrucciones de instalación y funcionamiento

Intel

Intel Agilex Manual de usuario

Cypress

Cypress CY4607 HX2VL Manual de usuario

DIGITAL-LOGIC

DIGITAL-LOGIC MICROSPACE Manual de usuario

Texas Instruments

Texas Instruments TMS320F2837 D Series Manual de usuario

CYPRES

CYPRES CY14NVSRAMKIT-001 Manual de usuario

Texas Instruments

Texas Instruments INA-DUAL-2AMP-EVM Manual de usuario

Espressif Systems

Espressif Systems ESP8266EX Instrucciones de funcionamiento

Abov

Abov AC33M8128L Manual de usuario

Laird

Laird BL654PA Manual de usuario