1 /*********************************************************************************************************************** 2 * Copyright [2020-2023] 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 * 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_EVEN = 2U, ///< Even parity 92 UART_PARITY_ODD = 3U, ///< Odd parity 93 } uart_parity_t; 94 #endif 95 96 /** UART Stop bits definition */ 97 typedef enum e_uart_stop_bits 98 { 99 UART_STOP_BITS_1 = 0U, ///< Stop bit 1-bit 100 UART_STOP_BITS_2 = 1U, ///< Stop bits 2-bit 101 } uart_stop_bits_t; 102 103 /** UART transaction definition */ 104 typedef enum e_uart_dir 105 { 106 UART_DIR_RX_TX = 3U, ///< Both RX and TX 107 UART_DIR_RX = 1U, ///< Only RX 108 UART_DIR_TX = 2U, ///< Only TX 109 } uart_dir_t; 110 111 /** UART driver specific information */ 112 typedef struct st_uart_info 113 { 114 /** Maximum bytes that can be written at this time. Only applies if uart_cfg_t::p_transfer_tx is not NULL. */ 115 uint32_t write_bytes_max; 116 117 /** Maximum bytes that are available to read at one time. Only applies if uart_cfg_t::p_transfer_rx is not NULL. */ 118 uint32_t read_bytes_max; 119 } uart_info_t; 120 121 /** UART Callback parameter definition */ 122 typedef struct st_uart_callback_arg 123 { 124 uint32_t channel; ///< Device channel number 125 uart_event_t event; ///< Event code 126 127 /** Contains the next character received for the events UART_EVENT_RX_CHAR, UART_EVENT_ERR_PARITY, 128 * UART_EVENT_ERR_FRAMING, or UART_EVENT_ERR_OVERFLOW. Otherwise unused. */ 129 uint32_t data; 130 void const * p_context; ///< Context provided to user during callback 131 } uart_callback_args_t; 132 133 /** UART Configuration */ 134 typedef struct st_uart_cfg 135 { 136 /* UART generic configuration */ 137 uint8_t channel; ///< Select a channel corresponding to the channel number of the hardware. 138 uart_data_bits_t data_bits; ///< Data bit length (8 or 7 or 9) 139 uart_parity_t parity; ///< Parity type (none or odd or even) 140 uart_stop_bits_t stop_bits; ///< Stop bit length (1 or 2) 141 uint8_t rxi_ipl; ///< Receive interrupt priority 142 IRQn_Type rxi_irq; ///< Receive interrupt IRQ number 143 uint8_t txi_ipl; ///< Transmit interrupt priority 144 IRQn_Type txi_irq; ///< Transmit interrupt IRQ number 145 uint8_t tei_ipl; ///< Transmit end interrupt priority 146 IRQn_Type tei_irq; ///< Transmit end interrupt IRQ number 147 uint8_t eri_ipl; ///< Error interrupt priority 148 IRQn_Type eri_irq; ///< Error interrupt IRQ number 149 150 /** Optional transfer instance used to receive multiple bytes without interrupts. Set to NULL if unused. 151 * If NULL, the number of bytes allowed in the read API is limited to one byte at a time. */ 152 transfer_instance_t const * p_transfer_rx; 153 154 /** Optional transfer instance used to send multiple bytes without interrupts. Set to NULL if unused. 155 * If NULL, the number of bytes allowed in the write APIs is limited to one byte at a time. */ 156 transfer_instance_t const * p_transfer_tx; 157 158 /* Configuration for UART Event processing */ 159 void (* p_callback)(uart_callback_args_t * p_args); ///< Pointer to callback function 160 void const * p_context; ///< User defined context passed into callback function 161 162 /* Pointer to UART peripheral specific configuration */ 163 void const * p_extend; ///< UART hardware dependent configuration 164 } uart_cfg_t; 165 166 /** UART control block. Allocate an instance specific control block to pass into the UART API calls. 167 */ 168 typedef void uart_ctrl_t; 169 170 /** Shared Interface definition for UART */ 171 typedef struct st_uart_api 172 { 173 /** Open UART device. 174 * 175 * @param[in,out] p_ctrl Pointer to the UART control block. Must be declared by user. Value set here. 176 * @param[in] uart_cfg_t Pointer to UART configuration structure. All elements of this structure must be set by 177 * user. 178 */ 179 fsp_err_t (* open)(uart_ctrl_t * const p_ctrl, uart_cfg_t const * const p_cfg); 180 181 /** Read from UART device. The read buffer is used until the read is complete. When a transfer is complete, the 182 * callback is called with event UART_EVENT_RX_COMPLETE. Bytes received outside an active transfer are received in 183 * the callback function with event UART_EVENT_RX_CHAR. 184 * The maximum transfer size is reported by infoGet(). 185 * 186 * @param[in] p_ctrl Pointer to the UART control block for the channel. 187 * @param[in] p_dest Destination address to read data from. 188 * @param[in] bytes Read data length. 189 */ 190 fsp_err_t (* read)(uart_ctrl_t * const p_ctrl, uint8_t * const p_dest, uint32_t const bytes); 191 192 /** Write to UART device. The write buffer is used until write is complete. Do not overwrite write buffer 193 * contents until the write is finished. When the write is complete (all bytes are fully transmitted on the wire), 194 * the callback called with event UART_EVENT_TX_COMPLETE. 195 * The maximum transfer size is reported by infoGet(). 196 * 197 * @param[in] p_ctrl Pointer to the UART control block. 198 * @param[in] p_src Source address to write data to. 199 * @param[in] bytes Write data length. 200 */ 201 fsp_err_t (* write)(uart_ctrl_t * const p_ctrl, uint8_t const * const p_src, uint32_t const bytes); 202 203 /** Change baud rate. 204 * @warning Calling this API aborts any in-progress transmission and disables reception until the new baud 205 * settings have been applied. 206 * 207 * 208 * @param[in] p_ctrl Pointer to the UART control block. 209 * @param[in] p_baudrate_info Pointer to module specific information for configuring baud rate. 210 */ 211 fsp_err_t (* baudSet)(uart_ctrl_t * const p_ctrl, void const * const p_baudrate_info); 212 213 /** Get the driver specific information. 214 * 215 * @param[in] p_ctrl Pointer to the UART control block. 216 * @param[in] baudrate Baud rate in bps. 217 */ 218 fsp_err_t (* infoGet)(uart_ctrl_t * const p_ctrl, uart_info_t * const p_info); 219 220 /** 221 * Abort ongoing transfer. 222 * 223 * @param[in] p_ctrl Pointer to the UART control block. 224 * @param[in] communication_to_abort Type of abort request. 225 */ 226 fsp_err_t (* communicationAbort)(uart_ctrl_t * const p_ctrl, uart_dir_t communication_to_abort); 227 228 /** 229 * Specify callback function and optional context pointer and working memory pointer. 230 * 231 * @param[in] p_ctrl Pointer to the UART control block. 232 * @param[in] p_callback Callback function 233 * @param[in] p_context Pointer to send to callback function 234 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 235 * Callback arguments allocated here are only valid during the callback. 236 */ 237 fsp_err_t (* callbackSet)(uart_ctrl_t * const p_ctrl, void (* p_callback)(uart_callback_args_t *), 238 void const * const p_context, uart_callback_args_t * const p_callback_memory); 239 240 /** Close UART device. 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 * 248 * @param[in] p_ctrl Pointer to the UART control block. 249 * @param[in,out] remaining_bytes Pointer to location to store remaining bytes for read. 250 */ 251 fsp_err_t (* readStop)(uart_ctrl_t * const p_ctrl, uint32_t * remaining_bytes); 252 } uart_api_t; 253 254 /** This structure encompasses everything that is needed to use an instance of this interface. */ 255 typedef struct st_uart_instance 256 { 257 uart_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 258 uart_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 259 uart_api_t const * p_api; ///< Pointer to the API structure for this instance 260 } uart_instance_t; 261 262 /** @} (end defgroup UART_API) */ 263 264 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 265 FSP_FOOTER 266 267 #endif 268