Enhanced control services

The changes described in this section strengthen the HAL-over-LL layering by replacing HAL RCC clock enable/disable macros with static inline functions. Additionally, users gain finer control over interrupts involved in asynchronous interrupt- and DMA-based processes.

RCC clock macros converted to inline functions

In HAL2, RCC clock enable and disable macros for peripherals are replaced by static inline functions. For users, this change mainly involves renaming.

The benefits of this conversion include improved debugging by avoiding macros and strengthening the HAL-over-LL layering, as the new inline functions wrap the corresponding LL RCC function.

Example of RCC clock macro to inline function conversion

HAL1

HAL2 

#define __HAL_RCC_TIM1_CLK_ENABLE() ..

#define __HAL_RCC_TIM1_CLK_DISABLE() ..

#define __HAL_RCC_TIM1_IS_CLK_ENABLED() ..

__STATIC_INLINE void HAL_RCC_TIM1_EnableClock(void)

__STATIC_INLINE void HAL_RCC_TIM1_DisableClock(void)

__STATIC_INLINE hal_rcc_clk_status_t HAL_RCC_TIM1_IsEnabledClock(void)

New APIs for filtering optional asynchronous process interrupts

Conventional asynchronous HAL peripheral processes (interrupt- and DMA-based) typically enable all related interrupts, including mandatory ones, such as transfer complete, and optional informative ones, such as half transfer. HAL2 retains these APIs with the same behavior but adds new APIs that allow users to filter optional interrupts selectively. Additionally, for analog peripherals like ADC, DAC, and TIM, HAL2 introduces a silent asynchronous mode: a nonblocking circular DMA mode without any interrupt signaling.

The tables below show an example of these filtering APIs in HAL1 and HAL2 for UART and ADC.

UART filtering APIs in HAL1 and HAL2

HAL1

HAL2 

/*
  Conventional HAL UART Transmit API
  in interrupt based model
*/
HAL_StatusTypeDef HAL_UART_Transmit_IT(UART_HandleTypeDef *huart,
                                       const uint8_t *pData,
                                       uint16_t Size);

/*
  Conventional HAL UART Transmit API
  in interrupt based model
*/
hal_status_t HAL_UART_Transmit_IT(hal_uart_handle_t *huart,
                                  const void *p_data,
                                  uint32_t size_byte);

/* None */

/*
  New HAL UART Transmit API
  with interrupt filtering capability
*/
/*! Do not activate optional interrupts
    on TX IT process */
#define HAL_UART_OPT_TX_IT_NONE ..

/*! Activate FIFO Empty optional interrupt */
#define HAL_UART_OPT_TX_IT_FIFO_EMPTY ..

/*! Activate Clear To Send optional interrupt */
#define HAL_UART_OPT_TX_IT_CLEAR_TO_SEND ..

/*! Activate FIFO Empty and Clear To Send optional interrupts */
#define HAL_UART_OPT_TX_IT_DEFAULT ..

hal_status_t HAL_UART_Transmit_IT_Opt(hal_uart_handle_t *huart,
                                      const void *p_data,
                                      uint32_t size_byte,
                                      uint32_t interrupts);

/*
  Conventional HAL UART Transmit API
  in DMA based model
*/
HAL_StatusTypeDef HAL_UART_Transmit_DMA(UART_HandleTypeDef *huart,
                                        const uint8_t *pData,
                                        uint16_t Size);

/*
  Conventional HAL UART Transmit API
  in DMA based model
*/
hal_status_t HAL_UART_Transmit_DMA(hal_uart_handle_t *huart,
                                   const void *p_data,
                                   uint32_t size_byte);

/* None */

/*
  New HAL UART Transmit API in DMA based model
  with interrupt filtering capability
*/
/*! Do not activate optional interrupts
    on TX DMA process */
#define HAL_UART_OPT_DMA_TX_IT_NONE ..

/*! Activate DMA Half Transfer optional interrupt */
#define HAL_UART_OPT_DMA_TX_IT_HT ..

/*! Activate DMA Half Transfer optional interrupt */
#define HAL_UART_OPT_DMA_TX_IT_DEFAULT ..

/*! Activate Silent Mode on DMA */
#define HAL_UART_OPT_DMA_TX_IT_SILENT ..

hal_status_t HAL_UART_Transmit_DMA_Opt(hal_uart_handle_t *huart,
                                       const void *p_data,
                                       uint32_t size_byte,
                                       uint32_t interrupts);
ADC filtering APIs in HAL1 and HAL2

HAL1

HAL2 

/* Conventional HAL ADC regular conversion API
   in interrupt based model
*/
HAL_StatusTypeDef HAL_ADC_Start_IT(ADC_HandleTypeDef *hadc);

