LL ADC Macros

Common write and read registers macro

group ADC_LL_EM_WRITE_READ

Defines

LL_ADC_WRITE_REG ( instance , reg , value ) STM32_WRITE_REG((instance)->reg, (value))

Write a value in ADC register.

Parameters :

  • instance – ADC Instance

  • reg – Register to be written

  • value – Value to be written in the register

LL_ADC_READ_REG ( instance , reg ) STM32_READ_REG((instance)->reg)

Read a value in ADC register.

Parameters :

  • instance – ADC Instance

  • reg – Register to be read

Return values :

Register – value

ADC helper macro

group ADC_LL_EM_HELPER_MACRO

Defines

LL_ADC_CHANNEL_TO_DECIMAL_NB ( channel ) ((channel) & LL_ADC_CH_NUMBER_MASK )

Helper macro to get ADC channel number in decimal format from literals LL_ADC_CHANNEL_x.

Note

Example: LL_ADC_CHANNEL_TO_DECIMAL_NB(LL_ADC_CHANNEL_4) will return decimal number “4”.

Note

The input can be a value from functions where a channel number is returned, either defined with number or with bitfield (only one bit must be set).

Parameters :
Return values :

Value – between Min_Data=0 and Max_Data=13

LL_ADC_DECIMAL_NB_TO_CHANNEL ( decimal_nb ) (decimal_nb)

Helper macro to get ADC channel in literal format LL_ADC_CHANNEL_x from number in decimal format.

Note

Example: LL_ADC_DECIMAL_NB_TO_CHANNEL(4) will return a data equivalent to “LL_ADC_CHANNEL_4”.

Return values :
LL_ADC_IS_CHANNEL_INTERNAL ( channel ) (((channel) & LL_ADC_CH_INTERNAL_MASK ) != 0UL)

Helper macro to determine whether the selected channel corresponds to literal definitions of driver.

Note

The different literal definitions of ADC channels are:

  • ADC internal channel: LL_ADC_CHANNEL_VREFINT, LL_ADC_CHANNEL_TEMPSENSOR, …

  • ADC external channel (channel connected to a GPIO pin): LL_ADC_CHANNEL_1, LL_ADC_CHANNEL_2, …

Note

The channel parameter must be a value defined from literal definition of a ADC internal channel (LL_ADC_CHANNEL_VREFINT, LL_ADC_CHANNEL_TEMPSENSOR, …), ADC external channel (LL_ADC_CHANNEL_1, LL_ADC_CHANNEL_2, …), must not be a value from functions where a channel number is returned from ADC registers, because internal and external channels share the same channel number in ADC registers. The differentiation is made only with parameters definitions of driver.

Parameters :
Return values :

Value – “0” if the channel corresponds to a parameter definition of a ADC external channel (channel connected to a GPIO pin). Value “1” if the channel corresponds to a parameter definition of a ADC internal channel.

LL_ADC_CHANNEL_INTERNAL_TO_EXTERNAL ( channel ) ((channel) & LL_ADC_CH_NUMBER_MASK )

Helper macro to convert a channel defined from parameter definition of a ADC internal channel (LL_ADC_CHANNEL_VREFINT, LL_ADC_CHANNEL_TEMPSENSOR, …), to its equivalent parameter definition of a ADC external channel (LL_ADC_CHANNEL_1, LL_ADC_CHANNEL_2, …).

Note

The channel parameter can be, additionally to a value defined from parameter definition of a ADC internal channel (LL_ADC_CHANNEL_VREFINT, LL_ADC_CHANNEL_TEMPSENSOR, …), a value defined from parameter definition of ADC external channel (LL_ADC_CHANNEL_1, LL_ADC_CHANNEL_2, …) or a value from functions where a channel number is returned from ADC registers.

Parameters :
Return values :

Returned – value can be one of the following values:

LL_ADC_DECIMAL_NB_TO_REG_SEQ_LENGTH ( decimal_nb ) (((decimal_nb) - 1UL) << ADC_SQR1_LEN_Pos)

