Description Of STM32F4xx HAL Drivers User Manual

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 964

DownloadDescription Of STM32F4xx HAL Drivers User Manual
Open PDF In BrowserView PDF
UM1725
User Manual
Description of STM32F4xx HAL drivers

Introduction
TM

STM32Cube is STMicroelectronics's original initiative to ease developers' life by reducing
TM
development efforts, time and cost. STM32Cube covers the STM32 portfolio.
TM

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 as STM32CubeF4 for
STM32F4 series)
The STM32Cube HAL, an STM32 abstraction layer embedded software, ensuring maximized
portability across the 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 driver 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 easy portability to 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 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 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
TM
development tools. It is checked with CodeSonar static analysis tool. It is fully documented and is
MISRA-C 2004 compliant.
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.
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.

September 2016

DocID025834 Rev 4

1/964
www.st.com

Contents

UM1725

Contents
1

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

2

Overview of HAL drivers ............................................................... 28
2.1

2.2

2/964

2.1.1

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

2.1.2

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

HAL data structures ........................................................................ 31
2.2.1

Peripheral handle structures ............................................................ 32

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 .................................................. 35

2.5

HAL driver rules .............................................................................. 37
2.5.1

HAL API naming rules ...................................................................... 37

2.5.2

HAL general naming rules ................................................................ 38

2.5.3

HAL interrupt handler and callback functions ................................... 39

2.6

HAL generic APIs ............................................................................ 40

2.7

HAL extension APIs ........................................................................ 41
2.7.1

HAL extension model overview ........................................................ 41

2.7.2

HAL extension model cases ............................................................. 42

2.8

File inclusion model......................................................................... 44

2.9

HAL common resources .................................................................. 45

2.10

HAL configuration............................................................................ 45

2.11

HAL system peripheral handling ..................................................... 47

2.12

3

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

2.11.1

Clock ................................................................................................. 47

2.11.2

GPIOs ............................................................................................... 47

2.11.3

Cortex NVIC and SysTick timer........................................................ 49

2.11.4

PWR ................................................................................................. 50

2.11.5

EXTI .................................................................................................. 51

2.11.6

DMA .................................................................................................. 52

How to use HAL drivers .................................................................. 54
2.12.1

HAL usage models ........................................................................... 54

2.12.2

HAL initialization ............................................................................... 55

2.12.3

HAL IO operation process ................................................................ 57

2.12.4

Timeout and error management ....................................................... 60

HAL System Driver ........................................................................ 65

DocID025834 Rev 4

UM1725

Contents

3.1

3.2

HAL Firmware driver API description .............................................. 65
3.1.1

How to use this driver ....................................................................... 65

3.1.2

Initialization and de-initialization functions ....................................... 65

3.1.3

HAL Control functions....................................................................... 65

3.1.4

Detailed description of functions ...................................................... 66

HAL Firmware driver defines ........................................................... 70
3.2.1

4

HAL ADC Generic Driver ............................................................... 73
4.1

4.2

4.3

ADC Firmware driver registers structures ....................................... 73
4.1.1

ADC_InitTypeDef .............................................................................. 73

4.1.2

ADC_ChannelConfTypeDef ............................................................. 75

4.1.3

ADC_AnalogWDGConfTypeDef ....................................................... 75

4.1.4

ADC_HandleTypeDef ....................................................................... 76

ADC Firmware driver API description .............................................. 77
4.2.1

ADC Peripheral features................................................................... 77

4.2.2

How to use this driver ....................................................................... 77

4.2.3

Initialization and de-initialization functions ....................................... 80

4.2.4

IO operation functions ...................................................................... 80

4.2.5

Peripheral Control functions ............................................................. 80

4.2.6

Peripheral State and errors functions ............................................... 81

4.2.7

Detailed description of functions ...................................................... 81

ADC Firmware driver defines .......................................................... 86
4.3.1

5

ADC .................................................................................................. 86

HAL ADC Extension Driver ........................................................... 93
5.1

5.2

5.3

ADCEx Firmware driver registers structures ................................... 93
5.1.1

ADC_InjectionConfTypeDef ............................................................. 93

5.1.2

ADC_MultiModeTypeDef .................................................................. 95

ADCEx Firmware driver API description ......................................... 95
5.2.1

How to use this driver ....................................................................... 95

5.2.2

Extended features functions ............................................................. 97

5.2.3

Detailed description of functions ...................................................... 97

ADCEx Firmware driver defines .................................................... 100
5.3.1

6

HAL ................................................................................................... 70

ADCEx ............................................................................................ 100

HAL CAN Generic Driver ............................................................. 103
6.1

CAN Firmware driver registers structures ..................................... 103
6.1.1

CAN_InitTypeDef ............................................................................ 103

6.1.2

CAN_FilterConfTypeDef ................................................................. 104

DocID025834 Rev 4

3/964

Contents

UM1725

6.2

6.3

6.1.3

CanTxMsgTypeDef......................................................................... 105

6.1.4

CanRxMsgTypeDef ........................................................................ 105

6.1.5

CAN_HandleTypeDef ..................................................................... 106

CAN Firmware driver API description ............................................ 107
6.2.1

How to use this driver ..................................................................... 107

6.2.2

Initialization and de-initialization functions ..................................... 108

6.2.3

IO operation functions .................................................................... 108

6.2.4

Peripheral State and Error functions .............................................. 108

6.2.5

Detailed description of functions .................................................... 109

CAN Firmware driver defines ........................................................ 112
6.3.1

7

HAL CEC Generic Driver ............................................................. 120
7.1

7.2

7.3

CEC Firmware driver registers structures ..................................... 120
7.1.1

CEC_InitTypeDef ............................................................................ 120

7.1.2

CEC_HandleTypeDef ..................................................................... 121

CEC Firmware driver API description ............................................ 122
7.2.1

How to use this driver ..................................................................... 122

7.2.2

How to use this driver ..................................................................... 122

7.2.3

Initialization and Configuration functions ........................................ 123

7.2.4

IO operation functions .................................................................... 123

7.2.5

Peripheral Control function ............................................................. 124

7.2.6

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

CEC Firmware driver defines ........................................................ 127
7.3.1

8

CORTEX Firmware driver registers structures .............................. 136
8.1.1

8.2

8.3

MPU_Region_InitTypeDef .............................................................. 136

CORTEX Firmware driver API description .................................... 137
8.2.1

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

8.2.2

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

8.2.3

Peripheral Control functions ........................................................... 138

8.2.4

Detailed description of functions .................................................... 138

CORTEX Firmware driver defines ................................................. 143
8.3.1

CORTEX ......................................................................................... 143

HAL CRC Generic Driver ............................................................. 146
9.1

CRC Firmware driver registers structures ..................................... 146
9.1.1

4/964

CEC ................................................................................................ 127

HAL CORTEX Generic Driver ...................................................... 136
8.1

9

CAN ................................................................................................ 112

CRC_HandleTypeDef ..................................................................... 146

DocID025834 Rev 4

UM1725

Contents

9.2

9.3

CRC Firmware driver API description ........................................... 146
9.2.1

How to use this driver ..................................................................... 146

9.2.2

Initialization and de-initialization functions ..................................... 146

9.2.3

Peripheral Control functions ........................................................... 147

9.2.4

Peripheral State functions .............................................................. 147

9.2.5

Detailed description of functions .................................................... 147

CRC Firmware driver defines ........................................................ 148
9.3.1

10

HAL CRYP Generic Driver........................................................... 150
10.1

10.2

10.3

CRYP Firmware driver registers structures ................................... 150
10.1.1

CRYP_InitTypeDef ......................................................................... 150

10.1.2

CRYP_HandleTypeDef................................................................... 151

CRYP Firmware driver API description ......................................... 152
10.2.1

How to use this driver ..................................................................... 152

10.2.2

Initialization and de-initialization functions ..................................... 152

10.2.3

AES processing functions .............................................................. 153

10.2.4

DES processing functions .............................................................. 153

10.2.5

TDES processing functions ............................................................ 154

10.2.6

DMA callback functions .................................................................. 154

10.2.7

CRYP IRQ handler management ................................................... 154

10.2.8

Peripheral State functions .............................................................. 155

10.2.9

Detailed description of functions .................................................... 155

CRYP Firmware driver defines ...................................................... 169
10.3.1

11

CRYP .............................................................................................. 169

HAL CRYP Extension Driver ....................................................... 173
11.1

11.2

CRYPEx Firmware driver API description ..................................... 173
11.1.1

How to use this driver ..................................................................... 173

11.1.2

Extended AES processing functions .............................................. 174

11.1.3

CRYPEx IRQ handler management ............................................... 174

11.1.4

Detailed description of functions .................................................... 174

CRYPEx Firmware driver defines.................................................. 179
11.2.1

12

CRC ................................................................................................ 148

CRYPEx ......................................................................................... 179

HAL DAC Generic Driver ............................................................. 180
12.1

12.2

DAC Firmware driver registers structures ..................................... 180
12.1.1

DAC_HandleTypeDef ..................................................................... 180

12.1.2

DAC_ChannelConfTypeDef ........................................................... 180

DAC Firmware driver API description ............................................ 181

DocID025834 Rev 4

5/964

Contents

UM1725

12.3

12.2.1

DAC Peripheral features................................................................. 181

12.2.2

How to use this driver ..................................................................... 182

12.2.3

Initialization and de-initialization functions ..................................... 183

12.2.4

IO operation functions .................................................................... 183

12.2.5

Peripheral Control functions ........................................................... 183

12.2.6

Peripheral State and Errors functions ............................................ 184

12.2.7

Detailed description of functions .................................................... 184

DAC Firmware driver defines ........................................................ 188
12.3.1

13

HAL DAC Extension Driver ......................................................... 192
13.1

13.2

DACEx Firmware driver API description ....................................... 192
13.1.1

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

13.1.2

Extended features functions ........................................................... 192

13.1.3

Detailed description of functions .................................................... 192

DACEx Firmware driver defines .................................................... 196
13.2.1

14

DCMI Firmware driver registers structures .................................... 198
14.1.1

14.2

14.3

14.2.1

How to use this driver ..................................................................... 199

14.2.2

Initialization and Configuration functions ........................................ 199

14.2.3

IO operation functions .................................................................... 200

14.2.4

Peripheral Control functions ........................................................... 200

14.2.5

Peripheral State and Errors functions ............................................ 200

14.2.6

Detailed description of functions .................................................... 200

DCMI Firmware driver defines....................................................... 204
DCMI............................................................................................... 204

HAL DCMI Extension Driver ........................................................ 210
15.1

15.2

DCMIEx Firmware driver registers structures................................ 210
15.1.1

DCMI_CodesInitTypeDef................................................................ 210

15.1.2

DCMI_InitTypeDef .......................................................................... 210

DCMIEx Firmware driver defines .................................................. 211
15.2.1

DCMIEx .......................................................................................... 211

HAL DFSDM Generic Driver ........................................................ 213
16.1

DFSDM Firmware driver registers structures ................................ 213
16.1.1

6/964

DCMI_HandleTypeDef ................................................................... 198

DCMI Firmware driver API description .......................................... 199

14.3.1

16

DACEx ............................................................................................ 196

HAL DCMI Generic Driver ........................................................... 198
14.1

15

DAC ................................................................................................ 188

DFSDM_Channel_OutputClockTypeDef ........................................ 213

DocID025834 Rev 4

UM1725

Contents

16.2

16.3

16.1.2

DFSDM_Channel_InputTypeDef .................................................... 213

16.1.3

DFSDM_Channel_SerialInterfaceTypeDef .................................... 214

16.1.4

DFSDM_Channel_AwdTypeDef ..................................................... 214

16.1.5

DFSDM_Channel_InitTypeDef ....................................................... 214

16.1.6

DFSDM_Channel_HandleTypeDef ................................................ 215

16.1.7

DFSDM_Filter_RegularParamTypeDef .......................................... 215

16.1.8

DFSDM_Filter_InjectedParamTypeDef .......................................... 216

16.1.9

DFSDM_Filter_FilterParamTypeDef .............................................. 216

16.1.10

DFSDM_Filter_InitTypeDef ............................................................ 217

16.1.11

DFSDM_Filter_HandleTypeDef ...................................................... 217

16.1.12

DFSDM_Filter_AwdParamTypeDef ............................................... 218

DFSDM Firmware driver API description ...................................... 219
16.2.1

How to use this driver ..................................................................... 219

16.2.2

Channel initialization and de-initialization functions ....................... 221

16.2.3

Channel operation functions ........................................................... 222

16.2.4

Channel state function .................................................................... 222

16.2.5

Filter initialization and de-initialization functions ............................ 222

16.2.6

Filter control functions .................................................................... 223

16.2.7

Filter operation functions ................................................................ 223

16.2.8

Filter state functions ....................................................................... 224

16.2.9

Detailed description of functions .................................................... 224

DFSDM Firmware driver defines ................................................... 238
16.3.1

17

DFSDM ........................................................................................... 238

HAL DMA2D Generic Driver ........................................................ 241
17.1

17.2

17.3

DMA2D Firmware driver registers structures ................................ 241
17.1.1

DMA2D_ColorTypeDef ................................................................... 241

17.1.2

DMA2D_CLUTCfgTypeDef ............................................................ 241

17.1.3

DMA2D_InitTypeDef....................................................................... 242

17.1.4

DMA2D_LayerCfgTypeDef ............................................................. 242

17.1.5

__DMA2D_HandleTypeDef ............................................................ 243

DMA2D Firmware driver API description ....................................... 243
17.2.1

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

17.2.2

Initialization and Configuration functions ........................................ 245

17.2.3

IO operation functions .................................................................... 245

17.2.4

Peripheral Control functions ........................................................... 246

17.2.5

Peripheral State and Errors functions ............................................ 246

17.2.6

Detailed description of functions .................................................... 246

DMA2D Firmware driver defines ................................................... 254

DocID025834 Rev 4

7/964

Contents

UM1725

17.3.1

18

HAL DMA Generic Driver ............................................................ 260
18.1

18.2

18.3

DMA Firmware driver registers structures ..................................... 260
18.1.1

DMA_InitTypeDef ........................................................................... 260

18.1.2

__DMA_HandleTypeDef................................................................. 261

DMA Firmware driver API description ........................................... 262
18.2.1

How to use this driver ..................................................................... 262

18.2.2

Initialization and de-initialization functions ..................................... 263

18.2.3

IO operation functions .................................................................... 264

18.2.4

State and Errors functions .............................................................. 264

18.2.5

Detailed description of functions .................................................... 264

DMA Firmware driver defines ........................................................ 268
18.3.1

19

DMAEx Firmware driver API description ....................................... 271
19.1.1

How to use this driver ..................................................................... 271

19.1.2

Extended features functions ........................................................... 271

19.1.3

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

HAL DSI Generic Driver .............................................................. 273
20.1

20.2

20.3

DSI Firmware driver registers structures ....................................... 273
20.1.1

DSI_InitTypeDef ............................................................................. 273

20.1.2

DSI_PLLInitTypeDef ....................................................................... 273

20.1.3

DSI_VidCfgTypeDef ....................................................................... 274

20.1.4

DSI_CmdCfgTypeDef ..................................................................... 276

20.1.5

DSI_LPCmdTypeDef ...................................................................... 277

20.1.6

DSI_PHY_TimerTypeDef ............................................................... 278

20.1.7

DSI_HOST_TimeoutTypeDef ......................................................... 278

20.1.8

DSI_HandleTypeDef....................................................................... 279

DSI Firmware driver API description ............................................. 280
20.2.1

Initialization and Configuration functions ........................................ 280

20.2.2

IO operation functions .................................................................... 280

20.2.3

Peripheral Control functions ........................................................... 280

20.2.4

Peripheral State and Errors functions ............................................ 281

20.2.5

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

DSI Firmware driver defines .......................................................... 291
20.3.1

21

8/964

DMA ................................................................................................ 268

HAL DMA Extension Driver......................................................... 271
19.1

20

DMA2D ........................................................................................... 254

DSI .................................................................................................. 291

HAL ETH Generic Driver ............................................................. 299

DocID025834 Rev 4

UM1725

Contents

21.1

21.2

21.3

ETH Firmware driver registers structures ...................................... 299
21.1.1

ETH_InitTypeDef ............................................................................ 299

21.1.2

ETH_MACInitTypeDef .................................................................... 300

21.1.3

ETH_DMAInitTypeDef .................................................................... 302

21.1.4

ETH_DMADescTypeDef................................................................. 304

21.1.5

ETH_DMARxFrameInfos ................................................................ 304

21.1.6

ETH_HandleTypeDef ..................................................................... 305

ETH Firmware driver API description ............................................ 305
21.2.1

How to use this driver ..................................................................... 305

21.2.2

Initialization and de-initialization functions ..................................... 306

21.2.3

IO operation functions .................................................................... 306

21.2.4

Peripheral Control functions ........................................................... 307

21.2.5

Peripheral State functions .............................................................. 307

21.2.6

Detailed description of functions .................................................... 307

ETH Firmware driver defines......................................................... 311
21.3.1

22

HAL FLASH Generic Driver......................................................... 339
22.1

FLASH Firmware driver registers structures ................................. 339
22.1.1

22.2

22.3

FLASH_ProcessTypeDef ............................................................... 339

FLASH Firmware driver API description ........................................ 339
22.2.1

FLASH peripheral features ............................................................. 339

22.2.2

How to use this driver ..................................................................... 340

22.2.3

Programming operation functions .................................................. 340

22.2.4

Peripheral Control functions ........................................................... 340

22.2.5

Peripheral Errors functions ............................................................. 340

22.2.6

Detailed description of functions .................................................... 341

FLASH Firmware driver defines .................................................... 343
22.3.1

23

ETH................................................................................................. 311

FLASH ............................................................................................ 343

HAL FLASH Extension Driver ..................................................... 349
23.1

23.2

FLASHEx Firmware driver registers structures ............................. 349
23.1.1

FLASH_EraseInitTypeDef .............................................................. 349

23.1.2

FLASH_OBProgramInitTypeDef .................................................... 349

23.1.3

FLASH_AdvOBProgramInitTypeDef .............................................. 350

FLASHEx Firmware driver API description.................................... 351
23.2.1

Flash Extension features ................................................................ 351

23.2.2

How to use this driver ..................................................................... 351

23.2.3

Extended programming operation functions .................................. 351

DocID025834 Rev 4

9/964

Contents

UM1725

23.2.4

23.3

FLASHEx Firmware driver defines ................................................ 355
23.3.1

24

FLASH__RAMFUNC Firmware driver API description .................. 360
24.1.1

APIs executed from Internal RAM .................................................. 360

24.1.2

ramfunc functions ........................................................................... 360

24.1.3

Detailed description of functions .................................................... 360

HAL FMPI2C Generic Driver ....................................................... 362
25.1

25.2

25.3

FMPI2C Firmware driver registers structures ................................ 362
25.1.1

FMPI2C_InitTypeDef ...................................................................... 362

25.1.2

__FMPI2C_HandleTypeDef ........................................................... 362

FMPI2C Firmware driver API description ...................................... 364
25.2.1

How to use this driver ..................................................................... 364

25.2.2

Initialization and de-initialization functions ..................................... 368

25.2.3

IO operation functions .................................................................... 369

25.2.4

Peripheral State, Mode and Error functions ................................... 370

25.2.5

Detailed description of functions .................................................... 370

FMPI2C Firmware driver defines................................................... 383
25.3.1

26

26.2

FMPI2CEx Firmware driver API description .................................. 390
26.1.1

FMPI2C peripheral Extended features ........................................... 390

26.1.2

How to use this driver ..................................................................... 390

26.1.3

Extended features functions ........................................................... 390

26.1.4

Detailed description of functions .................................................... 390

FMPI2CEx Firmware driver defines .............................................. 391
26.2.1

FMPI2CEx ...................................................................................... 391

HAL GPIO Generic Driver............................................................ 392
27.1

GPIO Firmware driver registers structures .................................... 392
27.1.1

27.2

10/964

FMPI2C .......................................................................................... 383

HAL FMPI2C Extension Driver .................................................... 390
26.1

27

FLASHEx ........................................................................................ 355

HAL FLASH__RAMFUNC Generic Driver ................................... 360
24.1

25

Detailed description of functions .................................................... 352

GPIO_InitTypeDef .......................................................................... 392

GPIO Firmware driver API description .......................................... 392
27.2.1

GPIO Peripheral features ............................................................... 392

27.2.2

How to use this driver ..................................................................... 393

27.2.3

Initialization and de-initialization functions ..................................... 393

27.2.4

IO operation functions .................................................................... 394

27.2.5

Detailed description of functions .................................................... 394

DocID025834 Rev 4

UM1725

Contents

27.3

GPIO Firmware driver defines ....................................................... 396
27.3.1

28

HAL GPIO Extension Driver ........................................................ 401
28.1

GPIOEx Firmware driver defines................................................... 401
28.1.1

29

29.2

29.3

HASH Firmware driver registers structures ................................... 402
29.1.1

HASH_InitTypeDef ......................................................................... 402

29.1.2

HASH_HandleTypeDef................................................................... 402

HASH Firmware driver API description ......................................... 403
29.2.1

How to use this driver ..................................................................... 403

29.2.2

HASH processing using polling mode functions ............................ 404

29.2.3

HASH processing using interrupt mode functions .......................... 404

29.2.4

HASH processing using DMA mode functions ............................... 404

29.2.5

HMAC processing using polling mode functions ............................ 405

29.2.6

HMAC processing using DMA mode functions .............................. 405

29.2.7

Peripheral State functions .............................................................. 405

29.2.8

Initialization and de-initialization functions ..................................... 405

29.2.9

Detailed description of functions .................................................... 406

HASH Firmware driver defines ...................................................... 412
29.3.1

HASH .............................................................................................. 412

HAL HASH Extension Driver ....................................................... 415
30.1

31

GPIOEx .......................................................................................... 401

HAL HASH Generic Driver .......................................................... 402
29.1

30

GPIO ............................................................................................... 396

HASHEx Firmware driver API description ..................................... 415
30.1.1

How to use this driver ..................................................................... 415

30.1.2

HASH processing using polling mode functions ............................ 416

30.1.3

HMAC processing using polling mode functions ............................ 416

30.1.4

HASH processing using interrupt functions .................................... 416

30.1.5

HASH processing using DMA functions ......................................... 416

30.1.6

HMAC processing using DMA functions ........................................ 417

30.1.7

Detailed description of functions .................................................... 417

HAL HCD Generic Driver ............................................................. 422
31.1

HCD Firmware driver registers structures ..................................... 422
31.1.1

31.2

HCD_HandleTypeDef ..................................................................... 422

HCD Firmware driver API description ........................................... 422
31.2.1

How to use this driver ..................................................................... 422

31.2.2

Initialization and de-initialization functions ..................................... 423

31.2.3

IO operation functions .................................................................... 423

DocID025834 Rev 4

11/964

Contents

UM1725

31.3

31.2.4

Peripheral Control functions ........................................................... 423

31.2.5

Peripheral State functions .............................................................. 423

31.2.6

Detailed description of functions .................................................... 424

HCD Firmware driver defines ........................................................ 428
31.3.1

32

HAL I2C Generic Driver ............................................................... 430
32.1

32.2

32.3

I2C Firmware driver registers structures ....................................... 430
32.1.1

I2C_InitTypeDef .............................................................................. 430

32.1.2

I2C_HandleTypeDef ....................................................................... 431

I2C Firmware driver API description.............................................. 432
32.2.1

How to use this driver ..................................................................... 432

32.2.2

Initialization and de-initialization functions ..................................... 435

32.2.3

IO operation functions .................................................................... 436

32.2.4

Peripheral State, Mode and Errors functions ................................. 438

32.2.5

Detailed description of functions .................................................... 438

I2C Firmware driver defines .......................................................... 450
32.3.1

33

33.2

I2CEx Firmware driver API description ......................................... 456
33.1.1

I2C peripheral extension features .................................................. 456

33.1.2

How to use this driver ..................................................................... 456

33.1.3

Extension features functions .......................................................... 456

33.1.4

Detailed description of functions .................................................... 456

I2CEx Firmware driver defines ...................................................... 457
33.2.1

I2CEx .............................................................................................. 457

HAL I2S Generic Driver ............................................................... 458
34.1

34.2

34.3

I2S Firmware driver registers structures ....................................... 458
34.1.1

I2S_InitTypeDef .............................................................................. 458

34.1.2

I2S_HandleTypeDef ....................................................................... 458

I2S Firmware driver API description .............................................. 459
34.2.1

How to use this driver ..................................................................... 459

34.2.2

Initialization and de-initialization functions ..................................... 461

34.2.3

IO operation functions .................................................................... 461

34.2.4

Peripheral State and Errors functions ............................................ 462

34.2.5

Detailed description of functions .................................................... 462

I2S Firmware driver defines .......................................................... 469
34.3.1

12/964

I2C .................................................................................................. 450

HAL I2C Extension Driver ........................................................... 456
33.1

34

HCD ................................................................................................ 428

I2S .................................................................................................. 469

DocID025834 Rev 4

UM1725

35

Contents

HAL I2S Extension Driver ........................................................... 474
35.1

36

I2SEx Firmware driver API description .......................................... 474
35.1.1

I2S Extension features ................................................................... 474

35.1.2

How to use this driver ..................................................................... 474

35.1.3

Extension features Functions ......................................................... 475

35.1.4

Detailed description of functions .................................................... 476

HAL IRDA Generic Driver ............................................................ 478
36.1

36.2

36.3

IRDA Firmware driver registers structures .................................... 478
36.1.1

IRDA_InitTypeDef ........................................................................... 478

36.1.2

IRDA_HandleTypeDef .................................................................... 478

IRDA Firmware driver API description ........................................... 479
36.2.1

How to use this driver ..................................................................... 479

36.2.2

Initialization and Configuration functions ........................................ 481

36.2.3

IO operation functions .................................................................... 481

36.2.4

Peripheral State and Errors functions ............................................ 482

36.2.5

Detailed description of functions .................................................... 482

IRDA Firmware driver defines ....................................................... 487
36.3.1

37

HAL IWDG Generic Driver ........................................................... 494
37.1

37.2

37.3

IWDG Firmware driver registers structures ................................... 494
37.1.1

IWDG_InitTypeDef ......................................................................... 494

37.1.2

IWDG_HandleTypeDef ................................................................... 494

IWDG Firmware driver API description ......................................... 494
37.2.1

IWDG Generic features .................................................................. 494

37.2.2

How to use this driver ..................................................................... 495

37.2.3

Initialization and Start functions ...................................................... 495

37.2.4

IO operation functions .................................................................... 495

37.2.5

Detailed description of functions .................................................... 496

IWDG Firmware driver defines ...................................................... 496
37.3.1

38

IRDA ............................................................................................... 487

IWDG .............................................................................................. 496

HAL LPTIM Generic Driver .......................................................... 498
38.1

LPTIM Firmware driver registers structures .................................. 498
38.1.1

LPTIM_ClockConfigTypeDef .......................................................... 498

38.1.2

LPTIM_ULPClockConfigTypeDef ................................................... 498

38.1.3

LPTIM_TriggerConfigTypeDef ....................................................... 498

38.1.4

LPTIM_InitTypeDef......................................................................... 499

38.1.5

LPTIM_HandleTypeDef .................................................................. 499

DocID025834 Rev 4

13/964

Contents

UM1725

38.2

38.3

LPTIM Firmware driver API description ......................................... 500
38.2.1

How to use this driver ..................................................................... 500

38.2.2

Initialization and de-initialization functions ..................................... 501

38.2.3

LPTIM Start Stop operation functions ............................................ 501

38.2.4

LPTIM Read operation functions .................................................... 502

38.2.5

LPTIM IRQ handler ......................................................................... 502

38.2.6

Peripheral State functions .............................................................. 503

38.2.7

Detailed description of functions .................................................... 503

LPTIM Firmware driver defines ..................................................... 511
38.3.1

39

HAL LTDC Generic Driver ........................................................... 521
39.1

39.2

39.3

LTDC Firmware driver registers structures.................................... 521
39.1.1

LTDC_ColorTypeDef ...................................................................... 521

39.1.2

LTDC_InitTypeDef .......................................................................... 521

39.1.3

LTDC_LayerCfgTypeDef ................................................................ 522

39.1.4

LTDC_HandleTypeDef ................................................................... 524

LTDC Firmware driver API description .......................................... 524
39.2.1

How to use this driver ..................................................................... 524

39.2.2

Initialization and Configuration functions ........................................ 525

39.2.3

IO operation functions .................................................................... 525

39.2.4

Peripheral Control functions ........................................................... 526

39.2.5

Peripheral State and Errors functions ............................................ 527

39.2.6

Detailed description of functions .................................................... 527

LTDC Firmware driver defines ...................................................... 537
39.3.1

40

LTDCEx Firmware driver API description ...................................... 542
40.1.1

Initialization and Configuration functions ........................................ 542

40.1.2

Detailed description of functions .................................................... 542

HAL NAND Generic Driver .......................................................... 543
41.1

41.2

NAND Firmware driver registers structures ................................... 543
41.1.1

NAND_IDTypeDef .......................................................................... 543

41.1.2

NAND_AddressTypeDef................................................................. 543

41.1.3

NAND_InfoTypeDef ........................................................................ 543

41.1.4

NAND_HandleTypeDef .................................................................. 544

NAND Firmware driver API description ......................................... 544
41.2.1

14/964

LTDC .............................................................................................. 537

HAL LTDC Extension Driver ....................................................... 542
40.1

41

LPTIM ............................................................................................. 511

How to use this driver ..................................................................... 544

DocID025834 Rev 4

UM1725

Contents

41.3

41.2.2

NAND Initialization and de-initialization functions .......................... 545

41.2.3

NAND Input and Output functions .................................................. 545

41.2.4

NAND Control functions ................................................................. 546

41.2.5

NAND State functions..................................................................... 546

41.2.6

Detailed description of functions .................................................... 546

NAND Firmware driver defines...................................................... 550
41.3.1

42

HAL NOR Generic Driver............................................................. 552
42.1

42.2

42.3

NOR Firmware driver registers structures ..................................... 552
42.1.1

NOR_IDTypeDef ............................................................................ 552

42.1.2

NOR_CFITypeDef .......................................................................... 552

42.1.3

NOR_HandleTypeDef..................................................................... 553

NOR Firmware driver API description ........................................... 553
42.2.1

How to use this driver ..................................................................... 553

42.2.2

NOR Initialization and de_initialization functions ........................... 554

42.2.3

NOR Input and Output functions .................................................... 554

42.2.4

NOR Control functions.................................................................... 554

42.2.5

NOR State functions ....................................................................... 554

42.2.6

Detailed description of functions .................................................... 555

NOR Firmware driver defines ........................................................ 559
42.3.1

43

NOR ................................................................................................ 559

HAL PCCARD Generic Driver ..................................................... 560
43.1

PCCARD Firmware driver registers structures .............................. 560
43.1.1

43.2

43.3

PCCARD_HandleTypeDef ............................................................. 560

PCCARD Firmware driver API description .................................... 560
43.2.1

How to use this driver ..................................................................... 560

43.2.2

PCCARD Initialization and de-initialization functions ..................... 561

43.2.3

PCCARD Input and Output functions ............................................. 561

43.2.4

PCCARD State functions................................................................ 561

43.2.5

Detailed description of functions .................................................... 561

PCCARD Firmware driver defines................................................. 565
43.3.1

44

NAND.............................................................................................. 550

PCCARD ........................................................................................ 565

HAL PCD Generic Driver ............................................................. 566
44.1

PCD Firmware driver registers structures ..................................... 566
44.1.1

44.2

PCD_HandleTypeDef ..................................................................... 566

PCD Firmware driver API description ............................................ 567
44.2.1

How to use this driver ..................................................................... 567

DocID025834 Rev 4

15/964

Contents

UM1725

44.3

44.2.2

Initialization and de-initialization functions ..................................... 567

44.2.3

IO operation functions .................................................................... 567

44.2.4

Peripheral Control functions ........................................................... 568

44.2.5

Peripheral State functions .............................................................. 568

44.2.6

Detailed description of functions .................................................... 568

PCD Firmware driver defines ........................................................ 574
44.3.1

45

HAL PCD Extension Driver ......................................................... 577
45.1

46

PCDEx Firmware driver API description ....................................... 577
45.1.1

Extended features functions ........................................................... 577

45.1.2

Detailed description of functions .................................................... 577

HAL PWR Generic Driver ............................................................ 579
46.1

PWR Firmware driver registers structures .................................... 579
46.1.1

46.2

46.3

46.2.1

Initialization and de-initialization functions ..................................... 579

46.2.2

Peripheral Control functions ........................................................... 579

46.2.3

Detailed description of functions .................................................... 581

PWR Firmware driver defines ....................................................... 586

47.2

PWREx Firmware driver API description ....................................... 592
47.1.1

Peripheral extended features functions .......................................... 592

47.1.2

Detailed description of functions .................................................... 593

PWREx Firmware driver defines ................................................... 596
47.2.1

PWREx ........................................................................................... 596

HAL QSPI Generic Driver ............................................................ 600
48.1

48.2

16/964

PWR ............................................................................................... 586

HAL PWR Extension Driver ........................................................ 592
47.1

48

PWR_PVDTypeDef ........................................................................ 579

PWR Firmware driver API description ........................................... 579

46.3.1

47

PCD ................................................................................................ 574

QSPI Firmware driver registers structures .................................... 600
48.1.1

QSPI_InitTypeDef ........................................................................... 600

48.1.2

QSPI_HandleTypeDef .................................................................... 600

48.1.3

QSPI_CommandTypeDef ............................................................... 601

48.1.4

QSPI_AutoPollingTypeDef ............................................................. 602

48.1.5

QSPI_MemoryMappedTypeDef ..................................................... 602

QSPI Firmware driver API description ........................................... 602
48.2.1

How to use this driver ..................................................................... 602

48.2.2

Initialization and Configuration functions ........................................ 605

48.2.3

IO operation functions .................................................................... 605

DocID025834 Rev 4

UM1725

Contents

48.3

48.2.4

Peripheral Control and State functions ........................................... 606

48.2.5

Detailed description of functions .................................................... 606

QSPI Firmware driver defines ....................................................... 614
48.3.1

49

HAL RCC Generic Driver ............................................................. 620
49.1

49.2

49.3

RCC Firmware driver registers structures ..................................... 620
49.1.1

RCC_OscInitTypeDef ..................................................................... 620

49.1.2

RCC_ClkInitTypeDef ...................................................................... 620

RCC Firmware driver API description ........................................... 621
49.2.1

RCC specific features ..................................................................... 621

49.2.2

RCC Limitations .............................................................................. 621

49.2.3

Initialization and de-initialization functions ..................................... 622

49.2.4

Peripheral Control functions ........................................................... 623

49.2.5

Detailed description of functions .................................................... 623

RCC Firmware driver defines ........................................................ 628
49.3.1

50

RCC ................................................................................................ 628

HAL RCC Extension Driver ......................................................... 646
50.1

50.2

50.3

RCCEx Firmware driver registers structures ................................. 646
50.1.1

RCC_PLLInitTypeDef ..................................................................... 646

50.1.2

RCC_PLLI2SInitTypeDef................................................................ 646

50.1.3

RCC_PLLSAIInitTypeDef ............................................................... 647

50.1.4

RCC_PeriphCLKInitTypeDef .......................................................... 648

RCCEx Firmware driver API description ....................................... 649
50.2.1

Extended Peripheral Control functions ........................................... 649

50.2.2

Detailed description of functions .................................................... 649

RCCEx Firmware driver defines .................................................... 650
50.3.1

51

QSPI ............................................................................................... 614

RCCEx ............................................................................................ 650

HAL RNG Generic Driver............................................................. 674
51.1

RNG Firmware driver registers structures ..................................... 674
51.1.1

51.2

51.3

RNG_HandleTypeDef..................................................................... 674

RNG Firmware driver API description ........................................... 674
51.2.1

How to use this driver ..................................................................... 674

51.2.2

Initialization and de-initialization functions ..................................... 674

51.2.3

Peripheral Control functions ........................................................... 675

51.2.4

Peripheral State functions .............................................................. 675

51.2.5

Detailed description of functions .................................................... 675

RNG Firmware driver defines ........................................................ 678

DocID025834 Rev 4

17/964

Contents

UM1725

51.3.1

52

HAL RTC Generic Driver ............................................................. 681
52.1

52.2

52.3

RTC Firmware driver registers structures ..................................... 681
52.1.1

RTC_InitTypeDef ............................................................................ 681

52.1.2

RTC_TimeTypeDef......................................................................... 681

52.1.3

RTC_DateTypeDef ......................................................................... 682

52.1.4

RTC_AlarmTypeDef ....................................................................... 683

52.1.5

RTC_HandleTypeDef ..................................................................... 683

RTC Firmware driver API description ............................................ 684
52.2.1

Backup Domain Operating Condition ............................................. 684

52.2.2

Backup Domain Reset .................................................................... 684

52.2.3

Backup Domain Access.................................................................. 685

52.2.4

How to use this driver ..................................................................... 685

52.2.5

RTC and low power modes ............................................................ 685

52.2.6

Initialization and de-initialization functions ..................................... 685

52.2.7

RTC Time and Date functions ........................................................ 686

52.2.8

RTC Alarm functions ...................................................................... 686

52.2.9

Peripheral Control functions ........................................................... 686

52.2.10

Peripheral State functions .............................................................. 687

52.2.11

Detailed description of functions .................................................... 687

RTC Firmware driver defines ........................................................ 692
52.3.1

53

RTCEx Firmware driver registers structures ................................. 703
53.1.1

53.2

53.3

RTC_TamperTypeDef .................................................................... 703

RTCEx Firmware driver API description ........................................ 704
53.2.1

How to use this driver ..................................................................... 704

53.2.2

RTC TimeStamp and Tamper functions ......................................... 705

53.2.3

RTC Wake-up functions ................................................................. 705

53.2.4

Extension Peripheral Control functions .......................................... 705

53.2.5

Extended features functions ........................................................... 706

53.2.6

Detailed description of functions .................................................... 706

RTCEx Firmware driver defines .................................................... 716
53.3.1

RTCEx ............................................................................................ 716

HAL SAI Generic Driver .............................................................. 732
54.1

SAI Firmware driver registers structures ....................................... 732
54.1.1

18/964

RTC ................................................................................................ 692

HAL RTC Extension Driver ......................................................... 703
53.1

54

RNG ................................................................................................ 678

SAI_InitTypeDef ............................................................................. 732

DocID025834 Rev 4

UM1725

Contents

54.2

54.3

54.1.2

SAI_FrameInitTypeDef ................................................................... 733

54.1.3

SAI_SlotInitTypeDef ....................................................................... 734

54.1.4

__SAI_HandleTypeDef ................................................................... 734

SAI Firmware driver API description ............................................. 735
54.2.1

How to use this driver ..................................................................... 735

54.2.2

Initialization and de-initialization functions ..................................... 738

54.2.3

IO operation functions .................................................................... 738

54.2.4

Peripheral State and Errors functions ............................................ 739

54.2.5

Detailed description of functions .................................................... 739

SAI Firmware driver defines .......................................................... 745
54.3.1

55

HAL SAI Extension Driver ........................................................... 753
55.1

56

SAIEx Firmware driver API description ......................................... 753
55.1.1

SAI peripheral extension features .................................................. 753

55.1.2

How to use this driver ..................................................................... 753

55.1.3

Extension features Functions ......................................................... 753

55.1.4

Detailed description of functions .................................................... 753

HAL SDRAM Generic Driver ....................................................... 754
56.1

SDRAM Firmware driver registers structures ................................ 754
56.1.1

56.2

56.3

SDRAM_HandleTypeDef................................................................ 754

SDRAM Firmware driver API description ...................................... 754
56.2.1

How to use this driver ..................................................................... 754

56.2.2

SDRAM Initialization and de_initialization functions ...................... 755

56.2.3

SDRAM Input and Output functions ............................................... 755

56.2.4

SDRAM Control functions............................................................... 755

56.2.5

SDRAM State functions .................................................................. 756

56.2.6

Detailed description of functions .................................................... 756

SDRAM Firmware driver defines ................................................... 761
56.3.1

57

SAI .................................................................................................. 745

SDRAM ........................................................................................... 761

HAL SD Generic Driver ............................................................... 762
57.1

57.2

SD Firmware driver registers structures ........................................ 762
57.1.1

SD_HandleTypeDef........................................................................ 762

57.1.2

HAL_SD_CSDTypedef ................................................................... 763

57.1.3

HAL_SD_CIDTypedef .................................................................... 765

57.1.4

HAL_SD_CardStatusTypedef ........................................................ 766

57.1.5

HAL_SD_CardInfoTypedef ............................................................. 766

SD Firmware driver API description .............................................. 767

DocID025834 Rev 4

19/964

Contents

UM1725

57.3

57.2.1

How to use this driver ..................................................................... 767

57.2.2

Initialization and de-initialization functions ..................................... 769

57.2.3

IO operation functions .................................................................... 769

57.2.4

Peripheral Control functions ........................................................... 770

57.2.5

Peripheral State functions .............................................................. 770

57.2.6

Detailed description of functions .................................................... 770

SD Firmware driver defines ........................................................... 776
57.3.1

58

HAL SMARTCARD Generic Driver.............................................. 787
58.1

58.2

58.3

SMARTCARD Firmware driver registers structures ...................... 787
58.1.1

SMARTCARD_InitTypeDef ............................................................ 787

58.1.2

SMARTCARD_HandleTypeDef ...................................................... 788

SMARTCARD Firmware driver API description............................. 789
58.2.1

How to use this driver ..................................................................... 789

58.2.2

Initialization and Configuration functions ........................................ 790

58.2.3

IO operation functions .................................................................... 791

58.2.4

Peripheral State and Errors functions ............................................ 793

58.2.5

Detailed description of functions .................................................... 793

SMARTCARD Firmware driver defines ......................................... 797
58.3.1

59

59.2

59.3

SPDIFRX Firmware driver registers structures ............................. 805
59.1.1

SPDIFRX_InitTypeDef.................................................................... 805

59.1.2

SPDIFRX_SetDataFormatTypeDef ................................................ 806

59.1.3

SPDIFRX_HandleTypeDef ............................................................. 806

SPDIFRX Firmware driver API description .................................... 807
59.2.1

How to use this driver ..................................................................... 807

59.2.2

Initialization and de-initialization functions ..................................... 809

59.2.3

IO operation functions .................................................................... 809

59.2.4

Peripheral State and Errors functions ............................................ 810

59.2.5

Detailed description of functions .................................................... 810

SPDIFRX Firmware driver defines ................................................ 814
59.3.1

SPDIFRX ........................................................................................ 814

HAL SPI Generic Driver ............................................................... 820
60.1

20/964

SMARTCARD ................................................................................. 797

HAL SPDIFRX Generic Driver ..................................................... 805
59.1

60

SD ................................................................................................... 776

SPI Firmware driver registers structures ....................................... 820
60.1.1

SPI_InitTypeDef ............................................................................. 820

60.1.2

__SPI_HandleTypeDef ................................................................... 821

DocID025834 Rev 4

UM1725

Contents

60.2

60.3

SPI Firmware driver API description ............................................. 822
60.2.1

How to use this driver ..................................................................... 822

60.2.2

Initialization and de-initialization functions ..................................... 823

60.2.3

IO operation functions .................................................................... 823

60.2.4

Peripheral State and Errors functions ............................................ 824

60.2.5

Detailed description of functions .................................................... 824

SPI Firmware driver defines .......................................................... 830
60.3.1

61

HAL SRAM Generic Driver .......................................................... 835
61.1

SRAM Firmware driver registers structures................................... 835
61.1.1

61.2

61.3

SRAM_HandleTypeDef .................................................................. 835

SRAM Firmware driver API description ......................................... 835
61.2.1

How to use this driver ..................................................................... 835

61.2.2

SRAM Initialization and de_initialization functions ......................... 836

61.2.3

SRAM Input and Output functions .................................................. 836

61.2.4

SRAM Control functions ................................................................. 836

61.2.5

SRAM State functions .................................................................... 837

61.2.6

Detailed description of functions .................................................... 837

SRAM Firmware driver defines ..................................................... 841
61.3.1

62

SPI .................................................................................................. 830

SRAM ............................................................................................. 841

HAL TIM Generic Driver .............................................................. 842
62.1

62.2

TIM Firmware driver registers structures ....................................... 842
62.1.1

TIM_Base_InitTypeDef ................................................................... 842

62.1.2

TIM_OC_InitTypeDef...................................................................... 842

62.1.3

TIM_OnePulse_InitTypeDef ........................................................... 843

62.1.4

TIM_IC_InitTypeDef ....................................................................... 844

62.1.5

TIM_Encoder_InitTypeDef ............................................................. 845

62.1.6

TIM_ClockConfigTypeDef .............................................................. 845

62.1.7

TIM_ClearInputConfigTypeDef ....................................................... 846

62.1.8

TIM_SlaveConfigTypeDef .............................................................. 846

62.1.9

TIM_HandleTypeDef ...................................................................... 847

TIM Firmware driver API description ............................................. 847
62.2.1

TIMER Generic features ................................................................. 847

62.2.2

How to use this driver ..................................................................... 848

62.2.3

Time Base functions ....................................................................... 849

62.2.4

Time Output Compare functions .................................................... 849

62.2.5

Time PWM functions ...................................................................... 849

62.2.6

Time Input Capture functions ......................................................... 850

DocID025834 Rev 4

21/964

Contents

UM1725

62.3

62.2.7

Time One Pulse functions .............................................................. 850

62.2.8

Time Encoder functions .................................................................. 851

62.2.9

IRQ handler management .............................................................. 851

62.2.10

Peripheral Control functions ........................................................... 851

62.2.11

TIM Callbacks functions ................................................................. 852

62.2.12

Peripheral State functions .............................................................. 852

62.2.13

Detailed description of functions .................................................... 852

TIM Firmware driver defines.......................................................... 878
62.3.1

63

HAL TIM Extension Driver........................................................... 893
63.1

63.2

63.3

TIMEx Firmware driver registers structures................................... 893
63.1.1

TIM_HallSensor_InitTypeDef ......................................................... 893

63.1.2

TIM_MasterConfigTypeDef ............................................................ 893

63.1.3

TIM_BreakDeadTimeConfigTypeDef ............................................. 894

TIMEx Firmware driver API description ......................................... 894
63.2.1

TIMER Extended features .............................................................. 894

63.2.2

How to use this driver ..................................................................... 895

63.2.3

Timer Hall Sensor functions ........................................................... 895

63.2.4

Timer Complementary Output Compare functions ......................... 896

63.2.5

Timer Complementary PWM functions ........................................... 896

63.2.6

Timer Complementary One Pulse functions................................... 897

63.2.7

Peripheral Control functions ........................................................... 897

63.2.8

Extension Callbacks functions ........................................................ 897

63.2.9

Extension Peripheral State functions ............................................. 897

63.2.10

Detailed description of functions .................................................... 898

TIMEx Firmware driver defines ..................................................... 909
63.3.1

64

TIMEx ............................................................................................. 909

HAL UART Generic Driver........................................................... 910
64.1

64.2

22/964

TIM.................................................................................................. 878

UART Firmware driver registers structures ................................... 910
64.1.1

UART_InitTypeDef ......................................................................... 910

64.1.2

UART_HandleTypeDef ................................................................... 911

UART Firmware driver API description ......................................... 912
64.2.1

How to use this driver ..................................................................... 912

64.2.2

Initialization and Configuration functions ........................................ 914

64.2.3

IO operation functions .................................................................... 914

64.2.4

Peripheral Control functions ........................................................... 915

64.2.5

Peripheral State and Errors functions ............................................ 916

64.2.6

Detailed description of functions .................................................... 916

DocID025834 Rev 4

UM1725

Contents

64.3

UART Firmware driver defines ...................................................... 923
64.3.1

65

HAL USART Generic Driver ........................................................ 933
65.1

65.2

65.3

USART Firmware driver registers structures ................................. 933
65.1.1

USART_InitTypeDef ....................................................................... 933

65.1.2

USART_HandleTypeDef ................................................................ 934

USART Firmware driver API description ....................................... 934
65.2.1

How to use this driver ..................................................................... 934

65.2.2

Initialization and Configuration functions ........................................ 936

65.2.3

IO operation functions .................................................................... 937

65.2.4

Peripheral State and Errors functions ............................................ 938

65.2.5

Detailed description of functions .................................................... 938

USART Firmware driver defines.................................................... 944
65.3.1

66

UART .............................................................................................. 923

USART............................................................................................ 944

HAL WWDG Generic Driver ........................................................ 952
66.1

66.2

66.3

WWDG Firmware driver registers structures ................................. 952
66.1.1

WWDG_InitTypeDef ....................................................................... 952

66.1.2

WWDG_HandleTypeDef ................................................................ 952

WWDG Firmware driver API description ....................................... 953
66.2.1

WWDG specific features ................................................................ 953

66.2.2

How to use this driver ..................................................................... 953

66.2.3

Initialization and Configuration functions ........................................ 954

66.2.4

IO operation functions .................................................................... 954

66.2.5

Detailed description of functions .................................................... 954

WWDG Firmware driver defines.................................................... 955
66.3.1

WWDG............................................................................................ 955

67

FAQs............................................................................................. 959

68

Revision history .......................................................................... 963

DocID025834 Rev 4

23/964

Acronyms and definitions

UM1725

List of tables
Table 1: Acronyms and definitions ....................................................................................... 26
Table 2: HAL driver files ....................................................................................................... 28
Table 3: User-application files .............................................................................................. 30
Table 4: API classification .................................................................................................... 34
Table 5: List of devices supported by HAL drivers ............................................................... 35
Table 6: HAL API naming rules ............................................................................................ 37
Table 7: Macros handling interrupts and specific clock configurations ................................ 38
Table 8: Callback functions .................................................................................................. 39
Table 9: HAL generic APIs ................................................................................................... 40
Table 10: HAL extension APIs ............................................................................................. 41
Table 11: Define statements used for HAL configuration .................................................... 45
Table 12: Description of GPIO_InitTypeDef structure .......................................................... 48
Table 13: Description of EXTI configuration macros ............................................................ 51
Table 14: MSP functions ...................................................................................................... 57
Table 15: Timeout values ..................................................................................................... 60
Table 16: Document revision history .................................................................................. 963

24/964

DocID025834 Rev 4

UM1725

Acronyms and definitions

List of figures
Figure 1: Example of project template ................................................................................. 31
Figure 2: Adding device-specific functions ........................................................................... 42
Figure 3: Adding family-specific functions ............................................................................ 42
Figure 4: Adding new peripherals ........................................................................................ 43
Figure 5: Updating existing APIs .......................................................................................... 43
Figure 6: File inclusion model............................................................................................... 44
Figure 7: HAL driver model .................................................................................................. 54

DocID025834 Rev 4

25/964

Acronyms and definitions

1

UM1725

Acronyms and definitions
Table 1: Acronyms and definitions

26/964

Acronym

Definition

ADC

Analog-to-digital converter

ANSI

American National Standards Institute

API

Application Programming Interface

BSP

Board Support Package

CAN

Controller area network

CEC

Consumer Electronics Control

CMSIS

Cortex Microcontroller Software Interface Standard

CPU

Central Processing Unit

CRYP

Cryptographic processor unit

CRC

CRC calculation unit

DAC

Digital to analog converter

DCMI

Digital Camera Module Interface

DFSDM

Digital filter for sigma delta modulators

DMA

Direct Memory Access

DMA2D

Chrom-Art Accelerator™ controller

DSI

Display Serial Interface

ETH

Ethernet controller

EXTI

External interrupt/event controller

FLASH

Flash memory

FSMC

Flexible Static Memory controller

FMC

Flexible Memory controller

FMPI2C

Fast-mode Plus inter-integrated circuit

GPIO

General purpose I/Os

HAL

Hardware abstraction layer

HASH

Hash processor

HCD

USB Host Controller Driver

I2C

Inter-integrated circuit

I2S

Inter-integrated sound

IRDA

InfraRed Data Association

IWDG

Independent watchdog

LPTIM

Low-power Timer

LTDC

LCD TFT Display Controller

MSP

MCU Specific Package

NAND

NAND external Flash memory

DocID025834 Rev 4

UM1725

Acronyms and definitions
Acronym

Definition

NOR

NOR external Flash memory

NVIC

Nested Vectored Interrupt Controller

PCCARD

PCCARD external memory

PCD

USB Peripheral Controller Driver

PWR

Power controller

QSPI

QuadSPI Flash memory Interface

RCC

Reset and clock controller

RNG

Random Number Generator

RTC

Real-time clock

SAI

Serial Audio Interface

SD

Secure Digital

SDRAM

SDRAM external memory

SRAM

SRAM external memory

SMARTCARD

Smartcard IC

SPDIFRX

SPDIF-RX Receiver Interface

SPI

Serial Peripheral interface

SysTick

System tick timer

TIM

Advanced-control, general-purpose or basic timer

UART

Universal asynchronous receiver/transmitter

USART

Universal synchronous receiver/transmitter

WWDG

Window watchdog

USB

Universal Serial Bus

PPP

STM32 peripheral or block

DocID025834 Rev 4

27/964

Overview of HAL drivers

2

UM1725

Overview of HAL drivers
The HAL drivers were designed to offer a rich set of APIs and to interact easily with the
application upper layers.
Each driver consists of a set of functions covering the most common peripheral features.
The development of each driver is driven by a common API which standardizes the driver
structure, the functions and the parameter names.
The HAL drivers consist of a set of driver modules, each module being linked to standalone
peripheral. However, in some cases, the module is linked to a peripheral functional mode.
As an example, several modules exist for the USART peripheral: UART driver module,
USART driver module, SMARTCARD driver module and IRDA driver module.
The HAL main features are the following:
Cross-family portable set of APIs covering the common peripheral features as well as
extension APIs in case 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.
Peripheral multi-instance support allowing concurrent API calls for multiple instances
of a given peripheral (USART1, USART2...)
All HAL APIs implement user-callback functions mechanism:
Peripheral Init/DeInit HAL APIs can call user-callback functions to perform
peripheral system level Initialization/De-Initialization (clock, GPIOs, interrupt,
DMA)
Peripherals interrupt events
Error events.
Object locking mechanism: safe hardware access to prevent multiple spurious
accesses to shared resources.
Timeout used for all blocking processes: the timeout can be a simple counter or a
timebase.

2.1

HAL and user-application files

2.1.1

HAL driver files
HAL drivers are composed of the following set of files:
Table 2: HAL driver files
File

28/964

Description

stm32f4xx_hal_ppp.c

Main peripheral/module driver file.
It includes the APIs that are common to all STM32 devices.
Example: stm32f4xx_hal_adc.c, stm32f4xx_hal_irda.c, …

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.
Example: stm32f4xx_hal_adc.h, stm32f4xx_hal_irda.h, …

DocID025834 Rev 4

UM1725

Overview of HAL drivers
File

Description

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.
Example: stm32f4xx_hal_adc_ex.c, stm32f4xx_hal_dma_ex.c, …

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
Example: stm32f4xx_hal_adc_ex.h, stm32f4xx_hal_dma_ex.h, …

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.
Example: stm32f4xx_ll_fmc.c offers a set of API used by
stm32f4xx_hal_sdram.c, stm32f4xx_hal_sram.c,
stm32f4xx_hal_nor.c, stm32f4xx_hal_nand.c,…

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.
Example: stm32f4xx_ll_fmc.h, stm32f4xx_ll_usb.h,...

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.

Since the low-level drivers are only used by the HAL drivers built upon them, the
APIs provided by these drivers will not be described in this document.

DocID025834 Rev 4

29/964

Overview of HAL drivers

2.1.2

UM1725

User-application files
The minimum files required to build an application using the HAL drivers are listed in the
table below:
Table 3: 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 must be performed
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.
This file contains the main program routine, mainly:

main.c/.h

the call to HAL_Init()
assert_failed() implementation
system clock configuration
peripheral HAL initialization and user application code.

The STM32Cube package comes with ready-to-use project templates, one for each
supported board. Each project contains the files listed above and a preconfigured project
for the supported toolchains.
Each project template provides empty main loop function and can be used as a starting
point to get familiar with project settings for STM32Cube. Their characteristics are the
following:
It contains sources of HAL, CMSIS and BSP drivers which are the minimal
components to develop a code on a given board.
It contains the include paths for all the firmware components.

30/964

DocID025834 Rev 4

UM1725

Overview of HAL drivers
It defines the STM32 device supported, and allows to configure the CMSIS and HAL
drivers accordingly.
It provides ready to use user files preconfigured as defined below:
HAL is initialized
SysTick ISR implemented for HAL_Delay()
System clock configured with the maximum frequency of the device.
If an existing project is copied to another location, then include paths must be
updated.

Figure 1: Example of project template

2.2

HAL data structures
Each HAL driver can contain the following data structures:
Peripheral handle structures
Initialization and configuration structures
Specific process structures.

DocID025834 Rev 4

31/964

Overview of HAL drivers

2.2.1

UM1725

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.
An example of peripheral structure is shown below:
typedef struct
{
USART_TypeDef
*Instance; /* USART registers base address
*/
USART_InitTypeDef
Init;
/* Usart communication parameters */
uint8_t
*pTxBuffPtr;/* Pointer to Usart Tx transfer Buffer */
uint16_t
TxXferSize; /* Usart Tx Transfer size
*/
__IO uint16_t
TxXferCount;/* Usart Tx Transfer Counter
*/
uint8_t
*pRxBuffPtr;/* Pointer to Usart Rx transfer Buffer */
uint16_t
RxXferSize; /* Usart Rx Transfer size
*/
__IO uint16_t
RxXferCount; /* Usart Rx Transfer Counter
*/
DMA_HandleTypeDef
*hdmatx;
/* Usart Tx DMA Handle parameters */
DMA_HandleTypeDef
*hdmarx;
/* Usart Rx DMA Handle parameters */
HAL_LockTypeDef
Lock;
/* Locking object
*/
__IO HAL_USART_StateTypeDef State; /* Usart communication state
*/
__IO HAL_USART_ErrorTypeDef ErrorCode;/* USART Error code
*/
}USART_HandleTypeDef;

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.

32/964

DocID025834 Rev 4

UM1725

Overview of HAL drivers
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.

2.2.2

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.
typedef struct
{
uint32_t BaudRate;
/*!< This member configures the UART communication baudrate.*/
uint32_t WordLength; /*!< Specifies the number of data bits transmitted or received
in a frame.*/
uint32_t StopBits;
/*!< Specifies the number of stop bits transmitted.*/
uint32_t Parity;
/*!< Specifies the parity mode. */
uint32_t Mode;
/*!< Specifies wether the Receive or Transmit mode is enabled or
disabled.*/
uint32_t HwFlowCtl; /*!< Specifies wether the hardware flow control mode is enabled
or disabled.*/
uint32_t OverSampling; /*!< Specifies wether the Over sampling 8 is enabled or
disabled,
to achieve higher speed (up to fPCLK/8).*/
}UART_InitTypeDef;

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)

2.2.3

Specific process structures
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)

2.3

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.
HAL_StatusTypeDef HAL_ADC_Init(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef
HAL_ADC_DeInit(ADC_HandleTypeDef *hadc); HAL_StatusTypeDef
HAL_ADC_Start(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef
HAL_ADC_Stop(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef
HAL_ADC_Start_IT(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef
HAL_ADC_Stop_IT(ADC_HandleTypeDef* hadc); void HAL_ADC_IRQHandler(ADC_HandleTypeDef*
hadc);

DocID025834 Rev 4

33/964

Overview of HAL drivers

UM1725

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).
HAL_StatusTypeDef HAL_ADCEx_InjectedStop(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef
HAL_ADCEx_InjectedStop_IT(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef
HAL_ADCEx_InjectedStart(ADC_HandleTypeDef* hadc); HAL_StatusTypeDef
HAL_ADCEx_InjectedStart_IT(ADC_HandleTypeDef* hadc);

Device part number specific APIs: These APIs are implemented in the
extension file and delimited by specific define statements relative to a given part
number.
#if defined(STM32F427xx) || defined(STM32F437xx) || defined(STM32F429xx) ||
defined(STM32F439xx) HAL_StatusTypeDef HAL_FLASHEx_OB_SelectPCROP(void);
HAL_StatusTypeDef HAL_FLASHEx_OB_DeSelectPCROP(void);
#endif /* STM32F427xx || STM32F437xx || STM32F429xx || STM32F439xx || */

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.
The following table summarizes the location of the different categories of HAL APIs in the
driver files.
Table 4: API classification
Generic file
Common APIs

X

Extension file
X

(1)

Family specific APIs

X

Device specific APIs

X

Notes:
(1)

In some cases, the implementation for a specific device part number may change . In this case the generic API
is declared as weak function in the extension file. The API is implemented again to overwrite the default function

Family specific APIs are only related to a given family. This means that if a
specific API is implemented in another family, and the arguments of this latter
family are different, additional structures and arguments might need to be added.

The IRQ handlers are used for common and family specific processes.

34/964

DocID025834 Rev 4

UM1725

Devices supported by HAL drivers

STM32F405xx

STM32F415xx

STM32F407xx

STM32F417xx

STM32F427xx

STM32F437xx

STM32F429xx

STM32F439xx

STM32F401xC

STM32F401xE

STM32F446xx

STM32F469xx

STM32F479xx

STM32F410xx

STM32F412xx

Table 5: List of devices supported by HAL drivers

stm32f4xx_hal.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_adc.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_adc_ex.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_can.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_cec.c

No

No

No

No

No

No

No

No

No

No

Yes

No

No

No

No

stm32f4xx_hal_cortex.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_crc.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_cryp.c

No

Yes

No

Yes

No

Yes

No

Yes

No

No

No

No

Yes

No

No

stm32f4xx_hal_cryp_ex.
c

No

Yes

No

Yes

No

Yes

No

Yes

No

No

No

No

Yes

No

No

stm32f4xx_hal_dac.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

Yes

No

stm32f4xx_hal_dac_ex.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

Yes

No

stm32f4xx_hal_dcmi.c

No

No

Yes

Yes

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

No

No

stm32f4xx_hal_dcmi_ex.
c

No

No

Yes

Yes

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

No

No

stm32f4xx_hal_dfsdm.c

No

No

No

No

No

No

No

No

No

No

No

No

No

No

Yes

stm32f4xx_hal_dma.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_dma2d.c

No

No

No

No

Yes

Yes

Yes

Yes

No

No

No

Yes

Yes

No

No

stm32f4xx_hal_dma_ex.
c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_dsi.c

No

No

No

No

No

No

No

No

No

No

No

Yes

Yes

No

No

stm32f4xx_hal_eth.c

No

No

Yes

Yes

Yes

Yes

Yes

Yes

No

No

No

Yes

Yes

No

No

stm32f4xx_hal_flash.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_flash_ex.
c

No

No

No

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_flash_
ramfunc.c

No

No

No

No

No

No

No

No

No

No

Yes

No

No

Yes

Yes

stm32f4xx_hal_fmpi2c.c

No

No

No

No

No

No

No

No

No

No

No

No

Yes

Yes

stm32f4xx_hal_fmpi2c_
ex.c

No

No

No

No

No

No

No

No

No

No

No

No

Yes

Yes

stm32f4xx_hal_gpio.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_hash.c

No

Yes

No

Yes

No

Yes

No

Yes

No

No

No

No

Yes

No

No

stm32f4xx_hal_hash_ex.
c

No

No

No

No

No

Yes

No

Yes

No

No

No

No

Yes

No

No

stm32f4xx_hal_hcd.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

stm32f4xx_hal_i2c.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_i2c_ex.c

No

No

No

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_i2s.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

IP/Module

2.4

Overview of HAL drivers

DocID025834 Rev 4

Yes
Yes

35/964

STM32F407xx

STM32F417xx

STM32F427xx

STM32F437xx

STM32F429xx

STM32F439xx

STM32F401xC

STM32F401xE

STM32F446xx

STM32F469xx

STM32F479xx

STM32F410xx

STM32F412xx

stm32f4xx_hal_i2s_ex.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

stm32f4xx_hal_irda.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_iwdg.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_lptim.c

No

No

No

No

No

No

No

No

No

No

No

No

No

Yes

No

stm32f4xx_hal_ltdc.c

No

No

No

No

No

No

Yes

Yes

No

No

No

Yes

Yes

No

No

stm32f4xx_hal_ltdc_ex.c

No

No

No

No

No

No

No

No

No

No

No

Yes

Yes

No

No

stm32f4xx_hal_msp_
template.c

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

NA

stm32f4xx_hal_nand.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

No

No

stm32f4xx_hal_nor.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

No

Yes

stm32f4xx_hal_pccard.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

No

No

No

No

No

No

stm32f4xx_hal_pcd.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

stm32f4xx_hal_pcd_ex.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

stm32f4xx_hal_pwr.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_pwr_ex.c

No

No

No

No

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_qspi.c

No

No

No

No

No

No

No

No

No

No

Yes

Yes

Yes

No

Yes

stm32f4xx_hal_rcc.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_rcc_ex.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_rng.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

Yes

Yes

Yes

stm32f4xx_hal_rtc.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_rtc_ex.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_sai.c

No

No

No

No

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

No

No

stm32f4xx_hal_sai_ex.c

No

No

No

No

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

No

No

stm32f4xx_hal_sd.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

stm32f4xx_hal_sdram.c

No

No

No

No

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

No

No

stm32f4xx_hal_smartcar
d.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_spdifrx.c

No

No

No

No

No

No

No

No

No

No

Yes

No

No

No

No

stm32f4xx_hal_spi.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_sram.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

No

Yes

stm32f4xx_hal_tim.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_tim_ex.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_uart.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_usart.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_hal_wwdg.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

stm32f4xx_ll_fmc.c

No

No

No

No

Yes

Yes

Yes

Yes

No

No

Yes

Yes

Yes

No

No

stm32f4xx_ll_fsmc.c

Yes

Yes

Yes

Yes

No

No

No

No

No

No

No

No

No

No

Yes

stm32f4xx_ll_sdmmc.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

stm32f4xx_ll_usb.c

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

IP/Module

STM32F415xx

UM1725

STM32F405xx

Overview of HAL drivers

36/964

DocID025834 Rev 4

UM1725

Overview of HAL drivers

2.5

HAL driver rules

2.5.1

HAL API naming rules
The following naming rules are used in HAL drivers:
Table 6: HAL API naming rules

File
names

Generic

Family specific

Device specific

stm32f4xx_hal_ppp (c/h)

stm32f4xx_hal_ppp_ex (c/h)

stm32f4xx_ hal_ppp_ex (c/h)

Module
name

HAL_PPP_ MODULE

Functio
n name

HAL_PPP_Function
HAL_PPP_FeatureFunction_
MODE

HAL_PPPEx_Function
HAL_PPPEx_FeatureFunction_
MODE

HAL_PPPEx_Function
HAL_PPPEx_FeatureFunction_
MODE

Handle
name

PPP_HandleTypedef

NA

NA

Init
structu
re
name

PPP_InitTypeDef

NA

PPP_InitTypeDef

Enum
name

HAL_PPP_StructnameTypeD
ef

NA

NA

The PPP prefix refers to the peripheral functional mode and not to the peripheral itself.
For example, if the USART, PPP can be USART, IRDA, UART or SMARTCARD
depending on the peripheral mode.
The constants used in one file are defined within this file. A constant used in several
files is defined in a header file. All constants are written in uppercase, except for
peripheral driver function parameters.
typedef variable names should be suffixed with _TypeDef.
Registers are considered as constants. In most cases, their name is in uppercase and
uses the same acronyms as in the STM32F4xx reference manuals.
Peripheral registers are declared in the PPP_TypeDef structure (e.g. ADC_TypeDef)
in stm32f4xxx.h header file.stm32f4xxx.h corresponds to stm32f401xc.h,
stm32f401xe.h, stm32f405xx.h, stm32f415xx.h, stm32f407xx.h, stm32f417xx.h,
stm32f427xx.h, stm32f437xx.h, stm32f429xx.h, stm32f439xx.h, stm32f446xx.h,
stm32f469xx.h, stm32f479xx.h, stm32f410cx.h, stm32f410tx.h, stm32f410rx.h,
stm32f412cx.h, stm32f412rx.h, stm32f412vx.h or stm32f412zx.h.
Peripheral function names are prefixed by HAL_, then the corresponding peripheral
acronym in uppercase followed by an underscore. The first letter of each word is in
uppercase (e.g. HAL_UART_Transmit()). Only one underscore is allowed in a function
name to separate the peripheral acronym from the rest of the function name.
The structure containing the PPP peripheral initialization parameters are named
PPP_InitTypeDef (e.g. ADC_InitTypeDef).
The structure containing the Specific configuration parameters for the PPP peripheral
are named PPP_xxxxConfTypeDef (e.g. ADC_ChannelConfTypeDef).
Peripheral handle structures are named PPP_HandleTypedef (e.g
DMA_HandleTypeDef)
The functions used to initialize the PPP peripheral according to parameters specified
in PPP_InitTypeDef are named HAL_PPP_Init (e.g. HAL_TIM_Init()).

DocID025834 Rev 4

37/964

Overview of HAL drivers

UM1725

The functions used to reset the PPP peripheral registers to their default values are
named PPP_DeInit, e.g. TIM_DeInit.
The MODE suffix refers to the process mode, which can be polling, interrupt or DMA.
As an example, when the DMA is used in addition to the native resources, the function
should be called: HAL_PPP_Function_DMA ().
The Feature prefix should refer to the new feature.
Example: HAL_ADC_InjectionStart() refers to the injection mode

2.5.2

HAL general naming rules
For the shared and system peripherals, no handle or instance object is used. This rule
applies to the following peripherals:
GPIO
SYSTICK
NVIC
RCC
FLASH.
Example: The HAL_GPIO_Init() requires only the GPIO address and its configuration
parameters.
HAL_StatusTypeDef HAL_GPIO_Init (GPIO_TypeDef* GPIOx, GPIO_InitTypeDef *Init)
{
/*GPIO Initialization body */
}

The macros that handle interrupts and specific clock configurations are defined in
each peripheral/module driver. These macros are exported in the peripheral driver
header files so that they can be used by the extension file. The list of these macros is
defined below: This list is not exhaustive and other macros related to peripheral
features can be added, so that they can be used in the user application.
Table 7: Macros handling interrupts and specific clock configurations

38/964

Macros

Description

__HAL_PPP_ENABLE_IT(__HANDLE__, __INTERRUPT__)

Enables a specific peripheral
interrupt

__HAL_PPP_DISABLE_IT(__HANDLE__, __INTERRUPT__)

Disables a specific peripheral
interrupt

__HAL_PPP_GET_IT (__HANDLE__, __ INTERRUPT __)

Gets a specific peripheral interrupt
status

__HAL_PPP_CLEAR_IT (__HANDLE__, __ INTERRUPT __)

Clears a specific peripheral
interrupt status

__HAL_PPP_GET_FLAG (__HANDLE__, __FLAG__)

Gets a specific peripheral flag
status

__HAL_PPP_CLEAR_FLAG (__HANDLE__, __FLAG__)

Clears a specific peripheral flag
status

__HAL_PPP_ENABLE(__HANDLE__)

Enables a peripheral

__HAL_PPP_DISABLE(__HANDLE__)

Disables a peripheral

__HAL_PPP_XXXX (__HANDLE__, __PARAM__)

Specific PPP HAL driver macro

__HAL_PPP_GET_ IT_SOURCE (__HANDLE__, __
INTERRUPT __)

Checks the source of specified
interrupt

DocID025834 Rev 4

UM1725

Overview of HAL drivers
NVIC and SYSTICK are two ARM Cortex core features. The APIs related to these
features are located in the stm32f4xx_hal_cortex.c file.
When a status bit or a flag is read from registers, it is composed of shifted values
depending on the number of read values and of their size. In this case, the returned
status width is 32 bits. Example : STATUS = XX | (YY << 16) or STATUS=".
The PPP handles are valid before using the HAL_PPP_Init() API. The init function
performs a check before modifying the handle fields.
HAL_PPP_Init(PPP_HandleTypeDef) if(hppp == NULL) { return HAL_ERROR; }

The macros defined below are used:
Conditional macro:
#define ABS(x) (((x) > 0) ? (x) : -(x))

Pseudo-code macro (multiple instructions macro):
#define __HAL_LINKDMA(__HANDLE__, __PPP_DMA_FIELD_, __DMA_HANDLE_) \ do{ \
(__HANDLE__)->__PPP_DMA_FIELD_ = &(__DMA_HANDLE_); \ (__DMA_HANDLE_).Parent =
(__HANDLE__); \ } while(0)

2.5.3

HAL interrupt handler and callback functions
Besides the APIs, HAL peripheral drivers include:
HAL_PPP_IRQHandler() peripheral interrupt handler that should be called from
stm32f4xx_it.c
User callback functions.
The user callback functions are defined as empty functions with “weak” attribute. They
have to be defined in the user code.
There are three types of user callbacks functions:
Peripheral system level initialization/ de-Initialization callbacks: HAL_PPP_MspInit()
and HAL_PPP_MspDeInit
Process complete callbacks : HAL_PPP_ProcessCpltCallback
Error callback: HAL_PPP_ErrorCallback.
Table 8: Callback functions
Callback functions

Example

HAL_PPP_MspInit() / _DeInit()

Ex: HAL_USART_MspInit()
Called from HAL_PPP_Init() API function to perform peripheral
system level initialization (GPIOs, clock, DMA, interrupt)

HAL_PPP_ProcessCpltCallback

Ex: HAL_USART_TxCpltCallback
Called by peripheral or DMA interrupt handler when the process
completes

HAL_PPP_ErrorCallback

Ex: HAL_USART_ErrorCallback
Called by peripheral or DMA interrupt handler when an error
occurs

DocID025834 Rev 4

39/964

Overview of HAL drivers

2.6

UM1725

HAL generic APIs
The generic APIs provide common generic functions applying to all STM32 devices. They
are composed of four APIs groups:
Initialization and de-initialization functions:HAL_PPP_Init(), HAL_PPP_DeInit()
IO operation functions: HAL_PPP_Read(), HAL_PPP_Write(),HAL_PPP_Transmit(),
HAL_PPP_Receive()
Control functions:HAL_PPP_Set (), HAL_PPP_Get ().
State and Errors functions: HAL_PPP_GetState (), HAL_PPP_GetError ().
For some peripheral/module drivers, these groups are modified depending on the
peripheral/module implementation.
Example: in the timer driver, the API grouping is based on timer features (PWM, OC, IC...).
The initialization and de-initialization functions allow initializing a peripheral and configuring
the low-level resources, mainly clocks, GPIO, alternate functions (AF) and possibly DMA
and interrupts. The HAL_DeInit()function restores the peripheral default state, frees the
low-level resources and removes any direct dependency with the hardware.
The IO operation functions perform a row access to the peripheral payload data in write
and read modes.
The control functions are used to change dynamically the peripheral configuration and set
another operating mode.
The peripheral state and errors functions allow retrieving in runtime the peripheral and data
flow states, and identifying the type of errors that occurred. The example below is based on
the ADC peripheral. The list of generic APIs is not exhaustive. It is only given as an
example.
Table 9: HAL generic APIs
Function
Group

Common API Name

Description

HAL_ADC_Init()

This function initializes the peripheral and
configures the low -level resources (clocks,
GPIO, AF..)

HAL_ADC_DeInit()

This function restores the peripheral default state,
frees the low-level resources and removes any
direct dependency with the hardware.

HAL_ADC_Start ()

This function starts ADC conversions when the
polling method is used

HAL_ADC_Stop ()

This function stops ADC conversions when the
polling method is used

HAL_ADC_PollForConversion()

This function allows waiting for the end of
conversions when the polling method is used. In
this case, a timout value is specified by the user
according to the application.

HAL_ADC_Start_IT()

This function starts ADC conversions when the
interrupt method is used

HAL_ADC_Stop_IT()

This function stops ADC conversions when the
interrupt method is used

HAL_ADC_IRQHandler()

This function handles ADC interrupt requests

Initialization
group

IO operation
group

40/964

DocID025834 Rev 4

UM1725

Overview of HAL drivers
Function
Group

Common API Name

Description

HAL_ADC_ConvCpltCallback()

Callback function called in the IT subroutine to
indicate the end of the current process or when a
DMA transfer has completed

HAL_ADC_ErrorCallback()

Callback function called in the IT subroutine if a
peripheral error or a DMA transfer error occurred

HAL_ADC_ConfigChannel()

This function configures the selected ADC regular
channel, the corresponding rank in the sequencer
and the sample time

HAL_ADC_AnalogWDGConfig

This function configures the analog watchdog for
the selected ADC

HAL_ADC_GetState()

This function allows getting in runtime the
peripheral and the data flow states.

HAL_ADC_GetError()

This fuction allows getting in runtime the error
that occurred during IT routine

Control group

State and
Errors group

2.7

HAL extension APIs

2.7.1

HAL extension model overview
The extension APIs provide specific functions or overwrite modified APIs for a specific
family (series) or specific part number within the same family.
The extension model consists of an additional file, stm32f4xx_hal_ppp_ex.c, that includes
all the specific functions and define statements (stm32f4xx_hal_ppp_ex.h) for a given part
number.
Below an example based on the ADC peripheral:
Table 10: HAL extension APIs
Function Group

Common API Name

HAL_ADCEx_InjectedStart()

This function starts injected channel ADC conversions when
the polling method is used

HAL_ADCEx_InjectedStop()

This function stops injected channel ADC conversions when
the polling method is used

HAL_ADCEx_InjectedStart_IT()

This function starts injected channel ADC conversions when
the interrupt method is used

HAL_ADCEx_InjectedStop_IT()

This function stops injected channel ADC conversions when
the interrupt method is used

HAL_ADCEx_InjectedConfigChannel()

This function configures the selected ADC Injected channel
(corresponding rank in the sequencer and sample time)

DocID025834 Rev 4

41/964

Overview of HAL drivers

2.7.2

UM1725

HAL extension model cases
The specific IP features can be handled by the HAL drivers in five different ways. They are
described below.

Case1: Adding a part number-specific function
When a new feature specific to a given device is required, the new APIs are added in the
stm32f4xx_hal_ppp_ex.c extension file. They are named HAL_PPPEx_Function().
Figure 2: Adding device-specific functions

Example: stm32f4xx_hal_flash_ex.c/h
#if defined(STM32F427xx) || defined(STM32F437xx) || defined(STM32F429xx)||
defined(STM32F439xx)
HAL_StatusTypeDef HAL_FLASHEx_OB_SelectPCROP(void);
HAL_StatusTypeDef HAL_FLASHEx_OB_DeSelectPCROP(void);
#endif /* STM32F427xx ||STM32F437xx || STM32F429xx || STM32F439xx */

Case2: Adding a family-specific function
In this case, the API is added in the extension driver C file and named
HAL_PPPEx_Function ().
Figure 3: Adding family-specific functions

Example: stm32f4xx_hal_adc_ex.c/h
HAL_StatusTypeDef
HAL_StatusTypeDef
HAL_StatusTypeDef
HAL_StatusTypeDef

42/964

HAL_ADCEx_InjectedStop(ADC_HandleTypeDef* hadc);
HAL_ADCEx_InjectedStop_IT(ADC_HandleTypeDef* hadc);
HAL_ADCEx_InjectedStart(ADC_HandleTypeDef* hadc);
HAL_ADCEx_InjectedStart_IT(ADC_HandleTypeDef* hadc);

DocID025834 Rev 4

UM1725

Overview of HAL drivers

Case3 : Adding a new peripheral (specific to a device belonging to a given
family)
When a peripheral which is available only in a specific device is required, the APIs
corresponding to this new peripheral/module are added in stm32f4xx_hal_newppp.c.
However the inclusion of this file is selected in the stm32fxx_hal_conf.h using the macro:
#define HAL_NEWPPP_MODULE_ENABLED

Figure 4: Adding new peripherals

Example: stm32f4xx_hal_sai.c/h

Case4: Updating existing common APIs
In this case, the routines are defined with the same names in the stm32f4xx_hal_ppp_ex.c
extension file, while the generic API is defined as weak, so that the compiler will overwrite
the original routine by the new defined function.
Figure 5: Updating existing APIs

Case5 : Updating existing data structures
The data structure for a specific device part number (e.g. PPP_InitTypeDef) can have
different fields. In this case, the data structure is defined in the extension header file and
delimited by the specific part number define statement.
Example:
#if defined (STM32F401xx)
typedef struct
{
(…)
}PPP_InitTypeDef;
#endif /* STM32F401xx */

DocID025834 Rev 4

43/964

Overview of HAL drivers

2.8

UM1725

File inclusion model
The header of the common HAL driver file (stm32f4xx_hal.h) includes the common
configurations for the whole HAL library. It is the only header file that is included in the user
sources and the HAL C sources files to be able to use the HAL resources.
Figure 6: File inclusion model

A PPP driver is a standalone module which is used in a project. The user must enable the
corresponding USE_HAL_PPP_MODULE define statement in the configuration file.
/*********************************************************************
* @file stm32f4xx_hal_conf.h
* @author MCD Application Team
* @version VX.Y.Z * @date dd-mm-yyyy
* @brief This file contains the modules to be used
**********************************************************************
(…)
#define USE_HAL_USART_MODULE
#define USE_HAL_IRDA_MODULE
#define USE_HAL_DMA_MODULE
#define USE_HAL_RCC_MODULE
(…)

44/964

DocID025834 Rev 4

UM1725

2.9

Overview of HAL drivers

HAL common resources
The common HAL resources, such as common define enumerations, structures and
macros, are defined in stm32f4xx_hal_def.h.The main common define enumeration is
HAL_StatusTypeDef.
HAL Status: The HAL status is used by almost all HAL APIs, except for boolean
functions and IRQ handler. It returns the status of the current API operations. It has
four possible values as described below:
Typedef enum
{ HAL_OK = 0x00, HAL_ERROR = 0x01, HAL_BUSY = 0x02, HAL_TIMEOUT = 0x03
} HAL_StatusTypeDef;

HAL Locked: The HAL lock is used by all HAL APIs to prevent accessing by accident
shared resources.
typedef enum
{ HAL_UNLOCKED = 0x00, /*!__PPP_DMA_FIELD_ = &(__DMA_HANDLE_); \
(__DMA_HANDLE_).Parent = (__HANDLE__); \
} while(0)

2.10

HAL configuration
The configuration file, stm32f4xx_hal_conf.h, allows customizing the drivers for the user
application. Modifying this configuration is not mandatory: the application can use the
default configuration without any modification.
To configure these parameters, the user should enable, disable or modify some options by
uncommenting, commenting or modifying the values of the related define statements as
described in the table below:
Table 11: Define statements used for HAL configuration
Configuration item

Description

Default Value

HSE_VALUE

Defines the value of the external
oscillator (HSE) expressed in Hz.
The user must adjust this define
statement when using a different
crystal value.

25 000 000 (Hz)

HSE_STARTUP_TIMEOUT

Timeout for HSE start up,
expressed in ms

5000

DocID025834 Rev 4

45/964

Overview of HAL drivers

UM1725

Configuration item

Description

Default Value

HSI_VALUE

Defines the value of the internal
oscillator (HSI) expressed in Hz.

16 000 000 (Hz)

EXTERNAL_CLOCK_VALUE

This value is used by the
I2S/SAI HAL module to compute
the I2S/SAI clock source
frequency, this source is inserted
directly through I2S_CKIN pad.

12288000 (Hz)

VDD_VALUE

VDD value

3300 (mV)

USE_RTOS

Enables the use of RTOS

FALSE (for future use)

PREFETCH_ENABLE

Enables prefetch feature

TRUE

Enables instruction cache

TRUE

DATA_CACHE_ENABLE

Enables data cache

TRUE

USE HAL_PPP_MODULE

Enables module to be used in
the HAL driver

MAC_ADDRx

Ethernet peripheral
configuration : MAC address

ETH_RX_BUF_SIZE

Ethernet buffer size for receive

ETH_TX_BUF_SIZE

Ethernet buffer size for trasmit

ETH_RXBUFNB

The number of Rx buffers of
size ETH_RX_BUF_SIZE

4

ETH_TXBUFNB

The number of Tx buffers of size
ETH_RX_BUF_SIZE

4

DP83848_PHY_ADDRESS

DB83848 Ethernet PHY
Address

0x01

PHY_RESET_DELAY

PHY Reset delay these values
are based on a 1 ms Systick
interrupt

0x000000FF

PHY_CONFIG_DELAY

PHY Configuration delay

0x00000FFF

PHY_BCR PHY_BSR

Common PHY Registers

PHY_SR PHY_MICR PHY_MISR

Extended PHY registers

INSTRUCTION_CACHE_ENABLE

ETH_MAX_PACKET_SIZE
ETH_MAX_PACKET_SIZE

The stm32f4xx_hal_conf_template.h file is located in the HAL drivers Inc folder. It
should be copied to the user folder, renamed and modified as described above.

By default, the values defined in the stm32f4xx_hal_conf_template.h file are the
same as the ones used for the examples and demonstrations. All HAL include
files are enabled so that they can be used in the user code without modifications.

46/964

DocID025834 Rev 4

UM1725

2.11

Overview of HAL drivers

HAL system peripheral handling
This chapter gives an overview of how the system peripherals are handled by the HAL
drivers. The full API list is provided within each peripheral driver description section.

2.11.1

Clock
Two main functions can be used to configure the system clock:
HAL_RCC_OscConfig (RCC_OscInitTypeDef *RCC_OscInitStruct). This function
configures/enables multiple clock sources (HSE, HSI, LSE, LSI, PLL).
HAL_RCC_ClockConfig (RCC_ClkInitTypeDef *RCC_ClkInitStruct, uint32_t
FLatency). This function
Selects the system clock source
Configures AHB, APB1 and APB2 clock dividers
Configures the number od Flash memory wait states
Updates the SysTick configuration when HCLK clock changes.
Some peripheral clocks are not derived from the system clock (RTC, SDIO, I2S, SAI, Audio
PLL…). In this case, the clock configuration is performed by an extended API defined in
stm32f4xx_hal_ppp_ex.c: HAL_RCCEx_PeriphCLKConfig(RCC_PeriphCLKInitTypeDef
*PeriphClkInit).
Additional RCC HAL driver functions are available:
HAL_RCC_DeInit() Clock de-init function that return clock configuration to reset state
Get clock functions that allow retreiving various clock configurations (system clock,
HCLK, PCLK1, PCLK2, …)
MCO and CSS configuration functions
A set of macros are defined in stm32f4xx_hal_rcc.h. They allows executing elementary
operations on RCC block registers, such as peripherals clock gating/reset control:
__PPP_CLK_ENABLE/__PPP_CLK_DISABLE to enable/disable the peripheral clock
__PPP_FORCE_RESET/__PPP_RELEASE_RESET to force/release peripheral reset
__PPP_CLK_SLEEP_ENABLE/__PPP_CLK_SLEEP_DISABLE to enable/disable the
peripheral clock during low power (Sleep) mode.

2.11.2

GPIOs
GPIO HAL APIs are the following:
HAL_GPIO_Init() / HAL_GPIO_DeInit()
HAL_GPIO_ReadPin() / HAL_GPIO_WritePin()
HAL_GPIO_TogglePin ().
In addition to standard GPIO modes (input, output, analog), pin mode can be configured as
EXTI with interrupt or event generation.
When selecting EXTI mode with interrupt generation, the user must call
HAL_GPIO_EXTI_IRQHandler() from stm32f4xx_it.c and implement
HAL_GPIO_EXTI_Callback()

DocID025834 Rev 4

47/964

Overview of HAL drivers
The table below describes the GPIO_InitTypeDef structure field.

UM1725

Table 12: Description of GPIO_InitTypeDef structure
Structure
field
Pin

Description
Specifies the GPIO pins to be configured.
Possible values: GPIO_PIN_x or GPIO_PIN_All, where x[0..15]
Specifies the operating mode for the selected pins: GPIO mode or EXTI mode.
Possible values are:

Mode

Pull

Speed

48/964

GPIO mode
GPIO_MODE_INPUT : Input Floating
GPIO_MODE_OUTPUT_PP : Output Push Pull
GPIO_MODE_OUTPUT_OD : Output Open Drain
GPIO_MODE_AF_PP : Alternate Function Push Pull
GPIO_MODE_AF_OD : Alternate Function Open Drain
GPIO_MODE_ANALOG : Analog mode
External Interrupt Mode
GPIO_MODE_IT_RISING : Rising edge trigger detection
GPIO_MODE_IT_FALLING : Falling edge trigger detection
GPIO_MODE_IT_RISING_FALLING : Rising/Falling edge trigger detection
External Event Mode
GPIO_MODE_EVT_RISING : Rising edge trigger detection
GPIO_MODE_EVT_FALLING : Falling edge trigger detection
GPIO_MODE_EVT_RISING_FALLING: Rising/Falling edge trigger
detection
Specifies the Pull-up or Pull-down activation for the selected pins.
Possible values are:
GPIO_NOPULL
GPIO_PULLUP
GPIO_PULLDOWN
Specifies the speed for the selected pins
Possible values are:
GPIO_SPEED_LOW
GPIO_SPEED_MEDIUM
GPIO_SPEED_FAST
GPIO_SPEED_HIGH

DocID025834 Rev 4

UM1725

Overview of HAL drivers
Structure
field

Description
Peripheral to be connected to the selected pins.
Possible values: GPIO_AFx_PPP, where
AFx: is the alternate function index
PPP: is the peripheral instance
Example: use GPIO_AF1_TIM1 to connect TIM1 IOs on AF1.
These values are defined in the GPIO extended driver, since the AF mapping may
change between product lines.

Alternate
Refer to the “Alternate function mapping” table in the
datasheets for the detailed description of the system and
peripheral I/O alternate functions.

Please find below typical GPIO configuration examples:
Configuring GPIOs as output push-pull to drive external LEDs
GPIO_InitStruct.Pin = GPIO_PIN_12 | GPIO_PIN_13 | GPIO_PIN_14 | GPIO_PIN_15;
GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
GPIO_InitStruct.Pull = GPIO_PULLUP;
GPIO_InitStruct.Speed = GPIO_SPEED_FAST;
HAL_GPIO_Init(GPIOD, &GPIO_InitStruct);

Configuring PA0 as external interrupt with falling edge sensitivity:
GPIO_InitStructure.Mode = GPIO_MODE_IT_FALLING;
GPIO_InitStructure.Pull = GPIO_NOPULL;
GPIO_InitStructure.Pin = GPIO_PIN_0;
HAL_GPIO_Init(GPIOA, &GPIO_InitStructure);

Configuring USART3 Tx (PC10, mapped on AF7) as alternate function:
GPIO_InitStruct.Pin = GPIO_PIN_10;
GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;
GPIO_InitStruct.Pull = GPIO_PULLUP;
GPIO_InitStruct.Speed = GPIO_SPEED_FAST;
GPIO_InitStruct.Alternate = GPIO_AF7_USART3;
HAL_GPIO_Init(GPIOC, &GPIO_InitStruct);

2.11.3

Cortex NVIC and SysTick timer
The Cortex HAL driver, stm32f4xx_hal_cortex.c, provides APIs to handle NVIC and
Systick. The supported APIs include:
HAL_NVIC_SetPriorityGrouping()
HAL_NVIC_SetPriority()
HAL_NVIC_EnableIRQ()/HAL_NVIC_DisableIRQ()
HAL_NVIC_SystemReset()
HAL_NVIC_GetPendingIRQ() / HAL_NVIC_SetPendingIRQ () /
HAL_NVIC_ClearPendingIRQ()
HAL_SYSTICK_Config()
HAL_SYSTICK_CLKSourceConfig()
DocID025834 Rev 4

49/964

Overview of HAL drivers

2.11.4

UM1725

PWR
The PWR HAL driver handles power management. The features shared between all
STM32 Series are listed below:
PVD configuration, enabling/disabling and interrupt handling
HAL_PWR_PVDConfig()
HAL_PWR_EnablePVD() / HAL_PWR_DisablePVD()
HAL_PWR_PVD_IRQHandler()
HAL_PWR_PVDCallback()
Wakeup pin configuration
HAL_PWR_EnableWakeUpPin() / HAL_PWR_DisableWakeUpPin()
Low power mode entry
HAL_PWR_EnterSLEEPMode()
HAL_PWR_EnterSTOPMode()
HAL_PWR_EnterSTANDBYMode()

50/964

DocID025834 Rev 4

UM1725

Overview of HAL drivers
Depending on the STM32 Series, extension functions are available in
stm32f4xx_hal_pwr_ex. Here are a few examples (the list is not exhaustive)
Backup domain registers enable/disable
HAL_PWREx_EnableBkUpReg() / HAL_PWREx_DisableBkUpReg()
Flash overdrive control and flash power-down, for STM32F429/F439xx only
HAL_PWREx_ActivateOverDrive()
HAL_PWREx_EnableFlashPowerDown().

2.11.5

EXTI
The EXTI is not considered as a standalone peripheral but rather as a service used by
other peripheral. As a result there are no EXTI APIs but each peripheral HAL driver
implements the associated EXTI configuration and EXTI function are implemented as
macros in its header file.
The first 16 EXTI lines connected to the GPIOs are managed within the GPIO driver. The
GPIO_InitTypeDef structure allows configuring an I/O as external interrupt or external
event.
The EXTI lines connected internally to the PVD, RTC, USB, and COMP are configured
within the HAL drivers of these peripheral through the macros given in the table below. The
EXTI internal connections depend on the targeted STM32 microcontroller (refer to the
product datasheet for more details):
Table 13: Description of EXTI configuration macros
Macros

Description

PPP_EXTI_LINE_FUNCTION

Defines the EXTI line connected to the internal peripheral.
Example:
#define PWR_EXTI_LINE_PVD ((uint32_t)0x00010000)
/*!DMA_Handle->XferCpltCallback = HAL_UART_TxCpltCallback ;
hppp->DMA_Handle->XferErrorCallback = HAL_UART_ErrorCallback ;
(…)
}

2.12.4

Timeout and error management

2.12.4.1

Timeout management
The timeout is often used for the APIs that operate in polling mode. It defines the delay
during which a blocking process should wait till an error is returned. An example is provided
below:
HAL_StatusTypeDef HAL_DMA_PollForTransfer(DMA_HandleTypeDef *hdma, uint32_t
CompleteLevel, uint32_t Timeout)

The timeout possible value are the following:
Table 15: Timeout values
Timeout value

Description

0

No poll : Immediate process check and exit

1 ... (HAL_MAX_DELAY -1)
HAL_MAX_DELAY

(1)

Timeout in ms
Infinite poll till process is successful

Notes:
(1)

60/964

HAL_MAX_DELAY is defined in the stm32fxxx_hal_def.h as 0xFFFFFFFF

DocID025834 Rev 4

UM1725

Overview of HAL drivers
However, in some cases, a fixed timeout is used for system peripherals or internal HAL
driver processes. In these cases, the timeout has the same meaning and is used in the
same way, except when it is defined locally in the drivers and cannot be modified or
introduced as an argument in the user application.
Example of fixed timeout:
#define LOCAL_PROCESS_TIMEOUT 100
HAL_StatusTypeDef HAL_PPP_Process(PPP_HandleTypeDef)
{
(…)
timeout = HAL_GetTick() + LOCAL_PROCESS_TIMEOUT;
(…)
while(ProcessOngoing)
{
(…)
if(HAL_GetTick() >= timeout)
{
/* Process unlocked */
__HAL_UNLOCK(hppp);
hppp->State= HAL_PPP_STATE_TIMEOUT;
return HAL_PPP_STATE_TIMEOUT;
}
}
(…)
}

The following example shows how to use the timeout inside the polling functions:
HAL_PPP_StateTypeDef HAL_PPP_Poll (PPP_HandleTypeDef *hppp, uint32_t Timeout)
{
(…)
timeout = HAL_GetTick() + Timeout;
(…)
while(ProcessOngoing)
{
(…)
if(Timeout != HAL_MAX_DELAY)
{
if(HAL_GetTick() >= timeout)
{
/* Process unlocked */
__HAL_UNLOCK(hppp);
hppp->State= HAL_PPP_STATE_TIMEOUT;
return hppp->State;
}
}
(…)
}

2.12.4.2

Error management
The HAL drivers implement a check for the following items:
Valid parameters: for some process the used parameters should be valid and already
defined, otherwise the system can crash or go into an undefined state. These critical
parameters are checked before they are used (see example below).
HAL_StatusTypeDef HAL_PPP_Process(PPP_HandleTypeDef* hppp, uint32_t *pdata, uint32
Size)
{ if ((pData == NULL ) || (Size == 0))
{ return HAL_ERROR;
}
}

DocID025834 Rev 4

61/964

Overview of HAL drivers

UM1725

Valid handle: the PPP peripheral handle is the most important argument since it keeps
the PPP driver vital parameters. It is always checked in the beginning of the
HAL_PPP_Init() function.
HAL_StatusTypeDef HAL_PPP_Init(PPP_HandleTypeDef* hppp)
{ if (hppp == NULL) //the handle should be already allocated
{ return HAL_ERROR;
}
}

Timeout error: the following statement is used when a timeout error occurs:
while (Process ongoing)
{
timeout = HAL_GetTick() + Timeout;
while (data processing is running)
{
if(timeout)
{ return HAL_TIMEOUT;
}
}

When an error occurs during a peripheral process, HAL_PPP_Process () returns with a
HAL_ERROR status. The HAL PPP driver implements the HAL_PPP_GetError () to allow
retrieving the origin of the error.
HAL_PPP_ErrorTypeDef HAL_PPP_GetError (PPP_HandleTypeDef *hppp);

In all peripheral handles, a HAL_PPP_ErrorTypeDef is defined and used to store the last
error code.
typedef struct
{
PPP_TypeDef * Instance; /* PPP registers base address */
PPP_InitTypeDef Init; /* PPP initialization parameters */
HAL_LockTypeDef Lock; /* PPP locking object */
__IO HAL_PPP_StateTypeDef State; /* PPP state */
__IO HAL_PPP_ErrorTypeDef ErrorCode; /* PPP Error code */
(…)
/* PPP specific parameters */
}
PPP_HandleTypeDef;

The error state and the peripheral global state are always updated before returning an
error:
PPP->State = HAL_PPP_READY;
/* Set the peripheral ready */
PP->ErrorCode = HAL_ERRORCODE ; /* Set the error code */
_HAL_UNLOCK(PPP) ;
/* Unlock the PPP resources */
return HAL_ERROR;
/*return with HAL error */

HAL_PPP_GetError () must be used in interrupt mode in the error callback:
void HAL_PPP_ProcessCpltCallback(PPP_HandleTypeDef *hspi)
{
ErrorCode = HAL_PPP_GetError (hppp); /* retreive error code */
}

62/964

DocID025834 Rev 4

UM1725

2.12.4.3

Overview of HAL drivers

Run-time checking
The HAL implements run-time failure detection by checking the input values of all HAL
driver functions. The run-time checking is achieved by using an assert_param macro. This
macro is used in all the HAL drivers' functions which have an input parameter. It allows
verifying that the input value lies within the parameter allowed values.
To enable the run-time checking, use the assert_param macro, and leave the define
USE_FULL_ASSERT uncommented in stm32f34xx_hal_conf.h file.
void HAL_UART_Init(UART_HandleTypeDef *huart)
{
(..) /* Check the parameters */
assert_param(IS_UART_INSTANCE(huart->Instance));
assert_param(IS_UART_BAUDRATE(huart->Init.BaudRate));
assert_param(IS_UART_WORD_LENGTH(huart->Init.WordLength));
assert_param(IS_UART_STOPBITS(huart->Init.StopBits));
assert_param(IS_UART_PARITY(huart->Init.Parity));
assert_param(IS_UART_MODE(huart->Init.Mode));
assert_param(IS_UART_HARDWARE_FLOW_CONTROL(huart->Init.HwFlowCtl));
(..)
/** @defgroup UART_Word_Length *
@{
*/
#define UART_WORDLENGTH_8B ((uint32_t)0x00000000)
#define UART_WORDLENGTH_9B ((uint32_t)USART_CR1_M)
#define IS_UART_WORD_LENGTH(LENGTH) (((LENGTH) == UART_WORDLENGTH_8B) ||
\ ((LENGTH) == UART_WORDLENGTH_9B))

If the expression passed to the assert_param macro is false, theassert_failed function is
called and returns the name of the source file and the source line number of the call that
failed. If the expression is true, no value is returned.
The assert_param macro is implemented in stm32f4xx_hal_conf.h:
/* Exported macro ------------------------------------------------------------*/
#ifdef USE_FULL_ASSERT
/**
* @brief The assert_param macro is used for function's parameters check.
* @param expr: If expr is false, it calls assert_failed function
* which reports the name of the source file and the source
* line number of the call that failed.
* If expr is true, it returns no value.
* @retval None */
#define assert_param(expr) ((expr)?(void)0:assert_failed((uint8_t *)__FILE__,
__LINE__))
/* Exported functions --------------------------------------*/
void assert_failed(uint8_t* file, uint32_t line);
#else
#define assert_param(expr)((void)0)
#endif /* USE_FULL_ASSERT */

DocID025834 Rev 4

63/964

Overview of HAL drivers
UM1725
The assert_failed function is implemented in the main.c file or in any other user C file:
#ifdef USE_FULL_ASSERT /**
* @brief Reports the name of the source file and the source line number
* where the assert_param error has occurred.
* @param file: pointer to the source file name
* @param line: assert_param error line source number
* @retval None */
void assert_failed(uint8_t* file, uint32_t line)
{
/* User can add his own implementation to report the file name and line number,
ex: printf("Wrong parameters value: file %s on line %d\r\n", file, line) */
/* Infinite loop */
while (1)
{
}
}

Because of the overhead run-time checking introduces, it is recommended
to use it during application code development and debugging, and to
remove it from the final application to improve code size and speed.

64/964

DocID025834 Rev 4

UM1725

HAL System Driver

3

HAL System Driver

3.1

HAL Firmware driver API description

3.1.1

How to use this driver
The common HAL driver contains a set of generic and common APIs that can be used by
the PPP peripheral drivers and the user to start using the HAL.
The HAL contains two APIs' categories:
Common HAL APIs
Services HAL APIs

3.1.2

Initialization and de-initialization functions
This section provides functions allowing to:
Initializes the Flash interface the NVIC allocation and initial clock configuration. It
initializes the systick also when timeout is needed and the backup domain when
enabled.
de-Initializes common part of the HAL
Configure The time base source to have 1ms time base with a dedicated Tick
interrupt priority.
Systick timer is used by default as source of time base, but user can eventually
implement his proper time base source (a general purpose timer for example or
other time source), keeping in mind that Time base duration should be kept 1ms
since PPP_TIMEOUT_VALUEs are defined and handled in milliseconds basis.
Time base configuration function (HAL_InitTick ()) is called automatically at the
beginning of the program after reset by HAL_Init() or at any time when clock is
configured, by HAL_RCC_ClockConfig().
Source of time base is configured to generate interrupts at regular time intervals.
Care must be taken if HAL_Delay() is called from a peripheral ISR process, the
Tick interrupt line must have higher priority (numerically lower) than the
peripheral interrupt. Otherwise the caller ISR process will be blocked.
functions affecting time base configurations are declared as __weak to make
override possible in case of other implementations in user file.
This section contains the following APIs:
HAL_Init()
HAL_DeInit()
HAL_MspInit()
HAL_MspDeInit()
HAL_InitTick()

3.1.3

HAL Control functions
This section provides functions allowing to:
Provide a tick value in millisecond
Provide a blocking delay in millisecond
Suspend the time base source interrupt
Resume the time base source interrupt
Get the HAL API driver version
Get the device identifier
DocID025834 Rev 4

65/964

HAL System Driver

UM1725

Get the device revision identifier
Enable/Disable Debug module during SLEEP mode
Enable/Disable Debug module during STOP mode
Enable/Disable Debug module during STANDBY mode
This section contains the following APIs:
HAL_IncTick()
HAL_GetTick()
HAL_Delay()
HAL_SuspendTick()
HAL_ResumeTick()
HAL_GetHalVersion()
HAL_GetREVID()
HAL_GetDEVID()
HAL_DBGMCU_EnableDBGSleepMode()
HAL_DBGMCU_DisableDBGSleepMode()
HAL_DBGMCU_EnableDBGStopMode()
HAL_DBGMCU_DisableDBGStopMode()
HAL_DBGMCU_EnableDBGStandbyMode()
HAL_DBGMCU_DisableDBGStandbyMode()
HAL_EnableCompensationCell()
HAL_DisableCompensationCell()
HAL_EnableMemorySwappingBank()
HAL_DisableMemorySwappingBank()

3.1.4

Detailed description of functions
HAL_Init
Function Name

HAL_StatusTypeDef HAL_Init (void )

Function Description

This function is used to initialize the HAL Library; it must be the
first instruction to be executed in the main program (before to call
any other HAL function), it performs the following: Configure the
Flash prefetch, instruction and Data caches.

Return values

HAL: status

Notes

SysTick is used as time base for the HAL_Delay() function,
the application need to ensure that the SysTick time base is
always set to 1 millisecond to have correct HAL operation.

HAL_DeInit
Function Name

HAL_StatusTypeDef HAL_DeInit (void )

Function Description

This function de-Initializes common part of the HAL and stops the
systick.

Return values

HAL: status

HAL_MspInit

66/964

Function Name

void HAL_MspInit (void )

Function Description

Initializes the MSP.

DocID025834 Rev 4

UM1725

HAL System Driver
Return values

None

HAL_MspDeInit
Function Name

void HAL_MspDeInit (void )

Function Description

DeInitializes the MSP.

Return values

None

HAL_InitTick
Function Name

HAL_StatusTypeDef HAL_InitTick (uint32_t TickPriority)

Function Description

This function configures the source of the time base.

Parameters

TickPriority: Tick interrupt priority.

Return values

HAL: status

Notes

This function is called automatically at the beginning of
program after reset by HAL_Init() or at any time when clock is
reconfigured by HAL_RCC_ClockConfig().
In the default implementation, SysTick timer is the source of
time base. It is used to generate interrupts at regular time
intervals. Care must be taken if HAL_Delay() is called from a
peripheral ISR process, The the SysTick interrupt must have
higher priority (numerically lower) than the peripheral
interrupt. Otherwise the caller ISR process will be blocked.
The function is declared as __weak to be overwritten in case
of other implementation in user file.

HAL_IncTick
Function Name

void HAL_IncTick (void )

Function Description

This function is called to increment a global variable "uwTick" used
as application time base.

Return values

None

Notes

In the default implementation, this variable is incremented
each 1ms in Systick ISR.
This function is declared as __weak to be overwritten in case
of other implementations in user file.

HAL_Delay
Function Name

void HAL_Delay (__IO uint32_t Delay)

Function Description

This function provides accurate delay (in milliseconds) based on
variable incremented.

Parameters

Delay: specifies the delay time length, in milliseconds.

Return values

None

Notes

In the default implementation , SysTick timer is the source of
time base. It is used to generate interrupts at regular time
intervals where uwTick is incremented.
DocID025834 Rev 4

67/964

HAL System Driver

UM1725
This function is declared as __weak to be overwritten in case
of other implementations in user file.

HAL_GetTick
Function Name

uint32_t HAL_GetTick (void )

Function Description

Provides a tick value in millisecond.

Return values

tick: value

Notes

This function is declared as __weak to be overwritten in case
of other implementations in user file.

HAL_SuspendTick
Function Name

void HAL_SuspendTick (void )

Function Description

Suspend Tick increment.

Return values

None

Notes

In the default implementation , SysTick timer is the source of
time base. It is used to generate interrupts at regular time
intervals. Once HAL_SuspendTick() is called, the SysTick
interrupt will be disabled and so Tick increment is suspended.
This function is declared as __weak to be overwritten in case
of other implementations in user file.

HAL_ResumeTick
Function Name

void HAL_ResumeTick (void )

Function Description

Resume Tick increment.

Return values

None

Notes

In the default implementation , SysTick timer is the source of
time base. It is used to generate interrupts at regular time
intervals. Once HAL_ResumeTick() is called, the SysTick
interrupt will be enabled and so Tick increment is resumed.
This function is declared as __weak to be overwritten in case
of other implementations in user file.

HAL_GetHalVersion
Function Name

uint32_t HAL_GetHalVersion (void )

Function Description

Returns the HAL revision.

Return values

version: : 0xXYZR (8bits for each decimal, R for RC)

HAL_GetREVID
Function Name

uint32_t HAL_GetREVID (void )

Function Description

Returns the device revision identifier.

Return values

68/964

Device: revision identifier

DocID025834 Rev 4

UM1725

HAL System Driver

HAL_GetDEVID
Function Name

uint32_t HAL_GetDEVID (void )

Function Description

Returns the device identifier.

Return values

Device: identifier

HAL_DBGMCU_EnableDBGSleepMode
Function Name

void HAL_DBGMCU_EnableDBGSleepMode (void )

Function Description

Enable the Debug Module during SLEEP mode.

Return values

None

HAL_DBGMCU_DisableDBGSleepMode
Function Name

void HAL_DBGMCU_DisableDBGSleepMode (void )

Function Description

Disable the Debug Module during SLEEP mode.

Return values

None

HAL_DBGMCU_EnableDBGStopMode
Function Name

void HAL_DBGMCU_EnableDBGStopMode (void )

Function Description

Enable the Debug Module during STOP mode.

Return values

None

HAL_DBGMCU_DisableDBGStopMode
Function Name

void HAL_DBGMCU_DisableDBGStopMode (void )

Function Description

Disable the Debug Module during STOP mode.

Return values

None

HAL_DBGMCU_EnableDBGStandbyMode
Function Name

void HAL_DBGMCU_EnableDBGStandbyMode (void )

Function Description

Enable the Debug Module during STANDBY mode.

Return values

None

HAL_DBGMCU_DisableDBGStandbyMode
Function Name

void HAL_DBGMCU_DisableDBGStandbyMode (void )

Function Description

Disable the Debug Module during STANDBY mode.

Return values

None

HAL_EnableCompensationCell
Function Name

void HAL_EnableCompensationCell (void )

Function Description

Enables the I/O Compensation Cell.
DocID025834 Rev 4

69/964

HAL System Driver
Return values

UM1725
None

Notes

The I/O compensation cell can be used only when the device
supply voltage ranges from 2.4 to 3.6 V.

HAL_DisableCompensationCell
Function Name

void HAL_DisableCompensationCell (void )

Function Description

Power-down the I/O Compensation Cell.

Return values

None

Notes

The I/O compensation cell can be used only when the device
supply voltage ranges from 2.4 to 3.6 V.

HAL_EnableMemorySwappingBank
Function Name

void HAL_EnableMemorySwappingBank (void )

Function Description

Enables the Internal FLASH Bank Swapping.

Return values

None

Notes

This function can be used only for STM32F42xxx/43xxx
devices.
Flash Bank2 mapped at 0x08000000 (and aliased
@0x00000000) and Flash Bank1 mapped at 0x08100000
(and aliased at 0x00100000)

HAL_DisableMemorySwappingBank
Function Name

void HAL_DisableMemorySwappingBank (void )

Function Description

Disables the Internal FLASH Bank Swapping.

Return values

None

Notes

This function can be used only for STM32F42xxx/43xxx
devices.
The default state : Flash Bank1 mapped at 0x08000000 (and
aliased @0x00000000) and Flash Bank2 mapped at
0x08100000 (and aliased at 0x00100000)

3.2

HAL Firmware driver defines

3.2.1

HAL
HAL CAN Error Code

70/964

HAL_CAN_ERROR_NONE

No error

HAL_CAN_ERROR_EWG

EWG error

HAL_CAN_ERROR_EPV

EPV error

HAL_CAN_ERROR_BOF

BOF error

HAL_CAN_ERROR_STF

Stuff error

HAL_CAN_ERROR_FOR

Form error
DocID025834 Rev 4

UM1725

HAL System Driver
HAL_CAN_ERROR_ACK

Acknowledgment error

HAL_CAN_ERROR_BR

Bit recessive

HAL_CAN_ERROR_BD

LEC dominant

HAL_CAN_ERROR_CRC

LEC transfer error

HAL Exported Macros
__HAL_DBGMCU_FREEZE_TIM2
__HAL_DBGMCU_FREEZE_TIM3
__HAL_DBGMCU_FREEZE_TIM4
__HAL_DBGMCU_FREEZE_TIM5
__HAL_DBGMCU_FREEZE_TIM6
__HAL_DBGMCU_FREEZE_TIM7
__HAL_DBGMCU_FREEZE_TIM12
__HAL_DBGMCU_FREEZE_TIM13
__HAL_DBGMCU_FREEZE_TIM14
__HAL_DBGMCU_FREEZE_RTC
__HAL_DBGMCU_FREEZE_WWDG
__HAL_DBGMCU_FREEZE_IWDG
__HAL_DBGMCU_FREEZE_I2C1_TIMEOUT
__HAL_DBGMCU_FREEZE_I2C2_TIMEOUT
__HAL_DBGMCU_FREEZE_I2C3_TIMEOUT
__HAL_DBGMCU_FREEZE_CAN1
__HAL_DBGMCU_FREEZE_CAN2
__HAL_DBGMCU_FREEZE_TIM1
__HAL_DBGMCU_FREEZE_TIM8
__HAL_DBGMCU_FREEZE_TIM9
__HAL_DBGMCU_FREEZE_TIM10
__HAL_DBGMCU_FREEZE_TIM11
__HAL_DBGMCU_UNFREEZE_TIM2
__HAL_DBGMCU_UNFREEZE_TIM3
__HAL_DBGMCU_UNFREEZE_TIM4
__HAL_DBGMCU_UNFREEZE_TIM5
__HAL_DBGMCU_UNFREEZE_TIM6
__HAL_DBGMCU_UNFREEZE_TIM7
__HAL_DBGMCU_UNFREEZE_TIM12
__HAL_DBGMCU_UNFREEZE_TIM13
__HAL_DBGMCU_UNFREEZE_TIM14

DocID025834 Rev 4

71/964

HAL System Driver
__HAL_DBGMCU_UNFREEZE_RTC
__HAL_DBGMCU_UNFREEZE_WWDG
__HAL_DBGMCU_UNFREEZE_IWDG
__HAL_DBGMCU_UNFREEZE_I2C1_TIMEOUT
__HAL_DBGMCU_UNFREEZE_I2C2_TIMEOUT
__HAL_DBGMCU_UNFREEZE_I2C3_TIMEOUT
__HAL_DBGMCU_UNFREEZE_CAN1
__HAL_DBGMCU_UNFREEZE_CAN2
__HAL_DBGMCU_UNFREEZE_TIM1
__HAL_DBGMCU_UNFREEZE_TIM8
__HAL_DBGMCU_UNFREEZE_TIM9
__HAL_DBGMCU_UNFREEZE_TIM10
__HAL_DBGMCU_UNFREEZE_TIM11
__HAL_SYSCFG_REMAPMEMORY_FLASH
__HAL_SYSCFG_REMAPMEMORY_SYSTEMFLASH
__HAL_SYSCFG_REMAPMEMORY_SRAM
__HAL_SYSCFG_REMAPMEMORY_FMC
__HAL_SYSCFG_REMAPMEMORY_FMC_SDRAM

72/964

DocID025834 Rev 4

UM1725

UM1725

HAL ADC Generic Driver

4

HAL ADC Generic Driver

4.1

ADC Firmware driver registers structures

4.1.1

ADC_InitTypeDef
Data Fields
uint32_t ClockPrescaler
uint32_t Resolution
uint32_t DataAlign
uint32_t ScanConvMode
uint32_t EOCSelection
uint32_t ContinuousConvMode
uint32_t NbrOfConversion
uint32_t DiscontinuousConvMode
uint32_t NbrOfDiscConversion
uint32_t ExternalTrigConv
uint32_t ExternalTrigConvEdge
uint32_t DMAContinuousRequests

Field Documentation
uint32_t ADC_InitTypeDef::ClockPrescaler
Select ADC clock prescaler. The clock is common for all the ADCs. This parameter
can be a value of ADC_ClockPrescaler
uint32_t ADC_InitTypeDef::Resolution
Configures the ADC resolution. This parameter can be a value of ADC_Resolution
uint32_t ADC_InitTypeDef::DataAlign
Specifies ADC data alignment to right (MSB on register bit 11 and LSB on register bit
0) (default setting) or to left (if regular group: MSB on register bit 15 and LSB on
register bit 4, if injected group (MSB kept as signed value due to potential negative
value after offset application): MSB on register bit 14 and LSB on register bit 3). This
parameter can be a value of ADC_Data_align
uint32_t ADC_InitTypeDef::ScanConvMode
Configures the sequencer of regular and injected groups. This parameter can be
associated to parameter 'DiscontinuousConvMode' to have main sequence subdivided
in successive parts. If disabled: Conversion is performed in single mode (one channel
converted, the one defined in rank 1). Parameters 'NbrOfConversion' and
'InjectedNbrOfConversion' are discarded (equivalent to set to 1). If enabled:
Conversions are performed in sequence mode (multiple ranks defined by
'NbrOfConversion'/'InjectedNbrOfConversion' and each channel rank). Scan direction
is upward: from rank1 to rank 'n'. This parameter can be set to ENABLE or DISABLE
uint32_t ADC_InitTypeDef::EOCSelection
Specifies what EOC (End Of Conversion) flag is used for conversion by polling and
interruption: end of conversion of each rank or complete sequence. This parameter
can be a value of ADC_EOCSelection. Note: For injected group, end of conversion
(flag&IT) is raised only at the end of the sequence. Therefore, if end of conversion is
set to end of each conversion, injected group should not be used with interruption
(HAL_ADCEx_InjectedStart_IT) or polling (HAL_ADCEx_InjectedStart and
DocID025834 Rev 4

73/964

HAL ADC Generic Driver
UM1725
HAL_ADCEx_InjectedPollForConversion). By the way, polling is still possible since
driver will use an estimated timing for end of injected conversion. Note: If overrun
feature is intended to be used, use ADC in mode 'interruption' (function
HAL_ADC_Start_IT() ) with parameter EOCSelection set to end of each conversion
or in mode 'transfer by DMA' (function HAL_ADC_Start_DMA()). If overrun feature is
intended to be bypassed, use ADC in mode 'polling' or 'interruption' with parameter
EOCSelection must be set to end of sequence
uint32_t ADC_InitTypeDef::ContinuousConvMode
Specifies whether the conversion is performed in single mode (one conversion) or
continuous mode for regular group, after the selected trigger occurred (software start
or external trigger). This parameter can be set to ENABLE or DISABLE.
uint32_t ADC_InitTypeDef::NbrOfConversion
Specifies the number of ranks that will be converted within the regular group
sequencer. To use regular group sequencer and convert several ranks, parameter
'ScanConvMode' must be enabled. This parameter must be a number between
Min_Data = 1 and Max_Data = 16.
uint32_t ADC_InitTypeDef::DiscontinuousConvMode
Specifies whether the conversions sequence of regular group is performed in
Complete-sequence/Discontinuous-sequence (main sequence subdivided in
successive parts). Discontinuous mode is used only if sequencer is enabled
(parameter 'ScanConvMode'). If sequencer is disabled, this parameter is discarded.
Discontinuous mode can be enabled only if continuous mode is disabled. If continuous
mode is enabled, this parameter setting is discarded. This parameter can be set to
ENABLE or DISABLE.
uint32_t ADC_InitTypeDef::NbrOfDiscConversion
Specifies the number of discontinuous conversions in which the main sequence of
regular group (parameter NbrOfConversion) will be subdivided. If parameter
'DiscontinuousConvMode' is disabled, this parameter is discarded. This parameter
must be a number between Min_Data = 1 and Max_Data = 8.
uint32_t ADC_InitTypeDef::ExternalTrigConv
Selects the external event used to trigger the conversion start of regular group. If set
to ADC_SOFTWARE_START, external triggers are disabled. If set to external trigger
source, triggering is on event rising edge by default. This parameter can be a value of
ADC_External_trigger_Source_Regular
uint32_t ADC_InitTypeDef::ExternalTrigConvEdge
Selects the external trigger edge of regular group. If trigger is set to
ADC_SOFTWARE_START, this parameter is discarded. This parameter can be a
value of ADC_External_trigger_edge_Regular
uint32_t ADC_InitTypeDef::DMAContinuousRequests
Specifies whether the DMA requests are performed in one shot mode (DMA transfer
stop when number of conversions is reached) or in Continuous mode (DMA transfer
unlimited, whatever number of conversions). Note: In continuous mode, DMA must be
configured in circular mode. Otherwise an overrun will be triggered when DMA buffer
maximum pointer is reached. Note: This parameter must be modified when no
conversion is on going on both regular and injected groups (ADC disabled, or ADC
enabled without continuous mode or external trigger that could launch a conversion).
This parameter can be set to ENABLE or DISABLE.

74/964

DocID025834 Rev 4

UM1725

4.1.2

HAL ADC Generic Driver

ADC_ChannelConfTypeDef
Data Fields
uint32_t Channel
uint32_t Rank
uint32_t SamplingTime
uint32_t Offset

Field Documentation
uint32_t ADC_ChannelConfTypeDef::Channel
Specifies the channel to configure into ADC regular group. This parameter can be a
value of ADC_channels
uint32_t ADC_ChannelConfTypeDef::Rank
Specifies the rank in the regular group sequencer. This parameter must be a number
between Min_Data = 1 and Max_Data = 16
uint32_t ADC_ChannelConfTypeDef::SamplingTime
Sampling time value to be set for the selected channel. Unit: ADC clock cycles
Conversion time is the addition of sampling time and processing time (12 ADC clock
cycles at ADC resolution 12 bits, 11 cycles at 10 bits, 9 cycles at 8 bits, 7 cycles at 6
bits). This parameter can be a value of ADC_sampling_times Caution: This
parameter updates the parameter property of the channel, that can be used into
regular and/or injected groups. If this same channel has been previously configured in
the other group (regular/injected), it will be updated to last setting. Note: In case of
usage of internal measurement channels (VrefInt/Vbat/TempSensor), sampling time
constraints must be respected (sampling time can be adjusted in function of ADC
clock frequency and sampling time setting) Refer to device datasheet for timings
values, parameters TS_vrefint, TS_temp (values rough order: 4us min).
uint32_t ADC_ChannelConfTypeDef::Offset
Reserved for future use, can be set to 0

4.1.3

ADC_AnalogWDGConfTypeDef
Data Fields
uint32_t WatchdogMode
uint32_t HighThreshold
uint32_t LowThreshold
uint32_t Channel
uint32_t ITMode
uint32_t WatchdogNumber

Field Documentation
uint32_t ADC_AnalogWDGConfTypeDef::WatchdogMode
Configures the ADC analog watchdog mode. This parameter can be a value of
ADC_analog_watchdog_selection

DocID025834 Rev 4

75/964

HAL ADC Generic Driver

UM1725

uint32_t ADC_AnalogWDGConfTypeDef::HighThreshold
Configures the ADC analog watchdog High threshold value. This parameter must be
a 12-bit value.
uint32_t ADC_AnalogWDGConfTypeDef::LowThreshold
Configures the ADC analog watchdog High threshold value. This parameter must be
a 12-bit value.
uint32_t ADC_AnalogWDGConfTypeDef::Channel
Configures ADC channel for the analog watchdog. This parameter has an effect only
if watchdog mode is configured on single channel This parameter can be a value of
ADC_channels
uint32_t ADC_AnalogWDGConfTypeDef::ITMode
Specifies whether the analog watchdog is configured is interrupt mode or in polling
mode. This parameter can be set to ENABLE or DISABLE
uint32_t ADC_AnalogWDGConfTypeDef::WatchdogNumber
Reserved for future use, can be set to 0

4.1.4

ADC_HandleTypeDef
Data Fields
ADC_TypeDef * Instance
ADC_InitTypeDef Init
__IO uint32_t NbrOfCurrentConversionRank
DMA_HandleTypeDef * DMA_Handle
HAL_LockTypeDef Lock
__IO uint32_t State
__IO uint32_t ErrorCode

Field Documentation
ADC_TypeDef* ADC_HandleTypeDef::Instance
Register base address
ADC_InitTypeDef ADC_HandleTypeDef::Init
ADC required parameters
__IO uint32_t ADC_HandleTypeDef::NbrOfCurrentConversionRank
ADC number of current conversion rank
DMA_HandleTypeDef* ADC_HandleTypeDef::DMA_Handle
Pointer DMA Handler
HAL_LockTypeDef ADC_HandleTypeDef::Lock
ADC locking object
__IO uint32_t ADC_HandleTypeDef::State
ADC communication state
__IO uint32_t ADC_HandleTypeDef::ErrorCode
ADC Error code

76/964

DocID025834 Rev 4

UM1725

HAL ADC Generic Driver

4.2

ADC Firmware driver API description

4.2.1

ADC Peripheral features
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.

4.2.2

12-bit, 10-bit, 8-bit or 6-bit configurable resolution.
Interrupt generation at the end of conversion, end of injected conversion, and in case
of analog watchdog or overrun events
Single and continuous conversion modes.
Scan mode for automatic conversion of channel 0 to channel x.
Data alignment with in-built data coherency.
Channel-wise programmable sampling time.
External trigger option with configurable polarity for both regular and injected
conversion.
Dual/Triple mode (on devices with 2 ADCs or more).
Configurable DMA data storage in Dual/Triple ADC mode.
Configurable delay between conversions in Dual/Triple interleaved mode.
ADC conversion type (refer to the datasheets).
ADC supply requirements: 2.4 V to 3.6 V at full speed and down to 1.8 V at slower
speed.
ADC input range: VREF(minus) = VIN = VREF(plus).
DMA request generation during regular channel conversion.

How to use this driver
1.

Initialize the ADC low level resources by implementing the HAL_ADC_MspInit():
a.
Enable the ADC interface clock using __HAL_RCC_ADC_CLK_ENABLE()
b.
ADC pins configuration
Enable the clock for the ADC GPIOs using the following function:
__HAL_RCC_GPIOx_CLK_ENABLE()
Configure these ADC pins in analog mode using HAL_GPIO_Init()
c.
In case of using interrupts (e.g. HAL_ADC_Start_IT())
Configure the ADC interrupt priority using HAL_NVIC_SetPriority()
Enable the ADC IRQ handler using HAL_NVIC_EnableIRQ()
In ADC IRQ handler, call HAL_ADC_IRQHandler()
d.
In case of using DMA to control data transfer (e.g. HAL_ADC_Start_DMA())
Enable the DMAx interface clock using
__HAL_RCC_DMAx_CLK_ENABLE()
Configure and enable two DMA streams stream for managing data transfer
from peripheral to memory (output stream)
Associate the initialized DMA handle to the CRYP DMA handle using
__HAL_LINKDMA()
Configure the priority and enable the NVIC for the transfer complete
interrupt on the two DMA Streams. The output stream should have higher
priority than the input stream.

DocID025834 Rev 4

77/964

HAL ADC Generic Driver

UM1725

Configuration of ADC, groups regular/injected, channels parameters
1.
2.
3.

4.
5.

Configure the ADC parameters (resolution, data alignment, ...) and regular group
parameters (conversion trigger, sequencer, ...) using function HAL_ADC_Init().
Configure the channels for regular group parameters (channel number, channel rank
into sequencer, ..., into regular group) using function HAL_ADC_ConfigChannel().
Optionally, configure the injected group parameters (conversion trigger, sequencer,
..., of injected group) and the channels for injected group parameters (channel
number, channel rank into sequencer, ..., into injected group) using function
HAL_ADCEx_InjectedConfigChannel().
Optionally, configure the analog watchdog parameters (channels monitored,
thresholds, ...) using function HAL_ADC_AnalogWDGConfig().
Optionally, for devices with several ADC instances: configure the multimode
parameters using function HAL_ADCEx_MultiModeConfigChannel().

Execution of ADC conversions
1.

ADC driver can be used among three modes: polling, interruption, transfer by DMA.

Polling mode IO operation
Start the ADC peripheral using HAL_ADC_Start()
Wait for end of conversion using HAL_ADC_PollForConversion(), at this stage user
can specify the value of timeout according to his end application
To read the ADC converted values, use the HAL_ADC_GetValue() function.
Stop the ADC peripheral using HAL_ADC_Stop()

Interrupt mode IO operation
Start the ADC peripheral using HAL_ADC_Start_IT()
Use HAL_ADC_IRQHandler() called under ADC_IRQHandler() Interrupt subroutine
At ADC end of conversion HAL_ADC_ConvCpltCallback() function is executed and
user can add his own code by customization of function pointer
HAL_ADC_ConvCpltCallback
In case of ADC Error, HAL_ADC_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_ADC_ErrorCallback
Stop the ADC peripheral using HAL_ADC_Stop_IT()

DMA mode IO operation
Start the ADC peripheral using HAL_ADC_Start_DMA(), at this stage the user specify
the length of data to be transferred at each end of conversion
At The end of data transfer by HAL_ADC_ConvCpltCallback() function is executed
and user can add his own code by customization of function pointer
HAL_ADC_ConvCpltCallback
In case of transfer Error, HAL_ADC_ErrorCallback() function is executed and user
can add his own code by customization of function pointer HAL_ADC_ErrorCallback
Stop the ADC peripheral using HAL_ADC_Stop_DMA()
78/964

DocID025834 Rev 4

UM1725

HAL ADC Generic Driver

ADC HAL driver macros list
Below the list of most used macros in ADC HAL driver.
__HAL_ADC_ENABLE : Enable the ADC peripheral
__HAL_ADC_DISABLE : Disable the ADC peripheral
__HAL_ADC_ENABLE_IT: Enable the ADC end of conversion interrupt
__HAL_ADC_DISABLE_IT: Disable the ADC end of conversion interrupt
__HAL_ADC_GET_IT_SOURCE: Check if the specified ADC interrupt source is
enabled or disabled
__HAL_ADC_CLEAR_FLAG: Clear the ADC's pending flags
__HAL_ADC_GET_FLAG: Get the selected ADC's flag status
ADC_GET_RESOLUTION: Return resolution bits in CR1 register
You can refer to the ADC HAL driver header file for more useful macros

Deinitialization of ADC
1.

2.

3.
4.

Disable the ADC interface
ADC clock can be hard reset and disabled at RCC top level.
Hard reset of ADC peripherals using macro
__HAL_RCC_ADC_FORCE_RESET(), __HAL_RCC_ADC_RELEASE_RESET().
ADC clock disable using the equivalent macro/functions as configuration step.
Example: Into HAL_ADC_MspDeInit() (recommended code location) or with
other device clock parameters configuration:
HAL_RCC_GetOscConfig(&RCC_OscInitStructure);
RCC_OscInitStructure.OscillatorType = RCC_OSCILLATORTYPE_HSI;
RCC_OscInitStructure.HSIState = RCC_HSI_OFF; (if not used for system
clock)
HAL_RCC_OscConfig(&RCC_OscInitStructure);
ADC pins configuration
Disable the clock for the ADC GPIOs using macro
__HAL_RCC_GPIOx_CLK_DISABLE()
Optionally, in case of usage of ADC with interruptions:
Disable the NVIC for ADC using function HAL_NVIC_DisableIRQ(ADCx_IRQn)
Optionally, in case of usage of DMA:
Deinitialize the DMA using function HAL_DMA_DeInit().
Disable the NVIC for DMA using function
HAL_NVIC_DisableIRQ(DMAx_Channelx_IRQn)

DocID025834 Rev 4

79/964

HAL ADC Generic Driver

4.2.3

UM1725

Initialization and de-initialization functions
This section provides functions allowing to:
Initialize and configure the ADC.
De-initialize the ADC.
This section contains the following APIs:
HAL_ADC_Init()
HAL_ADC_DeInit()
HAL_ADC_MspInit()
HAL_ADC_MspDeInit()

4.2.4

IO operation functions
This section provides functions allowing to:
Start conversion of regular channel.
Stop conversion of regular channel.
Start conversion of regular channel and enable interrupt.
Stop conversion of regular channel and disable interrupt.
Start conversion of regular channel and enable DMA transfer.
Stop conversion of regular channel and disable DMA transfer.
Handle ADC interrupt request.
This section contains the following APIs:
HAL_ADC_Start()
HAL_ADC_Stop()
HAL_ADC_PollForConversion()
HAL_ADC_PollForEvent()
HAL_ADC_Start_IT()
HAL_ADC_Stop_IT()
HAL_ADC_IRQHandler()
HAL_ADC_Start_DMA()
HAL_ADC_Stop_DMA()
HAL_ADC_GetValue()
HAL_ADC_ConvCpltCallback()
HAL_ADC_ConvHalfCpltCallback()
HAL_ADC_LevelOutOfWindowCallback()
HAL_ADC_ErrorCallback()

4.2.5

Peripheral Control functions
This section provides functions allowing to:
Configure regular channels.
Configure injected channels.
Configure multimode.
Configure the analog watch dog.
This section contains the following APIs:
HAL_ADC_ConfigChannel()
HAL_ADC_AnalogWDGConfig()

80/964

DocID025834 Rev 4

UM1725

4.2.6

HAL ADC Generic Driver

Peripheral State and errors functions
This subsection provides functions allowing to
Check the ADC state
Check the ADC Error
This section contains the following APIs:
HAL_ADC_GetState()
HAL_ADC_GetError()

4.2.7

Detailed description of functions
HAL_ADC_Init
Function Name

HAL_StatusTypeDef HAL_ADC_Init (ADC_HandleTypeDef *
hadc)

Function Description

Initializes the ADCx peripheral according to the specified
parameters in the ADC_InitStruct and initializes the ADC MSP.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

HAL: status

Notes

This function is used to configure the global features of the
ADC ( ClockPrescaler, Resolution, Data Alignment and
number of conversion), however, the rest of the configuration
parameters are specific to the regular channels group (scan
mode activation, continuous mode activation, External trigger
source and edge, DMA continuous request after the last
transfer and End of conversion selection).

HAL_ADC_DeInit
Function Name

HAL_StatusTypeDef HAL_ADC_DeInit (ADC_HandleTypeDef *
hadc)

Function Description

Deinitializes the ADCx peripheral registers to their default reset
values.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

HAL: status

HAL_ADC_MspInit
Function Name

void HAL_ADC_MspInit (ADC_HandleTypeDef * hadc)

Function Description

Initializes the ADC MSP.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

None

DocID025834 Rev 4

81/964

HAL ADC Generic Driver

UM1725

HAL_ADC_MspDeInit
Function Name

void HAL_ADC_MspDeInit (ADC_HandleTypeDef * hadc)

Function Description

DeInitializes the ADC MSP.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

None

HAL_ADC_Start
Function Name

HAL_StatusTypeDef HAL_ADC_Start (ADC_HandleTypeDef *
hadc)

Function Description

Enables ADC and starts conversion of the regular channels.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

HAL: status

HAL_ADC_Stop
Function Name

HAL_StatusTypeDef HAL_ADC_Stop (ADC_HandleTypeDef *
hadc)

Function Description

Disables ADC and stop conversion of regular channels.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

HAL: status.

Notes

Caution: This function will stop also injected channels.

HAL_ADC_PollForConversion

82/964

Function Name

HAL_StatusTypeDef HAL_ADC_PollForConversion
(ADC_HandleTypeDef * hadc, uint32_t Timeout)

Function Description

Poll for regular conversion complete.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.
Timeout: Timeout value in millisecond.

Return values

HAL: status

Notes

ADC conversion flags EOS (end of sequence) and EOC (end
of conversion) are cleared by this function.
This function cannot be used in a particular setup: ADC
configured in DMA mode and polling for end of each
conversion (ADC init parameter "EOCSelection" set to
ADC_EOC_SINGLE_CONV). In this case, DMA resets the
flag EOC and polling cannot be performed on each
conversion. Nevertheless, polling can still be performed on
the complete sequence.

DocID025834 Rev 4

UM1725

HAL ADC Generic Driver

HAL_ADC_PollForEvent
Function Name

HAL_StatusTypeDef HAL_ADC_PollForEvent
(ADC_HandleTypeDef * hadc, uint32_t EventType, uint32_t
Timeout)

Function Description

Poll for conversion event.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.
EventType: the ADC event type. This parameter can be one
of the following values:
ADC_AWD_EVENT: ADC Analog watch Dog event.
ADC_OVR_EVENT: ADC Overrun event.
Timeout: Timeout value in millisecond.

Return values

HAL: status

HAL_ADC_Start_IT
Function Name

HAL_StatusTypeDef HAL_ADC_Start_IT (ADC_HandleTypeDef
* hadc)

Function Description

Enables the interrupt and starts ADC conversion of regular
channels.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

HAL: status.

HAL_ADC_Stop_IT
Function Name

HAL_StatusTypeDef HAL_ADC_Stop_IT (ADC_HandleTypeDef
* hadc)

Function Description

Disables the interrupt and stop ADC conversion of regular
channels.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

HAL: status.

Notes

Caution: This function will stop also injected channels.

HAL_ADC_IRQHandler
Function Name

void HAL_ADC_IRQHandler (ADC_HandleTypeDef * hadc)

Function Description

Handles ADC interrupt request.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

None

DocID025834 Rev 4

83/964

HAL ADC Generic Driver

UM1725

HAL_ADC_Start_DMA
Function Name

HAL_StatusTypeDef HAL_ADC_Start_DMA
(ADC_HandleTypeDef * hadc, uint32_t * pData, uint32_t
Length)

Function Description

Enables ADC DMA request after last transfer (Single-ADC mode)
and enables ADC peripheral.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.
pData: The destination Buffer address.
Length: The length of data to be transferred from ADC
peripheral to memory.

Return values

HAL: status

HAL_ADC_Stop_DMA
Function Name

HAL_StatusTypeDef HAL_ADC_Stop_DMA
(ADC_HandleTypeDef * hadc)

Function Description

Disables ADC DMA (Single-ADC mode) and disables ADC
peripheral.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

HAL: status

HAL_ADC_GetValue
Function Name

uint32_t HAL_ADC_GetValue (ADC_HandleTypeDef * hadc)

Function Description

Gets the converted value from data register of regular channel.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

Converted: value

HAL_ADC_ConvCpltCallback
Function Name

void HAL_ADC_ConvCpltCallback (ADC_HandleTypeDef *
hadc)

Function Description

Regular conversion complete callback in non blocking mode.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

None

HAL_ADC_ConvHalfCpltCallback

84/964

Function Name

void HAL_ADC_ConvHalfCpltCallback (ADC_HandleTypeDef *
hadc)

Function Description

Regular conversion half DMA transfer callback in non blocking
mode.

DocID025834 Rev 4

UM1725

HAL ADC Generic Driver
Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

None

HAL_ADC_LevelOutOfWindowCallback
Function Name

void HAL_ADC_LevelOutOfWindowCallback
(ADC_HandleTypeDef * hadc)

Function Description

Analog watchdog callback in non blocking mode.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

None

HAL_ADC_ErrorCallback
Function Name

void HAL_ADC_ErrorCallback (ADC_HandleTypeDef * hadc)

Function Description

Error ADC callback.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

None

Notes

In case of error due to overrun when using ADC with DMA
transfer (HAL ADC handle paramater "ErrorCode" to state
"HAL_ADC_ERROR_OVR"): Reinitialize the DMA using
function "HAL_ADC_Stop_DMA()".If needed, restart a new
ADC conversion using function "HAL_ADC_Start_DMA()"
(this function is also clearing overrun flag)

HAL_ADC_ConfigChannel
Function Name

HAL_StatusTypeDef HAL_ADC_ConfigChannel
(ADC_HandleTypeDef * hadc, ADC_ChannelConfTypeDef *
sConfig)

Function Description

Configures for the selected ADC regular channel its corresponding
rank in the sequencer and its sample time.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.
sConfig: ADC configuration structure.

Return values

HAL: status

HAL_ADC_AnalogWDGConfig
Function Name

HAL_StatusTypeDef HAL_ADC_AnalogWDGConfig
(ADC_HandleTypeDef * hadc, ADC_AnalogWDGConfTypeDef *
AnalogWDGConfig)

Function Description

Configures the analog watchdog.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.
DocID025834 Rev 4

85/964

HAL ADC Generic Driver

UM1725
AnalogWDGConfig: : pointer to an
ADC_AnalogWDGConfTypeDef structure that contains the
configuration information of ADC analog watchdog.

Return values

HAL: status

Notes

Analog watchdog thresholds can be modified while ADC
conversion is on going. In this case, some constraints must
be taken into account: The programmed threshold values are
effective from the next ADC EOC (end of unitary conversion).
Considering that registers write delay may happen due to bus
activity, this might cause an uncertainty on the effective timing
of the new programmed threshold values.

HAL_ADC_GetState
Function Name

uint32_t HAL_ADC_GetState (ADC_HandleTypeDef * hadc)

Function Description

return the ADC state

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

HAL: state

HAL_ADC_GetError
Function Name

uint32_t HAL_ADC_GetError (ADC_HandleTypeDef * hadc)

Function Description

Return the ADC error code.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

ADC: Error Code

4.3

ADC Firmware driver defines

4.3.1

ADC
ADC Analog Watchdog Selection
ADC_ANALOGWATCHDOG_SINGLE_REG
ADC_ANALOGWATCHDOG_SINGLE_INJEC
ADC_ANALOGWATCHDOG_SINGLE_REGINJEC
ADC_ANALOGWATCHDOG_ALL_REG
ADC_ANALOGWATCHDOG_ALL_INJEC
ADC_ANALOGWATCHDOG_ALL_REGINJEC
ADC_ANALOGWATCHDOG_NONE
ADC Common Channels
ADC_CHANNEL_0
ADC_CHANNEL_1
ADC_CHANNEL_2

86/964

DocID025834 Rev 4

UM1725

HAL ADC Generic Driver
ADC_CHANNEL_3
ADC_CHANNEL_4
ADC_CHANNEL_5
ADC_CHANNEL_6
ADC_CHANNEL_7
ADC_CHANNEL_8
ADC_CHANNEL_9
ADC_CHANNEL_10
ADC_CHANNEL_11
ADC_CHANNEL_12
ADC_CHANNEL_13
ADC_CHANNEL_14
ADC_CHANNEL_15
ADC_CHANNEL_16
ADC_CHANNEL_17
ADC_CHANNEL_18
ADC_CHANNEL_VREFINT
ADC_CHANNEL_VBAT
ADC Channels Type
ADC_ALL_CHANNELS
ADC_REGULAR_CHANNELS

reserved for future use

ADC_INJECTED_CHANNELS

reserved for future use

ADC Clock Prescaler
ADC_CLOCK_SYNC_PCLK_DIV2
ADC_CLOCK_SYNC_PCLK_DIV4
ADC_CLOCK_SYNC_PCLK_DIV6
ADC_CLOCK_SYNC_PCLK_DIV8
ADC Data Align
ADC_DATAALIGN_RIGHT
ADC_DATAALIGN_LEFT
ADC Delay Between 2 Sampling Phases
ADC_TWOSAMPLINGDELAY_5CYCLES
ADC_TWOSAMPLINGDELAY_6CYCLES
ADC_TWOSAMPLINGDELAY_7CYCLES
ADC_TWOSAMPLINGDELAY_8CYCLES
ADC_TWOSAMPLINGDELAY_9CYCLES

DocID025834 Rev 4

87/964

HAL ADC Generic Driver
ADC_TWOSAMPLINGDELAY_10CYCLES

UM1725

ADC_TWOSAMPLINGDELAY_11CYCLES
ADC_TWOSAMPLINGDELAY_12CYCLES
ADC_TWOSAMPLINGDELAY_13CYCLES
ADC_TWOSAMPLINGDELAY_14CYCLES
ADC_TWOSAMPLINGDELAY_15CYCLES
ADC_TWOSAMPLINGDELAY_16CYCLES
ADC_TWOSAMPLINGDELAY_17CYCLES
ADC_TWOSAMPLINGDELAY_18CYCLES
ADC_TWOSAMPLINGDELAY_19CYCLES
ADC_TWOSAMPLINGDELAY_20CYCLES
ADC EOC Selection
ADC_EOC_SEQ_CONV
ADC_EOC_SINGLE_CONV
ADC_EOC_SINGLE_SEQ_CONV

reserved for future use

ADC Error Code
HAL_ADC_ERROR_NONE

No error

HAL_ADC_ERROR_INTERNAL

ADC IP internal error: if problem of clocking,
enable/disable, erroneous state

HAL_ADC_ERROR_OVR

Overrun error

HAL_ADC_ERROR_DMA

DMA transfer error

ADC Event Type
ADC_AWD_EVENT
ADC_OVR_EVENT
ADC Exported Macros
__HAL_ADC_RESET_HANDLE_STATE

Description:
Reset ADC handle state.
Parameters:
__HANDLE__: ADC handle
Return value:
None

__HAL_ADC_ENABLE

Description:
Enable the ADC peripheral.
Parameters:
__HANDLE__: ADC handle
Return value:

88/964

DocID025834 Rev 4

UM1725

HAL ADC Generic Driver
None
Description:

__HAL_ADC_DISABLE

Disable the ADC peripheral.
Parameters:
__HANDLE__: ADC handle
Return value:
None
Description:

__HAL_ADC_ENABLE_IT

Enable the ADC end of conversion
interrupt.
Parameters:
__HANDLE__: specifies the ADC Handle.
__INTERRUPT__: ADC Interrupt.
Return value:
None
Description:

__HAL_ADC_DISABLE_IT

Disable the ADC end of conversion
interrupt.
Parameters:
__HANDLE__: specifies the ADC Handle.
__INTERRUPT__: ADC interrupt.
Return value:
None
__HAL_ADC_GET_IT_SOURCE

Description:
Check if the specified ADC interrupt source
is enabled or disabled.
Parameters:
__HANDLE__: specifies the ADC Handle.
__INTERRUPT__: specifies the ADC
interrupt source to check.
Return value:
The: new state of __IT__ (TRUE or
FALSE).

__HAL_ADC_CLEAR_FLAG

Description:
Clear the ADC's pending flags.
Parameters:
__HANDLE__: specifies the ADC Handle.
__FLAG__: ADC flag.

DocID025834 Rev 4

89/964

HAL ADC Generic Driver

UM1725
Return value:
None
Description:

__HAL_ADC_GET_FLAG

Get the selected ADC's flag status.
Parameters:
__HANDLE__: specifies the ADC Handle.
__FLAG__: ADC flag.
Return value:
None
ADC Exported Types

90/964

HAL_ADC_STATE_RESET

ADC not yet initialized or disabled

HAL_ADC_STATE_READY

ADC peripheral ready for use

HAL_ADC_STATE_BUSY_INTERNAL

ADC is busy to internal process (initialization,
calibration)

HAL_ADC_STATE_TIMEOUT

TimeOut occurrence

HAL_ADC_STATE_ERROR_INTERNAL

Internal error occurrence

HAL_ADC_STATE_ERROR_CONFIG

Configuration error occurrence

HAL_ADC_STATE_ERROR_DMA

DMA error occurrence

HAL_ADC_STATE_REG_BUSY

A conversion on group regular is ongoing or
can occur (either by continuous mode,
external trigger, low power auto power-on (if
feature available), multimode ADC master
control (if feature available))

HAL_ADC_STATE_REG_EOC

Conversion data available on group regular

HAL_ADC_STATE_REG_OVR

Overrun occurrence

HAL_ADC_STATE_INJ_BUSY

A conversion on group injected is ongoing or
can occur (either by auto-injection mode,
external trigger, low power auto power-on (if
feature available), multimode ADC master
control (if feature available))

HAL_ADC_STATE_INJ_EOC

Conversion data available on group injected

HAL_ADC_STATE_AWD1

Out-of-window occurrence of analog
watchdog 1

HAL_ADC_STATE_AWD2

Not available on STM32F4 device: Out-ofwindow occurrence of analog watchdog 2

HAL_ADC_STATE_AWD3

Not available on STM32F4 device: Out-ofwindow occurrence of analog watchdog 3

HAL_ADC_STATE_MULTIMODE_SLAVE

Not available on STM32F4 device: ADC in
multimode slave state, controlled by another
ADC master (

DocID025834 Rev 4

UM1725

HAL ADC Generic Driver
ADC External Trigger Edge Regular
ADC_EXTERNALTRIGCONVEDGE_NONE
ADC_EXTERNALTRIGCONVEDGE_RISING
ADC_EXTERNALTRIGCONVEDGE_FALLING
ADC_EXTERNALTRIGCONVEDGE_RISINGFALLING
ADC External Trigger Source Regular
ADC_EXTERNALTRIGCONV_T1_CC1
ADC_EXTERNALTRIGCONV_T1_CC2
ADC_EXTERNALTRIGCONV_T1_CC3
ADC_EXTERNALTRIGCONV_T2_CC2
ADC_EXTERNALTRIGCONV_T2_CC3
ADC_EXTERNALTRIGCONV_T2_CC4
ADC_EXTERNALTRIGCONV_T2_TRGO
ADC_EXTERNALTRIGCONV_T3_CC1
ADC_EXTERNALTRIGCONV_T3_TRGO
ADC_EXTERNALTRIGCONV_T4_CC4
ADC_EXTERNALTRIGCONV_T5_CC1
ADC_EXTERNALTRIGCONV_T5_CC2
ADC_EXTERNALTRIGCONV_T5_CC3
ADC_EXTERNALTRIGCONV_T8_CC1
ADC_EXTERNALTRIGCONV_T8_TRGO
ADC_EXTERNALTRIGCONV_Ext_IT11
ADC_SOFTWARE_START
ADC Flags Definition
ADC_FLAG_AWD
ADC_FLAG_EOC
ADC_FLAG_JEOC
ADC_FLAG_JSTRT
ADC_FLAG_STRT
ADC_FLAG_OVR
ADC Interrupts Definition
ADC_IT_EOC
ADC_IT_AWD
ADC_IT_JEOC
ADC_IT_OVR

DocID025834 Rev 4

91/964

HAL ADC Generic Driver
ADC Resolution

UM1725

ADC_RESOLUTION_12B
ADC_RESOLUTION_10B
ADC_RESOLUTION_8B
ADC_RESOLUTION_6B
ADC Sampling Times
ADC_SAMPLETIME_3CYCLES
ADC_SAMPLETIME_15CYCLES
ADC_SAMPLETIME_28CYCLES
ADC_SAMPLETIME_56CYCLES
ADC_SAMPLETIME_84CYCLES
ADC_SAMPLETIME_112CYCLES
ADC_SAMPLETIME_144CYCLES
ADC_SAMPLETIME_480CYCLES

92/964

DocID025834 Rev 4

UM1725

HAL ADC Extension Driver

5

HAL ADC Extension Driver

5.1

ADCEx Firmware driver registers structures

5.1.1

ADC_InjectionConfTypeDef
Data Fields
uint32_t InjectedChannel
uint32_t InjectedRank
uint32_t InjectedSamplingTime
uint32_t InjectedOffset
uint32_t InjectedNbrOfConversion
uint32_t InjectedDiscontinuousConvMode
uint32_t AutoInjectedConv
uint32_t ExternalTrigInjecConv
uint32_t ExternalTrigInjecConvEdge

Field Documentation
uint32_t ADC_InjectionConfTypeDef::InjectedChannel
Selection of ADC channel to configure This parameter can be a value of
ADC_channels Note: Depending on devices, some channels may not be available on
package pins. Refer to device datasheet for channels availability.
uint32_t ADC_InjectionConfTypeDef::InjectedRank
Rank in the injected group sequencer This parameter must be a value of
ADCEx_injected_rank Note: In case of need to disable a channel or change order of
conversion sequencer, rank containing a previous channel setting can be overwritten
by the new channel setting (or parameter number of conversions can be adjusted)
uint32_t ADC_InjectionConfTypeDef::InjectedSamplingTime
Sampling time value to be set for the selected channel. Unit: ADC clock cycles
Conversion time is the addition of sampling time and processing time (12 ADC clock
cycles at ADC resolution 12 bits, 11 cycles at 10 bits, 9 cycles at 8 bits, 7 cycles at 6
bits). This parameter can be a value of ADC_sampling_times Caution: This
parameter updates the parameter property of the channel, that can be used into
regular and/or injected groups. If this same channel has been previously configured in
the other group (regular/injected), it will be updated to last setting. Note: In case of
usage of internal measurement channels (VrefInt/Vbat/TempSensor), sampling time
constraints must be respected (sampling time can be adjusted in function of ADC
clock frequency and sampling time setting) Refer to device datasheet for timings
values, parameters TS_vrefint, TS_temp (values rough order: 4us min).
uint32_t ADC_InjectionConfTypeDef::InjectedOffset
Defines the offset to be subtracted from the raw converted data (for channels set on
injected group only). Offset value must be a positive number. Depending of ADC
resolution selected (12, 10, 8 or 6 bits), this parameter must be a number between
Min_Data = 0x000 and Max_Data = 0xFFF, 0x3FF, 0xFF or 0x3F respectively.
uint32_t ADC_InjectionConfTypeDef::InjectedNbrOfConversion
Specifies the number of ranks that will be converted within the injected group
sequencer. To use the injected group sequencer and convert several ranks,
parameter 'ScanConvMode' must be enabled. This parameter must be a number
DocID025834 Rev 4

93/964

HAL ADC Extension Driver
UM1725
between Min_Data = 1 and Max_Data = 4. Caution: this setting impacts the entire
injected group. Therefore, call of HAL_ADCEx_InjectedConfigChannel() to configure
a channel on injected group can impact the configuration of other channels previously
set.
uint32_t ADC_InjectionConfTypeDef::InjectedDiscontinuousConvMode
Specifies whether the conversions sequence of injected group is performed in
Complete-sequence/Discontinuous-sequence (main sequence subdivided in
successive parts). Discontinuous mode is used only if sequencer is enabled
(parameter 'ScanConvMode'). If sequencer is disabled, this parameter is discarded.
Discontinuous mode can be enabled only if continuous mode is disabled. If continuous
mode is enabled, this parameter setting is discarded. This parameter can be set to
ENABLE or DISABLE. Note: For injected group, number of discontinuous ranks
increment is fixed to one-by-one. Caution: this setting impacts the entire injected
group. Therefore, call of HAL_ADCEx_InjectedConfigChannel() to configure a
channel on injected group can impact the configuration of other channels previously
set.
uint32_t ADC_InjectionConfTypeDef::AutoInjectedConv
Enables or disables the selected ADC automatic injected group conversion after
regular one This parameter can be set to ENABLE or DISABLE. Note: To use
Automatic injected conversion, discontinuous mode must be disabled
('DiscontinuousConvMode' and 'InjectedDiscontinuousConvMode' set to DISABLE)
Note: To use Automatic injected conversion, injected group external triggers must be
disabled ('ExternalTrigInjecConv' set to ADC_SOFTWARE_START) Note: In case of
DMA used with regular group: if DMA configured in normal mode (single shot) JAUTO
will be stopped upon DMA transfer complete. To maintain JAUTO always enabled,
DMA must be configured in circular mode. Caution: this setting impacts the entire
injected group. Therefore, call of HAL_ADCEx_InjectedConfigChannel() to configure
a channel on injected group can impact the configuration of other channels previously
set.
uint32_t ADC_InjectionConfTypeDef::ExternalTrigInjecConv
Selects the external event used to trigger the conversion start of injected group. If set
to ADC_INJECTED_SOFTWARE_START, external triggers are disabled. If set to
external trigger source, triggering is on event rising edge. This parameter can be a
value of ADCEx_External_trigger_Source_Injected Note: This parameter must be
modified when ADC is disabled (before ADC start conversion or after ADC stop
conversion). If ADC is enabled, this parameter setting is bypassed without error
reporting (as it can be the expected behaviour in case of another parameter update on
the fly) Caution: this setting impacts the entire injected group. Therefore, call of
HAL_ADCEx_InjectedConfigChannel() to configure a channel on injected group can
impact the configuration of other channels previously set.
uint32_t ADC_InjectionConfTypeDef::ExternalTrigInjecConvEdge
Selects the external trigger edge of injected group. This parameter can be a value of
ADCEx_External_trigger_edge_Injected. If trigger is set to
ADC_INJECTED_SOFTWARE_START, this parameter is discarded. Caution: this
setting impacts the entire injected group. Therefore, call of
HAL_ADCEx_InjectedConfigChannel() to configure a channel on injected group can
impact the configuration of other channels previously set.

94/964

DocID025834 Rev 4

UM1725

5.1.2

HAL ADC Extension Driver

ADC_MultiModeTypeDef
Data Fields
uint32_t Mode
uint32_t DMAAccessMode
uint32_t TwoSamplingDelay

Field Documentation
uint32_t ADC_MultiModeTypeDef::Mode
Configures the ADC to operate in independent or multi mode. This parameter can be
a value of ADCEx_Common_mode
uint32_t ADC_MultiModeTypeDef::DMAAccessMode
Configures the Direct memory access mode for multi ADC mode. This parameter can
be a value of ADCEx_Direct_memory_access_mode_for_multi_mode
uint32_t ADC_MultiModeTypeDef::TwoSamplingDelay
Configures the Delay between 2 sampling phases. This parameter can be a value of
ADC_delay_between_2_sampling_phases

5.2

ADCEx Firmware driver API description

5.2.1

How to use this driver
1.

2.
3.

Initialize the ADC low level resources by implementing the HAL_ADC_MspInit():
a.
Enable the ADC interface clock using __HAL_RCC_ADC_CLK_ENABLE()
b.
ADC pins configuration
Enable the clock for the ADC GPIOs using the following function:
__HAL_RCC_GPIOx_CLK_ENABLE()
Configure these ADC pins in analog mode using HAL_GPIO_Init()
c.
In case of using interrupts (e.g. HAL_ADC_Start_IT())
Configure the ADC interrupt priority using HAL_NVIC_SetPriority()
Enable the ADC IRQ handler using HAL_NVIC_EnableIRQ()
In ADC IRQ handler, call HAL_ADC_IRQHandler()
d.
In case of using DMA to control data transfer (e.g. HAL_ADC_Start_DMA())
Enable the DMAx interface clock using
__HAL_RCC_DMAx_CLK_ENABLE()
Configure and enable two DMA streams stream for managing data transfer
from peripheral to memory (output stream)
Associate the initialized DMA handle to the ADC DMA handle using
__HAL_LINKDMA()
Configure the priority and enable the NVIC for the transfer complete
interrupt on the two DMA Streams. The output stream should have higher
priority than the input stream.
Configure the ADC Prescaler, conversion resolution and data alignment using the
HAL_ADC_Init() function.
Configure the ADC Injected channels group features, use HAL_ADC_Init() and
HAL_ADC_ConfigChannel() functions.
DocID025834 Rev 4

95/964

HAL ADC Extension Driver
4.
Three operation modes are available within this driver :

UM1725

Polling mode IO operation
Start the ADC peripheral using HAL_ADCEx_InjectedStart()
Wait for end of conversion using HAL_ADC_PollForConversion(), at this stage user
can specify the value of timeout according to his end application
To read the ADC converted values, use the HAL_ADCEx_InjectedGetValue()
function.
Stop the ADC peripheral using HAL_ADCEx_InjectedStop()

Interrupt mode IO operation
Start the ADC peripheral using HAL_ADCEx_InjectedStart_IT()
Use HAL_ADC_IRQHandler() called under ADC_IRQHandler() Interrupt subroutine
At ADC end of conversion HAL_ADCEx_InjectedConvCpltCallback() function is
executed and user can add his own code by customization of function pointer
HAL_ADCEx_InjectedConvCpltCallback
In case of ADC Error, HAL_ADCEx_InjectedErrorCallback() function is executed and
user can add his own code by customization of function pointer
HAL_ADCEx_InjectedErrorCallback
Stop the ADC peripheral using HAL_ADCEx_InjectedStop_IT()

DMA mode IO operation
Start the ADC peripheral using HAL_ADCEx_InjectedStart_DMA(), at this stage the
user specify the length of data to be transferred at each end of conversion
At The end of data transfer ba HAL_ADCEx_InjectedConvCpltCallback() function is
executed and user can add his own code by customization of function pointer
HAL_ADCEx_InjectedConvCpltCallback
In case of transfer Error, HAL_ADCEx_InjectedErrorCallback() function is executed
and user can add his own code by customization of function pointer
HAL_ADCEx_InjectedErrorCallback
Stop the ADC peripheral using HAL_ADCEx_InjectedStop_DMA()

Multi mode ADCs Regular channels configuration
Select the Multi mode ADC regular channels features (dual or triple mode) and
configure the DMA mode using HAL_ADCEx_MultiModeConfigChannel() functions.
Start the ADC peripheral using HAL_ADCEx_MultiModeStart_DMA(), at this stage the
user specify the length of data to be transferred at each end of conversion
Read the ADCs converted values using the HAL_ADCEx_MultiModeGetValue()
function.

96/964

DocID025834 Rev 4

UM1725

5.2.2

HAL ADC Extension Driver

Extended features functions
This section provides functions allowing to:
Start conversion of injected channel.
Stop conversion of injected channel.
Start multimode and enable DMA transfer.
Stop multimode and disable DMA transfer.
Get result of injected channel conversion.
Get result of multimode conversion.
Configure injected channels.
Configure multimode.
This section contains the following APIs:
HAL_ADCEx_InjectedStart()
HAL_ADCEx_InjectedStart_IT()
HAL_ADCEx_InjectedStop()
HAL_ADCEx_InjectedPollForConversion()
HAL_ADCEx_InjectedStop_IT()
HAL_ADCEx_InjectedGetValue()
HAL_ADCEx_MultiModeStart_DMA()
HAL_ADCEx_MultiModeStop_DMA()
HAL_ADCEx_MultiModeGetValue()
HAL_ADCEx_InjectedConvCpltCallback()
HAL_ADCEx_InjectedConfigChannel()
HAL_ADCEx_MultiModeConfigChannel()

5.2.3

Detailed description of functions
HAL_ADCEx_InjectedStart
Function Name

HAL_StatusTypeDef HAL_ADCEx_InjectedStart
(ADC_HandleTypeDef * hadc)

Function Description

Enables the selected ADC software start conversion of the injected
channels.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

HAL: status

HAL_ADCEx_InjectedStop
Function Name

HAL_StatusTypeDef HAL_ADCEx_InjectedStop
(ADC_HandleTypeDef * hadc)

Function Description

Stop conversion of injected channels.

Parameters

hadc: ADC handle

Return values

None

Notes

If ADC must be disabled and if conversion is on going on
regular group, function HAL_ADC_Stop must be used to stop
both injected and regular groups, and disable the ADC.
DocID025834 Rev 4

97/964

HAL ADC Extension Driver

UM1725
If injected group mode auto-injection is enabled, function
HAL_ADC_Stop must be used.
In case of auto-injection mode, HAL_ADC_Stop must be
used.

HAL_ADCEx_InjectedPollForConversion
Function Name

HAL_StatusTypeDef HAL_ADCEx_InjectedPollForConversion
(ADC_HandleTypeDef * hadc, uint32_t Timeout)

Function Description

Poll for injected conversion complete.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.
Timeout: Timeout value in millisecond.

Return values

HAL: status

HAL_ADCEx_InjectedStart_IT
Function Name

HAL_StatusTypeDef HAL_ADCEx_InjectedStart_IT
(ADC_HandleTypeDef * hadc)

Function Description

Enables the interrupt and starts ADC conversion of injected
channels.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

HAL: status.

HAL_ADCEx_InjectedStop_IT
Function Name

HAL_StatusTypeDef HAL_ADCEx_InjectedStop_IT
(ADC_HandleTypeDef * hadc)

Function Description

Stop conversion of injected channels, disable interruption of endof-conversion.

Parameters

hadc: ADC handle

Return values

None

Notes

If ADC must be disabled and if conversion is on going on
regular group, function HAL_ADC_Stop must be used to stop
both injected and regular groups, and disable the ADC.
If injected group mode auto-injection is enabled, function
HAL_ADC_Stop must be used.

HAL_ADCEx_InjectedGetValue
Function Name

uint32_t HAL_ADCEx_InjectedGetValue (ADC_HandleTypeDef
* hadc, uint32_t InjectedRank)

Function Description

Gets the converted value from data register of injected channel.

Parameters

98/964

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.
InjectedRank: the ADC injected rank. This parameter can be
one of the following values:
DocID025834 Rev 4

UM1725

HAL ADC Extension Driver
ADC_INJECTED_RANK_1: Injected Channel1 selected
ADC_INJECTED_RANK_2: Injected Channel2 selected
ADC_INJECTED_RANK_3: Injected Channel3 selected
ADC_INJECTED_RANK_4: Injected Channel4 selected
Return values

None

HAL_ADCEx_MultiModeStart_DMA
Function Name

HAL_StatusTypeDef HAL_ADCEx_MultiModeStart_DMA
(ADC_HandleTypeDef * hadc, uint32_t * pData, uint32_t
Length)

Function Description

Enables ADC DMA request after last transfer (Multi-ADC mode)
and enables ADC peripheral.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.
pData: Pointer to buffer in which transferred from ADC
peripheral to memory will be stored.
Length: The length of data to be transferred from ADC
peripheral to memory.

Return values

HAL: status

Notes

Caution: This function must be used only with the ADC
master.

HAL_ADCEx_MultiModeStop_DMA
Function Name

HAL_StatusTypeDef HAL_ADCEx_MultiModeStop_DMA
(ADC_HandleTypeDef * hadc)

Function Description

Disables ADC DMA (multi-ADC mode) and disables ADC
peripheral.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

HAL: status

HAL_ADCEx_MultiModeGetValue
Function Name

uint32_t HAL_ADCEx_MultiModeGetValue
(ADC_HandleTypeDef * hadc)

Function Description

Returns the last ADC1, ADC2 and ADC3 regular conversions
results data in the selected multi mode.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

The: converted data value.

DocID025834 Rev 4

99/964

HAL ADC Extension Driver

UM1725

HAL_ADCEx_InjectedConvCpltCallback
Function Name

void HAL_ADCEx_InjectedConvCpltCallback
(ADC_HandleTypeDef * hadc)

Function Description

Injected conversion complete callback in non blocking mode.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.

Return values

None

HAL_ADCEx_InjectedConfigChannel
Function Name

HAL_StatusTypeDef HAL_ADCEx_InjectedConfigChannel
(ADC_HandleTypeDef * hadc, ADC_InjectionConfTypeDef *
sConfigInjected)

Function Description

Configures for the selected ADC injected channel its
corresponding rank in the sequencer and its sample time.

Parameters

hadc: pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.
sConfigInjected: ADC configuration structure for injected
channel.

Return values

None

HAL_ADCEx_MultiModeConfigChannel
Function Name

HAL_StatusTypeDef HAL_ADCEx_MultiModeConfigChannel
(ADC_HandleTypeDef * hadc, ADC_MultiModeTypeDef *
multimode)

Function Description

Configures the ADC multi-mode.

Parameters

hadc: : pointer to a ADC_HandleTypeDef structure that
contains the configuration information for the specified ADC.
multimode: : pointer to an ADC_MultiModeTypeDef
structure that contains the configuration information for
multimode.

Return values

HAL: status

5.3

ADCEx Firmware driver defines

5.3.1

ADCEx
ADC Specific Channels
ADC_CHANNEL_DIFFERENCIATION_TEMPSENSOR_VBAT
ADC_CHANNEL_TEMPSENSOR
ADC Common Mode
ADC_MODE_INDEPENDENT
ADC_DUALMODE_REGSIMULT_INJECSIMULT
ADC_DUALMODE_REGSIMULT_ALTERTRIG

100/964

DocID025834 Rev 4

UM1725

HAL ADC Extension Driver
ADC_DUALMODE_INJECSIMULT
ADC_DUALMODE_REGSIMULT
ADC_DUALMODE_INTERL
ADC_DUALMODE_ALTERTRIG
ADC_TRIPLEMODE_REGSIMULT_INJECSIMULT
ADC_TRIPLEMODE_REGSIMULT_AlterTrig
ADC_TRIPLEMODE_INJECSIMULT
ADC_TRIPLEMODE_REGSIMULT
ADC_TRIPLEMODE_INTERL
ADC_TRIPLEMODE_ALTERTRIG
ADC Direct Memory Access Mode For Multi Mode
ADC_DMAACCESSMODE_DISABLED

DMA mode disabled

ADC_DMAACCESSMODE_1

DMA mode 1 enabled (2 / 3 half-words one by
one - 1 then 2 then 3)

ADC_DMAACCESSMODE_2

DMA mode 2 enabled (2 / 3 half-words by pairs 2&1 then 1&3 then 3&2)

ADC_DMAACCESSMODE_3

DMA mode 3 enabled (2 / 3 bytes by pairs - 2&1
then 1&3 then 3&2)

ADC External Trigger Edge Injected
ADC_EXTERNALTRIGINJECCONVEDGE_NONE
ADC_EXTERNALTRIGINJECCONVEDGE_RISING
ADC_EXTERNALTRIGINJECCONVEDGE_FALLING
ADC_EXTERNALTRIGINJECCONVEDGE_RISINGFALLING
ADC External Trigger Source Injected
ADC_EXTERNALTRIGINJECCONV_T1_CC4
ADC_EXTERNALTRIGINJECCONV_T1_TRGO
ADC_EXTERNALTRIGINJECCONV_T2_CC1
ADC_EXTERNALTRIGINJECCONV_T2_TRGO
ADC_EXTERNALTRIGINJECCONV_T3_CC2
ADC_EXTERNALTRIGINJECCONV_T3_CC4
ADC_EXTERNALTRIGINJECCONV_T4_CC1
ADC_EXTERNALTRIGINJECCONV_T4_CC2
ADC_EXTERNALTRIGINJECCONV_T4_CC3
ADC_EXTERNALTRIGINJECCONV_T4_TRGO
ADC_EXTERNALTRIGINJECCONV_T5_CC4
ADC_EXTERNALTRIGINJECCONV_T5_TRGO
ADC_EXTERNALTRIGINJECCONV_T8_CC2

DocID025834 Rev 4

101/964

HAL ADC Extension Driver
ADC_EXTERNALTRIGINJECCONV_T8_CC3
ADC_EXTERNALTRIGINJECCONV_T8_CC4
ADC_EXTERNALTRIGINJECCONV_EXT_IT15
ADC_INJECTED_SOFTWARE_START
ADC Injected Rank
ADC_INJECTED_RANK_1
ADC_INJECTED_RANK_2
ADC_INJECTED_RANK_3
ADC_INJECTED_RANK_4

102/964

DocID025834 Rev 4

UM1725

UM1725

HAL CAN Generic Driver

6

HAL CAN Generic Driver

6.1

CAN Firmware driver registers structures

6.1.1

CAN_InitTypeDef
Data Fields
uint32_t Prescaler
uint32_t Mode
uint32_t SJW
uint32_t BS1
uint32_t BS2
uint32_t TTCM
uint32_t ABOM
uint32_t AWUM
uint32_t NART
uint32_t RFLM
uint32_t TXFP

Field Documentation
uint32_t CAN_InitTypeDef::Prescaler
Specifies the length of a time quantum. This parameter must be a number between
Min_Data = 1 and Max_Data = 1024
uint32_t CAN_InitTypeDef::Mode
Specifies the CAN operating mode. This parameter can be a value of
CAN_operating_mode
uint32_t CAN_InitTypeDef::SJW
Specifies the maximum number of time quanta the CAN hardware is allowed to
lengthen or shorten a bit to perform resynchronization. This parameter can be a value
of CAN_synchronisation_jump_width
uint32_t CAN_InitTypeDef::BS1
Specifies the number of time quanta in Bit Segment 1. This parameter can be a value
of CAN_time_quantum_in_bit_segment_1
uint32_t CAN_InitTypeDef::BS2
Specifies the number of time quanta in Bit Segment 2. This parameter can be a value
of CAN_time_quantum_in_bit_segment_2
uint32_t CAN_InitTypeDef::TTCM
Enable or disable the time triggered communication mode. This parameter can be set
to ENABLE or DISABLE.
uint32_t CAN_InitTypeDef::ABOM
Enable or disable the automatic bus-off management. This parameter can be set to
ENABLE or DISABLE
uint32_t CAN_InitTypeDef::AWUM
Enable or disable the automatic wake-up mode. This parameter can be set to
ENABLE or DISABLE
uint32_t CAN_InitTypeDef::NART
Enable or disable the non-automatic retransmission mode. This parameter can be set
to ENABLE or DISABLE
DocID025834 Rev 4

103/964

HAL CAN Generic Driver

UM1725

uint32_t CAN_InitTypeDef::RFLM
Enable or disable the receive FIFO Locked mode. This parameter can be set to
ENABLE or DISABLE
uint32_t CAN_InitTypeDef::TXFP
Enable or disable the transmit FIFO priority. This parameter can be set to ENABLE or
DISABLE

6.1.2

CAN_FilterConfTypeDef
Data Fields
uint32_t FilterIdHigh
uint32_t FilterIdLow
uint32_t FilterMaskIdHigh
uint32_t FilterMaskIdLow
uint32_t FilterFIFOAssignment
uint32_t FilterNumber
uint32_t FilterMode
uint32_t FilterScale
uint32_t FilterActivation
uint32_t BankNumber

Field Documentation
uint32_t CAN_FilterConfTypeDef::FilterIdHigh
Specifies the filter identification number (MSBs for a 32-bit configuration, first one for
a 16-bit configuration). This parameter must be a number between Min_Data =
0x0000U and Max_Data = 0xFFFFU
uint32_t CAN_FilterConfTypeDef::FilterIdLow
Specifies the filter identification number (LSBs for a 32-bit configuration, second one
for a 16-bit configuration). This parameter must be a number between Min_Data =
0x0000U and Max_Data = 0xFFFFU
uint32_t CAN_FilterConfTypeDef::FilterMaskIdHigh
Specifies the filter mask number or identification number, according to the mode
(MSBs for a 32-bit configuration, first one for a 16-bit configuration). This parameter
must be a number between Min_Data = 0x0000U and Max_Data = 0xFFFFU
uint32_t CAN_FilterConfTypeDef::FilterMaskIdLow
Specifies the filter mask number or identification number, according to the mode
(LSBs for a 32-bit configuration, second one for a 16-bit configuration). This parameter
must be a number between Min_Data = 0x0000U and Max_Data = 0xFFFFU
uint32_t CAN_FilterConfTypeDef::FilterFIFOAssignment
Specifies the FIFO (0 or 1) which will be assigned to the filter. This parameter can be
a value of CAN_filter_FIFO
uint32_t CAN_FilterConfTypeDef::FilterNumber
Specifies the filter which will be initialized. This parameter must be a number between
Min_Data = 0 and Max_Data = 27
uint32_t CAN_FilterConfTypeDef::FilterMode
Specifies the filter mode to be initialized. This parameter can be a value of
CAN_filter_mode
uint32_t CAN_FilterConfTypeDef::FilterScale
Specifies the filter scale. This parameter can be a value of CAN_filter_scale
104/964

DocID025834 Rev 4

UM1725

HAL CAN Generic Driver
uint32_t CAN_FilterConfTypeDef::FilterActivation
Enable or disable the filter. This parameter can be set to ENABLE or DISABLE.
uint32_t CAN_FilterConfTypeDef::BankNumber
Select the start slave bank filter. This parameter must be a number between
Min_Data = 0 and Max_Data = 28

6.1.3

CanTxMsgTypeDef
Data Fields
uint32_t StdId
uint32_t ExtId
uint32_t IDE
uint32_t RTR
uint32_t DLC
uint8_t Data

Field Documentation
uint32_t CanTxMsgTypeDef::StdId
Specifies the standard identifier. This parameter must be a number between
Min_Data = 0 and Max_Data = 0x7FF
uint32_t CanTxMsgTypeDef::ExtId
Specifies the extended identifier. This parameter must be a number between
Min_Data = 0 and Max_Data = 0x1FFFFFFFU
uint32_t CanTxMsgTypeDef::IDE
Specifies the type of identifier for the message that will be transmitted. This
parameter can be a value of CAN_Identifier_Type
uint32_t CanTxMsgTypeDef::RTR
Specifies the type of frame for the message that will be transmitted. This parameter
can be a value of CAN_remote_transmission_request
uint32_t CanTxMsgTypeDef::DLC
Specifies the length of the frame that will be transmitted. This parameter must be a
number between Min_Data = 0 and Max_Data = 8
uint8_t CanTxMsgTypeDef::Data[8]
Contains the data to be transmitted. This parameter must be a number between
Min_Data = 0 and Max_Data = 0xFF

6.1.4

CanRxMsgTypeDef
Data Fields
uint32_t StdId
uint32_t ExtId
uint32_t IDE
uint32_t RTR
uint32_t DLC
uint8_t Data
uint32_t FMI
DocID025834 Rev 4

105/964

HAL CAN Generic Driver

UM1725

uint32_t FIFONumber

Field Documentation
uint32_t CanRxMsgTypeDef::StdId
Specifies the standard identifier. This parameter must be a number between
Min_Data = 0 and Max_Data = 0x7FF
uint32_t CanRxMsgTypeDef::ExtId
Specifies the extended identifier. This parameter must be a number between
Min_Data = 0 and Max_Data = 0x1FFFFFFFU
uint32_t CanRxMsgTypeDef::IDE
Specifies the type of identifier for the message that will be received. This parameter
can be a value of CAN_Identifier_Type
uint32_t CanRxMsgTypeDef::RTR
Specifies the type of frame for the received message. This parameter can be a value
of CAN_remote_transmission_request
uint32_t CanRxMsgTypeDef::DLC
Specifies the length of the frame that will be received. This parameter must be a
number between Min_Data = 0 and Max_Data = 8
uint8_t CanRxMsgTypeDef::Data[8]
Contains the data to be received. This parameter must be a number between
Min_Data = 0 and Max_Data = 0xFF
uint32_t CanRxMsgTypeDef::FMI
Specifies the index of the filter the message stored in the mailbox passes through.
This parameter must be a number between Min_Data = 0 and Max_Data = 0xFF
uint32_t CanRxMsgTypeDef::FIFONumber
Specifies the receive FIFO number. This parameter can be CAN_FIFO0 or
CAN_FIFO1

6.1.5

CAN_HandleTypeDef
Data Fields
CAN_TypeDef * Instance
CAN_InitTypeDef Init
CanTxMsgTypeDef * pTxMsg
CanRxMsgTypeDef * pRxMsg
__IO HAL_CAN_StateTypeDef State
HAL_LockTypeDef Lock
__IO uint32_t ErrorCode

Field Documentation
CAN_TypeDef* CAN_HandleTypeDef::Instance
Register base address
CAN_InitTypeDef CAN_HandleTypeDef::Init
CAN required parameters
CanTxMsgTypeDef* CAN_HandleTypeDef::pTxMsg
Pointer to transmit structure
CanRxMsgTypeDef* CAN_HandleTypeDef::pRxMsg
Pointer to reception structure
106/964

DocID025834 Rev 4

UM1725

HAL CAN Generic Driver
__IO HAL_CAN_StateTypeDef CAN_HandleTypeDef::State
CAN communication state
HAL_LockTypeDef CAN_HandleTypeDef::Lock
CAN locking object
__IO uint32_t CAN_HandleTypeDef::ErrorCode
CAN Error code

6.2

CAN Firmware driver API description

6.2.1

How to use this driver
1.

2.

3.
4.
5.

Enable the CAN controller interface clock using __HAL_RCC_CAN1_CLK_ENABLE()
for CAN1 and __HAL_RCC_CAN2_CLK_ENABLE() for CAN2 In case you are using
CAN2 only, you have to enable the CAN1 clock.
CAN pins configuration
Enable the clock for the CAN GPIOs using the following function:
__GPIOx_CLK_ENABLE()
Connect and configure the involved CAN pins to AF9 using the following function
HAL_GPIO_Init()
Initialize and configure the CAN using CAN_Init() function.
Transmit the desired CAN frame using HAL_CAN_Transmit() function.
Receive a CAN frame using HAL_CAN_Receive() function.

Polling mode IO operation
Start the CAN peripheral transmission and wait the end of this operation using
HAL_CAN_Transmit(), at this stage user can specify the value of timeout according to
his end application
Start the CAN peripheral reception and wait the end of this operation using
HAL_CAN_Receive(), at this stage user can specify the value of timeout according to
his end application

Interrupt mode IO operation
Start the CAN peripheral transmission using HAL_CAN_Transmit_IT()
Start the CAN peripheral reception using HAL_CAN_Receive_IT()
Use HAL_CAN_IRQHandler() called under the used CAN Interrupt subroutine
At CAN end of transmission HAL_CAN_TxCpltCallback() function is executed and
user can add his own code by customization of function pointer
HAL_CAN_TxCpltCallback
In case of CAN Error, HAL_CAN_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_CAN_ErrorCallback

CAN HAL driver macros list
Below the list of most used macros in CAN HAL driver.
__HAL_CAN_ENABLE_IT: Enable the specified CAN interrupts
__HAL_CAN_DISABLE_IT: Disable the specified CAN interrupts

DocID025834 Rev 4

107/964

HAL CAN Generic Driver

UM1725

__HAL_CAN_GET_IT_SOURCE: Check if the specified CAN interrupt source is
enabled or disabled
__HAL_CAN_CLEAR_FLAG: Clear the CAN's pending flags
__HAL_CAN_GET_FLAG: Get the selected CAN's flag status
You can refer to the CAN HAL driver header file for more useful macros

6.2.2

Initialization and de-initialization functions
This section provides functions allowing to:
Initialize and configure the CAN.
De-initialize the CAN.
This section contains the following APIs:
HAL_CAN_Init()
HAL_CAN_ConfigFilter()
HAL_CAN_DeInit()
HAL_CAN_MspInit()
HAL_CAN_MspDeInit()

6.2.3

IO operation functions
This section provides functions allowing to:
Transmit a CAN frame message.
Receive a CAN frame message.
Enter CAN peripheral in sleep mode.
Wake up the CAN peripheral from sleep mode.
This section contains the following APIs:
HAL_CAN_Transmit()
HAL_CAN_Transmit_IT()
HAL_CAN_Receive()
HAL_CAN_Receive_IT()
HAL_CAN_Sleep()
HAL_CAN_WakeUp()
HAL_CAN_IRQHandler()
HAL_CAN_TxCpltCallback()
HAL_CAN_RxCpltCallback()
HAL_CAN_ErrorCallback()

6.2.4

Peripheral State and Error functions
This subsection provides functions allowing to :
Check the CAN state.
Check CAN Errors detected during interrupt process
This section contains the following APIs:
HAL_CAN_GetState()
HAL_CAN_GetError()

108/964

DocID025834 Rev 4

UM1725

6.2.5

HAL CAN Generic Driver

Detailed description of functions
HAL_CAN_Init
Function Name

HAL_StatusTypeDef HAL_CAN_Init (CAN_HandleTypeDef *
hcan)

Function Description

Initializes the CAN peripheral according to the specified
parameters in the CAN_InitStruct.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

HAL: status

HAL_CAN_ConfigFilter
Function Name

HAL_StatusTypeDef HAL_CAN_ConfigFilter
(CAN_HandleTypeDef * hcan, CAN_FilterConfTypeDef *
sFilterConfig)

Function Description

Configures the CAN reception filter according to the specified
parameters in the CAN_FilterInitStruct.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.
sFilterConfig: pointer to a CAN_FilterConfTypeDef structure
that contains the filter configuration information.

Return values

None

HAL_CAN_DeInit
Function Name

HAL_StatusTypeDef HAL_CAN_DeInit (CAN_HandleTypeDef *
hcan)

Function Description

Deinitializes the CANx peripheral registers to their default reset
values.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

HAL: status

HAL_CAN_MspInit
Function Name

void HAL_CAN_MspInit (CAN_HandleTypeDef * hcan)

Function Description

Initializes the CAN MSP.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

None

HAL_CAN_MspDeInit
Function Name

void HAL_CAN_MspDeInit (CAN_HandleTypeDef * hcan)

Function Description

DeInitializes the CAN MSP.
DocID025834 Rev 4

109/964

HAL CAN Generic Driver
Parameters

UM1725
hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

None

HAL_CAN_Transmit
Function Name

HAL_StatusTypeDef HAL_CAN_Transmit
(CAN_HandleTypeDef * hcan, uint32_t Timeout)

Function Description

Initiates and transmits a CAN frame message.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CAN_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_CAN_Transmit_IT
(CAN_HandleTypeDef * hcan)

Function Description

Initiates and transmits a CAN frame message.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

HAL: status

HAL_CAN_Receive
Function Name

HAL_StatusTypeDef HAL_CAN_Receive (CAN_HandleTypeDef
* hcan, uint8_t FIFONumber, uint32_t Timeout)

Function Description

Receives a correct CAN frame.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.
FIFONumber: FIFO Number value
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CAN_Receive_IT

110/964

Function Name

HAL_StatusTypeDef HAL_CAN_Receive_IT
(CAN_HandleTypeDef * hcan, uint8_t FIFONumber)

Function Description

Receives a correct CAN frame.

Parameters

hcan: Pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.
FIFONumber: Specify the FIFO number

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL CAN Generic Driver

HAL_CAN_Sleep
Function Name

HAL_StatusTypeDef HAL_CAN_Sleep (CAN_HandleTypeDef *
hcan)

Function Description

Enters the Sleep (low power) mode.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

HAL: status.

HAL_CAN_WakeUp
Function Name

HAL_StatusTypeDef HAL_CAN_WakeUp
(CAN_HandleTypeDef * hcan)

Function Description

Wakes up the CAN peripheral from sleep mode, after that the CAN
peripheral is in the normal mode.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

HAL: status.

HAL_CAN_IRQHandler
Function Name

void HAL_CAN_IRQHandler (CAN_HandleTypeDef * hcan)

Function Description

Handles CAN interrupt request.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

None

HAL_CAN_TxCpltCallback
Function Name

void HAL_CAN_TxCpltCallback (CAN_HandleTypeDef * hcan)

Function Description

Transmission complete callback in non blocking mode.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

None

HAL_CAN_RxCpltCallback
Function Name

void HAL_CAN_RxCpltCallback (CAN_HandleTypeDef * hcan)

Function Description

Transmission complete callback in non blocking mode.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

None

DocID025834 Rev 4

111/964

HAL CAN Generic Driver

UM1725

HAL_CAN_ErrorCallback
Function Name

void HAL_CAN_ErrorCallback (CAN_HandleTypeDef * hcan)

Function Description

Error CAN callback.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

None

HAL_CAN_GetError
Function Name

uint32_t HAL_CAN_GetError (CAN_HandleTypeDef * hcan)

Function Description

Return the CAN error code.

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

CAN: Error Code

HAL_CAN_GetState
Function Name

HAL_CAN_StateTypeDef HAL_CAN_GetState
(CAN_HandleTypeDef * hcan)

Function Description

return the CAN state

Parameters

hcan: pointer to a CAN_HandleTypeDef structure that
contains the configuration information for the specified CAN.

Return values

HAL: state

6.3

CAN Firmware driver defines

6.3.1

CAN
CAN Exported Macros
__HAL_CAN_RESET_HANDLE_STATE

Description:
Reset CAN handle state.
Parameters:
__HANDLE__: specifies the CAN Handle.
Return value:
None

__HAL_CAN_ENABLE_IT

Description:
Enable the specified CAN interrupts.
Parameters:
__HANDLE__: CAN handle
__INTERRUPT__: CAN Interrupt
Return value:
None

112/964

DocID025834 Rev 4

UM1725

HAL CAN Generic Driver
Description:

__HAL_CAN_DISABLE_IT

Disable the specified CAN interrupts.
Parameters:
__HANDLE__: CAN handle
__INTERRUPT__: CAN Interrupt
Return value:
None
__HAL_CAN_MSG_PENDING

Description:
Return the number of pending received
messages.
Parameters:
__HANDLE__: CAN handle
__FIFONUMBER__: Receive FIFO
number, CAN_FIFO0 or CAN_FIFO1.
Return value:
The: number of pending message.

__HAL_CAN_GET_FLAG

Description:
Check whether the specified CAN flag is
set or not.
Parameters:
__HANDLE__: CAN Handle
__FLAG__: specifies the flag to check.
This parameter can be one of the following
values:
CAN_TSR_RQCP0: Request
MailBox0 Flag
CAN_TSR_RQCP1: Request
MailBox1 Flag
CAN_TSR_RQCP2: Request
MailBox2 Flag
CAN_FLAG_TXOK0: Transmission
OK MailBox0 Flag
CAN_FLAG_TXOK1: Transmission
OK MailBox1 Flag
CAN_FLAG_TXOK2: Transmission
OK MailBox2 Flag
CAN_FLAG_TME0: Transmit mailbox
0 empty Flag
CAN_FLAG_TME1: Transmit mailbox
1 empty Flag
CAN_FLAG_TME2: Transmit mailbox
2 empty Flag
CAN_FLAG_FMP0: FIFO 0 Message
Pending Flag
CAN_FLAG_FF0: FIFO 0 Full Flag
CAN_FLAG_FOV0: FIFO 0 Overrun
DocID025834 Rev 4

113/964

HAL CAN Generic Driver

UM1725
Flag
CAN_FLAG_FMP1: FIFO 1 Message
Pending Flag
CAN_FLAG_FF1: FIFO 1 Full Flag
CAN_FLAG_FOV1: FIFO 1 Overrun
Flag
CAN_FLAG_WKU: Wake up Flag
CAN_FLAG_SLAK: Sleep
acknowledge Flag
CAN_FLAG_SLAKI: Sleep
acknowledge Flag
CAN_FLAG_EWG: Error Warning
Flag
CAN_FLAG_EPV: Error Passive Flag
CAN_FLAG_BOF: Bus-Off Flag
Return value:
The: new state of __FLAG__ (TRUE or
FALSE).

__HAL_CAN_CLEAR_FLAG

Description:
Clear the specified CAN pending flag.
Parameters:
__HANDLE__: CAN Handle.
__FLAG__: specifies the flag to check.
This parameter can be one of the following
values:
CAN_TSR_RQCP0: Request
MailBox0 Flag
CAN_TSR_RQCP1: Request
MailBox1 Flag
CAN_TSR_RQCP2: Request
MailBox2 Flag
CAN_FLAG_TXOK0: Transmission
OK MailBox0 Flag
CAN_FLAG_TXOK1: Transmission
OK MailBox1 Flag
CAN_FLAG_TXOK2: Transmission
OK MailBox2 Flag
CAN_FLAG_TME0: Transmit mailbox
0 empty Flag
CAN_FLAG_TME1: Transmit mailbox
1 empty Flag
CAN_FLAG_TME2: Transmit mailbox
2 empty Flag
CAN_FLAG_FMP0: FIFO 0 Message
Pending Flag
CAN_FLAG_FF0: FIFO 0 Full Flag
CAN_FLAG_FOV0: FIFO 0 Overrun
Flag
CAN_FLAG_FMP1: FIFO 1 Message
Pending Flag
CAN_FLAG_FF1: FIFO 1 Full Flag

114/964

DocID025834 Rev 4

UM1725

HAL CAN Generic Driver
CAN_FLAG_FOV1: FIFO 1 Overrun
Flag
CAN_FLAG_WKU: Wake up Flag
CAN_FLAG_SLAK: Sleep
acknowledge Flag
CAN_FLAG_SLAKI: Sleep
acknowledge Flag
Return value:
The: new state of __FLAG__ (TRUE or
FALSE).
__HAL_CAN_GET_IT_SOURCE

Description:
Check if the specified CAN interrupt source
is enabled or disabled.
Parameters:
__HANDLE__: CAN Handle
__INTERRUPT__: specifies the CAN
interrupt source to check. This parameter
can be one of the following values:
CAN_IT_TME: Transmit mailbox
empty interrupt enable
CAN_IT_FMP0: FIFO0 message
pending interrupt enable
CAN_IT_FMP1: FIFO1 message
pending interrupt enable
Return value:
The: new state of __IT__ (TRUE or
FALSE).

__HAL_CAN_TRANSMIT_STATUS

Description:
Check the transmission status of a CAN
Frame.
Parameters:
__HANDLE__: CAN Handle
__TRANSMITMAILBOX__: the number of
the mailbox that is used for transmission.
Return value:
The: new status of transmission (TRUE or
FALSE).

__HAL_CAN_FIFO_RELEASE

Description:
Release the specified receive FIFO.
Parameters:
__HANDLE__: CAN handle
__FIFONUMBER__: Receive FIFO
number, CAN_FIFO0 or CAN_FIFO1.

DocID025834 Rev 4

115/964

HAL CAN Generic Driver

UM1725
Return value:
None

__HAL_CAN_CANCEL_TRANSMIT

Description:
Cancel a transmit request.
Parameters:
__HANDLE__: CAN Handle
__TRANSMITMAILBOX__: the number of
the mailbox that is used for transmission.
Return value:
None

__HAL_CAN_DBG_FREEZE

Description:
Enable or disable the DBG Freeze for
CAN.
Parameters:
__HANDLE__: CAN Handle
__NEWSTATE__: new state of the CAN
peripheral. This parameter can be:
ENABLE (CAN reception/transmission is
frozen during debug. Reception FIFOs can
still be accessed/controlled normally) or
DISABLE (CAN is working during debug).
Return value:
None

CAN Filter FIFO
CAN_FILTER_FIFO0

Filter FIFO 0 assignment for filter x

CAN_FILTER_FIFO1

Filter FIFO 1 assignment for filter x

CAN Filter Mode
CAN_FILTERMODE_IDMASK

Identifier mask mode

CAN_FILTERMODE_IDLIST

Identifier list mode

CAN Filter Scale
CAN_FILTERSCALE_16BIT

Two 16-bit filters

CAN_FILTERSCALE_32BIT

One 32-bit filter

CAN Flags

116/964

CAN_FLAG_RQCP0

Request MailBox0 flag

CAN_FLAG_RQCP1

Request MailBox1 flag

CAN_FLAG_RQCP2

Request MailBox2 flag

CAN_FLAG_TXOK0

Transmission OK MailBox0 flag

CAN_FLAG_TXOK1

Transmission OK MailBox1 flag

CAN_FLAG_TXOK2

Transmission OK MailBox2 flag

DocID025834 Rev 4

UM1725

HAL CAN Generic Driver
CAN_FLAG_TME0

Transmit mailbox 0 empty flag

CAN_FLAG_TME1

Transmit mailbox 0 empty flag

CAN_FLAG_TME2

Transmit mailbox 0 empty flag

CAN_FLAG_FF0

FIFO 0 Full flag

CAN_FLAG_FOV0

FIFO 0 Overrun flag

CAN_FLAG_FF1

FIFO 1 Full flag

CAN_FLAG_FOV1

FIFO 1 Overrun flag

CAN_FLAG_INAK

Initialization acknowledge flag

CAN_FLAG_SLAK

Sleep acknowledge flag

CAN_FLAG_ERRI

Error flag

CAN_FLAG_WKU

Wake up flag

CAN_FLAG_SLAKI

Sleep acknowledge flag

CAN_FLAG_EWG

Error warning flag

CAN_FLAG_EPV

Error passive flag

CAN_FLAG_BOF

Bus-Off flag

CAN Identifier Type
CAN_ID_STD

Standard Id

CAN_ID_EXT

Extended Id

CAN InitStatus
CAN_INITSTATUS_FAILED

CAN initialization failed

CAN_INITSTATUS_SUCCESS

CAN initialization OK

CAN Interrupts
CAN_IT_TME

Transmit mailbox empty interrupt

CAN_IT_FMP0

FIFO 0 message pending interrupt

CAN_IT_FF0

FIFO 0 full interrupt

CAN_IT_FOV0

FIFO 0 overrun interrupt

CAN_IT_FMP1

FIFO 1 message pending interrupt

CAN_IT_FF1

FIFO 1 full interrupt

CAN_IT_FOV1

FIFO 1 overrun interrupt

CAN_IT_WKU

Wake-up interrupt

CAN_IT_SLK

Sleep acknowledge interrupt

CAN_IT_EWG

Error warning interrupt

CAN_IT_EPV

Error passive interrupt

CAN_IT_BOF

Bus-off interrupt

CAN_IT_LEC

Last error code interrupt

CAN_IT_ERR

Error Interrupt

DocID025834 Rev 4

117/964

HAL CAN Generic Driver
CAN Mailboxes Definition

UM1725

CAN_TXMAILBOX_0
CAN_TXMAILBOX_1
CAN_TXMAILBOX_2
CAN Operating Mode
CAN_MODE_NORMAL

Normal mode

CAN_MODE_LOOPBACK

Loopback mode

CAN_MODE_SILENT

Silent mode

CAN_MODE_SILENT_LOOPBACK

Loopback combined with silent mode

CAN Receive FIFO Number Constants
CAN_FIFO0

CAN FIFO 0 used to receive

CAN_FIFO1

CAN FIFO 1 used to receive

CAN Remote Transmission Request
CAN_RTR_DATA

Data frame

CAN_RTR_REMOTE

Remote frame

CAN Synchronisation Jump Width
CAN_SJW_1TQ

1 time quantum

CAN_SJW_2TQ

2 time quantum

CAN_SJW_3TQ

3 time quantum

CAN_SJW_4TQ

4 time quantum

CAN Time Quantum in bit segment 1

118/964

CAN_BS1_1TQ

1 time quantum

CAN_BS1_2TQ

2 time quantum

CAN_BS1_3TQ

3 time quantum

CAN_BS1_4TQ

4 time quantum

CAN_BS1_5TQ

5 time quantum

CAN_BS1_6TQ

6 time quantum

CAN_BS1_7TQ

7 time quantum

CAN_BS1_8TQ

8 time quantum

CAN_BS1_9TQ

9 time quantum

CAN_BS1_10TQ

10 time quantum

CAN_BS1_11TQ

11 time quantum

CAN_BS1_12TQ

12 time quantum

CAN_BS1_13TQ

13 time quantum

CAN_BS1_14TQ

14 time quantum

CAN_BS1_15TQ

15 time quantum

DocID025834 Rev 4

UM1725

HAL CAN Generic Driver
CAN_BS1_16TQ

16 time quantum

CAN Time Quantum in bit segment 2
CAN_BS2_1TQ

1 time quantum

CAN_BS2_2TQ

2 time quantum

CAN_BS2_3TQ

3 time quantum

CAN_BS2_4TQ

4 time quantum

CAN_BS2_5TQ

5 time quantum

CAN_BS2_6TQ

6 time quantum

CAN_BS2_7TQ

7 time quantum

CAN_BS2_8TQ

8 time quantum

DocID025834 Rev 4

119/964

HAL CEC Generic Driver

UM1725

7

HAL CEC Generic Driver

7.1

CEC Firmware driver registers structures

7.1.1

CEC_InitTypeDef
Data Fields
uint32_t SignalFreeTime
uint32_t Tolerance
uint32_t BRERxStop
uint32_t BREErrorBitGen
uint32_t LBPEErrorBitGen
uint32_t BroadcastMsgNoErrorBitGen
uint32_t SignalFreeTimeOption
uint32_t ListenMode
uint16_t OwnAddress
uint8_t * RxBuffer

Field Documentation
uint32_t CEC_InitTypeDef::SignalFreeTime
Set SFT field, specifies the Signal Free Time. It can be one of
CEC_Signal_Free_Time and belongs to the set {0,...,7} where 0x0 is the default
configuration else means 0.5 + (SignalFreeTime - 1) nominal data bit periods
uint32_t CEC_InitTypeDef::Tolerance
Set RXTOL bit, specifies the tolerance accepted on the received waveforms, it can be
a value of CEC_Tolerance : it is either CEC_STANDARD_TOLERANCE or
CEC_EXTENDED_TOLERANCE
uint32_t CEC_InitTypeDef::BRERxStop
Set BRESTP bit CEC_BRERxStop : specifies whether or not a Bit Rising Error stops
the reception. CEC_NO_RX_STOP_ON_BRE: reception is not stopped.
CEC_RX_STOP_ON_BRE: reception is stopped.
uint32_t CEC_InitTypeDef::BREErrorBitGen
Set BREGEN bit CEC_BREErrorBitGen : specifies whether or not an Error-Bit is
generated on the CEC line upon Bit Rising Error detection.
CEC_BRE_ERRORBIT_NO_GENERATION: no error-bit generation.
CEC_BRE_ERRORBIT_GENERATION: error-bit generation if BRESTP is set.
uint32_t CEC_InitTypeDef::LBPEErrorBitGen
Set LBPEGEN bit CEC_LBPEErrorBitGen : specifies whether or not an Error-Bit is
generated on the CEC line upon Long Bit Period Error detection.
CEC_LBPE_ERRORBIT_NO_GENERATION: no error-bit generation.
CEC_LBPE_ERRORBIT_GENERATION: error-bit generation.
uint32_t CEC_InitTypeDef::BroadcastMsgNoErrorBitGen
Set BRDNOGEN bit CEC_BroadCastMsgErrorBitGen : allows to avoid an Error-Bit
generation on the CEC line upon an error detected on a broadcast message.It
supersedes BREGEN and LBPEGEN bits for a broadcast message error handling. It
can take two values:1) CEC_BROADCASTERROR_ERRORBIT_GENERATION. a)
BRE detection: error-bit generation on the CEC line if
BRESTP=CEC_RX_STOP_ON_BRE and
120/964

DocID025834 Rev 4

UM1725

7.1.2

HAL CEC Generic Driver
BREGEN=CEC_BRE_ERRORBIT_NO_GENERATION. b) LBPE detection: error-bit
generation on the CEC line if
LBPGEN=CEC_LBPE_ERRORBIT_NO_GENERATION.2)
CEC_BROADCASTERROR_NO_ERRORBIT_GENERATION. no error-bit generation
in case neither a) nor b) are satisfied. Additionally, there is no error-bit generation in
case of Short Bit Period Error detection in a broadcast message while LSTN bit is set.
uint32_t CEC_InitTypeDef::SignalFreeTimeOption
Set SFTOP bit CEC_SFT_Option : specifies when SFT timer starts.
CEC_SFT_START_ON_TXSOM SFT: timer starts when TXSOM is set by software.
CEC_SFT_START_ON_TX_RX_END: SFT timer starts automatically at the end of
message transmission/reception.
uint32_t CEC_InitTypeDef::ListenMode
Set LSTN bit CEC_Listening_Mode : specifies device listening mode. It can take two
values:CEC_REDUCED_LISTENING_MODE: CEC peripheral receives only message
addressed to its own address (OAR). Messages addressed to different destination are
ignored. Broadcast messages are always received.CEC_FULL_LISTENING_MODE:
CEC peripheral receives messages addressed to its own address (OAR) with positive
acknowledge. Messages addressed to different destination are received, but without
interfering with the CEC bus: no acknowledge sent.
uint16_t CEC_InitTypeDef::OwnAddress
Own addresses configuration This parameter can be a value of
CEC_OWN_ADDRESS
uint8_t* CEC_InitTypeDef::RxBuffer
CEC Rx buffer pointeur

CEC_HandleTypeDef
Data Fields
CEC_TypeDef * Instance
CEC_InitTypeDef Init
uint8_t * pTxBuffPtr
uint16_t TxXferCount
uint16_t RxXferSize
HAL_LockTypeDef Lock
HAL_CEC_StateTypeDef gState
HAL_CEC_StateTypeDef RxState
uint32_t ErrorCode

Field Documentation
CEC_TypeDef* CEC_HandleTypeDef::Instance
CEC registers base address
CEC_InitTypeDef CEC_HandleTypeDef::Init
CEC communication parameters
uint8_t* CEC_HandleTypeDef::pTxBuffPtr
Pointer to CEC Tx transfer Buffer
uint16_t CEC_HandleTypeDef::TxXferCount
CEC Tx Transfer Counter
uint16_t CEC_HandleTypeDef::RxXferSize
CEC Rx Transfer size, 0: header received only

DocID025834 Rev 4

121/964

HAL CEC Generic Driver

UM1725

HAL_LockTypeDef CEC_HandleTypeDef::Lock
Locking object
HAL_CEC_StateTypeDef CEC_HandleTypeDef::gState
CEC state information related to global Handle management and also related to Tx
operations. This parameter can be a value of HAL_CEC_StateTypeDef
HAL_CEC_StateTypeDef CEC_HandleTypeDef::RxState
CEC state information related to Rx operations. This parameter can be a value of
HAL_CEC_StateTypeDef
uint32_t CEC_HandleTypeDef::ErrorCode
For errors handling purposes, copy of ISR register in case error is reported

7.2

CEC Firmware driver API description

7.2.1

How to use this driver
The CEC HAL driver can be used as follow:
1.
2.

3.

4.

Declare a CEC_HandleTypeDef handle structure.
Initialize the CEC low level resources by implementing the HAL_CEC_MspInit ()API:
a.
Enable the CEC interface clock.
b.
CEC pins configuration:
Enable the clock for the CEC GPIOs.
Configure these CEC pins as alternate function pull-up.
c.
NVIC configuration if you need to use interrupt process
(HAL_CEC_Transmit_IT() and HAL_CEC_Receive_IT() APIs):
Configure the CEC interrupt priority.
Enable the NVIC CEC IRQ handle.
The specific CEC interrupts (Transmission complete interrupt, RXNE
interrupt and Error Interrupts) will be managed using the macros
__HAL_CEC_ENABLE_IT() and __HAL_CEC_DISABLE_IT() inside the
transmit and receive process.
Program the Signal Free Time (SFT) and SFT option, Tolerance, reception stop in in
case of Bit Rising Error, Error-Bit generation conditions, device logical address and
Listen mode in the hcec Init structure.
Initialize the CEC registers by calling the HAL_CEC_Init() API.
This API (HAL_CEC_Init()) configures also the low level Hardware GPIO,
CLOCK, CORTEX...etc) by calling the customed HAL_CEC_MspInit() API.

7.2.2

How to use this driver
The CEC HAL driver can be used as follow:
1.
2.

122/964

Declare a CEC_HandleTypeDef handle structure.
Initialize the CEC low level resources by implementing the HAL_CEC_MspInit ()API:
a.
Enable the CEC interface clock.
b.
CEC pins configuration:
Enable the clock for the CEC GPIOs.
Configure these CEC pins as alternate function pull-up.
c.
NVIC configuration if you need to use interrupt process
(HAL_CEC_Transmit_IT() and HAL_CEC_Receive_IT() APIs):
Configure the CEC interrupt priority.
DocID025834 Rev 4

UM1725

HAL CEC Generic Driver

3.

4.

Enable the NVIC CEC IRQ handle.
The specific CEC interrupts (Transmission complete interrupt, RXNE
interrupt and Error Interrupts) will be managed using the macros
__HAL_CEC_ENABLE_IT() and __HAL_CEC_DISABLE_IT() inside the
transmit and receive process.
Program the Signal Free Time (SFT) and SFT option, Tolerance, reception stop in in
case of Bit Rising Error, Error-Bit generation conditions, device logical address and
Listen mode in the hcec Init structure.
Initialize the CEC registers by calling the HAL_CEC_Init() API.
This API (HAL_CEC_Init()) configures also the low level Hardware GPIO,
CLOCK, CORTEX...etc) by calling the customed HAL_CEC_MspInit() API.

7.2.3

Initialization and Configuration functions
This subsection provides a set of functions allowing to initialize the CEC
The following parameters need to be configured:
SignalFreeTime
Tolerance
BRERxStop (RX stopped or not upon Bit Rising Error)
BREErrorBitGen (Error-Bit generation in case of Bit Rising Error)
LBPEErrorBitGen (Error-Bit generation in case of Long Bit Period Error)
BroadcastMsgNoErrorBitGen (Error-bit generation in case of broadcast message
error)
SignalFreeTimeOption (SFT Timer start definition)
OwnAddress (CEC device address)
ListenMode
This section contains the following APIs:
HAL_CEC_Init()
HAL_CEC_DeInit()
HAL_CEC_SetDeviceAddress()
HAL_CEC_MspInit()
HAL_CEC_MspDeInit()

7.2.4

IO operation functions
This section contains the following APIs:
HAL_CEC_Transmit_IT()
HAL_CEC_GetLastReceivedFrameSize()
HAL_CEC_ChangeRxBuffer()
HAL_CEC_IRQHandler()
HAL_CEC_TxCpltCallback()
HAL_CEC_RxCpltCallback()
HAL_CEC_ErrorCallback()

DocID025834 Rev 4

123/964

HAL CEC Generic Driver

7.2.5

UM1725

Peripheral Control function
This subsection provides a set of functions allowing to control the CEC.
HAL_CEC_GetState() API can be helpful to check in run-time the state of the CEC
peripheral.
HAL_CEC_GetError() API can be helpful to check in run-time the error of the CEC
peripheral.
This section contains the following APIs:
HAL_CEC_GetState()
HAL_CEC_GetError()

7.2.6

Detailed description of functions
HAL_CEC_Init
Function Name

HAL_StatusTypeDef HAL_CEC_Init (CEC_HandleTypeDef *
hcec)

Function Description

Initializes the CEC mode according to the specified parameters in
the CEC_InitTypeDef and creates the associated handle .

Parameters

hcec: CEC handle

Return values

HAL: status

HAL_CEC_DeInit
Function Name

HAL_StatusTypeDef HAL_CEC_DeInit (CEC_HandleTypeDef *
hcec)

Function Description

DeInitializes the CEC peripheral.

Parameters

hcec: CEC handle

Return values

HAL: status

HAL_CEC_SetDeviceAddress
Function Name

HAL_StatusTypeDef HAL_CEC_SetDeviceAddress
(CEC_HandleTypeDef * hcec, uint16_t CEC_OwnAddress)

Function Description

Initializes the Own Address of the CEC device.

Parameters

hcec: CEC handle
CEC_OwnAddress: The CEC own address.

Return values

HAL: status

HAL_CEC_MspInit

124/964

Function Name

void HAL_CEC_MspInit (CEC_HandleTypeDef * hcec)

Function Description

CEC MSP Init.

Parameters

hcec: CEC handle

Return values

None
DocID025834 Rev 4

UM1725

HAL CEC Generic Driver

HAL_CEC_MspDeInit
Function Name

void HAL_CEC_MspDeInit (CEC_HandleTypeDef * hcec)

Function Description

CEC MSP DeInit.

Parameters

hcec: CEC handle

Return values

None

HAL_CEC_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_CEC_Transmit_IT
(CEC_HandleTypeDef * hcec, uint8_t InitiatorAddress, uint8_t
DestinationAddress, uint8_t * pData, uint32_t Size)

Function Description

Send data in interrupt mode.

Parameters

hcec: CEC handle
InitiatorAddress: Initiator logical address
DestinationAddress: destination logical address
pData: pointer to input byte data buffer
Size: amount of data to be sent in bytes (without counting the
header). 0 means only the header is sent (ping operation).
Maximum TX size is 15 bytes (1 opcode and up to 14
operands).

Return values

HAL: status

HAL_CEC_GetLastReceivedFrameSize
Function Name

uint32_t HAL_CEC_GetLastReceivedFrameSize
(CEC_HandleTypeDef * hcec)

Function Description

Get size of the received frame.

Parameters

hcec: CEC handle

Return values

Frame: size

HAL_CEC_ChangeRxBuffer
Function Name

void HAL_CEC_ChangeRxBuffer (CEC_HandleTypeDef * hcec,
uint8_t * Rxbuffer)

Function Description

Change Rx Buffer.

Parameters

hcec: CEC handle
Rxbuffer: Rx Buffer

Return values

Frame: size

Notes

This function can be called only inside the
HAL_CEC_RxCpltCallback()

HAL_CEC_IRQHandler
Function Name

void HAL_CEC_IRQHandler (CEC_HandleTypeDef * hcec)

Function Description

This function handles CEC interrupt requests.

DocID025834 Rev 4

125/964

HAL CEC Generic Driver
Parameters
Return values

UM1725
hcec: CEC handle
None

HAL_CEC_TxCpltCallback
Function Name

void HAL_CEC_TxCpltCallback (CEC_HandleTypeDef * hcec)

Function Description

Tx Transfer completed callback.

Parameters

hcec: CEC handle

Return values

None

HAL_CEC_RxCpltCallback
Function Name

void HAL_CEC_RxCpltCallback (CEC_HandleTypeDef * hcec,
uint32_t RxFrameSize)

Function Description

Rx Transfer completed callback.

Parameters

hcec: CEC handle
RxFrameSize: Size of frame

Return values

None

HAL_CEC_ErrorCallback
Function Name

void HAL_CEC_ErrorCallback (CEC_HandleTypeDef * hcec)

Function Description

CEC error callbacks.

Parameters

hcec: CEC handle

Return values

None

HAL_CEC_GetState
Function Name

HAL_CEC_StateTypeDef HAL_CEC_GetState
(CEC_HandleTypeDef * hcec)

Function Description

return the CEC state

Parameters

hcec: pointer to a CEC_HandleTypeDef structure that
contains the configuration information for the specified CEC
module.

Return values

HAL: state

HAL_CEC_GetError

126/964

Function Name

uint32_t HAL_CEC_GetError (CEC_HandleTypeDef * hcec)

Function Description

Return the CEC error code.

Parameters

hcec: : pointer to a CEC_HandleTypeDef structure that
contains the configuration information for the specified CEC.

Return values

CEC: Error Code

DocID025834 Rev 4

UM1725

HAL CEC Generic Driver

7.3

CEC Firmware driver defines

7.3.1

CEC
CEC all RX or TX errors flags
CEC_ISR_ALL_ERROR
CEC Error Bit Generation if Bit Rise Error reported
CEC_BRE_ERRORBIT_NO_GENERATION
CEC_BRE_ERRORBIT_GENERATION
CEC Reception Stop on Error
CEC_NO_RX_STOP_ON_BRE
CEC_RX_STOP_ON_BRE
CEC Error Bit Generation on Broadcast message
CEC_BROADCASTERROR_ERRORBIT_GENERATION
CEC_BROADCASTERROR_NO_ERRORBIT_GENERATION
CEC Error Code
HAL_CEC_ERROR_NONE

no error

HAL_CEC_ERROR_RXOVR

CEC Rx-Overrun

HAL_CEC_ERROR_BRE

CEC Rx Bit Rising Error

HAL_CEC_ERROR_SBPE

CEC Rx Short Bit period Error

HAL_CEC_ERROR_LBPE

CEC Rx Long Bit period Error

HAL_CEC_ERROR_RXACKE

CEC Rx Missing Acknowledge

HAL_CEC_ERROR_ARBLST

CEC Arbitration Lost

HAL_CEC_ERROR_TXUDR

CEC Tx-Buffer Underrun

HAL_CEC_ERROR_TXERR

CEC Tx-Error

HAL_CEC_ERROR_TXACKE

CEC Tx Missing Acknowledge

CEC Exported Macros
__HAL_CEC_RESET_HANDLE_STATE

Description:
Reset CEC handle gstate &
RxState.
Parameters:
__HANDLE__: CEC handle.
Return value:
None
Description:

__HAL_CEC_GET_FLAG

Checks whether or not the
specified CEC interrupt flag is
set.

DocID025834 Rev 4

127/964

HAL CEC Generic Driver

UM1725
Parameters:
__HANDLE__: specifies the
CEC Handle.
__FLAG__: specifies the flag to
check.
CEC_FLAG_TXACKE: Tx
Missing acknowledge Error
CEC_FLAG_TXERR: Tx
Error.
CEC_FLAG_TXUDR: TxBuffer Underrun.
CEC_FLAG_TXEND: End
of transmission (successful
transmission of the last
byte).
CEC_FLAG_TXBR: TxByte Request.
CEC_FLAG_ARBLST:
Arbitration Lost
CEC_FLAG_RXACKE:
Rx-Missing Acknowledge
CEC_FLAG_LBPE: Rx
Long period Error
CEC_FLAG_SBPE: Rx
Short period Error
CEC_FLAG_BRE: Rx Bit
Rising Error
CEC_FLAG_RXOVR: Rx
Overrun.
CEC_FLAG_RXEND: End
Of Reception.
CEC_FLAG_RXBR: RxByte Received.
Return value:
ITStatus
Description:

__HAL_CEC_CLEAR_FLAG

Clears the interrupt or status
flag when raised (write at 1)
Parameters:
__HANDLE__: specifies the
CEC Handle.
__FLAG__: specifies the
interrupt/status flag to clear.
This parameter can be one of
the following values:
CEC_FLAG_TXACKE: Tx
Missing acknowledge Error
CEC_FLAG_TXERR: Tx
Error.
CEC_FLAG_TXUDR: TxBuffer Underrun.
128/964

DocID025834 Rev 4

UM1725

HAL CEC Generic Driver
CEC_FLAG_TXEND: End
of transmission (successful
transmission of the last
byte).
CEC_FLAG_TXBR: TxByte Request.
CEC_FLAG_ARBLST:
Arbitration Lost
CEC_FLAG_RXACKE:
Rx-Missing Acknowledge
CEC_FLAG_LBPE: Rx
Long period Error
CEC_FLAG_SBPE: Rx
Short period Error
CEC_FLAG_BRE: Rx Bit
Rising Error
CEC_FLAG_RXOVR: Rx
Overrun.
CEC_FLAG_RXEND: End
Of Reception.
CEC_FLAG_RXBR: RxByte Received.
Return value:
none
Description:

__HAL_CEC_ENABLE_IT

Enables the specified CEC
interrupt.
Parameters:
__HANDLE__: specifies the
CEC Handle.
__INTERRUPT__: specifies the
CEC interrupt to enable. This
parameter can be one of the
following values:
CEC_IT_TXACKE: Tx
Missing acknowledge Error
IT Enable
CEC_IT_TXERR: Tx Error
IT Enable
CEC_IT_TXUDR: TxBuffer Underrun IT Enable
CEC_IT_TXEND: End of
transmission IT Enable
CEC_IT_TXBR: Tx-Byte
Request IT Enable
CEC_IT_ARBLST:
Arbitration Lost IT Enable
CEC_IT_RXACKE: RxMissing Acknowledge IT
Enable
CEC_IT_LBPE: Rx Long
DocID025834 Rev 4

129/964

HAL CEC Generic Driver

UM1725
period Error IT Enable
CEC_IT_SBPE: Rx Short
period Error IT Enable
CEC_IT_BRE: Rx Bit
Rising Error IT Enable
CEC_IT_RXOVR: Rx
Overrun IT Enable
CEC_IT_RXEND: End Of
Reception IT Enable
CEC_IT_RXBR: Rx-Byte
Received IT Enable
Return value:
none
Description:

__HAL_CEC_DISABLE_IT

Disables the specified CEC
interrupt.
Parameters:
__HANDLE__: specifies the
CEC Handle.
__INTERRUPT__: specifies the
CEC interrupt to disable. This
parameter can be one of the
following values:
CEC_IT_TXACKE: Tx
Missing acknowledge Error
IT Enable
CEC_IT_TXERR: Tx Error
IT Enable
CEC_IT_TXUDR: TxBuffer Underrun IT Enable
CEC_IT_TXEND: End of
transmission IT Enable
CEC_IT_TXBR: Tx-Byte
Request IT Enable
CEC_IT_ARBLST:
Arbitration Lost IT Enable
CEC_IT_RXACKE: RxMissing Acknowledge IT
Enable
CEC_IT_LBPE: Rx Long
period Error IT Enable
CEC_IT_SBPE: Rx Short
period Error IT Enable
CEC_IT_BRE: Rx Bit
Rising Error IT Enable
CEC_IT_RXOVR: Rx
Overrun IT Enable
CEC_IT_RXEND: End Of
Reception IT Enable
CEC_IT_RXBR: Rx-Byte
Received IT Enable
130/964

DocID025834 Rev 4

UM1725

HAL CEC Generic Driver
Return value:
none
__HAL_CEC_GET_IT_SOURCE

Description:
Checks whether or not the
specified CEC interrupt is
enabled.
Parameters:
__HANDLE__: specifies the
CEC Handle.
__INTERRUPT__: specifies the
CEC interrupt to check. This
parameter can be one of the
following values:
CEC_IT_TXACKE: Tx
Missing acknowledge Error
IT Enable
CEC_IT_TXERR: Tx Error
IT Enable
CEC_IT_TXUDR: TxBuffer Underrun IT Enable
CEC_IT_TXEND: End of
transmission IT Enable
CEC_IT_TXBR: Tx-Byte
Request IT Enable
CEC_IT_ARBLST:
Arbitration Lost IT Enable
CEC_IT_RXACKE: RxMissing Acknowledge IT
Enable
CEC_IT_LBPE: Rx Long
period Error IT Enable
CEC_IT_SBPE: Rx Short
period Error IT Enable
CEC_IT_BRE: Rx Bit
Rising Error IT Enable
CEC_IT_RXOVR: Rx
Overrun IT Enable
CEC_IT_RXEND: End Of
Reception IT Enable
CEC_IT_RXBR: Rx-Byte
Received IT Enable
Return value:
FlagStatus
Description:

__HAL_CEC_ENABLE

Enables the CEC device.
Parameters:
__HANDLE__: specifies the
CEC Handle.
DocID025834 Rev 4

131/964

HAL CEC Generic Driver

UM1725
Return value:
none
Description:

__HAL_CEC_DISABLE

Disables the CEC device.
Parameters:
__HANDLE__: specifies the
CEC Handle.
Return value:
none
__HAL_CEC_FIRST_BYTE_TX_SET

Description:
Set Transmission Start flag.
Parameters:
__HANDLE__: specifies the
CEC Handle.
Return value:
none

__HAL_CEC_LAST_BYTE_TX_SET

Description:
Set Transmission End flag.
Parameters:
__HANDLE__: specifies the
CEC Handle.
Return value:
none: If the CEC message
consists of only one byte,
TXEOM must be set before of
TXSOM.

__HAL_CEC_GET_TRANSMISSION_START_FLA
G

Description:
Get Transmission Start flag.
Parameters:
__HANDLE__: specifies the
CEC Handle.
Return value:
FlagStatus

__HAL_CEC_GET_TRANSMISSION_END_FLAG

Description:
Get Transmission End flag.
Parameters:
__HANDLE__: specifies the
CEC Handle.

132/964

DocID025834 Rev 4

UM1725

HAL CEC Generic Driver
Return value:
FlagStatus
Description:

__HAL_CEC_CLEAR_OAR

Clear OAR register.
Parameters:
__HANDLE__: specifies the
CEC Handle.
Return value:
none
Description:

__HAL_CEC_SET_OAR

Set OAR register (without
resetting previously set address
in case of multi-address mode)
To reset OAR,
Parameters:
__HANDLE__: specifies the
CEC Handle.
__ADDRESS__: Own Address
value (CEC logical address is
identified by bit position)
Return value:
none
CEC Flags definition
CEC_FLAG_TXACKE
CEC_FLAG_TXERR
CEC_FLAG_TXUDR
CEC_FLAG_TXEND
CEC_FLAG_TXBR
CEC_FLAG_ARBLST
CEC_FLAG_RXACKE
CEC_FLAG_LBPE
CEC_FLAG_SBPE
CEC_FLAG_BRE
CEC_FLAG_RXOVR
CEC_FLAG_RXEND
CEC_FLAG_RXBR
CEC all RX errors interrupts enabling flag
CEC_IER_RX_ALL_ERR
CEC all TX errors interrupts enabling flag
DocID025834 Rev 4

133/964

HAL CEC Generic Driver
CEC_IER_TX_ALL_ERR

UM1725

CEC Initiator logical address position in message header
CEC_INITIATOR_LSB_POS
CEC Interrupts definition
CEC_IT_TXACKE
CEC_IT_TXERR
CEC_IT_TXUDR
CEC_IT_TXEND
CEC_IT_TXBR
CEC_IT_ARBLST
CEC_IT_RXACKE
CEC_IT_LBPE
CEC_IT_SBPE
CEC_IT_BRE
CEC_IT_RXOVR
CEC_IT_RXEND
CEC_IT_RXBR
CEC Error Bit Generation if Long Bit Period Error reported
CEC_LBPE_ERRORBIT_NO_GENERATION
CEC_LBPE_ERRORBIT_GENERATION
CEC Listening mode option
CEC_REDUCED_LISTENING_MODE
CEC_FULL_LISTENING_MODE
CEC Device Own Address position in CEC CFGR register
CEC_CFGR_OAR_LSB_POS
CEC Own Address
CEC_OWN_ADDRESS_NONE
CEC_OWN_ADDRESS_0
CEC_OWN_ADDRESS_1
CEC_OWN_ADDRESS_2
CEC_OWN_ADDRESS_3
CEC_OWN_ADDRESS_4
CEC_OWN_ADDRESS_5
CEC_OWN_ADDRESS_6
CEC_OWN_ADDRESS_7
CEC_OWN_ADDRESS_8

134/964

DocID025834 Rev 4

UM1725

HAL CEC Generic Driver
CEC_OWN_ADDRESS_9
CEC_OWN_ADDRESS_10
CEC_OWN_ADDRESS_11
CEC_OWN_ADDRESS_12
CEC_OWN_ADDRESS_13
CEC_OWN_ADDRESS_14
CEC Signal Free Time start option
CEC_SFT_START_ON_TXSOM
CEC_SFT_START_ON_TX_RX_END
CEC Signal Free Time setting parameter
CEC_DEFAULT_SFT
CEC_0_5_BITPERIOD_SFT
CEC_1_5_BITPERIOD_SFT
CEC_2_5_BITPERIOD_SFT
CEC_3_5_BITPERIOD_SFT
CEC_4_5_BITPERIOD_SFT
CEC_5_5_BITPERIOD_SFT
CEC_6_5_BITPERIOD_SFT
CEC Receiver Tolerance
CEC_STANDARD_TOLERANCE
CEC_EXTENDED_TOLERANCE

DocID025834 Rev 4

135/964

HAL CORTEX Generic Driver

UM1725

8

HAL CORTEX Generic Driver

8.1

CORTEX Firmware driver registers structures

8.1.1

MPU_Region_InitTypeDef
Data Fields
uint8_t Enable
uint8_t Number
uint32_t BaseAddress
uint8_t Size
uint8_t SubRegionDisable
uint8_t TypeExtField
uint8_t AccessPermission
uint8_t DisableExec
uint8_t IsShareable
uint8_t IsCacheable
uint8_t IsBufferable

Field Documentation
uint8_t MPU_Region_InitTypeDef::Enable
Specifies the status of the region. This parameter can be a value of
CORTEX_MPU_Region_Enable
uint8_t MPU_Region_InitTypeDef::Number
Specifies the number of the region to protect. This parameter can be a value of
CORTEX_MPU_Region_Number
uint32_t MPU_Region_InitTypeDef::BaseAddress
Specifies the base address of the region to protect.
uint8_t MPU_Region_InitTypeDef::Size
Specifies the size of the region to protect. This parameter can be a value of
CORTEX_MPU_Region_Size
uint8_t MPU_Region_InitTypeDef::SubRegionDisable
Specifies the number of the subregion protection to disable. This parameter must be
a number between Min_Data = 0x00 and Max_Data = 0xFF
uint8_t MPU_Region_InitTypeDef::TypeExtField
Specifies the TEX field level. This parameter can be a value of
CORTEX_MPU_TEX_Levels
uint8_t MPU_Region_InitTypeDef::AccessPermission
Specifies the region access permission type. This parameter can be a value of
CORTEX_MPU_Region_Permission_Attributes
uint8_t MPU_Region_InitTypeDef::DisableExec
Specifies the instruction access status. This parameter can be a value of
CORTEX_MPU_Instruction_Access
uint8_t MPU_Region_InitTypeDef::IsShareable
Specifies the shareability status of the protected region. This parameter can be a
value of CORTEX_MPU_Access_Shareable

136/964

DocID025834 Rev 4

UM1725

HAL CORTEX Generic Driver
uint8_t MPU_Region_InitTypeDef::IsCacheable
Specifies the cacheable status of the region protected. This parameter can be a value
of CORTEX_MPU_Access_Cacheable
uint8_t MPU_Region_InitTypeDef::IsBufferable
Specifies the bufferable status of the protected region. This parameter can be a value
of CORTEX_MPU_Access_Bufferable

8.2

CORTEX Firmware driver API description

8.2.1

How to use this driver

How to configure Interrupts using CORTEX HAL driver
This section provides functions allowing to configure the NVIC interrupts (IRQ). The
Cortex-M4 exceptions are managed by CMSIS functions.
1.
2.
3.
4.

Configure the NVIC Priority Grouping using HAL_NVIC_SetPriorityGrouping()
function according to the following table.
Configure the priority of the selected IRQ Channels using HAL_NVIC_SetPriority().
Enable the selected IRQ Channels using HAL_NVIC_EnableIRQ().
please refer to programing manual for details in how to configure priority. When the
NVIC_PRIORITYGROUP_0 is selected, IRQ preemption is no more possible. The
pending IRQ priority will be managed only by the sub priority. IRQ priority order
(sorted by highest to lowest priority): Lowest preemption priority Lowest sub priority
Lowest hardware priority (IRQ number)

How to configure Systick using CORTEX HAL driver
Setup SysTick Timer for time base.
The HAL_SYSTICK_Config() function calls the SysTick_Config() function which is a
CMSIS function that:
Configures the SysTick Reload register with value passed as function parameter.
Configures the SysTick IRQ priority to the lowest value (0x0FU).
Resets the SysTick Counter register.
Configures the SysTick Counter clock source to be Core Clock Source (HCLK).
Enables the SysTick Interrupt.
Starts the SysTick Counter.
You can change the SysTick Clock source to be HCLK_Div8 by calling the macro
__HAL_CORTEX_SYSTICKCLK_CONFIG(SYSTICK_CLKSOURCE_HCLK_DIV8)
just after the HAL_SYSTICK_Config() function call. The
__HAL_CORTEX_SYSTICKCLK_CONFIG() macro is defined inside the
stm32f4xx_hal_cortex.h file.
You can change the SysTick IRQ priority by calling the
HAL_NVIC_SetPriority(SysTick_IRQn,...) function just after the
HAL_SYSTICK_Config() function call. The HAL_NVIC_SetPriority() call the
NVIC_SetPriority() function which is a CMSIS function.
To adjust the SysTick time base, use the following formula: Reload Value = SysTick
Counter Clock (Hz) x Desired Time base (s)
Reload Value is the parameter to be passed for HAL_SYSTICK_Config()
function
DocID025834 Rev 4

137/964

HAL CORTEX Generic Driver

UM1725

Reload Value should not exceed 0xFFFFFF

8.2.2

Initialization and de-initialization functions
This section provides the CORTEX HAL driver functions allowing to configure Interrupts
Systick functionalities
This section contains the following APIs:
HAL_NVIC_SetPriorityGrouping()
HAL_NVIC_SetPriority()
HAL_NVIC_EnableIRQ()
HAL_NVIC_DisableIRQ()
HAL_NVIC_SystemReset()
HAL_SYSTICK_Config()

8.2.3

Peripheral Control functions
This subsection provides a set of functions allowing to control the CORTEX (NVIC,
SYSTICK, MPU) functionalities.
This section contains the following APIs:
HAL_MPU_ConfigRegion()
HAL_NVIC_GetPriorityGrouping()
HAL_NVIC_GetPriority()
HAL_NVIC_SetPendingIRQ()
HAL_NVIC_GetPendingIRQ()
HAL_NVIC_ClearPendingIRQ()
HAL_NVIC_GetActive()
HAL_SYSTICK_CLKSourceConfig()
HAL_SYSTICK_IRQHandler()
HAL_SYSTICK_Callback()

8.2.4

Detailed description of functions
HAL_NVIC_SetPriorityGrouping

138/964

Function Name

void HAL_NVIC_SetPriorityGrouping (uint32_t PriorityGroup)

Function Description

Sets the priority grouping field (preemption priority and subpriority)
using the required unlock sequence.

Parameters

PriorityGroup: The priority grouping bits length. This
parameter can be one of the following values:
NVIC_PRIORITYGROUP_0: 0 bits for preemption
priority 4 bits for subpriority
NVIC_PRIORITYGROUP_1: 1 bits for preemption
priority 3 bits for subpriority
NVIC_PRIORITYGROUP_2: 2 bits for preemption
priority 2 bits for subpriority
NVIC_PRIORITYGROUP_3: 3 bits for preemption
priority 1 bits for subpriority
NVIC_PRIORITYGROUP_4: 4 bits for preemption
priority 0 bits for subpriority

Return values

None

DocID025834 Rev 4

UM1725

HAL CORTEX Generic Driver
Notes

When the NVIC_PriorityGroup_0 is selected, IRQ preemption
is no more possible. The pending IRQ priority will be
managed only by the subpriority.

HAL_NVIC_SetPriority
Function Name

void HAL_NVIC_SetPriority (IRQn_Type IRQn, uint32_t
PreemptPriority, uint32_t SubPriority)

Function Description

Sets the priority of an interrupt.

Parameters

IRQn: External interrupt number. This parameter can be an
enumerator of IRQn_Type enumeration (For the complete
STM32 Devices IRQ Channels list, please refer to the
appropriate CMSIS device file (stm32f4xxxx.h))
PreemptPriority: The preemption priority for the IRQn
channel. This parameter can be a value between 0 and 15 A
lower priority value indicates a higher priority
SubPriority: the subpriority level for the IRQ channel. This
parameter can be a value between 0 and 15 A lower priority
value indicates a higher priority.

Return values

None

HAL_NVIC_EnableIRQ
Function Name

void HAL_NVIC_EnableIRQ (IRQn_Type IRQn)

Function Description

Enables a device specific interrupt in the NVIC interrupt controller.

Parameters

IRQn: External interrupt number. This parameter can be an
enumerator of IRQn_Type enumeration (For the complete
STM32 Devices IRQ Channels list, please refer to the
appropriate CMSIS device file (stm32f4xxxx.h))

Return values

None

Notes

To configure interrupts priority correctly, the
NVIC_PriorityGroupConfig() function should be called before.

HAL_NVIC_DisableIRQ
Function Name

void HAL_NVIC_DisableIRQ (IRQn_Type IRQn)

Function Description

Disables a device specific interrupt in the NVIC interrupt controller.

Parameters

IRQn: External interrupt number. This parameter can be an
enumerator of IRQn_Type enumeration (For the complete
STM32 Devices IRQ Channels list, please refer to the
appropriate CMSIS device file (stm32f4xxxx.h))

Return values

None

DocID025834 Rev 4

139/964

HAL CORTEX Generic Driver

UM1725

HAL_NVIC_SystemReset
Function Name

void HAL_NVIC_SystemReset (void )

Function Description

Initiates a system reset request to reset the MCU.

Return values

None

HAL_SYSTICK_Config
Function Name

uint32_t HAL_SYSTICK_Config (uint32_t TicksNumb)

Function Description

Initializes the System Timer and its interrupt, and starts the System
Tick Timer.

Parameters

TicksNumb: Specifies the ticks Number of ticks between two
interrupts.

Return values

status: - 0 Function succeeded.
1 Function failed.

HAL_MPU_ConfigRegion
Function Name

void HAL_MPU_ConfigRegion (MPU_Region_InitTypeDef *
MPU_Init)

Function Description

Initializes and configures the Region and the memory to be
protected.

Parameters

MPU_Init: Pointer to a MPU_Region_InitTypeDef structure
that contains the initialization and configuration information.

Return values

None

HAL_NVIC_GetPriorityGrouping
Function Name

uint32_t HAL_NVIC_GetPriorityGrouping (void )

Function Description

Gets the priority grouping field from the NVIC Interrupt Controller.

Return values

Priority: grouping field (SCB->AIRCR [10:8] PRIGROUP
field)

HAL_NVIC_GetPriority
Function Name

void HAL_NVIC_GetPriority (IRQn_Type IRQn, uint32_t
PriorityGroup, uint32_t * pPreemptPriority, uint32_t *
pSubPriority)

Function Description

Gets the priority of an interrupt.

Parameters

140/964

IRQn: External interrupt number. This parameter can be an
enumerator of IRQn_Type enumeration (For the complete
STM32 Devices IRQ Channels list, please refer to the
appropriate CMSIS device file (stm32f4xxxx.h))
PriorityGroup: the priority grouping bits length. This
parameter can be one of the following values:
NVIC_PRIORITYGROUP_0: 0 bits for preemption
priority 4 bits for subpriority
NVIC_PRIORITYGROUP_1: 1 bits for preemption
DocID025834 Rev 4

UM1725

HAL CORTEX Generic Driver
priority 3 bits for subpriority
NVIC_PRIORITYGROUP_2: 2 bits for preemption
priority 2 bits for subpriority
NVIC_PRIORITYGROUP_3: 3 bits for preemption
priority 1 bits for subpriority
NVIC_PRIORITYGROUP_4: 4 bits for preemption
priority 0 bits for subpriority
pPreemptPriority: Pointer on the Preemptive priority value
(starting from 0).
pSubPriority: Pointer on the Subpriority value (starting from
0).
Return values

None

HAL_NVIC_GetPendingIRQ
Function Name

uint32_t HAL_NVIC_GetPendingIRQ (IRQn_Type IRQn)

Function Description

Gets Pending Interrupt (reads the pending register in the NVIC
and returns the pending bit for the specified interrupt).

Parameters

IRQn: External interrupt number. This parameter can be an
enumerator of IRQn_Type enumeration (For the complete
STM32 Devices IRQ Channels list, please refer to the
appropriate CMSIS device file (stm32f4xxxx.h))

Return values

status: - 0 Interrupt status is not pending.
1 Interrupt status is pending.

HAL_NVIC_SetPendingIRQ
Function Name

void HAL_NVIC_SetPendingIRQ (IRQn_Type IRQn)

Function Description

Sets Pending bit of an external interrupt.

Parameters

IRQn: External interrupt number This parameter can be an
enumerator of IRQn_Type enumeration (For the complete
STM32 Devices IRQ Channels list, please refer to the
appropriate CMSIS device file (stm32f4xxxx.h))

Return values

None

HAL_NVIC_ClearPendingIRQ
Function Name

void HAL_NVIC_ClearPendingIRQ (IRQn_Type IRQn)

Function Description

Clears the pending bit of an external interrupt.

Parameters

IRQn: External interrupt number. This parameter can be an
enumerator of IRQn_Type enumeration (For the complete
STM32 Devices IRQ Channels list, please refer to the
appropriate CMSIS device file (stm32f4xxxx.h))

Return values

None

DocID025834 Rev 4

141/964

HAL CORTEX Generic Driver

UM1725

HAL_NVIC_GetActive
Function Name

uint32_t HAL_NVIC_GetActive (IRQn_Type IRQn)

Function Description

Gets active interrupt ( reads the active register in NVIC and returns
the active bit).

Parameters

IRQn: External interrupt number This parameter can be an
enumerator of IRQn_Type enumeration (For the complete
STM32 Devices IRQ Channels list, please refer to the
appropriate CMSIS device file (stm32f4xxxx.h))

Return values

status: - 0 Interrupt status is not pending.
1 Interrupt status is pending.

HAL_SYSTICK_CLKSourceConfig
Function Name

void HAL_SYSTICK_CLKSourceConfig (uint32_t CLKSource)

Function Description

Configures the SysTick clock source.

Parameters

CLKSource: specifies the SysTick clock source. This
parameter can be one of the following values:
SYSTICK_CLKSOURCE_HCLK_DIV8: AHB clock
divided by 8 selected as SysTick clock source.
SYSTICK_CLKSOURCE_HCLK: AHB clock selected as
SysTick clock source.

Return values

None

HAL_SYSTICK_IRQHandler
Function Name

void HAL_SYSTICK_IRQHandler (void )

Function Description

This function handles SYSTICK interrupt request.

Return values

None

HAL_SYSTICK_Callback
Function Name

void HAL_SYSTICK_Callback (void )

Function Description

SYSTICK callback.

Return values

None

HAL_MPU_Disable
Function Name

__STATIC_INLINE void HAL_MPU_Disable (void )

Function Description

Disables the MPU.

Return values

142/964

None

DocID025834 Rev 4

UM1725

HAL CORTEX Generic Driver

HAL_MPU_Enable
Function Name

__STATIC_INLINE void HAL_MPU_Enable (uint32_t
MPU_Control)

Function Description

Enables the MPU.

Parameters

MPU_Control: Specifies the control mode of the MPU during
hard fault, NMI, FAULTMASK and privileged access to the
default memory This parameter can be one of the following
values:
MPU_HFNMI_PRIVDEF_NONE
MPU_HARDFAULT_NMI
MPU_PRIVILEGED_DEFAULT
MPU_HFNMI_PRIVDEF

Return values

None

8.3

CORTEX Firmware driver defines

8.3.1

CORTEX
CORTEX MPU Instruction Access Bufferable
MPU_ACCESS_BUFFERABLE
MPU_ACCESS_NOT_BUFFERABLE
CORTEX MPU Instruction Access Cacheable
MPU_ACCESS_CACHEABLE
MPU_ACCESS_NOT_CACHEABLE
CORTEX MPU Instruction Access Shareable
MPU_ACCESS_SHAREABLE
MPU_ACCESS_NOT_SHAREABLE
MPU HFNMI and PRIVILEGED Access control
MPU_HFNMI_PRIVDEF_NONE
MPU_HARDFAULT_NMI
MPU_PRIVILEGED_DEFAULT
MPU_HFNMI_PRIVDEF
CORTEX MPU Instruction Access
MPU_INSTRUCTION_ACCESS_ENABLE
MPU_INSTRUCTION_ACCESS_DISABLE
CORTEX MPU Region Enable
MPU_REGION_ENABLE
MPU_REGION_DISABLE

DocID025834 Rev 4

143/964

HAL CORTEX Generic Driver
CORTEX MPU Region Number
MPU_REGION_NUMBER0
MPU_REGION_NUMBER1
MPU_REGION_NUMBER2
MPU_REGION_NUMBER3
MPU_REGION_NUMBER4
MPU_REGION_NUMBER5
MPU_REGION_NUMBER6
MPU_REGION_NUMBER7
CORTEX MPU Region Permission Attributes
MPU_REGION_NO_ACCESS
MPU_REGION_PRIV_RW
MPU_REGION_PRIV_RW_URO
MPU_REGION_FULL_ACCESS
MPU_REGION_PRIV_RO
MPU_REGION_PRIV_RO_URO
CORTEX MPU Region Size
MPU_REGION_SIZE_32B
MPU_REGION_SIZE_64B
MPU_REGION_SIZE_128B
MPU_REGION_SIZE_256B
MPU_REGION_SIZE_512B
MPU_REGION_SIZE_1KB
MPU_REGION_SIZE_2KB
MPU_REGION_SIZE_4KB
MPU_REGION_SIZE_8KB
MPU_REGION_SIZE_16KB
MPU_REGION_SIZE_32KB
MPU_REGION_SIZE_64KB
MPU_REGION_SIZE_128KB
MPU_REGION_SIZE_256KB
MPU_REGION_SIZE_512KB
MPU_REGION_SIZE_1MB
MPU_REGION_SIZE_2MB
MPU_REGION_SIZE_4MB
MPU_REGION_SIZE_8MB

144/964

DocID025834 Rev 4

UM1725

UM1725

HAL CORTEX Generic Driver
MPU_REGION_SIZE_16MB
MPU_REGION_SIZE_32MB
MPU_REGION_SIZE_64MB
MPU_REGION_SIZE_128MB
MPU_REGION_SIZE_256MB
MPU_REGION_SIZE_512MB
MPU_REGION_SIZE_1GB
MPU_REGION_SIZE_2GB
MPU_REGION_SIZE_4GB
MPU TEX Levels
MPU_TEX_LEVEL0
MPU_TEX_LEVEL1
MPU_TEX_LEVEL2
CORTEX Preemption Priority Group
NVIC_PRIORITYGROUP_0

0 bits for pre-emption priority 4 bits for subpriority

NVIC_PRIORITYGROUP_1

1 bits for pre-emption priority 3 bits for subpriority

NVIC_PRIORITYGROUP_2

2 bits for pre-emption priority 2 bits for subpriority

NVIC_PRIORITYGROUP_3

3 bits for pre-emption priority 1 bits for subpriority

NVIC_PRIORITYGROUP_4

4 bits for pre-emption priority 0 bits for subpriority

CORTEX _SysTick clock source
SYSTICK_CLKSOURCE_HCLK_DIV8
SYSTICK_CLKSOURCE_HCLK

DocID025834 Rev 4

145/964

HAL CRC Generic Driver

UM1725

9

HAL CRC Generic Driver

9.1

CRC Firmware driver registers structures

9.1.1

CRC_HandleTypeDef
Data Fields
CRC_TypeDef * Instance
HAL_LockTypeDef Lock
__IO HAL_CRC_StateTypeDef State

Field Documentation
CRC_TypeDef* CRC_HandleTypeDef::Instance
Register base address
HAL_LockTypeDef CRC_HandleTypeDef::Lock
CRC locking object
__IO HAL_CRC_StateTypeDef CRC_HandleTypeDef::State
CRC communication state

9.2

CRC Firmware driver API description

9.2.1

How to use this driver
The CRC HAL driver can be used as follows:
1.
2.
3.

9.2.2

Enable CRC AHB clock using __HAL_RCC_CRC_CLK_ENABLE();
Use HAL_CRC_Accumulate() function to compute the CRC value of a 32-bit data
buffer using combination of the previous CRC value and the new one.
Use HAL_CRC_Calculate() function to compute the CRC Value of a new 32-bit data
buffer. This function resets the CRC computation unit before starting the computation
to avoid getting wrong CRC values.

Initialization and de-initialization functions
This section provides functions allowing to:
Initialize the CRC according to the specified parameters in the CRC_InitTypeDef and
create the associated handle
DeInitialize the CRC peripheral
Initialize the CRC MSP
DeInitialize CRC MSP
This section contains the following APIs:
HAL_CRC_Init()
HAL_CRC_DeInit()
HAL_CRC_MspInit()
HAL_CRC_MspDeInit()

146/964

DocID025834 Rev 4

UM1725

9.2.3

HAL CRC Generic Driver

Peripheral Control functions
This section provides functions allowing to:
Compute the 32-bit CRC value of 32-bit data buffer, using combination of the
previous CRC value and the new one.
Compute the 32-bit CRC value of 32-bit data buffer, independently of the previous
CRC value.
This section contains the following APIs:
HAL_CRC_Accumulate()
HAL_CRC_Calculate()

9.2.4

Peripheral State functions
This subsection permits to get in run-time the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_CRC_GetState()

9.2.5

Detailed description of functions
HAL_CRC_Init
Function Name

HAL_StatusTypeDef HAL_CRC_Init (CRC_HandleTypeDef *
hcrc)

Function Description

Initializes the CRC according to the specified parameters in the
CRC_InitTypeDef and creates the associated handle.

Parameters

hcrc: pointer to a CRC_HandleTypeDef structure that
contains the configuration information for CRC

Return values

HAL: status

HAL_CRC_DeInit
Function Name

HAL_StatusTypeDef HAL_CRC_DeInit (CRC_HandleTypeDef *
hcrc)

Function Description

DeInitializes the CRC peripheral.

Parameters

hcrc: pointer to a CRC_HandleTypeDef structure that
contains the configuration information for CRC

Return values

HAL: status

HAL_CRC_MspInit
Function Name

void HAL_CRC_MspInit (CRC_HandleTypeDef * hcrc)

Function Description

Initializes the CRC MSP.

Parameters

hcrc: pointer to a CRC_HandleTypeDef structure that
contains the configuration information for CRC

Return values

None

DocID025834 Rev 4

147/964

HAL CRC Generic Driver

UM1725

HAL_CRC_MspDeInit
Function Name

void HAL_CRC_MspDeInit (CRC_HandleTypeDef * hcrc)

Function Description

DeInitializes the CRC MSP.

Parameters

hcrc: pointer to a CRC_HandleTypeDef structure that
contains the configuration information for CRC

Return values

None

HAL_CRC_Accumulate
Function Name

uint32_t HAL_CRC_Accumulate (CRC_HandleTypeDef * hcrc,
uint32_t pBuffer, uint32_t BufferLength)

Function Description

Computes the 32-bit CRC of 32-bit data buffer using combination
of the previous CRC value and the new one.

Parameters

hcrc: pointer to a CRC_HandleTypeDef structure that
contains the configuration information for CRC
pBuffer: pointer to the buffer containing the data to be
computed
BufferLength: length of the buffer to be computed

Return values

32-bit: CRC

HAL_CRC_Calculate
Function Name

uint32_t HAL_CRC_Calculate (CRC_HandleTypeDef * hcrc,
uint32_t pBuffer, uint32_t BufferLength)

Function Description

Computes the 32-bit CRC of 32-bit data buffer independently of
the previous CRC value.

Parameters

hcrc: pointer to a CRC_HandleTypeDef structure that
contains the configuration information for CRC
pBuffer: Pointer to the buffer containing the data to be
computed
BufferLength: Length of the buffer to be computed

Return values

32-bit: CRC

HAL_CRC_GetState
Function Name

HAL_CRC_StateTypeDef HAL_CRC_GetState
(CRC_HandleTypeDef * hcrc)

Function Description

Returns the CRC state.

Parameters

hcrc: pointer to a CRC_HandleTypeDef structure that
contains the configuration information for CRC

Return values

HAL: state

9.3

CRC Firmware driver defines

9.3.1

CRC
CRC Exported Macros

148/964

DocID025834 Rev 4

UM1725

HAL CRC Generic Driver
__HAL_CRC_RESET_HANDLE_STATE

Description:
Resets CRC handle state.
Parameters:
__HANDLE__: CRC handle
Return value:
None

__HAL_CRC_DR_RESET

Description:
Resets CRC Data Register.
Parameters:
__HANDLE__: CRC handle
Return value:
None

__HAL_CRC_SET_IDR

Description:
Stores a 8-bit data in the Independent
Data(ID) register.
Parameters:
__HANDLE__: CRC handle
__VALUE__: 8-bit value to be stored in the
ID register
Return value:
None

__HAL_CRC_GET_IDR

Description:
Returns the 8-bit data stored in the
Independent Data(ID) register.
Parameters:
__HANDLE__: CRC handle
Return value:
8-bit: value of the ID register

DocID025834 Rev 4

149/964

HAL CRYP Generic Driver

UM1725

10

HAL CRYP Generic Driver

10.1

CRYP Firmware driver registers structures

10.1.1

CRYP_InitTypeDef
Data Fields
uint32_t DataType
uint32_t KeySize
uint8_t * pKey
uint8_t * pInitVect
uint8_t IVSize
uint8_t TagSize
uint8_t * Header
uint32_t HeaderSize
uint8_t * pScratch

Field Documentation
uint32_t CRYP_InitTypeDef::DataType
32-bit data, 16-bit data, 8-bit data or 1-bit string. This parameter can be a value of
CRYP_Data_Type
uint32_t CRYP_InitTypeDef::KeySize
Used only in AES mode only : 128, 192 or 256 bit key length. This parameter can be
a value of CRYP_Key_Size
uint8_t* CRYP_InitTypeDef::pKey
The key used for encryption/decryption
uint8_t* CRYP_InitTypeDef::pInitVect
The initialization vector used also as initialization counter in CTR mode
uint8_t CRYP_InitTypeDef::IVSize
The size of initialization vector. This parameter (called nonce size in CCM) is used
only in AES-128/192/256 encryption/decryption CCM mode
uint8_t CRYP_InitTypeDef::TagSize
The size of returned authentication TAG. This parameter is used only in AES128/192/256 encryption/decryption CCM mode
uint8_t* CRYP_InitTypeDef::Header
The header used in GCM and CCM modes
uint32_t CRYP_InitTypeDef::HeaderSize
The size of header buffer in bytes
uint8_t* CRYP_InitTypeDef::pScratch
Scratch buffer used to append the header. It's size must be equal to header size + 21
bytes. This parameter is used only in AES-128/192/256 encryption/decryption CCM
mode

150/964

DocID025834 Rev 4

UM1725

10.1.2

HAL CRYP Generic Driver

CRYP_HandleTypeDef
Data Fields
CRYP_TypeDef * Instance
CRYP_InitTypeDef Init
uint8_t * pCrypInBuffPtr
uint8_t * pCrypOutBuffPtr
__IO uint16_t CrypInCount
__IO uint16_t CrypOutCount
HAL_StatusTypeDef Status
HAL_PhaseTypeDef Phase
DMA_HandleTypeDef * hdmain
DMA_HandleTypeDef * hdmaout
HAL_LockTypeDef Lock
__IO HAL_CRYP_STATETypeDef State

Field Documentation
CRYP_TypeDef* CRYP_HandleTypeDef::Instance
CRYP registers base address
CRYP_InitTypeDef CRYP_HandleTypeDef::Init
CRYP required parameters
uint8_t* CRYP_HandleTypeDef::pCrypInBuffPtr
Pointer to CRYP processing (encryption, decryption,...) buffer
uint8_t* CRYP_HandleTypeDef::pCrypOutBuffPtr
Pointer to CRYP processing (encryption, decryption,...) buffer
__IO uint16_t CRYP_HandleTypeDef::CrypInCount
Counter of inputed data
__IO uint16_t CRYP_HandleTypeDef::CrypOutCount
Counter of output data
HAL_StatusTypeDef CRYP_HandleTypeDef::Status
CRYP peripheral status
HAL_PhaseTypeDef CRYP_HandleTypeDef::Phase
CRYP peripheral phase
DMA_HandleTypeDef* CRYP_HandleTypeDef::hdmain
CRYP In DMA handle parameters
DMA_HandleTypeDef* CRYP_HandleTypeDef::hdmaout
CRYP Out DMA handle parameters
HAL_LockTypeDef CRYP_HandleTypeDef::Lock
CRYP locking object
__IO HAL_CRYP_STATETypeDef CRYP_HandleTypeDef::State
CRYP peripheral state

DocID025834 Rev 4

151/964

HAL CRYP Generic Driver

UM1725

10.2

CRYP Firmware driver API description

10.2.1

How to use this driver
The CRYP HAL driver can be used as follows:
1.

2.

3.

4.

5.

10.2.2

Initialize the CRYP low level resources by implementing the HAL_CRYP_MspInit():
a.
Enable the CRYP interface clock using __HAL_RCC_CRYP_CLK_ENABLE()
b.
In case of using interrupts (e.g. HAL_CRYP_AESECB_Encrypt_IT())
Configure the CRYP interrupt priority using HAL_NVIC_SetPriority()
Enable the CRYP IRQ handler using HAL_NVIC_EnableIRQ()
In CRYP IRQ handler, call HAL_CRYP_IRQHandler()
c.
In case of using DMA to control data transfer (e.g.
HAL_CRYP_AESECB_Encrypt_DMA())
Enable the DMAx interface clock using __DMAx_CLK_ENABLE()
Configure and enable two DMA streams one for managing data transfer
from memory to peripheral (input stream) and another stream for managing
data transfer from peripheral to memory (output stream)
Associate the initialized DMA handle to the CRYP DMA handle using
__HAL_LINKDMA()
Configure the priority and enable the NVIC for the transfer complete
interrupt on the two DMA Streams. The output stream should have higher
priority than the input stream HAL_NVIC_SetPriority() and
HAL_NVIC_EnableIRQ()
Initialize the CRYP HAL using HAL_CRYP_Init(). This function configures mainly:
a.
The data type: 1-bit, 8-bit, 16-bit and 32-bit
b.
The key size: 128, 192 and 256. This parameter is relevant only for AES
c.
The encryption/decryption key. It's size depends on the algorithm used for
encryption/decryption
d.
The initialization vector (counter). It is not used ECB mode.
Three processing (encryption/decryption) functions are available:
a.
Polling mode: encryption and decryption APIs are blocking functions i.e. they
process the data and wait till the processing is finished, e.g.
HAL_CRYP_AESCBC_Encrypt()
b.
Interrupt mode: encryption and decryption APIs are not blocking functions i.e.
they process the data under interrupt, e.g. HAL_CRYP_AESCBC_Encrypt_IT()
c.
DMA mode: encryption and decryption APIs are not blocking functions i.e. the
data transfer is ensured by DMA, e.g. HAL_CRYP_AESCBC_Encrypt_DMA()
When the processing function is called at first time after HAL_CRYP_Init() the CRYP
peripheral is initialized and processes the buffer in input. At second call, the
processing function performs an append of the already processed buffer. When a new
data block is to be processed, call HAL_CRYP_Init() then the processing function.
Call HAL_CRYP_DeInit() to deinitialize the CRYP peripheral.

Initialization and de-initialization functions
This section provides functions allowing to:
Initialize the CRYP according to the specified parameters in the CRYP_InitTypeDef
and creates the associated handle
DeInitialize the CRYP peripheral
Initialize the CRYP MSP
DeInitialize CRYP MSP
This section contains the following APIs:

152/964

DocID025834 Rev 4

UM1725

HAL CRYP Generic Driver
HAL_CRYP_Init()
HAL_CRYP_DeInit()
HAL_CRYP_MspInit()
HAL_CRYP_MspDeInit()

10.2.3

AES processing functions
This section provides functions allowing to:
Encrypt plaintext using AES-128/192/256 using chaining modes
Decrypt cyphertext using AES-128/192/256 using chaining modes
Three processing functions are available:
Polling mode
Interrupt mode
DMA mode
This section contains the following APIs:
HAL_CRYP_AESECB_Encrypt()
HAL_CRYP_AESCBC_Encrypt()
HAL_CRYP_AESCTR_Encrypt()
HAL_CRYP_AESECB_Decrypt()
HAL_CRYP_AESCBC_Decrypt()
HAL_CRYP_AESCTR_Decrypt()
HAL_CRYP_AESECB_Encrypt_IT()
HAL_CRYP_AESCBC_Encrypt_IT()
HAL_CRYP_AESCTR_Encrypt_IT()
HAL_CRYP_AESECB_Decrypt_IT()
HAL_CRYP_AESCBC_Decrypt_IT()
HAL_CRYP_AESCTR_Decrypt_IT()
HAL_CRYP_AESECB_Encrypt_DMA()
HAL_CRYP_AESCBC_Encrypt_DMA()
HAL_CRYP_AESCTR_Encrypt_DMA()
HAL_CRYP_AESECB_Decrypt_DMA()
HAL_CRYP_AESCBC_Decrypt_DMA()
HAL_CRYP_AESCTR_Decrypt_DMA()

10.2.4

DES processing functions
This section provides functions allowing to:
Encrypt plaintext using DES using ECB or CBC chaining modes
Decrypt cyphertext using ECB or CBC chaining modes
Three processing functions are available:
Polling mode
Interrupt mode
DMA mode
This section contains the following APIs:
HAL_CRYP_DESECB_Encrypt()
HAL_CRYP_DESECB_Decrypt()
HAL_CRYP_DESCBC_Encrypt()
HAL_CRYP_DESCBC_Decrypt()
HAL_CRYP_DESECB_Encrypt_IT()
DocID025834 Rev 4

153/964

HAL CRYP Generic Driver

UM1725

HAL_CRYP_DESCBC_Encrypt_IT()
HAL_CRYP_DESECB_Decrypt_IT()
HAL_CRYP_DESCBC_Decrypt_IT()
HAL_CRYP_DESECB_Encrypt_DMA()
HAL_CRYP_DESCBC_Encrypt_DMA()
HAL_CRYP_DESECB_Decrypt_DMA()
HAL_CRYP_DESCBC_Decrypt_DMA()

10.2.5

TDES processing functions
This section provides functions allowing to:
Encrypt plaintext using TDES based on ECB or CBC chaining modes
Decrypt cyphertext using TDES based on ECB or CBC chaining modes
Three processing functions are available:
Polling mode
Interrupt mode
DMA mode
This section contains the following APIs:
HAL_CRYP_TDESECB_Encrypt()
HAL_CRYP_TDESECB_Decrypt()
HAL_CRYP_TDESCBC_Encrypt()
HAL_CRYP_TDESCBC_Decrypt()
HAL_CRYP_TDESECB_Encrypt_IT()
HAL_CRYP_TDESCBC_Encrypt_IT()
HAL_CRYP_TDESECB_Decrypt_IT()
HAL_CRYP_TDESCBC_Decrypt_IT()
HAL_CRYP_TDESECB_Encrypt_DMA()
HAL_CRYP_TDESCBC_Encrypt_DMA()
HAL_CRYP_TDESECB_Decrypt_DMA()
HAL_CRYP_TDESCBC_Decrypt_DMA()

10.2.6

DMA callback functions
This section provides DMA callback functions:
DMA Input data transfer complete
DMA Output data transfer complete
DMA error
This section contains the following APIs:
HAL_CRYP_InCpltCallback()
HAL_CRYP_OutCpltCallback()
HAL_CRYP_ErrorCallback()

10.2.7

CRYP IRQ handler management
This section provides CRYP IRQ handler function.
This section contains the following APIs:
HAL_CRYP_IRQHandler()

154/964

DocID025834 Rev 4

UM1725

10.2.8

HAL CRYP Generic Driver

Peripheral State functions
This subsection permits to get in run-time the status of the peripheral.
This section contains the following APIs:
HAL_CRYP_GetState()

10.2.9

Detailed description of functions
HAL_CRYP_Init
Function Name

HAL_StatusTypeDef HAL_CRYP_Init (CRYP_HandleTypeDef *
hcryp)

Function Description

Initializes the CRYP according to the specified parameters in the
CRYP_InitTypeDef and creates the associated handle.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module

Return values

HAL: status

HAL_CRYP_DeInit
Function Name

HAL_StatusTypeDef HAL_CRYP_DeInit
(CRYP_HandleTypeDef * hcryp)

Function Description

DeInitializes the CRYP peripheral.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module

Return values

HAL: status

HAL_CRYP_MspInit
Function Name

void HAL_CRYP_MspInit (CRYP_HandleTypeDef * hcryp)

Function Description

Initializes the CRYP MSP.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module

Return values

None

HAL_CRYP_MspDeInit
Function Name

void HAL_CRYP_MspDeInit (CRYP_HandleTypeDef * hcryp)

Function Description

DeInitializes CRYP MSP.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module

Return values

None

DocID025834 Rev 4

155/964

HAL CRYP Generic Driver

UM1725

HAL_CRYP_AESECB_Encrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_AESECB_Encrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in AES ECB encryption mode then
encrypt pPlainData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16.
pCypherData: Pointer to the cyphertext buffer
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CRYP_AESECB_Decrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_AESECB_Decrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in AES ECB decryption mode then
decrypted pCypherData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 16.
pPlainData: Pointer to the plaintext buffer
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CRYP_AESCBC_Encrypt

156/964

Function Name

HAL_StatusTypeDef HAL_CRYP_AESCBC_Encrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in AES CBC encryption mode then
encrypt pPlainData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16.
pCypherData: Pointer to the cyphertext buffer
Timeout: Specify Timeout value

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL CRYP Generic Driver

HAL_CRYP_AESCBC_Decrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_AESCBC_Decrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in AES ECB decryption mode then
decrypted pCypherData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 16.
pPlainData: Pointer to the plaintext buffer
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CRYP_AESCTR_Encrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_AESCTR_Encrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in AES CTR encryption mode then
encrypt pPlainData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16.
pCypherData: Pointer to the cyphertext buffer
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CRYP_AESCTR_Decrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_AESCTR_Decrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in AES CTR decryption mode then
decrypted pCypherData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 16.
pPlainData: Pointer to the plaintext buffer
Timeout: Specify Timeout value

Return values

HAL: status

DocID025834 Rev 4

157/964

HAL CRYP Generic Driver

UM1725

HAL_CRYP_AESECB_Encrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYP_AESECB_Encrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in AES ECB encryption mode using
Interrupt.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
bytes
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_AESCBC_Encrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYP_AESCBC_Encrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in AES CBC encryption mode
using Interrupt.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
bytes
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_AESCTR_Encrypt_IT

158/964

Function Name

HAL_StatusTypeDef HAL_CRYP_AESCTR_Encrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in AES CTR encryption mode using
Interrupt.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
bytes
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL CRYP Generic Driver

HAL_CRYP_AESECB_Decrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYP_AESECB_Decrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in AES ECB decryption mode using
Interrupt.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 16.
pPlainData: Pointer to the plaintext buffer

Return values

HAL: status

HAL_CRYP_AESCTR_Decrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYP_AESCTR_Decrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in AES CTR decryption mode using
Interrupt.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pPlainData: Pointer to the plaintext buffer

Return values

HAL: status

HAL_CRYP_AESCBC_Decrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYP_AESCBC_Decrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in AES CBC decryption mode
using IT.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pPlainData: Pointer to the plaintext buffer

Return values

HAL: status

HAL_CRYP_AESECB_Encrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_AESECB_Encrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in AES ECB encryption mode using
DMA.
DocID025834 Rev 4

159/964

HAL CRYP Generic Driver
Parameters

Return values

UM1725
hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
bytes
pCypherData: Pointer to the cyphertext buffer
HAL: status

HAL_CRYP_AESECB_Decrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_AESECB_Decrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in AES ECB decryption mode using
DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
bytes
pPlainData: Pointer to the plaintext buffer

Return values

HAL: status

HAL_CRYP_AESCBC_Encrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_AESCBC_Encrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in AES CBC encryption mode
using DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16.
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_AESCBC_Decrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_AESCBC_Decrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in AES CBC encryption mode
using DMA.

Parameters

160/964

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
bytes
DocID025834 Rev 4

UM1725

HAL CRYP Generic Driver
pPlainData: Pointer to the plaintext buffer
Return values

HAL: status

HAL_CRYP_AESCTR_Encrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_AESCTR_Encrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in AES CTR encryption mode using
DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16.
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_AESCTR_Decrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_AESCTR_Decrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in AES CTR decryption mode using
DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pPlainData: Pointer to the plaintext buffer

Return values

HAL: status

HAL_CRYP_DESECB_Encrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_DESECB_Encrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in DES ECB encryption mode.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer
Timeout: Specify Timeout value

Return values

HAL: status

DocID025834 Rev 4

161/964

HAL CRYP Generic Driver

UM1725

HAL_CRYP_DESCBC_Encrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_DESCBC_Encrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in DES CBC encryption mode.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CRYP_DESECB_Decrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_DESECB_Decrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in DES ECB decryption mode.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pPlainData: Pointer to the plaintext buffer
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CRYP_DESCBC_Decrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_DESCBC_Decrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in DES ECB decryption mode.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pPlainData: Pointer to the plaintext buffer
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CRYP_DESECB_Encrypt_IT

162/964

Function Name

HAL_StatusTypeDef HAL_CRYP_DESECB_Encrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in DES ECB encryption mode
using IT.
DocID025834 Rev 4

UM1725

HAL CRYP Generic Driver
Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_DESECB_Decrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYP_DESECB_Decrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in DES ECB decryption mode
using IT.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_DESCBC_Encrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYP_DESCBC_Encrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in DES CBC encryption mode
using interrupt.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_DESCBC_Decrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYP_DESCBC_Decrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in DES ECB decryption mode
using interrupt.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status
DocID025834 Rev 4

163/964

HAL CRYP Generic Driver

UM1725

HAL_CRYP_DESECB_Encrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_DESECB_Encrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in DES ECB encryption mode
using DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_DESECB_Decrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_DESECB_Decrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in DES ECB decryption mode
using DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_DESCBC_Encrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_DESCBC_Encrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in DES CBC encryption mode
using DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_DESCBC_Decrypt_DMA

164/964

Function Name

HAL_StatusTypeDef HAL_CRYP_DESCBC_Decrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in DES ECB decryption mode
using DMA.
DocID025834 Rev 4

UM1725

HAL CRYP Generic Driver
Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_TDESECB_Encrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_TDESECB_Encrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in TDES ECB encryption mode
then encrypt pPlainData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CRYP_TDESCBC_Encrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_TDESCBC_Encrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in TDES CBC encryption mode
then encrypt pPlainData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CRYP_TDESECB_Decrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_TDESECB_Decrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in TDES ECB decryption mode
then decrypted pCypherData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer
DocID025834 Rev 4

165/964

HAL CRYP Generic Driver

UM1725
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CRYP_TDESCBC_Decrypt
Function Name

HAL_StatusTypeDef HAL_CRYP_TDESCBC_Decrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in TDES CBC decryption mode
then decrypted pCypherData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pPlainData: Pointer to the plaintext buffer
Timeout: Specify Timeout value

Return values

HAL: status

HAL_CRYP_TDESECB_Encrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYP_TDESECB_Encrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in TDES ECB encryption mode
using interrupt.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_TDESECB_Decrypt_IT

166/964

Function Name

HAL_StatusTypeDef HAL_CRYP_TDESECB_Decrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in TDES ECB decryption mode.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL CRYP Generic Driver

HAL_CRYP_TDESCBC_Encrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYP_TDESCBC_Encrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in TDES CBC encryption mode.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_TDESCBC_Decrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYP_TDESCBC_Decrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in TDES CBC decryption mode.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pPlainData: Pointer to the plaintext buffer

Return values

HAL: status

HAL_CRYP_TDESECB_Encrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_TDESECB_Encrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in TDES ECB encryption mode
using DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_TDESECB_Decrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_TDESECB_Decrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in TDES ECB decryption mode
using DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
DocID025834 Rev 4

167/964

HAL CRYP Generic Driver

UM1725
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_TDESCBC_Encrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_TDESCBC_Encrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in TDES CBC encryption mode
using DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYP_TDESCBC_Decrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYP_TDESCBC_Decrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in TDES CBC decryption mode
using DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 8
pPlainData: Pointer to the plaintext buffer

Return values

HAL: status

HAL_CRYP_InCpltCallback
Function Name

void HAL_CRYP_InCpltCallback (CRYP_HandleTypeDef *
hcryp)

Function Description

Input FIFO transfer completed callbacks.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module

Return values

None

HAL_CRYP_OutCpltCallback

168/964

Function Name

void HAL_CRYP_OutCpltCallback (CRYP_HandleTypeDef *
hcryp)

Function Description

Output FIFO transfer completed callbacks.

DocID025834 Rev 4

UM1725

HAL CRYP Generic Driver
Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module

Return values

None

HAL_CRYP_ErrorCallback
Function Name

void HAL_CRYP_ErrorCallback (CRYP_HandleTypeDef *
hcryp)

Function Description

CRYP error callbacks.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module

Return values

None

HAL_CRYP_IRQHandler
Function Name

void HAL_CRYP_IRQHandler (CRYP_HandleTypeDef * hcryp)

Function Description

This function handles CRYP interrupt request.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module

Return values

None

HAL_CRYP_GetState
Function Name

HAL_CRYP_STATETypeDef HAL_CRYP_GetState
(CRYP_HandleTypeDef * hcryp)

Function Description

Returns the CRYP state.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module

Return values

HAL: state

10.3

CRYP Firmware driver defines

10.3.1

CRYP
CRYP Data Type
CRYP_DATATYPE_32B
CRYP_DATATYPE_16B
CRYP_DATATYPE_8B
CRYP_DATATYPE_1B
CRYP CRYP_AlgoModeDirection
CRYP_CR_ALGOMODE_DIRECTION
CRYP_CR_ALGOMODE_TDES_ECB_ENCRYPT
CRYP_CR_ALGOMODE_TDES_ECB_DECRYPT

DocID025834 Rev 4

169/964

HAL CRYP Generic Driver
CRYP_CR_ALGOMODE_TDES_CBC_ENCRYPT

UM1725

CRYP_CR_ALGOMODE_TDES_CBC_DECRYPT
CRYP_CR_ALGOMODE_DES_ECB_ENCRYPT
CRYP_CR_ALGOMODE_DES_ECB_DECRYPT
CRYP_CR_ALGOMODE_DES_CBC_ENCRYPT
CRYP_CR_ALGOMODE_DES_CBC_DECRYPT
CRYP_CR_ALGOMODE_AES_ECB_ENCRYPT
CRYP_CR_ALGOMODE_AES_ECB_DECRYPT
CRYP_CR_ALGOMODE_AES_CBC_ENCRYPT
CRYP_CR_ALGOMODE_AES_CBC_DECRYPT
CRYP_CR_ALGOMODE_AES_CTR_ENCRYPT
CRYP_CR_ALGOMODE_AES_CTR_DECRYPT
CRYP CRYP_Interrupt
CRYP_IT_INI

Input FIFO Interrupt

CRYP_IT_OUTI

Output FIFO Interrupt

CRYP CRYP_Flags
CRYP_FLAG_BUSY

The CRYP core is currently processing a block of data or a key
preparation (for AES decryption).

CRYP_FLAG_IFEM

Input FIFO is empty

CRYP_FLAG_IFNF

Input FIFO is not Full

CRYP_FLAG_OFNE

Output FIFO is not empty

CRYP_FLAG_OFFU

Output FIFO is Full

CRYP_FLAG_OUTRIS

Output FIFO service raw interrupt status

CRYP_FLAG_INRIS

Input FIFO service raw interrupt status

CRYP Exported Macros
__HAL_CRYP_RESET_HANDLE_STATE

Description:
Reset CRYP handle state.
Parameters:
__HANDLE__: specifies the CRYP
handle.
Return value:
None

__HAL_CRYP_ENABLE

Description:
Enable/Disable the CRYP peripheral.
Parameters:
__HANDLE__: specifies the CRYP
handle.

170/964

DocID025834 Rev 4

UM1725

HAL CRYP Generic Driver
Return value:
None
__HAL_CRYP_DISABLE
__HAL_CRYP_FIFO_FLUSH

Description:
Flush the data FIFO.
Parameters:
__HANDLE__: specifies the CRYP
handle.
Return value:
None

__HAL_CRYP_SET_MODE

Description:
Set the algorithm mode: AES-ECB, AESCBC, AES-CTR, DES-ECB, DES-CBC.
Parameters:
__HANDLE__: specifies the CRYP
handle.
MODE: The algorithm mode.
Return value:
None

__HAL_CRYP_GET_FLAG

Description:
Check whether the specified CRYP flag is
set or not.
Parameters:
__HANDLE__: specifies the CRYP
handle.
__FLAG__: specifies the flag to check.
This parameter can be one of the
following values:
CRYP_FLAG_BUSY: The CRYP
core is currently processing a block
of data or a key preparation (for AES
decryption).
CRYP_FLAG_IFEM: Input FIFO is
empty
CRYP_FLAG_IFNF: Input FIFO is
not full
CRYP_FLAG_INRIS: Input FIFO
service raw interrupt is pending
CRYP_FLAG_OFNE: Output FIFO
is not empty
CRYP_FLAG_OFFU: Output FIFO is
full
CRYP_FLAG_OUTRIS: Input FIFO
service raw interrupt is pending

DocID025834 Rev 4

171/964

HAL CRYP Generic Driver

UM1725
Return value:
The: new state of __FLAG__ (TRUE or
FALSE).

__HAL_CRYP_GET_IT

Description:
Check whether the specified CRYP
interrupt is set or not.
Parameters:
__HANDLE__: specifies the CRYP
handle.
__INTERRUPT__: specifies the interrupt
to check. This parameter can be one of
the following values:
CRYP_IT_INRIS: Input FIFO service
raw interrupt is pending
CRYP_IT_OUTRIS: Output FIFO
service raw interrupt is pending
Return value:
The: new state of __INTERRUPT__
(TRUE or FALSE).

__HAL_CRYP_ENABLE_IT

Description:
Enable the CRYP interrupt.
Parameters:
__HANDLE__: specifies the CRYP
handle.
__INTERRUPT__: CRYP Interrupt.
Return value:
None

__HAL_CRYP_DISABLE_IT

Description:
Disable the CRYP interrupt.
Parameters:
__HANDLE__: specifies the CRYP
handle.
__INTERRUPT__: CRYP interrupt.
Return value:
None

CRYP Key Size
CRYP_KEYSIZE_128B
CRYP_KEYSIZE_192B
CRYP_KEYSIZE_256B

172/964

DocID025834 Rev 4

UM1725

HAL CRYP Extension Driver

11

HAL CRYP Extension Driver

11.1

CRYPEx Firmware driver API description

11.1.1

How to use this driver
The CRYP Extension HAL driver can be used as follows:
1.

2.

3.

4.

5.

Initialize the CRYP low level resources by implementing the HAL_CRYP_MspInit():
a.
Enable the CRYP interface clock using __HAL_RCC_CRYP_CLK_ENABLE()
b.
In case of using interrupts (e.g. HAL_CRYPEx_AESGCM_Encrypt_IT())
Configure the CRYP interrupt priority using HAL_NVIC_SetPriority()
Enable the CRYP IRQ handler using HAL_NVIC_EnableIRQ()
In CRYP IRQ handler, call HAL_CRYP_IRQHandler()
c.
In case of using DMA to control data transfer (e.g.
HAL_AES_ECB_Encrypt_DMA())
Enable the DMAx interface clock using __DMAx_CLK_ENABLE()
Configure and enable two DMA streams one for managing data transfer
from memory to peripheral (input stream) and another stream for managing
data transfer from peripheral to memory (output stream)
Associate the initialized DMA handle to the CRYP DMA handle using
__HAL_LINKDMA()
Configure the priority and enable the NVIC for the transfer complete
interrupt on the two DMA Streams. The output stream should have higher
priority than the input stream HAL_NVIC_SetPriority() and
HAL_NVIC_EnableIRQ()
Initialize the CRYP HAL using HAL_CRYP_Init(). This function configures mainly:
a.
The data type: 1-bit, 8-bit, 16-bit and 32-bit
b.
The key size: 128, 192 and 256. This parameter is relevant only for AES
c.
The encryption/decryption key. Its size depends on the algorithm used for
encryption/decryption
d.
The initialization vector (counter). It is not used ECB mode.
Three processing (encryption/decryption) functions are available:
a.
Polling mode: encryption and decryption APIs are blocking functions i.e. they
process the data and wait till the processing is finished e.g.
HAL_CRYPEx_AESGCM_Encrypt()
b.
Interrupt mode: encryption and decryption APIs are not blocking functions i.e.
they process the data under interrupt e.g. HAL_CRYPEx_AESGCM_Encrypt_IT()
c.
DMA mode: encryption and decryption APIs are not blocking functions i.e. the
data transfer is ensured by DMA e.g. HAL_CRYPEx_AESGCM_Encrypt_DMA()
When the processing function is called at first time after HAL_CRYP_Init() the CRYP
peripheral is initialized and processes the buffer in input. At second call, the
processing function performs an append of the already processed buffer. When a new
data block is to be processed, call HAL_CRYP_Init() then the processing function.
In AES-GCM and AES-CCM modes are an authenticated encryption algorithms which
provide authentication messages. HAL_AES_GCM_Finish() and
HAL_AES_CCM_Finish() are used to provide those authentication messages. Call
those functions after the processing ones (polling, interrupt or DMA). e.g. in AES-CCM
mode call HAL_CRYPEx_AESCCM_Encrypt() to encrypt the plain data then call
HAL_CRYPEx_AESCCM_Finish() to get the authentication message For CCM
Encrypt/Decrypt API's, only DataType = 8-bit is supported by this version. The
HAL_CRYPEx_AESGCM_xxxx() implementation is limited to 32bits inputs data length
(Plain/Cyphertext, Header) compared with GCM standards specifications (800-38D).
DocID025834 Rev 4

173/964

HAL CRYP Extension Driver
6. Call HAL_CRYP_DeInit() to deinitialize the CRYP peripheral.

11.1.2

UM1725

Extended AES processing functions
This section provides functions allowing to:
Encrypt plaintext using AES-128/192/256 using GCM and CCM chaining modes
Decrypt cyphertext using AES-128/192/256 using GCM and CCM chaining modes
Finish the processing. This function is available only for GCM and CCM
Three processing methods are available:
Polling mode
Interrupt mode
DMA mode
This section contains the following APIs:
HAL_CRYPEx_AESCCM_Encrypt()
HAL_CRYPEx_AESGCM_Encrypt()
HAL_CRYPEx_AESGCM_Decrypt()
HAL_CRYPEx_AESGCM_Finish()
HAL_CRYPEx_AESCCM_Finish()
HAL_CRYPEx_AESCCM_Decrypt()
HAL_CRYPEx_AESGCM_Encrypt_IT()
HAL_CRYPEx_AESCCM_Encrypt_IT()
HAL_CRYPEx_AESGCM_Decrypt_IT()
HAL_CRYPEx_AESCCM_Decrypt_IT()
HAL_CRYPEx_AESGCM_Encrypt_DMA()
HAL_CRYPEx_AESCCM_Encrypt_DMA()
HAL_CRYPEx_AESGCM_Decrypt_DMA()
HAL_CRYPEx_AESCCM_Decrypt_DMA()

11.1.3

CRYPEx IRQ handler management
This section provides CRYPEx IRQ handler function.
This section contains the following APIs:
HAL_CRYPEx_GCMCCM_IRQHandler()

11.1.4

Detailed description of functions
HAL_CRYPEx_AESGCM_Encrypt
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESGCM_Encrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in AES GCM encryption mode then
encrypt pPlainData.

Parameters

174/964

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pCypherData: Pointer to the cyphertext buffer
Timeout: Timeout duration

DocID025834 Rev 4

UM1725

HAL CRYP Extension Driver
Return values

HAL: status

HAL_CRYPEx_AESGCM_Decrypt
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESGCM_Decrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in AES GCM decryption mode then
decrypted pCypherData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the cyphertext buffer, must be a multiple of
16
pPlainData: Pointer to the plaintext buffer
Timeout: Timeout duration

Return values

HAL: status

HAL_CRYPEx_AESGCM_Finish
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESGCM_Finish
(CRYP_HandleTypeDef * hcryp, uint32_t Size, uint8_t *
AuthTag, uint32_t Timeout)

Function Description

Computes the authentication TAG.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
Size: Total length of the plain/cyphertext buffer
AuthTag: Pointer to the authentication buffer
Timeout: Timeout duration

Return values

HAL: status

HAL_CRYPEx_AESCCM_Encrypt
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESCCM_Encrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in AES CCM encryption mode then
encrypt pPlainData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pCypherData: Pointer to the cyphertext buffer
Timeout: Timeout duration

Return values

HAL: status

DocID025834 Rev 4

175/964

HAL CRYP Extension Driver

UM1725

HAL_CRYPEx_AESCCM_Decrypt
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESCCM_Decrypt
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData, uint32_t Timeout)

Function Description

Initializes the CRYP peripheral in AES CCM decryption mode then
decrypted pCypherData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pCypherData: Pointer to the cyphertext buffer
Timeout: Timeout duration

Return values

HAL: status

HAL_CRYPEx_AESCCM_Finish
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESCCM_Finish
(CRYP_HandleTypeDef * hcryp, uint8_t * AuthTag, uint32_t
Timeout)

Function Description

Computes the authentication TAG for AES CCM mode.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
AuthTag: Pointer to the authentication buffer
Timeout: Timeout duration

Return values

HAL: status

Notes

This API is called after
HAL_AES_CCM_Encrypt()/HAL_AES_CCM_Decrypt()

HAL_CRYPEx_AESGCM_Encrypt_IT

176/964

Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESGCM_Encrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in AES GCM encryption mode
using IT.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL CRYP Extension Driver

HAL_CRYPEx_AESGCM_Decrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESGCM_Decrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in AES GCM decryption mode
using IT.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the cyphertext buffer, must be a multiple of
16
pPlainData: Pointer to the plaintext buffer

Return values

HAL: status

HAL_CRYPEx_AESCCM_Encrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESCCM_Encrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in AES CCM encryption mode
using interrupt.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYPEx_AESCCM_Decrypt_IT
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESCCM_Decrypt_IT
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in AES CCM decryption mode
using interrupt then decrypted pCypherData.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pPlainData: Pointer to the plaintext buffer

Return values

HAL: status

DocID025834 Rev 4

177/964

HAL CRYP Extension Driver

UM1725

HAL_CRYPEx_AESGCM_Encrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESGCM_Encrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in AES GCM encryption mode
using DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYPEx_AESGCM_Decrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESGCM_Decrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in AES GCM decryption mode
using DMA.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer.
Size: Length of the cyphertext buffer, must be a multiple of
16
pPlainData: Pointer to the plaintext buffer

Return values

HAL: status

HAL_CRYPEx_AESCCM_Encrypt_DMA
Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESCCM_Encrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t
Size, uint8_t * pCypherData)

Function Description

Initializes the CRYP peripheral in AES CCM encryption mode
using interrupt.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pPlainData: Pointer to the plaintext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pCypherData: Pointer to the cyphertext buffer

Return values

HAL: status

HAL_CRYPEx_AESCCM_Decrypt_DMA

178/964

Function Name

HAL_StatusTypeDef HAL_CRYPEx_AESCCM_Decrypt_DMA
(CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData,
uint16_t Size, uint8_t * pPlainData)

Function Description

Initializes the CRYP peripheral in AES CCM decryption mode
DocID025834 Rev 4

UM1725

HAL CRYP Extension Driver
using DMA then decrypted pCypherData.
Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that
contains the configuration information for CRYP module
pCypherData: Pointer to the cyphertext buffer
Size: Length of the plaintext buffer, must be a multiple of 16
pPlainData: Pointer to the plaintext buffer

Return values

HAL: status

HAL_CRYPEx_GCMCCM_IRQHandler
Function Name

void HAL_CRYPEx_GCMCCM_IRQHandler
(CRYP_HandleTypeDef * hcryp)

Function Description

This function handles CRYPEx interrupt request.

Parameters

hcryp: pointer to a CRYPEx_HandleTypeDef structure that
contains the configuration information for CRYP module

Return values

None

11.2

CRYPEx Firmware driver defines

11.2.1

CRYPEx
CRYP AlgoModeDirection
CRYP_CR_ALGOMODE_AES_GCM_ENCRYPT
CRYP_CR_ALGOMODE_AES_GCM_DECRYPT
CRYP_CR_ALGOMODE_AES_CCM_ENCRYPT
CRYP_CR_ALGOMODE_AES_CCM_DECRYPT
CRYP PhaseConfig
CRYP_PHASE_INIT
CRYP_PHASE_HEADER
CRYP_PHASE_PAYLOAD
CRYP_PHASE_FINAL
CRYP Exported Macros
__HAL_CRYP_SET_PHASE

Description:
Set the phase: Init, header, payload, final.
Parameters:
__HANDLE__: specifies the CRYP handle.
__PHASE__: The phase.
Return value:
None

DocID025834 Rev 4

179/964

HAL DAC Generic Driver

UM1725

12

HAL DAC Generic Driver

12.1

DAC Firmware driver registers structures

12.1.1

DAC_HandleTypeDef
Data Fields
DAC_TypeDef * Instance
__IO HAL_DAC_StateTypeDef State
HAL_LockTypeDef Lock
DMA_HandleTypeDef * DMA_Handle1
DMA_HandleTypeDef * DMA_Handle2
__IO uint32_t ErrorCode

Field Documentation
DAC_TypeDef* DAC_HandleTypeDef::Instance
Register base address
__IO HAL_DAC_StateTypeDef DAC_HandleTypeDef::State
DAC communication state
HAL_LockTypeDef DAC_HandleTypeDef::Lock
DAC locking object
DMA_HandleTypeDef* DAC_HandleTypeDef::DMA_Handle1
Pointer DMA handler for channel 1
DMA_HandleTypeDef* DAC_HandleTypeDef::DMA_Handle2
Pointer DMA handler for channel 2
__IO uint32_t DAC_HandleTypeDef::ErrorCode
DAC Error code

12.1.2

DAC_ChannelConfTypeDef
Data Fields
uint32_t DAC_Trigger
uint32_t DAC_OutputBuffer

Field Documentation
uint32_t DAC_ChannelConfTypeDef::DAC_Trigger
Specifies the external trigger for the selected DAC channel. This parameter can be a
value of DAC_trigger_selection
uint32_t DAC_ChannelConfTypeDef::DAC_OutputBuffer
Specifies whether the DAC channel output buffer is enabled or disabled. This
parameter can be a value of DAC_output_buffer

180/964

DocID025834 Rev 4

UM1725

HAL DAC Generic Driver

12.2

DAC Firmware driver API description

12.2.1

DAC Peripheral features

DAC Channels
The device integrates two 12-bit Digital Analog Converters that can be used independently
or simultaneously (dual mode):
1.
2.

DAC channel1 with DAC_OUT1 (PA4) as output
DAC channel2 with DAC_OUT2 (PA5) as output

DAC Triggers
Digital to Analog conversion can be non-triggered using DAC_TRIGGER_NONE and
DAC_OUT1/DAC_OUT2 is available once writing to DHRx register.
Digital to Analog conversion can be triggered by:
1.
2.
3.

External event: EXTI Line 9 (any GPIOx_Pin9) using DAC_TRIGGER_EXT_IT9. The
used pin (GPIOx_Pin9) must be configured in input mode.
Timers TRGO: TIM2, TIM4, TIM5, TIM6, TIM7 and TIM8
(DAC_TRIGGER_T2_TRGO, DAC_TRIGGER_T4_TRGO...)
Software using DAC_TRIGGER_SOFTWARE

DAC Buffer mode feature
Each DAC channel integrates an output buffer that can be used to reduce the output
impedance, and to drive external loads directly without having to add an external
operational amplifier. To enable, the output buffer use sConfig.DAC_OutputBuffer =
DAC_OUTPUTBUFFER_ENABLE;
Refer to the device datasheet for more details about output impedance value with
and without output buffer.

DAC wave generation feature
Both DAC channels can be used to generate
1.
2.

Noise wave
Triangle wave

DAC data format
The DAC data format can be:
1.
2.
3.

8-bit right alignment using DAC_ALIGN_8B_R
12-bit left alignment using DAC_ALIGN_12B_L
12-bit right alignment using DAC_ALIGN_12B_R

DocID025834 Rev 4

181/964

HAL DAC Generic Driver

UM1725

DAC data value to voltage correspondence
The analog output voltage on each DAC channel pin is determined by the following
equation: DAC_OUTx = VREF+ * DOR / 4095 with DOR is the Data Output Register VEF+
is the input voltage reference (refer to the device datasheet) e.g. To set DAC_OUT1 to
0.7V, use Assuming that VREF+ = 3.3V, DAC_OUT1 = (3.3 * 868) / 4095 = 0.7V

DMA requests
A DMA1 request can be generated when an external trigger (but not a software trigger)
occurs if DMA1 requests are enabled using HAL_DAC_Start_DMA()
DMA1 requests are mapped as following:
1.
2.

12.2.2

DAC channel1 : mapped on DMA1 Stream5 channel7 which must be already
configured
DAC channel2 : mapped on DMA1 Stream6 channel7 which must be already
configured For Dual mode and specific signal (Triangle and noise) generation please
refer to Extension Features Driver description

How to use this driver
DAC APB clock must be enabled to get write access to DAC registers using
HAL_DAC_Init()
Configure DAC_OUTx (DAC_OUT1: PA4, DAC_OUT2: PA5) in analog mode.
Configure the DAC channel using HAL_DAC_ConfigChannel() function.
Enable the DAC channel using HAL_DAC_Start() or HAL_DAC_Start_DMA functions

Polling mode IO operation
Start the DAC peripheral using HAL_DAC_Start()
To read the DAC last data output value, use the HAL_DAC_GetValue() function.
Stop the DAC peripheral using HAL_DAC_Stop()

DMA mode IO operation
Start the DAC peripheral using HAL_DAC_Start_DMA(), at this stage the user specify
the length of data to be transferred at each end of conversion
At The end of data transfer HAL_DAC_ConvCpltCallbackCh1()or
HAL_DAC_ConvCpltCallbackCh2() function is executed and user can add his own
code by customization of function pointer HAL_DAC_ConvCpltCallbackCh1 or
HAL_DAC_ConvCpltCallbackCh2
In case of transfer Error, HAL_DAC_ErrorCallbackCh1() function is executed and
user can add his own code by customization of function pointer
HAL_DAC_ErrorCallbackCh1
Stop the DAC peripheral using HAL_DAC_Stop_DMA()

DAC HAL driver macros list
Below the list of most used macros in DAC HAL driver.
__HAL_DAC_ENABLE : Enable the DAC peripheral
__HAL_DAC_DISABLE : Disable the DAC peripheral
__HAL_DAC_CLEAR_FLAG: Clear the DAC's pending flags
182/964

DocID025834 Rev 4

UM1725

HAL DAC Generic Driver
__HAL_DAC_GET_FLAG: Get the selected DAC's flag status
You can refer to the DAC HAL driver header file for more useful macros

12.2.3

Initialization and de-initialization functions
This section provides functions allowing to:
Initialize and configure the DAC.
De-initialize the DAC.
This section contains the following APIs:
HAL_DAC_Init()
HAL_DAC_DeInit()
HAL_DAC_MspInit()
HAL_DAC_MspDeInit()

12.2.4

IO operation functions
This section provides functions allowing to:
Start conversion.
Stop conversion.
Start conversion and enable DMA transfer.
Stop conversion and disable DMA transfer.
Get result of conversion.
This section contains the following APIs:
HAL_DAC_Start()
HAL_DAC_Stop()
HAL_DAC_Start_DMA()
HAL_DAC_Stop_DMA()
HAL_DAC_GetValue()
HAL_DAC_IRQHandler()
HAL_DAC_ConvCpltCallbackCh1()
HAL_DAC_ConvHalfCpltCallbackCh1()
HAL_DAC_ErrorCallbackCh1()
HAL_DAC_DMAUnderrunCallbackCh1()

12.2.5

Peripheral Control functions
This section provides functions allowing to:
Configure channels.
Set the specified data holding register value for DAC channel.
This section contains the following APIs:
HAL_DAC_ConfigChannel()
HAL_DAC_SetValue()

DocID025834 Rev 4

183/964

HAL DAC Generic Driver

12.2.6

UM1725

Peripheral State and Errors functions
This subsection provides functions allowing to
Check the DAC state.
Check the DAC Errors.
This section contains the following APIs:
HAL_DAC_GetState()
HAL_DAC_GetError()
HAL_DAC_IRQHandler()
HAL_DAC_ConvCpltCallbackCh1()
HAL_DAC_ConvHalfCpltCallbackCh1()
HAL_DAC_ErrorCallbackCh1()
HAL_DAC_DMAUnderrunCallbackCh1()

12.2.7

Detailed description of functions
HAL_DAC_Init
Function Name

HAL_StatusTypeDef HAL_DAC_Init (DAC_HandleTypeDef *
hdac)

Function Description

Initializes the DAC peripheral according to the specified
parameters in the DAC_InitStruct.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

HAL: status

HAL_DAC_DeInit
Function Name

HAL_StatusTypeDef HAL_DAC_DeInit (DAC_HandleTypeDef *
hdac)

Function Description

Deinitializes the DAC peripheral registers to their default reset
values.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

HAL: status

HAL_DAC_MspInit

184/964

Function Name

void HAL_DAC_MspInit (DAC_HandleTypeDef * hdac)

Function Description

Initializes the DAC MSP.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

None

DocID025834 Rev 4

UM1725

HAL DAC Generic Driver

HAL_DAC_MspDeInit
Function Name

void HAL_DAC_MspDeInit (DAC_HandleTypeDef * hdac)

Function Description

DeInitializes the DAC MSP.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

None

HAL_DAC_Start
Function Name

HAL_StatusTypeDef HAL_DAC_Start (DAC_HandleTypeDef *
hdac, uint32_t Channel)

Function Description

Enables DAC and starts conversion of channel.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.
Channel: The selected DAC channel. This parameter can be
one of the following values:
DAC_CHANNEL_1: DAC Channel1 selected
DAC_CHANNEL_2: DAC Channel2 selected

Return values

HAL: status

HAL_DAC_Stop
Function Name

HAL_StatusTypeDef HAL_DAC_Stop (DAC_HandleTypeDef *
hdac, uint32_t Channel)

Function Description

Disables DAC and stop conversion of channel.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.
Channel: The selected DAC channel. This parameter can be
one of the following values:
DAC_CHANNEL_1: DAC Channel1 selected
DAC_CHANNEL_2: DAC Channel2 selected

Return values

HAL: status

HAL_DAC_Start_DMA
Function Name

HAL_StatusTypeDef HAL_DAC_Start_DMA
(DAC_HandleTypeDef * hdac, uint32_t Channel, uint32_t *
pData, uint32_t Length, uint32_t Alignment)

Function Description

Enables DAC and starts conversion of channel.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.
Channel: The selected DAC channel. This parameter can be
one of the following values:
DAC_CHANNEL_1: DAC Channel1 selected
DAC_CHANNEL_2: DAC Channel2 selected
pData: The destination peripheral Buffer address.
Length: The length of data to be transferred from memory to
DAC peripheral
DocID025834 Rev 4

185/964

HAL DAC Generic Driver

UM1725
Alignment: Specifies the data alignment for DAC channel.
This parameter can be one of the following values:
DAC_ALIGN_8B_R: 8bit right data alignment selected
DAC_ALIGN_12B_L: 12bit left data alignment selected
DAC_ALIGN_12B_R: 12bit right data alignment selected

Return values

HAL: status

HAL_DAC_Stop_DMA
Function Name

HAL_StatusTypeDef HAL_DAC_Stop_DMA
(DAC_HandleTypeDef * hdac, uint32_t Channel)

Function Description

Disables DAC and stop conversion of channel.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.
Channel: The selected DAC channel. This parameter can be
one of the following values:
DAC_CHANNEL_1: DAC Channel1 selected
DAC_CHANNEL_2: DAC Channel2 selected

Return values

HAL: status

HAL_DAC_GetValue
Function Name

uint32_t HAL_DAC_GetValue (DAC_HandleTypeDef * hdac,
uint32_t Channel)

Function Description

Returns the last data output value of the selected DAC channel.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.
Channel: The selected DAC channel. This parameter can be
one of the following values:
DAC_CHANNEL_1: DAC Channel1 selected
DAC_CHANNEL_2: DAC Channel2 selected

Return values

The: selected DAC channel data output value.

HAL_DAC_ConfigChannel

186/964

Function Name

HAL_StatusTypeDef HAL_DAC_ConfigChannel
(DAC_HandleTypeDef * hdac, DAC_ChannelConfTypeDef *
sConfig, uint32_t Channel)

Function Description

Configures the selected DAC channel.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.
sConfig: DAC configuration structure.
Channel: The selected DAC channel. This parameter can be
one of the following values:
DAC_CHANNEL_1: DAC Channel1 selected
DAC_CHANNEL_2: DAC Channel2 selected

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL DAC Generic Driver

HAL_DAC_SetValue
Function Name

HAL_StatusTypeDef HAL_DAC_SetValue
(DAC_HandleTypeDef * hdac, uint32_t Channel, uint32_t
Alignment, uint32_t Data)

Function Description

Set the specified data holding register value for DAC channel.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.
Channel: The selected DAC channel. This parameter can be
one of the following values:
DAC_CHANNEL_1: DAC Channel1 selected
DAC_CHANNEL_2: DAC Channel2 selected
Alignment: Specifies the data alignment. This parameter
can be one of the following values:
DAC_ALIGN_8B_R: 8bit right data alignment selected
DAC_ALIGN_12B_L: 12bit left data alignment selected
DAC_ALIGN_12B_R: 12bit right data alignment selected
Data: Data to be loaded in the selected data holding register.

Return values

HAL: status

HAL_DAC_GetState
Function Name

HAL_DAC_StateTypeDef HAL_DAC_GetState
(DAC_HandleTypeDef * hdac)

Function Description

return the DAC state

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

HAL: state

HAL_DAC_IRQHandler
Function Name

void HAL_DAC_IRQHandler (DAC_HandleTypeDef * hdac)

Function Description

Handles DAC interrupt request.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

None

HAL_DAC_GetError
Function Name

uint32_t HAL_DAC_GetError (DAC_HandleTypeDef * hdac)

Function Description

Return the DAC error code.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

DAC: Error Code

DocID025834 Rev 4

187/964

HAL DAC Generic Driver

UM1725

HAL_DAC_ConvCpltCallbackCh1
Function Name

void HAL_DAC_ConvCpltCallbackCh1 (DAC_HandleTypeDef *
hdac)

Function Description

Conversion complete callback in non blocking mode for Channel1.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

None

HAL_DAC_ConvHalfCpltCallbackCh1
Function Name

void HAL_DAC_ConvHalfCpltCallbackCh1
(DAC_HandleTypeDef * hdac)

Function Description

Conversion half DMA transfer callback in non blocking mode for
Channel1.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

None

HAL_DAC_ErrorCallbackCh1
Function Name

void HAL_DAC_ErrorCallbackCh1 (DAC_HandleTypeDef *
hdac)

Function Description

Error DAC callback for Channel1.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

None

HAL_DAC_DMAUnderrunCallbackCh1
Function Name

void HAL_DAC_DMAUnderrunCallbackCh1
(DAC_HandleTypeDef * hdac)

Function Description

DMA underrun DAC callback for channel1.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

None

12.3

DAC Firmware driver defines

12.3.1

DAC
DAC Channel Selection
DAC_CHANNEL_1
DAC_CHANNEL_2

188/964

DocID025834 Rev 4

UM1725

HAL DAC Generic Driver
DAC Data Alignment
DAC_ALIGN_12B_R
DAC_ALIGN_12B_L
DAC_ALIGN_8B_R
DAC Error Code
HAL_DAC_ERROR_NONE

No error

HAL_DAC_ERROR_DMAUNDERRUNCH1

DAC channel1 DAM underrun error

HAL_DAC_ERROR_DMAUNDERRUNCH2

DAC channel2 DAM underrun error

HAL_DAC_ERROR_DMA

DMA error

DAC Exported Macros
__HAL_DAC_RESET_HANDLE_STATE

Description:
Reset DAC handle state.
Parameters:
__HANDLE__: specifies the DAC handle.
Return value:
None

__HAL_DAC_ENABLE

Description:
Enable the DAC channel.
Parameters:
__HANDLE__: specifies the DAC handle.
__DAC_Channel__: specifies the DAC
channel
Return value:
None

__HAL_DAC_DISABLE

Description:
Disable the DAC channel.
Parameters:
__HANDLE__: specifies the DAC handle
__DAC_Channel__: specifies the DAC
channel.
Return value:
None

__HAL_DAC_ENABLE_IT

Description:
Enable the DAC interrupt.
Parameters:
__HANDLE__: specifies the DAC handle
__INTERRUPT__: specifies the DAC
DocID025834 Rev 4

189/964

HAL DAC Generic Driver

UM1725
interrupt.
Return value:
None
Description:

__HAL_DAC_DISABLE_IT

Disable the DAC interrupt.
Parameters:
__HANDLE__: specifies the DAC handle
__INTERRUPT__: specifies the DAC
interrupt.
Return value:
None
__HAL_DAC_GET_IT_SOURCE

Description:
Checks if the specified DAC interrupt
source is enabled or disabled.
Parameters:
__HANDLE__: DAC handle
__INTERRUPT__: DAC interrupt source to
check This parameter can be any
combination of the following values:
DAC_IT_DMAUDR1: DAC channel 1
DMA underrun interrupt
DAC_IT_DMAUDR2: DAC channel 2
DMA underrun interrupt
Return value:
State: of interruption (SET or RESET)

__HAL_DAC_GET_FLAG

Description:
Get the selected DAC's flag status.
Parameters:
__HANDLE__: specifies the DAC handle.
__FLAG__: specifies the flag to clear. This
parameter can be any combination of the
following values:
DAC_FLAG_DMAUDR1: DMA
underrun 1 flag
DAC_FLAG_DMAUDR2: DMA
underrun 2 flag
Return value:
None

__HAL_DAC_CLEAR_FLAG

Description:
Clear the DAC's flag.
Parameters:
__HANDLE__: specifies the DAC handle.

190/964

DocID025834 Rev 4

UM1725

HAL DAC Generic Driver
__FLAG__: specifies the flag to clear. This
parameter can be any combination of the
following values:
DAC_FLAG_DMAUDR1: DMA
underrun 1 flag
DAC_FLAG_DMAUDR2: DMA
underrun 2 flag
Return value:
None
DAC Flags Definition
DAC_FLAG_DMAUDR1
DAC_FLAG_DMAUDR2
DAC IT Definition
DAC_IT_DMAUDR1
DAC_IT_DMAUDR2
DAC Output Buffer
DAC_OUTPUTBUFFER_ENABLE
DAC_OUTPUTBUFFER_DISABLE
DAC Trigger Selection
DAC_TRIGGER_NONE

Conversion is automatic once the DAC1_DHRxxxx
register has been loaded, and not by external trigger

DAC_TRIGGER_T2_TRGO

TIM2 TRGO selected as external conversion trigger for
DAC channel

DAC_TRIGGER_T4_TRGO

TIM4 TRGO selected as external conversion trigger for
DAC channel

DAC_TRIGGER_T5_TRGO

TIM5 TRGO selected as external conversion trigger for
DAC channel

DAC_TRIGGER_T6_TRGO

TIM6 TRGO selected as external conversion trigger for
DAC channel

DAC_TRIGGER_T7_TRGO

TIM7 TRGO selected as external conversion trigger for
DAC channel

DAC_TRIGGER_T8_TRGO

TIM8 TRGO selected as external conversion trigger for
DAC channel

DAC_TRIGGER_EXT_IT9

EXTI Line9 event selected as external conversion trigger
for DAC channel

DAC_TRIGGER_SOFTWARE

Conversion started by software trigger for DAC channel

DocID025834 Rev 4

191/964

HAL DAC Extension Driver

UM1725

13

HAL DAC Extension Driver

13.1

DACEx Firmware driver API description

13.1.1

How to use this driver
When Dual mode is enabled (i.e DAC Channel1 and Channel2 are used
simultaneously) : Use HAL_DACEx_DualGetValue() to get digital data to be converted
and use HAL_DACEx_DualSetValue() to set digital value to converted simultaneously
in Channel 1 and Channel 2.
Use HAL_DACEx_TriangleWaveGenerate() to generate Triangle signal.
Use HAL_DACEx_NoiseWaveGenerate() to generate Noise signal.

13.1.2

Extended features functions
This section provides functions allowing to:
Start conversion.
Stop conversion.
Start conversion and enable DMA transfer.
Stop conversion and disable DMA transfer.
Get result of conversion.
Get result of dual mode conversion.
This section contains the following APIs:
HAL_DACEx_DualGetValue()
HAL_DACEx_TriangleWaveGenerate()
HAL_DACEx_NoiseWaveGenerate()
HAL_DACEx_DualSetValue()
HAL_DACEx_ConvCpltCallbackCh2()
HAL_DACEx_ConvHalfCpltCallbackCh2()
HAL_DACEx_ErrorCallbackCh2()
HAL_DACEx_DMAUnderrunCallbackCh2()

13.1.3

Detailed description of functions
HAL_DACEx_DualGetValue

192/964

Function Name

uint32_t HAL_DACEx_DualGetValue (DAC_HandleTypeDef *
hdac)

Function Description

Returns the last data output value of the selected DAC channel.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

The: selected DAC channel data output value.

DocID025834 Rev 4

UM1725

HAL DAC Extension Driver

HAL_DACEx_TriangleWaveGenerate
Function Name

HAL_StatusTypeDef HAL_DACEx_TriangleWaveGenerate
(DAC_HandleTypeDef * hdac, uint32_t Channel, uint32_t
Amplitude)

Function Description

Enables or disables the selected DAC channel wave generation.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.
Channel: The selected DAC channel. This parameter can be
one of the following values: DAC_CHANNEL_1 /
DAC_CHANNEL_2
Amplitude: Select max triangle amplitude. This parameter
can be one of the following values:
DAC_TRIANGLEAMPLITUDE_1: Select max triangle
amplitude of 1
DAC_TRIANGLEAMPLITUDE_3: Select max triangle
amplitude of 3
DAC_TRIANGLEAMPLITUDE_7: Select max triangle
amplitude of 7
DAC_TRIANGLEAMPLITUDE_15: Select max triangle
amplitude of 15
DAC_TRIANGLEAMPLITUDE_31: Select max triangle
amplitude of 31
DAC_TRIANGLEAMPLITUDE_63: Select max triangle
amplitude of 63
DAC_TRIANGLEAMPLITUDE_127: Select max triangle
amplitude of 127
DAC_TRIANGLEAMPLITUDE_255: Select max triangle
amplitude of 255
DAC_TRIANGLEAMPLITUDE_511: Select max triangle
amplitude of 511
DAC_TRIANGLEAMPLITUDE_1023: Select max triangle
amplitude of 1023
DAC_TRIANGLEAMPLITUDE_2047: Select max triangle
amplitude of 2047
DAC_TRIANGLEAMPLITUDE_4095: Select max triangle
amplitude of 4095

Return values

HAL: status

HAL_DACEx_NoiseWaveGenerate
Function Name

HAL_StatusTypeDef HAL_DACEx_NoiseWaveGenerate
(DAC_HandleTypeDef * hdac, uint32_t Channel, uint32_t
Amplitude)

Function Description

Enables or disables the selected DAC channel wave generation.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.
Channel: The selected DAC channel. This parameter can be
one of the following values: DAC_CHANNEL_1 /
DAC_CHANNEL_2
Amplitude: Unmask DAC channel LFSR for noise wave
generation. This parameter can be one of the following
DocID025834 Rev 4

193/964

HAL DAC Extension Driver

Return values

UM1725
values:
DAC_LFSRUNMASK_BIT0: Unmask DAC channel
LFSR bit0 for noise wave generation
DAC_LFSRUNMASK_BITS1_0: Unmask DAC channel
LFSR bit[1:0] for noise wave generation
DAC_LFSRUNMASK_BITS2_0: Unmask DAC channel
LFSR bit[2:0] for noise wave generation
DAC_LFSRUNMASK_BITS3_0: Unmask DAC channel
LFSR bit[3:0] for noise wave generation
DAC_LFSRUNMASK_BITS4_0: Unmask DAC channel
LFSR bit[4:0] for noise wave generation
DAC_LFSRUNMASK_BITS5_0: Unmask DAC channel
LFSR bit[5:0] for noise wave generation
DAC_LFSRUNMASK_BITS6_0: Unmask DAC channel
LFSR bit[6:0] for noise wave generation
DAC_LFSRUNMASK_BITS7_0: Unmask DAC channel
LFSR bit[7:0] for noise wave generation
DAC_LFSRUNMASK_BITS8_0: Unmask DAC channel
LFSR bit[8:0] for noise wave generation
DAC_LFSRUNMASK_BITS9_0: Unmask DAC channel
LFSR bit[9:0] for noise wave generation
DAC_LFSRUNMASK_BITS10_0: Unmask DAC channel
LFSR bit[10:0] for noise wave generation
DAC_LFSRUNMASK_BITS11_0: Unmask DAC channel
LFSR bit[11:0] for noise wave generation
HAL: status

HAL_DACEx_DualSetValue

194/964

Function Name

HAL_StatusTypeDef HAL_DACEx_DualSetValue
(DAC_HandleTypeDef * hdac, uint32_t Alignment, uint32_t
Data1, uint32_t Data2)

Function Description

Set the specified data holding register value for dual DAC channel.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.
Alignment: Specifies the data alignment for dual channel
DAC. This parameter can be one of the following values:
DAC_ALIGN_8B_R: 8bit right data alignment selected
DAC_ALIGN_12B_L: 12bit left data alignment selected
DAC_ALIGN_12B_R: 12bit right data alignment selected
Data1: Data for DAC Channel2 to be loaded in the selected
data holding register.
Data2: Data for DAC Channel1 to be loaded in the selected
data holding register.

Return values

HAL: status

Notes

In dual mode, a unique register access is required to write in
both DAC channels at the same time.

DocID025834 Rev 4

UM1725

HAL DAC Extension Driver

HAL_DACEx_ConvCpltCallbackCh2
Function Name

void HAL_DACEx_ConvCpltCallbackCh2
(DAC_HandleTypeDef * hdac)

Function Description

Conversion complete callback in non blocking mode for Channel2.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

None

HAL_DACEx_ConvHalfCpltCallbackCh2
Function Name

void HAL_DACEx_ConvHalfCpltCallbackCh2
(DAC_HandleTypeDef * hdac)

Function Description

Conversion half DMA transfer callback in non blocking mode for
Channel2.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

None

HAL_DACEx_ErrorCallbackCh2
Function Name

void HAL_DACEx_ErrorCallbackCh2 (DAC_HandleTypeDef *
hdac)

Function Description

Error DAC callback for Channel2.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

None

HAL_DACEx_DMAUnderrunCallbackCh2
Function Name

void HAL_DACEx_DMAUnderrunCallbackCh2
(DAC_HandleTypeDef * hdac)

Function Description

DMA underrun DAC callback for channel2.

Parameters

hdac: pointer to a DAC_HandleTypeDef structure that
contains the configuration information for the specified DAC.

Return values

None

DAC_DMAConvCpltCh2
Function Name

void DAC_DMAConvCpltCh2 (DMA_HandleTypeDef * hdma)

Function Description

DMA conversion complete callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

DocID025834 Rev 4

195/964

HAL DAC Extension Driver

UM1725

DAC_DMAErrorCh2
Function Name

void DAC_DMAErrorCh2 (DMA_HandleTypeDef * hdma)

Function Description

DMA error callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

DAC_DMAHalfConvCpltCh2
Function Name

void DAC_DMAHalfConvCpltCh2 (DMA_HandleTypeDef *
hdma)

Function Description

DMA half transfer complete callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

13.2

DACEx Firmware driver defines

13.2.1

DACEx
DAC LFS Run Mask Triangle Amplitude

196/964

DAC_LFSRUNMASK_BIT0

Unmask DAC channel LFSR bit0 for noise wave
generation

DAC_LFSRUNMASK_BITS1_0

Unmask DAC channel LFSR bit[1:0] for noise wave
generation

DAC_LFSRUNMASK_BITS2_0

Unmask DAC channel LFSR bit[2:0] for noise wave
generation

DAC_LFSRUNMASK_BITS3_0

Unmask DAC channel LFSR bit[3:0] for noise wave
generation

DAC_LFSRUNMASK_BITS4_0

Unmask DAC channel LFSR bit[4:0] for noise wave
generation

DAC_LFSRUNMASK_BITS5_0

Unmask DAC channel LFSR bit[5:0] for noise wave
generation

DAC_LFSRUNMASK_BITS6_0

Unmask DAC channel LFSR bit[6:0] for noise wave
generation

DAC_LFSRUNMASK_BITS7_0

Unmask DAC channel LFSR bit[7:0] for noise wave
generation

DAC_LFSRUNMASK_BITS8_0

Unmask DAC channel LFSR bit[8:0] for noise wave
generation

DAC_LFSRUNMASK_BITS9_0

Unmask DAC channel LFSR bit[9:0] for noise wave
generation

DAC_LFSRUNMASK_BITS10_0

Unmask DAC channel LFSR bit[10:0] for noise
wave generation

DocID025834 Rev 4

UM1725
DAC_LFSRUNMASK_BITS11_0

HAL DAC Extension Driver
Unmask DAC channel LFSR bit[11:0] for noise
wave generation

DAC_TRIANGLEAMPLITUDE_1

Select max triangle amplitude of 1

DAC_TRIANGLEAMPLITUDE_3

Select max triangle amplitude of 3

DAC_TRIANGLEAMPLITUDE_7

Select max triangle amplitude of 7

DAC_TRIANGLEAMPLITUDE_15

Select max triangle amplitude of 15

DAC_TRIANGLEAMPLITUDE_31

Select max triangle amplitude of 31

DAC_TRIANGLEAMPLITUDE_63

Select max triangle amplitude of 63

DAC_TRIANGLEAMPLITUDE_127

Select max triangle amplitude of 127

DAC_TRIANGLEAMPLITUDE_255

Select max triangle amplitude of 255

DAC_TRIANGLEAMPLITUDE_511

Select max triangle amplitude of 511

DAC_TRIANGLEAMPLITUDE_1023

Select max triangle amplitude of 1023

DAC_TRIANGLEAMPLITUDE_2047

Select max triangle amplitude of 2047

DAC_TRIANGLEAMPLITUDE_4095

Select max triangle amplitude of 4095

DocID025834 Rev 4

197/964

HAL DCMI Generic Driver

UM1725

14

HAL DCMI Generic Driver

14.1

DCMI Firmware driver registers structures

14.1.1

DCMI_HandleTypeDef
Data Fields
DCMI_TypeDef * Instance
DCMI_InitTypeDef Init
HAL_LockTypeDef Lock
__IO HAL_DCMI_StateTypeDef State
__IO uint32_t XferCount
__IO uint32_t XferSize
uint32_t XferTransferNumber
uint32_t pBuffPtr
DMA_HandleTypeDef * DMA_Handle
__IO uint32_t ErrorCode

Field Documentation
DCMI_TypeDef* DCMI_HandleTypeDef::Instance
DCMI Register base address
DCMI_InitTypeDef DCMI_HandleTypeDef::Init
DCMI parameters
HAL_LockTypeDef DCMI_HandleTypeDef::Lock
DCMI locking object
__IO HAL_DCMI_StateTypeDef DCMI_HandleTypeDef::State
DCMI state
__IO uint32_t DCMI_HandleTypeDef::XferCount
DMA transfer counter
__IO uint32_t DCMI_HandleTypeDef::XferSize
DMA transfer size
uint32_t DCMI_HandleTypeDef::XferTransferNumber
DMA transfer number
uint32_t DCMI_HandleTypeDef::pBuffPtr
Pointer to DMA output buffer
DMA_HandleTypeDef* DCMI_HandleTypeDef::DMA_Handle
Pointer to the DMA handler
__IO uint32_t DCMI_HandleTypeDef::ErrorCode
DCMI Error code

198/964

DocID025834 Rev 4

UM1725

HAL DCMI Generic Driver

14.2

DCMI Firmware driver API description

14.2.1

How to use this driver
The sequence below describes how to use this driver to capture image from a camera
module connected to the DCMI Interface. This sequence does not take into account the
configuration of the camera module, which should be made before to configure and enable
the DCMI to capture images.
1.

2.
3.

4.

5.
6.

Program the required configuration through following parameters: horizontal and
vertical polarity, pixel clock polarity, Capture Rate, Synchronization Mode, code of the
frame delimiter and data width using HAL_DCMI_Init() function.
Configure the DMA2_Stream1 channel1 to transfer Data from DCMI DR register to
the destination memory buffer.
Program the required configuration through following parameters: DCMI mode,
destination memory Buffer address and the data length and enable capture using
HAL_DCMI_Start_DMA() function.
Optionally, configure and Enable the CROP feature to select a rectangular window
from the received image using HAL_DCMI_ConfigCrop() and
HAL_DCMI_EnableCROP() functions
The capture can be stopped using HAL_DCMI_Stop() function.
To control DCMI state you can use the function HAL_DCMI_GetState().

DCMI HAL driver macros list
Below the list of most used macros in DCMI HAL driver.
__HAL_DCMI_ENABLE: Enable the DCMI peripheral.
__HAL_DCMI_DISABLE: Disable the DCMI peripheral.
__HAL_DCMI_GET_FLAG: Get the DCMI pending flags.
__HAL_DCMI_CLEAR_FLAG: Clear the DCMI pending flags.
__HAL_DCMI_ENABLE_IT: Enable the specified DCMI interrupts.
__HAL_DCMI_DISABLE_IT: Disable the specified DCMI interrupts.
__HAL_DCMI_GET_IT_SOURCE: Check whether the specified DCMI interrupt has
occurred or not.
You can refer to the DCMI HAL driver header file for more useful macros

14.2.2

Initialization and Configuration functions
This section provides functions allowing to:
Initialize and configure the DCMI
De-initialize the DCMI
This section contains the following APIs:
HAL_DCMI_Init()
HAL_DCMI_DeInit()
HAL_DCMI_MspInit()
HAL_DCMI_MspDeInit()

DocID025834 Rev 4

199/964

HAL DCMI Generic Driver

14.2.3

UM1725

IO operation functions
This section provides functions allowing to:
Configure destination address and data length and Enables DCMI DMA request and
enables DCMI capture
Stop the DCMI capture.
Handles DCMI interrupt request.
This section contains the following APIs:
HAL_DCMI_Start_DMA()
HAL_DCMI_Stop()
HAL_DCMI_Suspend()
HAL_DCMI_Resume()
HAL_DCMI_IRQHandler()
HAL_DCMI_ErrorCallback()
HAL_DCMI_LineEventCallback()
HAL_DCMI_VsyncEventCallback()
HAL_DCMI_FrameEventCallback()
HAL_DCMI_VsyncCallback()
HAL_DCMI_HsyncCallback()

14.2.4

Peripheral Control functions
This section provides functions allowing to:
Configure the CROP feature.
Enable/Disable the CROP feature.
This section contains the following APIs:
HAL_DCMI_ConfigCrop()
HAL_DCMI_DisableCrop()
HAL_DCMI_EnableCrop()

14.2.5

Peripheral State and Errors functions
This subsection provides functions allowing to
Check the DCMI state.
Get the specific DCMI error flag.
This section contains the following APIs:
HAL_DCMI_GetState()
HAL_DCMI_GetError()

14.2.6

Detailed description of functions
HAL_DCMI_Init
Function Name

HAL_StatusTypeDef HAL_DCMI_Init (DCMI_HandleTypeDef *
hdcmi)

Function Description

Initializes the DCMI according to the specified parameters in the
DCMI_InitTypeDef and create the associated handle.

Parameters

200/964

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

DocID025834 Rev 4

UM1725

HAL DCMI Generic Driver
Return values

HAL: status

HAL_DCMI_DeInit
Function Name

HAL_StatusTypeDef HAL_DCMI_DeInit (DCMI_HandleTypeDef
* hdcmi)

Function Description

Deinitializes the DCMI peripheral registers to their default reset
values.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

HAL: status

HAL_DCMI_MspInit
Function Name

void HAL_DCMI_MspInit (DCMI_HandleTypeDef * hdcmi)

Function Description

Initializes the DCMI MSP.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

None

HAL_DCMI_MspDeInit
Function Name

void HAL_DCMI_MspDeInit (DCMI_HandleTypeDef * hdcmi)

Function Description

DeInitializes the DCMI MSP.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

None

HAL_DCMI_Start_DMA
Function Name

HAL_StatusTypeDef HAL_DCMI_Start_DMA
(DCMI_HandleTypeDef * hdcmi, uint32_t DCMI_Mode, uint32_t
pData, uint32_t Length)

Function Description

Enables DCMI DMA request and enables DCMI capture.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.
DCMI_Mode: DCMI capture mode snapshot or continuous
grab.
pData: The destination memory Buffer address (LCD Frame
buffer).
Length: The length of capture to be transferred.

Return values

HAL: status

DocID025834 Rev 4

201/964

HAL DCMI Generic Driver

UM1725

HAL_DCMI_Stop
Function Name

HAL_StatusTypeDef HAL_DCMI_Stop (DCMI_HandleTypeDef *
hdcmi)

Function Description

Disable DCMI DMA request and Disable DCMI capture.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

HAL: status

HAL_DCMI_Suspend
Function Name

HAL_StatusTypeDef HAL_DCMI_Suspend
(DCMI_HandleTypeDef * hdcmi)

Function Description

HAL_DCMI_Resume
Function Name

HAL_StatusTypeDef HAL_DCMI_Resume
(DCMI_HandleTypeDef * hdcmi)

Function Description

Resume DCMI capture.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

HAL: status

HAL_DCMI_ErrorCallback
Function Name

void HAL_DCMI_ErrorCallback (DCMI_HandleTypeDef *
hdcmi)

Function Description

Error DCMI callback.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

None

HAL_DCMI_LineEventCallback
Function Name

void HAL_DCMI_LineEventCallback (DCMI_HandleTypeDef *
hdcmi)

Function Description

Line Event callback.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

None

HAL_DCMI_FrameEventCallback

202/964

Function Name

void HAL_DCMI_FrameEventCallback (DCMI_HandleTypeDef *
hdcmi)

Function Description

Frame Event callback.
DocID025834 Rev 4

UM1725

HAL DCMI Generic Driver
Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

None

HAL_DCMI_VsyncEventCallback
Function Name

void HAL_DCMI_VsyncEventCallback (DCMI_HandleTypeDef *
hdcmi)

Function Description

VSYNC Event callback.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

None

HAL_DCMI_VsyncCallback
Function Name

void HAL_DCMI_VsyncCallback (DCMI_HandleTypeDef *
hdcmi)

Function Description

HAL_DCMI_HsyncCallback
Function Name

void HAL_DCMI_HsyncCallback (DCMI_HandleTypeDef *
hdcmi)

Function Description

HAL_DCMI_IRQHandler
Function Name

void HAL_DCMI_IRQHandler (DCMI_HandleTypeDef * hdcmi)

Function Description

Handles DCMI interrupt request.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for the DCMI.

Return values

None

HAL_DCMI_ConfigCrop
Function Name

HAL_StatusTypeDef HAL_DCMI_ConfigCrop
(DCMI_HandleTypeDef * hdcmi, uint32_t X0, uint32_t Y0,
uint32_t XSize, uint32_t YSize)

Function Description

Configure the DCMI CROP coordinate.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.
X0: DCMI window X offset
Y0: DCMI window Y offset
XSize: DCMI Pixel per line
YSize: DCMI Line number

Return values

HAL: status

DocID025834 Rev 4

203/964

HAL DCMI Generic Driver

UM1725

HAL_DCMI_EnableCrop
Function Name

HAL_StatusTypeDef HAL_DCMI_EnableCrop
(DCMI_HandleTypeDef * hdcmi)

Function Description

Enable the Crop feature.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

HAL: status

HAL_DCMI_DisableCrop
Function Name

HAL_StatusTypeDef HAL_DCMI_DisableCrop
(DCMI_HandleTypeDef * hdcmi)

Function Description

Disable the Crop feature.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

HAL: status

HAL_DCMI_GetState
Function Name

HAL_DCMI_StateTypeDef HAL_DCMI_GetState
(DCMI_HandleTypeDef * hdcmi)

Function Description

Return the DCMI state.

Parameters

hdcmi: pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

HAL: state

HAL_DCMI_GetError
Function Name

uint32_t HAL_DCMI_GetError (DCMI_HandleTypeDef * hdcmi)

Function Description

Return the DCMI error code.

Parameters

hdcmi: : pointer to a DCMI_HandleTypeDef structure that
contains the configuration information for DCMI.

Return values

DCMI: Error Code

14.3

DCMI Firmware driver defines

14.3.1

DCMI
DCMI Capture Mode

204/964

DCMI_MODE_CONTINUOUS

The received data are transferred continuously into the
destination memory through the DMA

DCMI_MODE_SNAPSHOT

Once activated, the interface waits for the start of frame
and then transfers a single frame through the DMA

DocID025834 Rev 4

UM1725

HAL DCMI Generic Driver
DCMI Capture Rate
DCMI_CR_ALL_FRAME

All frames are captured

DCMI_CR_ALTERNATE_2_FRAME

Every alternate frame captured

DCMI_CR_ALTERNATE_4_FRAME

One frame in 4 frames captured

DCMI Error Code
HAL_DCMI_ERROR_NONE

No error

HAL_DCMI_ERROR_OVR

Overrun error

HAL_DCMI_ERROR_SYNC

Synchronization error

HAL_DCMI_ERROR_TIMEOUT

Timeout error

HAL_DCMI_ERROR_DMA

DMA error

DCMI Exported Macros
__HAL_DCMI_RESET_HANDLE_STATE

Description:
Reset DCMI handle state.
Parameters:
__HANDLE__: specifies the DCMI
handle.
Return value:
None

__HAL_DCMI_ENABLE

Description:
Enable the DCMI.
Parameters:
__HANDLE__: DCMI handle
Return value:
None

__HAL_DCMI_DISABLE

Description:
Disable the DCMI.
Parameters:
__HANDLE__: DCMI handle
Return value:
None

__HAL_DCMI_GET_FLAG

Description:
Get the DCMI pending flag.
Parameters:
__HANDLE__: DCMI handle
__FLAG__: Get the specified flag. This
parameter can be one of the following
values (no combination allowed)
DCMI_FLAG_HSYNC: HSYNC pin
DocID025834 Rev 4

205/964

HAL DCMI Generic Driver

UM1725
state (active line / synchronization
between lines)
DCMI_FLAG_VSYNC: VSYNC pin
state (active frame / synchronization
between frames)
DCMI_FLAG_FNE: FIFO empty flag
DCMI_FLAG_FRAMERI: Frame
capture complete flag mask
DCMI_FLAG_OVRRI: Overrun flag
mask
DCMI_FLAG_ERRRI:
Synchronization error flag mask
DCMI_FLAG_VSYNCRI: VSYNC
flag mask
DCMI_FLAG_LINERI: Line flag mask
DCMI_FLAG_FRAMEMI: DCMI
Capture complete masked interrupt
status
DCMI_FLAG_OVRMI: DCMI Overrun
masked interrupt status
DCMI_FLAG_ERRMI: DCMI
Synchronization error masked
interrupt status
DCMI_FLAG_VSYNCMI: DCMI
VSYNC masked interrupt status
DCMI_FLAG_LINEMI: DCMI Line
masked interrupt status
Return value:
The: state of FLAG.

__HAL_DCMI_CLEAR_FLAG

Description:
Clear the DCMI pending flags.
Parameters:
__HANDLE__: DCMI handle
__FLAG__: specifies the flag to clear.
This parameter can be any combination of
the following values:
DCMI_FLAG_FRAMERI: Frame
capture complete flag mask
DCMI_FLAG_OVRRI: Overrun flag
mask
DCMI_FLAG_ERRRI:
Synchronization error flag mask
DCMI_FLAG_VSYNCRI: VSYNC
flag mask
DCMI_FLAG_LINERI: Line flag mask
Return value:
None

206/964

DocID025834 Rev 4

UM1725

HAL DCMI Generic Driver
Description:

__HAL_DCMI_ENABLE_IT

Enable the specified DCMI interrupts.
Parameters:
__HANDLE__: DCMI handle
__INTERRUPT__: specifies the DCMI
interrupt sources to be enabled. This
parameter can be any combination of the
following values:
DCMI_IT_FRAME: Frame capture
complete interrupt mask
DCMI_IT_OVR: Overrun interrupt
mask
DCMI_IT_ERR: Synchronization
error interrupt mask
DCMI_IT_VSYNC: VSYNC interrupt
mask
DCMI_IT_LINE: Line interrupt mask
Return value:
None
Description:

__HAL_DCMI_DISABLE_IT

Disable the specified DCMI interrupts.
Parameters:
__HANDLE__: DCMI handle
__INTERRUPT__: specifies the DCMI
interrupt sources to be enabled. This
parameter can be any combination of the
following values:
DCMI_IT_FRAME: Frame capture
complete interrupt mask
DCMI_IT_OVR: Overrun interrupt
mask
DCMI_IT_ERR: Synchronization
error interrupt mask
DCMI_IT_VSYNC: VSYNC interrupt
mask
DCMI_IT_LINE: Line interrupt mask
Return value:
None
__HAL_DCMI_GET_IT_SOURCE

Description:
Check whether the specified DCMI
interrupt has occurred or not.
Parameters:
__HANDLE__: DCMI handle
__INTERRUPT__: specifies the DCMI
interrupt source to check. This parameter
can be one of the following values:

DocID025834 Rev 4

207/964

HAL DCMI Generic Driver

UM1725
DCMI_IT_FRAME: Frame capture
complete interrupt mask
DCMI_IT_OVR: Overrun interrupt
mask
DCMI_IT_ERR: Synchronization
error interrupt mask
DCMI_IT_VSYNC: VSYNC interrupt
mask
DCMI_IT_LINE: Line interrupt mask
Return value:
The: state of INTERRUPT.

DCMI Extended Data Mode
DCMI_EXTEND_DATA_8B

Interface captures 8-bit data on every pixel clock

DCMI_EXTEND_DATA_10B

Interface captures 10-bit data on every pixel clock

DCMI_EXTEND_DATA_12B

Interface captures 12-bit data on every pixel clock

DCMI_EXTEND_DATA_14B

Interface captures 14-bit data on every pixel clock

DCMI Flags
DCMI_FLAG_HSYNC

HSYNC pin state (active line / synchronization between lines)

DCMI_FLAG_VSYNC

VSYNC pin state (active frame / synchronization between
frames)

DCMI_FLAG_FNE

FIFO not empty flag

DCMI_FLAG_FRAMERI

Frame capture complete interrupt flag

DCMI_FLAG_OVRRI

Overrun interrupt flag

DCMI_FLAG_ERRRI

Synchronization error interrupt flag

DCMI_FLAG_VSYNCRI

VSYNC interrupt flag

DCMI_FLAG_LINERI

Line interrupt flag

DCMI_FLAG_FRAMEMI

DCMI Frame capture complete masked interrupt status

DCMI_FLAG_OVRMI

DCMI Overrun masked interrupt status

DCMI_FLAG_ERRMI

DCMI Synchronization error masked interrupt status

DCMI_FLAG_VSYNCMI

DCMI VSYNC masked interrupt status

DCMI_FLAG_LINEMI

DCMI Line masked interrupt status

DCMI HSYNC Polarity
DCMI_HSPOLARITY_LOW

Horizontal synchronization active Low

DCMI_HSPOLARITY_HIGH

Horizontal synchronization active High

DCMI interrupt sources

208/964

DCMI_IT_FRAME

Capture complete interrupt

DCMI_IT_OVR

Overrun interrupt

DCMI_IT_ERR

Synchronization error interrupt

DCMI_IT_VSYNC

VSYNC interrupt

DocID025834 Rev 4

UM1725

HAL DCMI Generic Driver
DCMI_IT_LINE

Line interrupt

DCMI MODE JPEG
DCMI_JPEG_DISABLE

Mode JPEG Disabled

DCMI_JPEG_ENABLE

Mode JPEG Enabled

DCMI PIXCK Polarity
DCMI_PCKPOLARITY_FALLING

Pixel clock active on Falling edge

DCMI_PCKPOLARITY_RISING

Pixel clock active on Rising edge

DCMI Synchronization Mode
DCMI_SYNCHRO_HARDWARE

Hardware synchronization data capture (frame/line
start/stop) is synchronized with the HSYNC/VSYNC
signals

DCMI_SYNCHRO_EMBEDDED

Embedded synchronization data capture is
synchronized with synchronization codes embedded in
the data flow

DCMI VSYNC Polarity
DCMI_VSPOLARITY_LOW

Vertical synchronization active Low

DCMI_VSPOLARITY_HIGH

Vertical synchronization active High

DCMI Window Coordinate
DCMI_WINDOW_COORDINATE

Window coordinate

DCMI Window Height
DCMI_WINDOW_HEIGHT

Window Height

DCMI Window Vertical Line
DCMI_POSITION_CWSIZE_VLINE

Required left shift to set crop window vertical line
count

DCMI_POSITION_CWSTRT_VST

Required left shift to set crop window vertical start
line count

DocID025834 Rev 4

209/964

HAL DCMI Extension Driver

UM1725

15

HAL DCMI Extension Driver

15.1

DCMIEx Firmware driver registers structures

15.1.1

DCMI_CodesInitTypeDef
Data Fields
uint8_t FrameStartCode
uint8_t LineStartCode
uint8_t LineEndCode
uint8_t FrameEndCode

Field Documentation
uint8_t DCMI_CodesInitTypeDef::FrameStartCode
Specifies the code of the frame start delimiter.
uint8_t DCMI_CodesInitTypeDef::LineStartCode
Specifies the code of the line start delimiter.
uint8_t DCMI_CodesInitTypeDef::LineEndCode
Specifies the code of the line end delimiter.
uint8_t DCMI_CodesInitTypeDef::FrameEndCode
Specifies the code of the frame end delimiter.

15.1.2

DCMI_InitTypeDef
Data Fields
uint32_t SynchroMode
uint32_t PCKPolarity
uint32_t VSPolarity
uint32_t HSPolarity
uint32_t CaptureRate
uint32_t ExtendedDataMode
DCMI_CodesInitTypeDef SyncroCode
uint32_t JPEGMode
uint32_t ByteSelectMode
uint32_t ByteSelectStart
uint32_t LineSelectMode
uint32_t LineSelectStart

Field Documentation
uint32_t DCMI_InitTypeDef::SynchroMode
Specifies the Synchronization Mode: Hardware or Embedded. This parameter can be
a value of DCMI_Synchronization_Mode

210/964

DocID025834 Rev 4

UM1725

HAL DCMI Extension Driver
uint32_t DCMI_InitTypeDef::PCKPolarity
Specifies the Pixel clock polarity: Falling or Rising. This parameter can be a value of
DCMI_PIXCK_Polarity
uint32_t DCMI_InitTypeDef::VSPolarity
Specifies the Vertical synchronization polarity: High or Low. This parameter can be a
value of DCMI_VSYNC_Polarity
uint32_t DCMI_InitTypeDef::HSPolarity
Specifies the Horizontal synchronization polarity: High or Low. This parameter can be
a value of DCMI_HSYNC_Polarity
uint32_t DCMI_InitTypeDef::CaptureRate
Specifies the frequency of frame capture: All, 1/2 or 1/4. This parameter can be a
value of DCMI_Capture_Rate
uint32_t DCMI_InitTypeDef::ExtendedDataMode
Specifies the data width: 8-bit, 10-bit, 12-bit or 14-bit. This parameter can be a value
of DCMI_Extended_Data_Mode
DCMI_CodesInitTypeDef DCMI_InitTypeDef::SyncroCode
Specifies the code of the frame start delimiter.
uint32_t DCMI_InitTypeDef::JPEGMode
Enable or Disable the JPEG mode This parameter can be a value of
DCMI_MODE_JPEG
uint32_t DCMI_InitTypeDef::ByteSelectMode
Specifies the data to be captured by the interface This parameter can be a value of
DCMIEx_Byte_Select_Mode
uint32_t DCMI_InitTypeDef::ByteSelectStart
Specifies if the data to be captured by the interface is even or odd This parameter can
be a value of DCMIEx_Byte_Select_Start
uint32_t DCMI_InitTypeDef::LineSelectMode
Specifies the line of data to be captured by the interface This parameter can be a
value of DCMIEx_Line_Select_Mode
uint32_t DCMI_InitTypeDef::LineSelectStart
Specifies if the line of data to be captured by the interface is even or odd This
parameter can be a value of DCMIEx_Line_Select_Start

15.2

DCMIEx Firmware driver defines

15.2.1

DCMIEx
DCMI Byte Select Mode
DCMI_BSM_ALL

Interface captures all received data

DCMI_BSM_OTHER

Interface captures every other byte from the received data

DCMI_BSM_ALTERNATE_4

Interface captures one byte out of four

DCMI_BSM_ALTERNATE_2

Interface captures two bytes out of four

DCMI Byte Select Start
DCMI_OEBS_ODD

Interface captures first data from the frame/line start, second one
being dropped

DCMI_OEBS_EVEN

Interface captures second data from the frame/line start, first one
being dropped

DocID025834 Rev 4

211/964

HAL DCMI Extension Driver
DCMI Line Select Mode

UM1725

DCMI_LSM_ALL

Interface captures all received lines

DCMI_LSM_ALTERNATE_2

Interface captures one line out of two

DCMI Line Select Start

212/964

DCMI_OELS_ODD

Interface captures first line from the frame start, second one being
dropped

DCMI_OELS_EVEN

Interface captures second line from the frame start, first one being
dropped

DocID025834 Rev 4

UM1725

HAL DFSDM Generic Driver

16

HAL DFSDM Generic Driver

16.1

DFSDM Firmware driver registers structures

16.1.1

DFSDM_Channel_OutputClockTypeDef
Data Fields
FunctionalState Activation
uint32_t Selection
uint32_t Divider

Field Documentation
FunctionalState DFSDM_Channel_OutputClockTypeDef::Activation
Output clock enable/disable
uint32_t DFSDM_Channel_OutputClockTypeDef::Selection
Output clock is system clock or audio clock. This parameter can be a value of
DFSDM_Channel_OuputClock
uint32_t DFSDM_Channel_OutputClockTypeDef::Divider
Output clock divider. This parameter must be a number between Min_Data = 2 and
Max_Data = 256

16.1.2

DFSDM_Channel_InputTypeDef
Data Fields
uint32_t Multiplexer
uint32_t DataPacking
uint32_t Pins

Field Documentation
uint32_t DFSDM_Channel_InputTypeDef::Multiplexer
Input is external serial inputs or internal register. This parameter can be a value of
DFSDM_Channel_InputMultiplexer
uint32_t DFSDM_Channel_InputTypeDef::DataPacking
Standard, interleaved or dual mode for internal register. This parameter can be a
value of DFSDM_Channel_DataPacking
uint32_t DFSDM_Channel_InputTypeDef::Pins
Input pins are taken from same or following channel. This parameter can be a value
of DFSDM_Channel_InputPins

DocID025834 Rev 4

213/964

HAL DFSDM Generic Driver

16.1.3

UM1725

DFSDM_Channel_SerialInterfaceTypeDef
Data Fields
uint32_t Type
uint32_t SpiClock

Field Documentation
uint32_t DFSDM_Channel_SerialInterfaceTypeDef::Type
SPI or Manchester modes. This parameter can be a value of
DFSDM_Channel_SerialInterfaceType
uint32_t DFSDM_Channel_SerialInterfaceTypeDef::SpiClock
SPI clock select (external or internal with different sampling point). This parameter
can be a value of DFSDM_Channel_SpiClock

16.1.4

DFSDM_Channel_AwdTypeDef
Data Fields
uint32_t FilterOrder
uint32_t Oversampling

Field Documentation
uint32_t DFSDM_Channel_AwdTypeDef::FilterOrder
Analog watchdog Sinc filter order. This parameter can be a value of
DFSDM_Channel_AwdFilterOrder
uint32_t DFSDM_Channel_AwdTypeDef::Oversampling
Analog watchdog filter oversampling ratio. This parameter must be a number between
Min_Data = 1 and Max_Data = 32

16.1.5

DFSDM_Channel_InitTypeDef
Data Fields
DFSDM_Channel_OutputClockTypeDef OutputClock
DFSDM_Channel_InputTypeDef Input
DFSDM_Channel_SerialInterfaceTypeDef SerialInterface
DFSDM_Channel_AwdTypeDef Awd
int32_t Offset
uint32_t RightBitShift

214/964

DocID025834 Rev 4

UM1725

HAL DFSDM Generic Driver
Field Documentation
DFSDM_Channel_OutputClockTypeDef
DFSDM_Channel_InitTypeDef::OutputClock
DFSDM channel output clock parameters
DFSDM_Channel_InputTypeDef DFSDM_Channel_InitTypeDef::Input
DFSDM channel input parameters
DFSDM_Channel_SerialInterfaceTypeDef
DFSDM_Channel_InitTypeDef::SerialInterface
DFSDM channel serial interface parameters
DFSDM_Channel_AwdTypeDef DFSDM_Channel_InitTypeDef::Awd
DFSDM channel analog watchdog parameters
int32_t DFSDM_Channel_InitTypeDef::Offset
DFSDM channel offset. This parameter must be a number between Min_Data = 8388608 and Max_Data = 8388607
uint32_t DFSDM_Channel_InitTypeDef::RightBitShift
DFSDM channel right bit shift. This parameter must be a number between Min_Data
= 0x00 and Max_Data = 0x1F

16.1.6

DFSDM_Channel_HandleTypeDef
Data Fields
DFSDM_Channel_TypeDef * Instance
DFSDM_Channel_InitTypeDef Init
HAL_DFSDM_Channel_StateTypeDef State

Field Documentation
DFSDM_Channel_TypeDef* DFSDM_Channel_HandleTypeDef::Instance
DFSDM channel instance
DFSDM_Channel_InitTypeDef DFSDM_Channel_HandleTypeDef::Init
DFSDM channel init parameters
HAL_DFSDM_Channel_StateTypeDef DFSDM_Channel_HandleTypeDef::State
DFSDM channel state

16.1.7

DFSDM_Filter_RegularParamTypeDef
Data Fields
uint32_t Trigger
FunctionalState FastMode
FunctionalState DmaMode

DocID025834 Rev 4

215/964

HAL DFSDM Generic Driver

UM1725

Field Documentation
uint32_t DFSDM_Filter_RegularParamTypeDef::Trigger
Trigger used to start regular conversion: software or synchronous. This parameter
can be a value of DFSDM_Filter_Trigger
FunctionalState DFSDM_Filter_RegularParamTypeDef::FastMode
Enable/disable fast mode for regular conversion
FunctionalState DFSDM_Filter_RegularParamTypeDef::DmaMode
Enable/disable DMA for regular conversion

16.1.8

DFSDM_Filter_InjectedParamTypeDef
Data Fields
uint32_t Trigger
FunctionalState ScanMode
FunctionalState DmaMode
uint32_t ExtTrigger
uint32_t ExtTriggerEdge

Field Documentation
uint32_t DFSDM_Filter_InjectedParamTypeDef::Trigger
Trigger used to start injected conversion: software, external or synchronous. This
parameter can be a value of DFSDM_Filter_Trigger
FunctionalState DFSDM_Filter_InjectedParamTypeDef::ScanMode
Enable/disable scanning mode for injected conversion
FunctionalState DFSDM_Filter_InjectedParamTypeDef::DmaMode
Enable/disable DMA for injected conversion
uint32_t DFSDM_Filter_InjectedParamTypeDef::ExtTrigger
External trigger. This parameter can be a value of DFSDM_Filter_ExtTrigger
uint32_t DFSDM_Filter_InjectedParamTypeDef::ExtTriggerEdge
External trigger edge: rising, falling or both. This parameter can be a value of
DFSDM_Filter_ExtTriggerEdge

16.1.9

DFSDM_Filter_FilterParamTypeDef
Data Fields
uint32_t SincOrder
uint32_t Oversampling
uint32_t IntOversampling

216/964

DocID025834 Rev 4

UM1725

HAL DFSDM Generic Driver
Field Documentation
uint32_t DFSDM_Filter_FilterParamTypeDef::SincOrder
Sinc filter order. This parameter can be a value of DFSDM_Filter_SincOrder
uint32_t DFSDM_Filter_FilterParamTypeDef::Oversampling
Filter oversampling ratio. This parameter must be a number between Min_Data = 1
and Max_Data = 1024
uint32_t DFSDM_Filter_FilterParamTypeDef::IntOversampling
Integrator oversampling ratio. This parameter must be a number between Min_Data =
1 and Max_Data = 256

16.1.10

DFSDM_Filter_InitTypeDef
Data Fields
DFSDM_Filter_RegularParamTypeDef RegularParam
DFSDM_Filter_InjectedParamTypeDef InjectedParam
DFSDM_Filter_FilterParamTypeDef FilterParam

Field Documentation
DFSDM_Filter_RegularParamTypeDef DFSDM_Filter_InitTypeDef::RegularParam
DFSDM regular conversion parameters
DFSDM_Filter_InjectedParamTypeDef DFSDM_Filter_InitTypeDef::InjectedParam
DFSDM injected conversion parameters
DFSDM_Filter_FilterParamTypeDef DFSDM_Filter_InitTypeDef::FilterParam
DFSDM filter parameters

16.1.11

DFSDM_Filter_HandleTypeDef
Data Fields
DFSDM_Filter_TypeDef * Instance
DFSDM_Filter_InitTypeDef Init
DMA_HandleTypeDef * hdmaReg
DMA_HandleTypeDef * hdmaInj
uint32_t RegularContMode
uint32_t RegularTrigger
uint32_t InjectedTrigger
uint32_t ExtTriggerEdge
FunctionalState InjectedScanMode
uint32_t InjectedChannelsNbr
uint32_t InjConvRemaining
HAL_DFSDM_Filter_StateTypeDef State
uint32_t ErrorCode

DocID025834 Rev 4

217/964

HAL DFSDM Generic Driver

UM1725

Field Documentation
DFSDM_Filter_TypeDef* DFSDM_Filter_HandleTypeDef::Instance
DFSDM filter instance
DFSDM_Filter_InitTypeDef DFSDM_Filter_HandleTypeDef::Init
DFSDM filter init parameters
DMA_HandleTypeDef* DFSDM_Filter_HandleTypeDef::hdmaReg
Pointer on DMA handler for regular conversions
DMA_HandleTypeDef* DFSDM_Filter_HandleTypeDef::hdmaInj
Pointer on DMA handler for injected conversions
uint32_t DFSDM_Filter_HandleTypeDef::RegularContMode
Regular conversion continuous mode
uint32_t DFSDM_Filter_HandleTypeDef::RegularTrigger
Trigger used for regular conversion
uint32_t DFSDM_Filter_HandleTypeDef::InjectedTrigger
Trigger used for injected conversion
uint32_t DFSDM_Filter_HandleTypeDef::ExtTriggerEdge
Rising, falling or both edges selected
FunctionalState DFSDM_Filter_HandleTypeDef::InjectedScanMode
Injected scanning mode
uint32_t DFSDM_Filter_HandleTypeDef::InjectedChannelsNbr
Number of channels in injected sequence
uint32_t DFSDM_Filter_HandleTypeDef::InjConvRemaining
Injected conversions remaining
HAL_DFSDM_Filter_StateTypeDef DFSDM_Filter_HandleTypeDef::State
DFSDM filter state
uint32_t DFSDM_Filter_HandleTypeDef::ErrorCode
DFSDM filter error code

16.1.12

DFSDM_Filter_AwdParamTypeDef
Data Fields
uint32_t DataSource
uint32_t Channel
int32_t HighThreshold
int32_t LowThreshold
uint32_t HighBreakSignal
uint32_t LowBreakSignal

Field Documentation
uint32_t DFSDM_Filter_AwdParamTypeDef::DataSource
Values from digital filter or from channel watchdog filter. This parameter can be a
value of DFSDM_Filter_AwdDataSource
uint32_t DFSDM_Filter_AwdParamTypeDef::Channel
Analog watchdog channel selection. This parameter can be a values combination of
DFSDM_Channel_Selection

218/964

DocID025834 Rev 4

UM1725

HAL DFSDM Generic Driver
int32_t DFSDM_Filter_AwdParamTypeDef::HighThreshold
High threshold for the analog watchdog. This parameter must be a number between
Min_Data = -8388608 and Max_Data = 8388607
int32_t DFSDM_Filter_AwdParamTypeDef::LowThreshold
Low threshold for the analog watchdog. This parameter must be a number between
Min_Data = -8388608 and Max_Data = 8388607
uint32_t DFSDM_Filter_AwdParamTypeDef::HighBreakSignal
Break signal assigned to analog watchdog high threshold event. This parameter can
be a values combination of DFSDM_BreakSignals
uint32_t DFSDM_Filter_AwdParamTypeDef::LowBreakSignal
Break signal assigned to analog watchdog low threshold event. This parameter can
be a values combination of DFSDM_BreakSignals

16.2

DFSDM Firmware driver API description

16.2.1

How to use this driver

Channel initialization
1.
2.

3.

User has first to initialize channels (before filters initialization).
As prerequisite, fill in the HAL_DFSDM_ChannelMspInit() :
Enable DFSDMz clock interface with __HAL_RCC_DFSDMz_CLK_ENABLE().
Enable the clocks for the DFSDMz GPIOS with
__HAL_RCC_GPIOx_CLK_ENABLE().
Configure these DFSDMz pins in alternate mode using HAL_GPIO_Init().
If interrupt mode is used, enable and configure DFSDMz_FLT0 global interrupt
with HAL_NVIC_SetPriority() and HAL_NVIC_EnableIRQ().
Configure the output clock, input, serial interface, analog watchdog, offset and data
right bit shift parameters for this channel using the HAL_DFSDM_ChannelInit()
function.

Channel clock absence detector
1.
2.
3.
4.
5.
6.

Start clock absence detector using HAL_DFSDM_ChannelCkabStart() or
HAL_DFSDM_ChannelCkabStart_IT().
In polling mode, use HAL_DFSDM_ChannelPollForCkab() to detect the clock
absence.
In interrupt mode, HAL_DFSDM_ChannelCkabCallback() will be called if clock
absence is detected.
Stop clock absence detector using HAL_DFSDM_ChannelCkabStop() or
HAL_DFSDM_ChannelCkabStop_IT().
Please note that the same mode (polling or interrupt) has to be used for all channels
because the channels are sharing the same interrupt.
Please note also that in interrupt mode, if clock absence detector is stopped for one
channel, interrupt will be disabled for all channels.

DocID025834 Rev 4

219/964

HAL DFSDM Generic Driver

UM1725

Channel short circuit detector
1.
2.
3.
4.
5.
6.

Start short circuit detector using HAL_DFSDM_ChannelScdStart() or or
HAL_DFSDM_ChannelScdStart_IT().
In polling mode, use HAL_DFSDM_ChannelPollForScd() to detect short circuit.
In interrupt mode, HAL_DFSDM_ChannelScdCallback() will be called if short circuit is
detected.
Stop short circuit detector using HAL_DFSDM_ChannelScdStop() or or
HAL_DFSDM_ChannelScdStop_IT().
Please note that the same mode (polling or interrupt) has to be used for all channels
because the channels are sharing the same interrupt.
Please note also that in interrupt mode, if short circuit detector is stopped for one
channel, interrupt will be disabled for all channels.

Channel analog watchdog value
1.

Get analog watchdog filter value of a channel using
HAL_DFSDM_ChannelGetAwdValue().

Channel offset value
1.

Modify offset value of a channel using HAL_DFSDM_ChannelModifyOffset().

Filter initialization
1.
2.

3.

After channel initialization, user has to init filters.
As prerequisite, fill in the HAL_DFSDM_FilterMspInit() :
If interrupt mode is used , enable and configure DFSDMz_FLTx global interrupt
with HAL_NVIC_SetPriority() and HAL_NVIC_EnableIRQ(). Please note that
DFSDMz_FLT0 global interrupt could be already enabled if interrupt is used for
channel.
If DMA mode is used, configure DMA with HAL_DMA_Init() and link it with
DFSDMz filter handle using __HAL_LINKDMA().
Configure the regular conversion, injected conversion and filter parameters for this
filter using the HAL_DFSDM_FilterInit() function.

Filter regular channel conversion
1.
2.

3.
4.

220/964

Select regular channel and enable/disable continuous mode using
HAL_DFSDM_FilterConfigRegChannel().
Start regular conversion using HAL_DFSDM_FilterRegularStart(),
HAL_DFSDM_FilterRegularStart_IT(), HAL_DFSDM_FilterRegularStart_DMA() or
HAL_DFSDM_FilterRegularMsbStart_DMA().
In polling mode, use HAL_DFSDM_FilterPollForRegConversion() to detect the end of
regular conversion.
In interrupt mode, HAL_DFSDM_FilterRegConvCpltCallback() will be called at the
end of regular conversion.
DocID025834 Rev 4

UM1725
5.
6.

7.

HAL DFSDM Generic Driver
Get value of regular conversion and corresponding channel using
HAL_DFSDM_FilterGetRegularValue().
In DMA mode, HAL_DFSDM_FilterRegConvHalfCpltCallback() and
HAL_DFSDM_FilterRegConvCpltCallback() will be called respectively at the half
transfer and at the transfer complete. Please note that
HAL_DFSDM_FilterRegConvHalfCpltCallback() will be called only in DMA circular
mode.
Stop regular conversion using HAL_DFSDM_FilterRegularStop(),
HAL_DFSDM_FilterRegularStop_IT() or HAL_DFSDM_FilterRegularStop_DMA().

Filter injected channels conversion
1.
2.

3.
4.
5.
6.

7.

Select injected channels using HAL_DFSDM_FilterConfigInjChannel().
Start injected conversion using HAL_DFSDM_FilterInjectedStart(),
HAL_DFSDM_FilterInjectedStart_IT(), HAL_DFSDM_FilterInjectedStart_DMA() or
HAL_DFSDM_FilterInjectedMsbStart_DMA().
In polling mode, use HAL_DFSDM_FilterPollForInjConversion() to detect the end of
injected conversion.
In interrupt mode, HAL_DFSDM_FilterInjConvCpltCallback() will be called at the end
of injected conversion.
Get value of injected conversion and corresponding channel using
HAL_DFSDM_FilterGetInjectedValue().
In DMA mode, HAL_DFSDM_FilterInjConvHalfCpltCallback() and
HAL_DFSDM_FilterInjConvCpltCallback() will be called respectively at the half
transfer and at the transfer complete. Please note that
HAL_DFSDM_FilterInjConvCpltCallback() will be called only in DMA circular mode.
Stop injected conversion using HAL_DFSDM_FilterInjectedStop(),
HAL_DFSDM_FilterInjectedStop_IT() or HAL_DFSDM_FilterInjectedStop_DMA().

Filter analog watchdog
1.
2.
3.

Start filter analog watchdog using HAL_DFSDM_FilterAwdStart_IT().
HAL_DFSDM_FilterAwdCallback() will be called if analog watchdog occurs.
Stop filter analog watchdog using HAL_DFSDM_FilterAwdStop_IT().

Filter extreme detector
1.
2.
3.
4.

Start filter extreme detector using HAL_DFSDM_FilterExdStart().
Get extreme detector maximum value using HAL_DFSDM_FilterGetExdMaxValue().
Get extreme detector minimum value using HAL_DFSDM_FilterGetExdMinValue().
Start filter extreme detector using HAL_DFSDM_FilterExdStop().

Filter conversion time
1.

16.2.2

Get conversion time value using HAL_DFSDM_FilterGetConvTimeValue().

Channel initialization and de-initialization functions
This section provides functions allowing to:
Initialize the DFSDM channel.
De-initialize the DFSDM channel.
DocID025834 Rev 4

221/964

HAL DFSDM Generic Driver
This section contains the following APIs:
HAL_DFSDM_ChannelInit()
HAL_DFSDM_ChannelDeInit()
HAL_DFSDM_ChannelMspInit()
HAL_DFSDM_ChannelMspDeInit()

16.2.3

Channel operation functions
This section provides functions allowing to:
Manage clock absence detector feature.
Manage short circuit detector feature.
Get analog watchdog value.
Modify offset value.
This section contains the following APIs:
HAL_DFSDM_ChannelCkabStart()
HAL_DFSDM_ChannelPollForCkab()
HAL_DFSDM_ChannelCkabStop()
HAL_DFSDM_ChannelCkabStart_IT()
HAL_DFSDM_ChannelCkabCallback()
HAL_DFSDM_ChannelCkabStop_IT()
HAL_DFSDM_ChannelScdStart()
HAL_DFSDM_ChannelPollForScd()
HAL_DFSDM_ChannelScdStop()
HAL_DFSDM_ChannelScdStart_IT()
HAL_DFSDM_ChannelScdCallback()
HAL_DFSDM_ChannelScdStop_IT()
HAL_DFSDM_ChannelGetAwdValue()
HAL_DFSDM_ChannelModifyOffset()

16.2.4

Channel state function
This section provides function allowing to:
Get channel handle state.
This section contains the following APIs:
HAL_DFSDM_ChannelGetState()

16.2.5

Filter initialization and de-initialization functions
This section provides functions allowing to:
Initialize the DFSDM filter.
De-initialize the DFSDM filter.
This section contains the following APIs:
HAL_DFSDM_FilterInit()
HAL_DFSDM_FilterDeInit()
HAL_DFSDM_FilterMspInit()
HAL_DFSDM_FilterMspDeInit()

222/964

DocID025834 Rev 4

UM1725

UM1725

16.2.6

HAL DFSDM Generic Driver

Filter control functions
This section provides functions allowing to:
Select channel and enable/disable continuous mode for regular conversion.
Select channels for injected conversion.
This section contains the following APIs:
HAL_DFSDM_FilterConfigRegChannel()
HAL_DFSDM_FilterConfigInjChannel()

16.2.7

Filter operation functions
This section provides functions allowing to:
Start conversion of regular/injected channel.
Poll for the end of regular/injected conversion.
Stop conversion of regular/injected channel.
Start conversion of regular/injected channel and enable interrupt.
Call the callback functions at the end of regular/injected conversions.
Stop conversion of regular/injected channel and disable interrupt.
Start conversion of regular/injected channel and enable DMA transfer.
Stop conversion of regular/injected channel and disable DMA transfer.
Start analog watchdog and enable interrupt.
Call the callback function when analog watchdog occurs.
Stop analog watchdog and disable interrupt.
Start extreme detector.
Stop extreme detector.
Get result of regular channel conversion.
Get result of injected channel conversion.
Get extreme detector maximum and minimum values.
Get conversion time.
Handle DFSDM interrupt request.
This section contains the following APIs:
HAL_DFSDM_FilterRegularStart()
HAL_DFSDM_FilterPollForRegConversion()
HAL_DFSDM_FilterRegularStop()
HAL_DFSDM_FilterRegularStart_IT()
HAL_DFSDM_FilterRegularStop_IT()
HAL_DFSDM_FilterRegularStart_DMA()
HAL_DFSDM_FilterRegularMsbStart_DMA()
HAL_DFSDM_FilterRegularStop_DMA()
HAL_DFSDM_FilterGetRegularValue()
HAL_DFSDM_FilterInjectedStart()
HAL_DFSDM_FilterPollForInjConversion()
HAL_DFSDM_FilterInjectedStop()
HAL_DFSDM_FilterInjectedStart_IT()
HAL_DFSDM_FilterInjectedStop_IT()
HAL_DFSDM_FilterInjectedStart_DMA()
HAL_DFSDM_FilterInjectedMsbStart_DMA()
HAL_DFSDM_FilterInjectedStop_DMA()
HAL_DFSDM_FilterGetInjectedValue()
DocID025834 Rev 4

223/964

HAL DFSDM Generic Driver

UM1725

HAL_DFSDM_FilterAwdStart_IT()
HAL_DFSDM_FilterAwdStop_IT()
HAL_DFSDM_FilterExdStart()
HAL_DFSDM_FilterExdStop()
HAL_DFSDM_FilterGetExdMaxValue()
HAL_DFSDM_FilterGetExdMinValue()
HAL_DFSDM_FilterGetConvTimeValue()
HAL_DFSDM_IRQHandler()
HAL_DFSDM_FilterRegConvCpltCallback()
HAL_DFSDM_FilterRegConvHalfCpltCallback()
HAL_DFSDM_FilterInjConvCpltCallback()
HAL_DFSDM_FilterInjConvHalfCpltCallback()
HAL_DFSDM_FilterAwdCallback()
HAL_DFSDM_FilterErrorCallback()

16.2.8

Filter state functions
This section provides functions allowing to:
Get the DFSDM filter state.
Get the DFSDM filter error.
This section contains the following APIs:
HAL_DFSDM_FilterGetState()
HAL_DFSDM_FilterGetError()

16.2.9

Detailed description of functions
HAL_DFSDM_ChannelInit
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelInit
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

Initialize the DFSDM channel according to the specified
parameters in the DFSDM_ChannelInitTypeDef structure and
initialize the associated handle.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

HAL: status.

HAL_DFSDM_ChannelDeInit
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelDeInit
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

De-initialize the DFSDM channel.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

HAL: status.

HAL_DFSDM_ChannelMspInit

224/964

Function Name

void HAL_DFSDM_ChannelMspInit
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

Initialize the DFSDM channel MSP.
DocID025834 Rev 4

UM1725

HAL DFSDM Generic Driver
Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

None

HAL_DFSDM_ChannelMspDeInit
Function Name

void HAL_DFSDM_ChannelMspDeInit
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

De-initialize the DFSDM channel MSP.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

None

HAL_DFSDM_ChannelCkabStart
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelCkabStart
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

This function allows to start clock absence detection in polling
mode.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

HAL: status

Notes

Same mode has to be used for all channels.
If clock is not available on this channel during 5 seconds,
clock absence detection will not be activated and function will
return HAL_TIMEOUT error.

HAL_DFSDM_ChannelCkabStart_IT
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelCkabStart_IT
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

This function allows to start clock absence detection in interrupt
mode.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

HAL: status

Notes

Same mode has to be used for all channels.
If clock is not available on this channel during 5 seconds,
clock absence detection will not be activated and function will
return HAL_TIMEOUT error.

HAL_DFSDM_ChannelCkabStop
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelCkabStop
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

This function allows to stop clock absence detection in polling
mode.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

HAL: status

DocID025834 Rev 4

225/964

HAL DFSDM Generic Driver

UM1725

HAL_DFSDM_ChannelCkabStop_IT
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelCkabStop_IT
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

This function allows to stop clock absence detection in interrupt
mode.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

HAL: status

Notes

Interrupt will be disabled for all channels

HAL_DFSDM_ChannelScdStart
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelScdStart
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel, uint32_t
Threshold, uint32_t BreakSignal)

Function Description

This function allows to start short circuit detection in polling mode.

Parameters

hdfsdm_channel: : DFSDM channel handle.
Threshold: : Short circuit detector threshold. This parameter
must be a number between Min_Data = 0 and Max_Data =
255.
BreakSignal: : Break signals assigned to short circuit event.
This parameter can be a values combination of DFSDM break
signals.

Return values

HAL: status

Notes

Same mode has to be used for all channels

HAL_DFSDM_ChannelScdStart_IT
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelScdStart_IT
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel, uint32_t
Threshold, uint32_t BreakSignal)

Function Description

This function allows to start short circuit detection in interrupt
mode.

Parameters

hdfsdm_channel: : DFSDM channel handle.
Threshold: : Short circuit detector threshold. This parameter
must be a number between Min_Data = 0 and Max_Data =
255.
BreakSignal: : Break signals assigned to short circuit event.
This parameter can be a values combination of DFSDM break
signals.

Return values

HAL: status

Notes

Same mode has to be used for all channels

HAL_DFSDM_ChannelScdStop
Function Name

226/964

HAL_StatusTypeDef HAL_DFSDM_ChannelScdStop
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

DocID025834 Rev 4

UM1725
Function Description

HAL DFSDM Generic Driver
This function allows to stop short circuit detection in polling mode.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

HAL: status

HAL_DFSDM_ChannelScdStop_IT
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelScdStop_IT
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

This function allows to stop short circuit detection in interrupt
mode.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

HAL: status

Notes

Interrupt will be disabled for all channels

HAL_DFSDM_ChannelGetAwdValue
Function Name

int16_t HAL_DFSDM_ChannelGetAwdValue
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

This function allows to get channel analog watchdog value.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

Channel: analog watchdog value.

HAL_DFSDM_ChannelModifyOffset
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelModifyOffset
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel, int32_t
Offset)

Function Description

This function allows to modify channel offset value.

Parameters

hdfsdm_channel: : DFSDM channel handle.
Offset: : DFSDM channel offset. This parameter must be a
number between Min_Data = -8388608 and Max_Data =
8388607.

Return values

HAL: status.

HAL_DFSDM_ChannelPollForCkab
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelPollForCkab
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel, uint32_t
Timeout)

Function Description

This function allows to poll for the clock absence detection.

Parameters

hdfsdm_channel: : DFSDM channel handle.
Timeout: : Timeout value in milliseconds.

Return values

HAL: status

DocID025834 Rev 4

227/964

HAL DFSDM Generic Driver

UM1725

HAL_DFSDM_ChannelPollForScd
Function Name

HAL_StatusTypeDef HAL_DFSDM_ChannelPollForScd
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel, uint32_t
Timeout)

Function Description

This function allows to poll for the short circuit detection.

Parameters

hdfsdm_channel: : DFSDM channel handle.
Timeout: : Timeout value in milliseconds.

Return values

HAL: status

HAL_DFSDM_ChannelCkabCallback
Function Name

void HAL_DFSDM_ChannelCkabCallback
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

Clock absence detection callback.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

None

HAL_DFSDM_ChannelScdCallback
Function Name

void HAL_DFSDM_ChannelScdCallback
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

Short circuit detection callback.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

None

HAL_DFSDM_ChannelGetState
Function Name

HAL_DFSDM_Channel_StateTypeDef
HAL_DFSDM_ChannelGetState
(DFSDM_Channel_HandleTypeDef * hdfsdm_channel)

Function Description

This function allows to get the current DFSDM channel handle
state.

Parameters

hdfsdm_channel: : DFSDM channel handle.

Return values

DFSDM: channel state.

HAL_DFSDM_FilterInit

228/964

Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterInit
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

Initialize the DFSDM filter according to the specified parameters in
the DFSDM_FilterInitTypeDef structure and initialize the
associated handle.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status.

DocID025834 Rev 4

UM1725

HAL DFSDM Generic Driver

HAL_DFSDM_FilterDeInit
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterDeInit
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

De-initializes the DFSDM filter.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status.

HAL_DFSDM_FilterMspInit
Function Name

void HAL_DFSDM_FilterMspInit
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

Initializes the DFSDM filter MSP.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

None

HAL_DFSDM_FilterMspDeInit
Function Name

void HAL_DFSDM_FilterMspDeInit
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

De-initializes the DFSDM filter MSP.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

None

HAL_DFSDM_FilterConfigRegChannel
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterConfigRegChannel
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, uint32_t
Channel, uint32_t ContinuousMode)

Function Description

This function allows to select channel and to enable/disable
continuous mode for regular conversion.

Parameters

hdfsdm_filter: : DFSDM filter handle.
Channel: : Channel for regular conversion. This parameter
can be a value of DFSDM Channel Selection.
ContinuousMode: : Enable/disable continuous mode for
regular conversion. This parameter can be a value of DFSDM
Continuous Mode.

Return values

HAL: status

HAL_DFSDM_FilterConfigInjChannel
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterConfigInjChannel
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, uint32_t
Channel)

Function Description

This function allows to select channels for injected conversion.

Parameters

hdfsdm_filter: : DFSDM filter handle.
Channel: : Channels for injected conversion. This parameter
DocID025834 Rev 4

229/964

HAL DFSDM Generic Driver
Return values

UM1725
can be a values combination of DFSDM Channel Selection.
HAL: status

HAL_DFSDM_FilterRegularStart
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterRegularStart
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to start regular conversion in polling mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

Notes

This function should be called only when DFSDM filter
instance is in idle state or if injected conversion is ongoing.

HAL_DFSDM_FilterRegularStart_IT
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterRegularStart_IT
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to start regular conversion in interrupt mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

Notes

This function should be called only when DFSDM filter
instance is in idle state or if injected conversion is ongoing.

HAL_DFSDM_FilterRegularStart_DMA
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterRegularStart_DMA
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, int32_t *
pData, uint32_t Length)

Function Description

This function allows to start regular conversion in DMA mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.
pData: : The destination buffer address.
Length: : The length of data to be transferred from DFSDM
filter to memory.

Return values

HAL: status

Notes

This function should be called only when DFSDM filter
instance is in idle state or if injected conversion is ongoing.
Please note that data on buffer will contain signed regular
conversion value on 24 most significant bits and
corresponding channel on 3 least significant bits.

HAL_DFSDM_FilterRegularMsbStart_DMA
Function Name

230/964

HAL_StatusTypeDef
HAL_DFSDM_FilterRegularMsbStart_DMA
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, int16_t *
pData, uint32_t Length)

DocID025834 Rev 4

UM1725
Function Description

HAL DFSDM Generic Driver
This function allows to start regular conversion in DMA mode and
to get only the 16 most significant bits of conversion.

Parameters

hdfsdm_filter: : DFSDM filter handle.
pData: : The destination buffer address.
Length: : The length of data to be transferred from DFSDM
filter to memory.

Return values

HAL: status

Notes

This function should be called only when DFSDM filter
instance is in idle state or if injected conversion is ongoing.
Please note that data on buffer will contain signed 16 most
significant bits of regular conversion.

HAL_DFSDM_FilterRegularStop
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterRegularStop
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to stop regular conversion in polling mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

Notes

This function should be called only if regular conversion is
ongoing.

HAL_DFSDM_FilterRegularStop_IT
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterRegularStop_IT
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to stop regular conversion in interrupt mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

Notes

This function should be called only if regular conversion is
ongoing.

HAL_DFSDM_FilterRegularStop_DMA
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterRegularStop_DMA
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to stop regular conversion in DMA mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

Notes

This function should be called only if regular conversion is
ongoing.

HAL_DFSDM_FilterInjectedStart
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterInjectedStart
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)
DocID025834 Rev 4

231/964

HAL DFSDM Generic Driver
Function Description

UM1725
This function allows to start injected conversion in polling mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

Notes

This function should be called only when DFSDM filter
instance is in idle state or if regular conversion is ongoing.

HAL_DFSDM_FilterInjectedStart_IT
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterInjectedStart_IT
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to start injected conversion in interrupt mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

Notes

This function should be called only when DFSDM filter
instance is in idle state or if regular conversion is ongoing.

HAL_DFSDM_FilterInjectedStart_DMA
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterInjectedStart_DMA
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, int32_t *
pData, uint32_t Length)

Function Description

This function allows to start injected conversion in DMA mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.
pData: : The destination buffer address.
Length: : The length of data to be transferred from DFSDM
filter to memory.

Return values

HAL: status

Notes

This function should be called only when DFSDM filter
instance is in idle state or if regular conversion is ongoing.
Please note that data on buffer will contain signed injected
conversion value on 24 most significant bits and
corresponding channel on 3 least significant bits.

HAL_DFSDM_FilterInjectedMsbStart_DMA

232/964

Function Name

HAL_StatusTypeDef
HAL_DFSDM_FilterInjectedMsbStart_DMA
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, int16_t *
pData, uint32_t Length)

Function Description

This function allows to start injected conversion in DMA mode and
to get only the 16 most significant bits of conversion.

Parameters

hdfsdm_filter: : DFSDM filter handle.
pData: : The destination buffer address.
Length: : The length of data to be transferred from DFSDM
filter to memory.

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL DFSDM Generic Driver
Notes

This function should be called only when DFSDM filter
instance is in idle state or if regular conversion is ongoing.
Please note that data on buffer will contain signed 16 most
significant bits of injected conversion.

HAL_DFSDM_FilterInjectedStop
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterInjectedStop
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to stop injected conversion in polling mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

Notes

This function should be called only if injected conversion is
ongoing.

HAL_DFSDM_FilterInjectedStop_IT
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterInjectedStop_IT
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to stop injected conversion in interrupt mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

Notes

This function should be called only if injected conversion is
ongoing.

HAL_DFSDM_FilterInjectedStop_DMA
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterInjectedStop_DMA
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to stop injected conversion in DMA mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

Notes

This function should be called only if injected conversion is
ongoing.

HAL_DFSDM_FilterAwdStart_IT
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterAwdStart_IT
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter,
DFSDM_Filter_AwdParamTypeDef * awdParam)

Function Description

This function allows to start filter analog watchdog in interrupt
mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.
awdParam: : DFSDM filter analog watchdog parameters.

Return values

HAL: status

DocID025834 Rev 4

233/964

HAL DFSDM Generic Driver

UM1725

HAL_DFSDM_FilterAwdStop_IT
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterAwdStop_IT
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to stop filter analog watchdog in interrupt
mode.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

HAL_DFSDM_FilterExdStart
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterExdStart
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, uint32_t
Channel)

Function Description

This function allows to start extreme detector feature.

Parameters

hdfsdm_filter: : DFSDM filter handle.
Channel: : Channels where extreme detector is enabled.
This parameter can be a values combination of DFSDM
Channel Selection.

Return values

HAL: status

HAL_DFSDM_FilterExdStop
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterExdStop
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to stop extreme detector feature.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

HAL: status

HAL_DFSDM_FilterGetRegularValue
Function Name

int32_t HAL_DFSDM_FilterGetRegularValue
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, uint32_t *
Channel)

Function Description

This function allows to get regular conversion value.

Parameters

hdfsdm_filter: : DFSDM filter handle.
Channel: : Corresponding channel of regular conversion.

Return values

Regular: conversion value

HAL_DFSDM_FilterGetInjectedValue
Function Name

int32_t HAL_DFSDM_FilterGetInjectedValue
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, uint32_t *
Channel)

Function Description

This function allows to get injected conversion value.

Parameters

234/964

hdfsdm_filter: : DFSDM filter handle.
Channel: : Corresponding channel of injected conversion.
DocID025834 Rev 4

UM1725

HAL DFSDM Generic Driver
Return values

Injected: conversion value

HAL_DFSDM_FilterGetExdMaxValue
Function Name

int32_t HAL_DFSDM_FilterGetExdMaxValue
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, uint32_t *
Channel)

Function Description

This function allows to get extreme detector maximum value.

Parameters

hdfsdm_filter: : DFSDM filter handle.
Channel: : Corresponding channel.

Return values

Extreme: detector maximum value This value is between
Min_Data = -8388608 and Max_Data = 8388607.

HAL_DFSDM_FilterGetExdMinValue
Function Name

int32_t HAL_DFSDM_FilterGetExdMinValue
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, uint32_t *
Channel)

Function Description

This function allows to get extreme detector minimum value.

Parameters

hdfsdm_filter: : DFSDM filter handle.
Channel: : Corresponding channel.

Return values

Extreme: detector minimum value This value is between
Min_Data = -8388608 and Max_Data = 8388607.

HAL_DFSDM_FilterGetConvTimeValue
Function Name

uint32_t HAL_DFSDM_FilterGetConvTimeValue
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to get conversion time value.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

Conversion: time value

Notes

To get time in second, this value has to be divided by DFSDM
clock frequency.

HAL_DFSDM_IRQHandler
Function Name

void HAL_DFSDM_IRQHandler (DFSDM_Filter_HandleTypeDef
* hdfsdm_filter)

Function Description

This function handles the DFSDM interrupts.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

None

HAL_DFSDM_FilterPollForRegConversion
Function Name

HAL_StatusTypeDef
HAL_DFSDM_FilterPollForRegConversion
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, uint32_t
DocID025834 Rev 4

235/964

HAL DFSDM Generic Driver

UM1725
Timeout)

Function Description

This function allows to poll for the end of regular conversion.

Parameters

hdfsdm_filter: : DFSDM filter handle.
Timeout: : Timeout value in milliseconds.

Return values

HAL: status

Notes

This function should be called only if regular conversion is
ongoing.

HAL_DFSDM_FilterPollForInjConversion
Function Name

HAL_StatusTypeDef HAL_DFSDM_FilterPollForInjConversion
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, uint32_t
Timeout)

Function Description

This function allows to poll for the end of injected conversion.

Parameters

hdfsdm_filter: : DFSDM filter handle.
Timeout: : Timeout value in milliseconds.

Return values

HAL: status

Notes

This function should be called only if injected conversion is
ongoing.

HAL_DFSDM_FilterRegConvCpltCallback
Function Name

void HAL_DFSDM_FilterRegConvCpltCallback
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

Regular conversion complete callback.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

None

Notes

In interrupt mode, user has to read conversion value in this
function using HAL_DFSDM_FilterGetRegularValue.

HAL_DFSDM_FilterRegConvHalfCpltCallback
Function Name

void HAL_DFSDM_FilterRegConvHalfCpltCallback
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

Half regular conversion complete callback.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

None

HAL_DFSDM_FilterInjConvCpltCallback
Function Name

void HAL_DFSDM_FilterInjConvCpltCallback
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

Injected conversion complete callback.

Parameters

236/964

hdfsdm_filter: : DFSDM filter handle.

DocID025834 Rev 4

UM1725

HAL DFSDM Generic Driver
Return values

None

Notes

In interrupt mode, user has to read conversion value in this
function using HAL_DFSDM_FilterGetInjectedValue.

HAL_DFSDM_FilterInjConvHalfCpltCallback
Function Name

void HAL_DFSDM_FilterInjConvHalfCpltCallback
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

Half injected conversion complete callback.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

None

HAL_DFSDM_FilterAwdCallback
Function Name

void HAL_DFSDM_FilterAwdCallback
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter, uint32_t
Channel, uint32_t Threshold)

Function Description

Filter analog watchdog callback.

Parameters

hdfsdm_filter: : DFSDM filter handle.
Channel: : Corresponding channel.
Threshold: : Low or high threshold has been reached.

Return values

None

HAL_DFSDM_FilterErrorCallback
Function Name

void HAL_DFSDM_FilterErrorCallback
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

Error callback.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

None

HAL_DFSDM_FilterGetState
Function Name

HAL_DFSDM_Filter_StateTypeDef
HAL_DFSDM_FilterGetState (DFSDM_Filter_HandleTypeDef *
hdfsdm_filter)

Function Description

This function allows to get the current DFSDM filter handle state.

Parameters

hdfsdm_filter: : DFSDM filter handle.

Return values

DFSDM: filter state.

HAL_DFSDM_FilterGetError
Function Name

uint32_t HAL_DFSDM_FilterGetError
(DFSDM_Filter_HandleTypeDef * hdfsdm_filter)

Function Description

This function allows to get the current DFSDM filter error.

DocID025834 Rev 4

237/964

HAL DFSDM Generic Driver
Parameters
Return values

UM1725
hdfsdm_filter: : DFSDM filter handle.
DFSDM: filter error code.

16.3

DFSDM Firmware driver defines

16.3.1

DFSDM
DFSDM analog watchdog threshold
DFSDM_AWD_HIGH_THRESHOLD

Analog watchdog high threshold

DFSDM_AWD_LOW_THRESHOLD

Analog watchdog low threshold

DFSDM break signals
DFSDM_NO_BREAK_SIGNAL

No break signal

DFSDM_BREAK_SIGNAL_0

Break signal 0

DFSDM_BREAK_SIGNAL_1

Break signal 1

DFSDM_BREAK_SIGNAL_2

Break signal 2

DFSDM_BREAK_SIGNAL_3

Break signal 3

DFSDM channel analog watchdog filter order
DFSDM_CHANNEL_FASTSINC_ORDER

FastSinc filter type

DFSDM_CHANNEL_SINC1_ORDER

Sinc 1 filter type

DFSDM_CHANNEL_SINC2_ORDER

Sinc 2 filter type

DFSDM_CHANNEL_SINC3_ORDER

Sinc 3 filter type

DFSDM channel input data packing
DFSDM_CHANNEL_STANDARD_MODE

Standard data packing mode

DFSDM_CHANNEL_INTERLEAVED_MODE

Interleaved data packing mode

DFSDM_CHANNEL_DUAL_MODE

Dual data packing mode

DFSDM channel input multiplexer
DFSDM_CHANNEL_EXTERNAL_INPUTS

Data are taken from external inputs

DFSDM_CHANNEL_INTERNAL_REGISTER

Data are taken from internal register

DFSDM channel input pins
DFSDM_CHANNEL_SAME_CHANNEL_PINS

Input from pins on same channel

DFSDM_CHANNEL_FOLLOWING_CHANNEL_PINS

Input from pins on following
channel

DFSDM channel output clock selection
DFSDM_CHANNEL_OUTPUT_CLOCK_SYSTEM

Source for ouput clock is system clock

DFSDM_CHANNEL_OUTPUT_CLOCK_AUDIO

Source for ouput clock is audio clock

DFSDM Channel Selection
DFSDM_CHANNEL_0
DFSDM_CHANNEL_1

238/964

DocID025834 Rev 4

UM1725

HAL DFSDM Generic Driver
DFSDM_CHANNEL_2
DFSDM_CHANNEL_3
DFSDM channel serial interface type
DFSDM_CHANNEL_SPI_RISING

SPI with rising edge

DFSDM_CHANNEL_SPI_FALLING

SPI with falling edge

DFSDM_CHANNEL_MANCHESTER_RISING

Manchester with rising edge

DFSDM_CHANNEL_MANCHESTER_FALLING

Manchester with falling edge

DFSDM channel SPI clock selection
DFSDM_CHANNEL_SPI_CLOCK_EXTERNAL

External SPI clock

DFSDM_CHANNEL_SPI_CLOCK_INTERNAL

Internal SPI clock

DFSDM_CHANNEL_SPI_CLOCK_INTERNAL_DIV2_FALLING

Internal SPI clock divided
by 2, falling edge

DFSDM_CHANNEL_SPI_CLOCK_INTERNAL_DIV2_RISING

Internal SPI clock divided
by 2, rising edge

DFSDM Continuous Mode
DFSDM_CONTINUOUS_CONV_OFF

Conversion are not continuous

DFSDM_CONTINUOUS_CONV_ON

Conversion are continuous

DFSDM Exported Macros
__HAL_DFSDM_CHANNEL_RESET_HANDLE_STATE

Description:
Reset DFSDM channel
handle state.
Parameters:
__HANDLE__: DFSDM
channel handle.
Return value:
None

__HAL_DFSDM_FILTER_RESET_HANDLE_STATE

Description:
Reset DFSDM filter handle
state.
Parameters:
__HANDLE__: DFSDM
filter handle.
Return value:
None

DFSDM filter analog watchdog data source
DFSDM_FILTER_AWD_FILTER_DATA

From digital filter

DFSDM_FILTER_AWD_CHANNEL_DATA

From analog watchdog channel

DFSDM filter error code

DocID025834 Rev 4

239/964

HAL DFSDM Generic Driver
DFSDM_FILTER_ERROR_NONE

UM1725
No error

DFSDM_FILTER_ERROR_REGULAR_OVERRUN

Overrun occurs during regular
conversion

DFSDM_FILTER_ERROR_INJECTED_OVERRUN

Overrun occurs during injected
conversion

DFSDM_FILTER_ERROR_DMA

DMA error occurs

DFSDM filter external trigger
DFSDM_FILTER_EXT_TRIG_TIM1_TRGO

For DFSDM filter 0 and 1

DFSDM_FILTER_EXT_TRIG_TIM3_TRGO

For DFSDM filter 0 and 1

DFSDM_FILTER_EXT_TRIG_TIM8_TRGO

For DFSDM filter 0 and 1

DFSDM_FILTER_EXT_TRIG_TIM10_OC1

For DFSDM filter 0 and 1

DFSDM_FILTER_EXT_TRIG_TIM4_TRGO

For DFSDM filter 0 and 1

DFSDM_FILTER_EXT_TRIG_TIM6_TRGO

For DFSDM filter 0 and 1

DFSDM_FILTER_EXT_TRIG_EXTI11

For DFSDM filter 0 and 1

DFSDM_FILTER_EXT_TRIG_EXTI15

For DFSDM filter 0 and 1

DFSDM filter external trigger edge
DFSDM_FILTER_EXT_TRIG_RISING_EDGE

External rising edge

DFSDM_FILTER_EXT_TRIG_FALLING_EDGE

External falling edge

DFSDM_FILTER_EXT_TRIG_BOTH_EDGES

External rising and falling edges

DFSDM filter sinc order
DFSDM_FILTER_FASTSINC_ORDER

FastSinc filter type

DFSDM_FILTER_SINC1_ORDER

Sinc 1 filter type

DFSDM_FILTER_SINC2_ORDER

Sinc 2 filter type

DFSDM_FILTER_SINC3_ORDER

Sinc 3 filter type

DFSDM_FILTER_SINC4_ORDER

Sinc 4 filter type

DFSDM_FILTER_SINC5_ORDER

Sinc 5 filter type

DFSDM filter conversion trigger

240/964

DFSDM_FILTER_SW_TRIGGER

Software trigger

DFSDM_FILTER_SYNC_TRIGGER

Synchronous with DFSDM_FLT0

DFSDM_FILTER_EXT_TRIGGER

External trigger (only for injected conversion)

DocID025834 Rev 4

UM1725

HAL DMA2D Generic Driver

17

HAL DMA2D Generic Driver

17.1

DMA2D Firmware driver registers structures

17.1.1

DMA2D_ColorTypeDef
Data Fields
uint32_t Blue
uint32_t Green
uint32_t Red

Field Documentation
uint32_t DMA2D_ColorTypeDef::Blue
Configures the blue value. This parameter must be a number between Min_Data =
0x00 and Max_Data = 0xFF.
uint32_t DMA2D_ColorTypeDef::Green
Configures the green value. This parameter must be a number between Min_Data =
0x00 and Max_Data = 0xFF.
uint32_t DMA2D_ColorTypeDef::Red
Configures the red value. This parameter must be a number between Min_Data =
0x00 and Max_Data = 0xFF.

17.1.2

DMA2D_CLUTCfgTypeDef
Data Fields
uint32_t * pCLUT
uint32_t CLUTColorMode
uint32_t Size

Field Documentation
uint32_t* DMA2D_CLUTCfgTypeDef::pCLUT
Configures the DMA2D CLUT memory address.
uint32_t DMA2D_CLUTCfgTypeDef::CLUTColorMode
Configures the DMA2D CLUT color mode. This parameter can be one value of
DMA2D_CLUT_CM.
uint32_t DMA2D_CLUTCfgTypeDef::Size
Configures the DMA2D CLUT size. This parameter must be a number between
Min_Data = 0x00 and Max_Data = 0xFF.

DocID025834 Rev 4

241/964

HAL DMA2D Generic Driver

17.1.3

UM1725

DMA2D_InitTypeDef
Data Fields
uint32_t Mode
uint32_t ColorMode
uint32_t OutputOffset

Field Documentation
uint32_t DMA2D_InitTypeDef::Mode
Configures the DMA2D transfer mode. This parameter can be one value of
DMA2D_Mode.
uint32_t DMA2D_InitTypeDef::ColorMode
Configures the color format of the output image. This parameter can be one value of
DMA2D_Output_Color_Mode.
uint32_t DMA2D_InitTypeDef::OutputOffset
Specifies the Offset value. This parameter must be a number between Min_Data =
0x0000 and Max_Data = 0x3FFF.

17.1.4

DMA2D_LayerCfgTypeDef
Data Fields
uint32_t InputOffset
uint32_t InputColorMode
uint32_t AlphaMode
uint32_t InputAlpha

Field Documentation
uint32_t DMA2D_LayerCfgTypeDef::InputOffset
Configures the DMA2D foreground or background offset. This parameter must be a
number between Min_Data = 0x0000 and Max_Data = 0x3FFF.
uint32_t DMA2D_LayerCfgTypeDef::InputColorMode
Configures the DMA2D foreground or background color mode. This parameter can be
one value of DMA2D_Input_Color_Mode.
uint32_t DMA2D_LayerCfgTypeDef::AlphaMode
Configures the DMA2D foreground or background alpha mode. This parameter can
be one value of DMA2D_Alpha_Mode.
uint32_t DMA2D_LayerCfgTypeDef::InputAlpha
Specifies the DMA2D foreground or background alpha value and color value in case
of A8 or A4 color mode. This parameter must be a number between Min_Data = 0x00
and Max_Data = 0xFF except for the color modes detailed below.
Note:In case of A8 or A4 color mode (ARGB), this parameter must be a number
between Min_Data = 0x00000000 and Max_Data = 0xFFFFFFFF
whereInputAlpha[24:31] is the alpha value ALPHA[0:7]InputAlpha[16:23] is the red
value RED[0:7]InputAlpha[8:15] is the green value GREEN[0:7]InputAlpha[0:7] is the
blue value BLUE[0:7].
242/964

DocID025834 Rev 4

UM1725

17.1.5

HAL DMA2D Generic Driver

__DMA2D_HandleTypeDef
Data Fields
DMA2D_TypeDef * Instance
DMA2D_InitTypeDef Init
void(* XferCpltCallback
void(* XferErrorCallback
DMA2D_LayerCfgTypeDef LayerCfg
HAL_LockTypeDef Lock
__IO HAL_DMA2D_StateTypeDef State
__IO uint32_t ErrorCode

Field Documentation
DMA2D_TypeDef* __DMA2D_HandleTypeDef::Instance
DMA2D register base address.
DMA2D_InitTypeDef __DMA2D_HandleTypeDef::Init
DMA2D communication parameters.
void(* __DMA2D_HandleTypeDef::XferCpltCallback)(struct
__DMA2D_HandleTypeDef *hdma2d)
DMA2D transfer complete callback.
void(* __DMA2D_HandleTypeDef::XferErrorCallback)(struct
__DMA2D_HandleTypeDef *hdma2d)
DMA2D transfer error callback.
DMA2D_LayerCfgTypeDef
__DMA2D_HandleTypeDef::LayerCfg[MAX_DMA2D_LAYER]
DMA2D Layers parameters
HAL_LockTypeDef __DMA2D_HandleTypeDef::Lock
DMA2D lock.
__IO HAL_DMA2D_StateTypeDef __DMA2D_HandleTypeDef::State
DMA2D transfer state.
__IO uint32_t __DMA2D_HandleTypeDef::ErrorCode
DMA2D error code.

17.2

DMA2D Firmware driver API description

17.2.1

How to use this driver
1.
2.

Program the required configuration through the following parameters: the transfer
mode, the output color mode and the output offset using HAL_DMA2D_Init() function.
Program the required configuration through the following parameters: the input color
mode, the input color, the input alpha value, the alpha mode, and the input offset
using HAL_DMA2D_ConfigLayer() function for foreground or/and background layer.

DocID025834 Rev 4

243/964

HAL DMA2D Generic Driver

UM1725

Polling mode IO operation
1.
2.

Configure pdata parameter (explained hereafter), destination and data length and
enable the transfer using HAL_DMA2D_Start().
Wait for end of transfer using HAL_DMA2D_PollForTransfer(), at this stage user can
specify the value of timeout according to his end application.

Interrupt mode IO operation
1.

Configure pdata parameter, destination and data length and enable the transfer using
HAL_DMA2D_Start_IT().
2.
Use HAL_DMA2D_IRQHandler() called under DMA2D_IRQHandler() interrupt
subroutine
3.
At the end of data transfer HAL_DMA2D_IRQHandler() function is executed and user
can add his own function by customization of function pointer XferCpltCallback
(member of DMA2D handle structure).
4.
In case of error, the HAL_DMA2D_IRQHandler() function will call the callback
XferErrorCallback. In Register-to-Memory transfer mode, pdata parameter is the
register color, in Memory-to-memory or Memory-to-Memory with pixel format
conversion pdata is the source address. Configure the foreground source address,
the background source address, the destination and data length then Enable the
transfer using HAL_DMA2D_BlendingStart() in polling mode and
HAL_DMA2D_BlendingStart_IT() in interrupt mode HAL_DMA2D_BlendingStart() and
HAL_DMA2D_BlendingStart_IT() functions are used if the memory to memory with
blending transfer mode is selected.
5.
Optionally, configure and enable the CLUT using HAL_DMA2D_CLUTLoad() in
polling mode or HAL_DMA2D_CLUTLoad_IT() in interrupt mode.
6.
Optionally, configure the line watermark in using the API
HAL_DMA2D_ProgramLineEvent()
7.
Optionally, configure the dead time value in the AHB clock cycle inserted between
two consecutive accesses on the AHB master port in using the API
HAL_DMA2D_ConfigDeadTime() and enable/disable the functionality with the APIs
HAL_DMA2D_EnableDeadTime() or HAL_DMA2D_DisableDeadTime().
8.
The transfer can be suspended, resumed and aborted using the following functions:
HAL_DMA2D_Suspend(), HAL_DMA2D_Resume(), HAL_DMA2D_Abort().
9.
The CLUT loading can be suspended, resumed and aborted using the following
functions: HAL_DMA2D_CLUTLoading_Suspend(),
HAL_DMA2D_CLUTLoading_Resume(), HAL_DMA2D_CLUTLoading_Abort().
10. To control the DMA2D state, use the following function: HAL_DMA2D_GetState().
11. To read the DMA2D error code, use the following function: HAL_DMA2D_GetError().

DMA2D HAL driver macros list
Below the list of most used macros in DMA2D HAL driver :
__HAL_DMA2D_ENABLE: Enable the DMA2D peripheral.
__HAL_DMA2D_GET_FLAG: Get the DMA2D pending flags.
__HAL_DMA2D_CLEAR_FLAG: Clear the DMA2D pending flags.
__HAL_DMA2D_ENABLE_IT: Enable the specified DMA2D interrupts.
__HAL_DMA2D_DISABLE_IT: Disable the specified DMA2D interrupts.
__HAL_DMA2D_GET_IT_SOURCE: Check whether the specified DMA2D interrupt is
enabled or not
244/964

DocID025834 Rev 4

UM1725

HAL DMA2D Generic Driver
You can refer to the DMA2D HAL driver header file for more useful macros

17.2.2

Initialization and Configuration functions
This section provides functions allowing to:
Initialize and configure the DMA2D
De-initialize the DMA2D
This section contains the following APIs:
HAL_DMA2D_Init()
HAL_DMA2D_DeInit()
HAL_DMA2D_MspInit()
HAL_DMA2D_MspDeInit()

17.2.3

IO operation functions
This section provides functions allowing to:
Configure the pdata, destination address and data size then start the DMA2D
transfer.
Configure the source for foreground and background, destination address and data
size then start a MultiBuffer DMA2D transfer.
Configure the pdata, destination address and data size then start the DMA2D transfer
with interrupt.
Configure the source for foreground and background, destination address and data
size then start a MultiBuffer DMA2D transfer with interrupt.
Abort DMA2D transfer.
Suspend DMA2D transfer.
Resume DMA2D transfer.
Enable CLUT transfer.
Configure CLUT loading then start transfer in polling mode.
Configure CLUT loading then start transfer in interrupt mode.
Abort DMA2D CLUT loading.
Suspend DMA2D CLUT loading.
Resume DMA2D CLUT loading.
Poll for transfer complete.
handle DMA2D interrupt request.
Transfer watermark callback.
CLUT Transfer Complete callback.
This section contains the following APIs:
HAL_DMA2D_Start()
HAL_DMA2D_Start_IT()
HAL_DMA2D_BlendingStart()
HAL_DMA2D_BlendingStart_IT()
HAL_DMA2D_Abort()
HAL_DMA2D_Suspend()
HAL_DMA2D_Resume()
HAL_DMA2D_EnableCLUT()
HAL_DMA2D_CLUTLoad()
DocID025834 Rev 4

245/964

HAL DMA2D Generic Driver

UM1725

HAL_DMA2D_CLUTLoad_IT()
HAL_DMA2D_CLUTLoading_Abort()
HAL_DMA2D_CLUTLoading_Suspend()
HAL_DMA2D_CLUTLoading_Resume()
HAL_DMA2D_PollForTransfer()
HAL_DMA2D_IRQHandler()
HAL_DMA2D_LineEventCallback()
HAL_DMA2D_CLUTLoadingCpltCallback()

17.2.4

Peripheral Control functions
This section provides functions allowing to:
Configure the DMA2D foreground or background layer parameters.
Configure the DMA2D CLUT transfer.
Configure the line watermark
Configure the dead time value.
Enable or disable the dead time value functionality.
This section contains the following APIs:
HAL_DMA2D_ConfigLayer()
HAL_DMA2D_ConfigCLUT()
HAL_DMA2D_ProgramLineEvent()
HAL_DMA2D_EnableDeadTime()
HAL_DMA2D_DisableDeadTime()
HAL_DMA2D_ConfigDeadTime()

17.2.5

Peripheral State and Errors functions
This subsection provides functions allowing to :
Get the DMA2D state
Get the DMA2D error code
This section contains the following APIs:
HAL_DMA2D_GetState()
HAL_DMA2D_GetError()

17.2.6

Detailed description of functions
HAL_DMA2D_Init
Function Name

HAL_StatusTypeDef HAL_DMA2D_Init
(DMA2D_HandleTypeDef * hdma2d)

Function Description

Initialize the DMA2D according to the specified parameters in the
DMA2D_InitTypeDef and create the associated handle.

Parameters

hdma2d: pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.

Return values

HAL: status

HAL_DMA2D_DeInit
Function Name

246/964

HAL_StatusTypeDef HAL_DMA2D_DeInit
(DMA2D_HandleTypeDef * hdma2d)
DocID025834 Rev 4

UM1725
Function Description

HAL DMA2D Generic Driver
Deinitializes the DMA2D peripheral registers to their default reset
values.

Parameters

hdma2d: pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.

Return values

None

HAL_DMA2D_MspInit
Function Name

void HAL_DMA2D_MspInit (DMA2D_HandleTypeDef *
hdma2d)

Function Description

Initializes the DMA2D MSP.

Parameters

hdma2d: pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.

Return values

None

HAL_DMA2D_MspDeInit
Function Name

void HAL_DMA2D_MspDeInit (DMA2D_HandleTypeDef *
hdma2d)

Function Description

DeInitializes the DMA2D MSP.

Parameters

hdma2d: pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.

Return values

None

HAL_DMA2D_Start
Function Name

HAL_StatusTypeDef HAL_DMA2D_Start
(DMA2D_HandleTypeDef * hdma2d, uint32_t pdata, uint32_t
DstAddress, uint32_t Width, uint32_t Height)

Function Description

Start the DMA2D Transfer.

Parameters

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
pdata: Configure the source memory Buffer address if
Memory-to-Memory or Memory-to-Memory with pixel format
conversion mode is selected, or configure the color value if
Register-to-Memory mode is selected.
DstAddress: The destination memory Buffer address.
Width: The width of data to be transferred from source to
destination (expressed in number of pixels per line).
Height: The height of data to be transferred from source to
destination (expressed in number of lines).

Return values

HAL: status

DocID025834 Rev 4

247/964

HAL DMA2D Generic Driver

UM1725

HAL_DMA2D_BlendingStart
Function Name

HAL_StatusTypeDef HAL_DMA2D_BlendingStart
(DMA2D_HandleTypeDef * hdma2d, uint32_t SrcAddress1,
uint32_t SrcAddress2, uint32_t DstAddress, uint32_t Width,
uint32_t Height)

Function Description

Start the multi-source DMA2D Transfer.

Parameters

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
SrcAddress1: The source memory Buffer address for the
foreground layer.
SrcAddress2: The source memory Buffer address for the
background layer.
DstAddress: The destination memory Buffer address.
Width: The width of data to be transferred from source to
destination (expressed in number of pixels per line).
Height: The height of data to be transferred from source to
destination (expressed in number of lines).

Return values

HAL: status

HAL_DMA2D_Start_IT
Function Name

HAL_StatusTypeDef HAL_DMA2D_Start_IT
(DMA2D_HandleTypeDef * hdma2d, uint32_t pdata, uint32_t
DstAddress, uint32_t Width, uint32_t Height)

Function Description

Start the DMA2D Transfer with interrupt enabled.

Parameters

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
pdata: Configure the source memory Buffer address if the
Memory-to-Memory or Memory-to-Memory with pixel format
conversion mode is selected, or configure the color value if
Register-to-Memory mode is selected.
DstAddress: The destination memory Buffer address.
Width: The width of data to be transferred from source to
destination (expressed in number of pixels per line).
Height: The height of data to be transferred from source to
destination (expressed in number of lines).

Return values

HAL: status

HAL_DMA2D_BlendingStart_IT
Function Name

HAL_StatusTypeDef HAL_DMA2D_BlendingStart_IT
(DMA2D_HandleTypeDef * hdma2d, uint32_t SrcAddress1,
uint32_t SrcAddress2, uint32_t DstAddress, uint32_t Width,
uint32_t Height)

Function Description

Start the multi-source DMA2D Transfer with interrupt enabled.

Parameters

248/964

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
SrcAddress1: The source memory Buffer address for the
foreground layer.
DocID025834 Rev 4

UM1725

HAL DMA2D Generic Driver
SrcAddress2: The source memory Buffer address for the
background layer.
DstAddress: The destination memory Buffer address.
Width: The width of data to be transferred from source to
destination (expressed in number of pixels per line).
Height: The height of data to be transferred from source to
destination (expressed in number of lines).
Return values

HAL: status

HAL_DMA2D_Suspend
Function Name

HAL_StatusTypeDef HAL_DMA2D_Suspend
(DMA2D_HandleTypeDef * hdma2d)

Function Description

Suspend the DMA2D Transfer.

Parameters

hdma2d: pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.

Return values

HAL: status

HAL_DMA2D_Resume
Function Name

HAL_StatusTypeDef HAL_DMA2D_Resume
(DMA2D_HandleTypeDef * hdma2d)

Function Description

Resume the DMA2D Transfer.

Parameters

hdma2d: pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.

Return values

HAL: status

HAL_DMA2D_Abort
Function Name

HAL_StatusTypeDef HAL_DMA2D_Abort
(DMA2D_HandleTypeDef * hdma2d)

Function Description

Abort the DMA2D Transfer.

Parameters

hdma2d: : pointer to a DMA2D_HandleTypeDef structure
that contains the configuration information for the DMA2D.

Return values

HAL: status

HAL_DMA2D_EnableCLUT
Function Name

HAL_StatusTypeDef HAL_DMA2D_EnableCLUT
(DMA2D_HandleTypeDef * hdma2d, uint32_t LayerIdx)

Function Description

Enable the DMA2D CLUT Transfer.

Parameters

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
LayerIdx: DMA2D Layer index. This parameter can be one
of the following values: 0(background) / 1(foreground)

Return values

HAL: status

DocID025834 Rev 4

249/964

HAL DMA2D Generic Driver

UM1725

HAL_DMA2D_CLUTLoad
Function Name

HAL_StatusTypeDef HAL_DMA2D_CLUTLoad
(DMA2D_HandleTypeDef * hdma2d, DMA2D_CLUTCfgTypeDef
CLUTCfg, uint32_t LayerIdx)

Function Description

Start DMA2D CLUT Loading.

Parameters

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
CLUTCfg: Pointer to a DMA2D_CLUTCfgTypeDef structure
that contains the configuration information for the color look
up table.
LayerIdx: DMA2D Layer index. This parameter can be one
of the following values: 0(background) / 1(foreground)

Return values

HAL: status

Notes

Invoking this API is similar to calling
HAL_DMA2D_ConfigCLUT() then
HAL_DMA2D_EnableCLUT().

HAL_DMA2D_CLUTLoad_IT
Function Name

HAL_StatusTypeDef HAL_DMA2D_CLUTLoad_IT
(DMA2D_HandleTypeDef * hdma2d, DMA2D_CLUTCfgTypeDef
CLUTCfg, uint32_t LayerIdx)

Function Description

Start DMA2D CLUT Loading with interrupt enabled.

Parameters

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
CLUTCfg: Pointer to a DMA2D_CLUTCfgTypeDef structure
that contains the configuration information for the color look
up table.
LayerIdx: DMA2D Layer index. This parameter can be one
of the following values: 0(background) / 1(foreground)

Return values

HAL: status

HAL_DMA2D_CLUTLoading_Abort
Function Name

HAL_StatusTypeDef HAL_DMA2D_CLUTLoading_Abort
(DMA2D_HandleTypeDef * hdma2d, uint32_t LayerIdx)

Function Description

Abort the DMA2D CLUT loading.

Parameters

hdma2d: : Pointer to a DMA2D_HandleTypeDef structure
that contains the configuration information for the DMA2D.
LayerIdx: DMA2D Layer index. This parameter can be one
of the following values: 0(background) / 1(foreground)

Return values

HAL: status

HAL_DMA2D_CLUTLoading_Suspend
Function Name

250/964

HAL_StatusTypeDef HAL_DMA2D_CLUTLoading_Suspend
(DMA2D_HandleTypeDef * hdma2d, uint32_t LayerIdx)

DocID025834 Rev 4

UM1725

HAL DMA2D Generic Driver
Function Description

Suspend the DMA2D CLUT loading.

Parameters

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
LayerIdx: DMA2D Layer index. This parameter can be one
of the following values: 0(background) / 1(foreground)

Return values

HAL: status

HAL_DMA2D_CLUTLoading_Resume
Function Name

HAL_StatusTypeDef HAL_DMA2D_CLUTLoading_Resume
(DMA2D_HandleTypeDef * hdma2d, uint32_t LayerIdx)

Function Description

Resume the DMA2D CLUT loading.

Parameters

hdma2d: pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
LayerIdx: DMA2D Layer index. This parameter can be one
of the following values: 0(background) / 1(foreground)

Return values

HAL: status

HAL_DMA2D_PollForTransfer
Function Name

HAL_StatusTypeDef HAL_DMA2D_PollForTransfer
(DMA2D_HandleTypeDef * hdma2d, uint32_t Timeout)

Function Description

Polling for transfer complete or CLUT loading.

Parameters

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
Timeout: Timeout duration

Return values

HAL: status

HAL_DMA2D_IRQHandler
Function Name

void HAL_DMA2D_IRQHandler (DMA2D_HandleTypeDef *
hdma2d)

Function Description

Handle DMA2D interrupt request.

Parameters

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.

Return values

HAL: status

HAL_DMA2D_LineEventCallback
Function Name

void HAL_DMA2D_LineEventCallback
(DMA2D_HandleTypeDef * hdma2d)

Function Description

Transfer watermark callback.

Parameters

hdma2d: pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.

Return values

None

DocID025834 Rev 4

251/964

HAL DMA2D Generic Driver

UM1725

HAL_DMA2D_CLUTLoadingCpltCallback
Function Name

void HAL_DMA2D_CLUTLoadingCpltCallback
(DMA2D_HandleTypeDef * hdma2d)

Function Description

CLUT Transfer Complete callback.

Parameters

hdma2d: pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.

Return values

None

HAL_DMA2D_ConfigLayer
Function Name

HAL_StatusTypeDef HAL_DMA2D_ConfigLayer
(DMA2D_HandleTypeDef * hdma2d, uint32_t LayerIdx)

Function Description

Configure the DMA2D Layer according to the specified parameters
in the DMA2D_InitTypeDef and create the associated handle.

Parameters

hdma2d: pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
LayerIdx: DMA2D Layer index. This parameter can be one
of the following values: 0(background) / 1(foreground)

Return values

HAL: status

HAL_DMA2D_ConfigCLUT
Function Name

HAL_StatusTypeDef HAL_DMA2D_ConfigCLUT
(DMA2D_HandleTypeDef * hdma2d, DMA2D_CLUTCfgTypeDef
CLUTCfg, uint32_t LayerIdx)

Function Description

Configure the DMA2D CLUT Transfer.

Parameters

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
CLUTCfg: Pointer to a DMA2D_CLUTCfgTypeDef structure
that contains the configuration information for the color look
up table.
LayerIdx: DMA2D Layer index. This parameter can be one
of the following values: 0(background) / 1(foreground)

Return values

HAL: status

HAL_DMA2D_ProgramLineEvent

252/964

Function Name

HAL_StatusTypeDef HAL_DMA2D_ProgramLineEvent
(DMA2D_HandleTypeDef * hdma2d, uint32_t Line)

Function Description

Configure the line watermark.

Parameters

hdma2d: Pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.
Line: Line Watermark configuration (maximum 16-bit long
value expected).

Return values

HAL: status

Notes

HAL_DMA2D_ProgramLineEvent() API enables the transfer
watermark interrupt.
DocID025834 Rev 4

UM1725

HAL DMA2D Generic Driver
The transfer watermark interrupt is disabled once it has
occurred.

HAL_DMA2D_EnableDeadTime
Function Name

HAL_StatusTypeDef HAL_DMA2D_EnableDeadTime
(DMA2D_HandleTypeDef * hdma2d)

Function Description

Enable DMA2D dead time feature.

Parameters

hdma2d: DMA2D handle.

Return values

HAL: status

HAL_DMA2D_DisableDeadTime
Function Name

HAL_StatusTypeDef HAL_DMA2D_DisableDeadTime
(DMA2D_HandleTypeDef * hdma2d)

Function Description

Disable DMA2D dead time feature.

Parameters

hdma2d: DMA2D handle.

Return values

HAL: status

HAL_DMA2D_ConfigDeadTime
Function Name

HAL_StatusTypeDef HAL_DMA2D_ConfigDeadTime
(DMA2D_HandleTypeDef * hdma2d, uint8_t DeadTime)

Function Description

Configure dead time.

Parameters

hdma2d: DMA2D handle.
DeadTime: dead time value.

Return values

HAL: status

Notes

The dead time value represents the guaranteed minimum
number of cycles between two consecutive transactions on
the AHB bus.

HAL_DMA2D_GetState
Function Name

HAL_DMA2D_StateTypeDef HAL_DMA2D_GetState
(DMA2D_HandleTypeDef * hdma2d)

Function Description

Return the DMA2D state.

Parameters

hdma2d: pointer to a DMA2D_HandleTypeDef structure that
contains the configuration information for the DMA2D.

Return values

HAL: state

HAL_DMA2D_GetError
Function Name

uint32_t HAL_DMA2D_GetError (DMA2D_HandleTypeDef *
hdma2d)

Function Description

Return the DMA2D error code.

Parameters

hdma2d: : pointer to a DMA2D_HandleTypeDef structure
DocID025834 Rev 4

253/964

HAL DMA2D Generic Driver

UM1725
that contains the configuration information for DMA2D.

Return values

DMA2D: Error Code

17.3

DMA2D Firmware driver defines

17.3.1

DMA2D
DMA2D API Aliases
HAL_DMA2D_DisableCLUT

Aliased to HAL_DMA2D_CLUTLoading_Abort for
compatibility with legacy code

DMA2D Alpha Mode
DMA2D_NO_MODIF_ALPHA

No modification of the alpha channel value

DMA2D_REPLACE_ALPHA

Replace original alpha channel value by programmed
alpha value

DMA2D_COMBINE_ALPHA

Replace original alpha channel value by programmed
alpha value with original alpha channel value

DMA2D CLUT Color Mode
DMA2D_CCM_ARGB8888

ARGB8888 DMA2D CLUT color mode

DMA2D_CCM_RGB888

RGB888 DMA2D CLUT color mode

DMA2D CLUT Size
DMA2D_CLUT_SIZE

DMA2D CLUT size

DMA2D Color Value
DMA2D_COLOR_VALUE

Color value mask

DMA2D Error Code
HAL_DMA2D_ERROR_NONE

No error

HAL_DMA2D_ERROR_TE

Transfer error

HAL_DMA2D_ERROR_CE

Configuration error

HAL_DMA2D_ERROR_CAE

CLUT access error

HAL_DMA2D_ERROR_TIMEOUT

Timeout error

DMA2D Exported Macros
__HAL_DMA2D_RESET_HANDLE_STATE

Description:
Reset DMA2D handle state.
Parameters:
__HANDLE__: specifies the DMA2D
handle.
Return value:
None

__HAL_DMA2D_ENABLE

Description:
Enable the DMA2D.

254/964

DocID025834 Rev 4

UM1725

HAL DMA2D Generic Driver
Parameters:
__HANDLE__: DMA2D handle
Return value:
None.
__HAL_DMA2D_GET_FLAG

Description:
Get the DMA2D pending flags.
Parameters:
__HANDLE__: DMA2D handle
__FLAG__: flag to check. This
parameter can be any combination of
the following values:
DMA2D_FLAG_CE: Configuration
error flag
DMA2D_FLAG_CTC: CLUT
transfer complete flag
DMA2D_FLAG_CAE: CLUT
access error flag
DMA2D_FLAG_TW: Transfer
Watermark flag
DMA2D_FLAG_TC: Transfer
complete flag
DMA2D_FLAG_TE: Transfer error
flag
Return value:
The: state of FLAG.

__HAL_DMA2D_CLEAR_FLAG

Description:
Clear the DMA2D pending flags.
Parameters:
__HANDLE__: DMA2D handle
__FLAG__: specifies the flag to clear.
This parameter can be any combination
of the following values:
DMA2D_FLAG_CE: Configuration
error flag
DMA2D_FLAG_CTC: CLUT
transfer complete flag
DMA2D_FLAG_CAE: CLUT
access error flag
DMA2D_FLAG_TW: Transfer
Watermark flag
DMA2D_FLAG_TC: Transfer
complete flag
DMA2D_FLAG_TE: Transfer error
flag
Return value:
None

DocID025834 Rev 4

255/964

HAL DMA2D Generic Driver
__HAL_DMA2D_ENABLE_IT

UM1725
Description:
Enable the specified DMA2D interrupts.
Parameters:
__HANDLE__: DMA2D handle
__INTERRUPT__: specifies the
DMA2D interrupt sources to be
enabled. This parameter can be any
combination of the following values:
DMA2D_IT_CE: Configuration
error interrupt mask
DMA2D_IT_CTC: CLUT transfer
complete interrupt mask
DMA2D_IT_CAE: CLUT access
error interrupt mask
DMA2D_IT_TW: Transfer
Watermark interrupt mask
DMA2D_IT_TC: Transfer complete
interrupt mask
DMA2D_IT_TE: Transfer error
interrupt mask
Return value:
None

__HAL_DMA2D_DISABLE_IT

Description:
Disable the specified DMA2D interrupts.
Parameters:
__HANDLE__: DMA2D handle
__INTERRUPT__: specifies the
DMA2D interrupt sources to be
disabled. This parameter can be any
combination of the following values:
DMA2D_IT_CE: Configuration
error interrupt mask
DMA2D_IT_CTC: CLUT transfer
complete interrupt mask
DMA2D_IT_CAE: CLUT access
error interrupt mask
DMA2D_IT_TW: Transfer
Watermark interrupt mask
DMA2D_IT_TC: Transfer complete
interrupt mask
DMA2D_IT_TE: Transfer error
interrupt mask
Return value:
None

__HAL_DMA2D_GET_IT_SOURCE

Description:
Check whether the specified DMA2D
interrupt source is enabled or not.

256/964

DocID025834 Rev 4

UM1725

HAL DMA2D Generic Driver
Parameters:
__HANDLE__: DMA2D handle
__INTERRUPT__: specifies the
DMA2D interrupt source to check. This
parameter can be one of the following
values:
DMA2D_IT_CE: Configuration
error interrupt mask
DMA2D_IT_CTC: CLUT transfer
complete interrupt mask
DMA2D_IT_CAE: CLUT access
error interrupt mask
DMA2D_IT_TW: Transfer
Watermark interrupt mask
DMA2D_IT_TC: Transfer complete
interrupt mask
DMA2D_IT_TE: Transfer error
interrupt mask
Return value:
The: state of INTERRUPT source.
DMA2D Exported Types
MAX_DMA2D_LAYER
DMA2D Flags
DMA2D_FLAG_CE

Configuration Error Interrupt Flag

DMA2D_FLAG_CTC

CLUT Transfer Complete Interrupt Flag

DMA2D_FLAG_CAE

CLUT Access Error Interrupt Flag

DMA2D_FLAG_TW

Transfer Watermark Interrupt Flag

DMA2D_FLAG_TC

Transfer Complete Interrupt Flag

DMA2D_FLAG_TE

Transfer Error Interrupt Flag

DMA2D Input Color Mode
DMA2D_INPUT_ARGB8888

ARGB8888 color mode

DMA2D_INPUT_RGB888

RGB888 color mode

DMA2D_INPUT_RGB565

RGB565 color mode

DMA2D_INPUT_ARGB1555

ARGB1555 color mode

DMA2D_INPUT_ARGB4444

ARGB4444 color mode

DMA2D_INPUT_L8

L8 color mode

DMA2D_INPUT_AL44

AL44 color mode

DMA2D_INPUT_AL88

AL88 color mode

DMA2D_INPUT_L4

L4 color mode

DMA2D_INPUT_A8

A8 color mode

DMA2D_INPUT_A4

A4 color mode

DocID025834 Rev 4

257/964

HAL DMA2D Generic Driver
DMA2D Interrupts

UM1725

DMA2D_IT_CE

Configuration Error Interrupt

DMA2D_IT_CTC

CLUT Transfer Complete Interrupt

DMA2D_IT_CAE

CLUT Access Error Interrupt

DMA2D_IT_TW

Transfer Watermark Interrupt

DMA2D_IT_TC

Transfer Complete Interrupt

DMA2D_IT_TE

Transfer Error Interrupt

DMA2D Maximum Line Watermark
DMA2D_LINE_WATERMARK_MAX

DMA2D maximum line watermark

DMA2D Maximum Number of Layers
DMA2D_MAX_LAYER

DMA2D maximum number of layers

DMA2D Mode
DMA2D_M2M

DMA2D memory to memory transfer mode

DMA2D_M2M_PFC

DMA2D memory to memory with pixel format conversion transfer
mode

DMA2D_M2M_BLEND

DMA2D memory to memory with blending transfer mode

DMA2D_R2M

DMA2D register to memory transfer mode

DMA2D Offset
DMA2D_OFFSET

Line Offset

DMA2D Output Color Mode
DMA2D_OUTPUT_ARGB8888

ARGB8888 DMA2D color mode

DMA2D_OUTPUT_RGB888

RGB888 DMA2D color mode

DMA2D_OUTPUT_RGB565

RGB565 DMA2D color mode

DMA2D_OUTPUT_ARGB1555

ARGB1555 DMA2D color mode

DMA2D_OUTPUT_ARGB4444

ARGB4444 DMA2D color mode

DMA2D Shifts

258/964

DMA2D_POSITION_FGPFCCR_CS

Required left shift to set foreground CLUT size

DMA2D_POSITION_BGPFCCR_CS

Required left shift to set background CLUT size

DMA2D_POSITION_FGPFCCR_CCM

Required left shift to set foreground CLUT color
mode

DMA2D_POSITION_BGPFCCR_CCM

Required left shift to set background CLUT
color mode

DMA2D_POSITION_AMTCR_DT

Required left shift to set deadtime value

DMA2D_POSITION_FGPFCCR_AM

Required left shift to set foreground alpha mode

DMA2D_POSITION_BGPFCCR_AM

Required left shift to set background alpha
mode

DMA2D_POSITION_FGPFCCR_ALPHA

Required left shift to set foreground alpha value

DMA2D_POSITION_BGPFCCR_ALPHA

Required left shift to set background alpha

DocID025834 Rev 4

UM1725

HAL DMA2D Generic Driver
value
DMA2D_POSITION_NLR_PL

Required left shift to set pixels per lines value

DMA2D Size
DMA2D_PIXEL

DMA2D number of pixels per line

DMA2D_LINE

DMA2D number of lines

DMA2D Time Out
DMA2D_TIMEOUT_ABORT

1s

DMA2D_TIMEOUT_SUSPEND

1s

DocID025834 Rev 4

259/964

HAL DMA Generic Driver

UM1725

18

HAL DMA Generic Driver

18.1

DMA Firmware driver registers structures

18.1.1

DMA_InitTypeDef
Data Fields
uint32_t Channel
uint32_t Direction
uint32_t PeriphInc
uint32_t MemInc
uint32_t PeriphDataAlignment
uint32_t MemDataAlignment
uint32_t Mode
uint32_t Priority
uint32_t FIFOMode
uint32_t FIFOThreshold
uint32_t MemBurst
uint32_t PeriphBurst

Field Documentation
uint32_t DMA_InitTypeDef::Channel
Specifies the channel used for the specified stream. This parameter can be a value of
DMA_Channel_selection
uint32_t DMA_InitTypeDef::Direction
Specifies if the data will be transferred from memory to peripheral, from memory to
memory or from peripheral to memory. This parameter can be a value of
DMA_Data_transfer_direction
uint32_t DMA_InitTypeDef::PeriphInc
Specifies whether the Peripheral address register should be incremented or not. This
parameter can be a value of DMA_Peripheral_incremented_mode
uint32_t DMA_InitTypeDef::MemInc
Specifies whether the memory address register should be incremented or not. This
parameter can be a value of DMA_Memory_incremented_mode
uint32_t DMA_InitTypeDef::PeriphDataAlignment
Specifies the Peripheral data width. This parameter can be a value of
DMA_Peripheral_data_size
uint32_t DMA_InitTypeDef::MemDataAlignment
Specifies the Memory data width. This parameter can be a value of
DMA_Memory_data_size
uint32_t DMA_InitTypeDef::Mode
Specifies the operation mode of the DMAy Streamx. This parameter can be a value of
DMA_mode
Note:The circular buffer mode cannot be used if the memory-to-memory data transfer
is configured on the selected Stream
uint32_t DMA_InitTypeDef::Priority
Specifies the software priority for the DMAy Streamx. This parameter can be a value
of DMA_Priority_level
260/964

DocID025834 Rev 4

UM1725

HAL DMA Generic Driver
uint32_t DMA_InitTypeDef::FIFOMode
Specifies if the FIFO mode or Direct mode will be used for the specified stream. This
parameter can be a value of DMA_FIFO_direct_mode
Note:The Direct mode (FIFO mode disabled) cannot be used if the memory-tomemory data transfer is configured on the selected stream
uint32_t DMA_InitTypeDef::FIFOThreshold
Specifies the FIFO threshold level. This parameter can be a value of
DMA_FIFO_threshold_level
uint32_t DMA_InitTypeDef::MemBurst
Specifies the Burst transfer configuration for the memory transfers. It specifies the
amount of data to be transferred in a single non interruptible transaction. This
parameter can be a value of DMA_Memory_burst
Note:The burst mode is possible only if the address Increment mode is enabled.
uint32_t DMA_InitTypeDef::PeriphBurst
Specifies the Burst transfer configuration for the peripheral transfers. It specifies the
amount of data to be transferred in a single non interruptible transaction. This
parameter can be a value of DMA_Peripheral_burst
Note:The burst mode is possible only if the address Increment mode is enabled.

18.1.2

__DMA_HandleTypeDef
Data Fields
DMA_Stream_TypeDef * Instance
DMA_InitTypeDef Init
HAL_LockTypeDef Lock
__IO HAL_DMA_StateTypeDef State
void * Parent
void(* XferCpltCallback
void(* XferHalfCpltCallback
void(* XferM1CpltCallback
void(* XferM1HalfCpltCallback
void(* XferErrorCallback
void(* XferAbortCallback
__IO uint32_t ErrorCode
uint32_t StreamBaseAddress
uint32_t StreamIndex

Field Documentation
DMA_Stream_TypeDef* __DMA_HandleTypeDef::Instance
Register base address
DMA_InitTypeDef __DMA_HandleTypeDef::Init
DMA communication parameters
HAL_LockTypeDef __DMA_HandleTypeDef::Lock
DMA locking object
__IO HAL_DMA_StateTypeDef __DMA_HandleTypeDef::State
DMA transfer state
void* __DMA_HandleTypeDef::Parent
Parent object state

DocID025834 Rev 4

261/964

HAL DMA Generic Driver

UM1725

void(* __DMA_HandleTypeDef::XferCpltCallback)(struct __DMA_HandleTypeDef
*hdma)
DMA transfer complete callback
void(* __DMA_HandleTypeDef::XferHalfCpltCallback)(struct
__DMA_HandleTypeDef *hdma)
DMA Half transfer complete callback
void(* __DMA_HandleTypeDef::XferM1CpltCallback)(struct
__DMA_HandleTypeDef *hdma)
DMA transfer complete Memory1 callback
void(* __DMA_HandleTypeDef::XferM1HalfCpltCallback)(struct
__DMA_HandleTypeDef *hdma)
DMA transfer Half complete Memory1 callback
void(* __DMA_HandleTypeDef::XferErrorCallback)(struct
__DMA_HandleTypeDef *hdma)
DMA transfer error callback
void(* __DMA_HandleTypeDef::XferAbortCallback)(struct
__DMA_HandleTypeDef *hdma)
DMA transfer Abort callback
__IO uint32_t __DMA_HandleTypeDef::ErrorCode
DMA Error code
uint32_t __DMA_HandleTypeDef::StreamBaseAddress
DMA Stream Base Address
uint32_t __DMA_HandleTypeDef::StreamIndex
DMA Stream Index

18.2

DMA Firmware driver API description

18.2.1

How to use this driver
1.

2.

Enable and configure the peripheral to be connected to the DMA Stream (except for
internal SRAM/FLASH memories: no initialization is necessary) please refer to
Reference manual for connection between peripherals and DMA requests.
For a given Stream, program the required configuration through the following
parameters: Transfer Direction, Source and Destination data formats, Circular, Normal
or peripheral flow control mode, Stream Priority level, Source and Destination
Increment mode, FIFO mode and its Threshold (if needed), Burst mode for Source
and/or Destination (if needed) using HAL_DMA_Init() function. Prior to
HAL_DMA_Init() the clock must be enabled for DMA through the following macros:
__HAL_RCC_DMA1_CLK_ENABLE() or __HAL_RCC_DMA2_CLK_ENABLE().

Polling mode IO operation
Use HAL_DMA_Start() to start DMA transfer after the configuration of Source address
and destination address and the Length of data to be transferred.
Use HAL_DMA_PollForTransfer() to poll for the end of current transfer, in this case a
fixed Timeout can be configured by User depending from his application.
Use HAL_DMA_Abort() function to abort the current transfer.

262/964

DocID025834 Rev 4

UM1725

HAL DMA Generic Driver

Interrupt mode IO operation
Configure the DMA interrupt priority using HAL_NVIC_SetPriority()
Enable the DMA IRQ handler using HAL_NVIC_EnableIRQ()
Use HAL_DMA_Start_IT() to start DMA transfer after the configuration of Source
address and destination address and the Length of data to be transferred. In this case
the DMA interrupt is configured
Use HAL_DMA_IRQHandler() called under DMA_IRQHandler() Interrupt subroutine
At the end of data transfer HAL_DMA_IRQHandler() function is executed and user
can add his own function by customization of function pointer XferCpltCallback and
XferErrorCallback (i.e a member of DMA handle structure).

1.
2.

Use HAL_DMA_GetState() function to return the DMA state and
HAL_DMA_GetError() in case of error detection.
Use HAL_DMA_Abort_IT() function to abort the current transfer In Memory-toMemory transfer mode, Circular mode is not allowed. The FIFO is used mainly to
reduce bus usage and to allow data packing/unpacking: it is possible to set different
Data Sizes for the Peripheral and the Memory (ie. you can set Half-Word data size for
the peripheral to access its data register and set Word data size for the Memory to
gain in access time. Each two half words will be packed and written in a single access
to a Word in the Memory). When FIFO is disabled, it is not allowed to configure
different Data Sizes for Source and Destination. In this case the Peripheral Data Size
will be applied to both Source and Destination.

DMA HAL driver macros list
Below the list of most used macros in DMA HAL driver.
__HAL_DMA_ENABLE: Enable the specified DMA Stream.
__HAL_DMA_DISABLE: Disable the specified DMA Stream.
__HAL_DMA_GET_IT_SOURCE: Check whether the specified DMA Stream interrupt
has occurred or not.
You can refer to the DMA HAL driver header file for more useful macros

18.2.2

Initialization and de-initialization functions
This section provides functions allowing to initialize the DMA Stream source and
destination addresses, incrementation and data sizes, transfer direction, circular/normal
mode selection, memory-to-memory mode selection and Stream priority value.
The HAL_DMA_Init() function follows the DMA configuration procedures as described in
reference manual.
This section contains the following APIs:
HAL_DMA_Init()
HAL_DMA_DeInit()

DocID025834 Rev 4

263/964

HAL DMA Generic Driver

18.2.3

UM1725

IO operation functions
This section provides functions allowing to:
Configure the source, destination address and data length and Start DMA transfer
Configure the source, destination address and data length and Start DMA transfer
with interrupt
Abort DMA transfer
Poll for transfer complete
Handle DMA interrupt request
This section contains the following APIs:
HAL_DMA_Start()
HAL_DMA_Start_IT()
HAL_DMA_Abort()
HAL_DMA_Abort_IT()
HAL_DMA_PollForTransfer()
HAL_DMA_IRQHandler()
HAL_DMA_RegisterCallback()
HAL_DMA_UnRegisterCallback()
HAL_DMA_CleanCallbacks()

18.2.4

State and Errors functions
This subsection provides functions allowing to
Check the DMA state
Get error code
This section contains the following APIs:
HAL_DMA_GetState()
HAL_DMA_GetError()

18.2.5

Detailed description of functions
HAL_DMA_Init
Function Name

HAL_StatusTypeDef HAL_DMA_Init (DMA_HandleTypeDef *
hdma)

Function Description

Initializes the DMA according to the specified parameters in the
DMA_InitTypeDef and create the associated handle.

Parameters

hdma: Pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.

Return values

HAL: status

HAL_DMA_DeInit
Function Name

HAL_StatusTypeDef HAL_DMA_DeInit (DMA_HandleTypeDef *
hdma)

Function Description

DeInitializes the DMA peripheral.

Parameters

264/964

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
DocID025834 Rev 4

UM1725

HAL DMA Generic Driver
Stream.
Return values

HAL: status

HAL_DMA_Start
Function Name

HAL_StatusTypeDef HAL_DMA_Start (DMA_HandleTypeDef *
hdma, uint32_t SrcAddress, uint32_t DstAddress, uint32_t
DataLength)

Function Description

Starts the DMA Transfer.

Parameters

hdma: : pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.
SrcAddress: The source memory Buffer address
DstAddress: The destination memory Buffer address
DataLength: The length of data to be transferred from
source to destination

Return values

HAL: status

HAL_DMA_Start_IT
Function Name

HAL_StatusTypeDef HAL_DMA_Start_IT
(DMA_HandleTypeDef * hdma, uint32_t SrcAddress, uint32_t
DstAddress, uint32_t DataLength)

Function Description

Starts the DMA Transfer with interrupt enabled.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.
SrcAddress: The source memory Buffer address
DstAddress: The destination memory Buffer address
DataLength: The length of data to be transferred from
source to destination

Return values

HAL: status

HAL_DMA_Abort
Function Name

HAL_StatusTypeDef HAL_DMA_Abort (DMA_HandleTypeDef *
hdma)

Function Description

Aborts the DMA Transfer.

Parameters

hdma: : pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.

Return values

HAL: status

Notes

After disabling a DMA Stream, a check for wait until the DMA
Stream is effectively disabled is added. If a Stream is disabled
while a data transfer is ongoing, the current data will be
transferred and the Stream will be effectively disabled only
after the transfer of this single data is finished.

DocID025834 Rev 4

265/964

HAL DMA Generic Driver

UM1725

HAL_DMA_Abort_IT
Function Name

HAL_StatusTypeDef HAL_DMA_Abort_IT
(DMA_HandleTypeDef * hdma)

Function Description

Aborts the DMA Transfer in Interrupt mode.

Parameters

hdma: : pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.

Return values

HAL: status

HAL_DMA_PollForTransfer
Function Name

HAL_StatusTypeDef HAL_DMA_PollForTransfer
(DMA_HandleTypeDef * hdma,
HAL_DMA_LevelCompleteTypeDef CompleteLevel, uint32_t
Timeout)

Function Description

Polling for transfer complete.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.
CompleteLevel: Specifies the DMA level complete.
Timeout: Timeout duration.

Return values

HAL: status

Notes

The polling mode is kept in this version for legacy. it is
recommanded to use the IT model instead. This model could
be used for debug purpose.
The HAL_DMA_PollForTransfer API cannot be used in
circular and double buffering mode (automatic circular mode).

HAL_DMA_IRQHandler
Function Name

void HAL_DMA_IRQHandler (DMA_HandleTypeDef * hdma)

Function Description

Handles DMA interrupt request.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.

Return values

None

HAL_DMA_CleanCallbacks
Function Name

HAL_StatusTypeDef HAL_DMA_CleanCallbacks
(DMA_HandleTypeDef * hdma)

Function Description

HAL_DMA_RegisterCallback
Function Name

266/964

HAL_StatusTypeDef HAL_DMA_RegisterCallback
(DMA_HandleTypeDef * hdma, HAL_DMA_CallbackIDTypeDef

DocID025834 Rev 4

UM1725

HAL DMA Generic Driver
CallbackID, void(*)(DMA_HandleTypeDef *_hdma) pCallback)
Function Description

Register callbacks.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.
CallbackID: User Callback identifer a DMA_HandleTypeDef
structure as parameter.
pCallback: pointer to private callbacsk function which has
pointer to a DMA_HandleTypeDef structure as parameter.

Return values

HAL: status

HAL_DMA_UnRegisterCallback
Function Name

HAL_StatusTypeDef HAL_DMA_UnRegisterCallback
(DMA_HandleTypeDef * hdma, HAL_DMA_CallbackIDTypeDef
CallbackID)

Function Description

UnRegister callbacks.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.
CallbackID: User Callback identifer a
HAL_DMA_CallbackIDTypeDef ENUM as parameter.

Return values

HAL: status

HAL_DMA_GetState
Function Name

HAL_DMA_StateTypeDef HAL_DMA_GetState
(DMA_HandleTypeDef * hdma)

Function Description

Returns the DMA state.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.

Return values

HAL: state

HAL_DMA_GetError
Function Name

uint32_t HAL_DMA_GetError (DMA_HandleTypeDef * hdma)

Function Description

Return the DMA error code.

Parameters

hdma: : pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.

Return values

DMA: Error Code

DocID025834 Rev 4

267/964

HAL DMA Generic Driver

UM1725

18.3

DMA Firmware driver defines

18.3.1

DMA
DMA Channel selection
DMA_CHANNEL_0

DMA Channel 0

DMA_CHANNEL_1

DMA Channel 1

DMA_CHANNEL_2

DMA Channel 2

DMA_CHANNEL_3

DMA Channel 3

DMA_CHANNEL_4

DMA Channel 4

DMA_CHANNEL_5

DMA Channel 5

DMA_CHANNEL_6

DMA Channel 6

DMA_CHANNEL_7

DMA Channel 7

DMA Data transfer direction
DMA_PERIPH_TO_MEMORY

Peripheral to memory direction

DMA_MEMORY_TO_PERIPH

Memory to peripheral direction

DMA_MEMORY_TO_MEMORY

Memory to memory direction

DMA Error Code
HAL_DMA_ERROR_NONE

No error

HAL_DMA_ERROR_TE

Transfer error

HAL_DMA_ERROR_FE

FIFO error

HAL_DMA_ERROR_DME

Direct Mode error

HAL_DMA_ERROR_TIMEOUT

Timeout error

HAL_DMA_ERROR_PARAM

Parameter error

HAL_DMA_ERROR_NO_XFER

Abort requested with no Xfer ongoing

HAL_DMA_ERROR_NOT_SUPPORTED

Not supported mode

DMA FIFO direct mode
DMA_FIFOMODE_DISABLE

FIFO mode disable

DMA_FIFOMODE_ENABLE

FIFO mode enable

DMA FIFO threshold level
DMA_FIFO_THRESHOLD_1QUARTERFULL

FIFO threshold 1 quart full configuration

DMA_FIFO_THRESHOLD_HALFFULL

FIFO threshold half full configuration

DMA_FIFO_THRESHOLD_3QUARTERSFULL

FIFO threshold 3 quarts full configuration

DMA_FIFO_THRESHOLD_FULL

FIFO threshold full configuration

DMA flag definitions
DMA_FLAG_FEIF0_4
DMA_FLAG_DMEIF0_4
DMA_FLAG_TEIF0_4
268/964

DocID025834 Rev 4

UM1725

HAL DMA Generic Driver
DMA_FLAG_HTIF0_4
DMA_FLAG_TCIF0_4
DMA_FLAG_FEIF1_5
DMA_FLAG_DMEIF1_5
DMA_FLAG_TEIF1_5
DMA_FLAG_HTIF1_5
DMA_FLAG_TCIF1_5
DMA_FLAG_FEIF2_6
DMA_FLAG_DMEIF2_6
DMA_FLAG_TEIF2_6
DMA_FLAG_HTIF2_6
DMA_FLAG_TCIF2_6
DMA_FLAG_FEIF3_7
DMA_FLAG_DMEIF3_7
DMA_FLAG_TEIF3_7
DMA_FLAG_HTIF3_7
DMA_FLAG_TCIF3_7
DMA Handle index
TIM_DMA_ID_UPDATE

Index of the DMA handle used for Update DMA requests

TIM_DMA_ID_CC1

Index of the DMA handle used for Capture/Compare 1
DMA requests

TIM_DMA_ID_CC2

Index of the DMA handle used for Capture/Compare 2
DMA requests

TIM_DMA_ID_CC3

Index of the DMA handle used for Capture/Compare 3
DMA requests

TIM_DMA_ID_CC4

Index of the DMA handle used for Capture/Compare 4
DMA requests

TIM_DMA_ID_COMMUTATION

Index of the DMA handle used for Commutation DMA
requests

TIM_DMA_ID_TRIGGER

Index of the DMA handle used for Trigger DMA requests

DMA interrupt enable definitions
DMA_IT_TC
DMA_IT_HT
DMA_IT_TE
DMA_IT_DME
DMA_IT_FE
DMA Memory burst
DMA_MBURST_SINGLE

DocID025834 Rev 4

269/964

HAL DMA Generic Driver
DMA_MBURST_INC4

UM1725

DMA_MBURST_INC8
DMA_MBURST_INC16
DMA Memory data size
DMA_MDATAALIGN_BYTE

Memory data alignment: Byte

DMA_MDATAALIGN_HALFWORD

Memory data alignment: HalfWord

DMA_MDATAALIGN_WORD

Memory data alignment: Word

DMA Memory incremented mode
DMA_MINC_ENABLE

Memory increment mode enable

DMA_MINC_DISABLE

Memory increment mode disable

DMA mode
DMA_NORMAL

Normal mode

DMA_CIRCULAR

Circular mode

DMA_PFCTRL

Peripheral flow control mode

DMA Peripheral burst
DMA_PBURST_SINGLE
DMA_PBURST_INC4
DMA_PBURST_INC8
DMA_PBURST_INC16
DMA Peripheral data size
DMA_PDATAALIGN_BYTE

Peripheral data alignment: Byte

DMA_PDATAALIGN_HALFWORD

Peripheral data alignment: HalfWord

DMA_PDATAALIGN_WORD

Peripheral data alignment: Word

DMA Peripheral incremented mode
DMA_PINC_ENABLE

Peripheral increment mode enable

DMA_PINC_DISABLE

Peripheral increment mode disable

DMA Priority level

270/964

DMA_PRIORITY_LOW

Priority level: Low

DMA_PRIORITY_MEDIUM

Priority level: Medium

DMA_PRIORITY_HIGH

Priority level: High

DMA_PRIORITY_VERY_HIGH

Priority level: Very High

DocID025834 Rev 4

UM1725

HAL DMA Extension Driver

19

HAL DMA Extension Driver

19.1

DMAEx Firmware driver API description

19.1.1

How to use this driver
The DMA Extension HAL driver can be used as follows:
1.

19.1.2

Start a multi buffer transfer using the HAL_DMA_MultiBufferStart() function for polling
mode or HAL_DMA_MultiBufferStart_IT() for interrupt mode. In Memory-to-Memory
transfer mode, Multi (Double) Buffer mode is not allowed. When Multi (Double) Buffer
mode is enabled the, transfer is circular by default. In Multi (Double) buffer mode, it is
possible to update the base address for the AHB memory port on the fly
(DMA_SxM0AR or DMA_SxM1AR) when the stream is enabled.

Extended features functions
This section provides functions allowing to:
Configure the source, destination address and data length and Start MultiBuffer DMA
transfer
Configure the source, destination address and data length and Start MultiBuffer DMA
transfer with interrupt
Change on the fly the memory0 or memory1 address.
This section contains the following APIs:
HAL_DMAEx_MultiBufferStart()
HAL_DMAEx_MultiBufferStart_IT()
HAL_DMAEx_ChangeMemory()

19.1.3

Detailed description of functions
HAL_DMAEx_MultiBufferStart
Function Name

HAL_StatusTypeDef HAL_DMAEx_MultiBufferStart
(DMA_HandleTypeDef * hdma, uint32_t SrcAddress, uint32_t
DstAddress, uint32_t SecondMemAddress, uint32_t
DataLength)

Function Description

Starts the multi_buffer DMA Transfer.

Parameters

hdma: : pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.
SrcAddress: The source memory Buffer address
DstAddress: The destination memory Buffer address
SecondMemAddress: The second memory Buffer address
in case of multi buffer Transfer
DataLength: The length of data to be transferred from
source to destination

Return values

HAL: status

DocID025834 Rev 4

271/964

HAL DMA Extension Driver

UM1725

HAL_DMAEx_MultiBufferStart_IT
Function Name

HAL_StatusTypeDef HAL_DMAEx_MultiBufferStart_IT
(DMA_HandleTypeDef * hdma, uint32_t SrcAddress, uint32_t
DstAddress, uint32_t SecondMemAddress, uint32_t
DataLength)

Function Description

Starts the multi_buffer DMA Transfer with interrupt enabled.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.
SrcAddress: The source memory Buffer address
DstAddress: The destination memory Buffer address
SecondMemAddress: The second memory Buffer address
in case of multi buffer Transfer
DataLength: The length of data to be transferred from
source to destination

Return values

HAL: status

HAL_DMAEx_ChangeMemory

272/964

Function Name

HAL_StatusTypeDef HAL_DMAEx_ChangeMemory
(DMA_HandleTypeDef * hdma, uint32_t Address,
HAL_DMA_MemoryTypeDef memory)

Function Description

Change the memory0 or memory1 address on the fly.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
Stream.
Address: The new address
memory: the memory to be changed, This parameter can be
one of the following values: MEMORY0 / MEMORY1

Return values

HAL: status

Notes

The MEMORY0 address can be changed only when the
current transfer use MEMORY1 and the MEMORY1 address
can be changed only when the current transfer use
MEMORY0.

DocID025834 Rev 4

UM1725

HAL DSI Generic Driver

20

HAL DSI Generic Driver

20.1

DSI Firmware driver registers structures

20.1.1

DSI_InitTypeDef
Data Fields
uint32_t AutomaticClockLaneControl
uint32_t TXEscapeCkdiv
uint32_t NumberOfLanes

Field Documentation
uint32_t DSI_InitTypeDef::AutomaticClockLaneControl
Automatic clock lane control This parameter can be any value of
DSI_Automatic_Clk_Lane_Control
uint32_t DSI_InitTypeDef::TXEscapeCkdiv
TX Escape clock division The values 0 and 1 stop the TX_ESC clock generation
uint32_t DSI_InitTypeDef::NumberOfLanes
Number of lanes This parameter can be any value of DSI_Number_Of_Lanes

20.1.2

DSI_PLLInitTypeDef
Data Fields
uint32_t PLLNDIV
uint32_t PLLIDF
uint32_t PLLODF

Field Documentation
uint32_t DSI_PLLInitTypeDef::PLLNDIV
PLL Loop Division Factor This parameter must be a value between 10 and 125
uint32_t DSI_PLLInitTypeDef::PLLIDF
PLL Input Division Factor This parameter can be any value of DSI_PLL_IDF
uint32_t DSI_PLLInitTypeDef::PLLODF
PLL Output Division Factor This parameter can be any value of DSI_PLL_ODF

DocID025834 Rev 4

273/964

HAL DSI Generic Driver

20.1.3

UM1725

DSI_VidCfgTypeDef
Data Fields
uint32_t VirtualChannelID
uint32_t ColorCoding
uint32_t LooselyPacked
uint32_t Mode
uint32_t PacketSize
uint32_t NumberOfChunks
uint32_t NullPacketSize
uint32_t HSPolarity
uint32_t VSPolarity
uint32_t DEPolarity
uint32_t HorizontalSyncActive
uint32_t HorizontalBackPorch
uint32_t HorizontalLine
uint32_t VerticalSyncActive
uint32_t VerticalBackPorch
uint32_t VerticalFrontPorch
uint32_t VerticalActive
uint32_t LPCommandEnable
uint32_t LPLargestPacketSize
uint32_t LPVACTLargestPacketSize
uint32_t LPHorizontalFrontPorchEnable
uint32_t LPHorizontalBackPorchEnable
uint32_t LPVerticalActiveEnable
uint32_t LPVerticalFrontPorchEnable
uint32_t LPVerticalBackPorchEnable
uint32_t LPVerticalSyncActiveEnable
uint32_t FrameBTAAcknowledgeEnable

Field Documentation
uint32_t DSI_VidCfgTypeDef::VirtualChannelID
Virtual channel ID
uint32_t DSI_VidCfgTypeDef::ColorCoding
Color coding for LTDC interface This parameter can be any value of
DSI_Color_Coding
uint32_t DSI_VidCfgTypeDef::LooselyPacked
Enable or disable loosely packed stream (needed only when using 18-bit
configuration). This parameter can be any value of DSI_LooselyPacked
uint32_t DSI_VidCfgTypeDef::Mode
Video mode type This parameter can be any value of DSI_Video_Mode_Type
uint32_t DSI_VidCfgTypeDef::PacketSize
Video packet size
uint32_t DSI_VidCfgTypeDef::NumberOfChunks
Number of chunks
uint32_t DSI_VidCfgTypeDef::NullPacketSize
Null packet size
274/964

DocID025834 Rev 4

UM1725

HAL DSI Generic Driver
uint32_t DSI_VidCfgTypeDef::HSPolarity
HSYNC pin polarity This parameter can be any value of DSI_HSYNC_Polarity
uint32_t DSI_VidCfgTypeDef::VSPolarity
VSYNC pin polarity This parameter can be any value of
DSI_VSYNC_Active_Polarity
uint32_t DSI_VidCfgTypeDef::DEPolarity
Data Enable pin polarity This parameter can be any value of
DSI_DATA_ENABLE_Polarity
uint32_t DSI_VidCfgTypeDef::HorizontalSyncActive
Horizontal synchronism active duration (in lane byte clock cycles)
uint32_t DSI_VidCfgTypeDef::HorizontalBackPorch
Horizontal back-porch duration (in lane byte clock cycles)
uint32_t DSI_VidCfgTypeDef::HorizontalLine
Horizontal line duration (in lane byte clock cycles)
uint32_t DSI_VidCfgTypeDef::VerticalSyncActive
Vertical synchronism active duration
uint32_t DSI_VidCfgTypeDef::VerticalBackPorch
Vertical back-porch duration
uint32_t DSI_VidCfgTypeDef::VerticalFrontPorch
Vertical front-porch duration
uint32_t DSI_VidCfgTypeDef::VerticalActive
Vertical active duration
uint32_t DSI_VidCfgTypeDef::LPCommandEnable
Low-power command enable This parameter can be any value of
DSI_LP_Command
uint32_t DSI_VidCfgTypeDef::LPLargestPacketSize
The size, in bytes, of the low power largest packet that can fit in a line during VSA,
VBP and VFP regions
uint32_t DSI_VidCfgTypeDef::LPVACTLargestPacketSize
The size, in bytes, of the low power largest packet that can fit in a line during VACT
region
uint32_t DSI_VidCfgTypeDef::LPHorizontalFrontPorchEnable
Low-power horizontal front-porch enable This parameter can be any value of
DSI_LP_HFP
uint32_t DSI_VidCfgTypeDef::LPHorizontalBackPorchEnable
Low-power horizontal back-porch enable This parameter can be any value of
DSI_LP_HBP
uint32_t DSI_VidCfgTypeDef::LPVerticalActiveEnable
Low-power vertical active enable This parameter can be any value of DSI_LP_VACT
uint32_t DSI_VidCfgTypeDef::LPVerticalFrontPorchEnable
Low-power vertical front-porch enable This parameter can be any value of
DSI_LP_VFP
uint32_t DSI_VidCfgTypeDef::LPVerticalBackPorchEnable
Low-power vertical back-porch enable This parameter can be any value of
DSI_LP_VBP
uint32_t DSI_VidCfgTypeDef::LPVerticalSyncActiveEnable
Low-power vertical sync active enable This parameter can be any value of
DSI_LP_VSYNC
uint32_t DSI_VidCfgTypeDef::FrameBTAAcknowledgeEnable
Frame bus-turn-around acknowledge enable This parameter can be any value of
DSI_FBTA_acknowledge

DocID025834 Rev 4

275/964

HAL DSI Generic Driver

20.1.4

UM1725

DSI_CmdCfgTypeDef
Data Fields
uint32_t VirtualChannelID
uint32_t ColorCoding
uint32_t CommandSize
uint32_t TearingEffectSource
uint32_t TearingEffectPolarity
uint32_t HSPolarity
uint32_t VSPolarity
uint32_t DEPolarity
uint32_t VSyncPol
uint32_t AutomaticRefresh
uint32_t TEAcknowledgeRequest

Field Documentation
uint32_t DSI_CmdCfgTypeDef::VirtualChannelID
Virtual channel ID
uint32_t DSI_CmdCfgTypeDef::ColorCoding
Color coding for LTDC interface This parameter can be any value of
DSI_Color_Coding
uint32_t DSI_CmdCfgTypeDef::CommandSize
Maximum allowed size for an LTDC write memory command, measured in pixels.
This parameter can be any value between 0x00 and 0xFFFFU
uint32_t DSI_CmdCfgTypeDef::TearingEffectSource
Tearing effect source This parameter can be any value of DSI_TearingEffectSource
uint32_t DSI_CmdCfgTypeDef::TearingEffectPolarity
Tearing effect pin polarity This parameter can be any value of
DSI_TearingEffectPolarity
uint32_t DSI_CmdCfgTypeDef::HSPolarity
HSYNC pin polarity This parameter can be any value of DSI_HSYNC_Polarity
uint32_t DSI_CmdCfgTypeDef::VSPolarity
VSYNC pin polarity This parameter can be any value of
DSI_VSYNC_Active_Polarity
uint32_t DSI_CmdCfgTypeDef::DEPolarity
Data Enable pin polarity This parameter can be any value of
DSI_DATA_ENABLE_Polarity
uint32_t DSI_CmdCfgTypeDef::VSyncPol
VSync edge on which the LTDC is halted This parameter can be any value of
DSI_Vsync_Polarity
uint32_t DSI_CmdCfgTypeDef::AutomaticRefresh
Automatic refresh mode This parameter can be any value of DSI_AutomaticRefresh
uint32_t DSI_CmdCfgTypeDef::TEAcknowledgeRequest
Tearing Effect Acknowledge Request Enable This parameter can be any value of
DSI_TE_AcknowledgeRequest

276/964

DocID025834 Rev 4

UM1725

20.1.5

HAL DSI Generic Driver

DSI_LPCmdTypeDef
Data Fields
uint32_t LPGenShortWriteNoP
uint32_t LPGenShortWriteOneP
uint32_t LPGenShortWriteTwoP
uint32_t LPGenShortReadNoP
uint32_t LPGenShortReadOneP
uint32_t LPGenShortReadTwoP
uint32_t LPGenLongWrite
uint32_t LPDcsShortWriteNoP
uint32_t LPDcsShortWriteOneP
uint32_t LPDcsShortReadNoP
uint32_t LPDcsLongWrite
uint32_t LPMaxReadPacket
uint32_t AcknowledgeRequest

Field Documentation
uint32_t DSI_LPCmdTypeDef::LPGenShortWriteNoP
Generic Short Write Zero parameters Transmission This parameter can be any value
of DSI_LP_LPGenShortWriteNoP
uint32_t DSI_LPCmdTypeDef::LPGenShortWriteOneP
Generic Short Write One parameter Transmission This parameter can be any value of
DSI_LP_LPGenShortWriteOneP
uint32_t DSI_LPCmdTypeDef::LPGenShortWriteTwoP
Generic Short Write Two parameters Transmission This parameter can be any value
of DSI_LP_LPGenShortWriteTwoP
uint32_t DSI_LPCmdTypeDef::LPGenShortReadNoP
Generic Short Read Zero parameters Transmission This parameter can be any value
of DSI_LP_LPGenShortReadNoP
uint32_t DSI_LPCmdTypeDef::LPGenShortReadOneP
Generic Short Read One parameter Transmission This parameter can be any value
of DSI_LP_LPGenShortReadOneP
uint32_t DSI_LPCmdTypeDef::LPGenShortReadTwoP
Generic Short Read Two parameters Transmission This parameter can be any value
of DSI_LP_LPGenShortReadTwoP
uint32_t DSI_LPCmdTypeDef::LPGenLongWrite
Generic Long Write Transmission This parameter can be any value of
DSI_LP_LPGenLongWrite
uint32_t DSI_LPCmdTypeDef::LPDcsShortWriteNoP
DCS Short Write Zero parameters Transmission This parameter can be any value of
DSI_LP_LPDcsShortWriteNoP
uint32_t DSI_LPCmdTypeDef::LPDcsShortWriteOneP
DCS Short Write One parameter Transmission This parameter can be any value of
DSI_LP_LPDcsShortWriteOneP
uint32_t DSI_LPCmdTypeDef::LPDcsShortReadNoP
DCS Short Read Zero parameters Transmission This parameter can be any value of
DSI_LP_LPDcsShortReadNoP

DocID025834 Rev 4

277/964

HAL DSI Generic Driver

UM1725

uint32_t DSI_LPCmdTypeDef::LPDcsLongWrite
DCS Long Write Transmission This parameter can be any value of
DSI_LP_LPDcsLongWrite
uint32_t DSI_LPCmdTypeDef::LPMaxReadPacket
Maximum Read Packet Size Transmission This parameter can be any value of
DSI_LP_LPMaxReadPacket
uint32_t DSI_LPCmdTypeDef::AcknowledgeRequest
Acknowledge Request Enable This parameter can be any value of
DSI_AcknowledgeRequest

20.1.6

DSI_PHY_TimerTypeDef
Data Fields
uint32_t ClockLaneHS2LPTime
uint32_t ClockLaneLP2HSTime
uint32_t DataLaneHS2LPTime
uint32_t DataLaneLP2HSTime
uint32_t DataLaneMaxReadTime
uint32_t StopWaitTime

Field Documentation
uint32_t DSI_PHY_TimerTypeDef::ClockLaneHS2LPTime
The maximum time that the D-PHY clock lane takes to go from high-speed to lowpower transmission
uint32_t DSI_PHY_TimerTypeDef::ClockLaneLP2HSTime
The maximum time that the D-PHY clock lane takes to go from low-power to highspeed transmission
uint32_t DSI_PHY_TimerTypeDef::DataLaneHS2LPTime
The maximum time that the D-PHY data lanes takes to go from high-speed to lowpower transmission
uint32_t DSI_PHY_TimerTypeDef::DataLaneLP2HSTime
The maximum time that the D-PHY data lanes takes to go from low-power to highspeed transmission
uint32_t DSI_PHY_TimerTypeDef::DataLaneMaxReadTime
The maximum time required to perform a read command
uint32_t DSI_PHY_TimerTypeDef::StopWaitTime
The minimum wait period to request a High-Speed transmission after the Stop state

20.1.7

DSI_HOST_TimeoutTypeDef
Data Fields
uint32_t TimeoutCkdiv
uint32_t HighSpeedTransmissionTimeout
uint32_t LowPowerReceptionTimeout
uint32_t HighSpeedReadTimeout
uint32_t LowPowerReadTimeout

278/964

DocID025834 Rev 4

UM1725

HAL DSI Generic Driver
uint32_t HighSpeedWriteTimeout
uint32_t HighSpeedWritePrespMode
uint32_t LowPowerWriteTimeout
uint32_t BTATimeout

Field Documentation
uint32_t DSI_HOST_TimeoutTypeDef::TimeoutCkdiv
Time-out clock division
uint32_t DSI_HOST_TimeoutTypeDef::HighSpeedTransmissionTimeout
High-speed transmission time-out
uint32_t DSI_HOST_TimeoutTypeDef::LowPowerReceptionTimeout
Low-power reception time-out
uint32_t DSI_HOST_TimeoutTypeDef::HighSpeedReadTimeout
High-speed read time-out
uint32_t DSI_HOST_TimeoutTypeDef::LowPowerReadTimeout
Low-power read time-out
uint32_t DSI_HOST_TimeoutTypeDef::HighSpeedWriteTimeout
High-speed write time-out
uint32_t DSI_HOST_TimeoutTypeDef::HighSpeedWritePrespMode
High-speed write presp mode This parameter can be any value of
DSI_HS_PrespMode
uint32_t DSI_HOST_TimeoutTypeDef::LowPowerWriteTimeout
Low-speed write time-out
uint32_t DSI_HOST_TimeoutTypeDef::BTATimeout
BTA time-out

20.1.8

DSI_HandleTypeDef
Data Fields
DSI_TypeDef * Instance
DSI_InitTypeDef Init
HAL_LockTypeDef Lock
__IO HAL_DSI_StateTypeDef State
__IO uint32_t ErrorCode
uint32_t ErrorMsk

Field Documentation
DSI_TypeDef* DSI_HandleTypeDef::Instance
Register base address
DSI_InitTypeDef DSI_HandleTypeDef::Init
DSI required parameters
HAL_LockTypeDef DSI_HandleTypeDef::Lock
DSI peripheral status
__IO HAL_DSI_StateTypeDef DSI_HandleTypeDef::State
DSI communication state
__IO uint32_t DSI_HandleTypeDef::ErrorCode
DSI Error code

DocID025834 Rev 4

279/964

HAL DSI Generic Driver

UM1725

uint32_t DSI_HandleTypeDef::ErrorMsk
DSI Error monitoring mask

20.2

DSI Firmware driver API description

20.2.1

Initialization and Configuration functions
This section provides functions allowing to:
Initialize and configure the DSI
De-initialize the DSI
This section contains the following APIs:
HAL_DSI_Init()
HAL_DSI_DeInit()
HAL_DSI_GetError()
HAL_DSI_ConfigErrorMonitor()
HAL_DSI_MspInit()
HAL_DSI_MspDeInit()

20.2.2

IO operation functions
This section provides function allowing to:
Handle DSI interrupt request
This section contains the following APIs:
HAL_DSI_IRQHandler()
HAL_DSI_TearingEffectCallback()
HAL_DSI_EndOfRefreshCallback()
HAL_DSI_ErrorCallback()

20.2.3

Peripheral Control functions
This section contains the following APIs:
HAL_DSI_SetGenericVCID()
HAL_DSI_ConfigVideoMode()
HAL_DSI_ConfigAdaptedCommandMode()
HAL_DSI_ConfigCommand()
HAL_DSI_ConfigFlowControl()
HAL_DSI_ConfigPhyTimer()
HAL_DSI_ConfigHostTimeouts()
HAL_DSI_Start()
HAL_DSI_Stop()
HAL_DSI_Refresh()
HAL_DSI_ColorMode()
HAL_DSI_Shutdown()
HAL_DSI_ShortWrite()
HAL_DSI_LongWrite()
HAL_DSI_Read()
HAL_DSI_EnterULPMData()
HAL_DSI_ExitULPMData()
HAL_DSI_EnterULPM()

280/964

DocID025834 Rev 4

UM1725

HAL DSI Generic Driver
HAL_DSI_ExitULPM()
HAL_DSI_PatternGeneratorStart()
HAL_DSI_PatternGeneratorStop()
HAL_DSI_SetSlewRateAndDelayTuning()
HAL_DSI_SetLowPowerRXFilter()
HAL_DSI_SetSDD()
HAL_DSI_SetLanePinsConfiguration()
HAL_DSI_SetPHYTimings()
HAL_DSI_ForceTXStopMode()
HAL_DSI_ForceRXLowPower()
HAL_DSI_ForceDataLanesInRX()
HAL_DSI_SetPullDown()
HAL_DSI_SetContentionDetectionOff()

20.2.4

Peripheral State and Errors functions
This subsection provides functions allowing to
Check the DSI state.
Get error code.
This section contains the following APIs:
HAL_DSI_GetState()

20.2.5

Detailed description of functions
HAL_DSI_Init
Function Name

HAL_StatusTypeDef HAL_DSI_Init (DSI_HandleTypeDef * hdsi,
DSI_PLLInitTypeDef * PLLInit)

Function Description

Initializes the DSI according to the specified parameters in the
DSI_InitTypeDef and create the associated handle.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
PLLInit: pointer to a DSI_PLLInitTypeDef structure that
contains the PLL Clock structure definition for the DSI.

Return values

HAL: status

HAL_DSI_DeInit
Function Name

HAL_StatusTypeDef HAL_DSI_DeInit (DSI_HandleTypeDef *
hdsi)

Function Description

De-initializes the DSI peripheral registers to their default reset
values.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

HAL: status

HAL_DSI_MspInit
Function Name

void HAL_DSI_MspInit (DSI_HandleTypeDef * hdsi)

DocID025834 Rev 4

281/964

HAL DSI Generic Driver
Function Description

UM1725
Initializes the DSI MSP.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

None

HAL_DSI_MspDeInit
Function Name

void HAL_DSI_MspDeInit (DSI_HandleTypeDef * hdsi)

Function Description

De-initializes the DSI MSP.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

None

HAL_DSI_IRQHandler
Function Name

void HAL_DSI_IRQHandler (DSI_HandleTypeDef * hdsi)

Function Description

Handles DSI interrupt request.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

HAL: status

HAL_DSI_TearingEffectCallback
Function Name

void HAL_DSI_TearingEffectCallback (DSI_HandleTypeDef *
hdsi)

Function Description

Tearing Effect DSI callback.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

None

HAL_DSI_EndOfRefreshCallback
Function Name

void HAL_DSI_EndOfRefreshCallback (DSI_HandleTypeDef *
hdsi)

Function Description

End of Refresh DSI callback.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

None

HAL_DSI_ErrorCallback
Function Name

void HAL_DSI_ErrorCallback (DSI_HandleTypeDef * hdsi)

Function Description

Operation Error DSI callback.

Parameters

282/964

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
DocID025834 Rev 4

UM1725

HAL DSI Generic Driver
Return values

None

HAL_DSI_SetGenericVCID
Function Name

HAL_StatusTypeDef HAL_DSI_SetGenericVCID
(DSI_HandleTypeDef * hdsi, uint32_t VirtualChannelID)

Function Description

Configure the Generic interface read-back Virtual Channel ID.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
VirtualChannelID: Virtual channel ID

Return values

HAL: status

HAL_DSI_ConfigVideoMode
Function Name

HAL_StatusTypeDef HAL_DSI_ConfigVideoMode
(DSI_HandleTypeDef * hdsi, DSI_VidCfgTypeDef * VidCfg)

Function Description

Select video mode and configure the corresponding parameters.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
VidCfg: pointer to a DSI_VidCfgTypeDef structure that
contains the DSI video mode configuration parameters

Return values

HAL: status

HAL_DSI_ConfigAdaptedCommandMode
Function Name

HAL_StatusTypeDef HAL_DSI_ConfigAdaptedCommandMode
(DSI_HandleTypeDef * hdsi, DSI_CmdCfgTypeDef * CmdCfg)

Function Description

Select adapted command mode and configure the corresponding
parameters.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
CmdCfg: pointer to a DSI_CmdCfgTypeDef structure that
contains the DSI command mode configuration parameters

Return values

HAL: status

HAL_DSI_ConfigCommand
Function Name

HAL_StatusTypeDef HAL_DSI_ConfigCommand
(DSI_HandleTypeDef * hdsi, DSI_LPCmdTypeDef * LPCmd)

Function Description

Configure command transmission mode: High-speed or Lowpower and enable/disable acknowledge request after packet
transmission.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
LPCmd: pointer to a DSI_LPCmdTypeDef structure that
contains the DSI command transmission mode configuration
parameters

DocID025834 Rev 4

283/964

HAL DSI Generic Driver
Return values

UM1725
HAL: status

HAL_DSI_ConfigFlowControl
Function Name

HAL_StatusTypeDef HAL_DSI_ConfigFlowControl
(DSI_HandleTypeDef * hdsi, uint32_t FlowControl)

Function Description

Configure the flow control parameters.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
FlowControl: flow control feature(s) to be enabled. This
parameter can be any combination of DSI Flow Control.

Return values

HAL: status

HAL_DSI_ConfigPhyTimer
Function Name

HAL_StatusTypeDef HAL_DSI_ConfigPhyTimer
(DSI_HandleTypeDef * hdsi, DSI_PHY_TimerTypeDef *
PhyTimers)

Function Description

Configure the DSI PHY timer parameters.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
PhyTimers: DSI_PHY_TimerTypeDef structure that contains
the DSI PHY timing parameters

Return values

HAL: status

HAL_DSI_ConfigHostTimeouts
Function Name

HAL_StatusTypeDef HAL_DSI_ConfigHostTimeouts
(DSI_HandleTypeDef * hdsi, DSI_HOST_TimeoutTypeDef *
HostTimeouts)

Function Description

Configure the DSI HOST timeout parameters.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
HostTimeouts: DSI_HOST_TimeoutTypeDef structure that
contains the DSI host timeout parameters

Return values

HAL: status

HAL_DSI_Start

284/964

Function Name

HAL_StatusTypeDef HAL_DSI_Start (DSI_HandleTypeDef *
hdsi)

Function Description

Start the DSI module.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL DSI Generic Driver

HAL_DSI_Stop
Function Name

HAL_StatusTypeDef HAL_DSI_Stop (DSI_HandleTypeDef *
hdsi)

Function Description

Stop the DSI module.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

HAL: status

HAL_DSI_Refresh
Function Name

HAL_StatusTypeDef HAL_DSI_Refresh (DSI_HandleTypeDef *
hdsi)

Function Description

Refresh the display in command mode.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

HAL: status

HAL_DSI_ColorMode
Function Name

HAL_StatusTypeDef HAL_DSI_ColorMode
(DSI_HandleTypeDef * hdsi, uint32_t ColorMode)

Function Description

Controls the display color mode in Video mode.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
ColorMode: Color mode (full or 8-colors). This parameter
can be any value of DSI Color Mode

Return values

HAL: status

HAL_DSI_Shutdown
Function Name

HAL_StatusTypeDef HAL_DSI_Shutdown
(DSI_HandleTypeDef * hdsi, uint32_t Shutdown)

Function Description

Control the display shutdown in Video mode.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
Shutdown: Shut-down (Display-ON or Display-OFF). This
parameter can be any value of DSI ShutDown

Return values

HAL: status

HAL_DSI_ShortWrite
Function Name

HAL_StatusTypeDef HAL_DSI_ShortWrite
(DSI_HandleTypeDef * hdsi, uint32_t ChannelID, uint32_t
Mode, uint32_t Param1, uint32_t Param2)

Function Description

DCS or Generic short write command.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
DocID025834 Rev 4

285/964

HAL DSI Generic Driver

Return values

UM1725
contains the configuration information for the DSI.
ChannelID: Virtual channel ID.
Mode: DSI short packet data type. This parameter can be
any value of DSI SHORT WRITE PKT Data Type.
Param1: DSC command or first generic parameter. This
parameter can be any value of DSI DCS Command or a
generic command code.
Param2: DSC parameter or second generic parameter.
HAL: status

HAL_DSI_LongWrite
Function Name

HAL_StatusTypeDef HAL_DSI_LongWrite
(DSI_HandleTypeDef * hdsi, uint32_t ChannelID, uint32_t
Mode, uint32_t NbParams, uint32_t Param1, uint8_t *
ParametersTable)

Function Description

DCS or Generic long write command.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
ChannelID: Virtual channel ID.
Mode: DSI long packet data type. This parameter can be any
value of DSI LONG WRITE PKT Data Type.
NbParams: Number of parameters.
Param1: DSC command or first generic parameter. This
parameter can be any value of DSI DCS Command or a
generic command code
ParametersTable: Pointer to parameter values table.

Return values

HAL: status

HAL_DSI_Read
Function Name

HAL_StatusTypeDef HAL_DSI_Read (DSI_HandleTypeDef *
hdsi, uint32_t ChannelNbr, uint8_t * Array, uint32_t Size,
uint32_t Mode, uint32_t DCSCmd, uint8_t * ParametersTable)

Function Description

Read command (DCS or generic)

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
ChannelNbr: Virtual channel ID
Array: pointer to a buffer to store the payload of a read back
operation.
Size: Data size to be read (in byte).
Mode: DSI read packet data type. This parameter can be
any value of DSI SHORT READ PKT Data Type.
DCSCmd: DCS get/read command.
ParametersTable: Pointer to parameter values table.

Return values

HAL: status

HAL_DSI_EnterULPMData
Function Name
286/964

HAL_StatusTypeDef HAL_DSI_EnterULPMData
DocID025834 Rev 4

UM1725

HAL DSI Generic Driver
(DSI_HandleTypeDef * hdsi)
Function Description

Enter the ULPM (Ultra Low Power Mode) with the D-PHY PLL
running (only data lanes are in ULPM)

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

HAL: status

HAL_DSI_ExitULPMData
Function Name

HAL_StatusTypeDef HAL_DSI_ExitULPMData
(DSI_HandleTypeDef * hdsi)

Function Description

Exit the ULPM (Ultra Low Power Mode) with the D-PHY PLL
running (only data lanes are in ULPM)

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

HAL: status

HAL_DSI_EnterULPM
Function Name

HAL_StatusTypeDef HAL_DSI_EnterULPM
(DSI_HandleTypeDef * hdsi)

Function Description

Enter the ULPM (Ultra Low Power Mode) with the D-PHY PLL
turned off (both data and clock lanes are in ULPM)

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

HAL: status

HAL_DSI_ExitULPM
Function Name

HAL_StatusTypeDef HAL_DSI_ExitULPM (DSI_HandleTypeDef
* hdsi)

Function Description

Exit the ULPM (Ultra Low Power Mode) with the D-PHY PLL
turned off (both data and clock lanes are in ULPM)

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

HAL: status

HAL_DSI_PatternGeneratorStart
Function Name

HAL_StatusTypeDef HAL_DSI_PatternGeneratorStart
(DSI_HandleTypeDef * hdsi, uint32_t Mode, uint32_t
Orientation)

Function Description

Start test pattern generation.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
Mode: Pattern generator mode This parameter can be one of
the following values: 0 : Color bars (horizontal or vertical) 1 :
DocID025834 Rev 4

287/964

HAL DSI Generic Driver

Return values

UM1725
BER pattern (vertical only)
Orientation: Pattern generator orientation This parameter
can be one of the following values: 0 : Vertical color bars 1 :
Horizontal color bars
HAL: status

HAL_DSI_PatternGeneratorStop
Function Name

HAL_StatusTypeDef HAL_DSI_PatternGeneratorStop
(DSI_HandleTypeDef * hdsi)

Function Description

Stop test pattern generation.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

HAL: status

HAL_DSI_SetSlewRateAndDelayTuning
Function Name

HAL_StatusTypeDef HAL_DSI_SetSlewRateAndDelayTuning
(DSI_HandleTypeDef * hdsi, uint32_t CommDelay, uint32_t
Lane, uint32_t Value)

Function Description

Set Slew-Rate And Delay Tuning.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
CommDelay: Communication delay to be adjusted. This
parameter can be any value of DSI Communication Delay
Lane: select between clock or data lanes. This parameter
can be any value of DSI Lane Group
Value: Custom value of the slew-rate or delay

Return values

HAL: status

HAL_DSI_SetLowPowerRXFilter
Function Name

HAL_StatusTypeDef HAL_DSI_SetLowPowerRXFilter
(DSI_HandleTypeDef * hdsi, uint32_t Frequency)

Function Description

Low-Power Reception Filter Tuning.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
Frequency: cutoff frequency of low-pass filter at the input of
LPRX

Return values

HAL: status

HAL_DSI_SetSDD

288/964

Function Name

HAL_StatusTypeDef HAL_DSI_SetSDD (DSI_HandleTypeDef *
hdsi, FunctionalState State)

Function Description

Activate an additional current path on all lanes to meet the SDDTx
parameter defined in the MIPI D-PHY specification.

DocID025834 Rev 4

UM1725

HAL DSI Generic Driver
Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
State: ENABLE or DISABLE

Return values

HAL: status

HAL_DSI_SetLanePinsConfiguration
Function Name

HAL_StatusTypeDef HAL_DSI_SetLanePinsConfiguration
(DSI_HandleTypeDef * hdsi, uint32_t CustomLane, uint32_t
Lane, FunctionalState State)

Function Description

Custom lane pins configuration.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
CustomLane: Function to be applyed on selected lane. This
parameter can be any value of DSI CustomLane
Lane: select between clock or data lane 0 or data lane 1.
This parameter can be any value of DSI Lane Select
State: ENABLE or DISABLE

Return values

HAL: status

HAL_DSI_SetPHYTimings
Function Name

HAL_StatusTypeDef HAL_DSI_SetPHYTimings
(DSI_HandleTypeDef * hdsi, uint32_t Timing, FunctionalState
State, uint32_t Value)

Function Description

Set custom timing for the PHY.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
Timing: PHY timing to be adjusted. This parameter can be
any value of DSI PHY Timing
State: ENABLE or DISABLE
Value: Custom value of the timing

Return values

HAL: status

HAL_DSI_ForceTXStopMode
Function Name

HAL_StatusTypeDef HAL_DSI_ForceTXStopMode
(DSI_HandleTypeDef * hdsi, uint32_t Lane, FunctionalState
State)

Function Description

Force the Clock/Data Lane in TX Stop Mode.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
Lane: select between clock or data lanes. This parameter
can be any value of DSI Lane Group
State: ENABLE or DISABLE

Return values

HAL: status

DocID025834 Rev 4

289/964

HAL DSI Generic Driver

UM1725

HAL_DSI_ForceRXLowPower
Function Name

HAL_StatusTypeDef HAL_DSI_ForceRXLowPower
(DSI_HandleTypeDef * hdsi, FunctionalState State)

Function Description

Forces LP Receiver in Low-Power Mode.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
State: ENABLE or DISABLE

Return values

HAL: status

HAL_DSI_ForceDataLanesInRX
Function Name

HAL_StatusTypeDef HAL_DSI_ForceDataLanesInRX
(DSI_HandleTypeDef * hdsi, FunctionalState State)

Function Description

Force Data Lanes in RX Mode after a BTA.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
State: ENABLE or DISABLE

Return values

HAL: status

HAL_DSI_SetPullDown
Function Name

HAL_StatusTypeDef HAL_DSI_SetPullDown
(DSI_HandleTypeDef * hdsi, FunctionalState State)

Function Description

Enable a pull-down on the lanes to prevent from floating states
when unused.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
State: ENABLE or DISABLE

Return values

HAL: status

HAL_DSI_SetContentionDetectionOff
Function Name

HAL_StatusTypeDef HAL_DSI_SetContentionDetectionOff
(DSI_HandleTypeDef * hdsi, FunctionalState State)

Function Description

Switch off the contention detection on data lanes.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
State: ENABLE or DISABLE

Return values

HAL: status

HAL_DSI_GetError
Function Name

uint32_t HAL_DSI_GetError (DSI_HandleTypeDef * hdsi)

Function Description

Return the DSI error code.

Parameters

290/964

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
DocID025834 Rev 4

UM1725

HAL DSI Generic Driver
Return values

DSI: Error Code

HAL_DSI_ConfigErrorMonitor
Function Name

HAL_StatusTypeDef HAL_DSI_ConfigErrorMonitor
(DSI_HandleTypeDef * hdsi, uint32_t ActiveErrors)

Function Description

Enable the error monitor flags.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.
ActiveErrors: indicates which error interrupts will be
enabled. This parameter can be any combination of DSI Error
Data Type.

Return values

HAL: status

HAL_DSI_GetState
Function Name

HAL_DSI_StateTypeDef HAL_DSI_GetState
(DSI_HandleTypeDef * hdsi)

Function Description

Return the DSI state.

Parameters

hdsi: pointer to a DSI_HandleTypeDef structure that
contains the configuration information for the DSI.

Return values

HAL: state

20.3

DSI Firmware driver defines

20.3.1

DSI
DSI Acknowledge Request
DSI_ACKNOWLEDGE_DISABLE
DSI_ACKNOWLEDGE_ENABLE
DSI Automatic Refresh
DSI_AR_DISABLE
DSI_AR_ENABLE
DSI Automatic Clk Lane Control
DSI_AUTO_CLK_LANE_CTRL_DISABLE
DSI_AUTO_CLK_LANE_CTRL_ENABLE
DSI Color Coding
DSI_RGB565

The values 0x00000001U and 0x00000002U can also be used for
the RGB565 color mode configuration

DSI_RGB666

The value 0x00000004U can also be used for the RGB666 color
mode configuration

DSI_RGB888
DSI Color Mode

DocID025834 Rev 4

291/964

HAL DSI Generic Driver
DSI_COLOR_MODE_FULL

UM1725

DSI_COLOR_MODE_EIGHT
DSI Communication Delay
DSI_SLEW_RATE_HSTX
DSI_SLEW_RATE_LPTX
DSI_HS_DELAY
DSI CustomLane
DSI_SWAP_LANE_PINS
DSI_INVERT_HS_SIGNAL
DSI DATA ENABLE Polarity
DSI_DATA_ENABLE_ACTIVE_HIGH
DSI_DATA_ENABLE_ACTIVE_LOW
DSI DCS Command
DSI_ENTER_IDLE_MODE
DSI_ENTER_INVERT_MODE
DSI_ENTER_NORMAL_MODE
DSI_ENTER_PARTIAL_MODE
DSI_ENTER_SLEEP_MODE
DSI_EXIT_IDLE_MODE
DSI_EXIT_INVERT_MODE
DSI_EXIT_SLEEP_MODE
DSI_GET_3D_CONTROL
DSI_GET_ADDRESS_MODE
DSI_GET_BLUE_CHANNEL
DSI_GET_DIAGNOSTIC_RESULT
DSI_GET_DISPLAY_MODE
DSI_GET_GREEN_CHANNEL
DSI_GET_PIXEL_FORMAT
DSI_GET_POWER_MODE
DSI_GET_RED_CHANNEL
DSI_GET_SCANLINE
DSI_GET_SIGNAL_MODE
DSI_NOP
DSI_READ_DDB_CONTINUE
DSI_READ_DDB_START
DSI_READ_MEMORY_CONTINUE

292/964

DocID025834 Rev 4

UM1725

HAL DSI Generic Driver
DSI_READ_MEMORY_START
DSI_SET_3D_CONTROL
DSI_SET_ADDRESS_MODE
DSI_SET_COLUMN_ADDRESS
DSI_SET_DISPLAY_OFF
DSI_SET_DISPLAY_ON
DSI_SET_GAMMA_CURVE
DSI_SET_PAGE_ADDRESS
DSI_SET_PARTIAL_COLUMNS
DSI_SET_PARTIAL_ROWS
DSI_SET_PIXEL_FORMAT
DSI_SET_SCROLL_AREA
DSI_SET_SCROLL_START
DSI_SET_TEAR_OFF
DSI_SET_TEAR_ON
DSI_SET_TEAR_SCANLINE
DSI_SET_VSYNC_TIMING
DSI_SOFT_RESET
DSI_WRITE_LUT
DSI_WRITE_MEMORY_CONTINUE
DSI_WRITE_MEMORY_START
DSI Error Data Type
HAL_DSI_ERROR_NONE
HAL_DSI_ERROR_ACK

acknowledge errors

HAL_DSI_ERROR_PHY

PHY related errors

HAL_DSI_ERROR_TX

transmission error

HAL_DSI_ERROR_RX

reception error

HAL_DSI_ERROR_ECC

ECC errors

HAL_DSI_ERROR_CRC

CRC error

HAL_DSI_ERROR_PSE

Packet Size error

HAL_DSI_ERROR_EOT

End Of Transmission error

HAL_DSI_ERROR_OVF

FIFO overflow error

HAL_DSI_ERROR_GEN

Generic FIFO related errors

DSI FBTA Acknowledge
DSI_FBTAA_DISABLE
DSI_FBTAA_ENABLE
DSI Flags
DocID025834 Rev 4

293/964

HAL DSI Generic Driver
DSI_FLAG_TE

UM1725

DSI_FLAG_ER
DSI_FLAG_BUSY
DSI_FLAG_PLLLS
DSI_FLAG_PLLL
DSI_FLAG_PLLU
DSI_FLAG_RRS
DSI_FLAG_RR
DSI Flow Control
DSI_FLOW_CONTROL_CRC_RX
DSI_FLOW_CONTROL_ECC_RX
DSI_FLOW_CONTROL_BTA
DSI_FLOW_CONTROL_EOTP_RX
DSI_FLOW_CONTROL_EOTP_TX
DSI_FLOW_CONTROL_ALL
DSI HSYNC Polarity
DSI_HSYNC_ACTIVE_HIGH
DSI_HSYNC_ACTIVE_LOW
DSI HS Presp Mode
DSI_HS_PM_DISABLE
DSI_HS_PM_ENABLE
DSI Interrupts
DSI_IT_TE
DSI_IT_ER
DSI_IT_PLLL
DSI_IT_PLLU
DSI_IT_RR
DSI Lane Group
DSI_CLOCK_LANE
DSI_CLOCK_LANE
DSI_DATA_LANES
DSI Lane Select
DSI_DATA_LANE0
DSI_DATA_LANE1
DSI LONG WRITE PKT Data Type
DSI_DCS_LONG_PKT_WRITE

294/964

DCS long write

DocID025834 Rev 4

UM1725

HAL DSI Generic Driver
DSI_GEN_LONG_PKT_WRITE

Generic long write

DSI Loosely Packed
DSI_LOOSELY_PACKED_ENABLE
DSI_LOOSELY_PACKED_DISABLE
DSI LP Command
DSI_LP_COMMAND_DISABLE
DSI_LP_COMMAND_ENABLE
DSI LP HBP
DSI_LP_HBP_DISABLE
DSI_LP_HBP_ENABLE
DSI LP HFP
DSI_LP_HFP_DISABLE
DSI_LP_HFP_ENABLE
DSI LP LPDcs Long Write
DSI_LP_DLW_DISABLE
DSI_LP_DLW_ENABLE
DSI LP LPDcs Short Read NoP
DSI_LP_DSR0P_DISABLE
DSI_LP_DSR0P_ENABLE
DSI LP LPDcs Short Write NoP
DSI_LP_DSW0P_DISABLE
DSI_LP_DSW0P_ENABLE
DSI LP LPDcs Short Write OneP
DSI_LP_DSW1P_DISABLE
DSI_LP_DSW1P_ENABLE
DSI LP LPGen LongWrite
DSI_LP_GLW_DISABLE
DSI_LP_GLW_ENABLE
DSI LP LPGen Short Read NoP
DSI_LP_GSR0P_DISABLE
DSI_LP_GSR0P_ENABLE

DSI LP LPGen Short Read OneP
DSI_LP_GSR1P_DISABLE
DSI_LP_GSR1P_ENABLE
DSI LP LPGen Short Read TwoP
DocID025834 Rev 4

295/964

HAL DSI Generic Driver
DSI_LP_GSR2P_DISABLE

UM1725

DSI_LP_GSR2P_ENABLE
DSI LP LPGen Short Write NoP
DSI_LP_GSW0P_DISABLE
DSI_LP_GSW0P_ENABLE
DSI LP LPGen Short Write OneP
DSI_LP_GSW1P_DISABLE
DSI_LP_GSW1P_ENABLE
DSI LP LPGen Short Write TwoP
DSI_LP_GSW2P_DISABLE
DSI_LP_GSW2P_ENABLE
DSI LP LPMax Read Packet
DSI_LP_MRDP_DISABLE
DSI_LP_MRDP_ENABLE
DSI LP VACT
DSI_LP_VACT_DISABLE
DSI_LP_VACT_ENABLE
DSI LP VBP
DSI_LP_VBP_DISABLE
DSI_LP_VBP_ENABLE
DSI LP VFP
DSI_LP_VFP_DISABLE
DSI_LP_VFP_ENABLE
DSI LP VSYNC
DSI_LP_VSYNC_DISABLE
DSI_LP_VSYNC_ENABLE
DSI Number Of Lanes
DSI_ONE_DATA_LANE
DSI_TWO_DATA_LANES
DSI PHY Timing
DSI_TCLK_POST
DSI_TLPX_CLK
DSI_THS_EXIT
DSI_TLPX_DATA
DSI_THS_ZERO
DSI_THS_TRAIL

296/964

DocID025834 Rev 4

UM1725

HAL DSI Generic Driver
DSI_THS_PREPARE
DSI_TCLK_ZERO
DSI_TCLK_PREPARE
DSI PLL IDF
DSI_PLL_IN_DIV1
DSI_PLL_IN_DIV2
DSI_PLL_IN_DIV3
DSI_PLL_IN_DIV4
DSI_PLL_IN_DIV5
DSI_PLL_IN_DIV6
DSI_PLL_IN_DIV7
DSI PLL ODF
DSI_PLL_OUT_DIV1
DSI_PLL_OUT_DIV2
DSI_PLL_OUT_DIV4
DSI_PLL_OUT_DIV8
DSI SHORT READ PKT Data Type
DSI_DCS_SHORT_PKT_READ

DCS short read

DSI_GEN_SHORT_PKT_READ_P0

Generic short read, no parameters

DSI_GEN_SHORT_PKT_READ_P1

Generic short read, one parameter

DSI_GEN_SHORT_PKT_READ_P2

Generic short read, two parameters

DSI SHORT WRITE PKT Data Type
DSI_DCS_SHORT_PKT_WRITE_P0

DCS short write, no parameters

DSI_DCS_SHORT_PKT_WRITE_P1

DCS short write, one parameter

DSI_GEN_SHORT_PKT_WRITE_P0

Generic short write, no parameters

DSI_GEN_SHORT_PKT_WRITE_P1

Generic short write, one parameter

DSI_GEN_SHORT_PKT_WRITE_P2

Generic short write, two parameters

DSI ShutDown
DSI_DISPLAY_ON
DSI_DISPLAY_OFF
DSI Tearing Effect Polarity
DSI_TE_RISING_EDGE
DSI_TE_FALLING_EDGE
DSI Tearing Effect Source
DSI_TE_DSILINK
DSI_TE_EXTERNAL
DSI TE Acknowledge Request
DocID025834 Rev 4

297/964

HAL DSI Generic Driver
DSI_TE_ACKNOWLEDGE_DISABLE
DSI_TE_ACKNOWLEDGE_ENABLE
DSI Video Mode Type
DSI_VID_MODE_NB_PULSES
DSI_VID_MODE_NB_EVENTS
DSI_VID_MODE_BURST
DSI VSYNC Active Polarity
DSI_VSYNC_ACTIVE_HIGH
DSI_VSYNC_ACTIVE_LOW
DSI Vsync Polarity
DSI_VSYNC_FALLING
DSI_VSYNC_RISING

298/964

DocID025834 Rev 4

UM1725

UM1725

HAL ETH Generic Driver

21

HAL ETH Generic Driver

21.1

ETH Firmware driver registers structures

21.1.1

ETH_InitTypeDef
Data Fields
uint32_t AutoNegotiation
uint32_t Speed
uint32_t DuplexMode
uint16_t PhyAddress
uint8_t * MACAddr
uint32_t RxMode
uint32_t ChecksumMode
uint32_t MediaInterface

Field Documentation
uint32_t ETH_InitTypeDef::AutoNegotiation
Selects or not the AutoNegotiation mode for the external PHY The AutoNegotiation
allows an automatic setting of the Speed (10/100Mbps) and the mode (half/fullduplex). This parameter can be a value of ETH_AutoNegotiation
uint32_t ETH_InitTypeDef::Speed
Sets the Ethernet speed: 10/100 Mbps. This parameter can be a value of
ETH_Speed
uint32_t ETH_InitTypeDef::DuplexMode
Selects the MAC duplex mode: Half-Duplex or Full-Duplex mode This parameter can
be a value of ETH_Duplex_Mode
uint16_t ETH_InitTypeDef::PhyAddress
Ethernet PHY address. This parameter must be a number between Min_Data = 0 and
Max_Data = 32
uint8_t* ETH_InitTypeDef::MACAddr
MAC Address of used Hardware: must be pointer on an array of 6 bytes
uint32_t ETH_InitTypeDef::RxMode
Selects the Ethernet Rx mode: Polling mode, Interrupt mode. This parameter can be
a value of ETH_Rx_Mode
uint32_t ETH_InitTypeDef::ChecksumMode
Selects if the checksum is check by hardware or by software. This parameter can be
a value of ETH_Checksum_Mode
uint32_t ETH_InitTypeDef::MediaInterface
Selects the media-independent interface or the reduced media-independent interface.
This parameter can be a value of ETH_Media_Interface

DocID025834 Rev 4

299/964

HAL ETH Generic Driver

21.1.2

UM1725

ETH_MACInitTypeDef
Data Fields
uint32_t Watchdog
uint32_t Jabber
uint32_t InterFrameGap
uint32_t CarrierSense
uint32_t ReceiveOwn
uint32_t LoopbackMode
uint32_t ChecksumOffload
uint32_t RetryTransmission
uint32_t AutomaticPadCRCStrip
uint32_t BackOffLimit
uint32_t DeferralCheck
uint32_t ReceiveAll
uint32_t SourceAddrFilter
uint32_t PassControlFrames
uint32_t BroadcastFramesReception
uint32_t DestinationAddrFilter
uint32_t PromiscuousMode
uint32_t MulticastFramesFilter
uint32_t UnicastFramesFilter
uint32_t HashTableHigh
uint32_t HashTableLow
uint32_t PauseTime
uint32_t ZeroQuantaPause
uint32_t PauseLowThreshold
uint32_t UnicastPauseFrameDetect
uint32_t ReceiveFlowControl
uint32_t TransmitFlowControl
uint32_t VLANTagComparison
uint32_t VLANTagIdentifier

Field Documentation
uint32_t ETH_MACInitTypeDef::Watchdog
Selects or not the Watchdog timer When enabled, the MAC allows no more then 2048
bytes to be received. When disabled, the MAC can receive up to 16384 bytes. This
parameter can be a value of ETH_Watchdog
uint32_t ETH_MACInitTypeDef::Jabber
Selects or not Jabber timer When enabled, the MAC allows no more then 2048 bytes
to be sent. When disabled, the MAC can send up to 16384 bytes. This parameter can
be a value of ETH_Jabber
uint32_t ETH_MACInitTypeDef::InterFrameGap
Selects the minimum IFG between frames during transmission. This parameter can
be a value of ETH_Inter_Frame_Gap
uint32_t ETH_MACInitTypeDef::CarrierSense
Selects or not the Carrier Sense. This parameter can be a value of
ETH_Carrier_Sense
300/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
uint32_t ETH_MACInitTypeDef::ReceiveOwn
Selects or not the ReceiveOwn, ReceiveOwn allows the reception of frames when the
TX_EN signal is asserted in Half-Duplex mode. This parameter can be a value of
ETH_Receive_Own
uint32_t ETH_MACInitTypeDef::LoopbackMode
Selects or not the internal MAC MII Loopback mode. This parameter can be a value
of ETH_Loop_Back_Mode
uint32_t ETH_MACInitTypeDef::ChecksumOffload
Selects or not the IPv4 checksum checking for received frame payloads'
TCP/UDP/ICMP headers. This parameter can be a value of ETH_Checksum_Offload
uint32_t ETH_MACInitTypeDef::RetryTransmission
Selects or not the MAC attempt retries transmission, based on the settings of BL,
when a collision occurs (Half-Duplex mode). This parameter can be a value of
ETH_Retry_Transmission
uint32_t ETH_MACInitTypeDef::AutomaticPadCRCStrip
Selects or not the Automatic MAC Pad/CRC Stripping. This parameter can be a value
of ETH_Automatic_Pad_CRC_Strip
uint32_t ETH_MACInitTypeDef::BackOffLimit
Selects the BackOff limit value. This parameter can be a value of
ETH_Back_Off_Limit
uint32_t ETH_MACInitTypeDef::DeferralCheck
Selects or not the deferral check function (Half-Duplex mode). This parameter can be
a value of ETH_Deferral_Check
uint32_t ETH_MACInitTypeDef::ReceiveAll
Selects or not all frames reception by the MAC (No filtering). This parameter can be a
value of ETH_Receive_All
uint32_t ETH_MACInitTypeDef::SourceAddrFilter
Selects the Source Address Filter mode. This parameter can be a value of
ETH_Source_Addr_Filter
uint32_t ETH_MACInitTypeDef::PassControlFrames
Sets the forwarding mode of the control frames (including unicast and multicast
PAUSE frames) This parameter can be a value of ETH_Pass_Control_Frames
uint32_t ETH_MACInitTypeDef::BroadcastFramesReception
Selects or not the reception of Broadcast Frames. This parameter can be a value of
ETH_Broadcast_Frames_Reception
uint32_t ETH_MACInitTypeDef::DestinationAddrFilter
Sets the destination filter mode for both unicast and multicast frames. This parameter
can be a value of ETH_Destination_Addr_Filter
uint32_t ETH_MACInitTypeDef::PromiscuousMode
Selects or not the Promiscuous Mode This parameter can be a value of
ETH_Promiscuous_Mode
uint32_t ETH_MACInitTypeDef::MulticastFramesFilter
Selects the Multicast Frames filter mode:
None/HashTableFilter/PerfectFilter/PerfectHashTableFilter. This parameter can be a
value of ETH_Multicast_Frames_Filter
uint32_t ETH_MACInitTypeDef::UnicastFramesFilter
Selects the Unicast Frames filter mode:
HashTableFilter/PerfectFilter/PerfectHashTableFilter. This parameter can be a value
of ETH_Unicast_Frames_Filter
uint32_t ETH_MACInitTypeDef::HashTableHigh
This field holds the higher 32 bits of Hash table. This parameter must be a number
between Min_Data = 0x0 and Max_Data = 0xFFFFFFFFU

DocID025834 Rev 4

301/964

HAL ETH Generic Driver

UM1725

uint32_t ETH_MACInitTypeDef::HashTableLow
This field holds the lower 32 bits of Hash table. This parameter must be a number
between Min_Data = 0x0 and Max_Data = 0xFFFFFFFFU
uint32_t ETH_MACInitTypeDef::PauseTime
This field holds the value to be used in the Pause Time field in the transmit control
frame. This parameter must be a number between Min_Data = 0x0 and Max_Data =
0xFFFFU
uint32_t ETH_MACInitTypeDef::ZeroQuantaPause
Selects or not the automatic generation of Zero-Quanta Pause Control frames. This
parameter can be a value of ETH_Zero_Quanta_Pause
uint32_t ETH_MACInitTypeDef::PauseLowThreshold
This field configures the threshold of the PAUSE to be checked for automatic
retransmission of PAUSE Frame. This parameter can be a value of
ETH_Pause_Low_Threshold
uint32_t ETH_MACInitTypeDef::UnicastPauseFrameDetect
Selects or not the MAC detection of the Pause frames (with MAC Address0 unicast
address and unique multicast address). This parameter can be a value of
ETH_Unicast_Pause_Frame_Detect
uint32_t ETH_MACInitTypeDef::ReceiveFlowControl
Enables or disables the MAC to decode the received Pause frame and disable its
transmitter for a specified time (Pause Time) This parameter can be a value of
ETH_Receive_Flow_Control
uint32_t ETH_MACInitTypeDef::TransmitFlowControl
Enables or disables the MAC to transmit Pause frames (Full-Duplex mode) or the
MAC back-pressure operation (Half-Duplex mode) This parameter can be a value of
ETH_Transmit_Flow_Control
uint32_t ETH_MACInitTypeDef::VLANTagComparison
Selects the 12-bit VLAN identifier or the complete 16-bit VLAN tag for comparison
and filtering. This parameter can be a value of ETH_VLAN_Tag_Comparison
uint32_t ETH_MACInitTypeDef::VLANTagIdentifier
Holds the VLAN tag identifier for receive frames

21.1.3

ETH_DMAInitTypeDef
Data Fields
uint32_t DropTCPIPChecksumErrorFrame
uint32_t ReceiveStoreForward
uint32_t FlushReceivedFrame
uint32_t TransmitStoreForward
uint32_t TransmitThresholdControl
uint32_t ForwardErrorFrames
uint32_t ForwardUndersizedGoodFrames
uint32_t ReceiveThresholdControl
uint32_t SecondFrameOperate
uint32_t AddressAlignedBeats
uint32_t FixedBurst
uint32_t RxDMABurstLength
uint32_t TxDMABurstLength
uint32_t EnhancedDescriptorFormat
uint32_t DescriptorSkipLength
uint32_t DMAArbitration

302/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
Field Documentation
uint32_t ETH_DMAInitTypeDef::DropTCPIPChecksumErrorFrame
Selects or not the Dropping of TCP/IP Checksum Error Frames. This parameter can
be a value of ETH_Drop_TCP_IP_Checksum_Error_Frame
uint32_t ETH_DMAInitTypeDef::ReceiveStoreForward
Enables or disables the Receive store and forward mode. This parameter can be a
value of ETH_Receive_Store_Forward
uint32_t ETH_DMAInitTypeDef::FlushReceivedFrame
Enables or disables the flushing of received frames. This parameter can be a value of
ETH_Flush_Received_Frame
uint32_t ETH_DMAInitTypeDef::TransmitStoreForward
Enables or disables Transmit store and forward mode. This parameter can be a value
of ETH_Transmit_Store_Forward
uint32_t ETH_DMAInitTypeDef::TransmitThresholdControl
Selects or not the Transmit Threshold Control. This parameter can be a value of
ETH_Transmit_Threshold_Control
uint32_t ETH_DMAInitTypeDef::ForwardErrorFrames
Selects or not the forward to the DMA of erroneous frames. This parameter can be a
value of ETH_Forward_Error_Frames
uint32_t ETH_DMAInitTypeDef::ForwardUndersizedGoodFrames
Enables or disables the Rx FIFO to forward Undersized frames (frames with no Error
and length less than 64 bytes) including pad-bytes and CRC) This parameter can be a
value of ETH_Forward_Undersized_Good_Frames
uint32_t ETH_DMAInitTypeDef::ReceiveThresholdControl
Selects the threshold level of the Receive FIFO. This parameter can be a value of
ETH_Receive_Threshold_Control
uint32_t ETH_DMAInitTypeDef::SecondFrameOperate
Selects or not the Operate on second frame mode, which allows the DMA to process
a second frame of Transmit data even before obtaining the status for the first frame.
This parameter can be a value of ETH_Second_Frame_Operate
uint32_t ETH_DMAInitTypeDef::AddressAlignedBeats
Enables or disables the Address Aligned Beats. This parameter can be a value of
ETH_Address_Aligned_Beats
uint32_t ETH_DMAInitTypeDef::FixedBurst
Enables or disables the AHB Master interface fixed burst transfers. This parameter
can be a value of ETH_Fixed_Burst
uint32_t ETH_DMAInitTypeDef::RxDMABurstLength
Indicates the maximum number of beats to be transferred in one Rx DMA transaction.
This parameter can be a value of ETH_Rx_DMA_Burst_Length
uint32_t ETH_DMAInitTypeDef::TxDMABurstLength
Indicates the maximum number of beats to be transferred in one Tx DMA transaction.
This parameter can be a value of ETH_Tx_DMA_Burst_Length
uint32_t ETH_DMAInitTypeDef::EnhancedDescriptorFormat
Enables the enhanced descriptor format. This parameter can be a value of
ETH_DMA_Enhanced_descriptor_format
uint32_t ETH_DMAInitTypeDef::DescriptorSkipLength
Specifies the number of word to skip between two unchained descriptors (Ring mode)
This parameter must be a number between Min_Data = 0 and Max_Data = 32
uint32_t ETH_DMAInitTypeDef::DMAArbitration
Selects the DMA Tx/Rx arbitration. This parameter can be a value of
ETH_DMA_Arbitration

DocID025834 Rev 4

303/964

HAL ETH Generic Driver

21.1.4

UM1725

ETH_DMADescTypeDef
Data Fields
__IO uint32_t Status
uint32_t ControlBufferSize
uint32_t Buffer1Addr
uint32_t Buffer2NextDescAddr
uint32_t ExtendedStatus
uint32_t Reserved1
uint32_t TimeStampLow
uint32_t TimeStampHigh

Field Documentation
__IO uint32_t ETH_DMADescTypeDef::Status
Status
uint32_t ETH_DMADescTypeDef::ControlBufferSize
Control and Buffer1, Buffer2 lengths
uint32_t ETH_DMADescTypeDef::Buffer1Addr
Buffer1 address pointer
uint32_t ETH_DMADescTypeDef::Buffer2NextDescAddr
Buffer2 or next descriptor address pointer Enhanced ETHERNET DMA PTP
Descriptors
uint32_t ETH_DMADescTypeDef::ExtendedStatus
Extended status for PTP receive descriptor
uint32_t ETH_DMADescTypeDef::Reserved1
Reserved
uint32_t ETH_DMADescTypeDef::TimeStampLow
Time Stamp Low value for transmit and receive
uint32_t ETH_DMADescTypeDef::TimeStampHigh
Time Stamp High value for transmit and receive

21.1.5

ETH_DMARxFrameInfos
Data Fields
ETH_DMADescTypeDef * FSRxDesc
ETH_DMADescTypeDef * LSRxDesc
uint32_t SegCount
uint32_t length
uint32_t buffer

Field Documentation
ETH_DMADescTypeDef* ETH_DMARxFrameInfos::FSRxDesc
First Segment Rx Desc
ETH_DMADescTypeDef* ETH_DMARxFrameInfos::LSRxDesc
Last Segment Rx Desc

304/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
uint32_t ETH_DMARxFrameInfos::SegCount
Segment count
uint32_t ETH_DMARxFrameInfos::length
Frame length
uint32_t ETH_DMARxFrameInfos::buffer
Frame buffer

21.1.6

ETH_HandleTypeDef
Data Fields
ETH_TypeDef * Instance
ETH_InitTypeDef Init
uint32_t LinkStatus
ETH_DMADescTypeDef * RxDesc
ETH_DMADescTypeDef * TxDesc
ETH_DMARxFrameInfos RxFrameInfos
__IO HAL_ETH_StateTypeDef State
HAL_LockTypeDef Lock

Field Documentation
ETH_TypeDef* ETH_HandleTypeDef::Instance
Register base address
ETH_InitTypeDef ETH_HandleTypeDef::Init
Ethernet Init Configuration
uint32_t ETH_HandleTypeDef::LinkStatus
Ethernet link status
ETH_DMADescTypeDef* ETH_HandleTypeDef::RxDesc
Rx descriptor to Get
ETH_DMADescTypeDef* ETH_HandleTypeDef::TxDesc
Tx descriptor to Set
ETH_DMARxFrameInfos ETH_HandleTypeDef::RxFrameInfos
last Rx frame infos
__IO HAL_ETH_StateTypeDef ETH_HandleTypeDef::State
ETH communication state
HAL_LockTypeDef ETH_HandleTypeDef::Lock
ETH Lock

21.2

ETH Firmware driver API description

21.2.1

How to use this driver
1.
2.
3.
4.

Declare a ETH_HandleTypeDef handle structure, for example: ETH_HandleTypeDef
heth;
Fill parameters of Init structure in heth handle
Call HAL_ETH_Init() API to initialize the Ethernet peripheral (MAC, DMA, ...)
Initialize the ETH low level resources through the HAL_ETH_MspInit() API:
a.
Enable the Ethernet interface clock using
DocID025834 Rev 4

305/964

HAL ETH Generic Driver

UM1725

__HAL_RCC_ETHMAC_CLK_ENABLE();
__HAL_RCC_ETHMACTX_CLK_ENABLE();
__HAL_RCC_ETHMACRX_CLK_ENABLE();
b.
Initialize the related GPIO clocks
c.
Configure Ethernet pin-out
d.
Configure Ethernet NVIC interrupt (IT mode)
5. Initialize Ethernet DMA Descriptors in chain mode and point to allocated buffers:
a.
HAL_ETH_DMATxDescListInit(); for Transmission process
b.
HAL_ETH_DMARxDescListInit(); for Reception process
6. Enable MAC and DMA transmission and reception:
a.
HAL_ETH_Start();
7. Prepare ETH DMA TX Descriptors and give the hand to ETH DMA to transfer the
frame to MAC TX FIFO:
a.
HAL_ETH_TransmitFrame();
8. Poll for a received frame in ETH RX DMA Descriptors and get received frame
parameters
a.
HAL_ETH_GetReceivedFrame(); (should be called into an infinite loop)
9.
Get a received frame when an ETH RX interrupt occurs:
a.
HAL_ETH_GetReceivedFrame_IT(); (called in IT mode only)
10. Communicate with external PHY device:
a.
Read a specific register from the PHY HAL_ETH_ReadPHYRegister();
b.
Write data to a specific RHY register: HAL_ETH_WritePHYRegister();
11. Configure the Ethernet MAC after ETH peripheral initialization
HAL_ETH_ConfigMAC(); all MAC parameters should be filled.
12. Configure the Ethernet DMA after ETH peripheral initialization
HAL_ETH_ConfigDMA(); all DMA parameters should be filled. The PTP protocol and
the DMA descriptors ring mode are not supported in this driver

21.2.2

Initialization and de-initialization functions
This section provides functions allowing to:
Initialize and configure the Ethernet peripheral
De-initialize the Ethernet peripheral
This section contains the following APIs:
HAL_ETH_Init()
HAL_ETH_DeInit()
HAL_ETH_DMATxDescListInit()
HAL_ETH_DMARxDescListInit()
HAL_ETH_MspInit()
HAL_ETH_MspDeInit()

21.2.3

IO operation functions
This section provides functions allowing to:
Transmit a frame HAL_ETH_TransmitFrame();
Receive a frame HAL_ETH_GetReceivedFrame();
HAL_ETH_GetReceivedFrame_IT();
Read from an External PHY register HAL_ETH_ReadPHYRegister();
Write to an External PHY register HAL_ETH_WritePHYRegister();
This section contains the following APIs:
HAL_ETH_TransmitFrame()
HAL_ETH_GetReceivedFrame()

306/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
HAL_ETH_GetReceivedFrame_IT()
HAL_ETH_IRQHandler()
HAL_ETH_TxCpltCallback()
HAL_ETH_RxCpltCallback()
HAL_ETH_ErrorCallback()
HAL_ETH_ReadPHYRegister()
HAL_ETH_WritePHYRegister()

21.2.4

Peripheral Control functions
This section provides functions allowing to:
Enable MAC and DMA transmission and reception. HAL_ETH_Start();
Disable MAC and DMA transmission and reception. HAL_ETH_Stop();
Set the MAC configuration in runtime mode HAL_ETH_ConfigMAC();
Set the DMA configuration in runtime mode HAL_ETH_ConfigDMA();
This section contains the following APIs:
HAL_ETH_Start()
HAL_ETH_Stop()
HAL_ETH_ConfigMAC()
HAL_ETH_ConfigDMA()

21.2.5

Peripheral State functions
This subsection permits to get in run-time the status of the peripheral and the data flow.
Get the ETH handle state: HAL_ETH_GetState();
This section contains the following APIs:
HAL_ETH_GetState()

21.2.6

Detailed description of functions
HAL_ETH_Init
Function Name

HAL_StatusTypeDef HAL_ETH_Init (ETH_HandleTypeDef *
heth)

Function Description

Initializes the Ethernet MAC and DMA according to default
parameters.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

HAL: status

HAL_ETH_DeInit
Function Name

HAL_StatusTypeDef HAL_ETH_DeInit (ETH_HandleTypeDef *
heth)

Function Description

De-Initializes the ETH peripheral.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

HAL: status

DocID025834 Rev 4

307/964

HAL ETH Generic Driver

UM1725

HAL_ETH_MspInit
Function Name

void HAL_ETH_MspInit (ETH_HandleTypeDef * heth)

Function Description

Initializes the ETH MSP.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

None

HAL_ETH_MspDeInit
Function Name

void HAL_ETH_MspDeInit (ETH_HandleTypeDef * heth)

Function Description

DeInitializes ETH MSP.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

None

HAL_ETH_DMATxDescListInit
Function Name

HAL_StatusTypeDef HAL_ETH_DMATxDescListInit
(ETH_HandleTypeDef * heth, ETH_DMADescTypeDef *
DMATxDescTab, uint8_t * TxBuff, uint32_t TxBuffCount)

Function Description

Initializes the DMA Tx descriptors in chain mode.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module
DMATxDescTab: Pointer to the first Tx desc list
TxBuff: Pointer to the first TxBuffer list
TxBuffCount: Number of the used Tx desc in the list

Return values

HAL: status

HAL_ETH_DMARxDescListInit
Function Name

HAL_StatusTypeDef HAL_ETH_DMARxDescListInit
(ETH_HandleTypeDef * heth, ETH_DMADescTypeDef *
DMARxDescTab, uint8_t * RxBuff, uint32_t RxBuffCount)

Function Description

Initializes the DMA Rx descriptors in chain mode.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module
DMARxDescTab: Pointer to the first Rx desc list
RxBuff: Pointer to the first RxBuffer list
RxBuffCount: Number of the used Rx desc in the list

Return values

HAL: status

HAL_ETH_TransmitFrame

308/964

Function Name

HAL_StatusTypeDef HAL_ETH_TransmitFrame
(ETH_HandleTypeDef * heth, uint32_t FrameLength)

Function Description

Sends an Ethernet frame.
DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module
FrameLength: Amount of data to be sent

Return values

HAL: status

HAL_ETH_GetReceivedFrame
Function Name

HAL_StatusTypeDef HAL_ETH_GetReceivedFrame
(ETH_HandleTypeDef * heth)

Function Description

Checks for received frames.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

HAL: status

HAL_ETH_ReadPHYRegister
Function Name

HAL_StatusTypeDef HAL_ETH_ReadPHYRegister
(ETH_HandleTypeDef * heth, uint16_t PHYReg, uint32_t *
RegValue)

Function Description

Reads a PHY register.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module
PHYReg: PHY register address, is the index of one of the 32
PHY register. This parameter can be one of the following
values: PHY_BCR: Transceiver Basic Control Register,
PHY_BSR: Transceiver Basic Status Register. More PHY
register could be read depending on the used PHY
RegValue: PHY register value

Return values

HAL: status

HAL_ETH_WritePHYRegister
Function Name

HAL_StatusTypeDef HAL_ETH_WritePHYRegister
(ETH_HandleTypeDef * heth, uint16_t PHYReg, uint32_t
RegValue)

Function Description

Writes to a PHY register.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module
PHYReg: PHY register address, is the index of one of the 32
PHY register. This parameter can be one of the following
values: PHY_BCR: Transceiver Control Register. More PHY
register could be written depending on the used PHY
RegValue: the value to write

Return values

HAL: status

HAL_ETH_GetReceivedFrame_IT
Function Name

HAL_StatusTypeDef HAL_ETH_GetReceivedFrame_IT

DocID025834 Rev 4

309/964

HAL ETH Generic Driver

UM1725
(ETH_HandleTypeDef * heth)

Function Description

Gets the Received frame in interrupt mode.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

HAL: status

HAL_ETH_IRQHandler
Function Name

void HAL_ETH_IRQHandler (ETH_HandleTypeDef * heth)

Function Description

This function handles ETH interrupt request.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

HAL: status

HAL_ETH_TxCpltCallback
Function Name

void HAL_ETH_TxCpltCallback (ETH_HandleTypeDef * heth)

Function Description

Tx Transfer completed callbacks.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

None

HAL_ETH_RxCpltCallback
Function Name

void HAL_ETH_RxCpltCallback (ETH_HandleTypeDef * heth)

Function Description

Rx Transfer completed callbacks.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

None

HAL_ETH_ErrorCallback
Function Name

void HAL_ETH_ErrorCallback (ETH_HandleTypeDef * heth)

Function Description

Ethernet transfer error callbacks.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

None

HAL_ETH_Start
Function Name

HAL_StatusTypeDef HAL_ETH_Start (ETH_HandleTypeDef *
heth)

Function Description

Enables Ethernet MAC and DMA reception/transmission.

Parameters

310/964

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module
DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
Return values

HAL: status

HAL_ETH_Stop
Function Name

HAL_StatusTypeDef HAL_ETH_Stop (ETH_HandleTypeDef *
heth)

Function Description

Stop Ethernet MAC and DMA reception/transmission.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

HAL: status

HAL_ETH_ConfigMAC
Function Name

HAL_StatusTypeDef HAL_ETH_ConfigMAC
(ETH_HandleTypeDef * heth, ETH_MACInitTypeDef * macconf)

Function Description

Set ETH MAC Configuration.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module
macconf: MAC Configuration structure

Return values

HAL: status

HAL_ETH_ConfigDMA
Function Name

HAL_StatusTypeDef HAL_ETH_ConfigDMA
(ETH_HandleTypeDef * heth, ETH_DMAInitTypeDef * dmaconf)

Function Description

Sets ETH DMA Configuration.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module
dmaconf: DMA Configuration structure

Return values

HAL: status

HAL_ETH_GetState
Function Name

HAL_ETH_StateTypeDef HAL_ETH_GetState
(ETH_HandleTypeDef * heth)

Function Description

Return the ETH HAL state.

Parameters

heth: pointer to a ETH_HandleTypeDef structure that
contains the configuration information for ETHERNET module

Return values

HAL: state

21.3

ETH Firmware driver defines

21.3.1

ETH
ETH Address Aligned Beats
ETH_ADDRESSALIGNEDBEATS_ENABLE

DocID025834 Rev 4

311/964

HAL ETH Generic Driver
ETH_ADDRESSALIGNEDBEATS_DISABLE

UM1725

ETH Automatic Pad CRC Strip
ETH_AUTOMATICPADCRCSTRIP_ENABLE
ETH_AUTOMATICPADCRCSTRIP_DISABLE
ETH AutoNegotiation
ETH_AUTONEGOTIATION_ENABLE
ETH_AUTONEGOTIATION_DISABLE
ETH Back Off Limit
ETH_BACKOFFLIMIT_10
ETH_BACKOFFLIMIT_8
ETH_BACKOFFLIMIT_4
ETH_BACKOFFLIMIT_1
ETH Broadcast Frames Reception
ETH_BROADCASTFRAMESRECEPTION_ENABLE
ETH_BROADCASTFRAMESRECEPTION_DISABLE
ETH Buffers setting
ETH_MAX_PACKET_SIZE

ETH_HEADER + ETH_EXTRA + ETH_VLAN_TAG +
ETH_MAX_ETH_PAYLOAD + ETH_CRC

ETH_HEADER

6 byte Dest addr, 6 byte Src addr, 2 byte length/type

ETH_CRC

Ethernet CRC

ETH_EXTRA

Extra bytes in some cases

ETH_VLAN_TAG

optional 802.1q VLAN Tag

ETH_MIN_ETH_PAYLOAD

Minimum Ethernet payload size

ETH_MAX_ETH_PAYLOAD

Maximum Ethernet payload size

ETH_JUMBO_FRAME_PAYLOAD

Jumbo frame payload size

ETH_RX_BUF_SIZE
ETH_RXBUFNB
ETH_TX_BUF_SIZE
ETH_TXBUFNB
ETH Carrier Sense
ETH_CARRIERSENCE_ENABLE
ETH_CARRIERSENCE_DISABLE
ETH Checksum Mode
ETH_CHECKSUM_BY_HARDWARE
ETH_CHECKSUM_BY_SOFTWARE
ETH Checksum Offload
ETH_CHECKSUMOFFLAOD_ENABLE
312/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
ETH_CHECKSUMOFFLAOD_DISABLE
ETH Deferral Check
ETH_DEFFERRALCHECK_ENABLE
ETH_DEFFERRALCHECK_DISABLE
ETH Destination Addr Filter
ETH_DESTINATIONADDRFILTER_NORMAL
ETH_DESTINATIONADDRFILTER_INVERSE
ETH DMA Arbitration
ETH_DMAARBITRATION_ROUNDROBIN_RXTX_1_1
ETH_DMAARBITRATION_ROUNDROBIN_RXTX_2_1
ETH_DMAARBITRATION_ROUNDROBIN_RXTX_3_1
ETH_DMAARBITRATION_ROUNDROBIN_RXTX_4_1
ETH_DMAARBITRATION_RXPRIORTX
ETH DMA Enhanced descriptor format
ETH_DMAENHANCEDDESCRIPTOR_ENABLE
ETH_DMAENHANCEDDESCRIPTOR_DISABLE
ETH DMA Flags
ETH_DMA_FLAG_TST

Time-stamp trigger interrupt (on DMA)

ETH_DMA_FLAG_PMT

PMT interrupt (on DMA)

ETH_DMA_FLAG_MMC

MMC interrupt (on DMA)

ETH_DMA_FLAG_DATATRANSFERERROR

Error bits 0-Rx DMA, 1-Tx DMA

ETH_DMA_FLAG_READWRITEERROR

Error bits 0-write transfer, 1-read transfer

ETH_DMA_FLAG_ACCESSERROR

Error bits 0-data buffer, 1-desc. access

ETH_DMA_FLAG_NIS

Normal interrupt summary flag

ETH_DMA_FLAG_AIS

Abnormal interrupt summary flag

ETH_DMA_FLAG_ER

Early receive flag

ETH_DMA_FLAG_FBE

Fatal bus error flag

ETH_DMA_FLAG_ET

Early transmit flag

ETH_DMA_FLAG_RWT

Receive watchdog timeout flag

ETH_DMA_FLAG_RPS

Receive process stopped flag

ETH_DMA_FLAG_RBU

Receive buffer unavailable flag

ETH_DMA_FLAG_R

Receive flag

ETH_DMA_FLAG_TU

Underflow flag

ETH_DMA_FLAG_RO

Overflow flag

ETH_DMA_FLAG_TJT

Transmit jabber timeout flag

ETH_DMA_FLAG_TBU

Transmit buffer unavailable flag

DocID025834 Rev 4

313/964

HAL ETH Generic Driver
ETH_DMA_FLAG_TPS

UM1725
Transmit process stopped flag

ETH_DMA_FLAG_T

Transmit flag

ETH DMA Interrupts
ETH_DMA_IT_TST

Time-stamp trigger interrupt (on DMA)

ETH_DMA_IT_PMT

PMT interrupt (on DMA)

ETH_DMA_IT_MMC

MMC interrupt (on DMA)

ETH_DMA_IT_NIS

Normal interrupt summary

ETH_DMA_IT_AIS

Abnormal interrupt summary

ETH_DMA_IT_ER

Early receive interrupt

ETH_DMA_IT_FBE

Fatal bus error interrupt

ETH_DMA_IT_ET

Early transmit interrupt

ETH_DMA_IT_RWT

Receive watchdog timeout interrupt

ETH_DMA_IT_RPS

Receive process stopped interrupt

ETH_DMA_IT_RBU

Receive buffer unavailable interrupt

ETH_DMA_IT_R

Receive interrupt

ETH_DMA_IT_TU

Underflow interrupt

ETH_DMA_IT_RO

Overflow interrupt

ETH_DMA_IT_TJT

Transmit jabber timeout interrupt

ETH_DMA_IT_TBU

Transmit buffer unavailable interrupt

ETH_DMA_IT_TPS

Transmit process stopped interrupt

ETH_DMA_IT_T

Transmit interrupt

ETH DMA overflow
ETH_DMA_OVERFLOW_RXFIFOCOUNTER

Overflow bit for FIFO overflow
counter

ETH_DMA_OVERFLOW_MISSEDFRAMECOUNTER

Overflow bit for missed frame
counter

ETH DMA receive process state
ETH_DMA_RECEIVEPROCESS_STOPPED

Stopped - Reset or Stop Rx Command
issued

ETH_DMA_RECEIVEPROCESS_FETCHING

Running - fetching the Rx descriptor

ETH_DMA_RECEIVEPROCESS_WAITING

Running - waiting for packet

ETH_DMA_RECEIVEPROCESS_SUSPENDED

Suspended - Rx Descriptor unavailable

ETH_DMA_RECEIVEPROCESS_CLOSING

Running - closing descriptor

ETH_DMA_RECEIVEPROCESS_QUEUING

Running - queuing the receive frame
into host memory

ETH DMA RX Descriptor
ETH_DMARXDESC_OWN

314/964

OWN bit: descriptor is owned by
DMA engine

DocID025834 Rev 4

UM1725
ETH_DMARXDESC_AFM

HAL ETH Generic Driver
DA Filter Fail for the rx frame

ETH_DMARXDESC_FL

Receive descriptor frame length

ETH_DMARXDESC_ES

Error summary: OR of the following
bits: DE || OE || IPC || LC || RWT ||
RE || CE

ETH_DMARXDESC_DE

Descriptor error: no more
descriptors for receive frame

ETH_DMARXDESC_SAF

SA Filter Fail for the received frame

ETH_DMARXDESC_LE

Frame size not matching with length
field

ETH_DMARXDESC_OE

Overflow Error: Frame was
damaged due to buffer overflow

ETH_DMARXDESC_VLAN

VLAN Tag: received frame is a
VLAN frame

ETH_DMARXDESC_FS

First descriptor of the frame

ETH_DMARXDESC_LS

Last descriptor of the frame

ETH_DMARXDESC_IPV4HCE

IPC Checksum Error: Rx Ipv4
header checksum error

ETH_DMARXDESC_LC

Late collision occurred during
reception

ETH_DMARXDESC_FT

Frame type - Ethernet, otherwise
802.3

ETH_DMARXDESC_RWT

Receive Watchdog Timeout:
watchdog timer expired during
reception

ETH_DMARXDESC_RE

Receive error: error reported by MII
interface

ETH_DMARXDESC_DBE

Dribble bit error: frame contains non
int multiple of 8 bits

ETH_DMARXDESC_CE

CRC error

ETH_DMARXDESC_MAMPCE

Rx MAC Address/Payload
Checksum Error: Rx MAC address
matched/ Rx Payload Checksum
Error

ETH_DMARXDESC_DIC

Disable Interrupt on Completion

ETH_DMARXDESC_RBS2

Receive Buffer2 Size

ETH_DMARXDESC_RER

Receive End of Ring

ETH_DMARXDESC_RCH

Second Address Chained

ETH_DMARXDESC_RBS1

Receive Buffer1 Size

ETH_DMARXDESC_B1AP

Buffer1 Address Pointer

ETH_DMARXDESC_B2AP

Buffer2 Address Pointer

ETH_DMAPTPRXDESC_PTPV
DocID025834 Rev 4

315/964

HAL ETH Generic Driver
ETH_DMAPTPRXDESC_PTPFT

UM1725

ETH_DMAPTPRXDESC_PTPMT
ETH_DMAPTPRXDESC_PTPMT_SYNC
ETH_DMAPTPRXDESC_PTPMT_FOLLOWUP
ETH_DMAPTPRXDESC_PTPMT_DELAYREQ
ETH_DMAPTPRXDESC_PTPMT_DELAYRESP
ETH_DMAPTPRXDESC_PTPMT_PDELAYREQ_ANNOUNCE
ETH_DMAPTPRXDESC_PTPMT_PDELAYRESP_MANAG
ETH_DMAPTPRXDESC_PTPMT_PDELAYRESPFOLLOWUP_SIGNAL
ETH_DMAPTPRXDESC_IPV6PR
ETH_DMAPTPRXDESC_IPV4PR
ETH_DMAPTPRXDESC_IPCB
ETH_DMAPTPRXDESC_IPPE
ETH_DMAPTPRXDESC_IPHE
ETH_DMAPTPRXDESC_IPPT
ETH_DMAPTPRXDESC_IPPT_UDP
ETH_DMAPTPRXDESC_IPPT_TCP
ETH_DMAPTPRXDESC_IPPT_ICMP
ETH_DMAPTPRXDESC_RTSL
ETH_DMAPTPRXDESC_RTSH
ETH DMA Rx descriptor buffers
ETH_DMARXDESC_BUFFER1

DMA Rx Desc Buffer1

ETH_DMARXDESC_BUFFER2

DMA Rx Desc Buffer2

ETH DMA transmit process state
ETH_DMA_TRANSMITPROCESS_STOPPED

Stopped - Reset or Stop Tx Command
issued

ETH_DMA_TRANSMITPROCESS_FETCHING

Running - fetching the Tx descriptor

ETH_DMA_TRANSMITPROCESS_WAITING

Running - waiting for status

ETH_DMA_TRANSMITPROCESS_READING

Running - reading the data from host
memory

ETH_DMA_TRANSMITPROCESS_SUSPENDED

Suspended - Tx Descriptor
unavailable

ETH_DMA_TRANSMITPROCESS_CLOSING

Running - closing Rx descriptor

ETH DMA TX Descriptor

316/964

ETH_DMATXDESC_OWN

OWN bit: descriptor is owned by
DMA engine

ETH_DMATXDESC_IC

Interrupt on Completion

ETH_DMATXDESC_LS

Last Segment
DocID025834 Rev 4

UM1725
ETH_DMATXDESC_FS

HAL ETH Generic Driver
First Segment

ETH_DMATXDESC_DC

Disable CRC

ETH_DMATXDESC_DP

Disable Padding

ETH_DMATXDESC_TTSE

Transmit Time Stamp Enable

ETH_DMATXDESC_CIC

Checksum Insertion Control: 4
cases

ETH_DMATXDESC_CIC_BYPASS

Do Nothing: Checksum Engine is
bypassed

ETH_DMATXDESC_CIC_IPV4HEADER

IPV4 header Checksum Insertion

ETH_DMATXDESC_CIC_TCPUDPICMP_SEGMENT

TCP/UDP/ICMP Checksum
Insertion calculated over segment
only

ETH_DMATXDESC_CIC_TCPUDPICMP_FULL

TCP/UDP/ICMP Checksum
Insertion fully calculated

ETH_DMATXDESC_TER

Transmit End of Ring

ETH_DMATXDESC_TCH

Second Address Chained

ETH_DMATXDESC_TTSS

Tx Time Stamp Status

ETH_DMATXDESC_IHE

IP Header Error

ETH_DMATXDESC_ES

Error summary: OR of the
following bits: UE || ED || EC ||
LCO || NC || LCA || FF || JT

ETH_DMATXDESC_JT

Jabber Timeout

ETH_DMATXDESC_FF

Frame Flushed: DMA/MTL flushed
the frame due to SW flush

ETH_DMATXDESC_PCE

Payload Checksum Error

ETH_DMATXDESC_LCA

Loss of Carrier: carrier lost during
transmission

ETH_DMATXDESC_NC

No Carrier: no carrier signal from
the transceiver

ETH_DMATXDESC_LCO

Late Collision: transmission
aborted due to collision

ETH_DMATXDESC_EC

Excessive Collision: transmission
aborted after 16 collisions

ETH_DMATXDESC_VF

VLAN Frame

ETH_DMATXDESC_CC

Collision Count

ETH_DMATXDESC_ED

Excessive Deferral

ETH_DMATXDESC_UF

Underflow Error: late data arrival
from the memory

ETH_DMATXDESC_DB

Deferred Bit

ETH_DMATXDESC_TBS2

Transmit Buffer2 Size

ETH_DMATXDESC_TBS1

Transmit Buffer1 Size
DocID025834 Rev 4

317/964

HAL ETH Generic Driver
ETH_DMATXDESC_B1AP

Buffer1 Address Pointer

UM1725

ETH_DMATXDESC_B2AP

Buffer2 Address Pointer

ETH_DMAPTPTXDESC_TTSL
ETH_DMAPTPTXDESC_TTSH
ETH DMA Tx descriptor Checksum Insertion Control
ETH_DMATXDESC_CHECKSUMBYPASS

Checksum engine bypass

ETH_DMATXDESC_CHECKSUMIPV4HEADER

IPv4 header checksum
insertion

ETH_DMATXDESC_CHECKSUMTCPUDPICMPSEGMENT

TCP/UDP/ICMP checksum
insertion. Pseudo header
checksum is assumed to be
present

ETH_DMATXDESC_CHECKSUMTCPUDPICMPFULL

TCP/UDP/ICMP checksum
fully in hardware including
pseudo header

ETH DMA Tx descriptor segment
ETH_DMATXDESC_LASTSEGMENTS

Last Segment

ETH_DMATXDESC_FIRSTSEGMENT

First Segment

ETH Drop TCP IP Checksum Error Frame
ETH_DROPTCPIPCHECKSUMERRORFRAME_ENABLE
ETH_DROPTCPIPCHECKSUMERRORFRAME_DISABLE
ETH Duplex Mode
ETH_MODE_FULLDUPLEX
ETH_MODE_HALFDUPLEX
ETH Exported Macros
__HAL_ETH_RESET_HANDLE_STATE

Description:
Reset ETH handle state.
Parameters:
__HANDLE__: specifies the ETH
handle.
Return value:
None

__HAL_ETH_DMATXDESC_GET_FLAG

Description:
Checks whether the specified
ETHERNET DMA Tx Desc flag is set or
not.
Parameters:
__HANDLE__: ETH Handle
__FLAG__: specifies the flag of TDES0
to check.

318/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
Return value:
the: ETH_DMATxDescFlag (SET or
RESET).
__HAL_ETH_DMARXDESC_GET_FLAG

Description:
Checks whether the specified
ETHERNET DMA Rx Desc flag is set or
not.
Parameters:
__HANDLE__: ETH Handle
__FLAG__: specifies the flag of RDES0
to check.
Return value:
the: ETH_DMATxDescFlag (SET or
RESET).

__HAL_ETH_DMARXDESC_ENABLE_IT

Description:
Enables the specified DMA Rx Desc
receive interrupt.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_DMARXDESC_DISABLE_IT

Description:
Disables the specified DMA Rx Desc
receive interrupt.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_DMARXDESC_SET_OWN_
BIT

Description:
Set the specified DMA Rx Desc Own bit.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_DMATXDESC_GET_COLLI
SION_COUNT

Description:
Returns the specified ETHERNET DMA
Tx Desc collision count.
Parameters:
__HANDLE__: ETH Handle

DocID025834 Rev 4

319/964

HAL ETH Generic Driver

UM1725
Return value:
The: Transmit descriptor collision
counter value.

__HAL_ETH_DMATXDESC_SET_OWN_
BIT

Description:
Set the specified DMA Tx Desc Own bit.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_DMATXDESC_ENABLE_IT

Description:
Enables the specified DMA Tx Desc
Transmit interrupt.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_DMATXDESC_DISABLE_IT

Description:
Disables the specified DMA Tx Desc
Transmit interrupt.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_DMATXDESC_CHECKSUM
_INSERTION

Description:
Selects the specified ETHERNET DMA
Tx Desc Checksum Insertion.
Parameters:
__HANDLE__: ETH Handle
__CHECKSUM__: specifies is the DMA
Tx desc checksum insertion. This
parameter can be one of the following
values:
ETH_DMATXDESC_CHECKSUMB
YPASS : Checksum bypass
ETH_DMATXDESC_CHECKSUMI
PV4HEADER : IPv4 header
checksum
ETH_DMATXDESC_CHECKSUMT
CPUDPICMPSEGMENT :
TCP/UDP/ICMP checksum. Pseudo
header checksum is assumed to be
present

320/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
ETH_DMATXDESC_CHECKSUMT
CPUDPICMPFULL :
TCP/UDP/ICMP checksum fully in
hardware including pseudo header
Return value:
None
__HAL_ETH_DMATXDESC_CRC_ENABL
E

Description:
Enables the DMA Tx Desc CRC.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_DMATXDESC_CRC_DISAB
LE

Description:
Disables the DMA Tx Desc CRC.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_DMATXDESC_SHORT_FRA
ME_PADDING_ENABLE

Description:
Enables the DMA Tx Desc padding for
frame shorter than 64 bytes.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_DMATXDESC_SHORT_FRA
ME_PADDING_DISABLE

Description:
Disables the DMA Tx Desc padding for
frame shorter than 64 bytes.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_MAC_ENABLE_IT

Description:
Enables the specified ETHERNET MAC
interrupts.
Parameters:
__HANDLE__: : ETH Handle
__INTERRUPT__: specifies the
ETHERNET MAC interrupt sources to

DocID025834 Rev 4

321/964

HAL ETH Generic Driver

UM1725
be enabled or disabled. This parameter
can be any combination of the following
values:
ETH_MAC_IT_TST : Time stamp
trigger interrupt
ETH_MAC_IT_PMT : PMT interrupt
Return value:
None

__HAL_ETH_MAC_DISABLE_IT

Description:
Disables the specified ETHERNET MAC
interrupts.
Parameters:
__HANDLE__: : ETH Handle
__INTERRUPT__: specifies the
ETHERNET MAC interrupt sources to
be enabled or disabled. This parameter
can be any combination of the following
values:
ETH_MAC_IT_TST : Time stamp
trigger interrupt
ETH_MAC_IT_PMT : PMT interrupt
Return value:
None

__HAL_ETH_INITIATE_PAUSE_CONTRO
L_FRAME

Description:
Initiate a Pause Control Frame (Fullduplex only).
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_GET_FLOW_CONTROL_BU
SY_STATUS

Description:
Checks whether the ETHERNET flow
control busy bit is set or not.
Parameters:
__HANDLE__: ETH Handle
Return value:
The: new state of flow control busy
status bit (SET or RESET).

__HAL_ETH_BACK_PRESSURE_ACTIVA
TION_ENABLE

Description:
Enables the MAC Back Pressure
operation activation (Half-duplex only).
Parameters:

322/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
__HANDLE__: ETH Handle
Return value:
None
__HAL_ETH_BACK_PRESSURE_ACTIVA
TION_DISABLE

Description:
Disables the MAC BackPressure
operation activation (Half-duplex only).
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_MAC_GET_FLAG

Description:
Checks whether the specified
ETHERNET MAC flag is set or not.
Parameters:
__HANDLE__: ETH Handle
__FLAG__: specifies the flag to check.
This parameter can be one of the
following values:
ETH_MAC_FLAG_TST : Time
stamp trigger flag
ETH_MAC_FLAG_MMCT : MMC
transmit flag
ETH_MAC_FLAG_MMCR : MMC
receive flag
ETH_MAC_FLAG_MMC : MMC
flag
ETH_MAC_FLAG_PMT : PMT flag
Return value:
The: state of ETHERNET MAC flag.

__HAL_ETH_DMA_ENABLE_IT

Description:
Enables the specified ETHERNET DMA
interrupts.
Parameters:
__HANDLE__: : ETH Handle
__INTERRUPT__: specifies the
ETHERNET DMA interrupt sources to
be enabled
Return value:
None

__HAL_ETH_DMA_DISABLE_IT

Description:
Disables the specified ETHERNET DMA
interrupts.

DocID025834 Rev 4

323/964

HAL ETH Generic Driver

UM1725
Parameters:
__HANDLE__: : ETH Handle
__INTERRUPT__: specifies the
ETHERNET DMA interrupt sources to
be disabled.
Return value:
None

__HAL_ETH_DMA_CLEAR_IT

Description:
Clears the ETHERNET DMA IT pending
bit.
Parameters:
__HANDLE__: : ETH Handle
__INTERRUPT__: specifies the interrupt
pending bit to clear.
Return value:
None

__HAL_ETH_DMA_GET_FLAG

Description:
Checks whether the specified
ETHERNET DMA flag is set or not.
Parameters:
__HANDLE__: ETH Handle
__FLAG__: specifies the flag to check.
Return value:
The: new state of ETH_DMA_FLAG
(SET or RESET).

__HAL_ETH_DMA_CLEAR_FLAG

Description:
Checks whether the specified
ETHERNET DMA flag is set or not.
Parameters:
__HANDLE__: ETH Handle
__FLAG__: specifies the flag to clear.
Return value:
The: new state of ETH_DMA_FLAG
(SET or RESET).

__HAL_ETH_GET_DMA_OVERFLOW_ST
ATUS

Description:
Checks whether the specified
ETHERNET DMA overflow flag is set or
not.
Parameters:
__HANDLE__: ETH Handle
__OVERFLOW__: specifies the DMA

324/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
overflow flag to check. This parameter
can be one of the following values:
ETH_DMA_OVERFLOW_RXFIFO
COUNTER : Overflow for FIFO
Overflows Counter
ETH_DMA_OVERFLOW_MISSED
FRAMECOUNTER : Overflow for
Buffer Unavailable Missed Frame
Counter
Return value:
The: state of ETHERNET DMA overflow
Flag (SET or RESET).
__HAL_ETH_SET_RECEIVE_WATCHDO
G_TIMER

Description:
Set the DMA Receive status watchdog
timer register value.
Parameters:
__HANDLE__: ETH Handle
__VALUE__: DMA Receive status
watchdog timer register value
Return value:
None

__HAL_ETH_GLOBAL_UNICAST_WAKE
UP_ENABLE

Description:
Enables any unicast packet filtered by
the MAC address recognition to be a
wake-up frame.
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_GLOBAL_UNICAST_WAKE
UP_DISABLE

Description:
Disables any unicast packet filtered by
the MAC address recognition to be a
wake-up frame.
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_WAKEUP_FRAME_DETECT
ION_ENABLE

Description:
Enables the MAC Wake-Up Frame
Detection.
Parameters:
__HANDLE__: ETH Handle.

DocID025834 Rev 4

325/964

HAL ETH Generic Driver

UM1725
Return value:
None

__HAL_ETH_WAKEUP_FRAME_DETECT
ION_DISABLE

Description:
Disables the MAC Wake-Up Frame
Detection.
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_MAGIC_PACKET_DETECTI
ON_ENABLE

Description:
Enables the MAC Magic Packet
Detection.
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_MAGIC_PACKET_DETECTI
ON_DISABLE

Description:
Disables the MAC Magic Packet
Detection.
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_POWER_DOWN_ENABLE

Description:
Enables the MAC Power Down.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_POWER_DOWN_DISABLE

Description:
Disables the MAC Power Down.
Parameters:
__HANDLE__: ETH Handle
Return value:
None

__HAL_ETH_GET_PMT_FLAG_STATUS

Description:
Checks whether the specified

326/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
ETHERNET PMT flag is set or not.
Parameters:
__HANDLE__: ETH Handle.
__FLAG__: specifies the flag to check.
This parameter can be one of the
following values:
ETH_PMT_FLAG_WUFFRPR :
Wake-Up Frame Filter Register
Pointer Reset
ETH_PMT_FLAG_WUFR : WakeUp Frame Received
ETH_PMT_FLAG_MPR : Magic
Packet Received
Return value:
The: new state of ETHERNET PMT Flag
(SET or RESET).
__HAL_ETH_MMC_COUNTER_FULL_PR
ESET

Description:
Preset and Initialize the MMC counters
to almost-full value: 0xFFFF_FFF0 (full 16)
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_MMC_COUNTER_HALF_PR
ESET

Description:
Preset and Initialize the MMC counters
to almost-half value: 0x7FFF_FFF0 (half
- 16)
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_MMC_COUNTER_FREEZE_
ENABLE

Description:
Enables the MMC Counter Freeze.
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_MMC_COUNTER_FREEZE_
DISABLE

Description:
Disables the MMC Counter Freeze.
Parameters:

DocID025834 Rev 4

327/964

HAL ETH Generic Driver

UM1725
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_ETH_MMC_RESET_ONREA
D_ENABLE

Description:
Enables the MMC Reset On Read.
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_ETH_MMC_RESET_ONREA
D_DISABLE

Description:
Disables the MMC Reset On Read.
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_ETH_MMC_COUNTER_RO
LLOVER_ENABLE

Description:
Enables the MMC Counter Stop
Rollover.
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_ETH_MMC_COUNTER_RO
LLOVER_DISABLE

Description:
Disables the MMC Counter Stop
Rollover.
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_MMC_COUNTERS_RESET

Description:
Resets the MMC Counters.
Parameters:
__HANDLE__: ETH Handle.
Return value:
None

__HAL_ETH_MMC_RX_IT_ENABLE

Description:
Enables the specified ETHERNET MMC

328/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
Rx interrupts.
Parameters:
__HANDLE__: ETH Handle.
__INTERRUPT__: specifies the
ETHERNET MMC interrupt sources to
be enabled or disabled. This parameter
can be one of the following values:
ETH_MMC_IT_RGUF : When Rx
good unicast frames counter
reaches half the maximum value
ETH_MMC_IT_RFAE : When Rx
alignment error counter reaches
half the maximum value
ETH_MMC_IT_RFCE : When Rx
crc error counter reaches half the
maximum value
Return value:
None
__HAL_ETH_MMC_RX_IT_DISABLE

Description:
Disables the specified ETHERNET MMC
Rx interrupts.
Parameters:
__HANDLE__: ETH Handle.
__INTERRUPT__: specifies the
ETHERNET MMC interrupt sources to
be enabled or disabled. This parameter
can be one of the following values:
ETH_MMC_IT_RGUF : When Rx
good unicast frames counter
reaches half the maximum value
ETH_MMC_IT_RFAE : When Rx
alignment error counter reaches
half the maximum value
ETH_MMC_IT_RFCE : When Rx
crc error counter reaches half the
maximum value
Return value:
None

__HAL_ETH_MMC_TX_IT_ENABLE

Description:
Enables the specified ETHERNET MMC
Tx interrupts.
Parameters:
__HANDLE__: ETH Handle.
__INTERRUPT__: specifies the
ETHERNET MMC interrupt sources to
be enabled or disabled. This parameter
can be one of the following values:

DocID025834 Rev 4

329/964

HAL ETH Generic Driver

UM1725
ETH_MMC_IT_TGF : When Tx
good frame counter reaches half
the maximum value
ETH_MMC_IT_TGFMSC: When Tx
good multi col counter reaches half
the maximum value
ETH_MMC_IT_TGFSC : When Tx
good single col counter reaches
half the maximum value
Return value:
None

__HAL_ETH_MMC_TX_IT_DISABLE

Description:
Disables the specified ETHERNET MMC
Tx interrupts.
Parameters:
__HANDLE__: ETH Handle.
__INTERRUPT__: specifies the
ETHERNET MMC interrupt sources to
be enabled or disabled. This parameter
can be one of the following values:
ETH_MMC_IT_TGF : When Tx
good frame counter reaches half
the maximum value
ETH_MMC_IT_TGFMSC: When Tx
good multi col counter reaches half
the maximum value
ETH_MMC_IT_TGFSC : When Tx
good single col counter reaches
half the maximum value
Return value:
None

__HAL_ETH_WAKEUP_EXTI_ENABLE_I
T

Description:
Enables the ETH External interrupt line.
Return value:
None

__HAL_ETH_WAKEUP_EXTI_DISABLE_I
T

Description:
Disables the ETH External interrupt line.
Return value:
None

__HAL_ETH_WAKEUP_EXTI_ENABLE_E
VENT

Description:
Enable event on ETH External event
line.
Return value:
None.

330/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
__HAL_ETH_WAKEUP_EXTI_DISABLE_
EVENT

Description:
Disable event on ETH External event
line.
Return value:
None.

__HAL_ETH_WAKEUP_EXTI_GET_FLAG

Description:
Get flag of the ETH External interrupt
line.
Return value:
None

__HAL_ETH_WAKEUP_EXTI_CLEAR_FL
AG

Description:
Clear flag of the ETH External interrupt
line.
Return value:
None

__HAL_ETH_WAKEUP_EXTI_ENABLE_R
ISING_EDGE_TRIGGER

Description:
Enables rising edge trigger to the ETH
External interrupt line.
Return value:
None

__HAL_ETH_WAKEUP_EXTI_DISABLE_
RISING_EDGE_TRIGGER

Description:
Disables the rising edge trigger to the
ETH External interrupt line.
Return value:
None

__HAL_ETH_WAKEUP_EXTI_ENABLE_F
ALLING_EDGE_TRIGGER

Description:
Enables falling edge trigger to the ETH
External interrupt line.
Return value:
None

__HAL_ETH_WAKEUP_EXTI_DISABLE_
FALLING_EDGE_TRIGGER

Description:
Disables falling edge trigger to the ETH
External interrupt line.
Return value:
None

__HAL_ETH_WAKEUP_EXTI_ENABLE_F
ALLINGRISING_TRIGGER

Description:

DocID025834 Rev 4

Enables rising/falling edge trigger to the
ETH External interrupt line.

331/964

HAL ETH Generic Driver

UM1725
Return value:
None

__HAL_ETH_WAKEUP_EXTI_DISABLE_
FALLINGRISING_TRIGGER

Description:
Disables rising/falling edge trigger to the
ETH External interrupt line.
Return value:
None

__HAL_ETH_WAKEUP_EXTI_GENERAT
E_SWIT

Description:
Generate a Software interrupt on
selected EXTI line.
Return value:
None.

ETH EXTI LINE WAKEUP
ETH_EXTI_LINE_WAKEUP

External interrupt line 19 Connected to the ETH EXTI Line

ETH Fixed Burst
ETH_FIXEDBURST_ENABLE
ETH_FIXEDBURST_DISABLE
ETH Flush Received Frame
ETH_FLUSHRECEIVEDFRAME_ENABLE
ETH_FLUSHRECEIVEDFRAME_DISABLE
ETH Forward Error Frames
ETH_FORWARDERRORFRAMES_ENABLE
ETH_FORWARDERRORFRAMES_DISABLE
ETH Forward Undersized Good Frames
ETH_FORWARDUNDERSIZEDGOODFRAMES_ENABLE
ETH_FORWARDUNDERSIZEDGOODFRAMES_DISABLE
ETH Inter Frame Gap

332/964

ETH_INTERFRAMEGAP_96BIT

minimum IFG between frames during transmission is
96Bit

ETH_INTERFRAMEGAP_88BIT

minimum IFG between frames during transmission is
88Bit

ETH_INTERFRAMEGAP_80BIT

minimum IFG between frames during transmission is
80Bit

ETH_INTERFRAMEGAP_72BIT

minimum IFG between frames during transmission is
72Bit

ETH_INTERFRAMEGAP_64BIT

minimum IFG between frames during transmission is
64Bit

ETH_INTERFRAMEGAP_56BIT

minimum IFG between frames during transmission is
56Bit

DocID025834 Rev 4

UM1725
ETH_INTERFRAMEGAP_48BIT
ETH_INTERFRAMEGAP_40BIT

HAL ETH Generic Driver
minimum IFG between frames during transmission is
48Bit
minimum IFG between frames during transmission is
40Bit

ETH Jabber
ETH_JABBER_ENABLE
ETH_JABBER_DISABLE
ETH Loop Back Mode
ETH_LOOPBACKMODE_ENABLE
ETH_LOOPBACKMODE_DISABLE
ETH MAC addresses
ETH_MAC_ADDRESS0
ETH_MAC_ADDRESS1
ETH_MAC_ADDRESS2
ETH_MAC_ADDRESS3
ETH MAC addresses filter Mask bytes
ETH_MAC_ADDRESSMASK_BYTE6

Mask MAC Address high reg bits [15:8]

ETH_MAC_ADDRESSMASK_BYTE5

Mask MAC Address high reg bits [7:0]

ETH_MAC_ADDRESSMASK_BYTE4

Mask MAC Address low reg bits [31:24]

ETH_MAC_ADDRESSMASK_BYTE3

Mask MAC Address low reg bits [23:16]

ETH_MAC_ADDRESSMASK_BYTE2

Mask MAC Address low reg bits [15:8]

ETH_MAC_ADDRESSMASK_BYTE1

Mask MAC Address low reg bits [70]

ETH MAC addresses filter SA DA
ETH_MAC_ADDRESSFILTER_SA
ETH_MAC_ADDRESSFILTER_DA
ETH MAC Flags
ETH_MAC_FLAG_TST

Time stamp trigger flag (on MAC)

ETH_MAC_FLAG_MMCT

MMC transmit flag

ETH_MAC_FLAG_MMCR

MMC receive flag

ETH_MAC_FLAG_MMC

MMC flag (on MAC)

ETH_MAC_FLAG_PMT

PMT flag (on MAC)

ETH MAC Interrupts
ETH_MAC_IT_TST

Time stamp trigger interrupt (on MAC)

ETH_MAC_IT_MMCT

MMC transmit interrupt

ETH_MAC_IT_MMCR

MMC receive interrupt

ETH_MAC_IT_MMC

MMC interrupt (on MAC)

ETH_MAC_IT_PMT

PMT interrupt (on MAC)

DocID025834 Rev 4

333/964

HAL ETH Generic Driver
ETH Media Interface

UM1725

ETH_MEDIA_INTERFACE_MII
ETH_MEDIA_INTERFACE_RMII
ETH MMC Rx Interrupts
ETH_MMC_IT_RGUF

When Rx good unicast frames counter reaches half the maximum
value

ETH_MMC_IT_RFAE

When Rx alignment error counter reaches half the maximum value

ETH_MMC_IT_RFCE

When Rx crc error counter reaches half the maximum value

ETH MMC Tx Interrupts
ETH_MMC_IT_TGF

When Tx good frame counter reaches half the maximum value

ETH_MMC_IT_TGFMSC

When Tx good multi col counter reaches half the maximum
value

ETH_MMC_IT_TGFSC

When Tx good single col counter reaches half the maximum
value

ETH Multicast Frames Filter
ETH_MULTICASTFRAMESFILTER_PERFECTHASHTABLE
ETH_MULTICASTFRAMESFILTER_HASHTABLE
ETH_MULTICASTFRAMESFILTER_PERFECT
ETH_MULTICASTFRAMESFILTER_NONE
ETH Pass Control Frames
ETH_PASSCONTROLFRAMES_BLOCKALL

MAC filters all
control frames from
reaching the
application

ETH_PASSCONTROLFRAMES_FORWARDALL

MAC forwards all
control frames to
application even if
they fail the
Address Filter

ETH_PASSCONTROLFRAMES_FORWARDPASSEDADDRFILTER

MAC forwards
control frames that
pass the Address
Filter.

ETH Pause Low Threshold
ETH_PAUSELOWTHRESHOLD_MINUS4

Pause time minus 4 slot times

ETH_PAUSELOWTHRESHOLD_MINUS28

Pause time minus 28 slot times

ETH_PAUSELOWTHRESHOLD_MINUS144

Pause time minus 144 slot times

ETH_PAUSELOWTHRESHOLD_MINUS256

Pause time minus 256 slot times

ETH PMT Flags

334/964

ETH_PMT_FLAG_WUFFRPR

Wake-Up Frame Filter Register Pointer Reset

ETH_PMT_FLAG_WUFR

Wake-Up Frame Received
DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
ETH_PMT_FLAG_MPR

Magic Packet Received

ETH Promiscuous Mode
ETH_PROMISCUOUS_MODE_ENABLE
ETH_PROMISCUOUS_MODE_DISABLE
ETH Receive All
ETH_RECEIVEALL_ENABLE
ETH_RECEIVEAll_DISABLE
ETH Receive Flow Control
ETH_RECEIVEFLOWCONTROL_ENABLE
ETH_RECEIVEFLOWCONTROL_DISABLE
ETH Receive Own
ETH_RECEIVEOWN_ENABLE
ETH_RECEIVEOWN_DISABLE
ETH Receive Store Forward
ETH_RECEIVESTOREFORWARD_ENABLE
ETH_RECEIVESTOREFORWARD_DISABLE
ETH Receive Threshold Control
ETH_RECEIVEDTHRESHOLDCONTROL_64BYTES

threshold level of the MTL
Receive FIFO is 64 Bytes

ETH_RECEIVEDTHRESHOLDCONTROL_32BYTES

threshold level of the MTL
Receive FIFO is 32 Bytes

ETH_RECEIVEDTHRESHOLDCONTROL_96BYTES

threshold level of the MTL
Receive FIFO is 96 Bytes

ETH_RECEIVEDTHRESHOLDCONTROL_128BYTES

threshold level of the MTL
Receive FIFO is 128 Bytes

ETH Retry Transmission
ETH_RETRYTRANSMISSION_ENABLE
ETH_RETRYTRANSMISSION_DISABLE
ETH Rx DMA Burst Length
ETH_RXDMABURSTLENGTH_1BEAT

maximum number of beats to be
transferred in one RxDMA transaction
is 1

ETH_RXDMABURSTLENGTH_2BEAT

maximum number of beats to be
transferred in one RxDMA transaction
is 2

ETH_RXDMABURSTLENGTH_4BEAT

maximum number of beats to be
transferred in one RxDMA transaction
is 4

ETH_RXDMABURSTLENGTH_8BEAT

maximum number of beats to be
transferred in one RxDMA transaction

DocID025834 Rev 4

335/964

HAL ETH Generic Driver

UM1725
is 8

ETH_RXDMABURSTLENGTH_16BEAT

maximum number of beats to be
transferred in one RxDMA transaction
is 16

ETH_RXDMABURSTLENGTH_32BEAT

maximum number of beats to be
transferred in one RxDMA transaction
is 32

ETH_RXDMABURSTLENGTH_4XPBL_4BEAT

maximum number of beats to be
transferred in one RxDMA transaction
is 4

ETH_RXDMABURSTLENGTH_4XPBL_8BEAT

maximum number of beats to be
transferred in one RxDMA transaction
is 8

ETH_RXDMABURSTLENGTH_4XPBL_16BEAT

maximum number of beats to be
transferred in one RxDMA transaction
is 16

ETH_RXDMABURSTLENGTH_4XPBL_32BEAT

maximum number of beats to be
transferred in one RxDMA transaction
is 32

ETH_RXDMABURSTLENGTH_4XPBL_64BEAT

maximum number of beats to be
transferred in one RxDMA transaction
is 64

ETH_RXDMABURSTLENGTH_4XPBL_128BEAT

maximum number of beats to be
transferred in one RxDMA transaction
is 128

ETH Rx Mode
ETH_RXPOLLING_MODE
ETH_RXINTERRUPT_MODE
ETH Second Frame Operate
ETH_SECONDFRAMEOPERARTE_ENABLE
ETH_SECONDFRAMEOPERARTE_DISABLE
ETH Source Addr Filter
ETH_SOURCEADDRFILTER_NORMAL_ENABLE
ETH_SOURCEADDRFILTER_INVERSE_ENABLE
ETH_SOURCEADDRFILTER_DISABLE
ETH Speed
ETH_SPEED_10M
ETH_SPEED_100M
ETH Transmit Flow Control
ETH_TRANSMITFLOWCONTROL_ENABLE
ETH_TRANSMITFLOWCONTROL_DISABLE

336/964

DocID025834 Rev 4

UM1725

HAL ETH Generic Driver
ETH Transmit Store Forward
ETH_TRANSMITSTOREFORWARD_ENABLE
ETH_TRANSMITSTOREFORWARD_DISABLE
ETH Transmit Threshold Control
ETH_TRANSMITTHRESHOLDCONTROL_64BYTES

threshold level of the MTL
Transmit FIFO is 64 Bytes

ETH_TRANSMITTHRESHOLDCONTROL_128BYTES

threshold level of the MTL
Transmit FIFO is 128 Bytes

ETH_TRANSMITTHRESHOLDCONTROL_192BYTES

threshold level of the MTL
Transmit FIFO is 192 Bytes

ETH_TRANSMITTHRESHOLDCONTROL_256BYTES

threshold level of the MTL
Transmit FIFO is 256 Bytes

ETH_TRANSMITTHRESHOLDCONTROL_40BYTES

threshold level of the MTL
Transmit FIFO is 40 Bytes

ETH_TRANSMITTHRESHOLDCONTROL_32BYTES

threshold level of the MTL
Transmit FIFO is 32 Bytes

ETH_TRANSMITTHRESHOLDCONTROL_24BYTES

threshold level of the MTL
Transmit FIFO is 24 Bytes

ETH_TRANSMITTHRESHOLDCONTROL_16BYTES

threshold level of the MTL
Transmit FIFO is 16 Bytes

ETH Tx DMA Burst Length
ETH_TXDMABURSTLENGTH_1BEAT

maximum number of beats to be
transferred in one TxDMA (or both)
transaction is 1

ETH_TXDMABURSTLENGTH_2BEAT

maximum number of beats to be
transferred in one TxDMA (or both)
transaction is 2

ETH_TXDMABURSTLENGTH_4BEAT

maximum number of beats to be
transferred in one TxDMA (or both)
transaction is 4

ETH_TXDMABURSTLENGTH_8BEAT

maximum number of beats to be
transferred in one TxDMA (or both)
transaction is 8

ETH_TXDMABURSTLENGTH_16BEAT

maximum number of beats to be
transferred in one TxDMA (or both)
transaction is 16

ETH_TXDMABURSTLENGTH_32BEAT

maximum number of beats to be
transferred in one TxDMA (or both)
transaction is 32

ETH_TXDMABURSTLENGTH_4XPBL_4BEAT

maximum number of beats to be
transferred in one TxDMA (or both)
transaction is 4

ETH_TXDMABURSTLENGTH_4XPBL_8BEAT

maximum number of beats to be
transferred in one TxDMA (or both)

DocID025834 Rev 4

337/964

HAL ETH Generic Driver

UM1725
transaction is 8

ETH_TXDMABURSTLENGTH_4XPBL_16BEAT

maximum number of beats to be
transferred in one TxDMA (or both)
transaction is 16

ETH_TXDMABURSTLENGTH_4XPBL_32BEAT

maximum number of beats to be
transferred in one TxDMA (or both)
transaction is 32

ETH_TXDMABURSTLENGTH_4XPBL_64BEAT

maximum number of beats to be
transferred in one TxDMA (or both)
transaction is 64

ETH_TXDMABURSTLENGTH_4XPBL_128BEAT

maximum number of beats to be
transferred in one TxDMA (or both)
transaction is 128

ETH Unicast Frames Filter
ETH_UNICASTFRAMESFILTER_PERFECTHASHTABLE
ETH_UNICASTFRAMESFILTER_HASHTABLE
ETH_UNICASTFRAMESFILTER_PERFECT
ETH Unicast Pause Frame Detect
ETH_UNICASTPAUSEFRAMEDETECT_ENABLE
ETH_UNICASTPAUSEFRAMEDETECT_DISABLE
ETH VLAN Tag Comparison
ETH_VLANTAGCOMPARISON_12BIT
ETH_VLANTAGCOMPARISON_16BIT
ETH Watchdog
ETH_WATCHDOG_ENABLE
ETH_WATCHDOG_DISABLE
ETH Zero Quanta Pause
ETH_ZEROQUANTAPAUSE_ENABLE
ETH_ZEROQUANTAPAUSE_DISABLE

338/964

DocID025834 Rev 4

UM1725

HAL FLASH Generic Driver

22

HAL FLASH Generic Driver

22.1

FLASH Firmware driver registers structures

22.1.1

FLASH_ProcessTypeDef
Data Fields
__IO FLASH_ProcedureTypeDef ProcedureOnGoing
__IO uint32_t NbSectorsToErase
__IO uint8_t VoltageForErase
__IO uint32_t Sector
__IO uint32_t Bank
__IO uint32_t Address
HAL_LockTypeDef Lock
__IO uint32_t ErrorCode

Field Documentation
__IO FLASH_ProcedureTypeDef FLASH_ProcessTypeDef::ProcedureOnGoing
__IO uint32_t FLASH_ProcessTypeDef::NbSectorsToErase
__IO uint8_t FLASH_ProcessTypeDef::VoltageForErase
__IO uint32_t FLASH_ProcessTypeDef::Sector
__IO uint32_t FLASH_ProcessTypeDef::Bank
__IO uint32_t FLASH_ProcessTypeDef::Address
HAL_LockTypeDef FLASH_ProcessTypeDef::Lock
__IO uint32_t FLASH_ProcessTypeDef::ErrorCode

22.2

FLASH Firmware driver API description

22.2.1

FLASH peripheral features
The Flash memory interface manages CPU AHB I-Code and D-Code accesses to the
Flash memory. It implements the erase and program Flash memory operations and the
read and write protection mechanisms.
The Flash memory interface accelerates code execution with a system of instruction
prefetch and cache lines.
The FLASH main features are:
Flash memory read operations
Flash memory program/erase operations
Read / write protections
Prefetch on I-Code
64 cache lines of 128 bits on I-Code
8 cache lines of 128 bits on D-Code

DocID025834 Rev 4

339/964

HAL FLASH Generic Driver

22.2.2

UM1725

How to use this driver
This driver provides functions and macros to configure and program the FLASH memory of
all STM32F4xx devices.
1.

2.

FLASH Memory IO Programming functions:
Lock and Unlock the FLASH interface using HAL_FLASH_Unlock() and
HAL_FLASH_Lock() functions
Program functions: byte, half word, word and double word
There Two modes of programming :
Polling mode using HAL_FLASH_Program() function
Interrupt mode using HAL_FLASH_Program_IT() function
Interrupts and flags management functions :
Handle FLASH interrupts by calling HAL_FLASH_IRQHandler()
Wait for last FLASH operation according to its status
Get error flag status by calling HAL_SetErrorCode()

In addition to these functions, this driver includes a set of macros allowing to handle the
following operations:
Set the latency
Enable/Disable the prefetch buffer
Enable/Disable the Instruction cache and the Data cache
Reset the Instruction cache and the Data cache
Enable/Disable the FLASH interrupts
Monitor the FLASH flags status

22.2.3

Programming operation functions
This subsection provides a set of functions allowing to manage the FLASH program
operations.
This section contains the following APIs:
HAL_FLASH_Program()
HAL_FLASH_Program_IT()
HAL_FLASH_IRQHandler()
HAL_FLASH_EndOfOperationCallback()
HAL_FLASH_OperationErrorCallback()

22.2.4

Peripheral Control functions
This subsection provides a set of functions allowing to control the FLASH memory
operations.
This section contains the following APIs:
HAL_FLASH_Unlock()
HAL_FLASH_Lock()
HAL_FLASH_OB_Unlock()
HAL_FLASH_OB_Lock()
HAL_FLASH_OB_Launch()

22.2.5

Peripheral Errors functions
This subsection permits to get in run-time Errors of the FLASH peripheral.
This section contains the following APIs:
HAL_FLASH_GetError()

340/964

DocID025834 Rev 4

UM1725

HAL FLASH Generic Driver
FLASH_WaitForLastOperation()

22.2.6

Detailed description of functions
HAL_FLASH_Program
Function Name

HAL_StatusTypeDef HAL_FLASH_Program (uint32_t
TypeProgram, uint32_t Address, uint64_t Data)

Function Description

Program byte, halfword, word or double word at a specified
address.

Parameters

TypeProgram: Indicate the way to program at a specified
address. This parameter can be a value of FLASH Type
Program
Address: specifies the address to be programmed.
Data: specifies the data to be programmed

Return values

HAL_StatusTypeDef: HAL Status

HAL_FLASH_Program_IT
Function Name

HAL_StatusTypeDef HAL_FLASH_Program_IT (uint32_t
TypeProgram, uint32_t Address, uint64_t Data)

Function Description

Program byte, halfword, word or double word at a specified
address with interrupt enabled.

Parameters

TypeProgram: Indicate the way to program at a specified
address. This parameter can be a value of FLASH Type
Program
Address: specifies the address to be programmed.
Data: specifies the data to be programmed

Return values

HAL: Status

HAL_FLASH_IRQHandler
Function Name

void HAL_FLASH_IRQHandler (void )

Function Description

This function handles FLASH interrupt request.

Return values

None

HAL_FLASH_EndOfOperationCallback
Function Name

void HAL_FLASH_EndOfOperationCallback (uint32_t
ReturnValue)

Function Description

FLASH end of operation interrupt callback.

Parameters

ReturnValue: The value saved in this parameter depends on
the ongoing procedure Mass Erase: Bank number which has
been requested to erase Sectors Erase: Sector which has
been erased (if 0xFFFFFFFFU, it means that all the selected
sectors have been erased) Program: Address which was
selected for data program

Return values

None

DocID025834 Rev 4

341/964

HAL FLASH Generic Driver

UM1725

HAL_FLASH_OperationErrorCallback
Function Name

void HAL_FLASH_OperationErrorCallback (uint32_t
ReturnValue)

Function Description

FLASH operation error interrupt callback.

Parameters

ReturnValue: The value saved in this parameter depends on
the ongoing procedure Mass Erase: Bank number which has
been requested to erase Sectors Erase: Sector number which
returned an error Program: Address which was selected for
data program

Return values

None

HAL_FLASH_Unlock
Function Name

HAL_StatusTypeDef HAL_FLASH_Unlock (void )

Function Description

Unlock the FLASH control register access.

Return values

HAL: Status

HAL_FLASH_Lock
Function Name

HAL_StatusTypeDef HAL_FLASH_Lock (void )

Function Description

Locks the FLASH control register access.

Return values

HAL: Status

HAL_FLASH_OB_Unlock
Function Name

HAL_StatusTypeDef HAL_FLASH_OB_Unlock (void )

Function Description

Unlock the FLASH Option Control Registers access.

Return values

HAL: Status

HAL_FLASH_OB_Lock
Function Name

HAL_StatusTypeDef HAL_FLASH_OB_Lock (void )

Function Description

Lock the FLASH Option Control Registers access.

Return values

HAL: Status

HAL_FLASH_OB_Launch
Function Name

HAL_StatusTypeDef HAL_FLASH_OB_Launch (void )

Function Description

Launch the option byte loading.

Return values

HAL: Status

HAL_FLASH_GetError

342/964

Function Name

uint32_t HAL_FLASH_GetError (void )

Function Description

Get the specific FLASH error flag.

DocID025834 Rev 4

UM1725

HAL FLASH Generic Driver
Return values

FLASH_ErrorCode: The returned value can be a
combination of:
HAL_FLASH_ERROR_RD: FLASH Read Protection
error flag (PCROP)
HAL_FLASH_ERROR_PGS: FLASH Programming
Sequence error flag
HAL_FLASH_ERROR_PGP: FLASH Programming
Parallelism error flag
HAL_FLASH_ERROR_PGA: FLASH Programming
Alignment error flag
HAL_FLASH_ERROR_WRP: FLASH Write protected
error flag
HAL_FLASH_ERROR_OPERATION: FLASH operation
Error flag

FLASH_WaitForLastOperation
Function Name

HAL_StatusTypeDef FLASH_WaitForLastOperation (uint32_t
Timeout)

Function Description

Wait for a FLASH operation to complete.

Parameters

Timeout: maximum flash operationtimeout

Return values

HAL: Status

22.3

FLASH Firmware driver defines

22.3.1

FLASH
FLASH Error Code
HAL_FLASH_ERROR_NONE

No error

HAL_FLASH_ERROR_RD

Read Protection error

HAL_FLASH_ERROR_PGS

Programming Sequence error

HAL_FLASH_ERROR_PGP

Programming Parallelism error

HAL_FLASH_ERROR_PGA

Programming Alignment error

HAL_FLASH_ERROR_WRP

Write protection error

HAL_FLASH_ERROR_OPERATION

Operation Error

FLASH Exported Macros
__HAL_FLASH_SET_LATENCY

Description:
Set the FLASH Latency.
Parameters:
__LATENCY__: FLASH Latency
The value of this parameter
depend on device used within the
same series
Return value:
none

DocID025834 Rev 4

343/964

HAL FLASH Generic Driver
__HAL_FLASH_GET_LATENCY

UM1725
Description:
Get the FLASH Latency.
Return value:
FLASH: Latency The value of this
parameter depend on device
used within the same series

__HAL_FLASH_PREFETCH_BUFFER_ENABLE

Description:
Enable the FLASH prefetch
buffer.
Return value:
none

__HAL_FLASH_PREFETCH_BUFFER_DISABL
E

Description:
Disable the FLASH prefetch
buffer.
Return value:
none

__HAL_FLASH_INSTRUCTION_CACHE_ENAB
LE

Description:
Enable the FLASH instruction
cache.
Return value:
none

__HAL_FLASH_INSTRUCTION_CACHE_DISAB
LE

Description:
Disable the FLASH instruction
cache.
Return value:
none

__HAL_FLASH_DATA_CACHE_ENABLE

Description:
Enable the FLASH data cache.
Return value:
none

__HAL_FLASH_DATA_CACHE_DISABLE

Description:
Disable the FLASH data cache.
Return value:
none

__HAL_FLASH_INSTRUCTION_CACHE_RESE
T

Description:
Resets the FLASH instruction
Cache.
Return value:

344/964

DocID025834 Rev 4

UM1725

HAL FLASH Generic Driver
None
Notes:
This function must be used only
when the Instruction Cache is
disabled.
__HAL_FLASH_DATA_CACHE_RESET

Description:
Resets the FLASH data Cache.
Return value:
None
Notes:
This function must be used only
when the data Cache is disabled.
Description:

__HAL_FLASH_ENABLE_IT

Enable the specified FLASH
interrupt.
Parameters:
__INTERRUPT__: : FLASH
interrupt This parameter can be
any combination of the following
values:
FLASH_IT_EOP: End of
FLASH Operation Interrupt
FLASH_IT_ERR: Error
Interrupt
Return value:
none
__HAL_FLASH_DISABLE_IT

Description:
Disable the specified FLASH
interrupt.
Parameters:
__INTERRUPT__: : FLASH
interrupt This parameter can be
any combination of the following
values:
FLASH_IT_EOP: End of
FLASH Operation Interrupt
FLASH_IT_ERR: Error
Interrupt
Return value:
none
Description:

__HAL_FLASH_GET_FLAG

Get the specified FLASH flag
status.
DocID025834 Rev 4

345/964

HAL FLASH Generic Driver

UM1725
Parameters:
__FLAG__: specifies the FLASH
flag to check. This parameter can
be one of the following values:
FLASH_FLAG_EOP :
FLASH End of Operation flag
FLASH_FLAG_OPERR :
FLASH operation Error flag
FLASH_FLAG_WRPERR:
FLASH Write protected error
flag
FLASH_FLAG_PGAERR:
FLASH Programming
Alignment error flag
FLASH_FLAG_PGPERR:
FLASH Programming
Parallelism error flag
FLASH_FLAG_PGSERR:
FLASH Programming
Sequence error flag
FLASH_FLAG_RDERR :
FLASH Read Protection
error flag (PCROP)
FLASH_FLAG_BSY : FLASH
Busy flag
Return value:
The: new state of __FLAG__
(SET or RESET).

__HAL_FLASH_CLEAR_FLAG

Description:
Clear the specified FLASH flag.
Parameters:
__FLAG__: specifies the FLASH
flags to clear. This parameter can
be any combination of the
following values:
FLASH_FLAG_EOP :
FLASH End of Operation flag
FLASH_FLAG_OPERR :
FLASH operation Error flag
FLASH_FLAG_WRPERR:
FLASH Write protected error
flag
FLASH_FLAG_PGAERR:
FLASH Programming
Alignment error flag
FLASH_FLAG_PGPERR:
FLASH Programming
Parallelism error flag
FLASH_FLAG_PGSERR:
FLASH Programming
Sequence error flag

346/964

DocID025834 Rev 4

UM1725

HAL FLASH Generic Driver
FLASH_FLAG_RDERR :
FLASH Read Protection
error flag (PCROP)
Return value:
none
FLASH Flag definition
FLASH_FLAG_EOP

FLASH End of Operation flag

FLASH_FLAG_OPERR

FLASH operation Error flag

FLASH_FLAG_WRPERR

FLASH Write protected error flag

FLASH_FLAG_PGAERR

FLASH Programming Alignment error flag

FLASH_FLAG_PGPERR

FLASH Programming Parallelism error flag

FLASH_FLAG_PGSERR

FLASH Programming Sequence error flag

FLASH_FLAG_RDERR

Read Protection error flag (PCROP)

FLASH_FLAG_BSY

FLASH Busy flag

FLASH Interrupt definition
FLASH_IT_EOP

End of FLASH Operation Interrupt source

FLASH_IT_ERR

Error Interrupt source

FLASH Private macros to check input parameters
IS_FLASH_TYPEPROGRAM
FLASH Keys
RDP_KEY
FLASH_KEY1
FLASH_KEY2
FLASH_OPT_KEY1
FLASH_OPT_KEY2
FLASH Latency
FLASH_LATENCY_0

FLASH Zero Latency cycle

FLASH_LATENCY_1

FLASH One Latency cycle

FLASH_LATENCY_2

FLASH Two Latency cycles

FLASH_LATENCY_3

FLASH Three Latency cycles

FLASH_LATENCY_4

FLASH Four Latency cycles

FLASH_LATENCY_5

FLASH Five Latency cycles

FLASH_LATENCY_6

FLASH Six Latency cycles

FLASH_LATENCY_7

FLASH Seven Latency cycles

FLASH_LATENCY_8

FLASH Eight Latency cycles

FLASH_LATENCY_9

FLASH Nine Latency cycles

FLASH_LATENCY_10

FLASH Ten Latency cycles

DocID025834 Rev 4

347/964

HAL FLASH Generic Driver
FLASH_LATENCY_11

FLASH Eleven Latency cycles

UM1725

FLASH_LATENCY_12

FLASH Twelve Latency cycles

FLASH_LATENCY_13

FLASH Thirteen Latency cycles

FLASH_LATENCY_14

FLASH Fourteen Latency cycles

FLASH_LATENCY_15

FLASH Fifteen Latency cycles

FLASH Program Parallelism
FLASH_PSIZE_BYTE
FLASH_PSIZE_HALF_WORD
FLASH_PSIZE_WORD
FLASH_PSIZE_DOUBLE_WORD
CR_PSIZE_MASK
FLASH Type Program

348/964

FLASH_TYPEPROGRAM_BYTE

Program byte (8-bit) at a specified address

FLASH_TYPEPROGRAM_HALFWORD

Program a half-word (16-bit) at a specified
address

FLASH_TYPEPROGRAM_WORD

Program a word (32-bit) at a specified
address

FLASH_TYPEPROGRAM_DOUBLEWORD

Program a double word (64-bit) at a
specified address

DocID025834 Rev 4

UM1725

HAL FLASH Extension Driver

23

HAL FLASH Extension Driver

23.1

FLASHEx Firmware driver registers structures

23.1.1

FLASH_EraseInitTypeDef
Data Fields
uint32_t TypeErase
uint32_t Banks
uint32_t Sector
uint32_t NbSectors
uint32_t VoltageRange

Field Documentation
uint32_t FLASH_EraseInitTypeDef::TypeErase
Mass erase or sector Erase. This parameter can be a value of
FLASHEx_Type_Erase
uint32_t FLASH_EraseInitTypeDef::Banks
Select banks to erase when Mass erase is enabled. This parameter must be a value
of FLASHEx_Banks
uint32_t FLASH_EraseInitTypeDef::Sector
Initial FLASH sector to erase when Mass erase is disabled This parameter must be a
value of FLASHEx_Sectors
uint32_t FLASH_EraseInitTypeDef::NbSectors
Number of sectors to be erased. This parameter must be a value between 1 and (max
number of sectors - value of Initial sector)
uint32_t FLASH_EraseInitTypeDef::VoltageRange
The device voltage range which defines the erase parallelism This parameter must be
a value of FLASHEx_Voltage_Range

23.1.2

FLASH_OBProgramInitTypeDef
Data Fields
uint32_t OptionType
uint32_t WRPState
uint32_t WRPSector
uint32_t Banks
uint32_t RDPLevel
uint32_t BORLevel
uint8_t USERConfig

Field Documentation

DocID025834 Rev 4

349/964

HAL FLASH Extension Driver

UM1725

uint32_t FLASH_OBProgramInitTypeDef::OptionType
Option byte to be configured. This parameter can be a value of
FLASHEx_Option_Type
uint32_t FLASH_OBProgramInitTypeDef::WRPState
Write protection activation or deactivation. This parameter can be a value of
FLASHEx_WRP_State
uint32_t FLASH_OBProgramInitTypeDef::WRPSector
Specifies the sector(s) to be write protected. The value of this parameter depend on
device used within the same series
uint32_t FLASH_OBProgramInitTypeDef::Banks
Select banks for WRP activation/deactivation of all sectors. This parameter must be a
value of FLASHEx_Banks
uint32_t FLASH_OBProgramInitTypeDef::RDPLevel
Set the read protection level. This parameter can be a value of
FLASHEx_Option_Bytes_Read_Protection
uint32_t FLASH_OBProgramInitTypeDef::BORLevel
Set the BOR Level. This parameter can be a value of FLASHEx_BOR_Reset_Level
uint8_t FLASH_OBProgramInitTypeDef::USERConfig
Program the FLASH User Option Byte: IWDG_SW / RST_STOP / RST_STDBY.

23.1.3

FLASH_AdvOBProgramInitTypeDef
Data Fields
uint32_t OptionType
uint32_t PCROPState
uint32_t Banks
uint16_t SectorsBank1
uint16_t SectorsBank2
uint8_t BootConfig

Field Documentation
uint32_t FLASH_AdvOBProgramInitTypeDef::OptionType
Option byte to be configured for extension. This parameter can be a value of
FLASHEx_Advanced_Option_Type
uint32_t FLASH_AdvOBProgramInitTypeDef::PCROPState
PCROP activation or deactivation. This parameter can be a value of
FLASHEx_PCROP_State
uint32_t FLASH_AdvOBProgramInitTypeDef::Banks
Select banks for PCROP activation/deactivation of all sectors. This parameter must
be a value of FLASHEx_Banks
uint16_t FLASH_AdvOBProgramInitTypeDef::SectorsBank1
Specifies the sector(s) set for PCROP for Bank1. This parameter can be a value of
FLASHEx_Option_Bytes_PC_ReadWrite_Protection
uint16_t FLASH_AdvOBProgramInitTypeDef::SectorsBank2
Specifies the sector(s) set for PCROP for Bank2. This parameter can be a value of
FLASHEx_Option_Bytes_PC_ReadWrite_Protection
uint8_t FLASH_AdvOBProgramInitTypeDef::BootConfig
Specifies Option bytes for boot config. This parameter can be a value of
FLASHEx_Dual_Boot

350/964

DocID025834 Rev 4

UM1725

HAL FLASH Extension Driver

23.2

FLASHEx Firmware driver API description

23.2.1

Flash Extension features
Comparing to other previous devices, the FLASH interface for STM32F427xx/437xx and
STM32F429xx/439xx devices contains the following additional features
Capacity up to 2 Mbyte with dual bank architecture supporting read-while-write
capability (RWW)
Dual bank memory organization
PCROP protection for all banks

23.2.2

How to use this driver
This driver provides functions to configure and program the FLASH memory of all
STM32F427xx/437xx, STM32F429xx/439xx, STM32F469xx/479xx and STM32F446xx
devices. It includes
1.

2.

3.

23.2.3

FLASH Memory Erase functions:
Lock and Unlock the FLASH interface using HAL_FLASH_Unlock() and
HAL_FLASH_Lock() functions
Erase function: Erase sector, erase all sectors
There are two modes of erase :
Polling Mode using HAL_FLASHEx_Erase()
Interrupt Mode using HAL_FLASHEx_Erase_IT()
Option Bytes Programming functions: Use HAL_FLASHEx_OBProgram() to :
Set/Reset the write protection
Set the Read protection Level
Set the BOR level
Program the user Option Bytes
Advanced Option Bytes Programming functions: Use
HAL_FLASHEx_AdvOBProgram() to :
Extended space (bank 2) erase function
Full FLASH space (2 Mo) erase (bank 1 and bank 2)
Dual Boot activation
Write protection configuration for bank 2
PCROP protection configuration and control for both banks

Extended programming operation functions
This subsection provides a set of functions allowing to manage the Extension FLASH
programming operations.
This section contains the following APIs:
HAL_FLASHEx_Erase()
HAL_FLASHEx_Erase_IT()
HAL_FLASHEx_OBProgram()
HAL_FLASHEx_OBGetConfig()
HAL_FLASHEx_AdvOBProgram()
HAL_FLASHEx_AdvOBGetConfig()
HAL_FLASHEx_OB_SelectPCROP()
HAL_FLASHEx_OB_DeSelectPCROP()
HAL_FLASHEx_OB_GetBank2WRP()

DocID025834 Rev 4

351/964

HAL FLASH Extension Driver

23.2.4

UM1725

Detailed description of functions
HAL_FLASHEx_Erase
Function Name

HAL_StatusTypeDef HAL_FLASHEx_Erase
(FLASH_EraseInitTypeDef * pEraseInit, uint32_t * SectorError)

Function Description

Perform a mass erase or erase the specified FLASH memory
sectors.

Parameters

pEraseInit: pointer to an FLASH_EraseInitTypeDef structure
that contains the configuration information for the erasing.
SectorError: pointer to variable that contains the
configuration information on faulty sector in case of error
(0xFFFFFFFFU means that all the sectors have been
correctly erased)

Return values

HAL: Status

HAL_FLASHEx_Erase_IT
Function Name

HAL_StatusTypeDef HAL_FLASHEx_Erase_IT
(FLASH_EraseInitTypeDef * pEraseInit)

Function Description

Perform a mass erase or erase the specified FLASH memory
sectors with interrupt enabled.

Parameters

pEraseInit: pointer to an FLASH_EraseInitTypeDef structure
that contains the configuration information for the erasing.

Return values

HAL: Status

HAL_FLASHEx_OBProgram
Function Name

HAL_StatusTypeDef HAL_FLASHEx_OBProgram
(FLASH_OBProgramInitTypeDef * pOBInit)

Function Description

Program option bytes.

Parameters

pOBInit: pointer to an FLASH_OBInitStruct structure that
contains the configuration information for the programming.

Return values

HAL: Status

HAL_FLASHEx_OBGetConfig

352/964

Function Name

void HAL_FLASHEx_OBGetConfig
(FLASH_OBProgramInitTypeDef * pOBInit)

Function Description

Get the Option byte configuration.

Parameters

pOBInit: pointer to an FLASH_OBInitStruct structure that
contains the configuration information for the programming.

Return values

None

DocID025834 Rev 4

UM1725

HAL FLASH Extension Driver

HAL_FLASHEx_AdvOBProgram
Function Name

HAL_StatusTypeDef HAL_FLASHEx_AdvOBProgram
(FLASH_AdvOBProgramInitTypeDef * pAdvOBInit)

Function Description

Program option bytes.

Parameters

pAdvOBInit: pointer to an
FLASH_AdvOBProgramInitTypeDef structure that contains
the configuration information for the programming.

Return values

HAL: Status

HAL_FLASHEx_AdvOBGetConfig
Function Name

void HAL_FLASHEx_AdvOBGetConfig
(FLASH_AdvOBProgramInitTypeDef * pAdvOBInit)

Function Description

Get the OBEX byte configuration.

Parameters

pAdvOBInit: pointer to an
FLASH_AdvOBProgramInitTypeDef structure that contains
the configuration information for the programming.

Return values

None

HAL_FLASHEx_OB_SelectPCROP
Function
Name

HAL_StatusTypeDef HAL_FLASHEx_OB_SelectPCROP (void )

Function
Descripti
on

Select the Protection Mode.

Return
values

HAL: Status

Notes

After PCROP activated Option Byte modification NOT POSSIBLE!
excepted Global Read Out Protection modification (from level1 to level0)
Once SPRMOD bit is active unprotection of a protected sector is not
possible
Read a protected sector will set RDERR Flag and write a protected sector
will set WRPERR Flag
This function can be used only for
STM32F42xxx/STM32F43xxx/STM32F401xx/STM32F411xx/STM32F446
xx/
STM32F469xx/STM32F479xx/STM32F412Zx/STM32F412Vx/STM32F412
Rx/STM32F412Cx devices.

HAL_FLASHEx_OB_DeSelectPCROP
Function
Name

HAL_StatusTypeDef HAL_FLASHEx_OB_DeSelectPCROP (void )

Function
Descripti
on

Deselect the Protection Mode.

Return

HAL: Status
DocID025834 Rev 4

353/964

HAL FLASH Extension Driver
values
Notes

UM1725
After PCROP activated Option Byte modification NOT POSSIBLE!
excepted Global Read Out Protection modification (from level1 to level0)
Once SPRMOD bit is active unprotection of a protected sector is not
possible
Read a protected sector will set RDERR Flag and write a protected sector
will set WRPERR Flag
This function can be used only for
STM32F42xxx/STM32F43xxx/STM32F401xx/STM32F411xx/STM32F446
xx/
STM32F469xx/STM32F479xx/STM32F412Zx/STM32F412Vx/STM32F412
Rx/STM32F412Cx devices.

HAL_FLASHEx_OB_GetBank2WRP
Function Name

uint16_t HAL_FLASHEx_OB_GetBank2WRP (void )

Function Description

Returns the FLASH Write Protection Option Bytes value for Bank
2.

Return values

The: FLASH Write Protection Option Bytes value

Notes

This function can be used only for
STM32F42xxx/STM32F43xxx/STM32F469xx/STM32F479xx
devices.

FLASH_Erase_Sector
Function Name

void FLASH_Erase_Sector (uint32_t Sector, uint8_t
VoltageRange)

Function Description

Erase the specified FLASH memory sector.

Parameters

Sector: FLASH sector to erase The value of this parameter
depend on device used within the same series
VoltageRange: The device voltage range which defines the
erase parallelism. This parameter can be one of the following
values:
FLASH_VOLTAGE_RANGE_1: when the device voltage
range is 1.8V to 2.1V, the operation will be done by byte
(8-bit)
FLASH_VOLTAGE_RANGE_2: when the device voltage
range is 2.1V to 2.7V, the operation will be done by half
word (16-bit)
FLASH_VOLTAGE_RANGE_3: when the device voltage
range is 2.7V to 3.6V, the operation will be done by word
(32-bit)
FLASH_VOLTAGE_RANGE_4: when the device voltage
range is 2.7V to 3.6V + External Vpp, the operation will
be done by double word (64-bit)

Return values

None

FLASH_FlushCaches
Function Name
354/964

void FLASH_FlushCaches (void )
DocID025834 Rev 4

UM1725
Function Description

HAL FLASH Extension Driver
Flush the instruction and data caches.

Return values

None

23.3

FLASHEx Firmware driver defines

23.3.1

FLASHEx
FLASH Advanced Option Type
OPTIONBYTE_PCROP

PCROP option byte configuration

OPTIONBYTE_BOOTCONFIG

BOOTConfig option byte configuration

FLASH Banks
FLASH_BANK_1

Bank 1

FLASH_BANK_2

Bank 2

FLASH_BANK_BOTH

Bank1 and Bank2

FLASH BOR Reset Level
OB_BOR_LEVEL3

Supply voltage ranges from 2.70 to 3.60 V

OB_BOR_LEVEL2

Supply voltage ranges from 2.40 to 2.70 V

OB_BOR_LEVEL1

Supply voltage ranges from 2.10 to 2.40 V

OB_BOR_OFF

Supply voltage ranges from 1.62 to 2.10 V

FLASH Dual Boot
OB_DUAL_BOOT_ENABLE

Dual Bank Boot Enable

OB_DUAL_BOOT_DISABLE

Dual Bank Boot Disable, always boot on User Flash

FLASH Private macros to check input parameters
IS_FLASH_TYPEERASE
IS_VOLTAGERANGE
IS_WRPSTATE
IS_OPTIONBYTE
IS_OB_RDP_LEVEL
IS_OB_IWDG_SOURCE
IS_OB_STOP_SOURCE
IS_OB_STDBY_SOURCE
IS_OB_BOR_LEVEL
IS_PCROPSTATE
IS_OBEX
IS_FLASH_LATENCY
IS_FLASH_BANK
IS_FLASH_SECTOR
IS_FLASH_ADDRESS

DocID025834 Rev 4

355/964

HAL FLASH Extension Driver
IS_FLASH_NBSECTORS

UM1725

IS_OB_WRP_SECTOR
IS_OB_PCROP
IS_OB_BOOT
IS_OB_PCROP_SELECT
FLASH Mass Erase bit
FLASH_MER_BIT

2 MER bits here to clear

FLASH Option Bytes IWatchdog
OB_IWDG_SW

Software IWDG selected

OB_IWDG_HW

Hardware IWDG selected

FLASH Option Bytes nRST_STDBY
OB_STDBY_NO_RST

No reset generated when entering in STANDBY

OB_STDBY_RST

Reset generated when entering in STANDBY

FLASH Option Bytes nRST_STOP
OB_STOP_NO_RST

No reset generated when entering in STOP

OB_STOP_RST

Reset generated when entering in STOP

FLASH Option Bytes PC ReadWrite Protection

356/964

OB_PCROP_SECTOR_0

PC Read/Write protection of Sector0

OB_PCROP_SECTOR_1

PC Read/Write protection of Sector1

OB_PCROP_SECTOR_2

PC Read/Write protection of Sector2

OB_PCROP_SECTOR_3

PC Read/Write protection of Sector3

OB_PCROP_SECTOR_4

PC Read/Write protection of Sector4

OB_PCROP_SECTOR_5

PC Read/Write protection of Sector5

OB_PCROP_SECTOR_6

PC Read/Write protection of Sector6

OB_PCROP_SECTOR_7

PC Read/Write protection of Sector7

OB_PCROP_SECTOR_8

PC Read/Write protection of Sector8

OB_PCROP_SECTOR_9

PC Read/Write protection of Sector9

OB_PCROP_SECTOR_10

PC Read/Write protection of Sector10

OB_PCROP_SECTOR_11

PC Read/Write protection of Sector11

OB_PCROP_SECTOR_12

PC Read/Write protection of Sector12

OB_PCROP_SECTOR_13

PC Read/Write protection of Sector13

OB_PCROP_SECTOR_14

PC Read/Write protection of Sector14

OB_PCROP_SECTOR_15

PC Read/Write protection of Sector15

OB_PCROP_SECTOR_16

PC Read/Write protection of Sector16

OB_PCROP_SECTOR_17

PC Read/Write protection of Sector17

OB_PCROP_SECTOR_18

PC Read/Write protection of Sector18

DocID025834 Rev 4

UM1725
OB_PCROP_SECTOR_19

HAL FLASH Extension Driver
PC Read/Write protection of Sector19

OB_PCROP_SECTOR_20

PC Read/Write protection of Sector20

OB_PCROP_SECTOR_21

PC Read/Write protection of Sector21

OB_PCROP_SECTOR_22

PC Read/Write protection of Sector22

OB_PCROP_SECTOR_23

PC Read/Write protection of Sector23

OB_PCROP_SECTOR_All

PC Read/Write protection of all Sectors

FLASH Option Bytes Read Protection
OB_RDP_LEVEL_0
OB_RDP_LEVEL_1
OB_RDP_LEVEL_2

Warning: When enabling read protection level 2 it s no more
possible to go back to level 1 or 0

FLASH Option Bytes Write Protection
OB_WRP_SECTOR_0

Write protection of Sector0

OB_WRP_SECTOR_1

Write protection of Sector1

OB_WRP_SECTOR_2

Write protection of Sector2

OB_WRP_SECTOR_3

Write protection of Sector3

OB_WRP_SECTOR_4

Write protection of Sector4

OB_WRP_SECTOR_5

Write protection of Sector5

OB_WRP_SECTOR_6

Write protection of Sector6

OB_WRP_SECTOR_7

Write protection of Sector7

OB_WRP_SECTOR_8

Write protection of Sector8

OB_WRP_SECTOR_9

Write protection of Sector9

OB_WRP_SECTOR_10

Write protection of Sector10

OB_WRP_SECTOR_11

Write protection of Sector11

OB_WRP_SECTOR_12

Write protection of Sector12

OB_WRP_SECTOR_13

Write protection of Sector13

OB_WRP_SECTOR_14

Write protection of Sector14

OB_WRP_SECTOR_15

Write protection of Sector15

OB_WRP_SECTOR_16

Write protection of Sector16

OB_WRP_SECTOR_17

Write protection of Sector17

OB_WRP_SECTOR_18

Write protection of Sector18

OB_WRP_SECTOR_19

Write protection of Sector19

OB_WRP_SECTOR_20

Write protection of Sector20

OB_WRP_SECTOR_21

Write protection of Sector21

OB_WRP_SECTOR_22

Write protection of Sector22

OB_WRP_SECTOR_23

Write protection of Sector23

OB_WRP_SECTOR_All

Write protection of all Sectors
DocID025834 Rev 4

357/964

HAL FLASH Extension Driver
FLASH Option Type

UM1725

OPTIONBYTE_WRP

WRP option byte configuration

OPTIONBYTE_RDP

RDP option byte configuration

OPTIONBYTE_USER

USER option byte configuration

OPTIONBYTE_BOR

BOR option byte configuration

FLASH PCROP State
OB_PCROP_STATE_DISABLE

Disable PCROP

OB_PCROP_STATE_ENABLE

Enable PCROP

FLASH Sectors
FLASH_SECTOR_0

Sector Number 0

FLASH_SECTOR_1

Sector Number 1

FLASH_SECTOR_2

Sector Number 2

FLASH_SECTOR_3

Sector Number 3

FLASH_SECTOR_4

Sector Number 4

FLASH_SECTOR_5

Sector Number 5

FLASH_SECTOR_6

Sector Number 6

FLASH_SECTOR_7

Sector Number 7

FLASH_SECTOR_8

Sector Number 8

FLASH_SECTOR_9

Sector Number 9

FLASH_SECTOR_10

Sector Number 10

FLASH_SECTOR_11

Sector Number 11

FLASH_SECTOR_12

Sector Number 12

FLASH_SECTOR_13

Sector Number 13

FLASH_SECTOR_14

Sector Number 14

FLASH_SECTOR_15

Sector Number 15

FLASH_SECTOR_16

Sector Number 16

FLASH_SECTOR_17

Sector Number 17

FLASH_SECTOR_18

Sector Number 18

FLASH_SECTOR_19

Sector Number 19

FLASH_SECTOR_20

Sector Number 20

FLASH_SECTOR_21

Sector Number 21

FLASH_SECTOR_22

Sector Number 22

FLASH_SECTOR_23

Sector Number 23

FLASH Selection Protection Mode

358/964

OB_PCROP_DESELECTED

Disabled PcROP, nWPRi bits used for Write Protection on
sector i

OB_PCROP_SELECTED

Enable PcROP, nWPRi bits used for PCRoP Protection on
DocID025834 Rev 4

UM1725

HAL FLASH Extension Driver
sector i
FLASH Type Erase
FLASH_TYPEERASE_SECTORS

Sectors erase only

FLASH_TYPEERASE_MASSERASE

Flash Mass erase activation

FLASH Voltage Range
FLASH_VOLTAGE_RANGE_1

Device operating range: 1.8V to 2.1V

FLASH_VOLTAGE_RANGE_2

Device operating range: 2.1V to 2.7V

FLASH_VOLTAGE_RANGE_3

Device operating range: 2.7V to 3.6V

FLASH_VOLTAGE_RANGE_4

Device operating range: 2.7V to 3.6V + External Vpp

FLASH WRP State
OB_WRPSTATE_DISABLE

Disable the write protection of the desired bank 1 sectors

OB_WRPSTATE_ENABLE

Enable the write protection of the desired bank 1 sectors

DocID025834 Rev 4

359/964

HAL FLASH__RAMFUNC Generic Driver

UM1725

24

HAL FLASH__RAMFUNC Generic Driver

24.1

FLASH__RAMFUNC Firmware driver API description

24.1.1

APIs executed from Internal RAM

ARM Compiler
RAM functions are defined using the toolchain options. Functions that are be executed in
RAM should reside in a separate source module. Using the 'Options for File' dialog you can
simply change the 'Code / Const' area of a module to a memory space in physical RAM.
Available memory areas are declared in the 'Target' tab of the Options for Target' dialog.

ICCARM Compiler
RAM functions are defined using a specific toolchain keyword "__ramfunc".

GNU Compiler
RAM functions are defined using a specific toolchain attribute
"__attribute__((section(".RamFunc")))".

24.1.2

ramfunc functions
This subsection provides a set of functions that should be executed from RAM transfers.
This section contains the following APIs:
HAL_FLASHEx_StopFlashInterfaceClk()
HAL_FLASHEx_StartFlashInterfaceClk()
HAL_FLASHEx_EnableFlashSleepMode()
HAL_FLASHEx_DisableFlashSleepMode()

24.1.3

Detailed description of functions
HAL_FLASHEx_StopFlashInterfaceClk
Function Name

__RAM_FUNC HAL_FLASHEx_StopFlashInterfaceClk (void )

Function Description

Stop the flash interface while System Run.

Return values

None

Notes

This mode is only available for STM32F41xxx/STM32F446xx
devices.
This mode couldn't be set while executing with the flash itself.
It should be done with specific routine executed from RAM.

HAL_FLASHEx_StartFlashInterfaceClk
Function Name

__RAM_FUNC HAL_FLASHEx_StartFlashInterfaceClk (void )

Function Description

Start the flash interface while System Run.

Return values
360/964

None
DocID025834 Rev 4

UM1725

HAL FLASH__RAMFUNC Generic Driver
Notes

This mode is only available for STM32F411xx/STM32F446xx
devices.
This mode couldn't be set while executing with the flash itself.
It should be done with specific routine executed from RAM.

HAL_FLASHEx_EnableFlashSleepMode
Function Name

__RAM_FUNC HAL_FLASHEx_EnableFlashSleepMode (void )

Function Description

Enable the flash sleep while System Run.

Return values

None

Notes

This mode is only available for STM32F41xxx/STM32F446xx
devices.
This mode could n't be set while executing with the flash
itself. It should be done with specific routine executed from
RAM.

HAL_FLASHEx_DisableFlashSleepMode
Function Name

__RAM_FUNC HAL_FLASHEx_DisableFlashSleepMode (void )

Function Description

Disable the flash sleep while System Run.

Return values

None

Notes

This mode is only available for STM32F41xxx/STM32F446xx
devices.
This mode couldn't be set while executing with the flash itself.
It should be done with specific routine executed from RAM.

DocID025834 Rev 4

361/964

HAL FMPI2C Generic Driver

UM1725

25

HAL FMPI2C Generic Driver

25.1

FMPI2C Firmware driver registers structures

25.1.1

FMPI2C_InitTypeDef
Data Fields
uint32_t Timing
uint32_t OwnAddress1
uint32_t AddressingMode
uint32_t DualAddressMode
uint32_t OwnAddress2
uint32_t OwnAddress2Masks
uint32_t GeneralCallMode
uint32_t NoStretchMode

Field Documentation
uint32_t FMPI2C_InitTypeDef::Timing
Specifies the FMPI2C_TIMINGR_register value. This parameter calculated by
referring to FMPI2C initialization section in Reference manual
uint32_t FMPI2C_InitTypeDef::OwnAddress1
Specifies the first device own address. This parameter can be a 7-bit or 10-bit
address.
uint32_t FMPI2C_InitTypeDef::AddressingMode
Specifies if 7-bit or 10-bit addressing mode is selected. This parameter can be a
value of FMPI2C_ADDRESSING_MODE
uint32_t FMPI2C_InitTypeDef::DualAddressMode
Specifies if dual addressing mode is selected. This parameter can be a value of
FMPI2C_DUAL_ADDRESSING_MODE
uint32_t FMPI2C_InitTypeDef::OwnAddress2
Specifies the second device own address if dual addressing mode is selected This
parameter can be a 7-bit address.
uint32_t FMPI2C_InitTypeDef::OwnAddress2Masks
Specifies the acknowledge mask address second device own address if dual
addressing mode is selected This parameter can be a value of
FMPI2C_OWN_ADDRESS2_MASKS
uint32_t FMPI2C_InitTypeDef::GeneralCallMode
Specifies if general call mode is selected. This parameter can be a value of
FMPI2C_GENERAL_CALL_ADDRESSING_MODE
uint32_t FMPI2C_InitTypeDef::NoStretchMode
Specifies if nostretch mode is selected. This parameter can be a value of
FMPI2C_NOSTRETCH_MODE

25.1.2

__FMPI2C_HandleTypeDef
Data Fields

362/964

DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver
FMPI2C_TypeDef * Instance
FMPI2C_InitTypeDef Init
uint8_t * pBuffPtr
uint16_t XferSize
__IO uint16_t XferCount
__IO uint32_t XferOptions
__IO uint32_t PreviousState
HAL_StatusTypeDef(* XferISR
DMA_HandleTypeDef * hdmatx
DMA_HandleTypeDef * hdmarx
HAL_LockTypeDef Lock
__IO HAL_FMPI2C_StateTypeDef State
__IO HAL_FMPI2C_ModeTypeDef Mode
__IO uint32_t ErrorCode
__IO uint32_t AddrEventCount

Field Documentation
FMPI2C_TypeDef* __FMPI2C_HandleTypeDef::Instance
FMPI2C registers base address
FMPI2C_InitTypeDef __FMPI2C_HandleTypeDef::Init
FMPI2C communication parameters
uint8_t* __FMPI2C_HandleTypeDef::pBuffPtr
Pointer to FMPI2C transfer buffer
uint16_t __FMPI2C_HandleTypeDef::XferSize
FMPI2C transfer size
__IO uint16_t __FMPI2C_HandleTypeDef::XferCount
FMPI2C transfer counter
__IO uint32_t __FMPI2C_HandleTypeDef::XferOptions
FMPI2C sequantial transfer options, this parameter can be a value of
FMPI2C_XFEROPTIONS
__IO uint32_t __FMPI2C_HandleTypeDef::PreviousState
FMPI2C communication Previous state
HAL_StatusTypeDef(* __FMPI2C_HandleTypeDef::XferISR)(struct
__FMPI2C_HandleTypeDef *hfmpi2c, uint32_t ITFlags, uint32_t ITSources)
FMPI2C transfer IRQ handler function pointer
DMA_HandleTypeDef* __FMPI2C_HandleTypeDef::hdmatx
FMPI2C Tx DMA handle parameters
DMA_HandleTypeDef* __FMPI2C_HandleTypeDef::hdmarx
FMPI2C Rx DMA handle parameters
HAL_LockTypeDef __FMPI2C_HandleTypeDef::Lock
FMPI2C locking object
__IO HAL_FMPI2C_StateTypeDef __FMPI2C_HandleTypeDef::State
FMPI2C communication state
__IO HAL_FMPI2C_ModeTypeDef __FMPI2C_HandleTypeDef::Mode
FMPI2C communication mode
__IO uint32_t __FMPI2C_HandleTypeDef::ErrorCode
FMPI2C Error code
__IO uint32_t __FMPI2C_HandleTypeDef::AddrEventCount
FMPI2C Address Event counter

DocID025834 Rev 4

363/964

HAL FMPI2C Generic Driver

UM1725

25.2

FMPI2C Firmware driver API description

25.2.1

How to use this driver
The FMPI2C HAL driver can be used as follows:
1.
2.

3.

4.

5.
6.

Declare a FMPI2C_HandleTypeDef handle structure, for example:
FMPI2C_HandleTypeDef hfmpi2c;
Initialize the FMPI2C low level resources by implementing the HAL_FMPI2C_MspInit()
API:
a.
Enable the FMPI2Cx interface clock
b.
FMPI2C pins configuration
Enable the clock for the FMPI2C GPIOs
Configure FMPI2C pins as alternate function open-drain
c.
NVIC configuration if you need to use interrupt process
Configure the FMPI2Cx interrupt priority
Enable the NVIC FMPI2C IRQ Channel
d.
DMA Configuration if you need to use DMA process
Declare a DMA_HandleTypeDef handle structure for the transmit or receive
channel
Enable the DMAx interface clock using
Configure the DMA handle parameters
Configure the DMA Tx or Rx channel
Associate the initialized DMA handle to the hfmpi2c DMA Tx or Rx handle
Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Tx or Rx channel
Configure the Communication Clock Timing, Own Address1, Master Addressing
mode, Dual Addressing mode, Own Address2, Own Address2 Mask, General call and
Nostretch mode in the hfmpi2c Init structure.
Initialize the FMPI2C registers by calling the HAL_FMPI2C_Init(), configures also the
low level Hardware (GPIO, CLOCK, NVIC...etc) by calling the customized
HAL_FMPI2C_MspInit(&hfmpi2c) API.
To check if target device is ready for communication, use the function
HAL_FMPI2C_IsDeviceReady()
For FMPI2C IO and IO MEM operations, three operation modes are available within
this driver :

Polling mode IO operation
Transmit in master mode an amount of data in blocking mode using
HAL_FMPI2C_Master_Transmit()
Receive in master mode an amount of data in blocking mode using
HAL_FMPI2C_Master_Receive()
Transmit in slave mode an amount of data in blocking mode using
HAL_FMPI2C_Slave_Transmit()
Receive in slave mode an amount of data in blocking mode using
HAL_FMPI2C_Slave_Receive()

Polling mode IO MEM operation
Write an amount of data in blocking mode to a specific memory address using
HAL_FMPI2C_Mem_Write()

364/964

DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver
Read an amount of data in blocking mode from a specific memory address using
HAL_FMPI2C_Mem_Read()

Interrupt mode IO operation
Transmit in master mode an amount of data in non-blocking mode using
HAL_FMPI2C_Master_Transmit_IT()
At transmission end of transfer, HAL_FMPI2C_MasterTxCpltCallback() is executed
and user can add his own code by customization of function pointer
HAL_FMPI2C_MasterTxCpltCallback()
Receive in master mode an amount of data in non-blocking mode using
HAL_FMPI2C_Master_Receive_IT()
At reception end of transfer, HAL_FMPI2C_MasterRxCpltCallback() is executed and
user can add his own code by customization of function pointer
HAL_FMPI2C_MasterRxCpltCallback()
Transmit in slave mode an amount of data in non-blocking mode using
HAL_FMPI2C_Slave_Transmit_IT()
At transmission end of transfer, HAL_FMPI2C_SlaveTxCpltCallback() is executed
and user can add his own code by customization of function pointer
HAL_FMPI2C_SlaveTxCpltCallback()
Receive in slave mode an amount of data in non-blocking mode using
HAL_FMPI2C_Slave_Receive_IT()
At reception end of transfer, HAL_FMPI2C_SlaveRxCpltCallback() is executed and
user can add his own code by customization of function pointer
HAL_FMPI2C_SlaveRxCpltCallback()
In case of transfer Error, HAL_FMPI2C_ErrorCallback() function is executed and user
can add his own code by customization of function pointer
HAL_FMPI2C_ErrorCallback()
Abort a master FMPI2C process communication with Interrupt using
HAL_FMPI2C_Master_Abort_IT()
End of abort process, HAL_FMPI2C_MasterRxCpltCallback() or
HAL_FMPI2C_MasterTxCpltCallback() is executed and user can add his own code by
customization of function pointer HAL_FMPI2C_MasterRxCpltCallback() or
HAL_FMPI2C_MasterTxCpltCallback()
Discard a slave FMPI2C process communication using
__HAL_FMPI2C_GENERATE_NACK() macro. This action will inform Master to
generate a Stop condition to discard the communication.

Interrupt mode IO sequential operation
These interfaces allow to manage a sequential transfer with a repeated start
condition when a direction change during transfer

A specific option field manage the different steps of a sequential transfer
Option field values are defined through FMPI2C_XFEROPTIONS and are listed
below:
FMPI2C_FIRST_AND_LAST_FRAME: No sequential usage, functionnal is same
as associated interfaces in no sequential mode
FMPI2C_FIRST_FRAME: Sequential usage, this option allow to manage a
sequence with start condition, address and data to transfer without a final stop
condition
DocID025834 Rev 4

365/964

HAL FMPI2C Generic Driver

UM1725

FMPI2C_NEXT_FRAME: Sequential usage, this option allow to manage a
sequence with a restart condition, address and with new data to transfer if the
direction change or manage only the new data to transfer if no direction change
and without a final stop condition in both cases
FMPI2C_LAST_FRAME: Sequential usage, this option allow to manage a
sequance with a restart condition, address and with new data to transfer if the
direction change or manage only the new data to transfer if no direction change
and with a final stop condition in both cases
Differents sequential FMPI2C interfaces are listed below:
Sequential transmit in master FMPI2C mode an amount of data in non-blocking
mode using HAL_FMPI2C_Master_Sequential_Transmit_IT()
At transmission end of current frame transfer,
HAL_FMPI2C_MasterTxCpltCallback() is executed and user can add his
own code by customization of function pointer
HAL_FMPI2C_MasterTxCpltCallback()
Sequential receive in master FMPI2C mode an amount of data in non-blocking
mode using HAL_FMPI2C_Master_Sequential_Receive_IT()
At reception end of current frame transfer,
HAL_FMPI2C_MasterRxCpltCallback() is executed and user can add his
own code by customization of function pointer
HAL_FMPI2C_MasterRxCpltCallback()
Abort a master FMPI2C process communication with Interrupt using
HAL_FMPI2C_Master_Abort_IT()
End of abort process, HAL_FMPI2C_AbortCpltCallback() is executed and
user can add his own code by customization of function pointer
HAL_FMPI2C_AbortCpltCallback()
mean HAL_FMPI2C_MasterTxCpltCallback() in case of previous state was
master transmit
mean HAL_FMPI2C_MasterRxCpltCallback() in case of previous state was
master receive
Enable/disable the Address listen mode in slave FMPI2C mode using
HAL_FMPI2C_EnableListen_IT() HAL_FMPI2C_DisableListen_IT()
When address slave FMPI2C match, HAL_FMPI2C_AddrCallback() is
executed and user can add his own code to check the Address Match Code
and the transmission direction request by master (Write/Read).
At Listen mode end HAL_FMPI2C_ListenCpltCallback() is executed and
user can add his own code by customization of function pointer
HAL_FMPI2C_ListenCpltCallback()
Sequential transmit in slave FMPI2C mode an amount of data in non-blocking
mode using HAL_FMPI2C_Slave_Sequential_Transmit_IT()
At transmission end of current frame transfer,
HAL_FMPI2C_SlaveTxCpltCallback() is executed and user can add his own
code by customization of function pointer
HAL_FMPI2C_SlaveTxCpltCallback()
Sequential receive in slave FMPI2C mode an amount of data in non-blocking
mode using HAL_FMPI2C_Slave_Sequential_Receive_IT()
At reception end of current frame transfer,
HAL_FMPI2C_SlaveRxCpltCallback() is executed and user can add his own
code by customization of function pointer
HAL_FMPI2C_SlaveRxCpltCallback()
In case of transfer Error, HAL_FMPI2C_ErrorCallback() function is executed and
user can add his own code by customization of function pointer
HAL_FMPI2C_ErrorCallback()

366/964

DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver
Abort a master FMPI2C process communication with Interrupt using
HAL_FMPI2C_Master_Abort_IT()
End of abort process, HAL_FMPI2C_AbortCpltCallback() is executed and user
can add his own code by customization of function pointer
HAL_FMPI2C_AbortCpltCallback()
Discard a slave FMPI2C process communication using
__HAL_FMPI2C_GENERATE_NACK() macro. This action will inform Master to
generate a Stop condition to discard the communication.

Interrupt mode IO MEM operation
Write an amount of data in non-blocking mode with Interrupt to a specific memory
address using HAL_FMPI2C_Mem_Write_IT()
At Memory end of write transfer, HAL_FMPI2C_MemTxCpltCallback() is executed
and user can add his own code by customization of function pointer
HAL_FMPI2C_MemTxCpltCallback()
Read an amount of data in non-blocking mode with Interrupt from a specific memory
address using HAL_FMPI2C_Mem_Read_IT()
At Memory end of read transfer, HAL_FMPI2C_MemRxCpltCallback() is executed
and user can add his own code by customization of function pointer
HAL_FMPI2C_MemRxCpltCallback()
In case of transfer Error, HAL_FMPI2C_ErrorCallback() function is executed and user
can add his own code by customization of function pointer
HAL_FMPI2C_ErrorCallback()

DMA mode IO operation
Transmit in master mode an amount of data in non-blocking mode (DMA) using
HAL_FMPI2C_Master_Transmit_DMA()
At transmission end of transfer, HAL_FMPI2C_MasterTxCpltCallback() is executed
and user can add his own code by customization of function pointer
HAL_FMPI2C_MasterTxCpltCallback()
Receive in master mode an amount of data in non-blocking mode (DMA) using
HAL_FMPI2C_Master_Receive_DMA()
At reception end of transfer, HAL_FMPI2C_MasterRxCpltCallback() is executed and
user can add his own code by customization of function pointer
HAL_FMPI2C_MasterRxCpltCallback()
Transmit in slave mode an amount of data in non-blocking mode (DMA) using
HAL_FMPI2C_Slave_Transmit_DMA()
At transmission end of transfer, HAL_FMPI2C_SlaveTxCpltCallback() is executed
and user can add his own code by customization of function pointer
HAL_FMPI2C_SlaveTxCpltCallback()
Receive in slave mode an amount of data in non-blocking mode (DMA) using
HAL_FMPI2C_Slave_Receive_DMA()
At reception end of transfer, HAL_FMPI2C_SlaveRxCpltCallback() is executed and
user can add his own code by customization of function pointer
HAL_FMPI2C_SlaveRxCpltCallback()
In case of transfer Error, HAL_FMPI2C_ErrorCallback() function is executed and user
can add his own code by customization of function pointer
HAL_FMPI2C_ErrorCallback()
Abort a master FMPI2C process communication with Interrupt using
HAL_FMPI2C_Master_Abort_IT()
DocID025834 Rev 4

367/964

HAL FMPI2C Generic Driver

UM1725

End of abort process, HAL_FMPI2C_MasterRxCpltCallback() or
HAL_FMPI2C_MasterTxCpltCallback() is executed and user can add his own code by
customization of function pointer HAL_FMPI2C_MasterRxCpltCallback() or
HAL_FMPI2C_MasterTxCpltCallback()
Discard a slave FMPI2C process communication using
__HAL_FMPI2C_GENERATE_NACK() macro. This action will inform Master to
generate a Stop condition to discard the communication.

DMA mode IO MEM operation
Write an amount of data in non-blocking mode with DMA to a specific memory
address using HAL_FMPI2C_Mem_Write_DMA()
At Memory end of write transfer, HAL_FMPI2C_MemTxCpltCallback() is executed
and user can add his own code by customization of function pointer
HAL_FMPI2C_MemTxCpltCallback()
Read an amount of data in non-blocking mode with DMA from a specific memory
address using HAL_FMPI2C_Mem_Read_DMA()
At Memory end of read transfer, HAL_FMPI2C_MemRxCpltCallback() is executed
and user can add his own code by customization of function pointer
HAL_FMPI2C_MemRxCpltCallback()
In case of transfer Error, HAL_FMPI2C_ErrorCallback() function is executed and user
can add his own code by customization of function pointer
HAL_FMPI2C_ErrorCallback()

FMPI2C HAL driver macros list
Below the list of most used macros in FMPI2C HAL driver.
__HAL_FMPI2C_ENABLE: Enable the FMPI2C peripheral
__HAL_FMPI2C_DISABLE: Disable the FMPI2C peripheral
__HAL_FMPI2C_GENERATE_NACK: Generate a Non-Acknowledge FMPI2C
peripheral in Slave mode
__HAL_FMPI2C_GET_FLAG: Check whether the specified FMPI2C flag is set or not
__HAL_FMPI2C_CLEAR_FLAG: Clear the specified FMPI2C pending flag
__HAL_FMPI2C_ENABLE_IT: Enable the specified FMPI2C interrupt
__HAL_FMPI2C_DISABLE_IT: Disable the specified FMPI2C interrupt
You can refer to the FMPI2C HAL driver header file for more useful macros

25.2.2

Initialization and de-initialization functions
This subsection provides a set of functions allowing to initialize and deinitialize the
FMPI2Cx peripheral:
User must Implement HAL_FMPI2C_MspInit() function in which he configures all
related peripherals resources (CLOCK, GPIO, DMA, IT and NVIC ).
Call the function HAL_FMPI2C_Init() to configure the selected device with the
selected configuration:
Clock Timing
Own Address 1
Addressing mode (Master, Slave)

368/964

DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver
Dual Addressing mode
Own Address 2
Own Address 2 Mask
General call mode
Nostretch mode
Call the function HAL_FMPI2C_DeInit() to restore the default configuration of the
selected FMPI2Cx peripheral.
This section contains the following APIs:
HAL_FMPI2C_Init()
HAL_FMPI2C_DeInit()
HAL_FMPI2C_MspInit()
HAL_FMPI2C_MspDeInit()

25.2.3

IO operation functions
This subsection provides a set of functions allowing to manage the FMPI2C data transfers.
1.

2.

3.

4.

5.

There are two modes of transfer:
Blocking mode : The communication is performed in the polling mode. The
status of all data processing is returned by the same function after finishing
transfer.
No-Blocking mode : The communication is performed using Interrupts or DMA.
These functions return the status of the transfer startup. The end of the data
processing will be indicated through the dedicated FMPI2C IRQ when using
Interrupt mode or the DMA IRQ when using DMA mode.
Blocking mode functions are :
HAL_FMPI2C_Master_Transmit()
HAL_FMPI2C_Master_Receive()
HAL_FMPI2C_Slave_Transmit()
HAL_FMPI2C_Slave_Receive()
HAL_FMPI2C_Mem_Write()
HAL_FMPI2C_Mem_Read()
HAL_FMPI2C_IsDeviceReady()
No-Blocking mode functions with Interrupt are :
HAL_FMPI2C_Master_Transmit_IT()
HAL_FMPI2C_Master_Receive_IT()
HAL_FMPI2C_Slave_Transmit_IT()
HAL_FMPI2C_Slave_Receive_IT()
HAL_FMPI2C_Master_Sequential_Transmit_IT()
HAL_FMPI2C_Master_Sequential_Receive_IT()
HAL_FMPI2C_Slave_Sequential_Transmit_IT()
HAL_FMPI2C_Slave_Sequential_Receive_IT()
HAL_FMPI2C_Mem_Write_IT()
HAL_FMPI2C_Mem_Read_IT()
No-Blocking mode functions with DMA are :
HAL_FMPI2C_Master_Transmit_DMA()
HAL_FMPI2C_Master_Receive_DMA()
HAL_FMPI2C_Slave_Transmit_DMA()
HAL_FMPI2C_Slave_Receive_DMA()
HAL_FMPI2C_Mem_Write_DMA()
HAL_FMPI2C_Mem_Read_DMA()
A set of Transfer Complete Callbacks are provided in non Blocking mode:
HAL_FMPI2C_MemTxCpltCallback()
DocID025834 Rev 4

369/964

HAL FMPI2C Generic Driver

UM1725

HAL_FMPI2C_MemRxCpltCallback()
HAL_FMPI2C_MasterTxCpltCallback()
HAL_FMPI2C_MasterRxCpltCallback()
HAL_FMPI2C_SlaveTxCpltCallback()
HAL_FMPI2C_SlaveRxCpltCallback()
HAL_FMPI2C_ErrorCallback()
HAL_FMPI2C_AbortCpltCallback()
This section contains the following APIs:
HAL_FMPI2C_Master_Transmit()
HAL_FMPI2C_Master_Receive()
HAL_FMPI2C_Slave_Transmit()
HAL_FMPI2C_Slave_Receive()
HAL_FMPI2C_Master_Transmit_IT()
HAL_FMPI2C_Master_Receive_IT()
HAL_FMPI2C_Slave_Transmit_IT()
HAL_FMPI2C_Slave_Receive_IT()
HAL_FMPI2C_Master_Transmit_DMA()
HAL_FMPI2C_Master_Receive_DMA()
HAL_FMPI2C_Slave_Transmit_DMA()
HAL_FMPI2C_Slave_Receive_DMA()
HAL_FMPI2C_Mem_Write()
HAL_FMPI2C_Mem_Read()
HAL_FMPI2C_Mem_Write_IT()
HAL_FMPI2C_Mem_Read_IT()
HAL_FMPI2C_Mem_Write_DMA()
HAL_FMPI2C_Mem_Read_DMA()
HAL_FMPI2C_IsDeviceReady()
HAL_FMPI2C_Master_Sequential_Transmit_IT()
HAL_FMPI2C_Master_Sequential_Receive_IT()
HAL_FMPI2C_Slave_Sequential_Transmit_IT()
HAL_FMPI2C_Slave_Sequential_Receive_IT()
HAL_FMPI2C_EnableListen_IT()
HAL_FMPI2C_DisableListen_IT()
HAL_FMPI2C_Master_Abort_IT()

25.2.4

Peripheral State, Mode and Error functions
This subsection permit to get in run-time the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_FMPI2C_GetState()
HAL_FMPI2C_GetMode()
HAL_FMPI2C_GetError()

25.2.5

Detailed description of functions
HAL_FMPI2C_Init

370/964

Function Name

HAL_StatusTypeDef HAL_FMPI2C_Init
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Initializes the FMPI2C according to the specified parameters in the
FMPI2C_InitTypeDef and initialize the associated handle.
DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver
Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

HAL: status

HAL_FMPI2C_DeInit
Function Name

HAL_StatusTypeDef HAL_FMPI2C_DeInit
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

DeInitialize the FMPI2C peripheral.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

HAL: status

HAL_FMPI2C_MspInit
Function Name

void HAL_FMPI2C_MspInit (FMPI2C_HandleTypeDef *
hfmpi2c)

Function Description

Initialize the FMPI2C MSP.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

HAL_FMPI2C_MspDeInit
Function Name

void HAL_FMPI2C_MspDeInit (FMPI2C_HandleTypeDef *
hfmpi2c)

Function Description

DeInitialize the FMPI2C MSP.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

HAL_FMPI2C_Master_Transmit
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Master_Transmit
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint8_t * pData, uint16_t Size, uint32_t Timeout)

Function Description

Transmits in master mode an amount of data in blocking mode.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
DocID025834 Rev 4

371/964

HAL FMPI2C Generic Driver

UM1725
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_FMPI2C_Master_Receive
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Master_Receive
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint8_t * pData, uint16_t Size, uint32_t Timeout)

Function Description

Receives in master mode an amount of data in blocking mode.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_FMPI2C_Slave_Transmit
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Slave_Transmit
(FMPI2C_HandleTypeDef * hfmpi2c, uint8_t * pData, uint16_t
Size, uint32_t Timeout)

Function Description

Transmits in slave mode an amount of data in blocking mode.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_FMPI2C_Slave_Receive

372/964

Function Name

HAL_StatusTypeDef HAL_FMPI2C_Slave_Receive
(FMPI2C_HandleTypeDef * hfmpi2c, uint8_t * pData, uint16_t
Size, uint32_t Timeout)

Function Description

Receive in slave mode an amount of data in blocking mode.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status
DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver

HAL_FMPI2C_Mem_Write
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Mem_Write
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint16_t MemAddress, uint16_t MemAddSize, uint8_t * pData,
uint16_t Size, uint32_t Timeout)

Function Description

Write an amount of data in blocking mode to a specific memory
address.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_FMPI2C_Mem_Read
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Mem_Read
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint16_t MemAddress, uint16_t MemAddSize, uint8_t * pData,
uint16_t Size, uint32_t Timeout)

Function Description

Read an amount of data in blocking mode from a specific memory
address.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_FMPI2C_IsDeviceReady
Function Name

HAL_StatusTypeDef HAL_FMPI2C_IsDeviceReady
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint32_t Trials, uint32_t Timeout)

Function Description

Checks if target device is ready for communication.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address
Trials: Number of trials
Timeout: Timeout duration
DocID025834 Rev 4

373/964

HAL FMPI2C Generic Driver
Return values
Notes

UM1725
HAL: status
This function is used with Memory devices

HAL_FMPI2C_Master_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Master_Transmit_IT
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint8_t * pData, uint16_t Size)

Function Description

Transmit in master mode an amount of data in non-blocking mode
with Interrupt.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_FMPI2C_Master_Receive_IT
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Master_Receive_IT
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint8_t * pData, uint16_t Size)

Function Description

Receive in master mode an amount of data in non-blocking mode
with Interrupt.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_FMPI2C_Slave_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Slave_Transmit_IT
(FMPI2C_HandleTypeDef * hfmpi2c, uint8_t * pData, uint16_t
Size)

Function Description

Transmit in slave mode an amount of data in non-blocking mode
with Interrupt.

Parameters

374/964

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
pData: Pointer to data buffer
Size: Amount of data to be sent
DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver
Return values

HAL: status

HAL_FMPI2C_Slave_Receive_IT
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Slave_Receive_IT
(FMPI2C_HandleTypeDef * hfmpi2c, uint8_t * pData, uint16_t
Size)

Function Description

Receive in slave mode an amount of data in non-blocking mode
with Interrupt.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_FMPI2C_Mem_Write_IT
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Mem_Write_IT
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint16_t MemAddress, uint16_t MemAddSize, uint8_t * pData,
uint16_t Size)

Function Description

Write an amount of data in non-blocking mode with Interrupt to a
specific memory address.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_FMPI2C_Mem_Read_IT
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Mem_Read_IT
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint16_t MemAddress, uint16_t MemAddSize, uint8_t * pData,
uint16_t Size)

Function Description

Read an amount of data in non-blocking mode with Interrupt from
a specific memory address.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer

DocID025834 Rev 4

375/964

HAL FMPI2C Generic Driver

UM1725
Size: Amount of data to be sent

Return values

HAL: status

HAL_FMPI2C_Master_Sequential_Transmit_IT
Function Name

HAL_StatusTypeDef
HAL_FMPI2C_Master_Sequential_Transmit_IT
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint8_t * pData, uint16_t Size, uint32_t XferOptions)

Function Description

Sequential transmit in master FMPI2C mode an amount of data in
non-blocking mode with Interrupt.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent
XferOptions: Options of Transfer, value of FMPI2C
Sequential Transfer Options

Return values

HAL: status

Notes

This interface allow to manage repeated start condition when
a direction change during transfer

HAL_FMPI2C_Master_Sequential_Receive_IT

376/964

Function Name

HAL_StatusTypeDef
HAL_FMPI2C_Master_Sequential_Receive_IT
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint8_t * pData, uint16_t Size, uint32_t XferOptions)

Function Description

Sequential receive in master FMPI2C mode an amount of data in
non-blocking mode with Interrupt.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent
XferOptions: Options of Transfer, value of FMPI2C
Sequential Transfer Options

Return values

HAL: status

Notes

This interface allow to manage repeated start condition when
a direction change during transfer

DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver

HAL_FMPI2C_Slave_Sequential_Transmit_IT
Function Name

HAL_StatusTypeDef
HAL_FMPI2C_Slave_Sequential_Transmit_IT
(FMPI2C_HandleTypeDef * hfmpi2c, uint8_t * pData, uint16_t
Size, uint32_t XferOptions)

Function Description

Sequential transmit in slave/device FMPI2C mode an amount of
data in non-blocking mode with Interrupt.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
pData: Pointer to data buffer
Size: Amount of data to be sent
XferOptions: Options of Transfer, value of FMPI2C
Sequential Transfer Options

Return values

HAL: status

Notes

This interface allow to manage repeated start condition when
a direction change during transfer

HAL_FMPI2C_Slave_Sequential_Receive_IT
Function Name

HAL_StatusTypeDef
HAL_FMPI2C_Slave_Sequential_Receive_IT
(FMPI2C_HandleTypeDef * hfmpi2c, uint8_t * pData, uint16_t
Size, uint32_t XferOptions)

Function Description

Sequential receive in slave/device FMPI2C mode an amount of
data in non-blocking mode with Interrupt.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
pData: Pointer to data buffer
Size: Amount of data to be sent
XferOptions: Options of Transfer, value of FMPI2C
Sequential Transfer Options

Return values

HAL: status

Notes

This interface allow to manage repeated start condition when
a direction change during transfer

HAL_FMPI2C_EnableListen_IT
Function Name

HAL_StatusTypeDef HAL_FMPI2C_EnableListen_IT
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Enable the Address listen mode with Interrupt.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

HAL: status

DocID025834 Rev 4

377/964

HAL FMPI2C Generic Driver

UM1725

HAL_FMPI2C_DisableListen_IT
Function Name

HAL_StatusTypeDef HAL_FMPI2C_DisableListen_IT
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Disable the Address listen mode with Interrupt.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C

Return values

HAL: status

HAL_FMPI2C_Master_Abort_IT
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Master_Abort_IT
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress)

Function Description

Abort a master FMPI2C IT or DMA process communication with
Interrupt.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface

Return values

HAL: status

HAL_FMPI2C_Master_Transmit_DMA
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Master_Transmit_DMA
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint8_t * pData, uint16_t Size)

Function Description

Transmit in master mode an amount of data in non-blocking mode
with DMA.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_FMPI2C_Master_Receive_DMA

378/964

Function Name

HAL_StatusTypeDef HAL_FMPI2C_Master_Receive_DMA
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint8_t * pData, uint16_t Size)

Function Description

Receive in master mode an amount of data in non-blocking mode
with DMA.

DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver
Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_FMPI2C_Slave_Transmit_DMA
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Slave_Transmit_DMA
(FMPI2C_HandleTypeDef * hfmpi2c, uint8_t * pData, uint16_t
Size)

Function Description

Transmit in slave mode an amount of data in non-blocking mode
with DMA.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_FMPI2C_Slave_Receive_DMA
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Slave_Receive_DMA
(FMPI2C_HandleTypeDef * hfmpi2c, uint8_t * pData, uint16_t
Size)

Function Description

Receive in slave mode an amount of data in non-blocking mode
with DMA.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_FMPI2C_Mem_Write_DMA
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Mem_Write_DMA
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint16_t MemAddress, uint16_t MemAddSize, uint8_t * pData,
uint16_t Size)

Function Description

Write an amount of data in non-blocking mode with DMA to a
specific memory address.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DocID025834 Rev 4

379/964

HAL FMPI2C Generic Driver

UM1725
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_FMPI2C_Mem_Read_DMA
Function Name

HAL_StatusTypeDef HAL_FMPI2C_Mem_Read_DMA
(FMPI2C_HandleTypeDef * hfmpi2c, uint16_t DevAddress,
uint16_t MemAddress, uint16_t MemAddSize, uint8_t * pData,
uint16_t Size)

Function Description

Reads an amount of data in non-blocking mode with DMA from a
specific memory address.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer
Size: Amount of data to be read

Return values

HAL: status

HAL_FMPI2C_EV_IRQHandler
Function Name

void HAL_FMPI2C_EV_IRQHandler (FMPI2C_HandleTypeDef *
hfmpi2c)

Function Description

This function handles FMPI2C event interrupt request.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

HAL_FMPI2C_ER_IRQHandler

380/964

Function Name

void HAL_FMPI2C_ER_IRQHandler (FMPI2C_HandleTypeDef *
hfmpi2c)

Function Description

This function handles FMPI2C error interrupt request.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver

HAL_FMPI2C_MasterTxCpltCallback
Function Name

void HAL_FMPI2C_MasterTxCpltCallback
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Master Tx Transfer completed callback.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

HAL_FMPI2C_MasterRxCpltCallback
Function Name

void HAL_FMPI2C_MasterRxCpltCallback
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Master Rx Transfer completed callback.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

HAL_FMPI2C_SlaveTxCpltCallback
Function Name

void HAL_FMPI2C_SlaveTxCpltCallback
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Slave Tx Transfer completed callback.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

HAL_FMPI2C_SlaveRxCpltCallback
Function Name

void HAL_FMPI2C_SlaveRxCpltCallback
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Slave Rx Transfer completed callback.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

HAL_FMPI2C_AddrCallback
Function Name

void HAL_FMPI2C_AddrCallback (FMPI2C_HandleTypeDef *
hfmpi2c, uint8_t TransferDirection, uint16_t AddrMatchCode)

Function Description

Slave Address Match callback.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
DocID025834 Rev 4

381/964

HAL FMPI2C Generic Driver

Return values

UM1725
FMPI2C.
TransferDirection: Master request Transfer Direction
(Write/Read), value of FMPI2C Sequential Transfer Options
AddrMatchCode: Address Match Code
None

HAL_FMPI2C_ListenCpltCallback
Function Name

void HAL_FMPI2C_ListenCpltCallback
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Listen Complete callback.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

HAL_FMPI2C_MemTxCpltCallback
Function Name

void HAL_FMPI2C_MemTxCpltCallback
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Memory Tx Transfer completed callback.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

HAL_FMPI2C_MemRxCpltCallback
Function Name

void HAL_FMPI2C_MemRxCpltCallback
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Memory Rx Transfer completed callback.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

HAL_FMPI2C_ErrorCallback

382/964

Function Name

void HAL_FMPI2C_ErrorCallback (FMPI2C_HandleTypeDef *
hfmpi2c)

Function Description

FMPI2C error callback.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver

HAL_FMPI2C_AbortCpltCallback
Function Name

void HAL_FMPI2C_AbortCpltCallback
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

FMPI2C abort callback.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

None

HAL_FMPI2C_GetState
Function Name

HAL_FMPI2C_StateTypeDef HAL_FMPI2C_GetState
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Return the FMPI2C handle state.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

HAL: state

HAL_FMPI2C_GetMode
Function Name

HAL_FMPI2C_ModeTypeDef HAL_FMPI2C_GetMode
(FMPI2C_HandleTypeDef * hfmpi2c)

Function Description

Returns the FMPI2C Master, Slave, Memory or no mode.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for FMPI2C module

Return values

HAL: mode

HAL_FMPI2C_GetError
Function Name

uint32_t HAL_FMPI2C_GetError (FMPI2C_HandleTypeDef *
hfmpi2c)

Function Description

Return the FMPI2C error code.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2C.

Return values

FMPI2C: Error Code

25.3

FMPI2C Firmware driver defines

25.3.1

FMPI2C
FMPI2C Addressing Mode
FMPI2C_ADDRESSINGMODE_7BIT
FMPI2C_ADDRESSINGMODE_10BIT

DocID025834 Rev 4

383/964

HAL FMPI2C Generic Driver
FMPI2C Dual Addressing Mode

UM1725

FMPI2C_DUALADDRESS_DISABLE
FMPI2C_DUALADDRESS_ENABLE
FMPI2C Error Code definition
HAL_FMPI2C_ERROR_NONE

No error

HAL_FMPI2C_ERROR_BERR

BERR error

HAL_FMPI2C_ERROR_ARLO

ARLO error

HAL_FMPI2C_ERROR_AF

ACKF error

HAL_FMPI2C_ERROR_OVR

OVR error

HAL_FMPI2C_ERROR_DMA

DMA transfer error

HAL_FMPI2C_ERROR_TIMEOUT

Timeout error

HAL_FMPI2C_ERROR_SIZE

Size Management error

FMPI2C Exported Macros
__HAL_FMPI2C_RESET_HANDLE_STATE

Description:
Reset FMPI2C handle state.
Parameters:
__HANDLE__: specifies the FMPI2C
Handle.
Return value:
None

__HAL_FMPI2C_ENABLE_IT

Description:
Enable the specified FMPI2C interrupt.
Parameters:
__HANDLE__: specifies the FMPI2C
Handle.
__INTERRUPT__: specifies the
interrupt source to enable. This
parameter can be one of the following
values:
FMPI2C_IT_ERRI Errors interrupt
enable
FMPI2C_IT_TCI Transfer
complete interrupt enable
FMPI2C_IT_STOPI STOP
detection interrupt enable
FMPI2C_IT_NACKI NACK
received interrupt enable
FMPI2C_IT_ADDRI Address
match interrupt enable
FMPI2C_IT_RXI RX interrupt
enable
FMPI2C_IT_TXI TX interrupt
enable

384/964

DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver
Return value:
None
__HAL_FMPI2C_DISABLE_IT

Description:
Disable the specified FMPI2C interrupt.
Parameters:
__HANDLE__: specifies the FMPI2C
Handle.
__INTERRUPT__: specifies the
interrupt source to disable. This
parameter can be one of the following
values:
FMPI2C_IT_ERRI Errors interrupt
enable
FMPI2C_IT_TCI Transfer
complete interrupt enable
FMPI2C_IT_STOPI STOP
detection interrupt enable
FMPI2C_IT_NACKI NACK
received interrupt enable
FMPI2C_IT_ADDRI Address
match interrupt enable
FMPI2C_IT_RXI RX interrupt
enable
FMPI2C_IT_TXI TX interrupt
enable
Return value:
None

__HAL_FMPI2C_GET_IT_SOURCE

Description:
Check whether the specified FMPI2C
interrupt source is enabled or not.
Parameters:
__HANDLE__: specifies the FMPI2C
Handle.
__INTERRUPT__: specifies the
FMPI2C interrupt source to check. This
parameter can be one of the following
values:
FMPI2C_IT_ERRI Errors interrupt
enable
FMPI2C_IT_TCI Transfer
complete interrupt enable
FMPI2C_IT_STOPI STOP
detection interrupt enable
FMPI2C_IT_NACKI NACK
received interrupt enable
FMPI2C_IT_ADDRI Address
match interrupt enable
FMPI2C_IT_RXI RX interrupt

DocID025834 Rev 4

385/964

HAL FMPI2C Generic Driver

UM1725
enable
FMPI2C_IT_TXI TX interrupt
enable
Return value:
The: new state of __INTERRUPT__
(SET or RESET).

__HAL_FMPI2C_GET_FLAG

Description:
Check whether the specified FMPI2C
flag is set or not.
Parameters:
__HANDLE__: specifies the FMPI2C
Handle.
__FLAG__: specifies the flag to check.
This parameter can be one of the
following values:
FMPI2C_FLAG_TXE Transmit
data register empty
FMPI2C_FLAG_TXIS Transmit
interrupt status
FMPI2C_FLAG_RXNE Receive
data register not empty
FMPI2C_FLAG_ADDR Address
matched (slave mode)
FMPI2C_FLAG_AF Acknowledge
failure received flag
FMPI2C_FLAG_STOPF STOP
detection flag
FMPI2C_FLAG_TC Transfer
complete (master mode)
FMPI2C_FLAG_TCR Transfer
complete reload
FMPI2C_FLAG_BERR Bus error
FMPI2C_FLAG_ARLO Arbitration
lost
FMPI2C_FLAG_OVR
Overrun/Underrun
FMPI2C_FLAG_PECERR PEC
error in reception
FMPI2C_FLAG_TIMEOUT
Timeout or Tlow detection flag
FMPI2C_FLAG_ALERT SMBus
alert
FMPI2C_FLAG_BUSY Bus busy
FMPI2C_FLAG_DIR Transfer
direction (slave mode)
Return value:
The: new state of __FLAG__ (SET or
RESET).

__HAL_FMPI2C_CLEAR_FLAG
386/964

Description:

DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver
Clear the FMPI2C pending flags which
are cleared by writing 1 in a specific bit.
Parameters:
__HANDLE__: specifies the FMPI2C
Handle.
__FLAG__: specifies the flag to clear.
This parameter can be any combination
of the following values:
FMPI2C_FLAG_TXE Transmit
data register empty
FMPI2C_FLAG_ADDR Address
matched (slave mode)
FMPI2C_FLAG_AF Acknowledge
failure received flag
FMPI2C_FLAG_STOPF STOP
detection flag
FMPI2C_FLAG_BERR Bus error
FMPI2C_FLAG_ARLO Arbitration
lost
FMPI2C_FLAG_OVR
Overrun/Underrun
FMPI2C_FLAG_PECERR PEC
error in reception
FMPI2C_FLAG_TIMEOUT
Timeout or Tlow detection flag
FMPI2C_FLAG_ALERT SMBus
alert
Return value:
None
__HAL_FMPI2C_ENABLE

Description:
Enable the specified FMPI2C
peripheral.
Parameters:
__HANDLE__: specifies the FMPI2C
Handle.
Return value:
None

__HAL_FMPI2C_DISABLE

Description:
Disable the specified FMPI2C
peripheral.
Parameters:
__HANDLE__: specifies the FMPI2C
Handle.
Return value:
None

DocID025834 Rev 4

387/964

HAL FMPI2C Generic Driver
__HAL_FMPI2C_GENERATE_NACK

UM1725
Description:
Generate a Non-Acknowledge FMPI2C
peripheral in Slave mode.
Parameters:
__HANDLE__: specifies the FMPI2C
Handle.
Return value:
None

FMPI2C Flag definition
FMPI2C_FLAG_TXE
FMPI2C_FLAG_TXIS
FMPI2C_FLAG_RXNE
FMPI2C_FLAG_ADDR
FMPI2C_FLAG_AF
FMPI2C_FLAG_STOPF
FMPI2C_FLAG_TC
FMPI2C_FLAG_TCR
FMPI2C_FLAG_BERR
FMPI2C_FLAG_ARLO
FMPI2C_FLAG_OVR
FMPI2C_FLAG_PECERR
FMPI2C_FLAG_TIMEOUT
FMPI2C_FLAG_ALERT
FMPI2C_FLAG_BUSY
FMPI2C_FLAG_DIR
FMPI2C General Call Addressing Mode
FMPI2C_GENERALCALL_DISABLE
FMPI2C_GENERALCALL_ENABLE
FMPI2C Interrupt configuration definition
FMPI2C_IT_ERRI
FMPI2C_IT_TCI
FMPI2C_IT_STOPI
FMPI2C_IT_NACKI
FMPI2C_IT_ADDRI
FMPI2C_IT_RXI
FMPI2C_IT_TXI

388/964

DocID025834 Rev 4

UM1725

HAL FMPI2C Generic Driver
FMPI2C Memory Address Size
FMPI2C_MEMADD_SIZE_8BIT
FMPI2C_MEMADD_SIZE_16BIT
FMPI2C No-Stretch Mode
FMPI2C_NOSTRETCH_DISABLE
FMPI2C_NOSTRETCH_ENABLE
FMPI2C Own Address2 Masks
FMPI2C_OA2_NOMASK
FMPI2C_OA2_MASK01
FMPI2C_OA2_MASK02
FMPI2C_OA2_MASK03
FMPI2C_OA2_MASK04
FMPI2C_OA2_MASK05
FMPI2C_OA2_MASK06
FMPI2C_OA2_MASK07
FMPI2C Reload End Mode
FMPI2C_RELOAD_MODE
FMPI2C_AUTOEND_MODE
FMPI2C_SOFTEND_MODE
FMPI2C Start or Stop Mode
FMPI2C_NO_STARTSTOP
FMPI2C_GENERATE_STOP
FMPI2C_GENERATE_START_READ
FMPI2C_GENERATE_START_WRITE
FMPI2C Transfer Direction
FMPI2C_DIRECTION_RECEIVE
FMPI2C_DIRECTION_TRANSMIT
FMPI2C Sequential Transfer Options
FMPI2C_NO_OPTION_FRAME
FMPI2C_FIRST_FRAME
FMPI2C_NEXT_FRAME
FMPI2C_FIRST_AND_LAST_FRAME
FMPI2C_LAST_FRAME

DocID025834 Rev 4

389/964

HAL FMPI2C Extension Driver

UM1725

26

HAL FMPI2C Extension Driver

26.1

FMPI2CEx Firmware driver API description

26.1.1

FMPI2C peripheral Extended features
Comparing to other previous devices, the FMPI2C interface for STM32F4xx devices
contains the following additional features
Possibility to disable or enable Analog Noise Filter
Use of a configured Digital Noise Filter
Disable or enable wakeup from Stop mode

26.1.2

How to use this driver
This driver provides functions to configure Noise Filter and Wake Up Feature
1.
2.
3.

4.

26.1.3

Configure FMPI2C Analog noise filter using the function
HAL_FMPI2CEx_ConfigAnalogFilter()
Configure FMPI2C Digital noise filter using the function
HAL_FMPI2CEx_ConfigDigitalFilter()
Configure the enable or disable of FMPI2C Wake Up Mode using the functions :
HAL_FMPI2CEx_EnableWakeUp()
HAL_FMPI2CEx_DisableWakeUp()
Configure the enable or disable of fast mode plus driving capability using the
functions :
HAL_FMPI2CEx_EnableFastModePlus()
HAL_FMPI2CEx_DisbleFastModePlus()

Extended features functions
This section provides functions allowing to:
Configure Noise Filters
Configure Wake Up Feature
This section contains the following APIs:
HAL_FMPI2CEx_ConfigAnalogFilter()
HAL_FMPI2CEx_ConfigDigitalFilter()
HAL_FMPI2CEx_EnableFastModePlus()
HAL_FMPI2CEx_DisableFastModePlus()

26.1.4

Detailed description of functions
HAL_FMPI2CEx_ConfigAnalogFilter
Function Name

HAL_StatusTypeDef HAL_FMPI2CEx_ConfigAnalogFilter
(FMPI2C_HandleTypeDef * hfmpi2c, uint32_t AnalogFilter)

Function Description

Configure FMPI2C Analog noise filter.

Parameters

390/964

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2Cx peripheral.
AnalogFilter: New state of the Analog filter.
DocID025834 Rev 4

UM1725

HAL FMPI2C Extension Driver
Return values

HAL: status

HAL_FMPI2CEx_ConfigDigitalFilter
Function Name

HAL_StatusTypeDef HAL_FMPI2CEx_ConfigDigitalFilter
(FMPI2C_HandleTypeDef * hfmpi2c, uint32_t DigitalFilter)

Function Description

Configure FMPI2C Digital noise filter.

Parameters

hfmpi2c: Pointer to a FMPI2C_HandleTypeDef structure that
contains the configuration information for the specified
FMPI2Cx peripheral.
DigitalFilter: Coefficient of digital noise filter between 0x00
and 0x0F.

Return values

HAL: status

HAL_FMPI2CEx_EnableFastModePlus
Function Name

void HAL_FMPI2CEx_EnableFastModePlus (uint32_t
ConfigFastModePlus)

Function Description

Enable the FMPI2C fast mode plus driving capability.

Parameters

ConfigFastModePlus: Selects the pin. This parameter can
be one of the FMPI2C Extended Fast Mode Plus values

Return values

None

HAL_FMPI2CEx_DisableFastModePlus
Function Name

void HAL_FMPI2CEx_DisableFastModePlus (uint32_t
ConfigFastModePlus)

Function Description

Disable the FMPI2C fast mode plus driving capability.

Parameters

ConfigFastModePlus: Selects the pin. This parameter can
be one of the FMPI2C Extended Fast Mode Plus values

Return values

None

26.2

FMPI2CEx Firmware driver defines

26.2.1

FMPI2CEx
FMPI2C Extended Analog Filter
FMPI2C_ANALOGFILTER_ENABLE
FMPI2C_ANALOGFILTER_DISABLE
FMPI2C Extended Fast Mode Plus
FMPI2C_FASTMODEPLUS_SCL

Enable Fast Mode Plus on FMPI2C1 SCL pins

FMPI2C_FASTMODEPLUS_SDA

Enable Fast Mode Plus on FMPI2C1 SDA pins

DocID025834 Rev 4

391/964

HAL GPIO Generic Driver

UM1725

27

HAL GPIO Generic Driver

27.1

GPIO Firmware driver registers structures

27.1.1

GPIO_InitTypeDef
Data Fields
uint32_t Pin
uint32_t Mode
uint32_t Pull
uint32_t Speed
uint32_t Alternate

Field Documentation
uint32_t GPIO_InitTypeDef::Pin
Specifies the GPIO pins to be configured. This parameter can be any value of
GPIO_pins_define
uint32_t GPIO_InitTypeDef::Mode
Specifies the operating mode for the selected pins. This parameter can be a value of
GPIO_mode_define
uint32_t GPIO_InitTypeDef::Pull
Specifies the Pull-up or Pull-Down activation for the selected pins. This parameter
can be a value of GPIO_pull_define
uint32_t GPIO_InitTypeDef::Speed
Specifies the speed for the selected pins. This parameter can be a value of
GPIO_speed_define
uint32_t GPIO_InitTypeDef::Alternate
Peripheral to be connected to the selected pins. This parameter can be a value of
GPIO_Alternate_function_selection

27.2

GPIO Firmware driver API description

27.2.1

GPIO Peripheral features
Subject to the specific hardware characteristics of each I/O port listed in the datasheet,
each port bit of the General Purpose IO (GPIO) Ports, can be individually configured by
software in several modes:
Input mode
Analog mode
Output mode
Alternate function mode
External interrupt/event lines
During and just after reset, the alternate functions and external interrupt lines are not
active and the I/O ports are configured in input floating mode.

392/964

DocID025834 Rev 4

UM1725

HAL GPIO Generic Driver
All GPIO pins have weak internal pull-up and pull-down resistors, which can be activated
or not.
In Output or Alternate mode, each IO can be configured on open-drain or push-pull type
and the IO speed can be selected depending on the VDD value.
All ports have external interrupt/event capability. To use external interrupt lines, the port
must be configured in input mode. All available GPIO pins are connected to the 16 external
interrupt/event lines from EXTI0 to EXTI15.
The external interrupt/event controller consists of up to 23 edge detectors (16 lines are
connected to GPIO) for generating event/interrupt requests (each input line can be
independently configured to select the type (interrupt or event) and the corresponding
trigger event (rising or falling or both). Each line can also be masked independently.

27.2.2

How to use this driver
1.
2.

3.

4.
5.
6.
7.
8.

9.

27.2.3

Enable the GPIO AHB clock using the following function:
__HAL_RCC_GPIOx_CLK_ENABLE().
Configure the GPIO pin(s) using HAL_GPIO_Init().
Configure the IO mode using "Mode" member from GPIO_InitTypeDef structure
Activate Pull-up, Pull-down resistor using "Pull" member from GPIO_InitTypeDef
structure.
In case of Output or alternate function mode selection: the speed is configured
through "Speed" member from GPIO_InitTypeDef structure.
In alternate mode is selection, the alternate function connected to the IO is
configured through "Alternate" member from GPIO_InitTypeDef structure.
Analog mode is required when a pin is to be used as ADC channel or DAC
output.
In case of external interrupt/event selection the "Mode" member from
GPIO_InitTypeDef structure select the type (interrupt or event) and the
corresponding trigger event (rising or falling or both).
In case of external interrupt/event mode selection, configure NVIC IRQ priority
mapped to the EXTI line using HAL_NVIC_SetPriority() and enable it using
HAL_NVIC_EnableIRQ().
To get the level of a pin configured in input mode use HAL_GPIO_ReadPin().
To set/reset the level of a pin configured in output mode use
HAL_GPIO_WritePin()/HAL_GPIO_TogglePin().
To lock pin configuration until next reset use HAL_GPIO_LockPin().
During and just after reset, the alternate functions are not active and the GPIO pins
are configured in input floating mode (except JTAG pins).
The LSE oscillator pins OSC32_IN and OSC32_OUT can be used as general
purpose (PC14 and PC15, respectively) when the LSE oscillator is off. The LSE has
priority over the GPIO function.
The HSE oscillator pins OSC_IN/OSC_OUT can be used as general purpose PH0
and PH1, respectively, when the HSE oscillator is off. The HSE has priority over the
GPIO function.

Initialization and de-initialization functions
This section provides functions allowing to initialize and de-initialize the GPIOs to be ready
for use.
This section contains the following APIs:
HAL_GPIO_Init()
HAL_GPIO_DeInit()
DocID025834 Rev 4

393/964

HAL GPIO Generic Driver

27.2.4

UM1725

IO operation functions
This section contains the following APIs:
HAL_GPIO_ReadPin()
HAL_GPIO_WritePin()
HAL_GPIO_TogglePin()
HAL_GPIO_LockPin()
HAL_GPIO_EXTI_IRQHandler()
HAL_GPIO_EXTI_Callback()

27.2.5

Detailed description of functions
HAL_GPIO_Init
Function Name

void HAL_GPIO_Init (GPIO_TypeDef * GPIOx,
GPIO_InitTypeDef * GPIO_Init)

Function Description

Initializes the GPIOx peripheral according to the specified
parameters in the GPIO_Init.

Parameters

GPIOx: where x can be (A..K) to select the GPIO peripheral
for STM32F429X device or x can be (A..I) to select the GPIO
peripheral for STM32F40XX and STM32F427X devices.
GPIO_Init: pointer to a GPIO_InitTypeDef structure that
contains the configuration information for the specified GPIO
peripheral.

Return values

None

HAL_GPIO_DeInit
Function Name

void HAL_GPIO_DeInit (GPIO_TypeDef * GPIOx, uint32_t
GPIO_Pin)

Function Description

De-initializes the GPIOx peripheral registers to their default reset
values.

Parameters

GPIOx: where x can be (A..K) to select the GPIO peripheral
for STM32F429X device or x can be (A..I) to select the GPIO
peripheral for STM32F40XX and STM32F427X devices.
GPIO_Pin: specifies the port bit to be written. This parameter
can be one of GPIO_PIN_x where x can be (0..15).

Return values

None

HAL_GPIO_ReadPin
Function Name

GPIO_PinState HAL_GPIO_ReadPin (GPIO_TypeDef * GPIOx,
uint16_t GPIO_Pin)

Function Description

Reads the specified input port pin.

Parameters

394/964

GPIOx: where x can be (A..K) to select the GPIO peripheral
for STM32F429X device or x can be (A..I) to select the GPIO
peripheral for STM32F40XX and STM32F427X devices.
GPIO_Pin: specifies the port bit to read. This parameter can
be GPIO_PIN_x where x can be (0..15).

DocID025834 Rev 4

UM1725

HAL GPIO Generic Driver
Return values

The: input port pin value.

HAL_GPIO_WritePin
Function Name

void HAL_GPIO_WritePin (GPIO_TypeDef * GPIOx, uint16_t
GPIO_Pin, GPIO_PinState PinState)

Function Description

Sets or clears the selected data port bit.

Parameters

GPIOx: where x can be (A..K) to select the GPIO peripheral
for STM32F429X device or x can be (A..I) to select the GPIO
peripheral for STM32F40XX and STM32F427X devices.
GPIO_Pin: specifies the port bit to be written. This parameter
can be one of GPIO_PIN_x where x can be (0..15).
PinState: specifies the value to be written to the selected bit.
This parameter can be one of the GPIO_PinState enum
values:
GPIO_PIN_RESET: to clear the port pin
GPIO_PIN_SET: to set the port pin

Return values

None

Notes

This function uses GPIOx_BSRR register to allow atomic
read/modify accesses. In this way, there is no risk of an IRQ
occurring between the read and the modify access.

HAL_GPIO_TogglePin
Function Name

void HAL_GPIO_TogglePin (GPIO_TypeDef * GPIOx, uint16_t
GPIO_Pin)

Function Description

Toggles the specified GPIO pins.

Parameters

GPIOx: Where x can be (A..K) to select the GPIO peripheral
for STM32F429X device or x can be (A..I) to select the GPIO
peripheral for STM32F40XX and STM32F427X devices.
GPIO_Pin: Specifies the pins to be toggled.

Return values

None

HAL_GPIO_LockPin
Function Name

HAL_StatusTypeDef HAL_GPIO_LockPin (GPIO_TypeDef *
GPIOx, uint16_t GPIO_Pin)

Function Description

Locks GPIO Pins configuration registers.

Parameters

GPIOx: where x can be (A..F) to select the GPIO peripheral
for STM32F4 family
GPIO_Pin: specifies the port bit to be locked. This parameter
can be any combination of GPIO_PIN_x where x can be
(0..15).

Return values

None

Notes

The locked registers are GPIOx_MODER, GPIOx_OTYPER,
GPIOx_OSPEEDR, GPIOx_PUPDR, GPIOx_AFRL and
GPIOx_AFRH.
The configuration of the locked GPIO pins can no longer be
DocID025834 Rev 4

395/964

HAL GPIO Generic Driver

UM1725
modified until the next reset.

HAL_GPIO_EXTI_IRQHandler
Function Name

void HAL_GPIO_EXTI_IRQHandler (uint16_t GPIO_Pin)

Function Description

This function handles EXTI interrupt request.

Parameters

GPIO_Pin: Specifies the pins connected EXTI line

Return values

None

HAL_GPIO_EXTI_Callback
Function Name

void HAL_GPIO_EXTI_Callback (uint16_t GPIO_Pin)

Function Description

EXTI line detection callbacks.

Parameters

GPIO_Pin: Specifies the pins connected EXTI line

Return values

None

27.3

GPIO Firmware driver defines

27.3.1

GPIO
GPIO Alternate Function Selection
GPIO_AF0_RTC_50Hz
GPIO_AF0_MCO
GPIO_AF0_TAMPER
GPIO_AF0_SWJ
GPIO_AF0_TRACE
GPIO_AF1_TIM1
GPIO_AF1_TIM2
GPIO_AF2_TIM3
GPIO_AF2_TIM4
GPIO_AF2_TIM5
GPIO_AF3_TIM8
GPIO_AF3_TIM9
GPIO_AF3_TIM10
GPIO_AF3_TIM11
GPIO_AF4_I2C1
GPIO_AF4_I2C2
GPIO_AF4_I2C3
GPIO_AF5_SPI1
GPIO_AF5_SPI2

396/964

DocID025834 Rev 4

UM1725

HAL GPIO Generic Driver
GPIO_AF5_SPI3
GPIO_AF5_SPI4
GPIO_AF5_SPI5
GPIO_AF5_SPI6
GPIO_AF5_I2S3ext
GPIO_AF6_SPI3
GPIO_AF6_I2S2ext
GPIO_AF6_SAI1
GPIO_AF7_USART1
GPIO_AF7_USART2
GPIO_AF7_USART3
GPIO_AF7_I2S3ext
GPIO_AF8_UART4
GPIO_AF8_UART5
GPIO_AF8_USART6
GPIO_AF8_UART7
GPIO_AF8_UART8
GPIO_AF9_CAN1
GPIO_AF9_CAN2
GPIO_AF9_TIM12
GPIO_AF9_TIM13
GPIO_AF9_TIM14
GPIO_AF9_LTDC
GPIO_AF9_QSPI
GPIO_AF10_OTG_FS
GPIO_AF10_OTG_HS
GPIO_AF10_QSPI
GPIO_AF11_ETH
GPIO_AF12_FMC
GPIO_AF12_OTG_HS_FS
GPIO_AF12_SDIO
GPIO_AF13_DCMI
GPIO_AF13_DSI
GPIO_AF14_LTDC
GPIO_AF15_EVENTOUT

DocID025834 Rev 4

397/964

HAL GPIO Generic Driver
GPIO Exported Macros

UM1725

__HAL_GPIO_EXTI_GET_FLAG

Description:
Checks whether the specified EXTI line
flag is set or not.
Parameters:
__EXTI_LINE__: specifies the EXTI line
flag to check. This parameter can be
GPIO_PIN_x where x can be(0..15)
Return value:
The: new state of __EXTI_LINE__ (SET or
RESET).

__HAL_GPIO_EXTI_CLEAR_FLAG

Description:
Clears the EXTI's line pending flags.
Parameters:
__EXTI_LINE__: specifies the EXTI lines
flags to clear. This parameter can be any
combination of GPIO_PIN_x where x can
be (0..15)
Return value:
None

__HAL_GPIO_EXTI_GET_IT

Description:
Checks whether the specified EXTI line is
asserted or not.
Parameters:
__EXTI_LINE__: specifies the EXTI line to
check. This parameter can be
GPIO_PIN_x where x can be(0..15)
Return value:
The: new state of __EXTI_LINE__ (SET or
RESET).

__HAL_GPIO_EXTI_CLEAR_IT

Description:
Clears the EXTI's line pending bits.
Parameters:
__EXTI_LINE__: specifies the EXTI lines
to clear. This parameter can be any
combination of GPIO_PIN_x where x can
be (0..15)
Return value:
None

__HAL_GPIO_EXTI_GENERATE_SWIT

Description:
Generates a Software interrupt on selected

398/964

DocID025834 Rev 4

UM1725

HAL GPIO Generic Driver
EXTI line.
Parameters:
__EXTI_LINE__: specifies the EXTI line to
check. This parameter can be
GPIO_PIN_x where x can be(0..15)
Return value:
None
GPIO mode define
GPIO_MODE_INPUT

Input Floating Mode

GPIO_MODE_OUTPUT_PP

Output Push Pull Mode

GPIO_MODE_OUTPUT_OD

Output Open Drain Mode

GPIO_MODE_AF_PP

Alternate Function Push Pull Mode

GPIO_MODE_AF_OD

Alternate Function Open Drain Mode

GPIO_MODE_ANALOG

Analog Mode

GPIO_MODE_IT_RISING

External Interrupt Mode with Rising edge trigger
detection

GPIO_MODE_IT_FALLING

External Interrupt Mode with Falling edge trigger
detection

GPIO_MODE_IT_RISING_FALLING

External Interrupt Mode with Rising/Falling edge
trigger detection

GPIO_MODE_EVT_RISING

External Event Mode with Rising edge trigger
detection

GPIO_MODE_EVT_FALLING

External Event Mode with Falling edge trigger
detection

GPIO_MODE_EVT_RISING_FALLING

External Event Mode with Rising/Falling edge
trigger detection

GPIO pins define
GPIO_PIN_0
GPIO_PIN_1
GPIO_PIN_2
GPIO_PIN_3
GPIO_PIN_4
GPIO_PIN_5
GPIO_PIN_6
GPIO_PIN_7
GPIO_PIN_8
GPIO_PIN_9
GPIO_PIN_10
GPIO_PIN_11

DocID025834 Rev 4

399/964

HAL GPIO Generic Driver
GPIO_PIN_12

UM1725

GPIO_PIN_13
GPIO_PIN_14
GPIO_PIN_15
GPIO_PIN_All
GPIO_PIN_MASK
GPIO pull define
GPIO_NOPULL

No Pull-up or Pull-down activation

GPIO_PULLUP

Pull-up activation

GPIO_PULLDOWN

Pull-down activation

GPIO speed define

400/964

GPIO_SPEED_FREQ_LOW

IO works at 2 MHz, please refer to the product
datasheet

GPIO_SPEED_FREQ_MEDIUM

range 12,5 MHz to 50 MHz, please refer to the
product datasheet

GPIO_SPEED_FREQ_HIGH

range 25 MHz to 100 MHz, please refer to the
product datasheet

GPIO_SPEED_FREQ_VERY_HIGH

range 50 MHz to 200 MHz, please refer to the
product datasheet

DocID025834 Rev 4

UM1725

HAL GPIO Extension Driver

28

HAL GPIO Extension Driver

28.1

GPIOEx Firmware driver defines

28.1.1

GPIOEx
GPIO Get Port Index
GPIO_GET_INDEX
GPIO Check Alternate Function
IS_GPIO_AF

DocID025834 Rev 4

401/964

HAL HASH Generic Driver

UM1725

29

HAL HASH Generic Driver

29.1

HASH Firmware driver registers structures

29.1.1

HASH_InitTypeDef
Data Fields
uint32_t DataType
uint32_t KeySize
uint8_t * pKey

Field Documentation
uint32_t HASH_InitTypeDef::DataType
32-bit data, 16-bit data, 8-bit data or 1-bit string. This parameter can be a value of
HASH_Data_Type
uint32_t HASH_InitTypeDef::KeySize
The key size is used only in HMAC operation
uint8_t* HASH_InitTypeDef::pKey
The key is used only in HMAC operation

29.1.2

HASH_HandleTypeDef
Data Fields
HASH_InitTypeDef Init
uint8_t * pHashInBuffPtr
uint8_t * pHashOutBuffPtr
__IO uint32_t HashBuffSize
__IO uint32_t HashInCount
__IO uint32_t HashITCounter
HAL_StatusTypeDef Status
HAL_HASH_PhaseTypeDef Phase
DMA_HandleTypeDef * hdmain
HAL_LockTypeDef Lock
__IO HAL_HASH_StateTypeDef State

Field Documentation
HASH_InitTypeDef HASH_HandleTypeDef::Init
HASH required parameters
uint8_t* HASH_HandleTypeDef::pHashInBuffPtr
Pointer to input buffer
uint8_t* HASH_HandleTypeDef::pHashOutBuffPtr
Pointer to input buffer

402/964

DocID025834 Rev 4

UM1725

HAL HASH Generic Driver
__IO uint32_t HASH_HandleTypeDef::HashBuffSize
Size of buffer to be processed
__IO uint32_t HASH_HandleTypeDef::HashInCount
Counter of inputed data
__IO uint32_t HASH_HandleTypeDef::HashITCounter
Counter of issued interrupts
HAL_StatusTypeDef HASH_HandleTypeDef::Status
HASH peripheral status
HAL_HASH_PhaseTypeDef HASH_HandleTypeDef::Phase
HASH peripheral phase
DMA_HandleTypeDef* HASH_HandleTypeDef::hdmain
HASH In DMA handle parameters
HAL_LockTypeDef HASH_HandleTypeDef::Lock
HASH locking object
__IO HAL_HASH_StateTypeDef HASH_HandleTypeDef::State
HASH peripheral state

29.2

HASH Firmware driver API description

29.2.1

How to use this driver
The HASH HAL driver can be used as follows:
1.

2.

3.

Initialize the HASH low level resources by implementing the HAL_HASH_MspInit():
a.
Enable the HASH interface clock using __HAL_RCC_HASH_CLK_ENABLE()
b.
In case of using processing APIs based on interrupts (e.g.
HAL_HMAC_SHA1_Start_IT())
Configure the HASH interrupt priority using HAL_NVIC_SetPriority()
Enable the HASH IRQ handler using HAL_NVIC_EnableIRQ()
In HASH IRQ handler, call HAL_HASH_IRQHandler()
c.
In case of using DMA to control data transfer (e.g.
HAL_HMAC_SHA1_Start_DMA())
Enable the DMAx interface clock using __DMAx_CLK_ENABLE()
Configure and enable one DMA stream one for managing data transfer from
memory to peripheral (input stream). Managing data transfer from peripheral
to memory can be performed only using CPU
Associate the initialized DMA handle to the HASH DMA handle using
__HAL_LINKDMA()
Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Stream using HAL_NVIC_SetPriority() and
HAL_NVIC_EnableIRQ()
Initialize the HASH HAL using HAL_HASH_Init(). This function configures mainly:
a.
The data type: 1-bit, 8-bit, 16-bit and 32-bit.
b.
For HMAC, the encryption key.
c.
For HMAC, the key size used for encryption.
Three processing functions are available:
a.
Polling mode: processing APIs are blocking functions i.e. they process the data
and wait till the digest computation is finished e.g. HAL_HASH_SHA1_Start()
b.
Interrupt mode: encryption and decryption APIs are not blocking functions i.e.
they process the data under interrupt e.g. HAL_HASH_SHA1_Start_IT()
c.
DMA mode: processing APIs are not blocking functions and the CPU is not used
for data transfer i.e. the data transfer is ensured by DMA e.g.
HAL_HASH_SHA1_Start_DMA()
DocID025834 Rev 4

403/964

HAL HASH Generic Driver
UM1725
4. When the processing function is called at first time after HAL_HASH_Init() the HASH
peripheral is initialized and processes the buffer in input. After that, the digest
computation is started. When processing multi-buffer use the accumulate function to
write the data in the peripheral without starting the digest computation. In last buffer
use the start function to input the last buffer ans start the digest computation.
a.
e.g. HAL_HASH_SHA1_Accumulate() : write 1st data buffer in the peripheral
without starting the digest computation
b.
write (n-1)th data buffer in the peripheral without starting the digest computation
c.
HAL_HASH_SHA1_Start() : write (n)th data buffer in the peripheral and start the
digest computation
5. In HMAC mode, there is no Accumulate API. Only Start API is available.
6. In case of using DMA, call the DMA start processing e.g.
HAL_HASH_SHA1_Start_DMA(). After that, call the finish function in order to get the
digest value e.g. HAL_HASH_SHA1_Finish()
7. Call HAL_HASH_DeInit() to deinitialize the HASH peripheral.

29.2.2

HASH processing using polling mode functions
This section provides functions allowing to calculate in polling mode the hash value using
one of the following algorithms:
MD5
SHA1
This section contains the following APIs:
HAL_HASH_MD5_Start()
HAL_HASH_MD5_Accumulate()
HAL_HASH_SHA1_Start()
HAL_HASH_SHA1_Accumulate()

29.2.3

HASH processing using interrupt mode functions
This section provides functions allowing to calculate in interrupt mode the hash value using
one of the following algorithms:
MD5
SHA1
This section contains the following APIs:
HAL_HASH_MD5_Start_IT()
HAL_HASH_SHA1_Start_IT()
HAL_HASH_IRQHandler()
HAL_HMAC_SHA1_Start()
HAL_HMAC_MD5_Start()

29.2.4

HASH processing using DMA mode functions
This section provides functions allowing to calculate in DMA mode the hash value using
one of the following algorithms:
MD5
SHA1
This section contains the following APIs:
HAL_HASH_MD5_Start_DMA()
HAL_HASH_MD5_Finish()
HAL_HASH_SHA1_Start_DMA()

404/964

DocID025834 Rev 4

UM1725

HAL HASH Generic Driver
HAL_HASH_SHA1_Finish()
HAL_HASH_SHA1_Start_IT()
HAL_HASH_MD5_Start_IT()

29.2.5

HMAC processing using polling mode functions
This section provides functions allowing to calculate in polling mode the HMAC value using
one of the following algorithms:
MD5
SHA1
This section contains the following APIs:
HAL_HMAC_MD5_Start()
HAL_HMAC_SHA1_Start()
HAL_HASH_SHA1_Start_DMA()
HAL_HASH_SHA1_Finish()
HAL_HASH_MD5_Start_DMA()
HAL_HASH_MD5_Finish()

29.2.6

HMAC processing using DMA mode functions
This section provides functions allowing to calculate in DMA mode the HMAC value using
one of the following algorithms:
MD5
SHA1
This section contains the following APIs:
HAL_HMAC_MD5_Start_DMA()
HAL_HMAC_SHA1_Start_DMA()

29.2.7

Peripheral State functions
This subsection permits to get in run-time the status of the peripheral.
This section contains the following APIs:
HAL_HASH_GetState()
HAL_HASH_IRQHandler()

29.2.8

Initialization and de-initialization functions
This section provides functions allowing to:
Initialize the HASH according to the specified parameters in the HASH_InitTypeDef
and creates the associated handle.
DeInitialize the HASH peripheral.
Initialize the HASH MSP.
DeInitialize HASH MSP.
This section contains the following APIs:
HAL_HASH_Init()
HAL_HASH_DeInit()
HAL_HASH_MspInit()
HAL_HASH_MspDeInit()
HAL_HASH_InCpltCallback()
HAL_HASH_ErrorCallback()
DocID025834 Rev 4

405/964

HAL HASH Generic Driver

UM1725

HAL_HASH_DgstCpltCallback()

29.2.9

Detailed description of functions
HAL_HASH_Init
Function Name

HAL_StatusTypeDef HAL_HASH_Init (HASH_HandleTypeDef *
hhash)

Function Description

Initializes the HASH according to the specified parameters in the
HASH_HandleTypeDef and creates the associated handle.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module

Return values

HAL: status

HAL_HASH_DeInit
Function Name

HAL_StatusTypeDef HAL_HASH_DeInit
(HASH_HandleTypeDef * hhash)

Function Description

DeInitializes the HASH peripheral.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module

Return values

HAL: status

Notes

This API must be called before starting a new processing.

HAL_HASH_SHA1_Start
Function Name

HAL_StatusTypeDef HAL_HASH_SHA1_Start
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size, uint8_t * pOutBuffer, uint32_t Timeout)

Function Description

Initializes the HASH peripheral in SHA1 mode then processes
pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.
pOutBuffer: Pointer to the computed digest. Its size must be
20 bytes.
Timeout: Timeout value

Return values

HAL: status

HAL_HASH_MD5_Start

406/964

Function Name

HAL_StatusTypeDef HAL_HASH_MD5_Start
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size, uint8_t * pOutBuffer, uint32_t Timeout)

Function Description

Initializes the HASH peripheral in MD5 mode then processes
pInBuffer.

DocID025834 Rev 4

UM1725

HAL HASH Generic Driver
Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is multiple
of 64 bytes, appending the input buffer is possible. If the Size
is not multiple of 64 bytes, the padding is managed by
hardware and appending the input buffer is no more possible.
pOutBuffer: Pointer to the computed digest. Its size must be
16 bytes.
Timeout: Timeout value

Return values

HAL: status

HAL_HASH_MD5_Accumulate
Function Name

HAL_StatusTypeDef HAL_HASH_MD5_Accumulate
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in MD5 mode then writes the
pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is multiple
of 64 bytes, appending the input buffer is possible. If the Size
is not multiple of 64 bytes, the padding is managed by
hardware and appending the input buffer is no more possible.

Return values

HAL: status

HAL_HASH_SHA1_Accumulate
Function Name

HAL_StatusTypeDef HAL_HASH_SHA1_Accumulate
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in SHA1 mode then processes
pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.

Return values

HAL: status

Notes

Input buffer size in bytes must be a multiple of 4 otherwise the
digest computation is corrupted.

HAL_HMAC_SHA1_Start
Function Name

HAL_StatusTypeDef HAL_HMAC_SHA1_Start
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size, uint8_t * pOutBuffer, uint32_t Timeout)

DocID025834 Rev 4

407/964

HAL HASH Generic Driver
Function Description

UM1725
Initializes the HASH peripheral in HMAC SHA1 mode then
processes pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.
pOutBuffer: Pointer to the computed digest. Its size must be
20 bytes.
Timeout: Timeout value

Return values

HAL: status

HAL_HMAC_MD5_Start
Function Name

HAL_StatusTypeDef HAL_HMAC_MD5_Start
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size, uint8_t * pOutBuffer, uint32_t Timeout)

Function Description

Initializes the HASH peripheral in HMAC MD5 mode then
processes pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.
pOutBuffer: Pointer to the computed digest. Its size must be
20 bytes.
Timeout: Timeout value

Return values

HAL: status

HAL_HASH_SHA1_Start_IT
Function Name

HAL_StatusTypeDef HAL_HASH_SHA1_Start_IT
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size, uint8_t * pOutBuffer)

Function Description

Initializes the HASH peripheral in SHA1 mode then processes
pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.
pOutBuffer: Pointer to the computed digest. Its size must be
20 bytes.

Return values

HAL: status

HAL_HASH_MD5_Start_IT
Function Name

408/964

HAL_StatusTypeDef HAL_HASH_MD5_Start_IT
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t

DocID025834 Rev 4

UM1725

HAL HASH Generic Driver
Size, uint8_t * pOutBuffer)
Function Description

Initializes the HASH peripheral in MD5 mode then processes
pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.
pOutBuffer: Pointer to the computed digest. Its size must be
16 bytes.

Return values

HAL: status

HAL_HASH_SHA1_Start_DMA
Function Name

HAL_StatusTypeDef HAL_HASH_SHA1_Start_DMA
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in SHA1 mode then enables DMA
to control data transfer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.

Return values

HAL: status

HAL_HASH_SHA1_Finish
Function Name

HAL_StatusTypeDef HAL_HASH_SHA1_Finish
(HASH_HandleTypeDef * hhash, uint8_t * pOutBuffer, uint32_t
Timeout)

Function Description

Returns the computed digest in SHA1 mode.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pOutBuffer: Pointer to the computed digest. Its size must be
20 bytes.
Timeout: Timeout value

Return values

HAL: status

HAL_HASH_MD5_Start_DMA
Function Name

HAL_StatusTypeDef HAL_HASH_MD5_Start_DMA
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in MD5 mode then enables DMA to
control data transfer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
DocID025834 Rev 4

409/964

HAL HASH Generic Driver

UM1725
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.

Return values

HAL: status

HAL_HASH_MD5_Finish
Function Name

HAL_StatusTypeDef HAL_HASH_MD5_Finish
(HASH_HandleTypeDef * hhash, uint8_t * pOutBuffer, uint32_t
Timeout)

Function Description

Returns the computed digest in MD5 mode.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pOutBuffer: Pointer to the computed digest. Its size must be
16 bytes.
Timeout: Timeout value

Return values

HAL: status

HAL_HMAC_SHA1_Start_DMA
Function Name

HAL_StatusTypeDef HAL_HMAC_SHA1_Start_DMA
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in HMAC SHA1 mode then enables
DMA to control data transfer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.

Return values

HAL: status

HAL_HMAC_MD5_Start_DMA

410/964

Function Name

HAL_StatusTypeDef HAL_HMAC_MD5_Start_DMA
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in HMAC MD5 mode then enables
DMA to control data transfer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL HASH Generic Driver

HAL_HASH_IRQHandler
Function Name

void HAL_HASH_IRQHandler (HASH_HandleTypeDef * hhash)

Function Description

This function handles HASH interrupt request.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module

Return values

None

HAL_HASH_GetState
Function Name

HAL_HASH_StateTypeDef HAL_HASH_GetState
(HASH_HandleTypeDef * hhash)

Function Description

return the HASH state

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module

Return values

HAL: state

HAL_HASH_MspInit
Function Name

void HAL_HASH_MspInit (HASH_HandleTypeDef * hhash)

Function Description

Initializes the HASH MSP.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module

Return values

None

HAL_HASH_MspDeInit
Function Name

void HAL_HASH_MspDeInit (HASH_HandleTypeDef * hhash)

Function Description

DeInitializes HASH MSP.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module

Return values

None

HAL_HASH_InCpltCallback
Function Name

void HAL_HASH_InCpltCallback (HASH_HandleTypeDef *
hhash)

Function Description

Input data transfer complete callback.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module

Return values

None

DocID025834 Rev 4

411/964

HAL HASH Generic Driver

UM1725

HAL_HASH_DgstCpltCallback
Function Name

void HAL_HASH_DgstCpltCallback (HASH_HandleTypeDef *
hhash)

Function Description

Digest computation complete callback.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module

Return values

None

Notes

This callback is not relevant with DMA.

HAL_HASH_ErrorCallback
Function Name

void HAL_HASH_ErrorCallback (HASH_HandleTypeDef *
hhash)

Function Description

Data transfer Error callback.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module

Return values

None

29.3

HASH Firmware driver defines

29.3.1

HASH
HASH Data Type
HASH_DATATYPE_32B

32-bit data. No swapping

HASH_DATATYPE_16B

16-bit data. Each half word is swapped

HASH_DATATYPE_8B

8-bit data. All bytes are swapped

HASH_DATATYPE_1B

1-bit data. In the word all bits are swapped

HASH Algorithm Selection
HASH_ALGOSELECTION_SHA1

HASH function is SHA1

HASH_ALGOSELECTION_SHA224

HASH function is SHA224

HASH_ALGOSELECTION_SHA256

HASH function is SHA256

HASH_ALGOSELECTION_MD5

HASH function is MD5

HASH Algorithm Mode
HASH_ALGOMODE_HASH

Algorithm is HASH

HASH_ALGOMODE_HMAC

Algorithm is HMAC

HASH HMAC Long key

412/964

HASH_HMAC_KEYTYPE_SHORTKEY

HMAC Key is <= 64 bytes

HASH_HMAC_KEYTYPE_LONGKEY

HMAC Key is> 64 bytes

DocID025834 Rev 4

UM1725

HAL HASH Generic Driver
HASH Flags definition
HASH_FLAG_DINIS

16 locations are free in the DIN : A new block can be entered into
the input buffer

HASH_FLAG_DCIS

Digest calculation complete

HASH_FLAG_DMAS

DMA interface is enabled (DMAE=1) or a transfer is ongoing

HASH_FLAG_BUSY

The hash core is Busy : processing a block of data

HASH_FLAG_DINNE

DIN not empty : The input buffer contains at least one word of data

HASH Interrupts definition
HASH_IT_DINI

A new block can be entered into the input buffer (DIN)

HASH_IT_DCI

Digest calculation complete

HASH Exported Macros
__HAL_HASH_RESET_HANDLE_STATE

Description:
Reset HASH handle state.
Parameters:
__HANDLE__: specifies the HASH
handle.
Return value:
None
Description:

__HAL_HASH_GET_FLAG

Check whether the specified HASH flag is
set or not.
Parameters:
__FLAG__: specifies the flag to check.
This parameter can be one of the
following values:
HASH_FLAG_DINIS: A new block
can be entered into the input buffer.
HASH_FLAG_DCIS: Digest
calculation complete
HASH_FLAG_DMAS: DMA interface
is enabled (DMAE=1) or a transfer is
ongoing
HASH_FLAG_BUSY: The hash core
is Busy : processing a block of data
HASH_FLAG_DINNE: DIN not
empty : The input buffer contains at
least one word of data
Return value:
The: new state of __FLAG__ (TRUE or
FALSE).
__HAL_HASH_SET_MDMAT

Description:
Enable the multiple DMA mode.

DocID025834 Rev 4

413/964

HAL HASH Generic Driver

UM1725
Return value:
None

__HAL_HASH_RESET_MDMAT

Description:
Disable the multiple DMA mode.
Return value:
None

__HAL_HASH_START_DIGEST

Description:
Start the digest computation.
Return value:
None

__HAL_HASH_SET_NBVALIDBITS

Description:
Set the number of valid bits in last word
written in Data register.
Parameters:
SIZE: size in byte of last data written in
Data register.
Return value:
None

414/964

DocID025834 Rev 4

UM1725

HAL HASH Extension Driver

30

HAL HASH Extension Driver

30.1

HASHEx Firmware driver API description

30.1.1

How to use this driver
The HASH HAL driver can be used as follows:
1.

2.

3.

4.

5.
6.

Initialize the HASH low level resources by implementing the HAL_HASH_MspInit():
a.
Enable the HASH interface clock using __HAL_RCC_HASH_CLK_ENABLE()
b.
In case of using processing APIs based on interrupts (e.g.
HAL_HMACEx_SHA224_Start())
Configure the HASH interrupt priority using HAL_NVIC_SetPriority()
Enable the HASH IRQ handler using HAL_NVIC_EnableIRQ()
In HASH IRQ handler, call HAL_HASH_IRQHandler()
c.
In case of using DMA to control data transfer (e.g.
HAL_HMACEx_SH224_Start_DMA())
Enable the DMAx interface clock using __DMAx_CLK_ENABLE()
Configure and enable one DMA stream one for managing data transfer from
memory to peripheral (input stream). Managing data transfer from peripheral
to memory can be performed only using CPU
Associate the initialized DMA handle to the HASH DMA handle using
__HAL_LINKDMA()
Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Stream: HAL_NVIC_SetPriority() and
HAL_NVIC_EnableIRQ()
Initialize the HASH HAL using HAL_HASH_Init(). This function configures mainly:
a.
The data type: 1-bit, 8-bit, 16-bit and 32-bit.
b.
For HMAC, the encryption key.
c.
For HMAC, the key size used for encryption.
Three processing functions are available:
a.
Polling mode: processing APIs are blocking functions i.e. they process the data
and wait till the digest computation is finished e.g.
HAL_HASHEx_SHA224_Start()
b.
Interrupt mode: encryption and decryption APIs are not blocking functions i.e.
they process the data under interrupt e.g. HAL_HASHEx_SHA224_Start_IT()
c.
DMA mode: processing APIs are not blocking functions and the CPU is not used
for data transfer i.e. the data transfer is ensured by DMA e.g.
HAL_HASHEx_SHA224_Start_DMA()
When the processing function is called at first time after HAL_HASH_Init() the HASH
peripheral is initialized and processes the buffer in input. After that, the digest
computation is started. When processing multi-buffer use the accumulate function to
write the data in the peripheral without starting the digest computation. In last buffer
use the start function to input the last buffer ans start the digest computation.
a.
e.g. HAL_HASHEx_SHA224_Accumulate() : write 1st data buffer in the
peripheral without starting the digest computation
b.
write (n-1)th data buffer in the peripheral without starting the digest computation
c.
HAL_HASHEx_SHA224_Start() : write (n)th data buffer in the peripheral and
start the digest computation
In HMAC mode, there is no Accumulate API. Only Start API is available.
In case of using DMA, call the DMA start processing e.g.
HAL_HASHEx_SHA224_Start_DMA(). After that, call the finish function in order to get
the digest value e.g. HAL_HASHEx_SHA224_Finish()
DocID025834 Rev 4

415/964

HAL HASH Extension Driver
7. Call HAL_HASH_DeInit() to deinitialize the HASH peripheral.

30.1.2

UM1725

HASH processing using polling mode functions
This section provides functions allowing to calculate in polling mode the hash value using
one of the following algorithms:
SHA224
SHA256
This section contains the following APIs:
HAL_HASHEx_SHA224_Start()
HAL_HASHEx_SHA256_Start()
HAL_HASHEx_SHA224_Accumulate()
HAL_HASHEx_SHA256_Accumulate()

30.1.3

HMAC processing using polling mode functions
This section provides functions allowing to calculate in polling mode the HMAC value using
one of the following algorithms:
SHA224
SHA256
This section contains the following APIs:
HAL_HMACEx_SHA224_Start()
HAL_HMACEx_SHA256_Start()

30.1.4

HASH processing using interrupt functions
This section provides functions allowing to calculate in interrupt mode the hash value using
one of the following algorithms:
SHA224
SHA256
This section contains the following APIs:
HAL_HASHEx_SHA224_Start_IT()
HAL_HASHEx_SHA256_Start_IT()
HAL_HASHEx_IRQHandler()

30.1.5

HASH processing using DMA functions
This section provides functions allowing to calculate in DMA mode the hash value using
one of the following algorithms:
SHA224
SHA256
This section contains the following APIs:
HAL_HASHEx_SHA224_Start_DMA()
HAL_HASHEx_SHA224_Finish()
HAL_HASHEx_SHA256_Start_DMA()
HAL_HASHEx_SHA256_Finish()

416/964

DocID025834 Rev 4

UM1725

30.1.6

HAL HASH Extension Driver

HMAC processing using DMA functions
This section provides functions allowing to calculate in DMA mode the HMAC value using
one of the following algorithms:
SHA224
SHA256
This section contains the following APIs:
HAL_HMACEx_SHA224_Start_DMA()
HAL_HMACEx_SHA256_Start_DMA()

30.1.7

Detailed description of functions
HAL_HASHEx_SHA224_Start
Function Name

HAL_StatusTypeDef HAL_HASHEx_SHA224_Start
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size, uint8_t * pOutBuffer, uint32_t Timeout)

Function Description

Initializes the HASH peripheral in SHA224 mode then processes
pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.
pOutBuffer: Pointer to the computed digest. Its size must be
28 bytes.
Timeout: Specify Timeout value

Return values

HAL: status

HAL_HASHEx_SHA256_Start
Function Name

HAL_StatusTypeDef HAL_HASHEx_SHA256_Start
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size, uint8_t * pOutBuffer, uint32_t Timeout)

Function Description

Initializes the HASH peripheral in SHA256 mode then processes
pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.
pOutBuffer: Pointer to the computed digest. Its size must be
32 bytes.
Timeout: Specify Timeout value

Return values

HAL: status

DocID025834 Rev 4

417/964

HAL HASH Extension Driver

UM1725

HAL_HASHEx_SHA224_Accumulate
Function Name

HAL_StatusTypeDef HAL_HASHEx_SHA224_Accumulate
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in SHA224 mode then processes
pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.

Return values

HAL: status

HAL_HASHEx_SHA256_Accumulate
Function Name

HAL_StatusTypeDef HAL_HASHEx_SHA256_Accumulate
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in SHA256 mode then processes
pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.

Return values

HAL: status

HAL_HMACEx_SHA224_Start

418/964

Function Name

HAL_StatusTypeDef HAL_HMACEx_SHA224_Start
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size, uint8_t * pOutBuffer, uint32_t Timeout)

Function Description

Initializes the HASH peripheral in HMAC SHA224 mode then
processes pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.
pOutBuffer: Pointer to the computed digest. Its size must be
20 bytes.
Timeout: Timeout value

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL HASH Extension Driver

HAL_HMACEx_SHA256_Start
Function Name

HAL_StatusTypeDef HAL_HMACEx_SHA256_Start
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size, uint8_t * pOutBuffer, uint32_t Timeout)

Function Description

Initializes the HASH peripheral in HMAC SHA256 mode then
processes pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.
pOutBuffer: Pointer to the computed digest. Its size must be
20 bytes.
Timeout: Timeout value

Return values

HAL: status

HAL_HASHEx_SHA224_Start_IT
Function Name

HAL_StatusTypeDef HAL_HASHEx_SHA224_Start_IT
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size, uint8_t * pOutBuffer)

Function Description

Initializes the HASH peripheral in SHA224 mode then processes
pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.
pOutBuffer: Pointer to the computed digest. Its size must be
20 bytes.

Return values

HAL: status

HAL_HASHEx_SHA256_Start_IT
Function Name

HAL_StatusTypeDef HAL_HASHEx_SHA256_Start_IT
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size, uint8_t * pOutBuffer)

Function Description

Initializes the HASH peripheral in SHA256 mode then processes
pInBuffer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.
pOutBuffer: Pointer to the computed digest. Its size must be
20 bytes.

Return values

HAL: status

DocID025834 Rev 4

419/964

HAL HASH Extension Driver

UM1725

HAL_HASHEx_SHA224_Start_DMA
Function Name

HAL_StatusTypeDef HAL_HASHEx_SHA224_Start_DMA
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in SHA224 mode then enables
DMA to control data transfer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.

Return values

HAL: status

HAL_HASHEx_SHA224_Finish
Function Name

HAL_StatusTypeDef HAL_HASHEx_SHA224_Finish
(HASH_HandleTypeDef * hhash, uint8_t * pOutBuffer, uint32_t
Timeout)

Function Description

Returns the computed digest in SHA224.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pOutBuffer: Pointer to the computed digest. Its size must be
28 bytes.
Timeout: Timeout value

Return values

HAL: status

HAL_HASHEx_SHA256_Start_DMA
Function Name

HAL_StatusTypeDef HAL_HASHEx_SHA256_Start_DMA
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in SHA256 mode then enables
DMA to control data transfer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.

Return values

HAL: status

HAL_HASHEx_SHA256_Finish
Function Name

HAL_StatusTypeDef HAL_HASHEx_SHA256_Finish
(HASH_HandleTypeDef * hhash, uint8_t * pOutBuffer, uint32_t
Timeout)

Function Description

Returns the computed digest in SHA256.

Parameters

420/964

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
DocID025834 Rev 4

UM1725

HAL HASH Extension Driver
pOutBuffer: Pointer to the computed digest. Its size must be
32 bytes.
Timeout: Timeout value
Return values

HAL: status

HAL_HMACEx_SHA224_Start_DMA
Function Name

HAL_StatusTypeDef HAL_HMACEx_SHA224_Start_DMA
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in HMAC SHA224 mode then
enables DMA to control data transfer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.

Return values

HAL: status

HAL_HMACEx_SHA256_Start_DMA
Function Name

HAL_StatusTypeDef HAL_HMACEx_SHA256_Start_DMA
(HASH_HandleTypeDef * hhash, uint8_t * pInBuffer, uint32_t
Size)

Function Description

Initializes the HASH peripheral in HMAC SHA256 mode then
enables DMA to control data transfer.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module
pInBuffer: Pointer to the input buffer (buffer to be hashed).
Size: Length of the input buffer in bytes. If the Size is not
multiple of 64 bytes, the padding is managed by hardware.

Return values

HAL: status

HAL_HASHEx_IRQHandler
Function Name

void HAL_HASHEx_IRQHandler (HASH_HandleTypeDef *
hhash)

Function Description

This function handles HASH interrupt request.

Parameters

hhash: pointer to a HASH_HandleTypeDef structure that
contains the configuration information for HASH module

Return values

None

DocID025834 Rev 4

421/964

HAL HCD Generic Driver

UM1725

31

HAL HCD Generic Driver

31.1

HCD Firmware driver registers structures

31.1.1

HCD_HandleTypeDef
Data Fields
HCD_TypeDef * Instance
HCD_InitTypeDef Init
HCD_HCTypeDef hc
HAL_LockTypeDef Lock
__IO HCD_StateTypeDef State
void * pData

Field Documentation
HCD_TypeDef* HCD_HandleTypeDef::Instance
Register base address
HCD_InitTypeDef HCD_HandleTypeDef::Init
HCD required parameters
HCD_HCTypeDef HCD_HandleTypeDef::hc[15]
Host channels parameters
HAL_LockTypeDef HCD_HandleTypeDef::Lock
HCD peripheral status
__IO HCD_StateTypeDef HCD_HandleTypeDef::State
HCD communication state
void* HCD_HandleTypeDef::pData
Pointer Stack Handler

31.2

HCD Firmware driver API description

31.2.1

How to use this driver
1.
2.
3.
4.

422/964

Declare a HCD_HandleTypeDef handle structure, for example: HCD_HandleTypeDef
hhcd;
Fill parameters of Init structure in HCD handle
Call HAL_HCD_Init() API to initialize the HCD peripheral (Core, Host core, ...)
Initialize the HCD low level resources through the HAL_HCD_MspInit() API:
a.
Enable the HCD/USB Low Level interface clock using the following macros
__HAL_RCC_USB_OTG_FS_CLK_ENABLE();
__HAL_RCC_USB_OTG_HS_CLK_ENABLE(); (For High Speed Mode)
__HAL_RCC_USB_OTG_HS_ULPI_CLK_ENABLE(); (For High Speed
Mode)
b.
Initialize the related GPIO clocks
c.
Configure HCD pin-out
d.
Configure HCD NVIC interrupt
DocID025834 Rev 4

UM1725

HAL HCD Generic Driver
5.
6.

31.2.2

Associate the Upper USB Host stack to the HAL HCD Driver:
a.
hhcd.pData = phost;
Enable HCD transmission and reception:
a.
HAL_HCD_Start();

Initialization and de-initialization functions
This section provides functions allowing to:
This section contains the following APIs:
HAL_HCD_Init()
HAL_HCD_HC_Init()
HAL_HCD_HC_Halt()
HAL_HCD_DeInit()
HAL_HCD_MspInit()
HAL_HCD_MspDeInit()

31.2.3

IO operation functions
This subsection provides a set of functions allowing to manage the USB Host Data
Transfer
This section contains the following APIs:
HAL_HCD_HC_SubmitRequest()
HAL_HCD_IRQHandler()
HAL_HCD_SOF_Callback()
HAL_HCD_Connect_Callback()
HAL_HCD_Disconnect_Callback()
HAL_HCD_HC_NotifyURBChange_Callback()

31.2.4

Peripheral Control functions
This subsection provides a set of functions allowing to control the HCD data transfers.
This section contains the following APIs:
HAL_HCD_Start()
HAL_HCD_Stop()
HAL_HCD_ResetPort()

31.2.5

Peripheral State functions
This subsection permits to get in run-time the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_HCD_GetState()
HAL_HCD_HC_GetURBState()
HAL_HCD_HC_GetXferCount()
HAL_HCD_HC_GetState()
HAL_HCD_GetCurrentFrame()
HAL_HCD_GetCurrentSpeed()

DocID025834 Rev 4

423/964

HAL HCD Generic Driver

31.2.6

UM1725

Detailed description of functions
HAL_HCD_Init
Function Name

HAL_StatusTypeDef HAL_HCD_Init (HCD_HandleTypeDef *
hhcd)

Function Description

Initialize the host driver.

Parameters

hhcd: HCD handle

Return values

HAL: status

HAL_HCD_DeInit
Function Name

HAL_StatusTypeDef HAL_HCD_DeInit (HCD_HandleTypeDef *
hhcd)

Function Description

DeInitialize the host driver.

Parameters

hhcd: HCD handle

Return values

HAL: status

HAL_HCD_HC_Init
Function Name

HAL_StatusTypeDef HAL_HCD_HC_Init (HCD_HandleTypeDef
* hhcd, uint8_t ch_num, uint8_t epnum, uint8_t dev_address,
uint8_t speed, uint8_t ep_type, uint16_t mps)

Function Description

Initialize a host channel.

Parameters

hhcd: HCD handle
ch_num: Channel number. This parameter can be a value
from 1 to 15
epnum: Endpoint number. This parameter can be a value
from 1 to 15
dev_address: : Current device address This parameter can
be a value from 0 to 255
speed: Current device speed. This parameter can be one of
these values: HCD_SPEED_HIGH: High speed mode,
HCD_SPEED_FULL: Full speed mode, HCD_SPEED_LOW:
Low speed mode
ep_type: Endpoint Type. This parameter can be one of these
values: EP_TYPE_CTRL: Control type, EP_TYPE_ISOC:
Isochronous type, EP_TYPE_BULK: Bulk type,
EP_TYPE_INTR: Interrupt type
mps: Max Packet Size. This parameter can be a value from
0 to32K

Return values

HAL: status

HAL_HCD_HC_Halt

424/964

Function Name

HAL_StatusTypeDef HAL_HCD_HC_Halt
(HCD_HandleTypeDef * hhcd, uint8_t ch_num)

Function Description

Halt a host channel.

DocID025834 Rev 4

UM1725

HAL HCD Generic Driver
Parameters

hhcd: HCD handle
ch_num: Channel number. This parameter can be a value
from 1 to 15

Return values

HAL: status

HAL_HCD_MspInit
Function Name

void HAL_HCD_MspInit (HCD_HandleTypeDef * hhcd)

Function Description

Initialize the HCD MSP.

Parameters

hhcd: HCD handle

Return values

None

HAL_HCD_MspDeInit
Function Name

void HAL_HCD_MspDeInit (HCD_HandleTypeDef * hhcd)

Function Description

DeInitialize the HCD MSP.

Parameters

hhcd: HCD handle

Return values

None

HAL_HCD_HC_SubmitRequest
Function Name

HAL_StatusTypeDef HAL_HCD_HC_SubmitRequest
(HCD_HandleTypeDef * hhcd, uint8_t ch_num, uint8_t
direction, uint8_t ep_type, uint8_t token, uint8_t * pbuff,
uint16_t length, uint8_t do_ping)

Function Description

Submit a new URB for processing.

Parameters

hhcd: HCD handle
ch_num: Channel number. This parameter can be a value
from 1 to 15
direction: Channel number. This parameter can be one of
these values: 0 : Output / 1 : Input
ep_type: Endpoint Type. This parameter can be one of these
values: EP_TYPE_CTRL: Control type/ EP_TYPE_ISOC:
Isochronous type/ EP_TYPE_BULK: Bulk type/
EP_TYPE_INTR: Interrupt type/
token: Endpoint Type. This parameter can be one of these
values: 0: HC_PID_SETUP / 1: HC_PID_DATA1
pbuff: pointer to URB data
length: Length of URB data
do_ping: activate do ping protocol (for high speed only). This
parameter can be one of these values: 0 : do ping inactive / 1
: do ping active

Return values

HAL: status

HAL_HCD_IRQHandler
Function Name

void HAL_HCD_IRQHandler (HCD_HandleTypeDef * hhcd)

Function Description

Handle HCD interrupt request.
DocID025834 Rev 4

425/964

HAL HCD Generic Driver
Parameters

UM1725
hhcd: HCD handle

Return values

None

HAL_HCD_SOF_Callback
Function Name

void HAL_HCD_SOF_Callback (HCD_HandleTypeDef * hhcd)

Function Description

SOF callback.

Parameters

hhcd: HCD handle

Return values

None

HAL_HCD_Connect_Callback
Function Name

void HAL_HCD_Connect_Callback (HCD_HandleTypeDef *
hhcd)

Function Description

Connection Event callback.

Parameters

hhcd: HCD handle

Return values

None

HAL_HCD_Disconnect_Callback
Function Name

void HAL_HCD_Disconnect_Callback (HCD_HandleTypeDef *
hhcd)

Function Description

Disconnection Event callback.

Parameters

hhcd: HCD handle

Return values

None

HAL_HCD_HC_NotifyURBChange_Callback
Function Name

void HAL_HCD_HC_NotifyURBChange_Callback
(HCD_HandleTypeDef * hhcd, uint8_t chnum,
HCD_URBStateTypeDef urb_state)

Function Description

Notify URB state change callback.

Parameters

hhcd: HCD handle
chnum: Channel number. This parameter can be a value
from 1 to 15
urb_state: This parameter can be one of these values:
URB_IDLE/ URB_DONE/ URB_NOTREADY/ URB_NYET/
URB_ERROR/ URB_STALL/

Return values

None

HAL_HCD_ResetPort

426/964

Function Name

HAL_StatusTypeDef HAL_HCD_ResetPort
(HCD_HandleTypeDef * hhcd)

Function Description

Reset the host port.

DocID025834 Rev 4

UM1725

HAL HCD Generic Driver
Parameters

hhcd: HCD handle

Return values

HAL: status

HAL_HCD_Start
Function Name

HAL_StatusTypeDef HAL_HCD_Start (HCD_HandleTypeDef *
hhcd)

Function Description

Start the host driver.

Parameters

hhcd: HCD handle

Return values

HAL: status

HAL_HCD_Stop
Function Name

HAL_StatusTypeDef HAL_HCD_Stop (HCD_HandleTypeDef *
hhcd)

Function Description

Stop the host driver.

Parameters

hhcd: HCD handle

Return values

HAL: status

HAL_HCD_GetState
Function Name

HCD_StateTypeDef HAL_HCD_GetState (HCD_HandleTypeDef
* hhcd)

Function Description

Return the HCD handle state.

Parameters

hhcd: HCD handle

Return values

HAL: state

HAL_HCD_HC_GetURBState
Function Name

HCD_URBStateTypeDef HAL_HCD_HC_GetURBState
(HCD_HandleTypeDef * hhcd, uint8_t chnum)

Function Description

Return URB state for a channel.

Parameters

hhcd: HCD handle
chnum: Channel number. This parameter can be a value
from 1 to 15

Return values

URB: state. This parameter can be one of these values:
URB_IDLE/ URB_DONE/ URB_NOTREADY/ URB_NYET/
URB_ERROR/ URB_STALL

HAL_HCD_HC_GetXferCount
Function Name

uint32_t HAL_HCD_HC_GetXferCount (HCD_HandleTypeDef *
hhcd, uint8_t chnum)

Function Description

Return the last host transfer size.

Parameters

hhcd: HCD handle
chnum: Channel number. This parameter can be a value
DocID025834 Rev 4

427/964

HAL HCD Generic Driver

UM1725
from 1 to 15

Return values

last: transfer size in byte

HAL_HCD_HC_GetState
Function Name

HCD_HCStateTypeDef HAL_HCD_HC_GetState
(HCD_HandleTypeDef * hhcd, uint8_t chnum)

Function Description

Return the Host Channel state.

Parameters

hhcd: HCD handle
chnum: Channel number. This parameter can be a value
from 1 to 15

Return values

Host: channel state This parameter can be one of these
values: HC_IDLE/ HC_XFRC/ HC_HALTED/ HC_NYET/
HC_NAK/ HC_STALL/ HC_XACTERR/ HC_BBLERR/
HC_DATATGLERR

HAL_HCD_GetCurrentFrame
Function Name

uint32_t HAL_HCD_GetCurrentFrame (HCD_HandleTypeDef *
hhcd)

Function Description

Return the current Host frame number.

Parameters

hhcd: HCD handle

Return values

Current: Host frame number

HAL_HCD_GetCurrentSpeed
Function Name

uint32_t HAL_HCD_GetCurrentSpeed (HCD_HandleTypeDef *
hhcd)

Function Description

Return the Host enumeration speed.

Parameters

hhcd: HCD handle

Return values

Enumeration: speed

31.3

HCD Firmware driver defines

31.3.1

HCD
HCD Exported Macros
__HAL_HCD_ENABLE
__HAL_HCD_DISABLE
__HAL_HCD_GET_FLAG
__HAL_HCD_CLEAR_FLAG
__HAL_HCD_IS_INVALID_INTERRUPT
__HAL_HCD_CLEAR_HC_INT
__HAL_HCD_MASK_HALT_HC_INT

428/964

DocID025834 Rev 4

UM1725

HAL HCD Generic Driver
__HAL_HCD_UNMASK_HALT_HC_INT
__HAL_HCD_MASK_ACK_HC_INT
__HAL_HCD_UNMASK_ACK_HC_INT
HCD PHY Module
HCD_PHY_ULPI
HCD_PHY_EMBEDDED
HCD Speed
HCD_SPEED_HIGH
HCD_SPEED_LOW
HCD_SPEED_FULL

DocID025834 Rev 4

429/964

HAL I2C Generic Driver

UM1725

32

HAL I2C Generic Driver

32.1

I2C Firmware driver registers structures

32.1.1

I2C_InitTypeDef
Data Fields
uint32_t ClockSpeed
uint32_t DutyCycle
uint32_t OwnAddress1
uint32_t AddressingMode
uint32_t DualAddressMode
uint32_t OwnAddress2
uint32_t GeneralCallMode
uint32_t NoStretchMode

Field Documentation
uint32_t I2C_InitTypeDef::ClockSpeed
Specifies the clock frequency. This parameter must be set to a value lower than
400kHz
uint32_t I2C_InitTypeDef::DutyCycle
Specifies the I2C fast mode duty cycle. This parameter can be a value of
I2C_duty_cycle_in_fast_mode
uint32_t I2C_InitTypeDef::OwnAddress1
Specifies the first device own address. This parameter can be a 7-bit or 10-bit
address.
uint32_t I2C_InitTypeDef::AddressingMode
Specifies if 7-bit or 10-bit addressing mode is selected. This parameter can be a
value of I2C_addressing_mode
uint32_t I2C_InitTypeDef::DualAddressMode
Specifies if dual addressing mode is selected. This parameter can be a value of
I2C_dual_addressing_mode
uint32_t I2C_InitTypeDef::OwnAddress2
Specifies the second device own address if dual addressing mode is selected This
parameter can be a 7-bit address.
uint32_t I2C_InitTypeDef::GeneralCallMode
Specifies if general call mode is selected. This parameter can be a value of
I2C_general_call_addressing_mode
uint32_t I2C_InitTypeDef::NoStretchMode
Specifies if nostretch mode is selected. This parameter can be a value of
I2C_nostretch_mode

430/964

DocID025834 Rev 4

UM1725

32.1.2

HAL I2C Generic Driver

I2C_HandleTypeDef
Data Fields
I2C_TypeDef * Instance
I2C_InitTypeDef Init
uint8_t * pBuffPtr
uint16_t XferSize
__IO uint16_t XferCount
__IO uint32_t XferOptions
__IO uint32_t PreviousState
DMA_HandleTypeDef * hdmatx
DMA_HandleTypeDef * hdmarx
HAL_LockTypeDef Lock
__IO HAL_I2C_StateTypeDef State
__IO HAL_I2C_ModeTypeDef Mode
__IO uint32_t ErrorCode
__IO uint32_t Devaddress
__IO uint32_t Memaddress
__IO uint32_t MemaddSize
__IO uint32_t EventCount

Field Documentation
I2C_TypeDef* I2C_HandleTypeDef::Instance
I2C registers base address
I2C_InitTypeDef I2C_HandleTypeDef::Init
I2C communication parameters
uint8_t* I2C_HandleTypeDef::pBuffPtr
Pointer to I2C transfer buffer
uint16_t I2C_HandleTypeDef::XferSize
I2C transfer size
__IO uint16_t I2C_HandleTypeDef::XferCount
I2C transfer counter
__IO uint32_t I2C_HandleTypeDef::XferOptions
I2C transfer options
__IO uint32_t I2C_HandleTypeDef::PreviousState
I2C communication Previous state and mode context for internal usage
DMA_HandleTypeDef* I2C_HandleTypeDef::hdmatx
I2C Tx DMA handle parameters
DMA_HandleTypeDef* I2C_HandleTypeDef::hdmarx
I2C Rx DMA handle parameters
HAL_LockTypeDef I2C_HandleTypeDef::Lock
I2C locking object
__IO HAL_I2C_StateTypeDef I2C_HandleTypeDef::State
I2C communication state
__IO HAL_I2C_ModeTypeDef I2C_HandleTypeDef::Mode
I2C communication mode
__IO uint32_t I2C_HandleTypeDef::ErrorCode
I2C Error code
DocID025834 Rev 4

431/964

HAL I2C Generic Driver

UM1725

__IO uint32_t I2C_HandleTypeDef::Devaddress
I2C Target device address
__IO uint32_t I2C_HandleTypeDef::Memaddress
I2C Target memory address
__IO uint32_t I2C_HandleTypeDef::MemaddSize
I2C Target memory address size
__IO uint32_t I2C_HandleTypeDef::EventCount
I2C Event counter

32.2

I2C Firmware driver API description

32.2.1

How to use this driver
The I2C HAL driver can be used as follows:
1.
2.

3.

4.

5.
6.

Declare a I2C_HandleTypeDef handle structure, for example: I2C_HandleTypeDef
hi2c;
Initialize the I2C low level resources by implement the HAL_I2C_MspInit() API:
a.
Enable the I2Cx interface clock
b.
I2C pins configuration
Enable the clock for the I2C GPIOs
Configure I2C pins as alternate function open-drain
c.
NVIC configuration if you need to use interrupt process
Configure the I2Cx interrupt priority
Enable the NVIC I2C IRQ Channel
d.
DMA Configuration if you need to use DMA process
Declare a DMA_HandleTypeDef handle structure for the transmit or receive
stream
Enable the DMAx interface clock using
Configure the DMA handle parameters
Configure the DMA Tx or Rx Stream
Associate the initialized DMA handle to the hi2c DMA Tx or Rx handle
Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Tx or Rx Stream
Configure the Communication Speed, Duty cycle, Addressing mode, Own Address1,
Dual Addressing mode, Own Address2, General call and Nostretch mode in the hi2c
Init structure.
Initialize the I2C registers by calling the HAL_I2C_Init(), configures also the low level
Hardware (GPIO, CLOCK, NVIC...etc) by calling the customized
HAL_I2C_MspInit(&hi2c) API.
To check if target device is ready for communication, use the function
HAL_I2C_IsDeviceReady()
For I2C IO and IO MEM operations, three operation modes are available within this
driver :

Polling mode IO operation
Transmit in master mode an amount of data in blocking mode using
HAL_I2C_Master_Transmit()
Receive in master mode an amount of data in blocking mode using
HAL_I2C_Master_Receive()
Transmit in slave mode an amount of data in blocking mode using
HAL_I2C_Slave_Transmit()

432/964

DocID025834 Rev 4

UM1725

HAL I2C Generic Driver
Receive in slave mode an amount of data in blocking mode using
HAL_I2C_Slave_Receive()

Polling mode IO MEM operation
Write an amount of data in blocking mode to a specific memory address using
HAL_I2C_Mem_Write()
Read an amount of data in blocking mode from a specific memory address using
HAL_I2C_Mem_Read()

Interrupt mode IO operation
Transmit in master mode an amount of data in non blocking mode using
HAL_I2C_Master_Transmit_IT()
At transmission end of transfer HAL_I2C_MasterTxCpltCallback is executed and user
can add his own code by customization of function pointer
HAL_I2C_MasterTxCpltCallback
Receive in master mode an amount of data in non blocking mode using
HAL_I2C_Master_Receive_IT()
At reception end of transfer HAL_I2C_MasterRxCpltCallback is executed and user
can add his own code by customization of function pointer
HAL_I2C_MasterRxCpltCallback
Transmit in slave mode an amount of data in non blocking mode using
HAL_I2C_Slave_Transmit_IT()
At transmission end of transfer HAL_I2C_SlaveTxCpltCallback is executed and user
can add his own code by customization of function pointer
HAL_I2C_SlaveTxCpltCallback
Receive in slave mode an amount of data in non blocking mode using
HAL_I2C_Slave_Receive_IT()
At reception end of transfer HAL_I2C_SlaveRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveRxCpltCallback
In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback

Interrupt mode IO sequential operation
These interfaces allow to manage a sequential transfer with a repeated start condition
when a direction change during transfer
A specific option manage the different steps of a sequential transfer
Differents steps option I2C_XferOptions_definition are listed below :
I2C_FIRST_AND_LAST_FRAME: No sequential usage, functionnal is same as
associated interfaces in no sequential mode
I2C_FIRST_FRAME: Sequential usage, this option allow to manage a start
condition with data to transfer without a final stop condition
I2C_NEXT_FRAME: Sequential usage, this option allow to manage a restart
condition with new data to transfer if the direction change or manage only the
new data to transfer if no direction change and without a final stop condition in
both cases
I2C_LAST_FRAME: Sequential usage, this option allow to manage a restart
condition with new data to transfer if the direction change or manage only the
new data to transfer if no direction change and with a final stop condition in both
cases
DocID025834 Rev 4

433/964

HAL I2C Generic Driver

UM1725

Sequential transmit in master I2C mode an amount of data in non-blocking mode
using HAL_I2C_Master_Sequential_Transmit_IT()
At transmission end of current frame transfer, HAL_I2C_MasterTxCpltCallback()
is executed and user can add his own code by customization of function pointer
HAL_I2C_MasterTxCpltCallback()
Sequential receive in master I2C mode an amount of data in non-blocking mode
using HAL_I2C_Master_Sequential_Receive_IT()
At reception end of current frame transfer, HAL_I2C_MasterRxCpltCallback() is
executed and user can add his own code by customization of function pointer
HAL_I2C_MasterRxCpltCallback()
Abort a master I2C process communication with Interrupt using
HAL_I2C_Master_Abort_IT()
The associated previous transfer callback is called at the end of abort process
mean HAL_I2C_MasterTxCpltCallback() in case of previous state was master
transmit
mean HAL_I2c_MasterRxCpltCallback() in case of previous state was master
receive
Enable/disable the Address listen mode in slave I2C mode using
HAL_I2C_EnableListen_IT() HAL_I2C_DisableListen_IT()
When address slave I2C match, HAL_I2C_AddrCallback() is executed and user
can add his own code to check the Address Match Code and the transmission
direction request by master (Write/Read).
At Listen mode end HAL_I2C_ListenCpltCallback() is executed and user can add
his own code by customization of function pointer HAL_I2C_ListenCpltCallback()
Sequential transmit in slave I2C mode an amount of data in non-blocking mode using
HAL_I2C_Slave_Sequential_Transmit_IT()
At transmission end of current frame transfer, HAL_I2C_SlaveTxCpltCallback()
is executed and user can add his own code by customization of function pointer
HAL_I2C_SlaveTxCpltCallback()
Sequential receive in slave I2C mode an amount of data in non-blocking mode using
HAL_I2C_Slave_Sequential_Receive_IT()
At reception end of current frame transfer, HAL_I2C_SlaveRxCpltCallback() is
executed and user can add his own code by customization of function pointer
HAL_I2C_SlaveRxCpltCallback()

Interrupt mode IO MEM operation
Write an amount of data in no-blocking mode with Interrupt to a specific memory
address using HAL_I2C_Mem_Write_IT()
At MEM end of write transfer HAL_I2C_MemTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemTxCpltCallback
Read an amount of data in no-blocking mode with Interrupt from a specific memory
address using HAL_I2C_Mem_Read_IT()
At MEM end of read transfer HAL_I2C_MemRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemRxCpltCallback
In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback

DMA mode IO operation
Transmit in master mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Master_Transmit_DMA()
At transmission end of transfer HAL_I2C_MasterTxCpltCallback is executed and user
can add his own code by customization of function pointer
HAL_I2C_MasterTxCpltCallback
434/964

DocID025834 Rev 4

UM1725

HAL I2C Generic Driver
Receive in master mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Master_Receive_DMA()
At reception end of transfer HAL_I2C_MasterRxCpltCallback is executed and user
can add his own code by customization of function pointer
HAL_I2C_MasterRxCpltCallback
Transmit in slave mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Slave_Transmit_DMA()
At transmission end of transfer HAL_I2C_SlaveTxCpltCallback is executed and user
can add his own code by customization of function pointer
HAL_I2C_SlaveTxCpltCallback
Receive in slave mode an amount of data in non blocking mode (DMA) using
HAL_I2C_Slave_Receive_DMA()
At reception end of transfer HAL_I2C_SlaveRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_SlaveRxCpltCallback
In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback

DMA mode IO MEM operation
Write an amount of data in no-blocking mode with DMA to a specific memory address
using HAL_I2C_Mem_Write_DMA()
At MEM end of write transfer HAL_I2C_MemTxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemTxCpltCallback
Read an amount of data in no-blocking mode with DMA from a specific memory
address using HAL_I2C_Mem_Read_DMA()
At MEM end of read transfer HAL_I2C_MemRxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2C_MemRxCpltCallback
In case of transfer Error, HAL_I2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2C_ErrorCallback

I2C HAL driver macros list
Below the list of most used macros in I2C HAL driver.
__HAL_I2C_ENABLE: Enable the I2C peripheral
__HAL_I2C_DISABLE: Disable the I2C peripheral
__HAL_I2C_GET_FLAG: Checks whether the specified I2C flag is set or not
__HAL_I2C_CLEAR_FLAG: Clear the specified I2C pending flag
__HAL_I2C_ENABLE_IT: Enable the specified I2C interrupt
__HAL_I2C_DISABLE_IT: Disable the specified I2C interrupt
You can refer to the I2C HAL driver header file for more useful macros

32.2.2

Initialization and de-initialization functions
This subsection provides a set of functions allowing to initialize and de-initialize the I2Cx
peripheral:
User must Implement HAL_I2C_MspInit() function in which he configures all related
peripherals resources (CLOCK, GPIO, DMA, IT and NVIC).

DocID025834 Rev 4

435/964

HAL I2C Generic Driver

UM1725

Call the function HAL_I2C_Init() to configure the selected device with the selected
configuration:
Communication Speed
Duty cycle
Addressing mode
Own Address 1
Dual Addressing mode
Own Address 2
General call mode
Nostretch mode
Call the function HAL_I2C_DeInit() to restore the default configuration of the selected
I2Cx peripheral.
This section contains the following APIs:
HAL_I2C_Init()
HAL_I2C_DeInit()
HAL_I2C_MspInit()
HAL_I2C_MspDeInit()

32.2.3

IO operation functions
This subsection provides a set of functions allowing to manage the I2C data transfers.
1.

2.

3.

4.

436/964

There are two modes of transfer:
Blocking mode : The communication is performed in the polling mode. The
status of all data processing is returned by the same function after finishing
transfer.
No-Blocking mode : The communication is performed using Interrupts or DMA.
These functions return the status of the transfer startup. The end of the data
processing will be indicated through the dedicated I2C IRQ when using Interrupt
mode or the DMA IRQ when using DMA mode.
Blocking mode functions are :
HAL_I2C_Master_Transmit()
HAL_I2C_Master_Receive()
HAL_I2C_Slave_Transmit()
HAL_I2C_Slave_Receive()
HAL_I2C_Mem_Write()
HAL_I2C_Mem_Read()
HAL_I2C_IsDeviceReady()
No-Blocking mode functions with Interrupt are :
HAL_I2C_Master_Transmit_IT()
HAL_I2C_Master_Receive_IT()
HAL_I2C_Slave_Transmit_IT()
HAL_I2C_Slave_Receive_IT()
HAL_I2C_Master_Sequential_Transmit_IT()
HAL_I2C_Master_Sequential_Receive_IT()
HAL_I2C_Slave_Sequential_Transmit_IT()
HAL_I2C_Slave_Sequential_Receive_IT()
HAL_I2C_Mem_Write_IT()
HAL_I2C_Mem_Read_IT()
No-Blocking mode functions with DMA are :
HAL_I2C_Master_Transmit_DMA()
HAL_I2C_Master_Receive_DMA()
HAL_I2C_Slave_Transmit_DMA()
DocID025834 Rev 4

UM1725

HAL I2C Generic Driver

5.

HAL_I2C_Slave_Receive_DMA()
HAL_I2C_Mem_Write_DMA()
HAL_I2C_Mem_Read_DMA()
A set of Transfer Complete Callbacks are provided in non Blocking mode:
HAL_I2C_MemTxCpltCallback()
HAL_I2C_MemRxCpltCallback()
HAL_I2C_MasterTxCpltCallback()
HAL_I2C_MasterRxCpltCallback()
HAL_I2C_SlaveTxCpltCallback()
HAL_I2C_SlaveRxCpltCallback()
HAL_I2C_ErrorCallback()
HAL_I2C_AbortCpltCallback()

This section contains the following APIs:
HAL_I2C_Master_Transmit()
HAL_I2C_Master_Receive()
HAL_I2C_Slave_Transmit()
HAL_I2C_Slave_Receive()
HAL_I2C_Master_Transmit_IT()
HAL_I2C_Master_Receive_IT()
HAL_I2C_Master_Sequential_Transmit_IT()
HAL_I2C_Master_Sequential_Receive_IT()
HAL_I2C_Slave_Transmit_IT()
HAL_I2C_Slave_Receive_IT()
HAL_I2C_Slave_Sequential_Transmit_IT()
HAL_I2C_Slave_Sequential_Receive_IT()
HAL_I2C_EnableListen_IT()
HAL_I2C_DisableListen_IT()
HAL_I2C_Master_Transmit_DMA()
HAL_I2C_Master_Receive_DMA()
HAL_I2C_Master_Abort_IT()
HAL_I2C_Slave_Transmit_DMA()
HAL_I2C_Slave_Receive_DMA()
HAL_I2C_Mem_Write()
HAL_I2C_Mem_Read()
HAL_I2C_Mem_Write_IT()
HAL_I2C_Mem_Read_IT()
HAL_I2C_Mem_Write_DMA()
HAL_I2C_Mem_Read_DMA()
HAL_I2C_IsDeviceReady()
HAL_I2C_EV_IRQHandler()
HAL_I2C_ER_IRQHandler()
HAL_I2C_MasterTxCpltCallback()
HAL_I2C_MasterRxCpltCallback()
HAL_I2C_SlaveTxCpltCallback()
HAL_I2C_SlaveRxCpltCallback()
HAL_I2C_AddrCallback()
HAL_I2C_ListenCpltCallback()
HAL_I2C_MemTxCpltCallback()
HAL_I2C_MemRxCpltCallback()
HAL_I2C_ErrorCallback()
HAL_I2C_AbortCpltCallback()
DocID025834 Rev 4

437/964

HAL I2C Generic Driver

32.2.4

UM1725

Peripheral State, Mode and Errors functions
This subsection permits to get in run-time the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_I2C_GetState()
HAL_I2C_GetMode()
HAL_I2C_GetError()

32.2.5

Detailed description of functions
HAL_I2C_Init
Function Name

HAL_StatusTypeDef HAL_I2C_Init (I2C_HandleTypeDef * hi2c)

Function Description

Initializes the I2C according to the specified parameters in the
I2C_InitTypeDef and create the associated handle.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

HAL: status

HAL_I2C_DeInit
Function Name

HAL_StatusTypeDef HAL_I2C_DeInit (I2C_HandleTypeDef *
hi2c)

Function Description

DeInitializes the I2C peripheral.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

HAL: status

HAL_I2C_MspInit
Function Name

void HAL_I2C_MspInit (I2C_HandleTypeDef * hi2c)

Function Description

I2C MSP Init.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

None

HAL_I2C_MspDeInit

438/964

Function Name

void HAL_I2C_MspDeInit (I2C_HandleTypeDef * hi2c)

Function Description

I2C MSP DeInit.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

None

DocID025834 Rev 4

UM1725

HAL I2C Generic Driver

HAL_I2C_Master_Transmit
Function Name

HAL_StatusTypeDef HAL_I2C_Master_Transmit
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t *
pData, uint16_t Size, uint32_t Timeout)

Function Description

Transmits in master mode an amount of data in blocking mode.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_I2C_Master_Receive
Function Name

HAL_StatusTypeDef HAL_I2C_Master_Receive
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t *
pData, uint16_t Size, uint32_t Timeout)

Function Description

Receives in master mode an amount of data in blocking mode.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_I2C_Slave_Transmit
Function Name

HAL_StatusTypeDef HAL_I2C_Slave_Transmit
(I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size,
uint32_t Timeout)

Function Description

Transmits in slave mode an amount of data in blocking mode.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

DocID025834 Rev 4

439/964

HAL I2C Generic Driver

UM1725

HAL_I2C_Slave_Receive
Function Name

HAL_StatusTypeDef HAL_I2C_Slave_Receive
(I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size,
uint32_t Timeout)

Function Description

Receive in slave mode an amount of data in blocking mode.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_I2C_Mem_Write
Function Name

HAL_StatusTypeDef HAL_I2C_Mem_Write
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint16_t
MemAddress, uint16_t MemAddSize, uint8_t * pData, uint16_t
Size, uint32_t Timeout)

Function Description

Write an amount of data in blocking mode to a specific memory
address.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_I2C_Mem_Read

440/964

Function Name

HAL_StatusTypeDef HAL_I2C_Mem_Read
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint16_t
MemAddress, uint16_t MemAddSize, uint8_t * pData, uint16_t
Size, uint32_t Timeout)

Function Description

Read an amount of data in blocking mode from a specific memory
address.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL I2C Generic Driver

HAL_I2C_IsDeviceReady
Function Name

HAL_StatusTypeDef HAL_I2C_IsDeviceReady
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint32_t
Trials, uint32_t Timeout)

Function Description

Checks if target device is ready for communication.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address
Trials: Number of trials
Timeout: Timeout duration

Return values

HAL: status

Notes

This function is used with Memory devices

HAL_I2C_Master_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_I2C_Master_Transmit_IT
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t *
pData, uint16_t Size)

Function Description

Transmit in master mode an amount of data in no-blocking mode
with Interrupt.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_I2C_Master_Receive_IT
Function Name

HAL_StatusTypeDef HAL_I2C_Master_Receive_IT
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t *
pData, uint16_t Size)

Function Description

Receive in master mode an amount of data in no-blocking mode
with Interrupt.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

DocID025834 Rev 4

441/964

HAL I2C Generic Driver

UM1725

HAL_I2C_Slave_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_I2C_Slave_Transmit_IT
(I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size)

Function Description

Transmit in slave mode an amount of data in no-blocking mode
with Interrupt.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_I2C_Slave_Receive_IT
Function Name

HAL_StatusTypeDef HAL_I2C_Slave_Receive_IT
(I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size)

Function Description

Receive in slave mode an amount of data in no-blocking mode
with Interrupt.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_I2C_Mem_Write_IT
Function Name

HAL_StatusTypeDef HAL_I2C_Mem_Write_IT
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint16_t
MemAddress, uint16_t MemAddSize, uint8_t * pData, uint16_t
Size)

Function Description

Write an amount of data in no-blocking mode with Interrupt to a
specific memory address.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_I2C_Mem_Read_IT

442/964

Function Name

HAL_StatusTypeDef HAL_I2C_Mem_Read_IT
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint16_t
MemAddress, uint16_t MemAddSize, uint8_t * pData, uint16_t
Size)

Function Description

Read an amount of data in no-blocking mode with Interrupt from a
specific memory address.
DocID025834 Rev 4

UM1725

HAL I2C Generic Driver
Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_I2C_Master_Sequential_Transmit_IT
Function Name

HAL_StatusTypeDef
HAL_I2C_Master_Sequential_Transmit_IT
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t *
pData, uint16_t Size, uint32_t XferOptions)

Function Description

Sequential transmit in master mode an amount of data in noblocking mode with Interrupt.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent
XferOptions: Options of Transfer, value of I2C XferOptions
definition

Return values

HAL: status

Notes

This interface allow to manage repeated start condition when
a direction change during transfer

HAL_I2C_Master_Sequential_Receive_IT
Function Name

HAL_StatusTypeDef HAL_I2C_Master_Sequential_Receive_IT
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t *
pData, uint16_t Size, uint32_t XferOptions)

Function Description

Sequential receive in master mode an amount of data in noblocking mode with Interrupt.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent
XferOptions: Options of Transfer, value of I2C XferOptions
definition

Return values

HAL: status

Notes

This interface allow to manage repeated start condition when
a direction change during transfer
DocID025834 Rev 4

443/964

HAL I2C Generic Driver

UM1725

HAL_I2C_Slave_Sequential_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_I2C_Slave_Sequential_Transmit_IT
(I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size,
uint32_t XferOptions)

Function Description

Sequential transmit in slave mode an amount of data in noblocking mode with Interrupt.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
pData: Pointer to data buffer
Size: Amount of data to be sent
XferOptions: Options of Transfer, value of I2C XferOptions
definition

Return values

HAL: status

Notes

This interface allow to manage repeated start condition when
a direction change during transfer

HAL_I2C_Slave_Sequential_Receive_IT
Function Name

HAL_StatusTypeDef HAL_I2C_Slave_Sequential_Receive_IT
(I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size,
uint32_t XferOptions)

Function Description

Sequential receive in slave mode an amount of data in no-blocking
mode with Interrupt.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
pData: Pointer to data buffer
Size: Amount of data to be sent
XferOptions: Options of Transfer, value of I2C XferOptions
definition

Return values

HAL: status

Notes

This interface allow to manage repeated start condition when
a direction change during transfer

HAL_I2C_Master_Abort_IT

444/964

Function Name

HAL_StatusTypeDef HAL_I2C_Master_Abort_IT
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress)

Function Description

Abort a master I2C process communication with Interrupt.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for the specified I2C.
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface

Return values

HAL: status

Notes

This abort can be called only if state is ready

DocID025834 Rev 4

UM1725

HAL I2C Generic Driver

HAL_I2C_EnableListen_IT
Function Name

HAL_StatusTypeDef HAL_I2C_EnableListen_IT
(I2C_HandleTypeDef * hi2c)

Function Description

Enable the Address listen mode with Interrupt.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for the specified I2C.

Return values

HAL: status

HAL_I2C_DisableListen_IT
Function Name

HAL_StatusTypeDef HAL_I2C_DisableListen_IT
(I2C_HandleTypeDef * hi2c)

Function Description

Disable the Address listen mode with Interrupt.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for the specified I2C.

Return values

HAL: status

HAL_I2C_Master_Transmit_DMA
Function Name

HAL_StatusTypeDef HAL_I2C_Master_Transmit_DMA
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t *
pData, uint16_t Size)

Function Description

Transmit in master mode an amount of data in no-blocking mode
with DMA.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_I2C_Master_Receive_DMA
Function Name

HAL_StatusTypeDef HAL_I2C_Master_Receive_DMA
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t *
pData, uint16_t Size)

Function Description

Receive in master mode an amount of data in no-blocking mode
with DMA.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address: The device 7 bits
address value in datasheet must be shift at right before call
interface
pData: Pointer to data buffer
Size: Amount of data to be sent

DocID025834 Rev 4

445/964

HAL I2C Generic Driver
Return values

UM1725
HAL: status

HAL_I2C_Slave_Transmit_DMA
Function Name

HAL_StatusTypeDef HAL_I2C_Slave_Transmit_DMA
(I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size)

Function Description

Transmit in slave mode an amount of data in no-blocking mode
with DMA.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_I2C_Slave_Receive_DMA
Function Name

HAL_StatusTypeDef HAL_I2C_Slave_Receive_DMA
(I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size)

Function Description

Receive in slave mode an amount of data in no-blocking mode
with DMA.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_I2C_Mem_Write_DMA
Function Name

HAL_StatusTypeDef HAL_I2C_Mem_Write_DMA
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint16_t
MemAddress, uint16_t MemAddSize, uint8_t * pData, uint16_t
Size)

Function Description

Write an amount of data in no-blocking mode with DMA to a
specific memory address.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_I2C_Mem_Read_DMA
Function Name

446/964

HAL_StatusTypeDef HAL_I2C_Mem_Read_DMA
(I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint16_t
MemAddress, uint16_t MemAddSize, uint8_t * pData, uint16_t
Size)
DocID025834 Rev 4

UM1725
Function Description

HAL I2C Generic Driver
Reads an amount of data in no-blocking mode with DMA from a
specific memory address.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module
DevAddress: Target device address
MemAddress: Internal memory address
MemAddSize: Size of internal memory address
pData: Pointer to data buffer
Size: Amount of data to be read

Return values

HAL: status

HAL_I2C_EV_IRQHandler
Function Name

void HAL_I2C_EV_IRQHandler (I2C_HandleTypeDef * hi2c)

Function Description

This function handles I2C event interrupt request.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

HAL: status

HAL_I2C_ER_IRQHandler
Function Name

void HAL_I2C_ER_IRQHandler (I2C_HandleTypeDef * hi2c)

Function Description

This function handles I2C error interrupt request.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

HAL: status

HAL_I2C_MasterTxCpltCallback
Function Name

void HAL_I2C_MasterTxCpltCallback (I2C_HandleTypeDef *
hi2c)

Function Description

Master Tx Transfer completed callbacks.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

None

HAL_I2C_MasterRxCpltCallback
Function Name

void HAL_I2C_MasterRxCpltCallback (I2C_HandleTypeDef *
hi2c)

Function Description

Master Rx Transfer completed callbacks.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

None

DocID025834 Rev 4

447/964

HAL I2C Generic Driver

UM1725

HAL_I2C_SlaveTxCpltCallback
Function Name

void HAL_I2C_SlaveTxCpltCallback (I2C_HandleTypeDef *
hi2c)

Function Description

Slave Tx Transfer completed callbacks.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

None

HAL_I2C_SlaveRxCpltCallback
Function Name

void HAL_I2C_SlaveRxCpltCallback (I2C_HandleTypeDef *
hi2c)

Function Description

Slave Rx Transfer completed callbacks.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

None

HAL_I2C_AddrCallback
Function Name

void HAL_I2C_AddrCallback (I2C_HandleTypeDef * hi2c,
uint8_t TransferDirection, uint16_t AddrMatchCode)

Function Description

Slave Address Match callback.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for the specified I2C.
TransferDirection: Master request Transfer Direction
(Write/Read), value of I2C XferOptions definition
AddrMatchCode: Address Match Code

Return values

None

HAL_I2C_ListenCpltCallback
Function Name

void HAL_I2C_ListenCpltCallback (I2C_HandleTypeDef * hi2c)

Function Description

Listen Complete callback.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for the specified I2C.

Return values

None

HAL_I2C_MemTxCpltCallback

448/964

Function Name

void HAL_I2C_MemTxCpltCallback (I2C_HandleTypeDef *
hi2c)

Function Description

Memory Tx Transfer completed callbacks.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

None

DocID025834 Rev 4

UM1725

HAL I2C Generic Driver

HAL_I2C_MemRxCpltCallback
Function Name

void HAL_I2C_MemRxCpltCallback (I2C_HandleTypeDef *
hi2c)

Function Description

Memory Rx Transfer completed callbacks.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

None

HAL_I2C_ErrorCallback
Function Name

void HAL_I2C_ErrorCallback (I2C_HandleTypeDef * hi2c)

Function Description

I2C error callbacks.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

None

HAL_I2C_AbortCpltCallback
Function Name

void HAL_I2C_AbortCpltCallback (I2C_HandleTypeDef * hi2c)

Function Description

I2C abort callback.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for the specified I2C.

Return values

None

HAL_I2C_GetState
Function Name

HAL_I2C_StateTypeDef HAL_I2C_GetState
(I2C_HandleTypeDef * hi2c)

Function Description

Returns the I2C state.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

HAL: state

HAL_I2C_GetMode
Function Name

HAL_I2C_ModeTypeDef HAL_I2C_GetMode
(I2C_HandleTypeDef * hi2c)

Function Description

Returns the I2C Master, Slave, Memory or no mode.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for I2C module

Return values

HAL: mode

DocID025834 Rev 4

449/964

HAL I2C Generic Driver

UM1725

HAL_I2C_GetError
Function Name

uint32_t HAL_I2C_GetError (I2C_HandleTypeDef * hi2c)

Function Description

Return the I2C error code.

Parameters

hi2c: Pointer to a I2C_HandleTypeDef structure that contains
the configuration information for the specified I2C.

Return values

I2C: Error Code

32.3

I2C Firmware driver defines

32.3.1

I2C
I2C addressing mode
I2C_ADDRESSINGMODE_7BIT
I2C_ADDRESSINGMODE_10BIT
I2C dual addressing mode
I2C_DUALADDRESS_DISABLE
I2C_DUALADDRESS_ENABLE
I2C duty cycle in fast mode
I2C_DUTYCYCLE_2
I2C_DUTYCYCLE_16_9
I2C Error Code
HAL_I2C_ERROR_NONE

No error

HAL_I2C_ERROR_BERR

BERR error

HAL_I2C_ERROR_ARLO

ARLO error

HAL_I2C_ERROR_AF

AF error

HAL_I2C_ERROR_OVR

OVR error

HAL_I2C_ERROR_DMA

DMA transfer error

HAL_I2C_ERROR_TIMEOUT

Timeout Error

I2C Exported Macros
__HAL_I2C_RESET_HANDLE_STATE

Description:
Reset I2C handle state.
Parameters:
__HANDLE__: specifies the I2C Handle.
This parameter can be I2C where x: 1, 2, or
3 to select the I2C peripheral.
Return value:
None

__HAL_I2C_ENABLE_IT

Description:
Enable or disable the specified I2C

450/964

DocID025834 Rev 4

UM1725

HAL I2C Generic Driver
interrupts.
Parameters:
__HANDLE__: specifies the I2C Handle.
This parameter can be I2C where x: 1, 2, or
3 to select the I2C peripheral.
__INTERRUPT__: specifies the interrupt
source to enable or disable. This parameter
can be one of the following values:
I2C_IT_BUF: Buffer interrupt enable
I2C_IT_EVT: Event interrupt enable
I2C_IT_ERR: Error interrupt enable
Return value:
None
__HAL_I2C_DISABLE_IT
__HAL_I2C_GET_IT_SOURCE

Description:
Checks if the specified I2C interrupt source
is enabled or disabled.
Parameters:
__HANDLE__: specifies the I2C Handle.
This parameter can be I2C where x: 1, 2, or
3 to select the I2C peripheral.
__INTERRUPT__: specifies the I2C
interrupt source to check. This parameter
can be one of the following values:
I2C_IT_BUF: Buffer interrupt enable
I2C_IT_EVT: Event interrupt enable
I2C_IT_ERR: Error interrupt enable
Return value:
The: new state of __INTERRUPT__ (TRUE
or FALSE).

__HAL_I2C_GET_FLAG

Description:
Checks whether the specified I2C flag is set
or not.
Parameters:
__HANDLE__: specifies the I2C Handle.
This parameter can be I2C where x: 1, 2, or
3 to select the I2C peripheral.
__FLAG__: specifies the flag to check. This
parameter can be one of the following
values:
I2C_FLAG_SMBALERT: SMBus Alert
flag
I2C_FLAG_TIMEOUT: Timeout or Tlow
error flag
I2C_FLAG_PECERR: PEC error in
reception flag
DocID025834 Rev 4

451/964

HAL I2C Generic Driver

UM1725
I2C_FLAG_OVR: Overrun/Underrun
flag
I2C_FLAG_AF: Acknowledge failure
flag
I2C_FLAG_ARLO: Arbitration lost flag
I2C_FLAG_BERR: Bus error flag
I2C_FLAG_TXE: Data register empty
flag
I2C_FLAG_RXNE: Data register not
empty flag
I2C_FLAG_STOPF: Stop detection flag
I2C_FLAG_ADD10: 10-bit header sent
flag
I2C_FLAG_BTF: Byte transfer finished
flag
I2C_FLAG_ADDR: Address sent flag
Address matched flag
I2C_FLAG_SB: Start bit flag
I2C_FLAG_DUALF: Dual flag
I2C_FLAG_SMBHOST: SMBus host
header
I2C_FLAG_SMBDEFAULT: SMBus
default header
I2C_FLAG_GENCALL: General call
header flag
I2C_FLAG_TRA: Transmitter/Receiver
flag
I2C_FLAG_BUSY: Bus busy flag
I2C_FLAG_MSL: Master/Slave flag
Return value:
The: new state of __FLAG__ (TRUE or
FALSE).

__HAL_I2C_CLEAR_FLAG

Description:
Clears the I2C pending flags which are
cleared by writing 0 in a specific bit.
Parameters:
__HANDLE__: specifies the I2C Handle.
This parameter can be I2C where x: 1, 2, or
3 to select the I2C peripheral.
__FLAG__: specifies the flag to clear. This
parameter can be any combination of the
following values:
I2C_FLAG_SMBALERT: SMBus Alert
flag
I2C_FLAG_TIMEOUT: Timeout or Tlow
error flag
I2C_FLAG_PECERR: PEC error in
reception flag
I2C_FLAG_OVR: Overrun/Underrun
flag (Slave mode)
I2C_FLAG_AF: Acknowledge failure

452/964

DocID025834 Rev 4

UM1725

HAL I2C Generic Driver
flag
I2C_FLAG_ARLO: Arbitration lost flag
(Master mode)
I2C_FLAG_BERR: Bus error flag
Return value:
None
__HAL_I2C_CLEAR_ADDRFLAG

Description:
Clears the I2C ADDR pending flag.
Parameters:
__HANDLE__: specifies the I2C Handle.
This parameter can be I2C where x: 1, 2, or
3 to select the I2C peripheral.
Return value:
None

__HAL_I2C_CLEAR_STOPFLAG

Description:
Clears the I2C STOPF pending flag.
Parameters:
__HANDLE__: specifies the I2C Handle.
This parameter can be I2C where x: 1, 2, or
3 to select the I2C peripheral.
Return value:
None

__HAL_I2C_ENABLE

Description:
Enable the I2C peripheral.
Parameters:
__HANDLE__: specifies the I2C Handle.
This parameter can be I2Cx where x: 1 or 2
to select the I2C peripheral.
Return value:
None

__HAL_I2C_DISABLE

Description:
Disable the I2C peripheral.
Parameters:
__HANDLE__: specifies the I2C Handle.
This parameter can be I2Cx where x: 1 or 2
to select the I2C peripheral.
Return value:
None

I2C Flag definition

DocID025834 Rev 4

453/964

HAL I2C Generic Driver
I2C_FLAG_SMBALERT

UM1725

I2C_FLAG_TIMEOUT
I2C_FLAG_PECERR
I2C_FLAG_OVR
I2C_FLAG_AF
I2C_FLAG_ARLO
I2C_FLAG_BERR
I2C_FLAG_TXE
I2C_FLAG_RXNE
I2C_FLAG_STOPF
I2C_FLAG_ADD10
I2C_FLAG_BTF
I2C_FLAG_ADDR
I2C_FLAG_SB
I2C_FLAG_DUALF
I2C_FLAG_SMBHOST
I2C_FLAG_SMBDEFAULT
I2C_FLAG_GENCALL
I2C_FLAG_TRA
I2C_FLAG_BUSY
I2C_FLAG_MSL
I2C general call addressing mode
I2C_GENERALCALL_DISABLE
I2C_GENERALCALL_ENABLE
I2C Interrupt configuration definition
I2C_IT_BUF
I2C_IT_EVT
I2C_IT_ERR
I2C Private macros to check input parameters
IS_I2C_DUTY_CYCLE
IS_I2C_ADDRESSING_MODE
IS_I2C_DUAL_ADDRESS
IS_I2C_GENERAL_CALL
IS_I2C_NO_STRETCH
IS_I2C_MEMADD_SIZE
IS_I2C_CLOCK_SPEED

454/964

DocID025834 Rev 4

UM1725

HAL I2C Generic Driver
IS_I2C_OWN_ADDRESS1
IS_I2C_OWN_ADDRESS2
IS_I2C_TRANSFER_OPTIONS_REQUEST
I2C Memory Address Size
I2C_MEMADD_SIZE_8BIT
I2C_MEMADD_SIZE_16BIT
I2C nostretch mode
I2C_NOSTRETCH_DISABLE
I2C_NOSTRETCH_ENABLE
I2C XferDirection definition
I2C_DIRECTION_RECEIVE
I2C_DIRECTION_TRANSMIT
I2C XferOptions definition
I2C_FIRST_FRAME
I2C_NEXT_FRAME
I2C_FIRST_AND_LAST_FRAME
I2C_LAST_FRAME

DocID025834 Rev 4

455/964

HAL I2C Extension Driver

UM1725

33

HAL I2C Extension Driver

33.1

I2CEx Firmware driver API description

33.1.1

I2C peripheral extension features
Comparing to other previous devices, the I2C interface for STM32F427xx/437xx/
429xx/439xx devices contains the following additional features :
Possibility to disable or enable Analog Noise Filter
Use of a configured Digital Noise Filter

33.1.2

How to use this driver
This driver provides functions to configure Noise Filter
1.
2.

33.1.3

Configure I2C Analog noise filter using the function HAL_I2C_AnalogFilter_Config()
Configure I2C Digital noise filter using the function HAL_I2C_DigitalFilter_Config()

Extension features functions
This section provides functions allowing to:
Configure Noise Filters
This section contains the following APIs:
HAL_I2CEx_ConfigAnalogFilter()
HAL_I2CEx_ConfigDigitalFilter()

33.1.4

Detailed description of functions
HAL_I2CEx_ConfigAnalogFilter
Function Name

HAL_StatusTypeDef HAL_I2CEx_ConfigAnalogFilter
(I2C_HandleTypeDef * hi2c, uint32_t AnalogFilter)

Function Description

Configures I2C Analog noise filter.

Parameters

hi2c: pointer to a I2C_HandleTypeDef structure that contains
the configuration information for the specified I2Cx peripheral.
AnalogFilter: new state of the Analog filter.

Return values

HAL: status

HAL_I2CEx_ConfigDigitalFilter

456/964

Function Name

HAL_StatusTypeDef HAL_I2CEx_ConfigDigitalFilter
(I2C_HandleTypeDef * hi2c, uint32_t DigitalFilter)

Function Description

Configures I2C Digital noise filter.

Parameters

hi2c: pointer to a I2C_HandleTypeDef structure that contains
the configuration information for the specified I2Cx peripheral.
DigitalFilter: Coefficient of digital noise filter between 0x00
and 0x0F.

Return values

HAL: status
DocID025834 Rev 4

UM1725

HAL I2C Extension Driver

33.2

I2CEx Firmware driver defines

33.2.1

I2CEx
I2C Analog Filter
I2C_ANALOGFILTER_ENABLE
I2C_ANALOGFILTER_DISABLE

DocID025834 Rev 4

457/964

HAL I2S Generic Driver

UM1725

34

HAL I2S Generic Driver

34.1

I2S Firmware driver registers structures

34.1.1

I2S_InitTypeDef
Data Fields
uint32_t Mode
uint32_t Standard
uint32_t DataFormat
uint32_t MCLKOutput
uint32_t AudioFreq
uint32_t CPOL
uint32_t ClockSource
uint32_t FullDuplexMode

Field Documentation
uint32_t I2S_InitTypeDef::Mode
Specifies the I2S operating mode. This parameter can be a value of I2S_Mode
uint32_t I2S_InitTypeDef::Standard
Specifies the standard used for the I2S communication. This parameter can be a
value of I2S_Standard
uint32_t I2S_InitTypeDef::DataFormat
Specifies the data format for the I2S communication. This parameter can be a value
of I2S_Data_Format
uint32_t I2S_InitTypeDef::MCLKOutput
Specifies whether the I2S MCLK output is enabled or not. This parameter can be a
value of I2S_MCLK_Output
uint32_t I2S_InitTypeDef::AudioFreq
Specifies the frequency selected for the I2S communication. This parameter can be a
value of I2S_Audio_Frequency
uint32_t I2S_InitTypeDef::CPOL
Specifies the idle state of the I2S clock. This parameter can be a value of
I2S_Clock_Polarity
uint32_t I2S_InitTypeDef::ClockSource
Specifies the I2S Clock Source. This parameter can be a value of I2S_Clock_Source
uint32_t I2S_InitTypeDef::FullDuplexMode
Specifies the I2S FullDuplex mode. This parameter can be a value of
I2S_FullDuplex_Mode

34.1.2

I2S_HandleTypeDef
Data Fields
SPI_TypeDef * Instance
I2S_InitTypeDef Init

458/964

DocID025834 Rev 4

UM1725

HAL I2S Generic Driver
uint16_t * pTxBuffPtr
__IO uint16_t TxXferSize
__IO uint16_t TxXferCount
uint16_t * pRxBuffPtr
__IO uint16_t RxXferSize
__IO uint16_t RxXferCount
DMA_HandleTypeDef * hdmatx
DMA_HandleTypeDef * hdmarx
__IO HAL_LockTypeDef Lock
__IO HAL_I2S_StateTypeDef State
__IO uint32_t ErrorCode

Field Documentation
SPI_TypeDef* I2S_HandleTypeDef::Instance
I2S_InitTypeDef I2S_HandleTypeDef::Init
uint16_t* I2S_HandleTypeDef::pTxBuffPtr
__IO uint16_t I2S_HandleTypeDef::TxXferSize
__IO uint16_t I2S_HandleTypeDef::TxXferCount
uint16_t* I2S_HandleTypeDef::pRxBuffPtr
__IO uint16_t I2S_HandleTypeDef::RxXferSize
__IO uint16_t I2S_HandleTypeDef::RxXferCount
DMA_HandleTypeDef* I2S_HandleTypeDef::hdmatx
DMA_HandleTypeDef* I2S_HandleTypeDef::hdmarx
__IO HAL_LockTypeDef I2S_HandleTypeDef::Lock
__IO HAL_I2S_StateTypeDef I2S_HandleTypeDef::State
__IO uint32_t I2S_HandleTypeDef::ErrorCode

34.2

I2S Firmware driver API description

34.2.1

How to use this driver
The I2S HAL driver can be used as follow:
1.
2.

Declare a I2S_HandleTypeDef handle structure.
Initialize the I2S low level resources by implement the HAL_I2S_MspInit() API:
a.
Enable the SPIx interface clock.
b.
I2S pins configuration:
Enable the clock for the I2S GPIOs.
Configure these I2S pins as alternate function pull-up.
c.
NVIC configuration if you need to use interrupt process (HAL_I2S_Transmit_IT()
and HAL_I2S_Receive_IT() APIs).
Configure the I2Sx interrupt priority.
Enable the NVIC I2S IRQ handle.
d.
DMA Configuration if you need to use DMA process (HAL_I2S_Transmit_DMA()
and HAL_I2S_Receive_DMA() APIs:
Declare a DMA handle structure for the Tx/Rx stream.
Enable the DMAx interface clock.
Configure the declared DMA handle structure with the required Tx/Rx
parameters.
Configure the DMA Tx/Rx Stream.
Associate the initialized DMA handle to the I2S DMA Tx/Rx handle.
DocID025834 Rev 4

459/964

HAL I2S Generic Driver

3.

4.

UM1725

Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Tx/Rx Stream.
Program the Mode, Standard, Data Format, MCLK Output, Audio frequency and
Polarity using HAL_I2S_Init() function. The specific I2S interrupts (Transmission
complete interrupt, RXNE interrupt and Error Interrupts) will be managed using the
macros __I2S_ENABLE_IT() and __I2S_DISABLE_IT() inside the transmit and
receive process. Make sure that either: I2S PLL is configured or External clock
source is configured after setting correctly the define constant
EXTERNAL_CLOCK_VALUE in the stm32f4xx_hal_conf.h file.
Three operation modes are available within this driver :

Polling mode IO operation
Send an amount of data in blocking mode using HAL_I2S_Transmit()
Receive an amount of data in blocking mode using HAL_I2S_Receive()

Interrupt mode IO operation
Send an amount of data in non blocking mode using HAL_I2S_Transmit_IT()
At transmission end of half transfer HAL_I2S_TxHalfCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_I2S_TxHalfCpltCallback
At transmission end of transfer HAL_I2S_TxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2S_TxCpltCallback
Receive an amount of data in non blocking mode using HAL_I2S_Receive_IT()
At reception end of half transfer HAL_I2S_RxHalfCpltCallback is executed and user
can add his own code by customization of function pointer
HAL_I2S_RxHalfCpltCallback
At reception end of transfer HAL_I2S_RxCpltCallback is executed and user can add
his own code by customization of function pointer HAL_I2S_RxCpltCallback
In case of transfer Error, HAL_I2S_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2S_ErrorCallback

DMA mode IO operation
Send an amount of data in non blocking mode (DMA) using
HAL_I2S_Transmit_DMA()
At transmission end of half transfer HAL_I2S_TxHalfCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_I2S_TxHalfCpltCallback
At transmission end of transfer HAL_I2S_TxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2S_TxCpltCallback
Receive an amount of data in non blocking mode (DMA) using
HAL_I2S_Receive_DMA()
At reception end of half transfer HAL_I2S_RxHalfCpltCallback is executed and user
can add his own code by customization of function pointer
HAL_I2S_RxHalfCpltCallback
At reception end of transfer HAL_I2S_RxCpltCallback is executed and user can add
his own code by customization of function pointer HAL_I2S_RxCpltCallback
In case of transfer Error, HAL_I2S_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2S_ErrorCallback
460/964

DocID025834 Rev 4

UM1725

HAL I2S Generic Driver
Pause the DMA Transfer using HAL_I2S_DMAPause()
Resume the DMA Transfer using HAL_I2S_DMAResume()
Stop the DMA Transfer using HAL_I2S_DMAStop()

I2S HAL driver macros list
Below the list of most used macros in USART HAL driver.
__HAL_I2S_ENABLE: Enable the specified SPI peripheral (in I2S mode)
__HAL_I2S_DISABLE: Disable the specified SPI peripheral (in I2S mode)
__HAL_I2S_ENABLE_IT : Enable the specified I2S interrupts
__HAL_I2S_DISABLE_IT : Disable the specified I2S interrupts
__HAL_I2S_GET_FLAG: Check whether the specified I2S flag is set or not
You can refer to the I2S HAL driver header file for more useful macros

34.2.2

Initialization and de-initialization functions
This subsection provides a set of functions allowing to initialize and de-initialize the I2Sx
peripheral in simplex mode:
User must Implement HAL_I2S_MspInit() function in which he configures all related
peripherals resources (CLOCK, GPIO, DMA, IT and NVIC ).
Call the function HAL_I2S_Init() to configure the selected device with the selected
configuration:
Mode
Standard
Data Format
MCLK Output
Audio frequency
Polarity
Call the function HAL_I2S_DeInit() to restore the default configuration of the selected
I2Sx peripheral.
This section contains the following APIs:
HAL_I2S_Init()
HAL_I2S_DeInit()
HAL_I2S_MspInit()
HAL_I2S_MspDeInit()

34.2.3

IO operation functions
This subsection provides a set of functions allowing to manage the I2S data transfers.
1.

2.

There are two modes of transfer:
Blocking mode : The communication is performed in the polling mode. The
status of all data processing is returned by the same function after finishing
transfer.
No-Blocking mode : The communication is performed using Interrupts or DMA.
These functions return the status of the transfer startup. The end of the data
processing will be indicated through the dedicated I2S IRQ when using Interrupt
mode or the DMA IRQ when using DMA mode.
Blocking mode functions are :
DocID025834 Rev 4

461/964

HAL I2S Generic Driver

3.

4.

5.

UM1725

HAL_I2S_Transmit()
HAL_I2S_Receive()
No-Blocking mode functions with Interrupt are :
HAL_I2S_Transmit_IT()
HAL_I2S_Receive_IT()
No-Blocking mode functions with DMA are :
HAL_I2S_Transmit_DMA()
HAL_I2S_Receive_DMA()
A set of Transfer Complete Callbacks are provided in non Blocking mode:
HAL_I2S_TxCpltCallback()
HAL_I2S_RxCpltCallback()
HAL_I2S_ErrorCallback()

This section contains the following APIs:
HAL_I2S_Transmit()
HAL_I2S_Receive()
HAL_I2S_Transmit_IT()
HAL_I2S_Receive_IT()
HAL_I2S_Transmit_DMA()
HAL_I2S_Receive_DMA()
HAL_I2S_DMAPause()
HAL_I2S_DMAResume()
HAL_I2S_DMAStop()
HAL_I2S_IRQHandler()
HAL_I2S_TxHalfCpltCallback()
HAL_I2S_TxCpltCallback()
HAL_I2S_RxHalfCpltCallback()
HAL_I2S_RxCpltCallback()
HAL_I2S_ErrorCallback()
HAL_I2S_GetState()
HAL_I2S_GetError()

34.2.4

Peripheral State and Errors functions
This subsection permits to get in run-time the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_I2S_GetState()
HAL_I2S_GetError()

34.2.5

Detailed description of functions
HAL_I2S_Init

462/964

Function Name

HAL_StatusTypeDef HAL_I2S_Init (I2S_HandleTypeDef * hi2s)

Function Description

Initializes the I2S according to the specified parameters in the
I2S_InitTypeDef and create the associated handle.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL I2S Generic Driver

HAL_I2S_DeInit
Function Name

HAL_StatusTypeDef HAL_I2S_DeInit (I2S_HandleTypeDef *
hi2s)

Function Description

DeInitializes the I2S peripheral.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

HAL: status

HAL_I2S_MspInit
Function Name

void HAL_I2S_MspInit (I2S_HandleTypeDef * hi2s)

Function Description

I2S MSP Init.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

None

HAL_I2S_MspDeInit
Function Name

void HAL_I2S_MspDeInit (I2S_HandleTypeDef * hi2s)

Function Description

I2S MSP DeInit.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

None

HAL_I2S_Transmit
Function Name

HAL_StatusTypeDef HAL_I2S_Transmit (I2S_HandleTypeDef *
hi2s, uint16_t * pData, uint16_t Size, uint32_t Timeout)

Function Description

Transmit an amount of data in blocking mode.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module
pData: a 16-bit pointer to data buffer.
Size: number of data sample to be sent:
Timeout: Timeout duration

Return values

HAL: status

Notes

When a 16-bit data frame or a 16-bit data frame extended is
selected during the I2S configuration phase, the Size
parameter means the number of 16-bit data length in the
transaction and when a 24-bit data frame or a 32-bit data
frame is selected the Size parameter means the number of
16-bit data length.
The I2S is kept enabled at the end of transaction to avoid the
clock de-synchronization between Master and Slave(example:
audio streaming).

DocID025834 Rev 4

463/964

HAL I2S Generic Driver

UM1725

HAL_I2S_Receive
Function Name

HAL_StatusTypeDef HAL_I2S_Receive (I2S_HandleTypeDef *
hi2s, uint16_t * pData, uint16_t Size, uint32_t Timeout)

Function Description

Receive an amount of data in blocking mode.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module
pData: a 16-bit pointer to data buffer.
Size: number of data sample to be sent:
Timeout: Timeout duration

Return values

HAL: status

Notes

When a 16-bit data frame or a 16-bit data frame extended is
selected during the I2S configuration phase, the Size
parameter means the number of 16-bit data length in the
transaction and when a 24-bit data frame or a 32-bit data
frame is selected the Size parameter means the number of
16-bit data length.
The I2S is kept enabled at the end of transaction to avoid the
clock de-synchronization between Master and Slave(example:
audio streaming).
In I2S Master Receiver mode, just after enabling the
peripheral the clock will be generate in continuous way and as
the I2S is not disabled at the end of the I2S transaction.

HAL_I2S_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_I2S_Transmit_IT
(I2S_HandleTypeDef * hi2s, uint16_t * pData, uint16_t Size)

Function Description

Transmit an amount of data in non-blocking mode with Interrupt.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module
pData: a 16-bit pointer to data buffer.
Size: number of data sample to be sent:

Return values

HAL: status

Notes

When a 16-bit data frame or a 16-bit data frame extended is
selected during the I2S configuration phase, the Size
parameter means the number of 16-bit data length in the
transaction and when a 24-bit data frame or a 32-bit data
frame is selected the Size parameter means the number of
16-bit data length.
The I2S is kept enabled at the end of transaction to avoid the
clock de-synchronization between Master and Slave(example:
audio streaming).

HAL_I2S_Receive_IT

464/964

Function Name

HAL_StatusTypeDef HAL_I2S_Receive_IT
(I2S_HandleTypeDef * hi2s, uint16_t * pData, uint16_t Size)

Function Description

Receive an amount of data in non-blocking mode with Interrupt.

DocID025834 Rev 4

UM1725

HAL I2S Generic Driver
Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module
pData: a 16-bit pointer to the Receive data buffer.
Size: number of data sample to be sent:

Return values

HAL: status

Notes

When a 16-bit data frame or a 16-bit data frame extended is
selected during the I2S configuration phase, the Size
parameter means the number of 16-bit data length in the
transaction and when a 24-bit data frame or a 32-bit data
frame is selected the Size parameter means the number of
16-bit data length.
The I2S is kept enabled at the end of transaction to avoid the
clock de-synchronization between Master and Slave(example:
audio streaming).
It is recommended to use DMA for the I2S receiver to avoid
de-synchronisation between Master and Slave otherwise the
I2S interrupt should be optimized.

HAL_I2S_IRQHandler
Function Name

void HAL_I2S_IRQHandler (I2S_HandleTypeDef * hi2s)

Function Description

This function handles I2S interrupt request.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

None

HAL_I2S_Transmit_DMA
Function Name

HAL_StatusTypeDef HAL_I2S_Transmit_DMA
(I2S_HandleTypeDef * hi2s, uint16_t * pData, uint16_t Size)

Function Description

Transmit an amount of data in non-blocking mode with DMA.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module
pData: a 16-bit pointer to the Transmit data buffer.
Size: number of data sample to be sent:

Return values

HAL: status

Notes

When a 16-bit data frame or a 16-bit data frame extended is
selected during the I2S configuration phase, the Size
parameter means the number of 16-bit data length in the
transaction and when a 24-bit data frame or a 32-bit data
frame is selected the Size parameter means the number of
16-bit data length.
The I2S is kept enabled at the end of transaction to avoid the
clock de-synchronization between Master and Slave(example:
audio streaming).

DocID025834 Rev 4

465/964

HAL I2S Generic Driver

UM1725

HAL_I2S_Receive_DMA
Function Name

HAL_StatusTypeDef HAL_I2S_Receive_DMA
(I2S_HandleTypeDef * hi2s, uint16_t * pData, uint16_t Size)

Function Description

Receive an amount of data in non-blocking mode with DMA.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module
pData: a 16-bit pointer to the Receive data buffer.
Size: number of data sample to be sent:

Return values

HAL: status

Notes

When a 16-bit data frame or a 16-bit data frame extended is
selected during the I2S configuration phase, the Size
parameter means the number of 16-bit data length in the
transaction and when a 24-bit data frame or a 32-bit data
frame is selected the Size parameter means the number of
16-bit data length.
The I2S is kept enabled at the end of transaction to avoid the
clock de-synchronization between Master and Slave(example:
audio streaming).

HAL_I2S_DMAPause
Function Name

HAL_StatusTypeDef HAL_I2S_DMAPause
(I2S_HandleTypeDef * hi2s)

Function Description

Pauses the audio stream playing from the Media.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

HAL: status

HAL_I2S_DMAResume
Function Name

HAL_StatusTypeDef HAL_I2S_DMAResume
(I2S_HandleTypeDef * hi2s)

Function Description

Resumes the audio stream playing from the Media.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

HAL: status

HAL_I2S_DMAStop

466/964

Function Name

HAL_StatusTypeDef HAL_I2S_DMAStop (I2S_HandleTypeDef
* hi2s)

Function Description

Resumes the audio stream playing from the Media.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL I2S Generic Driver

HAL_I2S_GetState
Function Name

HAL_I2S_StateTypeDef HAL_I2S_GetState
(I2S_HandleTypeDef * hi2s)

Function Description

Return the I2S state.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

HAL: state

HAL_I2S_GetError
Function Name

uint32_t HAL_I2S_GetError (I2S_HandleTypeDef * hi2s)

Function Description

Return the I2S error code.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

I2S: Error Code

HAL_I2S_TxHalfCpltCallback
Function Name

void HAL_I2S_TxHalfCpltCallback (I2S_HandleTypeDef * hi2s)

Function Description

Tx Transfer Half completed callbacks.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

None

HAL_I2S_TxCpltCallback
Function Name

void HAL_I2S_TxCpltCallback (I2S_HandleTypeDef * hi2s)

Function Description

Tx Transfer completed callbacks.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

None

HAL_I2S_RxHalfCpltCallback
Function Name

void HAL_I2S_RxHalfCpltCallback (I2S_HandleTypeDef * hi2s)

Function Description

Rx Transfer half completed callbacks.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

None

HAL_I2S_RxCpltCallback
Function Name

void HAL_I2S_RxCpltCallback (I2S_HandleTypeDef * hi2s)

Function Description

Rx Transfer completed callbacks.

DocID025834 Rev 4

467/964

HAL I2S Generic Driver
Parameters

UM1725
hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

None

HAL_I2S_ErrorCallback
Function Name

void HAL_I2S_ErrorCallback (I2S_HandleTypeDef * hi2s)

Function Description

I2S error callbacks.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

None

I2S_DMATxCplt
Function Name

void I2S_DMATxCplt (DMA_HandleTypeDef * hdma)

Function Description

DMA I2S transmit process complete callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

I2S_DMATxHalfCplt
Function Name

void I2S_DMATxHalfCplt (DMA_HandleTypeDef * hdma)

Function Description

DMA I2S transmit process half complete callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

I2S_DMARxCplt
Function Name

void I2S_DMARxCplt (DMA_HandleTypeDef * hdma)

Function Description

DMA I2S receive process complete callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

I2S_DMARxHalfCplt
Function Name

void I2S_DMARxHalfCplt (DMA_HandleTypeDef * hdma)

Function Description

DMA I2S receive process half complete callback.

Parameters

468/964

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.
DocID025834 Rev 4

UM1725

HAL I2S Generic Driver
Return values

None

I2S_DMAError
Function Name

void I2S_DMAError (DMA_HandleTypeDef * hdma)

Function Description

DMA I2S communication error callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

I2S_WaitFlagStateUntilTimeout
Function Name

HAL_StatusTypeDef I2S_WaitFlagStateUntilTimeout
(I2S_HandleTypeDef * hi2s, uint32_t Flag, uint32_t Status,
uint32_t Timeout)

Function Description

This function handles I2S Communication Timeout.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module
Flag: Flag checked
Status: Value of the flag expected
Timeout: Duration of the timeout

Return values

HAL: status

I2S_Transmit_IT
Function Name

HAL_StatusTypeDef I2S_Transmit_IT (I2S_HandleTypeDef *
hi2s)

Function Description

Transmit an amount of data in non-blocking mode with Interrupt.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

HAL: status

I2S_Receive_IT
Function Name

HAL_StatusTypeDef I2S_Receive_IT (I2S_HandleTypeDef *
hi2s)

Function Description

Receive an amount of data in non-blocking mode with Interrupt.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

HAL: status

34.3

I2S Firmware driver defines

34.3.1

I2S
I2S Audio Frequency
DocID025834 Rev 4

469/964

HAL I2S Generic Driver
I2S_AUDIOFREQ_192K

UM1725

I2S_AUDIOFREQ_96K
I2S_AUDIOFREQ_48K
I2S_AUDIOFREQ_44K
I2S_AUDIOFREQ_32K
I2S_AUDIOFREQ_22K
I2S_AUDIOFREQ_16K
I2S_AUDIOFREQ_11K
I2S_AUDIOFREQ_8K
I2S_AUDIOFREQ_DEFAULT
I2S Clock Polarity
I2S_CPOL_LOW
I2S_CPOL_HIGH
I2S Clock Source
I2S_CLOCK_PLL
I2S_CLOCK_EXTERNAL
I2S Data Format
I2S_DATAFORMAT_16B
I2S_DATAFORMAT_16B_EXTENDED
I2S_DATAFORMAT_24B
I2S_DATAFORMAT_32B
I2S Error Code
HAL_I2S_ERROR_NONE

No error

HAL_I2S_ERROR_UDR

I2S Underrun error

HAL_I2S_ERROR_OVR

I2S Overrun error

HAL_I2SEX_ERROR_UDR

I2S extended Underrun error

HAL_I2SEX_ERROR_OVR

I2S extended Overrun error

HAL_I2S_ERROR_FRE

I2S Frame format error

HAL_I2S_ERROR_DMA

DMA transfer error

I2S Exported Macros
__HAL_I2S_RESET_HANDLE_STATE

Description:
Reset I2S handle state.
Parameters:
__HANDLE__: specifies the I2S Handle.
Return value:
None

470/964

DocID025834 Rev 4

UM1725

HAL I2S Generic Driver
Description:

__HAL_I2S_ENABLE

Enable or disable the specified SPI
peripheral (in I2S mode).
Parameters:
__HANDLE__: specifies the I2S Handle.
Return value:
None
__HAL_I2S_DISABLE
Description:

__HAL_I2S_ENABLE_IT

Enable or disable the specified I2S
interrupts.
Parameters:
__HANDLE__: specifies the I2S Handle.
__INTERRUPT__: specifies the interrupt
source to enable or disable. This parameter
can be one of the following values:
I2S_IT_TXE: Tx buffer empty interrupt
enable
I2S_IT_RXNE: RX buffer not empty
interrupt enable
I2S_IT_ERR: Error interrupt enable
Return value:
None
__HAL_I2S_DISABLE_IT
__HAL_I2S_GET_IT_SOURCE

Description:
Checks if the specified I2S interrupt source
is enabled or disabled.
Parameters:
__HANDLE__: specifies the I2S Handle.
This parameter can be I2S where x: 1, 2, or
3 to select the I2S peripheral.
__INTERRUPT__: specifies the I2S
interrupt source to check. This parameter
can be one of the following values:
I2S_IT_TXE: Tx buffer empty interrupt
enable
I2S_IT_RXNE: RX buffer not empty
interrupt enable
I2S_IT_ERR: Error interrupt enable
Return value:
The: new state of __IT__ (TRUE or FALSE).

__HAL_I2S_GET_FLAG

Description:
Checks whether the specified I2S flag is set
DocID025834 Rev 4

471/964

HAL I2S Generic Driver

UM1725
or not.
Parameters:
__HANDLE__: specifies the I2S Handle.
__FLAG__: specifies the flag to check. This
parameter can be one of the following
values:
I2S_FLAG_RXNE: Receive buffer not
empty flag
I2S_FLAG_TXE: Transmit buffer empty
flag
I2S_FLAG_UDR: Underrun flag
I2S_FLAG_OVR: Overrun flag
I2S_FLAG_FRE: Frame error flag
I2S_FLAG_CHSIDE: Channel Side flag
I2S_FLAG_BSY: Busy flag
Return value:
The: new state of __FLAG__ (TRUE or
FALSE).

__HAL_I2S_CLEAR_OVRFLAG

Description:
Clears the I2S OVR pending flag.
Parameters:
__HANDLE__: specifies the I2S Handle.
Return value:
None

__HAL_I2S_CLEAR_UDRFLAG

Description:
Clears the I2S UDR pending flag.
Parameters:
__HANDLE__: specifies the I2S Handle.
Return value:
None

I2S Flags Definition
I2S_FLAG_TXE
I2S_FLAG_RXNE
I2S_FLAG_UDR
I2S_FLAG_OVR
I2S_FLAG_FRE
I2S_FLAG_CHSIDE
I2S_FLAG_BSY
I2S FullDuplex Mode
I2S_FULLDUPLEXMODE_DISABLE

472/964

DocID025834 Rev 4

UM1725

HAL I2S Generic Driver
I2S_FULLDUPLEXMODE_ENABLE
I2S Interrupts Definition
I2S_IT_TXE
I2S_IT_RXNE
I2S_IT_ERR
I2S Mclk Output
I2S_MCLKOUTPUT_ENABLE
I2S_MCLKOUTPUT_DISABLE
I2S Mode
I2S_MODE_SLAVE_TX
I2S_MODE_SLAVE_RX
I2S_MODE_MASTER_TX
I2S_MODE_MASTER_RX
I2S Standard
I2S_STANDARD_PHILIPS
I2S_STANDARD_MSB
I2S_STANDARD_LSB
I2S_STANDARD_PCM_SHORT
I2S_STANDARD_PCM_LONG

DocID025834 Rev 4

473/964

HAL I2S Extension Driver

UM1725

35

HAL I2S Extension Driver

35.1

I2SEx Firmware driver API description

35.1.1

I2S Extension features
1.

2.
3.

In I2S full duplex mode, each SPI peripheral is able to manage sending and receiving
data simultaneously using two data lines. Each SPI peripheral has an extended block
called I2Sxext (i.e I2S2ext for SPI2 and I2S3ext for SPI3).
The extension block is not a full SPI IP, it is used only as I2S slave to implement full
duplex mode. The extension block uses the same clock sources as its master.
Both I2Sx and I2Sx_ext can be configured as transmitters or receivers.
Only I2Sx can deliver SCK and WS to I2Sx_ext in full duplex mode, where I2Sx
can be I2S2 or I2S3.

35.1.2

How to use this driver
Three operation modes are available within this driver :

Polling mode IO operation
Send and receive in the same time an amount of data in blocking mode using
HAL_I2S_TransmitReceive()

Interrupt mode IO operation
Send and receive in the same time an amount of data in non blocking mode using
HAL_I2S_TransmitReceive_IT()
At transmission end of half transfer HAL_I2S_TxHalfCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_I2S_TxHalfCpltCallback
At transmission end of transfer HAL_I2S_TxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2S_TxCpltCallback
At reception end of half transfer HAL_I2S_RxHalfCpltCallback is executed and user
can add his own code by customization of function pointer
HAL_I2S_RxHalfCpltCallback
At reception end of transfer HAL_I2S_RxCpltCallback is executed and user can add
his own code by customization of function pointer HAL_I2S_RxCpltCallback
In case of transfer Error, HAL_I2S_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2S_ErrorCallback

474/964

DocID025834 Rev 4

UM1725

HAL I2S Extension Driver

DMA mode IO operation
Send and receive an amount of data in non blocking mode (DMA) using
HAL_I2S_TransmitReceive_DMA()
At transmission end of half transfer HAL_I2S_TxHalfCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_I2S_TxHalfCpltCallback
At transmission end of transfer HAL_I2S_TxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_I2S_TxCpltCallback
At reception end of half transfer HAL_I2S_RxHalfCpltCallback is executed and user
can add his own code by customization of function pointer
HAL_I2S_RxHalfCpltCallback
At reception end of transfer HAL_I2S_RxCpltCallback is executed and user can add
his own code by customization of function pointer HAL_I2S_RxCpltCallback
In case of transfer Error, HAL_I2S_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_I2S_ErrorCallback
Pause the DMA Transfer using HAL_I2S_DMAPause()
Resume the DMA Transfer using HAL_I2S_DMAResume()
Stop the DMA Transfer using HAL_I2S_DMAStop()

35.1.3

Extension features Functions
This subsection provides a set of functions allowing to manage the I2S data transfers.
1.

2.
3.
4.
5.

There are two modes of transfer:
Blocking mode : The communication is performed in the polling mode. The
status of all data processing is returned by the same function after finishing
transfer.
No-Blocking mode : The communication is performed using Interrupts or DMA.
These functions return the status of the transfer startup. The end of the data
processing will be indicated through the dedicated I2S IRQ when using Interrupt
mode or the DMA IRQ when using DMA mode.
Blocking mode functions are :
HAL_I2S_TransmitReceive()
No-Blocking mode functions with Interrupt are :
HAL_I2S_TransmitReceive_IT()
No-Blocking mode functions with DMA are :
HAL_I2S_TransmitReceive_DMA()
A set of Transfer Complete Callbacks are provided in non Blocking mode:
HAL_I2S_TxCpltCallback()
HAL_I2S_RxCpltCallback()
HAL_I2S_ErrorCallback()

This section contains the following APIs:
HAL_I2S_Init()
HAL_I2SEx_TransmitReceive()
HAL_I2SEx_TransmitReceive_IT()
HAL_I2SEx_TransmitReceive_DMA()
HAL_I2S_DMAPause()
HAL_I2S_DMAResume()
HAL_I2S_DMAStop()
HAL_I2S_IRQHandler()
DocID025834 Rev 4

475/964

HAL I2S Extension Driver

35.1.4

UM1725

Detailed description of functions
HAL_I2SEx_TransmitReceive
Function Name

HAL_StatusTypeDef HAL_I2SEx_TransmitReceive
(I2S_HandleTypeDef * hi2s, uint16_t * pTxData, uint16_t *
pRxData, uint16_t Size, uint32_t Timeout)

Function Description

Full-Duplex Transmit/Receive data in blocking mode.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module
pTxData: a 16-bit pointer to the Transmit data buffer.
pRxData: a 16-bit pointer to the Receive data buffer.
Size: number of data sample to be sent:
Timeout: Timeout duration

Return values

HAL: status

Notes

When a 16-bit data frame or a 16-bit data frame extended is
selected during the I2S configuration phase, the Size
parameter means the number of 16-bit data length in the
transaction and when a 24-bit data frame or a 32-bit data
frame is selected the Size parameter means the number of
16-bit data length.
The I2S is kept enabled at the end of transaction to avoid the
clock de-synchronization between Master and Slave(example:
audio streaming).

HAL_I2SEx_TransmitReceive_IT

476/964

Function Name

HAL_StatusTypeDef HAL_I2SEx_TransmitReceive_IT
(I2S_HandleTypeDef * hi2s, uint16_t * pTxData, uint16_t *
pRxData, uint16_t Size)

Function Description

Full-Duplex Transmit/Receive data in non-blocking mode using
Interrupt.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module
pTxData: a 16-bit pointer to the Transmit data buffer.
pRxData: a 16-bit pointer to the Receive data buffer.
Size: number of data sample to be sent:

Return values

HAL: status

Notes

When a 16-bit data frame or a 16-bit data frame extended is
selected during the I2S configuration phase, the Size
parameter means the number of 16-bit data length in the
transaction and when a 24-bit data frame or a 32-bit data
frame is selected the Size parameter means the number of
16-bit data length.
The I2S is kept enabled at the end of transaction to avoid the
clock de-synchronization between Master and Slave(example:
audio streaming).

DocID025834 Rev 4

UM1725

HAL I2S Extension Driver

HAL_I2SEx_TransmitReceive_DMA
Function Name

HAL_StatusTypeDef HAL_I2SEx_TransmitReceive_DMA
(I2S_HandleTypeDef * hi2s, uint16_t * pTxData, uint16_t *
pRxData, uint16_t Size)

Function Description

Full-Duplex Transmit/Receive data in non-blocking mode using
DMA.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module
pTxData: a 16-bit pointer to the Transmit data buffer.
pRxData: a 16-bit pointer to the Receive data buffer.
Size: number of data sample to be sent:

Return values

HAL: status

Notes

When a 16-bit data frame or a 16-bit data frame extended is
selected during the I2S configuration phase, the Size
parameter means the number of 16-bit data length in the
transaction and when a 24-bit data frame or a 32-bit data
frame is selected the Size parameter means the number of
16-bit data length.
The I2S is kept enabled at the end of transaction to avoid the
clock de-synchronization between Master and Slave(example:
audio streaming).

I2SEx_TransmitReceive_IT
Function Name

HAL_StatusTypeDef I2SEx_TransmitReceive_IT
(I2S_HandleTypeDef * hi2s)

Function Description

Full-Duplex Transmit/Receive data in non-blocking mode using
Interrupt.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

HAL: status

I2S_GetInputClock
Function Name

uint32_t I2S_GetInputClock (I2S_HandleTypeDef * hi2s)

Function Description

Get I2S clock Input based on Source clock selection in RCC.

Parameters

hi2s: pointer to a I2S_HandleTypeDef structure that contains
the configuration information for I2S module

Return values

I2S: Clock Input

DocID025834 Rev 4

477/964

HAL IRDA Generic Driver

UM1725

36

HAL IRDA Generic Driver

36.1

IRDA Firmware driver registers structures

36.1.1

IRDA_InitTypeDef
Data Fields
uint32_t BaudRate
uint32_t WordLength
uint32_t Parity
uint32_t Mode
uint8_t Prescaler
uint32_t IrDAMode

Field Documentation
uint32_t IRDA_InitTypeDef::BaudRate
This member configures the IRDA communication baud rate. The baud rate is
computed using the following formula:IntegerDivider = ((PCLKx) / (8 * (hirda>Init.BaudRate)))FractionalDivider = ((IntegerDivider - ((uint32_t) IntegerDivider)) * 8)
+ 0.5
uint32_t IRDA_InitTypeDef::WordLength
Specifies the number of data bits transmitted or received in a frame. This parameter
can be a value of IRDA_Word_Length
uint32_t IRDA_InitTypeDef::Parity
Specifies the parity mode. This parameter can be a value of IRDA_Parity
Note:When parity is enabled, the computed parity is inserted at the MSB position of
the transmitted data (9th bit when the word length is set to 9 data bits; 8th bit when the
word length is set to 8 data bits).
uint32_t IRDA_InitTypeDef::Mode
Specifies wether the Receive or Transmit mode is enabled or disabled. This
parameter can be a value of IRDA_Mode
uint8_t IRDA_InitTypeDef::Prescaler
Specifies the Prescaler
uint32_t IRDA_InitTypeDef::IrDAMode
Specifies the IrDA mode This parameter can be a value of IRDA_Low_Power

36.1.2

IRDA_HandleTypeDef
Data Fields
USART_TypeDef * Instance
IRDA_InitTypeDef Init
uint8_t * pTxBuffPtr
uint16_t TxXferSize
uint16_t TxXferCount
uint8_t * pRxBuffPtr
uint16_t RxXferSize

478/964

DocID025834 Rev 4

UM1725

HAL IRDA Generic Driver
uint16_t RxXferCount
DMA_HandleTypeDef * hdmatx
DMA_HandleTypeDef * hdmarx
HAL_LockTypeDef Lock
__IO HAL_IRDA_StateTypeDef gState
__IO HAL_IRDA_StateTypeDef RxState
__IO uint32_t ErrorCode

Field Documentation
USART_TypeDef* IRDA_HandleTypeDef::Instance
IRDA_InitTypeDef IRDA_HandleTypeDef::Init
uint8_t* IRDA_HandleTypeDef::pTxBuffPtr
uint16_t IRDA_HandleTypeDef::TxXferSize
uint16_t IRDA_HandleTypeDef::TxXferCount
uint8_t* IRDA_HandleTypeDef::pRxBuffPtr
uint16_t IRDA_HandleTypeDef::RxXferSize
uint16_t IRDA_HandleTypeDef::RxXferCount
DMA_HandleTypeDef* IRDA_HandleTypeDef::hdmatx
DMA_HandleTypeDef* IRDA_HandleTypeDef::hdmarx
HAL_LockTypeDef IRDA_HandleTypeDef::Lock
__IO HAL_IRDA_StateTypeDef IRDA_HandleTypeDef::gState
__IO HAL_IRDA_StateTypeDef IRDA_HandleTypeDef::RxState
__IO uint32_t IRDA_HandleTypeDef::ErrorCode

36.2

IRDA Firmware driver API description

36.2.1

How to use this driver
The IRDA HAL driver can be used as follows:
1.
2.

Declare a IRDA_HandleTypeDef handle structure.
Initialize the IRDA low level resources by implementing the HAL_IRDA_MspInit() API:
a.
Enable the USARTx interface clock.
b.
IRDA pins configuration:
Enable the clock for the IRDA GPIOs.
Configure these IRDA pins as alternate function pull-up.
c.
NVIC configuration if you need to use interrupt process
(HAL_IRDA_Transmit_IT() and HAL_IRDA_Receive_IT() APIs):
Configure the USARTx interrupt priority.
Enable the NVIC USART IRQ handle.
d.
DMA Configuration if you need to use DMA process
(HAL_IRDA_Transmit_DMA() and HAL_IRDA_Receive_DMA() APIs):
Declare a DMA handle structure for the Tx/Rx stream.
Enable the DMAx interface clock.
Configure the declared DMA handle structure with the required Tx/Rx
parameters.
Configure the DMA Tx/Rx Stream.
Associate the initialized DMA handle to the IRDA DMA Tx/Rx handle.
Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Tx/Rx Stream.

DocID025834 Rev 4

479/964

HAL IRDA Generic Driver
UM1725
3.
Program the Baud Rate, Word Length, Parity, IrDA Mode, Prescaler and
Mode(Receiver/Transmitter) in the hirda Init structure.
4.
Initialize the IRDA registers by calling the HAL_IRDA_Init() API:
This API configures also the low level Hardware GPIO, CLOCK, CORTEX...etc)
by calling the customized HAL_IRDA_MspInit() API. The specific IRDA interrupts
(Transmission complete interrupt, RXNE interrupt and Error Interrupts) will be
managed using the macros __HAL_IRDA_ENABLE_IT() and
__HAL_IRDA_DISABLE_IT() inside the transmit and receive process.
5.
Three operation modes are available within this driver :

Polling mode IO operation
Send an amount of data in blocking mode using HAL_IRDA_Transmit()
Receive an amount of data in blocking mode using HAL_IRDA_Receive()

Interrupt mode IO operation
Send an amount of data in non blocking mode using HAL_IRDA_Transmit_IT()
At transmission end of transfer HAL_IRDA_TxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_IRDA_TxCpltCallback
Receive an amount of data in non blocking mode using HAL_IRDA_Receive_IT()
At reception end of transfer HAL_IRDA_RxCpltCallback is executed and user can add
his own code by customization of function pointer HAL_IRDA_RxCpltCallback
In case of transfer Error, HAL_IRDA_ErrorCallback() function is executed and user
can add his own code by customization of function pointer HAL_IRDA_ErrorCallback

DMA mode IO operation
Send an amount of data in non blocking mode (DMA) using
HAL_IRDA_Transmit_DMA()
At transmission end of transfer HAL_IRDA_TxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_IRDA_TxCpltCallback
Receive an amount of data in non blocking mode (DMA) using
HAL_IRDA_Receive_DMA()
At reception end of transfer HAL_IRDA_RxCpltCallback is executed and user can add
his own code by customization of function pointer HAL_IRDA_RxCpltCallback
In case of transfer Error, HAL_IRDA_ErrorCallback() function is executed and user
can add his own code by customization of function pointer HAL_IRDA_ErrorCallback

IRDA HAL driver macros list
You can refer to the IRDA HAL driver header file for more useful macros

480/964

DocID025834 Rev 4

UM1725

36.2.2

HAL IRDA Generic Driver

Initialization and Configuration functions
This subsection provides a set of functions allowing to initialize the USARTx or the UARTy
in IrDA mode.
For the asynchronous mode only these parameters can be configured:
BaudRate
WordLength
Parity: If the parity is enabled, then the MSB bit of the data written in the data
register is transmitted but is changed by the parity bit. Depending on the frame
length defined by the M bit (8-bits or 9-bits), please refer to Reference manual for
possible IRDA frame formats.
Prescaler: A pulse of width less than two and greater than one PSC period(s)
may or may not be rejected. The receiver set up time should be managed by
software. The IrDA physical layer specification specifies a minimum of 10 ms
delay between transmission and reception (IrDA is a half duplex protocol).
Mode: Receiver/transmitter modes
IrDAMode: the IrDA can operate in the Normal mode or in the Low power mode.
The HAL_IRDA_Init() API follows IRDA configuration procedures (details for the
procedures are available in reference manual).
This section contains the following APIs:
HAL_IRDA_Init()
HAL_IRDA_DeInit()
HAL_IRDA_MspInit()
HAL_IRDA_MspDeInit()

36.2.3

IO operation functions
IrDA is a half duplex communication protocol. If the Transmitter is busy, any data on the
IrDA receive line will be ignored by the IrDA decoder and if the Receiver is busy, data on
the TX from the USART to IrDA will not be encoded by IrDA. While receiving data,
transmission should be avoided as the data to be transmitted could be corrupted.
1.

2.

3.

4.

There are two modes of transfer:
Blocking mode: The communication is performed in polling mode. The HAL
status of all data processing is returned by the same function after finishing
transfer.
No-Blocking mode: The communication is performed using Interrupts or DMA,
These APIs return the HAL status. The end of the data processing will be
indicated through the dedicated IRDA IRQ when using Interrupt mode or the
DMA IRQ when using DMA mode. The HAL_IRDA_TxCpltCallback(),
HAL_IRDA_RxCpltCallback() user callbacks will be executed respectively at the
end of the transmit or Receive process The HAL_IRDA_ErrorCallback() user
callback will be executed when a communication error is detected
Blocking mode API's are :
HAL_IRDA_Transmit()
HAL_IRDA_Receive()
Non Blocking mode APIs with Interrupt are :
HAL_IRDA_Transmit_IT()
HAL_IRDA_Receive_IT()
HAL_IRDA_IRQHandler()
Non Blocking mode functions with DMA are :
HAL_IRDA_Transmit_DMA()
DocID025834 Rev 4

481/964

HAL IRDA Generic Driver
5.

UM1725

HAL_IRDA_Receive_DMA()
A set of Transfer Complete Callbacks are provided in non Blocking mode:
HAL_IRDA_TxCpltCallback()
HAL_IRDA_RxCpltCallback()
HAL_IRDA_ErrorCallback()

This section contains the following APIs:
HAL_IRDA_Transmit()
HAL_IRDA_Receive()
HAL_IRDA_Transmit_IT()
HAL_IRDA_Receive_IT()
HAL_IRDA_Transmit_DMA()
HAL_IRDA_Receive_DMA()
HAL_IRDA_DMAPause()
HAL_IRDA_DMAResume()
HAL_IRDA_DMAStop()
HAL_IRDA_IRQHandler()
HAL_IRDA_TxCpltCallback()
HAL_IRDA_TxHalfCpltCallback()
HAL_IRDA_RxCpltCallback()
HAL_IRDA_RxHalfCpltCallback()
HAL_IRDA_ErrorCallback()

36.2.4

Peripheral State and Errors functions
This subsection provides a set of functions allowing to return the State of IrDA
communication process and also return Peripheral Errors occurred during communication
process
HAL_IRDA_GetState() API can be helpful to check in run-time the state of the IrDA
peripheral.
HAL_IRDA_GetError() check in run-time errors that could be occurred during
communication.
This section contains the following APIs:
HAL_IRDA_GetState()
HAL_IRDA_GetError()

36.2.5

Detailed description of functions
HAL_IRDA_Init

482/964

Function Name

HAL_StatusTypeDef HAL_IRDA_Init (IRDA_HandleTypeDef *
hirda)

Function Description

Initializes the IRDA mode according to the specified parameters in
the IRDA_InitTypeDef and create the associated handle.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL IRDA Generic Driver

HAL_IRDA_DeInit
Function Name

HAL_StatusTypeDef HAL_IRDA_DeInit (IRDA_HandleTypeDef
* hirda)

Function Description

DeInitializes the IRDA peripheral.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

HAL: status

HAL_IRDA_MspInit
Function Name

void HAL_IRDA_MspInit (IRDA_HandleTypeDef * hirda)

Function Description

IRDA MSP Init.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

None

HAL_IRDA_MspDeInit
Function Name

void HAL_IRDA_MspDeInit (IRDA_HandleTypeDef * hirda)

Function Description

IRDA MSP DeInit.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

None

HAL_IRDA_Transmit
Function Name

HAL_StatusTypeDef HAL_IRDA_Transmit
(IRDA_HandleTypeDef * hirda, uint8_t * pData, uint16_t Size,
uint32_t Timeout)

Function Description

Sends an amount of data in blocking mode.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Specify timeout value

Return values

HAL: status

HAL_IRDA_Receive
Function Name

HAL_StatusTypeDef HAL_IRDA_Receive
(IRDA_HandleTypeDef * hirda, uint8_t * pData, uint16_t Size,
uint32_t Timeout)

DocID025834 Rev 4

483/964

HAL IRDA Generic Driver
Function Description

UM1725
Receive an amount of data in blocking mode.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.
pData: Pointer to data buffer
Size: Amount of data to be received
Timeout: Specify timeout value

Return values

HAL: status

HAL_IRDA_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_IRDA_Transmit_IT
(IRDA_HandleTypeDef * hirda, uint8_t * pData, uint16_t Size)

Function Description

Send an amount of data in non blocking mode.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_IRDA_Receive_IT
Function Name

HAL_StatusTypeDef HAL_IRDA_Receive_IT
(IRDA_HandleTypeDef * hirda, uint8_t * pData, uint16_t Size)

Function Description

Receives an amount of data in non blocking mode.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.
pData: Pointer to data buffer
Size: Amount of data to be received

Return values

HAL: status

HAL_IRDA_Transmit_DMA

484/964

Function Name

HAL_StatusTypeDef HAL_IRDA_Transmit_DMA
(IRDA_HandleTypeDef * hirda, uint8_t * pData, uint16_t Size)

Function Description

Sends an amount of data in non blocking mode.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL IRDA Generic Driver

HAL_IRDA_Receive_DMA
Function Name

HAL_StatusTypeDef HAL_IRDA_Receive_DMA
(IRDA_HandleTypeDef * hirda, uint8_t * pData, uint16_t Size)

Function Description

Receives an amount of data in non blocking mode.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.
pData: Pointer to data buffer
Size: Amount of data to be received

Return values

HAL: status

Notes

When the IRDA parity is enabled (PCE = 1) the data received
contain the parity bit.

HAL_IRDA_DMAPause
Function Name

HAL_StatusTypeDef HAL_IRDA_DMAPause
(IRDA_HandleTypeDef * hirda)

Function Description

Pauses the DMA Transfer.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

HAL: status

HAL_IRDA_DMAResume
Function Name

HAL_StatusTypeDef HAL_IRDA_DMAResume
(IRDA_HandleTypeDef * hirda)

Function Description

Resumes the DMA Transfer.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

HAL: status

HAL_IRDA_DMAStop
Function Name

HAL_StatusTypeDef HAL_IRDA_DMAStop
(IRDA_HandleTypeDef * hirda)

Function Description

Stops the DMA Transfer.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

HAL: status

DocID025834 Rev 4

485/964

HAL IRDA Generic Driver

UM1725

HAL_IRDA_IRQHandler
Function Name

void HAL_IRDA_IRQHandler (IRDA_HandleTypeDef * hirda)

Function Description

This function handles IRDA interrupt request.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

None

HAL_IRDA_TxCpltCallback
Function Name

void HAL_IRDA_TxCpltCallback (IRDA_HandleTypeDef *
hirda)

Function Description

Tx Transfer complete callbacks.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

None

HAL_IRDA_RxCpltCallback
Function Name

void HAL_IRDA_RxCpltCallback (IRDA_HandleTypeDef *
hirda)

Function Description

Rx Transfer complete callbacks.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

None

HAL_IRDA_TxHalfCpltCallback
Function Name

void HAL_IRDA_TxHalfCpltCallback (IRDA_HandleTypeDef *
hirda)

Function Description

Tx Half Transfer completed callbacks.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

None

HAL_IRDA_RxHalfCpltCallback
Function Name

void HAL_IRDA_RxHalfCpltCallback (IRDA_HandleTypeDef *
hirda)

Function Description

Rx Half Transfer complete callbacks.

Parameters

486/964

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.
DocID025834 Rev 4

UM1725

HAL IRDA Generic Driver
Return values

None

HAL_IRDA_ErrorCallback
Function Name

void HAL_IRDA_ErrorCallback (IRDA_HandleTypeDef * hirda)

Function Description

IRDA error callbacks.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

None

HAL_IRDA_GetState
Function Name

HAL_IRDA_StateTypeDef HAL_IRDA_GetState
(IRDA_HandleTypeDef * hirda)

Function Description

Returns the IRDA state.

Parameters

hirda: pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA
module.

Return values

HAL: state

HAL_IRDA_GetError
Function Name

uint32_t HAL_IRDA_GetError (IRDA_HandleTypeDef * hirda)

Function Description

Return the IARDA error code.

Parameters

hirda: : pointer to a IRDA_HandleTypeDef structure that
contains the configuration information for the specified IRDA.

Return values

IRDA: Error Code

36.3

IRDA Firmware driver defines

36.3.1

IRDA
IRDA Error Code
HAL_IRDA_ERROR_NONE

No error

HAL_IRDA_ERROR_PE

Parity error

HAL_IRDA_ERROR_NE

Noise error

HAL_IRDA_ERROR_FE

Frame error

HAL_IRDA_ERROR_ORE

Overrun error

HAL_IRDA_ERROR_DMA

DMA transfer error

DocID025834 Rev 4

487/964

HAL IRDA Generic Driver
IRDA Exported Macros

UM1725

__HAL_IRDA_RESET_HANDLE_STATE

Description:
Reset IRDA handle gstate & RxState.
Parameters:
__HANDLE__: specifies the USART
Handle. This parameter can be
USARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
Return value:
None

__HAL_IRDA_FLUSH_DRREGISTER

Description:
Flushs the IRDA DR register.
Parameters:
__HANDLE__: specifies the USART
Handle. This parameter can be
USARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.

__HAL_IRDA_GET_FLAG

Description:
Checks whether the specified IRDA
flag is set or not.
Parameters:
__HANDLE__: specifies the USART
Handle. This parameter can be
USARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
__FLAG__: specifies the flag to
check. This parameter can be one of
the following values:
IRDA_FLAG_TXE: Transmit data
register empty flag
IRDA_FLAG_TC: Transmission
Complete flag
IRDA_FLAG_RXNE: Receive
data register not empty flag
IRDA_FLAG_IDLE: Idle Line
detection flag
IRDA_FLAG_ORE: OverRun
Error flag
IRDA_FLAG_NE: Noise Error
flag
IRDA_FLAG_FE: Framing Error
flag
IRDA_FLAG_PE: Parity Error
flag

488/964

DocID025834 Rev 4

UM1725

HAL IRDA Generic Driver
Return value:
The: new state of __FLAG__ (TRUE
or FALSE).
__HAL_IRDA_CLEAR_FLAG

Description:
Clears the specified IRDA pending
flag.
Parameters:
__HANDLE__: specifies the USART
Handle. This parameter can be
USARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
__FLAG__: specifies the flag to
check. This parameter can be any
combination of the following values:
IRDA_FLAG_TC: Transmission
Complete flag.
IRDA_FLAG_RXNE: Receive
data register not empty flag.
Return value:
None
Notes:
PE (Parity error), FE (Framing error),
NE (Noise error), ORE (OverRun
error) and IDLE (Idle line detected)
flags are cleared by software
sequence: a read operation to
USART_SR register followed by a
read operation to USART_DR
register. RXNE flag can be also
cleared by a read to the USART_DR
register. TC flag can be also cleared
by software sequence: a read
operation to USART_SR register
followed by a write operation to
USART_DR register. TXE flag is
cleared only by a write to the
USART_DR register.

__HAL_IRDA_CLEAR_PEFLAG

Description:
Clear the IRDA PE pending flag.
Parameters:
__HANDLE__: specifies the USART
Handle. This parameter can be
USARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
Return value:

DocID025834 Rev 4

489/964

HAL IRDA Generic Driver

UM1725
None

__HAL_IRDA_CLEAR_FEFLAG

Description:
Clear the IRDA FE pending flag.
Parameters:
__HANDLE__: specifies the USART
Handle. This parameter can be
USARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
Return value:
None

__HAL_IRDA_CLEAR_NEFLAG

Description:
Clear the IRDA NE pending flag.
Parameters:
__HANDLE__: specifies the USART
Handle. This parameter can be
USARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
Return value:
None

__HAL_IRDA_CLEAR_OREFLAG

Description:
Clear the IRDA ORE pending flag.
Parameters:
__HANDLE__: specifies the USART
Handle. This parameter can be
USARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
Return value:
None

__HAL_IRDA_CLEAR_IDLEFLAG

Description:
Clear the IRDA IDLE pending flag.
Parameters:
__HANDLE__: specifies the USART
Handle. This parameter can be
USARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
Return value:
None

490/964

DocID025834 Rev 4

UM1725

HAL IRDA Generic Driver
Description:

__HAL_IRDA_ENABLE_IT

Enables or disables the specified
IRDA interrupt.
Parameters:
__HANDLE__: specifies the USART
Handle. This parameter can be
USARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
__INTERRUPT__: specifies the IRDA
interrupt source to check. This
parameter can be one of the following
values:
IRDA_IT_TXE: Transmit Data
Register empty interrupt
IRDA_IT_TC: Transmission
complete interrupt
IRDA_IT_RXNE: Receive Data
register not empty interrupt
IRDA_IT_IDLE: Idle line
detection interrupt
IRDA_IT_PE: Parity Error
interrupt
IRDA_IT_ERR: Error
interrupt(Frame error, noise
error, overrun error)
Return value:
None
__HAL_IRDA_DISABLE_IT
__HAL_IRDA_GET_IT_SOURCE

Description:
Checks whether the specified IRDA
interrupt has occurred or not.
Parameters:
__HANDLE__: specifies the USART
Handle. This parameter can be
USARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
__IT__: specifies the IRDA interrupt
source to check. This parameter can
be one of the following values:
IRDA_IT_TXE: Transmit Data
Register empty interrupt
IRDA_IT_TC: Transmission
complete interrupt
IRDA_IT_RXNE: Receive Data
register not empty interrupt
IRDA_IT_IDLE: Idle line
detection interrupt

DocID025834 Rev 4

491/964

HAL IRDA Generic Driver

UM1725
USART_IT_ERR: Error interrupt
IRDA_IT_PE: Parity Error
interrupt
Return value:
The: new state of __IT__ (TRUE or
FALSE).

__HAL_IRDA_ONE_BIT_SAMPLE_ENABLE

Description:
Macro to enable the IRDA's one bit
sample method.
Parameters:
__HANDLE__: specifies the IRDA
Handle.
Return value:
None

__HAL_IRDA_ONE_BIT_SAMPLE_DISABLE

Description:
Macro to disable the IRDA's one bit
sample method.
Parameters:
__HANDLE__: specifies the IRDA
Handle.
Return value:
None

__HAL_IRDA_ENABLE

Description:
Enable UART/USART associated to
IRDA Handle.
Parameters:
__HANDLE__: specifies the IRDA
Handle. IRDA Handle selects the
USARTx or UARTy peripheral
(USART,UART availability and x,y
values depending on device).
Return value:
None

__HAL_IRDA_DISABLE

Description:
Disable UART/USART associated to
IRDA Handle.
Parameters:
__HANDLE__: specifies the IRDA
Handle. IRDA Handle selects the
USARTx or UARTy peripheral
(USART,UART availability and x,y
values depending on device).

492/964

DocID025834 Rev 4

UM1725

HAL IRDA Generic Driver
Return value:
None
IRDA Flags
IRDA_FLAG_TXE
IRDA_FLAG_TC
IRDA_FLAG_RXNE
IRDA_FLAG_IDLE
IRDA_FLAG_ORE
IRDA_FLAG_NE
IRDA_FLAG_FE
IRDA_FLAG_PE
IRDA Interrupt Definitions
IRDA_IT_PE
IRDA_IT_TXE
IRDA_IT_TC
IRDA_IT_RXNE
IRDA_IT_IDLE
IRDA_IT_LBD
IRDA_IT_CTS
IRDA_IT_ERR
IRDA Low Power
IRDA_POWERMODE_LOWPOWER
IRDA_POWERMODE_NORMAL
IRDA Transfer Mode
IRDA_MODE_RX
IRDA_MODE_TX
IRDA_MODE_TX_RX
IRDA Parity
IRDA_PARITY_NONE
IRDA_PARITY_EVEN
IRDA_PARITY_ODD
IRDA Word Length
IRDA_WORDLENGTH_8B
IRDA_WORDLENGTH_9B

DocID025834 Rev 4

493/964

HAL IWDG Generic Driver

UM1725

37

HAL IWDG Generic Driver

37.1

IWDG Firmware driver registers structures

37.1.1

IWDG_InitTypeDef
Data Fields
uint32_t Prescaler
uint32_t Reload

Field Documentation
uint32_t IWDG_InitTypeDef::Prescaler
Select the prescaler of the IWDG. This parameter can be a value of IWDG_Prescaler
uint32_t IWDG_InitTypeDef::Reload
Specifies the IWDG down-counter reload value. This parameter must be a number
between Min_Data = 0 and Max_Data = 0x0FFF

37.1.2

IWDG_HandleTypeDef
Data Fields
IWDG_TypeDef * Instance
IWDG_InitTypeDef Init

Field Documentation
IWDG_TypeDef* IWDG_HandleTypeDef::Instance
Register base address
IWDG_InitTypeDef IWDG_HandleTypeDef::Init
IWDG required parameters

37.2

IWDG Firmware driver API description

37.2.1

IWDG Generic features
The IWDG can be started by either software or hardware (configurable through option
byte).
The IWDG is clocked by Low-Speed clock (LSI) and thus stays active even if the
main clock fails.
Once the IWDG is started, the LSI is forced ON and both can not be disabled. The
counter starts counting down from the reset value (0xFFF). When it reaches the end of
count value (0x000) a reset signal is generated (IWDG reset).

494/964

DocID025834 Rev 4

UM1725

HAL IWDG Generic Driver
Whenever the key value 0x0000 AAAA is written in the IWDG_KR register, the
IWDG_RLR value is reloaded in the counter and the watchdog reset is prevented.
The IWDG is implemented in the VDD voltage domain that is still functional in STOP
and STANDBY mode (IWDG reset can wake-up from STANDBY). IWDGRST flag in
RCC_CSR register can be used to inform when an IWDG reset occurs.
Debug mode : When the microcontroller enters debug mode (core halted), the IWDG
counter either continues to work normally or stops, depending on DBG_IWDG_STOP
configuration bit in DBG module, accessible through
__HAL_DBGMCU_FREEZE_IWDG() and __HAL_DBGMCU_UNFREEZE_IWDG()
macros
Min-max timeout value @32KHz (LSI): ~125us / ~32.7s The IWDG timeout may vary due
to LSI frequency dispersion. STM32F4xx devices provide the capability to measure the LSI
frequency (LSI clock connected internally to TIM5 CH4 input capture). The measured value
can be used to have an IWDG timeout with an acceptable accuracy.

37.2.2

How to use this driver
1.

2.

Use IWDG using HAL_IWDG_Init() function to :
Enable instance by writing Start keyword in IWDG_KEY register. LSI clock is
forced ON and IWDG counter starts downcounting.
Enable write access to configuration register: IWDG_PR & IWDG_RLR.
Configure the IWDG prescaler and counter reload value. This reload value will
be loaded in the IWDG counter each time the watchdog is reloaded, then the
IWDG will start counting down from this value.
wait for status flags to be reset"
Then the application program must refresh the IWDG counter at regular intervals
during normal operation to prevent an MCU reset, using HAL_IWDG_Refresh()
function.

IWDG HAL driver macros list
Below the list of most used macros in IWDG HAL driver:
__HAL_IWDG_START: Enable the IWDG peripheral
__HAL_IWDG_RELOAD_COUNTER: Reloads IWDG counter with value defined in
the reload register

37.2.3

Initialization and Start functions
This section provides functions allowing to:
Initialize the IWDG according to the specified parameters in the IWDG_InitTypeDef of
associated handle.
Once initialization is performed in HAL_IWDG_Init function, Watchdog is reloaded in
order to exit function with correct time base.
This section contains the following APIs:
HAL_IWDG_Init()

37.2.4

IO operation functions
This section provides functions allowing to:
Refresh the IWDG.
This section contains the following APIs:
DocID025834 Rev 4

495/964

HAL IWDG Generic Driver

UM1725

HAL_IWDG_Refresh()

37.2.5

Detailed description of functions
HAL_IWDG_Init
Function Name

HAL_StatusTypeDef HAL_IWDG_Init (IWDG_HandleTypeDef *
hiwdg)

Function Description

Initialize the IWDG according to the specified parameters in the
IWDG_InitTypeDef and start watchdog.

Parameters

hiwdg: pointer to a IWDG_HandleTypeDef structure that
contains the configuration information for the specified IWDG
module.

Return values

HAL: status

HAL_IWDG_Refresh
Function Name

HAL_StatusTypeDef HAL_IWDG_Refresh
(IWDG_HandleTypeDef * hiwdg)

Function Description

Refresh the IWDG.

Parameters

hiwdg: pointer to a IWDG_HandleTypeDef structure that
contains the configuration information for the specified IWDG
module.

Return values

HAL: status

37.3

IWDG Firmware driver defines

37.3.1

IWDG
IWDG Exported Macros
Description:

__HAL_IWDG_START

Enable the IWDG peripheral.
Parameters:
__HANDLE__: IWDG handle
Return value:
None
__HAL_IWDG_RELOAD_COUNTER

Description:
Reload IWDG counter with value defined in
the reload register (write access to IWDG_PR
& IWDG_RLR registers disabled).
Parameters:
__HANDLE__: IWDG handle
Return value:
None

496/964

DocID025834 Rev 4

UM1725

HAL IWDG Generic Driver
IWDG Prescaler
IWDG_PRESCALER_4

IWDG prescaler set to 4

IWDG_PRESCALER_8

IWDG prescaler set to 8

IWDG_PRESCALER_16

IWDG prescaler set to 16

IWDG_PRESCALER_32

IWDG prescaler set to 32

IWDG_PRESCALER_64

IWDG prescaler set to 64

IWDG_PRESCALER_128

IWDG prescaler set to 128

IWDG_PRESCALER_256

IWDG prescaler set to 256

DocID025834 Rev 4

497/964

HAL LPTIM Generic Driver

UM1725

38

HAL LPTIM Generic Driver

38.1

LPTIM Firmware driver registers structures

38.1.1

LPTIM_ClockConfigTypeDef
Data Fields
uint32_t Source
uint32_t Prescaler

Field Documentation
uint32_t LPTIM_ClockConfigTypeDef::Source
Selects the clock source. This parameter can be a value of LPTIM_Clock_Source
uint32_t LPTIM_ClockConfigTypeDef::Prescaler
Specifies the counter clock Prescaler. This parameter can be a value of
LPTIM_Clock_Prescaler

38.1.2

LPTIM_ULPClockConfigTypeDef
Data Fields
uint32_t Polarity
uint32_t SampleTime

Field Documentation
uint32_t LPTIM_ULPClockConfigTypeDef::Polarity
Selects the polarity of the active edge for the counter unit if the ULPTIM input is
selected. Note: This parameter is used only when Ultra low power clock source is
used. Note: If the polarity is configured on 'both edges', an auxiliary clock (one of the
Low power oscillator) must be active. This parameter can be a value of
LPTIM_Clock_Polarity
uint32_t LPTIM_ULPClockConfigTypeDef::SampleTime
Selects the clock sampling time to configure the clock glitch filter. Note: This
parameter is used only when Ultra low power clock source is used. This parameter
can be a value of LPTIM_Clock_Sample_Time

38.1.3

LPTIM_TriggerConfigTypeDef
Data Fields
uint32_t Source
uint32_t ActiveEdge
uint32_t SampleTime

498/964

DocID025834 Rev 4

UM1725

HAL LPTIM Generic Driver
Field Documentation
uint32_t LPTIM_TriggerConfigTypeDef::Source
Selects the Trigger source. This parameter can be a value of
LPTIM_Trigger_Source
uint32_t LPTIM_TriggerConfigTypeDef::ActiveEdge
Selects the Trigger active edge. Note: This parameter is used only when an external
trigger is used. This parameter can be a value of LPTIM_External_Trigger_Polarity
uint32_t LPTIM_TriggerConfigTypeDef::SampleTime
Selects the trigger sampling time to configure the clock glitch filter. Note: This
parameter is used only when an external trigger is used. This parameter can be a
value of LPTIM_Trigger_Sample_Time

38.1.4

LPTIM_InitTypeDef
Data Fields
LPTIM_ClockConfigTypeDef Clock
LPTIM_ULPClockConfigTypeDef UltraLowPowerClock
LPTIM_TriggerConfigTypeDef Trigger
uint32_t OutputPolarity
uint32_t UpdateMode
uint32_t CounterSource

Field Documentation
LPTIM_ClockConfigTypeDef LPTIM_InitTypeDef::Clock
Specifies the clock parameters
LPTIM_ULPClockConfigTypeDef LPTIM_InitTypeDef::UltraLowPowerClock
Specifies the Ultra Low Power clock parameters
LPTIM_TriggerConfigTypeDef LPTIM_InitTypeDef::Trigger
Specifies the Trigger parameters
uint32_t LPTIM_InitTypeDef::OutputPolarity
Specifies the Output polarity. This parameter can be a value of
LPTIM_Output_Polarity
uint32_t LPTIM_InitTypeDef::UpdateMode
Specifies whether the update of the autorelaod and the compare values is done
immediately or after the end of current period. This parameter can be a value of
LPTIM_Updating_Mode
uint32_t LPTIM_InitTypeDef::CounterSource
Specifies whether the counter is incremented each internal event or each external
event. This parameter can be a value of LPTIM_Counter_Source

38.1.5

LPTIM_HandleTypeDef
Data Fields
LPTIM_TypeDef * Instance
LPTIM_InitTypeDef Init
DocID025834 Rev 4

499/964

HAL LPTIM Generic Driver

UM1725

HAL_StatusTypeDef Status
HAL_LockTypeDef Lock
__IO HAL_LPTIM_StateTypeDef State

Field Documentation
LPTIM_TypeDef* LPTIM_HandleTypeDef::Instance
Register base address
LPTIM_InitTypeDef LPTIM_HandleTypeDef::Init
LPTIM required parameters
HAL_StatusTypeDef LPTIM_HandleTypeDef::Status
LPTIM peripheral status
HAL_LockTypeDef LPTIM_HandleTypeDef::Lock
LPTIM locking object
__IO HAL_LPTIM_StateTypeDef LPTIM_HandleTypeDef::State
LPTIM peripheral state

38.2

LPTIM Firmware driver API description

38.2.1

How to use this driver
The LPTIM HAL driver can be used as follows:
1.

2.

3.

500/964

Initialize the LPTIM low level resources by implementing the HAL_LPTIM_MspInit():
a.
Enable the LPTIM interface clock using __LPTIMx_CLK_ENABLE().
b.
In case of using interrupts (e.g. HAL_LPTIM_PWM_Start_IT()):
Configure the LPTIM interrupt priority using HAL_NVIC_SetPriority().
Enable the LPTIM IRQ handler using HAL_NVIC_EnableIRQ().
In LPTIM IRQ handler, call HAL_LPTIM_IRQHandler().
Initialize the LPTIM HAL using HAL_LPTIM_Init(). This function configures mainly:
a.
The instance: LPTIM1.
b.
Clock: the counter clock.
Source : it can be either the ULPTIM input (IN1) or one of the internal clock;
(APB, LSE or LSI).
Prescaler: select the clock divider.
c.
UltraLowPowerClock : To be used only if the ULPTIM is selected as counter
clock source.
Polarity: polarity of the active edge for the counter unit if the ULPTIM input
is selected.
SampleTime: clock sampling time to configure the clock glitch filter.
d.
Trigger: How the counter start.
Source: trigger can be software or one of the hardware triggers.
ActiveEdge : only for hardware trigger.
SampleTime : trigger sampling time to configure the trigger glitch filter.
e.
OutputPolarity : 2 opposite polarities are possibles.
f.
UpdateMode: specifies whether the update of the autoreload and the compare
values is done immediately or after the end of current period.
Six modes are available:
a.
PWM Mode: To generate a PWM signal with specified period and pulse, call
HAL_LPTIM_PWM_Start() or HAL_LPTIM_PWM_Start_IT() for interruption
mode.

DocID025834 Rev 4

UM1725

HAL LPTIM Generic Driver
One Pulse Mode: To generate pulse with specified width in response to a
stimulus, call HAL_LPTIM_OnePulse_Start() or
HAL_LPTIM_OnePulse_Start_IT() for interruption mode.
c.
Set once Mode: In this mode, the output changes the level (from low level to high
level if the output polarity is configured high, else the opposite) when a compare
match occurs. To start this mode, call HAL_LPTIM_SetOnce_Start() or
HAL_LPTIM_SetOnce_Start_IT() for interruption mode.
d.
Encoder Mode: To use the encoder interface call HAL_LPTIM_Encoder_Start()
or HAL_LPTIM_Encoder_Start_IT() for interruption mode.
e.
Time out Mode: an active edge on one selected trigger input rests the counter.
The first trigger event will start the timer, any successive trigger event will reset
the counter and the timer will restart. To start this mode call
HAL_LPTIM_TimeOut_Start_IT() or HAL_LPTIM_TimeOut_Start_IT() for
interruption mode.
f.
Counter Mode: counter can be used to count external events on the LPTIM
Input1 or it can be used to count internal clock cycles. To start this mode, call
HAL_LPTIM_Counter_Start() or HAL_LPTIM_Counter_Start_IT() for interruption
mode.
User can stop any process by calling the corresponding API: HAL_LPTIM_Xxx_Stop()
or HAL_LPTIM_Xxx_Stop_IT() if the process is already started in interruption mode.
Call HAL_LPTIM_DeInit() to deinitialize the LPTIM peripheral.
b.

4.
5.

38.2.2

Initialization and de-initialization functions
This section provides functions allowing to:
Initialize the LPTIM according to the specified parameters in the LPTIM_InitTypeDef
and creates the associated handle.
DeInitialize the LPTIM peripheral.
Initialize the LPTIM MSP.
DeInitialize LPTIM MSP.
This section contains the following APIs:
HAL_LPTIM_Init()
HAL_LPTIM_DeInit()
HAL_LPTIM_MspInit()
HAL_LPTIM_MspDeInit()

38.2.3

LPTIM Start Stop operation functions
This section provides functions allowing to:
Start the PWM mode.
Stop the PWM mode.
Start the One pulse mode.
Stop the One pulse mode.
Start the Set once mode.
Stop the Set once mode.
Start the Encoder mode.
Stop the Encoder mode.
Start the Timeout mode.
Stop the Timeout mode.
Start the Counter mode.
Stop the Counter mode.
This section contains the following APIs:
DocID025834 Rev 4

501/964

HAL LPTIM Generic Driver

UM1725

HAL_LPTIM_PWM_Start()
HAL_LPTIM_PWM_Stop()
HAL_LPTIM_PWM_Start_IT()
HAL_LPTIM_PWM_Stop_IT()
HAL_LPTIM_OnePulse_Start()
HAL_LPTIM_OnePulse_Stop()
HAL_LPTIM_OnePulse_Start_IT()
HAL_LPTIM_OnePulse_Stop_IT()
HAL_LPTIM_SetOnce_Start()
HAL_LPTIM_SetOnce_Stop()
HAL_LPTIM_SetOnce_Start_IT()
HAL_LPTIM_SetOnce_Stop_IT()
HAL_LPTIM_Encoder_Start()
HAL_LPTIM_Encoder_Stop()
HAL_LPTIM_Encoder_Start_IT()
HAL_LPTIM_Encoder_Stop_IT()
HAL_LPTIM_TimeOut_Start()
HAL_LPTIM_TimeOut_Stop()
HAL_LPTIM_TimeOut_Start_IT()
HAL_LPTIM_TimeOut_Stop_IT()
HAL_LPTIM_Counter_Start()
HAL_LPTIM_Counter_Stop()
HAL_LPTIM_Counter_Start_IT()
HAL_LPTIM_Counter_Stop_IT()

38.2.4

LPTIM Read operation functions
This section provides LPTIM Reading functions.
Read the counter value.
Read the period (Auto-reload) value.
Read the pulse (Compare)value.
This section contains the following APIs:
HAL_LPTIM_ReadCounter()
HAL_LPTIM_ReadAutoReload()
HAL_LPTIM_ReadCompare()

38.2.5

LPTIM IRQ handler
This section provides LPTIM IRQ handler function.
This section contains the following APIs:
HAL_LPTIM_IRQHandler()
HAL_LPTIM_CompareMatchCallback()
HAL_LPTIM_AutoReloadMatchCallback()
HAL_LPTIM_TriggerCallback()
HAL_LPTIM_CompareWriteCallback()
HAL_LPTIM_AutoReloadWriteCallback()
HAL_LPTIM_DirectionUpCallback()
HAL_LPTIM_DirectionDownCallback()

502/964

DocID025834 Rev 4

UM1725

38.2.6

HAL LPTIM Generic Driver

Peripheral State functions
This subsection permits to get in run-time the status of the peripheral.
This section contains the following APIs:
HAL_LPTIM_GetState()

38.2.7

Detailed description of functions
HAL_LPTIM_Init
Function Name

HAL_StatusTypeDef HAL_LPTIM_Init (LPTIM_HandleTypeDef
* hlptim)

Function Description

Initializes the LPTIM according to the specified parameters in the
LPTIM_InitTypeDef and creates the associated handle.

Parameters

hlptim: LPTIM handle

Return values

HAL: status

HAL_LPTIM_DeInit
Function Name

HAL_StatusTypeDef HAL_LPTIM_DeInit
(LPTIM_HandleTypeDef * hlptim)

Function Description

DeInitializes the LPTIM peripheral.

Parameters

hlptim: LPTIM handle

Return values

HAL: status

HAL_LPTIM_MspInit
Function Name

void HAL_LPTIM_MspInit (LPTIM_HandleTypeDef * hlptim)

Function Description

Initializes the LPTIM MSP.

Parameters

hlptim: LPTIM handle

Return values

None

HAL_LPTIM_MspDeInit
Function Name

void HAL_LPTIM_MspDeInit (LPTIM_HandleTypeDef * hlptim)

Function Description

DeInitializes LPTIM MSP.

Parameters

hlptim: LPTIM handle

Return values

None

HAL_LPTIM_PWM_Start
Function Name

HAL_StatusTypeDef HAL_LPTIM_PWM_Start
(LPTIM_HandleTypeDef * hlptim, uint32_t Period, uint32_t
Pulse)

Function Description

Starts the LPTIM PWM generation.
DocID025834 Rev 4

503/964

HAL LPTIM Generic Driver
Parameters

UM1725
hlptim: : LPTIM handle
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF.
Pulse: : Specifies the compare value. This parameter must
be a value between 0x0000 and 0xFFFF.

Return values

HAL: status

HAL_LPTIM_PWM_Stop
Function Name

HAL_StatusTypeDef HAL_LPTIM_PWM_Stop
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the LPTIM PWM generation.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status

HAL_LPTIM_PWM_Start_IT
Function Name

HAL_StatusTypeDef HAL_LPTIM_PWM_Start_IT
(LPTIM_HandleTypeDef * hlptim, uint32_t Period, uint32_t
Pulse)

Function Description

Starts the LPTIM PWM generation in interrupt mode.

Parameters

hlptim: : LPTIM handle
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF
Pulse: : Specifies the compare value. This parameter must
be a value between 0x0000 and 0xFFFF

Return values

HAL: status

HAL_LPTIM_PWM_Stop_IT
Function Name

HAL_StatusTypeDef HAL_LPTIM_PWM_Stop_IT
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the LPTIM PWM generation in interrupt mode.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status

HAL_LPTIM_OnePulse_Start
Function Name

HAL_StatusTypeDef HAL_LPTIM_OnePulse_Start
(LPTIM_HandleTypeDef * hlptim, uint32_t Period, uint32_t
Pulse)

Function Description

Starts the LPTIM One pulse generation.

Parameters

504/964

hlptim: : LPTIM handle
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF.
Pulse: : Specifies the compare value. This parameter must
be a value between 0x0000 and 0xFFFF.
DocID025834 Rev 4

UM1725

HAL LPTIM Generic Driver
Return values

HAL: status

HAL_LPTIM_OnePulse_Stop
Function Name

HAL_StatusTypeDef HAL_LPTIM_OnePulse_Stop
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the LPTIM One pulse generation.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status

HAL_LPTIM_OnePulse_Start_IT
Function Name

HAL_StatusTypeDef HAL_LPTIM_OnePulse_Start_IT
(LPTIM_HandleTypeDef * hlptim, uint32_t Period, uint32_t
Pulse)

Function Description

Starts the LPTIM One pulse generation in interrupt mode.

Parameters

hlptim: : LPTIM handle
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF.
Pulse: : Specifies the compare value. This parameter must
be a value between 0x0000 and 0xFFFF.

Return values

HAL: status

HAL_LPTIM_OnePulse_Stop_IT
Function Name

HAL_StatusTypeDef HAL_LPTIM_OnePulse_Stop_IT
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the LPTIM One pulse generation in interrupt mode.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status

HAL_LPTIM_SetOnce_Start
Function Name

HAL_StatusTypeDef HAL_LPTIM_SetOnce_Start
(LPTIM_HandleTypeDef * hlptim, uint32_t Period, uint32_t
Pulse)

Function Description

Starts the LPTIM in Set once mode.

Parameters

hlptim: : LPTIM handle
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF.
Pulse: : Specifies the compare value. This parameter must
be a value between 0x0000 and 0xFFFF.

Return values

HAL: status

DocID025834 Rev 4

505/964

HAL LPTIM Generic Driver

UM1725

HAL_LPTIM_SetOnce_Stop
Function Name

HAL_StatusTypeDef HAL_LPTIM_SetOnce_Stop
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the LPTIM Set once mode.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status

HAL_LPTIM_SetOnce_Start_IT
Function Name

HAL_StatusTypeDef HAL_LPTIM_SetOnce_Start_IT
(LPTIM_HandleTypeDef * hlptim, uint32_t Period, uint32_t
Pulse)

Function Description

Starts the LPTIM Set once mode in interrupt mode.

Parameters

hlptim: : LPTIM handle
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF.
Pulse: : Specifies the compare value. This parameter must
be a value between 0x0000 and 0xFFFF.

Return values

HAL: status

HAL_LPTIM_SetOnce_Stop_IT
Function Name

HAL_StatusTypeDef HAL_LPTIM_SetOnce_Stop_IT
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the LPTIM Set once mode in interrupt mode.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status

HAL_LPTIM_Encoder_Start
Function Name

HAL_StatusTypeDef HAL_LPTIM_Encoder_Start
(LPTIM_HandleTypeDef * hlptim, uint32_t Period)

Function Description

Starts the Encoder interface.

Parameters

hlptim: : LPTIM handle
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF.

Return values

HAL: status

HAL_LPTIM_Encoder_Stop

506/964

Function Name

HAL_StatusTypeDef HAL_LPTIM_Encoder_Stop
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the Encoder interface.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status
DocID025834 Rev 4

UM1725

HAL LPTIM Generic Driver

HAL_LPTIM_Encoder_Start_IT
Function Name

HAL_StatusTypeDef HAL_LPTIM_Encoder_Start_IT
(LPTIM_HandleTypeDef * hlptim, uint32_t Period)

Function Description

Starts the Encoder interface in interrupt mode.

Parameters

hlptim: : LPTIM handle
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF.

Return values

HAL: status

HAL_LPTIM_Encoder_Stop_IT
Function Name

HAL_StatusTypeDef HAL_LPTIM_Encoder_Stop_IT
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the Encoder interface in interrupt mode.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status

HAL_LPTIM_TimeOut_Start
Function Name

HAL_StatusTypeDef HAL_LPTIM_TimeOut_Start
(LPTIM_HandleTypeDef * hlptim, uint32_t Period, uint32_t
Timeout)

Function Description

Starts the Timeout function.

Parameters

hlptim: : LPTIM handle
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF.
Timeout: : Specifies the TimeOut value to rest the counter.
This parameter must be a value between 0x0000 and
0xFFFF.

Return values

HAL: status

HAL_LPTIM_TimeOut_Stop
Function Name

HAL_StatusTypeDef HAL_LPTIM_TimeOut_Stop
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the Timeout function.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status

HAL_LPTIM_TimeOut_Start_IT
Function Name

HAL_StatusTypeDef HAL_LPTIM_TimeOut_Start_IT
(LPTIM_HandleTypeDef * hlptim, uint32_t Period, uint32_t
Timeout)

Function Description

Starts the Timeout function in interrupt mode.

Parameters

hlptim: : LPTIM handle
DocID025834 Rev 4

507/964

HAL LPTIM Generic Driver

UM1725
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF.
Timeout: : Specifies the TimeOut value to rest the counter.
This parameter must be a value between 0x0000 and
0xFFFF.

Return values

HAL: status

HAL_LPTIM_TimeOut_Stop_IT
Function Name

HAL_StatusTypeDef HAL_LPTIM_TimeOut_Stop_IT
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the Timeout function in interrupt mode.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status

HAL_LPTIM_Counter_Start
Function Name

HAL_StatusTypeDef HAL_LPTIM_Counter_Start
(LPTIM_HandleTypeDef * hlptim, uint32_t Period)

Function Description

Starts the Counter mode.

Parameters

hlptim: : LPTIM handle
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF.

Return values

HAL: status

HAL_LPTIM_Counter_Stop
Function Name

HAL_StatusTypeDef HAL_LPTIM_Counter_Stop
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the Counter mode.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status

HAL_LPTIM_Counter_Start_IT

508/964

Function Name

HAL_StatusTypeDef HAL_LPTIM_Counter_Start_IT
(LPTIM_HandleTypeDef * hlptim, uint32_t Period)

Function Description

Starts the Counter mode in interrupt mode.

Parameters

hlptim: : LPTIM handle
Period: : Specifies the Autoreload value. This parameter
must be a value between 0x0000 and 0xFFFF.

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL LPTIM Generic Driver

HAL_LPTIM_Counter_Stop_IT
Function Name

HAL_StatusTypeDef HAL_LPTIM_Counter_Stop_IT
(LPTIM_HandleTypeDef * hlptim)

Function Description

Stops the Counter mode in interrupt mode.

Parameters

hlptim: : LPTIM handle

Return values

HAL: status

HAL_LPTIM_ReadCounter
Function Name

uint32_t HAL_LPTIM_ReadCounter (LPTIM_HandleTypeDef *
hlptim)

Function Description

This function returns the current counter value.

Parameters

hlptim: LPTIM handle

Return values

Counter: value.

HAL_LPTIM_ReadAutoReload
Function Name

uint32_t HAL_LPTIM_ReadAutoReload
(LPTIM_HandleTypeDef * hlptim)

Function Description

This function return the current Autoreload (Period) value.

Parameters

hlptim: LPTIM handle

Return values

Autoreload: value.

HAL_LPTIM_ReadCompare
Function Name

uint32_t HAL_LPTIM_ReadCompare (LPTIM_HandleTypeDef *
hlptim)

Function Description

This function return the current Compare (Pulse) value.

Parameters

hlptim: LPTIM handle

Return values

Compare: value.

HAL_LPTIM_IRQHandler
Function Name

void HAL_LPTIM_IRQHandler (LPTIM_HandleTypeDef *
hlptim)

Function Description

This function handles LPTIM interrupt request.

Parameters

hlptim: LPTIM handle

Return values

None

HAL_LPTIM_CompareMatchCallback
Function Name

void HAL_LPTIM_CompareMatchCallback
(LPTIM_HandleTypeDef * hlptim)

Function Description

Compare match callback in non blocking mode.

DocID025834 Rev 4

509/964

HAL LPTIM Generic Driver
Parameters
Return values

UM1725
hlptim: : LPTIM handle
None

HAL_LPTIM_AutoReloadMatchCallback
Function Name

void HAL_LPTIM_AutoReloadMatchCallback
(LPTIM_HandleTypeDef * hlptim)

Function Description

Autoreload match callback in non blocking mode.

Parameters

hlptim: : LPTIM handle

Return values

None

HAL_LPTIM_TriggerCallback
Function Name

void HAL_LPTIM_TriggerCallback (LPTIM_HandleTypeDef *
hlptim)

Function Description

Trigger detected callback in non blocking mode.

Parameters

hlptim: : LPTIM handle

Return values

None

HAL_LPTIM_CompareWriteCallback
Function Name

void HAL_LPTIM_CompareWriteCallback
(LPTIM_HandleTypeDef * hlptim)

Function Description

Compare write callback in non blocking mode.

Parameters

hlptim: : LPTIM handle

Return values

None

HAL_LPTIM_AutoReloadWriteCallback
Function Name

void HAL_LPTIM_AutoReloadWriteCallback
(LPTIM_HandleTypeDef * hlptim)

Function Description

Autoreload write callback in non blocking mode.

Parameters

hlptim: : LPTIM handle

Return values

None

HAL_LPTIM_DirectionUpCallback

510/964

Function Name

void HAL_LPTIM_DirectionUpCallback
(LPTIM_HandleTypeDef * hlptim)

Function Description

Direction counter changed from Down to Up callback in non
blocking mode.

Parameters

hlptim: : LPTIM handle

Return values

None

DocID025834 Rev 4

UM1725

HAL LPTIM Generic Driver

HAL_LPTIM_DirectionDownCallback
Function Name

void HAL_LPTIM_DirectionDownCallback
(LPTIM_HandleTypeDef * hlptim)

Function Description

Direction counter changed from Up to Down callback in non
blocking mode.

Parameters

hlptim: : LPTIM handle

Return values

None

HAL_LPTIM_GetState
Function Name

HAL_LPTIM_StateTypeDef HAL_LPTIM_GetState
(LPTIM_HandleTypeDef * hlptim)

Function Description

Returns the LPTIM state.

Parameters

hlptim: LPTIM handle

Return values

HAL: state

38.3

LPTIM Firmware driver defines

38.3.1

LPTIM
LPTIM Clock Polarity
LPTIM_CLOCKPOLARITY_RISING
LPTIM_CLOCKPOLARITY_FALLING
LPTIM_CLOCKPOLARITY_RISING_FALLING
LPTIM Clock Prescaler
LPTIM_PRESCALER_DIV1
LPTIM_PRESCALER_DIV2
LPTIM_PRESCALER_DIV4
LPTIM_PRESCALER_DIV8
LPTIM_PRESCALER_DIV16
LPTIM_PRESCALER_DIV32
LPTIM_PRESCALER_DIV64
LPTIM_PRESCALER_DIV128
LPTIM Clock Sample Time
LPTIM_CLOCKSAMPLETIME_DIRECTTRANSITION
LPTIM_CLOCKSAMPLETIME_2TRANSITIONS
LPTIM_CLOCKSAMPLETIME_4TRANSITIONS
LPTIM_CLOCKSAMPLETIME_8TRANSITIONS

DocID025834 Rev 4

511/964

HAL LPTIM Generic Driver
LPTIM Clock Source

UM1725

LPTIM_CLOCKSOURCE_APBCLOCK_LPOSC
LPTIM_CLOCKSOURCE_ULPTIM
LPTIM Counter Source
LPTIM_COUNTERSOURCE_INTERNAL
LPTIM_COUNTERSOURCE_EXTERNAL
LPTIM Exported Macros
__HAL_LPTIM_RESET_HANDLE_STATE

Description:
Reset LPTIM handle
state.
Parameters:
__HANDLE__: LPTIM
handle
Return value:
None
Description:

__HAL_LPTIM_ENABLE

Enable/Disable the
LPTIM peripheral.
Parameters:
__HANDLE__: LPTIM
handle
Return value:
None
__HAL_LPTIM_DISABLE
__HAL_LPTIM_START_CONTINUOUS

Description:
Starts the LPTIM
peripheral in Continuous
or in single mode.
Parameters:
__HANDLE__: DMA
handle
Return value:
None

__HAL_LPTIM_START_SINGLE
__HAL_LPTIM_AUTORELOAD_SET

Description:
Writes the passed
parameter in the
Autoreload register.
Parameters:

512/964

DocID025834 Rev 4

UM1725

HAL LPTIM Generic Driver
__HANDLE__: LPTIM
handle
__VALUE__: :
Autoreload value
Return value:
None
__HAL_LPTIM_COMPARE_SET

Description:
Writes the passed
parameter in the
Compare register.
Parameters:
__HANDLE__: LPTIM
handle
__VALUE__: : Compare
value
Return value:
None
Description:

__HAL_LPTIM_GET_FLAG

Checks whether the
specified LPTIM flag is
set or not.
Parameters:
__HANDLE__: LPTIM
handle
__FLAG__: : LPTIM flag
to check This parameter
can be a value of:
LPTIM_FLAG_DO
WN : Counter
direction change up
Flag.
LPTIM_FLAG_UP :
Counter direction
change down to up
Flag.
LPTIM_FLAG_ARR
OK : Autoreload
register update OK
Flag.
LPTIM_FLAG_CMP
OK : Compare
register update OK
Flag.
LPTIM_FLAG_EXT
TRIG : External
trigger edge event
Flag.
LPTIM_FLAG_ARR
DocID025834 Rev 4

513/964

HAL LPTIM Generic Driver

UM1725
M : Autoreload
match Flag.
LPTIM_FLAG_CMP
M : Compare match
Flag.
Return value:
The: state of the
specified flag (SET or
RESET).

__HAL_LPTIM_CLEAR_FLAG

Description:
Clears the specified
LPTIM flag.
Parameters:
__HANDLE__: LPTIM
handle.
__FLAG__: : LPTIM flag
to clear. This parameter
can be a value of:
LPTIM_FLAG_DO
WN : Counter
direction change up
Flag.
LPTIM_FLAG_UP :
Counter direction
change down to up
Flag.
LPTIM_FLAG_ARR
OK : Autoreload
register update OK
Flag.
LPTIM_FLAG_CMP
OK : Compare
register update OK
Flag.
LPTIM_FLAG_EXT
TRIG : External
trigger edge event
Flag.
LPTIM_FLAG_ARR
M : Autoreload
match Flag.
LPTIM_FLAG_CMP
M : Compare match
Flag.
Return value:
None.
Description:

__HAL_LPTIM_ENABLE_IT

Enable the specified
LPTIM interrupt.
514/964

DocID025834 Rev 4

UM1725

HAL LPTIM Generic Driver
Parameters:
__HANDLE__: : LPTIM
handle.
__INTERRUPT__: :
LPTIM interrupt to set.
This parameter can be a
value of:
LPTIM_IT_DOWN :
Counter direction
change up Interrupt.
LPTIM_IT_UP :
Counter direction
change down to up
Interrupt.
LPTIM_IT_ARROK
: Autoreload
register update OK
Interrupt.
LPTIM_IT_CMPOK
: Compare register
update OK
Interrupt.
LPTIM_IT_EXTTRI
G : External trigger
edge event
Interrupt.
LPTIM_IT_ARRM :
Autoreload match
Interrupt.
LPTIM_IT_CMPM :
Compare match
Interrupt.
Return value:
None.
Description:

__HAL_LPTIM_DISABLE_IT

Disable the specified
LPTIM interrupt.
Parameters:
__HANDLE__: : LPTIM
handle.
__INTERRUPT__: :
LPTIM interrupt to set.
This parameter can be a
value of:
LPTIM_IT_DOWN :
Counter direction
change up Interrupt.
LPTIM_IT_UP :
Counter direction
change down to up
Interrupt.
DocID025834 Rev 4

515/964

HAL LPTIM Generic Driver

UM1725
LPTIM_IT_ARROK
: Autoreload
register update OK
Interrupt.
LPTIM_IT_CMPOK
: Compare register
update OK
Interrupt.
LPTIM_IT_EXTTRI
G : External trigger
edge event
Interrupt.
LPTIM_IT_ARRM :
Autoreload match
Interrupt.
LPTIM_IT_CMPM :
Compare match
Interrupt.
Return value:
None.

__HAL_LPTIM_GET_IT_SOURCE

Description:
Checks whether the
specified LPTIM interrupt
is set or not.
Parameters:
__HANDLE__: : LPTIM
handle.
__INTERRUPT__: :
LPTIM interrupt to
check. This parameter
can be a value of:
LPTIM_IT_DOWN :
Counter direction
change up Interrupt.
LPTIM_IT_UP :
Counter direction
change down to up
Interrupt.
LPTIM_IT_ARROK
: Autoreload
register update OK
Interrupt.
LPTIM_IT_CMPOK
: Compare register
update OK
Interrupt.
LPTIM_IT_EXTTRI
G : External trigger
edge event
Interrupt.
LPTIM_IT_ARRM :

516/964

DocID025834 Rev 4

UM1725

HAL LPTIM Generic Driver
Autoreload match
Interrupt.
LPTIM_IT_CMPM :
Compare match
Interrupt.
Return value:
Interrupt: status.
__HAL_LPTIM_OPTR_CONFIG

Description:
LPTIM Option Register.
Parameters:
__HANDLE__: LPTIM
handle
__VALUE__: This
parameter can be a
value of :
LPTIM_OP_PAD_A
F
LPTIM_OP_PAD_P
A4
LPTIM_OP_PAD_P
B9
LPTIM_OP_TIM_D
AC
Return value:
None

__HAL_LPTIM_WAKEUPTIMER_EXTI_ENABLE_IT

Description:
Enable interrupt on the
LPTIM Wake-up Timer
associated Exti line.
Return value:
None

__HAL_LPTIM_WAKEUPTIMER_EXTI_DISABLE_IT

Description:
Disable interrupt on the
LPTIM Wake-up Timer
associated Exti line.
Return value:
None

__HAL_LPTIM_WAKEUPTIMER_EXTI_ENABLE_EVENT

Description:
Enable event on the
LPTIM Wake-up Timer
associated Exti line.
Return value:
None.

DocID025834 Rev 4

517/964

HAL LPTIM Generic Driver
__HAL_LPTIM_WAKEUPTIMER_EXTI_DISABLE_EVENT

UM1725
Description:
Disable event on the
LPTIM Wake-up Timer
associated Exti line.
Return value:
None.

__HAL_LPTIM_WAKEUPTIMER_EXTI_ENABLE_FALLIN
G_EDGE

Description:
Enable falling edge
trigger on the LPTIM
Wake-up Timer
associated Exti line.
Return value:
None.

__HAL_LPTIM_WAKEUPTIMER_EXTI_DISABLE_FALLI
NG_EDGE

Description:
Disable falling edge
trigger on the LPTIM
Wake-up Timer
associated Exti line.
Return value:
None.

__HAL_LPTIM_WAKEUPTIMER_EXTI_ENABLE_RISING
_EDGE

Description:
Enable rising edge
trigger on the LPTIM
Wake-up Timer
associated Exti line.
Return value:
None.

__HAL_LPTIM_WAKEUPTIMER_EXTI_DISABLE_RISIN
G_EDGE

Description:
Disable rising edge
trigger on the LPTIM
Wake-up Timer
associated Exti line.
Return value:
None.

__HAL_LPTIM_WAKEUPTIMER_EXTI_ENABLE_RISING
_FALLING_EDGE

Description:
Enable rising & falling
edge trigger on the
LPTIM Wake-up Timer
associated Exti line.
Return value:
None.

__HAL_LPTIM_WAKEUPTIMER_EXTI_DISABLE_RISIN
518/964

DocID025834 Rev 4

Description:

UM1725

HAL LPTIM Generic Driver
G_FALLING_EDGE

Disable rising & falling
edge trigger on the
LPTIM Wake-up Timer
associated Exti line.
Return value:
None.

__HAL_LPTIM_WAKEUPTIMER_EXTI_GET_FLAG

Description:
Check whether the
LPTIM Wake-up Timer
associated Exti line
interrupt flag is set or
not.
Return value:
Line: Status.

__HAL_LPTIM_WAKEUPTIMER_EXTI_CLEAR_FLAG

Description:
Clear the LPTIM Wakeup Timer associated Exti
line flag.
Return value:
None.

__HAL_LPTIM_WAKEUPTIMER_EXTI_GENERATE_SWI
T

Description:
Generate a Software
interrupt on the LPTIM
Wake-up Timer
associated Exti line.
Return value:
None.

LPTIM External Trigger Polarity
LPTIM_ACTIVEEDGE_RISING
LPTIM_ACTIVEEDGE_FALLING
LPTIM_ACTIVEEDGE_RISING_FALLING
LPTIM Flag Definition
LPTIM_FLAG_DOWN
LPTIM_FLAG_UP
LPTIM_FLAG_ARROK
LPTIM_FLAG_CMPOK
LPTIM_FLAG_EXTTRIG
LPTIM_FLAG_ARRM
LPTIM_FLAG_CMPM
LPTIM Interrupts Definition

DocID025834 Rev 4

519/964

HAL LPTIM Generic Driver
LPTIM_IT_DOWN

UM1725

LPTIM_IT_UP
LPTIM_IT_ARROK
LPTIM_IT_CMPOK
LPTIM_IT_EXTTRIG
LPTIM_IT_ARRM
LPTIM_IT_CMPM
Register Definition
LPTIM_OP_PAD_AF
LPTIM_OP_PAD_PA4
LPTIM_OP_PAD_PB9
LPTIM_OP_TIM_DAC
LPTIM Output Polarity
LPTIM_OUTPUTPOLARITY_HIGH
LPTIM_OUTPUTPOLARITY_LOW
LPTIM Trigger Sample Time
LPTIM_TRIGSAMPLETIME_DIRECTTRANSITION
LPTIM_TRIGSAMPLETIME_2TRANSITIONS
LPTIM_TRIGSAMPLETIME_4TRANSITIONS
LPTIM_TRIGSAMPLETIME_8TRANSITIONS
LPTIM Trigger Source
LPTIM_TRIGSOURCE_SOFTWARE
LPTIM_TRIGSOURCE_0
LPTIM_TRIGSOURCE_1
LPTIM_TRIGSOURCE_2
LPTIM_TRIGSOURCE_3
LPTIM_TRIGSOURCE_4
LPTIM_TRIGSOURCE_5
LPTIM Updating Mode
LPTIM_UPDATE_IMMEDIATE
LPTIM_UPDATE_ENDOFPERIOD
LPTIM WAKEUP Timer EXTI Line
LPTIM_EXTI_LINE_WAKEUPTIMER_EVENT

520/964

External interrupt line 23 Connected to the
LPTIM EXTI Line

DocID025834 Rev 4

UM1725

HAL LTDC Generic Driver

39

HAL LTDC Generic Driver

39.1

LTDC Firmware driver registers structures

39.1.1

LTDC_ColorTypeDef
Data Fields
uint8_t Blue
uint8_t Green
uint8_t Red
uint8_t Reserved

Field Documentation
uint8_t LTDC_ColorTypeDef::Blue
Configures the blue value. This parameter must be a number between Min_Data =
0x00 and Max_Data = 0xFF.
uint8_t LTDC_ColorTypeDef::Green
Configures the green value. This parameter must be a number between Min_Data =
0x00 and Max_Data = 0xFF.
uint8_t LTDC_ColorTypeDef::Red
Configures the red value. This parameter must be a number between Min_Data =
0x00 and Max_Data = 0xFF.
uint8_t LTDC_ColorTypeDef::Reserved
Reserved 0xFF

39.1.2

LTDC_InitTypeDef
Data Fields
uint32_t HSPolarity
uint32_t VSPolarity
uint32_t DEPolarity
uint32_t PCPolarity
uint32_t HorizontalSync
uint32_t VerticalSync
uint32_t AccumulatedHBP
uint32_t AccumulatedVBP
uint32_t AccumulatedActiveW
uint32_t AccumulatedActiveH
uint32_t TotalWidth
uint32_t TotalHeigh
LTDC_ColorTypeDef Backcolor

DocID025834 Rev 4

521/964

HAL LTDC Generic Driver

UM1725

Field Documentation
uint32_t LTDC_InitTypeDef::HSPolarity
configures the horizontal synchronization polarity. This parameter can be one value of
LTDC_HS_POLARITY
uint32_t LTDC_InitTypeDef::VSPolarity
configures the vertical synchronization polarity. This parameter can be one value of
LTDC_VS_POLARITY
uint32_t LTDC_InitTypeDef::DEPolarity
configures the data enable polarity. This parameter can be one of value of
LTDC_DE_POLARITY
uint32_t LTDC_InitTypeDef::PCPolarity
configures the pixel clock polarity. This parameter can be one of value of
LTDC_PC_POLARITY
uint32_t LTDC_InitTypeDef::HorizontalSync
configures the number of Horizontal synchronization width. This parameter must be a
number between Min_Data = 0x000 and Max_Data = 0xFFF.
uint32_t LTDC_InitTypeDef::VerticalSync
configures the number of Vertical synchronization height. This parameter must be a
number between Min_Data = 0x000 and Max_Data = 0x7FF.
uint32_t LTDC_InitTypeDef::AccumulatedHBP
configures the accumulated horizontal back porch width. This parameter must be a
number between Min_Data = LTDC_HorizontalSync and Max_Data = 0xFFF.
uint32_t LTDC_InitTypeDef::AccumulatedVBP
configures the accumulated vertical back porch height. This parameter must be a
number between Min_Data = LTDC_VerticalSync and Max_Data = 0x7FF.
uint32_t LTDC_InitTypeDef::AccumulatedActiveW
configures the accumulated active width. This parameter must be a number between
Min_Data = LTDC_AccumulatedHBP and Max_Data = 0xFFF.
uint32_t LTDC_InitTypeDef::AccumulatedActiveH
configures the accumulated active height. This parameter must be a number between
Min_Data = LTDC_AccumulatedVBP and Max_Data = 0x7FF.
uint32_t LTDC_InitTypeDef::TotalWidth
configures the total width. This parameter must be a number between Min_Data =
LTDC_AccumulatedActiveW and Max_Data = 0xFFF.
uint32_t LTDC_InitTypeDef::TotalHeigh
configures the total height. This parameter must be a number between Min_Data =
LTDC_AccumulatedActiveH and Max_Data = 0x7FF.
LTDC_ColorTypeDef LTDC_InitTypeDef::Backcolor
Configures the background color.

39.1.3

LTDC_LayerCfgTypeDef
Data Fields
uint32_t WindowX0
uint32_t WindowX1
uint32_t WindowY0
uint32_t WindowY1
uint32_t PixelFormat
uint32_t Alpha

522/964

DocID025834 Rev 4

UM1725

HAL LTDC Generic Driver
uint32_t Alpha0
uint32_t BlendingFactor1
uint32_t BlendingFactor2
uint32_t FBStartAdress
uint32_t ImageWidth
uint32_t ImageHeight
LTDC_ColorTypeDef Backcolor

Field Documentation
uint32_t LTDC_LayerCfgTypeDef::WindowX0
Configures the Window Horizontal Start Position. This parameter must be a number
between Min_Data = 0x000 and Max_Data = 0xFFF.
uint32_t LTDC_LayerCfgTypeDef::WindowX1
Configures the Window Horizontal Stop Position. This parameter must be a number
between Min_Data = 0x000 and Max_Data = 0xFFF.
uint32_t LTDC_LayerCfgTypeDef::WindowY0
Configures the Window vertical Start Position. This parameter must be a number
between Min_Data = 0x000 and Max_Data = 0x7FF.
uint32_t LTDC_LayerCfgTypeDef::WindowY1
Configures the Window vertical Stop Position. This parameter must be a number
between Min_Data = 0x0000 and Max_Data = 0x7FF.
uint32_t LTDC_LayerCfgTypeDef::PixelFormat
Specifies the pixel format. This parameter can be one of value of LTDC_Pixelformat
uint32_t LTDC_LayerCfgTypeDef::Alpha
Specifies the constant alpha used for blending. This parameter must be a number
between Min_Data = 0x00 and Max_Data = 0xFF.
uint32_t LTDC_LayerCfgTypeDef::Alpha0
Configures the default alpha value. This parameter must be a number between
Min_Data = 0x00 and Max_Data = 0xFF.
uint32_t LTDC_LayerCfgTypeDef::BlendingFactor1
Select the blending factor 1. This parameter can be one of value of
LTDC_BlendingFactor1
uint32_t LTDC_LayerCfgTypeDef::BlendingFactor2
Select the blending factor 2. This parameter can be one of value of
LTDC_BlendingFactor2
uint32_t LTDC_LayerCfgTypeDef::FBStartAdress
Configures the color frame buffer address
uint32_t LTDC_LayerCfgTypeDef::ImageWidth
Configures the color frame buffer line length. This parameter must be a number
between Min_Data = 0x0000U and Max_Data = 0x1FFF.
uint32_t LTDC_LayerCfgTypeDef::ImageHeight
Specifies the number of line in frame buffer. This parameter must be a number
between Min_Data = 0x000 and Max_Data = 0x7FF.
LTDC_ColorTypeDef LTDC_LayerCfgTypeDef::Backcolor
Configures the layer background color.

DocID025834 Rev 4

523/964

HAL LTDC Generic Driver

39.1.4

UM1725

LTDC_HandleTypeDef
Data Fields
LTDC_TypeDef * Instance
LTDC_InitTypeDef Init
LTDC_LayerCfgTypeDef LayerCfg
HAL_LockTypeDef Lock
__IO HAL_LTDC_StateTypeDef State
__IO uint32_t ErrorCode

Field Documentation
LTDC_TypeDef* LTDC_HandleTypeDef::Instance
LTDC Register base address
LTDC_InitTypeDef LTDC_HandleTypeDef::Init
LTDC parameters
LTDC_LayerCfgTypeDef LTDC_HandleTypeDef::LayerCfg[MAX_LAYER]
LTDC Layers parameters
HAL_LockTypeDef LTDC_HandleTypeDef::Lock
LTDC Lock
__IO HAL_LTDC_StateTypeDef LTDC_HandleTypeDef::State
LTDC state
__IO uint32_t LTDC_HandleTypeDef::ErrorCode
LTDC Error code

39.2

LTDC Firmware driver API description

39.2.1

How to use this driver
1.

2.

3.
4.
5.
6.
7.

524/964

Program the required configuration through the following parameters: the LTDC
timing, the horizontal and vertical polarity, the pixel clock polarity, Data Enable polarity
and the LTDC background color value using HAL_LTDC_Init() function
Program the required configuration through the following parameters: the pixel format,
the blending factors, input alpha value, the window size and the image size using
HAL_LTDC_ConfigLayer() function for foreground or/and background layer.
Optionally, configure and enable the CLUT using HAL_LTDC_ConfigCLUT() and
HAL_LTDC_EnableCLUT functions.
Optionally, enable the Dither using HAL_LTDC_EnableDither().
Optionally, configure and enable the Color keying using
HAL_LTDC_ConfigColorKeying() and HAL_LTDC_EnableColorKeying functions.
Optionally, configure LineInterrupt using HAL_LTDC_ProgramLineEvent() function
If needed, reconfigure and change the pixel format value, the alpha value value, the
window size, the window position and the layer start address for foreground or/and
background layer using respectively the following functions:
HAL_LTDC_SetPixelFormat(), HAL_LTDC_SetAlpha(),
HAL_LTDC_SetWindowSize(), HAL_LTDC_SetWindowPosition(),
HAL_LTDC_SetAddress.
DocID025834 Rev 4

UM1725
8.

9.

HAL LTDC Generic Driver
Variant functions with "_NoReload" post fix allows to set the LTDC
configuration/settings without immediate reload. This is useful in case when the
program requires to modify serval LTDC settings (on one or both layers) then
applying(reload) these settings in one shot by calling the function
"HAL_LTDC_Relaod" After calling the "_NoReload" functions to set different
color/format/layer settings, the program can call the function "HAL_LTDC_Relaod" To
apply(Reload) these settings. Function "HAL_LTDC_Relaod" can be called with the
parameter "ReloadType" set to LTDC_RELOAD_IMMEDIATE if an immediate reload
is required. Function "HAL_LTDC_Relaod" can be called with the parameter
"ReloadType" set to LTDC_RELOAD_VERTICAL_BLANKING if the reload should be
done in the next vertical blanking period, this option allows to avoid display flicker by
applying the new settings during the vertical blanking period.
To control LTDC state you can use the following function: HAL_LTDC_GetState()

LTDC HAL driver macros list
Below the list of most used macros in LTDC HAL driver.
__HAL_LTDC_ENABLE: Enable the LTDC.
__HAL_LTDC_DISABLE: Disable the LTDC.
__HAL_LTDC_LAYER_ENABLE: Enable the LTDC Layer.
__HAL_LTDC_LAYER_DISABLE: Disable the LTDC Layer.
__HAL_LTDC_RELOAD_CONFIG: Reload Layer Configuration.
__HAL_LTDC_GET_FLAG: Get the LTDC pending flags.
__HAL_LTDC_CLEAR_FLAG: Clear the LTDC pending flags.
__HAL_LTDC_ENABLE_IT: Enable the specified LTDC interrupts.
__HAL_LTDC_DISABLE_IT: Disable the specified LTDC interrupts.
__HAL_LTDC_GET_IT_SOURCE: Check whether the specified LTDC interrupt has
occurred or not.
You can refer to the LTDC HAL driver header file for more useful macros

39.2.2

Initialization and Configuration functions
This section provides functions allowing to:
Initialize and configure the LTDC
De-initialize the LTDC
This section contains the following APIs:
HAL_LTDC_Init()
HAL_LTDC_DeInit()
HAL_LTDC_MspInit()
HAL_LTDC_MspDeInit()
HAL_LTDC_ErrorCallback()
HAL_LTDC_LineEventCallback()
HAL_LTDC_ReloadEventCallback()

39.2.3

IO operation functions
This section provides function allowing to:
Handle LTDC interrupt request
DocID025834 Rev 4

525/964

HAL LTDC Generic Driver
This section contains the following APIs:
HAL_LTDC_IRQHandler()
HAL_LTDC_ErrorCallback()
HAL_LTDC_LineEventCallback()
HAL_LTDC_ReloadEventCallback()

39.2.4

Peripheral Control functions
This section provides functions allowing to:
Configure the LTDC foreground or/and background parameters.
Set the active layer.
Configure the color keying.
Configure the C-LUT.
Enable / Disable the color keying.
Enable / Disable the C-LUT.
Update the layer position.
Update the layer size.
Update pixel format on the fly.
Update transparency on the fly.
Update address on the fly.
This section contains the following APIs:
HAL_LTDC_ConfigLayer()
HAL_LTDC_ConfigColorKeying()
HAL_LTDC_ConfigCLUT()
HAL_LTDC_EnableColorKeying()
HAL_LTDC_DisableColorKeying()
HAL_LTDC_EnableCLUT()
HAL_LTDC_DisableCLUT()
HAL_LTDC_EnableDither()
HAL_LTDC_DisableDither()
HAL_LTDC_SetWindowSize()
HAL_LTDC_SetWindowPosition()
HAL_LTDC_SetPixelFormat()
HAL_LTDC_SetAlpha()
HAL_LTDC_SetAddress()
HAL_LTDC_SetPitch()
HAL_LTDC_ProgramLineEvent()
HAL_LTDC_Relaod()
HAL_LTDC_ConfigLayer_NoReload()
HAL_LTDC_SetWindowSize_NoReload()
HAL_LTDC_SetWindowPosition_NoReload()
HAL_LTDC_SetPixelFormat_NoReload()
HAL_LTDC_SetAlpha_NoReload()
HAL_LTDC_SetAddress_NoReload()
HAL_LTDC_SetPitch_NoReload()
HAL_LTDC_ConfigColorKeying_NoReload()
HAL_LTDC_EnableColorKeying_NoReload()
HAL_LTDC_DisableColorKeying_NoReload()
HAL_LTDC_EnableCLUT_NoReload()
HAL_LTDC_DisableCLUT_NoReload()

526/964

DocID025834 Rev 4

UM1725

UM1725

39.2.5

HAL LTDC Generic Driver

Peripheral State and Errors functions
This subsection provides functions allowing to
Check the LTDC state.
Get error code.
This section contains the following APIs:
HAL_LTDC_GetState()
HAL_LTDC_GetError()

39.2.6

Detailed description of functions
HAL_LTDC_Init
Function Name

HAL_StatusTypeDef HAL_LTDC_Init (LTDC_HandleTypeDef *
hltdc)

Function Description

Initializes the LTDC according to the specified parameters in the
LTDC_InitTypeDef and create the associated handle.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

HAL: status

HAL_LTDC_DeInit
Function Name

HAL_StatusTypeDef HAL_LTDC_DeInit (LTDC_HandleTypeDef
* hltdc)

Function Description

Deinitializes the LTDC peripheral registers to their default reset
values.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

None

HAL_LTDC_MspInit
Function Name

void HAL_LTDC_MspInit (LTDC_HandleTypeDef * hltdc)

Function Description

Initializes the LTDC MSP.

Parameters

hltdc: : pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

None

HAL_LTDC_MspDeInit
Function Name

void HAL_LTDC_MspDeInit (LTDC_HandleTypeDef * hltdc)

Function Description

DeInitializes the LTDC MSP.

Parameters

hltdc: : pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

None

DocID025834 Rev 4

527/964

HAL LTDC Generic Driver

UM1725

HAL_LTDC_ErrorCallback
Function Name

void HAL_LTDC_ErrorCallback (LTDC_HandleTypeDef * hltdc)

Function Description

Error LTDC callback.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

None

HAL_LTDC_LineEventCallback
Function Name

void HAL_LTDC_LineEventCallback (LTDC_HandleTypeDef *
hltdc)

Function Description

Line Event callback.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

None

HAL_LTDC_ReloadEventCallback
Function Name

void HAL_LTDC_ReloadEventCallback (LTDC_HandleTypeDef
* hltdc)

Function Description

Reload Event callback.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

None

HAL_LTDC_IRQHandler
Function Name

void HAL_LTDC_IRQHandler (LTDC_HandleTypeDef * hltdc)

Function Description

Handles LTDC interrupt request.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

HAL: status

HAL_LTDC_ConfigLayer
Function Name

HAL_StatusTypeDef HAL_LTDC_ConfigLayer
(LTDC_HandleTypeDef * hltdc, LTDC_LayerCfgTypeDef *
pLayerCfg, uint32_t LayerIdx)

Function Description

Configure the LTDC Layer according to the specified parameters
in the LTDC_InitTypeDef and create the associated handle.

Parameters

528/964

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
pLayerCfg: pointer to a LTDC_LayerCfgTypeDef structure
that contains the configuration information for the Layer.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1
DocID025834 Rev 4

UM1725

HAL LTDC Generic Driver
Return values

HAL: status

HAL_LTDC_SetWindowSize
Function Name

HAL_StatusTypeDef HAL_LTDC_SetWindowSize
(LTDC_HandleTypeDef * hltdc, uint32_t XSize, uint32_t YSize,
uint32_t LayerIdx)

Function Description

Set the LTDC window size.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
XSize: LTDC Pixel per line
YSize: LTDC Line number
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_SetWindowPosition
Function Name

HAL_StatusTypeDef HAL_LTDC_SetWindowPosition
(LTDC_HandleTypeDef * hltdc, uint32_t X0, uint32_t Y0,
uint32_t LayerIdx)

Function Description

Set the LTDC window position.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
X0: LTDC window X offset
Y0: LTDC window Y offset
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_SetPixelFormat
Function Name

HAL_StatusTypeDef HAL_LTDC_SetPixelFormat
(LTDC_HandleTypeDef * hltdc, uint32_t Pixelformat, uint32_t
LayerIdx)

Function Description

Reconfigure the pixel format.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
Pixelformat: new pixel format value.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1.

Return values

HAL: status

HAL_LTDC_SetAlpha
Function Name

HAL_StatusTypeDef HAL_LTDC_SetAlpha
(LTDC_HandleTypeDef * hltdc, uint32_t Alpha, uint32_t
LayerIdx)

DocID025834 Rev 4

529/964

HAL LTDC Generic Driver
Function Description

UM1725
Reconfigure the layer alpha value.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
Alpha: new alpha value.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_SetAddress
Function Name

HAL_StatusTypeDef HAL_LTDC_SetAddress
(LTDC_HandleTypeDef * hltdc, uint32_t Address, uint32_t
LayerIdx)

Function Description

Reconfigure the frame buffer Address.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
Address: new address value.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1.

Return values

HAL: status

HAL_LTDC_SetPitch
Function Name

HAL_StatusTypeDef HAL_LTDC_SetPitch
(LTDC_HandleTypeDef * hltdc, uint32_t LinePitchInPixels,
uint32_t LayerIdx)

Function Description

Function used to reconfigure the pitch for specific cases where the
attached LayerIdx buffer have a width that is larger than the one
intended to be displayed on screen.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
LinePitchInPixels: New line pitch in pixels to configure for
LTDC layer 'LayerIdx'.
LayerIdx: LTDC layer index concerned by the modification of
line pitch.

Return values

HAL: status

HAL_LTDC_ConfigColorKeying
Function Name

HAL_StatusTypeDef HAL_LTDC_ConfigColorKeying
(LTDC_HandleTypeDef * hltdc, uint32_t RGBValue, uint32_t
LayerIdx)

Function Description

Configure the color keying.

Parameters

530/964

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
RGBValue: the color key value
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

DocID025834 Rev 4

UM1725

HAL LTDC Generic Driver
Return values

HAL: status

HAL_LTDC_ConfigCLUT
Function Name

HAL_StatusTypeDef HAL_LTDC_ConfigCLUT
(LTDC_HandleTypeDef * hltdc, uint32_t * pCLUT, uint32_t
CLUTSize, uint32_t LayerIdx)

Function Description

Load the color lookup table.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
pCLUT: pointer to the color lookup table address.
CLUTSize: the color lookup table size.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_EnableColorKeying
Function Name

HAL_StatusTypeDef HAL_LTDC_EnableColorKeying
(LTDC_HandleTypeDef * hltdc, uint32_t LayerIdx)

Function Description

Enable the color keying.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_DisableColorKeying
Function Name

HAL_StatusTypeDef HAL_LTDC_DisableColorKeying
(LTDC_HandleTypeDef * hltdc, uint32_t LayerIdx)

Function Description

Disable the color keying.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_EnableCLUT
Function Name

HAL_StatusTypeDef HAL_LTDC_EnableCLUT
(LTDC_HandleTypeDef * hltdc, uint32_t LayerIdx)

Function Description

Enable the color lookup table.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

DocID025834 Rev 4

531/964

HAL LTDC Generic Driver
Return values

UM1725
HAL: status

HAL_LTDC_DisableCLUT
Function Name

HAL_StatusTypeDef HAL_LTDC_DisableCLUT
(LTDC_HandleTypeDef * hltdc, uint32_t LayerIdx)

Function Description

Disable the color lookup table.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_ProgramLineEvent
Function Name

HAL_StatusTypeDef HAL_LTDC_ProgramLineEvent
(LTDC_HandleTypeDef * hltdc, uint32_t Line)

Function Description

Define the position of the line interrupt .

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
Line: Line Interrupt Position.

Return values

HAL: status

HAL_LTDC_EnableDither
Function Name

HAL_StatusTypeDef HAL_LTDC_EnableDither
(LTDC_HandleTypeDef * hltdc)

Function Description

Enables Dither.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

HAL: status

HAL_LTDC_DisableDither
Function Name

HAL_StatusTypeDef HAL_LTDC_DisableDither
(LTDC_HandleTypeDef * hltdc)

Function Description

Disables Dither.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

HAL: status

HAL_LTDC_Relaod

532/964

Function Name

HAL_StatusTypeDef HAL_LTDC_Relaod
(LTDC_HandleTypeDef * hltdc, uint32_t ReloadType)

Function Description

LTDC configuration relaod .

DocID025834 Rev 4

UM1725

HAL LTDC Generic Driver
Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
ReloadType: This parameter can be one of the following
values : LTDC_RELOAD_IMMEDIATE : Immediate Reload
LTDC_SRCR_VBR : Reload in the next Vertical Blanking

Return values

HAL: status

HAL_LTDC_ConfigLayer_NoReload
Function Name

HAL_StatusTypeDef HAL_LTDC_ConfigLayer_NoReload
(LTDC_HandleTypeDef * hltdc, LTDC_LayerCfgTypeDef *
pLayerCfg, uint32_t LayerIdx)

Function Description

Configure the LTDC Layer according to the specified without
reloading parameters in the LTDC_InitTypeDef and create the
associated handle.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
pLayerCfg: pointer to a LTDC_LayerCfgTypeDef structure
that contains the configuration information for the Layer.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_SetWindowSize_NoReload
Function Name

HAL_StatusTypeDef HAL_LTDC_SetWindowSize_NoReload
(LTDC_HandleTypeDef * hltdc, uint32_t XSize, uint32_t YSize,
uint32_t LayerIdx)

Function Description

Set the LTDC window size without reloading.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
XSize: LTDC Pixel per line
YSize: LTDC Line number
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_SetWindowPosition_NoReload
Function Name

HAL_StatusTypeDef
HAL_LTDC_SetWindowPosition_NoReload
(LTDC_HandleTypeDef * hltdc, uint32_t X0, uint32_t Y0,
uint32_t LayerIdx)

Function Description

Set the LTDC window position without reloading.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
X0: LTDC window X offset
Y0: LTDC window Y offset
LayerIdx: LTDC Layer index. This parameter can be one of
DocID025834 Rev 4

533/964

HAL LTDC Generic Driver

UM1725
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_SetPixelFormat_NoReload
Function Name

HAL_StatusTypeDef HAL_LTDC_SetPixelFormat_NoReload
(LTDC_HandleTypeDef * hltdc, uint32_t Pixelformat, uint32_t
LayerIdx)

Function Description

Reconfigure the pixel format without reloading.

Parameters

hltdc: pointer to a LTDC_HandleTypeDfef structure that
contains the configuration information for the LTDC.
Pixelformat: new pixel format value.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1.

Return values

HAL: status

HAL_LTDC_SetAlpha_NoReload
Function Name

HAL_StatusTypeDef HAL_LTDC_SetAlpha_NoReload
(LTDC_HandleTypeDef * hltdc, uint32_t Alpha, uint32_t
LayerIdx)

Function Description

Reconfigure the layer alpha value without reloading.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
Alpha: new alpha value.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_SetAddress_NoReload
Function Name

HAL_StatusTypeDef HAL_LTDC_SetAddress_NoReload
(LTDC_HandleTypeDef * hltdc, uint32_t Address, uint32_t
LayerIdx)

Function Description

Reconfigure the frame buffer Address without reloading.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
Address: new address value.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1.

Return values

HAL: status

HAL_LTDC_SetPitch_NoReload

534/964

Function Name

HAL_StatusTypeDef HAL_LTDC_SetPitch_NoReload
(LTDC_HandleTypeDef * hltdc, uint32_t LinePitchInPixels,
uint32_t LayerIdx)

Function Description

Function used to reconfigure the pitch for specific cases where the
DocID025834 Rev 4

UM1725

HAL LTDC Generic Driver
attached LayerIdx buffer have a width that is larger than the one
intended to be displayed on screen.
Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
LinePitchInPixels: New line pitch in pixels to configure for
LTDC layer 'LayerIdx'.
LayerIdx: LTDC layer index concerned by the modification of
line pitch.

Return values

HAL: status

HAL_LTDC_ConfigColorKeying_NoReload
Function Name

HAL_StatusTypeDef
HAL_LTDC_ConfigColorKeying_NoReload
(LTDC_HandleTypeDef * hltdc, uint32_t RGBValue, uint32_t
LayerIdx)

Function Description

Configure the color keying without reloading.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
RGBValue: the color key value
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_EnableColorKeying_NoReload
Function Name

HAL_StatusTypeDef
HAL_LTDC_EnableColorKeying_NoReload
(LTDC_HandleTypeDef * hltdc, uint32_t LayerIdx)

Function Description

Enable the color keying without reloading.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_DisableColorKeying_NoReload
Function Name

HAL_StatusTypeDef
HAL_LTDC_DisableColorKeying_NoReload
(LTDC_HandleTypeDef * hltdc, uint32_t LayerIdx)

Function Description

Disable the color keying without reloading.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

DocID025834 Rev 4

535/964

HAL LTDC Generic Driver

UM1725

HAL_LTDC_EnableCLUT_NoReload
Function Name

HAL_StatusTypeDef HAL_LTDC_EnableCLUT_NoReload
(LTDC_HandleTypeDef * hltdc, uint32_t LayerIdx)

Function Description

Enable the color lookup table without reloading.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_DisableCLUT_NoReload
Function Name

HAL_StatusTypeDef HAL_LTDC_DisableCLUT_NoReload
(LTDC_HandleTypeDef * hltdc, uint32_t LayerIdx)

Function Description

Disable the color lookup table without reloading.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
LayerIdx: LTDC Layer index. This parameter can be one of
the following values: 0 or 1

Return values

HAL: status

HAL_LTDC_GetState
Function Name

HAL_LTDC_StateTypeDef HAL_LTDC_GetState
(LTDC_HandleTypeDef * hltdc)

Function Description

Return the LTDC state.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

HAL: state

HAL_LTDC_GetError

536/964

Function Name

uint32_t HAL_LTDC_GetError (LTDC_HandleTypeDef * hltdc)

Function Description

Return the LTDC error code.

Parameters

hltdc: : pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.

Return values

LTDC: Error Code

DocID025834 Rev 4

UM1725

HAL LTDC Generic Driver

39.3

LTDC Firmware driver defines

39.3.1

LTDC
LTDC Alpha
LTDC_ALPHA

LTDC Cte Alpha mask

LTDC BACK COLOR
LTDC_COLOR

Color mask

LTDC Blending Factor1
LTDC_BLENDING_FACTOR1_CA

Blending factor : Cte Alpha

LTDC_BLENDING_FACTOR1_PAxCA

Blending factor : Cte Alpha x Pixel Alpha

LTDC Blending Factor2
LTDC_BLENDING_FACTOR2_CA

Blending factor : Cte Alpha

LTDC_BLENDING_FACTOR2_PAxCA

Blending factor : Cte Alpha x Pixel Alpha

LTDC DE POLARITY
LTDC_DEPOLARITY_AL

Data Enable, is active low.

LTDC_DEPOLARITY_AH

Data Enable, is active high.

LTDC Error Code
HAL_LTDC_ERROR_NONE

LTDC No error

HAL_LTDC_ERROR_TE

LTDC Transfer error

HAL_LTDC_ERROR_FU

LTDC FIFO Underrun

HAL_LTDC_ERROR_TIMEOUT

LTDC Timeout error

LTDC Exported Macros
__HAL_LTDC_RESET_HANDLE_STATE

Description:
Reset LTDC handle state.
Parameters:
__HANDLE__: specifies the LTDC
handle.
Return value:
None

__HAL_LTDC_ENABLE

Description:
Enable the LTDC.
Parameters:
__HANDLE__: LTDC handle
Return value:
None.

__HAL_LTDC_DISABLE

Description:
Disable the LTDC.
DocID025834 Rev 4

537/964

HAL LTDC Generic Driver

UM1725
Parameters:
__HANDLE__: LTDC handle
Return value:
None.

__HAL_LTDC_LAYER_ENABLE

Description:
Enable the LTDC Layer.
Parameters:
__HANDLE__: LTDC handle
__LAYER__: Specify the layer to be
enabled This parameter can be 0 or 1
Return value:
None.

__HAL_LTDC_LAYER_DISABLE

Description:
Disable the LTDC Layer.
Parameters:
__HANDLE__: LTDC handle
__LAYER__: Specify the layer to be
disabled This parameter can be 0 or 1
Return value:
None.

__HAL_LTDC_RELOAD_CONFIG

Description:
Reload Layer Configuration.
Parameters:
__HANDLE__: LTDC handle
Return value:
None.

__HAL_LTDC_GET_FLAG

Description:
Get the LTDC pending flags.
Parameters:
__HANDLE__: LTDC handle
__FLAG__: Get the specified flag. This
parameter can be any combination of the
following values:
LTDC_FLAG_LI: Line Interrupt flag
LTDC_FLAG_FU: FIFO Underrun
Interrupt flag
LTDC_FLAG_TE: Transfer Error
interrupt flag
LTDC_FLAG_RR: Register Reload
Interrupt Flag

538/964

DocID025834 Rev 4

UM1725

HAL LTDC Generic Driver
Return value:
The: state of FLAG (SET or RESET).
__HAL_LTDC_CLEAR_FLAG

Description:
Clears the LTDC pending flags.
Parameters:
__HANDLE__: LTDC handle
__FLAG__: specifies the flag to clear.
This parameter can be any combination
of the following values:
LTDC_FLAG_LI: Line Interrupt flag
LTDC_FLAG_FU: FIFO Underrun
Interrupt flag
LTDC_FLAG_TE: Transfer Error
interrupt flag
LTDC_FLAG_RR: Register Reload
Interrupt Flag
Return value:
None

__HAL_LTDC_ENABLE_IT

Description:
Enables the specified LTDC interrupts.
Parameters:
__HANDLE__: LTDC handle
__INTERRUPT__: specifies the LTDC
interrupt sources to be enabled. This
parameter can be any combination of the
following values:
LTDC_IT_LI: Line Interrupt flag
LTDC_IT_FU: FIFO Underrun
Interrupt flag
LTDC_IT_TE: Transfer Error
interrupt flag
LTDC_IT_RR: Register Reload
Interrupt Flag
Return value:
None

__HAL_LTDC_DISABLE_IT

Description:
Disables the specified LTDC interrupts.
Parameters:
__HANDLE__: LTDC handle
__INTERRUPT__: specifies the LTDC
interrupt sources to be disabled. This
parameter can be any combination of the
following values:
LTDC_IT_LI: Line Interrupt flag
LTDC_IT_FU: FIFO Underrun
DocID025834 Rev 4

539/964

HAL LTDC Generic Driver

UM1725
Interrupt flag
LTDC_IT_TE: Transfer Error
interrupt flag
LTDC_IT_RR: Register Reload
Interrupt Flag
Return value:
None

__HAL_LTDC_GET_IT_SOURCE

Description:
Checks whether the specified LTDC
interrupt has occurred or not.
Parameters:
__HANDLE__: LTDC handle
__INTERRUPT__: specifies the LTDC
interrupt source to check. This parameter
can be one of the following values:
LTDC_IT_LI: Line Interrupt flag
LTDC_IT_FU: FIFO Underrun
Interrupt flag
LTDC_IT_TE: Transfer Error
interrupt flag
LTDC_IT_RR: Register Reload
Interrupt Flag
Return value:
The: state of INTERRUPT (SET or
RESET).

LTDC Exported Types
MAX_LAYER
LTDC Flag
LTDC_FLAG_LI
LTDC_FLAG_FU
LTDC_FLAG_TE
LTDC_FLAG_RR
LTDC HS POLARITY
LTDC_HSPOLARITY_AL

Horizontal Synchronization is active low.

LTDC_HSPOLARITY_AH

Horizontal Synchronization is active high.

LTDC Interrupts
LTDC_IT_LI
LTDC_IT_FU
LTDC_IT_TE
LTDC_IT_RR
LTDC LAYER Config

540/964

DocID025834 Rev 4

UM1725

HAL LTDC Generic Driver
LTDC_STOPPOSITION

LTDC Layer stop position

LTDC_STARTPOSITION

LTDC Layer start position

LTDC_COLOR_FRAME_BUFFER

LTDC Layer Line length

LTDC_LINE_NUMBER

LTDC Layer Line number

LTDC PC POLARITY
LTDC_PCPOLARITY_IPC

input pixel clock.

LTDC_PCPOLARITY_IIPC

inverted input pixel clock.

LTDC Pixel format
LTDC_PIXEL_FORMAT_ARGB8888

ARGB8888 LTDC pixel format

LTDC_PIXEL_FORMAT_RGB888

RGB888 LTDC pixel format

LTDC_PIXEL_FORMAT_RGB565

RGB565 LTDC pixel format

LTDC_PIXEL_FORMAT_ARGB1555

ARGB1555 LTDC pixel format

LTDC_PIXEL_FORMAT_ARGB4444

ARGB4444 LTDC pixel format

LTDC_PIXEL_FORMAT_L8

L8 LTDC pixel format

LTDC_PIXEL_FORMAT_AL44

AL44 LTDC pixel format

LTDC_PIXEL_FORMAT_AL88

AL88 LTDC pixel format

LTDC Reload Type
LTDC_RELOAD_IMMEDIATE

Immediate Reload

LTDC_RELOAD_VERTICAL_BLANKING

Vertical Blanking Reload

LTDC SYNC
LTDC_HORIZONTALSYNC

Horizontal synchronization width.

LTDC_VERTICALSYNC

Vertical synchronization height.

LTDC VS POLARITY
LTDC_VSPOLARITY_AL

Vertical Synchronization is active low.

LTDC_VSPOLARITY_AH

Vertical Synchronization is active high.

DocID025834 Rev 4

541/964

HAL LTDC Extension Driver

UM1725

40

HAL LTDC Extension Driver

40.1

LTDCEx Firmware driver API description

40.1.1

Initialization and Configuration functions
This section provides functions allowing to:
Initialize and configure the LTDC
This section contains the following APIs:
HAL_LTDC_StructInitFromVideoConfig()
HAL_LTDC_StructInitFromAdaptedCommandConfig()

40.1.2

Detailed description of functions
HAL_LTDC_StructInitFromVideoConfig
Function Name

HAL_StatusTypeDef HAL_LTDC_StructInitFromVideoConfig
(LTDC_HandleTypeDef * hltdc, DSI_VidCfgTypeDef * VidCfg)

Function Description

Retrieve common parameters from DSI Video mode configuration
structure.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
VidCfg: pointer to a DSI_VidCfgTypeDef structure that
contains the DSI video mode configuration parameters

Return values

HAL: status

Notes

The implementation of this function is taking into account the
LTDC polarities inversion as described in the current LTDC
specification

HAL_LTDC_StructInitFromAdaptedCommandConfig

542/964

Function Name

HAL_StatusTypeDef
HAL_LTDC_StructInitFromAdaptedCommandConfig
(LTDC_HandleTypeDef * hltdc, DSI_CmdCfgTypeDef *
CmdCfg)

Function Description

Retrieve common parameters from DSI Adapted command mode
configuration structure.

Parameters

hltdc: pointer to a LTDC_HandleTypeDef structure that
contains the configuration information for the LTDC.
CmdCfg: pointer to a DSI_CmdCfgTypeDef structure that
contains the DSI command mode configuration parameters

Return values

HAL: status

Notes

The implementation of this function is taking into account the
LTDC polarities inversion as described in the current LTDC
specification

DocID025834 Rev 4

UM1725

HAL NAND Generic Driver

41

HAL NAND Generic Driver

41.1

NAND Firmware driver registers structures

41.1.1

NAND_IDTypeDef
Data Fields
uint8_t Maker_Id
uint8_t Device_Id
uint8_t Third_Id
uint8_t Fourth_Id

Field Documentation
uint8_t NAND_IDTypeDef::Maker_Id
uint8_t NAND_IDTypeDef::Device_Id
uint8_t NAND_IDTypeDef::Third_Id
uint8_t NAND_IDTypeDef::Fourth_Id

41.1.2

NAND_AddressTypeDef
Data Fields
uint16_t Page
uint16_t Zone
uint16_t Block

Field Documentation
uint16_t NAND_AddressTypeDef::Page
NAND memory Page address
uint16_t NAND_AddressTypeDef::Zone
NAND memory Zone address
uint16_t NAND_AddressTypeDef::Block
NAND memory Block address

41.1.3

NAND_InfoTypeDef
Data Fields
uint32_t PageSize
uint32_t SpareAreaSize
uint32_t BlockSize
uint32_t BlockNbr
DocID025834 Rev 4

543/964

HAL NAND Generic Driver

UM1725

uint32_t ZoneSize

Field Documentation
uint32_t NAND_InfoTypeDef::PageSize
NAND memory page (without spare area) size measured in K. bytes
uint32_t NAND_InfoTypeDef::SpareAreaSize
NAND memory spare area size measured in K. bytes
uint32_t NAND_InfoTypeDef::BlockSize
NAND memory block size number of pages
uint32_t NAND_InfoTypeDef::BlockNbr
NAND memory number of blocks
uint32_t NAND_InfoTypeDef::ZoneSize
NAND memory zone size measured in number of blocks

41.1.4

NAND_HandleTypeDef
Data Fields
FMC_NAND_TypeDef * Instance
FMC_NAND_InitTypeDef Init
HAL_LockTypeDef Lock
__IO HAL_NAND_StateTypeDef State
NAND_InfoTypeDef Info

Field Documentation
FMC_NAND_TypeDef* NAND_HandleTypeDef::Instance
Register base address
FMC_NAND_InitTypeDef NAND_HandleTypeDef::Init
NAND device control configuration parameters
HAL_LockTypeDef NAND_HandleTypeDef::Lock
NAND locking object
__IO HAL_NAND_StateTypeDef NAND_HandleTypeDef::State
NAND device access state
NAND_InfoTypeDef NAND_HandleTypeDef::Info
NAND characteristic information structure

41.2

NAND Firmware driver API description

41.2.1

How to use this driver
This driver is a generic layered driver which contains a set of APIs used to control NAND
flash memories. It uses the FMC/FSMC layer functions to interface with NAND devices.
This driver is used as follows:
NAND flash memory configuration sequence using the function HAL_NAND_Init()
with control and timing parameters for both common and attribute spaces.

544/964

DocID025834 Rev 4

UM1725

HAL NAND Generic Driver
Read NAND flash memory maker and device IDs using the function
HAL_NAND_Read_ID(). The read information is stored in the NAND_ID_TypeDef
structure declared by the function caller.
Access NAND flash memory by read/write operations using the functions
HAL_NAND_Read_Page()/HAL_NAND_Read_SpareArea(),
HAL_NAND_Write_Page()/HAL_NAND_Write_SpareArea() to read/write
page(s)/spare area(s). These functions use specific device information (Block, page
size..) predefined by the user in the HAL_NAND_Info_TypeDef structure. The
read/write address information is contained by the Nand_Address_Typedef structure
passed as parameter.
Perform NAND flash Reset chip operation using the function HAL_NAND_Reset().
Perform NAND flash erase block operation using the function
HAL_NAND_Erase_Block(). The erase block address information is contained in the
Nand_Address_Typedef structure passed as parameter.
Read the NAND flash status operation using the function HAL_NAND_Read_Status().
You can also control the NAND device by calling the control APIs
HAL_NAND_ECC_Enable()/ HAL_NAND_ECC_Disable() to respectively
enable/disable the ECC code correction feature or the function HAL_NAND_GetECC()
to get the ECC correction code.
You can monitor the NAND device HAL state by calling the function
HAL_NAND_GetState()
This driver is a set of generic APIs which handle standard NAND flash
operations. If a NAND flash device contains different operations and/or
implementations, it should be implemented separately.

41.2.2

NAND Initialization and de-initialization functions
This section provides functions allowing to initialize/de-initialize the NAND memory
This section contains the following APIs:
HAL_NAND_Init()
HAL_NAND_DeInit()
HAL_NAND_MspInit()
HAL_NAND_MspDeInit()
HAL_NAND_IRQHandler()
HAL_NAND_ITCallback()

41.2.3

NAND Input and Output functions
This section provides functions allowing to use and control the NAND memory
This section contains the following APIs:
HAL_NAND_Read_ID()
HAL_NAND_Reset()
HAL_NAND_Read_Page()
HAL_NAND_Write_Page()
HAL_NAND_Read_SpareArea()
HAL_NAND_Write_SpareArea()
HAL_NAND_Erase_Block()
HAL_NAND_Read_Status()
HAL_NAND_Address_Inc()

DocID025834 Rev 4

545/964

HAL NAND Generic Driver

41.2.4

UM1725

NAND Control functions
This subsection provides a set of functions allowing to control dynamically the NAND
interface.
This section contains the following APIs:
HAL_NAND_ECC_Enable()
HAL_NAND_ECC_Disable()
HAL_NAND_GetECC()

41.2.5

NAND State functions
This subsection permits to get in run-time the status of the NAND controller and the data
flow.
This section contains the following APIs:
HAL_NAND_GetState()
HAL_NAND_Read_Status()

41.2.6

Detailed description of functions
HAL_NAND_Init
Function Name

HAL_StatusTypeDef HAL_NAND_Init (NAND_HandleTypeDef *
hnand, FMC_NAND_PCC_TimingTypeDef *
ComSpace_Timing, FMC_NAND_PCC_TimingTypeDef *
AttSpace_Timing)

Function Description

Perform NAND memory Initialization sequence.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.
ComSpace_Timing: pointer to Common space timing
structure
AttSpace_Timing: pointer to Attribute space timing structure

Return values

HAL: status

HAL_NAND_DeInit
Function Name

HAL_StatusTypeDef HAL_NAND_DeInit
(NAND_HandleTypeDef * hnand)

Function Description

Perform NAND memory De-Initialization sequence.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.

Return values

HAL: status

HAL_NAND_MspInit
Function Name

void HAL_NAND_MspInit (NAND_HandleTypeDef * hnand)

Function Description

NAND MSP Init.

Parameters

546/964

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.

DocID025834 Rev 4

UM1725

HAL NAND Generic Driver
Return values

None

HAL_NAND_MspDeInit
Function Name

void HAL_NAND_MspDeInit (NAND_HandleTypeDef * hnand)

Function Description

NAND MSP DeInit.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.

Return values

None

HAL_NAND_IRQHandler
Function Name

void HAL_NAND_IRQHandler (NAND_HandleTypeDef * hnand)

Function Description

This function handles NAND device interrupt request.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.

Return values

HAL: status

HAL_NAND_ITCallback
Function Name

void HAL_NAND_ITCallback (NAND_HandleTypeDef * hnand)

Function Description

NAND interrupt feature callback.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.

Return values

None

HAL_NAND_Read_ID
Function Name

HAL_StatusTypeDef HAL_NAND_Read_ID
(NAND_HandleTypeDef * hnand, NAND_IDTypeDef *
pNAND_ID)

Function Description

Read the NAND memory electronic signature.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.
pNAND_ID: NAND ID structure

Return values

HAL: status

HAL_NAND_Reset
Function Name

HAL_StatusTypeDef HAL_NAND_Reset
(NAND_HandleTypeDef * hnand)

Function Description

NAND memory reset.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.

Return values

HAL: status

DocID025834 Rev 4

547/964

HAL NAND Generic Driver

UM1725

HAL_NAND_Read_Page
Function Name

HAL_StatusTypeDef HAL_NAND_Read_Page
(NAND_HandleTypeDef * hnand, NAND_AddressTypeDef *
pAddress, uint8_t * pBuffer, uint32_t NumPageToRead)

Function Description

Read Page(s) from NAND memory block.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.
pAddress: : pointer to NAND address structure
pBuffer: : pointer to destination read buffer
NumPageToRead: : number of pages to read from block

Return values

HAL: status

HAL_NAND_Write_Page
Function Name

HAL_StatusTypeDef HAL_NAND_Write_Page
(NAND_HandleTypeDef * hnand, NAND_AddressTypeDef *
pAddress, uint8_t * pBuffer, uint32_t NumPageToWrite)

Function Description

Write Page(s) to NAND memory block.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.
pAddress: : pointer to NAND address structure
pBuffer: : pointer to source buffer to write
NumPageToWrite: : number of pages to write to block

Return values

HAL: status

HAL_NAND_Read_SpareArea
Function Name

HAL_StatusTypeDef HAL_NAND_Read_SpareArea
(NAND_HandleTypeDef * hnand, NAND_AddressTypeDef *
pAddress, uint8_t * pBuffer, uint32_t NumSpareAreaToRead)

Function Description

Read Spare area(s) from NAND memory.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.
pAddress: : pointer to NAND address structure
pBuffer: pointer to source buffer to write
NumSpareAreaToRead: Number of spare area to read

Return values

HAL: status

HAL_NAND_Write_SpareArea
Function Name

HAL_StatusTypeDef HAL_NAND_Write_SpareArea
(NAND_HandleTypeDef * hnand, NAND_AddressTypeDef *
pAddress, uint8_t * pBuffer, uint32_t NumSpareAreaTowrite)

Function Description

Write Spare area(s) to NAND memory.

Parameters

548/964

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.
pAddress: : pointer to NAND address structure
pBuffer: : pointer to source buffer to write
DocID025834 Rev 4

UM1725

HAL NAND Generic Driver
NumSpareAreaTowrite: : number of spare areas to write to
block
Return values

HAL: status

HAL_NAND_Erase_Block
Function Name

HAL_StatusTypeDef HAL_NAND_Erase_Block
(NAND_HandleTypeDef * hnand, NAND_AddressTypeDef *
pAddress)

Function Description

NAND memory Block erase.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.
pAddress: : pointer to NAND address structure

Return values

HAL: status

HAL_NAND_Read_Status
Function Name

uint32_t HAL_NAND_Read_Status (NAND_HandleTypeDef *
hnand)

Function Description

NAND memory read status.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.

Return values

NAND: status

HAL_NAND_Address_Inc
Function Name

uint32_t HAL_NAND_Address_Inc (NAND_HandleTypeDef *
hnand, NAND_AddressTypeDef * pAddress)

Function Description

Increment the NAND memory address.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.
pAddress: pointer to NAND address structure

Return values

The: new status of the increment address operation. It can
be:
NAND_VALID_ADDRESS: When the new address is
valid address
NAND_INVALID_ADDRESS: When the new address is
invalid address

HAL_NAND_ECC_Enable
Function Name

HAL_StatusTypeDef HAL_NAND_ECC_Enable
(NAND_HandleTypeDef * hnand)

Function Description

Enables dynamically NAND ECC feature.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.

Return values

HAL: status
DocID025834 Rev 4

549/964

HAL NAND Generic Driver

UM1725

HAL_NAND_ECC_Disable
Function Name

HAL_StatusTypeDef HAL_NAND_ECC_Disable
(NAND_HandleTypeDef * hnand)

Function Description

Disables dynamically FMC_NAND ECC feature.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.

Return values

HAL: status

HAL_NAND_GetECC
Function Name

HAL_StatusTypeDef HAL_NAND_GetECC
(NAND_HandleTypeDef * hnand, uint32_t * ECCval, uint32_t
Timeout)

Function Description

Disables dynamically NAND ECC feature.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.
ECCval: pointer to ECC value
Timeout: maximum timeout to wait

Return values

HAL: status

HAL_NAND_GetState
Function Name

HAL_NAND_StateTypeDef HAL_NAND_GetState
(NAND_HandleTypeDef * hnand)

Function Description

return the NAND state

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.

Return values

HAL: state

HAL_NAND_Read_Status
Function Name

uint32_t HAL_NAND_Read_Status (NAND_HandleTypeDef *
hnand)

Function Description

NAND memory read status.

Parameters

hnand: pointer to a NAND_HandleTypeDef structure that
contains the configuration information for NAND module.

Return values

NAND: status

41.3

NAND Firmware driver defines

41.3.1

NAND
NAND Exported Macros
__HAL_NAND_RESET_HANDLE_STATE

Description:
Reset NAND handle state.

550/964

DocID025834 Rev 4

UM1725

HAL NAND Generic Driver
Parameters:
__HANDLE__: specifies the NAND
handle.
Return value:
None

DocID025834 Rev 4

551/964

HAL NOR Generic Driver

UM1725

42

HAL NOR Generic Driver

42.1

NOR Firmware driver registers structures

42.1.1

NOR_IDTypeDef
Data Fields
uint16_t Manufacturer_Code
uint16_t Device_Code1
uint16_t Device_Code2
uint16_t Device_Code3

Field Documentation
uint16_t NOR_IDTypeDef::Manufacturer_Code
Defines the device's manufacturer code used to identify the memory
uint16_t NOR_IDTypeDef::Device_Code1
uint16_t NOR_IDTypeDef::Device_Code2
uint16_t NOR_IDTypeDef::Device_Code3
Defines the device's codes used to identify the memory. These codes can be
accessed by performing read operations with specific control signals and addresses
set.They can also be accessed by issuing an Auto Select command

42.1.2

NOR_CFITypeDef
Data Fields
uint16_t CFI_1
uint16_t CFI_2
uint16_t CFI_3
uint16_t CFI_4

Field Documentation
uint16_t NOR_CFITypeDef::CFI_1
< Defines the information stored in the memory's Common flash interface which
contains a description of various electrical and timing parameters, density information
and functions supported by the memory
uint16_t NOR_CFITypeDef::CFI_2
uint16_t NOR_CFITypeDef::CFI_3
uint16_t NOR_CFITypeDef::CFI_4

552/964

DocID025834 Rev 4

UM1725

42.1.3

HAL NOR Generic Driver

NOR_HandleTypeDef
Data Fields
FMC_NORSRAM_TypeDef * Instance
FMC_NORSRAM_EXTENDED_TypeDef * Extended
FMC_NORSRAM_InitTypeDef Init
HAL_LockTypeDef Lock
__IO HAL_NOR_StateTypeDef State

Field Documentation
FMC_NORSRAM_TypeDef* NOR_HandleTypeDef::Instance
Register base address
FMC_NORSRAM_EXTENDED_TypeDef* NOR_HandleTypeDef::Extended
Extended mode register base address
FMC_NORSRAM_InitTypeDef NOR_HandleTypeDef::Init
NOR device control configuration parameters
HAL_LockTypeDef NOR_HandleTypeDef::Lock
NOR locking object
__IO HAL_NOR_StateTypeDef NOR_HandleTypeDef::State
NOR device access state

42.2

NOR Firmware driver API description

42.2.1

How to use this driver
This driver is a generic layered driver which contains a set of APIs used to control NOR
flash memories. It uses the FMC/FSMC layer functions to interface with NOR devices. This
driver is used as follows:
NOR flash memory configuration sequence using the function HAL_NOR_Init() with
control and timing parameters for both normal and extended mode.
Read NOR flash memory manufacturer code and device IDs using the function
HAL_NOR_Read_ID(). The read information is stored in the NOR_ID_TypeDef
structure declared by the function caller.
Access NOR flash memory by read/write data unit operations using the functions
HAL_NOR_Read(), HAL_NOR_Program().
Perform NOR flash erase block/chip operations using the functions
HAL_NOR_Erase_Block() and HAL_NOR_Erase_Chip().
Read the NOR flash CFI (common flash interface) IDs using the function
HAL_NOR_Read_CFI(). The read information is stored in the NOR_CFI_TypeDef
structure declared by the function caller.
You can also control the NOR device by calling the control APIs
HAL_NOR_WriteOperation_Enable()/ HAL_NOR_WriteOperation_Disable() to
respectively enable/disable the NOR write operation
You can monitor the NOR device HAL state by calling the function
HAL_NOR_GetState()

DocID025834 Rev 4

553/964

HAL NOR Generic Driver

UM1725

This driver is a set of generic APIs which handle standard NOR flash operations.
If a NOR flash device contains different operations and/or implementations, it
should be implemented separately.

NOR HAL driver macros list
Below the list of most used macros in NOR HAL driver.
NOR_WRITE : NOR memory write data to specified address

42.2.2

NOR Initialization and de_initialization functions
This section provides functions allowing to initialize/de-initialize the NOR memory
This section contains the following APIs:
HAL_NOR_Init()
HAL_NOR_DeInit()
HAL_NOR_MspInit()
HAL_NOR_MspDeInit()
HAL_NOR_MspWait()

42.2.3

NOR Input and Output functions
This section provides functions allowing to use and control the NOR memory
This section contains the following APIs:
HAL_NOR_Read_ID()
HAL_NOR_ReturnToReadMode()
HAL_NOR_Read()
HAL_NOR_Program()
HAL_NOR_ReadBuffer()
HAL_NOR_ProgramBuffer()
HAL_NOR_Erase_Block()
HAL_NOR_Erase_Chip()
HAL_NOR_Read_CFI()

42.2.4

NOR Control functions
This subsection provides a set of functions allowing to control dynamically the NOR
interface.
This section contains the following APIs:
HAL_NOR_WriteOperation_Enable()
HAL_NOR_WriteOperation_Disable()

42.2.5

NOR State functions
This subsection permits to get in run-time the status of the NOR controller and the data
flow.
This section contains the following APIs:
HAL_NOR_GetState()
HAL_NOR_GetStatus()

554/964

DocID025834 Rev 4

UM1725

42.2.6

HAL NOR Generic Driver

Detailed description of functions
HAL_NOR_Init
Function Name

HAL_StatusTypeDef HAL_NOR_Init (NOR_HandleTypeDef *
hnor, FMC_NORSRAM_TimingTypeDef * Timing,
FMC_NORSRAM_TimingTypeDef * ExtTiming)

Function Description

Perform the NOR memory Initialization sequence.

Parameters

hnor: pointer to the NOR handle
Timing: pointer to NOR control timing structure
ExtTiming: pointer to NOR extended mode timing structure

Return values

HAL: status

HAL_NOR_DeInit
Function Name

HAL_StatusTypeDef HAL_NOR_DeInit (NOR_HandleTypeDef *
hnor)

Function Description

Perform NOR memory De-Initialization sequence.

Parameters

hnor: pointer to a NOR_HandleTypeDef structure that
contains the configuration information for NOR module.

Return values

HAL: status

HAL_NOR_MspInit
Function Name

void HAL_NOR_MspInit (NOR_HandleTypeDef * hnor)

Function Description

NOR MSP Init.

Parameters

hnor: pointer to a NOR_HandleTypeDef structure that
contains the configuration information for NOR module.

Return values

None

HAL_NOR_MspDeInit
Function Name

void HAL_NOR_MspDeInit (NOR_HandleTypeDef * hnor)

Function Description

NOR MSP DeInit.

Parameters

hnor: pointer to a NOR_HandleTypeDef structure that
contains the configuration information for NOR module.

Return values

None

HAL_NOR_MspWait
Function Name

void HAL_NOR_MspWait (NOR_HandleTypeDef * hnor,
uint32_t Timeout)

Function Description

NOR BSP Wait for Ready/Busy signal.

Parameters

hnor: pointer to a NOR_HandleTypeDef structure that
contains the configuration information for NOR module.
Timeout: Maximum timeout value

DocID025834 Rev 4

555/964

HAL NOR Generic Driver
Return values

UM1725
None

HAL_NOR_Read_ID
Function Name

HAL_StatusTypeDef HAL_NOR_Read_ID
(NOR_HandleTypeDef * hnor, NOR_IDTypeDef * pNOR_ID)

Function Description

Read NOR flash IDs.

Parameters

hnor: pointer to the NOR handle
pNOR_ID: : pointer to NOR ID structure

Return values

HAL: status

HAL_NOR_ReturnToReadMode
Function Name

HAL_StatusTypeDef HAL_NOR_ReturnToReadMode
(NOR_HandleTypeDef * hnor)

Function Description

Returns the NOR memory to Read mode.

Parameters

hnor: pointer to the NOR handle

Return values

HAL: status

HAL_NOR_Read
Function Name

HAL_StatusTypeDef HAL_NOR_Read (NOR_HandleTypeDef *
hnor, uint32_t * pAddress, uint16_t * pData)

Function Description

Read data from NOR memory.

Parameters

hnor: pointer to the NOR handle
pAddress: pointer to Device address
pData: : pointer to read data

Return values

HAL: status

HAL_NOR_Program
Function Name

HAL_StatusTypeDef HAL_NOR_Program
(NOR_HandleTypeDef * hnor, uint32_t * pAddress, uint16_t *
pData)

Function Description

Program data to NOR memory.

Parameters

hnor: pointer to the NOR handle
pAddress: Device address
pData: : pointer to the data to write

Return values

HAL: status

HAL_NOR_ReadBuffer

556/964

Function Name

HAL_StatusTypeDef HAL_NOR_ReadBuffer
(NOR_HandleTypeDef * hnor, uint32_t uwAddress, uint16_t *
pData, uint32_t uwBufferSize)

Function Description

Reads a half-word buffer from the NOR memory.

DocID025834 Rev 4

UM1725

HAL NOR Generic Driver
Parameters

hnor: pointer to the NOR handle
uwAddress: NOR memory internal address to read from.
pData: pointer to the buffer that receives the data read from
the NOR memory.
uwBufferSize: : number of Half word to read.

Return values

HAL: status

HAL_NOR_ProgramBuffer
Function Name

HAL_StatusTypeDef HAL_NOR_ProgramBuffer
(NOR_HandleTypeDef * hnor, uint32_t uwAddress, uint16_t *
pData, uint32_t uwBufferSize)

Function Description

Writes a half-word buffer to the NOR memory.

Parameters

hnor: pointer to the NOR handle
uwAddress: NOR memory internal start write address
pData: pointer to source data buffer.
uwBufferSize: Size of the buffer to write

Return values

HAL: status

HAL_NOR_Erase_Block
Function Name

HAL_StatusTypeDef HAL_NOR_Erase_Block
(NOR_HandleTypeDef * hnor, uint32_t BlockAddress, uint32_t
Address)

Function Description

Erase the specified block of the NOR memory.

Parameters

hnor: pointer to the NOR handle
BlockAddress: : Block to erase address
Address: Device address

Return values

HAL: status

HAL_NOR_Erase_Chip
Function Name

HAL_StatusTypeDef HAL_NOR_Erase_Chip
(NOR_HandleTypeDef * hnor, uint32_t Address)

Function Description

Erase the entire NOR chip.

Parameters

hnor: pointer to the NOR handle
Address: : Device address

Return values

HAL: status

HAL_NOR_Read_CFI
Function Name

HAL_StatusTypeDef HAL_NOR_Read_CFI
(NOR_HandleTypeDef * hnor, NOR_CFITypeDef * pNOR_CFI)

Function Description

Read NOR flash CFI IDs.

Parameters

hnor: pointer to the NOR handle
pNOR_CFI: : pointer to NOR CFI IDs structure

DocID025834 Rev 4

557/964

HAL NOR Generic Driver
Return values

UM1725
HAL: status

HAL_NOR_WriteOperation_Enable
Function Name

HAL_StatusTypeDef HAL_NOR_WriteOperation_Enable
(NOR_HandleTypeDef * hnor)

Function Description

Enables dynamically NOR write operation.

Parameters

hnor: pointer to the NOR handle

Return values

HAL: status

HAL_NOR_WriteOperation_Disable
Function Name

HAL_StatusTypeDef HAL_NOR_WriteOperation_Disable
(NOR_HandleTypeDef * hnor)

Function Description

Disables dynamically NOR write operation.

Parameters

hnor: pointer to the NOR handle

Return values

HAL: status

HAL_NOR_GetState
Function Name

HAL_NOR_StateTypeDef HAL_NOR_GetState
(NOR_HandleTypeDef * hnor)

Function Description

return the NOR controller state

Parameters

hnor: pointer to the NOR handle

Return values

NOR: controller state

HAL_NOR_GetStatus
Function Name

HAL_NOR_StatusTypeDef HAL_NOR_GetStatus
(NOR_HandleTypeDef * hnor, uint32_t Address, uint32_t
Timeout)

Function Description

Returns the NOR operation status.

Parameters

558/964

hnor: pointer to the NOR handle
Address: Device address
Timeout: NOR programming Timeout

DocID025834 Rev 4

UM1725

HAL NOR Generic Driver
Return values

NOR_Status: The returned value can be:
HAL_NOR_STATUS_SUCCESS,
HAL_NOR_STATUS_ERROR or
HAL_NOR_STATUS_TIMEOUT

42.3

NOR Firmware driver defines

42.3.1

NOR
NOR Exported Macros
__HAL_NOR_RESET_HANDLE_STATE

Description:
Reset NOR handle state.
Parameters:
__HANDLE__: specifies the NOR handle.
Return value:
None

DocID025834 Rev 4

559/964

HAL PCCARD Generic Driver

UM1725

43

HAL PCCARD Generic Driver

43.1

PCCARD Firmware driver registers structures

43.1.1

PCCARD_HandleTypeDef
Data Fields
FMC_PCCARD_TypeDef * Instance
FMC_PCCARD_InitTypeDef Init
__IO HAL_PCCARD_StateTypeDef State
HAL_LockTypeDef Lock

Field Documentation
FMC_PCCARD_TypeDef* PCCARD_HandleTypeDef::Instance
Register base address for PCCARD device
FMC_PCCARD_InitTypeDef PCCARD_HandleTypeDef::Init
PCCARD device control configuration parameters
__IO HAL_PCCARD_StateTypeDef PCCARD_HandleTypeDef::State
PCCARD device access state
HAL_LockTypeDef PCCARD_HandleTypeDef::Lock
PCCARD Lock

43.2

PCCARD Firmware driver API description

43.2.1

How to use this driver
This driver is a generic layered driver which contains a set of APIs used to control
PCCARD/compact flash memories. It uses the FMC/FSMC layer functions to interface with
PCCARD devices. This driver is used for:
PCCARD/Compact Flash memory configuration sequence using the function
HAL_PCCARD_Init()/HAL_CF_Init() with control and timing parameters for both
common and attribute spaces.
Read PCCARD/Compact Flash memory maker and device IDs using the function
HAL_PCCARD_Read_ID()/HAL_CF_Read_ID(). The read information is stored in the
CompactFlash_ID structure declared by the function caller.
Access PCCARD/Compact Flash memory by read/write operations using the
functions HAL_PCCARD_Read_Sector()/ HAL_PCCARD_Write_Sector() HAL_CF_Read_Sector()/HAL_CF_Write_Sector(), to read/write sector.
Perform PCCARD/Compact Flash Reset chip operation using the function
HAL_PCCARD_Reset()/HAL_CF_Reset.
Perform PCCARD/Compact Flash erase sector operation using the function
HAL_PCCARD_Erase_Sector()/HAL_CF_Erase_Sector.
Read the PCCARD/Compact Flash status operation using the function
HAL_PCCARD_ReadStatus()/HAL_CF_ReadStatus().
You can monitor the PCCARD/Compact Flash device HAL state by calling the
function HAL_PCCARD_GetState()/HAL_CF_GetState()

560/964

DocID025834 Rev 4

UM1725

HAL PCCARD Generic Driver
This driver is a set of generic APIs which handle standard PCCARD/compact
flash operations. If a PCCARD/Compact Flash device contains different
operations and/or implementations, it should be implemented separately.

43.2.2

PCCARD Initialization and de-initialization functions
This section provides functions allowing to initialize/de-initialize the PCCARD memory
This section contains the following APIs:
HAL_PCCARD_Init()
HAL_PCCARD_DeInit()
HAL_PCCARD_MspInit()
HAL_PCCARD_MspDeInit()

43.2.3

PCCARD Input and Output functions
This section provides functions allowing to use and control the PCCARD memory
This section contains the following APIs:
HAL_PCCARD_Read_ID()
HAL_PCCARD_Read_Sector()
HAL_PCCARD_Write_Sector()
HAL_PCCARD_Erase_Sector()
HAL_PCCARD_Reset()
HAL_PCCARD_IRQHandler()
HAL_PCCARD_ITCallback()

43.2.4

PCCARD State functions
This subsection permits to get in run-time the status of the PCCARD controller and the
data flow.
This section contains the following APIs:
HAL_PCCARD_GetState()
HAL_PCCARD_GetStatus()
HAL_PCCARD_ReadStatus()

43.2.5

Detailed description of functions
HAL_PCCARD_Init
Function Name

HAL_StatusTypeDef HAL_PCCARD_Init
(PCCARD_HandleTypeDef * hpccard,
FMC_NAND_PCC_TimingTypeDef * ComSpaceTiming,
FMC_NAND_PCC_TimingTypeDef * AttSpaceTiming,
FMC_NAND_PCC_TimingTypeDef * IOSpaceTiming)

Function Description

Perform the PCCARD memory Initialization sequence.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.
ComSpaceTiming: Common space timing structure
AttSpaceTiming: Attribute space timing structure

DocID025834 Rev 4

561/964

HAL PCCARD Generic Driver

UM1725
IOSpaceTiming: IO space timing structure

Return values

HAL: status

HAL_PCCARD_DeInit
Function Name

HAL_StatusTypeDef HAL_PCCARD_DeInit
(PCCARD_HandleTypeDef * hpccard)

Function Description

Perform the PCCARD memory De-initialization sequence.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.

Return values

HAL: status

HAL_PCCARD_MspInit
Function Name

void HAL_PCCARD_MspInit (PCCARD_HandleTypeDef *
hpccard)

Function Description

PCCARD MSP Init.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.

Return values

None

HAL_PCCARD_MspDeInit
Function Name

void HAL_PCCARD_MspDeInit (PCCARD_HandleTypeDef *
hpccard)

Function Description

PCCARD MSP DeInit.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.

Return values

None

HAL_PCCARD_Read_ID

562/964

Function Name

HAL_StatusTypeDef HAL_PCCARD_Read_ID
(PCCARD_HandleTypeDef * hpccard, uint8_t
CompactFlash_ID, uint8_t * pStatus)

Function Description

Read Compact Flash's ID.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.
CompactFlash_ID: Compact flash ID structure.
pStatus: pointer to compact flash status

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL PCCARD Generic Driver

HAL_PCCARD_Write_Sector
Function Name

HAL_StatusTypeDef HAL_PCCARD_Write_Sector
(PCCARD_HandleTypeDef * hpccard, uint16_t * pBuffer,
uint16_t SectorAddress, uint8_t * pStatus)

Function Description

Write sector to PCCARD memory.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.
pBuffer: pointer to source write buffer
SectorAddress: Sector address to write
pStatus: pointer to PCCARD status

Return values

HAL: status

HAL_PCCARD_Read_Sector
Function Name

HAL_StatusTypeDef HAL_PCCARD_Read_Sector
(PCCARD_HandleTypeDef * hpccard, uint16_t * pBuffer,
uint16_t SectorAddress, uint8_t * pStatus)

Function Description

Read sector from PCCARD memory.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.
pBuffer: pointer to destination read buffer
SectorAddress: Sector address to read
pStatus: pointer to PCCARD status

Return values

HAL: status

HAL_PCCARD_Erase_Sector
Function Name

HAL_StatusTypeDef HAL_PCCARD_Erase_Sector
(PCCARD_HandleTypeDef * hpccard, uint16_t SectorAddress,
uint8_t * pStatus)

Function Description

Erase sector from PCCARD memory.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.
SectorAddress: Sector address to erase
pStatus: pointer to PCCARD status

Return values

HAL: status

HAL_PCCARD_Reset
Function Name

HAL_StatusTypeDef HAL_PCCARD_Reset
(PCCARD_HandleTypeDef * hpccard)

Function Description

Reset the PCCARD memory.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD

DocID025834 Rev 4

563/964

HAL PCCARD Generic Driver

UM1725
module.

Return values

HAL: status

HAL_PCCARD_IRQHandler
Function Name

void HAL_PCCARD_IRQHandler (PCCARD_HandleTypeDef *
hpccard)

Function Description

This function handles PCCARD device interrupt request.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.

Return values

HAL: status

HAL_PCCARD_ITCallback
Function Name

void HAL_PCCARD_ITCallback (PCCARD_HandleTypeDef *
hpccard)

Function Description

PCCARD interrupt feature callback.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.

Return values

None

HAL_PCCARD_GetState
Function Name

HAL_PCCARD_StateTypeDef HAL_PCCARD_GetState
(PCCARD_HandleTypeDef * hpccard)

Function Description

return the PCCARD controller state

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.

Return values

HAL: state

HAL_PCCARD_GetStatus

564/964

Function Name

HAL_PCCARD_StatusTypeDef HAL_PCCARD_GetStatus
(PCCARD_HandleTypeDef * hpccard)

Function Description

Get the compact flash memory status.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.

Return values

New: status of the PCCARD operation. This parameter can
be:
CompactFlash_TIMEOUT_ERROR: when the previous
operation generate a Timeout error
CompactFlash_READY: when memory is ready for the
next operation
DocID025834 Rev 4

UM1725

HAL PCCARD Generic Driver

HAL_PCCARD_ReadStatus
Function Name

HAL_PCCARD_StatusTypeDef HAL_PCCARD_ReadStatus
(PCCARD_HandleTypeDef * hpccard)

Function Description

Reads the Compact Flash memory status using the Read status
command.

Parameters

hpccard: pointer to a PCCARD_HandleTypeDef structure
that contains the configuration information for PCCARD
module.

Return values

The: status of the Compact Flash memory. This parameter
can be:
CompactFlash_BUSY: when memory is busy
CompactFlash_READY: when memory is ready for the
next operation
CompactFlash_ERROR: when the previous operation
generates error

43.3

PCCARD Firmware driver defines

43.3.1

PCCARD
PCCARD Exported Macros
__HAL_PCCARD_RESET_HANDLE_STATE

Description:
Reset PCCARD handle state.
Parameters:
__HANDLE__: specifies the PCCARD
handle.
Return value:
None

DocID025834 Rev 4

565/964

HAL PCD Generic Driver

UM1725

44

HAL PCD Generic Driver

44.1

PCD Firmware driver registers structures

44.1.1

PCD_HandleTypeDef
Data Fields
PCD_TypeDef * Instance
PCD_InitTypeDef Init
PCD_EPTypeDef IN_ep
PCD_EPTypeDef OUT_ep
HAL_LockTypeDef Lock
__IO PCD_StateTypeDef State
uint32_t Setup
PCD_LPM_StateTypeDef LPM_State
uint32_t BESL
uint32_t lpm_active
void * pData

Field Documentation
PCD_TypeDef* PCD_HandleTypeDef::Instance
Register base address
PCD_InitTypeDef PCD_HandleTypeDef::Init
PCD required parameters
PCD_EPTypeDef PCD_HandleTypeDef::IN_ep[15]
IN endpoint parameters
PCD_EPTypeDef PCD_HandleTypeDef::OUT_ep[15]
OUT endpoint parameters
HAL_LockTypeDef PCD_HandleTypeDef::Lock
PCD peripheral status
__IO PCD_StateTypeDef PCD_HandleTypeDef::State
PCD communication state
uint32_t PCD_HandleTypeDef::Setup[12]
Setup packet buffer
PCD_LPM_StateTypeDef PCD_HandleTypeDef::LPM_State
LPM State
uint32_t PCD_HandleTypeDef::BESL
uint32_t PCD_HandleTypeDef::lpm_active
Enable or disable the Link Power Management . This parameter can be set to
ENABLE or DISABLE
void* PCD_HandleTypeDef::pData
Pointer to upper stack Handler

566/964

DocID025834 Rev 4

UM1725

HAL PCD Generic Driver

44.2

PCD Firmware driver API description

44.2.1

How to use this driver
The PCD HAL driver can be used as follows:
1.
2.
3.
4.

5.
6.

44.2.2

Declare a PCD_HandleTypeDef handle structure, for example: PCD_HandleTypeDef
hpcd;
Fill parameters of Init structure in HCD handle
Call HAL_PCD_Init() API to initialize the PCD peripheral (Core, Device core, ...)
Initialize the PCD low level resources through the HAL_PCD_MspInit() API:
a.
Enable the PCD/USB Low Level interface clock using
__HAL_RCC_USB_OTG_FS_CLK_ENABLE();
__HAL_RCC_USB_OTG_HS_CLK_ENABLE(); (For High Speed Mode)
b.
Initialize the related GPIO clocks
c.
Configure PCD pin-out
d.
Configure PCD NVIC interrupt
Associate the Upper USB device stack to the HAL PCD Driver:
a.
hpcd.pData = pdev;
Enable PCD transmission and reception:
a.
HAL_PCD_Start();

Initialization and de-initialization functions
This section provides functions allowing to:
This section contains the following APIs:
HAL_PCD_Init()
HAL_PCD_DeInit()
HAL_PCD_MspInit()
HAL_PCD_MspDeInit()

44.2.3

IO operation functions
This subsection provides a set of functions allowing to manage the PCD data transfers.
This section contains the following APIs:
HAL_PCD_Start()
HAL_PCD_Stop()
HAL_PCD_IRQHandler()
HAL_PCD_DataOutStageCallback()
HAL_PCD_DataInStageCallback()
HAL_PCD_SetupStageCallback()
HAL_PCD_SOFCallback()
HAL_PCD_ResetCallback()
HAL_PCD_SuspendCallback()
HAL_PCD_ResumeCallback()
HAL_PCD_ISOOUTIncompleteCallback()
HAL_PCD_ISOINIncompleteCallback()
HAL_PCD_ConnectCallback()
HAL_PCD_DisconnectCallback()

DocID025834 Rev 4

567/964

HAL PCD Generic Driver

44.2.4

UM1725

Peripheral Control functions
This subsection provides a set of functions allowing to control the PCD data transfers.
This section contains the following APIs:
HAL_PCD_DevConnect()
HAL_PCD_DevDisconnect()
HAL_PCD_SetAddress()
HAL_PCD_EP_Open()
HAL_PCD_EP_Close()
HAL_PCD_EP_Receive()
HAL_PCD_EP_GetRxCount()
HAL_PCD_EP_Transmit()
HAL_PCD_EP_SetStall()
HAL_PCD_EP_ClrStall()
HAL_PCD_EP_Flush()
HAL_PCD_ActivateRemoteWakeup()
HAL_PCD_DeActivateRemoteWakeup()

44.2.5

Peripheral State functions
This subsection permits to get in run-time the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_PCD_GetState()

44.2.6

Detailed description of functions
HAL_PCD_Init
Function Name

HAL_StatusTypeDef HAL_PCD_Init (PCD_HandleTypeDef *
hpcd)

Function Description

Initializes the PCD according to the specified parameters in the
PCD_InitTypeDef and initialize the associated handle.

Parameters

hpcd: PCD handle

Return values

HAL: status

HAL_PCD_DeInit

568/964

Function Name

HAL_StatusTypeDef HAL_PCD_DeInit (PCD_HandleTypeDef *
hpcd)

Function Description

DeInitializes the PCD peripheral.

Parameters

hpcd: PCD handle

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL PCD Generic Driver

HAL_PCD_MspInit
Function Name

void HAL_PCD_MspInit (PCD_HandleTypeDef * hpcd)

Function Description

Initializes the PCD MSP.

Parameters

hpcd: PCD handle

Return values

None

HAL_PCD_MspDeInit
Function Name

void HAL_PCD_MspDeInit (PCD_HandleTypeDef * hpcd)

Function Description

DeInitializes PCD MSP.

Parameters

hpcd: PCD handle

Return values

None

HAL_PCD_Start
Function Name

HAL_StatusTypeDef HAL_PCD_Start (PCD_HandleTypeDef *
hpcd)

Function Description

Start The USB OTG Device.

Parameters

hpcd: PCD handle

Return values

HAL: status

HAL_PCD_Stop
Function Name

HAL_StatusTypeDef HAL_PCD_Stop (PCD_HandleTypeDef *
hpcd)

Function Description

Stop The USB OTG Device.

Parameters

hpcd: PCD handle

Return values

HAL: status

HAL_PCD_IRQHandler
Function Name

void HAL_PCD_IRQHandler (PCD_HandleTypeDef * hpcd)

Function Description

Handles PCD interrupt request.

Parameters

hpcd: PCD handle

Return values

HAL: status

HAL_PCD_DataOutStageCallback
Function Name

void HAL_PCD_DataOutStageCallback (PCD_HandleTypeDef *
hpcd, uint8_t epnum)

Function Description

Data OUT stage callback.

Parameters

hpcd: PCD handle
epnum: endpoint number

DocID025834 Rev 4

569/964

HAL PCD Generic Driver
Return values

UM1725
None

HAL_PCD_DataInStageCallback
Function Name

void HAL_PCD_DataInStageCallback (PCD_HandleTypeDef *
hpcd, uint8_t epnum)

Function Description

Data IN stage callback.

Parameters

hpcd: PCD handle
epnum: endpoint number

Return values

None

HAL_PCD_SetupStageCallback
Function Name

void HAL_PCD_SetupStageCallback (PCD_HandleTypeDef *
hpcd)

Function Description

Setup stage callback.

Parameters

hpcd: PCD handle

Return values

None

HAL_PCD_SOFCallback
Function Name

void HAL_PCD_SOFCallback (PCD_HandleTypeDef * hpcd)

Function Description

USB Start Of Frame callback.

Parameters

hpcd: PCD handle

Return values

None

HAL_PCD_ResetCallback
Function Name

void HAL_PCD_ResetCallback (PCD_HandleTypeDef * hpcd)

Function Description

USB Reset callback.

Parameters

hpcd: PCD handle

Return values

None

HAL_PCD_SuspendCallback

570/964

Function Name

void HAL_PCD_SuspendCallback (PCD_HandleTypeDef *
hpcd)

Function Description

Suspend event callback.

Parameters

hpcd: PCD handle

Return values

None

DocID025834 Rev 4

UM1725

HAL PCD Generic Driver

HAL_PCD_ResumeCallback
Function Name

void HAL_PCD_ResumeCallback (PCD_HandleTypeDef *
hpcd)

Function Description

Resume event callback.

Parameters

hpcd: PCD handle

Return values

None

HAL_PCD_ISOOUTIncompleteCallback
Function Name

void HAL_PCD_ISOOUTIncompleteCallback
(PCD_HandleTypeDef * hpcd, uint8_t epnum)

Function Description

Incomplete ISO OUT callback.

Parameters

hpcd: PCD handle
epnum: endpoint number

Return values

None

HAL_PCD_ISOINIncompleteCallback
Function Name

void HAL_PCD_ISOINIncompleteCallback
(PCD_HandleTypeDef * hpcd, uint8_t epnum)

Function Description

Incomplete ISO IN callback.

Parameters

hpcd: PCD handle
epnum: endpoint number

Return values

None

HAL_PCD_ConnectCallback
Function Name

void HAL_PCD_ConnectCallback (PCD_HandleTypeDef *
hpcd)

Function Description

Connection event callback.

Parameters

hpcd: PCD handle

Return values

None

HAL_PCD_DisconnectCallback
Function Name

void HAL_PCD_DisconnectCallback (PCD_HandleTypeDef *
hpcd)

Function Description

Disconnection event callback.

Parameters

hpcd: PCD handle

Return values

None

DocID025834 Rev 4

571/964

HAL PCD Generic Driver

UM1725

HAL_PCD_DevConnect
Function Name

HAL_StatusTypeDef HAL_PCD_DevConnect
(PCD_HandleTypeDef * hpcd)

Function Description

Connect the USB device.

Parameters

hpcd: PCD handle

Return values

HAL: status

HAL_PCD_DevDisconnect
Function Name

HAL_StatusTypeDef HAL_PCD_DevDisconnect
(PCD_HandleTypeDef * hpcd)

Function Description

Disconnect the USB device.

Parameters

hpcd: PCD handle

Return values

HAL: status

HAL_PCD_SetAddress
Function Name

HAL_StatusTypeDef HAL_PCD_SetAddress
(PCD_HandleTypeDef * hpcd, uint8_t address)

Function Description

Set the USB Device address.

Parameters

hpcd: PCD handle
address: new device address

Return values

HAL: status

HAL_PCD_EP_Open
Function Name

HAL_StatusTypeDef HAL_PCD_EP_Open
(PCD_HandleTypeDef * hpcd, uint8_t ep_addr, uint16_t
ep_mps, uint8_t ep_type)

Function Description

Open and configure an endpoint.

Parameters

hpcd: PCD handle
ep_addr: endpoint address
ep_mps: endpoint max packet size
ep_type: endpoint type

Return values

HAL: status

HAL_PCD_EP_Close

572/964

Function Name

HAL_StatusTypeDef HAL_PCD_EP_Close
(PCD_HandleTypeDef * hpcd, uint8_t ep_addr)

Function Description

Deactivate an endpoint.

Parameters

hpcd: PCD handle
ep_addr: endpoint address

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL PCD Generic Driver

HAL_PCD_EP_Receive
Function Name

HAL_StatusTypeDef HAL_PCD_EP_Receive
(PCD_HandleTypeDef * hpcd, uint8_t ep_addr, uint8_t * pBuf,
uint32_t len)

Function Description

Receive an amount of data.

Parameters

hpcd: PCD handle
ep_addr: endpoint address
pBuf: pointer to the reception buffer
len: amount of data to be received

Return values

HAL: status

HAL_PCD_EP_Transmit
Function Name

HAL_StatusTypeDef HAL_PCD_EP_Transmit
(PCD_HandleTypeDef * hpcd, uint8_t ep_addr, uint8_t * pBuf,
uint32_t len)

Function Description

Send an amount of data.

Parameters

hpcd: PCD handle
ep_addr: endpoint address
pBuf: pointer to the transmission buffer
len: amount of data to be sent

Return values

HAL: status

HAL_PCD_EP_GetRxCount
Function Name

uint16_t HAL_PCD_EP_GetRxCount (PCD_HandleTypeDef *
hpcd, uint8_t ep_addr)

Function Description

Get Received Data Size.

Parameters

hpcd: PCD handle
ep_addr: endpoint address

Return values

Data: Size

HAL_PCD_EP_SetStall
Function Name

HAL_StatusTypeDef HAL_PCD_EP_SetStall
(PCD_HandleTypeDef * hpcd, uint8_t ep_addr)

Function Description

Set a STALL condition over an endpoint.

Parameters

hpcd: PCD handle
ep_addr: endpoint address

Return values

HAL: status

HAL_PCD_EP_ClrStall
Function Name

HAL_StatusTypeDef HAL_PCD_EP_ClrStall
(PCD_HandleTypeDef * hpcd, uint8_t ep_addr)

Function Description

Clear a STALL condition over in an endpoint.
DocID025834 Rev 4

573/964

HAL PCD Generic Driver
Parameters

UM1725
hpcd: PCD handle
ep_addr: endpoint address

Return values

HAL: status

HAL_PCD_EP_Flush
Function Name

HAL_StatusTypeDef HAL_PCD_EP_Flush
(PCD_HandleTypeDef * hpcd, uint8_t ep_addr)

Function Description

Flush an endpoint.

Parameters

hpcd: PCD handle
ep_addr: endpoint address

Return values

HAL: status

HAL_PCD_ActivateRemoteWakeup
Function Name

HAL_StatusTypeDef HAL_PCD_ActivateRemoteWakeup
(PCD_HandleTypeDef * hpcd)

Function Description

Activate remote wakeup signalling.

Parameters

hpcd: PCD handle

Return values

HAL: status

HAL_PCD_DeActivateRemoteWakeup
Function Name

HAL_StatusTypeDef HAL_PCD_DeActivateRemoteWakeup
(PCD_HandleTypeDef * hpcd)

Function Description

De-activate remote wakeup signalling.

Parameters

hpcd: PCD handle

Return values

HAL: status

HAL_PCD_GetState
Function Name

PCD_StateTypeDef HAL_PCD_GetState (PCD_HandleTypeDef
* hpcd)

Function Description

Return the PCD handle state.

Parameters

hpcd: PCD handle

Return values

HAL: state

44.3

PCD Firmware driver defines

44.3.1

PCD
PCD Exported Macros
__HAL_PCD_ENABLE
__HAL_PCD_DISABLE
__HAL_PCD_GET_FLAG

574/964

DocID025834 Rev 4

UM1725

HAL PCD Generic Driver
__HAL_PCD_CLEAR_FLAG
__HAL_PCD_IS_INVALID_INTERRUPT
__HAL_PCD_UNGATE_PHYCLOCK
__HAL_PCD_GATE_PHYCLOCK
__HAL_PCD_IS_PHY_SUSPENDED
USB_OTG_FS_WAKEUP_EXTI_RISING_EDGE
USB_OTG_FS_WAKEUP_EXTI_FALLING_EDGE
USB_OTG_FS_WAKEUP_EXTI_RISING_FALLING_EDGE
USB_OTG_HS_WAKEUP_EXTI_RISING_EDGE
USB_OTG_HS_WAKEUP_EXTI_FALLING_EDGE
USB_OTG_HS_WAKEUP_EXTI_RISING_FALLING_EDGE
USB_OTG_HS_WAKEUP_EXTI_LINE

External
interrupt
line 20
Connecte
d to the
USB HS
EXTI Line

USB_OTG_FS_WAKEUP_EXTI_LINE

External
interrupt
line 18
Connecte
d to the
USB FS
EXTI Line

__HAL_USB_OTG_HS_WAKEUP_EXTI_ENABLE_IT
__HAL_USB_OTG_HS_WAKEUP_EXTI_DISABLE_IT
__HAL_USB_OTG_HS_WAKEUP_EXTI_GET_FLAG
__HAL_USB_OTG_HS_WAKEUP_EXTI_CLEAR_FLAG
__HAL_USB_OTG_HS_WAKEUP_EXTI_ENABLE_RISING_EDGE
__HAL_USB_OTG_HS_WAKEUP_EXTI_ENABLE_FALLING_EDGE
__HAL_USB_OTG_HS_WAKEUP_EXTI_ENABLE_RISING_FALLING_EDG
E
__HAL_USB_OTG_HS_WAKEUP_EXTI_GENERATE_SWIT
__HAL_USB_OTG_FS_WAKEUP_EXTI_ENABLE_IT
__HAL_USB_OTG_FS_WAKEUP_EXTI_DISABLE_IT
__HAL_USB_OTG_FS_WAKEUP_EXTI_GET_FLAG
__HAL_USB_OTG_FS_WAKEUP_EXTI_CLEAR_FLAG
__HAL_USB_OTG_FS_WAKEUP_EXTI_ENABLE_RISING_EDGE
__HAL_USB_OTG_FS_WAKEUP_EXTI_ENABLE_FALLING_EDGE
__HAL_USB_OTG_FS_WAKEUP_EXTI_ENABLE_RISING_FALLING_EDGE
DocID025834 Rev 4

575/964

HAL PCD Generic Driver
__HAL_USB_OTG_FS_WAKEUP_EXTI_GENERATE_SWIT
PCD PHY Module
PCD_PHY_ULPI
PCD_PHY_EMBEDDED
PCD Speed
PCD_SPEED_HIGH
PCD_SPEED_HIGH_IN_FULL
PCD_SPEED_FULL
Turnaround Timeout Value
USBD_HS_TRDT_VALUE
USBD_FS_TRDT_VALUE

576/964

DocID025834 Rev 4

UM1725

UM1725

HAL PCD Extension Driver

45

HAL PCD Extension Driver

45.1

PCDEx Firmware driver API description

45.1.1

Extended features functions
This section provides functions allowing to:
Update FIFO configuration
This section contains the following APIs:
HAL_PCDEx_SetTxFiFo()
HAL_PCDEx_SetRxFiFo()
HAL_PCDEx_ActivateLPM()
HAL_PCDEx_DeActivateLPM()
HAL_PCDEx_LPM_Callback()

45.1.2

Detailed description of functions
HAL_PCDEx_SetTxFiFo
Function Name

HAL_StatusTypeDef HAL_PCDEx_SetTxFiFo
(PCD_HandleTypeDef * hpcd, uint8_t fifo, uint16_t size)

Function Description

Set Tx FIFO.

Parameters

hpcd: PCD handle
fifo: The number of Tx fifo
size: Fifo size

Return values

HAL: status

HAL_PCDEx_SetRxFiFo
Function Name

HAL_StatusTypeDef HAL_PCDEx_SetRxFiFo
(PCD_HandleTypeDef * hpcd, uint16_t size)

Function Description

Set Rx FIFO.

Parameters

hpcd: PCD handle
size: Size of Rx fifo

Return values

HAL: status

HAL_PCDEx_ActivateLPM
Function Name

HAL_StatusTypeDef HAL_PCDEx_ActivateLPM
(PCD_HandleTypeDef * hpcd)

Function Description

Activate LPM feature.

Parameters

hpcd: PCD handle

Return values

HAL: status

DocID025834 Rev 4

577/964

HAL PCD Extension Driver

UM1725

HAL_PCDEx_DeActivateLPM
Function Name

HAL_StatusTypeDef HAL_PCDEx_DeActivateLPM
(PCD_HandleTypeDef * hpcd)

Function Description

Deactivate LPM feature.

Parameters

hpcd: PCD handle

Return values

HAL: status

HAL_PCDEx_LPM_Callback

578/964

Function Name

void HAL_PCDEx_LPM_Callback (PCD_HandleTypeDef *
hpcd, PCD_LPM_MsgTypeDef msg)

Function Description

Send LPM message to user layer callback.

Parameters

hpcd: PCD handle
msg: LPM message

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL PWR Generic Driver

46

HAL PWR Generic Driver

46.1

PWR Firmware driver registers structures

46.1.1

PWR_PVDTypeDef
Data Fields
uint32_t PVDLevel
uint32_t Mode

Field Documentation
uint32_t PWR_PVDTypeDef::PVDLevel
PVDLevel: Specifies the PVD detection level. This parameter can be a value of
PWR_PVD_detection_level
uint32_t PWR_PVDTypeDef::Mode
Mode: Specifies the operating mode for the selected pins. This parameter can be a
value of PWR_PVD_Mode

46.2

PWR Firmware driver API description

46.2.1

Initialization and de-initialization functions
After reset, the backup domain (RTC registers, RTC backup data registers and backup
SRAM) is protected against possible unwanted write accesses. To enable access to the
RTC Domain and RTC registers, proceed as follows:
Enable the Power Controller (PWR) APB1 interface clock using the
__HAL_RCC_PWR_CLK_ENABLE() macro.
Enable access to RTC domain using the HAL_PWR_EnableBkUpAccess() function.
This section contains the following APIs:
HAL_PWR_DeInit()
HAL_PWR_EnableBkUpAccess()
HAL_PWR_DisableBkUpAccess()

46.2.2

Peripheral Control functions
PVD configuration
The PVD is used to monitor the VDD power supply by comparing it to a threshold
selected by the PVD Level (PLS[2:0] bits in the PWR_CR).
A PVDO flag is available to indicate if VDD/VDDA is higher or lower than the PVD
threshold. This event is internally connected to the EXTI line16 and can generate an
interrupt if enabled. This is done through __HAL_PWR_PVD_EXTI_ENABLE_IT()
macro.
The PVD is stopped in Standby mode.
DocID025834 Rev 4

579/964

HAL PWR Generic Driver

UM1725

Wake-up pin configuration
Wake-up pin is used to wake up the system from Standby mode. This pin is forced in
input pull-down configuration and is active on rising edges.
There is one Wake-up pin: Wake-up Pin 1 on PA.00.
For STM32F446xx there are two Wake-Up pins: Pin1 on PA.00 and Pin2 on
PC.13
For
STM32F410xx/STM32F412Zx/STM32F412Rx/STM32F412Vx/STM32F412Cx
there are three Wake-Up pins: Pin1 on PA.00, Pin2 on PC.00 and Pin3 on PC.01

Low Power modes configuration
The devices feature 3 low-power modes:
Sleep mode: Cortex-M4 core stopped, peripherals kept running.
Stop mode: all clocks are stopped, regulator running, regulator in low power mode
Standby mode: 1.2V domain powered off.

Sleep mode
Entry: The Sleep mode is entered by using the
HAL_PWR_EnterSLEEPMode(PWR_MAINREGULATOR_ON,
PWR_SLEEPENTRY_WFI) functions with
PWR_SLEEPENTRY_WFI: enter SLEEP mode with WFI instruction
PWR_SLEEPENTRY_WFE: enter SLEEP mode with WFE instruction The
Regulator parameter is not used for the STM32F4 family and is kept as
parameter just to maintain compatibility with the lower power families (STM32L).
Exit: Any peripheral interrupt acknowledged by the nested vectored interrupt
controller (NVIC) can wake up the device from Sleep mode.

Stop mode
In Stop mode, all clocks in the 1.2V domain are stopped, the PLL, the HSI, and the HSE
RC oscillators are disabled. Internal SRAM and register contents are preserved. The
voltage regulator can be configured either in normal or low-power mode. To minimize the
consumption In Stop mode, FLASH can be powered off before entering the Stop mode
using the HAL_PWREx_EnableFlashPowerDown() function. It can be switched on again by
software after exiting the Stop mode using the HAL_PWREx_DisableFlashPowerDown()
function.
Entry: The Stop mode is entered using the
HAL_PWR_EnterSTOPMode(PWR_MAINREGULATOR_ON) function with:
Main regulator ON.
Low Power regulator ON.
Exit: Any EXTI Line (Internal or External) configured in Interrupt/Event mode.

Standby mode
The Standby mode allows to achieve the lowest power consumption. It is based on
the Cortex-M4 deep sleep mode, with the voltage regulator disabled. The 1.2V domain
is consequently powered off. The PLL, the HSI oscillator and the HSE oscillator are
also switched off. SRAM and register contents are lost except for the RTC registers,
580/964

DocID025834 Rev 4

UM1725

HAL PWR Generic Driver
RTC backup registers, backup SRAM and Standby circuitry. The voltage regulator is
OFF.
Entry:
The Standby mode is entered using the HAL_PWR_EnterSTANDBYMode()
function.
Exit:
WKUP pin rising edge, RTC alarm (Alarm A and Alarm B), RTC wake-up,
tamper event, time-stamp event, external reset in NRST pin, IWDG reset.

Auto-wake-up (AWU) from low-power mode
The MCU can be woken up from low-power mode by an RTC Alarm event, an RTC
Wake-up event, a tamper event or a time-stamp event, without depending on an
external interrupt (Auto-wake-up mode).
RTC auto-wake-up (AWU) from the Stop and Standby modes
To wake up from the Stop mode with an RTC alarm event, it is necessary to
configure the RTC to generate the RTC alarm using the
HAL_RTC_SetAlarm_IT() function.
To wake up from the Stop mode with an RTC Tamper or time stamp event, it is
necessary to configure the RTC to detect the tamper or time stamp event using
the HAL_RTCEx_SetTimeStamp_IT() or HAL_RTCEx_SetTamper_IT() functions.
To wake up from the Stop mode with an RTC Wake-up event, it is necessary to
configure the RTC to generate the RTC Wake-up event using the
HAL_RTCEx_SetWakeUpTimer_IT() function.
This section contains the following APIs:
HAL_PWR_ConfigPVD()
HAL_PWR_EnablePVD()
HAL_PWR_DisablePVD()
HAL_PWR_EnableWakeUpPin()
HAL_PWR_DisableWakeUpPin()
HAL_PWR_EnterSLEEPMode()
HAL_PWR_EnterSTOPMode()
HAL_PWR_EnterSTANDBYMode()
HAL_PWR_PVD_IRQHandler()
HAL_PWR_PVDCallback()
HAL_PWR_EnableSleepOnExit()
HAL_PWR_DisableSleepOnExit()
HAL_PWR_EnableSEVOnPend()
HAL_PWR_DisableSEVOnPend()

46.2.3

Detailed description of functions
HAL_PWR_DeInit
Function Name

void HAL_PWR_DeInit (void )

Function Description

Deinitializes the HAL PWR peripheral registers to their default
reset values.

Return values

None

DocID025834 Rev 4

581/964

HAL PWR Generic Driver

UM1725

HAL_PWR_EnableBkUpAccess
Function Name

void HAL_PWR_EnableBkUpAccess (void )

Function Description

Enables access to the backup domain (RTC registers, RTC
backup data registers and backup SRAM).

Return values

None

Notes

If the HSE divided by 2, 3, ..31 is used as the RTC clock, the
Backup Domain Access should be kept enabled.

HAL_PWR_DisableBkUpAccess
Function Name

void HAL_PWR_DisableBkUpAccess (void )

Function Description

Disables access to the backup domain (RTC registers, RTC
backup data registers and backup SRAM).

Return values

None

Notes

If the HSE divided by 2, 3, ..31 is used as the RTC clock, the
Backup Domain Access should be kept enabled.

HAL_PWR_ConfigPVD
Function Name

void HAL_PWR_ConfigPVD (PWR_PVDTypeDef * sConfigPVD)

Function Description

Configures the voltage threshold detected by the Power Voltage
Detector(PVD).

Parameters

sConfigPVD: pointer to an PWR_PVDTypeDef structure that
contains the configuration information for the PVD.

Return values

None

Notes

Refer to the electrical characteristics of your device datasheet
for more details about the voltage threshold corresponding to
each detection level.

HAL_PWR_EnablePVD
Function Name

void HAL_PWR_EnablePVD (void )

Function Description

Enables the Power Voltage Detector(PVD).

Return values

None

HAL_PWR_DisablePVD
Function Name

void HAL_PWR_DisablePVD (void )

Function Description

Disables the Power Voltage Detector(PVD).

Return values

582/964

None

DocID025834 Rev 4

UM1725

HAL PWR Generic Driver

HAL_PWR_EnableWakeUpPin
Function
Name

void HAL_PWR_EnableWakeUpPin (uint32_t WakeUpPinx)

Function
Descripti
on

Enables the Wake-up PINx functionality.

Paramet
ers

WakeUpPinx: Specifies the Power Wake-Up pin to enable. This
parameter can be one of the following values:
PWR_WAKEUP_PIN1
PWR_WAKEUP_PIN2 available only on
STM32F410xx/STM32F446xx/STM32F412Zx/STM32F412Rx/STM32
F412Vx/STM32F412Cx devices
PWR_WAKEUP_PIN3 available only on
STM32F410xx/STM32F412xx devices

Return
values

None

HAL_PWR_DisableWakeUpPin
Function
Name

void HAL_PWR_DisableWakeUpPin (uint32_t WakeUpPinx)

Function
Descripti
on

Disables the Wake-up PINx functionality.

Paramet
ers

WakeUpPinx: Specifies the Power Wake-Up pin to disable. This
parameter can be one of the following values:
PWR_WAKEUP_PIN1
PWR_WAKEUP_PIN2 available only on
STM32F410xx/STM32F446xx/STM32F412Zx/STM32F412Rx/STM32
F412Vx/STM32F412Cx devices
PWR_WAKEUP_PIN3 available only on
STM32F410xx/STM32F412Zx/STM32F412Rx/STM32F412Vx/STM3
2F412Cx devices

Return
values

None

HAL_PWR_EnterSTOPMode
Function Name

void HAL_PWR_EnterSTOPMode (uint32_t Regulator, uint8_t
STOPEntry)

Function Description

Enters Stop mode.

Parameters

Regulator: Specifies the regulator state in Stop mode. This
parameter can be one of the following values:
PWR_MAINREGULATOR_ON: Stop mode with
regulator ON
PWR_LOWPOWERREGULATOR_ON: Stop mode with
low power regulator ON
STOPEntry: Specifies if Stop mode in entered with WFI or
WFE instruction. This parameter can be one of the following
values:
DocID025834 Rev 4

583/964

HAL PWR Generic Driver

UM1725
PWR_STOPENTRY_WFI: Enter Stop mode with WFI
instruction
PWR_STOPENTRY_WFE: Enter Stop mode with WFE
instruction

Return values

None

Notes

In Stop mode, all I/O pins keep the same state as in Run
mode.
When exiting Stop mode by issuing an interrupt or a wake-up
event, the HSI RC oscillator is selected as system clock.
When the voltage regulator operates in low power mode, an
additional startup delay is incurred when waking up from Stop
mode. By keeping the internal regulator ON during Stop
mode, the consumption is higher although the startup time is
reduced.

HAL_PWR_EnterSLEEPMode
Function Name

void HAL_PWR_EnterSLEEPMode (uint32_t Regulator, uint8_t
SLEEPEntry)

Function Description

Enters Sleep mode.

Parameters

Regulator: Specifies the regulator state in SLEEP mode.
This parameter can be one of the following values:
PWR_MAINREGULATOR_ON: SLEEP mode with
regulator ON
PWR_LOWPOWERREGULATOR_ON: SLEEP mode
with low power regulator ON
SLEEPEntry: Specifies if SLEEP mode in entered with WFI
or WFE instruction. This parameter can be one of the
following values:
PWR_SLEEPENTRY_WFI: enter SLEEP mode with WFI
instruction
PWR_SLEEPENTRY_WFE: enter SLEEP mode with
WFE instruction

Return values

None

Notes

In Sleep mode, all I/O pins keep the same state as in Run
mode.
In Sleep mode, the systick is stopped to avoid exit from this
mode with systick interrupt when used as time base for
Timeout
This parameter is not used for the STM32F4 family and is
kept as parameter just to maintain compatibility with the lower
power families.

HAL_PWR_EnterSTANDBYMode

584/964

Function Name

void HAL_PWR_EnterSTANDBYMode (void )

Function Description

Enters Standby mode.

Return values

None

Notes

In Standby mode, all I/O pins are high impedance except for:
DocID025834 Rev 4

UM1725

HAL PWR Generic Driver
Reset pad (still available)RTC_AF1 pin (PC13) if configured
for tamper, time-stamp, RTC Alarm out, or RTC clock
calibration out.RTC_AF2 pin (PI8) if configured for tamper or
time-stamp.WKUP pin 1 (PA0) if enabled.

HAL_PWR_PVD_IRQHandler
Function Name

void HAL_PWR_PVD_IRQHandler (void )

Function Description

This function handles the PWR PVD interrupt request.

Return values

None

Notes

This API should be called under the PVD_IRQHandler().

HAL_PWR_PVDCallback
Function Name

void HAL_PWR_PVDCallback (void )

Function Description

PWR PVD interrupt callback.

Return values

None

HAL_PWR_EnableSleepOnExit
Function Name

void HAL_PWR_EnableSleepOnExit (void )

Function Description

Indicates Sleep-On-Exit when returning from Handler mode to
Thread mode.

Return values

None

Notes

Set SLEEPONEXIT bit of SCR register. When this bit is set,
the processor re-enters SLEEP mode when an interruption
handling is over. Setting this bit is useful when the processor
is expected to run only on interruptions handling.

HAL_PWR_DisableSleepOnExit
Function Name

void HAL_PWR_DisableSleepOnExit (void )

Function Description

Disables Sleep-On-Exit feature when returning from Handler mode
to Thread mode.

Return values

None

Notes

Clears SLEEPONEXIT bit of SCR register. When this bit is
set, the processor re-enters SLEEP mode when an
interruption handling is over.

HAL_PWR_EnableSEVOnPend
Function Name

void HAL_PWR_EnableSEVOnPend (void )

Function Description

Enables CORTEX M4 SEVONPEND bit.

Return values

None

Notes

Sets SEVONPEND bit of SCR register. When this bit is set,
this causes WFE to wake up when an interrupt moves from

DocID025834 Rev 4

585/964

HAL PWR Generic Driver

UM1725
inactive to pended.

HAL_PWR_DisableSEVOnPend
Function Name

void HAL_PWR_DisableSEVOnPend (void )

Function Description

Disables CORTEX M4 SEVONPEND bit.

Return values

None

Notes

Clears SEVONPEND bit of SCR register. When this bit is set,
this causes WFE to wake up when an interrupt moves from
inactive to pended.

46.3

PWR Firmware driver defines

46.3.1

PWR
PWR CR Register alias address
DBP_BIT_NUMBER
CR_DBP_BB
PVDE_BIT_NUMBER
CR_PVDE_BB
PMODE_BIT_NUMBER
CR_PMODE_BB
PWR CSR Register alias address
EWUP_BIT_NUMBER
CSR_EWUP_BB
PWR Exported Macro
Description:

__HAL_PWR_GET_FLAG

Check PWR flag is set or
not.
Parameters:
__FLAG__: specifies the
flag to check. This
parameter can be one of the
following values:
PWR_FLAG_WU:
Wake Up flag. This flag
indicates that a wakeup
event was received
from the WKUP pin or
from the RTC alarm
(Alarm A or Alarm B),
RTC Tamper event,
RTC TimeStamp event
or RTC Wakeup. An
additional wakeup
event is detected if the
586/964

DocID025834 Rev 4

UM1725

HAL PWR Generic Driver
WKUP pin is enabled
(by setting the EWUP
bit) when the WKUP
pin level is already
high.
PWR_FLAG_SB:
StandBy flag. This flag
indicates that the
system was resumed
from StandBy mode.
PWR_FLAG_PVDO:
PVD Output. This flag
is valid only if PVD is
enabled by the
HAL_PWR_EnablePV
D() function. The PVD
is stopped by Standby
mode For this reason,
this bit is equal to 0
after Standby or reset
until the PVDE bit is
set.
PWR_FLAG_BRR:
Backup regulator ready
flag. This bit is not
reset when the device
wakes up from Standby
mode or by a system
reset or power reset.
PWR_FLAG_VOSRDY
: This flag indicates
that the Regulator
voltage scaling output
selection is ready.
Return value:
The: new state of
__FLAG__ (TRUE or
FALSE).
__HAL_PWR_CLEAR_FLAG

Description:
Clear the PWR's pending
flags.
Parameters:
__FLAG__: specifies the
flag to clear. This parameter
can be one of the following
values:
PWR_FLAG_WU:
Wake Up flag
PWR_FLAG_SB:
StandBy flag

__HAL_PWR_PVD_EXTI_ENABLE_IT
DocID025834 Rev 4

Description:
587/964

HAL PWR Generic Driver

UM1725
Enable the PVD Exti Line
16.
Return value:
None.

__HAL_PWR_PVD_EXTI_DISABLE_IT

Description:
Disable the PVD EXTI Line
16.
Return value:
None.

__HAL_PWR_PVD_EXTI_ENABLE_EVENT

Description:
Enable event on PVD Exti
Line 16.
Return value:
None.

__HAL_PWR_PVD_EXTI_DISABLE_EVENT

Description:
Disable event on PVD Exti
Line 16.
Return value:
None.

__HAL_PWR_PVD_EXTI_ENABLE_RISING_EDGE

Description:
Enable the PVD Extended
Interrupt Rising Trigger.
Return value:
None.

__HAL_PWR_PVD_EXTI_DISABLE_RISING_EDGE

Description:
Disable the PVD Extended
Interrupt Rising Trigger.
Return value:
None.

__HAL_PWR_PVD_EXTI_ENABLE_FALLING_EDGE

Description:
Enable the PVD Extended
Interrupt Falling Trigger.
Return value:
None.

__HAL_PWR_PVD_EXTI_DISABLE_FALLING_EDGE

Description:
Disable the PVD Extended
Interrupt Falling Trigger.
Return value:

588/964

DocID025834 Rev 4

UM1725

HAL PWR Generic Driver
None.
__HAL_PWR_PVD_EXTI_ENABLE_RISING_FALLIN
G_EDGE

Description:
PVD EXTI line
configuration: set rising &
falling edge trigger.
Return value:
None.

__HAL_PWR_PVD_EXTI_DISABLE_RISING_FALLIN
G_EDGE

Description:
Disable the PVD Extended
Interrupt Rising & Falling
Trigger.
Return value:
None.

__HAL_PWR_PVD_EXTI_GET_FLAG

Description:
checks whether the
specified PVD Exti interrupt
flag is set or not.
Return value:
EXTI: PVD Line Status.

__HAL_PWR_PVD_EXTI_CLEAR_FLAG

Description:
Clear the PVD Exti flag.
Return value:
None.

__HAL_PWR_PVD_EXTI_GENERATE_SWIT

Description:
Generates a Software
interrupt on PVD EXTI line.
Return value:
None

PWR Flag
PWR_FLAG_WU
PWR_FLAG_SB
PWR_FLAG_PVDO
PWR_FLAG_BRR
PWR_FLAG_VOSRDY
PWR Private macros to check input parameters
IS_PWR_PVD_LEVEL
IS_PWR_PVD_MODE
IS_PWR_REGULATOR

DocID025834 Rev 4

589/964

HAL PWR Generic Driver
IS_PWR_SLEEP_ENTRY

UM1725

IS_PWR_STOP_ENTRY
PWR PVD detection level
PWR_PVDLEVEL_0
PWR_PVDLEVEL_1
PWR_PVDLEVEL_2
PWR_PVDLEVEL_3
PWR_PVDLEVEL_4
PWR_PVDLEVEL_5
PWR_PVDLEVEL_6
PWR_PVDLEVEL_7
PWR PVD EXTI Line
PWR_EXTI_LINE_PVD

External interrupt line 16 Connected to the PVD EXTI Line

PWR PVD Mode
PWR_PVD_MODE_NORMAL

basic mode is used

PWR_PVD_MODE_IT_RISING

External Interrupt Mode with Rising edge
trigger detection

PWR_PVD_MODE_IT_FALLING

External Interrupt Mode with Falling
edge trigger detection

PWR_PVD_MODE_IT_RISING_FALLING

External Interrupt Mode with
Rising/Falling edge trigger detection

PWR_PVD_MODE_EVENT_RISING

Event Mode with Rising edge trigger
detection

PWR_PVD_MODE_EVENT_FALLING

Event Mode with Falling edge trigger
detection

PWR_PVD_MODE_EVENT_RISING_FALLING

Event Mode with Rising/Falling edge
trigger detection

PWR PVD Mode Mask
PVD_MODE_IT
PVD_MODE_EVT
PVD_RISING_EDGE
PVD_FALLING_EDGE
PWR Register alias address
PWR_OFFSET
PWR_CR_OFFSET
PWR_CSR_OFFSET
PWR_CR_OFFSET_BB
PWR_CSR_OFFSET_BB

590/964

DocID025834 Rev 4

UM1725

HAL PWR Generic Driver
PWR Regulator state in SLEEP/STOP mode
PWR_MAINREGULATOR_ON
PWR_LOWPOWERREGULATOR_ON
PWR SLEEP mode entry
PWR_SLEEPENTRY_WFI
PWR_SLEEPENTRY_WFE
PWR STOP mode entry
PWR_STOPENTRY_WFI
PWR_STOPENTRY_WFE
PWR WakeUp Pins
PWR_WAKEUP_PIN1

DocID025834 Rev 4

591/964

HAL PWR Extension Driver

UM1725

47

HAL PWR Extension Driver

47.1

PWREx Firmware driver API description

47.1.1

Peripheral extended features functions
Main and Backup Regulators configuration
The backup domain includes 4 Kbytes of backup SRAM accessible only from the
CPU, and address in 32-bit, 16-bit or 8-bit mode. Its content is retained even in
Standby or VBAT mode when the low power backup regulator is enabled. It can be
considered as an internal EEPROM when VBAT is always present. You can use the
HAL_PWREx_EnableBkUpReg() function to enable the low power backup regulator.
When the backup domain is supplied by VDD (analog switch connected to VDD) the
backup SRAM is powered from VDD which replaces the VBAT power supply to save
battery life.
The backup SRAM is not mass erased by a tamper event. It is read protected to
prevent confidential data, such as cryptographic private key, from being accessed.
The backup SRAM can be erased only through the Flash interface when a protection
level change from level 1 to level 0 is requested. Refer to the description of Read
protection (RDP) in the Flash programming manual.
The main internal regulator can be configured to have a tradeoff between
performance and power consumption when the device does not operate at the
maximum frequency. This is done through
__HAL_PWR_MAINREGULATORMODE_CONFIG() macro which configure VOS bit
in PWR_CR register Refer to the product datasheets for more details.

FLASH Power Down configuration
By setting the FPDS bit in the PWR_CR register by using the
HAL_PWREx_EnableFlashPowerDown() function, the Flash memory also enters
power down mode when the device enters Stop mode. When the Flash memory is in
power down mode, an additional startup delay is incurred when waking up from Stop
mode.
For STM32F42xxx/43xxx/446xx/469xx/479xx Devices, the scale can be modified only
when the PLL is OFF and the HSI or HSE clock source is selected as system clock.
The new value programmed is active only when the PLL is ON. When the PLL is OFF,
the voltage scale 3 is automatically selected. Refer to the datasheets for more details.

Over-Drive and Under-Drive configuration
For STM32F42xxx/43xxx/446xx/469xx/479xx Devices, in Run mode: the main
regulator has 2 operating modes available:
Normal mode: The CPU and core logic operate at maximum frequency at a
given voltage scaling (scale 1, scale 2 or scale 3)
Over-drive mode: This mode allows the CPU and the core logic to operate at a
higher frequency than the normal mode for a given voltage scaling (scale 1, scale
2 or scale 3). This mode is enabled through HAL_PWREx_EnableOverDrive()
592/964

DocID025834 Rev 4

UM1725

HAL PWR Extension Driver
function and disabled by HAL_PWREx_DisableOverDrive() function, to enter or
exit from Over-drive mode please follow the sequence described in Reference
manual.
For STM32F42xxx/43xxx/446xx/469xx/479xx Devices, in Stop mode: the main
regulator or low power regulator supplies a low power voltage to the 1.2V domain,
thus preserving the content of registers and internal SRAM. 2 operating modes are
available:
Normal mode: the 1.2V domain is preserved in nominal leakage mode. This
mode is only available when the main regulator or the low power regulator is
used in Scale 3 or low voltage mode.
Under-drive mode: the 1.2V domain is preserved in reduced leakage mode. This
mode is only available when the main regulator or the low power regulator is in
low voltage mode.
This section contains the following APIs:
HAL_PWREx_EnableBkUpReg()
HAL_PWREx_DisableBkUpReg()
HAL_PWREx_EnableFlashPowerDown()
HAL_PWREx_DisableFlashPowerDown()
HAL_PWREx_GetVoltageRange()
HAL_PWREx_ControlVoltageScaling()
HAL_PWREx_EnableWakeUpPinPolarityRisingEdge()
HAL_PWREx_EnableWakeUpPinPolarityFallingEdge()
HAL_PWREx_EnableOverDrive()
HAL_PWREx_DisableOverDrive()
HAL_PWREx_EnterUnderDriveSTOPMode()

47.1.2

Detailed description of functions
HAL_PWREx_EnableFlashPowerDown
Function Name

void HAL_PWREx_EnableFlashPowerDown (void )

Function Description

Enables the Flash Power Down in Stop mode.

Return values

None

HAL_PWREx_DisableFlashPowerDown
Function Name

void HAL_PWREx_DisableFlashPowerDown (void )

Function Description

Disables the Flash Power Down in Stop mode.

Return values

None

HAL_PWREx_EnableBkUpReg
Function Name

HAL_StatusTypeDef HAL_PWREx_EnableBkUpReg (void )

Function Description

Enables the Backup Regulator.

Return values

HAL: status

HAL_PWREx_DisableBkUpReg
Function Name

HAL_StatusTypeDef HAL_PWREx_DisableBkUpReg (void )

DocID025834 Rev 4

593/964

HAL PWR Extension Driver
Function Description
Return values

UM1725
Disables the Backup Regulator.
HAL: status

HAL_PWREx_GetVoltageRange
Function Name

uint32_t HAL_PWREx_GetVoltageRange (void )

Function Description

Return Voltage Scaling Range.

Return values

The: configured scale for the regulator voltage(VOS bit field).
The returned value can be one of the following:
PWR_REGULATOR_VOLTAGE_SCALE1:
Regulator voltage output Scale 1 mode
PWR_REGULATOR_VOLTAGE_SCALE2:
Regulator voltage output Scale 2 mode
PWR_REGULATOR_VOLTAGE_SCALE3:
Regulator voltage output Scale 3 mode

HAL_PWREx_ControlVoltageScaling

594/964

Function Name

HAL_StatusTypeDef HAL_PWREx_ControlVoltageScaling
(uint32_t VoltageScaling)

Function Description

Configures the main internal regulator output voltage.

Parameters

VoltageScaling: specifies the regulator output voltage to
achieve a tradeoff between performance and power
consumption. This parameter can be one of the following
values:
PWR_REGULATOR_VOLTAGE_SCALE1: Regulator
voltage output range 1 mode, the maximum value of
fHCLK is 168 MHz. It can be extended to 180 MHz by
activating the over-drive mode.
PWR_REGULATOR_VOLTAGE_SCALE2: Regulator
voltage output range 2 mode, the maximum value of
fHCLK is 144 MHz. It can be extended to, 168 MHz by
activating the over-drive mode.
PWR_REGULATOR_VOLTAGE_SCALE3: Regulator
voltage output range 3 mode, the maximum value of
fHCLK is 120 MHz.

Return values

HAL: Status

Notes

To update the system clock frequency(SYSCLK): Set the HSI
or HSE as system clock frequency using the
HAL_RCC_ClockConfig().Call the HAL_RCC_OscConfig() to
configure the PLL.Call HAL_PWREx_ConfigVoltageScaling()
API to adjust the voltage scale.Set the new system clock
frequency using the HAL_RCC_ClockConfig().
The scale can be modified only when the HSI or HSE clock
source is selected as system clock source, otherwise the API
returns HAL_ERROR.
When the PLL is OFF, the voltage scale 3 is automatically
selected and the VOS bits value in the PWR_CR1 register are
not taken in account.
This API forces the PLL state ON to allow the possibility to
configure the voltage scale 1 or 2.
DocID025834 Rev 4

UM1725

HAL PWR Extension Driver
The new voltage scale is active only when the PLL is ON.

HAL_PWREx_EnableWakeUpPinPolarityRisingEdge
Function Name

void HAL_PWREx_EnableWakeUpPinPolarityRisingEdge
(void )

Function Description

Enables Wakeup Pin Detection on high level (rising edge).

Return values

None

HAL_PWREx_EnableWakeUpPinPolarityFallingEdge
Function Name

void HAL_PWREx_EnableWakeUpPinPolarityFallingEdge
(void )

Function Description

Enables Wakeup Pin Detection on low level (falling edge).

Return values

None

HAL_PWREx_EnableOverDrive
Function Name

HAL_StatusTypeDef HAL_PWREx_EnableOverDrive (void )

Function
Description

Activates the Over-Drive mode.

Return values

HAL: status

Notes

This function can be used only for
STM32F42xx/STM32F43xx/STM32F446xx/STM32F469xx/STM32F
479xx devices. This mode allows the CPU and the core logic to
operate at a higher frequency than the normal mode for a given
voltage scaling (scale 1, scale 2 or scale 3).
It is recommended to enter or exit Over-drive mode when the
application is not running critical tasks and when the system clock
source is either HSI or HSE. During the Over-drive switch activation,
no peripheral clocks should be enabled. The peripheral clocks must
be enabled once the Over-drive mode is activated.

HAL_PWREx_DisableOverDrive
Function Name

HAL_StatusTypeDef HAL_PWREx_DisableOverDrive (void )

Function
Description

Deactivates the Over-Drive mode.

Return values

HAL: status

Notes

This function can be used only for
STM32F42xx/STM32F43xx/STM32F446xx/STM32F469xx/STM32F
479xx devices. This mode allows the CPU and the core logic to
operate at a higher frequency than the normal mode for a given
voltage scaling (scale 1, scale 2 or scale 3).
It is recommended to enter or exit Over-drive mode when the
application is not running critical tasks and when the system clock
source is either HSI or HSE. During the Over-drive switch activation,
no peripheral clocks should be enabled. The peripheral clocks must
be enabled once the Over-drive mode is activated.
DocID025834 Rev 4

595/964

HAL PWR Extension Driver

UM1725

HAL_PWREx_EnterUnderDriveSTOPMode
Function
Name

HAL_StatusTypeDef HAL_PWREx_EnterUnderDriveSTOPMode
(uint32_t Regulator, uint8_t STOPEntry)

Function
Description

Enters in Under-Drive STOP mode.

Parameters

Regulator: specifies the regulator state in STOP mode. This
parameter can be one of the following values:
PWR_MAINREGULATOR_UNDERDRIVE_ON: Main Regulator
in under-drive mode and Flash memory in power-down when the
device is in Stop under-drive mode
PWR_LOWPOWERREGULATOR_UNDERDRIVE_ON: Low
Power Regulator in under-drive mode and Flash memory in
power-down when the device is in Stop under-drive mode
STOPEntry: specifies if STOP mode in entered with WFI or WFE
instruction. This parameter can be one of the following values:
PWR_SLEEPENTRY_WFI: enter STOP mode with WFI
instruction
PWR_SLEEPENTRY_WFE: enter STOP mode with WFE
instruction

Return
values

None

Notes

This mode is only available for
STM32F42xxx/STM324F3xxx/STM32F446xx/STM32F469xx/STM32F
479xx devices.
This mode can be selected only when the Under-Drive is already
active
This mode is enabled only with STOP low power mode. In this mode,
the 1.2V domain is preserved in reduced leakage mode. This mode is
only available when the main regulator or the low power regulator is in
low voltage mode
If the Under-drive mode was enabled, it is automatically disabled after
exiting Stop mode. When the voltage regulator operates in Under-drive
mode, an additional startup delay is induced when waking up from
Stop mode.
In Stop mode, all I/O pins keep the same state as in Run mode.
When exiting Stop mode by issuing an interrupt or a wake-up event,
the HSI RC oscillator is selected as system clock.
When the voltage regulator operates in low power mode, an additional
startup delay is incurred when waking up from Stop mode. By keeping
the internal regulator ON during Stop mode, the consumption is higher
although the startup time is reduced.

47.2

PWREx Firmware driver defines

47.2.1

PWREx
PWRx CSR Register alias address
BRE_BIT_NUMBER
CSR_BRE_BB

596/964

DocID025834 Rev 4

UM1725

HAL PWR Extension Driver
WUPP_BIT_NUMBER
CSR_WUPP_BB
PWREx Exported Constants
__HAL_PWR_VOLTAGESCALING_CON
FIG

Description:
macros configure the main internal
regulator output voltage.
Parameters:
__REGULATOR__: specifies the
regulator output voltage to achieve a
tradeoff between performance and power
consumption when the device does not
operate at the maximum frequency (refer
to the datasheets for more details). This
parameter can be one of the following
values:
PWR_REGULATOR_VOLTAGE_SC
ALE1: Regulator voltage output
Scale 1 mode
PWR_REGULATOR_VOLTAGE_SC
ALE2: Regulator voltage output
Scale 2 mode
PWR_REGULATOR_VOLTAGE_SC
ALE3: Regulator voltage output
Scale 3 mode
Return value:
None

__HAL_PWR_OVERDRIVE_ENABLE

Notes:
These macros can be used only for
STM32F42xx/STM3243xx devices.

__HAL_PWR_OVERDRIVE_DISABLE
__HAL_PWR_OVERDRIVESWITCHING
_ENABLE

Notes:
These macros can be used only for
STM32F42xx/STM3243xx devices.

__HAL_PWR_OVERDRIVESWITCHING
_DISABLE
__HAL_PWR_UNDERDRIVE_ENABLE

Notes:
This mode is enabled only with STOP low
power mode. In this mode, the 1.2V
domain is preserved in reduced leakage
mode. This mode is only available when
the main regulator or the low power
regulator is in low voltage mode. If the
Under-drive mode was enabled, it is
automatically disabled after exiting Stop
mode. When the voltage regulator
operates in Under-drive mode, an
additional startup delay is induced when

DocID025834 Rev 4

597/964

HAL PWR Extension Driver

UM1725
waking up from Stop mode.

__HAL_PWR_UNDERDRIVE_DISABLE
__HAL_PWR_GET_ODRUDR_FLAG

Description:
Check PWR flag is set or not.
Parameters:
__FLAG__: specifies the flag to check.
This parameter can be one of the
following values:
PWR_FLAG_ODRDY: This flag
indicates that the Over-drive mode is
ready
PWR_FLAG_ODSWRDY: This flag
indicates that the Over-drive mode
switching is ready
PWR_FLAG_UDRDY: This flag
indicates that the Under-drive mode
is enabled in Stop mode
Return value:
The: new state of __FLAG__ (TRUE or
FALSE).
Notes:
These macros can be used only for
STM32F42xx/STM3243xx devices.

__HAL_PWR_CLEAR_ODRUDR_FLAG

Notes:
These macros can be used only for
STM32F42xx/STM3243xx devices.

PWREx Private macros to check input parameters
IS_PWR_REGULATOR_UNDERDRIVE
IS_PWR_VOLTAGE_SCALING_RANGE
IS_PWR_WAKEUP_PIN
PWREx Over Under Drive Flag
PWR_FLAG_ODRDY
PWR_FLAG_ODSWRDY
PWR_FLAG_UDRDY
PWREx Register alias address
FPDS_BIT_NUMBER
CR_FPDS_BB
ODEN_BIT_NUMBER
CR_ODEN_BB
ODSWEN_BIT_NUMBER
CR_ODSWEN_BB
598/964

DocID025834 Rev 4

UM1725

HAL PWR Extension Driver
MRLVDS_BIT_NUMBER
CR_MRLVDS_BB
LPLVDS_BIT_NUMBER
CR_LPLVDS_BB
PWREx Regulator state in UnderDrive mode
PWR_MAINREGULATOR_UNDERDRIVE_ON
PWR_LOWPOWERREGULATOR_UNDERDRIVE_ON
PWREx Regulator Voltage Scale
PWR_REGULATOR_VOLTAGE_SCALE1
PWR_REGULATOR_VOLTAGE_SCALE2
PWR_REGULATOR_VOLTAGE_SCALE3

DocID025834 Rev 4

599/964

HAL QSPI Generic Driver

UM1725

48

HAL QSPI Generic Driver

48.1

QSPI Firmware driver registers structures

48.1.1

QSPI_InitTypeDef
Data Fields
uint32_t ClockPrescaler
uint32_t FifoThreshold
uint32_t SampleShifting
uint32_t FlashSize
uint32_t ChipSelectHighTime
uint32_t ClockMode
uint32_t FlashID
uint32_t DualFlash

Field Documentation
uint32_t QSPI_InitTypeDef::ClockPrescaler
uint32_t QSPI_InitTypeDef::FifoThreshold
uint32_t QSPI_InitTypeDef::SampleShifting
uint32_t QSPI_InitTypeDef::FlashSize
uint32_t QSPI_InitTypeDef::ChipSelectHighTime
uint32_t QSPI_InitTypeDef::ClockMode
uint32_t QSPI_InitTypeDef::FlashID
uint32_t QSPI_InitTypeDef::DualFlash

48.1.2

QSPI_HandleTypeDef
Data Fields
QUADSPI_TypeDef * Instance
QSPI_InitTypeDef Init
uint8_t * pTxBuffPtr
__IO uint16_t TxXferSize
__IO uint16_t TxXferCount
uint8_t * pRxBuffPtr
__IO uint16_t RxXferSize
__IO uint16_t RxXferCount
DMA_HandleTypeDef * hdma
__IO HAL_LockTypeDef Lock
__IO HAL_QSPI_StateTypeDef State
__IO uint32_t ErrorCode
uint32_t Timeout

600/964

DocID025834 Rev 4

UM1725

HAL QSPI Generic Driver
Field Documentation
QUADSPI_TypeDef* QSPI_HandleTypeDef::Instance
QSPI_InitTypeDef QSPI_HandleTypeDef::Init
uint8_t* QSPI_HandleTypeDef::pTxBuffPtr
__IO uint16_t QSPI_HandleTypeDef::TxXferSize
__IO uint16_t QSPI_HandleTypeDef::TxXferCount
uint8_t* QSPI_HandleTypeDef::pRxBuffPtr
__IO uint16_t QSPI_HandleTypeDef::RxXferSize
__IO uint16_t QSPI_HandleTypeDef::RxXferCount
DMA_HandleTypeDef* QSPI_HandleTypeDef::hdma
__IO HAL_LockTypeDef QSPI_HandleTypeDef::Lock
__IO HAL_QSPI_StateTypeDef QSPI_HandleTypeDef::State
__IO uint32_t QSPI_HandleTypeDef::ErrorCode
uint32_t QSPI_HandleTypeDef::Timeout

48.1.3

QSPI_CommandTypeDef
Data Fields
uint32_t Instruction
uint32_t Address
uint32_t AlternateBytes
uint32_t AddressSize
uint32_t AlternateBytesSize
uint32_t DummyCycles
uint32_t InstructionMode
uint32_t AddressMode
uint32_t AlternateByteMode
uint32_t DataMode
uint32_t NbData
uint32_t DdrMode
uint32_t DdrHoldHalfCycle
uint32_t SIOOMode

Field Documentation
uint32_t QSPI_CommandTypeDef::Instruction
uint32_t QSPI_CommandTypeDef::Address
uint32_t QSPI_CommandTypeDef::AlternateBytes
uint32_t QSPI_CommandTypeDef::AddressSize
uint32_t QSPI_CommandTypeDef::AlternateBytesSize
uint32_t QSPI_CommandTypeDef::DummyCycles
uint32_t QSPI_CommandTypeDef::InstructionMode
uint32_t QSPI_CommandTypeDef::AddressMode
uint32_t QSPI_CommandTypeDef::AlternateByteMode
uint32_t QSPI_CommandTypeDef::DataMode
uint32_t QSPI_CommandTypeDef::NbData
uint32_t QSPI_CommandTypeDef::DdrMode
uint32_t QSPI_CommandTypeDef::DdrHoldHalfCycle
uint32_t QSPI_CommandTypeDef::SIOOMode
DocID025834 Rev 4

601/964

HAL QSPI Generic Driver

48.1.4

UM1725

QSPI_AutoPollingTypeDef
Data Fields
uint32_t Match
uint32_t Mask
uint32_t Interval
uint32_t StatusBytesSize
uint32_t MatchMode
uint32_t AutomaticStop

Field Documentation
uint32_t QSPI_AutoPollingTypeDef::Match
uint32_t QSPI_AutoPollingTypeDef::Mask
uint32_t QSPI_AutoPollingTypeDef::Interval
uint32_t QSPI_AutoPollingTypeDef::StatusBytesSize
uint32_t QSPI_AutoPollingTypeDef::MatchMode
uint32_t QSPI_AutoPollingTypeDef::AutomaticStop

48.1.5

QSPI_MemoryMappedTypeDef
Data Fields
uint32_t TimeOutPeriod
uint32_t TimeOutActivation

Field Documentation
uint32_t QSPI_MemoryMappedTypeDef::TimeOutPeriod
uint32_t QSPI_MemoryMappedTypeDef::TimeOutActivation

48.2

QSPI Firmware driver API description

48.2.1

How to use this driver

Initialization
1.

602/964

As prerequisite, fill in the HAL_QSPI_MspInit() :
Enable QuadSPI clock interface with __HAL_RCC_QSPI_CLK_ENABLE().
Reset QuadSPI IP with __HAL_RCC_QSPI_FORCE_RESET() and
__HAL_RCC_QSPI_RELEASE_RESET().
Enable the clocks for the QuadSPI GPIOS with
__HAL_RCC_GPIOx_CLK_ENABLE().
DocID025834 Rev 4

UM1725

HAL QSPI Generic Driver

2.

Configure these QuadSPI pins in alternate mode using HAL_GPIO_Init().
If interrupt mode is used, enable and configure QuadSPI global interrupt with
HAL_NVIC_SetPriority() and HAL_NVIC_EnableIRQ().
If DMA mode is used, enable the clocks for the QuadSPI DMA channel with
__HAL_RCC_DMAx_CLK_ENABLE(), configure DMA with HAL_DMA_Init(), link
it with QuadSPI handle using __HAL_LINKDMA(), enable and configure DMA
channel global interrupt with HAL_NVIC_SetPriority() and
HAL_NVIC_EnableIRQ().
Configure the flash size, the clock prescaler, the fifo threshold, the clock mode, the
sample shifting and the CS high time using the HAL_QSPI_Init() function.

Indirect functional mode
1.

2.

3.

4.

Configure the command sequence using the HAL_QSPI_Command() or
HAL_QSPI_Command_IT() functions :
Instruction phase : the mode used and if present the instruction opcode.
Address phase : the mode used and if present the size and the address value.
Alternate-bytes phase : the mode used and if present the size and the alternate
bytes values.
Dummy-cycles phase : the number of dummy cycles (mode used is same as
data phase).
Data phase : the mode used and if present the number of bytes.
Double Data Rate (DDR) mode : the activation (or not) of this mode and the
delay if activated.
Sending Instruction Only Once (SIOO) mode : the activation (or not) of this
mode.
If no data is required for the command, it is sent directly to the memory :
In polling mode, the output of the function is done when the transfer is complete.
In interrupt mode, HAL_QSPI_CmdCpltCallback() will be called when the
transfer is complete.
For the indirect write mode, use HAL_QSPI_Transmit(), HAL_QSPI_Transmit_DMA()
or HAL_QSPI_Transmit_IT() after the command configuration :
In polling mode, the output of the function is done when the transfer is complete.
In interrupt mode, HAL_QSPI_FifoThresholdCallback() will be called when the
fifo threshold is reached and HAL_QSPI_TxCpltCallback() will be called when the
transfer is complete.
In DMA mode, HAL_QSPI_TxHalfCpltCallback() will be called at the half transfer
and HAL_QSPI_TxCpltCallback() will be called when the transfer is complete.
For the indirect read mode, use HAL_QSPI_Receive(), HAL_QSPI_Receive_DMA()
or HAL_QSPI_Receive_IT() after the command configuration :
In polling mode, the output of the function is done when the transfer is complete.
In interrupt mode, HAL_QSPI_FifoThresholdCallback() will be called when the
fifo threshold is reached and HAL_QSPI_RxCpltCallback() will be called when the
transfer is complete.
In DMA mode, HAL_QSPI_RxHalfCpltCallback() will be called at the half transfer
and HAL_QSPI_RxCpltCallback() will be called when the transfer is complete.

Auto-polling functional mode
1.

Configure the command sequence and the auto-polling functional mode using the
HAL_QSPI_AutoPolling() or HAL_QSPI_AutoPolling_IT() functions :
Instruction phase : the mode used and if present the instruction opcode.
DocID025834 Rev 4

603/964

HAL QSPI Generic Driver

2.

UM1725

Address phase : the mode used and if present the size and the address value.
Alternate-bytes phase : the mode used and if present the size and the alternate
bytes values.
Dummy-cycles phase : the number of dummy cycles (mode used is same as
data phase).
Data phase : the mode used.
Double Data Rate (DDR) mode : the activation (or not) of this mode and the
delay if activated.
Sending Instruction Only Once (SIOO) mode : the activation (or not) of this
mode.
The size of the status bytes, the match value, the mask used, the match mode
(OR/AND), the polling interval and the automatic stop activation.
After the configuration :
In polling mode, the output of the function is done when the status match is
reached. The automatic stop is activated to avoid an infinite loop.
In interrupt mode, HAL_QSPI_StatusMatchCallback() will be called each time
the status match is reached.

Memory-mapped functional mode
1.

2.

Configure the command sequence and the memory-mapped functional mode using
the HAL_QSPI_MemoryMapped() functions :
Instruction phase : the mode used and if present the instruction opcode.
Address phase : the mode used and the size.
Alternate-bytes phase : the mode used and if present the size and the alternate
bytes values.
Dummy-cycles phase : the number of dummy cycles (mode used is same as
data phase).
Data phase : the mode used.
Double Data Rate (DDR) mode : the activation (or not) of this mode and the
delay if activated.
Sending Instruction Only Once (SIOO) mode : the activation (or not) of this
mode.
The timeout activation and the timeout period.
After the configuration, the QuadSPI will be used as soon as an access on the AHB is
done on the address range. HAL_QSPI_TimeOutCallback() will be called when the
timeout expires.

Errors management and abort functionality
1.
2.

604/964

HAL_QSPI_GetError() function gives the error raised during the last operation.
HAL_QSPI_Abort() and HAL_QSPI_AbortIT() functions aborts any on-going operation
and flushes the fifo :
In polling mode, the output of the function is done when the transfer complete bit
is set and the busy bit cleared.
In interrupt mode, HAL_QSPI_AbortCpltCallback() will be called when the
transfer complete bi is set.

DocID025834 Rev 4

UM1725

HAL QSPI Generic Driver

Control functions
1.
2.
3.
4.

HAL_QSPI_GetState() function gives the current state of the HAL QuadSPI driver.
HAL_QSPI_SetTimeout() function configures the timeout value used in the driver.
HAL_QSPI_SetFifoThreshold() function configures the threshold on the Fifo of the
QSPI IP.
HAL_QSPI_GetFifoThreshold() function gives the current of the Fifo's threshold

Workarounds linked to Silicon Limitation
1.

48.2.2

Workarounds Implemented inside HAL Driver
Extra data written in the FIFO at the end of a read transfer

Initialization and Configuration functions
This subsection provides a set of functions allowing to :
Initialize the QuadSPI.
De-initialize the QuadSPI.
This section contains the following APIs:
HAL_QSPI_Init()
HAL_QSPI_DeInit()
HAL_QSPI_MspInit()
HAL_QSPI_MspDeInit()

48.2.3

IO operation functions
This subsection provides a set of functions allowing to :
Handle the interrupts.
Handle the command sequence.
Transmit data in blocking, interrupt or DMA mode.
Receive data in blocking, interrupt or DMA mode.
Manage the auto-polling functional mode.
Manage the memory-mapped functional mode.
This section contains the following APIs:
HAL_QSPI_IRQHandler()
HAL_QSPI_Command()
HAL_QSPI_Command_IT()
HAL_QSPI_Transmit()
HAL_QSPI_Receive()
HAL_QSPI_Transmit_IT()
HAL_QSPI_Receive_IT()
HAL_QSPI_Transmit_DMA()
HAL_QSPI_Receive_DMA()
HAL_QSPI_AutoPolling()
HAL_QSPI_AutoPolling_IT()
HAL_QSPI_MemoryMapped()
HAL_QSPI_ErrorCallback()
DocID025834 Rev 4

605/964

HAL QSPI Generic Driver

UM1725

HAL_QSPI_AbortCpltCallback()
HAL_QSPI_CmdCpltCallback()
HAL_QSPI_RxCpltCallback()
HAL_QSPI_TxCpltCallback()
HAL_QSPI_RxHalfCpltCallback()
HAL_QSPI_TxHalfCpltCallback()
HAL_QSPI_FifoThresholdCallback()
HAL_QSPI_StatusMatchCallback()
HAL_QSPI_TimeOutCallback()

48.2.4

Peripheral Control and State functions
This subsection provides a set of functions allowing to :
Check in run-time the state of the driver.
Check the error code set during last operation.
Abort any operation.
This section contains the following APIs:
HAL_QSPI_GetState()
HAL_QSPI_GetError()
HAL_QSPI_Abort()
HAL_QSPI_Abort_IT()
HAL_QSPI_SetTimeout()
HAL_QSPI_SetFifoThreshold()
HAL_QSPI_GetFifoThreshold()
HAL_QSPI_ErrorCallback()
HAL_QSPI_AbortCpltCallback()
HAL_QSPI_FifoThresholdCallback()
HAL_QSPI_CmdCpltCallback()
HAL_QSPI_RxCpltCallback()
HAL_QSPI_TxCpltCallback()
HAL_QSPI_RxHalfCpltCallback()
HAL_QSPI_TxHalfCpltCallback()
HAL_QSPI_StatusMatchCallback()
HAL_QSPI_TimeOutCallback()

48.2.5

Detailed description of functions
HAL_QSPI_Init

606/964

Function Name

HAL_StatusTypeDef HAL_QSPI_Init (QSPI_HandleTypeDef *
hqspi)

Function Description

Initializes the QSPI mode according to the specified parameters in
the QSPI_InitTypeDef and creates the associated handle.

Parameters

hqspi: qspi handle

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL QSPI Generic Driver

HAL_QSPI_DeInit
Function Name

HAL_StatusTypeDef HAL_QSPI_DeInit (QSPI_HandleTypeDef
* hqspi)

Function Description

DeInitializes the QSPI peripheral.

Parameters

hqspi: qspi handle

Return values

HAL: status

HAL_QSPI_MspInit
Function Name

void HAL_QSPI_MspInit (QSPI_HandleTypeDef * hqspi)

Function Description

QSPI MSP Init.

Parameters

hqspi: QSPI handle

Return values

None

HAL_QSPI_MspDeInit
Function Name

void HAL_QSPI_MspDeInit (QSPI_HandleTypeDef * hqspi)

Function Description

QSPI MSP DeInit.

Parameters

hqspi: QSPI handle

Return values

None

HAL_QSPI_IRQHandler
Function Name

void HAL_QSPI_IRQHandler (QSPI_HandleTypeDef * hqspi)

Function Description

This function handles QSPI interrupt request.

Parameters

hqspi: QSPI handle

Return values

None.:

HAL_QSPI_Command
Function Name

HAL_StatusTypeDef HAL_QSPI_Command
(QSPI_HandleTypeDef * hqspi, QSPI_CommandTypeDef *
cmd, uint32_t Timeout)

Function Description

Sets the command configuration.

Parameters

hqspi: QSPI handle
cmd: : structure that contains the command configuration
information
Timeout: : Time out duration

Return values

HAL: status

Notes

This function is used only in Indirect Read or Write Modes

DocID025834 Rev 4

607/964

HAL QSPI Generic Driver

UM1725

HAL_QSPI_Transmit
Function Name

HAL_StatusTypeDef HAL_QSPI_Transmit
(QSPI_HandleTypeDef * hqspi, uint8_t * pData, uint32_t
Timeout)

Function Description

Transmit an amount of data in blocking mode.

Parameters

hqspi: QSPI handle
pData: pointer to data buffer
Timeout: : Time out duration

Return values

HAL: status

Notes

This function is used only in Indirect Write Mode

HAL_QSPI_Receive
Function Name

HAL_StatusTypeDef HAL_QSPI_Receive
(QSPI_HandleTypeDef * hqspi, uint8_t * pData, uint32_t
Timeout)

Function Description

Receive an amount of data in blocking mode.

Parameters

hqspi: QSPI handle
pData: pointer to data buffer
Timeout: : Time out duration

Return values

HAL: status

Notes

This function is used only in Indirect Read Mode

HAL_QSPI_Command_IT
Function Name

HAL_StatusTypeDef HAL_QSPI_Command_IT
(QSPI_HandleTypeDef * hqspi, QSPI_CommandTypeDef *
cmd)

Function Description

Sets the command configuration in interrupt mode.

Parameters

hqspi: QSPI handle
cmd: : structure that contains the command configuration
information

Return values

HAL: status

Notes

This function is used only in Indirect Read or Write Modes

HAL_QSPI_Transmit_IT

608/964

Function Name

HAL_StatusTypeDef HAL_QSPI_Transmit_IT
(QSPI_HandleTypeDef * hqspi, uint8_t * pData)

Function Description

Send an amount of data in interrupt mode.

Parameters

hqspi: QSPI handle
pData: pointer to data buffer

Return values

HAL: status

Notes

This function is used only in Indirect Write Mode

DocID025834 Rev 4

UM1725

HAL QSPI Generic Driver

HAL_QSPI_Receive_IT
Function Name

HAL_StatusTypeDef HAL_QSPI_Receive_IT
(QSPI_HandleTypeDef * hqspi, uint8_t * pData)

Function Description

Receive an amount of data in no-blocking mode with Interrupt.

Parameters

hqspi: QSPI handle
pData: pointer to data buffer

Return values

HAL: status

Notes

This function is used only in Indirect Read Mode

HAL_QSPI_Transmit_DMA
Function Name

HAL_StatusTypeDef HAL_QSPI_Transmit_DMA
(QSPI_HandleTypeDef * hqspi, uint8_t * pData)

Function Description

Sends an amount of data in non blocking mode with DMA.

Parameters

hqspi: QSPI handle
pData: pointer to data buffer

Return values

HAL: status

Notes

This function is used only in Indirect Write Mode
If DMA peripheral access is configured as halfword, the
number of data and the fifo threshold should be aligned on
halfword
If DMA peripheral access is configured as word, the number
of data and the fifo threshold should be aligned on word

HAL_QSPI_Receive_DMA
Function Name

HAL_StatusTypeDef HAL_QSPI_Receive_DMA
(QSPI_HandleTypeDef * hqspi, uint8_t * pData)

Function Description

Receives an amount of data in non blocking mode with DMA.

Parameters

hqspi: QSPI handle
pData: pointer to data buffer.

Return values

HAL: status

Notes

This function is used only in Indirect Read Mode
If DMA peripheral access is configured as halfword, the
number of data and the fifo threshold should be aligned on
halfword
If DMA peripheral access is configured as word, the number
of data and the fifo threshold should be aligned on word

HAL_QSPI_AutoPolling
Function Name

HAL_StatusTypeDef HAL_QSPI_AutoPolling
(QSPI_HandleTypeDef * hqspi, QSPI_CommandTypeDef *
cmd, QSPI_AutoPollingTypeDef * cfg, uint32_t Timeout)

Function Description

Configure the QSPI Automatic Polling Mode in blocking mode.

Parameters

hqspi: QSPI handle
DocID025834 Rev 4

609/964

HAL QSPI Generic Driver

UM1725
cmd: structure that contains the command configuration
information.
cfg: structure that contains the polling configuration
information.
Timeout: : Time out duration

Return values

HAL: status

Notes

This function is used only in Automatic Polling Mode

HAL_QSPI_AutoPolling_IT
Function Name

HAL_StatusTypeDef HAL_QSPI_AutoPolling_IT
(QSPI_HandleTypeDef * hqspi, QSPI_CommandTypeDef *
cmd, QSPI_AutoPollingTypeDef * cfg)

Function Description

Configure the QSPI Automatic Polling Mode in non-blocking mode.

Parameters

hqspi: QSPI handle
cmd: structure that contains the command configuration
information.
cfg: structure that contains the polling configuration
information.

Return values

HAL: status

Notes

This function is used only in Automatic Polling Mode

HAL_QSPI_MemoryMapped
Function Name

HAL_StatusTypeDef HAL_QSPI_MemoryMapped
(QSPI_HandleTypeDef * hqspi, QSPI_CommandTypeDef *
cmd, QSPI_MemoryMappedTypeDef * cfg)

Function Description

Configure the Memory Mapped mode.

Parameters

hqspi: QSPI handle
cmd: structure that contains the command configuration
information.
cfg: structure that contains the memory mapped
configuration information.

Return values

HAL: status

Notes

This function is used only in Memory mapped Mode

HAL_QSPI_ErrorCallback

610/964

Function Name

void HAL_QSPI_ErrorCallback (QSPI_HandleTypeDef * hqspi)

Function Description

Transfer Error callbacks.

Parameters

hqspi: QSPI handle

Return values

None

DocID025834 Rev 4

UM1725

HAL QSPI Generic Driver

HAL_QSPI_AbortCpltCallback
Function Name

void HAL_QSPI_AbortCpltCallback (QSPI_HandleTypeDef *
hqspi)

Function Description

Abort completed callback.

Parameters

hqspi: QSPI handle

Return values

None

HAL_QSPI_FifoThresholdCallback
Function Name

void HAL_QSPI_FifoThresholdCallback (QSPI_HandleTypeDef
* hqspi)

Function Description

FIFO Threshold callbacks.

Parameters

hqspi: QSPI handle

Return values

None

HAL_QSPI_CmdCpltCallback
Function Name

void HAL_QSPI_CmdCpltCallback (QSPI_HandleTypeDef *
hqspi)

Function Description

Command completed callback.

Parameters

hqspi: QSPI handle

Return values

None

HAL_QSPI_RxCpltCallback
Function Name

void HAL_QSPI_RxCpltCallback (QSPI_HandleTypeDef *
hqspi)

Function Description

Rx Transfer completed callbacks.

Parameters

hqspi: QSPI handle

Return values

None

HAL_QSPI_TxCpltCallback
Function Name

void HAL_QSPI_TxCpltCallback (QSPI_HandleTypeDef *
hqspi)

Function Description

Tx Transfer completed callbacks.

Parameters

hqspi: QSPI handle

Return values

None

HAL_QSPI_RxHalfCpltCallback
Function Name

void HAL_QSPI_RxHalfCpltCallback (QSPI_HandleTypeDef *
hqspi)

Function Description

Rx Half Transfer completed callbacks.

DocID025834 Rev 4

611/964

HAL QSPI Generic Driver
Parameters
Return values

UM1725
hqspi: QSPI handle
None

HAL_QSPI_TxHalfCpltCallback
Function Name

void HAL_QSPI_TxHalfCpltCallback (QSPI_HandleTypeDef *
hqspi)

Function Description

Tx Half Transfer completed callbacks.

Parameters

hqspi: QSPI handle

Return values

None

HAL_QSPI_StatusMatchCallback
Function Name

void HAL_QSPI_StatusMatchCallback (QSPI_HandleTypeDef *
hqspi)

Function Description

Status Match callbacks.

Parameters

hqspi: QSPI handle

Return values

None

HAL_QSPI_TimeOutCallback
Function Name

void HAL_QSPI_TimeOutCallback (QSPI_HandleTypeDef *
hqspi)

Function Description

Timeout callbacks.

Parameters

hqspi: QSPI handle

Return values

None

HAL_QSPI_GetState
Function Name

HAL_QSPI_StateTypeDef HAL_QSPI_GetState
(QSPI_HandleTypeDef * hqspi)

Function Description

Return the QSPI handle state.

Parameters

hqspi: QSPI handle

Return values

HAL: state

HAL_QSPI_GetError

612/964

Function Name

uint32_t HAL_QSPI_GetError (QSPI_HandleTypeDef * hqspi)

Function Description

Return the QSPI error code.

Parameters

hqspi: QSPI handle

Return values

QSPI: Error Code

DocID025834 Rev 4

UM1725

HAL QSPI Generic Driver

HAL_QSPI_Abort
Function Name

HAL_StatusTypeDef HAL_QSPI_Abort (QSPI_HandleTypeDef *
hqspi)

Function Description

Abort the current transmission.

Parameters

hqspi: QSPI handle

Return values

HAL: status

HAL_QSPI_Abort_IT
Function Name

HAL_StatusTypeDef HAL_QSPI_Abort_IT
(QSPI_HandleTypeDef * hqspi)

Function Description

Abort the current transmission (non-blocking function)

Parameters

hqspi: QSPI handle

Return values

HAL: status

HAL_QSPI_SetTimeout
Function Name

void HAL_QSPI_SetTimeout (QSPI_HandleTypeDef * hqspi,
uint32_t Timeout)

Function Description

Set QSPI timeout.

Parameters

hqspi: QSPI handle.
Timeout: Timeout for the QSPI memory access.

Return values

None

HAL_QSPI_SetFifoThreshold
Function Name

HAL_StatusTypeDef HAL_QSPI_SetFifoThreshold
(QSPI_HandleTypeDef * hqspi, uint32_t Threshold)

Function Description

Set QSPI Fifo threshold.

Parameters

hqspi: QSPI handle.
Threshold: Threshold of the Fifo (value between 1 and 16).

Return values

HAL: status

HAL_QSPI_GetFifoThreshold
Function Name

uint32_t HAL_QSPI_GetFifoThreshold (QSPI_HandleTypeDef *
hqspi)

Function Description

Get QSPI Fifo threshold.

Parameters

hqspi: QSPI handle.

Return values

Fifo: threshold (value between 1 and 16)

DocID025834 Rev 4

613/964

HAL QSPI Generic Driver

UM1725

48.3

QSPI Firmware driver defines

48.3.1

QSPI
QSPI Address Mode
QSPI_ADDRESS_NONE

No address

QSPI_ADDRESS_1_LINE

Address on a single line

QSPI_ADDRESS_2_LINES

Address on two lines

QSPI_ADDRESS_4_LINES

Address on four lines

QSPI Address Size
QSPI_ADDRESS_8_BITS

8-bit address

QSPI_ADDRESS_16_BITS

16-bit address

QSPI_ADDRESS_24_BITS

24-bit address

QSPI_ADDRESS_32_BITS

32-bit address

QSPI Alternate Bytes Mode
QSPI_ALTERNATE_BYTES_NONE

No alternate bytes

QSPI_ALTERNATE_BYTES_1_LINE

Alternate bytes on a single line

QSPI_ALTERNATE_BYTES_2_LINES

Alternate bytes on two lines

QSPI_ALTERNATE_BYTES_4_LINES

Alternate bytes on four lines

QSPI Alternate Bytes Size
QSPI_ALTERNATE_BYTES_8_BITS

8-bit alternate bytes

QSPI_ALTERNATE_BYTES_16_BITS

16-bit alternate bytes

QSPI_ALTERNATE_BYTES_24_BITS

24-bit alternate bytes

QSPI_ALTERNATE_BYTES_32_BITS

32-bit alternate bytes

QSPI Automatic Stop
QSPI_AUTOMATIC_STOP_DISABLE

AutoPolling stops only with abort or QSPI
disabling

QSPI_AUTOMATIC_STOP_ENABLE

AutoPolling stops as soon as there is a match

QSPI Chip Select High Time

614/964

QSPI_CS_HIGH_TIME_1_CYCLE

nCS stay high for at least 1 clock cycle between
commands

QSPI_CS_HIGH_TIME_2_CYCLE

nCS stay high for at least 2 clock cycles between
commands

QSPI_CS_HIGH_TIME_3_CYCLE

nCS stay high for at least 3 clock cycles between
commands

QSPI_CS_HIGH_TIME_4_CYCLE

nCS stay high for at least 4 clock cycles between
commands

QSPI_CS_HIGH_TIME_5_CYCLE

nCS stay high for at least 5 clock cycles between
commands

QSPI_CS_HIGH_TIME_6_CYCLE

nCS stay high for at least 6 clock cycles between

DocID025834 Rev 4

UM1725

HAL QSPI Generic Driver
commands
QSPI_CS_HIGH_TIME_7_CYCLE

nCS stay high for at least 7 clock cycles between
commands

QSPI_CS_HIGH_TIME_8_CYCLE

nCS stay high for at least 8 clock cycles between
commands

QSPI Clock Mode
QSPI_CLOCK_MODE_0

Clk stays low while nCS is released

QSPI_CLOCK_MODE_3

Clk goes high while nCS is released

QSPI Clock Prescaler
IS_QSPI_CLOCK_PRESCALER
QSPI Data Mode
QSPI_DATA_NONE

No data

QSPI_DATA_1_LINE

Data on a single line

QSPI_DATA_2_LINES

Data on two lines

QSPI_DATA_4_LINES

Data on four lines

QSPI Ddr HoldHalfCycle
QSPI_DDR_HHC_ANALOG_DELAY

Delay the data output using analog delay in DDR
mode

QSPI_DDR_HHC_HALF_CLK_DELAY

Delay the data output by 1/2 clock cycle in DDR
mode

QSPI Ddr Mode
QSPI_DDR_MODE_DISABLE

Double data rate mode disabled

QSPI_DDR_MODE_ENABLE

Double data rate mode enabled

QSPI Dual Flash Mode
QSPI_DUALFLASH_ENABLE
QSPI_DUALFLASH_DISABLE
QSPI Dummy Cycles
IS_QSPI_DUMMY_CYCLES
QSPI Error Code
HAL_QSPI_ERROR_NONE

No error

HAL_QSPI_ERROR_TIMEOUT

Timeout error

HAL_QSPI_ERROR_TRANSFER

Transfer error

HAL_QSPI_ERROR_DMA

DMA transfer error

HAL_QSPI_ERROR_INVALID_PARAM

Invalid parameters error

QSPI Exported Macros
__HAL_QSPI_RESET_HANDLE_STATE

Description:
Reset QSPI handle state.
Parameters:

DocID025834 Rev 4

615/964

HAL QSPI Generic Driver

UM1725
__HANDLE__: QSPI handle.
Return value:
None

__HAL_QSPI_ENABLE

Description:
Enable QSPI.
Parameters:
__HANDLE__: specifies the QSPI Handle.
Return value:
None

__HAL_QSPI_DISABLE

Description:
Disable QSPI.
Parameters:
__HANDLE__: specifies the QSPI Handle.
Return value:
None

__HAL_QSPI_ENABLE_IT

Description:
Enables the specified QSPI interrupt.
Parameters:
__HANDLE__: specifies the QSPI Handle.
__INTERRUPT__: specifies the QSPI
interrupt source to enable. This parameter
can be one of the following values:
QSPI_IT_TO: QSPI Time out
interrupt
QSPI_IT_SM: QSPI Status match
interrupt
QSPI_IT_FT: QSPI FIFO threshold
interrupt
QSPI_IT_TC: QSPI Transfer
complete interrupt
QSPI_IT_TE: QSPI Transfer error
interrupt
Return value:
None

__HAL_QSPI_DISABLE_IT

Description:
Disables the specified QSPI interrupt.
Parameters:
__HANDLE__: specifies the QSPI Handle.
__INTERRUPT__: specifies the QSPI
interrupt source to disable. This parameter
can be one of the following values:
QSPI_IT_TO: QSPI Timeout interrupt

616/964

DocID025834 Rev 4

UM1725

HAL QSPI Generic Driver
QSPI_IT_SM: QSPI Status match
interrupt
QSPI_IT_FT: QSPI FIFO threshold
interrupt
QSPI_IT_TC: QSPI Transfer
complete interrupt
QSPI_IT_TE: QSPI Transfer error
interrupt
Return value:
None
__HAL_QSPI_GET_IT_SOURCE

Description:
Checks whether the specified QSPI
interrupt source is enabled.
Parameters:
__HANDLE__: specifies the QSPI Handle.
__INTERRUPT__: specifies the QSPI
interrupt source to check. This parameter
can be one of the following values:
QSPI_IT_TO: QSPI Time out
interrupt
QSPI_IT_SM: QSPI Status match
interrupt
QSPI_IT_FT: QSPI FIFO threshold
interrupt
QSPI_IT_TC: QSPI Transfer
complete interrupt
QSPI_IT_TE: QSPI Transfer error
interrupt
Return value:
The: new state of __INTERRUPT__
(TRUE or FALSE).

__HAL_QSPI_GET_FLAG

Description:
Get the selected QSPI's flag status.
Parameters:
__HANDLE__: specifies the QSPI Handle.
__FLAG__: specifies the QSPI flag to
check. This parameter can be one of the
following values:
QSPI_FLAG_BUSY: QSPI Busy flag
QSPI_FLAG_TO: QSPI Time out flag
QSPI_FLAG_SM: QSPI Status match
flag
QSPI_FLAG_FT: QSPI FIFO
threshold flag
QSPI_FLAG_TC: QSPI Transfer
complete flag
QSPI_FLAG_TE: QSPI Transfer error

DocID025834 Rev 4

617/964

HAL QSPI Generic Driver

UM1725
flag
Return value:
None

__HAL_QSPI_CLEAR_FLAG

Description:
Clears the specified QSPI's flag status.
Parameters:
__HANDLE__: specifies the QSPI Handle.
__FLAG__: specifies the QSPI clear
register flag that needs to be set This
parameter can be one of the following
values:
QSPI_FLAG_TO: QSPI Time out flag
QSPI_FLAG_SM: QSPI Status match
flag
QSPI_FLAG_TC: QSPI Transfer
complete flag
QSPI_FLAG_TE: QSPI Transfer error
flag
Return value:
None

QSPI Fifo Threshold
IS_QSPI_FIFO_THRESHOLD
QSPI Flags
QSPI_FLAG_BUSY

Busy flag: operation is ongoing

QSPI_FLAG_TO

Timeout flag: timeout occurs in memory-mapped mode

QSPI_FLAG_SM

Status match flag: received data matches in autopolling mode

QSPI_FLAG_FT

Fifo threshold flag: Fifo threshold reached or data left after read
from memory is complete

QSPI_FLAG_TC

Transfer complete flag: programmed number of data have been
transferred or the transfer has been aborted

QSPI_FLAG_TE

Transfer error flag: invalid address is being accessed

QSPI Flash Size
IS_QSPI_FLASH_SIZE
QSPI Flash Select
QSPI_FLASH_ID_1
QSPI_FLASH_ID_2
QSPI Instruction
IS_QSPI_INSTRUCTION
QSPI Instruction Mode
QSPI_INSTRUCTION_NONE

618/964

No instruction

DocID025834 Rev 4

UM1725

HAL QSPI Generic Driver
QSPI_INSTRUCTION_1_LINE

Instruction on a single line

QSPI_INSTRUCTION_2_LINES

Instruction on two lines

QSPI_INSTRUCTION_4_LINES

Instruction on four lines

QSPI Interrupts
QSPI_IT_TO

Interrupt on the timeout flag

QSPI_IT_SM

Interrupt on the status match flag

QSPI_IT_FT

Interrupt on the fifo threshold flag

QSPI_IT_TC

Interrupt on the transfer complete flag

QSPI_IT_TE

Interrupt on the transfer error flag

QSPI Interval
IS_QSPI_INTERVAL
QSPI Match Mode
QSPI_MATCH_MODE_AND

AND match mode between unmasked bits

QSPI_MATCH_MODE_OR

OR match mode between unmasked bits

QSPI Sample Shifting
QSPI_SAMPLE_SHIFTING_NONE

No clock cycle shift to sample data

QSPI_SAMPLE_SHIFTING_HALFCYCLE

1/2 clock cycle shift to sample data

QSPI SIOO Mode
QSPI_SIOO_INST_EVERY_CMD

Send instruction on every transaction

QSPI_SIOO_INST_ONLY_FIRST_CMD

Send instruction only for the first command

QSPI Status Bytes Size
IS_QSPI_STATUS_BYTES_SIZE
QSPI TimeOut Activation
QSPI_TIMEOUT_COUNTER_DISABLE

Timeout counter disabled, nCS remains active

QSPI_TIMEOUT_COUNTER_ENABLE

Timeout counter enabled, nCS released when
timeout expires

QSPI TimeOut Period
IS_QSPI_TIMEOUT_PERIOD
QSPI Timeout definition
HAL_QPSI_TIMEOUT_DEFAULT_VALUE

DocID025834 Rev 4

619/964

HAL RCC Generic Driver

UM1725

49

HAL RCC Generic Driver

49.1

RCC Firmware driver registers structures

49.1.1

RCC_OscInitTypeDef
Data Fields
uint32_t OscillatorType
uint32_t HSEState
uint32_t LSEState
uint32_t HSIState
uint32_t HSICalibrationValue
uint32_t LSIState
RCC_PLLInitTypeDef PLL

Field Documentation
uint32_t RCC_OscInitTypeDef::OscillatorType
The oscillators to be configured. This parameter can be a value of
RCC_Oscillator_Type
uint32_t RCC_OscInitTypeDef::HSEState
The new state of the HSE. This parameter can be a value of RCC_HSE_Config
uint32_t RCC_OscInitTypeDef::LSEState
The new state of the LSE. This parameter can be a value of RCC_LSE_Config
uint32_t RCC_OscInitTypeDef::HSIState
The new state of the HSI. This parameter can be a value of RCC_HSI_Config
uint32_t RCC_OscInitTypeDef::HSICalibrationValue
The HSI calibration trimming value (default is RCC_HSICALIBRATION_DEFAULT).
This parameter must be a number between Min_Data = 0x00 and Max_Data = 0x1F
uint32_t RCC_OscInitTypeDef::LSIState
The new state of the LSI. This parameter can be a value of RCC_LSI_Config
RCC_PLLInitTypeDef RCC_OscInitTypeDef::PLL
PLL structure parameters

49.1.2

RCC_ClkInitTypeDef
Data Fields
uint32_t ClockType
uint32_t SYSCLKSource
uint32_t AHBCLKDivider
uint32_t APB1CLKDivider
uint32_t APB2CLKDivider

Field Documentation

620/964

DocID025834 Rev 4

UM1725

HAL RCC Generic Driver
uint32_t RCC_ClkInitTypeDef::ClockType
The clock to be configured. This parameter can be a value of
RCC_System_Clock_Type
uint32_t RCC_ClkInitTypeDef::SYSCLKSource
The clock source (SYSCLKS) used as system clock. This parameter can be a value
of RCC_System_Clock_Source
uint32_t RCC_ClkInitTypeDef::AHBCLKDivider
The AHB clock (HCLK) divider. This clock is derived from the system clock
(SYSCLK). This parameter can be a value of RCC_AHB_Clock_Source
uint32_t RCC_ClkInitTypeDef::APB1CLKDivider
The APB1 clock (PCLK1) divider. This clock is derived from the AHB clock (HCLK).
This parameter can be a value of RCC_APB1_APB2_Clock_Source
uint32_t RCC_ClkInitTypeDef::APB2CLKDivider
The APB2 clock (PCLK2) divider. This clock is derived from the AHB clock (HCLK).
This parameter can be a value of RCC_APB1_APB2_Clock_Source

49.2

RCC Firmware driver API description

49.2.1

RCC specific features
After reset the device is running from Internal High Speed oscillator (HSI 16MHz) with
Flash 0 wait state, Flash prefetch buffer, D-Cache and I-Cache are disabled, and all
peripherals are off except internal SRAM, Flash and JTAG.
There is no prescaler on High speed (AHB) and Low speed (APB) busses; all
peripherals mapped on these busses are running at HSI speed.
The clock for all peripherals is switched off, except the SRAM and FLASH.
All GPIOs are in input floating state, except the JTAG pins which are assigned to be
used for debug purpose.
Once the device started from reset, the user application has to:
Configure the clock source to be used to drive the System clock (if the application
needs higher frequency/performance)
Configure the System clock frequency and Flash settings
Configure the AHB and APB busses prescalers
Enable the clock for the peripheral(s) to be used
Configure the clock source(s) for peripherals which clocks are not derived from the
System clock (I2S, RTC, ADC, USB OTG FS/SDIO/RNG)

49.2.2

RCC Limitations
A delay between an RCC peripheral clock enable and the effective peripheral enabling
should be taken into account in order to manage the peripheral read/write from/to registers.
This delay depends on the peripheral mapping.
If peripheral is mapped on AHB: the delay is 2 AHB clock cycle after the clock enable
bit is set on the hardware register
If peripheral is mapped on APB: the delay is 2 APB clock cycle after the clock enable
bit is set on the hardware register
Implemented Workaround:
For AHB & APB peripherals, a dummy read to the peripheral register has been
inserted in each __HAL_RCC_PPP_CLK_ENABLE() macro.

DocID025834 Rev 4

621/964

HAL RCC Generic Driver

49.2.3

UM1725

Initialization and de-initialization functions
This section provides functions allowing to configure the internal/external oscillators (HSE,
HSI, LSE, LSI, PLL, CSS and MCO) and the System busses clocks (SYSCLK, AHB, APB1
and APB2).
Internal/external clock and PLL configuration
1.
2.
3.
4.
5.

6.

7.
8.

HSI (high-speed internal), 16 MHz factory-trimmed RC used directly or through the
PLL as System clock source.
LSI (low-speed internal), 32 KHz low consumption RC used as IWDG and/or RTC
clock source.
HSE (high-speed external), 4 to 26 MHz crystal oscillator used directly or through the
PLL as System clock source. Can be used also as RTC clock source.
LSE (low-speed external), 32 KHz oscillator used as RTC clock source.
PLL (clocked by HSI or HSE), featuring two different output clocks:
The first output is used to generate the high speed system clock (up to 168 MHz)
The second output is used to generate the clock for the USB OTG FS (48 MHz),
the random analog generator (<=48 MHz) and the SDIO (<= 48 MHz).
CSS (Clock security system), once enable using the macro
__HAL_RCC_CSS_ENABLE() and if a HSE clock failure occurs(HSE used directly or
through PLL as System clock source), the System clocks automatically switched to
HSI and an interrupt is generated if enabled. The interrupt is linked to the Cortex-M4
NMI (Non-Maskable Interrupt) exception vector.
MCO1 (microcontroller clock output), used to output HSI, LSE, HSE or PLL clock
(through a configurable prescaler) on PA8 pin.
MCO2 (microcontroller clock output), used to output HSE, PLL, SYSCLK or PLLI2S
clock (through a configurable prescaler) on PC9 pin.

System, AHB and APB busses clocks configuration
1.

2.

3.

4.

5.

622/964

Several clock sources can be used to drive the System clock (SYSCLK): HSI, HSE
and PLL. The AHB clock (HCLK) is derived from System clock through configurable
prescaler and used to clock the CPU, memory and peripherals mapped on AHB bus
(DMA, GPIO...). APB1 (PCLK1) and APB2 (PCLK2) clocks are derived from AHB
clock through configurable prescalers and used to clock the peripherals mapped on
these busses. You can use "HAL_RCC_GetSysClockFreq()" function to retrieve the
frequencies of these clocks.
For the STM32F405xx/07xx and STM32F415xx/17xx devices, the maximum
frequency of the SYSCLK and HCLK is 168 MHz, PCLK2 84 MHz and PCLK1 42
MHz. Depending on the device voltage range, the maximum frequency should be
adapted accordingly (refer to the product datasheets for more details).
For the STM32F42xxx, STM32F43xxx, STM32F446xx, STM32F469xx and
STM32F479xx devices, the maximum frequency of the SYSCLK and HCLK is 180
MHz, PCLK2 90 MHz and PCLK1 45 MHz. Depending on the device voltage range,
the maximum frequency should be adapted accordingly (refer to the product
datasheets for more details).
For the STM32F401xx, the maximum frequency of the SYSCLK and HCLK is 84
MHz, PCLK2 84 MHz and PCLK1 42 MHz. Depending on the device voltage range,
the maximum frequency should be adapted accordingly (refer to the product
datasheets for more details).
For the STM32F41xxx, the maximum frequency of the SYSCLK and HCLK is 100
MHz, PCLK2 100 MHz and PCLK1 50 MHz. Depending on the device voltage range,
the maximum frequency should be adapted accordingly (refer to the product
datasheets for more details).

DocID025834 Rev 4

UM1725

HAL RCC Generic Driver
This section contains the following APIs:
HAL_RCC_DeInit()
HAL_RCC_OscConfig()
HAL_RCC_ClockConfig()

49.2.4

Peripheral Control functions
This subsection provides a set of functions allowing to control the RCC Clocks
frequencies.
This section contains the following APIs:
HAL_RCC_MCOConfig()
HAL_RCC_EnableCSS()
HAL_RCC_DisableCSS()
HAL_RCC_GetSysClockFreq()
HAL_RCC_GetHCLKFreq()
HAL_RCC_GetPCLK1Freq()
HAL_RCC_GetPCLK2Freq()
HAL_RCC_GetOscConfig()
HAL_RCC_GetClockConfig()
HAL_RCC_NMI_IRQHandler()
HAL_RCC_CSSCallback()

49.2.5

Detailed description of functions
HAL_RCC_DeInit
Function Name

void HAL_RCC_DeInit (void )

Function Description

Resets the RCC clock configuration to the default reset state.

Return values

None

Notes

The default reset state of the clock configuration is given
below: HSI ON and used as system clock sourceHSE and
PLL OFFAHB, APB1 and APB2 prescaler set to 1.CSS,
MCO1 and MCO2 OFFAll interrupts disabled
This function doesn't modify the configuration of the
Peripheral clocksLSI, LSE and RTC clocks

HAL_RCC_OscConfig
Function Name

HAL_StatusTypeDef HAL_RCC_OscConfig
(RCC_OscInitTypeDef * RCC_OscInitStruct)

Function Description

Initializes the RCC Oscillators according to the specified
parameters in the RCC_OscInitTypeDef.

Parameters

RCC_OscInitStruct: pointer to an RCC_OscInitTypeDef
structure that contains the configuration information for the
RCC Oscillators.

Return values

HAL: status

Notes

The PLL is not disabled when used as system clock.
Transitions LSE Bypass to LSE On and LSE On to LSE
Bypass are not supported by this API. User should request a
transition to LSE Off first and then LSE On or LSE Bypass.
DocID025834 Rev 4

623/964

HAL RCC Generic Driver

UM1725
Transition HSE Bypass to HSE On and HSE On to HSE
Bypass are not supported by this API. User should request a
transition to HSE Off first and then HSE On or HSE Bypass.

HAL_RCC_ClockConfig
Function Name

HAL_StatusTypeDef HAL_RCC_ClockConfig
(RCC_ClkInitTypeDef * RCC_ClkInitStruct, uint32_t FLatency)

Function Description

Initializes the CPU, AHB and APB busses clocks according to the
specified parameters in the RCC_ClkInitStruct.

Parameters

RCC_ClkInitStruct: pointer to an RCC_OscInitTypeDef
structure that contains the configuration information for the
RCC peripheral.
FLatency: FLASH Latency, this parameter depend on device
selected

Return values

None

Notes

The SystemCoreClock CMSIS variable is used to store
System Clock Frequency and updated by
HAL_RCC_GetHCLKFreq() function called within this function
The HSI is used (enabled by hardware) as system clock
source after startup from Reset, wake-up from STOP and
STANDBY mode, or in case of failure of the HSE used
directly or indirectly as system clock (if the Clock Security
System CSS is enabled).
A switch from one clock source to another occurs only if the
target clock source is ready (clock stable after startup delay or
PLL locked). If a clock source which is not yet ready is
selected, the switch will occur when the clock source will be
ready.
Depending on the device voltage range, the software has to
set correctly HPRE[3:0] bits to ensure that HCLK not exceed
the maximum allowed frequency (for more details refer to
section above "Initialization/de-initialization functions")

HAL_RCC_MCOConfig
Function Name

void HAL_RCC_MCOConfig (uint32_t RCC_MCOx, uint32_t
RCC_MCOSource, uint32_t RCC_MCODiv)

Function Description

Selects the clock source to output on MCO1 pin(PA8) or on MCO2
pin(PC9).

Parameters

624/964

RCC_MCOx: specifies the output direction for the clock
source. This parameter can be one of the following values:
RCC_MCO1: Clock source to output on MCO1 pin(PA8).
RCC_MCO2: Clock source to output on MCO2 pin(PC9).
RCC_MCOSource: specifies the clock source to output. This
parameter can be one of the following values:
RCC_MCO1SOURCE_HSI: HSI clock selected as
MCO1 source
RCC_MCO1SOURCE_LSE: LSE clock selected as
MCO1 source
RCC_MCO1SOURCE_HSE: HSE clock selected as
DocID025834 Rev 4

UM1725

HAL RCC Generic Driver
MCO1 source
RCC_MCO1SOURCE_PLLCLK: main PLL clock
selected as MCO1 source
RCC_MCO2SOURCE_SYSCLK: System clock
(SYSCLK) selected as MCO2 source
RCC_MCO2SOURCE_PLLI2SCLK: PLLI2S clock
selected as MCO2 source, available for all STM32F4
devices except STM32F410xx
RCC_MCO2SOURCE_I2SCLK: I2SCLK clock selected
as MCO2 source, available only for STM32F410Rx
devices
RCC_MCO2SOURCE_HSE: HSE clock selected as
MCO2 source
RCC_MCO2SOURCE_PLLCLK: main PLL clock
selected as MCO2 source
RCC_MCODiv: specifies the MCOx prescaler. This
parameter can be one of the following values:
RCC_MCODIV_1: no division applied to MCOx clock
RCC_MCODIV_2: division by 2 applied to MCOx clock
RCC_MCODIV_3: division by 3 applied to MCOx clock
RCC_MCODIV_4: division by 4 applied to MCOx clock
RCC_MCODIV_5: division by 5 applied to MCOx clock
Return values

None

Notes

PA8/PC9 should be configured in alternate function mode.
For STM32F410Rx devices to output I2SCLK clock on MCO2
you should have at last one of the SPI clocks enabled (SPI1,
SPI2 or SPI5).

HAL_RCC_EnableCSS
Function Name

void HAL_RCC_EnableCSS (void )

Function Description

Enables the Clock Security System.

Return values

None

Notes

If a failure is detected on the HSE oscillator clock, this
oscillator is automatically disabled and an interrupt is
generated to inform the software about the failure (Clock
Security System Interrupt, CSSI), allowing the MCU to
perform rescue operations. The CSSI is linked to the CortexM4 NMI (Non-Maskable Interrupt) exception vector.

HAL_RCC_DisableCSS
Function Name

void HAL_RCC_DisableCSS (void )

Function Description

Disables the Clock Security System.

Return values

None

DocID025834 Rev 4

625/964

HAL RCC Generic Driver

UM1725

HAL_RCC_GetSysClockFreq
Function Name

uint32_t HAL_RCC_GetSysClockFreq (void )

Function Description

Returns the SYSCLK frequency.

Return values

SYSCLK: frequency

Notes

The system frequency computed by this function is not the
real frequency in the chip. It is calculated based on the
predefined constant and the selected clock source:
If SYSCLK source is HSI, function returns values based on
HSI_VALUE(*)
If SYSCLK source is HSE, function returns values based on
HSE_VALUE(**)
If SYSCLK source is PLL, function returns values based on
HSE_VALUE(**) or HSI_VALUE(*) multiplied/divided by the
PLL factors.
(*) HSI_VALUE is a constant defined in stm32f4xx_hal_conf.h
file (default value 16 MHz) but the real value may vary
depending on the variations in voltage and temperature.
(**) HSE_VALUE is a constant defined in
stm32f4xx_hal_conf.h file (default value 25 MHz), user has to
ensure that HSE_VALUE is same as the real frequency of the
crystal used. Otherwise, this function may have wrong result.
The result of this function could be not correct when using
fractional value for HSE crystal.
This function can be used by the user application to compute
the baudrate for the communication peripherals or configure
other parameters.
Each time SYSCLK changes, this function must be called to
update the right SYSCLK value. Otherwise, any configuration
based on this function will be incorrect.

HAL_RCC_GetHCLKFreq
Function Name

uint32_t HAL_RCC_GetHCLKFreq (void )

Function Description

Returns the HCLK frequency.

Return values

HCLK: frequency

Notes

Each time HCLK changes, this function must be called to
update the right HCLK value. Otherwise, any configuration
based on this function will be incorrect.
The SystemCoreClock CMSIS variable is used to store
System Clock Frequency and updated within this function

HAL_RCC_GetPCLK1Freq

626/964

Function Name

uint32_t HAL_RCC_GetPCLK1Freq (void )

Function Description

Returns the PCLK1 frequency.

Return values

PCLK1: frequency

Notes

Each time PCLK1 changes, this function must be called to
update the right PCLK1 value. Otherwise, any configuration

DocID025834 Rev 4

UM1725

HAL RCC Generic Driver
based on this function will be incorrect.

HAL_RCC_GetPCLK2Freq
Function Name

uint32_t HAL_RCC_GetPCLK2Freq (void )

Function Description

Returns the PCLK2 frequency.

Return values

PCLK2: frequency

Notes

Each time PCLK2 changes, this function must be called to
update the right PCLK2 value. Otherwise, any configuration
based on this function will be incorrect.

HAL_RCC_GetOscConfig
Function Name

void HAL_RCC_GetOscConfig (RCC_OscInitTypeDef *
RCC_OscInitStruct)

Function Description

Configures the RCC_OscInitStruct according to the internal RCC
configuration registers.

Parameters

RCC_OscInitStruct: pointer to an RCC_OscInitTypeDef
structure that will be configured.

Return values

None

HAL_RCC_GetClockConfig
Function Name

void HAL_RCC_GetClockConfig (RCC_ClkInitTypeDef *
RCC_ClkInitStruct, uint32_t * pFLatency)

Function Description

Configures the RCC_ClkInitStruct according to the internal RCC
configuration registers.

Parameters

RCC_ClkInitStruct: pointer to an RCC_ClkInitTypeDef
structure that will be configured.
pFLatency: Pointer on the Flash Latency.

Return values

None

HAL_RCC_NMI_IRQHandler
Function Name

void HAL_RCC_NMI_IRQHandler (void )

Function Description

This function handles the RCC CSS interrupt request.

Return values

None

Notes

This API should be called under the NMI_Handler().

HAL_RCC_CSSCallback
Function Name

void HAL_RCC_CSSCallback (void )

Function Description

RCC Clock Security System interrupt callback.

Return values

None

DocID025834 Rev 4

627/964

HAL RCC Generic Driver

UM1725

49.3

RCC Firmware driver defines

49.3.1

RCC
AHB1 Peripheral Clock Enable Disable
__HAL_RCC_GPIOA_CLK_ENABLE
__HAL_RCC_GPIOB_CLK_ENABLE
__HAL_RCC_GPIOC_CLK_ENABLE
__HAL_RCC_GPIOH_CLK_ENABLE
__HAL_RCC_DMA1_CLK_ENABLE
__HAL_RCC_DMA2_CLK_ENABLE
__HAL_RCC_GPIOA_CLK_DISABLE
__HAL_RCC_GPIOB_CLK_DISABLE
__HAL_RCC_GPIOC_CLK_DISABLE
__HAL_RCC_GPIOH_CLK_DISABLE
__HAL_RCC_DMA1_CLK_DISABLE
__HAL_RCC_DMA2_CLK_DISABLE
AHB1 Force Release Reset
__HAL_RCC_AHB1_FORCE_RESET
__HAL_RCC_GPIOA_FORCE_RESET
__HAL_RCC_GPIOB_FORCE_RESET
__HAL_RCC_GPIOC_FORCE_RESET
__HAL_RCC_GPIOH_FORCE_RESET
__HAL_RCC_DMA1_FORCE_RESET
__HAL_RCC_DMA2_FORCE_RESET
__HAL_RCC_AHB1_RELEASE_RESET
__HAL_RCC_GPIOA_RELEASE_RESET
__HAL_RCC_GPIOB_RELEASE_RESET
__HAL_RCC_GPIOC_RELEASE_RESET
__HAL_RCC_GPIOH_RELEASE_RESET
__HAL_RCC_DMA1_RELEASE_RESET
__HAL_RCC_DMA2_RELEASE_RESET
AHB1 Peripheral Low Power Enable Disable
__HAL_RCC_GPIOA_CLK_SLEEP_ENABLE
__HAL_RCC_GPIOB_CLK_SLEEP_ENABLE
__HAL_RCC_GPIOC_CLK_SLEEP_ENABLE
__HAL_RCC_GPIOH_CLK_SLEEP_ENABLE
__HAL_RCC_DMA1_CLK_SLEEP_ENABLE

628/964

DocID025834 Rev 4

UM1725

HAL RCC Generic Driver
__HAL_RCC_DMA2_CLK_SLEEP_ENABLE
__HAL_RCC_GPIOA_CLK_SLEEP_DISABLE
__HAL_RCC_GPIOB_CLK_SLEEP_DISABLE
__HAL_RCC_GPIOC_CLK_SLEEP_DISABLE
__HAL_RCC_GPIOH_CLK_SLEEP_DISABLE
__HAL_RCC_DMA1_CLK_SLEEP_DISABLE
__HAL_RCC_DMA2_CLK_SLEEP_DISABLE
AHB1 Peripheral Clock Enable Disable Status
__HAL_RCC_GPIOA_IS_CLK_ENABLED
__HAL_RCC_GPIOB_IS_CLK_ENABLED
__HAL_RCC_GPIOC_IS_CLK_ENABLED
__HAL_RCC_GPIOH_IS_CLK_ENABLED
__HAL_RCC_DMA1_IS_CLK_ENABLED
__HAL_RCC_DMA2_IS_CLK_ENABLED
__HAL_RCC_GPIOA_IS_CLK_DISABLED
__HAL_RCC_GPIOB_IS_CLK_DISABLED
__HAL_RCC_GPIOC_IS_CLK_DISABLED
__HAL_RCC_GPIOH_IS_CLK_DISABLED
__HAL_RCC_DMA1_IS_CLK_DISABLED
__HAL_RCC_DMA2_IS_CLK_DISABLED
AHB Clock Source
RCC_SYSCLK_DIV1
RCC_SYSCLK_DIV2
RCC_SYSCLK_DIV4
RCC_SYSCLK_DIV8
RCC_SYSCLK_DIV16
RCC_SYSCLK_DIV64
RCC_SYSCLK_DIV128
RCC_SYSCLK_DIV256
RCC_SYSCLK_DIV512
APB1/APB2 Clock Source
RCC_HCLK_DIV1
RCC_HCLK_DIV2
RCC_HCLK_DIV4
RCC_HCLK_DIV8
RCC_HCLK_DIV16

DocID025834 Rev 4

629/964

HAL RCC Generic Driver
APB1 Peripheral Clock Enable Disable
__HAL_RCC_TIM5_CLK_ENABLE
__HAL_RCC_WWDG_CLK_ENABLE
__HAL_RCC_SPI2_CLK_ENABLE
__HAL_RCC_USART2_CLK_ENABLE
__HAL_RCC_I2C1_CLK_ENABLE
__HAL_RCC_I2C2_CLK_ENABLE
__HAL_RCC_PWR_CLK_ENABLE
__HAL_RCC_TIM5_CLK_DISABLE
__HAL_RCC_WWDG_CLK_DISABLE
__HAL_RCC_SPI2_CLK_DISABLE
__HAL_RCC_USART2_CLK_DISABLE
__HAL_RCC_I2C1_CLK_DISABLE
__HAL_RCC_I2C2_CLK_DISABLE
__HAL_RCC_PWR_CLK_DISABLE
APB1 Force Release Reset
__HAL_RCC_APB1_FORCE_RESET
__HAL_RCC_TIM5_FORCE_RESET
__HAL_RCC_WWDG_FORCE_RESET
__HAL_RCC_SPI2_FORCE_RESET
__HAL_RCC_USART2_FORCE_RESET
__HAL_RCC_I2C1_FORCE_RESET
__HAL_RCC_I2C2_FORCE_RESET
__HAL_RCC_PWR_FORCE_RESET
__HAL_RCC_APB1_RELEASE_RESET
__HAL_RCC_TIM5_RELEASE_RESET
__HAL_RCC_WWDG_RELEASE_RESET
__HAL_RCC_SPI2_RELEASE_RESET
__HAL_RCC_USART2_RELEASE_RESET
__HAL_RCC_I2C1_RELEASE_RESET
__HAL_RCC_I2C2_RELEASE_RESET
__HAL_RCC_PWR_RELEASE_RESET
APB1 Peripheral Low Power Enable Disable
__HAL_RCC_TIM5_CLK_SLEEP_ENABLE
__HAL_RCC_WWDG_CLK_SLEEP_ENABLE
__HAL_RCC_SPI2_CLK_SLEEP_ENABLE

630/964

DocID025834 Rev 4

UM1725

UM1725

HAL RCC Generic Driver
__HAL_RCC_USART2_CLK_SLEEP_ENABLE
__HAL_RCC_I2C1_CLK_SLEEP_ENABLE
__HAL_RCC_I2C2_CLK_SLEEP_ENABLE
__HAL_RCC_PWR_CLK_SLEEP_ENABLE
__HAL_RCC_TIM5_CLK_SLEEP_DISABLE
__HAL_RCC_WWDG_CLK_SLEEP_DISABLE
__HAL_RCC_SPI2_CLK_SLEEP_DISABLE
__HAL_RCC_USART2_CLK_SLEEP_DISABLE
__HAL_RCC_I2C1_CLK_SLEEP_DISABLE
__HAL_RCC_I2C2_CLK_SLEEP_DISABLE
__HAL_RCC_PWR_CLK_SLEEP_DISABLE
APB1 Peripheral Clock Enable Disable Status
__HAL_RCC_TIM5_IS_CLK_ENABLED
__HAL_RCC_WWDG_IS_CLK_ENABLED
__HAL_RCC_SPI2_IS_CLK_ENABLED
__HAL_RCC_USART2_IS_CLK_ENABLED
__HAL_RCC_I2C1_IS_CLK_ENABLED
__HAL_RCC_I2C2_IS_CLK_ENABLED
__HAL_RCC_PWR_IS_CLK_ENABLED
__HAL_RCC_TIM5_IS_CLK_DISABLED
__HAL_RCC_WWDG_IS_CLK_DISABLED
__HAL_RCC_SPI2_IS_CLK_DISABLED
__HAL_RCC_USART2_IS_CLK_DISABLED
__HAL_RCC_I2C1_IS_CLK_DISABLED
__HAL_RCC_I2C2_IS_CLK_DISABLED
__HAL_RCC_PWR_IS_CLK_DISABLED
APB2 Peripheral Clock Enable Disable
__HAL_RCC_TIM1_CLK_ENABLE
__HAL_RCC_USART1_CLK_ENABLE
__HAL_RCC_USART6_CLK_ENABLE
__HAL_RCC_ADC1_CLK_ENABLE
__HAL_RCC_SPI1_CLK_ENABLE
__HAL_RCC_SYSCFG_CLK_ENABLE
__HAL_RCC_TIM9_CLK_ENABLE
__HAL_RCC_TIM11_CLK_ENABLE
__HAL_RCC_TIM1_CLK_DISABLE

DocID025834 Rev 4

631/964

HAL RCC Generic Driver
__HAL_RCC_USART1_CLK_DISABLE
__HAL_RCC_USART6_CLK_DISABLE
__HAL_RCC_ADC1_CLK_DISABLE
__HAL_RCC_SPI1_CLK_DISABLE
__HAL_RCC_SYSCFG_CLK_DISABLE
__HAL_RCC_TIM9_CLK_DISABLE
__HAL_RCC_TIM11_CLK_DISABLE
APB2 Force Release Reset
__HAL_RCC_APB2_FORCE_RESET
__HAL_RCC_TIM1_FORCE_RESET
__HAL_RCC_USART1_FORCE_RESET
__HAL_RCC_USART6_FORCE_RESET
__HAL_RCC_ADC_FORCE_RESET
__HAL_RCC_SPI1_FORCE_RESET
__HAL_RCC_SYSCFG_FORCE_RESET
__HAL_RCC_TIM9_FORCE_RESET
__HAL_RCC_TIM11_FORCE_RESET
__HAL_RCC_APB2_RELEASE_RESET
__HAL_RCC_TIM1_RELEASE_RESET
__HAL_RCC_USART1_RELEASE_RESET
__HAL_RCC_USART6_RELEASE_RESET
__HAL_RCC_ADC_RELEASE_RESET
__HAL_RCC_SPI1_RELEASE_RESET
__HAL_RCC_SYSCFG_RELEASE_RESET
__HAL_RCC_TIM9_RELEASE_RESET
__HAL_RCC_TIM11_RELEASE_RESET
APB2 Peripheral Low Power Enable Disable
__HAL_RCC_TIM1_CLK_SLEEP_ENABLE
__HAL_RCC_USART1_CLK_SLEEP_ENABLE
__HAL_RCC_USART6_CLK_SLEEP_ENABLE
__HAL_RCC_ADC1_CLK_SLEEP_ENABLE
__HAL_RCC_SPI1_CLK_SLEEP_ENABLE
__HAL_RCC_SYSCFG_CLK_SLEEP_ENABLE
__HAL_RCC_TIM9_CLK_SLEEP_ENABLE
__HAL_RCC_TIM11_CLK_SLEEP_ENABLE
__HAL_RCC_TIM1_CLK_SLEEP_DISABLE

632/964

DocID025834 Rev 4

UM1725

UM1725

HAL RCC Generic Driver
__HAL_RCC_USART1_CLK_SLEEP_DISABLE
__HAL_RCC_USART6_CLK_SLEEP_DISABLE
__HAL_RCC_ADC1_CLK_SLEEP_DISABLE
__HAL_RCC_SPI1_CLK_SLEEP_DISABLE
__HAL_RCC_SYSCFG_CLK_SLEEP_DISABLE
__HAL_RCC_TIM9_CLK_SLEEP_DISABLE
__HAL_RCC_TIM11_CLK_SLEEP_DISABLE
APB2 Peripheral Clock Enable Disable Status
__HAL_RCC_TIM1_IS_CLK_ENABLED
__HAL_RCC_USART1_IS_CLK_ENABLED
__HAL_RCC_USART6_IS_CLK_ENABLED
__HAL_RCC_ADC1_IS_CLK_ENABLED
__HAL_RCC_SPI1_IS_CLK_ENABLED
__HAL_RCC_SYSCFG_IS_CLK_ENABLED
__HAL_RCC_TIM9_IS_CLK_ENABLED
__HAL_RCC_TIM11_IS_CLK_ENABLED
__HAL_RCC_TIM1_IS_CLK_DISABLED
__HAL_RCC_USART1_IS_CLK_DISABLED
__HAL_RCC_USART6_IS_CLK_DISABLED
__HAL_RCC_ADC1_IS_CLK_DISABLED
__HAL_RCC_SPI1_IS_CLK_DISABLED
__HAL_RCC_SYSCFG_IS_CLK_DISABLED
__HAL_RCC_TIM9_IS_CLK_DISABLED
__HAL_RCC_TIM11_IS_CLK_DISABLED
RCC BitAddress AliasRegion
RCC_OFFSET
RCC_CR_OFFSET
RCC_HSION_BIT_NUMBER
RCC_CR_HSION_BB
RCC_CSSON_BIT_NUMBER
RCC_CR_CSSON_BB
RCC_PLLON_BIT_NUMBER
RCC_CR_PLLON_BB
RCC_BDCR_OFFSET
RCC_RTCEN_BIT_NUMBER
RCC_BDCR_RTCEN_BB

DocID025834 Rev 4

633/964

HAL RCC Generic Driver
RCC_BDRST_BIT_NUMBER

UM1725

RCC_BDCR_BDRST_BB
RCC_CSR_OFFSET
RCC_LSION_BIT_NUMBER
RCC_CSR_LSION_BB
RCC_CR_BYTE2_ADDRESS
RCC_CIR_BYTE1_ADDRESS
RCC_CIR_BYTE2_ADDRESS
RCC_BDCR_BYTE0_ADDRESS
RCC_DBP_TIMEOUT_VALUE
RCC_LSE_TIMEOUT_VALUE
HSE_TIMEOUT_VALUE
HSI_TIMEOUT_VALUE
LSI_TIMEOUT_VALUE
Flags
RCC_FLAG_HSIRDY
RCC_FLAG_HSERDY
RCC_FLAG_PLLRDY
RCC_FLAG_PLLI2SRDY
RCC_FLAG_LSERDY
RCC_FLAG_LSIRDY
RCC_FLAG_BORRST
RCC_FLAG_PINRST
RCC_FLAG_PORRST
RCC_FLAG_SFTRST
RCC_FLAG_IWDGRST
RCC_FLAG_WWDGRST
RCC_FLAG_LPWRRST
Flags Interrupts Management
__HAL_RCC_ENABLE_IT

Description:
Enable RCC interrupt (Perform Byte access
to RCC_CIR[14:8] bits to enable the
selected interrupts).
Parameters:
__INTERRUPT__: specifies the RCC
interrupt sources to be enabled. This
parameter can be any combination of the
following values:
RCC_IT_LSIRDY: LSI ready interrupt.

634/964

DocID025834 Rev 4

UM1725

HAL RCC Generic Driver
RCC_IT_LSERDY: LSE ready interrupt.
RCC_IT_HSIRDY: HSI ready interrupt.
RCC_IT_HSERDY: HSE ready
interrupt.
RCC_IT_PLLRDY: Main PLL ready
interrupt.
RCC_IT_PLLI2SRDY: PLLI2S ready
interrupt.
__HAL_RCC_DISABLE_IT

Description:
Disable RCC interrupt (Perform Byte access
to RCC_CIR[14:8] bits to disable the
selected interrupts).
Parameters:
__INTERRUPT__: specifies the RCC
interrupt sources to be disabled. This
parameter can be any combination of the
following values:
RCC_IT_LSIRDY: LSI ready interrupt.
RCC_IT_LSERDY: LSE ready interrupt.
RCC_IT_HSIRDY: HSI ready interrupt.
RCC_IT_HSERDY: HSE ready
interrupt.
RCC_IT_PLLRDY: Main PLL ready
interrupt.
RCC_IT_PLLI2SRDY: PLLI2S ready
interrupt.

__HAL_RCC_CLEAR_IT

Description:
Clear the RCC's interrupt pending bits
(Perform Byte access to RCC_CIR[23:16]
bits to clear the selected interrupt pending
bits.
Parameters:
__INTERRUPT__: specifies the interrupt
pending bit to clear. This parameter can be
any combination of the following values:
RCC_IT_LSIRDY: LSI ready interrupt.
RCC_IT_LSERDY: LSE ready interrupt.
RCC_IT_HSIRDY: HSI ready interrupt.
RCC_IT_HSERDY: HSE ready
interrupt.
RCC_IT_PLLRDY: Main PLL ready
interrupt.
RCC_IT_PLLI2SRDY: PLLI2S ready
interrupt.
RCC_IT_CSS: Clock Security System
interrupt

__HAL_RCC_GET_IT

Description:
Check the RCC's interrupt has occurred or

DocID025834 Rev 4

635/964

HAL RCC Generic Driver

UM1725
not.
Parameters:
__INTERRUPT__: specifies the RCC
interrupt source to check. This parameter
can be one of the following values:
RCC_IT_LSIRDY: LSI ready interrupt.
RCC_IT_LSERDY: LSE ready interrupt.
RCC_IT_HSIRDY: HSI ready interrupt.
RCC_IT_HSERDY: HSE ready
interrupt.
RCC_IT_PLLRDY: Main PLL ready
interrupt.
RCC_IT_PLLI2SRDY: PLLI2S ready
interrupt.
RCC_IT_CSS: Clock Security System
interrupt
Return value:
The: new state of __INTERRUPT__ (TRUE
or FALSE).

__HAL_RCC_CLEAR_RESET_FLAGS
RCC_FLAG_MASK

Description:
Check RCC flag is set or not.
Parameters:
__FLAG__: specifies the flag to check. This
parameter can be one of the following
values:
RCC_FLAG_HSIRDY: HSI oscillator
clock ready.
RCC_FLAG_HSERDY: HSE oscillator
clock ready.
RCC_FLAG_PLLRDY: Main PLL clock
ready.
RCC_FLAG_PLLI2SRDY: PLLI2S
clock ready.
RCC_FLAG_LSERDY: LSE oscillator
clock ready.
RCC_FLAG_LSIRDY: LSI oscillator
clock ready.
RCC_FLAG_BORRST: POR/PDR or
BOR reset.
RCC_FLAG_PINRST: Pin reset.
RCC_FLAG_PORRST: POR/PDR
reset.
RCC_FLAG_SFTRST: Software reset.
RCC_FLAG_IWDGRST: Independent
Watchdog reset.
RCC_FLAG_WWDGRST: Window
Watchdog reset.
RCC_FLAG_LPWRRST: Low Power

636/964

DocID025834 Rev 4

UM1725

HAL RCC Generic Driver
reset.
Return value:
The: new state of __FLAG__ (TRUE or
FALSE).
__HAL_RCC_GET_FLAG
Get Clock source
__HAL_RCC_SYSCLK_CONFIG

Description:
Macro to configure the system clock source.
Parameters:
__RCC_SYSCLKSOURCE__: specifies the
system clock source. This parameter can be one
of the following values:
RCC_SYSCLKSOURCE_HSI: HSI
oscillator is used as system clock source.
RCC_SYSCLKSOURCE_HSE: HSE
oscillator is used as system clock source.
RCC_SYSCLKSOURCE_PLLCLK: PLL
output is used as system clock source.
RCC_SYSCLKSOURCE_PLLRCLK: PLLR
output is used as system clock source.

__HAL_RCC_GET_SYSCLK_SO
URCE

Description:
Macro to get the clock source used as system
clock.
Return value:
The: clock source used as system clock. The
returned value can be one of the following:
RCC_SYSCLKSOURCE_STATUS_HSI:
HSI used as system clock.
RCC_SYSCLKSOURCE_STATUS_HSE:
HSE used as system clock.
RCC_SYSCLKSOURCE_STATUS_PLLCL
K: PLL used as system clock.
RCC_SYSCLKSOURCE_STATUS_PLLRC
LK: PLLR used as system clock.

__HAL_RCC_GET_PLL_OSCSO
URCE

Description:
Macro to get the oscillator used as PLL clock
source.
Return value:
The: oscillator used as PLL clock source. The
returned value can be one of the following:
RCC_PLLSOURCE_HSI: HSI oscillator is
used as PLL clock source.
RCC_PLLSOURCE_HSE: HSE oscillator is
used as PLL clock source.

HSE Config

DocID025834 Rev 4

637/964

HAL RCC Generic Driver
RCC_HSE_OFF

UM1725

RCC_HSE_ON
RCC_HSE_BYPASS
HSE Configuration
__HAL_RCC_HSE_CONFIG

Description:
Macro to configure the External High Speed oscillator
(HSE).
Parameters:
__STATE__: specifies the new state of the HSE. This
parameter can be one of the following values:
RCC_HSE_OFF: turn OFF the HSE oscillator,
HSERDY flag goes low after 6 HSE oscillator
clock cycles.
RCC_HSE_ON: turn ON the HSE oscillator.
RCC_HSE_BYPASS: HSE oscillator bypassed
with external clock.
Notes:
Transition HSE Bypass to HSE On and HSE On to
HSE Bypass are not supported by this macro. User
should request a transition to HSE Off first and then
HSE On or HSE Bypass. After enabling the HSE
(RCC_HSE_ON or RCC_HSE_Bypass), the
application software should wait on HSERDY flag to
be set indicating that HSE clock is stable and can be
used to clock the PLL and/or system clock. HSE state
can not be changed if it is used directly or through the
PLL as system clock. In this case, you have to select
another source of the system clock then change the
HSE state (ex. disable it). The HSE is stopped by
hardware when entering STOP and STANDBY modes.
This function reset the CSSON bit, so if the clock
security system(CSS) was previously enabled you
have to enable it again after calling this function.

HSI Config
RCC_HSI_OFF
RCC_HSI_ON
RCC_HSICALIBRATION_DEFAULT
HSI Configuration
Notes:

__HAL_RCC_HSI_ENABLE

The HSI is stopped by hardware
when entering STOP and
STANDBY modes. It is used
(enabled by hardware) as
system clock source after
startup from Reset, wake-up
from STOP and STANDBY
mode, or in case of failure of the
638/964

DocID025834 Rev 4

UM1725

HAL RCC Generic Driver
HSE used directly or indirectly
as system clock (if the Clock
Security System CSS is
enabled). HSI can not be
stopped if it is used as system
clock source. In this case, you
have to select another source of
the system clock then stop the
HSI. After enabling the HSI, the
application software should wait
on HSIRDY flag to be set
indicating that HSI clock is
stable and can be used as
system clock source. This
parameter can be: ENABLE or
DISABLE. When the HSI is
stopped, HSIRDY flag goes low
after 6 HSI oscillator clock
cycles.
__HAL_RCC_HSI_DISABLE
__HAL_RCC_HSI_CALIBRATIONVALUE_ADJUS
T

Description:
Macro to adjust the Internal High
Speed oscillator (HSI)
calibration value.
Parameters:
__HSICalibrationValue__:
specifies the calibration
trimming value. (default is
RCC_HSICALIBRATION_DEFA
ULT). This parameter must be a
number between 0 and 0x1F.
Notes:
The calibration is used to
compensate for the variations in
voltage and temperature that
influence the frequency of the
internal HSI RC.

RTC Clock Configuration
__HAL_RCC_RTC_ENABLE

Notes:
These macros must be used only after the
RTC clock source was selected.

__HAL_RCC_RTC_DISABLE
__HAL_RCC_RTC_CLKPRESCALER

Description:
Macros to configure the RTC clock
(RTCCLK).
Parameters:
__RTCCLKSource__: specifies the RTC

DocID025834 Rev 4

639/964

HAL RCC Generic Driver

UM1725
clock source. This parameter can be one of
the following values:
RCC_RTCCLKSOURCE_LSE: LSE
selected as RTC clock.
RCC_RTCCLKSOURCE_LSI: LSI
selected as RTC clock.
RCC_RTCCLKSOURCE_HSE_DIVx:
HSE clock divided by x selected as
RTC clock, where x:[2,31]
Notes:
As the RTC clock configuration bits are in
the Backup domain and write access is
denied to this domain after reset, you have
to enable write access using the Power
Backup Access macro before to configure
the RTC clock source (to be done once
after reset). Once the RTC clock is
configured it can't be changed unless the
Backup domain is reset using
__HAL_RCC_BackupReset_RELEASE()
macro, or by a Power On Reset (POR).
If the LSE or LSI is used as RTC clock
source, the RTC continues to work in STOP
and STANDBY modes, and can be used as
wake-up source. However, when the HSE
clock is used as RTC clock source, the
RTC cannot be used in STOP and
STANDBY modes. The maximum input
clock frequency for RTC is 1MHz (when
using HSE as RTC clock source).

__HAL_RCC_RTC_CONFIG
__HAL_RCC_BACKUPRESET_FORC
E

Notes:
This function resets the RTC peripheral
(including the backup registers) and the
RTC clock source selection in RCC_CSR
register. The BKPSRAM is not affected by
this reset.

__HAL_RCC_BACKUPRESET_RELEA
SE
Interrupts
RCC_IT_LSIRDY
RCC_IT_LSERDY
RCC_IT_HSIRDY
RCC_IT_HSERDY
RCC_IT_PLLRDY
RCC_IT_PLLI2SRDY
RCC_IT_CSS

640/964

DocID025834 Rev 4

UM1725

HAL RCC Generic Driver
RCC Private macros to check input parameters
IS_RCC_OSCILLATORTYPE
IS_RCC_HSE
IS_RCC_LSE
IS_RCC_HSI
IS_RCC_LSI
IS_RCC_PLL
IS_RCC_PLLSOURCE
IS_RCC_SYSCLKSOURCE
IS_RCC_RTCCLKSOURCE
IS_RCC_PLLM_VALUE
IS_RCC_PLLP_VALUE
IS_RCC_PLLQ_VALUE
IS_RCC_HCLK
IS_RCC_CLOCKTYPE
IS_RCC_PCLK
IS_RCC_MCO
IS_RCC_MCO1SOURCE
IS_RCC_MCODIV
IS_RCC_CALIBRATION_VALUE
LSE Config
RCC_LSE_OFF
RCC_LSE_ON
RCC_LSE_BYPASS
LSE Configuration
__HAL_RCC_LSE_CONFIG

Description:
Macro to configure the External Low Speed oscillator
(LSE).
Parameters:
__STATE__: specifies the new state of the LSE. This
parameter can be one of the following values:
RCC_LSE_OFF: turn OFF the LSE oscillator,
LSERDY flag goes low after 6 LSE oscillator clock
cycles.
RCC_LSE_ON: turn ON the LSE oscillator.
RCC_LSE_BYPASS: LSE oscillator bypassed
with external clock.
Notes:
Transition LSE Bypass to LSE On and LSE On to LSE
Bypass are not supported by this macro. User should
DocID025834 Rev 4

641/964

HAL RCC Generic Driver

UM1725
request a transition to LSE Off first and then LSE On or
LSE Bypass. As the LSE is in the Backup domain and
write access is denied to this domain after reset, you
have to enable write access using
HAL_PWR_EnableBkUpAccess() function before to
configure the LSE (to be done once after reset). After
enabling the LSE (RCC_LSE_ON or
RCC_LSE_BYPASS), the application software should
wait on LSERDY flag to be set indicating that LSE
clock is stable and can be used to clock the RTC.

LSI Config
RCC_LSI_OFF
RCC_LSI_ON
LSI Configuration
__HAL_RCC_LSI_ENABLE

Notes:
After enabling the LSI, the application software should
wait on LSIRDY flag to be set indicating that LSI clock
is stable and can be used to clock the IWDG and/or the
RTC. LSI can not be disabled if the IWDG is running.
When the LSI is stopped, LSIRDY flag goes low after 6
LSI oscillator clock cycles.

__HAL_RCC_LSI_DISABLE
MCO1 Clock Source
RCC_MCO1SOURCE_HSI
RCC_MCO1SOURCE_LSE
RCC_MCO1SOURCE_HSE
RCC_MCO1SOURCE_PLLCLK
MCO2 Clock Source
RCC_MCO2SOURCE_SYSCLK
RCC_MCO2SOURCE_PLLI2SCLK
RCC_MCO2SOURCE_HSE
RCC_MCO2SOURCE_PLLCLK
MCOx Clock Prescaler
RCC_MCODIV_1
RCC_MCODIV_2
RCC_MCODIV_3
RCC_MCODIV_4
RCC_MCODIV_5
MCO Index
RCC_MCO1
RCC_MCO2

642/964

DocID025834 Rev 4

UM1725

HAL RCC Generic Driver
Oscillator Type
RCC_OSCILLATORTYPE_NONE
RCC_OSCILLATORTYPE_HSE
RCC_OSCILLATORTYPE_HSI
RCC_OSCILLATORTYPE_LSE
RCC_OSCILLATORTYPE_LSI
PLLP Clock Divider
RCC_PLLP_DIV2
RCC_PLLP_DIV4
RCC_PLLP_DIV6
RCC_PLLP_DIV8
PLL Clock Source
RCC_PLLSOURCE_HSI
RCC_PLLSOURCE_HSE
PLL Config
RCC_PLL_NONE
RCC_PLL_OFF
RCC_PLL_ON
PLL Configuration
Notes:

__HAL_RCC_PLL_ENABLE

After enabling the main PLL, the
application software should wait on
PLLRDY flag to be set indicating that
PLL clock is stable and can be used as
system clock source. The main PLL can
not be disabled if it is used as system
clock source The main PLL is disabled
by hardware when entering STOP and
STANDBY modes.
__HAL_RCC_PLL_DISABLE
__HAL_RCC_PLL_PLLSOURCE_CONFIG

Description:
Macro to configure the PLL clock
source.
Parameters:
__PLLSOURCE__: specifies the PLL
entry clock source. This parameter can
be one of the following values:
RCC_PLLSOURCE_HSI: HSI
oscillator clock selected as PLL
clock entry
RCC_PLLSOURCE_HSE: HSE
oscillator clock selected as PLL

DocID025834 Rev 4

643/964

HAL RCC Generic Driver

UM1725
clock entry
Notes:
This function must be used only when
the main PLL is disabled.

__HAL_RCC_PLL_PLLM_CONFIG

Description:
Macro to configure the PLL
multiplication factor.
Parameters:
__PLLM__: specifies the division factor
for PLL VCO input clock This parameter
must be a number between Min_Data =
2 and Max_Data = 63.
Notes:
This function must be used only when
the main PLL is disabled.
You have to set the PLLM parameter
correctly to ensure that the VCO input
frequency ranges from 1 to 2 MHz. It is
recommended to select a frequency of 2
MHz to limit PLL jitter.

RTC Clock Source
RCC_RTCCLKSOURCE_LSE
RCC_RTCCLKSOURCE_LSI
RCC_RTCCLKSOURCE_HSE_DIV2
RCC_RTCCLKSOURCE_HSE_DIV3
RCC_RTCCLKSOURCE_HSE_DIV4
RCC_RTCCLKSOURCE_HSE_DIV5
RCC_RTCCLKSOURCE_HSE_DIV6
RCC_RTCCLKSOURCE_HSE_DIV7
RCC_RTCCLKSOURCE_HSE_DIV8
RCC_RTCCLKSOURCE_HSE_DIV9
RCC_RTCCLKSOURCE_HSE_DIV10
RCC_RTCCLKSOURCE_HSE_DIV11
RCC_RTCCLKSOURCE_HSE_DIV12
RCC_RTCCLKSOURCE_HSE_DIV13
RCC_RTCCLKSOURCE_HSE_DIV14
RCC_RTCCLKSOURCE_HSE_DIV15
RCC_RTCCLKSOURCE_HSE_DIV16
RCC_RTCCLKSOURCE_HSE_DIV17
RCC_RTCCLKSOURCE_HSE_DIV18

644/964

DocID025834 Rev 4

UM1725

HAL RCC Generic Driver
RCC_RTCCLKSOURCE_HSE_DIV19
RCC_RTCCLKSOURCE_HSE_DIV20
RCC_RTCCLKSOURCE_HSE_DIV21
RCC_RTCCLKSOURCE_HSE_DIV22
RCC_RTCCLKSOURCE_HSE_DIV23
RCC_RTCCLKSOURCE_HSE_DIV24
RCC_RTCCLKSOURCE_HSE_DIV25
RCC_RTCCLKSOURCE_HSE_DIV26
RCC_RTCCLKSOURCE_HSE_DIV27
RCC_RTCCLKSOURCE_HSE_DIV28
RCC_RTCCLKSOURCE_HSE_DIV29
RCC_RTCCLKSOURCE_HSE_DIV30
RCC_RTCCLKSOURCE_HSE_DIV31
System Clock Source
RCC_SYSCLKSOURCE_HSI
RCC_SYSCLKSOURCE_HSE
RCC_SYSCLKSOURCE_PLLCLK
RCC_SYSCLKSOURCE_PLLRCLK
System Clock Source Status
RCC_SYSCLKSOURCE_STATUS_HSI

HSI used as system clock

RCC_SYSCLKSOURCE_STATUS_HSE

HSE used as system clock

RCC_SYSCLKSOURCE_STATUS_PLLCLK

PLL used as system clock

RCC_SYSCLKSOURCE_STATUS_PLLRCLK

PLLR used as system clock

System Clock Type
RCC_CLOCKTYPE_SYSCLK
RCC_CLOCKTYPE_HCLK
RCC_CLOCKTYPE_PCLK1
RCC_CLOCKTYPE_PCLK2

DocID025834 Rev 4

645/964

HAL RCC Extension Driver

UM1725

50

HAL RCC Extension Driver

50.1

RCCEx Firmware driver registers structures

50.1.1

RCC_PLLInitTypeDef
Data Fields
uint32_t PLLState
uint32_t PLLSource
uint32_t PLLM
uint32_t PLLN
uint32_t PLLP
uint32_t PLLQ
uint32_t PLLR

Field Documentation
uint32_t RCC_PLLInitTypeDef::PLLState
The new state of the PLL. This parameter can be a value of RCC_PLL_Config
uint32_t RCC_PLLInitTypeDef::PLLSource
RCC_PLLSource: PLL entry clock source. This parameter must be a value of
RCC_PLL_Clock_Source
uint32_t RCC_PLLInitTypeDef::PLLM
PLLM: Division factor for PLL VCO input clock. This parameter must be a number
between Min_Data = 0 and Max_Data = 63
uint32_t RCC_PLLInitTypeDef::PLLN
PLLN: Multiplication factor for PLL VCO output clock. This parameter must be a
number between Min_Data = 50 and Max_Data = 432 except for STM32F411xE
devices where the Min_Data = 192
uint32_t RCC_PLLInitTypeDef::PLLP
PLLP: Division factor for main system clock (SYSCLK). This parameter must be a
value of RCC_PLLP_Clock_Divider
uint32_t RCC_PLLInitTypeDef::PLLQ
PLLQ: Division factor for OTG FS, SDIO and RNG clocks. This parameter must be a
number between Min_Data = 4 and Max_Data = 15
uint32_t RCC_PLLInitTypeDef::PLLR
PLLR: PLL division factor for I2S, SAI, SYSTEM, SPDIFRX clocks. This parameter is
only available in STM32F410xx/STM32F446xx/STM32F469xx/STM32F479xx and
STM32F412Zx/STM32F412Vx/STM32F412Rx/STM32F412Cx devices. This
parameter must be a number between Min_Data = 2 and Max_Data = 7

50.1.2

RCC_PLLI2SInitTypeDef
Data Fields
uint32_t PLLI2SN
uint32_t PLLI2SR

646/964

DocID025834 Rev 4

UM1725

HAL RCC Extension Driver
uint32_t PLLI2SQ

Field Documentation
uint32_t RCC_PLLI2SInitTypeDef::PLLI2SN
Specifies the multiplication factor for PLLI2S VCO output clock. This parameter must
be a number between Min_Data = 50 and Max_Data = 432. This parameter will be
used only when PLLI2S is selected as Clock Source I2S or SAI
uint32_t RCC_PLLI2SInitTypeDef::PLLI2SR
Specifies the division factor for I2S clock. This parameter must be a number between
Min_Data = 2 and Max_Data = 7. This parameter will be used only when PLLI2S is
selected as Clock Source I2S or SAI
uint32_t RCC_PLLI2SInitTypeDef::PLLI2SQ
Specifies the division factor for SAI1 clock. This parameter must be a number
between Min_Data = 2 and Max_Data = 15. This parameter will be used only when
PLLI2S is selected as Clock Source SAI

50.1.3

RCC_PLLSAIInitTypeDef
Data Fields
uint32_t PLLSAIN
uint32_t PLLSAIP
uint32_t PLLSAIQ
uint32_t PLLSAIR

Field Documentation
uint32_t RCC_PLLSAIInitTypeDef::PLLSAIN
Specifies the multiplication factor for PLLI2S VCO output clock. This parameter must
be a number between Min_Data = 50 and Max_Data = 432. This parameter will be
used only when PLLSAI is selected as Clock Source SAI or LTDC
uint32_t RCC_PLLSAIInitTypeDef::PLLSAIP
Specifies division factor for OTG FS and SDIO clocks. This parameter is only
available in STM32F469xx/STM32F479xx devices. This parameter must be a value of
RCCEx_PLLSAIP_Clock_Divider
uint32_t RCC_PLLSAIInitTypeDef::PLLSAIQ
Specifies the division factor for SAI1 clock. This parameter must be a number
between Min_Data = 2 and Max_Data = 15. This parameter will be used only when
PLLSAI is selected as Clock Source SAI or LTDC
uint32_t RCC_PLLSAIInitTypeDef::PLLSAIR
specifies the division factor for LTDC clock This parameter must be a number
between Min_Data = 2 and Max_Data = 7. This parameter will be used only when
PLLSAI is selected as Clock Source LTDC

DocID025834 Rev 4

647/964

HAL RCC Extension Driver

50.1.4

UM1725

RCC_PeriphCLKInitTypeDef
Data Fields
uint32_t PeriphClockSelection
RCC_PLLI2SInitTypeDef PLLI2S
RCC_PLLSAIInitTypeDef PLLSAI
uint32_t PLLI2SDivQ
uint32_t PLLSAIDivQ
uint32_t PLLSAIDivR
uint32_t RTCClockSelection
uint8_t TIMPresSelection
uint32_t Clk48ClockSelection
uint32_t SdioClockSelection

Field Documentation
uint32_t RCC_PeriphCLKInitTypeDef::PeriphClockSelection
The Extended Clock to be configured. This parameter can be a value of
RCCEx_Periph_Clock_Selection
RCC_PLLI2SInitTypeDef RCC_PeriphCLKInitTypeDef::PLLI2S
PLL I2S structure parameters. This parameter will be used only when PLLI2S is
selected as Clock Source I2S or SAI
RCC_PLLSAIInitTypeDef RCC_PeriphCLKInitTypeDef::PLLSAI
PLL SAI structure parameters. This parameter will be used only when PLLI2S is
selected as Clock Source SAI or LTDC
uint32_t RCC_PeriphCLKInitTypeDef::PLLI2SDivQ
Specifies the PLLI2S division factor for SAI1 clock. This parameter must be a number
between Min_Data = 1 and Max_Data = 32 This parameter will be used only when
PLLI2S is selected as Clock Source SAI
uint32_t RCC_PeriphCLKInitTypeDef::PLLSAIDivQ
Specifies the PLLI2S division factor for SAI1 clock. This parameter must be a number
between Min_Data = 1 and Max_Data = 32 This parameter will be used only when
PLLSAI is selected as Clock Source SAI
uint32_t RCC_PeriphCLKInitTypeDef::PLLSAIDivR
Specifies the PLLSAI division factor for LTDC clock. This parameter must be one
value of RCCEx_PLLSAI_DIVR
uint32_t RCC_PeriphCLKInitTypeDef::RTCClockSelection
Specifies RTC Clock Prescalers Selection. This parameter can be a value of
RCC_RTC_Clock_Source
uint8_t RCC_PeriphCLKInitTypeDef::TIMPresSelection
Specifies TIM Clock Prescalers Selection. This parameter can be a value of
RCCEx_TIM_PRescaler_Selection
uint32_t RCC_PeriphCLKInitTypeDef::Clk48ClockSelection
Specifies CLK48 Clock Selection this clock used OTG FS, SDIO and RNG clocks.
This parameter can be a value of RCCEx_CLK48_Clock_Source
uint32_t RCC_PeriphCLKInitTypeDef::SdioClockSelection
Specifies SDIO Clock Source Selection. This parameter can be a value of
RCCEx_SDIO_Clock_Source

648/964

DocID025834 Rev 4

UM1725

HAL RCC Extension Driver

50.2

RCCEx Firmware driver API description

50.2.1

Extended Peripheral Control functions
This subsection provides a set of functions allowing to control the RCC Clocks
frequencies.
Important note: Care must be taken when HAL_RCCEx_PeriphCLKConfig() is
used to select the RTC clock source; in this case the Backup domain will be reset
in order to modify the RTC Clock source, as consequence RTC registers
(including the backup registers) and RCC_BDCR register are set to their reset
values.
This section contains the following APIs:
HAL_RCC_DeInit()
HAL_RCCEx_PeriphCLKConfig()
HAL_RCCEx_GetPeriphCLKConfig()
HAL_RCC_OscConfig()
HAL_RCC_GetOscConfig()
HAL_RCCEx_SelectLSEMode()

50.2.2

Detailed description of functions
HAL_RCCEx_PeriphCLKConfig
Function Name

HAL_StatusTypeDef HAL_RCCEx_PeriphCLKConfig
(RCC_PeriphCLKInitTypeDef * PeriphClkInit)

Function Description

Initializes the RCC extended peripherals clocks according to the
specified parameters in the RCC_PeriphCLKInitTypeDef.

Parameters

PeriphClkInit: pointer to an RCC_PeriphCLKInitTypeDef
structure that contains the configuration information for the
Extended Peripherals clocks(I2S, SAI, LTDC, RTC and TIM).

Return values

HAL: status

Notes

Care must be taken when HAL_RCCEx_PeriphCLKConfig() is
used to select the RTC clock source; in this case the Backup
domain will be reset in order to modify the RTC Clock source,
as consequence RTC registers (including the backup
registers) and RCC_BDCR register are set to their reset
values.

HAL_RCCEx_GetPeriphCLKConfig
Function Name

void HAL_RCCEx_GetPeriphCLKConfig
(RCC_PeriphCLKInitTypeDef * PeriphClkInit)

Function Description

Configures the RCC_PeriphCLKInitTypeDef according to the
internal RCC configuration registers.

Parameters

PeriphClkInit: pointer to an RCC_PeriphCLKInitTypeDef
structure that will be configured.

Return values

None

DocID025834 Rev 4

649/964

HAL RCC Extension Driver

UM1725

HAL_RCCEx_SelectLSEMode
Functi
on
Name

void HAL_RCCEx_SelectLSEMode (uint8_t Mode)

Functi
on
Descri
ption

Select LSE mode.

Param
eters

Mode: specifies the LSE mode. This parameter can be one of the following
values:
RCC_LSE_LOWPOWER_MODE: LSE oscillator in low power mode
selection
RCC_LSE_HIGHDRIVE_MODE: LSE oscillator in High Drive mode
selection

Return
values

None

Notes

This mode is only available for
STM32F410xx/STM32F411xx/STM32F446xx/STM32F469xx/STM32F479xx/
STM32F412Zx/STM32F412Vx/STM32F412Rx/STM32F412Cx devices.

50.3

RCCEx Firmware driver defines

50.3.1

RCCEx
AHB1 Peripheral Clock Enable Disable
__HAL_RCC_BKPSRAM_CLK_ENABLE
__HAL_RCC_CCMDATARAMEN_CLK_ENABLE
__HAL_RCC_CRC_CLK_ENABLE
__HAL_RCC_GPIOD_CLK_ENABLE
__HAL_RCC_GPIOE_CLK_ENABLE
__HAL_RCC_GPIOI_CLK_ENABLE
__HAL_RCC_GPIOF_CLK_ENABLE
__HAL_RCC_GPIOG_CLK_ENABLE
__HAL_RCC_GPIOJ_CLK_ENABLE
__HAL_RCC_GPIOK_CLK_ENABLE
__HAL_RCC_DMA2D_CLK_ENABLE
__HAL_RCC_ETHMAC_CLK_ENABLE
__HAL_RCC_ETHMACTX_CLK_ENABLE
__HAL_RCC_ETHMACRX_CLK_ENABLE
__HAL_RCC_ETHMACPTP_CLK_ENABLE
__HAL_RCC_USB_OTG_HS_CLK_ENABLE
__HAL_RCC_USB_OTG_HS_ULPI_CLK_ENABLE

650/964

DocID025834 Rev 4

UM1725

HAL RCC Extension Driver
__HAL_RCC_GPIOD_CLK_DISABLE
__HAL_RCC_GPIOE_CLK_DISABLE
__HAL_RCC_GPIOF_CLK_DISABLE
__HAL_RCC_GPIOG_CLK_DISABLE
__HAL_RCC_GPIOI_CLK_DISABLE
__HAL_RCC_GPIOJ_CLK_DISABLE
__HAL_RCC_GPIOK_CLK_DISABLE
__HAL_RCC_DMA2D_CLK_DISABLE
__HAL_RCC_ETHMAC_CLK_DISABLE
__HAL_RCC_ETHMACTX_CLK_DISABLE
__HAL_RCC_ETHMACRX_CLK_DISABLE
__HAL_RCC_ETHMACPTP_CLK_DISABLE
__HAL_RCC_USB_OTG_HS_CLK_DISABLE
__HAL_RCC_USB_OTG_HS_ULPI_CLK_DISABLE
__HAL_RCC_BKPSRAM_CLK_DISABLE
__HAL_RCC_CCMDATARAMEN_CLK_DISABLE
__HAL_RCC_CRC_CLK_DISABLE
__HAL_RCC_ETH_CLK_ENABLE
__HAL_RCC_ETH_CLK_DISABLE
AHB1 Force Release Reset
__HAL_RCC_GPIOD_FORCE_RESET
__HAL_RCC_GPIOE_FORCE_RESET
__HAL_RCC_GPIOF_FORCE_RESET
__HAL_RCC_GPIOG_FORCE_RESET
__HAL_RCC_GPIOI_FORCE_RESET
__HAL_RCC_ETHMAC_FORCE_RESET
__HAL_RCC_USB_OTG_HS_FORCE_RESET
__HAL_RCC_GPIOJ_FORCE_RESET
__HAL_RCC_GPIOK_FORCE_RESET
__HAL_RCC_DMA2D_FORCE_RESET
__HAL_RCC_CRC_FORCE_RESET
__HAL_RCC_GPIOD_RELEASE_RESET
__HAL_RCC_GPIOE_RELEASE_RESET
__HAL_RCC_GPIOF_RELEASE_RESET
__HAL_RCC_GPIOG_RELEASE_RESET
__HAL_RCC_GPIOI_RELEASE_RESET

DocID025834 Rev 4

651/964

HAL RCC Extension Driver
__HAL_RCC_ETHMAC_RELEASE_RESET
__HAL_RCC_USB_OTG_HS_RELEASE_RESET
__HAL_RCC_GPIOJ_RELEASE_RESET
__HAL_RCC_GPIOK_RELEASE_RESET
__HAL_RCC_DMA2D_RELEASE_RESET
__HAL_RCC_CRC_RELEASE_RESET
AHB1 Peripheral Low Power Enable Disable
__HAL_RCC_GPIOD_CLK_SLEEP_ENABLE
__HAL_RCC_GPIOE_CLK_SLEEP_ENABLE
__HAL_RCC_GPIOF_CLK_SLEEP_ENABLE
__HAL_RCC_GPIOG_CLK_SLEEP_ENABLE
__HAL_RCC_GPIOI_CLK_SLEEP_ENABLE
__HAL_RCC_SRAM2_CLK_SLEEP_ENABLE
__HAL_RCC_ETHMAC_CLK_SLEEP_ENABLE
__HAL_RCC_ETHMACTX_CLK_SLEEP_ENABLE
__HAL_RCC_ETHMACRX_CLK_SLEEP_ENABLE
__HAL_RCC_ETHMACPTP_CLK_SLEEP_ENABLE
__HAL_RCC_USB_OTG_HS_CLK_SLEEP_ENABLE
__HAL_RCC_USB_OTG_HS_ULPI_CLK_SLEEP_ENABLE
__HAL_RCC_GPIOJ_CLK_SLEEP_ENABLE
__HAL_RCC_GPIOK_CLK_SLEEP_ENABLE
__HAL_RCC_SRAM3_CLK_SLEEP_ENABLE
__HAL_RCC_DMA2D_CLK_SLEEP_ENABLE
__HAL_RCC_CRC_CLK_SLEEP_ENABLE
__HAL_RCC_FLITF_CLK_SLEEP_ENABLE
__HAL_RCC_SRAM1_CLK_SLEEP_ENABLE
__HAL_RCC_BKPSRAM_CLK_SLEEP_ENABLE
__HAL_RCC_GPIOD_CLK_SLEEP_DISABLE
__HAL_RCC_GPIOE_CLK_SLEEP_DISABLE
__HAL_RCC_GPIOF_CLK_SLEEP_DISABLE
__HAL_RCC_GPIOG_CLK_SLEEP_DISABLE
__HAL_RCC_GPIOI_CLK_SLEEP_DISABLE
__HAL_RCC_SRAM2_CLK_SLEEP_DISABLE
__HAL_RCC_ETHMAC_CLK_SLEEP_DISABLE
__HAL_RCC_ETHMACTX_CLK_SLEEP_DISABLE
__HAL_RCC_ETHMACRX_CLK_SLEEP_DISABLE

652/964

DocID025834 Rev 4

UM1725

UM1725

HAL RCC Extension Driver
__HAL_RCC_ETHMACPTP_CLK_SLEEP_DISABLE
__HAL_RCC_USB_OTG_HS_CLK_SLEEP_DISABLE
__HAL_RCC_USB_OTG_HS_ULPI_CLK_SLEEP_DISABLE
__HAL_RCC_GPIOJ_CLK_SLEEP_DISABLE
__HAL_RCC_GPIOK_CLK_SLEEP_DISABLE
__HAL_RCC_DMA2D_CLK_SLEEP_DISABLE
__HAL_RCC_CRC_CLK_SLEEP_DISABLE
__HAL_RCC_FLITF_CLK_SLEEP_DISABLE
__HAL_RCC_SRAM1_CLK_SLEEP_DISABLE
__HAL_RCC_BKPSRAM_CLK_SLEEP_DISABLE
AHB1 Peripheral Clock Enable Disable Status
__HAL_RCC_GPIOD_IS_CLK_ENABLED
__HAL_RCC_GPIOE_IS_CLK_ENABLED
__HAL_RCC_GPIOF_IS_CLK_ENABLED
__HAL_RCC_GPIOG_IS_CLK_ENABLED
__HAL_RCC_GPIOI_IS_CLK_ENABLED
__HAL_RCC_GPIOJ_IS_CLK_ENABLED
__HAL_RCC_GPIOK_IS_CLK_ENABLED
__HAL_RCC_DMA2D_IS_CLK_ENABLED
__HAL_RCC_ETHMAC_IS_CLK_ENABLED
__HAL_RCC_ETHMACTX_IS_CLK_ENABLED
__HAL_RCC_ETHMACRX_IS_CLK_ENABLED
__HAL_RCC_ETHMACPTP_IS_CLK_ENABLED
__HAL_RCC_USB_OTG_HS_IS_CLK_ENABLED
__HAL_RCC_USB_OTG_HS_ULPI_IS_CLK_ENABLED
__HAL_RCC_BKPSRAM_IS_CLK_ENABLED
__HAL_RCC_CCMDATARAMEN_IS_CLK_ENABLED
__HAL_RCC_CRC_IS_CLK_ENABLED
__HAL_RCC_ETH_IS_CLK_ENABLED
__HAL_RCC_GPIOD_IS_CLK_DISABLED
__HAL_RCC_GPIOE_IS_CLK_DISABLED
__HAL_RCC_GPIOF_IS_CLK_DISABLED
__HAL_RCC_GPIOG_IS_CLK_DISABLED
__HAL_RCC_GPIOI_IS_CLK_DISABLED
__HAL_RCC_GPIOJ_IS_CLK_DISABLED
__HAL_RCC_GPIOK_IS_CLK_DISABLED

DocID025834 Rev 4

653/964

HAL RCC Extension Driver
__HAL_RCC_DMA2D_IS_CLK_DISABLED
__HAL_RCC_ETHMAC_IS_CLK_DISABLED
__HAL_RCC_ETHMACTX_IS_CLK_DISABLED
__HAL_RCC_ETHMACRX_IS_CLK_DISABLED
__HAL_RCC_ETHMACPTP_IS_CLK_DISABLED
__HAL_RCC_USB_OTG_HS_IS_CLK_DISABLED
__HAL_RCC_USB_OTG_HS_ULPI_IS_CLK_DISABLED
__HAL_RCC_BKPSRAM_IS_CLK_DISABLED
__HAL_RCC_CCMDATARAMEN_IS_CLK_DISABLED
__HAL_RCC_CRC_IS_CLK_DISABLED
__HAL_RCC_ETH_IS_CLK_DISABLED
AHB2 Peripheral Clock Enable Disable
__HAL_RCC_DCMI_CLK_ENABLE
__HAL_RCC_DCMI_CLK_DISABLE
__HAL_RCC_CRYP_CLK_ENABLE
__HAL_RCC_HASH_CLK_ENABLE
__HAL_RCC_CRYP_CLK_DISABLE
__HAL_RCC_HASH_CLK_DISABLE
__HAL_RCC_USB_OTG_FS_CLK_ENABLE
__HAL_RCC_USB_OTG_FS_CLK_DISABLE
__HAL_RCC_RNG_CLK_ENABLE
__HAL_RCC_RNG_CLK_DISABLE
AHB2 Force Release Reset
__HAL_RCC_AHB2_FORCE_RESET
__HAL_RCC_USB_OTG_FS_FORCE_RESET
__HAL_RCC_RNG_FORCE_RESET
__HAL_RCC_DCMI_FORCE_RESET
__HAL_RCC_AHB2_RELEASE_RESET
__HAL_RCC_USB_OTG_FS_RELEASE_RESET
__HAL_RCC_RNG_RELEASE_RESET
__HAL_RCC_DCMI_RELEASE_RESET
__HAL_RCC_CRYP_FORCE_RESET
__HAL_RCC_HASH_FORCE_RESET
__HAL_RCC_CRYP_RELEASE_RESET
__HAL_RCC_HASH_RELEASE_RESET
AHB2 Peripheral Low Power Enable Disable

654/964

DocID025834 Rev 4

UM1725

UM1725

HAL RCC Extension Driver
__HAL_RCC_USB_OTG_FS_CLK_SLEEP_ENABLE
__HAL_RCC_USB_OTG_FS_CLK_SLEEP_DISABLE
__HAL_RCC_RNG_CLK_SLEEP_ENABLE
__HAL_RCC_RNG_CLK_SLEEP_DISABLE
__HAL_RCC_DCMI_CLK_SLEEP_ENABLE
__HAL_RCC_DCMI_CLK_SLEEP_DISABLE
__HAL_RCC_CRYP_CLK_SLEEP_ENABLE
__HAL_RCC_HASH_CLK_SLEEP_ENABLE
__HAL_RCC_CRYP_CLK_SLEEP_DISABLE
__HAL_RCC_HASH_CLK_SLEEP_DISABLE
AHB2 Peripheral Clock Enable Disable Status
__HAL_RCC_DCMI_IS_CLK_ENABLED
__HAL_RCC_DCMI_IS_CLK_DISABLED
__HAL_RCC_CRYP_IS_CLK_ENABLED
__HAL_RCC_CRYP_IS_CLK_DISABLED
__HAL_RCC_HASH_IS_CLK_ENABLED
__HAL_RCC_HASH_IS_CLK_DISABLED
__HAL_RCC_USB_OTG_FS_IS_CLK_ENABLED
__HAL_RCC_USB_OTG_FS_IS_CLK_DISABLED
__HAL_RCC_RNG_IS_CLK_ENABLED
__HAL_RCC_RNG_IS_CLK_DISABLED
AHB3 Peripheral Clock Enable Disable
__HAL_RCC_FMC_CLK_ENABLE
__HAL_RCC_FMC_CLK_DISABLE
__HAL_RCC_QSPI_CLK_ENABLE
__HAL_RCC_QSPI_CLK_DISABLE
AHB3 Force Release Reset
__HAL_RCC_AHB3_FORCE_RESET
__HAL_RCC_AHB3_RELEASE_RESET
__HAL_RCC_FMC_FORCE_RESET
__HAL_RCC_FMC_RELEASE_RESET
__HAL_RCC_QSPI_FORCE_RESET
__HAL_RCC_QSPI_RELEASE_RESET
AHB3 Peripheral Low Power Enable Disable
__HAL_RCC_FMC_CLK_SLEEP_ENABLE
__HAL_RCC_FMC_CLK_SLEEP_DISABLE

DocID025834 Rev 4

655/964

HAL RCC Extension Driver
__HAL_RCC_QSPI_CLK_SLEEP_ENABLE
__HAL_RCC_QSPI_CLK_SLEEP_DISABLE
AHB3 Peripheral Clock Enable Disable Status
__HAL_RCC_FMC_IS_CLK_ENABLED
__HAL_RCC_FMC_IS_CLK_DISABLED
__HAL_RCC_QSPI_IS_CLK_ENABLED
__HAL_RCC_QSPI_IS_CLK_DISABLED
APB1 Peripheral Clock Enable Disable
__HAL_RCC_TIM6_CLK_ENABLE
__HAL_RCC_TIM7_CLK_ENABLE
__HAL_RCC_TIM12_CLK_ENABLE
__HAL_RCC_TIM13_CLK_ENABLE
__HAL_RCC_TIM14_CLK_ENABLE
__HAL_RCC_TIM14_CLK_ENABLE
__HAL_RCC_USART3_CLK_ENABLE
__HAL_RCC_UART4_CLK_ENABLE
__HAL_RCC_UART5_CLK_ENABLE
__HAL_RCC_CAN1_CLK_ENABLE
__HAL_RCC_CAN2_CLK_ENABLE
__HAL_RCC_DAC_CLK_ENABLE
__HAL_RCC_UART7_CLK_ENABLE
__HAL_RCC_UART8_CLK_ENABLE
__HAL_RCC_TIM2_CLK_ENABLE
__HAL_RCC_TIM3_CLK_ENABLE
__HAL_RCC_TIM4_CLK_ENABLE
__HAL_RCC_SPI3_CLK_ENABLE
__HAL_RCC_I2C3_CLK_ENABLE
__HAL_RCC_TIM2_CLK_DISABLE
__HAL_RCC_TIM3_CLK_DISABLE
__HAL_RCC_TIM4_CLK_DISABLE
__HAL_RCC_SPI3_CLK_DISABLE
__HAL_RCC_I2C3_CLK_DISABLE
__HAL_RCC_TIM6_CLK_DISABLE
__HAL_RCC_TIM7_CLK_DISABLE
__HAL_RCC_TIM12_CLK_DISABLE
__HAL_RCC_TIM13_CLK_DISABLE

656/964

DocID025834 Rev 4

UM1725

UM1725

HAL RCC Extension Driver
__HAL_RCC_TIM14_CLK_DISABLE
__HAL_RCC_USART3_CLK_DISABLE
__HAL_RCC_UART4_CLK_DISABLE
__HAL_RCC_UART5_CLK_DISABLE
__HAL_RCC_CAN1_CLK_DISABLE
__HAL_RCC_CAN2_CLK_DISABLE
__HAL_RCC_DAC_CLK_DISABLE
__HAL_RCC_UART7_CLK_DISABLE
__HAL_RCC_UART8_CLK_DISABLE
APB1 Force Release Reset
__HAL_RCC_TIM6_FORCE_RESET
__HAL_RCC_TIM7_FORCE_RESET
__HAL_RCC_TIM12_FORCE_RESET
__HAL_RCC_TIM13_FORCE_RESET
__HAL_RCC_TIM14_FORCE_RESET
__HAL_RCC_USART3_FORCE_RESET
__HAL_RCC_UART4_FORCE_RESET
__HAL_RCC_UART5_FORCE_RESET
__HAL_RCC_CAN1_FORCE_RESET
__HAL_RCC_CAN2_FORCE_RESET
__HAL_RCC_DAC_FORCE_RESET
__HAL_RCC_UART7_FORCE_RESET
__HAL_RCC_UART8_FORCE_RESET
__HAL_RCC_TIM2_FORCE_RESET
__HAL_RCC_TIM3_FORCE_RESET
__HAL_RCC_TIM4_FORCE_RESET
__HAL_RCC_SPI3_FORCE_RESET
__HAL_RCC_I2C3_FORCE_RESET
__HAL_RCC_TIM2_RELEASE_RESET
__HAL_RCC_TIM3_RELEASE_RESET
__HAL_RCC_TIM4_RELEASE_RESET
__HAL_RCC_SPI3_RELEASE_RESET
__HAL_RCC_I2C3_RELEASE_RESET
__HAL_RCC_TIM6_RELEASE_RESET
__HAL_RCC_TIM7_RELEASE_RESET
__HAL_RCC_TIM12_RELEASE_RESET

DocID025834 Rev 4

657/964

HAL RCC Extension Driver
__HAL_RCC_TIM13_RELEASE_RESET
__HAL_RCC_TIM14_RELEASE_RESET
__HAL_RCC_USART3_RELEASE_RESET
__HAL_RCC_UART4_RELEASE_RESET
__HAL_RCC_UART5_RELEASE_RESET
__HAL_RCC_CAN1_RELEASE_RESET
__HAL_RCC_CAN2_RELEASE_RESET
__HAL_RCC_DAC_RELEASE_RESET
__HAL_RCC_UART7_RELEASE_RESET
__HAL_RCC_UART8_RELEASE_RESET
APB1 Peripheral Low Power Enable Disable
__HAL_RCC_TIM6_CLK_SLEEP_ENABLE
__HAL_RCC_TIM7_CLK_SLEEP_ENABLE
__HAL_RCC_TIM12_CLK_SLEEP_ENABLE
__HAL_RCC_TIM13_CLK_SLEEP_ENABLE
__HAL_RCC_TIM14_CLK_SLEEP_ENABLE
__HAL_RCC_USART3_CLK_SLEEP_ENABLE
__HAL_RCC_UART4_CLK_SLEEP_ENABLE
__HAL_RCC_UART5_CLK_SLEEP_ENABLE
__HAL_RCC_CAN1_CLK_SLEEP_ENABLE
__HAL_RCC_CAN2_CLK_SLEEP_ENABLE
__HAL_RCC_DAC_CLK_SLEEP_ENABLE
__HAL_RCC_UART7_CLK_SLEEP_ENABLE
__HAL_RCC_UART8_CLK_SLEEP_ENABLE
__HAL_RCC_TIM2_CLK_SLEEP_ENABLE
__HAL_RCC_TIM3_CLK_SLEEP_ENABLE
__HAL_RCC_TIM4_CLK_SLEEP_ENABLE
__HAL_RCC_SPI3_CLK_SLEEP_ENABLE
__HAL_RCC_I2C3_CLK_SLEEP_ENABLE
__HAL_RCC_TIM2_CLK_SLEEP_DISABLE
__HAL_RCC_TIM3_CLK_SLEEP_DISABLE
__HAL_RCC_TIM4_CLK_SLEEP_DISABLE
__HAL_RCC_SPI3_CLK_SLEEP_DISABLE
__HAL_RCC_I2C3_CLK_SLEEP_DISABLE
__HAL_RCC_TIM6_CLK_SLEEP_DISABLE
__HAL_RCC_TIM7_CLK_SLEEP_DISABLE

658/964

DocID025834 Rev 4

UM1725

UM1725

HAL RCC Extension Driver
__HAL_RCC_TIM12_CLK_SLEEP_DISABLE
__HAL_RCC_TIM13_CLK_SLEEP_DISABLE
__HAL_RCC_TIM14_CLK_SLEEP_DISABLE
__HAL_RCC_USART3_CLK_SLEEP_DISABLE
__HAL_RCC_UART4_CLK_SLEEP_DISABLE
__HAL_RCC_UART5_CLK_SLEEP_DISABLE
__HAL_RCC_CAN1_CLK_SLEEP_DISABLE
__HAL_RCC_CAN2_CLK_SLEEP_DISABLE
__HAL_RCC_DAC_CLK_SLEEP_DISABLE
__HAL_RCC_UART7_CLK_SLEEP_DISABLE
__HAL_RCC_UART8_CLK_SLEEP_DISABLE
APB1 Peripheral Clock Enable Disable Status
__HAL_RCC_TIM2_IS_CLK_ENABLED
__HAL_RCC_TIM3_IS_CLK_ENABLED
__HAL_RCC_TIM4_IS_CLK_ENABLED
__HAL_RCC_SPI3_IS_CLK_ENABLED
__HAL_RCC_I2C3_IS_CLK_ENABLED
__HAL_RCC_TIM6_IS_CLK_ENABLED
__HAL_RCC_TIM7_IS_CLK_ENABLED
__HAL_RCC_TIM12_IS_CLK_ENABLED
__HAL_RCC_TIM13_IS_CLK_ENABLED
__HAL_RCC_TIM14_IS_CLK_ENABLED
__HAL_RCC_USART3_IS_CLK_ENABLED
__HAL_RCC_UART4_IS_CLK_ENABLED
__HAL_RCC_UART5_IS_CLK_ENABLED
__HAL_RCC_CAN1_IS_CLK_ENABLED
__HAL_RCC_CAN2_IS_CLK_ENABLED
__HAL_RCC_DAC_IS_CLK_ENABLED
__HAL_RCC_UART7_IS_CLK_ENABLED
__HAL_RCC_UART8_IS_CLK_ENABLED
__HAL_RCC_TIM2_IS_CLK_DISABLED
__HAL_RCC_TIM3_IS_CLK_DISABLED
__HAL_RCC_TIM4_IS_CLK_DISABLED
__HAL_RCC_SPI3_IS_CLK_DISABLED
__HAL_RCC_I2C3_IS_CLK_DISABLED
__HAL_RCC_TIM6_IS_CLK_DISABLED

DocID025834 Rev 4

659/964

HAL RCC Extension Driver
__HAL_RCC_TIM7_IS_CLK_DISABLED
__HAL_RCC_TIM12_IS_CLK_DISABLED
__HAL_RCC_TIM13_IS_CLK_DISABLED
__HAL_RCC_TIM14_IS_CLK_DISABLED
__HAL_RCC_USART3_IS_CLK_DISABLED
__HAL_RCC_UART4_IS_CLK_DISABLED
__HAL_RCC_UART5_IS_CLK_DISABLED
__HAL_RCC_CAN1_IS_CLK_DISABLED
__HAL_RCC_CAN2_IS_CLK_DISABLED
__HAL_RCC_DAC_IS_CLK_DISABLED
__HAL_RCC_UART7_IS_CLK_DISABLED
__HAL_RCC_UART8_IS_CLK_DISABLED
APB2 Peripheral Clock Enable Disable
__HAL_RCC_TIM8_CLK_ENABLE
__HAL_RCC_ADC2_CLK_ENABLE
__HAL_RCC_ADC3_CLK_ENABLE
__HAL_RCC_SPI5_CLK_ENABLE
__HAL_RCC_SPI6_CLK_ENABLE
__HAL_RCC_SAI1_CLK_ENABLE
__HAL_RCC_SDIO_CLK_ENABLE
__HAL_RCC_SPI4_CLK_ENABLE
__HAL_RCC_TIM10_CLK_ENABLE
__HAL_RCC_SDIO_CLK_DISABLE
__HAL_RCC_SPI4_CLK_DISABLE
__HAL_RCC_TIM10_CLK_DISABLE
__HAL_RCC_TIM8_CLK_DISABLE
__HAL_RCC_ADC2_CLK_DISABLE
__HAL_RCC_ADC3_CLK_DISABLE
__HAL_RCC_SPI5_CLK_DISABLE
__HAL_RCC_SPI6_CLK_DISABLE
__HAL_RCC_SAI1_CLK_DISABLE
__HAL_RCC_LTDC_CLK_ENABLE
__HAL_RCC_LTDC_CLK_DISABLE
__HAL_RCC_DSI_CLK_ENABLE
__HAL_RCC_DSI_CLK_DISABLE

660/964

DocID025834 Rev 4

UM1725

UM1725

HAL RCC Extension Driver
APB2 Force Release Reset
__HAL_RCC_TIM8_FORCE_RESET
__HAL_RCC_SPI5_FORCE_RESET
__HAL_RCC_SPI6_FORCE_RESET
__HAL_RCC_SAI1_FORCE_RESET
__HAL_RCC_SDIO_FORCE_RESET
__HAL_RCC_SPI4_FORCE_RESET
__HAL_RCC_TIM10_FORCE_RESET
__HAL_RCC_SDIO_RELEASE_RESET
__HAL_RCC_SPI4_RELEASE_RESET
__HAL_RCC_TIM10_RELEASE_RESET
__HAL_RCC_TIM8_RELEASE_RESET
__HAL_RCC_SPI5_RELEASE_RESET
__HAL_RCC_SPI6_RELEASE_RESET
__HAL_RCC_SAI1_RELEASE_RESET
__HAL_RCC_LTDC_FORCE_RESET
__HAL_RCC_LTDC_RELEASE_RESET
__HAL_RCC_DSI_FORCE_RESET
__HAL_RCC_DSI_RELEASE_RESET
APB2 Peripheral Low Power Enable Disable
__HAL_RCC_TIM8_CLK_SLEEP_ENABLE
__HAL_RCC_ADC2_CLK_SLEEP_ENABLE
__HAL_RCC_ADC3_CLK_SLEEP_ENABLE
__HAL_RCC_SPI5_CLK_SLEEP_ENABLE
__HAL_RCC_SPI6_CLK_SLEEP_ENABLE
__HAL_RCC_SAI1_CLK_SLEEP_ENABLE
__HAL_RCC_SDIO_CLK_SLEEP_ENABLE
__HAL_RCC_SPI4_CLK_SLEEP_ENABLE
__HAL_RCC_TIM10_CLK_SLEEP_ENABLE
__HAL_RCC_SDIO_CLK_SLEEP_DISABLE
__HAL_RCC_SPI4_CLK_SLEEP_DISABLE
__HAL_RCC_TIM10_CLK_SLEEP_DISABLE
__HAL_RCC_TIM8_CLK_SLEEP_DISABLE
__HAL_RCC_ADC2_CLK_SLEEP_DISABLE
__HAL_RCC_ADC3_CLK_SLEEP_DISABLE
__HAL_RCC_SPI5_CLK_SLEEP_DISABLE

DocID025834 Rev 4

661/964

HAL RCC Extension Driver
__HAL_RCC_SPI6_CLK_SLEEP_DISABLE
__HAL_RCC_SAI1_CLK_SLEEP_DISABLE
__HAL_RCC_LTDC_CLK_SLEEP_ENABLE
__HAL_RCC_LTDC_CLK_SLEEP_DISABLE
__HAL_RCC_DSI_CLK_SLEEP_ENABLE
__HAL_RCC_DSI_CLK_SLEEP_DISABLE
APB2 Peripheral Clock Enable Disable Status
__HAL_RCC_TIM8_IS_CLK_ENABLED
__HAL_RCC_ADC2_IS_CLK_ENABLED
__HAL_RCC_ADC3_IS_CLK_ENABLED
__HAL_RCC_SPI5_IS_CLK_ENABLED
__HAL_RCC_SPI6_IS_CLK_ENABLED
__HAL_RCC_SAI1_IS_CLK_ENABLED
__HAL_RCC_SDIO_IS_CLK_ENABLED
__HAL_RCC_SPI4_IS_CLK_ENABLED
__HAL_RCC_TIM10_IS_CLK_ENABLED
__HAL_RCC_SDIO_IS_CLK_DISABLED
__HAL_RCC_SPI4_IS_CLK_DISABLED
__HAL_RCC_TIM10_IS_CLK_DISABLED
__HAL_RCC_TIM8_IS_CLK_DISABLED
__HAL_RCC_ADC2_IS_CLK_DISABLED
__HAL_RCC_ADC3_IS_CLK_DISABLED
__HAL_RCC_SPI5_IS_CLK_DISABLED
__HAL_RCC_SPI6_IS_CLK_DISABLED
__HAL_RCC_SAI1_IS_CLK_DISABLED
__HAL_RCC_LTDC_IS_CLK_ENABLED
__HAL_RCC_LTDC_IS_CLK_DISABLED
__HAL_RCC_DSI_IS_CLK_ENABLED
__HAL_RCC_DSI_IS_CLK_DISABLED
RCC BitAddress AliasRegion
RCC_PLLSAION_BIT_NUMBER
RCC_CR_PLLSAION_BB
PLLSAI_TIMEOUT_VALUE
RCC_PLLI2SON_BIT_NUMBER
RCC_CR_PLLI2SON_BB
RCC_DCKCFGR_OFFSET

662/964

DocID025834 Rev 4

UM1725

UM1725

HAL RCC Extension Driver
RCC_TIMPRE_BIT_NUMBER
RCC_DCKCFGR_TIMPRE_BB
RCC_CFGR_OFFSET
RCC_I2SSRC_BIT_NUMBER
RCC_CFGR_I2SSRC_BB
PLLI2S_TIMEOUT_VALUE
PLL_TIMEOUT_VALUE
RCC CLK48 Clock Source
RCC_CLK48CLKSOURCE_PLLQ
RCC_CLK48CLKSOURCE_PLLSAIP
RCC DSI Clock Source
RCC_DSICLKSOURCE_DSIPHY
RCC_DSICLKSOURCE_PLLR
RCCEx Exported Macros
__HAL_RCC_PLL_CONFIG

Description:
Macro to configure the main PLL clock
source, multiplication and division factors.
Parameters:
__RCC_PLLSource__: specifies the PLL
entry clock source. This parameter can be
one of the following values:
RCC_PLLSOURCE_HSI: HSI
oscillator clock selected as PLL clock
entry
RCC_PLLSOURCE_HSE: HSE
oscillator clock selected as PLL clock
entry
__PLLM__: specifies the division factor for
PLL VCO input clock This parameter must
be a number between Min_Data = 2 and
Max_Data = 63.
__PLLN__: specifies the multiplication
factor for PLL VCO output clock This
parameter must be a number between
Min_Data = 50 and Max_Data = 432.
__PLLP__: specifies the division factor for
main system clock (SYSCLK) This
parameter must be a number in the range
{2, 4, 6, or 8}.
__PLLQ__: specifies the division factor for
OTG FS, SDIO and RNG clocks This
parameter must be a number between
Min_Data = 2 and Max_Data = 15.
__PLLR__: PLL division factor for I2S, SAI,
SYSTEM, SPDIFRX clocks. This
parameter must be a number between
DocID025834 Rev 4

663/964

HAL RCC Extension Driver

UM1725
Min_Data = 2 and Max_Data = 7.
Notes:
This function must be used only when the
main PLL is disabled.
This clock source (RCC_PLLSource) is
common for the main PLL and PLLI2S.
You have to set the PLLM parameter
correctly to ensure that the VCO input
frequency ranges from 1 to 2 MHz. It is
recommended to select a frequency of 2
MHz to limit PLL jitter.
You have to set the PLLN parameter
correctly to ensure that the VCO output
frequency is between 100 and 432 MHz.
If the USB OTG FS is used in your
application, you have to set the PLLQ
parameter correctly to have 48 MHz clock
for the USB. However, the SDIO and RNG
need a frequency lower than or equal to 48
MHz to work correctly.
This parameter is only available in
STM32F446xx/STM32F469xx/STM32F479
xx/
STM32F412Zx/STM32F412Vx/STM32F41
2Rx/STM32F412Cx devices.

__HAL_RCC_PLLI2S_ENABLE

Notes:
The PLLI2S is disabled by hardware when
entering STOP and STANDBY modes.

__HAL_RCC_PLLI2S_DISABLE
__HAL_RCC_PLLI2S_CONFIG

Description:
Macro to configure the PLLI2S clock
multiplication and division factors .
Parameters:
__PLLI2SN__: specifies the multiplication
factor for PLLI2S VCO output clock This
parameter must be a number between
Min_Data = 50 and Max_Data = 432.
__PLLI2SR__: specifies the division factor
for I2S clock This parameter must be a
number between Min_Data = 2 and
Max_Data = 7.
Notes:
This macro must be used only when the
PLLI2S is disabled. PLLI2S clock source is
common with the main PLL (configured in
HAL_RCC_ClockConfig() API).
You have to set the PLLI2SN parameter
correctly to ensure that the VCO output
frequency is between Min_Data = 100 and

664/964

DocID025834 Rev 4

UM1725

HAL RCC Extension Driver
Max_Data = 432 MHz.
You have to set the PLLI2SR parameter
correctly to not exceed 192 MHz on the I2S
clock frequency.
__HAL_RCC_PLLI2S_SAICLK_CONFI
G

Description:
Macro used by the SAI HAL driver to
configure the PLLI2S clock multiplication
and division factors.
Parameters:
__PLLI2SN__: specifies the multiplication
factor for PLLI2S VCO output clock. This
parameter must be a number between
Min_Data = 50 and Max_Data = 432.
__PLLI2SQ__: specifies the division factor
for SAI1 clock. This parameter must be a
number between Min_Data = 2 and
Max_Data = 15.
__PLLI2SR__: specifies the division factor
for I2S clock This parameter must be a
number between Min_Data = 2 and
Max_Data = 7.
Notes:
This macro must be used only when the
PLLI2S is disabled. PLLI2S clock source is
common with the main PLL (configured in
HAL_RCC_ClockConfig() API)
You have to set the PLLI2SN parameter
correctly to ensure that the VCO output
frequency is between Min_Data = 100 and
Max_Data = 432 MHz.
the PLLI2SQ parameter is only available
with
STM32F427xx/437xx/429xx/439xx/469xx/4
79xx Devices and can be configured using
the
__HAL_RCC_PLLI2S_PLLSAICLK_CONFI
G() macro
You have to set the PLLI2SR parameter
correctly to not exceed 192 MHz on the I2S
clock frequency.

__HAL_RCC_PLLSAI_ENABLE

Notes:
The PLLSAI is only available with
STM32F429x/439x Devices. The PLLSAI
is disabled by hardware when entering
STOP and STANDBY modes.

__HAL_RCC_PLLSAI_DISABLE
__HAL_RCC_PLLSAI_CONFIG

Description:
Macro to configure the PLLSAI clock
multiplication and division factors.

DocID025834 Rev 4

665/964

HAL RCC Extension Driver

UM1725
Parameters:
__PLLSAIN__: specifies the multiplication
factor for PLLSAI VCO output clock. This
parameter must be a number between
Min_Data = 50 and Max_Data = 432.
__PLLSAIP__: specifies division factor for
SDIO and CLK48 clocks. This parameter
must be a number in the range {2, 4, 6, or
8}.
__PLLSAIQ__: specifies the division factor
for SAI clock This parameter must be a
number between Min_Data = 2 and
Max_Data = 15.
__PLLSAIR__: specifies the division factor
for LTDC clock This parameter must be a
number between Min_Data = 2 and
Max_Data = 7.
Notes:
You have to set the PLLSAIN parameter
correctly to ensure that the VCO output
frequency is between Min_Data = 100 and
Max_Data = 432 MHz.

__HAL_RCC_PLLI2S_PLLSAICLKDIVQ
_CONFIG

Description:
Macro to configure the SAI clock Divider
coming from PLLI2S.
Parameters:
__PLLI2SDivQ__: specifies the PLLI2S
division factor for SAI1 clock. This
parameter must be a number between 1
and 32. SAI1 clock frequency = f(PLLI2SQ)
/ __PLLI2SDivQ__
Notes:
This function must be called before
enabling the PLLI2S.

__HAL_RCC_PLLSAI_PLLSAICLKDIV
Q_CONFIG

Description:
Macro to configure the SAI clock Divider
coming from PLLSAI.
Parameters:
__PLLSAIDivQ__: specifies the PLLSAI
division factor for SAI1 clock . This
parameter must be a number between
Min_Data = 1 and Max_Data = 32. SAI1
clock frequency = f(PLLSAIQ) /
__PLLSAIDivQ__
Notes:
This function must be called before
enabling the PLLSAI.

666/964

DocID025834 Rev 4

UM1725

HAL RCC Extension Driver
__HAL_RCC_PLLSAI_PLLSAICLKDIV
R_CONFIG

Description:
Macro to configure the LTDC clock Divider
coming from PLLSAI.
Parameters:
__PLLSAIDivR__: specifies the PLLSAI
division factor for LTDC clock . This
parameter must be a number between
Min_Data = 2 and Max_Data = 16. LTDC
clock frequency = f(PLLSAIR) /
__PLLSAIDivR__
Notes:
The LTDC peripheral is only available with
STM32F427/437/429/439/469/479xx
Devices. This function must be called
before enabling the PLLSAI.
Description:

__HAL_RCC_I2S_CONFIG

Macro to configure the I2S clock source
(I2SCLK).
Parameters:
__SOURCE__: specifies the I2S clock
source. This parameter can be one of the
following values:
RCC_I2SCLKSOURCE_PLLI2S:
PLLI2S clock used as I2S clock
source.
RCC_I2SCLKSOURCE_EXT:
External clock mapped on the
I2S_CKIN pin used as I2S clock
source.
Notes:
This function must be called before
enabling the I2S APB clock.
__HAL_RCC_SAI_BLOCKACLKSOUR
CE_CONFIG

Description:
Macro to configure SAI1BlockA clock
source selection.
Parameters:
__SOURCE__: specifies the SAI Block A
clock source. This parameter can be one of
the following values:
RCC_SAIACLKSOURCE_PLLI2S:
PLLI2S_Q clock divided by
PLLI2SDIVQ used as SAI1 Block A
clock.
RCC_SAIACLKSOURCE_PLLSAI:
PLLISAI_Q clock divided by
PLLSAIDIVQ used as SAI1 Block A
clock.

DocID025834 Rev 4

667/964

HAL RCC Extension Driver

UM1725
RCC_SAIACLKSOURCE_Ext:
External clock mapped on the
I2S_CKIN pin used as SAI1 Block A
clock.
Notes:
The SAI peripheral is only available with
STM32F427/437/429/439/469/479xx
Devices. This function must be called
before enabling PLLSAI, PLLI2S and the
SAI clock.

__HAL_RCC_SAI_BLOCKBCLKSOUR
CE_CONFIG

Description:
Macro to configure SAI1BlockB clock
source selection.
Parameters:
__SOURCE__: specifies the SAI Block B
clock source. This parameter can be one of
the following values:
RCC_SAIBCLKSOURCE_PLLI2S:
PLLI2S_Q clock divided by
PLLI2SDIVQ used as SAI1 Block B
clock.
RCC_SAIBCLKSOURCE_PLLSAI:
PLLISAI_Q clock divided by
PLLSAIDIVQ used as SAI1 Block B
clock.
RCC_SAIBCLKSOURCE_Ext:
External clock mapped on the
I2S_CKIN pin used as SAI1 Block B
clock.
Notes:
The SAI peripheral is only available with
STM32F427/437/429/439/469/479xx
Devices. This function must be called
before enabling PLLSAI, PLLI2S and the
SAI clock.

__HAL_RCC_CLK48_CONFIG

Description:
Macro to configure the CLK48 clock.
Parameters:
__SOURCE__: specifies the CLK48 clock
source. This parameter can be one of the
following values:
RCC_CLK48CLKSOURCE_PLLQ:
PLL VCO Output divided by PLLQ
used as CLK48 clock.
RCC_CLK48CLKSOURCE_PLLSAIP:
PLLSAI VCO Output divided by
PLLSAIP used as CLK48 clock.

668/964

DocID025834 Rev 4

UM1725

HAL RCC Extension Driver
__HAL_RCC_GET_CLK48_SOURCE

Description:
Macro to Get the CLK48 clock.
Return value:
The: clock source can be one of the
following values:
RCC_CLK48CLKSOURCE_PLLQ:
PLL VCO Output divided by PLLQ
used as CLK48 clock.
RCC_CLK48CLKSOURCE_PLLSAIP:
PLLSAI VCO Output divided by
PLLSAIP used as CLK48 clock.

__HAL_RCC_SDIO_CONFIG

Description:
Macro to configure the SDIO clock.
Parameters:
__SOURCE__: specifies the SDIO clock
source. This parameter can be one of the
following values:
RCC_SDIOCLKSOURCE_CLK48:
CLK48 output used as SDIO clock.
RCC_SDIOCLKSOURCE_SYSCLK:
System clock output used as SDIO
clock.

__HAL_RCC_GET_SDIO_SOURCE

Description:
Macro to Get the SDIO clock.
Return value:
The: clock source can be one of the
following values:
RCC_SDIOCLKSOURCE_CLK48:
CLK48 output used as SDIO clock.
RCC_SDIOCLKSOURCE_SYSCLK:
System clock output used as SDIO
clock.

__HAL_RCC_DSI_CONFIG

Description:
Macro to configure the DSI clock.
Parameters:
__SOURCE__: specifies the DSI clock
source. This parameter can be one of the
following values:
RCC_DSICLKSOURCE_PLLR: PLLR
output used as DSI clock.
RCC_DSICLKSOURCE_DSIPHY:
DSI-PHY output used as DSI clock.

DocID025834 Rev 4

669/964

HAL RCC Extension Driver
__HAL_RCC_GET_DSI_SOURCE

UM1725
Description:
Macro to Get the DSI clock.
Return value:
The: clock source can be one of the
following values:
RCC_DSICLKSOURCE_PLLR: PLLR
output used as DSI clock.
RCC_DSICLKSOURCE_DSIPHY: DSIPHY output used as DSI clock.

__HAL_RCC_TIMCLKPRESCALER

Description:
Macro to configure the Timers clocks
prescalers.
Parameters:
__PRESC__: : specifies the Timers clocks
prescalers selection This parameter can be
one of the following values:
RCC_TIMPRES_DESACTIVATED: The
Timers kernels clocks prescaler is equal
to HPRE if PPREx is corresponding to
division by 1 or 2, else it is equal to
[(HPRE * PPREx) / 2] if PPREx is
corresponding to division by 4 or more.
RCC_TIMPRES_ACTIVATED: The
Timers kernels clocks prescaler is equal
to HPRE if PPREx is corresponding to
division by 1, 2 or 4, else it is equal to
[(HPRE * PPREx) / 4] if PPREx is
corresponding to division by 8 or more.
Notes:
This feature is only available with
STM32F429x/439x Devices.

__HAL_RCC_PLLSAI_ENABLE_IT
__HAL_RCC_PLLSAI_DISABLE_IT
__HAL_RCC_PLLSAI_CLEAR_IT
__HAL_RCC_PLLSAI_GET_IT

Description:
Check the PLLSAI RDY interrupt has
occurred or not.
Return value:
The: new state (TRUE or FALSE).

__HAL_RCC_PLLSAI_GET_FLAG

Description:
Check PLLSAI RDY flag is set or not.
Return value:
The: new state (TRUE or FALSE).

670/964

DocID025834 Rev 4

UM1725

HAL RCC Extension Driver
I2S Clock Source
RCC_I2SCLKSOURCE_PLLI2S
RCC_I2SCLKSOURCE_EXT
RCC Private macros to check input parameters
IS_RCC_PLLN_VALUE
IS_RCC_PLLI2SN_VALUE
IS_RCC_PERIPHCLOCK
IS_RCC_PLLI2SR_VALUE
IS_RCC_PLLI2SQ_VALUE
IS_RCC_PLLSAIN_VALUE
IS_RCC_PLLSAIQ_VALUE
IS_RCC_PLLSAIR_VALUE
IS_RCC_PLLSAI_DIVQ_VALUE
IS_RCC_PLLI2S_DIVQ_VALUE
IS_RCC_PLLSAI_DIVR_VALUE
IS_RCC_PLLR_VALUE
IS_RCC_PLLSAIP_VALUE
IS_RCC_CLK48CLKSOURCE
IS_RCC_SDIOCLKSOURCE
IS_RCC_DSIBYTELANECLKSOURCE
IS_RCC_LSE_MODE
IS_RCC_MCO2SOURCE
RCC LSE Dual Mode Selection
RCC_LSE_LOWPOWER_MODE
RCC_LSE_HIGHDRIVE_MODE
RCC Extended MCOx Clock Config
__HAL_RCC_MCO1_CONFIG

Description:
Macro to configure the MCO1 clock.
Parameters:
__MCOCLKSOURCE__: specifies the MCO clock
source. This parameter can be one of the following
values:
RCC_MCO1SOURCE_HSI: HSI clock selected
as MCO1 source
RCC_MCO1SOURCE_LSE: LSE clock selected
as MCO1 source
RCC_MCO1SOURCE_HSE: HSE clock
selected as MCO1 source
RCC_MCO1SOURCE_PLLCLK: main PLL
clock selected as MCO1 source

DocID025834 Rev 4

671/964

HAL RCC Extension Driver

UM1725
__MCODIV__: specifies the MCO clock prescaler.
This parameter can be one of the following values:
RCC_MCODIV_1: no division applied to MCOx
clock
RCC_MCODIV_2: division by 2 applied to
MCOx clock
RCC_MCODIV_3: division by 3 applied to
MCOx clock
RCC_MCODIV_4: division by 4 applied to
MCOx clock
RCC_MCODIV_5: division by 5 applied to
MCOx clock

__HAL_RCC_MCO2_CONFIG

Description:
Macro to configure the MCO2 clock.
Parameters:
__MCOCLKSOURCE__: specifies the MCO clock
source. This parameter can be one of the following
values:
RCC_MCO2SOURCE_SYSCLK: System clock
(SYSCLK) selected as MCO2 source
RCC_MCO2SOURCE_PLLI2SCLK: PLLI2S
clock selected as MCO2 source, available for all
STM32F4 devices except STM32F410xx
RCC_MCO2SOURCE_I2SCLK: I2SCLK clock
selected as MCO2 source, available only for
STM32F410Rx devices
RCC_MCO2SOURCE_HSE: HSE clock
selected as MCO2 source
RCC_MCO2SOURCE_PLLCLK: main PLL
clock selected as MCO2 source
__MCODIV__: specifies the MCO clock prescaler.
This parameter can be one of the following values:
RCC_MCODIV_1: no division applied to MCOx
clock
RCC_MCODIV_2: division by 2 applied to
MCOx clock
RCC_MCODIV_3: division by 3 applied to
MCOx clock
RCC_MCODIV_4: division by 4 applied to
MCOx clock
RCC_MCODIV_5: division by 5 applied to
MCOx clock
Notes:
For STM32F410Rx devices, to output I2SCLK clock
on MCO2, you should have at least one of the SPI
clocks enabled (SPI1, SPI2 or SPI5).

672/964

DocID025834 Rev 4

UM1725

HAL RCC Extension Driver
RCC Periph Clock Selection
RCC_PERIPHCLK_I2S
RCC_PERIPHCLK_SAI_PLLI2S
RCC_PERIPHCLK_SAI_PLLSAI
RCC_PERIPHCLK_LTDC
RCC_PERIPHCLK_TIM
RCC_PERIPHCLK_RTC
RCC_PERIPHCLK_PLLI2S
RCC_PERIPHCLK_CLK48
RCC_PERIPHCLK_SDIO
RCC PLLSAIP Clock Divider
RCC_PLLSAIP_DIV2
RCC_PLLSAIP_DIV4
RCC_PLLSAIP_DIV6
RCC_PLLSAIP_DIV8
RCC PLLSAI DIVR
RCC_PLLSAIDIVR_2
RCC_PLLSAIDIVR_4
RCC_PLLSAIDIVR_8
RCC_PLLSAIDIVR_16
RCC SAI BlockA Clock Source
RCC_SAIACLKSOURCE_PLLSAI
RCC_SAIACLKSOURCE_PLLI2S
RCC_SAIACLKSOURCE_EXT
RCC SAI BlockB Clock Source
RCC_SAIBCLKSOURCE_PLLSAI
RCC_SAIBCLKSOURCE_PLLI2S
RCC_SAIBCLKSOURCE_EXT
RCC SDIO Clock Source
RCC_SDIOCLKSOURCE_CLK48
RCC_SDIOCLKSOURCE_SYSCLK
RCC TIM PRescaler Selection
RCC_TIMPRES_DESACTIVATED
RCC_TIMPRES_ACTIVATED

DocID025834 Rev 4

673/964

HAL RNG Generic Driver

UM1725

51

HAL RNG Generic Driver

51.1

RNG Firmware driver registers structures

51.1.1

RNG_HandleTypeDef
Data Fields
RNG_TypeDef * Instance
HAL_LockTypeDef Lock
__IO HAL_RNG_StateTypeDef State
uint32_t RandomNumber

Field Documentation
RNG_TypeDef* RNG_HandleTypeDef::Instance
Register base address
HAL_LockTypeDef RNG_HandleTypeDef::Lock
RNG locking object
__IO HAL_RNG_StateTypeDef RNG_HandleTypeDef::State
RNG communication state
uint32_t RNG_HandleTypeDef::RandomNumber
Last Generated RNG Data

51.2

RNG Firmware driver API description

51.2.1

How to use this driver
The RNG HAL driver can be used as follows:
1.
2.
3.
4.

51.2.2

Enable the RNG controller clock using __HAL_RCC_RNG_CLK_ENABLE() macro in
HAL_RNG_MspInit().
Activate the RNG peripheral using HAL_RNG_Init() function.
Wait until the 32 bit Random Number Generator contains a valid random data using
(polling/interrupt) mode.
Get the 32 bit random number using HAL_RNG_GenerateRandomNumber() function.

Initialization and de-initialization functions
This section provides functions allowing to:
Initialize the RNG according to the specified parameters in the RNG_InitTypeDef and
create the associated handle
DeInitialize the RNG peripheral
Initialize the RNG MSP
DeInitialize RNG MSP
This section contains the following APIs:
HAL_RNG_Init()
HAL_RNG_DeInit()

674/964

DocID025834 Rev 4

UM1725

HAL RNG Generic Driver
HAL_RNG_MspInit()
HAL_RNG_MspDeInit()

51.2.3

Peripheral Control functions
This section provides functions allowing to:
Get the 32 bit Random number
Get the 32 bit Random number with interrupt enabled
Handle RNG interrupt request
This section contains the following APIs:
HAL_RNG_GenerateRandomNumber()
HAL_RNG_GenerateRandomNumber_IT()
HAL_RNG_IRQHandler()
HAL_RNG_GetRandomNumber()
HAL_RNG_GetRandomNumber_IT()
HAL_RNG_ReadLastRandomNumber()
HAL_RNG_ReadyDataCallback()
HAL_RNG_ErrorCallback()

51.2.4

Peripheral State functions
This subsection permits to get in run-time the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_RNG_GetState()

51.2.5

Detailed description of functions
HAL_RNG_Init
Function Name

HAL_StatusTypeDef HAL_RNG_Init (RNG_HandleTypeDef *
hrng)

Function Description

Initializes the RNG peripheral and creates the associated handle.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.

Return values

HAL: status

HAL_RNG_DeInit
Function Name

HAL_StatusTypeDef HAL_RNG_DeInit (RNG_HandleTypeDef *
hrng)

Function Description

DeInitializes the RNG peripheral.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.

Return values

HAL: status

HAL_RNG_MspInit
Function Name

void HAL_RNG_MspInit (RNG_HandleTypeDef * hrng)

DocID025834 Rev 4

675/964

HAL RNG Generic Driver
Function Description

UM1725
Initializes the RNG MSP.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.

Return values

None

HAL_RNG_MspDeInit
Function Name

void HAL_RNG_MspDeInit (RNG_HandleTypeDef * hrng)

Function Description

DeInitializes the RNG MSP.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.

Return values

None

HAL_RNG_GetRandomNumber
Function Name

uint32_t HAL_RNG_GetRandomNumber (RNG_HandleTypeDef
* hrng)

Function Description

Returns generated random number in polling mode (Obsolete)
Use HAL_RNG_GenerateRandomNumber() API instead.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.

Return values

Random: value

HAL_RNG_GetRandomNumber_IT
Function Name

uint32_t HAL_RNG_GetRandomNumber_IT
(RNG_HandleTypeDef * hrng)

Function Description

Returns a 32-bit random number with interrupt enabled (Obsolete),
Use HAL_RNG_GenerateRandomNumber_IT() API instead.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.

Return values

32-bit: random number

HAL_RNG_GenerateRandomNumber

676/964

Function Name

HAL_StatusTypeDef HAL_RNG_GenerateRandomNumber
(RNG_HandleTypeDef * hrng, uint32_t * random32bit)

Function Description

Generates a 32-bit random number.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.
random32bit: pointer to generated random number variable
if successful.

Return values

HAL: status

Notes

Each time the random number data is read the
RNG_FLAG_DRDY flag is automatically cleared.

DocID025834 Rev 4

UM1725

HAL RNG Generic Driver

HAL_RNG_GenerateRandomNumber_IT
Function Name

HAL_StatusTypeDef HAL_RNG_GenerateRandomNumber_IT
(RNG_HandleTypeDef * hrng)

Function Description

Generates a 32-bit random number in interrupt mode.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.

Return values

HAL: status

HAL_RNG_ReadLastRandomNumber
Function Name

uint32_t HAL_RNG_ReadLastRandomNumber
(RNG_HandleTypeDef * hrng)

Function Description

Read latest generated random number.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.

Return values

random: value

HAL_RNG_IRQHandler
Function Name

void HAL_RNG_IRQHandler (RNG_HandleTypeDef * hrng)

Function Description

Handles RNG interrupt request.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.

Return values

None

Notes

In the case of a clock error, the RNG is no more able to
generate random numbers because the PLL48CLK clock is
not correct. User has to check that the clock controller is
correctly configured to provide the RNG clock and clear the
CEIS bit using __HAL_RNG_CLEAR_IT(). The clock error
has no impact on the previously generated random numbers,
and the RNG_DR register contents can be used.
In the case of a seed error, the generation of random
numbers is interrupted as long as the SECS bit is '1'. If a
number is available in the RNG_DR register, it must not be
used because it may not have enough entropy. In this case, it
is recommended to clear the SEIS bit using
__HAL_RNG_CLEAR_IT(), then disable and enable the RNG
peripheral to reinitialize and restart the RNG.
User-written HAL_RNG_ErrorCallback() API is called once
whether SEIS or CEIS are set.

HAL_RNG_ErrorCallback
Function Name

void HAL_RNG_ErrorCallback (RNG_HandleTypeDef * hrng)

Function Description

RNG error callbacks.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.
DocID025834 Rev 4

677/964

HAL RNG Generic Driver
Return values

UM1725
None

HAL_RNG_ReadyDataCallback
Function Name

void HAL_RNG_ReadyDataCallback (RNG_HandleTypeDef *
hrng, uint32_t random32bit)

Function Description

Data Ready callback in non-blocking mode.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.
random32bit: generated random number.

Return values

None

HAL_RNG_GetState
Function Name

HAL_RNG_StateTypeDef HAL_RNG_GetState
(RNG_HandleTypeDef * hrng)

Function Description

Returns the RNG state.

Parameters

hrng: pointer to a RNG_HandleTypeDef structure that
contains the configuration information for RNG.

Return values

HAL: state

51.3

RNG Firmware driver defines

51.3.1

RNG
RNG Interrupt definition
RNG_IT_DRDY

Data Ready interrupt

RNG_IT_CEI

Clock error interrupt

RNG_IT_SEI

Seed error interrupt

RNG Flag definition
RNG_FLAG_DRDY

Data ready

RNG_FLAG_CECS

Clock error current status

RNG_FLAG_SECS

Seed error current status

RNG Exported Macros
__HAL_RNG_RESET_HANDLE_STATE

Description:
Reset RNG handle state.
Parameters:
__HANDLE__: RNG Handle
Return value:
None

__HAL_RNG_ENABLE

Description:
Enables the RNG peripheral.

678/964

DocID025834 Rev 4

UM1725

HAL RNG Generic Driver
Parameters:
__HANDLE__: RNG Handle
Return value:
None
Description:

__HAL_RNG_DISABLE

Disables the RNG peripheral.
Parameters:
__HANDLE__: RNG Handle
Return value:
None
Description:

__HAL_RNG_GET_FLAG

Check the selected RNG flag status.
Parameters:
__HANDLE__: RNG Handle
__FLAG__: RNG flag This parameter can
be one of the following values:
RNG_FLAG_DRDY: Data ready
RNG_FLAG_CECS: Clock error
current status
RNG_FLAG_SECS: Seed error
current status
Return value:
The: new state of __FLAG__ (SET or
RESET).
__HAL_RNG_CLEAR_FLAG

Description:
Clears the selected RNG flag status.
Parameters:
__HANDLE__: RNG handle
__FLAG__: RNG flag to clear
Return value:
None
Notes:
WARNING: This is a dummy macro for
HAL code alignment, flags
RNG_FLAG_DRDY, RNG_FLAG_CECS
and RNG_FLAG_SECS are read-only.

__HAL_RNG_ENABLE_IT

Description:
Enables the RNG interrupts.
Parameters:
__HANDLE__: RNG Handle
DocID025834 Rev 4

679/964

HAL RNG Generic Driver

UM1725
Return value:
None

__HAL_RNG_DISABLE_IT

Description:
Disables the RNG interrupts.
Parameters:
__HANDLE__: RNG Handle
Return value:
None

__HAL_RNG_GET_IT

Description:
Checks whether the specified RNG
interrupt has occurred or not.
Parameters:
__HANDLE__: RNG Handle
__INTERRUPT__: specifies the RNG
interrupt status flag to check. This
parameter can be one of the following
values:
RNG_IT_DRDY: Data ready interrupt
RNG_IT_CEI: Clock error interrupt
RNG_IT_SEI: Seed error interrupt
Return value:
The: new state of __INTERRUPT__ (SET
or RESET).

__HAL_RNG_CLEAR_IT

Description:
Clear the RNG interrupt status flags.
Parameters:
__HANDLE__: RNG Handle
__INTERRUPT__: specifies the RNG
interrupt status flag to clear. This
parameter can be one of the following
values:
RNG_IT_CEI: Clock error interrupt
RNG_IT_SEI: Seed error interrupt
Return value:
None
Notes:
RNG_IT_DRDY flag is read-only, reading
RNG_DR register automatically clears
RNG_IT_DRDY.

680/964

DocID025834 Rev 4

UM1725

HAL RTC Generic Driver

52

HAL RTC Generic Driver

52.1

RTC Firmware driver registers structures

52.1.1

RTC_InitTypeDef
Data Fields
uint32_t HourFormat
uint32_t AsynchPrediv
uint32_t SynchPrediv
uint32_t OutPut
uint32_t OutPutPolarity
uint32_t OutPutType

Field Documentation
uint32_t RTC_InitTypeDef::HourFormat
Specifies the RTC Hour Format. This parameter can be a value of
RTC_Hour_Formats
uint32_t RTC_InitTypeDef::AsynchPrediv
Specifies the RTC Asynchronous Predivider value. This parameter must be a number
between Min_Data = 0x00 and Max_Data = 0x7F
uint32_t RTC_InitTypeDef::SynchPrediv
Specifies the RTC Synchronous Predivider value. This parameter must be a number
between Min_Data = 0x00 and Max_Data = 0x7FFFU
uint32_t RTC_InitTypeDef::OutPut
Specifies which signal will be routed to the RTC output. This parameter can be a
value of RTC_Output_selection_Definitions
uint32_t RTC_InitTypeDef::OutPutPolarity
Specifies the polarity of the output signal. This parameter can be a value of
RTC_Output_Polarity_Definitions
uint32_t RTC_InitTypeDef::OutPutType
Specifies the RTC Output Pin mode. This parameter can be a value of
RTC_Output_Type_ALARM_OUT

52.1.2

RTC_TimeTypeDef
Data Fields
uint8_t Hours
uint8_t Minutes
uint8_t Seconds
uint8_t TimeFormat
uint32_t SubSeconds
uint32_t SecondFraction
uint32_t DayLightSaving
uint32_t StoreOperation
DocID025834 Rev 4

681/964

HAL RTC Generic Driver

UM1725

Field Documentation
uint8_t RTC_TimeTypeDef::Hours
Specifies the RTC Time Hour. This parameter must be a number between Min_Data
= 0 and Max_Data = 12 if the RTC_HourFormat_12 is selected. This parameter must
be a number between Min_Data = 0 and Max_Data = 23 if the RTC_HourFormat_24
is selected
uint8_t RTC_TimeTypeDef::Minutes
Specifies the RTC Time Minutes. This parameter must be a number between
Min_Data = 0 and Max_Data = 59
uint8_t RTC_TimeTypeDef::Seconds
Specifies the RTC Time Seconds. This parameter must be a number between
Min_Data = 0 and Max_Data = 59
uint8_t RTC_TimeTypeDef::TimeFormat
Specifies the RTC AM/PM Time. This parameter can be a value of
RTC_AM_PM_Definitions
uint32_t RTC_TimeTypeDef::SubSeconds
Specifies the RTC_SSR RTC Sub Second register content. This parameter
corresponds to a time unit range between [0-1] Second with [1 Sec / SecondFraction
+1] granularity
uint32_t RTC_TimeTypeDef::SecondFraction
Specifies the range or granularity of Sub Second register content corresponding to
Synchronous pre-scaler factor value (PREDIV_S) This parameter corresponds to a
time unit range between [0-1] Second with [1 Sec / SecondFraction +1] granularity.
This field will be used only by HAL_RTC_GetTime function
uint32_t RTC_TimeTypeDef::DayLightSaving
Specifies DayLight Save Operation. This parameter can be a value of
RTC_DayLightSaving_Definitions
uint32_t RTC_TimeTypeDef::StoreOperation
Specifies RTC_StoreOperation value to be written in the BCK bit in CR register to
store the operation. This parameter can be a value of
RTC_StoreOperation_Definitions

52.1.3

RTC_DateTypeDef
Data Fields
uint8_t WeekDay
uint8_t Month
uint8_t Date
uint8_t Year

Field Documentation
uint8_t RTC_DateTypeDef::WeekDay
Specifies the RTC Date WeekDay. This parameter can be a value of
RTC_WeekDay_Definitions
uint8_t RTC_DateTypeDef::Month
Specifies the RTC Date Month (in BCD format). This parameter can be a value of
RTC_Month_Date_Definitions

682/964

DocID025834 Rev 4

UM1725

HAL RTC Generic Driver
uint8_t RTC_DateTypeDef::Date
Specifies the RTC Date. This parameter must be a number between Min_Data = 1
and Max_Data = 31
uint8_t RTC_DateTypeDef::Year
Specifies the RTC Date Year. This parameter must be a number between Min_Data =
0 and Max_Data = 99

52.1.4

RTC_AlarmTypeDef
Data Fields
RTC_TimeTypeDef AlarmTime
uint32_t AlarmMask
uint32_t AlarmSubSecondMask
uint32_t AlarmDateWeekDaySel
uint8_t AlarmDateWeekDay
uint32_t Alarm

Field Documentation
RTC_TimeTypeDef RTC_AlarmTypeDef::AlarmTime
Specifies the RTC Alarm Time members
uint32_t RTC_AlarmTypeDef::AlarmMask
Specifies the RTC Alarm Masks. This parameter can be a value of
RTC_AlarmMask_Definitions
uint32_t RTC_AlarmTypeDef::AlarmSubSecondMask
Specifies the RTC Alarm SubSeconds Masks. This parameter can be a value of
RTC_Alarm_Sub_Seconds_Masks_Definitions
uint32_t RTC_AlarmTypeDef::AlarmDateWeekDaySel
Specifies the RTC Alarm is on Date or WeekDay. This parameter can be a value of
RTC_AlarmDateWeekDay_Definitions
uint8_t RTC_AlarmTypeDef::AlarmDateWeekDay
Specifies the RTC Alarm Date/WeekDay. If the Alarm Date is selected, this parameter
must be set to a value in the 1-31 range. If the Alarm WeekDay is selected, this
parameter can be a value of RTC_WeekDay_Definitions
uint32_t RTC_AlarmTypeDef::Alarm
Specifies the alarm . This parameter can be a value of RTC_Alarms_Definitions

52.1.5

RTC_HandleTypeDef
Data Fields
RTC_TypeDef * Instance
RTC_InitTypeDef Init
HAL_LockTypeDef Lock
__IO HAL_RTCStateTypeDef State

DocID025834 Rev 4

683/964

HAL RTC Generic Driver

UM1725

Field Documentation
RTC_TypeDef* RTC_HandleTypeDef::Instance
Register base address
RTC_InitTypeDef RTC_HandleTypeDef::Init
RTC required parameters
HAL_LockTypeDef RTC_HandleTypeDef::Lock
RTC locking object
__IO HAL_RTCStateTypeDef RTC_HandleTypeDef::State
Time communication state

52.2

RTC Firmware driver API description

52.2.1

Backup Domain Operating Condition
The real-time clock (RTC), the RTC backup registers, and the backup SRAM (BKP SRAM)
can be powered from the VBAT voltage when the main VDD supply is powered off. To
retain the content of the RTC backup registers, backup SRAM, and supply the RTC when
VDD is turned off, VBAT pin can be connected to an optional standby voltage supplied by a
battery or by another source.
To allow the RTC operating even when the main digital supply (VDD) is turned off, the
VBAT pin powers the following blocks:
1.
2.
3.
4.

The RTC
The LSE oscillator
The backup SRAM when the low power backup regulator is enabled
PC13 to PC15 I/Os, plus PI8 I/O (when available)

When the backup domain is supplied by VDD (analog switch connected to VDD), the
following pins are available:
1.
2.
3.

PC14 and PC15 can be used as either GPIO or LSE pins
PC13 can be used as a GPIO or as the RTC_AF1 pin
PI8 can be used as a GPIO or as the RTC_AF2 pin

When the backup domain is supplied by VBAT (analog switch connected to VBAT
because VDD is not present), the following pins are available:
1.
2.
3.

52.2.2

PC14 and PC15 can be used as LSE pins only
PC13 can be used as the RTC_AF1 pin
PI8 can be used as the RTC_AF2 pin

Backup Domain Reset
The backup domain reset sets all RTC registers and the RCC_BDCR register to their reset
values. The BKPSRAM is not affected by this reset. The only way to reset the BKPSRAM is
through the Flash interface by requesting a protection level change from 1 to 0.
A backup domain reset is generated when one of the following events occurs:
1.
2.

684/964

Software reset, triggered by setting the BDRST bit in the RCC Backup domain control
register (RCC_BDCR).
VDD or VBAT power on, if both supplies have previously been powered off.

DocID025834 Rev 4

UM1725

52.2.3

HAL RTC Generic Driver

Backup Domain Access
After reset, the backup domain (RTC registers, RTC backup data registers and backup
SRAM) is protected against possible unwanted write accesses.
To enable access to the RTC Domain and RTC registers, proceed as follows:
Enable the Power Controller (PWR) APB1 interface clock using the
__HAL_RCC_PWR_CLK_ENABLE() function.
Enable access to RTC domain using the HAL_PWR_EnableBkUpAccess() function.
Select the RTC clock source using the __HAL_RCC_RTC_CONFIG() function.
Enable RTC Clock using the __HAL_RCC_RTC_ENABLE() function.

52.2.4

How to use this driver
Enable the RTC domain access (see description in the section above).
Configure the RTC Prescaler (Asynchronous and Synchronous) and RTC hour format
using the HAL_RTC_Init() function.

Time and Date configuration
To configure the RTC Calendar (Time and Date) use the HAL_RTC_SetTime() and
HAL_RTC_SetDate() functions.
To read the RTC Calendar, use the HAL_RTC_GetTime() and HAL_RTC_GetDate()
functions.

Alarm configuration
To configure the RTC Alarm use the HAL_RTC_SetAlarm() function. You can also
configure the RTC Alarm with interrupt mode using the HAL_RTC_SetAlarm_IT()
function.
To read the RTC Alarm, use the HAL_RTC_GetAlarm() function.

52.2.5

RTC and low power modes
The MCU can be woken up from a low power mode by an RTC alternate function.
The RTC alternate functions are the RTC alarms (Alarm A and Alarm B), RTC wake-up,
RTC tamper event detection and RTC time stamp event detection. These RTC alternate
functions can wake up the system from the Stop and Standby low power modes.
The system can also wake up from low power modes without depending on an external
interrupt (Auto-wake-up mode), by using the RTC alarm or the RTC wake-up events.
The RTC provides a programmable time base for waking up from the Stop or Standby
mode at regular intervals. Wake-up from STOP and STANDBY modes is possible only
when the RTC clock source is LSE or LSI.

52.2.6

Initialization and de-initialization functions
This section provides functions allowing to initialize and configure the RTC Prescaler
(Synchronous and Asynchronous), RTC Hour format, disable RTC registers Write
protection, enter and exit the RTC initialization mode, RTC registers synchronization check
and reference clock detection enable.

DocID025834 Rev 4

685/964

HAL RTC Generic Driver
UM1725
1.
The RTC Prescaler is programmed to generate the RTC 1Hz time base. It is split into
2 programmable prescalers to minimize power consumption.
A 7-bit asynchronous prescaler and a 13-bit synchronous prescaler.
When both prescalers are used, it is recommended to configure the
asynchronous prescaler to a high value to minimize power consumption.
2.
All RTC registers are Write protected. Writing to the RTC registers is enabled by
writing a key into the Write Protection register, RTC_WPR.
3.
To configure the RTC Calendar, user application should enter initialization mode. In
this mode, the calendar counter is stopped and its value can be updated. When the
initialization sequence is complete, the calendar restarts counting after 4 RTCCLK
cycles.
4.
To read the calendar through the shadow registers after Calendar initialization,
calendar update or after wake-up from low power modes the software must first clear
the RSF flag. The software must then wait until it is set again before reading the
calendar, which means that the calendar registers have been correctly copied into the
RTC_TR and RTC_DR shadow registers.The HAL_RTC_WaitForSynchro() function
implements the above software sequence (RSF clear and RSF check).
This section contains the following APIs:
HAL_RTC_Init()
HAL_RTC_DeInit()
HAL_RTC_MspInit()
HAL_RTC_MspDeInit()

52.2.7

RTC Time and Date functions
This section provides functions allowing to configure Time and Date features
This section contains the following APIs:
HAL_RTC_SetTime()
HAL_RTC_GetTime()
HAL_RTC_SetDate()
HAL_RTC_GetDate()

52.2.8

RTC Alarm functions
This section provides functions allowing to configure Alarm feature
This section contains the following APIs:
HAL_RTC_SetAlarm()
HAL_RTC_SetAlarm_IT()
HAL_RTC_DeactivateAlarm()
HAL_RTC_GetAlarm()
HAL_RTC_AlarmIRQHandler()
HAL_RTC_AlarmAEventCallback()
HAL_RTC_PollForAlarmAEvent()

52.2.9

Peripheral Control functions
This subsection provides functions allowing to
Wait for RTC Time and Date Synchronization
This section contains the following APIs:
HAL_RTC_WaitForSynchro()

686/964

DocID025834 Rev 4

UM1725

52.2.10

HAL RTC Generic Driver

Peripheral State functions
This subsection provides functions allowing to
Get RTC state
This section contains the following APIs:
HAL_RTC_GetState()

52.2.11

Detailed description of functions
HAL_RTC_Init
Function Name

HAL_StatusTypeDef HAL_RTC_Init (RTC_HandleTypeDef *
hrtc)

Function Description

Initializes the RTC peripheral.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

HAL_RTC_DeInit
Function Name

HAL_StatusTypeDef HAL_RTC_DeInit (RTC_HandleTypeDef *
hrtc)

Function Description

DeInitializes the RTC peripheral.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

Notes

This function doesn't reset the RTC Backup Data registers.

HAL_RTC_MspInit
Function Name

void HAL_RTC_MspInit (RTC_HandleTypeDef * hrtc)

Function Description

Initializes the RTC MSP.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

None

HAL_RTC_MspDeInit
Function Name

void HAL_RTC_MspDeInit (RTC_HandleTypeDef * hrtc)

Function Description

DeInitializes the RTC MSP.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

None

DocID025834 Rev 4

687/964

HAL RTC Generic Driver

UM1725

HAL_RTC_SetTime
Function Name

HAL_StatusTypeDef HAL_RTC_SetTime (RTC_HandleTypeDef
* hrtc, RTC_TimeTypeDef * sTime, uint32_t Format)

Function Description

Sets RTC current time.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
sTime: Pointer to Time structure
Format: Specifies the format of the entered parameters. This
parameter can be one of the following values:
RTC_FORMAT_BIN: Binary data format
RTC_FORMAT_BCD: BCD data format

Return values

HAL: status

HAL_RTC_GetTime
Function Name

HAL_StatusTypeDef HAL_RTC_GetTime (RTC_HandleTypeDef
* hrtc, RTC_TimeTypeDef * sTime, uint32_t Format)

Function Description

Gets RTC current time.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
sTime: Pointer to Time structure
Format: Specifies the format of the entered parameters. This
parameter can be one of the following values:
RTC_FORMAT_BIN: Binary data format
RTC_FORMAT_BCD: BCD data format

Return values

HAL: status

Notes

You can use SubSeconds and SecondFraction (sTime
structure fields returned) to convert SubSeconds value in
second fraction ratio with time unit following generic formula:
Second fraction ratio * time_unit= [(SecondFractionSubSeconds)/(SecondFraction+1)] * time_unit This
conversion can be performed only if no shift operation is
pending (ie. SHFP=0) when PREDIV_S >= SS
You must call HAL_RTC_GetDate() after
HAL_RTC_GetTime() to unlock the values in the higher-order
calendar shadow registers to ensure consistency between the
time and date values. Reading RTC current time locks the
values in calendar shadow registers until current date is read.

HAL_RTC_SetDate
Function Name

HAL_StatusTypeDef HAL_RTC_SetDate (RTC_HandleTypeDef
* hrtc, RTC_DateTypeDef * sDate, uint32_t Format)

Function Description

Sets RTC current date.

Parameters

688/964

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
sDate: Pointer to date structure
Format: specifies the format of the entered parameters. This
parameter can be one of the following values:
DocID025834 Rev 4

UM1725

HAL RTC Generic Driver
RTC_FORMAT_BIN: Binary data format
RTC_FORMAT_BCD: BCD data format
Return values

HAL: status

HAL_RTC_GetDate
Function Name

HAL_StatusTypeDef HAL_RTC_GetDate (RTC_HandleTypeDef
* hrtc, RTC_DateTypeDef * sDate, uint32_t Format)

Function Description

Gets RTC current date.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
sDate: Pointer to Date structure
Format: Specifies the format of the entered parameters. This
parameter can be one of the following values:
RTC_FORMAT_BIN: Binary data format
RTC_FORMAT_BCD: BCD data format

Return values

HAL: status

Notes

You must call HAL_RTC_GetDate() after
HAL_RTC_GetTime() to unlock the values in the higher-order
calendar shadow registers to ensure consistency between the
time and date values. Reading RTC current time locks the
values in calendar shadow registers until Current date is read.

HAL_RTC_SetAlarm
Function Name

HAL_StatusTypeDef HAL_RTC_SetAlarm
(RTC_HandleTypeDef * hrtc, RTC_AlarmTypeDef * sAlarm,
uint32_t Format)

Function Description

Sets the specified RTC Alarm.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
sAlarm: Pointer to Alarm structure
Format: Specifies the format of the entered parameters. This
parameter can be one of the following values:
RTC_FORMAT_BIN: Binary data format
RTC_FORMAT_BCD: BCD data format

Return values

HAL: status

HAL_RTC_SetAlarm_IT
Function Name

HAL_StatusTypeDef HAL_RTC_SetAlarm_IT
(RTC_HandleTypeDef * hrtc, RTC_AlarmTypeDef * sAlarm,
uint32_t Format)

Function Description

Sets the specified RTC Alarm with Interrupt.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
sAlarm: Pointer to Alarm structure
Format: Specifies the format of the entered parameters. This
parameter can be one of the following values:
DocID025834 Rev 4

689/964

HAL RTC Generic Driver

UM1725
RTC_FORMAT_BIN: Binary data format
RTC_FORMAT_BCD: BCD data format

Return values

HAL: status

HAL_RTC_DeactivateAlarm
Function Name

HAL_StatusTypeDef HAL_RTC_DeactivateAlarm
(RTC_HandleTypeDef * hrtc, uint32_t Alarm)

Function Description

Deactivate the specified RTC Alarm.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
Alarm: Specifies the Alarm. This parameter can be one of
the following values:
RTC_ALARM_A: AlarmA
RTC_ALARM_B: AlarmB

Return values

HAL: status

HAL_RTC_GetAlarm
Function Name

HAL_StatusTypeDef HAL_RTC_GetAlarm
(RTC_HandleTypeDef * hrtc, RTC_AlarmTypeDef * sAlarm,
uint32_t Alarm, uint32_t Format)

Function Description

Gets the RTC Alarm value and masks.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
sAlarm: Pointer to Date structure
Alarm: Specifies the Alarm. This parameter can be one of
the following values:
RTC_ALARM_A: AlarmA
RTC_ALARM_B: AlarmB
Format: Specifies the format of the entered parameters. This
parameter can be one of the following values:
RTC_FORMAT_BIN: Binary data format
RTC_FORMAT_BCD: BCD data format

Return values

HAL: status

HAL_RTC_AlarmIRQHandler
Function Name

void HAL_RTC_AlarmIRQHandler (RTC_HandleTypeDef * hrtc)

Function Description

This function handles Alarm interrupt request.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

None

HAL_RTC_PollForAlarmAEvent
Function Name

690/964

HAL_StatusTypeDef HAL_RTC_PollForAlarmAEvent
(RTC_HandleTypeDef * hrtc, uint32_t Timeout)
DocID025834 Rev 4

UM1725
Function Description

HAL RTC Generic Driver
This function handles AlarmA Polling request.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
Timeout: Timeout duration

Return values

HAL: status

HAL_RTC_AlarmAEventCallback
Function Name

void HAL_RTC_AlarmAEventCallback (RTC_HandleTypeDef *
hrtc)

Function Description

Alarm A callback.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

None

HAL_RTC_WaitForSynchro
Function Name

HAL_StatusTypeDef HAL_RTC_WaitForSynchro
(RTC_HandleTypeDef * hrtc)

Function Description

Waits until the RTC Time and Date registers (RTC_TR and
RTC_DR) are synchronized with RTC APB clock.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

Notes

The RTC Resynchronization mode is write protected, use the
__HAL_RTC_WRITEPROTECTION_DISABLE() before
calling this function.
To read the calendar through the shadow registers after
Calendar initialization, calendar update or after wake-up from
low power modes the software must first clear the RSF flag.
The software must then wait until it is set again before reading
the calendar, which means that the calendar registers have
been correctly copied into the RTC_TR and RTC_DR shadow
registers.

HAL_RTC_GetState
Function Name

HAL_RTCStateTypeDef HAL_RTC_GetState
(RTC_HandleTypeDef * hrtc)

Function Description

Returns the RTC state.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: state

DocID025834 Rev 4

691/964

HAL RTC Generic Driver

UM1725

RTC_EnterInitMode
Function Name

HAL_StatusTypeDef RTC_EnterInitMode
(RTC_HandleTypeDef * hrtc)

Function Description

Enters the RTC Initialization mode.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

Notes

The RTC Initialization mode is write protected, use the
__HAL_RTC_WRITEPROTECTION_DISABLE() before
calling this function.

RTC_ByteToBcd2
Function Name

uint8_t RTC_ByteToBcd2 (uint8_t Value)

Function Description

Converts a 2 digit decimal to BCD format.

Parameters

Value: Byte to be converted

Return values

Converted: byte

RTC_Bcd2ToByte
Function Name

uint8_t RTC_Bcd2ToByte (uint8_t Value)

Function Description

Converts from 2 digit BCD to Binary.

Parameters

Value: BCD value to be converted

Return values

Converted: word

52.3

RTC Firmware driver defines

52.3.1

RTC
RTC Alarm Date WeekDay Definitions
RTC_ALARMDATEWEEKDAYSEL_DATE
RTC_ALARMDATEWEEKDAYSEL_WEEKDAY
RTC Alarm Mask Definitions
RTC_ALARMMASK_NONE
RTC_ALARMMASK_DATEWEEKDAY
RTC_ALARMMASK_HOURS
RTC_ALARMMASK_MINUTES
RTC_ALARMMASK_SECONDS
RTC_ALARMMASK_ALL
RTC Alarms Definitions
RTC_ALARM_A
RTC_ALARM_B

692/964

DocID025834 Rev 4

UM1725

HAL RTC Generic Driver
RTC Alarm Sub Seconds Masks Definitions
RTC_ALARMSUBSECONDMASK_ALL

All Alarm SS fields are masked. There is no
comparison on sub seconds for Alarm

RTC_ALARMSUBSECONDMASK_SS14_1

SS[14:1] are don't care in Alarm
comparison. Only SS[0] is compared.

RTC_ALARMSUBSECONDMASK_SS14_2

SS[14:2] are don't care in Alarm
comparison. Only SS[1:0] are compared

RTC_ALARMSUBSECONDMASK_SS14_3

SS[14:3] are don't care in Alarm
comparison. Only SS[2:0] are compared

RTC_ALARMSUBSECONDMASK_SS14_4

SS[14:4] are don't care in Alarm
comparison. Only SS[3:0] are compared

RTC_ALARMSUBSECONDMASK_SS14_5

SS[14:5] are don't care in Alarm
comparison. Only SS[4:0] are compared

RTC_ALARMSUBSECONDMASK_SS14_6

SS[14:6] are don't care in Alarm
comparison. Only SS[5:0] are compared

RTC_ALARMSUBSECONDMASK_SS14_7

SS[14:7] are don't care in Alarm
comparison. Only SS[6:0] are compared

RTC_ALARMSUBSECONDMASK_SS14_8

SS[14:8] are don't care in Alarm
comparison. Only SS[7:0] are compared

RTC_ALARMSUBSECONDMASK_SS14_9

SS[14:9] are don't care in Alarm
comparison. Only SS[8:0] are compared

RTC_ALARMSUBSECONDMASK_SS14_10

SS[14:10] are don't care in Alarm
comparison. Only SS[9:0] are compared

RTC_ALARMSUBSECONDMASK_SS14_11

SS[14:11] are don't care in Alarm
comparison. Only SS[10:0] are compared

RTC_ALARMSUBSECONDMASK_SS14_12

SS[14:12] are don't care in Alarm
comparison.Only SS[11:0] are compared

RTC_ALARMSUBSECONDMASK_SS14_13

SS[14:13] are don't care in Alarm
comparison. Only SS[12:0] are compared

RTC_ALARMSUBSECONDMASK_SS14

SS[14] is don't care in Alarm
comparison.Only SS[13:0] are compared

RTC_ALARMSUBSECONDMASK_NONE

SS[14:0] are compared and must match to
activate alarm.

RTC AM PM Definitions
RTC_HOURFORMAT12_AM
RTC_HOURFORMAT12_PM
RTC DayLight Saving Definitions
RTC_DAYLIGHTSAVING_SUB1H
RTC_DAYLIGHTSAVING_ADD1H
RTC_DAYLIGHTSAVING_NONE

DocID025834 Rev 4

693/964

HAL RTC Generic Driver
RTC Exported Macros

UM1725

__HAL_RTC_RESET_HANDLE_STATE

Description:
Reset RTC handle state.
Parameters:
__HANDLE__: specifies
the RTC handle.
Return value:
None

__HAL_RTC_WRITEPROTECTION_DISABLE

Description:
Disable the write
protection for RTC
registers.
Parameters:
__HANDLE__: specifies
the RTC handle.
Return value:
None

__HAL_RTC_WRITEPROTECTION_ENABLE

Description:
Enable the write protection
for RTC registers.
Parameters:
__HANDLE__: specifies
the RTC handle.
Return value:
None

__HAL_RTC_ALARMA_ENABLE

Description:
Enable the RTC ALARMA
peripheral.
Parameters:
__HANDLE__: specifies
the RTC handle.
Return value:
None

__HAL_RTC_ALARMA_DISABLE

Description:
Disable the RTC ALARMA
peripheral.
Parameters:
__HANDLE__: specifies
the RTC handle.

694/964

DocID025834 Rev 4

UM1725

HAL RTC Generic Driver
Return value:
None
__HAL_RTC_ALARMB_ENABLE

Description:
Enable the RTC ALARMB
peripheral.
Parameters:
__HANDLE__: specifies
the RTC handle.
Return value:
None

__HAL_RTC_ALARMB_DISABLE

Description:
Disable the RTC ALARMB
peripheral.
Parameters:
__HANDLE__: specifies
the RTC handle.
Return value:
None

__HAL_RTC_ALARM_ENABLE_IT

Description:
Enable the RTC Alarm
interrupt.
Parameters:
__HANDLE__: specifies
the RTC handle.
__INTERRUPT__:
specifies the RTC Alarm
interrupt sources to be
enabled or disabled. This
parameter can be any
combination of the
following values:
RTC_IT_ALRA:
Alarm A interrupt
RTC_IT_ALRB:
Alarm B interrupt
Return value:
None

__HAL_RTC_ALARM_DISABLE_IT

Description:
Disable the RTC Alarm
interrupt.
Parameters:
__HANDLE__: specifies
the RTC handle.

DocID025834 Rev 4

695/964

HAL RTC Generic Driver

UM1725
__INTERRUPT__:
specifies the RTC Alarm
interrupt sources to be
enabled or disabled. This
parameter can be any
combination of the
following values:
RTC_IT_ALRA:
Alarm A interrupt
RTC_IT_ALRB:
Alarm B interrupt
Return value:
None

__HAL_RTC_ALARM_GET_IT

Description:
Check whether the
specified RTC Alarm
interrupt has occurred or
not.
Parameters:
__HANDLE__: specifies
the RTC handle.
__INTERRUPT__:
specifies the RTC Alarm
interrupt to check. This
parameter can be:
RTC_IT_ALRA:
Alarm A interrupt
RTC_IT_ALRB:
Alarm B interrupt
Return value:
None

__HAL_RTC_ALARM_GET_FLAG

Description:
Get the selected RTC
Alarm's flag status.
Parameters:
__HANDLE__: specifies
the RTC handle.
__FLAG__: specifies the
RTC Alarm Flag to check.
This parameter can be:
RTC_FLAG_ALRAF
RTC_FLAG_ALRBF
RTC_FLAG_ALRAW
F
RTC_FLAG_ALRBW
F
Return value:

696/964

DocID025834 Rev 4

UM1725

HAL RTC Generic Driver
None
__HAL_RTC_ALARM_CLEAR_FLAG

Description:
Clear the RTC Alarm's
pending flags.
Parameters:
__HANDLE__: specifies
the RTC handle.
__FLAG__: specifies the
RTC Alarm Flag sources
to be enabled or disabled.
This parameter can be:
RTC_FLAG_ALRAF
RTC_FLAG_ALRBF
Return value:
None

__HAL_RTC_ALARM_GET_IT_SOURCE

Description:
Check whether the
specified RTC Alarm
interrupt has been enabled
or not.
Parameters:
__HANDLE__: specifies
the RTC handle.
__INTERRUPT__:
specifies the RTC Alarm
interrupt sources to check.
This parameter can be:
RTC_IT_ALRA:
Alarm A interrupt
RTC_IT_ALRB:
Alarm B interrupt
Return value:
None

__HAL_RTC_ALARM_EXTI_ENABLE_IT

Description:
Enable interrupt on the
RTC Alarm associated Exti
line.
Return value:
None

__HAL_RTC_ALARM_EXTI_DISABLE_IT

Description:
Disable interrupt on the
RTC Alarm associated Exti
line.

DocID025834 Rev 4

697/964

HAL RTC Generic Driver

UM1725
Return value:
None

__HAL_RTC_ALARM_EXTI_ENABLE_EVENT

Description:
Enable event on the RTC
Alarm associated Exti line.
Return value:
None.

__HAL_RTC_ALARM_EXTI_DISABLE_EVENT

Description:
Disable event on the RTC
Alarm associated Exti line.
Return value:
None.

__HAL_RTC_ALARM_EXTI_ENABLE_FALLING_EDGE

Description:
Enable falling edge trigger
on the RTC Alarm
associated Exti line.
Return value:
None.

__HAL_RTC_ALARM_EXTI_DISABLE_FALLING_EDG
E

Description:
Disable falling edge trigger
on the RTC Alarm
associated Exti line.
Return value:
None.

__HAL_RTC_ALARM_EXTI_ENABLE_RISING_EDGE

Description:
Enable rising edge trigger
on the RTC Alarm
associated Exti line.
Return value:
None.

__HAL_RTC_ALARM_EXTI_DISABLE_RISING_EDGE

Description:
Disable rising edge trigger
on the RTC Alarm
associated Exti line.
Return value:
None.

__HAL_RTC_ALARM_EXTI_ENABLE_RISING_FALLIN
G_EDGE

698/964

DocID025834 Rev 4

Description:
Enable rising & falling
edge trigger on the RTC
Alarm associated Exti line.

UM1725

HAL RTC Generic Driver
Return value:
None.
__HAL_RTC_ALARM_EXTI_DISABLE_RISING_FALLIN
G_EDGE

Description:
Disable rising & falling
edge trigger on the RTC
Alarm associated Exti line.
Return value:
None.

__HAL_RTC_ALARM_EXTI_GET_FLAG

Description:
Check whether the RTC
Alarm associated Exti line
interrupt flag is set or not.
Return value:
Line: Status.

__HAL_RTC_ALARM_EXTI_CLEAR_FLAG

Description:
Clear the RTC Alarm
associated Exti line flag.
Return value:
None.

__HAL_RTC_ALARM_EXTI_GENERATE_SWIT

Description:
Generate a Software
interrupt on RTC Alarm
associated Exti line.
Return value:
None.

RTC Flags Definitions
RTC_FLAG_RECALPF
RTC_FLAG_TAMP2F
RTC_FLAG_TAMP1F
RTC_FLAG_TSOVF
RTC_FLAG_TSF
RTC_FLAG_WUTF
RTC_FLAG_ALRBF
RTC_FLAG_ALRAF
RTC_FLAG_INITF
RTC_FLAG_RSF
RTC_FLAG_INITS
RTC_FLAG_SHPF

DocID025834 Rev 4

699/964

HAL RTC Generic Driver
RTC_FLAG_WUTWF

UM1725

RTC_FLAG_ALRBWF
RTC_FLAG_ALRAWF
RTC Hour Formats
RTC_HOURFORMAT_24
RTC_HOURFORMAT_12
RTC Input Parameter Format Definitions
RTC_FORMAT_BIN
RTC_FORMAT_BCD
RTC Interrupts Definitions
RTC_IT_TS
RTC_IT_WUT
RTC_IT_ALRB
RTC_IT_ALRA
RTC_IT_TAMP
RTC_IT_TAMP1
RTC_IT_TAMP2
RTC Private macros to check input parameters
IS_RTC_HOUR_FORMAT
IS_RTC_OUTPUT
IS_RTC_OUTPUT_POL
IS_RTC_OUTPUT_TYPE
IS_RTC_HOUR12
IS_RTC_HOUR24
IS_RTC_ASYNCH_PREDIV
IS_RTC_SYNCH_PREDIV
IS_RTC_MINUTES
IS_RTC_SECONDS
IS_RTC_HOURFORMAT12
IS_RTC_DAYLIGHT_SAVING
IS_RTC_STORE_OPERATION
IS_RTC_FORMAT
IS_RTC_YEAR
IS_RTC_MONTH
IS_RTC_DATE
IS_RTC_WEEKDAY

700/964

DocID025834 Rev 4

UM1725

HAL RTC Generic Driver
IS_RTC_ALARM_DATE_WEEKDAY_DATE
IS_RTC_ALARM_DATE_WEEKDAY_WEEKDAY
IS_RTC_ALARM_DATE_WEEKDAY_SEL
IS_RTC_ALARM_MASK
IS_RTC_ALARM
IS_RTC_ALARM_SUB_SECOND_VALUE
IS_RTC_ALARM_SUB_SECOND_MASK
RTC Month Date Definitions
RTC_MONTH_JANUARY
RTC_MONTH_FEBRUARY
RTC_MONTH_MARCH
RTC_MONTH_APRIL
RTC_MONTH_MAY
RTC_MONTH_JUNE
RTC_MONTH_JULY
RTC_MONTH_AUGUST
RTC_MONTH_SEPTEMBER
RTC_MONTH_OCTOBER
RTC_MONTH_NOVEMBER
RTC_MONTH_DECEMBER
RTC Output Polarity Definitions
RTC_OUTPUT_POLARITY_HIGH
RTC_OUTPUT_POLARITY_LOW
RTC Output Selection Definitions
RTC_OUTPUT_DISABLE
RTC_OUTPUT_ALARMA
RTC_OUTPUT_ALARMB
RTC_OUTPUT_WAKEUP
RTC Output Type ALARM OUT
RTC_OUTPUT_TYPE_OPENDRAIN
RTC_OUTPUT_TYPE_PUSHPULL
RTC Store Operation Definitions
RTC_STOREOPERATION_RESET
RTC_STOREOPERATION_SET
RTC WeekDay Definitions
RTC_WEEKDAY_MONDAY

DocID025834 Rev 4

701/964

HAL RTC Generic Driver
RTC_WEEKDAY_TUESDAY
RTC_WEEKDAY_WEDNESDAY
RTC_WEEKDAY_THURSDAY
RTC_WEEKDAY_FRIDAY
RTC_WEEKDAY_SATURDAY
RTC_WEEKDAY_SUNDAY

702/964

DocID025834 Rev 4

UM1725

UM1725

HAL RTC Extension Driver

53

HAL RTC Extension Driver

53.1

RTCEx Firmware driver registers structures

53.1.1

RTC_TamperTypeDef
Data Fields
uint32_t Tamper
uint32_t PinSelection
uint32_t Trigger
uint32_t Filter
uint32_t SamplingFrequency
uint32_t PrechargeDuration
uint32_t TamperPullUp
uint32_t TimeStampOnTamperDetection

Field Documentation
uint32_t RTC_TamperTypeDef::Tamper
Specifies the Tamper Pin. This parameter can be a value of
RTCEx_Tamper_Pins_Definitions
uint32_t RTC_TamperTypeDef::PinSelection
Specifies the Tamper Pin. This parameter can be a value of
RTCEx_Tamper_Pins_Selection
uint32_t RTC_TamperTypeDef::Trigger
Specifies the Tamper Trigger. This parameter can be a value of
RTCEx_Tamper_Trigger_Definitions
uint32_t RTC_TamperTypeDef::Filter
Specifies the RTC Filter Tamper. This parameter can be a value of
RTCEx_Tamper_Filter_Definitions
uint32_t RTC_TamperTypeDef::SamplingFrequency
Specifies the sampling frequency. This parameter can be a value of
RTCEx_Tamper_Sampling_Frequencies_Definitions
uint32_t RTC_TamperTypeDef::PrechargeDuration
Specifies the Precharge Duration . This parameter can be a value of
RTCEx_Tamper_Pin_Precharge_Duration_Definitions
uint32_t RTC_TamperTypeDef::TamperPullUp
Specifies the Tamper PullUp . This parameter can be a value of
RTCEx_Tamper_Pull_UP_Definitions
uint32_t RTC_TamperTypeDef::TimeStampOnTamperDetection
Specifies the TimeStampOnTamperDetection. This parameter can be a value of
RTCEx_Tamper_TimeStampOnTamperDetection_Definitions

DocID025834 Rev 4

703/964

HAL RTC Extension Driver

UM1725

53.2

RTCEx Firmware driver API description

53.2.1

How to use this driver
Enable the RTC domain access.
Configure the RTC Prescaler (Asynchronous and Synchronous) and RTC hour format
using the HAL_RTC_Init() function.

RTC Wake-up configuration
To configure the RTC Wake-up Clock source and Counter use the
HAL_RTC_SetWakeUpTimer() function. You can also configure the RTC Wake-up
timer in interrupt mode using the HAL_RTC_SetWakeUpTimer_IT() function.
To read the RTC Wake-up Counter register, use the HAL_RTC_GetWakeUpTimer()
function.

TimeStamp configuration
Configure the RTC_AFx trigger and enable the RTC TimeStamp using the
HAL_RTC_SetTimeStamp() function. You can also configure the RTC TimeStamp
with interrupt mode using the HAL_RTC_SetTimeStamp_IT() function.
To read the RTC TimeStamp Time and Date register, use the
HAL_RTC_GetTimeStamp() function.
The TIMESTAMP alternate function can be mapped either to RTC_AF1 (PC13) or
RTC_AF2 (PI8 or PA0 only for STM32F446xx devices) depending on the value of
TSINSEL bit in RTC_TAFCR register. The corresponding pin is also selected by
HAL_RTC_SetTimeStamp() or HAL_RTC_SetTimeStamp_IT() function.

Tamper configuration
Enable the RTC Tamper and configure the Tamper filter count, trigger Edge or Level
according to the Tamper filter (if equal to 0 Edge else Level) value, sampling
frequency, precharge or discharge and Pull-UP using the HAL_RTC_SetTamper()
function. You can configure RTC Tamper in interrupt mode using
HAL_RTC_SetTamper_IT() function.
The TAMPER1 alternate function can be mapped either to RTC_AF1 (PC13) or
RTC_AF2 (PI8 or PA0 only for STM32F446xx devices) depending on the value of
TAMP1INSEL bit in RTC_TAFCR register. The corresponding pin is also selected by
HAL_RTC_SetTamper() or HAL_RTC_SetTamper_IT() function.

Backup Data Registers configuration
To write to the RTC Backup Data registers, use the HAL_RTC_BKUPWrite() function.
To read the RTC Backup Data registers, use the HAL_RTC_BKUPRead() function.

704/964

DocID025834 Rev 4

UM1725

53.2.2

HAL RTC Extension Driver

RTC TimeStamp and Tamper functions
This section provides functions allowing to configure TimeStamp feature
This section contains the following APIs:
HAL_RTCEx_SetTimeStamp()
HAL_RTCEx_SetTimeStamp_IT()
HAL_RTCEx_DeactivateTimeStamp()
HAL_RTCEx_GetTimeStamp()
HAL_RTCEx_SetTamper()
HAL_RTCEx_SetTamper_IT()
HAL_RTCEx_DeactivateTamper()
HAL_RTCEx_TamperTimeStampIRQHandler()
HAL_RTCEx_TimeStampEventCallback()
HAL_RTCEx_Tamper1EventCallback()
HAL_RTCEx_Tamper2EventCallback()
HAL_RTCEx_PollForTimeStampEvent()
HAL_RTCEx_PollForTamper1Event()
HAL_RTCEx_PollForTamper2Event()

53.2.3

RTC Wake-up functions
This section provides functions allowing to configure Wake-up feature
This section contains the following APIs:
HAL_RTCEx_SetWakeUpTimer()
HAL_RTCEx_SetWakeUpTimer_IT()
HAL_RTCEx_DeactivateWakeUpTimer()
HAL_RTCEx_GetWakeUpTimer()
HAL_RTCEx_WakeUpTimerIRQHandler()
HAL_RTCEx_WakeUpTimerEventCallback()
HAL_RTCEx_PollForWakeUpTimerEvent()

53.2.4

Extension Peripheral Control functions
This subsection provides functions allowing to
Write a data in a specified RTC Backup data register
Read a data in a specified RTC Backup data register
Set the Coarse calibration parameters.
Deactivate the Coarse calibration parameters
Set the Smooth calibration parameters.
Configure the Synchronization Shift Control Settings.
Configure the Calibration Pinout (RTC_CALIB) Selection (1Hz or 512Hz).
Deactivate the Calibration Pinout (RTC_CALIB) Selection (1Hz or 512Hz).
Enable the RTC reference clock detection.
Disable the RTC reference clock detection.
Enable the Bypass Shadow feature.
Disable the Bypass Shadow feature.
This section contains the following APIs:
HAL_RTCEx_BKUPWrite()
HAL_RTCEx_BKUPRead()
HAL_RTCEx_SetCoarseCalib()
HAL_RTCEx_DeactivateCoarseCalib()
DocID025834 Rev 4

705/964

HAL RTC Extension Driver

UM1725

HAL_RTCEx_SetSmoothCalib()
HAL_RTCEx_SetSynchroShift()
HAL_RTCEx_SetCalibrationOutPut()
HAL_RTCEx_DeactivateCalibrationOutPut()
HAL_RTCEx_SetRefClock()
HAL_RTCEx_DeactivateRefClock()
HAL_RTCEx_EnableBypassShadow()
HAL_RTCEx_DisableBypassShadow()

53.2.5

Extended features functions
This section provides functions allowing to:
RTC Alarm B callback
RTC Poll for Alarm B request
This section contains the following APIs:
HAL_RTCEx_AlarmBEventCallback()
HAL_RTCEx_PollForAlarmBEvent()

53.2.6

Detailed description of functions
HAL_RTCEx_SetTimeStamp

706/964

Function Name

HAL_StatusTypeDef HAL_RTCEx_SetTimeStamp
(RTC_HandleTypeDef * hrtc, uint32_t TimeStampEdge,
uint32_t RTC_TimeStampPin)

Function Description

Sets TimeStamp.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
TimeStampEdge: Specifies the pin edge on which the
TimeStamp is activated. This parameter can be one of the
following values:
RTC_TIMESTAMPEDGE_RISING: the Time stamp
event occurs on the rising edge of the related pin.
RTC_TIMESTAMPEDGE_FALLING: the Time stamp
event occurs on the falling edge of the related pin.
RTC_TimeStampPin: specifies the RTC TimeStamp Pin.
This parameter can be one of the following values:
RTC_TIMESTAMPPIN_DEFAULT: PC13 is selected as
RTC TimeStamp Pin.
RTC_TIMESTAMPPIN_POS1: PI8/PA0 is selected as
RTC TimeStamp Pin. (PI8 for all STM32 devices except
for STM32F446xx devices the PA0 is used)
RTC_TIMESTAMPPIN_PA0: PA0 is selected as RTC
TimeStamp Pin only for STM32F446xx devices

Return values

HAL: status

Notes

This API must be called before enabling the TimeStamp
feature.

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver

HAL_RTCEx_SetTimeStamp_IT
Function Name

HAL_StatusTypeDef HAL_RTCEx_SetTimeStamp_IT
(RTC_HandleTypeDef * hrtc, uint32_t TimeStampEdge,
uint32_t RTC_TimeStampPin)

Function Description

Sets TimeStamp with Interrupt.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
TimeStampEdge: Specifies the pin edge on which the
TimeStamp is activated. This parameter can be one of the
following values:
RTC_TIMESTAMPEDGE_RISING: the Time stamp
event occurs on the rising edge of the related pin.
RTC_TIMESTAMPEDGE_FALLING: the Time stamp
event occurs on the falling edge of the related pin.
RTC_TimeStampPin: Specifies the RTC TimeStamp Pin.
This parameter can be one of the following values:
RTC_TIMESTAMPPIN_DEFAULT: PC13 is selected as
RTC TimeStamp Pin.
RTC_TIMESTAMPPIN_PI8: PI8 is selected as RTC
TimeStamp Pin. (not applicable in the case of
STM32F446xx devices)
RTC_TIMESTAMPPIN_PA0: PA0 is selected as RTC
TimeStamp Pin only for STM32F446xx devices

Return values

HAL: status

Notes

This API must be called before enabling the TimeStamp
feature.

HAL_RTCEx_DeactivateTimeStamp
Function Name

HAL_StatusTypeDef HAL_RTCEx_DeactivateTimeStamp
(RTC_HandleTypeDef * hrtc)

Function Description

Deactivates TimeStamp.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

HAL_RTCEx_GetTimeStamp
Function Name

HAL_StatusTypeDef HAL_RTCEx_GetTimeStamp
(RTC_HandleTypeDef * hrtc, RTC_TimeTypeDef *
sTimeStamp, RTC_DateTypeDef * sTimeStampDate, uint32_t
Format)

Function Description

Gets the RTC TimeStamp value.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
sTimeStamp: Pointer to Time structure
sTimeStampDate: Pointer to Date structure
Format: specifies the format of the entered parameters. This
parameter can be one of the following values:
DocID025834 Rev 4

707/964

HAL RTC Extension Driver

UM1725
RTC_FORMAT_BIN: Binary data format
RTC_FORMAT_BCD: BCD data format

Return values

HAL: status

HAL_RTCEx_SetTamper
Function Name

HAL_StatusTypeDef HAL_RTCEx_SetTamper
(RTC_HandleTypeDef * hrtc, RTC_TamperTypeDef * sTamper)

Function Description

Sets Tamper.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
sTamper: Pointer to Tamper Structure.

Return values

HAL: status

Notes

By calling this API we disable the tamper interrupt for all
tampers.

HAL_RTCEx_SetTamper_IT
Function Name

HAL_StatusTypeDef HAL_RTCEx_SetTamper_IT
(RTC_HandleTypeDef * hrtc, RTC_TamperTypeDef * sTamper)

Function Description

Sets Tamper with interrupt.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
sTamper: Pointer to RTC Tamper.

Return values

HAL: status

Notes

By calling this API we force the tamper interrupt for all
tampers.

HAL_RTCEx_DeactivateTamper
Function Name

HAL_StatusTypeDef HAL_RTCEx_DeactivateTamper
(RTC_HandleTypeDef * hrtc, uint32_t Tamper)

Function Description

Deactivates Tamper.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
Tamper: Selected tamper pin. This parameter can be
RTC_Tamper_1 and/or RTC_TAMPER_2.

Return values

HAL: status

HAL_RTCEx_TamperTimeStampIRQHandler
Function Name

void HAL_RTCEx_TamperTimeStampIRQHandler
(RTC_HandleTypeDef * hrtc)

Function Description

This function handles TimeStamp interrupt request.

Parameters

708/964

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver
Return values

None

HAL_RTCEx_Tamper1EventCallback
Function Name

void HAL_RTCEx_Tamper1EventCallback
(RTC_HandleTypeDef * hrtc)

Function Description

Tamper 1 callback.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

None

HAL_RTCEx_Tamper2EventCallback
Function Name

void HAL_RTCEx_Tamper2EventCallback
(RTC_HandleTypeDef * hrtc)

Function Description

Tamper 2 callback.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

None

HAL_RTCEx_TimeStampEventCallback
Function Name

void HAL_RTCEx_TimeStampEventCallback
(RTC_HandleTypeDef * hrtc)

Function Description

TimeStamp callback.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

None

HAL_RTCEx_PollForTimeStampEvent
Function Name

HAL_StatusTypeDef HAL_RTCEx_PollForTimeStampEvent
(RTC_HandleTypeDef * hrtc, uint32_t Timeout)

Function Description

This function handles TimeStamp polling request.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
Timeout: Timeout duration

Return values

HAL: status

HAL_RTCEx_PollForTamper1Event
Function Name

HAL_StatusTypeDef HAL_RTCEx_PollForTamper1Event
(RTC_HandleTypeDef * hrtc, uint32_t Timeout)

Function Description

This function handles Tamper1 Polling.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

DocID025834 Rev 4

709/964

HAL RTC Extension Driver

UM1725
Timeout: Timeout duration

Return values

HAL: status

HAL_RTCEx_PollForTamper2Event
Function Name

HAL_StatusTypeDef HAL_RTCEx_PollForTamper2Event
(RTC_HandleTypeDef * hrtc, uint32_t Timeout)

Function Description

This function handles Tamper2 Polling.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
Timeout: Timeout duration

Return values

HAL: status

HAL_RTCEx_SetWakeUpTimer
Function Name

HAL_StatusTypeDef HAL_RTCEx_SetWakeUpTimer
(RTC_HandleTypeDef * hrtc, uint32_t WakeUpCounter,
uint32_t WakeUpClock)

Function Description

Sets wake up timer.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
WakeUpCounter: Wake up counter
WakeUpClock: Wake up clock

Return values

HAL: status

HAL_RTCEx_SetWakeUpTimer_IT
Function Name

HAL_StatusTypeDef HAL_RTCEx_SetWakeUpTimer_IT
(RTC_HandleTypeDef * hrtc, uint32_t WakeUpCounter,
uint32_t WakeUpClock)

Function Description

Sets wake up timer with interrupt.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
WakeUpCounter: Wake up counter
WakeUpClock: Wake up clock

Return values

HAL: status

HAL_RTCEx_DeactivateWakeUpTimer

710/964

Function Name

uint32_t HAL_RTCEx_DeactivateWakeUpTimer
(RTC_HandleTypeDef * hrtc)

Function Description

Deactivates wake up timer counter.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver

HAL_RTCEx_GetWakeUpTimer
Function Name

uint32_t HAL_RTCEx_GetWakeUpTimer (RTC_HandleTypeDef
* hrtc)

Function Description

Gets wake up timer counter.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

Counter: value

HAL_RTCEx_WakeUpTimerIRQHandler
Function Name

void HAL_RTCEx_WakeUpTimerIRQHandler
(RTC_HandleTypeDef * hrtc)

Function Description

This function handles Wake Up Timer interrupt request.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

None

HAL_RTCEx_WakeUpTimerEventCallback
Function Name

void HAL_RTCEx_WakeUpTimerEventCallback
(RTC_HandleTypeDef * hrtc)

Function Description

Wake Up Timer callback.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

None

HAL_RTCEx_PollForWakeUpTimerEvent
Function Name

HAL_StatusTypeDef HAL_RTCEx_PollForWakeUpTimerEvent
(RTC_HandleTypeDef * hrtc, uint32_t Timeout)

Function Description

This function handles Wake Up Timer Polling.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
Timeout: Timeout duration

Return values

HAL: status

HAL_RTCEx_BKUPWrite
Function Name

void HAL_RTCEx_BKUPWrite (RTC_HandleTypeDef * hrtc,
uint32_t BackupRegister, uint32_t Data)

Function Description

Writes a data in a specified RTC Backup data register.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
BackupRegister: RTC Backup data Register number. This
parameter can be: RTC_BKP_DRx where x can be from 0 to
19 to specify the register.
DocID025834 Rev 4

711/964

HAL RTC Extension Driver

UM1725
Data: Data to be written in the specified RTC Backup data
register.

Return values

None

HAL_RTCEx_BKUPRead
Function Name

uint32_t HAL_RTCEx_BKUPRead (RTC_HandleTypeDef * hrtc,
uint32_t BackupRegister)

Function Description

Reads data from the specified RTC Backup data Register.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
BackupRegister: RTC Backup data Register number. This
parameter can be: RTC_BKP_DRx where x can be from 0 to
19 to specify the register.

Return values

Read: value

HAL_RTCEx_SetCoarseCalib
Function Name

HAL_StatusTypeDef HAL_RTCEx_SetCoarseCalib
(RTC_HandleTypeDef * hrtc, uint32_t CalibSign, uint32_t
Value)

Function Description

Sets the Coarse calibration parameters.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
CalibSign: Specifies the sign of the coarse calibration value.
This parameter can be one of the following values :
RTC_CALIBSIGN_POSITIVE: The value sign is positive
RTC_CALIBSIGN_NEGATIVE: The value sign is
negative
Value: value of coarse calibration expressed in ppm (coded
on 5 bits).

Return values

HAL: status

Notes

This Calibration value should be between 0 and 63 when
using negative sign with a 2-ppm step.
This Calibration value should be between 0 and 126 when
using positive sign with a 4-ppm step.

HAL_RTCEx_DeactivateCoarseCalib

712/964

Function Name

HAL_StatusTypeDef HAL_RTCEx_DeactivateCoarseCalib
(RTC_HandleTypeDef * hrtc)

Function Description

Deactivates the Coarse calibration parameters.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver

HAL_RTCEx_SetSmoothCalib
Function Name

HAL_StatusTypeDef HAL_RTCEx_SetSmoothCalib
(RTC_HandleTypeDef * hrtc, uint32_t SmoothCalibPeriod,
uint32_t SmoothCalibPlusPulses, uint32_t
SmouthCalibMinusPulsesValue)

Function Description

Sets the Smooth calibration parameters.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
SmoothCalibPeriod: Select the Smooth Calibration Period.
This parameter can be can be one of the following values :
RTC_SMOOTHCALIB_PERIOD_32SEC: The smooth
calibration period is 32s.
RTC_SMOOTHCALIB_PERIOD_16SEC: The smooth
calibration period is 16s.
RTC_SMOOTHCALIB_PERIOD_8SEC: The smooth
calibration period is 8s.
SmoothCalibPlusPulses: Select to Set or reset the CALP
bit. This parameter can be one of the following values:
RTC_SMOOTHCALIB_PLUSPULSES_SET: Add one
RTCCLK pulse every 2*11 pulses.
RTC_SMOOTHCALIB_PLUSPULSES_RESET: No
RTCCLK pulses are added.
SmouthCalibMinusPulsesValue: Select the value of
CALM[8:0] bits. This parameter can be one any value from 0
to 0x000001FF.

Return values

HAL: status

Notes

To deactivate the smooth calibration, the field
SmoothCalibPlusPulses must be equal to
SMOOTHCALIB_PLUSPULSES_RESET and the field
SmouthCalibMinusPulsesValue must be equal to 0.

HAL_RTCEx_SetSynchroShift
Function Name

HAL_StatusTypeDef HAL_RTCEx_SetSynchroShift
(RTC_HandleTypeDef * hrtc, uint32_t ShiftAdd1S, uint32_t
ShiftSubFS)

Function Description

Configures the Synchronization Shift Control Settings.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
ShiftAdd1S: Select to add or not 1 second to the time
calendar. This parameter can be one of the following values :
RTC_SHIFTADD1S_SET: Add one second to the clock
calendar.
RTC_SHIFTADD1S_RESET: No effect.
ShiftSubFS: Select the number of Second Fractions to
substitute. This parameter can be one any value from 0 to
0x7FFF.

Return values

HAL: status

Notes

When REFCKON is set, firmware must not write to Shift
DocID025834 Rev 4

713/964

HAL RTC Extension Driver

UM1725
control register.

HAL_RTCEx_SetCalibrationOutPut
Function Name

HAL_StatusTypeDef HAL_RTCEx_SetCalibrationOutPut
(RTC_HandleTypeDef * hrtc, uint32_t CalibOutput)

Function Description

Configures the Calibration Pinout (RTC_CALIB) Selection (1Hz or
512Hz).

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
CalibOutput: Select the Calibration output Selection . This
parameter can be one of the following values:
RTC_CALIBOUTPUT_512HZ: A signal has a regular
waveform at 512Hz.
RTC_CALIBOUTPUT_1HZ: A signal has a regular
waveform at 1Hz.

Return values

HAL: status

HAL_RTCEx_DeactivateCalibrationOutPut
Function Name

HAL_StatusTypeDef
HAL_RTCEx_DeactivateCalibrationOutPut
(RTC_HandleTypeDef * hrtc)

Function Description

Deactivates the Calibration Pinout (RTC_CALIB) Selection (1Hz or
512Hz).

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

HAL_RTCEx_SetRefClock
Function Name

HAL_StatusTypeDef HAL_RTCEx_SetRefClock
(RTC_HandleTypeDef * hrtc)

Function Description

Enables the RTC reference clock detection.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

HAL_RTCEx_DeactivateRefClock

714/964

Function Name

HAL_StatusTypeDef HAL_RTCEx_DeactivateRefClock
(RTC_HandleTypeDef * hrtc)

Function Description

Disable the RTC reference clock detection.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver

HAL_RTCEx_EnableBypassShadow
Function Name

HAL_StatusTypeDef HAL_RTCEx_EnableBypassShadow
(RTC_HandleTypeDef * hrtc)

Function Description

Enables the Bypass Shadow feature.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

Notes

When the Bypass Shadow is enabled the calendar value are
taken directly from the Calendar counter.

HAL_RTCEx_DisableBypassShadow
Function Name

HAL_StatusTypeDef HAL_RTCEx_DisableBypassShadow
(RTC_HandleTypeDef * hrtc)

Function Description

Disables the Bypass Shadow feature.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

HAL: status

Notes

When the Bypass Shadow is enabled the calendar value are
taken directly from the Calendar counter.

HAL_RTCEx_AlarmBEventCallback
Function Name

void HAL_RTCEx_AlarmBEventCallback
(RTC_HandleTypeDef * hrtc)

Function Description

Alarm B callback.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.

Return values

None

HAL_RTCEx_PollForAlarmBEvent
Function Name

HAL_StatusTypeDef HAL_RTCEx_PollForAlarmBEvent
(RTC_HandleTypeDef * hrtc, uint32_t Timeout)

Function Description

This function handles AlarmB Polling request.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that
contains the configuration information for RTC.
Timeout: Timeout duration

Return values

HAL: status

DocID025834 Rev 4

715/964

HAL RTC Extension Driver

UM1725

53.3

RTCEx Firmware driver defines

53.3.1

RTCEx
RTC Add 1 Second Parameter Definitions
RTC_SHIFTADD1S_RESET
RTC_SHIFTADD1S_SET
RTC Backup Registers Definitions
RTC_BKP_DR0
RTC_BKP_DR1
RTC_BKP_DR2
RTC_BKP_DR3
RTC_BKP_DR4
RTC_BKP_DR5
RTC_BKP_DR6
RTC_BKP_DR7
RTC_BKP_DR8
RTC_BKP_DR9
RTC_BKP_DR10
RTC_BKP_DR11
RTC_BKP_DR12
RTC_BKP_DR13
RTC_BKP_DR14
RTC_BKP_DR15
RTC_BKP_DR16
RTC_BKP_DR17
RTC_BKP_DR18
RTC_BKP_DR19
RTC Calibration
__HAL_RTC_COARSE_CALIB_ENABLE

Description:
Enable the Coarse calibration
process.
Parameters:
__HANDLE__: specifies the
RTC handle.
Return value:
None

__HAL_RTC_COARSE_CALIB_DISABLE

Description:
Disable the Coarse calibration

716/964

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver
process.
Parameters:
__HANDLE__: specifies the
RTC handle.
Return value:
None
__HAL_RTC_CALIBRATION_OUTPUT_ENABLE

Description:
Enable the RTC calibration
output.
Parameters:
__HANDLE__: specifies the
RTC handle.
Return value:
None

__HAL_RTC_CALIBRATION_OUTPUT_DISABLE

Description:
Disable the calibration output.
Parameters:
__HANDLE__: specifies the
RTC handle.
Return value:
None

__HAL_RTC_CLOCKREF_DETECTION_ENABLE

Description:
Enable the clock reference
detection.
Parameters:
__HANDLE__: specifies the
RTC handle.
Return value:
None

__HAL_RTC_CLOCKREF_DETECTION_DISABLE

Description:
Disable the clock reference
detection.
Parameters:
__HANDLE__: specifies the
RTC handle.
Return value:
None

__HAL_RTC_SHIFT_GET_FLAG

Description:
Get the selected RTC shift

DocID025834 Rev 4

717/964

HAL RTC Extension Driver

UM1725
operation's flag status.
Parameters:
__HANDLE__: specifies the
RTC handle.
__FLAG__: specifies the RTC
shift operation Flag is pending
or not. This parameter can be:
RTC_FLAG_SHPF
Return value:
None

RTC Calib Output Selection Definitions
RTC_CALIBOUTPUT_512HZ
RTC_CALIBOUTPUT_1HZ
RTC Digital Calib Definitions
RTC_CALIBSIGN_POSITIVE
RTC_CALIBSIGN_NEGATIVE
Private macros to check input parameters
IS_RTC_BKP
IS_TIMESTAMP_EDGE
IS_RTC_TAMPER
IS_RTC_TAMPER_PIN
IS_RTC_TIMESTAMP_PIN
IS_RTC_TAMPER_TRIGGER
IS_RTC_TAMPER_FILTER
IS_RTC_TAMPER_SAMPLING_FREQ
IS_RTC_TAMPER_PRECHARGE_DURATION
IS_RTC_TAMPER_TIMESTAMPONTAMPER_DETECTION
IS_RTC_TAMPER_PULLUP_STATE
IS_RTC_WAKEUP_CLOCK
IS_RTC_WAKEUP_COUNTER
IS_RTC_CALIB_SIGN
IS_RTC_CALIB_VALUE
IS_RTC_SMOOTH_CALIB_PERIOD
IS_RTC_SMOOTH_CALIB_PLUS
IS_RTC_SMOOTH_CALIB_MINUS
IS_RTC_SHIFT_ADD1S
IS_RTC_SHIFT_SUBFS
IS_RTC_CALIB_OUTPUT

718/964

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver
RTC Smooth Calib Period Definitions
RTC_SMOOTHCALIB_PERIOD_32SEC

If RTCCLK = 32768 Hz, Smooth calibration
period is 32s, else 2exp20 RTCCLK seconds

RTC_SMOOTHCALIB_PERIOD_16SEC

If RTCCLK = 32768 Hz, Smooth calibration
period is 16s, else 2exp19 RTCCLK seconds

RTC_SMOOTHCALIB_PERIOD_8SEC

If RTCCLK = 32768 Hz, Smooth calibration
period is 8s, else 2exp18 RTCCLK seconds

RTC Smooth Calib Plus Pulses Definitions
RTC_SMOOTHCALIB_PLUSPULSES_SET

The number of RTCCLK pulses added
during a X -second window = Y CALM[8:0] with Y = 512, 256, 128 when
X = 32, 16, 8

RTC_SMOOTHCALIB_PLUSPULSES_RESET

The number of RTCCLK pulses
subbstited during a 32-second window =
CALM[8:0]

RTC Tamper
__HAL_RTC_TAMPER1_ENABLE

Description:
Enable the RTC Tamper1 input
detection.
Parameters:
__HANDLE__: specifies the RTC
handle.
Return value:
None

__HAL_RTC_TAMPER1_DISABLE

Description:
Disable the RTC Tamper1 input
detection.
Parameters:
__HANDLE__: specifies the RTC
handle.
Return value:
None

__HAL_RTC_TAMPER2_ENABLE

Description:
Enable the RTC Tamper2 input
detection.
Parameters:
__HANDLE__: specifies the RTC
handle.
Return value:
None

__HAL_RTC_TAMPER2_DISABLE

Description:

DocID025834 Rev 4

719/964

HAL RTC Extension Driver

UM1725
Disable the RTC Tamper2 input
detection.
Parameters:
__HANDLE__: specifies the RTC
handle.
Return value:
None

__HAL_RTC_TAMPER_GET_IT

Description:
Check whether the specified RTC
Tamper interrupt has occurred or not.
Parameters:
__HANDLE__: specifies the RTC
handle.
__INTERRUPT__: specifies the RTC
Tamper interrupt to check. This
parameter can be:
RTC_IT_TAMP1
RTC_IT_TAMP2
Return value:
None

__HAL_RTC_TAMPER_GET_IT_SOURCE

Description:
Check whether the specified RTC
Tamper interrupt has been enabled or
not.
Parameters:
__HANDLE__: specifies the RTC
handle.
__INTERRUPT__: specifies the RTC
Tamper interrupt source to check. This
parameter can be:
RTC_IT_TAMP: Tamper interrupt
Return value:
None

__HAL_RTC_TAMPER_GET_FLAG

Description:
Get the selected RTC Tamper's flag
status.
Parameters:
__HANDLE__: specifies the RTC
handle.
__FLAG__: specifies the RTC Tamper
Flag sources to be enabled or disabled.
This parameter can be:
RTC_FLAG_TAMP1F

720/964

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver
RTC_FLAG_TAMP2F
Return value:
None
__HAL_RTC_TAMPER_CLEAR_FLAG

Description:
Clear the RTC Tamper's pending flags.
Parameters:
__HANDLE__: specifies the RTC
handle.
__FLAG__: specifies the RTC Tamper
Flag to clear. This parameter can be:
RTC_FLAG_TAMP1F
RTC_FLAG_TAMP2F
Return value:
None

RTC Tamper Filter Definitions
RTC_TAMPERFILTER_DISABLE

Tamper filter is disabled

RTC_TAMPERFILTER_2SAMPLE

Tamper is activated after 2 consecutive samples at
the active level

RTC_TAMPERFILTER_4SAMPLE

Tamper is activated after 4 consecutive samples at
the active level

RTC_TAMPERFILTER_8SAMPLE

Tamper is activated after 8 consecutive samples at
the active level.

RTC Tamper Pins Definitions
RTC_TAMPER_1
RTC_TAMPER_2
RTC tamper Pins Selection
RTC_TAMPERPIN_DEFAULT
RTC_TAMPERPIN_POS1
RTC Tamper Pin Precharge Duration Definitions
RTC_TAMPERPRECHARGEDURATION_1RTCCLK

Tamper pins are pre-charged
before sampling during 1 RTCCLK
cycle

RTC_TAMPERPRECHARGEDURATION_2RTCCLK

Tamper pins are pre-charged
before sampling during 2 RTCCLK
cycles

RTC_TAMPERPRECHARGEDURATION_4RTCCLK

Tamper pins are pre-charged
before sampling during 4 RTCCLK
cycles

RTC_TAMPERPRECHARGEDURATION_8RTCCLK

Tamper pins are pre-charged
before sampling during 8 RTCCLK
cycles

DocID025834 Rev 4

721/964

HAL RTC Extension Driver
RTC Tamper Pull Up Definitions

UM1725

RTC_TAMPER_PULLUP_ENABLE

TimeStamp on Tamper Detection event saved

RTC_TAMPER_PULLUP_DISABLE

TimeStamp on Tamper Detection event is not saved

RTC Tamper Sampling Frequencies Definitions
RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV32768

Each of the tamper inputs are
sampled with a frequency =
RTCCLK / 32768

RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV16384

Each of the tamper inputs are
sampled with a frequency =
RTCCLK / 16384

RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV8192

Each of the tamper inputs are
sampled with a frequency =
RTCCLK / 8192

RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV4096

Each of the tamper inputs are
sampled with a frequency =
RTCCLK / 4096

RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV2048

Each of the tamper inputs are
sampled with a frequency =
RTCCLK / 2048

RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV1024

Each of the tamper inputs are
sampled with a frequency =
RTCCLK / 1024

RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV512

Each of the tamper inputs are
sampled with a frequency =
RTCCLK / 512

RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV256

Each of the tamper inputs are
sampled with a frequency =
RTCCLK / 256

EXTI RTC Tamper Timestamp EXTI
__HAL_RTC_TAMPER_TIMESTAMP_EXTI_ENABLE_I
T

Description:
Enable interrupt on the
RTC Tamper and
Timestamp associated Exti
line.
Return value:
None

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_DISABLE_
IT

Description:
Disable interrupt on the
RTC Tamper and
Timestamp associated Exti
line.
Return value:
None

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_ENABLE_
722/964

DocID025834 Rev 4

Description:

UM1725

HAL RTC Extension Driver
EVENT

Enable event on the RTC
Tamper and Timestamp
associated Exti line.
Return value:
None.

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_DISABLE_
EVENT

Description:
Disable event on the RTC
Tamper and Timestamp
associated Exti line.
Return value:
None.

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_ENABLE_
FALLING_EDGE

Description:
Enable falling edge trigger
on the RTC Tamper and
Timestamp associated Exti
line.
Return value:
None.

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_DISABLE_
FALLING_EDGE

Description:
Disable falling edge trigger
on the RTC Tamper and
Timestamp associated Exti
line.
Return value:
None.

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_ENABLE_
RISING_EDGE

Description:
Enable rising edge trigger
on the RTC Tamper and
Timestamp associated Exti
line.
Return value:
None.

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_DISABLE_
RISING_EDGE

Description:
Disable rising edge trigger
on the RTC Tamper and
Timestamp associated Exti
line.
Return value:
None.

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_ENABLE_
RISING_FALLING_EDGE

DocID025834 Rev 4

Description:
Enable rising & falling
edge trigger on the RTC
723/964

HAL RTC Extension Driver

UM1725
Tamper and Timestamp
associated Exti line.
Return value:
None.

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_DISABLE_
RISING_FALLING_EDGE

Description:
Disable rising & falling
edge trigger on the RTC
Tamper and Timestamp
associated Exti line.
Return value:
None.

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_GET_FLA
G

Description:
Check whether the RTC
Tamper and Timestamp
associated Exti line
interrupt flag is set or not.
Return value:
Line: Status.

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_CLEAR_F
LAG

Description:
Clear the RTC Tamper and
Timestamp associated Exti
line flag.
Return value:
None.

__HAL_RTC_TAMPER_TIMESTAMP_EXTI_GENERAT
E_SWIT

Description:
Generate a Software
interrupt on the RTC
Tamper and Timestamp
associated Exti line.
Return value:
None.

RTC Tamper TimeStamp On Tamper Detection Definitions
RTC_TIMESTAMPONTAMPERDETECTION_ENABLE

TimeStamp on Tamper
Detection event saved

RTC_TIMESTAMPONTAMPERDETECTION_DISABLE

TimeStamp on Tamper
Detection event is not saved

RTC Tamper Triggers Definitions
RTC_TAMPERTRIGGER_RISINGEDGE
RTC_TAMPERTRIGGER_FALLINGEDGE
RTC_TAMPERTRIGGER_LOWLEVEL
RTC_TAMPERTRIGGER_HIGHLEVEL
724/964

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver
RTC Timestamp
__HAL_RTC_TIMESTAMP_ENABLE

Description:
Enable the RTC TimeStamp
peripheral.
Parameters:
__HANDLE__: specifies the RTC
handle.
Return value:
None

__HAL_RTC_TIMESTAMP_DISABLE

Description:
Disable the RTC TimeStamp
peripheral.
Parameters:
__HANDLE__: specifies the RTC
handle.
Return value:
None

__HAL_RTC_TIMESTAMP_ENABLE_IT

Description:
Enable the RTC TimeStamp
interrupt.
Parameters:
__HANDLE__: specifies the RTC
handle.
__INTERRUPT__: specifies the
RTC TimeStamp interrupt sources
to be enabled or disabled. This
parameter can be:
RTC_IT_TS: TimeStamp
interrupt
Return value:
None

__HAL_RTC_TIMESTAMP_DISABLE_IT

Description:
Disable the RTC TimeStamp
interrupt.
Parameters:
__HANDLE__: specifies the RTC
handle.
__INTERRUPT__: specifies the
RTC TimeStamp interrupt sources
to be enabled or disabled. This
parameter can be:
RTC_IT_TS: TimeStamp
interrupt

DocID025834 Rev 4

725/964

HAL RTC Extension Driver

UM1725
Return value:
None

__HAL_RTC_TIMESTAMP_GET_IT

Description:
Check whether the specified RTC
TimeStamp interrupt has occurred
or not.
Parameters:
__HANDLE__: specifies the RTC
handle.
__INTERRUPT__: specifies the
RTC TimeStamp interrupt to check.
This parameter can be:
RTC_IT_TS: TimeStamp
interrupt
Return value:
None

__HAL_RTC_TIMESTAMP_GET_IT_SOURCE

Description:
Check whether the specified RTC
Time Stamp interrupt has been
enabled or not.
Parameters:
__HANDLE__: specifies the RTC
handle.
__INTERRUPT__: specifies the
RTC Time Stamp interrupt source to
check. This parameter can be:
RTC_IT_TS: TimeStamp
interrupt
Return value:
None

__HAL_RTC_TIMESTAMP_GET_FLAG

Description:
Get the selected RTC TimeStamp's
flag status.
Parameters:
__HANDLE__: specifies the RTC
handle.
__FLAG__: specifies the RTC
TimeStamp flag to check. This
parameter can be:
RTC_FLAG_TSF
RTC_FLAG_TSOVF
Return value:
None

726/964

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver
__HAL_RTC_TIMESTAMP_CLEAR_FLAG

Description:
Clear the RTC Time Stamp's
pending flags.
Parameters:
__HANDLE__: specifies the RTC
handle.
__FLAG__: specifies the RTC Alarm
Flag sources to be enabled or
disabled. This parameter can be:
RTC_FLAG_TSF
Return value:
None

RTC TimeStamp Pins Selection
RTC_TIMESTAMPPIN_DEFAULT
RTC_TIMESTAMPPIN_POS1
RTC TimeStamp Edges Definitions
RTC_TIMESTAMPEDGE_RISING
RTC_TIMESTAMPEDGE_FALLING
RTC WakeUp Timer
__HAL_RTC_WAKEUPTIMER_ENABLE

Description:
Enable the RTC WakeUp Timer
peripheral.
Parameters:
__HANDLE__: specifies the RTC
handle.
Return value:
None

__HAL_RTC_WAKEUPTIMER_DISABLE

Description:
Disable the RTC Wake-up Timer
peripheral.
Parameters:
__HANDLE__: specifies the RTC
handle.
Return value:
None

__HAL_RTC_WAKEUPTIMER_ENABLE_IT

Description:
Enable the RTC WakeUpTimer
interrupt.
Parameters:
__HANDLE__: specifies the RTC

DocID025834 Rev 4

727/964

HAL RTC Extension Driver

UM1725
handle.
__INTERRUPT__: specifies the
RTC WakeUpTimer interrupt
sources to be enabled or disabled.
This parameter can be:
RTC_IT_WUT: WakeUpTimer
A interrupt
Return value:
None

__HAL_RTC_WAKEUPTIMER_DISABLE_IT

Description:
Disable the RTC WakeUpTimer
interrupt.
Parameters:
__HANDLE__: specifies the RTC
handle.
__INTERRUPT__: specifies the
RTC WakeUpTimer interrupt
sources to be enabled or disabled.
This parameter can be:
RTC_IT_WUT: WakeUpTimer
A interrupt
Return value:
None

__HAL_RTC_WAKEUPTIMER_GET_IT

Description:
Check whether the specified RTC
WakeUpTimer interrupt has
occurred or not.
Parameters:
__HANDLE__: specifies the RTC
handle.
__INTERRUPT__: specifies the
RTC WakeUpTimer interrupt to
check. This parameter can be:
RTC_IT_WUT: WakeUpTimer
A interrupt
Return value:
None

__HAL_RTC_WAKEUPTIMER_GET_IT_SOUR
CE

Description:
Check whether the specified RTC
Wake Up timer interrupt has been
enabled or not.
Parameters:
__HANDLE__: specifies the RTC
handle.
__INTERRUPT__: specifies the

728/964

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver
RTC Wake Up timer interrupt
sources to check. This parameter
can be:
RTC_IT_WUT: WakeUpTimer
interrupt
Return value:
None
__HAL_RTC_WAKEUPTIMER_GET_FLAG

Description:
Get the selected RTC
WakeUpTimer's flag status.
Parameters:
__HANDLE__: specifies the RTC
handle.
__FLAG__: specifies the RTC
WakeUpTimer Flag to check. This
parameter can be:
RTC_FLAG_WUTF
RTC_FLAG_WUTWF
Return value:
None

__HAL_RTC_WAKEUPTIMER_CLEAR_FLAG

Description:
Clear the RTC Wake Up timer's
pending flags.
Parameters:
__HANDLE__: specifies the RTC
handle.
__FLAG__: specifies the RTC
Tamper Flag sources to be enabled
or disabled. This parameter can be:
RTC_FLAG_WUTF
Return value:
None

__HAL_RTC_WAKEUPTIMER_EXTI_ENABLE
_IT

Description:
Enable interrupt on the RTC Wakeup Timer associated Exti line.
Return value:
None

__HAL_RTC_WAKEUPTIMER_EXTI_DISABLE
_IT

Description:
Disable interrupt on the RTC Wakeup Timer associated Exti line.
Return value:
None

DocID025834 Rev 4

729/964

HAL RTC Extension Driver
__HAL_RTC_WAKEUPTIMER_EXTI_ENABLE
_EVENT

UM1725
Description:
Enable event on the RTC Wake-up
Timer associated Exti line.
Return value:
None.

__HAL_RTC_WAKEUPTIMER_EXTI_DISABLE
_EVENT

Description:
Disable event on the RTC Wake-up
Timer associated Exti line.
Return value:
None.

__HAL_RTC_WAKEUPTIMER_EXTI_ENABLE
_FALLING_EDGE

Description:
Enable falling edge trigger on the
RTC Wake-up Timer associated
Exti line.
Return value:
None.

__HAL_RTC_WAKEUPTIMER_EXTI_DISABLE
_FALLING_EDGE

Description:
Disable falling edge trigger on the
RTC Wake-up Timer associated
Exti line.
Return value:
None.

__HAL_RTC_WAKEUPTIMER_EXTI_ENABLE
_RISING_EDGE

Description:
Enable rising edge trigger on the
RTC Wake-up Timer associated
Exti line.
Return value:
None.

__HAL_RTC_WAKEUPTIMER_EXTI_DISABLE
_RISING_EDGE

Description:
Disable rising edge trigger on the
RTC Wake-up Timer associated
Exti line.
Return value:
None.

__HAL_RTC_WAKEUPTIMER_EXTI_ENABLE
_RISING_FALLING_EDGE

Description:
Enable rising & falling edge trigger
on the RTC Wake-up Timer
associated Exti line.
Return value:
None.

730/964

DocID025834 Rev 4

UM1725

HAL RTC Extension Driver
__HAL_RTC_WAKEUPTIMER_EXTI_DISABLE
_RISING_FALLING_EDGE

Description:
Disable rising & falling edge trigger
on the RTC Wake-up Timer
associated Exti line.
Return value:
None.

__HAL_RTC_WAKEUPTIMER_EXTI_GET_FL
AG

Description:
Check whether the RTC Wake-up
Timer associated Exti line interrupt
flag is set or not.
Return value:
Line: Status.

__HAL_RTC_WAKEUPTIMER_EXTI_CLEAR_
FLAG

Description:
Clear the RTC Wake-up Timer
associated Exti line flag.
Return value:
None.

__HAL_RTC_WAKEUPTIMER_EXTI_GENERA
TE_SWIT

Description:
Generate a Software interrupt on
the RTC Wake-up Timer
associated Exti line.
Return value:
None.

RTC Wake-up Timer Definitions
RTC_WAKEUPCLOCK_RTCCLK_DIV16
RTC_WAKEUPCLOCK_RTCCLK_DIV8
RTC_WAKEUPCLOCK_RTCCLK_DIV4
RTC_WAKEUPCLOCK_RTCCLK_DIV2
RTC_WAKEUPCLOCK_CK_SPRE_16BITS
RTC_WAKEUPCLOCK_CK_SPRE_17BITS

DocID025834 Rev 4

731/964

HAL SAI Generic Driver

UM1725

54

HAL SAI Generic Driver

54.1

SAI Firmware driver registers structures

54.1.1

SAI_InitTypeDef
Data Fields
uint32_t AudioMode
uint32_t Synchro
uint32_t SynchroExt
uint32_t OutputDrive
uint32_t NoDivider
uint32_t FIFOThreshold
uint32_t ClockSource
uint32_t AudioFrequency
uint32_t Mckdiv
uint32_t MonoStereoMode
uint32_t CompandingMode
uint32_t TriState
uint32_t Protocol
uint32_t DataSize
uint32_t FirstBit
uint32_t ClockStrobing

Field Documentation
uint32_t SAI_InitTypeDef::AudioMode
Specifies the SAI Block audio Mode. This parameter can be a value of
SAI_Block_Mode
uint32_t SAI_InitTypeDef::Synchro
Specifies SAI Block synchronization This parameter can be a value of
SAI_Block_Synchronization
uint32_t SAI_InitTypeDef::SynchroExt
Specifies SAI external output synchronization, this setup is common for BlockA and
BlockB This parameter can be a value of SAI_Block_SyncExt
Note:: If both audio blocks of same SAI are used, this parameter has to be set to the
same value for each audio block
uint32_t SAI_InitTypeDef::OutputDrive
Specifies when SAI Block outputs are driven. This parameter can be a value of
SAI_Block_Output_Drive
Note:this value has to be set before enabling the audio block but after the audio block
configuration.
uint32_t SAI_InitTypeDef::NoDivider
Specifies whether master clock will be divided or not. This parameter can be a value
of SAI_Block_NoDivider
Note:If bit NODIV in the SAI_xCR1 register is cleared, the frame length should be
aligned to a number equal to a power of 2, from 8 to 256. If bit NODIV in the
SAI_xCR1 register is set, the frame length can take any of the values without

732/964

DocID025834 Rev 4

UM1725

54.1.2

HAL SAI Generic Driver
constraint since the input clock of the audio block should be equal to the bit clock.
There is no MCLK_x clock which can be output.
uint32_t SAI_InitTypeDef::FIFOThreshold
Specifies SAI Block FIFO threshold. This parameter can be a value of
SAI_Block_Fifo_Threshold
uint32_t SAI_InitTypeDef::ClockSource
Specifies the SAI Block x Clock source. This parameter is not used for STM32F446xx
devices.
uint32_t SAI_InitTypeDef::AudioFrequency
Specifies the audio frequency sampling. This parameter can be a value of
SAI_Audio_Frequency
uint32_t SAI_InitTypeDef::Mckdiv
Specifies the master clock divider, the parameter will be used if for AudioFrequency
the user choice This parameter must be a number between Min_Data = 0 and
Max_Data = 15
uint32_t SAI_InitTypeDef::MonoStereoMode
Specifies if the mono or stereo mode is selected. This parameter can be a value of
SAI_Mono_Stereo_Mode
uint32_t SAI_InitTypeDef::CompandingMode
Specifies the companding mode type. This parameter can be a value of
SAI_Block_Companding_Mode
uint32_t SAI_InitTypeDef::TriState
Specifies the companding mode type. This parameter can be a value of
SAI_TRIState_Management
uint32_t SAI_InitTypeDef::Protocol
Specifies the SAI Block protocol. This parameter can be a value of
SAI_Block_Protocol
uint32_t SAI_InitTypeDef::DataSize
Specifies the SAI Block data size. This parameter can be a value of
SAI_Block_Data_Size
uint32_t SAI_InitTypeDef::FirstBit
Specifies whether data transfers start from MSB or LSB bit. This parameter can be a
value of SAI_Block_MSB_LSB_transmission
uint32_t SAI_InitTypeDef::ClockStrobing
Specifies the SAI Block clock strobing edge sensitivity. This parameter can be a value
of SAI_Block_Clock_Strobing

SAI_FrameInitTypeDef
Data Fields
uint32_t FrameLength
uint32_t ActiveFrameLength
uint32_t FSDefinition
uint32_t FSPolarity
uint32_t FSOffset

Field Documentation
uint32_t SAI_FrameInitTypeDef::FrameLength
Specifies the Frame length, the number of SCK clocks for each audio frame. This
parameter must be a number between Min_Data = 8 and Max_Data = 256.
DocID025834 Rev 4

733/964

HAL SAI Generic Driver
UM1725
Note:If master clock MCLK_x pin is declared as an output, the frame length should be
aligned to a number equal to power of 2 in order to keep in an audio frame, an integer
number of MCLK pulses by bit Clock.
uint32_t SAI_FrameInitTypeDef::ActiveFrameLength
Specifies the Frame synchronization active level length. This Parameter specifies the
length in number of bit clock (SCK + 1) of the active level of FS signal in audio frame.
This parameter must be a number between Min_Data = 1 and Max_Data = 128
uint32_t SAI_FrameInitTypeDef::FSDefinition
Specifies the Frame synchronization definition. This parameter can be a value of
SAI_Block_FS_Definition
uint32_t SAI_FrameInitTypeDef::FSPolarity
Specifies the Frame synchronization Polarity. This parameter can be a value of
SAI_Block_FS_Polarity
uint32_t SAI_FrameInitTypeDef::FSOffset
Specifies the Frame synchronization Offset. This parameter can be a value of
SAI_Block_FS_Offset

54.1.3

SAI_SlotInitTypeDef
Data Fields
uint32_t FirstBitOffset
uint32_t SlotSize
uint32_t SlotNumber
uint32_t SlotActive

Field Documentation
uint32_t SAI_SlotInitTypeDef::FirstBitOffset
Specifies the position of first data transfer bit in the slot. This parameter must be a
number between Min_Data = 0 and Max_Data = 24
uint32_t SAI_SlotInitTypeDef::SlotSize
Specifies the Slot Size. This parameter can be a value of SAI_Block_Slot_Size
uint32_t SAI_SlotInitTypeDef::SlotNumber
Specifies the number of slot in the audio frame. This parameter must be a number
between Min_Data = 1 and Max_Data = 16
uint32_t SAI_SlotInitTypeDef::SlotActive
Specifies the slots in audio frame that will be activated. This parameter can be a
value of SAI_Block_Slot_Active

54.1.4

__SAI_HandleTypeDef
Data Fields
SAI_Block_TypeDef * Instance
SAI_InitTypeDef Init
SAI_FrameInitTypeDef FrameInit
SAI_SlotInitTypeDef SlotInit
uint8_t * pBuffPtr
uint16_t XferSize

734/964

DocID025834 Rev 4

UM1725

HAL SAI Generic Driver
uint16_t XferCount
DMA_HandleTypeDef * hdmatx
DMA_HandleTypeDef * hdmarx
SAIcallback mutecallback
void(* InterruptServiceRoutine
HAL_LockTypeDef Lock
__IO HAL_SAI_StateTypeDef State
__IO uint32_t ErrorCode

Field Documentation
SAI_Block_TypeDef* __SAI_HandleTypeDef::Instance
SAI Blockx registers base address
SAI_InitTypeDef __SAI_HandleTypeDef::Init
SAI communication parameters
SAI_FrameInitTypeDef __SAI_HandleTypeDef::FrameInit
SAI Frame configuration parameters
SAI_SlotInitTypeDef __SAI_HandleTypeDef::SlotInit
SAI Slot configuration parameters
uint8_t* __SAI_HandleTypeDef::pBuffPtr
Pointer to SAI transfer Buffer
uint16_t __SAI_HandleTypeDef::XferSize
SAI transfer size
uint16_t __SAI_HandleTypeDef::XferCount
SAI transfer counter
DMA_HandleTypeDef* __SAI_HandleTypeDef::hdmatx
SAI Tx DMA handle parameters
DMA_HandleTypeDef* __SAI_HandleTypeDef::hdmarx
SAI Rx DMA handle parameters
SAIcallback __SAI_HandleTypeDef::mutecallback
SAI mute callback
void(* __SAI_HandleTypeDef::InterruptServiceRoutine)(struct
__SAI_HandleTypeDef *hsai)
HAL_LockTypeDef __SAI_HandleTypeDef::Lock
SAI locking object
__IO HAL_SAI_StateTypeDef __SAI_HandleTypeDef::State
SAI communication state
__IO uint32_t __SAI_HandleTypeDef::ErrorCode
SAI Error code

54.2

SAI Firmware driver API description

54.2.1

How to use this driver
The SAI HAL driver can be used as follows:
1.
2.

Declare a SAI_HandleTypeDef handle structure (eg. SAI_HandleTypeDef hsai).
Initialize the SAI low level resources by implementing the HAL_SAI_MspInit() API:
a.
Enable the SAI interface clock.
b.
SAI pins configuration:
Enable the clock for the SAI GPIOs.
Configure these SAI pins as alternate function pull-up.
DocID025834 Rev 4

735/964

HAL SAI Generic Driver
UM1725
c.
NVIC configuration if you need to use interrupt process (HAL_SAI_Transmit_IT()
and HAL_SAI_Receive_IT() APIs):
Configure the SAI interrupt priority.
Enable the NVIC SAI IRQ handle.
d.
DMA Configuration if you need to use DMA process (HAL_SAI_Transmit_DMA()
and HAL_SAI_Receive_DMA() APIs):
Declare a DMA handle structure for the Tx/Rx stream.
Enable the DMAx interface clock.
Configure the declared DMA handle structure with the required Tx/Rx
parameters.
Configure the DMA Tx/Rx Stream.
Associate the initialized DMA handle to the SAI DMA Tx/Rx handle.
Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Tx/Rx Stream.
3.
The initialization can be done by two ways
a.
Expert mode : Initialize the structures Init, FrameInit and SlotInit and call
HAL_SAI_Init().
b.
Simplified mode : Initialize the high part of Init Structure and call
HAL_SAI_InitProtocol().
The specific SAI interrupts (FIFO request and Overrun underrun interrupt) will be
managed using the macros __HAL_SAI_ENABLE_IT() and
__HAL_SAI_DISABLE_IT() inside the transmit and receive process.

SAI Clock Source configuration is managed differently depending on the selected
STM32F4 devices :
For STM32F446xx devices, the configuration is managed through
RCCEx_PeriphCLKConfig() function in the HAL RCC drivers
For STM32F439xx/STM32F437xx/STM32F429xx/STM32F427xx devices,
the configuration is managed within HAL SAI drivers through HAL_SAI_Init()
function using ClockSource field of SAI_InitTypeDef structure.

Make sure that either:
I2S PLL is configured or
SAI PLL is configured or
External clock source is configured after setting correctly the define constant
EXTERNAL_CLOCK_VALUE in the stm32f4xx_hal_conf.h file.

In master Tx mode: enabling the audio block immediately generates the bit clock
for the external slaves even if there is no data in the FIFO, However FS signal
generation is conditioned by the presence of data in the FIFO.

In master Rx mode: enabling the audio block immediately generates the bit clock
and FS signal for the external slaves.

736/964

DocID025834 Rev 4

UM1725

HAL SAI Generic Driver
It is mandatory to respect the following conditions in order to avoid bad SAI
behavior:
First bit Offset <= (SLOT size - Data size)
Data size <= SLOT size
Number of SLOT x SLOT size = Frame length
The number of slots should be even when
SAI_FS_CHANNEL_IDENTIFICATION is selected.
Three operation modes are available within this driver :

Polling mode IO operation
Send an amount of data in blocking mode using HAL_SAI_Transmit()
Receive an amount of data in blocking mode using HAL_SAI_Receive()

Interrupt mode IO operation
Send an amount of data in non-blocking mode using HAL_SAI_Transmit_IT()
At transmission end of transfer HAL_SAI_TxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_SAI_TxCpltCallback()
Receive an amount of data in non-blocking mode using HAL_SAI_Receive_IT()
At reception end of transfer HAL_SAI_RxCpltCallback() is executed and user can add
his own code by customization of function pointer HAL_SAI_RxCpltCallback()
In case of flag error, HAL_SAI_ErrorCallback() function is executed and user can add
his own code by customization of function pointer HAL_SAI_ErrorCallback()

DMA mode IO operation
Send an amount of data in non-blocking mode (DMA) using
HAL_SAI_Transmit_DMA()
At transmission end of transfer HAL_SAI_TxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_SAI_TxCpltCallback()
Receive an amount of data in non-blocking mode (DMA) using
HAL_SAI_Receive_DMA()
At reception end of transfer HAL_SAI_RxCpltCallback() is executed and user can add
his own code by customization of function pointer HAL_SAI_RxCpltCallback()
In case of flag error, HAL_SAI_ErrorCallback() function is executed and user can add
his own code by customization of function pointer HAL_SAI_ErrorCallback()
Pause the DMA Transfer using HAL_SAI_DMAPause()
Resume the DMA Transfer using HAL_SAI_DMAResume()
Stop the DMA Transfer using HAL_SAI_DMAStop()

SAI HAL driver additional function list
Below the list the others API available SAI HAL driver :
HAL_SAI_EnableTxMuteMode(): Enable the mute in tx mode
HAL_SAI_DisableTxMuteMode(): Disable the mute in tx mode
HAL_SAI_EnableRxMuteMode(): Enable the mute in Rx mode
HAL_SAI_DisableRxMuteMode(): Disable the mute in Rx mode
DocID025834 Rev 4

737/964

HAL SAI Generic Driver

UM1725

HAL_SAI_FlushRxFifo(): Flush the rx fifo.
HAL_SAI_Abort(): Abort the current transfer

SAI HAL driver macros list
Below the list of most used macros in SAI HAL driver :
__HAL_SAI_ENABLE(): Enable the SAI peripheral
__HAL_SAI_DISABLE(): Disable the SAI peripheral
__HAL_SAI_ENABLE_IT(): Enable the specified SAI interrupts
__HAL_SAI_DISABLE_IT(): Disable the specified SAI interrupts
__HAL_SAI_GET_IT_SOURCE(): Check if the specified SAI interrupt source is
enabled or disabled
__HAL_SAI_GET_FLAG(): Check whether the specified SAI flag is set or not

54.2.2

Initialization and de-initialization functions
This subsection provides a set of functions allowing to initialize and de-initialize the SAIx
peripheral:
User must implement HAL_SAI_MspInit() function in which he configures all related
peripherals resources (CLOCK, GPIO, DMA, IT and NVIC ).
Call the function HAL_SAI_Init() to configure the selected device with the selected
configuration:
Mode (Master/slave TX/RX)
Protocol
Data Size
MCLK Output
Audio frequency
FIFO Threshold
Frame Config
Slot Config
Call the function HAL_SAI_DeInit() to restore the default configuration of the selected
SAI peripheral.
This section contains the following APIs:
HAL_SAI_InitProtocol()
HAL_SAI_Init()
HAL_SAI_DeInit()
HAL_SAI_MspInit()
HAL_SAI_MspDeInit()

54.2.3

IO operation functions
This subsection provides a set of functions allowing to manage the SAI data transfers.
There are two modes of transfer:
Blocking mode : The communication is performed in the polling mode. The
status of all data processing is returned by the same function after finishing
transfer.
No-Blocking mode : The communication is performed using Interrupts or DMA.
These functions return the status of the transfer startup. The end of the data
processing will be indicated through the dedicated SAI IRQ when using Interrupt
mode or the DMA IRQ when using DMA mode.
Blocking mode functions are :
HAL_SAI_Transmit()

738/964

DocID025834 Rev 4

UM1725

HAL SAI Generic Driver
HAL_SAI_Receive()
HAL_SAI_TransmitReceive()
Non Blocking mode functions with Interrupt are :
HAL_SAI_Transmit_IT()
HAL_SAI_Receive_IT()
HAL_SAI_TransmitReceive_IT()
Non Blocking mode functions with DMA are :
HAL_SAI_Transmit_DMA()
HAL_SAI_Receive_DMA()
HAL_SAI_TransmitReceive_DMA()
A set of Transfer Complete Callbacks are provided in non Blocking mode:
HAL_SAI_TxCpltCallback()
HAL_SAI_RxCpltCallback()
HAL_SAI_ErrorCallback()
This section contains the following APIs:
HAL_SAI_Transmit()
HAL_SAI_Receive()
HAL_SAI_Transmit_IT()
HAL_SAI_Receive_IT()
HAL_SAI_DMAPause()
HAL_SAI_DMAResume()
HAL_SAI_DMAStop()
HAL_SAI_Abort()
HAL_SAI_Transmit_DMA()
HAL_SAI_Receive_DMA()
HAL_SAI_EnableTxMuteMode()
HAL_SAI_DisableTxMuteMode()
HAL_SAI_EnableRxMuteMode()
HAL_SAI_DisableRxMuteMode()
HAL_SAI_IRQHandler()
HAL_SAI_TxCpltCallback()
HAL_SAI_TxHalfCpltCallback()
HAL_SAI_RxCpltCallback()
HAL_SAI_RxHalfCpltCallback()
HAL_SAI_ErrorCallback()

54.2.4

Peripheral State and Errors functions
This subsection permits to get in run-time the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_SAI_GetState()
HAL_SAI_GetError()

54.2.5

Detailed description of functions
HAL_SAI_InitProtocol
Function Name

HAL_StatusTypeDef HAL_SAI_InitProtocol
(SAI_HandleTypeDef * hsai, uint32_t protocol, uint32_t
datasize, uint32_t nbslot)

Function Description

Initialize the structure FrameInit, SlotInit and the low part of Init
DocID025834 Rev 4

739/964

HAL SAI Generic Driver

UM1725
according to the specified parameters and call the function
HAL_SAI_Init to initialize the SAI block.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.
protocol: one of the supported protocol SAI Supported
protocol
datasize: one of the supported datasize SAI protocol data
size the configuration information for SAI module.
nbslot: Number of slot.

Return values

HAL: status

HAL_SAI_Init
Function Name

HAL_StatusTypeDef HAL_SAI_Init (SAI_HandleTypeDef * hsai)

Function Description

Initialize the SAI according to the specified parameters.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

HAL: status

HAL_SAI_DeInit
Function Name

HAL_StatusTypeDef HAL_SAI_DeInit (SAI_HandleTypeDef *
hsai)

Function Description

DeInitialize the SAI peripheral.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

HAL: status

HAL_SAI_MspInit
Function Name

void HAL_SAI_MspInit (SAI_HandleTypeDef * hsai)

Function Description

Initialize the SAI MSP.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

None

HAL_SAI_MspDeInit

740/964

Function Name

void HAL_SAI_MspDeInit (SAI_HandleTypeDef * hsai)

Function Description

DeInitialize the SAI MSP.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

None

DocID025834 Rev 4

UM1725

HAL SAI Generic Driver

HAL_SAI_Transmit
Function Name

HAL_StatusTypeDef HAL_SAI_Transmit (SAI_HandleTypeDef
* hsai, uint8_t * pData, uint16_t Size, uint32_t Timeout)

Function Description

Transmit an amount of data in blocking mode.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_SAI_Receive
Function Name

HAL_StatusTypeDef HAL_SAI_Receive (SAI_HandleTypeDef *
hsai, uint8_t * pData, uint16_t Size, uint32_t Timeout)

Function Description

Receive an amount of data in blocking mode.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.
pData: Pointer to data buffer
Size: Amount of data to be received
Timeout: Timeout duration

Return values

HAL: status

HAL_SAI_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_SAI_Transmit_IT
(SAI_HandleTypeDef * hsai, uint8_t * pData, uint16_t Size)

Function Description

Transmit an amount of data in non-blocking mode with Interrupt.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_SAI_Receive_IT
Function Name

HAL_StatusTypeDef HAL_SAI_Receive_IT
(SAI_HandleTypeDef * hsai, uint8_t * pData, uint16_t Size)

Function Description

Receive an amount of data in non-blocking mode with Interrupt.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.
pData: Pointer to data buffer
Size: Amount of data to be received

Return values

HAL: status

DocID025834 Rev 4

741/964

HAL SAI Generic Driver

UM1725

HAL_SAI_Transmit_DMA
Function Name

HAL_StatusTypeDef HAL_SAI_Transmit_DMA
(SAI_HandleTypeDef * hsai, uint8_t * pData, uint16_t Size)

Function Description

Transmit an amount of data in non-blocking mode with DMA.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_SAI_Receive_DMA
Function Name

HAL_StatusTypeDef HAL_SAI_Receive_DMA
(SAI_HandleTypeDef * hsai, uint8_t * pData, uint16_t Size)

Function Description

Receive an amount of data in non-blocking mode with DMA.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.
pData: Pointer to data buffer
Size: Amount of data to be received

Return values

HAL: status

HAL_SAI_DMAPause
Function Name

HAL_StatusTypeDef HAL_SAI_DMAPause
(SAI_HandleTypeDef * hsai)

Function Description

Pause the audio stream playing from the Media.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

HAL: status

HAL_SAI_DMAResume
Function Name

HAL_StatusTypeDef HAL_SAI_DMAResume
(SAI_HandleTypeDef * hsai)

Function Description

Resume the audio stream playing from the Media.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

HAL: status

HAL_SAI_DMAStop
Function Name

HAL_StatusTypeDef HAL_SAI_DMAStop (SAI_HandleTypeDef
* hsai)

Function Description

Stop the audio stream playing from the Media.

Parameters

742/964

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.
DocID025834 Rev 4

UM1725

HAL SAI Generic Driver
Return values

HAL: status

HAL_SAI_Abort
Function Name

HAL_StatusTypeDef HAL_SAI_Abort (SAI_HandleTypeDef *
hsai)

Function Description

Abort the current transfer and disable the SAI.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

HAL: status

HAL_SAI_EnableTxMuteMode
Function Name

HAL_StatusTypeDef HAL_SAI_EnableTxMuteMode
(SAI_HandleTypeDef * hsai, uint16_t val)

Function Description

Enable the Tx mute mode.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.
val: value sent during the mute SAI Block Mute Value

Return values

HAL: status

HAL_SAI_DisableTxMuteMode
Function Name

HAL_StatusTypeDef HAL_SAI_DisableTxMuteMode
(SAI_HandleTypeDef * hsai)

Function Description

Disable the Tx mute mode.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

HAL: status

HAL_SAI_EnableRxMuteMode
Function Name

HAL_StatusTypeDef HAL_SAI_EnableRxMuteMode
(SAI_HandleTypeDef * hsai, SAIcallback callback, uint16_t
counter)

Function Description

Enable the Rx mute detection.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.
callback: function called when the mute is detected.
counter: number a data before mute detection max 63.

Return values

HAL: status

HAL_SAI_DisableRxMuteMode
Function Name

HAL_StatusTypeDef HAL_SAI_DisableRxMuteMode
(SAI_HandleTypeDef * hsai)

Function Description

Disable the Rx mute detection.
DocID025834 Rev 4

743/964

HAL SAI Generic Driver
Parameters

UM1725
hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

HAL: status

HAL_SAI_IRQHandler
Function Name

void HAL_SAI_IRQHandler (SAI_HandleTypeDef * hsai)

Function Description

Handle SAI interrupt request.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

None

HAL_SAI_TxHalfCpltCallback
Function Name

void HAL_SAI_TxHalfCpltCallback (SAI_HandleTypeDef *
hsai)

Function Description

Tx Transfer Half completed callback.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

None

HAL_SAI_TxCpltCallback
Function Name

void HAL_SAI_TxCpltCallback (SAI_HandleTypeDef * hsai)

Function Description

Tx Transfer completed callback.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

None

HAL_SAI_RxHalfCpltCallback
Function Name

void HAL_SAI_RxHalfCpltCallback (SAI_HandleTypeDef *
hsai)

Function Description

Rx Transfer half completed callback.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

None

HAL_SAI_RxCpltCallback

744/964

Function Name

void HAL_SAI_RxCpltCallback (SAI_HandleTypeDef * hsai)

Function Description

Rx Transfer completed callback.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

None
DocID025834 Rev 4

UM1725

HAL SAI Generic Driver

HAL_SAI_ErrorCallback
Function Name

void HAL_SAI_ErrorCallback (SAI_HandleTypeDef * hsai)

Function Description

SAI error callback.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

None

HAL_SAI_GetState
Function Name

HAL_SAI_StateTypeDef HAL_SAI_GetState
(SAI_HandleTypeDef * hsai)

Function Description

Return the SAI handle state.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

HAL: state

HAL_SAI_GetError
Function Name

uint32_t HAL_SAI_GetError (SAI_HandleTypeDef * hsai)

Function Description

Return the SAI error code.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for the specified SAI Block.

Return values

SAI: Error Code

54.3

SAI Firmware driver defines

54.3.1

SAI
SAI Audio Frequency
SAI_AUDIO_FREQUENCY_192K
SAI_AUDIO_FREQUENCY_96K
SAI_AUDIO_FREQUENCY_48K
SAI_AUDIO_FREQUENCY_44K
SAI_AUDIO_FREQUENCY_32K
SAI_AUDIO_FREQUENCY_22K
SAI_AUDIO_FREQUENCY_16K
SAI_AUDIO_FREQUENCY_11K
SAI_AUDIO_FREQUENCY_8K
SAI_AUDIO_FREQUENCY_MCKDIV
SAI Block Clock Strobing
SAI_CLOCKSTROBING_FALLINGEDGE
SAI_CLOCKSTROBING_RISINGEDGE
DocID025834 Rev 4

745/964

HAL SAI Generic Driver
SAI Block Companding Mode
SAI_NOCOMPANDING
SAI_ULAW_1CPL_COMPANDING
SAI_ALAW_1CPL_COMPANDING
SAI_ULAW_2CPL_COMPANDING
SAI_ALAW_2CPL_COMPANDING
SAI Block Data Size
SAI_DATASIZE_8
SAI_DATASIZE_10
SAI_DATASIZE_16
SAI_DATASIZE_20
SAI_DATASIZE_24
SAI_DATASIZE_32
SAI Block Fifo Status Level
SAI_FIFOSTATUS_EMPTY
SAI_FIFOSTATUS_LESS1QUARTERFULL
SAI_FIFOSTATUS_1QUARTERFULL
SAI_FIFOSTATUS_HALFFULL
SAI_FIFOSTATUS_3QUARTERFULL
SAI_FIFOSTATUS_FULL
SAI Block Fifo Threshold
SAI_FIFOTHRESHOLD_EMPTY
SAI_FIFOTHRESHOLD_1QF
SAI_FIFOTHRESHOLD_HF
SAI_FIFOTHRESHOLD_3QF
SAI_FIFOTHRESHOLD_FULL
SAI Block Flags Definition
SAI_FLAG_OVRUDR
SAI_FLAG_MUTEDET
SAI_FLAG_WCKCFG
SAI_FLAG_FREQ
SAI_FLAG_CNRDY
SAI_FLAG_AFSDET
SAI_FLAG_LFSDET
SAI Block FS Definition
SAI_FS_STARTFRAME

746/964

DocID025834 Rev 4

UM1725

UM1725

HAL SAI Generic Driver
SAI_FS_CHANNEL_IDENTIFICATION
SAI Block FS Offset
SAI_FS_FIRSTBIT
SAI_FS_BEFOREFIRSTBIT
SAI Block FS Polarity
SAI_FS_ACTIVE_LOW
SAI_FS_ACTIVE_HIGH
SAI Block Interrupts Definition
SAI_IT_OVRUDR
SAI_IT_MUTEDET
SAI_IT_WCKCFG
SAI_IT_FREQ
SAI_IT_CNRDY
SAI_IT_AFSDET
SAI_IT_LFSDET
SAI Block Mode
SAI_MODEMASTER_TX
SAI_MODEMASTER_RX
SAI_MODESLAVE_TX
SAI_MODESLAVE_RX
SAI Block MSB LSB transmission
SAI_FIRSTBIT_MSB
SAI_FIRSTBIT_LSB
SAI Block Mute Value
SAI_ZERO_VALUE
SAI_LAST_SENT_VALUE
SAI Block NoDivider
SAI_MASTERDIVIDER_ENABLE
SAI_MASTERDIVIDER_DISABLE
SAI Block Output Drive
SAI_OUTPUTDRIVE_DISABLE
SAI_OUTPUTDRIVE_ENABLE
SAI Block Protocol
SAI_FREE_PROTOCOL
SAI_SPDIF_PROTOCOL
SAI_AC97_PROTOCOL
SAI Block Slot Active
DocID025834 Rev 4

747/964

HAL SAI Generic Driver
SAI_SLOT_NOTACTIVE

UM1725

SAI_SLOTACTIVE_0
SAI_SLOTACTIVE_1
SAI_SLOTACTIVE_2
SAI_SLOTACTIVE_3
SAI_SLOTACTIVE_4
SAI_SLOTACTIVE_5
SAI_SLOTACTIVE_6
SAI_SLOTACTIVE_7
SAI_SLOTACTIVE_8
SAI_SLOTACTIVE_9
SAI_SLOTACTIVE_10
SAI_SLOTACTIVE_11
SAI_SLOTACTIVE_12
SAI_SLOTACTIVE_13
SAI_SLOTACTIVE_14
SAI_SLOTACTIVE_15
SAI_SLOTACTIVE_ALL
SAI Block Slot Size
SAI_SLOTSIZE_DATASIZE
SAI_SLOTSIZE_16B
SAI_SLOTSIZE_32B
SAI External synchronisation
SAI_SYNCEXT_DISABLE
SAI_SYNCEXT_OUTBLOCKA_ENABLE
SAI_SYNCEXT_OUTBLOCKB_ENABLE
SAI Block Synchronization
SAI_ASYNCHRONOUS

Asynchronous

SAI_SYNCHRONOUS

Synchronous with other block of same SAI

SAI_SYNCHRONOUS_EXT_SAI1

Synchronous with other SAI, SAI1

SAI_SYNCHRONOUS_EXT_SAI2

Synchronous with other SAI, SAI2

SAI Clock Source
SAI_CLKSOURCE_PLLSAI
SAI_CLKSOURCE_PLLI2S
SAI_CLKSOURCE_EXT
SAI_CLKSOURCE_NA

748/964

No applicable for STM32F446xx

DocID025834 Rev 4

UM1725

HAL SAI Generic Driver
SAI Error Code
HAL_SAI_ERROR_NONE

No error

HAL_SAI_ERROR_OVR

Overrun Error

HAL_SAI_ERROR_UDR

Underrun error

HAL_SAI_ERROR_AFSDET

Anticipated Frame synchronisation detection

HAL_SAI_ERROR_LFSDET

Late Frame synchronisation detection

HAL_SAI_ERROR_CNREADY

codec not ready

HAL_SAI_ERROR_WCKCFG

Wrong clock configuration

HAL_SAI_ERROR_TIMEOUT

Timeout error

HAL_SAI_ERROR_DMA

DMA error

SAI Exported Macros
__HAL_SAI_RESET_HANDLE_STATE

Description:
Reset SAI handle state.
Parameters:
__HANDLE__: specifies the SAI Handle.
Return value:
NoneS

__HAL_SAI_ENABLE_IT

Description:
Enable or disable the specified SAI
interrupts.
Parameters:
__HANDLE__: specifies the SAI Handle.
__INTERRUPT__: specifies the interrupt
source to enable or disable. This parameter
can be one of the following values:
SAI_IT_OVRUDR: Overrun underrun
interrupt enable
SAI_IT_MUTEDET: Mute detection
interrupt enable
SAI_IT_WCKCFG: Wrong Clock
Configuration interrupt enable
SAI_IT_FREQ: FIFO request interrupt
enable
SAI_IT_CNRDY: Codec not ready
interrupt enable
SAI_IT_AFSDET: Anticipated frame
synchronization detection interrupt
enable
SAI_IT_LFSDET: Late frame
synchronization detection interrupt
enable
Return value:
None
DocID025834 Rev 4

749/964

HAL SAI Generic Driver
__HAL_SAI_DISABLE_IT

UM1725

__HAL_SAI_GET_IT_SOURCE

Description:
Check if the specified SAI interrupt source is
enabled or disabled.
Parameters:
__HANDLE__: specifies the SAI Handle.
This parameter can be SAI where x: 1, 2, or
3 to select the SAI peripheral.
__INTERRUPT__: specifies the SAI
interrupt source to check. This parameter
can be one of the following values:
SAI_IT_OVRUDR: Overrun underrun
interrupt enable
SAI_IT_MUTEDET: Mute detection
interrupt enable
SAI_IT_WCKCFG: Wrong Clock
Configuration interrupt enable
SAI_IT_FREQ: FIFO request interrupt
enable
SAI_IT_CNRDY: Codec not ready
interrupt enable
SAI_IT_AFSDET: Anticipated frame
synchronization detection interrupt
enable
SAI_IT_LFSDET: Late frame
synchronization detection interrupt
enable
Return value:
The: new state of __INTERRUPT__ (TRUE
or FALSE).

__HAL_SAI_GET_FLAG

Description:
Check whether the specified SAI flag is set
or not.
Parameters:
__HANDLE__: specifies the SAI Handle.
__FLAG__: specifies the flag to check. This
parameter can be one of the following
values:
SAI_FLAG_OVRUDR: Overrun
underrun flag.
SAI_FLAG_MUTEDET: Mute detection
flag.
SAI_FLAG_WCKCFG: Wrong Clock
Configuration flag.
SAI_FLAG_FREQ: FIFO request flag.
SAI_FLAG_CNRDY: Codec not ready
flag.
SAI_FLAG_AFSDET: Anticipated
frame synchronization detection flag.

750/964

DocID025834 Rev 4

UM1725

HAL SAI Generic Driver
SAI_FLAG_LFSDET: Late frame
synchronization detection flag.
Return value:
The: new state of __FLAG__ (TRUE or
FALSE).
__HAL_SAI_CLEAR_FLAG

Description:
Clear the specified SAI pending flag.
Parameters:
__HANDLE__: specifies the SAI Handle.
__FLAG__: specifies the flag to check. This
parameter can be any combination of the
following values:
SAI_FLAG_OVRUDR: Clear Overrun
underrun
SAI_FLAG_MUTEDET: Clear Mute
detection
SAI_FLAG_WCKCFG: Clear Wrong
Clock Configuration
SAI_FLAG_FREQ: Clear FIFO request
SAI_FLAG_CNRDY: Clear Codec not
ready
SAI_FLAG_AFSDET: Clear Anticipated
frame synchronization detection
SAI_FLAG_LFSDET: Clear Late frame
synchronization detection
Return value:
None

__HAL_SAI_ENABLE

Description:
Enable SAI.
Parameters:
__HANDLE__: specifies the SAI Handle.
Return value:
None

__HAL_SAI_DISABLE

Description:
Disable SAI.
Parameters:
__HANDLE__: specifies the SAI Handle.
Return value:
None

SAI Mono Stereo Mode
SAI_STEREOMODE
SAI_MONOMODE
DocID025834 Rev 4

751/964

HAL SAI Generic Driver
SAI Supported protocol

UM1725

SAI_I2S_STANDARD
SAI_I2S_MSBJUSTIFIED
SAI_I2S_LSBJUSTIFIED
SAI_PCM_LONG
SAI_PCM_SHORT
SAI protocol data size
SAI_PROTOCOL_DATASIZE_16BIT
SAI_PROTOCOL_DATASIZE_16BITEXTENDED
SAI_PROTOCOL_DATASIZE_24BIT
SAI_PROTOCOL_DATASIZE_32BIT
SAI TRIState Management
SAI_OUTPUT_NOTRELEASED
SAI_OUTPUT_RELEASED

752/964

DocID025834 Rev 4

UM1725

HAL SAI Extension Driver

55

HAL SAI Extension Driver

55.1

SAIEx Firmware driver API description

55.1.1

SAI peripheral extension features
Comparing to other previous devices, the SAI interface for STM32F446xx devices contains
the following additional features :
Possibility to be clocked from PLLR

55.1.2

How to use this driver
This driver provides functions to manage several sources to clock SAI

55.1.3

Extension features Functions
This subsection provides a set of functions allowing to manage the possible SAI clock
sources.
This section contains the following APIs:
SAI_BlockSynchroConfig()
SAI_GetInputClock()

55.1.4

Detailed description of functions
SAI_BlockSynchroConfig
Function Name

void SAI_BlockSynchroConfig (SAI_HandleTypeDef * hsai)

Function Description

Configure SAI Block synchronization mode.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

SAI: Clock Input

SAI_GetInputClock
Function Name

uint32_t SAI_GetInputClock (SAI_HandleTypeDef * hsai)

Function Description

Get SAI Input Clock based on SAI source clock selection.

Parameters

hsai: pointer to a SAI_HandleTypeDef structure that contains
the configuration information for SAI module.

Return values

SAI: Clock Input

DocID025834 Rev 4

753/964

HAL SDRAM Generic Driver

UM1725

56

HAL SDRAM Generic Driver

56.1

SDRAM Firmware driver registers structures

56.1.1

SDRAM_HandleTypeDef
Data Fields
FMC_SDRAM_TypeDef * Instance
FMC_SDRAM_InitTypeDef Init
__IO HAL_SDRAM_StateTypeDef State
HAL_LockTypeDef Lock
DMA_HandleTypeDef * hdma

Field Documentation
FMC_SDRAM_TypeDef* SDRAM_HandleTypeDef::Instance
Register base address
FMC_SDRAM_InitTypeDef SDRAM_HandleTypeDef::Init
SDRAM device configuration parameters
__IO HAL_SDRAM_StateTypeDef SDRAM_HandleTypeDef::State
SDRAM access state
HAL_LockTypeDef SDRAM_HandleTypeDef::Lock
SDRAM locking object
DMA_HandleTypeDef* SDRAM_HandleTypeDef::hdma
Pointer DMA handler

56.2

SDRAM Firmware driver API description

56.2.1

How to use this driver
This driver is a generic layered driver which contains a set of APIs used to control SDRAM
memories. It uses the FMC layer functions to interface with SDRAM devices. The following
sequence should be followed to configure the FMC to interface with SDRAM memories:
1.

2.

3.

754/964

Declare a SDRAM_HandleTypeDef handle structure, for example:
SDRAM_HandleTypeDef hdsram
Fill the SDRAM_HandleTypeDef handle "Init" field with the allowed values of the
structure member.
Fill the SDRAM_HandleTypeDef handle "Instance" field with a predefined base
register instance for NOR or SDRAM device
Declare a FMC_SDRAM_TimingTypeDef structure; for example:
FMC_SDRAM_TimingTypeDef Timing; and fill its fields with the allowed values of the
structure member.
Initialize the SDRAM Controller by calling the function HAL_SDRAM_Init(). This
function performs the following sequence:
a.
MSP hardware layer configuration using the function HAL_SDRAM_MspInit()
b.
Control register configuration using the FMC SDRAM interface function
FMC_SDRAM_Init()
DocID025834 Rev 4

UM1725

HAL SDRAM Generic Driver
Timing register configuration using the FMC SDRAM interface function
FMC_SDRAM_Timing_Init()
d.
Program the SDRAM external device by applying its initialization sequence
according to the device plugged in your hardware. This step is mandatory for
accessing the SDRAM device.
At this stage you can perform read/write accesses from/to the memory connected to
the SDRAM Bank. You can perform either polling or DMA transfer using the following
APIs:
HAL_SDRAM_Read()/HAL_SDRAM_Write() for polling read/write access
HAL_SDRAM_Read_DMA()/HAL_SDRAM_Write_DMA() for DMA read/write
transfer
You can also control the SDRAM device by calling the control APIs
HAL_SDRAM_WriteOperation_Enable()/ HAL_SDRAM_WriteOperation_Disable() to
respectively enable/disable the SDRAM write operation or the function
HAL_SDRAM_SendCommand() to send a specified command to the SDRAM device.
The command to be sent must be configured with the
FMC_SDRAM_CommandTypeDef structure.
You can continuously monitor the SDRAM device HAL state by calling the function
HAL_SDRAM_GetState()
c.

4.

5.

6.

56.2.2

SDRAM Initialization and de_initialization functions
This section provides functions allowing to initialize/de-initialize the SDRAM memory
This section contains the following APIs:
HAL_SDRAM_Init()
HAL_SDRAM_DeInit()
HAL_SDRAM_MspInit()
HAL_SDRAM_MspDeInit()
HAL_SDRAM_IRQHandler()
HAL_SDRAM_RefreshErrorCallback()
HAL_SDRAM_DMA_XferCpltCallback()
HAL_SDRAM_DMA_XferErrorCallback()

56.2.3

SDRAM Input and Output functions
This section provides functions allowing to use and control the SDRAM memory
This section contains the following APIs:
HAL_SDRAM_Read_8b()
HAL_SDRAM_Write_8b()
HAL_SDRAM_Read_16b()
HAL_SDRAM_Write_16b()
HAL_SDRAM_Read_32b()
HAL_SDRAM_Write_32b()
HAL_SDRAM_Read_DMA()
HAL_SDRAM_Write_DMA()

56.2.4

SDRAM Control functions
This subsection provides a set of functions allowing to control dynamically the SDRAM
interface.
This section contains the following APIs:
HAL_SDRAM_WriteProtection_Enable()
DocID025834 Rev 4

755/964

HAL SDRAM Generic Driver

UM1725

HAL_SDRAM_WriteProtection_Disable()
HAL_SDRAM_SendCommand()
HAL_SDRAM_ProgramRefreshRate()
HAL_SDRAM_SetAutoRefreshNumber()
HAL_SDRAM_GetModeStatus()

56.2.5

SDRAM State functions
This subsection permits to get in run-time the status of the SDRAM controller and the data
flow.
This section contains the following APIs:
HAL_SDRAM_GetState()

56.2.6

Detailed description of functions
HAL_SDRAM_Init
Function Name

HAL_StatusTypeDef HAL_SDRAM_Init
(SDRAM_HandleTypeDef * hsdram,
FMC_SDRAM_TimingTypeDef * Timing)

Function Description

Performs the SDRAM device initialization sequence.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
Timing: Pointer to SDRAM control timing structure

Return values

HAL: status

HAL_SDRAM_DeInit
Function Name

HAL_StatusTypeDef HAL_SDRAM_DeInit
(SDRAM_HandleTypeDef * hsdram)

Function Description

Perform the SDRAM device initialization sequence.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.

Return values

HAL: status

HAL_SDRAM_MspInit
Function Name

void HAL_SDRAM_MspInit (SDRAM_HandleTypeDef *
hsdram)

Function Description

SDRAM MSP Init.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.

Return values

None

HAL_SDRAM_MspDeInit
Function Name

756/964

void HAL_SDRAM_MspDeInit (SDRAM_HandleTypeDef *
hsdram)

DocID025834 Rev 4

UM1725

HAL SDRAM Generic Driver
Function Description

SDRAM MSP DeInit.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.

Return values

None

HAL_SDRAM_IRQHandler
Function Name

void HAL_SDRAM_IRQHandler (SDRAM_HandleTypeDef *
hsdram)

Function Description

This function handles SDRAM refresh error interrupt request.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.

Return values

HAL: status

HAL_SDRAM_RefreshErrorCallback
Function Name

void HAL_SDRAM_RefreshErrorCallback
(SDRAM_HandleTypeDef * hsdram)

Function Description

SDRAM Refresh error callback.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.

Return values

None

HAL_SDRAM_DMA_XferCpltCallback
Function Name

void HAL_SDRAM_DMA_XferCpltCallback
(DMA_HandleTypeDef * hdma)

Function Description

DMA transfer complete callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

HAL_SDRAM_DMA_XferErrorCallback
Function Name

void HAL_SDRAM_DMA_XferErrorCallback
(DMA_HandleTypeDef * hdma)

Function Description

DMA transfer complete error callback.

Parameters

hdma: DMA handle

Return values

None

HAL_SDRAM_Read_8b
Function Name

HAL_StatusTypeDef HAL_SDRAM_Read_8b
(SDRAM_HandleTypeDef * hsdram, uint32_t * pAddress,
uint8_t * pDstBuffer, uint32_t BufferSize)

DocID025834 Rev 4

757/964

HAL SDRAM Generic Driver
Function Description

UM1725
Reads 8-bit data buffer from the SDRAM memory.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
pAddress: Pointer to read start address
pDstBuffer: Pointer to destination buffer
BufferSize: Size of the buffer to read from memory

Return values

HAL: status

HAL_SDRAM_Write_8b
Function Name

HAL_StatusTypeDef HAL_SDRAM_Write_8b
(SDRAM_HandleTypeDef * hsdram, uint32_t * pAddress,
uint8_t * pSrcBuffer, uint32_t BufferSize)

Function Description

Writes 8-bit data buffer to SDRAM memory.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
pAddress: Pointer to write start address
pSrcBuffer: Pointer to source buffer to write
BufferSize: Size of the buffer to write to memory

Return values

HAL: status

HAL_SDRAM_Read_16b
Function Name

HAL_StatusTypeDef HAL_SDRAM_Read_16b
(SDRAM_HandleTypeDef * hsdram, uint32_t * pAddress,
uint16_t * pDstBuffer, uint32_t BufferSize)

Function Description

Reads 16-bit data buffer from the SDRAM memory.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
pAddress: Pointer to read start address
pDstBuffer: Pointer to destination buffer
BufferSize: Size of the buffer to read from memory

Return values

HAL: status

HAL_SDRAM_Write_16b

758/964

Function Name

HAL_StatusTypeDef HAL_SDRAM_Write_16b
(SDRAM_HandleTypeDef * hsdram, uint32_t * pAddress,
uint16_t * pSrcBuffer, uint32_t BufferSize)

Function Description

Writes 16-bit data buffer to SDRAM memory.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
pAddress: Pointer to write start address
pSrcBuffer: Pointer to source buffer to write
BufferSize: Size of the buffer to write to memory

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL SDRAM Generic Driver

HAL_SDRAM_Read_32b
Function Name

HAL_StatusTypeDef HAL_SDRAM_Read_32b
(SDRAM_HandleTypeDef * hsdram, uint32_t * pAddress,
uint32_t * pDstBuffer, uint32_t BufferSize)

Function Description

Reads 32-bit data buffer from the SDRAM memory.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
pAddress: Pointer to read start address
pDstBuffer: Pointer to destination buffer
BufferSize: Size of the buffer to read from memory

Return values

HAL: status

HAL_SDRAM_Write_32b
Function Name

HAL_StatusTypeDef HAL_SDRAM_Write_32b
(SDRAM_HandleTypeDef * hsdram, uint32_t * pAddress,
uint32_t * pSrcBuffer, uint32_t BufferSize)

Function Description

Writes 32-bit data buffer to SDRAM memory.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
pAddress: Pointer to write start address
pSrcBuffer: Pointer to source buffer to write
BufferSize: Size of the buffer to write to memory

Return values

HAL: status

HAL_SDRAM_Read_DMA
Function Name

HAL_StatusTypeDef HAL_SDRAM_Read_DMA
(SDRAM_HandleTypeDef * hsdram, uint32_t * pAddress,
uint32_t * pDstBuffer, uint32_t BufferSize)

Function Description

Reads a Words data from the SDRAM memory using DMA
transfer.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
pAddress: Pointer to read start address
pDstBuffer: Pointer to destination buffer
BufferSize: Size of the buffer to read from memory

Return values

HAL: status

HAL_SDRAM_Write_DMA
Function Name

HAL_StatusTypeDef HAL_SDRAM_Write_DMA
(SDRAM_HandleTypeDef * hsdram, uint32_t * pAddress,
uint32_t * pSrcBuffer, uint32_t BufferSize)

Function Description

Writes a Words data buffer to SDRAM memory using DMA
transfer.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
DocID025834 Rev 4

759/964

HAL SDRAM Generic Driver

UM1725
pAddress: Pointer to write start address
pSrcBuffer: Pointer to source buffer to write
BufferSize: Size of the buffer to write to memory

Return values

HAL: status

HAL_SDRAM_WriteProtection_Enable
Function Name

HAL_StatusTypeDef HAL_SDRAM_WriteProtection_Enable
(SDRAM_HandleTypeDef * hsdram)

Function Description

Enables dynamically SDRAM write protection.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.

Return values

HAL: status

HAL_SDRAM_WriteProtection_Disable
Function Name

HAL_StatusTypeDef HAL_SDRAM_WriteProtection_Disable
(SDRAM_HandleTypeDef * hsdram)

Function Description

Disables dynamically SDRAM write protection.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.

Return values

HAL: status

HAL_SDRAM_SendCommand
Function Name

HAL_StatusTypeDef HAL_SDRAM_SendCommand
(SDRAM_HandleTypeDef * hsdram,
FMC_SDRAM_CommandTypeDef * Command, uint32_t
Timeout)

Function Description

Sends Command to the SDRAM bank.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
Command: SDRAM command structure
Timeout: Timeout duration

Return values

HAL: status

HAL_SDRAM_ProgramRefreshRate

760/964

Function Name

HAL_StatusTypeDef HAL_SDRAM_ProgramRefreshRate
(SDRAM_HandleTypeDef * hsdram, uint32_t RefreshRate)

Function Description

Programs the SDRAM Memory Refresh rate.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
RefreshRate: The SDRAM refresh rate value

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL SDRAM Generic Driver

HAL_SDRAM_SetAutoRefreshNumber
Function Name

HAL_StatusTypeDef HAL_SDRAM_SetAutoRefreshNumber
(SDRAM_HandleTypeDef * hsdram, uint32_t
AutoRefreshNumber)

Function Description

Sets the Number of consecutive SDRAM Memory auto Refresh
commands.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.
AutoRefreshNumber: The SDRAM auto Refresh number

Return values

HAL: status

HAL_SDRAM_GetModeStatus
Function Name

uint32_t HAL_SDRAM_GetModeStatus
(SDRAM_HandleTypeDef * hsdram)

Function Description

Returns the SDRAM memory current mode.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.

Return values

The: SDRAM memory mode.

HAL_SDRAM_GetState
Function Name

HAL_SDRAM_StateTypeDef HAL_SDRAM_GetState
(SDRAM_HandleTypeDef * hsdram)

Function Description

Returns the SDRAM state.

Parameters

hsdram: pointer to a SDRAM_HandleTypeDef structure that
contains the configuration information for SDRAM module.

Return values

HAL: state

56.3

SDRAM Firmware driver defines

56.3.1

SDRAM
SDRAM Exported Macros
__HAL_SDRAM_RESET_HANDLE_STATE

Description:
Reset SDRAM handle state.
Parameters:
__HANDLE__: specifies the SDRAM
handle.
Return value:
None

DocID025834 Rev 4

761/964

HAL SD Generic Driver

UM1725

57

HAL SD Generic Driver

57.1

SD Firmware driver registers structures

57.1.1

SD_HandleTypeDef
Data Fields
SD_TypeDef * Instance
SD_InitTypeDef Init
HAL_LockTypeDef Lock
uint32_t CardType
uint32_t RCA
uint32_t CSD
uint32_t CID
__IO uint32_t SdTransferCplt
__IO uint32_t SdTransferErr
__IO uint32_t DmaTransferCplt
__IO uint32_t SdOperation
DMA_HandleTypeDef * hdmarx
DMA_HandleTypeDef * hdmatx

Field Documentation
SD_TypeDef* SD_HandleTypeDef::Instance
SDIO register base address
SD_InitTypeDef SD_HandleTypeDef::Init
SD required parameters
HAL_LockTypeDef SD_HandleTypeDef::Lock
SD locking object
uint32_t SD_HandleTypeDef::CardType
SD card type
uint32_t SD_HandleTypeDef::RCA
SD relative card address
uint32_t SD_HandleTypeDef::CSD[4]
SD card specific data table
uint32_t SD_HandleTypeDef::CID[4]
SD card identification number table
__IO uint32_t SD_HandleTypeDef::SdTransferCplt
SD transfer complete flag in non blocking mode
__IO uint32_t SD_HandleTypeDef::SdTransferErr
SD transfer error flag in non blocking mode
__IO uint32_t SD_HandleTypeDef::DmaTransferCplt
SD DMA transfer complete flag
__IO uint32_t SD_HandleTypeDef::SdOperation
SD transfer operation (read/write)
DMA_HandleTypeDef* SD_HandleTypeDef::hdmarx
SD Rx DMA handle parameters
DMA_HandleTypeDef* SD_HandleTypeDef::hdmatx
SD Tx DMA handle parameters
762/964

DocID025834 Rev 4

UM1725

57.1.2

HAL SD Generic Driver

HAL_SD_CSDTypedef
Data Fields
__IO uint8_t CSDStruct
__IO uint8_t SysSpecVersion
__IO uint8_t Reserved1
__IO uint8_t TAAC
__IO uint8_t NSAC
__IO uint8_t MaxBusClkFrec
__IO uint16_t CardComdClasses
__IO uint8_t RdBlockLen
__IO uint8_t PartBlockRead
__IO uint8_t WrBlockMisalign
__IO uint8_t RdBlockMisalign
__IO uint8_t DSRImpl
__IO uint8_t Reserved2
__IO uint32_t DeviceSize
__IO uint8_t MaxRdCurrentVDDMin
__IO uint8_t MaxRdCurrentVDDMax
__IO uint8_t MaxWrCurrentVDDMin
__IO uint8_t MaxWrCurrentVDDMax
__IO uint8_t DeviceSizeMul
__IO uint8_t EraseGrSize
__IO uint8_t EraseGrMul
__IO uint8_t WrProtectGrSize
__IO uint8_t WrProtectGrEnable
__IO uint8_t ManDeflECC
__IO uint8_t WrSpeedFact
__IO uint8_t MaxWrBlockLen
__IO uint8_t WriteBlockPaPartial
__IO uint8_t Reserved3
__IO uint8_t ContentProtectAppli
__IO uint8_t FileFormatGrouop
__IO uint8_t CopyFlag
__IO uint8_t PermWrProtect
__IO uint8_t TempWrProtect
__IO uint8_t FileFormat
__IO uint8_t ECC
__IO uint8_t CSD_CRC
__IO uint8_t Reserved4

Field Documentation
__IO uint8_t HAL_SD_CSDTypedef::CSDStruct
CSD structure
__IO uint8_t HAL_SD_CSDTypedef::SysSpecVersion
System specification version
__IO uint8_t HAL_SD_CSDTypedef::Reserved1
Reserved
DocID025834 Rev 4

763/964

HAL SD Generic Driver

UM1725

__IO uint8_t HAL_SD_CSDTypedef::TAAC
Data read access time 1
__IO uint8_t HAL_SD_CSDTypedef::NSAC
Data read access time 2 in CLK cycles
__IO uint8_t HAL_SD_CSDTypedef::MaxBusClkFrec
Max. bus clock frequency
__IO uint16_t HAL_SD_CSDTypedef::CardComdClasses
Card command classes
__IO uint8_t HAL_SD_CSDTypedef::RdBlockLen
Max. read data block length
__IO uint8_t HAL_SD_CSDTypedef::PartBlockRead
Partial blocks for read allowed
__IO uint8_t HAL_SD_CSDTypedef::WrBlockMisalign
Write block misalignment
__IO uint8_t HAL_SD_CSDTypedef::RdBlockMisalign
Read block misalignment
__IO uint8_t HAL_SD_CSDTypedef::DSRImpl
DSR implemented
__IO uint8_t HAL_SD_CSDTypedef::Reserved2
Reserved
__IO uint32_t HAL_SD_CSDTypedef::DeviceSize
Device Size
__IO uint8_t HAL_SD_CSDTypedef::MaxRdCurrentVDDMin
Max. read current @ VDD min
__IO uint8_t HAL_SD_CSDTypedef::MaxRdCurrentVDDMax
Max. read current @ VDD max
__IO uint8_t HAL_SD_CSDTypedef::MaxWrCurrentVDDMin
Max. write current @ VDD min
__IO uint8_t HAL_SD_CSDTypedef::MaxWrCurrentVDDMax
Max. write current @ VDD max
__IO uint8_t HAL_SD_CSDTypedef::DeviceSizeMul
Device size multiplier
__IO uint8_t HAL_SD_CSDTypedef::EraseGrSize
Erase group size
__IO uint8_t HAL_SD_CSDTypedef::EraseGrMul
Erase group size multiplier
__IO uint8_t HAL_SD_CSDTypedef::WrProtectGrSize
Write protect group size
__IO uint8_t HAL_SD_CSDTypedef::WrProtectGrEnable
Write protect group enable
__IO uint8_t HAL_SD_CSDTypedef::ManDeflECC
Manufacturer default ECC
__IO uint8_t HAL_SD_CSDTypedef::WrSpeedFact
Write speed factor
__IO uint8_t HAL_SD_CSDTypedef::MaxWrBlockLen
Max. write data block length
__IO uint8_t HAL_SD_CSDTypedef::WriteBlockPaPartial
Partial blocks for write allowed
__IO uint8_t HAL_SD_CSDTypedef::Reserved3
Reserved
__IO uint8_t HAL_SD_CSDTypedef::ContentProtectAppli
Content protection application
__IO uint8_t HAL_SD_CSDTypedef::FileFormatGrouop
File format group
764/964

DocID025834 Rev 4

UM1725

HAL SD Generic Driver
__IO uint8_t HAL_SD_CSDTypedef::CopyFlag
Copy flag (OTP)
__IO uint8_t HAL_SD_CSDTypedef::PermWrProtect
Permanent write protection
__IO uint8_t HAL_SD_CSDTypedef::TempWrProtect
Temporary write protection
__IO uint8_t HAL_SD_CSDTypedef::FileFormat
File format
__IO uint8_t HAL_SD_CSDTypedef::ECC
ECC code
__IO uint8_t HAL_SD_CSDTypedef::CSD_CRC
CSD CRC
__IO uint8_t HAL_SD_CSDTypedef::Reserved4
Always 1

57.1.3

HAL_SD_CIDTypedef
Data Fields
__IO uint8_t ManufacturerID
__IO uint16_t OEM_AppliID
__IO uint32_t ProdName1
__IO uint8_t ProdName2
__IO uint8_t ProdRev
__IO uint32_t ProdSN
__IO uint8_t Reserved1
__IO uint16_t ManufactDate
__IO uint8_t CID_CRC
__IO uint8_t Reserved2

Field Documentation
__IO uint8_t HAL_SD_CIDTypedef::ManufacturerID
Manufacturer ID
__IO uint16_t HAL_SD_CIDTypedef::OEM_AppliID
OEM/Application ID
__IO uint32_t HAL_SD_CIDTypedef::ProdName1
Product Name part1
__IO uint8_t HAL_SD_CIDTypedef::ProdName2
Product Name part2
__IO uint8_t HAL_SD_CIDTypedef::ProdRev
Product Revision
__IO uint32_t HAL_SD_CIDTypedef::ProdSN
Product Serial Number
__IO uint8_t HAL_SD_CIDTypedef::Reserved1
Reserved1
__IO uint16_t HAL_SD_CIDTypedef::ManufactDate
Manufacturing Date
__IO uint8_t HAL_SD_CIDTypedef::CID_CRC
CID CRC

DocID025834 Rev 4

765/964

HAL SD Generic Driver

UM1725

__IO uint8_t HAL_SD_CIDTypedef::Reserved2
Always 1

57.1.4

HAL_SD_CardStatusTypedef
Data Fields
__IO uint8_t DAT_BUS_WIDTH
__IO uint8_t SECURED_MODE
__IO uint16_t SD_CARD_TYPE
__IO uint32_t SIZE_OF_PROTECTED_AREA
__IO uint8_t SPEED_CLASS
__IO uint8_t PERFORMANCE_MOVE
__IO uint8_t AU_SIZE
__IO uint16_t ERASE_SIZE
__IO uint8_t ERASE_TIMEOUT
__IO uint8_t ERASE_OFFSET

Field Documentation
__IO uint8_t HAL_SD_CardStatusTypedef::DAT_BUS_WIDTH
Shows the currently defined data bus width
__IO uint8_t HAL_SD_CardStatusTypedef::SECURED_MODE
Card is in secured mode of operation
__IO uint16_t HAL_SD_CardStatusTypedef::SD_CARD_TYPE
Carries information about card type
__IO uint32_t HAL_SD_CardStatusTypedef::SIZE_OF_PROTECTED_AREA
Carries information about the capacity of protected area
__IO uint8_t HAL_SD_CardStatusTypedef::SPEED_CLASS
Carries information about the speed class of the card
__IO uint8_t HAL_SD_CardStatusTypedef::PERFORMANCE_MOVE
Carries information about the card's performance move
__IO uint8_t HAL_SD_CardStatusTypedef::AU_SIZE
Carries information about the card's allocation unit size
__IO uint16_t HAL_SD_CardStatusTypedef::ERASE_SIZE
Determines the number of AUs to be erased in one operation
__IO uint8_t HAL_SD_CardStatusTypedef::ERASE_TIMEOUT
Determines the timeout for any number of AU erase
__IO uint8_t HAL_SD_CardStatusTypedef::ERASE_OFFSET
Carries information about the erase offset

57.1.5

HAL_SD_CardInfoTypedef
Data Fields
HAL_SD_CSDTypedef SD_csd
HAL_SD_CIDTypedef SD_cid
uint64_t CardCapacity
uint32_t CardBlockSize

766/964

DocID025834 Rev 4

UM1725

HAL SD Generic Driver
uint16_t RCA
uint8_t CardType

Field Documentation
HAL_SD_CSDTypedef HAL_SD_CardInfoTypedef::SD_csd
SD card specific data register
HAL_SD_CIDTypedef HAL_SD_CardInfoTypedef::SD_cid
SD card identification number register
uint64_t HAL_SD_CardInfoTypedef::CardCapacity
Card capacity
uint32_t HAL_SD_CardInfoTypedef::CardBlockSize
Card block size
uint16_t HAL_SD_CardInfoTypedef::RCA
SD relative card address
uint8_t HAL_SD_CardInfoTypedef::CardType
SD card type

57.2

SD Firmware driver API description

57.2.1

How to use this driver
This driver implements a high level communication layer for read and write from/to this
memory. The needed STM32 hardware resources (SDIO and GPIO) are performed by the
user in HAL_SD_MspInit() function (MSP layer). Basically, the MSP layer configuration
should be the same as we provide in the examples. You can easily tailor this configuration
according to hardware resources.
This driver is a generic layered driver for SDIO memories which uses the HAL SDIO driver
functions to interface with SD and uSD cards devices. It is used as follows:
1.

Initialize the SDIO low level resources by implement the HAL_SD_MspInit() API:
a.
Enable the SDIO interface clock using __HAL_RCC_SDIO_CLK_ENABLE();
b.
SDIO pins configuration for SD card
Enable the clock for the SDIO GPIOs using the functions
__HAL_RCC_GPIOx_CLK_ENABLE();
Configure these SDIO pins as alternate function pull-up using
HAL_GPIO_Init() and according to your pin assignment;
c.
DMA Configuration if you need to use DMA process
(HAL_SD_ReadBlocks_DMA() and HAL_SD_WriteBlocks_DMA() APIs).
Enable the DMAx interface clock using
__HAL_RCC_DMAx_CLK_ENABLE();
Configure the DMA using the function HAL_DMA_Init() with predeclared
and filled.
d.
NVIC configuration if you need to use interrupt process when using DMA
transfer.
Configure the SDIO and DMA interrupt priorities using functions
HAL_NVIC_SetPriority(); DMA priority is superior to SDIO's priority
Enable the NVIC DMA and SDIO IRQs using function
HAL_NVIC_EnableIRQ()
SDIO interrupts are managed using the macros
__HAL_SD_SDIO_ENABLE_IT() and __HAL_SD_SDIO_DISABLE_IT()
inside the communication process.
DocID025834 Rev 4

767/964

HAL SD Generic Driver

2.

UM1725

SDIO interrupts pending bits are managed using the macros
__HAL_SD_SDIO_GET_IT() and __HAL_SD_SDIO_CLEAR_IT()
At this stage, you can perform SD read/write/erase operations after SD card
initialization

SD Card Initialization and configuration
To initialize the SD Card, use the HAL_SD_Init() function. It Initializes the SD Card and put
it into Standby State (Ready for data transfer). This function provide the following
operations:
1.

2.

3.

4.
5.

Apply the SD Card initialization process at 400KHz and check the SD Card type
(Standard Capacity or High Capacity). You can change or adapt this frequency by
adjusting the "ClockDiv" field. The SD Card frequency (SDIO_CK) is computed as
follows: SDIO_CK = SDIOCLK / (ClockDiv + 2) In initialization mode and according to
the SD Card standard, make sure that the SDIO_CK frequency doesn't exceed
400KHz.
Get the SD CID and CSD data. All these information are managed by the SDCardInfo
structure. This structure provide also ready computed SD Card capacity and Block
size. These information are stored in SD handle structure in case of future use.
Configure the SD Card Data transfer frequency. By Default, the card transfer
frequency is set to 24MHz. You can change or adapt this frequency by adjusting the
"ClockDiv" field. In transfer mode and according to the SD Card standard, make sure
that the SDIO_CK frequency doesn't exceed 25MHz and 50MHz in High-speed mode
switch. To be able to use a frequency higher than 24MHz, you should use the SDIO
peripheral in bypass mode. Refer to the corresponding reference manual for more
details.
Select the corresponding SD Card according to the address read with the step 2.
Configure the SD Card in wide bus mode: 4-bits data.

SD Card Read operation
You can read from SD card in polling mode by using function HAL_SD_ReadBlocks().
This function support only 512-bytes block length (the block size should be chosen as
512 bytes). You can choose either one block read operation or multiple block read
operation by adjusting the "NumberOfBlocks" parameter.
You can read from SD card in DMA mode by using function
HAL_SD_ReadBlocks_DMA(). This function support only 512-bytes block length (the
block size should be chosen as 512 bytes). You can choose either one block read
operation or multiple block read operation by adjusting the "NumberOfBlocks"
parameter. After this, you have to call the function HAL_SD_CheckReadOperation(),
to insure that the read transfer is done correctly in both DMA and SD sides.

SD Card Write operation
You can write to SD card in polling mode by using function HAL_SD_WriteBlocks().
This function support only 512-bytes block length (the block size should be chosen as
512 bytes). You can choose either one block read operation or multiple block read
operation by adjusting the "NumberOfBlocks" parameter.
You can write to SD card in DMA mode by using function
HAL_SD_WriteBlocks_DMA(). This function support only 512-bytes block length (the
block size should be chosen as 512 byte). You can choose either one block read
operation or multiple block read operation by adjusting the "NumberOfBlocks"

768/964

DocID025834 Rev 4

UM1725

HAL SD Generic Driver
parameter. After this, you have to call the function HAL_SD_CheckWriteOperation(),
to insure that the write transfer is done correctly in both DMA and SD sides.

SD card status
At any time, you can check the SD Card status and get the SD card state by using the
HAL_SD_GetStatus() function. This function checks first if the SD card is still
connected and then get the internal SD Card transfer state.
You can also get the SD card SD Status register by using the
HAL_SD_SendSDStatus() function.

SD HAL driver macros list
You can refer to the SD HAL driver header file for more useful macros

57.2.2

Initialization and de-initialization functions
This section provides functions allowing to initialize/de-initialize the SD card device to be
ready for use.
This section contains the following APIs:
HAL_SD_Init()
HAL_SD_DeInit()
HAL_SD_MspInit()
HAL_SD_MspDeInit()

57.2.3

IO operation functions
This subsection provides a set of functions allowing to manage the data transfer from/to
SD card.
This section contains the following APIs:
HAL_SD_ReadBlocks()
HAL_SD_WriteBlocks()
HAL_SD_ReadBlocks_DMA()
HAL_SD_WriteBlocks_DMA()
HAL_SD_CheckReadOperation()
HAL_SD_CheckWriteOperation()
HAL_SD_Erase()
HAL_SD_IRQHandler()
HAL_SD_XferCpltCallback()
HAL_SD_XferErrorCallback()
HAL_SD_DMA_RxCpltCallback()
HAL_SD_DMA_RxErrorCallback()
HAL_SD_DMA_TxCpltCallback()
HAL_SD_DMA_TxErrorCallback()

DocID025834 Rev 4

769/964

HAL SD Generic Driver

57.2.4

UM1725

Peripheral Control functions
This subsection provides a set of functions allowing to control the SD card operations.
This section contains the following APIs:
HAL_SD_Get_CardInfo()
HAL_SD_WideBusOperation_Config()
HAL_SD_StopTransfer()
HAL_SD_HighSpeed()

57.2.5

Peripheral State functions
This subsection permits to get in runtime the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_SD_SendSDStatus()
HAL_SD_GetStatus()
HAL_SD_GetCardStatus()

57.2.6

Detailed description of functions
HAL_SD_Init
Function Name

HAL_SD_ErrorTypedef HAL_SD_Init (SD_HandleTypeDef *
hsd, HAL_SD_CardInfoTypedef * SDCardInfo)

Function Description

Initializes the SD card according to the specified parameters in the
SD_HandleTypeDef and create the associated handle.

Parameters

hsd: SD handle
SDCardInfo: HAL_SD_CardInfoTypedef structure for SD
card information

Return values

HAL: SD error state

HAL_SD_DeInit
Function Name

HAL_StatusTypeDef HAL_SD_DeInit (SD_HandleTypeDef *
hsd)

Function Description

De-Initializes the SD card.

Parameters

hsd: SD handle

Return values

HAL: status

HAL_SD_MspInit

770/964

Function Name

void HAL_SD_MspInit (SD_HandleTypeDef * hsd)

Function Description

Initializes the SD MSP.

Parameters

hsd: SD handle

Return values

None

DocID025834 Rev 4

UM1725

HAL SD Generic Driver

HAL_SD_MspDeInit
Function Name

void HAL_SD_MspDeInit (SD_HandleTypeDef * hsd)

Function Description

De-Initialize SD MSP.

Parameters

hsd: SD handle

Return values

None

HAL_SD_ReadBlocks
Function Name

HAL_SD_ErrorTypedef HAL_SD_ReadBlocks
(SD_HandleTypeDef * hsd, uint32_t * pReadBuffer, uint64_t
ReadAddr, uint32_t BlockSize, uint32_t NumberOfBlocks)

Function Description

Reads block(s) from a specified address in a card.

Parameters

hsd: SD handle
pReadBuffer: pointer to the buffer that will contain the
received data
ReadAddr: Address from where data is to be read
BlockSize: SD card Data block size
NumberOfBlocks: Number of SD blocks to read

Return values

SD: Card error state

Notes

BlockSize must be 512 bytes.

HAL_SD_WriteBlocks
Function Name

HAL_SD_ErrorTypedef HAL_SD_WriteBlocks
(SD_HandleTypeDef * hsd, uint32_t * pWriteBuffer, uint64_t
WriteAddr, uint32_t BlockSize, uint32_t NumberOfBlocks)

Function Description

Allows to write block(s) to a specified address in a card.

Parameters

hsd: SD handle
pWriteBuffer: pointer to the buffer that will contain the data
to transmit
WriteAddr: Address from where data is to be written
BlockSize: SD card Data block size
NumberOfBlocks: Number of SD blocks to write

Return values

SD: Card error state

Notes

BlockSize must be 512 bytes.

HAL_SD_Erase
Function Name

HAL_SD_ErrorTypedef HAL_SD_Erase (SD_HandleTypeDef *
hsd, uint64_t startaddr, uint64_t endaddr)

Function Description

Erases the specified memory area of the given SD card.

Parameters

hsd: SD handle
startaddr: Start byte address
endaddr: End byte address

Return values

SD: Card error state

DocID025834 Rev 4

771/964

HAL SD Generic Driver

UM1725

HAL_SD_IRQHandler
Function Name

void HAL_SD_IRQHandler (SD_HandleTypeDef * hsd)

Function Description

This function handles SD card interrupt request.

Parameters

hsd: SD handle

Return values

None

HAL_SD_DMA_RxCpltCallback
Function Name

void HAL_SD_DMA_RxCpltCallback (DMA_HandleTypeDef *
hdma)

Function Description

SD Transfer complete Rx callback in non blocking mode.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

HAL_SD_DMA_RxErrorCallback
Function Name

void HAL_SD_DMA_RxErrorCallback (DMA_HandleTypeDef *
hdma)

Function Description

SD DMA transfer complete Rx error callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

HAL_SD_DMA_TxCpltCallback
Function Name

void HAL_SD_DMA_TxCpltCallback (DMA_HandleTypeDef *
hdma)

Function Description

SD Transfer complete Tx callback in non blocking mode.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

HAL_SD_DMA_TxErrorCallback

772/964

Function Name

void HAL_SD_DMA_TxErrorCallback (DMA_HandleTypeDef *
hdma)

Function Description

SD DMA transfer complete error Tx callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

DocID025834 Rev 4

UM1725

HAL SD Generic Driver

HAL_SD_XferCpltCallback
Function Name

void HAL_SD_XferCpltCallback (SD_HandleTypeDef * hsd)

Function Description

SD end of transfer callback.

Parameters

hsd: SD handle

Return values

None

HAL_SD_XferErrorCallback
Function Name

void HAL_SD_XferErrorCallback (SD_HandleTypeDef * hsd)

Function Description

SD Transfer Error callback.

Parameters

hsd: SD handle

Return values

None

HAL_SD_ReadBlocks_DMA
Function Name

HAL_SD_ErrorTypedef HAL_SD_ReadBlocks_DMA
(SD_HandleTypeDef * hsd, uint32_t * pReadBuffer, uint64_t
ReadAddr, uint32_t BlockSize, uint32_t NumberOfBlocks)

Function Description

Reads block(s) from a specified address in a card.

Parameters

hsd: SD handle
pReadBuffer: Pointer to the buffer that will contain the
received data
ReadAddr: Address from where data is to be read
BlockSize: SD card Data block size
NumberOfBlocks: Number of blocks to read.

Return values

SD: Card error state

Notes

This API should be followed by the function
HAL_SD_CheckReadOperation() to check the completion of
the read process
BlockSize must be 512 bytes.

HAL_SD_WriteBlocks_DMA
Function Name

HAL_SD_ErrorTypedef HAL_SD_WriteBlocks_DMA
(SD_HandleTypeDef * hsd, uint32_t * pWriteBuffer, uint64_t
WriteAddr, uint32_t BlockSize, uint32_t NumberOfBlocks)

Function Description

Writes block(s) to a specified address in a card.

Parameters

hsd: SD handle
pWriteBuffer: pointer to the buffer that will contain the data
to transmit
WriteAddr: Address from where data is to be read
BlockSize: the SD card Data block size
NumberOfBlocks: Number of blocks to write

Return values

SD: Card error state

Notes

This API should be followed by the function
HAL_SD_CheckWriteOperation() to check the completion of
DocID025834 Rev 4

773/964

HAL SD Generic Driver

UM1725
the write process (by SD current status polling).
BlockSize must be 512 bytes.

HAL_SD_CheckWriteOperation
Function Name

HAL_SD_ErrorTypedef HAL_SD_CheckWriteOperation
(SD_HandleTypeDef * hsd, uint32_t Timeout)

Function Description

This function waits until the SD DMA data write transfer is finished.

Parameters

hsd: SD handle
Timeout: Timeout duration

Return values

SD: Card error state

HAL_SD_CheckReadOperation
Function Name

HAL_SD_ErrorTypedef HAL_SD_CheckReadOperation
(SD_HandleTypeDef * hsd, uint32_t Timeout)

Function Description

This function waits until the SD DMA data read transfer is finished.

Parameters

hsd: SD handle
Timeout: Timeout duration

Return values

SD: Card error state

HAL_SD_Get_CardInfo
Function Name

HAL_SD_ErrorTypedef HAL_SD_Get_CardInfo
(SD_HandleTypeDef * hsd, HAL_SD_CardInfoTypedef *
pCardInfo)

Function Description

Returns information about specific card.

Parameters

hsd: SD handle
pCardInfo: Pointer to a HAL_SD_CardInfoTypedef structure
that contains all SD cardinformation

Return values

SD: Card error state

HAL_SD_WideBusOperation_Config

774/964

Function Name

HAL_SD_ErrorTypedef HAL_SD_WideBusOperation_Config
(SD_HandleTypeDef * hsd, uint32_t WideMode)

Function Description

Enables wide bus operation for the requested card if supported by
card.

Parameters

hsd: SD handle
WideMode: Specifies the SD card wide bus mode This
parameter can be one of the following values:
SDIO_BUS_WIDE_8B: 8-bit data transfer (Only for
MMC)
SDIO_BUS_WIDE_4B: 4-bit data transfer
SDIO_BUS_WIDE_1B: 1-bit data transfer

Return values

SD: Card error state

DocID025834 Rev 4

UM1725

HAL SD Generic Driver

HAL_SD_StopTransfer
Function Name

HAL_SD_ErrorTypedef HAL_SD_StopTransfer
(SD_HandleTypeDef * hsd)

Function Description

Aborts an ongoing data transfer.

Parameters

hsd: SD handle

Return values

SD: Card error state

HAL_SD_HighSpeed
Function Name

HAL_SD_ErrorTypedef HAL_SD_HighSpeed
(SD_HandleTypeDef * hsd)

Function Description

Switches the SD card to High Speed mode.

Parameters

hsd: SD handle

Return values

SD: Card error state

Notes

This operation should be followed by the configuration of PLL
to have SDIOCK clock between 67 and 75 MHz

HAL_SD_SendSDStatus
Function Name

HAL_SD_ErrorTypedef HAL_SD_SendSDStatus
(SD_HandleTypeDef * hsd, uint32_t * pSDstatus)

Function Description

Returns the current SD card's status.

Parameters

hsd: SD handle
pSDstatus: Pointer to the buffer that will contain the SD card
status SD Status register)

Return values

SD: Card error state

HAL_SD_GetCardStatus
Function Name

HAL_SD_ErrorTypedef HAL_SD_GetCardStatus
(SD_HandleTypeDef * hsd, HAL_SD_CardStatusTypedef *
pCardStatus)

Function Description

Gets the SD card status.

Parameters

hsd: SD handle
pCardStatus: Pointer to the HAL_SD_CardStatusTypedef
structure that will contain the SD card status information

Return values

SD: Card error state

HAL_SD_GetStatus
Function Name

HAL_SD_TransferStateTypedef HAL_SD_GetStatus
(SD_HandleTypeDef * hsd)

Function Description

Gets the current sd card data status.

Parameters

hsd: SD handle

DocID025834 Rev 4

775/964

HAL SD Generic Driver
Return values

UM1725
Data: Transfer state

57.3

SD Firmware driver defines

57.3.1

SD
SD Exported Constants

776/964

SD_CMD_GO_IDLE_STATE

Resets the SD memory
card.

SD_CMD_SEND_OP_COND

Sends host capacity support
information and activates
the card's initialization
process.

SD_CMD_ALL_SEND_CID

Asks any card connected to
the host to send the CID
numbers on the CMD line.

SD_CMD_SET_REL_ADDR

Asks the card to publish a
new relative address (RCA).

SD_CMD_SET_DSR

Programs the DSR of all
cards.

SD_CMD_SDIO_SEN_OP_COND

Sends host capacity support
information (HCS) and asks
the accessed card to send
its operating condition
register (OCR) content in
the response on the CMD
line.

SD_CMD_HS_SWITCH

Checks switchable function
(mode 0) and switch card
function (mode 1).

SD_CMD_SEL_DESEL_CARD

Selects the card by its own
relative address and gets
deselected by any other
address

SD_CMD_HS_SEND_EXT_CSD

Sends SD Memory Card
interface condition, which
includes host supply voltage
information and asks the
card whether card supports
voltage.

SD_CMD_SEND_CSD

Addressed card sends its
card specific data (CSD) on
the CMD line.

SD_CMD_SEND_CID

Addressed card sends its
card identification (CID) on
the CMD line.

SD_CMD_READ_DAT_UNTIL_STOP

SD card doesn't support it.

SD_CMD_STOP_TRANSMISSION

Forces the card to stop

DocID025834 Rev 4

UM1725

HAL SD Generic Driver
transmission.
SD_CMD_SEND_STATUS

Addressed card sends its
status register.

SD_CMD_HS_BUSTEST_READ
SD_CMD_GO_INACTIVE_STATE

Sends an addressed card
into the inactive state.

SD_CMD_SET_BLOCKLEN

Sets the block length (in
bytes for SDSC) for all
following block commands
(read, write, lock). Default
block length is fixed to 512
Bytes. Not effective for
SDHS and SDXC.

SD_CMD_READ_SINGLE_BLOCK

Reads single block of size
selected by
SET_BLOCKLEN in case of
SDSC, and a block of fixed
512 bytes in case of SDHC
and SDXC.

SD_CMD_READ_MULT_BLOCK

Continuously transfers data
blocks from card to host
until interrupted by
STOP_TRANSMISSION
command.

SD_CMD_HS_BUSTEST_WRITE

64 bytes tuning pattern is
sent for SDR50 and
SDR104.

SD_CMD_WRITE_DAT_UNTIL_STOP

Speed class control
command.

SD_CMD_SET_BLOCK_COUNT

Specify block count for
CMD18 and CMD25.

SD_CMD_WRITE_SINGLE_BLOCK

Writes single block of size
selected by
SET_BLOCKLEN in case of
SDSC, and a block of fixed
512 bytes in case of SDHC
and SDXC.

SD_CMD_WRITE_MULT_BLOCK

Continuously writes blocks
of data until a
STOP_TRANSMISSION
follows.

SD_CMD_PROG_CID

Reserved for manufacturers.

SD_CMD_PROG_CSD

Programming of the
programmable bits of the
CSD.

SD_CMD_SET_WRITE_PROT

Sets the write protection bit
of the addressed group.

DocID025834 Rev 4

777/964

HAL SD Generic Driver
SD_CMD_CLR_WRITE_PROT

UM1725
Clears the write protection
bit of the addressed group.

SD_CMD_SEND_WRITE_PROT

Asks the card to send the
status of the write protection
bits.

SD_CMD_SD_ERASE_GRP_START

Sets the address of the first
write block to be erased.
(For SD card only).

SD_CMD_SD_ERASE_GRP_END

Sets the address of the last
write block of the continuous
range to be erased.

SD_CMD_ERASE_GRP_START

Sets the address of the first
write block to be erased.
Reserved for each
command system set by
switch function command
(CMD6).

SD_CMD_ERASE_GRP_END

Sets the address of the last
write block of the continuous
range to be erased.
Reserved for each
command system set by
switch function command
(CMD6).

SD_CMD_ERASE

Reserved for SD security
applications.

SD_CMD_FAST_IO

SD card doesn't support it
(Reserved).

SD_CMD_GO_IRQ_STATE

SD card doesn't support it
(Reserved).

SD_CMD_LOCK_UNLOCK

Sets/resets the password or
lock/unlock the card. The
size of the data block is set
by the SET_BLOCK_LEN
command.

SD_CMD_APP_CMD

Indicates to the card that the
next command is an
application specific
command rather than a
standard command.

SD_CMD_GEN_CMD

Used either to transfer a
data block to the card or to
get a data block from the
card for general
purpose/application specific
commands.

SD_CMD_NO_CMD
SD_CMD_APP_SD_SET_BUSWIDTH

778/964

DocID025834 Rev 4

SDIO_APP_CMD should be
sent before sending these

UM1725

HAL SD Generic Driver
commands. (ACMD6)
Defines the data bus width
to be used for data transfer.
The allowed data bus widths
are given in SCR register.
SD_CMD_SD_APP_STATUS

(ACMD13) Sends the SD
status.

SD_CMD_SD_APP_SEND_NUM_WRITE_BLOCKS

(ACMD22) Sends the
number of the written
(without errors) write blocks.
Responds with 32bit+CRC
data block.

SD_CMD_SD_APP_OP_COND

(ACMD41) Sends host
capacity support information
(HCS) and asks the
accessed card to send its
operating condition register
(OCR) content in the
response on the CMD line.

SD_CMD_SD_APP_SET_CLR_CARD_DETECT

(ACMD42)
Connects/Disconnects the
50 KOhm pull-up resistor on
CD/DAT3 (pin 1) of the card.

SD_CMD_SD_APP_SEND_SCR

Reads the SD Configuration
Register (SCR).

SD_CMD_SDIO_RW_DIRECT

For SD I/O card only,
reserved for security
specification.

SD_CMD_SDIO_RW_EXTENDED

For SD I/O card only,
reserved for security
specification.

SD_CMD_SD_APP_GET_MKB

SD_CMD_APP_CMD
should be sent before
sending these commands.
For SD card only

SD_CMD_SD_APP_GET_MID

For SD card only

SD_CMD_SD_APP_SET_CER_RN1

For SD card only

SD_CMD_SD_APP_GET_CER_RN2

For SD card only

SD_CMD_SD_APP_SET_CER_RES2

For SD card only

SD_CMD_SD_APP_GET_CER_RES1

For SD card only

SD_CMD_SD_APP_SECURE_READ_MULTIPLE_BLOCK

For SD card only

SD_CMD_SD_APP_SECURE_WRITE_MULTIPLE_BLOCK

For SD card only

SD_CMD_SD_APP_SECURE_ERASE

For SD card only

SD_CMD_SD_APP_CHANGE_SECURE_AREA

For SD card only

SD_CMD_SD_APP_SECURE_WRITE_MKB

For SD card only

DocID025834 Rev 4

779/964

HAL SD Generic Driver
STD_CAPACITY_SD_CARD_V1_1

UM1725

STD_CAPACITY_SD_CARD_V2_0
HIGH_CAPACITY_SD_CARD
MULTIMEDIA_CARD
SECURE_DIGITAL_IO_CARD
HIGH_SPEED_MULTIMEDIA_CARD
SECURE_DIGITAL_IO_COMBO_CARD
HIGH_CAPACITY_MMC_CARD
SD Exported Macros
Description:

__HAL_SD_SDIO_ENABLE

Enable the SD device.
Return value:
None
Description:

__HAL_SD_SDIO_DISABLE

Disable the SD device.
Return value:
None
__HAL_SD_SDIO_DMA_ENABLE

Description:
Enable the SDIO DMA transfer.
Return value:
None

__HAL_SD_SDIO_DMA_DISABLE

Description:
Disable the SDIO DMA transfer.
Return value:
None

__HAL_SD_SDIO_ENABLE_IT

Description:
Enable the SD device interrupt.
Parameters:
__HANDLE__: SD Handle
__INTERRUPT__: specifies the SDIO interrupt
sources to be enabled. This parameter can be
one or a combination of the following values:
SDIO_IT_CCRCFAIL: Command response
received (CRC check failed) interrupt
SDIO_IT_DCRCFAIL: Data block
sent/received (CRC check failed) interrupt
SDIO_IT_CTIMEOUT: Command response
timeout interrupt
SDIO_IT_DTIMEOUT: Data timeout
interrupt

780/964

DocID025834 Rev 4

UM1725

HAL SD Generic Driver
SDIO_IT_TXUNDERR: Transmit FIFO
underrun error interrupt
SDIO_IT_RXOVERR: Received FIFO
overrun error interrupt
SDIO_IT_CMDREND: Command response
received (CRC check passed) interrupt
SDIO_IT_CMDSENT: Command sent (no
response required) interrupt
SDIO_IT_DATAEND: Data end (data
counter, SDIDCOUNT, is zero) interrupt
SDIO_IT_STBITERR: Start bit not detected
on all data signals in wide bus mode
interrupt
SDIO_IT_DBCKEND: Data block
sent/received (CRC check passed) interrupt
SDIO_IT_CMDACT: Command transfer in
progress interrupt
SDIO_IT_TXACT: Data transmit in progress
interrupt
SDIO_IT_RXACT: Data receive in progress
interrupt
SDIO_IT_TXFIFOHE: Transmit FIFO Half
Empty interrupt
SDIO_IT_RXFIFOHF: Receive FIFO Half
Full interrupt
SDIO_IT_TXFIFOF: Transmit FIFO full
interrupt
SDIO_IT_RXFIFOF: Receive FIFO full
interrupt
SDIO_IT_TXFIFOE: Transmit FIFO empty
interrupt
SDIO_IT_RXFIFOE: Receive FIFO empty
interrupt
SDIO_IT_TXDAVL: Data available in
transmit FIFO interrupt
SDIO_IT_RXDAVL: Data available in
receive FIFO interrupt
SDIO_IT_SDIOIT: SD I/O interrupt received
interrupt
SDIO_IT_CEATAEND: CE-ATA command
completion signal received for CMD61
interrupt
Return value:
None
__HAL_SD_SDIO_DISABLE_IT

Description:
Disable the SD device interrupt.
Parameters:
__HANDLE__: SD Handle
__INTERRUPT__: specifies the SDIO interrupt
sources to be disabled. This parameter can be
one or a combination of the following values:

DocID025834 Rev 4

781/964

HAL SD Generic Driver

UM1725
SDIO_IT_CCRCFAIL: Command response
received (CRC check failed) interrupt
SDIO_IT_DCRCFAIL: Data block
sent/received (CRC check failed) interrupt
SDIO_IT_CTIMEOUT: Command response
timeout interrupt
SDIO_IT_DTIMEOUT: Data timeout
interrupt
SDIO_IT_TXUNDERR: Transmit FIFO
underrun error interrupt
SDIO_IT_RXOVERR: Received FIFO
overrun error interrupt
SDIO_IT_CMDREND: Command response
received (CRC check passed) interrupt
SDIO_IT_CMDSENT: Command sent (no
response required) interrupt
SDIO_IT_DATAEND: Data end (data
counter, SDIDCOUNT, is zero) interrupt
SDIO_IT_STBITERR: Start bit not detected
on all data signals in wide bus mode
interrupt
SDIO_IT_DBCKEND: Data block
sent/received (CRC check passed) interrupt
SDIO_IT_CMDACT: Command transfer in
progress interrupt
SDIO_IT_TXACT: Data transmit in progress
interrupt
SDIO_IT_RXACT: Data receive in progress
interrupt
SDIO_IT_TXFIFOHE: Transmit FIFO Half
Empty interrupt
SDIO_IT_RXFIFOHF: Receive FIFO Half
Full interrupt
SDIO_IT_TXFIFOF: Transmit FIFO full
interrupt
SDIO_IT_RXFIFOF: Receive FIFO full
interrupt
SDIO_IT_TXFIFOE: Transmit FIFO empty
interrupt
SDIO_IT_RXFIFOE: Receive FIFO empty
interrupt
SDIO_IT_TXDAVL: Data available in
transmit FIFO interrupt
SDIO_IT_RXDAVL: Data available in
receive FIFO interrupt
SDIO_IT_SDIOIT: SD I/O interrupt received
interrupt
SDIO_IT_CEATAEND: CE-ATA command
completion signal received for CMD61
interrupt
Return value:
None

782/964

DocID025834 Rev 4

UM1725

HAL SD Generic Driver
__HAL_SD_SDIO_GET_FLAG

Description:
Check whether the specified SD flag is set or
not.
Parameters:
__HANDLE__: SD Handle
__FLAG__: specifies the flag to check. This
parameter can be one of the following values:
SDIO_FLAG_CCRCFAIL: Command
response received (CRC check failed)
SDIO_FLAG_DCRCFAIL: Data block
sent/received (CRC check failed)
SDIO_FLAG_CTIMEOUT: Command
response timeout
SDIO_FLAG_DTIMEOUT: Data timeout
SDIO_FLAG_TXUNDERR: Transmit FIFO
underrun error
SDIO_FLAG_RXOVERR: Received FIFO
overrun error
SDIO_FLAG_CMDREND: Command
response received (CRC check passed)
SDIO_FLAG_CMDSENT: Command sent
(no response required)
SDIO_FLAG_DATAEND: Data end (data
counter, SDIDCOUNT, is zero)
SDIO_FLAG_STBITERR: Start bit not
detected on all data signals in wide bus
mode.
SDIO_FLAG_DBCKEND: Data block
sent/received (CRC check passed)
SDIO_FLAG_CMDACT: Command transfer
in progress
SDIO_FLAG_TXACT: Data transmit in
progress
SDIO_FLAG_RXACT: Data receive in
progress
SDIO_FLAG_TXFIFOHE: Transmit FIFO
Half Empty
SDIO_FLAG_RXFIFOHF: Receive FIFO
Half Full
SDIO_FLAG_TXFIFOF: Transmit FIFO full
SDIO_FLAG_RXFIFOF: Receive FIFO full
SDIO_FLAG_TXFIFOE: Transmit FIFO
empty
SDIO_FLAG_RXFIFOE: Receive FIFO
empty
SDIO_FLAG_TXDAVL: Data available in
transmit FIFO
SDIO_FLAG_RXDAVL: Data available in
receive FIFO
SDIO_FLAG_SDIOIT: SD I/O interrupt
received
SDIO_FLAG_CEATAEND: CE-ATA

DocID025834 Rev 4

783/964

HAL SD Generic Driver

UM1725
command completion signal received for
CMD61
Return value:
The: new state of SD FLAG (SET or RESET).

__HAL_SD_SDIO_CLEAR_FLAG

Description:
Clear the SD's pending flags.
Parameters:
__HANDLE__: SD Handle
__FLAG__: specifies the flag to clear. This
parameter can be one or a combination of the
following values:
SDIO_FLAG_CCRCFAIL: Command
response received (CRC check failed)
SDIO_FLAG_DCRCFAIL: Data block
sent/received (CRC check failed)
SDIO_FLAG_CTIMEOUT: Command
response timeout
SDIO_FLAG_DTIMEOUT: Data timeout
SDIO_FLAG_TXUNDERR: Transmit FIFO
underrun error
SDIO_FLAG_RXOVERR: Received FIFO
overrun error
SDIO_FLAG_CMDREND: Command
response received (CRC check passed)
SDIO_FLAG_CMDSENT: Command sent
(no response required)
SDIO_FLAG_DATAEND: Data end (data
counter, SDIDCOUNT, is zero)
SDIO_FLAG_STBITERR: Start bit not
detected on all data signals in wide bus
mode
SDIO_FLAG_DBCKEND: Data block
sent/received (CRC check passed)
SDIO_FLAG_SDIOIT: SD I/O interrupt
received
SDIO_FLAG_CEATAEND: CE-ATA
command completion signal received for
CMD61
Return value:
None

__HAL_SD_SDIO_GET_IT

Description:
Check whether the specified SD interrupt has
occurred or not.
Parameters:
__HANDLE__: SD Handle
__INTERRUPT__: specifies the SDIO interrupt
source to check. This parameter can be one of
the following values:

784/964

DocID025834 Rev 4

UM1725

HAL SD Generic Driver
SDIO_IT_CCRCFAIL: Command response
received (CRC check failed) interrupt
SDIO_IT_DCRCFAIL: Data block
sent/received (CRC check failed) interrupt
SDIO_IT_CTIMEOUT: Command response
timeout interrupt
SDIO_IT_DTIMEOUT: Data timeout
interrupt
SDIO_IT_TXUNDERR: Transmit FIFO
underrun error interrupt
SDIO_IT_RXOVERR: Received FIFO
overrun error interrupt
SDIO_IT_CMDREND: Command response
received (CRC check passed) interrupt
SDIO_IT_CMDSENT: Command sent (no
response required) interrupt
SDIO_IT_DATAEND: Data end (data
counter, SDIDCOUNT, is zero) interrupt
SDIO_IT_STBITERR: Start bit not detected
on all data signals in wide bus mode
interrupt
SDIO_IT_DBCKEND: Data block
sent/received (CRC check passed) interrupt
SDIO_IT_CMDACT: Command transfer in
progress interrupt
SDIO_IT_TXACT: Data transmit in progress
interrupt
SDIO_IT_RXACT: Data receive in progress
interrupt
SDIO_IT_TXFIFOHE: Transmit FIFO Half
Empty interrupt
SDIO_IT_RXFIFOHF: Receive FIFO Half
Full interrupt
SDIO_IT_TXFIFOF: Transmit FIFO full
interrupt
SDIO_IT_RXFIFOF: Receive FIFO full
interrupt
SDIO_IT_TXFIFOE: Transmit FIFO empty
interrupt
SDIO_IT_RXFIFOE: Receive FIFO empty
interrupt
SDIO_IT_TXDAVL: Data available in
transmit FIFO interrupt
SDIO_IT_RXDAVL: Data available in
receive FIFO interrupt
SDIO_IT_SDIOIT: SD I/O interrupt received
interrupt
SDIO_IT_CEATAEND: CE-ATA command
completion signal received for CMD61
interrupt
Return value:
The: new state of SD IT (SET or RESET).

DocID025834 Rev 4

785/964

HAL SD Generic Driver
__HAL_SD_SDIO_CLEAR_IT

UM1725
Description:
Clear the SD's interrupt pending bits.
Parameters:
__HANDLE__: SD Handle
__INTERRUPT__: specifies the interrupt
pending bit to clear. This parameter can be one
or a combination of the following values:
SDIO_IT_CCRCFAIL: Command response
received (CRC check failed) interrupt
SDIO_IT_DCRCFAIL: Data block
sent/received (CRC check failed) interrupt
SDIO_IT_CTIMEOUT: Command response
timeout interrupt
SDIO_IT_DTIMEOUT: Data timeout
interrupt
SDIO_IT_TXUNDERR: Transmit FIFO
underrun error interrupt
SDIO_IT_RXOVERR: Received FIFO
overrun error interrupt
SDIO_IT_CMDREND: Command response
received (CRC check passed) interrupt
SDIO_IT_CMDSENT: Command sent (no
response required) interrupt
SDIO_IT_DATAEND: Data end (data
counter, SDIO_DCOUNT, is zero) interrupt
SDIO_IT_STBITERR: Start bit not detected
on all data signals in wide bus mode
interrupt
SDIO_IT_SDIOIT: SD I/O interrupt received
interrupt
SDIO_IT_CEATAEND: CE-ATA command
completion signal received for CMD61
Return value:
None

SD Handle Structure definition
SD_InitTypeDef
SD_TypeDef

786/964

DocID025834 Rev 4

UM1725

HAL SMARTCARD Generic Driver

58

HAL SMARTCARD Generic Driver

58.1

SMARTCARD Firmware driver registers structures

58.1.1

SMARTCARD_InitTypeDef
Data Fields
uint32_t BaudRate
uint32_t WordLength
uint32_t StopBits
uint32_t Parity
uint32_t Mode
uint32_t CLKPolarity
uint32_t CLKPhase
uint32_t CLKLastBit
uint32_t Prescaler
uint32_t GuardTime
uint32_t NACKState

Field Documentation
uint32_t SMARTCARD_InitTypeDef::BaudRate
This member configures the SmartCard communication baud rate. The baud rate is
computed using the following formula:IntegerDivider = ((PCLKx) / (8 * (hirda>Init.BaudRate)))FractionalDivider = ((IntegerDivider - ((uint32_t) IntegerDivider)) * 8)
+ 0.5
uint32_t SMARTCARD_InitTypeDef::WordLength
Specifies the number of data bits transmitted or received in a frame. This parameter
can be a value of SMARTCARD_Word_Length
uint32_t SMARTCARD_InitTypeDef::StopBits
Specifies the number of stop bits transmitted. This parameter can be a value of
SMARTCARD_Stop_Bits
uint32_t SMARTCARD_InitTypeDef::Parity
Specifies the parity mode. This parameter can be a value of SMARTCARD_Parity
Note:When parity is enabled, the computed parity is inserted at the MSB position of
the transmitted data (9th bit when the word length is set to 9 data bits; 8th bit when the
word length is set to 8 data bits).
uint32_t SMARTCARD_InitTypeDef::Mode
Specifies whether the Receive or Transmit mode is enabled or disabled. This
parameter can be a value of SMARTCARD_Mode
uint32_t SMARTCARD_InitTypeDef::CLKPolarity
Specifies the steady state of the serial clock. This parameter can be a value of
SMARTCARD_Clock_Polarity
uint32_t SMARTCARD_InitTypeDef::CLKPhase
Specifies the clock transition on which the bit capture is made. This parameter can be
a value of SMARTCARD_Clock_Phase
uint32_t SMARTCARD_InitTypeDef::CLKLastBit
Specifies whether the clock pulse corresponding to the last transmitted data bit (MSB)

DocID025834 Rev 4

787/964

HAL SMARTCARD Generic Driver
UM1725
has to be output on the SCLK pin in synchronous mode. This parameter can be a
value of SMARTCARD_Last_Bit
uint32_t SMARTCARD_InitTypeDef::Prescaler
Specifies the SmartCard Prescaler value used for dividing the system clock to provide
the smartcard clock. The value given in the register (5 significant bits) is multiplied by
2 to give the division factor of the source clock frequency. This parameter can be a
value of SMARTCARD_Prescaler
uint32_t SMARTCARD_InitTypeDef::GuardTime
Specifies the SmartCard Guard Time value in terms of number of baud clocks
uint32_t SMARTCARD_InitTypeDef::NACKState
Specifies the SmartCard NACK Transmission state. This parameter can be a value of
SMARTCARD_NACK_State

58.1.2

SMARTCARD_HandleTypeDef
Data Fields
USART_TypeDef * Instance
SMARTCARD_InitTypeDef Init
uint8_t * pTxBuffPtr
uint16_t TxXferSize
uint16_t TxXferCount
uint8_t * pRxBuffPtr
uint16_t RxXferSize
uint16_t RxXferCount
DMA_HandleTypeDef * hdmatx
DMA_HandleTypeDef * hdmarx
HAL_LockTypeDef Lock
__IO HAL_SMARTCARD_StateTypeDef gState
__IO HAL_SMARTCARD_StateTypeDef RxState
__IO uint32_t ErrorCode

Field Documentation
USART_TypeDef* SMARTCARD_HandleTypeDef::Instance
SMARTCARD_InitTypeDef SMARTCARD_HandleTypeDef::Init
uint8_t* SMARTCARD_HandleTypeDef::pTxBuffPtr
uint16_t SMARTCARD_HandleTypeDef::TxXferSize
uint16_t SMARTCARD_HandleTypeDef::TxXferCount
uint8_t* SMARTCARD_HandleTypeDef::pRxBuffPtr
uint16_t SMARTCARD_HandleTypeDef::RxXferSize
uint16_t SMARTCARD_HandleTypeDef::RxXferCount
DMA_HandleTypeDef* SMARTCARD_HandleTypeDef::hdmatx
DMA_HandleTypeDef* SMARTCARD_HandleTypeDef::hdmarx
HAL_LockTypeDef SMARTCARD_HandleTypeDef::Lock
__IO HAL_SMARTCARD_StateTypeDef SMARTCARD_HandleTypeDef::gState
__IO HAL_SMARTCARD_StateTypeDef SMARTCARD_HandleTypeDef::RxState
__IO uint32_t SMARTCARD_HandleTypeDef::ErrorCode

788/964

DocID025834 Rev 4

UM1725

HAL SMARTCARD Generic Driver

58.2

SMARTCARD Firmware driver API description

58.2.1

How to use this driver
The SMARTCARD HAL driver can be used as follows:
1.
2.

3.
4.

Declare a SMARTCARD_HandleTypeDef handle structure.
Initialize the SMARTCARD low level resources by implementing the
HAL_SMARTCARD_MspInit() API:
a.
Enable the USARTx interface clock.
b.
SMARTCARD pins configuration:
Enable the clock for the SMARTCARD GPIOs.
Configure these SMARTCARD pins as alternate function pull-up.
c.
NVIC configuration if you need to use interrupt process
(HAL_SMARTCARD_Transmit_IT() and HAL_SMARTCARD_Receive_IT() APIs):
Configure the USARTx interrupt priority.
Enable the NVIC USART IRQ handle.
d.
DMA Configuration if you need to use DMA process
(HAL_SMARTCARD_Transmit_DMA() and HAL_SMARTCARD_Receive_DMA()
APIs):
Declare a DMA handle structure for the Tx/Rx stream.
Enable the DMAx interface clock.
Configure the declared DMA handle structure with the required Tx/Rx
parameters.
Configure the DMA Tx/Rx Stream.
Associate the initialized DMA handle to the SMARTCARD DMA Tx/Rx
handle.
Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Tx/Rx Stream.
Program the Baud Rate, Word Length , Stop Bit, Parity, Hardware flow control and
Mode(Receiver/Transmitter) in the SMARTCARD Init structure.
Initialize the SMARTCARD registers by calling the HAL_SMARTCARD_Init() API:
These APIs configure also the low level Hardware GPIO, CLOCK,
CORTEX...etc) by calling the customized HAL_SMARTCARD_MspInit() API.
The specific SMARTCARD interrupts (Transmission complete interrupt, RXNE
interrupt and Error Interrupts) will be managed using the macros
__HAL_SMARTCARD_ENABLE_IT() and __HAL_SMARTCARD_DISABLE_IT()
inside the transmit and receive process.

Three operation modes are available within this driver :

Polling mode IO operation
Send an amount of data in blocking mode using HAL_SMARTCARD_Transmit()
Receive an amount of data in blocking mode using HAL_SMARTCARD_Receive()

Interrupt mode IO operation
Send an amount of data in non blocking mode using
HAL_SMARTCARD_Transmit_IT()

DocID025834 Rev 4

789/964

HAL SMARTCARD Generic Driver

UM1725

At transmission end of transfer HAL_SMARTCARD_TxCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_SMARTCARD_TxCpltCallback
Receive an amount of data in non blocking mode using
HAL_SMARTCARD_Receive_IT()
At reception end of transfer HAL_SMARTCARD_RxCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_SMARTCARD_RxCpltCallback
In case of transfer Error, HAL_SMARTCARD_ErrorCallback() function is executed
and user can add his own code by customization of function pointer
HAL_SMARTCARD_ErrorCallback

DMA mode IO operation
Send an amount of data in non blocking mode (DMA) using
HAL_SMARTCARD_Transmit_DMA()
At transmission end of transfer HAL_SMARTCARD_TxCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_SMARTCARD_TxCpltCallback
Receive an amount of data in non blocking mode (DMA) using
HAL_SMARTCARD_Receive_DMA()
At reception end of transfer HAL_SMARTCARD_RxCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_SMARTCARD_RxCpltCallback
In case of transfer Error, HAL_SMARTCARD_ErrorCallback() function is executed
and user can add his own code by customization of function pointer
HAL_SMARTCARD_ErrorCallback

SMARTCARD HAL driver macros list
Below the list of most used macros in SMARTCARD HAL driver.
__HAL_SMARTCARD_ENABLE: Enable the SMARTCARD peripheral
__HAL_SMARTCARD_DISABLE: Disable the SMARTCARD peripheral
__HAL_SMARTCARD_GET_FLAG : Check whether the specified SMARTCARD flag
is set or not
__HAL_SMARTCARD_CLEAR_FLAG : Clear the specified SMARTCARD pending
flag
__HAL_SMARTCARD_ENABLE_IT: Enable the specified SMARTCARD interrupt
__HAL_SMARTCARD_DISABLE_IT: Disable the specified SMARTCARD interrupt
You can refer to the SMARTCARD HAL driver header file for more useful macros

58.2.2

Initialization and Configuration functions
This subsection provides a set of functions allowing to initialize the USART in Smartcard
mode.
The Smartcard interface is designed to support asynchronous protocol Smartcards as
defined in the ISO 7816-3 standard.

790/964

DocID025834 Rev 4

UM1725

HAL SMARTCARD Generic Driver
The USART can provide a clock to the smartcard through the SCLK output. In smartcard
mode, SCLK is not associated to the communication but is simply derived from the internal
peripheral input clock through a 5-bit prescaler.

For the Smartcard mode only these parameters can be configured:
Baud Rate
Word Length => Should be 9 bits (8 bits + parity)
Stop Bit
Parity: => Should be enabled
USART polarity
USART phase
USART LastBit
Receiver/transmitter modes
Prescaler
GuardTime
NACKState: The Smartcard NACK state
Recommended SmartCard interface configuration to get the Answer to Reset from
the Card:
Word Length = 9 Bits
1.5 Stop Bit
Even parity
BaudRate = 12096 baud
Tx and Rx enabled
Please refer to the ISO 7816-3 specification for more details.
It is also possible to choose 0.5 stop bit for receiving but it is recommended to
use 1.5 stop bits for both transmitting and receiving to avoid switching between
the two configurations.
The HAL_SMARTCARD_Init() function follows the USART SmartCard configuration
procedure (details for the procedure are available in reference manual (RM0329)).
This section contains the following APIs:
HAL_SMARTCARD_Init()
HAL_SMARTCARD_DeInit()
HAL_SMARTCARD_MspInit()
HAL_SMARTCARD_MspDeInit()
HAL_SMARTCARD_ReInit()

58.2.3

IO operation functions
This subsection provides a set of functions allowing to manage the SMARTCARD data
transfers. Smartcard is a single wire half duplex communication protocol. The Smartcard
interface is designed to support asynchronous protocol Smartcards as defined in the ISO
7816-3 standard. The USART should be configured as: (+) 8 bits plus parity: where M=1
and PCE=1 in the USART_CR1 register (+) 1.5 stop bits when transmitting and receiving:
where STOP=11 in the USART_CR2 register.
1.

There are two modes of transfer:
Blocking mode: The communication is performed in polling mode. The HAL
status of all data processing is returned by the same function after finishing
transfer.
DocID025834 Rev 4

791/964

HAL SMARTCARD Generic Driver

2.

3.

4.

5.

UM1725

Non Blocking mode: The communication is performed using Interrupts or DMA,
These APIs return the HAL status. The end of the data processing will be
indicated through the dedicated SMARTCARD IRQ when using Interrupt mode or
the DMA IRQ when using DMA mode. The
HAL_SMARTCARD_TxCpltCallback(), HAL_SMARTCARD_RxCpltCallback()
user callbacks will be executed respectively at the end of the Transmit or Receive
process The HAL_SMARTCARD_ErrorCallback() user callback will be executed
when a communication error is detected
Blocking mode APIs are :
HAL_SMARTCARD_Transmit()
HAL_SMARTCARD_Receive()
Non Blocking mode APIs with Interrupt are :
HAL_SMARTCARD_Transmit_IT()
HAL_SMARTCARD_Receive_IT()
HAL_SMARTCARD_IRQHandler()
Non Blocking mode functions with DMA are :
HAL_SMARTCARD_Transmit_DMA()
HAL_SMARTCARD_Receive_DMA()
A set of Transfer Complete Callbacks are provided in non Blocking mode:
HAL_SMARTCARD_TxCpltCallback()
HAL_SMARTCARD_RxCpltCallback()
HAL_SMARTCARD_ErrorCallback()

This subsection provides a set of functions allowing to manage the SMARTCARD data
transfers. Smartcard is a single wire half duplex communication protocol. The Smartcard
interface is designed to support asynchronous protocol Smartcards as defined in the ISO
7816-3 standard. The USART should be configured as:
8 bits plus parity: where M=1 and PCE=1 in the USART_CR1 register
1.5 stop bits when transmitting and receiving: where STOP=11 in the USART_CR2
register. (#) There are two modes of transfer:
Blocking mode: The communication is performed in polling mode. The HAL
status of all data processing is returned by the same function after finishing
transfer.
Non Blocking mode: The communication is performed using Interrupts or DMA,
These APIs return the HAL status. The end of the data processing will be
indicated through the dedicated SMARTCARD IRQ when using Interrupt mode or
the DMA IRQ when using DMA mode. The
HAL_SMARTCARD_TxCpltCallback(), HAL_SMARTCARD_RxCpltCallback()
user callbacks will be executed respectively at the end of the Transmit or Receive
process The HAL_SMARTCARD_ErrorCallback() user callback will be executed
when a communication error is detected (#) Blocking mode APIs are :
HAL_SMARTCARD_Transmit()
HAL_SMARTCARD_Receive() (#) Non Blocking mode APIs with Interrupt are :
HAL_SMARTCARD_Transmit_IT()
HAL_SMARTCARD_Receive_IT()
HAL_SMARTCARD_IRQHandler() (#) Non Blocking mode functions with DMA
are :
HAL_SMARTCARD_Transmit_DMA()
HAL_SMARTCARD_Receive_DMA() (#) A set of Transfer Complete Callbacks
are provided in non Blocking mode:
HAL_SMARTCARD_TxCpltCallback()
HAL_SMARTCARD_RxCpltCallback()
HAL_SMARTCARD_ErrorCallback()

792/964

DocID025834 Rev 4

UM1725

HAL SMARTCARD Generic Driver
This section contains the following APIs:
HAL_SMARTCARD_Transmit()
HAL_SMARTCARD_Receive()
HAL_SMARTCARD_Transmit_IT()
HAL_SMARTCARD_Receive_IT()
HAL_SMARTCARD_Transmit_DMA()
HAL_SMARTCARD_Receive_DMA()
HAL_SMARTCARD_IRQHandler()
HAL_SMARTCARD_TxCpltCallback()
HAL_SMARTCARD_RxCpltCallback()
HAL_SMARTCARD_ErrorCallback()

58.2.4

Peripheral State and Errors functions
This subsection provides a set of functions allowing to control the SmartCard.
HAL_SMARTCARD_GetState() API can be helpful to check in run-time the state of
the SmartCard peripheral.
HAL_SMARTCARD_GetError() check in run-time errors that could be occurred during
communication.
This section contains the following APIs:
HAL_SMARTCARD_GetState()
HAL_SMARTCARD_GetError()

58.2.5

Detailed description of functions
HAL_SMARTCARD_Init
Function Name

HAL_StatusTypeDef HAL_SMARTCARD_Init
(SMARTCARD_HandleTypeDef * hsc)

Function Description

Initializes the SmartCard mode according to the specified
parameters in the SMARTCARD_InitTypeDef and create the
associated handle .

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.

Return values

HAL: status

HAL_SMARTCARD_ReInit
Function Name

HAL_StatusTypeDef HAL_SMARTCARD_ReInit
(SMARTCARD_HandleTypeDef * hsc)

Function Description

HAL_SMARTCARD_DeInit
Function Name

HAL_StatusTypeDef HAL_SMARTCARD_DeInit
(SMARTCARD_HandleTypeDef * hsc)

Function Description

DeInitializes the USART SmartCard peripheral.

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
DocID025834 Rev 4

793/964

HAL SMARTCARD Generic Driver

UM1725
module.

Return values

HAL: status

HAL_SMARTCARD_MspInit
Function Name

void HAL_SMARTCARD_MspInit
(SMARTCARD_HandleTypeDef * hsc)

Function Description

SMARTCARD MSP Init.

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.

Return values

None

HAL_SMARTCARD_MspDeInit
Function Name

void HAL_SMARTCARD_MspDeInit
(SMARTCARD_HandleTypeDef * hsc)

Function Description

SMARTCARD MSP DeInit.

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.

Return values

None

HAL_SMARTCARD_Transmit
Function Name

HAL_StatusTypeDef HAL_SMARTCARD_Transmit
(SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t
Size, uint32_t Timeout)

Function Description

Send an amount of data in blocking mode.

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.
pData: pointer to data buffer
Size: amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_SMARTCARD_Receive
Function Name

HAL_StatusTypeDef HAL_SMARTCARD_Receive
(SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t
Size, uint32_t Timeout)

Function Description

Receive an amount of data in blocking mode.

Parameters

794/964

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.
pData: pointer to data buffer
Size: amount of data to be received
DocID025834 Rev 4

UM1725

HAL SMARTCARD Generic Driver
Timeout: Timeout duration
Return values

HAL: status

HAL_SMARTCARD_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_SMARTCARD_Transmit_IT
(SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t
Size)

Function Description

Send an amount of data in non blocking mode.

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.
pData: pointer to data buffer
Size: amount of data to be sent

Return values

HAL: status

HAL_SMARTCARD_Receive_IT
Function Name

HAL_StatusTypeDef HAL_SMARTCARD_Receive_IT
(SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t
Size)

Function Description

Receive an amount of data in non blocking mode.

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.
pData: pointer to data buffer
Size: amount of data to be received

Return values

HAL: status

HAL_SMARTCARD_Transmit_DMA
Function Name

HAL_StatusTypeDef HAL_SMARTCARD_Transmit_DMA
(SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t
Size)

Function Description

Send an amount of data in non blocking mode.

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.
pData: pointer to data buffer
Size: amount of data to be sent

Return values

HAL: status

HAL_SMARTCARD_Receive_DMA
Function Name

HAL_StatusTypeDef HAL_SMARTCARD_Receive_DMA
(SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t
Size)

Function Description

Receive an amount of data in non blocking mode.
DocID025834 Rev 4

795/964

HAL SMARTCARD Generic Driver
Parameters

UM1725
hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.
pData: pointer to data buffer
Size: amount of data to be received

Return values

HAL: status

Notes

When the SMARTCARD parity is enabled (PCE = 1) the data
received contain the parity bit.s

HAL_SMARTCARD_IRQHandler
Function Name

void HAL_SMARTCARD_IRQHandler
(SMARTCARD_HandleTypeDef * hsc)

Function Description

This function handles SMARTCARD interrupt request.

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.

Return values

None

HAL_SMARTCARD_TxCpltCallback
Function Name

void HAL_SMARTCARD_TxCpltCallback
(SMARTCARD_HandleTypeDef * hsc)

Function Description

Tx Transfer completed callbacks.

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.

Return values

None

HAL_SMARTCARD_RxCpltCallback
Function Name

void HAL_SMARTCARD_RxCpltCallback
(SMARTCARD_HandleTypeDef * hsc)

Function Description

Rx Transfer completed callbacks.

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.

Return values

None

HAL_SMARTCARD_ErrorCallback
Function Name

void HAL_SMARTCARD_ErrorCallback
(SMARTCARD_HandleTypeDef * hsc)

Function Description

SMARTCARD error callbacks.

Parameters

796/964

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.
DocID025834 Rev 4

UM1725

HAL SMARTCARD Generic Driver
Return values

None

HAL_SMARTCARD_GetState
Function Name

HAL_SMARTCARD_StateTypeDef
HAL_SMARTCARD_GetState (SMARTCARD_HandleTypeDef *
hsc)

Function Description

return the SMARTCARD state

Parameters

hsc: pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for SMARTCARD
module.

Return values

HAL: state

HAL_SMARTCARD_GetError
Function Name

uint32_t HAL_SMARTCARD_GetError
(SMARTCARD_HandleTypeDef * hsc)

Function Description

Return the SMARTCARD error code.

Parameters

hsc: : pointer to a SMARTCARD_HandleTypeDef structure
that contains the configuration information for the specified
SMARTCARD.

Return values

SMARTCARD: Error Code

58.3

SMARTCARD Firmware driver defines

58.3.1

SMARTCARD
SMARTCARD Clock Phase
SMARTCARD_PHASE_1EDGE
SMARTCARD_PHASE_2EDGE
SMARTCARD Clock Polarity
SMARTCARD_POLARITY_LOW
SMARTCARD_POLARITY_HIGH
SMARTCARD DMA requests
SMARTCARD_DMAREQ_TX
SMARTCARD_DMAREQ_RX

SMARTCARD Error Code
HAL_SMARTCARD_ERROR_NONE

No error

HAL_SMARTCARD_ERROR_PE

Parity error

HAL_SMARTCARD_ERROR_NE

Noise error

HAL_SMARTCARD_ERROR_FE

Frame error

HAL_SMARTCARD_ERROR_ORE

Overrun error

DocID025834 Rev 4

797/964

HAL SMARTCARD Generic Driver
HAL_SMARTCARD_ERROR_DMA

UM1725
DMA transfer error

SMARTCARD Exported Macros
__HAL_SMARTCARD_RESET_HANDLE_STA
TE

Description:
Reset SMARTCARD handle gstate
& RxState.
Parameters:
__HANDLE__: specifies the
SMARTCARD Handle.
Return value:
None

__HAL_SMARTCARD_FLUSH_DRREGISTER

Description:
Flushs the Smartcard DR register.
Parameters:
__HANDLE__: specifies the
SMARTCARD Handle.

__HAL_SMARTCARD_GET_FLAG

Description:
Checks whether the specified
Smartcard flag is set or not.
Parameters:
__HANDLE__: specifies the
SMARTCARD Handle.
__FLAG__: specifies the flag to
check. This parameter can be one
of the following values:
SMARTCARD_FLAG_TXE:
Transmit data register empty
flag
SMARTCARD_FLAG_TC:
Transmission Complete flag
SMARTCARD_FLAG_RXNE:
Receive data register not
empty flag
SMARTCARD_FLAG_IDLE:
Idle Line detection flag
SMARTCARD_FLAG_ORE:
Overrun Error flag
SMARTCARD_FLAG_NE:
Noise Error flag
SMARTCARD_FLAG_FE:
Framing Error flag
SMARTCARD_FLAG_PE:
Parity Error flag
Return value:
The: new state of __FLAG__
(TRUE or FALSE).

798/964

DocID025834 Rev 4

UM1725
__HAL_SMARTCARD_CLEAR_FLAG

HAL SMARTCARD Generic Driver
Description:
Clears the specified Smartcard
pending flags.
Parameters:
__HANDLE__: specifies the
SMARTCARD Handle.
__FLAG__: specifies the flag to
check. This parameter can be any
combination of the following
values:
SMARTCARD_FLAG_TC:
Transmission Complete flag.
SMARTCARD_FLAG_RXNE:
Receive data register not
empty flag.
Notes:
PE (Parity error), FE (Framing
error), NE (Noise error) and ORE
(Overrun error) flags are cleared
by software sequence: a read
operation to USART_SR register
followed by a read operation to
USART_DR register. RXNE flag
can be also cleared by a read to
the USART_DR register. TC flag
can be also cleared by software
sequence: a read operation to
USART_SR register followed by a
write operation to USART_DR
register. TXE flag is cleared only
by a write to the USART_DR
register.

__HAL_SMARTCARD_CLEAR_PEFLAG

Description:
Clear the SMARTCARD PE
pending flag.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3,
4, 5, 6, 7 or 8 to select the USART
or SMARTCARD peripheral.
Return value:
None

__HAL_SMARTCARD_CLEAR_FEFLAG

Description:
Clear the SMARTCARD FE
pending flag.
Parameters:

DocID025834 Rev 4

799/964

HAL SMARTCARD Generic Driver

UM1725
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3,
4, 5, 6, 7 or 8 to select the USART
or SMARTCARD peripheral.
Return value:
None

__HAL_SMARTCARD_CLEAR_NEFLAG

Description:
Clear the SMARTCARD NE
pending flag.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3,
4, 5, 6, 7 or 8 to select the USART
or SMARTCARD peripheral.
Return value:
None

__HAL_SMARTCARD_CLEAR_OREFLAG

Description:
Clear the SMARTCARD ORE
pending flag.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3,
4, 5, 6, 7 or 8 to select the USART
or SMARTCARD peripheral.
Return value:
None

__HAL_SMARTCARD_CLEAR_IDLEFLAG

Description:
Clear the SMARTCARD IDLE
pending flag.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3,
4, 5, 6, 7 or 8 to select the USART
or SMARTCARD peripheral.
Return value:
None

__HAL_SMARTCARD_ENABLE_IT

Description:
Enables or disables the specified
SmartCard interrupts.

800/964

DocID025834 Rev 4

UM1725

HAL SMARTCARD Generic Driver
Parameters:
__HANDLE__: specifies the
SMARTCARD Handle.
__INTERRUPT__: specifies the
SMARTCARD interrupt source to
check. This parameter can be one
of the following values:
SMARTCARD_IT_TXE:
Transmit Data Register empty
interrupt
SMARTCARD_IT_TC:
Transmission complete
interrupt
SMARTCARD_IT_RXNE:
Receive Data register not
empty interrupt
SMARTCARD_IT_IDLE: Idle
line detection interrupt
SMARTCARD_IT_PE: Parity
Error interrupt
SMARTCARD_IT_ERR: Error
interrupt(Frame error, noise
error, overrun error)
__HAL_SMARTCARD_DISABLE_IT
__HAL_SMARTCARD_GET_IT_SOURCE

Description:
Checks whether the specified
SmartCard interrupt has occurred
or not.
Parameters:
__HANDLE__: specifies the
SmartCard Handle.
__IT__: specifies the
SMARTCARD interrupt source to
check. This parameter can be one
of the following values:
SMARTCARD_IT_TXE:
Transmit Data Register empty
interrupt
SMARTCARD_IT_TC:
Transmission complete
interrupt
SMARTCARD_IT_RXNE:
Receive Data register not
empty interrupt
SMARTCARD_IT_IDLE: Idle
line detection interrupt
SMARTCARD_IT_ERR: Error
interrupt
SMARTCARD_IT_PE: Parity
Error interrupt

DocID025834 Rev 4

801/964

HAL SMARTCARD Generic Driver

UM1725
Return value:
The: new state of __IT__ (TRUE or
FALSE).

__HAL_SMARTCARD_ONE_BIT_SAMPLE_EN
ABLE

Description:
Macro to enable the
SMARTCARD's one bit sample
method.
Parameters:
__HANDLE__: specifies the
SMARTCARD Handle.
Return value:
None

__HAL_SMARTCARD_ONE_BIT_SAMPLE_DI
SABLE

Description:
Macro to disable the
SMARTCARD's one bit sample
method.
Parameters:
__HANDLE__: specifies the
SMARTCARD Handle.
Return value:
None

__HAL_SMARTCARD_ENABLE

Description:
Enable the USART associated to
the SMARTCARD Handle.
Parameters:
__HANDLE__: specifies the
SMARTCARD Handle.
SMARTCARD Handle selects the
USARTx peripheral (USART
availability and x value depending
on device).
Return value:
None

__HAL_SMARTCARD_DISABLE

Description:
Disable the USART associated to
the SMARTCARD Handle.
Parameters:
__HANDLE__: specifies the
SMARTCARD Handle.
SMARTCARD Handle selects the
USARTx peripheral (USART
availability and x value depending

802/964

DocID025834 Rev 4

UM1725

HAL SMARTCARD Generic Driver
on device).
Return value:
None
Description:

__HAL_SMARTCARD_DMA_REQUEST_ENAB
LE

Macros to enable or disable the
SmartCard DMA request.
Parameters:
__HANDLE__: specifies the
SmartCard Handle.
__REQUEST__: specifies the
SmartCard DMA request. This
parameter can be one of the
following values:
SMARTCARD_DMAREQ_TX:
SmartCard DMA transmit
request
SMARTCARD_DMAREQ_RX
: SmartCard DMA receive
request

__HAL_SMARTCARD_DMA_REQUEST_DISA
BLE
SMARTCARD Last Bit
SMARTCARD_LASTBIT_DISABLE
SMARTCARD_LASTBIT_ENABLE
SMARTCARD Mode
SMARTCARD_MODE_RX
SMARTCARD_MODE_TX
SMARTCARD_MODE_TX_RX
SMARTCARD NACK State
SMARTCARD_NACK_ENABLE
SMARTCARD_NACK_DISABLE
SMARTCARD Parity
SMARTCARD_PARITY_EVEN
SMARTCARD_PARITY_ODD
SMARTCARD Prescaler
SMARTCARD_PRESCALER_SYSCLK_DIV2

SYSCLK divided by 2

SMARTCARD_PRESCALER_SYSCLK_DIV4

SYSCLK divided by 4

SMARTCARD_PRESCALER_SYSCLK_DIV6

SYSCLK divided by 6

SMARTCARD_PRESCALER_SYSCLK_DIV8

SYSCLK divided by 8

SMARTCARD_PRESCALER_SYSCLK_DIV10

SYSCLK divided by 10

SMARTCARD_PRESCALER_SYSCLK_DIV12

SYSCLK divided by 12

DocID025834 Rev 4

803/964

HAL SMARTCARD Generic Driver
SMARTCARD_PRESCALER_SYSCLK_DIV14

SYSCLK divided by 14

UM1725

SMARTCARD_PRESCALER_SYSCLK_DIV16

SYSCLK divided by 16

SMARTCARD_PRESCALER_SYSCLK_DIV18

SYSCLK divided by 18

SMARTCARD_PRESCALER_SYSCLK_DIV20

SYSCLK divided by 20

SMARTCARD_PRESCALER_SYSCLK_DIV22

SYSCLK divided by 22

SMARTCARD_PRESCALER_SYSCLK_DIV24

SYSCLK divided by 24

SMARTCARD_PRESCALER_SYSCLK_DIV26

SYSCLK divided by 26

SMARTCARD_PRESCALER_SYSCLK_DIV28

SYSCLK divided by 28

SMARTCARD_PRESCALER_SYSCLK_DIV30

SYSCLK divided by 30

SMARTCARD_PRESCALER_SYSCLK_DIV32

SYSCLK divided by 32

SMARTCARD_PRESCALER_SYSCLK_DIV34

SYSCLK divided by 34

SMARTCARD_PRESCALER_SYSCLK_DIV36

SYSCLK divided by 36

SMARTCARD_PRESCALER_SYSCLK_DIV38

SYSCLK divided by 38

SMARTCARD_PRESCALER_SYSCLK_DIV40

SYSCLK divided by 40

SMARTCARD_PRESCALER_SYSCLK_DIV42

SYSCLK divided by 42

SMARTCARD_PRESCALER_SYSCLK_DIV44

SYSCLK divided by 44

SMARTCARD_PRESCALER_SYSCLK_DIV46

SYSCLK divided by 46

SMARTCARD_PRESCALER_SYSCLK_DIV48

SYSCLK divided by 48

SMARTCARD_PRESCALER_SYSCLK_DIV50

SYSCLK divided by 50

SMARTCARD_PRESCALER_SYSCLK_DIV52

SYSCLK divided by 52

SMARTCARD_PRESCALER_SYSCLK_DIV54

SYSCLK divided by 54

SMARTCARD_PRESCALER_SYSCLK_DIV56

SYSCLK divided by 56

SMARTCARD_PRESCALER_SYSCLK_DIV58

SYSCLK divided by 58

SMARTCARD_PRESCALER_SYSCLK_DIV60

SYSCLK divided by 60

SMARTCARD_PRESCALER_SYSCLK_DIV62

SYSCLK divided by 62

SMARTCARD Number of Stop Bits
SMARTCARD_STOPBITS_0_5
SMARTCARD_STOPBITS_1_5
SMARTCARD Word Length
SMARTCARD_WORDLENGTH_9B

804/964

DocID025834 Rev 4

UM1725

HAL SPDIFRX Generic Driver

59

HAL SPDIFRX Generic Driver

59.1

SPDIFRX Firmware driver registers structures

59.1.1

SPDIFRX_InitTypeDef
Data Fields
uint32_t InputSelection
uint32_t Retries
uint32_t WaitForActivity
uint32_t ChannelSelection
uint32_t DataFormat
uint32_t StereoMode
uint32_t PreambleTypeMask
uint32_t ChannelStatusMask
uint32_t ValidityBitMask
uint32_t ParityErrorMask

Field Documentation
uint32_t SPDIFRX_InitTypeDef::InputSelection
Specifies the SPDIF input selection. This parameter can be a value of
SPDIFRX_Input_Selection
uint32_t SPDIFRX_InitTypeDef::Retries
Specifies the Maximum allowed re-tries during synchronization phase. This parameter
can be a value of SPDIFRX_Max_Retries
uint32_t SPDIFRX_InitTypeDef::WaitForActivity
Specifies the wait for activity on SPDIF selected input. This parameter can be a value
of SPDIFRX_Wait_For_Activity.
uint32_t SPDIFRX_InitTypeDef::ChannelSelection
Specifies whether the control flow will take the channel status from channel A or B.
This parameter can be a value of SPDIFRX_Channel_Selection
uint32_t SPDIFRX_InitTypeDef::DataFormat
Specifies the Data samples format (LSB, MSB, ...). This parameter can be a value of
SPDIFRX_Data_Format
uint32_t SPDIFRX_InitTypeDef::StereoMode
Specifies whether the peripheral is in stereo or mono mode. This parameter can be a
value of SPDIFRX_Stereo_Mode
uint32_t SPDIFRX_InitTypeDef::PreambleTypeMask
Specifies whether The preamble type bits are copied or not into the received frame.
This parameter can be a value of SPDIFRX_PT_Mask
uint32_t SPDIFRX_InitTypeDef::ChannelStatusMask
Specifies whether the channel status and user bits are copied or not into the received
frame. This parameter can be a value of SPDIFRX_ChannelStatus_Mask
uint32_t SPDIFRX_InitTypeDef::ValidityBitMask
Specifies whether the validity bit is copied or not into the received frame. This
parameter can be a value of SPDIFRX_V_Mask

DocID025834 Rev 4

805/964

HAL SPDIFRX Generic Driver

UM1725

uint32_t SPDIFRX_InitTypeDef::ParityErrorMask
Specifies whether the parity error bit is copied or not into the received frame. This
parameter can be a value of SPDIFRX_PE_Mask

59.1.2

SPDIFRX_SetDataFormatTypeDef
Data Fields
uint32_t DataFormat
uint32_t StereoMode
uint32_t PreambleTypeMask
uint32_t ChannelStatusMask
uint32_t ValidityBitMask
uint32_t ParityErrorMask

Field Documentation
uint32_t SPDIFRX_SetDataFormatTypeDef::DataFormat
Specifies the Data samples format (LSB, MSB, ...). This parameter can be a value of
SPDIFRX_Data_Format
uint32_t SPDIFRX_SetDataFormatTypeDef::StereoMode
Specifies whether the peripheral is in stereo or mono mode. This parameter can be a
value of SPDIFRX_Stereo_Mode
uint32_t SPDIFRX_SetDataFormatTypeDef::PreambleTypeMask
Specifies whether The preamble type bits are copied or not into the received frame.
This parameter can be a value of SPDIFRX_PT_Mask
uint32_t SPDIFRX_SetDataFormatTypeDef::ChannelStatusMask
Specifies whether the channel status and user bits are copied or not into the received
frame. This parameter can be a value of SPDIFRX_ChannelStatus_Mask
uint32_t SPDIFRX_SetDataFormatTypeDef::ValidityBitMask
Specifies whether the validity bit is copied or not into the received frame. This
parameter can be a value of SPDIFRX_V_Mask
uint32_t SPDIFRX_SetDataFormatTypeDef::ParityErrorMask
Specifies whether the parity error bit is copied or not into the received frame. This
parameter can be a value of SPDIFRX_PE_Mask

59.1.3

SPDIFRX_HandleTypeDef
Data Fields
SPDIFRX_TypeDef * Instance
SPDIFRX_InitTypeDef Init
uint32_t * pRxBuffPtr
uint32_t * pCsBuffPtr
__IO uint16_t RxXferSize
__IO uint16_t RxXferCount
__IO uint16_t CsXferSize
__IO uint16_t CsXferCount
DMA_HandleTypeDef * hdmaCsRx

806/964

DocID025834 Rev 4

UM1725

HAL SPDIFRX Generic Driver
DMA_HandleTypeDef * hdmaDrRx
__IO HAL_LockTypeDef Lock
__IO HAL_SPDIFRX_StateTypeDef State
__IO uint32_t ErrorCode

Field Documentation
SPDIFRX_TypeDef* SPDIFRX_HandleTypeDef::Instance
SPDIFRX_InitTypeDef SPDIFRX_HandleTypeDef::Init
uint32_t* SPDIFRX_HandleTypeDef::pRxBuffPtr
uint32_t* SPDIFRX_HandleTypeDef::pCsBuffPtr
__IO uint16_t SPDIFRX_HandleTypeDef::RxXferSize
__IO uint16_t SPDIFRX_HandleTypeDef::RxXferCount
__IO uint16_t SPDIFRX_HandleTypeDef::CsXferSize
__IO uint16_t SPDIFRX_HandleTypeDef::CsXferCount
DMA_HandleTypeDef* SPDIFRX_HandleTypeDef::hdmaCsRx
DMA_HandleTypeDef* SPDIFRX_HandleTypeDef::hdmaDrRx
__IO HAL_LockTypeDef SPDIFRX_HandleTypeDef::Lock
__IO HAL_SPDIFRX_StateTypeDef SPDIFRX_HandleTypeDef::State
__IO uint32_t SPDIFRX_HandleTypeDef::ErrorCode

59.2

SPDIFRX Firmware driver API description

59.2.1

How to use this driver
The SPDIFRX HAL driver can be used as follow:
1.
2.

Declare SPDIFRX_HandleTypeDef handle structure.
Initialize the SPDIFRX low level resources by implement the
HAL_SPDIFRX_MspInit() API:
a.
Enable the SPDIFRX interface clock.
b.
SPDIFRX pins configuration:
Enable the clock for the SPDIFRX GPIOs.
Configure these SPDIFRX pins as alternate function pull-up.
c.
NVIC configuration if you need to use interrupt process
(HAL_SPDIFRX_ReceiveControlFlow_IT() and
HAL_SPDIFRX_ReceiveDataFlow_IT() API's).
Configure the SPDIFRX interrupt priority.
Enable the NVIC SPDIFRX IRQ handle.
d.
DMA Configuration if you need to use DMA process
(HAL_SPDIFRX_ReceiveDataFlow_DMA() and
HAL_SPDIFRX_ReceiveControlFlow_DMA() API's).
Declare a DMA handle structure for the reception of the Data Flow channel.
Declare a DMA handle structure for the reception of the Control Flow
channel.
Enable the DMAx interface clock.
Configure the declared DMA handle structure CtrlRx/DataRx with the
required parameters.
Configure the DMA Channel.
Associate the initialized DMA handle to the SPDIFRX DMA CtrlRx/DataRx
handle.

DocID025834 Rev 4

807/964

HAL SPDIFRX Generic Driver

3.

4.

UM1725

Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA CtrlRx/DataRx channel.
Program the input selection, re-tries number, wait for activity, channel status
selection, data format, stereo mode and masking of user bits using
HAL_SPDIFRX_Init() function. The specific SPDIFRX interrupts (RXNE/CSRNE and
Error Interrupts) will be managed using the macros __SPDIFRX_ENABLE_IT() and
__SPDIFRX_DISABLE_IT() inside the receive process. Make sure that ck_spdif clock
is configured.
Three operation modes are available within this driver :

Polling mode for reception operation (for debug purpose)
Receive data flow in blocking mode using HAL_SPDIFRX_ReceiveDataFlow()
Receive control flow of data in blocking mode using
HAL_SPDIFRX_ReceiveControlFlow()

Interrupt mode for reception operation
Receive an amount of data (Data Flow) in non blocking mode using
HAL_SPDIFRX_ReceiveDataFlow_IT()
Receive an amount of data (Control Flow) in non blocking mode using
HAL_SPDIFRX_ReceiveControlFlow_IT()
At reception end of half transfer HAL_SPDIFRX_RxHalfCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_SPDIFRX_RxHalfCpltCallback
At reception end of transfer HAL_SPDIFRX_RxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_SPDIFRX_RxCpltCallback
In case of transfer Error, HAL_SPDIFRX_ErrorCallback() function is executed and
user can add his own code by customization of function pointer
HAL_SPDIFRX_ErrorCallback

DMA mode for reception operation
Receive an amount of data (Data Flow) in non blocking mode (DMA) using
HAL_SPDIFRX_ReceiveDataFlow_DMA()
Receive an amount of data (Control Flow) in non blocking mode (DMA) using
HAL_SPDIFRX_ReceiveControlFlow_DMA()
At reception end of half transfer HAL_SPDIFRX_RxHalfCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_SPDIFRX_RxHalfCpltCallback
At reception end of transfer HAL_SPDIFRX_RxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_SPDIFRX_RxCpltCallback
In case of transfer Error, HAL_SPDIFRX_ErrorCallback() function is executed and
user can add his own code by customization of function pointer
HAL_SPDIFRX_ErrorCallback
Stop the DMA Transfer using HAL_SPDIFRX_DMAStop()

SPDIFRX HAL driver macros list
Below the list of most used macros in SPDIFRX HAL driver.
__HAL_SPDIFRX_IDLE: Disable the specified SPDIFRX peripheral (IDEL State)
808/964

DocID025834 Rev 4

UM1725

HAL SPDIFRX Generic Driver
__HAL_SPDIFRX_SYNC: Enable the synchronization state of the specified SPDIFRX
peripheral (SYNC State)
__HAL_SPDIFRX_RCV: Enable the receive state of the specified SPDIFRX
peripheral (RCV State)
__HAL_SPDIFRX_ENABLE_IT : Enable the specified SPDIFRX interrupts
__HAL_SPDIFRX_DISABLE_IT : Disable the specified SPDIFRX interrupts
__HAL_SPDIFRX_GET_FLAG: Check whether the specified SPDIFRX flag is set or
not.
You can refer to the SPDIFRX HAL driver header file for more useful macros

59.2.2

Initialization and de-initialization functions
This subsection provides a set of functions allowing to initialize and de-initialize the
SPDIFRX peripheral:
User must Implement HAL_SPDIFRX_MspInit() function in which he configures all
related peripherals resources (CLOCK, GPIO, DMA, IT and NVIC ).
Call the function HAL_SPDIFRX_Init() to configure the SPDIFRX peripheral with the
selected configuration:
Input Selection (IN0, IN1,...)
Maximum allowed re-tries during synchronization phase
Wait for activity on SPDIF selected input
Channel status selection (from channel A or B)
Data format (LSB, MSB, ...)
Stereo mode
User bits masking (PT,C,U,V,...)
Call the function HAL_SPDIFRX_DeInit() to restore the default configuration of the
selected SPDIFRXx peripheral.
This section contains the following APIs:
HAL_SPDIFRX_Init()
HAL_SPDIFRX_DeInit()
HAL_SPDIFRX_MspInit()
HAL_SPDIFRX_MspDeInit()
HAL_SPDIFRX_SetDataFormat()

59.2.3

IO operation functions
This subsection provides a set of functions allowing to manage the SPDIFRX data
transfers.
1.

2.

There is two mode of transfer:
Blocking mode : The communication is performed in the polling mode. The
status of all data processing is returned by the same function after finishing
transfer.
No-Blocking mode : The communication is performed using Interrupts or DMA.
These functions return the status of the transfer start-up. The end of the data
processing will be indicated through the dedicated SPDIFRX IRQ when using
Interrupt mode or the DMA IRQ when using DMA mode.
Blocking mode functions are :
HAL_SPDIFRX_ReceiveDataFlow()
DocID025834 Rev 4

809/964

HAL SPDIFRX Generic Driver

3.

4.

5.

UM1725

HAL_SPDIFRX_ReceiveControlFlow() (+@) Do not use blocking mode to
receive both control and data flow at the same time.
No-Blocking mode functions with Interrupt are :
HAL_SPDIFRX_ReceiveControlFlow_IT()
HAL_SPDIFRX_ReceiveDataFlow_IT()
No-Blocking mode functions with DMA are :
HAL_SPDIFRX_ReceiveControlFlow_DMA()
HAL_SPDIFRX_ReceiveDataFlow_DMA()
A set of Transfer Complete Callbacks are provided in No_Blocking mode:
HAL_SPDIFRX_RxCpltCallback()
HAL_SPDIFRX_ErrorCallback()

This section contains the following APIs:
HAL_SPDIFRX_ReceiveDataFlow()
HAL_SPDIFRX_ReceiveControlFlow()
HAL_SPDIFRX_ReceiveDataFlow_IT()
HAL_SPDIFRX_ReceiveControlFlow_IT()
HAL_SPDIFRX_ReceiveDataFlow_DMA()
HAL_SPDIFRX_ReceiveControlFlow_DMA()
HAL_SPDIFRX_DMAStop()
HAL_SPDIFRX_IRQHandler()
HAL_SPDIFRX_RxHalfCpltCallback()
HAL_SPDIFRX_RxCpltCallback()
HAL_SPDIFRX_CxHalfCpltCallback()
HAL_SPDIFRX_CxCpltCallback()
HAL_SPDIFRX_ErrorCallback()

59.2.4

Peripheral State and Errors functions
This subsection permit to get in run-time the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_SPDIFRX_GetState()
HAL_SPDIFRX_GetError()

59.2.5

Detailed description of functions
HAL_SPDIFRX_Init
Function Name

HAL_StatusTypeDef HAL_SPDIFRX_Init
(SPDIFRX_HandleTypeDef * hspdif)

Function Description

Initializes the SPDIFRX according to the specified parameters in
the SPDIFRX_InitTypeDef and create the associated handle.

Parameters

hspdif: SPDIFRX handle

Return values

HAL: status

HAL_SPDIFRX_DeInit

810/964

Function Name

HAL_StatusTypeDef HAL_SPDIFRX_DeInit
(SPDIFRX_HandleTypeDef * hspdif)

Function Description

DeInitializes the SPDIFRX peripheral.

DocID025834 Rev 4

UM1725

HAL SPDIFRX Generic Driver
Parameters

hspdif: SPDIFRX handle

Return values

HAL: status

HAL_SPDIFRX_MspInit
Function Name

void HAL_SPDIFRX_MspInit (SPDIFRX_HandleTypeDef *
hspdif)

Function Description

SPDIFRX MSP Init.

Parameters

hspdif: SPDIFRX handle

Return values

None

HAL_SPDIFRX_MspDeInit
Function Name

void HAL_SPDIFRX_MspDeInit (SPDIFRX_HandleTypeDef *
hspdif)

Function Description

SPDIFRX MSP DeInit.

Parameters

hspdif: SPDIFRX handle

Return values

None

HAL_SPDIFRX_SetDataFormat
Function Name

HAL_StatusTypeDef HAL_SPDIFRX_SetDataFormat
(SPDIFRX_HandleTypeDef * hspdif,
SPDIFRX_SetDataFormatTypeDef sDataFormat)

Function Description

Sets the SPDIFRX dtat format according to the specified
parameters in the SPDIFRX_InitTypeDef.

Parameters

hspdif: SPDIFRX handle
sDataFormat: SPDIFRX data format

Return values

HAL: status

HAL_SPDIFRX_ReceiveDataFlow
Function Name

HAL_StatusTypeDef HAL_SPDIFRX_ReceiveDataFlow
(SPDIFRX_HandleTypeDef * hspdif, uint32_t * pData, uint16_t
Size, uint32_t Timeout)

Function Description

Receives an amount of data (Data Flow) in blocking mode.

Parameters

hspdif: pointer to SPDIFRX_HandleTypeDef structure that
contains the configuration information for SPDIFRX module.
pData: Pointer to data buffer
Size: Amount of data to be received
Timeout: Timeout duration

Return values

HAL: status

HAL_SPDIFRX_ReceiveControlFlow
Function Name

HAL_StatusTypeDef HAL_SPDIFRX_ReceiveControlFlow
(SPDIFRX_HandleTypeDef * hspdif, uint32_t * pData, uint16_t
DocID025834 Rev 4

811/964

HAL SPDIFRX Generic Driver

UM1725
Size, uint32_t Timeout)

Function Description

Receives an amount of data (Control Flow) in blocking mode.

Parameters

hspdif: pointer to a SPDIFRX_HandleTypeDef structure that
contains the configuration information for SPDIFRX module.
pData: Pointer to data buffer
Size: Amount of data to be received
Timeout: Timeout duration

Return values

HAL: status

HAL_SPDIFRX_ReceiveControlFlow_IT
Function Name

HAL_StatusTypeDef HAL_SPDIFRX_ReceiveControlFlow_IT
(SPDIFRX_HandleTypeDef * hspdif, uint32_t * pData, uint16_t
Size)

Function Description

Receive an amount of data (Control Flow) with Interrupt.

Parameters

hspdif: SPDIFRX handle
pData: a 32-bit pointer to the Receive data buffer.
Size: number of data sample (Control Flow) to be received :

Return values

HAL: status

HAL_SPDIFRX_ReceiveDataFlow_IT
Function Name

HAL_StatusTypeDef HAL_SPDIFRX_ReceiveDataFlow_IT
(SPDIFRX_HandleTypeDef * hspdif, uint32_t * pData, uint16_t
Size)

Function Description

Receive an amount of data (Data Flow) in non-blocking mode with
Interrupt.

Parameters

hspdif: SPDIFRX handle
pData: a 32-bit pointer to the Receive data buffer.
Size: number of data sample to be received .

Return values

HAL: status

HAL_SPDIFRX_IRQHandler
Function Name

void HAL_SPDIFRX_IRQHandler (SPDIFRX_HandleTypeDef *
hspdif)

Function Description

This function handles SPDIFRX interrupt request.

Parameters

hspdif: SPDIFRX handle

Return values

HAL: status

HAL_SPDIFRX_ReceiveControlFlow_DMA

812/964

Function Name

HAL_StatusTypeDef
HAL_SPDIFRX_ReceiveControlFlow_DMA
(SPDIFRX_HandleTypeDef * hspdif, uint32_t * pData, uint16_t
Size)

Function Description

Receive an amount of data (Control Flow) with DMA.
DocID025834 Rev 4

UM1725

HAL SPDIFRX Generic Driver
Parameters

hspdif: SPDIFRX handle
pData: a 32-bit pointer to the Receive data buffer.
Size: number of data (Control Flow) sample to be received :

Return values

HAL: status

HAL_SPDIFRX_ReceiveDataFlow_DMA
Function Name

HAL_StatusTypeDef HAL_SPDIFRX_ReceiveDataFlow_DMA
(SPDIFRX_HandleTypeDef * hspdif, uint32_t * pData, uint16_t
Size)

Function Description

Receive an amount of data (Data Flow) mode with DMA.

Parameters

hspdif: SPDIFRX handle
pData: a 32-bit pointer to the Receive data buffer.
Size: number of data sample to be received :

Return values

HAL: status

HAL_SPDIFRX_DMAStop
Function Name

HAL_StatusTypeDef HAL_SPDIFRX_DMAStop
(SPDIFRX_HandleTypeDef * hspdif)

Function Description

stop the audio stream receive from the Media.

Parameters

hspdif: SPDIFRX handle

Return values

None

HAL_SPDIFRX_RxHalfCpltCallback
Function Name

void HAL_SPDIFRX_RxHalfCpltCallback
(SPDIFRX_HandleTypeDef * hspdif)

Function Description

Rx Transfer (Data flow) half completed callbacks.

Parameters

hspdif: SPDIFRX handle

Return values

None

HAL_SPDIFRX_RxCpltCallback
Function Name

void HAL_SPDIFRX_RxCpltCallback
(SPDIFRX_HandleTypeDef * hspdif)

Function Description

Rx Transfer (Data flow) completed callbacks.

Parameters

hspdif: SPDIFRX handle

Return values

None

HAL_SPDIFRX_ErrorCallback
Function Name

void HAL_SPDIFRX_ErrorCallback (SPDIFRX_HandleTypeDef
* hspdif)

Function Description

SPDIFRX error callbacks.

DocID025834 Rev 4

813/964

HAL SPDIFRX Generic Driver
Parameters

UM1725
hspdif: SPDIFRX handle

Return values

None

HAL_SPDIFRX_CxHalfCpltCallback
Function Name

void HAL_SPDIFRX_CxHalfCpltCallback
(SPDIFRX_HandleTypeDef * hspdif)

Function Description

Rx (Control flow) Transfer half completed callbacks.

Parameters

hspdif: SPDIFRX handle

Return values

None

HAL_SPDIFRX_CxCpltCallback
Function Name

void HAL_SPDIFRX_CxCpltCallback
(SPDIFRX_HandleTypeDef * hspdif)

Function Description

Rx Transfer (Control flow) completed callbacks.

Parameters

hspdif: SPDIFRX handle

Return values

None

HAL_SPDIFRX_GetState
Function Name

HAL_SPDIFRX_StateTypeDef HAL_SPDIFRX_GetState
(SPDIFRX_HandleTypeDef * hspdif)

Function Description

Return the SPDIFRX state.

Parameters

hspdif: : SPDIFRX handle

Return values

HAL: state

HAL_SPDIFRX_GetError
Function Name

uint32_t HAL_SPDIFRX_GetError (SPDIFRX_HandleTypeDef *
hspdif)

Function Description

Return the SPDIFRX error code.

Parameters

hspdif: : SPDIFRX handle

Return values

SPDIFRX: Error Code

59.3

SPDIFRX Firmware driver defines

59.3.1

SPDIFRX
SPDIFRX Channel Status Mask
SPDIFRX_CHANNELSTATUS_OFF
SPDIFRX_CHANNELSTATUS_ON
SPDIFRX Channel Selection
SPDIFRX_CHANNEL_A

814/964

DocID025834 Rev 4

UM1725

HAL SPDIFRX Generic Driver
SPDIFRX_CHANNEL_B
SPDIFRX Data Format
SPDIFRX_DATAFORMAT_LSB
SPDIFRX_DATAFORMAT_MSB
SPDIFRX_DATAFORMAT_32BITS
SPDIFRX Error Code
HAL_SPDIFRX_ERROR_NONE

No error

HAL_SPDIFRX_ERROR_TIMEOUT

Timeout error

HAL_SPDIFRX_ERROR_OVR

OVR error

HAL_SPDIFRX_ERROR_PE

Parity error

HAL_SPDIFRX_ERROR_DMA

DMA transfer error

HAL_SPDIFRX_ERROR_UNKNOWN

Unknown Error error

SPDIFRX Exported Macros
__HAL_SPDIFRX_RESET_HANDLE_STATE

Description:
Reset SPDIFRX handle state.
Parameters:
__HANDLE__: SPDIFRX handle.
Return value:
None

__HAL_SPDIFRX_IDLE

Description:
Disable the specified SPDIFRX
peripheral (IDLE State).
Parameters:
__HANDLE__: specifies the
SPDIFRX Handle.
Return value:
None

__HAL_SPDIFRX_SYNC

Description:
Enable the specified SPDIFRX
peripheral (SYNC State).
Parameters:
__HANDLE__: specifies the
SPDIFRX Handle.
Return value:
None

__HAL_SPDIFRX_RCV

Description:
Enable the specified SPDIFRX
peripheral (RCV State).
DocID025834 Rev 4

815/964

HAL SPDIFRX Generic Driver

UM1725
Parameters:
__HANDLE__: specifies the
SPDIFRX Handle.
Return value:
None

__HAL_SPDIFRX_ENABLE_IT

Description:
Enable or disable the specified
SPDIFRX interrupts.
Parameters:
__HANDLE__: specifies the
SPDIFRX Handle.
__INTERRUPT__: specifies the
interrupt source to enable or disable.
This parameter can be one of the
following values:
SPDIFRX_IT_RXNE
SPDIFRX_IT_CSRNE
SPDIFRX_IT_PERRIE
SPDIFRX_IT_OVRIE
SPDIFRX_IT_SBLKIE
SPDIFRX_IT_SYNCDIE
SPDIFRX_IT_IFEIE
Return value:
None

__HAL_SPDIFRX_DISABLE_IT
__HAL_SPDIFRX_GET_IT_SOURCE

Description:
Checks if the specified SPDIFRX
interrupt source is enabled or
disabled.
Parameters:
__HANDLE__: specifies the
SPDIFRX Handle.
__INTERRUPT__: specifies the
SPDIFRX interrupt source to check.
This parameter can be one of the
following values:
SPDIFRX_IT_RXNE
SPDIFRX_IT_CSRNE
SPDIFRX_IT_PERRIE
SPDIFRX_IT_OVRIE
SPDIFRX_IT_SBLKIE
SPDIFRX_IT_SYNCDIE
SPDIFRX_IT_IFEIE
Return value:
The: new state of __IT__ (TRUE or

816/964

DocID025834 Rev 4

UM1725

HAL SPDIFRX Generic Driver
FALSE).
__HAL_SPDIFRX_GET_FLAG

Description:
Checks whether the specified
SPDIFRX flag is set or not.
Parameters:
__HANDLE__: specifies the
SPDIFRX Handle.
__FLAG__: specifies the flag to
check. This parameter can be one of
the following values:
SPDIFRX_FLAG_RXNE
SPDIFRX_FLAG_CSRNE
SPDIFRX_FLAG_PERR
SPDIFRX_FLAG_OVR
SPDIFRX_FLAG_SBD
SPDIFRX_FLAG_SYNCD
SPDIFRX_FLAG_FERR
SPDIFRX_FLAG_SERR
SPDIFRX_FLAG_TERR
Return value:
The: new state of __FLAG__ (TRUE
or FALSE).

__HAL_SPDIFRX_CLEAR_IT

Description:
Clears the specified SPDIFRX SR
flag, in setting the proper IFCR
register bit.
Parameters:
__HANDLE__: specifies the USART
Handle.
__IT_CLEAR__: specifies the
interrupt clear register flag that needs
to be set to clear the corresponding
interrupt This parameter can be one
of the following values:
SPDIFRX_FLAG_PERR
SPDIFRX_FLAG_OVR
SPDIFRX_SR_SBD
SPDIFRX_SR_SYNCD
Return value:
None

SPDIFRX Flags Definition
SPDIFRX_FLAG_RXNE
SPDIFRX_FLAG_CSRNE
SPDIFRX_FLAG_PERR
SPDIFRX_FLAG_OVR
DocID025834 Rev 4

817/964

HAL SPDIFRX Generic Driver
SPDIFRX_FLAG_SBD

UM1725

SPDIFRX_FLAG_SYNCD
SPDIFRX_FLAG_FERR
SPDIFRX_FLAG_SERR
SPDIFRX_FLAG_TERR
SPDIFRX Input Selection
SPDIFRX_INPUT_IN0
SPDIFRX_INPUT_IN1
SPDIFRX_INPUT_IN2
SPDIFRX_INPUT_IN3
SPDIFRX Interrupts Definition
SPDIFRX_IT_RXNE
SPDIFRX_IT_CSRNE
SPDIFRX_IT_PERRIE
SPDIFRX_IT_OVRIE
SPDIFRX_IT_SBLKIE
SPDIFRX_IT_SYNCDIE
SPDIFRX_IT_IFEIE
SPDIFRX Maximum Retries
SPDIFRX_MAXRETRIES_NONE
SPDIFRX_MAXRETRIES_3
SPDIFRX_MAXRETRIES_15
SPDIFRX_MAXRETRIES_63
SPDIFRX Parity Error Mask
SPDIFRX_PARITYERRORMASK_OFF
SPDIFRX_PARITYERRORMASK_ON
SPDIFRX Preamble Type Mask
SPDIFRX_PREAMBLETYPEMASK_OFF
SPDIFRX_PREAMBLETYPEMASK_ON
SPDIFRX State
SPDIFRX_STATE_IDLE
SPDIFRX_STATE_SYNC
SPDIFRX_STATE_RCV
SPDIFRX Stereo Mode
SPDIFRX_STEREOMODE_DISABLE
SPDIFRX_STEREOMODE_ENABLE
SPDIFRX Validity Mask
818/964

DocID025834 Rev 4

UM1725

HAL SPDIFRX Generic Driver
SPDIFRX_VALIDITYMASK_OFF
SPDIFRX_VALIDITYMASK_ON
SPDIFRX Wait For Activity
SPDIFRX_WAITFORACTIVITY_OFF
SPDIFRX_WAITFORACTIVITY_ON

DocID025834 Rev 4

819/964

HAL SPI Generic Driver

UM1725

60

HAL SPI Generic Driver

60.1

SPI Firmware driver registers structures

60.1.1

SPI_InitTypeDef
Data Fields
uint32_t Mode
uint32_t Direction
uint32_t DataSize
uint32_t CLKPolarity
uint32_t CLKPhase
uint32_t NSS
uint32_t BaudRatePrescaler
uint32_t FirstBit
uint32_t TIMode
uint32_t CRCCalculation
uint32_t CRCPolynomial

Field Documentation
uint32_t SPI_InitTypeDef::Mode
Specifies the SPI operating mode. This parameter can be a value of SPI_Mode
uint32_t SPI_InitTypeDef::Direction
Specifies the SPI bidirectional mode state. This parameter can be a value of
SPI_Direction
uint32_t SPI_InitTypeDef::DataSize
Specifies the SPI data size. This parameter can be a value of SPI_Data_Size
uint32_t SPI_InitTypeDef::CLKPolarity
Specifies the serial clock steady state. This parameter can be a value of
SPI_Clock_Polarity
uint32_t SPI_InitTypeDef::CLKPhase
Specifies the clock active edge for the bit capture. This parameter can be a value of
SPI_Clock_Phase
uint32_t SPI_InitTypeDef::NSS
Specifies whether the NSS signal is managed by hardware (NSS pin) or by software
using the SSI bit. This parameter can be a value of SPI_Slave_Select_management
uint32_t SPI_InitTypeDef::BaudRatePrescaler
Specifies the Baud Rate prescaler value which will be used to configure the transmit
and receive SCK clock. This parameter can be a value of SPI_BaudRate_Prescaler
Note:The communication clock is derived from the master clock. The slave clock does
not need to be set.
uint32_t SPI_InitTypeDef::FirstBit
Specifies whether data transfers start from MSB or LSB bit. This parameter can be a
value of SPI_MSB_LSB_transmission
uint32_t SPI_InitTypeDef::TIMode
Specifies if the TI mode is enabled or not. This parameter can be a value of
SPI_TI_mode

820/964

DocID025834 Rev 4

UM1725

HAL SPI Generic Driver
uint32_t SPI_InitTypeDef::CRCCalculation
Specifies if the CRC calculation is enabled or not. This parameter can be a value of
SPI_CRC_Calculation
uint32_t SPI_InitTypeDef::CRCPolynomial
Specifies the polynomial used for the CRC calculation. This parameter must be a
number between Min_Data = 0 and Max_Data = 65535

60.1.2

__SPI_HandleTypeDef
Data Fields
SPI_TypeDef * Instance
SPI_InitTypeDef Init
uint8_t * pTxBuffPtr
uint16_t TxXferSize
__IO uint16_t TxXferCount
uint8_t * pRxBuffPtr
uint16_t RxXferSize
__IO uint16_t RxXferCount
void(* RxISR
void(* TxISR
DMA_HandleTypeDef * hdmatx
DMA_HandleTypeDef * hdmarx
HAL_LockTypeDef Lock
__IO HAL_SPI_StateTypeDef State
__IO uint32_t ErrorCode

Field Documentation
SPI_TypeDef* __SPI_HandleTypeDef::Instance
SPI_InitTypeDef __SPI_HandleTypeDef::Init
uint8_t* __SPI_HandleTypeDef::pTxBuffPtr
uint16_t __SPI_HandleTypeDef::TxXferSize
__IO uint16_t __SPI_HandleTypeDef::TxXferCount
uint8_t* __SPI_HandleTypeDef::pRxBuffPtr
uint16_t __SPI_HandleTypeDef::RxXferSize
__IO uint16_t __SPI_HandleTypeDef::RxXferCount
void(* __SPI_HandleTypeDef::RxISR)(struct __SPI_HandleTypeDef *hspi)
void(* __SPI_HandleTypeDef::TxISR)(struct __SPI_HandleTypeDef *hspi)
DMA_HandleTypeDef* __SPI_HandleTypeDef::hdmatx
DMA_HandleTypeDef* __SPI_HandleTypeDef::hdmarx
HAL_LockTypeDef __SPI_HandleTypeDef::Lock
__IO HAL_SPI_StateTypeDef __SPI_HandleTypeDef::State
__IO uint32_t __SPI_HandleTypeDef::ErrorCode

DocID025834 Rev 4

821/964

HAL SPI Generic Driver

UM1725

60.2

SPI Firmware driver API description

60.2.1

How to use this driver
The SPI HAL driver can be used as follows:
1.
2.

3.

4.

Declare a SPI_HandleTypeDef handle structure, for example: SPI_HandleTypeDef
hspi;
Initialize the SPI low level resources by implementing the HAL_SPI_MspInit() API:
a.
Enable the SPIx interface clock
b.
SPI pins configuration
Enable the clock for the SPI GPIOs
Configure these SPI pins as alternate function push-pull
c.
NVIC configuration if you need to use interrupt process
Configure the SPIx interrupt priority
Enable the NVIC SPI IRQ handle
d.
DMA Configuration if you need to use DMA process
Declare a DMA_HandleTypeDef handle structure for the transmit or receive
stream
Enable the DMAx clock
Configure the DMA handle parameters
Configure the DMA Tx or Rx stream
Associate the initialized hdma_tx handle to the hspi DMA Tx or Rx handle
Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Tx or Rx stream
Program the Mode, BidirectionalMode , Data size, Baudrate Prescaler, NSS
management, Clock polarity and phase, FirstBit and CRC configuration in the hspi Init
structure.
Initialize the SPI registers by calling the HAL_SPI_Init() API:
This API configures also the low level Hardware GPIO, CLOCK, CORTEX...etc)
by calling the customized HAL_SPI_MspInit() API.

Circular mode restriction:
1.

2.
3.

The DMA circular mode cannot be used when the SPI is configured in these modes:
a.
Master 2Lines RxOnly
b.
Master 1Line Rx
The CRC feature is not managed when the DMA circular mode is enabled
When the SPI DMA Pause/Stop features are used, we must use the following APIs
the HAL_SPI_DMAPause()/ HAL_SPI_DMAStop() only under the SPI callbacks

Master Receive mode restriction:
1.

In Master unidirectional receive-only mode (MSTR =1, BIDIMODE=0, RXONLY=0) or
bidirectional receive mode (MSTR=1, BIDIMODE=1, BIDIOE=0), to ensure that the
SPI does not initiate a new transfer the following procedure has to be respected:
a.
HAL_SPI_DeInit()
b.
HAL_SPI_Init()
The max SPI frequency depend on SPI data size (8bits, 16bits), SPI mode(2
Lines fullduplex, 2 lines RxOnly, 1 line TX/RX) and Process mode (Polling, IT,
DMA).

822/964

DocID025834 Rev 4

UM1725

HAL SPI Generic Driver
TX/RX processes are HAL_SPI_TransmitReceive(),
HAL_SPI_TransmitReceive_IT() and HAL_SPI_TransmitReceive_DMA()
RX processes are HAL_SPI_Receive(), HAL_SPI_Receive_IT() and
HAL_SPI_Receive_DMA()
TX processes are HAL_SPI_Transmit(), HAL_SPI_Transmit_IT() and
HAL_SPI_Transmit_DMA()

60.2.2

Initialization and de-initialization functions
This subsection provides a set of functions allowing to initialize and de-initialize the SPIx
peripheral:
User must implement HAL_SPI_MspInit() function in which he configures all related
peripherals resources (CLOCK, GPIO, DMA, IT and NVIC ).
Call the function HAL_SPI_Init() to configure the selected device with the selected
configuration:
Mode
Direction
Data Size
Clock Polarity and Phase
NSS Management
BaudRate Prescaler
FirstBit
TIMode
CRC Calculation
CRC Polynomial if CRC enabled
Call the function HAL_SPI_DeInit() to restore the default configuration of the selected
SPIx peripheral.
This section contains the following APIs:
HAL_SPI_Init()
HAL_SPI_DeInit()
HAL_SPI_MspInit()
HAL_SPI_MspDeInit()

60.2.3

IO operation functions
This subsection provides a set of functions allowing to manage the SPI data transfers.
The SPI supports master and slave mode :
1.

2.

There are two modes of transfer:
Blocking mode: The communication is performed in polling mode. The HAL
status of all data processing is returned by the same function after finishing
transfer.
No-Blocking mode: The communication is performed using Interrupts or DMA,
These APIs return the HAL status. The end of the data processing will be
indicated through the dedicated SPI IRQ when using Interrupt mode or the DMA
IRQ when using DMA mode. The HAL_SPI_TxCpltCallback(),
HAL_SPI_RxCpltCallback() and HAL_SPI_TxRxCpltCallback() user callbacks will
be executed respectively at the end of the transmit or Receive process The
HAL_SPI_ErrorCallback()user callback will be executed when a communication
error is detected
APIs provided for these 2 transfer modes (Blocking mode or Non blocking mode
using either Interrupt or DMA) exist for 1Line (simplex) and 2Lines (full duplex) modes.
DocID025834 Rev 4

823/964

HAL SPI Generic Driver
This section contains the following APIs:

UM1725

HAL_SPI_Transmit()
HAL_SPI_Receive()
HAL_SPI_TransmitReceive()
HAL_SPI_Transmit_IT()
HAL_SPI_Receive_IT()
HAL_SPI_TransmitReceive_IT()
HAL_SPI_Transmit_DMA()
HAL_SPI_Receive_DMA()
HAL_SPI_TransmitReceive_DMA()
HAL_SPI_DMAPause()
HAL_SPI_DMAResume()
HAL_SPI_DMAStop()
HAL_SPI_IRQHandler()
HAL_SPI_TxCpltCallback()
HAL_SPI_RxCpltCallback()
HAL_SPI_TxRxCpltCallback()
HAL_SPI_TxHalfCpltCallback()
HAL_SPI_RxHalfCpltCallback()
HAL_SPI_TxRxHalfCpltCallback()
HAL_SPI_ErrorCallback()

60.2.4

Peripheral State and Errors functions
This subsection provides a set of functions allowing to control the SPI.
HAL_SPI_GetState() API can be helpful to check in run-time the state of the SPI
peripheral
HAL_SPI_GetError() check in run-time Errors occurring during communication
This section contains the following APIs:
HAL_SPI_GetState()
HAL_SPI_GetError()

60.2.5

Detailed description of functions
HAL_SPI_Init
Function Name

HAL_StatusTypeDef HAL_SPI_Init (SPI_HandleTypeDef * hspi)

Function Description

Initialize the SPI according to the specified parameters in the
SPI_InitTypeDef and initialize the associated handle.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

HAL: status

HAL_SPI_DeInit
Function Name

HAL_StatusTypeDef HAL_SPI_DeInit (SPI_HandleTypeDef *
hspi)

Function Description

De Initialize the SPI peripheral.

Parameters

824/964

hspi: pointer to a SPI_HandleTypeDef structure that contains

DocID025834 Rev 4

UM1725

HAL SPI Generic Driver
the configuration information for SPI module.
Return values

HAL: status

HAL_SPI_MspInit
Function Name

void HAL_SPI_MspInit (SPI_HandleTypeDef * hspi)

Function Description

Initialize the SPI MSP.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

None

HAL_SPI_MspDeInit
Function Name

void HAL_SPI_MspDeInit (SPI_HandleTypeDef * hspi)

Function Description

De-Initialize the SPI MSP.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

None

HAL_SPI_Transmit
Function Name

HAL_StatusTypeDef HAL_SPI_Transmit (SPI_HandleTypeDef *
hspi, uint8_t * pData, uint16_t Size, uint32_t Timeout)

Function Description

Transmit an amount of data in blocking mode.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.
pData: pointer to data buffer
Size: amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_SPI_Receive
Function Name

HAL_StatusTypeDef HAL_SPI_Receive (SPI_HandleTypeDef *
hspi, uint8_t * pData, uint16_t Size, uint32_t Timeout)

Function Description

Receive an amount of data in blocking mode.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.
pData: pointer to data buffer
Size: amount of data to be received
Timeout: Timeout duration

Return values

HAL: status

DocID025834 Rev 4

825/964

HAL SPI Generic Driver

UM1725

HAL_SPI_TransmitReceive
Function Name

HAL_StatusTypeDef HAL_SPI_TransmitReceive
(SPI_HandleTypeDef * hspi, uint8_t * pTxData, uint8_t *
pRxData, uint16_t Size, uint32_t Timeout)

Function Description

Transmit and Receive an amount of data in blocking mode.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.
pTxData: pointer to transmission data buffer
pRxData: pointer to reception data buffer
Size: amount of data to be sent and received
Timeout: Timeout duration

Return values

HAL: status

HAL_SPI_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_SPI_Transmit_IT
(SPI_HandleTypeDef * hspi, uint8_t * pData, uint16_t Size)

Function Description

Transmit an amount of data in non-blocking mode with Interrupt.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.
pData: pointer to data buffer
Size: amount of data to be sent

Return values

HAL: status

HAL_SPI_Receive_IT
Function Name

HAL_StatusTypeDef HAL_SPI_Receive_IT
(SPI_HandleTypeDef * hspi, uint8_t * pData, uint16_t Size)

Function Description

Receive an amount of data in non-blocking mode with Interrupt.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.
pData: pointer to data buffer
Size: amount of data to be sent

Return values

HAL: status

HAL_SPI_TransmitReceive_IT
Function Name

HAL_StatusTypeDef HAL_SPI_TransmitReceive_IT
(SPI_HandleTypeDef * hspi, uint8_t * pTxData, uint8_t *
pRxData, uint16_t Size)

Function Description

Transmit and Receive an amount of data in non-blocking mode
with Interrupt.

Parameters

826/964

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.
pTxData: pointer to transmission data buffer
pRxData: pointer to reception data buffer
Size: amount of data to be sent and received
DocID025834 Rev 4

UM1725

HAL SPI Generic Driver
Return values

HAL: status

HAL_SPI_Transmit_DMA
Function Name

HAL_StatusTypeDef HAL_SPI_Transmit_DMA
(SPI_HandleTypeDef * hspi, uint8_t * pData, uint16_t Size)

Function Description

Transmit an amount of data in non-blocking mode with DMA.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.
pData: pointer to data buffer
Size: amount of data to be sent

Return values

HAL: status

HAL_SPI_Receive_DMA
Function Name

HAL_StatusTypeDef HAL_SPI_Receive_DMA
(SPI_HandleTypeDef * hspi, uint8_t * pData, uint16_t Size)

Function Description

Receive an amount of data in non-blocking mode with DMA.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.
pData: pointer to data buffer
Size: amount of data to be sent

Return values

HAL: status

Notes

When the CRC feature is enabled the pData Length must be
Size + 1.

HAL_SPI_TransmitReceive_DMA
Function Name

HAL_StatusTypeDef HAL_SPI_TransmitReceive_DMA
(SPI_HandleTypeDef * hspi, uint8_t * pTxData, uint8_t *
pRxData, uint16_t Size)

Function Description

Transmit and Receive an amount of data in non-blocking mode
with DMA.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.
pTxData: pointer to transmission data buffer
pRxData: pointer to reception data buffer
Size: amount of data to be sent

Return values

HAL: status

Notes

When the CRC feature is enabled the pRxData Length must
be Size + 1

HAL_SPI_DMAPause
Function Name

HAL_StatusTypeDef HAL_SPI_DMAPause
(SPI_HandleTypeDef * hspi)

Function Description

Pause the DMA Transfer.
DocID025834 Rev 4

827/964

HAL SPI Generic Driver
Parameters

UM1725
hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for the specified SPI module.

Return values

HAL: status

HAL_SPI_DMAResume
Function Name

HAL_StatusTypeDef HAL_SPI_DMAResume
(SPI_HandleTypeDef * hspi)

Function Description

Resume the DMA Transfer.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for the specified SPI module.

Return values

HAL: status

HAL_SPI_DMAStop
Function Name

HAL_StatusTypeDef HAL_SPI_DMAStop (SPI_HandleTypeDef
* hspi)

Function Description

Stop the DMA Transfer.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for the specified SPI module.

Return values

HAL: status

HAL_SPI_IRQHandler
Function Name

void HAL_SPI_IRQHandler (SPI_HandleTypeDef * hspi)

Function Description

Handle SPI interrupt request.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for the specified SPI module.

Return values

None

HAL_SPI_TxCpltCallback
Function Name

void HAL_SPI_TxCpltCallback (SPI_HandleTypeDef * hspi)

Function Description

Tx Transfer completed callback.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

None

HAL_SPI_RxCpltCallback

828/964

Function Name

void HAL_SPI_RxCpltCallback (SPI_HandleTypeDef * hspi)

Function Description

Rx Transfer completed callback.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

None
DocID025834 Rev 4

UM1725

HAL SPI Generic Driver

HAL_SPI_TxRxCpltCallback
Function Name

void HAL_SPI_TxRxCpltCallback (SPI_HandleTypeDef * hspi)

Function Description

Tx and Rx Transfer completed callback.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

None

HAL_SPI_TxHalfCpltCallback
Function Name

void HAL_SPI_TxHalfCpltCallback (SPI_HandleTypeDef * hspi)

Function Description

Tx Half Transfer completed callback.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

None

HAL_SPI_RxHalfCpltCallback
Function Name

void HAL_SPI_RxHalfCpltCallback (SPI_HandleTypeDef *
hspi)

Function Description

Rx Half Transfer completed callback.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

None

HAL_SPI_TxRxHalfCpltCallback
Function Name

void HAL_SPI_TxRxHalfCpltCallback (SPI_HandleTypeDef *
hspi)

Function Description

Tx and Rx Half Transfer callback.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

None

HAL_SPI_ErrorCallback
Function Name

void HAL_SPI_ErrorCallback (SPI_HandleTypeDef * hspi)

Function Description

SPI error callback.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

None

HAL_SPI_GetState
Function Name

HAL_SPI_StateTypeDef HAL_SPI_GetState
(SPI_HandleTypeDef * hspi)
DocID025834 Rev 4

829/964

HAL SPI Generic Driver
Function Description

UM1725
Return the SPI handle state.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

SPI: state

HAL_SPI_GetError
Function Name

uint32_t HAL_SPI_GetError (SPI_HandleTypeDef * hspi)

Function Description

Return the SPI error code.

Parameters

hspi: pointer to a SPI_HandleTypeDef structure that contains
the configuration information for SPI module.

Return values

SPI: error code in bitmap format

60.3

SPI Firmware driver defines

60.3.1

SPI
SPI BaudRate Prescaler
SPI_BAUDRATEPRESCALER_2
SPI_BAUDRATEPRESCALER_4
SPI_BAUDRATEPRESCALER_8
SPI_BAUDRATEPRESCALER_16
SPI_BAUDRATEPRESCALER_32
SPI_BAUDRATEPRESCALER_64
SPI_BAUDRATEPRESCALER_128
SPI_BAUDRATEPRESCALER_256
SPI Clock Phase
SPI_PHASE_1EDGE
SPI_PHASE_2EDGE
SPI Clock Polarity
SPI_POLARITY_LOW
SPI_POLARITY_HIGH
SPI CRC Calculation
SPI_CRCCALCULATION_DISABLE
SPI_CRCCALCULATION_ENABLE
SPI Data Size
SPI_DATASIZE_8BIT
SPI_DATASIZE_16BIT
SPI Direction Mode
SPI_DIRECTION_2LINES

830/964

DocID025834 Rev 4

UM1725

HAL SPI Generic Driver
SPI_DIRECTION_2LINES_RXONLY
SPI_DIRECTION_1LINE
SPI Error Code
HAL_SPI_ERROR_NONE

No error

HAL_SPI_ERROR_MODF

MODF error

HAL_SPI_ERROR_CRC

CRC error

HAL_SPI_ERROR_OVR

OVR error

HAL_SPI_ERROR_FRE

FRE error

HAL_SPI_ERROR_DMA

DMA transfer error

HAL_SPI_ERROR_FLAG

Flag: RXNE,TXE, BSY

SPI Exported Macros
__HAL_SPI_RESET_HANDLE_STATE

Description:
Reset SPI handle state.
Parameters:
__HANDLE__: specifies the SPI Handle.
This parameter can be SPI where x: 1, 2, or
3 to select the SPI peripheral.
Return value:
None
Description:

__HAL_SPI_ENABLE_IT

Enable or disable the specified SPI
interrupts.
Parameters:
__HANDLE__: specifies the SPI Handle.
This parameter can be SPI where x: 1, 2, or
3 to select the SPI peripheral.
__INTERRUPT__: specifies the interrupt
source to enable or disable. This parameter
can be one of the following values:
SPI_IT_TXE: Tx buffer empty interrupt
enable
SPI_IT_RXNE: RX buffer not empty
interrupt enable
SPI_IT_ERR: Error interrupt enable
Return value:
None
__HAL_SPI_DISABLE_IT
__HAL_SPI_GET_IT_SOURCE

Description:
Check whether the specified SPI interrupt
source is enabled or not.
Parameters:

DocID025834 Rev 4

831/964

HAL SPI Generic Driver

UM1725
__HANDLE__: specifies the SPI Handle.
This parameter can be SPI where x: 1, 2, or
3 to select the SPI peripheral.
__INTERRUPT__: specifies the SPI
interrupt source to check. This parameter
can be one of the following values:
SPI_IT_TXE: Tx buffer empty interrupt
enable
SPI_IT_RXNE: RX buffer not empty
interrupt enable
SPI_IT_ERR: Error interrupt enable
Return value:
The: new state of __IT__ (TRUE or FALSE).
Description:

__HAL_SPI_GET_FLAG

Check whether the specified SPI flag is set
or not.
Parameters:
__HANDLE__: specifies the SPI Handle.
This parameter can be SPI where x: 1, 2, or
3 to select the SPI peripheral.
__FLAG__: specifies the flag to check. This
parameter can be one of the following
values:
SPI_FLAG_RXNE: Receive buffer not
empty flag
SPI_FLAG_TXE: Transmit buffer
empty flag
SPI_FLAG_CRCERR: CRC error flag
SPI_FLAG_MODF: Mode fault flag
SPI_FLAG_OVR: Overrun flag
SPI_FLAG_BSY: Busy flag
SPI_FLAG_FRE: Frame format error
flag
Return value:
The: new state of __FLAG__ (TRUE or
FALSE).
__HAL_SPI_CLEAR_CRCERRFLAG

Description:
Clear the SPI CRCERR pending flag.
Parameters:
__HANDLE__: specifies the SPI Handle.
This parameter can be SPI where x: 1, 2, or
3 to select the SPI peripheral.
Return value:
None

832/964

DocID025834 Rev 4

UM1725

HAL SPI Generic Driver
__HAL_SPI_CLEAR_MODFFLAG

Description:
Clear the SPI MODF pending flag.
Parameters:
__HANDLE__: specifies the SPI Handle.
This parameter can be SPI where x: 1, 2, or
3 to select the SPI peripheral.
Return value:
None

__HAL_SPI_CLEAR_OVRFLAG

Description:
Clear the SPI OVR pending flag.
Parameters:
__HANDLE__: specifies the SPI Handle.
This parameter can be SPI where x: 1, 2, or
3 to select the SPI peripheral.
Return value:
None

__HAL_SPI_CLEAR_FREFLAG

Description:
Clear the SPI FRE pending flag.
Parameters:
__HANDLE__: specifies the SPI Handle.
This parameter can be SPI where x: 1, 2, or
3 to select the SPI peripheral.
Return value:
None

__HAL_SPI_ENABLE

Description:
Enable the SPI peripheral.
Parameters:
__HANDLE__: specifies the SPI Handle.
This parameter can be SPI where x: 1, 2, or
3 to select the SPI peripheral.
Return value:
None

__HAL_SPI_DISABLE

Description:
Disable the SPI peripheral.
Parameters:
__HANDLE__: specifies the SPI Handle.
This parameter can be SPI where x: 1, 2, or
3 to select the SPI peripheral.

DocID025834 Rev 4

833/964

HAL SPI Generic Driver

UM1725
Return value:
None

SPI Flags Definition
SPI_FLAG_RXNE
SPI_FLAG_TXE
SPI_FLAG_BSY
SPI_FLAG_CRCERR
SPI_FLAG_MODF
SPI_FLAG_OVR
SPI_FLAG_FRE
SPI Interrupt Definition
SPI_IT_TXE
SPI_IT_RXNE
SPI_IT_ERR
SPI Mode
SPI_MODE_SLAVE
SPI_MODE_MASTER
SPI MSB LSB Transmission
SPI_FIRSTBIT_MSB
SPI_FIRSTBIT_LSB
SPI Slave Select Management
SPI_NSS_SOFT
SPI_NSS_HARD_INPUT
SPI_NSS_HARD_OUTPUT
SPI TI Mode
SPI_TIMODE_DISABLE
SPI_TIMODE_ENABLE

834/964

DocID025834 Rev 4

UM1725

HAL SRAM Generic Driver

61

HAL SRAM Generic Driver

61.1

SRAM Firmware driver registers structures

61.1.1

SRAM_HandleTypeDef
Data Fields
FMC_NORSRAM_TypeDef * Instance
FMC_NORSRAM_EXTENDED_TypeDef * Extended
FMC_NORSRAM_InitTypeDef Init
HAL_LockTypeDef Lock
__IO HAL_SRAM_StateTypeDef State
DMA_HandleTypeDef * hdma

Field Documentation
FMC_NORSRAM_TypeDef* SRAM_HandleTypeDef::Instance
Register base address
FMC_NORSRAM_EXTENDED_TypeDef* SRAM_HandleTypeDef::Extended
Extended mode register base address
FMC_NORSRAM_InitTypeDef SRAM_HandleTypeDef::Init
SRAM device control configuration parameters
HAL_LockTypeDef SRAM_HandleTypeDef::Lock
SRAM locking object
__IO HAL_SRAM_StateTypeDef SRAM_HandleTypeDef::State
SRAM device access state
DMA_HandleTypeDef* SRAM_HandleTypeDef::hdma
Pointer DMA handler

61.2

SRAM Firmware driver API description

61.2.1

How to use this driver
This driver is a generic layered driver which contains a set of APIs used to control SRAM
memories. It uses the FMC layer functions to interface with SRAM devices. The following
sequence should be followed to configure the FMC/FSMC to interface with SRAM/PSRAM
memories:
1.

2.

Declare a SRAM_HandleTypeDef handle structure, for example:
SRAM_HandleTypeDef hsram; and:
Fill the SRAM_HandleTypeDef handle "Init" field with the allowed values of the
structure member.
Fill the SRAM_HandleTypeDef handle "Instance" field with a predefined base
register instance for NOR or SRAM device
Fill the SRAM_HandleTypeDef handle "Extended" field with a predefined base
register instance for NOR or SRAM extended mode
Declare two FMC_NORSRAM_TimingTypeDef structures, for both normal and
extended mode timings; for example: FMC_NORSRAM_TimingTypeDef Timing and
DocID025834 Rev 4

835/964

HAL SRAM Generic Driver
UM1725
FMC_NORSRAM_TimingTypeDef ExTiming; and fill its fields with the allowed values
of the structure member.
3.
Initialize the SRAM Controller by calling the function HAL_SRAM_Init(). This function
performs the following sequence:
a.
MSP hardware layer configuration using the function HAL_SRAM_MspInit()
b.
Control register configuration using the FMC NORSRAM interface function
FMC_NORSRAM_Init()
c.
Timing register configuration using the FMC NORSRAM interface function
FMC_NORSRAM_Timing_Init()
d.
Extended mode Timing register configuration using the FMC NORSRAM
interface function FMC_NORSRAM_Extended_Timing_Init()
e.
Enable the SRAM device using the macro __FMC_NORSRAM_ENABLE()
4.
At this stage you can perform read/write accesses from/to the memory connected to
the NOR/SRAM Bank. You can perform either polling or DMA transfer using the
following APIs:
HAL_SRAM_Read()/HAL_SRAM_Write() for polling read/write access
HAL_SRAM_Read_DMA()/HAL_SRAM_Write_DMA() for DMA read/write
transfer
5.
You can also control the SRAM device by calling the control APIs
HAL_SRAM_WriteOperation_Enable()/ HAL_SRAM_WriteOperation_Disable() to
respectively enable/disable the SRAM write operation
6.
You can continuously monitor the SRAM device HAL state by calling the function
HAL_SRAM_GetState()

61.2.2

SRAM Initialization and de_initialization functions
This section provides functions allowing to initialize/de-initialize the SRAM memory
This section contains the following APIs:
HAL_SRAM_Init()
HAL_SRAM_DeInit()
HAL_SRAM_MspInit()
HAL_SRAM_MspDeInit()
HAL_SRAM_DMA_XferCpltCallback()
HAL_SRAM_DMA_XferErrorCallback()

61.2.3

SRAM Input and Output functions
This section provides functions allowing to use and control the SRAM memory
This section contains the following APIs:
HAL_SRAM_Read_8b()
HAL_SRAM_Write_8b()
HAL_SRAM_Read_16b()
HAL_SRAM_Write_16b()
HAL_SRAM_Read_32b()
HAL_SRAM_Write_32b()
HAL_SRAM_Read_DMA()
HAL_SRAM_Write_DMA()

61.2.4

SRAM Control functions
This subsection provides a set of functions allowing to control dynamically the SRAM
interface.
This section contains the following APIs:

836/964

DocID025834 Rev 4

UM1725

HAL SRAM Generic Driver
HAL_SRAM_WriteOperation_Enable()
HAL_SRAM_WriteOperation_Disable()

61.2.5

SRAM State functions
This subsection permits to get in run-time the status of the SRAM controller and the data
flow.
This section contains the following APIs:
HAL_SRAM_GetState()

61.2.6

Detailed description of functions
HAL_SRAM_Init
Function Name

HAL_StatusTypeDef HAL_SRAM_Init (SRAM_HandleTypeDef *
hsram, FMC_NORSRAM_TimingTypeDef * Timing,
FMC_NORSRAM_TimingTypeDef * ExtTiming)

Function Description

Performs the SRAM device initialization sequence.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.
Timing: Pointer to SRAM control timing structure
ExtTiming: Pointer to SRAM extended mode timing structure

Return values

HAL: status

HAL_SRAM_DeInit
Function Name

HAL_StatusTypeDef HAL_SRAM_DeInit
(SRAM_HandleTypeDef * hsram)

Function Description

Performs the SRAM device De-initialization sequence.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.

Return values

HAL: status

HAL_SRAM_MspInit
Function Name

void HAL_SRAM_MspInit (SRAM_HandleTypeDef * hsram)

Function Description

SRAM MSP Init.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.

Return values

None

HAL_SRAM_MspDeInit
Function Name

void HAL_SRAM_MspDeInit (SRAM_HandleTypeDef * hsram)

Function Description

SRAM MSP DeInit.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.

DocID025834 Rev 4

837/964

HAL SRAM Generic Driver
Return values

UM1725
None

HAL_SRAM_DMA_XferCpltCallback
Function Name

void HAL_SRAM_DMA_XferCpltCallback
(DMA_HandleTypeDef * hdma)

Function Description

DMA transfer complete callback.

Parameters

hdma: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.

Return values

None

HAL_SRAM_DMA_XferErrorCallback
Function Name

void HAL_SRAM_DMA_XferErrorCallback
(DMA_HandleTypeDef * hdma)

Function Description

DMA transfer complete error callback.

Parameters

hdma: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.

Return values

None

HAL_SRAM_Read_8b
Function Name

HAL_StatusTypeDef HAL_SRAM_Read_8b
(SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint8_t *
pDstBuffer, uint32_t BufferSize)

Function Description

Reads 8-bit buffer from SRAM memory.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.
pAddress: Pointer to read start address
pDstBuffer: Pointer to destination buffer
BufferSize: Size of the buffer to read from memory

Return values

HAL: status

HAL_SRAM_Write_8b

838/964

Function Name

HAL_StatusTypeDef HAL_SRAM_Write_8b
(SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint8_t *
pSrcBuffer, uint32_t BufferSize)

Function Description

Writes 8-bit buffer to SRAM memory.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.
pAddress: Pointer to write start address
pSrcBuffer: Pointer to source buffer to write
BufferSize: Size of the buffer to write to memory

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL SRAM Generic Driver

HAL_SRAM_Read_16b
Function Name

HAL_StatusTypeDef HAL_SRAM_Read_16b
(SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint16_t
* pDstBuffer, uint32_t BufferSize)

Function Description

Reads 16-bit buffer from SRAM memory.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.
pAddress: Pointer to read start address
pDstBuffer: Pointer to destination buffer
BufferSize: Size of the buffer to read from memory

Return values

HAL: status

HAL_SRAM_Write_16b
Function Name

HAL_StatusTypeDef HAL_SRAM_Write_16b
(SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint16_t
* pSrcBuffer, uint32_t BufferSize)

Function Description

Writes 16-bit buffer to SRAM memory.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.
pAddress: Pointer to write start address
pSrcBuffer: Pointer to source buffer to write
BufferSize: Size of the buffer to write to memory

Return values

HAL: status

HAL_SRAM_Read_32b
Function Name

HAL_StatusTypeDef HAL_SRAM_Read_32b
(SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint32_t
* pDstBuffer, uint32_t BufferSize)

Function Description

Reads 32-bit buffer from SRAM memory.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.
pAddress: Pointer to read start address
pDstBuffer: Pointer to destination buffer
BufferSize: Size of the buffer to read from memory

Return values

HAL: status

HAL_SRAM_Write_32b
Function Name

HAL_StatusTypeDef HAL_SRAM_Write_32b
(SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint32_t
* pSrcBuffer, uint32_t BufferSize)

Function Description

Writes 32-bit buffer to SRAM memory.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.
pAddress: Pointer to write start address
pSrcBuffer: Pointer to source buffer to write
DocID025834 Rev 4

839/964

HAL SRAM Generic Driver

UM1725
BufferSize: Size of the buffer to write to memory

Return values

HAL: status

HAL_SRAM_Read_DMA
Function Name

HAL_StatusTypeDef HAL_SRAM_Read_DMA
(SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint32_t
* pDstBuffer, uint32_t BufferSize)

Function Description

Reads a Words data from the SRAM memory using DMA transfer.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.
pAddress: Pointer to read start address
pDstBuffer: Pointer to destination buffer
BufferSize: Size of the buffer to read from memory

Return values

HAL: status

HAL_SRAM_Write_DMA
Function Name

HAL_StatusTypeDef HAL_SRAM_Write_DMA
(SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint32_t
* pSrcBuffer, uint32_t BufferSize)

Function Description

Writes a Words data buffer to SRAM memory using DMA transfer.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.
pAddress: Pointer to write start address
pSrcBuffer: Pointer to source buffer to write
BufferSize: Size of the buffer to write to memory

Return values

HAL: status

HAL_SRAM_WriteOperation_Enable
Function Name

HAL_StatusTypeDef HAL_SRAM_WriteOperation_Enable
(SRAM_HandleTypeDef * hsram)

Function Description

Enables dynamically SRAM write operation.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.

Return values

HAL: status

HAL_SRAM_WriteOperation_Disable

840/964

Function Name

HAL_StatusTypeDef HAL_SRAM_WriteOperation_Disable
(SRAM_HandleTypeDef * hsram)

Function Description

Disables dynamically SRAM write operation.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL SRAM Generic Driver

HAL_SRAM_GetState
Function Name

HAL_SRAM_StateTypeDef HAL_SRAM_GetState
(SRAM_HandleTypeDef * hsram)

Function Description

Returns the SRAM controller state.

Parameters

hsram: pointer to a SRAM_HandleTypeDef structure that
contains the configuration information for SRAM module.

Return values

HAL: state

61.3

SRAM Firmware driver defines

61.3.1

SRAM
SRAM Exported Macros
__HAL_SRAM_RESET_HANDLE_STATE

Description:
Reset SRAM handle state.
Parameters:
__HANDLE__: SRAM handle
Return value:
None

DocID025834 Rev 4

841/964

HAL TIM Generic Driver

UM1725

62

HAL TIM Generic Driver

62.1

TIM Firmware driver registers structures

62.1.1

TIM_Base_InitTypeDef
Data Fields
uint32_t Prescaler
uint32_t CounterMode
uint32_t Period
uint32_t ClockDivision
uint32_t RepetitionCounter

Field Documentation
uint32_t TIM_Base_InitTypeDef::Prescaler
Specifies the prescaler value used to divide the TIM clock. This parameter can be a
number between Min_Data = 0x0000U and Max_Data = 0xFFFFU
uint32_t TIM_Base_InitTypeDef::CounterMode
Specifies the counter mode. This parameter can be a value of TIM_Counter_Mode
uint32_t TIM_Base_InitTypeDef::Period
Specifies the period value to be loaded into the active Auto-Reload Register at the
next update event. This parameter can be a number between Min_Data = 0x0000U
and Max_Data = 0xFFFF.
uint32_t TIM_Base_InitTypeDef::ClockDivision
Specifies the clock division. This parameter can be a value of TIM_ClockDivision
uint32_t TIM_Base_InitTypeDef::RepetitionCounter
Specifies the repetition counter value. Each time the RCR downcounter reaches zero,
an update event is generated and counting restarts from the RCR value (N). This
means in PWM mode that (N+1) corresponds to:the number of PWM periods in edgealigned modethe number of half PWM period in center-aligned mode This parameter
must be a number between Min_Data = 0x00 and Max_Data = 0xFF.
Note:This parameter is valid only for TIM1 and TIM8.

62.1.2

TIM_OC_InitTypeDef
Data Fields
uint32_t OCMode
uint32_t Pulse
uint32_t OCPolarity
uint32_t OCNPolarity
uint32_t OCFastMode
uint32_t OCIdleState
uint32_t OCNIdleState

842/964

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
Field Documentation
uint32_t TIM_OC_InitTypeDef::OCMode
Specifies the TIM mode. This parameter can be a value of
TIM_Output_Compare_and_PWM_modes
uint32_t TIM_OC_InitTypeDef::Pulse
Specifies the pulse value to be loaded into the Capture Compare Register. This
parameter can be a number between Min_Data = 0x0000U and Max_Data = 0xFFFFU
uint32_t TIM_OC_InitTypeDef::OCPolarity
Specifies the output polarity. This parameter can be a value of
TIM_Output_Compare_Polarity
uint32_t TIM_OC_InitTypeDef::OCNPolarity
Specifies the complementary output polarity. This parameter can be a value of
TIM_Output_Compare_N_Polarity
Note:This parameter is valid only for TIM1 and TIM8.
uint32_t TIM_OC_InitTypeDef::OCFastMode
Specifies the Fast mode state. This parameter can be a value of
TIM_Output_Fast_State
Note:This parameter is valid only in PWM1 and PWM2 mode.
uint32_t TIM_OC_InitTypeDef::OCIdleState
Specifies the TIM Output Compare pin state during Idle state. This parameter can be
a value of TIM_Output_Compare_Idle_State
Note:This parameter is valid only for TIM1 and TIM8.
uint32_t TIM_OC_InitTypeDef::OCNIdleState
Specifies the TIM Output Compare pin state during Idle state. This parameter can be
a value of TIM_Output_Compare_N_Idle_State
Note:This parameter is valid only for TIM1 and TIM8.

62.1.3

TIM_OnePulse_InitTypeDef
Data Fields
uint32_t OCMode
uint32_t Pulse
uint32_t OCPolarity
uint32_t OCNPolarity
uint32_t OCIdleState
uint32_t OCNIdleState
uint32_t ICPolarity
uint32_t ICSelection
uint32_t ICFilter

Field Documentation
uint32_t TIM_OnePulse_InitTypeDef::OCMode
Specifies the TIM mode. This parameter can be a value of
TIM_Output_Compare_and_PWM_modes
uint32_t TIM_OnePulse_InitTypeDef::Pulse
Specifies the pulse value to be loaded into the Capture Compare Register. This
parameter can be a number between Min_Data = 0x0000U and Max_Data = 0xFFFFU

DocID025834 Rev 4

843/964

HAL TIM Generic Driver

UM1725

uint32_t TIM_OnePulse_InitTypeDef::OCPolarity
Specifies the output polarity. This parameter can be a value of
TIM_Output_Compare_Polarity
uint32_t TIM_OnePulse_InitTypeDef::OCNPolarity
Specifies the complementary output polarity. This parameter can be a value of
TIM_Output_Compare_N_Polarity
Note:This parameter is valid only for TIM1 and TIM8.
uint32_t TIM_OnePulse_InitTypeDef::OCIdleState
Specifies the TIM Output Compare pin state during Idle state. This parameter can be
a value of TIM_Output_Compare_Idle_State
Note:This parameter is valid only for TIM1 and TIM8.
uint32_t TIM_OnePulse_InitTypeDef::OCNIdleState
Specifies the TIM Output Compare pin state during Idle state. This parameter can be
a value of TIM_Output_Compare_N_Idle_State
Note:This parameter is valid only for TIM1 and TIM8.
uint32_t TIM_OnePulse_InitTypeDef::ICPolarity
Specifies the active edge of the input signal. This parameter can be a value of
TIM_Input_Capture_Polarity
uint32_t TIM_OnePulse_InitTypeDef::ICSelection
Specifies the input. This parameter can be a value of TIM_Input_Capture_Selection
uint32_t TIM_OnePulse_InitTypeDef::ICFilter
Specifies the input capture filter. This parameter can be a number between Min_Data
= 0x0 and Max_Data = 0xF

62.1.4

TIM_IC_InitTypeDef
Data Fields
uint32_t ICPolarity
uint32_t ICSelection
uint32_t ICPrescaler
uint32_t ICFilter

Field Documentation
uint32_t TIM_IC_InitTypeDef::ICPolarity
Specifies the active edge of the input signal. This parameter can be a value of
TIM_Input_Capture_Polarity
uint32_t TIM_IC_InitTypeDef::ICSelection
Specifies the input. This parameter can be a value of TIM_Input_Capture_Selection
uint32_t TIM_IC_InitTypeDef::ICPrescaler
Specifies the Input Capture Prescaler. This parameter can be a value of
TIM_Input_Capture_Prescaler
uint32_t TIM_IC_InitTypeDef::ICFilter
Specifies the input capture filter. This parameter can be a number between Min_Data
= 0x0 and Max_Data = 0xF

844/964

DocID025834 Rev 4

UM1725

62.1.5

HAL TIM Generic Driver

TIM_Encoder_InitTypeDef
Data Fields
uint32_t EncoderMode
uint32_t IC1Polarity
uint32_t IC1Selection
uint32_t IC1Prescaler
uint32_t IC1Filter
uint32_t IC2Polarity
uint32_t IC2Selection
uint32_t IC2Prescaler
uint32_t IC2Filter

Field Documentation
uint32_t TIM_Encoder_InitTypeDef::EncoderMode
Specifies the active edge of the input signal. This parameter can be a value of
TIM_Encoder_Mode
uint32_t TIM_Encoder_InitTypeDef::IC1Polarity
Specifies the active edge of the input signal. This parameter can be a value of
TIM_Input_Capture_Polarity
uint32_t TIM_Encoder_InitTypeDef::IC1Selection
Specifies the input. This parameter can be a value of TIM_Input_Capture_Selection
uint32_t TIM_Encoder_InitTypeDef::IC1Prescaler
Specifies the Input Capture Prescaler. This parameter can be a value of
TIM_Input_Capture_Prescaler
uint32_t TIM_Encoder_InitTypeDef::IC1Filter
Specifies the input capture filter. This parameter can be a number between Min_Data
= 0x0 and Max_Data = 0xF
uint32_t TIM_Encoder_InitTypeDef::IC2Polarity
Specifies the active edge of the input signal. This parameter can be a value of
TIM_Input_Capture_Polarity
uint32_t TIM_Encoder_InitTypeDef::IC2Selection
Specifies the input. This parameter can be a value of TIM_Input_Capture_Selection
uint32_t TIM_Encoder_InitTypeDef::IC2Prescaler
Specifies the Input Capture Prescaler. This parameter can be a value of
TIM_Input_Capture_Prescaler
uint32_t TIM_Encoder_InitTypeDef::IC2Filter
Specifies the input capture filter. This parameter can be a number between Min_Data
= 0x0 and Max_Data = 0xF

62.1.6

TIM_ClockConfigTypeDef
Data Fields
uint32_t ClockSource
uint32_t ClockPolarity
uint32_t ClockPrescaler
DocID025834 Rev 4

845/964

HAL TIM Generic Driver

UM1725

uint32_t ClockFilter

Field Documentation
uint32_t TIM_ClockConfigTypeDef::ClockSource
TIM clock sources. This parameter can be a value of TIM_Clock_Source
uint32_t TIM_ClockConfigTypeDef::ClockPolarity
TIM clock polarity. This parameter can be a value of TIM_Clock_Polarity
uint32_t TIM_ClockConfigTypeDef::ClockPrescaler
TIM clock prescaler. This parameter can be a value of TIM_Clock_Prescaler
uint32_t TIM_ClockConfigTypeDef::ClockFilter
TIM clock filter. This parameter can be a number between Min_Data = 0x0 and
Max_Data = 0xF

62.1.7

TIM_ClearInputConfigTypeDef
Data Fields
uint32_t ClearInputState
uint32_t ClearInputSource
uint32_t ClearInputPolarity
uint32_t ClearInputPrescaler
uint32_t ClearInputFilter

Field Documentation
uint32_t TIM_ClearInputConfigTypeDef::ClearInputState
TIM clear Input state. This parameter can be ENABLE or DISABLE
uint32_t TIM_ClearInputConfigTypeDef::ClearInputSource
TIM clear Input sources. This parameter can be a value of TIM_ClearInput_Source
uint32_t TIM_ClearInputConfigTypeDef::ClearInputPolarity
TIM Clear Input polarity. This parameter can be a value of TIM_ClearInput_Polarity
uint32_t TIM_ClearInputConfigTypeDef::ClearInputPrescaler
TIM Clear Input prescaler. This parameter can be a value of
TIM_ClearInput_Prescaler
uint32_t TIM_ClearInputConfigTypeDef::ClearInputFilter
TIM Clear Input filter. This parameter can be a number between Min_Data = 0x0 and
Max_Data = 0xF

62.1.8

TIM_SlaveConfigTypeDef
Data Fields
uint32_t SlaveMode
uint32_t InputTrigger
uint32_t TriggerPolarity
uint32_t TriggerPrescaler
uint32_t TriggerFilter

846/964

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
Field Documentation
uint32_t TIM_SlaveConfigTypeDef::SlaveMode
Slave mode selection This parameter can be a value of TIM_Slave_Mode
uint32_t TIM_SlaveConfigTypeDef::InputTrigger
Input Trigger source This parameter can be a value of TIM_Trigger_Selection
uint32_t TIM_SlaveConfigTypeDef::TriggerPolarity
Input Trigger polarity This parameter can be a value of TIM_Trigger_Polarity
uint32_t TIM_SlaveConfigTypeDef::TriggerPrescaler
Input trigger prescaler This parameter can be a value of TIM_Trigger_Prescaler
uint32_t TIM_SlaveConfigTypeDef::TriggerFilter
Input trigger filter This parameter can be a number between Min_Data = 0x0 and
Max_Data = 0xF

62.1.9

TIM_HandleTypeDef
Data Fields
TIM_TypeDef * Instance
TIM_Base_InitTypeDef Init
HAL_TIM_ActiveChannel Channel
DMA_HandleTypeDef * hdma
HAL_LockTypeDef Lock
__IO HAL_TIM_StateTypeDef State

Field Documentation
TIM_TypeDef* TIM_HandleTypeDef::Instance
Register base address
TIM_Base_InitTypeDef TIM_HandleTypeDef::Init
TIM Time Base required parameters
HAL_TIM_ActiveChannel TIM_HandleTypeDef::Channel
Active channel
DMA_HandleTypeDef* TIM_HandleTypeDef::hdma[7]
DMA Handlers array This array is accessed by a DMA_Handle_index
HAL_LockTypeDef TIM_HandleTypeDef::Lock
Locking object
__IO HAL_TIM_StateTypeDef TIM_HandleTypeDef::State
TIM operation state

62.2

TIM Firmware driver API description

62.2.1

TIMER Generic features
The Timer features include:
1.
2.
3.

16-bit up, down, up/down auto-reload counter.
16-bit programmable prescaler allowing dividing (also on the fly) the counter clock
frequency either by any factor between 1 and 65536.
Up to 4 independent channels for:
DocID025834 Rev 4

847/964

HAL TIM Generic Driver

UM1725

Input Capture
Output Compare
PWM generation (Edge and Center-aligned Mode)
One-pulse mode output

62.2.2

How to use this driver
1.

2.

3.

4.

5.

6.

848/964

Initialize the TIM low level resources by implementing the following functions
depending from feature used :
Time Base : HAL_TIM_Base_MspInit()
Input Capture : HAL_TIM_IC_MspInit()
Output Compare : HAL_TIM_OC_MspInit()
PWM generation : HAL_TIM_PWM_MspInit()
One-pulse mode output : HAL_TIM_OnePulse_MspInit()
Encoder mode output : HAL_TIM_Encoder_MspInit()
Initialize the TIM low level resources :
a.
Enable the TIM interface clock using __TIMx_CLK_ENABLE();
b.
TIM pins configuration
Enable the clock for the TIM GPIOs using the following function:
__GPIOx_CLK_ENABLE();
Configure these TIM pins in Alternate function mode using
HAL_GPIO_Init();
The external Clock can be configured, if needed (the default clock is the internal clock
from the APBx), using the following function: HAL_TIM_ConfigClockSource, the clock
configuration should be done before any start function.
Configure the TIM in the desired functioning mode using one of the initialization
function of this driver:
HAL_TIM_Base_Init: to use the Timer to generate a simple time base
HAL_TIM_OC_Init and HAL_TIM_OC_ConfigChannel: to use the Timer to
generate an Output Compare signal.
HAL_TIM_PWM_Init and HAL_TIM_PWM_ConfigChannel: to use the Timer to
generate a PWM signal.
HAL_TIM_IC_Init and HAL_TIM_IC_ConfigChannel: to use the Timer to
measure an external signal.
HAL_TIM_OnePulse_Init and HAL_TIM_OnePulse_ConfigChannel: to use the
Timer in One Pulse Mode.
HAL_TIM_Encoder_Init: to use the Timer Encoder Interface.
Activate the TIM peripheral using one of the start functions depending from the
feature used:
Time Base : HAL_TIM_Base_Start(), HAL_TIM_Base_Start_DMA(),
HAL_TIM_Base_Start_IT()
Input Capture : HAL_TIM_IC_Start(), HAL_TIM_IC_Start_DMA(),
HAL_TIM_IC_Start_IT()
Output Compare : HAL_TIM_OC_Start(), HAL_TIM_OC_Start_DMA(),
HAL_TIM_OC_Start_IT()
PWM generation : HAL_TIM_PWM_Start(), HAL_TIM_PWM_Start_DMA(),
HAL_TIM_PWM_Start_IT()
One-pulse mode output : HAL_TIM_OnePulse_Start(),
HAL_TIM_OnePulse_Start_IT()
Encoder mode output : HAL_TIM_Encoder_Start(),
HAL_TIM_Encoder_Start_DMA(), HAL_TIM_Encoder_Start_IT().
The DMA Burst is managed with the two following functions:
HAL_TIM_DMABurst_WriteStart() HAL_TIM_DMABurst_ReadStart()
DocID025834 Rev 4

UM1725

62.2.3

HAL TIM Generic Driver

Time Base functions
This section provides functions allowing to:
Initialize and configure the TIM base.
De-initialize the TIM base.
Start the Time Base.
Stop the Time Base.
Start the Time Base and enable interrupt.
Stop the Time Base and disable interrupt.
Start the Time Base and enable DMA transfer.
Stop the Time Base and disable DMA transfer.
This section contains the following APIs:
HAL_TIM_Base_Init()
HAL_TIM_Base_DeInit()
HAL_TIM_Base_MspInit()
HAL_TIM_Base_MspDeInit()
HAL_TIM_Base_Start()
HAL_TIM_Base_Stop()
HAL_TIM_Base_Start_IT()
HAL_TIM_Base_Stop_IT()
HAL_TIM_Base_Start_DMA()
HAL_TIM_Base_Stop_DMA()

62.2.4

Time Output Compare functions
This section provides functions allowing to:
Initialize and configure the TIM Output Compare.
De-initialize the TIM Output Compare.
Start the Time Output Compare.
Stop the Time Output Compare.
Start the Time Output Compare and enable interrupt.
Stop the Time Output Compare and disable interrupt.
Start the Time Output Compare and enable DMA transfer.
Stop the Time Output Compare and disable DMA transfer.
This section contains the following APIs:
HAL_TIM_OC_Init()
HAL_TIM_OC_DeInit()
HAL_TIM_OC_MspInit()
HAL_TIM_OC_MspDeInit()
HAL_TIM_OC_Start()
HAL_TIM_OC_Stop()
HAL_TIM_OC_Start_IT()
HAL_TIM_OC_Stop_IT()
HAL_TIM_OC_Start_DMA()
HAL_TIM_OC_Stop_DMA()

62.2.5

Time PWM functions
This section provides functions allowing to:
Initialize and configure the TIM OPWM.
De-initialize the TIM PWM.
DocID025834 Rev 4

849/964

HAL TIM Generic Driver

UM1725

Start the Time PWM.
Stop the Time PWM.
Start the Time PWM and enable interrupt.
Stop the Time PWM and disable interrupt.
Start the Time PWM and enable DMA transfer.
Stop the Time PWM and disable DMA transfer.
This section contains the following APIs:
HAL_TIM_PWM_Init()
HAL_TIM_PWM_DeInit()
HAL_TIM_PWM_MspInit()
HAL_TIM_PWM_MspDeInit()
HAL_TIM_PWM_Start()
HAL_TIM_PWM_Stop()
HAL_TIM_PWM_Start_IT()
HAL_TIM_PWM_Stop_IT()
HAL_TIM_PWM_Start_DMA()
HAL_TIM_PWM_Stop_DMA()

62.2.6

Time Input Capture functions
This section provides functions allowing to:
Initialize and configure the TIM Input Capture.
De-initialize the TIM Input Capture.
Start the Time Input Capture.
Stop the Time Input Capture.
Start the Time Input Capture and enable interrupt.
Stop the Time Input Capture and disable interrupt.
Start the Time Input Capture and enable DMA transfer.
Stop the Time Input Capture and disable DMA transfer.
This section contains the following APIs:
HAL_TIM_IC_Init()
HAL_TIM_IC_DeInit()
HAL_TIM_IC_MspInit()
HAL_TIM_IC_MspDeInit()
HAL_TIM_IC_Start()
HAL_TIM_IC_Stop()
HAL_TIM_IC_Start_IT()
HAL_TIM_IC_Stop_IT()
HAL_TIM_IC_Start_DMA()
HAL_TIM_IC_Stop_DMA()

62.2.7

Time One Pulse functions
This section provides functions allowing to:
Initialize and configure the TIM One Pulse.
De-initialize the TIM One Pulse.
Start the Time One Pulse.
Stop the Time One Pulse.
Start the Time One Pulse and enable interrupt.
Stop the Time One Pulse and disable interrupt.
Start the Time One Pulse and enable DMA transfer.

850/964

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
Stop the Time One Pulse and disable DMA transfer.
This section contains the following APIs:
HAL_TIM_OnePulse_Init()
HAL_TIM_OnePulse_DeInit()
HAL_TIM_OnePulse_MspInit()
HAL_TIM_OnePulse_MspDeInit()
HAL_TIM_OnePulse_Start()
HAL_TIM_OnePulse_Stop()
HAL_TIM_OnePulse_Start_IT()
HAL_TIM_OnePulse_Stop_IT()

62.2.8

Time Encoder functions
This section provides functions allowing to:
Initialize and configure the TIM Encoder.
De-initialize the TIM Encoder.
Start the Time Encoder.
Stop the Time Encoder.
Start the Time Encoder and enable interrupt.
Stop the Time Encoder and disable interrupt.
Start the Time Encoder and enable DMA transfer.
Stop the Time Encoder and disable DMA transfer.
This section contains the following APIs:
HAL_TIM_Encoder_Init()
HAL_TIM_Encoder_DeInit()
HAL_TIM_Encoder_MspInit()
HAL_TIM_Encoder_MspDeInit()
HAL_TIM_Encoder_Start()
HAL_TIM_Encoder_Stop()
HAL_TIM_Encoder_Start_IT()
HAL_TIM_Encoder_Stop_IT()
HAL_TIM_Encoder_Start_DMA()
HAL_TIM_Encoder_Stop_DMA()

62.2.9

IRQ handler management
This section provides Timer IRQ handler function.
This section contains the following APIs:
HAL_TIM_IRQHandler()

62.2.10

Peripheral Control functions
This section provides functions allowing to:
Configure The Input Output channels for OC, PWM, IC or One Pulse mode.
Configure External Clock source.
Configure Complementary channels, break features and dead time.
Configure Master and the Slave synchronization.
Configure the DMA Burst Mode.
This section contains the following APIs:

DocID025834 Rev 4

851/964

HAL TIM Generic Driver

UM1725

HAL_TIM_OC_ConfigChannel()
HAL_TIM_IC_ConfigChannel()
HAL_TIM_PWM_ConfigChannel()
HAL_TIM_OnePulse_ConfigChannel()
HAL_TIM_DMABurst_WriteStart()
HAL_TIM_DMABurst_WriteStop()
HAL_TIM_DMABurst_ReadStart()
HAL_TIM_DMABurst_ReadStop()
HAL_TIM_GenerateEvent()
HAL_TIM_ConfigOCrefClear()
HAL_TIM_ConfigClockSource()
HAL_TIM_ConfigTI1Input()
HAL_TIM_SlaveConfigSynchronization()
HAL_TIM_SlaveConfigSynchronization_IT()
HAL_TIM_ReadCapturedValue()

62.2.11

TIM Callbacks functions
This section provides TIM callback functions:
Timer Period elapsed callback
Timer Output Compare callback
Timer Input capture callback
Timer Trigger callback
Timer Error callback
This section contains the following APIs:
HAL_TIM_PeriodElapsedCallback()
HAL_TIM_OC_DelayElapsedCallback()
HAL_TIM_IC_CaptureCallback()
HAL_TIM_PWM_PulseFinishedCallback()
HAL_TIM_TriggerCallback()
HAL_TIM_ErrorCallback()

62.2.12

Peripheral State functions
This subsection permits to get in run-time the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_TIM_Base_GetState()
HAL_TIM_OC_GetState()
HAL_TIM_PWM_GetState()
HAL_TIM_IC_GetState()
HAL_TIM_OnePulse_GetState()
HAL_TIM_Encoder_GetState()

62.2.13

Detailed description of functions
HAL_TIM_Base_Init

852/964

Function Name

HAL_StatusTypeDef HAL_TIM_Base_Init (TIM_HandleTypeDef
* htim)

Function Description

Initializes the TIM Time base Unit according to the specified
parameters in the TIM_HandleTypeDef and create the associated
DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
handle.
Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_Base_DeInit
Function Name

HAL_StatusTypeDef HAL_TIM_Base_DeInit
(TIM_HandleTypeDef * htim)

Function Description

DeInitializes the TIM Base peripheral.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_Base_MspInit
Function Name

void HAL_TIM_Base_MspInit (TIM_HandleTypeDef * htim)

Function Description

Initializes the TIM Base MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_Base_MspDeInit
Function Name

void HAL_TIM_Base_MspDeInit (TIM_HandleTypeDef * htim)

Function Description

DeInitializes TIM Base MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_Base_Start
Function Name

HAL_StatusTypeDef HAL_TIM_Base_Start
(TIM_HandleTypeDef * htim)

Function Description

Starts the TIM Base generation.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_Base_Stop
Function Name

HAL_StatusTypeDef HAL_TIM_Base_Stop
(TIM_HandleTypeDef * htim)

Function Description

Stops the TIM Base generation.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
DocID025834 Rev 4

853/964

HAL TIM Generic Driver

UM1725
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_Base_Start_IT
Function Name

HAL_StatusTypeDef HAL_TIM_Base_Start_IT
(TIM_HandleTypeDef * htim)

Function Description

Starts the TIM Base generation in interrupt mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_Base_Stop_IT
Function Name

HAL_StatusTypeDef HAL_TIM_Base_Stop_IT
(TIM_HandleTypeDef * htim)

Function Description

Stops the TIM Base generation in interrupt mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_Base_Start_DMA
Function Name

HAL_StatusTypeDef HAL_TIM_Base_Start_DMA
(TIM_HandleTypeDef * htim, uint32_t * pData, uint16_t Length)

Function Description

Starts the TIM Base generation in DMA mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
pData: The source Buffer address.
Length: The length of data to be transferred from memory to
peripheral.

Return values

HAL: status

HAL_TIM_Base_Stop_DMA
Function Name

HAL_StatusTypeDef HAL_TIM_Base_Stop_DMA
(TIM_HandleTypeDef * htim)

Function Description

Stops the TIM Base generation in DMA mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_OC_Init
Function Name

854/964

HAL_StatusTypeDef HAL_TIM_OC_Init (TIM_HandleTypeDef *
htim)

DocID025834 Rev 4

UM1725
Function Description

HAL TIM Generic Driver
Initializes the TIM Output Compare according to the specified
parameters in the TIM_HandleTypeDef and create the associated
handle.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_OC_DeInit
Function Name

HAL_StatusTypeDef HAL_TIM_OC_DeInit
(TIM_HandleTypeDef * htim)

Function Description

DeInitializes the TIM peripheral.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_OC_MspInit
Function Name

void HAL_TIM_OC_MspInit (TIM_HandleTypeDef * htim)

Function Description

Initializes the TIM Output Compare MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_OC_MspDeInit
Function Name

void HAL_TIM_OC_MspDeInit (TIM_HandleTypeDef * htim)

Function Description

DeInitializes TIM Output Compare MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_OC_Start
Function Name

HAL_StatusTypeDef HAL_TIM_OC_Start (TIM_HandleTypeDef
* htim, uint32_t Channel)

Function Description

Starts the TIM Output Compare signal generation.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be enabled. This parameter can be
one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status
DocID025834 Rev 4

855/964

HAL TIM Generic Driver

UM1725

HAL_TIM_OC_Stop
Function Name

HAL_StatusTypeDef HAL_TIM_OC_Stop (TIM_HandleTypeDef
* htim, uint32_t Channel)

Function Description

Stops the TIM Output Compare signal generation.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_OC_Start_IT
Function Name

HAL_StatusTypeDef HAL_TIM_OC_Start_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Starts the TIM Output Compare signal generation in interrupt
mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be enabled. This parameter can be
one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_OC_Stop_IT

856/964

Function Name

HAL_StatusTypeDef HAL_TIM_OC_Stop_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM Output Compare signal generation in interrupt
mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver

HAL_TIM_OC_Start_DMA
Function Name

HAL_StatusTypeDef HAL_TIM_OC_Start_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel, uint32_t *
pData, uint16_t Length)

Function Description

Starts the TIM Output Compare signal generation in DMA mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be enabled. This parameter can be
one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected
pData: The source Buffer address.
Length: The length of data to be transferred from memory to
TIM peripheral

Return values

HAL: status

HAL_TIM_OC_Stop_DMA
Function Name

HAL_StatusTypeDef HAL_TIM_OC_Stop_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM Output Compare signal generation in DMA mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_PWM_Init
Function Name

HAL_StatusTypeDef HAL_TIM_PWM_Init (TIM_HandleTypeDef
* htim)

Function Description

Initializes the TIM PWM Time Base according to the specified
parameters in the TIM_HandleTypeDef and create the associated
handle.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_PWM_DeInit
Function Name

HAL_StatusTypeDef HAL_TIM_PWM_DeInit
(TIM_HandleTypeDef * htim)
DocID025834 Rev 4

857/964

HAL TIM Generic Driver
Function Description

UM1725
DeInitializes the TIM peripheral.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_PWM_MspInit
Function Name

void HAL_TIM_PWM_MspInit (TIM_HandleTypeDef * htim)

Function Description

Initializes the TIM PWM MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_PWM_MspDeInit
Function Name

void HAL_TIM_PWM_MspDeInit (TIM_HandleTypeDef * htim)

Function Description

DeInitializes TIM PWM MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_PWM_Start
Function Name

HAL_StatusTypeDef HAL_TIM_PWM_Start
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Starts the PWM signal generation.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_PWM_Stop
Function Name

HAL_StatusTypeDef HAL_TIM_PWM_Stop
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the PWM signal generation.

Parameters

858/964

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected
Return values

HAL: status

HAL_TIM_PWM_Start_IT
Function Name

HAL_StatusTypeDef HAL_TIM_PWM_Start_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Starts the PWM signal generation in interrupt mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_PWM_Stop_IT
Function Name

HAL_StatusTypeDef HAL_TIM_PWM_Stop_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the PWM signal generation in interrupt mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_PWM_Start_DMA
Function Name

HAL_StatusTypeDef HAL_TIM_PWM_Start_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel, uint32_t *
pData, uint16_t Length)

Function Description

Starts the TIM PWM signal generation in DMA mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected
pData: The source Buffer address.
DocID025834 Rev 4

859/964

HAL TIM Generic Driver

UM1725
Length: The length of data to be transferred from memory to
TIM peripheral

Return values

HAL: status

HAL_TIM_PWM_Stop_DMA
Function Name

HAL_StatusTypeDef HAL_TIM_PWM_Stop_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM PWM signal generation in DMA mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_IC_Init
Function Name

HAL_StatusTypeDef HAL_TIM_IC_Init (TIM_HandleTypeDef *
htim)

Function Description

Initializes the TIM Input Capture Time base according to the
specified parameters in the TIM_HandleTypeDef and create the
associated handle.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_IC_DeInit
Function Name

HAL_StatusTypeDef HAL_TIM_IC_DeInit (TIM_HandleTypeDef
* htim)

Function Description

DeInitializes the TIM peripheral.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_IC_MspInit

860/964

Function Name

void HAL_TIM_IC_MspInit (TIM_HandleTypeDef * htim)

Function Description

Initializes the TIM INput Capture MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver

HAL_TIM_IC_MspDeInit
Function Name

void HAL_TIM_IC_MspDeInit (TIM_HandleTypeDef * htim)

Function Description

DeInitializes TIM Input Capture MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_IC_Start
Function Name

HAL_StatusTypeDef HAL_TIM_IC_Start (TIM_HandleTypeDef *
htim, uint32_t Channel)

Function Description

Starts the TIM Input Capture measurement.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_IC_Stop
Function Name

HAL_StatusTypeDef HAL_TIM_IC_Stop (TIM_HandleTypeDef *
htim, uint32_t Channel)

Function Description

Stops the TIM Input Capture measurement.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_IC_Start_IT
Function Name

HAL_StatusTypeDef HAL_TIM_IC_Start_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Starts the TIM Input Capture measurement in interrupt mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
DocID025834 Rev 4

861/964

HAL TIM Generic Driver

UM1725
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_IC_Stop_IT
Function Name

HAL_StatusTypeDef HAL_TIM_IC_Stop_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM Input Capture measurement in interrupt mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_IC_Start_DMA
Function Name

HAL_StatusTypeDef HAL_TIM_IC_Start_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel, uint32_t *
pData, uint16_t Length)

Function Description

Starts the TIM Input Capture measurement on in DMA mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected
pData: The destination Buffer address.
Length: The length of data to be transferred from TIM
peripheral to memory.

Return values

HAL: status

HAL_TIM_IC_Stop_DMA
Function Name

HAL_StatusTypeDef HAL_TIM_IC_Stop_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM Input Capture measurement on in DMA mode.

Parameters

862/964

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected
Return values

HAL: status

HAL_TIM_OnePulse_Init
Function Name

HAL_StatusTypeDef HAL_TIM_OnePulse_Init
(TIM_HandleTypeDef * htim, uint32_t OnePulseMode)

Function Description

Initializes the TIM One Pulse Time Base according to the specified
parameters in the TIM_HandleTypeDef and create the associated
handle.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
OnePulseMode: Select the One pulse mode. This parameter
can be one of the following values:
TIM_OPMODE_SINGLE: Only one pulse will be
generated.
TIM_OPMODE_REPETITIVE: Repetitive pulses will be
generated.

Return values

HAL: status

HAL_TIM_OnePulse_DeInit
Function Name

HAL_StatusTypeDef HAL_TIM_OnePulse_DeInit
(TIM_HandleTypeDef * htim)

Function Description

DeInitializes the TIM One Pulse.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_OnePulse_MspInit
Function Name

void HAL_TIM_OnePulse_MspInit (TIM_HandleTypeDef * htim)

Function Description

Initializes the TIM One Pulse MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_OnePulse_MspDeInit
Function Name

void HAL_TIM_OnePulse_MspDeInit (TIM_HandleTypeDef *
htim)

Function Description

DeInitializes TIM One Pulse MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None
DocID025834 Rev 4

863/964

HAL TIM Generic Driver

UM1725

HAL_TIM_OnePulse_Start
Function Name

HAL_StatusTypeDef HAL_TIM_OnePulse_Start
(TIM_HandleTypeDef * htim, uint32_t OutputChannel)

Function Description

Starts the TIM One Pulse signal generation.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
OutputChannel: : TIM Channels to be enabled. This
parameter can be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected

Return values

HAL: status

HAL_TIM_OnePulse_Stop
Function Name

HAL_StatusTypeDef HAL_TIM_OnePulse_Stop
(TIM_HandleTypeDef * htim, uint32_t OutputChannel)

Function Description

Stops the TIM One Pulse signal generation.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
OutputChannel: : TIM Channels to be disable. This
parameter can be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected

Return values

HAL: status

HAL_TIM_OnePulse_Start_IT
Function Name

HAL_StatusTypeDef HAL_TIM_OnePulse_Start_IT
(TIM_HandleTypeDef * htim, uint32_t OutputChannel)

Function Description

Starts the TIM One Pulse signal generation in interrupt mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
OutputChannel: : TIM Channels to be enabled. This
parameter can be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected

Return values

HAL: status

HAL_TIM_OnePulse_Stop_IT
Function Name

HAL_StatusTypeDef HAL_TIM_OnePulse_Stop_IT
(TIM_HandleTypeDef * htim, uint32_t OutputChannel)

Function Description

Stops the TIM One Pulse signal generation in interrupt mode.

Parameters

864/964

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
OutputChannel: : TIM Channels to be enabled. This
parameter can be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
TIM_CHANNEL_2: TIM Channel 2 selected
Return values

HAL: status

HAL_TIM_Encoder_Init
Function Name

HAL_StatusTypeDef HAL_TIM_Encoder_Init
(TIM_HandleTypeDef * htim, TIM_Encoder_InitTypeDef *
sConfig)

Function Description

Initializes the TIM Encoder Interface and create the associated
handle.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
sConfig: TIM Encoder Interface configuration structure

Return values

HAL: status

HAL_TIM_Encoder_DeInit
Function Name

HAL_StatusTypeDef HAL_TIM_Encoder_DeInit
(TIM_HandleTypeDef * htim)

Function Description

DeInitializes the TIM Encoder interface.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIM_Encoder_MspInit
Function Name

void HAL_TIM_Encoder_MspInit (TIM_HandleTypeDef * htim)

Function Description

Initializes the TIM Encoder Interface MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_Encoder_MspDeInit
Function Name

void HAL_TIM_Encoder_MspDeInit (TIM_HandleTypeDef *
htim)

Function Description

DeInitializes TIM Encoder Interface MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_Encoder_Start
Function Name

HAL_StatusTypeDef HAL_TIM_Encoder_Start
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Starts the TIM Encoder Interface.

DocID025834 Rev 4

865/964

HAL TIM Generic Driver
Parameters

UM1725
htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2
are selected

Return values

HAL: status

HAL_TIM_Encoder_Stop
Function Name

HAL_StatusTypeDef HAL_TIM_Encoder_Stop
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM Encoder Interface.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2
are selected

Return values

HAL: status

HAL_TIM_Encoder_Start_IT
Function Name

HAL_StatusTypeDef HAL_TIM_Encoder_Start_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Starts the TIM Encoder Interface in interrupt mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2
are selected

Return values

HAL: status

HAL_TIM_Encoder_Stop_IT
Function Name

HAL_StatusTypeDef HAL_TIM_Encoder_Stop_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM Encoder Interface in interrupt mode.

Parameters

866/964

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be disabled. This parameter can
be one of the following values:
DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2
are selected
Return values

HAL: status

HAL_TIM_Encoder_Start_DMA
Function Name

HAL_StatusTypeDef HAL_TIM_Encoder_Start_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel, uint32_t *
pData1, uint32_t * pData2, uint16_t Length)

Function Description

Starts the TIM Encoder Interface in DMA mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2
are selected
pData1: The destination Buffer address for IC1.
pData2: The destination Buffer address for IC2.
Length: The length of data to be transferred from TIM
peripheral to memory.

Return values

HAL: status

HAL_TIM_Encoder_Stop_DMA
Function Name

HAL_StatusTypeDef HAL_TIM_Encoder_Stop_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM Encoder Interface in DMA mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2
are selected

Return values

HAL: status

HAL_TIM_IRQHandler
Function Name

void HAL_TIM_IRQHandler (TIM_HandleTypeDef * htim)

Function Description

This function handles TIM interrupts requests.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None
DocID025834 Rev 4

867/964

HAL TIM Generic Driver

UM1725

HAL_TIM_OC_ConfigChannel
Function Name

HAL_StatusTypeDef HAL_TIM_OC_ConfigChannel
(TIM_HandleTypeDef * htim, TIM_OC_InitTypeDef * sConfig,
uint32_t Channel)

Function Description

Initializes the TIM Output Compare Channels according to the
specified parameters in the TIM_OC_InitTypeDef.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
sConfig: TIM Output Compare configuration structure
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_PWM_ConfigChannel
Function Name

HAL_StatusTypeDef HAL_TIM_PWM_ConfigChannel
(TIM_HandleTypeDef * htim, TIM_OC_InitTypeDef * sConfig,
uint32_t Channel)

Function Description

Initializes the TIM PWM channels according to the specified
parameters in the TIM_OC_InitTypeDef.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
sConfig: TIM PWM configuration structure
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_IC_ConfigChannel
Function Name

HAL_StatusTypeDef HAL_TIM_IC_ConfigChannel
(TIM_HandleTypeDef * htim, TIM_IC_InitTypeDef * sConfig,
uint32_t Channel)

Function Description

Initializes the TIM Input Capture Channels according to the
specified parameters in the TIM_IC_InitTypeDef.

Parameters

868/964

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
sConfig: TIM Input Capture configuration structure
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected
Return values

HAL: status

HAL_TIM_OnePulse_ConfigChannel
Function Name

HAL_StatusTypeDef HAL_TIM_OnePulse_ConfigChannel
(TIM_HandleTypeDef * htim, TIM_OnePulse_InitTypeDef *
sConfig, uint32_t OutputChannel, uint32_t InputChannel)

Function Description

Initializes the TIM One Pulse Channels according to the specified
parameters in the TIM_OnePulse_InitTypeDef.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
sConfig: TIM One Pulse configuration structure
OutputChannel: TIM Channels to be enabled. This
parameter can be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
InputChannel: TIM Channels to be enabled. This parameter
can be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected

Return values

HAL: status

HAL_TIM_ConfigOCrefClear
Function Name

HAL_StatusTypeDef HAL_TIM_ConfigOCrefClear
(TIM_HandleTypeDef * htim, TIM_ClearInputConfigTypeDef *
sClearInputConfig, uint32_t Channel)

Function Description

Configures the OCRef clear feature.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
sClearInputConfig: pointer to a
TIM_ClearInputConfigTypeDef structure that contains the
OCREF clear feature and parameters for the TIM peripheral.
Channel: specifies the TIM Channel. This parameter can be
one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIM_ConfigClockSource
Function Name

HAL_StatusTypeDef HAL_TIM_ConfigClockSource
(TIM_HandleTypeDef * htim, TIM_ClockConfigTypeDef *
sClockSourceConfig)

Function Description

Configures the clock source to be used.
DocID025834 Rev 4

869/964

HAL TIM Generic Driver
Parameters

Return values

UM1725
htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
sClockSourceConfig: pointer to a TIM_ClockConfigTypeDef
structure that contains the clock source information for the
TIM peripheral.
HAL: status

HAL_TIM_ConfigTI1Input
Function Name

HAL_StatusTypeDef HAL_TIM_ConfigTI1Input
(TIM_HandleTypeDef * htim, uint32_t TI1_Selection)

Function Description

Selects the signal connected to the TI1 input: direct from
CH1_input or a XOR combination between CH1_input, CH2_input
& CH3_input.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
TI1_Selection: Indicate whether or not channel 1 is
connected to the output of a XOR gate. This parameter can
be one of the following values:
TIM_TI1SELECTION_CH1: The TIMx_CH1 pin is
connected to TI1 input
TIM_TI1SELECTION_XORCOMBINATION: The
TIMx_CH1, CH2 and CH3 pins are connected to the TI1
input (XOR combination)

Return values

HAL: status

HAL_TIM_SlaveConfigSynchronization
Function Name

HAL_StatusTypeDef HAL_TIM_SlaveConfigSynchronization
(TIM_HandleTypeDef * htim, TIM_SlaveConfigTypeDef *
sSlaveConfig)

Function Description

Configures the TIM in Slave mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
sSlaveConfig: pointer to a TIM_SlaveConfigTypeDef
structure that contains the selected trigger (internal trigger
input, filtered timer input or external trigger input) and the )
and the Slave mode (Disable, Reset, Gated, Trigger, External
clock mode 1).

Return values

HAL: status

HAL_TIM_SlaveConfigSynchronization_IT
Function Name

HAL_StatusTypeDef
HAL_TIM_SlaveConfigSynchronization_IT
(TIM_HandleTypeDef * htim, TIM_SlaveConfigTypeDef *
sSlaveConfig)

Function Description

Configures the TIM in Slave mode in interrupt mode.

Parameters

870/964

htim: TIM handle.
DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
sSlaveConfig: pointer to a TIM_SlaveConfigTypeDef
structure that contains the selected trigger (internal trigger
input, filtered timer input or external trigger input) and the )
and the Slave mode (Disable, Reset, Gated, Trigger, External
clock mode 1).
Return values

HAL: status

HAL_TIM_DMABurst_WriteStart
Function Name

HAL_StatusTypeDef HAL_TIM_DMABurst_WriteStart
(TIM_HandleTypeDef * htim, uint32_t BurstBaseAddress,
uint32_t BurstRequestSrc, uint32_t * BurstBuffer, uint32_t
BurstLength)

Function Description

Configure the DMA Burst to transfer Data from the memory to the
TIM peripheral.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
BurstBaseAddress: TIM Base address from when the DMA
will starts the Data write. This parameters can be on of the
following values:
TIM_DMABASE_CR1
TIM_DMABASE_CR2
TIM_DMABASE_SMCR
TIM_DMABASE_DIER
TIM_DMABASE_SR
TIM_DMABASE_EGR
TIM_DMABASE_CCMR1
TIM_DMABASE_CCMR2
TIM_DMABASE_CCER
TIM_DMABASE_CNT
TIM_DMABASE_PSC
TIM_DMABASE_ARR
TIM_DMABASE_RCR
TIM_DMABASE_CCR1
TIM_DMABASE_CCR2
TIM_DMABASE_CCR3
TIM_DMABASE_CCR4
TIM_DMABASE_BDTR
TIM_DMABASE_DCR
BurstRequestSrc: TIM DMA Request sources. This
parameters can be on of the following values:
TIM_DMA_UPDATE: TIM update Interrupt source
TIM_DMA_CC1: TIM Capture Compare 1 DMA source
TIM_DMA_CC2: TIM Capture Compare 2 DMA source
TIM_DMA_CC3: TIM Capture Compare 3 DMA source
TIM_DMA_CC4: TIM Capture Compare 4 DMA source
TIM_DMA_COM: TIM Commutation DMA source
TIM_DMA_TRIGGER: TIM Trigger DMA source
BurstBuffer: The Buffer address.
BurstLength: DMA Burst length. This parameter can be one
value between TIM_DMABURSTLENGTH_1TRANSFER and

DocID025834 Rev 4

871/964

HAL TIM Generic Driver

UM1725
TIM_DMABURSTLENGTH_18TRANSFERS.

Return values

HAL: status

HAL_TIM_DMABurst_WriteStop
Function Name

HAL_StatusTypeDef HAL_TIM_DMABurst_WriteStop
(TIM_HandleTypeDef * htim, uint32_t BurstRequestSrc)

Function Description

Stops the TIM DMA Burst mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
BurstRequestSrc: TIM DMA Request sources to disable

Return values

HAL: status

HAL_TIM_DMABurst_ReadStart
Function Name

HAL_StatusTypeDef HAL_TIM_DMABurst_ReadStart
(TIM_HandleTypeDef * htim, uint32_t BurstBaseAddress,
uint32_t BurstRequestSrc, uint32_t * BurstBuffer, uint32_t
BurstLength)

Function Description

Configure the DMA Burst to transfer Data from the TIM peripheral
to the memory.

Parameters

872/964

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
BurstBaseAddress: TIM Base address from when the DMA
will starts the Data read. This parameters can be on of the
following values:
TIM_DMABASE_CR1
TIM_DMABASE_CR2
TIM_DMABASE_SMCR
TIM_DMABASE_DIER
TIM_DMABASE_SR
TIM_DMABASE_EGR
TIM_DMABASE_CCMR1
TIM_DMABASE_CCMR2
TIM_DMABASE_CCER
TIM_DMABASE_CNT
TIM_DMABASE_PSC
TIM_DMABASE_ARR
TIM_DMABASE_RCR
TIM_DMABASE_CCR1
TIM_DMABASE_CCR2
TIM_DMABASE_CCR3
TIM_DMABASE_CCR4
TIM_DMABASE_BDTR
TIM_DMABASE_DCR
BurstRequestSrc: TIM DMA Request sources. This
parameters can be on of the following values:
TIM_DMA_UPDATE: TIM update Interrupt source
TIM_DMA_CC1: TIM Capture Compare 1 DMA source
TIM_DMA_CC2: TIM Capture Compare 2 DMA source
DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
TIM_DMA_CC3: TIM Capture Compare 3 DMA source
TIM_DMA_CC4: TIM Capture Compare 4 DMA source
TIM_DMA_COM: TIM Commutation DMA source
TIM_DMA_TRIGGER: TIM Trigger DMA source
BurstBuffer: The Buffer address.
BurstLength: DMA Burst length. This parameter can be one
value between TIM_DMABURSTLENGTH_1TRANSFER and
TIM_DMABURSTLENGTH_18TRANSFERS.
Return values

HAL: status

HAL_TIM_DMABurst_ReadStop
Function Name

HAL_StatusTypeDef HAL_TIM_DMABurst_ReadStop
(TIM_HandleTypeDef * htim, uint32_t BurstRequestSrc)

Function Description

Stop the DMA burst reading.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
BurstRequestSrc: TIM DMA Request sources to disable.

Return values

HAL: status

HAL_TIM_GenerateEvent
Function Name

HAL_StatusTypeDef HAL_TIM_GenerateEvent
(TIM_HandleTypeDef * htim, uint32_t EventSource)

Function Description

Generate a software event.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
EventSource: specifies the event source. This parameter
can be one of the following values:
TIM_EVENTSOURCE_UPDATE: Timer update Event
source
TIM_EVENTSOURCE_CC1: Timer Capture Compare 1
Event source
TIM_EVENTSOURCE_CC2: Timer Capture Compare 2
Event source
TIM_EVENTSOURCE_CC3: Timer Capture Compare 3
Event source
TIM_EVENTSOURCE_CC4: Timer Capture Compare 4
Event source
TIM_EVENTSOURCE_COM: Timer COM event source
TIM_EVENTSOURCE_TRIGGER: Timer Trigger Event
source
TIM_EVENTSOURCE_BREAK: Timer Break event
source

Return values

HAL: status

Notes

TIM6 and TIM7 can only generate an update event.
TIM_EVENTSOURCE_COM and
TIM_EVENTSOURCE_BREAK are used only with TIM1 and
TIM8.
DocID025834 Rev 4

873/964

HAL TIM Generic Driver

UM1725

HAL_TIM_ReadCapturedValue
Function Name

uint32_t HAL_TIM_ReadCapturedValue (TIM_HandleTypeDef *
htim, uint32_t Channel)

Function Description

Read the captured value from Capture Compare unit.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channels to be enabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

Captured: value

HAL_TIM_PeriodElapsedCallback
Function Name

void HAL_TIM_PeriodElapsedCallback (TIM_HandleTypeDef *
htim)

Function Description

Period elapsed callback in non blocking mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_OC_DelayElapsedCallback
Function Name

void HAL_TIM_OC_DelayElapsedCallback
(TIM_HandleTypeDef * htim)

Function Description

Output Compare callback in non blocking mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_IC_CaptureCallback
Function Name

void HAL_TIM_IC_CaptureCallback (TIM_HandleTypeDef *
htim)

Function Description

Input Capture callback in non blocking mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_PWM_PulseFinishedCallback

874/964

Function Name

void HAL_TIM_PWM_PulseFinishedCallback
(TIM_HandleTypeDef * htim)

Function Description

PWM Pulse finished callback in non blocking mode.
DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_TriggerCallback
Function Name

void HAL_TIM_TriggerCallback (TIM_HandleTypeDef * htim)

Function Description

Hall Trigger detection callback in non blocking mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_ErrorCallback
Function Name

void HAL_TIM_ErrorCallback (TIM_HandleTypeDef * htim)

Function Description

Timer error callback in non blocking mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIM_Base_GetState
Function Name

HAL_TIM_StateTypeDef HAL_TIM_Base_GetState
(TIM_HandleTypeDef * htim)

Function Description

Return the TIM Base state.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: state

HAL_TIM_OC_GetState
Function Name

HAL_TIM_StateTypeDef HAL_TIM_OC_GetState
(TIM_HandleTypeDef * htim)

Function Description

Return the TIM OC state.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: state

HAL_TIM_PWM_GetState
Function Name

HAL_TIM_StateTypeDef HAL_TIM_PWM_GetState
(TIM_HandleTypeDef * htim)

Function Description

Return the TIM PWM state.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

DocID025834 Rev 4

875/964

HAL TIM Generic Driver
Return values

UM1725
HAL: state

HAL_TIM_IC_GetState
Function Name

HAL_TIM_StateTypeDef HAL_TIM_IC_GetState
(TIM_HandleTypeDef * htim)

Function Description

Return the TIM Input Capture state.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: state

HAL_TIM_OnePulse_GetState
Function Name

HAL_TIM_StateTypeDef HAL_TIM_OnePulse_GetState
(TIM_HandleTypeDef * htim)

Function Description

Return the TIM One Pulse Mode state.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: state

HAL_TIM_Encoder_GetState
Function Name

HAL_TIM_StateTypeDef HAL_TIM_Encoder_GetState
(TIM_HandleTypeDef * htim)

Function Description

Return the TIM Encoder Mode state.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: state

TIM_Base_SetConfig
Function Name

void TIM_Base_SetConfig (TIM_TypeDef * TIMx,
TIM_Base_InitTypeDef * Structure)

Function Description

Time Base configuration.

Parameters

TIMx: TIM peripheral
Structure: pointer on TIM Time Base required parameters

Return values

None

TIM_TI1_SetConfig
Function Name

void TIM_TI1_SetConfig (TIM_TypeDef * TIMx, uint32_t
TIM_ICPolarity, uint32_t TIM_ICSelection, uint32_t
TIM_ICFilter)

Function Description

Configure the TI1 as Input.

Parameters

876/964

TIMx: to select the TIM peripheral.
TIM_ICPolarity: : The Input Polarity. This parameter can be
one of the following values:
DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
TIM_ICPolarity_Rising
TIM_ICPolarity_Falling
TIM_ICPolarity_BothEdge
TIM_ICSelection: specifies the input to be used. This
parameter can be one of the following values:
TIM_ICSelection_DirectTI: TIM Input 1 is selected to be
connected to IC1.
TIM_ICSelection_IndirectTI: TIM Input 1 is selected to be
connected to IC2.
TIM_ICSelection_TRC: TIM Input 1 is selected to be
connected to TRC.
TIM_ICFilter: Specifies the Input Capture Filter. This
parameter must be a value between 0x00 and 0x0F.
Return values

None

Notes

TIM_ICFilter and TIM_ICPolarity are not used in INDIRECT
mode as TI2FP1 (on channel2 path) is used as the input
signal. Therefore CCMR1 must be protected against uninitialized filter and polarity values.

TIM_OC2_SetConfig
Function Name

void TIM_OC2_SetConfig (TIM_TypeDef * TIMx,
TIM_OC_InitTypeDef * OC_Config)

Function Description

Time Output Compare 2 configuration.

Parameters

TIMx: to select the TIM peripheral
OC_Config: The output configuration structure

Return values

None

TIM_DMADelayPulseCplt
Function Name

void TIM_DMADelayPulseCplt (DMA_HandleTypeDef * hdma)

Function Description

TIM DMA Delay Pulse complete callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

TIM_DMAError
Function Name

void TIM_DMAError (DMA_HandleTypeDef * hdma)

Function Description

TIM DMA error callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

DocID025834 Rev 4

877/964

HAL TIM Generic Driver

UM1725

TIM_DMACaptureCplt
Function Name

void TIM_DMACaptureCplt (DMA_HandleTypeDef * hdma)

Function Description

TIM DMA Capture complete callback.

Parameters

hdma: pointer to a DMA_HandleTypeDef structure that
contains the configuration information for the specified DMA
module.

Return values

None

TIM_CCxChannelCmd
Function Name

void TIM_CCxChannelCmd (TIM_TypeDef * TIMx, uint32_t
Channel, uint32_t ChannelState)

Function Description

Enables or disables the TIM Capture Compare Channel x.

Parameters

TIMx: to select the TIM peripheral
Channel: specifies the TIM Channel This parameter can be
one of the following values:
TIM_Channel_1: TIM Channel 1
TIM_Channel_2: TIM Channel 2
TIM_Channel_3: TIM Channel 3
TIM_Channel_4: TIM Channel 4
ChannelState: specifies the TIM Channel CCxE bit new
state. This parameter can be: TIM_CCx_ENABLE or
TIM_CCx_Disable.

Return values

None

62.3

TIM Firmware driver defines

62.3.1

TIM
TIM AOE Bit State
TIM_AUTOMATICOUTPUT_ENABLE
TIM_AUTOMATICOUTPUT_DISABLE
TIM Break Input State
TIM_BREAK_ENABLE
TIM_BREAK_DISABLE
TIM Break Polarity
TIM_BREAKPOLARITY_LOW
TIM_BREAKPOLARITY_HIGH
TIM Channel
TIM_CHANNEL_1
TIM_CHANNEL_2
TIM_CHANNEL_3
TIM_CHANNEL_4

878/964

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
TIM_CHANNEL_ALL
TIM Clear Input Polarity
TIM_CLEARINPUTPOLARITY_INVERTED

Polarity for ETRx pin

TIM_CLEARINPUTPOLARITY_NONINVERTED

Polarity for ETRx pin

TIM Clear Input Prescaler
TIM_CLEARINPUTPRESCALER_DIV1

No prescaler is used

TIM_CLEARINPUTPRESCALER_DIV2

Prescaler for External ETR pin: Capture
performed once every 2 events.

TIM_CLEARINPUTPRESCALER_DIV4

Prescaler for External ETR pin: Capture
performed once every 4 events.

TIM_CLEARINPUTPRESCALER_DIV8

Prescaler for External ETR pin: Capture
performed once every 8 events.

TIM Clear Input Source
TIM_CLEARINPUTSOURCE_ETR
TIM_CLEARINPUTSOURCE_NONE
TIM Clock Division
TIM_CLOCKDIVISION_DIV1
TIM_CLOCKDIVISION_DIV2
TIM_CLOCKDIVISION_DIV4
TIM Clock Polarity
TIM_CLOCKPOLARITY_INVERTED

Polarity for ETRx clock sources

TIM_CLOCKPOLARITY_NONINVERTED

Polarity for ETRx clock sources

TIM_CLOCKPOLARITY_RISING

Polarity for TIx clock sources

TIM_CLOCKPOLARITY_FALLING

Polarity for TIx clock sources

TIM_CLOCKPOLARITY_BOTHEDGE

Polarity for TIx clock sources

TIM Clock Prescaler
TIM_CLOCKPRESCALER_DIV1

No prescaler is used

TIM_CLOCKPRESCALER_DIV2

Prescaler for External ETR Clock: Capture performed
once every 2 events.

TIM_CLOCKPRESCALER_DIV4

Prescaler for External ETR Clock: Capture performed
once every 4 events.

TIM_CLOCKPRESCALER_DIV8

Prescaler for External ETR Clock: Capture performed
once every 8 events.

TIM Clock Source
TIM_CLOCKSOURCE_ETRMODE2
TIM_CLOCKSOURCE_INTERNAL
TIM_CLOCKSOURCE_ITR0
TIM_CLOCKSOURCE_ITR1

DocID025834 Rev 4

879/964

HAL TIM Generic Driver
TIM_CLOCKSOURCE_ITR2

UM1725

TIM_CLOCKSOURCE_ITR3
TIM_CLOCKSOURCE_TI1ED
TIM_CLOCKSOURCE_TI1
TIM_CLOCKSOURCE_TI2
TIM_CLOCKSOURCE_ETRMODE1
TIM Commutation Source
TIM_COMMUTATION_TRGI
TIM_COMMUTATION_SOFTWARE
TIM Counter Mode
TIM_COUNTERMODE_UP
TIM_COUNTERMODE_DOWN
TIM_COUNTERMODE_CENTERALIGNED1
TIM_COUNTERMODE_CENTERALIGNED2
TIM_COUNTERMODE_CENTERALIGNED3
TIM DMA Base address
TIM_DMABASE_CR1
TIM_DMABASE_CR2
TIM_DMABASE_SMCR
TIM_DMABASE_DIER
TIM_DMABASE_SR
TIM_DMABASE_EGR
TIM_DMABASE_CCMR1
TIM_DMABASE_CCMR2
TIM_DMABASE_CCER
TIM_DMABASE_CNT
TIM_DMABASE_PSC
TIM_DMABASE_ARR
TIM_DMABASE_RCR
TIM_DMABASE_CCR1
TIM_DMABASE_CCR2
TIM_DMABASE_CCR3
TIM_DMABASE_CCR4
TIM_DMABASE_BDTR
TIM_DMABASE_DCR
TIM_DMABASE_OR

880/964

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
TIM DMA Burst Length
TIM_DMABURSTLENGTH_1TRANSFER
TIM_DMABURSTLENGTH_2TRANSFERS
TIM_DMABURSTLENGTH_3TRANSFERS
TIM_DMABURSTLENGTH_4TRANSFERS
TIM_DMABURSTLENGTH_5TRANSFERS
TIM_DMABURSTLENGTH_6TRANSFERS
TIM_DMABURSTLENGTH_7TRANSFERS
TIM_DMABURSTLENGTH_8TRANSFERS
TIM_DMABURSTLENGTH_9TRANSFERS
TIM_DMABURSTLENGTH_10TRANSFERS
TIM_DMABURSTLENGTH_11TRANSFERS
TIM_DMABURSTLENGTH_12TRANSFERS
TIM_DMABURSTLENGTH_13TRANSFERS
TIM_DMABURSTLENGTH_14TRANSFERS
TIM_DMABURSTLENGTH_15TRANSFERS
TIM_DMABURSTLENGTH_16TRANSFERS
TIM_DMABURSTLENGTH_17TRANSFERS
TIM_DMABURSTLENGTH_18TRANSFERS
TIM DMA sources
TIM_DMA_UPDATE
TIM_DMA_CC1
TIM_DMA_CC2
TIM_DMA_CC3
TIM_DMA_CC4
TIM_DMA_COM
TIM_DMA_TRIGGER
TIM Encoder Mode
TIM_ENCODERMODE_TI1
TIM_ENCODERMODE_TI2
TIM_ENCODERMODE_TI12
TIM ETR Polarity
TIM_ETRPOLARITY_INVERTED

Polarity for ETR source

TIM_ETRPOLARITY_NONINVERTED

Polarity for ETR source

TIM ETR Prescaler
TIM_ETRPRESCALER_DIV1

No prescaler is used

DocID025834 Rev 4

881/964

HAL TIM Generic Driver
TIM_ETRPRESCALER_DIV2

ETR input source is divided by 2

UM1725

TIM_ETRPRESCALER_DIV4

ETR input source is divided by 4

TIM_ETRPRESCALER_DIV8

ETR input source is divided by 8

TIM Event Source
TIM_EVENTSOURCE_UPDATE
TIM_EVENTSOURCE_CC1
TIM_EVENTSOURCE_CC2
TIM_EVENTSOURCE_CC3
TIM_EVENTSOURCE_CC4
TIM_EVENTSOURCE_COM
TIM_EVENTSOURCE_TRIGGER
TIM_EVENTSOURCE_BREAK
TIM Exported Macros
__HAL_TIM_RESET_HANDLE_ST
ATE

Description:
Reset TIM handle state.
Parameters:
__HANDLE__: TIM handle
Return value:
None

__HAL_TIM_ENABLE

Description:
Enable the TIM peripheral.
Parameters:
__HANDLE__: TIM handle
Return value:
None

__HAL_TIM_MOE_ENABLE

Description:
Enable the TIM main Output.
Parameters:
__HANDLE__: TIM handle
Return value:
None

__HAL_TIM_DISABLE

Description:
Disable the TIM peripheral.
Parameters:
__HANDLE__: TIM handle

882/964

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
Return value:
None
__HAL_TIM_MOE_DISABLE

Description:
Disable the TIM main Output.
Parameters:
__HANDLE__: TIM handle
Return value:
None

__HAL_TIM_ENABLE_IT
__HAL_TIM_ENABLE_DMA
__HAL_TIM_DISABLE_IT
__HAL_TIM_DISABLE_DMA
__HAL_TIM_GET_FLAG
__HAL_TIM_CLEAR_FLAG
__HAL_TIM_GET_IT_SOURCE
__HAL_TIM_CLEAR_IT
__HAL_TIM_IS_TIM_COUNTING_
DOWN
__HAL_TIM_SET_PRESCALER
TIM_SET_ICPRESCALERVALUE
TIM_RESET_ICPRESCALERVAL
UE
TIM_SET_CAPTUREPOLARITY
TIM_RESET_CAPTUREPOLARIT
Y
__HAL_TIM_SET_COMPARE

Description:
Sets the TIM Capture Compare Register value
on runtime without calling another time
ConfigChannel function.
Parameters:
__HANDLE__: TIM handle.
__CHANNEL__: : TIM Channels to be
configured. This parameter can be one of the
following values:
TIM_CHANNEL_1: TIM Channel 1
selected
TIM_CHANNEL_2: TIM Channel 2
selected
TIM_CHANNEL_3: TIM Channel 3
selected
TIM_CHANNEL_4: TIM Channel 4
selected

DocID025834 Rev 4

883/964

HAL TIM Generic Driver

UM1725
__COMPARE__: specifies the Capture
Compare register new value.
Return value:
None

__HAL_TIM_GET_COMPARE

Description:
Gets the TIM Capture Compare Register value
on runtime.
Parameters:
__HANDLE__: TIM handle.
__CHANNEL__: : TIM Channel associated with
the capture compare register This parameter
can be one of the following values:
TIM_CHANNEL_1: get capture/compare 1
register value
TIM_CHANNEL_2: get capture/compare 2
register value
TIM_CHANNEL_3: get capture/compare 3
register value
TIM_CHANNEL_4: get capture/compare 4
register value
Return value:
None

__HAL_TIM_SET_COUNTER

Description:
Sets the TIM Counter Register value on
runtime.
Parameters:
__HANDLE__: TIM handle.
__COUNTER__: specifies the Counter register
new value.
Return value:
None

__HAL_TIM_GET_COUNTER

Description:
Gets the TIM Counter Register value on
runtime.
Parameters:
__HANDLE__: TIM handle.
Return value:
None

__HAL_TIM_SET_AUTORELOAD

Description:
Sets the TIM Autoreload Register value on
runtime without calling another time any Init
function.

884/964

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
Parameters:
__HANDLE__: TIM handle.
__AUTORELOAD__: specifies the Counter
register new value.
Return value:
None
__HAL_TIM_GET_AUTORELOAD

Description:
Gets the TIM Autoreload Register value on
runtime.
Parameters:
__HANDLE__: TIM handle.
Return value:
None
Description:

__HAL_TIM_SET_CLOCK
DIVISION

Sets the TIM Clock Division value on runtime
without calling another time any Init function.
Parameters:
__HANDLE__: TIM handle.
__CKD__: specifies the clock division value.
This parameter can be one of the following
value:
TIM_CLOCKDIVISION_DIV1
TIM_CLOCKDIVISION_DIV2
TIM_CLOCKDIVISION_DIV4
Return value:
None
Description:

__HAL_TIM_GET_CLOCK
DIVISION

Gets the TIM Clock Division value on runtime.
Parameters:
__HANDLE__: TIM handle.
Return value:
None

__HAL_TIM_SET_ICPRESCALER

Description:
Sets the TIM Input Capture prescaler on
runtime without calling another time
Parameters:
__HANDLE__: TIM handle.
__CHANNEL__: : TIM Channels to be
configured. This parameter can be one of the
following values:
TIM_CHANNEL_1: TIM Channel 1

DocID025834 Rev 4

885/964

HAL TIM Generic Driver

UM1725
selected
TIM_CHANNEL_2: TIM Channel 2
selected
TIM_CHANNEL_3: TIM Channel 3
selected
TIM_CHANNEL_4: TIM Channel 4
selected
__ICPSC__: specifies the Input Capture4
prescaler new value. This parameter can be
one of the following values:
TIM_ICPSC_DIV1: no prescaler
TIM_ICPSC_DIV2: capture is done once
every 2 events
TIM_ICPSC_DIV4: capture is done once
every 4 events
TIM_ICPSC_DIV8: capture is done once
every 8 events
Return value:
None

__HAL_TIM_GET_ICPRESCALER

Description:
Gets the TIM Input Capture prescaler on
runtime.
Parameters:
__HANDLE__: TIM handle.
__CHANNEL__: : TIM Channels to be
configured. This parameter can be one of the
following values:
TIM_CHANNEL_1: get input capture 1
prescaler value
TIM_CHANNEL_2: get input capture 2
prescaler value
TIM_CHANNEL_3: get input capture 3
prescaler value
TIM_CHANNEL_4: get input capture 4
prescaler value
Return value:
None

__HAL_TIM_URS_ENABLE

Description:
Set the Update Request Source (URS) bit of the
TIMx_CR1 register.
Parameters:
__HANDLE__: TIM handle.
Return value:
None
Notes:
When the USR bit of the TIMx_CR1 register is

886/964

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
set, only counter overflow/underflow generates
an update interrupt or DMA request (if enabled)
Description:

__HAL_TIM_URS_DISABLE

Reset the Update Request Source (URS) bit of
the TIMx_CR1 register.
Parameters:
__HANDLE__: TIM handle.
Return value:
None
Notes:
When the USR bit of the TIMx_CR1 register is
reset, any of the following events generate an
update interrupt or DMA request (if enabled): _
Counter overflow/underflow _ Setting the UG bit
_ Update generation through the slave mode
controller
__HAL_TIM_SET_CAPTURE
POLARITY

Description:
Sets the TIM Capture x input polarity on
runtime.
Parameters:
__HANDLE__: TIM handle.
__CHANNEL__: TIM Channels to be
configured. This parameter can be one of the
following values:
TIM_CHANNEL_1: TIM Channel 1
selected
TIM_CHANNEL_2: TIM Channel 2
selected
TIM_CHANNEL_3: TIM Channel 3
selected
TIM_CHANNEL_4: TIM Channel 4
selected
__POLARITY__: Polarity for TIx source
TIM_INPUTCHANNELPOLARITY_RISING
: Rising Edge
TIM_INPUTCHANNELPOLARITY_FALLIN
G: Falling Edge
TIM_INPUTCHANNELPOLARITY_BOTHE
DGE: Rising and Falling Edge
Return value:
None
Notes:
The polarity
TIM_INPUTCHANNELPOLARITY_BOTHEDGE
is not authorized for TIM Channel 4.

DocID025834 Rev 4

887/964

HAL TIM Generic Driver
TIM Flag definition

UM1725

TIM_FLAG_UPDATE
TIM_FLAG_CC1
TIM_FLAG_CC2
TIM_FLAG_CC3
TIM_FLAG_CC4
TIM_FLAG_COM
TIM_FLAG_TRIGGER
TIM_FLAG_BREAK
TIM_FLAG_CC1OF
TIM_FLAG_CC2OF
TIM_FLAG_CC3OF
TIM_FLAG_CC4OF
TIM Input Capture Polarity
TIM_ICPOLARITY_RISING
TIM_ICPOLARITY_FALLING
TIM_ICPOLARITY_BOTHEDGE
TIM Input Capture Prescaler
TIM_ICPSC_DIV1

Capture performed each time an edge is detected on the capture
input

TIM_ICPSC_DIV2

Capture performed once every 2 events

TIM_ICPSC_DIV4

Capture performed once every 4 events

TIM_ICPSC_DIV8

Capture performed once every 8 events

TIM Input Capture Selection
TIM_ICSELECTION_DIRECTTI

TIM Input 1, 2, 3 or 4 is selected to be connected to
IC1, IC2, IC3 or IC4, respectively

TIM_ICSELECTION_INDIRECTTI

TIM Input 1, 2, 3 or 4 is selected to be connected to
IC2, IC1, IC4 or IC3, respectively

TIM_ICSELECTION_TRC

TIM Input 1, 2, 3 or 4 is selected to be connected to
TRC

TIM Input Channel Polarity
TIM_INPUTCHANNELPOLARITY_RISING

Polarity for TIx source

TIM_INPUTCHANNELPOLARITY_FALLING

Polarity for TIx source

TIM_INPUTCHANNELPOLARITY_BOTHEDGE

Polarity for TIx source

TIM Interrupt definition
TIM_IT_UPDATE
TIM_IT_CC1
TIM_IT_CC2
888/964

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
TIM_IT_CC3
TIM_IT_CC4
TIM_IT_COM
TIM_IT_TRIGGER
TIM_IT_BREAK
TIM Private macros to check input parameters
IS_TIM_COUNTER_MODE
IS_TIM_CLOCKDIVISION_DIV
IS_TIM_PWM_MODE
IS_TIM_OC_MODE
IS_TIM_FAST_STATE
IS_TIM_OC_POLARITY
IS_TIM_OCN_POLARITY
IS_TIM_OCIDLE_STATE
IS_TIM_OCNIDLE_STATE
IS_TIM_CHANNELS
IS_TIM_OPM_CHANNELS
IS_TIM_COMPLEMENTARY_CHANNELS
IS_TIM_IC_POLARITY
IS_TIM_IC_SELECTION
IS_TIM_IC_PRESCALER
IS_TIM_OPM_MODE
IS_TIM_DMA_SOURCE
IS_TIM_ENCODER_MODE
IS_TIM_EVENT_SOURCE
IS_TIM_CLOCKSOURCE
IS_TIM_CLOCKPOLARITY
IS_TIM_CLOCKPRESCALER
IS_TIM_CLOCKFILTER
IS_TIM_CLEARINPUT_SOURCE
IS_TIM_CLEARINPUT_POLARITY
IS_TIM_CLEARINPUT_PRESCALER
IS_TIM_CLEARINPUT_FILTER
IS_TIM_OSSR_STATE
IS_TIM_OSSI_STATE
IS_TIM_LOCK_LEVEL

DocID025834 Rev 4

889/964

HAL TIM Generic Driver
IS_TIM_BREAK_STATE

UM1725

IS_TIM_BREAK_POLARITY
IS_TIM_AUTOMATIC_OUTPUT_STATE
IS_TIM_TRGO_SOURCE
IS_TIM_SLAVE_MODE
IS_TIM_MSM_STATE
IS_TIM_TRIGGER_SELECTION
IS_TIM_INTERNAL_TRIGGEREVENT_SELECTION
IS_TIM_TRIGGERPOLARITY
IS_TIM_TRIGGERPRESCALER
IS_TIM_TRIGGERFILTER
IS_TIM_TI1SELECTION
IS_TIM_DMA_BASE
IS_TIM_DMA_LENGTH
IS_TIM_IC_FILTER
TIM Lock level
TIM_LOCKLEVEL_OFF
TIM_LOCKLEVEL_1
TIM_LOCKLEVEL_2
TIM_LOCKLEVEL_3
TIM Mask Definition
TIM_CCER_CCxE_MASK
TIM_CCER_CCxNE_MASK
TIM Master Mode Selection
TIM_TRGO_RESET
TIM_TRGO_ENABLE
TIM_TRGO_UPDATE
TIM_TRGO_OC1
TIM_TRGO_OC1REF
TIM_TRGO_OC2REF
TIM_TRGO_OC3REF
TIM_TRGO_OC4REF
TIM Master Slave Mode
TIM_MASTERSLAVEMODE_ENABLE
TIM_MASTERSLAVEMODE_DISABLE

890/964

DocID025834 Rev 4

UM1725

HAL TIM Generic Driver
TIM One Pulse Mode
TIM_OPMODE_SINGLE
TIM_OPMODE_REPETITIVE
TIM OSSI OffState Selection for Idle mode state
TIM_OSSI_ENABLE
TIM_OSSI_DISABLE
TIM OSSR OffState Selection for Run mode state
TIM_OSSR_ENABLE
TIM_OSSR_DISABLE
TIM Output Compare and PWM modes
TIM_OCMODE_TIMING
TIM_OCMODE_ACTIVE
TIM_OCMODE_INACTIVE
TIM_OCMODE_TOGGLE
TIM_OCMODE_PWM1
TIM_OCMODE_PWM2
TIM_OCMODE_FORCED_ACTIVE
TIM_OCMODE_FORCED_INACTIVE
TIM Output Compare Idle State
TIM_OCIDLESTATE_SET
TIM_OCIDLESTATE_RESET
TIM Output Compare N Idle State
TIM_OCNIDLESTATE_SET
TIM_OCNIDLESTATE_RESET
TIM Output CompareN Polarity
TIM_OCNPOLARITY_HIGH
TIM_OCNPOLARITY_LOW
TIM Output Compare Polarity
TIM_OCPOLARITY_HIGH
TIM_OCPOLARITY_LOW
TIM Output Fast State
TIM_OCFAST_DISABLE
TIM_OCFAST_ENABLE
TIM Slave Mode
TIM_SLAVEMODE_DISABLE
TIM_SLAVEMODE_RESET

DocID025834 Rev 4

891/964

HAL TIM Generic Driver
TIM_SLAVEMODE_GATED

UM1725

TIM_SLAVEMODE_TRIGGER
TIM_SLAVEMODE_EXTERNAL1
TIM TI1 Selection
TIM_TI1SELECTION_CH1
TIM_TI1SELECTION_XORCOMBINATION
TIM Trigger Polarity
TIM_TRIGGERPOLARITY_INVERTED

Polarity for ETRx trigger sources

TIM_TRIGGERPOLARITY_NONINVERTED

Polarity for ETRx trigger sources

TIM_TRIGGERPOLARITY_RISING

Polarity for TIxFPx or TI1_ED trigger
sources

TIM_TRIGGERPOLARITY_FALLING

Polarity for TIxFPx or TI1_ED trigger
sources

TIM_TRIGGERPOLARITY_BOTHEDGE

Polarity for TIxFPx or TI1_ED trigger
sources

TIM Trigger Prescaler
TIM_TRIGGERPRESCALER_DIV1

No prescaler is used

TIM_TRIGGERPRESCALER_DIV2

Prescaler for External ETR Trigger: Capture
performed once every 2 events.

TIM_TRIGGERPRESCALER_DIV4

Prescaler for External ETR Trigger: Capture
performed once every 4 events.

TIM_TRIGGERPRESCALER_DIV8

Prescaler for External ETR Trigger: Capture
performed once every 8 events.

TIM Trigger Selection
TIM_TS_ITR0
TIM_TS_ITR1
TIM_TS_ITR2
TIM_TS_ITR3
TIM_TS_TI1F_ED
TIM_TS_TI1FP1
TIM_TS_TI2FP2
TIM_TS_ETRF
TIM_TS_NONE

892/964

DocID025834 Rev 4

UM1725

HAL TIM Extension Driver

63

HAL TIM Extension Driver

63.1

TIMEx Firmware driver registers structures

63.1.1

TIM_HallSensor_InitTypeDef
Data Fields
uint32_t IC1Polarity
uint32_t IC1Prescaler
uint32_t IC1Filter
uint32_t Commutation_Delay

Field Documentation
uint32_t TIM_HallSensor_InitTypeDef::IC1Polarity
Specifies the active edge of the input signal. This parameter can be a value of
TIM_Input_Capture_Polarity
uint32_t TIM_HallSensor_InitTypeDef::IC1Prescaler
Specifies the Input Capture Prescaler. This parameter can be a value of
TIM_Input_Capture_Prescaler
uint32_t TIM_HallSensor_InitTypeDef::IC1Filter
Specifies the input capture filter. This parameter can be a number between Min_Data
= 0x0 and Max_Data = 0xF
uint32_t TIM_HallSensor_InitTypeDef::Commutation_Delay
Specifies the pulse value to be loaded into the Capture Compare Register. This
parameter can be a number between Min_Data = 0x0000U and Max_Data = 0xFFFFU

63.1.2

TIM_MasterConfigTypeDef
Data Fields
uint32_t MasterOutputTrigger
uint32_t MasterSlaveMode

Field Documentation
uint32_t TIM_MasterConfigTypeDef::MasterOutputTrigger
Trigger output (TRGO) selection. This parameter can be a value of
TIM_Master_Mode_Selection
uint32_t TIM_MasterConfigTypeDef::MasterSlaveMode
Master/slave mode selection. This parameter can be a value of
TIM_Master_Slave_Mode

DocID025834 Rev 4

893/964

HAL TIM Extension Driver

63.1.3

UM1725

TIM_BreakDeadTimeConfigTypeDef
Data Fields
uint32_t OffStateRunMode
uint32_t OffStateIDLEMode
uint32_t LockLevel
uint32_t DeadTime
uint32_t BreakState
uint32_t BreakPolarity
uint32_t AutomaticOutput

Field Documentation
uint32_t TIM_BreakDeadTimeConfigTypeDef::OffStateRunMode
TIM off state in run mode. This parameter can be a value of
TIM_OSSR_Off_State_Selection_for_Run_mode_state
uint32_t TIM_BreakDeadTimeConfigTypeDef::OffStateIDLEMode
TIM off state in IDLE mode. This parameter can be a value of
TIM_OSSI_Off_State_Selection_for_Idle_mode_state
uint32_t TIM_BreakDeadTimeConfigTypeDef::LockLevel
TIM Lock level. This parameter can be a value of TIM_Lock_level
uint32_t TIM_BreakDeadTimeConfigTypeDef::DeadTime
TIM dead Time. This parameter can be a number between Min_Data = 0x00 and
Max_Data = 0xFF
uint32_t TIM_BreakDeadTimeConfigTypeDef::BreakState
TIM Break State. This parameter can be a value of
TIM_Break_Input_enable_disable
uint32_t TIM_BreakDeadTimeConfigTypeDef::BreakPolarity
TIM Break input polarity. This parameter can be a value of TIM_Break_Polarity
uint32_t TIM_BreakDeadTimeConfigTypeDef::AutomaticOutput
TIM Automatic Output Enable state. This parameter can be a value of
TIM_AOE_Bit_Set_Reset

63.2

TIMEx Firmware driver API description

63.2.1

TIMER Extended features
The Timer Extension features include:
1.

2.
3.
4.

894/964

Complementary outputs with programmable dead-time for :
Input Capture
Output Compare
PWM generation (Edge and Center-aligned Mode)
One-pulse mode output
Synchronization circuit to control the timer with external signals and to interconnect
several timers together.
Break input to put the timer output signals in reset state or in a known state.
Supports incremental (quadrature) encoder and hall-sensor circuitry for positioning
purposes
DocID025834 Rev 4

UM1725

63.2.2

HAL TIM Extension Driver

How to use this driver
1.

2.

3.

4.

5.

63.2.3

Initialize the TIM low level resources by implementing the following functions
depending from feature used :
Complementary Output Compare : HAL_TIM_OC_MspInit()
Complementary PWM generation : HAL_TIM_PWM_MspInit()
Complementary One-pulse mode output : HAL_TIM_OnePulse_MspInit()
Hall Sensor output : HAL_TIM_HallSensor_MspInit()
Initialize the TIM low level resources :
a.
Enable the TIM interface clock using __TIMx_CLK_ENABLE();
b.
TIM pins configuration
Enable the clock for the TIM GPIOs using the following function:
__GPIOx_CLK_ENABLE();
Configure these TIM pins in Alternate function mode using
HAL_GPIO_Init();
The external Clock can be configured, if needed (the default clock is the internal clock
from the APBx), using the following function: HAL_TIM_ConfigClockSource, the clock
configuration should be done before any start function.
Configure the TIM in the desired functioning mode using one of the initialization
function of this driver:
HAL_TIMEx_HallSensor_Init and HAL_TIMEx_ConfigCommutationEvent: to use
the Timer Hall Sensor Interface and the commutation event with the
corresponding Interrupt and DMA request if needed (Note that One Timer is used
to interface with the Hall sensor Interface and another Timer should be used to
use the commutation event).
Activate the TIM peripheral using one of the start functions:
Complementary Output Compare : HAL_TIMEx_OCN_Start(),
HAL_TIMEx_OCN_Start_DMA(), HAL_TIMEx_OC_Start_IT()
Complementary PWM generation : HAL_TIMEx_PWMN_Start(),
HAL_TIMEx_PWMN_Start_DMA(), HAL_TIMEx_PWMN_Start_IT()
Complementary One-pulse mode output : HAL_TIMEx_OnePulseN_Start(),
HAL_TIMEx_OnePulseN_Start_IT()
Hall Sensor output : HAL_TIMEx_HallSensor_Start(),
HAL_TIMEx_HallSensor_Start_DMA(), HAL_TIMEx_HallSensor_Start_IT().

Timer Hall Sensor functions
This section provides functions allowing to:
Initialize and configure TIM HAL Sensor.
De-initialize TIM HAL Sensor.
Start the Hall Sensor Interface.
Stop the Hall Sensor Interface.
Start the Hall Sensor Interface and enable interrupts.
Stop the Hall Sensor Interface and disable interrupts.
Start the Hall Sensor Interface and enable DMA transfers.
Stop the Hall Sensor Interface and disable DMA transfers.
This section contains the following APIs:
HAL_TIMEx_HallSensor_Init()
HAL_TIMEx_HallSensor_DeInit()
HAL_TIMEx_HallSensor_MspInit()
HAL_TIMEx_HallSensor_MspDeInit()
HAL_TIMEx_HallSensor_Start()
DocID025834 Rev 4

895/964

HAL TIM Extension Driver

UM1725

HAL_TIMEx_HallSensor_Stop()
HAL_TIMEx_HallSensor_Start_IT()
HAL_TIMEx_HallSensor_Stop_IT()
HAL_TIMEx_HallSensor_Start_DMA()
HAL_TIMEx_HallSensor_Stop_DMA()

63.2.4

Timer Complementary Output Compare functions
This section provides functions allowing to:
Start the Complementary Output Compare/PWM.
Stop the Complementary Output Compare/PWM.
Start the Complementary Output Compare/PWM and enable interrupts.
Stop the Complementary Output Compare/PWM and disable interrupts.
Start the Complementary Output Compare/PWM and enable DMA transfers.
Stop the Complementary Output Compare/PWM and disable DMA transfers.
This section contains the following APIs:
HAL_TIMEx_OCN_Start()
HAL_TIMEx_OCN_Stop()
HAL_TIMEx_OCN_Start_IT()
HAL_TIMEx_OCN_Stop_IT()
HAL_TIMEx_OCN_Start_DMA()
HAL_TIMEx_OCN_Stop_DMA()

63.2.5

Timer Complementary PWM functions
This section provides functions allowing to:
Start the Complementary PWM.
Stop the Complementary PWM.
Start the Complementary PWM and enable interrupts.
Stop the Complementary PWM and disable interrupts.
Start the Complementary PWM and enable DMA transfers.
Stop the Complementary PWM and disable DMA transfers.
Start the Complementary Input Capture measurement.
Stop the Complementary Input Capture.
Start the Complementary Input Capture and enable interrupts.
Stop the Complementary Input Capture and disable interrupts.
Start the Complementary Input Capture and enable DMA transfers.
Stop the Complementary Input Capture and disable DMA transfers.
Start the Complementary One Pulse generation.
Stop the Complementary One Pulse.
Start the Complementary One Pulse and enable interrupts.
Stop the Complementary One Pulse and disable interrupts.
This section contains the following APIs:
HAL_TIMEx_PWMN_Start()
HAL_TIMEx_PWMN_Stop()
HAL_TIMEx_PWMN_Start_IT()
HAL_TIMEx_PWMN_Stop_IT()
HAL_TIMEx_PWMN_Start_DMA()
HAL_TIMEx_PWMN_Stop_DMA()

896/964

DocID025834 Rev 4

UM1725

63.2.6

HAL TIM Extension Driver

Timer Complementary One Pulse functions
This section provides functions allowing to:
Start the Complementary One Pulse generation.
Stop the Complementary One Pulse.
Start the Complementary One Pulse and enable interrupts.
Stop the Complementary One Pulse and disable interrupts.
This section contains the following APIs:
HAL_TIMEx_OnePulseN_Start()
HAL_TIMEx_OnePulseN_Stop()
HAL_TIMEx_OnePulseN_Start_IT()
HAL_TIMEx_OnePulseN_Stop_IT()

63.2.7

Peripheral Control functions
This section provides functions allowing to:
Configure The Input Output channels for OC, PWM, IC or One Pulse mode.
Configure External Clock source.
Configure Complementary channels, break features and dead time.
Configure Master and the Slave synchronization.
Configure the commutation event in case of use of the Hall sensor interface.
Configure the DMA Burst Mode.
This section contains the following APIs:
HAL_TIMEx_ConfigCommutationEvent()
HAL_TIMEx_ConfigCommutationEvent_IT()
HAL_TIMEx_ConfigCommutationEvent_DMA()
HAL_TIMEx_MasterConfigSynchronization()
HAL_TIMEx_ConfigBreakDeadTime()
HAL_TIMEx_RemapConfig()

63.2.8

Extension Callbacks functions
This section provides Extension TIM callback functions:
Timer Commutation callback
Timer Break callback
This section contains the following APIs:
HAL_TIMEx_CommutationCallback()
HAL_TIMEx_BreakCallback()
TIMEx_DMACommutationCplt()

63.2.9

Extension Peripheral State functions
This subsection permits to get in run-time the status of the peripheral and the data flow.
This section contains the following APIs:
HAL_TIMEx_HallSensor_GetState()

DocID025834 Rev 4

897/964

HAL TIM Extension Driver

63.2.10

UM1725

Detailed description of functions
HAL_TIMEx_HallSensor_Init
Function Name

HAL_StatusTypeDef HAL_TIMEx_HallSensor_Init
(TIM_HandleTypeDef * htim, TIM_HallSensor_InitTypeDef *
sConfig)

Function Description

Initializes the TIM Hall Sensor Interface and create the associated
handle.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
sConfig: TIM Hall Sensor configuration structure

Return values

HAL: status

HAL_TIMEx_HallSensor_DeInit
Function Name

HAL_StatusTypeDef HAL_TIMEx_HallSensor_DeInit
(TIM_HandleTypeDef * htim)

Function Description

DeInitializes the TIM Hall Sensor interface.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIMEx_HallSensor_MspInit
Function Name

void HAL_TIMEx_HallSensor_MspInit (TIM_HandleTypeDef *
htim)

Function Description

Initializes the TIM Hall Sensor MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIMEx_HallSensor_MspDeInit
Function Name

void HAL_TIMEx_HallSensor_MspDeInit (TIM_HandleTypeDef
* htim)

Function Description

DeInitializes TIM Hall Sensor MSP.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIMEx_HallSensor_Start
Function Name

HAL_StatusTypeDef HAL_TIMEx_HallSensor_Start
(TIM_HandleTypeDef * htim)

Function Description

Starts the TIM Hall Sensor Interface.

Parameters
898/964

htim: pointer to a TIM_HandleTypeDef structure that
DocID025834 Rev 4

UM1725

HAL TIM Extension Driver
contains the configuration information for TIM module.
Return values

HAL: status

HAL_TIMEx_HallSensor_Stop
Function Name

HAL_StatusTypeDef HAL_TIMEx_HallSensor_Stop
(TIM_HandleTypeDef * htim)

Function Description

Stops the TIM Hall sensor Interface.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIMEx_HallSensor_Start_IT
Function Name

HAL_StatusTypeDef HAL_TIMEx_HallSensor_Start_IT
(TIM_HandleTypeDef * htim)

Function Description

Starts the TIM Hall Sensor Interface in interrupt mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIMEx_HallSensor_Stop_IT
Function Name

HAL_StatusTypeDef HAL_TIMEx_HallSensor_Stop_IT
(TIM_HandleTypeDef * htim)

Function Description

Stops the TIM Hall Sensor Interface in interrupt mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIMEx_HallSensor_Start_DMA
Function Name

HAL_StatusTypeDef HAL_TIMEx_HallSensor_Start_DMA
(TIM_HandleTypeDef * htim, uint32_t * pData, uint16_t Length)

Function Description

Starts the TIM Hall Sensor Interface in DMA mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
pData: The destination Buffer address.
Length: The length of data to be transferred from TIM
peripheral to memory.

Return values

HAL: status

HAL_TIMEx_HallSensor_Stop_DMA
Function Name

HAL_StatusTypeDef HAL_TIMEx_HallSensor_Stop_DMA
(TIM_HandleTypeDef * htim)

DocID025834 Rev 4

899/964

HAL TIM Extension Driver
Function Description

UM1725
Stops the TIM Hall Sensor Interface in DMA mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: status

HAL_TIMEx_OCN_Start
Function Name

HAL_StatusTypeDef HAL_TIMEx_OCN_Start
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Starts the TIM Output Compare signal generation on the
complementary output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be enabled. This parameter can be
one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIMEx_OCN_Stop
Function Name

HAL_StatusTypeDef HAL_TIMEx_OCN_Stop
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM Output Compare signal generation on the
complementary output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIMEx_OCN_Start_IT
Function Name

HAL_StatusTypeDef HAL_TIMEx_OCN_Start_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Starts the TIM Output Compare signal generation in interrupt
mode on the complementary output.

Parameters

900/964

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be enabled. This parameter can be
one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
DocID025834 Rev 4

UM1725

HAL TIM Extension Driver
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected
Return values

HAL: status

HAL_TIMEx_OCN_Stop_IT
Function Name

HAL_StatusTypeDef HAL_TIMEx_OCN_Stop_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM Output Compare signal generation in interrupt mode
on the complementary output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIMEx_OCN_Start_DMA
Function Name

HAL_StatusTypeDef HAL_TIMEx_OCN_Start_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel, uint32_t *
pData, uint16_t Length)

Function Description

Starts the TIM Output Compare signal generation in DMA mode on
the complementary output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be enabled. This parameter can be
one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected
pData: The source Buffer address.
Length: The length of data to be transferred from memory to
TIM peripheral

Return values

HAL: status

HAL_TIMEx_OCN_Stop_DMA
Function Name

HAL_StatusTypeDef HAL_TIMEx_OCN_Stop_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM Output Compare signal generation in DMA mode on
the complementary output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be disabled. This parameter can
DocID025834 Rev 4

901/964

HAL TIM Extension Driver

UM1725
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIMEx_PWMN_Start
Function Name

HAL_StatusTypeDef HAL_TIMEx_PWMN_Start
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Starts the PWM signal generation on the complementary output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be enabled. This parameter can be
one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIMEx_PWMN_Stop
Function Name

HAL_StatusTypeDef HAL_TIMEx_PWMN_Stop
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the PWM signal generation on the complementary output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIMEx_PWMN_Start_IT
Function Name

HAL_StatusTypeDef HAL_TIMEx_PWMN_Start_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Starts the PWM signal generation in interrupt mode on the
complementary output.

Parameters

902/964

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
DocID025834 Rev 4

UM1725

HAL TIM Extension Driver
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected
Return values

HAL: status

HAL_TIMEx_PWMN_Stop_IT
Function Name

HAL_StatusTypeDef HAL_TIMEx_PWMN_Stop_IT
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the PWM signal generation in interrupt mode on the
complementary output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be disabled. This parameter can
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIMEx_PWMN_Start_DMA
Function Name

HAL_StatusTypeDef HAL_TIMEx_PWMN_Start_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel, uint32_t *
pData, uint16_t Length)

Function Description

Starts the TIM PWM signal generation in DMA mode on the
complementary output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be enabled. This parameter can be
one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected
pData: The source Buffer address.
Length: The length of data to be transferred from memory to
TIM peripheral

Return values

HAL: status

HAL_TIMEx_PWMN_Stop_DMA
Function Name

HAL_StatusTypeDef HAL_TIMEx_PWMN_Stop_DMA
(TIM_HandleTypeDef * htim, uint32_t Channel)

Function Description

Stops the TIM PWM signal generation in DMA mode on the
complementary output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
Channel: TIM Channel to be disabled. This parameter can
DocID025834 Rev 4

903/964

HAL TIM Extension Driver

UM1725
be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected
TIM_CHANNEL_3: TIM Channel 3 selected
TIM_CHANNEL_4: TIM Channel 4 selected

Return values

HAL: status

HAL_TIMEx_OnePulseN_Start
Function Name

HAL_StatusTypeDef HAL_TIMEx_OnePulseN_Start
(TIM_HandleTypeDef * htim, uint32_t OutputChannel)

Function Description

Starts the TIM One Pulse signal generation on the complementary
output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
OutputChannel: TIM Channel to be enabled. This parameter
can be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected

Return values

HAL: status

HAL_TIMEx_OnePulseN_Stop
Function Name

HAL_StatusTypeDef HAL_TIMEx_OnePulseN_Stop
(TIM_HandleTypeDef * htim, uint32_t OutputChannel)

Function Description

Stops the TIM One Pulse signal generation on the complementary
output.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
OutputChannel: TIM Channel to be disabled. This
parameter can be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected

Return values

HAL: status

HAL_TIMEx_OnePulseN_Start_IT

904/964

Function Name

HAL_StatusTypeDef HAL_TIMEx_OnePulseN_Start_IT
(TIM_HandleTypeDef * htim, uint32_t OutputChannel)

Function Description

Starts the TIM One Pulse signal generation in interrupt mode on
the complementary channel.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
OutputChannel: TIM Channel to be enabled. This parameter
can be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected

Return values

HAL: status
DocID025834 Rev 4

UM1725

HAL TIM Extension Driver

HAL_TIMEx_OnePulseN_Stop_IT
Function Name

HAL_StatusTypeDef HAL_TIMEx_OnePulseN_Stop_IT
(TIM_HandleTypeDef * htim, uint32_t OutputChannel)

Function Description

Stops the TIM One Pulse signal generation in interrupt mode on
the complementary channel.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
OutputChannel: TIM Channel to be disabled. This
parameter can be one of the following values:
TIM_CHANNEL_1: TIM Channel 1 selected
TIM_CHANNEL_2: TIM Channel 2 selected

Return values

HAL: status

HAL_TIMEx_ConfigCommutationEvent
Function Name

HAL_StatusTypeDef HAL_TIMEx_ConfigCommutationEvent
(TIM_HandleTypeDef * htim, uint32_t InputTrigger, uint32_t
CommutationSource)

Function Description

Configure the TIM commutation event sequence.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
InputTrigger: the Internal trigger corresponding to the Timer
Interfacing with the Hall sensor. This parameter can be one of
the following values:
TIM_TS_ITR0: Internal trigger 0 selected
TIM_TS_ITR1: Internal trigger 1 selected
TIM_TS_ITR2: Internal trigger 2 selected
TIM_TS_ITR3: Internal trigger 3 selected
TIM_TS_NONE: No trigger is needed
CommutationSource: the Commutation Event source. This
parameter can be one of the following values:
TIM_COMMUTATION_TRGI: Commutation source is the
TRGI of the Interface Timer
TIM_COMMUTATION_SOFTWARE: Commutation
source is set by software using the COMG bit

Return values

HAL: status

Notes

This function is mandatory to use the commutation event in
order to update the configuration at each commutation
detection on the TRGI input of the Timer, the typical use of
this feature is with the use of another Timer(interface Timer)
configured in Hall sensor interface, this interface Timer will
generate the commutation at its TRGO output (connected to
Timer used in this function) each time the TI1 of the Interface
Timer detect a commutation at its input TI1.

HAL_TIMEx_ConfigCommutationEvent_IT
Function Name

HAL_StatusTypeDef
HAL_TIMEx_ConfigCommutationEvent_IT
(TIM_HandleTypeDef * htim, uint32_t InputTrigger, uint32_t
DocID025834 Rev 4

905/964

HAL TIM Extension Driver

UM1725
CommutationSource)

Function Description

Configure the TIM commutation event sequence with interrupt.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
InputTrigger: the Internal trigger corresponding to the Timer
Interfacing with the Hall sensor. This parameter can be one of
the following values:
TIM_TS_ITR0: Internal trigger 0 selected
TIM_TS_ITR1: Internal trigger 1 selected
TIM_TS_ITR2: Internal trigger 2 selected
TIM_TS_ITR3: Internal trigger 3 selected
TIM_TS_NONE: No trigger is needed
CommutationSource: the Commutation Event source. This
parameter can be one of the following values:
TIM_COMMUTATION_TRGI: Commutation source is the
TRGI of the Interface Timer
TIM_COMMUTATION_SOFTWARE: Commutation
source is set by software using the COMG bit

Return values

HAL: status

Notes

This function is mandatory to use the commutation event in
order to update the configuration at each commutation
detection on the TRGI input of the Timer, the typical use of
this feature is with the use of another Timer(interface Timer)
configured in Hall sensor interface, this interface Timer will
generate the commutation at its TRGO output (connected to
Timer used in this function) each time the TI1 of the Interface
Timer detect a commutation at its input TI1.

HAL_TIMEx_ConfigCommutationEvent_DMA
Function Name

HAL_StatusTypeDef
HAL_TIMEx_ConfigCommutationEvent_DMA
(TIM_HandleTypeDef * htim, uint32_t InputTrigger, uint32_t
CommutationSource)

Function Description

Configure the TIM commutation event sequence with DMA.

Parameters

906/964

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
InputTrigger: the Internal trigger corresponding to the Timer
Interfacing with the Hall sensor. This parameter can be one of
the following values:
TIM_TS_ITR0: Internal trigger 0 selected
TIM_TS_ITR1: Internal trigger 1 selected
TIM_TS_ITR2: Internal trigger 2 selected
TIM_TS_ITR3: Internal trigger 3 selected
TIM_TS_NONE: No trigger is needed
CommutationSource: the Commutation Event source. This
parameter can be one of the following values:
TIM_COMMUTATION_TRGI: Commutation source is the
TRGI of the Interface Timer
TIM_COMMUTATION_SOFTWARE: Commutation

DocID025834 Rev 4

UM1725

HAL TIM Extension Driver
source is set by software using the COMG bit
Return values

HAL: status

Notes

This function is mandatory to use the commutation event in
order to update the configuration at each commutation
detection on the TRGI input of the Timer, the typical use of
this feature is with the use of another Timer(interface Timer)
configured in Hall sensor interface, this interface Timer will
generate the commutation at its TRGO output (connected to
Timer used in this function) each time the TI1 of the Interface
Timer detect a commutation at its input TI1.
: The user should configure the DMA in his own software, in
This function only the COMDE bit is set

HAL_TIMEx_MasterConfigSynchronization
Function Name

HAL_StatusTypeDef
HAL_TIMEx_MasterConfigSynchronization
(TIM_HandleTypeDef * htim, TIM_MasterConfigTypeDef *
sMasterConfig)

Function Description

Configures the TIM in master mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
sMasterConfig: pointer to a TIM_MasterConfigTypeDef
structure that contains the selected trigger output (TRGO) and
the Master/Slave mode.

Return values

HAL: status

HAL_TIMEx_ConfigBreakDeadTime
Function Name

HAL_StatusTypeDef HAL_TIMEx_ConfigBreakDeadTime
(TIM_HandleTypeDef * htim,
TIM_BreakDeadTimeConfigTypeDef * sBreakDeadTimeConfig)

Function Description

Configures the Break feature, dead time, Lock level, OSSI/OSSR
State and the AOE(automatic output enable).

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.
sBreakDeadTimeConfig: pointer to a
TIM_ConfigBreakDeadConfig_TypeDef structure that
contains the BDTR Register configuration information for the
TIM peripheral.

Return values

HAL: status

HAL_TIMEx_RemapConfig
Function Name

HAL_StatusTypeDef HAL_TIMEx_RemapConfig
(TIM_HandleTypeDef * htim, uint32_t Remap)

Function Description

Configures the TIM2, TIM5 and TIM11 Remapping input
capabilities.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
DocID025834 Rev 4

907/964

HAL TIM Extension Driver

Return values

UM1725
contains the configuration information for TIM module.
Remap: specifies the TIM input remapping source. This
parameter can be one of the following values:
TIM_TIM2_TIM8_TRGO: TIM2 ITR1 input is connected
to TIM8 Trigger output(default)
TIM_TIM2_ETH_PTP: TIM2 ITR1 input is connected to
ETH PTP trigger output.
TIM_TIM2_USBFS_SOF: TIM2 ITR1 input is connected
to USB FS SOF.
TIM_TIM2_USBHS_SOF: TIM2 ITR1 input is connected
to USB HS SOF.
TIM_TIM5_GPIO: TIM5 CH4 input is connected to
dedicated Timer pin(default)
TIM_TIM5_LSI: TIM5 CH4 input is connected to LSI
clock.
TIM_TIM5_LSE: TIM5 CH4 input is connected to LSE
clock.
TIM_TIM5_RTC: TIM5 CH4 input is connected to RTC
Output event.
TIM_TIM11_GPIO: TIM11 CH4 input is connected to
dedicated Timer pin(default)
TIM_TIM11_HSE: TIM11 CH4 input is connected to
HSE_RTC clock (HSE divided by a programmable
prescaler)
HAL: status

HAL_TIMEx_CommutationCallback
Function Name

void HAL_TIMEx_CommutationCallback (TIM_HandleTypeDef
* htim)

Function Description

Hall commutation changed callback in non blocking mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

HAL_TIMEx_BreakCallback
Function Name

void HAL_TIMEx_BreakCallback (TIM_HandleTypeDef * htim)

Function Description

Hall Break detection callback in non blocking mode.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

None

TIMEx_DMACommutationCplt
Function Name

void TIMEx_DMACommutationCplt (DMA_HandleTypeDef *
hdma)

Function Description

TIM DMA Commutation callback.

Parameters
908/964

hdma: pointer to a DMA_HandleTypeDef structure that
DocID025834 Rev 4

UM1725

HAL TIM Extension Driver
contains the configuration information for the specified DMA
module.
Return values

None

HAL_TIMEx_HallSensor_GetState
Function Name

HAL_TIM_StateTypeDef HAL_TIMEx_HallSensor_GetState
(TIM_HandleTypeDef * htim)

Function Description

Return the TIM Hall Sensor interface state.

Parameters

htim: pointer to a TIM_HandleTypeDef structure that
contains the configuration information for TIM module.

Return values

HAL: state

63.3

TIMEx Firmware driver defines

63.3.1

TIMEx
TIM Remap
TIM_TIM2_TIM8_TRGO
TIM_TIM2_ETH_PTP
TIM_TIM2_USBFS_SOF
TIM_TIM2_USBHS_SOF
TIM_TIM5_GPIO
TIM_TIM5_LSI
TIM_TIM5_LSE
TIM_TIM5_RTC
TIM_TIM11_GPIO
TIM_TIM11_HSE

DocID025834 Rev 4

909/964

HAL UART Generic Driver

UM1725

64

HAL UART Generic Driver

64.1

UART Firmware driver registers structures

64.1.1

UART_InitTypeDef
Data Fields
uint32_t BaudRate
uint32_t WordLength
uint32_t StopBits
uint32_t Parity
uint32_t Mode
uint32_t HwFlowCtl
uint32_t OverSampling

Field Documentation
uint32_t UART_InitTypeDef::BaudRate
This member configures the UART communication baud rate. The baud rate is
computed using the following formula:IntegerDivider = ((PCLKx) / (8 * (OVR8+1) *
(huart->Init.BaudRate)))FractionalDivider = ((IntegerDivider - ((uint32_t)
IntegerDivider)) * 8 * (OVR8+1)) + 0.5 Where OVR8 is the "oversampling by 8 mode"
configuration bit in the CR1 register.
uint32_t UART_InitTypeDef::WordLength
Specifies the number of data bits transmitted or received in a frame. This parameter
can be a value of UART_Word_Length
uint32_t UART_InitTypeDef::StopBits
Specifies the number of stop bits transmitted. This parameter can be a value of
UART_Stop_Bits
uint32_t UART_InitTypeDef::Parity
Specifies the parity mode. This parameter can be a value of UART_Parity
Note:When parity is enabled, the computed parity is inserted at the MSB position of
the transmitted data (9th bit when the word length is set to 9 data bits; 8th bit when the
word length is set to 8 data bits).
uint32_t UART_InitTypeDef::Mode
Specifies whether the Receive or Transmit mode is enabled or disabled. This
parameter can be a value of UART_Mode
uint32_t UART_InitTypeDef::HwFlowCtl
Specifies whether the hardware flow control mode is enabled or disabled. This
parameter can be a value of UART_Hardware_Flow_Control
uint32_t UART_InitTypeDef::OverSampling
Specifies whether the Over sampling 8 is enabled or disabled, to achieve higher
speed (up to fPCLK/8). This parameter can be a value of UART_Over_Sampling

910/964

DocID025834 Rev 4

UM1725

64.1.2

HAL UART Generic Driver

UART_HandleTypeDef
Data Fields
USART_TypeDef * Instance
UART_InitTypeDef Init
uint8_t * pTxBuffPtr
uint16_t TxXferSize
uint16_t TxXferCount
uint8_t * pRxBuffPtr
uint16_t RxXferSize
uint16_t RxXferCount
DMA_HandleTypeDef * hdmatx
DMA_HandleTypeDef * hdmarx
HAL_LockTypeDef Lock
__IO HAL_UART_StateTypeDef gState
__IO HAL_UART_StateTypeDef RxState
__IO uint32_t ErrorCode

Field Documentation
USART_TypeDef* UART_HandleTypeDef::Instance
UART registers base address
UART_InitTypeDef UART_HandleTypeDef::Init
UART communication parameters
uint8_t* UART_HandleTypeDef::pTxBuffPtr
Pointer to UART Tx transfer Buffer
uint16_t UART_HandleTypeDef::TxXferSize
UART Tx Transfer size
uint16_t UART_HandleTypeDef::TxXferCount
UART Tx Transfer Counter
uint8_t* UART_HandleTypeDef::pRxBuffPtr
Pointer to UART Rx transfer Buffer
uint16_t UART_HandleTypeDef::RxXferSize
UART Rx Transfer size
uint16_t UART_HandleTypeDef::RxXferCount
UART Rx Transfer Counter
DMA_HandleTypeDef* UART_HandleTypeDef::hdmatx
UART Tx DMA Handle parameters
DMA_HandleTypeDef* UART_HandleTypeDef::hdmarx
UART Rx DMA Handle parameters
HAL_LockTypeDef UART_HandleTypeDef::Lock
Locking object
__IO HAL_UART_StateTypeDef UART_HandleTypeDef::gState
UART state information related to global Handle management and also related to Tx
operations. This parameter can be a value of HAL_UART_StateTypeDef
__IO HAL_UART_StateTypeDef UART_HandleTypeDef::RxState
UART state information related to Rx operations. This parameter can be a value of
HAL_UART_StateTypeDef
__IO uint32_t UART_HandleTypeDef::ErrorCode
UART Error code
DocID025834 Rev 4

911/964

HAL UART Generic Driver

UM1725

64.2

UART Firmware driver API description

64.2.1

How to use this driver
The UART HAL driver can be used as follows:
1.
2.

3.
4.
5.
6.
7.

Declare a UART_HandleTypeDef handle structure.
Initialize the UART low level resources by implementing the HAL_UART_MspInit()
API:
a.
Enable the USARTx interface clock.
b.
UART pins configuration:
Enable the clock for the UART GPIOs.
Configure these UART pins as alternate function pull-up.
c.
NVIC configuration if you need to use interrupt process
(HAL_UART_Transmit_IT() and HAL_UART_Receive_IT() APIs):
Configure the USARTx interrupt priority.
Enable the NVIC USART IRQ handle.
d.
DMA Configuration if you need to use DMA process
(HAL_UART_Transmit_DMA() and HAL_UART_Receive_DMA() APIs):
Declare a DMA handle structure for the Tx/Rx stream.
Enable the DMAx interface clock.
Configure the declared DMA handle structure with the required Tx/Rx
parameters.
Configure the DMA Tx/Rx Stream.
Associate the initialized DMA handle to the UART DMA Tx/Rx handle.
Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Tx/Rx Stream.
Program the Baud Rate, Word Length, Stop Bit, Parity, Hardware flow control and
Mode(Receiver/Transmitter) in the Init structure.
For the UART asynchronous mode, initialize the UART registers by calling the
HAL_UART_Init() API.
For the UART Half duplex mode, initialize the UART registers by calling the
HAL_HalfDuplex_Init() API.
For the LIN mode, initialize the UART registers by calling the HAL_LIN_Init() API.
For the Multi-Processor mode, initialize the UART registers by calling the
HAL_MultiProcessor_Init() API.
The specific UART interrupts (Transmission complete interrupt, RXNE interrupt
and Error Interrupts) will be managed using the macros
__HAL_UART_ENABLE_IT() and __HAL_UART_DISABLE_IT() inside the
transmit and receive process.

These APIs (HAL_UART_Init() and HAL_HalfDuplex_Init()) configure also the low
level Hardware GPIO, CLOCK, CORTEX...etc) by calling the customized
HAL_UART_MspInit() API.

912/964

DocID025834 Rev 4

UM1725

HAL UART Generic Driver
Three operation modes are available within this driver :

Polling mode IO operation
Send an amount of data in blocking mode using HAL_UART_Transmit()
Receive an amount of data in blocking mode using HAL_UART_Receive()

Interrupt mode IO operation
Send an amount of data in non blocking mode using HAL_UART_Transmit_IT()
At transmission end of transfer HAL_UART_TxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_UART_TxCpltCallback
Receive an amount of data in non blocking mode using HAL_UART_Receive_IT()
At reception end of transfer HAL_UART_RxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_UART_RxCpltCallback
In case of transfer Error, HAL_UART_ErrorCallback() function is executed and user
can add his own code by customization of function pointer HAL_UART_ErrorCallback

DMA mode IO operation
Send an amount of data in non blocking mode (DMA) using
HAL_UART_Transmit_DMA()
At transmission end of half transfer HAL_UART_TxHalfCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_UART_TxHalfCpltCallback
At transmission end of transfer HAL_UART_TxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_UART_TxCpltCallback
Receive an amount of data in non blocking mode (DMA) using
HAL_UART_Receive_DMA()
At reception end of half transfer HAL_UART_RxHalfCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_UART_RxHalfCpltCallback
At reception end of transfer HAL_UART_RxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_UART_RxCpltCallback
In case of transfer Error, HAL_UART_ErrorCallback() function is executed and user
can add his own code by customization of function pointer HAL_UART_ErrorCallback
Pause the DMA Transfer using HAL_UART_DMAPause()
Resume the DMA Transfer using HAL_UART_DMAResume()
Stop the DMA Transfer using HAL_UART_DMAStop()

UART HAL driver macros list
Below the list of most used macros in UART HAL driver.
__HAL_UART_ENABLE: Enable the UART peripheral
__HAL_UART_DISABLE: Disable the UART peripheral
__HAL_UART_GET_FLAG : Check whether the specified UART flag is set or not
__HAL_UART_CLEAR_FLAG : Clear the specified UART pending flag
__HAL_UART_ENABLE_IT: Enable the specified UART interrupt
__HAL_UART_DISABLE_IT: Disable the specified UART interrupt

DocID025834 Rev 4

913/964

HAL UART Generic Driver

UM1725

__HAL_UART_GET_IT_SOURCE: Check whether the specified UART interrupt has
occurred or not
You can refer to the UART HAL driver header file for more useful macros

64.2.2

Initialization and Configuration functions
This subsection provides a set of functions allowing to initialize the USARTx or the UARTy
in asynchronous mode.
For the asynchronous mode only these parameters can be configured:
Baud Rate
Word Length
Stop Bit
Parity: If the parity is enabled, then the MSB bit of the data written in the data
register is transmitted but is changed by the parity bit. Depending on the frame
length defined by the M bit (8-bits or 9-bits), please refer to Reference manual for
possible UART frame formats.
Hardware flow control
Receiver/transmitter modes
Over Sampling Method
The HAL_UART_Init(), HAL_HalfDuplex_Init(), HAL_LIN_Init() and
HAL_MultiProcessor_Init() APIs follow respectively the UART asynchronous, UART Half
duplex, LIN and Multi-Processor configuration procedures (details for the procedures are
available in reference manual (RM0329)).
This section contains the following APIs:
HAL_UART_Init()
HAL_HalfDuplex_Init()
HAL_LIN_Init()
HAL_MultiProcessor_Init()
HAL_UART_DeInit()
HAL_UART_MspInit()
HAL_UART_MspDeInit()

64.2.3

IO operation functions
This subsection provides a set of functions allowing to manage the UART asynchronous
and Half duplex data transfers.
1.

2.
914/964

There are two modes of transfer:
Blocking mode: The communication is performed in polling mode. The HAL
status of all data processing is returned by the same function after finishing
transfer.
Non blocking mode: The communication is performed using Interrupts or DMA,
these APIs return the HAL status. The end of the data processing will be
indicated through the dedicated UART IRQ when using Interrupt mode or the
DMA IRQ when using DMA mode. The HAL_UART_TxCpltCallback(),
HAL_UART_RxCpltCallback() user callbacks will be executed respectively at the
end of the transmit or receive process. The HAL_UART_ErrorCallback() user
callback will be executed when a communication error is detected.
Blocking mode APIs are:
DocID025834 Rev 4

UM1725

HAL UART Generic Driver

3.

4.

5.

HAL_UART_Transmit()
HAL_UART_Receive()
Non Blocking mode APIs with Interrupt are:
HAL_UART_Transmit_IT()
HAL_UART_Receive_IT()
HAL_UART_IRQHandler()
Non Blocking mode functions with DMA are:
HAL_UART_Transmit_DMA()
HAL_UART_Receive_DMA()
A set of Transfer Complete Callbacks are provided in non blocking mode:
HAL_UART_TxCpltCallback()
HAL_UART_RxCpltCallback()
HAL_UART_ErrorCallback()
In the Half duplex communication, it is forbidden to run the transmit and receive
process in parallel, the UART state HAL_UART_STATE_BUSY_TX_RX can't be
useful.

This section contains the following APIs:
HAL_UART_Transmit()
HAL_UART_Receive()
HAL_UART_Transmit_IT()
HAL_UART_Receive_IT()
HAL_UART_Transmit_DMA()
HAL_UART_Receive_DMA()
HAL_UART_DMAPause()
HAL_UART_DMAResume()
HAL_UART_DMAStop()
HAL_UART_IRQHandler()
HAL_UART_TxCpltCallback()
HAL_UART_TxHalfCpltCallback()
HAL_UART_RxCpltCallback()
HAL_UART_RxHalfCpltCallback()
HAL_UART_ErrorCallback()

64.2.4

Peripheral Control functions
This subsection provides a set of functions allowing to control the UART:
HAL_LIN_SendBreak() API can be helpful to transmit the break character.
HAL_MultiProcessor_EnterMuteMode() API can be helpful to enter the UART in mute
mode.
HAL_MultiProcessor_ExitMuteMode() API can be helpful to exit the UART mute
mode by software.
This section contains the following APIs:
HAL_LIN_SendBreak()
HAL_MultiProcessor_EnterMuteMode()
HAL_MultiProcessor_ExitMuteMode()
HAL_HalfDuplex_EnableTransmitter()
HAL_HalfDuplex_EnableReceiver()

DocID025834 Rev 4

915/964

HAL UART Generic Driver

64.2.5

UM1725

Peripheral State and Errors functions
This subsection provides a set of functions allowing to return the State of UART
communication process, return Peripheral Errors occurred during communication process
HAL_UART_GetState() API can be helpful to check in run-time the state of the UART
peripheral.
HAL_UART_GetError() check in run-time errors that could be occurred during
communication.
This section contains the following APIs:
HAL_UART_GetState()
HAL_UART_GetError()

64.2.6

Detailed description of functions
HAL_UART_Init
Function Name

HAL_StatusTypeDef HAL_UART_Init (UART_HandleTypeDef *
huart)

Function Description

Initializes the UART mode according to the specified parameters in
the UART_InitTypeDef and create the associated handle.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: status

HAL_HalfDuplex_Init
Function Name

HAL_StatusTypeDef HAL_HalfDuplex_Init
(UART_HandleTypeDef * huart)

Function Description

Initializes the half-duplex mode according to the specified
parameters in the UART_InitTypeDef and create the associated
handle.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: status

HAL_LIN_Init
Function Name

HAL_StatusTypeDef HAL_LIN_Init (UART_HandleTypeDef *
huart, uint32_t BreakDetectLength)

Function Description

Initializes the LIN mode according to the specified parameters in
the UART_InitTypeDef and create the associated handle.

Parameters

916/964

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.
BreakDetectLength: Specifies the LIN break detection
length. This parameter can be one of the following values:
UART_LINBREAKDETECTLENGTH_10B: 10-bit break
DocID025834 Rev 4

UM1725

HAL UART Generic Driver
detection
UART_LINBREAKDETECTLENGTH_11B: 11-bit break
detection
Return values

HAL: status

HAL_MultiProcessor_Init
Function Name

HAL_StatusTypeDef HAL_MultiProcessor_Init
(UART_HandleTypeDef * huart, uint8_t Address, uint32_t
WakeUpMethod)

Function Description

Initializes the Multi-Processor mode according to the specified
parameters in the UART_InitTypeDef and create the associated
handle.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.
Address: USART address
WakeUpMethod: specifies the USART wake-up method.
This parameter can be one of the following values:
UART_WAKEUPMETHOD_IDLELINE: Wake-up by an
idle line detection
UART_WAKEUPMETHOD_ADDRESSMARK: Wake-up
by an address mark

Return values

HAL: status

HAL_UART_DeInit
Function Name

HAL_StatusTypeDef HAL_UART_DeInit
(UART_HandleTypeDef * huart)

Function Description

DeInitializes the UART peripheral.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: status

HAL_UART_MspInit
Function Name

void HAL_UART_MspInit (UART_HandleTypeDef * huart)

Function Description

UART MSP Init.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

None

HAL_UART_MspDeInit
Function Name

void HAL_UART_MspDeInit (UART_HandleTypeDef * huart)

Function Description

UART MSP DeInit.
DocID025834 Rev 4

917/964

HAL UART Generic Driver
Parameters

UM1725
huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

None

HAL_UART_Transmit
Function Name

HAL_StatusTypeDef HAL_UART_Transmit
(UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size,
uint32_t Timeout)

Function Description

Sends an amount of data in blocking mode.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.
pData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_UART_Receive
Function Name

HAL_StatusTypeDef HAL_UART_Receive
(UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size,
uint32_t Timeout)

Function Description

Receives an amount of data in blocking mode.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.
pData: Pointer to data buffer
Size: Amount of data to be received
Timeout: Timeout duration

Return values

HAL: status

HAL_UART_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_UART_Transmit_IT
(UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size)

Function Description

Sends an amount of data in non blocking mode.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_UART_Receive_IT
Function Name
918/964

HAL_StatusTypeDef HAL_UART_Receive_IT
DocID025834 Rev 4

UM1725

HAL UART Generic Driver
(UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size)
Function Description

Receives an amount of data in non blocking mode.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.
pData: Pointer to data buffer
Size: Amount of data to be received

Return values

HAL: status

HAL_UART_Transmit_DMA
Function Name

HAL_StatusTypeDef HAL_UART_Transmit_DMA
(UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size)

Function Description

Sends an amount of data in non blocking mode.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.
pData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_UART_Receive_DMA
Function Name

HAL_StatusTypeDef HAL_UART_Receive_DMA
(UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size)

Function Description

Receives an amount of data in non blocking mode.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.
pData: Pointer to data buffer
Size: Amount of data to be received

Return values

HAL: status

Notes

When the UART parity is enabled (PCE = 1) the data
received contain the parity bit.

HAL_UART_DMAPause
Function Name

HAL_StatusTypeDef HAL_UART_DMAPause
(UART_HandleTypeDef * huart)

Function Description

Pauses the DMA Transfer.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: status

DocID025834 Rev 4

919/964

HAL UART Generic Driver

UM1725

HAL_UART_DMAResume
Function Name

HAL_StatusTypeDef HAL_UART_DMAResume
(UART_HandleTypeDef * huart)

Function Description

Resumes the DMA Transfer.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: status

HAL_UART_DMAStop
Function Name

HAL_StatusTypeDef HAL_UART_DMAStop
(UART_HandleTypeDef * huart)

Function Description

Stops the DMA Transfer.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: status

HAL_UART_IRQHandler
Function Name

void HAL_UART_IRQHandler (UART_HandleTypeDef * huart)

Function Description

This function handles UART interrupt request.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

None

HAL_UART_TxCpltCallback
Function Name

void HAL_UART_TxCpltCallback (UART_HandleTypeDef *
huart)

Function Description

Tx Transfer completed callbacks.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

None

HAL_UART_TxHalfCpltCallback
Function Name

void HAL_UART_TxHalfCpltCallback (UART_HandleTypeDef *
huart)

Function Description

Tx Half Transfer completed callbacks.

Parameters

920/964

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.
DocID025834 Rev 4

UM1725

HAL UART Generic Driver
Return values

None

HAL_UART_RxCpltCallback
Function Name

void HAL_UART_RxCpltCallback (UART_HandleTypeDef *
huart)

Function Description

Rx Transfer completed callbacks.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

None

HAL_UART_RxHalfCpltCallback
Function Name

void HAL_UART_RxHalfCpltCallback (UART_HandleTypeDef *
huart)

Function Description

Rx Half Transfer completed callbacks.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

None

HAL_UART_ErrorCallback
Function Name

void HAL_UART_ErrorCallback (UART_HandleTypeDef *
huart)

Function Description

UART error callbacks.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

None

HAL_LIN_SendBreak
Function Name

HAL_StatusTypeDef HAL_LIN_SendBreak
(UART_HandleTypeDef * huart)

Function Description

Transmits break characters.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: status

HAL_MultiProcessor_EnterMuteMode
Function Name

HAL_StatusTypeDef HAL_MultiProcessor_EnterMuteMode
(UART_HandleTypeDef * huart)

Function Description

Enters the UART in mute mode.
DocID025834 Rev 4

921/964

HAL UART Generic Driver
Parameters

UM1725
huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: status

HAL_MultiProcessor_ExitMuteMode
Function Name

HAL_StatusTypeDef HAL_MultiProcessor_ExitMuteMode
(UART_HandleTypeDef * huart)

Function Description

Exits the UART mute mode: wake up software.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: status

HAL_HalfDuplex_EnableTransmitter
Function Name

HAL_StatusTypeDef HAL_HalfDuplex_EnableTransmitter
(UART_HandleTypeDef * huart)

Function Description

Enables the UART transmitter and disables the UART receiver.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: status

HAL_HalfDuplex_EnableReceiver
Function Name

HAL_StatusTypeDef HAL_HalfDuplex_EnableReceiver
(UART_HandleTypeDef * huart)

Function Description

Enables the UART receiver and disables the UART transmitter.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: status

HAL_UART_GetState

922/964

Function Name

HAL_UART_StateTypeDef HAL_UART_GetState
(UART_HandleTypeDef * huart)

Function Description

Returns the UART state.

Parameters

huart: pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART
module.

Return values

HAL: state

DocID025834 Rev 4

UM1725

HAL UART Generic Driver

HAL_UART_GetError
Function Name

uint32_t HAL_UART_GetError (UART_HandleTypeDef * huart)

Function Description

Return the UART error code.

Parameters

huart: : pointer to a UART_HandleTypeDef structure that
contains the configuration information for the specified UART.

Return values

UART: Error Code

64.3

UART Firmware driver defines

64.3.1

UART
UART Error Code
HAL_UART_ERROR_NONE

No error

HAL_UART_ERROR_PE

Parity error

HAL_UART_ERROR_NE

Noise error

HAL_UART_ERROR_FE

Frame error

HAL_UART_ERROR_ORE

Overrun error

HAL_UART_ERROR_DMA

DMA transfer error

UART Exported Macros
__HAL_UART_RESET_HANDLE_STATE

Description:
Reset UART handle gstate &
RxState.
Parameters:
__HANDLE__: specifies the UART
Handle. This parameter can be
UARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
Return value:
None

__HAL_UART_FLUSH_DRREGISTER

Description:
Flushes the UART DR register.
Parameters:
__HANDLE__: specifies the UART
Handle.

__HAL_UART_GET_FLAG

Description:
Checks whether the specified UART
flag is set or not.
Parameters:
__HANDLE__: specifies the UART
Handle. This parameter can be
DocID025834 Rev 4

923/964

HAL UART Generic Driver

UM1725
UARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
__FLAG__: specifies the flag to
check. This parameter can be one of
the following values:
UART_FLAG_CTS: CTS
Change flag (not available for
UART4 and UART5)
UART_FLAG_LBD: LIN Break
detection flag
UART_FLAG_TXE: Transmit
data register empty flag
UART_FLAG_TC:
Transmission Complete flag
UART_FLAG_RXNE: Receive
data register not empty flag
UART_FLAG_IDLE: Idle Line
detection flag
UART_FLAG_ORE: Overrun
Error flag
UART_FLAG_NE: Noise Error
flag
UART_FLAG_FE: Framing
Error flag
UART_FLAG_PE: Parity Error
flag
Return value:
The: new state of __FLAG__ (TRUE
or FALSE).

__HAL_UART_CLEAR_FLAG

Description:
Clears the specified UART pending
flag.
Parameters:
__HANDLE__: specifies the UART
Handle. This parameter can be
UARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
__FLAG__: specifies the flag to
check. This parameter can be any
combination of the following values:
UART_FLAG_CTS: CTS
Change flag (not available for
UART4 and UART5).
UART_FLAG_LBD: LIN Break
detection flag.
UART_FLAG_TC:
Transmission Complete flag.
UART_FLAG_RXNE: Receive
data register not empty flag.

924/964

DocID025834 Rev 4

UM1725

HAL UART Generic Driver
Return value:
None
Notes:
PE (Parity error), FE (Framing error),
NE (Noise error), ORE (Overrun
error) and IDLE (Idle line detected)
flags are cleared by software
sequence: a read operation to
USART_SR register followed by a
read operation to USART_DR
register. RXNE flag can be also
cleared by a read to the USART_DR
register. TC flag can be also cleared
by software sequence: a read
operation to USART_SR register
followed by a write operation to
USART_DR register. TXE flag is
cleared only by a write to the
USART_DR register.
__HAL_UART_CLEAR_PEFLAG

Description:
Clear the UART PE pending flag.
Parameters:
__HANDLE__: specifies the UART
Handle. This parameter can be
UARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
Return value:
None

__HAL_UART_CLEAR_FEFLAG

Description:
Clear the UART FE pending flag.
Parameters:
__HANDLE__: specifies the UART
Handle. This parameter can be
UARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
Return value:
None

__HAL_UART_CLEAR_NEFLAG

Description:
Clear the UART NE pending flag.
Parameters:
__HANDLE__: specifies the UART
Handle. This parameter can be
UARTx where x: 1, 2, 3, 4, 5, 6, 7 or

DocID025834 Rev 4

925/964

HAL UART Generic Driver

UM1725
8 to select the USART or UART
peripheral.
Return value:
None

__HAL_UART_CLEAR_OREFLAG

Description:
Clear the UART ORE pending flag.
Parameters:
__HANDLE__: specifies the UART
Handle. This parameter can be
UARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
Return value:
None

__HAL_UART_CLEAR_IDLEFLAG

Description:
Clear the UART IDLE pending flag.
Parameters:
__HANDLE__: specifies the UART
Handle. This parameter can be
UARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
Return value:
None

UART_IT_MASK

Description:
Enable the specified UART interrupt.
Parameters:
__HANDLE__: specifies the UART
Handle. This parameter can be
UARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
__INTERRUPT__: specifies the
UART interrupt source to enable.
This parameter can be one of the
following values:
UART_IT_CTS: CTS change
interrupt
UART_IT_LBD: LIN Break
detection interrupt
UART_IT_TXE: Transmit Data
Register empty interrupt
UART_IT_TC: Transmission
complete interrupt
UART_IT_RXNE: Receive Data

926/964

DocID025834 Rev 4

UM1725

HAL UART Generic Driver
register not empty interrupt
UART_IT_IDLE: Idle line
detection interrupt
UART_IT_PE: Parity Error
interrupt
UART_IT_ERR: Error
interrupt(Frame error, noise
error, overrun error)
Return value:
None
__HAL_UART_ENABLE_IT
Description:

__HAL_UART_DISABLE_IT

Disable the specified UART
interrupt.
Parameters:
__HANDLE__: specifies the UART
Handle. This parameter can be
UARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
__INTERRUPT__: specifies the
UART interrupt source to disable.
This parameter can be one of the
following values:
UART_IT_CTS: CTS change
interrupt
UART_IT_LBD: LIN Break
detection interrupt
UART_IT_TXE: Transmit Data
Register empty interrupt
UART_IT_TC: Transmission
complete interrupt
UART_IT_RXNE: Receive Data
register not empty interrupt
UART_IT_IDLE: Idle line
detection interrupt
UART_IT_PE: Parity Error
interrupt
UART_IT_ERR: Error
interrupt(Frame error, noise
error, overrun error)
Return value:
None
__HAL_UART_GET_IT_SOURCE

Description:
Checks whether the specified UART
interrupt has occurred or not.
Parameters:
__HANDLE__: specifies the UART

DocID025834 Rev 4

927/964

HAL UART Generic Driver

UM1725
Handle. This parameter can be
UARTx where x: 1, 2, 3, 4, 5, 6, 7 or
8 to select the USART or UART
peripheral.
__IT__: specifies the UART interrupt
source to check. This parameter can
be one of the following values:
UART_IT_CTS: CTS change
interrupt (not available for
UART4 and UART5)
UART_IT_LBD: LIN Break
detection interrupt
UART_IT_TXE: Transmit Data
Register empty interrupt
UART_IT_TC: Transmission
complete interrupt
UART_IT_RXNE: Receive Data
register not empty interrupt
UART_IT_IDLE: Idle line
detection interrupt
USART_IT_ERR: Error interrupt
Return value:
The: new state of __IT__ (TRUE or
FALSE).

__HAL_UART_HWCONTROL_CTS_ENABLE

Description:
Enable CTS flow control This macro
allows to enable CTS hardware flow
control for a given UART instance,
without need to call
Parameters:
__HANDLE__: specifies the UART
Handle. The Handle Instance can be
USART1, USART2 or LPUART.
Return value:
None
Notes:
As macro is expected to be used for
modifying CTS Hw flow control
feature activation, without need for
USART instance Deinit/Init, following
conditions for macro call should be
fulfilled : UART instance should have
already been initialised (through call
of HAL_UART_Init() )macro could
only be called when corresponding
UART instance is disabled (i.e
__HAL_UART_DISABLE(__HANDL
E__)) and should be followed by an
Enable macro (i.e
__HAL_UART_ENABLE(__HANDLE

928/964

DocID025834 Rev 4

UM1725

HAL UART Generic Driver
__)).
__HAL_UART_HWCONTROL_CTS_DISABLE

Description:
Disable CTS flow control This macro
allows to disable CTS hardware flow
control for a given UART instance,
without need to call
Parameters:
__HANDLE__: specifies the UART
Handle. The Handle Instance can be
USART1, USART2 or LPUART.
Return value:
None
Notes:
As macro is expected to be used for
modifying CTS Hw flow control
feature activation, without need for
USART instance Deinit/Init, following
conditions for macro call should be
fulfilled : UART instance should have
already been initialised (through call
of HAL_UART_Init() )macro could
only be called when corresponding
UART instance is disabled (i.e
__HAL_UART_DISABLE(__HANDL
E__)) and should be followed by an
Enable macro (i.e
__HAL_UART_ENABLE(__HANDLE
__)).

__HAL_UART_HWCONTROL_RTS_ENABLE

Description:
Enable RTS flow control This macro
allows to enable RTS hardware flow
control for a given UART instance,
without need to call
Parameters:
__HANDLE__: specifies the UART
Handle. The Handle Instance can be
USART1, USART2 or LPUART.
Return value:
None
Notes:
As macro is expected to be used for
modifying RTS Hw flow control
feature activation, without need for
USART instance Deinit/Init, following
conditions for macro call should be
fulfilled : UART instance should have
already been initialised (through call

DocID025834 Rev 4

929/964

HAL UART Generic Driver

UM1725
of HAL_UART_Init() )macro could
only be called when corresponding
UART instance is disabled (i.e
__HAL_UART_DISABLE(__HANDL
E__)) and should be followed by an
Enable macro (i.e
__HAL_UART_ENABLE(__HANDLE
__)).

__HAL_UART_HWCONTROL_RTS_DISABLE

Description:
Disable RTS flow control This macro
allows to disable RTS hardware flow
control for a given UART instance,
without need to call
Parameters:
__HANDLE__: specifies the UART
Handle. The Handle Instance can be
USART1, USART2 or LPUART.
Return value:
None
Notes:
As macro is expected to be used for
modifying RTS Hw flow control
feature activation, without need for
USART instance Deinit/Init, following
conditions for macro call should be
fulfilled : UART instance should have
already been initialised (through call
of HAL_UART_Init() )macro could
only be called when corresponding
UART instance is disabled (i.e
__HAL_UART_DISABLE(__HANDL
E__)) and should be followed by an
Enable macro (i.e
__HAL_UART_ENABLE(__HANDLE
__)).

__HAL_UART_ONE_BIT_SAMPLE_ENABLE

Description:
macros to enables the UART's one
bit sample method
Parameters:
__HANDLE__: specifies the UART
Handle.
Return value:
None

__HAL_UART_ONE_BIT_SAMPLE_DISABLE

Description:
macros to disables the UART's one
bit sample method

930/964

DocID025834 Rev 4

UM1725

HAL UART Generic Driver
Parameters:
__HANDLE__: specifies the UART
Handle.
Return value:
None
Description:

__HAL_UART_ENABLE

Enable UART.
Parameters:
__HANDLE__: specifies the UART
Handle.
Return value:
None
Description:

__HAL_UART_DISABLE

Disable UART.
Parameters:
__HANDLE__: specifies the UART
Handle.
Return value:
None
UART FLags
UART_FLAG_CTS
UART_FLAG_LBD
UART_FLAG_TXE
UART_FLAG_TC
UART_FLAG_RXNE
UART_FLAG_IDLE
UART_FLAG_ORE
UART_FLAG_NE
UART_FLAG_FE
UART_FLAG_PE
UART Hardware Flow Control
UART_HWCONTROL_NONE
UART_HWCONTROL_RTS
UART_HWCONTROL_CTS
UART_HWCONTROL_RTS_CTS
UART Interrupt Definitions
UART_IT_PE

DocID025834 Rev 4

931/964

HAL UART Generic Driver
UART_IT_TXE

UM1725

UART_IT_TC
UART_IT_RXNE
UART_IT_IDLE
UART_IT_LBD
UART_IT_CTS
UART_IT_ERR
UART LIN Break Detection Length
UART_LINBREAKDETECTLENGTH_10B
UART_LINBREAKDETECTLENGTH_11B
UART Transfer Mode
UART_MODE_RX
UART_MODE_TX
UART_MODE_TX_RX
UART Over Sampling
UART_OVERSAMPLING_16
UART_OVERSAMPLING_8
UART Parity
UART_PARITY_NONE
UART_PARITY_EVEN
UART_PARITY_ODD
UART State
UART_STATE_DISABLE
UART_STATE_ENABLE
UART Number of Stop Bits
UART_STOPBITS_1
UART_STOPBITS_2
UART Wakeup Functions
UART_WAKEUPMETHOD_IDLELINE
UART_WAKEUPMETHOD_ADDRESSMARK
UART Word Length
UART_WORDLENGTH_8B
UART_WORDLENGTH_9B

932/964

DocID025834 Rev 4

UM1725

HAL USART Generic Driver

65

HAL USART Generic Driver

65.1

USART Firmware driver registers structures

65.1.1

USART_InitTypeDef
Data Fields
uint32_t BaudRate
uint32_t WordLength
uint32_t StopBits
uint32_t Parity
uint32_t Mode
uint32_t CLKPolarity
uint32_t CLKPhase
uint32_t CLKLastBit

Field Documentation
uint32_t USART_InitTypeDef::BaudRate
This member configures the Usart communication baud rate. The baud rate is
computed using the following formula:IntegerDivider = ((PCLKx) / (8 * (husart>Init.BaudRate)))FractionalDivider = ((IntegerDivider - ((uint32_t) IntegerDivider)) * 8)
+ 0.5
uint32_t USART_InitTypeDef::WordLength
Specifies the number of data bits transmitted or received in a frame. This parameter
can be a value of USART_Word_Length
uint32_t USART_InitTypeDef::StopBits
Specifies the number of stop bits transmitted. This parameter can be a value of
USART_Stop_Bits
uint32_t USART_InitTypeDef::Parity
Specifies the parity mode. This parameter can be a value of USART_Parity
Note:When parity is enabled, the computed parity is inserted at the MSB position of
the transmitted data (9th bit when the word length is set to 9 data bits; 8th bit when the
word length is set to 8 data bits).
uint32_t USART_InitTypeDef::Mode
Specifies whether the Receive or Transmit mode is enabled or disabled. This
parameter can be a value of USART_Mode
uint32_t USART_InitTypeDef::CLKPolarity
Specifies the steady state of the serial clock. This parameter can be a value of
USART_Clock_Polarity
uint32_t USART_InitTypeDef::CLKPhase
Specifies the clock transition on which the bit capture is made. This parameter can be
a value of USART_Clock_Phase
uint32_t USART_InitTypeDef::CLKLastBit
Specifies whether the clock pulse corresponding to the last transmitted data bit (MSB)
has to be output on the SCLK pin in synchronous mode. This parameter can be a
value of USART_Last_Bit

DocID025834 Rev 4

933/964

HAL USART Generic Driver

65.1.2

UM1725

USART_HandleTypeDef
Data Fields
USART_TypeDef * Instance
USART_InitTypeDef Init
uint8_t * pTxBuffPtr
uint16_t TxXferSize
__IO uint16_t TxXferCount
uint8_t * pRxBuffPtr
uint16_t RxXferSize
__IO uint16_t RxXferCount
DMA_HandleTypeDef * hdmatx
DMA_HandleTypeDef * hdmarx
HAL_LockTypeDef Lock
__IO HAL_USART_StateTypeDef State
__IO uint32_t ErrorCode

Field Documentation
USART_TypeDef* USART_HandleTypeDef::Instance
USART_InitTypeDef USART_HandleTypeDef::Init
uint8_t* USART_HandleTypeDef::pTxBuffPtr
uint16_t USART_HandleTypeDef::TxXferSize
__IO uint16_t USART_HandleTypeDef::TxXferCount
uint8_t* USART_HandleTypeDef::pRxBuffPtr
uint16_t USART_HandleTypeDef::RxXferSize
__IO uint16_t USART_HandleTypeDef::RxXferCount
DMA_HandleTypeDef* USART_HandleTypeDef::hdmatx
DMA_HandleTypeDef* USART_HandleTypeDef::hdmarx
HAL_LockTypeDef USART_HandleTypeDef::Lock
__IO HAL_USART_StateTypeDef USART_HandleTypeDef::State
__IO uint32_t USART_HandleTypeDef::ErrorCode

65.2

USART Firmware driver API description

65.2.1

How to use this driver
The USART HAL driver can be used as follows:
1.
2.

934/964

Declare a USART_HandleTypeDef handle structure.
Initialize the USART low level resources by implementing the HAL_USART_MspInit ()
API:
a.
Enable the USARTx interface clock.
b.
USART pins configuration:
Enable the clock for the USART GPIOs.
Configure these USART pins as alternate function pull-up.
c.
NVIC configuration if you need to use interrupt process
(HAL_USART_Transmit_IT(), HAL_USART_Receive_IT() and
HAL_USART_TransmitReceive_IT() APIs):
Configure the USARTx interrupt priority.
DocID025834 Rev 4

UM1725

HAL USART Generic Driver

3.
4.

5.

Enable the NVIC USART IRQ handle.
d.
DMA Configuration if you need to use DMA process
(HAL_USART_Transmit_DMA() HAL_USART_Receive_IT() and
HAL_USART_TransmitReceive_IT() APIs):
Declare a DMA handle structure for the Tx/Rx stream.
Enable the DMAx interface clock.
Configure the declared DMA handle structure with the required Tx/Rx
parameters.
Configure the DMA Tx/Rx Stream.
Associate the initialized DMA handle to the USART DMA Tx/Rx handle.
Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Tx/Rx Stream.
Program the Baud Rate, Word Length, Stop Bit, Parity, Hardware flow control and
Mode(Receiver/Transmitter) in the husart Init structure.
Initialize the USART registers by calling the HAL_USART_Init() API:
These APIs configures also the low level Hardware GPIO, CLOCK,
CORTEX...etc) by calling the customized HAL_USART_MspInit(&husart) API.
The specific USART interrupts (Transmission complete interrupt, RXNE interrupt
and Error Interrupts) will be managed using the macros
__HAL_USART_ENABLE_IT() and __HAL_USART_DISABLE_IT() inside the
transmit and receive process.
Three operation modes are available within this driver :

Polling mode IO operation
Send an amount of data in blocking mode using HAL_USART_Transmit()
Receive an amount of data in blocking mode using HAL_USART_Receive()

Interrupt mode IO operation
Send an amount of data in non blocking mode using HAL_USART_Transmit_IT()
At transmission end of transfer HAL_USART_TxHalfCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_USART_TxCpltCallback
Receive an amount of data in non blocking mode using HAL_USART_Receive_IT()
At reception end of transfer HAL_USART_RxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_USART_RxCpltCallback
In case of transfer Error, HAL_USART_ErrorCallback() function is executed and user
can add his own code by customization of function pointer
HAL_USART_ErrorCallback

DMA mode IO operation
Send an amount of data in non blocking mode (DMA) using
HAL_USART_Transmit_DMA()
At transmission end of half transfer HAL_USART_TxHalfCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_USART_TxHalfCpltCallback
At transmission end of transfer HAL_USART_TxCpltCallback is executed and user
can add his own code by customization of function pointer
HAL_USART_TxCpltCallback
DocID025834 Rev 4

935/964

HAL USART Generic Driver

UM1725

Receive an amount of data in non blocking mode (DMA) using
HAL_USART_Receive_DMA()
At reception end of half transfer HAL_USART_RxHalfCpltCallback is executed and
user can add his own code by customization of function pointer
HAL_USART_RxHalfCpltCallback
At reception end of transfer HAL_USART_RxCpltCallback is executed and user can
add his own code by customization of function pointer HAL_USART_RxCpltCallback
In case of transfer Error, HAL_USART_ErrorCallback() function is executed and user
can add his own code by customization of function pointer
HAL_USART_ErrorCallback
Pause the DMA Transfer using HAL_USART_DMAPause()
Resume the DMA Transfer using HAL_USART_DMAResume()
Stop the DMA Transfer using HAL_USART_DMAStop()

USART HAL driver macros list
Below the list of most used macros in USART HAL driver.
__HAL_USART_ENABLE: Enable the USART peripheral
__HAL_USART_DISABLE: Disable the USART peripheral
__HAL_USART_GET_FLAG : Check whether the specified USART flag is set or not
__HAL_USART_CLEAR_FLAG : Clear the specified USART pending flag
__HAL_USART_ENABLE_IT: Enable the specified USART interrupt
__HAL_USART_DISABLE_IT: Disable the specified USART interrupt
You can refer to the USART HAL driver header file for more useful macros

65.2.2

Initialization and Configuration functions
This subsection provides a set of functions allowing to initialize the USART in
asynchronous and in synchronous modes.
For the asynchronous mode only these parameters can be configured:
Baud Rate
Word Length
Stop Bit
Parity: If the parity is enabled, then the MSB bit of the data written in the data
register is transmitted but is changed by the parity bit. Depending on the frame
length defined by the M bit (8-bits or 9-bits), please refer to Reference manual for
possible USART frame formats.
USART polarity
USART phase
USART LastBit
Receiver/transmitter modes
The HAL_USART_Init() function follows the USART synchronous configuration procedure
(details for the procedure are available in reference manual (RM0329)).
This section contains the following APIs:
HAL_USART_Init()
HAL_USART_DeInit()
HAL_USART_MspInit()
HAL_USART_MspDeInit()

936/964

DocID025834 Rev 4

UM1725

65.2.3

HAL USART Generic Driver

IO operation functions
This subsection provides a set of functions allowing to manage the USART synchronous
data transfers.
The USART supports master mode only: it cannot receive or send data related to an input
clock (SCLK is always an output).
1.

2.

3.

4.

5.

There are two modes of transfer:
Blocking mode: The communication is performed in polling mode. The HAL
status of all data processing is returned by the same function after finishing
transfer.
No-Blocking mode: The communication is performed using Interrupts or DMA,
These API's return the HAL status. The end of the data processing will be
indicated through the dedicated USART IRQ when using Interrupt mode or the
DMA IRQ when using DMA mode. The HAL_USART_TxCpltCallback(),
HAL_USART_RxCpltCallback() and HAL_USART_TxRxCpltCallback() user
callbacks will be executed respectively at the end of the transmit or Receive
process The HAL_USART_ErrorCallback() user callback will be executed when a
communication error is detected
Blocking mode APIs are :
HAL_USART_Transmit() in simplex mode
HAL_USART_Receive() in full duplex receive only
HAL_USART_TransmitReceive() in full duplex mode
Non Blocking mode APIs with Interrupt are :
HAL_USART_Transmit_IT()in simplex mode
HAL_USART_Receive_IT() in full duplex receive only
HAL_USART_TransmitReceive_IT() in full duplex mode
HAL_USART_IRQHandler()
Non Blocking mode functions with DMA are :
HAL_USART_Transmit_DMA()in simplex mode
HAL_USART_Receive_DMA() in full duplex receive only
HAL_USART_TransmitReceie_DMA() in full duplex mode
HAL_USART_DMAPause()
HAL_USART_DMAResume()
HAL_USART_DMAStop()
A set of Transfer Complete Callbacks are provided in non Blocking mode:
HAL_USART_TxHalfCpltCallback()
HAL_USART_TxCpltCallback()
HAL_USART_RxHalfCpltCallback()
HAL_USART_RxCpltCallback()
HAL_USART_ErrorCallback()
HAL_USART_TxRxCpltCallback()

This section contains the following APIs:
HAL_USART_Transmit()
HAL_USART_Receive()
HAL_USART_TransmitReceive()
HAL_USART_Transmit_IT()
HAL_USART_Receive_IT()
HAL_USART_TransmitReceive_IT()
HAL_USART_Transmit_DMA()
HAL_USART_Receive_DMA()
HAL_USART_TransmitReceive_DMA()
HAL_USART_DMAPause()
DocID025834 Rev 4

937/964

HAL USART Generic Driver

UM1725

HAL_USART_DMAResume()
HAL_USART_DMAStop()
HAL_USART_IRQHandler()
HAL_USART_TxCpltCallback()
HAL_USART_TxHalfCpltCallback()
HAL_USART_RxCpltCallback()
HAL_USART_RxHalfCpltCallback()
HAL_USART_TxRxCpltCallback()
HAL_USART_ErrorCallback()

65.2.4

Peripheral State and Errors functions
This subsection provides a set of functions allowing to return the State of USART
communication process, return Peripheral Errors occurred during communication process
HAL_USART_GetState() API can be helpful to check in run-time the state of the
USART peripheral.
HAL_USART_GetError() check in run-time errors that could be occurred during
communication.
This section contains the following APIs:
HAL_USART_GetState()
HAL_USART_GetError()

65.2.5

Detailed description of functions
HAL_USART_Init
Function Name

HAL_StatusTypeDef HAL_USART_Init
(USART_HandleTypeDef * husart)

Function Description

Initializes the USART mode according to the specified parameters
in the USART_InitTypeDef and create the associated handle.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

HAL: status

HAL_USART_DeInit
Function Name

HAL_StatusTypeDef HAL_USART_DeInit
(USART_HandleTypeDef * husart)

Function Description

DeInitializes the USART peripheral.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

HAL: status

HAL_USART_MspInit

938/964

Function Name

void HAL_USART_MspInit (USART_HandleTypeDef * husart)

Function Description

USART MSP Init.
DocID025834 Rev 4

UM1725

HAL USART Generic Driver
Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

None

HAL_USART_MspDeInit
Function Name

void HAL_USART_MspDeInit (USART_HandleTypeDef *
husart)

Function Description

USART MSP DeInit.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

None

HAL_USART_Transmit
Function Name

HAL_StatusTypeDef HAL_USART_Transmit
(USART_HandleTypeDef * husart, uint8_t * pTxData, uint16_t
Size, uint32_t Timeout)

Function Description

Simplex Send an amount of data in blocking mode.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.
pTxData: Pointer to data buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_USART_Receive
Function Name

HAL_StatusTypeDef HAL_USART_Receive
(USART_HandleTypeDef * husart, uint8_t * pRxData, uint16_t
Size, uint32_t Timeout)

Function Description

Full-Duplex Receive an amount of data in blocking mode.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.
pRxData: Pointer to data buffer
Size: Amount of data to be received
Timeout: Timeout duration

Return values

HAL: status

HAL_USART_TransmitReceive
Function Name

HAL_StatusTypeDef HAL_USART_TransmitReceive
(USART_HandleTypeDef * husart, uint8_t * pTxData, uint8_t *
pRxData, uint16_t Size, uint32_t Timeout)

DocID025834 Rev 4

939/964

HAL USART Generic Driver
Function Description

UM1725
Full-Duplex Send receive an amount of data in full-duplex mode
(blocking mode).

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.
pTxData: Pointer to data transmitted buffer
pRxData: Pointer to data received buffer
Size: Amount of data to be sent
Timeout: Timeout duration

Return values

HAL: status

HAL_USART_Transmit_IT
Function Name

HAL_StatusTypeDef HAL_USART_Transmit_IT
(USART_HandleTypeDef * husart, uint8_t * pTxData, uint16_t
Size)

Function Description

Simplex Send an amount of data in non-blocking mode.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.
pTxData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

Notes

The USART errors are not managed to avoid the overrun
error.

HAL_USART_Receive_IT
Function Name

HAL_StatusTypeDef HAL_USART_Receive_IT
(USART_HandleTypeDef * husart, uint8_t * pRxData, uint16_t
Size)

Function Description

Simplex Receive an amount of data in non-blocking mode.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.
pRxData: Pointer to data buffer
Size: Amount of data to be received

Return values

HAL: status

HAL_USART_TransmitReceive_IT
Function Name

HAL_StatusTypeDef HAL_USART_TransmitReceive_IT
(USART_HandleTypeDef * husart, uint8_t * pTxData, uint8_t *
pRxData, uint16_t Size)

Function Description

Full-Duplex Send receive an amount of data in full-duplex mode
(non-blocking).

Parameters

940/964

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
DocID025834 Rev 4

UM1725

HAL USART Generic Driver
USART module.
pTxData: Pointer to data transmitted buffer
pRxData: Pointer to data received buffer
Size: Amount of data to be received
Return values

HAL: status

HAL_USART_Transmit_DMA
Function Name

HAL_StatusTypeDef HAL_USART_Transmit_DMA
(USART_HandleTypeDef * husart, uint8_t * pTxData, uint16_t
Size)

Function Description

Simplex Send an amount of data in non-blocking mode.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.
pTxData: Pointer to data buffer
Size: Amount of data to be sent

Return values

HAL: status

HAL_USART_Receive_DMA
Function Name

HAL_StatusTypeDef HAL_USART_Receive_DMA
(USART_HandleTypeDef * husart, uint8_t * pRxData, uint16_t
Size)

Function Description

Full-Duplex Receive an amount of data in non-blocking mode.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.
pRxData: Pointer to data buffer
Size: Amount of data to be received

Return values

HAL: status

Notes

The USART DMA transmit stream must be configured in
order to generate the clock for the slave.
When the USART parity is enabled (PCE = 1) the data
received contain the parity bit.

HAL_USART_TransmitReceive_DMA
Function Name

HAL_StatusTypeDef HAL_USART_TransmitReceive_DMA
(USART_HandleTypeDef * husart, uint8_t * pTxData, uint8_t *
pRxData, uint16_t Size)

Function Description

Full-Duplex Transmit Receive an amount of data in non-blocking
mode.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.
pTxData: Pointer to data transmitted buffer
pRxData: Pointer to data received buffer

DocID025834 Rev 4

941/964

HAL USART Generic Driver

UM1725
Size: Amount of data to be received

Return values

HAL: status

Notes

When the USART parity is enabled (PCE = 1) the data
received contain the parity bit.

HAL_USART_DMAPause
Function Name

HAL_StatusTypeDef HAL_USART_DMAPause
(USART_HandleTypeDef * husart)

Function Description

Pauses the DMA Transfer.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

HAL: status

HAL_USART_DMAResume
Function Name

HAL_StatusTypeDef HAL_USART_DMAResume
(USART_HandleTypeDef * husart)

Function Description

Resumes the DMA Transfer.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

HAL: status

HAL_USART_DMAStop
Function Name

HAL_StatusTypeDef HAL_USART_DMAStop
(USART_HandleTypeDef * husart)

Function Description

Stops the DMA Transfer.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

HAL: status

HAL_USART_IRQHandler

942/964

Function Name

void HAL_USART_IRQHandler (USART_HandleTypeDef *
husart)

Function Description

This function handles USART interrupt request.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

None

DocID025834 Rev 4

UM1725

HAL USART Generic Driver

HAL_USART_TxCpltCallback
Function Name

void HAL_USART_TxCpltCallback (USART_HandleTypeDef *
husart)

Function Description

Tx Transfer completed callbacks.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

None

HAL_USART_TxHalfCpltCallback
Function Name

void HAL_USART_TxHalfCpltCallback
(USART_HandleTypeDef * husart)

Function Description

Tx Half Transfer completed callbacks.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

None

HAL_USART_RxCpltCallback
Function Name

void HAL_USART_RxCpltCallback (USART_HandleTypeDef *
husart)

Function Description

Rx Transfer completed callbacks.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

None

HAL_USART_RxHalfCpltCallback
Function Name

void HAL_USART_RxHalfCpltCallback
(USART_HandleTypeDef * husart)

Function Description

Rx Half Transfer completed callbacks.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

None

HAL_USART_TxRxCpltCallback
Function Name

void HAL_USART_TxRxCpltCallback (USART_HandleTypeDef
* husart)

Function Description

Tx/Rx Transfers completed callback for the non-blocking process.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
DocID025834 Rev 4

943/964

HAL USART Generic Driver

UM1725
USART module.

Return values

None

HAL_USART_ErrorCallback
Function Name

void HAL_USART_ErrorCallback (USART_HandleTypeDef *
husart)

Function Description

USART error callbacks.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

None

HAL_USART_GetState
Function Name

HAL_USART_StateTypeDef HAL_USART_GetState
(USART_HandleTypeDef * husart)

Function Description

Returns the USART state.

Parameters

husart: pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART module.

Return values

HAL: state

HAL_USART_GetError
Function Name

uint32_t HAL_USART_GetError (USART_HandleTypeDef *
husart)

Function Description

Return the USART error code.

Parameters

husart: : pointer to a USART_HandleTypeDef structure that
contains the configuration information for the specified
USART.

Return values

USART: Error Code

65.3

USART Firmware driver defines

65.3.1

USART
USART Clock
USART_CLOCK_DISABLE
USART_CLOCK_ENABLE
USART Clock Phase
USART_PHASE_1EDGE
USART_PHASE_2EDGE
USART Clock Polarity
USART_POLARITY_LOW

944/964

DocID025834 Rev 4

UM1725

HAL USART Generic Driver
USART_POLARITY_HIGH
USART Error Code
HAL_USART_ERROR_NONE

No error

HAL_USART_ERROR_PE

Parity error

HAL_USART_ERROR_NE

Noise error

HAL_USART_ERROR_FE

Frame error

HAL_USART_ERROR_ORE

Overrun error

HAL_USART_ERROR_DMA

DMA transfer error

USART Exported Macros
__HAL_USART_RESET_HANDLE_STATE

Description:
Reset USART handle state.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3 or
6 to select the USART peripheral.
Return value:
None
Description:

__HAL_USART_GET_FLAG

Checks whether the specified
Smartcard flag is set or not.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3 or
6 to select the USART peripheral.
__FLAG__: specifies the flag to
check. This parameter can be one
of the following values:
USART_FLAG_TXE: Transmit
data register empty flag
USART_FLAG_TC:
Transmission Complete flag
USART_FLAG_RXNE:
Receive data register not
empty flag
USART_FLAG_IDLE: Idle Line
detection flag
USART_FLAG_ORE: Overrun
Error flag
USART_FLAG_NE: Noise
Error flag
USART_FLAG_FE: Framing
Error flag
USART_FLAG_PE: Parity
DocID025834 Rev 4

945/964

HAL USART Generic Driver

UM1725
Error flag
Return value:
The: new state of __FLAG__
(TRUE or FALSE).

__HAL_USART_CLEAR_FLAG

Description:
Clears the specified Smartcard
pending flags.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3 or
6 to select the USART peripheral.
__FLAG__: specifies the flag to
check. This parameter can be any
combination of the following values:
USART_FLAG_TC:
Transmission Complete flag.
USART_FLAG_RXNE:
Receive data register not
empty flag.
Return value:
None
Notes:
PE (Parity error), FE (Framing
error), NE (Noise error), ORE
(Overrun error) and IDLE (Idle line
detected) flags are cleared by
software sequence: a read
operation to USART_SR register
followed by a read operation to
USART_DR register. RXNE flag
can be also cleared by a read to the
USART_DR register. TC flag can
be also cleared by software
sequence: a read operation to
USART_SR register followed by a
write operation to USART_DR
register. TXE flag is cleared only by
a write to the USART_DR register.

__HAL_USART_CLEAR_PEFLAG

Description:
Clear the USART PE pending flag.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3 or
6 to select the USART peripheral.
Return value:

946/964

DocID025834 Rev 4

UM1725

HAL USART Generic Driver
None
__HAL_USART_CLEAR_FEFLAG

Description:
Clear the USART FE pending flag.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3 or
6 to select the USART peripheral.
Return value:
None

__HAL_USART_CLEAR_NEFLAG

Description:
Clear the USART NE pending flag.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3 or
6 to select the USART peripheral.
Return value:
None

__HAL_USART_CLEAR_OREFLAG

Description:
Clear the UART ORE pending flag.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3 or
6 to select the USART peripheral.
Return value:
None

__HAL_USART_CLEAR_IDLEFLAG

Description:
Clear the USART IDLE pending
flag.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3 or
6 to select the USART peripheral.
Return value:
None

__HAL_USART_ENABLE_IT

Description:
Enables or disables the specified
USART interrupts.

DocID025834 Rev 4

947/964

HAL USART Generic Driver

UM1725
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3 or
6 to select the USART peripheral.
__INTERRUPT__: specifies the
USART interrupt source to check.
This parameter can be one of the
following values:
USART_IT_TXE: Transmit
Data Register empty interrupt
USART_IT_TC: Transmission
complete interrupt
USART_IT_RXNE: Receive
Data register not empty
interrupt
USART_IT_IDLE: Idle line
detection interrupt
USART_IT_PE: Parity Error
interrupt
USART_IT_ERR: Error
interrupt(Frame error, noise
error, overrun error) This
parameter can be: ENABLE or
DISABLE.
Return value:
None

__HAL_USART_DISABLE_IT
__HAL_USART_GET_IT_SOURCE

Description:
Checks whether the specified
USART interrupt has occurred or
not.
Parameters:
__HANDLE__: specifies the
USART Handle. This parameter
can be USARTx where x: 1, 2, 3 or
6 to select the USART peripheral.
__IT__: specifies the USART
interrupt source to check. This
parameter can be one of the
following values:
USART_IT_TXE: Transmit
Data Register empty interrupt
USART_IT_TC: Transmission
complete interrupt
USART_IT_RXNE: Receive
Data register not empty
interrupt
USART_IT_IDLE: Idle line
detection interrupt

948/964

DocID025834 Rev 4

UM1725

HAL USART Generic Driver
USART_IT_ERR: Error
interrupt
USART_IT_PE: Parity Error
interrupt
Return value:
The: new state of __IT__ (TRUE or
FALSE).
__HAL_USART_ONE_BIT_SAMPLE_ENABLE

Description:
Macro to enable the USART's one
bit sample method.
Parameters:
__HANDLE__: specifies the
USART Handle.
Return value:
None

__HAL_USART_ONE_BIT_SAMPLE_DISABLE

Description:
Macro to disable the USART's one
bit sample method.
Parameters:
__HANDLE__: specifies the
USART Handle.
Return value:
None
Description:

__HAL_USART_ENABLE

Enable USART.
Parameters:
__HANDLE__: specifies the
USART Handle. USART Handle
selects the USARTx peripheral
(USART availability and x value
depending on device).
Return value:
None
Description:

__HAL_USART_DISABLE

Disable USART.
Parameters:
__HANDLE__: specifies the
USART Handle. USART Handle
selects the USARTx peripheral
(USART availability and x value
depending on device).

DocID025834 Rev 4

949/964

HAL USART Generic Driver

UM1725
Return value:
None

USART Flags
USART_FLAG_TXE
USART_FLAG_TC
USART_FLAG_RXNE
USART_FLAG_IDLE
USART_FLAG_ORE
USART_FLAG_NE
USART_FLAG_FE
USART_FLAG_PE
USART Interrupts Definition
USART_IT_PE
USART_IT_TXE
USART_IT_TC
USART_IT_RXNE
USART_IT_IDLE
USART_IT_LBD
USART_IT_CTS
USART_IT_ERR
USART Last Bit
USART_LASTBIT_DISABLE
USART_LASTBIT_ENABLE
USART Mode
USART_MODE_RX
USART_MODE_TX
USART_MODE_TX_RX
USART NACK State
USART_NACK_ENABLE
USART_NACK_DISABLE
USART Parity
USART_PARITY_NONE
USART_PARITY_EVEN
USART_PARITY_ODD
USART Number of Stop Bits
USART_STOPBITS_1

950/964

DocID025834 Rev 4

UM1725

HAL USART Generic Driver
USART_STOPBITS_0_5
USART_STOPBITS_2
USART_STOPBITS_1_5
USART Word Length
USART_WORDLENGTH_8B
USART_WORDLENGTH_9B

DocID025834 Rev 4

951/964

HAL WWDG Generic Driver

UM1725

66

HAL WWDG Generic Driver

66.1

WWDG Firmware driver registers structures

66.1.1

WWDG_InitTypeDef
Data Fields
uint32_t Prescaler
uint32_t Window
uint32_t Counter
uint32_t EWIMode

Field Documentation
uint32_t WWDG_InitTypeDef::Prescaler
Specifies the prescaler value of the WWDG. This parameter can be a value of
WWDG_Prescaler
uint32_t WWDG_InitTypeDef::Window
Specifies the WWDG window value to be compared to the downcounter. This
parameter must be a number Min_Data = 0x40 and Max_Data = 0x7F
uint32_t WWDG_InitTypeDef::Counter
Specifies the WWDG free-running downcounter value. This parameter must be a
number between Min_Data = 0x40 and Max_Data = 0x7F
uint32_t WWDG_InitTypeDef::EWIMode
Specifies if WWDG Early Wakeup Interupt is enable or not. This parameter can be a
value of WWDG_EWI_Mode

66.1.2

WWDG_HandleTypeDef
Data Fields
WWDG_TypeDef * Instance
WWDG_InitTypeDef Init

Field Documentation
WWDG_TypeDef* WWDG_HandleTypeDef::Instance
Register base address
WWDG_InitTypeDef WWDG_HandleTypeDef::Init
WWDG required parameters

952/964

DocID025834 Rev 4

UM1725

HAL WWDG Generic Driver

66.2

WWDG Firmware driver API description

66.2.1

WWDG specific features
Once enabled the WWDG generates a system reset on expiry of a programmed time
period, unless the program refreshes the counter (downcounter) before reaching 0x3F
value (i.e. a reset is generated when the counter value rolls over from 0x40 to 0x3F).
An MCU reset is also generated if the counter value is refreshed before the counter
has reached the refresh window value. This implies that the counter must be refreshed
in a limited window.
Once enabled the WWDG cannot be disabled except by a system reset.
WWDGRST flag in RCC_CSR register can be used to inform when a WWDG reset
occurs.
The WWDG counter input clock is derived from the APB clock divided by a
programmable prescaler.
WWDG clock (Hz) = PCLK1 / (4096 * Prescaler)
WWDG timeout (mS) = 1000 * Counter / WWDG clock
WWDG Counter refresh is allowed between the following limits :
min time (mS) = 1000 * (Counter _ Window) / WWDG clock
max time (mS) = 1000 * (Counter _ 0x40) / WWDG clock
Min-max timeout value at 50 MHz(PCLK1): 81.9 us / 41.9 ms
The Early Wakeup Interrupt (EWI) can be used if specific safety operations or data
logging must be performed before the actual reset is generated. When the
downcounter reaches the value 0x40, an EWI interrupt is generated and the
corresponding interrupt service routine (ISR) can be used to trigger specific actions
(such as communications or data logging), before resetting the device. In some
applications, the EWI interrupt can be used to manage a software system check
and/or system recovery/graceful degradation, without generating a WWDG reset. In
this case, the corresponding interrupt service routine (ISR) should reload the WWDG
counter to avoid the WWDG reset, then trigger the required actions. Note:When the
EWI interrupt cannot be served, e.g. due to a system lock in a higher priority task, the
WWDG reset will eventually be generated.
Debug mode : When the microcontroller enters debug mode (core halted), the
WWDG counter either continues to work normally or stops, depending on
DBG_WWDG_STOP configuration bit in DBG module, accessible through
__HAL_DBGMCU_FREEZE_WWDG() and __HAL_DBGMCU_UNFREEZE_WWDG()
macros

66.2.2

How to use this driver
Enable WWDG APB1 clock using __HAL_RCC_WWDG_CLK_ENABLE().
Set the WWDG prescaler, refresh window, counter value and Early Wakeup Interrupt
mode using using HAL_WWDG_Init() function. This enables WWDG peripheral and
the downcounter starts downcounting from given counter value. Init function can be
called again to modify all watchdog parameters, however if EWI mode has been set
once, it can't be clear until next reset.
The application program must refresh the WWDG counter at regular intervals during
normal operation to prevent an MCU reset using HAL_WWDG_Refresh() function.
This operation must occur only when the counter is lower than the window value
already programmed.
if Early Wakeup Interrupt mode is enable an interrupt is generated when the counter
reaches 0x40. User can add his own code in weak function
HAL_WWDG_EarlyWakeupCallback().
DocID025834 Rev 4

953/964

HAL WWDG Generic Driver

UM1725

WWDG HAL driver macros list
Below the list of most used macros in WWDG HAL driver.
__HAL_WWDG_GET_IT_SOURCE: Check the selected WWDG's interrupt source.
__HAL_WWDG_GET_FLAG: Get the selected WWDG's flag status.
__HAL_WWDG_CLEAR_FLAG: Clear the WWDG's pending flags.

66.2.3

Initialization and Configuration functions
This section provides functions allowing to:
Initialize and start the WWDG according to the specified parameters in the
WWDG_InitTypeDef of associated handle.
Initialize the WWDG MSP.
This section contains the following APIs:
HAL_WWDG_Init()
HAL_WWDG_MspInit()

66.2.4

IO operation functions
This section provides functions allowing to:
Refresh the WWDG.
Handle WWDG interrupt request and associated function callback.
This section contains the following APIs:
HAL_WWDG_Refresh()
HAL_WWDG_IRQHandler()
HAL_WWDG_EarlyWakeupCallback()

66.2.5

Detailed description of functions
HAL_WWDG_Init
Function Name

HAL_StatusTypeDef HAL_WWDG_Init
(WWDG_HandleTypeDef * hwwdg)

Function Description

Initialize the WWDG according to the specified.

Parameters

hwwdg: pointer to a WWDG_HandleTypeDef structure that
contains the configuration information for the specified
WWDG module.

Return values

HAL: status

HAL_WWDG_MspInit

954/964

Function Name

void HAL_WWDG_MspInit (WWDG_HandleTypeDef * hwwdg)

Function Description

Initialize the WWDG MSP.

Parameters

hwwdg: pointer to a WWDG_HandleTypeDef structure that
contains the configuration information for the specified
WWDG module.

Return values

None

Notes

When rewriting this function in user file, mechanism may be
DocID025834 Rev 4

UM1725

HAL WWDG Generic Driver
added to avoid multiple initialize when HAL_WWDG_Init
function is called again to change parameters.

HAL_WWDG_Refresh
Function Name

HAL_StatusTypeDef HAL_WWDG_Refresh
(WWDG_HandleTypeDef * hwwdg)

Function Description

Refresh the WWDG.

Parameters

hwwdg: pointer to a WWDG_HandleTypeDef structure that
contains the configuration information for the specified
WWDG module.

Return values

HAL: status

HAL_WWDG_IRQHandler
Function Name

void HAL_WWDG_IRQHandler (WWDG_HandleTypeDef *
hwwdg)

Function Description

Handle WWDG interrupt request.

Parameters

hwwdg: pointer to a WWDG_HandleTypeDef structure that
contains the configuration information for the specified
WWDG module.

Return values

None

Notes

The Early Wakeup Interrupt (EWI) can be used if specific
safety operations or data logging must be performed before
the actual reset is generated. The EWI interrupt is enabled by
calling HAL_WWDG_Init function with EWIMode set to
WWDG_EWI_ENABLE. When the downcounter reaches the
value 0x40, and EWI interrupt is generated and the
corresponding Interrupt Service Routine (ISR) can be used to
trigger specific actions (such as communications or data
logging), before resetting the device.

HAL_WWDG_EarlyWakeupCallback
Function Name

void HAL_WWDG_EarlyWakeupCallback
(WWDG_HandleTypeDef * hwwdg)

Function Description

WWDG Early Wakeup callback.

Parameters

hwwdg: : pointer to a WWDG_HandleTypeDef structure that
contains the configuration information for the specified
WWDG module.

Return values

None

66.3

WWDG Firmware driver defines

66.3.1

WWDG
WWDG Early Wakeup Interrupt Mode
WWDG_EWI_DISABLE

EWI Disable
DocID025834 Rev 4

955/964

HAL WWDG Generic Driver
WWDG_EWI_ENABLE

UM1725
EWI Enable

WWDG Exported Macros
Description:

__HAL_WWDG_ENABLE

Enables the WWDG peripheral.
Parameters:
__HANDLE__: WWDG handle
Return value:
None
__HAL_WWDG_ENABLE_IT

Description:
Enables the WWDG early wakeup interrupt.
Parameters:
__HANDLE__: WWDG handle
__INTERRUPT__: specifies the interrupt to
enable. This parameter can be one of the
following values:
WWDG_IT_EWI: Early wakeup interrupt
Return value:
None
Notes:
Once enabled this interrupt cannot be disabled
except by a system reset.

__HAL_WWDG_GET_IT

Description:
Checks whether the selected WWDG interrupt
has occurred or not.
Parameters:
__HANDLE__: WWDG handle
__INTERRUPT__: specifies the it to check. This
parameter can be one of the following values:
WWDG_FLAG_EWIF: Early wakeup
interrupt IT
Return value:
The: new state of WWDG_FLAG (SET or
RESET).

__HAL_WWDG_CLEAR_IT

Description:
Clear the WWDG's interrupt pending bits bits to
clear the selected interrupt pending bits.
Parameters:
__HANDLE__: WWDG handle
__INTERRUPT__: specifies the interrupt
pending bit to clear. This parameter can be one
of the following values:

956/964

DocID025834 Rev 4

UM1725

HAL WWDG Generic Driver
WWDG_FLAG_EWIF: Early wakeup
interrupt flag
Description:

__HAL_WWDG_GET_FLAG

Check whether the specified WWDG flag is set
or not.
Parameters:
__HANDLE__: WWDG handle
__FLAG__: specifies the flag to check. This
parameter can be one of the following values:
WWDG_FLAG_EWIF: Early wakeup
interrupt flag
Return value:
The: new state of WWDG_FLAG (SET or
RESET).
__HAL_WWDG_CLEAR_FLAG

Description:
Clears the WWDG's pending flags.
Parameters:
__HANDLE__: WWDG handle
__FLAG__: specifies the flag to clear. This
parameter can be one of the following values:
WWDG_FLAG_EWIF: Early wakeup
interrupt flag
Return value:
None

__HAL_WWDG_GET_IT_SOURCE

Description:
Checks if the specified WWDG interrupt source
is enabled or disabled.
Parameters:
__HANDLE__: WWDG Handle.
__INTERRUPT__: specifies the WWDG
interrupt source to check. This parameter can
be one of the following values:
WWDG_IT_EWI: Early Wakeup Interrupt
Return value:
state: of __INTERRUPT__ (TRUE or FALSE).

WWDG Flag definition
WWDG_FLAG_EWIF

Early wakeup interrupt flag

WWDG Interrupt definition
WWDG_IT_EWI

Early wakeup interrupt

WWDG Prescaler
WWDG_PRESCALER_1

WWDG counter clock = (PCLK1/4096)/1

DocID025834 Rev 4

957/964

HAL WWDG Generic Driver
WWDG_PRESCALER_2

WWDG counter clock = (PCLK1/4096)/2

WWDG_PRESCALER_4

WWDG counter clock = (PCLK1/4096)/4

WWDG_PRESCALER_8

WWDG counter clock = (PCLK1/4096)/8

958/964

UM1725

DocID025834 Rev 4

UM1725

67

FAQs

FAQs
General subjects
Why should I use the HAL drivers?
There are many advantages in using the HAL drivers:
Ease of use: you can use the HAL drivers to configure and control any peripheral
embedded within your STM32 MCU without prior in-depth knowledge of the product.
HAL drivers provide intuitive and ready-to-use APIs to configure the peripherals and
support polling, interrupt and DMA programming model to accommodate all
application requirements, thus allowing the end-user to build a complete application by
calling a few APIs.
Higher level of abstraction than a standard peripheral library allowing to transparently
manage:
Data transfers and processing using blocking mode (polling) or non-blocking
mode (interrupt or DMA)
Error management through peripheral error detection and timeout mechanism.
Generic architecture speeding up initialization and porting, thus allowing customers to
focus on innovation.
Generic set of APIs with full compatibility across the STM32 series/lines, to ease the
porting task between STM32 MCUs.
The APIs provided within the HAL drivers are feature-oriented and do not required indepth knowledge of peripheral operation.
The APIs provided are modular. They include initialization, IO operation and control
functions. The end-user has to call init function, then start the process by calling one
IO operation functions (write, read, transmit, receive, …). Most of the peripherals have
the same architecture.
The number of functions required to build a complete and useful application is very
reduced. As an example, to build a UART communication process, the user only has
to call HAL_UART_Init() then HAL_UART_Transmit() or HAL_UART_Receive().

Which STM32F4 devices are supported by the HAL drivers?
The HAL drivers are developed to support all STM32F4 devices. To ensure compatibility
between all devices and portability with others series and lines, the API is split into the
generic and the extension APIs . For more details, please refer to Section 4.4: "Devices
supported by HAL drivers".

What is the cost of using HAL drivers in term of code size and performance?
Like generic architecture drivers, the HAL drivers may induce firmware overhead.
This is due to the high abstraction level and ready-to-use APIs which allow data transfers,
errors management and offloads the user application from implementation details.

Architecture
How many files should I modify to configure the HAL drivers?
Only one file needs to be modified: stm32f4xx_hal_conf.h. You can modify this file by
disabling unused modules, or adjusting some parameters (i.e. HSE value, System
configuration, Ethernet parameters configuration…)
DocID025834 Rev 4

959/964

FAQs

UM1725
A template is provided in the HAL drivers folders (stm32f4xx_hal_conf_template.c).

Which header files should I include in my application to use the HAL
drivers?
Only stm32f4xx_hal.h file has to be included.

What is the difference between stm32f4xx_hal_ppp.c/.h and
stm32f4xx_hal_ppp_ex.c/.h?
The HAL driver architecture supports common features across STM32 series/lines. To
support specific features, the drivers are split into two groups.
The generic APIs (stm32f4xx_hal_ppp.c): It includes the common set of APIs across
all the STM32 product lines
The extension APIs (stm32f4xx_hal_ppp_ex.c): It includes the specific APIs for
specific device part number or family.

Is it possible to use the APIs available in stm32f4xx_ll_ppp.c?
These APIs cannot be used directly because they are internal and offer services to upper
layer drivers. As an example stm32f4xx_ll_fmc.c/h driver is used by stm32f4xx_hal_sram.c,
stm32f4xx_hal_nor.c, stm32f4xx_hal_nand.c and stm32f4xx_hal_sdram.c drivers.

Initialization and I/O operation functions
How do I configure the system clock?
Unlike the standard library, the system clock configuration is not performed in CMSIS
drivers file (system_stm32f4xx.c) but in the main user application by calling the two main
functions, HAL_RCC_OscConfig() and HAL_RCC_ClockConfig(). It can be modified in any
user application section.

What is the purpose of the PPP_HandleTypeDef *pHandle structure located
in each driver in addition to the Initialization structure
PPP_HandleTypeDef *pHandle is the main structure implemented in the HAL drivers. It
handles the peripheral configuration and registers, and embeds all the structures and
variables required to follow the peripheral device flow (pointer to buffer, Error code,
State,...)
However, this structure is not required to service peripherals such as GPIO, SYSTICK,
PWR, and RCC.

What is the purpose of HAL_PPP_MspInit() and HAL_PPP_MspDeInit()
functions?
These function are called within HAL_PPP_Init() and HAL_PPP_DeInit(), respectively.
They are used to perform the low level Initialization/de-initialization related to the additional
hardware resources (RCC, GPIO, NVIC and DMA).
These functions are declared in stm32f4xx_hal_msp.c. A template is provided in the HAL
driver folders (stm32f4xx_hal_msp_template.c).

960/964

DocID025834 Rev 4

UM1725

FAQs

When and how should I use callbacks functions (functions declared with the
attribute __weak)?
Use callback functions for the I/O operations used in DMA or interrupt mode. The PPP
process complete callbacks are called to inform the user about process completion in realtime event mode (interrupts).
The Errors callbacks are called when a processing error occurs in DMA or interrupt mode.
These callbacks are customized by the user to add user proprietary code. They can be
declared in the application. Note that the same process completion callbacks are used for
DMA and interrupt mode.

Is it mandatory to use HAL_Init() function at the beginning of the user
application?
It is mandatory to use HAL_Init() function to enable the system configuration (Prefetch,
Data instruction cache,…), configure the systTick and the NVIC priority grouping and the
hardware low level initialization.
The sysTick configuration shall be adjusted by calling HAL_RCC_ClockConfig() function,
to obtain 1 ms whatever the system clock.

Why do I need to configure the SysTick timer to use the HAL drivers?
The SysTick timer is configured to be used to generate variable increments by calling
HAL_IncTick() function in Systick ISR and retrieve the value of this variable by calling
HAL_GetTick() function.
The call HAL_GetTick() function is mandatory when using HAL drivers with Polling
Process or when using HAL_Delay().

Why is the SysTick timer configured to have 1 ms?
This is mandatory to ensure correct IO operation in particular for polling mode operation
where the 1 ms is required as timebase.

Could HAL_Delay() function block my application under certain conditions?
Care must be taken when using HAL_Delay() since this function provides accurate delay
based on a variable incremented in SysTick ISR. This implies that if HAL_Delay() is called
from a peripheral ISR process, then the SysTick interrupt must have higher priority
(numerically lower) than the peripheral interrupt, otherwise the caller ISR process will be
blocked. Use HAL_NVIC_SetPriority() function to change the SysTick interrupt priority.

What programming model sequence should I follow to use HAL drivers ?
Follow the sequence below to use the APIs provided in the HAL drivers:
1.
2.
3.
4.
5.
6.

Call HAL_Init() function to initialize the system (data cache, NVIC priority,…).
Initialize the system clock by calling HAL_RCC_OscConfig() followed by
HAL_RCC_ClockConfig().
Add HAL_IncTick() function under SysTick_Handler() ISR function to enable polling
process when using HAL_Delay() function
Start initializing your peripheral by calling HAL_PPP_Init().
Implement the hardware low level initialization (Peripheral clock, GPIO, DMA,..) by
calling HAL_PPP_MspInit() in stm32f4xx_hal_msp.c
Start your process operation by calling IO operation functions.

DocID025834 Rev 4

961/964

FAQs

UM1725

What is the purpose of HAL_PPP_IRQHandler() function and when should I
use it?
HAL_PPP_IRQHandler() is used to handle interrupt process. It is called under
PPP_IRQHandler() function in stm32f4xx_it.c. In this case, the end-user has to implement
only the callbacks functions (prefixed by __weak) to perform the appropriate action when
an interrupt is detected. Advanced users can implement their own code in
PPP_IRQHandler() without calling HAL_PPP_IRQHandler().

Can I use directly the macros defined in stm32f4xx_hal_ppp.h ?
Yes, you can: a set of macros is provided with the APIs. They allow accessing directly
some specific features using peripheral flags.

Where must PPP_HandleTypedef structure peripheral handler be declared?
PPP_HandleTypedef structure peripheral handler must be declared as a global variable, so
that all the structure fields are set to 0 by default. In this way, the peripheral handler default
state are set to HAL_PPP_STATE_RESET, which is the default state for each peripheral
after a system reset.

962/964

DocID025834 Rev 4

UM1725

68

Revision history

Revision history
Table 16: Document revision history
Date

Revision

05-May-2014

1

Initial release.

2

Added CEC, FMPI2C, QSPI and SPDIFRX in Table 1: "Acronyms
and definitions".
Added STM32F446xx, cec, dcmi, fmpi2c, fmpi2c_ex, spdifrx and
qspi in Table 5: "List of devices supported by HAL drivers".
Updated Common macros section in Section 4.9: "HAL common
resources".
Added Section 9: "HAL CEC Generic Driver", Section 26: "HAL
FLASH__RAMFUNC Generic Driver"Section 27: "HAL FMPI2C
Generic Driver", Section 28: "HAL FMPI2C Extension Driver",
Section 50: "HAL QSPI Generic Driver" and Section 61: "HAL
SPDIFRX Generic Driver".

3

Added DSI and LPTIM and removed msp_template in Table 1:
"Acronyms and definitions".
Added STM32F469xx, STM32F479xx, STM32F410xx, dsi, ltdc_ex
and lptim in Table 5: "List of devices supported by HAL drivers".
Added Section 22: "HAL DSI Generic Driver", Section 40: "HAL
LPTIM Generic Driver" and Section 41: "HAL LTDC Generic
Driver".

4

Added DFSDM in Table 1: "Acronyms and definitions".
Added
STM32F412Cx,
STM32F412Rx,
STM32F412Vx,
STM32F412Zx and DFSDM in Table 5: "List of devices supported
by HAL drivers".
Added Section 16: "HAL DFSDM Generic Driver".

03-Apr-2015

15-Sep-2015

08-Sep-2016

Changes

DocID025834 Rev 4

963/964

UM1725

IMPORTANT NOTICE – PLEASE READ CAREFULLY
STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements,
modifications, and improvements to ST products and/or to this document at any time without notice. Purchasers should obtain
the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and
conditions of sale in place at the time of order acknowledgement.
Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application
assistance or the design of Purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for
such product.
ST and the ST logo are trademarks of ST. All other product or service names are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2016 STMicroelectronics – All rights reserved

964/964

DocID025834 Rev 4



Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
Tagged PDF                      : Yes
Language                        : fr-FR
Page Layout                     : SinglePage
Page Mode                       : UseNone
Page Count                      : 964
Creator                         : C2 v4.2.0220 build 670 - c2_rendition_config : Techlit_Active
Producer                        : 䵩捲潳潦璮⁗潲搠㈰㄰㬠浯摩晩敤⁵獩湧⁩呥硴′⸱⸷⁢礠ㅔ㍘
Title                           : Description of STM32F4xx HAL drivers
Keywords                        : Technical Literature, 025834, Product Development, Specification, User manual, STM32CubeF4
Modify Date                     : 2016:09:19 10:57:10+02:00
Subject                         : -
Author                          : STMICROELECTRONICS
Create Date                     : 2016:09:08 11:26:31+02:00
EXIF Metadata provided by EXIF.tools

Navigation menu