1 /**************************************************************************//** 2 * @file scuart.h 3 * @version V3.00 4 * @brief Smartcard UART mode (SCUART) driver header file 5 * 6 * @copyright SPDX-License-Identifier: Apache-2.0 7 * @copyright Copyright (C) 2021 Nuvoton Technology Corp. All rights reserved. 8 *****************************************************************************/ 9 #ifndef __SCUART_H__ 10 #define __SCUART_H__ 11 12 #ifdef __cplusplus 13 extern "C" 14 { 15 #endif 16 17 18 /** @addtogroup Standard_Driver Standard Driver 19 @{ 20 */ 21 22 /** @addtogroup SCUART_Driver SCUART Driver 23 @{ 24 */ 25 26 /** @addtogroup SCUART_EXPORTED_CONSTANTS SCUART Exported Constants 27 @{ 28 */ 29 #define SCUART_CHAR_LEN_5 (0x3UL << SC_UARTCTL_WLS_Pos) /*!< Set SCUART word length to 5 bits \hideinitializer */ 30 #define SCUART_CHAR_LEN_6 (0x2UL << SC_UARTCTL_WLS_Pos) /*!< Set SCUART word length to 6 bits \hideinitializer */ 31 #define SCUART_CHAR_LEN_7 (0x1UL << SC_UARTCTL_WLS_Pos) /*!< Set SCUART word length to 7 bits \hideinitializer */ 32 #define SCUART_CHAR_LEN_8 (0UL) /*!< Set SCUART word length to 8 bits \hideinitializer */ 33 34 #define SCUART_PARITY_NONE (SC_UARTCTL_PBOFF_Msk) /*!< Set SCUART transfer with no parity \hideinitializer */ 35 #define SCUART_PARITY_ODD (SC_UARTCTL_OPE_Msk) /*!< Set SCUART transfer with odd parity \hideinitializer */ 36 #define SCUART_PARITY_EVEN (0UL) /*!< Set SCUART transfer with even parity \hideinitializer */ 37 38 #define SCUART_STOP_BIT_1 (SC_CTL_NSB_Msk) /*!< Set SCUART transfer with one stop bit \hideinitializer */ 39 #define SCUART_STOP_BIT_2 (0UL) /*!< Set SCUART transfer with two stop bits \hideinitializer */ 40 41 /**@}*/ /* end of group SCUART_EXPORTED_CONSTANTS */ 42 43 /** @addtogroup SCUART_EXPORTED_FUNCTIONS SCUART Exported Functions 44 @{ 45 */ 46 47 /* TX Macros */ 48 /** 49 * @brief Write Data to Tx data register 50 * 51 * @param[in] sc The pointer of smartcard module. 52 * @param[in] u8Data Data byte to transmit. 53 * 54 * @return None 55 * 56 * @details By writing data to DAT register, the SC will send out an 8-bit data. 57 * \hideinitializer 58 */ 59 #define SCUART_WRITE(sc, u8Data) ((sc)->DAT = (u8Data)) 60 61 /** 62 * @brief Get Tx FIFO empty flag status from register 63 * 64 * @param[in] sc The pointer of smartcard module. 65 * 66 * @return Transmit FIFO empty status 67 * @retval 0 Transmit FIFO is not empty 68 * @retval SC_STATUS_TXEMPTY_Msk Transmit FIFO is empty 69 * 70 * @details When the last byte of Tx buffer has been transferred to Transmitter Shift Register, hardware sets TXEMPTY (SC_STATUS[9]) high. 71 * It will be cleared when writing data into DAT (SC_DAT[7:0]). 72 * \hideinitializer 73 */ 74 #define SCUART_GET_TX_EMPTY(sc) ((sc)->STATUS & SC_STATUS_TXEMPTY_Msk) 75 76 /** 77 * @brief Get Tx FIFO full flag status from register 78 * 79 * @param[in] sc The pointer of smartcard module. 80 * 81 * @return Transmit FIFO full status 82 * @retval 0 Transmit FIFO is not full 83 * @retval SC_STATUS_TXFULL_Msk Transmit FIFO is full 84 * 85 * @details TXFULL (SC_STATUS[10]) is set when Tx buffer counts equals to 4, otherwise is cleared by hardware. 86 * \hideinitializer 87 */ 88 #define SCUART_GET_TX_FULL(sc) ((sc)->STATUS & SC_STATUS_TXFULL_Msk) 89 90 /** 91 * @brief Wait specified smartcard port transmission complete 92 * 93 * @param[in] sc The pointer of smartcard module. 94 * 95 * @return None 96 * 97 * @details TXACT (SC_STATUS[31]) is cleared automatically when Tx transfer is finished or the last byte transmission has completed. 98 * 99 * @note This macro blocks until transmit complete. 100 * \hideinitializer 101 */ 102 #define SCUART_WAIT_TX_EMPTY(sc) while(((sc)->STATUS & SC_STATUS_TXACT_Msk) == SC_STATUS_TXACT_Msk) 103 104 /** 105 * @brief Check specified smartcard port transmit FIFO is full or not 106 * 107 * @param[in] sc The pointer of smartcard module. 108 * 109 * @return Transmit FIFO full status 110 * @retval 0 Transmit FIFO is not full 111 * @retval 1 Transmit FIFO is full 112 * 113 * @details TXFULL (SC_STATUS[10]) indicates Tx buffer full or not. 114 * This bit is set when Tx buffer counts equals to 4, otherwise is cleared by hardware. 115 * \hideinitializer 116 */ 117 #define SCUART_IS_TX_FULL(sc) (((sc)->STATUS & SC_STATUS_TXFULL_Msk)? 1 : 0) 118 119 /** 120 * @brief Check specified smartcard port transmission is over 121 * 122 * @param[in] sc The pointer of smartcard module. 123 * 124 * @return Transmit complete status 125 * @retval 0 Transmit is not complete 126 * @retval 1 Transmit complete 127 * 128 * @details TXACT (SC_STATUS[31]) indicates Tx Transmit is complete or not. 129 * \hideinitializer 130 */ 131 #define SCUART_IS_TX_EMPTY(sc) (((sc)->STATUS & SC_STATUS_TXACT_Msk)? 0 : 1) 132 133 /** 134 * @brief Check specified smartcard port transmit FIFO empty status 135 * 136 * @param[in] sc The pointer of smartcard module. 137 * 138 * @return Transmit FIFO empty status 139 * @retval 0 Transmit FIFO is not empty 140 * @retval 1 Transmit FIFO is empty 141 * 142 * @details TXEMPTY (SC_STATUS[9]) is set by hardware when the last byte of Tx buffer has been transferred to Transmitter Shift Register. 143 * \hideinitializer 144 */ 145 #define SCUART_IS_TX_FIFO_EMPTY(sc) (((sc)->STATUS & SC_STATUS_TXEMPTY_Msk)? 1 : 0) 146 147 /** 148 * @brief Check specified Smartcard port Transmission Status 149 * 150 * @param[in] sc The pointer of smartcard module. 151 * 152 * @retval 0 Transmit is completed 153 * @retval 1 Transmit is active 154 * 155 * @details TXACT (SC_STATUS[31]) is set by hardware when Tx transfer is in active and the STOP bit of the last byte has been transmitted. 156 * \hideinitializer 157 */ 158 #define SCUART_IS_TX_ACTIVE(sc) (((sc)->STATUS & SC_STATUS_TXACT_Msk)? 1 : 0) 159 160 161 /* RX Macros */ 162 /** 163 * @brief Read Rx data register 164 * 165 * @param[in] sc The pointer of smartcard module. 166 * 167 * @return The oldest data byte in RX FIFO 168 * 169 * @details By reading DAT register, the SC will return an 8-bit received data. 170 * \hideinitializer 171 */ 172 #define SCUART_READ(sc) ((sc)->DAT) 173 174 /** 175 * @brief Get Rx FIFO empty flag status from register 176 * 177 * @param[in] sc The pointer of smartcard module. 178 * 179 * @return Receive FIFO empty status 180 * @retval 0 Receive FIFO is not empty 181 * @retval SC_STATUS_RXEMPTY_Msk Receive FIFO is empty 182 * 183 * @details When the last byte of Rx buffer has been read by CPU, hardware sets RXEMPTY (SC_STATUS[1]) high. 184 * It will be cleared when SC receives any new data. 185 * \hideinitializer 186 */ 187 #define SCUART_GET_RX_EMPTY(sc) ((sc)->STATUS & SC_STATUS_RXEMPTY_Msk) 188 189 /** 190 * @brief Get Rx FIFO full flag status from register 191 * 192 * @param[in] sc The pointer of smartcard module. 193 * 194 * @return Receive FIFO full status 195 * @retval 0 Receive FIFO is not full 196 * @retval SC_STATUS_TXFULL_Msk Receive FIFO is full 197 * 198 * @details RXFULL (SC_STATUS[2]) is set when Rx buffer counts equals to 4, otherwise it is cleared by hardware. 199 * \hideinitializer 200 */ 201 #define SCUART_GET_RX_FULL(sc) ((sc)->STATUS & SC_STATUS_RXFULL_Msk) 202 203 /** 204 * @brief Check if receive data number in FIFO reach FIFO trigger level or not 205 * 206 * @param[in] sc The pointer of smartcard module. 207 * 208 * @return Receive FIFO data status 209 * @retval 0 The number of bytes in receive FIFO is less than trigger level 210 * @retval 1 The number of bytes in receive FIFO equals or larger than trigger level 211 * 212 * @details RDAIF (SC_INTSTS[0]) is used for received data reaching trigger level RXTRGLV (SC_CTL[7:6]) interrupt status flag. 213 * 214 * @note If receive trigger level is \b not 1 byte, this macro return 0 does not necessary indicates there is no data in FIFO. 215 * \hideinitializer 216 */ 217 #define SCUART_IS_RX_READY(sc) (((sc)->INTSTS & SC_INTSTS_RDAIF_Msk)? 1 : 0) 218 219 /** 220 * @brief Check specified smartcard port receive FIFO is full or not 221 * 222 * @param[in] sc The pointer of smartcard module. 223 * 224 * @return Receive FIFO full status 225 * @retval 0 Receive FIFO is not full 226 * @retval 1 Receive FIFO is full 227 * 228 * @details RXFULLF( SC_STATUS[2]) is set when Rx buffer counts equals to 4, otherwise it is cleared by hardware. 229 * \hideinitializer 230 */ 231 #define SCUART_IS_RX_FULL(sc) (((sc)->STATUS & SC_STATUS_RXFULL_Msk)? 1 : 0) 232 233 234 /* Interrupt Macros */ 235 /** 236 * @brief Enable specified interrupts 237 * 238 * @param[in] sc The pointer of smartcard module. 239 * @param[in] u32Mask Interrupt masks to enable, a combination of following bits, 240 * - \ref SC_INTEN_RXTOIEN_Msk 241 * - \ref SC_INTEN_TERRIEN_Msk 242 * - \ref SC_INTEN_TBEIEN_Msk 243 * - \ref SC_INTEN_RDAIEN_Msk 244 * 245 * @return None 246 * 247 * @details The macro is used to enable receiver buffer time-out interrupt, transfer error interrupt, 248 * transmit buffer empty interrupt or receive data reach trigger level interrupt. 249 * \hideinitializer 250 */ 251 #define SCUART_ENABLE_INT(sc, u32Mask) ((sc)->INTEN |= (u32Mask)) 252 253 /** 254 * @brief Disable specified interrupts 255 * 256 * @param[in] sc The pointer of smartcard module. 257 * @param[in] u32Mask Interrupt masks to disable, a combination of following bits, 258 * - \ref SC_INTEN_RXTOIEN_Msk 259 * - \ref SC_INTEN_TERRIEN_Msk 260 * - \ref SC_INTEN_TBEIEN_Msk 261 * - \ref SC_INTEN_RDAIEN_Msk 262 * 263 * @return None 264 * 265 * @details The macro is used to disable receiver buffer time-out interrupt, transfer error interrupt, 266 * transmit buffer empty interrupt or receive data reach trigger level interrupt. 267 * \hideinitializer 268 */ 269 #define SCUART_DISABLE_INT(sc, u32Mask) ((sc)->INTEN &= ~(u32Mask)) 270 271 /** 272 * @brief Get specified interrupt flag/status 273 * 274 * @param[in] sc The pointer of smartcard module. 275 * @param[in] u32Type Interrupt flag/status to check, could be one of following value 276 * - \ref SC_INTSTS_RXTOIF_Msk 277 * - \ref SC_INTSTS_TERRIF_Msk 278 * - \ref SC_INTSTS_TBEIF_Msk 279 * - \ref SC_INTSTS_RDAIF_Msk 280 * 281 * @return The status of specified interrupt 282 * @retval 0 Specified interrupt does not happened 283 * @retval 1 Specified interrupt happened 284 * 285 * @details The macro is used to get receiver buffer time-out interrupt status, transfer error interrupt status, 286 * transmit buffer empty interrupt status or receive data reach interrupt status. 287 * \hideinitializer 288 */ 289 #define SCUART_GET_INT_FLAG(sc, u32Type) (((sc)->INTSTS & (u32Type))? 1 : 0) 290 291 /** 292 * @brief Clear specified interrupt flag/status 293 * 294 * @param[in] sc The pointer of smartcard module. 295 * @param[in] u32Type Interrupt flag/status to clear, only \ref SC_INTSTS_TERRIF_Msk valid for this macro. 296 * 297 * @return None 298 * 299 * @details The macro is used to clear transfer error interrupt flag. 300 * \hideinitializer 301 */ 302 #define SCUART_CLR_INT_FLAG(sc, u32Type) ((sc)->INTSTS = (u32Type)) 303 304 /** 305 * @brief Get receive error flag/status 306 * 307 * @param[in] sc The pointer of smartcard module. 308 * 309 * @return Current receive error status, could one of following errors: 310 * @retval SC_STATUS_PEF_Msk Parity error 311 * @retval SC_STATUS_FEF_Msk Frame error 312 * @retval SC_STATUS_BEF_Msk Break error 313 * 314 * @details The macro is used to get receiver parity error status, frame error status or break error status. 315 * \hideinitializer 316 */ 317 #define SCUART_GET_ERR_FLAG(sc) ((sc)->STATUS & (SC_STATUS_PEF_Msk | SC_STATUS_FEF_Msk | SC_STATUS_BEF_Msk)) 318 319 /** 320 * @brief Clear specified receive error flag/status 321 * 322 * @param[in] sc The pointer of smartcard module. 323 * @param[in] u32Mask Receive error flag/status to clear, combination following values 324 * - \ref SC_STATUS_PEF_Msk 325 * - \ref SC_STATUS_FEF_Msk 326 * - \ref SC_STATUS_BEF_Msk 327 * 328 * @return None 329 * 330 * @details The macro is used to clear receiver parity error flag, frame error flag or break error flag. 331 * \hideinitializer 332 */ 333 #define SCUART_CLR_ERR_FLAG(sc, u32Mask) ((sc)->STATUS = (u32Mask)) 334 335 void SCUART_Close(SC_T* sc); 336 uint32_t SCUART_Open(SC_T* sc, uint32_t u32Baudrate); 337 uint32_t SCUART_Read(SC_T* sc, uint8_t pu8RxBuf[], uint32_t u32ReadBytes); 338 uint32_t SCUART_SetLineConfig(SC_T* sc, uint32_t u32Baudrate, uint32_t u32DataWidth, uint32_t u32Parity, uint32_t u32StopBits); 339 void SCUART_SetTimeoutCnt(SC_T* sc, uint32_t u32TOC); 340 uint32_t SCUART_Write(SC_T* sc, uint8_t pu8TxBuf[], uint32_t u32WriteBytes); 341 342 /**@}*/ /* end of group SCUART_EXPORTED_FUNCTIONS */ 343 344 /**@}*/ /* end of group SCUART_Driver */ 345 346 /**@}*/ /* end of group Standard_Driver */ 347 348 #ifdef __cplusplus 349 } 350 #endif 351 352 #endif /* __SCUART_H__ */ 353