Helper macro to get ADC group regular sequencer length in literal format LL_ADC_REG_SEQ_SCAN_x from number in decimal format.

Note

Example: LL_ADC_DECIMAL_NB_TO_REG_SEQ_LENGTH(4) will return a data equivalent to “LL_ADC_REG_SEQ_SCAN_ENABLE_4RANKS”.

Parameters :

  • decimal_nb – Value between Min_Data=1 and Max_Data=16 for ADC1 or ADC2

Return values :

Returned – value can be one of the following values:

LL_ADC_REG_SEQ_LENGTH_TO_DECIMAL_NB ( seq_length ) (((seq_length) >> ADC_SQR1_LEN_Pos) + 1UL)

Helper macro to get ADC group regular sequencer length in decimal format from literal format LL_ADC_REG_SEQ_SCAN_x.

Note

Example: LL_ADC_REG_SEQ_LENGTH_TO_DECIMAL_NB(LL_ADC_REG_SEQ_SCAN_ENABLE_4RANKS) will return decimal number “4”.

Parameters :
Return values :

Value – between Min_Data=1 and Max_Data=16

LL_ADC_DECIMAL_NB_TO_INJ_SEQ_LENGTH ( decimal_nb ) (((decimal_nb) << ADC_JSQR_JLEN_Pos) - 1UL)

Helper macro to get ADC group injected sequencer length in literal format LL_ADC_INJ_SEQ_SCAN_x from number in decimal format.

Note

Example: LL_ADC_DECIMAL_NB_TO_REG_SEQ_LENGTH(4) will return a data equivalent to “LL_ADC_REG_SEQ_SCAN_ENABLE_4RANKS”.

Parameters :

  • decimal_nb – Value between Min_Data=1 and Max_Data=4.

Return values :

Returned – value can be one of the following values:

LL_ADC_INJ_SEQ_LENGTH_TO_DECIMAL_NB ( seq_length ) (((seq_length) >> ADC_JSQR_JLEN_Pos) + 1UL)

Helper macro to get ADC group injected sequencer length in decimal format from literal format LL_ADC_REG_SEQ_SCAN_x.

Note

Example: LL_ADC_REG_SEQ_LENGTH_TO_DECIMAL_NB(LL_ADC_INJ_SEQ_SCAN_ENABLE_4RANKS) will return decimal number “4”.

Parameters :
Return values :

Value – between Min_Data=1 and Max_Data=4.

LL_ADC_DECIMAL_NB_TO_REG_SEQ_RANK ( decimal_nb ) ((((decimal_nb) / 5UL) << LL_ADC_SQRX_REGOFFSET_POS ) | (((decimal_nb) % 5UL ) * 6UL))

Helper macro to get ADC group regular sequencer rank in literal format LL_ADC_REG_RANK_x from number in decimal format.

Note

Example: LL_ADC_DECIMAL_NB_TO_REG_SEQ_LENGTH(2) will return a data equivalent to “LL_ADC_REG_RANK_2”.

Parameters :

  • decimal_nb – Value between Min_Data=1 and Max_Data=16

Return values :

Returned – value can be one of the following values:

LL_ADC_REG_SEQ_RANK_TO_DECIMAL_NB ( seq_length ) ((((seq_length) >> LL_ADC_SQRX_REGOFFSET_POS ) * 5UL) + (((seq_length) & LL_ADC_REG_RANK_ID_SQRX_MASK ) / 6UL))

Helper macro to get ADC group regular sequencer rank in decimal format from literal format LL_ADC_REG_RANK_x.

Note

Example: LL_ADC_REG_SEQ_RANK_TO_DECIMAL_NB(LL_ADC_REG_RANK_2) will return decimal number “2”.

Parameters :
Return values :

Value – between Min_Data=1 and Max_Data=16

LL_ADC_DECIMAL_NB_TO_INJ_SEQ_RANK ( decimal_nb ) ((((decimal_nb) - 1UL) << ( LL_ADC_JDRX_REGOFFSET_POS )) | (((decimal_nb) * 6UL) + 3UL))

