stm32h7/hal/stm32h7xx_hal_smartcard_ex.c

0001 /**
0002   ******************************************************************************
0003   * @file    stm32h7xx_hal_smartcard_ex.c
0004   * @author  MCD Application Team
0005   * @brief   SMARTCARD HAL module driver.
0006   *          This file provides extended firmware functions to manage the following
0007   *          functionalities of the SmartCard.
0008   *           + Initialization and de-initialization functions
0009   *           + Peripheral Control functions
0010   *
0011   ******************************************************************************
0012   * @attention
0013   *
0014   * Copyright (c) 2017 STMicroelectronics.
0015   * All rights reserved.
0016   *
0017   * This software is licensed under terms that can be found in the LICENSE file
0018   * in the root directory of this software component.
0019   * If no LICENSE file comes with this software, it is provided AS-IS.
0020   *
0021   ******************************************************************************
0022   @verbatim
0023   =============================================================================
0024                ##### SMARTCARD peripheral extended features  #####
0025   =============================================================================
0026   [..]
0027   The Extended SMARTCARD HAL driver can be used as follows:
0028
0029     (#) After having configured the SMARTCARD basic features with HAL_SMARTCARD_Init(),
0030         then program SMARTCARD advanced features if required (TX/RX pins swap, TimeOut,
0031         auto-retry counter,...) in the hsmartcard AdvancedInit structure.
0032
0033     (#) FIFO mode enabling/disabling and RX/TX FIFO threshold programming.
0034
0035         -@- When SMARTCARD operates in FIFO mode, FIFO mode must be enabled prior
0036             starting RX/TX transfers. Also RX/TX FIFO thresholds must be
0037             configured prior starting RX/TX transfers.
0038
0039   @endverbatim
0040   ******************************************************************************
0041   */
0042
0043 /* Includes ------------------------------------------------------------------*/
0044 #include "stm32h7xx_hal.h"
0045
0046 /** @addtogroup STM32H7xx_HAL_Driver
0047   * @{
0048   */
0049
0050 /** @defgroup SMARTCARDEx SMARTCARDEx
0051   * @ingroup RTEMSBSPsARMSTM32H7
0052   * @brief SMARTCARD Extended HAL module driver
0053   * @{
0054   */
0055 #ifdef HAL_SMARTCARD_MODULE_ENABLED
0056
0057 /* Private typedef -----------------------------------------------------------*/
0058 /* Private define ------------------------------------------------------------*/
0059 /** @defgroup SMARTCARDEx_Private_Constants SMARTCARD Extended Private Constants
0060   * @ingroup RTEMSBSPsARMSTM32H7
0061   * @{
0062   */
0063 /* UART RX FIFO depth */
0064 #define RX_FIFO_DEPTH 16U
0065
0066 /* UART TX FIFO depth */
0067 #define TX_FIFO_DEPTH 16U
0068 /**
0069   * @}
0070   */
0071
0072 /* Private macros ------------------------------------------------------------*/
0073 /* Private variables ---------------------------------------------------------*/
0074 /* Private function prototypes -----------------------------------------------*/
0075 static void SMARTCARDEx_SetNbDataToProcess(SMARTCARD_HandleTypeDef *hsmartcard);
0076
0077 /* Exported functions --------------------------------------------------------*/
0078 /** @defgroup SMARTCARDEx_Exported_Functions  SMARTCARD Extended Exported Functions
0079   * @ingroup RTEMSBSPsARMSTM32H7
0080   * @{
0081   */
0082
0083 /** @defgroup SMARTCARDEx_Exported_Functions_Group1 Extended Peripheral Control functions
0084   * @ingroup RTEMSBSPsARMSTM32H7
0085   * @brief    Extended control functions
0086   *
0087 @verbatim
0088   ===============================================================================
0089                       ##### Peripheral Control functions #####
0090   ===============================================================================
0091   [..]
0092   This subsection provides a set of functions allowing to initialize the SMARTCARD.
0093      (+) HAL_SMARTCARDEx_BlockLength_Config() API allows to configure the Block Length on the fly
0094      (+) HAL_SMARTCARDEx_TimeOut_Config() API allows to configure the receiver timeout value on the fly
0095      (+) HAL_SMARTCARDEx_EnableReceiverTimeOut() API enables the receiver timeout feature
0096      (+) HAL_SMARTCARDEx_DisableReceiverTimeOut() API disables the receiver timeout feature
0097
0098 @endverbatim
0099   * @{
0100   */
0101
0102 /** @brief Update on the fly the SMARTCARD block length in RTOR register.
0103   * @param hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains
0104   *                    the configuration information for the specified SMARTCARD module.
0105   * @param BlockLength SMARTCARD block length (8-bit long at most)
0106   * @retval None
0107   */
0108 void HAL_SMARTCARDEx_BlockLength_Config(SMARTCARD_HandleTypeDef *hsmartcard, uint8_t BlockLength)
0109 {
0110   MODIFY_REG(hsmartcard->Instance->RTOR, USART_RTOR_BLEN, ((uint32_t)BlockLength << USART_RTOR_BLEN_Pos));
0111 }
0112
0113 /** @brief Update on the fly the receiver timeout value in RTOR register.
0114   * @param hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains
0115   *                    the configuration information for the specified SMARTCARD module.
0116   * @param TimeOutValue receiver timeout value in number of baud blocks. The timeout
0117   *                     value must be less or equal to 0x0FFFFFFFF.
0118   * @retval None
0119   */
0120 void HAL_SMARTCARDEx_TimeOut_Config(SMARTCARD_HandleTypeDef *hsmartcard, uint32_t TimeOutValue)
0121 {
0122   assert_param(IS_SMARTCARD_TIMEOUT_VALUE(hsmartcard->Init.TimeOutValue));
0123   MODIFY_REG(hsmartcard->Instance->RTOR, USART_RTOR_RTO, TimeOutValue);
0124 }
0125
0126 /** @brief Enable the SMARTCARD receiver timeout feature.
0127   * @param hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains
0128   *                    the configuration information for the specified SMARTCARD module.
0129   * @retval HAL status
0130   */
0131 HAL_StatusTypeDef HAL_SMARTCARDEx_EnableReceiverTimeOut(SMARTCARD_HandleTypeDef *hsmartcard)
0132 {
0133   if (hsmartcard->gState == HAL_SMARTCARD_STATE_READY)
0134   {
0135     /* Process Locked */
0136     __HAL_LOCK(hsmartcard);
0137
0138     hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY;
0139
0140     /* Set the USART RTOEN bit */
0141     SET_BIT(hsmartcard->Instance->CR2, USART_CR2_RTOEN);
0142
0143     hsmartcard->gState = HAL_SMARTCARD_STATE_READY;
0144
0145     /* Process Unlocked */
0146     __HAL_UNLOCK(hsmartcard);
0147
0148     return HAL_OK;
0149   }
0150   else
0151   {
0152     return HAL_BUSY;
0153   }
0154 }
0155
0156 /** @brief Disable the SMARTCARD receiver timeout feature.
0157   * @param hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains
0158   *                    the configuration information for the specified SMARTCARD module.
0159   * @retval HAL status
0160   */
0161 HAL_StatusTypeDef HAL_SMARTCARDEx_DisableReceiverTimeOut(SMARTCARD_HandleTypeDef *hsmartcard)
0162 {
0163   if (hsmartcard->gState == HAL_SMARTCARD_STATE_READY)
0164   {
0165     /* Process Locked */
0166     __HAL_LOCK(hsmartcard);
0167
0168     hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY;
0169
0170     /* Clear the USART RTOEN bit */
0171     CLEAR_BIT(hsmartcard->Instance->CR2, USART_CR2_RTOEN);
0172
0173     hsmartcard->gState = HAL_SMARTCARD_STATE_READY;
0174
0175     /* Process Unlocked */
0176     __HAL_UNLOCK(hsmartcard);
0177
0178     return HAL_OK;
0179   }
0180   else
0181   {
0182     return HAL_BUSY;
0183   }
0184 }
0185
0186 /**
0187   * @}
0188   */
0189
0190 /** @defgroup SMARTCARDEx_Exported_Functions_Group2 Extended Peripheral IO operation functions
0191   * @ingroup RTEMSBSPsARMSTM32H7
0192   * @brief   SMARTCARD Transmit and Receive functions
0193   *
0194 @verbatim
0195  ===============================================================================
0196                       ##### IO operation functions #####
0197  ===============================================================================
0198     [..]
0199     This subsection provides a set of FIFO mode related callback functions.
0200
0201     (#) TX/RX Fifos Callbacks:
0202         (++) HAL_SMARTCARDEx_RxFifoFullCallback()
0203         (++) HAL_SMARTCARDEx_TxFifoEmptyCallback()
0204
0205 @endverbatim
0206   * @{
0207   */
0208
0209 /**
0210   * @brief  SMARTCARD RX Fifo full callback.
0211   * @param  hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains
0212   *                   the configuration information for the specified SMARTCARD module.
0213   * @retval None
0214   */
0215 __weak void HAL_SMARTCARDEx_RxFifoFullCallback(SMARTCARD_HandleTypeDef *hsmartcard)
0216 {
0217   /* Prevent unused argument(s) compilation warning */
0218   UNUSED(hsmartcard);
0219
0220   /* NOTE : This function should not be modified, when the callback is needed,
0221             the HAL_SMARTCARDEx_RxFifoFullCallback can be implemented in the user file.
0222    */
0223 }
0224
0225 /**
0226   * @brief  SMARTCARD TX Fifo empty callback.
0227   * @param  hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains
0228   *                   the configuration information for the specified SMARTCARD module.
0229   * @retval None
0230   */
0231 __weak void HAL_SMARTCARDEx_TxFifoEmptyCallback(SMARTCARD_HandleTypeDef *hsmartcard)
0232 {
0233   /* Prevent unused argument(s) compilation warning */
0234   UNUSED(hsmartcard);
0235
0236   /* NOTE : This function should not be modified, when the callback is needed,
0237             the HAL_SMARTCARDEx_TxFifoEmptyCallback can be implemented in the user file.
0238    */
0239 }
0240
0241 /**
0242   * @}
0243   */
0244
0245 /** @defgroup SMARTCARDEx_Exported_Functions_Group3 Extended Peripheral FIFO Control functions
0246   * @ingroup RTEMSBSPsARMSTM32H7
0247   *  @brief   SMARTCARD control functions
0248   *
0249 @verbatim
0250  ===============================================================================
0251                   ##### Peripheral FIFO Control functions #####
0252  ===============================================================================
0253     [..]
0254     This subsection provides a set of functions allowing to control the SMARTCARD
0255     FIFO feature.
0256      (+) HAL_SMARTCARDEx_EnableFifoMode() API enables the FIFO mode
0257      (+) HAL_SMARTCARDEx_DisableFifoMode() API disables the FIFO mode
0258      (+) HAL_SMARTCARDEx_SetTxFifoThreshold() API sets the TX FIFO threshold
0259      (+) HAL_SMARTCARDEx_SetRxFifoThreshold() API sets the RX FIFO threshold
0260 @endverbatim
0261   * @{
0262   */
0263
0264 /**
0265   * @brief  Enable the FIFO mode.
0266   * @param hsmartcard SMARTCARD handle.
0267   * @retval HAL status
0268   */
0269 HAL_StatusTypeDef HAL_SMARTCARDEx_EnableFifoMode(SMARTCARD_HandleTypeDef *hsmartcard)
0270 {
0271   uint32_t tmpcr1;
0272
0273   /* Check parameters */
0274   assert_param(IS_UART_FIFO_INSTANCE(hsmartcard->Instance));
0275
0276   /* Process Locked */
0277   __HAL_LOCK(hsmartcard);
0278
0279   hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY;
0280
0281   /* Save actual SMARTCARD configuration */
0282   tmpcr1 = READ_REG(hsmartcard->Instance->CR1);
0283
0284   /* Disable SMARTCARD */
0285   __HAL_SMARTCARD_DISABLE(hsmartcard);
0286
0287   /* Enable FIFO mode */
0288   SET_BIT(tmpcr1, USART_CR1_FIFOEN);
0289   hsmartcard->FifoMode = SMARTCARD_FIFOMODE_ENABLE;
0290
0291   /* Restore SMARTCARD configuration */
0292   WRITE_REG(hsmartcard->Instance->CR1, tmpcr1);
0293
0294   /* Determine the number of data to process during RX/TX ISR execution */
0295   SMARTCARDEx_SetNbDataToProcess(hsmartcard);
0296
0297   hsmartcard->gState = HAL_SMARTCARD_STATE_READY;
0298
0299   /* Process Unlocked */
0300   __HAL_UNLOCK(hsmartcard);
0301
0302   return HAL_OK;
0303 }
0304
0305 /**
0306   * @brief  Disable the FIFO mode.
0307   * @param hsmartcard SMARTCARD handle.
0308   * @retval HAL status
0309   */
0310 HAL_StatusTypeDef HAL_SMARTCARDEx_DisableFifoMode(SMARTCARD_HandleTypeDef *hsmartcard)
0311 {
0312   uint32_t tmpcr1;
0313
0314   /* Check parameters */
0315   assert_param(IS_UART_FIFO_INSTANCE(hsmartcard->Instance));
0316
0317   /* Process Locked */
0318   __HAL_LOCK(hsmartcard);
0319
0320   hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY;
0321
0322   /* Save actual SMARTCARD configuration */
0323   tmpcr1 = READ_REG(hsmartcard->Instance->CR1);
0324
0325   /* Disable SMARTCARD */
0326   __HAL_SMARTCARD_DISABLE(hsmartcard);
0327
0328   /* Enable FIFO mode */
0329   CLEAR_BIT(tmpcr1, USART_CR1_FIFOEN);
0330   hsmartcard->FifoMode = SMARTCARD_FIFOMODE_DISABLE;
0331
0332   /* Restore SMARTCARD configuration */
0333   WRITE_REG(hsmartcard->Instance->CR1, tmpcr1);
0334
0335   hsmartcard->gState = HAL_SMARTCARD_STATE_READY;
0336
0337   /* Process Unlocked */
0338   __HAL_UNLOCK(hsmartcard);
0339
0340   return HAL_OK;
0341 }
0342
0343 /**
0344   * @brief  Set the TXFIFO threshold.
0345   * @param hsmartcard      SMARTCARD handle.
0346   * @param Threshold  TX FIFO threshold value
0347   *          This parameter can be one of the following values:
0348   *            @arg @ref SMARTCARD_TXFIFO_THRESHOLD_1_8
0349   *            @arg @ref SMARTCARD_TXFIFO_THRESHOLD_1_4
0350   *            @arg @ref SMARTCARD_TXFIFO_THRESHOLD_1_2
0351   *            @arg @ref SMARTCARD_TXFIFO_THRESHOLD_3_4
0352   *            @arg @ref SMARTCARD_TXFIFO_THRESHOLD_7_8
0353   *            @arg @ref SMARTCARD_TXFIFO_THRESHOLD_8_8
0354   * @retval HAL status
0355   */
0356 HAL_StatusTypeDef HAL_SMARTCARDEx_SetTxFifoThreshold(SMARTCARD_HandleTypeDef *hsmartcard, uint32_t Threshold)
0357 {
0358   uint32_t tmpcr1;
0359
0360   /* Check parameters */
0361   assert_param(IS_UART_FIFO_INSTANCE(hsmartcard->Instance));
0362   assert_param(IS_SMARTCARD_TXFIFO_THRESHOLD(Threshold));
0363
0364   /* Process Locked */
0365   __HAL_LOCK(hsmartcard);
0366
0367   hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY;
0368
0369   /* Save actual SMARTCARD configuration */
0370   tmpcr1 = READ_REG(hsmartcard->Instance->CR1);
0371
0372   /* Disable SMARTCARD */
0373   __HAL_SMARTCARD_DISABLE(hsmartcard);
0374
0375   /* Update TX threshold configuration */
0376   MODIFY_REG(hsmartcard->Instance->CR3, USART_CR3_TXFTCFG, Threshold);
0377
0378   /* Determine the number of data to process during RX/TX ISR execution */
0379   SMARTCARDEx_SetNbDataToProcess(hsmartcard);
0380
0381   /* Restore SMARTCARD configuration */
0382   MODIFY_REG(hsmartcard->Instance->CR1, USART_CR1_UE, tmpcr1);
0383
0384   hsmartcard->gState = HAL_SMARTCARD_STATE_READY;
0385
0386   /* Process Unlocked */
0387   __HAL_UNLOCK(hsmartcard);
0388
0389   return HAL_OK;
0390 }
0391
0392 /**
0393   * @brief  Set the RXFIFO threshold.
0394   * @param hsmartcard      SMARTCARD handle.
0395   * @param Threshold  RX FIFO threshold value
0396   *          This parameter can be one of the following values:
0397   *            @arg @ref SMARTCARD_RXFIFO_THRESHOLD_1_8
0398   *            @arg @ref SMARTCARD_RXFIFO_THRESHOLD_1_4
0399   *            @arg @ref SMARTCARD_RXFIFO_THRESHOLD_1_2
0400   *            @arg @ref SMARTCARD_RXFIFO_THRESHOLD_3_4
0401   *            @arg @ref SMARTCARD_RXFIFO_THRESHOLD_7_8
0402   *            @arg @ref SMARTCARD_RXFIFO_THRESHOLD_8_8
0403   * @retval HAL status
0404   */
0405 HAL_StatusTypeDef HAL_SMARTCARDEx_SetRxFifoThreshold(SMARTCARD_HandleTypeDef *hsmartcard, uint32_t Threshold)
0406 {
0407   uint32_t tmpcr1;
0408
0409   /* Check parameters */
0410   assert_param(IS_UART_FIFO_INSTANCE(hsmartcard->Instance));
0411   assert_param(IS_SMARTCARD_RXFIFO_THRESHOLD(Threshold));
0412
0413   /* Process Locked */
0414   __HAL_LOCK(hsmartcard);
0415
0416   hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY;
0417
0418   /* Save actual SMARTCARD configuration */
0419   tmpcr1 = READ_REG(hsmartcard->Instance->CR1);
0420
0421   /* Disable SMARTCARD */
0422   __HAL_SMARTCARD_DISABLE(hsmartcard);
0423
0424   /* Update RX threshold configuration */
0425   MODIFY_REG(hsmartcard->Instance->CR3, USART_CR3_RXFTCFG, Threshold);
0426
0427   /* Determine the number of data to process during RX/TX ISR execution */
0428   SMARTCARDEx_SetNbDataToProcess(hsmartcard);
0429
0430   /* Restore SMARTCARD configuration */
0431   MODIFY_REG(hsmartcard->Instance->CR1, USART_CR1_UE, tmpcr1);
0432
0433   hsmartcard->gState = HAL_SMARTCARD_STATE_READY;
0434
0435   /* Process Unlocked */
0436   __HAL_UNLOCK(hsmartcard);
0437
0438   return HAL_OK;
0439 }
0440
0441 /**
0442   * @}
0443   */
0444
0445 /**
0446   * @}
0447   */
0448
0449 /** @defgroup SMARTCARDEx_Private_Functions  SMARTCARD Extended Private Functions
0450   * @ingroup RTEMSBSPsARMSTM32H7
0451   * @{
0452   */
0453
0454 /**
0455   * @brief Calculate the number of data to process in RX/TX ISR.
0456   * @note The RX FIFO depth and the TX FIFO depth is extracted from
0457   *       the USART configuration registers.
0458   * @param hsmartcard SMARTCARD handle.
0459   * @retval None
0460   */
0461 static void SMARTCARDEx_SetNbDataToProcess(SMARTCARD_HandleTypeDef *hsmartcard)
0462 {
0463   uint8_t rx_fifo_depth;
0464   uint8_t tx_fifo_depth;
0465   uint8_t rx_fifo_threshold;
0466   uint8_t tx_fifo_threshold;
0467   /* 2 0U/1U added for MISRAC2012-Rule-18.1_b and MISRAC2012-Rule-18.1_d */
0468   static const uint8_t numerator[]   = {1U, 1U, 1U, 3U, 7U, 1U, 0U, 0U};
0469   static const uint8_t denominator[] = {8U, 4U, 2U, 4U, 8U, 1U, 1U, 1U};
0470
0471   if (hsmartcard->FifoMode == SMARTCARD_FIFOMODE_DISABLE)
0472   {
0473     hsmartcard->NbTxDataToProcess = 1U;
0474     hsmartcard->NbRxDataToProcess = 1U;
0475   }
0476   else
0477   {
0478     rx_fifo_depth = RX_FIFO_DEPTH;
0479     tx_fifo_depth = TX_FIFO_DEPTH;
0480     rx_fifo_threshold = (uint8_t)(READ_BIT(hsmartcard->Instance->CR3, USART_CR3_RXFTCFG) >> USART_CR3_RXFTCFG_Pos);
0481     tx_fifo_threshold = (uint8_t)(READ_BIT(hsmartcard->Instance->CR3, USART_CR3_TXFTCFG) >> USART_CR3_TXFTCFG_Pos);
0482     hsmartcard->NbTxDataToProcess = ((uint16_t)tx_fifo_depth * numerator[tx_fifo_threshold]) / \
0483                                     (uint16_t)denominator[tx_fifo_threshold];
0484     hsmartcard->NbRxDataToProcess = ((uint16_t)rx_fifo_depth * numerator[rx_fifo_threshold]) / \
0485                                     (uint16_t)denominator[rx_fifo_threshold];
0486   }
0487 }
0488
0489 /**
0490   * @}
0491   */
0492
0493 #endif /* HAL_SMARTCARD_MODULE_ENABLED */
0494
0495 /**
0496   * @}
0497   */
0498
0499 /**
0500   * @}
0501   */
0502