1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /*******************************************************************************************************************//** 8 * @ingroup RENESAS_INTERFACES 9 * @defgroup UART_API UART Interface 10 * @brief Interface for UART communications. 11 * 12 * @section UART_INTERFACE_SUMMARY Summary 13 * The UART interface provides common APIs for UART HAL drivers. The UART interface supports the following features: 14 * - Full-duplex UART communication 15 * - Interrupt driven transmit/receive processing 16 * - Callback function with returned event code 17 * - Runtime baud-rate change 18 * - Hardware resource locking during a transaction 19 * - CTS/RTS hardware flow control support (with an associated IOPORT pin) 20 * 21 * Implemented by: 22 * - @ref SCIF_UART 23 * 24 * @{ 25 **********************************************************************************************************************/ 26 27 #ifndef R_UART_API_H 28 #define R_UART_API_H 29 30 /*********************************************************************************************************************** 31 * Includes 32 **********************************************************************************************************************/ 33 34 /* Includes board and MCU related header files. */ 35 #include "bsp_api.h" 36 #include "r_transfer_api.h" 37 38 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 39 FSP_HEADER 40 41 /********************************************************************************************************************** 42 * Macro definitions 43 **********************************************************************************************************************/ 44 45 /********************************************************************************************************************** 46 * Typedef definitions 47 **********************************************************************************************************************/ 48 49 /** UART Event codes */ 50 typedef enum e_sf_event 51 { 52 UART_EVENT_RX_COMPLETE = (1UL << 0), ///< Receive complete event 53 UART_EVENT_TX_COMPLETE = (1UL << 1), ///< Transmit complete event 54 UART_EVENT_RX_CHAR = (1UL << 2), ///< Character received 55 UART_EVENT_ERR_PARITY = (1UL << 3), ///< Parity error event 56 UART_EVENT_ERR_FRAMING = (1UL << 4), ///< Mode fault error event 57 UART_EVENT_ERR_OVERFLOW = (1UL << 5), ///< FIFO Overflow error event 58 UART_EVENT_BREAK_DETECT = (1UL << 6), ///< Break detect error event 59 UART_EVENT_TX_DATA_EMPTY = (1UL << 7), ///< Last byte is transmitting, ready for more data 60 } uart_event_t; 61 62 /** UART Data bit length definition */ 63 typedef enum e_uart_data_bits 64 { 65 UART_DATA_BITS_9 = 0U, ///< Data bits 9-bit 66 UART_DATA_BITS_8 = 2U, ///< Data bits 8-bit 67 UART_DATA_BITS_7 = 3U, ///< Data bits 7-bit 68 } uart_data_bits_t; 69 70 /** UART Parity definition */ 71 typedef enum e_uart_parity 72 { 73 UART_PARITY_OFF = 0U, ///< No parity 74 UART_PARITY_EVEN = 2U, ///< Even parity 75 UART_PARITY_ODD = 3U, ///< Odd parity 76 } uart_parity_t; 77 78 /** UART Stop bits definition */ 79 typedef enum e_uart_stop_bits 80 { 81 UART_STOP_BITS_1 = 0U, ///< Stop bit 1-bit 82 UART_STOP_BITS_2 = 1U, ///< Stop bits 2-bit 83 } uart_stop_bits_t; 84 85 /** UART transaction definition */ 86 typedef enum e_uart_dir 87 { 88 UART_DIR_RX_TX = 3U, ///< Both RX and TX 89 UART_DIR_RX = 1U, ///< Only RX 90 UART_DIR_TX = 2U, ///< Only TX 91 } uart_dir_t; 92 93 /** UART driver specific information */ 94 typedef struct st_uart_info 95 { 96 /** Maximum bytes that can be written at this time. Only applies if uart_cfg_t::p_transfer_tx is not NULL. */ 97 uint32_t write_bytes_max; 98 99 /** Maximum bytes that are available to read at one time. Only applies if uart_cfg_t::p_transfer_rx is not NULL. */ 100 uint32_t read_bytes_max; 101 } uart_info_t; 102 103 /** UART Callback parameter definition */ 104 typedef struct st_uart_callback_arg 105 { 106 uint32_t channel; ///< Device channel number 107 uart_event_t event; ///< Event code 108 109 /** Contains the next character received for the events UART_EVENT_RX_CHAR, UART_EVENT_ERR_PARITY, 110 * UART_EVENT_ERR_FRAMING, or UART_EVENT_ERR_OVERFLOW. Otherwise unused. */ 111 uint32_t data; 112 void const * p_context; ///< Context provided to user during callback 113 } uart_callback_args_t; 114 115 /** UART Configuration */ 116 typedef struct st_uart_cfg 117 { 118 /* UART generic configuration */ 119 uint8_t channel; ///< Select a channel corresponding to the channel number of the hardware. 120 uart_data_bits_t data_bits; ///< Data bit length (8 or 7 or 9) 121 uart_parity_t parity; ///< Parity type (none or odd or even) 122 uart_stop_bits_t stop_bits; ///< Stop bit length (1 or 2) 123 uint8_t rxi_ipl; ///< Receive interrupt priority 124 IRQn_Type rxi_irq; ///< Receive interrupt IRQ number 125 uint8_t txi_ipl; ///< Transmit interrupt priority 126 IRQn_Type txi_irq; ///< Transmit interrupt IRQ number 127 uint8_t tei_ipl; ///< Transmit end interrupt priority 128 IRQn_Type tei_irq; ///< Transmit end interrupt IRQ number 129 uint8_t eri_ipl; ///< Error interrupt priority 130 IRQn_Type eri_irq; ///< Error interrupt IRQ number 131 132 /** Optional transfer instance used to receive multiple bytes without interrupts. Set to NULL if unused. 133 * If NULL, the number of bytes allowed in the read API is limited to one byte at a time. */ 134 transfer_instance_t const * p_transfer_rx; 135 136 /** Optional transfer instance used to send multiple bytes without interrupts. Set to NULL if unused. 137 * If NULL, the number of bytes allowed in the write APIs is limited to one byte at a time. */ 138 transfer_instance_t const * p_transfer_tx; 139 140 /* Configuration for UART Event processing */ 141 void (* p_callback)(uart_callback_args_t * p_args); ///< Pointer to callback function 142 void const * p_context; ///< User defined context passed into callback function 143 144 /* Pointer to UART peripheral specific configuration */ 145 void const * p_extend; ///< UART hardware dependent configuration 146 } uart_cfg_t; 147 148 /** UART control block. Allocate an instance specific control block to pass into the UART API calls. 149 * @par Implemented as 150 * - scif_uart_instance_ctrl_t 151 */ 152 typedef void uart_ctrl_t; 153 154 /** Shared Interface definition for UART */ 155 typedef struct st_uart_api 156 { 157 /** Open UART device. 158 * @par Implemented as 159 * - @ref R_SCIF_UART_Open() 160 * 161 * @param[in,out] p_ctrl Pointer to the UART control block. Must be declared by user. Value set here. 162 * @param[in] uart_cfg_t Pointer to UART configuration structure. All elements of this structure must be set by 163 * user. 164 */ 165 fsp_err_t (* open)(uart_ctrl_t * const p_ctrl, uart_cfg_t const * const p_cfg); 166 167 /** Read from UART device. The read buffer is used until the read is complete. When a transfer is complete, the 168 * callback is called with event UART_EVENT_RX_COMPLETE. Bytes received outside an active transfer are received in 169 * the callback function with event UART_EVENT_RX_CHAR. 170 * The maximum transfer size is reported by infoGet(). 171 * @par Implemented as 172 * - @ref R_SCIF_UART_Read() 173 * 174 * @param[in] p_ctrl Pointer to the UART control block for the channel. 175 * @param[in] p_dest Destination address to read data from. 176 * @param[in] bytes Read data length. 177 */ 178 fsp_err_t (* read)(uart_ctrl_t * const p_ctrl, uint8_t * const p_dest, uint32_t const bytes); 179 180 /** Write to UART device. The write buffer is used until write is complete. Do not overwrite write buffer 181 * contents until the write is finished. When the write is complete (all bytes are fully transmitted on the wire), 182 * the callback called with event UART_EVENT_TX_COMPLETE. 183 * The maximum transfer size is reported by infoGet(). 184 * @par Implemented as 185 * - @ref R_SCIF_UART_Write() 186 * 187 * @param[in] p_ctrl Pointer to the UART control block. 188 * @param[in] p_src Source address to write data to. 189 * @param[in] bytes Write data length. 190 */ 191 fsp_err_t (* write)(uart_ctrl_t * const p_ctrl, uint8_t const * const p_src, uint32_t const bytes); 192 193 /** Change baud rate. 194 * @warning Calling this API aborts any in-progress transmission and disables reception until the new baud 195 * settings have been applied. 196 * 197 * @par Implemented as 198 * - @ref R_SCIF_UART_BaudSet() 199 * 200 * @param[in] p_ctrl Pointer to the UART control block. 201 * @param[in] p_baudrate_info Pointer to module specific information for configuring baud rate. 202 */ 203 fsp_err_t (* baudSet)(uart_ctrl_t * const p_ctrl, void const * const p_baudrate_info); 204 205 /** Get the driver specific information. 206 * @par Implemented as 207 * - @ref R_SCIF_UART_InfoGet() 208 * 209 * @param[in] p_ctrl Pointer to the UART control block. 210 * @param[in] baudrate Baud rate in bps. 211 */ 212 fsp_err_t (* infoGet)(uart_ctrl_t * const p_ctrl, uart_info_t * const p_info); 213 214 /** 215 * Abort ongoing transfer. 216 * @par Implemented as 217 * - @ref R_SCIF_UART_Abort() 218 * 219 * @param[in] p_ctrl Pointer to the UART control block. 220 * @param[in] communication_to_abort Type of abort request. 221 */ 222 fsp_err_t (* communicationAbort)(uart_ctrl_t * const p_ctrl, uart_dir_t communication_to_abort); 223 224 /** 225 * Specify callback function and optional context pointer and working memory pointer. 226 * @par Implemented as 227 * - R_SCIF_Uart_CallbackSet() 228 * 229 * @param[in] p_api_ctrl Pointer to the UART control block. 230 * @param[in] p_callback Callback function 231 * @param[in] p_context Pointer to send to callback function 232 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 233 * Callback arguments allocated here are only valid during the callback. 234 */ 235 fsp_err_t (* callbackSet)(uart_ctrl_t * const p_api_ctrl, void (* p_callback)(uart_callback_args_t *), 236 void const * const p_context, uart_callback_args_t * const p_callback_memory); 237 238 /** Close UART device. 239 * @par Implemented as 240 * - @ref R_SCIF_UART_Close() 241 * 242 * @param[in] p_ctrl Pointer to the UART control block. 243 */ 244 fsp_err_t (* close)(uart_ctrl_t * const p_ctrl); 245 246 /** Stop ongoing read and return the number of bytes remaining in the read. 247 * @par Implemented as 248 * - @ref R_SCIF_UART_ReadStop() 249 * 250 * @param[in] p_ctrl Pointer to the UART control block. 251 * @param[in,out] remaining_bytes Pointer to location to store remaining bytes for read. 252 */ 253 fsp_err_t (* readStop)(uart_ctrl_t * const p_ctrl, uint32_t * remaining_bytes); 254 } uart_api_t; 255 256 /** This structure encompasses everything that is needed to use an instance of this interface. */ 257 typedef struct st_uart_instance 258 { 259 uart_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 260 uart_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 261 uart_api_t const * p_api; ///< Pointer to the API structure for this instance 262 } uart_instance_t; 263 264 /** @} (end defgroup UART_API) */ 265 266 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 267 FSP_FOOTER 268 269 #endif 270