Helper macro to get ADC group injected sequencer rank in literal format LL_ADC_INJ_RANK_x from number in decimal format.

Parameters :

  • decimal_nb – Value between Min_Data=1 and Max_Data=16

Return values :

Returned – value can be one of the following values:

LL_ADC_INJ_SEQ_RANK_TO_DECIMAL_NB ( seq_length ) ((((seq_length) & LL_ADC_INJ_RANK_ID_JSQR_MASK ) - 3UL) / 6UL)

Helper macro to get ADC group injected sequencer rank in decimal format from literal format LL_ADC_INJ_RANK_x.

Note

Example: LL_ADC_INJ_SEQ_RANK_TO_DECIMAL_NB(LL_ADC_INJ_RANK_2) will return decimal number “2”.

Parameters :
Return values :

Value – between Min_Data=1 and Max_Data=16

LL_ADC_OVS_SHIFT_KEEP_RES ( ovs_ratio_decimal ) (STM32_POSITION_VAL(ovs_ratio_decimal))

Helper macro to get ADC oversampling right bit shift value in function of ratio to have oversampling data keeping current resolution (example: to keep data resolution, ratio x8 requires right shift of 3 bits).

Note

Example: LL_ADC_OVS_SHIFT_KEEP_RES(8) will return decimal number “3”.

Parameters :

  • ovs_ratio_decimal – Value power of 2 (1, 2, 4, 8, 16, …) between Min_Data=1 and Max_Data=1024

Return values :

Value – between Min_Data=1 and Max_Data=11

LL_ADC_ANALOGWD_SET_THRESHOLD_RES ( resolution , awd_threshold ) (uint32_t)(((uint32_t)(awd_threshold)) << ((resolution) >> (ADC_CFGR1_RES_Pos - 1U)))

Helper macro to set the value of ADC analog watchdog threshold high or low in function of ADC resolution, when ADC resolution is different of default resolution (12 bit).

Note

To be used with function LL_ADC_SetAnalogWDThresholds(). Example, with a ADC resolution of 8 bits, to set the value of analog watchdog threshold high (on 8 bits): LL_ADC_SetAnalogWDThresholds (< ADCx param >, LL_ADC_ANALOGWD_SET_THRESHOLD_RES(LL_ADC_RESOLUTION_8B, <threshold_value_8_bits>));

Parameters :

  • resolution – This parameter can be one of the following values:

  • awd_threshold – Analog watchdog threshold value. Value is signed and can exceed ADC resolution with post-processing computation (offset, oversampling, data shift, …). Value between Min_Data=-4194304 (two’s complement 0xFFC00000) and Max_Data=+4194303 (0x003FFFFF)

Return values :

Value – is represented as unsigned for intermediate computation but is formatted as signed and can exceed ADC resolution with post-processing computation (offset, oversampling, data shift, …): to be casted to signed 32 bits.

LL_ADC_ANALOGWD_GET_THRESHOLD_RES ( resolution , awd_threshold )

(uint32_t)((((uint32_t)(awd_threshold)) >> ((resolution) >> (ADC_CFGR1_RES_Pos - 1U))) \

| (((uint32_t)(awd_threshold)) & (~ADC_AWD1LTR_LTR)))


Helper macro to get the value of ADC analog watchdog threshold high or low in function of ADC resolution, when ADC resolution is different of 12 bits.

Note

To be used with function LL_ADC_GetAnalogWDThresholds(). Example, with a ADC resolution of 8 bits, to get the value of analog watchdog threshold high (on 8 bits): < threshold_value_6_bits > = LL_ADC_ANALOGWD_GET_THRESHOLD_RES (LL_ADC_RESOLUTION_8B, LL_ADC_GetAnalogWDThresholds(<ADCx param>, LL_ADC_AWD_THRESHOLD_HIGH) );

