stm32l4xx_hal_adc.c File Reference

This file provides firmware functions to manage the following functionalities of the Analog to Digital Convertor (ADC) peripheral: + Initialization and de-initialization functions ++ Initialization and Configuration of ADC + Operation functions ++ Start, stop, get result of conversions of regular group, using 3 possible modes: polling, interruption or DMA. + Control functions ++ Channels configuration on regular group ++ Analog Watchdog configuration + State functions ++ ADC state machine management ++ Interrupts and flags management Other functions (extended functions) are available in file "stm32l4xx_hal_adc_ex.c". More...

#include "stm32l4xx_hal.h"

Go to the source code of this file.

Defines
#define	ADC_CFGR_FIELDS_1
#define	ADC_ENABLE_TIMEOUT   ((uint32_t) 2)
#define	ADC_DISABLE_TIMEOUT   ((uint32_t) 2)
#define	ADC_CONVERSION_TIME_MAX_CPU_CYCLES   ((uint32_t) 653U * 4096U * 256U)
Functions
HAL_StatusTypeDef	HAL_ADC_Init (ADC_HandleTypeDef *hadc)
	Initialize the ADC peripheral and regular group according to parameters specified in structure "ADC_InitTypeDef".
HAL_StatusTypeDef	HAL_ADC_DeInit (ADC_HandleTypeDef *hadc)
	Deinitialize the ADC peripheral registers to their default reset values, with deinitialization of the ADC MSP.
__weak void	HAL_ADC_MspInit (ADC_HandleTypeDef *hadc)
	Initialize the ADC MSP.
__weak void	HAL_ADC_MspDeInit (ADC_HandleTypeDef *hadc)
	DeInitialize the ADC MSP.
HAL_StatusTypeDef	HAL_ADC_RegisterCallback (ADC_HandleTypeDef *hadc, HAL_ADC_CallbackIDTypeDef CallbackID, pADC_CallbackTypeDef pCallback)
	Register a User ADC Callback To be used instead of the weak predefined callback.
HAL_StatusTypeDef	HAL_ADC_UnRegisterCallback (ADC_HandleTypeDef *hadc, HAL_ADC_CallbackIDTypeDef CallbackID)
	Unregister a ADC Callback ADC callback is redirected to the weak predefined callback.
HAL_StatusTypeDef	HAL_ADC_Start (ADC_HandleTypeDef *hadc)
	Enable ADC, start conversion of regular group.
HAL_StatusTypeDef	HAL_ADC_Stop (ADC_HandleTypeDef *hadc)
	Stop ADC conversion of regular group (and injected channels in case of auto_injection mode), disable ADC peripheral.
HAL_StatusTypeDef	HAL_ADC_PollForConversion (ADC_HandleTypeDef *hadc, uint32_t Timeout)
	Wait for regular group conversion to be completed.
HAL_StatusTypeDef	HAL_ADC_PollForEvent (ADC_HandleTypeDef *hadc, uint32_t EventType, uint32_t Timeout)
	Poll for ADC event.
HAL_StatusTypeDef	HAL_ADC_Start_IT (ADC_HandleTypeDef *hadc)
	Enable ADC, start conversion of regular group with interruption.
HAL_StatusTypeDef	HAL_ADC_Stop_IT (ADC_HandleTypeDef *hadc)
	Stop ADC conversion of regular group (and injected group in case of auto_injection mode), disable interrution of end-of-conversion, disable ADC peripheral.
HAL_StatusTypeDef	HAL_ADC_Start_DMA (ADC_HandleTypeDef *hadc, uint32_t *pData, uint32_t Length)
	Enable ADC, start conversion of regular group and transfer result through DMA.
HAL_StatusTypeDef	HAL_ADC_Stop_DMA (ADC_HandleTypeDef *hadc)
	Stop ADC conversion of regular group (and injected group in case of auto_injection mode), disable ADC DMA transfer, disable ADC peripheral.
uint32_t	HAL_ADC_GetValue (ADC_HandleTypeDef *hadc)
	Get ADC regular group conversion result.
void	HAL_ADC_IRQHandler (ADC_HandleTypeDef *hadc)
	Handle ADC interrupt request.
__weak void	HAL_ADC_ConvCpltCallback (ADC_HandleTypeDef *hadc)
	Conversion complete callback in non-blocking mode.
__weak void	HAL_ADC_ConvHalfCpltCallback (ADC_HandleTypeDef *hadc)
	Conversion DMA half-transfer callback in non-blocking mode.
__weak void	HAL_ADC_LevelOutOfWindowCallback (ADC_HandleTypeDef *hadc)
	Analog watchdog 1 callback in non-blocking mode.
__weak void	HAL_ADC_ErrorCallback (ADC_HandleTypeDef *hadc)
	ADC error callback in non-blocking mode (ADC conversion with interruption or transfer by DMA).
