1 /*********************************************************************************************************************** 2 * Copyright [2020-2022] Renesas Electronics Corporation and/or its affiliates. All Rights Reserved. 3 * 4 * This software and documentation are supplied by Renesas Electronics America Inc. and may only be used with products 5 * of Renesas Electronics Corp. and its affiliates ("Renesas"). No other uses are authorized. Renesas products are 6 * sold pursuant to Renesas terms and conditions of sale. Purchasers are solely responsible for the selection and use 7 * of Renesas products and Renesas assumes no liability. No license, express or implied, to any intellectual property 8 * right is granted by Renesas. This software is protected under all applicable laws, including copyright laws. Renesas 9 * reserves the right to change or discontinue this software and/or this documentation. THE SOFTWARE AND DOCUMENTATION 10 * IS DELIVERED TO YOU "AS IS," AND RENESAS MAKES NO REPRESENTATIONS OR WARRANTIES, AND TO THE FULLEST EXTENT 11 * PERMISSIBLE UNDER APPLICABLE LAW, DISCLAIMS ALL WARRANTIES, WHETHER EXPLICITLY OR IMPLICITLY, INCLUDING WARRANTIES 12 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT, WITH RESPECT TO THE SOFTWARE OR 13 * DOCUMENTATION. RENESAS SHALL HAVE NO LIABILITY ARISING OUT OF ANY SECURITY VULNERABILITY OR BREACH. TO THE MAXIMUM 14 * EXTENT PERMITTED BY LAW, IN NO EVENT WILL RENESAS BE LIABLE TO YOU IN CONNECTION WITH THE SOFTWARE OR DOCUMENTATION 15 * (OR ANY PERSON OR ENTITY CLAIMING RIGHTS DERIVED FROM YOU) FOR ANY LOSS, DAMAGES, OR CLAIMS WHATSOEVER, INCLUDING, 16 * WITHOUT LIMITATION, ANY DIRECT, CONSEQUENTIAL, SPECIAL, INDIRECT, PUNITIVE, OR INCIDENTAL DAMAGES; ANY LOST PROFITS, 17 * OTHER ECONOMIC DAMAGE, PROPERTY DAMAGE, OR PERSONAL INJURY; AND EVEN IF RENESAS HAS BEEN ADVISED OF THE POSSIBILITY 18 * OF SUCH LOSS, DAMAGES, CLAIMS OR COSTS. 19 **********************************************************************************************************************/ 20 21 /*******************************************************************************************************************//** 22 * @ingroup RENESAS_INTERFACES 23 * @defgroup UART_API UART Interface 24 * @brief Interface for UART communications. 25 * 26 * @section UART_INTERFACE_SUMMARY Summary 27 * The UART interface provides common APIs for UART HAL drivers. The UART interface supports the following features: 28 * - Full-duplex UART communication 29 * - Interrupt driven transmit/receive processing 30 * - Callback function with returned event code 31 * - Runtime baud-rate change 32 * - Hardware resource locking during a transaction 33 * - CTS/RTS hardware flow control support (with an associated IOPORT pin) 34 * 35 * Implemented by: 36 * - @ref SCI_UART 37 * - @ref SCI_B_UART 38 * 39 * @{ 40 **********************************************************************************************************************/ 41 42 #ifndef R_UART_API_H 43 #define R_UART_API_H 44 45 /*********************************************************************************************************************** 46 * Includes 47 **********************************************************************************************************************/ 48 49 /* Includes board and MCU related header files. */ 50 #include "bsp_api.h" 51 #include "r_transfer_api.h" 52 53 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 54 FSP_HEADER 55 56 /********************************************************************************************************************** 57 * Macro definitions 58 **********************************************************************************************************************/ 59 60 /********************************************************************************************************************** 61 * Typedef definitions 62 **********************************************************************************************************************/ 63 64 /** UART Event codes */ 65 typedef enum e_sf_event 66 { 67 UART_EVENT_RX_COMPLETE = (1UL << 0), ///< Receive complete event 68 UART_EVENT_TX_COMPLETE = (1UL << 1), ///< Transmit complete event 69 UART_EVENT_RX_CHAR = (1UL << 2), ///< Character received 70 UART_EVENT_ERR_PARITY = (1UL << 3), ///< Parity error event 71 UART_EVENT_ERR_FRAMING = (1UL << 4), ///< Mode fault error event 72 UART_EVENT_ERR_OVERFLOW = (1UL << 5), ///< FIFO Overflow error event 73 UART_EVENT_BREAK_DETECT = (1UL << 6), ///< Break detect error event 74 UART_EVENT_TX_DATA_EMPTY = (1UL << 7), ///< Last byte is transmitting, ready for more data 75 } uart_event_t; 76 77 /** UART Data bit length definition */ 78 typedef enum e_uart_data_bits 79 { 80 UART_DATA_BITS_9 = 0U, ///< Data bits 9-bit 81 UART_DATA_BITS_8 = 2U, ///< Data bits 8-bit 82 UART_DATA_BITS_7 = 3U, ///< Data bits 7-bit 83 } uart_data_bits_t; 84 85 /** UART Parity definition */ 86 typedef enum e_uart_parity 87 { 88 UART_PARITY_OFF = 0U, ///< No parity 89 UART_PARITY_EVEN = 2U, ///< Even parity 90 UART_PARITY_ODD = 3U, ///< Odd parity 91 } uart_parity_t; 92 93 /** UART Stop bits definition */ 94 typedef enum e_uart_stop_bits 95 { 96 UART_STOP_BITS_1 = 0U, ///< Stop bit 1-bit 97 UART_STOP_BITS_2 = 1U, ///< Stop bits 2-bit 98 } uart_stop_bits_t; 99 100 /** UART transaction definition */ 101 typedef enum e_uart_dir 102 { 103 UART_DIR_RX_TX = 3U, ///< Both RX and TX 104 UART_DIR_RX = 1U, ///< Only RX 105 UART_DIR_TX = 2U, ///< Only TX 106 } uart_dir_t; 107 108 /** UART driver specific information */ 109 typedef struct st_uart_info 110 { 111 /** Maximum bytes that can be written at this time. Only applies if uart_cfg_t::p_transfer_tx is not NULL. */ 112 uint32_t write_bytes_max; 113 114 /** Maximum bytes that are available to read at one time. Only applies if uart_cfg_t::p_transfer_rx is not NULL. */ 115 uint32_t read_bytes_max; 116 } uart_info_t; 117 118 /** UART Callback parameter definition */ 119 typedef struct st_uart_callback_arg 120 { 121 uint32_t channel; ///< Device channel number 122 uart_event_t event; ///< Event code 123 124 /** Contains the next character received for the events UART_EVENT_RX_CHAR, UART_EVENT_ERR_PARITY, 125 * UART_EVENT_ERR_FRAMING, or UART_EVENT_ERR_OVERFLOW. Otherwise unused. */ 126 uint32_t data; 127 void const * p_context; ///< Context provided to user during callback 128 } uart_callback_args_t; 129 130 /** UART Configuration */ 131 typedef struct st_uart_cfg 132 { 133 /* UART generic configuration */ 134 uint8_t channel; ///< Select a channel corresponding to the channel number of the hardware. 135 uart_data_bits_t data_bits; ///< Data bit length (8 or 7 or 9) 136 uart_parity_t parity; ///< Parity type (none or odd or even) 137 uart_stop_bits_t stop_bits; ///< Stop bit length (1 or 2) 138 uint8_t rxi_ipl; ///< Receive interrupt priority 139 IRQn_Type rxi_irq; ///< Receive interrupt IRQ number 140 uint8_t txi_ipl; ///< Transmit interrupt priority 141 IRQn_Type txi_irq; ///< Transmit interrupt IRQ number 142 uint8_t tei_ipl; ///< Transmit end interrupt priority 143 IRQn_Type tei_irq; ///< Transmit end interrupt IRQ number 144 uint8_t eri_ipl; ///< Error interrupt priority 145 IRQn_Type eri_irq; ///< Error interrupt IRQ number 146 147 /** Optional transfer instance used to receive multiple bytes without interrupts. Set to NULL if unused. 148 * If NULL, the number of bytes allowed in the read API is limited to one byte at a time. */ 149 transfer_instance_t const * p_transfer_rx; 150 151 /** Optional transfer instance used to send multiple bytes without interrupts. Set to NULL if unused. 152 * If NULL, the number of bytes allowed in the write APIs is limited to one byte at a time. */ 153 transfer_instance_t const * p_transfer_tx; 154 155 /* Configuration for UART Event processing */ 156 void (* p_callback)(uart_callback_args_t * p_args); ///< Pointer to callback function 157 void const * p_context; ///< User defined context passed into callback function 158 159 /* Pointer to UART peripheral specific configuration */ 160 void const * p_extend; ///< UART hardware dependent configuration 161 } uart_cfg_t; 162 163 /** UART control block. Allocate an instance specific control block to pass into the UART API calls. 164 * @par Implemented as 165 * - sci_uart_instance_ctrl_t 166 */ 167 typedef void uart_ctrl_t; 168 169 /** Shared Interface definition for UART */ 170 typedef struct st_uart_api 171 { 172 /** Open UART device. 173 * @par Implemented as 174 * - @ref R_SCI_UART_Open() 175 * - @ref R_SCI_B_UART_Open() 176 * 177 * @param[in,out] p_ctrl Pointer to the UART control block. Must be declared by user. Value set here. 178 * @param[in] uart_cfg_t Pointer to UART configuration structure. All elements of this structure must be set by 179 * user. 180 */ 181 fsp_err_t (* open)(uart_ctrl_t * const p_ctrl, uart_cfg_t const * const p_cfg); 182 183 /** Read from UART device. The read buffer is used until the read is complete. When a transfer is complete, the 184 * callback is called with event UART_EVENT_RX_COMPLETE. Bytes received outside an active transfer are received in 185 * the callback function with event UART_EVENT_RX_CHAR. 186 * The maximum transfer size is reported by infoGet(). 187 * @par Implemented as 188 * - @ref R_SCI_UART_Read() 189 * - @ref R_SCI_B_UART_Read() 190 * 191 * @param[in] p_ctrl Pointer to the UART control block for the channel. 192 * @param[in] p_dest Destination address to read data from. 193 * @param[in] bytes Read data length. 194 */ 195 fsp_err_t (* read)(uart_ctrl_t * const p_ctrl, uint8_t * const p_dest, uint32_t const bytes); 196 197 /** Write to UART device. The write buffer is used until write is complete. Do not overwrite write buffer 198 * contents until the write is finished. When the write is complete (all bytes are fully transmitted on the wire), 199 * the callback called with event UART_EVENT_TX_COMPLETE. 200 * The maximum transfer size is reported by infoGet(). 201 * @par Implemented as 202 * - @ref R_SCI_UART_Write() 203 * - @ref R_SCI_B_UART_Write() 204 * 205 * @param[in] p_ctrl Pointer to the UART control block. 206 * @param[in] p_src Source address to write data to. 207 * @param[in] bytes Write data length. 208 */ 209 fsp_err_t (* write)(uart_ctrl_t * const p_ctrl, uint8_t const * const p_src, uint32_t const bytes); 210 211 /** Change baud rate. 212 * @warning Calling this API aborts any in-progress transmission and disables reception until the new baud 213 * settings have been applied. 214 * 215 * @par Implemented as 216 * - @ref R_SCI_UART_BaudSet() 217 * - @ref R_SCI_B_UART_BaudSet() 218 * 219 * @param[in] p_ctrl Pointer to the UART control block. 220 * @param[in] p_baudrate_info Pointer to module specific information for configuring baud rate. 221 */ 222 fsp_err_t (* baudSet)(uart_ctrl_t * const p_ctrl, void const * const p_baudrate_info); 223 224 /** Get the driver specific information. 225 * @par Implemented as 226 * - @ref R_SCI_UART_InfoGet() 227 * - @ref R_SCI_B_UART_InfoGet() 228 * 229 * @param[in] p_ctrl Pointer to the UART control block. 230 * @param[in] baudrate Baud rate in bps. 231 */ 232 fsp_err_t (* infoGet)(uart_ctrl_t * const p_ctrl, uart_info_t * const p_info); 233 234 /** 235 * Abort ongoing transfer. 236 * @par Implemented as 237 * - @ref R_SCI_UART_Abort() 238 * - @ref R_SCI_B_UART_Abort() 239 * 240 * @param[in] p_ctrl Pointer to the UART control block. 241 * @param[in] communication_to_abort Type of abort request. 242 */ 243 fsp_err_t (* communicationAbort)(uart_ctrl_t * const p_ctrl, uart_dir_t communication_to_abort); 244 245 /** 246 * Specify callback function and optional context pointer and working memory pointer. 247 * @par Implemented as 248 * - R_SCI_Uart_CallbackSet() 249 * - R_SCI_B_Uart_CallbackSet() 250 * 251 * @param[in] p_ctrl Pointer to the UART control block. 252 * @param[in] p_callback Callback function 253 * @param[in] p_context Pointer to send to callback function 254 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 255 * Callback arguments allocated here are only valid during the callback. 256 */ 257 fsp_err_t (* callbackSet)(uart_ctrl_t * const p_api_ctrl, void (* p_callback)(uart_callback_args_t *), 258 void const * const p_context, uart_callback_args_t * const p_callback_memory); 259 260 /** Close UART device. 261 * @par Implemented as 262 * - @ref R_SCI_UART_Close() 263 * - @ref R_SCI_B_UART_Close() 264 * 265 * @param[in] p_ctrl Pointer to the UART control block. 266 */ 267 fsp_err_t (* close)(uart_ctrl_t * const p_ctrl); 268 269 /** Stop ongoing read and return the number of bytes remaining in the read. 270 * @par Implemented as 271 * - @ref R_SCI_UART_ReadStop() 272 * - @ref R_SCI_B_UART_ReadStop() 273 * 274 * @param[in] p_ctrl Pointer to the UART control block. 275 * @param[in,out] remaining_bytes Pointer to location to store remaining bytes for read. 276 */ 277 fsp_err_t (* readStop)(uart_ctrl_t * const p_ctrl, uint32_t * remaining_bytes); 278 } uart_api_t; 279 280 /** This structure encompasses everything that is needed to use an instance of this interface. */ 281 typedef struct st_uart_instance 282 { 283 uart_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 284 uart_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 285 uart_api_t const * p_api; ///< Pointer to the API structure for this instance 286 } uart_instance_t; 287 288 /** @} (end defgroup UART_API) */ 289 290 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 291 FSP_FOOTER 292 293 #endif 294