UM1816 User manual Description of STM32L1xx HAL drivers Introduction TM STMCube is an STMicroelectronics original initiative to ease developers life by reducing development efforts, time and cost. STM32Cube covers STM32 portfolio. STM32Cube Version 1.x includes: The STM32CubeMX, a graphical software configuration tool that allows generating C initialization code using graphical wizards. A comprehensive embedded software platform, delivered per series (such 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 TM development tools. It is checked with CodeSonar static analysis tool. It is fully documented and is MISRA-C 2004 compliant. The HAL drivers layer implements run-time failure detection by checking the input values of all functions. Such dynamic checking contributes to enhance the firmware robustness. Run-time detection is also suitable for user application development and debugging. This user manual is structured as follows: Overview of the HAL drivers Detailed description of each peripheral driver: configuration structures, functions, and how to use the given API to build your application. May 2015 DOCID026682 Rev 3 1/654 www.st.com Contents UM1816 Contents 1 Acronyms and definitions............................................................. 37 2 Overview of HAL drivers ............................................................... 39 2.1 2.2 2/654 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 2.3 API classification ............................................................................. 44 2.4 Devices supported by HAL drivers .................................................. 45 2.5 HAL drivers rules............................................................................. 50 2.5.1 HAL API naming rules ...................................................................... 50 2.5.2 HAL general naming rules ................................................................ 51 2.5.3 HAL interrupt handler and callback functions ................................... 52 2.6 HAL generic APIs ............................................................................ 53 2.7 HAL extension APIs ........................................................................ 54 2.7.1 HAL extension model overview ........................................................ 54 2.7.2 HAL extension model cases ............................................................. 54 2.8 File inclusion model......................................................................... 57 2.9 HAL common resources .................................................................. 58 2.10 HAL configuration............................................................................ 59 2.11 HAL system peripheral handling ..................................................... 60 2.12 3 HAL and user-application files......................................................... 39 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 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 HAL System Driver ........................................................................ 76 DOCID026682 Rev 3 UM1816 Contents 3.1 HAL System Driver .......................................................................... 76 3.2 HAL Firmware driver API description .............................................. 76 3.3 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 4 HAL ................................................................................................... 80 HAL ADC Generic Driver ............................................................... 82 4.1 HAL ADC Generic Driver ................................................................ 82 4.2 ADC Firmware driver registers structures ....................................... 82 4.3 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 4.3.4 UM1816 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 5 HAL ADC Extension Driver ......................................................... 111 5.1 HAL ADC Extension Driver ........................................................... 111 5.2 ADCEx Firmware driver registers structures ................................. 111 5.2.1 5.3 4/654 ADC .................................................................................................. 96 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 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 6 HAL COMP Generic Driver .......................................................... 120 6.1 HAL COMP Generic Driver ........................................................... 120 6.2 COMP Firmware driver registers structures .................................. 120 6.3 6.4 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 7 ADCEx ............................................................................................ 115 COMP ............................................................................................. 126 HAL COMP Extension Driver ...................................................... 134 7.1 HAL COMP Extension Driver ........................................................ 134 7.2 COMPEx Firmware driver defines ................................................. 134 7.2.1 COMPEx ......................................................................................... 134 DOCID026682 Rev 3 5/654 Contents 8 UM1816 HAL CORTEX Generic Driver ...................................................... 137 8.1 HAL CORTEX Generic Driver ....................................................... 137 8.2 CORTEX Firmware driver registers structures .............................. 137 8.2.1 8.3 8.4 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 9 CORTEX ......................................................................................... 142 HAL CRC Generic Driver ............................................................. 146 9.1 HAL CRC Generic Driver .............................................................. 146 9.2 CRC Firmware driver registers structures ..................................... 146 9.2.1 9.3 6/654 MPU_Region_InitTypeDef .............................................................. 137 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 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 10 CRC ................................................................................................ 149 HAL CRYP Generic Driver........................................................... 151 10.1 HAL CRYP Generic Driver ............................................................ 151 10.2 CRYP Firmware driver registers structures ................................... 151 10.3 10.2.1 CRYP_InitTypeDef ......................................................................... 151 10.2.2 CRYP_HandleTypeDef................................................................... 151 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 10.4 10.3.25 UM1816 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 CRYP Firmware driver defines ...................................................... 161 10.4.1 11 HAL CRYP Extension Driver ....................................................... 165 11.1 HAL CRYP Extension Driver ......................................................... 165 11.2 CRYPEx Firmware driver API description ..................................... 165 11.3 11.2.1 Extended features functions ........................................................... 165 11.2.2 HAL_CRYPEx_ComputationCpltCallback...................................... 165 CRYPEx Firmware driver defines.................................................. 165 11.3.1 12 CRYPEx ......................................................................................... 165 HAL DAC Generic Driver ............................................................. 166 12.1 HAL DAC Generic Driver .............................................................. 166 12.2 DAC Firmware driver registers structures ..................................... 166 12.3 8/654 CRYP .............................................................................................. 161 12.2.1 DAC_HandleTypeDef ..................................................................... 166 12.2.2 DAC_ChannelConfTypeDef ........................................................... 166 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 DOCID026682 Rev 3 UM1816 Contents 12.4 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 DAC Firmware driver defines ........................................................ 176 12.4.1 13 HAL DAC Extension Driver ......................................................... 180 13.1 HAL DAC Extension Driver ........................................................... 180 13.2 DACEx Firmware driver API description ....................................... 180 13.3 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 DACEx Firmware driver defines .................................................... 183 13.3.1 14 DAC ................................................................................................ 176 DACEx ............................................................................................ 183 HAL DMA Generic Driver ............................................................ 185 14.1 HAL DMA Generic Driver .............................................................. 185 14.2 DMA Firmware driver registers structures ..................................... 185 14.3 14.2.1 DMA_InitTypeDef ........................................................................... 185 14.2.2 __DMA_HandleTypeDef................................................................. 185 DMA Firmware driver API description ........................................... 186 DOCID026682 Rev 3 9/654 Contents 14.4 14.3.1 UM1816 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 DMA Firmware driver defines ........................................................ 190 14.4.1 15 HAL DMA Extension Driver......................................................... 195 15.1 HAL DMA Extension Driver ........................................................... 195 15.2 DMAEx Firmware driver defines.................................................... 195 15.2.1 16 DMAEx............................................................................................ 195 HAL FLASH Generic Driver......................................................... 197 16.1 HAL FLASH Generic Driver........................................................... 197 16.2 FLASH Firmware driver registers structures ................................. 197 16.2.1 16.3 10/654 DMA ................................................................................................ 190 FLASH_ProcessTypeDef ............................................................... 197 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 DOCID026682 Rev 3 UM1816 Contents 16.4 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 FLASH Firmware driver defines .................................................... 202 16.4.1 17 HAL FLASH Extension Driver ..................................................... 206 17.1 HAL FLASH Extension Driver ....................................................... 206 17.2 FLASHEx Firmware driver registers structures ............................. 206 17.3 17.4 17.2.1 FLASH_EraseInitTypeDef .............................................................. 206 17.2.2 FLASH_OBProgramInitTypeDef .................................................... 206 17.2.3 FLASH_AdvOBProgramInitTypeDef .............................................. 207 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 FLASHEx Firmware driver defines ................................................ 212 17.4.1 18 FLASH ............................................................................................ 202 FLASHEx ........................................................................................ 212 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 19 18.2.5 UM1816 HAL_FLASHEx_HalfPageProgram ................................................ 220 18.2.6 HAL_FLASHEx_DATAEEPROM_EraseDoubleWord .................... 221 18.2.7 HAL_FLASHEx_DATAEEPROM_ProgramDoubleWord ............... 221 HAL GPIO Generic Driver............................................................ 223 19.1 HAL GPIO Generic Driver ............................................................. 223 19.2 GPIO Firmware driver registers structures .................................... 223 19.2.1 19.3 19.4 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 GPIO Firmware driver defines ....................................................... 227 19.4.1 20 20.1 HAL GPIO Extension Driver .......................................................... 231 20.2 GPIOEx Firmware driver defines................................................... 231 GPIOEx .......................................................................................... 231 HAL I2C Generic Driver ............................................................... 233 21.1 HAL I2C Generic Driver ................................................................ 233 21.2 I2C Firmware driver registers structures ....................................... 233 21.3 12/654 GPIO ............................................................................................... 227 HAL GPIO Extension Driver ........................................................ 231 20.2.1 21 GPIO_InitTypeDef .......................................................................... 223 21.2.1 I2C_InitTypeDef .............................................................................. 233 21.2.2 I2C_HandleTypeDef ....................................................................... 233 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 DOCID026682 Rev 3 UM1816 Contents 21.4 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 I2C Firmware driver defines .......................................................... 247 21.4.1 22 I2C .................................................................................................. 247 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 22.2.2 22.3 22.4 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 I2S Firmware driver defines .......................................................... 264 22.4.1 23 I2S .................................................................................................. 264 HAL IRDA Generic Driver ............................................................ 268 23.1 HAL IRDA Generic Driver ............................................................. 268 23.2 IRDA Firmware driver registers structures .................................... 268 23.3 14/654 UM1816 I2S_HandleTypeDef ....................................................................... 254 23.2.1 IRDA_InitTypeDef ........................................................................... 268 23.2.2 IRDA_HandleTypeDef .................................................................... 268 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 DOCID026682 Rev 3 UM1816 Contents 23.4 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 IRDA Firmware driver defines ....................................................... 278 23.4.1 24 IRDA ............................................................................................... 278 HAL IWDG Generic Driver ........................................................... 286 24.1 HAL IWDG Generic Driver ............................................................ 286 24.2 IWDG Firmware driver registers structures ................................... 286 24.3 24.2.1 IWDG_InitTypeDef ......................................................................... 286 24.2.2 IWDG_HandleTypeDef ................................................................... 286 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 25 HAL LCD Generic Driver ............................................................. 291 25.1 HAL LCD Generic Driver ............................................................... 291 25.2 LCD Firmware driver registers structures ...................................... 291 25.3 25.4 25.2.1 LCD_InitTypeDef ............................................................................ 291 25.2.2 LCD_HandleTypeDef ..................................................................... 292 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 LCD Firmware driver defines......................................................... 296 25.4.1 26 LCD................................................................................................. 296 HAL NOR Generic Driver............................................................. 306 26.1 HAL NOR Generic Driver .............................................................. 306 26.2 NOR Firmware driver registers structures ..................................... 306 26.3 16/654 IWDG .............................................................................................. 288 26.2.1 NOR_IDTypeDef ............................................................................ 306 26.2.2 NOR_CFITypeDef .......................................................................... 306 26.2.3 NOR_HandleTypeDef..................................................................... 307 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 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.4 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 NOR Firmware driver defines ........................................................ 313 26.4.1 27 NOR ................................................................................................ 313 HAL OPAMP Generic Driver ....................................................... 315 27.1 HAL OPAMP Generic Driver ......................................................... 315 27.2 OPAMP Firmware driver registers structures ................................ 315 27.3 27.2.1 OPAMP_InitTypeDef ...................................................................... 315 27.2.2 OPAMP_HandleTypeDef................................................................ 316 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 27.4 27.3.15 UM1816 HAL_OPAMP_GetTrimOffset ......................................................... 321 27.3.16 HAL_OPAMP_GetState ................................................................. 321 OPAMP Firmware driver defines ................................................... 322 27.4.1 28 HAL OPAMP Extension Driver .................................................... 327 28.1 HAL OPAMP Extension Driver ...................................................... 327 28.2 OPAMPEx Firmware driver API description .................................. 327 28.3 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 OPAMPEx Firmware driver defines............................................... 328 28.3.1 29 OPAMPEx ...................................................................................... 328 HAL PCD Generic Driver ............................................................. 330 29.1 HAL PCD Generic Driver .............................................................. 330 29.2 PCD Firmware driver registers structures ..................................... 330 29.3 18/654 OPAMP ........................................................................................... 322 29.2.1 PCD_InitTypeDef ............................................................................ 330 29.2.2 PCD_EPTypeDef ............................................................................ 330 29.2.3 PCD_HandleTypeDef ..................................................................... 331 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 DOCID026682 Rev 3 UM1816 Contents 29.4 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 PCD Firmware driver defines ........................................................ 340 29.4.1 30 HAL PCD Extension Driver ......................................................... 349 30.1 HAL PCD Extension Driver ........................................................... 349 30.2 PCDEx Firmware driver API description ....................................... 349 30.3 30.2.1 Peripheral Control functions ........................................................... 349 30.2.2 HAL_PCDEx_PMAConfig .............................................................. 349 PCDEx Firmware driver defines .................................................... 349 30.3.1 31 PCD ................................................................................................ 340 PCDEx ............................................................................................ 349 HAL PWR Generic Driver ............................................................ 350 31.1 HAL PWR Generic Driver .............................................................. 350 31.2 PWR Firmware driver registers structures .................................... 350 31.2.1 31.3 PWR_PVDTypeDef ........................................................................ 350 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 31.3.3 UM1816 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 31.4 PWR Firmware driver defines ....................................................... 358 31.4.1 32 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 PWREx Firmware driver defines ................................................... 365 32.3.1 20/654 PWR ............................................................................................... 358 HAL PWR Extension Driver ........................................................ 364 32.3 33 HAL_PWR_PVDCallback ............................................................... 358 PWREx ........................................................................................... 365 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 DOCID026682 Rev 3 UM1816 Contents 33.2.3 33.3 33.4 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 RCC Firmware driver defines ........................................................ 374 33.4.1 34 RCC ................................................................................................ 374 HAL RCC Extension Driver ......................................................... 400 34.1 HAL RCC Extension Driver ........................................................... 400 34.2 RCCEx Firmware driver registers structures ................................. 400 34.2.1 34.3 34.4 RCC_PeriphCLKInitTypeDef .......................................................... 400 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 RCCEx Firmware driver defines .................................................... 402 34.4.1 35 RCC_ClkInitTypeDef ...................................................................... 367 RCCEx ............................................................................................ 402 HAL RTC Generic Driver ............................................................. 408 35.1 HAL RTC Generic Driver ............................................................... 408 DOCID026682 Rev 3 21/654 Contents UM1816 35.2 35.3 22/654 RTC Firmware driver registers structures ..................................... 408 35.2.1 RTC_InitTypeDef ............................................................................ 408 35.2.2 RTC_DateTypeDef ......................................................................... 408 35.2.3 RTC_HandleTypeDef ..................................................................... 409 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 DOCID026682 Rev 3 UM1816 Contents 35.4 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 RTC Firmware driver defines ........................................................ 421 35.4.1 36 RTC ................................................................................................ 421 HAL RTC Extension Driver ......................................................... 431 36.1 HAL RTC Extension Driver............................................................ 431 36.2 RTCEx Firmware driver registers structures ................................. 431 36.3 36.2.1 RTC_TamperTypeDef .................................................................... 431 36.2.2 RTC_TimeTypeDef......................................................................... 431 36.2.3 RTC_AlarmTypeDef ....................................................................... 432 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 36.4 36.3.25 UM1816 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 RTCEx Firmware driver defines .................................................... 444 36.4.1 37 HAL SD Generic Driver ............................................................... 468 37.1 HAL SD Generic Driver ................................................................. 468 37.2 SD Firmware driver registers structures ........................................ 468 37.3 24/654 RTCEx ............................................................................................ 444 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 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 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.4 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 SD Firmware driver defines ........................................................... 482 37.4.1 38 SD ................................................................................................... 482 HAL SMARTCARD Generic Driver.............................................. 495 38.1 HAL SMARTCARD Generic Driver ............................................... 495 38.2 SMARTCARD Firmware driver registers structures ...................... 495 38.3 38.2.1 SMARTCARD_InitTypeDef ............................................................ 495 38.2.2 SMARTCARD_HandleTypeDef ...................................................... 496 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 38.4 38.3.10 UM1816 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 SMARTCARD Firmware driver defines ......................................... 505 38.4.1 39 HAL SPI Generic Driver ............................................................... 516 39.1 HAL SPI Generic Driver ................................................................ 516 39.2 SPI Firmware driver registers structures ....................................... 516 39.3 26/654 SMARTCARD ................................................................................. 505 39.2.1 SPI_InitTypeDef ............................................................................. 516 39.2.2 __SPI_HandleTypeDef ................................................................... 517 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 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.4 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 SPI Firmware driver defines .......................................................... 525 39.4.1 40 SPI .................................................................................................. 525 HAL SRAM Generic Driver .......................................................... 532 40.1 HAL SRAM Generic Driver ............................................................ 532 40.2 SRAM Firmware driver registers structures................................... 532 40.2.1 40.3 SRAM_HandleTypeDef .................................................................. 532 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 40.4 40.3.21 UM1816 HAL_SRAM_WriteOperation_Disable ............................................ 537 40.3.22 HAL_SRAM_GetState .................................................................... 537 SRAM Firmware driver defines ..................................................... 538 40.4.1 41 HAL TIM Generic Driver .............................................................. 539 41.1 HAL TIM Generic Driver ................................................................ 539 41.2 TIM Firmware driver registers structures ....................................... 539 41.3 28/654 SRAM ............................................................................................. 538 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 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 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 41.3.60 UM1816 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 30/654 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 42 HAL TIM Extension Driver........................................................... 589 42.1 HAL TIM Extension Driver ............................................................. 589 42.2 TIMEx Firmware driver registers structures................................... 589 42.2.1 42.3 42.4 TIM_MasterConfigTypeDef ............................................................ 589 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 TIMEx Firmware driver defines ..................................................... 591 42.4.1 43 TIM.................................................................................................. 571 TIMEx ............................................................................................. 591 HAL UART Generic Driver........................................................... 593 43.1 HAL UART Generic Driver ............................................................ 593 43.2 UART Firmware driver registers structures ................................... 593 43.3 43.2.1 UART_InitTypeDef ......................................................................... 593 43.2.2 UART_HandleTypeDef ................................................................... 594 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 43.4 43.3.16 UM1816 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 UART Firmware driver defines ...................................................... 606 43.4.1 44 HAL USART Generic Driver ........................................................ 618 44.1 HAL USART Generic Driver .......................................................... 618 44.2 USART Firmware driver registers structures ................................. 618 44.3 32/654 UART .............................................................................................. 606 44.2.1 USART_InitTypeDef ....................................................................... 618 44.2.2 USART_HandleTypeDef ................................................................ 619 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 DOCID026682 Rev 3 UM1816 Contents 44.4 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 USART Firmware driver defines.................................................... 630 44.4.1 45 USART............................................................................................ 630 HAL WWDG Generic Driver ........................................................ 639 45.1 HAL WWDG Generic Driver .......................................................... 639 45.2 WWDG Firmware driver registers structures ................................. 639 45.3 45.2.1 WWDG_InitTypeDef ....................................................................... 639 45.2.2 WWDG_HandleTypeDef ................................................................ 639 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 45.4 45.3.13 UM1816 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 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 UM1816 List of figures 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 Table 1: Acronyms and definitions Acronym Definition ADC Analog-to-digital converter ANSI American National Standards Institute API Application Programming Interface BSP Board Support Package COMP Comparator CMSIS Cortex Microcontroller Software Interface Standard CPU CRYP Central Processing Unit Cryptographic processor unit CRC CRC calculation unit DAC Digital to analog converter DMA Direct Memory Access EXTI External interrupt/event controller FLASH Flash memory GPIO General purpose I/Os HAL Hardware abstraction layer I2C Inter-integrated circuit I2S Inter-integrated sound IRDA InfraRed Data Association IWDG Independent watchdog LCD Liquid Crystal Display Controler MSP MCU Specific Package NVIC Nested Vectored Interrupt Controller PCD USB Peripheral Controller Driver PWR Power controller RCC Reset and clock controller RNG Random Number Generator RTC Real-time clock SD SRAM SMARTCARD SPI SysTick Secure Digital SRAM external memory Smartcard IC Serial Peripheral interface System tick timer TIM Advanced-control, general-purpose or basic timer TSC Touch Sensing Controller DOCID026682 Rev 3 37/654 Acronyms and definitions UM1816 Acronym 38/654 Definition UART Universal asynchronous receiver/transmitter USART Universal synchronous receiver/transmitter WWDG Window watchdog USB Universal Serial Bus PPP STM32 peripheral or block DOCID026682 Rev 3 UM1816 2 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. 2.1 HAL and user-application files 2.1.1 HAL driver files A HAL drivers are composed of the following set of files: Table 2: HAL drivers files File Description stm32l1xx_hal_ppp.c 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, … stm32l1xx_hal_ppp.h Header file of the main driver C file It includes common data, handle and enumeration structures, define statements and macros, as well as the exported generic APIs. Example: stm32l1xx_hal_adc.h, stm32l1xx_hal_irda.h, … DOCID026682 Rev 3 39/654 Overview of HAL drivers 2.1.2 UM1816 File Description stm32l1xx_hal_ppp_ex.c Extension file of a peripheral/module driver. It includes the specific APIs for a given part number or family, as well as the newly defined APIs that overwrite the default generic APIs if the internal process is implemented in different way. Example: stm32l1xx_hal_adc_ex.c, stm32l1xx_hal_dma_ex.c, … stm32l1xx_hal_ppp_ex.h Header file of the extension C file. It includes the specific data and enumeration structures, define statements and macros, as well as the exported device part number specific APIs Example: stm32l1xx_hal_adc_ex.h, stm32l1xx_hal_dma_ex.h, … stm32l1xx_hal.c This file is used for HAL initialization and contains DBGMCU, Remap and Time Delay based on systick APIs. stm32l1xx_hal.h stm32l1xx_hal.c header file stm32l1xx_hal_msp_template.c Template file to be copied to the user application folder. It contains the MSP initialization and de-initialization (main routine and callbacks) of the peripheral used in the user application. stm32l1xx_hal_conf_template.h Template file allowing to customize the drivers for a given application. stm32l1xx_hal_def.h Common HAL resources such as common define statements, enumerations, structures and macros. User-application files The minimum files required to build an application using the HAL are listed in the table below: Table 3: User-application files File system_stm32l1xx.c Description 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 : 40/654 relocate the vector table in internal SRAM. startup_stm32l1xx.s Toolchain specific file that contains reset handler and exception vectors. For some toolchains, it allows adapting the stack/heap size to fit the application requirements. stm32l1xx_flash.icf (optional) Linker file for EWARM toolchain allowing mainly to adapt the stack/heap size to fit the application requirements. stm32l1xx_hal_msp.c This file contains the MSP initialization and de-initialization (main routine and callbacks) of the peripheral used in the user application. stm32l1xx_hal_conf.h This file allows the user to customize the HAL drivers for a specific application. It is not mandatory to modify this configuration. The application can use the default configuration without any modification. DOCID026682 Rev 3 UM1816 Overview of HAL drivers File Description stm32l1xx_it.c/.h This file contains the exceptions handler and peripherals interrupt service routine, and calls HAL_IncTick() at regular time intervals to increment a local variable (declared in 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. This file contains the main program routine, mainly: main.c/.h the call to HAL_Init() assert_failed() implementation system clock configuration peripheral HAL initialization and user application code. The STM32Cube package comes with ready-to-use project templates, one for each supported board. Each project contains the files listed above and a preconfigured project for the supported toolchains. Each project template provides empty main loop function and can be used as a starting point to get familiar with project settings for STM32Cube. Their characteristics are the following: It contains sources of HAL, CMSIS and BSP drivers which are the minimal components to develop a code on a given board. It contains the include paths for all the firmware components. 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 UM1816 Figure 1: Example of project template 2.2 HAL data structures Each HAL driver can contain the following data structures: 2.2.1 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: 42/654 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); 44/654 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. 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. Table 4: APis classification Generic file Common APIs X Extension file X (1) Family specific APIs X Device specific APIs X Notes: (1) In some cases, the implementation for a specific device part number may change . In this case the generic API is declared as weak function in the extension file. The API is implemented again to overwrite the default function Family specific APIs are only related to a given family. This means that if a specific API is implemented in another family, and the arguments of this latter family are different, additional structures and arguments might need to be added. The IRQ handlers are used for common and family specific processes. 2.4 Devices supported by HAL drivers DOCID026682 Rev 3 45/654 Overview of HAL drivers UM1816 Table 5: List of devices supported by HAL drivers STM32L151xB STM32L151xBA STM32L151xC STM32L151xCA STM32L151xD STM32L151xDX STM32L151xE STM32L152xB STM32L152xBA STM32L152xC STM32L152xCA STM32L152xD STM32L152xDX STM32L152xE STM32L162xC STM32L162xCA STM32L162xD STM32L162xDX STM32L162xE LCD Line w/ AES STM32L100xC LCD LINE w/o AES STM32L100xBA ACCESS LINE STM32L100xB VALUE LINE 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 Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes 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 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 Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_flash.c stm32l1xx_hal_flash.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_flash_ramfunc.c stm32l1xx_hal_flash_ramfunc.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_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 Files 46/654 DOCID026682 Rev 3 UM1816 Overview of HAL drivers STM32L151xB STM32L151xBA STM32L151xC STM32L151xCA STM32L151xD STM32L151xDX STM32L151xE STM32L152xB STM32L152xBA STM32L152xC STM32L152xCA STM32L152xD STM32L152xDX STM32L152xE STM32L162xC STM32L162xCA STM32L162xD STM32L162xDX STM32L162xE LCD Line w/ AES STM32L100xC LCD LINE w/o AES STM32L100xBA ACCESS LINE STM32L100xB VALUE LINE 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 No No No No No Yes Yes Yes Yes Yes No No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes stm32l1xx_hal_opamp_ex.c stm32l1xx_hal_opamp_ex.h No No No No No Yes Yes Yes Yes Yes No No 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 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_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 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 Files DOCID026682 Rev 3 47/654 Overview of HAL drivers UM1816 STM32L151xB STM32L151xBA STM32L151xC STM32L151xCA STM32L151xD STM32L151xDX STM32L151xE STM32L152xB STM32L152xBA STM32L152xC STM32L152xCA STM32L152xD STM32L152xDX STM32L152xE STM32L162xC STM32L162xCA STM32L162xD STM32L162xDX STM32L162xE LCD Line w/ AES STM32L100xC LCD LINE w/o AES STM32L100xBA ACCESS LINE STM32L100xB VALUE LINE stm32l1xx_hal_rcc_ex.c stm32l1xx_hal_rcc_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_rtc.c stm32l1xx_hal_rtc.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_rtc_ex.c stm32l1xx_hal_rtc_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_sd.c stm32l1xx_hal_sd.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_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 stm32l1xx_hal_spi_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_sram.c stm32l1xx_hal_sram.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_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 Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes 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 stm32l1xx_hal_usart.c stm32l1xx_hal_usart.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_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 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 Files 48/654 DOCID026682 Rev 3 Files stm32l1xx_ll_sdmmc.c stm32l1xx_ll_sdmmc.h No No No No No No No Yes No No DOCID026682 Rev 3 No No No No Yes No No No No Yes No STM32L162xE STM32L162xDX STM32L162xD LCD LINE w/o AES STM32L162xCA STM32L162xC STM32L152xE STM32L152xDX STM32L152xD STM32L152xCA ACCESS LINE STM32L152xC STM32L152xBA STM32L152xB STM32L151xE STM32L151xDX STM32L151xD VALUE LINE STM32L151xCA STM32L151xC STM32L151xBA STM32L151xB STM32L100xC STM32L100xBA STM32L100xB UM1816 Overview of HAL drivers LCD Line w/ AES No 49/654 Overview of HAL drivers UM1816 2.5 HAL drivers rules 2.5.1 HAL API naming rules The following naming rules are used in HAL drivers: Table 6: HAL API naming rules File names Generic Family specific Device specific stm32l1xx_hal_ppp (c/h) stm32l1xx_hal_ppp_ex (c/h) stm32l1xx_ hal_ppp_ex (c/h) Module name Functio n name HAL_PPP_Function HAL_PPP_FeatureFunction_ MODE HAL_PPPEx_Function HAL_PPPEx_FeatureFunction_ MODE HAL_PPPEx_Function HAL_PPPEx_FeatureFunction_ MODE Handle name PPP_HandleTypedef NA NA Init structu re name PPP_InitTypeDef NA PPP_InitTypeDef Enum name HAL_PPP_StructnameTypeD ef NA NA 50/654 HAL_PPP_ MODULE 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()). DOCID026682 Rev 3 UM1816 Overview of HAL drivers 2.5.2 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__) Enables a specific peripheral interrupt __HAL_PPP_DISABLE_IT(__HANDLE__, __INTERRUPT__) Disables a specific peripheral 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__) Gets a specific peripheral interrupt status Clears a specific peripheral interrupt status Gets a specific peripheral flag status Clears a specific peripheral flag status __HAL_PPP_ENABLE(__HANDLE__) Enables a peripheral __HAL_PPP_DISABLE(__HANDLE__) Disables a peripheral __HAL_PPP_XXXX (__HANDLE__, __PARAM__) Specific PPP HAL driver macro __HAL_PPP_GET_ IT_SOURCE (__HANDLE__, __ INTERRUPT __) Checks the source of specified interrupt 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. Table 8: Callback functions 52/654 Callback functions Example HAL_PPP_MspInit() / _DeInit() Ex: HAL_USART_MspInit() Called from HAL_PPP_Init() API function to perform peripheral system level initialization (GPIOs, clock, DMA, interrupt) HAL_PPP_ProcessCpltCallback Ex: HAL_USART_TxCpltCallback Called by peripheral or DMA interrupt handler when the process completes HAL_PPP_ErrorCallback Ex: HAL_USART_ErrorCallback Called by peripheral or DMA interrupt handler when an error occurs 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 HAL_ADC_Init() Initialization group IO operation group Description This function initializes the peripheral and configures the low -level resources (clocks, GPIO, AF..) HAL_ADC_DeInit() This function restores the peripheral default state, frees the low-level resources and removes any direct dependency with the hardware. HAL_ADC_Start () This function starts ADC conversions when the polling method is used HAL_ADC_Stop () This function stops ADC conversions when the polling method is used HAL_ADC_PollForConversion() This function allows waiting for the end of conversions when the polling method is used. In this case, a timout value is specified by the user according to the application. HAL_ADC_Start_IT() This function starts ADC conversions when the interrupt method is used HAL_ADC_Stop_IT() This function stops ADC conversions when the interrupt method is used HAL_ADC_IRQHandler() This function handles ADC interrupt requests DOCID026682 Rev 3 53/654 Overview of HAL drivers Function Group UM1816 Common API Name Description HAL_ADC_ConvCpltCallback() Callback function called in the IT subroutine to indicate the end of the current process or when a DMA transfer has completed HAL_ADC_ErrorCallback() Callback function called in the IT subroutine if a peripheral error or a DMA transfer error occurred HAL_ADC_ConfigChannel() This function configures the selected ADC regular channel, the corresponding rank in the sequencer and the sample time HAL_ADC_AnalogWDGConfig This function configures the analog watchdog for the selected ADC Control group HAL_ADC_GetState() This function allows getting in runtime the peripheral and the data flow states. HAL_ADC_GetError() This fuction allows getting in runtime the error that occurred during IT routine State and Errors group 2.7 HAL extension APIs 2.7.1 HAL extension model overview The extension APIs provide specific functions or overwrite modified APIs for a specific family (series) or specific part number within the same family. The extension model consists of an additional file, 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: Table 10: HAL extension APIs 2.7.2 Function Group Common API Name HAL_ADCEx_CalibrationStart() This function is used to start the automatic ADC calibration HAL_ADCEx_Calibration_GetValue() This function is used to get the ADC calibration factor HAL_ADCEx_Calibration_SetValue() 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 Overview of HAL drivers Figure 2: Adding device-specific functions 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 UM1816 Figure 4: Adding new peripherals 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 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 */ 56/654 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 2.10 Overview of HAL drivers 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 Defines the value of the external oscillator (HSE) expressed in Hz. The user must adjust this define statement when using a different crystal value. 8 000 000 (Hz) HSE_STARTUP_TIMEOUT Timeout for HSE start up, expressed in ms 5000 HSI_VALUE Defines the value of the internal oscillator (HSI) expressed in Hz. 16 000 000 (Hz) MSI_VALUE Defines the Internal Multiple Speed oscillator (MSI) value expressed in Hz. 2 097 000 (Hz) LSE_VALUE Defines the value of the external oscillator (HSE) expressed in Hz. The user must adjust this define statement when using a different crystal value. 32768 (Hz) LSE_STARTUP_TIMEOUT Timeout for LSE start up, expressed in ms 5000 VDD_VALUE VDD value 3300 (mV) USE_RTOS Enables the use of RTOS FALSE (for future use) PREFETCH_ENABLE Enables prefetch feature TRUE Enables buffer cache FALSE BUFFER_CACHE_ENABLE 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 2.11 UM1816 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: 2.11.2 __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. 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 Table 12: Description of GPIO_InitTypeDef structure Structure field Description Pin Specifies the GPIO pins to be configured. Possible values: GPIO_PIN_x or GPIO_PIN_All, where x[0..15] Specifies the operating mode for the selected pins: GPIO mode or EXTI mode. Possible values are: Mode 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 Pull Specifies the Pull-up or Pull-down activation for the selected pins. Possible values are: GPIO_NOPULL GPIO_PULLUP GPIO_PULLDOWN Speed 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 UM1816 Structure field Description Peripheral to be connected to the selected pins. Possible values: GPIO_AFx_PPP, where AFx: is the alternate function index PPP: is the peripheral instance Example: use GPIO_AF1_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. Alternate Refer to the “Alternate function mapping” table in the datasheets for the detailed description of the system and peripheral I/O alternate functions. Please find below typical GPIO configuration examples: Configuring GPIOs as output push-pull to drive external LEDs GPIO_InitStruct.Pin = GPIO_PIN_12 | GPIO_PIN_13 | GPIO_PIN_14 | GPIO_PIN_15; GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP; GPIO_InitStruct.Pull = GPIO_PULLUP; GPIO_InitStruct.Speed = GPIO_SPEED_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: 62/654 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() DOCID026682 Rev 3 UM1816 2.11.4 Overview of HAL drivers PWR The PWR HAL driver handles power management. The features shared between all STM32 Series are listed below: PVD configuration, enabling/disabling and interrupt handling HAL_PWR_PVDConfig() HAL_PWR_EnablePVD() / HAL_PWR_DisablePVD() HAL_PWR_PVD_IRQHandler() HAL_PWR_PVDCallback() Wakeup pin configuration HAL_PWR_EnableWakeUpPin() / HAL_PWR_DisableWakeUpPin() Low power mode entry HAL_PWR_EnterSLEEPMode() HAL_PWR_EnterSTOPMode() HAL_PWR_EnterSTANDBYMode() Depending on the STM32 Series, extension functions are available in stm32l1xx_hal_pwr_ex. Here are a few examples (the list is not exhaustive) 2.11.5 Ultra low power mode control HAL_PWREx_EnableUltraLowPower() / HAL_PWREx_DisableUltraLowPower() HAL_PWREx_EnableLowPowerRunMode() / HAL_PWREx_DisableLowPowerRunMode() EXTI The EXTI is not considered as a standalone peripheral but rather as a service used by other peripheral. As a result there are no EXTI APIs but each peripheral HAL driver implements the associated EXTI configuration and EXTI function are implemented as macros in its header file. The first 16 EXTI lines connected to the GPIOs are managed within the GPIO driver. The GPIO_InitTypeDef structure allows configuring an I/O as external interrupt or external event. The EXTI lines connected internally to the PVD, RTC, USB, and COMP are configured within the HAL drivers of these peripheral through the macros given in the table below. The EXTI internal connections depend on the targeted STM32 microcontroller (refer to the product datasheet for more details): Table 13: Description of EXTI configuration macros Macros Description PPP_EXTI_LINE_FUNCTION Defines the EXTI line connected to the internal peripheral. Example: #define PWR_EXTI_LINE_PVD ((uint32_t)0x00010000) /*!<External interrupt line 16 Connected to the PVD EXTI Line */ __HAL_PPP_EXTI_ENABLE_IT(__EXTI_LINE__) Enables a given EXTI line Example: __HAL_PVD_EXTI_ENABLE_IT(PWR_EXTI_LINE_PVD) __HAL_PPP_EXTI_DISABLE_IT(__EXTI_LINE__) Disables a given EXTI line. Example: __HAL_PVD_EXTI_DISABLE_IT(PWR_EXTI_LINE_PVD) DOCID026682 Rev 3 63/654 Overview of HAL drivers UM1816 Macros Description __HAL_PPP_EXTI_GET_FLAG(__EXTI_LINE__) 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: 64/654 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). 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 functions”). 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 UM1816 Figure 7: HAL driver model 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. 66/654 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 DOCID026682 Rev 3 UM1816 Overview of HAL drivers 2.12.2.2 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. 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 UM1816 the HAL_PPP_MspDeInit could be implemented in the user file */ } 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() Global MSP initialization routine void HAL_MspDeInit() Global MSP de-initialization routine void HAL_PPP_MspInit() 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: 2.12.3.1 Polling mode Interrupt mode DMA mode 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 UM1816 void USART1_IRQHandler(void) { HAL_UART_IRQHandler(&UartHandle); } 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 0 No poll : Immediate process check and exit 1 ... (HAL_MAX_DELAY -1) HAL_MAX_DELAY (1) Timeout in ms Infinite poll till process is successful Notes: (1) 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: UM1816 void HAL_PPP_ProcessCpltCallback(PPP_HandleTypeDef *hspi) { ErrorCode = HAL_PPP_GetError (hppp); /* retreive error code */ } 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 UM1816 3 HAL System Driver 3.1 HAL System Driver 3.2 HAL Firmware driver API description 3.2.1 How to use this driver The common HAL driver contains a set of generic and common APIs that can be used by the PPP peripheral drivers and the user to start using the HAL. The HAL contains two APIs' categories: 3.2.2 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: 3.2.3 HAL_Init() HAL_DeInit() HAL_MspInit() HAL_MspDeInit() HAL_InitTick() HAL Control functions This section provides functions allowing to: 76/654 Provide a tick value in millisecond Provide a blocking delay in millisecond DOCID026682 Rev 3 UM1816 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: 3.2.4 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 HAL status Notes This function is optional. HAL_MspInit Function Name void HAL_MspInit (void ) DOCID026682 Rev 3 77/654 HAL System Driver Function Description Return values 3.2.7 3.2.8 UM1816 Initializes the MSP. HAL_MspDeInit Function Name void HAL_MspDeInit (void ) Function Description DeInitializes the MSP. Return values Function Name HAL_StatusTypeDef HAL_InitTick (uint32_t TickPriority) Function Description This function configures the source of the time base. Parameters TickPriority: Tick interrupt priority. Return values HAL status Notes This function is called automatically at the beginning of program after reset by HAL_Init() or at any time when clock is reconfigured by HAL_RCC_ClockConfig(). In the default implementation, SysTick timer is the source of time base. It is used to generate interrupts at regular time intervals. Care must be taken if HAL_Delay() is called from a peripheral ISR process, The the SysTick interrupt must have higher priority (numerically lower) than the peripheral interrupt. Otherwise the caller ISR process will be blocked. The function is declared as __Weak to be overwritten in case of other implementation in user file. HAL_IncTick Function Name void HAL_IncTick (void ) Function Description This function is called to increment a global variable "uwTick" used as application time base. Return values None Notes In the default implementation, this variable is incremented each 1ms in Systick ISR. This function is declared as __weak to be overwritten in case of other implementations in user file. 3.2.10 3.2.11 78/654 None HAL_InitTick 3.2.9 None HAL_GetTick Function Name uint32_t HAL_GetTick (void ) Function Description Provides a tick value in millisecond. Return values tick value Notes This function is declared as __weak to be overwritten in case of other implementations in user file. HAL_Delay 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 None Notes In the default implementation , SysTick timer is the source of time base. It is used to generate interrupts at regular time intervals where uwTick is incremented. 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 3.2.15 HAL_GetHalVersion Function Name uint32_t HAL_GetHalVersion (void ) Function Description Returns the HAL revision. Return values version 0xXYZR (8bits for each decimal, R for RC) HAL_GetREVID Function Name uint32_t HAL_GetREVID (void ) Function Description Returns the device revision identifier. Return values Device revision identifier DOCID026682 Rev 3 79/654 HAL System Driver 3.2.16 3.2.17 3.2.18 3.2.19 3.2.20 3.2.21 3.2.22 UM1816 HAL_GetDEVID Function Name uint32_t HAL_GetDEVID (void ) Function Description Returns the device identifier. Return values Device identifier HAL_DBGMCU_EnableDBGSleepMode Function Name void HAL_DBGMCU_EnableDBGSleepMode (void ) Function Description Enable the Debug Module during SLEEP mode. Return values None HAL_DBGMCU_DisableDBGSleepMode Function Name void HAL_DBGMCU_DisableDBGSleepMode (void ) Function Description Disable the Debug Module during SLEEP mode. Return values None HAL_DBGMCU_EnableDBGStopMode Function Name void HAL_DBGMCU_EnableDBGStopMode (void ) Function Description Enable the Debug Module during STOP mode. Return values None HAL_DBGMCU_DisableDBGStopMode Function Name void HAL_DBGMCU_DisableDBGStopMode (void ) Function Description Disable the Debug Module during STOP mode. Return values None HAL_DBGMCU_EnableDBGStandbyMode Function Name void HAL_DBGMCU_EnableDBGStandbyMode (void ) Function Description Enable the Debug Module during STANDBY mode. Return values None HAL_DBGMCU_DisableDBGStandbyMode Function Name void HAL_DBGMCU_DisableDBGStandbyMode (void ) Function Description Disable the Debug Module during STANDBY mode. Return values None 3.3 HAL Firmware driver defines 3.3.1 HAL HAL Private Defines 80/654 DOCID026682 Rev 3 UM1816 HAL System Driver __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 [7:0] release candidate __STM32L1xx_HAL_VERSION IDCODE_DEVID_MASK DOCID026682 Rev 3 81/654 HAL ADC Generic Driver UM1816 4 HAL ADC Generic Driver 4.1 HAL ADC Generic Driver 4.2 ADC Firmware driver registers structures 4.2.1 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 82/654 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 UM1816 Complete-sequence/Discontinuous-sequence (main sequence subdivided in successive parts). Discontinuous mode is used only if sequencer is enabled (parameter 'ScanConvMode'). If sequencer is disabled, this parameter is discarded. Discontinuous mode can be enabled only if continuous mode is disabled. If continuous mode is enabled, this parameter setting is discarded. This parameter can be set to ENABLE or DISABLE. uint32_t ADC_InitTypeDef::NbrOfDiscConversion Specifies the number of discontinuous conversions in which the main sequence of regular group (parameter NbrOfConversion) will be subdivided. If parameter 'DiscontinuousConvMode' is disabled, this parameter is discarded. This parameter must be a number between Min_Data = 1 and Max_Data = 8. uint32_t ADC_InitTypeDef::ExternalTrigConv Selects the external event used to trigger the conversion start of regular group. If set to ADC_SOFTWARE_START, external triggers are disabled. If set to external trigger source, triggering is on event rising edge. 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 84/654 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 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 4.2.4 UM1816 uint32_t ADC_AnalogWDGConfTypeDef::HighThreshold 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 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 ADC Firmware driver API description 4.3.1 ADC peripheral features 86/654 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. DOCID026682 Rev 3 UM1816 HAL ADC Generic Driver 4.3.2 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. 2. 3. 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(). 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() 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 4. Insert the ADC interruption handler function HAL_ADC_IRQHandler() into the function of corresponding ADC interruption vector ADCx_IRQHandler(). 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. 2. 3. 4. 5. Configure the ADC parameters (resolution, data alignment, ...) and regular group parameters (conversion trigger, sequencer, ...) using function HAL_ADC_Init(). Configure the channels for regular group parameters (channel number, channel rank into sequencer, ..., into regular group) using function HAL_ADC_ConfigChannel(). Optionally, configure the injected group parameters (conversion trigger, sequencer, ..., of injected group) and the channels for injected group parameters (channel number, channel rank into sequencer, ..., into injected group) using function HAL_ADCEx_InjectedConfigChannel(). Optionally, configure the analog watchdog parameters (channels monitored, thresholds, ...) using function HAL_ADC_AnalogWDGConfig(). Optionally, for devices with several ADC instances: configure the multimode parameters using function HAL_ADCEx_MultiModeConfigChannel(). Execution of ADC conversions 1. 2. 88/654 Optionally, perform an automatic ADC calibration to improve the conversion accuracy using function HAL_ADCEx_Calibration_Start(). 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: 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. 2. 3. 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); ADC pins configuration Disable the clock for the ADC GPIOs using macro __HAL_RCC_GPIOx_CLK_DISABLE() Optionally, in case of usage of ADC with interruptions: Disable the NVIC for ADC using function HAL_NVIC_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: 4.3.4 HAL_ADC_Init() HAL_ADC_DeInit() HAL_ADC_MspInit() HAL_ADC_MspDeInit() 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: 4.3.5 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: 90/654 Configure channels on regular group Configure the analog watchdog DOCID026682 Rev 3 UM1816 UM1816 HAL ADC Generic Driver This section contains the following APIs: 4.3.6 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: 4.3.7 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 hadc: ADC handle Return values 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 HAL status Notes 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 UM1816 HAL_ADC_MspDeInit(). 4.3.9 4.3.10 4.3.11 4.3.12 4.3.13 92/654 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 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 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 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 HAL status. Notes : 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. 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 DOCID026682 Rev 3 UM1816 HAL ADC Generic Driver Notes 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 4.3.15 4.3.16 4.3.17 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). 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 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. 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 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 4.3.19 4.3.20 4.3.21 4.3.22 94/654 UM1816 HAL_ADC_Stop_DMA Function Name HAL_StatusTypeDef HAL_ADC_Stop_DMA (ADC_HandleTypeDef * hadc) 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 hadc: ADC handle Return values HAL status. Notes : 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. 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. 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 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 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 DOCID026682 Rev 3 UM1816 4.3.23 4.3.24 4.3.25 HAL ADC Generic Driver HAL_ADC_LevelOutOfWindowCallback Function Name void HAL_ADC_LevelOutOfWindowCallback (ADC_HandleTypeDef * hadc) Function Description Analog watchdog callback in non blocking mode. Parameters hadc: ADC handle Return values None 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 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 hadc: ADC handle sConfig: Structure of ADC channel for regular group. Return values HAL status Notes 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 hadc: ADC handle AnalogWDGConfig: Structure of ADC analog watchdog configuration Return values HAL status DOCID026682 Rev 3 95/654 HAL ADC Generic Driver 4.3.27 4.3.28 UM1816 HAL_ADC_GetState Function Name uint32_t HAL_ADC_GetState (ADC_HandleTypeDef * hadc) Function Description return the ADC state Parameters hadc: ADC handle Return values HAL state HAL_ADC_GetError Function Name uint32_t HAL_ADC_GetError (ADC_HandleTypeDef * hadc) Function Description Return the ADC error code. Parameters hadc: ADC handle Return values ADC Error Code 4.4 ADC Firmware driver defines 4.4.1 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 UM1816 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 HAL_ADC_ERROR_OVR Overrun error HAL_ADC_ERROR_DMA DMA transfer error ADC Event type ADC_AWD_EVENT ADC Analog watchdog event ADC_OVR_EVENT ADC overrun event ADC Exported Macros __HAL_ADC_ENABLE Description: Enable the ADC peripheral. Parameters: __HANDLE__: ADC handle Return value: __HAL_ADC_DISABLE None Description: Disable the ADC peripheral. Parameters: __HANDLE__: ADC handle Return value: __HAL_ADC_ENABLE_IT None Description: Enable the ADC end of conversion interrupt. Parameters: 98/654 __HANDLE__: ADC handle __INTERRUPT__: ADC Interrupt This parameter can be any combination of the DOCID026682 Rev 3 UM1816 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: __HAL_ADC_DISABLE_IT 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: __HAL_ADC_GET_IT_SOURCE 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 UM1816 State: of interruption (SET or RESET) Description: __HAL_ADC_GET_FLAG 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: __HAL_ADC_CLEAR_FLAG None Description: Clear the ADC's pending flags. Parameters: 100/654 __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 Return value: __HAL_ADC_RESET_HANDLE_STATE None Description: Reset ADC handle state. Parameters: __HANDLE__: ADC handle Return value: None ADC Exported Types HAL_ADC_STATE_RESET ADC not yet initialized or disabled HAL_ADC_STATE_READY ADC peripheral ready for use HAL_ADC_STATE_BUSY_INTERNAL ADC is busy to internal process (initialization, calibration) HAL_ADC_STATE_TIMEOUT TimeOut occurrence HAL_ADC_STATE_ERROR_INTERNAL Internal error occurrence HAL_ADC_STATE_ERROR_CONFIG Configuration error occurrence HAL_ADC_STATE_ERROR_DMA DMA error occurrence HAL_ADC_STATE_REG_BUSY A conversion on group regular is ongoing or can occur (either by continuous mode, external trigger, low power auto power-on, multimode ADC master control) HAL_ADC_STATE_REG_EOC Conversion data available on group regular HAL_ADC_STATE_REG_OVR Overrun occurrence HAL_ADC_STATE_REG_EOSMP Not available on STM32L1 device: End Of Sampling flag raised HAL_ADC_STATE_INJ_BUSY A conversion on group injected is ongoing or can occur (either by auto-injection mode, external trigger, low power auto power-on, multimode ADC master control) HAL_ADC_STATE_INJ_EOC Conversion data available on group injected HAL_ADC_STATE_INJ_JQOVF Not available on STM32L1 device: Injected queue overflow occurrence HAL_ADC_STATE_AWD1 Out-of-window occurrence of analog watchdog 1 HAL_ADC_STATE_AWD2 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 End of Regular conversion flag ADC_FLAG_JEOC ADC End of Injected conversion flag ADC_FLAG_JSTRT ADC Injected group start flag ADC_FLAG_STRT ADC Regular group start 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 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 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 ADC LowPowerAutoPowerOff ADC_AUTOPOWEROFF_DISABLE ADC_AUTOPOWEROFF_IDLE_PHASE ADC power off when ADC is not converting (idle phase) ADC_AUTOPOWEROFF_DELAY_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 < Note : For compatibility with other STM32 devices with ADC autowait ADC_AUTOWAIT_UNTIL_DATA_READ 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 UM1816 ADC_DISABLE_TIMEOUT ADC_STAB_DELAY_US ADC_TEMPSENSOR_DELAY_US ADC_FLAG_POSTCONV_ALL ADC Private Macros Description: ADC_IS_ENABLE Verification of ADC state: enabled or disabled. Parameters: __HANDLE__: ADC handle Return value: ADC_IS_SOFTWARE_START_REGULAR SET: (ADC enabled) or RESET (ADC disabled) Description: Test if conversion trigger of regular group is software start or external trigger. Parameters: __HANDLE__: ADC handle Return value: ADC_IS_SOFTWARE_START_INJECTED SET: (software start) or RESET (external trigger) Description: Test if conversion trigger of injected group is software start or external trigger. Parameters: __HANDLE__: ADC handle Return value: ADC_STATE_CLR_SET SET: (software start) or RESET (external trigger) Description: Simultaneously clears and sets specific bits of the handle State. Return value: None Notes: 104/654 DOCID026682 Rev 3 : ADC_STATE_CLR_SET() macro is merely aliased to generic macro UM1816 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. ADC_CLEAR_ERRORCODE Description: Clear ADC error code (set it to error code: "no error") Parameters: __HANDLE__: ADC handle Return value: ADC_SQR1_L_SHIFT None Description: Set ADC number of ranks into regular channel sequence length. Parameters: _NbrOfConversion_: Regular channel sequence length Return value: ADC_SMPR2 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: ADC_SMPR3 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: ADC_SQR5_RK None Description: DOCID026682 Rev 3 Set the selected regular channel rank for rank between 1 and 6. 105/654 HAL ADC Generic Driver UM1816 Parameters: _CHANNELNB_: Channel number. _RANKNB_: Rank number. Return value: ADC_SQR4_RK None Description: Set the selected regular channel rank for rank between 7 and 12. Parameters: _CHANNELNB_: Channel number. _RANKNB_: Rank number. Return value: ADC_SQR3_RK None Description: Set the selected regular channel rank for rank between 13 and 18. Parameters: _CHANNELNB_: Channel number. _RANKNB_: Rank number. Return value: ADC_SQR2_RK None Description: Set the selected regular channel rank for rank between 19 and 24. Parameters: _CHANNELNB_: Channel number. _RANKNB_: Rank number. Return value: ADC_SQR1_RK None Description: Set the selected regular channel rank for rank between 25 and 28. Parameters: _CHANNELNB_: Channel number. _RANKNB_: Rank number. Return value: ADC_JSQR_JL_SHIFT Description: 106/654 None DOCID026682 Rev 3 Set the injected sequence length. UM1816 HAL ADC Generic Driver Parameters: _JSQR_JL_: Sequence length. Return value: None Description: ADC_JSQR_RK_JL 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: ADC_CR2_DMACONTREQ Enable the ADC DMA continuous request. Parameters: _DMACONTREQ_MODE_: DMA continuous request mode. Return value: None Description: ADC_CR2_CONTINUOUS Enable ADC continuous conversion mode. Parameters: _CONTINUOUS_MODE_: Continuous mode. Return value: ADC_CR1_DISCONTINUOUS_NUM 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 UM1816 None Description: ADC_CR1_SCAN_SET Enable ADC scan mode to convert multiple ranks with sequencer. Parameters: _SCAN_MODE_: Scan conversion mode. Return value: None 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 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 Sampling time 4 ADC clock cycles ADC_SAMPLETIME_9CYCLES 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 UM1816 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 110/654 DOCID026682 Rev 3 UM1816 HAL ADC Extension Driver 5 HAL ADC Extension Driver 5.1 HAL ADC Extension Driver 5.2 ADCEx Firmware driver registers structures 5.2.1 ADC_InjectionConfTypeDef Data Fields uint32_t InjectedChannel uint32_t InjectedRank uint32_t InjectedSamplingTime uint32_t InjectedOffset uint32_t InjectedNbrOfConversion uint32_t InjectedDiscontinuousConvMode uint32_t AutoInjectedConv uint32_t ExternalTrigInjecConv uint32_t ExternalTrigInjecConvEdge Field Documentation uint32_t ADC_InjectionConfTypeDef::InjectedChannel Selection of ADC channel to configure This parameter can be a value of ADC_channels Note: Depending on devices, some channels may not be available on package pins. Refer to device datasheet for channels availability. uint32_t ADC_InjectionConfTypeDef::InjectedRank Rank in the injected group sequencer This parameter must be a value of ADCEx_injected_rank Note: In case of need to disable a channel or change order of conversion sequencer, rank containing a previous channel setting can be overwritten by the new channel setting (or parameter number of conversions can be adjusted) uint32_t ADC_InjectionConfTypeDef::InjectedSamplingTime Sampling time value to be set for the selected channel. Unit: ADC clock cycles Conversion time is the addition of sampling time and processing time (12 ADC clock cycles at ADC resolution 12 bits, 11 cycles at 10 bits, 9 cycles at 8 bits, 7 cycles at 6 bits). This parameter can be a value of ADC_sampling_times Caution: This parameter updates the parameter property of the channel, that can be used into regular and/or injected groups. If this same channel has been previously configured in the other group (regular/injected), it will be updated to last setting. Note: In case of usage of internal measurement channels (VrefInt/Vbat/TempSensor), sampling time constraints must be respected (sampling time can be adjusted in function of ADC clock frequency and sampling time setting) Refer to device datasheet for timings values, parameters TS_vrefint, TS_temp (values rough order: 4us min). uint32_t ADC_InjectionConfTypeDef::InjectedOffset Defines the offset to be subtracted from the raw converted data (for channels set on injected group only). Offset value must be a positive number. Depending of ADC resolution selected (12, 10, 8 or 6 bits), this parameter must be a number between Min_Data = 0x000 and Max_Data = 0xFFF, 0x3FF, 0xFF or 0x3F respectively. uint32_t ADC_InjectionConfTypeDef::InjectedNbrOfConversion Specifies the number of ranks that will be converted within the injected group DOCID026682 Rev 3 111/654 HAL ADC Extension Driver UM1816 sequencer. To use the injected group sequencer and convert several ranks, 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 HAL ADC Extension Driver 5.3 ADCEx Firmware driver API description 5.3.1 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: 5.3.2 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: 5.3.3 5.3.4 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 HAL_ADCEx_InjectedStop Function Name HAL_StatusTypeDef HAL_ADCEx_InjectedStop (ADC_HandleTypeDef * hadc) Function Description Stop conversion of injected channels. Parameters hadc: ADC handle Return values None Notes If ADC must be disabled and if conversion is on going on regular group, function HAL_ADC_Stop must be used to stop both injected and regular groups, and disable the ADC. In case of auto-injection mode, HAL_ADC_Stop must be used. DOCID026682 Rev 3 113/654 HAL ADC Extension Driver 5.3.5 5.3.6 5.3.7 5.3.8 5.3.9 114/654 UM1816 HAL_ADCEx_InjectedPollForConversion Function Name 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 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 None Notes If ADC must be disabled and if conversion is on going on regular group, function HAL_ADC_Stop must be used to stop both injected and regular groups, and disable the ADC. 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 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 Return values None HAL_ADCEx_InjectedConvCpltCallback Function Name void HAL_ADCEx_InjectedConvCpltCallback (ADC_HandleTypeDef * hadc) Function Description Injected conversion complete callback in non blocking mode. DOCID026682 Rev 3 UM1816 5.3.10 HAL ADC Extension Driver Parameters hadc: ADC handle Return values None 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 None Notes 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 ADCEx Firmware driver defines 5.4.1 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: __HAL_ADC_CHANNEL_SPEED_FAST None 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 Description: __ADC_SQR1_SQXX Set ADC ranks available in register SQR1. Parameters: _NbrOfConversion_: Regular channel sequence length Return value: None Description: ADC_SMPR0 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: ADC_SMPR1 Set the ADC's sample time for channel numbers between 20 and 29. Parameters: _SAMPLETIME_: Sample time parameter. _CHANNELNB_: Channel number. Return value: ADC_SMPR1_CHANNEL_MAX None Description: Defines the highest channel available in register SMPR1. Parameters: DOCID026682 Rev 3 117/654 HAL ADC Extension Driver UM1816 None Return value: None Description: ADC_CR2_MASK_ADCINIT 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: ADC_CONVCYCLES_MAX_RANGE None Description: Get the maximum ADC conversion cycles on all channels. Parameters: __HANDLE__: ADC handle Return value: ADC_GET_CLOCK_PRESCALER_DECIMAL ADC: conversion cycles on all channels Description: Get the ADC clock prescaler from ADC common control register and convert it to its decimal number setting (refer to reference manual) Return value: None Description: ADC_SMPR0_CLEAR Clear register SMPR0. Parameters: __HANDLE__: ADC handle Return value: None Description: ADC_CR2_CLEAR Clear register CR2. Parameters: __HANDLE__: ADC handle Return value: ADC_SMPR0_CHANNEL_SET 118/654 None Description: DOCID026682 Rev 3 UM1816 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 IS_ADC_INJECTED_RANK IS_ADC_EXTTRIGINJEC_EDGE IS_ADC_EXTTRIGINJEC DOCID026682 Rev 3 119/654 HAL COMP Generic Driver UM1816 6 HAL COMP Generic Driver 6.1 HAL COMP Generic Driver 6.2 COMP Firmware driver registers structures 6.2.1 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 120/654 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 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 6.3 COMP Firmware driver API description 6.3.1 COMP Peripheral features The STM32L1xx device family integrates 2 analog comparators COMP1 and COMP2: 1. 2. 3. 4. 5. 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. The COMP output is available using HAL_COMP_GetOutputLevel(). 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". 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. 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 Table 17: COMP Inputs for the STM32L1xx devices 1/4 VREFINT 1/2 VREFINT 3/4 VREFINT VREFINT DAC Ch1 OUT (PA4) DAC Ch2 OUT (PA5) I/O: PB3 Inverting inputs COMP1 COMP2 OK - OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK - I/O: Non-inverting inputs (1) PB4, 5, 6, 7 (2) PA0, 1, 2, 3, 4, 5, 6, 7 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 (3) OPAMP3 output Notes: (1) (2) (3) 6.3.2 PA6/7 are available on devices category Cat.3, Cat.4, Cat.5 only. PA0/1/2/3 are available on devices category Cat.3, Cat.4, Cat.5 only. 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. 122/654 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 DOCID026682 Rev 3 UM1816 2. 3. 4. 5. 6. 6.3.3 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. 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) Enable the comparator using HAL_COMP_Start() or HAL_COMP_Start_IT() function If needed, use HAL_COMP_GetOutputLevel() or HAL_COMP_TriggerCallback() functions to manage comparator actions (output level or events) Disable the comparator using HAL_COMP_Stop() or HAL_COMP_Stop_IT() function 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: 6.3.4 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: 6.3.5 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 UM1816 Peripheral State functions This subsection permit to get in run-time the status of the peripheral. This section contains the following APIs: 6.3.7 6.3.8 6.3.9 6.3.10 6.3.11 HAL_COMP_GetState() 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 hcomp: COMP handle Return values HAL status Notes If the selected comparator is locked, initialization can't be performed. To unlock the configuration, perform a system reset. 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 HAL status Notes 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 hcomp: COMP handle Return values None HAL_COMP_MspDeInit Function Name void HAL_COMP_MspDeInit (COMP_HandleTypeDef * hcomp) Function Description DeInitializes COMP MSP. Parameters hcomp: COMP handle Return values None HAL_COMP_Start Function Name 124/654 HAL_StatusTypeDef HAL_COMP_Start DOCID026682 Rev 3 UM1816 HAL COMP Generic Driver (COMP_HandleTypeDef * hcomp) 6.3.12 6.3.13 6.3.14 6.3.15 6.3.16 Function Description Start the comparator. Parameters hcomp: COMP handle Return values HAL status 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 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. 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 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 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 6.3.18 6.3.19 UM1816 HAL_COMP_GetOutputLevel Function Name uint32_t HAL_COMP_GetOutputLevel (COMP_HandleTypeDef * hcomp) Function Description Return the output level (high or low) of the selected comparator. HAL_COMP_TriggerCallback Function Name void HAL_COMP_TriggerCallback (COMP_HandleTypeDef * hcomp) Function Description Comparator callback. Parameters hcomp: COMP handle Return values None 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 COMP Firmware driver defines 6.4.1 COMP COMP Exported Macro __HAL_COMP_RESET_HANDLE_STATE Description: Reset COMP handle state. Parameters: __HANDLE__: COMP handle. Return value: None Description: __HAL_COMP_ENABLE Enables the specified comparator. Parameters: __HANDLE__: COMP handle. Return value: Description: __HAL_COMP_DISABLE 126/654 None. DOCID026682 Rev 3 UM1816 HAL COMP Generic Driver Disables the specified comparator. Parameters: __HANDLE__: COMP handle. Return value: None. Description: __HAL_COMP_GET_FLAG 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: __HAL_COMP_COMP1_EXTI_ENABLE_RISING_EDGE The: new state of __FLAG__ (TRUE or FALSE). Description: Enable the COMP1 EXTI line rising edge trigger. Return value: __HAL_COMP_COMP1_EXTI_DISABLE_RISING_EDG E None Description: Disable the COMP1 EXTI line rising edge trigger. Return value: __HAL_COMP_COMP1_EXTI_ENABLE_FALLING_EDG E None Description: Enable the COMP1 EXTI line falling edge trigger. Return value: __HAL_COMP_COMP1_EXTI_DISABLE_FALLING_ED GE DOCID026682 Rev 3 None Description: Disable the COMP1 EXTI line falling edge trigger. 127/654 HAL COMP Generic Driver UM1816 Return value: __HAL_COMP_COMP1_EXTI_ENABLE_RISING_FALLI NG_EDGE None Description: Enable the COMP1 EXTI line rising & falling edge trigger. Return value: __HAL_COMP_COMP1_EXTI_DISABLE_RISING_FALLI NG_EDGE None Description: Disable the COMP1 EXTI line rising & falling edge trigger. Return value: __HAL_COMP_COMP1_EXTI_ENABLE_IT None Description: Enable the COMP1 EXTI line in interrupt mode. Return value: __HAL_COMP_COMP1_EXTI_DISABLE_IT None Description: Disable the COMP1 EXTI line in interrupt mode. Return value: __HAL_COMP_COMP1_EXTI_ENABLE_EVENT None Description: Enable the COMP1 EXTI Line in event mode. Return value: __HAL_COMP_COMP1_EXTI_DISABLE_EVENT None Description: Disable the COMP1 EXTI Line in event mode. Return value: __HAL_COMP_COMP1_EXTI_GET_FLAG None Description: Check whether the COMP1 EXTI line flag is set or not. Return value: 128/654 DOCID026682 Rev 3 UM1816 HAL COMP Generic Driver __HAL_COMP_COMP1_EXTI_CLEAR_FLAG RESET: or SET Description: Clear the the COMP1 EXTI flag. Return value: __HAL_COMP_COMP1_EXTI_GENERATE_SWIT None Description: Generates a Software interrupt on COMP1 EXTI Line. Return value: __HAL_COMP_COMP2_EXTI_ENABLE_RISING_EDGE None Description: Enable the COMP2 EXTI line rising edge trigger. Return value: __HAL_COMP_COMP2_EXTI_DISABLE_RISING_EDG E None Description: Disable the COMP2 EXTI line rising edge trigger. Return value: __HAL_COMP_COMP2_EXTI_ENABLE_FALLING_EDG E None Description: Enable the COMP2 EXTI line falling edge trigger. Return value: __HAL_COMP_COMP2_EXTI_DISABLE_FALLING_ED GE None Description: Disable the COMP2 EXTI line falling edge trigger. Return value: __HAL_COMP_COMP2_EXTI_ENABLE_RISING_FALLI NG_EDGE None Description: Enable the COMP2 EXTI line rising & falling edge trigger. Return value: __HAL_COMP_COMP2_EXTI_DISABLE_RISING_FALLI DOCID026682 Rev 3 None Description: 129/654 HAL COMP Generic Driver NG_EDGE UM1816 Disable the COMP2 EXTI line rising & falling edge trigger. Return value: __HAL_COMP_COMP2_EXTI_ENABLE_IT None Description: Enable the COMP2 EXTI line. Return value: __HAL_COMP_COMP2_EXTI_DISABLE_IT None Description: Disable the COMP2 EXTI line. Return value: __HAL_COMP_COMP2_EXTI_ENABLE_EVENT None Description: Enable the COMP2 EXTI Line in event mode. Return value: __HAL_COMP_COMP2_EXTI_DISABLE_EVENT None Description: Disable the COMP2 EXTI Line in event mode. Return value: __HAL_COMP_COMP2_EXTI_GET_FLAG None Description: Check whether the COMP2 EXTI line flag is set or not. Return value: __HAL_COMP_COMP2_EXTI_CLEAR_FLAG RESET: or SET Description: Clear the the COMP2 EXTI flag. Return value: __HAL_COMP_COMP2_EXTI_GENERATE_SWIT Description: 130/654 DOCID026682 Rev 3 None 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 DAC_OUT1 (PA4) connected to comparator 2 inverting input COMP_INVERTINGINPUT_DAC2 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 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 COMP_OUTPUT_NONE COMP2 output is not connected to other peripherals IS_COMP_OUTPUT COMP OutputLevel COMP_OUTPUTLEVEL_LOW 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: __COMP_CSR_CMPXOUT value: of Description: Select the COMP register CSR bit CMPxOUT corresponding to the selected COMP instance. Parameters: __HANDLE__: COMP handle Return value: __COMP_IS_ENABLED 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 132/654 DOCID026682 Rev 3 No External Interrupt trigger detection UM1816 HAL COMP Generic Driver External Interrupt Mode with Rising edge trigger detection COMP_TRIGGERMODE_IT_RISING COMP_TRIGGERMODE_IT_FALLING External Interrupt Mode with Falling edge trigger detection COMP_TRIGGERMODE_IT_RISING_FALLING External Interrupt Mode with Rising/Falling edge trigger detection IS_COMP_TRIGGERMODE COMP WindowMode 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 HAL COMP Extension Driver 7.1 HAL COMP Extension Driver 7.2 COMPEx Firmware driver defines 7.2.1 COMPEx COMPEx NonInvertingInput 134/654 COMP_NONINVERTINGINPUT_PB4 I/O pin PB4 connection to COMP2 noninverting input COMP_NONINVERTINGINPUT_PB5 I/O pin PB5 connection to COMP2 noninverting input COMP_NONINVERTINGINPUT_PB6 I/O pin PB6 connection to COMP2 noninverting input COMP_NONINVERTINGINPUT_PB7 I/O pin PB7 connection to COMP2 noninverting input COMP_NONINVERTINGINPUT_NONE In case of window mode: No I/O pin connection to COMP1 non-inverting input. Instead, connection to COMP2 non-inverting input. COMP_NONINVERTINGINPUT_PA0 I/O pin PA0 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PA1 I/O pin PA1 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PA2 I/O pin PA2 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PA3 I/O pin PA3 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PA4 I/O pin PA4 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PA5 I/O pin PA5 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PA6 I/O pin PA5 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PA7 I/O pin PA7 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PB0 I/O pin PB0 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PB1 I/O pin PB1 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PC0 I/O pin PC0 connection to COMP1 noninverting input DOCID026682 Rev 3 UM1816 COMP_NONINVERTINGINPUT_PC1 HAL COMP Extension Driver I/O pin PC1 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PC2 I/O pin PC2 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PC3 I/O pin PC3 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PC4 I/O pin PC4 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PC5 I/O pin PC5 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PB12 I/O pin PB12 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PB13 I/O pin PB13 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PB14 I/O pin PB14 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PB15 I/O pin PB15 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PE7 I/O pin PE7 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PE8 I/O pin PE8 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PE9 I/O pin PE9 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PE10 I/O pin PE10 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PF6 I/O pin PF6 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PF7 I/O pin PF7 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PF8 I/O pin PF8 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PF9 I/O pin PF9 connection to COMP1 noninverting input COMP_NONINVERTINGINPUT_PF10 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 UM1816 Description: Specifies whether Routing Interface (RI) needs to be configured for switches of comparator non-inverting input. Parameters: __HANDLE__: COMP handle. Return value: 136/654 DOCID026682 Rev 3 None. UM1816 HAL CORTEX Generic Driver 8 HAL CORTEX Generic Driver 8.1 HAL CORTEX Generic Driver 8.2 CORTEX Firmware driver registers structures 8.2.1 MPU_Region_InitTypeDef Data Fields uint8_t Enable uint8_t Number uint32_t BaseAddress uint8_t Size uint8_t SubRegionDisable uint8_t TypeExtField uint8_t AccessPermission uint8_t DisableExec uint8_t IsShareable uint8_t IsCacheable uint8_t IsBufferable Field Documentation uint8_t MPU_Region_InitTypeDef::Enable Specifies the status of the region. This parameter can be a value of CORTEX_MPU_Region_Enable uint8_t MPU_Region_InitTypeDef::Number Specifies the number of the region to protect. This parameter can be a value of CORTEX_MPU_Region_Number uint32_t MPU_Region_InitTypeDef::BaseAddress Specifies the base address of the region to protect. uint8_t MPU_Region_InitTypeDef::Size Specifies the size of the region to protect. This parameter can be a value of CORTEX_MPU_Region_Size uint8_t MPU_Region_InitTypeDef::SubRegionDisable Specifies the number of the subregion protection to disable. This parameter must be a number between Min_Data = 0x00 and Max_Data = 0xFF uint8_t MPU_Region_InitTypeDef::TypeExtField Specifies the TEX field level. This parameter can be a value of CORTEX_MPU_TEX_Levels uint8_t MPU_Region_InitTypeDef::AccessPermission Specifies the region access permission type. This parameter can be a value of CORTEX_MPU_Region_Permission_Attributes uint8_t MPU_Region_InitTypeDef::DisableExec Specifies the instruction access status. This parameter can be a value of CORTEX_MPU_Instruction_Access uint8_t MPU_Region_InitTypeDef::IsShareable Specifies the shareability status of the protected region. This parameter can be a value of CORTEX_MPU_Access_Shareable DOCID026682 Rev 3 137/654 HAL CORTEX Generic Driver UM1816 uint8_t MPU_Region_InitTypeDef::IsCacheable Specifies the cacheable status of the region protected. This parameter can be a value of CORTEX_MPU_Access_Cacheable uint8_t MPU_Region_InitTypeDef::IsBufferable Specifies the bufferable status of the protected region. This parameter can be a value of CORTEX_MPU_Access_Bufferable 8.3 CORTEX Firmware driver API description 8.3.1 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: 8.3.2 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: 8.3.3 138/654 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 HAL CORTEX Generic Driver priority 0 bits for subpriority 8.3.4 Return values None Notes 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 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. Return values 8.3.5 8.3.6 8.3.7 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 None Notes To configure interrupts priority correctly, the NVIC_PriorityGroupConfig() function should be called before. HAL_NVIC_DisableIRQ Function Name void HAL_NVIC_DisableIRQ (IRQn_Type IRQn) Function Description Disables a device specific interrupt in the NVIC interrupt controller. Parameters IRQn: External interrupt number This parameter can be an enumerator of IRQn_Type enumeration (For the complete STM32 Devices IRQ Channels list, please refer to the appropriate CMSIS device file (stm32l1xxxx.h)) Return values None HAL_NVIC_SystemReset Function Name void HAL_NVIC_SystemReset (void ) DOCID026682 Rev 3 139/654 HAL CORTEX Generic Driver Function Description Return values 8.3.8 8.3.9 8.3.10 8.3.11 UM1816 Initiates a system reset request to reset the MCU. HAL_SYSTICK_Config Function Name uint32_t HAL_SYSTICK_Config (uint32_t TicksNumb) Function Description Initializes the System Timer and its interrupt, and starts the System Tick Timer. Parameters TicksNumb: Specifies the ticks Number of ticks between two interrupts. Return values status - 0 Function succeeded. 1 Function failed. HAL_MPU_ConfigRegion Function Name void HAL_MPU_ConfigRegion (MPU_Region_InitTypeDef * MPU_Init) Function Description Initializes and configures the Region and the memory to be protected. Parameters MPU_Init: Pointer to a MPU_Region_InitTypeDef structure that contains the initialization and configuration information. Return values None HAL_NVIC_GetPriorityGrouping Function Name uint32_t HAL_NVIC_GetPriorityGrouping (void ) Function Description Gets the priority grouping field from the NVIC Interrupt Controller. Return values Priority grouping field (SCB->AIRCR [10:8] PRIGROUP field) HAL_NVIC_GetPriority Function Name void HAL_NVIC_GetPriority (IRQn_Type IRQn, uint32_t PriorityGroup, uint32_t * pPreemptPriority, uint32_t * pSubPriority) Function Description Gets the priority of an interrupt. Parameters 140/654 None 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 DOCID026682 Rev 3 UM1816 Return values 8.3.12 8.3.13 8.3.14 8.3.15 HAL CORTEX Generic Driver (starting from 0). pSubPriority: Pointer on the Subpriority value (starting from 0). None HAL_NVIC_SetPendingIRQ Function Name void HAL_NVIC_SetPendingIRQ (IRQn_Type IRQn) Function Description Sets Pending bit of an external interrupt. Parameters IRQn: External interrupt number This parameter can be an enumerator of IRQn_Type enumeration (For the complete STM32 Devices IRQ Channels list, please refer to the appropriate CMSIS device file (stm32l1xxxx.h)) Return values None HAL_NVIC_GetPendingIRQ Function Name uint32_t HAL_NVIC_GetPendingIRQ (IRQn_Type IRQn) Function Description Gets Pending Interrupt (reads the pending register in the NVIC and returns the pending bit for the specified interrupt). Parameters IRQn: External interrupt number This parameter can be an enumerator of IRQn_Type enumeration (For the complete STM32 Devices IRQ Channels list, please refer to the appropriate CMSIS device file (stm32l1xxxx.h)) Return values status - 0 Interrupt status is not pending. 1 Interrupt status is pending. HAL_NVIC_ClearPendingIRQ Function Name void HAL_NVIC_ClearPendingIRQ (IRQn_Type IRQn) Function Description Clears the pending bit of an external interrupt. Parameters IRQn: External interrupt number This parameter can be an enumerator of IRQn_Type enumeration (For the complete STM32 Devices IRQ Channels list, please refer to the appropriate CMSIS device file (stm32l1xxxx.h)) Return values None HAL_NVIC_GetActive Function Name uint32_t HAL_NVIC_GetActive (IRQn_Type IRQn) Function Description Gets active interrupt ( reads the active register in NVIC and returns the active bit). Parameters IRQn: External interrupt number This parameter can be an enumerator of IRQn_Type enumeration (For the complete STM32 Devices IRQ Channels list, please refer to the appropriate CMSIS device file (stm32l1xxxx.h)) Return values 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 8.3.17 8.3.18 HAL_SYSTICK_CLKSourceConfig Function Name void HAL_SYSTICK_CLKSourceConfig (uint32_t CLKSource) Function Description Configures the SysTick clock source. Parameters CLKSource: specifies the SysTick clock source. This parameter can be one of the following values: SYSTICK_CLKSOURCE_HCLK_DIV8: AHB clock divided by 8 selected as SysTick clock source.SYSTICK_CLKSOURCE_HCLK: AHB clock selected as SysTick clock source. Return values None HAL_SYSTICK_IRQHandler Function Name void HAL_SYSTICK_IRQHandler (void ) Function Description This function handles SYSTICK interrupt request. Return values None HAL_SYSTICK_Callback Function Name void HAL_SYSTICK_Callback (void ) Function Description SYSTICK callback. Return values None 8.4 CORTEX Firmware driver defines 8.4.1 CORTEX CORTEX MPU Instruction Access Bufferable MPU_ACCESS_BUFFERABLE MPU_ACCESS_NOT_BUFFERABLE CORTEX MPU Instruction Access Cacheable MPU_ACCESS_CACHEABLE MPU_ACCESS_NOT_CACHEABLE CORTEX MPU Instruction Access Shareable MPU_ACCESS_SHAREABLE MPU_ACCESS_NOT_SHAREABLE MPU HFNMI and PRIVILEGED Access control MPU_HFNMI_PRIVDEF_NONE MPU_HARDFAULT_NMI MPU_PRIVILEGED_DEFAULT 142/654 DOCID026682 Rev 3 UM1816 HAL CORTEX Generic Driver 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 143/654 HAL CORTEX Generic Driver MPU_REGION_SIZE_128KB UM1816 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 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 HAL CRC Generic Driver 9.1 HAL CRC Generic Driver 9.2 CRC Firmware driver registers structures 9.2.1 CRC_HandleTypeDef Data Fields CRC_TypeDef * Instance HAL_LockTypeDef Lock __IO HAL_CRC_StateTypeDef State Field Documentation CRC_TypeDef* CRC_HandleTypeDef::Instance Register base address HAL_LockTypeDef CRC_HandleTypeDef::Lock CRC locking object __IO HAL_CRC_StateTypeDef CRC_HandleTypeDef::State CRC communication state 9.3 CRC Firmware driver API description 9.3.1 How to use this driver The CRC HAL driver can be used as follows: 1. 2. 3. 9.3.2 Enable CRC AHB clock using __HAL_RCC_CRC_CLK_ENABLE(); Use HAL_CRC_Accumulate() function to compute the CRC value of a 32-bit data buffer using combination of the previous CRC value and the new one. Use HAL_CRC_Calculate() function to compute the CRC Value of a new 32-bit data buffer. This function resets the CRC computation unit before starting the computation to avoid getting wrong CRC values. Initialization and de-initialization functions This section provides functions allowing to: Initialize the CRC according to the specified parameters in the CRC_InitTypeDef and create the associated handle DeInitialize the CRC peripheral Initialize the CRC MSP DeInitialize CRC MSP This section contains the following APIs: 146/654 HAL_CRC_Init() HAL_CRC_DeInit() HAL_CRC_MspInit() DOCID026682 Rev 3 UM1816 HAL CRC Generic Driver 9.3.3 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: 9.3.4 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: 9.3.5 9.3.6 9.3.7 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 hcrc: pointer to a CRC_HandleTypeDef structure that contains the configuration information for CRC Return values HAL status HAL_CRC_DeInit Function Name HAL_StatusTypeDef HAL_CRC_DeInit (CRC_HandleTypeDef * hcrc) Function Description DeInitializes the CRC peripheral. Parameters hcrc: pointer to a CRC_HandleTypeDef structure that contains the configuration information for CRC Return values HAL status HAL_CRC_MspInit Function Name void HAL_CRC_MspInit (CRC_HandleTypeDef * hcrc) Function Description Initializes the CRC MSP. Parameters hcrc: pointer to a CRC_HandleTypeDef structure that contains the configuration information for CRC Return values None DOCID026682 Rev 3 147/654 HAL CRC Generic Driver 9.3.8 9.3.9 UM1816 HAL_CRC_MspDeInit Function Name void HAL_CRC_MspDeInit (CRC_HandleTypeDef * hcrc) Function Description DeInitializes the CRC MSP. Parameters hcrc: pointer to a CRC_HandleTypeDef structure that contains the configuration information for CRC Return values None HAL_CRC_Accumulate Function Name uint32_t HAL_CRC_Accumulate (CRC_HandleTypeDef * hcrc, uint32_t pBuffer, uint32_t BufferLength) Function Description Computes the 32-bit CRC of 32-bit data buffer using combination of the previous CRC value and the new one. Parameters Return values 9.3.10 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 9.3.12 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 HAL_CRC_GetState Function Name HAL_CRC_StateTypeDef HAL_CRC_GetState (CRC_HandleTypeDef * hcrc) Function Description Returns the CRC state. Parameters hcrc: pointer to a CRC_HandleTypeDef structure that contains the configuration information for CRC Return values HAL state HAL_CRC_Accumulate Function Name 148/654 32-bit CRC HAL_CRC_Calculate 9.3.11 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) uint32_t HAL_CRC_Accumulate (CRC_HandleTypeDef * hcrc, 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 9.3.13 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 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 CRC Firmware driver defines 9.4.1 CRC CRC Exported Macros __HAL_CRC_RESET_HANDLE_STATE Description: Reset CRC handle state. Parameters: __HANDLE__: CRC handle Return value: __HAL_CRC_DR_RESET None Description: Resets CRC Data Register. Parameters: __HANDLE__: CRC handle Return value: __HAL_CRC_SET_IDR None Description: Stores a 8-bit data in the Independent DOCID026682 Rev 3 149/654 HAL CRC Generic Driver UM1816 Data(ID) register. Parameters: __HANDLE__: CRC handle __VALUE__: 8-bit value to be stored in the ID register Return value: __HAL_CRC_GET_IDR None Description: Returns the 8-bit data stored in the Independent Data(ID) register. Parameters: __HANDLE__: CRC handle Return value: 150/654 8-bit: value of the ID register 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 10.2.2 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 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 UM1816 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 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: 10.3.2 HAL_CRYP_Init() HAL_CRYP_DeInit() HAL_CRYP_MspInit() HAL_CRYP_MspDeInit() 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: 152/654 HAL_CRYP_AESECB_Encrypt() HAL_CRYP_AESCBC_Encrypt() DOCID026682 Rev 3 UM1816 HAL CRYP Generic Driver 10.3.3 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() 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: 10.3.4 HAL_CRYP_ErrorCallback() HAL_CRYP_InCpltCallback() HAL_CRYP_OutCpltCallback() CRYP IRQ handler management This section provides CRYP IRQ handler function. This section contains the following APIs: 10.3.5 HAL_CRYP_IRQHandler() Peripheral State functions This subsection permits to get in run-time the status of the peripheral. This section contains the following APIs: 10.3.6 HAL_CRYP_GetState() HAL_CRYP_Init Function Name HAL_StatusTypeDef HAL_CRYP_Init (CRYP_HandleTypeDef * hcryp) Function Description Initializes the CRYP according to the specified parameters in the CRYP_InitTypeDef and creates the associated handle. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module Return values HAL status DOCID026682 Rev 3 153/654 HAL CRYP Generic Driver 10.3.7 10.3.8 10.3.9 10.3.10 UM1816 HAL_CRYP_DeInit Function Name HAL_StatusTypeDef HAL_CRYP_DeInit (CRYP_HandleTypeDef * hcryp) Function Description DeInitializes the CRYP peripheral. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module Return values HAL status HAL_CRYP_MspInit Function Name void HAL_CRYP_MspInit (CRYP_HandleTypeDef * hcryp) Function Description Initializes the CRYP MSP. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module Return values None HAL_CRYP_MspDeInit Function Name void HAL_CRYP_MspDeInit (CRYP_HandleTypeDef * hcryp) Function Description DeInitializes CRYP MSP. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module Return values None HAL_CRYP_AESECB_Encrypt Function Name HAL_StatusTypeDef HAL_CRYP_AESECB_Encrypt (CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t Size, uint8_t * pCypherData, uint32_t Timeout) Function Description Initializes the CRYP peripheral in AES ECB encryption mode then encrypt pPlainData. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module pPlainData: Pointer to the plaintext buffer (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 Return values 10.3.11 154/654 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 DOCID026682 Rev 3 UM1816 HAL CRYP Generic Driver 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 HAL status Return values 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 HAL status Return values 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 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 Return values 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 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 Return values 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 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 Return values 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 10.3.17 156/654 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 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 DOCID026682 Rev 3 UM1816 Return values 10.3.18 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 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) HAL status Return values 10.3.20 HAL status HAL_CRYP_AESCTR_Encrypt_IT 10.3.19 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_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 10.3.21 UM1816 Size: Length of the plaintext buffer, must be a multiple of 16 pPlainData: Pointer to the plaintext buffer (aligned on u32) HAL status HAL_CRYP_AESCTR_Decrypt_IT Function Name HAL_StatusTypeDef HAL_CRYP_AESCTR_Decrypt_IT (CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData, uint16_t Size, uint8_t * pPlainData) Function Description Initializes the CRYP peripheral in AES CTR decryption mode using Interrupt. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module pCypherData: Pointer to the cyphertext buffer (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 Return values 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 10.3.23 HAL status HAL_CRYP_AESCBC_Encrypt_DMA Function Name HAL_StatusTypeDef HAL_CRYP_AESCBC_Encrypt_DMA (CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t Size, uint8_t * pCypherData) Function Description Initializes the CRYP peripheral in AES CBC encryption mode using DMA. Parameters 158/654 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) 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) DOCID026682 Rev 3 UM1816 HAL CRYP Generic Driver Return values 10.3.24 Function Name HAL_StatusTypeDef HAL_CRYP_AESCTR_Encrypt_DMA (CRYP_HandleTypeDef * hcryp, uint8_t * pPlainData, uint16_t Size, uint8_t * pCypherData) Function Description Initializes the CRYP peripheral in AES CTR encryption mode using DMA. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module pPlainData: Pointer to the plaintext buffer (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 HAL_CRYP_AESECB_Decrypt_DMA Function Name HAL_StatusTypeDef HAL_CRYP_AESECB_Decrypt_DMA (CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData, uint16_t Size, uint8_t * pPlainData) Function Description Initializes the CRYP peripheral in AES ECB decryption mode using DMA. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module pCypherData: Pointer to the cyphertext buffer (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 Return values 10.3.26 HAL status HAL_CRYP_AESCTR_Encrypt_DMA Return values 10.3.25 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 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 Return values DOCID026682 Rev 3 159/654 HAL CRYP Generic Driver 10.3.27 UM1816 HAL_CRYP_AESCTR_Decrypt_DMA Function Name HAL_StatusTypeDef HAL_CRYP_AESCTR_Decrypt_DMA (CRYP_HandleTypeDef * hcryp, uint8_t * pCypherData, uint16_t Size, uint8_t * pPlainData) Function Description Initializes the CRYP peripheral in AES CTR decryption mode using DMA. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module pCypherData: Pointer to the cyphertext buffer (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 Return values 10.3.28 10.3.29 10.3.30 10.3.31 160/654 HAL_CRYP_ErrorCallback Function Name void HAL_CRYP_ErrorCallback (CRYP_HandleTypeDef * hcryp) Function Description CRYP error callback. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module Return values None 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 HAL_CRYP_OutCpltCallback Function Name void HAL_CRYP_OutCpltCallback (CRYP_HandleTypeDef * hcryp) Function Description Output transfer completed callback. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module Return values None HAL_CRYP_IRQHandler Function Name void HAL_CRYP_IRQHandler (CRYP_HandleTypeDef * hcryp) Function Description This function handles CRYP interrupt request. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that DOCID026682 Rev 3 UM1816 HAL CRYP Generic Driver contains the configuration information for CRYP module Return values 10.3.32 None HAL_CRYP_GetState Function Name HAL_CRYP_STATETypeDef HAL_CRYP_GetState (CRYP_HandleTypeDef * hcryp) Function Description Returns the CRYP state. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module Return values HAL state 10.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 Computation Complete interrupt CRYP_IT_ERR 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 UM1816 CRYP Exported Macros __HAL_CRYP_RESET_HANDLE_STATE Description: Reset CRYP handle state. Parameters: __HANDLE__: specifies the CRYP handle. Return value: __HAL_CRYP_ENABLE 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, AESCBC, AES-CTR, DES-ECB, DES-CBC,... Parameters: __HANDLE__: specifies the CRYP handle. __MODE__: The algorithm mode. Return value: __HAL_CRYP_GET_FLAG None Description: Check whether the specified CRYP flag is set or not. Parameters: 162/654 __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 DOCID026682 Rev 3 UM1816 HAL CRYP Generic Driver Return value: __HAL_CRYP_CLEAR_FLAG 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: __HAL_CRYP_ENABLE_IT Enable the CRYP interrupt. Parameters: __HANDLE__: specifies the CRYP handle. __INTERRUPT__: CRYP Interrupt. Return value: None Description: __HAL_CRYP_DISABLE_IT Disable the CRYP interrupt. Parameters: __HANDLE__: specifies the CRYP handle. __INTERRUPT__: CRYP interrupt. Return value: __HAL_CRYP_GET_IT_SOURCE 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 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: __HAL_CRYP_CLEAR_IT 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 CRYP Private Defines CRYP_ALGO_CHAIN_MASK 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: 11.2.2 HAL_CRYPEx_ComputationCpltCallback() HAL_CRYPEx_ComputationCpltCallback Function Name void HAL_CRYPEx_ComputationCpltCallback (CRYP_HandleTypeDef * hcryp) Function Description Computation completed callbacks. Parameters hcryp: pointer to a CRYP_HandleTypeDef structure that contains the configuration information for CRYP module Return values 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 12.2.2 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 DAC_ChannelConfTypeDef Data Fields uint32_t DAC_Trigger uint32_t DAC_OutputBuffer Field Documentation 166/654 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 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. 2. DAC channel1 with DAC_OUT1 (PA4) as output DAC channel2 with DAC_OUT2 (PA5) as output DAC Triggers Digital to Analog conversion can be non-triggered using DAC_TRIGGER_NONE and DAC_OUT1/DAC_OUT2 is available once writing to DHRx register. Digital to Analog conversion can be triggered by: 1. 2. 3. External event: EXTI Line 9 (any GPIOx_PIN_9) using DAC_TRIGGER_EXT_IT9. The used pin (GPIOx_PIN_9) must be configured in input mode. Timers TRGO: TIM2, TIM4, TIM6, TIM7, TIM9 (DAC_Trigger_T2_TRGO, DAC_Trigger_T4_TRGO...) Software using DAC_TRIGGER_SOFTWARE DAC Buffer mode feature Each DAC channel integrates an output buffer that can be used to reduce the output impedance, and to drive external loads directly without having to add an external operational amplifier. To enable, the output buffer use sConfig.DAC_OutputBuffer = DAC_OUTPUTBUFFER_ENABLE; Refer to the device datasheet for more details about output impedance value with and without output buffer. DAC 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() UM1816 DAC data format The DAC data format can be: 1. 2. 3. 8-bit right alignment using DAC_ALIGN_8B_R 12-bit left alignment using DAC_ALIGN_12B_L 12-bit right alignment using DAC_ALIGN_12B_R 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. 2. 12.3.2 DAC channel1 : mapped on DMA1 channel2 which must be already configured 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 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 168/654 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 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: 12.3.4 HAL_DAC_Init() HAL_DAC_DeInit() HAL_DAC_MspInit() HAL_DAC_MspDeInit() 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 UM1816 Get result of conversion. This section contains the following APIs: 12.3.5 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() 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: 12.3.6 HAL_DAC_ConfigChannel() HAL_DAC_SetValue() 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: 12.3.7 12.3.8 HAL_DAC_GetState() HAL_DAC_GetError() HAL_DAC_Init Function Name HAL_StatusTypeDef HAL_DAC_Init (DAC_HandleTypeDef * hdac) Function Description Initializes the DAC peripheral according to the specified parameters in the DAC_InitStruct. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values HAL status HAL_DAC_DeInit Function Name 170/654 HAL_StatusTypeDef HAL_DAC_DeInit (DAC_HandleTypeDef * hdac) DOCID026682 Rev 3 UM1816 12.3.9 12.3.10 12.3.11 Function Description HAL DAC Generic Driver Deinitializes the DAC peripheral registers to their default reset values. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values HAL status HAL_DAC_MspInit 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 HAL_DAC_MspDeInit Function Name void HAL_DAC_MspDeInit (DAC_HandleTypeDef * hdac) Function Description DeInitializes the DAC MSP. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values None HAL_DAC_Start Function Name HAL_StatusTypeDef HAL_DAC_Start (DAC_HandleTypeDef * hdac, uint32_t Channel) Function Description Enables DAC and starts conversion of channel. Parameters Return values 12.3.12 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 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 UM1816 HAL_DAC_Start_DMA Function Name HAL_StatusTypeDef HAL_DAC_Start_DMA (DAC_HandleTypeDef * hdac, uint32_t Channel, uint32_t * pData, uint32_t Length, uint32_t Alignment) Function Description Enables DAC and starts conversion of channel. Parameters Return values 12.3.14 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 HAL status 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 Return values 172/654 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_DAC_GetValue 12.3.16 HAL status HAL_DAC_Stop_DMA 12.3.15 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 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 The selected DAC channel data output value. HAL_DAC_IRQHandler DOCID026682 Rev 3 UM1816 12.3.17 12.3.18 12.3.19 12.3.20 12.3.21 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 HAL_DAC_ConvCpltCallbackCh1 Function Name void HAL_DAC_ConvCpltCallbackCh1 (DAC_HandleTypeDef * hdac) Function Description Conversion complete callback in non blocking mode for Channel1. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values None HAL_DAC_ConvHalfCpltCallbackCh1 Function Name void HAL_DAC_ConvHalfCpltCallbackCh1 (DAC_HandleTypeDef * hdac) Function Description Conversion half DMA transfer callback in non blocking mode for Channel1. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values None HAL_DAC_ErrorCallbackCh1 Function Name void HAL_DAC_ErrorCallbackCh1 (DAC_HandleTypeDef * hdac) Function Description Error DAC callback for Channel1. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values None HAL_DAC_DMAUnderrunCallbackCh1 Function Name void HAL_DAC_DMAUnderrunCallbackCh1 (DAC_HandleTypeDef * hdac) Function Description DMA underrun DAC callback for channel1. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values None 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. HAL status Return values 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 12.3.23 12.3.24 174/654 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 HAL_DAC_GetState Function Name HAL_DAC_StateTypeDef HAL_DAC_GetState (DAC_HandleTypeDef * hdac) Function Description return the DAC state Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values HAL state HAL_DAC_GetError Function Name uint32_t HAL_DAC_GetError (DAC_HandleTypeDef * hdac) Function Description Return the DAC error code. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values DAC Error Code DOCID026682 Rev 3 UM1816 12.3.25 HAL DAC Generic Driver 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 12.3.26 Function Name HAL_StatusTypeDef HAL_DAC_SetValue (DAC_HandleTypeDef * hdac, uint32_t Channel, uint32_t Alignment, uint32_t Data) Function Description Set the specified data holding register value for DAC channel. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Channel: The selected DAC channel. This parameter can be one of the following values: DAC_CHANNEL_1: DAC Channel1 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 Return values 12.3.28 HAL status HAL_DAC_SetValue 12.3.27 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_DAC_GetState Function Name HAL_DAC_StateTypeDef HAL_DAC_GetState (DAC_HandleTypeDef * hdac) Function Description return the DAC state Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values HAL state HAL_DAC_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 DMA error DAC Exported Macros __HAL_DAC_RESET_HANDLE_STATE Description: Reset DAC handle state. Parameters: __HANDLE__: specifies the DAC handle. Return value: __HAL_DAC_ENABLE None Description: Enable the DAC channel. Parameters: __HANDLE__: specifies the DAC handle. __DAC_Channel__: specifies the DAC channel Return value: __HAL_DAC_DISABLE None Description: Disable the DAC channel. Parameters: 176/654 __HANDLE__: specifies the DAC handle __DAC_Channel__: specifies the DAC DOCID026682 Rev 3 UM1816 HAL DAC Generic Driver channel. Return value: None Description: __HAL_DAC_ENABLE_IT 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: __HAL_DAC_DISABLE_IT 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: __HAL_DAC_GET_IT_SOURCE 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 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: __HAL_DAC_CLEAR_FLAG 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 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 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 Conversion is automatic once the DAC1_DHRxxxx register has been loaded, and not by external trigger DAC_TRIGGER_T6_TRGO TIM6 TRGO selected as external conversion trigger for DAC channel DAC_TRIGGER_T7_TRGO TIM7 TRGO selected as external conversion trigger for DAC channel DAC_TRIGGER_T9_TRGO TIM9 TRGO selected as external conversion trigger for DAC channel DAC_TRIGGER_T2_TRGO TIM2 TRGO selected as external conversion trigger for DAC channel DAC_TRIGGER_T4_TRGO TIM4 TRGO selected as external conversion trigger for DAC channel DAC_TRIGGER_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 13.2.2 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. 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: 13.2.3 13.2.4 HAL_DACEx_DualGetValue() HAL_DACEx_TriangleWaveGenerate() HAL_DACEx_NoiseWaveGenerate() HAL_DACEx_DualSetValue() HAL_DACEx_ConvCpltCallbackCh2() HAL_DACEx_ConvHalfCpltCallbackCh2() HAL_DACEx_ErrorCallbackCh2() HAL_DACEx_DMAUnderrunCallbackCh2() 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. HAL_DACEx_TriangleWaveGenerate Function Name 180/654 HAL_StatusTypeDef HAL_DACEx_TriangleWaveGenerate (DAC_HandleTypeDef * hdac, uint32_t Channel, uint32_t DOCID026682 Rev 3 UM1816 HAL DAC Extension Driver Amplitude) Function Description Enables or disables the selected DAC channel wave generation. Parameters Return values 13.2.5 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 HAL status HAL_DACEx_NoiseWaveGenerate Function Name HAL_StatusTypeDef HAL_DACEx_NoiseWaveGenerate (DAC_HandleTypeDef * hdac, uint32_t Channel, uint32_t Amplitude) Function Description Enables or disables the selected DAC channel wave generation. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Channel: The selected DAC channel. This parameter can be one of the following values: DAC_CHANNEL_1 / DAC_CHANNEL_2 Amplitude: Unmask DAC channel LFSR for noise wave generation. This parameter can be one of the following 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 13.2.6 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_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 13.2.7 13.2.8 hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Alignment: Specifies the data alignment for dual channel DAC. This parameter can be one of the following values: DAC_ALIGN_8B_R: 8bit right data alignment selected DAC_ALIGN_12B_L: 12bit left data alignment selected DAC_ALIGN_12B_R: 12bit right data alignment selected Data1: Data for DAC Channel2 to be loaded in the selected data holding register. Data2: Data for DAC Channel1 to be loaded in the selected data holding register. Return values HAL status Notes In dual mode, a unique register access is required to write in both DAC channels at the same time. HAL_DACEx_ConvCpltCallbackCh2 Function Name void HAL_DACEx_ConvCpltCallbackCh2 (DAC_HandleTypeDef * hdac) Function Description Conversion complete callback in non blocking mode for Channel2. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values None HAL_DACEx_ConvHalfCpltCallbackCh2 Function Name 182/654 HAL status void HAL_DACEx_ConvHalfCpltCallbackCh2 (DAC_HandleTypeDef * hdac) DOCID026682 Rev 3 UM1816 13.2.9 13.2.10 Function Description HAL DAC Extension Driver Conversion half DMA transfer callback in non blocking mode for Channel2. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values None HAL_DACEx_ErrorCallbackCh2 Function Name void HAL_DACEx_ErrorCallbackCh2 (DAC_HandleTypeDef * hdac) Function Description Error DAC callback for Channel2. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values None HAL_DACEx_DMAUnderrunCallbackCh2 Function Name void HAL_DACEx_DMAUnderrunCallbackCh2 (DAC_HandleTypeDef * hdac) Function Description DMA underrun DAC callback for channel2. Parameters hdac: pointer to a DAC_HandleTypeDef structure that contains the configuration information for the specified DAC. Return values None 13.3 DACEx Firmware driver defines 13.3.1 DACEx DACEx lfsrunmask triangleamplitude DAC_LFSRUNMASK_BIT0 Unmask DAC channel LFSR bit0 for noise wave generation DAC_LFSRUNMASK_BITS1_0 Unmask DAC channel LFSR bit[1:0] for noise wave generation DAC_LFSRUNMASK_BITS2_0 Unmask DAC channel LFSR bit[2:0] for noise wave generation DAC_LFSRUNMASK_BITS3_0 Unmask DAC channel LFSR bit[3:0] for noise wave generation DAC_LFSRUNMASK_BITS4_0 Unmask DAC channel LFSR bit[4:0] for noise wave generation DAC_LFSRUNMASK_BITS5_0 Unmask DAC channel LFSR bit[5:0] for noise wave generation DAC_LFSRUNMASK_BITS6_0 Unmask DAC channel LFSR bit[6:0] for noise wave generation DAC_LFSRUNMASK_BITS7_0 Unmask DAC channel LFSR bit[7:0] for noise wave generation DOCID026682 Rev 3 183/654 HAL DAC Extension Driver DAC_LFSRUNMASK_BITS8_0 DAC_LFSRUNMASK_BITS9_0 Unmask DAC channel LFSR bit[9:0] for noise wave generation DAC_LFSRUNMASK_BITS10_0 Unmask DAC channel LFSR bit[10:0] for noise wave generation DAC_LFSRUNMASK_BITS11_0 Unmask DAC channel LFSR bit[11:0] for noise wave generation DAC_TRIANGLEAMPLITUDE_1 Select max triangle amplitude of 1 DAC_TRIANGLEAMPLITUDE_3 Select max triangle amplitude of 3 DAC_TRIANGLEAMPLITUDE_7 Select max triangle amplitude of 7 DAC_TRIANGLEAMPLITUDE_15 Select max triangle amplitude of 15 DAC_TRIANGLEAMPLITUDE_31 Select max triangle amplitude of 31 DAC_TRIANGLEAMPLITUDE_63 Select max triangle amplitude of 63 DAC_TRIANGLEAMPLITUDE_127 Select max triangle amplitude of 127 DAC_TRIANGLEAMPLITUDE_255 Select max triangle amplitude of 255 DAC_TRIANGLEAMPLITUDE_511 Select max triangle amplitude of 511 DAC_TRIANGLEAMPLITUDE_1023 Select max triangle amplitude of 1023 DAC_TRIANGLEAMPLITUDE_2047 Select max triangle amplitude of 2047 DAC_TRIANGLEAMPLITUDE_4095 Select max triangle amplitude of 4095 IS_DAC_LFSR_UNMASK_TRIANGLE_AMPLITUDE DACEx wave generation DAC_WAVE_NOISE DAC_WAVE_TRIANGLE 184/654 UM1816 Unmask DAC channel LFSR bit[8:0] for noise wave generation 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 14.2.2 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 __DMA_HandleTypeDef DOCID026682 Rev 3 185/654 HAL DMA Generic Driver Data Fields UM1816 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 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. 2. 3. 4. 186/654 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. 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. 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 In Memory-to-Memory transfer mode, Circular mode is not allowed. 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: 14.3.3 HAL_DMA_Init() HAL_DMA_DeInit() 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: 14.3.4 HAL_DMA_Start() HAL_DMA_Start_IT() HAL_DMA_Abort() HAL_DMA_PollForTransfer() HAL_DMA_IRQHandler() State and Errors functions This subsection provides functions allowing to Check the DMA state Get error code This section contains the following APIs: 14.3.5 14.3.6 14.3.7 HAL_DMA_GetState() HAL_DMA_GetError() HAL_DMA_Init Function Name HAL_StatusTypeDef HAL_DMA_Init (DMA_HandleTypeDef * hdma) Function Description Initializes the DMA according to the specified parameters in the DMA_InitTypeDef and create the associated handle. Parameters hdma: Pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA Channel. Return values HAL status HAL_DMA_DeInit Function Name HAL_StatusTypeDef HAL_DMA_DeInit (DMA_HandleTypeDef * hdma) Function Description DeInitializes the DMA peripheral. Parameters hdma: pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA Channel. Return values HAL status HAL_DMA_Start Function Name 188/654 HAL_StatusTypeDef HAL_DMA_Start (DMA_HandleTypeDef * hdma, uint32_t SrcAddress, uint32_t DstAddress, uint32_t DataLength) DOCID026682 Rev 3 UM1816 HAL DMA Generic Driver Function Description Starts the DMA Transfer. Parameters Return values 14.3.8 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 14.3.10 HAL status HAL_DMA_Start_IT 14.3.9 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 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 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 HAL status Notes 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. 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 14.3.11 14.3.12 14.3.13 UM1816 CompleteLevel: Specifies the DMA level complete. Timeout: Timeout duration. HAL status HAL_DMA_IRQHandler Function Name void HAL_DMA_IRQHandler (DMA_HandleTypeDef * hdma) Function Description Handles DMA interrupt request. Parameters hdma: pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA Channel. Return values None 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 HAL_DMA_GetError Function Name uint32_t HAL_DMA_GetError (DMA_HandleTypeDef * hdma) Function Description Return the DMA error code. Parameters hdma: : pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA Channel. Return values 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. Parameters: __HANDLE__: DMA handle. Return value: __HAL_DMA_ENABLE None Description: Enable the specified DMA Channel. Parameters: __HANDLE__: DMA handle Return value: __HAL_DMA_DISABLE None. Description: Disable the specified DMA Channel. Parameters: __HANDLE__: DMA handle Return value: __HAL_DMA_ENABLE_IT None. Description: Enables the specified DMA Channel interrupts. 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: __HAL_DMA_DISABLE_IT None Description: Disables the specified DMA Channel interrupts. Parameters: __HANDLE__: DMA handle DOCID026682 Rev 3 191/654 HAL DMA Generic Driver 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: __HAL_DMA_GET_IT_SOURCE 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). 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 192/654 DOCID026682 Rev 3 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 UM1816 Priority level : Low DMA_PRIORITY_MEDIUM Priority level : Medium DMA_PRIORITY_HIGH 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 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: __HAL_DMA_GET_HT_FLAG_INDEX The: specified transfer complete flag index. Description: Returns the current DMA Channel half transfer complete flag. Parameters: __HANDLE__: DMA handle Return value: __HAL_DMA_GET_TE_FLAG_INDEX The: specified half transfer complete flag index. Description: Returns the current DMA Channel transfer error flag. Parameters: __HANDLE__: DMA handle Return value: __HAL_DMA_GET_FLAG 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 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: __HAL_DMA_CLEAR_FLAG 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: 196/654 None 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: 16.3.2 Flash memory read operations Flash memory program/erase operations Read / write protections Prefetch on I-Code Option Bytes programming 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: 16.3.3 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 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. 2. 3. 16.3.4 Call the HAL_FLASH_Unlock() function to enable the flash control register and program memory access. Call the desired function to erase page or program data. Call the HAL_FLASH_Lock() to disable the flash program memory access (recommended to protect the FLASH memory against possible unwanted operation). 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. 2. 3. 4. Call the HAL_FLASH_OB_Unlock() function to enable the Flash option control register access. Call the following functions to program the desired option bytes. HAL_FLASHEx_OBProgram(FLASH_OBProgramInitTypeDef *pOBInit); 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. 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. 2. 16.3.5 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. 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. * Peripheral Control functions This subsection provides a set of functions allowing to control the FLASH memory operations. This section contains the following APIs: 16.3.6 HAL_FLASH_Unlock() HAL_FLASH_Lock() HAL_FLASH_OB_Unlock() HAL_FLASH_OB_Lock() HAL_FLASH_OB_Launch() 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: 16.3.7 16.3.8 HAL_FLASH_GetError() 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 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). 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 16.3.9 16.3.10 200/654 UM1816 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 HAL_FLASH_EndOfOperationCallback Function Name void HAL_FLASH_EndOfOperationCallback (uint32_t ReturnValue) Function Description FLASH end of operation interrupt callback. Parameters ReturnValue: The value saved in this parameter depends on the ongoing 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 Return values none HAL_FLASH_OperationErrorCallback Function Name void HAL_FLASH_OperationErrorCallback (uint32_t ReturnValue) Function Description FLASH operation error interrupt callback. DOCID026682 Rev 3 UM1816 16.3.11 16.3.12 16.3.13 16.3.14 16.3.15 16.3.16 16.3.17 HAL FLASH Generic Driver Parameters 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 Return values none HAL_FLASH_IRQHandler Function Name void HAL_FLASH_IRQHandler (void ) Function Description This function handles FLASH interrupt request. Return values None HAL_FLASH_Unlock Function Name HAL_StatusTypeDef HAL_FLASH_Unlock (void ) Function Description Unlock the FLASH control register access. Return values HAL Status HAL_FLASH_Lock Function Name HAL_StatusTypeDef HAL_FLASH_Lock (void ) Function Description Locks the FLASH control register access. Return values HAL Status HAL_FLASH_OB_Unlock Function Name HAL_StatusTypeDef HAL_FLASH_OB_Unlock (void ) Function Description Unlock the FLASH Option Control Registers access. Return values HAL Status HAL_FLASH_OB_Lock Function Name HAL_StatusTypeDef HAL_FLASH_OB_Lock (void ) Function Description Lock the FLASH Option Control Registers access. Return values HAL Status HAL_FLASH_OB_Launch Function Name HAL_StatusTypeDef HAL_FLASH_OB_Launch (void ) Function Description Launch the option byte loading. Return values HAL_StatusTypeDef HAL Status 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 Busy flag FLASH_FLAG_EOP FLASH End of Programming 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 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 __HAL_FLASH_DISABLE_IT none Description: Disable the specified FLASH interrupt. Parameters: __INTERRUPT__: : FLASH interrupt This parameter can be any combination of the following values: FLASH_IT_EOP: End of FLASH Operation Interrupt FLASH_IT_ERR: Error Interrupt Return value: none Description: __HAL_FLASH_GET_FLAG Get the specified FLASH flag status. 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: __HAL_FLASH_CLEAR_FLAG The: new state of __FLAG__ (SET or RESET). 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 End of programming interrupt source FLASH_IT_ERR Error interrupt source FLASH Keys FLASH_PDKEY1 Flash power down key1 FLASH_PDKEY2 Flash power down key2: used with FLASH_PDKEY1 to unlock the RUN_PD bit in FLASH_ACR FLASH_PEKEY1 Flash program erase key1 FLASH_PEKEY2 Flash program erase key: used with FLASH_PEKEY2 to unlock the write access to the FLASH_PECR register and data EEPROM FLASH_PRGKEY1 Flash program memory key1 FLASH_PRGKEY2 Flash program memory key2: used with FLASH_PRGKEY2 to unlock the program memory FLASH_OPTKEY1 Flash option key1 FLASH_OPTKEY2 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 17.2.2 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) 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 206/654 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 DOCID026682 Rev 3 UM1816 HAL FLASH Extension Driver 17.2.3 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 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: 17.3.2 HAL_FLASHEx_Erase() HAL_FLASHEx_Erase_IT() Option Bytes Programming functions Any operation of erase or program should follow these steps: 1. 2. 3. 4. Call the HAL_FLASH_OB_Unlock() function to enable the Flash option control register access. 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. 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. 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. 2. 3. 4. 5. 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. In order to activate the PcROP (change the function of the nWRPi option bits), the SPRMOD option bit must be activated. 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. 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 PcROP is available only in STM32L151xBA, STM32L152xBA, STM32L151xC, STM32L152xC & STM32L162xC devices. This section contains the following APIs: 17.3.3 HAL_FLASHEx_OBProgram() HAL_FLASHEx_OBGetConfig() HAL_FLASHEx_AdvOBProgram() HAL_FLASHEx_AdvOBGetConfig() DATA EEPROM Programming functions Any operation of erase or program should follow these steps: 1. 2. 3. 208/654 Call the HAL_FLASHEx_DATAEEPROM_Unlock() function to enable the data EEPROM access and Flash program erase control register access. Call the desired function to erase or program data. 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). DOCID026682 Rev 3 UM1816 HAL FLASH Extension Driver This section contains the following APIs: 17.3.4 HAL_FLASHEx_DATAEEPROM_Unlock() HAL_FLASHEx_DATAEEPROM_Lock() HAL_FLASHEx_DATAEEPROM_Erase() HAL_FLASHEx_DATAEEPROM_Program() HAL_FLASHEx_DATAEEPROM_EnableFixedTimeProgram() HAL_FLASHEx_DATAEEPROM_DisableFixedTimeProgram() 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 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) Return values 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 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.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 17.3.7 17.3.8 17.3.9 17.3.10 17.3.11 pOBInit: pointer to an FLASH_OBInitStruct structure that contains the configuration information for the programming. HAL_StatusTypeDef HAL Status HAL_FLASHEx_OBGetConfig Function Name void HAL_FLASHEx_OBGetConfig (FLASH_OBProgramInitTypeDef * pOBInit) Function Description Get the Option byte configuration. Parameters pOBInit: pointer to an FLASH_OBInitStruct structure that contains the configuration information for the programming. Return values None HAL_FLASHEx_AdvOBProgram Function Name HAL_StatusTypeDef HAL_FLASHEx_AdvOBProgram (FLASH_AdvOBProgramInitTypeDef * pAdvOBInit) Function Description Program option bytes. Parameters pAdvOBInit: pointer to an FLASH_AdvOBProgramInitTypeDef structure that contains the configuration information for the programming. Return values HAL_StatusTypeDef HAL Status Notes This function can be used only for Cat2 & Cat3 devices for PCROP and Cat4 & Cat5 for BFB2. HAL_FLASHEx_AdvOBGetConfig Function Name void HAL_FLASHEx_AdvOBGetConfig (FLASH_AdvOBProgramInitTypeDef * pAdvOBInit) Function Description Get the OBEX byte configuration. Parameters pAdvOBInit: pointer to an FLASH_AdvOBProgramInitTypeDef structure that contains the configuration information for the programming. Return values None Notes This function can be used only for Cat2 & Cat3 devices for PCROP and Cat4 & Cat5 for BFB2. 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 HAL_FLASHEx_DATAEEPROM_Lock Function Name 210/654 UM1816 HAL_StatusTypeDef HAL_FLASHEx_DATAEEPROM_Lock DOCID026682 Rev 3 UM1816 HAL FLASH Extension Driver (void ) 17.3.12 17.3.13 Function Description Locks the Data memory and FLASH_PECR register access. Return values 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 FLASH Status: The returned value can be: FLASH_ERROR_PROGRAM, HAL_FLASH_ERROR_WRP, FLASH_COMPLETE or FLASH_TIMEOUT. Notes 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). 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 HAL_StatusTypeDef HAL Status Notes 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_StatusTypeDef HAL Status HAL_FLASHEx_DATAEEPROM_EnableFixedTimeProgram Function Name void HAL_FLASHEx_DATAEEPROM_EnableFixedTimeProgram (void ) DOCID026682 Rev 3 211/654 HAL FLASH Extension Driver Function Description Return values 17.3.15 UM1816 Enable DATA EEPROM fixed Time programming (2*Tprog). None 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 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: __HAL_FLASH_GET_LATENCY none Description: Get the FLASH Latency. Return value: 212/654 DOCID026682 Rev 3 FLASH: Latency This parameter can be one of the following values: FLASH_LATENCY_0: FLASH Zero Latency cycle FLASH_LATENCY_1: UM1816 HAL FLASH Extension Driver FLASH One Latency cycle __HAL_FLASH_ACC64_ENABLE Description: Enable the FLASH 64-bit access. Return value: none Notes: __HAL_FLASH_ACC64_DISABLE 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: __HAL_FLASH_PREFETCH_BUFFER_ENABLE Read access 32 bit is used To reset this bit, the LATENCY should be zero wait state and the prefetch off. Description: Enable the FLASH prefetch buffer. Return value: __HAL_FLASH_PREFETCH_BUFFER_DISABLE none Description: Disable the FLASH prefetch buffer. Return value: __HAL_FLASH_SLEEP_POWERDOWN_ENABLE none Description: Enable the FLASH power down during Sleep mode. Return value: __HAL_FLASH_SLEEP_POWERDOWN_DISABLE none Description: Disable the FLASH power down during Sleep mode. Return value: DOCID026682 Rev 3 213/654 HAL FLASH Extension Driver UM1816 __HAL_FLASH_POWER_DOWN_ENABLE 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 BOR Reset threshold levels for 1.7V - 1.8V VDD power supply OB_BOR_LEVEL2 BOR Reset threshold levels for 1.9V - 2.0V VDD power supply OB_BOR_LEVEL3 BOR Reset threshold levels for 2.3V - 2.4V VDD power supply OB_BOR_LEVEL4 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 Software WDG selected OB_IWDG_HW 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 UM1816 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 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 Write protection of all Sectors FLASHEx Option Type 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 UM1816 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 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 Program a half-word (16-bit) at a specified address. FLASH_TYPEPROGRAMDATA_WORD Program a word (32-bit) at a specified address. FLASH_TYPEPROGRAMDATA_FASTBYTE 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 218/654 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 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 18.2.2 18.2.3 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. 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. 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 Return values HAL Status: The returned value can be: HAL_ERROR, HAL_OK or HAL_TIMEOUT. Notes 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 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. HAL_FLASHEx_ProgramParallelHalfPage DOCID026682 Rev 3 219/654 HAL FLASH__RAMFUNC Generic Driver UM1816 __RAM_FUNC HAL_FLASHEx_ProgramParallelHalfPage Function Name (uint32_t Address1, uint32_t * pBuffer1, uint32_t Address2, uint32_t * pBuffer2) Function Description Programs 2 half page in program memory in parallel. Parameters Return values HAL Status: The returned value can be: HAL_ERROR, HAL_OK or HAL_TIMEOUT. Notes 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 220/654 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. 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 Address: specifies the address to be written. pBuffer: pointer to the buffer containing the data to be written to the half page. Return values HAL Status: The returned value can be: HAL_ERROR, DOCID026682 Rev 3 UM1816 HAL FLASH__RAMFUNC Generic Driver HAL_OK or HAL_TIMEOUT. Notes 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 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 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 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. 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 Address: specifies the address to be written. Data: specifies the data to be written. Return values 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 UM1816 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. 2. 3. 4. 5. 6. 7. 8. 9. 224/654 Enable the GPIO AHB clock using the following function : __GPIOx_CLK_ENABLE(). Configure the GPIO pin(s) using HAL_GPIO_Init(). Configure the IO mode using "Mode" member from GPIO_InitTypeDef structure Activate Pull-up, Pull-down resistor using "Pull" member from GPIO_InitTypeDef structure. In case of Output or alternate function mode selection: the speed is configured through "Speed" member from GPIO_InitTypeDef structure, 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). 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(). 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. To get the level of a pin configured in input mode use HAL_GPIO_ReadPin(). To set/reset the level of a pin configured in output mode use HAL_GPIO_WritePin()/HAL_GPIO_TogglePin(). To lock pin configuration until next reset use HAL_GPIO_LockPin(). During and just after reset, the alternate functions are not active and the GPIO pins are configured in input floating mode (except JTAG pins). The LSE oscillator pins OSC32_IN and OSC32_OUT can be used as general purpose (PC14 and PC15, respectively) when the LSE oscillator is off. The LSE has priority over the GPIO function. DOCID026682 Rev 3 UM1816 10. 19.3.3 HAL GPIO Generic Driver The HSE oscillator pins OSC_IN/OSC_OUT can be used as general purpose PH0 and PH1, respectively, when the HSE oscillator is off. The HSE has priority over the GPIO function. Initialization and Configuration functions This section contains the following APIs: 19.3.4 HAL_GPIO_Init() HAL_GPIO_DeInit() 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 19.3.5 None Function Name void HAL_GPIO_DeInit (GPIO_TypeDef * GPIOx, uint32_t GPIO_Pin) Function Description De-initializes the GPIOx peripheral registers to their default reset values. Parameters GPIOx: where x can be (A..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 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 19.3.7 HAL_GPIO_DeInit Return values 19.3.6 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. 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. 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 Parameters UM1816 Sets or clears the selected data port bit. 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 Return values None Notes This function uses GPIOx_BSRR register to allow atomic read/modify accesses. In this way, there is no risk of an IRQ occurring between the read and the modify access. 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 19.3.9 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 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 None Notes The locked registers are GPIOx_MODER, GPIOx_OTYPER, GPIOx_OSPEEDR, GPIOx_PUPDR, GPIOx_AFRL and GPIOx_AFRH. The configuration of the locked GPIO pins can no longer be 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 19.3.10 19.3.11 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). HAL_GPIO_EXTI_IRQHandler Function Name void HAL_GPIO_EXTI_IRQHandler (uint16_t GPIO_Pin) Function Description This function handles EXTI interrupt request. Parameters GPIO_Pin: Specifies the port pin connected to corresponding EXTI line. Return values None HAL_GPIO_EXTI_Callback Function Name void HAL_GPIO_EXTI_Callback (uint16_t GPIO_Pin) Function Description EXTI line detection callbacks. Parameters GPIO_Pin: Specifies the port pin connected to corresponding EXTI line. Return values None 19.4 GPIO Firmware driver defines 19.4.1 GPIO GPIO Exported Macros __HAL_GPIO_EXTI_GET_FLAG Description: Checks whether the specified EXTI line flag is set or not. Parameters: __EXTI_LINE__: specifies the EXTI line flag to check. This parameter can be GPIO_PIN_x where x can be(0..15) Return value: __HAL_GPIO_EXTI_CLEAR_FLAG 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 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: __HAL_GPIO_EXTI_CLEAR_IT 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: __HAL_GPIO_EXTI_GENERATE_SWIT None 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 228/654 GPIO_MODE_INPUT Input Floating Mode GPIO_MODE_OUTPUT_PP Output Push Pull Mode GPIO_MODE_OUTPUT_OD Output Open Drain Mode GPIO_MODE_AF_PP Alternate Function Push Pull Mode GPIO_MODE_AF_OD Alternate Function Open Drain Mode GPIO_MODE_ANALOG Analog Mode GPIO_MODE_IT_RISING External Interrupt Mode with Rising edge trigger detection GPIO_MODE_IT_FALLING External Interrupt Mode with Falling edge trigger detection GPIO_MODE_IT_RISING_FALLING External Interrupt Mode with Rising/Falling edge DOCID026682 Rev 3 UM1816 HAL GPIO Generic Driver trigger detection GPIO_MODE_EVT_RISING External Event Mode with Rising edge trigger detection GPIO_MODE_EVT_FALLING External Event Mode with Falling edge trigger detection GPIO_MODE_EVT_RISING_FALLING External Event Mode with Rising/Falling edge trigger detection GPIO pins 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 UM1816 IS_GPIO_PULL IS_GPIO_SPEED IS_GPIO_MODE GPIO pull GPIO_NOPULL No Pull-up or Pull-down activation GPIO_PULLUP Pull-up activation GPIO_PULLDOWN Pull-down activation GPIO speed 230/654 GPIO_SPEED_VERY_LOW Very Low speed GPIO_SPEED_LOW Low speed GPIO_SPEED_MEDIUM Medium speed GPIO_SPEED_HIGH High speed 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 SWJ (SWD and JTAG) Alternate Function mapping GPIO_AF0_TRACE TRACE Alternate Function mapping GPIO_AF0_RTC_50Hz RTC_OUT Alternate Function mapping GPIO_AF1_TIM2 TIM2 Alternate Function mapping GPIO_AF2_TIM3 TIM3 Alternate Function mapping GPIO_AF2_TIM4 TIM4 Alternate Function mapping GPIO_AF2_TIM5 TIM5 Alternate Function mapping GPIO_AF3_TIM9 TIM9 Alternate Function mapping GPIO_AF3_TIM10 TIM10 Alternate Function mapping GPIO_AF3_TIM11 TIM11 Alternate Function mapping GPIO_AF4_I2C1 I2C1 Alternate Function mapping GPIO_AF4_I2C2 I2C2 Alternate Function mapping GPIO_AF5_SPI1 SPI1/I2S1 Alternate Function mapping GPIO_AF5_SPI2 SPI2/I2S2 Alternate Function mapping GPIO_AF6_SPI3 SPI3/I2S3 Alternate Function mapping GPIO_AF7_USART1 USART1 Alternate Function mapping GPIO_AF7_USART2 USART2 Alternate Function mapping GPIO_AF7_USART3 USART3 Alternate Function mapping GPIO_AF8_UART4 UART4 Alternate Function mapping GPIO_AF8_UART5 UART5 Alternate Function mapping GPIO_AF11_LCD LCD Alternate Function mapping GPIO_AF12_FSMC FSMC Alternate Function mapping GPIO_AF12_SDIO SDIO Alternate Function mapping GPIO_AF14_TIM_IC1 TIMER INPUT CAPTURE Alternate Function mapping GPIO_AF14_TIM_IC2 TIMER INPUT CAPTURE Alternate Function mapping GPIO_AF14_TIM_IC3 TIMER INPUT CAPTURE Alternate Function mapping DOCID026682 Rev 3 231/654 HAL GPIO Extension Driver GPIO_AF14_TIM_IC4 GPIO_AF15_EVENTOUT UM1816 TIMER INPUT CAPTURE Alternate Function mapping 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 21.2.2 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 I2C_HandleTypeDef DOCID026682 Rev 3 233/654 HAL I2C Generic Driver Data Fields UM1816 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 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. 2. 234/654 Declare a I2C_HandleTypeDef handle structure, for example: I2C_HandleTypeDef hi2c; Initialize the I2C low level resources by implement the HAL_I2C_MspInit() API: a. Enable the I2Cx interface clock b. I2C pins configuration Enable the clock for the I2C GPIOs Configure I2C pins as alternate function open-drain c. NVIC configuration if you need to use interrupt process Configure the I2Cx interrupt priority Enable the NVIC I2C IRQ Channel d. DMA Configuration if you need to use DMA process DOCID026682 Rev 3 UM1816 HAL I2C Generic Driver 3. 4. 5. 6. 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 Configure the Communication Speed, Duty cycle, Addressing mode, Own Address1, Dual Addressing mode, Own Address2, General call and Nostretch mode in the hi2c Init structure. Initialize the I2C registers by calling the HAL_I2C_Init(), configures also the low level Hardware (GPIO, CLOCK, NVIC...etc) by calling the customed HAL_I2C_MspInit(&hi2c) API. To check if target device is ready for communication, use the function HAL_I2C_IsDeviceReady() For I2C IO and IO MEM operations, three operation modes are available within this driver : Polling mode IO operation Transmit in master mode an amount of data in blocking mode using HAL_I2C_Master_Transmit() Receive in master mode an amount of data in blocking mode using HAL_I2C_Master_Receive() Transmit in slave mode an amount of data in blocking mode using HAL_I2C_Slave_Transmit() 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 236/654 Write an amount of data in no-blocking mode with DMA to a specific memory address using HAL_I2C_Mem_Write_DMA() 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: 21.3.3 HAL_I2C_Init() HAL_I2C_DeInit() HAL_I2C_MspInit() HAL_I2C_MspDeInit() 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 2. 3. 4. 5. Blocking mode : The communication is performed in the polling mode. The status of all data processing is returned by the same function after finishing transfer. No-Blocking mode : The communication is performed using Interrupts or DMA. These functions return the status of the transfer startup. The end of the data processing will be indicated through the dedicated I2C IRQ when using Interrupt mode or the DMA IRQ when using DMA mode. Blocking mode functions are : HAL_I2C_Master_Transmit() HAL_I2C_Master_Receive() HAL_I2C_Slave_Transmit() HAL_I2C_Slave_Receive() HAL_I2C_Mem_Write() HAL_I2C_Mem_Read() HAL_I2C_IsDeviceReady() No-Blocking mode functions with Interrupt are : HAL_I2C_Master_Transmit_IT() HAL_I2C_Master_Receive_IT() HAL_I2C_Slave_Transmit_IT() HAL_I2C_Slave_Receive_IT() HAL_I2C_Mem_Write_IT() HAL_I2C_Mem_Read_IT() No-Blocking mode functions with DMA are : HAL_I2C_Master_Transmit_DMA() HAL_I2C_Master_Receive_DMA() HAL_I2C_Slave_Transmit_DMA() HAL_I2C_Slave_Receive_DMA() HAL_I2C_Mem_Write_DMA() HAL_I2C_Mem_Read_DMA() A set of Transfer Complete Callbacks are provided in non Blocking mode: HAL_I2C_MemTxCpltCallback() HAL_I2C_MemRxCpltCallback() HAL_I2C_MasterTxCpltCallback() HAL_I2C_MasterRxCpltCallback() HAL_I2C_SlaveTxCpltCallback() HAL_I2C_SlaveRxCpltCallback() HAL_I2C_ErrorCallback() This section contains the following APIs: 238/654 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() DOCID026682 Rev 3 UM1816 HAL I2C Generic Driver 21.3.4 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() 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: 21.3.5 21.3.6 21.3.7 21.3.8 HAL_I2C_GetState() HAL_I2C_GetError() HAL_I2C_Init Function Name HAL_StatusTypeDef HAL_I2C_Init (I2C_HandleTypeDef * hi2c) Function Description Initializes the I2C according to the specified parameters in the I2C_InitTypeDef and create the associated handle. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values HAL status HAL_I2C_DeInit Function Name HAL_StatusTypeDef HAL_I2C_DeInit (I2C_HandleTypeDef * hi2c) Function Description DeInitializes the I2C peripheral. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values HAL status HAL_I2C_MspInit Function Name void HAL_I2C_MspInit (I2C_HandleTypeDef * hi2c) Function Description I2C MSP Init. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values None HAL_I2C_MspDeInit DOCID026682 Rev 3 239/654 HAL I2C Generic Driver Function Name 21.3.9 Function Description I2C MSP DeInit. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values None 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 21.3.10 HAL status Function Name HAL_StatusTypeDef HAL_I2C_Master_Receive (I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t * pData, uint16_t Size, uint32_t Timeout) Function Description Receives in master mode an amount of data in blocking mode. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module DevAddress: Target device address pData: Pointer to data buffer Size: Amount of data to be sent Timeout: Timeout duration HAL status HAL_I2C_Slave_Transmit Function Name HAL_StatusTypeDef HAL_I2C_Slave_Transmit (I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size, uint32_t Timeout) Function Description Transmits in slave mode an amount of data in blocking mode. Parameters Return values 240/654 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_I2C_Master_Receive Return values 21.3.11 UM1816 void HAL_I2C_MspDeInit (I2C_HandleTypeDef * hi2c) 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 DOCID026682 Rev 3 UM1816 21.3.12 HAL I2C Generic Driver HAL_I2C_Slave_Receive Function Name HAL_StatusTypeDef HAL_I2C_Slave_Receive (I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size, uint32_t Timeout) Function Description Receive in slave mode an amount of data in blocking mode. Parameters Return values 21.3.13 HAL status Function Name HAL_StatusTypeDef HAL_I2C_Master_Transmit_IT (I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t * pData, uint16_t Size) Function Description Transmit in master mode an amount of data in no-blocking mode with Interrupt. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module DevAddress: Target device address pData: Pointer to data buffer Size: Amount of data to be sent HAL status HAL_I2C_Master_Receive_IT Function Name HAL_StatusTypeDef HAL_I2C_Master_Receive_IT (I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t * pData, uint16_t Size) Function Description Receive in master mode an amount of data in no-blocking mode with Interrupt. Parameters Return values 21.3.15 HAL_I2C_Master_Transmit_IT Return values 21.3.14 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 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 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 Return values 21.3.16 Function Description Receive in slave mode an amount of data in no-blocking mode with Interrupt. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module pData: Pointer to data buffer Size: Amount of data to be sent HAL status HAL_I2C_Master_Transmit_DMA Function Name HAL_StatusTypeDef HAL_I2C_Master_Transmit_DMA (I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t * pData, uint16_t Size) Function Description Transmit in master mode an amount of data in no-blocking mode with DMA. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module DevAddress: Target device address pData: Pointer to data buffer Size: Amount of data to be sent HAL status HAL_I2C_Master_Receive_DMA Function Name HAL_StatusTypeDef HAL_I2C_Master_Receive_DMA (I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint8_t * pData, uint16_t Size) Function Description Receive in master mode an amount of data in no-blocking mode with DMA. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module DevAddress: Target device address pData: Pointer to data buffer Size: Amount of data to be sent HAL status HAL_I2C_Slave_Transmit_DMA Function Name 242/654 HAL status HAL_StatusTypeDef HAL_I2C_Slave_Receive_IT (I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size) Return values 21.3.19 Function Name Return values 21.3.18 pData: Pointer to data buffer Size: Amount of data to be sent HAL_I2C_Slave_Receive_IT Return values 21.3.17 UM1816 HAL_StatusTypeDef HAL_I2C_Slave_Transmit_DMA (I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size) DOCID026682 Rev 3 UM1816 Function Description HAL I2C Generic Driver Transmit in slave mode an amount of data in no-blocking mode with DMA. Parameters Return values 21.3.20 HAL status Function Name HAL_StatusTypeDef HAL_I2C_Slave_Receive_DMA (I2C_HandleTypeDef * hi2c, uint8_t * pData, uint16_t Size) Function Description Receive in slave mode an amount of data in no-blocking mode with DMA. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module pData: Pointer to data buffer Size: Amount of data to be sent HAL status HAL_I2C_Mem_Write Function Name HAL_StatusTypeDef HAL_I2C_Mem_Write (I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint16_t MemAddress, uint16_t MemAddSize, uint8_t * pData, uint16_t Size, uint32_t Timeout) Function Description Write an amount of data in blocking mode to a specific memory address. Parameters Return values 21.3.22 HAL_I2C_Slave_Receive_DMA Return values 21.3.21 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 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 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 Return values 21.3.23 244/654 HAL status Function Name HAL_StatusTypeDef HAL_I2C_Mem_Write_IT (I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint16_t MemAddress, uint16_t MemAddSize, uint8_t * pData, uint16_t Size) Function Description Write an amount of data in no-blocking mode with Interrupt to a specific memory address. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module DevAddress: Target device address MemAddress: Internal memory address MemAddSize: Size of internal memory address pData: Pointer to data buffer Size: Amount of data to be sent HAL status 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 21.3.25 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_I2C_Mem_Write_IT Return values 21.3.24 UM1816 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 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. DOCID026682 Rev 3 UM1816 HAL I2C Generic Driver Parameters Return values 21.3.26 21.3.28 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 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 21.3.27 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 HAL_I2C_IsDeviceReady Function Name HAL_StatusTypeDef HAL_I2C_IsDeviceReady (I2C_HandleTypeDef * hi2c, uint16_t DevAddress, uint32_t Trials, uint32_t Timeout) Function Description Checks if target device is ready for communication. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module DevAddress: Target device address Trials: Number of trials Timeout: Timeout duration Return values HAL status Notes This function is used with Memory devices HAL_I2C_EV_IRQHandler Function Name void HAL_I2C_EV_IRQHandler (I2C_HandleTypeDef * hi2c) Function Description This function handles I2C event interrupt request. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values HAL status DOCID026682 Rev 3 245/654 HAL I2C Generic Driver 21.3.29 21.3.30 21.3.31 21.3.32 21.3.33 21.3.34 246/654 UM1816 HAL_I2C_ER_IRQHandler Function Name void HAL_I2C_ER_IRQHandler (I2C_HandleTypeDef * hi2c) Function Description This function handles I2C error interrupt request. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values HAL status HAL_I2C_MasterTxCpltCallback Function Name void HAL_I2C_MasterTxCpltCallback (I2C_HandleTypeDef * hi2c) Function Description Master Tx Transfer completed callbacks. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values None HAL_I2C_MasterRxCpltCallback Function Name void HAL_I2C_MasterRxCpltCallback (I2C_HandleTypeDef * hi2c) Function Description Master Rx Transfer completed callbacks. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values None HAL_I2C_SlaveTxCpltCallback Function Name void HAL_I2C_SlaveTxCpltCallback (I2C_HandleTypeDef * hi2c) Function Description Slave Tx Transfer completed callbacks. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values None HAL_I2C_SlaveRxCpltCallback Function Name void HAL_I2C_SlaveRxCpltCallback (I2C_HandleTypeDef * hi2c) Function Description Slave Rx Transfer completed callbacks. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values None HAL_I2C_MemTxCpltCallback DOCID026682 Rev 3 UM1816 21.3.35 21.3.36 21.3.37 21.3.38 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 HAL_I2C_MemRxCpltCallback Function Name void HAL_I2C_MemRxCpltCallback (I2C_HandleTypeDef * hi2c) Function Description Memory Rx Transfer completed callbacks. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values None HAL_I2C_ErrorCallback Function Name void HAL_I2C_ErrorCallback (I2C_HandleTypeDef * hi2c) Function Description I2C error callbacks. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values None HAL_I2C_GetState Function Name HAL_I2C_StateTypeDef HAL_I2C_GetState (I2C_HandleTypeDef * hi2c) Function Description Returns the I2C state. Parameters hi2c: pointer to a I2C_HandleTypeDef structure that contains the configuration information for I2C module Return values HAL state HAL_I2C_GetError Function Name uint32_t HAL_I2C_GetError (I2C_HandleTypeDef * hi2c) Function Description Return the I2C error code. Parameters hi2c: : pointer to a I2C_HandleTypeDef structure that contains the configuration information for the specified I2C. Return values I2C Error Code 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 UM1816 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 I2C Error Codes HAL_I2C_ERROR_NONE No error HAL_I2C_ERROR_BERR BERR error HAL_I2C_ERROR_ARLO ARLO error HAL_I2C_ERROR_AF AF error HAL_I2C_ERROR_OVR OVR error HAL_I2C_ERROR_DMA DMA transfer error HAL_I2C_ERROR_TIMEOUT Timeout error I2C Exported Macros __HAL_I2C_RESET_HANDLE_STATE Description: Reset I2C handle state. Parameters: __HANDLE__: specifies the I2C Handle. This parameter can be I2C where x: 1, 2, or 3 to select the I2C peripheral. Return value: __HAL_I2C_ENABLE_IT None Description: Enable or disable the specified I2C interrupts. Parameters: 248/654 __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 DOCID026682 Rev 3 UM1816 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 __HAL_I2C_DISABLE_IT __HAL_I2C_GET_IT_SOURCE Description: Checks if the specified I2C interrupt source is enabled or disabled. Parameters: __HANDLE__: specifies the I2C Handle. This parameter can be 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: __HAL_I2C_GET_FLAG 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 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: __HAL_I2C_CLEAR_FLAG 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: __HAL_I2C_CLEAR_ADDRFLAG 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: __HAL_I2C_CLEAR_STOPFLAG None Description: Clears the I2C STOPF pending flag. Parameters: 250/654 __HANDLE__: specifies the I2C Handle. DOCID026682 Rev 3 UM1816 HAL I2C Generic Driver This parameter can be I2Cx where x: 1 or 2 to select the I2C peripheral. Return value: __HAL_I2C_ENABLE 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: __HAL_I2C_DISABLE 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 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 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 HAL I2C Generic Driver I2C_MEM_ADD_LSB 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 22.2.2 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 I2S_HandleTypeDef Data Fields 254/654 SPI_TypeDef * Instance I2S_InitTypeDef Init uint16_t * pTxBuffPtr __IO uint16_t TxXferSize __IO uint16_t TxXferCount uint16_t * pRxBuffPtr __IO uint16_t RxXferSize DOCID026682 Rev 3 UM1816 HAL I2S Generic Driver __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 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. 2. 3. Declare a I2S_HandleTypeDef handle structure. Initialize the I2S low level resources by implement the HAL_I2S_MspInit() API: a. Enable the SPIx interface clock. b. I2S pins configuration: Enable the clock for the I2S GPIOs. Configure these I2S pins as alternate function. 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. 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 256/654 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() 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: 22.3.3 HAL_I2S_Init() HAL_I2S_DeInit() HAL_I2S_MspInit() HAL_I2S_MspDeInit() IO operation functions This subsection provides a set of functions allowing to manage the I2S data transfers. 1. 2. 3. There are two modes of transfer: Blocking mode : The communication is performed in the polling mode. The status of all data processing is returned by the same function after finishing transfer. No-Blocking mode : The communication is performed using Interrupts or DMA. These functions return the status of the transfer startup. The end of the data processing will be indicated through the dedicated I2S IRQ when using Interrupt mode or the DMA IRQ when using DMA mode. Blocking mode functions are : HAL_I2S_Transmit() HAL_I2S_Receive() No-Blocking mode functions with Interrupt are : HAL_I2S_Transmit_IT() DOCID026682 Rev 3 257/654 HAL I2S Generic Driver 4. 5. UM1816 HAL_I2S_Receive_IT() No-Blocking mode functions with DMA are : HAL_I2S_Transmit_DMA() HAL_I2S_Receive_DMA() A set of Transfer Complete Callbacks are provided in non Blocking mode: HAL_I2S_TxCpltCallback() HAL_I2S_RxCpltCallback() HAL_I2S_ErrorCallback() This section contains the following APIs: 22.3.4 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() 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: 22.3.5 22.3.6 258/654 HAL_I2S_GetState() HAL_I2S_GetError() 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 HAL_I2S_DeInit Function Name HAL_StatusTypeDef HAL_I2S_DeInit (I2S_HandleTypeDef * hi2s) Function Description DeInitializes the I2S peripheral. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values HAL status DOCID026682 Rev 3 UM1816 22.3.7 22.3.8 22.3.9 HAL I2S Generic Driver HAL_I2S_MspInit Function Name void HAL_I2S_MspInit (I2S_HandleTypeDef * hi2s) Function Description I2S MSP Init. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values None HAL_I2S_MspDeInit Function Name void HAL_I2S_MspDeInit (I2S_HandleTypeDef * hi2s) Function Description I2S MSP DeInit. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values None HAL_I2S_Transmit Function Name HAL_StatusTypeDef HAL_I2S_Transmit (I2S_HandleTypeDef * hi2s, uint16_t * pData, uint16_t Size, uint32_t Timeout) Function Description Transmit an amount of data in blocking mode. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module pData: a 16-bit pointer to data buffer. Size: number of data sample to be sent: Timeout: Timeout duration Return values HAL status Notes When a 16-bit data frame or a 16-bit data frame extended is selected during the I2S configuration phase, the Size parameter means the number of 16-bit data length in the transaction and when a 24-bit data frame or a 32-bit data frame is selected the Size parameter means the number of 16-bit data length. The I2S is kept enabled at the end of transaction to avoid the clock de-synchronization between Master and Slave(example: audio streaming). 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 hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module pData: a 16-bit pointer to data buffer. Size: number of data sample to be sent: Return values HAL status Notes When a 16-bit data frame or a 16-bit data frame extended is selected during the I2S configuration phase, the Size parameter means the number of 16-bit data length in the transaction and when a 24-bit data frame or a 32-bit data frame is selected the Size parameter means the number of 16-bit data length. The I2S is kept enabled at the end of transaction to avoid the clock de-synchronization between Master and Slave(example: audio streaming). 22.3.12 260/654 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 hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module pData: a 16-bit pointer to the Receive data buffer. Size: number of data sample to be sent: Return values HAL status Notes When a 16-bit data frame or a 16-bit data frame extended is selected during the I2S configuration phase, the Size parameter means the number of 16-bit data length in the transaction and when a 24-bit data frame or a 32-bit data frame is selected the Size parameter means the number of 16-bit data length. DOCID026682 Rev 3 UM1816 HAL I2S Generic Driver 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 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.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 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.15 The I2S is kept enabled at the end of transaction to avoid the clock de-synchronization between Master and Slave(example: audio streaming). It is recommended to use DMA for the I2S receiver to avoid de-synchronisation between Master and Slave otherwise the I2S interrupt should be optimized. HAL_I2S_DMAPause Function Name HAL_StatusTypeDef HAL_I2S_DMAPause DOCID026682 Rev 3 261/654 HAL I2S Generic Driver UM1816 (I2S_HandleTypeDef * hi2s) 22.3.16 22.3.17 22.3.18 22.3.19 22.3.20 262/654 Function Description Pauses the audio stream playing from the Media. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values HAL status HAL_I2S_DMAResume Function Name HAL_StatusTypeDef HAL_I2S_DMAResume (I2S_HandleTypeDef * hi2s) Function Description Resumes the audio stream playing from the Media. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values HAL status HAL_I2S_DMAStop Function Name HAL_StatusTypeDef HAL_I2S_DMAStop (I2S_HandleTypeDef * hi2s) Function Description Resumes the audio stream playing from the Media. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values HAL status HAL_I2S_IRQHandler Function Name void HAL_I2S_IRQHandler (I2S_HandleTypeDef * hi2s) Function Description This function handles I2S interrupt request. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values None HAL_I2S_TxHalfCpltCallback Function Name void HAL_I2S_TxHalfCpltCallback (I2S_HandleTypeDef * hi2s) Function Description Tx Transfer Half completed callbacks. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values None HAL_I2S_TxCpltCallback Function Name void HAL_I2S_TxCpltCallback (I2S_HandleTypeDef * hi2s) Function Description Tx Transfer completed callbacks. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains DOCID026682 Rev 3 UM1816 HAL I2S Generic Driver the configuration information for I2S module Return values 22.3.21 22.3.22 22.3.23 22.3.24 22.3.25 None HAL_I2S_RxHalfCpltCallback Function Name void HAL_I2S_RxHalfCpltCallback (I2S_HandleTypeDef * hi2s) Function Description Rx Transfer half completed callbacks. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values None HAL_I2S_RxCpltCallback Function Name void HAL_I2S_RxCpltCallback (I2S_HandleTypeDef * hi2s) Function Description Rx Transfer completed callbacks. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values None HAL_I2S_ErrorCallback Function Name void HAL_I2S_ErrorCallback (I2S_HandleTypeDef * hi2s) Function Description I2S error callbacks. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values None HAL_I2S_GetState Function Name HAL_I2S_StateTypeDef HAL_I2S_GetState (I2S_HandleTypeDef * hi2s) Function Description Return the I2S state. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values HAL state HAL_I2S_GetError Function Name uint32_t HAL_I2S_GetError (I2S_HandleTypeDef * hi2s) Function Description Return the I2S error code. Parameters hi2s: pointer to a I2S_HandleTypeDef structure that contains the configuration information for I2S module Return values I2S Error Code DOCID026682 Rev 3 263/654 HAL I2S Generic Driver UM1816 22.4 I2S Firmware driver defines 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 Generic Driver None Description: __HAL_I2S_ENABLE Enable or disable the specified SPI peripheral (in I2S mode). Parameters: __HANDLE__: specifies the I2S Handle. Return value: None __HAL_I2S_DISABLE Description: __HAL_I2S_ENABLE_IT Enable or disable the specified I2S interrupts. Parameters: __HANDLE__: specifies the I2S Handle. __INTERRUPT__: specifies the interrupt source to enable or disable. This parameter can be one of the following values: I2S_IT_TXE: Tx buffer empty interrupt enable I2S_IT_RXNE: RX buffer not empty interrupt enable I2S_IT_ERR: Error interrupt enable Return value: None __HAL_I2S_DISABLE_IT __HAL_I2S_GET_IT_SOURCE Description: Checks if the specified I2S interrupt source is enabled or disabled. Parameters: __HANDLE__: specifies the I2S Handle. This parameter can be I2S where x: 1, 2, or 3 to select the I2S peripheral. __INTERRUPT__: specifies the I2S interrupt source to check. This parameter can be one of the following values: I2S_IT_TXE: Tx buffer empty interrupt enable I2S_IT_RXNE: RX buffer not empty interrupt enable I2S_IT_ERR: Error interrupt enable Return value: __HAL_I2S_GET_FLAG The: new state of __IT__ (TRUE or FALSE). Description: DOCID026682 Rev 3 265/654 HAL I2S Generic Driver 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: __HAL_I2S_CLEAR_OVRFLAG The: new state of __FLAG__ (TRUE or FALSE). Description: Clears the I2S OVR pending flag. Parameters: __HANDLE__: specifies the I2S Handle. Return value: __HAL_I2S_CLEAR_UDRFLAG None Description: Clears the I2S UDR pending flag. Parameters: __HANDLE__: specifies the I2S Handle. Return value: None I2S Flag definition I2S_FLAG_TXE I2S_FLAG_RXNE I2S_FLAG_UDR I2S_FLAG_OVR I2S_FLAG_FRE I2S_FLAG_CHSIDE I2S_FLAG_BSY I2S Interrupt configuration definition 266/654 DOCID026682 Rev 3 UM1816 HAL I2S Generic Driver 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 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 23.2.2 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 IRDA_HandleTypeDef Data Fields 268/654 USART_TypeDef * Instance 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. 2. Declare a IRDA_HandleTypeDef handle structure. Initialize the IRDA low level resources by implementing the HAL_IRDA_MspInit() API: a. Enable the USARTx interface clock. b. IRDA pins configuration: DOCID026682 Rev 3 269/654 HAL IRDA Generic Driver 3. 4. 5. UM1816 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 (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) Program the Baud Rate, Word Length, Parity, IrDA Mode, Prescaler and Mode(Receiver/Transmitter) in the hirda Init structure. 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. Three operation modes are available within this driver : Polling mode IO operation Send an amount of data in blocking mode using HAL_IRDA_Transmit() Receive an amount of data in blocking mode using HAL_IRDA_Receive() Interrupt mode IO operation Send an amount of data in non blocking mode using HAL_IRDA_Transmit_IT() At transmission end of transfer HAL_IRDA_TxCpltCallback is executed and user can add his own code by customization of function pointer HAL_IRDA_TxCpltCallback Receive an amount of data in non blocking mode using HAL_IRDA_Receive_IT() At reception end of transfer HAL_IRDA_RxCpltCallback is executed and user can add his own code by customization of function pointer HAL_IRDA_RxCpltCallback In case of transfer Error, HAL_IRDA_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_IRDA_ErrorCallback DMA mode IO operation 270/654 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. Table 18: IRDA frame formats M bit PCE bit IRDA frame 0 0 | SB | 8 bit data | STB | 0 1 | SB | 7 bit data | PB | STB | 1 0 | 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: 23.3.3 UM1816 HAL_IRDA_Init() HAL_IRDA_DeInit() HAL_IRDA_MspInit() HAL_IRDA_MspDeInit() 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. 2. 3. 4. 5. There are two modes of transfer: Blocking mode: The communication is performed in polling mode. The HAL status of all data processing is returned by the same function after finishing transfer. No-Blocking mode: The communication is performed using Interrupts or DMA, These API's return the HAL status. The end of the data processing will be indicated through the dedicated IRDA IRQ when using Interrupt mode or the DMA IRQ when using DMA mode. The HAL_IRDA_TxCpltCallback(), HAL_IRDA_RxCpltCallback() user callbacks will be executed respectively at the end of the transmit or Receive process The HAL_IRDA_ErrorCallback() user callback will be executed when a communication error is detected Blocking mode APIs are : HAL_IRDA_Transmit() HAL_IRDA_Receive() Non Blocking mode APIs with Interrupt are : HAL_IRDA_Transmit_IT() HAL_IRDA_Receive_IT() HAL_IRDA_IRQHandler() Non Blocking mode functions with DMA are : HAL_IRDA_Transmit_DMA() HAL_IRDA_Receive_DMA() HAL_IRDA_DMAPause() HAL_IRDA_DMAResume() HAL_IRDA_DMAStop() 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: 272/654 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() DOCID026682 Rev 3 UM1816 HAL IRDA Generic Driver 23.3.4 HAL_IRDA_DMAStop() HAL_IRDA_IRQHandler() HAL_IRDA_TxCpltCallback() HAL_IRDA_TxHalfCpltCallback() HAL_IRDA_RxCpltCallback() HAL_IRDA_RxHalfCpltCallback() HAL_IRDA_ErrorCallback() 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: 23.3.5 23.3.6 23.3.7 HAL_IRDA_GetState() HAL_IRDA_GetError() 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 hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. Return values HAL status HAL_IRDA_DeInit Function Name HAL_StatusTypeDef HAL_IRDA_DeInit (IRDA_HandleTypeDef * hirda) Function Description DeInitializes the IRDA peripheral. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. Return values HAL status HAL_IRDA_MspInit Function Name void HAL_IRDA_MspInit (IRDA_HandleTypeDef * hirda) Function Description IRDA MSP Init. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. DOCID026682 Rev 3 273/654 HAL IRDA Generic Driver Return values 23.3.8 23.3.9 Function Name void HAL_IRDA_MspDeInit (IRDA_HandleTypeDef * hirda) Function Description IRDA MSP DeInit. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. Return values None HAL_IRDA_Transmit Function Name HAL_StatusTypeDef HAL_IRDA_Transmit (IRDA_HandleTypeDef * hirda, uint8_t * pData, uint16_t Size, uint32_t Timeout) Function Description Sends an amount of data in blocking mode. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. pData: Pointer to data buffer Size: Amount of data to be sent Timeout: Specify timeout value HAL status 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 23.3.11 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 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 274/654 None HAL_IRDA_MspDeInit Return values 23.3.10 UM1816 hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. pData: Pointer to data buffer DOCID026682 Rev 3 UM1816 HAL IRDA Generic Driver Return values 23.3.12 23.3.15 HAL status Function Name HAL_StatusTypeDef HAL_IRDA_Receive_IT (IRDA_HandleTypeDef * hirda, uint8_t * pData, uint16_t Size) Function Description Receives an amount of data in non-blocking mode. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. pData: Pointer to data buffer Size: Amount of data to be received HAL status 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 Return values 23.3.14 Size: Amount of data to be sent HAL_IRDA_Receive_IT Return values 23.3.13 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 HAL status 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 HAL status Notes When the IRDA parity is enabled (PCE = 1) the data received contain the parity bit. HAL_IRDA_DMAPause Function Name HAL_StatusTypeDef HAL_IRDA_DMAPause (IRDA_HandleTypeDef * hirda) Function Description Pauses the DMA Transfer. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that DOCID026682 Rev 3 275/654 HAL IRDA Generic Driver Return values 23.3.16 23.3.17 23.3.18 23.3.19 23.3.20 HAL status HAL_IRDA_DMAResume Function Name HAL_StatusTypeDef HAL_IRDA_DMAResume (IRDA_HandleTypeDef * hirda) Function Description Resumes the DMA Transfer. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_IRDA_DMAStop Function Name HAL_StatusTypeDef HAL_IRDA_DMAStop (IRDA_HandleTypeDef * hirda) Function Description Stops the DMA Transfer. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_IRDA_IRQHandler Function Name void HAL_IRDA_IRQHandler (IRDA_HandleTypeDef * hirda) Function Description This function handles IRDA interrupt request. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. Return values None HAL_IRDA_TxCpltCallback Function Name void HAL_IRDA_TxCpltCallback (IRDA_HandleTypeDef * hirda) Function Description Tx Transfer completed callbacks. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. Return values None HAL_IRDA_TxHalfCpltCallback Function Name 276/654 UM1816 contains the configuration information for the specified IRDA module. void HAL_IRDA_TxHalfCpltCallback (IRDA_HandleTypeDef * hirda) DOCID026682 Rev 3 UM1816 23.3.21 23.3.22 23.3.23 23.3.24 23.3.25 HAL IRDA Generic Driver Function Description Tx Half Transfer completed callbacks. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values None HAL_IRDA_RxCpltCallback Function Name void HAL_IRDA_RxCpltCallback (IRDA_HandleTypeDef * hirda) Function Description Rx Transfer completed callbacks. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. Return values None HAL_IRDA_RxHalfCpltCallback Function Name void HAL_IRDA_RxHalfCpltCallback (IRDA_HandleTypeDef * hirda) Function Description Rx Half Transfer complete callbacks. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. Return values None HAL_IRDA_ErrorCallback Function Name void HAL_IRDA_ErrorCallback (IRDA_HandleTypeDef * hirda) Function Description IRDA error callbacks. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. Return values None HAL_IRDA_GetState Function Name HAL_IRDA_StateTypeDef HAL_IRDA_GetState (IRDA_HandleTypeDef * hirda) Function Description Returns the IRDA state. Parameters hirda: Pointer to a IRDA_HandleTypeDef structure that contains the configuration information for the specified IRDA module. Return values HAL state HAL_IRDA_GetError 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 Noise error HAL_IRDA_ERROR_FE frame error HAL_IRDA_ERROR_ORE Overrun error HAL_IRDA_ERROR_DMA DMA transfer error IRDA Exported Macros __HAL_IRDA_RESET_HANDLE_STATE 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: __HAL_IRDA_FLUSH_DRREGISTER None Description: Flush the IRDA DR register. Parameters: __HAL_IRDA_GET_FLAG __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: 278/654 DOCID026682 Rev 3 __HANDLE__: specifies the IRDA UM1816 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: __HAL_IRDA_CLEAR_FLAG 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: DOCID026682 Rev 3 PE (Parity error), FE (Framing error), NE (Noise error), ORE (OverRun error) and IDLE (Idle line detected) flags are cleared by software 279/654 HAL IRDA Generic Driver 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. __HAL_IRDA_CLEAR_PEFLAG 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: __HAL_IRDA_CLEAR_FEFLAG 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: __HAL_IRDA_CLEAR_NEFLAG 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: __HAL_IRDA_CLEAR_OREFLAG Description: 280/654 None DOCID026682 Rev 3 Clear the IRDA ORE pending flag. UM1816 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: __HAL_IRDA_CLEAR_IDLEFLAG 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: __HAL_IRDA_ENABLE_IT 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: __HAL_IRDA_DISABLE_IT None Description: DOCID026682 Rev 3 281/654 HAL IRDA Generic Driver 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: __HAL_IRDA_GET_IT_SOURCE None Description: Check whether the specified IRDA interrupt has occurred or not. Parameters: 282/654 DOCID026682 Rev 3 __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 UM1816 HAL IRDA Generic Driver Return value: __HAL_IRDA_ONE_BIT_SAMPLE_ENABLE The: new state of __IT__ (TRUE or FALSE). Description: Enables the IRDA one bit sample method. Parameters: __HANDLE__: specifies the IRDA Handle. Return value: __HAL_IRDA_ONE_BIT_SAMPLE_DISABLE None Description: Disables the IRDA one bit sample method. Parameters: __HANDLE__: specifies the IRDA Handle. Return value: __HAL_IRDA_ENABLE None Description: Enable UART/USART associated to IRDA Handle. Parameters: __HANDLE__: specifies the IRDA Handle. IRDA Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). Return value: __HAL_IRDA_DISABLE 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: DOCID026682 Rev 3 None 283/654 HAL IRDA Generic Driver IRDA Flags UM1816 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 HAL IRDA Generic Driver IRDA_CR3_REG_INDEX IRDA_DIV IRDA_DIVMANT IRDA_DIVFRAQ IRDA_BRR IS_IRDA_BAUDRATE The maximum Baud Rate is 115200bps Returns : True or False IS_IRDA_WORD_LENGTH IS_IRDA_PARITY IS_IRDA_MODE IS_IRDA_POWERMODE IRDA_IT_MASK 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 24.2.2 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 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: 24.3.2 HAL_IWDG_Init() HAL_IWDG_MspInit() IO operation functions This section provides functions allowing to: Start the IWDG. Refresh the IWDG. This section contains the following APIs: 24.3.3 HAL_IWDG_Start() HAL_IWDG_Refresh() 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: 24.3.4 24.3.5 24.3.6 HAL_IWDG_GetState() 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 hiwdg: pointer to a IWDG_HandleTypeDef structure that contains the configuration information for the specified IWDG module. Return values HAL status HAL_IWDG_MspInit Function Name void HAL_IWDG_MspInit (IWDG_HandleTypeDef * hiwdg) Function Description Initializes the IWDG MSP. Parameters hiwdg: pointer to a IWDG_HandleTypeDef structure that contains the configuration information for the specified IWDG module. Return values None 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 hiwdg: pointer to a IWDG_HandleTypeDef structure that contains the configuration information for the specified IWDG module. Return values HAL status 24.3.7 24.3.8 UM1816 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 HAL_IWDG_GetState Function Name HAL_IWDG_StateTypeDef HAL_IWDG_GetState (IWDG_HandleTypeDef * hiwdg) Function Description Returns the IWDG state. Parameters hiwdg: pointer to a IWDG_HandleTypeDef structure that contains the configuration information for the specified IWDG module. Return values 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. Return value: None Description: __HAL_IWDG_START Enables the IWDG peripheral. Parameters: __HANDLE__: IWDG handle Return value: __HAL_IWDG_RELOAD_COUNTER 288/654 None Description: DOCID026682 Rev 3 UM1816 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: __HAL_IWDG_GET_FLAG 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 Reload Counter Enable IWDG_KEY_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 Watchdog counter prescaler value update flag IWDG_FLAG_RVU Watchdog counter reload value update flag IWDG Private Macros IWDG_ENABLE_WRITE_ACCESS Description: DOCID026682 Rev 3 289/654 HAL IWDG Generic Driver UM1816 Enables write access to IWDG_PR and IWDG_RLR registers. Parameters: __HANDLE__: IWDG handle Return value: IWDG_DISABLE_WRITE_ACCESS None Description: Disables write access to IWDG_PR and IWDG_RLR registers. Parameters: __HANDLE__: IWDG handle Return value: IS_IWDG_PRESCALER None Description: Check IWDG prescaler value. Parameters: __PRESCALER__: IWDG prescaler value Return value: IS_IWDG_RELOAD None Description: Check IWDG reload value. Parameters: __RELOAD__: IWDG reload value Return value: 290/654 None 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 25.2.2 UM1816 uint32_t LCD_InitTypeDef::BlinkFrequency 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. 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. 2. 3. 4. 5. 292/654 Declare a LCD_HandleTypeDef handle structure. 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. Program the Prescaler, Divider, Blink mode, Blink Frequency Duty, Bias, Voltage Source, Dead Time, Pulse On Duration and Contrast in the hlcd Init structure. 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 Optionally you can update the LCD configuration using these macros: DOCID026682 Rev 3 UM1816 HAL LCD Generic Driver 6. 7. 8. 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 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. The HAL_LCD_Clear() API can be used to clear the LCD RAM memory. When LCD RAM memory is updated enable the update display request using the HAL_LCD_UpdateDisplayRequest() API. LCD and low power modes: 1. 25.3.2 The LCD remain active during STOP mode. Initialization and Configuration functions This section contains the following APIs: 25.3.3 HAL_LCD_DeInit() HAL_LCD_Init() HAL_LCD_MspDeInit() HAL_LCD_MspInit() 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: 25.3.4 HAL_LCD_Write() HAL_LCD_Clear() HAL_LCD_UpdateDisplayRequest() 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: 25.3.5 25.3.6 25.3.7 25.3.8 25.3.9 HAL_LCD_GetState() HAL_LCD_GetError() 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 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 hlcd: LCD handle Return values None Notes This function can be used only when the LCD is disabled. The LCD HighDrive can be enabled/disabled using related macros up to user. HAL_LCD_MspDeInit Function Name void HAL_LCD_MspDeInit (LCD_HandleTypeDef * hlcd) Function Description LCD MSP DeInit. Parameters hlcd: LCD handle Return values None HAL_LCD_MspInit Function Name void HAL_LCD_MspInit (LCD_HandleTypeDef * hlcd) Function Description LCD MSP Init. Parameters hlcd: LCD handle Return values None HAL_LCD_Write Function Name 294/654 HAL_StatusTypeDef HAL_LCD_Write (LCD_HandleTypeDef * hlcd, uint32_t RAMRegisterIndex, uint32_t RAMRegisterMask, uint32_t Data) DOCID026682 Rev 3 UM1816 HAL LCD Generic Driver Function Description Writes a word in the specific LCD RAM. Parameters 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 Return values 25.3.10 25.3.11 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 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 None Notes 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 25.3.13 UM1816 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 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 1/4 Bias LCD_BIAS_1_2 1/2 Bias LCD_BIAS_1_3 1/3 Bias IS_LCD_BIAS 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 IS_LCD_BLINK_FREQUENCY LCD Blink Mode LCD_BLINKMODE_OFF Blink disabled LCD_BLINKMODE_SEG0_COM0 Blink enabled on SEG[0], COM[0] (1 pixel) LCD_BLINKMODE_SEG0_ALLCOM 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 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 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 IS_LCD_DEAD_TIME LCD Divider LCD_DIVIDER_16 LCD frequency = CLKPS/16 LCD_DIVIDER_17 LCD frequency = CLKPS/17 LCD_DIVIDER_18 LCD frequency = CLKPS/18 LCD_DIVIDER_19 LCD frequency = CLKPS/19 LCD_DIVIDER_20 LCD frequency = CLKPS/20 LCD_DIVIDER_21 LCD frequency = CLKPS/21 LCD_DIVIDER_22 LCD frequency = CLKPS/22 LCD_DIVIDER_23 LCD frequency = CLKPS/23 LCD_DIVIDER_24 LCD frequency = CLKPS/24 LCD_DIVIDER_25 LCD frequency = CLKPS/25 LCD_DIVIDER_26 LCD frequency = CLKPS/26 LCD_DIVIDER_27 LCD frequency = CLKPS/27 LCD_DIVIDER_28 LCD frequency = CLKPS/28 LCD_DIVIDER_29 LCD frequency = CLKPS/29 LCD_DIVIDER_30 LCD frequency = CLKPS/30 DOCID026682 Rev 3 297/654 HAL LCD Generic Driver LCD_DIVIDER_31 UM1816 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 1/3 duty LCD_DUTY_1_4 1/4 duty LCD_DUTY_1_8 1/8 duty IS_LCD_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 HAL_LCD_ERROR_UDD Update display done flag timeout error HAL_LCD_ERROR_ENS LCD enabled status flag timeout error HAL_LCD_ERROR_RDY LCD Booster ready timeout error LCD Exported Macros __HAL_LCD_RESET_HANDLE_STATE Description: Reset LCD handle state. Parameters: __HANDLE__: specifies the LCD Handle. Return value: None Description: __HAL_LCD_ENABLE macros to enables or disables the LCD Parameters: __HANDLE__: specifies the LCD Handle. Return value: None __HAL_LCD_DISABLE __HAL_LCD_HIGHDRIVER_ENABLE 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 Return value: __HAL_LCD_DEADTIME_CONFIG 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 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: __HAL_LCD_CONTRAST_CONFIG 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: __HAL_LCD_BLINK_CONFIG None Description: Macro to configure the LCD Blink mode and Blink frequency. Parameters: 300/654 __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 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: __HAL_LCD_ENABLE_IT 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 __HAL_LCD_DISABLE_IT __HAL_LCD_GET_IT_SOURCE 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 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: __HAL_LCD_GET_FLAG 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: __HAL_LCD_CLEAR_FLAG 302/654 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: DOCID026682 Rev 3 UM1816 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 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 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 CLKPS = LCDCLK/2 LCD_PRESCALER_4 CLKPS = LCDCLK/4 LCD_PRESCALER_8 CLKPS = LCDCLK/8 LCD_PRESCALER_16 CLKPS = LCDCLK/16 LCD_PRESCALER_32 CLKPS = LCDCLK/32 LCD_PRESCALER_64 CLKPS = LCDCLK/64 LCD_PRESCALER_128 CLKPS = LCDCLK/128 DOCID026682 Rev 3 303/654 HAL LCD Generic Driver LCD_PRESCALER_256 CLKPS = LCDCLK/256 UM1816 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 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 IS_LCD_PULSE_ON_DURATION LCD RAMRegister 304/654 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 DOCID026682 Rev 3 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 26.2.2 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 NOR_CFITypeDef Data Fields uint16_t CFI_1 uint16_t CFI_2 uint16_t CFI_3 uint16_t CFI_4 Field Documentation 306/654 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 DOCID026682 Rev 3 UM1816 26.2.3 HAL NOR Generic Driver NOR_HandleTypeDef 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. 26.3.2 NOR_WRITE : NOR memory write data to specified address NOR Initialization and de_initialization functions This section provides functions allowing to initialize/de-initialize the NOR memory This section contains the following APIs: 26.3.3 HAL_NOR_Init() HAL_NOR_DeInit() HAL_NOR_MspInit() HAL_NOR_MspDeInit() HAL_NOR_MspWait() NOR Input and Output functions This section provides functions allowing to use and control the NOR memory This section contains the following APIs: 26.3.4 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() NOR Control functions This subsection provides a set of functions allowing to control dynamically the NOR interface. This section contains the following APIs: 26.3.5 HAL_NOR_WriteOperation_Enable() HAL_NOR_WriteOperation_Disable() 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: 26.3.6 308/654 HAL_NOR_GetState() HAL_NOR_GetStatus() HAL_NOR_Init 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 26.3.7 26.3.8 26.3.9 26.3.10 HAL status HAL_NOR_DeInit Function Name HAL_StatusTypeDef HAL_NOR_DeInit (NOR_HandleTypeDef * hnor) Function Description Perform NOR memory De-Initialization sequence. Parameters hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. Return values HAL status HAL_NOR_MspInit Function Name void HAL_NOR_MspInit (NOR_HandleTypeDef * hnor) Function Description NOR MSP Init. Parameters hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. Return values None HAL_NOR_MspDeInit Function Name void HAL_NOR_MspDeInit (NOR_HandleTypeDef * hnor) Function Description NOR MSP DeInit. Parameters hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. Return values None HAL_NOR_MspWait Function Name void HAL_NOR_MspWait (NOR_HandleTypeDef * hnor, uint32_t Timeout) Function Description NOR MSP Wait fro Ready/Busy signal. Parameters Return values 26.3.11 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 hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. Timeout: Maximum timeout value None HAL_NOR_Read_ID DOCID026682 Rev 3 309/654 HAL NOR Generic Driver Function Name Function Description Read NOR flash IDs. Parameters Return values 26.3.12 26.3.13 310/654 HAL status Function Name HAL_StatusTypeDef HAL_NOR_ReturnToReadMode (NOR_HandleTypeDef * hnor) Function Description Returns the NOR memory to Read mode. Parameters hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. Return values HAL status HAL_NOR_Read Function Name HAL_StatusTypeDef HAL_NOR_Read (NOR_HandleTypeDef * hnor, uint32_t * pAddress, uint16_t * pData) Function Description Read data from NOR memory. Parameters hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. pAddress: pointer to Device address pData: : pointer to read data HAL status HAL_NOR_Program Function Name HAL_StatusTypeDef HAL_NOR_Program (NOR_HandleTypeDef * hnor, uint32_t * pAddress, uint16_t * pData) Function Description Program data to NOR memory. Parameters Return values 26.3.15 hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. pNOR_ID: : pointer to NOR ID structure HAL_NOR_ReturnToReadMode Return values 26.3.14 UM1816 HAL_StatusTypeDef HAL_NOR_Read_ID (NOR_HandleTypeDef * hnor, NOR_IDTypeDef * pNOR_ID) 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 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 DOCID026682 Rev 3 UM1816 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 Return values 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 HAL status Notes 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 26.3.18 HAL status HAL_NOR_Erase_Chip Function Name HAL_StatusTypeDef HAL_NOR_Erase_Chip (NOR_HandleTypeDef * hnor, uint32_t Address) Function Description Erase the entire NOR chip. Parameters Return values 26.3.19 hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. BlockAddress: : Block to erase address Address: Device address hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. Address: : Device address HAL status HAL_NOR_Read_CFI DOCID026682 Rev 3 311/654 HAL NOR Generic Driver Function Name Function Description Read NOR flash CFI IDs. Parameters Return values 26.3.20 26.3.21 26.3.22 26.3.23 UM1816 HAL_StatusTypeDef HAL_NOR_Read_CFI (NOR_HandleTypeDef * hnor, NOR_CFITypeDef * pNOR_CFI) 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 HAL_NOR_WriteOperation_Enable Function Name HAL_StatusTypeDef HAL_NOR_WriteOperation_Enable (NOR_HandleTypeDef * hnor) Function Description Enables dynamically NOR write operation. Parameters hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. Return values HAL status HAL_NOR_WriteOperation_Disable Function Name HAL_StatusTypeDef HAL_NOR_WriteOperation_Disable (NOR_HandleTypeDef * hnor) Function Description Disables dynamically NOR write operation. Parameters hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. Return values HAL status HAL_NOR_GetState Function Name HAL_NOR_StateTypeDef HAL_NOR_GetState (NOR_HandleTypeDef * hnor) Function Description return the NOR controller state Parameters hnor: pointer to a NOR_HandleTypeDef structure that contains the configuration information for NOR module. Return values NOR controller state HAL_NOR_GetStatus Function Name HAL_NOR_StatusTypeDef HAL_NOR_GetStatus (NOR_HandleTypeDef * hnor, uint32_t Address, uint32_t Timeout) Function Description Returns the NOR operation status. Parameters Return values 312/654 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, DOCID026682 Rev 3 UM1816 HAL NOR Generic Driver HAL_NOR_STATUS_ERROR or HAL_NOR_STATUS_TIMEOUT 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 UM1816 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 Return value: NOR_WRITE NOR: shifted address value Description: NOR memory write data to specified address. Parameters: __ADDRESS__: NOR memory address __DATA__: Data to write Return value: 314/654 None 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. 316/654 The OPAMP(s) provides several exclusive running modes. Standalone mode DOCID026682 Rev 3 UM1816 HAL OPAMP Generic Driver 2. 3. 4. 5. 6. 7. 8. Follower mode 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 Each OPAMP(s) can be configured in normal and low power mode. 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. 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. Running mode: Follower mode No Inverting Input is connected. The OPAMP(s) output(s) are internally connected to inverting input. The OPAMPs inverting input can be selected among the list shown in Table 19: "OPAMPs inverting/non-inverting inputs for STM32L1 devices". 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 Inverting inputs VM0 VM1 (2) non-inverting inputs OPAMP3 (1) OPAMP1 OPAMP2 PA2 VINM pin PA7 VINM pin PC2 VINM pin PA6 DAC_CH1 DAC_CH2 PC1 DAC_CH2 (3) VP0 (4) DAC_CH1 DAC_CH2 PA1 DAC_CH1 - Notes: (1) (2) (3) OPAMP3 availability depends on device category. NA in follower mode. 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 DOCID026682 Rev 3 OPAMP3 (1) 317/654 HAL OPAMP Generic Driver UM1816 OPAMP1 OPAMP2 PA3 PB0 Output OPAMP3 (1) PC3 Notes: (1) 27.3.2 OPAMP3 availability depends on device category. 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. 2. 3. 4. 5. 6. 318/654 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. 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). Enable the opamp using HAL_OPAMP_Start() function. Disable the opamp using HAL_OPAMP_Stop() function. 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) If needed, unlock the opamp using HAL_OPAMPEx_Unlock() function. 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. 2. 3. 27.3.3 If needed, Fill in the HAL_OPAMP_MspInit() This is the case for instance if you wish to use new OPAMP I/O Configure the opamp using HAL_OPAMP_Init() function: As in configure case, selects first the parameters you wish to modify. 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. Initialization and de-initialization functions This section provides functions allowing to: This section contains the following APIs: 27.3.4 HAL_OPAMP_Init() HAL_OPAMP_DeInit() HAL_OPAMP_MspInit() HAL_OPAMP_MspDeInit() 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: 27.3.5 HAL_OPAMP_Start() HAL_OPAMP_Stop() HAL_OPAMP_SelfCalibrate() Peripheral Control functions This subsection provides a set of functions allowing to control the OPAMP data transfers. This section contains the following APIs: 27.3.6 HAL_OPAMP_Lock() HAL_OPAMP_GetTrimOffset() Peripheral State functions This subsection permit to get in run-time the status of the peripheral. This section contains the following APIs: 27.3.7 HAL_OPAMP_GetState() 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 27.3.8 27.3.9 27.3.10 27.3.11 27.3.12 320/654 UM1816 If the selected opamp is locked, initialization can't be performed. To unlock the configuration, perform a system reset. HAL_OPAMP_DeInit Function Name HAL_StatusTypeDef HAL_OPAMP_DeInit (OPAMP_HandleTypeDef * hopamp) Function Description DeInitializes the OPAMP peripheral. Parameters hopamp: OPAMP handle Return values HAL status Notes Deinitialization can be performed if the OPAMP configuration is locked. (the OPAMP lock is SW in STM32L1) 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 HAL_OPAMP_MspDeInit Function Name void HAL_OPAMP_MspDeInit (OPAMP_HandleTypeDef * hopamp) Function Description DeInitializes OPAMP MSP. Parameters hopamp: OPAMP handle Return values None 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 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 DOCID026682 Rev 3 UM1816 27.3.13 HAL OPAMP Generic Driver HAL_OPAMP_SelfCalibrate Function Name HAL_StatusTypeDef HAL_OPAMP_SelfCalibrate (OPAMP_HandleTypeDef * hopamp) Function Description Run the self calibration of one OPAMP. Parameters hopamp: handle Return values Updated offset trimming values (PMOS & NMOS), user trimming is enabled HAL status Notes 27.3.14 27.3.15 27.3.16 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. 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 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 Trimming value (P or N): range: 0->31 or OPAMP_FACTORYTRIMMING_DUMMY if trimming value is not available Notes 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. 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 UM1816 Return the OPAMP state. Parameters hopamp: : OPAMP handle Return values HAL state 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 Offset trimming P OPAMP_FACTORYTRIMMING_N Offset trimming N OPAMP InvertingInput 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 follower mode OPAMP NonInvertingInput 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 322/654 OPAMP_POWERSUPPLY_LOW Power supply range low (VDDA lower than 2.4V) OPAMP_POWERSUPPLY_HIGH Power supply range high (VDDA higher than 2.4V) 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. Parameters: __HANDLE__: OPAMP handle. Return value: OPAMP_CSR_OPAXPD None Description: Select the OPAMP bit OPAxPD (power-down) corresponding to the selected OPAMP instance. Parameters: __HANDLE__: OPAMP handle Return value: OPAMP_CSR_S3SELX None Description: Select the OPAMP bit S3SELx (switch 3) corresponding to the selected OPAMP instance. Parameters: __HANDLE__: OPAMP handle Return value: OPAMP_CSR_S4SELX None Description: Select the OPAMP bit S4SELx (switch 4) corresponding to the selected OPAMP instance. Parameters: __HANDLE__: OPAMP handle Return value: OPAMP_CSR_S5SELX None Description: Select the OPAMP bit S5SELx (switch 5) corresponding to the selected OPAMP instance. Parameters: DOCID026682 Rev 3 __HANDLE__: OPAMP handle 323/654 HAL OPAMP Generic Driver UM1816 Return value: None Description: OPAMP_CSR_S6SELX Select the OPAMP bit S3SELx (switch 6) corresponding to the selected OPAMP instance. Parameters: __HANDLE__: OPAMP handle Return value: OPAMP_CSR_OPAXCAL_L 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: OPAMP_CSR_OPAXCAL_H 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: OPAMP_CSR_OPAXLPM Select the OPAMP bit OPAxLPM (low power mode) corresponding to the selected OPAMP instance. Parameters: __HANDLE__: OPAMP handle Return value: OPAMP_CSR_ALL_SWITCHES Description: 324/654 None DOCID026682 Rev 3 Select the OPAMP bits of all switches corresponding to the selected OPAMP instance. UM1816 HAL OPAMP Generic Driver Parameters: __HANDLE__: OPAMP handle Return value: None Description: OPAMP_CSR_ANAWSELX Select the OPAMP bit ANAWSELx (switch SanA) corresponding to the selected OPAMP instance. Parameters: __HANDLE__: OPAMP handle Return value: OPAMP_CSR_OPAXCALOUT None Description: Select the OPAMP bit OPAxCALOUT in function of the selected OPAMP instance. Parameters: __HANDLE__: OPAMP handle Return value: OPAMP_OFFSET_TRIM_BITSPOSITION 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: OPAMP_OFFSET_TRIM_SET None Description: DOCID026682 Rev 3 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). 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 Description: IS_OPAMP_TRIMMINGVALUE Check that trimming value is within correct range. Parameters: TRIMMINGVALUE: OPAMP trimming value Return value: IS_OPAMP_FUNCTIONAL_NORMALMODE IS_OPAMP_INVERTING_INPUT IS_OPAMP_POWERMODE IS_OPAMP_POWER_SUPPLY_RANGE IS_OPAMP_TRIMMING IS_OPAMP_FACTORYTRIMMING OPAMP User Trimming 326/654 OPAMP_TRIMMING_FACTORY Factory trimming OPAMP_TRIMMING_USER User trimming DOCID026682 Rev 3 None 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: 28.2.2 HAL_OPAMPEx_Unlock() Extended IO operation functions OPAMP Self calibration. This section contains the following APIs: 28.2.3 28.2.4 HAL_OPAMPEx_SelfCalibrateAll() 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 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 hopamp1: handle hopamp2: handle hopamp3: handle Return values 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 Description: __HAL_OPAMP_OPAMP3OUT_CONNECT_ADC_COMP1 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: __HAL_OPAMP_OPAMP3OUT_DISCONNECT_ADC_COMP1 None 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 OPAMPEx Private Macro OPAMP_INSTANCE_DECIMAL Description: 328/654 DOCID026682 Rev 3 Get the OPAMP instance in decimal number for further processing needs by UM1816 HAL OPAMP Extension Driver HAL OPAMP driver functions. Parameters: __HANDLE__: OPAMP handle Return value: IS_OPAMP_NONINVERTING_INPUT_CHECK_INSTANCE 0: for OPAMP1, "1" for OPAMP2, "2" for OPAMP3 Description: Check OPAMP noninverting input in function of OPAMPx instance. Parameters: __HANDLE__: OPAMP handle INPUT: OPAMP noninverting input Return value: DOCID026682 Rev 3 None 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 29.2.2 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. PCD_EPTypeDef Data Fields 330/654 uint8_t num uint8_t is_in uint8_t is_stall 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 29.2.3 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 PCD_HandleTypeDef Data Fields PCD_TypeDef * Instance PCD_InitTypeDef Init __IO uint8_t USB_Address DOCID026682 Rev 3 331/654 HAL PCD Generic Driver UM1816 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 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. 2. 3. 4. 5. 6. 29.3.2 Declare a PCD_HandleTypeDef handle structure, for example: PCD_HandleTypeDef hpcd; Fill parameters of Init structure in HCD handle Call HAL_PCD_Init() API to initialize the HCD peripheral (Core, Device core, ...) Initialize the PCD low level resources through the HAL_PCD_MspInit() API: a. Enable the PCD/USB Low Level interface clock using __HAL_RCC_USB_CLK_ENABLE); b. Initialize the related GPIO clocks c. Configure PCD pin-out d. Configure PCD NVIC interrupt Associate the Upper USB device stack to the HAL PCD Driver: a. hpcd.pData = pdev; Enable HCD transmission and reception: a. HAL_PCD_Start(); 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 29.3.3 HAL_PCD_Init() HAL_PCD_DeInit() HAL_PCD_MspInit() HAL_PCD_MspDeInit() IO operation functions This subsection provides a set of functions allowing to manage the PCD data transfers. This section contains the following APIs: 29.3.4 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() Peripheral Control functions This subsection provides a set of functions allowing to control the PCD data transfers. This section contains the following APIs: 29.3.5 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() 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: 29.3.6 HAL_PCD_GetState() HAL_PCDEx_SetConnectionState() HAL_PCD_Init Function Name HAL_StatusTypeDef HAL_PCD_Init (PCD_HandleTypeDef * DOCID026682 Rev 3 333/654 HAL PCD Generic Driver UM1816 hpcd) 29.3.7 29.3.8 29.3.9 29.3.10 29.3.11 334/654 Function Description Initializes the PCD according to the specified parameters in the PCD_InitTypeDef and create the associated handle. Parameters hpcd: PCD handle Return values HAL status 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 HAL_PCD_MspInit Function Name void HAL_PCD_MspInit (PCD_HandleTypeDef * hpcd) Function Description Initializes the PCD MSP. Parameters hpcd: PCD handle Return values None HAL_PCD_MspDeInit Function Name void HAL_PCD_MspDeInit (PCD_HandleTypeDef * hpcd) Function Description DeInitializes PCD MSP. Parameters hpcd: PCD handle Return values None HAL_PCD_Start Function Name HAL_StatusTypeDef HAL_PCD_Start (PCD_HandleTypeDef * hpcd) Function Description Start The USB OTG Device. Parameters hpcd: PCD handle Return values HAL status HAL_PCD_Stop Function Name HAL_StatusTypeDef HAL_PCD_Stop (PCD_HandleTypeDef * hpcd) Function Description Stop The USB OTG Device. Parameters hpcd: PCD handle Return values HAL status DOCID026682 Rev 3 UM1816 29.3.12 29.3.13 29.3.14 29.3.15 29.3.16 29.3.17 HAL PCD Generic Driver HAL_PCD_IRQHandler 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 HAL_PCD_DataOutStageCallback Function Name void HAL_PCD_DataOutStageCallback (PCD_HandleTypeDef * hpcd, uint8_t epnum) Function Description Data out stage callbacks. Parameters hpcd: PCD handle epnum: endpoint number Return values None 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 HAL_PCD_SetupStageCallback Function Name void HAL_PCD_SetupStageCallback (PCD_HandleTypeDef * hpcd) Function Description Setup stage callback. Parameters hpcd: ppp handle Return values None 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 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 29.3.18 29.3.19 29.3.20 29.3.21 29.3.22 29.3.23 336/654 UM1816 None HAL_PCD_SuspendCallback Function Name void HAL_PCD_SuspendCallback (PCD_HandleTypeDef * hpcd) Function Description Suspend event callbacks. Parameters hpcd: PCD handle Return values None HAL_PCD_ResumeCallback Function Name void HAL_PCD_ResumeCallback (PCD_HandleTypeDef * hpcd) Function Description Resume event callbacks. Parameters hpcd: PCD handle Return values None HAL_PCD_ISOOUTIncompleteCallback Function Name void HAL_PCD_ISOOUTIncompleteCallback (PCD_HandleTypeDef * hpcd, uint8_t epnum) Function Description Incomplete ISO OUT callbacks. Parameters hpcd: PCD handle epnum: endpoint number Return values None HAL_PCD_ISOINIncompleteCallback Function Name void HAL_PCD_ISOINIncompleteCallback (PCD_HandleTypeDef * hpcd, uint8_t epnum) Function Description Incomplete ISO IN callbacks. Parameters hpcd: PCD handle epnum: endpoint number Return values None HAL_PCD_ConnectCallback Function Name void HAL_PCD_ConnectCallback (PCD_HandleTypeDef * hpcd) Function Description Connection event callbacks. Parameters hpcd: PCD handle Return values None HAL_PCD_DisconnectCallback DOCID026682 Rev 3 UM1816 29.3.24 29.3.25 29.3.26 29.3.27 29.3.28 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 HAL_PCD_DevConnect Function Name HAL_StatusTypeDef HAL_PCD_DevConnect (PCD_HandleTypeDef * hpcd) Function Description Connect the USB device. Parameters hpcd: PCD handle Return values HAL status HAL_PCD_DevDisconnect Function Name HAL_StatusTypeDef HAL_PCD_DevDisconnect (PCD_HandleTypeDef * hpcd) Function Description Disconnect the USB device. Parameters hpcd: PCD handle Return values HAL status HAL_PCD_SetAddress Function Name HAL_StatusTypeDef HAL_PCD_SetAddress (PCD_HandleTypeDef * hpcd, uint8_t address) Function Description Set the USB Device address. Parameters hpcd: PCD handle address: new device address Return values HAL status HAL_PCD_EP_Open Function Name HAL_StatusTypeDef HAL_PCD_EP_Open (PCD_HandleTypeDef * hpcd, uint8_t ep_addr, uint16_t ep_mps, uint8_t ep_type) Function Description Open and configure an endpoint. Parameters hpcd: PCD handle ep_addr: endpoint address ep_mps: endpoint max packert size ep_type: endpoint type Return values HAL status HAL_PCD_EP_Close Function Name HAL_StatusTypeDef HAL_PCD_EP_Close DOCID026682 Rev 3 337/654 HAL PCD Generic Driver UM1816 (PCD_HandleTypeDef * hpcd, uint8_t ep_addr) 29.3.29 29.3.30 29.3.31 29.3.32 338/654 Function Description Deactivate an endpoint. Parameters hpcd: PCD handle ep_addr: endpoint address Return values HAL status HAL_PCD_EP_Receive Function Name HAL_StatusTypeDef HAL_PCD_EP_Receive (PCD_HandleTypeDef * hpcd, uint8_t ep_addr, uint8_t * pBuf, uint32_t len) Function Description Receive an amount of data. Parameters hpcd: PCD handle ep_addr: endpoint address pBuf: pointer to the reception buffer len: amount of data to be received Return values HAL status HAL_PCD_EP_GetRxCount Function Name uint16_t HAL_PCD_EP_GetRxCount (PCD_HandleTypeDef * hpcd, uint8_t ep_addr) Function Description Get Received Data Size. Parameters hpcd: PCD handle ep_addr: endpoint address Return values Data Size HAL_PCD_EP_Transmit Function Name HAL_StatusTypeDef HAL_PCD_EP_Transmit (PCD_HandleTypeDef * hpcd, uint8_t ep_addr, uint8_t * pBuf, uint32_t len) Function Description Send an amount of data. Parameters hpcd: PCD handle ep_addr: endpoint address pBuf: pointer to the transmission buffer len: amount of data to be sent Return values HAL status HAL_PCD_EP_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 DOCID026682 Rev 3 UM1816 HAL PCD Generic Driver Return values 29.3.33 29.3.34 29.3.35 29.3.36 29.3.37 HAL status HAL_PCD_EP_ClrStall Function Name HAL_StatusTypeDef HAL_PCD_EP_ClrStall (PCD_HandleTypeDef * hpcd, uint8_t ep_addr) Function Description Clear a STALL condition over in an endpoint. Parameters hpcd: PCD handle ep_addr: endpoint address Return values HAL status HAL_PCD_EP_Flush Function Name HAL_StatusTypeDef HAL_PCD_EP_Flush (PCD_HandleTypeDef * hpcd, uint8_t ep_addr) Function Description Flush an endpoint. Parameters hpcd: PCD handle ep_addr: endpoint address Return values HAL status HAL_PCD_ActivateRemoteWakeup Function Name HAL_StatusTypeDef HAL_PCD_ActivateRemoteWakeup (PCD_HandleTypeDef * hpcd) Function Description HAL_PCD_ActivateRemoteWakeup : active remote wakeup signalling. Parameters hpcd: PCD handle Return values status HAL_PCD_DeActivateRemoteWakeup Function Name HAL_StatusTypeDef HAL_PCD_DeActivateRemoteWakeup (PCD_HandleTypeDef * hpcd) Function Description HAL_PCD_DeActivateRemoteWakeup : de-active remote wakeup signalling. Parameters hpcd: PCD handle Return values status 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 UM1816 HAL_PCDEx_SetConnectionState Function Name 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 __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: PCD_GET_EPTYPE 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 UM1816 Return value: Endpoint: Type Description: PCD_FreeUserBuffer 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: PCD_GET_DB_DIR gets direction of the double buffered endpoint Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. Return value: PCD_SET_EP_TX_STATUS 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: PCD_SET_EP_RX_STATUS 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: 342/654 DOCID026682 Rev 3 UM1816 HAL PCD Generic Driver PCD_SET_EP_TXRX_STATUS 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: PCD_GET_EP_TX_STATUS 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. Return value: status PCD_GET_EP_RX_STATUS Description: PCD_SET_EP_TX_VALID 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 UM1816 Description: PCD_SET_EP_KIND set & clear EP_KIND bit. Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. Return value: None PCD_CLEAR_EP_KIND Description: PCD_SET_OUT_STATUS Sets/clears directly STATUS_OUT bit in the endpoint register. Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. Return value: None PCD_CLEAR_OUT_STATUS PCD_SET_EP_DBUF Description: Sets/clears directly EP_KIND bit in the endpoint register. Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. Return value: None PCD_CLEAR_EP_DBUF PCD_CLEAR_RX_EP_CTR Description: Clears bit CTR_RX / CTR_TX in the endpoint register. Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. Return value: 344/654 None DOCID026682 Rev 3 UM1816 HAL PCD Generic Driver PCD_CLEAR_TX_EP_CTR Description: PCD_RX_DTOG Toggles DTOG_RX / DTOG_TX bit in the endpoint register. Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. Return value: None PCD_TX_DTOG Description: PCD_CLEAR_RX_DTOG Clears DTOG_RX / DTOG_TX bit in the endpoint register. Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. Return value: None PCD_CLEAR_TX_DTOG Description: PCD_SET_EP_ADDRESS Sets address in an endpoint register. Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. bAddr: Address. Return value: None 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 Description: sets address of the tx/rx buffer. Parameters: DOCID026682 Rev 3 345/654 HAL PCD Generic Driver UM1816 USBx: USB peripheral instance register address. bEpNum: Endpoint Number. wAddr: address to be set (must be word aligned). Return value: None PCD_SET_EP_RX_ADDRESS PCD_GET_EP_TX_ADDRESS Description: Gets address of the tx/rx buffer. Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. Return value: address: of the buffer. PCD_GET_EP_RX_ADDRESS Description: PCD_CALC_BLK32 Sets counter of rx buffer with no. Parameters: dwReg: Register wCount: Counter. wNBlocks: no. of Blocks. Return value: None PCD_CALC_BLK2 PCD_SET_EP_CNT_RX_REG PCD_SET_EP_RX_DBUF0_CNT PCD_SET_EP_TX_CNT Description: sets counter for the tx/rx buffer. Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. wCount: Counter value. Return value: PCD_GET_EP_TX_CNT Description: 346/654 None gets counter of the tx buffer. DOCID026682 Rev 3 UM1816 HAL PCD Generic Driver Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. Return value: Counter: value PCD_GET_EP_RX_CNT PCD_SET_EP_DBUF0_ADDR 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 PCD_SET_EP_DBUF1_ADDR PCD_SET_EP_DBUF_ADDR 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: PCD_GET_EP_DBUF0_ADDR 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 PCD_GET_EP_DBUF1_ADDR PCD_SET_EP_DBUF0_CNT Description: Gets buffer 0/1 address of a double buffer DOCID026682 Rev 3 347/654 HAL PCD Generic Driver 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 PCD_SET_EP_DBUF1_CNT PCD_SET_EP_DBUF_CNT PCD_GET_EP_DBUF0_CNT Description: Gets buffer 0/1 rx/tx counter for double buffering. Parameters: USBx: USB peripheral instance register address. bEpNum: Endpoint Number. Return value: None PCD_GET_EP_DBUF1_CNT 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: 30.2.2 HAL_PCDEx_PMAConfig() 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: 31.3.2 HAL_PWR_DeInit() HAL_PWR_EnableBkUpAccess() HAL_PWR_DisableBkUpAccess() Peripheral Control functions PVD configuration 350/654 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). 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: 31.3.3 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() HAL_PWR_DeInit Function Name void HAL_PWR_DeInit (void ) Function Description Deinitializes the PWR peripheral registers to their default reset values. Return values None Notes 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 31.3.5 354/654 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 None Notes If the HSE divided by 2, 4, 8 or 16 is used as the RTC clock, the Backup Domain Access should be kept enabled. HAL_PWR_DisableBkUpAccess Function Name void HAL_PWR_DisableBkUpAccess (void ) Function Description Disables access to the backup domain (RTC registers, RTC backup data registers). Return values None Notes If the HSE divided by 2, 4, 8 or 16 is used as the RTC clock, DOCID026682 Rev 3 UM1816 31.3.6 31.3.7 31.3.8 31.3.9 31.3.10 HAL PWR Generic Driver the Backup Domain Access should be kept enabled. HAL_PWR_ConfigPVD Function Name void HAL_PWR_ConfigPVD (PWR_PVDTypeDef * sConfigPVD) Function Description Configures the voltage threshold detected by the Power Voltage Detector(PVD). Parameters sConfigPVD: pointer to an PWR_PVDTypeDef structure that contains the configuration information for the PVD. Return values None Notes Refer to the electrical characteristics of your device datasheet for more details about the voltage threshold corresponding to each detection level. HAL_PWR_EnablePVD Function Name void HAL_PWR_EnablePVD (void ) Function Description Enables the Power Voltage Detector(PVD). Return values None HAL_PWR_DisablePVD Function Name void HAL_PWR_DisablePVD (void ) Function Description Disables the Power Voltage Detector(PVD). Return values None HAL_PWR_EnableWakeUpPin Function Name void HAL_PWR_EnableWakeUpPin (uint32_t WakeUpPinx) Function Description Enables the WakeUp PINx functionality. Parameters 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 Return values None HAL_PWR_DisableWakeUpPin Function Name void HAL_PWR_DisableWakeUpPin (uint32_t WakeUpPinx) Function Description Disables the WakeUp PINx functionality. Parameters 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 Return values None DOCID026682 Rev 3 355/654 HAL PWR Generic Driver 31.3.11 UM1816 HAL_PWR_EnterSLEEPMode Function Name void HAL_PWR_EnterSLEEPMode (uint32_t Regulator, uint8_t SLEEPEntry) Function Description Enters Sleep mode. Parameters 31.3.12 Return values None Notes In Sleep mode, all I/O pins keep the same state as in Run mode. 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 None Notes 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 356/654 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 void HAL_PWR_EnterSTANDBYMode (void ) DOCID026682 Rev 3 UM1816 31.3.14 31.3.15 31.3.16 31.3.17 HAL PWR Generic Driver Function Description Enters Standby mode. Return values None Notes 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. HAL_PWR_EnableSleepOnExit Function Name void HAL_PWR_EnableSleepOnExit (void ) Function Description Indicates Sleep-On-Exit when returning from Handler mode to Thread mode. Return values None Notes Set SLEEPONEXIT bit of SCR register. When this bit is set, the processor re-enters SLEEP mode when an interruption handling is over. Setting this bit is useful when the processor is expected to run only on interruptions handling. HAL_PWR_DisableSleepOnExit Function Name void HAL_PWR_DisableSleepOnExit (void ) Function Description Disables Sleep-On-Exit feature when returning from Handler mode to Thread mode. Return values None Notes Clears SLEEPONEXIT bit of SCR register. When this bit is set, the processor re-enters SLEEP mode when an interruption handling is over. HAL_PWR_EnableSEVOnPend Function Name void HAL_PWR_EnableSEVOnPend (void ) Function Description Enables CORTEX 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. 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 31.3.19 UM1816 HAL_PWR_PVD_IRQHandler Function Name void HAL_PWR_PVD_IRQHandler (void ) Function Description This function handles the PWR PVD interrupt request. Return values None Notes This API should be called under the PVD_IRQHandler(). HAL_PWR_PVDCallback Function Name void HAL_PWR_PVDCallback (void ) Function Description PWR PVD interrupt callback. Return values None 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: 358/654 DOCID026682 Rev 3 __REGULATOR__: specifies the regulator output voltage to achieve a tradeoff between performance and power consumption when the device does not operate at the maximum UM1816 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: __HAL_PWR_GET_FLAG 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 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: __HAL_PWR_CLEAR_FLAG The: new state of __FLAG__ (TRUE or FALSE). Description: Clear the PWR's pending flags. Parameters: __HAL_PWR_PVD_EXTI_ENABLE_IT __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: __HAL_PWR_PVD_EXTI_DISABLE_IT None. Description: Disable interrupt on PVD Exti Line 16. Return value: __HAL_PWR_PVD_EXTI_ENABLE_EVENT None. Description: Enable event on PVD Exti Line 16. Return value: 360/654 DOCID026682 Rev 3 UM1816 HAL PWR Generic Driver __HAL_PWR_PVD_EXTI_DISABLE_EVENT None. Description: Disable event on PVD Exti Line 16. Return value: __HAL_PWR_PVD_EXTI_ENABLE_FALLING _EDGE None. Description: PVD EXTI line configuration: set falling edge trigger. Return value: __HAL_PWR_PVD_EXTI_DISABLE_FALLIN G_EDGE None. Description: Disable the PVD Extended Interrupt Falling Trigger. Return value: __HAL_PWR_PVD_EXTI_ENABLE_RISING_ EDGE None. Description: PVD EXTI line configuration: set rising edge trigger. Return value: __HAL_PWR_PVD_EXTI_DISABLE_RISING _EDGE None. Description: Disable the PVD Extended Interrupt Rising Trigger. Return value: __HAL_PWR_PVD_EXTI_ENABLE_RISING_ FALLING_EDGE None. Description: PVD EXTI line configuration: set rising & falling edge trigger. Return value: __HAL_PWR_PVD_EXTI_DISABLE_RISING _FALLING_EDGE None. Description: Disable the PVD Extended Interrupt Rising & Falling Trigger. Return value: __HAL_PWR_PVD_EXTI_GET_FLAG None. Description: DOCID026682 Rev 3 Check whether the specified PVD EXTI interrupt flag is set or not. 361/654 HAL PWR Generic Driver UM1816 Return value: __HAL_PWR_PVD_EXTI_CLEAR_FLAG EXTI: PVD Line Status. Description: Clear the PVD EXTI flag. Return value: __HAL_PWR_PVD_EXTI_GENERATE_SWIT None. 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 HAL PWR Generic Driver basic mode is used PWR_PVD_MODE_IT_RISING External Interrupt Mode with Rising edge trigger detection PWR_PVD_MODE_IT_FALLING External Interrupt Mode with Falling edge trigger detection PWR_PVD_MODE_IT_RISING_FALLING External Interrupt Mode with Rising/Falling edge trigger detection PWR_PVD_MODE_EVENT_RISING Event Mode with Rising edge trigger detection PWR_PVD_MODE_EVENT_FALLING Event Mode with Falling edge trigger detection PWR_PVD_MODE_EVENT_RISING_FALLING Event Mode with Rising/Falling edge trigger detection PWR 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 DOCID026682 Rev 3 363/654 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: 32.2.2 32.2.3 32.2.4 32.2.5 364/654 HAL_PWREx_GetVoltageRange() HAL_PWREx_EnableFastWakeUp() HAL_PWREx_DisableFastWakeUp() HAL_PWREx_EnableUltraLowPower() HAL_PWREx_DisableUltraLowPower() HAL_PWREx_EnableLowPowerRunMode() HAL_PWREx_DisableLowPowerRunMode() 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) 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. HAL_PWREx_DisableFastWakeUp Function Name void HAL_PWREx_DisableFastWakeUp (void ) Function Description Disables the Fast WakeUp from Ultra Low Power mode. Return values None HAL_PWREx_EnableUltraLowPower Function Name void HAL_PWREx_EnableUltraLowPower (void ) Function Description Enables the Ultra Low Power mode. Return values None DOCID026682 Rev 3 UM1816 32.2.6 32.2.7 HAL PWR Extension Driver HAL_PWREx_DisableUltraLowPower Function Name void HAL_PWREx_DisableUltraLowPower (void ) Function Description Disables the Ultra Low Power mode. Return values 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 None 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 33.2.2 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 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 33.2.3 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 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: 33.3.2 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 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. 33.3.3 For AHB & APB peripherals, a dummy read to the peripheral register has been inserted in each __HAL_RCC_PPP_CLK_ENABLE() macro. 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. 2. 3. 4. 5. 6. 368/654 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. HSI (high-speed internal), 16 MHz factory-trimmed RC used directly or through the PLL as System clock source. LSI (low-speed internal), ~37 KHz low consumption RC used as IWDG and/or RTC clock source. 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. LSE (low-speed external), 32 KHz oscillator used as RTC clock source. PLL (clocked by HSI or HSE), featuring two different output clocks: The first output is used to generate the high speed system clock (up to 32 MHz) DOCID026682 Rev 3 UM1816 HAL RCC Generic Driver 7. 8. The second output is used to generate the clock for the USB OTG FS (48 MHz) CSS (Clock security system), once enable using the macro __HAL_RCC_CSS_ENABLE() and if a HSE clock failure occurs(HSE used directly or through PLL as System clock source), the System 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. 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. 2. 3. 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. 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"). 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 Latency HCLK clock frequency (MHz) voltage range 1 (1.8 V) voltage range 2 (1.5 V) voltage range 3 (1.2 V) 0W(1CPU cycles) 0 < HCLK ≤ 16 0 < HCLK ≤ 8 0 < HCLK ≤ 2 1WS(2CPU cycles) 16< HCLK ≤ 32 8 < HCLK ≤ 16 2 < HCLK ≤ 4 Table 22: Clock frequency versus product voltage range Product voltage range Clock frequency MSI HSI HSE PLL Range 1 (1.8 V) 4.2 MHz 16 MHz 32 MHz HSE (external clock) or 24 MHz (crystal) 32 MHz (PLLVCO max = 96 MHz) Range 2 (1.5 V) 4.2 MHz 16 MHz 16 MHz 16 MHz (PLLVCO max = 48 MHz) Range 3 (1.2 V) 4.2 MHz NA 8 MHz 4 MHz (PLLVCO max = 24 MHz) This section contains the following APIs: HAL_RCC_DeInit() DOCID026682 Rev 3 369/654 HAL RCC Generic Driver 33.3.4 UM1816 HAL_RCC_OscConfig() HAL_RCC_ClockConfig() Peripheral Control functions This subsection provides a set of functions allowing to control the RCC Clocks frequencies. This section contains the following APIs: 33.3.5 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() 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 33.3.7 370/654 HAL_RCC_OscConfig Function Name HAL_StatusTypeDef HAL_RCC_OscConfig (RCC_OscInitTypeDef * RCC_OscInitStruct) Function Description Initializes the RCC Oscillators according to the specified parameters in the RCC_OscInitTypeDef. Parameters RCC_OscInitStruct: pointer to an RCC_OscInitTypeDef structure that contains the configuration information for the RCC Oscillators. Return values HAL status Notes The PLL is not disabled when used as system clock. 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 DOCID026682 Rev 3 UM1816 HAL RCC Generic Driver specified parameters in the RCC_ClkInitStruct. Parameters RCC_ClkInitStruct: pointer to an RCC_OscInitTypeDef structure that contains the configuration information for the RCC peripheral. FLatency: FLASH Latency This parameter can be one of the following values: FLASH_LATENCY_0: FLASH 0 Latency cycleFLASH_LATENCY_1: FLASH 1 Latency cycle Return values HAL status Notes 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 33.3.9 33.3.10 33.3.11 UM1816 None MCO pin should be configured in alternate function mode. 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 CortexM3 NMI (Non-Maskable Interrupt) exception vector. HAL_RCC_DisableCSS Function Name void HAL_RCC_DisableCSS (void ) Function Description Disables the Clock Security System. Return values 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 None DOCID026682 Rev 3 UM1816 HAL RCC Generic Driver 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 33.3.14 33.3.15 33.3.16 Each time SYSCLK changes, this function must be called to update the right SYSCLK value. Otherwise, any configuration based on this function will be incorrect. HAL_RCC_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. HAL_RCC_GetPCLK2Freq Function Name uint32_t HAL_RCC_GetPCLK2Freq (void ) Function Description Returns the PCLK2 frequency. Return values PCLK2 frequency Notes Each time PCLK2 changes, this function must be called to update the right PCLK2 value. Otherwise, any configuration based on this function will be incorrect. HAL_RCC_GetOscConfig Function Name void HAL_RCC_GetOscConfig (RCC_OscInitTypeDef * RCC_OscInitStruct) Function Description Configures the RCC_OscInitStruct according to the internal RCC configuration registers. Parameters RCC_OscInitStruct: pointer to an RCC_OscInitTypeDef structure that will be configured. Return values None HAL_RCC_GetClockConfig Function Name void HAL_RCC_GetClockConfig (RCC_ClkInitTypeDef * RCC_ClkInitStruct, uint32_t * pFLatency) DOCID026682 Rev 3 373/654 HAL RCC Generic Driver Function Description Parameters Return values 33.3.17 33.3.18 UM1816 Get the RCC_ClkInitStruct according to the internal RCC configuration registers. RCC_ClkInitStruct: pointer to an RCC_ClkInitTypeDef structure that contains the current clock configuration. pFLatency: Pointer on the Flash Latency. None HAL_RCC_NMI_IRQHandler Function Name void HAL_RCC_NMI_IRQHandler (void ) Function Description This function handles the RCC CSS interrupt request. Return values None Notes This API should be called under the NMI_Handler(). HAL_RCC_CSSCallback Function Name void HAL_RCC_CSSCallback (void ) Function Description RCC Clock Security System interrupt callback. Return values none 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 HAL RCC Generic Driver 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 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 Generic Driver __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 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 Generic Driver __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 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 Generic Driver __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 Internal High Speed clock ready flag RCC_FLAG_MSIRDY MSI clock ready flag RCC_FLAG_HSERDY External High Speed clock ready flag RCC_FLAG_PLLRDY PLL clock ready flag RCC_FLAG_LSIRDY Internal Low Speed oscillator Ready RCC_FLAG_LSECSS CSS on LSE failure Detection DOCID026682 Rev 3 381/654 HAL RCC Generic Driver RCC_FLAG_RMV UM1816 Remove reset flag RCC_FLAG_OBLRST Options bytes loading reset flag RCC_FLAG_PINRST PIN reset flag RCC_FLAG_PORRST POR/PDR reset flag RCC_FLAG_SFTRST Software Reset flag 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 Description: Enable RCC interrupt. Parameters: __HAL_RCC_DISABLE_IT __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: 382/654 __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 || DOCID026682 Rev 3 UM1816 HAL RCC Generic Driver STM32L151xB || STM32L152xB devices) Description: __HAL_RCC_CLEAR_IT 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: __HAL_RCC_GET_IT 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: __HAL_RCC_CLEAR_RESET_FLAGS The: new state of __INTERRUPT__ (TRUE or FALSE). 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 UM1816 RCC_FLAG_WWDGRST, RCC_FLAG_LPWRRST Description: __HAL_RCC_GET_FLAG 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: 384/654 __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 HSE clock deactivation RCC_HSE_ON 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 HSI clock deactivation RCC_HSI_ON HSI clock activation RCC_HSICALIBRATION_DEFAULT HSI Configuration Notes: __HAL_RCC_HSI_ENABLE 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. __HAL_RCC_HSI_DISABLE __HAL_RCC_HSI_CALIBRATIONVALUE_ADJUS T Description: macro to adjust the Internal High Speed oscillator (HSI) calibration value. Parameters: _HSICALIBRATIONVALUE_: specifies the calibration trimming value. (default is RCC_HSICALIBRATION_DEFA ULT). This parameter must be a number between 0 and 0x1F. Notes: Interrupts 386/654 DOCID026682 Rev 3 The calibration is used to compensate for the variations in voltage and temperature that influence the frequency of the internal HSI RC. UM1816 HAL RCC Generic Driver RCC_IT_LSIRDY LSI Ready Interrupt flag RCC_IT_LSERDY LSE Ready Interrupt flag RCC_IT_HSIRDY HSI Ready Interrupt flag RCC_IT_HSERDY HSE Ready Interrupt flag RCC_IT_PLLRDY PLL Ready Interrupt flag RCC_IT_MSIRDY MSI Ready Interrupt flag RCC_IT_LSECSS LSE Clock Security System Interrupt flag RCC_IT_CSS Clock Security System Interrupt flag LSE Config RCC_LSE_OFF LSE clock deactivation RCC_LSE_ON LSE clock activation RCC_LSE_BYPASS External clock source for LSE clock LSE Configuration __HAL_RCC_LSE_CONFIG Description: Macro to configure the External Low Speed oscillator (LSE). Parameters: __STATE__: specifies the new state of the LSE. This parameter can be one of the following values: RCC_LSE_OFF: turn OFF the LSE oscillator, LSERDY flag goes low after 6 LSE oscillator clock cycles. RCC_LSE_ON: turn ON the LSE oscillator. RCC_LSE_BYPASS: LSE oscillator bypassed with external clock. Notes: 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 LSI clock deactivation RCC_LSI_ON LSI clock activation LSI Configuration __HAL_RCC_LSI_ENABLE Notes: After enabling the LSI, the application software should wait on LSIRDY flag to be set indicating that LSI clock DOCID026682 Rev 3 387/654 HAL RCC Generic Driver 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. __HAL_RCC_LSI_DISABLE MCO1 Clock Source RCC_MCO1SOURCE_NOCLOCK RCC_MCO1SOURCE_SYSCLK RCC_MCO1SOURCE_MSI 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 MCO1 to be compliant with other families with 2 MCOs MSI Clock Range 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 Notes: __HAL_RCC_MSI_ENABLE 388/654 DOCID026682 Rev 3 After enabling the MSI, the UM1816 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. __HAL_RCC_MSI_DISABLE Notes: __HAL_RCC_MSI_CALIBRATIONVALUE_ADJUS T 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. __HAL_RCC_MSI_RANGE_CONFIG __HAL_RCC_GET_MSI_RANGE 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 UM1816 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 390/654 DOCID026682 Rev 3 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 Generic Driver __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 391/654 HAL RCC Generic Driver __HAL_RCC_CRC_CLK_SLEEP_DISABLE UM1816 __HAL_RCC_FLITF_CLK_SLEEP_DISABLE __HAL_RCC_DMA1_CLK_SLEEP_DISABLE __HAL_RCC_TIM2_CLK_SLEEP_ENABLE Notes: __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 __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 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. 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 PLL deactivation RCC_PLL_ON PLL activation PLL Configuration Notes: __HAL_RCC_PLL_ENABLE __HAL_RCC_PLL_DISABLE 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 UM1816 used as system clock source __HAL_RCC_PLL_CONFIG Description: Macro to configure the main PLL clock source, multiplication and division factors. Parameters: __RCC_PLLSOURCE__: specifies the PLL entry clock source. This parameter can be one of the following values: RCC_PLLSOURCE_HSI: HSI oscillator clock selected as PLL clock entry RCC_PLLSOURCE_HSE: HSE oscillator clock selected as PLL clock entry __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: 394/654 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 UM1816 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 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: 396/654 __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 DOCID026682 Rev 3 UM1816 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). __HAL_RCC_RTC_CONFIG __HAL_RCC_GET_RTC_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 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: __HAL_RCC_RTC_ENABLE These macros must be used only after the RTC clock source was selected. Notes: __HAL_RCC_RTC_DISABLE __HAL_RCC_BACKUPRESET_FORC E 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 No clock RCC_RTCCLKSOURCE_LSE LSE oscillator clock used as RTC clock RCC_RTCCLKSOURCE_LSI 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 MSI selected as system clock RCC_SYSCLKSOURCE_HSI HSI selected as system clock RCC_SYSCLKSOURCE_HSE 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 HAL RCC Generic Driver 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 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: 34.3.2 400/654 HAL_RCCEx_PeriphCLKConfig() HAL_RCCEx_GetPeriphCLKConfig() HAL_RCCEx_GetPeriphCLKFreq() HAL_RCCEx_EnableLSECSS() HAL_RCCEx_DisableLSECSS() HAL_RCCEx_PeriphCLKConfig DOCID026682 Rev 3 UM1816 Function Name 34.3.3 34.3.4 34.3.5 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 PeriphClkInit: pointer to an RCC_PeriphCLKInitTypeDef structure that contains the configuration information for the Extended Peripherals clocks(RTC/LCD clock). Return values HAL status 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 PeriphClkInit: pointer to an RCC_PeriphCLKInitTypeDef structure that returns the configuration information for the Extended Peripherals clocks(RTC/LCD clocks). Return values None 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 Frequency in Hz (0: means that no available frequency for the peripheral) Notes Returns 0 if peripheral clock is unknown 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 UM1816 __HAL_RCC_LCD_CLK_ENABLE __HAL_RCC_LCD_CLK_DISABLE __HAL_RCC_TIM5_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_TIM5_CLK_DISABLE __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 UM1816 __HAL_RCC_UART5_CLK_SLEEP_ENABLE __HAL_RCC_UART4_CLK_SLEEP_DISABLE __HAL_RCC_UART5_CLK_SLEEP_DISABLE __HAL_RCC_OPAMP_CLK_SLEEP_ENABLE __HAL_RCC_OPAMP_CLK_SLEEP_DISABLE __HAL_RCC_SDIO_CLK_SLEEP_ENABLE Notes: __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 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. UM1816 HAL RCC Extension Driver __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 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 35.2.2 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 RTC_DateTypeDef Data Fields 408/654 uint8_t WeekDay uint8_t Month uint8_t Date uint8_t Year DOCID026682 Rev 3 UM1816 HAL RTC Generic Driver Field Documentation 35.2.3 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 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. 2. 3. The RTC The LSE oscillator 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. 2. PC14 and PC15 can be used as either GPIO or LSE pins PC13 can be used as a GPIO or as the RTC_AF1 pin When the backup domain is supplied by VBAT (analog switch connected to VBAT because VDD is not present), the following pins are available: 1. 2. 35.3.2 PC14 and PC15 can be used as LSE pins only PC13 can be used as the RTC_AF1 pin 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. 2. 35.3.3 Software reset, triggered by setting the BDRST bit in the RCC Backup domain control register (RCC_BDCR). VDD or VBAT power on, if both supplies have previously been powered off. 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: 35.3.4 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. 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 410/654 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. DOCID026682 Rev 3 UM1816 35.3.5 HAL RTC Generic Driver RTC and low power modes The MCU can be woken up from a low power mode by an RTC alternate function. The RTC alternate functions are the RTC alarms (Alarm A and Alarm B), RTC 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. 2. 3. 4. 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. All RTC registers are Write protected. Writing to the RTC registers is enabled by writing a key into the Write Protection register, RTC_WPR. 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. 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: 35.3.7 HAL_RTC_Init() HAL_RTC_DeInit() HAL_RTC_MspInit() HAL_RTC_MspDeInit() HAL_RTC_SetTime() HAL_RTC_GetTime() HAL_RTC_SetDate() HAL_RTC_GetDate() 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 35.3.8 UM1816 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() RTC Alarm functions This section provides functions allowing to configure Alarm feature This section contains the following APIs: 35.3.9 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() Peripheral State functions This subsection provides functions allowing to Get RTC state This section contains the following APIs: 35.3.10 HAL_RTC_GetState() Peripheral Control functions This subsection provides functions allowing to Wait for RTC Time and Date Synchronization This section contains the following APIs: 35.3.11 35.3.12 HAL_RTC_WaitForSynchro() HAL_RTC_Init Function Name HAL_StatusTypeDef HAL_RTC_Init (RTC_HandleTypeDef * hrtc) Function Description Initializes the RTC peripheral. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values HAL status HAL_RTC_DeInit Function Name 412/654 HAL_StatusTypeDef HAL_RTC_DeInit (RTC_HandleTypeDef * hrtc) DOCID026682 Rev 3 UM1816 35.3.13 35.3.14 35.3.15 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 HAL status HAL status Notes This function doesn't reset the RTC Backup Data registers. This function does not reset the RTC Backup Data registers. HAL_RTC_MspInit Function Name void HAL_RTC_MspInit (RTC_HandleTypeDef * hrtc) Function Description Initializes the RTC MSP. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None HAL_RTC_MspDeInit Function Name void HAL_RTC_MspDeInit (RTC_HandleTypeDef * hrtc) Function Description DeInitializes the RTC MSP. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None 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 35.3.16 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 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 35.3.17 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 Return values HAL status Notes You must call HAL_RTC_GetDate() after HAL_RTC_GetTime() to unlock the values in the higher-order calendar shadow registers to ensure consistency between the time and date values. Reading RTC current time locks the values in calendar shadow registers until Current date is read. HAL_RTC_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 35.3.18 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 HAL status Notes You must call HAL_RTC_GetDate() after HAL_RTC_GetTime() to unlock the values in the higher-order calendar shadow registers to ensure consistency between the time and date values. Reading RTC current time locks the values in calendar shadow registers until Current date is read. HAL_RTC_SetTime Function Name 414/654 HAL status HAL_RTC_GetDate 35.3.19 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_StatusTypeDef HAL_RTC_SetTime (RTC_HandleTypeDef * hrtc, RTC_TimeTypeDef * sTime, uint32_t Format) DOCID026682 Rev 3 UM1816 HAL RTC Generic Driver Function Description Sets RTC current time. Parameters Return values 35.3.20 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 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 35.3.22 HAL status HAL_RTC_SetDate 35.3.21 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 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 HAL status Notes You must call HAL_RTC_GetDate() after HAL_RTC_GetTime() to unlock the values in the higher-order calendar shadow registers to ensure consistency between the time and date values. Reading RTC current time locks the values in calendar shadow registers until Current date is read. HAL_RTC_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 UM1816 35.3.23 Return values HAL status Notes You must call HAL_RTC_GetDate() after HAL_RTC_GetTime() to unlock the values in the higher-order calendar shadow registers to ensure consistency between the time and date values. Reading RTC current time locks the values in calendar shadow registers until Current date is read. HAL_RTC_SetAlarm Function Name HAL_StatusTypeDef HAL_RTC_SetAlarm (RTC_HandleTypeDef * hrtc, RTC_AlarmTypeDef * sAlarm, uint32_t Format) Function Description Sets the specified RTC Alarm. Parameters Return values 35.3.24 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 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 HAL status Notes 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 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 DOCID026682 Rev 3 UM1816 35.3.25 HAL RTC Generic Driver 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 35.3.26 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 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 35.3.27 35.3.28 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 HAL_RTC_AlarmIRQHandler Function Name void HAL_RTC_AlarmIRQHandler (RTC_HandleTypeDef * hrtc) Function Description This function handles Alarm interrupt request. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None HAL_RTC_PollForAlarmAEvent Function Name 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 35.3.30 HAL_RTC_AlarmAEventCallback Function Name void HAL_RTC_AlarmAEventCallback (RTC_HandleTypeDef * hrtc) Function Description Alarm A callback. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None HAL_RTC_DeactivateAlarm Function Name HAL_StatusTypeDef HAL_RTC_DeactivateAlarm (RTC_HandleTypeDef * hrtc, uint32_t Alarm) Function Description Deactive the specified RTC Alarm. Parameters Return values 35.3.31 35.3.32 35.3.33 UM1816 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 HAL_RTC_AlarmIRQHandler Function Name void HAL_RTC_AlarmIRQHandler (RTC_HandleTypeDef * hrtc) Function Description This function handles Alarm interrupt request. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None HAL_RTC_AlarmAEventCallback Function Name void HAL_RTC_AlarmAEventCallback (RTC_HandleTypeDef * hrtc) Function Description Alarm A callback. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None HAL_RTC_PollForAlarmAEvent Function Name HAL_StatusTypeDef HAL_RTC_PollForAlarmAEvent (RTC_HandleTypeDef * hrtc, uint32_t Timeout) Function Description This function handles AlarmA Polling request. Parameters 418/654 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Timeout: Timeout duration DOCID026682 Rev 3 UM1816 HAL RTC Generic Driver Return values 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 35.3.35 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 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 HAL status Notes 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 status HAL_RTC_GetAlarm Function Name HAL_StatusTypeDef HAL_RTC_GetAlarm (RTC_HandleTypeDef * hrtc, RTC_AlarmTypeDef * sAlarm, uint32_t Alarm, uint32_t Format) Function Description Gets the RTC Alarm value and masks. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. sAlarm: Pointer to Date structure Alarm: Specifies the Alarm. This parameter can be one of the following values: RTC_ALARM_A: AlarmARTC_ALARM_B: AlarmB Format: Specifies the format of the entered parameters. This DOCID026682 Rev 3 419/654 HAL RTC Generic Driver UM1816 parameter can be one of the following values: RTC_FORMAT_BIN: Binary data formatRTC_FORMAT_BCD: BCD data format Return values 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 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 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 35.3.39 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 HAL_RTC_WaitForSynchro Function Name HAL_StatusTypeDef HAL_RTC_WaitForSynchro (RTC_HandleTypeDef * hrtc) Function Description Waits until the RTC Time and Date registers (RTC_TR and RTC_DR) are synchronized with RTC APB clock. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values HAL status Notes The RTC Resynchronization mode is write protected, use the __HAL_RTC_WRITEPROTECTION_DISABLE() before calling this function. To read the calendar through the shadow registers after Calendar initialization, calendar update or after wakeup from 420/654 HAL status 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_SECONDS RTC_ALARMMASK_ALL IS_RTC_ALARM_MASK Alarms Definitions RTC_ALARM_A RTC_ALARM_B IS_RTC_ALARM 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 SS[14] is don't care in Alarm comparison.Only SS[13:0] are compared RTC_ALARMSUBSECONDMASK_NONE SS[14:0] are compared and must match to activate alarm. 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: 422/654 DOCID026682 Rev 3 __HANDLE__: RTC UM1816 HAL RTC Generic Driver handle. Return value: __HAL_RTC_WRITEPROTECTION_DISABLE None Description: Disable the write protection for RTC registers. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_WRITEPROTECTION_ENABLE None Description: Enable the write protection for RTC registers. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_ALARMA_ENABLE None Description: Enable the RTC ALARMA peripheral. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_ALARMA_DISABLE None Description: Disable the RTC ALARMA peripheral. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_ALARMB_ENABLE Description: DOCID026682 Rev 3 None Enable the RTC ALARMB peripheral. 423/654 HAL RTC Generic Driver UM1816 Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_ALARMB_DISABLE None Description: Disable the RTC ALARMB peripheral. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_ALARM_ENABLE_IT 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: __HAL_RTC_ALARM_DISABLE_IT None Description: Disable the RTC Alarm interrupt. Parameters: 424/654 DOCID026682 Rev 3 __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 Generic Driver RTC_IT_ALRA: Alarm A interrupt RTC_IT_ALRB: Alarm B interrupt Return value: __HAL_RTC_ALARM_GET_IT 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: __HAL_RTC_ALARM_GET_FLAG 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: __HAL_RTC_ALARM_CLEAR_FLAG Description: DOCID026682 Rev 3 None Clear the RTC Alarm's pending flags. 425/654 HAL RTC Generic Driver 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: __HAL_RTC_ALARM_GET_IT_SOURCE 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: __HAL_RTC_ALARM_EXTI_ENABLE_IT None Description: Enable interrupt on the RTC Alarm associated Exti line. Return value: __HAL_RTC_ALARM_EXTI_DISABLE_IT None Description: Disable interrupt on the RTC Alarm associated Exti line. Return value: __HAL_RTC_ALARM_EXTI_ENABLE_EVENT Description: 426/654 DOCID026682 Rev 3 None Enable event on the RTC Alarm associated Exti line. UM1816 HAL RTC Generic Driver Return value: __HAL_RTC_ALARM_EXTI_DISABLE_EVENT None. Description: Disable event on the RTC Alarm associated Exti line. Return value: __HAL_RTC_ALARM_EXTI_ENABLE_FALLING_EDGE None. Description: Enable falling edge trigger on the RTC Alarm associated Exti line. Return value: __HAL_RTC_ALARM_EXTI_DISABLE_FALLING_EDG E None. Description: Disable falling edge trigger on the RTC Alarm associated Exti line. Return value: __HAL_RTC_ALARM_EXTI_ENABLE_RISING_EDGE None. Description: Enable rising edge trigger on the RTC Alarm associated Exti line. Return value: __HAL_RTC_ALARM_EXTI_DISABLE_RISING_EDGE None. Description: Disable rising edge trigger on the RTC Alarm associated Exti line. Return value: __HAL_RTC_ALARM_EXTI_ENABLE_RISING_FALLIN G_EDGE None. Description: Enable rising & falling edge trigger on the RTC Alarm associated Exti line. Return value: __HAL_RTC_ALARM_EXTI_DISABLE_RISING_FALLIN G_EDGE DOCID026682 Rev 3 None. Description: Disable rising & falling edge trigger on the RTC 427/654 HAL RTC Generic Driver UM1816 Alarm associated Exti line. Return value: __HAL_RTC_ALARM_EXTI_GET_FLAG None. Description: Check whether the RTC Alarm associated Exti line interrupt flag is set or not. Return value: __HAL_RTC_ALARM_EXTI_CLEAR_FLAG Line: Status. Description: Clear the RTC Alarm associated Exti line flag. Return value: __HAL_RTC_ALARM_EXTI_GENERATE_SWIT None. Description: Generate a Software interrupt on RTC Alarm associated Exti line. Return value: 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 428/654 DOCID026682 Rev 3 None. UM1816 HAL RTC Generic Driver 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 429/654 HAL RTC Generic Driver RTC_OUTPUT_POLARITY_HIGH UM1816 RTC_OUTPUT_POLARITY_LOW IS_RTC_OUTPUT_POL Alarm Output Type RTC_OUTPUT_TYPE_OPENDRAIN 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 36.2.2 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 RTC_TimeTypeDef Data Fields uint8_t Hours uint8_t Minutes DOCID026682 Rev 3 431/654 HAL RTC Extension Driver UM1816 uint8_t Seconds uint32_t SubSeconds uint8_t TimeFormat uint32_t DayLightSaving uint32_t StoreOperation Field Documentation 36.2.3 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 RTC_StoreOperation_Definitions RTC_AlarmTypeDef Data Fields RTC_TimeTypeDef AlarmTime uint32_t AlarmMask uint32_t AlarmSubSecondMask uint32_t AlarmDateWeekDaySel uint8_t AlarmDateWeekDay uint32_t Alarm Field Documentation 432/654 RTC_TimeTypeDef RTC_AlarmTypeDef::AlarmTime Specifies the RTC Alarm Time members uint32_t RTC_AlarmTypeDef::AlarmMask Specifies the RTC Alarm Masks. This parameter can be a value of RTC_AlarmMask_Definitions DOCID026682 Rev 3 UM1816 HAL RTC Extension Driver uint32_t RTC_AlarmTypeDef::AlarmSubSecondMask Specifies the RTC Alarm SubSeconds Masks. This parameter can be a value of RTC_Alarm_Sub_Seconds_Masks_Definitions uint32_t RTC_AlarmTypeDef::AlarmDateWeekDaySel Specifies the RTC Alarm is on Date or WeekDay. This parameter can be a value of RTC_AlarmDateWeekDay_Definitions uint8_t RTC_AlarmTypeDef::AlarmDateWeekDay Specifies the RTC Alarm Date/WeekDay. If the Alarm Date is selected, this parameter must be set to a value in the 1-31 range. If the Alarm WeekDay is selected, this parameter can be a value of RTC_WeekDay_Definitions uint32_t RTC_AlarmTypeDef::Alarm Specifies the alarm . This parameter can be a value of RTC_Alarms_Definitions 36.3 RTCEx Firmware driver API description 36.3.1 How to use this driver Enable the RTC domain access. Configure the RTC Prescaler (Asynchronous and Synchronous) and RTC hour format using the HAL_RTC_Init() function. RTC Wakeup configuration To configure the RTC Wakeup Clock source and Counter use the HAL_RTCEx_SetWakeUpTimer() function. You can also configure the RTC Wakeup timer with interrupt mode using the HAL_RTCEx_SetWakeUpTimer_IT() function. To read the RTC WakeUp Counter register, use the HAL_RTCEx_GetWakeUpTimer() function. TimeStamp configuration Configure the RTC_AFx trigger and enable the RTC TimeStamp using the HAL_RTCEx_SetTimeStamp() function. You can also configure the RTC TimeStamp with interrupt mode using the HAL_RTCEx_SetTimeStamp_IT() function. To read the RTC TimeStamp Time and Date register, use the HAL_RTCEx_GetTimeStamp() function. The TIMESTAMP alternate function can be mapped to RTC_AF1 (PC13). Tamper configuration Enable the RTC Tamper and configure the Tamper filter count, trigger Edge or Level according to the Tamper filter (if equal to 0 Edge else Level) value, sampling frequency, precharge or discharge and Pull-UP using the HAL_RTCEx_SetTamper() function. You can configure RTC Tamper with interrupt mode using HAL_RTCEx_SetTamper_IT() function. The TAMPER1 alternate function can be mapped to RTC_AF1 (PC13). DOCID026682 Rev 3 433/654 HAL RTC Extension Driver UM1816 Backup Data Registers configuration 36.3.2 To write to the RTC Backup Data registers, use the HAL_RTCEx_BKUPWrite() function. To read the RTC Backup Data registers, use the HAL_RTCEx_BKUPRead() function. RTC TimeStamp and Tamper functions This section provides functions allowing to configure TimeStamp feature This section contains the following APIs: 36.3.3 HAL_RTCEx_SetTimeStamp() HAL_RTCEx_SetTimeStamp_IT() HAL_RTCEx_DeactivateTimeStamp() HAL_RTCEx_GetTimeStamp() HAL_RTCEx_SetTamper() HAL_RTCEx_SetTamper_IT() HAL_RTCEx_DeactivateTamper() HAL_RTCEx_TamperTimeStampIRQHandler() HAL_RTCEx_TimeStampEventCallback() HAL_RTCEx_Tamper1EventCallback() HAL_RTCEx_Tamper2EventCallback() HAL_RTCEx_Tamper3EventCallback() HAL_RTCEx_PollForTimeStampEvent() HAL_RTCEx_PollForTamper1Event() HAL_RTCEx_PollForTamper2Event() HAL_RTCEx_PollForTamper3Event() RTC Wake-up functions This section provides functions allowing to configure Wake-up feature This section contains the following APIs: 36.3.4 HAL_RTCEx_SetWakeUpTimer() HAL_RTCEx_SetWakeUpTimer_IT() HAL_RTCEx_DeactivateWakeUpTimer() HAL_RTCEx_GetWakeUpTimer() HAL_RTCEx_WakeUpTimerIRQHandler() HAL_RTCEx_WakeUpTimerEventCallback() HAL_RTCEx_PollForWakeUpTimerEvent() Extension Peripheral Control functions This subsection provides functions allowing to 434/654 Writes a data in a specified RTC Backup data register Read a data in a specified RTC Backup data register Sets the Coarse calibration parameters. Deactivates the Coarse calibration parameters Sets the Smooth calibration parameters. Configures the Synchronization Shift Control Settings. Configures the Calibration Pinout (RTC_CALIB) Selection (1Hz or 512Hz). Deactivates the Calibration Pinout (RTC_CALIB) Selection (1Hz or 512Hz). Enables the RTC reference clock detection. DOCID026682 Rev 3 UM1816 HAL RTC Extension Driver Disable the RTC reference clock detection. Enables the Bypass Shadow feature. Disables the Bypass Shadow feature. This section contains the following APIs: 36.3.5 HAL_RTCEx_BKUPWrite() HAL_RTCEx_BKUPRead() HAL_RTCEx_SetCoarseCalib() HAL_RTCEx_DeactivateCoarseCalib() HAL_RTCEx_SetSmoothCalib() HAL_RTCEx_SetSynchroShift() HAL_RTCEx_SetCalibrationOutPut() HAL_RTCEx_DeactivateCalibrationOutPut() HAL_RTCEx_SetRefClock() HAL_RTCEx_DeactivateRefClock() HAL_RTCEx_EnableBypassShadow() HAL_RTCEx_DisableBypassShadow() Extended features functions This section provides functions allowing to: RTC Alram B callback RTC Poll for Alarm B request This section contains the following APIs: 36.3.6 HAL_RTCEx_AlarmBEventCallback() HAL_RTCEx_PollForAlarmBEvent() HAL_RTCEx_SetTimeStamp Function Name HAL_StatusTypeDef HAL_RTCEx_SetTimeStamp (RTC_HandleTypeDef * hrtc, uint32_t TimeStampEdge) Function Description Sets TimeStamp. Parameters 36.3.7 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. TimeStampEdge: Specifies the pin edge on which the TimeStamp is activated. This parameter can be one of the following values: RTC_TIMESTAMPEDGE_RISING: the Time stamp event occurs on the rising edge of the related pin.RTC_TIMESTAMPEDGE_FALLING: the Time stamp event occurs on the falling edge of the related pin. Return values HAL status Notes This API must be called before enabling the TimeStamp feature. HAL_RTCEx_SetTimeStamp_IT Function Name HAL_StatusTypeDef HAL_RTCEx_SetTimeStamp_IT (RTC_HandleTypeDef * hrtc, uint32_t TimeStampEdge) Function Description Sets TimeStamp with Interrupt. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that DOCID026682 Rev 3 435/654 HAL RTC Extension Driver 36.3.8 36.3.9 Return values HAL status Notes This API must be called before enabling the TimeStamp feature. HAL_RTCEx_DeactivateTimeStamp Function Name HAL_StatusTypeDef HAL_RTCEx_DeactivateTimeStamp (RTC_HandleTypeDef * hrtc) Function Description Deactivates TimeStamp. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values HAL status HAL_RTCEx_GetTimeStamp Function Name HAL_StatusTypeDef HAL_RTCEx_GetTimeStamp (RTC_HandleTypeDef * hrtc, RTC_TimeTypeDef * sTimeStamp, RTC_DateTypeDef * sTimeStampDate, uint32_t Format) Function Description Gets the RTC TimeStamp value. Parameters Return values 36.3.10 436/654 UM1816 contains the configuration information for RTC. TimeStampEdge: Specifies the pin edge on which the TimeStamp is activated. This parameter can be one of the following values: RTC_TIMESTAMPEDGE_RISING: the Time stamp event occurs on the rising edge of the related pin.RTC_TIMESTAMPEDGE_FALLING: the Time stamp event occurs on the falling edge of the related pin. hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. sTimeStamp: Pointer to Time structure sTimeStampDate: Pointer to Date structure Format: specifies the format of the entered parameters. This parameter can be one of the following values: RTC_FORMAT_BIN: Binary data format RTC_FORMAT_BCD: BCD data format HAL status HAL_RTCEx_SetTamper Function Name HAL_StatusTypeDef HAL_RTCEx_SetTamper (RTC_HandleTypeDef * hrtc, RTC_TamperTypeDef * sTamper) Function Description Sets Tamper. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. sTamper: Pointer to Tamper Structure. Return values HAL status Notes By calling this API we disable the tamper interrupt for all tampers. DOCID026682 Rev 3 UM1816 36.3.11 36.3.12 HAL RTC Extension Driver HAL_RTCEx_SetTamper_IT Function Name HAL_StatusTypeDef HAL_RTCEx_SetTamper_IT (RTC_HandleTypeDef * hrtc, RTC_TamperTypeDef * sTamper) Function Description Sets Tamper with interrupt. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. sTamper: Pointer to RTC Tamper. Return values HAL status Notes By calling this API we force the tamper interrupt for all tampers. HAL_RTCEx_DeactivateTamper Function Name HAL_StatusTypeDef HAL_RTCEx_DeactivateTamper (RTC_HandleTypeDef * hrtc, uint32_t Tamper) Function Description Deactivates Tamper. Parameters Return values 36.3.13 36.3.14 36.3.15 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Tamper: Selected tamper pin. This parameter can be a value of Tamper Pins Definitions HAL status HAL_RTCEx_TamperTimeStampIRQHandler Function Name void HAL_RTCEx_TamperTimeStampIRQHandler (RTC_HandleTypeDef * hrtc) Function Description This function handles TimeStamp interrupt request. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None HAL_RTCEx_TimeStampEventCallback Function Name void HAL_RTCEx_TimeStampEventCallback (RTC_HandleTypeDef * hrtc) Function Description TimeStamp callback. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None HAL_RTCEx_Tamper1EventCallback Function Name void HAL_RTCEx_Tamper1EventCallback (RTC_HandleTypeDef * hrtc) Function Description Tamper 1 callback. DOCID026682 Rev 3 437/654 HAL RTC Extension Driver Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None 36.3.16 36.3.17 36.3.18 HAL_RTCEx_Tamper2EventCallback Function Name void HAL_RTCEx_Tamper2EventCallback (RTC_HandleTypeDef * hrtc) Function Description Tamper 2 callback. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None HAL_RTCEx_Tamper3EventCallback Function Name void HAL_RTCEx_Tamper3EventCallback (RTC_HandleTypeDef * hrtc) Function Description Tamper 3 callback. Parameters hrtc: RTC handle Return values None HAL_RTCEx_PollForTimeStampEvent Function Name HAL_StatusTypeDef HAL_RTCEx_PollForTimeStampEvent (RTC_HandleTypeDef * hrtc, uint32_t Timeout) Function Description This function handles TimeStamp polling request. Parameters Return values 36.3.19 438/654 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Timeout: Timeout duration HAL status HAL_RTCEx_PollForTamper1Event Function Name HAL_StatusTypeDef HAL_RTCEx_PollForTamper1Event (RTC_HandleTypeDef * hrtc, uint32_t Timeout) Function Description This function handles Tamper1 Polling. Parameters Return values 36.3.20 UM1816 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Timeout: Timeout duration HAL status HAL_RTCEx_PollForTamper2Event Function Name HAL_StatusTypeDef HAL_RTCEx_PollForTamper2Event (RTC_HandleTypeDef * hrtc, uint32_t Timeout) Function Description This function handles Tamper2 Polling. DOCID026682 Rev 3 UM1816 HAL RTC Extension Driver Parameters Return values 36.3.21 36.3.22 HAL status Function Name HAL_StatusTypeDef HAL_RTCEx_PollForTamper3Event (RTC_HandleTypeDef * hrtc, uint32_t Timeout) Function Description This function handles Tamper3 Polling. Parameters hrtc: RTC handle Timeout: Timeout duration Return values HAL status HAL_RTCEx_SetWakeUpTimer Function Name HAL_StatusTypeDef HAL_RTCEx_SetWakeUpTimer (RTC_HandleTypeDef * hrtc, uint32_t WakeUpCounter, uint32_t WakeUpClock) Function Description Sets wake up timer. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. WakeUpCounter: Wake up counter WakeUpClock: Wake up clock HAL status HAL_RTCEx_SetWakeUpTimer_IT Function Name HAL_StatusTypeDef HAL_RTCEx_SetWakeUpTimer_IT (RTC_HandleTypeDef * hrtc, uint32_t WakeUpCounter, uint32_t WakeUpClock) Function Description Sets wake up timer with interrupt. Parameters Return values 36.3.24 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Timeout: Timeout duration HAL_RTCEx_PollForTamper3Event Return values 36.3.23 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. WakeUpCounter: Wake up counter WakeUpClock: Wake up clock HAL status HAL_RTCEx_DeactivateWakeUpTimer Function Name uint32_t HAL_RTCEx_DeactivateWakeUpTimer (RTC_HandleTypeDef * hrtc) Function Description Deactivates wake up timer counter. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values HAL status DOCID026682 Rev 3 439/654 HAL RTC Extension Driver 36.3.25 36.3.26 36.3.27 36.3.28 HAL_RTCEx_GetWakeUpTimer Function Name uint32_t HAL_RTCEx_GetWakeUpTimer (RTC_HandleTypeDef * hrtc) Function Description Gets wake up timer counter. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values Counter value HAL_RTCEx_WakeUpTimerIRQHandler Function Name void HAL_RTCEx_WakeUpTimerIRQHandler (RTC_HandleTypeDef * hrtc) Function Description This function handles Wake Up Timer interrupt request. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None HAL_RTCEx_WakeUpTimerEventCallback Function Name void HAL_RTCEx_WakeUpTimerEventCallback (RTC_HandleTypeDef * hrtc) Function Description Wake Up Timer callback. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None HAL_RTCEx_PollForWakeUpTimerEvent Function Name HAL_StatusTypeDef HAL_RTCEx_PollForWakeUpTimerEvent (RTC_HandleTypeDef * hrtc, uint32_t Timeout) Function Description This function handles Wake Up Timer Polling. Parameters Return values 36.3.29 UM1816 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Timeout: Timeout duration HAL status HAL_RTCEx_BKUPWrite Function Name void HAL_RTCEx_BKUPWrite (RTC_HandleTypeDef * hrtc, uint32_t BackupRegister, uint32_t Data) Function Description Writes a data in a specified RTC Backup data register. Parameters 440/654 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. BackupRegister: RTC Backup data Register number. This parameter can be: RTC_BKP_DRx where x can be from 0 to 19 to specify the register. DOCID026682 Rev 3 UM1816 HAL RTC Extension Driver Return values 36.3.30 Data: Data to be written in the specified RTC Backup data register. None HAL_RTCEx_BKUPRead Function Name uint32_t HAL_RTCEx_BKUPRead (RTC_HandleTypeDef * hrtc, uint32_t BackupRegister) Function Description Reads data from the specified RTC Backup data Register. Parameters Return values 36.3.31 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. BackupRegister: RTC Backup data Register number. This parameter can be: RTC_BKP_DRx where x can be from 0 to 19 to specify the register. Read value HAL_RTCEx_SetCoarseCalib Function Name HAL_StatusTypeDef HAL_RTCEx_SetCoarseCalib (RTC_HandleTypeDef * hrtc, uint32_t CalibSign, uint32_t Value) Function Description Sets the Coarse calibration parameters. Parameters Return values HAL status Notes This Calibration value should be between 0 and 63 when using negative sign with a 2-ppm step. This Calibration value should be between 0 and 126 when using positive sign with a 4-ppm step. 36.3.32 36.3.33 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. CalibSign: Specifies the sign of the coarse calibration value. This parameter can be one of the following values : RTC_CALIBSIGN_POSITIVE: The value sign is positiveRTC_CALIBSIGN_NEGATIVE: The value sign is negative Value: value of coarse calibration expressed in ppm (coded on 5 bits). HAL_RTCEx_DeactivateCoarseCalib Function Name HAL_StatusTypeDef HAL_RTCEx_DeactivateCoarseCalib (RTC_HandleTypeDef * hrtc) Function Description Deactivates the Coarse calibration parameters. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values HAL status HAL_RTCEx_SetSmoothCalib DOCID026682 Rev 3 441/654 HAL RTC Extension Driver Function Name UM1816 HAL_StatusTypeDef HAL_RTCEx_SetSmoothCalib (RTC_HandleTypeDef * hrtc, uint32_t SmoothCalibPeriod, uint32_t SmoothCalibPlusPulses, uint32_t SmouthCalibMinusPulsesValue) Function Description Sets the Smooth calibration parameters. Parameters 36.3.34 Return values HAL status Notes To deactivate the smooth calibration, the field SmoothCalibPlusPulses must be equal to SMOOTHCALIB_PLUSPULSES_RESET and the field SmouthCalibMinusPulsesValue must be equal to 0. HAL_RTCEx_SetSynchroShift Function Name HAL_StatusTypeDef HAL_RTCEx_SetSynchroShift (RTC_HandleTypeDef * hrtc, uint32_t ShiftAdd1S, uint32_t ShiftSubFS) Function Description Configures the Synchronization Shift Control Settings. Parameters 36.3.35 442/654 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. SmoothCalibPeriod: Select the Smooth Calibration Period. This parameter can be can be one of the following values : RTC_SMOOTHCALIB_PERIOD_32SEC: The smooth calibration periode is 32s.RTC_SMOOTHCALIB_PERIOD_16SEC: The smooth calibration periode is 16s.RTC_SMOOTHCALIB_PERIOD_8SEC: The smooth calibartion periode is 8s. SmoothCalibPlusPulses: Select to Set or reset the CALP bit. This parameter can be one of the following values: RTC_SMOOTHCALIB_PLUSPULSES_SET: Add one RTCCLK puls every 2*11 pulses.RTC_SMOOTHCALIB_PLUSPULSES_RESET: No RTCCLK pulses are added. SmouthCalibMinusPulsesValue: Select the value of CALM[8:0] bits. This parameter can be one any value from 0 to 0x000001FF. hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. ShiftAdd1S: Select to add or not 1 second to the time calendar. This parameter can be one of the following values : RTC_SHIFTADD1S_SET: Add one second to the clock calendar.RTC_SHIFTADD1S_RESET: No effect. ShiftSubFS: Select the number of Second Fractions to substitute. This parameter can be one any value from 0 to 0x7FFF. Return values HAL status Notes When REFCKON is set, firmware must not write to Shift control register. HAL_RTCEx_SetCalibrationOutPut DOCID026682 Rev 3 UM1816 Function Name HAL RTC Extension Driver HAL_StatusTypeDef HAL_RTCEx_SetCalibrationOutPut (RTC_HandleTypeDef * hrtc, uint32_t CalibOutput) Function Description Configures the Calibration Pinout (RTC_CALIB) Selection (1Hz or 512Hz). Parameters Return values 36.3.36 36.3.37 36.3.38 36.3.39 hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. CalibOutput: : Select the Calibration output Selection . This parameter can be one of the following values: RTC_CALIBOUTPUT_512HZ: A signal has a regular waveform at 512Hz.RTC_CALIBOUTPUT_1HZ: A signal has a regular waveform at 1Hz. HAL status HAL_RTCEx_DeactivateCalibrationOutPut Function Name HAL_StatusTypeDef HAL_RTCEx_DeactivateCalibrationOutPut (RTC_HandleTypeDef * hrtc) Function Description Deactivates the Calibration Pinout (RTC_CALIB) Selection (1Hz or 512Hz). Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values HAL status HAL_RTCEx_SetRefClock Function Name HAL_StatusTypeDef HAL_RTCEx_SetRefClock (RTC_HandleTypeDef * hrtc) Function Description Enables the RTC reference clock detection. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values HAL status HAL_RTCEx_DeactivateRefClock Function Name HAL_StatusTypeDef HAL_RTCEx_DeactivateRefClock (RTC_HandleTypeDef * hrtc) Function Description Disable the RTC reference clock detection. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values HAL status HAL_RTCEx_EnableBypassShadow Function Name HAL_StatusTypeDef HAL_RTCEx_EnableBypassShadow (RTC_HandleTypeDef * hrtc) Function Description Enables the Bypass Shadow feature. DOCID026682 Rev 3 443/654 HAL RTC Extension Driver Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values HAL status Notes When the Bypass Shadow is enabled the calendar value are taken directly from the Calendar counter. 36.3.40 36.3.41 36.3.42 UM1816 HAL_RTCEx_DisableBypassShadow Function Name HAL_StatusTypeDef HAL_RTCEx_DisableBypassShadow (RTC_HandleTypeDef * hrtc) Function Description Disables the Bypass Shadow feature. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values HAL status Notes When the Bypass Shadow is enabled the calendar value are taken directly from the Calendar counter. HAL_RTCEx_AlarmBEventCallback Function Name void HAL_RTCEx_AlarmBEventCallback (RTC_HandleTypeDef * hrtc) Function Description Alarm B callback. Parameters hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Return values None HAL_RTCEx_PollForAlarmBEvent Function Name HAL_StatusTypeDef HAL_RTCEx_PollForAlarmBEvent (RTC_HandleTypeDef * hrtc, uint32_t Timeout) Function Description This function handles AlarmB Polling request. Parameters Return values hrtc: pointer to a RTC_HandleTypeDef structure that contains the configuration information for RTC. Timeout: Timeout duration HAL status 36.4 RTCEx Firmware driver defines 36.4.1 RTCEx Add 1 Second Parameter Definitions RTC_SHIFTADD1S_RESET RTC_SHIFTADD1S_SET IS_RTC_SHIFT_ADD1S Backup Registers Definitions 444/654 DOCID026682 Rev 3 UM1816 HAL RTC Extension Driver RTC_BKP_DR0 RTC_BKP_DR1 RTC_BKP_DR2 RTC_BKP_DR3 RTC_BKP_DR4 RTC_BKP_DR5 RTC_BKP_DR6 RTC_BKP_DR7 RTC_BKP_DR8 RTC_BKP_DR9 RTC_BKP_DR10 RTC_BKP_DR11 RTC_BKP_DR12 RTC_BKP_DR13 RTC_BKP_DR14 RTC_BKP_DR15 RTC_BKP_DR16 RTC_BKP_DR17 RTC_BKP_DR18 RTC_BKP_DR19 RTC_BKP_DR20 RTC_BKP_DR21 RTC_BKP_DR22 RTC_BKP_DR23 RTC_BKP_DR24 RTC_BKP_DR25 RTC_BKP_DR26 RTC_BKP_DR27 RTC_BKP_DR28 RTC_BKP_DR29 RTC_BKP_DR30 RTC_BKP_DR31 IS_RTC_BKP Calib Output Selection Definitions RTC_CALIBOUTPUT_512HZ RTC_CALIBOUTPUT_1HZ DOCID026682 Rev 3 445/654 HAL RTC Extension Driver IS_RTC_CALIB_OUTPUT UM1816 Digital Calibration Definitions RTC_CALIBSIGN_POSITIVE RTC_CALIBSIGN_NEGATIVE IS_RTC_CALIB_SIGN IS_RTC_CALIB_VALUE RTCEx Exported Macros __HAL_RTC_WAKEUPTIMER_ENABLE Description: Enable the RTC WakeUp Timer peripheral. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_TIMESTAMP_ENABLE None Description: Enable the RTC TimeStamp peripheral. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_WAKEUPTIMER_DISABLE None Description: Disable the RTC WakeUp Timer peripheral. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_TIMESTAMP_DISABLE Description: 446/654 DOCID026682 Rev 3 None Disable the RTC TimeStamp peripheral. UM1816 HAL RTC Extension Driver Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_COARSE_CALIB_ENABLE None Description: Enable the Coarse calibration process. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_COARSE_CALIB_DISABLE None Description: Disable the Coarse calibration process. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_CALIBRATION_OUTPUT_ENABLE None Description: Enable the RTC calibration output. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_CALIBRATION_OUTPUT_DISABLE None Description: Disable the calibration output. Parameters: __HANDLE__: specifies the RTC handle. Return value: DOCID026682 Rev 3 447/654 HAL RTC Extension Driver UM1816 __HAL_RTC_CLOCKREF_DETECTION_ENABLE None Description: Enable the clock reference detection. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_CLOCKREF_DETECTION_DISABLE None Description: Disable the clock reference detection. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_TIMESTAMP_ENABLE_IT None Description: Enable the RTC TimeStamp interrupt. Parameters: __HANDLE__: specifies the RTC handle. __INTERRUPT__: specifies the RTC TimeStamp interrupt sources to be enabled or disabled. This parameter can be: RTC_IT_TS: TimeStamp interrupt Return value: __HAL_RTC_WAKEUPTIMER_ENABLE_IT None Description: Enable the RTC WakeUpTimer interrupt. Parameters: 448/654 DOCID026682 Rev 3 __HANDLE__: UM1816 HAL RTC Extension Driver specifies the RTC handle. __INTERRUPT__: specifies the RTC WakeUpTimer interrupt sources to be enabled or disabled. This parameter can be: RTC_IT_WUT: WakeUpTimer A interrupt Return value: __HAL_RTC_TIMESTAMP_DISABLE_IT None Description: Disable the RTC TimeStamp interrupt. Parameters: __HANDLE__: specifies the RTC handle. __INTERRUPT__: specifies the RTC TimeStamp interrupt sources to be enabled or disabled. This parameter can be: RTC_IT_TS: TimeStamp interrupt Return value: __HAL_RTC_WAKEUPTIMER_DISABLE_IT None Description: Disable the RTC WakeUpTimer interrupt. Parameters: DOCID026682 Rev 3 __HANDLE__: specifies the RTC handle. __INTERRUPT__: specifies the RTC WakeUpTimer interrupt sources to be enabled or disabled. This parameter can be: RTC_IT_WUT: WakeUpTimer A 449/654 HAL RTC Extension Driver UM1816 interrupt Return value: __HAL_RTC_TAMPER1_ENABLE None Description: Enable the RTC Tamper1 input detection. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_TAMPER1_DISABLE None Description: Disable the RTC Tamper1 input detection. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_TAMPER2_ENABLE None Description: Enable the RTC Tamper2 input detection. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_TAMPER2_DISABLE None Description: Disable the RTC Tamper2 input detection. Parameters: 450/654 DOCID026682 Rev 3 __HANDLE__: specifies the RTC handle. UM1816 HAL RTC Extension Driver Return value: __HAL_RTC_TAMPER3_ENABLE None Description: Enable the RTC Tamper3 input detection. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_TAMPER3_DISABLE None Description: Disable the RTC Tamper3 input detection. Parameters: __HANDLE__: specifies the RTC handle. Return value: __HAL_RTC_TAMPER_GET_IT None Description: Check whether the specified RTC Tamper interrupt has occurred or not. Parameters: __HANDLE__: specifies the RTC handle. __INTERRUPT__: specifies the RTC Tamper interrupt sources to be enabled or disabled. This parameter can be: RTC_IT_TAMP1 RTC_IT_TAMP2 RTC_IT_TAMP3 Return value: __HAL_RTC_TAMPER_ENABLE_IT Description: DOCID026682 Rev 3 None Enable the RTC 451/654 HAL RTC Extension Driver UM1816 Tamper interrupt. Parameters: __HANDLE__: specifies the RTC handle. __INTERRUPT__: specifies the RTC Tamper interrupt sources to be enabled This parameter can be any combination of the following values: RTC_IT_TAMP1: Tamper1 interrupt RTC_IT_TAMP2: Tamper2 interrupt (*) RTC_IT_TAMP3: Tamper3 interrupt (*) Return value: None Notes: __HAL_RTC_TAMPER_DISABLE_IT (*) Available only on devices STM32L100xBA, STM32L151xBA, STM32L152xBA, STM32L100xC, STM32L151xC, STM32L152xC, STM32L162xC, STM32L151xCA, STM32L151xD, STM32L152xCA, STM32L152xD, STM32L162xCA, STM32L162xD, STM32L151xE, STM32L152xE, STM32L162xE STM32L151xDX, STM32L152xDX, STM32L162xDX Description: Disable the RTC Tamper interrupt. Parameters: 452/654 DOCID026682 Rev 3 __HANDLE__: UM1816 HAL RTC Extension Driver specifies the RTC handle. __INTERRUPT__: specifies the RTC Tamper interrupt sources to be disabled. This parameter can be any combination of the following values: RTC_IT_TAMP1: Tamper1 interrupt RTC_IT_TAMP2: Tamper2 interrupt (*) RTC_IT_TAMP3: Tamper3 interrupt (*) Return value: None Notes: __HAL_RTC_TAMPER_GET_IT_SOURCE (*) Available only on devices STM32L100xBA, STM32L151xBA, STM32L152xBA, STM32L100xC, STM32L151xC, STM32L152xC, STM32L162xC, STM32L151xCA, STM32L151xD, STM32L152xCA, STM32L152xD, STM32L162xCA, STM32L162xD, STM32L151xE, STM32L152xE, STM32L162xE STM32L151xDX, STM32L152xDX, STM32L162xDX Description: Check whether the specified RTC Tamper interrupt has been enabled or not. Parameters: DOCID026682 Rev 3 __HANDLE__: specifies the RTC 453/654 HAL RTC Extension Driver UM1816 handle. __INTERRUPT__: specifies the RTC Tamper interrupt source to check. This parameter can be: RTC_IT_TAMP1: Tamper1 interrupt RTC_IT_TAMP2: Tamper2 interrupt (*) RTC_IT_TAMP3: Tamper3 interrupt (*) Return value: None Notes: __HAL_RTC_WAKEUPTIMER_GET_IT (*) Available only on devices STM32L100xBA, STM32L151xBA, STM32L152xBA, STM32L100xC, STM32L151xC, STM32L152xC, STM32L162xC, STM32L151xCA, STM32L151xD, STM32L152xCA, STM32L152xD, STM32L162xCA, STM32L162xD, STM32L151xE, STM32L152xE, STM32L162xE STM32L151xDX, STM32L152xDX, STM32L162xDX Description: Check whether the specified RTC WakeUpTimer interrupt has occurred or not. Parameters: 454/654 DOCID026682 Rev 3 __HANDLE__: specifies the RTC handle. __FLAG__: specifies the RTC UM1816 HAL RTC Extension Driver WakeUpTimer interrupt sources to be enabled or disabled. This parameter can be: RTC_IT_WUT: WakeUpTimer A interrupt Return value: __HAL_RTC_WAKEUPTIMER_GET_IT_SOURCE None Description: Check whether the specified RTC Wake Up timer interrupt has been enabled or not. Parameters: __HANDLE__: specifies the RTC handle. __INTERRUPT__: specifies the RTC Wake Up timer interrupt sources to check. This parameter can be: RTC_IT_WUT: WakeUpTimer interrupt Return value: __HAL_RTC_TIMESTAMP_GET_IT None Description: Check whether the specified RTC TimeStamp interrupt has occurred or not. Parameters: DOCID026682 Rev 3 __HANDLE__: specifies the RTC handle. __INTERRUPT__: specifies the RTC TimeStamp interrupt sources to be enabled or disabled. This parameter can be: RTC_IT_TS: TimeStamp interrupt 455/654 HAL RTC Extension Driver UM1816 Return value: __HAL_RTC_TIMESTAMP_GET_IT_SOURCE None Description: Check whether the specified RTC Time Stamp interrupt has been enabled or not. Parameters: __HANDLE__: specifies the RTC handle. __INTERRUPT__: specifies the RTC Time Stamp interrupt source to check. This parameter can be: RTC_IT_TS: TimeStamp interrupt Return value: __HAL_RTC_TIMESTAMP_GET_FLAG None Description: Get the selected RTC TimeStamp's flag status. Parameters: __HANDLE__: specifies the RTC handle. __FLAG__: specifies the RTC TimeStamp Flag sources to be enabled or disabled. This parameter can be: RTC_FLAG_TSF RTC_FLAG_TS OVF Return value: __HAL_RTC_WAKEUPTIMER_GET_FLAG None Description: Get the selected RTC WakeUpTimer's flag status. Parameters: 456/654 DOCID026682 Rev 3 __HANDLE__: UM1816 HAL RTC Extension Driver specifies the RTC handle. __FLAG__: specifies the RTC WakeUpTimer Flag sources to be enabled or disabled. This parameter can be: RTC_FLAG_WU TF RTC_FLAG_WU TWF Return value: __HAL_RTC_TAMPER_GET_FLAG None Description: Get the selected RTC Tamper's flag status. Parameters: __HANDLE__: specifies the RTC handle. __FLAG__: specifies the RTC Tamper Flag sources to be enabled or disabled. This parameter can be: RTC_FLAG_TA MP1F RTC_FLAG_TA MP2F (*) RTC_FLAG_TA MP3F (*) Return value: None Notes: DOCID026682 Rev 3 (*) Available only on devices STM32L100xBA, STM32L151xBA, STM32L152xBA, STM32L100xC, STM32L151xC, STM32L152xC, STM32L162xC, STM32L151xCA, STM32L151xD, STM32L152xCA, STM32L152xD, STM32L162xCA, STM32L162xD, 457/654 HAL RTC Extension Driver UM1816 STM32L151xE, STM32L152xE, STM32L162xE STM32L151xDX, STM32L152xDX, STM32L162xDX __HAL_RTC_SHIFT_GET_FLAG Description: Get the selected RTC shift operation's flag status. Parameters: __HANDLE__: specifies the RTC handle. __FLAG__: specifies the RTC shift operation Flag is pending or not. This parameter can be: RTC_FLAG_SH PF Return value: __HAL_RTC_TIMESTAMP_CLEAR_FLAG None Description: Clear the RTC Time Stamp's pending flags. Parameters: __HANDLE__: specifies the RTC handle. __FLAG__: specifies the RTC Alarm Flag sources to be enabled or disabled. This parameter can be: RTC_FLAG_TSF Return value: __HAL_RTC_TAMPER_CLEAR_FLAG None Description: Clear the RTC Tamper's pending flags. Parameters: 458/654 DOCID026682 Rev 3 __HANDLE__: specifies the RTC handle. UM1816 HAL RTC Extension Driver __FLAG__: specifies the RTC Tamper Flag sources to be enabled or disabled. This parameter can be: RTC_FLAG_TA MP1F RTC_FLAG_TA MP2F (*) RTC_FLAG_TA MP3F (*) Return value: None Notes: __HAL_RTC_WAKEUPTIMER_CLEAR_FLAG (*) Available only on devices STM32L100xBA, STM32L151xBA, STM32L152xBA, STM32L100xC, STM32L151xC, STM32L152xC, STM32L162xC, STM32L151xCA, STM32L151xD, STM32L152xCA, STM32L152xD, STM32L162xCA, STM32L162xD, STM32L151xE, STM32L152xE, STM32L162xE STM32L151xDX, STM32L152xDX, STM32L162xDX Description: Clear the RTC Wake Up timer's pending flags. Parameters: DOCID026682 Rev 3 __HANDLE__: specifies the RTC handle. __FLAG__: specifies the RTC Tamper Flag sources to be enabled or disabled. This parameter can be: RTC_FLAG_WU TF 459/654 HAL RTC Extension Driver UM1816 Return value: __HAL_RTC_WAKEUPTIMER_EXTI_ENABLE_IT None Description: Enable interrupt on the RTC WakeUp Timer associated Exti line. Return value: __HAL_RTC_WAKEUPTIMER_EXTI_DISABLE_IT None Description: Disable interrupt on the RTC WakeUp Timer associated Exti line. Return value: __HAL_RTC_WAKEUPTIMER_EXTI_ENABLE_EVENT None Description: Enable event on the RTC WakeUp Timer associated Exti line. Return value: __HAL_RTC_WAKEUPTIMER_EXTI_DISABLE_EVENT None. Description: Disable event on the RTC WakeUp Timer associated Exti line. Return value: __HAL_RTC_WAKEUPTIMER_EXTI_ENABLE_FALLING_E DGE None. Description: Enable falling edge trigger on the RTC WakeUp Timer associated Exti line. Return value: __HAL_RTC_WAKEUPTIMER_EXTI_DISABLE_FALLING_E DGE None. Description: Disable falling edge trigger on the RTC WakeUp Timer associated Exti line. Return value: 460/654 DOCID026682 Rev 3 UM1816 HAL RTC Extension Driver __HAL_RTC_WAKEUPTIMER_EXTI_ENABLE_RISING_ED GE None. Description: Enable rising edge trigger on the RTC WakeUp Timer associated Exti line. Return value: __HAL_RTC_WAKEUPTIMER_EXTI_DISABLE_RISING_ED GE None. Description: Disable rising edge trigger on the RTC WakeUp Timer associated Exti line. Return value: __HAL_RTC_WAKEUPTIMER_EXTI_ENABLE_RISING_FA LLING_EDGE None. Description: Enable rising & falling edge trigger on the RTC WakeUp Timer associated Exti line. Return value: __HAL_RTC_WAKEUPTIMER_EXTI_DISABLE_RISING_FA LLING_EDGE None. Description: Disable rising & falling edge trigger on the RTC WakeUp Timer associated Exti line. Return value: __HAL_RTC_WAKEUPTIMER_EXTI_GET_FLAG None. Description: Check whether the RTC WakeUp Timer associated Exti line interrupt flag is set or not. Return value: __HAL_RTC_WAKEUPTIMER_EXTI_CLEAR_FLAG Description: DOCID026682 Rev 3 Line: Status. Clear the RTC WakeUp Timer associated Exti line flag. 461/654 HAL RTC Extension Driver UM1816 Return value: __HAL_RTC_WAKEUPTIMER_EXTI_GENERATE_SWIT None. Description: Generate a Software interrupt on the RTC WakeUp Timer associated Exti line. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_ENABLE_IT None. Description: Enable interrupt on the RTC Tamper and Timestamp associated Exti line. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_DISABLE_IT None Description: Disable interrupt on the RTC Tamper and Timestamp associated Exti line. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_ENABLE_EVE NT None Description: Enable event on the RTC Tamper and Timestamp associated Exti line. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_DISABLE_EVE NT None. Description: Disable event on the RTC Tamper and Timestamp associated Exti line. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_ENABLE_FALL ING_EDGE 462/654 DOCID026682 Rev 3 None. Description: Enable falling edge trigger on the RTC Tamper and Timestamp UM1816 HAL RTC Extension Driver associated Exti line. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_DISABLE_FAL LING_EDGE None. Description: Disable falling edge trigger on the RTC Tamper and Timestamp associated Exti line. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_ENABLE_RISI NG_EDGE None. Description: Enable rising edge trigger on the RTC Tamper and Timestamp associated Exti line. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_DISABLE_RISI NG_EDGE None. Description: Disable rising edge trigger on the RTC Tamper and Timestamp associated Exti line. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_ENABLE_RISI NG_FALLING_EDGE None. Description: Enable rising & falling edge trigger on the RTC Tamper and Timestamp associated Exti line. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_DISABLE_RISI NG_FALLING_EDGE None. Description: Disable rising & falling edge trigger on the RTC Tamper and Timestamp associated Exti line. Return value: DOCID026682 Rev 3 None. 463/654 HAL RTC Extension Driver __HAL_RTC_TAMPER_TIMESTAMP_EXTI_GET_FLAG UM1816 Description: Check whether the RTC Tamper and Timestamp associated Exti line interrupt flag is set or not. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_CLEAR_FLAG Line: Status. Description: Clear the RTC Tamper and Timestamp associated Exti line flag. Return value: __HAL_RTC_TAMPER_TIMESTAMP_EXTI_GENERATE_S WIT None. Description: Generate a Software interrupt on the RTC Tamper and Timestamp associated Exti line. Return value: None. Output selection Definitions RTC_OUTPUT_DISABLE RTC_OUTPUT_ALARMA RTC_OUTPUT_ALARMB RTC_OUTPUT_WAKEUP IS_RTC_OUTPUT RTCEx Private Constants RTC_EXTI_LINE_TAMPER_TIMESTAMP_EVENT External interrupt line 19 Connected to the RTC Tamper and Time Stamp events RTC_EXTI_LINE_WAKEUPTIMER_EVENT External interrupt line 20 Connected to the RTC Wakeup event Smooth Calib Minus Pulses Definitions IS_RTC_SMOOTH_CALIB_MINUS Smooth Calib Period Definitions RTC_SMOOTHCALIB_PERIOD_32SEC 464/654 If RTCCLK = 32768 Hz, Smooth calibation period is 32s, else 2exp20 RTCCLK seconds DOCID026682 Rev 3 UM1816 RTC_SMOOTHCALIB_PERIOD_16SEC RTC_SMOOTHCALIB_PERIOD_8SEC HAL RTC Extension Driver If RTCCLK = 32768 Hz, Smooth calibation period is 16s, else 2exp19 RTCCLK seconds If RTCCLK = 32768 Hz, Smooth calibation period is 8s, else 2exp18 RTCCLK seconds IS_RTC_SMOOTH_CALIB_PERIOD Smooth Calib Plus Pulses Definitions RTC_SMOOTHCALIB_PLUSPULSES_SET The number of RTCCLK pulses added during a X -second window = Y CALM[8:0] with Y = 512, 256, 128 when X = 32, 16, 8 RTC_SMOOTHCALIB_PLUSPULSES_RESET The number of RTCCLK pulses subbstited during a 32-second window = CALM[8:0] IS_RTC_SMOOTH_CALIB_PLUS Substract Fraction Of Second Value IS_RTC_SHIFT_SUBFS Tamper Filter Definitions RTC_TAMPERFILTER_DISABLE Tamper filter is disabled RTC_TAMPERFILTER_2SAMPLE Tamper is activated after 2 consecutive samples at the active level RTC_TAMPERFILTER_4SAMPLE Tamper is activated after 4 consecutive samples at the active level RTC_TAMPERFILTER_8SAMPLE Tamper is activated after 8 consecutive samples at the active level. IS_RTC_TAMPER_FILTER Tamper Pins Definitions RTC_TAMPER_1 RTC_TAMPER_2 RTC_TAMPER_3 IS_RTC_TAMPER Tamper Pin Precharge Duration RTC_TAMPERPRECHARGEDURATION_1RTCCLK Tamper pins are pre-charged before sampling during 1 RTCCLK cycle RTC_TAMPERPRECHARGEDURATION_2RTCCLK Tamper pins are pre-charged before sampling during 2 RTCCLK cycles RTC_TAMPERPRECHARGEDURATION_4RTCCLK Tamper pins are pre-charged before sampling during 4 RTCCLK cycles RTC_TAMPERPRECHARGEDURATION_8RTCCLK Tamper pins are pre-charged before sampling during 8 RTCCLK cycles DOCID026682 Rev 3 465/654 HAL RTC Extension Driver IS_RTC_TAMPER_PRECHARGE_DURATION UM1816 Tamper Pull-Up Definitions RTC_TAMPER_PULLUP_ENABLE TimeStamp on Tamper Detection event saved RTC_TAMPER_PULLUP_DISABLE TimeStamp on Tamper Detection event is not saved IS_RTC_TAMPER_PULLUP_STATE Tamper Sampling Frequencies RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV32768 Each of the tamper inputs are sampled with a frequency = RTCCLK / 32768 RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV16384 Each of the tamper inputs are sampled with a frequency = RTCCLK / 16384 RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV8192 Each of the tamper inputs are sampled with a frequency = RTCCLK / 8192 RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV4096 Each of the tamper inputs are sampled with a frequency = RTCCLK / 4096 RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV2048 Each of the tamper inputs are sampled with a frequency = RTCCLK / 2048 RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV1024 Each of the tamper inputs are sampled with a frequency = RTCCLK / 1024 RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV512 Each of the tamper inputs are sampled with a frequency = RTCCLK / 512 RTC_TAMPERSAMPLINGFREQ_RTCCLK_DIV256 Each of the tamper inputs are sampled with a frequency = RTCCLK / 256 IS_RTC_TAMPER_SAMPLING_FREQ TimeStampOnTamperDetection Definitions RTC_TIMESTAMPONTAMPERDETECTION_ENABLE TimeStamp on Tamper Detection event saved RTC_TIMESTAMPONTAMPERDETECTION_DISABLE TimeStamp on Tamper Detection event is not saved IS_RTC_TAMPER_TIMESTAMPONTAMPER_DETECTION Tamper Trigger Definitions RTC_TAMPERTRIGGER_RISINGEDGE RTC_TAMPERTRIGGER_FALLINGEDGE RTC_TAMPERTRIGGER_LOWLEVEL RTC_TAMPERTRIGGER_HIGHLEVEL 466/654 DOCID026682 Rev 3 UM1816 HAL RTC Extension Driver IS_RTC_TAMPER_TRIGGER Time Stamp Edges Definitions RTC_TIMESTAMPEDGE_RISING RTC_TIMESTAMPEDGE_FALLING IS_TIMESTAMP_EDGE Wakeup Timer Definitions RTC_WAKEUPCLOCK_RTCCLK_DIV16 RTC_WAKEUPCLOCK_RTCCLK_DIV8 RTC_WAKEUPCLOCK_RTCCLK_DIV4 RTC_WAKEUPCLOCK_RTCCLK_DIV2 RTC_WAKEUPCLOCK_CK_SPRE_16BITS RTC_WAKEUPCLOCK_CK_SPRE_17BITS IS_RTC_WAKEUP_CLOCK IS_RTC_WAKEUP_COUNTER DOCID026682 Rev 3 467/654 HAL SD Generic Driver UM1816 37 HAL SD Generic Driver 37.1 HAL SD Generic Driver 37.2 SD Firmware driver registers structures 37.2.1 SD_HandleTypeDef Data Fields SD_TypeDef * Instance SD_InitTypeDef Init HAL_LockTypeDef Lock uint32_t CardType uint32_t RCA uint32_t CSD uint32_t CID __IO uint32_t SdTransferCplt __IO uint32_t SdTransferErr __IO uint32_t DmaTransferCplt __IO uint32_t SdOperation DMA_HandleTypeDef * hdmarx DMA_HandleTypeDef * hdmatx Field Documentation 468/654 SD_TypeDef* SD_HandleTypeDef::Instance SDIO register base address SD_InitTypeDef SD_HandleTypeDef::Init SD required parameters HAL_LockTypeDef SD_HandleTypeDef::Lock SD locking object uint32_t SD_HandleTypeDef::CardType SD card type uint32_t SD_HandleTypeDef::RCA SD relative card address uint32_t SD_HandleTypeDef::CSD[4] SD card specific data table uint32_t SD_HandleTypeDef::CID[4] SD card identification number table __IO uint32_t SD_HandleTypeDef::SdTransferCplt SD transfer complete flag in non blocking mode __IO uint32_t SD_HandleTypeDef::SdTransferErr SD transfer error flag in non blocking mode __IO uint32_t SD_HandleTypeDef::DmaTransferCplt SD DMA transfer complete flag __IO uint32_t SD_HandleTypeDef::SdOperation SD transfer operation (read/write) DOCID026682 Rev 3 UM1816 HAL SD Generic Driver 37.2.2 DMA_HandleTypeDef* SD_HandleTypeDef::hdmarx SD Rx DMA handle parameters DMA_HandleTypeDef* SD_HandleTypeDef::hdmatx SD Tx DMA handle parameters HAL_SD_CSDTypedef Data Fields __IO uint8_t CSDStruct __IO uint8_t SysSpecVersion __IO uint8_t Reserved1 __IO uint8_t TAAC __IO uint8_t NSAC __IO uint8_t MaxBusClkFrec __IO uint16_t CardComdClasses __IO uint8_t RdBlockLen __IO uint8_t PartBlockRead __IO uint8_t WrBlockMisalign __IO uint8_t RdBlockMisalign __IO uint8_t DSRImpl __IO uint8_t Reserved2 __IO uint32_t DeviceSize __IO uint8_t MaxRdCurrentVDDMin __IO uint8_t MaxRdCurrentVDDMax __IO uint8_t MaxWrCurrentVDDMin __IO uint8_t MaxWrCurrentVDDMax __IO uint8_t DeviceSizeMul __IO uint8_t EraseGrSize __IO uint8_t EraseGrMul __IO uint8_t WrProtectGrSize __IO uint8_t WrProtectGrEnable __IO uint8_t ManDeflECC __IO uint8_t WrSpeedFact __IO uint8_t MaxWrBlockLen __IO uint8_t WriteBlockPaPartial __IO uint8_t Reserved3 __IO uint8_t ContentProtectAppli __IO uint8_t FileFormatGrouop __IO uint8_t CopyFlag __IO uint8_t PermWrProtect __IO uint8_t TempWrProtect __IO uint8_t FileFormat __IO uint8_t ECC __IO uint8_t CSD_CRC __IO uint8_t Reserved4 Field Documentation DOCID026682 Rev 3 469/654 HAL SD Generic Driver 470/654 UM1816 __IO uint8_t HAL_SD_CSDTypedef::CSDStruct CSD structure __IO uint8_t HAL_SD_CSDTypedef::SysSpecVersion System specification version __IO uint8_t HAL_SD_CSDTypedef::Reserved1 Reserved __IO uint8_t HAL_SD_CSDTypedef::TAAC Data read access time 1 __IO uint8_t HAL_SD_CSDTypedef::NSAC Data read access time 2 in CLK cycles __IO uint8_t HAL_SD_CSDTypedef::MaxBusClkFrec Max. bus clock frequency __IO uint16_t HAL_SD_CSDTypedef::CardComdClasses Card command classes __IO uint8_t HAL_SD_CSDTypedef::RdBlockLen Max. read data block length __IO uint8_t HAL_SD_CSDTypedef::PartBlockRead Partial blocks for read allowed __IO uint8_t HAL_SD_CSDTypedef::WrBlockMisalign Write block misalignment __IO uint8_t HAL_SD_CSDTypedef::RdBlockMisalign Read block misalignment __IO uint8_t HAL_SD_CSDTypedef::DSRImpl DSR implemented __IO uint8_t HAL_SD_CSDTypedef::Reserved2 Reserved __IO uint32_t HAL_SD_CSDTypedef::DeviceSize Device Size __IO uint8_t HAL_SD_CSDTypedef::MaxRdCurrentVDDMin Max. read current @ VDD min __IO uint8_t HAL_SD_CSDTypedef::MaxRdCurrentVDDMax Max. read current @ VDD max __IO uint8_t HAL_SD_CSDTypedef::MaxWrCurrentVDDMin Max. write current @ VDD min __IO uint8_t HAL_SD_CSDTypedef::MaxWrCurrentVDDMax Max. write current @ VDD max __IO uint8_t HAL_SD_CSDTypedef::DeviceSizeMul Device size multiplier __IO uint8_t HAL_SD_CSDTypedef::EraseGrSize Erase group size __IO uint8_t HAL_SD_CSDTypedef::EraseGrMul Erase group size multiplier __IO uint8_t HAL_SD_CSDTypedef::WrProtectGrSize Write protect group size __IO uint8_t HAL_SD_CSDTypedef::WrProtectGrEnable Write protect group enable __IO uint8_t HAL_SD_CSDTypedef::ManDeflECC Manufacturer default ECC __IO uint8_t HAL_SD_CSDTypedef::WrSpeedFact Write speed factor __IO uint8_t HAL_SD_CSDTypedef::MaxWrBlockLen Max. write data block length __IO uint8_t HAL_SD_CSDTypedef::WriteBlockPaPartial Partial blocks for write allowed DOCID026682 Rev 3 UM1816 HAL SD Generic Driver 37.2.3 __IO uint8_t HAL_SD_CSDTypedef::Reserved3 Reserved __IO uint8_t HAL_SD_CSDTypedef::ContentProtectAppli Content protection application __IO uint8_t HAL_SD_CSDTypedef::FileFormatGrouop File format group __IO uint8_t HAL_SD_CSDTypedef::CopyFlag Copy flag (OTP) __IO uint8_t HAL_SD_CSDTypedef::PermWrProtect Permanent write protection __IO uint8_t HAL_SD_CSDTypedef::TempWrProtect Temporary write protection __IO uint8_t HAL_SD_CSDTypedef::FileFormat File format __IO uint8_t HAL_SD_CSDTypedef::ECC ECC code __IO uint8_t HAL_SD_CSDTypedef::CSD_CRC CSD CRC __IO uint8_t HAL_SD_CSDTypedef::Reserved4 Always 1 HAL_SD_CIDTypedef Data Fields __IO uint8_t ManufacturerID __IO uint16_t OEM_AppliID __IO uint32_t ProdName1 __IO uint8_t ProdName2 __IO uint8_t ProdRev __IO uint32_t ProdSN __IO uint8_t Reserved1 __IO uint16_t ManufactDate __IO uint8_t CID_CRC __IO uint8_t Reserved2 Field Documentation __IO uint8_t HAL_SD_CIDTypedef::ManufacturerID Manufacturer ID __IO uint16_t HAL_SD_CIDTypedef::OEM_AppliID OEM/Application ID __IO uint32_t HAL_SD_CIDTypedef::ProdName1 Product Name part1 __IO uint8_t HAL_SD_CIDTypedef::ProdName2 Product Name part2 __IO uint8_t HAL_SD_CIDTypedef::ProdRev Product Revision __IO uint32_t HAL_SD_CIDTypedef::ProdSN Product Serial Number DOCID026682 Rev 3 471/654 HAL SD Generic Driver 37.2.4 UM1816 __IO uint8_t HAL_SD_CIDTypedef::Reserved1 Reserved1 __IO uint16_t HAL_SD_CIDTypedef::ManufactDate Manufacturing Date __IO uint8_t HAL_SD_CIDTypedef::CID_CRC CID CRC __IO uint8_t HAL_SD_CIDTypedef::Reserved2 Always 1 HAL_SD_CardStatusTypedef Data Fields __IO uint8_t DAT_BUS_WIDTH __IO uint8_t SECURED_MODE __IO uint16_t SD_CARD_TYPE __IO uint32_t SIZE_OF_PROTECTED_AREA __IO uint8_t SPEED_CLASS __IO uint8_t PERFORMANCE_MOVE __IO uint8_t AU_SIZE __IO uint16_t ERASE_SIZE __IO uint8_t ERASE_TIMEOUT __IO uint8_t ERASE_OFFSET Field Documentation 37.2.5 472/654 __IO uint8_t HAL_SD_CardStatusTypedef::DAT_BUS_WIDTH Shows the currently defined data bus width __IO uint8_t HAL_SD_CardStatusTypedef::SECURED_MODE Card is in secured mode of operation __IO uint16_t HAL_SD_CardStatusTypedef::SD_CARD_TYPE Carries information about card type __IO uint32_t HAL_SD_CardStatusTypedef::SIZE_OF_PROTECTED_AREA Carries information about the capacity of protected area __IO uint8_t HAL_SD_CardStatusTypedef::SPEED_CLASS Carries information about the speed class of the card __IO uint8_t HAL_SD_CardStatusTypedef::PERFORMANCE_MOVE Carries information about the card's performance move __IO uint8_t HAL_SD_CardStatusTypedef::AU_SIZE Carries information about the card's allocation unit size __IO uint16_t HAL_SD_CardStatusTypedef::ERASE_SIZE Determines the number of AUs to be erased in one operation __IO uint8_t HAL_SD_CardStatusTypedef::ERASE_TIMEOUT Determines the timeout for any number of AU erase __IO uint8_t HAL_SD_CardStatusTypedef::ERASE_OFFSET Carries information about the erase offset HAL_SD_CardInfoTypedef DOCID026682 Rev 3 UM1816 HAL SD Generic Driver Data Fields HAL_SD_CSDTypedef SD_csd HAL_SD_CIDTypedef SD_cid uint64_t CardCapacity uint32_t CardBlockSize uint16_t RCA uint8_t CardType Field Documentation HAL_SD_CSDTypedef HAL_SD_CardInfoTypedef::SD_csd SD card specific data register HAL_SD_CIDTypedef HAL_SD_CardInfoTypedef::SD_cid SD card identification number register uint64_t HAL_SD_CardInfoTypedef::CardCapacity Card capacity uint32_t HAL_SD_CardInfoTypedef::CardBlockSize Card block size uint16_t HAL_SD_CardInfoTypedef::RCA SD relative card address uint8_t HAL_SD_CardInfoTypedef::CardType SD card type 37.3 SD Firmware driver API description 37.3.1 How to use this driver This driver implements a high level communication layer for read and write from/to this memory. The needed STM32 hardware resources (SDIO and GPIO) are performed by the user in HAL_SD_MspInit() function (MSP layer). Basically, the MSP layer configuration should be the same as we provide in the examples. You can easily tailor this configuration according to hardware resources. This driver is a generic layered driver for SDIO memories which uses the HAL SDIO driver functions to interface with SD and uSD cards devices. It is used as follows: 1. Initialize the SDIO low level resources by implement the HAL_SD_MspInit() API: a. Enable the SDIO interface clock using __HAL_RCC_SDIO_CLK_ENABLE(); b. SDIO pins configuration for SD card Enable the clock for the SDIO GPIOs using the functions __HAL_RCC_GPIOx_CLK_ENABLE(); Configure these SDIO pins as alternate function pull-up using HAL_GPIO_Init() and according to your pin assignment; c. DMA Configuration if you need to use DMA process (HAL_SD_ReadBlocks_DMA() and HAL_SD_WriteBlocks_DMA() APIs). Enable the DMAx interface clock using __HAL_RCC_DMAx_CLK_ENABLE(); Configure the DMA using the function HAL_DMA_Init() with predeclared and filled. d. NVIC configuration if you need to use interrupt process when using DMA transfer. Configure the SDIO and DMA interrupt priorities using functions HAL_NVIC_SetPriority(); DMA priority is superior to SDIO's priority DOCID026682 Rev 3 473/654 HAL SD Generic Driver UM1816 2. Enable the NVIC DMA and SDIO IRQs using function HAL_NVIC_EnableIRQ() SDIO interrupts are managed using the macros __HAL_SD_SDIO_ENABLE_IT() and __HAL_SD_SDIO_DISABLE_IT() inside the communication process. SDIO interrupts pending bits are managed using the macros __HAL_SD_SDIO_GET_IT() and __HAL_SD_SDIO_CLEAR_IT() At this stage, you can perform SD read/write/erase operations after SD card initialization SD Card Initialization and configuration To initialize the SD Card, use the HAL_SD_Init() function. It Initializes the SD Card and put it into Standby State (Ready for data transfer). This function provide the following operations: 1. 2. 3. 4. 5. Apply the SD Card initialization process at 400KHz and check the SD Card type (Standard Capacity or High Capacity). You can change or adapt this frequency by adjusting the "ClockDiv" field. The SD Card frequency (SDIO_CK) is computed as follows: SDIO_CK = SDIOCLK / (ClockDiv + 2) In initialization mode and according to the SD Card standard, make sure that the SDIO_CK frequency doesn't exceed 400KHz. Get the SD CID and CSD data. All these information are managed by the SDCardInfo structure. This structure provide also ready computed SD Card capacity and Block size. These information are stored in SD handle structure in case of future use. Configure the SD Card Data transfer frequency. By Default, the card transfer frequency is set to 48MHz / (SDIO_TRANSFER_CLK_DIV + 2) = 8MHz. You can change or adapt this frequency by adjusting the "ClockDiv" field. The SD Card frequency (SDIO_CK) is computed as follows: SDIO_CK = SDIOCLK / (ClockDiv + 2) In transfer mode and according to the SD Card standard, make sure that the SDIO_CK frequency doesn't exceed 25MHz and 50MHz in High-speed mode switch. To be able to use a frequency higher than 24MHz, you should use the SDIO peripheral in bypass mode. Refer to the corresponding reference manual for more details. Select the corresponding SD Card according to the address read with the step 2. Configure the SD Card in wide bus mode: 4-bits data. SD Card Read operation You can read from SD card in polling mode by using function HAL_SD_ReadBlocks(). This function support only 512-bytes block length (the block size should be chosen as 512 bytes). You can choose either one block read operation or multiple block read operation by adjusting the "NumberOfBlocks" parameter. You can read from SD card in DMA mode by using function HAL_SD_ReadBlocks_DMA(). This function support only 512-bytes block length (the block size should be chosen as 512 bytes). You can choose either one block read operation or multiple block read operation by adjusting the "NumberOfBlocks" parameter. After this, you have to call the function HAL_SD_CheckReadOperation(), to insure that the read transfer is done correctly in both DMA and SD sides. SD Card Write operation 474/654 You can write to SD card in polling mode by using function HAL_SD_WriteBlocks(). This function support only 512-bytes block length (the block size should be chosen as DOCID026682 Rev 3 UM1816 HAL SD Generic Driver 512 bytes). You can choose either one block read operation or multiple block read operation by adjusting the "NumberOfBlocks" parameter. You can write to SD card in DMA mode by using function HAL_SD_WriteBlocks_DMA(). This function support only 512-bytes block length (the block size should be chosen as 512 byte). You can choose either one block read operation or multiple block read operation by adjusting the "NumberOfBlocks" parameter. After this, you have to call the function HAL_SD_CheckWriteOperation(), to insure that the write transfer is done correctly in both DMA and SD sides. SD card status At any time, you can check the SD Card status and get the SD card state by using the HAL_SD_GetStatus() function. This function checks first if the SD card is still connected and then get the internal SD Card transfer state. You can also get the SD card SD Status register by using the HAL_SD_SendSDStatus() function. SD HAL driver macros list You can refer to the SD HAL driver header file for more useful macros 37.3.2 Initialization and de-initialization functions This section provides functions allowing to initialize/de-initialize the SD card device to be ready for use. This section contains the following APIs: 37.3.3 HAL_SD_Init() HAL_SD_DeInit() HAL_SD_MspInit() HAL_SD_MspDeInit() IO operation functions This subsection provides a set of functions allowing to manage the data transfer from/to SD card. This section contains the following APIs: HAL_SD_ReadBlocks() HAL_SD_WriteBlocks() HAL_SD_ReadBlocks_DMA() HAL_SD_WriteBlocks_DMA() HAL_SD_CheckReadOperation() HAL_SD_CheckWriteOperation() HAL_SD_Erase() HAL_SD_IRQHandler() HAL_SD_XferCpltCallback() HAL_SD_XferErrorCallback() HAL_SD_DMA_RxCpltCallback() HAL_SD_DMA_RxErrorCallback() DOCID026682 Rev 3 475/654 HAL SD Generic Driver 37.3.4 UM1816 HAL_SD_DMA_TxCpltCallback() HAL_SD_DMA_TxErrorCallback() Peripheral Control functions This subsection provides a set of functions allowing to control the SD card operations. This section contains the following APIs: 37.3.5 HAL_SD_Get_CardInfo() HAL_SD_WideBusOperation_Config() HAL_SD_StopTransfer() HAL_SD_HighSpeed() Peripheral State functions This subsection permits to get in runtime the status of the peripheral and the data flow. This section contains the following APIs: 37.3.6 37.3.7 37.3.8 37.3.9 476/654 HAL_SD_SendSDStatus() HAL_SD_GetStatus() HAL_SD_GetCardStatus() HAL_SD_Init Function Name HAL_SD_ErrorTypedef HAL_SD_Init (SD_HandleTypeDef * hsd, HAL_SD_CardInfoTypedef * SDCardInfo) Function Description Initializes the SD card according to the specified parameters in the SD_HandleTypeDef and create the associated handle. Parameters hsd: SD handle SDCardInfo: HAL_SD_CardInfoTypedef structure for SD card information Return values HAL SD error state HAL_SD_DeInit Function Name HAL_StatusTypeDef HAL_SD_DeInit (SD_HandleTypeDef * hsd) Function Description De-Initializes the SD card. Parameters hsd: SD handle Return values HAL status HAL_SD_MspInit Function Name void HAL_SD_MspInit (SD_HandleTypeDef * hsd) Function Description Initializes the SD MSP. Parameters hsd: SD handle Return values None HAL_SD_MspDeInit DOCID026682 Rev 3 UM1816 37.3.10 37.3.11 37.3.12 Function Name HAL SD Generic Driver void HAL_SD_MspDeInit (SD_HandleTypeDef * hsd) Function Description De-Initialize SD MSP. Parameters hsd: SD handle Return values None HAL_SD_ReadBlocks Function Name HAL_SD_ErrorTypedef HAL_SD_ReadBlocks (SD_HandleTypeDef * hsd, uint32_t * pReadBuffer, uint64_t ReadAddr, uint32_t BlockSize, uint32_t NumberOfBlocks) Function Description Reads block(s) from a specified address in a card. Parameters hsd: SD handle pReadBuffer: pointer to the buffer that will contain the received data ReadAddr: Address from where data is to be read BlockSize: SD card Data block size NumberOfBlocks: Number of SD blocks to read Return values SD Card error state Notes BlockSize must be 512 bytes. HAL_SD_WriteBlocks Function Name HAL_SD_ErrorTypedef HAL_SD_WriteBlocks (SD_HandleTypeDef * hsd, uint32_t * pWriteBuffer, uint64_t WriteAddr, uint32_t BlockSize, uint32_t NumberOfBlocks) Function Description Allows to write block(s) to a specified address in a card. Parameters hsd: SD handle pWriteBuffer: pointer to the buffer that will contain the data to transmit WriteAddr: Address from where data is to be written BlockSize: SD card Data block size NumberOfBlocks: Number of SD blocks to write Return values SD Card error state Notes BlockSize must be 512 bytes. HAL_SD_ReadBlocks_DMA Function Name HAL_SD_ErrorTypedef HAL_SD_ReadBlocks_DMA (SD_HandleTypeDef * hsd, uint32_t * pReadBuffer, uint64_t ReadAddr, uint32_t BlockSize, uint32_t NumberOfBlocks) Function Description Reads block(s) from a specified address in a card. Parameters hsd: SD handle pReadBuffer: Pointer to the buffer that will contain the received data ReadAddr: Address from where data is to be read BlockSize: SD card Data block size NumberOfBlocks: Number of blocks to read. DOCID026682 Rev 3 477/654 HAL SD Generic Driver Return values Notes UM1816 SD Card error state This API should be followed by the function HAL_SD_CheckReadOperation() to check the completion of the read process BlockSize must be 512 bytes. 37.3.13 HAL_SD_WriteBlocks_DMA Function Name HAL_SD_ErrorTypedef HAL_SD_WriteBlocks_DMA (SD_HandleTypeDef * hsd, uint32_t * pWriteBuffer, uint64_t WriteAddr, uint32_t BlockSize, uint32_t NumberOfBlocks) Function Description Writes block(s) to a specified address in a card. Parameters hsd: SD handle pWriteBuffer: pointer to the buffer that will contain the data to transmit WriteAddr: Address from where data is to be read BlockSize: the SD card Data block size NumberOfBlocks: Number of blocks to write Return values SD Card error state Notes This API should be followed by the function HAL_SD_CheckWriteOperation() to check the completion of the write process (by SD current status polling). BlockSize must be 512 bytes. 37.3.14 37.3.15 37.3.16 478/654 HAL_SD_CheckReadOperation Function Name HAL_SD_ErrorTypedef HAL_SD_CheckReadOperation (SD_HandleTypeDef * hsd, uint32_t Timeout) Function Description This function waits until the SD DMA data read transfer is finished. Parameters hsd: SD handle Timeout: Timeout duration Return values SD Card error state HAL_SD_CheckWriteOperation Function Name HAL_SD_ErrorTypedef HAL_SD_CheckWriteOperation (SD_HandleTypeDef * hsd, uint32_t Timeout) Function Description This function waits until the SD DMA data write transfer is finished. Parameters hsd: SD handle Timeout: Timeout duration Return values SD Card error state HAL_SD_Erase Function Name HAL_SD_ErrorTypedef HAL_SD_Erase (SD_HandleTypeDef * hsd, uint64_t startaddr, uint64_t endaddr) Function Description Erases the specified memory area of the given SD card. DOCID026682 Rev 3 UM1816 37.3.17 37.3.18 37.3.19 37.3.20 37.3.21 HAL SD Generic Driver Parameters hsd: SD handle startaddr: Start byte address endaddr: End byte address Return values SD Card error state HAL_SD_IRQHandler Function Name void HAL_SD_IRQHandler (SD_HandleTypeDef * hsd) Function Description This function handles SD card interrupt request. Parameters hsd: SD handle Return values None HAL_SD_XferCpltCallback Function Name void HAL_SD_XferCpltCallback (SD_HandleTypeDef * hsd) Function Description SD end of transfer callback. Parameters hsd: SD handle Return values None HAL_SD_XferErrorCallback Function Name void HAL_SD_XferErrorCallback (SD_HandleTypeDef * hsd) Function Description SD Transfer Error callback. Parameters hsd: SD handle Return values None HAL_SD_DMA_RxCpltCallback Function Name void HAL_SD_DMA_RxCpltCallback (DMA_HandleTypeDef * hdma) Function Description SD Transfer complete Rx callback in non blocking mode. Parameters hdma: pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA module. Return values None HAL_SD_DMA_RxErrorCallback Function Name void HAL_SD_DMA_RxErrorCallback (DMA_HandleTypeDef * hdma) Function Description SD DMA transfer complete Rx error callback. Parameters hdma: pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA module. Return values None DOCID026682 Rev 3 479/654 HAL SD Generic Driver 37.3.22 37.3.23 37.3.24 37.3.25 37.3.26 HAL_SD_DMA_TxCpltCallback Function Name void HAL_SD_DMA_TxCpltCallback (DMA_HandleTypeDef * hdma) Function Description SD Transfer complete Tx callback in non blocking mode. Parameters hdma: pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA module. Return values None HAL_SD_DMA_TxErrorCallback Function Name void HAL_SD_DMA_TxErrorCallback (DMA_HandleTypeDef * hdma) Function Description SD DMA transfer complete error Tx callback. Parameters hdma: pointer to a DMA_HandleTypeDef structure that contains the configuration information for the specified DMA module. Return values None HAL_SD_Get_CardInfo Function Name HAL_SD_ErrorTypedef HAL_SD_Get_CardInfo (SD_HandleTypeDef * hsd, HAL_SD_CardInfoTypedef * pCardInfo) Function Description Returns information about specific card. Parameters hsd: SD handle pCardInfo: Pointer to a HAL_SD_CardInfoTypedef structure that contains all SD cardinformation Return values SD Card error state HAL_SD_WideBusOperation_Config Function Name HAL_SD_ErrorTypedef HAL_SD_WideBusOperation_Config (SD_HandleTypeDef * hsd, uint32_t WideMode) Function Description Enables wide bus operation for the requested card if supported by card. Parameters hsd: SD handle WideMode: Specifies the SD card wide bus mode This parameter can be one of the following values: SDIO_BUS_WIDE_8B: 8-bit data transfer (Only for MMC)SDIO_BUS_WIDE_4B: 4-bit data transferSDIO_BUS_WIDE_1B: 1-bit data transfer Return values SD Card error state HAL_SD_StopTransfer Function Name 480/654 UM1816 HAL_SD_ErrorTypedef HAL_SD_StopTransfer DOCID026682 Rev 3 UM1816 HAL SD Generic Driver (SD_HandleTypeDef * hsd) 37.3.27 37.3.28 37.3.29 37.3.30 Function Description Aborts an ongoing data transfer. Parameters hsd: SD handle Return values SD Card error state HAL_SD_HighSpeed Function Name HAL_SD_ErrorTypedef HAL_SD_HighSpeed (SD_HandleTypeDef * hsd) Function Description Switches the SD card to High Speed mode. Parameters hsd: SD handle Return values SD Card error state Notes This operation should be followed by the configuration of PLL to have SDIOCK clock between 67 and 75 MHz HAL_SD_SendSDStatus Function Name HAL_SD_ErrorTypedef HAL_SD_SendSDStatus (SD_HandleTypeDef * hsd, uint32_t * pSDstatus) Function Description Returns the current SD card's status. Parameters hsd: SD handle pSDstatus: Pointer to the buffer that will contain the SD card status SD Status register) Return values SD Card error state HAL_SD_GetStatus Function Name HAL_SD_TransferStateTypedef HAL_SD_GetStatus (SD_HandleTypeDef * hsd) Function Description Gets the current sd card data status. Parameters hsd: SD handle Return values Data Transfer state HAL_SD_GetCardStatus Function Name HAL_SD_ErrorTypedef HAL_SD_GetCardStatus (SD_HandleTypeDef * hsd, HAL_SD_CardStatusTypedef * pCardStatus) Function Description Gets the SD card status. Parameters hsd: SD handle pCardStatus: Pointer to the HAL_SD_CardStatusTypedef structure that will contain the SD card status information Return values SD Card error state DOCID026682 Rev 3 481/654 HAL SD Generic Driver UM1816 37.4 SD Firmware driver defines 37.4.1 SD SD Exported Constants 482/654 SD_CMD_GO_IDLE_STATE Resets the SD memory card. SD_CMD_SEND_OP_COND Sends host capacity support information and activates the card's initialization process. SD_CMD_ALL_SEND_CID Asks any card connected to the host to send the CID numbers on the CMD line. SD_CMD_SET_REL_ADDR Asks the card to publish a new relative address (RCA). SD_CMD_SET_DSR Programs the DSR of all cards. SD_CMD_SDIO_SEN_OP_COND Sends host capacity support information (HCS) and asks the accessed card to send its operating condition register (OCR) content in the response on the CMD line. SD_CMD_HS_SWITCH Checks switchable function (mode 0) and switch card function (mode 1). SD_CMD_SEL_DESEL_CARD Selects the card by its own relative address and gets deselected by any other address SD_CMD_HS_SEND_EXT_CSD Sends SD Memory Card interface condition, which includes host supply voltage information and asks the card whether card supports voltage. SD_CMD_SEND_CSD Addressed card sends its card specific data (CSD) on the CMD line. SD_CMD_SEND_CID Addressed card sends its card identification (CID) on the CMD line. SD_CMD_READ_DAT_UNTIL_STOP SD card doesn't support it. SD_CMD_STOP_TRANSMISSION Forces the card to stop transmission. SD_CMD_SEND_STATUS Addressed card sends its DOCID026682 Rev 3 UM1816 HAL SD Generic Driver status register. SD_CMD_HS_BUSTEST_READ SD_CMD_GO_INACTIVE_STATE Sends an addressed card into the inactive state. SD_CMD_SET_BLOCKLEN Sets the block length (in bytes for SDSC) for all following block commands (read, write, lock). Default block length is fixed to 512 Bytes. Not effective for SDHS and SDXC. SD_CMD_READ_SINGLE_BLOCK Reads single block of size selected by SET_BLOCKLEN in case of SDSC, and a block of fixed 512 bytes in case of SDHC and SDXC. SD_CMD_READ_MULT_BLOCK Continuously transfers data blocks from card to host until interrupted by STOP_TRANSMISSION command. SD_CMD_HS_BUSTEST_WRITE 64 bytes tuning pattern is sent for SDR50 and SDR104. SD_CMD_WRITE_DAT_UNTIL_STOP Speed class control command. SD_CMD_SET_BLOCK_COUNT Specify block count for CMD18 and CMD25. SD_CMD_WRITE_SINGLE_BLOCK Writes single block of size selected by SET_BLOCKLEN in case of SDSC, and a block of fixed 512 bytes in case of SDHC and SDXC. SD_CMD_WRITE_MULT_BLOCK Continuously writes blocks of data until a STOP_TRANSMISSION follows. SD_CMD_PROG_CID Reserved for manufacturers. SD_CMD_PROG_CSD Programming of the programmable bits of the CSD. SD_CMD_SET_WRITE_PROT Sets the write protection bit of the addressed group. SD_CMD_CLR_WRITE_PROT Clears the write protection bit of the addressed group. DOCID026682 Rev 3 483/654 HAL SD Generic Driver SD_CMD_SEND_WRITE_PROT UM1816 Asks the card to send the status of the write protection bits. SD_CMD_SD_ERASE_GRP_START Sets the address of the first write block to be erased. (For SD card only). SD_CMD_SD_ERASE_GRP_END Sets the address of the last write block of the continuous range to be erased. SD_CMD_ERASE_GRP_START Sets the address of the first write block to be erased. Reserved for each command system set by switch function command (CMD6). SD_CMD_ERASE_GRP_END Sets the address of the last write block of the continuous range to be erased. Reserved for each command system set by switch function command (CMD6). SD_CMD_ERASE Reserved for SD security applications. SD_CMD_FAST_IO SD card doesn't support it (Reserved). SD_CMD_GO_IRQ_STATE SD card doesn't support it (Reserved). SD_CMD_LOCK_UNLOCK Sets/resets the password or lock/unlock the card. The size of the data block is set by the SET_BLOCK_LEN command. SD_CMD_APP_CMD Indicates to the card that the next command is an application specific command rather than a standard command. SD_CMD_GEN_CMD Used either to transfer a data block to the card or to get a data block from the card for general purpose/application specific commands. SD_CMD_NO_CMD SD_CMD_APP_SD_SET_BUSWIDTH 484/654 DOCID026682 Rev 3 SDIO_APP_CMD should be sent before sending these commands. (ACMD6) Defines the data bus width UM1816 HAL SD Generic Driver to be used for data transfer. The allowed data bus widths are given in SCR register. SD_CMD_SD_APP_STATUS (ACMD13) Sends the SD status. SD_CMD_SD_APP_SEND_NUM_WRITE_BLOCKS (ACMD22) Sends the number of the written (without errors) write blocks. Responds with 32bit+CRC data block. SD_CMD_SD_APP_OP_COND (ACMD41) Sends host capacity support information (HCS) and asks the accessed card to send its operating condition register (OCR) content in the response on the CMD line. SD_CMD_SD_APP_SET_CLR_CARD_DETECT (ACMD42) Connects/Disconnects the 50 KOhm pull-up resistor on CD/DAT3 (pin 1) of the card. SD_CMD_SD_APP_SEND_SCR Reads the SD Configuration Register (SCR). SD_CMD_SDIO_RW_DIRECT For SD I/O card only, reserved for security specification. SD_CMD_SDIO_RW_EXTENDED For SD I/O card only, reserved for security specification. SD_CMD_SD_APP_GET_MKB SD_CMD_APP_CMD should be sent before sending these commands. For SD card only SD_CMD_SD_APP_GET_MID For SD card only SD_CMD_SD_APP_SET_CER_RN1 For SD card only SD_CMD_SD_APP_GET_CER_RN2 For SD card only SD_CMD_SD_APP_SET_CER_RES2 For SD card only SD_CMD_SD_APP_GET_CER_RES1 For SD card only SD_CMD_SD_APP_SECURE_READ_MULTIPLE_BLOCK For SD card only SD_CMD_SD_APP_SECURE_WRITE_MULTIPLE_BLOCK For SD card only SD_CMD_SD_APP_SECURE_ERASE For SD card only SD_CMD_SD_APP_CHANGE_SECURE_AREA For SD card only SD_CMD_SD_APP_SECURE_WRITE_MKB For SD card only STD_CAPACITY_SD_CARD_V1_1 STD_CAPACITY_SD_CARD_V2_0 DOCID026682 Rev 3 485/654 HAL SD Generic Driver HIGH_CAPACITY_SD_CARD UM1816 MULTIMEDIA_CARD SECURE_DIGITAL_IO_CARD HIGH_SPEED_MULTIMEDIA_CARD SECURE_DIGITAL_IO_COMBO_CARD HIGH_CAPACITY_MMC_CARD SD Exported Macros Description: __HAL_SD_SDIO_ENABLE Enable the SD device. Return value: __HAL_SD_SDIO_DISABLE None Description: Disable the SD device. Return value: __HAL_SD_SDIO_DMA_ENABLE None Description: Enable the SDIO DMA transfer. Return value: __HAL_SD_SDIO_DMA_DISABLE None Description: Disable the SDIO DMA transfer. Return value: __HAL_SD_SDIO_ENABLE_IT None Description: Enable the SD device interrupt. Parameters: 486/654 __HANDLE__: SD Handle __INTERRUPT__: specifies the SDIO interrupt sources to be enabled. This parameter can be one or a combination of the following values: SDIO_IT_CCRCFAIL: Command response received (CRC check failed) interrupt SDIO_IT_DCRCFAIL: Data block sent/received (CRC check failed) interrupt SDIO_IT_CTIMEOUT: Command response timeout interrupt SDIO_IT_DTIMEOUT: Data timeout interrupt SDIO_IT_TXUNDERR: Transmit FIFO underrun error interrupt SDIO_IT_RXOVERR: Received FIFO DOCID026682 Rev 3 UM1816 HAL SD Generic Driver overrun error interrupt SDIO_IT_CMDREND: Command response received (CRC check passed) interrupt SDIO_IT_CMDSENT: Command sent (no response required) interrupt SDIO_IT_DATAEND: Data end (data counter, SDIDCOUNT, is zero) interrupt SDIO_IT_STBITERR: Start bit not detected on all data signals in wide bus mode interrupt SDIO_IT_DBCKEND: Data block sent/received (CRC check passed) interrupt SDIO_IT_CMDACT: Command transfer in progress interrupt SDIO_IT_TXACT: Data transmit in progress interrupt SDIO_IT_RXACT: Data receive in progress interrupt SDIO_IT_TXFIFOHE: Transmit FIFO Half Empty interrupt SDIO_IT_RXFIFOHF: Receive FIFO Half Full interrupt SDIO_IT_TXFIFOF: Transmit FIFO full interrupt SDIO_IT_RXFIFOF: Receive FIFO full interrupt SDIO_IT_TXFIFOE: Transmit FIFO empty interrupt SDIO_IT_RXFIFOE: Receive FIFO empty interrupt SDIO_IT_TXDAVL: Data available in transmit FIFO interrupt SDIO_IT_RXDAVL: Data available in receive FIFO interrupt SDIO_IT_SDIOIT: SD I/O interrupt received interrupt SDIO_IT_CEATAEND: CE-ATA command completion signal received for CMD61 interrupt Return value: __HAL_SD_SDIO_DISABLE_IT None Description: Disable the SD device interrupt. Parameters: __HANDLE__: SD Handle __INTERRUPT__: specifies the SDIO interrupt sources to be disabled. This parameter can be one or a combination of the following values: SDIO_IT_CCRCFAIL: Command response received (CRC check failed) interrupt SDIO_IT_DCRCFAIL: Data block DOCID026682 Rev 3 487/654 HAL SD Generic Driver UM1816 sent/received (CRC check failed) interrupt SDIO_IT_CTIMEOUT: Command response timeout interrupt SDIO_IT_DTIMEOUT: Data timeout interrupt SDIO_IT_TXUNDERR: Transmit FIFO underrun error interrupt SDIO_IT_RXOVERR: Received FIFO overrun error interrupt SDIO_IT_CMDREND: Command response received (CRC check passed) interrupt SDIO_IT_CMDSENT: Command sent (no response required) interrupt SDIO_IT_DATAEND: Data end (data counter, SDIDCOUNT, is zero) interrupt SDIO_IT_STBITERR: Start bit not detected on all data signals in wide bus mode interrupt SDIO_IT_DBCKEND: Data block sent/received (CRC check passed) interrupt SDIO_IT_CMDACT: Command transfer in progress interrupt SDIO_IT_TXACT: Data transmit in progress interrupt SDIO_IT_RXACT: Data receive in progress interrupt SDIO_IT_TXFIFOHE: Transmit FIFO Half Empty interrupt SDIO_IT_RXFIFOHF: Receive FIFO Half Full interrupt SDIO_IT_TXFIFOF: Transmit FIFO full interrupt SDIO_IT_RXFIFOF: Receive FIFO full interrupt SDIO_IT_TXFIFOE: Transmit FIFO empty interrupt SDIO_IT_RXFIFOE: Receive FIFO empty interrupt SDIO_IT_TXDAVL: Data available in transmit FIFO interrupt SDIO_IT_RXDAVL: Data available in receive FIFO interrupt SDIO_IT_SDIOIT: SD I/O interrupt received interrupt SDIO_IT_CEATAEND: CE-ATA command completion signal received for CMD61 interrupt Return value: __HAL_SD_SDIO_GET_FLAG Description: 488/654 None Check whether the specified SD flag is set or not. DOCID026682 Rev 3 UM1816 HAL SD Generic Driver Parameters: __HANDLE__: SD Handle __FLAG__: specifies the flag to check. This parameter can be one of the following values: SDIO_FLAG_CCRCFAIL: Command response received (CRC check failed) SDIO_FLAG_DCRCFAIL: Data block sent/received (CRC check failed) SDIO_FLAG_CTIMEOUT: Command response timeout SDIO_FLAG_DTIMEOUT: Data timeout SDIO_FLAG_TXUNDERR: Transmit FIFO underrun error SDIO_FLAG_RXOVERR: Received FIFO overrun error SDIO_FLAG_CMDREND: Command response received (CRC check passed) SDIO_FLAG_CMDSENT: Command sent (no response required) SDIO_FLAG_DATAEND: Data end (data counter, SDIDCOUNT, is zero) SDIO_FLAG_STBITERR: Start bit not detected on all data signals in wide bus mode. SDIO_FLAG_DBCKEND: Data block sent/received (CRC check passed) SDIO_FLAG_CMDACT: Command transfer in progress SDIO_FLAG_TXACT: Data transmit in progress SDIO_FLAG_RXACT: Data receive in progress SDIO_FLAG_TXFIFOHE: Transmit FIFO Half Empty SDIO_FLAG_RXFIFOHF: Receive FIFO Half Full SDIO_FLAG_TXFIFOF: Transmit FIFO full SDIO_FLAG_RXFIFOF: Receive FIFO full SDIO_FLAG_TXFIFOE: Transmit FIFO empty SDIO_FLAG_RXFIFOE: Receive FIFO empty SDIO_FLAG_TXDAVL: Data available in transmit FIFO SDIO_FLAG_RXDAVL: Data available in receive FIFO SDIO_FLAG_SDIOIT: SD I/O interrupt received SDIO_FLAG_CEATAEND: CE-ATA command completion signal received for CMD61 Return value: DOCID026682 Rev 3 489/654 HAL SD Generic Driver UM1816 __HAL_SD_SDIO_CLEAR_FLAG The: new state of SD FLAG (SET or RESET). Description: Clear the SD's pending flags. Parameters: __HANDLE__: SD Handle __FLAG__: specifies the flag to clear. This parameter can be one or a combination of the following values: SDIO_FLAG_CCRCFAIL: Command response received (CRC check failed) SDIO_FLAG_DCRCFAIL: Data block sent/received (CRC check failed) SDIO_FLAG_CTIMEOUT: Command response timeout SDIO_FLAG_DTIMEOUT: Data timeout SDIO_FLAG_TXUNDERR: Transmit FIFO underrun error SDIO_FLAG_RXOVERR: Received FIFO overrun error SDIO_FLAG_CMDREND: Command response received (CRC check passed) SDIO_FLAG_CMDSENT: Command sent (no response required) SDIO_FLAG_DATAEND: Data end (data counter, SDIDCOUNT, is zero) SDIO_FLAG_STBITERR: Start bit not detected on all data signals in wide bus mode SDIO_FLAG_DBCKEND: Data block sent/received (CRC check passed) SDIO_FLAG_SDIOIT: SD I/O interrupt received SDIO_FLAG_CEATAEND: CE-ATA command completion signal received for CMD61 Return value: __HAL_SD_SDIO_GET_IT None Description: Check whether the specified SD interrupt has occurred or not. Parameters: 490/654 __HANDLE__: SD Handle __INTERRUPT__: specifies the SDIO interrupt source to check. This parameter can be one of the following values: SDIO_IT_CCRCFAIL: Command response received (CRC check failed) interrupt SDIO_IT_DCRCFAIL: Data block sent/received (CRC check failed) interrupt DOCID026682 Rev 3 UM1816 HAL SD Generic Driver SDIO_IT_CTIMEOUT: Command response timeout interrupt SDIO_IT_DTIMEOUT: Data timeout interrupt SDIO_IT_TXUNDERR: Transmit FIFO underrun error interrupt SDIO_IT_RXOVERR: Received FIFO overrun error interrupt SDIO_IT_CMDREND: Command response received (CRC check passed) interrupt SDIO_IT_CMDSENT: Command sent (no response required) interrupt SDIO_IT_DATAEND: Data end (data counter, SDIDCOUNT, is zero) interrupt SDIO_IT_STBITERR: Start bit not detected on all data signals in wide bus mode interrupt SDIO_IT_DBCKEND: Data block sent/received (CRC check passed) interrupt SDIO_IT_CMDACT: Command transfer in progress interrupt SDIO_IT_TXACT: Data transmit in progress interrupt SDIO_IT_RXACT: Data receive in progress interrupt SDIO_IT_TXFIFOHE: Transmit FIFO Half Empty interrupt SDIO_IT_RXFIFOHF: Receive FIFO Half Full interrupt SDIO_IT_TXFIFOF: Transmit FIFO full interrupt SDIO_IT_RXFIFOF: Receive FIFO full interrupt SDIO_IT_TXFIFOE: Transmit FIFO empty interrupt SDIO_IT_RXFIFOE: Receive FIFO empty interrupt SDIO_IT_TXDAVL: Data available in transmit FIFO interrupt SDIO_IT_RXDAVL: Data available in receive FIFO interrupt SDIO_IT_SDIOIT: SD I/O interrupt received interrupt SDIO_IT_CEATAEND: CE-ATA command completion signal received for CMD61 interrupt Return value: __HAL_SD_SDIO_CLEAR_IT The: new state of SD IT (SET or RESET). Description: Clear the SD's interrupt pending bits. Parameters: DOCID026682 Rev 3 491/654 HAL SD Generic Driver UM1816 __HANDLE__: : SD Handle __INTERRUPT__: specifies the interrupt pending bit to clear. This parameter can be one or a combination of the following values: SDIO_IT_CCRCFAIL: Command response received (CRC check failed) interrupt SDIO_IT_DCRCFAIL: Data block sent/received (CRC check failed) interrupt SDIO_IT_CTIMEOUT: Command response timeout interrupt SDIO_IT_DTIMEOUT: Data timeout interrupt SDIO_IT_TXUNDERR: Transmit FIFO underrun error interrupt SDIO_IT_RXOVERR: Received FIFO overrun error interrupt SDIO_IT_CMDREND: Command response received (CRC check passed) interrupt SDIO_IT_CMDSENT: Command sent (no response required) interrupt SDIO_IT_DATAEND: Data end (data counter, SDIO_DCOUNT, is zero) interrupt SDIO_IT_STBITERR: Start bit not detected on all data signals in wide bus mode interrupt SDIO_IT_SDIOIT: SD I/O interrupt received interrupt SDIO_IT_CEATAEND: CE-ATA command completion signal received for CMD61 Return value: None SD Handle Structure definition SD_InitTypeDef SD_TypeDef SD Private Defines DATA_BLOCK_SIZE SDIO_STATIC_FLAGS SDIO_CMD0TIMEOUT SD_OCR_ADDR_OUT_OF_RANGE SD_OCR_ADDR_MISALIGNED SD_OCR_BLOCK_LEN_ERR SD_OCR_ERASE_SEQ_ERR SD_OCR_BAD_ERASE_PARAM SD_OCR_WRITE_PROT_VIOLATION SD_OCR_LOCK_UNLOCK_FAILED 492/654 DOCID026682 Rev 3 UM1816 HAL SD Generic Driver SD_OCR_COM_CRC_FAILED SD_OCR_ILLEGAL_CMD SD_OCR_CARD_ECC_FAILED SD_OCR_CC_ERROR SD_OCR_GENERAL_UNKNOWN_ERROR SD_OCR_STREAM_READ_UNDERRUN SD_OCR_STREAM_WRITE_OVERRUN SD_OCR_CID_CSD_OVERWRITE SD_OCR_WP_ERASE_SKIP SD_OCR_CARD_ECC_DISABLED SD_OCR_ERASE_RESET SD_OCR_AKE_SEQ_ERROR SD_OCR_ERRORBITS SD_R6_GENERAL_UNKNOWN_ERROR SD_R6_ILLEGAL_CMD SD_R6_COM_CRC_FAILED SD_VOLTAGE_WINDOW_SD SD_HIGH_CAPACITY SD_STD_CAPACITY SD_CHECK_PATTERN SD_MAX_VOLT_TRIAL SD_ALLZERO SD_WIDE_BUS_SUPPORT SD_SINGLE_BUS_SUPPORT SD_CARD_LOCKED SD_DATATIMEOUT SD_0TO7BITS SD_8TO15BITS SD_16TO23BITS SD_24TO31BITS SD_MAX_DATA_LENGTH SD_HALFFIFO SD_HALFFIFOBYTES SD_CCCC_LOCK_UNLOCK SD_CCCC_WRITE_PROT SD_CCCC_ERASE DOCID026682 Rev 3 493/654 HAL SD Generic Driver SD_SDIO_SEND_IF_COND 494/654 UM1816 SDIO_APP_CMD should be sent before sending these commands. DOCID026682 Rev 3 UM1816 HAL SMARTCARD Generic Driver 38 HAL SMARTCARD Generic Driver 38.1 HAL SMARTCARD Generic Driver 38.2 SMARTCARD Firmware driver registers structures 38.2.1 SMARTCARD_InitTypeDef Data Fields uint32_t BaudRate uint32_t WordLength uint32_t StopBits uint32_t Parity uint32_t Mode uint32_t CLKPolarity uint32_t CLKPhase uint32_t CLKLastBit uint32_t Prescaler uint32_t GuardTime uint32_t NACKState Field Documentation uint32_t SMARTCARD_InitTypeDef::BaudRate This member configures the SmartCard communication baud rate. The baud rate is computed using the following formula:IntegerDivider = ((PCLKx) / (16 * (hsmartcard>Init.BaudRate)))FractionalDivider = ((IntegerDivider - ((uint32_t) IntegerDivider)) * 16) + 0.5 uint32_t SMARTCARD_InitTypeDef::WordLength Specifies the number of data bits transmitted or received in a frame. This parameter can be a value of SMARTCARD_Word_Length uint32_t SMARTCARD_InitTypeDef::StopBits Specifies the number of stop bits transmitted. This parameter can be a value of SMARTCARD_Stop_Bits uint32_t SMARTCARD_InitTypeDef::Parity Specifies the parity mode. This parameter can be a value of SMARTCARD_Parity Note:When parity is enabled, the computed parity is inserted at the MSB position of the transmitted data (9th bit when the word length is set to 9 data bits; 8th bit when the word length is set to 8 data bits). uint32_t SMARTCARD_InitTypeDef::Mode Specifies whether the Receive or Transmit mode is enabled or disabled. This parameter can be a value of SMARTCARD_Mode uint32_t SMARTCARD_InitTypeDef::CLKPolarity Specifies the steady state of the serial clock. This parameter can be a value of SMARTCARD_Clock_Polarity uint32_t SMARTCARD_InitTypeDef::CLKPhase Specifies the clock transition on which the bit capture is made. This parameter can be a value of SMARTCARD_Clock_Phase DOCID026682 Rev 3 495/654 HAL SMARTCARD Generic Driver 38.2.2 UM1816 uint32_t SMARTCARD_InitTypeDef::CLKLastBit Specifies whether the clock pulse corresponding to the last transmitted data bit (MSB) has to be output on the SCLK pin in synchronous mode. This parameter can be a value of SMARTCARD_Last_Bit uint32_t SMARTCARD_InitTypeDef::Prescaler Specifies the SmartCard Prescaler value used for dividing the system clock to provide the smartcard clock This parameter can be a value of SMARTCARD_Prescaler uint32_t SMARTCARD_InitTypeDef::GuardTime Specifies the SmartCard Guard Time value in terms of number of baud clocks The value given in the register (5 significant bits) is multiplied by 2 to give the division factor of the source clock frequency uint32_t SMARTCARD_InitTypeDef::NACKState Specifies the SmartCard NACK Transmission state This parameter can be a value of SMARTCARD_NACK_State SMARTCARD_HandleTypeDef Data Fields USART_TypeDef * Instance SMARTCARD_InitTypeDef Init uint8_t * pTxBuffPtr uint16_t TxXferSize uint16_t TxXferCount uint8_t * pRxBuffPtr uint16_t RxXferSize uint16_t RxXferCount DMA_HandleTypeDef * hdmatx DMA_HandleTypeDef * hdmarx HAL_LockTypeDef Lock __IO HAL_SMARTCARD_StateTypeDef State __IO uint32_t ErrorCode Field Documentation 496/654 USART_TypeDef* SMARTCARD_HandleTypeDef::Instance USART registers base address SMARTCARD_InitTypeDef SMARTCARD_HandleTypeDef::Init SmartCard communication parameters uint8_t* SMARTCARD_HandleTypeDef::pTxBuffPtr Pointer to SmartCard Tx transfer Buffer uint16_t SMARTCARD_HandleTypeDef::TxXferSize SmartCard Tx Transfer size uint16_t SMARTCARD_HandleTypeDef::TxXferCount SmartCard Tx Transfer Counter uint8_t* SMARTCARD_HandleTypeDef::pRxBuffPtr Pointer to SmartCard Rx transfer Buffer uint16_t SMARTCARD_HandleTypeDef::RxXferSize SmartCard Rx Transfer size uint16_t SMARTCARD_HandleTypeDef::RxXferCount SmartCard Rx Transfer Counter DOCID026682 Rev 3 UM1816 HAL SMARTCARD Generic Driver DMA_HandleTypeDef* SMARTCARD_HandleTypeDef::hdmatx SmartCard Tx DMA Handle parameters DMA_HandleTypeDef* SMARTCARD_HandleTypeDef::hdmarx SmartCard Rx DMA Handle parameters HAL_LockTypeDef SMARTCARD_HandleTypeDef::Lock Locking object __IO HAL_SMARTCARD_StateTypeDef SMARTCARD_HandleTypeDef::State SmartCard communication state __IO uint32_t SMARTCARD_HandleTypeDef::ErrorCode SmartCard Error code 38.3 SMARTCARD Firmware driver API description 38.3.1 How to use this driver The SMARTCARD HAL driver can be used as follows: 1. 2. 3. 4. 5. Declare a SMARTCARD_HandleTypeDef handle structure. Initialize the SMARTCARD low level resources by implementing the HAL_SMARTCARD_MspInit() API: a. Enable the interface clock of the USARTx associated to the SMARTCARD. b. SMARTCARD pins configuration: Enable the clock for the SMARTCARD GPIOs. Configure the SMARTCARD pins as alternate function pull-up. c. NVIC configuration if you need to use interrupt process (HAL_SMARTCARD_Transmit_IT() and HAL_SMARTCARD_Receive_IT() APIs): Configure the USARTx interrupt priority. Enable the NVIC USART IRQ handle. d. DMA Configuration if you need to use DMA process (HAL_SMARTCARD_Transmit_DMA() and HAL_SMARTCARD_Receive_DMA() APIs): Declare a DMA handle structure for the Tx/Rx 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 SMARTCARD 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) Program the Baud Rate, Word Length , Stop Bit, Parity, Hardware flow control and Mode(Receiver/Transmitter) in the SMARTCARD Init structure. Initialize the SMARTCARD registers by calling the HAL_SMARTCARD_Init() API: This API configures also the low level Hardware GPIO, CLOCK, CORTEX...etc) by calling the customed HAL_SMARTCARD_MspInit(&hsc) API. The specific SMARTCARD interrupts (Transmission complete interrupt, RXNE interrupt and Error Interrupts) will be managed using the macros __HAL_SMARTCARD_ENABLE_IT() and __HAL_SMARTCARD_DISABLE_IT() inside the transmit and receive process. Three operation modes are available within this driver : DOCID026682 Rev 3 497/654 HAL SMARTCARD Generic Driver UM1816 Polling mode IO operation Send an amount of data in blocking mode using HAL_SMARTCARD_Transmit() Receive an amount of data in blocking mode using HAL_SMARTCARD_Receive() Interrupt mode IO operation Send an amount of data in non blocking mode using HAL_SMARTCARD_Transmit_IT() At transmission end of transfer HAL_SMARTCARD_TxCpltCallback is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_TxCpltCallback Receive an amount of data in non blocking mode using HAL_SMARTCARD_Receive_IT() At reception end of transfer HAL_SMARTCARD_RxCpltCallback is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_RxCpltCallback In case of transfer Error, HAL_SMARTCARD_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_ErrorCallback DMA mode IO operation Send an amount of data in non blocking mode (DMA) using HAL_SMARTCARD_Transmit_DMA() At transmission end of transfer HAL_SMARTCARD_TxCpltCallback is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_TxCpltCallback Receive an amount of data in non blocking mode (DMA) using HAL_SMARTCARD_Receive_DMA() At reception end of transfer HAL_SMARTCARD_RxCpltCallback is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_RxCpltCallback In case of transfer Error, HAL_SMARTCARD_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_ErrorCallback SMARTCARD HAL driver macros list Below the list of most used macros in SMARTCARD HAL driver. 498/654 __HAL_SMARTCARD_ENABLE: Enable the SMARTCARD peripheral __HAL_SMARTCARD_DISABLE: Disable the SMARTCARD peripheral __HAL_SMARTCARD_GET_FLAG : Check whether the specified SMARTCARD flag is set or not __HAL_SMARTCARD_CLEAR_FLAG : Clear the specified SMARTCARD pending flag __HAL_SMARTCARD_ENABLE_IT: Enable the specified SMARTCARD interrupt __HAL_SMARTCARD_DISABLE_IT: Disable the specified SMARTCARD interrupt __HAL_SMARTCARD_GET_IT_SOURCE: Check whether the specified SMARTCARD interrupt has occurred or not DOCID026682 Rev 3 UM1816 HAL SMARTCARD Generic Driver You can refer to the SMARTCARD HAL driver header file for more useful macros 38.3.2 Initialization and Configuration functions This subsection provides a set of functions allowing to initialize the USART in Smartcard mode. The Smartcard interface is designed to support asynchronous protocol Smartcards as defined in the ISO 7816-3 standard. The USART can provide a clock to the smartcard through the SCLK output. In smartcard mode, SCLK is not associated to the communication but is simply derived from the internal peripheral input clock through a 5-bit prescaler. For the Smartcard mode only these parameters can be configured: Baud Rate Word Length => Should be 9 bits (8 bits + parity) Stop Bit Parity: => Should be enabled (see Table 23: "Smartcard frame formats") USART polarity USART phase USART LastBit Receiver/transmitter modes Prescaler GuardTime NACKState: The Smartcard NACK state Recommended SmartCard interface configuration to get the Answer to Reset from the Card: Word Length = 9 Bits 1.5 Stop Bit Even parity BaudRate = 12096 baud Tx and Rx enabled Table 23: Smartcard frame formats M bit PCE bit Smartcard frame 1 1 | SB | 8 bit data | PB | STB | It is also possible to choose 0.5 stop bit for receiving but it is recommended to use 1.5 stop bits for both transmitting and receiving to avoid switching between the two configurations. The HAL_SMARTCARD_Init() function follows the USART SmartCard configuration procedure (details for the procedure are available in reference manual (RM0038)). This section contains the following APIs: HAL_SMARTCARD_Init() HAL_SMARTCARD_DeInit() HAL_SMARTCARD_MspInit() DOCID026682 Rev 3 499/654 HAL SMARTCARD Generic Driver 38.3.3 UM1816 HAL_SMARTCARD_MspDeInit() IO operation functions This subsection provides a set of functions allowing to manage the SMARTCARD data transfers. 1. 2. 3. 4. 5. 6. 7. Smartcard is a single wire half duplex communication protocol. The Smartcard interface is designed to support asynchronous protocol Smartcards as defined in the ISO 7816-3 standard. The USART should be configured as: 8 bits plus parity: where M=1 and PCE=1 in the USART_CR1 register 1.5 stop bits when transmitting and receiving: where STOP=11 in the USART_CR2 register. There are two modes of transfer: Blocking mode: The communication is performed in polling mode. The HAL status of all data processing is returned by the same function after finishing transfer. No-Blocking mode: The communication is performed using Interrupts or DMA, the relevant API's return the HAL status. The end of the data processing will be indicated through the dedicated SMARTCARD IRQ when using Interrupt mode or the DMA IRQ when using DMA mode. The HAL_SMARTCARD_TxCpltCallback(), HAL_SMARTCARD_RxCpltCallback() user callbacks will be executed respectively at the end of the Transmit or Receive process The HAL_SMARTCARD_ErrorCallback() user callback will be executed when a communication error is detected. Blocking mode APIs are : HAL_SMARTCARD_Transmit() HAL_SMARTCARD_Receive() Non Blocking mode APIs with Interrupt are : HAL_SMARTCARD_Transmit_IT() HAL_SMARTCARD_Receive_IT() HAL_SMARTCARD_IRQHandler() Non Blocking mode functions with DMA are : HAL_SMARTCARD_Transmit_DMA() HAL_SMARTCARD_Receive_DMA() A set of Transfer Complete Callbacks are provided in non Blocking mode: HAL_SMARTCARD_TxCpltCallback() HAL_SMARTCARD_RxCpltCallback() HAL_SMARTCARD_ErrorCallback() This section contains the following APIs: 500/654 HAL_SMARTCARD_Transmit() HAL_SMARTCARD_Receive() HAL_SMARTCARD_Transmit_IT() HAL_SMARTCARD_Receive_IT() HAL_SMARTCARD_Transmit_DMA() HAL_SMARTCARD_Receive_DMA() HAL_SMARTCARD_IRQHandler() HAL_SMARTCARD_TxCpltCallback() HAL_SMARTCARD_RxCpltCallback() HAL_SMARTCARD_ErrorCallback() DOCID026682 Rev 3 UM1816 38.3.4 HAL SMARTCARD Generic Driver Peripheral State and Errors functions This subsection provides a set of functions allowing to return the State of SmartCard communication process and also return Peripheral Errors occurred during communication process HAL_SMARTCARD_GetState() API can be helpful to check in run-time the state of the SMARTCARD peripheral. HAL_SMARTCARD_GetError() check in run-time errors that could be occurred during communication. This section contains the following APIs: 38.3.5 38.3.6 38.3.7 38.3.8 HAL_SMARTCARD_GetState() HAL_SMARTCARD_GetError() HAL_SMARTCARD_Init Function Name HAL_StatusTypeDef HAL_SMARTCARD_Init (SMARTCARD_HandleTypeDef * hsc) Function Description Initializes the SmartCard mode according to the specified parameters in the SMARTCARD_HandleTypeDef and create the associated handle. Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. Return values HAL status HAL_SMARTCARD_DeInit Function Name HAL_StatusTypeDef HAL_SMARTCARD_DeInit (SMARTCARD_HandleTypeDef * hsc) Function Description DeInitializes the SMARTCARD peripheral. Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. Return values HAL status HAL_SMARTCARD_MspInit Function Name void HAL_SMARTCARD_MspInit (SMARTCARD_HandleTypeDef * hsc) Function Description SMARTCARD MSP Init. Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. Return values None HAL_SMARTCARD_MspDeInit Function Name void HAL_SMARTCARD_MspDeInit (SMARTCARD_HandleTypeDef * hsc) DOCID026682 Rev 3 501/654 HAL SMARTCARD Generic Driver Function Description 38.3.9 Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. Return values None HAL_SMARTCARD_Transmit Function Name HAL_StatusTypeDef HAL_SMARTCARD_Transmit (SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t Size, uint32_t Timeout) Function Description Sends an amount of data in blocking mode. Parameters Return values 38.3.10 502/654 HAL status Function Name HAL_StatusTypeDef HAL_SMARTCARD_Receive (SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t Size, uint32_t Timeout) Function Description Receive an amount of data in blocking mode. Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. pData: Pointer to data buffer Size: Amount of data to be received Timeout: Specify timeout value HAL status HAL_SMARTCARD_Transmit_IT Function Name HAL_StatusTypeDef HAL_SMARTCARD_Transmit_IT (SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t Size) Function Description Sends an amount of data in non-blocking mode. Parameters Return values 38.3.12 hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. pData: Pointer to data buffer Size: Amount of data to be sent Timeout: Specify timeout value HAL_SMARTCARD_Receive Return values 38.3.11 UM1816 SMARTCARD MSP DeInit. hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. pData: Pointer to data buffer Size: Amount of data to be sent HAL status HAL_SMARTCARD_Receive_IT DOCID026682 Rev 3 UM1816 Function Name HAL SMARTCARD Generic Driver HAL_StatusTypeDef HAL_SMARTCARD_Receive_IT (SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t Size) Function Description Receives an amount of data in non-blocking mode. Parameters Return values 38.3.13 38.3.15 HAL status HAL_SMARTCARD_Transmit_DMA Function Name HAL_StatusTypeDef HAL_SMARTCARD_Transmit_DMA (SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t Size) Function Description Sends an amount of data in non-blocking mode. Parameters Return values 38.3.14 hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. pData: Pointer to data buffer Size: Amount of data to be received hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. pData: Pointer to data buffer Size: Amount of data to be sent HAL status HAL_SMARTCARD_Receive_DMA Function Name HAL_StatusTypeDef HAL_SMARTCARD_Receive_DMA (SMARTCARD_HandleTypeDef * hsc, uint8_t * pData, uint16_t Size) Function Description Receive an amount of data in non-blocking mode. Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. pData: Pointer to data buffer Size: Amount of data to be received Return values HAL status Notes When the SMARTCARD parity is enabled (PCE = 1) the data received contain the parity bit. HAL_SMARTCARD_IRQHandler Function Name void HAL_SMARTCARD_IRQHandler (SMARTCARD_HandleTypeDef * hsc) Function Description This function handles SMARTCARD interrupt request. Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. DOCID026682 Rev 3 503/654 HAL SMARTCARD Generic Driver Return values 38.3.16 38.3.17 38.3.18 38.3.19 38.3.20 None HAL_SMARTCARD_TxCpltCallback Function Name void HAL_SMARTCARD_TxCpltCallback (SMARTCARD_HandleTypeDef * hsc) Function Description Tx Transfer completed callback. Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. Return values None HAL_SMARTCARD_RxCpltCallback Function Name void HAL_SMARTCARD_RxCpltCallback (SMARTCARD_HandleTypeDef * hsc) Function Description Rx Transfer completed callback. Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. Return values None HAL_SMARTCARD_ErrorCallback Function Name void HAL_SMARTCARD_ErrorCallback (SMARTCARD_HandleTypeDef * hsc) Function Description SMARTCARD error callback. Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. Return values None HAL_SMARTCARD_GetState Function Name HAL_SMARTCARD_StateTypeDef HAL_SMARTCARD_GetState (SMARTCARD_HandleTypeDef * hsc) Function Description Returns the SMARTCARD state. Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. Return values HAL state HAL_SMARTCARD_GetError Function Name 504/654 UM1816 uint32_t HAL_SMARTCARD_GetError (SMARTCARD_HandleTypeDef * hsc) DOCID026682 Rev 3 UM1816 Function Description HAL SMARTCARD Generic Driver Return the SMARTCARD error code. Parameters hsc: Pointer to a SMARTCARD_HandleTypeDef structure that contains the configuration information for the specified SMARTCARD module. Return values SMARTCARD Error Code 38.4 SMARTCARD Firmware driver defines 38.4.1 SMARTCARD SMARTCARD Clock Phase SMARTCARD_PHASE_1EDGE SMARTCARD_PHASE_2EDGE SMARTCARD Clock Polarity SMARTCARD_POLARITY_LOW SMARTCARD_POLARITY_HIGH SMARTCARD DMA requests SMARTCARD_DMAREQ_TX SMARTCARD_DMAREQ_RX SMARTCARD Error Codes HAL_SMARTCARD_ERROR_NONE No error HAL_SMARTCARD_ERROR_PE Parity error HAL_SMARTCARD_ERROR_NE Noise error HAL_SMARTCARD_ERROR_FE frame error HAL_SMARTCARD_ERROR_ORE Overrun error HAL_SMARTCARD_ERROR_DMA DMA transfer error SMARTCARD Exported Macros __HAL_SMARTCARD_RESET_HANDLE_STA TE Description: Reset SMARTCARD handle state. Parameters: __HANDLE__: specifies the SMARTCARD Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_SMARTCARD_FLUSH_DRREGISTER Description: DOCID026682 Rev 3 None Flush the Smartcard DR register. 505/654 HAL SMARTCARD Generic Driver UM1816 Parameters: __HANDLE__: specifies the SMARTCARD Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_SMARTCARD_GET_FLAG None Description: Check whether the specified Smartcard flag is set or not. Parameters: __HANDLE__: specifies the SMARTCARD Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). __FLAG__: specifies the flag to check. This parameter can be one of the following values: SMARTCARD_FLAG_TXE: Transmit data register empty flag SMARTCARD_FLAG_TC: Transmission Complete flag SMARTCARD_FLAG_RXNE: Receive data register not empty flag SMARTCARD_FLAG_IDLE: Idle Line detection flag SMARTCARD_FLAG_ORE: OverRun Error flag SMARTCARD_FLAG_NE: Noise Error flag SMARTCARD_FLAG_FE: Framing Error flag SMARTCARD_FLAG_PE: Parity Error flag Return value: __HAL_SMARTCARD_CLEAR_FLAG The: new state of __FLAG__ (TRUE or FALSE). Description: Clear the specified Smartcard pending flags. Parameters: 506/654 DOCID026682 Rev 3 __HANDLE__: specifies the UM1816 HAL SMARTCARD Generic Driver SMARTCARD Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). __FLAG__: specifies the flag to check. This parameter can be any combination of the following values: SMARTCARD_FLAG_TC: Transmission Complete flag. SMARTCARD_FLAG_RXNE: Receive data register not empty flag. Return value: None None Notes: __HAL_SMARTCARD_CLEAR_PEFLAG PE (Parity error), FE (Framing error), NE (Noise error) and ORE (OverRun error) flags are cleared by software sequence: a read operation to USART_SR register followed by a read operation to USART_DR register. RXNE flag can be also cleared by a read to the USART_DR register. TC flag can be also cleared by software sequence: a read operation to USART_SR register followed by a write operation to USART_DR register. TXE flag is cleared only by a write to the USART_DR register. Description: Clear the SMARTCARD PE pending flag. Parameters: __HANDLE__: specifies the USART Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_SMARTCARD_CLEAR_FEFLAG Description: DOCID026682 Rev 3 None Clear the SMARTCARD FE pending flag. 507/654 HAL SMARTCARD Generic Driver UM1816 Parameters: __HANDLE__: specifies the USART Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_SMARTCARD_CLEAR_NEFLAG None Description: Clear the SMARTCARD NE pending flag. Parameters: __HANDLE__: specifies the USART Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_SMARTCARD_CLEAR_OREFLAG None Description: Clear the SMARTCARD ORE pending flag. Parameters: __HANDLE__: specifies the USART Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_SMARTCARD_CLEAR_IDLEFLAG None Description: Clear the SMARTCARD IDLE pending flag. Parameters: __HANDLE__: specifies the USART Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_SMARTCARD_ENABLE_IT Description: 508/654 DOCID026682 Rev 3 None Enable the specified SmartCard UM1816 HAL SMARTCARD Generic Driver interrupt. Parameters: __HANDLE__: specifies the SMARTCARD Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). __INTERRUPT__: specifies the SMARTCARD interrupt to enable. This parameter can be one of the following values: SMARTCARD_IT_TXE: Transmit Data Register empty interrupt SMARTCARD_IT_TC: Transmission complete interrupt SMARTCARD_IT_RXNE: Receive Data register not empty interrupt SMARTCARD_IT_IDLE: Idle line detection interrupt SMARTCARD_IT_PE: Parity Error interrupt SMARTCARD_IT_ERR: Error interrupt(Frame error, noise error, overrun error) Return value: __HAL_SMARTCARD_DISABLE_IT None Description: Disable the specified SmartCard interrupts. Parameters: DOCID026682 Rev 3 __HANDLE__: specifies the SMARTCARD Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). __INTERRUPT__: specifies the SMARTCARD interrupt to disable. This parameter can be one of the following values: SMARTCARD_IT_TXE: Transmit Data Register empty interrupt SMARTCARD_IT_TC: Transmission complete interrupt 509/654 HAL SMARTCARD Generic Driver UM1816 __HAL_SMARTCARD_GET_IT_SOURCE SMARTCARD_IT_RXNE: Receive Data register not empty interrupt SMARTCARD_IT_IDLE: Idle line detection interrupt SMARTCARD_IT_PE: Parity Error interrupt SMARTCARD_IT_ERR: Error interrupt(Frame error, noise error, overrun error) Description: Check whether the specified SmartCard interrupt has occurred or not. Parameters: __HANDLE__: specifies the SMARTCARD Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). __IT__: specifies the SMARTCARD interrupt source to check. This parameter can be one of the following values: SMARTCARD_IT_TXE: Transmit Data Register empty interrupt SMARTCARD_IT_TC: Transmission complete interrupt SMARTCARD_IT_RXNE: Receive Data register not empty interrupt SMARTCARD_IT_IDLE: Idle line detection interrupt SMARTCARD_IT_ERR: Error interrupt SMARTCARD_IT_PE: Parity Error interrupt Return value: __HAL_SMARTCARD_ONE_BIT_SAMPLE_EN ABLE The: new state of __IT__ (TRUE or FALSE). Description: Enables the SMARTCARD one bit sample method. Parameters: 510/654 DOCID026682 Rev 3 __HANDLE__: specifies the SMARTCARD Handle. UM1816 HAL SMARTCARD Generic Driver Return value: __HAL_SMARTCARD_ONE_BIT_SAMPLE_DI SABLE None Description: Disables the SMARTCARD one bit sample method. Parameters: __HANDLE__: specifies the SMARTCARD Handle. Return value: __HAL_SMARTCARD_ENABLE None Description: Enable the USART associated to the SMARTCARD Handle. Parameters: __HANDLE__: specifies the SMARTCARD Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_SMARTCARD_DISABLE None Description: Disable the USART associated to the SMARTCARD Handle. Parameters: __HANDLE__: specifies the SMARTCARD Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_SMARTCARD_DMA_REQUEST_ENAB LE None Description: Enable the SmartCard DMA request. Parameters: DOCID026682 Rev 3 __HANDLE__: specifies the SmartCard Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). 511/654 HAL SMARTCARD Generic Driver UM1816 __REQUEST__: specifies the SmartCard DMA request. This parameter can be one of the following values: SMARTCARD_DMAREQ_TX: SmartCard DMA transmit request SMARTCARD_DMAREQ_RX : SmartCard DMA receive request Return value: __HAL_SMARTCARD_DMA_REQUEST_DISA BLE None Description: Disable the SmartCard DMA request. Parameters: __HANDLE__: specifies the SmartCard Handle. SMARTCARD Handle selects the USARTx peripheral (USART availability and x value depending on device). __REQUEST__: specifies the SmartCard DMA request. This parameter can be one of the following values: SMARTCARD_DMAREQ_TX: SmartCard DMA transmit request SMARTCARD_DMAREQ_RX : SmartCard DMA receive request Return value: SMARTCARD Flags SMARTCARD_FLAG_TXE SMARTCARD_FLAG_TC SMARTCARD_FLAG_RXNE SMARTCARD_FLAG_IDLE SMARTCARD_FLAG_ORE SMARTCARD_FLAG_NE SMARTCARD_FLAG_FE SMARTCARD_FLAG_PE SMARTCARD Interrupts Definition SMARTCARD_IT_PE 512/654 DOCID026682 Rev 3 None UM1816 HAL SMARTCARD Generic Driver SMARTCARD_IT_TXE SMARTCARD_IT_TC SMARTCARD_IT_RXNE SMARTCARD_IT_IDLE SMARTCARD_IT_ERR SMARTCARD Last Bit SMARTCARD_LASTBIT_DISABLE SMARTCARD_LASTBIT_ENABLE SMARTCARD Mode SMARTCARD_MODE_RX SMARTCARD_MODE_TX SMARTCARD_MODE_TX_RX SMARTCARD NACK State SMARTCARD_NACK_ENABLE SMARTCARD_NACK_DISABLE SMARTCARD One Bit Sampling Method SMARTCARD_ONE_BIT_SAMPLE_DISABLE SMARTCARD_ONE_BIT_SAMPLE_ENABLE SMARTCARD Parity SMARTCARD_PARITY_EVEN SMARTCARD_PARITY_ODD SMARTCARD Prescaler SMARTCARD_PRESCALER_SYSCLK_DIV2 SYSCLK divided by 2 SMARTCARD_PRESCALER_SYSCLK_DIV4 SYSCLK divided by 4 SMARTCARD_PRESCALER_SYSCLK_DIV6 SYSCLK divided by 6 SMARTCARD_PRESCALER_SYSCLK_DIV8 SYSCLK divided by 8 SMARTCARD_PRESCALER_SYSCLK_DIV10 SYSCLK divided by 10 SMARTCARD_PRESCALER_SYSCLK_DIV12 SYSCLK divided by 12 SMARTCARD_PRESCALER_SYSCLK_DIV14 SYSCLK divided by 14 SMARTCARD_PRESCALER_SYSCLK_DIV16 SYSCLK divided by 16 SMARTCARD_PRESCALER_SYSCLK_DIV18 SYSCLK divided by 18 SMARTCARD_PRESCALER_SYSCLK_DIV20 SYSCLK divided by 20 SMARTCARD_PRESCALER_SYSCLK_DIV22 SYSCLK divided by 22 SMARTCARD_PRESCALER_SYSCLK_DIV24 SYSCLK divided by 24 SMARTCARD_PRESCALER_SYSCLK_DIV26 SYSCLK divided by 26 SMARTCARD_PRESCALER_SYSCLK_DIV28 SYSCLK divided by 28 DOCID026682 Rev 3 513/654 HAL SMARTCARD Generic Driver SMARTCARD_PRESCALER_SYSCLK_DIV30 SYSCLK divided by 30 UM1816 SMARTCARD_PRESCALER_SYSCLK_DIV32 SYSCLK divided by 32 SMARTCARD_PRESCALER_SYSCLK_DIV34 SYSCLK divided by 34 SMARTCARD_PRESCALER_SYSCLK_DIV36 SYSCLK divided by 36 SMARTCARD_PRESCALER_SYSCLK_DIV38 SYSCLK divided by 38 SMARTCARD_PRESCALER_SYSCLK_DIV40 SYSCLK divided by 40 SMARTCARD_PRESCALER_SYSCLK_DIV42 SYSCLK divided by 42 SMARTCARD_PRESCALER_SYSCLK_DIV44 SYSCLK divided by 44 SMARTCARD_PRESCALER_SYSCLK_DIV46 SYSCLK divided by 46 SMARTCARD_PRESCALER_SYSCLK_DIV48 SYSCLK divided by 48 SMARTCARD_PRESCALER_SYSCLK_DIV50 SYSCLK divided by 50 SMARTCARD_PRESCALER_SYSCLK_DIV52 SYSCLK divided by 52 SMARTCARD_PRESCALER_SYSCLK_DIV54 SYSCLK divided by 54 SMARTCARD_PRESCALER_SYSCLK_DIV56 SYSCLK divided by 56 SMARTCARD_PRESCALER_SYSCLK_DIV58 SYSCLK divided by 58 SMARTCARD_PRESCALER_SYSCLK_DIV60 SYSCLK divided by 60 SMARTCARD_PRESCALER_SYSCLK_DIV62 SYSCLK divided by 62 SMARTCARD Private Macros SMARTCARD_CR1_REG_INDEX SMARTCARD_CR3_REG_INDEX SMARTCARD_DIV SMARTCARD_DIVMANT SMARTCARD_DIVFRAQ SMARTCARD_BRR IS_SMARTCARD_BAUDRATE The maximum Baud Rate is derived from the maximum clock on APB (i.e. 32 MHz) divided by the smallest oversampling used on the USART (i.e. 16) __BAUDRATE__: Baud rate set by the configuration function. Return : TRUE or FALSE IS_SMARTCARD_WORD_LENGTH IS_SMARTCARD_STOPBITS IS_SMARTCARD_PARITY IS_SMARTCARD_MODE IS_SMARTCARD_POLARITY IS_SMARTCARD_PHASE IS_SMARTCARD_LASTBIT IS_SMARTCARD_ONE_BIT_SAMPLE IS_SMARTCARD_NACK_STATE 514/654 DOCID026682 Rev 3 UM1816 HAL SMARTCARD Generic Driver IS_SMARTCARD_PRESCALER SMARTCARD_IT_MASK SMARTCARD Number of Stop Bits SMARTCARD_STOPBITS_0_5 SMARTCARD_STOPBITS_1_5 SMARTCARD Word Length SMARTCARD_WORDLENGTH_9B DOCID026682 Rev 3 515/654 HAL SPI Generic Driver UM1816 39 HAL SPI Generic Driver 39.1 HAL SPI Generic Driver 39.2 SPI Firmware driver registers structures 39.2.1 SPI_InitTypeDef Data Fields uint32_t Mode uint32_t Direction uint32_t DataSize uint32_t CLKPolarity uint32_t CLKPhase uint32_t NSS uint32_t BaudRatePrescaler uint32_t FirstBit uint32_t TIMode uint32_t CRCCalculation uint32_t CRCPolynomial Field Documentation 516/654 uint32_t SPI_InitTypeDef::Mode Specifies the SPI operating mode. This parameter can be a value of SPI_mode uint32_t SPI_InitTypeDef::Direction Specifies the SPI Directional mode state. This parameter can be a value of SPI_Direction_mode uint32_t SPI_InitTypeDef::DataSize Specifies the SPI data size. This parameter can be a value of SPI_data_size uint32_t SPI_InitTypeDef::CLKPolarity Specifies the serial clock steady state. This parameter can be a value of SPI_Clock_Polarity uint32_t SPI_InitTypeDef::CLKPhase Specifies the clock active edge for the bit capture. This parameter can be a value of SPI_Clock_Phase uint32_t SPI_InitTypeDef::NSS Specifies whether the NSS signal is managed by hardware (NSS pin) or by software using the SSI bit. This parameter can be a value of SPI_Slave_Select_management uint32_t SPI_InitTypeDef::BaudRatePrescaler Specifies the Baud Rate prescaler value which will be used to configure the transmit and receive SCK clock. This parameter can be a value of SPI_BaudRate_Prescaler Note:The communication clock is derived from the master clock. The slave clock does not need to be set uint32_t SPI_InitTypeDef::FirstBit Specifies whether data transfers start from MSB or LSB bit. This parameter can be a value of SPI_MSB_LSB_transmission DOCID026682 Rev 3 UM1816 HAL SPI Generic Driver 39.2.2 uint32_t SPI_InitTypeDef::TIMode Specifies if the TI mode is enabled or not. This parameter can be a value of SPI_TI_mode uint32_t SPI_InitTypeDef::CRCCalculation Specifies if the CRC calculation is enabled or not. This parameter can be a value of SPI_CRC_Calculation uint32_t SPI_InitTypeDef::CRCPolynomial Specifies the polynomial used for the CRC calculation. This parameter must be a number between Min_Data = 0 and Max_Data = 65535 __SPI_HandleTypeDef Data Fields SPI_TypeDef * Instance SPI_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 void(* RxISR void(* TxISR HAL_LockTypeDef Lock __IO HAL_SPI_StateTypeDef State __IO uint32_t ErrorCode Field Documentation SPI_TypeDef* __SPI_HandleTypeDef::Instance SPI_InitTypeDef __SPI_HandleTypeDef::Init uint8_t* __SPI_HandleTypeDef::pTxBuffPtr uint16_t __SPI_HandleTypeDef::TxXferSize uint16_t __SPI_HandleTypeDef::TxXferCount uint8_t* __SPI_HandleTypeDef::pRxBuffPtr uint16_t __SPI_HandleTypeDef::RxXferSize uint16_t __SPI_HandleTypeDef::RxXferCount DMA_HandleTypeDef* __SPI_HandleTypeDef::hdmatx DMA_HandleTypeDef* __SPI_HandleTypeDef::hdmarx void(* __SPI_HandleTypeDef::RxISR)(struct __SPI_HandleTypeDef *hspi) void(* __SPI_HandleTypeDef::TxISR)(struct __SPI_HandleTypeDef *hspi) HAL_LockTypeDef __SPI_HandleTypeDef::Lock __IO HAL_SPI_StateTypeDef __SPI_HandleTypeDef::State __IO uint32_t __SPI_HandleTypeDef::ErrorCode DOCID026682 Rev 3 517/654 HAL SPI Generic Driver UM1816 39.3 SPI Firmware driver API description 39.3.1 How to use this driver The SPI HAL driver can be used as follows: 1. 2. 3. 4. Declare a SPI_HandleTypeDef handle structure, for example: SPI_HandleTypeDef hspi; Initialize the SPI low level resources by implementing the HAL_SPI_MspInit ()API: a. Enable the SPIx interface clock b. SPI pins configuration Enable the clock for the SPI GPIOs Configure these SPI pins as alternate function push-pull c. NVIC configuration if you need to use interrupt process Configure the SPIx interrupt priority Enable the NVIC SPI IRQ handle d. DMA Configuration if you need to use DMA process Declare a DMA_HandleTypeDef handle structure for the transmit or receive Channel Enable the DMAx clock Configure the DMA handle parameters Configure the DMA Tx or Rx Channel Associate the initilalized hdma_tx(or _rx) handle to the hspi DMA Tx (or Rx) handle Configure the priority and enable the NVIC for the transfer complete interrupt on the DMA Tx or Rx Channel Program the Mode, Direction , Data size, Baudrate Prescaler, NSS management, Clock polarity and phase, FirstBit and CRC configuration in the hspi Init structure. Initialize the SPI registers by calling the HAL_SPI_Init() API: This API configures also the low level Hardware GPIO, CLOCK, CORTEX...etc) by calling the customed HAL_SPI_MspInit() API. Circular mode restriction: 1. 2. 3. 39.3.2 The DMA circular mode cannot be used when the SPI is configured in these modes: a. Master 2Lines RxOnly b. Master 1Line Rx The CRC feature is not managed when the DMA circular mode is enabled When the SPI DMA Pause/Stop features are used, we must use the following APIs the HAL_SPI_DMAPause()/ HAL_SPI_DMAStop() only under the SPI callbacks Initialization and de-initialization functions This subsection provides a set of functions allowing to initialize and de-initialiaze the SPIx peripheral: 518/654 User must implement HAL_SPI_MspInit() function in which he configures all related peripherals resources (CLOCK, GPIO, DMA, IT and NVIC ). Call the function HAL_SPI_Init() to configure the selected device with the selected configuration: Mode Direction Data Size Clock Polarity and Phase NSS Management BaudRate Prescaler FirstBit DOCID026682 Rev 3 UM1816 HAL SPI Generic Driver TIMode CRC Calculation CRC Polynomial if CRC enabled Call the function HAL_SPI_DeInit() to restore the default configuration of the selected SPIx periperal. This section contains the following APIs: 39.3.3 HAL_SPI_Init() HAL_SPI_DeInit() HAL_SPI_MspInit() HAL_SPI_MspDeInit() IO operation functions The SPI supports master and slave mode : 1. 2. There are two modes of transfer: Blocking mode: The communication is performed in polling mode. The HAL status of all data processing is returned by the same function after finishing transfer. No-Blocking mode: The communication is performed using Interrupts or DMA, These APIs return the HAL status. The end of the data processing will be indicated through the dedicated SPI IRQ when using Interrupt mode or the DMA IRQ when using DMA mode. The HAL_SPI_TxCpltCallback(), HAL_SPI_RxCpltCallback() and HAL_SPI_TxRxCpltCallback() user callbacks will be executed respectivelly at the end of the transmit or Receive process The HAL_SPI_ErrorCallback()user callback will be executed when a communication error is detected APIs provided for these 2 transfer modes (Blocking mode or Non blocking mode using either Interrupt or DMA) exist for 1Line (simplex) and 2Lines (full duplex) modes. This section contains the following APIs: HAL_SPI_Transmit() HAL_SPI_Receive() HAL_SPI_TransmitReceive() HAL_SPI_Transmit_IT() HAL_SPI_Receive_IT() HAL_SPI_TransmitReceive_IT() HAL_SPI_Transmit_DMA() HAL_SPI_Receive_DMA() HAL_SPI_TransmitReceive_DMA() HAL_SPI_DMAPause() HAL_SPI_DMAResume() HAL_SPI_DMAStop() HAL_SPI_IRQHandler() HAL_SPI_TxCpltCallback() HAL_SPI_RxCpltCallback() HAL_SPI_TxRxCpltCallback() HAL_SPI_TxHalfCpltCallback() HAL_SPI_RxHalfCpltCallback() HAL_SPI_TxRxHalfCpltCallback() HAL_SPI_ErrorCallback() DOCID026682 Rev 3 519/654 HAL SPI Generic Driver 39.3.4 UM1816 Peripheral State and Errors functions This subsection provides a set of functions allowing to control the SPI. HAL_SPI_GetState() API can be helpful to check in run-time the state of the SPI peripheral HAL_SPI_GetError() check in run-time Errors occurring during communication This section contains the following APIs: 39.3.5 39.3.6 39.3.7 39.3.8 39.3.9 HAL_SPI_GetState() HAL_SPI_GetError() HAL_SPI_Init Function Name HAL_StatusTypeDef HAL_SPI_Init (SPI_HandleTypeDef * hspi) Function Description Initializes the SPI according to the specified parameters in the SPI_InitTypeDef and create the associated handle. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values HAL status HAL_SPI_DeInit Function Name HAL_StatusTypeDef HAL_SPI_DeInit (SPI_HandleTypeDef * hspi) Function Description DeInitializes the SPI peripheral. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values HAL status HAL_SPI_MspInit Function Name void HAL_SPI_MspInit (SPI_HandleTypeDef * hspi) Function Description SPI MSP Init. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values None HAL_SPI_MspDeInit Function Name void HAL_SPI_MspDeInit (SPI_HandleTypeDef * hspi) Function Description SPI MSP DeInit. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values None HAL_SPI_Transmit Function Name 520/654 HAL_StatusTypeDef HAL_SPI_Transmit (SPI_HandleTypeDef * DOCID026682 Rev 3 UM1816 HAL SPI Generic Driver hspi, uint8_t * pData, uint16_t Size, uint32_t Timeout) Function Description Transmit an amount of data in blocking mode. Parameters Return values 39.3.10 HAL_StatusTypeDef HAL_SPI_Receive (SPI_HandleTypeDef * hspi, uint8_t * pData, uint16_t Size, uint32_t Timeout) Function Description Receive an amount of data in blocking mode. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. pData: pointer to data buffer Size: amount of data to be sent Timeout: Timeout duration HAL status HAL_SPI_TransmitReceive Function Name HAL_StatusTypeDef HAL_SPI_TransmitReceive (SPI_HandleTypeDef * hspi, uint8_t * pTxData, uint8_t * pRxData, uint16_t Size, uint32_t Timeout) Function Description Transmit and Receive an amount of data in blocking mode. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. pTxData: pointer to transmission data buffer pRxData: pointer to reception data buffer to be Size: amount of data to be sent Timeout: Timeout duration HAL status HAL_SPI_Transmit_IT Function Name HAL_StatusTypeDef HAL_SPI_Transmit_IT (SPI_HandleTypeDef * hspi, uint8_t * pData, uint16_t Size) Function Description Transmit an amount of data in no-blocking mode with Interrupt. Parameters Return values 39.3.13 HAL status Function Name Return values 39.3.12 HAL_SPI_Receive Return values 39.3.11 hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. pData: pointer to data buffer Size: amount of data to be sent Timeout: Timeout duration hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. pData: pointer to data buffer Size: amount of data to be sent HAL status HAL_SPI_Receive_IT DOCID026682 Rev 3 521/654 HAL SPI Generic Driver Function Name Function Description Receive an amount of data in no-blocking mode with Interrupt. Parameters Return values 39.3.14 522/654 HAL status Function Name HAL_StatusTypeDef HAL_SPI_TransmitReceive_IT (SPI_HandleTypeDef * hspi, uint8_t * pTxData, uint8_t * pRxData, uint16_t Size) Function Description Transmit and Receive an amount of data in no-blocking mode with Interrupt. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. pTxData: pointer to transmission data buffer pRxData: pointer to reception data buffer to be Size: amount of data to be sent HAL status HAL_SPI_Transmit_DMA Function Name HAL_StatusTypeDef HAL_SPI_Transmit_DMA (SPI_HandleTypeDef * hspi, uint8_t * pData, uint16_t Size) Function Description Transmit an amount of data in no-blocking mode with DMA. Parameters Return values 39.3.16 hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. pData: pointer to data buffer Size: amount of data to be sent HAL_SPI_TransmitReceive_IT Return values 39.3.15 UM1816 HAL_StatusTypeDef HAL_SPI_Receive_IT (SPI_HandleTypeDef * hspi, uint8_t * pData, uint16_t Size) hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. pData: pointer to data buffer Size: amount of data to be sent HAL status HAL_SPI_Receive_DMA Function Name HAL_StatusTypeDef HAL_SPI_Receive_DMA (SPI_HandleTypeDef * hspi, uint8_t * pData, uint16_t Size) Function Description Receive an amount of data in no-blocking mode with DMA. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. pData: pointer to data buffer Size: amount of data to be sent Return values HAL status Notes When the CRC feature is enabled the pData Length must be Size + 1. DOCID026682 Rev 3 UM1816 39.3.17 39.3.18 39.3.19 39.3.20 39.3.21 HAL SPI Generic Driver HAL_SPI_TransmitReceive_DMA Function Name HAL_StatusTypeDef HAL_SPI_TransmitReceive_DMA (SPI_HandleTypeDef * hspi, uint8_t * pTxData, uint8_t * pRxData, uint16_t Size) Function Description Transmit and Receive an amount of data in no-blocking mode with DMA. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. pTxData: pointer to transmission data buffer pRxData: pointer to reception data buffer Size: amount of data to be sent Return values HAL status Notes When the CRC feature is enabled the pRxData Length must be Size + 1 HAL_SPI_DMAPause Function Name HAL_StatusTypeDef HAL_SPI_DMAPause (SPI_HandleTypeDef * hspi) Function Description Pauses the DMA Transfer. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for the specified SPI module. Return values HAL status HAL_SPI_DMAResume Function Name HAL_StatusTypeDef HAL_SPI_DMAResume (SPI_HandleTypeDef * hspi) Function Description Resumes the DMA Transfer. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for the specified SPI module. Return values HAL status HAL_SPI_DMAStop Function Name HAL_StatusTypeDef HAL_SPI_DMAStop (SPI_HandleTypeDef * hspi) Function Description Stops the DMA Transfer. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_SPI_IRQHandler Function Name void HAL_SPI_IRQHandler (SPI_HandleTypeDef * hspi) Function Description This function handles SPI interrupt request. DOCID026682 Rev 3 523/654 HAL SPI Generic Driver Parameters Return values 39.3.22 39.3.23 39.3.24 39.3.25 39.3.26 524/654 UM1816 hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. HAL status HAL_SPI_TxCpltCallback Function Name void HAL_SPI_TxCpltCallback (SPI_HandleTypeDef * hspi) Function Description Tx Transfer completed callbacks. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values None HAL_SPI_RxCpltCallback Function Name void HAL_SPI_RxCpltCallback (SPI_HandleTypeDef * hspi) Function Description Rx Transfer completed callbacks. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values None HAL_SPI_TxRxCpltCallback Function Name void HAL_SPI_TxRxCpltCallback (SPI_HandleTypeDef * hspi) Function Description Tx and Rx Transfer completed callbacks. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values None HAL_SPI_TxHalfCpltCallback Function Name void HAL_SPI_TxHalfCpltCallback (SPI_HandleTypeDef * hspi) Function Description Tx Half Transfer completed callbacks. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values None HAL_SPI_RxHalfCpltCallback Function Name void HAL_SPI_RxHalfCpltCallback (SPI_HandleTypeDef * hspi) Function Description Rx Half Transfer completed callbacks. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values None DOCID026682 Rev 3 UM1816 39.3.27 39.3.28 39.3.29 39.3.30 HAL SPI Generic Driver HAL_SPI_TxRxHalfCpltCallback Function Name void HAL_SPI_TxRxHalfCpltCallback (SPI_HandleTypeDef * hspi) Function Description Tx and Rx Transfer completed callbacks. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values None HAL_SPI_ErrorCallback Function Name void HAL_SPI_ErrorCallback (SPI_HandleTypeDef * hspi) Function Description SPI error callbacks. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values None HAL_SPI_GetState Function Name HAL_SPI_StateTypeDef HAL_SPI_GetState (SPI_HandleTypeDef * hspi) Function Description Return the SPI state. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values HAL state HAL_SPI_GetError Function Name uint32_t HAL_SPI_GetError (SPI_HandleTypeDef * hspi) Function Description Return the SPI error code. Parameters hspi: pointer to a SPI_HandleTypeDef structure that contains the configuration information for SPI module. Return values SPI Error Code 39.4 SPI Firmware driver defines 39.4.1 SPI SPI BaudRate Prescaler SPI_BAUDRATEPRESCALER_2 SPI_BAUDRATEPRESCALER_4 SPI_BAUDRATEPRESCALER_8 SPI_BAUDRATEPRESCALER_16 SPI_BAUDRATEPRESCALER_32 SPI_BAUDRATEPRESCALER_64 DOCID026682 Rev 3 525/654 HAL SPI Generic Driver SPI_BAUDRATEPRESCALER_128 SPI_BAUDRATEPRESCALER_256 IS_SPI_BAUDRATE_PRESCALER SPI Clock Phase SPI_PHASE_1EDGE SPI_PHASE_2EDGE IS_SPI_CPHA SPI Clock Polarity SPI_POLARITY_LOW SPI_POLARITY_HIGH IS_SPI_CPOL SPI CRC Calculation SPI_CRCCALCULATION_DISABLE SPI_CRCCALCULATION_ENABLE IS_SPI_CRC_CALCULATION IS_SPI_CRC_POLYNOMIAL SPI data size SPI_DATASIZE_8BIT SPI_DATASIZE_16BIT IS_SPI_DATASIZE SPI Direction mode SPI_DIRECTION_2LINES SPI_DIRECTION_2LINES_RXONLY SPI_DIRECTION_1LINE IS_SPI_DIRECTION_MODE IS_SPI_DIRECTION_2LINES_OR_1LINE IS_SPI_DIRECTION_2LINES SPI Error Codes HAL_SPI_ERROR_NONE No error HAL_SPI_ERROR_MODF MODF error HAL_SPI_ERROR_CRC CRC error HAL_SPI_ERROR_OVR OVR error HAL_SPI_ERROR_FRE FRE error HAL_SPI_ERROR_DMA DMA transfer error HAL_SPI_ERROR_FLAG Flag: RXNE,TXE, BSY SPI Exported Macros 526/654 DOCID026682 Rev 3 UM1816 UM1816 HAL SPI Generic Driver __HAL_SPI_RESET_HANDLE_STATE Description: Reset SPI handle state. Parameters: __HANDLE__: specifies the SPI handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. Return value: None Description: __HAL_SPI_ENABLE_IT Enable or disable the specified SPI interrupts. Parameters: __HANDLE__: specifies the SPI handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. __INTERRUPT__: specifies the interrupt source to enable or disable. This parameter can be one of the following values: SPI_IT_TXE: Tx buffer empty interrupt enable SPI_IT_RXNE: RX buffer not empty interrupt enable SPI_IT_ERR: Error interrupt enable Return value: None __HAL_SPI_DISABLE_IT __HAL_SPI_GET_IT_SOURCE Description: Check if the specified SPI interrupt source is enabled or disabled. Parameters: __HANDLE__: specifies the SPI handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. __INTERRUPT__: specifies the SPI interrupt source to check. This parameter can be one of the following values: SPI_IT_TXE: Tx buffer empty interrupt enable SPI_IT_RXNE: RX buffer not empty interrupt enable SPI_IT_ERR: Error interrupt enable Return value: __HAL_SPI_GET_FLAG The: new state of __IT__ (TRUE or FALSE). Description: DOCID026682 Rev 3 527/654 HAL SPI Generic Driver UM1816 Check whether the specified SPI flag is set or not. Parameters: __HANDLE__: specifies the SPI handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. __FLAG__: specifies the flag to check. This parameter can be one of the following values: SPI_FLAG_RXNE: Receive buffer not empty flag SPI_FLAG_TXE: Transmit buffer empty flag SPI_FLAG_CRCERR: CRC error flag SPI_FLAG_MODF: Mode fault flag SPI_FLAG_OVR: Overrun flag SPI_FLAG_BSY: Busy flag SPI_FLAG_FRE: Frame format error flag Return value: __HAL_SPI_CLEAR_CRCERRFLAG The: new state of __FLAG__ (TRUE or FALSE). Description: Clear the SPI CRCERR pending flag. Parameters: __HANDLE__: specifies the SPI handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. Return value: __HAL_SPI_CLEAR_MODFFLAG None Description: Clear the SPI MODF pending flag. Parameters: __HANDLE__: specifies the SPI handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. Return value: __HAL_SPI_CLEAR_OVRFLAG None Description: Clear the SPI OVR pending flag. Parameters: 528/654 __HANDLE__: specifies the SPI handle. This parameter can be SPI where x: 1, 2, or DOCID026682 Rev 3 UM1816 HAL SPI Generic Driver 3 to select the SPI peripheral. Return value: __HAL_SPI_CLEAR_FREFLAG None Description: Clear the SPI FRE pending flag. Parameters: __HANDLE__: specifies the SPI handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. Return value: None Description: __HAL_SPI_ENABLE Enables the SPI. Parameters: __HANDLE__: specifies the SPI Handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. Return value: None Description: __HAL_SPI_DISABLE Disables the SPI. Parameters: __HANDLE__: specifies the SPI Handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. Return value: None SPI Flag definition SPI_FLAG_RXNE SPI_FLAG_TXE SPI_FLAG_CRCERR SPI_FLAG_MODF SPI_FLAG_OVR SPI_FLAG_BSY SPI_FLAG_FRE SPI Interrupt configuration definition SPI_IT_TXE SPI_IT_RXNE DOCID026682 Rev 3 529/654 HAL SPI Generic Driver SPI_IT_ERR UM1816 SPI mode SPI_MODE_SLAVE SPI_MODE_MASTER IS_SPI_MODE SPI MSB LSB transmission SPI_FIRSTBIT_MSB SPI_FIRSTBIT_LSB IS_SPI_FIRST_BIT SPI Private Constants SPI_TIMEOUT_VALUE SPI Private Macros SPI_1LINE_TX Description: Sets the SPI transmit-only mode. Parameters: __HANDLE__: specifies the SPI Handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. Return value: SPI_1LINE_RX None Description: Sets the SPI receive-only mode. Parameters: __HANDLE__: specifies the SPI Handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. Return value: SPI_RESET_CRC None Description: Resets the CRC calculation of the SPI. Parameters: __HANDLE__: specifies the SPI Handle. This parameter can be SPI where x: 1, 2, or 3 to select the SPI peripheral. Return value: None SPI Slave Select management SPI_NSS_SOFT SPI_NSS_HARD_INPUT SPI_NSS_HARD_OUTPUT 530/654 DOCID026682 Rev 3 UM1816 HAL SPI Generic Driver IS_SPI_NSS SPI TI mode SPI_TIMODE_DISABLE SPI_TIMODE_ENABLE IS_SPI_TIMODE DOCID026682 Rev 3 531/654 HAL SRAM Generic Driver UM1816 40 HAL SRAM Generic Driver 40.1 HAL SRAM Generic Driver 40.2 SRAM Firmware driver registers structures 40.2.1 SRAM_HandleTypeDef Data Fields FSMC_NORSRAM_TypeDef * Instance FSMC_NORSRAM_EXTENDED_TypeDef * Extended FSMC_NORSRAM_InitTypeDef Init HAL_LockTypeDef Lock __IO HAL_SRAM_StateTypeDef State DMA_HandleTypeDef * hdma Field Documentation FSMC_NORSRAM_TypeDef* SRAM_HandleTypeDef::Instance Register base address FSMC_NORSRAM_EXTENDED_TypeDef* SRAM_HandleTypeDef::Extended Extended mode register base address FSMC_NORSRAM_InitTypeDef SRAM_HandleTypeDef::Init SRAM device control configuration parameters HAL_LockTypeDef SRAM_HandleTypeDef::Lock SRAM locking object __IO HAL_SRAM_StateTypeDef SRAM_HandleTypeDef::State SRAM device access state DMA_HandleTypeDef* SRAM_HandleTypeDef::hdma Pointer DMA handler 40.3 SRAM Firmware driver API description 40.3.1 How to use this driver This driver is a generic layered driver which contains a set of APIs used to control SRAM memories. It uses the FSMC layer functions to interface with SRAM devices. The following sequence should be followed to configure the FSMC to interface with SRAM/PSRAM memories: 1. 532/654 Declare a SRAM_HandleTypeDef handle structure, for example: SRAM_HandleTypeDef hsram; and: Fill the SRAM_HandleTypeDef handle "Init" field with the allowed values of the structure member. Fill the SRAM_HandleTypeDef handle "Instance" field with a predefined base register instance for NOR or SRAM device Fill the SRAM_HandleTypeDef handle "Extended" field with a predefined base register instance for NOR or SRAM extended mode DOCID026682 Rev 3 UM1816 2. 3. 4. 5. 6. 40.3.2 HAL SRAM Generic Driver Declare two FSMC_NORSRAM_TimingTypeDef structures, for both normal and extended mode timings; for example: FSMC_NORSRAM_TimingTypeDef Timing and FSMC_NORSRAM_TimingTypeDef ExTiming; and fill its fields with the allowed values of the structure member. Initialize the SRAM Controller by calling the function HAL_SRAM_Init(). This function performs the following sequence: a. MSP hardware layer configuration using the function HAL_SRAM_MspInit() b. Control register configuration using the FSMC NORSRAM interface function FSMC_NORSRAM_Init() c. Timing register configuration using the FSMC NORSRAM interface function FSMC_NORSRAM_Timing_Init() d. Extended mode Timing register configuration using the FSMC NORSRAM interface function FSMC_NORSRAM_Extended_Timing_Init() e. Enable the SRAM device using the macro __FSMC_NORSRAM_ENABLE() At this stage you can perform read/write accesses from/to the memory connected to the NOR/SRAM Bank. You can perform either polling or DMA transfer using the following APIs: HAL_SRAM_Read()/HAL_SRAM_Write() for polling read/write access HAL_SRAM_Read_DMA()/HAL_SRAM_Write_DMA() for DMA read/write transfer You can also control the SRAM device by calling the control APIs HAL_SRAM_WriteOperation_Enable()/ HAL_SRAM_WriteOperation_Disable() to respectively enable/disable the SRAM write operation You can continuously monitor the SRAM device HAL state by calling the function HAL_SRAM_GetState() SRAM Initialization and de_initialization functions This section provides functions allowing to initialize/de-initialize the SRAM memory This section contains the following APIs: 40.3.3 HAL_SRAM_Init() HAL_SRAM_DeInit() HAL_SRAM_MspInit() HAL_SRAM_MspDeInit() HAL_SRAM_DMA_XferCpltCallback() HAL_SRAM_DMA_XferErrorCallback() SRAM Input and Output functions This section provides functions allowing to use and control the SRAM memory This section contains the following APIs: 40.3.4 HAL_SRAM_Read_8b() HAL_SRAM_Write_8b() HAL_SRAM_Read_16b() HAL_SRAM_Write_16b() HAL_SRAM_Read_32b() HAL_SRAM_Write_32b() HAL_SRAM_Read_DMA() HAL_SRAM_Write_DMA() SRAM Control functions This subsection provides a set of functions allowing to control dynamically the SRAM interface. DOCID026682 Rev 3 533/654 HAL SRAM Generic Driver This section contains the following APIs: 40.3.5 UM1816 HAL_SRAM_WriteOperation_Enable() HAL_SRAM_WriteOperation_Disable() SRAM State functions This subsection permits to get in run-time the status of the SRAM controller and the data flow. This section contains the following APIs: 40.3.6 HAL_SRAM_GetState() HAL_SRAM_Init Function Name HAL_StatusTypeDef HAL_SRAM_Init (SRAM_HandleTypeDef * hsram, FSMC_NORSRAM_TimingTypeDef * Timing, FSMC_NORSRAM_TimingTypeDef * ExtTiming) Function Description Performs the SRAM device initialization sequence. Parameters Return values 40.3.7 40.3.8 40.3.9 534/654 hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. Timing: Pointer to SRAM control timing structure ExtTiming: Pointer to SRAM extended mode timing structure HAL status HAL_SRAM_DeInit Function Name HAL_StatusTypeDef HAL_SRAM_DeInit (SRAM_HandleTypeDef * hsram) Function Description Performs the SRAM device De-initialization sequence. Parameters hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. Return values HAL status HAL_SRAM_MspInit Function Name void HAL_SRAM_MspInit (SRAM_HandleTypeDef * hsram) Function Description SRAM MSP Init. Parameters hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. Return values None HAL_SRAM_MspDeInit Function Name void HAL_SRAM_MspDeInit (SRAM_HandleTypeDef * hsram) Function Description SRAM MSP DeInit. Parameters hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. Return values None DOCID026682 Rev 3 UM1816 40.3.10 40.3.11 40.3.12 HAL SRAM Generic Driver HAL_SRAM_DMA_XferCpltCallback Function Name void HAL_SRAM_DMA_XferCpltCallback (DMA_HandleTypeDef * hdma) Function Description DMA transfer complete callback. Parameters hdma: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. Return values None HAL_SRAM_DMA_XferErrorCallback Function Name void HAL_SRAM_DMA_XferErrorCallback (DMA_HandleTypeDef * hdma) Function Description DMA transfer complete error callback. Parameters hdma: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. Return values None HAL_SRAM_Read_8b Function Name HAL_StatusTypeDef HAL_SRAM_Read_8b (SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint8_t * pDstBuffer, uint32_t BufferSize) Function Description Reads 8-bit buffer from SRAM memory. Parameters Return values 40.3.13 HAL status HAL_SRAM_Write_8b Function Name HAL_StatusTypeDef HAL_SRAM_Write_8b (SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint8_t * pSrcBuffer, uint32_t BufferSize) Function Description Writes 8-bit buffer to SRAM memory. Parameters Return values 40.3.14 hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. pAddress: Pointer to read start address pDstBuffer: Pointer to destination buffer BufferSize: Size of the buffer to read from memory hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. pAddress: Pointer to write start address pSrcBuffer: Pointer to source buffer to write BufferSize: Size of the buffer to write to memory HAL status HAL_SRAM_Read_16b Function Name HAL_StatusTypeDef HAL_SRAM_Read_16b (SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint16_t DOCID026682 Rev 3 535/654 HAL SRAM Generic Driver UM1816 * pDstBuffer, uint32_t BufferSize) Function Description Reads 16-bit buffer from SRAM memory. Parameters Return values 40.3.15 HAL_StatusTypeDef HAL_SRAM_Write_16b (SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint16_t * pSrcBuffer, uint32_t BufferSize) Function Description Writes 16-bit buffer to SRAM memory. Parameters hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. pAddress: Pointer to write start address pSrcBuffer: Pointer to source buffer to write BufferSize: Size of the buffer to write to memory HAL status HAL_SRAM_Read_32b Function Name HAL_StatusTypeDef HAL_SRAM_Read_32b (SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint32_t * pDstBuffer, uint32_t BufferSize) Function Description Reads 32-bit buffer from SRAM memory. Parameters hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. pAddress: Pointer to read start address pDstBuffer: Pointer to destination buffer BufferSize: Size of the buffer to read from memory HAL status HAL_SRAM_Write_32b Function Name HAL_StatusTypeDef HAL_SRAM_Write_32b (SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint32_t * pSrcBuffer, uint32_t BufferSize) Function Description Writes 32-bit buffer to SRAM memory. Parameters Return values 536/654 HAL status Function Name Return values 40.3.17 HAL_SRAM_Write_16b Return values 40.3.16 hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. pAddress: Pointer to read start address pDstBuffer: Pointer to destination buffer BufferSize: Size of the buffer to read from memory hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. pAddress: Pointer to write start address pSrcBuffer: Pointer to source buffer to write BufferSize: Size of the buffer to write to memory HAL status DOCID026682 Rev 3 UM1816 40.3.18 HAL SRAM Generic Driver HAL_SRAM_Read_DMA Function Name HAL_StatusTypeDef HAL_SRAM_Read_DMA (SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint32_t * pDstBuffer, uint32_t BufferSize) Function Description Reads a Words data from the SRAM memory using DMA transfer. Parameters Return values 40.3.19 40.3.21 40.3.22 HAL status HAL_SRAM_Write_DMA Function Name HAL_StatusTypeDef HAL_SRAM_Write_DMA (SRAM_HandleTypeDef * hsram, uint32_t * pAddress, uint32_t * pSrcBuffer, uint32_t BufferSize) Function Description Writes a Words data buffer to SRAM memory using DMA transfer. Parameters Return values 40.3.20 hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. pAddress: Pointer to read start address pDstBuffer: Pointer to destination buffer BufferSize: Size of the buffer to read from memory hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. pAddress: Pointer to write start address pSrcBuffer: Pointer to source buffer to write BufferSize: Size of the buffer to write to memory HAL status HAL_SRAM_WriteOperation_Enable Function Name HAL_StatusTypeDef HAL_SRAM_WriteOperation_Enable (SRAM_HandleTypeDef * hsram) Function Description Enables dynamically SRAM write operation. Parameters hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. Return values HAL status HAL_SRAM_WriteOperation_Disable Function Name HAL_StatusTypeDef HAL_SRAM_WriteOperation_Disable (SRAM_HandleTypeDef * hsram) Function Description Disables dynamically SRAM write operation. Parameters hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. Return values HAL status HAL_SRAM_GetState Function Name HAL_SRAM_StateTypeDef HAL_SRAM_GetState (SRAM_HandleTypeDef * hsram) DOCID026682 Rev 3 537/654 HAL SRAM Generic Driver Function Description UM1816 Returns the SRAM controller state. Parameters hsram: pointer to a SRAM_HandleTypeDef structure that contains the configuration information for SRAM module. Return values HAL state 40.4 SRAM Firmware driver defines 40.4.1 SRAM SRAM Exported Macros __HAL_SRAM_RESET_HANDLE_STATE Description: Reset SRAM handle state. Parameters: __HANDLE__: SRAM handle Return value: 538/654 None DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver 41 HAL TIM Generic Driver 41.1 HAL TIM Generic Driver 41.2 TIM Firmware driver registers structures 41.2.1 TIM_Base_InitTypeDef Data Fields uint32_t Prescaler uint32_t CounterMode uint32_t Period uint32_t ClockDivision Field Documentation 41.2.2 uint32_t TIM_Base_InitTypeDef::Prescaler Specifies the prescaler value used to divide the TIM clock. This parameter can be a number between Min_Data = 0x0000 and Max_Data = 0xFFFF uint32_t TIM_Base_InitTypeDef::CounterMode Specifies the counter mode. This parameter can be a value of TIM_Counter_Mode uint32_t TIM_Base_InitTypeDef::Period Specifies the period value to be loaded into the active Auto-Reload Register at the next update event. This parameter can be a number between Min_Data = 0x0000 and Max_Data = 0xFFFF. uint32_t TIM_Base_InitTypeDef::ClockDivision Specifies the clock division. This parameter can be a value of TIM_ClockDivision TIM_OC_InitTypeDef Data Fields uint32_t OCMode uint32_t Pulse uint32_t OCPolarity uint32_t OCFastMode uint32_t OCIdleState Field Documentation uint32_t TIM_OC_InitTypeDef::OCMode Specifies the TIM mode. This parameter can be a value of TIM_Output_Compare_and_PWM_modes uint32_t TIM_OC_InitTypeDef::Pulse Specifies the pulse value to be loaded into the Capture Compare Register. This parameter can be a number between Min_Data = 0x0000 and Max_Data = 0xFFFF DOCID026682 Rev 3 539/654 HAL TIM Generic Driver 41.2.3 UM1816 uint32_t TIM_OC_InitTypeDef::OCPolarity Specifies the output polarity. This parameter can be a value of TIM_Output_Compare_Polarity uint32_t TIM_OC_InitTypeDef::OCFastMode Specifies the Fast mode state. This parameter can be a value of TIM_Output_Fast_State Note:This parameter is valid only in PWM1 and PWM2 mode. uint32_t TIM_OC_InitTypeDef::OCIdleState Specifies the TIM Output Compare pin state during Idle state. This parameter can be a value of TIM_Output_Compare_Idle_State. TIM_OnePulse_InitTypeDef Data Fields uint32_t OCMode uint32_t Pulse uint32_t OCPolarity uint32_t OCIdleState uint32_t ICPolarity uint32_t ICSelection uint32_t ICFilter Field Documentation 41.2.4 uint32_t TIM_OnePulse_InitTypeDef::OCMode Specifies the TIM mode. This parameter can be a value of TIM_Output_Compare_and_PWM_modes uint32_t TIM_OnePulse_InitTypeDef::Pulse Specifies the pulse value to be loaded into the Capture Compare Register. This parameter can be a number between Min_Data = 0x0000 and Max_Data = 0xFFFF uint32_t TIM_OnePulse_InitTypeDef::OCPolarity Specifies the output polarity. This parameter can be a value of TIM_Output_Compare_Polarity uint32_t TIM_OnePulse_InitTypeDef::OCIdleState Specifies the TIM Output Compare pin state during Idle state. This parameter can be a value of TIM_Output_Compare_Idle_State. uint32_t TIM_OnePulse_InitTypeDef::ICPolarity Specifies the active edge of the input signal. This parameter can be a value of TIM_Input_Capture_Polarity uint32_t TIM_OnePulse_InitTypeDef::ICSelection Specifies the input. This parameter can be a value of TIM_Input_Capture_Selection uint32_t TIM_OnePulse_InitTypeDef::ICFilter Specifies the input capture filter. This parameter can be a number between Min_Data = 0x0 and Max_Data = 0xF TIM_IC_InitTypeDef Data Fields 540/654 DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver uint32_t ICPolarity uint32_t ICSelection uint32_t ICPrescaler uint32_t ICFilter Field Documentation 41.2.5 uint32_t TIM_IC_InitTypeDef::ICPolarity Specifies the active edge of the input signal. This parameter can be a value of TIM_Input_Capture_Polarity uint32_t TIM_IC_InitTypeDef::ICSelection Specifies the input. This parameter can be a value of TIM_Input_Capture_Selection uint32_t TIM_IC_InitTypeDef::ICPrescaler Specifies the Input Capture Prescaler. This parameter can be a value of TIM_Input_Capture_Prescaler uint32_t TIM_IC_InitTypeDef::ICFilter Specifies the input capture filter. This parameter can be a number between Min_Data = 0x0 and Max_Data = 0xF TIM_Encoder_InitTypeDef Data Fields uint32_t EncoderMode uint32_t IC1Polarity uint32_t IC1Selection uint32_t IC1Prescaler uint32_t IC1Filter uint32_t IC2Polarity uint32_t IC2Selection uint32_t IC2Prescaler uint32_t IC2Filter Field Documentation uint32_t TIM_Encoder_InitTypeDef::EncoderMode Specifies the active edge of the input signal. This parameter can be a value of TIM_Encoder_Mode uint32_t TIM_Encoder_InitTypeDef::IC1Polarity Specifies the active edge of the input signal. This parameter can be a value of TIM_Input_Capture_Polarity uint32_t TIM_Encoder_InitTypeDef::IC1Selection Specifies the input. This parameter can be a value of TIM_Input_Capture_Selection uint32_t TIM_Encoder_InitTypeDef::IC1Prescaler Specifies the Input Capture Prescaler. This parameter can be a value of TIM_Input_Capture_Prescaler uint32_t TIM_Encoder_InitTypeDef::IC1Filter Specifies the input capture filter. This parameter can be a number between Min_Data = 0x0 and Max_Data = 0xF DOCID026682 Rev 3 541/654 HAL TIM Generic Driver 41.2.6 UM1816 uint32_t TIM_Encoder_InitTypeDef::IC2Polarity Specifies the active edge of the input signal. This parameter can be a value of TIM_Input_Capture_Polarity uint32_t TIM_Encoder_InitTypeDef::IC2Selection Specifies the input. This parameter can be a value of TIM_Input_Capture_Selection uint32_t TIM_Encoder_InitTypeDef::IC2Prescaler Specifies the Input Capture Prescaler. This parameter can be a value of TIM_Input_Capture_Prescaler uint32_t TIM_Encoder_InitTypeDef::IC2Filter Specifies the input capture filter. This parameter can be a number between Min_Data = 0x0 and Max_Data = 0xF TIM_ClockConfigTypeDef Data Fields uint32_t ClockSource uint32_t ClockPolarity uint32_t ClockPrescaler uint32_t ClockFilter Field Documentation 41.2.7 uint32_t TIM_ClockConfigTypeDef::ClockSource TIM clock sources This parameter can be a value of TIM_Clock_Source uint32_t TIM_ClockConfigTypeDef::ClockPolarity TIM clock polarity This parameter can be a value of TIM_Clock_Polarity uint32_t TIM_ClockConfigTypeDef::ClockPrescaler TIM clock prescaler This parameter can be a value of TIM_Clock_Prescaler uint32_t TIM_ClockConfigTypeDef::ClockFilter TIM clock filter This parameter can be a number between Min_Data = 0x0 and Max_Data = 0xF TIM_ClearInputConfigTypeDef Data Fields uint32_t ClearInputState uint32_t ClearInputSource uint32_t ClearInputPolarity uint32_t ClearInputPrescaler uint32_t ClearInputFilter Field Documentation 542/654 uint32_t TIM_ClearInputConfigTypeDef::ClearInputState TIM clear Input state This parameter can be ENABLE or DISABLE uint32_t TIM_ClearInputConfigTypeDef::ClearInputSource TIM clear Input sources This parameter can be a value of TIM_ClearInput_Source DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver 41.2.8 uint32_t TIM_ClearInputConfigTypeDef::ClearInputPolarity TIM Clear Input polarity This parameter can be a value of TIM_ClearInput_Polarity uint32_t TIM_ClearInputConfigTypeDef::ClearInputPrescaler TIM Clear Input prescaler This parameter can be a value of TIM_ClearInput_Prescaler uint32_t TIM_ClearInputConfigTypeDef::ClearInputFilter TIM Clear Input filter This parameter can be a number between Min_Data = 0x0 and Max_Data = 0xF TIM_SlaveConfigTypeDef Data Fields uint32_t SlaveMode uint32_t InputTrigger uint32_t TriggerPolarity uint32_t TriggerPrescaler uint32_t TriggerFilter Field Documentation 41.2.9 uint32_t TIM_SlaveConfigTypeDef::SlaveMode Slave mode selection This parameter can be a value of TIM_Slave_Mode uint32_t TIM_SlaveConfigTypeDef::InputTrigger Input Trigger source This parameter can be a value of TIM_Trigger_Selection uint32_t TIM_SlaveConfigTypeDef::TriggerPolarity Input Trigger polarity This parameter can be a value of TIM_Trigger_Polarity uint32_t TIM_SlaveConfigTypeDef::TriggerPrescaler Input trigger prescaler This parameter can be a value of TIM_Trigger_Prescaler uint32_t TIM_SlaveConfigTypeDef::TriggerFilter Input trigger filter This parameter can be a number between Min_Data = 0x0 and Max_Data = 0xF TIM_HandleTypeDef Data Fields TIM_TypeDef * Instance TIM_Base_InitTypeDef Init HAL_TIM_ActiveChannel Channel DMA_HandleTypeDef * hdma HAL_LockTypeDef Lock __IO HAL_TIM_StateTypeDef State Field Documentation TIM_TypeDef* TIM_HandleTypeDef::Instance Register base address DOCID026682 Rev 3 543/654 HAL TIM Generic Driver UM1816 TIM_Base_InitTypeDef TIM_HandleTypeDef::Init TIM Time Base required parameters HAL_TIM_ActiveChannel TIM_HandleTypeDef::Channel Active channel DMA_HandleTypeDef* TIM_HandleTypeDef::hdma[7] DMA Handlers array This array is accessed by a TIM_DMA_Handle_index HAL_LockTypeDef TIM_HandleTypeDef::Lock Locking object __IO HAL_TIM_StateTypeDef TIM_HandleTypeDef::State TIM operation state 41.3 TIM Firmware driver API description 41.3.1 TIMER Generic features The Timer features include: 1. 2. 3. 4. 5. 41.3.2 How to use this driver 1. 2. 3. 4. 544/654 16-bit up, down, up/down auto-reload counter. 16-bit programmable prescaler allowing dividing (also on the fly) the counter clock frequency either by any factor between 1 and 65536. Up to 4 independent channels for: Input Capture Output Compare PWM generation (Edge and Center-aligned Mode) One-pulse mode output Synchronization circuit to control the timer with external signals and to interconnect several timers together. Supports incremental (quadrature) encoder Initialize the TIM low level resources by implementing the following functions depending from feature used : Time Base : HAL_TIM_Base_MspInit() Input Capture : HAL_TIM_IC_MspInit() Output Compare : HAL_TIM_OC_MspInit() PWM generation : HAL_TIM_PWM_MspInit() One-pulse mode output : HAL_TIM_OnePulse_MspInit() Encoder mode output : HAL_TIM_Encoder_MspInit() Initialize the TIM low level resources : a. Enable the TIM interface clock using __HAL_RCC_TIMx_CLK_ENABLE(); b. TIM pins configuration Enable the clock for the TIM GPIOs using the following function: __HAL_RCC_GPIOx_CLK_ENABLE(); Configure these TIM pins in Alternate function mode using HAL_GPIO_Init(); The external Clock can be configured, if needed (the default clock is the internal clock from the APBx), using the following function: HAL_TIM_ConfigClockSource, the clock configuration should be done before any start function. Configure the TIM in the desired functioning mode using one of the Initialization function of this driver: HAL_TIM_Base_Init: to use the Timer to generate a simple time base DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver 5. 6. 41.3.3 HAL_TIM_OC_Init and HAL_TIM_OC_ConfigChannel: to use the Timer to generate an Output Compare signal. HAL_TIM_PWM_Init and HAL_TIM_PWM_ConfigChannel: to use the Timer to generate a PWM signal. HAL_TIM_IC_Init and HAL_TIM_IC_ConfigChannel: to use the Timer to measure an external signal. HAL_TIM_OnePulse_Init and HAL_TIM_OnePulse_ConfigChannel: to use the Timer in One Pulse Mode. HAL_TIM_Encoder_Init: to use the Timer Encoder Interface. Activate the TIM peripheral using one of the start functions depending from the feature used: Time Base : HAL_TIM_Base_Start(), HAL_TIM_Base_Start_DMA(), HAL_TIM_Base_Start_IT() Input Capture : HAL_TIM_IC_Start(), HAL_TIM_IC_Start_DMA(), HAL_TIM_IC_Start_IT() Output Compare : HAL_TIM_OC_Start(), HAL_TIM_OC_Start_DMA(), HAL_TIM_OC_Start_IT() PWM generation : HAL_TIM_PWM_Start(), HAL_TIM_PWM_Start_DMA(), HAL_TIM_PWM_Start_IT() One-pulse mode output : HAL_TIM_OnePulse_Start(), HAL_TIM_OnePulse_Start_IT() Encoder mode output : HAL_TIM_Encoder_Start(), HAL_TIM_Encoder_Start_DMA(), HAL_TIM_Encoder_Start_IT(). The DMA Burst is managed with the two following functions: HAL_TIM_DMABurst_WriteStart() HAL_TIM_DMABurst_ReadStart() Time Base functions This section provides functions allowing to: Initialize and configure the TIM base. De-initialize the TIM base. Start the Time Base. Stop the Time Base. Start the Time Base and enable interrupt. Stop the Time Base and disable interrupt. Start the Time Base and enable DMA transfer. Stop the Time Base and disable DMA transfer. This section contains the following APIs: 41.3.4 HAL_TIM_Base_Init() HAL_TIM_Base_DeInit() HAL_TIM_Base_MspInit() HAL_TIM_Base_MspDeInit() HAL_TIM_Base_Start() HAL_TIM_Base_Stop() HAL_TIM_Base_Start_IT() HAL_TIM_Base_Stop_IT() HAL_TIM_Base_Start_DMA() HAL_TIM_Base_Stop_DMA() Time Output Compare functions This section provides functions allowing to: Initialize and configure the TIM Output Compare. DOCID026682 Rev 3 545/654 HAL TIM Generic Driver UM1816 De-initialize the TIM Output Compare. Start the Time Output Compare. Stop the Time Output Compare. Start the Time Output Compare and enable interrupt. Stop the Time Output Compare and disable interrupt. Start the Time Output Compare and enable DMA transfer. Stop the Time Output Compare and disable DMA transfer. This section contains the following APIs: 41.3.5 HAL_TIM_OC_Init() HAL_TIM_OC_DeInit() HAL_TIM_OC_MspInit() HAL_TIM_OC_MspDeInit() HAL_TIM_OC_Start() HAL_TIM_OC_Stop() HAL_TIM_OC_Start_IT() HAL_TIM_OC_Stop_IT() HAL_TIM_OC_Start_DMA() HAL_TIM_OC_Stop_DMA() Time PWM functions This section provides functions allowing to: Initialize and configure the TIM PWM. De-initialize the TIM PWM. Start the Time PWM. Stop the Time PWM. Start the Time PWM and enable interrupt. Stop the Time PWM and disable interrupt. Start the Time PWM and enable DMA transfer. Stop the Time PWM and disable DMA transfer. This section contains the following APIs: 41.3.6 HAL_TIM_PWM_Init() HAL_TIM_PWM_DeInit() HAL_TIM_PWM_MspInit() HAL_TIM_PWM_MspDeInit() HAL_TIM_PWM_Start() HAL_TIM_PWM_Stop() HAL_TIM_PWM_Start_IT() HAL_TIM_PWM_Stop_IT() HAL_TIM_PWM_Start_DMA() HAL_TIM_PWM_Stop_DMA() Time Input Capture functions This section provides functions allowing to: 546/654 Initialize and configure the TIM Input Capture. De-initialize the TIM Input Capture. Start the Time Input Capture. Stop the Time Input Capture. Start the Time Input Capture and enable interrupt. Stop the Time Input Capture and disable interrupt. DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver Start the Time Input Capture and enable DMA transfer. Stop the Time Input Capture and disable DMA transfer. This section contains the following APIs: 41.3.7 HAL_TIM_IC_Init() HAL_TIM_IC_DeInit() HAL_TIM_IC_MspInit() HAL_TIM_IC_MspDeInit() HAL_TIM_IC_Start() HAL_TIM_IC_Stop() HAL_TIM_IC_Start_IT() HAL_TIM_IC_Stop_IT() HAL_TIM_IC_Start_DMA() HAL_TIM_IC_Stop_DMA() Time One Pulse functions This section provides functions allowing to: Initialize and configure the TIM One Pulse. De-initialize the TIM One Pulse. Start the Time One Pulse. Stop the Time One Pulse. Start the Time One Pulse and enable interrupt. Stop the Time One Pulse and disable interrupt. Start the Time One Pulse and enable DMA transfer. Stop the Time One Pulse and disable DMA transfer. This section contains the following APIs: 41.3.8 HAL_TIM_OnePulse_Init() HAL_TIM_OnePulse_DeInit() HAL_TIM_OnePulse_MspInit() HAL_TIM_OnePulse_MspDeInit() HAL_TIM_OnePulse_Start() HAL_TIM_OnePulse_Stop() HAL_TIM_OnePulse_Start_IT() HAL_TIM_OnePulse_Stop_IT() Time Encoder functions This section provides functions allowing to: Initialize and configure the TIM Encoder. De-initialize the TIM Encoder. Start the Time Encoder. Stop the Time Encoder. Start the Time Encoder and enable interrupt. Stop the Time Encoder and disable interrupt. Start the Time Encoder and enable DMA transfer. Stop the Time Encoder and disable DMA transfer. This section contains the following APIs: HAL_TIM_Encoder_Init() HAL_TIM_Encoder_DeInit() HAL_TIM_Encoder_MspInit() DOCID026682 Rev 3 547/654 HAL TIM Generic Driver 41.3.9 UM1816 HAL_TIM_Encoder_MspDeInit() HAL_TIM_Encoder_Start() HAL_TIM_Encoder_Stop() HAL_TIM_Encoder_Start_IT() HAL_TIM_Encoder_Stop_IT() HAL_TIM_Encoder_Start_DMA() HAL_TIM_Encoder_Stop_DMA() IRQ handler management This section provides Timer IRQ handler function. This section contains the following APIs: 41.3.10 HAL_TIM_IRQHandler() Peripheral Control functions This section provides functions allowing to: Configure The Input Output channels for OC, PWM, IC or One Pulse mode. Configure External Clock source. Configure Complementary channels, break features and dead time. Configure Master and the Slave synchronization. Configure the DMA Burst Mode. This section contains the following APIs: 41.3.11 HAL_TIM_OC_ConfigChannel() HAL_TIM_IC_ConfigChannel() HAL_TIM_PWM_ConfigChannel() HAL_TIM_OnePulse_ConfigChannel() HAL_TIM_DMABurst_WriteStart() HAL_TIM_DMABurst_WriteStop() HAL_TIM_DMABurst_ReadStart() HAL_TIM_DMABurst_ReadStop() HAL_TIM_GenerateEvent() HAL_TIM_ConfigOCrefClear() HAL_TIM_ConfigClockSource() HAL_TIM_ConfigTI1Input() HAL_TIM_SlaveConfigSynchronization() HAL_TIM_SlaveConfigSynchronization_IT() HAL_TIM_ReadCapturedValue() TIM Callbacks functions This section provides TIM callback functions: Timer Period elapsed callback Timer Output Compare callback Timer Input capture callback Timer Trigger callback Timer Error callback This section contains the following APIs: 548/654 HAL_TIM_PeriodElapsedCallback() HAL_TIM_OC_DelayElapsedCallback() DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver 41.3.12 HAL_TIM_IC_CaptureCallback() HAL_TIM_PWM_PulseFinishedCallback() HAL_TIM_TriggerCallback() HAL_TIM_ErrorCallback() 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: 41.3.13 41.3.14 41.3.15 41.3.16 HAL_TIM_Base_GetState() HAL_TIM_OC_GetState() HAL_TIM_PWM_GetState() HAL_TIM_IC_GetState() HAL_TIM_OnePulse_GetState() HAL_TIM_Encoder_GetState() TIM_DMAError() TIM_DMADelayPulseCplt() TIM_DMACaptureCplt() HAL_TIM_Base_Init Function Name HAL_StatusTypeDef HAL_TIM_Base_Init (TIM_HandleTypeDef * htim) Function Description Initializes the TIM Time base Unit according to the specified parameters in the TIM_HandleTypeDef and create the associated handle. Parameters htim: TIM Base handle Return values HAL status HAL_TIM_Base_DeInit Function Name HAL_StatusTypeDef HAL_TIM_Base_DeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes the TIM Base peripheral. Parameters htim: TIM Base handle Return values HAL status HAL_TIM_Base_MspInit Function Name void HAL_TIM_Base_MspInit (TIM_HandleTypeDef * htim) Function Description Initializes the TIM Base MSP. Parameters htim: TIM handle Return values None HAL_TIM_Base_MspDeInit Function Name void HAL_TIM_Base_MspDeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes TIM Base MSP. DOCID026682 Rev 3 549/654 HAL TIM Generic Driver Parameters Return values 41.3.17 41.3.18 41.3.19 41.3.20 41.3.21 550/654 UM1816 htim: TIM handle None HAL_TIM_Base_Start Function Name HAL_StatusTypeDef HAL_TIM_Base_Start (TIM_HandleTypeDef * htim) Function Description Starts the TIM Base generation. Parameters htim: : TIM handle Return values HAL status HAL_TIM_Base_Stop Function Name HAL_StatusTypeDef HAL_TIM_Base_Stop (TIM_HandleTypeDef * htim) Function Description Stops the TIM Base generation. Parameters htim: : TIM handle Return values HAL status HAL_TIM_Base_Start_IT Function Name HAL_StatusTypeDef HAL_TIM_Base_Start_IT (TIM_HandleTypeDef * htim) Function Description Starts the TIM Base generation in interrupt mode. Parameters htim: : TIM handle Return values HAL status HAL_TIM_Base_Stop_IT Function Name HAL_StatusTypeDef HAL_TIM_Base_Stop_IT (TIM_HandleTypeDef * htim) Function Description Stops the TIM Base generation in interrupt mode. Parameters htim: : TIM handle Return values HAL status HAL_TIM_Base_Start_DMA Function Name HAL_StatusTypeDef HAL_TIM_Base_Start_DMA (TIM_HandleTypeDef * htim, uint32_t * pData, uint16_t Length) Function Description Starts the TIM Base generation in DMA mode. Parameters htim: : TIM handle pData: The source Buffer address. Length: The length of data to be transferred from memory to peripheral. Return values HAL status DOCID026682 Rev 3 UM1816 41.3.22 41.3.23 41.3.24 41.3.25 41.3.26 41.3.27 HAL TIM Generic Driver HAL_TIM_Base_Stop_DMA Function Name HAL_StatusTypeDef HAL_TIM_Base_Stop_DMA (TIM_HandleTypeDef * htim) Function Description Stops the TIM Base generation in DMA mode. Parameters htim: : TIM handle Return values HAL status HAL_TIM_OC_Init Function Name HAL_StatusTypeDef HAL_TIM_OC_Init (TIM_HandleTypeDef * htim) Function Description Initializes the TIM Output Compare according to the specified parameters in the TIM_HandleTypeDef and create the associated handle. Parameters htim: TIM Output Compare handle Return values HAL status HAL_TIM_OC_DeInit Function Name HAL_StatusTypeDef HAL_TIM_OC_DeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes the TIM peripheral. Parameters htim: TIM Output Compare handle Return values HAL status HAL_TIM_OC_MspInit Function Name void HAL_TIM_OC_MspInit (TIM_HandleTypeDef * htim) Function Description Initializes the TIM Output Compare MSP. Parameters htim: TIM handle Return values None HAL_TIM_OC_MspDeInit Function Name void HAL_TIM_OC_MspDeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes TIM Output Compare MSP. Parameters htim: TIM handle Return values None HAL_TIM_OC_Start Function Name HAL_StatusTypeDef HAL_TIM_OC_Start (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Starts the TIM Output Compare signal generation. DOCID026682 Rev 3 551/654 HAL TIM Generic Driver Parameters Return values 41.3.28 41.3.29 41.3.30 552/654 UM1816 htim: : TIM Output Compare handle Channel: : TIM Channel to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected HAL status HAL_TIM_OC_Stop Function Name HAL_StatusTypeDef HAL_TIM_OC_Stop (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the TIM Output Compare signal generation. Parameters htim: : TIM handle Channel: : TIM Channel to be disabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_OC_Start_IT Function Name HAL_StatusTypeDef HAL_TIM_OC_Start_IT (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Starts the TIM Output Compare signal generation in interrupt mode. Parameters htim: : TIM OC handle Channel: : TIM Channel to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_OC_Stop_IT Function Name HAL_StatusTypeDef HAL_TIM_OC_Stop_IT (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the TIM Output Compare signal generation in interrupt mode. Parameters htim: : TIM Output Compare handle Channel: : TIM Channel to be disabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status DOCID026682 Rev 3 UM1816 41.3.31 HAL TIM Generic Driver HAL_TIM_OC_Start_DMA Function Name HAL_StatusTypeDef HAL_TIM_OC_Start_DMA (TIM_HandleTypeDef * htim, uint32_t Channel, uint32_t * pData, uint16_t Length) Function Description Starts the TIM Output Compare signal generation in DMA mode. Parameters htim: : TIM Output Compare handle Channel: : TIM Channel to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected pData: The source Buffer address. Length: The length of data to be transferred from memory to TIM peripheral Return values 41.3.32 41.3.33 41.3.34 HAL status HAL_TIM_OC_Stop_DMA Function Name HAL_StatusTypeDef HAL_TIM_OC_Stop_DMA (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the TIM Output Compare signal generation in DMA mode. Parameters htim: : TIM Output Compare handle Channel: : TIM Channel to be disabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_PWM_Init Function Name HAL_StatusTypeDef HAL_TIM_PWM_Init (TIM_HandleTypeDef * htim) Function Description Initializes the TIM PWM Time Base according to the specified parameters in the TIM_HandleTypeDef and create the associated handle. Parameters htim: TIM handle Return values HAL status HAL_TIM_PWM_DeInit Function Name HAL_StatusTypeDef HAL_TIM_PWM_DeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes the TIM peripheral. Parameters htim: TIM handle Return values HAL status DOCID026682 Rev 3 553/654 HAL TIM Generic Driver 41.3.35 41.3.36 41.3.37 41.3.38 41.3.39 554/654 UM1816 HAL_TIM_PWM_MspInit Function Name void HAL_TIM_PWM_MspInit (TIM_HandleTypeDef * htim) Function Description Initializes the TIM PWM MSP. Parameters htim: TIM handle Return values None HAL_TIM_PWM_MspDeInit Function Name void HAL_TIM_PWM_MspDeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes TIM PWM MSP. Parameters htim: TIM handle Return values None HAL_TIM_PWM_Start Function Name HAL_StatusTypeDef HAL_TIM_PWM_Start (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Starts the PWM signal generation. Parameters htim: : TIM handle Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_PWM_Stop Function Name HAL_StatusTypeDef HAL_TIM_PWM_Stop (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the PWM signal generation. Parameters htim: : TIM handle Channel: : TIM Channels to be disabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_PWM_Start_IT Function Name HAL_StatusTypeDef HAL_TIM_PWM_Start_IT (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Starts the PWM signal generation in interrupt mode. Parameters htim: : TIM handle Channel: : TIM Channel to be disabled This parameter can DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values 41.3.40 41.3.41 HAL_TIM_PWM_Stop_IT Function Name HAL_StatusTypeDef HAL_TIM_PWM_Stop_IT (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the PWM signal generation in interrupt mode. Parameters htim: : TIM handle Channel: : TIM Channels to be disabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_PWM_Start_DMA Function Name HAL_StatusTypeDef HAL_TIM_PWM_Start_DMA (TIM_HandleTypeDef * htim, uint32_t Channel, uint32_t * pData, uint16_t Length) Function Description Starts the TIM PWM signal generation in DMA mode. Parameters Return values 41.3.42 HAL status htim: : TIM handle Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected pData: The source Buffer address. Length: The length of data to be transferred from memory to TIM peripheral HAL status HAL_TIM_PWM_Stop_DMA Function Name HAL_StatusTypeDef HAL_TIM_PWM_Stop_DMA (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the TIM PWM signal generation in DMA mode. Parameters htim: : TIM handle Channel: : TIM Channels to be disabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status DOCID026682 Rev 3 555/654 HAL TIM Generic Driver 41.3.43 41.3.44 41.3.45 41.3.46 41.3.47 41.3.48 556/654 UM1816 HAL_TIM_IC_Init Function Name HAL_StatusTypeDef HAL_TIM_IC_Init (TIM_HandleTypeDef * htim) Function Description Initializes the TIM Input Capture Time base according to the specified parameters in the TIM_HandleTypeDef and create the associated handle. Parameters htim: TIM Input Capture handle Return values HAL status HAL_TIM_IC_DeInit Function Name HAL_StatusTypeDef HAL_TIM_IC_DeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes the TIM peripheral. Parameters htim: TIM Input Capture handle Return values HAL status HAL_TIM_IC_MspInit Function Name void HAL_TIM_IC_MspInit (TIM_HandleTypeDef * htim) Function Description Initializes the TIM Input Capture MSP. Parameters htim: TIM handle Return values None HAL_TIM_IC_MspDeInit Function Name void HAL_TIM_IC_MspDeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes TIM Input Capture MSP. Parameters htim: TIM handle Return values None HAL_TIM_IC_Start Function Name HAL_StatusTypeDef HAL_TIM_IC_Start (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Starts the TIM Input Capture measurement. Parameters htim: : TIM Input Capture handle Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_IC_Stop DOCID026682 Rev 3 UM1816 41.3.49 41.3.50 41.3.51 Function Name HAL TIM Generic Driver HAL_StatusTypeDef HAL_TIM_IC_Stop (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the TIM Input Capture measurement. Parameters htim: : TIM handle Channel: : TIM Channels to be disabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_IC_Start_IT Function Name HAL_StatusTypeDef HAL_TIM_IC_Start_IT (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Starts the TIM Input Capture measurement in interrupt mode. Parameters htim: : TIM Input Capture handle Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_IC_Stop_IT Function Name HAL_StatusTypeDef HAL_TIM_IC_Stop_IT (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the TIM Input Capture measurement in interrupt mode. Parameters htim: : TIM handle Channel: : TIM Channels to be disabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_IC_Start_DMA Function Name HAL_StatusTypeDef HAL_TIM_IC_Start_DMA (TIM_HandleTypeDef * htim, uint32_t Channel, uint32_t * pData, uint16_t Length) Function Description Starts the TIM Input Capture measurement in DMA mode. Parameters htim: : TIM Input Capture handle Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected DOCID026682 Rev 3 557/654 HAL TIM Generic Driver Return values 41.3.52 41.3.53 41.3.54 41.3.55 558/654 UM1816 pData: The destination Buffer address. Length: The length of data to be transferred from TIM peripheral to memory. HAL status HAL_TIM_IC_Stop_DMA Function Name HAL_StatusTypeDef HAL_TIM_IC_Stop_DMA (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the TIM Input Capture measurement in DMA mode. Parameters htim: : TIM Input Capture handle Channel: : TIM Channels to be disabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_OnePulse_Init Function Name HAL_StatusTypeDef HAL_TIM_OnePulse_Init (TIM_HandleTypeDef * htim, uint32_t OnePulseMode) Function Description Initializes the TIM One Pulse Time Base according to the specified parameters in the TIM_HandleTypeDef and create the associated handle. Parameters htim: TIM OnePulse handle OnePulseMode: Select the One pulse mode. This parameter can be one of the following values: TIM_OPMODE_SINGLE: Only one pulse will be generated.TIM_OPMODE_REPETITIVE: Repetitive pulses wil be generated. Return values HAL status HAL_TIM_OnePulse_DeInit Function Name HAL_StatusTypeDef HAL_TIM_OnePulse_DeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes the TIM One Pulse. Parameters htim: TIM One Pulse handle Return values HAL status HAL_TIM_OnePulse_MspInit Function Name void HAL_TIM_OnePulse_MspInit (TIM_HandleTypeDef * htim) Function Description Initializes the TIM One Pulse MSP. Parameters htim: TIM handle Return values None DOCID026682 Rev 3 UM1816 41.3.56 41.3.57 41.3.58 41.3.59 41.3.60 HAL TIM Generic Driver HAL_TIM_OnePulse_MspDeInit Function Name void HAL_TIM_OnePulse_MspDeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes TIM One Pulse MSP. Parameters htim: TIM handle Return values None HAL_TIM_OnePulse_Start Function Name HAL_StatusTypeDef HAL_TIM_OnePulse_Start (TIM_HandleTypeDef * htim, uint32_t OutputChannel) Function Description Starts the TIM One Pulse signal generation. Parameters htim: : TIM One Pulse handle OutputChannel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selected Return values HAL status HAL_TIM_OnePulse_Stop Function Name HAL_StatusTypeDef HAL_TIM_OnePulse_Stop (TIM_HandleTypeDef * htim, uint32_t OutputChannel) Function Description Stops the TIM One Pulse signal generation. Parameters htim: : TIM One Pulse handle OutputChannel: : TIM Channels to be disable This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selected Return values HAL status HAL_TIM_OnePulse_Start_IT Function Name HAL_StatusTypeDef HAL_TIM_OnePulse_Start_IT (TIM_HandleTypeDef * htim, uint32_t OutputChannel) Function Description Starts the TIM One Pulse signal generation in interrupt mode. Parameters htim: : TIM One Pulse handle OutputChannel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selected Return values HAL status HAL_TIM_OnePulse_Stop_IT Function Name HAL_StatusTypeDef HAL_TIM_OnePulse_Stop_IT (TIM_HandleTypeDef * htim, uint32_t OutputChannel) DOCID026682 Rev 3 559/654 HAL TIM Generic Driver Function Description 41.3.61 41.3.62 41.3.63 41.3.64 41.3.65 Parameters htim: : TIM One Pulse handle OutputChannel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selected Return values HAL status HAL_TIM_Encoder_Init Function Name HAL_StatusTypeDef HAL_TIM_Encoder_Init (TIM_HandleTypeDef * htim, TIM_Encoder_InitTypeDef * sConfig) Function Description Initializes the TIM Encoder Interface and create the associated handle. Parameters htim: TIM Encoder Interface handle sConfig: TIM Encoder Interface configuration structure Return values HAL status HAL_TIM_Encoder_DeInit Function Name HAL_StatusTypeDef HAL_TIM_Encoder_DeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes the TIM Encoder interface. Parameters htim: TIM Encoder handle Return values HAL status HAL_TIM_Encoder_MspInit Function Name void HAL_TIM_Encoder_MspInit (TIM_HandleTypeDef * htim) Function Description Initializes the TIM Encoder Interface MSP. Parameters htim: TIM handle Return values None HAL_TIM_Encoder_MspDeInit Function Name void HAL_TIM_Encoder_MspDeInit (TIM_HandleTypeDef * htim) Function Description DeInitializes TIM Encoder Interface MSP. Parameters htim: TIM handle Return values None HAL_TIM_Encoder_Start Function Name 560/654 UM1816 Stops the TIM One Pulse signal generation in interrupt mode. HAL_StatusTypeDef HAL_TIM_Encoder_Start (TIM_HandleTypeDef * htim, uint32_t Channel) DOCID026682 Rev 3 UM1816 41.3.66 41.3.67 41.3.68 HAL TIM Generic Driver Function Description Starts the TIM Encoder Interface. Parameters htim: : TIM Encoder Interface handle Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2 are selected Return values HAL status HAL_TIM_Encoder_Stop Function Name HAL_StatusTypeDef HAL_TIM_Encoder_Stop (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the TIM Encoder Interface. Parameters htim: : TIM Encoder Interface handle Channel: : TIM Channels to be disabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2 are selected Return values HAL status HAL_TIM_Encoder_Start_IT Function Name HAL_StatusTypeDef HAL_TIM_Encoder_Start_IT (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Starts the TIM Encoder Interface in interrupt mode. Parameters htim: : TIM Encoder Interface handle Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2 are selected Return values HAL status HAL_TIM_Encoder_Stop_IT Function Name HAL_StatusTypeDef HAL_TIM_Encoder_Stop_IT (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the TIM Encoder Interface in interrupt mode. Parameters htim: : TIM Encoder Interface handle Channel: : TIM Channels to be disabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2 are selected Return values HAL status DOCID026682 Rev 3 561/654 HAL TIM Generic Driver 41.3.69 UM1816 HAL_TIM_Encoder_Start_DMA Function Name HAL_StatusTypeDef HAL_TIM_Encoder_Start_DMA (TIM_HandleTypeDef * htim, uint32_t Channel, uint32_t * pData1, uint32_t * pData2, uint16_t Length) Function Description Starts the TIM Encoder Interface in DMA mode. Parameters Return values 41.3.70 41.3.71 41.3.72 562/654 htim: : TIM Encoder Interface handle Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2 are selected pData1: The destination Buffer address for IC1. pData2: The destination Buffer address for IC2. Length: The length of data to be transferred from TIM peripheral to memory. HAL status HAL_TIM_Encoder_Stop_DMA Function Name HAL_StatusTypeDef HAL_TIM_Encoder_Stop_DMA (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Stops the TIM Encoder Interface in DMA mode. Parameters htim: : TIM Encoder Interface handle Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_ALL: TIM Channel 1 and TIM Channel 2 are selected Return values HAL status HAL_TIM_IRQHandler Function Name void HAL_TIM_IRQHandler (TIM_HandleTypeDef * htim) Function Description This function handles TIM interrupts requests. Parameters htim: TIM handle Return values None HAL_TIM_OC_ConfigChannel Function Name HAL_StatusTypeDef HAL_TIM_OC_ConfigChannel (TIM_HandleTypeDef * htim, TIM_OC_InitTypeDef * sConfig, uint32_t Channel) Function Description Initializes the TIM Output Compare Channels according to the specified parameters in the TIM_OC_InitTypeDef. Parameters htim: TIM Output Compare handle sConfig: TIM Output Compare configuration structure Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values 41.3.73 41.3.74 41.3.75 HAL status HAL_TIM_IC_ConfigChannel Function Name HAL_StatusTypeDef HAL_TIM_IC_ConfigChannel (TIM_HandleTypeDef * htim, TIM_IC_InitTypeDef * sConfig, uint32_t Channel) Function Description Initializes the TIM Input Capture Channels according to the specified parameters in the TIM_IC_InitTypeDef. Parameters htim: TIM IC handle sConfig: TIM Input Capture configuration structure Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_PWM_ConfigChannel Function Name HAL_StatusTypeDef HAL_TIM_PWM_ConfigChannel (TIM_HandleTypeDef * htim, TIM_OC_InitTypeDef * sConfig, uint32_t Channel) Function Description Initializes the TIM PWM channels according to the specified parameters in the TIM_OC_InitTypeDef. Parameters htim: TIM handle sConfig: TIM PWM configuration structure Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values HAL status HAL_TIM_OnePulse_ConfigChannel Function Name HAL_StatusTypeDef HAL_TIM_OnePulse_ConfigChannel (TIM_HandleTypeDef * htim, TIM_OnePulse_InitTypeDef * sConfig, uint32_t OutputChannel, uint32_t InputChannel) Function Description Initializes the TIM One Pulse Channels according to the specified parameters in the TIM_OnePulse_InitTypeDef. Parameters htim: TIM One Pulse handle sConfig: TIM One Pulse configuration structure OutputChannel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selected DOCID026682 Rev 3 563/654 HAL TIM Generic Driver Return values 41.3.76 HAL status Fu nc tio n N a m e HAL_StatusTypeDef HAL_TIM_DMABurst_WriteStart (TIM_HandleTypeDef * htim, uint32_t BurstBaseAddress, uint32_t BurstRequestSrc, uint32_t * BurstBuffer, uint32_t BurstLength) Fu nc tio n D es cri pti on Configure the DMA Burst to transfer Data from the memory to the TIM peripheral. Pa ra m et er s R et ur n va lu es 564/654 InputChannel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selected HAL_TIM_DMABurst_WriteStart 41.3.77 UM1816 htim: TIM handle BurstBaseAddress: : TIM Base address from where the DMA will start the Data write This parameter can be one of the following values: TIM_DMABASE_CR1TIM_DMABASE_CR2TIM_DMABASE_SMCRTIM_DMAB ASE_DIERTIM_DMABASE_SRTIM_DMABASE_EGRTIM_DMABASE_CCMR1T IM_DMABASE_CCMR2TIM_DMABASE_CCERTIM_DMABASE_CNTTIM_DMA BASE_PSCTIM_DMABASE_ARRTIM_DMABASE_CCR1TIM_DMABASE_CCR 2TIM_DMABASE_CCR3TIM_DMABASE_CCR4TIM_DMABASE_DCR BurstRequestSrc: TIM DMA Request sources This parameter can be one of the following values: TIM_DMA_UPDATE: TIM update Interrupt sourceTIM_DMA_CC1: TIM Capture Compare 1 DMA sourceTIM_DMA_CC2: TIM Capture Compare 2 DMA sourceTIM_DMA_CC3: TIM Capture Compare 3 DMA sourceTIM_DMA_CC4: TIM Capture Compare 4 DMA sourceTIM_DMA_TRIGGER: TIM Trigger DMA source BurstBuffer: The Buffer address. BurstLength: DMA Burst length. This parameter can be one value between: TIM_DMABURSTLENGTH_1TRANSFER and TIM_DMABURSTLENGTH_18TRANSFERS. HAL status HAL_TIM_DMABurst_WriteStop DOCID026682 Rev 3 UM1816 41.3.78 Function Name HAL TIM Generic Driver HAL_StatusTypeDef HAL_TIM_DMABurst_WriteStop (TIM_HandleTypeDef * htim, uint32_t BurstRequestSrc) Function Description Stops the TIM DMA Burst mode. Parameters htim: TIM handle BurstRequestSrc: TIM DMA Request sources to disable Return values HAL status HAL_TIM_DMABurst_ReadStart Fu nc tio n N a m e HAL_StatusTypeDef HAL_TIM_DMABurst_ReadStart (TIM_HandleTypeDef * htim, uint32_t BurstBaseAddress, uint32_t BurstRequestSrc, uint32_t * BurstBuffer, uint32_t BurstLength) Fu nc tio n D es cri pti on Configure the DMA Burst to transfer Data from the TIM peripheral to the memory. Pa ra m et er s R et ur n va lu es htim: TIM handle BurstBaseAddress: : TIM Base address from where the DMA will starts the Data read This parameter can be one of the following values: TIM_DMABASE_CR1TIM_DMABASE_CR2TIM_DMABASE_SMCRTIM_DMAB ASE_DIERTIM_DMABASE_SRTIM_DMABASE_EGRTIM_DMABASE_CCMR1T IM_DMABASE_CCMR2TIM_DMABASE_CCERTIM_DMABASE_CNTTIM_DMA BASE_PSCTIM_DMABASE_ARRTIM_DMABASE_CCR1TIM_DMABASE_CCR 2TIM_DMABASE_CCR3TIM_DMABASE_CCR4TIM_DMABASE_DCR BurstRequestSrc: TIM DMA Request sources This parameter can be one of the following values: TIM_DMA_UPDATE: TIM update Interrupt sourceTIM_DMA_CC1: TIM Capture Compare 1 DMA sourceTIM_DMA_CC2: TIM Capture Compare 2 DMA sourceTIM_DMA_CC3: TIM Capture Compare 3 DMA sourceTIM_DMA_CC4: TIM Capture Compare 4 DMA sourceTIM_DMA_TRIGGER: TIM Trigger DMA source BurstBuffer: The Buffer address. BurstLength: DMA Burst length. This parameter can be one value between: TIM_DMABURSTLENGTH_1TRANSFER and TIM_DMABURSTLENGTH_18TRANSFERS. HAL status DOCID026682 Rev 3 565/654 HAL TIM Generic Driver 41.3.79 41.3.80 41.3.81 UM1816 HAL_TIM_DMABurst_ReadStop Function Name HAL_StatusTypeDef HAL_TIM_DMABurst_ReadStop (TIM_HandleTypeDef * htim, uint32_t BurstRequestSrc) Function Description Stop the DMA burst reading. Parameters htim: TIM handle BurstRequestSrc: TIM DMA Request sources to disable. Return values HAL status HAL_TIM_GenerateEvent Function Name HAL_StatusTypeDef HAL_TIM_GenerateEvent (TIM_HandleTypeDef * htim, uint32_t EventSource) Function Description Generate a software event. Parameters htim: TIM handle EventSource: specifies the event source. This parameter can be one of the following values: TIM_EVENTSOURCE_UPDATE: Timer update Event sourceTIM_EVENTSOURCE_CC1: Timer Capture Compare 1 Event sourceTIM_EVENTSOURCE_CC2: Timer Capture Compare 2 Event sourceTIM_EVENTSOURCE_CC3: Timer Capture Compare 3 Event sourceTIM_EVENTSOURCE_CC4: Timer Capture Compare 4 Event sourceTIM_EVENTSOURCE_TRIGGER: Timer Trigger Event source Return values HAL status Notes TIM6 and TIM7 can only generate an update event. HAL_TIM_ConfigOCrefClear Function Name HAL_StatusTypeDef HAL_TIM_ConfigOCrefClear (TIM_HandleTypeDef * htim, TIM_ClearInputConfigTypeDef * sClearInputConfig, uint32_t Channel) Function Description Configures the OCRef clear feature. Parameters Return values 41.3.82 HAL status HAL_TIM_ConfigClockSource Function Name 566/654 htim: TIM handle sClearInputConfig: pointer to a TIM_ClearInputConfigTypeDef structure that contains the OCREF clear feature and parameters for the TIM peripheral. Channel: specifies the TIM Channel This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1TIM_CHANNEL_2: TIM Channel 2TIM_CHANNEL_3: TIM Channel 3TIM_CHANNEL_4: TIM Channel 4 HAL_StatusTypeDef HAL_TIM_ConfigClockSource (TIM_HandleTypeDef * htim, TIM_ClockConfigTypeDef * sClockSourceConfig) DOCID026682 Rev 3 UM1816 41.3.83 41.3.84 41.3.85 HAL TIM Generic Driver Function Description Configures the clock source to be used. Parameters htim: TIM handle sClockSourceConfig: pointer to a TIM_ClockConfigTypeDef structure that contains the clock source information for the TIM peripheral. Return values HAL status HAL_TIM_ConfigTI1Input Function Name HAL_StatusTypeDef HAL_TIM_ConfigTI1Input (TIM_HandleTypeDef * htim, uint32_t TI1_Selection) Function Description Selects the signal connected to the TI1 input: direct from CH1_input or a XOR combination between CH1_input, CH2_input & CH3_input. Parameters htim: TIM handle. TI1_Selection: Indicate whether or not channel 1 is connected to the output of a XOR gate. This parameter can be one of the following values: TIM_TI1SELECTION_CH1: The TIMx_CH1 pin is connected to TI1 inputTIM_TI1SELECTION_XORCOMBINATION: The TIMx_CH1, CH2 and CH3 pins are connected to the TI1 input (XOR combination) Return values HAL status HAL_TIM_SlaveConfigSynchronization Function Name HAL_StatusTypeDef HAL_TIM_SlaveConfigSynchronization (TIM_HandleTypeDef * htim, TIM_SlaveConfigTypeDef * sSlaveConfig) Function Description Configures the TIM in Slave mode. Parameters htim: : TIM handle. sSlaveConfig: pointer to a TIM_SlaveConfigTypeDef structure that contains the selected trigger (internal trigger input, filtered timer input or external trigger input) and the ) and the Slave mode (Disable, Reset, Gated, Trigger, External clock mode 1). Return values HAL status HAL_TIM_SlaveConfigSynchronization_IT Function Name HAL_StatusTypeDef HAL_TIM_SlaveConfigSynchronization_IT (TIM_HandleTypeDef * htim, TIM_SlaveConfigTypeDef * sSlaveConfig) Function Description Configures the TIM in Slave mode in interrupt mode. Parameters htim: TIM handle. sSlaveConfig: pointer to a TIM_SlaveConfigTypeDef structure that contains the selected trigger (internal trigger input, filtered timer input or external trigger input) and the ) DOCID026682 Rev 3 567/654 HAL TIM Generic Driver Return values 41.3.86 41.3.87 41.3.88 41.3.89 41.3.90 568/654 UM1816 and the Slave mode (Disable, Reset, Gated, Trigger, External clock mode 1). HAL status HAL_TIM_ReadCapturedValue Function Name uint32_t HAL_TIM_ReadCapturedValue (TIM_HandleTypeDef * htim, uint32_t Channel) Function Description Read the captured value from Capture Compare unit. Parameters htim: TIM handle. Channel: : TIM Channels to be enabled This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selectedTIM_CHANNEL_2: TIM Channel 2 selectedTIM_CHANNEL_3: TIM Channel 3 selectedTIM_CHANNEL_4: TIM Channel 4 selected Return values Captured value HAL_TIM_PeriodElapsedCallback Function Name void HAL_TIM_PeriodElapsedCallback (TIM_HandleTypeDef * htim) Function Description Period elapsed callback in non blocking mode. Parameters htim: : TIM handle Return values None HAL_TIM_OC_DelayElapsedCallback Function Name void HAL_TIM_OC_DelayElapsedCallback (TIM_HandleTypeDef * htim) Function Description Output Compare callback in non blocking mode. Parameters htim: : TIM OC handle Return values None HAL_TIM_IC_CaptureCallback Function Name void HAL_TIM_IC_CaptureCallback (TIM_HandleTypeDef * htim) Function Description Input Capture callback in non blocking mode. Parameters htim: : TIM IC handle Return values None HAL_TIM_PWM_PulseFinishedCallback Function Name void HAL_TIM_PWM_PulseFinishedCallback (TIM_HandleTypeDef * htim) Function Description PWM Pulse finished callback in non blocking mode. DOCID026682 Rev 3 UM1816 41.3.91 41.3.92 41.3.93 41.3.94 41.3.95 41.3.96 HAL TIM Generic Driver Parameters htim: : TIM handle Return values None HAL_TIM_TriggerCallback Function Name void HAL_TIM_TriggerCallback (TIM_HandleTypeDef * htim) Function Description Hall Trigger detection callback in non blocking mode. Parameters htim: : TIM handle Return values None HAL_TIM_ErrorCallback Function Name void HAL_TIM_ErrorCallback (TIM_HandleTypeDef * htim) Function Description Timer error callback in non blocking mode. Parameters htim: : TIM handle Return values None HAL_TIM_Base_GetState Function Name HAL_TIM_StateTypeDef HAL_TIM_Base_GetState (TIM_HandleTypeDef * htim) Function Description Return the TIM Base state. Parameters htim: TIM Base handle Return values HAL state HAL_TIM_OC_GetState Function Name HAL_TIM_StateTypeDef HAL_TIM_OC_GetState (TIM_HandleTypeDef * htim) Function Description Return the TIM OC state. Parameters htim: TIM Ouput Compare handle Return values HAL state HAL_TIM_PWM_GetState Function Name HAL_TIM_StateTypeDef HAL_TIM_PWM_GetState (TIM_HandleTypeDef * htim) Function Description Return the TIM PWM state. Parameters htim: TIM handle Return values HAL state HAL_TIM_IC_GetState Function Name HAL_TIM_StateTypeDef HAL_TIM_IC_GetState (TIM_HandleTypeDef * htim) DOCID026682 Rev 3 569/654 HAL TIM Generic Driver Function Description 41.3.97 41.3.98 41.3.99 UM1816 Return the TIM Input Capture state. Parameters htim: TIM IC handle Return values HAL state HAL_TIM_OnePulse_GetState Function Name HAL_TIM_StateTypeDef HAL_TIM_OnePulse_GetState (TIM_HandleTypeDef * htim) Function Description Return the TIM One Pulse Mode state. Parameters htim: TIM OPM handle Return values HAL state HAL_TIM_Encoder_GetState Function Name HAL_TIM_StateTypeDef HAL_TIM_Encoder_GetState (TIM_HandleTypeDef * htim) Function Description Return the TIM Encoder Mode state. Parameters htim: TIM Encoder handle Return values HAL state TIM_DMAError Function Name void TIM_DMAError (DMA_HandleTypeDef * hdma) Function Description TIM DMA error callback. Parameters hdma: : pointer to DMA handle. Return values None 41.3.100 TIM_DMADelayPulseCplt Function Name void TIM_DMADelayPulseCplt (DMA_HandleTypeDef * hdma) Function Description TIM DMA Delay Pulse complete callback. Parameters hdma: : pointer to DMA handle. Return values None 41.3.101 TIM_DMACaptureCplt 570/654 Function Name void TIM_DMACaptureCplt (DMA_HandleTypeDef * hdma) Function Description TIM DMA Capture complete callback. Parameters hdma: : pointer to DMA handle. Return values None DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver 41.4 TIM Firmware driver defines 41.4.1 TIM TIM Automatic Output Enable TIM_AUTOMATICOUTPUT_ENABLE TIM_AUTOMATICOUTPUT_DISABLE TIM Channel TIM_CHANNEL_1 TIM_CHANNEL_2 TIM_CHANNEL_3 TIM_CHANNEL_4 TIM_CHANNEL_ALL TIM Capture/Compare Channel State TIM_CCx_ENABLE TIM_CCx_DISABLE TIM ClearInput Polarity TIM_CLEARINPUTPOLARITY_INVERTED Polarity for ETRx pin TIM_CLEARINPUTPOLARITY_NONINVERTED Polarity for ETRx pin TIM ClearInput Prescaler TIM_CLEARINPUTPRESCALER_DIV1 No prescaler is used TIM_CLEARINPUTPRESCALER_DIV2 Prescaler for External ETR pin: Capture performed once every 2 events. TIM_CLEARINPUTPRESCALER_DIV4 Prescaler for External ETR pin: Capture performed once every 4 events. TIM_CLEARINPUTPRESCALER_DIV8 Prescaler for External ETR pin: Capture performed once every 8 events. TIM ClearInput Source TIM_CLEARINPUTSOURCE_ETR TIM_CLEARINPUTSOURCE_OCREFCLR TIM_CLEARINPUTSOURCE_NONE TIM ClockDivision TIM_CLOCKDIVISION_DIV1 TIM_CLOCKDIVISION_DIV2 TIM_CLOCKDIVISION_DIV4 TIM Clock Polarity TIM_CLOCKPOLARITY_INVERTED Polarity for ETRx clock sources TIM_CLOCKPOLARITY_NONINVERTED Polarity for ETRx clock sources TIM_CLOCKPOLARITY_RISING Polarity for TIx clock sources DOCID026682 Rev 3 571/654 HAL TIM Generic Driver TIM_CLOCKPOLARITY_FALLING UM1816 Polarity for TIx clock sources TIM_CLOCKPOLARITY_BOTHEDGE Polarity for TIx clock sources TIM Clock Prescaler TIM_CLOCKPRESCALER_DIV1 No prescaler is used TIM_CLOCKPRESCALER_DIV2 Prescaler for External ETR Clock: Capture performed once every 2 events. TIM_CLOCKPRESCALER_DIV4 Prescaler for External ETR Clock: Capture performed once every 4 events. TIM_CLOCKPRESCALER_DIV8 Prescaler for External ETR Clock: Capture performed once every 8 events. TIM Clock Source TIM_CLOCKSOURCE_ETRMODE2 TIM_CLOCKSOURCE_INTERNAL TIM_CLOCKSOURCE_ITR0 TIM_CLOCKSOURCE_ITR1 TIM_CLOCKSOURCE_ITR2 TIM_CLOCKSOURCE_ITR3 TIM_CLOCKSOURCE_TI1ED TIM_CLOCKSOURCE_TI1 TIM_CLOCKSOURCE_TI2 TIM_CLOCKSOURCE_ETRMODE1 TIM Counter Mode TIM_COUNTERMODE_UP TIM_COUNTERMODE_DOWN TIM_COUNTERMODE_CENTERALIGNED1 TIM_COUNTERMODE_CENTERALIGNED2 TIM_COUNTERMODE_CENTERALIGNED3 TIM DMA Base Address TIM_DMABASE_CR1 TIM_DMABASE_CR2 TIM_DMABASE_SMCR TIM_DMABASE_DIER TIM_DMABASE_SR TIM_DMABASE_EGR TIM_DMABASE_CCMR1 TIM_DMABASE_CCMR2 TIM_DMABASE_CCER 572/654 DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver TIM_DMABASE_CNT TIM_DMABASE_PSC TIM_DMABASE_ARR TIM_DMABASE_CCR1 TIM_DMABASE_CCR2 TIM_DMABASE_CCR3 TIM_DMABASE_CCR4 TIM_DMABASE_DCR TIM_DMABASE_OR TIM DMA Burst Length TIM_DMABURSTLENGTH_1TRANSFER TIM_DMABURSTLENGTH_2TRANSFERS TIM_DMABURSTLENGTH_3TRANSFERS TIM_DMABURSTLENGTH_4TRANSFERS TIM_DMABURSTLENGTH_5TRANSFERS TIM_DMABURSTLENGTH_6TRANSFERS TIM_DMABURSTLENGTH_7TRANSFERS TIM_DMABURSTLENGTH_8TRANSFERS TIM_DMABURSTLENGTH_9TRANSFERS TIM_DMABURSTLENGTH_10TRANSFERS TIM_DMABURSTLENGTH_11TRANSFERS TIM_DMABURSTLENGTH_12TRANSFERS TIM_DMABURSTLENGTH_13TRANSFERS TIM_DMABURSTLENGTH_14TRANSFERS TIM_DMABURSTLENGTH_15TRANSFERS TIM_DMABURSTLENGTH_16TRANSFERS TIM_DMABURSTLENGTH_17TRANSFERS TIM_DMABURSTLENGTH_18TRANSFERS TIM DMA Handle Index TIM_DMA_ID_UPDATE Index of the DMA handle used for Update DMA requests TIM_DMA_ID_CC1 Index of the DMA handle used for Capture/Compare 1 DMA requests TIM_DMA_ID_CC2 Index of the DMA handle used for Capture/Compare 2 DMA requests TIM_DMA_ID_CC3 Index of the DMA handle used for Capture/Compare 3 DMA requests TIM_DMA_ID_CC4 Index of the DMA handle used for Capture/Compare 4 DMA requests DOCID026682 Rev 3 573/654 HAL TIM Generic Driver TIM_DMA_ID_TRIGGER UM1816 Index of the DMA handle used for Trigger DMA requests TIM DMA Sources TIM_DMA_UPDATE TIM_DMA_CC1 TIM_DMA_CC2 TIM_DMA_CC3 TIM_DMA_CC4 TIM_DMA_TRIGGER TIM Encoder Mode TIM_ENCODERMODE_TI1 TIM_ENCODERMODE_TI2 TIM_ENCODERMODE_TI12 TIM ETR Polarity TIM_ETRPOLARITY_INVERTED Polarity for ETR source TIM_ETRPOLARITY_NONINVERTED Polarity for ETR source TIM ETR Prescaler TIM_ETRPRESCALER_DIV1 No prescaler is used TIM_ETRPRESCALER_DIV2 ETR input source is divided by 2 TIM_ETRPRESCALER_DIV4 ETR input source is divided by 4 TIM_ETRPRESCALER_DIV8 ETR input source is divided by 8 TIM Event Source TIM_EVENTSOURCE_UPDATE TIM_EVENTSOURCE_CC1 TIM_EVENTSOURCE_CC2 TIM_EVENTSOURCE_CC3 TIM_EVENTSOURCE_CC4 TIM_EVENTSOURCE_TRIGGER TIM Exported Macros __HAL_TIM_RESET_HANDLE_ST ATE Description: Reset TIM handle state. Parameters: __HANDLE__: TIM handle. Return value: __HAL_TIM_ENABLE Description: 574/654 None Enable the TIM peripheral. DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver Parameters: __HANDLE__: TIM handle Return value: __HAL_TIM_DISABLE None Description: Disable the TIM peripheral. Parameters: __HANDLE__: TIM handle Return value: __HAL_TIM_ENABLE_IT None Description: Enables the specified TIM interrupt. Parameters: __HANDLE__: specifies the TIM Handle. __INTERRUPT__: specifies the TIM interrupt source to enable. This parameter can be one of the following values: TIM_IT_UPDATE: Update interrupt TIM_IT_CC1: Capture/Compare 1 interrupt TIM_IT_CC2: Capture/Compare 2 interrupt TIM_IT_CC3: Capture/Compare 3 interrupt TIM_IT_CC4: Capture/Compare 4 interrupt TIM_IT_COM: Commutation interrupt TIM_IT_TRIGGER: Trigger interrupt Return value: __HAL_TIM_DISABLE_IT None Description: Disables the specified TIM interrupt. Parameters: __HANDLE__: specifies the TIM Handle. __INTERRUPT__: specifies the TIM interrupt source to disable. This parameter can be one of the following values: TIM_IT_UPDATE: Update interrupt TIM_IT_CC1: Capture/Compare 1 interrupt TIM_IT_CC2: Capture/Compare 2 interrupt TIM_IT_CC3: Capture/Compare 3 interrupt TIM_IT_CC4: Capture/Compare 4 interrupt TIM_IT_COM: Commutation interrupt TIM_IT_TRIGGER: Trigger interrupt Return value: None DOCID026682 Rev 3 575/654 HAL TIM Generic Driver __HAL_TIM_ENABLE_DMA UM1816 Description: Enables the specified DMA request. Parameters: __HANDLE__: specifies the TIM Handle. __DMA__: specifies the TIM DMA request to enable. This parameter can be one of the following values: TIM_DMA_UPDATE: Update DMA request TIM_DMA_CC1: Capture/Compare 1 DMA request TIM_DMA_CC2: Capture/Compare 2 DMA request TIM_DMA_CC3: Capture/Compare 3 DMA request TIM_DMA_CC4: Capture/Compare 4 DMA request TIM_DMA_COM: Commutation DMA request TIM_DMA_TRIGGER: Trigger DMA request Return value: __HAL_TIM_DISABLE_DMA None Description: Disables the specified DMA request. Parameters: __HANDLE__: specifies the TIM Handle. __DMA__: specifies the TIM DMA request to disable. This parameter can be one of the following values: TIM_DMA_UPDATE: Update DMA request TIM_DMA_CC1: Capture/Compare 1 DMA request TIM_DMA_CC2: Capture/Compare 2 DMA request TIM_DMA_CC3: Capture/Compare 3 DMA request TIM_DMA_CC4: Capture/Compare 4 DMA request TIM_DMA_COM: Commutation DMA request TIM_DMA_TRIGGER: Trigger DMA request Return value: __HAL_TIM_GET_FLAG Description: 576/654 None Checks whether the specified TIM interrupt flag is set or not. DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver Parameters: __HANDLE__: specifies the TIM Handle. __FLAG__: specifies the TIM interrupt flag to check. This parameter can be one of the following values: TIM_FLAG_UPDATE: Update interrupt flag TIM_FLAG_CC1: Capture/Compare 1 interrupt flag TIM_FLAG_CC2: Capture/Compare 2 interrupt flag TIM_FLAG_CC3: Capture/Compare 3 interrupt flag TIM_FLAG_CC4: Capture/Compare 4 interrupt flag TIM_FLAG_COM: Commutation interrupt flag TIM_FLAG_TRIGGER: Trigger interrupt flag TIM_FLAG_CC1OF: Capture/Compare 1 overcapture flag TIM_FLAG_CC2OF: Capture/Compare 2 overcapture flag TIM_FLAG_CC3OF: Capture/Compare 3 overcapture flag TIM_FLAG_CC4OF: Capture/Compare 4 overcapture flag Return value: __HAL_TIM_CLEAR_FLAG The: new state of __FLAG__ (TRUE or FALSE). Description: Clears the specified TIM interrupt flag. Parameters: __HANDLE__: specifies the TIM Handle. __FLAG__: specifies the TIM interrupt flag to clear. This parameter can be one of the following values: TIM_FLAG_UPDATE: Update interrupt flag TIM_FLAG_CC1: Capture/Compare 1 interrupt flag TIM_FLAG_CC2: Capture/Compare 2 interrupt flag TIM_FLAG_CC3: Capture/Compare 3 interrupt flag TIM_FLAG_CC4: Capture/Compare 4 interrupt flag TIM_FLAG_COM: Commutation interrupt flag TIM_FLAG_TRIGGER: Trigger interrupt flag TIM_FLAG_CC1OF: Capture/Compare 1 overcapture flag DOCID026682 Rev 3 577/654 HAL TIM Generic Driver UM1816 TIM_FLAG_CC2OF: Capture/Compare 2 overcapture flag TIM_FLAG_CC3OF: Capture/Compare 3 overcapture flag TIM_FLAG_CC4OF: Capture/Compare 4 overcapture flag Return value: __HAL_TIM_GET_IT_SOURCE The: new state of __FLAG__ (TRUE or FALSE). Description: Checks whether the specified TIM interrupt has occurred or not. Parameters: __HANDLE__: TIM handle __INTERRUPT__: specifies the TIM interrupt source to check. Return value: The: state of TIM_IT (SET or RESET). Description: __HAL_TIM_CLEAR_IT Clear the TIM interrupt pending bits. Parameters: __HANDLE__: TIM handle __INTERRUPT__: specifies the interrupt pending bit to clear. Return value: __HAL_TIM_IS_TIM_COUNTING_ DOWN None Description: Indicates whether or not the TIM Counter is used as downcounter. Parameters: __HANDLE__: TIM handle. Return value: False: (Counter used as upcounter) or True (Counter used as downcounter) Notes: __HAL_TIM_SET_PRESCALER This macro is particularly usefull to get the counting mode when the timer operates in Center-aligned mode or Encoder mode. Description: Sets the TIM active prescaler register value on update event. Parameters: 578/654 DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver __HANDLE__: TIM handle. __PRESC__: specifies the active prescaler register new value. Return value: __HAL_TIM_SET_COMPARE None Description: Sets the TIM Capture Compare Register value on runtime without calling another time ConfigChannel function. Parameters: __HANDLE__: TIM handle. __CHANNEL__: : TIM Channels to be configured. This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selected TIM_CHANNEL_2: TIM Channel 2 selected TIM_CHANNEL_3: TIM Channel 3 selected TIM_CHANNEL_4: TIM Channel 4 selected __COMPARE__: specifies the Capture Compare register new value. Return value: __HAL_TIM_GET_COMPARE None Description: Gets the TIM Capture Compare Register value on runtime. Parameters: __HANDLE__: TIM handle. __CHANNEL__: : TIM Channel associated with the capture compare register This parameter can be one of the following values: TIM_CHANNEL_1: get capture/compare 1 register value TIM_CHANNEL_2: get capture/compare 2 register value TIM_CHANNEL_3: get capture/compare 3 register value TIM_CHANNEL_4: get capture/compare 4 register value Return value: __HAL_TIM_SET_COUNTER None Description: Sets the TIM Counter Register value on DOCID026682 Rev 3 579/654 HAL TIM Generic Driver UM1816 runtime. Parameters: __HANDLE__: TIM handle. __COUNTER__: specifies the Counter register new value. Return value: __HAL_TIM_GET_COUNTER None Description: Gets the TIM Counter Register value on runtime. Parameters: __HANDLE__: TIM handle. Return value: __HAL_TIM_SET_AUTORELOAD None Description: Sets the TIM Autoreload Register value on runtime without calling another time any Init function. Parameters: __HANDLE__: TIM handle. __AUTORELOAD__: specifies the Counter register new value. Return value: __HAL_TIM_GET_AUTORELOAD None Description: Gets the TIM Autoreload Register value on runtime. Parameters: __HANDLE__: TIM handle. Return value: __HAL_TIM_SET_CLOCKDIVISIO N None Description: Sets the TIM Clock Division value on runtime without calling another time any Init function. Parameters: 580/654 __HANDLE__: TIM handle. __CKD__: specifies the clock division value. This parameter can be one of the following value: TIM_CLOCKDIVISION_DIV1 TIM_CLOCKDIVISION_DIV2 DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver TIM_CLOCKDIVISION_DIV4 Return value: __HAL_TIM_GET_CLOCKDIVISIO N None Description: Gets the TIM Clock Division value on runtime. Parameters: __HANDLE__: TIM handle. Return value: __HAL_TIM_SET_ICPRESCALER None Description: Sets the TIM Input Capture prescaler on runtime without calling another time Parameters: __HANDLE__: TIM handle. __CHANNEL__: : TIM Channels to be configured. This parameter can be one of the following values: TIM_CHANNEL_1: TIM Channel 1 selected TIM_CHANNEL_2: TIM Channel 2 selected TIM_CHANNEL_3: TIM Channel 3 selected TIM_CHANNEL_4: TIM Channel 4 selected __ICPSC__: specifies the Input Capture4 prescaler new value. This parameter can be one of the following values: TIM_ICPSC_DIV1: no prescaler TIM_ICPSC_DIV2: capture is done once every 2 events TIM_ICPSC_DIV4: capture is done once every 4 events TIM_ICPSC_DIV8: capture is done once every 8 events Return value: __HAL_TIM_GET_ICPRESCALER None Description: Gets the TIM Input Capture prescaler on runtime. Parameters: __HANDLE__: TIM handle. __CHANNEL__: : TIM Channels to be configured. This parameter can be one of the following values: DOCID026682 Rev 3 581/654 HAL TIM Generic Driver UM1816 TIM_CHANNEL_1: get input capture 1 prescaler value TIM_CHANNEL_2: get input capture 2 prescaler value TIM_CHANNEL_3: get input capture 3 prescaler value TIM_CHANNEL_4: get input capture 4 prescaler value Return value: None Description: __HAL_TIM_URS_ENABLE Set the Update Request Source (URS) bit of the TIMx_CR1 register. Parameters: __HANDLE__: TIM handle. Return value: None Notes: __HAL_TIM_URS_DISABLE When the USR bit of the TIMx_CR1 register is set, only counter overflow/underflow generates an update interrupt or DMA request (if enabled) Description: Reset the Update Request Source (URS) bit of the TIMx_CR1 register. Parameters: __HANDLE__: TIM handle. Return value: None Notes: __HAL_TIM_SET_CAPTUREPOL ARITY When the USR bit of the TIMx_CR1 register is reset, any of the following events generate an update interrupt or DMA request (if enabled): (+) Counter overflow/underflow (+) Setting the UG bit (+) Update generation through the slave mode controller Description: Sets the TIM Capture x input polarity on runtime. Parameters: 582/654 __HANDLE__: TIM handle. __CHANNEL__: TIM Channels to be configured. This parameter can be one of the following values: DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver TIM_CHANNEL_1: TIM Channel 1 selected TIM_CHANNEL_2: TIM Channel 2 selected TIM_CHANNEL_3: TIM Channel 3 selected TIM_CHANNEL_4: TIM Channel 4 selected __POLARITY__: Polarity for TIx source TIM_INPUTCHANNELPOLARITY_RISING : Rising Edge TIM_INPUTCHANNELPOLARITY_FALLIN G: Falling Edge TIM_INPUTCHANNELPOLARITY_BOTHE DGE: Rising and Falling Edge Return value: None Notes: The polarity TIM_INPUTCHANNELPOLARITY_BOTHEDGE is not authorized for TIM Channel 4. TIM Flag Definition TIM_FLAG_UPDATE TIM_FLAG_CC1 TIM_FLAG_CC2 TIM_FLAG_CC3 TIM_FLAG_CC4 TIM_FLAG_TRIGGER TIM_FLAG_CC1OF TIM_FLAG_CC2OF TIM_FLAG_CC3OF TIM_FLAG_CC4OF TIM Input Capture Polarity TIM_ICPOLARITY_RISING TIM_ICPOLARITY_FALLING TIM_ICPOLARITY_BOTHEDGE TIM Input Capture Prescaler TIM_ICPSC_DIV1 Capture performed each time an edge is detected on the capture input TIM_ICPSC_DIV2 Capture performed once every 2 events TIM_ICPSC_DIV4 Capture performed once every 4 events TIM_ICPSC_DIV8 Capture performed once every 8 events DOCID026682 Rev 3 583/654 HAL TIM Generic Driver TIM Input Capture Selection UM1816 TIM_ICSELECTION_DIRECTTI TIM Input 1, 2, 3 or 4 is selected to be connected to IC1, IC2, IC3 or IC4, respectively TIM_ICSELECTION_INDIRECTTI TIM Input 1, 2, 3 or 4 is selected to be connected to IC2, IC1, IC4 or IC3, respectively TIM_ICSELECTION_TRC TIM Input 1, 2, 3 or 4 is selected to be connected to TRC TIM Input Channel Polarity TIM_INPUTCHANNELPOLARITY_RISING Polarity for TIx source TIM_INPUTCHANNELPOLARITY_FALLING Polarity for TIx source TIM_INPUTCHANNELPOLARITY_BOTHEDGE Polarity for TIx source TIM Interrupt Definition TIM_IT_UPDATE TIM_IT_CC1 TIM_IT_CC2 TIM_IT_CC3 TIM_IT_CC4 TIM_IT_TRIGGER TIM Lock level TIM_LOCKLEVEL_OFF TIM_LOCKLEVEL_1 TIM_LOCKLEVEL_2 TIM_LOCKLEVEL_3 TIM Master Mode Selection TIM_TRGO_RESET TIM_TRGO_ENABLE TIM_TRGO_UPDATE TIM_TRGO_OC1 TIM_TRGO_OC1REF TIM_TRGO_OC2REF TIM_TRGO_OC3REF TIM_TRGO_OC4REF TIM Master Slave Mode TIM_MASTERSLAVEMODE_ENABLE TIM_MASTERSLAVEMODE_DISABLE TIM One Pulse Mode TIM_OPMODE_SINGLE 584/654 DOCID026682 Rev 3 UM1816 HAL TIM Generic Driver TIM_OPMODE_REPETITIVE TIM OSSI Off State Selection for Idle mode state TIM_OSSI_ENABLE TIM_OSSI_DISABLE TIM OSSR Off State Selection for Run mode state TIM_OSSR_ENABLE TIM_OSSR_DISABLE TIM Output Compare and PWM modes TIM_OCMODE_TIMING TIM_OCMODE_ACTIVE TIM_OCMODE_INACTIVE TIM_OCMODE_TOGGLE TIM_OCMODE_PWM1 TIM_OCMODE_PWM2 TIM_OCMODE_FORCED_ACTIVE TIM_OCMODE_FORCED_INACTIVE TIM Output Compare Idle State TIM_OCIDLESTATE_SET TIM_OCIDLESTATE_RESET TIM Output Compare Polarity TIM_OCPOLARITY_HIGH TIM_OCPOLARITY_LOW TIM Output Fast State TIM_OCFAST_DISABLE TIM_OCFAST_ENABLE TIM Private Constants TIM_CCER_CCxE_MASK TIM Private Macros IS_TIM_COUNTER_MODE IS_TIM_CLOCKDIVISION_DIV IS_TIM_PWM_MODE IS_TIM_OC_MODE IS_TIM_FAST_STATE IS_TIM_OC_POLARITY IS_TIM_OCIDLE_STATE IS_TIM_CHANNELS DOCID026682 Rev 3 585/654 HAL TIM Generic Driver IS_TIM_OPM_CHANNELS UM1816 IS_TIM_IC_POLARITY IS_TIM_IC_SELECTION IS_TIM_IC_PRESCALER IS_TIM_OPM_MODE IS_TIM_ENCODER_MODE IS_TIM_DMA_SOURCE IS_TIM_EVENT_SOURCE IS_TIM_CLOCKSOURCE IS_TIM_CLOCKPOLARITY IS_TIM_CLOCKPRESCALER IS_TIM_CLOCKFILTER IS_TIM_CLEARINPUT_SOURCE IS_TIM_CLEARINPUT_POLARITY IS_TIM_CLEARINPUT_PRESCALER IS_TIM_CLEARINPUT_FILTER IS_TIM_OSSR_STATE IS_TIM_OSSI_STATE IS_TIM_LOCK_LEVEL IS_TIM_AUTOMATIC_OUTPUT_STATE IS_TIM_TRGO_SOURCE IS_TIM_SLAVE_MODE IS_TIM_MSM_STATE IS_TIM_TRIGGER_SELECTION IS_TIM_INTERNAL_TRIGGEREVENT_SELECTION IS_TIM_TRIGGERPOLARITY IS_TIM_TRIGGERPRESCALER IS_TIM_TRIGGERFILTER IS_TIM_TI1SELECTION IS_TIM_DMA_BASE IS_TIM_DMA_LENGTH IS_TIM_IC_FILTER TIM_SET_ICPRESCALERVALUE Description: Set TIM IC prescaler. Parameters: 586/654 DOCID026682 Rev 3 __HANDLE__: TIM handle __CHANNEL__: specifies TIM UM1816 HAL TIM Generic Driver Channel __ICPSC__: specifies the prescaler value. Return value: TIM_RESET_ICPRESCALERVALUE None Description: Reset TIM IC prescaler. Parameters: __HANDLE__: TIM handle __CHANNEL__: specifies TIM Channel Return value: TIM_SET_CAPTUREPOLARITY None Description: Set TIM IC polarity. Parameters: __HANDLE__: TIM handle __CHANNEL__: specifies TIM Channel __POLARITY__: specifies TIM Channel Polarity Return value: TIM_RESET_CAPTUREPOLARITY None Description: Reset TIM IC polarity. Parameters: __HANDLE__: TIM handle __CHANNEL__: specifies TIM Channel Return value: None TIM Select TIM_SELECT_NONE None selected TIM_SELECT_TIM2 Timer 2 selected TIM_SELECT_TIM3 Timer 3 selected TIM_SELECT_TIM4 Timer 4 selected IS_RI_TIM TIM Slave Mode TIM_SLAVEMODE_DISABLE DOCID026682 Rev 3 587/654 HAL TIM Generic Driver TIM_SLAVEMODE_RESET UM1816 TIM_SLAVEMODE_GATED TIM_SLAVEMODE_TRIGGER TIM_SLAVEMODE_EXTERNAL1 TIM TI1 Input Selection TIM_TI1SELECTION_CH1 TIM_TI1SELECTION_XORCOMBINATION TIM Trigger Polarity TIM_TRIGGERPOLARITY_INVERTED Polarity for ETRx trigger sources TIM_TRIGGERPOLARITY_NONINVERTED Polarity for ETRx trigger sources TIM_TRIGGERPOLARITY_RISING Polarity for TIxFPx or TI1_ED trigger sources TIM_TRIGGERPOLARITY_FALLING Polarity for TIxFPx or TI1_ED trigger sources TIM_TRIGGERPOLARITY_BOTHEDGE Polarity for TIxFPx or TI1_ED trigger sources TIM Trigger Prescaler TIM_TRIGGERPRESCALER_DIV1 No prescaler is used TIM_TRIGGERPRESCALER_DIV2 Prescaler for External ETR Trigger: Capture performed once every 2 events. TIM_TRIGGERPRESCALER_DIV4 Prescaler for External ETR Trigger: Capture performed once every 4 events. TIM_TRIGGERPRESCALER_DIV8 Prescaler for External ETR Trigger: Capture performed once every 8 events. TIM Trigger Selection TIM_TS_ITR0 TIM_TS_ITR1 TIM_TS_ITR2 TIM_TS_ITR3 TIM_TS_TI1F_ED TIM_TS_TI1FP1 TIM_TS_TI2FP2 TIM_TS_ETRF TIM_TS_NONE 588/654 DOCID026682 Rev 3 UM1816 HAL TIM Extension Driver 42 HAL TIM Extension Driver 42.1 HAL TIM Extension Driver 42.2 TIMEx Firmware driver registers structures 42.2.1 TIM_MasterConfigTypeDef Data Fields uint32_t MasterOutputTrigger uint32_t MasterSlaveMode Field Documentation uint32_t TIM_MasterConfigTypeDef::MasterOutputTrigger Trigger output (TRGO) selection This parameter can be a value of TIM_Master_Mode_Selection uint32_t TIM_MasterConfigTypeDef::MasterSlaveMode Master/slave mode selection This parameter can be a value of TIM_Master_Slave_Mode 42.3 TIMEx Firmware driver API description 42.3.1 TIMER Extended features The Timer Extension features include: 1. 2. 42.3.2 Synchronization circuit to control the timer with external signals and to interconnect several timers together. Timer remapping capabilities configuration Peripheral Control functions This section provides functions allowing to: Configure Master synchronization. Configure timer remapping capabilities. This section contains the following APIs: 42.3.3 HAL_TIMEx_MasterConfigSynchronization() HAL_TIMEx_RemapConfig() HAL_TIMEx_MasterConfigSynchronization Function Name HAL_StatusTypeDef HAL_TIMEx_MasterConfigSynchronization (TIM_HandleTypeDef * htim, TIM_MasterConfigTypeDef * sMasterConfig) DOCID026682 Rev 3 589/654 HAL TIM Extension Driver Function Description 42.3.4 UM1816 Configures the TIM in master mode. Parameters htim: TIM handle. sMasterConfig: pointer to a TIM_MasterConfigTypeDef structure that contains the selected trigger output (TRGO) and the Master/Slave mode. Return values HAL status HAL_TIMEx_RemapConfig Function Name HAL_StatusTypeDef HAL_TIMEx_RemapConfig (TIM_HandleTypeDef * htim, uint32_t Remap) Function Description Configures the TIM2/TIM3/TIM9/TIM10/TIM11 Remapping input capabilities. Parameters htim: TIM handle. Remap: specifies the TIM remapping source. This parameter is a combination of the following values depending on TIM instance. Return values HAL status Notes For TIM2, the parameter can have the following values: TIM_TIM2_ITR1_TIM10_OC: TIM2 ITR1 input is connected to TIM10 OC TIM_TIM2_ITR1_TIM5_TGO: TIM2 ITR1 input is connected to TIM5 TGO For TIM3, the parameter can have the following values: TIM_TIM3_ITR2_TIM11_OC: TIM3 ITR2 input is connected to TIM11 OC TIM_TIM3_ITR2_TIM5_TGO: TIM3 ITR2 input is connected to TIM5 TGO For TIM9, the parameter is a combination of 2 fields (field1 | field2): For TIM9, the field1 can have the following values: TIM_TIM9_ITR1_TIM3_TGO: TIM9 ITR1 input is connected to TIM3 TGO TIM_TIM9_ITR1_TS: TIM9 ITR1 input is connected to touch sensing I/O For TIM9, the field2 can have the following values: TIM_TIM9_GPIO: TIM9 Channel1 is connected to GPIO TIM_TIM9_LSE: TIM9 Channel1 is connected to LSE internal clock TIM_TIM9_GPIO1: TIM9 Channel1 is connected to GPIO TIM_TIM9_GPIO2: TIM9 Channel1 is connected to GPIO For TIM10, the parameter is a combination of 3 fields (field1 | field2 | field3): For TIM10, the field1 can have the following values: TIM_TIM10_TI1RMP: TIM10 Channel 1 depends on TI1_RMP TIM_TIM10_RI: TIM10 Channel 1 is connected to RI For TIM10, the field2 can have the following values: TIM_TIM10_ETR_LSE: TIM10 ETR input is connected to LSE clock TIM_TIM10_ETR_TIM9_TGO: TIM10 ETR input is connected to TIM9 TGO For TIM10, the field3 can have the following values: TIM_TIM10_GPIO: TIM10 Channel1 is connected to GPIO TIM_TIM10_LSI: TIM10 Channel1 is connected to LSI internal 590/654 DOCID026682 Rev 3 UM1816 HAL TIM Extension Driver clock TIM_TIM10_LSE: TIM10 Channel1 is connected to LSE internal clock TIM_TIM10_RTC: TIM10 Channel1 is connected to RTC wakeup interrupt For TIM11, the parameter is a combination of 3 fields (field1 | field2 | field3): For TIM11, the field1 can have the following values: TIM_TIM11_TI1RMP: TIM11 Channel 1 depends on TI1_RMP TIM_TIM11_RI: TIM11 Channel 1 is connected to RI For TIM11, the field2 can have the following values: TIM_TIM11_ETR_LSE: TIM11 ETR input is connected to LSE clock TIM_TIM11_ETR_TIM9_TGO: TIM11 ETR input is connected to TIM9 TGO For TIM11, the field3 can have the following values: TIM_TIM11_GPIO: TIM11 Channel1 is connected to GPIO TIM_TIM11_MSI: TIM11 Channel1 is connected to MSI internal clock TIM_TIM11_HSE_RTC: TIM11 Channel1 is connected to HSE_RTC clock TIM_TIM11_GPIO1: TIM11 Channel1 is connected to GPIO 42.4 TIMEx Firmware driver defines 42.4.1 TIMEx TIMEx Remap TIM_TIM2_ITR1_TIM10_OC TIM2 ITR1 input is connected to TIM10 OC TIM_TIM2_ITR1_TIM5_TGO TIM2 ITR1 input is connected to TIM5 TGO TIM_TIM3_ITR2_TIM11_OC TIM3 ITR2 input is connected to TIM11 OC TIM_TIM3_ITR2_TIM5_TGO TIM3 ITR2 input is connected to TIM5 TGO TIM_TIM9_ITR1_TIM3_TGO TIM9 ITR1 input is connected to TIM3 TGO TIM_TIM9_ITR1_TS TIM9 ITR1 input is connected to touch sensing I/O TIM_TIM9_GPIO TIM9 Channel1 is connected to GPIO TIM_TIM9_LSE TIM9 Channel1 is connected to LSE internal clock TIM_TIM9_GPIO1 TIM9 Channel1 is connected to GPIO TIM_TIM9_GPIO2 TIM9 Channel1 is connected to GPIO TIM_TIM10_TI1RMP TIM10 Channel 1 depends on TI1_RMP TIM_TIM10_RI TIM10 Channel 1 is connected to RI TIM_TIM10_ETR_LSE TIM10 ETR input is connected to LSE clock TIM_TIM10_ETR_TIM9_TGO TIM10 ETR input is connected to TIM9 TGO TIM_TIM10_GPIO TIM10 Channel1 is connected to GPIO TIM_TIM10_LSI TIM10 Channel1 is connected to LSI internal clock TIM_TIM10_LSE TIM10 Channel1 is connected to LSE internal clock TIM_TIM10_RTC TIM10 Channel1 is connected to RTC wakeup interrupt TIM_TIM11_TI1RMP TIM11 Channel 1 depends on TI1_RMP DOCID026682 Rev 3 591/654 HAL TIM Extension Driver TIM_TIM11_RI UM1816 TIM11 Channel 1 is connected to RI TIM_TIM11_ETR_LSE TIM11 ETR input is connected to LSE clock TIM_TIM11_ETR_TIM9_TGO TIM11 ETR input is connected to TIM9 TGO TIM_TIM11_GPIO TIM11 Channel1 is connected to GPIO TIM_TIM11_MSI TIM11 Channel1 is connected to MSI internal clock TIM_TIM11_HSE_RTC TIM11 Channel1 is connected to HSE_RTC clock TIM_TIM11_GPIO1 TIM11 Channel1 is connected to GPIO IS_TIM_REMAP 592/654 DOCID026682 Rev 3 UM1816 HAL UART Generic Driver 43 HAL UART Generic Driver 43.1 HAL UART Generic Driver 43.2 UART Firmware driver registers structures 43.2.1 UART_InitTypeDef Data Fields uint32_t BaudRate uint32_t WordLength uint32_t StopBits uint32_t Parity uint32_t Mode uint32_t HwFlowCtl uint32_t OverSampling Field Documentation uint32_t UART_InitTypeDef::BaudRate This member configures the UART communication baud rate. The baud rate is computed using the following formula:IntegerDivider = ((PCLKx) / (8 * (OVR8+1) * (huart->Init.BaudRate)))FractionalDivider = ((IntegerDivider - ((uint32_t) IntegerDivider)) * 8 * (OVR8+1)) + 0.5 Where OVR8 is the "oversampling by 8 mode" configuration bit in the CR1 register. uint32_t UART_InitTypeDef::WordLength Specifies the number of data bits transmitted or received in a frame. This parameter can be a value of UART_Word_Length uint32_t UART_InitTypeDef::StopBits Specifies the number of stop bits transmitted. This parameter can be a value of UART_Stop_Bits uint32_t UART_InitTypeDef::Parity Specifies the parity mode. This parameter can be a value of UART_Parity Note:When parity is enabled, the computed parity is inserted at the MSB position of the transmitted data (9th bit when the word length is set to 9 data bits; 8th bit when the word length is set to 8 data bits). uint32_t UART_InitTypeDef::Mode Specifies wether the Receive or Transmit mode is enabled or disabled. This parameter can be a value of UART_Mode uint32_t UART_InitTypeDef::HwFlowCtl Specifies wether the hardware flow control mode is enabled or disabled. This parameter can be a value of UART_Hardware_Flow_Control uint32_t UART_InitTypeDef::OverSampling Specifies wether the Over sampling 8 is enabled or disabled, to achieve higher speed (up to fPCLK/8). This parameter can be a value of UART_Over_Sampling DOCID026682 Rev 3 593/654 HAL UART Generic Driver 43.2.2 UM1816 UART_HandleTypeDef Data Fields USART_TypeDef * Instance UART_InitTypeDef Init uint8_t * pTxBuffPtr uint16_t TxXferSize uint16_t TxXferCount uint8_t * pRxBuffPtr uint16_t RxXferSize uint16_t RxXferCount DMA_HandleTypeDef * hdmatx DMA_HandleTypeDef * hdmarx HAL_LockTypeDef Lock __IO HAL_UART_StateTypeDef State __IO uint32_t ErrorCode Field Documentation 594/654 USART_TypeDef* UART_HandleTypeDef::Instance UART registers base address UART_InitTypeDef UART_HandleTypeDef::Init UART communication parameters uint8_t* UART_HandleTypeDef::pTxBuffPtr Pointer to UART Tx transfer Buffer uint16_t UART_HandleTypeDef::TxXferSize UART Tx Transfer size uint16_t UART_HandleTypeDef::TxXferCount UART Tx Transfer Counter uint8_t* UART_HandleTypeDef::pRxBuffPtr Pointer to UART Rx transfer Buffer uint16_t UART_HandleTypeDef::RxXferSize UART Rx Transfer size uint16_t UART_HandleTypeDef::RxXferCount UART Rx Transfer Counter DMA_HandleTypeDef* UART_HandleTypeDef::hdmatx UART Tx DMA Handle parameters DMA_HandleTypeDef* UART_HandleTypeDef::hdmarx UART Rx DMA Handle parameters HAL_LockTypeDef UART_HandleTypeDef::Lock Locking object __IO HAL_UART_StateTypeDef UART_HandleTypeDef::State UART communication state __IO uint32_t UART_HandleTypeDef::ErrorCode UART Error code DOCID026682 Rev 3 UM1816 HAL UART Generic Driver 43.3 UART Firmware driver API description 43.3.1 How to use this driver The UART HAL driver can be used as follows: 1. 2. 3. 4. 5. 6. 7. Declare a UART_HandleTypeDef handle structure. Initialize the UART low level resources by implementing the HAL_UART_MspInit() API: a. Enable the USARTx interface clock. b. UART pins configuration: Enable the clock for the UART GPIOs. Configure the UART pins as alternate function pull-up. c. NVIC configuration if you need to use interrupt process (HAL_UART_Transmit_IT() and HAL_UART_Receive_IT() APIs): Configure the USARTx interrupt priority. Enable the NVIC USART IRQ handle. d. DMA Configuration if you need to use DMA process (HAL_UART_Transmit_DMA() and HAL_UART_Receive_DMA() APIs): Declare a DMA handle structure for the Tx/Rx 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 initialized DMA handle to the UART DMA Tx/Rx handle. Configure the priority and enable the NVIC for the transfer complete interrupt on the DMA Tx/Rx 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) Program the Baud Rate, Word Length, Stop Bit, Parity, Hardware flow control and Mode(Receiver/Transmitter) in the huart Init structure. For the UART asynchronous mode, initialize the UART registers by calling the HAL_UART_Init() API. For the UART Half duplex mode, initialize the UART registers by calling the HAL_HalfDuplex_Init() API. For the LIN mode, initialize the UART registers by calling the HAL_LIN_Init() API. For the Multi-Processor mode, initialize the UART registers by calling the HAL_MultiProcessor_Init() API. The specific UART interrupts (Transmission complete interrupt, RXNE interrupt and Error Interrupts) will be managed using the macros __HAL_UART_ENABLE_IT() and __HAL_UART_DISABLE_IT() inside the transmit and receive process. These APIs (HAL_UART_Init() and HAL_HalfDuplex_Init()) configure also the low level Hardware GPIO, CLOCK, CORTEX...etc) by calling the customed HAL_UART_MspInit() API. Three operation modes are available within this driver : DOCID026682 Rev 3 595/654 HAL UART Generic Driver UM1816 Polling mode IO operation Send an amount of data in blocking mode using HAL_UART_Transmit() Receive an amount of data in blocking mode using HAL_UART_Receive() Interrupt mode IO operation Send an amount of data in non blocking mode using HAL_UART_Transmit_IT() At transmission end of transfer HAL_UART_TxCpltCallback is executed and user can add his own code by customization of function pointer HAL_UART_TxCpltCallback Receive an amount of data in non blocking mode using HAL_UART_Receive_IT() At reception end of transfer HAL_UART_RxCpltCallback is executed and user can add his own code by customization of function pointer HAL_UART_RxCpltCallback In case of transfer Error, HAL_UART_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_UART_ErrorCallback DMA mode IO operation Send an amount of data in non blocking mode (DMA) using HAL_UART_Transmit_DMA() At transmission end of half transfer HAL_UART_TxHalfCpltCallback is executed and user can add his own code by customization of function pointer HAL_UART_TxHalfCpltCallback At transmission end of transfer HAL_UART_TxCpltCallback is executed and user can add his own code by customization of function pointer HAL_UART_TxCpltCallback Receive an amount of data in non blocking mode (DMA) using HAL_UART_Receive_DMA() At reception end of half transfer HAL_UART_RxHalfCpltCallback is executed and user can add his own code by customization of function pointer HAL_UART_RxHalfCpltCallback At reception end of transfer HAL_UART_RxCpltCallback is executed and user can add his own code by customization of function pointer HAL_UART_RxCpltCallback In case of transfer Error, HAL_UART_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_UART_ErrorCallback Pause the DMA Transfer using HAL_UART_DMAPause() Resume the DMA Transfer using HAL_UART_DMAResume() Stop the DMA Transfer using HAL_UART_DMAStop() UART HAL driver macros list Below the list of most used macros in UART HAL driver. 596/654 __HAL_UART_ENABLE: Enable the UART peripheral __HAL_UART_DISABLE: Disable the UART peripheral __HAL_UART_GET_FLAG : Check whether the specified UART flag is set or not __HAL_UART_CLEAR_FLAG : Clear the specified UART pending flag __HAL_UART_ENABLE_IT: Enable the specified UART interrupt __HAL_UART_DISABLE_IT: Disable the specified UART interrupt __HAL_UART_GET_IT_SOURCE: Check whether the specified UART interrupt has occurred or not DOCID026682 Rev 3 UM1816 HAL UART Generic Driver You can refer to the UART HAL driver header file for more useful macros 43.3.2 Initialization and Configuration functions This subsection provides a set of functions allowing to initialize the USARTx or the UARTy in asynchronous mode. For the asynchronous mode only these parameters can be configured: Baud Rate Word Length Stop Bit Parity: If the parity is enabled, then the MSB bit of the data written in the data register is transmitted but is changed by the parity bit. Depending on the frame length defined by the M bit (8-bits or 9-bits), the possible UART frame formats are as listed in Table 19: "OPAMPs inverting/non-inverting inputs for STM32L1 devices" Hardware flow control Receiver/transmitter modes Over Sampling Methode Table 24: UART frame formats M bit PCE bit UART frame 0 0 | SB | 8 bit data | STB | 0 1 | SB | 7 bit data | PB | STB | 1 0 | SB | 9 bit data | STB | 1 1 | SB | 8 bit data | PB | STB | The HAL_UART_Init(), HAL_HalfDuplex_Init(), HAL_LIN_Init() and HAL_MultiProcessor_Init() APIs follow respectively the UART asynchronous, UART Half duplex, LIN and Multi-Processor configuration procedures (details for the procedures are available in reference manual (RM0038)). This section contains the following APIs: 43.3.3 HAL_UART_Init() HAL_HalfDuplex_Init() HAL_LIN_Init() HAL_MultiProcessor_Init() HAL_UART_DeInit() HAL_UART_MspInit() HAL_UART_MspDeInit() IO operation functions This subsection provides a set of functions allowing to manage the UART asynchronous and Half duplex data transfers. 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. DOCID026682 Rev 3 597/654 HAL UART Generic Driver UM1816 2. 3. 4. 5. Non blocking mode: The communication is performed using Interrupts or DMA, these APIs return the HAL status. The end of the data processing will be indicated through the dedicated UART IRQ when using Interrupt mode or the DMA IRQ when using DMA mode. The HAL_UART_TxCpltCallback(), HAL_UART_RxCpltCallback() user callbacks will be executed respectively at the end of the transmit or receive process. The HAL_UART_ErrorCallback() user callback will be executed when a communication error is detected. Blocking mode APIs are: HAL_UART_Transmit() HAL_UART_Receive() Non Blocking mode APIs with Interrupt are: HAL_UART_Transmit_IT() HAL_UART_Receive_IT() HAL_UART_IRQHandler() Non Blocking mode functions with DMA are: HAL_UART_Transmit_DMA() HAL_UART_Receive_DMA() HAL_UART_DMAPause() HAL_UART_DMAResume() HAL_UART_DMAStop() A set of Transfer Complete Callbacks are provided in non blocking mode: HAL_UART_TxHalfCpltCallback() HAL_UART_TxCpltCallback() HAL_UART_RxHalfCpltCallback() HAL_UART_RxCpltCallback() HAL_UART_ErrorCallback() In the Half duplex communication, it is forbidden to run the transmit and receive process in parallel, the UART state HAL_UART_STATE_BUSY_TX_RX can't be useful. This section contains the following APIs: 43.3.4 HAL_UART_Transmit() HAL_UART_Receive() HAL_UART_Transmit_IT() HAL_UART_Receive_IT() HAL_UART_Transmit_DMA() HAL_UART_Receive_DMA() HAL_UART_DMAPause() HAL_UART_DMAResume() HAL_UART_DMAStop() HAL_UART_IRQHandler() HAL_UART_TxCpltCallback() HAL_UART_TxHalfCpltCallback() HAL_UART_RxCpltCallback() HAL_UART_RxHalfCpltCallback() HAL_UART_ErrorCallback() Peripheral Control functions This subsection provides a set of functions allowing to control the UART: 598/654 HAL_LIN_SendBreak() API can be helpful to transmit the break character. DOCID026682 Rev 3 UM1816 HAL UART Generic Driver HAL_MultiProcessor_EnterMuteMode() API can be helpful to enter the UART in mute mode. HAL_MultiProcessor_ExitMuteMode() API can be helpful to exit the UART mute mode by software. HAL_HalfDuplex_EnableTransmitter() API to enable the UART transmitter and disables the UART receiver in Half Duplex mode HAL_HalfDuplex_EnableReceiver() API to enable the UART receiver and disables the UART transmitter in Half Duplex mode This section contains the following APIs: 43.3.5 HAL_LIN_SendBreak() HAL_MultiProcessor_EnterMuteMode() HAL_MultiProcessor_ExitMuteMode() HAL_HalfDuplex_EnableTransmitter() HAL_HalfDuplex_EnableReceiver() Peripheral State and Errors functions This subsection provides a set of functions allowing to return the State of UART communication process, return Peripheral Errors occurred during communication process HAL_UART_GetState() API can be helpful to check in run-time the state of the UART peripheral. HAL_UART_GetError() check in run-time errors that could be occurred during communication. This section contains the following APIs: 43.3.6 43.3.7 HAL_UART_GetState() HAL_UART_GetError() HAL_UART_Init Function Name HAL_StatusTypeDef HAL_UART_Init (UART_HandleTypeDef * huart) Function Description Initializes the UART mode according to the specified parameters in the UART_InitTypeDef and create the associated handle. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_HalfDuplex_Init Function Name HAL_StatusTypeDef HAL_HalfDuplex_Init (UART_HandleTypeDef * huart) Function Description Initializes the half-duplex mode according to the specified parameters in the UART_InitTypeDef and create the associated handle. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status DOCID026682 Rev 3 599/654 HAL UART Generic Driver 43.3.8 UM1816 HAL_LIN_Init Function Name HAL_StatusTypeDef HAL_LIN_Init (UART_HandleTypeDef * huart, uint32_t BreakDetectLength) Function Description Initializes the LIN mode according to the specified parameters in the UART_InitTypeDef and create the associated handle. Parameters Return values 43.3.9 Function Name HAL_StatusTypeDef HAL_MultiProcessor_Init (UART_HandleTypeDef * huart, uint8_t Address, uint32_t WakeUpMethod) Function Description Initializes the Multi-Processor mode according to the specified parameters in the UART_InitTypeDef and create the associated handle. Parameters Return values 43.3.11 600/654 HAL status HAL_MultiProcessor_Init 43.3.10 huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. BreakDetectLength: Specifies the LIN break detection length. This parameter can be one of the following values: UART_LINBREAKDETECTLENGTH_10B: 10-bit break detectionUART_LINBREAKDETECTLENGTH_11B: 11-bit break detection huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Address: UART node address WakeUpMethod: specifies the UART wakeup method. This parameter can be one of the following values: UART_WAKEUPMETHOD_IDLELINE: Wakeup by an idle line detectionUART_WAKEUPMETHOD_ADDRESSMARK: Wakeup by an address mark HAL status HAL_UART_DeInit Function Name HAL_StatusTypeDef HAL_UART_DeInit (UART_HandleTypeDef * huart) Function Description DeInitializes the UART peripheral. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_UART_MspInit Function Name void HAL_UART_MspInit (UART_HandleTypeDef * huart) Function Description UART MSP Init. DOCID026682 Rev 3 UM1816 43.3.12 43.3.13 HAL UART Generic Driver Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values None HAL_UART_MspDeInit Function Name void HAL_UART_MspDeInit (UART_HandleTypeDef * huart) Function Description UART MSP DeInit. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values None HAL_UART_Transmit Function Name HAL_StatusTypeDef HAL_UART_Transmit (UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size, uint32_t Timeout) Function Description Sends an amount of data in blocking mode. Parameters Return values 43.3.14 HAL status HAL_UART_Receive Function Name HAL_StatusTypeDef HAL_UART_Receive (UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size, uint32_t Timeout) Function Description Receives an amount of data in blocking mode. Parameters Return values 43.3.15 huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. pData: Pointer to data buffer Size: Amount of data to be sent Timeout: Timeout duration huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. pData: Pointer to data buffer Size: Amount of data to be received Timeout: Timeout duration HAL status HAL_UART_Transmit_IT Function Name HAL_StatusTypeDef HAL_UART_Transmit_IT (UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size) Function Description Sends an amount of data in non blocking mode. DOCID026682 Rev 3 601/654 HAL UART Generic Driver Parameters Return values 43.3.16 43.3.19 HAL status HAL_StatusTypeDef HAL_UART_Receive_IT (UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size) Function Description Receives an amount of data in non blocking mode. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. pData: Pointer to data buffer Size: Amount of data to be received HAL status HAL_UART_Transmit_DMA Function Name HAL_StatusTypeDef HAL_UART_Transmit_DMA (UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size) Function Description Sends an amount of data in non blocking mode. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. pData: Pointer to data buffer Size: Amount of data to be sent HAL status HAL_UART_Receive_DMA Function Name HAL_StatusTypeDef HAL_UART_Receive_DMA (UART_HandleTypeDef * huart, uint8_t * pData, uint16_t Size) Function Description Receives an amount of data in non blocking mode. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. pData: Pointer to data buffer Size: Amount of data to be received Return values HAL status Notes When the UART parity is enabled (PCE = 1), the received data contain the parity bit (MSB position) HAL_UART_DMAPause Function Name 602/654 Function Name Return values 43.3.18 huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. pData: Pointer to data buffer Size: Amount of data to be sent HAL_UART_Receive_IT Return values 43.3.17 UM1816 HAL_StatusTypeDef HAL_UART_DMAPause DOCID026682 Rev 3 UM1816 HAL UART Generic Driver (UART_HandleTypeDef * huart) 43.3.20 43.3.21 43.3.22 43.3.23 Function Description Pauses the DMA Transfer. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_UART_DMAResume Function Name HAL_StatusTypeDef HAL_UART_DMAResume (UART_HandleTypeDef * huart) Function Description Resumes the DMA Transfer. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_UART_DMAStop Function Name HAL_StatusTypeDef HAL_UART_DMAStop (UART_HandleTypeDef * huart) Function Description Stops the DMA Transfer. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_UART_IRQHandler Function Name void HAL_UART_IRQHandler (UART_HandleTypeDef * huart) Function Description This function handles UART interrupt request. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values None HAL_UART_TxCpltCallback Function Name void HAL_UART_TxCpltCallback (UART_HandleTypeDef * huart) Function Description Tx Transfer completed callbacks. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values None DOCID026682 Rev 3 603/654 HAL UART Generic Driver 43.3.24 43.3.25 43.3.26 43.3.27 43.3.28 604/654 UM1816 HAL_UART_TxHalfCpltCallback Function Name void HAL_UART_TxHalfCpltCallback (UART_HandleTypeDef * huart) Function Description Tx Half Transfer completed callbacks. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values None HAL_UART_RxCpltCallback Function Name void HAL_UART_RxCpltCallback (UART_HandleTypeDef * huart) Function Description Rx Transfer completed callbacks. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values None HAL_UART_RxHalfCpltCallback Function Name void HAL_UART_RxHalfCpltCallback (UART_HandleTypeDef * huart) Function Description Rx Half Transfer completed callbacks. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values None HAL_UART_ErrorCallback Function Name void HAL_UART_ErrorCallback (UART_HandleTypeDef * huart) Function Description UART error callbacks. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values None HAL_LIN_SendBreak Function Name HAL_StatusTypeDef HAL_LIN_SendBreak (UART_HandleTypeDef * huart) Function Description Transmits break characters. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART DOCID026682 Rev 3 UM1816 HAL UART Generic Driver module. Return values 43.3.29 43.3.30 43.3.31 43.3.32 43.3.33 HAL status HAL_MultiProcessor_EnterMuteMode Function Name HAL_StatusTypeDef HAL_MultiProcessor_EnterMuteMode (UART_HandleTypeDef * huart) Function Description Enters the UART in mute mode. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_MultiProcessor_ExitMuteMode Function Name HAL_StatusTypeDef HAL_MultiProcessor_ExitMuteMode (UART_HandleTypeDef * huart) Function Description Exits the UART mute mode: wake up software. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_HalfDuplex_EnableTransmitter Function Name HAL_StatusTypeDef HAL_HalfDuplex_EnableTransmitter (UART_HandleTypeDef * huart) Function Description Enables the UART transmitter and disables the UART receiver. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_HalfDuplex_EnableReceiver Function Name HAL_StatusTypeDef HAL_HalfDuplex_EnableReceiver (UART_HandleTypeDef * huart) Function Description Enables the UART receiver and disables the UART transmitter. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL status HAL_UART_GetState Function Name HAL_UART_StateTypeDef HAL_UART_GetState (UART_HandleTypeDef * huart) DOCID026682 Rev 3 605/654 HAL UART Generic Driver Function Description 43.3.34 UM1816 Returns the UART state. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART module. Return values HAL state HAL_UART_GetError Function Name uint32_t HAL_UART_GetError (UART_HandleTypeDef * huart) Function Description Return the UART error code. Parameters huart: Pointer to a UART_HandleTypeDef structure that contains the configuration information for the specified UART. Return values UART Error Code 43.4 UART Firmware driver defines 43.4.1 UART UART Error Codes HAL_UART_ERROR_NONE No error HAL_UART_ERROR_PE Parity error HAL_UART_ERROR_NE Noise error HAL_UART_ERROR_FE frame error HAL_UART_ERROR_ORE Overrun error HAL_UART_ERROR_DMA DMA transfer error UART Exported Macros __HAL_UART_RESET_HANDLE_STATE Description: Reset UART handle state. Parameters: __HANDLE__: specifies the UART Handle. UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). Return value: __HAL_UART_FLUSH_DRREGISTER None Description: Flush the UART DR register. Parameters: 606/654 DOCID026682 Rev 3 __HANDLE__: specifies the UART Handle. UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y UM1816 HAL UART Generic Driver values depending on device). Description: __HAL_UART_GET_FLAG Check whether the specified UART flag is set or not. Parameters: __HANDLE__: specifies the UART Handle. UART 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: UART_FLAG_CTS: CTS Change flag (not available for UART4 and UART5) UART_FLAG_LBD: LIN Break detection flag UART_FLAG_TXE: Transmit data register empty flag UART_FLAG_TC: Transmission Complete flag UART_FLAG_RXNE: Receive data register not empty flag UART_FLAG_IDLE: Idle Line detection flag UART_FLAG_ORE: OverRun Error flag UART_FLAG_NE: Noise Error flag UART_FLAG_FE: Framing Error flag UART_FLAG_PE: Parity Error flag Return value: __HAL_UART_CLEAR_FLAG The: new state of __FLAG__ (TRUE or FALSE). Description: Clear the specified UART pending flag. Parameters: DOCID026682 Rev 3 __HANDLE__: specifies the UART Handle. UART 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: 607/654 HAL UART Generic Driver UM1816 UART_FLAG_CTS: CTS Change flag (not available for UART4 and UART5). UART_FLAG_LBD: LIN Break detection flag. UART_FLAG_TC: Transmission Complete flag. UART_FLAG_RXNE: Receive data register not empty flag. Return value: None Notes: __HAL_UART_CLEAR_PEFLAG PE (Parity error), FE (Framing error), NE (Noise error), ORE (OverRun error) and IDLE (Idle line detected) flags are cleared by software sequence: a read operation to USART_SR register followed by a read operation to USART_DR register. RXNE flag can be also cleared by a read to the USART_DR register. TC flag can be also cleared by software sequence: a read operation to USART_SR register followed by a write operation to USART_DR register. TXE flag is cleared only by a write to the USART_DR register. Description: Clear the UART PE pending flag. Parameters: __HANDLE__: specifies the UART Handle. UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). Return value: __HAL_UART_CLEAR_FEFLAG None Description: Clear the UART FE pending flag. Parameters: __HANDLE__: specifies the UART Handle. UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). Return value: 608/654 DOCID026682 Rev 3 UM1816 HAL UART Generic Driver __HAL_UART_CLEAR_NEFLAG None Description: Clear the UART NE pending flag. Parameters: __HANDLE__: specifies the UART Handle. UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). Return value: __HAL_UART_CLEAR_OREFLAG None Description: Clear the UART ORE pending flag. Parameters: __HANDLE__: specifies the UART Handle. UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). Return value: __HAL_UART_CLEAR_IDLEFLAG None Description: Clear the UART IDLE pending flag. Parameters: __HANDLE__: specifies the UART Handle. UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). Return value: __HAL_UART_ENABLE_IT None Description: Enable the specified UART interrupt. Parameters: DOCID026682 Rev 3 __HANDLE__: specifies the UART Handle. UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). __INTERRUPT__: specifies the UART interrupt source to enable. This parameter can be one of the following values: 609/654 HAL UART Generic Driver UM1816 UART_IT_CTS: CTS change interrupt UART_IT_LBD: LIN Break detection interrupt UART_IT_TXE: Transmit Data Register empty interrupt UART_IT_TC: Transmission complete interrupt UART_IT_RXNE: Receive Data register not empty interrupt UART_IT_IDLE: Idle line detection interrupt UART_IT_PE: Parity Error interrupt UART_IT_ERR: Error interrupt(Frame error, noise error, overrun error) Return value: __HAL_UART_DISABLE_IT None Description: Disable the specified UART interrupt. Parameters: __HANDLE__: specifies the UART Handle. UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). __INTERRUPT__: specifies the UART interrupt source to disable. This parameter can be one of the following values: UART_IT_CTS: CTS change interrupt UART_IT_LBD: LIN Break detection interrupt UART_IT_TXE: Transmit Data Register empty interrupt UART_IT_TC: Transmission complete interrupt UART_IT_RXNE: Receive Data register not empty interrupt UART_IT_IDLE: Idle line detection interrupt UART_IT_PE: Parity Error interrupt UART_IT_ERR: Error interrupt(Frame error, noise error, overrun error) Return value: 610/654 DOCID026682 Rev 3 UM1816 HAL UART Generic Driver __HAL_UART_GET_IT_SOURCE None Description: Check whether the specified UART interrupt has occurred or not. Parameters: __HANDLE__: specifies the UART Handle. UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). __IT__: specifies the UART interrupt source to check. This parameter can be one of the following values: UART_IT_CTS: CTS change interrupt (not available for UART4 and UART5) UART_IT_LBD: LIN Break detection interrupt UART_IT_TXE: Transmit Data Register empty interrupt UART_IT_TC: Transmission complete interrupt UART_IT_RXNE: Receive Data register not empty interrupt UART_IT_IDLE: Idle line detection interrupt UART_IT_ERR: Error interrupt Return value: __HAL_UART_ONE_BIT_SAMPLE_ENABLE The: new state of __IT__ (TRUE or FALSE). Description: macros to enables or disables the UART's one bit sampling method Parameters: __HANDLE__: specifies the UART Handle. This parameter can be USARTx with x: 1, 2 or 3, or UARTy with y:4 or 5 to select the USART or UART peripheral (availability depending on device for UARTy). Return value: None __HAL_UART_ONE_BIT_SAMPLE_DISABLE __HAL_UART_HWCONTROL_CTS_ENABLE Description: DOCID026682 Rev 3 Enable CTS flow control This macro allows to enable CTS hardware flow control for a given UART instance, 611/654 HAL UART Generic Driver UM1816 without need to call Parameters: __HANDLE__: specifies the UART Handle. This parameter can be any USARTx (supporting the HW Flow control feature). It is used to select the USART peripheral (USART availability and x value depending on device). Return value: None Notes: __HAL_UART_HWCONTROL_CTS_DISABLE As macro is expected to be used for modifying CTS Hw flow control feature activation, without need for USART instance Deinit/Init, following conditions for macro call should be fulfilled : UART instance should have already been initialised (through call of HAL_UART_Init() )macro could only be called when corresponding UART instance is disabled (i.e __HAL_UART_DISABLE(__HANDL E__)) and should be followed by an Enable macro (i.e __HAL_UART_ENABLE(__HANDLE __)). Description: Disable CTS flow control This macro allows to disable CTS hardware flow control for a given UART instance, without need to call Parameters: __HANDLE__: specifies the UART Handle. This parameter can be any USARTx (supporting the HW Flow control feature). It is used to select the USART peripheral (USART availability and x value depending on device). Return value: None Notes: 612/654 DOCID026682 Rev 3 As macro is expected to be used for modifying CTS Hw flow control feature activation, without need for USART instance Deinit/Init, following conditions for macro call should be UM1816 HAL UART Generic Driver fulfilled : UART instance should have already been initialised (through call of HAL_UART_Init() )macro could only be called when corresponding UART instance is disabled (i.e __HAL_UART_DISABLE(__HANDL E__)) and should be followed by an Enable macro (i.e __HAL_UART_ENABLE(__HANDLE __)). __HAL_UART_HWCONTROL_RTS_ENABLE Description: Enable RTS flow control This macro allows to enable RTS hardware flow control for a given UART instance, without need to call Parameters: __HANDLE__: specifies the UART Handle. This parameter can be any USARTx (supporting the HW Flow control feature). It is used to select the USART peripheral (USART availability and x value depending on device). Return value: None Notes: __HAL_UART_HWCONTROL_RTS_DISABLE As macro is expected to be used for modifying RTS Hw flow control feature activation, without need for USART instance Deinit/Init, following conditions for macro call should be fulfilled : UART instance should have already been initialised (through call of HAL_UART_Init() )macro could only be called when corresponding UART instance is disabled (i.e __HAL_UART_DISABLE(__HANDL E__)) and should be followed by an Enable macro (i.e __HAL_UART_ENABLE(__HANDLE __)). Description: Disable RTS flow control This macro allows to disable RTS hardware flow control for a given UART instance, without need to call Parameters: DOCID026682 Rev 3 __HANDLE__: specifies the UART Handle. This parameter can be any 613/654 HAL UART Generic Driver UM1816 USARTx (supporting the HW Flow control feature). It is used to select the USART peripheral (USART availability and x value depending on device). Return value: None Notes: __HAL_UART_ENABLE As macro is expected to be used for modifying RTS Hw flow control feature activation, without need for USART instance Deinit/Init, following conditions for macro call should be fulfilled : UART instance should have already been initialised (through call of HAL_UART_Init() )macro could only be called when corresponding UART instance is disabled (i.e __HAL_UART_DISABLE(__HANDL E__)) and should be followed by an Enable macro (i.e __HAL_UART_ENABLE(__HANDLE __)). Description: Enable UART. Parameters: __HANDLE__: specifies the UART Handle. UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). Return value: __HAL_UART_DISABLE None Description: Disable UART UART Handle selects the USARTx or UARTy peripheral (USART,UART availability and x,y values depending on device). Return value: UART FLags UART_FLAG_CTS UART_FLAG_LBD UART_FLAG_TXE UART_FLAG_TC 614/654 DOCID026682 Rev 3 None UM1816 HAL UART Generic Driver UART_FLAG_RXNE UART_FLAG_IDLE UART_FLAG_ORE UART_FLAG_NE UART_FLAG_FE UART_FLAG_PE UART Hardware Flow Control UART_HWCONTROL_NONE UART_HWCONTROL_RTS UART_HWCONTROL_CTS UART_HWCONTROL_RTS_CTS UART Interrupt Definitions UART_IT_PE UART_IT_TXE UART_IT_TC UART_IT_RXNE UART_IT_IDLE UART_IT_LBD UART_IT_CTS UART_IT_ERR UART LIN Break Detection Length UART_LINBREAKDETECTLENGTH_10B UART_LINBREAKDETECTLENGTH_11B UART Transfer Mode UART_MODE_RX UART_MODE_TX UART_MODE_TX_RX UART Over Sampling UART_OVERSAMPLING_16 UART_OVERSAMPLING_8 UART Parity UART_PARITY_NONE UART_PARITY_EVEN UART_PARITY_ODD UART Private Macros UART_CR1_REG_INDEX DOCID026682 Rev 3 615/654 HAL UART Generic Driver UART_CR2_REG_INDEX UM1816 UART_CR3_REG_INDEX UART_DIV_SAMPLING16 UART_DIVMANT_SAMPLING16 UART_DIVFRAQ_SAMPLING16 UART_BRR_SAMPLING16 UART_DIV_SAMPLING8 UART_DIVMANT_SAMPLING8 UART_DIVFRAQ_SAMPLING8 UART_BRR_SAMPLING8 IS_UART_WORD_LENGTH IS_UART_LIN_WORD_LENGTH IS_UART_STOPBITS IS_UART_PARITY IS_UART_HARDWARE_FLOW_CONTROL IS_UART_MODE IS_UART_STATE IS_UART_OVERSAMPLING IS_UART_LIN_OVERSAMPLING IS_UART_LIN_BREAK_DETECT_LENGTH IS_UART_WAKEUPMETHOD IS_UART_BAUDRATE 32 MHz) divided by the smallest oversampling used on the USART (i.e. 8) Return : TRUE or FALSE IS_UART_ADDRESS This parameter must be a number between Min_Data = 0 and Max_Data = 15 Return : TRUE or FALSE UART_IT_MASK UART State UART_STATE_DISABLE UART_STATE_ENABLE UART Number of Stop Bits UART_STOPBITS_1 UART_STOPBITS_2 UART Wakeup Functions UART_WAKEUPMETHOD_IDLELINE UART_WAKEUPMETHOD_ADDRESSMARK UART Word Length 616/654 DOCID026682 Rev 3 UM1816 HAL UART Generic Driver UART_WORDLENGTH_8B UART_WORDLENGTH_9B DOCID026682 Rev 3 617/654 HAL USART Generic Driver UM1816 44 HAL USART Generic Driver 44.1 HAL USART Generic Driver 44.2 USART Firmware driver registers structures 44.2.1 USART_InitTypeDef Data Fields uint32_t BaudRate uint32_t WordLength uint32_t StopBits uint32_t Parity uint32_t Mode uint32_t CLKPolarity uint32_t CLKPhase uint32_t CLKLastBit Field Documentation 618/654 uint32_t USART_InitTypeDef::BaudRate This member configures the Usart communication baud rate. The baud rate is computed using the following formula:IntegerDivider = ((PCLKx) / (8 * (husart>Init.BaudRate)))FractionalDivider = ((IntegerDivider - ((uint32_t) IntegerDivider)) * 8) + 0.5 uint32_t USART_InitTypeDef::WordLength Specifies the number of data bits transmitted or received in a frame. This parameter can be a value of USART_Word_Length uint32_t USART_InitTypeDef::StopBits Specifies the number of stop bits transmitted. This parameter can be a value of USART_Stop_Bits uint32_t USART_InitTypeDef::Parity Specifies the parity mode. This parameter can be a value of USART_Parity Note:When parity is enabled, the computed parity is inserted at the MSB position of the transmitted data (9th bit when the word length is set to 9 data bits; 8th bit when the word length is set to 8 data bits). uint32_t USART_InitTypeDef::Mode Specifies whether the Receive or Transmit mode is enabled or disabled. This parameter can be a value of USART_Mode uint32_t USART_InitTypeDef::CLKPolarity Specifies the steady state of the serial clock. This parameter can be a value of USART_Clock_Polarity uint32_t USART_InitTypeDef::CLKPhase Specifies the clock transition on which the bit capture is made. This parameter can be a value of USART_Clock_Phase uint32_t USART_InitTypeDef::CLKLastBit Specifies whether the clock pulse corresponding to the last transmitted data bit (MSB) has to be output on the SCLK pin in synchronous mode. This parameter can be a value of USART_Last_Bit DOCID026682 Rev 3 UM1816 44.2.2 HAL USART Generic Driver USART_HandleTypeDef Data Fields USART_TypeDef * Instance USART_InitTypeDef Init uint8_t * pTxBuffPtr uint16_t TxXferSize __IO uint16_t TxXferCount uint8_t * pRxBuffPtr uint16_t RxXferSize __IO uint16_t RxXferCount DMA_HandleTypeDef * hdmatx DMA_HandleTypeDef * hdmarx HAL_LockTypeDef Lock __IO HAL_USART_StateTypeDef State __IO uint32_t ErrorCode Field Documentation USART_TypeDef* USART_HandleTypeDef::Instance USART registers base address USART_InitTypeDef USART_HandleTypeDef::Init Usart communication parameters uint8_t* USART_HandleTypeDef::pTxBuffPtr Pointer to Usart Tx transfer Buffer uint16_t USART_HandleTypeDef::TxXferSize Usart Tx Transfer size __IO uint16_t USART_HandleTypeDef::TxXferCount Usart Tx Transfer Counter uint8_t* USART_HandleTypeDef::pRxBuffPtr Pointer to Usart Rx transfer Buffer uint16_t USART_HandleTypeDef::RxXferSize Usart Rx Transfer size __IO uint16_t USART_HandleTypeDef::RxXferCount Usart Rx Transfer Counter DMA_HandleTypeDef* USART_HandleTypeDef::hdmatx Usart Tx DMA Handle parameters DMA_HandleTypeDef* USART_HandleTypeDef::hdmarx Usart Rx DMA Handle parameters HAL_LockTypeDef USART_HandleTypeDef::Lock Locking object __IO HAL_USART_StateTypeDef USART_HandleTypeDef::State Usart communication state __IO uint32_t USART_HandleTypeDef::ErrorCode USART Error code DOCID026682 Rev 3 619/654 HAL USART Generic Driver UM1816 44.3 USART Firmware driver API description 44.3.1 How to use this driver The USART HAL driver can be used as follows: 1. 2. 3. 4. 5. Declare a USART_HandleTypeDef handle structure. Initialize the USART low level resources by implementing the HAL_USART_MspInit() API: a. Enable the USARTx interface clock. b. USART pins configuration: Enable the clock for the USART GPIOs. Configure the USART pins as alternate function pull-up. c. NVIC configuration if you need to use interrupt process (HAL_USART_Transmit_IT(), HAL_USART_Receive_IT() and HAL_USART_TransmitReceive_IT() APIs): Configure the USARTx interrupt priority. Enable the NVIC USART IRQ handle. d. DMA Configuration if you need to use DMA process (HAL_USART_Transmit_DMA() HAL_USART_Receive_DMA() and HAL_USART_TransmitReceive_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 USART 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) Program the Baud Rate, Word Length, Stop Bit, Parity, Hardware flow control and Mode(Receiver/Transmitter) in the husart Init structure. Initialize the USART registers by calling the HAL_USART_Init() API: These APIs configures also the low level Hardware GPIO, CLOCK, CORTEX...etc) by calling the customed HAL_USART_MspInit(&husart) API. The specific USART interrupts (Transmission complete interrupt, RXNE interrupt and Error Interrupts) will be managed using the macros __HAL_USART_ENABLE_IT() and __HAL_USART_DISABLE_IT() inside the transmit and receive process. Three operation modes are available within this driver : Polling mode IO operation Send an amount of data in blocking mode using HAL_USART_Transmit() Receive an amount of data in blocking mode using HAL_USART_Receive() Interrupt mode IO operation 620/654 Send an amount of data in non blocking mode using HAL_USART_Transmit_IT() DOCID026682 Rev 3 UM1816 HAL USART Generic Driver At transmission end of transfer HAL_USART_TxCpltCallback is executed and user can add his own code by customization of function pointer HAL_USART_TxCpltCallback Receive an amount of data in non blocking mode using HAL_USART_Receive_IT() At reception end of transfer HAL_USART_RxCpltCallback is executed and user can add his own code by customization of function pointer HAL_USART_RxCpltCallback In case of transfer Error, HAL_USART_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_USART_ErrorCallback DMA mode IO operation Send an amount of data in non blocking mode (DMA) using HAL_USART_Transmit_DMA() At transmission end of half transfer HAL_USART_TxHalfCpltCallback is executed and user can add his own code by customization of function pointer HAL_USART_TxHalfCpltCallback At transmission end of transfer HAL_USART_TxCpltCallback is executed and user can add his own code by customization of function pointer HAL_USART_TxCpltCallback Receive an amount of data in non blocking mode (DMA) using HAL_USART_Receive_DMA() At reception end of half transfer HAL_USART_RxHalfCpltCallback is executed and user can add his own code by customization of function pointer HAL_USART_RxHalfCpltCallback At reception end of transfer HAL_USART_RxCpltCallback is executed and user can add his own code by customization of function pointer HAL_USART_RxCpltCallback In case of transfer Error, HAL_USART_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_USART_ErrorCallback Pause the DMA Transfer using HAL_USART_DMAPause() Resume the DMA Transfer using HAL_USART_DMAResume() Stop the DMA Transfer using HAL_USART_DMAStop() USART HAL driver macros list Below the list of most used macros in USART HAL driver. __HAL_USART_ENABLE: Enable the USART peripheral __HAL_USART_DISABLE: Disable the USART peripheral __HAL_USART_GET_FLAG : Check whether the specified USART flag is set or not __HAL_USART_CLEAR_FLAG : Clear the specified USART pending flag __HAL_USART_ENABLE_IT: Enable the specified USART interrupt __HAL_USART_DISABLE_IT: Disable the specified USART interrupt __HAL_USART_GET_IT_SOURCE: Check whether the specified USART interrupt has occurred or not You can refer to the USART HAL driver header file for more useful macros DOCID026682 Rev 3 621/654 HAL USART Generic Driver 44.3.2 UM1816 Initialization and Configuration functions This subsection provides a set of functions allowing to initialize the USART in asynchronous and in synchronous modes. For the asynchronous mode only these parameters can be configured: Baud Rate Word Length Stop Bit Parity: If the parity is enabled, then the MSB bit of the data written in the data register is transmitted but is changed by the parity bit. Depending on the frame length defined by the M bit (8-bits or 9-bits), the possible USART frame formats are as listed in Table 19: "OPAMPs inverting/non-inverting inputs for STM32L1 devices": USART polarity USART phase USART LastBit Receiver/transmitter modes Table 25: USART frame formats M bit PCE bit USART frame 0 0 | SB | 8 bit data | STB | 0 1 | SB | 7 bit data | PB | STB | 1 0 | SB | 9 bit data | STB | 1 1 | SB | 8 bit data | PB | STB | The HAL_USART_Init() function follows the USART synchronous configuration procedure (details for the procedure are available in reference manual (RM0038)). This section contains the following APIs: 44.3.3 HAL_USART_Init() HAL_USART_DeInit() HAL_USART_MspInit() HAL_USART_MspDeInit() IO operation functions This subsection provides a set of functions allowing to manage the USART synchronous data transfers. The USART supports master mode only: it cannot receive or send data related to an input clock (SCLK is always an output). 1. 622/654 There are two modes of transfer: Blocking mode: The communication is performed in polling mode. The HAL status of all data processing is returned by the same function after finishing transfer. No-Blocking mode: The communication is performed using Interrupts or DMA, These API's return the HAL status. The end of the data processing will be indicated through the dedicated USART IRQ when using Interrupt mode or the DMA IRQ when using DMA mode. The HAL_USART_TxCpltCallback(), HAL_USART_RxCpltCallback() and HAL_USART_TxRxCpltCallback() user callbacks will be executed respectively at the end of the transmit or Receive DOCID026682 Rev 3 UM1816 2. 3. 4. 5. HAL USART Generic Driver process The HAL_USART_ErrorCallback() user callback will be executed when a communication error is detected Blocking mode APIs are : HAL_USART_Transmit() in simplex mode HAL_USART_Receive() in full duplex receive only HAL_USART_TransmitReceive() in full duplex mode Non Blocking mode APIs with Interrupt are : HAL_USART_Transmit_IT()in simplex mode HAL_USART_Receive_IT() in full duplex receive only HAL_USART_TransmitReceive_IT() in full duplex mode HAL_USART_IRQHandler() Non Blocking mode functions with DMA are : HAL_USART_Transmit_DMA()in simplex mode HAL_USART_Receive_DMA() in full duplex receive only HAL_USART_TransmitReceive_DMA() in full duplex mode HAL_USART_DMAPause() HAL_USART_DMAResume() HAL_USART_DMAStop() A set of Transfer Complete Callbacks are provided in non Blocking mode: HAL_USART_TxHalfCpltCallback() HAL_USART_TxCpltCallback() HAL_USART_RxHalfCpltCallback() HAL_USART_RxCpltCallback() HAL_USART_ErrorCallback() HAL_USART_TxRxCpltCallback() This section contains the following APIs: 44.3.4 HAL_USART_Transmit() HAL_USART_Receive() HAL_USART_TransmitReceive() HAL_USART_Transmit_IT() HAL_USART_Receive_IT() HAL_USART_TransmitReceive_IT() HAL_USART_Transmit_DMA() HAL_USART_Receive_DMA() HAL_USART_TransmitReceive_DMA() HAL_USART_DMAPause() HAL_USART_DMAResume() HAL_USART_DMAStop() HAL_USART_IRQHandler() HAL_USART_TxCpltCallback() HAL_USART_TxHalfCpltCallback() HAL_USART_RxCpltCallback() HAL_USART_RxHalfCpltCallback() HAL_USART_TxRxCpltCallback() HAL_USART_ErrorCallback() Peripheral State and Errors functions This subsection provides a set of functions allowing to return the State of USART communication process, return Peripheral Errors occurred during communication process HAL_USART_GetState() API can be helpful to check in run-time the state of the USART peripheral. DOCID026682 Rev 3 623/654 HAL USART Generic Driver UM1816 HAL_USART_GetError() check in run-time errors that could be occurred during communication. This section contains the following APIs: 44.3.5 44.3.6 44.3.7 44.3.8 44.3.9 624/654 HAL_USART_GetState() HAL_USART_GetError() HAL_USART_Init Function Name HAL_StatusTypeDef HAL_USART_Init (USART_HandleTypeDef * husart) Function Description Initializes the USART mode according to the specified parameters in the USART_InitTypeDef and create the associated handle. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values HAL status HAL_USART_DeInit Function Name HAL_StatusTypeDef HAL_USART_DeInit (USART_HandleTypeDef * husart) Function Description DeInitializes the USART peripheral. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values HAL status HAL_USART_MspInit Function Name void HAL_USART_MspInit (USART_HandleTypeDef * husart) Function Description USART MSP Init. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values None HAL_USART_MspDeInit Function Name void HAL_USART_MspDeInit (USART_HandleTypeDef * husart) Function Description USART MSP DeInit. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values None HAL_USART_Transmit DOCID026682 Rev 3 UM1816 Function Name HAL USART Generic Driver HAL_StatusTypeDef HAL_USART_Transmit (USART_HandleTypeDef * husart, uint8_t * pTxData, uint16_t Size, uint32_t Timeout) Function Description Simplex Send an amount of data in blocking mode. Parameters Return values 44.3.10 HAL status Function Name HAL_StatusTypeDef HAL_USART_Receive (USART_HandleTypeDef * husart, uint8_t * pRxData, uint16_t Size, uint32_t Timeout) Function Description Full-Duplex Receive an amount of data in blocking mode. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. pRxData: Pointer to data buffer Size: Amount of data to be received Timeout: Timeout duration HAL status HAL_USART_TransmitReceive Function Name HAL_StatusTypeDef HAL_USART_TransmitReceive (USART_HandleTypeDef * husart, uint8_t * pTxData, uint8_t * pRxData, uint16_t Size, uint32_t Timeout) Function Description Full-Duplex Send receive an amount of data in full-duplex mode (blocking mode). Parameters Return values 44.3.12 HAL_USART_Receive Return values 44.3.11 husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. pTxData: Pointer to data buffer Size: Amount of data to be sent Timeout: Timeout duration husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. pTxData: Pointer to data transmitted buffer pRxData: Pointer to data received buffer Size: Amount of data to be sent Timeout: Timeout duration HAL status HAL_USART_Transmit_IT Function Name HAL_StatusTypeDef HAL_USART_Transmit_IT (USART_HandleTypeDef * husart, uint8_t * pTxData, uint16_t Size) Function Description Simplex Send an amount of data in non-blocking mode. DOCID026682 Rev 3 625/654 HAL USART Generic Driver Parameters 44.3.13 husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. pTxData: Pointer to data buffer Size: Amount of data to be sent Return values HAL status Notes The USART errors are not managed to avoid the overrun error. HAL_USART_Receive_IT Function Name HAL_StatusTypeDef HAL_USART_Receive_IT (USART_HandleTypeDef * husart, uint8_t * pRxData, uint16_t Size) Function Description Simplex Receive an amount of data in non-blocking mode. Parameters Return values 44.3.14 husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. pRxData: Pointer to data buffer Size: Amount of data to be received HAL status HAL_USART_TransmitReceive_IT Function Name HAL_StatusTypeDef HAL_USART_TransmitReceive_IT (USART_HandleTypeDef * husart, uint8_t * pTxData, uint8_t * pRxData, uint16_t Size) Function Description Full-Duplex Send receive an amount of data in full-duplex mode (non-blocking). Parameters Return values 44.3.15 UM1816 husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. pTxData: Pointer to data transmitted buffer pRxData: Pointer to data received buffer Size: Amount of data to be received HAL status HAL_USART_Transmit_DMA Function Name HAL_StatusTypeDef HAL_USART_Transmit_DMA (USART_HandleTypeDef * husart, uint8_t * pTxData, uint16_t Size) Function Description Simplex Send an amount of data in non-blocking mode. Parameters 626/654 husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. pTxData: Pointer to data buffer Size: Amount of data to be sent DOCID026682 Rev 3 UM1816 HAL USART Generic Driver Return values 44.3.16 HAL_USART_Receive_DMA Function Name HAL_StatusTypeDef HAL_USART_Receive_DMA (USART_HandleTypeDef * husart, uint8_t * pRxData, uint16_t Size) Function Description Full-Duplex Receive an amount of data in non-blocking mode. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. pRxData: Pointer to data buffer Size: Amount of data to be received Return values HAL status Notes The USART DMA transmit channel must be configured in order to generate the clock for the slave. When the USART parity is enabled (PCE = 1) the data received contain the parity bit. 44.3.17 44.3.18 44.3.19 HAL status HAL_USART_TransmitReceive_DMA Function Name HAL_StatusTypeDef HAL_USART_TransmitReceive_DMA (USART_HandleTypeDef * husart, uint8_t * pTxData, uint8_t * pRxData, uint16_t Size) Function Description Full-Duplex Transmit Receive an amount of data in non-blocking mode. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. pTxData: Pointer to data transmitted buffer pRxData: Pointer to data received buffer Size: Amount of data to be received Return values HAL status Notes When the USART parity is enabled (PCE = 1) the data received contain the parity bit. HAL_USART_DMAPause Function Name HAL_StatusTypeDef HAL_USART_DMAPause (USART_HandleTypeDef * husart) Function Description Pauses the DMA Transfer. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values HAL status HAL_USART_DMAResume DOCID026682 Rev 3 627/654 HAL USART Generic Driver Function Name 44.3.20 44.3.21 44.3.22 44.3.23 628/654 UM1816 HAL_StatusTypeDef HAL_USART_DMAResume (USART_HandleTypeDef * husart) Function Description Resumes the DMA Transfer. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values HAL status HAL_USART_DMAStop Function Name HAL_StatusTypeDef HAL_USART_DMAStop (USART_HandleTypeDef * husart) Function Description Stops the DMA Transfer. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values HAL status HAL_USART_IRQHandler Function Name void HAL_USART_IRQHandler (USART_HandleTypeDef * husart) Function Description This function handles USART interrupt request. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values None HAL_USART_TxCpltCallback Function Name void HAL_USART_TxCpltCallback (USART_HandleTypeDef * husart) Function Description Tx Transfer completed callbacks. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values None HAL_USART_TxHalfCpltCallback Function Name void HAL_USART_TxHalfCpltCallback (USART_HandleTypeDef * husart) Function Description Tx Half Transfer completed callbacks. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. DOCID026682 Rev 3 UM1816 HAL USART Generic Driver Return values 44.3.24 44.3.25 44.3.26 44.3.27 44.3.28 None HAL_USART_RxCpltCallback Function Name void HAL_USART_RxCpltCallback (USART_HandleTypeDef * husart) Function Description Rx Transfer completed callbacks. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values None HAL_USART_RxHalfCpltCallback Function Name void HAL_USART_RxHalfCpltCallback (USART_HandleTypeDef * husart) Function Description Rx Half Transfer completed callbacks. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values None HAL_USART_TxRxCpltCallback Function Name void HAL_USART_TxRxCpltCallback (USART_HandleTypeDef * husart) Function Description Tx/Rx Transfers completed callback for the non-blocking process. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values None HAL_USART_ErrorCallback Function Name void HAL_USART_ErrorCallback (USART_HandleTypeDef * husart) Function Description USART error callbacks. Parameters husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. Return values None HAL_USART_GetState Function Name HAL_USART_StateTypeDef HAL_USART_GetState (USART_HandleTypeDef * husart) Function Description Returns the USART state. DOCID026682 Rev 3 629/654 HAL USART Generic Driver Parameters Return values 44.3.29 UM1816 husart: Pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART module. HAL state HAL_USART_GetError Function Name uint32_t HAL_USART_GetError (USART_HandleTypeDef * husart) Function Description Return the USART error code. Parameters husart: : pointer to a USART_HandleTypeDef structure that contains the configuration information for the specified USART. Return values USART Error Code 44.4 USART Firmware driver defines 44.4.1 USART USART Clock USART_CLOCK_DISABLE USART_CLOCK_ENABLE USART Clock Phase USART_PHASE_1EDGE USART_PHASE_2EDGE USART Clock Polarity USART_POLARITY_LOW USART_POLARITY_HIGH USART Error Codes HAL_USART_ERROR_NONE No error HAL_USART_ERROR_PE Parity error HAL_USART_ERROR_NE Noise error HAL_USART_ERROR_FE frame error HAL_USART_ERROR_ORE Overrun error HAL_USART_ERROR_DMA DMA transfer error USART Exported Macros __HAL_USART_RESET_HANDLE_STATE Description: Reset USART handle state. Parameters: 630/654 DOCID026682 Rev 3 __HANDLE__: specifies the USART Handle. USART Handle selects the USARTx peripheral UM1816 HAL USART Generic Driver (USART availability and x value depending on device). Return value: __HAL_USART_GET_FLAG None Description: Check whether the specified USART flag is set or not. Parameters: __HANDLE__: specifies the USART Handle. USART Handle selects the USARTx peripheral (USART availability and x value depending on device). __FLAG__: specifies the flag to check. This parameter can be one of the following values: USART_FLAG_TXE: Transmit data register empty flag USART_FLAG_TC: Transmission Complete flag USART_FLAG_RXNE: Receive data register not empty flag USART_FLAG_IDLE: Idle Line detection flag USART_FLAG_ORE: OverRun Error flag USART_FLAG_NE: Noise Error flag USART_FLAG_FE: Framing Error flag USART_FLAG_PE: Parity Error flag Return value: __HAL_USART_CLEAR_FLAG The: new state of __FLAG__ (TRUE or FALSE). Description: Clear the specified USART pending flags. Parameters: DOCID026682 Rev 3 __HANDLE__: specifies the USART Handle. USART Handle selects the USARTx peripheral (USART availability and x value depending on device). __FLAG__: specifies the flag to check. This parameter can be any combination of the following values: 631/654 HAL USART Generic Driver UM1816 USART_FLAG_TC: Transmission Complete flag. USART_FLAG_RXNE: Receive data register not empty flag. Return value: None Notes: __HAL_USART_CLEAR_PEFLAG PE (Parity error), FE (Framing error), NE (Noise error), ORE (OverRun error) and IDLE (Idle line detected) flags are cleared by software sequence: a read operation to USART_SR register followed by a read operation to USART_DR register. RXNE flag can be also cleared by a read to the USART_DR register. TC flag can be also cleared by software sequence: a read operation to USART_SR register followed by a write operation to USART_DR register. TXE flag is cleared only by a write to the USART_DR register. Description: Clear the USART PE pending flag. Parameters: __HANDLE__: specifies the USART Handle. USART Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_USART_CLEAR_FEFLAG None Description: Clear the USART FE pending flag. Parameters: __HANDLE__: specifies the USART Handle. USART Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_USART_CLEAR_NEFLAG 632/654 DOCID026682 Rev 3 None Description: UM1816 HAL USART Generic Driver Clear the USART NE pending flag. Parameters: __HANDLE__: specifies the USART Handle. USART Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_USART_CLEAR_OREFLAG None Description: Clear the USART ORE pending flag. Parameters: __HANDLE__: specifies the USART Handle. USART Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_USART_CLEAR_IDLEFLAG None Description: Clear the USART IDLE pending flag. Parameters: __HANDLE__: specifies the USART Handle. USART Handle selects the USARTx peripheral (USART availability and x value depending on device). Return value: __HAL_USART_ENABLE_IT None Description: Enable the specified Usart interrupts. Parameters: DOCID026682 Rev 3 __HANDLE__: specifies the USART Handle. USART Handle selects the USARTx peripheral (USART availability and x value depending on device). __INTERRUPT__: specifies the USART interrupt source to enable. This parameter can be one of the following values: 633/654 HAL USART Generic Driver UM1816 USART_IT_TXE: Transmit Data Register empty interrupt USART_IT_TC: Transmission complete interrupt USART_IT_RXNE: Receive Data register not empty interrupt USART_IT_IDLE: Idle line detection interrupt USART_IT_PE: Parity Error interrupt USART_IT_ERR: Error interrupt(Frame error, noise error, overrun error) Return value: __HAL_USART_DISABLE_IT None Description: Disable the specified Usart interrupts. Parameters: __HANDLE__: specifies the USART Handle. USART Handle selects the USARTx peripheral (USART availability and x value depending on device). __INTERRUPT__: specifies the USART interrupt source to disable. This parameter can be one of the following values: USART_IT_TXE: Transmit Data Register empty interrupt USART_IT_TC: Transmission complete interrupt USART_IT_RXNE: Receive Data register not empty interrupt USART_IT_IDLE: Idle line detection interrupt USART_IT_PE: Parity Error interrupt USART_IT_ERR: Error interrupt(Frame error, noise error, overrun error) Return value: __HAL_USART_GET_IT_SOURCE Description: 634/654 DOCID026682 Rev 3 None C