Parameters :

  • resolution – This parameter can be one of the following values:

  • awd_threshold – Analog watchdog threshold value. Value is signed and can exceed ADC resolution with post-processing computation (offset, oversampling, data shift, …). Value between Min_Data=-4194304 (two’s complement 0xFFC00000) and Max_Data=+4194303 (0x003FFFFF)

Return values :

Value – is represented as unsigned for intermediate computation but is formatted as signed and can exceed ADC resolution with post-processing computation (offset, oversampling, data shift, …): to be casted to signed 32 bits.

LL_ADC_OFFSET_SET_LEVEL_RES ( resolution , offset_level ) ((offset_level) << ((resolution) >> (ADC_CFGR1_RES_Pos - 1U)))

Helper macro to set the value of ADC offset level in function of ADC resolution, when ADC resolution is different of default resolution.

Note

To be used with function LL_ADC_SetOffsetLevel(). Example, with a ADC resolution of 8 bits, to set the value of analog watchdog threshold high (on 8 bits): LL_ADC_SetOffset (< ADCx param >, LL_ADC_OFFSET_SET_LEVEL_RES(LL_ADC_RESOLUTION_8B, <offset_level_8_bits>));

Parameters :
Return values :

Value – between Min_Data=0x00000000 and Max_Data=0x003FFFFF

LL_ADC_OFFSET_GET_LEVEL_RES ( resolution , offset_level ) ((offset_level) >> ((resolution) >> (ADC_CFGR1_RES_Pos - 1U)))

Helper macro to get the value of ADC offset level in function of ADC resolution, when ADC resolution is different of default resolution.

Note

To be used with function LL_ADC_GetOffset(). Example, with a ADC resolution of 8 bits, to set the value of analog watchdog threshold high (on 8 bits): LL_ADC_GetOffsetLevel (< ADCx param >, LL_ADC_OFFSET_SET_LEVEL_RES(LL_ADC_RESOLUTION_8B, <offset_level_8_bits>));

Parameters :
Return values :

Value – between Min_Data=0x00000000 and Max_Data=0x003FFFFF

LL_ADC_CALIB_FACTOR_SINGLE_DIFF ( calib_factor_single_ended , calib_factor_differential ) (((calib_factor_differential) << ADC_CALFACT_CALFACT_D_Pos) | (calib_factor_single_ended))

Helper macro to set the ADC calibration value with both single ended and differential modes calibration factors concatenated.

Note

To be used with function LL_ADC_SetCalibrationFactor()

. Example, to set calibration factors single ended to 0x55 and differential ended to 0x2A: LL_ADC_SetCalibrationFactor(

ADC1,

LL_ADC_CALIB_FACTOR_SINGLE_DIFF(0x55, 0x2A))

Parameters :

  • calib_factor_single_ended – Value between Min_Data=0x00 and Max_Data=0x7F

  • calib_factor_differential – Value between Min_Data=0x00 and Max_Data=0x7F

Return values :

Value – between Min_Data=0x00000000 and Max_Data=0xFFFFFFFF

LL_ADC_MULTI_CONV_DATA_MASTER_SLAVE ( adc_multi_master_slave , adc_multi_conv_data ) (((adc_multi_conv_data) >> ((ADCC_CDR_RDATA_SLV_Pos) & ~(adc_multi_master_slave))) & ADCC_CDR_RDATA_MST)

Helper macro to get the ADC multimode conversion data of ADC master or ADC slave from raw value with both ADC conversion data concatenated (unpack multimode conversion data).

Note

This macro is intended to be used when multimode transfer by DMA is enabled (refer to function LL_ADC_SetMultiDMATransfer()) and data retrieved from CDR (not CDR2). In this case the transferred data needs to be processed with this macro to separate the conversion data of ADC master and ADC slave.

Parameters :

  • adc_multi_master_slave – This parameter can be one of the following values:

  • adc_multi_conv_data – Value between Min_Data=0x0000 and Max_Data=0xFFFF

Return values :

Value – between Min_Data=0x0000 and Max_Data=0xFFFF

LL_ADC_DIGITAL_SCALE ( resolution ) (0xFFFUL >> ((resolution) >> (ADC_CFGR1_RES_Pos - 1UL)))

