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