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