Helper macro to define the ADC conversion data full-scale digital maximum value corresponding to the selected ADC resolution.

Note

ADC conversion data full-scale corresponds to voltage range determined by analog voltage references Vref+ and Vref- (refer to reference manual).

Note

Value returned corresponds to range maximum value without post-processing computation. With post-processing (offset, gain), conversion data maximum value can exceed this range (as well as minimum value in negative range).

Parameters :
Return values :

ADC – conversion data full-scale digital value (unit: digital value of ADC conversion data)

LL_ADC_CONVERT_DATA_RESOLUTION ( data , adc_res_current , adc_res_target )

((((int32_t)(data)) * (int32_t)64L) \

/ (int32_t)((uint32_t)(1UL << (2U * ((3U + ((adc_res_target) >> ADC_CFGR1_RES_Pos)) \

- ((adc_res_current) >> ADC_CFGR1_RES_Pos))))))


Helper macro to convert the ADC conversion data from a resolution to another resolution.

Note

Arguments data type converted to signed (int32_t) to handle all possible input values (conversion data can be negative after post-processing computation: offset feature).

Note

Processing of negative values: Computation with numerical values power of two instead of binary shift for explicit sign management (arithmetic shift instead of logical shift).

Parameters :
Return values :

ADC – conversion data to the requested resolution

LL_ADC_CALC_DATA_TO_VOLTAGE ( vref_analog_voltage , conv_data , resolution )

((int32_t)(conv_data) * (int32_t)(vref_analog_voltage) \

/ (int32_t)(

LL_ADC_DIGITAL_SCALE (resolution)))

Helper macro to calculate the voltage (unit: mVolt) corresponding to a ADC conversion data (unit: digital value).

Note

Analog reference voltage (Vref+) must be either known from user board environment or can be calculated using ADC measurement and ADC helper macro LL_ADC_CALC_VREFANALOG_VOLTAGE().

Note

Arguments data type converted to signed (int32_t) to handle all possible input values (conversion data can be negative after post-processing computation: offset feature).

Parameters :
Return values :

ADC – conversion data equivalent voltage value (unit: mVolt).

LL_ADC_CALC_VOLTAGE_TO_DATA ( vref_analog_voltage , voltage_mv , resolution ) ((int32_t)(voltage_mv) * (int32_t)( LL_ADC_DIGITAL_SCALE

(resolution)) \

/ (int32_t)(vref_analog_voltage))


Helper macro to calculate the ADC conversion data (unit: digital value) corresponding to a voltage (unit: mVolt).

Note

Analog reference voltage (Vref+) must be either known from user board environment or can be calculated using ADC measurement and ADC helper macro LL_ADC_CALC_VREFANALOG_VOLTAGE().

Note

Arguments data type converted to signed (int32_t) to handle all possible input values (conversion data can be negative after post-processing computation: offset feature)

Parameters :
Return values :

ADC – conversion data equivalent value (unit: digital value)

LL_ADC_CALC_VREFANALOG_VOLTAGE ( vrefint_conv_data , resolution ) ((((uint32_t)* LL_ADC_VREFINT_CAL_ADDR ) * (uint32_t) LL_ADC_VREFINT_CAL_VREF

) \

/ (uint32_t)

LL_ADC_CONVERT_DATA_RESOLUTION

((vrefint_conv_data), \

(resolution), \

LL_ADC_RESOLUTION_12B ))

Helper macro to calculate analog reference voltage (Vref+) (unit: mVolt) from ADC conversion data of internal voltage reference VrefInt.

Note

Computation is using VrefInt calibration value stored in system memory for each device during production.

Note

This voltage depends on user board environment: voltage level connected to pin Vref+. On devices with small package, the pin Vref+ is not present and internally bonded to pin Vdda.

Parameters :
Return values :

Analog – reference voltage Vref+ value (unit: mVolt)

Functions

int32_t LL_ADC_CALC_TEMPERATURE ( uint32_t vref_analog_voltage , uint32_t tempsensor_conv_data , uint32_t resolution )