HAL_StatusTypeDef	HAL_ADC_ConfigChannel (ADC_HandleTypeDef *hadc, ADC_ChannelConfTypeDef *sConfig)
	Configure a channel to be assigned to ADC group regular.
HAL_StatusTypeDef	HAL_ADC_AnalogWDGConfig (ADC_HandleTypeDef *hadc, ADC_AnalogWDGConfTypeDef *AnalogWDGConfig)
	Configure the analog watchdog.
uint32_t	HAL_ADC_GetState (ADC_HandleTypeDef *hadc)
	Return the ADC handle state.
uint32_t	HAL_ADC_GetError (ADC_HandleTypeDef *hadc)
	Return the ADC error code.
HAL_StatusTypeDef	ADC_ConversionStop (ADC_HandleTypeDef *hadc, uint32_t ConversionGroup)
	Stop ADC conversion.
HAL_StatusTypeDef	ADC_Enable (ADC_HandleTypeDef *hadc)
	Enable the selected ADC.
HAL_StatusTypeDef	ADC_Disable (ADC_HandleTypeDef *hadc)
	Disable the selected ADC.
void	ADC_DMAConvCplt (DMA_HandleTypeDef *hdma)
	DMA transfer complete callback.
void	ADC_DMAHalfConvCplt (DMA_HandleTypeDef *hdma)
	DMA half transfer complete callback.
void	ADC_DMAError (DMA_HandleTypeDef *hdma)
	DMA error callback.

---

Detailed Description

This file provides firmware functions to manage the following functionalities of the Analog to Digital Convertor (ADC) peripheral: + Initialization and de-initialization functions ++ Initialization and Configuration of ADC + Operation functions ++ Start, stop, get result of conversions of regular group, using 3 possible modes: polling, interruption or DMA. + Control functions ++ Channels configuration on regular group ++ Analog Watchdog configuration + State functions ++ ADC state machine management ++ Interrupts and flags management Other functions (extended functions) are available in file "stm32l4xx_hal_adc_ex.c".

Author:

MCD Application Team

  ==============================================================================
                     ##### ADC peripheral features #####
  ==============================================================================
  [..]
  (+) 12-bit, 10-bit, 8-bit or 6-bit configurable resolution.

  (+) Interrupt generation at the end of regular 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.
  
  (+) Programmable sampling time (channel wise)
  
  (+) External trigger (timer or EXTI) with configurable polarity
  
  (+) DMA request generation for transfer of conversions data of regular group.
  
  (+) Configurable delay between conversions in Dual interleaved mode.
  
  (+) ADC channels selectable single/differential input.
  
  (+) ADC offset shared on 4 offset instances.
  (+) ADC calibration
  
  (+) ADC conversion of regular group.
  
  (+) ADC supply requirements: 1.62 V to 3.6 V.
  
  (+) 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 ***
     ============================================================
     [..]

    (#) Enable the ADC interface
        (++) As prerequisite, ADC clock must be configured at RCC top level.

        (++) Two clock settings are mandatory: 
             (+++) ADC clock (core clock, also possibly conversion clock).

             (+++) ADC clock (conversions clock).
                   Two possible clock sources: synchronous clock derived from APB clock
                   or asynchronous clock derived from system clock, PLLSAI1 or the PLLSAI2 
                   running up to 80MHz.

             (+++) Example:
                   Into HAL_ADC_MspInit() (recommended code location) or with
                   other device clock parameters configuration:
               (+++) __HAL_RCC_ADC_CLK_ENABLE();                  (mandatory)

               RCC_ADCCLKSOURCE_PLL enable:                       (optional: if asynchronous clock selected)
               (+++) RCC_PeriphClkInitTypeDef   RCC_PeriphClkInit;
               (+++) PeriphClkInit.PeriphClockSelection = RCC_PERIPHCLK_ADC;
               (+++) PeriphClkInit.AdcClockSelection    = RCC_ADCCLKSOURCE_PLL;
               (+++) HAL_RCCEx_PeriphCLKConfig(&PeriphClkInit);

        (++) ADC clock source and clock prescaler are 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)
         (++) 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, group regular, channels parameters ***
     ================================================================
     [..]

    (#) 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 analog watchdog parameters (channels
        monitored, thresholds, ...)
        using function HAL_ADC_AnalogWDGConfig().

     *** Execution of ADC conversions ***
     ====================================
     [..]

    (#) 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()
          (+++) Retrieve conversion results 
                using function HAL_ADC_GetValue()
          (+++) 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)
          (+++) Retrieve conversion results 
                using function HAL_ADC_GetValue()
          (+++) Stop conversion and disable the ADC peripheral 
                using function HAL_ADC_Stop_IT()

        (++) ADC conversion with transfer by DMA:
          (+++) 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()

     [..]

    (@) Callback functions must be implemented in user program:
      (+@) HAL_ADC_ErrorCallback()
      (+@) HAL_ADC_LevelOutOfWindowCallback() (callback of analog watchdog)
      (+@) HAL_ADC_ConvCpltCallback()
      (+@) HAL_ADC_ConvHalfCpltCallback

     *** Deinitialization of ADC ***
     ============================================================
     [..]

    (#) 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:
               (+++) RCC_OscInitStructure.OscillatorType = RCC_OSCILLATORTYPE_HSI14;
               (+++) RCC_OscInitStructure.HSI14State = RCC_HSI14_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)

    (#) 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)

    [..]
    
    *** Callback registration ***
    =============================================
    [..]

     The compilation flag USE_HAL_ADC_REGISTER_CALLBACKS, when set to 1,
     allows the user to configure dynamically the driver callbacks.
     Use Functions @ref HAL_ADC_RegisterCallback()
     to register an interrupt callback.
    [..]

     Function @ref HAL_ADC_RegisterCallback() allows to register following callbacks:
       (+) ConvCpltCallback               : ADC conversion complete callback
       (+) ConvHalfCpltCallback           : ADC conversion DMA half-transfer callback
       (+) LevelOutOfWindowCallback       : ADC analog watchdog 1 callback
       (+) ErrorCallback                  : ADC error callback
       (+) InjectedConvCpltCallback       : ADC group injected conversion complete callback
       (+) InjectedQueueOverflowCallback  : ADC group injected context queue overflow callback
       (+) LevelOutOfWindow2Callback      : ADC analog watchdog 2 callback
       (+) LevelOutOfWindow3Callback      : ADC analog watchdog 3 callback
       (+) EndOfSamplingCallback          : ADC end of sampling callback
       (+) MspInitCallback                : ADC Msp Init callback
       (+) MspDeInitCallback              : ADC Msp DeInit callback
     This function takes as parameters the HAL peripheral handle, the Callback ID
     and a pointer to the user callback function.
    [..]

     Use function @ref HAL_ADC_UnRegisterCallback to reset a callback to the default
     weak function.
    [..]

     @ref HAL_ADC_UnRegisterCallback takes as parameters the HAL peripheral handle,
     and the Callback ID.
     This function allows to reset following callbacks:
       (+) ConvCpltCallback               : ADC conversion complete callback
       (+) ConvHalfCpltCallback           : ADC conversion DMA half-transfer callback
       (+) LevelOutOfWindowCallback       : ADC analog watchdog 1 callback
       (+) ErrorCallback                  : ADC error callback
       (+) InjectedConvCpltCallback       : ADC group injected conversion complete callback
       (+) InjectedQueueOverflowCallback  : ADC group injected context queue overflow callback
       (+) LevelOutOfWindow2Callback      : ADC analog watchdog 2 callback
       (+) LevelOutOfWindow3Callback      : ADC analog watchdog 3 callback
       (+) EndOfSamplingCallback          : ADC end of sampling callback
       (+) MspInitCallback                : ADC Msp Init callback
       (+) MspDeInitCallback              : ADC Msp DeInit callback
     [..]

     By default, after the @ref HAL_ADC_Init() and when the state is @ref HAL_ADC_STATE_RESET
     all callbacks are set to the corresponding weak functions:
     examples @ref HAL_ADC_ConvCpltCallback(), @ref HAL_ADC_ErrorCallback().
     Exception done for MspInit and MspDeInit functions that are
     reset to the legacy weak functions in the @ref HAL_ADC_Init()/ @ref HAL_ADC_DeInit() only when
     these callbacks are null (not registered beforehand).
    [..]

     If MspInit or MspDeInit are not null, the @ref HAL_ADC_Init()/ @ref HAL_ADC_DeInit()
     keep and use the user MspInit/MspDeInit callbacks (registered beforehand) whatever the state.
     [..]

     Callbacks can be registered/unregistered in @ref HAL_ADC_STATE_READY state only.
     Exception done MspInit/MspDeInit functions that can be registered/unregistered
     in @ref HAL_ADC_STATE_READY or @ref HAL_ADC_STATE_RESET state,
     thus registered (user) MspInit/DeInit callbacks can be used during the Init/DeInit.
    [..]

     Then, the user first registers the MspInit/MspDeInit user callbacks
     using @ref HAL_ADC_RegisterCallback() before calling @ref HAL_ADC_DeInit()
     or @ref HAL_ADC_Init() function.
     [..]

     When the compilation flag USE_HAL_ADC_REGISTER_CALLBACKS is set to 0 or
     not defined, the callback registration feature is not available and all callbacks
     are set to the corresponding weak functions.
  
  

Attention:

© COPYRIGHT(c) 2017 STMicroelectronics

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of STMicroelectronics nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Definition in file stm32l4xx_hal_adc.c.