STM32 HAL library function - HAL_UART_Transmit_IT() detailed explanation

function source code

HAL_StatusTypeDef HAL_UART_Transmit_IT(UART_HandleTypeDef *huart, const uint8_t *pData, uint16_t Size)
{
    
    
  /* Check that a Tx process is not already ongoing */
  if (huart->gState == HAL_UART_STATE_READY)
  {
    
    
    if ((pData == NULL) || (Size == 0U))
    {
    
    
      return HAL_ERROR;
    }

    /* In case of 9bits/No Parity transfer, pData buffer provided as input parameter
       should be aligned on a u16 frontier, as data to be filled into TDR will be
       handled through a u16 cast. */
    if ((huart->Init.WordLength == UART_WORDLENGTH_9B) && (huart->Init.Parity == UART_PARITY_NONE))
    {
    
    
      if ((((uint32_t)pData) & 1U) != 0U)
      {
    
    
        return  HAL_ERROR;
      }
    }

    huart->pTxBuffPtr  = pData;
    huart->TxXferSize  = Size;
    huart->TxXferCount = Size;
    huart->TxISR       = NULL;

    huart->ErrorCode = HAL_UART_ERROR_NONE;
    huart->gState = HAL_UART_STATE_BUSY_TX;

    /* Configure Tx interrupt processing */
    if (huart->FifoMode == UART_FIFOMODE_ENABLE)
    {
    
    
      /* Set the Tx ISR function pointer according to the data word length */
      if ((huart->Init.WordLength == UART_WORDLENGTH_9B) && (huart->Init.Parity == UART_PARITY_NONE))
      {
    
    
        huart->TxISR = UART_TxISR_16BIT_FIFOEN;
      }
      else
      {
    
    
        huart->TxISR = UART_TxISR_8BIT_FIFOEN;
      }

      /* Enable the TX FIFO threshold interrupt */
      ATOMIC_SET_BIT(huart->Instance->CR3, USART_CR3_TXFTIE);
    }
    else
    {
    
    
      /* Set the Tx ISR function pointer according to the data word length */
      if ((huart->Init.WordLength == UART_WORDLENGTH_9B) && (huart->Init.Parity == UART_PARITY_NONE))
      {
    
    
        huart->TxISR = UART_TxISR_16BIT;
      }
      else
      {
    
    
        huart->TxISR = UART_TxISR_8BIT;
      }

      /* Enable the Transmit Data Register Empty interrupt */
      ATOMIC_SET_BIT(huart->Instance->CR1, USART_CR1_TXEIE_TXFNFIE);
    }

    return HAL_OK;
  }
  else
  {
    
    
    return HAL_BUSY;
  }
}

Detailed explanation of function usage

HAL_UART_Transmit_ITThe usage of the function is as follows:

Input parameters:

• huart: Pointer to the UART handle structure, which is used to specify the UART peripheral to be used.
• pData: Pointer to the buffer of the data to be sent, which can be uint8_ttype or uint16_tdata of type.
• Size: The size of the data to send, expressed in the number of data elements ( uint8_tor uint16_t).

return value:

• HAL_StatusTypeDefA return value of type that represents the execution status of the function. Possible return values ​​include:
  • HAL_OK: The send operation was successfully initiated.
  • HAL_BUSY: There is currently a sending operation in progress.
  • HAL_ERROR: The parameter passed in is invalid.

What the function does:

• Send data in interrupt mode. The function will check the status of UART, if there is currently a sending operation in progress, it will return the busy status. Then, it checks whether the incoming data buffer pointer and data size are legal, and returns an error status if not.
• If the parameters are legal, the function will set the member variables in the UART handle structure, and select the function pointer of the corresponding interrupt service routine according to the FIFO mode and data length of the UART, and enable the corresponding interrupt.
• Finally, the function returns a status value indicating the start status of the send operation.

When using this function, you need to create a valid UART handle structure and pass it to the function as the first parameter. Additionally, you need to provide a valid data buffer pointer and data size.

Before using this function, you need to initialize the UART configuration, including the settings of baud rate, data bits, stop bits, parity and other parameters. You also need to make sure that the UART's interrupts are configured correctly, and implement the corresponding interrupt service routine to handle events such as transmission completion and errors.

function function

The above code is a function in HAL library HAL_UART_Transmit_ITto send data in interrupt mode.

HAL_UART_Transmit_ITThe function of the function is to send data in interrupt mode. It accepts a pointer to the UART handle structure huart, a pointer to the buffer of the data to be sent pData, and the size of the data to be sent Size.

