Description of STM32L1xx HAL drivers

Description of STM32L1xx HAL drivers

UM1816

User manual

Description of STM32L1xx HAL drivers

Introduction

STMCube

TM

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

STM32Cube Version 1.x includes:

The STM32CubeMX, a graphical software configuration tool that allows generating C initialization code using graphical wizards.

A comprehensive embedded software platform, delivered per series (such as STM32CubeL1 for

STM32L1 series)

The STM32Cube HAL, an STM32 abstraction layer embedded software, ensuring maximized portability across STM32 portfolio

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

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

The HAL drivers layer provides a generic multi instance simple set of APIs (application programming interfaces) to interact with the upper layer (application, libraries and stacks). It is composed of generic and extension APIs. It is directly built around a generic architecture and allows the built-upon layers, such as the middleware layer, to implement their functions without knowing in-depth how to use the

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

The HAL drivers include a complete set of ready-to-use APIs which simplify the user application implementation. As an example, the communication peripherals contain APIs to initialize and configure the peripheral, to manage data transfers based on polling, to handle interrupts or DMA, and to manage communication errors.

The HAL drivers APIs are split into two categories: generic APIs which provide common and generic functions for all the STM32 series and extension APIs which include specific and customized functions for a given family or part number.

The HAL drivers are feature-oriented instead of IP-oriented. As an example, the timer APIs are split into several categories following the functions offered by the IP: basic timer, capture, pulse width modulation

(PWM), etc..

The drivers source code is developed in Strict ANSI-C which makes it independent from the development tools. It is checked with CodeSonar

TM

static analysis tool. It is fully documented and is

MISRA-C 2004 compliant.

The HAL drivers layer implements run-time failure detection by checking the input values of all functions. Such dynamic checking contributes to enhance the firmware robustness. Run-time detection is also suitable for user application development and debugging.

This user manual is structured as follows:

Overview of the HAL drivers

Detailed description of each peripheral driver: configuration structures, functions, and how to use the given API to build your application.

May 2015 DOCID026682 Rev 3 1/654

www.st.com

Contents

Contents

UM1816

1 Acronyms and definitions ............................................................. 37

2 Overview of HAL drivers ............................................................... 39

2.1

2.2

2.3

2.4

2.5

HAL and user-application files......................................................... 39

2.1.1

HAL driver files ................................................................................. 39

2.1.2

User-application files ........................................................................ 40

HAL data structures ........................................................................ 42

2.2.1

Peripheral handle structures ............................................................ 42

2.2.2

Initialization and configuration structure ........................................... 44

2.2.3

Specific process structures .............................................................. 44

API classification ............................................................................. 44

Devices supported by HAL drivers .................................................. 45

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

2.5.1

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

2.5.2

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

2.5.3

HAL interrupt handler and callback functions ................................... 52

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

2.7

2.8

2.9

HAL extension APIs ........................................................................ 54

2.7.1

HAL extension model overview ........................................................ 54

2.7.2

HAL extension model cases ............................................................. 54

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

HAL common resources .................................................................. 58

2.10

HAL configuration ............................................................................ 59

2.11

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

2.11.1

Clock ................................................................................................. 60

2.11.2

GPIOs ............................................................................................... 60

2.11.3

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

2.11.4

PWR ................................................................................................. 63

2.11.5

EXTI .................................................................................................. 63

2.11.6

DMA .................................................................................................. 64

2.12

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

2.12.1

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

2.12.2

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

2.12.3

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

2.12.4

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

3 HAL System Driver ........................................................................ 76

2/654 DOCID026682 Rev 3

UM1816 Contents

3.1

3.2

3.3

HAL System Driver .......................................................................... 76

HAL Firmware driver API description .............................................. 76

3.2.1

How to use this driver ....................................................................... 76

3.2.2

Initialization and de-initialization functions ....................................... 76

3.2.3

HAL Control functions....................................................................... 76

3.2.4

HAL_Init ............................................................................................ 77

3.2.5

HAL_DeInit ....................................................................................... 77

3.2.6

HAL_MspInit ..................................................................................... 77

3.2.7

HAL_MspDeInit ................................................................................ 78

3.2.8

HAL_InitTick ..................................................................................... 78

3.2.9

HAL_IncTick ..................................................................................... 78

3.2.10

HAL_GetTick .................................................................................... 78

3.2.11

HAL_Delay ....................................................................................... 78

3.2.12

HAL_SuspendTick ............................................................................ 79

3.2.13

HAL_ResumeTick ............................................................................. 79

3.2.14

HAL_GetHalVersion ......................................................................... 79

3.2.15

HAL_GetREVID ................................................................................ 79

3.2.16

HAL_GetDEVID ................................................................................ 80

3.2.17

HAL_DBGMCU_EnableDBGSleepMode ......................................... 80

3.2.18

HAL_DBGMCU_DisableDBGSleepMode ........................................ 80

3.2.19

HAL_DBGMCU_EnableDBGStopMode ........................................... 80

3.2.20

HAL_DBGMCU_DisableDBGStopMode .......................................... 80

3.2.21

HAL_DBGMCU_EnableDBGStandbyMode ..................................... 80

3.2.22

HAL_DBGMCU_DisableDBGStandbyMode .................................... 80

HAL Firmware driver defines ........................................................... 80

3.3.1

HAL ................................................................................................... 80

4 HAL ADC Generic Driver ............................................................... 82

4.1

4.2

4.3

HAL ADC Generic Driver ................................................................ 82

ADC Firmware driver registers structures ....................................... 82

4.2.1

ADC_InitTypeDef .............................................................................. 82

4.2.2

ADC_ChannelConfTypeDef ............................................................. 84

4.2.3

ADC_AnalogWDGConfTypeDef ....................................................... 85

4.2.4

ADC_HandleTypeDef ....................................................................... 86

ADC Firmware driver API description .............................................. 86

4.3.1

ADC peripheral features ................................................................... 86

4.3.2

How to use this driver ....................................................................... 87

4.3.3

Initialization and de-initialization functions ....................................... 90

DOCID026682 Rev 3 3/654

Contents

4.4

UM1816

4.3.4

IO operation functions ...................................................................... 90

4.3.5

Peripheral Control functions ............................................................. 90

4.3.6

Peripheral State and Errors functions .............................................. 91

4.3.7

HAL_ADC_Init .................................................................................. 91

4.3.8

HAL_ADC_DeInit .............................................................................. 91

4.3.9

HAL_ADC_MspInit ........................................................................... 92

4.3.10

HAL_ADC_MspDeInit ....................................................................... 92

4.3.11

HAL_ADC_Start ............................................................................... 92

4.3.12

HAL_ADC_Stop ................................................................................ 92

4.3.13

HAL_ADC_PollForConversion ......................................................... 92

4.3.14

HAL_ADC_PollForEvent .................................................................. 93

4.3.15

HAL_ADC_Start_IT .......................................................................... 93

4.3.16

HAL_ADC_Stop_IT .......................................................................... 93

4.3.17

HAL_ADC_Start_DMA ..................................................................... 93

4.3.18

HAL_ADC_Stop_DMA...................................................................... 94

4.3.19

HAL_ADC_GetValue ........................................................................ 94

4.3.20

HAL_ADC_IRQHandler .................................................................... 94

4.3.21

HAL_ADC_ConvCpltCallback .......................................................... 94

4.3.22

HAL_ADC_ConvHalfCpltCallback .................................................... 94

4.3.23

HAL_ADC_LevelOutOfWindowCallback .......................................... 95

4.3.24

HAL_ADC_ErrorCallback ................................................................. 95

4.3.25

HAL_ADC_ConfigChannel ............................................................... 95

4.3.26

HAL_ADC_AnalogWDGConfig ........................................................ 95

4.3.27

HAL_ADC_GetState ......................................................................... 96

4.3.28

HAL_ADC_GetError ......................................................................... 96

ADC Firmware driver defines .......................................................... 96

4.4.1

ADC .................................................................................................. 96

5 HAL ADC Extension Driver ......................................................... 111

5.1

5.2

5.3

HAL ADC Extension Driver ........................................................... 111

ADCEx Firmware driver registers structures ................................. 111

5.2.1

ADC_InjectionConfTypeDef ........................................................... 111

ADCEx Firmware driver API description ....................................... 113

5.3.1

IO operation functions .................................................................... 113

5.3.2

Peripheral Control functions ........................................................... 113

5.3.3

HAL_ADCEx_InjectedStart ............................................................ 113

5.3.4

HAL_ADCEx_InjectedStop ............................................................. 113

5.3.5

HAL_ADCEx_InjectedPollForConversion ...................................... 114

5.3.6

HAL_ADCEx_InjectedStart_IT ....................................................... 114

4/654 DOCID026682 Rev 3

UM1816 Contents

5.4

5.3.7

HAL_ADCEx_InjectedStop_IT ....................................................... 114

5.3.8

HAL_ADCEx_InjectedGetValue ..................................................... 114

5.3.9

HAL_ADCEx_InjectedConvCpltCallback ....................................... 114

5.3.10

HAL_ADCEx_InjectedConfigChannel ............................................ 115

ADCEx Firmware driver defines .................................................... 115

5.4.1

ADCEx ............................................................................................ 115

6 HAL COMP Generic Driver .......................................................... 120

6.1

6.2

6.3

6.4

HAL COMP Generic Driver ........................................................... 120

COMP Firmware driver registers structures .................................. 120

6.2.1

COMP_InitTypeDef ........................................................................ 120

6.2.2

COMP_HandleTypeDef .................................................................. 121

COMP Firmware driver API description ........................................ 121

6.3.1

COMP Peripheral features ............................................................. 121

6.3.2

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

6.3.3

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

6.3.4

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

6.3.5

Peripheral Control functions ........................................................... 123

6.3.6

Peripheral State functions .............................................................. 124

6.3.7

HAL_COMP_Init ............................................................................. 124

6.3.8

HAL_COMP_DeInit ........................................................................ 124

6.3.9

HAL_COMP_MspInit ...................................................................... 124

6.3.10

HAL_COMP_MspDeInit.................................................................. 124

6.3.11

HAL_COMP_Start .......................................................................... 124

6.3.12

HAL_COMP_Stop .......................................................................... 125

6.3.13

HAL_COMP_Start_IT ..................................................................... 125

6.3.14

HAL_COMP_Stop_IT ..................................................................... 125

6.3.15

HAL_COMP_IRQHandler ............................................................... 125

6.3.16

HAL_COMP_Lock .......................................................................... 125

6.3.17

HAL_COMP_GetOutputLevel ........................................................ 126

6.3.18

HAL_COMP_TriggerCallback ........................................................ 126

6.3.19

HAL_COMP_GetState.................................................................... 126

COMP Firmware driver defines ..................................................... 126

6.4.1

COMP ............................................................................................. 126

7 HAL COMP Extension Driver ...................................................... 134

7.1

7.2

HAL COMP Extension Driver ........................................................ 134

COMPEx Firmware driver defines ................................................. 134

7.2.1

COMPEx ......................................................................................... 134

DOCID026682 Rev 3 5/654

Contents UM1816

8 HAL CORTEX Generic Driver ...................................................... 137

8.1

9.3

HAL CORTEX Generic Driver ....................................................... 137

8.2

8.3

8.4

CORTEX Firmware driver registers structures .............................. 137

8.2.1

MPU_Region_InitTypeDef .............................................................. 137

CORTEX Firmware driver API description .................................... 138

8.3.1

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

8.3.2

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

8.3.3

HAL_NVIC_SetPriorityGrouping .................................................... 138

8.3.4

HAL_NVIC_SetPriority ................................................................... 139

8.3.5

HAL_NVIC_EnableIRQ .................................................................. 139

8.3.6

HAL_NVIC_DisableIRQ.................................................................. 139

8.3.7

HAL_NVIC_SystemReset............................................................... 139

8.3.8

HAL_SYSTICK_Config ................................................................... 140

8.3.9

HAL_MPU_ConfigRegion ............................................................... 140

8.3.10

HAL_NVIC_GetPriorityGrouping .................................................... 140

8.3.11

HAL_NVIC_GetPriority ................................................................... 140

8.3.12

HAL_NVIC_SetPendingIRQ ........................................................... 141

8.3.13

HAL_NVIC_GetPendingIRQ .......................................................... 141

8.3.14

HAL_NVIC_ClearPendingIRQ ........................................................ 141

8.3.15

HAL_NVIC_GetActive .................................................................... 141

8.3.16

HAL_SYSTICK_CLKSourceConfig ................................................ 142

8.3.17

HAL_SYSTICK_IRQHandler .......................................................... 142

8.3.18

HAL_SYSTICK_Callback ............................................................... 142

CORTEX Firmware driver defines ................................................. 142

8.4.1

CORTEX ......................................................................................... 142

9 HAL CRC Generic Driver ............................................................. 146

9.1

9.2

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

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

9.2.1

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

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

9.3.1

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

9.3.2

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

9.3.3

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

9.3.4

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

9.3.5

HAL_CRC_Init ................................................................................ 147

9.3.6

HAL_CRC_DeInit ........................................................................... 147

9.3.7

HAL_CRC_MspInit ......................................................................... 147

6/654 DOCID026682 Rev 3

UM1816 Contents

9.4

9.3.8

HAL_CRC_MspDeInit..................................................................... 148

9.3.9

HAL_CRC_Accumulate .................................................................. 148

9.3.10

HAL_CRC_Calculate ...................................................................... 148

9.3.11

HAL_CRC_GetState ....................................................................... 148

9.3.12

HAL_CRC_Accumulate .................................................................. 148

9.3.13

HAL_CRC_Calculate ...................................................................... 149

CRC Firmware driver defines ........................................................ 149

9.4.1

CRC ................................................................................................ 149

10 HAL CRYP Generic Driver ........................................................... 151

10.1

HAL CRYP Generic Driver ............................................................ 151

10.2

CRYP Firmware driver registers structures ................................... 151

10.2.1

CRYP_InitTypeDef ......................................................................... 151

10.2.2

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

10.3

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

10.3.1

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

10.3.2

AES processing functions .............................................................. 152

10.3.3

DMA callback functions .................................................................. 153

10.3.4

CRYP IRQ handler management ................................................... 153

10.3.5

Peripheral State functions .............................................................. 153

10.3.6

HAL_CRYP_Init .............................................................................. 153

10.3.7

HAL_CRYP_DeInit ......................................................................... 154

10.3.8

HAL_CRYP_MspInit ....................................................................... 154

10.3.9

HAL_CRYP_MspDeInit .................................................................. 154

10.3.10

HAL_CRYP_AESECB_Encrypt ...................................................... 154

10.3.11

HAL_CRYP_AESCBC_Encrypt ..................................................... 154

10.3.12

HAL_CRYP_AESCTR_Encrypt ...................................................... 155

10.3.13

HAL_CRYP_AESECB_Decrypt ..................................................... 155

10.3.14

HAL_CRYP_AESCBC_Decrypt ..................................................... 155

10.3.15

HAL_CRYP_AESCTR_Decrypt ..................................................... 156

10.3.16

HAL_CRYP_AESECB_Encrypt_IT ................................................ 156

10.3.17

HAL_CRYP_AESCBC_Encrypt_IT ................................................ 156

10.3.18

HAL_CRYP_AESCTR_Encrypt_IT ................................................ 157

10.3.19

HAL_CRYP_AESECB_Decrypt_IT ................................................ 157

10.3.20

HAL_CRYP_AESCBC_Decrypt_IT ................................................ 157

10.3.21

HAL_CRYP_AESCTR_Decrypt_IT ................................................ 158

10.3.22

HAL_CRYP_AESECB_Encrypt_DMA ............................................ 158

10.3.23

HAL_CRYP_AESCBC_Encrypt_DMA ........................................... 158

10.3.24

HAL_CRYP_AESCTR_Encrypt_DMA ............................................ 159

DOCID026682 Rev 3 7/654

Contents UM1816

10.3.25

HAL_CRYP_AESECB_Decrypt_DMA ........................................... 159

10.3.26

HAL_CRYP_AESCBC_Decrypt_DMA ........................................... 159

10.3.27

HAL_CRYP_AESCTR_Decrypt_DMA ........................................... 160

10.3.28

HAL_CRYP_ErrorCallback ............................................................. 160

10.3.29

HAL_CRYP_InCpltCallback ........................................................... 160

10.3.30

HAL_CRYP_OutCpltCallback ........................................................ 160

10.3.31

HAL_CRYP_IRQHandler................................................................ 160

10.3.32

HAL_CRYP_GetState .................................................................... 161

10.4

CRYP Firmware driver defines ...................................................... 161

10.4.1

CRYP .............................................................................................. 161

11 HAL CRYP Extension Driver ....................................................... 165

11.1

HAL CRYP Extension Driver ......................................................... 165

11.2

CRYPEx Firmware driver API description ..................................... 165

11.2.1

Extended features functions ........................................................... 165

11.2.2

HAL_CRYPEx_ComputationCpltCallback...................................... 165

11.3

CRYPEx Firmware driver defines .................................................. 165

11.3.1

CRYPEx ......................................................................................... 165

12 HAL DAC Generic Driver ............................................................. 166

12.1

HAL DAC Generic Driver .............................................................. 166

12.2

DAC Firmware driver registers structures ..................................... 166

12.2.1

DAC_HandleTypeDef ..................................................................... 166

12.2.2

DAC_ChannelConfTypeDef ........................................................... 166

12.3

DAC Firmware driver API description ............................................ 167

12.3.1

DAC Peripheral features................................................................. 167

12.3.2

How to use this driver ..................................................................... 168

12.3.3

Initialization and de-initialization functions ..................................... 169

12.3.4

IO operation functions .................................................................... 169

12.3.5

Peripheral Control functions ........................................................... 170

12.3.6

Peripheral State and Errors functions ............................................ 170

12.3.7

HAL_DAC_Init ................................................................................ 170

12.3.8

HAL_DAC_DeInit ............................................................................ 170

12.3.9

HAL_DAC_MspInit ......................................................................... 171

12.3.10

HAL_DAC_MspDeInit ..................................................................... 171

12.3.11

HAL_DAC_Start ............................................................................. 171

12.3.12

HAL_DAC_Stop .............................................................................. 171

12.3.13

HAL_DAC_Start_DMA ................................................................... 172

12.3.14

HAL_DAC_Stop_DMA.................................................................... 172

8/654 DOCID026682 Rev 3

UM1816 Contents

12.3.15

HAL_DAC_GetValue ...................................................................... 172

12.3.16

HAL_DAC_IRQHandler .................................................................. 172

12.3.17

HAL_DAC_ConvCpltCallbackCh1 .................................................. 173

12.3.18

HAL_DAC_ConvHalfCpltCallbackCh1 ........................................... 173

12.3.19

HAL_DAC_ErrorCallbackCh1 ........................................................ 173

12.3.20

HAL_DAC_DMAUnderrunCallbackCh1 ......................................... 173

12.3.21

HAL_DAC_SetValue ...................................................................... 173

12.3.22

HAL_DAC_ConfigChannel ............................................................. 174

12.3.23

HAL_DAC_GetState ....................................................................... 174

12.3.24

HAL_DAC_GetError ....................................................................... 174

12.3.25

HAL_DAC_ConfigChannel ............................................................. 175

12.3.26

HAL_DAC_SetValue ...................................................................... 175

12.3.27

HAL_DAC_GetState ....................................................................... 175

12.3.28

HAL_DAC_GetError ....................................................................... 175

12.4

DAC Firmware driver defines ........................................................ 176

12.4.1

DAC ................................................................................................ 176

13 HAL DAC Extension Driver ......................................................... 180

13.1

HAL DAC Extension Driver ........................................................... 180

13.2

DACEx Firmware driver API description ....................................... 180

13.2.1

How to use this driver ..................................................................... 180

13.2.2

Extended features functions ........................................................... 180

13.2.3

HAL_DACEx_DualGetValue .......................................................... 180

13.2.4

HAL_DACEx_TriangleWaveGenerate ........................................... 180

13.2.5

HAL_DACEx_NoiseWaveGenerate ............................................... 181

13.2.6

HAL_DACEx_DualSetValue ........................................................... 182

13.2.7

HAL_DACEx_ConvCpltCallbackCh2 ............................................. 182

13.2.8

HAL_DACEx_ConvHalfCpltCallbackCh2 ....................................... 182

13.2.9

HAL_DACEx_ErrorCallbackCh2 .................................................... 183

13.2.10

HAL_DACEx_DMAUnderrunCallbackCh2 ..................................... 183

13.3

DACEx Firmware driver defines .................................................... 183

13.3.1

DACEx ............................................................................................ 183

14 HAL DMA Generic Driver ............................................................ 185

14.1

HAL DMA Generic Driver .............................................................. 185

14.2

DMA Firmware driver registers structures ..................................... 185

14.2.1

DMA_InitTypeDef ........................................................................... 185

14.2.2

__DMA_HandleTypeDef................................................................. 185

14.3

DMA Firmware driver API description ........................................... 186

DOCID026682 Rev 3 9/654

Contents UM1816

14.3.1

How to use this driver ..................................................................... 186

14.3.2

Initialization and de-initialization functions ..................................... 187

14.3.3

IO operation functions .................................................................... 187

14.3.4

State and Errors functions .............................................................. 188

14.3.5

HAL_DMA_Init ................................................................................ 188

14.3.6

HAL_DMA_DeInit ........................................................................... 188

14.3.7

HAL_DMA_Start ............................................................................. 188

14.3.8

HAL_DMA_Start_IT ........................................................................ 189

14.3.9

HAL_DMA_Abort ............................................................................ 189

14.3.10

HAL_DMA_PollForTransfer ............................................................ 189

14.3.11

HAL_DMA_IRQHandler.................................................................. 190

14.3.12

HAL_DMA_GetState ...................................................................... 190

14.3.13

HAL_DMA_GetError ....................................................................... 190

14.4

DMA Firmware driver defines ........................................................ 190

14.4.1

DMA ................................................................................................ 190

15 HAL DMA Extension Driver ......................................................... 195

15.1

HAL DMA Extension Driver ........................................................... 195

15.2

DMAEx Firmware driver defines .................................................... 195

15.2.1

DMAEx............................................................................................ 195

16 HAL FLASH Generic Driver ......................................................... 197

16.1

HAL FLASH Generic Driver........................................................... 197

16.2

FLASH Firmware driver registers structures ................................. 197

16.2.1

FLASH_ProcessTypeDef ............................................................... 197

16.3

FLASH Firmware driver API description ........................................ 197

16.3.1

FLASH peripheral features ............................................................. 197

16.3.2

How to use this driver ..................................................................... 197

16.3.3

Programming operation functions .................................................. 198

16.3.4

Option Bytes Programming functions ............................................. 199

16.3.5

Peripheral Control functions ........................................................... 199

16.3.6

Peripheral Errors functions ............................................................. 199

16.3.7

HAL_FLASH_Program ................................................................... 200

16.3.8

HAL_FLASH_Program_IT .............................................................. 200

16.3.9

HAL_FLASH_EndOfOperationCallback ......................................... 200

16.3.10

HAL_FLASH_OperationErrorCallback ........................................... 200

16.3.11

HAL_FLASH_IRQHandler .............................................................. 201

16.3.12

HAL_FLASH_Unlock ...................................................................... 201

16.3.13

HAL_FLASH_Lock ......................................................................... 201

10/654 DOCID026682 Rev 3

UM1816 Contents

16.3.14

HAL_FLASH_OB_Unlock ............................................................... 201

16.3.15

HAL_FLASH_OB_Lock .................................................................. 201

16.3.16

HAL_FLASH_OB_Launch .............................................................. 201

16.3.17

HAL_FLASH_GetError ................................................................... 201

16.4

FLASH Firmware driver defines .................................................... 202

16.4.1

FLASH ............................................................................................ 202

17 HAL FLASH Extension Driver ..................................................... 206

17.1

HAL FLASH Extension Driver ....................................................... 206

17.2

FLASHEx Firmware driver registers structures ............................. 206

17.2.1

FLASH_EraseInitTypeDef .............................................................. 206

17.2.2

FLASH_OBProgramInitTypeDef .................................................... 206

17.2.3

FLASH_AdvOBProgramInitTypeDef .............................................. 207

17.3

FLASHEx Firmware driver API description.................................... 207

17.3.1

FLASH Erasing Programming functions ......................................... 207

17.3.2

Option Bytes Programming functions ............................................. 208

17.3.3

DATA EEPROM Programming functions ....................................... 208

17.3.4

HAL_FLASHEx_Erase ................................................................... 209

17.3.5

HAL_FLASHEx_Erase_IT .............................................................. 209

17.3.6

HAL_FLASHEx_OBProgram .......................................................... 209

17.3.7

HAL_FLASHEx_OBGetConfig ....................................................... 210

17.3.8

HAL_FLASHEx_AdvOBProgram ................................................... 210

17.3.9

HAL_FLASHEx_AdvOBGetConfig ................................................. 210

17.3.10

HAL_FLASHEx_DATAEEPROM_Unlock ...................................... 210

17.3.11

HAL_FLASHEx_DATAEEPROM_Lock .......................................... 210

17.3.12

HAL_FLASHEx_DATAEEPROM_Erase ........................................ 211

17.3.13

HAL_FLASHEx_DATAEEPROM_Program.................................... 211

17.3.14

HAL_FLASHEx_DATAEEPROM_EnableFixedTimeProgram ....... 211

17.3.15

HAL_FLASHEx_DATAEEPROM_DisableFixedTimeProgram....... 212

17.4

FLASHEx Firmware driver defines ................................................ 212

17.4.1

FLASHEx ........................................................................................ 212

18 HAL FLASH__RAMFUNC Generic Driver ................................... 219

18.1

HAL FLASH__RAMFUNC Generic Driver ..................................... 219

18.2

FLASH__RAMFUNC Firmware driver API description .................. 219

18.2.1

HAL_FLASHEx_EnableRunPowerDown ....................................... 219

18.2.2

HAL_FLASHEx_DisableRunPowerDown....................................... 219

18.2.3

HAL_FLASHEx_EraseParallelPage ............................................... 219

18.2.4

HAL_FLASHEx_ProgramParallelHalfPage .................................... 219

DOCID026682 Rev 3 11/654

Contents UM1816

18.2.5

HAL_FLASHEx_HalfPageProgram ................................................ 220

18.2.6

HAL_FLASHEx_DATAEEPROM_EraseDoubleWord .................... 221

18.2.7

HAL_FLASHEx_DATAEEPROM_ProgramDoubleWord ............... 221

19 HAL GPIO Generic Driver............................................................ 223

19.1

HAL GPIO Generic Driver ............................................................. 223

19.2

GPIO Firmware driver registers structures .................................... 223

19.2.1

GPIO_InitTypeDef .......................................................................... 223

19.3

GPIO Firmware driver API description .......................................... 223

19.3.1

GPIO Peripheral features ............................................................... 223

19.3.2

How to use this driver ..................................................................... 224

19.3.3

Initialization and Configuration functions ........................................ 225

19.3.4

HAL_GPIO_Init ............................................................................... 225

19.3.5

HAL_GPIO_DeInit .......................................................................... 225

19.3.6

HAL_GPIO_ReadPin ...................................................................... 225

19.3.7

HAL_GPIO_WritePin ...................................................................... 225

19.3.8

HAL_GPIO_TogglePin ................................................................... 226

19.3.9

HAL_GPIO_LockPin ....................................................................... 226

19.3.10

HAL_GPIO_EXTI_IRQHandler ...................................................... 227

19.3.11

HAL_GPIO_EXTI_Callback ............................................................ 227

19.4

GPIO Firmware driver defines ....................................................... 227

19.4.1

GPIO ............................................................................................... 227

20 HAL GPIO Extension Driver ........................................................ 231

20.1

HAL GPIO Extension Driver .......................................................... 231

20.2

GPIOEx Firmware driver defines ................................................... 231

20.2.1

GPIOEx .......................................................................................... 231

21 HAL I2C Generic Driver ............................................................... 233

21.1

HAL I2C Generic Driver ................................................................ 233

21.2

I2C Firmware driver registers structures ....................................... 233

21.2.1

I2C_InitTypeDef .............................................................................. 233

21.2.2

I2C_HandleTypeDef ....................................................................... 233

21.3

I2C Firmware driver API description .............................................. 234

21.3.1

How to use this driver ..................................................................... 234

21.3.2

Initialization and de-initialization functions ..................................... 237

21.3.3

IO operation functions .................................................................... 237

21.3.4

Peripheral State and Errors functions ............................................ 239

21.3.5

HAL_I2C_Init .................................................................................. 239

21.3.6

HAL_I2C_DeInit .............................................................................. 239

12/654 DOCID026682 Rev 3

UM1816 Contents

21.3.7

HAL_I2C_MspInit ........................................................................... 239

21.3.8

HAL_I2C_MspDeInit ....................................................................... 239

21.3.9

HAL_I2C_Master_Transmit ............................................................ 240

21.3.10

HAL_I2C_Master_Receive ............................................................. 240

21.3.11

HAL_I2C_Slave_Transmit .............................................................. 240

21.3.12

HAL_I2C_Slave_Receive ............................................................... 241

21.3.13

HAL_I2C_Master_Transmit_IT ....................................................... 241

21.3.14

HAL_I2C_Master_Receive_IT ........................................................ 241

21.3.15

HAL_I2C_Slave_Transmit_IT ......................................................... 241

21.3.16

HAL_I2C_Slave_Receive_IT .......................................................... 242

21.3.17

HAL_I2C_Master_Transmit_DMA .................................................. 242

21.3.18

HAL_I2C_Master_Receive_DMA ................................................... 242

21.3.19

HAL_I2C_Slave_Transmit_DMA .................................................... 242

21.3.20

HAL_I2C_Slave_Receive_DMA ..................................................... 243

21.3.21

HAL_I2C_Mem_Write ..................................................................... 243

21.3.22

HAL_I2C_Mem_Read .................................................................... 243

21.3.23

HAL_I2C_Mem_Write_IT ............................................................... 244

21.3.24

HAL_I2C_Mem_Read_IT ............................................................... 244

21.3.25

HAL_I2C_Mem_Write_DMA .......................................................... 244

21.3.26

HAL_I2C_Mem_Read_DMA .......................................................... 245

21.3.27

HAL_I2C_IsDeviceReady ............................................................... 245

21.3.28

HAL_I2C_EV_IRQHandler ............................................................. 245

21.3.29

HAL_I2C_ER_IRQHandler ............................................................. 246

21.3.30

HAL_I2C_MasterTxCpltCallback .................................................... 246

21.3.31

HAL_I2C_MasterRxCpltCallback ................................................... 246

21.3.32

HAL_I2C_SlaveTxCpltCallback ...................................................... 246

21.3.33

HAL_I2C_SlaveRxCpltCallback ..................................................... 246

21.3.34

HAL_I2C_MemTxCpltCallback ....................................................... 246

21.3.35

HAL_I2C_MemRxCpltCallback ...................................................... 247

21.3.36

HAL_I2C_ErrorCallback ................................................................. 247

21.3.37

HAL_I2C_GetState ......................................................................... 247

21.3.38

HAL_I2C_GetError ......................................................................... 247

21.4

I2C Firmware driver defines .......................................................... 247

21.4.1

I2C .................................................................................................. 247

22 HAL I2S Generic Driver ............................................................... 254

22.1

HAL I2S Generic Driver ................................................................. 254

22.2

I2S Firmware driver registers structures ....................................... 254

22.2.1

I2S_InitTypeDef .............................................................................. 254

DOCID026682 Rev 3 13/654

Contents UM1816

22.2.2

I2S_HandleTypeDef ....................................................................... 254

22.3

I2S Firmware driver API description .............................................. 255

22.3.1

How to use this driver ..................................................................... 255

22.3.2

Initialization and de-initialization functions ..................................... 257

22.3.3

IO operation functions .................................................................... 257

22.3.4

Peripheral State and Errors functions ............................................ 258

22.3.5

HAL_I2S_Init .................................................................................. 258

22.3.6

HAL_I2S_DeInit .............................................................................. 258

22.3.7

HAL_I2S_MspInit ............................................................................ 259

22.3.8

HAL_I2S_MspDeInit ....................................................................... 259

22.3.9

HAL_I2S_Transmit ......................................................................... 259

22.3.10

HAL_I2S_Receive .......................................................................... 259

22.3.11

HAL_I2S_Transmit_IT .................................................................... 260

22.3.12

HAL_I2S_Receive_IT ..................................................................... 260

22.3.13

HAL_I2S_Transmit_DMA ............................................................... 261

22.3.14

HAL_I2S_Receive_DMA ................................................................ 261

22.3.15

HAL_I2S_DMAPause ..................................................................... 261

22.3.16

HAL_I2S_DMAResume .................................................................. 262

22.3.17

HAL_I2S_DMAStop ........................................................................ 262

22.3.18

HAL_I2S_IRQHandler .................................................................... 262

22.3.19

HAL_I2S_TxHalfCpltCallback ........................................................ 262

22.3.20

HAL_I2S_TxCpltCallback ............................................................... 262

22.3.21

HAL_I2S_RxHalfCpltCallback ........................................................ 263

22.3.22

HAL_I2S_RxCpltCallback .............................................................. 263

22.3.23

HAL_I2S_ErrorCallback ................................................................. 263

22.3.24

HAL_I2S_GetState ......................................................................... 263

22.3.25

HAL_I2S_GetError ......................................................................... 263

22.4

I2S Firmware driver defines .......................................................... 264

22.4.1

I2S .................................................................................................. 264

23 HAL IRDA Generic Driver ............................................................ 268

23.1

HAL IRDA Generic Driver ............................................................. 268

23.2

IRDA Firmware driver registers structures .................................... 268

23.2.1

IRDA_InitTypeDef ........................................................................... 268

23.2.2

IRDA_HandleTypeDef .................................................................... 268

23.3

IRDA Firmware driver API description ........................................... 269

23.3.1

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

23.3.2

Initialization and Configuration functions ........................................ 271

23.3.3

IO operation functions .................................................................... 272

14/654 DOCID026682 Rev 3

UM1816 Contents

23.3.4

Peripheral State and Errors functions ............................................ 273

23.3.5

HAL_IRDA_Init ............................................................................... 273

23.3.6

HAL_IRDA_DeInit ........................................................................... 273

23.3.7

HAL_IRDA_MspInit ........................................................................ 273

23.3.8

HAL_IRDA_MspDeInit .................................................................... 274

23.3.9

HAL_IRDA_Transmit ...................................................................... 274

23.3.10

HAL_IRDA_Receive ....................................................................... 274

23.3.11

HAL_IRDA_Transmit_IT ................................................................. 274

23.3.12

HAL_IRDA_Receive_IT .................................................................. 275

23.3.13

HAL_IRDA_Transmit_DMA ............................................................ 275

23.3.14

HAL_IRDA_Receive_DMA ............................................................. 275

23.3.15

HAL_IRDA_DMAPause .................................................................. 275

23.3.16

HAL_IRDA_DMAResume............................................................... 276

23.3.17

HAL_IRDA_DMAStop..................................................................... 276

23.3.18

HAL_IRDA_IRQHandler ................................................................. 276

23.3.19

HAL_IRDA_TxCpltCallback ............................................................ 276

23.3.20

HAL_IRDA_TxHalfCpltCallback ..................................................... 276

23.3.21

HAL_IRDA_RxCpltCallback ........................................................... 277

23.3.22

HAL_IRDA_RxHalfCpltCallback ..................................................... 277

23.3.23

HAL_IRDA_ErrorCallback .............................................................. 277

23.3.24

HAL_IRDA_GetState ...................................................................... 277

23.3.25

HAL_IRDA_GetError ...................................................................... 277

23.4

IRDA Firmware driver defines ....................................................... 278

23.4.1

IRDA ............................................................................................... 278

24 HAL IWDG Generic Driver ........................................................... 286

24.1

HAL IWDG Generic Driver ............................................................ 286

24.2

IWDG Firmware driver registers structures ................................... 286

24.2.1

IWDG_InitTypeDef ......................................................................... 286

24.2.2

IWDG_HandleTypeDef ................................................................... 286

24.3

IWDG Firmware driver API description ......................................... 286

24.3.1

Initialization and de-initialization functions ..................................... 286

24.3.2

IO operation functions .................................................................... 287

24.3.3

Peripheral State functions .............................................................. 287

24.3.4

HAL_IWDG_Init .............................................................................. 287

24.3.5

HAL_IWDG_MspInit ....................................................................... 287

24.3.6

HAL_IWDG_Start ........................................................................... 287

24.3.7

HAL_IWDG_Refresh ...................................................................... 288

24.3.8

HAL_IWDG_GetState..................................................................... 288

DOCID026682 Rev 3 15/654

Contents UM1816

24.4

IWDG Firmware driver defines ...................................................... 288

24.4.1

IWDG .............................................................................................. 288

25 HAL LCD Generic Driver ............................................................. 291

25.1

HAL LCD Generic Driver ............................................................... 291

25.2

LCD Firmware driver registers structures ...................................... 291

25.2.1

LCD_InitTypeDef ............................................................................ 291

25.2.2

LCD_HandleTypeDef ..................................................................... 292

25.3

LCD Firmware driver API description ............................................ 292

25.3.1

How to use this driver ..................................................................... 292

25.3.2

Initialization and Configuration functions ........................................ 293

25.3.3

IO operation functions .................................................................... 293

25.3.4

Peripheral State functions .............................................................. 293

25.3.5

HAL_LCD_DeInit ............................................................................ 294

25.3.6

HAL_LCD_Init ................................................................................. 294

25.3.7

HAL_LCD_MspDeInit ..................................................................... 294

25.3.8

HAL_LCD_MspInit .......................................................................... 294

25.3.9

HAL_LCD_Write ............................................................................. 294

25.3.10

HAL_LCD_Clear ............................................................................. 295

25.3.11

HAL_LCD_UpdateDisplayRequest ................................................ 295

25.3.12

HAL_LCD_GetState ....................................................................... 296

25.3.13

HAL_LCD_GetError ........................................................................ 296

25.4

LCD Firmware driver defines......................................................... 296

25.4.1

LCD................................................................................................. 296

26 HAL NOR Generic Driver............................................................. 306

26.1

HAL NOR Generic Driver .............................................................. 306

26.2

NOR Firmware driver registers structures ..................................... 306

26.2.1

NOR_IDTypeDef ............................................................................ 306

26.2.2

NOR_CFITypeDef .......................................................................... 306

26.2.3

NOR_HandleTypeDef..................................................................... 307

26.3

NOR Firmware driver API description ........................................... 307

26.3.1

How to use this driver ..................................................................... 307

26.3.2

NOR Initialization and de_initialization functions ........................... 308

26.3.3

NOR Input and Output functions .................................................... 308

26.3.4

NOR Control functions.................................................................... 308

26.3.5

NOR State functions ....................................................................... 308

26.3.6

HAL_NOR_Init ................................................................................ 308

26.3.7

HAL_NOR_DeInit ........................................................................... 309

16/654 DOCID026682 Rev 3

UM1816 Contents

26.3.8

HAL_NOR_MspInit ......................................................................... 309

26.3.9

HAL_NOR_MspDeInit .................................................................... 309

26.3.10

HAL_NOR_MspWait ....................................................................... 309

26.3.11

HAL_NOR_Read_ID ...................................................................... 309

26.3.12

HAL_NOR_ReturnToReadMode .................................................... 310

26.3.13

HAL_NOR_Read ............................................................................ 310

26.3.14

HAL_NOR_Program ....................................................................... 310

26.3.15

HAL_NOR_ReadBuffer .................................................................. 310

26.3.16

HAL_NOR_ProgramBuffer ............................................................. 311

26.3.17

HAL_NOR_Erase_Block ................................................................ 311

26.3.18

HAL_NOR_Erase_Chip .................................................................. 311

26.3.19

HAL_NOR_Read_CFI .................................................................... 311

26.3.20

HAL_NOR_WriteOperation_Enable ............................................... 312

26.3.21

HAL_NOR_WriteOperation_Disable .............................................. 312

26.3.22

HAL_NOR_GetState ...................................................................... 312

26.3.23

HAL_NOR_GetStatus..................................................................... 312

26.4

NOR Firmware driver defines ........................................................ 313

26.4.1

NOR ................................................................................................ 313

27 HAL OPAMP Generic Driver ....................................................... 315

27.1

HAL OPAMP Generic Driver ......................................................... 315

27.2

OPAMP Firmware driver registers structures ................................ 315

27.2.1

OPAMP_InitTypeDef ...................................................................... 315

27.2.2

OPAMP_HandleTypeDef................................................................ 316

27.3

OPAMP Firmware driver API description ...................................... 316

27.3.1

OPAMP Peripheral Features .......................................................... 316

27.3.2

How to use this driver ..................................................................... 318

27.3.3

Initialization and de-initialization functions ..................................... 319

27.3.4

IO operation functions .................................................................... 319

27.3.5

Peripheral Control functions ........................................................... 319

27.3.6

Peripheral State functions .............................................................. 319

27.3.7

HAL_OPAMP_Init ........................................................................... 319

27.3.8

HAL_OPAMP_DeInit ...................................................................... 320

27.3.9

HAL_OPAMP_MspInit .................................................................... 320

27.3.10

HAL_OPAMP_MspDeInit ............................................................... 320

27.3.11

HAL_OPAMP_Start ........................................................................ 320

27.3.12

HAL_OPAMP_Stop ........................................................................ 320

27.3.13

HAL_OPAMP_SelfCalibrate ........................................................... 321

27.3.14

HAL_OPAMP_Lock ........................................................................ 321

DOCID026682 Rev 3 17/654

Contents UM1816

27.3.15

HAL_OPAMP_GetTrimOffset ......................................................... 321

27.3.16

HAL_OPAMP_GetState ................................................................. 321

27.4

OPAMP Firmware driver defines ................................................... 322

27.4.1

OPAMP ........................................................................................... 322

28 HAL OPAMP Extension Driver .................................................... 327

28.1

HAL OPAMP Extension Driver ...................................................... 327

28.2

OPAMPEx Firmware driver API description .................................. 327

28.2.1

Peripheral Control functions ........................................................... 327

28.2.2

Extended IO operation functions .................................................... 327

28.2.3

HAL_OPAMPEx_Unlock ................................................................ 327

28.2.4

HAL_OPAMPEx_SelfCalibrateAll ................................................... 327

28.3

OPAMPEx Firmware driver defines ............................................... 328

28.3.1

OPAMPEx ...................................................................................... 328

29 HAL PCD Generic Driver ............................................................. 330

29.1

HAL PCD Generic Driver .............................................................. 330

29.2

PCD Firmware driver registers structures ..................................... 330

29.2.1

PCD_InitTypeDef ............................................................................ 330

29.2.2

PCD_EPTypeDef ............................................................................ 330

29.2.3

PCD_HandleTypeDef ..................................................................... 331

29.3

PCD Firmware driver API description ............................................ 332

29.3.1

How to use this driver ..................................................................... 332

29.3.2

Initialization and de-initialization functions ..................................... 332

29.3.3

IO operation functions .................................................................... 333

29.3.4

Peripheral Control functions ........................................................... 333

29.3.5

Peripheral State functions .............................................................. 333

29.3.6

HAL_PCD_Init ................................................................................ 333

29.3.7

HAL_PCD_DeInit ............................................................................ 334

29.3.8

HAL_PCD_MspInit ......................................................................... 334

29.3.9

HAL_PCD_MspDeInit ..................................................................... 334

29.3.10

HAL_PCD_Start ............................................................................. 334

29.3.11

HAL_PCD_Stop .............................................................................. 334

29.3.12

HAL_PCD_IRQHandler .................................................................. 335

29.3.13

HAL_PCD_DataOutStageCallback ................................................ 335

29.3.14

HAL_PCD_DataInStageCallback ................................................... 335

29.3.15

HAL_PCD_SetupStageCallback .................................................... 335

29.3.16

HAL_PCD_SOFCallback ................................................................ 335

29.3.17

HAL_PCD_ResetCallback .............................................................. 335

18/654 DOCID026682 Rev 3

UM1816 Contents

29.3.18

HAL_PCD_SuspendCallback ......................................................... 336

29.3.19

HAL_PCD_ResumeCallback .......................................................... 336

29.3.20

HAL_PCD_ISOOUTIncompleteCallback ........................................ 336

29.3.21

HAL_PCD_ISOINIncompleteCallback ............................................ 336

29.3.22

HAL_PCD_ConnectCallback .......................................................... 336

29.3.23

HAL_PCD_DisconnectCallback ..................................................... 336

29.3.24

HAL_PCD_DevConnect ................................................................. 337

29.3.25

HAL_PCD_DevDisconnect ............................................................. 337

29.3.26

HAL_PCD_SetAddress .................................................................. 337

29.3.27

HAL_PCD_EP_Open ..................................................................... 337

29.3.28

HAL_PCD_EP_Close ..................................................................... 337

29.3.29

HAL_PCD_EP_Receive ................................................................. 338

29.3.30

HAL_PCD_EP_GetRxCount .......................................................... 338

29.3.31

HAL_PCD_EP_Transmit ................................................................ 338

29.3.32

HAL_PCD_EP_SetStall .................................................................. 338

29.3.33

HAL_PCD_EP_ClrStall................................................................... 339

29.3.34

HAL_PCD_EP_Flush ..................................................................... 339

29.3.35

HAL_PCD_ActivateRemoteWakeup .............................................. 339

29.3.36

HAL_PCD_DeActivateRemoteWakeup.......................................... 339

29.3.37

HAL_PCD_GetState ....................................................................... 339

29.3.38

HAL_PCDEx_SetConnectionState ................................................. 340

29.4

PCD Firmware driver defines ........................................................ 340

29.4.1

PCD ................................................................................................ 340

30 HAL PCD Extension Driver ......................................................... 349

30.1

HAL PCD Extension Driver ........................................................... 349

30.2

PCDEx Firmware driver API description ....................................... 349

30.2.1

Peripheral Control functions ........................................................... 349

30.2.2

HAL_PCDEx_PMAConfig .............................................................. 349

30.3

PCDEx Firmware driver defines .................................................... 349

30.3.1

PCDEx ............................................................................................ 349

31 HAL PWR Generic Driver ............................................................ 350

31.1

HAL PWR Generic Driver .............................................................. 350

31.2

PWR Firmware driver registers structures .................................... 350

31.2.1

PWR_PVDTypeDef ........................................................................ 350

31.3

PWR Firmware driver API description ........................................... 350

31.3.1

Initialization and de-initialization functions ..................................... 350

31.3.2

Peripheral Control functions ........................................................... 350

DOCID026682 Rev 3 19/654

Contents UM1816

31.3.3

HAL_PWR_DeInit ........................................................................... 354

31.3.4

HAL_PWR_EnableBkUpAccess .................................................... 354

31.3.5

HAL_PWR_DisableBkUpAccess .................................................... 354

31.3.6

HAL_PWR_ConfigPVD .................................................................. 355

31.3.7

HAL_PWR_EnablePVD.................................................................. 355

31.3.8

HAL_PWR_DisablePVD ................................................................. 355

31.3.9

HAL_PWR_EnableWakeUpPin ...................................................... 355

31.3.10

HAL_PWR_DisableWakeUpPin ..................................................... 355

31.3.11

HAL_PWR_EnterSLEEPMode ....................................................... 356

31.3.12

HAL_PWR_EnterSTOPMode ......................................................... 356

31.3.13

HAL_PWR_EnterSTANDBYMode ................................................. 356

31.3.14

HAL_PWR_EnableSleepOnExit ..................................................... 357

31.3.15

HAL_PWR_DisableSleepOnExit .................................................... 357

31.3.16

HAL_PWR_EnableSEVOnPend .................................................... 357

31.3.17

HAL_PWR_DisableSEVOnPend .................................................... 357

31.3.18

HAL_PWR_PVD_IRQHandler ........................................................ 358

31.3.19

HAL_PWR_PVDCallback ............................................................... 358

31.4

PWR Firmware driver defines ....................................................... 358

31.4.1

PWR ............................................................................................... 358

32 HAL PWR Extension Driver ........................................................ 364

32.1

HAL PWR Extension Driver........................................................... 364

32.2

PWREx Firmware driver API description ....................................... 364

32.2.1

Peripheral extended features functions .......................................... 364

32.2.2

HAL_PWREx_GetVoltageRange ................................................... 364

32.2.3

HAL_PWREx_EnableFastWakeUp ................................................ 364

32.2.4

HAL_PWREx_DisableFastWakeUp ............................................... 364

32.2.5

HAL_PWREx_EnableUltraLowPower ............................................ 364

32.2.6

HAL_PWREx_DisableUltraLowPower ........................................... 365

32.2.7

HAL_PWREx_EnableLowPowerRunMode .................................... 365

32.2.8

HAL_PWREx_DisableLowPowerRunMode ................................... 365

32.3

PWREx Firmware driver defines ................................................... 365

32.3.1

PWREx ........................................................................................... 365

33 HAL RCC Generic Driver ............................................................. 366

33.1

HAL RCC Generic Driver .............................................................. 366

33.2

RCC Firmware driver registers structures ..................................... 366

33.2.1

RCC_PLLInitTypeDef ..................................................................... 366

33.2.2

RCC_OscInitTypeDef ..................................................................... 366

20/654 DOCID026682 Rev 3

UM1816 Contents

33.2.3

RCC_ClkInitTypeDef ...................................................................... 367

33.3

RCC Firmware driver API description ........................................... 368

33.3.1

RCC specific features ..................................................................... 368

33.3.2

RCC Limitations .............................................................................. 368

33.3.3

Initialization and de-initialization function ....................................... 368

33.3.4

Peripheral Control functions ........................................................... 370

33.3.5

HAL_RCC_DeInit ........................................................................... 370

33.3.6

HAL_RCC_OscConfig .................................................................... 370

33.3.7

HAL_RCC_ClockConfig ................................................................. 370

33.3.8

HAL_RCC_MCOConfig .................................................................. 371

33.3.9

HAL_RCC_EnableCSS .................................................................. 372

33.3.10

HAL_RCC_DisableCSS ................................................................. 372

33.3.11

HAL_RCC_GetSysClockFreq ........................................................ 372

33.3.12

HAL_RCC_GetHCLKFreq .............................................................. 373

33.3.13

HAL_RCC_GetPCLK1Freq ............................................................ 373

33.3.14

HAL_RCC_GetPCLK2Freq ............................................................ 373

33.3.15

HAL_RCC_GetOscConfig .............................................................. 373

33.3.16

HAL_RCC_GetClockConfig ........................................................... 373

33.3.17

HAL_RCC_NMI_IRQHandler ......................................................... 374

33.3.18

HAL_RCC_CSSCallback................................................................ 374

33.4

RCC Firmware driver defines ........................................................ 374

33.4.1

RCC ................................................................................................ 374

34 HAL RCC Extension Driver ......................................................... 400

34.1

HAL RCC Extension Driver ........................................................... 400

34.2

RCCEx Firmware driver registers structures ................................. 400

34.2.1

RCC_PeriphCLKInitTypeDef .......................................................... 400

34.3

RCCEx Firmware driver API description ....................................... 400

34.3.1

Extended Peripheral Control functions ........................................... 400

34.3.2

HAL_RCCEx_PeriphCLKConfig ..................................................... 400

34.3.3

HAL_RCCEx_GetPeriphCLKConfig ............................................... 401

34.3.4

HAL_RCCEx_GetPeriphCLKFreq .................................................. 401

34.3.5

HAL_RCCEx_EnableLSECSS ....................................................... 401

34.3.6

HAL_RCCEx_DisableLSECSS ...................................................... 402

34.4

RCCEx Firmware driver defines .................................................... 402

34.4.1

RCCEx ............................................................................................ 402

35 HAL RTC Generic Driver ............................................................. 408

35.1

HAL RTC Generic Driver ............................................................... 408

DOCID026682 Rev 3 21/654

Contents UM1816

35.2

RTC Firmware driver registers structures ..................................... 408

35.2.1

RTC_InitTypeDef ............................................................................ 408

35.2.2

RTC_DateTypeDef ......................................................................... 408

35.2.3

RTC_HandleTypeDef ..................................................................... 409

35.3

RTC Firmware driver API description ............................................ 409

35.3.1

Backup Domain Operating Condition ............................................. 409

35.3.2

Backup Domain Reset .................................................................... 410

35.3.3

Backup Domain Access.................................................................. 410

35.3.4

How to use this driver ..................................................................... 410

35.3.5

RTC and low power modes ............................................................ 411

35.3.6

Initialization and de-initialization functions ..................................... 411

35.3.7

RTC Time and Date functions ........................................................ 411

35.3.8

RTC Alarm functions ...................................................................... 412

35.3.9

Peripheral State functions .............................................................. 412

35.3.10

Peripheral Control functions ........................................................... 412

35.3.11

HAL_RTC_Init ................................................................................ 412

35.3.12

HAL_RTC_DeInit ............................................................................ 412

35.3.13

HAL_RTC_MspInit .......................................................................... 413

35.3.14

HAL_RTC_MspDeInit ..................................................................... 413

35.3.15

HAL_RTC_SetTime ........................................................................ 413

35.3.16

HAL_RTC_GetTime ....................................................................... 413

35.3.17

HAL_RTC_SetDate ........................................................................ 414

35.3.18

HAL_RTC_GetDate ........................................................................ 414

35.3.19

HAL_RTC_SetTime ........................................................................ 414

35.3.20

HAL_RTC_SetDate ........................................................................ 415

35.3.21

HAL_RTC_GetDate ........................................................................ 415

35.3.22

HAL_RTC_GetTime ....................................................................... 415

35.3.23

HAL_RTC_SetAlarm ...................................................................... 416

35.3.24

HAL_RTC_SetAlarm_IT ................................................................. 416

35.3.25

HAL_RTC_DeactivateAlarm ........................................................... 417

35.3.26

HAL_RTC_GetAlarm ...................................................................... 417

35.3.27

HAL_RTC_AlarmIRQHandler ......................................................... 417

35.3.28

HAL_RTC_PollForAlarmAEvent ..................................................... 417

35.3.29

HAL_RTC_AlarmAEventCallback .................................................. 418

35.3.30

HAL_RTC_DeactivateAlarm ........................................................... 418

35.3.31

HAL_RTC_AlarmIRQHandler ......................................................... 418

35.3.32

HAL_RTC_AlarmAEventCallback .................................................. 418

35.3.33

HAL_RTC_PollForAlarmAEvent ..................................................... 418

35.3.34

HAL_RTC_SetAlarm ...................................................................... 419

22/654 DOCID026682 Rev 3

UM1816 Contents

35.3.35

HAL_RTC_SetAlarm_IT ................................................................. 419

35.3.36

HAL_RTC_GetAlarm ...................................................................... 419

35.3.37

HAL_RTC_WaitForSynchro ........................................................... 420

35.3.38

HAL_RTC_GetState ....................................................................... 420

35.3.39

HAL_RTC_WaitForSynchro ........................................................... 420

35.4

RTC Firmware driver defines ........................................................ 421

35.4.1

RTC ................................................................................................ 421

36 HAL RTC Extension Driver ......................................................... 431

36.1

HAL RTC Extension Driver............................................................ 431

36.2

RTCEx Firmware driver registers structures ................................. 431

36.2.1

RTC_TamperTypeDef .................................................................... 431

36.2.2

RTC_TimeTypeDef ......................................................................... 431

36.2.3

RTC_AlarmTypeDef ....................................................................... 432

36.3

RTCEx Firmware driver API description ........................................ 433

36.3.1

How to use this driver ..................................................................... 433

36.3.2

RTC TimeStamp and Tamper functions ......................................... 434

36.3.3

RTC Wake-up functions ................................................................. 434

36.3.4

Extension Peripheral Control functions .......................................... 434

36.3.5

Extended features functions ........................................................... 435

36.3.6

HAL_RTCEx_SetTimeStamp ......................................................... 435

36.3.7

HAL_RTCEx_SetTimeStamp_IT .................................................... 435

36.3.8

HAL_RTCEx_DeactivateTimeStamp ............................................. 436

36.3.9

HAL_RTCEx_GetTimeStamp ......................................................... 436

36.3.10

HAL_RTCEx_SetTamper ............................................................... 436

36.3.11

HAL_RTCEx_SetTamper_IT .......................................................... 437

36.3.12

HAL_RTCEx_DeactivateTamper ................................................... 437

36.3.13

HAL_RTCEx_TamperTimeStampIRQHandler ............................... 437

36.3.14

HAL_RTCEx_TimeStampEventCallback ....................................... 437

36.3.15

HAL_RTCEx_Tamper1EventCallback ........................................... 437

36.3.16

HAL_RTCEx_Tamper2EventCallback ........................................... 438

36.3.17

HAL_RTCEx_Tamper3EventCallback ........................................... 438

36.3.18

HAL_RTCEx_PollForTimeStampEvent .......................................... 438

36.3.19

HAL_RTCEx_PollForTamper1Event .............................................. 438

36.3.20

HAL_RTCEx_PollForTamper2Event .............................................. 438

36.3.21

HAL_RTCEx_PollForTamper3Event .............................................. 439

36.3.22

HAL_RTCEx_SetWakeUpTimer .................................................... 439

36.3.23

HAL_RTCEx_SetWakeUpTimer_IT ............................................... 439

36.3.24

HAL_RTCEx_DeactivateWakeUpTimer ......................................... 439

DOCID026682 Rev 3 23/654

Contents UM1816

36.3.25

HAL_RTCEx_GetWakeUpTimer .................................................... 440

36.3.26

HAL_RTCEx_WakeUpTimerIRQHandler ....................................... 440

36.3.27

HAL_RTCEx_WakeUpTimerEventCallback ................................... 440

36.3.28

HAL_RTCEx_PollForWakeUpTimerEvent ..................................... 440

36.3.29

HAL_RTCEx_BKUPWrite ............................................................... 440

36.3.30

HAL_RTCEx_BKUPRead .............................................................. 441

36.3.31

HAL_RTCEx_SetCoarseCalib ........................................................ 441

36.3.32

HAL_RTCEx_DeactivateCoarseCalib ............................................ 441

36.3.33

HAL_RTCEx_SetSmoothCalib ....................................................... 441

36.3.34

HAL_RTCEx_SetSynchroShift ....................................................... 442

36.3.35

HAL_RTCEx_SetCalibrationOutPut ............................................... 442

36.3.36

HAL_RTCEx_DeactivateCalibrationOutPut ................................... 443

36.3.37

HAL_RTCEx_SetRefClock ............................................................. 443

36.3.38

HAL_RTCEx_DeactivateRefClock ................................................. 443

36.3.39

HAL_RTCEx_EnableBypassShadow ............................................. 443

36.3.40

HAL_RTCEx_DisableBypassShadow ............................................ 444

36.3.41

HAL_RTCEx_AlarmBEventCallback .............................................. 444

36.3.42

HAL_RTCEx_PollForAlarmBEvent ................................................ 444

36.4

RTCEx Firmware driver defines .................................................... 444

36.4.1

RTCEx ............................................................................................ 444

37 HAL SD Generic Driver ............................................................... 468

37.1

HAL SD Generic Driver ................................................................. 468

37.2

SD Firmware driver registers structures ........................................ 468

37.2.1

SD_HandleTypeDef ........................................................................ 468

37.2.2

HAL_SD_CSDTypedef ................................................................... 469

37.2.3

HAL_SD_CIDTypedef .................................................................... 471

37.2.4

HAL_SD_CardStatusTypedef ........................................................ 472

37.2.5

HAL_SD_CardInfoTypedef ............................................................. 472

37.3

SD Firmware driver API description .............................................. 473

37.3.1

How to use this driver ..................................................................... 473

37.3.2

Initialization and de-initialization functions ..................................... 475

37.3.3

IO operation functions .................................................................... 475

37.3.4

Peripheral Control functions ........................................................... 476

37.3.5

Peripheral State functions .............................................................. 476

37.3.6

HAL_SD_Init ................................................................................... 476

37.3.7

HAL_SD_DeInit .............................................................................. 476

37.3.8

HAL_SD_MspInit ............................................................................ 476

37.3.9

HAL_SD_MspDeInit ....................................................................... 476

24/654 DOCID026682 Rev 3

UM1816 Contents

37.3.10

HAL_SD_ReadBlocks .................................................................... 477

37.3.11

HAL_SD_WriteBlocks ..................................................................... 477

37.3.12

HAL_SD_ReadBlocks_DMA .......................................................... 477

37.3.13

HAL_SD_WriteBlocks_DMA .......................................................... 478

37.3.14

HAL_SD_CheckReadOperation ..................................................... 478

37.3.15

HAL_SD_CheckWriteOperation ..................................................... 478

37.3.16

HAL_SD_Erase .............................................................................. 478

37.3.17

HAL_SD_IRQHandler..................................................................... 479

37.3.18

HAL_SD_XferCpltCallback ............................................................. 479

37.3.19

HAL_SD_XferErrorCallback ........................................................... 479

37.3.20

HAL_SD_DMA_RxCpltCallback ..................................................... 479

37.3.21

HAL_SD_DMA_RxErrorCallback ................................................... 479

37.3.22

HAL_SD_DMA_TxCpltCallback ..................................................... 480

37.3.23

HAL_SD_DMA_TxErrorCallback .................................................... 480

37.3.24

HAL_SD_Get_CardInfo .................................................................. 480

37.3.25

HAL_SD_WideBusOperation_Config ............................................. 480

37.3.26

HAL_SD_StopTransfer ................................................................... 480

37.3.27

HAL_SD_HighSpeed ...................................................................... 481

37.3.28

HAL_SD_SendSDStatus ................................................................ 481

37.3.29

HAL_SD_GetStatus ........................................................................ 481

37.3.30

HAL_SD_GetCardStatus ................................................................ 481

37.4

SD Firmware driver defines ........................................................... 482

37.4.1

SD ................................................................................................... 482

38 HAL SMARTCARD Generic Driver .............................................. 495

38.1

HAL SMARTCARD Generic Driver ............................................... 495

38.2

SMARTCARD Firmware driver registers structures ...................... 495

38.2.1

SMARTCARD_InitTypeDef ............................................................ 495

38.2.2

SMARTCARD_HandleTypeDef ...................................................... 496

38.3

SMARTCARD Firmware driver API description ............................. 497

38.3.1

How to use this driver ..................................................................... 497

38.3.2

Initialization and Configuration functions ........................................ 499

38.3.3

IO operation functions .................................................................... 500

38.3.4

Peripheral State and Errors functions ............................................ 501

38.3.5

HAL_SMARTCARD_Init ................................................................. 501

38.3.6

HAL_SMARTCARD_DeInit ............................................................ 501

38.3.7

HAL_SMARTCARD_MspInit .......................................................... 501

38.3.8

HAL_SMARTCARD_MspDeInit ..................................................... 501

38.3.9

HAL_SMARTCARD_Transmit ........................................................ 502

DOCID026682 Rev 3 25/654

Contents UM1816

38.3.10

HAL_SMARTCARD_Receive ......................................................... 502

38.3.11

HAL_SMARTCARD_Transmit_IT .................................................. 502

38.3.12

HAL_SMARTCARD_Receive_IT ................................................... 502

38.3.13

HAL_SMARTCARD_Transmit_DMA .............................................. 503

38.3.14

HAL_SMARTCARD_Receive_DMA ............................................... 503

38.3.15

HAL_SMARTCARD_IRQHandler ................................................... 503

38.3.16

HAL_SMARTCARD_TxCpltCallback ............................................. 504

38.3.17

HAL_SMARTCARD_RxCpltCallback ............................................. 504

38.3.18

HAL_SMARTCARD_ErrorCallback ................................................ 504

38.3.19

HAL_SMARTCARD_GetState ....................................................... 504

38.3.20

HAL_SMARTCARD_GetError ........................................................ 504

38.4

SMARTCARD Firmware driver defines ......................................... 505

38.4.1

SMARTCARD ................................................................................. 505

39 HAL SPI Generic Driver ............................................................... 516

39.1

HAL SPI Generic Driver ................................................................ 516

39.2

SPI Firmware driver registers structures ....................................... 516

39.2.1

SPI_InitTypeDef ............................................................................. 516

39.2.2

__SPI_HandleTypeDef ................................................................... 517

39.3

SPI Firmware driver API description ............................................. 518

39.3.1

How to use this driver ..................................................................... 518

39.3.2

Initialization and de-initialization functions ..................................... 518

39.3.3

IO operation functions .................................................................... 519

39.3.4

Peripheral State and Errors functions ............................................ 520

39.3.5

HAL_SPI_Init .................................................................................. 520

39.3.6

HAL_SPI_DeInit ............................................................................. 520

39.3.7

HAL_SPI_MspInit ........................................................................... 520

39.3.8

HAL_SPI_MspDeInit ....................................................................... 520

39.3.9

HAL_SPI_Transmit ......................................................................... 520

39.3.10

HAL_SPI_Receive .......................................................................... 521

39.3.11

HAL_SPI_TransmitReceive ............................................................ 521

39.3.12

HAL_SPI_Transmit_IT.................................................................... 521

39.3.13

HAL_SPI_Receive_IT..................................................................... 521

39.3.14

HAL_SPI_TransmitReceive_IT ...................................................... 522

39.3.15

HAL_SPI_Transmit_DMA ............................................................... 522

39.3.16

HAL_SPI_Receive_DMA ................................................................ 522

39.3.17

HAL_SPI_TransmitReceive_DMA .................................................. 523

39.3.18

HAL_SPI_DMAPause..................................................................... 523

39.3.19

HAL_SPI_DMAResume ................................................................. 523

26/654 DOCID026682 Rev 3

UM1816 Contents

39.3.20

HAL_SPI_DMAStop ....................................................................... 523

39.3.21

HAL_SPI_IRQHandler .................................................................... 523

39.3.22

HAL_SPI_TxCpltCallback .............................................................. 524

39.3.23

HAL_SPI_RxCpltCallback .............................................................. 524

39.3.24

HAL_SPI_TxRxCpltCallback .......................................................... 524

39.3.25

HAL_SPI_TxHalfCpltCallback ........................................................ 524

39.3.26

HAL_SPI_RxHalfCpltCallback ........................................................ 524

39.3.27

HAL_SPI_TxRxHalfCpltCallback .................................................... 525

39.3.28

HAL_SPI_ErrorCallback ................................................................. 525

39.3.29

HAL_SPI_GetState ......................................................................... 525

39.3.30

HAL_SPI_GetError ......................................................................... 525

39.4

SPI Firmware driver defines .......................................................... 525

39.4.1

SPI .................................................................................................. 525

40 HAL SRAM Generic Driver .......................................................... 532

40.1

HAL SRAM Generic Driver ............................................................ 532

40.2

SRAM Firmware driver registers structures................................... 532

40.2.1

SRAM_HandleTypeDef .................................................................. 532

40.3

SRAM Firmware driver API description ......................................... 532

40.3.1

How to use this driver ..................................................................... 532

40.3.2

SRAM Initialization and de_initialization functions ......................... 533

40.3.3

SRAM Input and Output functions .................................................. 533

40.3.4

SRAM Control functions ................................................................. 533

40.3.5

SRAM State functions .................................................................... 534

40.3.6

HAL_SRAM_Init ............................................................................. 534

40.3.7

HAL_SRAM_DeInit ......................................................................... 534

40.3.8

HAL_SRAM_MspInit ....................................................................... 534

40.3.9

HAL_SRAM_MspDeInit .................................................................. 534

40.3.10

HAL_SRAM_DMA_XferCpltCallback ............................................. 535

40.3.11

HAL_SRAM_DMA_XferErrorCallback ............................................ 535

40.3.12

HAL_SRAM_Read_8b.................................................................... 535

40.3.13

HAL_SRAM_Write_8b .................................................................... 535

40.3.14

HAL_SRAM_Read_16b.................................................................. 535

40.3.15

HAL_SRAM_Write_16b .................................................................. 536

40.3.16

HAL_SRAM_Read_32b.................................................................. 536

40.3.17

HAL_SRAM_Write_32b .................................................................. 536

40.3.18

HAL_SRAM_Read_DMA................................................................ 537

40.3.19

HAL_SRAM_Write_DMA ................................................................ 537

40.3.20

HAL_SRAM_WriteOperation_Enable ............................................. 537

DOCID026682 Rev 3 27/654

Contents UM1816

40.3.21

HAL_SRAM_WriteOperation_Disable ............................................ 537

40.3.22

HAL_SRAM_GetState .................................................................... 537

40.4

SRAM Firmware driver defines ..................................................... 538

40.4.1

SRAM ............................................................................................. 538

41 HAL TIM Generic Driver .............................................................. 539

41.1

HAL TIM Generic Driver ................................................................ 539

41.2

TIM Firmware driver registers structures ....................................... 539

41.2.1

TIM_Base_InitTypeDef ................................................................... 539

41.2.2

TIM_OC_InitTypeDef ...................................................................... 539

41.2.3

TIM_OnePulse_InitTypeDef ........................................................... 540

41.2.4

TIM_IC_InitTypeDef ....................................................................... 540

41.2.5

TIM_Encoder_InitTypeDef ............................................................. 541

41.2.6

TIM_ClockConfigTypeDef .............................................................. 542

41.2.7

TIM_ClearInputConfigTypeDef ....................................................... 542

41.2.8

TIM_SlaveConfigTypeDef .............................................................. 543

41.2.9

TIM_HandleTypeDef ...................................................................... 543

41.3

TIM Firmware driver API description ............................................. 544

41.3.1

TIMER Generic features ................................................................. 544

41.3.2

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

41.3.3

Time Base functions ....................................................................... 545

41.3.4

Time Output Compare functions .................................................... 545

41.3.5

Time PWM functions ...................................................................... 546

41.3.6

Time Input Capture functions ......................................................... 546

41.3.7

Time One Pulse functions .............................................................. 547

41.3.8

Time Encoder functions .................................................................. 547

41.3.9

IRQ handler management .............................................................. 548

41.3.10

Peripheral Control functions ........................................................... 548

41.3.11

TIM Callbacks functions ................................................................. 548

41.3.12

Peripheral State functions .............................................................. 549

41.3.13

HAL_TIM_Base_Init ....................................................................... 549

41.3.14

HAL_TIM_Base_DeInit ................................................................... 549

41.3.15

HAL_TIM_Base_MspInit................................................................. 549

41.3.16

HAL_TIM_Base_MspDeInit ............................................................ 549

41.3.17

HAL_TIM_Base_Start..................................................................... 550

41.3.18

HAL_TIM_Base_Stop ..................................................................... 550

41.3.19

HAL_TIM_Base_Start_IT ............................................................... 550

41.3.20

HAL_TIM_Base_Stop_IT................................................................ 550

41.3.21

HAL_TIM_Base_Start_DMA .......................................................... 550

28/654 DOCID026682 Rev 3

UM1816 Contents

41.3.22

HAL_TIM_Base_Stop_DMA ........................................................... 551

41.3.23

HAL_TIM_OC_Init .......................................................................... 551

41.3.24

HAL_TIM_OC_DeInit ...................................................................... 551

41.3.25

HAL_TIM_OC_MspInit ................................................................... 551

41.3.26

HAL_TIM_OC_MspDeInit ............................................................... 551

41.3.27

HAL_TIM_OC_Start ....................................................................... 551

41.3.28

HAL_TIM_OC_Stop ........................................................................ 552

41.3.29

HAL_TIM_OC_Start_IT .................................................................. 552

41.3.30

HAL_TIM_OC_Stop_IT .................................................................. 552

41.3.31

HAL_TIM_OC_Start_DMA ............................................................. 553

41.3.32

HAL_TIM_OC_Stop_DMA ............................................................. 553

41.3.33

HAL_TIM_PWM_Init ....................................................................... 553

41.3.34

HAL_TIM_PWM_DeInit .................................................................. 553

41.3.35

HAL_TIM_PWM_MspInit ................................................................ 554

41.3.36

HAL_TIM_PWM_MspDeInit ........................................................... 554

41.3.37

HAL_TIM_PWM_Start .................................................................... 554

41.3.38

HAL_TIM_PWM_Stop .................................................................... 554

41.3.39

HAL_TIM_PWM_Start_IT ............................................................... 554

41.3.40

HAL_TIM_PWM_Stop_IT ............................................................... 555

41.3.41

HAL_TIM_PWM_Start_DMA .......................................................... 555

41.3.42

HAL_TIM_PWM_Stop_DMA .......................................................... 555

41.3.43

HAL_TIM_IC_Init ............................................................................ 556

41.3.44

HAL_TIM_IC_DeInit ....................................................................... 556

41.3.45

HAL_TIM_IC_MspInit ..................................................................... 556

41.3.46

HAL_TIM_IC_MspDeInit................................................................. 556

41.3.47

HAL_TIM_IC_Start ......................................................................... 556

41.3.48

HAL_TIM_IC_Stop ......................................................................... 556

41.3.49

HAL_TIM_IC_Start_IT .................................................................... 557

41.3.50

HAL_TIM_IC_Stop_IT .................................................................... 557

41.3.51

HAL_TIM_IC_Start_DMA ............................................................... 557

41.3.52

HAL_TIM_IC_Stop_DMA ............................................................... 558

41.3.53

HAL_TIM_OnePulse_Init ................................................................ 558

41.3.54

HAL_TIM_OnePulse_DeInit ........................................................... 558

41.3.55

HAL_TIM_OnePulse_MspInit ......................................................... 558

41.3.56

HAL_TIM_OnePulse_MspDeInit .................................................... 559

41.3.57

HAL_TIM_OnePulse_Start ............................................................. 559

41.3.58

HAL_TIM_OnePulse_Stop ............................................................. 559

41.3.59

HAL_TIM_OnePulse_Start_IT ........................................................ 559

DOCID026682 Rev 3 29/654

Contents

30/654

UM1816

41.3.60

HAL_TIM_OnePulse_Stop_IT ........................................................ 559

41.3.61

HAL_TIM_Encoder_Init .................................................................. 560

41.3.62

HAL_TIM_Encoder_DeInit ............................................................. 560

41.3.63

HAL_TIM_Encoder_MspInit ........................................................... 560

41.3.64

HAL_TIM_Encoder_MspDeInit ....................................................... 560

41.3.65

HAL_TIM_Encoder_Start ............................................................... 560

41.3.66

HAL_TIM_Encoder_Stop ............................................................... 561

41.3.67

HAL_TIM_Encoder_Start_IT .......................................................... 561

41.3.68

HAL_TIM_Encoder_Stop_IT .......................................................... 561

41.3.69

HAL_TIM_Encoder_Start_DMA ..................................................... 562

41.3.70

HAL_TIM_Encoder_Stop_DMA ..................................................... 562

41.3.71

HAL_TIM_IRQHandler ................................................................... 562

41.3.72

HAL_TIM_OC_ConfigChannel ....................................................... 562

41.3.73

HAL_TIM_IC_ConfigChannel ......................................................... 563

41.3.74

HAL_TIM_PWM_ConfigChannel .................................................... 563

41.3.75

HAL_TIM_OnePulse_ConfigChannel ............................................. 563

41.3.76

HAL_TIM_DMABurst_WriteStart .................................................... 564

41.3.77

HAL_TIM_DMABurst_WriteStop .................................................... 564

41.3.78

HAL_TIM_DMABurst_ReadStart .................................................... 565

41.3.79

HAL_TIM_DMABurst_ReadStop .................................................... 566

41.3.80

HAL_TIM_GenerateEvent .............................................................. 566

41.3.81

HAL_TIM_ConfigOCrefClear .......................................................... 566

41.3.82

HAL_TIM_ConfigClockSource ....................................................... 566

41.3.83

HAL_TIM_ConfigTI1Input ............................................................... 567

41.3.84

HAL_TIM_SlaveConfigSynchronization ......................................... 567

41.3.85

HAL_TIM_SlaveConfigSynchronization_IT .................................... 567

41.3.86

HAL_TIM_ReadCapturedValue ...................................................... 568

41.3.87

HAL_TIM_PeriodElapsedCallback ................................................. 568

41.3.88

HAL_TIM_OC_DelayElapsedCallback ........................................... 568

41.3.89

HAL_TIM_IC_CaptureCallback ...................................................... 568

41.3.90

HAL_TIM_PWM_PulseFinishedCallback ....................................... 568

41.3.91

HAL_TIM_TriggerCallback ............................................................. 569

41.3.92

HAL_TIM_ErrorCallback................................................................. 569

41.3.93

HAL_TIM_Base_GetState .............................................................. 569

41.3.94

HAL_TIM_OC_GetState ................................................................. 569

41.3.95

HAL_TIM_PWM_GetState ............................................................. 569

41.3.96

HAL_TIM_IC_GetState................................................................... 569

41.3.97

HAL_TIM_OnePulse_GetState ...................................................... 570

41.3.98

HAL_TIM_Encoder_GetState ......................................................... 570

DOCID026682 Rev 3

UM1816 Contents

41.3.99

TIM_DMAError ............................................................................... 570

41.3.100

TIM_DMADelayPulseCplt ............................................................... 570

41.3.101

TIM_DMACaptureCplt .................................................................... 570

41.4

TIM Firmware driver defines.......................................................... 571

41.4.1

TIM .................................................................................................. 571

42 HAL TIM Extension Driver ........................................................... 589

42.1

HAL TIM Extension Driver ............................................................. 589

42.2

TIMEx Firmware driver registers structures................................... 589

42.2.1

TIM_MasterConfigTypeDef ............................................................ 589

42.3

TIMEx Firmware driver API description ......................................... 589

42.3.1

TIMER Extended features .............................................................. 589

42.3.2

Peripheral Control functions ........................................................... 589

42.3.3

HAL_TIMEx_MasterConfigSynchronization ................................... 589

42.3.4

HAL_TIMEx_RemapConfig ............................................................ 590

42.4

TIMEx Firmware driver defines ..................................................... 591

42.4.1

TIMEx ............................................................................................. 591

43 HAL UART Generic Driver ........................................................... 593

43.1

HAL UART Generic Driver ............................................................ 593

43.2

UART Firmware driver registers structures ................................... 593

43.2.1

UART_InitTypeDef ......................................................................... 593

43.2.2

UART_HandleTypeDef ................................................................... 594

43.3

UART Firmware driver API description ......................................... 595

43.3.1

How to use this driver ..................................................................... 595

43.3.2

Initialization and Configuration functions ........................................ 597

43.3.3

IO operation functions .................................................................... 597

43.3.4

Peripheral Control functions ........................................................... 598

43.3.5

Peripheral State and Errors functions ............................................ 599

43.3.6

HAL_UART_Init .............................................................................. 599

43.3.7

HAL_HalfDuplex_Init ...................................................................... 599

43.3.8

HAL_LIN_Init .................................................................................. 600

43.3.9

HAL_MultiProcessor_Init ................................................................ 600

43.3.10

HAL_UART_DeInit ......................................................................... 600

43.3.11

HAL_UART_MspInit ....................................................................... 600

43.3.12

HAL_UART_MspDeInit................................................................... 601

43.3.13

HAL_UART_Transmit ..................................................................... 601

43.3.14

HAL_UART_Receive ...................................................................... 601

43.3.15

HAL_UART_Transmit_IT................................................................ 601

DOCID026682 Rev 3 31/654

Contents UM1816

43.3.16

HAL_UART_Receive_IT................................................................. 602

43.3.17

HAL_UART_Transmit_DMA ........................................................... 602

43.3.18

HAL_UART_Receive_DMA ............................................................ 602

43.3.19

HAL_UART_DMAPause................................................................. 602

43.3.20

HAL_UART_DMAResume ............................................................. 603

43.3.21

HAL_UART_DMAStop ................................................................... 603

43.3.22

HAL_UART_IRQHandler ................................................................ 603

43.3.23

HAL_UART_TxCpltCallback .......................................................... 603

43.3.24

HAL_UART_TxHalfCpltCallback .................................................... 604

43.3.25

HAL_UART_RxCpltCallback .......................................................... 604

43.3.26

HAL_UART_RxHalfCpltCallback .................................................... 604

43.3.27

HAL_UART_ErrorCallback ............................................................. 604

43.3.28

HAL_LIN_SendBreak ..................................................................... 604

43.3.29

HAL_MultiProcessor_EnterMuteMode ........................................... 605

43.3.30

HAL_MultiProcessor_ExitMuteMode .............................................. 605

43.3.31

HAL_HalfDuplex_EnableTransmitter ............................................. 605

43.3.32

HAL_HalfDuplex_EnableReceiver ................................................. 605

43.3.33

HAL_UART_GetState..................................................................... 605

43.3.34

HAL_UART_GetError ..................................................................... 606

43.4

UART Firmware driver defines ...................................................... 606

43.4.1

UART .............................................................................................. 606

44 HAL USART Generic Driver ........................................................ 618

44.1

HAL USART Generic Driver .......................................................... 618

44.2

USART Firmware driver registers structures ................................. 618

44.2.1

USART_InitTypeDef ....................................................................... 618

44.2.2

USART_HandleTypeDef ................................................................ 619

44.3

USART Firmware driver API description ....................................... 620

44.3.1

How to use this driver ..................................................................... 620

44.3.2

Initialization and Configuration functions ........................................ 622

44.3.3

IO operation functions .................................................................... 622

44.3.4

Peripheral State and Errors functions ............................................ 623

44.3.5

HAL_USART_Init ............................................................................ 624

44.3.6

HAL_USART_DeInit ....................................................................... 624

44.3.7

HAL_USART_MspInit ..................................................................... 624

44.3.8

HAL_USART_MspDeInit ................................................................ 624

44.3.9

HAL_USART_Transmit .................................................................. 624

44.3.10

HAL_USART_Receive ................................................................... 625

44.3.11

HAL_USART_TransmitReceive ..................................................... 625

32/654 DOCID026682 Rev 3

UM1816 Contents

44.3.12

HAL_USART_Transmit_IT ............................................................. 625

44.3.13

HAL_USART_Receive_IT .............................................................. 626

44.3.14

HAL_USART_TransmitReceive_IT ................................................ 626

44.3.15

HAL_USART_Transmit_DMA ........................................................ 626

44.3.16

HAL_USART_Receive_DMA ......................................................... 627

44.3.17

HAL_USART_TransmitReceive_DMA ........................................... 627

44.3.18

HAL_USART_DMAPause .............................................................. 627

44.3.19

HAL_USART_DMAResume ........................................................... 627

44.3.20

HAL_USART_DMAStop ................................................................. 628

44.3.21

HAL_USART_IRQHandler ............................................................. 628

44.3.22

HAL_USART_TxCpltCallback ........................................................ 628

44.3.23

HAL_USART_TxHalfCpltCallback .................................................. 628

44.3.24

HAL_USART_RxCpltCallback ........................................................ 629

44.3.25

HAL_USART_RxHalfCpltCallback ................................................. 629

44.3.26

HAL_USART_TxRxCpltCallback .................................................... 629

44.3.27

HAL_USART_ErrorCallback .......................................................... 629

44.3.28

HAL_USART_GetState .................................................................. 629

44.3.29

HAL_USART_GetError................................................................... 630

44.4

USART Firmware driver defines .................................................... 630

44.4.1

USART............................................................................................ 630

45 HAL WWDG Generic Driver ........................................................ 639

45.1

HAL WWDG Generic Driver .......................................................... 639

45.2

WWDG Firmware driver registers structures ................................. 639

45.2.1

WWDG_InitTypeDef ....................................................................... 639

45.2.2

WWDG_HandleTypeDef ................................................................ 639

45.3

WWDG Firmware driver API description ....................................... 640

45.3.1

WWDG specific features ................................................................ 640

45.3.2

How to use this driver ..................................................................... 640

45.3.3

Initialization and de-initialization functions ..................................... 640

45.3.4

IO operation functions .................................................................... 641

45.3.5

Peripheral State functions .............................................................. 641

45.3.6

HAL_WWDG_Init ............................................................................ 641

45.3.7

HAL_WWDG_DeInit ....................................................................... 641

45.3.8

HAL_WWDG_MspInit ..................................................................... 642

45.3.9

HAL_WWDG_MspDeInit ................................................................ 642

45.3.10

HAL_WWDG_WakeupCallback ..................................................... 642

45.3.11

HAL_WWDG_Start ......................................................................... 642

45.3.12

HAL_WWDG_Start_IT.................................................................... 642

DOCID026682 Rev 3 33/654

Contents UM1816

45.3.13

HAL_WWDG_Refresh .................................................................... 643

45.3.14

HAL_WWDG_IRQHandler ............................................................. 643

45.3.15

HAL_WWDG_WakeupCallback ..................................................... 643

45.3.16

HAL_WWDG_GetState .................................................................. 643

45.4

WWDG Firmware driver defines .................................................... 644

45.4.1

WWDG............................................................................................ 644

46 FAQs ............................................................................................. 648

47 Revision history .......................................................................... 652

34/654 DOCID026682 Rev 3

UM1816

List of tables

List of tables

Table 1: Acronyms and definitions ............................................................................................................ 37

Table 2: HAL drivers files .......................................................................................................................... 39

Table 3: User-application files .................................................................................................................. 40

Table 4: APis classification ....................................................................................................................... 45

Table 5: List of devices supported by HAL drivers ................................................................................... 46

Table 6: HAL API naming rules ................................................................................................................ 50

Table 7: Macros handling interrupts and specific clock configurations .................................................... 51

Table 8: Callback functions ....................................................................................................................... 52

Table 9: HAL generic APIs ....................................................................................................................... 53

Table 10: HAL extension APIs .................................................................................................................. 54

Table 11: Define statements used for HAL configuration ......................................................................... 59

Table 12: Description of GPIO_InitTypeDef structure .............................................................................. 61

Table 13: Description of EXTI configuration macros ................................................................................ 63

Table 14: MSP functions ........................................................................................................................... 68

Table 15: Timeout values ......................................................................................................................... 71

Table 16: Redirection of COMP outputs to embedded timers ................................................................ 122

Table 17: COMP Inputs for the STM32L1xx devices ............................................................................. 122

Table 18: IRDA frame formats ................................................................................................................ 271

Table 19: OPAMPs inverting/non-inverting inputs for STM32L1 devices ............................................... 317

Table 20: OPAMP outputs for STM32L1 devices ................................................................................... 317

Table 21: Number of wait states (WS) according to CPU clock (HCLK) frequency ............................... 369

Table 22: Clock frequency versus product voltage range ...................................................................... 369

Table 23: Smartcard frame formats ........................................................................................................ 499

Table 24: UART frame formats ............................................................................................................... 597

Table 25: USART frame formats ............................................................................................................ 622

Table 26: Document revision history ...................................................................................................... 652

DOCID026682 Rev 3 35/654

List of figures

List of figures

UM1816

Figure 1: Example of project template ...................................................................................................... 42

Figure 2: Adding device-specific functions ............................................................................................... 55

Figure 3: Adding family-specific functions ................................................................................................ 55

Figure 4: Adding new peripherals ............................................................................................................. 56

Figure 5: Updating existing APIs .............................................................................................................. 56

Figure 6: File inclusion model ................................................................................................................... 57

Figure 7: HAL driver model ....................................................................................................................... 66

36/654 DOCID026682 Rev 3

UM1816

1

Acronyms and definitions

Acronyms and definitions

Acronym

Table 1: Acronyms and definitions

Definition

NVIC

PCD

PWR

RCC

RNG

RTC

SD

GPIO

HAL

I2C

I2S

IRDA

IWDG

LCD

MSP

ADC

ANSI

API

BSP

COMP

CMSIS

CPU

CRYP

CRC

DAC

DMA

EXTI

FLASH

SRAM

SMARTCARD

SPI

SysTick

TIM

TSC

Analog-to-digital converter

American National Standards Institute

Application Programming Interface

Board Support Package

Comparator

Cortex Microcontroller Software Interface Standard

Central Processing Unit

Cryptographic processor unit

CRC calculation unit

Digital to analog converter

Direct Memory Access

External interrupt/event controller

Flash memory

General purpose I/Os

Hardware abstraction layer

Inter-integrated circuit

Inter-integrated sound

InfraRed Data Association

Independent watchdog

Liquid Crystal Display Controler

MCU Specific Package

Nested Vectored Interrupt Controller

USB Peripheral Controller Driver

Power controller

Reset and clock controller

Random Number Generator

Real-time clock

Secure Digital

SRAM external memory

Smartcard IC

Serial Peripheral interface

System tick timer

Advanced-control, general-purpose or basic timer

Touch Sensing Controller

DOCID026682 Rev 3 37/654

Acronyms and definitions

Acronym

UART

USART

WWDG

USB

PPP

Definition

Universal asynchronous receiver/transmitter

Universal synchronous receiver/transmitter

Window watchdog

Universal Serial Bus

STM32 peripheral or block

UM1816

38/654 DOCID026682 Rev 3

UM1816

2

2.1

2.1.1

Overview of HAL drivers

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

HAL and user-application files

HAL driver files

A HAL drivers are composed of the following set of files:

File

Table 2: HAL drivers files

Description

stm32l1xx_hal_ppp.c

stm32l1xx_hal_ppp.h

Main peripheral/module driver file.

It includes the APIs that are common to all STM32 devices.

Example: stm32l1xx_hal_adc.c, stm32l1xx_hal_irda.c, …

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: stm32l1xx_hal_adc.h, stm32l1xx_hal_irda.h, …

DOCID026682 Rev 3 39/654

Overview of HAL drivers

File

stm32l1xx_hal_ppp_ex.c

stm32l1xx_hal_ppp_ex.h

stm32l1xx_hal.c

stm32l1xx_hal.h

stm32l1xx_hal_msp_template.c

stm32l1xx_hal_conf_template.h

stm32l1xx_hal_def.h

UM1816

Description

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: stm32l1xx_hal_adc_ex.c, stm32l1xx_hal_dma_ex.c, …

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: stm32l1xx_hal_adc_ex.h, stm32l1xx_hal_dma_ex.h, …

This file is used for HAL initialization and contains DBGMCU,

Remap and Time Delay based on systick APIs. stm32l1xx_hal.c header file

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.

Template file allowing to customize the drivers for a given application.

Common HAL resources such as common define statements, enumerations, structures and macros.

2.1.2 User-application files

The minimum files required to build an application using the HAL are listed in the table below:

File

Table 3: User-application files

Description

system_stm32l1xx.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 is to be done using the HAL APIs in the user files.

It allows to :

 relocate the vector table in internal SRAM.

startup_stm32l1xx.s

stm32l1xx_flash.icf

(optional)

stm32l1xx_hal_msp.c

stm32l1xx_hal_conf.h

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.

Linker file for EWARM toolchain allowing mainly to adapt the stack/heap size to fit the application requirements.

This file contains the MSP initialization and de-initialization (main routine and callbacks) of the peripheral used in the user application.

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.

40/654 DOCID026682 Rev 3

UM1816

File

stm32l1xx_it.c/.h

Overview of HAL drivers

Description

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

main.c/.h

This file contains the main program routine, mainly:

 the call to HAL_Init()

 assert_failed() implementation

 system clock configuration

 peripheral HAL initialization and user application code.

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.

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.

DOCID026682 Rev 3 41/654

Overview of HAL drivers

Figure 1: Example of project template

UM1816

2.2

2.2.1

42/654

HAL data structures

Each HAL driver can contain the following data structures:

Peripheral handle structures

Initialization and configuration structures

Specific process structures.

Peripheral handle structures

The APIs have a modular generic multi-instance architecture that allows working with several IP instances simultaneously.

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.

DOCID026682 Rev 3

UM1816

Overview of HAL drivers

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

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.

DOCID026682 Rev 3 43/654

Overview of HAL drivers

2.2.2

UM1816

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);

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_Calibration_Start(ADC_HandleTypeDef* hadc, uint32_t

SingleDiff); uint32_t HAL_ADCEx_Calibration_GetValue(ADC_HandleTypeDef* hadc, uint32_t

SingleDiff);

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.

44/654 DOCID026682 Rev 3

UM1816

Overview of HAL drivers

#if defined(STM32L100xBA) || defined (STM32L151xBA) || defined (STM32L152xBA) || \ defined(STM32L100xC) || defined (STM32L151xC) || defined (STM32L152xC) || defined

(STM32L162xC) || \ defined(STM32L151xCA) || defined (STM32L151xD) || defined (STM32L152xCA) || defined

(STM32L152xD) || defined (STM32L162xCA) || defined (STM32L162xD) || \ defined(STM32L151xE) || defined (STM32L152xE) || defined (STM32L162xE) void HAL_RCCEx_EnableLSECSS(void); void HAL_RCCEx_DisableLSECSS(void);

#endif /* STM32L100xBA || ….. STM32L162xE*/

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.

Common APIs

Table 4: APis classification

Generic file

X

Extension file

X

(1)

Family specific APIs

Device specific APIs

X

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.

2.4 Devices supported by HAL drivers

DOCID026682 Rev 3 45/654

Overview of HAL drivers

VALUE LINE

Table 5: List of devices supported by HAL drivers

ACCESS LINE LCD LINE w/o AES

UM1816

LCD Line w/ AES

Files

stm32l1xx_hal.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_adc.c stm32l1xx_hal_adc.h Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_adc_ex.c stm32l1xx_hal_adc_ex.h stm32l1xx_hal_comp.c stm32l1xx_hal_comp.h

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes stm32l1xx_hal_cortex.c stm32l1xx_hal_cortex.h

Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_crc.c stm32l1xx_hal_crc.h Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_cryp.c stm32l1xx_hal_cryp.h

No No No No No No No No No No No No No No No No No Yes Yes Yes Yes Yes stm32l1xx_hal_dac.c stm32l1xx_hal_dac.h Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_dac_ex.c stm32l1xx_hal_dac_ex.h

Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_dma.c stm32l1xx_hal_dma.h stm32l1xx_hal_flash.c stm32l1xx_hal_flash.h stm32l1xx_hal_flash_ramfunc.c stm32l1xx_hal_flash_ramfunc.h stm32l1xx_hal_flash_ex.c stm32l1xx_hal_flash_ex.h

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

46/654 DOCID026682 Rev 3

UM1816

Files

VALUE LINE ACCESS LINE LCD LINE w/o AES

Overview of HAL drivers

LCD Line w/ AES

stm32l1xx_hal_gpio.c stm32l1xx_hal_gpio.h

Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_i2c.c stm32l1xx_hal_i2c.h Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_i2c_ex.c Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_i2s.c stm32l1xx_hal_i2s.h No No Yes No No Yes Yes Yes Yes Yes No No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_irda.c stm32l1xx_hal_irda.h Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_iwdg.c stm32l1xx_hal_iwdg.h

Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_lcd.c stm32l1xx_hal_lcd.h Yes Yes Yes No No No No No No No No No No No No No No Yes Yes Yes Yes Yes stm32l1xx_hal_msp_template.c NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA stm32l1xx_hal_nor.c stm32l1xx_hal_nor.h No No No No No No No Yes No No No No No No Yes No No No No Yes No No stm32l1xx_hal_opamp.c stm32l1xx_hal_opamp.h stm32l1xx_hal_opamp_ex.c stm32l1xx_hal_opamp_ex.h

No

No

No

No

No

No

No

No

No

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

No

No

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes stm32l1xx_hal_pcd.c stm32l1xx_hal_pcd.h Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_pcd_ex.c stm32l1xx_hal_pcd_ex.h

Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_pwr.c stm32l1xx_hal_pwr_ex.c stm32l1xx_hal_pwr_ex.h

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes stm32l1xx_hal_rcc.c stm32l1xx_hal_rcc.h Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes

DOCID026682 Rev 3 47/654

Overview of HAL drivers

Files

VALUE LINE ACCESS LINE LCD LINE w/o AES

UM1816

LCD Line w/ AES

stm32l1xx_hal_rcc_ex.c stm32l1xx_hal_rcc_ex.h stm32l1xx_hal_rtc.c stm32l1xx_hal_rtc.h stm32l1xx_hal_rtc_ex.c stm32l1xx_hal_rtc_ex.h stm32l1xx_hal_sd.c stm32l1xx_hal_sd.h stm32l1xx_hal_spi_ex.c stm32l1xx_hal_sram.c stm32l1xx_hal_sram.h

Yes

Yes

Yes

No No No No No No No Yes No No No No No No Yes No No No No Yes No No stm32l1xx_hal_smartcard.c stm32l1xx_hal_smartcard.h

Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_spi.c stm32l1xx_hal_spi.h Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes

Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

No

Yes

Yes

Yes

No stm32l1xx_hal_tim.c stm32l1xx_hal_tim.h Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_tim_ex.cstm32l1xx_hal_tim

_ex.h stm32l1xx_hal_uart.c stm32l1xx_hal_uart.h

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes stm32l1xx_hal_usart.c stm32l1xx_hal_usart.h stm32l1xx_hal_wwdg.c stm32l1xx_hal_wwdg.h

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes stm32l1xx_ll_fsmc.c stm32l1xx_ll_fsmc.h No No No No No No No Yes No No No No No No Yes No No No No Yes No No

48/654 DOCID026682 Rev 3

UM1816

Files

stm32l1xx_ll_sdmmc.c stm32l1xx_ll_sdmmc.h

VALUE LINE ACCESS LINE LCD LINE w/o AES

Overview of HAL drivers

LCD Line w/ AES

No No No No No No No Yes No No No No No No Yes No No No No Yes No No

DOCID026682 Rev 3 49/654

Overview of HAL drivers

2.5 HAL drivers rules

2.5.1

UM1816

HAL API naming rules

The following naming rules are used in HAL drivers:

Generic

Table 6: HAL API naming rules

Family specific

File

names

stm32l1xx_hal_ppp (c/h) stm32l1xx_hal_ppp_ex (c/h)

Module

name

HAL_PPP_ MODULE

Device specific

stm32l1xx_ hal_ppp_ex (c/h)

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

Init structu re

name

PPP_HandleTypedef

PPP_InitTypeDef

NA

NA

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 STM32L1xx reference manuals.

Peripheral registers are declared in the PPP_TypeDef structure (e.g. ADC_TypeDef) in stm32l1xxx.h header file. stm32l1xxx.h corresponds to stm32l100xb.h, stm32l100xba.h, stm32l100xc.h, stm32l151xb.h, stm32l151xba.h, stm32l151xc.h, stm32l151xca.h, stm32l151xd.h, stm32l151xe.h, stm32l151xdx.h, stm32l152xb.h, stm32l152xba.h, stm32l152xc.h, stm32l152xca.h, stm32l152xd.h, stm32l152xe.h, stm32l152xdx.h, stm32l162xc.h, stm32l162xca.h, stm32l162xd.h or stm32l162xe.h, stm32l162xdx.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()).

50/654 DOCID026682 Rev 3

UM1816

2.5.2

Overview of HAL drivers

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_Start() refers to the injection mode

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

Macros Description

__HAL_PPP_ENABLE_IT(__HANDLE__, __INTERRUPT__)

__HAL_PPP_DISABLE_IT(__HANDLE__, __INTERRUPT__)

__HAL_PPP_GET_IT (__HANDLE__, __ INTERRUPT __)

__HAL_PPP_CLEAR_IT (__HANDLE__, __ INTERRUPT __)

__HAL_PPP_GET_FLAG (__HANDLE__, __FLAG__)

__HAL_PPP_CLEAR_FLAG (__HANDLE__, __FLAG__)

__HAL_PPP_ENABLE(__HANDLE__)

__HAL_PPP_DISABLE(__HANDLE__)

__HAL_PPP_XXXX (__HANDLE__, __PARAM__)

__HAL_PPP_GET_ IT_SOURCE (__HANDLE__, __

INTERRUPT __)

Enables a specific peripheral interrupt

Disables a specific peripheral interrupt

Gets a specific peripheral interrupt status

Clears a specific peripheral interrupt status

Gets a specific peripheral flag status

Clears a specific peripheral flag status

Enables a peripheral

Disables a peripheral

Specific PPP HAL driver macro

Checks the source of specified interrupt

DOCID026682 Rev 3 51/654

Overview of HAL drivers

UM1816

NVIC and SYSTICK are two ARM Cortex core features. The APIs related to these features are located in the stm32l1xx_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 = XX | (YY

<< 8) | (YY << 16) | (YY << 24)".

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

Callback functions

Table 8: Callback functions

Example

HAL_PPP_MspInit() / _DeInit()

HAL_PPP_ProcessCpltCallback

HAL_PPP_ErrorCallback

Ex: HAL_USART_MspInit()

Called from HAL_PPP_Init() API function to perform peripheral system level initialization (GPIOs, clock, DMA, interrupt)

Ex: HAL_USART_TxCpltCallback

Called by peripheral or DMA interrupt handler when the process completes

Ex: HAL_USART_ErrorCallback

Called by peripheral or DMA interrupt handler when an error occurs

52/654 DOCID026682 Rev 3

UM1816

2.6

Overview of HAL drivers

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

Initialization

group

IO operation

group

HAL_ADC_Init()

HAL_ADC_DeInit()

HAL_ADC_Start ()

HAL_ADC_Stop ()

This function initializes the peripheral and configures the low -level resources (clocks,

GPIO, AF..)

This function restores the peripheral default state, frees the low-level resources and removes any direct dependency with the hardware.

This function starts ADC conversions when the polling method is used

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()

HAL_ADC_IRQHandler()

This function stops ADC conversions when the interrupt method is used

This function handles ADC interrupt requests

DOCID026682 Rev 3 53/654

Overview of HAL drivers

Function

Group

Common API Name Description

UM1816

Control group

State and

Errors group

HAL_ADC_ConvCpltCallback()

HAL_ADC_ErrorCallback()

HAL_ADC_ConfigChannel()

HAL_ADC_AnalogWDGConfig

HAL_ADC_GetState()

HAL_ADC_GetError()

Callback function called in the IT subroutine to indicate the end of the current process or when a

DMA transfer has completed

Callback function called in the IT subroutine if a peripheral error or a DMA transfer error occurred

This function configures the selected ADC regular channel, the corresponding rank in the sequencer and the sample time

This function configures the analog watchdog for the selected ADC

This function allows getting in runtime the peripheral and the data flow states.

This fuction allows getting in runtime the error that occurred during IT routine

2.7

2.7.1

2.7.2

HAL extension APIs

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, stm32l1xx_hal_ppp_ex.c, that includes all the specific functions and define statements (stm32l1xx_hal_ppp_ex.h) for a given part number.

Below an example based on the ADC peripheral:

Function Group

Table 10: HAL extension APIs

Common API Name

HAL_ADCEx_CalibrationStart()

HAL_ADCEx_Calibration_GetValue()

HAL_ADCEx_Calibration_SetValue()

This function is used to start the automatic ADC calibration

This function is used to get the ADC calibration factor

This function is used to set the calibration factor to overwrite automatic conversion result

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 stm32l1xx_hal_ppp_ex.c extension file. They are named HAL_PPPEx_Function().

54/654 DOCID026682 Rev 3

UM1816

Figure 2: Adding device-specific functions

Overview of HAL drivers

Example: stm32l1xx_hal_rcc_ex.c/h

#if defined(STM32L100xBA) || defined (STM32L151xBA) || defined (STM32L152xBA) || \ defined(STM32L100xC) || defined (STM32L151xC) || defined (STM32L152xC) || defined

STM32L162xC) || \ defined(STM32L151xCA) || defined (STM32L151xD) || defined (STM32L152xCA) || defined

(STM32L152xD) || defined (STM32L162xCA) || defined (STM32L162xD) ||\ defined(STM32L151xE) || defined (STM32L152xE) || defined (STM32L162xE) void HAL_RCCEx_EnableLSECSS(void); void HAL_RCCEx_DisableLSECSS(void);

#endif /* STM32L100xBA || ….. STM32L162xE*/

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

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 stm32l1xx_hal_newppp.c.

However the inclusion of this file is selected in the stm32lxx_hal_conf.h using the macro:

#define HAL_NEWPPP_MODULE_ENABLED

DOCID026682 Rev 3 55/654

Overview of HAL drivers

Figure 4: Adding new peripherals

UM1816

Example: stm32l1xx_hal_lcd.c/h

Case4: Updating existing common APIs

In this case, the routines are defined with the same names in the stm32l1xx_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

56/654

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 (STM32L100xB) typedef struct

{

(…)

}PPP_InitTypeDef;

#endif /* STM32L100xB */

DOCID026682 Rev 3

UM1816

2.8

Overview of HAL drivers

File inclusion model

The header of the common HAL driver file (stm32l1xx_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 stm32l1xx_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

(…)

DOCID026682 Rev 3 57/654

Overview of HAL drivers

2.9

UM1816

HAL common resources

The common HAL resources, such as common define enumerations, structures and macros, are defined in stm32l1xx_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, /*!<Resources unlocked */

HAL_LOCKED = 0x01 /*!< Resources locked */

} HAL_LockTypeDef;In addition to common resources, the stm32l1xx_hal_def.h file calls the stm32l1xx.h file in CMSIS library to get the data structures and the address mapping for all peripherals:

Declarations of peripheral registers and bits definition.

Macros to access peripheral registers hardware (Write register, Read register…etc.).

Common macros

Macro defining HAL_MAX_DELAY

#define HAL_MAX_DELAY 0xFFFFFFFF

Macro linking a PPP peripheral to a DMA structure pointer: __HAL_LINKDMA();

#define __HAL_LINKDMA(__HANDLE__, __PPP_DMA_FIELD_, __DMA_HANDLE_) \ do{ \

(__HANDLE__)->__PPP_DMA_FIELD_ = &(__DMA_HANDLE_); \

(__DMA_HANDLE_).Parent = (__HANDLE__); \

} while(0)

58/654 DOCID026682 Rev 3

UM1816

Overview of HAL drivers

2.10 HAL configuration

The configuration file, stm32l1xx_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

HSE_STARTUP_TIMEOUT

HSI_VALUE

MSI_VALUE

LSE_VALUE

LSE_STARTUP_TIMEOUT

VDD_VALUE

USE_RTOS

PREFETCH_ENABLE

BUFFER_CACHE_ENABLE

Defines the value of the external oscillator (HSE) expressed in Hz. The user must adjust this define statement when using a different crystal value.

Timeout for HSE start up, expressed in ms

Defines the value of the internal oscillator (HSI) expressed in Hz.

Defines the Internal Multiple Speed oscillator (MSI) value expressed in Hz.

Defines the value of the external oscillator (HSE) expressed in Hz. The user must adjust this define statement when using a different crystal value.

Timeout for LSE start up, expressed in ms

VDD value

Enables the use of RTOS

Enables prefetch feature

Enables buffer cache

8 000 000

(Hz)

5000

16 000 000

(Hz)

2 097 000

(Hz)

32768 (Hz)

5000

3300 (mV)

FALSE (for future use)

TRUE

FALSE

The stm32l1xx_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 stm32l1xx_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.

DOCID026682 Rev 3 59/654

Overview of HAL drivers

UM1816

2.11 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, USB…). In this case, the clock configuration is performed by an extended API defined in stm32l1xx_hal_rcc_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 stm32l1xx_hal_rcc.h and stm32l1xx_hal_rcc_ex.h. They allow 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 stm32l1xx_it.c and implement

HAL_GPIO_EXTI_Callback()

The table below describes the GPIO_InitTypeDef structure field.

60/654 DOCID026682 Rev 3

UM1816

Overview of HAL drivers

Structure field

Pin

Mode

Pull

Speed

Table 12: Description of GPIO_InitTypeDef structure

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:

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_VERY_LOW

GPIO_SPEED_LOW

GPIO_SPEED_MEDIUM

GPIO_SPEED_HIGH

DOCID026682 Rev 3 61/654

Overview of HAL drivers

Structure field

Alternate

Description

UM1816

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_TIM2 to connect TIM2 IOs on AF1.

These values are defined in the GPIO extended driver, since the AF mapping may change between product lines.

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_MEDIUM;

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 USART1 Tx (PA9, mapped on AF4) as alternate function:

GPIO_InitStruct.Pin = GPIO_PIN_9;

GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;

GPIO_InitStruct.Pull = GPIO_PULLUP;

GPIO_InitStruct.Speed = GPIO_SPEED_FAST;

GPIO_InitStruct.Alternate = GPIO_AF4_USART1;

HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);

2.11.3 Cortex NVIC and SysTick timer

The Cortex HAL driver, stm32l1xx_hal_cortex.c, provides APIs to handle NVIC and Systick.

The supported APIs include:

HAL_NVIC_SetPriority()

HAL_NVIC_EnableIRQ()/HAL_NVIC_DisableIRQ()

HAL_NVIC_SystemReset()

HAL_SYSTICK_IRQHandler()

HAL_NVIC_GetPendingIRQ() / HAL_NVIC_SetPendingIRQ () /

HAL_NVIC_ClearPendingIRQ()

HAL_SYSTICK_Config()

HAL_SYSTICK_CLKSourceConfig()

HAL_SYSTICK_Callback()

62/654 DOCID026682 Rev 3

UM1816

2.11.4 PWR

Overview of HAL drivers

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()

Depending on the STM32 Series, extension functions are available in stm32l1xx_hal_pwr_ex. Here are a few examples (the list is not exhaustive)

Ultra low power mode control

HAL_PWREx_EnableUltraLowPower() / HAL_PWREx_DisableUltraLowPower()

HAL_PWREx_EnableLowPowerRunMode() /

HAL_PWREx_DisableLowPowerRunMode()

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

__HAL_PPP_EXTI_ENABLE_IT(__EXTI_LINE__)

__HAL_PPP_EXTI_DISABLE_IT(__EXTI_LINE__)

Defines the EXTI line connected to the internal peripheral.

Example:

#define PWR_EXTI_LINE_PVD ((uint32_t)0x00010000)

/*!<External interrupt line 16 Connected to the PVD EXTI

Line */

Enables a given EXTI line

Example:

__HAL_PVD_EXTI_ENABLE_IT(PWR_EXTI_LINE_PVD)

Disables a given EXTI line.

Example:

__HAL_PVD_EXTI_DISABLE_IT(PWR_EXTI_LINE_PVD)

DOCID026682 Rev 3 63/654

Overview of HAL drivers

Macros

__HAL_PPP_EXTI_GET_FLAG(__EXTI_LINE__)

UM1816

Description

Gets a given EXTI line interrupt flag pending bit status.

Example:

__HAL_PVD_EXTI_GET_FLAG(PWR_EXTI_LINE_PVD)

__HAL_PPP_EXTI_CLEAR_FLAG(__EXTI_LINE_

_)

Clears a given EXTI line interrupt flag pending bit.

Example;

__HAL_PVD_EXTI_CLEAR_FLAG(PWR_EXTI_LINE_PV

D)

__HAL_PPP_EXTI_GENERATE_SWIT

(__EXTI_LINE__)

Generates a software interrupt for a given EXTI line.

Example:

__HAL_PVD_EXTI_ GENERATE_SWIT

(PWR_EXTI_LINE_PVD)

If the EXTI interrupt mode is selected, the user application must call

HAL_PPP_FUNCTION_IRQHandler() (for example HAL_PWR_PVD_IRQHandler()), from stm32l1xx_it.c file, and implement HAL_PPP_FUNCTIONCallback() callback function (for example HAL_PWR_PVDCallback().

2.11.6 DMA

The DMA HAL driver allows enabling and configuring the peripheral to be connected to the

DMA Channels (except for internal SRAM/FLASH memory which do not require any initialization). Refer to the product reference manual for details on the DMA request corresponding to each peripheral.

For a given channel, HAL_DMA_Init() API allows programming the required configuration through the following parameters:

Transfer Direction

Source and Destination data formats

Circular, Normal or peripheral flow control mode

Channels Priority level

Source and Destination Increment mode

Two operating modes are available:

Polling mode I/O operation a. Use HAL_DMA_Start() to start DMA transfer when the source and destination addresses and the Length of data to be transferred have been configured. b. Use HAL_DMA_PollForTransfer() to poll for the end of current transfer. In this case a fixed timeout can be configured depending on the user application.

Interrupt mode I/O operation a. Configure the DMA interrupt priority using HAL_NVIC_SetPriority() b. Enable the DMA IRQ handler using HAL_NVIC_EnableIRQ() c. Use HAL_DMA_Start_IT() to start DMA transfer when the source and destination addresses and the length of data to be transferred have been confgured. In this case the DMA interrupt is configured. d. Use HAL_DMA_IRQHandler() called under DMA_IRQHandler() Interrupt subroutine e. When data transfer is complete, HAL_DMA_IRQHandler() function is executed and a user function can be called by customizing XferCpltCallback and

XferErrorCallback function pointer (i.e. a member of DMA handle structure).

64/654 DOCID026682 Rev 3

UM1816

Overview of HAL drivers

Additional functions and macros are available to ensure efficient DMA management:

Use HAL_DMA_GetState() function to return the DMA state and

HAL_DMA_GetError() in case of error detection.

Use HAL_DMA_Abort() function to abort the current transfer

The most used DMA HAL driver macros are the following:

__HAL_DMA_ENABLE: enablse the specified DMA Channels.

__HAL_DMA_DISABLE: disables the specified DMA Channels.

__HAL_DMA_GET_FLAG: gets the DMA Channels pending flags.

__HAL_DMA_CLEAR_FLAG: clears the DMA Channels pending flags.

__HAL_DMA_ENABLE_IT: enables the specified DMA Channels interrupts.

__HAL_DMA_DISABLE_IT: disables the specified DMA Channels interrupts.

__HAL_DMA_GET_IT_SOURCE: checks whether the specified DMA stream interrupt has occurred or not.

When a peripheral is used in DMA mode, the DMA initialization should be done in the HAL_PPP_MspInit() callback. In addition, the user application should associate the DMA handle to the PPP handle (refer to section “HAL IO operation func tions”).

DMA channel callbacks need to be initialized by the user application only in case of memory-to-memory transfer. However when peripheral-to-memory transfers are used, these callbacks are automatically initialized by calling a process API function that uses the DMA.

2.12 How to use HAL drivers

2.12.1 HAL usage models

The following figure shows the typical use of the HAL driver and the interaction between the application user, the HAL driver and the interrupts.

DOCID026682 Rev 3 65/654

Overview of HAL drivers

Figure 7: HAL driver model

UM1816

Basically, the HAL driver APIs are called from user files and optionally from interrupt handlers file when the APIs based on the DMA or the PPP peripheral dedicated interrupts are used.

When DMA or PPP peripheral interrupts are used, the PPP process complete callbacks are called to inform the user about the process completion in real-time event mode (interrupts).

Note that the same process completion callbacks are used for DMA in interrupt mode.

2.12.2 HAL initialization

2.12.2.1 HAL global initialization

In addition to the peripheral initialization and de-initialization functions, a set of APIs are provided to initialize the HAL core implemented in file stm32l1xx_hal.c.

HAL_Init(): this function must be called at application startup to

Initialize data/instruction cache and pre-fetch queue

Set Systick timer to generate an interrupt each 1ms (based on HSI clock) with the lowest priority

Call HAL_MspInit() user callback function to perform system level initializations

(Clock, GPIOs, DMA, interrupts). HAL_MspInit() is defined as “weak” empty function in the HAL drivers.

HAL_DeInit()

Resets all peripherals

66/654 DOCID026682 Rev 3

UM1816

Overview of HAL drivers

Calls function HAL_MspDeInit() which a is user callback function to do system level De-Initalizations.

HAL_GetTick(): this function gets current SysTick counter value (incremented in

SysTick interrupt) used by peripherals drivers to handle timeouts.

HAL_Delay(). this function implements a delay (expressed in milliseconds) using the

SysTick timer.

Care must be taken when using HAL_Delay() since this function provides an accurate delay (expressed in milliseconds) based on a variable incremented in SysTick ISR.

This means that if HAL_Delay() is called from a peripheral ISR, then the SysTick interrupt must have highest priority (numerically lower) than the peripheral interrupt, otherwise the caller ISR will be blocked.

2.12.2.2 System clock initialization

The clock configuration is done at the beginning of the user code. However the user can change the configuration of the clock in his own code. Please find below the typical Clock configuration sequence: static void SystemClock_Config(void)

{

RCC_ClkInitTypeDef RCC_ClkInitStruct;

RCC_OscInitTypeDef RCC_OscInitStruct;

/* Enable MSI with range 5, PLL is OFF */

RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_MSI;

RCC_OscInitStruct.MSIState = RCC_MSIRANGE_5;

RCC_OscInitStruct.MSICalibrationValue=0x00;

RCC_OscInitStruct.PLL.PLLState = RCC_PLL_NONE;

HAL_RCC_OscConfig(&RCC_OscInitStruct);

/* Select MSI as system clock source and configure the HCLK, PCLK1 and PCLK2 clocks dividers */

RCC_ClkInitStruct.ClockType = (RCC_CLOCKTYPE_SYSCLK | RCC_CLOCKTYPE_HCLK |

RCC_CLOCKTYPE_PCLK1 | RCC_CLOCKTYPE_PCLK2);

RCC_ClkInitStruct.SYSCLKSource = RCC_SYSCLKSOURCE_MSI;

RCC_ClkInitStruct.AHBCLKDivider = RCC_SYSCLK_DIV1;

RCC_ClkInitStruct.APB1CLKDivider = RCC_HCLK_DIV1;

RCC_ClkInitStruct.APB2CLKDivider = RCC_HCLK_DIV1;

HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_0);

}

2.12.2.3 HAL MSP initialization process

The peripheral initialization is done through HAL_PPP_Init() while the hardware resources initialization used by a peripheral (PPP) is performed during this initialization by calling

MSP callback function HAL_PPP_MspInit().

The MspInit callback performs the low level initialization related to the different additional hardware resources: RCC, GPIO, NVIC and DMA.

All the HAL drivers with handles include two MSP callbacks for initialization and deinitialization:

/**

* @brief Initializes the PPP MSP.

* @param hppp: PPP handle

* @retval None */ void __weak HAL_PPP_MspInit(PPP_HandleTypeDef *hppp) {

/* NOTE : This function Should not be modified, when the callback is needed, the HAL_PPP_MspInit could be implemented in the user file */

}

/**

* @brief DeInitializes PPP MSP.

* @param hppp: PPP handle

* @retval None */ void __weak HAL_PPP_MspDeInit(PPP_HandleTypeDef *hppp) {

/* NOTE : This function Should not be modified, when the callback is needed,

DOCID026682 Rev 3 67/654

Overview of HAL drivers the HAL_PPP_MspDeInit could be implemented in the user file */

}

UM1816

The MSP callbacks are declared empty as weak functions in each peripheral driver. The user can use them to set the low level initialization code or omit them and use his own initialization routine.

The HAL MSP callback is implemented inside the stm32l1xx_hal_msp.c file in the user folders. An stm32l1xx_hal_msp.c file template is located in the HAL folder and should be copied to the user folder. It can be generated automatically by STM32CubeMX tool and further modified. Note that all the routines are declared as weak functions and could be overwritten or removed to use user low level initialization code.

stm32l1xx_hal_msp.c file contains the following functions:

Table 14: MSP functions

Routine Description

void HAL_MspInit()

void HAL_MspDeInit()

void HAL_PPP_MspInit()

Global MSP initialization routine

Global MSP de-initialization routine

PPP MSP initialization routine

void HAL_PPP_MspDeInit()

PPP MSP de-initialization routine

By default, if no peripheral needs to be de-initialized during the program execution, the whole MSP initialization is done in Hal_MspInit() and MSP De-Initialization in the

Hal_MspDeInit(). In this case the HAL_PPP_MspInit() and HAL_PPP_MspDeInit() are not implemented.

When one or more peripherals needs to be de-initialized in run time and the low level resources of a given peripheral need to be released and used by another peripheral,

HAL_PPP_MspDeInit() and HAL_PPP_MspInit() are implemented for the concerned peripheral and other peripherals initialization and de-Initialization are kept in the global

HAL_MspInit() and the HAL_MspDeInit().

If there is nothing to be initialized by the global HAL_MspInit() and HAL_MspDeInit(), the two routines can simply be omitted.

2.12.3 HAL IO operation process

The HAL functions with internal data processing like Transmit, Receive, Write and Read are generally provided with three data processing modes as follows:

Polling mode

Interrupt mode

DMA mode

2.12.3.1 Polling mode

In polling mode, the HAL functions return the process status when the data processing in blocking mode is complete. The operation is considered complete when the function returns the HAL_OK status, otherwise an error status is returned. The user can get more information through the HAL_PPP_GetState() function. The data processing is handled internally in a loop. A timeout (expressed in ms) is used to prevent process hanging.

The example below shows the typical polling mode processing sequence :

HAL_StatusTypeDef HAL_PPP_Transmit ( PPP_HandleTypeDef * phandle, uint8_t pData, int16_tSize,uint32_tTimeout)

{

68/654 DOCID026682 Rev 3

UM1816

Overview of HAL drivers if((pData == NULL ) || (Size == 0))

{ return HAL_ERROR;

}

(…) while (data processing is running)

{ if( timeout reached )

{ return HAL_TIMEOUT;

}

}

(…) return HELIAC; }

2.12.3.2 Interrupt mode

In Interrupt mode, the HAL function returns the process status after starting the data processing and enabling the appropriate interruption. The end of the operation is indicated by a callback declared as a weak function. It can be customized by the user to be informed in real-time about the process completion. The user can also get the process status through the HAL_PPP_GetState() function.

In interrupt mode, four functions are declared in the driver:

HAL_PPP_Process_IT(): launch the process

HAL_PPP_IRQHandler(): the global PPP peripheral interruption

__weak HAL_PPP_ProcessCpltCallback (): the callback relative to the process completion.

__weak HAL_PPP_ProcessErrorCallback(): the callback relative to the process Error.

To use a process in interrupt mode, HAL_PPP_Process_IT() is called in the user file and

HAL_PPP_IRQHandler in stm32l1xx_it.c.

The HAL_PPP_ProcessCpltCallback() function is declared as weak function in the driver.

This means that the user can declare it again in the application. The function in the driver is not modified.

An example of use is illustrated below:

main.c file:

UART_HandleTypeDef UartHandle; int main(void)

{

/* Set User Parameters */

UartHandle.Init.BaudRate = 9600;

UartHandle.Init.WordLength = UART_DATABITS_8;

UartHandle.Init.StopBits = UART_STOPBITS_1;

UartHandle.Init.Parity = UART_PARITY_NONE;

UartHandle.Init.HwFlowCtl = UART_HWCONTROL_NONE;

UartHandle.Init.Mode = UART_MODE_TX_RX;

UartHandle.Init.Instance = USART1;

HAL_UART_Init(&UartHandle);

HAL_UART_SendIT(&UartHandle, TxBuffer, sizeof(TxBuffer)); while (1);

} void HAL_UART_TxCpltCallback(UART_HandleTypeDef *huart)

{

} void HAL_UART_ErrorCallback(UART_HandleTypeDef *huart)

{

}

stm32l1xx_it.cfile: extern UART_HandleTypeDef UartHandle;

DOCID026682 Rev 3 69/654

Overview of HAL drivers void USART1_IRQHandler(void)

{

HAL_UART_IRQHandler(&UartHandle);

}

UM1816

2.12.3.3 DMA mode

In DMA mode, the HAL function returns the process status after starting the data processing through the DMA and after enabling the appropriate DMA interruption. The end of the operation is indicated by a callback declared as a weak function and can be customized by the user to be informed in real-time about the process completion. The user can also get the process status through the HAL_PPP_GetState() function. For the DMA mode, three functions are declared in the driver:

HAL_PPP_Process_DMA(): launch the process

HAL_PPP_DMA_IRQHandler(): the DMA interruption used by the PPP peripheral

__weak HAL_PPP_ProcessCpltCallback(): the callback relative to the process completion.

__weak HAL_PPP_ErrorCpltCallback(): the callback relative to the process Error.

To use a process in DMA mode, HAL_PPP_Process_DMA() is called in the user file and the HAL_PPP_DMA_IRQHandler() is placed in the stm32l1xx_it.c. When DMA mode is used, the DMA initialization is done in the HAL_PPP_MspInit() callback. The user should also associate the DMA handle to the PPP handle. For this purpose, the handles of all the peripheral drivers that use the DMA must be declared as follows: typedef struct

{

PPP_TypeDef *Instance; /* Register base address */

PPP_InitTypeDef Init; /* PPP communication parameters */

HAL_StateTypeDef State; /* PPP communication state */

(…)

DMA_HandleTypeDef *hdma; /* associated DMA handle */

} PPP_HandleTypeDef;

The initialization is done as follows (UART example): int main(void)

{

/* Set User Parameters */

UartHandle.Init.BaudRate = 9600;

UartHandle.Init.WordLength = UART_DATABITS_8;

UartHandle.Init.StopBits = UART_STOPBITS_1;

UartHandle.Init.Parity = UART_PARITY_NONE;

UartHandle.Init.HwFlowCtl = UART_HWCONTROL_NONE;

UartHandle.Init.Mode = UART_MODE_TX_RX;

UartHandle.Init.Instance = UART1;

HAL_UART_Init(&UartHandle);

(..)

} void HAL_USART_MspInit (UART_HandleTypeDef * huart)

{ static DMA_HandleTypeDef hdma_tx; static DMA_HandleTypeDef hdma_rx;

(…)

__HAL_LINKDMA(UartHandle, DMA_Handle_tx, hdma_tx);

__HAL_LINKDMA(UartHandle, DMA_Handle_rx, hdma_rx);

(…)

}

The HAL_PPP_ProcessCpltCallback() function is declared as weak function in the driver that means, the user can declare it again in the application code. The function in the driver should not be modified.

An example of use is illustrated below:

main.c file:

70/654 DOCID026682 Rev 3

UM1816

Overview of HAL drivers

UART_HandleTypeDef UartHandle; int main(void)

{

/* Set User Paramaters */

UartHandle.Init.BaudRate = 9600;

UartHandle.Init.WordLength = UART_DATABITS_8;

UartHandle.Init.StopBits = UART_STOPBITS_1;

UartHandle.Init.Parity = UART_PARITY_NONE;

UartHandle.Init.HwFlowCtl = UART_HWCONTROL_NONE;

UartHandle.Init.Mode = UART_MODE_TX_RX; UartHandle.Init.Instance = USART1;

HAL_UART_Init(&UartHandle);

HAL_UART_Send_DMA(&UartHandle, TxBuffer, sizeof(TxBuffer)); while (1);

} void HAL_UART_TxCpltCallback(UART_HandleTypeDef *phuart)

{

} void HAL_UART_TxErrorCallback(UART_HandleTypeDef *phuart)

{

}

stm32l1xx_it.c file: extern UART_HandleTypeDef UartHandle; void DMAx_IRQHandler(void)

{

HAL_DMA_IRQHandler(&UartHandle.DMA_Handle_tx);

}

HAL_USART_TxCpltCallback() and HAL_USART_ErrorCallback() should be linked in the

HAL_PPP_Process_DMA() function to the DMA transfer complete callback and the DMA transfer Error callback by using the following statement:

HAL_PPP_Process_DMA (PPP_HandleTypeDef *hppp, Params….)

{

(…) hppp->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

No poll : Immediate process check and exit 0

1 ... (HAL_MAX_DELAY -1)

(1)

HAL_MAX_DELAY

Timeout in ms

Infinite poll till process is successful

Notes:

(1)

HAL_MAX_DELAY is defined in the stm32l1xx_hal_def.h as 0xFFFFFFFF

DOCID026682 Rev 3 71/654

Overview of HAL drivers

UM1816

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;

}

}

72/654 DOCID026682 Rev 3

UM1816

Overview of HAL drivers

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 */

DOCID026682 Rev 3 73/654

Overview of HAL drivers

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 */

}

UM1816

2.12.4.3 Run-time checking

The HAL implements run-time failure detection by checking the input values of all HAL drivers 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 stm32l1xx_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 stm32l1xx_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 */

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)

{

74/654 DOCID026682 Rev 3

UM1816

Overview of HAL drivers

/* 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.

DOCID026682 Rev 3 75/654

HAL System Driver

3

3.1

3.2

3.2.1

3.2.2

3.2.3

76/654

UM1816

HAL System Driver

HAL System Driver

HAL Firmware driver API description

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

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 source of time base 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()

HAL Control functions

This section provides functions allowing to:

Provide a tick value in millisecond

Provide a blocking delay in millisecond

DOCID026682 Rev 3

UM1816

3.2.4

HAL System Driver

Suspend the time base source interrupt

Resume the time base source interrupt

Get the HAL API driver version

Get the device identifier

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_Init

Function Name HAL_StatusTypeDef HAL_Init (void )

Function Description This function configures the Flash prefetch, Configures time base source, NVIC and Low level hardware.

Return values

HAL status

Notes

This function is called at the beginning of program after reset and before the clock configuration

The time base configuration is based on MSI clock when exiting from Reset. Once done, time base tick start incrementing. In the default implementation,Systick is used as source of time base. the tick variable is incremented each

1ms in its ISR.

3.2.5

3.2.6

HAL_DeInit

Function Name

HAL_StatusTypeDef HAL_DeInit (void )

Function Description This function de-Initializes common part of the HAL and stops the source of time base.

Return values

Notes

HAL status

This function is optional.

HAL_MspInit

Function Name void HAL_MspInit (void )

DOCID026682 Rev 3 77/654

HAL System Driver

Function Description Initializes the MSP.

Return values

None

3.2.7 HAL_MspDeInit

Function Name

void HAL_MspDeInit (void )

Function Description DeInitializes the MSP.

Return values

None

3.2.8

3.2.9

UM1816

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

Notes

HAL status

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.

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

3.2.11 HAL_Delay

78/654 DOCID026682 Rev 3

UM1816

HAL System Driver

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

Notes

None

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.

ThiS function is declared as __weak to be overwritten in case of other implementations in user file.

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

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

3.2.14 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)

3.2.15 HAL_GetREVID

Function Name uint32_t HAL_GetREVID (void )

Function Description Returns the device revision identifier.

Return values

Device revision identifier

DOCID026682 Rev 3 79/654

HAL System Driver

3.2.16 HAL_GetDEVID

Function Name uint32_t HAL_GetDEVID (void )

Function Description Returns the device identifier.

Return values

Device identifier

3.2.17 HAL_DBGMCU_EnableDBGSleepMode

Function Name

void HAL_DBGMCU_EnableDBGSleepMode (void )

Function Description Enable the Debug Module during SLEEP mode.

Return values

None

UM1816

3.2.18 HAL_DBGMCU_DisableDBGSleepMode

Function Name void HAL_DBGMCU_DisableDBGSleepMode (void )

Function Description Disable the Debug Module during SLEEP mode.

Return values

None

3.2.19 HAL_DBGMCU_EnableDBGStopMode

Function Name

void HAL_DBGMCU_EnableDBGStopMode (void )

Function Description Enable the Debug Module during STOP mode.

Return values

None

3.2.20 HAL_DBGMCU_DisableDBGStopMode

Function Name void HAL_DBGMCU_DisableDBGStopMode (void )

Function Description Disable the Debug Module during STOP mode.

Return values

None

3.2.21 HAL_DBGMCU_EnableDBGStandbyMode

Function Name void HAL_DBGMCU_EnableDBGStandbyMode (void )

Function Description Enable the Debug Module during STANDBY mode.

Return values

None

3.2.22 HAL_DBGMCU_DisableDBGStandbyMode

Function Name void HAL_DBGMCU_DisableDBGStandbyMode (void )

Function Description Disable the Debug Module during STANDBY mode.

Return values

None

3.3

3.3.1

80/654

HAL Firmware driver defines

HAL

HAL Private Defines

DOCID026682 Rev 3

UM1816

__STM32L1xx_HAL_VERSION_MAIN [31:24] main version

__STM32L1xx_HAL_VERSION_SUB1 [23:16] sub1 version

__STM32L1xx_HAL_VERSION_SUB2 [15:8] sub2 version

__STM32L1xx_HAL_VERSION_RC

__STM32L1xx_HAL_VERSION

[7:0] release candidate

IDCODE_DEVID_MASK

HAL System Driver

DOCID026682 Rev 3 81/654

HAL ADC Generic Driver

UM1816

4

4.1

4.2

4.2.1

82/654

HAL ADC Generic Driver

HAL ADC Generic Driver

ADC Firmware driver registers structures

ADC_InitTypeDef

Data Fields

uint32_t ClockPrescaler

uint32_t Resolution

uint32_t DataAlign

uint32_t ScanConvMode

uint32_t EOCSelection

uint32_t LowPowerAutoWait

uint32_t LowPowerAutoPowerOff

uint32_t ChannelsBank

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 source (asynchronous clock derived from HSI RC oscillator) and

clock prescaler. This parameter can be a value of

ADC_ClockPrescaler

Note: In case

of usage of channels on injected group, ADC frequency should be lower than AHB clock frequency /4 for resolution 12 or 10 bits, AHB clock frequency /3 for resolution 8 bits, AHB clock frequency /2 for resolution 6 bits. Note: HSI RC oscillator must be preliminarily enabled at RCC top level.

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

DOCID026682 Rev 3

UM1816

HAL ADC Generic Driver

'NbrOfConversion'/'InjectedNbrOfConversion' and each channel rank). Scan direction

is upward: from rank1 to rank 'n'. This parameter can be a value of

ADC_Scan_mode

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

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::LowPowerAutoWait

Selects the dynamic low power Auto Delay: new conversion start only when the previous conversion (for regular group) or previous sequence (for injected group) has been treated by user software, using function HAL_ADC_GetValue() or

HAL_ADCEx_InjectedGetValue(). This feature automatically adapts the speed of

ADC to the speed of the system that reads the data. Moreover, this avoids risk of overrun for low frequency applications. This parameter can be a value of

ADC_LowPowerAutoWait

. Note: Do not use with interruption or DMA

(HAL_ADC_Start_IT(), HAL_ADC_Start_DMA()) since they have to clear immediately the EOC flag to free the IRQ vector sequencer. Do use with polling: 1.

Start conversion with HAL_ADC_Start(), 2. Later on, when conversion data is needed: use HAL_ADC_PollForConversion() to ensure that conversion is completed and use HAL_ADC_GetValue() to retrieve conversion result and trig another conversion (in case of usage of injected group, use the equivalent functions

HAL_ADCExInjected_Start(), HAL_ADCEx_InjectedGetValue(), ...). Note: ADC clock latency and some timing constraints depending on clock prescaler have to be taken into account: refer to reference manual (register ADC_CR2 bit DELS description).

uint32_t ADC_InitTypeDef::LowPowerAutoPowerOff

Selects the auto-off mode: the ADC automatically powers-off after a conversion and automatically wakes-up when a new conversion is triggered (with startup time between trigger and start of sampling). This feature can be combined with automatic wait mode (parameter 'LowPowerAutoWait'). This parameter can be a value of

ADC_LowPowerAutoPowerOff

.

uint32_t ADC_InitTypeDef::ChannelsBank

Selects the ADC channels bank. This parameter can be a value of

ADC_ChannelsBank

. Note: Banks availability depends on devices categories. Note:

To change bank selection on the fly, without going through execution of

'HAL_ADC_Init()', macro '__HAL_ADC_CHANNELS_BANK()' can be used directly.

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 = 28.

uint32_t ADC_InitTypeDef::DiscontinuousConvMode

Specifies whether the conversions sequence of regular group is performed in

DOCID026682 Rev 3 83/654

HAL ADC Generic Driver

Complete-sequence/Discontinuous-sequence (main sequence subdivided in

UM1816

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. 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. This parameter can be set to ENABLE or DISABLE.

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

4.2.2 ADC_ChannelConfTypeDef

Data Fields

uint32_t Channel

uint32_t Rank

uint32_t SamplingTime

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

Note: Depending on devices, some channels may not be

available on package pins. Refer to device datasheet for channels availability.

Maximum number of channels by device category (without taking in account each device package constraints): STM32L1 category 1, 2: 24 channels on external pins +

3 channels on internal measurement paths (VrefInt, Temp sensor, Vcomp): Channel 0 to channel 26. STM32L1 category 3: 25 channels on external pins + 3 channels on internal measurement paths (VrefInt, Temp sensor, Vcomp): Channel 0 to channel 26,

1 additional channel in bank B. Note: OPAMP1 and OPAMP2 are connected internally but not increasing internal channels number: they are sharing ADC input with external channels ADC_IN3 and ADC_IN8. STM32L1 category 4, 5: 40 channels on external

84/654 DOCID026682 Rev 3

UM1816

4.2.3

HAL ADC Generic Driver pins + 3 channels on internal measurement paths (VrefInt, Temp sensor, Vcomp):

Channel 0 to channel 31, 11 additional channels in bank B. Note: OPAMP1 and

OPAMP2 are connected internally but not increasing internal channels number: they are sharing ADC input with external channels ADC_IN3 and ADC_IN8. Note: In case of peripherals OPAMPx not used: 3 channels (3, 8, 13) can be configured as direct channels (fast channels). Refer to macro ' __HAL_ADC_CHANNEL_SPEED_FAST()

'. Note: In case of peripheral OPAMP3 and ADC channel OPAMP3 used (OPAMP3 available on STM32L1 devices Cat.4 only): the analog switch COMP1_SW1 must be closed. Refer to macro: '

__HAL_OPAMP_OPAMP3OUT_CONNECT_ADC_COMP1() '.

uint32_t ADC_ChannelConfTypeDef::Rank

Specifies the rank in the regular group sequencer This parameter can be a value of

ADC_regular_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_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).

ADC_AnalogWDGConfTypeDef

Data Fields

uint32_t WatchdogMode

uint32_t Channel

uint32_t ITMode

uint32_t HighThreshold

uint32_t LowThreshold

uint32_t WatchdogNumber

Field Documentation

uint32_t ADC_AnalogWDGConfTypeDef::WatchdogMode

Configures the ADC analog watchdog mode: single/all channels, regular/injected

group. This parameter can be a value of

ADC_analog_watchdog_mode

.

uint32_t ADC_AnalogWDGConfTypeDef::Channel

Selects which ADC channel to monitor by analog watchdog. This parameter has an effect only if watchdog mode is configured on single channel (parameter

WatchdogMode) This parameter can be a value of

ADC_channels

.

uint32_t ADC_AnalogWDGConfTypeDef::ITMode

Specifies whether the analog watchdog is configured in interrupt or polling mode. This parameter can be set to ENABLE or DISABLE

DOCID026682 Rev 3 85/654

HAL ADC Generic Driver

uint32_t ADC_AnalogWDGConfTypeDef::HighThreshold

UM1816

Configures the ADC analog watchdog High threshold value. This parameter must be a number between Min_Data = 0x000 and Max_Data = 0xFFF.

uint32_t ADC_AnalogWDGConfTypeDef::LowThreshold

Configures the ADC analog watchdog High threshold value. This parameter must be a number between Min_Data = 0x000 and Max_Data = 0xFFF.

uint32_t ADC_AnalogWDGConfTypeDef::WatchdogNumber

Reserved for future use, can be set to 0

4.2.4 ADC_HandleTypeDef

Data Fields

ADC_TypeDef * Instance

ADC_InitTypeDef Init

__IO uint32_t NbrOfConversionRank

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::NbrOfConversionRank

ADC conversion rank counter

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 (bitmap of ADC states)

__IO uint32_t ADC_HandleTypeDef::ErrorCode

ADC Error code

4.3

4.3.1

ADC Firmware driver API description

ADC peripheral features

12-bit, 10-bit, 8-bit or 6-bit configurable resolution

Interrupt generation at the end of regular conversion, end of injected conversion, and in case of analog watchdog or overrun events.

Single and continuous conversion modes.

Scan mode for conversion of several channels sequentially.

Data alignment with in-built data coherency.

86/654 DOCID026682 Rev 3

UM1816

4.3.2

HAL ADC Generic Driver

Programmable sampling time (channel wise)

ADC conversion of regular group and injected group.

External trigger (timer or EXTI) with configurable polarity for both regular and injected groups.

DMA request generation for transfer of conversions data of regular group.

ADC calibration

ADC offset on injected channels

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: from Vref- (connected to Vssa) to Vref+ (connected to Vdda or to an external voltage reference).

How to use this driver

Configuration of top level parameters related to ADC

1. Enable the ADC interface

As prerequisite, ADC clock must be configured at RCC top level. Caution: On

STM32L1, ADC clock frequency max is 16MHz (refer to device datasheet).

Therefore, ADC clock prescaler must be configured in function of ADC clock source frequency to remain below this maximum frequency.

Two clock settings are mandatory:

ADC clock (core clock).

ADC clock (conversions clock). Only one possible clock source: derived from HSI RC 16MHz oscillator (HSI). ADC is connected directly to HSI RC

16MHz oscillator. Therefore, RCC PLL setting has no impact on ADC. PLL can be disabled (".PLL.PLLState = RCC_PLL_NONE") or enabled with

HSI16 as clock source (".PLL.PLLSource = RCC_PLLSOURCE_HSI") to be used as device main clock source SYSCLK. The only mandatory setting is

".HSIState = RCC_HSI_ON"

Example: Into HAL_ADC_MspInit() (recommended code location) or with other device clock parameters configuration:

__HAL_RCC_ADC1_CLK_ENABLE();

HAL_RCC_GetOscConfig(&RCC_OscInitStructure);

RCC_OscInitStructure.OscillatorType = (... |

RCC_OSCILLATORTYPE_HSI);

RCC_OscInitStructure.HSIState = RCC_HSI_ON;

RCC_OscInitStructure.HSICalibrationValue =

RCC_HSICALIBRATION_DEFAULT;

RCC_OscInitStructure.PLL.PLLState = RCC_PLL_NONE;

RCC_OscInitStructure.PLL.PLLSource = ...

RCC_OscInitStructure.PLL...

HAL_RCC_OscConfig(&RCC_OscInitStructure);

ADC clock prescaler is configured at ADC level with parameter "ClockPrescaler" using function HAL_ADC_Init().

2. ADC pins configuration

Enable the clock for the ADC GPIOs using macro

__HAL_RCC_GPIOx_CLK_ENABLE()

Configure these ADC pins in analog mode using function HAL_GPIO_Init()

3. Optionally, in case of usage of ADC with interruptions:

Configure the NVIC for ADC using function HAL_NVIC_EnableIRQ(ADCx_IRQn)

DOCID026682 Rev 3 87/654

HAL ADC Generic Driver

UM1816

Insert the ADC interruption handler function HAL_ADC_IRQHandler() into the function of corresponding ADC interruption vector ADCx_IRQHandler().

4. Optionally, in case of usage of DMA:

Configure the DMA (DMA channel, mode normal or circular, ...) using function

HAL_DMA_Init().

Configure the NVIC for DMA using function

HAL_NVIC_EnableIRQ(DMAx_Channelx_IRQn)

Insert the ADC interruption handler function HAL_ADC_IRQHandler() into the function of corresponding DMA interruption vector

DMAx_Channelx_IRQHandler().

Configuration of ADC, groups regular/injected, channels parameters

1. Configure the ADC parameters (resolution, data alignment, ...) and regular group parameters (conversion trigger, sequencer, ...) using function HAL_ADC_Init().

2. Configure the channels for regular group parameters (channel number, channel rank into sequencer, ..., into regular group) using function HAL_ADC_ConfigChannel().

3. 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().

4. Optionally, configure the analog watchdog parameters (channels monitored, thresholds, ...) using function HAL_ADC_AnalogWDGConfig().

5. Optionally, for devices with several ADC instances: configure the multimode parameters using function HAL_ADCEx_MultiModeConfigChannel().

Execution of ADC conversions

1. Optionally, perform an automatic ADC calibration to improve the conversion accuracy using function HAL_ADCEx_Calibration_Start().

2. ADC driver can be used among three modes: polling, interruption, transfer by DMA.

ADC conversion by polling:

Activate the ADC peripheral and start conversions using function

HAL_ADC_Start()

Wait for ADC conversion completion using function

HAL_ADC_PollForConversion() (or for injected group:

HAL_ADCEx_InjectedPollForConversion() )

Retrieve conversion results using function HAL_ADC_GetValue() (or for injected group: HAL_ADCEx_InjectedGetValue() )

Stop conversion and disable the ADC peripheral using function

HAL_ADC_Stop()

ADC conversion by interruption:

Activate the ADC peripheral and start conversions using function

HAL_ADC_Start_IT()

Wait for ADC conversion completion by call of function

HAL_ADC_ConvCpltCallback() (this function must be implemented in user program) (or for injected group: HAL_ADCEx_InjectedConvCpltCallback() )

Retrieve conversion results using function HAL_ADC_GetValue() (or for injected group: HAL_ADCEx_InjectedGetValue() )

Stop conversion and disable the ADC peripheral using function

HAL_ADC_Stop_IT()

ADC conversion with transfer by DMA:

88/654 DOCID026682 Rev 3

UM1816

HAL ADC Generic Driver

Activate the ADC peripheral and start conversions using function

HAL_ADC_Start_DMA()

Wait for ADC conversion completion by call of function

HAL_ADC_ConvCpltCallback() or HAL_ADC_ConvHalfCpltCallback() (these functions must be implemented in user program)

Conversion results are automatically transferred by DMA into destination variable address.

Stop conversion and disable the ADC peripheral using function

HAL_ADC_Stop_DMA()

For devices with several ADCs: ADC multimode conversion with transfer by

DMA:

Activate the ADC peripheral (slave) and start conversions using function

HAL_ADC_Start()

Activate the ADC peripheral (master) and start conversions using function

HAL_ADCEx_MultiModeStart_DMA()

Wait for ADC conversion completion by call of function

HAL_ADC_ConvCpltCallback() or HAL_ADC_ConvHalfCpltCallback() (these functions must be implemented in user program)

Conversion results are automatically transferred by DMA into destination variable address.

Stop conversion and disable the ADC peripheral (master) using function

HAL_ADCEx_MultiModeStop_DMA()

Stop conversion and disable the ADC peripheral (slave) using function

HAL_ADC_Stop_IT()

Callback functions must be implemented in user program:

HAL_ADC_ErrorCallback()

HAL_ADC_LevelOutOfWindowCallback() (callback of analog watchdog)

HAL_ADC_ConvCpltCallback()

HAL_ADC_ConvHalfCpltCallback

HAL_ADCEx_InjectedConvCpltCallback()

Deinitialization of ADC

1. Disable the ADC interface

ADC clock can be hard reset and disabled at RCC top level.

Hard reset of ADC peripherals using macro __ADCx_FORCE_RESET(),

__ADCx_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);

2. ADC pins configuration

Disable the clock for the ADC GPIOs using macro

__HAL_RCC_GPIOx_CLK_DISABLE()

3. Optionally, in case of usage of ADC with interruptions:

Disable the NVIC for ADC using function HAL_NVIC_EnableIRQ(ADCx_IRQn)

DOCID026682 Rev 3 89/654

HAL ADC Generic Driver

4. Optionally, in case of usage of DMA:

Deinitialize the DMA using function HAL_DMA_Init().

Disable the NVIC for DMA using function

HAL_NVIC_EnableIRQ(DMAx_Channelx_IRQn)

4.3.3 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.3.4

4.3.5

IO operation functions

This section provides functions allowing to:

Start conversion of regular group.

Stop conversion of regular group.

Poll for conversion complete on regular group.

Poll for conversion event.

Get result of regular channel conversion.

Start conversion of regular group and enable interruptions.

Stop conversion of regular group and disable interruptions.

Handle ADC interrupt request

Start conversion of regular group and enable DMA transfer.

Stop conversion of regular group and disable ADC DMA transfer.

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_Start_DMA()

HAL_ADC_Stop_DMA()

HAL_ADC_GetValue()

HAL_ADC_IRQHandler()

HAL_ADC_ConvCpltCallback()

HAL_ADC_ConvHalfCpltCallback()

HAL_ADC_LevelOutOfWindowCallback()

HAL_ADC_ErrorCallback()

Peripheral Control functions

This section provides functions allowing to:

Configure channels on regular group

Configure the analog watchdog

90/654 DOCID026682 Rev 3

UM1816

UM1816

4.3.6

4.3.7

HAL ADC Generic Driver

This section contains the following APIs:

HAL_ADC_ConfigChannel()

HAL_ADC_AnalogWDGConfig()

Peripheral State and Errors functions

This subsection provides functions to get in run-time the status of the peripheral.

Check the ADC state

Check the ADC error code

This section contains the following APIs:

HAL_ADC_GetState()

HAL_ADC_GetError()

HAL_ADC_Init

Function Name

HAL_StatusTypeDef HAL_ADC_Init (ADC_HandleTypeDef *

hadc)

Function Description Initializes the ADC peripheral and regular group according to parameters specified in structure "ADC_InitTypeDef".

Parameters

Return values

hadc: ADC handle

HAL status

Notes

As prerequisite, ADC clock must be configured at RCC top level (clock source APB2). See commented example code below that can be copied and uncommented into

HAL_ADC_MspInit().

Possibility to update parameters on the fly: This function initializes the ADC MSP (HAL_ADC_MspInit()) only when coming from ADC state reset. Following calls to this function can be used to reconfigure some parameters of

ADC_InitTypeDef structure on the fly, without modifying MSP configuration. If ADC MSP has to be modified again,

HAL_ADC_DeInit() must be called before HAL_ADC_Init().

The setting of these parameters is conditioned to ADC state.

For parameters constraints, see comments of structure

"ADC_InitTypeDef".

This function configures the ADC within 2 scopes: scope of entire ADC and scope of regular group. For parameters details, see comments of structure "ADC_InitTypeDef".

4.3.8 HAL_ADC_DeInit

Function Name

HAL_StatusTypeDef HAL_ADC_DeInit (ADC_HandleTypeDef *

hadc)

Function Description Deinitialize the ADC peripheral registers to its default reset values.

Parameters

hadc: ADC handle

Return values

Notes

HAL status

To not impact other ADCs, reset of common ADC registers have been left commented below. If needed, the example code can be copied and uncommented into function

DOCID026682 Rev 3 91/654

HAL ADC Generic Driver

4.3.9

HAL_ADC_MspDeInit().

HAL_ADC_MspInit

Function Name void HAL_ADC_MspInit (ADC_HandleTypeDef * hadc)

Function Description Initializes the ADC MSP.

Parameters

hadc: ADC handle

Return values

None

UM1816

4.3.10 HAL_ADC_MspDeInit

Function Name void HAL_ADC_MspDeInit (ADC_HandleTypeDef * hadc)

Function Description DeInitializes the ADC MSP.

Parameters

hadc: ADC handle

Return values

None

4.3.11 HAL_ADC_Start

Function Name

HAL_StatusTypeDef HAL_ADC_Start (ADC_HandleTypeDef *

hadc)

Function Description Enables ADC, starts conversion of regular group.

Parameters

hadc: ADC handle

Return values

HAL status

4.3.12 HAL_ADC_Stop

Function Name

HAL_StatusTypeDef HAL_ADC_Stop (ADC_HandleTypeDef *

hadc)

Function Description Stop ADC conversion of regular group (and injected channels in case of auto_injection mode), disable ADC peripheral.

Parameters

hadc: ADC handle

Return values

Notes

HAL status.

: ADC peripheral disable is forcing stop of potential conversion on injected group. If injected group is under use, it should be preliminarily stopped using

HAL_ADCEx_InjectedStop function.

4.3.13 HAL_ADC_PollForConversion

Function Name

HAL_StatusTypeDef HAL_ADC_PollForConversion

(ADC_HandleTypeDef * hadc, uint32_t Timeout)

Function Description Wait for regular group conversion to be completed.

Parameters

hadc: ADC handle

Timeout: Timeout value in millisecond.

Return values

HAL status

92/654 DOCID026682 Rev 3

UM1816

Notes

HAL ADC Generic Driver

ADC conversion flags EOS (end of sequence) and EOC (end of conversion) are cleared by this function, with an exception: if low power feature "LowPowerAutoWait" is enabled, flags are not cleared to not interfere with this feature until data register is read using function HAL_ADC_GetValue().

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 (ADC init parameter "EOCSelection" set to ADC_EOC_SEQ_CONV).

4.3.14 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

Return values

hadc: ADC handle

EventType: the ADC event type. This parameter can be one of the following values: ADC_AWD_EVENT: ADC Analog watchdog event.ADC_OVR_EVENT: ADC Overrun event

Timeout: Timeout value in millisecond.

HAL status

4.3.15 HAL_ADC_Start_IT

Function Name

HAL_StatusTypeDef HAL_ADC_Start_IT (ADC_HandleTypeDef

* hadc)

Function Description Enables ADC, starts conversion of regular group with interruption.

4.3.16 HAL_ADC_Stop_IT

Function Name

HAL_StatusTypeDef HAL_ADC_Stop_IT (ADC_HandleTypeDef

* hadc)

Function Description Stop ADC conversion of regular group (and injected group in case of auto_injection mode), disable interrution of end-of-conversion, disable ADC peripheral.

Parameters

hadc: ADC handle

Return values

None

4.3.17 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, starts conversion of regular group and transfers result through DMA.

DOCID026682 Rev 3 93/654

HAL ADC Generic Driver

4.3.18 HAL_ADC_Stop_DMA

Function Name

HAL_StatusTypeDef HAL_ADC_Stop_DMA

(ADC_HandleTypeDef * hadc)

UM1816

Function Description Stop ADC conversion of regular group (and injected group in case of auto_injection mode), disable ADC DMA transfer, disable ADC peripheral.

Parameters

Notes

Return values

hadc: ADC handle

HAL status.

: ADC peripheral disable is forcing stop of potential conversion on injected group. If injected group is under use, it should be preliminarily stopped using

HAL_ADCEx_InjectedStop function.

4.3.19 HAL_ADC_GetValue

Function Name

uint32_t HAL_ADC_GetValue (ADC_HandleTypeDef * hadc)

Function Description Get ADC regular group conversion result.

Parameters

hadc: ADC handle

Return values

Converted value

Notes

Reading DR register automatically clears EOC (end of conversion of regular group) flag.

4.3.20 HAL_ADC_IRQHandler

Function Name void HAL_ADC_IRQHandler (ADC_HandleTypeDef * hadc)

Function Description Handles ADC interrupt request.

Parameters

hadc: ADC handle

Return values

None

4.3.21 HAL_ADC_ConvCpltCallback

Function Name

void HAL_ADC_ConvCpltCallback (ADC_HandleTypeDef *

hadc)

Function Description Conversion complete callback in non blocking mode.

Parameters

hadc: ADC handle

Return values

None

4.3.22 HAL_ADC_ConvHalfCpltCallback

Function Name

void HAL_ADC_ConvHalfCpltCallback (ADC_HandleTypeDef *

hadc)

Function Description Conversion DMA half-transfer callback in non blocking mode.

Parameters

hadc: ADC handle

Return values

None

94/654 DOCID026682 Rev 3

UM1816

4.3.23 HAL_ADC_LevelOutOfWindowCallback

Function Name

HAL ADC Generic Driver

void HAL_ADC_LevelOutOfWindowCallback

(ADC_HandleTypeDef * hadc)

Function Description Analog watchdog callback in non blocking mode.

Parameters

hadc: ADC handle

Return values

None

4.3.24 HAL_ADC_ErrorCallback

Function Name void HAL_ADC_ErrorCallback (ADC_HandleTypeDef * hadc)

Function Description ADC error callback in non blocking mode (ADC conversion with interruption or transfer by DMA)

Parameters

hadc: ADC handle

Return values

None

4.3.25 HAL_ADC_ConfigChannel

Function Name

HAL_StatusTypeDef HAL_ADC_ConfigChannel

(ADC_HandleTypeDef * hadc, ADC_ChannelConfTypeDef *

sConfig)

Function Description Configures the the selected channel to be linked to the regular group.

Parameters

Notes

Return values

hadc: ADC handle

sConfig: Structure of ADC channel for regular group.

HAL status

In case of usage of internal measurement channels:

Vbat/VrefInt/TempSensor. These internal paths can be be disabled using function HAL_ADC_DeInit().

Possibility to update parameters on the fly: This function initializes channel into regular group, following calls to this function can be used to reconfigure some parameters of structure "ADC_ChannelConfTypeDef" on the fly, without reseting the ADC. The setting of these parameters is conditioned to ADC state. For parameters constraints, see comments of structure "ADC_ChannelConfTypeDef".

4.3.26 HAL_ADC_AnalogWDGConfig

Function Name

HAL_StatusTypeDef HAL_ADC_AnalogWDGConfig

(ADC_HandleTypeDef * hadc, ADC_AnalogWDGConfTypeDef *

AnalogWDGConfig)

Function Description Configures the analog watchdog.

Parameters

Return values

hadc: ADC handle

AnalogWDGConfig: Structure of ADC analog watchdog configuration

HAL status

DOCID026682 Rev 3 95/654

HAL ADC Generic Driver

4.3.27 HAL_ADC_GetState

UM1816

Function Name uint32_t HAL_ADC_GetState (ADC_HandleTypeDef * hadc)

Function Description return the ADC state

Parameters

hadc: ADC handle

Return values

HAL state

4.3.28 HAL_ADC_GetError

Function Name uint32_t HAL_ADC_GetError (ADC_HandleTypeDef * hadc)

Function Description Return the ADC error code.

Parameters

hadc: ADC handle

Return values

ADC Error Code

4.4

4.4.1

ADC Firmware driver defines

ADC

ADC analog watchdog mode

ADC_ANALOGWATCHDOG_NONE

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 channels

ADC_CHANNEL_0

ADC_CHANNEL_1

ADC_CHANNEL_2

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

96/654 DOCID026682 Rev 3

UM1816

HAL ADC Generic Driver

ADC_CHANNEL_13

ADC_CHANNEL_14

ADC_CHANNEL_15

ADC_CHANNEL_16

ADC_CHANNEL_17

ADC_CHANNEL_18

ADC_CHANNEL_19

ADC_CHANNEL_20

ADC_CHANNEL_21

ADC_CHANNEL_22

ADC_CHANNEL_23

ADC_CHANNEL_24

ADC_CHANNEL_25

ADC_CHANNEL_26

ADC_CHANNEL_27

ADC_CHANNEL_28

ADC_CHANNEL_29

ADC_CHANNEL_30

ADC_CHANNEL_31

ADC_CHANNEL_TEMPSENSOR

ADC_CHANNEL_VREFINT

ADC_CHANNEL_VCOMP

ADC_CHANNEL_VOPAMP1

ADC_CHANNEL_VOPAMP2

ADC_CHANNEL_VOPAMP3

ADC ChannelsBank

ADC_CHANNELS_BANK_A

ADC_CHANNELS_BANK_B

IS_ADC_CHANNELSBANK

IS_ADC_CHANNELSBANK

ADC ClockPrescaler

ADC_CLOCK_ASYNC_DIV1 ADC asynchronous clock derived from ADC dedicated HSI without prescaler

ADC_CLOCK_ASYNC_DIV2 ADC asynchronous clock derived from ADC dedicated HSI divided by a prescaler of 2

ADC_CLOCK_ASYNC_DIV4 ADC asynchronous clock derived from ADC dedicated HSI divided by a prescaler of 4

ADC conversion group

DOCID026682 Rev 3 97/654

HAL ADC Generic Driver

ADC_REGULAR_GROUP

ADC_INJECTED_GROUP

ADC_REGULAR_INJECTED_GROUP

ADC Data_align

ADC_DATAALIGN_RIGHT

ADC_DATAALIGN_LEFT

ADC EOCSelection

ADC_EOC_SEQ_CONV

ADC_EOC_SINGLE_CONV

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

UM1816

HAL_ADC_ERROR_OVR

HAL_ADC_ERROR_DMA

Overrun error

DMA transfer error

ADC Event type

ADC_AWD_EVENT ADC Analog watchdog event

ADC_OVR_EVENT

ADC Exported Macros

ADC overrun event

__HAL_ADC_ENABLE Description:

Enable the ADC peripheral.

__HAL_ADC_DISABLE

__HAL_ADC_ENABLE_IT

Parameters:

__HANDLE__: ADC handle

Return value:

None

Description:

Disable the ADC peripheral.

Parameters:

__HANDLE__: ADC handle

Return value:

None

Description:

Enable the ADC end of conversion interrupt.

Parameters:

__HANDLE__: ADC handle

__INTERRUPT__: ADC Interrupt This parameter can be any combination of the

98/654 DOCID026682 Rev 3

UM1816

__HAL_ADC_DISABLE_IT

__HAL_ADC_GET_IT_SOURCE

HAL ADC Generic Driver following values:

ADC_IT_EOC: ADC End of Regular

Conversion interrupt source

ADC_IT_JEOC: ADC End of Injected

Conversion interrupt source

ADC_IT_AWD: ADC Analog watchdog interrupt source

ADC_IT_OVR: ADC overrun interrupt source

Return value:

None

Description:

Disable the ADC end of conversion interrupt.

Parameters:

__HANDLE__: ADC handle

__INTERRUPT__: ADC Interrupt This parameter can be any combination of the following values:

ADC_IT_EOC: ADC End of Regular

Conversion interrupt source

ADC_IT_JEOC: ADC End of Injected

Conversion interrupt source

ADC_IT_AWD: ADC Analog watchdog interrupt source

ADC_IT_OVR: ADC overrun interrupt source

Return value:

None

Description:

Checks if the specified ADC interrupt source is enabled or disabled.

Parameters:

__HANDLE__: ADC handle

__INTERRUPT__: ADC interrupt source to check This parameter can be any combination of the following values:

ADC_IT_EOC: ADC End of Regular

Conversion interrupt source

ADC_IT_JEOC: ADC End of Injected

Conversion interrupt source

ADC_IT_AWD: ADC Analog watchdog interrupt source

ADC_IT_OVR: ADC overrun interrupt source

Return value:

DOCID026682 Rev 3 99/654

HAL ADC Generic Driver

__HAL_ADC_GET_FLAG

100/654

__HAL_ADC_CLEAR_FLAG

UM1816

State: of interruption (SET or RESET)

Description:

Get the selected ADC's flag status.

Parameters:

__HANDLE__: ADC handle

__FLAG__: ADC flag This parameter can be any combination of the following values:

ADC_FLAG_STRT: ADC Regular group start flag

ADC_FLAG_JSTRT: ADC Injected group start flag

ADC_FLAG_EOC: ADC End of

Regular conversion flag

ADC_FLAG_JEOC: ADC End of

Injected conversion flag

ADC_FLAG_AWD: ADC Analog watchdog flag

ADC_FLAG_OVR: ADC overrun flag

ADC_FLAG_ADONS: ADC ready status flag

ADC_FLAG_RCNR: ADC Regular group ready status flag

ADC_FLAG_JCNR: ADC Injected group ready status flag

Return value:

None

Description:

Clear the ADC's pending flags.

Parameters:

__HANDLE__: ADC handle

__FLAG__: ADC flag

ADC_FLAG_STRT: ADC Regular group start flag

ADC_FLAG_JSTRT: ADC Injected group start flag

ADC_FLAG_EOC: ADC End of

Regular conversion flag

ADC_FLAG_JEOC: ADC End of

Injected conversion flag

ADC_FLAG_AWD: ADC Analog watchdog flag

ADC_FLAG_OVR: ADC overrun flag

ADC_FLAG_ADONS: ADC ready status flag

ADC_FLAG_RCNR: ADC Regular group ready status flag

ADC_FLAG_JCNR: ADC Injected group ready status flag

DOCID026682 Rev 3

UM1816

HAL ADC Generic Driver

__HAL_ADC_RESET_HANDLE_STATE Description:

Reset ADC handle state.

Parameters:

__HANDLE__: ADC handle

Return value:

None

ADC Exported Types

Return value:

None

HAL_ADC_STATE_RESET

HAL_ADC_STATE_READY

HAL_ADC_STATE_BUSY_INTERNAL

HAL_ADC_STATE_TIMEOUT TimeOut occurrence

HAL_ADC_STATE_ERROR_INTERNAL Internal error occurrence

HAL_ADC_STATE_ERROR_CONFIG

HAL_ADC_STATE_ERROR_DMA

Configuration error occurrence

DMA error occurrence

HAL_ADC_STATE_REG_BUSY

ADC not yet initialized or disabled

ADC peripheral ready for use

ADC is busy to internal process (initialization, calibration)

HAL_ADC_STATE_REG_EOC

HAL_ADC_STATE_REG_OVR

HAL_ADC_STATE_REG_EOSMP

A conversion on group regular is ongoing or can occur (either by continuous mode, external trigger, low power auto power-on, multimode ADC master control)

Conversion data available on group regular

Overrun occurrence

Not available on STM32L1 device: End Of

Sampling flag raised

HAL_ADC_STATE_INJ_BUSY

HAL_ADC_STATE_INJ_EOC

HAL_ADC_STATE_INJ_JQOVF

A conversion on group injected is ongoing or can occur (either by auto-injection mode, external trigger, low power auto power-on, multimode ADC master control)

Conversion data available on group injected

Not available on STM32L1 device: Injected queue overflow occurrence

HAL_ADC_STATE_AWD1

HAL_ADC_STATE_AWD2

Out-of-window occurrence of analog watchdog 1

Not available on STM32L1 device: Out-ofwindow occurrence of analog watchdog 2

HAL_ADC_STATE_AWD3 Not available on STM32L1 device: Out-ofwindow occurrence of analog watchdog 3

HAL_ADC_STATE_MULTIMODE_SLAVE Not available on STM32L1 device: ADC in multimode slave state, controlled by another

ADC master (

DOCID026682 Rev 3 101/654

HAL ADC Generic Driver

ADC external trigger enable for regular group

ADC_EXTERNALTRIGCONVEDGE_NONE

ADC_EXTERNALTRIGCONVEDGE_RISING

ADC_EXTERNALTRIGCONVEDGE_FALLING

ADC_EXTERNALTRIGCONVEDGE_RISINGFALLING

ADC External trigger source Regular

ADC_EXTERNALTRIGCONV_T2_CC3

ADC_EXTERNALTRIGCONV_T2_CC2

ADC_EXTERNALTRIGCONV_T2_TRGO

ADC_EXTERNALTRIGCONV_T3_CC1

ADC_EXTERNALTRIGCONV_T3_CC3

ADC_EXTERNALTRIGCONV_T3_TRGO

ADC_EXTERNALTRIGCONV_T4_CC4

ADC_EXTERNALTRIGCONV_T4_TRGO

ADC_EXTERNALTRIGCONV_T6_TRGO

ADC_EXTERNALTRIGCONV_T9_CC2

ADC_EXTERNALTRIGCONV_T9_TRGO

ADC_EXTERNALTRIGCONV_EXT_IT11

ADC_SOFTWARE_START

ADC flags definition

ADC_FLAG_AWD ADC Analog watchdog flag

ADC_FLAG_EOC

ADC_FLAG_JEOC

ADC End of Regular conversion flag

ADC End of Injected conversion flag

ADC_FLAG_JSTRT ADC Injected group start flag

ADC_FLAG_STRT

ADC_FLAG_OVR

ADC Regular group start flag

ADC overrun flag

ADC_FLAG_ADONS ADC ready status flag

ADC_FLAG_RCNR ADC Regular group ready status flag

ADC_FLAG_JCNR ADC Injected group ready status flag

ADC Internal HAL driver Ext trig src Regular

ADC_EXTERNALTRIG_T9_CC2

ADC_EXTERNALTRIG_T9_TRGO

ADC_EXTERNALTRIG_T2_CC3

ADC_EXTERNALTRIG_T2_CC2

ADC_EXTERNALTRIG_T3_TRGO

ADC_EXTERNALTRIG_T4_CC4

102/654 DOCID026682 Rev 3

UM1816

UM1816

HAL ADC Generic Driver

ADC_EXTERNALTRIG_T2_TRGO

ADC_EXTERNALTRIG_T3_CC1

ADC_EXTERNALTRIG_T3_CC3

ADC_EXTERNALTRIG_T4_TRGO

ADC_EXTERNALTRIG_T6_TRGO

ADC_EXTERNALTRIG_EXT_IT11

ADC interrupts definition

ADC_IT_EOC

ADC_IT_JEOC

ADC End of Regular Conversion interrupt source

ADC End of Injected Conversion interrupt source

ADC_IT_AWD

ADC_IT_OVR

ADC Analog watchdog interrupt source

ADC overrun interrupt source

ADC LowPowerAutoPowerOff

ADC_AUTOPOWEROFF_DISABLE

ADC_AUTOPOWEROFF_IDLE_PHASE

ADC_AUTOPOWEROFF_DELAY_PHASE

ADC power off when ADC is not converting (idle phase)

ADC power off when a delay is inserted between conversions (see parameter ADC_LowPowerAutoWait)

ADC_AUTOPOWEROFF_IDLE_DELAY_PHASES ADC power off when ADC is not converting (idle phase) and when a delay is inserted between conversions

ADC LowPowerAutoWait

ADC_AUTOWAIT_DISABLE

ADC_AUTOWAIT_UNTIL_DATA_READ

< Note : For compatibility with other

STM32 devices with ADC autowait

Insert a delay between ADC conversions: infinite delay, until the result of previous conversion is read

ADC_AUTOWAIT_7_APBCLOCKCYCLES Insert a delay between ADC conversions:

7 APB clock cycles

ADC_AUTOWAIT_15_APBCLOCKCYCLES Insert a delay between ADC conversions:

15 APB clock cycles

ADC_AUTOWAIT_31_APBCLOCKCYCLES Insert a delay between ADC conversions:

31 APB clock cycles

ADC_AUTOWAIT_63_APBCLOCKCYCLES Insert a delay between ADC conversions:

63 APB clock cycles

ADC_AUTOWAIT_127_APBCLOCKCYCLES Insert a delay between ADC conversions:

127 APB clock cycles

ADC_AUTOWAIT_255_APBCLOCKCYCLES Insert a delay between ADC conversions:

255 APB clock cycles

ADC Private Constants

DOCID026682 Rev 3 103/654

HAL ADC Generic Driver

ADC_ENABLE_TIMEOUT

ADC_DISABLE_TIMEOUT

ADC_STAB_DELAY_US

ADC_TEMPSENSOR_DELAY_US

ADC_FLAG_POSTCONV_ALL

ADC Private Macros

ADC_IS_ENABLE

UM1816

Description:

Verification of ADC state: enabled or disabled.

Parameters:

__HANDLE__: ADC handle

Return value:

SET: (ADC enabled) or RESET (ADC disabled)

ADC_IS_SOFTWARE_START_REGULAR Description:

Test if conversion trigger of regular group is software start or external trigger.

Parameters:

__HANDLE__: ADC handle

Return value:

SET: (software start) or RESET

(external trigger)

ADC_IS_SOFTWARE_START_INJECTED Description:

Test if conversion trigger of injected group is software start or external trigger.

ADC_STATE_CLR_SET

Parameters:

__HANDLE__: ADC handle

Return value:

SET: (software start) or RESET

(external trigger)

Description:

Simultaneously clears and sets specific bits of the handle State.

Return value:

None

Notes:

: ADC_STATE_CLR_SET() macro is merely aliased to generic macro

104/654 DOCID026682 Rev 3

UM1816

ADC_CLEAR_ERRORCODE

ADC_SQR1_L_SHIFT

ADC_SMPR2

ADC_SMPR3

ADC_SQR5_RK

HAL ADC Generic Driver

MODIFY_REG(), the first parameter is the ADC handle State, the second parameter is the bit field to clear, the third and last parameter is the bit field to set.

Description:

Clear ADC error code (set it to error code: "no error")

Parameters:

__HANDLE__: ADC handle

Return value:

None

Description:

Set ADC number of ranks into regular channel sequence length.

Parameters:

_NbrOfConversion_: Regular channel sequence length

Return value:

None

Description:

Set the ADC's sample time for channel numbers between 10 and 18.

Parameters:

_SAMPLETIME_: Sample time parameter.

_CHANNELNB_: Channel number.

Return value:

None

Description:

Set the ADC's sample time for channel numbers between 0 and 9.

Parameters:

_SAMPLETIME_: Sample time parameter.

_CHANNELNB_: Channel number.

Return value:

None

Description:

Set the selected regular channel rank for rank between 1 and 6.

DOCID026682 Rev 3 105/654

HAL ADC Generic Driver

106/654

ADC_SQR4_RK

ADC_SQR3_RK

ADC_SQR2_RK

ADC_SQR1_RK

ADC_JSQR_JL_SHIFT

UM1816

Parameters:

_CHANNELNB_: Channel number.

_RANKNB_: Rank number.

Return value:

None

Description:

Set the selected regular channel rank for rank between 7 and 12.

Parameters:

_CHANNELNB_: Channel number.

_RANKNB_: Rank number.

Return value:

None

Description:

Set the selected regular channel rank for rank between 13 and 18.

Parameters:

_CHANNELNB_: Channel number.

_RANKNB_: Rank number.

Return value:

None

Description:

Set the selected regular channel rank for rank between 19 and 24.

Parameters:

_CHANNELNB_: Channel number.

_RANKNB_: Rank number.

Return value:

None

Description:

Set the selected regular channel rank for rank between 25 and 28.

Parameters:

_CHANNELNB_: Channel number.

_RANKNB_: Rank number.

Return value:

None

Description:

Set the injected sequence length.

DOCID026682 Rev 3

UM1816

ADC_JSQR_RK_JL

ADC_CR2_DMACONTREQ

ADC_CR2_CONTINUOUS

ADC_CR1_DISCONTINUOUS_NUM

HAL ADC Generic Driver

Parameters:

_JSQR_JL_: Sequence length.

Return value:

None

Description:

Set the selected injected channel rank

Note: on STM32L1 devices, channel rank position in JSQR register is depending on total number of ranks selected into injected sequencer (ranks sequence starting from 4-JL)

Parameters:

_CHANNELNB_: Channel number.

_RANKNB_: Rank number.

_JSQR_JL_: Sequence length.

Return value:

None

Description:

Enable the ADC DMA continuous request.

Parameters:

_DMACONTREQ_MODE_: DMA continuous request mode.

Return value:

None

Description:

Enable ADC continuous conversion mode.

Parameters:

_CONTINUOUS_MODE_: Continuous mode.

Return value:

None

Description:

Configures the number of discontinuous conversions for the regular group channels.

Parameters:

_NBR_DISCONTINUOUS_CONV_:

Number of discontinuous conversions.

Return value:

DOCID026682 Rev 3 107/654

HAL ADC Generic Driver

ADC_CR1_SCAN_SET

IS_ADC_CLOCKPRESCALER

IS_ADC_RESOLUTION

IS_ADC_RESOLUTION_8_6_BITS

IS_ADC_DATA_ALIGN

IS_ADC_SCAN_MODE

IS_ADC_EXTTRIG_EDGE

IS_ADC_EXTTRIG

IS_ADC_EOC_SELECTION

IS_ADC_AUTOWAIT

IS_ADC_AUTOPOWEROFF

IS_ADC_CHANNEL

IS_ADC_SAMPLE_TIME

IS_ADC_REGULAR_RANK

IS_ADC_ANALOG_WATCHDOG_MODE

IS_ADC_CONVERSION_GROUP

IS_ADC_EVENT_TYPE

UM1816

None

Description:

Enable ADC scan mode to convert multiple ranks with sequencer.

Parameters:

_SCAN_MODE_: Scan conversion mode.

Return value:

None

ADC range verification

IS_ADC_RANGE

ADC regular discontinuous mode number verification

IS_ADC_REGULAR_DISCONT_NUMBER

ADC regular nb conv verification

IS_ADC_REGULAR_NB_CONV

ADC rank into regular group

ADC_REGULAR_RANK_1

ADC_REGULAR_RANK_2

ADC_REGULAR_RANK_3

ADC_REGULAR_RANK_4

ADC_REGULAR_RANK_5

108/654 DOCID026682 Rev 3

UM1816

HAL ADC Generic Driver

ADC_REGULAR_RANK_6

ADC_REGULAR_RANK_7

ADC_REGULAR_RANK_8

ADC_REGULAR_RANK_9

ADC_REGULAR_RANK_10

ADC_REGULAR_RANK_11

ADC_REGULAR_RANK_12

ADC_REGULAR_RANK_13

ADC_REGULAR_RANK_14

ADC_REGULAR_RANK_15

ADC_REGULAR_RANK_16

ADC_REGULAR_RANK_17

ADC_REGULAR_RANK_18

ADC_REGULAR_RANK_19

ADC_REGULAR_RANK_20

ADC_REGULAR_RANK_21

ADC_REGULAR_RANK_22

ADC_REGULAR_RANK_23

ADC_REGULAR_RANK_24

ADC_REGULAR_RANK_25

ADC_REGULAR_RANK_26

ADC_REGULAR_RANK_27

ADC_REGULAR_RANK_28

ADC Resolution

ADC_RESOLUTION_12B ADC 12-bit resolution

ADC_RESOLUTION_10B ADC 10-bit resolution

ADC_RESOLUTION_8B ADC 8-bit resolution

ADC_RESOLUTION_6B ADC 6-bit resolution

ADC sampling times

ADC_SAMPLETIME_4CYCLES

ADC_SAMPLETIME_9CYCLES

Sampling time 4 ADC clock cycles

Sampling time 9 ADC clock cycles

ADC_SAMPLETIME_16CYCLES Sampling time 16 ADC clock cycles

ADC_SAMPLETIME_24CYCLES Sampling time 24 ADC clock cycles

ADC_SAMPLETIME_48CYCLES Sampling time 48 ADC clock cycles

ADC_SAMPLETIME_96CYCLES Sampling time 96 ADC clock cycles

ADC_SAMPLETIME_192CYCLES Sampling time 192 ADC clock cycles

DOCID026682 Rev 3 109/654

HAL ADC Generic Driver

ADC_SAMPLETIME_384CYCLES Sampling time 384 ADC clock cycles

ADC sampling times all channels

ADC_SAMPLETIME_ALLCHANNELS_SMPR3BIT2

ADC_SAMPLETIME_ALLCHANNELS_SMPR2BIT2

ADC_SAMPLETIME_ALLCHANNELS_SMPR1BIT2

ADC_SAMPLETIME_ALLCHANNELS_SMPR0BIT2

ADC_SAMPLETIME_ALLCHANNELS_SMPR3BIT1

ADC_SAMPLETIME_ALLCHANNELS_SMPR2BIT1

ADC_SAMPLETIME_ALLCHANNELS_SMPR1BIT1

ADC_SAMPLETIME_ALLCHANNELS_SMPR0BIT1

ADC_SAMPLETIME_ALLCHANNELS_SMPR3BIT0

ADC_SAMPLETIME_ALLCHANNELS_SMPR2BIT0

ADC_SAMPLETIME_ALLCHANNELS_SMPR1BIT0

ADC_SAMPLETIME_ALLCHANNELS_SMPR0BIT0

ADC Scan mode

ADC_SCAN_DISABLE

ADC_SCAN_ENABLE

UM1816

110/654 DOCID026682 Rev 3

UM1816

HAL ADC Extension Driver

5

5.1

5.2

5.2.1

HAL ADC Extension Driver

HAL ADC Extension Driver

ADCEx Firmware driver registers structures

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

DOCID026682 Rev 3 111/654

HAL ADC Extension Driver sequencer. To use the injected group sequencer and convert several ranks,

UM1816

parameter 'ScanConvMode' must be enabled. This parameter must be a number 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.

112/654 DOCID026682 Rev 3

UM1816

5.3

5.3.1

5.3.2

5.3.3

HAL ADC Extension Driver

ADCEx Firmware driver API description

IO operation functions

This section provides functions allowing to:

Start conversion of injected group.

Stop conversion of injected group.

Poll for conversion complete on injected group.

Get result of injected channel conversion.

Start conversion of injected group and enable interruptions.

Stop conversion of injected group and disable interruptions.

This section contains the following APIs:

HAL_ADCEx_InjectedStart()

HAL_ADCEx_InjectedStop()

HAL_ADCEx_InjectedPollForConversion()

HAL_ADCEx_InjectedStart_IT()

HAL_ADCEx_InjectedStop_IT()

HAL_ADCEx_InjectedGetValue()

HAL_ADCEx_InjectedConvCpltCallback()

Peripheral Control functions

This section provides functions allowing to:

Configure channels on injected group

This section contains the following APIs:

HAL_ADCEx_InjectedConfigChannel()

HAL_ADCEx_InjectedStart

Function Name

HAL_StatusTypeDef HAL_ADCEx_InjectedStart

(ADC_HandleTypeDef * hadc)

Function Description Enables ADC, starts conversion of injected group.

Parameters

hadc: ADC handle

Return values

HAL status

5.3.4 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

Notes

None

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.

In case of auto-injection mode, HAL_ADC_Stop must be used.

DOCID026682 Rev 3 113/654

HAL ADC Extension Driver

5.3.5 HAL_ADCEx_InjectedPollForConversion

Function Name

UM1816

HAL_StatusTypeDef HAL_ADCEx_InjectedPollForConversion

(ADC_HandleTypeDef * hadc, uint32_t Timeout)

Function Description Wait for injected group conversion to be completed.

Parameters

hadc: ADC handle

Timeout: Timeout value in millisecond.

Return values

HAL status

5.3.6

5.3.7

HAL_ADCEx_InjectedStart_IT

Function Name

HAL_StatusTypeDef HAL_ADCEx_InjectedStart_IT

(ADC_HandleTypeDef * hadc)

Function Description Enables ADC, starts conversion of injected group with interruption.

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

Notes

None

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.

5.3.8

5.3.9

HAL_ADCEx_InjectedGetValue

Function Name

uint32_t HAL_ADCEx_InjectedGetValue (ADC_HandleTypeDef

* hadc, uint32_t InjectedRank)

Function Description Get ADC injected group conversion result.

Parameters

Return values

hadc: ADC handle

InjectedRank: the converted ADC injected rank. This parameter can be one of the following values:

ADC_INJECTED_RANK_1: Injected Channel1 selectedADC_INJECTED_RANK_2: Injected Channel2 selectedADC_INJECTED_RANK_3: Injected Channel3 selectedADC_INJECTED_RANK_4: Injected Channel4 selected

None

HAL_ADCEx_InjectedConvCpltCallback

Function Name

void HAL_ADCEx_InjectedConvCpltCallback

(ADC_HandleTypeDef * hadc)

Function Description Injected conversion complete callback in non blocking mode.

114/654 DOCID026682 Rev 3

UM1816

Parameters

Return values

hadc: ADC handle

None

HAL ADC Extension Driver

5.3.10 HAL_ADCEx_InjectedConfigChannel

Function Name

HAL_StatusTypeDef HAL_ADCEx_InjectedConfigChannel

(ADC_HandleTypeDef * hadc, ADC_InjectionConfTypeDef *

sConfigInjected)

Function Description Configures the ADC injected group and the selected channel to be linked to the injected group.

Parameters

hadc: ADC handle

sConfigInjected: Structure of ADC injected group and ADC channel for injected group.

Return values

Notes

None

Possibility to update parameters on the fly: This function initializes injected group, following calls to this function can be used to reconfigure some parameters of structure

"ADC_InjectionConfTypeDef" on the fly, without reseting the

ADC. The setting of these parameters is conditioned to ADC state: this function must be called when ADC is not under conversion.

5.4

5.4.1

ADCEx Firmware driver defines

ADCEx

ADCEx Exported Macros

__HAL_ADC_CHANNELS_BANK Description:

Selection of channels bank.

Parameters:

__HANDLE__: ADC handle

__BANK__: Bank selection. This parameter can be a value of

Return value:

None

__HAL_ADC_CHANNEL_SPEED_FAST Limited to channels 3, 8, 13 and to devices category Cat.3, Cat.4, Cat.5.

__HAL_ADC_CHANNEL_SPEED_SLOW

ADCEx external trigger enable for injected group

ADC_EXTERNALTRIGINJECCONV_EDGE_NONE

ADC_EXTERNALTRIGINJECCONV_EDGE_RISING

ADC_EXTERNALTRIGINJECCONV_EDGE_FALLING

ADC_EXTERNALTRIGINJECCONV_EDGE_RISINGFALLING

ADCEx External trigger source Injected

DOCID026682 Rev 3 115/654

HAL ADC Extension Driver

ADC_EXTERNALTRIGINJECCONV_T2_CC1

ADC_EXTERNALTRIGINJECCONV_T2_TRGO

ADC_EXTERNALTRIGINJECCONV_T3_CC4

ADC_EXTERNALTRIGINJECCONV_T4_TRGO

ADC_EXTERNALTRIGINJECCONV_T4_CC1

ADC_EXTERNALTRIGINJECCONV_T4_CC2

ADC_EXTERNALTRIGINJECCONV_T4_CC3

ADC_EXTERNALTRIGINJECCONV_T7_TRGO

ADC_EXTERNALTRIGINJECCONV_T9_CC1

ADC_EXTERNALTRIGINJECCONV_T9_TRGO

ADC_EXTERNALTRIGINJECCONV_T10_CC1

ADC_EXTERNALTRIGINJECCONV_EXT_IT15

ADC_INJECTED_SOFTWARE_START

ADCEx injected nb conv verification

IS_ADC_INJECTED_NB_CONV

ADCEx rank into injected group

ADC_INJECTED_RANK_1

ADC_INJECTED_RANK_2

ADC_INJECTED_RANK_3

ADC_INJECTED_RANK_4

ADCEx Internal HAL driver Ext trig src Injected

ADC_EXTERNALTRIGINJEC_T9_CC1

ADC_EXTERNALTRIGINJEC_T9_TRGO

ADC_EXTERNALTRIGINJEC_T2_TRGO

ADC_EXTERNALTRIGINJEC_T2_CC1

ADC_EXTERNALTRIGINJEC_T3_CC4

ADC_EXTERNALTRIGINJEC_T4_TRGO

ADC_EXTERNALTRIGINJEC_T4_CC1

ADC_EXTERNALTRIGINJEC_T4_CC2

ADC_EXTERNALTRIGINJEC_T4_CC3

ADC_EXTERNALTRIGINJEC_T10_CC1

ADC_EXTERNALTRIGINJEC_T7_TRGO

ADC_EXTERNALTRIGINJEC_EXT_IT15

ADCEx Private Constants

ADC_CONVERSIONCLOCKCYCLES_SAMPLETIME_4CYCLE5

ADC_CONVERSIONCLOCKCYCLES_SAMPLETIME_9CYCLES

116/654 DOCID026682 Rev 3

UM1816

UM1816

HAL ADC Extension Driver

ADC_CONVERSIONCLOCKCYCLES_SAMPLETIME_16CYCLES

ADC_CONVERSIONCLOCKCYCLES_SAMPLETIME_24CYCLES

ADC_CONVERSIONCLOCKCYCLES_SAMPLETIME_48CYCLES

ADC_CONVERSIONCLOCKCYCLES_SAMPLETIME_96CYCLES

ADC_CONVERSIONCLOCKCYCLES_SAMPLETIME_192CYCLES

ADC_CONVERSIONCLOCKCYCLES_SAMPLETIME_384CYCLES

ADC_TEMPSENSOR_DELAY_US

ADCEx Private Macro

__ADC_SQR1_SQXX Description:

Set ADC ranks available in register

SQR1.

Parameters:

_NbrOfConversion_: Regular channel sequence length

Return value:

None

ADC_SMPR0

ADC_SMPR1

Description:

Set the ADC's sample time for channel numbers between 30 and 31.

Parameters:

_SAMPLETIME_: Sample time parameter.

_CHANNELNB_: Channel number.

Return value:

None

None

Description:

Set the ADC's sample time for channel numbers between 20 and 29.

ADC_SMPR1_CHANNEL_MAX

Parameters:

_SAMPLETIME_: Sample time parameter.

_CHANNELNB_: Channel number.

Return value:

None

Description:

Defines the highest channel available in register SMPR1.

Parameters:

DOCID026682 Rev 3 117/654

HAL ADC Extension Driver

ADC_CR2_MASK_ADCINIT

ADC_CONVCYCLES_MAX_RANGE

UM1816

None

Return value:

None

Description:

Define mask of configuration bits of

ADC and regular group in register

CR2 (bits of ADC enable, conversion start and injected group are excluded of this mask).

Return value:

None

Description:

Get the maximum ADC conversion cycles on all channels.

Parameters:

__HANDLE__: ADC handle

Return value:

ADC: conversion cycles on all channels

ADC_GET_CLOCK_PRESCALER_DECIMAL Description:

Get the ADC clock prescaler from

ADC common control register and convert it to its decimal number setting (refer to reference manual)

ADC_SMPR0_CLEAR

Return value:

None

Description:

Clear register SMPR0.

Parameters:

__HANDLE__: ADC handle

Return value:

None

ADC_CR2_CLEAR

ADC_SMPR0_CHANNEL_SET

Description:

Clear register CR2.

Parameters:

__HANDLE__: ADC handle

Return value:

None

Description:

118/654 DOCID026682 Rev 3

UM1816

IS_ADC_INJECTED_RANK

IS_ADC_EXTTRIGINJEC_EDGE

IS_ADC_EXTTRIGINJEC

HAL ADC Extension Driver

Set the sampling time of selected channel on register SMPR0 Register

SMPR0 availability depends on device category.

Parameters:

__HANDLE__: ADC handle

_SAMPLETIME_: Sample time parameter.

__CHANNEL__: Channel number.

Return value:

None

DOCID026682 Rev 3 119/654

HAL COMP Generic Driver

UM1816

6

6.1

6.2

6.2.1

120/654

HAL COMP Generic Driver

HAL COMP Generic Driver

COMP Firmware driver registers structures

COMP_InitTypeDef

Data Fields

uint32_t InvertingInput

uint32_t NonInvertingInput

uint32_t Output

uint32_t Mode

uint32_t WindowMode

uint32_t TriggerMode

uint32_t NonInvertingInputPull

Field Documentation

uint32_t COMP_InitTypeDef::InvertingInput

Selects the inverting input of the comparator. This parameter can be a value of

COMP_InvertingInput

Note: Inverting input can be changed on the fly, while

comparator is running. Note: This feature is available on COMP2 only. If COMP1 is selected, this parameter is discarded (On COMP1, inverting input is fixed to Vrefint).

uint32_t COMP_InitTypeDef::NonInvertingInput

Selects the non inverting input of the comparator. This parameter can be a value of

COMPEx_NonInvertingInput

uint32_t COMP_InitTypeDef::Output

Selects the output redirection of the comparator. This parameter can be a value of

COMP_Output

Note: This feature is available on COMP2 only. If COMP1 is selected,

this parameter is discarded.

uint32_t COMP_InitTypeDef::Mode

Selects the operating consumption mode of the comparator to adjust the

speed/consumption. This parameter can be a value of

COMP_Mode

Note: This

feature is available on COMP2 only. If COMP1 is selected, this parameter is discarded.

uint32_t COMP_InitTypeDef::WindowMode

Selects the window mode of the 2 comparators. If enabled, non-inverting inputs of the

2 comparators are connected together and are using inputs of COMP2 only (COMP1 non-inverting input is no more accessible, even from ADC channel VCOMP). This

parameter can be a value of

COMP_WindowMode

Note: This feature must be

enabled from COMP2 instance. If COMP1 is selected, this parameter is discarded.

uint32_t COMP_InitTypeDef::TriggerMode

Selects the trigger mode of the comparator when using interruption on EXTI line

(interrupt mode). This parameter can be a value of

COMP_TriggerMode

Note: This

feature is used with function "HAL_COMP_Start_IT()". In all other functions, this parameter is discarded.

uint32_t COMP_InitTypeDef::NonInvertingInputPull

Selects the internal pulling resistor connected on non inverting input. This parameter

DOCID026682 Rev 3

UM1816

6.2.2

6.3

6.3.1

HAL COMP Generic Driver

can be a value of

COMP_NonInvertingInputPull

Note: To avoid extra power

consumption, only one resistor should be enabled at a time. Note: This feature is available on COMP1 only. If COMP2 is selected, this parameter is discarded.

COMP_HandleTypeDef

Data Fields

COMP_TypeDef * Instance

COMP_InitTypeDef Init

HAL_LockTypeDef Lock

__IO HAL_COMP_StateTypeDef State

Field Documentation

COMP_TypeDef* COMP_HandleTypeDef::Instance

Register base address

COMP_InitTypeDef COMP_HandleTypeDef::Init

COMP required parameters

HAL_LockTypeDef COMP_HandleTypeDef::Lock

Locking object

__IO HAL_COMP_StateTypeDef COMP_HandleTypeDef::State

COMP communication state

COMP Firmware driver API description

COMP Peripheral features

The STM32L1xx device family integrates 2 analog comparators COMP1 and COMP2:

1.

The non inverting input and inverting input can be set to GPIO pins. Refer to

Table

17: "COMP Inputs for the STM32L1xx devices"

. HAL COMP driver configures the

Routing Interface (RI) to connect the selected I/O pins to comparator input. Caution:

Comparator COMP1 and ADC cannot be used at the same time as ADC since they share the ADC switch matrix: COMP1 non-inverting input is routed through ADC switch matrix. Except if ADC is intented to measure voltage on COMP1 non-inverting input: it can be performed on ADC channel VCOMP.

2. The COMP output is available using HAL_COMP_GetOutputLevel().

3. The COMP output can be redirected to embedded timers (TIM2, TIM3, TIM4, TIM10).

COMP output cannot be redirected to any I/O pin. Refer to

Table 16: "Redirection of

COMP outputs to embedded timers"

.

4. The comparators COMP1 and COMP2 can be combined in window mode. In this mode, COMP2 non inverting input is used as common non-inverting input.

5. The 2 comparators have interrupt capability with wake-up from Sleep and Stop modes (through the EXTI controller):

COMP1 is internally connected to EXTI Line 21

COMP2 is internally connected to EXTI Line 22 From the corresponding IRQ handler, the right interrupt source can be retrieved with the macros

__HAL_COMP_COMP1_EXTI_GET_FLAG() and

__HAL_COMP_COMP2_EXTI_GET_FLAG().

DOCID026682 Rev 3 121/654

HAL COMP Generic Driver

UM1816

6. The comparators also offer the possibility to ouput the voltage reference (VrefInt), used on inverting inputs, on I/O pin through a buffer. To use it, refer to macro

"__HAL_SYSCFG_VREFINT_OUT_ENABLE()".

Table 16: Redirection of COMP outputs to embedded timers

COMP1 COMP2

No redirection to timers

TIM2 IC4

TIM2 OCREF CLR

TIM3 IC4

TIM3 OCREF CLR

TIM4 IC4

TIM4 OCREF CLR

TIM10 IC1

Inverting inputs

Table 17: COMP Inputs for the STM32L1xx devices

COMP1

1/4 VREFINT

1/2 VREFINT

3/4 VREFINT

VREFINT

DAC Ch1 OUT (PA4)

DAC Ch2 OUT (PA5)

I/O: PB3

-

-

-

OK

-

-

-

Non-inverting inputs

I/O:

PB4, 5, 6, 7

(1)

PA0, 1, 2, 3, 4, 5, 6, 7

(2)

PB0, 1, 12, 13, 14, 15

PC0 1, 2, 3, 4, 5

PE7, 8, 9, 10

PF6, 7, 8, 9, 10

OPAMP1 output

OPAMP2 output

OPAMP3 output

(3)

-

OK

OK

OK

OK

OK

OK

OK

OK

COMP2

OK

OK

OK

OK

OK

OK

OK

-

-

-

-

OK

-

-

-

-

6.3.2

Notes:

(1)

PA6/7 are available on devices category Cat.3, Cat.4, Cat.5 only.

(2)

PA0/1/2/3 are available on devices category Cat.3, Cat.4, Cat.5 only.

(3)

Available on devices category Cat.4 only.

How to use this driver

This driver provides functions to configure and program the Comparators of all

STM32L1xx devices. To use the comparator, perform the following steps:

1. Initialize the COMP low level resources by implementing the HAL_COMP_MspInit().

Configure the comparator input I/O pin using HAL_GPIO_Init(): - For all inputs:

I/O pin in analog mode (Schmitt trigger disabled) - Possible alternate configuration, for non-inverting inputs of comparator 2: I/O pin in floating mode

122/654 DOCID026682 Rev 3

UM1816

6.3.3

6.3.4

6.3.5

HAL COMP Generic Driver

(Schmitt trigger enabled). It is recommended to use analog configuration to avoid any overconsumption around VDD/2.

Enable COMP Peripheral clock using macro

__HAL_RCC_COMP_CLK_ENABLE()

If required enable the COMP interrupt (EXTI line Interrupt): enable the comparator interrupt vector using HAL_NVIC_EnableIRQ(COMP_IRQn) and

HAL_NVIC_SetPriority(COMP_IRQn, xxx, xxx) functions.

2. Configure the comparator using HAL_COMP_Init() function:

Select the inverting input (COMP2 only)

Select the non-inverting input

Select the output redirection to timers (COMP2 only)

Select the speed mode (COMP2 only)

Select the window mode (related to COMP1 and COMP2, but selected by

COMP2 only)

Select the pull-up/down resistors on non-inverting input (COMP1 only)

3. Enable the comparator using HAL_COMP_Start() or HAL_COMP_Start_IT() function

4. If needed, use HAL_COMP_GetOutputLevel() or HAL_COMP_TriggerCallback() functions to manage comparator actions (output level or events)

5. Disable the comparator using HAL_COMP_Stop() or HAL_COMP_Stop_IT() function

6. De-initialize the comparator using HAL_COMP_DeInit() function

Initialization and de-initialization functions

This section provides functions to initialize and de-initialize comparators

This section contains the following APIs:

HAL_COMP_Init()

HAL_COMP_DeInit()

HAL_COMP_MspInit()

HAL_COMP_MspDeInit()

IO operation functions

This subsection provides a set of functions allowing to manage the COMP start and stop actions with or without interruption on ExtI line.

This section contains the following APIs:

HAL_COMP_Start()

HAL_COMP_Stop()

HAL_COMP_Start_IT()

HAL_COMP_Stop_IT()

HAL_COMP_IRQHandler()

Peripheral Control functions

This subsection provides a set of functions allowing to control the COMP management functions: Lock status, comparator output level check, IRQ callback (in case of usage of comparator with interruption on ExtI line).

This section contains the following APIs:

HAL_COMP_Lock()

HAL_COMP_GetOutputLevel()

HAL_COMP_TriggerCallback()

DOCID026682 Rev 3 123/654

HAL COMP Generic Driver

6.3.6 Peripheral State functions

This subsection permit to get in run-time the status of the peripheral.

This section contains the following APIs:

HAL_COMP_GetState()

6.3.7

UM1816

HAL_COMP_Init

Function Name

HAL_StatusTypeDef HAL_COMP_Init (COMP_HandleTypeDef

* hcomp)

Function Description Initializes the COMP according to the specified parameters in the

COMP_InitTypeDef and create the associated handle.

Parameters

Notes

Return values

hcomp: COMP handle

HAL status

If the selected comparator is locked, initialization can't be performed. To unlock the configuration, perform a system reset.

6.3.8

6.3.9

HAL_COMP_DeInit

Function Name

HAL_StatusTypeDef HAL_COMP_DeInit

(COMP_HandleTypeDef * hcomp)

Function Description DeInitializes the COMP peripheral.

Parameters

hcomp: COMP handle

Return values

Notes

HAL status

Deinitialization can't be performed if the COMP configuration is locked. To unlock the configuration, perform a system reset.

HAL_COMP_MspInit

Function Name void HAL_COMP_MspInit (COMP_HandleTypeDef * hcomp)

Function Description Initializes the COMP MSP.

Parameters

Return values

hcomp: COMP handle

None

6.3.10 HAL_COMP_MspDeInit

Function Name void HAL_COMP_MspDeInit (COMP_HandleTypeDef * hcomp)

Function Description DeInitializes COMP MSP.

Parameters

hcomp: COMP handle

Return values

None

6.3.11 HAL_COMP_Start

Function Name

HAL_StatusTypeDef HAL_COMP_Start

124/654 DOCID026682 Rev 3

UM1816

(COMP_HandleTypeDef * hcomp)

Function Description Start the comparator.

Parameters

hcomp: COMP handle

Return values

HAL status

HAL COMP Generic Driver

6.3.12 HAL_COMP_Stop

Function Name

HAL_StatusTypeDef HAL_COMP_Stop

(COMP_HandleTypeDef * hcomp)

Function Description Stop the comparator.

Parameters

hcomp: COMP handle

Return values

HAL status

6.3.13 HAL_COMP_Start_IT

Function Name

HAL_StatusTypeDef HAL_COMP_Start_IT

(COMP_HandleTypeDef * hcomp)

Function Description Enables the interrupt and starts the comparator.

Parameters

hcomp: COMP handle

Return values

HAL status.

6.3.14 HAL_COMP_Stop_IT

Function Name

HAL_StatusTypeDef HAL_COMP_Stop_IT

(COMP_HandleTypeDef * hcomp)

Function Description Disable the interrupt and Stop the comparator.

Parameters

hcomp: COMP handle

Return values

HAL status

6.3.15 HAL_COMP_IRQHandler

Function Name

void HAL_COMP_IRQHandler (COMP_HandleTypeDef *

hcomp)

Function Description Comparator IRQ Handler.

Parameters

hcomp: COMP handle

Return values

HAL status

6.3.16 HAL_COMP_Lock

Function Name

HAL_StatusTypeDef HAL_COMP_Lock

(COMP_HandleTypeDef * hcomp)

Function Description Lock the selected comparator configuration.

Parameters

hcomp: COMP handle

Return values

HAL status

DOCID026682 Rev 3 125/654

HAL COMP Generic Driver

6.3.17 HAL_COMP_GetOutputLevel

Function Name

UM1816 uint32_t HAL_COMP_GetOutputLevel (COMP_HandleTypeDef

* hcomp)

Function Description Return the output level (high or low) of the selected comparator.

6.3.18 HAL_COMP_TriggerCallback

Function Name

void HAL_COMP_TriggerCallback (COMP_HandleTypeDef *

hcomp)

Function Description Comparator callback.

Parameters

hcomp: COMP handle

Return values

None

6.3.19 HAL_COMP_GetState

Function Name

HAL_COMP_StateTypeDef HAL_COMP_GetState

(COMP_HandleTypeDef * hcomp)

Function Description Return the COMP state.

Parameters

hcomp: : COMP handle

Return values

HAL state

6.4

6.4.1

COMP Firmware driver defines

COMP

COMP Exported Macro

__HAL_COMP_RESET_HANDLE_STATE

__HAL_COMP_ENABLE

Description:

Reset COMP handle state.

Parameters:

__HANDLE__: COMP handle.

Return value:

None

Description:

Enables the specified comparator.

Parameters:

__HANDLE__: COMP handle.

Return value:

None.

Description:

126/654

__HAL_COMP_DISABLE

DOCID026682 Rev 3

UM1816

__HAL_COMP_GET_FLAG

HAL COMP Generic Driver

Disables the specified comparator.

Parameters:

__HANDLE__: COMP handle.

Return value:

None.

Description:

Checks whether the specified COMP flag is set or not.

Parameters:

__HANDLE__: specifies the COMP Handle.

__FLAG__: specifies the flag to check. This parameter can be one of the following values:

COMP_FLAG_LOC

K: lock flag

Return value:

The: new state of

__FLAG__ (TRUE or

FALSE).

__HAL_COMP_COMP1_EXTI_ENABLE_RISING_EDGE

Description:

Enable the COMP1 EXTI line rising edge trigger.

Return value:

None

__HAL_COMP_COMP1_EXTI_DISABLE_RISING_EDG

E

__HAL_COMP_COMP1_EXTI_ENABLE_FALLING_EDG

E

Description:

Disable the COMP1 EXTI line rising edge trigger.

Return value:

None

Description:

Enable the COMP1 EXTI line falling edge trigger.

__HAL_COMP_COMP1_EXTI_DISABLE_FALLING_ED

GE

Return value:

None

Description:

Disable the COMP1 EXTI line falling edge trigger.

DOCID026682 Rev 3 127/654

HAL COMP Generic Driver

__HAL_COMP_COMP1_EXTI_ENABLE_RISING_FALLI

NG_EDGE

__HAL_COMP_COMP1_EXTI_DISABLE_RISING_FALLI

NG_EDGE

__HAL_COMP_COMP1_EXTI_ENABLE_IT

__HAL_COMP_COMP1_EXTI_DISABLE_IT

__HAL_COMP_COMP1_EXTI_GET_FLAG

__HAL_COMP_COMP1_EXTI_ENABLE_EVENT

__HAL_COMP_COMP1_EXTI_DISABLE_EVENT

UM1816

Return value:

None

Description:

Enable the COMP1 EXTI line rising & falling edge trigger.

Return value:

None

Description:

Disable the COMP1 EXTI line rising & falling edge trigger.

Return value:

None

Description:

Enable the COMP1 EXTI line in interrupt mode.

Return value:

None

Description:

Disable the COMP1 EXTI line in interrupt mode.

Return value:

None

Description:

Enable the COMP1 EXTI

Line in event mode.

Return value:

None

Description:

Disable the COMP1 EXTI

Line in event mode.

Return value:

None

Description:

Check whether the

COMP1 EXTI line flag is set or not.

Return value:

128/654 DOCID026682 Rev 3

UM1816

__HAL_COMP_COMP1_EXTI_CLEAR_FLAG

__HAL_COMP_COMP1_EXTI_GENERATE_SWIT

HAL COMP Generic Driver

RESET: or SET

Description:

Clear the the COMP1

EXTI flag.

Return value:

None

Description:

Generates a Software interrupt on COMP1 EXTI

Line.

Return value:

None

__HAL_COMP_COMP2_EXTI_ENABLE_RISING_EDGE

Description:

Enable the COMP2 EXTI line rising edge trigger.

Return value:

None

__HAL_COMP_COMP2_EXTI_DISABLE_RISING_EDG

E

__HAL_COMP_COMP2_EXTI_ENABLE_FALLING_EDG

E

Description:

Disable the COMP2 EXTI line rising edge trigger.

Return value:

None

Description:

Enable the COMP2 EXTI line falling edge trigger.

__HAL_COMP_COMP2_EXTI_DISABLE_FALLING_ED

GE

__HAL_COMP_COMP2_EXTI_ENABLE_RISING_FALLI

NG_EDGE

Return value:

None

Description:

Disable the COMP2 EXTI line falling edge trigger.

Return value:

None

Description:

Enable the COMP2 EXTI line rising & falling edge trigger.

Return value:

None

__HAL_COMP_COMP2_EXTI_DISABLE_RISING_FALLI Description:

DOCID026682 Rev 3 129/654

HAL COMP Generic Driver

130/654

NG_EDGE

__HAL_COMP_COMP2_EXTI_ENABLE_IT

__HAL_COMP_COMP2_EXTI_DISABLE_IT

__HAL_COMP_COMP2_EXTI_ENABLE_EVENT

__HAL_COMP_COMP2_EXTI_DISABLE_EVENT

__HAL_COMP_COMP2_EXTI_GET_FLAG

__HAL_COMP_COMP2_EXTI_CLEAR_FLAG

__HAL_COMP_COMP2_EXTI_GENERATE_SWIT

DOCID026682 Rev 3

UM1816

Disable the COMP2 EXTI line rising & falling edge trigger.

Return value:

None

Description:

Enable the COMP2 EXTI line.

Return value:

None

Description:

Disable the COMP2 EXTI line.

Return value:

None

Description:

Enable the COMP2 EXTI

Line in event mode.

Return value:

None

Description:

Disable the COMP2 EXTI

Line in event mode.

Return value:

None

Description:

Check whether the

COMP2 EXTI line flag is set or not.

Return value:

RESET: or SET

Description:

Clear the the COMP2

EXTI flag.

Return value:

None

Description:

Generates a Software interrupt on COMP1 EXTI

Line.

UM1816

HAL COMP Generic Driver

Return value:

None

COMP ExtiLineEvent

COMP_EXTI_LINE_COMP1 External interrupt line 21 Connected to COMP1

COMP_EXTI_LINE_COMP2 External interrupt line 22 Connected to COMP2

COMP InvertingInput

COMP_INVERTINGINPUT_IO External I/O (COMP2_INM connected to pin

PB3) connected to comparator 2 inverting input

COMP_INVERTINGINPUT_VREFINT VREFINT connected to comparator 2 inverting input

COMP_INVERTINGINPUT_3_4VREFINT 3/4 VREFINT connected to comparator 2 inverting input

COMP_INVERTINGINPUT_1_2VREFINT 1/2 VREFINT connected to comparator 2 inverting input

COMP_INVERTINGINPUT_1_4VREFINT 1/4 VREFINT connected to comparator 2 inverting input

COMP_INVERTINGINPUT_DAC1

COMP_INVERTINGINPUT_DAC2

DAC_OUT1 (PA4) connected to comparator 2 inverting input

DAC2_OUT (PA5) connected to comparator 2 inverting input

IS_COMP_INVERTINGINPUT

COMP Mode

COMP_MODE_LOWSPEED Low Speed

COMP_MODE_HIGHSPEED High Speed

IS_COMP_MODE

COMP NonInvertingInputPull

COMP_NONINVERTINGINPUT_NOPULL No internal pull-up or pull-down resistor connected to comparator non inverting input

COMP_NONINVERTINGINPUT_10KPU Internal 10kOhm pull-up resistor connected to comparator non inverting input

COMP_NONINVERTINGINPUT_10KPD Internal 10kOhm pull-down resistor connected to comparator non inverting input

COMP_NONINVERTINGINPUT_400KPU Internal 400kOhm pull-up resistor connected to comparator non inverting input

COMP_NONINVERTINGINPUT_400KPD Internal 400kOhm pull-down resistor connected to comparator non inverting input

IS_COMP_NONINVERTINGINPUTPULL

COMP Output

COMP_OUTPUT_TIM2IC4 COMP2 output connected to TIM2 Input Capture 4

COMP_OUTPUT_TIM2OCREFCLR COMP2 output connected to TIM2 OCREF Clear

DOCID026682 Rev 3 131/654

HAL COMP Generic Driver

COMP_OUTPUT_TIM3IC4

COMP_OUTPUT_NONE

IS_COMP_OUTPUT

COMP OutputLevel

COMP_OUTPUTLEVEL_LOW

UM1816

COMP2 output connected to TIM3 Input Capture 4

COMP_OUTPUT_TIM3OCREFCLR COMP2 output connected to TIM3 OCREF Clear

COMP_OUTPUT_TIM4IC4 COMP2 output connected to TIM4 Input Capture 4

COMP_OUTPUT_TIM4OCREFCLR COMP2 output connected to TIM4 OCREF Clear

COMP_OUTPUT_TIM10IC1 COMP2 output connected to TIM10 Input Capture 1

COMP2 output is not connected to other peripherals

COMP_OUTPUTLEVEL_HIGH

COMP Private Constants

COMP1_START_DELAY_CPU_CYCLES

COMP2_START_DELAY_CPU_CYCLES

COMP_STATE_BIT_LOCK

COMP Private Macro

COMP_GET_EXTI_LINE Description:

Get the specified EXTI line for a comparator instance.

Parameters:

__INSTANCE__: specifies the COMP instance.

Return value:

 value: of

__COMP_CSR_CMPXOUT Description:

Select the COMP register CSR bit CMPxOUT corresponding to the selected COMP instance.

__COMP_IS_ENABLED

Parameters:

__HANDLE__: COMP handle

Return value:

Comparator: register CSR bit COMP_CSR_CMP1OUT or COMP_CSR_CMP2OUT

Description:

Verification of COMP state: enabled or disabled.

Parameters:

__HANDLE__: COMP handle

Return value:

SET: (COMP enabled) or RESET (COMP disabled)

COMP TriggerMode

COMP_TRIGGERMODE_NONE No External Interrupt trigger detection

132/654 DOCID026682 Rev 3

UM1816

COMP_TRIGGERMODE_IT_RISING

HAL COMP Generic Driver

External Interrupt Mode with Rising edge trigger detection

COMP_TRIGGERMODE_IT_FALLING

IS_COMP_TRIGGERMODE

COMP WindowMode

COMP_TRIGGERMODE_IT_RISING_FALLING External Interrupt Mode with

Rising/Falling edge trigger detection

External Interrupt Mode with Falling edge trigger detection

COMP_WINDOWMODE_DISABLE Window mode disabled: COMP1 non-inverting input is independant

COMP_WINDOWMODE_ENABLE Window mode enabled: COMP1 non-inverting input is no more accessible, even from ADC channel

VCOMP) (connected to COMP2 non-inverting input)

IS_COMP_WINDOWMODE

DOCID026682 Rev 3 133/654

HAL COMP Extension Driver

UM1816

7

7.1

7.2

7.2.1

HAL COMP Extension Driver

HAL COMP Extension Driver

COMPEx Firmware driver defines

COMPEx

COMPEx NonInvertingInput

COMP_NONINVERTINGINPUT_PB4

COMP_NONINVERTINGINPUT_PB5

COMP_NONINVERTINGINPUT_PB6

COMP_NONINVERTINGINPUT_PB7

COMP_NONINVERTINGINPUT_NONE

COMP_NONINVERTINGINPUT_PA0

COMP_NONINVERTINGINPUT_PA1

COMP_NONINVERTINGINPUT_PA2

COMP_NONINVERTINGINPUT_PA3

COMP_NONINVERTINGINPUT_PA4

COMP_NONINVERTINGINPUT_PA5

COMP_NONINVERTINGINPUT_PA6

COMP_NONINVERTINGINPUT_PA7

COMP_NONINVERTINGINPUT_PB0

COMP_NONINVERTINGINPUT_PB1

COMP_NONINVERTINGINPUT_PC0

I/O pin PB4 connection to COMP2 noninverting input

I/O pin PB5 connection to COMP2 noninverting input

I/O pin PB6 connection to COMP2 noninverting input

I/O pin PB7 connection to COMP2 noninverting input

In case of window mode: No I/O pin connection to COMP1 non-inverting input.

Instead, connection to COMP2 non-inverting input.

I/O pin PA0 connection to COMP1 noninverting input

I/O pin PA1 connection to COMP1 noninverting input

I/O pin PA2 connection to COMP1 noninverting input

I/O pin PA3 connection to COMP1 noninverting input

I/O pin PA4 connection to COMP1 noninverting input

I/O pin PA5 connection to COMP1 noninverting input

I/O pin PA5 connection to COMP1 noninverting input

I/O pin PA7 connection to COMP1 noninverting input

I/O pin PB0 connection to COMP1 noninverting input

I/O pin PB1 connection to COMP1 noninverting input

I/O pin PC0 connection to COMP1 noninverting input

134/654 DOCID026682 Rev 3

UM1816

COMP_NONINVERTINGINPUT_PC1

COMP_NONINVERTINGINPUT_PC2

COMP_NONINVERTINGINPUT_PC3

COMP_NONINVERTINGINPUT_PC4

COMP_NONINVERTINGINPUT_PC5

COMP_NONINVERTINGINPUT_PB12

COMP_NONINVERTINGINPUT_PB13

COMP_NONINVERTINGINPUT_PB14

COMP_NONINVERTINGINPUT_PB15

COMP_NONINVERTINGINPUT_PE7

COMP_NONINVERTINGINPUT_PE8

COMP_NONINVERTINGINPUT_PE9

COMP_NONINVERTINGINPUT_PE10

COMP_NONINVERTINGINPUT_PF6

COMP_NONINVERTINGINPUT_PF7

COMP_NONINVERTINGINPUT_PF8

COMP_NONINVERTINGINPUT_PF9

COMP_NONINVERTINGINPUT_PF10

HAL COMP Extension Driver

I/O pin PC1 connection to COMP1 noninverting input

I/O pin PC2 connection to COMP1 noninverting input

I/O pin PC3 connection to COMP1 noninverting input

I/O pin PC4 connection to COMP1 noninverting input

I/O pin PC5 connection to COMP1 noninverting input

I/O pin PB12 connection to COMP1 noninverting input

I/O pin PB13 connection to COMP1 noninverting input

I/O pin PB14 connection to COMP1 noninverting input

I/O pin PB15 connection to COMP1 noninverting input

I/O pin PE7 connection to COMP1 noninverting input

I/O pin PE8 connection to COMP1 noninverting input

I/O pin PE9 connection to COMP1 noninverting input

I/O pin PE10 connection to COMP1 noninverting input

I/O pin PF6 connection to COMP1 noninverting input

I/O pin PF7 connection to COMP1 noninverting input

I/O pin PF8 connection to COMP1 noninverting input

I/O pin PF9 connection to COMP1 noninverting input

I/O pin PF10 connection to COMP1 noninverting input

COMP_NONINVERTINGINPUT_OPAMP1 OPAMP1 output connection to COMP1 noninverting input

COMP_NONINVERTINGINPUT_OPAMP2 OPAMP2 output connection to COMP1 noninverting input

COMP_NONINVERTINGINPUT_OPAMP3 OPAMP3 output connection to COMP1 noninverting input

IS_COMP_NONINVERTINGINPUT

COMP Private Macro

DOCID026682 Rev 3 135/654

HAL COMP Extension Driver

__COMP_ROUTING_INTERFACE_TOBECONFIGURED Description:

UM1816

Specifies whether Routing

Interface (RI) needs to be configured for switches of comparator non-inverting input.

Parameters:

__HANDLE__: COMP handle.

Return value:

None.

136/654 DOCID026682 Rev 3

UM1816

HAL CORTEX Generic Driver

8

8.1

8.2

8.2.1

HAL CORTEX Generic Driver

HAL CORTEX Generic Driver

CORTEX Firmware driver registers structures

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

DOCID026682 Rev 3 137/654

HAL CORTEX Generic Driver

uint8_t MPU_Region_InitTypeDef::IsCacheable

UM1816

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

8.3.1

8.3.2

8.3.3

138/654

CORTEX Firmware driver API description

Initialization and de-initialization functions

This section provide 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()

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()

HAL_NVIC_SetPriorityGrouping

Function Name void HAL_NVIC_SetPriorityGrouping (uint32_t PriorityGroup)

Function Description Sets the priority grouping field (pre-emption 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 pre-emption priority 4 bits for subpriorityNVIC_PRIORITYGROUP_1: 1 bits for preemption priority 3 bits for subpriorityNVIC_PRIORITYGROUP_2: 2 bits for pre-emption priority 2 bits for subpriorityNVIC_PRIORITYGROUP_3: 3 bits for pre-emption priority 1 bits for subpriorityNVIC_PRIORITYGROUP_4: 4 bits for pre-emption

DOCID026682 Rev 3

UM1816

8.3.4

8.3.5

Return values

Notes

HAL CORTEX Generic Driver priority 0 bits for subpriority

None

When the NVIC_PriorityGroup_0 is selected, IRQ pre-emption 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

Return values

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 (stm32l1xx.h))

PreemptPriority: The pre-emption 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.

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 (stm32l1xx.h))

Return values

Notes

None

To configure interrupts priority correctly, the

NVIC_PriorityGroupConfig() function should be called before.

8.3.6

8.3.7

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

Return values

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 (stm32l1xxxx.h))

None

HAL_NVIC_SystemReset

Function Name void HAL_NVIC_SystemReset (void )

DOCID026682 Rev 3 139/654

HAL CORTEX Generic Driver

Function Description Initiates a system reset request to reset the MCU.

Return values

None

8.3.8

UM1816

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

Return values

TicksNumb: Specifies the ticks Number of ticks between two interrupts.

 status - 0 Function succeeded. 1 Function failed.

8.3.9 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

8.3.10 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)

8.3.11 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

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 (stm32l1xxxx.h))

PriorityGroup: the priority grouping bits length. This parameter can be one of the following values:

NVIC_PRIORITYGROUP_0: 0 bits for pre-emption priority 4 bits for subpriorityNVIC_PRIORITYGROUP_1: 1 bits for preemption priority 3 bits for subpriorityNVIC_PRIORITYGROUP_2: 2 bits for pre-emption priority 2 bits for subpriorityNVIC_PRIORITYGROUP_3: 3 bits for pre-emption priority 1 bits for subpriorityNVIC_PRIORITYGROUP_4: 4 bits for pre-emption priority 0 bits for subpriority

pPreemptPriority: Pointer on the Preemptive priority value

140/654 DOCID026682 Rev 3

UM1816

Return values

HAL CORTEX Generic Driver

(starting from 0).

pSubPriority: Pointer on the Subpriority value (starting from

0).

None

8.3.12 HAL_NVIC_SetPendingIRQ

Function Name void HAL_NVIC_SetPendingIRQ (IRQn_Type IRQn)

Function Description Sets Pending bit of an external interrupt.

Parameters

Return values

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 (stm32l1xxxx.h))

None

8.3.13 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

Return values

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 (stm32l1xxxx.h))

 status - 0 Interrupt status is not pending. 1 Interrupt status is pending.

8.3.14 HAL_NVIC_ClearPendingIRQ

Function Name

void HAL_NVIC_ClearPendingIRQ (IRQn_Type IRQn)

Function Description Clears the pending bit of an external interrupt.

Parameters

Return values

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 (stm32l1xxxx.h))

None

8.3.15 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

Return values

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 (stm32l1xxxx.h))

 status - 0 Interrupt status is not pending. 1 Interrupt status is

DOCID026682 Rev 3 141/654

HAL CORTEX Generic Driver

UM1816

pending.

8.3.16 HAL_SYSTICK_CLKSourceConfig

Function Name void HAL_SYSTICK_CLKSourceConfig (uint32_t CLKSource)

Function Description Configures the SysTick clock source.

Parameters

Return values

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.

None

8.3.17 HAL_SYSTICK_IRQHandler

Function Name void HAL_SYSTICK_IRQHandler (void )

Function Description This function handles SYSTICK interrupt request.

Return values

None

8.3.18 HAL_SYSTICK_Callback

Function Name void HAL_SYSTICK_Callback (void )

Function Description SYSTICK callback.

Return values

None

8.4

8.4.1

CORTEX Firmware driver defines

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

142/654 DOCID026682 Rev 3

UM1816

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

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

DOCID026682 Rev 3

HAL CORTEX Generic Driver

143/654

HAL CORTEX Generic Driver

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

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 Preemption Priority Group

IS_NVIC_PRIORITY_GROUP

IS_NVIC_PREEMPTION_PRIORITY

IS_NVIC_SUB_PRIORITY

IS_NVIC_DEVICE_IRQ

CORTEX Private Macros

IS_MPU_REGION_ENABLE

IS_MPU_INSTRUCTION_ACCESS

IS_MPU_ACCESS_SHAREABLE

IS_MPU_ACCESS_CACHEABLE

UM1816

144/654 DOCID026682 Rev 3

UM1816

HAL CORTEX Generic Driver

IS_MPU_ACCESS_BUFFERABLE

IS_MPU_TEX_LEVEL

IS_MPU_REGION_PERMISSION_ATTRIBUTE

IS_MPU_REGION_NUMBER

IS_MPU_REGION_SIZE

IS_MPU_SUB_REGION_DISABLE

CORTEX SysTick clock source

SYSTICK_CLKSOURCE_HCLK_DIV8

SYSTICK_CLKSOURCE_HCLK

CORTEX SysTick clock source

__HAL_CORTEX_SYSTICKCLK_CON

FIG

Description:

Configures the SysTick clock source.

Parameters:

__CLKSRC__: 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 value:

None

CORTEX SysTick clock source

IS_SYSTICK_CLK_SOURCE

DOCID026682 Rev 3 145/654

HAL CRC Generic Driver

UM1816

9

9.1

9.2

9.2.1

9.3

9.3.1

9.3.2

146/654

HAL CRC Generic Driver

HAL CRC Generic Driver

CRC Firmware driver registers structures

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

CRC Firmware driver API description

How to use this driver

The CRC HAL driver can be used as follows:

1. Enable CRC AHB clock using __HAL_RCC_CRC_CLK_ENABLE();

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

3. 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()

DOCID026682 Rev 3

UM1816

9.3.3

9.3.4

9.3.5

HAL CRC Generic Driver

HAL_CRC_MspDeInit()

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()

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()

HAL_CRC_Accumulate()

HAL_CRC_Calculate()

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

Return values

hcrc: pointer to a CRC_HandleTypeDef structure that contains the configuration information for CRC

HAL status

9.3.6 HAL_CRC_DeInit

Function Name

HAL_StatusTypeDef HAL_CRC_DeInit (CRC_HandleTypeDef *

hcrc)

Function Description DeInitializes the CRC peripheral.

Parameters

Return values

hcrc: pointer to a CRC_HandleTypeDef structure that contains the configuration information for CRC

HAL status

9.3.7 HAL_CRC_MspInit

Function Name void HAL_CRC_MspInit (CRC_HandleTypeDef * hcrc)

Function Description Initializes the CRC MSP.

Parameters

Return values

hcrc: pointer to a CRC_HandleTypeDef structure that contains the configuration information for CRC

None

DOCID026682 Rev 3 147/654

HAL CRC Generic Driver

9.3.8 HAL_CRC_MspDeInit

UM1816

Function Name void HAL_CRC_MspDeInit (CRC_HandleTypeDef * hcrc)

Function Description DeInitializes the CRC MSP.

Parameters

Return values

hcrc: pointer to a CRC_HandleTypeDef structure that contains the configuration information for CRC

None

9.3.9 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 (defined in word, 4 bytes)

Return values

32-bit CRC

9.3.10 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

Return values

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 (defined in word, 4 bytes)

32-bit CRC

9.3.11 HAL_CRC_GetState

Function Name

HAL_CRC_StateTypeDef HAL_CRC_GetState

(CRC_HandleTypeDef * hcrc)

Function Description Returns the CRC state.

Parameters

Return values

hcrc: pointer to a CRC_HandleTypeDef structure that contains the configuration information for CRC

HAL state

9.3.12 HAL_CRC_Accumulate

Function Name

uint32_t HAL_CRC_Accumulate (CRC_HandleTypeDef * hcrc,

148/654 DOCID026682 Rev 3

UM1816

HAL CRC Generic Driver

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

Return values

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 (defined in word, 4 bytes)

32-bit CRC

9.3.13 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

Return values

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 (defined in word, 4 bytes)

32-bit CRC

9.4

9.4.1

CRC Firmware driver defines

CRC

CRC Exported Macros

__HAL_CRC_RESET_HANDLE_STATE Description:

Reset CRC handle state.

Parameters:

__HANDLE__: CRC handle

__HAL_CRC_DR_RESET

Return value:

None

Description:

Resets CRC Data Register.

__HAL_CRC_SET_IDR

Parameters:

__HANDLE__: CRC handle

Return value:

None

Description:

Stores a 8-bit data in the Independent

DOCID026682 Rev 3 149/654

HAL CRC Generic Driver

__HAL_CRC_GET_IDR

UM1816

Data(ID) register.

Parameters:

__HANDLE__: CRC handle

__VALUE__: 8-bit value to be stored in the

ID register

Return value:

None

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

150/654 DOCID026682 Rev 3

UM1816

HAL CRYP Generic Driver

10 HAL CRYP Generic Driver

10.1 HAL CRYP Generic Driver

10.2 CRYP Firmware driver registers structures

10.2.1 CRYP_InitTypeDef

Data Fields

uint32_t DataType

uint8_t * pKey

uint8_t * pInitVect

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

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

10.2.2 CRYP_HandleTypeDef

Data Fields

AES_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

AES_TypeDef* CRYP_HandleTypeDef::Instance

Register base address

CRYP_InitTypeDef CRYP_HandleTypeDef::Init

CRYP required parameters

DOCID026682 Rev 3 151/654

HAL CRYP Generic Driver

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 outputed 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

UM1816

10.3 CRYP Firmware driver API description

10.3.1 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:

HAL_CRYP_Init()

HAL_CRYP_DeInit()

HAL_CRYP_MspInit()

HAL_CRYP_MspDeInit()

10.3.2 AES processing functions

This section provides functions allowing to:

Encrypt plaintext using AES algorithm in different chaining modes

Decrypt cyphertext using AES algorithm in different 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()

152/654 DOCID026682 Rev 3

UM1816

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.3.3 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_ErrorCallback()

HAL_CRYP_InCpltCallback()

HAL_CRYP_OutCpltCallback()

HAL CRYP Generic Driver

10.3.4 CRYP IRQ handler management

This section provides CRYP IRQ handler function.

This section contains the following APIs:

HAL_CRYP_IRQHandler()

10.3.5 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.3.6 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

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

HAL status

DOCID026682 Rev 3 153/654

HAL CRYP Generic Driver

10.3.7 HAL_CRYP_DeInit

Function Name

HAL_StatusTypeDef HAL_CRYP_DeInit

(CRYP_HandleTypeDef * hcryp)

UM1816

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

10.3.8 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

10.3.9 HAL_CRYP_MspDeInit

Function Name void HAL_CRYP_MspDeInit (CRYP_HandleTypeDef * hcryp)

Function Description DeInitializes CRYP MSP.

Parameters

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

None

10.3.10 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

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16.

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

Timeout: Specify Timeout value

HAL status

10.3.11 HAL_CRYP_AESCBC_Encrypt

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

154/654 DOCID026682 Rev 3

UM1816

Parameters

Return values

HAL CRYP Generic Driver encrypt pPlainData.

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16.

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

Timeout: Specify Timeout value

HAL status

10.3.12 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 (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16.

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

Timeout: Specify Timeout value

Return values

HAL status

10.3.13 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

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16.

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Timeout: Specify Timeout value

HAL status

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

DOCID026682 Rev 3 155/654

HAL CRYP Generic Driver

Parameters

Return values

UM1816

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16.

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Timeout: Specify Timeout value

HAL status

10.3.15 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

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16.

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Timeout: Specify Timeout value

HAL status

10.3.16 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

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16 bytes

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

HAL status

10.3.17 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

156/654 DOCID026682 Rev 3

UM1816

Return values

HAL CRYP Generic Driver contains the configuration information for CRYP module

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16 bytes

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

HAL status

10.3.18 HAL_CRYP_AESCTR_Encrypt_IT

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

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16 bytes

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

HAL status

10.3.19 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 (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16.

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Return values

HAL status

10.3.20 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 (aligned on u32)

DOCID026682 Rev 3 157/654

HAL CRYP Generic Driver

Return values

UM1816

Size: Length of the plaintext buffer, must be a multiple of 16

pPlainData: Pointer to the plaintext buffer (aligned on u32)

HAL status

10.3.21 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 (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Return values

HAL status

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

Parameters

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16 bytes

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

HAL status

10.3.23 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 (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16.

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

158/654 DOCID026682 Rev 3

UM1816

Return values

HAL status

HAL CRYP Generic Driver

10.3.24 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

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pPlainData: Pointer to the plaintext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16.

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

HAL status

10.3.25 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

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16 bytes

pPlainData: Pointer to the plaintext buffer (aligned on u32)

HAL status

10.3.26 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

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16 bytes

pPlainData: Pointer to the plaintext buffer (aligned on u32)

HAL status

DOCID026682 Rev 3 159/654

HAL CRYP Generic Driver

10.3.27 HAL_CRYP_AESCTR_Decrypt_DMA

Function Name

UM1816

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

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

pCypherData: Pointer to the cyphertext buffer (aligned on u32)

Size: Length of the plaintext buffer, must be a multiple of 16

pPlainData: Pointer to the plaintext buffer (aligned on u32)

HAL status

10.3.28 HAL_CRYP_ErrorCallback

Function Name

void HAL_CRYP_ErrorCallback (CRYP_HandleTypeDef *

hcryp)

Function Description CRYP error callback.

Parameters

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

None

10.3.29 HAL_CRYP_InCpltCallback

Function Name

void HAL_CRYP_InCpltCallback (CRYP_HandleTypeDef *

hcryp)

Function Description Input transfer completed callback.

Parameters

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

Return values

None

10.3.30 HAL_CRYP_OutCpltCallback

Function Name

void HAL_CRYP_OutCpltCallback (CRYP_HandleTypeDef *

hcryp)

Function Description Output transfer completed callback.

Parameters

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

None

10.3.31 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

160/654 DOCID026682 Rev 3

UM1816

Return values

HAL CRYP Generic Driver contains the configuration information for CRYP module

None

10.3.32 HAL_CRYP_GetState

Function Name

HAL_CRYP_STATETypeDef HAL_CRYP_GetState

(CRYP_HandleTypeDef * hcryp)

Function Description Returns the CRYP state.

Parameters

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

HAL state

10.4 CRYP Firmware driver defines

10.4.1 CRYP

AES Clear Flags

CRYP_CLEARFLAG_CCF Computation Complete Flag Clear

CRYP_CLEARFLAG_RDERR Read Error Clear

CRYP_CLEARFLAG_WRERR Write Error Clear

AES Flags

CRYP_FLAG_CCF Computation Complete Flag

CRYP_FLAG_RDERR Read Error Flag

CRYP_FLAG_WRERR Write Error Flag

AES Interrupts

CRYP_IT_CC

CRYP_IT_ERR

Computation Complete interrupt

Error interrupt

CRYP Algo Mode Direction

CRYP_CR_ALGOMODE_DIRECTION

CRYP_CR_ALGOMODE_AES_ECB_ENCRYPT

CRYP_CR_ALGOMODE_AES_ECB_KEYDERDECRYPT

CRYP_CR_ALGOMODE_AES_CBC_ENCRYPT

CRYP_CR_ALGOMODE_AES_CBC_KEYDERDECRYPT

CRYP_CR_ALGOMODE_AES_CTR_ENCRYPT

CRYP_CR_ALGOMODE_AES_CTR_DECRYPT

CRYP Data Type

CRYP_DATATYPE_32B

CRYP_DATATYPE_16B

CRYP_DATATYPE_8B

CRYP_DATATYPE_1B

DOCID026682 Rev 3 161/654

HAL CRYP Generic Driver

IS_CRYP_DATATYPE

__HAL_CRYP_GET_FLAG

UM1816

CRYP Exported Macros

__HAL_CRYP_RESET_HANDLE_STATE Description:

Reset CRYP handle state.

__HAL_CRYP_ENABLE

Parameters:

__HANDLE__: specifies the CRYP handle.

Return value:

None

Description:

Enable/Disable the CRYP peripheral.

Parameters:

__HANDLE__: specifies the CRYP handle.

Return value:

None

__HAL_CRYP_DISABLE

__HAL_CRYP_SET_MODE Description:

Set the algorithm mode: AES-ECB, AES-

CBC, AES-CTR, DES-ECB, DES-CBC,...

Parameters:

__HANDLE__: specifies the CRYP handle.

__MODE__: The algorithm mode.

Return value:

None

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_CCF : Computation

Complete Flag

CRYP_FLAG_RDERR : Read Error

Flag

CRYP_FLAG_WRERR : Write Error

Flag

162/654 DOCID026682 Rev 3

UM1816

__HAL_CRYP_CLEAR_FLAG

__HAL_CRYP_ENABLE_IT

__HAL_CRYP_DISABLE_IT

__HAL_CRYP_GET_IT_SOURCE

HAL CRYP Generic Driver

Return value:

The: new state of __FLAG__ (TRUE or

FALSE).

Description:

Clear the CRYP pending flag.

Parameters:

__HANDLE__: specifies the CRYP handle.

__FLAG__: specifies the flag to clear.

This parameter can be one of the following values:

CRYP_CLEARFLAG_CCF :

Computation Complete Clear Flag

CRYP_CLEARFLAG_RDERR :

Read Error Clear

CRYP_CLEARFLAG_WRERR :

Write Error Clear

Return value:

None

Description:

Enable the CRYP interrupt.

Parameters:

__HANDLE__: specifies the CRYP handle.

__INTERRUPT__: CRYP Interrupt.

Return value:

None

Description:

Disable the CRYP interrupt.

Parameters:

__HANDLE__: specifies the CRYP handle.

__INTERRUPT__: CRYP interrupt.

Return value:

None

Description:

Checks if the specified CRYP interrupt source is enabled or disabled.

Parameters:

__HANDLE__: specifies the CRYP handle.

__INTERRUPT__: CRYP interrupt source

DOCID026682 Rev 3 163/654

HAL CRYP Generic Driver

__HAL_CRYP_CLEAR_IT

CRYP Private Defines

CRYP_ALGO_CHAIN_MASK

UM1816

to check This parameter can be one of the following values:

CRYP_IT_CC : Computation

Complete interrupt

CRYP_IT_ERR : Error interrupt

(used for RDERR and WRERR)

Return value:

State: of interruption (SET or RESET)

Description:

Clear the CRYP pending IT.

Parameters:

__HANDLE__: specifies the CRYP handle.

__IT__: specifies the IT to clear. This parameter can be one of the following values:

CRYP_CLEARFLAG_CCF :

Computation Complete Clear Flag

CRYP_CLEARFLAG_RDERR :

Read Error Clear

CRYP_CLEARFLAG_WRERR :

Write Error Clear

Return value:

None

164/654 DOCID026682 Rev 3

UM1816

HAL CRYP Extension Driver

11 HAL CRYP Extension Driver

11.1 HAL CRYP Extension Driver

11.2 CRYPEx Firmware driver API description

11.2.1 Extended features functions

This section provides callback functions:

Computation completed.

This section contains the following APIs:

HAL_CRYPEx_ComputationCpltCallback()

11.2.2 HAL_CRYPEx_ComputationCpltCallback

Function Name

void HAL_CRYPEx_ComputationCpltCallback

(CRYP_HandleTypeDef * hcryp)

Function Description Computation completed callbacks.

Parameters

Return values

hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module

None

11.3 CRYPEx Firmware driver defines

11.3.1 CRYPEx

DOCID026682 Rev 3 165/654

HAL DAC Generic Driver

UM1816

12 HAL DAC Generic Driver

12.1 HAL DAC Generic Driver

12.2 DAC Firmware driver registers structures

12.2.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.2.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

166/654 DOCID026682 Rev 3

UM1816

HAL DAC Generic Driver

12.3 DAC Firmware driver API description

12.3.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. DAC channel1 with DAC_OUT1 (PA4) as output

2. 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. External event: EXTI Line 9 (any GPIOx_PIN_9) using DAC_TRIGGER_EXT_IT9.

The used pin (GPIOx_PIN_9) must be configured in input mode.

2. Timers TRGO: TIM2, TIM4, TIM6, TIM7, TIM9 (DAC_Trigger_T2_TRGO,

DAC_Trigger_T4_TRGO...)

3. 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 connect feature

Each DAC channel can be connected internally. To connect, use sConfig.DAC_ConnectOnChipPeripheral = DAC_CHIPCONNECT_ENABLE;

GPIO configurations guidelines

When a DAC channel is used (ex channel1 on PA4) and the other is not (ex channel1 on

PA5 is configured in Analog and disabled). Channel1 may disturb channel2 as coupling effect. Note that there is no coupling on channel2 as soon as channel2 is turned on.

Coupling on adjacent channel could be avoided as follows: when unused PA5 is configured as INPUT PULL-UP or DOWN. PA5 is configured in ANALOG just before it is turned on.

DAC wave generation feature

Both DAC channels can be used to generate

1. Noise wave using HAL_DACEx_NoiseWaveGenerate()

DOCID026682 Rev 3 167/654

HAL DAC Generic Driver

2. Triangle wave using HAL_DACEx_TriangleWaveGenerate()

DAC data format

The DAC data format can be:

1. 8-bit right alignment using DAC_ALIGN_8B_R

2. 12-bit left alignment using DAC_ALIGN_12B_L

3. 12-bit right alignment using DAC_ALIGN_12B_R

UM1816

DAC data value to voltage correspondance

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. DAC channel1 : mapped on DMA1 channel2 which must be already configured

2. DAC channel2 : mapped on DMA1 channel3 which must be already configured For

Dual mode and specific signal (Triangle and noise) generation please refer to

Extension Features Driver description

12.3.2 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

168/654 DOCID026682 Rev 3

UM1816

HAL DAC Generic Driver

At the middle of data transfer HAL_DACEx_ConvHalfCpltCallbackCh1()or

HAL_DACEx_ConvHalfCpltCallbackCh2() function is executed and user can add his own code by customization of function pointer HAL_DAC_ConvHalfCpltCallbackCh1 or HAL_DAC_ConvHalfCpltCallbackCh2

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() or

HAL_DACEx_ErrorCallbackCh2() function is executed and user can add his own code by customization of function pointer HAL_DAC_ErrorCallbackCh1 or

HAL_DACEx_ErrorCallbackCh2

For STM32F100x devices with specific feature: DMA underrun. In case of DMA underrun, DAC interruption triggers and execute internal function

HAL_DAC_IRQHandler. HAL_DAC_DMAUnderrunCallbackCh1()or

HAL_DACEx_DMAUnderrunCallbackCh2() function is executed and user can add his own code by customization of function pointer HAL_DAC_DMAUnderrunCallbackCh1 or HAL_DACEx_DMAUnderrunCallbackCh2 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

__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.3.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.3.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.

DOCID026682 Rev 3 169/654

HAL DAC Generic Driver

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()

HAL_DAC_SetValue()

HAL_DAC_ConfigChannel()

HAL_DAC_GetState()

HAL_DAC_GetError()

12.3.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()

12.3.6 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()

UM1816

12.3.7 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

12.3.8 HAL_DAC_DeInit

Function Name

HAL_StatusTypeDef HAL_DAC_DeInit (DAC_HandleTypeDef *

hdac)

170/654 DOCID026682 Rev 3

UM1816

HAL DAC Generic Driver

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

12.3.9 HAL_DAC_MspInit

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

12.3.10 HAL_DAC_MspDeInit

Function Name void HAL_DAC_MspDeInit (DAC_HandleTypeDef * hdac)

Function Description DeInitializes the DAC MSP.

Parameters

Return values

hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC.

None

12.3.11 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 selectedDAC_CHANNEL_2: DAC Channel2 selected

Return values

HAL status

12.3.12 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

Return values

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 selectedDAC_CHANNEL_2: DAC Channel2 selected

HAL status

DOCID026682 Rev 3 171/654

HAL DAC Generic Driver

12.3.13 HAL_DAC_Start_DMA

Function Name

UM1816

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

Return values

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 selectedDAC_CHANNEL_2: DAC Channel2 selected

pData: The destination peripheral Buffer address.

Length: The length of data to be transferred from memory to

DAC peripheral

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 selectedDAC_ALIGN_12B_L: 12bit left data alignment selectedDAC_ALIGN_12B_R: 12bit right data alignment selected

HAL status

12.3.14 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

Return values

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 selectedDAC_CHANNEL_2: DAC Channel2 selected

HAL status

12.3.15 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 selectedDAC_CHANNEL_2: DAC Channel2 selected

Return values

The selected DAC channel data output value.

12.3.16 HAL_DAC_IRQHandler

172/654 DOCID026682 Rev 3

UM1816

Function Name

HAL DAC Generic Driver

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

12.3.17 HAL_DAC_ConvCpltCallbackCh1

Function Name

void HAL_DAC_ConvCpltCallbackCh1 (DAC_HandleTypeDef *

hdac)

Function Description Conversion complete callback in non blocking mode for Channel1.

Parameters

Return values

hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC.

None

12.3.18 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

Return values

hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC.

None

12.3.19 HAL_DAC_ErrorCallbackCh1

Function Name

void HAL_DAC_ErrorCallbackCh1 (DAC_HandleTypeDef *

hdac)

Function Description Error DAC callback for Channel1.

Parameters

Return values

hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC.

None

12.3.20 HAL_DAC_DMAUnderrunCallbackCh1

Function Name

void HAL_DAC_DMAUnderrunCallbackCh1

(DAC_HandleTypeDef * hdac)

Function Description DMA underrun DAC callback for channel1.

Parameters

Return values

hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC.

None

12.3.21 HAL_DAC_SetValue

Function Name

HAL_StatusTypeDef HAL_DAC_SetValue

(DAC_HandleTypeDef * hdac, uint32_t Channel, uint32_t

DOCID026682 Rev 3 173/654

HAL DAC Generic Driver

UM1816

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 selectedDAC_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 selectedDAC_ALIGN_12B_L: 12bit left data alignment selectedDAC_ALIGN_12B_R: 12bit right data alignment selected

Data: Data to be loaded in the selected data holding register.

Return values

HAL status

12.3.22 HAL_DAC_ConfigChannel

Function Name

HAL_StatusTypeDef HAL_DAC_ConfigChannel

(DAC_HandleTypeDef * hdac, DAC_ChannelConfTypeDef *

sConfig, uint32_t Channel)

Function Description Configures the selected DAC channel.

Parameters

Return values

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 selectedDAC_CHANNEL_2: DAC Channel2 selected

HAL status

12.3.23 HAL_DAC_GetState

Function Name

HAL_DAC_StateTypeDef HAL_DAC_GetState

(DAC_HandleTypeDef * hdac)

Function Description return the DAC state

Parameters

Return values

hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC.

HAL state

12.3.24 HAL_DAC_GetError

Function Name uint32_t HAL_DAC_GetError (DAC_HandleTypeDef * hdac)

Function Description Return the DAC error code.

Parameters

Return values

hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC.

DAC Error Code

174/654 DOCID026682 Rev 3

UM1816

12.3.25 HAL_DAC_ConfigChannel

Function Name

HAL DAC Generic Driver

HAL_StatusTypeDef HAL_DAC_ConfigChannel

(DAC_HandleTypeDef * hdac, DAC_ChannelConfTypeDef *

sConfig, uint32_t Channel)

Function Description Configures the selected DAC channel.

Parameters

Return values

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 selectedDAC_CHANNEL_2: DAC Channel2 selected

HAL status

12.3.26 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

Return values

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 selectedDAC_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 selectedDAC_ALIGN_12B_L: 12bit left data alignment selectedDAC_ALIGN_12B_R: 12bit right data alignment selected

Data: Data to be loaded in the selected data holding register.

HAL status

12.3.27 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

12.3.28 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

DOCID026682 Rev 3 175/654

HAL DAC Generic Driver

Return values

UM1816

contains the configuration information for the specified DAC.

DAC Error Code

12.4 DAC Firmware driver defines

12.4.1 DAC

DAC Channel selection

DAC_CHANNEL_1

DAC_CHANNEL_2

DAC data alignement

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 DMA underrun error

HAL_DAC_ERROR_DMAUNDERRUNCH2 DAC channel2 DMA underrun error

HAL_DAC_ERROR_DMA

DAC Exported Macros

DMA error

__HAL_DAC_RESET_HANDLE_STATE Description:

Reset DAC handle state.

Parameters:

__HANDLE__: specifies the DAC handle.

Return value:

None

__HAL_DAC_ENABLE

__HAL_DAC_DISABLE

Description:

Enable the DAC channel.

Parameters:

__HANDLE__: specifies the DAC handle.

__DAC_Channel__: specifies the DAC channel

Return value:

None

Description:

Disable the DAC channel.

Parameters:

__HANDLE__: specifies the DAC handle

__DAC_Channel__: specifies the DAC

176/654 DOCID026682 Rev 3

UM1816

__HAL_DAC_ENABLE_IT

__HAL_DAC_DISABLE_IT

__HAL_DAC_GET_IT_SOURCE

HAL DAC Generic Driver channel.

Return value:

None

Description:

Enable the DAC interrupt.

Parameters:

__HANDLE__: specifies the DAC handle

__INTERRUPT__: specifies the DAC interrupt. 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:

None

Description:

Disable the DAC interrupt.

Parameters:

__HANDLE__: specifies the DAC handle

__INTERRUPT__: specifies the DAC interrupt. 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:

None

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)

DOCID026682 Rev 3 177/654

HAL DAC Generic Driver

__HAL_DAC_GET_FLAG

__HAL_DAC_CLEAR_FLAG

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 Private Macros

IS_DAC_TRIGGER

IS_DAC_OUTPUT_BUFFER_STATE

IS_DAC_CHANNEL

IS_DAC_ALIGN

IS_DAC_DATA

UM1816

Description:

Get the selected DAC's flag status.

Parameters:

__HANDLE__: specifies the DAC handle.

__FLAG__: specifies the DAC flag to get.

This parameter can be any combination of the following values:

DAC_FLAG_DMAUDR1: DAC channel 1 DMA underrun flag

DAC_FLAG_DMAUDR2: DAC channel 2 DMA underrun flag

Return value:

None

Description:

Clear the DAC's flag.

Parameters:

__HANDLE__: specifies the DAC handle.

__FLAG__: specifies the DAC flag to clear.

This parameter can be any combination of the following values:

DAC_FLAG_DMAUDR1: DAC channel 1 DMA underrun flag

DAC_FLAG_DMAUDR2: DAC channel 2 DMA underrun flag

Return value:

None

178/654 DOCID026682 Rev 3

UM1816

HAL DAC Generic Driver

DAC_DHR12R1_ALIGNMENT

DAC_DHR12R2_ALIGNMENT

DAC_DHR12RD_ALIGNMENT

DAC trigger selection

DAC_TRIGGER_NONE

DAC_TRIGGER_T6_TRGO

Conversion is automatic once the DAC1_DHRxxxx register has been loaded, and not by external trigger

TIM6 TRGO selected as external conversion trigger for

DAC channel

DAC_TRIGGER_T7_TRGO

DAC_TRIGGER_T9_TRGO

DAC_TRIGGER_T2_TRGO

DAC_TRIGGER_T4_TRGO

TIM7 TRGO selected as external conversion trigger for

DAC channel

TIM9 TRGO selected as external conversion trigger for

DAC channel

TIM2 TRGO selected as external conversion trigger for

DAC channel

TIM4 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

DOCID026682 Rev 3 179/654

HAL DAC Extension Driver

UM1816

13 HAL DAC Extension Driver

13.1 HAL DAC Extension Driver

13.2 DACEx Firmware driver API description

13.2.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.2.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.2.3 HAL_DACEx_DualGetValue

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.

13.2.4 HAL_DACEx_TriangleWaveGenerate

Function Name

HAL_StatusTypeDef HAL_DACEx_TriangleWaveGenerate

(DAC_HandleTypeDef * hdac, uint32_t Channel, uint32_t

180/654 DOCID026682 Rev 3

UM1816

HAL DAC Extension Driver

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 1DAC_TRIANGLEAMPLITUDE_3: Select max triangle amplitude of 3DAC_TRIANGLEAMPLITUDE_7:

Select max triangle amplitude of

7DAC_TRIANGLEAMPLITUDE_15: Select max triangle amplitude of 15DAC_TRIANGLEAMPLITUDE_31: Select max triangle amplitude of 31DAC_TRIANGLEAMPLITUDE_63:

Select max triangle amplitude of

63DAC_TRIANGLEAMPLITUDE_127: Select max triangle amplitude of 127DAC_TRIANGLEAMPLITUDE_255: Select max triangle amplitude of

255DAC_TRIANGLEAMPLITUDE_511: Select max triangle amplitude of 511DAC_TRIANGLEAMPLITUDE_1023: Select max triangle amplitude of

1023DAC_TRIANGLEAMPLITUDE_2047: Select max triangle amplitude of 2047DAC_TRIANGLEAMPLITUDE_4095: Select max triangle amplitude of 4095

Return values

HAL status

13.2.5 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 values: DAC_LFSRUNMASK_BIT0: Unmask DAC channel

LFSR bit0 for noise wave generationDAC_LFSRUNMASK_BITS1_0: Unmask DAC channel LFSR bit[1:0] for noise wave generationDAC_LFSRUNMASK_BITS2_0: Unmask DAC channel LFSR bit[2:0] for noise wave generationDAC_LFSRUNMASK_BITS3_0: Unmask DAC channel LFSR bit[3:0] for noise wave generationDAC_LFSRUNMASK_BITS4_0: Unmask DAC channel LFSR bit[4:0] for noise wave generationDAC_LFSRUNMASK_BITS5_0: Unmask DAC

DOCID026682 Rev 3 181/654

HAL DAC Extension Driver

Return values

UM1816

channel LFSR bit[5:0] for noise wave generationDAC_LFSRUNMASK_BITS6_0: Unmask DAC channel LFSR bit[6:0] for noise wave generationDAC_LFSRUNMASK_BITS7_0: Unmask DAC channel LFSR bit[7:0] for noise wave generationDAC_LFSRUNMASK_BITS8_0: Unmask DAC channel LFSR bit[8:0] for noise wave generationDAC_LFSRUNMASK_BITS9_0: Unmask DAC channel LFSR bit[9:0] for noise wave generationDAC_LFSRUNMASK_BITS10_0: Unmask DAC channel LFSR bit[10:0] for noise wave generationDAC_LFSRUNMASK_BITS11_0: Unmask DAC channel LFSR bit[11:0] for noise wave generation

HAL status

13.2.6 HAL_DACEx_DualSetValue

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

Return values

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.

HAL status

Notes

In dual mode, a unique register access is required to write in both DAC channels at the same time.

13.2.7 HAL_DACEx_ConvCpltCallbackCh2

Function Name

void HAL_DACEx_ConvCpltCallbackCh2

(DAC_HandleTypeDef * hdac)

Function Description Conversion complete callback in non blocking mode for Channel2.

Parameters

Return values

hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC.

None

13.2.8 HAL_DACEx_ConvHalfCpltCallbackCh2

Function Name

void HAL_DACEx_ConvHalfCpltCallbackCh2

(DAC_HandleTypeDef * hdac)

182/654 DOCID026682 Rev 3

UM1816

HAL DAC Extension Driver

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

13.2.9 HAL_DACEx_ErrorCallbackCh2

Function Name

void HAL_DACEx_ErrorCallbackCh2 (DAC_HandleTypeDef *

hdac)

Function Description Error DAC callback for Channel2.

Parameters

Return values

hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC.

None

13.2.10 HAL_DACEx_DMAUnderrunCallbackCh2

Function Name

void HAL_DACEx_DMAUnderrunCallbackCh2

(DAC_HandleTypeDef * hdac)

Function Description DMA underrun DAC callback for channel2.

Parameters

Return values

hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC.

None

13.3 DACEx Firmware driver defines

13.3.1 DACEx

DACEx lfsrunmask triangleamplitude

DAC_LFSRUNMASK_BIT0

DAC_LFSRUNMASK_BITS1_0

DAC_LFSRUNMASK_BITS2_0

DAC_LFSRUNMASK_BITS3_0

DAC_LFSRUNMASK_BITS4_0

DAC_LFSRUNMASK_BITS5_0

DAC_LFSRUNMASK_BITS6_0

DAC_LFSRUNMASK_BITS7_0

Unmask DAC channel LFSR bit0 for noise wave generation

Unmask DAC channel LFSR bit[1:0] for noise wave generation

Unmask DAC channel LFSR bit[2:0] for noise wave generation

Unmask DAC channel LFSR bit[3:0] for noise wave generation

Unmask DAC channel LFSR bit[4:0] for noise wave generation

Unmask DAC channel LFSR bit[5:0] for noise wave generation

Unmask DAC channel LFSR bit[6:0] for noise wave generation

Unmask DAC channel LFSR bit[7:0] for noise wave generation

DOCID026682 Rev 3 183/654

HAL DAC Extension Driver

DAC_LFSRUNMASK_BITS8_0

DAC_LFSRUNMASK_BITS9_0

DAC_LFSRUNMASK_BITS10_0

DAC_LFSRUNMASK_BITS11_0

DAC_TRIANGLEAMPLITUDE_1

DAC_TRIANGLEAMPLITUDE_3

DAC_TRIANGLEAMPLITUDE_7

DAC_TRIANGLEAMPLITUDE_15

DAC_TRIANGLEAMPLITUDE_31

DAC_TRIANGLEAMPLITUDE_63

DAC_TRIANGLEAMPLITUDE_127

UM1816

Unmask DAC channel LFSR bit[8:0] for noise wave generation

Unmask DAC channel LFSR bit[9:0] for noise wave generation

Unmask DAC channel LFSR bit[10:0] for noise wave generation

Unmask DAC channel LFSR bit[11:0] for noise wave generation

Select max triangle amplitude of 1

Select max triangle amplitude of 3

Select max triangle amplitude of 7

Select max triangle amplitude of 15

Select max triangle amplitude of 31

DAC_TRIANGLEAMPLITUDE_255

DAC_TRIANGLEAMPLITUDE_511

DAC_TRIANGLEAMPLITUDE_1023

DAC_TRIANGLEAMPLITUDE_2047

Select max triangle amplitude of 63

Select max triangle amplitude of

127

Select max triangle amplitude of

255

Select max triangle amplitude of

511

Select max triangle amplitude of

1023

Select max triangle amplitude of

2047

DAC_TRIANGLEAMPLITUDE_4095

IS_DAC_LFSR_UNMASK_TRIANGLE_AMPLITUDE

DACEx wave generation

DAC_WAVE_NOISE

Select max triangle amplitude of

4095

DAC_WAVE_TRIANGLE

184/654 DOCID026682 Rev 3

UM1816

HAL DMA Generic Driver

14 HAL DMA Generic Driver

14.1 HAL DMA Generic Driver

14.2 DMA Firmware driver registers structures

14.2.1 DMA_InitTypeDef

Data Fields

uint32_t Direction

uint32_t PeriphInc

uint32_t MemInc

uint32_t PeriphDataAlignment

uint32_t MemDataAlignment

uint32_t Mode

uint32_t Priority

Field Documentation

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 Channelx. 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 Channel

uint32_t DMA_InitTypeDef::Priority

Specifies the software priority for the DMAy Channelx. This parameter can be a value

of

DMA_Priority_level

14.2.2 __DMA_HandleTypeDef

DOCID026682 Rev 3 185/654

HAL DMA Generic Driver

Data Fields

DMA_Channel_TypeDef * Instance

DMA_InitTypeDef Init

HAL_LockTypeDef Lock

HAL_DMA_StateTypeDef State

void * Parent

void(* XferCpltCallback

void(* XferHalfCpltCallback

void(* XferErrorCallback

__IO uint32_t ErrorCode

UM1816

Field Documentation

DMA_Channel_TypeDef* __DMA_HandleTypeDef::Instance

Register base address

DMA_InitTypeDef __DMA_HandleTypeDef::Init

DMA communication parameters

HAL_LockTypeDef __DMA_HandleTypeDef::Lock

DMA locking object

HAL_DMA_StateTypeDef __DMA_HandleTypeDef::State

DMA transfer state

void* __DMA_HandleTypeDef::Parent

Parent object state

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::XferErrorCallback)(struct

__DMA_HandleTypeDef *hdma)

DMA transfer error callback

__IO uint32_t __DMA_HandleTypeDef::ErrorCode

DMA Error code

14.3 DMA Firmware driver API description

14.3.1 How to use this driver

1. Enable and configure the peripheral to be connected to the DMA Channel (except for internal SRAM / FLASH memories: no initialization is necessary) please refer to

Reference manual for connection between peripherals and DMA requests.

2. For a given Channel, program the required configuration through the following parameters: Transfer Direction, Source and Destination data formats, Circular or

Normal mode, Channel Priority level, Source and Destination Increment mode, using

HAL_DMA_Init() function.

3. Use HAL_DMA_GetState() function to return the DMA state and

HAL_DMA_GetError() in case of error detection.

4. Use HAL_DMA_Abort() function to abort the current transfer In Memory-to-Memory transfer mode, Circular mode is not allowed.

186/654 DOCID026682 Rev 3

UM1816

HAL DMA Generic Driver

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.

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_DMAy_Channelx_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).

DMA HAL driver macros list

Below the list of most used macros in DMA HAL driver.

__HAL_DMA_ENABLE: Enable the specified DMA Channel.

__HAL_DMA_DISABLE: Disable the specified DMA Channel.

__HAL_DMA_GET_FLAG: Get the DMA Channel pending flags.

__HAL_DMA_CLEAR_FLAG: Clear the DMA Channel pending flags.

__HAL_DMA_ENABLE_IT: Enable the specified DMA Channel interrupts.

__HAL_DMA_DISABLE_IT: Disable the specified DMA Channel interrupts.

__HAL_DMA_GET_IT_SOURCE: Check whether the specified DMA Channel interrupt has occurred or not.

You can refer to the DMA HAL driver header file for more useful macros

14.3.2 Initialization and de-initialization functions

This section provides functions allowing to initialize the DMA Channel source and destination addresses, incrementation and data sizes, transfer direction, circular/normal mode selection, memory-to-memory mode selection and Channel 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()

14.3.3 IO operation functions

This section provides functions allowing to:

DOCID026682 Rev 3 187/654

HAL DMA Generic Driver

UM1816

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_PollForTransfer()

HAL_DMA_IRQHandler()

14.3.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()

14.3.5 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

Return values

hdma: Pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA

Channel.

HAL status

14.3.6 HAL_DMA_DeInit

Function Name

HAL_StatusTypeDef HAL_DMA_DeInit (DMA_HandleTypeDef *

hdma)

Function Description DeInitializes the DMA peripheral.

Parameters

Return values

hdma: pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA

Channel.

HAL status

14.3.7 HAL_DMA_Start

Function Name

HAL_StatusTypeDef HAL_DMA_Start (DMA_HandleTypeDef * hdma, uint32_t SrcAddress, uint32_t DstAddress, uint32_t

DataLength)

188/654 DOCID026682 Rev 3

UM1816

HAL DMA Generic Driver

Function Description Starts the DMA Transfer.

Parameters

Return values

hdma: : pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA

Channel.

SrcAddress: The source memory Buffer address

DstAddress: The destination memory Buffer address

DataLength: The length of data to be transferred from source to destination

HAL status

14.3.8 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 Start the DMA Transfer with interrupt enabled.

Parameters

Return values

hdma: pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA

Channel.

SrcAddress: The source memory Buffer address

DstAddress: The destination memory Buffer address

DataLength: The length of data to be transferred from source to destination

HAL status

14.3.9 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

Channel.

Return values

Notes

HAL status

After disabling a DMA Channel, a check for wait until the DMA

Channel is effectively disabled is added. If a Channel is disabled while a data transfer is ongoing, the current data will be transferred and the Channel will be effectively disabled only after the transfer of this single data is finished.

14.3.10 HAL_DMA_PollForTransfer

Function Name

HAL_StatusTypeDef HAL_DMA_PollForTransfer

(DMA_HandleTypeDef * hdma, uint32_t 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

Channel.

DOCID026682 Rev 3 189/654

HAL DMA Generic Driver

Return values

CompleteLevel: Specifies the DMA level complete.

Timeout: Timeout duration.

UM1816

HAL status

14.3.11 HAL_DMA_IRQHandler

Function Name void HAL_DMA_IRQHandler (DMA_HandleTypeDef * hdma)

Function Description Handles DMA interrupt request.

Parameters

Return values

hdma: pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA

Channel.

None

14.3.12 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

Channel.

Return values

HAL state

14.3.13 HAL_DMA_GetError

Function Name

uint32_t HAL_DMA_GetError (DMA_HandleTypeDef * hdma)

Function Description Return the DMA error code.

Parameters

Return values

hdma: : pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA

Channel.

DMA Error Code

14.4 DMA Firmware driver defines

14.4.1 DMA

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_TIMEOUT Timeout error

DMA Exported Macros

190/654 DOCID026682 Rev 3

UM1816

HAL DMA Generic Driver

__HAL_DMA_RESET_HANDLE_STATE Description:

Reset DMA handle state.

__HAL_DMA_ENABLE

Parameters:

__HANDLE__: DMA handle.

Return value:

None

Description:

Enable the specified DMA Channel.

__HAL_DMA_DISABLE

__HAL_DMA_ENABLE_IT

Parameters:

__HANDLE__: DMA handle

Return value:

None.

Description:

Disable the specified DMA Channel.

Parameters:

__HANDLE__: DMA handle

Return value:

None.

Description:

Enables the specified DMA Channel interrupts.

__HAL_DMA_DISABLE_IT

Parameters:

__HANDLE__: DMA handle

__INTERRUPT__: specifies the DMA interrupt sources to be enabled or disabled. This parameter can be any combination of the following values:

DMA_IT_TC: Transfer complete interrupt mask

DMA_IT_HT: Half transfer complete interrupt mask

DMA_IT_TE: Transfer error interrupt mask

Return value:

None

Description:

Disables the specified DMA Channel interrupts.

Parameters:

__HANDLE__: DMA handle

DOCID026682 Rev 3 191/654

HAL DMA Generic Driver

__HAL_DMA_GET_IT_SOURCE

192/654

DMA flag definitions

DMA_FLAG_GL1

DMA_FLAG_TC1

DMA_FLAG_HT1

DMA_FLAG_TE1

DMA_FLAG_GL2

DMA_FLAG_TC2

DMA_FLAG_HT2

DMA_FLAG_TE2

DMA_FLAG_GL3

DMA_FLAG_TC3

DMA_FLAG_HT3

DMA_FLAG_TE3

DMA_FLAG_GL4

DOCID026682 Rev 3

UM1816

__INTERRUPT__: specifies the DMA interrupt sources to be enabled or disabled. This parameter can be any combination of the following values:

DMA_IT_TC: Transfer complete interrupt mask

DMA_IT_HT: Half transfer complete interrupt mask

DMA_IT_TE: Transfer error interrupt mask

Return value:

None

Description:

Checks whether the specified DMA

Channel interrupt is enabled or disabled.

Parameters:

__HANDLE__: DMA handle

__INTERRUPT__: specifies the DMA interrupt source to check. This parameter can be one of the following values:

DMA_IT_TC: Transfer complete interrupt mask

DMA_IT_HT: Half transfer complete interrupt mask

DMA_IT_TE: Transfer error interrupt mask

Return value:

The: state of DMA_IT (SET or RESET).

UM1816

HAL DMA Generic Driver

DMA_FLAG_TC4

DMA_FLAG_HT4

DMA_FLAG_TE4

DMA_FLAG_GL5

DMA_FLAG_TC5

DMA_FLAG_HT5

DMA_FLAG_TE5

DMA_FLAG_GL6

DMA_FLAG_TC6

DMA_FLAG_HT6

DMA_FLAG_TE6

DMA_FLAG_GL7

DMA_FLAG_TC7

DMA_FLAG_HT7

DMA_FLAG_TE7

DMA interrupt enable definitions

DMA_IT_TC

DMA_IT_HT

DMA_IT_TE

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

DOCID026682 Rev 3 193/654

HAL DMA Generic Driver

DMA_PRIORITY_LOW Priority level : Low

DMA_PRIORITY_MEDIUM

DMA_PRIORITY_HIGH

Priority level : Medium

Priority level : High

DMA_PRIORITY_VERY_HIGH Priority level : Very_High

DMA Private Constants

HAL_TIMEOUT_DMA_ABORT

DMA Private Macros

IS_DMA_BUFFER_SIZE

IS_DMA_DIRECTION

IS_DMA_PERIPHERAL_INC_STATE

IS_DMA_MEMORY_INC_STATE

IS_DMA_PERIPHERAL_DATA_SIZE

IS_DMA_MEMORY_DATA_SIZE

IS_DMA_MODE

IS_DMA_PRIORITY

UM1816

194/654 DOCID026682 Rev 3

UM1816

HAL DMA Extension Driver

15 HAL DMA Extension Driver

15.1 HAL DMA Extension Driver

15.2 DMAEx Firmware driver defines

15.2.1 DMAEx

DMA Extended Exported Macros

__HAL_DMA_GET_TC_FLAG_INDEX Description:

Returns the current DMA Channel transfer complete flag.

Parameters:

__HANDLE__: DMA handle

Return value:

The: specified transfer complete flag index.

__HAL_DMA_GET_HT_FLAG_INDEX Description:

Returns the current DMA Channel half transfer complete flag.

Parameters:

__HANDLE__: DMA handle

Return value:

The: specified half transfer complete flag index.

__HAL_DMA_GET_TE_FLAG_INDEX Description:

Returns the current DMA Channel transfer error flag.

__HAL_DMA_GET_FLAG

Parameters:

__HANDLE__: DMA handle

Return value:

The: specified transfer error flag index.

Description:

Get the DMA Channel pending flags.

Parameters:

__HANDLE__: DMA handle

__FLAG__: Get the specified flag. This parameter can be any combination of the following values:

DMA_FLAG_TCx: Transfer complete flag

DOCID026682 Rev 3 195/654

HAL DMA Extension Driver

__HAL_DMA_CLEAR_FLAG

UM1816

DMA_FLAG_HTx: Half transfer complete flag

DMA_FLAG_TEx: Transfer error flag

Where x can be 1_7 or 1_5 to select the

DMA Channel flag.

Return value:

The: state of FLAG (SET or RESET).

Description:

Clears the DMA Channel pending flags.

Parameters:

__HANDLE__: DMA handle

__FLAG__: specifies the flag to clear. This parameter can be any combination of the following values:

DMA_FLAG_TCx: Transfer complete flag

DMA_FLAG_HTx: Half transfer complete flag

DMA_FLAG_TEx: Transfer error flag

Where x can be 1_7 or 1_5 to select the

DMA Channel flag.

Return value:

None

196/654 DOCID026682 Rev 3

UM1816

HAL FLASH Generic Driver

16 HAL FLASH Generic Driver

16.1 HAL FLASH Generic Driver

16.2 FLASH Firmware driver registers structures

16.2.1 FLASH_ProcessTypeDef

Data Fields

__IO FLASH_ProcedureTypeDef ProcedureOnGoing

__IO uint32_t NbPagesToErase

__IO uint32_t Page

__IO uint32_t Address

HAL_LockTypeDef Lock

__IO uint32_t ErrorCode

Field Documentation

__IO FLASH_ProcedureTypeDef FLASH_ProcessTypeDef::ProcedureOnGoing

__IO uint32_t FLASH_ProcessTypeDef::NbPagesToErase

__IO uint32_t FLASH_ProcessTypeDef::Page

__IO uint32_t FLASH_ProcessTypeDef::Address

HAL_LockTypeDef FLASH_ProcessTypeDef::Lock

__IO uint32_t FLASH_ProcessTypeDef::ErrorCode

16.3 FLASH Firmware driver API description

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

The FLASH main features are:

Flash memory read operations

Flash memory program/erase operations

Read / write protections

Prefetch on I-Code

Option Bytes programming

16.3.2 How to use this driver

This driver provides functions to configure and program the Flash memory of all

STM32L1xx devices.

DOCID026682 Rev 3 197/654

HAL FLASH Generic Driver

UM1816

1. FLASH Memory Programming functions: this group includes all needed functions to erase and program the main memory:

Lock and Unlock the Flash interface.

Erase function: Erase Page.

Program functions: Fast Word and Half Page(should be executed from internal

SRAM).

2. DATA EEPROM Programming functions: this group includes all needed functions to erase and program the DATA EEPROM memory:

Lock and Unlock the DATA EEPROM interface.

Erase function: Erase Byte, erase HalfWord, erase Word, erase Double Word

(should be executed from internal SRAM).

Program functions: Fast Program Byte, Fast Program Half-Word,

FastProgramWord, Program Byte, Program Half-Word, Program Word and

Program Double-Word (should be executed from internal SRAM).

3. FLASH Option Bytes Programming functions: this group includes all needed functions to:

Lock and Unlock the Flash Option bytes.

Set/Reset the write protection.

Set the Read protection Level.

Set the BOR level.

Program the user option Bytes.

Launch the Option Bytes loader.

Get the Write protection.

Get the read protection status.

Get the BOR level.

Get the user option bytes.

4. 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_GetErrorCode()

5. FLASH Interface configuration functions: this group includes the management of following features:

Enable/Disable the RUN PowerDown mode.

Enable/Disable the SLEEP PowerDown mode.

6. FLASH Peripheral State methods: this group includes the management of following features:

Wait for the FLASH operation

Get the specific FLASH error flag

In addition to these function, this driver includes a set of macros allowing to handle the following operations:

Set/Get the latency

Enable/Disable the prefetch buffer

Enable/Disable the 64 bit Read Access.

Enable/Disable the Flash power-down

Enable/Disable the FLASH interrupts

Monitor the FLASH flags status

16.3.3 Programming operation functions

This subsection provides a set of functions allowing to manage the FLASH program operations.

The FLASH Memory Programming functions, includes the following functions:

198/654 DOCID026682 Rev 3

UM1816

HAL FLASH Generic Driver

HAL_FLASH_Unlock(void);

HAL_FLASH_Lock(void);

HAL_FLASH_Program(uint32_t TypeProgram, uint32_t Address, uint32_t Data)

HAL_FLASH_Program_IT(uint32_t TypeProgram, uint32_t Address, uint32_t Data)

Any operation of erase or program should follow these steps:

1. Call the HAL_FLASH_Unlock() function to enable the flash control register and program memory access.

2. Call the desired function to erase page or program data.

3. Call the HAL_FLASH_Lock() to disable the flash program memory access

(recommended to protect the FLASH memory against possible unwanted operation).

16.3.4 Option Bytes Programming functions

The FLASH_Option Bytes Programming_functions, includes the following functions:

HAL_FLASH_OB_Unlock(void);

HAL_FLASH_OB_Lock(void);

HAL_FLASH_OB_Launch(void);

HAL_FLASHEx_OBProgram(FLASH_OBProgramInitTypeDef *pOBInit);

HAL_FLASHEx_OBGetConfig(FLASH_OBProgramInitTypeDef *pOBInit);

Any operation of erase or program should follow these steps:

1. Call the HAL_FLASH_OB_Unlock() function to enable the Flash option control register access.

2. Call the following functions to program the desired option bytes.

HAL_FLASHEx_OBProgram(FLASH_OBProgramInitTypeDef *pOBInit);

3. Once all needed option bytes to be programmed are correctly written, call the

HAL_FLASH_OB_Launch(void) function to launch the Option Bytes programming process.

4. Call the HAL_FLASH_OB_Lock() to disable the Flash option control register access

(recommended to protect the option Bytes against possible unwanted operations).

Proprietary code Read Out Protection (PcROP):

1. The PcROP sector is selected by using the same option bytes as the Write protection.

As a result, these 2 options are exclusive each other.

2. To activate PCROP mode for Flash sectors(s), you need to follow the sequence below:

Use this function HAL_FLASHEx_AdvOBProgram with PCROPState =

OB_PCROP_STATE_ENABLE. *

16.3.5 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()

16.3.6 Peripheral Errors functions

This subsection permit to get in run-time Errors of the FLASH peripheral.

DOCID026682 Rev 3 199/654

HAL FLASH Generic Driver

This section contains the following APIs:

HAL_FLASH_GetError()

UM1816

16.3.7 HAL_FLASH_Program

Function Name

HAL_StatusTypeDef HAL_FLASH_Program (uint32_t

TypeProgram, uint32_t Address, uint64_t Data)

Function Description Program 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

Notes

HAL_StatusTypeDef HAL Status

To correctly run this function, the HAL_FLASH_Unlock() function must be called before. Call the HAL_FLASH_Lock() to disable the flash memory access (recommended to protect the FLASH memory against possible unwanted operation).

16.3.8 HAL_FLASH_Program_IT

Function Name

HAL_StatusTypeDef HAL_FLASH_Program_IT (uint32_t

TypeProgram, uint32_t Address, uint64_t Data)

Function Description Program word at a specified address with interrupt enabled.

Parameters

Return values

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

HAL_StatusTypeDef HAL Status

16.3.9 HAL_FLASH_EndOfOperationCallback

Function Name

void HAL_FLASH_EndOfOperationCallback (uint32_t

ReturnValue)

Function Description FLASH end of operation interrupt callback.

Parameters

Return values

ReturnValue: The value saved in this parameter depends on the ongoing procedurePages Erase: Address of the page which has been erased (if 0xFFFFFFFF, it means that all the selected sectors have been erased)Program: Address which was selected for data program

 none

16.3.10 HAL_FLASH_OperationErrorCallback

Function Name

void HAL_FLASH_OperationErrorCallback (uint32_t

ReturnValue)

Function Description FLASH operation error interrupt callback.

200/654 DOCID026682 Rev 3

UM1816

Parameters

Return values

HAL FLASH Generic Driver

ReturnValue: The value saved in this parameter depends on the ongoing procedurePages Erase: Address of the page which returned an errorProgram: Address which was selected for data program

 none

16.3.11 HAL_FLASH_IRQHandler

Function Name void HAL_FLASH_IRQHandler (void )

Function Description This function handles FLASH interrupt request.

Return values

None

16.3.12 HAL_FLASH_Unlock

Function Name HAL_StatusTypeDef HAL_FLASH_Unlock (void )

Function Description Unlock the FLASH control register access.

Return values

HAL Status

16.3.13 HAL_FLASH_Lock

Function Name HAL_StatusTypeDef HAL_FLASH_Lock (void )

Function Description Locks the FLASH control register access.

Return values

HAL Status

16.3.14 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

16.3.15 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

16.3.16 HAL_FLASH_OB_Launch

Function Name HAL_StatusTypeDef HAL_FLASH_OB_Launch (void )

Function Description Launch the option byte loading.

Return values

HAL_StatusTypeDef HAL Status

16.3.17 HAL_FLASH_GetError

Function Name uint32_t HAL_FLASH_GetError (void )

Function Description Get the specific FLASH error flag.

DOCID026682 Rev 3 201/654

HAL FLASH Generic Driver

Return values

UM1816

FLASH_ErrorCode The returned value can be:

HAL_FLASH_ERROR_WRP: FLASH Write protected error flag HAL_FLASH_ERROR_PGA: FLASH Programming

Alignment error flag HAL_FLASH_ERROR_SIZE: FLASH

Size error flag HAL_FLASH_ERROR_OPTV: Option validity error flag HAL_FLASH_ERROR_OPTVUSR: Option

UserValidity Error flag (available only Cat.3, Cat.4 and Cat.5 devices) HAL_FLASH_ERROR_RD: FLASH Read Protection error flag (PCROP) (available only Cat.2 and Cat.3 devices)

16.4 FLASH Firmware driver defines

16.4.1 FLASH

FLASH Error Codes

HAL_FLASH_ERROR_NONE

HAL_FLASH_ERROR_SIZE

HAL_FLASH_ERROR_OPTV

HAL_FLASH_ERROR_OPTVUSR

HAL_FLASH_ERROR_PGA

HAL_FLASH_ERROR_WRP

HAL_FLASH_ERROR_RD

HAL_FLASH_ERROR_OPERATION

FLASH Flags

FLASH_FLAG_BSY

FLASH_FLAG_EOP

FLASH Busy flag

FLASH End of Programming flag

FLASH_FLAG_ENDHV

FLASH_FLAG_READY

FLASH End of High Voltage flag

FLASH Ready flag after low power mode

FLASH_FLAG_WRPERR FLASH Write protected error flag

FLASH_FLAG_PGAERR FLASH Programming Alignment error flag

FLASH_FLAG_SIZERR FLASH Size error flag

FLASH_FLAG_OPTVERR FLASH Option Validity error flag

FLASH Interrupts

__HAL_FLASH_ENABLE_IT Description:

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:

202/654 DOCID026682 Rev 3

UM1816

HAL FLASH Generic Driver

 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

__HAL_FLASH_GET_FLAG Description:

Get the specified FLASH flag status.

Parameters:

__FLAG__: specifies the FLASH flag to check. This parameter can be one of the following values:

FLASH_FLAG_BSY : FLASH Busy flag

FLASH_FLAG_EOP : FLASH End of Operation flag

FLASH_FLAG_ENDHV : FLASH End of High

Voltage flag

FLASH_FLAG_READY: FLASH Ready flag after low power mode

FLASH_FLAG_WRPERR: FLASH Write protected error flag

FLASH_FLAG_PGAERR: FLASH

Programming Alignment error flag

FLASH_FLAG_SIZERR: FLASH Size error flag

FLASH_FLAG_OPTVERR: FLASH Option validity error error flag

FLASH_FLAG_OPTVERRUSR : FLASH

Option UserValidity (available only Cat.3, Cat.4 and Cat.5 devices)

FLASH_FLAG_RDERR : FLASH Read

Protection error flag (PCROP) (available only

Cat.2 and Cat.3 devices)

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_BSY : FLASH Busy flag

FLASH_FLAG_EOP : FLASH End of Operation

DOCID026682 Rev 3 203/654

HAL FLASH Generic Driver

UM1816

flag

FLASH_FLAG_ENDHV : FLASH End of High

Voltage flag

FLASH_FLAG_READY: FLASH Ready flag after low power mode

FLASH_FLAG_WRPERR: FLASH Write protected error flag

FLASH_FLAG_PGAERR: FLASH

Programming Alignment error flag

FLASH_FLAG_SIZERR: FLASH Size error flag

FLASH_FLAG_OPTVERR: FLASH Option validity error error flag

FLASH_FLAG_OPTVERRUSR : FLASH

Option UserValidity (available only Cat.3, Cat.4 and Cat.5 devices)

FLASH_FLAG_RDERR : FLASH Read

Protection error flag (PCROP) (available only

Cat.2 and Cat.3 devices)

Return value:

 none

FLASH Interrupts

FLASH_IT_EOP

FLASH_IT_ERR

FLASH Keys

FLASH_PDKEY1

FLASH_PDKEY2

End of programming interrupt source

Error interrupt source

FLASH_PEKEY1

FLASH_PEKEY2

FLASH_PRGKEY1

FLASH_PRGKEY2

FLASH_OPTKEY1

FLASH_OPTKEY2

Flash power down key1

Flash power down key2: used with FLASH_PDKEY1 to unlock the

RUN_PD bit in FLASH_ACR

Flash program erase key1

Flash program erase key: used with FLASH_PEKEY2 to unlock the write access to the FLASH_PECR register and data EEPROM

Flash program memory key1

Flash program memory key2: used with FLASH_PRGKEY2 to unlock the program memory

Flash option key1

Flash option key2: used with FLASH_OPTKEY1 to unlock the write access to the option byte block

FLASH Latency

FLASH_LATENCY_0 FLASH Zero Latency cycle

FLASH_LATENCY_1 FLASH One Latency cycle

Private Define

FLASH_TIMEOUT_VALUE

FLASH_PAGE_SIZE

Private Macros

204/654 DOCID026682 Rev 3

UM1816

HAL FLASH Generic Driver

IS_FLASH_TYPEPROGRAM

IS_FLASH_LATENCY

FLASH Type Program

FLASH_TYPEPROGRAM_WORD Program a word (32-bit) at a specified address

DOCID026682 Rev 3 205/654

HAL FLASH Extension Driver

UM1816

17 HAL FLASH Extension Driver

17.1 HAL FLASH Extension Driver

17.2 FLASHEx Firmware driver registers structures

17.2.1 FLASH_EraseInitTypeDef

Data Fields

uint32_t TypeErase

uint32_t PageAddress

uint32_t NbPages

Field Documentation

uint32_t FLASH_EraseInitTypeDef::TypeErase

TypeErase: Page Erase only. This parameter can be a value of

FLASHEx_Type_Erase

uint32_t FLASH_EraseInitTypeDef::PageAddress

PageAddress: Initial FLASH address to be erased This parameter must be a value belonging to FLASH Programm address (depending on the devices)

uint32_t FLASH_EraseInitTypeDef::NbPages

NbPages: Number of pages to be erased. This parameter must be a value between 1 and (max number of pages - value of Initial page)

17.2.2 FLASH_OBProgramInitTypeDef

Data Fields

uint32_t OptionType

uint32_t WRPState

uint32_t WRPSector0To31

uint32_t WRPSector32To63

uint32_t WRPSector64To95

uint8_t RDPLevel

uint8_t BORLevel

uint8_t USERConfig

Field Documentation

uint32_t FLASH_OBProgramInitTypeDef::OptionType

OptionType: Option byte to be configured. This parameter can be a value of

FLASHEx_Option_Type

uint32_t FLASH_OBProgramInitTypeDef::WRPState

WRPState: Write protection activation or deactivation. This parameter can be a value

of

FLASHEx_WRP_State

206/654 DOCID026682 Rev 3

UM1816

HAL FLASH Extension Driver

uint32_t FLASH_OBProgramInitTypeDef::WRPSector0To31

WRPSector0To31: specifies the sector(s) which are write protected between Sectors

0 to 31 This parameter can be a combination of

FLASHEx_Option_Bytes_Write_Protection1

uint32_t FLASH_OBProgramInitTypeDef::WRPSector32To63

WRPSector32To63: specifies the sector(s) which are write protected between

Sectors 32 to 63 or Sectors 32 to 47 for STM32L1xxxDX devices. This parameter can

be a combination of

FLASHEx_Option_Bytes_Write_Protection2

uint32_t FLASH_OBProgramInitTypeDef::WRPSector64To95

WRPSector64to95: specifies the sector(s) which are write protected between Sectors

64 to 95 This parameter can be a combination of

FLASHEx_Option_Bytes_Write_Protection3

uint8_t FLASH_OBProgramInitTypeDef::RDPLevel

RDPLevel: Set the read protection level.. This parameter can be a value of

FLASHEx_Option_Bytes_Read_Protection

uint8_t FLASH_OBProgramInitTypeDef::BORLevel

BORLevel: Set the BOR Level. This parameter can be a value of

FLASHEx_Option_Bytes_BOR_Level

uint8_t FLASH_OBProgramInitTypeDef::USERConfig

USERConfig: Program the FLASH User Option Byte: IWDG_SW / RST_STOP /

RST_STDBY. This parameter can be a combination of

FLASHEx_Option_Bytes_IWatchdog

,

FLASHEx_Option_Bytes_nRST_STOP

and

FLASHEx_Option_Bytes_nRST_STDBY

17.2.3 FLASH_AdvOBProgramInitTypeDef

Data Fields

uint32_t OptionType

uint16_t BootConfig

Field Documentation

uint32_t FLASH_AdvOBProgramInitTypeDef::OptionType

OptionType: Option byte to be configured for extension . This parameter can be a

value of

FLASHEx_OptionAdv_Type

uint16_t FLASH_AdvOBProgramInitTypeDef::BootConfig

BootConfig: specifies Option bytes for boot config This parameter can be a value of

FLASHEx_Option_Bytes_BOOT

17.3 FLASHEx Firmware driver API description

17.3.1 FLASH Erasing Programming functions

The FLASH Memory Erasing functions, includes the following functions:

HAL_FLASHEx_Erase: return only when erase has been done

HAL_FLASHEx_Erase_IT: end of erase is done when

HAL_FLASH_EndOfOperationCallback is called with parameter 0xFFFFFFFF

Any operation of erase should follow these steps:

DOCID026682 Rev 3 207/654

HAL FLASH Extension Driver

UM1816

1. Call the HAL_FLASH_Unlock() function to enable the flash control register and program memory access.

2. Call the desired function to erase page.

3. Call the HAL_FLASH_Lock() to disable the flash program memory access

(recommended to protect the FLASH memory against possible unwanted operation).

This section contains the following APIs:

HAL_FLASHEx_Erase()

HAL_FLASHEx_Erase_IT()

17.3.2 Option Bytes Programming functions

Any operation of erase or program should follow these steps:

1. Call the HAL_FLASH_OB_Unlock() function to enable the Flash option control register access.

2. Call following function to program the desired option bytes.

HAL_FLASHEx_OBProgram: - To Enable/Disable the desired sector write protection. - To set the desired read Protection Level. - To configure the user option Bytes: IWDG, STOP and the Standby. - To Set the BOR level.

3. Once all needed option bytes to be programmed are correctly written, call the

HAL_FLASH_OB_Launch(void) function to launch the Option Bytes programming process.

4. Call the HAL_FLASH_OB_Lock() to disable the Flash option control register access

(recommended to protect the option Bytes against possible unwanted operations).

Proprietary code Read Out Protection (PcROP):

1. The PcROP sector is selected by using the same option bytes as the Write protection

(nWRPi bits). As a result, these 2 options are exclusive each other.

2. In order to activate the PcROP (change the function of the nWRPi option bits), the

SPRMOD option bit must be activated.

3. The active value of nWRPi bits is inverted when PCROP mode is active, this means: if SPRMOD = 1 and nWRPi = 1 (default value), then the user sector "i" is read/write protected.

4. To activate PCROP mode for Flash sector(s), you need to call the following function:

HAL_FLASHEx_AdvOBProgram in selecting sectors to be read/write protected

HAL_FLASHEx_OB_SelectPCROP to enable the read/write protection

5. PcROP is available only in STM32L151xBA, STM32L152xBA, STM32L151xC,

STM32L152xC & STM32L162xC devices.

This section contains the following APIs:

HAL_FLASHEx_OBProgram()

HAL_FLASHEx_OBGetConfig()

HAL_FLASHEx_AdvOBProgram()

HAL_FLASHEx_AdvOBGetConfig()

17.3.3 DATA EEPROM Programming functions

Any operation of erase or program should follow these steps:

1. Call the HAL_FLASHEx_DATAEEPROM_Unlock() function to enable the data

EEPROM access and Flash program erase control register access.

2. Call the desired function to erase or program data.

3. Call the HAL_FLASHEx_DATAEEPROM_Lock() to disable the data EEPROM access and Flash program erase control register access(recommended to protect the

DATA_EEPROM against possible unwanted operation).

208/654 DOCID026682 Rev 3

UM1816

HAL FLASH Extension Driver

This section contains the following APIs:

HAL_FLASHEx_DATAEEPROM_Unlock()

HAL_FLASHEx_DATAEEPROM_Lock()

HAL_FLASHEx_DATAEEPROM_Erase()

HAL_FLASHEx_DATAEEPROM_Program()

HAL_FLASHEx_DATAEEPROM_EnableFixedTimeProgram()

HAL_FLASHEx_DATAEEPROM_DisableFixedTimeProgram()

17.3.4 HAL_FLASHEx_Erase

Function Name

HAL_StatusTypeDef HAL_FLASHEx_Erase

(FLASH_EraseInitTypeDef * pEraseInit, uint32_t * PageError)

Function Description Erase the specified FLASH memory Pages.

Parameters

Return values

pEraseInit: pointer to an FLASH_EraseInitTypeDef structure that contains the configuration information for the erasing.

PageError: pointer to variable that contains the configuration information on faulty sector in case of error (0xFFFFFFFF means that all the sectors have been correctly erased)

HAL_StatusTypeDef HAL Status

Notes

To correctly run this function, the HAL_FLASH_Unlock() function must be called before. Call the HAL_FLASH_Lock() to disable the flash memory access (recommended to protect the FLASH memory against possible unwanted operation)

For STM32L151xDX/STM32L152xDX/STM32L162xDX, as memory is not continuous between 2 banks, user should perform pages erase by bank only.

17.3.5 HAL_FLASHEx_Erase_IT

Function Name

HAL_StatusTypeDef HAL_FLASHEx_Erase_IT

(FLASH_EraseInitTypeDef * pEraseInit)

Function Description Perform a page erase of the specified FLASH memory pages with interrupt enabled.

Parameters

pEraseInit: pointer to an FLASH_EraseInitTypeDef structure that contains the configuration information for the erasing.

Return values

Notes

HAL_StatusTypeDef HAL Status

To correctly run this function, the HAL_FLASH_Unlock() function must be called before. Call the HAL_FLASH_Lock() to disable the flash memory access (recommended to protect the FLASH memory against possible unwanted operation)

For STM32L151xDX/STM32L152xDX/STM32L162xDX, as memory is not continuous between 2 banks, user should perform pages erase by bank only.

17.3.6 HAL_FLASHEx_OBProgram

Function Name

HAL_StatusTypeDef HAL_FLASHEx_OBProgram

(FLASH_OBProgramInitTypeDef * pOBInit)

Function Description Program option bytes.

DOCID026682 Rev 3 209/654

HAL FLASH Extension Driver

Parameters

Return values

UM1816

pOBInit: pointer to an FLASH_OBInitStruct structure that contains the configuration information for the programming.

HAL_StatusTypeDef HAL Status

17.3.7 HAL_FLASHEx_OBGetConfig

Function Name

void HAL_FLASHEx_OBGetConfig

(FLASH_OBProgramInitTypeDef * pOBInit)

Function Description Get the Option byte configuration.

Parameters

Return values

pOBInit: pointer to an FLASH_OBInitStruct structure that contains the configuration information for the programming.

None

17.3.8 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

Notes

HAL_StatusTypeDef HAL Status

This function can be used only for Cat2 & Cat3 devices for

PCROP and Cat4 & Cat5 for BFB2.

17.3.9 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

Notes

None

This function can be used only for Cat2 & Cat3 devices for

PCROP and Cat4 & Cat5 for BFB2.

17.3.10 HAL_FLASHEx_DATAEEPROM_Unlock

Function Name

HAL_StatusTypeDef HAL_FLASHEx_DATAEEPROM_Unlock

(void )

Function Description Unlocks the data memory and FLASH_PECR register access.

Return values

HAL_StatusTypeDef HAL Status

17.3.11 HAL_FLASHEx_DATAEEPROM_Lock

Function Name

HAL_StatusTypeDef HAL_FLASHEx_DATAEEPROM_Lock

210/654 DOCID026682 Rev 3

UM1816

HAL FLASH Extension Driver

(void )

Function Description Locks the Data memory and FLASH_PECR register access.

Return values

HAL_StatusTypeDef HAL Status

17.3.12 HAL_FLASHEx_DATAEEPROM_Erase

Function Name

HAL_StatusTypeDef HAL_FLASHEx_DATAEEPROM_Erase

(uint32_t TypeErase, uint32_t Address)

Function Description Erase a word in data memory.

Parameters

Address: specifies the address to be erased.

TypeErase: Indicate the way to erase at a specified address.

This parameter can be a value of FLASH Type Program

Return values

Notes

FLASH Status: The returned value can be:

FLASH_ERROR_PROGRAM, HAL_FLASH_ERROR_WRP,

FLASH_COMPLETE or FLASH_TIMEOUT.

To correctly run this function, the DATA_EEPROM_Unlock() function must be called before. Call the

DATA_EEPROM_Lock() to the data EEPROM access and

Flash program erase control register access(recommended to protect the DATA_EEPROM against possible unwanted operation).

17.3.13 HAL_FLASHEx_DATAEEPROM_Program

Function Name

HAL_StatusTypeDef HAL_FLASHEx_DATAEEPROM_Program

(uint32_t TypeProgram, uint32_t Address, uint32_t Data)

Function Description Program word at a specified address.

Parameters

TypeProgram: Indicate the way to program at a specified address. This parameter can be a value of FLASHEx Type

Program Data

Address: specifies the address to be programmed.

Data: specifies the data to be programmed

Return values

Notes

HAL_StatusTypeDef HAL Status

To correctly run this function, the

HAL_FLASH_EEPROM_Unlock() function must be called before. Call the HAL_FLASHEx_DATAEEPROM_Unlock() to he data EEPROM access and Flash program erase control register access(recommended to protect the DATA_EEPROM against possible unwanted operation).

The function

HAL_FLASHEx_DATAEEPROM_EnableFixedTimeProgram() can be called before this function to configure the Fixed Time

Programming.

17.3.14 HAL_FLASHEx_DATAEEPROM_EnableFixedTimeProgram

Function Name

void

HAL_FLASHEx_DATAEEPROM_EnableFixedTimeProgram

(void )

DOCID026682 Rev 3 211/654

HAL FLASH Extension Driver

UM1816

Function Description Enable DATA EEPROM fixed Time programming (2*Tprog).

Return values

None

17.3.15 HAL_FLASHEx_DATAEEPROM_DisableFixedTimeProgram

Function Name

void

HAL_FLASHEx_DATAEEPROM_DisableFixedTimeProgram

(void )

Function Description Disables DATA EEPROM fixed Time programming (2*Tprog).

Return values

None

17.4 FLASHEx Firmware driver defines

17.4.1 FLASHEx

FLASHEx Address

IS_FLASH_DATA_ADDRESS

IS_FLASH_PROGRAM_ADDRESS

IS_FLASH_PROGRAM_BANK1_ADDRESS

IS_FLASH_PROGRAM_BANK2_ADDRESS

IS_NBPAGES

IS_OB_BOOT_BANK

Exported Macros

__HAL_FLASH_SET_LATENCY

__HAL_FLASH_GET_LATENCY

Description:

Set the FLASH Latency.

Parameters:

__LATENCY__: FLASH

Latency This parameter can be one of the following values:

FLASH_LATENCY_0:

FLASH Zero Latency cycle

FLASH_LATENCY_1:

FLASH One Latency cycle

Return value:

 none

Description:

Get the FLASH Latency.

Return value:

FLASH: Latency This parameter can be one of the following values:

FLASH_LATENCY_0:

FLASH Zero Latency cycle

FLASH_LATENCY_1:

212/654 DOCID026682 Rev 3

UM1816

__HAL_FLASH_ACC64_ENABLE

__HAL_FLASH_ACC64_DISABLE

HAL FLASH Extension Driver

FLASH One Latency cycle

Description:

Enable the FLASH 64-bit access.

Return value:

 none

Notes:

Read access 64 bit is used.

This bit cannot be written at the same time as the LATENCY and PRFTEN bits.

Description:

Disable the FLASH 64-bit access.

Return value:

 none

Notes:

Read access 32 bit is used To reset this bit, the LATENCY should be zero wait state and the prefetch off.

__HAL_FLASH_PREFETCH_BUFFER_ENABLE Description:

Enable the FLASH prefetch buffer.

Return value:

 none

__HAL_FLASH_PREFETCH_BUFFER_DISABLE Description:

Disable the FLASH prefetch buffer.

Return value:

 none

__HAL_FLASH_SLEEP_POWERDOWN_ENABLE Description:

Enable the FLASH power down during Sleep mode.

Return value:

 none

__HAL_FLASH_SLEEP_POWERDOWN_DISABLE Description:

Disable the FLASH power down during Sleep mode.

Return value:

DOCID026682 Rev 3 213/654

HAL FLASH Extension Driver

__HAL_FLASH_POWER_DOWN_ENABLE

UM1816

 none

Notes:

Writing this bit to 0 this bit, automatically the keys are loss and a new unlock sequence is necessary to re-write it to 1.

__HAL_FLASH_POWER_DOWN_DISABLE

FLASHEx Flags

FLASH_FLAG_OPTVERRUSR FLASH Option User Validity error flag

FLASHEx Option Advanced Type

OPTIONBYTE_BOOTCONFIG BOOTConfig option byte configuration

FLASHEx Option Bytes BOOT

OB_BOOT_BANK2 At startup, if boot pins are set in boot from user Flash position and this parameter is selected the device will boot from Bank 2 or Bank

1, depending on the activation of the bank

OB_BOOT_BANK1 At startup, if boot pins are set in boot from user Flash position and this parameter is selected the device will boot from Bank1(Default)

FLASHEx Option Bytes BOR Level

OB_BOR_OFF BOR is disabled at power down, the reset is asserted when the

VDD power supply reaches the PDR(Power Down Reset) threshold (1.5V)

OB_BOR_LEVEL1

OB_BOR_LEVEL2

BOR Reset threshold levels for 1.7V - 1.8V VDD power supply

BOR Reset threshold levels for 1.9V - 2.0V VDD power supply

OB_BOR_LEVEL3

OB_BOR_LEVEL4

BOR Reset threshold levels for 2.3V - 2.4V VDD power supply

BOR Reset threshold levels for 2.55V - 2.65V VDD power supply

OB_BOR_LEVEL5 BOR Reset threshold levels for 2.8V - 2.9V VDD power supply

FLASHEx Option Bytes IWatchdog

OB_IWDG_SW

OB_IWDG_HW

Software WDG selected

Hardware WDG selected

FLASHEx Option Bytes nRST_STDBY

OB_STDBY_NORST No reset generated when entering in STANDBY

OB_STDBY_RST Reset generated when entering in STANDBY

FLASHEx Option Bytes nRST_STOP

OB_STOP_NORST No reset generated when entering in STOP

OB_STOP_RST Reset generated when entering in STOP

FLASHEx Option Bytes Read Protection

OB_RDP_LEVEL0

OB_RDP_LEVEL1

FLASHEx Option Bytes Write Mask

214/654 DOCID026682 Rev 3

UM1816

HAL FLASH Extension Driver

WRP_MASK_LOW

WRP_MASK_HIGH

FLASHEx Option Bytes Write Protection1

OB_WRP1_PAGES0TO15

OB_WRP1_PAGES16TO31

OB_WRP1_PAGES32TO47

OB_WRP1_PAGES48TO63

OB_WRP1_PAGES64TO79

OB_WRP1_PAGES80TO95

OB_WRP1_PAGES96TO111

OB_WRP1_PAGES112TO127

OB_WRP1_PAGES128TO143

OB_WRP1_PAGES144TO159

OB_WRP1_PAGES160TO175

OB_WRP1_PAGES176TO191

OB_WRP1_PAGES192TO207

OB_WRP1_PAGES208TO223

OB_WRP1_PAGES224TO239

OB_WRP1_PAGES240TO255

OB_WRP1_PAGES256TO271

OB_WRP1_PAGES272TO287

OB_WRP1_PAGES288TO303

OB_WRP1_PAGES304TO319

OB_WRP1_PAGES320TO335

OB_WRP1_PAGES336TO351

OB_WRP1_PAGES352TO367

OB_WRP1_PAGES368TO383

OB_WRP1_PAGES384TO399

OB_WRP1_PAGES400TO415

OB_WRP1_PAGES416TO431

OB_WRP1_PAGES432TO447

OB_WRP1_PAGES448TO463

OB_WRP1_PAGES464TO479

OB_WRP1_PAGES480TO495

OB_WRP1_PAGES496TO511

OB_WRP1_ALLPAGES Write protection of all Sectors

FLASHEx Option Bytes Write Protection2

DOCID026682 Rev 3 215/654

HAL FLASH Extension Driver

OB_WRP2_PAGES512TO527

OB_WRP2_PAGES528TO543

OB_WRP2_PAGES544TO559

OB_WRP2_PAGES560TO575

OB_WRP2_PAGES576TO591

OB_WRP2_PAGES592TO607

OB_WRP2_PAGES608TO623

OB_WRP2_PAGES624TO639

OB_WRP2_PAGES640TO655

OB_WRP2_PAGES656TO671

OB_WRP2_PAGES672TO687

OB_WRP2_PAGES688TO703

OB_WRP2_PAGES704TO719

OB_WRP2_PAGES720TO735

OB_WRP2_PAGES736TO751

OB_WRP2_PAGES752TO767

OB_WRP2_PAGES768TO783

OB_WRP2_PAGES784TO799

OB_WRP2_PAGES800TO815

OB_WRP2_PAGES816TO831

OB_WRP2_PAGES832TO847

OB_WRP2_PAGES848TO863

OB_WRP2_PAGES864TO879

OB_WRP2_PAGES880TO895

OB_WRP2_PAGES896TO911

OB_WRP2_PAGES912TO927

OB_WRP2_PAGES928TO943

OB_WRP2_PAGES944TO959

OB_WRP2_PAGES960TO975

OB_WRP2_PAGES976TO991

OB_WRP2_PAGES992TO1007

OB_WRP2_PAGES1008TO1023

OB_WRP2_ALLPAGES Write protection of all Sectors

FLASHEx Option Bytes Write Protection3

OB_WRP3_PAGES1024TO1039

OB_WRP3_PAGES1040TO1055

216/654 DOCID026682 Rev 3

UM1816

UM1816

HAL FLASH Extension Driver

OB_WRP3_PAGES1056TO1071

OB_WRP3_PAGES1072TO1087

OB_WRP3_PAGES1088TO1103

OB_WRP3_PAGES1104TO1119

OB_WRP3_PAGES1120TO1135

OB_WRP3_PAGES1136TO1151

OB_WRP3_PAGES1152TO1167

OB_WRP3_PAGES1168TO1183

OB_WRP3_PAGES1184TO1199

OB_WRP3_PAGES1200TO1215

OB_WRP3_PAGES1216TO1231

OB_WRP3_PAGES1232TO1247

OB_WRP3_PAGES1248TO1263

OB_WRP3_PAGES1264TO1279

OB_WRP3_PAGES1280TO1295

OB_WRP3_PAGES1296TO1311

OB_WRP3_PAGES1312TO1327

OB_WRP3_PAGES1328TO1343

OB_WRP3_PAGES1344TO1359

OB_WRP3_PAGES1360TO1375

OB_WRP3_PAGES1376TO1391

OB_WRP3_PAGES1392TO1407

OB_WRP3_PAGES1408TO1423

OB_WRP3_PAGES1424TO1439

OB_WRP3_PAGES1440TO1455

OB_WRP3_PAGES1456TO1471

OB_WRP3_PAGES1472TO1487

OB_WRP3_PAGES1488TO1503

OB_WRP3_PAGES1504TO1519

OB_WRP3_PAGES1520TO1535

OB_WRP3_ALLPAGES

FLASHEx Option Type

Write protection of all Sectors

OPTIONBYTE_WRP WRP option byte configuration

OPTIONBYTE_RDP RDP option byte configuration

OPTIONBYTE_USER USER option byte configuration

OPTIONBYTE_BOR BOR option byte configuration

Private Defines

DOCID026682 Rev 3 217/654

HAL FLASH Extension Driver

FLASH_FLAG_MASK

FLASH_NBPAGES_MAX

Private Macros

IS_FLASH_TYPEERASE

IS_OPTIONBYTE

IS_WRPSTATE

IS_OB_RDP

IS_OB_BOR_LEVEL

IS_OB_IWDG_SOURCE

IS_OB_STOP_SOURCE

IS_OB_STDBY_SOURCE

IS_OBEX

IS_TYPEERASEDATA

UM1816

IS_TYPEPROGRAMDATA

FLASHEx_Type_Erase

FLASH_TYPEERASE_PAGES Page erase only

FLASHEx Type Erase Data

FLASH_TYPEERASEDATA_BYTE Erase byte (8-bit) at a specified address.

FLASH_TYPEERASEDATA_HALFWORD Erase a half-word (16-bit) at a specified address.

FLASH_TYPEERASEDATA_WORD Erase a word (32-bit) at a specified address.

FLASHEx Type Program Data

FLASH_TYPEPROGRAMDATA_BYTE Program byte (8-bit) at a specified address.

FLASH_TYPEPROGRAMDATA_HALFWORD

FLASH_TYPEPROGRAMDATA_WORD

FLASH_TYPEPROGRAMDATA_FASTBYTE

Program a half-word (16-bit) at a specified address.

Program a word (32-bit) at a specified address.

Fast Program byte (8-bit) at a specified address.

FLASH_TYPEPROGRAMDATA_FASTHALFWORD Fast Program a half-word (16-bit) at a specified address.

FLASH_TYPEPROGRAMDATA_FASTWORD Fast Program a word (32-bit) at a specified address.

FLASHEx 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

218/654 DOCID026682 Rev 3

UM1816

HAL FLASH__RAMFUNC Generic Driver

18 HAL FLASH__RAMFUNC Generic Driver

18.1 HAL FLASH__RAMFUNC Generic Driver

18.2 FLASH__RAMFUNC Firmware driver API description

18.2.1 HAL_FLASHEx_EnableRunPowerDown

Function Name __RAM_FUNC HAL_FLASHEx_EnableRunPowerDown (void )

Function Description Enable the power down mode during RUN mode.

Return values

None

Notes

This function can be used only when the user code is running from Internal SRAM.

18.2.2 HAL_FLASHEx_DisableRunPowerDown

Function Name __RAM_FUNC HAL_FLASHEx_DisableRunPowerDown (void )

Function Description Disable the power down mode during RUN mode.

Return values

None

Notes

This function can be used only when the user code is running from Internal SRAM.

18.2.3 HAL_FLASHEx_EraseParallelPage

Function Name

__RAM_FUNC HAL_FLASHEx_EraseParallelPage (uint32_t

Page_Address1, uint32_t Page_Address2)

Function Description Erases a specified 2 page in program memory in parallel.

Parameters

Page_Address1: The page address in program memory to be erased in the first Bank (BANK1). This parameter should be between FLASH_BASE and FLASH_BANK1_END.

Page_Address2: The page address in program memory to be erased in the second Bank (BANK2). This parameter should be between FLASH_BANK2_BASE and

FLASH_BANK2_END.

Return values

Notes

HAL Status: The returned value can be: HAL_ERROR,

HAL_OK or HAL_TIMEOUT.

This function can be used only for STM32L151xD,

STM32L152xD), STM32L162xD and Cat5 devices. To correctly run this function, the HAL_FLASH_Unlock() function must be called before. Call the HAL_FLASH_Lock() to disable the flash memory access (recommended to protect the

FLASH memory against possible unwanted operation).

A Page is erased in the Program memory only if the address to load is the start address of a page (multiple of 256 bytes).

18.2.4 HAL_FLASHEx_ProgramParallelHalfPage

DOCID026682 Rev 3 219/654

HAL FLASH__RAMFUNC Generic Driver

Function Name

UM1816

__RAM_FUNC HAL_FLASHEx_ProgramParallelHalfPage

(uint32_t Address1, uint32_t * pBuffer1, uint32_t Address2,

uint32_t * pBuffer2)

Function Description Programs 2 half page in program memory in parallel.

Parameters

Address1: specifies the first address to be written in the first bank (BANK1). This parameter should be between

FLASH_BASE and (FLASH_BANK1_END -

FLASH_PAGE_SIZE).

pBuffer1: pointer to the buffer containing the data to be written to the first half page in the first bank.

Address2: specifies the second address to be written in the second bank (BANK2). This parameter should be between

FLASH_BANK2_BASE and (FLASH_BANK2_END -

FLASH_PAGE_SIZE).

pBuffer2: pointer to the buffer containing the data to be written to the second half page in the second bank.

Return values

Notes

HAL Status: The returned value can be: HAL_ERROR,

HAL_OK or HAL_TIMEOUT.

This function can be used only for STM32L151xD,

STM32L152xD), STM32L162xD and Cat5 devices.

To correctly run this function, the HAL_FLASH_Unlock() function must be called before. Call the HAL_FLASH_Lock() to disable the flash memory access (recommended to protect the FLASH memory against possible unwanted operation).

Half page write is possible only from SRAM.

If there are more than 32 words to write, after 32 words another Half Page programming operation starts and has to be finished.

A half page is written to the program memory only if the first address to load is the start address of a half page (multiple of

128 bytes) and the 31 remaining words to load are in the same half page.

During the Program memory half page write all read operations are forbidden (this includes DMA read operations and debugger read operations such as breakpoints, periodic updates, etc.).

If a PGAERR is set during a Program memory half page write, the complete write operation is aborted. Software should then reset the FPRG and PROG/DATA bits and restart the write operation from the beginning.

18.2.5 HAL_FLASHEx_HalfPageProgram

Function Name

__RAM_FUNC HAL_FLASHEx_HalfPageProgram (uint32_t

Address, uint32_t * pBuffer)

Function Description Programs a half page in program memory.

Parameters

Return values

Address: specifies the address to be written.

pBuffer: pointer to the buffer containing the data to be written to the half page.

HAL Status: The returned value can be: HAL_ERROR,

220/654 DOCID026682 Rev 3

UM1816

Notes

HAL FLASH__RAMFUNC Generic Driver

HAL_OK or HAL_TIMEOUT.

To correctly run this function, the HAL_FLASH_Unlock() function must be called before. Call the HAL_FLASH_Lock() to disable the flash memory access (recommended to protect the FLASH memory against possible unwanted operation)

Half page write is possible only from SRAM.

If there are more than 32 words to write, after 32 words another Half Page programming operation starts and has to be finished.

A half page is written to the program memory only if the first address to load is the start address of a half page (multiple of

128 bytes) and the 31 remaining words to load are in the same half page.

During the Program memory half page write all read operations are forbidden (this includes DMA read operations and debugger read operations such as breakpoints, periodic updates, etc.).

If a PGAERR is set during a Program memory half page write, the complete write operation is aborted. Software should then reset the FPRG and PROG/DATA bits and restart the write operation from the beginning.

18.2.6 HAL_FLASHEx_DATAEEPROM_EraseDoubleWord

Function Name

__RAM_FUNC

HAL_FLASHEx_DATAEEPROM_EraseDoubleWord (uint32_t

Address)

Function Description Erase a double word in data memory.

Parameters

Address: specifies the address to be erased.

Return values

Notes

HAL Status: The returned value can be: HAL_ERROR,

HAL_OK or HAL_TIMEOUT.

To correctly run this function, the

HAL_FLASH_EEPROM_Unlock() function must be called before. Call the HAL_FLASH_EEPROM_Lock() to he data

EEPROM access and Flash program erase control register access(recommended to protect the DATA_EEPROM against possible unwanted operation).

Data memory double word erase is possible only from SRAM.

A double word is erased to the data memory only if the first address to load is the start address of a double word (multiple of 8 bytes).

During the Data memory double word erase, all read operations are forbidden (this includes DMA read operations and debugger read operations such as breakpoints, periodic updates, etc.).

18.2.7 HAL_FLASHEx_DATAEEPROM_ProgramDoubleWord

Function Name

__RAM_FUNC

HAL_FLASHEx_DATAEEPROM_ProgramDoubleWord

(uint32_t Address, uint64_t Data)

DOCID026682 Rev 3 221/654

HAL FLASH__RAMFUNC Generic Driver

Function Description Write a double word in data memory without erase.

Parameters

Return values

UM1816

Address: specifies the address to be written.

Data: specifies the data to be written.

HAL Status: The returned value can be: HAL_ERROR,

HAL_OK or HAL_TIMEOUT.

Notes

To correctly run this function, the

HAL_FLASH_EEPROM_Unlock() function must be called before. Call the HAL_FLASH_EEPROM_Lock() to he data

EEPROM access and Flash program erase control register access(recommended to protect the DATA_EEPROM against possible unwanted operation).

Data memory double word write is possible only from SRAM.

A data memory double word is written to the data memory only if the first address to load is the start address of a double word (multiple of double word).

During the Data memory double word write, all read operations are forbidden (this includes DMA read operations and debugger read operations such as breakpoints, periodic updates, etc.).

222/654 DOCID026682 Rev 3

UM1816

HAL GPIO Generic Driver

19 HAL GPIO Generic Driver

19.1 HAL GPIO Generic Driver

19.2 GPIO Firmware driver registers structures

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

uint32_t GPIO_InitTypeDef::Mode

Specifies the operating mode for the selected pins. This parameter can be a value of

GPIO_mode

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

uint32_t GPIO_InitTypeDef::Speed

Specifies the speed for the selected pins. This parameter can be a value of

GPIO_speed

uint32_t GPIO_InitTypeDef::Alternate

Peripheral to be connected to the selected pins This parameter can be a value of

GPIOEx_Alternate_function_selection

19.3 GPIO Firmware driver API description

19.3.1 GPIO Peripheral features

Each port bit of the general-purpose I/O (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.

DOCID026682 Rev 3 223/654

HAL GPIO Generic Driver

UM1816

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.

The microcontroller IO pins are connected to onboard peripherals/modules through a multiplexer that allows only one peripheral s alternate function (AF) connected to an IO pin at a time. In this way, there can be no conflict between peripherals sharing the same IO pin.

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 28 edge detectors (depending on products 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.

19.3.2 How to use this driver

1. Enable the GPIO AHB clock using the following function : __GPIOx_CLK_ENABLE().

2. 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, the speed is configurable: Low, Medium and High.

If alternate mode is selected, 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).

3. 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().

4. HAL_GPIO_DeInit allows to set register values to their reset value. It's also recommended to use it to unconfigure pin which was used as an external interrupt or in event mode. That's the only way to reset corresponding bit in EXTI & SYSCFG registers.

5. To get the level of a pin configured in input mode use HAL_GPIO_ReadPin().

6. To set/reset the level of a pin configured in output mode use

HAL_GPIO_WritePin()/HAL_GPIO_TogglePin().

7. To lock pin configuration until next reset use HAL_GPIO_LockPin().

8. During and just after reset, the alternate functions are not active and the GPIO pins are configured in input floating mode (except JTAG pins).

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

224/654 DOCID026682 Rev 3

UM1816

HAL GPIO Generic Driver

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

19.3.3 Initialization and Configuration functions

This section contains the following APIs:

HAL_GPIO_Init()

HAL_GPIO_DeInit()

19.3.4 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

Return values

GPIOx: where x can be (A..G depending on device used) to select the GPIO peripheral for STM32L1XX family devices

GPIO_Init: pointer to a GPIO_InitTypeDef structure that contains the configuration information for the specified GPIO peripheral.

None

19.3.5 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

Return values

GPIOx: where x can be (A..G depending on device used) to select the GPIO peripheral for STM32L1XX family 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).

None

19.3.6 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

Return values

GPIOx: where x can be (A..G depending on device used) to select the GPIO peripheral for STM32L1XX family devices

GPIO_Pin: specifies the port bit to read. This parameter can be GPIO_PIN_x where x can be (0..15).

The input port pin value.

19.3.7 HAL_GPIO_WritePin

Function Name

void HAL_GPIO_WritePin (GPIO_TypeDef * GPIOx, uint16_t

GPIO_Pin, GPIO_PinState PinState)

DOCID026682 Rev 3 225/654

HAL GPIO Generic Driver

Function Description Sets or clears the selected data port bit.

Parameters

Return values

UM1816

GPIOx: where x can be (A..G depending on device used) to select the GPIO peripheral for STM32L1XX family 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 pinGPIO_PIN_SET: to set the port pin

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.

19.3.8 HAL_GPIO_TogglePin

Function Name

void HAL_GPIO_TogglePin (GPIO_TypeDef * GPIOx, uint16_t

GPIO_Pin)

Function Description Toggles the specified GPIO pin.

Parameters

Return values

GPIOx: where x can be (A..G depending on device used) to select the GPIO peripheral for STM32L1XX family devices

GPIO_Pin: specifies the pins to be toggled.

None

19.3.9 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..G depending on device used) to select the GPIO peripheral for STM32L1XX family devices

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

Notes

None

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 modified until the next reset.

Limitation concerning GPIOx_OTYPER: Locking of

GPIOx_OTYPER[i] with i = 15..8 depends from setting of

GPIOx_LCKR[i-8] and not from GPIOx_LCKR[i].

GPIOx_LCKR[i-8] is locking GPIOx_OTYPER[i] together with

GPIOx_OTYPER[i-8]. It is not possible to lock

GPIOx_OTYPER[i] with i = 15..8, without locking also

GPIOx_OTYPER[i-8]. Workaround: When calling

HAL_GPIO_LockPin with GPIO_Pin from GPIO_PIN_8 to

GPIO_PIN_15, you must call also HAL_GPIO_LockPin with

226/654 DOCID026682 Rev 3

UM1816

HAL GPIO Generic Driver

GPIO_Pin - 8. (When locking a pin from GPIO_PIN_8 to

GPIO_PIN_15, you must lock also the corresponding

GPIO_PIN_0 to GPIO_PIN_7).

19.3.10 HAL_GPIO_EXTI_IRQHandler

Function Name void HAL_GPIO_EXTI_IRQHandler (uint16_t GPIO_Pin)

Function Description This function handles EXTI interrupt request.

Parameters

Return values

GPIO_Pin: Specifies the port pin connected to corresponding

EXTI line.

None

19.3.11 HAL_GPIO_EXTI_Callback

Function Name void HAL_GPIO_EXTI_Callback (uint16_t GPIO_Pin)

Function Description EXTI line detection callbacks.

Parameters

Return values

GPIO_Pin: Specifies the port pin connected to corresponding

EXTI line.

None

19.4 GPIO Firmware driver defines

19.4.1 GPIO

GPIO Exported Macros

__HAL_GPIO_EXTI_GET_FLAG

__HAL_GPIO_EXTI_CLEAR_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).

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

DOCID026682 Rev 3 227/654

HAL GPIO Generic Driver

__HAL_GPIO_EXTI_GET_IT

__HAL_GPIO_EXTI_CLEAR_IT

UM1816

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

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

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

GPIO_MODE_INPUT

GPIO_MODE_OUTPUT_PP

GPIO_MODE_OUTPUT_OD

GPIO_MODE_AF_PP

GPIO_MODE_AF_OD

GPIO_MODE_ANALOG

GPIO_MODE_IT_RISING

GPIO_MODE_IT_FALLING

GPIO_MODE_IT_RISING_FALLING

Input Floating Mode

Output Push Pull Mode

Output Open Drain Mode

Alternate Function Push Pull Mode

Alternate Function Open Drain Mode

Analog Mode

External Interrupt Mode with Rising edge trigger detection

External Interrupt Mode with Falling edge trigger detection

External Interrupt Mode with Rising/Falling edge

228/654 DOCID026682 Rev 3

UM1816

GPIO_MODE_EVT_RISING

GPIO_MODE_EVT_FALLING

HAL GPIO Generic Driver trigger detection

External Event Mode with Rising edge trigger detection

External Event Mode with Falling edge trigger detection

GPIO_MODE_EVT_RISING_FALLING External Event Mode with Rising/Falling edge trigger detection

GPIO pins

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

GPIO_PIN_12

GPIO_PIN_13

GPIO_PIN_14

GPIO_PIN_15

GPIO_PIN_All

GPIO_PIN_MASK

GPIO Private Constants

GPIO_MODE

EXTI_MODE

GPIO_MODE_IT

GPIO_MODE_EVT

RISING_EDGE

FALLING_EDGE

GPIO_OUTPUT_TYPE

GPIO_NUMBER

GPIO Private Macros

IS_GPIO_PIN_ACTION

DOCID026682 Rev 3 229/654

HAL GPIO Generic Driver

IS_GPIO_PIN

IS_GPIO_PULL

IS_GPIO_SPEED

IS_GPIO_MODE

GPIO pull

GPIO_NOPULL

GPIO_PULLUP

GPIO_PULLDOWN

GPIO speed

No Pull-up or Pull-down activation

Pull-up activation

Pull-down activation

GPIO_SPEED_VERY_LOW Very Low speed

GPIO_SPEED_LOW Low speed

GPIO_SPEED_MEDIUM

GPIO_SPEED_HIGH

Medium speed

High speed

UM1816

230/654 DOCID026682 Rev 3

UM1816

HAL GPIO Extension Driver

20 HAL GPIO Extension Driver

20.1 HAL GPIO Extension Driver

20.2 GPIOEx Firmware driver defines

20.2.1 GPIOEx

GPIOEx Alternate function selection

GPIO_AF0_MCO MCO Alternate Function mapping

GPIO_AF0_TAMPER TAMPER Alternate Function mapping

GPIO_AF0_SWJ

GPIO_AF0_TRACE

GPIO_AF0_RTC_50Hz

GPIO_AF1_TIM2

GPIO_AF2_TIM3

GPIO_AF2_TIM4

GPIO_AF2_TIM5

GPIO_AF3_TIM9

GPIO_AF3_TIM10

GPIO_AF3_TIM11

GPIO_AF4_I2C1

GPIO_AF4_I2C2

GPIO_AF5_SPI1

GPIO_AF5_SPI2

GPIO_AF6_SPI3

GPIO_AF7_USART1

GPIO_AF7_USART2

GPIO_AF7_USART3

GPIO_AF8_UART4

GPIO_AF8_UART5

GPIO_AF11_LCD

GPIO_AF12_FSMC

GPIO_AF12_SDIO

GPIO_AF14_TIM_IC1

GPIO_AF14_TIM_IC2

GPIO_AF14_TIM_IC3

SWJ (SWD and JTAG) Alternate Function mapping

TRACE Alternate Function mapping

RTC_OUT Alternate Function mapping

TIM2 Alternate Function mapping

TIM3 Alternate Function mapping

TIM4 Alternate Function mapping

TIM5 Alternate Function mapping

TIM9 Alternate Function mapping

TIM10 Alternate Function mapping

TIM11 Alternate Function mapping

I2C1 Alternate Function mapping

I2C2 Alternate Function mapping

SPI1/I2S1 Alternate Function mapping

SPI2/I2S2 Alternate Function mapping

SPI3/I2S3 Alternate Function mapping

USART1 Alternate Function mapping

USART2 Alternate Function mapping

USART3 Alternate Function mapping

UART4 Alternate Function mapping

UART5 Alternate Function mapping

LCD Alternate Function mapping

FSMC Alternate Function mapping

SDIO Alternate Function mapping

TIMER INPUT CAPTURE Alternate Function mapping

TIMER INPUT CAPTURE Alternate Function mapping

TIMER INPUT CAPTURE Alternate Function mapping

DOCID026682 Rev 3 231/654

HAL GPIO Extension Driver

GPIO_AF14_TIM_IC4

UM1816

TIMER INPUT CAPTURE Alternate Function mapping

GPIO_AF15_EVENTOUT EVENTOUT Alternate Function mapping

GPIOEx Private Macros

IS_GPIO_AF

GPIO_GET_INDEX

232/654 DOCID026682 Rev 3

UM1816

HAL I2C Generic Driver

21 HAL I2C Generic Driver

21.1 HAL I2C Generic Driver

21.2 I2C Firmware driver registers structures

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

21.2.2 I2C_HandleTypeDef

DOCID026682 Rev 3 233/654

HAL I2C Generic Driver

Data Fields

I2C_TypeDef * Instance

I2C_InitTypeDef Init

uint8_t * pBuffPtr

uint16_t XferSize

__IO uint16_t XferCount

DMA_HandleTypeDef * hdmatx

DMA_HandleTypeDef * hdmarx

HAL_LockTypeDef Lock

__IO HAL_I2C_StateTypeDef State

__IO uint32_t ErrorCode

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

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 uint32_t I2C_HandleTypeDef::ErrorCode

UM1816

21.3 I2C Firmware driver API description

21.3.1 How to use this driver

The I2C HAL driver can be used as follows:

1. Declare a I2C_HandleTypeDef handle structure, for example: I2C_HandleTypeDef hi2c;

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

234/654 DOCID026682 Rev 3

UM1816

HAL I2C Generic Driver

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 initilalized 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 Channel

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

4. Initialize the I2C registers by calling the HAL_I2C_Init(), configures also the low level

Hardware (GPIO, CLOCK, NVIC...etc) by calling the customed

HAL_I2C_MspInit(&hi2c) API.

5. To check if target device is ready for communication, use the function

HAL_I2C_IsDeviceReady()

6. 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()

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()

DOCID026682 Rev 3 235/654

HAL I2C Generic Driver

UM1816

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

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()

236/654 DOCID026682 Rev 3

UM1816

HAL I2C Generic Driver

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

21.3.2 Initialization and de-initialization functions

This subsection provides a set of functions allowing to initialize and de-initialiaze the I2Cx peripheral:

User must Implement HAL_I2C_MspInit() function in which he configures all related peripherals resources (CLOCK, GPIO, DMA, IT and NVIC).

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

This section contains the following APIs:

HAL_I2C_Init()

HAL_I2C_DeInit()

HAL_I2C_MspInit()

HAL_I2C_MspDeInit()

21.3.3 IO operation functions

This subsection provides a set of functions allowing to manage the I2C data transfers.

1. There are two modes of transfer:

DOCID026682 Rev 3 237/654

HAL I2C Generic Driver

UM1816

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.

2. 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()

3. 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_Mem_Write_IT()

HAL_I2C_Mem_Read_IT()

4. No-Blocking mode functions with DMA are :

HAL_I2C_Master_Transmit_DMA()

HAL_I2C_Master_Receive_DMA()

HAL_I2C_Slave_Transmit_DMA()

HAL_I2C_Slave_Receive_DMA()

HAL_I2C_Mem_Write_DMA()

HAL_I2C_Mem_Read_DMA()

5. 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()

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_Slave_Transmit_IT()

HAL_I2C_Slave_Receive_IT()

HAL_I2C_Master_Transmit_DMA()

HAL_I2C_Master_Receive_DMA()

HAL_I2C_Slave_Transmit_DMA()

HAL_I2C_Slave_Receive_DMA()

HAL_I2C_Mem_Write()

HAL_I2C_Mem_Read()

238/654 DOCID026682 Rev 3

UM1816

HAL I2C Generic Driver

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_MemTxCpltCallback()

HAL_I2C_MemRxCpltCallback()

HAL_I2C_ErrorCallback()

21.3.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_I2C_GetState()

HAL_I2C_GetError()

21.3.5 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

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

HAL status

21.3.6 HAL_I2C_DeInit

Function Name

HAL_StatusTypeDef HAL_I2C_DeInit (I2C_HandleTypeDef *

hi2c)

Function Description DeInitializes the I2C peripheral.

Parameters

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

HAL status

21.3.7 HAL_I2C_MspInit

Function Name void HAL_I2C_MspInit (I2C_HandleTypeDef * hi2c)

Function Description I2C MSP Init.

Parameters

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

None

21.3.8 HAL_I2C_MspDeInit

DOCID026682 Rev 3 239/654

HAL I2C Generic Driver

Function Name void HAL_I2C_MspDeInit (I2C_HandleTypeDef * hi2c)

UM1816

Function Description I2C MSP DeInit.

Parameters

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

Return values

None

21.3.9 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

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

DevAddress: Target device address

pData: Pointer to data buffer

Size: Amount of data to be sent

Timeout: Timeout duration

HAL status

21.3.10 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

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

DevAddress: Target device address

pData: Pointer to data buffer

Size: Amount of data to be sent

Timeout: Timeout duration

HAL status

21.3.11 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

240/654 DOCID026682 Rev 3

UM1816

21.3.12 HAL_I2C_Slave_Receive

Function Name

HAL I2C Generic Driver

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

Return values

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

HAL status

21.3.13 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

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

DevAddress: Target device address

pData: Pointer to data buffer

Size: Amount of data to be sent

HAL status

21.3.14 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

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

DevAddress: Target device address

pData: Pointer to data buffer

Size: Amount of data to be sent

HAL status

21.3.15 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

DOCID026682 Rev 3 241/654

HAL I2C Generic Driver

UM1816

Return values

pData: Pointer to data buffer

Size: Amount of data to be sent

HAL status

21.3.16 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

Return values

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

HAL status

21.3.17 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

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

DevAddress: Target device address

pData: Pointer to data buffer

Size: Amount of data to be sent

HAL status

21.3.18 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

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

DevAddress: Target device address

pData: Pointer to data buffer

Size: Amount of data to be sent

HAL status

21.3.19 HAL_I2C_Slave_Transmit_DMA

Function Name

HAL_StatusTypeDef HAL_I2C_Slave_Transmit_DMA

(I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size)

242/654 DOCID026682 Rev 3

UM1816

HAL I2C Generic Driver

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

21.3.20 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

Return values

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

HAL status

21.3.21 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

Return values

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

HAL status

21.3.22 HAL_I2C_Mem_Read

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

DOCID026682 Rev 3 243/654

HAL I2C Generic Driver

UM1816

Return values

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

HAL status

21.3.23 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

Return values

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

HAL status

21.3.24 HAL_I2C_Mem_Read_IT

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.

Parameters

Return values

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

HAL status

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

244/654 DOCID026682 Rev 3

UM1816

Parameters

Return values

HAL I2C Generic Driver

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

HAL status

21.3.26 HAL_I2C_Mem_Read_DMA

Function Name

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)

Function Description Reads an amount of data in no-blocking mode with DMA from a specific memory address.

Parameters

Return values

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

HAL status

21.3.27 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

Notes

HAL status

This function is used with Memory devices

21.3.28 HAL_I2C_EV_IRQHandler

Function Name void HAL_I2C_EV_IRQHandler (I2C_HandleTypeDef * hi2c)

Function Description This function handles I2C event interrupt request.

Parameters

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

HAL status

DOCID026682 Rev 3 245/654

HAL I2C Generic Driver

21.3.29 HAL_I2C_ER_IRQHandler

UM1816

Function Name void HAL_I2C_ER_IRQHandler (I2C_HandleTypeDef * hi2c)

Function Description This function handles I2C error interrupt request.

Parameters

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

HAL status

21.3.30 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

21.3.31 HAL_I2C_MasterRxCpltCallback

Function Name

void HAL_I2C_MasterRxCpltCallback (I2C_HandleTypeDef *

hi2c)

Function Description Master Rx Transfer completed callbacks.

Parameters

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

None

21.3.32 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

21.3.33 HAL_I2C_SlaveRxCpltCallback

Function Name

void HAL_I2C_SlaveRxCpltCallback (I2C_HandleTypeDef *

hi2c)

Function Description Slave Rx Transfer completed callbacks.

Parameters

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

None

21.3.34 HAL_I2C_MemTxCpltCallback

246/654 DOCID026682 Rev 3

UM1816

Function Name

HAL I2C Generic Driver

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

21.3.35 HAL_I2C_MemRxCpltCallback

Function Name

void HAL_I2C_MemRxCpltCallback (I2C_HandleTypeDef *

hi2c)

Function Description Memory Rx Transfer completed callbacks.

Parameters

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

None

21.3.36 HAL_I2C_ErrorCallback

Function Name void HAL_I2C_ErrorCallback (I2C_HandleTypeDef * hi2c)

Function Description I2C error callbacks.

Parameters

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

None

21.3.37 HAL_I2C_GetState

Function Name

HAL_I2C_StateTypeDef HAL_I2C_GetState

(I2C_HandleTypeDef * hi2c)

Function Description Returns the I2C state.

Parameters

Return values

hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module

HAL state

21.3.38 HAL_I2C_GetError

Function Name uint32_t HAL_I2C_GetError (I2C_HandleTypeDef * hi2c)

Function Description Return the I2C error code.

Parameters

Return values

hi2c: : pointer to a I2C_HandleTypeDef structure that contains the configuration information for the specified I2C.

I2C Error Code

21.4 I2C Firmware driver defines

21.4.1 I2C

I2C_addressing_mode

DOCID026682 Rev 3 247/654

HAL I2C Generic Driver

I2C_ADDRESSINGMODE_7BIT

I2C_ADDRESSINGMODE_10BIT

IS_I2C_ADDRESSING_MODE

I2C_Clock_Speed_definition

IS_I2C_CLOCK_SPEED

I2C_dual_addressing_mode

I2C_DUALADDRESS_DISABLE

I2C_DUALADDRESS_ENABLE

IS_I2C_DUAL_ADDRESS

I2C_duty_cycle_in_fast_mode

I2C_DUTYCYCLE_2

I2C_DUTYCYCLE_16_9

IS_I2C_DUTY_CYCLE

UM1816

I2C Error Codes

HAL_I2C_ERROR_NONE

HAL_I2C_ERROR_BERR

HAL_I2C_ERROR_ARLO

No error

BERR error

ARLO error

HAL_I2C_ERROR_AF

HAL_I2C_ERROR_OVR

AF error

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.

__HAL_I2C_ENABLE_IT

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

Description:

Enable or disable the specified I2C interrupts.

Parameters:

__HANDLE__: specifies the I2C Handle.

This parameter can be I2Cx where x: 1 or 2 to select the I2C peripheral.

__INTERRUPT__: specifies the interrupt source to enable or disable. This parameter

248/654 DOCID026682 Rev 3

UM1816

__HAL_I2C_DISABLE_IT

__HAL_I2C_GET_IT_SOURCE

__HAL_I2C_GET_FLAG

HAL I2C Generic Driver 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

Description:

Checks if the specified I2C interrupt source is enabled or disabled.

Parameters:

__HANDLE__: specifies the I2C Handle.

This parameter can be I2Cx where x: 1 or 2 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).

Description:

Checks whether the specified I2C flag is set or not.

Parameters:

__HANDLE__: specifies the I2C Handle.

This parameter can be I2Cx where x: 1 or 2 to select the I2C peripheral.

__FLAG__: specifies the flag to check. This parameter can be one of the following values:

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

DOCID026682 Rev 3 249/654

HAL I2C Generic Driver

250/654

__HAL_I2C_CLEAR_FLAG

__HAL_I2C_CLEAR_ADDRFLAG

__HAL_I2C_CLEAR_STOPFLAG

UM1816

flag

I2C_FLAG_ADDR: Address sent flag

Address matched flag

I2C_FLAG_SB: Start bit flag

I2C_FLAG_DUALF: Dual flag

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

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 I2Cx where x: 1 or 2 to select the I2C peripheral.

__FLAG__: specifies the flag to clear. This parameter can be any combination of the following values:

I2C_FLAG_OVR: Overrun/Underrun flag (Slave mode)

I2C_FLAG_AF: Acknowledge failure flag

I2C_FLAG_ARLO: Arbitration lost flag

(Master mode)

I2C_FLAG_BERR: Bus error flag

Return value:

None

Description:

Clears the I2C ADDR pending flag.

Parameters:

__HANDLE__: specifies the I2C Handle.

This parameter can be I2Cx where x: 1 or 2 to select the I2C peripheral.

Return value:

None

Description:

Clears the I2C STOPF pending flag.

Parameters:

__HANDLE__: specifies the I2C Handle.

DOCID026682 Rev 3

UM1816

__HAL_I2C_ENABLE

__HAL_I2C_DISABLE

I2C_Flag_definition

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_GENCALL

I2C_FLAG_TRA

I2C_FLAG_BUSY

I2C_FLAG_MSL

I2C_FLAG_MASK

DOCID026682 Rev 3

HAL I2C Generic Driver

This parameter can be I2Cx where x: 1 or 2 to select the I2C peripheral.

Return value:

None

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

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

251/654

HAL I2C Generic Driver

I2C_general_call_addressing_mode

I2C_GENERALCALL_DISABLE

I2C_GENERALCALL_ENABLE

IS_I2C_GENERAL_CALL

I2C_Interrupt_configuration_definition

I2C_IT_BUF

I2C_IT_EVT

I2C_IT_ERR

I2C_Memory_Address_Size

I2C_MEMADD_SIZE_8BIT

I2C_MEMADD_SIZE_16BIT

IS_I2C_MEMADD_SIZE

I2C_nostretch_mode

I2C_NOSTRETCH_DISABLE

I2C_NOSTRETCH_ENABLE

IS_I2C_NO_STRETCH

I2C_Own_Address1_definition

IS_I2C_OWN_ADDRESS1

I2C_Own_Address2_definition

IS_I2C_OWN_ADDRESS2

I2C Private Constants

I2C_TIMEOUT_FLAG

I2C_TIMEOUT_ADDR_SLAVE

I2C_MIN_PCLK_FREQ

I2C Private Macros

I2C_FREQ_RANGE

I2C_RISE_TIME

I2C_SPEED_STANDARD

I2C_SPEED_FAST

I2C_SPEED

I2C_7BIT_ADD_WRITE

I2C_7BIT_ADD_READ

I2C_10BIT_ADDRESS

I2C_10BIT_HEADER_WRITE

I2C_10BIT_HEADER_READ

I2C_MEM_ADD_MSB

252/654 DOCID026682 Rev 3

UM1816

UM1816

I2C_MEM_ADD_LSB

HAL I2C Generic Driver

DOCID026682 Rev 3 253/654

HAL I2S Generic Driver

UM1816

22 HAL I2S Generic Driver

22.1 HAL I2S Generic Driver

22.2 I2S Firmware driver registers structures

22.2.1 I2S_InitTypeDef

Data Fields

uint32_t Mode

uint32_t Standard

uint32_t DataFormat

uint32_t MCLKOutput

uint32_t AudioFreq

uint32_t CPOL

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

22.2.2 I2S_HandleTypeDef

Data Fields

SPI_TypeDef * Instance

I2S_InitTypeDef Init

uint16_t * pTxBuffPtr

__IO uint16_t TxXferSize

__IO uint16_t TxXferCount

uint16_t * pRxBuffPtr

__IO uint16_t RxXferSize

254/654 DOCID026682 Rev 3

UM1816

__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

HAL I2S Generic Driver

22.3 I2S Firmware driver API description

22.3.1 How to use this driver

The I2S HAL driver can be used as follow:

1. Declare a I2S_HandleTypeDef handle structure.

2. 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. 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 Channel.

Enable the DMAx interface clock.

Configure the declared DMA handle structure with the required Tx/Rx parameters.

Configure the DMA Tx/Rx Channel.

Associate the initilalized DMA handle to the I2S DMA Tx/Rx handle.

Configure the priority and enable the NVIC for the transfer complete interrupt on the DMA Tx/Rx Channel.

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

DOCID026682 Rev 3 255/654

HAL I2S Generic Driver

UM1816

macros __HAL_I2S_ENABLE_IT() and __HAL_I2S_DISABLE_IT() inside the transmit and receive process. Make sure that either: External clock source is configured after setting correctly the define constant HSE_VALUE in the stm32l1xx_hal_conf.h file.

4. Three mode of operations 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

Pause the DMA Transfer using HAL_I2S_DMAPause()

Resume the DMA Transfer using HAL_I2S_DMAResume()

Stop the DMA Transfer using HAL_I2S_DMAStop()

256/654 DOCID026682 Rev 3

UM1816

HAL I2S Generic Driver

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

22.3.2 Initialization and de-initialization functions

This subsection provides a set of functions allowing to initialize and de-initialiaze 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 periperal.

This section contains the following APIs:

HAL_I2S_Init()

HAL_I2S_DeInit()

HAL_I2S_MspInit()

HAL_I2S_MspDeInit()

22.3.3 IO operation functions

This subsection provides a set of functions allowing to manage the I2S data transfers.

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

2. Blocking mode functions are :

HAL_I2S_Transmit()

HAL_I2S_Receive()

3. No-Blocking mode functions with Interrupt are :

HAL_I2S_Transmit_IT()

DOCID026682 Rev 3 257/654

HAL I2S Generic Driver

HAL_I2S_Receive_IT()

4. No-Blocking mode functions with DMA are :

HAL_I2S_Transmit_DMA()

HAL_I2S_Receive_DMA()

5. 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()

UM1816

22.3.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()

22.3.5 HAL_I2S_Init

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

22.3.6 HAL_I2S_DeInit

Function Name

HAL_StatusTypeDef HAL_I2S_DeInit (I2S_HandleTypeDef *

hi2s)

Function Description DeInitializes the I2S peripheral.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

HAL status

258/654 DOCID026682 Rev 3

UM1816

22.3.7 HAL_I2S_MspInit

HAL I2S Generic Driver

Function Name void HAL_I2S_MspInit (I2S_HandleTypeDef * hi2s)

Function Description I2S MSP Init.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

None

22.3.8 HAL_I2S_MspDeInit

Function Name void HAL_I2S_MspDeInit (I2S_HandleTypeDef * hi2s)

Function Description I2S MSP DeInit.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

None

22.3.9 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

Return values

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

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

22.3.10 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

DOCID026682 Rev 3 259/654

HAL I2S Generic Driver

Return values

Notes

UM1816

HAL status

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 continouse way and as the I2S is not disabled at the end of the I2S transaction.

22.3.11 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

Return values

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:

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

22.3.12 HAL_I2S_Receive_IT

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.

Parameters

Return values

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:

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.

260/654 DOCID026682 Rev 3

UM1816

HAL I2S Generic Driver

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.

22.3.13 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

Notes

HAL status

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

22.3.14 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

Notes

HAL status

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

22.3.15 HAL_I2S_DMAPause

Function Name

HAL_StatusTypeDef HAL_I2S_DMAPause

DOCID026682 Rev 3 261/654

HAL I2S Generic Driver

UM1816

(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

22.3.16 HAL_I2S_DMAResume

Function Name

HAL_StatusTypeDef HAL_I2S_DMAResume

(I2S_HandleTypeDef * hi2s)

Function Description Resumes the audio stream playing from the Media.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

HAL status

22.3.17 HAL_I2S_DMAStop

Function Name

HAL_StatusTypeDef HAL_I2S_DMAStop (I2S_HandleTypeDef

* hi2s)

Function Description Resumes the audio stream playing from the Media.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

HAL status

22.3.18 HAL_I2S_IRQHandler

Function Name void HAL_I2S_IRQHandler (I2S_HandleTypeDef * hi2s)

Function Description This function handles I2S interrupt request.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

None

22.3.19 HAL_I2S_TxHalfCpltCallback

Function Name void HAL_I2S_TxHalfCpltCallback (I2S_HandleTypeDef * hi2s)

Function Description Tx Transfer Half completed callbacks.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

None

22.3.20 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

262/654 DOCID026682 Rev 3

UM1816

Return values

HAL I2S Generic Driver the configuration information for I2S module

None

22.3.21 HAL_I2S_RxHalfCpltCallback

Function Name

void HAL_I2S_RxHalfCpltCallback (I2S_HandleTypeDef * hi2s)

Function Description Rx Transfer half completed callbacks.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

None

22.3.22 HAL_I2S_RxCpltCallback

Function Name

void HAL_I2S_RxCpltCallback (I2S_HandleTypeDef * hi2s)

Function Description Rx Transfer completed callbacks.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

None

22.3.23 HAL_I2S_ErrorCallback

Function Name

void HAL_I2S_ErrorCallback (I2S_HandleTypeDef * hi2s)

Function Description I2S error callbacks.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

None

22.3.24 HAL_I2S_GetState

Function Name

HAL_I2S_StateTypeDef HAL_I2S_GetState

(I2S_HandleTypeDef * hi2s)

Function Description Return the I2S state.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

HAL state

22.3.25 HAL_I2S_GetError

Function Name uint32_t HAL_I2S_GetError (I2S_HandleTypeDef * hi2s)

Function Description Return the I2S error code.

Parameters

Return values

hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module

I2S Error Code

DOCID026682 Rev 3 263/654

HAL I2S Generic Driver

22.4 I2S Firmware driver defines

UM1816

22.4.1 I2S

I2S Audio Frequency

I2S_AUDIOFREQ_192K

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

IS_I2S_AUDIO_FREQ

I2S Clock Polarity

I2S_CPOL_LOW

I2S_CPOL_HIGH

IS_I2S_CPOL

I2S Data Format

I2S_DATAFORMAT_16B

I2S_DATAFORMAT_16B_EXTENDED

I2S_DATAFORMAT_24B

I2S_DATAFORMAT_32B

IS_I2S_DATA_FORMAT

I2S Error Codes

HAL_I2S_ERROR_NONE No error

HAL_I2S_ERROR_UDR I2S Underrun error

HAL_I2S_ERROR_OVR I2S 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:

264/654 DOCID026682 Rev 3

UM1816

__HAL_I2S_ENABLE

__HAL_I2S_DISABLE

__HAL_I2S_ENABLE_IT

__HAL_I2S_DISABLE_IT

__HAL_I2S_GET_IT_SOURCE

__HAL_I2S_GET_FLAG

HAL I2S Generic Driver

None

Description:

Enable or disable the specified SPI peripheral (in I2S mode).

Parameters:

__HANDLE__: specifies the I2S Handle.

Return value:

None

Description:

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

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

Description:

DOCID026682 Rev 3 265/654

HAL I2S Generic Driver

__HAL_I2S_CLEAR_OVRFLAG

__HAL_I2S_CLEAR_UDRFLAG

I2S Flag definition

I2S_FLAG_TXE

I2S_FLAG_UDR

I2S_FLAG_OVR

I2S_FLAG_RXNE

I2S_FLAG_FRE

I2S_FLAG_CHSIDE

I2S_FLAG_BSY

I2S Interrupt configuration definition

UM1816

Checks whether the specified I2S flag is set 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).

Description:

Clears the I2S OVR pending flag.

Parameters:

__HANDLE__: specifies the I2S Handle.

Return value:

None

Description:

Clears the I2S UDR pending flag.

Parameters:

__HANDLE__: specifies the I2S Handle.

Return value:

None

266/654 DOCID026682 Rev 3

UM1816

I2S_IT_TXE

I2S_IT_RXNE

I2S_IT_ERR

I2S MCLK Output

I2S_MCLKOUTPUT_ENABLE

I2S_MCLKOUTPUT_DISABLE

IS_I2S_MCLK_OUTPUT

I2S Mode

I2S_MODE_SLAVE_TX

I2S_MODE_SLAVE_RX

I2S_MODE_MASTER_TX

I2S_MODE_MASTER_RX

IS_I2S_MODE

I2S Standard

I2S_STANDARD_PHILIPS

I2S_STANDARD_MSB

I2S_STANDARD_LSB

I2S_STANDARD_PCM_SHORT

I2S_STANDARD_PCM_LONG

IS_I2S_STANDARD

HAL I2S Generic Driver

DOCID026682 Rev 3 267/654

HAL IRDA Generic Driver

UM1816

23 HAL IRDA Generic Driver

23.1 HAL IRDA Generic Driver

23.2 IRDA Firmware driver registers structures

23.2.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) / (16 * (hirda-

>Init.BaudRate)))FractionalDivider = ((IntegerDivider - ((uint32_t) IntegerDivider)) * 16)

+ 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_Transfer_Mode

uint8_t IRDA_InitTypeDef::Prescaler

Specifies the Prescaler value prescaler value to be programmed in the IrDA lowpower Baud Register, for defining pulse width on which burst acceptance/rejection will be decided. This value is used as divisor of system clock to achieve required pulse width.

uint32_t IRDA_InitTypeDef::IrDAMode

Specifies the IrDA mode This parameter can be a value of

IRDA_Low_Power

23.2.2 IRDA_HandleTypeDef

Data Fields

USART_TypeDef * Instance

268/654 DOCID026682 Rev 3

UM1816

HAL IRDA Generic Driver

IRDA_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_IRDA_StateTypeDef State

__IO uint32_t ErrorCode

Field Documentation

USART_TypeDef* IRDA_HandleTypeDef::Instance

USART registers base address

IRDA_InitTypeDef IRDA_HandleTypeDef::Init

IRDA communication parameters

uint8_t* IRDA_HandleTypeDef::pTxBuffPtr

Pointer to IRDA Tx transfer Buffer

uint16_t IRDA_HandleTypeDef::TxXferSize

IRDA Tx Transfer size

uint16_t IRDA_HandleTypeDef::TxXferCount

IRDA Tx Transfer Counter

uint8_t* IRDA_HandleTypeDef::pRxBuffPtr

Pointer to IRDA Rx transfer Buffer

uint16_t IRDA_HandleTypeDef::RxXferSize

IRDA Rx Transfer size

uint16_t IRDA_HandleTypeDef::RxXferCount

IRDA Rx Transfer Counter

DMA_HandleTypeDef* IRDA_HandleTypeDef::hdmatx

IRDA Tx DMA Handle parameters

DMA_HandleTypeDef* IRDA_HandleTypeDef::hdmarx

IRDA Rx DMA Handle parameters

HAL_LockTypeDef IRDA_HandleTypeDef::Lock

Locking object

__IO HAL_IRDA_StateTypeDef IRDA_HandleTypeDef::State

IRDA communication state

__IO uint32_t IRDA_HandleTypeDef::ErrorCode

IRDA Error code

23.3 IRDA Firmware driver API description

23.3.1 How to use this driver

The IRDA HAL driver can be used as follows:

1. Declare a IRDA_HandleTypeDef handle structure.

2. Initialize the IRDA low level resources by implementing the HAL_IRDA_MspInit() API: a. Enable the USARTx interface clock. b. IRDA pins configuration:

DOCID026682 Rev 3 269/654

HAL IRDA Generic Driver

Enable the clock for the IRDA GPIOs.

Configure the IRDA pins as alternate function pull-up. c. NVIC configuration if you need to use interrupt process

UM1816

(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 channel.

Enable the DMAx interface clock.

Configure the declared DMA handle structure with the required Tx/Rx parameters.

Configure the DMA Tx/Rx channel.

Associate the initilalized 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 channel.

Configure the USARTx interrupt priority and enable the NVIC USART IRQ handle (used for last byte sending completion detection in DMA non circular mode)

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 customed 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

270/654

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

DOCID026682 Rev 3

UM1816

HAL IRDA Generic Driver

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

Below the list of most used macros in IRDA HAL driver.

__HAL_IRDA_ENABLE: Enable the IRDA peripheral

__HAL_IRDA_DISABLE: Disable the IRDA peripheral

__HAL_IRDA_GET_FLAG : Check whether the specified IRDA flag is set or not

__HAL_IRDA_CLEAR_FLAG : Clear the specified IRDA pending flag

__HAL_IRDA_ENABLE_IT: Enable the specified IRDA interrupt

__HAL_IRDA_DISABLE_IT: Disable the specified IRDA interrupt

__HAL_IRDA_GET_IT_SOURCE: Check whether the specified IRDA interrupt has occurred or not

You can refer to the IRDA HAL driver header file for more useful macros

23.3.2 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:

Baud Rate

Word Length

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), the possible IRDA frame formats are

as listed in

Table 18: "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.

M bit PCE bit

Table 18: IRDA frame formats

IRDA frame

0 0 | SB | 8 bit data | STB |

0

1

1

0

| SB | 7 bit data | PB | STB |

| SB | 9 bit data | STB |

1 1 | SB | 8 bit data | PB | STB |

The HAL_IRDA_Init() function follows IRDA configuration procedures (details for the procedures are available in reference manual (RM0038)).

DOCID026682 Rev 3 271/654

HAL IRDA Generic Driver

This section contains the following APIs:

HAL_IRDA_Init()

HAL_IRDA_DeInit()

HAL_IRDA_MspInit()

HAL_IRDA_MspDeInit()

UM1816

23.3.3 IO operation functions

This subsection provides a set of functions allowing to manage the IRDA data transfers.

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

2. Blocking mode APIs are :

HAL_IRDA_Transmit()

HAL_IRDA_Receive()

3. Non Blocking mode APIs with Interrupt are :

HAL_IRDA_Transmit_IT()

HAL_IRDA_Receive_IT()

HAL_IRDA_IRQHandler()

4. Non Blocking mode functions with DMA are :

HAL_IRDA_Transmit_DMA()

HAL_IRDA_Receive_DMA()

HAL_IRDA_DMAPause()

HAL_IRDA_DMAResume()

HAL_IRDA_DMAStop()

5. A set of Transfer Complete Callbacks are provided in non Blocking mode:

HAL_IRDA_TxHalfCpltCallback()

HAL_IRDA_TxCpltCallback()

HAL_IRDA_RxHalfCpltCallback()

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()

272/654 DOCID026682 Rev 3

UM1816

HAL IRDA Generic Driver

HAL_IRDA_DMAStop()

HAL_IRDA_IRQHandler()

HAL_IRDA_TxCpltCallback()

HAL_IRDA_TxHalfCpltCallback()

HAL_IRDA_RxCpltCallback()

HAL_IRDA_RxHalfCpltCallback()

HAL_IRDA_ErrorCallback()

23.3.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()

23.3.5 HAL_IRDA_Init

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

Return values

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module.

HAL status

23.3.6 HAL_IRDA_DeInit

Function Name

HAL_StatusTypeDef HAL_IRDA_DeInit (IRDA_HandleTypeDef

* hirda)

Function Description DeInitializes the IRDA peripheral.

Parameters

Return values

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module.

HAL status

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

DOCID026682 Rev 3 273/654

HAL IRDA Generic Driver

Return values

None

UM1816

23.3.8 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

23.3.9 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

Return values

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

HAL status

23.3.10 HAL_IRDA_Receive

Function Name

HAL_StatusTypeDef HAL_IRDA_Receive

(IRDA_HandleTypeDef * hirda, uint8_t * pData, uint16_t Size,

uint32_t Timeout)

Function Description Receive an amount of data in blocking mode.

Parameters

Return values

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

HAL status

23.3.11 HAL_IRDA_Transmit_IT

Function Name

HAL_StatusTypeDef HAL_IRDA_Transmit_IT

(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

274/654 DOCID026682 Rev 3

UM1816

Return values

Size: Amount of data to be sent

HAL status

HAL IRDA Generic Driver

23.3.12 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

Return values

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

HAL status

23.3.13 HAL_IRDA_Transmit_DMA

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

23.3.14 HAL_IRDA_Receive_DMA

Function Name

HAL_StatusTypeDef HAL_IRDA_Receive_DMA

(IRDA_HandleTypeDef * hirda, uint8_t * pData, uint16_t Size)

Function Description Receive 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

Notes

HAL status

When the IRDA parity is enabled (PCE = 1) the data received contain the parity bit.

23.3.15 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

DOCID026682 Rev 3 275/654

HAL IRDA Generic Driver

Return values

UM1816

contains the configuration information for the specified IRDA module.

HAL status

23.3.16 HAL_IRDA_DMAResume

Function Name

HAL_StatusTypeDef HAL_IRDA_DMAResume

(IRDA_HandleTypeDef * hirda)

Function Description Resumes the DMA Transfer.

Parameters

Return values

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified UART module.

HAL status

23.3.17 HAL_IRDA_DMAStop

Function Name

HAL_StatusTypeDef HAL_IRDA_DMAStop

(IRDA_HandleTypeDef * hirda)

Function Description Stops the DMA Transfer.

Parameters

Return values

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified UART module.

HAL status

23.3.18 HAL_IRDA_IRQHandler

Function Name void HAL_IRDA_IRQHandler (IRDA_HandleTypeDef * hirda)

Function Description This function handles IRDA interrupt request.

Parameters

Return values

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module.

None

23.3.19 HAL_IRDA_TxCpltCallback

Function Name

void HAL_IRDA_TxCpltCallback (IRDA_HandleTypeDef *

hirda)

Function Description Tx Transfer completed callbacks.

Parameters

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module.

Return values

None

23.3.20 HAL_IRDA_TxHalfCpltCallback

Function Name

void HAL_IRDA_TxHalfCpltCallback (IRDA_HandleTypeDef *

hirda)

276/654 DOCID026682 Rev 3

UM1816

HAL IRDA Generic Driver

Function Description Tx Half Transfer completed callbacks.

Parameters

Return values

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified

USART module.

None

23.3.21 HAL_IRDA_RxCpltCallback

Function Name

void HAL_IRDA_RxCpltCallback (IRDA_HandleTypeDef *

hirda)

Function Description Rx Transfer completed callbacks.

Parameters

Return values

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module.

None

23.3.22 HAL_IRDA_RxHalfCpltCallback

Function Name

void HAL_IRDA_RxHalfCpltCallback (IRDA_HandleTypeDef *

hirda)

Function Description Rx Half Transfer complete callbacks.

Parameters

Return values

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module.

None

23.3.23 HAL_IRDA_ErrorCallback

Function Name void HAL_IRDA_ErrorCallback (IRDA_HandleTypeDef * hirda)

Function Description IRDA error callbacks.

Parameters

Return values

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module.

None

23.3.24 HAL_IRDA_GetState

Function Name

HAL_IRDA_StateTypeDef HAL_IRDA_GetState

(IRDA_HandleTypeDef * hirda)

Function Description Returns the IRDA state.

Parameters

Return values

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module.

HAL state

23.3.25 HAL_IRDA_GetError

DOCID026682 Rev 3 277/654

HAL IRDA Generic Driver

Function Name

UM1816

uint32_t HAL_IRDA_GetError (IRDA_HandleTypeDef * hirda)

Function Description Return the IRDA error code.

Parameters

hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module.

Return values

IRDA Error Code

23.4 IRDA Firmware driver defines

23.4.1 IRDA

IRDA Error Codes

HAL_IRDA_ERROR_NONE No error

HAL_IRDA_ERROR_PE Parity error

HAL_IRDA_ERROR_NE

HAL_IRDA_ERROR_FE

Noise error frame error

HAL_IRDA_ERROR_ORE Overrun error

HAL_IRDA_ERROR_DMA DMA transfer error

IRDA Exported Macros

__HAL_IRDA_RESET_HANDLE_STATE

__HAL_IRDA_FLUSH_DRREGISTER

__HAL_IRDA_GET_FLAG

Description:

Reset IRDA handle state.

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

Description:

Flush the IRDA DR register.

Parameters:

__HANDLE__: specifies the USART

Handle. IRDA Handle selects the

USARTx or UARTy peripheral

(USART,UART availability and x,y values depending on device).

Description:

Check whether the specified IRDA flag is set or not.

Parameters:

__HANDLE__: specifies the IRDA

278/654 DOCID026682 Rev 3

UM1816

__HAL_IRDA_CLEAR_FLAG

HAL IRDA Generic Driver

Handle. IRDA Handle selects the

USARTx or UARTy peripheral

(USART,UART availability and x,y values depending on device).

__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

Return value:

The: new state of __FLAG__ (TRUE or FALSE).

Description:

Clear the specified IRDA pending flag.

Parameters:

__HANDLE__: specifies the IRDA

Handle. IRDA Handle selects the

USARTx or UARTy peripheral

(USART,UART availability and x,y values depending on device).

__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

DOCID026682 Rev 3 279/654

HAL IRDA Generic Driver

280/654

__HAL_IRDA_CLEAR_PEFLAG

__HAL_IRDA_CLEAR_FEFLAG

__HAL_IRDA_CLEAR_NEFLAG

__HAL_IRDA_CLEAR_OREFLAG

UM1816

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.

Description:

Clear the IRDA PE pending flag.

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

Description:

Clear the IRDA FE pending flag.

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

Description:

Clear the IRDA NE pending flag.

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

Description:

Clear the IRDA ORE pending flag.

DOCID026682 Rev 3

UM1816

__HAL_IRDA_CLEAR_IDLEFLAG

__HAL_IRDA_ENABLE_IT

__HAL_IRDA_DISABLE_IT

HAL IRDA Generic Driver

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

Description:

Clear the IRDA IDLE pending flag.

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

Description:

Enable the specified IRDA interrupt.

Parameters:

__HANDLE__: specifies the IRDA

Handle. IRDA Handle selects the

USARTx or UARTy peripheral

(USART,UART availability and x,y values depending on device).

__INTERRUPT__: specifies the IRDA interrupt source to enable. 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

Description:

DOCID026682 Rev 3 281/654

HAL IRDA Generic Driver

282/654

__HAL_IRDA_GET_IT_SOURCE

UM1816

Disable the specified IRDA interrupt.

Parameters:

__HANDLE__: specifies the IRDA

Handle. IRDA Handle selects the

USARTx or UARTy peripheral

(USART,UART availability and x,y values depending on device).

__INTERRUPT__: specifies the IRDA interrupt source to disable. 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

Description:

Check whether the specified IRDA interrupt has occurred or not.

Parameters:

__HANDLE__: specifies the IRDA

Handle. IRDA Handle selects the

USARTx or UARTy peripheral

(USART,UART availability and x,y values depending on device).

__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

IRDA_IT_ERR: Error interrupt

IRDA_IT_PE: Parity Error interrupt

DOCID026682 Rev 3

UM1816

HAL IRDA Generic Driver

Return value:

The: new state of __IT__ (TRUE or

FALSE).

__HAL_IRDA_ONE_BIT_SAMPLE_ENABLE Description:

Enables the IRDA one bit sample method.

Parameters:

__HANDLE__: specifies the IRDA

Handle.

Return value:

None

__HAL_IRDA_ONE_BIT_SAMPLE_DISABLE Description:

Disables the IRDA one bit sample method.

Parameters:

__HANDLE__: specifies the IRDA

Handle.

__HAL_IRDA_ENABLE

Return value:

None

Description:

Enable UART/USART associated to

IRDA Handle.

__HAL_IRDA_DISABLE

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

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

Return value:

None

DOCID026682 Rev 3 283/654

HAL IRDA Generic Driver

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 One Bit Sampling

IRDA_ONE_BIT_SAMPLE_DISABLE

IRDA_ONE_BIT_SAMPLE_ENABLE

IRDA Parity

IRDA_PARITY_NONE

IRDA_PARITY_EVEN

IRDA_PARITY_ODD

IRDA Private Constants

IRDA_DR_MASK_U16_8DATABITS

IRDA_DR_MASK_U16_9DATABITS

IRDA_DR_MASK_U8_7DATABITS

IRDA_DR_MASK_U8_8DATABITS

IRDA Private Macros

IRDA_CR1_REG_INDEX

IRDA_CR2_REG_INDEX

284/654 DOCID026682 Rev 3

UM1816

UM1816

HAL IRDA Generic Driver

IRDA_CR3_REG_INDEX

IRDA_DIV

IRDA_DIVMANT

IRDA_DIVFRAQ

IRDA_BRR

IS_IRDA_BAUDRATE

IS_IRDA_WORD_LENGTH

IS_IRDA_PARITY

The maximum Baud Rate is 115200bps Returns : True or

False

IS_IRDA_MODE

IRDA_IT_MASK

IS_IRDA_POWERMODE

IRDA Transfer Mode

IRDA_MODE_RX

IRDA_MODE_TX

IRDA_MODE_TX_RX

IRDA Word Length

IRDA_WORDLENGTH_8B

IRDA_WORDLENGTH_9B

DOCID026682 Rev 3 285/654

HAL IWDG Generic Driver

UM1816

24 HAL IWDG Generic Driver

24.1 HAL IWDG Generic Driver

24.2 IWDG Firmware driver registers structures

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

24.2.2 IWDG_HandleTypeDef

Data Fields

IWDG_TypeDef * Instance

IWDG_InitTypeDef Init

HAL_LockTypeDef Lock

__IO HAL_IWDG_StateTypeDef State

Field Documentation

IWDG_TypeDef* IWDG_HandleTypeDef::Instance

Register base address

IWDG_InitTypeDef IWDG_HandleTypeDef::Init

IWDG required parameters

HAL_LockTypeDef IWDG_HandleTypeDef::Lock

IWDG Locking object

__IO HAL_IWDG_StateTypeDef IWDG_HandleTypeDef::State

IWDG communication state

24.3 IWDG Firmware driver API description

24.3.1 Initialization and de-initialization functions

This section provides functions allowing to:

286/654 DOCID026682 Rev 3

UM1816

HAL IWDG Generic Driver

Initialize the IWDG according to the specified parameters in the IWDG_InitTypeDef and create the associated handle

Initialize the IWDG MSP

DeInitialize IWDG MSP

This section contains the following APIs:

HAL_IWDG_Init()

HAL_IWDG_MspInit()

24.3.2 IO operation functions

This section provides functions allowing to:

Start the IWDG.

Refresh the IWDG.

This section contains the following APIs:

HAL_IWDG_Start()

HAL_IWDG_Refresh()

24.3.3 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_IWDG_GetState()

24.3.4 HAL_IWDG_Init

Function Name

HAL_StatusTypeDef HAL_IWDG_Init (IWDG_HandleTypeDef *

hiwdg)

Function Description Initializes the IWDG according to the specified parameters in the

IWDG_InitTypeDef and creates the associated handle.

Parameters

Return values

hiwdg: pointer to a IWDG_HandleTypeDef structure that contains the configuration information for the specified IWDG module.

HAL status

24.3.5 HAL_IWDG_MspInit

Function Name void HAL_IWDG_MspInit (IWDG_HandleTypeDef * hiwdg)

Function Description Initializes the IWDG MSP.

Parameters

Return values

hiwdg: pointer to a IWDG_HandleTypeDef structure that contains the configuration information for the specified IWDG module.

None

24.3.6 HAL_IWDG_Start

Function Name

HAL_StatusTypeDef HAL_IWDG_Start (IWDG_HandleTypeDef

* hiwdg)

Function Description Starts the IWDG.

DOCID026682 Rev 3 287/654

HAL IWDG Generic Driver

Parameters

Return values

UM1816

hiwdg: pointer to a IWDG_HandleTypeDef structure that contains the configuration information for the specified IWDG module.

HAL status

24.3.7 HAL_IWDG_Refresh

Function Name

HAL_StatusTypeDef HAL_IWDG_Refresh

(IWDG_HandleTypeDef * hiwdg)

Function Description Refreshes the IWDG.

Parameters

hiwdg: pointer to a IWDG_HandleTypeDef structure that contains the configuration information for the specified IWDG module.

Return values

HAL status

24.3.8 HAL_IWDG_GetState

Function Name

HAL_IWDG_StateTypeDef HAL_IWDG_GetState

(IWDG_HandleTypeDef * hiwdg)

Function Description Returns the IWDG state.

Parameters

Return values

hiwdg: pointer to a IWDG_HandleTypeDef structure that contains the configuration information for the specified IWDG module.

HAL state

24.4 IWDG Firmware driver defines

24.4.1 IWDG

IWDG Exported Macros

__HAL_IWDG_RESET_HANDLE_STATE Description:

Reset IWDG handle state.

Parameters:

__HANDLE__: IWDG handle.

__HAL_IWDG_START

Return value:

None

Description:

Enables the IWDG peripheral.

__HAL_IWDG_RELOAD_COUNTER

Parameters:

__HANDLE__: IWDG handle

Return value:

None

Description:

288/654 DOCID026682 Rev 3

UM1816

__HAL_IWDG_GET_FLAG

HAL IWDG Generic Driver

Reloads IWDG counter with value defined in the reload register (write access to

IWDG_PR and IWDG_RLR registers disabled).

Parameters:

__HANDLE__: IWDG handle

Return value:

None

Description:

Gets the selected IWDG's flag status.

Parameters:

__HANDLE__: IWDG handle

__FLAG__: specifies the flag to check.

This parameter can be one of the following values:

IWDG_FLAG_PVU: Watchdog counter reload value update flag

IWDG_FLAG_RVU: Watchdog counter prescaler value flag

Return value:

The: new state of __FLAG__ (TRUE or

FALSE).

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

IWDG Private Defines

HAL_IWDG_DEFAULT_TIMEOUT

IWDG_KEY_RELOAD

IWDG_KEY_ENABLE

IWDG Reload Counter Enable

IWDG Peripheral Enable

IWDG_KEY_WRITE_ACCESS_ENABLE IWDG KR Write Access Enable

IWDG_KEY_WRITE_ACCESS_DISABLE IWDG KR Write Access Disable

IWDG_FLAG_PVU

IWDG_FLAG_RVU

Watchdog counter prescaler value update flag

Watchdog counter reload value update flag

IWDG Private Macros

IWDG_ENABLE_WRITE_ACCESS Description:

DOCID026682 Rev 3 289/654

HAL IWDG Generic Driver

Enables write access to IWDG_PR and

IWDG_RLR registers.

UM1816

Parameters:

__HANDLE__: IWDG handle

Return value:

None

IWDG_DISABLE_WRITE_ACCESS Description:

Disables write access to IWDG_PR and

IWDG_RLR registers.

IS_IWDG_PRESCALER

IS_IWDG_RELOAD

Parameters:

__HANDLE__: IWDG handle

Return value:

None

Description:

Check IWDG prescaler value.

Parameters:

__PRESCALER__: IWDG prescaler value

Return value:

None

Description:

Check IWDG reload value.

Parameters:

__RELOAD__: IWDG reload value

Return value:

None

290/654 DOCID026682 Rev 3

UM1816

HAL LCD Generic Driver

25 HAL LCD Generic Driver

25.1 HAL LCD Generic Driver

25.2 LCD Firmware driver registers structures

25.2.1 LCD_InitTypeDef

Data Fields

uint32_t Prescaler

uint32_t Divider

uint32_t Duty

uint32_t Bias

uint32_t VoltageSource

uint32_t Contrast

uint32_t DeadTime

uint32_t PulseOnDuration

uint32_t HighDrive

uint32_t BlinkMode

uint32_t BlinkFrequency

uint32_t MuxSegment

Field Documentation

uint32_t LCD_InitTypeDef::Prescaler

Configures the LCD Prescaler. This parameter can be one value of

LCD_Prescaler

uint32_t LCD_InitTypeDef::Divider

Configures the LCD Divider. This parameter can be one value of

LCD_Divider

uint32_t LCD_InitTypeDef::Duty

Configures the LCD Duty. This parameter can be one value of

LCD_Duty

uint32_t LCD_InitTypeDef::Bias

Configures the LCD Bias. This parameter can be one value of

LCD_Bias

uint32_t LCD_InitTypeDef::VoltageSource

Selects the LCD Voltage source. This parameter can be one value of

LCD_Voltage_Source

uint32_t LCD_InitTypeDef::Contrast

Configures the LCD Contrast. This parameter can be one value of

LCD_Contrast

uint32_t LCD_InitTypeDef::DeadTime

Configures the LCD Dead Time. This parameter can be one value of

LCD_DeadTime

uint32_t LCD_InitTypeDef::PulseOnDuration

Configures the LCD Pulse On Duration. This parameter can be one value of

LCD_PulseOnDuration

uint32_t LCD_InitTypeDef::HighDrive

Configures the LCD High Drive. This parameter can be one value of

LCD_HighDrive

uint32_t LCD_InitTypeDef::BlinkMode

Configures the LCD Blink Mode. This parameter can be one value of

LCD_BlinkMode

DOCID026682 Rev 3 291/654

HAL LCD Generic Driver

uint32_t LCD_InitTypeDef::BlinkFrequency

UM1816

Configures the LCD Blink frequency. This parameter can be one value of

LCD_BlinkFrequency

uint32_t LCD_InitTypeDef::MuxSegment

Enable or disable mux segment. This parameter can be set to ENABLE or DISABLE.

25.2.2 LCD_HandleTypeDef

Data Fields

LCD_TypeDef * Instance

LCD_InitTypeDef Init

HAL_LockTypeDef Lock

__IO HAL_LCD_StateTypeDef State

__IO uint32_t ErrorCode

Field Documentation

LCD_TypeDef* LCD_HandleTypeDef::Instance

LCD_InitTypeDef LCD_HandleTypeDef::Init

HAL_LockTypeDef LCD_HandleTypeDef::Lock

__IO HAL_LCD_StateTypeDef LCD_HandleTypeDef::State

__IO uint32_t LCD_HandleTypeDef::ErrorCode

25.3 LCD Firmware driver API description

25.3.1 How to use this driver

The LCD HAL driver can be used as follows:

1. Declare a LCD_HandleTypeDef handle structure.

2. Initialize the LCD low level resources by implement the HAL_LCD_MspInit() API: a. Enable the LCDCLK (same as RTCCLK): to configure the RTCCLK/LCDCLK, proceed as follows:

Use RCC function HAL_RCCEx_PeriphCLKConfig in indicating

RCC_PERIPHCLK_LCD and selected clock source (HSE, LSI or LSE)

The frequency generator allows you to achieve various LCD frame rates starting from an LCD input clock frequency (LCDCLK) which can vary from

32 kHz up to 1 MHz. b. LCD pins configuration:

Enable the clock for the LCD GPIOs.

Configure these LCD pins as alternate function no-pull. c. Enable the LCD interface clock.

3. Program the Prescaler, Divider, Blink mode, Blink Frequency Duty, Bias, Voltage

Source, Dead Time, Pulse On Duration and Contrast in the hlcd Init structure.

4. Initialize the LCD registers by calling the HAL_LCD_Init() API. The HAL_LCD_Init()

API configures also the low level Hardware GPIO, CLOCK, ...etc) by calling the custumed HAL_LCD_MspInit() API. After calling the HAL_LCD_Init() the LCD RAM memory is cleared

5. Optionally you can update the LCD configuration using these macros:

292/654 DOCID026682 Rev 3

UM1816

HAL LCD Generic Driver

LCD High Drive using the __HAL_LCD_HIGHDRIVER_ENABLE() and

__HAL_LCD_HIGHDRIVER_DISABLE() macros

LCD Pulse ON Duration using the

__HAL_LCD_PULSEONDURATION_CONFIG() macro

LCD Dead Time using the __HAL_LCD_DEADTIME_CONFIG() macro

The LCD Blink mode and frequency using the __HAL_LCD_BLINK_CONFIG() macro

The LCD Contrast using the __HAL_LCD_CONTRAST_CONFIG() macro

6. Write to the LCD RAM memory using the HAL_LCD_Write() API, this API can be called more time to update the different LCD RAM registers before calling

HAL_LCD_UpdateDisplayRequest() API.

7. The HAL_LCD_Clear() API can be used to clear the LCD RAM memory.

8. When LCD RAM memory is updated enable the update display request using the

HAL_LCD_UpdateDisplayRequest() API.

LCD and low power modes:

1. The LCD remain active during STOP mode.

25.3.2 Initialization and Configuration functions

This section contains the following APIs:

HAL_LCD_DeInit()

HAL_LCD_Init()

HAL_LCD_MspDeInit()

HAL_LCD_MspInit()

25.3.3 IO operation functions

Using its double buffer memory the LCD controller ensures the coherency of the displayed information without having to use interrupts to control LCD_RAM modification.

The application software can access the first buffer level (LCD_RAM) through the APB interface. Once it has modified the LCD_RAM using the HAL_LCD_Write() API, it sets the UDR flag in the LCD_SR register using the HAL_LCD_UpdateDisplayRequest()

API. This UDR flag (update display request) requests the updated information to be moved into the second buffer level (LCD_DISPLAY).

This operation is done synchronously with the frame (at the beginning of the next frame), until the update is completed, the LCD_RAM is write protected and the UDR flag stays high.

Once the update is completed another flag (UDD - Update Display Done) is set and generates an interrupt if the UDDIE bit in the LCD_FCR register is set. The time it takes to update LCD_DISPLAY is, in the worst case, one odd and one even frame.

The update will not occur (UDR = 1 and UDD = 0) until the display is enabled (LCDEN

= 1).

This section contains the following APIs:

HAL_LCD_Write()

HAL_LCD_Clear()

HAL_LCD_UpdateDisplayRequest()

25.3.4 Peripheral State functions

This subsection provides a set of functions allowing to control the LCD:

DOCID026682 Rev 3 293/654

HAL LCD Generic Driver

UM1816

HAL_LCD_GetState() API can be helpful to check in run-time the state of the LCD peripheral State.

HAL_LCD_GetError() API to return the LCD error code.

This section contains the following APIs:

HAL_LCD_GetState()

HAL_LCD_GetError()

25.3.5 HAL_LCD_DeInit

Function Name

HAL_StatusTypeDef HAL_LCD_DeInit (LCD_HandleTypeDef *

hlcd)

Function Description DeInitializes the LCD peripheral.

Parameters

hlcd: LCD handle

Return values

HAL status

25.3.6 HAL_LCD_Init

Function Name

HAL_StatusTypeDef HAL_LCD_Init (LCD_HandleTypeDef *

hlcd)

Function Description Initializes the LCD peripheral according to the specified parameters in the LCD_InitStruct.

Parameters

Notes

Return values

hlcd: LCD handle

None

This function can be used only when the LCD is disabled. The

LCD HighDrive can be enabled/disabled using related macros up to user.

25.3.7 HAL_LCD_MspDeInit

Function Name

void HAL_LCD_MspDeInit (LCD_HandleTypeDef * hlcd)

Function Description LCD MSP DeInit.

Parameters

hlcd: LCD handle

Return values

None

25.3.8 HAL_LCD_MspInit

Function Name void HAL_LCD_MspInit (LCD_HandleTypeDef * hlcd)

Function Description LCD MSP Init.

Parameters

hlcd: LCD handle

Return values

None

25.3.9 HAL_LCD_Write

Function Name

HAL_StatusTypeDef HAL_LCD_Write (LCD_HandleTypeDef * hlcd, uint32_t RAMRegisterIndex, uint32_t RAMRegisterMask,

uint32_t Data)

294/654 DOCID026682 Rev 3

UM1816

Function Description Writes a word in the specific LCD RAM.

HAL LCD Generic Driver

Parameters

Return values

hlcd: LCD handle

RAMRegisterIndex: specifies the LCD RAM Register. This parameter can be one of the following values:

LCD_RAM_REGISTER0: LCD RAM Register

0LCD_RAM_REGISTER1: LCD RAM Register

1LCD_RAM_REGISTER2: LCD RAM Register

2LCD_RAM_REGISTER3: LCD RAM Register

3LCD_RAM_REGISTER4: LCD RAM Register

4LCD_RAM_REGISTER5: LCD RAM Register

5LCD_RAM_REGISTER6: LCD RAM Register

6LCD_RAM_REGISTER7: LCD RAM Register

7LCD_RAM_REGISTER8: LCD RAM Register

8LCD_RAM_REGISTER9: LCD RAM Register

9LCD_RAM_REGISTER10: LCD RAM Register

10LCD_RAM_REGISTER11: LCD RAM Register

11LCD_RAM_REGISTER12: LCD RAM Register

12LCD_RAM_REGISTER13: LCD RAM Register

13LCD_RAM_REGISTER14: LCD RAM Register

14LCD_RAM_REGISTER15: LCD RAM Register 15

RAMRegisterMask: specifies the LCD RAM Register Data

Mask.

Data: specifies LCD Data Value to be written.

None

25.3.10 HAL_LCD_Clear

Function Name

HAL_StatusTypeDef HAL_LCD_Clear (LCD_HandleTypeDef *

hlcd)

Function Description Clears the LCD RAM registers.

Parameters

hlcd: LCD handle

Return values

None

25.3.11 HAL_LCD_UpdateDisplayRequest

Function Name

HAL_StatusTypeDef HAL_LCD_UpdateDisplayRequest

(LCD_HandleTypeDef * hlcd)

Function Description Enables the Update Display Request.

Parameters

hlcd: LCD handle

Return values

Notes

None

Each time software modifies the LCD_RAM it must set the

UDR bit to transfer the updated data to the second level buffer. The UDR bit stays set until the end of the update and during this time the LCD_RAM is write protected.

When the display is disabled, the update is performed for all

LCD_DISPLAY locations. When the display is enabled, the update is performed only for locations for which commons are active (depending on DUTY). For example if DUTY = 1/2, only the LCD_DISPLAY of COM0 and COM1 will be updated.

DOCID026682 Rev 3 295/654

HAL LCD Generic Driver

25.3.12 HAL_LCD_GetState

Function Name

HAL_LCD_StateTypeDef HAL_LCD_GetState

(LCD_HandleTypeDef * hlcd)

Function Description Returns the LCD state.

Parameters

hlcd: LCD handle

Return values

HAL state

UM1816

25.3.13 HAL_LCD_GetError

Function Name uint32_t HAL_LCD_GetError (LCD_HandleTypeDef * hlcd)

Function Description Return the LCD error code.

Parameters

hlcd: LCD handle

Return values

LCD Error Code

25.4 LCD Firmware driver defines

25.4.1 LCD

LCD Bias

LCD_BIAS_1_4

LCD_BIAS_1_2

1/4 Bias

1/2 Bias

LCD_BIAS_1_3

IS_LCD_BIAS

1/3 Bias

LCD Blink Frequency

LCD_BLINKFREQUENCY_DIV8

LCD_BLINKFREQUENCY_DIV16

LCD_BLINKFREQUENCY_DIV32

LCD_BLINKFREQUENCY_DIV64

The Blink frequency = fLCD/8

The Blink frequency = fLCD/16

The Blink frequency = fLCD/32

The Blink frequency = fLCD/64

LCD_BLINKFREQUENCY_DIV128 The Blink frequency = fLCD/128

LCD_BLINKFREQUENCY_DIV256 The Blink frequency = fLCD/256

LCD_BLINKFREQUENCY_DIV512 The Blink frequency = fLCD/512

LCD_BLINKFREQUENCY_DIV1024 The Blink frequency = fLCD/1024

IS_LCD_BLINK_FREQUENCY

LCD Blink Mode

LCD_BLINKMODE_OFF

LCD_BLINKMODE_SEG0_COM0

LCD_BLINKMODE_SEG0_ALLCOM

Blink disabled

Blink enabled on SEG[0], COM[0] (1 pixel)

Blink enabled on SEG[0], all COM (up to 8 pixels according to the programmed duty)

LCD_BLINKMODE_ALLSEG_ALLCOM Blink enabled on all SEG and all COM (all pixels)

IS_LCD_BLINK_MODE

296/654 DOCID026682 Rev 3

UM1816

HAL LCD Generic Driver

LCD Contrast

LCD_CONTRASTLEVEL_0 Maximum Voltage = 2.60V

LCD_CONTRASTLEVEL_1 Maximum Voltage = 2.73V

LCD_CONTRASTLEVEL_2 Maximum Voltage = 2.86V

LCD_CONTRASTLEVEL_3 Maximum Voltage = 2.99V

LCD_CONTRASTLEVEL_4 Maximum Voltage = 3.12V

LCD_CONTRASTLEVEL_5 Maximum Voltage = 3.25V

LCD_CONTRASTLEVEL_6 Maximum Voltage = 3.38V

LCD_CONTRASTLEVEL_7 Maximum Voltage = 3.51V

IS_LCD_CONTRAST

LCD Dead Time

LCD_DEADTIME_0

LCD_DEADTIME_1

No dead Time

One Phase between different couple of Frame

LCD_DEADTIME_2

LCD_DEADTIME_3

LCD_DEADTIME_4

LCD_DEADTIME_5

Two Phase between different couple of Frame

Three Phase between different couple of Frame

Four Phase between different couple of Frame

Five Phase between different couple of Frame

LCD_DEADTIME_6

LCD_DEADTIME_7

IS_LCD_DEAD_TIME

LCD Divider

Six Phase between different couple of Frame

Seven Phase between different couple of Frame

LCD_DIVIDER_16

LCD_DIVIDER_17

LCD_DIVIDER_18

LCD_DIVIDER_19

LCD_DIVIDER_20

LCD_DIVIDER_21

LCD_DIVIDER_22

LCD frequency = CLKPS/16

LCD frequency = CLKPS/17

LCD frequency = CLKPS/18

LCD frequency = CLKPS/19

LCD frequency = CLKPS/20

LCD frequency = CLKPS/21

LCD frequency = CLKPS/22

LCD_DIVIDER_23

LCD_DIVIDER_24

LCD_DIVIDER_25

LCD_DIVIDER_26

LCD_DIVIDER_27

LCD_DIVIDER_28

LCD_DIVIDER_29

LCD_DIVIDER_30

LCD frequency = CLKPS/23

LCD frequency = CLKPS/24

LCD frequency = CLKPS/25

LCD frequency = CLKPS/26

LCD frequency = CLKPS/27

LCD frequency = CLKPS/28

LCD frequency = CLKPS/29

LCD frequency = CLKPS/30

DOCID026682 Rev 3 297/654

HAL LCD Generic Driver

LCD_DIVIDER_31 LCD frequency = CLKPS/31

IS_LCD_DIVIDER

LCD Duty

LCD_DUTY_STATIC Static duty

LCD_DUTY_1_2 1/2 duty

LCD_DUTY_1_3

LCD_DUTY_1_4

LCD_DUTY_1_8

IS_LCD_DUTY

1/3 duty

1/4 duty

1/8 duty

LCD Error Codes

HAL_LCD_ERROR_NONE No error

HAL_LCD_ERROR_FCRSF Synchro flag timeout error

HAL_LCD_ERROR_UDR Update display request flag timeout error

UM1816

HAL_LCD_ERROR_UDD

HAL_LCD_ERROR_ENS

HAL_LCD_ERROR_RDY

LCD Exported Macros

Update display done flag timeout error

LCD enabled status flag timeout error

LCD Booster ready timeout error

__HAL_LCD_RESET_HANDLE_STATE Description:

Reset LCD handle state.

__HAL_LCD_ENABLE

Parameters:

__HANDLE__: specifies the LCD Handle.

Return value:

None

Description:

 macros to enables or disables the LCD

__HAL_LCD_DISABLE

__HAL_LCD_HIGHDRIVER_ENABLE

Parameters:

__HANDLE__: specifies the LCD Handle.

Return value:

None

Description:

Macros to enable or disable the low resistance divider.

Parameters:

__HANDLE__: specifies the LCD Handle.

Return value:

298/654 DOCID026682 Rev 3

UM1816

HAL LCD Generic Driver

None

Notes:

When this mode is enabled, the PulseOn

Duration (PON) have to be programmed to

1/CK_PS (LCD_PULSEONDURATION_1).

__HAL_LCD_HIGHDRIVER_DISABLE

__HAL_LCD_PULSEONDURATION_C

ONFIG

Description:

Macro to configure the LCD pulses on duration.

Parameters:

__HANDLE__: specifies the LCD Handle.

__DURATION__: specifies the LCD pulse on duration in terms of CK_PS (prescaled

LCD clock period) pulses. This parameter can be one of the following values:

LCD_PULSEONDURATION_0: 0 pulse

LCD_PULSEONDURATION_1: Pulse

ON duration = 1/CK_PS

LCD_PULSEONDURATION_2: Pulse

ON duration = 2/CK_PS

LCD_PULSEONDURATION_3: Pulse

ON duration = 3/CK_PS

LCD_PULSEONDURATION_4: Pulse

ON duration = 4/CK_PS

LCD_PULSEONDURATION_5: Pulse

ON duration = 5/CK_PS

LCD_PULSEONDURATION_6: Pulse

ON duration = 6/CK_PS

LCD_PULSEONDURATION_7: Pulse

ON duration = 7/CK_PS

__HAL_LCD_DEADTIME_CONFIG

Return value:

None

Description:

Macro to configure the LCD dead time.

Parameters:

__HANDLE__: specifies the LCD Handle.

__DEADTIME__: specifies the LCD dead time. This parameter can be one of the following values:

LCD_DEADTIME_0: No dead Time

LCD_DEADTIME_1: One Phase between different couple of Frame

LCD_DEADTIME_2: Two Phase between different couple of Frame

LCD_DEADTIME_3: Three Phase between different couple of Frame

DOCID026682 Rev 3 299/654

HAL LCD Generic Driver

300/654

__HAL_LCD_CONTRAST_CONFIG

__HAL_LCD_BLINK_CONFIG

UM1816

LCD_DEADTIME_4: Four Phase between different couple of Frame

LCD_DEADTIME_5: Five Phase between different couple of Frame

LCD_DEADTIME_6: Six Phase between different couple of Frame

LCD_DEADTIME_7: Seven Phase between different couple of Frame

Return value:

None

Description:

Macro to configure the LCD Contrast.

Parameters:

__HANDLE__: specifies the LCD Handle.

__CONTRAST__: specifies the LCD

Contrast. This parameter can be one of the following values:

LCD_CONTRASTLEVEL_0:

Maximum Voltage = 2.60V

LCD_CONTRASTLEVEL_1:

Maximum Voltage = 2.73V

LCD_CONTRASTLEVEL_2:

Maximum Voltage = 2.86V

LCD_CONTRASTLEVEL_3:

Maximum Voltage = 2.99V

LCD_CONTRASTLEVEL_4:

Maximum Voltage = 3.12V

LCD_CONTRASTLEVEL_5:

Maximum Voltage = 3.25V

LCD_CONTRASTLEVEL_6:

Maximum Voltage = 3.38V

LCD_CONTRASTLEVEL_7:

Maximum Voltage = 3.51V

Return value:

None

Description:

Macro to configure the LCD Blink mode and Blink frequency.

Parameters:

__HANDLE__: specifies the LCD Handle.

__BLINKMODE__: specifies the LCD blink mode. This parameter can be one of the following values:

LCD_BLINKMODE_OFF: Blink disabled

LCD_BLINKMODE_SEG0_COM0:

Blink enabled on SEG[0], COM[0] (1 pixel)

DOCID026682 Rev 3

UM1816

__HAL_LCD_ENABLE_IT

__HAL_LCD_DISABLE_IT

__HAL_LCD_GET_IT_SOURCE

HAL LCD Generic Driver

LCD_BLINKMODE_SEG0_ALLCOM:

Blink enabled on SEG[0], all COM (up to 8 pixels according to the programmed duty)

LCD_BLINKMODE_ALLSEG_ALLCO

M: Blink enabled on all SEG and all

COM (all pixels)

__BLINKFREQUENCY__: specifies the

LCD blink frequency.

LCD_BLINKFREQUENCY_DIV8: The

Blink frequency = fLcd/8

LCD_BLINKFREQUENCY_DIV16:

The Blink frequency = fLcd/16

LCD_BLINKFREQUENCY_DIV32:

The Blink frequency = fLcd/32

LCD_BLINKFREQUENCY_DIV64:

The Blink frequency = fLcd/64

LCD_BLINKFREQUENCY_DIV128:

The Blink frequency = fLcd/128

LCD_BLINKFREQUENCY_DIV256:

The Blink frequency = fLcd/256

LCD_BLINKFREQUENCY_DIV512:

The Blink frequency = fLcd/512

LCD_BLINKFREQUENCY_DIV1024:

The Blink frequency = fLcd/1024

Return value:

None

Description:

Enables or disables the specified LCD interrupt.

Parameters:

__HANDLE__: specifies the LCD Handle.

__INTERRUPT__: specifies the LCD interrupt source to be enabled or disabled.

This parameter can be one of the following values:

LCD_IT_SOF: Start of Frame

Interrupt

LCD_IT_UDD: Update Display Done

Interrupt

Return value:

None

Description:

Checks whether the specified LCD interrupt is enabled or not.

Parameters:

__HANDLE__: specifies the LCD Handle.

DOCID026682 Rev 3 301/654

HAL LCD Generic Driver

302/654

__HAL_LCD_GET_FLAG

UM1816

__IT__: specifies the LCD interrupt source to check. This parameter can be one of the following values:

LCD_IT_SOF: Start of Frame

Interrupt

LCD_IT_UDD: Update Display Done

Interrupt.

Return value:

The: state of __IT__ (TRUE or FALSE).

Notes:

If the device is in STOP mode (PCLK not provided) UDD will not generate an interrupt even if UDDIE = 1. If the display is not enabled the UDD interrupt will never occur.

Description:

Checks whether the specified LCD flag is set or not.

Parameters:

__HANDLE__: specifies the LCD Handle.

__FLAG__: specifies the flag to check.

This parameter can be one of the following values:

LCD_FLAG_ENS: LCD Enabled flag.

It indicates the LCD controller status.

Return value:

The: new state of __FLAG__ (TRUE or

FALSE).

Notes:

The ENS bit is set immediately when the

LCDEN bit in the LCD_CR goes from 0 to

1. On deactivation it reflects the real status of LCD so it becomes 0 at the end of the last displayed frame. LCD_FLAG_SOF:

Start of Frame flag. This flag is set by hardware at the beginning of a new frame, at the same time as the display data is updated. LCD_FLAG_UDR: Update

Display Request flag. LCD_FLAG_UDD:

Update Display Done flag.

LCD_FLAG_RDY: Step_up converter

Ready flag. It indicates the status of the step-up converter. LCD_FLAG_FCRSF:

LCD Frame Control Register

Synchronization Flag. This flag is set by hardware each time the LCD_FCR register is updated in the LCDCLK domain.

Description: __HAL_LCD_CLEAR_FLAG

DOCID026682 Rev 3

UM1816

LCD Flag

LCD_FLAG_ENS

LCD_FLAG_SOF

LCD_FLAG_UDR

LCD_FLAG_UDD

LCD_FLAG_RDY

LCD_FLAG_FCRSF

LCD HighDrive

LCD_HIGHDRIVE_0 Low resistance Drive

HAL LCD Generic Driver

Clears the specified LCD pending flag.

Parameters:

__HANDLE__: specifies the LCD Handle.

__FLAG__: specifies the flag to clear. This parameter can be any combination of the following values:

LCD_FLAG_SOF: Start of Frame

Interrupt

LCD_FLAG_UDD: Update Display

Done Interrupt

Return value:

None

LCD_HIGHDRIVE_1 High resistance Drive

IS_LCD_HIGHDRIVE

LCD Interrupts

LCD_IT_SOF

LCD_IT_UDD

LCD Mux Segment

LCD_MUXSEGMENT_DISABLE SEG pin multiplexing disabled

LCD_MUXSEGMENT_ENABLE SEG[31:28] are multiplexed with SEG[43:40]

IS_LCD_MUXSEGMENT

LCD Prescaler

LCD_PRESCALER_1 CLKPS = LCDCLK

LCD_PRESCALER_2

LCD_PRESCALER_4

LCD_PRESCALER_8

LCD_PRESCALER_16

CLKPS = LCDCLK/2

CLKPS = LCDCLK/4

CLKPS = LCDCLK/8

CLKPS = LCDCLK/16

LCD_PRESCALER_32

LCD_PRESCALER_64

LCD_PRESCALER_128

CLKPS = LCDCLK/32

CLKPS = LCDCLK/64

CLKPS = LCDCLK/128

DOCID026682 Rev 3 303/654

HAL LCD Generic Driver

LCD_PRESCALER_256 CLKPS = LCDCLK/256

LCD_PRESCALER_512 CLKPS = LCDCLK/512

LCD_PRESCALER_1024 CLKPS = LCDCLK/1024

LCD_PRESCALER_2048 CLKPS = LCDCLK/2048

LCD_PRESCALER_4096 CLKPS = LCDCLK/4096

LCD_PRESCALER_8192 CLKPS = LCDCLK/8192

LCD_PRESCALER_16384 CLKPS = LCDCLK/16384

LCD_PRESCALER_32768 CLKPS = LCDCLK/32768

IS_LCD_PRESCALER

LCD Private Defines

LCD_TIMEOUT_VALUE

LCD Pulse On Duration

LCD_PULSEONDURATION_0 Pulse ON duration = 0 pulse

LCD_PULSEONDURATION_1

LCD_PULSEONDURATION_2

LCD_PULSEONDURATION_3

LCD_PULSEONDURATION_4

Pulse ON duration = 1/CK_PS

Pulse ON duration = 2/CK_PS

Pulse ON duration = 3/CK_PS

Pulse ON duration = 4/CK_PS

LCD_PULSEONDURATION_5

LCD_PULSEONDURATION_6

Pulse ON duration = 5/CK_PS

Pulse ON duration = 6/CK_PS

LCD_PULSEONDURATION_7

IS_LCD_PULSE_ON_DURATION

Pulse ON duration = 7/CK_PS

LCD RAMRegister

LCD_RAM_REGISTER0 LCD RAM Register 0

LCD_RAM_REGISTER1 LCD RAM Register 1

LCD_RAM_REGISTER2 LCD RAM Register 2

LCD_RAM_REGISTER3 LCD RAM Register 3

LCD_RAM_REGISTER4 LCD RAM Register 4

LCD_RAM_REGISTER5 LCD RAM Register 5

LCD_RAM_REGISTER6 LCD RAM Register 6

LCD_RAM_REGISTER7 LCD RAM Register 7

LCD_RAM_REGISTER8 LCD RAM Register 8

LCD_RAM_REGISTER9 LCD RAM Register 9

LCD_RAM_REGISTER10 LCD RAM Register 10

LCD_RAM_REGISTER11 LCD RAM Register 11

LCD_RAM_REGISTER12 LCD RAM Register 12

LCD_RAM_REGISTER13 LCD RAM Register 13

304/654 DOCID026682 Rev 3

UM1816

UM1816

HAL LCD Generic Driver

LCD_RAM_REGISTER14 LCD RAM Register 14

LCD_RAM_REGISTER15 LCD RAM Register 15

IS_LCD_RAM_REGISTER

LCD Voltage Source

LCD_VOLTAGESOURCE_INTERNAL Internal voltage source for the LCD

LCD_VOLTAGESOURCE_EXTERNAL External voltage source for the LCD

IS_LCD_VOLTAGE_SOURCE

DOCID026682 Rev 3 305/654

HAL NOR Generic Driver

UM1816

26 HAL NOR Generic Driver

26.1 HAL NOR Generic Driver

26.2 NOR Firmware driver registers structures

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

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

306/654 DOCID026682 Rev 3

UM1816

26.2.3 NOR_HandleTypeDef

HAL NOR Generic Driver

Data Fields

FSMC_NORSRAM_TypeDef * Instance

FSMC_NORSRAM_EXTENDED_TypeDef * Extended

FSMC_NORSRAM_InitTypeDef Init

HAL_LockTypeDef Lock

__IO HAL_NOR_StateTypeDef State

Field Documentation

FSMC_NORSRAM_TypeDef* NOR_HandleTypeDef::Instance

Register base address

FSMC_NORSRAM_EXTENDED_TypeDef* NOR_HandleTypeDef::Extended

Extended mode register base address

FSMC_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

26.3 NOR Firmware driver API description

26.3.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 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()

DOCID026682 Rev 3 307/654

HAL NOR Generic Driver

UM1816

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

26.3.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()

26.3.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()

26.3.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()

26.3.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()

26.3.6 HAL_NOR_Init

308/654 DOCID026682 Rev 3

UM1816

Function Name

HAL NOR Generic Driver

HAL_StatusTypeDef HAL_NOR_Init (NOR_HandleTypeDef * hnor, FSMC_NORSRAM_TimingTypeDef * Timing,

FSMC_NORSRAM_TimingTypeDef * ExtTiming)

Function Description Perform the NOR memory Initialization sequence.

Parameters

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

Timing: pointer to NOR control timing structure

ExtTiming: pointer to NOR extended mode timing structure

HAL status

26.3.7 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

26.3.8 HAL_NOR_MspInit

Function Name void HAL_NOR_MspInit (NOR_HandleTypeDef * hnor)

Function Description NOR MSP Init.

Parameters

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

None

26.3.9 HAL_NOR_MspDeInit

Function Name

void HAL_NOR_MspDeInit (NOR_HandleTypeDef * hnor)

Function Description NOR MSP DeInit.

Parameters

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

None

26.3.10 HAL_NOR_MspWait

Function Name

void HAL_NOR_MspWait (NOR_HandleTypeDef * hnor,

uint32_t Timeout)

Function Description NOR MSP Wait fro Ready/Busy signal.

Parameters

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

Timeout: Maximum timeout value

None

26.3.11 HAL_NOR_Read_ID

DOCID026682 Rev 3 309/654

HAL NOR Generic Driver

Function Name

UM1816

HAL_StatusTypeDef HAL_NOR_Read_ID

(NOR_HandleTypeDef * hnor, NOR_IDTypeDef * pNOR_ID)

Function Description Read NOR flash IDs.

Parameters

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

pNOR_ID: : pointer to NOR ID structure

HAL status

26.3.12 HAL_NOR_ReturnToReadMode

Function Name

HAL_StatusTypeDef HAL_NOR_ReturnToReadMode

(NOR_HandleTypeDef * hnor)

Function Description Returns the NOR memory to Read mode.

Parameters

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

HAL status

26.3.13 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 a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

pAddress: pointer to Device address

pData: : pointer to read data

Return values

HAL status

26.3.14 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

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

pAddress: Device address

pData: : pointer to the data to write

HAL status

26.3.15 HAL_NOR_ReadBuffer

Function Name

HAL_StatusTypeDef HAL_NOR_ReadBuffer

(NOR_HandleTypeDef * hnor, uint32_t uwAddress, uint16_t *

pData, uint32_t uwBufferSize)

Function Description Reads a block of data from the FSMC NOR memory.

Parameters

hnor: pointer to a NOR_HandleTypeDef structure that

310/654 DOCID026682 Rev 3

UM1816

Return values

HAL NOR Generic Driver contains the configuration information for NOR module.

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.

HAL status

26.3.16 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 FSMC NOR memory.

Parameters

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

uwAddress: NOR memory internal address from which the data

pData: pointer to source data buffer.

uwBufferSize: number of Half words to write.

Return values

Notes

HAL status

Some NOR memory need Address aligned to xx bytes (can be aligned to 64 bytes boundary for example).

The maximum buffer size allowed is NOR memory dependent

(can be 64 Bytes max for example).

26.3.17 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

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

BlockAddress: : Block to erase address

Address: Device address

HAL status

26.3.18 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 a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

Address: : Device address

Return values

HAL status

26.3.19 HAL_NOR_Read_CFI

DOCID026682 Rev 3 311/654

HAL NOR Generic Driver

Function Name

UM1816

HAL_StatusTypeDef HAL_NOR_Read_CFI

(NOR_HandleTypeDef * hnor, NOR_CFITypeDef * pNOR_CFI)

Function Description Read NOR flash CFI IDs.

Parameters

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

pNOR_CFI: : pointer to NOR CFI IDs structure

HAL status

26.3.20 HAL_NOR_WriteOperation_Enable

Function Name

HAL_StatusTypeDef HAL_NOR_WriteOperation_Enable

(NOR_HandleTypeDef * hnor)

Function Description Enables dynamically NOR write operation.

Parameters

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

HAL status

26.3.21 HAL_NOR_WriteOperation_Disable

Function Name

HAL_StatusTypeDef HAL_NOR_WriteOperation_Disable

(NOR_HandleTypeDef * hnor)

Function Description Disables dynamically NOR write operation.

Parameters

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

HAL status

26.3.22 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 a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

Return values

NOR controller state

26.3.23 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

Return values

hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module.

Address: Device address

Timeout: NOR progamming Timeout

NOR_Status The returned value can be:

HAL_NOR_STATUS_SUCCESS,

312/654 DOCID026682 Rev 3

UM1816

HAL_NOR_STATUS_ERROR or

HAL_NOR_STATUS_TIMEOUT

HAL NOR Generic Driver

26.4 NOR Firmware driver defines

26.4.1 NOR

NOR Exported Macros

__HAL_NOR_RESET_HANDLE_STATE Description:

Reset NOR handle state.

Parameters:

__HANDLE__: NOR handle

Return value:

None

NOR Private Constants

NOR_CMD_ADDRESS_FIRST

NOR_CMD_ADDRESS_FIRST_CFI

NOR_CMD_ADDRESS_SECOND

NOR_CMD_ADDRESS_THIRD

NOR_CMD_ADDRESS_FOURTH

NOR_CMD_ADDRESS_FIFTH

NOR_CMD_ADDRESS_SIXTH

NOR_CMD_DATA_READ_RESET

NOR_CMD_DATA_FIRST

NOR_CMD_DATA_SECOND

NOR_CMD_DATA_AUTO_SELECT

NOR_CMD_DATA_PROGRAM

NOR_CMD_DATA_CHIP_BLOCK_ERASE_THIRD

NOR_CMD_DATA_CHIP_BLOCK_ERASE_FOURTH

NOR_CMD_DATA_CHIP_BLOCK_ERASE_FIFTH

NOR_CMD_DATA_CHIP_ERASE

NOR_CMD_DATA_CFI

NOR_CMD_DATA_BUFFER_AND_PROG

NOR_CMD_DATA_BUFFER_AND_PROG_CONFIRM

NOR_CMD_DATA_BLOCK_ERASE

NOR_MASK_STATUS_DQ5

NOR_MASK_STATUS_DQ6

MC_ADDRESS

DOCID026682 Rev 3 313/654

HAL NOR Generic Driver

DEVICE_CODE1_ADDR

DEVICE_CODE2_ADDR

DEVICE_CODE3_ADDR

CFI1_ADDRESS

CFI2_ADDRESS

CFI3_ADDRESS

CFI4_ADDRESS

NOR_TMEOUT

NOR_MEMORY_8B

NOR_MEMORY_16B

NOR_MEMORY_ADRESS1

NOR_MEMORY_ADRESS2

NOR_MEMORY_ADRESS3

NOR_MEMORY_ADRESS4

NOR Private Macros

NOR_ADDR_SHIFT Description:

NOR memory address shifting.

Parameters:

__NOR_ADDRESS: NOR base address

__NOR_MEMORY_WIDTH_: NOR memory width

__ADDRESS__: NOR memory address

NOR_WRITE

Return value:

NOR: shifted address value

Description:

NOR memory write data to specified address.

Parameters:

__ADDRESS__: NOR memory address

__DATA__: Data to write

Return value:

None

UM1816

314/654 DOCID026682 Rev 3

UM1816

HAL OPAMP Generic Driver

27 HAL OPAMP Generic Driver

27.1 HAL OPAMP Generic Driver

27.2 OPAMP Firmware driver registers structures

27.2.1 OPAMP_InitTypeDef

Data Fields

uint32_t PowerSupplyRange

uint32_t PowerMode

uint32_t Mode

uint32_t InvertingInput

uint32_t NonInvertingInput

uint32_t UserTrimming

uint32_t TrimmingValueP

uint32_t TrimmingValueN

uint32_t TrimmingValuePLowPower

uint32_t TrimmingValueNLowPower

Field Documentation

uint32_t OPAMP_InitTypeDef::PowerSupplyRange

Specifies the power supply range: above or under 2.4V. This parameter must be a

value of

OPAMP_PowerSupplyRange

Caution: This parameter is common to all

OPAMP instances: a modification of this parameter for the selected OPAMP impacts the other OPAMP instances.

uint32_t OPAMP_InitTypeDef::PowerMode

Specifies the power mode Normal or Low-Power. This parameter must be a value of

OPAMP_PowerMode

uint32_t OPAMP_InitTypeDef::Mode

Specifies the OPAMP mode This parameter must be a value of

OPAMP_Mode

mode

is either Standalone or Follower

uint32_t OPAMP_InitTypeDef::InvertingInput

Specifies the inverting input in Standalone modeIn Standalone mode: i.e when mode is OPAMP_STANDALONE_MODE This parameter must be a value of

OPAMP_InvertingInput

InvertingInput is either VM0 or VM1In Follower mode: i.e

when mode is OPAMP_FOLLOWER_MODE This parameter is Not Applicable

uint32_t OPAMP_InitTypeDef::NonInvertingInput

Specifies the non inverting input of the opamp: This parameter must be a value of

OPAMP_NonInvertingInput

Note: Non-inverting input availability depends on

OPAMP instance: OPAMP1: Non-inverting input is either IO0, DAC_Channel1

OPAMP2: Non-inverting input is either IO0, DAC_Channel1, DAC_Channel2

OPAMP3: Non-inverting input is either IO0, DAC_Channel2 (OPAMP3 availability depends on STM32L1 devices)

uint32_t OPAMP_InitTypeDef::UserTrimming

Specifies the trimming mode This parameter must be a value of

OPAMP_UserTrimming

UserTrimming is either factory or user trimming. Caution:

DOCID026682 Rev 3 315/654

HAL OPAMP Generic Driver

UM1816

This parameter is common to all OPAMP instances: a modification of this parameter for the selected OPAMP impacts the other OPAMP instances.

uint32_t OPAMP_InitTypeDef::TrimmingValueP

Specifies the offset trimming value (PMOS) i.e. when UserTrimming is

OPAMP_TRIMMING_USER. This parameter must be a number between Min_Data =

0 and Max_Data = 30 (Trimming value 31 is forbidden) 16 is typical default value

uint32_t OPAMP_InitTypeDef::TrimmingValueN

Specifies the offset trimming value (NMOS) i.e. when UserTrimming is

OPAMP_TRIMMING_USER. This parameter must be a number between Min_Data =

0 and Max_Data = 30 (Trimming value 31 is forbidden) 16 is typical default value

uint32_t OPAMP_InitTypeDef::TrimmingValuePLowPower

Specifies the offset trimming value (PMOS) i.e. when UserTrimming is

OPAMP_TRIMMING_USER. This parameter must be a number between Min_Data =

0 and Max_Data = 30 (Trimming value 31 is forbidden) 16 is typical default value

uint32_t OPAMP_InitTypeDef::TrimmingValueNLowPower

Specifies the offset trimming value (NMOS) i.e. when UserTrimming is

OPAMP_TRIMMING_USER. This parameter must be a number between Min_Data =

0 and Max_Data = 30 (Trimming value 31 is forbidden) 16 is typical default value

27.2.2 OPAMP_HandleTypeDef

Data Fields

OPAMP_TypeDef * Instance

OPAMP_InitTypeDef Init

HAL_StatusTypeDef Status

HAL_LockTypeDef Lock

__IO HAL_OPAMP_StateTypeDef State

Field Documentation

OPAMP_TypeDef* OPAMP_HandleTypeDef::Instance

OPAMP instance's registers base address

OPAMP_InitTypeDef OPAMP_HandleTypeDef::Init

OPAMP required parameters

HAL_StatusTypeDef OPAMP_HandleTypeDef::Status

OPAMP peripheral status

HAL_LockTypeDef OPAMP_HandleTypeDef::Lock

Locking object

__IO HAL_OPAMP_StateTypeDef OPAMP_HandleTypeDef::State

OPAMP communication state

27.3 OPAMP Firmware driver API description

27.3.1 OPAMP Peripheral Features

The device integrates up to 3 operational amplifiers OPAMP1, OPAMP2, OPAMP3

(OPAMP3 availability depends on device category)

1. The OPAMP(s) provides several exclusive running modes.

Standalone mode

316/654 DOCID026682 Rev 3

UM1816

HAL OPAMP Generic Driver

Follower mode

2. All OPAMP (same for all OPAMPs) can operate in

Either Low range (VDDA < 2.4V) power supply

Or High range (VDDA > 2.4V) power supply

3. Each OPAMP(s) can be configured in normal and low power mode.

4. The OPAMP(s) provide(s) calibration capabilities.

Calibration aims at correcting some offset for running mode.

The OPAMP uses either factory calibration settings OR user defined calibration

(trimming) settings (i.e. trimming mode).

The user defined settings can be figured out using self calibration handled by

HAL_OPAMP_SelfCalibrate, HAL_OPAMPEx_SelfCalibrateAll

HAL_OPAMP_SelfCalibrate:

Runs automatically the calibration in 2 steps: for transistors differential pair high (PMOS) or low (NMOS)

Enables the user trimming mode

Updates the init structure with trimming values with fresh calibration results.

The user may store the calibration results for larger (ex monitoring the trimming as a function of temperature for instance)

For devices having several OPAMPs, HAL_OPAMPEx_SelfCalibrateAll runs calibration of all OPAMPs in parallel to save search time.

5. Running mode: Standalone mode

Gain is set externally (gain depends on external loads).

Follower mode also possible externally by connecting the inverting input to the output.

6. Running mode: Follower mode

No Inverting Input is connected.

The OPAMP(s) output(s) are internally connected to inverting input.

7.

The OPAMPs inverting input can be selected among the list shown in

Table 19:

"OPAMPs inverting/non-inverting inputs for STM32L1 devices"

.

8.

The OPAMPs non inverting input can be selected among the list shown in

Table 19:

"OPAMPs inverting/non-inverting inputs for STM32L1 devices"

.

Table 19: OPAMPs inverting/non-inverting inputs for STM32L1 devices

HAL parameter name OPAMP1 OPAMP2

OPAMP3

(1)

Inverting inputs

(2)

VM0

VM1

PA2

VINM pin

(3)

PA7

VINM pin

PC2

VINM pin non-inverting inputs

VP0

DAC_CH1

(4)

DAC_CH2

PA1

DAC_CH1

-

PA6

DAC_CH1

DAC_CH2

PC1

-

DAC_CH2

Notes:

(1)

OPAMP3 availability depends on device category.

(2)

NA in follower mode.

(3)

OPAMP input OPAMPx_VINM are dedicated OPAMP pins, their availability depends on device package.

(4)

DAC channels 1 and 2 are connected internally to OPAMP. Nevertheless, I/O pins connected to DAC can still be used as DAC output (pins PA4 and PA5).

Table 20: OPAMP outputs for STM32L1 devices

OPAMP1 OPAMP2

OPAMP3

(1)

DOCID026682 Rev 3 317/654

HAL OPAMP Generic Driver

Output

OPAMP1

PA3

OPAMP2

PB0

UM1816

OPAMP3

(1)

PC3

Notes:

(1)

OPAMP3 availability depends on device category.

27.3.2 How to use this driver

power supply range

To run in low power mode:

1. Configure the opamp using HAL_OPAMP_Init() function:

Select OPAMP_POWERSUPPLY_LOW (VDDA lower than 2.4V)

Otherwise select OPAMP_POWERSUPPLY_HIGH (VDDA higher than 2.4V)

low / normal power mode

To run in low power mode:

1. Configure the opamp using HAL_OPAMP_Init() function:

Select OPAMP_POWERMODE_LOWPOWER

Otherwise select OPAMP_POWERMODE_NORMAL

Calibration

To run the opamp calibration self calibration:

1. Start calibration using HAL_OPAMP_SelfCalibrate. Store the calibration results.

Running mode

To use the opamp, perform the following steps:

1. Fill in the HAL_OPAMP_MspInit() to

Enable the OPAMP Peripheral clock using macro

"__HAL_RCC_OPAMP_CLK_ENABLE()"

Configure the opamp input AND output in analog mode using HAL_GPIO_Init() to map the opamp output to the GPIO pin.

2. Configure the opamp using HAL_OPAMP_Init() function:

Select the mode

Select the inverting input

Select the non-inverting input

Select either factory or user defined trimming mode.

If the user defined trimming mode is enabled, select PMOS & NMOS trimming values (typ. settings returned by HAL_OPAMP_SelfCalibrate function).

3. Enable the opamp using HAL_OPAMP_Start() function.

4. Disable the opamp using HAL_OPAMP_Stop() function.

5. Lock the opamp in running mode using HAL_OPAMP_Lock() function. Caution: On

STM32L1, HAL OPAMP lock is software lock only (not hardware lock as on some other STM32 devices)

6. If needed, unlock the opamp using HAL_OPAMPEx_Unlock() function.

318/654 DOCID026682 Rev 3

UM1816

HAL OPAMP Generic Driver

Running mode: change of configuration while OPAMP ON

To Re-configure OPAMP when OPAMP is ON (change on the fly)

1. If needed, Fill in the HAL_OPAMP_MspInit()

This is the case for instance if you wish to use new OPAMP I/O

2. Configure the opamp using HAL_OPAMP_Init() function:

As in configure case, selects first the parameters you wish to modify.

3. Change from low power mode to normal power mode (& vice versa) requires first

HAL_OPAMP_DeInit() (force OPAMP OFF) and then HAL_OPAMP_Init(). In other words, of OPAMP is ON, HAL_OPAMP_Init can NOT change power mode alone.

27.3.3 Initialization and de-initialization functions

This section provides functions allowing to:

This section contains the following APIs:

HAL_OPAMP_Init()

HAL_OPAMP_DeInit()

HAL_OPAMP_MspInit()

HAL_OPAMP_MspDeInit()

27.3.4 IO operation functions

This subsection provides a set of functions allowing to manage the OPAMP start, stop and calibration actions.

This section contains the following APIs:

HAL_OPAMP_Start()

HAL_OPAMP_Stop()

HAL_OPAMP_SelfCalibrate()

27.3.5 Peripheral Control functions

This subsection provides a set of functions allowing to control the OPAMP data transfers.

This section contains the following APIs:

HAL_OPAMP_Lock()

HAL_OPAMP_GetTrimOffset()

27.3.6 Peripheral State functions

This subsection permit to get in run-time the status of the peripheral.

This section contains the following APIs:

HAL_OPAMP_GetState()

27.3.7 HAL_OPAMP_Init

Function Name

HAL_StatusTypeDef HAL_OPAMP_Init

(OPAMP_HandleTypeDef * hopamp)

Function Description Initializes the OPAMP according to the specified parameters in the

OPAMP_InitTypeDef and create the associated handle.

Parameters

hopamp: OPAMP handle

Return values

HAL status

DOCID026682 Rev 3 319/654

HAL OPAMP Generic Driver

Notes

UM1816

If the selected opamp is locked, initialization can't be performed. To unlock the configuration, perform a system reset.

27.3.8 HAL_OPAMP_DeInit

Function Name

HAL_StatusTypeDef HAL_OPAMP_DeInit

(OPAMP_HandleTypeDef * hopamp)

Function Description DeInitializes the OPAMP peripheral.

Parameters

Return values

hopamp: OPAMP handle

HAL status

Notes

Deinitialization can be performed if the OPAMP configuration is locked. (the OPAMP lock is SW in STM32L1)

27.3.9 HAL_OPAMP_MspInit

Function Name

void HAL_OPAMP_MspInit (OPAMP_HandleTypeDef *

hopamp)

Function Description Initializes the OPAMP MSP.

Parameters

hopamp: OPAMP handle

Return values

None

27.3.10 HAL_OPAMP_MspDeInit

Function Name

void HAL_OPAMP_MspDeInit (OPAMP_HandleTypeDef *

hopamp)

Function Description DeInitializes OPAMP MSP.

Parameters

hopamp: OPAMP handle

Return values

None

27.3.11 HAL_OPAMP_Start

Function Name

HAL_StatusTypeDef HAL_OPAMP_Start

(OPAMP_HandleTypeDef * hopamp)

Function Description Start the opamp.

Parameters

hopamp: OPAMP handle

Return values

HAL status

27.3.12 HAL_OPAMP_Stop

Function Name

HAL_StatusTypeDef HAL_OPAMP_Stop

(OPAMP_HandleTypeDef * hopamp)

Function Description Stop the opamp.

Parameters

hopamp: OPAMP handle

Return values

HAL status

320/654 DOCID026682 Rev 3

UM1816

27.3.13 HAL_OPAMP_SelfCalibrate

Function Name

HAL OPAMP Generic Driver

HAL_StatusTypeDef HAL_OPAMP_SelfCalibrate

(OPAMP_HandleTypeDef * hopamp)

Function Description Run the self calibration of one OPAMP.

Parameters

hopamp: handle

Return values

Notes

Updated offset trimming values (PMOS & NMOS), user trimming is enabled

HAL status

Trimming values (PMOS & NMOS) are updated and user trimming is enabled if calibration is succesful.

Calibration is performed in the mode specified in OPAMP init structure (mode normal or low-power). To perform calibration for both modes, repeat this function twice after OPAMP init structure accordingly updated.

Calibration runs about 10 ms.

27.3.14 HAL_OPAMP_Lock

Function Name

HAL_StatusTypeDef HAL_OPAMP_Lock

(OPAMP_HandleTypeDef * hopamp)

Function Description Lock the selected opamp configuration.

Parameters

hopamp: OPAMP handle

Return values

HAL status

27.3.15 HAL_OPAMP_GetTrimOffset

Function Name

HAL_OPAMP_TrimmingValueTypeDef

HAL_OPAMP_GetTrimOffset (OPAMP_HandleTypeDef *

hopamp, uint32_t trimmingoffset)

Function Description Return the OPAMP factory trimming value Caution: On STM32L1

OPAMP, user can retrieve factory trimming if OPAMP has never been set to user trimming before.

Parameters

hopamp: : OPAMP handle

trimmingoffset: : Trimming offset (P or N) This parameter must be a value of OPAMP FactoryTrimming

Return values

Notes

Trimming value (P or N): range: 0->31 or

OPAMP_FACTORYTRIMMING_DUMMY if trimming value is not available

Calibration parameter retrieved is corresponding to the mode specified in OPAMP init structure (mode normal or lowpower). To retrieve calibration parameters for both modes, repeat this function after OPAMP init structure accordingly updated.

27.3.16 HAL_OPAMP_GetState

Function Name

HAL_OPAMP_StateTypeDef HAL_OPAMP_GetState

(OPAMP_HandleTypeDef * hopamp)

DOCID026682 Rev 3 321/654

HAL OPAMP Generic Driver

Function Description Return the OPAMP state.

Parameters

Return values

hopamp: : OPAMP handle

HAL state

UM1816

27.4 OPAMP Firmware driver defines

27.4.1 OPAMP

OPAMP Exported Constants

OPAMP_TRIM_VALUE_MASK

OPAMP_CSR_INSTANCE_OFFSET

OPAMP_OTR_INSTANCE_OFFSET

OPAMP FactoryTrimming

OPAMP_FACTORYTRIMMING_DUMMY Dummy value if trimming value could not be retrieved

OPAMP_FACTORYTRIMMING_P

OPAMP_FACTORYTRIMMING_N

OPAMP InvertingInput

Offset trimming P

Offset trimming N

OPAMP_INVERTINGINPUT_IO0 Comparator inverting input connected to dedicated IO pin low-leakage

OPAMP_INVERTINGINPUT_IO1 Comparator inverting input connected to alternative IO pin available on some device packages

OPAMP Mode

OPAMP_STANDALONE_MODE OPAMP standalone mode

OPAMP_FOLLOWER_MODE

OPAMP NonInvertingInput

OPAMP follower mode

OPAMP_NONINVERTINGINPUT_IO0 Comparator non-inverting input connected to dedicated IO pin low-leakage

OPAMP_NONINVERTINGINPUT_DAC_CH1 Comparator non-inverting input connected internally to DAC channel 1. Available only on OPAMP1 and OPAMP2.

OPAMP_NONINVERTINGINPUT_DAC_CH2 Comparator non-inverting input connected internally to DAC channel 2. Available only on OPAMP2 and OPAMP3 (OPAMP3 availability depends on STM32L1 devices).

OPAMP PowerMode

OPAMP_POWERMODE_NORMAL

OPAMP_POWERMODE_LOWPOWER

OPAMP PowerSupplyRange

OPAMP_POWERSUPPLY_LOW Power supply range low (VDDA lower than 2.4V)

OPAMP_POWERSUPPLY_HIGH Power supply range high (VDDA higher than 2.4V)

322/654 DOCID026682 Rev 3

UM1816

HAL OPAMP Generic Driver

OPAMP Private Constants

OPAMP_TRIMMING_DELAY

OPAMP Private Macro

__HAL_OPAMP_RESET_HANDLE_STATE Description:

Reset OPAMP handle state.

OPAMP_CSR_OPAXPD

OPAMP_CSR_S3SELX

OPAMP_CSR_S4SELX

OPAMP_CSR_S5SELX

Parameters:

__HANDLE__: OPAMP handle.

Return value:

None

Description:

Select the OPAMP bit OPAxPD

(power-down) corresponding to the selected OPAMP instance.

Parameters:

__HANDLE__: OPAMP handle

Return value:

None

Description:

Select the OPAMP bit S3SELx (switch

3) corresponding to the selected

OPAMP instance.

Parameters:

__HANDLE__: OPAMP handle

Return value:

None

Description:

Select the OPAMP bit S4SELx (switch

4) corresponding to the selected

OPAMP instance.

Parameters:

__HANDLE__: OPAMP handle

Return value:

None

Description:

Select the OPAMP bit S5SELx (switch

5) corresponding to the selected

OPAMP instance.

Parameters:

__HANDLE__: OPAMP handle

DOCID026682 Rev 3 323/654

HAL OPAMP Generic Driver

324/654

OPAMP_CSR_S6SELX

OPAMP_CSR_OPAXCAL_L

OPAMP_CSR_OPAXCAL_H

OPAMP_CSR_OPAXLPM

OPAMP_CSR_ALL_SWITCHES

UM1816

Return value:

None

Description:

Select the OPAMP bit S3SELx (switch

6) corresponding to the selected

OPAMP instance.

Parameters:

__HANDLE__: OPAMP handle

Return value:

None

Description:

Select the OPAMP bit OPAxCAL_L

(offset calibration for differential pair P) corresponding to the selected OPAMP instance.

Parameters:

__HANDLE__: OPAMP handle

Return value:

None

Description:

Select the OPAMP bit OPAxCAL_H

(offset calibration for differential pair N) corresponding to the selected OPAMP instance.

Parameters:

__HANDLE__: OPAMP handle

Return value:

None

Description:

Select the OPAMP bit OPAxLPM (low power mode) corresponding to the selected OPAMP instance.

Parameters:

__HANDLE__: OPAMP handle

Return value:

None

Description:

Select the OPAMP bits of all switches corresponding to the selected OPAMP instance.

DOCID026682 Rev 3

UM1816

OPAMP_CSR_ANAWSELX

OPAMP_CSR_OPAXCALOUT

OPAMP_OFFSET_TRIM_SET

OPAMP_OFFSET_TRIM_BITSPOSITION

HAL OPAMP Generic Driver

Parameters:

__HANDLE__: OPAMP handle

Return value:

None

Description:

Select the OPAMP bit ANAWSELx

(switch SanA) corresponding to the selected OPAMP instance.

Parameters:

__HANDLE__: OPAMP handle

Return value:

None

Description:

Select the OPAMP bit OPAxCALOUT in function of the selected OPAMP instance.

Parameters:

__HANDLE__: OPAMP handle

Return value:

None

Description:

Select the OPAMP trimming bits position value (position of LSB) in register OPAMP_OTR or register

OPAMP_LPOTR in function of the selected OPAMP instance and the transistors differential pair high

(PMOS) or low (NMOS).

Parameters:

__HANDLE__: OPAMP handle

__TRIM_HIGH_LOW__: transistors differential pair high or low. Must be a value of

Return value:

None

Description:

Shift the OPAMP trimming bits to register OPAMP_OTR or register

OPAMP_LPOTR in function of the selected OPAMP instance and the transistors differential pair high

(PMOS) or low (NMOS).

DOCID026682 Rev 3 325/654

HAL OPAMP Generic Driver

UM1816

Parameters:

__HANDLE__: OPAMP handle

__TRIM_HIGH_LOW__: transistors differential pair high or low. Must be a value of

__TRIMMING_VALUE__: Trimming value

Return value:

None

IS_OPAMP_TRIMMINGVALUE

IS_OPAMP_FUNCTIONAL_NORMALMODE

IS_OPAMP_INVERTING_INPUT

IS_OPAMP_POWERMODE

Description:

Check that trimming value is within correct range.

Parameters:

TRIMMINGVALUE: OPAMP trimming value

Return value:

None

IS_OPAMP_POWER_SUPPLY_RANGE

IS_OPAMP_TRIMMING

IS_OPAMP_FACTORYTRIMMING

OPAMP User Trimming

OPAMP_TRIMMING_FACTORY Factory trimming

OPAMP_TRIMMING_USER User trimming

326/654 DOCID026682 Rev 3

UM1816

HAL OPAMP Extension Driver

28 HAL OPAMP Extension Driver

28.1 HAL OPAMP Extension Driver

28.2 OPAMPEx Firmware driver API description

28.2.1 Peripheral Control functions

OPAMP unlock.

This section contains the following APIs:

HAL_OPAMPEx_Unlock()

28.2.2 Extended IO operation functions

OPAMP Self calibration.

This section contains the following APIs:

HAL_OPAMPEx_SelfCalibrateAll()

28.2.3 HAL_OPAMPEx_Unlock

Function Name

HAL_StatusTypeDef HAL_OPAMPEx_Unlock

(OPAMP_HandleTypeDef * hopamp)

Function Description Unlock the selected opamp configuration.

Parameters

hopamp: OPAMP handle

Return values

HAL status

28.2.4 HAL_OPAMPEx_SelfCalibrateAll

Function Name

HAL_StatusTypeDef HAL_OPAMPEx_SelfCalibrateAll

(OPAMP_HandleTypeDef * hopamp1, OPAMP_HandleTypeDef

* hopamp2, OPAMP_HandleTypeDef * hopamp3)

Function Description Run the self calibration of the 3 OPAMPs in parallel.

Parameters

Return values

hopamp1: handle

hopamp2: handle

hopamp3: handle

HAL status

Notes

Trimming values (PMOS & NMOS) are updated and user trimming is enabled is calibration is succesful.

Calibration is performed in the mode specified in OPAMP init structure (mode normal or low-power). To perform calibration for both modes, repeat this function twice after OPAMP init structure accordingly updated.

Calibration runs about 10 ms (5 dichotmy steps, repeated for

DOCID026682 Rev 3 327/654

HAL OPAMP Extension Driver

UM1816

P and N transistors: 10 steps with 1 ms for each step).

28.3 OPAMPEx Firmware driver defines

28.3.1 OPAMPEx

OPAMPEx Exported Constants

OPAMP_CSR_OPAXPD_ALL

OPAMP_CSR_OPAXCAL_L_ALL

OPAMP_CSR_OPAXCAL_H_ALL

OPAMP_CSR_ALL_SWITCHES_ALL_OPAMPS

OPAMPEx Exported Macro

__HAL_OPAMP_OPAMP3OUT_CONNECT_ADC_COMP1

OPAMPEx Private Macro

OPAMP_INSTANCE_DECIMAL

Description:

Enable internal analog switch SW1 to connect OPAMP3 ouput to ADC switch matrix (ADC channel VCOMP, channel 26) and

COMP1 noninverting input

(OPAMP3 available on STM32L1 devices Cat.4 only).

Return value:

None

__HAL_OPAMP_OPAMP3OUT_DISCONNECT_ADC_COMP1 Description:

Disable internal analog switch SW1 to disconnect

OPAMP3 ouput from ADC switch matrix (ADC channel VCOMP, channel 26) and

COMP1 noninverting input.

Return value:

None

Description:

Get the OPAMP instance in decimal number for further processing needs by

328/654 DOCID026682 Rev 3

UM1816

HAL OPAMP Extension Driver

HAL OPAMP driver functions.

Parameters:

__HANDLE__: OPAMP handle

Return value:

0: for OPAMP1, "1" for

OPAMP2, "2" for

OPAMP3

IS_OPAMP_NONINVERTING_INPUT_CHECK_INSTANCE Description:

Check OPAMP noninverting input in function of OPAMPx instance.

Parameters:

__HANDLE__: OPAMP handle

INPUT: OPAMP noninverting input

Return value:

None

DOCID026682 Rev 3 329/654

HAL PCD Generic Driver

UM1816

29 HAL PCD Generic Driver

29.1 HAL PCD Generic Driver

29.2 PCD Firmware driver registers structures

29.2.1 PCD_InitTypeDef

Data Fields

uint32_t dev_endpoints

uint32_t speed

uint32_t ep0_mps

uint32_t phy_itface

uint32_t Sof_enable

uint32_t low_power_enable

uint32_t lpm_enable

uint32_t battery_charging_enable

Field Documentation

uint32_t PCD_InitTypeDef::dev_endpoints

Device Endpoints number. This parameter depends on the used USB core. This parameter must be a number between Min_Data = 1 and Max_Data = 15

uint32_t PCD_InitTypeDef::speed

USB Core speed. This parameter can be any value of

PCD_Core_Speed

uint32_t PCD_InitTypeDef::ep0_mps

Set the Endpoint 0 Max Packet size. This parameter can be any value of

PCD_EP0_MPS

uint32_t PCD_InitTypeDef::phy_itface

Select the used PHY interface. This parameter can be any value of

PCD_Core_PHY

uint32_t PCD_InitTypeDef::Sof_enable

Enable or disable the output of the SOF signal.

uint32_t PCD_InitTypeDef::low_power_enable

Enable or disable Low Power mode

uint32_t PCD_InitTypeDef::lpm_enable

Enable or disable Battery charging.

uint32_t PCD_InitTypeDef::battery_charging_enable

Enable or disable Battery charging.

29.2.2 PCD_EPTypeDef

Data Fields

uint8_t num

uint8_t is_in

uint8_t is_stall

330/654 DOCID026682 Rev 3

UM1816

HAL PCD Generic Driver

uint8_t type

uint16_t pmaadress

uint16_t pmaaddr0

uint16_t pmaaddr1

uint8_t doublebuffer

uint32_t maxpacket

uint8_t * xfer_buff

uint32_t xfer_len

uint32_t xfer_count

Field Documentation

uint8_t PCD_EPTypeDef::num

Endpoint number This parameter must be a number between Min_Data = 1 and

Max_Data = 15

uint8_t PCD_EPTypeDef::is_in

Endpoint direction This parameter must be a number between Min_Data = 0 and

Max_Data = 1

uint8_t PCD_EPTypeDef::is_stall

Endpoint stall condition This parameter must be a number between Min_Data = 0 and

Max_Data = 1

uint8_t PCD_EPTypeDef::type

Endpoint type This parameter can be any value of

PCD_EP_Type

uint16_t PCD_EPTypeDef::pmaadress

PMA Address This parameter can be any value between Min_addr = 0 and Max_addr

= 1K

uint16_t PCD_EPTypeDef::pmaaddr0

PMA Address0 This parameter can be any value between Min_addr = 0 and

Max_addr = 1K

uint16_t PCD_EPTypeDef::pmaaddr1

PMA Address1 This parameter can be any value between Min_addr = 0 and

Max_addr = 1K

uint8_t PCD_EPTypeDef::doublebuffer

Double buffer enable This parameter can be 0 or 1

uint32_t PCD_EPTypeDef::maxpacket

Endpoint Max packet size This parameter must be a number between Min_Data = 0 and Max_Data = 64KB

uint8_t* PCD_EPTypeDef::xfer_buff

Pointer to transfer buffer

uint32_t PCD_EPTypeDef::xfer_len

Current transfer length

uint32_t PCD_EPTypeDef::xfer_count

Partial transfer length in case of multi packet transfer

29.2.3 PCD_HandleTypeDef

Data Fields

PCD_TypeDef * Instance

PCD_InitTypeDef Init

__IO uint8_t USB_Address

DOCID026682 Rev 3 331/654

HAL PCD Generic Driver

PCD_EPTypeDef IN_ep

PCD_EPTypeDef OUT_ep

HAL_LockTypeDef Lock

__IO PCD_StateTypeDef State

uint32_t Setup

void * pData

Field Documentation

PCD_TypeDef* PCD_HandleTypeDef::Instance

Register base address

PCD_InitTypeDef PCD_HandleTypeDef::Init

PCD required parameters

__IO uint8_t PCD_HandleTypeDef::USB_Address

USB Address

PCD_EPTypeDef PCD_HandleTypeDef::IN_ep[8]

IN endpoint parameters

PCD_EPTypeDef PCD_HandleTypeDef::OUT_ep[8]

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

void* PCD_HandleTypeDef::pData

Pointer to upper stack Handler

UM1816

29.3 PCD Firmware driver API description

29.3.1 How to use this driver

The PCD HAL driver can be used as follows:

1. Declare a PCD_HandleTypeDef handle structure, for example: PCD_HandleTypeDef hpcd;

2. Fill parameters of Init structure in HCD handle

3. Call HAL_PCD_Init() API to initialize the HCD peripheral (Core, Device core, ...)

4. 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_CLK_ENABLE); b. Initialize the related GPIO clocks c. Configure PCD pin-out d. Configure PCD NVIC interrupt

5. Associate the Upper USB device stack to the HAL PCD Driver: a. hpcd.pData = pdev;

6. Enable HCD transmission and reception: a. HAL_PCD_Start();

29.3.2 Initialization and de-initialization functions

This section provides functions allowing to:

This section contains the following APIs:

332/654 DOCID026682 Rev 3

UM1816

HAL PCD Generic Driver

HAL_PCD_Init()

HAL_PCD_DeInit()

HAL_PCD_MspInit()

HAL_PCD_MspDeInit()

29.3.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()

29.3.4 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()

29.3.5 Peripheral State 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_PCD_GetState()

HAL_PCDEx_SetConnectionState()

29.3.6 HAL_PCD_Init

Function Name

HAL_StatusTypeDef HAL_PCD_Init (PCD_HandleTypeDef *

DOCID026682 Rev 3 333/654

HAL PCD Generic Driver

UM1816

hpcd)

Function Description Initializes the PCD according to the specified parameters in the

PCD_InitTypeDef and create the associated handle.

Parameters

Return values

hpcd: PCD handle

HAL status

29.3.7 HAL_PCD_DeInit

Function Name

HAL_StatusTypeDef HAL_PCD_DeInit (PCD_HandleTypeDef *

hpcd)

Function Description DeInitializes the PCD peripheral.

Parameters

hpcd: PCD handle

Return values

HAL status

29.3.8 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

29.3.9 HAL_PCD_MspDeInit

Function Name void HAL_PCD_MspDeInit (PCD_HandleTypeDef * hpcd)

Function Description DeInitializes PCD MSP.

Parameters

Return values

hpcd: PCD handle

None

29.3.10 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

29.3.11 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

334/654 DOCID026682 Rev 3

UM1816

29.3.12 HAL_PCD_IRQHandler

HAL PCD Generic Driver

Function Name void HAL_PCD_IRQHandler (PCD_HandleTypeDef * hpcd)

Function Description This function handles PCD interrupt request.

Parameters

hpcd: PCD handle

Return values

HAL status

29.3.13 HAL_PCD_DataOutStageCallback

Function Name

void HAL_PCD_DataOutStageCallback (PCD_HandleTypeDef *

hpcd, uint8_t epnum)

Function Description Data out stage callbacks.

Parameters

Return values

hpcd: PCD handle

epnum: endpoint number

None

29.3.14 HAL_PCD_DataInStageCallback

Function Name

void HAL_PCD_DataInStageCallback (PCD_HandleTypeDef *

hpcd, uint8_t epnum)

Function Description Data IN stage callbacks.

Parameters

hpcd: PCD handle

epnum: endpoint number

Return values

None

29.3.15 HAL_PCD_SetupStageCallback

Function Name

void HAL_PCD_SetupStageCallback (PCD_HandleTypeDef *

hpcd)

Function Description Setup stage callback.

Parameters

hpcd: ppp handle

Return values

None

29.3.16 HAL_PCD_SOFCallback

Function Name void HAL_PCD_SOFCallback (PCD_HandleTypeDef * hpcd)

Function Description USB Start Of Frame callbacks.

Parameters

hpcd: PCD handle

Return values

None

29.3.17 HAL_PCD_ResetCallback

Function Name void HAL_PCD_ResetCallback (PCD_HandleTypeDef * hpcd)

Function Description USB Reset callbacks.

Parameters

hpcd: PCD handle

DOCID026682 Rev 3 335/654

HAL PCD Generic Driver

Return values

None

UM1816

29.3.18 HAL_PCD_SuspendCallback

Function Name

void HAL_PCD_SuspendCallback (PCD_HandleTypeDef *

hpcd)

Function Description Suspend event callbacks.

Parameters

hpcd: PCD handle

Return values

None

29.3.19 HAL_PCD_ResumeCallback

Function Name

void HAL_PCD_ResumeCallback (PCD_HandleTypeDef *

hpcd)

Function Description Resume event callbacks.

Parameters

hpcd: PCD handle

Return values

None

29.3.20 HAL_PCD_ISOOUTIncompleteCallback

Function Name

void HAL_PCD_ISOOUTIncompleteCallback

(PCD_HandleTypeDef * hpcd, uint8_t epnum)

Function Description Incomplete ISO OUT callbacks.

Parameters

hpcd: PCD handle

epnum: endpoint number

Return values

None

29.3.21 HAL_PCD_ISOINIncompleteCallback

Function Name

void HAL_PCD_ISOINIncompleteCallback

(PCD_HandleTypeDef * hpcd, uint8_t epnum)

Function Description Incomplete ISO IN callbacks.

Parameters

hpcd: PCD handle

epnum: endpoint number

Return values

None

29.3.22 HAL_PCD_ConnectCallback

Function Name

void HAL_PCD_ConnectCallback (PCD_HandleTypeDef *

hpcd)

Function Description Connection event callbacks.

Parameters

Return values

hpcd: PCD handle

None

29.3.23 HAL_PCD_DisconnectCallback

336/654 DOCID026682 Rev 3

UM1816

Function Name

HAL PCD Generic Driver

void HAL_PCD_DisconnectCallback (PCD_HandleTypeDef *

hpcd)

Function Description Disconnection event callbacks.

Parameters

hpcd: ppp handle

Return values

None

29.3.24 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

29.3.25 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

29.3.26 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

29.3.27 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

Return values

hpcd: PCD handle

ep_addr: endpoint address

ep_mps: endpoint max packert size

ep_type: endpoint type

HAL status

29.3.28 HAL_PCD_EP_Close

Function Name

HAL_StatusTypeDef HAL_PCD_EP_Close

DOCID026682 Rev 3 337/654

HAL PCD Generic Driver

(PCD_HandleTypeDef * hpcd, uint8_t ep_addr)

Function Description Deactivate an endpoint.

Parameters

hpcd: PCD handle

ep_addr: endpoint address

Return values

HAL status

UM1816

29.3.29 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

Return values

hpcd: PCD handle

ep_addr: endpoint address

pBuf: pointer to the reception buffer

len: amount of data to be received

HAL status

29.3.30 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

29.3.31 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

29.3.32 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

338/654 DOCID026682 Rev 3

UM1816

Return values

HAL status

HAL PCD Generic Driver

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

Parameters

hpcd: PCD handle

ep_addr: endpoint address

Return values

HAL status

29.3.34 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

Return values

hpcd: PCD handle

ep_addr: endpoint address

HAL status

29.3.35 HAL_PCD_ActivateRemoteWakeup

Function Name

HAL_StatusTypeDef HAL_PCD_ActivateRemoteWakeup

(PCD_HandleTypeDef * hpcd)

Function Description HAL_PCD_ActivateRemoteWakeup : active remote wakeup signalling.

Parameters

hpcd: PCD handle

Return values

 status

29.3.36 HAL_PCD_DeActivateRemoteWakeup

Function Name

HAL_StatusTypeDef HAL_PCD_DeActivateRemoteWakeup

(PCD_HandleTypeDef * hpcd)

Function Description HAL_PCD_DeActivateRemoteWakeup : de-active remote wakeup signalling.

Parameters

Return values

hpcd: PCD handle

 status

29.3.37 HAL_PCD_GetState

Function Name

PCD_StateTypeDef HAL_PCD_GetState (PCD_HandleTypeDef

* hpcd)

Function Description Return the PCD state.

Parameters

hpcd: : PCD handle

Return values

HAL state

DOCID026682 Rev 3 339/654

HAL PCD Generic Driver

29.3.38 HAL_PCDEx_SetConnectionState

Function Name

UM1816 void HAL_PCDEx_SetConnectionState (PCD_HandleTypeDef *

hpcd, uint8_t state)

Function Description Software Device Connection.

Parameters

hpcd: PCD handle

state: Device state

Return values

None

29.4 PCD Firmware driver defines

29.4.1 PCD

PCD Core PHY

PCD_PHY_EMBEDDED

PCD Core Speed

PCD_SPEED_HIGH

PCD_SPEED_FULL

PCD_ENDP_Type

PCD_ENDP0

PCD_ENDP1

PCD_ENDP2

PCD_ENDP3

PCD_ENDP4

PCD_ENDP5

PCD_ENDP6

PCD_ENDP7

PCD_SNG_BUF

PCD_DBL_BUF

IS_PCD_ALL_INSTANCE

PCD EP0 MPS

DEP0CTL_MPS_64

DEP0CTL_MPS_32

DEP0CTL_MPS_16

DEP0CTL_MPS_8

PCD_EP0MPS_64

PCD_EP0MPS_32

PCD_EP0MPS_16

PCD_EP0MPS_08

PCD EP Type

340/654 DOCID026682 Rev 3

UM1816

HAL PCD Generic Driver

PCD_EP_TYPE_CTRL

PCD_EP_TYPE_ISOC

PCD_EP_TYPE_BULK

PCD_EP_TYPE_INTR

PCD Exported Macros

__HAL_PCD_GET_FLAG

PCD_GET_EPTYPE

__HAL_PCD_CLEAR_FLAG

__HAL_USB_WAKEUP_EXTI_ENABLE_IT

__HAL_USB_WAKEUP_EXTI_DISABLE_IT

__HAL_USB_WAKEUP_EXTI_GET_FLAG

__HAL_USB_WAKEUP_EXTI_CLEAR_FLAG

__HAL_USB_WAKEUP_EXTI_ENABLE_RISING_EDGE

__HAL_USB_WAKEUP_EXTI_ENABLE_FALLING_EDGE

__HAL_USB_WAKEUP_EXTI_ENABLE_RISING_FALLING_EDGE

PCD_Exti_Line_Wakeup

USB_WAKEUP_EXTI_LINE External interrupt line 18 Connected to the USB FS EXTI

Line

PCD Private Constants

BTABLE_ADDRESS

PCD Private Macros

PCD_SET_ENDPOINT

PCD_GET_ENDPOINT

PCD_SET_EPTYPE Description:

 sets the type in the endpoint register(bits

EP_TYPE[1:0])

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

 wType: Endpoint Type.

Return value:

None

Description:

 gets the type in the endpoint register(bits

EP_TYPE[1:0])

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

DOCID026682 Rev 3 341/654

HAL PCD Generic Driver

342/654

PCD_FreeUserBuffer

PCD_GET_DB_DIR

PCD_SET_EP_TX_STATUS

PCD_SET_EP_RX_STATUS

UM1816

Return value:

Endpoint: Type

Description:

 free buffer used from the application realizing it to the line toggles bit SW_BUF in the double buffered endpoint register

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

 bDir: Direction

Return value:

None

Description:

 gets direction of the double buffered endpoint

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

EP_DBUF_OUT: if the endpoint counter not yet programmed.

Description:

 sets the status for tx transfer (bits

STAT_TX[1:0]).

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

 wState: new state

Return value:

None

Description:

 sets the status for rx transfer (bits

STAT_TX[1:0])

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

 wState: new state

Return value:

DOCID026682 Rev 3

UM1816

PCD_SET_EP_TXRX_STATUS

PCD_GET_EP_TX_STATUS

HAL PCD Generic Driver

None

Description:

 sets the status for rx & tx (bits STAT_TX[1:0]

& STAT_RX[1:0])

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

 wStaterx: new state.

 wStatetx: new state.

Return value:

None

Description:

 gets the status for tx/rx transfer (bits

STAT_TX[1:0] /STAT_RX[1:0])

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

PCD_GET_EP_RX_STATUS

PCD_SET_EP_TX_VALID

Return value:

 status

Description:

 sets directly the VALID tx/rx-status into the endpoint register

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

None

PCD_SET_EP_RX_VALID

PCD_GET_EP_TX_STALL_STATUS

Description:

 checks stall condition in an endpoint.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

TRUE: = endpoint in stall condition.

DOCID026682 Rev 3 343/654

HAL PCD Generic Driver

PCD_GET_EP_RX_STALL_STATUS

PCD_SET_EP_KIND

UM1816

Description:

 set & clear EP_KIND bit.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

None

PCD_CLEAR_EP_KIND

PCD_SET_OUT_STATUS

PCD_CLEAR_OUT_STATUS

PCD_SET_EP_DBUF

PCD_CLEAR_EP_DBUF

PCD_CLEAR_RX_EP_CTR

Description:

Sets/clears directly STATUS_OUT bit in the endpoint register.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

None

Description:

Sets/clears directly EP_KIND bit in the endpoint register.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

None

Description:

Clears bit CTR_RX / CTR_TX in the endpoint register.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

None

344/654 DOCID026682 Rev 3

UM1816

PCD_CLEAR_TX_EP_CTR

PCD_RX_DTOG

PCD_TX_DTOG

PCD_CLEAR_RX_DTOG

PCD_CLEAR_TX_DTOG

PCD_SET_EP_ADDRESS

PCD_GET_EP_ADDRESS

PCD_EP_TX_ADDRESS

PCD_EP_TX_CNT

PCD_EP_RX_ADDRESS

PCD_EP_RX_CNT

PCD_SET_EP_RX_CNT

PCD_SET_EP_TX_ADDRESS

HAL PCD Generic Driver

Description:

Toggles DTOG_RX / DTOG_TX bit in the endpoint register.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

None

Description:

Clears DTOG_RX / DTOG_TX bit in the endpoint register.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

None

Description:

Sets address in an endpoint register.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

 bAddr: Address.

Return value:

None

Description:

 sets address of the tx/rx buffer.

Parameters:

DOCID026682 Rev 3 345/654

HAL PCD Generic Driver

PCD_SET_EP_RX_ADDRESS

PCD_GET_EP_TX_ADDRESS

PCD_GET_EP_RX_ADDRESS

PCD_CALC_BLK32

PCD_CALC_BLK2

PCD_SET_EP_CNT_RX_REG

PCD_SET_EP_RX_DBUF0_CNT

PCD_SET_EP_TX_CNT

PCD_GET_EP_TX_CNT

UM1816

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

 wAddr: address to be set (must be word aligned).

Return value:

None

Description:

Gets address of the tx/rx buffer.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

 address: of the buffer.

Description:

Sets counter of rx buffer with no.

Parameters:

 dwReg: Register

 wCount: Counter.

 wNBlocks: no. of Blocks.

Return value:

None

Description:

 sets counter for the tx/rx buffer.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

 wCount: Counter value.

Return value:

None

Description:

 gets counter of the tx buffer.

346/654 DOCID026682 Rev 3

UM1816

PCD_GET_EP_RX_CNT

PCD_SET_EP_DBUF0_ADDR

PCD_SET_EP_DBUF1_ADDR

PCD_SET_EP_DBUF_ADDR

PCD_GET_EP_DBUF0_ADDR

PCD_GET_EP_DBUF1_ADDR

PCD_SET_EP_DBUF0_CNT

HAL PCD Generic Driver

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

Counter: value

Description:

Sets buffer 0/1 address in a double buffer endpoint.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

 wBuf0Addr: buffer 0 address.

Return value:

Counter: value

Description:

Sets addresses in a double buffer endpoint.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

 wBuf0Addr: buffer 0 address.

 wBuf1Addr: = buffer 1 address.

Return value:

None

Description:

Gets buffer 0/1 address of a double buffer endpoint.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

None

Description:

Gets buffer 0/1 address of a double buffer

DOCID026682 Rev 3 347/654

HAL PCD Generic Driver

PCD_SET_EP_DBUF1_CNT

PCD_SET_EP_DBUF_CNT

PCD_GET_EP_DBUF0_CNT

PCD_GET_EP_DBUF1_CNT

UM1816

endpoint.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

 bDir: endpoint dir EP_DBUF_OUT = OUT

EP_DBUF_IN = IN

 wCount: Counter value

Return value:

None

Description:

Gets buffer 0/1 rx/tx counter for double buffering.

Parameters:

USBx: USB peripheral instance register address.

 bEpNum: Endpoint Number.

Return value:

None

348/654 DOCID026682 Rev 3

UM1816

HAL PCD Extension Driver

30 HAL PCD Extension Driver

30.1 HAL PCD Extension Driver

30.2 PCDEx Firmware driver API description

30.2.1 Peripheral Control functions

This section provides functions allowing to:

Configure PMA for the EndPoint

This section contains the following APIs:

HAL_PCDEx_PMAConfig()

30.2.2 HAL_PCDEx_PMAConfig

Function Name

HAL_StatusTypeDef HAL_PCDEx_PMAConfig

(PCD_HandleTypeDef * hpcd, uint16_t ep_addr, uint16_t

ep_kind, uint32_t pmaadress)

Function Description Configure PMA for EP.

Parameters

Return values

hpcd: : Device instance

ep_addr: endpoint address

ep_kind: endpoint Kind USB_SNG_BUF: Single Buffer used

USB_DBL_BUF: Double Buffer used

pmaadress: EP address in The PMA: In case of single buffer endpoint this parameter is 16-bit value providing the address in PMA allocated to endpoint. In case of double buffer endpoint this parameter is a 32-bit value providing the endpoint buffer 0 address in the LSB part of 32-bit value and endpoint buffer 1 address in the MSB part of 32-bit value.

: status

30.3 PCDEx Firmware driver defines

30.3.1 PCDEx

DOCID026682 Rev 3 349/654

HAL PWR Generic Driver

UM1816

31 HAL PWR Generic Driver

31.1 HAL PWR Generic Driver

31.2 PWR Firmware driver registers structures

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

31.3 PWR Firmware driver API description

31.3.1 Initialization and de-initialization functions

After reset, the backup domain (RTC registers, RTC backup data registers) 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()

31.3.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).

The PVD can use an external input analog voltage (PVD_IN) which is compared internally to VREFINT. The PVD_IN (PB7) has to be configured in Analog mode when

PWR_PVDLevel_7 is selected (PLS[2:0] = 111).

350/654 DOCID026682 Rev 3

UM1816

HAL PWR Generic Driver

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.

WakeUp pin configuration

WakeUp 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 are two or three WakeUp pins: WakeUp Pin 1 on PA.00. WakeUp Pin 2 on

PC.13. WakeUp Pin 3 on PE.06. : Only on product with GPIOE available

Main and Backup Regulators configuration

Low Power modes configuration

The device features 5 low-power modes:

Low power run mode: regulator in low power mode, limited clock frequency, limited number of peripherals running.

Sleep mode: Cortex-M3 core stopped, peripherals kept running.

Low power sleep mode: Cortex-M3 core stopped, limited clock frequency, limited number of peripherals running, regulator in low power mode.

Stop mode: All clocks are stopped, regulator running, regulator in low power mode.

Standby mode: VCORE domain powered off

Low power run mode

To further reduce the consumption when the system is in Run mode, the regulator can be configured in low power mode. In this mode, the system frequency should not exceed MSI frequency range1. In Low power run mode, all I/O pins keep the same state as in Run mode.

Entry:

VCORE in range2

Decrease the system frequency tonot exceed the frequency of MSI frequency range1.

The regulator is forced in low power mode using the

HAL_PWREx_EnableLowPowerRunMode() function.

Exit:

The regulator is forced in Main regulator mode using the

HAL_PWREx_DisableLowPowerRunMode() function.

Increase the system frequency if needed.

Sleep mode

Entry: The Sleep mode is entered by using the

HAL_PWR_EnterSLEEPMode(PWR_MAINREGULATOR_ON,

PWR_SLEEPENTRY_WFx) functions with

PWR_SLEEPENTRY_WFI: enter SLEEP mode with WFI instruction

PWR_SLEEPENTRY_WFE: enter SLEEP mode with WFE instruction

DOCID026682 Rev 3 351/654

HAL PWR Generic Driver

UM1816

Exit:

Any peripheral interrupt acknowledged by the nested vectored interrupt controller

(NVIC) can wake up the device from Sleep mode.

Low power sleep mode

Entry: The Low power sleep mode is entered by using the

HAL_PWR_EnterSLEEPMode(PWR_LOWPOWERREGULATOR_ON,

PWR_SLEEPENTRY_WFx) functions with

PWR_SLEEPENTRY_WFI: enter SLEEP mode with WFI instruction

PWR_SLEEPENTRY_WFE: enter SLEEP mode with WFE instruction

The Flash memory can be switched off by using the control bits (SLEEP_PD in the

FLASH_ACR register. This reduces power consumption but increases the wake-up time.

Exit:

If the WFI instruction was used to enter Low power sleep mode, any peripheral interrupt acknowledged by the nested vectored interrupt controller (NVIC) can wake up the device from Low power sleep mode. If the WFE instruction was used to enter Low power sleep mode, the MCU exits Sleep mode as soon as an event occurs.

Stop mode

The Stop mode is based on the Cortex-M3 deepsleep mode combined with peripheral clock gating. The voltage regulator can be configured either in normal or low-power mode.

In Stop mode, all clocks in the VCORE domain are stopped, the PLL, the MSI, the HSI and the HSE RC oscillators are disabled. Internal SRAM and register contents are preserved.

To get the lowest consumption in Stop mode, the internal Flash memory also enters low power mode. When the Flash memory is in power-down mode, an additional startup delay is incurred when waking up from Stop mode. To minimize the consumption In Stop mode,

VREFINT, the BOR, PVD, and temperature sensor can be switched off before entering

Stop mode. They can be switched on again by software after exiting Stop mode using the

ULP bit in the PWR_CR register. In Stop mode, all I/O pins keep the same state as in Run mode.

Entry: The Stop mode is entered using the

HAL_PWR_EnterSTOPMode(PWR_MAINREGULATOR_ON,

PWR_SLEEPENTRY_WFI ) function with:

Main regulator ON.

Low Power regulator ON.

PWR_SLEEPENTRY_WFI: enter SLEEP mode with WFI instruction

PWR_SLEEPENTRY_WFE: enter SLEEP mode with WFE instruction

Exit:

By issuing an interrupt or a wakeup event, the MSI RC oscillator is selected as system clock.

Standby mode

The Standby mode allows to achieve the lowest power consumption. It is based on the

Cortex-M3 deepsleep mode, with the voltage regulator disabled. The VCORE domain is consequently powered off. The PLL, the MSI, the HSI oscillator and the HSE oscillator are also switched off. SRAM and register contents are lost except for the RTC registers, RTC backup registers and Standby circuitry. To minimize the consumption In Standby mode,

VREFINT, the BOR, PVD, and temperature sensor can be switched off before entering the

352/654 DOCID026682 Rev 3

UM1816

HAL PWR Generic Driver

Standby mode. They can be switched on again by software after exiting the Standby mode. function.

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 wakeup, tamper event, time-stamp event, external reset in NRST pin, IWDG reset.

Auto-wakeup (AWU) from low-power mode

The MCU can be woken up from low-power mode by an RTC Alarm event, an RTC

Wakeup event, a tamper event, a time-stamp event, or a comparator event, without depending on an external interrupt (Auto-wakeup mode).

RTC auto-wakeup (AWU) from the Stop mode

To wake up from the Stop mode with an RTC alarm event, it is necessary to:

Configure the EXTI Line 17 to be sensitive to rising edges (Interrupt or

Event modes) and Enable the RTC Alarm Interrupt using the

HAL_RTC_SetAlarm_IT() function

Configure the RTC to generate the RTC alarm using the HAL_RTC_Init() and HAL_RTC_SetTime() functions.

To wake up from the Stop mode with an RTC Tamper or time stamp event, it is necessary to:

Configure the EXTI Line 19 to be sensitive to rising edges (Interrupt or

Event modes) and Enable the RTC Tamper or time stamp Interrupt using the

HAL_RTCEx_SetTamper_IT() or HAL_RTCEx_SetTimeStamp_IT() functions.

To wake up from the Stop mode with an RTC WakeUp event, it is necessary to:

Configure the EXTI Line 20 to be sensitive to rising edges (Interrupt or

Event modes) and Enable the RTC WakeUp Interrupt using the

HAL_RTCEx_SetWakeUpTimer_IT() function.

Configure the RTC to generate the RTC WakeUp event using the

HAL_RTCEx_SetWakeUpTimer() function.

RTC auto-wakeup (AWU) from the Standby mode

To wake up from the Standby mode with an RTC alarm event, it is necessary to:

Enable the RTC Alarm Interrupt using the HAL_RTC_SetAlarm_IT() function.

Configure the RTC to generate the RTC alarm using the HAL_RTC_Init() and HAL_RTC_SetTime() functions.

To wake up from the Standby mode with an RTC Tamper or time stamp event, it is necessary to:

Enable the RTC Tamper or time stamp Interrupt and 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 Standby mode with an RTC WakeUp event, it is necessary to:

Enable the RTC WakeUp Interrupt and Configure the RTC to generate the

RTC WakeUp event using the HAL_RTCEx_SetWakeUpTimer_IT() and

HAL_RTCEx_SetWakeUpTimer() functions.

Comparator auto-wakeup (AWU) from the Stop mode

To wake up from the Stop mode with an comparator 1 or comparator 2 wakeup event, it is necessary to:

DOCID026682 Rev 3 353/654

HAL PWR Generic Driver

UM1816

Configure the EXTI Line 21 or EXTI Line 22 for comparator to be sensitive to to the selected edges (falling, rising or falling and rising) (Interrupt or

Event modes) using the COMP functions.

Configure the comparator to generate the event.

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_EnableSleepOnExit()

HAL_PWR_DisableSleepOnExit()

HAL_PWR_EnableSEVOnPend()

HAL_PWR_DisableSEVOnPend()

HAL_PWR_PVD_IRQHandler()

HAL_PWR_PVDCallback()

31.3.3 HAL_PWR_DeInit

Function Name void HAL_PWR_DeInit (void )

Function Description Deinitializes the PWR peripheral registers to their default reset values.

Return values

Notes

None

Before calling this function, the VOS[1:0] bits should be configured to "10" and the system frequency has to be configured accordingly. To configure the VOS[1:0] bits, use the PWR_VoltageScalingConfig() function.

ULP and FWU bits are not reset by this function.

31.3.4 HAL_PWR_EnableBkUpAccess

Function Name void HAL_PWR_EnableBkUpAccess (void )

Function Description Enables access to the backup domain (RTC registers, RTC backup data registers ).

Return values

Notes

None

If the HSE divided by 2, 4, 8 or 16 is used as the RTC clock, the Backup Domain Access should be kept enabled.

31.3.5 HAL_PWR_DisableBkUpAccess

Function Name void HAL_PWR_DisableBkUpAccess (void )

Function Description Disables access to the backup domain (RTC registers, RTC backup data registers).

Return values

Notes

None

If the HSE divided by 2, 4, 8 or 16 is used as the RTC clock,

354/654 DOCID026682 Rev 3

UM1816

HAL PWR Generic Driver the Backup Domain Access should be kept enabled.

31.3.6 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

Return values

sConfigPVD: pointer to an PWR_PVDTypeDef structure that contains the configuration information for the PVD.

None

Notes

Refer to the electrical characteristics of your device datasheet for more details about the voltage threshold corresponding to each detection level.

31.3.7 HAL_PWR_EnablePVD

Function Name void HAL_PWR_EnablePVD (void )

Function Description Enables the Power Voltage Detector(PVD).

Return values

None

31.3.8 HAL_PWR_DisablePVD

Function Name void HAL_PWR_DisablePVD (void )

Function Description Disables the Power Voltage Detector(PVD).

Return values

None

31.3.9 HAL_PWR_EnableWakeUpPin

Function Name void HAL_PWR_EnableWakeUpPin (uint32_t WakeUpPinx)

Function

Description

Parameters

Enables the WakeUp PINx functionality.

Return values

WakeUpPinx: Specifies the Power Wake-Up pin to enable.

This parameter can be one of the following values:

PWR_WAKEUP_PIN1PWR_WAKEUP_PIN2PWR_WAKEUP_

PIN3: Only on product with GPIOE available

None

31.3.10 HAL_PWR_DisableWakeUpPin

Function Name

Function

Description

Parameters

void HAL_PWR_DisableWakeUpPin (uint32_t WakeUpPinx)

Disables the WakeUp PINx functionality.

Return values

WakeUpPinx: Specifies the Power Wake-Up pin to disable.

This parameter can be one of the following values:

PWR_WAKEUP_PIN1PWR_WAKEUP_PIN2PWR_WAKEUP_

PIN3: Only on product with GPIOE available

None

DOCID026682 Rev 3 355/654

HAL PWR Generic Driver

31.3.11 HAL_PWR_EnterSLEEPMode

Function Name

UM1816 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

ONPWR_LOWPOWERREGULATOR_ON: SLEEP mode with low power regulator ON

SLEEPEntry: Specifies if SLEEP mode is entered with WFI or WFE instruction. When WFI entry is used, tick interrupt have to be disabled if not desired as the interrupt wake up source. This parameter can be one of the following values:

PWR_SLEEPENTRY_WFI: enter SLEEP mode with WFI instructionPWR_SLEEPENTRY_WFE: enter SLEEP mode with WFE instruction

Return values

Notes

None

In Sleep mode, all I/O pins keep the same state as in Run mode.

31.3.12 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

ONPWR_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: PWR_STOPENTRY_WFI: Enter Stop mode with WFI instructionPWR_STOPENTRY_WFE: Enter Stop mode with

WFE instruction

Return values

Notes

None

In Stop mode, all I/O pins keep the same state as in Run mode.

When exiting Stop mode by using an interrupt or a wakeup event, MSI 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.

31.3.13 HAL_PWR_EnterSTANDBYMode

Function Name void HAL_PWR_EnterSTANDBYMode (void )

356/654 DOCID026682 Rev 3

UM1816

HAL PWR Generic Driver

Function Description Enters Standby mode.

Return values

Notes

None

In Standby mode, all I/O pins are high impedance except for:

Reset pad (still available)RTC_AF1 pin (PC13) if configured for tamper, time-stamp, RTC Alarm out, or RTC clock calibration out.WKUP pin 1 (PA0) if enabled.WKUP pin 2

(PC13) if enabled.WKUP pin 3 (PE6) if enabled.

31.3.14 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

Notes

None

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.

31.3.15 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

Notes

None

Clears SLEEPONEXIT bit of SCR register. When this bit is set, the processor re-enters SLEEP mode when an interruption handling is over.

31.3.16 HAL_PWR_EnableSEVOnPend

Function Name void HAL_PWR_EnableSEVOnPend (void )

Function Description Enables CORTEX M3 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 inactive to pended.

31.3.17 HAL_PWR_DisableSEVOnPend

Function Name void HAL_PWR_DisableSEVOnPend (void )

Function Description Disables CORTEX M3 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.

DOCID026682 Rev 3 357/654

HAL PWR Generic Driver

31.3.18 HAL_PWR_PVD_IRQHandler

UM1816

Function Name void HAL_PWR_PVD_IRQHandler (void )

Function Description This function handles the PWR PVD interrupt request.

Return values

Notes

None

This API should be called under the PVD_IRQHandler().

31.3.19 HAL_PWR_PVDCallback

Function Name void HAL_PWR_PVDCallback (void )

Function Description PWR PVD interrupt callback.

Return values

None

31.4 PWR Firmware driver defines

31.4.1 PWR

PWR CR Register alias address

LPSDSR_BIT_NUMBER

CR_LPSDSR_BB

DBP_BIT_NUMBER

CR_DBP_BB

LPRUN_BIT_NUMBER

CR_LPRUN_BB

PVDE_BIT_NUMBER

CR_PVDE_BB

FWU_BIT_NUMBER

CR_FWU_BB

ULP_BIT_NUMBER

CR_ULP_BB

PWR CSR Register alias address

CSR_EWUP_BB

PWR Exported Macros

__HAL_PWR_VOLTAGESCALING_CONFIG 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

358/654 DOCID026682 Rev 3

UM1816

__HAL_PWR_GET_FLAG

HAL PWR Generic Driver frequency (refer to the datasheets for more details). This parameter can be one of the following values:

PWR_REGULATOR_VOLTAG

E_SCALE1: Regulator voltage output Scale 1 mode, System frequency up to 32 MHz.

PWR_REGULATOR_VOLTAG

E_SCALE2: Regulator voltage output Scale 2 mode, System frequency up to 16 MHz.

PWR_REGULATOR_VOLTAG

E_SCALE3: Regulator voltage output Scale 3 mode, System frequency up to 4.2 MHz

Return value:

None

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_WU: Wake Up flag. This flag indicates that a wakeup event was received from the WKUP pin or from the

RTC alarm (Alarm B), RTC

Tamper event, RTC TimeStamp event or RTC Wakeup. An additional wakeup event is detected if the 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_EnablePVD() 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_VREFINTRDY:

Internal voltage reference

(VREFINT) ready flag. This bit indicates the state of the

DOCID026682 Rev 3 359/654

HAL PWR Generic Driver

__HAL_PWR_CLEAR_FLAG

__HAL_PWR_PVD_EXTI_ENABLE_IT

__HAL_PWR_PVD_EXTI_DISABLE_IT

UM1816

internal voltage reference,

VREFINT.

PWR_FLAG_VOS: Voltage

Scaling select flag. A delay is required for the internal regulator to be ready after the voltage range is changed. The

VOSF bit indicates that the regulator has reached the voltage level defined with bits

VOS of PWR_CR register.

PWR_FLAG_REGLP: Regulator

LP flag. When the MCU exits from Low power run mode, this bit stays at 1 until the regulator is ready in main mode. A polling on this bit is recommended to wait for the regulator main mode. This bit is reset by hardware when the regulator is ready.

Return value:

The: new state of __FLAG__ (TRUE or FALSE).

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

Description:

Enable interrupt on PVD Exti Line

16.

Return value:

None.

Description:

Disable interrupt on PVD Exti Line

16.

Return value:

None.

__HAL_PWR_PVD_EXTI_ENABLE_EVENT Description:

Enable event on PVD Exti Line 16.

Return value:

360/654 DOCID026682 Rev 3

UM1816

HAL PWR Generic Driver

None.

__HAL_PWR_PVD_EXTI_DISABLE_EVENT

Description:

Disable event on PVD Exti Line 16.

Return value:

None.

__HAL_PWR_PVD_EXTI_ENABLE_FALLING

_EDGE

__HAL_PWR_PVD_EXTI_DISABLE_FALLIN

G_EDGE

Description:

PVD EXTI line configuration: set falling edge trigger.

Return value:

None.

Description:

Disable the PVD Extended Interrupt

Falling Trigger.

__HAL_PWR_PVD_EXTI_ENABLE_RISING_

EDGE

__HAL_PWR_PVD_EXTI_DISABLE_RISING

_EDGE

__HAL_PWR_PVD_EXTI_ENABLE_RISING_

FALLING_EDGE

__HAL_PWR_PVD_EXTI_DISABLE_RISING

_FALLING_EDGE

__HAL_PWR_PVD_EXTI_GET_FLAG

Return value:

None.

Description:

PVD EXTI line configuration: set rising edge trigger.

Return value:

None.

Description:

Disable the PVD Extended Interrupt

Rising Trigger.

Return value:

None.

Description:

PVD EXTI line configuration: set rising & falling edge trigger.

Return value:

None.

Description:

Disable the PVD Extended Interrupt

Rising & Falling Trigger.

Return value:

None.

Description:

Check whether the specified PVD

EXTI interrupt flag is set or not.

DOCID026682 Rev 3 361/654

HAL PWR Generic Driver

UM1816

__HAL_PWR_PVD_EXTI_CLEAR_FLAG

Return value:

EXTI: PVD Line Status.

Description:

Clear the PVD EXTI flag.

Return value:

None.

__HAL_PWR_PVD_EXTI_GENERATE_SWIT Description:

Generate a Software interrupt on selected EXTI line.

Return value:

None.

PWR Flag

PWR_FLAG_WU

PWR_FLAG_SB

PWR_FLAG_PVDO

PWR_FLAG_VREFINTRDY

PWR_FLAG_VOS

PWR_FLAG_REGLP

PWR_Private_Constants

PWR_EXTI_LINE_PVD External interrupt line 16 Connected to the PVD EXTI Line

PWR Private Macros

IS_PWR_PVD_LEVEL

IS_PWR_PVD_MODE

IS_PWR_REGULATOR

IS_PWR_SLEEP_ENTRY

IS_PWR_STOP_ENTRY

IS_PWR_VOLTAGE_SCALING_RANGE

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 Mode

362/654 DOCID026682 Rev 3

UM1816

PWR_PVD_MODE_NORMAL

PWR_PVD_MODE_IT_RISING

PWR_PVD_MODE_IT_FALLING

HAL PWR Generic Driver basic mode is used

External Interrupt Mode with Rising edge trigger detection

External Interrupt Mode with Falling edge trigger detection

PWR_PVD_MODE_IT_RISING_FALLING

PWR_PVD_MODE_EVENT_RISING

External Interrupt Mode with

Rising/Falling edge trigger detection

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 Register alias address

PWR_OFFSET

PWR_CR_OFFSET

PWR_CSR_OFFSET

PWR_CR_OFFSET_BB

PWR_CSR_OFFSET_BB

PWR Regulator state in SLEEP/STOP mode

PWR_MAINREGULATOR_ON

PWR_LOWPOWERREGULATOR_ON

PWR Regulator Voltage Scale

PWR_REGULATOR_VOLTAGE_SCALE1

PWR_REGULATOR_VOLTAGE_SCALE2

PWR_REGULATOR_VOLTAGE_SCALE3

PWR SLEEP mode entry

PWR_SLEEPENTRY_WFI

PWR_SLEEPENTRY_WFE

PWR STOP mode entry

PWR_STOPENTRY_WFI

PWR_STOPENTRY_WFE

363/654 DOCID026682 Rev 3

HAL PWR Extension Driver

UM1816

32 HAL PWR Extension Driver

32.1 HAL PWR Extension Driver

32.2 PWREx Firmware driver API description

32.2.1 Peripheral extended features functions

This section contains the following APIs:

HAL_PWREx_GetVoltageRange()

HAL_PWREx_EnableFastWakeUp()

HAL_PWREx_DisableFastWakeUp()

HAL_PWREx_EnableUltraLowPower()

HAL_PWREx_DisableUltraLowPower()

HAL_PWREx_EnableLowPowerRunMode()

HAL_PWREx_DisableLowPowerRunMode()

32.2.2 HAL_PWREx_GetVoltageRange

Function Name uint32_t HAL_PWREx_GetVoltageRange (void )

Function Description Return Voltage Scaling Range.

Return values

VOS bit field (PWR_REGULATOR_VOLTAGE_SCALE1,

PWR_REGULATOR_VOLTAGE_SCALE2 or

PWR_REGULATOR_VOLTAGE_SCALE3)

32.2.3 HAL_PWREx_EnableFastWakeUp

Function Name void HAL_PWREx_EnableFastWakeUp (void )

Function Description Enables the Fast WakeUp from Ultra Low Power mode.

Return values

None

Notes

This bit works in conjunction with ULP bit. Means, when ULP

= 1 and FWU = 1 :VREFINT startup time is ignored when exiting from low power mode.

32.2.4 HAL_PWREx_DisableFastWakeUp

Function Name void HAL_PWREx_DisableFastWakeUp (void )

Function Description Disables the Fast WakeUp from Ultra Low Power mode.

Return values

None

32.2.5 HAL_PWREx_EnableUltraLowPower

Function Name

void HAL_PWREx_EnableUltraLowPower (void )

Function Description Enables the Ultra Low Power mode.

Return values

None

364/654 DOCID026682 Rev 3

UM1816

32.2.6 HAL_PWREx_DisableUltraLowPower

HAL PWR Extension Driver

Function Name void HAL_PWREx_DisableUltraLowPower (void )

Function Description Disables the Ultra Low Power mode.

Return values

None

32.2.7 HAL_PWREx_EnableLowPowerRunMode

Function Name

void HAL_PWREx_EnableLowPowerRunMode (void )

Function Description Enters the Low Power Run mode.

Return values

None

Notes

Low power run mode can only be entered when VCORE is in range 2. In addition, the dynamic voltage scaling must not be used when Low power run mode is selected. Only Stop and

Sleep modes with regulator configured in Low power mode is allowed when Low power run mode is selected.

In Low power run mode, all I/O pins keep the same state as in

Run mode.

32.2.8 HAL_PWREx_DisableLowPowerRunMode

Function Name void HAL_PWREx_DisableLowPowerRunMode (void )

Function Description Exits the Low Power Run mode.

Return values

None

32.3 PWREx Firmware driver defines

32.3.1 PWREx

PWREx Wakeup Pins

PWR_WAKEUP_PIN1

PWR_WAKEUP_PIN2

PWR_WAKEUP_PIN3

IS_PWR_WAKEUP_PIN

DOCID026682 Rev 3 365/654

HAL RCC Generic Driver

UM1816

33 HAL RCC Generic Driver

33.1 HAL RCC Generic Driver

33.2 RCC Firmware driver registers structures

33.2.1 RCC_PLLInitTypeDef

Data Fields

uint32_t PLLState

uint32_t PLLSource

uint32_t PLLMUL

uint32_t PLLDIV

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

PLLSource: PLL entry clock source. This parameter must be a value of

RCC_PLL_Clock_Source

uint32_t RCC_PLLInitTypeDef::PLLMUL

PLLMUL: Multiplication factor for PLL VCO input clock This parameter must be a

value of

RCC_PLL_Multiplication_Factor

uint32_t RCC_PLLInitTypeDef::PLLDIV

PLLDIV: Division factor for PLL VCO input clock This parameter must be a value of

RCC_PLL_Division_Factor

33.2.2 RCC_OscInitTypeDef

Data Fields

uint32_t OscillatorType

uint32_t HSEState

uint32_t LSEState

uint32_t HSIState

uint32_t HSICalibrationValue

uint32_t LSIState

uint32_t MSIState

uint32_t MSICalibrationValue

uint32_t MSIClockRange

RCC_PLLInitTypeDef PLL

Field Documentation

366/654 DOCID026682 Rev 3

UM1816

HAL RCC Generic Driver

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

uint32_t RCC_OscInitTypeDef::MSIState

The new state of the MSI. This parameter can be a value of

RCC_MSI_Config

uint32_t RCC_OscInitTypeDef::MSICalibrationValue

The MSI calibration trimming value. (default is RCC_MSICALIBRATION_DEFAULT).

This parameter must be a number between Min_Data = 0x00 and Max_Data = 0xFF

uint32_t RCC_OscInitTypeDef::MSIClockRange

The MSI frequency range. This parameter can be a value of

RCC_MSI_Clock_Range

RCC_PLLInitTypeDef RCC_OscInitTypeDef::PLL

PLL structure parameters

33.2.3 RCC_ClkInitTypeDef

Data Fields

uint32_t ClockType

uint32_t SYSCLKSource

uint32_t AHBCLKDivider

uint32_t APB1CLKDivider

uint32_t APB2CLKDivider

Field Documentation

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

DOCID026682 Rev 3 367/654

HAL RCC Generic Driver

UM1816

33.3 RCC Firmware driver API description

33.3.1 RCC specific features

After reset the device is running from multispeed internal oscillator clock (MSI 2.097MHz) with Flash 0 wait state and Flash prefetch buffer is 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 MSI 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 whose clocks are not derived from the

System clock (I2S, RTC, ADC, USB OTG FS/SDIO/RNG) (*) SDIO only for

STM32L1xxxD devices

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

AHB & APB peripherals, 1 dummy read is necessary

Workarounds:

1. For AHB & APB peripherals, a dummy read to the peripheral register has been inserted in each __HAL_RCC_PPP_CLK_ENABLE() macro.

33.3.3 Initialization and de-initialization function

This section provides functions allowing to configure the internal/external oscillators (MSI,

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. MSI (Multispeed internal), Seven frequency ranges are available: 65.536 kHz,

131.072 kHz, 262.144 kHz, 524.288 kHz, 1.048 MHz, 2.097 MHz (default value) and

4.194 MHz.

2. HSI (high-speed internal), 16 MHz factory-trimmed RC used directly or through the

PLL as System clock source.

3. LSI (low-speed internal), ~37 KHz low consumption RC used as IWDG and/or RTC clock source.

4. HSE (high-speed external), 1 to 24 MHz crystal oscillator used directly or through the

PLL as System clock source. Can be used also as RTC clock source.

5. LSE (low-speed external), 32 KHz oscillator used as RTC clock source.

6. 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 32 MHz)

368/654 DOCID026682 Rev 3

UM1816

HAL RCC Generic Driver

The second output is used to generate the clock for the USB OTG FS (48 MHz)

7. 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 clockis automatically switched to

MSI and an interrupt is generated if enabled. The interrupt is linked to the Cortex-M3

NMI (Non-Maskable Interrupt) exception vector.

8. MCO1 (microcontroller clock output), used to output SYSCLK, HSI, LSI, MSI, LSE,

HSE or PLL clock (through a configurable prescaler) on PA8 pin.

System, AHB and APB busses clocks configuration

1. Several clock sources can be used to drive the System clock (SYSCLK): MSI, 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. All the peripheral clocks are derived from the

System clock (SYSCLK) except: RTC: RTC clock can be derived either from the LSI,

LSE or HSE clock divided by 2 to 16. You have to use __HAL_RCC_RTC_CONFIG() and __HAL_RCC_RTC_ENABLE() macros to configure this clock. LCD: LCD clock can be derived either from the LSI, LSE or HSE clock divided by 2 to 16. You have to use __HAL_RCC_LCD_CONFIG() macros to configure this clock. USB OTG FS and

RTC: USB OTG FS require a frequency equal to 48 MHz to work correctly. This clock is derived of the main PLL through PLL Multiplier. IWDG clock which is always the LSI clock.

2. The maximum frequency of the SYSCLK and HCLK is 32 MHz, PCLK2 32 MHz and

PCLK1 32 MHz. Depending on the device voltage range, the maximum frequency

should be adapted accordingly (see

Table 21: "Number of wait states (WS) according to CPU clock (HCLK) frequency"

).

3. The following table gives the different clock source frequencies depending on the

product voltage range (see

Table 22: "Clock frequency versus product voltage range"

)

Table 21: Number of wait states (WS) according to CPU clock (HCLK) frequency

HCLK clock frequency (MHz)

Latency voltage range 1 (1.8 V) voltage range 2 (1.5 V) voltage range 3 (1.2 V)

0W(1CPU cycles)

1WS(2CPU cycles)

0 < HCLK ≤ 16

16< HCLK ≤ 32

0 < HCLK ≤ 8

8 < HCLK ≤ 16

0 < HCLK ≤ 2

2 < HCLK ≤ 4

Table 22: Clock frequency versus product voltage range

Clock frequency

Product voltage range

MSI HSI HSE PLL

Range 1 (1.8 V)

Range 2 (1.5 V)

Range 3 (1.2 V)

4.2

MHz

4.2

MHz

4.2

MHz

16

MHz

16

MHz

NA

32 MHz HSE (external clock) or

24 MHz (crystal)

This section contains the following APIs:

HAL_RCC_DeInit()

16 MHz

8 MHz

32 MHz (PLLVCO max

= 96 MHz)

16 MHz (PLLVCO max

= 48 MHz)

4 MHz (PLLVCO max =

24 MHz)

DOCID026682 Rev 3 369/654

HAL RCC Generic Driver

HAL_RCC_OscConfig()

HAL_RCC_ClockConfig()

33.3.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()

UM1816

33.3.5 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: MSI ON and used as system clock sourceHSI, HSE and PLL OFFAHB, APB1 and APB2 prescaler set to 1.CSS and MCO1 OFFAll interrupts disabled

This function doesn't modify the configuration of the

Peripheral clocksLSI, LSE and RTC clocks

33.3.6 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

Notes

HAL status

The PLL is not disabled when used as system clock.

33.3.7 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

370/654 DOCID026682 Rev 3

UM1816

Parameters

Return values

Notes

HAL RCC Generic Driver specified parameters in the RCC_ClkInitStruct.

RCC_ClkInitStruct: pointer to an RCC_OscInitTypeDef structure that contains the configuration information for the

RCC peripheral.

FLatency: FLASH Latency This parameter can be one of the following values: FLASH_LATENCY_0: FLASH 0 Latency cycleFLASH_LATENCY_1: FLASH 1 Latency cycle

HAL status

The SystemCoreClock CMSIS variable is used to store

System Clock Frequency and updated by

HAL_RCC_GetHCLKFreq() function called within this function

The MSI 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. You can use HAL_RCC_GetClockConfig() function to know which clock is currently used as system clock source.

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")

33.3.8 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 MCO pin.

Parameters

RCC_MCOx: specifies the output direction for the clock source. This parameter can be one of the following values:

RCC_MCO: Clock source to output on MCO1 pin(PA8).

RCC_MCOSource: specifies the clock source to output. This parameter can be one of the following values:

RCC_MCO1SOURCE_NOCLOCK: No clock selectedRCC_MCO1SOURCE_SYSCLK: System clock selectedRCC_MCO1SOURCE_HSI: HSI oscillator clock selectedRCC_MCO1SOURCE_MSI: MSI oscillator clock selectedRCC_MCO1SOURCE_HSE: HSE oscillator clock selectedRCC_MCO1SOURCE_PLLCLK: PLL clock selectedRCC_MCO1SOURCE_LSI: LSI clock selectedRCC_MCO1SOURCE_LSE: LSE clock selected

RCC_MCODiv: specifies the MCO DIV. This parameter can be one of the following values: RCC_MCODIV_1: no division applied to MCO clockRCC_MCODIV_2: division by 2 applied to MCO clockRCC_MCODIV_4: division by 4 applied to MCO clockRCC_MCODIV_8: division by 8 applied to MCO clockRCC_MCODIV_16: division by 16 applied to MCO clock

DOCID026682 Rev 3 371/654

HAL RCC Generic Driver

Return values

Notes

UM1816

None

MCO pin should be configured in alternate function mode.

33.3.9 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 Cortex-

M3 NMI (Non-Maskable Interrupt) exception vector.

33.3.10 HAL_RCC_DisableCSS

Function Name

void HAL_RCC_DisableCSS (void )

Function Description Disables the Clock Security System.

Return values

None

33.3.11 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 MSI, function returns values based on

MSI Value as defined by the MSI range.

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 stm32l1xx_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 stm32l1xx_hal_conf.h file (default value 8 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.

372/654 DOCID026682 Rev 3

UM1816

HAL RCC Generic Driver

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.

33.3.12 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

33.3.13 HAL_RCC_GetPCLK1Freq

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 based on this function will be incorrect.

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

33.3.15 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

Return values

RCC_OscInitStruct: pointer to an RCC_OscInitTypeDef structure that will be configured.

None

33.3.16 HAL_RCC_GetClockConfig

Function Name

void HAL_RCC_GetClockConfig (RCC_ClkInitTypeDef *

RCC_ClkInitStruct, uint32_t * pFLatency)

DOCID026682 Rev 3 373/654

HAL RCC Generic Driver

Function Description Get the RCC_ClkInitStruct according to the internal RCC configuration registers.

Parameters

UM1816

RCC_ClkInitStruct: pointer to an RCC_ClkInitTypeDef structure that contains the current clock configuration.

pFLatency: Pointer on the Flash Latency.

Return values

None

33.3.17 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().

33.3.18 HAL_RCC_CSSCallback

Function Name void HAL_RCC_CSSCallback (void )

Function Description RCC Clock Security System interrupt callback.

Return values

 none

33.4 RCC Firmware driver defines

33.4.1 RCC

AHB Peripheral Clock Sleep Enable Disable Status

__HAL_RCC_GPIOA_IS_CLK_SLEEP_ENABLED

__HAL_RCC_GPIOB_IS_CLK_SLEEP_ENABLED

__HAL_RCC_GPIOC_IS_CLK_SLEEP_ENABLED

__HAL_RCC_GPIOD_IS_CLK_SLEEP_ENABLED

__HAL_RCC_GPIOH_IS_CLK_SLEEP_ENABLED

__HAL_RCC_CRC_IS_CLK_SLEEP_ENABLED

__HAL_RCC_FLITF_IS_CLK_SLEEP_ENABLED

__HAL_RCC_DMA1_IS_CLK_SLEEP_ENABLED

__HAL_RCC_GPIOA_IS_CLK_SLEEP_DISABLED

__HAL_RCC_GPIOB_IS_CLK_SLEEP_DISABLED

__HAL_RCC_GPIOC_IS_CLK_SLEEP_DISABLED

__HAL_RCC_GPIOD_IS_CLK_SLEEP_DISABLED

__HAL_RCC_GPIOH_IS_CLK_SLEEP_DISABLED

__HAL_RCC_CRC_IS_CLK_SLEEP_DISABLED

__HAL_RCC_FLITF_IS_CLK_SLEEP_DISABLED

__HAL_RCC_DMA1_IS_CLK_SLEEP_DISABLED

AHB Clock Source

374/654 DOCID026682 Rev 3

UM1816

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

AHB 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_GPIOD_IS_CLK_ENABLED

__HAL_RCC_GPIOH_IS_CLK_ENABLED

__HAL_RCC_CRC_IS_CLK_ENABLED

__HAL_RCC_FLITF_IS_CLK_ENABLED

__HAL_RCC_DMA1_IS_CLK_ENABLED

__HAL_RCC_GPIOA_IS_CLK_DISABLED

__HAL_RCC_GPIOB_IS_CLK_DISABLED

__HAL_RCC_GPIOC_IS_CLK_DISABLED

__HAL_RCC_GPIOD_IS_CLK_DISABLED

__HAL_RCC_GPIOH_IS_CLK_DISABLED

__HAL_RCC_CRC_IS_CLK_DISABLED

__HAL_RCC_FLITF_IS_CLK_DISABLED

__HAL_RCC_DMA1_IS_CLK_DISABLED

APB1 APB2 Clock Source

RCC_HCLK_DIV1

RCC_HCLK_DIV2

RCC_HCLK_DIV4

RCC_HCLK_DIV8

RCC_HCLK_DIV16

APB1 Clock Enable Disable

__HAL_RCC_TIM2_CLK_ENABLE

__HAL_RCC_TIM3_CLK_ENABLE

__HAL_RCC_TIM4_CLK_ENABLE

DOCID026682 Rev 3

HAL RCC Generic Driver

375/654

HAL RCC Generic Driver

__HAL_RCC_TIM6_CLK_ENABLE

__HAL_RCC_TIM7_CLK_ENABLE

__HAL_RCC_WWDG_CLK_ENABLE

__HAL_RCC_SPI2_CLK_ENABLE

__HAL_RCC_USART2_CLK_ENABLE

__HAL_RCC_USART3_CLK_ENABLE

__HAL_RCC_I2C1_CLK_ENABLE

__HAL_RCC_I2C2_CLK_ENABLE

__HAL_RCC_USB_CLK_ENABLE

__HAL_RCC_PWR_CLK_ENABLE

__HAL_RCC_DAC_CLK_ENABLE

__HAL_RCC_COMP_CLK_ENABLE

__HAL_RCC_TIM2_CLK_DISABLE

__HAL_RCC_TIM3_CLK_DISABLE

__HAL_RCC_TIM4_CLK_DISABLE

__HAL_RCC_TIM6_CLK_DISABLE

__HAL_RCC_TIM7_CLK_DISABLE

__HAL_RCC_WWDG_CLK_DISABLE

__HAL_RCC_SPI2_CLK_DISABLE

__HAL_RCC_USART2_CLK_DISABLE

__HAL_RCC_USART3_CLK_DISABLE

__HAL_RCC_I2C1_CLK_DISABLE

__HAL_RCC_I2C2_CLK_DISABLE

__HAL_RCC_USB_CLK_DISABLE

__HAL_RCC_PWR_CLK_DISABLE

__HAL_RCC_DAC_CLK_DISABLE

__HAL_RCC_COMP_CLK_DISABLE

APB1 Peripheral Clock Sleep Enable Disable Status

__HAL_RCC_TIM2_IS_CLK_SLEEP_ENABLED

__HAL_RCC_TIM3_IS_CLK_SLEEP_ENABLED

__HAL_RCC_TIM4_IS_CLK_SLEEP_ENABLED

__HAL_RCC_TIM6_IS_CLK_SLEEP_ENABLED

__HAL_RCC_TIM7_IS_CLK_SLEEP_ENABLED

__HAL_RCC_WWDG_IS_CLK_SLEEP_ENABLED

__HAL_RCC_SPI2_IS_CLK_SLEEP_ENABLED

__HAL_RCC_USART2_IS_CLK_SLEEP_ENABLED

376/654 DOCID026682 Rev 3

UM1816

UM1816

__HAL_RCC_USART3_IS_CLK_SLEEP_ENABLED

__HAL_RCC_I2C1_IS_CLK_SLEEP_ENABLED

__HAL_RCC_I2C2_IS_CLK_SLEEP_ENABLED

__HAL_RCC_USB_IS_CLK_SLEEP_ENABLED

__HAL_RCC_PWR_IS_CLK_SLEEP_ENABLED

__HAL_RCC_DAC_IS_CLK_SLEEP_ENABLED

__HAL_RCC_COMP_IS_CLK_SLEEP_ENABLED

__HAL_RCC_TIM2_IS_CLK_SLEEP_DISABLED

__HAL_RCC_TIM3_IS_CLK_SLEEP_DISABLED

__HAL_RCC_TIM4_IS_CLK_SLEEP_DISABLED

__HAL_RCC_TIM6_IS_CLK_SLEEP_DISABLED

__HAL_RCC_TIM7_IS_CLK_SLEEP_DISABLED

__HAL_RCC_WWDG_IS_CLK_SLEEP_DISABLED

__HAL_RCC_SPI2_IS_CLK_SLEEP_DISABLED

__HAL_RCC_USART2_IS_CLK_SLEEP_DISABLED

__HAL_RCC_USART3_IS_CLK_SLEEP_DISABLED

__HAL_RCC_I2C1_IS_CLK_SLEEP_DISABLED

__HAL_RCC_I2C2_IS_CLK_SLEEP_DISABLED

__HAL_RCC_USB_IS_CLK_SLEEP_DISABLED

__HAL_RCC_PWR_IS_CLK_SLEEP_DISABLED

__HAL_RCC_DAC_IS_CLK_SLEEP_DISABLED

__HAL_RCC_COMP_IS_CLK_SLEEP_DISABLED

APB1 Force Release Reset

__HAL_RCC_APB1_FORCE_RESET

__HAL_RCC_TIM2_FORCE_RESET

__HAL_RCC_TIM3_FORCE_RESET

__HAL_RCC_TIM4_FORCE_RESET

__HAL_RCC_TIM6_FORCE_RESET

__HAL_RCC_TIM7_FORCE_RESET

__HAL_RCC_WWDG_FORCE_RESET

__HAL_RCC_SPI2_FORCE_RESET

__HAL_RCC_USART2_FORCE_RESET

__HAL_RCC_USART3_FORCE_RESET

__HAL_RCC_I2C1_FORCE_RESET

__HAL_RCC_I2C2_FORCE_RESET

__HAL_RCC_USB_FORCE_RESET

DOCID026682 Rev 3

HAL RCC Generic Driver

377/654

HAL RCC Generic Driver

__HAL_RCC_PWR_FORCE_RESET

__HAL_RCC_DAC_FORCE_RESET

__HAL_RCC_COMP_FORCE_RESET

__HAL_RCC_APB1_RELEASE_RESET

__HAL_RCC_TIM2_RELEASE_RESET

__HAL_RCC_TIM3_RELEASE_RESET

__HAL_RCC_TIM4_RELEASE_RESET

__HAL_RCC_TIM6_RELEASE_RESET

__HAL_RCC_TIM7_RELEASE_RESET

__HAL_RCC_WWDG_RELEASE_RESET

__HAL_RCC_SPI2_RELEASE_RESET

__HAL_RCC_USART2_RELEASE_RESET

__HAL_RCC_USART3_RELEASE_RESET

__HAL_RCC_I2C1_RELEASE_RESET

__HAL_RCC_I2C2_RELEASE_RESET

__HAL_RCC_USB_RELEASE_RESET

__HAL_RCC_PWR_RELEASE_RESET

__HAL_RCC_DAC_RELEASE_RESET

__HAL_RCC_COMP_RELEASE_RESET

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_TIM6_IS_CLK_ENABLED

__HAL_RCC_TIM7_IS_CLK_ENABLED

__HAL_RCC_WWDG_IS_CLK_ENABLED

__HAL_RCC_SPI2_IS_CLK_ENABLED

__HAL_RCC_USART2_IS_CLK_ENABLED

__HAL_RCC_USART3_IS_CLK_ENABLED

__HAL_RCC_I2C1_IS_CLK_ENABLED

__HAL_RCC_I2C2_IS_CLK_ENABLED

__HAL_RCC_USB_IS_CLK_ENABLED

__HAL_RCC_PWR_IS_CLK_ENABLED

__HAL_RCC_DAC_IS_CLK_ENABLED

__HAL_RCC_COMP_IS_CLK_ENABLED

__HAL_RCC_TIM2_IS_CLK_DISABLED

378/654 DOCID026682 Rev 3

UM1816

UM1816

__HAL_RCC_TIM3_IS_CLK_DISABLED

__HAL_RCC_TIM4_IS_CLK_DISABLED

__HAL_RCC_TIM6_IS_CLK_DISABLED

__HAL_RCC_TIM7_IS_CLK_DISABLED

__HAL_RCC_WWDG_IS_CLK_DISABLED

__HAL_RCC_SPI2_IS_CLK_DISABLED

__HAL_RCC_USART2_IS_CLK_DISABLED

__HAL_RCC_USART3_IS_CLK_DISABLED

__HAL_RCC_I2C1_IS_CLK_DISABLED

__HAL_RCC_I2C2_IS_CLK_DISABLED

__HAL_RCC_USB_IS_CLK_DISABLED

__HAL_RCC_PWR_IS_CLK_DISABLED

__HAL_RCC_DAC_IS_CLK_DISABLED

__HAL_RCC_COMP_IS_CLK_DISABLED

APB2 Clock Enable Disable

__HAL_RCC_SYSCFG_CLK_ENABLE

__HAL_RCC_TIM9_CLK_ENABLE

__HAL_RCC_TIM10_CLK_ENABLE

__HAL_RCC_TIM11_CLK_ENABLE

__HAL_RCC_ADC1_CLK_ENABLE

__HAL_RCC_SPI1_CLK_ENABLE

__HAL_RCC_USART1_CLK_ENABLE

__HAL_RCC_SYSCFG_CLK_DISABLE

__HAL_RCC_TIM9_CLK_DISABLE

__HAL_RCC_TIM10_CLK_DISABLE

__HAL_RCC_TIM11_CLK_DISABLE

__HAL_RCC_ADC1_CLK_DISABLE

__HAL_RCC_SPI1_CLK_DISABLE

__HAL_RCC_USART1_CLK_DISABLE

APB2 Peripheral Clock Sleep Enable Disable Status

__HAL_RCC_SYSCFG_IS_CLK_SLEEP_ENABLED

__HAL_RCC_TIM9_IS_CLK_SLEEP_ENABLED

__HAL_RCC_TIM10_IS_CLK_SLEEP_ENABLED

__HAL_RCC_TIM11_IS_CLK_SLEEP_ENABLED

__HAL_RCC_ADC1_IS_CLK_SLEEP_ENABLED

__HAL_RCC_SPI1_IS_CLK_SLEEP_ENABLED

DOCID026682 Rev 3

HAL RCC Generic Driver

379/654

HAL RCC Generic Driver

__HAL_RCC_USART1_IS_CLK_SLEEP_ENABLED

__HAL_RCC_SYSCFG_IS_CLK_SLEEP_DISABLED

__HAL_RCC_TIM9_IS_CLK_SLEEP_DISABLED

__HAL_RCC_TIM10_IS_CLK_SLEEP_DISABLED

__HAL_RCC_TIM11_IS_CLK_SLEEP_DISABLED

__HAL_RCC_ADC1_IS_CLK_SLEEP_DISABLED

__HAL_RCC_SPI1_IS_CLK_SLEEP_DISABLED

__HAL_RCC_USART1_IS_CLK_SLEEP_DISABLED

APB2 Force Release Reset

__HAL_RCC_APB2_FORCE_RESET

__HAL_RCC_SYSCFG_FORCE_RESET

__HAL_RCC_TIM9_FORCE_RESET

__HAL_RCC_TIM10_FORCE_RESET

__HAL_RCC_TIM11_FORCE_RESET

__HAL_RCC_ADC1_FORCE_RESET

__HAL_RCC_SPI1_FORCE_RESET

__HAL_RCC_USART1_FORCE_RESET

__HAL_RCC_APB2_RELEASE_RESET

__HAL_RCC_SYSCFG_RELEASE_RESET

__HAL_RCC_TIM9_RELEASE_RESET

__HAL_RCC_TIM10_RELEASE_RESET

__HAL_RCC_TIM11_RELEASE_RESET

__HAL_RCC_ADC1_RELEASE_RESET

__HAL_RCC_SPI1_RELEASE_RESET

__HAL_RCC_USART1_RELEASE_RESET

APB2 Peripheral Clock Enable Disable Status

__HAL_RCC_SYSCFG_IS_CLK_ENABLED

__HAL_RCC_TIM9_IS_CLK_ENABLED

__HAL_RCC_TIM10_IS_CLK_ENABLED

__HAL_RCC_TIM11_IS_CLK_ENABLED

__HAL_RCC_ADC1_IS_CLK_ENABLED

__HAL_RCC_SPI1_IS_CLK_ENABLED

__HAL_RCC_USART1_IS_CLK_ENABLED

__HAL_RCC_SYSCFG_IS_CLK_DISABLED

__HAL_RCC_TIM9_IS_CLK_DISABLED

__HAL_RCC_TIM10_IS_CLK_DISABLED

380/654 DOCID026682 Rev 3

UM1816

UM1816

__HAL_RCC_TIM11_IS_CLK_DISABLED

__HAL_RCC_ADC1_IS_CLK_DISABLED

__HAL_RCC_SPI1_IS_CLK_DISABLED

__HAL_RCC_USART1_IS_CLK_DISABLED

BitAddress AliasRegion

RCC_CR_OFFSET_BB

RCC_CFGR_OFFSET_BB

RCC_CIR_OFFSET_BB

RCC_CSR_OFFSET_BB

HSION_BITNUMBER

RCC_CR_HSION_BB

MSION_BITNUMBER

RCC_CR_MSION_BB

HSEON_BITNUMBER

CR_HSEON_BB

CSSON_BITNUMBER

RCC_CR_CSSON_BB

PLLON_BITNUMBER

RCC_CR_PLLON_BB

LSION_BITNUMBER

RCC_CSR_LSION_BB

LSEON_BITNUMBER

RCC_CSR_LSEON_BB

LSEBYP_BITNUMBER

RCC_CSR_LSEBYP_BB

RTCEN_BITNUMBER

RCC_CSR_RTCEN_BB

RTCRST_BITNUMBER

RCC_CSR_RTCRST_BB

Flags

RCC_FLAG_HSIRDY

RCC_FLAG_MSIRDY

RCC_FLAG_HSERDY

Internal High Speed clock ready flag

MSI clock ready flag

External High Speed clock ready flag

RCC_FLAG_PLLRDY

RCC_FLAG_LSIRDY

RCC_FLAG_LSECSS

PLL clock ready flag

Internal Low Speed oscillator Ready

CSS on LSE failure Detection

HAL RCC Generic Driver

DOCID026682 Rev 3 381/654

HAL RCC Generic Driver

RCC_FLAG_RMV

RCC_FLAG_OBLRST

RCC_FLAG_PINRST

RCC_FLAG_PORRST

RCC_FLAG_SFTRST

Remove reset flag

Options bytes loading reset flag

PIN reset flag

POR/PDR reset flag

Software Reset flag

UM1816

RCC_FLAG_IWDGRST Independent Watchdog reset flag

RCC_FLAG_WWDGRST Window watchdog reset flag

RCC_FLAG_LPWRRST Low-Power reset flag

RCC_FLAG_LSERDY External Low Speed oscillator Ready

Flags Interrupts Management

__HAL_RCC_ENABLE_IT

__HAL_RCC_DISABLE_IT

Description:

Enable RCC interrupt.

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

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_MSIRDY: MSI ready interrupt

RCC_IT_LSECSS: LSE CSS interrupt

(not available for STM32L100xB ||

STM32L151xB || STM32L152xB devices)

Description:

Disable RCC interrupt.

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_MSIRDY: MSI ready interrupt

RCC_IT_LSECSS: LSE CSS interrupt

(not available for STM32L100xB ||

382/654 DOCID026682 Rev 3

UM1816

__HAL_RCC_CLEAR_IT

__HAL_RCC_GET_IT

HAL RCC Generic Driver

STM32L151xB || STM32L152xB devices)

Description:

Clear the RCC's 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_MSIRDY: MSI ready interrupt

RCC_IT_LSECSS: LSE CSS interrupt

(not available for STM32L100xB ||

STM32L151xB || STM32L152xB devices)

RCC_IT_CSS: Clock Security System interrupt

Description:

Check the RCC's interrupt has occurred or 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_MSIRDY: MSI ready interrupt

RCC_IT_LSECSS: LSE CSS interrupt

(not available for STM32L100xB ||

STM32L151xB || STM32L152xB devices)

RCC_IT_CSS: Clock Security System interrupt

Return value:

The: new state of __INTERRUPT__ (TRUE or FALSE).

__HAL_RCC_CLEAR_RESET_FLAGS The reset flags are: RCC_FLAG_PINRST,

RCC_FLAG_PORRST, RCC_FLAG_SFTRST,

RCC_FLAG_IWDGRST,

DOCID026682 Rev 3 383/654

HAL RCC Generic Driver

384/654

__HAL_RCC_GET_FLAG

UM1816

RCC_FLAG_WWDGRST,

RCC_FLAG_LPWRRST

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_MSIRDY: MSI oscillator clock ready.

RCC_FLAG_HSERDY: HSE oscillator clock ready.

RCC_FLAG_PLLRDY: Main PLL clock ready.

RCC_FLAG_LSERDY: LSE oscillator clock ready.

RCC_FLAG_LSECSS: CSS on LSE failure Detection (*)

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

Return value:

The: new state of __FLAG__ (TRUE or

FALSE).

Notes:

(*) This bit is available in high and medium+ density devices only.

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_MSI: MSI

DOCID026682 Rev 3

UM1816

__HAL_RCC_GET_SYSCLK_SOU

RCE

HAL RCC Generic Driver oscillator is used as system clock source.

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.

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_MSI:

MSI used as system clock

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

HSE Config

RCC_HSE_OFF

RCC_HSE_ON

HSE clock deactivation

HSE clock activation

RCC_HSE_BYPASS External clock source for HSE clock

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:

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

DOCID026682 Rev 3 385/654

HAL RCC Generic Driver

UM1816

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 clock deactivation

HSI clock activation

HSI Configuration

__HAL_RCC_HSI_ENABLE

__HAL_RCC_HSI_DISABLE

__HAL_RCC_HSI_CALIBRATIONVALUE_ADJUS

T

Notes:

The HSI is stopped by hardware when entering STOP and

STANDBY modes. 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. When the

HSI is stopped, HSIRDY flag goes low after 6 HSI oscillator clock cycles.

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.

Interrupts

386/654 DOCID026682 Rev 3

UM1816

RCC_IT_LSIRDY

RCC_IT_LSERDY

RCC_IT_HSIRDY

RCC_IT_HSERDY

RCC_IT_PLLRDY

LSI Ready Interrupt flag

LSE Ready Interrupt flag

HSI Ready Interrupt flag

HSE Ready Interrupt flag

PLL Ready Interrupt flag

RCC_IT_MSIRDY

RCC_IT_LSECSS

RCC_IT_CSS

LSE Config

MSI Ready Interrupt flag

LSE Clock Security System Interrupt flag

Clock Security System Interrupt flag

RCC_LSE_OFF

RCC_LSE_ON

LSE clock deactivation

LSE clock activation

RCC_LSE_BYPASS External clock source for LSE clock

LSE Configuration

HAL RCC Generic Driver

__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:

Transitions LSE Bypass to LSE On and LSE On to

LSE Bypass are not supported by this macro. 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

LSI clock deactivation

LSI clock activation

__HAL_RCC_LSI_ENABLE

Notes:

After enabling the LSI, the application software should wait on LSIRDY flag to be set indicating that LSI clock

DOCID026682 Rev 3 387/654

HAL RCC Generic Driver

__HAL_RCC_LSI_DISABLE

MCO1 Clock Source

RCC_MCO1SOURCE_NOCLOCK

RCC_MCO1SOURCE_SYSCLK

RCC_MCO1SOURCE_MSI

UM1816

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.

RCC_MCO1SOURCE_HSI

RCC_MCO1SOURCE_LSE

RCC_MCO1SOURCE_LSI

RCC_MCO1SOURCE_HSE

RCC_MCO1SOURCE_PLLCLK

MCO Clock Prescaler

RCC_MCODIV_1

RCC_MCODIV_2

RCC_MCODIV_4

RCC_MCODIV_8

RCC_MCODIV_16

MCO Index

RCC_MCO1

RCC_MCO

MSI Clock Range

MCO1 to be compliant with other families with 2 MCOs

RCC_MSIRANGE_0 MSI = 65.536 KHz

RCC_MSIRANGE_1 MSI = 131.072 KHz

RCC_MSIRANGE_2 MSI = 262.144 KHz

RCC_MSIRANGE_3 MSI = 524.288 KHz

RCC_MSIRANGE_4 MSI = 1.048 MHz

RCC_MSIRANGE_5 MSI = 2.097 MHz

RCC_MSIRANGE_6 MSI = 4.194 MHz

MSI Config

RCC_MSI_OFF

RCC_MSI_ON

RCC_MSICALIBRATION_DEFAULT

MSI Configuration

__HAL_RCC_MSI_ENABLE

Notes:

After enabling the MSI, the

388/654 DOCID026682 Rev 3

UM1816

__HAL_RCC_MSI_DISABLE

__HAL_RCC_MSI_CALIBRATIONVALUE_ADJUS

T

__HAL_RCC_MSI_RANGE_CONFIG

__HAL_RCC_GET_MSI_RANGE

HAL RCC Generic Driver application software should wait on MSIRDY flag to be set indicating that MSI clock is stable and can be used as system clock source.

Notes:

The MSI is stopped by hardware when entering STOP and

STANDBY modes. It is used

(enabled by hardware) as system clock source after startup from Reset, wakeup 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). MSI 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

MSI. When the MSI is stopped,

MSIRDY flag goes low after 6

MSI oscillator clock cycles.

Description:

Macro adjusts Internal Multi

Speed oscillator (MSI) calibration value.

Parameters:

_MSICALIBRATIONVALUE_: specifies the calibration trimming value. (default is

RCC_MSICALIBRATION_DEFA

ULT). This parameter must be a number between 0 and 0xFF.

Notes:

The calibration is used to compensate for the variations in voltage and temperature that influence the frequency of the internal MSI RC.

Description:

Macro to get the Internal Multi

Speed oscillator (MSI) clock range in run mode.

Return value:

DOCID026682 Rev 3 389/654

HAL RCC Generic Driver

390/654

Oscillator Type

RCC_OSCILLATORTYPE_NONE

RCC_OSCILLATORTYPE_HSE

RCC_OSCILLATORTYPE_HSI

RCC_OSCILLATORTYPE_LSE

RCC_OSCILLATORTYPE_LSI

RCC_OSCILLATORTYPE_MSI

Peripheral Clock Enable Disable

__HAL_RCC_GPIOA_CLK_ENABLE

__HAL_RCC_GPIOB_CLK_ENABLE

__HAL_RCC_GPIOC_CLK_ENABLE

__HAL_RCC_GPIOD_CLK_ENABLE

__HAL_RCC_GPIOH_CLK_ENABLE

__HAL_RCC_CRC_CLK_ENABLE

__HAL_RCC_FLITF_CLK_ENABLE

__HAL_RCC_DMA1_CLK_ENABLE

__HAL_RCC_GPIOA_CLK_DISABLE

__HAL_RCC_GPIOB_CLK_DISABLE

__HAL_RCC_GPIOC_CLK_DISABLE

__HAL_RCC_GPIOD_CLK_DISABLE

__HAL_RCC_GPIOH_CLK_DISABLE

DOCID026682 Rev 3

UM1816

MSI: clock range. This parameter must be one of the following values:

RCC_MSIRANGE_0: MSI clock is around 65.536 KHz

RCC_MSIRANGE_1: MSI clock is around 131.072

KHz

RCC_MSIRANGE_2: MSI clock is around 262.144

KHz

RCC_MSIRANGE_3: MSI clock is around 524.288

KHz

RCC_MSIRANGE_4: MSI clock is around 1.048 MHz

RCC_MSIRANGE_5: MSI clock is around 2.097 MHz

(default after Reset or wake-up from STANDBY)

RCC_MSIRANGE_6: MSI clock is around 4.194 MHz

UM1816

__HAL_RCC_CRC_CLK_DISABLE

__HAL_RCC_FLITF_CLK_DISABLE

__HAL_RCC_DMA1_CLK_DISABLE

RCC Peripheral Clock Force Release

__HAL_RCC_AHB_FORCE_RESET

__HAL_RCC_GPIOA_FORCE_RESET

__HAL_RCC_GPIOB_FORCE_RESET

__HAL_RCC_GPIOC_FORCE_RESET

__HAL_RCC_GPIOD_FORCE_RESET

__HAL_RCC_GPIOH_FORCE_RESET

__HAL_RCC_CRC_FORCE_RESET

__HAL_RCC_FLITF_FORCE_RESET

__HAL_RCC_DMA1_FORCE_RESET

__HAL_RCC_AHB_RELEASE_RESET

__HAL_RCC_GPIOA_RELEASE_RESET

__HAL_RCC_GPIOB_RELEASE_RESET

__HAL_RCC_GPIOC_RELEASE_RESET

__HAL_RCC_GPIOD_RELEASE_RESET

__HAL_RCC_GPIOH_RELEASE_RESET

__HAL_RCC_CRC_RELEASE_RESET

__HAL_RCC_FLITF_RELEASE_RESET

__HAL_RCC_DMA1_RELEASE_RESET

RCC Peripheral Clock Sleep Enable Disable

__HAL_RCC_GPIOA_CLK_SLEEP_ENABLE

__HAL_RCC_GPIOB_CLK_SLEEP_ENABLE

__HAL_RCC_GPIOC_CLK_SLEEP_ENABLE

__HAL_RCC_GPIOD_CLK_SLEEP_ENABLE

__HAL_RCC_GPIOH_CLK_SLEEP_ENABLE

__HAL_RCC_CRC_CLK_SLEEP_ENABLE

__HAL_RCC_FLITF_CLK_SLEEP_ENABLE

__HAL_RCC_DMA1_CLK_SLEEP_ENABLE

__HAL_RCC_GPIOA_CLK_SLEEP_DISABLE

__HAL_RCC_GPIOB_CLK_SLEEP_DISABLE

__HAL_RCC_GPIOC_CLK_SLEEP_DISABLE

__HAL_RCC_GPIOD_CLK_SLEEP_DISABLE

__HAL_RCC_GPIOH_CLK_SLEEP_DISABLE

DOCID026682 Rev 3

HAL RCC Generic Driver

391/654

HAL RCC Generic Driver

__HAL_RCC_CRC_CLK_SLEEP_DISABLE

__HAL_RCC_FLITF_CLK_SLEEP_DISABLE

__HAL_RCC_DMA1_CLK_SLEEP_DISABLE

__HAL_RCC_TIM2_CLK_SLEEP_ENABLE

__HAL_RCC_TIM3_CLK_SLEEP_ENABLE

__HAL_RCC_TIM4_CLK_SLEEP_ENABLE

__HAL_RCC_TIM6_CLK_SLEEP_ENABLE

__HAL_RCC_TIM7_CLK_SLEEP_ENABLE

__HAL_RCC_WWDG_CLK_SLEEP_ENABLE

__HAL_RCC_SPI2_CLK_SLEEP_ENABLE

__HAL_RCC_USART2_CLK_SLEEP_ENABLE

__HAL_RCC_USART3_CLK_SLEEP_ENABLE

__HAL_RCC_I2C1_CLK_SLEEP_ENABLE

__HAL_RCC_I2C2_CLK_SLEEP_ENABLE

UM1816

Notes:

Peripheral clock gating in SLEEP mode can be used to further reduce power consumption. After wakeup from SLEEP mode, the peripheral clock is enabled again.

By default, all peripheral clocks are enabled during SLEEP mode.

__HAL_RCC_USB_CLK_SLEEP_ENABLE

__HAL_RCC_PWR_CLK_SLEEP_ENABLE

__HAL_RCC_DAC_CLK_SLEEP_ENABLE

__HAL_RCC_COMP_CLK_SLEEP_ENABLE

__HAL_RCC_TIM2_CLK_SLEEP_DISABLE

__HAL_RCC_TIM3_CLK_SLEEP_DISABLE

__HAL_RCC_TIM4_CLK_SLEEP_DISABLE

__HAL_RCC_TIM6_CLK_SLEEP_DISABLE

__HAL_RCC_TIM7_CLK_SLEEP_DISABLE

__HAL_RCC_WWDG_CLK_SLEEP_DISABLE

__HAL_RCC_SPI2_CLK_SLEEP_DISABLE

__HAL_RCC_USART2_CLK_SLEEP_DISABLE

__HAL_RCC_USART3_CLK_SLEEP_DISABLE

__HAL_RCC_I2C1_CLK_SLEEP_DISABLE

__HAL_RCC_I2C2_CLK_SLEEP_DISABLE

__HAL_RCC_USB_CLK_SLEEP_DISABLE

__HAL_RCC_PWR_CLK_SLEEP_DISABLE

392/654 DOCID026682 Rev 3

UM1816

HAL RCC Generic Driver

__HAL_RCC_DAC_CLK_SLEEP_DISABLE

__HAL_RCC_COMP_CLK_SLEEP_DISABLE

__HAL_RCC_SYSCFG_CLK_SLEEP_ENABLE Notes:

Peripheral clock gating in SLEEP mode can be used to further reduce power consumption. After wakeup from SLEEP mode, the peripheral clock is enabled again.

By default, all peripheral clocks are enabled during SLEEP mode.

__HAL_RCC_TIM9_CLK_SLEEP_ENABLE

__HAL_RCC_TIM10_CLK_SLEEP_ENABLE

__HAL_RCC_TIM11_CLK_SLEEP_ENABLE

__HAL_RCC_ADC1_CLK_SLEEP_ENABLE

__HAL_RCC_SPI1_CLK_SLEEP_ENABLE

__HAL_RCC_USART1_CLK_SLEEP_ENABLE

__HAL_RCC_SYSCFG_CLK_SLEEP_DISABLE

__HAL_RCC_TIM9_CLK_SLEEP_DISABLE

__HAL_RCC_TIM10_CLK_SLEEP_DISABLE

__HAL_RCC_TIM11_CLK_SLEEP_DISABLE

__HAL_RCC_ADC1_CLK_SLEEP_DISABLE

__HAL_RCC_SPI1_CLK_SLEEP_DISABLE

__HAL_RCC_USART1_CLK_SLEEP_DISABLE

PLL Clock Source

RCC_PLLSOURCE_HSI HSI clock selected as PLL entry clock source

RCC_PLLSOURCE_HSE HSE clock selected as PLL entry clock source

PLL Config

RCC_PLL_NONE PLL is not configured

RCC_PLL_OFF

RCC_PLL_ON

PLL deactivation

PLL activation

PLL Configuration

__HAL_RCC_PLL_ENABLE

__HAL_RCC_PLL_DISABLE

Notes:

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 is disabled by hardware when entering STOP and STANDBY modes.

Notes:

The main PLL can not be disabled if it is

DOCID026682 Rev 3 393/654

HAL RCC Generic Driver

__HAL_RCC_PLL_CONFIG

394/654

UM1816

used as system clock source

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

__PLLMUL__: specifies the multiplication factor for PLL VCO output clock This parameter can be one of the following values:

RCC_PLL_MUL3: PLLVCO = PLL clock entry x 3

RCC_PLL_MUL4: PLLVCO = PLL clock entry x 4

RCC_PLL_MUL6: PLLVCO = PLL clock entry x 6

RCC_PLL_MUL8: PLLVCO = PLL clock entry x 8

RCC_PLL_MUL12: PLLVCO = PLL clock entry x 12

RCC_PLL_MUL16: PLLVCO = PLL clock entry x 16

RCC_PLL_MUL24: PLLVCO = PLL clock entry x 24

RCC_PLL_MUL32: PLLVCO = PLL clock entry x 32

RCC_PLL_MUL48: PLLVCO = PLL clock entry x 48

__PLLDIV__: specifies the division factor for PLL VCO input clock This parameter can be one of the following values:

RCC_PLL_DIV2: PLL clock output =

PLLVCO / 2

RCC_PLL_DIV3: PLL clock output =

PLLVCO / 3

RCC_PLL_DIV4: PLL clock output =

PLLVCO / 4

Notes:

This function must be used only when the main PLL is disabled.

The PLL VCO clock frequency must not exceed 96 MHz when the product is in

Range 1, 48 MHz when the product is in

DOCID026682 Rev 3

UM1816

HAL RCC Generic Driver

Range 2 and 24 MHz when the product is in Range 3.

__HAL_RCC_GET_PLL_OSCSOURCE Description:

Get oscillator clock selected as PLL input clock.

Return value:

The: clock source used for PLL entry. The returned value can be one of the following:

RCC_PLLSOURCE_HSI: HSI oscillator clock selected as PLL input clock

RCC_PLLSOURCE_HSE: HSE oscillator clock selected as PLL input clock

PLL Division Factor

RCC_PLL_DIV2

RCC_PLL_DIV3

RCC_PLL_DIV4

PLL Multiplication Factor

RCC_PLL_MUL3

RCC_PLL_MUL4

RCC_PLL_MUL6

RCC_PLL_MUL8

RCC_PLL_MUL12

RCC_PLL_MUL16

RCC_PLL_MUL24

RCC_PLL_MUL32

RCC_PLL_MUL48

RCC Private Constants

RCC_CR_BYTE2_ADDRESS

RCC_CIR_BYTE1_ADDRESS

RCC_CIR_BYTE2_ADDRESS

CR_REG_INDEX

CSR_REG_INDEX

RCC_FLAG_MASK

RCC Private Macros

MCO1_CLK_ENABLE

MCO1_GPIO_PORT

MCO1_PIN

DOCID026682 Rev 3 395/654

HAL RCC Generic Driver

IS_RCC_PLLSOURCE

IS_RCC_OSCILLATORTYPE

IS_RCC_HSE

IS_RCC_LSE

IS_RCC_HSI

IS_RCC_CALIBRATION_VALUE

IS_RCC_MSICALIBRATION_VALUE

IS_RCC_MSI_CLOCK_RANGE

IS_RCC_LSI

IS_RCC_MSI

IS_RCC_PLL

IS_RCC_PLL_DIV

IS_RCC_PLL_MUL

UM1816

IS_RCC_CLOCKTYPE

IS_RCC_SYSCLKSOURCE

IS_RCC_HCLK

IS_RCC_PCLK

IS_RCC_MCO

IS_RCC_MCODIV

IS_RCC_MCO1SOURCE

IS_RCC_RTCCLKSOURCE

Register offsets

RCC_OFFSET

RCC_CR_OFFSET

RCC_CFGR_OFFSET

RCC_CIR_OFFSET

RCC_CSR_OFFSET

RCC RTC Clock Configuration

__HAL_RCC_RTC_CLKPRESCALER

Description:

Macro to configures the RTC clock

(RTCCLK).

Parameters:

__RTC_CLKSOURCE__: specifies the RTC clock source. This parameter can be one of the following values:

RCC_RTCCLKSOURCE_NO_CLK: No clock selected as RTC clock

RCC_RTCCLKSOURCE_LSE: LSE selected as RTC clock

396/654 DOCID026682 Rev 3

UM1816

__HAL_RCC_RTC_CONFIG

__HAL_RCC_GET_RTC_SOURCE

HAL RCC Generic Driver

RCC_RTCCLKSOURCE_LSI: LSI selected as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV2:

HSE divided by 2 selected as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV4:

HSE divided by 4 selected as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV8:

HSE divided by 8 selected as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV16:

HSE divided by 16 selected as RTC clock

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_FORCE() macro, or by a Power On Reset (POR).

RTC prescaler cannot be modified if HSE is enabled (HSEON = 1).

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 wakeup 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).

Description:

 macros to get the RTC clock source.

Return value:

The: clock source can be one of the following values:

RCC_RTCCLKSOURCE_NO_CLK: No clock selected as RTC clock

RCC_RTCCLKSOURCE_LSE: LSE selected as RTC clock

RCC_RTCCLKSOURCE_LSI: LSI selected as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV2:

HSE divided by 2 selected as RTC

DOCID026682 Rev 3 397/654

HAL RCC Generic Driver

__HAL_RCC_RTC_ENABLE

__HAL_RCC_RTC_DISABLE

__HAL_RCC_BACKUPRESET_FORC

E

UM1816

clock

RCC_RTCCLKSOURCE_HSE_DIV4:

HSE divided by 4 selected as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV8:

HSE divided by 8 selected as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV16:

HSE divided by 16 selected as RTC clock

Notes:

These macros must be used only after the

RTC clock source was selected.

Notes:

These macros must be used only after the

RTC clock source was selected.

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_RELE

ASE

RTC LCD Clock Source

RCC_RTCCLKSOURCE_NO_CLK

RCC_RTCCLKSOURCE_LSE

RCC_RTCCLKSOURCE_LSI

No clock

LSE oscillator clock used as RTC clock

LSI oscillator clock used as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV2 HSE oscillator clock divided by 2 used as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV4 HSE oscillator clock divided by 4 used as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV8 HSE oscillator clock divided by 8 used as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV16 HSE oscillator clock divided by 16 used as RTC clock

System Clock Source

RCC_SYSCLKSOURCE_MSI

RCC_SYSCLKSOURCE_HSI

RCC_SYSCLKSOURCE_HSE

MSI selected as system clock

HSI selected as system clock

HSE selected as system clock

RCC_SYSCLKSOURCE_PLLCLK PLL selected as system clock

System Clock Source Status

RCC_SYSCLKSOURCE_STATUS_MSI

398/654 DOCID026682 Rev 3

UM1816

RCC_SYSCLKSOURCE_STATUS_HSI

RCC_SYSCLKSOURCE_STATUS_HSE

RCC_SYSCLKSOURCE_STATUS_PLLCLK

System Clock Type

RCC_CLOCKTYPE_SYSCLK SYSCLK to configure

RCC_CLOCKTYPE_HCLK HCLK to configure

RCC_CLOCKTYPE_PCLK1 PCLK1 to configure

RCC_CLOCKTYPE_PCLK2 PCLK2 to configure

RCC Timeout

RCC_DBP_TIMEOUT_VALUE

RCC_LSE_TIMEOUT_VALUE

CLOCKSWITCH_TIMEOUT_VALUE

HSE_TIMEOUT_VALUE

MSI_TIMEOUT_VALUE

HSI_TIMEOUT_VALUE

LSI_TIMEOUT_VALUE

PLL_TIMEOUT_VALUE

HAL RCC Generic Driver

DOCID026682 Rev 3 399/654

HAL RCC Extension Driver

UM1816

34 HAL RCC Extension Driver

34.1 HAL RCC Extension Driver

34.2 RCCEx Firmware driver registers structures

34.2.1 RCC_PeriphCLKInitTypeDef

Data Fields

uint32_t PeriphClockSelection

uint32_t RTCClockSelection

uint32_t LCDClockSelection

Field Documentation

uint32_t RCC_PeriphCLKInitTypeDef::PeriphClockSelection

The Extended Clock to be configured. This parameter can be a value of

RCCEx_Periph_Clock_Selection

uint32_t RCC_PeriphCLKInitTypeDef::RTCClockSelection

specifies the RTC clock source. This parameter can be a value of

RCC_RTC_LCD_Clock_Source

uint32_t RCC_PeriphCLKInitTypeDef::LCDClockSelection

specifies the LCD clock source. This parameter can be a value of

RCC_RTC_LCD_Clock_Source

34.3 RCCEx Firmware driver API description

34.3.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_RCCEx_PeriphCLKConfig()

HAL_RCCEx_GetPeriphCLKConfig()

HAL_RCCEx_GetPeriphCLKFreq()

HAL_RCCEx_EnableLSECSS()

HAL_RCCEx_DisableLSECSS()

34.3.2 HAL_RCCEx_PeriphCLKConfig

400/654 DOCID026682 Rev 3

UM1816

Function Name

HAL RCC Extension Driver

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

Return values

PeriphClkInit: pointer to an RCC_PeriphCLKInitTypeDef structure that contains the configuration information for the

Extended Peripherals clocks(RTC/LCD clock).

HAL status

34.3.3 HAL_RCCEx_GetPeriphCLKConfig

Function Name

void HAL_RCCEx_GetPeriphCLKConfig

(RCC_PeriphCLKInitTypeDef * PeriphClkInit)

Function Description Get the PeriphClkInit according to the internal RCC configuration registers.

Parameters

Return values

PeriphClkInit: pointer to an RCC_PeriphCLKInitTypeDef structure that returns the configuration information for the

Extended Peripherals clocks(RTC/LCD clocks).

None

34.3.4 HAL_RCCEx_GetPeriphCLKFreq

Function Name uint32_t HAL_RCCEx_GetPeriphCLKFreq (uint32_t PeriphClk)

Function Description Returns the peripheral clock frequency.

Parameters

PeriphClk: Peripheral clock identifier This parameter can be one of the following values: RCC_PERIPHCLK_RTC: RTC peripheral clockRCC_PERIPHCLK_LCD: LCD peripheral clock (depends on devices)

Return values

Notes

Frequency in Hz (0: means that no available frequency for the peripheral)

Returns 0 if peripheral clock is unknown

34.3.5 HAL_RCCEx_EnableLSECSS

Function Name void HAL_RCCEx_EnableLSECSS (void )

Function Description Enables the LSE Clock Security System.

Return values

None

Notes

If a failure is detected on the external 32 kHz oscillator, the

LSE clock is no longer supplied to the RTC but no hardware action is made to the registers. In Standby mode a wakeup is generated. In other modes an interrupt can be sent to wakeup the software (see Section 5.3.4: Clock interrupt register

(RCC_CIR) on page 104). The software MUST then disable the LSECSSON bit, stop the defective 32 kHz oscillator

(disabling LSEON), and can change the RTC clock source

(no clock or LSI or HSE, with RTCSEL), or take any required action to secure the application.

LSE CSS available only for high density and medium+

DOCID026682 Rev 3 401/654

HAL RCC Extension Driver

UM1816

devices

34.3.6 HAL_RCCEx_DisableLSECSS

Function Name void HAL_RCCEx_DisableLSECSS (void )

Function Description Disables the LSE Clock Security System.

Return values

None

Notes

Once enabled this bit cannot be disabled, except after an LSE failure detection (LSECSSD=1). In that case the software

MUST disable the LSECSSON bit. Reset by power on reset and RTC software reset (RTCRST bit).

LSE CSS available only for high density and medium+ devices

34.4 RCCEx Firmware driver defines

34.4.1 RCCEx

RCCEx Force Release Peripheral Reset

__HAL_RCC_GPIOE_FORCE_RESET

__HAL_RCC_GPIOE_RELEASE_RESET

__HAL_RCC_GPIOF_FORCE_RESET

__HAL_RCC_GPIOG_FORCE_RESET

__HAL_RCC_GPIOF_RELEASE_RESET

__HAL_RCC_GPIOG_RELEASE_RESET

__HAL_RCC_DMA2_FORCE_RESET

__HAL_RCC_DMA2_RELEASE_RESET

__HAL_RCC_CRYP_FORCE_RESET

__HAL_RCC_CRYP_RELEASE_RESET

__HAL_RCC_FSMC_FORCE_RESET

__HAL_RCC_FSMC_RELEASE_RESET

__HAL_RCC_LCD_FORCE_RESET

__HAL_RCC_LCD_RELEASE_RESET

__HAL_RCC_TIM5_FORCE_RESET

__HAL_RCC_TIM5_RELEASE_RESET

__HAL_RCC_SPI3_FORCE_RESET

__HAL_RCC_SPI3_RELEASE_RESET

__HAL_RCC_UART4_FORCE_RESET

__HAL_RCC_UART5_FORCE_RESET

__HAL_RCC_UART4_RELEASE_RESET

__HAL_RCC_UART5_RELEASE_RESET

402/654 DOCID026682 Rev 3

UM1816

HAL RCC Extension Driver

__HAL_RCC_OPAMP_FORCE_RESET

__HAL_RCC_OPAMP_RELEASE_RESET

__HAL_RCC_SDIO_FORCE_RESET

__HAL_RCC_SDIO_RELEASE_RESET

LCd Configuration

__HAL_RCC_LCD_CONFIG

Description:

Macro to configures LCD clock (LCDCLK).

Parameters:

__LCD_CLKSOURCE__: specifies the LCD 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_DIV2: HSE divided by 2 selected as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV4: HSE divided by 4 selected as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV8: HSE divided by 8 selected as RTC clock

RCC_RTCCLKSOURCE_HSE_DIV16:

HSE divided by 16 selected as RTC clock

Notes:

LCD and RTC use the same configuration LCD can however be used in the Stop low power mode if the LSE or LSI is used as the LCD clock source.

__HAL_RCC_GET_LCD_SOURC

E

RCCEx_Peripheral_Clock_Enable_Disable

__HAL_RCC_GPIOE_CLK_ENABLE

__HAL_RCC_GPIOE_CLK_DISABLE

__HAL_RCC_GPIOF_CLK_ENABLE

__HAL_RCC_GPIOG_CLK_ENABLE

__HAL_RCC_GPIOF_CLK_DISABLE

__HAL_RCC_GPIOG_CLK_DISABLE

__HAL_RCC_DMA2_CLK_ENABLE

__HAL_RCC_DMA2_CLK_DISABLE

__HAL_RCC_CRYP_CLK_ENABLE

__HAL_RCC_CRYP_CLK_DISABLE

__HAL_RCC_FSMC_CLK_ENABLE

DOCID026682 Rev 3 403/654

HAL RCC Extension Driver

__HAL_RCC_FSMC_CLK_DISABLE

__HAL_RCC_LCD_CLK_ENABLE

__HAL_RCC_LCD_CLK_DISABLE

__HAL_RCC_TIM5_CLK_ENABLE

__HAL_RCC_TIM5_CLK_DISABLE

UM1816

Notes:

After reset, the peripheral clock (used for registers read/write access) is disabled and the application software has to enable this clock before using it.

__HAL_RCC_SPI3_CLK_ENABLE

__HAL_RCC_SPI3_CLK_DISABLE

__HAL_RCC_UART4_CLK_ENABLE

__HAL_RCC_UART5_CLK_ENABLE

__HAL_RCC_UART4_CLK_DISABLE

__HAL_RCC_UART5_CLK_DISABLE

__HAL_RCC_OPAMP_CLK_ENABLE

__HAL_RCC_OPAMP_CLK_DISABLE

__HAL_RCC_SDIO_CLK_ENABLE

Notes:

After reset, the peripheral clock (used for registers read/write access) is disabled and the application software has to enable this clock before using it.

__HAL_RCC_SDIO_CLK_DISABLE

Peripheral Clock Enable Disable Status

__HAL_RCC_GPIOE_IS_CLK_ENABLED

__HAL_RCC_GPIOE_IS_CLK_DISABLED

__HAL_RCC_GPIOF_IS_CLK_ENABLED

__HAL_RCC_GPIOG_IS_CLK_ENABLED

__HAL_RCC_GPIOF_IS_CLK_DISABLED

__HAL_RCC_GPIOG_IS_CLK_DISABLED

__HAL_RCC_DMA2_IS_CLK_ENABLED

__HAL_RCC_DMA2_IS_CLK_DISABLED

__HAL_RCC_CRYP_IS_CLK_ENABLED

__HAL_RCC_CRYP_IS_CLK_DISABLED

__HAL_RCC_FSMC_IS_CLK_ENABLED

__HAL_RCC_FSMC_IS_CLK_DISABLED

__HAL_RCC_LCD_IS_CLK_ENABLED

__HAL_RCC_LCD_IS_CLK_DISABLED

404/654 DOCID026682 Rev 3

UM1816

HAL RCC Extension Driver

__HAL_RCC_TIM5_IS_CLK_ENABLED

__HAL_RCC_TIM5_IS_CLK_DISABLED

__HAL_RCC_SPI3_IS_CLK_ENABLED

__HAL_RCC_SPI3_IS_CLK_DISABLED

__HAL_RCC_UART4_IS_CLK_ENABLED

__HAL_RCC_UART5_IS_CLK_ENABLED

__HAL_RCC_UART4_IS_CLK_DISABLED

__HAL_RCC_UART5_IS_CLK_DISABLED

__HAL_RCC_OPAMP_IS_CLK_ENABLED

__HAL_RCC_OPAMP_IS_CLK_DISABLED

__HAL_RCC_SDIO_IS_CLK_ENABLED

__HAL_RCC_SDIO_IS_CLK_DISABLED

RCCEx Peripheral Clock Sleep Enable Disable

__HAL_RCC_GPIOE_CLK_SLEEP_ENABLE

__HAL_RCC_GPIOE_CLK_SLEEP_DISABLE

__HAL_RCC_GPIOF_CLK_SLEEP_ENABLE

__HAL_RCC_GPIOG_CLK_SLEEP_ENABLE

__HAL_RCC_GPIOF_CLK_SLEEP_DISABLE

__HAL_RCC_GPIOG_CLK_SLEEP_DISABLE

__HAL_RCC_DMA2_CLK_SLEEP_ENABLE

__HAL_RCC_DMA2_CLK_SLEEP_DISABLE

__HAL_RCC_CRYP_CLK_SLEEP_ENABLE

__HAL_RCC_CRYP_CLK_SLEEP_DISABLE

__HAL_RCC_FSMC_CLK_SLEEP_ENABLE

__HAL_RCC_FSMC_CLK_SLEEP_DISABLE

__HAL_RCC_LCD_CLK_SLEEP_ENABLE

__HAL_RCC_LCD_CLK_SLEEP_DISABLE

__HAL_RCC_TIM5_CLK_SLEEP_ENABLE Notes:

Peripheral clock gating in SLEEP mode can be used to further reduce power consumption. After wakeup from SLEEP mode, the peripheral clock is enabled again. By default, all peripheral clocks are enabled during SLEEP mode.

__HAL_RCC_TIM5_CLK_SLEEP_DISABLE

__HAL_RCC_SPI3_CLK_SLEEP_ENABLE

__HAL_RCC_SPI3_CLK_SLEEP_DISABLE

DOCID026682 Rev 3 405/654

HAL RCC Extension Driver

__HAL_RCC_UART4_CLK_SLEEP_ENABLE

__HAL_RCC_UART5_CLK_SLEEP_ENABLE

__HAL_RCC_UART4_CLK_SLEEP_DISABLE

__HAL_RCC_UART5_CLK_SLEEP_DISABLE

__HAL_RCC_OPAMP_CLK_SLEEP_ENABLE

UM1816

__HAL_RCC_OPAMP_CLK_SLEEP_DISABLE

__HAL_RCC_SDIO_CLK_SLEEP_ENABLE Notes:

Peripheral clock gating in SLEEP mode can be used to further reduce power consumption. After wakeup from SLEEP mode, the peripheral clock is enabled again. By default, all peripheral clocks are enabled during SLEEP mode.

__HAL_RCC_SDIO_CLK_SLEEP_DISABLE

Peripheral Clock Sleep Enable Disable Status

__HAL_RCC_GPIOE_IS_CLK_SLEEP_ENABLED

__HAL_RCC_GPIOE_IS_CLK_SLEEP_DISABLED

__HAL_RCC_GPIOF_IS_CLK_SLEEP_ENABLED

__HAL_RCC_GPIOG_IS_CLK_SLEEP_ENABLED

__HAL_RCC_GPIOF_IS_CLK_SLEEP_DISABLED

__HAL_RCC_GPIOG_IS_CLK_SLEEP_DISABLED

__HAL_RCC_DMA2_IS_CLK_SLEEP_ENABLED

__HAL_RCC_DMA2_IS_CLK_SLEEP_DISABLED

__HAL_RCC_CRYP_IS_CLK_SLEEP_ENABLED

__HAL_RCC_CRYP_IS_CLK_SLEEP_DISABLED

__HAL_RCC_FSMC_IS_CLK_SLEEP_ENABLED

__HAL_RCC_FSMC_IS_CLK_SLEEP_DISABLED

__HAL_RCC_LCD_IS_CLK_SLEEP_ENABLED

__HAL_RCC_LCD_IS_CLK_SLEEP_DISABLED

__HAL_RCC_TIM5_IS_CLK_SLEEP_ENABLED

__HAL_RCC_TIM5_IS_CLK_SLEEP_DISABLED

__HAL_RCC_SPI3_IS_CLK_SLEEP_ENABLED

__HAL_RCC_SPI3_IS_CLK_SLEEP_DISABLED

__HAL_RCC_UART4_IS_CLK_SLEEP_ENABLED

__HAL_RCC_UART5_IS_CLK_SLEEP_ENABLED

__HAL_RCC_UART4_IS_CLK_SLEEP_DISABLED

__HAL_RCC_UART5_IS_CLK_SLEEP_DISABLED

406/654 DOCID026682 Rev 3

UM1816

__HAL_RCC_OPAMP_IS_CLK_SLEEP_ENABLED

__HAL_RCC_OPAMP_IS_CLK_SLEEP_DISABLED

__HAL_RCC_SDIO_IS_CLK_SLEEP_ENABLED

__HAL_RCC_SDIO_IS_CLK_SLEEP_DISABLED

RCCEx Periph Clock Selection

RCC_PERIPHCLK_RTC

RCC_PERIPHCLK_LCD

RCCEx Private Constants

LSI_VALUE

LSECSSON_BITNUMBER

CSR_LSECSSON_BB

RCCEx Private Macros

IS_RCC_PERIPHCLOCK

HAL RCC Extension Driver

DOCID026682 Rev 3 407/654

HAL RTC Generic Driver

UM1816

35 HAL RTC Generic Driver

35.1 HAL RTC Generic Driver

35.2 RTC Firmware driver registers structures

35.2.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 = 0x7FFF

uint32_t RTC_InitTypeDef::OutPut

Specifies which signal will be routed to the RTC output. This parameter can be a

value of

RTCEx_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

35.2.2 RTC_DateTypeDef

Data Fields

uint8_t WeekDay

uint8_t Month

uint8_t Date

uint8_t Year

408/654 DOCID026682 Rev 3

UM1816

HAL RTC Generic Driver

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

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

35.2.3 RTC_HandleTypeDef

Data Fields

RTC_TypeDef * Instance

RTC_InitTypeDef Init

HAL_LockTypeDef Lock

__IO HAL_RTCStateTypeDef State

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

35.3 RTC Firmware driver API description

35.3.1 Backup Domain Operating Condition

The real-time clock (RTC) and the RTC backup registers can be powered from the VBAT voltage when the main VDD supply is powered off. To retain the content of the RTC backup registers 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. The RTC

2. The LSE oscillator

3. PC13 to PC15 I/Os (when available)

DOCID026682 Rev 3 409/654

HAL RTC Generic Driver

UM1816

When the backup domain is supplied by VDD (analog switch connected to VDD), the following pins are available:

1. PC14 and PC15 can be used as either GPIO or LSE pins

2. PC13 can be used as a GPIO or as the RTC_AF1 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. PC14 and PC15 can be used as LSE pins only

2. PC13 can be used as the RTC_AF1 pin

35.3.2 Backup Domain Reset

The backup domain reset sets all RTC registers and the RCC_BDCR register to their reset values.

A backup domain reset is generated when one of the following events occurs:

1. Software reset, triggered by setting the BDRST bit in the RCC Backup domain control register (RCC_BDCR).

2. VDD or VBAT power on, if both supplies have previously been powered off.

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

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

410/654 DOCID026682 Rev 3

UM1816

35.3.5 RTC and low power modes

HAL RTC Generic Driver

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 wakeup,

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-wakeup mode), by using the RTC alarm or the RTC wakeup events.

The RTC provides a programmable time base for waking up from the Stop or Standby mode at regular intervals. Wakeup from STOP and STANDBY modes is possible only when the RTC clock source is LSE or LSI.

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

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 wakeup 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()

HAL_RTC_SetTime()

HAL_RTC_GetTime()

HAL_RTC_SetDate()

HAL_RTC_GetDate()

35.3.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_SetDate()

HAL_RTC_GetDate()

DOCID026682 Rev 3 411/654

HAL RTC Generic Driver

HAL_RTC_GetTime()

HAL_RTC_SetAlarm()

HAL_RTC_SetAlarm_IT()

HAL_RTC_DeactivateAlarm()

HAL_RTC_GetAlarm()

HAL_RTC_AlarmIRQHandler()

HAL_RTC_PollForAlarmAEvent()

HAL_RTC_AlarmAEventCallback()

35.3.8 RTC Alarm functions

This section provides functions allowing to configure Alarm feature

This section contains the following APIs:

HAL_RTC_DeactivateAlarm()

HAL_RTC_AlarmIRQHandler()

HAL_RTC_AlarmAEventCallback()

HAL_RTC_PollForAlarmAEvent()

HAL_RTC_SetAlarm()

HAL_RTC_SetAlarm_IT()

HAL_RTC_GetAlarm()

HAL_RTC_WaitForSynchro()

35.3.9 Peripheral State functions

This subsection provides functions allowing to

Get RTC state

This section contains the following APIs:

HAL_RTC_GetState()

UM1816

35.3.10 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()

35.3.11 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

35.3.12 HAL_RTC_DeInit

Function Name

HAL_StatusTypeDef HAL_RTC_DeInit (RTC_HandleTypeDef *

hrtc)

412/654 DOCID026682 Rev 3

UM1816

HAL RTC Generic Driver

Function Description DeInitializes the RTC peripheral.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC.

hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC.

Return values

Notes

HAL status

HAL status

This function doesn't reset the RTC Backup Data registers.

This function does not reset the RTC Backup Data registers.

35.3.13 HAL_RTC_MspInit

Function Name void HAL_RTC_MspInit (RTC_HandleTypeDef * hrtc)

Function Description Initializes the RTC MSP.

Parameters

Return values

hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC.

None

35.3.14 HAL_RTC_MspDeInit

Function Name void HAL_RTC_MspDeInit (RTC_HandleTypeDef * hrtc)

Function Description DeInitializes the RTC MSP.

Parameters

Return values

hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC.

None

35.3.15 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

Return values

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 formatRTC_FORMAT_BCD: BCD data format

HAL status

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

DOCID026682 Rev 3 413/654

HAL RTC Generic Driver

Return values

Notes

UM1816

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 formatRTC_FORMAT_BCD: BCD data format

HAL status

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.

35.3.17 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

Return values

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 formatRTC_FORMAT_BCD: BCD data format

HAL status

35.3.18 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 formatRTC_FORMAT_BCD: BCD data format

Return values

Notes

HAL status

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.

35.3.19 HAL_RTC_SetTime

Function Name

HAL_StatusTypeDef HAL_RTC_SetTime (RTC_HandleTypeDef

* hrtc, RTC_TimeTypeDef * sTime, uint32_t Format)

414/654 DOCID026682 Rev 3

UM1816

HAL RTC Generic Driver

Function Description Sets RTC current time.

Parameters

Return values

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 formatRTC_FORMAT_BCD: BCD data format

HAL status

35.3.20 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

Return values

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 formatRTC_FORMAT_BCD: BCD data format

HAL status

35.3.21 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 formatRTC_FORMAT_BCD: BCD data format

Return values

Notes

HAL status

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.

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

DOCID026682 Rev 3 415/654

HAL RTC Generic Driver

Parameters

Return values

Notes

hrtc: pointer to a RTC_HandleTypeDef structure that

UM1816

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 formatRTC_FORMAT_BCD: BCD data format

HAL status

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.

35.3.23 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

Return values

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 formatRTC_FORMAT_BCD: BCD data format

HAL status

35.3.24 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:

RTC_FORMAT_BIN: Binary data formatRTC_FORMAT_BCD: BCD data format

Return values

Notes

HAL status

The Alarm register can only be written when the corresponding Alarm is disabled (Use the

HAL_RTC_DeactivateAlarm()).

The HAL_RTC_SetTime() must be called before enabling the

Alarm feature.

416/654 DOCID026682 Rev 3

UM1816

35.3.25 HAL_RTC_DeactivateAlarm

Function Name

HAL RTC Generic Driver

HAL_StatusTypeDef HAL_RTC_DeactivateAlarm

(RTC_HandleTypeDef * hrtc, uint32_t Alarm)

Function Description Deactive 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:

AlarmARTC_ALARM_B: AlarmB

Return values

HAL status

35.3.26 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

Return values

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:

AlarmARTC_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 formatRTC_FORMAT_BCD: BCD data format

HAL status

35.3.27 HAL_RTC_AlarmIRQHandler

Function Name

void HAL_RTC_AlarmIRQHandler (RTC_HandleTypeDef * hrtc)

Function Description This function handles Alarm interrupt request.

Parameters

Return values

hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC.

None

35.3.28 HAL_RTC_PollForAlarmAEvent

Function Name

HAL_StatusTypeDef HAL_RTC_PollForAlarmAEvent

(RTC_HandleTypeDef * hrtc, uint32_t Timeout)

Function Description This function handles AlarmA Polling request.

Parameters

Return values

hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC.

Timeout: Timeout duration

HAL status

DOCID026682 Rev 3 417/654

HAL RTC Generic Driver

35.3.29 HAL_RTC_AlarmAEventCallback

Function Name

UM1816 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

35.3.30 HAL_RTC_DeactivateAlarm

Function Name

HAL_StatusTypeDef HAL_RTC_DeactivateAlarm

(RTC_HandleTypeDef * hrtc, uint32_t Alarm)

Function Description Deactive the specified RTC Alarm.

Parameters

Return values

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:

AlarmARTC_ALARM_B: AlarmB

HAL status

35.3.31 HAL_RTC_AlarmIRQHandler

Function Name void HAL_RTC_AlarmIRQHandler (RTC_HandleTypeDef * hrtc)

Function Description This function handles Alarm interrupt request.

Parameters

Return values

hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC.

None

35.3.32 HAL_RTC_AlarmAEventCallback

Function Name

void HAL_RTC_AlarmAEventCallback (RTC_HandleTypeDef *

hrtc)

Function Description Alarm A callback.

Parameters

Return values

hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC.

None

35.3.33 HAL_RTC_PollForAlarmAEvent

Function Name

HAL_StatusTypeDef HAL_RTC_PollForAlarmAEvent

(RTC_HandleTypeDef * hrtc, uint32_t Timeout)

Function Description This function handles AlarmA Polling request.

Parameters

hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC.

Timeout: Timeout duration

418/654 DOCID026682 Rev 3

UM1816

Return values

HAL status

HAL RTC Generic Driver

35.3.34 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

Return values

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 formatRTC_FORMAT_BCD: BCD data format

HAL status

35.3.35 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:

RTC_FORMAT_BIN: Binary data formatRTC_FORMAT_BCD: BCD data format

Return values

Notes

HAL status

The Alarm register can only be written when the corresponding Alarm is disabled (Use the

HAL_RTC_DeactivateAlarm()).

The HAL_RTC_SetTime() must be called before enabling the

Alarm feature.

35.3.36 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:

AlarmARTC_ALARM_B: AlarmB

Format: Specifies the format of the entered parameters. This

DOCID026682 Rev 3 419/654

HAL RTC Generic Driver

UM1816

Return values parameter can be one of the following values:

RTC_FORMAT_BIN: Binary data formatRTC_FORMAT_BCD: BCD data format

HAL status

35.3.37 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

Notes

HAL status

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

35.3.38 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

35.3.39 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

Return values

hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC.

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 wakeup from

420/654 DOCID026682 Rev 3

UM1816

HAL RTC Generic Driver 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.

35.4 RTC Firmware driver defines

35.4.1 RTC

AlarmDateWeekDay Definitions

RTC_ALARMDATEWEEKDAYSEL_DATE

RTC_ALARMDATEWEEKDAYSEL_WEEKDAY

IS_RTC_ALARM_DATE_WEEKDAY_SEL

Alarm Mask Definitions

RTC_ALARMMASK_NONE

RTC_ALARMMASK_DATEWEEKDAY

RTC_ALARMMASK_HOURS

RTC_ALARMMASK_MINUTES

RTC_ALARMMASK_ALL

IS_RTC_ALARM_MASK

Alarms Definitions

RTC_ALARM_A

RTC_ALARM_B

IS_RTC_ALARM

RTC_ALARMMASK_SECONDS

Alarm Definitions

IS_RTC_ALARM_DATE_WEEKDAY_DATE

IS_RTC_ALARM_DATE_WEEKDAY_WEEKDAY

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

DOCID026682 Rev 3 421/654

HAL RTC Generic Driver

UM1816

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

RTC_ALARMSUBSECONDMASK_NONE

SS[14] is don't care in Alarm comparison.Only SS[13:0] are compared

SS[14:0] are compared and must match to activate alarm.

IS_RTC_ALARM_SUB_SECOND_MASK

Alarm Sub Seconds Value

IS_RTC_ALARM_SUB_SECOND_VALUE

AM PM Definitions

RTC_HOURFORMAT12_AM

RTC_HOURFORMAT12_PM

IS_RTC_HOURFORMAT12

Asynchronous Predivider

IS_RTC_ASYNCH_PREDIV

DayLightSaving

RTC_DAYLIGHTSAVING_SUB1H

RTC_DAYLIGHTSAVING_ADD1H

RTC_DAYLIGHTSAVING_NONE

IS_RTC_DAYLIGHT_SAVING

RTC Exported Macros

__HAL_RTC_RESET_HANDLE_STATE

Description:

Reset RTC handle state.

Parameters:

__HANDLE__: RTC

422/654 DOCID026682 Rev 3

UM1816

__HAL_RTC_WRITEPROTECTION_DISABLE

__HAL_RTC_WRITEPROTECTION_ENABLE

__HAL_RTC_ALARMA_ENABLE

__HAL_RTC_ALARMB_ENABLE

__HAL_RTC_ALARMA_DISABLE

DOCID026682 Rev 3

HAL RTC Generic Driver handle.

Return value:

None

Description:

Disable the write protection for RTC registers.

Parameters:

__HANDLE__: specifies the RTC handle.

Return value:

None

Description:

Enable the write protection for RTC registers.

Parameters:

__HANDLE__: specifies the RTC handle.

Return value:

None

Description:

Enable the RTC ALARMA peripheral.

Parameters:

__HANDLE__: specifies the RTC handle.

Return value:

None

Description:

Disable the RTC ALARMA peripheral.

Parameters:

__HANDLE__: specifies the RTC handle.

Return value:

None

Description:

Enable the RTC ALARMB peripheral.

423/654

HAL RTC Generic Driver

424/654

__HAL_RTC_ALARMB_DISABLE

__HAL_RTC_ALARM_ENABLE_IT

__HAL_RTC_ALARM_DISABLE_IT

DOCID026682 Rev 3

UM1816

Parameters:

__HANDLE__: specifies the RTC handle.

Return value:

None

Description:

Disable the RTC ALARMB peripheral.

Parameters:

__HANDLE__: specifies the RTC handle.

Return value:

None

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

Description:

Disable 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:

UM1816

__HAL_RTC_ALARM_GET_IT

__HAL_RTC_ALARM_GET_FLAG

__HAL_RTC_ALARM_CLEAR_FLAG

DOCID026682 Rev 3

HAL RTC Generic Driver

RTC_IT_ALRA:

Alarm A interrupt

RTC_IT_ALRB:

Alarm B interrupt

Return value:

None

Description:

Check whether the specified RTC Alarm interrupt has occurred 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

Description:

Get the selected RTC

Alarm's flag status.

Parameters:

__HANDLE__: specifies the RTC handle.

__FLAG__: specifies the

RTC Alarm Flag sources to check. This parameter can be:

RTC_FLAG_ALRAF

RTC_FLAG_ALRBF

RTC_FLAG_ALRAW

F

RTC_FLAG_ALRBW

F

Return value:

None

Description:

Clear the RTC Alarm's pending flags.

425/654

HAL RTC Generic Driver

426/654

__HAL_RTC_ALARM_GET_IT_SOURCE

__HAL_RTC_ALARM_EXTI_ENABLE_IT

__HAL_RTC_ALARM_EXTI_DISABLE_IT

__HAL_RTC_ALARM_EXTI_ENABLE_EVENT

DOCID026682 Rev 3

UM1816

Parameters:

__HANDLE__: specifies the RTC handle.

__FLAG__: specifies the

RTC Alarm Flag sources to clear. This parameter can be:

RTC_FLAG_ALRAF

RTC_FLAG_ALRBF

Return value:

None

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

Description:

Enable interrupt on the

RTC Alarm associated Exti line.

Return value:

None

Description:

Disable interrupt on the

RTC Alarm associated Exti line.

Return value:

None

Description:

Enable event on the RTC

Alarm associated Exti line.

UM1816

__HAL_RTC_ALARM_EXTI_DISABLE_EVENT

HAL RTC Generic Driver

Return value:

None.

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.

__HAL_RTC_ALARM_EXTI_ENABLE_RISING_FALLIN

G_EDGE

__HAL_RTC_ALARM_EXTI_DISABLE_RISING_FALLIN

G_EDGE

Return value:

None.

Description:

Enable rising & falling edge trigger on the RTC

Alarm associated Exti line.

Return value:

None.

Description:

Disable rising & falling edge trigger on the RTC

DOCID026682 Rev 3 427/654

HAL RTC Generic Driver

__HAL_RTC_ALARM_EXTI_GET_FLAG

__HAL_RTC_ALARM_EXTI_CLEAR_FLAG

__HAL_RTC_ALARM_EXTI_GENERATE_SWIT

UM1816

Alarm associated Exti line.

Return value:

None.

Description:

Check whether the RTC

Alarm associated Exti line interrupt flag is set or not.

Return value:

Line: Status.

Description:

Clear the RTC Alarm associated Exti line flag.

Return value:

None.

Description:

Generate a Software interrupt on RTC Alarm associated Exti line.

Return value:

None.

428/654

Flags Definitions

RTC_FLAG_RECALPF

RTC_FLAG_TAMP3F

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

RTC_FLAG_WUTWF

RTC_FLAG_ALRBWF

RTC_FLAG_ALRAWF

Hour Formats

DOCID026682 Rev 3

UM1816

RTC_HOURFORMAT_24

RTC_HOURFORMAT_12

IS_RTC_HOUR_FORMAT

Input Parameter Format

RTC_FORMAT_BIN

RTC_FORMAT_BCD

IS_RTC_FORMAT

Interrupts Definitions

RTC_IT_TS

RTC_IT_WUT

RTC_IT_ALRB

RTC_IT_ALRA

RTC_IT_TAMP1

RTC_IT_TAMP2

RTC_IT_TAMP3

Masks Definitions

RTC_TR_RESERVED_MASK

RTC_DR_RESERVED_MASK

RTC_INIT_MASK

RTC_RSF_MASK

RTC_FLAGS_MASK

Month 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

IS_RTC_MONTH

IS_RTC_DATE

Outpout Polarity

DOCID026682 Rev 3

HAL RTC Generic Driver

429/654

HAL RTC Generic Driver

RTC_OUTPUT_POLARITY_HIGH

RTC_OUTPUT_POLARITY_LOW

IS_RTC_OUTPUT_POL

Alarm Output Type

RTC_OUTPUT_TYPE_OPENDRAIN

UM1816

RTC_OUTPUT_TYPE_PUSHPULL

IS_RTC_OUTPUT_TYPE

RTC Private Constants

RTC_EXTI_LINE_ALARM_EVENT External interrupt line 17 Connected to the RTC

Alarm event

StoreOperation

RTC_STOREOPERATION_RESET

RTC_STOREOPERATION_SET

IS_RTC_STORE_OPERATION

Synchronous Predivider

IS_RTC_SYNCH_PREDIV

Default Timeout Value

RTC_TIMEOUT_VALUE

Time Definitions

IS_RTC_HOUR12

IS_RTC_HOUR24

IS_RTC_MINUTES

IS_RTC_SECONDS

WeekDay Definitions

RTC_WEEKDAY_MONDAY

RTC_WEEKDAY_TUESDAY

RTC_WEEKDAY_WEDNESDAY

RTC_WEEKDAY_THURSDAY

RTC_WEEKDAY_FRIDAY

RTC_WEEKDAY_SATURDAY

RTC_WEEKDAY_SUNDAY

IS_RTC_WEEKDAY

Year Definitions

IS_RTC_YEAR

430/654 DOCID026682 Rev 3

UM1816

HAL RTC Extension Driver

36 HAL RTC Extension Driver

36.1 HAL RTC Extension Driver

36.2 RTCEx Firmware driver registers structures

36.2.1 RTC_TamperTypeDef

Data Fields

uint32_t Tamper

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::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

36.2.2 RTC_TimeTypeDef

Data Fields

uint8_t Hours

uint8_t Minutes

DOCID026682 Rev 3 431/654

HAL RTC Extension Driver

uint8_t Seconds

uint32_t SubSeconds

uint8_t TimeFormat

uint32_t DayLightSaving

uint32_t StoreOperation

UM1816

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

uint32_t RTC_TimeTypeDef::SubSeconds

Specifies the RTC Time SubSeconds. 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::DayLightSaving

Specifies RTC_DayLightSaveOperation: the value of hour adjustment. 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