/* Conventional HAL ADC regular conversion API
   in interrupt based model
*/
hal_status_t HAL_ADC_REG_StartConv_IT(hal_adc_handle_t *hadc);

/* None */

/* New HAL ADC regular conversion API
   with interrupt filtering capability
*/

/* ADC optional interrupts disabled */
#define HAL_ADC_OPT_IT_NONE ..

/* ADC optional interrupt group regular
   end of sampling phase */
#define HAL_ADC_OPT_IT_REG_EOSMP..

/* ADC optional interrupt group regular
   end of unitary conversion */
#define HAL_ADC_OPT_IT_REG_EOC ..

/* ADC optional interrupt group regular
   end of sequence conversions */
#define HAL_ADC_OPT_IT_REG_EOS ..

/* ADC optional interrupt group regular overrun */
#define HAL_ADC_OPT_IT_REG_OVR ..

/* ADC optional interrupt group injected
   end of unitary conversion */
#define HAL_ADC_OPT_IT_INJ_EOC ..

/* ADC optional interrupt group injected
   end of sequence conversions */
#define HAL_ADC_OPT_IT_INJ_EOS ..

/* ADC optional interrupt analog watchdog 1
   out of window event */
#define HAL_ADC_OPT_IT_AWD_1 ..

/* ADC optional interrupt analog watchdog 2
   out of window event */
#define HAL_ADC_OPT_IT_AWD_2 ..

/* ADC optional interrupt analog watchdog 3 out
   of window event */
#define HAL_ADC_OPT_IT_AWD_3 ..

hal_status_t HAL_ADC_REG_StartConv_IT_Opt(hal_adc_handle_t *hadc, uint32_t it_opt);

/* Conventional HAL ADC regular conversion API
   in DMA based model
*/
HAL_StatusTypeDef HAL_ADC_Start_DMA(ADC_HandleTypeDef *hadc,
                                    const uint32_t *pData,
                                    uint32_t Length);

/* Conventional HAL ADC regular conversion API
   in DMA based model
*/
hal_status_t HAL_ADC_REG_StartConv_DMA(hal_adc_handle_t *hadc,
                                       const uint8_t *p_data,
                                       uint32_t size_byte);

/* None */

 /* New HAL ADC regular conversion API in DMA based model
    with interrupt filtering capability
 */
/* ADC optional interrupts disabled */
 #define HAL_ADC_OPT_IT_NONE ..

 /* ADC optional interrupt group regular
    end of sampling phase */
 #define HAL_ADC_OPT_IT_REG_EOSMP..

 /* ADC optional interrupt group regular
    end of unitary conversion */
 #define HAL_ADC_OPT_IT_REG_EOC ..

 /* ADC optional interrupt group regular
    end of sequence conversions */
 #define HAL_ADC_OPT_IT_REG_EOS ..

 /* ADC optional interrupt group regular overrun */
 #define HAL_ADC_OPT_IT_REG_OVR ..

 /* ADC optional interrupt group injected
    end of unitary conversion */
 #define HAL_ADC_OPT_IT_INJ_EOC ..

 /* ADC optional interrupt group injected
    end of sequence conversions */
 #define HAL_ADC_OPT_IT_INJ_EOS ..

 /* ADC optional interrupt analog watchdog 1
    out of window event */
 #define HAL_ADC_OPT_IT_AWD_1 ..

 /* ADC optional interrupt analog watchdog 2
    out of window event */
 #define HAL_ADC_OPT_IT_AWD_2 ..

 /* ADC optional interrupt analog watchdog 3 out
    of window event */
 #define HAL_ADC_OPT_IT_AWD_3 ..

 /* ADC data transfer with DMA optional interruptions disabled.
    DMA default interruptions: transfer complete, transfer error.
    DMA optional interruptions: refer to literals below. */
 #define HAL_ADC_OPT_DMA_IT_NONE ..

 /* ADC data transfer with DMA optional interrupt buffer half transfer */
 #define HAL_ADC_OPT_DMA_IT_HT ..

 /* ADC data transfer with DMA optional interrupt all enabled */
 #define HAL_ADC_OPT_DMA_IT_DEFAULT ..

 /* ADC data transfer with all interruptions disabled (ADC and DMA interruptions) */
 #define HAL_ADC_OPT_DMA_IT_SILENT ..

 hal_status_t HAL_ADC_REG_StartConv_DMA_Opt(hal_adc_handle_t *hadc,
                                            const uint8_t *p_data,
                                            uint32_t size_byte,
                                            uint32_t it_opt);