The function first checks the status of UART, if there is currently a sending operation in progress, it will return HAL_BUSYbusy. It then checks the incoming data buffer pointer and data size, and returns if they are invalid (NULL or size 0) HAL_ERROR.

Next, the function sets some member variables in the UART handle structure, including the send buffer pointer, the size of the sent data, the size of the remaining data to be sent, the function pointer of the send interrupt service routine, and the error code and UART status.

According to the FIFO mode and data length of UART, the function selects the function pointer of the corresponding interrupt service routine and enables the corresponding interrupt. If the FIFO mode is enabled, the function will enable the TX FIFO threshold interrupt; if the FIFO mode is not enabled, the function will enable the transmit data register empty interrupt.

Finally, the function returns HAL_OKto indicate that the send operation was successfully initiated.

All in all, HAL_UART_Transmit_ITthe function allows data to be sent in interrupt mode, and the asynchronous sending of data can be realized by configuring the interrupt service routine and enabling the corresponding interrupt. This can avoid blocking the main thread and improve the responsiveness of the system.

function line by line

Here is a detailed explanation of each line of code:

HAL_StatusTypeDef HAL_UART_Transmit_IT(UART_HandleTypeDef *huart, const uint8_t *pData, uint16_t Size)

Here is the definition of the function, which takes a UART_HandleTypeDefpointer to a structure huart, a pointer to a buffer for the data to send pData, and the size of the data to send Size. It returns HAL_StatusTypeDefthe state of a type.

if (huart->gState == HAL_UART_STATE_READY)

This line of code checks if the state of the UART is ie HAL_UART_STATE_READYthere is no transmission process in progress. If the UART status is not READY, it means that there is currently a sending operation in progress, and the function will return HAL_BUSY.

if ((pData == NULL) || (Size == 0U))
{
    
    
  return HAL_ERROR;
}

This line of code checks if the data buffer pointer to send pDatais NULL and Sizeif the data size to send is 0. If yes, return it HAL_ERROR.

if ((huart->Init.WordLength == UART_WORDLENGTH_9B) && (huart->Init.Parity == UART_PARITY_NONE))
{
    
    
  if ((((uint32_t)pData) & 1U) != 0U)
  {
    
    
    return  HAL_ERROR;
  }
}

pDataThis code checks that the data buffer pointer is aligned on a u16 boundary when using a 9-bit data length and no parity . Returns if not bounds aligned HAL_ERROR.

huart->pTxBuffPtr  = pData;
huart->TxXferSize  = Size;
huart->TxXferCount = Size;
huart->TxISR       = NULL;

huart->ErrorCode = HAL_UART_ERROR_NONE;
huart->gState = HAL_UART_STATE_BUSY_TX;

These codes set some member variables in the UART handle structure, including the send buffer pointer pTxBuffPtr, the size of the sent data TxXferSize, the size of the remaining data to be sent TxXferCount, the function pointer of the send interrupt service routine TxISR, and the error code and UART status.

if (huart->FifoMode == UART_FIFOMODE_ENABLE)
{
    
    
  if ((huart->Init.WordLength == UART_WORDLENGTH_9B) && (huart->Init.Parity == UART_PARITY_NONE))
  {
    
    
    huart->TxISR = UART_TxISR_16BIT_FIFOEN;
  }
  else
  {
    
    
    huart->TxISR = UART_TxISR_8BIT_FIFOEN;
  }

  ATOMIC_SET_BIT(huart->Instance->CR3, USART_CR3_TXFTIE);
}
else
{
    
    
  if ((huart->Init.WordLength == UART_WORDLENGTH_9B) && (huart->Init.Parity == UART_PARITY_NONE))
  {
    
    
    huart->TxISR = UART_TxISR_16BIT;
  }
  else
  {
    
    
    huart->TxISR = UART_TxISR_8BIT;
  }

  ATOMIC_SET_BIT(huart->Instance->CR1, USART_CR1_TXEIE_TXFNFIE);
}

This part of the code sets the function pointer of the interrupt service routine according to the FIFO mode and data length of the UART TxISR, and enables the corresponding interrupt. If the FIFO mode is enabled, select the 16-bit or 8-bit interrupt service routine according to the data length, and enable the TX FIFO threshold interrupt. If the FIFO mode is not enabled, also select the 16-bit or 8-bit interrupt service routine according to the data length, and enable the empty interrupt of the sending data register.

Finally, the function returns HAL_OKto indicate that the send operation was successfully initiated.