STM32L486xx HAL User Manual
|
00001 /** 00002 ****************************************************************************** 00003 * @file stm32l4xx_hal_smartcard_ex.c 00004 * @author MCD Application Team 00005 * @brief SMARTCARD HAL module driver. 00006 * This file provides extended firmware functions to manage the following 00007 * functionalities of the SmartCard. 00008 * + Initialization and de-initialization functions 00009 * + Peripheral Control functions 00010 * 00011 * 00012 @verbatim 00013 ============================================================================= 00014 ##### SMARTCARD peripheral extended features ##### 00015 ============================================================================= 00016 [..] 00017 The Extended SMARTCARD HAL driver can be used as follows: 00018 00019 (#) After having configured the SMARTCARD basic features with HAL_SMARTCARD_Init(), 00020 then program SMARTCARD advanced features if required (TX/RX pins swap, TimeOut, 00021 auto-retry counter,...) in the hsmartcard AdvancedInit structure. 00022 00023 (#) FIFO mode enabling/disabling and RX/TX FIFO threshold programming. 00024 00025 -@- When SMARTCARD operates in FIFO mode, FIFO mode must be enabled prior 00026 starting RX/TX transfers. Also RX/TX FIFO thresholds must be 00027 configured prior starting RX/TX transfers. 00028 00029 @endverbatim 00030 ****************************************************************************** 00031 * @attention 00032 * 00033 * <h2><center>© COPYRIGHT(c) 2017 STMicroelectronics</center></h2> 00034 * 00035 * Redistribution and use in source and binary forms, with or without modification, 00036 * are permitted provided that the following conditions are met: 00037 * 1. Redistributions of source code must retain the above copyright notice, 00038 * this list of conditions and the following disclaimer. 00039 * 2. Redistributions in binary form must reproduce the above copyright notice, 00040 * this list of conditions and the following disclaimer in the documentation 00041 * and/or other materials provided with the distribution. 00042 * 3. Neither the name of STMicroelectronics nor the names of its contributors 00043 * may be used to endorse or promote products derived from this software 00044 * without specific prior written permission. 00045 * 00046 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 00047 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 00048 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 00049 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 00050 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 00051 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 00052 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 00053 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 00054 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 00055 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00056 * 00057 ****************************************************************************** 00058 */ 00059 00060 /* Includes ------------------------------------------------------------------*/ 00061 #include "stm32l4xx_hal.h" 00062 00063 /** @addtogroup STM32L4xx_HAL_Driver 00064 * @{ 00065 */ 00066 00067 /** @defgroup SMARTCARDEx SMARTCARDEx 00068 * @brief SMARTCARD Extended HAL module driver 00069 * @{ 00070 */ 00071 #ifdef HAL_SMARTCARD_MODULE_ENABLED 00072 00073 /* Private typedef -----------------------------------------------------------*/ 00074 /* Private define ------------------------------------------------------------*/ 00075 /* UART RX FIFO depth */ 00076 #define RX_FIFO_DEPTH 8U 00077 00078 /* UART TX FIFO depth */ 00079 #define TX_FIFO_DEPTH 8U 00080 00081 /* Private macros ------------------------------------------------------------*/ 00082 /* Private variables ---------------------------------------------------------*/ 00083 /* Private function prototypes -----------------------------------------------*/ 00084 #if defined(USART_CR1_FIFOEN) 00085 static void SMARTCARDEx_SetNbDataToProcess(SMARTCARD_HandleTypeDef *hsmartcard); 00086 #endif 00087 00088 /* Exported functions --------------------------------------------------------*/ 00089 /** @defgroup SMARTCARDEx_Exported_Functions SMARTCARD Extended Exported Functions 00090 * @{ 00091 */ 00092 00093 /** @defgroup SMARTCARDEx_Exported_Functions_Group1 Extended Peripheral Control functions 00094 * @brief Extended control functions 00095 * 00096 @verbatim 00097 =============================================================================== 00098 ##### Peripheral Control functions ##### 00099 =============================================================================== 00100 [..] 00101 This subsection provides a set of functions allowing to initialize the SMARTCARD. 00102 (+) HAL_SMARTCARDEx_BlockLength_Config() API allows to configure the Block Length on the fly 00103 (+) HAL_SMARTCARDEx_TimeOut_Config() API allows to configure the receiver timeout value on the fly 00104 (+) HAL_SMARTCARDEx_EnableReceiverTimeOut() API enables the receiver timeout feature 00105 (+) HAL_SMARTCARDEx_DisableReceiverTimeOut() API disables the receiver timeout feature 00106 00107 @endverbatim 00108 * @{ 00109 */ 00110 00111 /** 00112 * @brief Update on the fly the SMARTCARD block length in RTOR register. 00113 * @param hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains 00114 * the configuration information for the specified SMARTCARD module. 00115 * @param BlockLength SMARTCARD block length (8-bit long at most) 00116 * @retval None 00117 */ 00118 void HAL_SMARTCARDEx_BlockLength_Config(SMARTCARD_HandleTypeDef *hsmartcard, uint8_t BlockLength) 00119 { 00120 MODIFY_REG(hsmartcard->Instance->RTOR, USART_RTOR_BLEN, ((uint32_t)BlockLength << USART_RTOR_BLEN_Pos)); 00121 } 00122 00123 /** 00124 * @brief Update on the fly the receiver timeout value in RTOR register. 00125 * @param hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains 00126 * the configuration information for the specified SMARTCARD module. 00127 * @param TimeOutValue receiver timeout value in number of baud blocks. The timeout 00128 * value must be less or equal to 0x0FFFFFFFF. 00129 * @retval None 00130 */ 00131 void HAL_SMARTCARDEx_TimeOut_Config(SMARTCARD_HandleTypeDef *hsmartcard, uint32_t TimeOutValue) 00132 { 00133 assert_param(IS_SMARTCARD_TIMEOUT_VALUE(hsmartcard->Init.TimeOutValue)); 00134 MODIFY_REG(hsmartcard->Instance->RTOR, USART_RTOR_RTO, TimeOutValue); 00135 } 00136 00137 /** 00138 * @brief Enable the SMARTCARD receiver timeout feature. 00139 * @param hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains 00140 * the configuration information for the specified SMARTCARD module. 00141 * @retval HAL status 00142 */ 00143 HAL_StatusTypeDef HAL_SMARTCARDEx_EnableReceiverTimeOut(SMARTCARD_HandleTypeDef *hsmartcard) 00144 { 00145 00146 if (hsmartcard->gState == HAL_SMARTCARD_STATE_READY) 00147 { 00148 /* Process Locked */ 00149 __HAL_LOCK(hsmartcard); 00150 00151 hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY; 00152 00153 /* Set the USART RTOEN bit */ 00154 SET_BIT(hsmartcard->Instance->CR2, USART_CR2_RTOEN); 00155 00156 hsmartcard->gState = HAL_SMARTCARD_STATE_READY; 00157 00158 /* Process Unlocked */ 00159 __HAL_UNLOCK(hsmartcard); 00160 00161 return HAL_OK; 00162 } 00163 else 00164 { 00165 return HAL_BUSY; 00166 } 00167 } 00168 00169 /** 00170 * @brief Disable the SMARTCARD receiver timeout feature. 00171 * @param hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains 00172 * the configuration information for the specified SMARTCARD module. 00173 * @retval HAL status 00174 */ 00175 HAL_StatusTypeDef HAL_SMARTCARDEx_DisableReceiverTimeOut(SMARTCARD_HandleTypeDef *hsmartcard) 00176 { 00177 00178 if (hsmartcard->gState == HAL_SMARTCARD_STATE_READY) 00179 { 00180 /* Process Locked */ 00181 __HAL_LOCK(hsmartcard); 00182 00183 hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY; 00184 00185 /* Clear the USART RTOEN bit */ 00186 CLEAR_BIT(hsmartcard->Instance->CR2, USART_CR2_RTOEN); 00187 00188 hsmartcard->gState = HAL_SMARTCARD_STATE_READY; 00189 00190 /* Process Unlocked */ 00191 __HAL_UNLOCK(hsmartcard); 00192 00193 return HAL_OK; 00194 } 00195 else 00196 { 00197 return HAL_BUSY; 00198 } 00199 } 00200 00201 /** 00202 * @} 00203 */ 00204 00205 /** @defgroup SMARTCARDEx_Exported_Functions_Group2 Extended Peripheral IO operation functions 00206 * @brief SMARTCARD Transmit and Receive functions 00207 * 00208 @verbatim 00209 =============================================================================== 00210 ##### IO operation functions ##### 00211 =============================================================================== 00212 This subsection provides a set of FIFO mode related callback functions. 00213 00214 (#) TX/RX Fifos Callbacks: 00215 (+) HAL_SMARTCARDEx_RxFifoFullCallback() 00216 (+) HAL_SMARTCARDEx_TxFifoEmptyCallback() 00217 00218 00219 @endverbatim 00220 * @{ 00221 */ 00222 00223 #if defined(USART_CR1_FIFOEN) 00224 /** 00225 * @brief SMARTCARD RX Fifo full callback. 00226 * @param hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains 00227 * the configuration information for the specified SMARTCARD module. 00228 * @retval None 00229 */ 00230 __weak void HAL_SMARTCARDEx_RxFifoFullCallback(SMARTCARD_HandleTypeDef *hsmartcard) 00231 { 00232 /* Prevent unused argument(s) compilation warning */ 00233 UNUSED(hsmartcard); 00234 00235 /* NOTE : This function should not be modified, when the callback is needed, 00236 the HAL_SMARTCARDEx_RxFifoFullCallback can be implemented in the user file. 00237 */ 00238 } 00239 00240 /** 00241 * @brief SMARTCARD TX Fifo empty callback. 00242 * @param hsmartcard Pointer to a SMARTCARD_HandleTypeDef structure that contains 00243 * the configuration information for the specified SMARTCARD module. 00244 * @retval None 00245 */ 00246 __weak void HAL_SMARTCARDEx_TxFifoEmptyCallback(SMARTCARD_HandleTypeDef *hsmartcard) 00247 { 00248 /* Prevent unused argument(s) compilation warning */ 00249 UNUSED(hsmartcard); 00250 00251 /* NOTE : This function should not be modified, when the callback is needed, 00252 the HAL_SMARTCARDEx_TxFifoEmptyCallback can be implemented in the user file. 00253 */ 00254 } 00255 #endif 00256 00257 /** 00258 * @} 00259 */ 00260 00261 /** @defgroup SMARTCARD_Exported_Functions_Group3 Extended Peripheral Peripheral Control functions 00262 * @brief SMARTCARD control functions 00263 * 00264 @verbatim 00265 =============================================================================== 00266 ##### Peripheral Control functions ##### 00267 =============================================================================== 00268 [..] 00269 This subsection provides a set of functions allowing to control the SMARTCARD. 00270 (+) HAL_SMARTCARDEx_EnableFifoMode() API enables the FIFO mode 00271 (+) HAL_SMARTCARDEx_DisableFifoMode() API disables the FIFO mode 00272 (+) HAL_SMARTCARDEx_SetTxFifoThreshold() API sets the TX FIFO threshold 00273 (+) HAL_SMARTCARDEx_SetRxFifoThreshold() API sets the RX FIFO threshold 00274 @endverbatim 00275 * @{ 00276 */ 00277 00278 #if defined(USART_CR1_FIFOEN) 00279 /** 00280 * @brief Enable the FIFO mode. 00281 * @param hsmartcard SMARTCARD handle. 00282 * @retval HAL status 00283 */ 00284 HAL_StatusTypeDef HAL_SMARTCARDEx_EnableFifoMode(SMARTCARD_HandleTypeDef *hsmartcard) 00285 { 00286 uint32_t tmpcr1 = 0U; 00287 00288 /* Check parameters */ 00289 assert_param(IS_UART_FIFO_INSTANCE(hsmartcard->Instance)); 00290 00291 /* Process Locked */ 00292 __HAL_LOCK(hsmartcard); 00293 00294 hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY; 00295 00296 /* Save actual SMARTCARD configuration */ 00297 tmpcr1 = READ_REG(hsmartcard->Instance->CR1); 00298 00299 /* Disable SMARTCARD */ 00300 __HAL_SMARTCARD_DISABLE(hsmartcard); 00301 00302 /* Enable FIFO mode */ 00303 SET_BIT(tmpcr1, USART_CR1_FIFOEN); 00304 hsmartcard->FifoMode = SMARTCARD_FIFOMODE_ENABLE; 00305 00306 /* Restore SMARTCARD configuration */ 00307 WRITE_REG(hsmartcard->Instance->CR1, tmpcr1); 00308 00309 /* Determine the number of data to process during RX/TX ISR execution */ 00310 SMARTCARDEx_SetNbDataToProcess(hsmartcard); 00311 00312 hsmartcard->gState = HAL_SMARTCARD_STATE_READY; 00313 00314 /* Process Unlocked */ 00315 __HAL_UNLOCK(hsmartcard); 00316 00317 return HAL_OK; 00318 } 00319 00320 /** 00321 * @brief Disable the FIFO mode. 00322 * @param hsmartcard SMARTCARD handle. 00323 * @retval HAL status 00324 */ 00325 HAL_StatusTypeDef HAL_SMARTCARDEx_DisableFifoMode(SMARTCARD_HandleTypeDef *hsmartcard) 00326 { 00327 uint32_t tmpcr1 = 0U; 00328 00329 /* Check parameters */ 00330 assert_param(IS_UART_FIFO_INSTANCE(hsmartcard->Instance)); 00331 00332 /* Process Locked */ 00333 __HAL_LOCK(hsmartcard); 00334 00335 hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY; 00336 00337 /* Save actual SMARTCARD configuration */ 00338 tmpcr1 = READ_REG(hsmartcard->Instance->CR1); 00339 00340 /* Disable SMARTCARD */ 00341 __HAL_SMARTCARD_DISABLE(hsmartcard); 00342 00343 /* Enable FIFO mode */ 00344 CLEAR_BIT(tmpcr1, USART_CR1_FIFOEN); 00345 hsmartcard->FifoMode = SMARTCARD_FIFOMODE_DISABLE; 00346 00347 /* Restore SMARTCARD configuration */ 00348 WRITE_REG(hsmartcard->Instance->CR1, tmpcr1); 00349 00350 hsmartcard->gState = HAL_SMARTCARD_STATE_READY; 00351 00352 /* Process Unlocked */ 00353 __HAL_UNLOCK(hsmartcard); 00354 00355 return HAL_OK; 00356 } 00357 00358 /** 00359 * @brief Set the TXFIFO threshold. 00360 * @param hsmartcard SMARTCARD handle. 00361 * @param Threshold TX FIFO threshold value 00362 * This parameter can be one of the following values: 00363 * @arg @ref SMARTCARD_TXFIFO_THRESHOLD_1_8 00364 * @arg @ref SMARTCARD_TXFIFO_THRESHOLD_1_4 00365 * @arg @ref SMARTCARD_TXFIFO_THRESHOLD_1_2 00366 * @arg @ref SMARTCARD_TXFIFO_THRESHOLD_3_4 00367 * @arg @ref SMARTCARD_TXFIFO_THRESHOLD_7_8 00368 * @arg @ref SMARTCARD_TXFIFO_THRESHOLD_8_8 00369 * @retval HAL status 00370 */ 00371 HAL_StatusTypeDef HAL_SMARTCARDEx_SetTxFifoThreshold(SMARTCARD_HandleTypeDef *hsmartcard, uint32_t Threshold) 00372 { 00373 uint32_t tmpcr1 = 0U; 00374 00375 /* Check parameters */ 00376 assert_param(IS_UART_FIFO_INSTANCE(hsmartcard->Instance)); 00377 assert_param(IS_SMARTCARD_TXFIFO_THRESHOLD(Threshold)); 00378 00379 /* Process Locked */ 00380 __HAL_LOCK(hsmartcard); 00381 00382 hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY; 00383 00384 /* Save actual SMARTCARD configuration */ 00385 tmpcr1 = READ_REG(hsmartcard->Instance->CR1); 00386 00387 /* Disable SMARTCARD */ 00388 __HAL_SMARTCARD_DISABLE(hsmartcard); 00389 00390 /* Update TX threshold configuration */ 00391 MODIFY_REG(hsmartcard->Instance->CR3, USART_CR3_TXFTCFG, Threshold); 00392 00393 /* Determine the number of data to process during RX/TX ISR execution */ 00394 SMARTCARDEx_SetNbDataToProcess(hsmartcard); 00395 00396 /* Restore SMARTCARD configuration */ 00397 MODIFY_REG(hsmartcard->Instance->CR1, USART_CR1_UE, tmpcr1); 00398 00399 hsmartcard->gState = HAL_SMARTCARD_STATE_READY; 00400 00401 /* Process Unlocked */ 00402 __HAL_UNLOCK(hsmartcard); 00403 00404 return HAL_OK; 00405 } 00406 00407 /** 00408 * @brief Set the RXFIFO threshold. 00409 * @param hsmartcard SMARTCARD handle. 00410 * @param Threshold RX FIFO threshold value 00411 * This parameter can be one of the following values: 00412 * @arg @ref SMARTCARD_RXFIFO_THRESHOLD_1_8 00413 * @arg @ref SMARTCARD_RXFIFO_THRESHOLD_1_4 00414 * @arg @ref SMARTCARD_RXFIFO_THRESHOLD_1_2 00415 * @arg @ref SMARTCARD_RXFIFO_THRESHOLD_3_4 00416 * @arg @ref SMARTCARD_RXFIFO_THRESHOLD_7_8 00417 * @arg @ref SMARTCARD_RXFIFO_THRESHOLD_8_8 00418 * @retval HAL status 00419 */ 00420 HAL_StatusTypeDef HAL_SMARTCARDEx_SetRxFifoThreshold(SMARTCARD_HandleTypeDef *hsmartcard, uint32_t Threshold) 00421 { 00422 uint32_t tmpcr1 = 0U; 00423 00424 /* Check parameters */ 00425 assert_param(IS_UART_FIFO_INSTANCE(hsmartcard->Instance)); 00426 assert_param(IS_SMARTCARD_RXFIFO_THRESHOLD(Threshold)); 00427 00428 /* Process Locked */ 00429 __HAL_LOCK(hsmartcard); 00430 00431 hsmartcard->gState = HAL_SMARTCARD_STATE_BUSY; 00432 00433 /* Save actual SMARTCARD configuration */ 00434 tmpcr1 = READ_REG(hsmartcard->Instance->CR1); 00435 00436 /* Disable SMARTCARD */ 00437 __HAL_SMARTCARD_DISABLE(hsmartcard); 00438 00439 /* Update RX threshold configuration */ 00440 MODIFY_REG(hsmartcard->Instance->CR3, USART_CR3_RXFTCFG, Threshold); 00441 00442 /* Determine the number of data to process during RX/TX ISR execution */ 00443 SMARTCARDEx_SetNbDataToProcess(hsmartcard); 00444 00445 /* Restore SMARTCARD configuration */ 00446 MODIFY_REG(hsmartcard->Instance->CR1, USART_CR1_UE, tmpcr1); 00447 00448 hsmartcard->gState = HAL_SMARTCARD_STATE_READY; 00449 00450 /* Process Unlocked */ 00451 __HAL_UNLOCK(hsmartcard); 00452 00453 return HAL_OK; 00454 } 00455 #endif 00456 00457 /** 00458 * @} 00459 */ 00460 00461 /** 00462 * @} 00463 */ 00464 00465 /** @defgroup SMARTCARDEx_Private_Functions SMARTCARD Extended private Functions 00466 * @{ 00467 */ 00468 00469 #if defined(USART_CR1_FIFOEN) 00470 /** 00471 * @brief Calculate the number of data to process in RX/TX ISR. 00472 * @note The RX FIFO depth and the TX FIFO depth is extracted from 00473 * the USART configuration registers. 00474 * @param hsmartcard SMARTCARD handle. 00475 * @retval None 00476 */ 00477 static void SMARTCARDEx_SetNbDataToProcess(SMARTCARD_HandleTypeDef *hsmartcard) 00478 { 00479 uint8_t rx_fifo_depth; 00480 uint8_t tx_fifo_depth; 00481 uint8_t rx_fifo_threshold; 00482 uint8_t tx_fifo_threshold; 00483 uint8_t numerator[] = {1, 1, 1, 3, 7, 1}; 00484 uint8_t denominator[] = {8, 4, 2, 4, 8, 1}; 00485 00486 if (hsmartcard->FifoMode == SMARTCARD_FIFOMODE_DISABLE) 00487 { 00488 hsmartcard->NbTxDataToProcess = 1U; 00489 hsmartcard->NbRxDataToProcess = 1U; 00490 } 00491 else 00492 { 00493 rx_fifo_depth = RX_FIFO_DEPTH; 00494 tx_fifo_depth = TX_FIFO_DEPTH; 00495 rx_fifo_threshold = (READ_BIT(hsmartcard->Instance->CR3, USART_CR3_RXFTCFG) >> USART_CR3_RXFTCFG_Pos); 00496 tx_fifo_threshold = (READ_BIT(hsmartcard->Instance->CR3, USART_CR3_TXFTCFG) >> USART_CR3_TXFTCFG_Pos); 00497 hsmartcard->NbTxDataToProcess = (tx_fifo_depth * numerator[tx_fifo_threshold]) / denominator[tx_fifo_threshold]; 00498 hsmartcard->NbRxDataToProcess = (rx_fifo_depth * numerator[rx_fifo_threshold]) / denominator[rx_fifo_threshold]; 00499 } 00500 } 00501 #endif 00502 00503 /** 00504 * @} 00505 */ 00506 00507 #endif /* HAL_SMARTCARD_MODULE_ENABLED */ 00508 00509 /** 00510 * @} 00511 */ 00512 00513 /** 00514 * @} 00515 */ 00516 00517 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/