Helper macro to calculate the temperature (unit: degree Celsius) from ADC conversion data of internal temperature sensor.

Note

Computation is using temperature sensor calibration values stored in system memory for each device during production.

Note

Calculation formula: Temperature = ((TS_ADC_DATA - TS_CAL1)

  • (TS_CAL2_TEMP - TS_CAL1_TEMP)) / (TS_CAL2 - TS_CAL1) + TS_CAL1_TEMP with TS_ADC_DATA = temperature sensor raw data measured by ADC Avg_Slope = (TS_CAL2 - TS_CAL1) / (TS_CAL2_TEMP - TS_CAL1_TEMP) TS_CAL1 = equivalent TS_ADC_DATA at temperature TEMP_DEGC_CAL1 (calibrated in factory) TS_CAL2 = equivalent TS_ADC_DATA at temperature TEMP_DEGC_CAL2 (calibrated in factory) Caution: Calculation relevancy under reserve that calibration parameters are correct (address and data). To calculate temperature using temperature sensor datasheet typical values (generic values less, therefore less accurate than calibrated values), use helper macro LL_ADC_CALC_TEMPERATURE_TYP_PARAMS().

Note

Analog reference voltage (Vref+) must be either known from user board environment or can be calculated using ADC measurement and ADC helper macro LL_ADC_CALC_VREFANALOG_VOLTAGE().

Parameters :
Return values :

Temperature – (unit: degree Celsius) or error code (value LL_ADC_TEMPERATURE_CALC_ERROR)

int32_t LL_ADC_CALC_TEMPERATURE_TYP_PARAMS ( int32_t tempsensor_typ_avg_slope , uint32_t tempsensor_typ_calx_v , int32_t tempsensor_calx_temp , uint32_t vref_analog_voltage , uint32_t tempsensor_conv_data , uint32_t resolution )

Helper macro to calculate the temperature (unit: degree Celsius) from ADC conversion data of internal temperature sensor.

Note

Computation is using temperature sensor typical values (refer to device datasheet).

Note

Calculation formula: Temperature = (TS_TYP_CALx_VOLT(uV) - TS_ADC_DATA * Conversion_uV) / Avg_Slope + CALx_TEMP with TS_ADC_DATA = temperature sensor raw data measured by ADC (unit: digital value) Avg_Slope = temperature sensor slope (unit: uV/Degree Celsius) TS_TYP_CALx_VOLT = temperature sensor digital value at temperature CALx_TEMP (unit: mVolt) Caution: Calculation relevancy under reserve the temperature sensor of the current device has characteristics in line with datasheet typical values. If temperature sensor calibration values are available on on this device (presence of macro LL_ADC_CALC_TEMPERATURE()), temperature calculation will be more accurate using helper macro LL_ADC_CALC_TEMPERATURE().

Note

Analog reference voltage (Vref+) must be either known from user board environment or can be calculated using ADC measurement and ADC helper macro LL_ADC_CALC_VREFANALOG_VOLTAGE().

Parameters :

  • tempsensor_typ_avg_slope – Device datasheet data: Temperature sensor slope typical value (unit: uV/DegCelsius). On this STM32 series, refer to device datasheet parameter “Avg_Slope”.

  • tempsensor_typ_calx_v – Device datasheet data: Temperature sensor voltage typical value (at temperature and Vref+ defined in parameters below) (unit: mVolt). On this STM32 series, refer to device datasheet parameter “V30” (corresponding to TS_CAL1).

  • tempsensor_calx_temp – Device datasheet data: Temperature at which temperature sensor voltage see parameter above) is corresponding (unit: mVolt)

  • vref_analog_voltage – Analog reference voltage Vref+ (unit: mVolt)

  • tempsensor_conv_data – ADC conversion data of internal temperature sensor (unit: digital value).

  • resolution – ADC resolution at which ADC conversion has been performed This parameter can be one of the following values:

Return values :

Temperature – (unit: degree Celsius)