1 /*********************************************************************************************************************** 2 * Copyright [2015-2017] Renesas Electronics Corporation and/or its licensors. All Rights Reserved. 3 * 4 * This file is part of Renesas SynergyTM Software Package (SSP) 5 * 6 * The contents of this file (the "contents") are proprietary and confidential to Renesas Electronics Corporation 7 * and/or its licensors ("Renesas") and subject to statutory and contractual protections. 8 * 9 * This file is subject to a Renesas SSP license agreement. Unless otherwise agreed in an SSP license agreement with 10 * Renesas: 1) you may not use, copy, modify, distribute, display, or perform the contents; 2) you may not use any name 11 * or mark of Renesas for advertising or publicity purposes or in connection with your use of the contents; 3) RENESAS 12 * MAKES NO WARRANTY OR REPRESENTATIONS ABOUT THE SUITABILITY OF THE CONTENTS FOR ANY PURPOSE; THE CONTENTS ARE PROVIDED 13 * "AS IS" WITHOUT ANY EXPRESS OR IMPLIED WARRANTY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 14 * PARTICULAR PURPOSE, AND NON-INFRINGEMENT; AND 4) RENESAS SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, OR 15 * CONSEQUENTIAL DAMAGES, INCLUDING DAMAGES RESULTING FROM LOSS OF USE, DATA, OR PROJECTS, WHETHER IN AN ACTION OF 16 * CONTRACT OR TORT, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE CONTENTS. Third-party contents 17 * included in this file may be subject to different terms. 18 **********************************************************************************************************************/ 19 20 /********************************************************************************************************************** 21 * File Name : r_uart_api.h 22 * Description : UART Shared Interface definition 23 **********************************************************************************************************************/ 24 25 /*******************************************************************************************************************//** 26 * @ingroup Interface_Library 27 * @defgroup UART_API UART Interface 28 * @brief Interface for UART communications. 29 * 30 * @section UART_INTERFACE_SUMMARY Summary 31 * The UART interface provides common APIs for UART HAL drivers. The UART interface supports the following features: 32 * - Full-duplex UART communication 33 * - Generic UART parameter setting 34 * - Interrupt driven transmit/receive processing 35 * - Callback function with returned event code 36 * - Runtime baud-rate change 37 * - Hardware resource locking during a transaction 38 * - CTS/RTS hardware flow control support (with an associated IOPORT pin) 39 * - Circular buffer support 40 * - Runtime Transmit/Receive circular buffer flushing 41 * 42 * Implemented by: 43 * - @ref UARTonSCI 44 * 45 * Related SSP architecture topics: 46 * - @ref ssp-interfaces 47 * - @ref ssp-predefined-layers 48 * - @ref using-ssp-modules 49 * 50 * UART Interface description: @ref HALUARTInterface 51 * @{ 52 **********************************************************************************************************************/ 53 54 #ifndef R_UART_API_H 55 #define R_UART_API_H 56 57 /*********************************************************************************************************************** 58 * Includes 59 **********************************************************************************************************************/ 60 /* Includes board and MCU related header files. */ 61 #include "bsp_api.h" 62 #include "r_transfer_api.h" 63 64 /* Common macro for SSP header files. There is also a corresponding SSP_FOOTER macro at the end of this file. */ 65 SSP_HEADER 66 67 /********************************************************************************************************************** 68 * Macro definitions 69 **********************************************************************************************************************/ 70 #define UART_API_VERSION_MAJOR (1U) 71 #define UART_API_VERSION_MINOR (6U) 72 73 /********************************************************************************************************************** 74 * Typedef definitions 75 **********************************************************************************************************************/ 76 /** UART Event codes */ 77 typedef enum e_sf_event 78 { 79 UART_EVENT_RX_COMPLETE = (1UL << 0), ///< Receive complete event 80 UART_EVENT_TX_COMPLETE = (1UL << 1), ///< Transmit complete event 81 UART_EVENT_ERR_PARITY = (1UL << 2), ///< Parity error event 82 UART_EVENT_ERR_FRAMING = (1UL << 3), ///< Mode fault error event 83 UART_EVENT_BREAK_DETECT = (1UL << 4), ///< Break detect error event 84 UART_EVENT_ERR_OVERFLOW = (1UL << 5), ///< FIFO Overflow error event 85 UART_EVENT_ERR_RXBUF_OVERFLOW = (1UL << 6), ///< DEPRECATED: Receive buffer overflow error event 86 UART_EVENT_RX_CHAR = (1UL << 7), ///< Character received 87 UART_EVENT_TX_DATA_EMPTY = (1UL << 8), ///< Last byte is transmitting, ready for more data 88 } uart_event_t; 89 90 /** UART Data bit length definition */ 91 typedef enum e_uart_data_bits 92 { 93 UART_DATA_BITS_8, ///< Data bits 8-bit 94 UART_DATA_BITS_7, ///< Data bits 7-bit 95 UART_DATA_BITS_9 ///< Data bits 9-bit 96 } uart_data_bits_t; 97 98 /** UART Parity definition */ 99 typedef enum e_uart_parity 100 { 101 UART_PARITY_OFF = 0U, ///< No parity 102 UART_PARITY_EVEN = 2U, ///< Even parity 103 UART_PARITY_ODD = 3U, ///< Odd parity 104 } uart_parity_t; 105 106 /** UART Stop bits definition */ 107 typedef enum e_uart_stop_bits 108 { 109 UART_STOP_BITS_1 = 0U, ///< Stop bit 1-bit 110 UART_STOP_BITS_2 = 1U, ///< Stop bits 2-bit 111 } uart_stop_bits_t; 112 113 /** UART transaction definition */ 114 typedef enum e_uart_dir 115 { 116 UART_DIR_RX_TX = 0U, ///< Both RX and TX 117 UART_DIR_RX = 1U, ///< Only RX 118 UART_DIR_TX = 2U, ///< Only TX 119 } uart_dir_t; 120 121 /** UART communication mode definition */ 122 typedef enum e_uart_mode 123 { 124 UART_MODE_RS232 = 0U, ///< Enables RS232 communication mode 125 UART_MODE_RS485 = 1U, ///< Enables RS485 communication mode 126 }uart_mode_t; 127 128 /** UART RS485 communication channel type definition */ 129 typedef enum e_uart_rs485_type 130 { 131 UART_RS485_HD = 0U, ///< Uses RS485 half duplex communication channel 132 UART_RS485_FD = 1U, ///< Uses RS485 full duplex communication channel 133 }uart_rs485_type_t; 134 135 /** UART driver specific information */ 136 typedef struct st_uart_info 137 { 138 /** Maximum bytes that can be written at this time. Only applies if uart_cfg_t::p_transfer_tx is not NULL. */ 139 uint32_t write_bytes_max; 140 141 /** Maximum bytes that are available to read at one time. Only applies if uart_cfg_t::p_transfer_rx is not NULL. */ 142 uint32_t read_bytes_max; 143 } uart_info_t; 144 145 /** UART Callback parameter definition */ 146 typedef struct st_uart_callback_arg 147 { 148 uint32_t channel; ///< Device channel number 149 uart_event_t event; ///< Event code 150 151 /** Contains the next character received for the events UART_EVENT_RX_CHAR, UART_EVENT_ERR_PARITY, 152 * UART_EVENT_ERR_FRAMING, or UART_EVENT_ERR_OVERFLOW. Otherwise unused. */ 153 uint32_t data; 154 void const * p_context; ///< Context provided to user during callback 155 } uart_callback_args_t; 156 157 /** UART Configuration */ 158 typedef struct st_uart_cfg 159 { 160 /* UART generic configuration */ 161 uint8_t channel; ///< Select a channel corresponding to the channel number of the hardware. 162 uint32_t baud_rate; ///< Baud rate, i.e. 9600, 19200, 115200 163 uart_data_bits_t data_bits; ///< Data bit length (8 or 7 or 9) 164 uart_parity_t parity; ///< Parity type (none or odd or even) 165 uart_stop_bits_t stop_bits; ///< Stop bit length (1 or 2) 166 bool ctsrts_en; ///< CTS/RTS hardware flow control enable 167 uint8_t rxi_ipl; ///< Receive interrupt priority 168 uint8_t txi_ipl; ///< Transmit interrupt priority 169 uint8_t tei_ipl; ///< Transmit end interrupt priority 170 uint8_t eri_ipl; ///< Error interrupt priority 171 172 /** Optional transfer instance used to receive multiple bytes without interrupts. Set to NULL if unused. 173 * If NULL, the number of bytes allowed in the read API is limited to one byte at a time. */ 174 transfer_instance_t const * p_transfer_rx; 175 176 /** Optional transfer instance used to send multiple bytes without interrupts. Set to NULL if unused. 177 * If NULL, the number of bytes allowed in the write APIs is limited to one byte at a time. */ 178 transfer_instance_t const * p_transfer_tx; 179 180 /* Configuration for UART Event processing */ 181 void (* p_callback)(uart_callback_args_t * p_args); ///< Pointer to callback function 182 void const * p_context; ///< User defined context passed into callback function 183 184 /* Pointer to UART peripheral specific configuration */ 185 void const * p_extend; ///< UART hardware dependent configuration 186 } uart_cfg_t; 187 188 /** UART control block. Allocate an instance specific control block to pass into the UART API calls. 189 * @par Implemented as 190 * - sci_uart_instance_ctrl_t 191 */ 192 typedef void uart_ctrl_t; 193 194 /** Shared Interface definition for UART */ 195 typedef struct st_uart_api 196 { 197 /** Open UART device. 198 * @par Implemented as 199 * - R_SCI_UartOpen() 200 * 201 * @param[in,out] p_ctrl Pointer to the UART control block Must be declared by user. Value set here. 202 * @param[in] uart_cfg_t Pointer to UART configuration structure. All elements of this structure must be set by 203 * user. 204 */ 205 ssp_err_t (* open)(uart_ctrl_t * const p_ctrl, 206 uart_cfg_t const * const p_cfg); 207 208 /** Read from UART device. If a transfer instance is used for reception, the received bytes are stored directly 209 * in the read input buffer. When a transfer is complete, the callback is called with event UART_EVENT_RX_COMPLETE. 210 * Bytes received outside an active transfer are received in the callback function with event UART_EVENT_RX_CHAR. 211 * The maximum transfer size is reported by infoGet(). 212 * @par Implemented as 213 * - R_SCI_UartRead() 214 * 215 * @param[in] p_ctrl Pointer to the UART control block for the channel. 216 * @param[in] p_dest Destination address to read data from. 217 * @param[in] bytes Read data length. Only applicable if uart_cfg_t::p_transfer_rx is not NULL. 218 * Otherwise all read bytes will be provided through the callback set in 219 * uart_cfg_t::p_callback. 220 */ 221 ssp_err_t (* read)(uart_ctrl_t * const p_ctrl, 222 uint8_t const * const p_dest, 223 uint32_t const bytes); 224 225 /** Write to UART device. The write buffer is used until write is complete. Do not overwrite write buffer 226 * contents until the write is finished. When the write is complete (all bytes are fully transmitted on the wire), 227 * the callback called with event UART_EVENT_TX_COMPLETE. 228 * The maximum transfer size is reported by infoGet(). 229 * @par Implemented as 230 * - R_SCI_UartWrite() 231 * 232 * @param[in] p_ctrl Pointer to the UART control block. 233 * @param[in] p_src Source address to write data to. 234 * @param[in] bytes Write data length. 235 */ 236 ssp_err_t (* write)(uart_ctrl_t * const p_ctrl, 237 uint8_t const * const p_src, 238 uint32_t const bytes); 239 240 /** Change baud rate. 241 * @warning Calling this API aborts any in-progress transmission and disables reception until the new baud 242 * settings have been applied. 243 * 244 * @par Implemented as 245 * - R_SCI_UartBaudSet() 246 * 247 * @param[in] p_ctrl Pointer to the UART control block. 248 * @param[in] baudrate Baud rate in bps. 249 */ 250 ssp_err_t (* baudSet)(uart_ctrl_t * const p_ctrl, 251 uint32_t const baudrate); 252 253 /** Get the driver specific information. 254 * @par Implemented as 255 * - R_SCI_UartInfoGet() 256 * 257 * @param[in] p_ctrl Pointer to the UART control block. 258 * @param[in] baudrate Baud rate in bps. 259 */ 260 ssp_err_t (* infoGet)(uart_ctrl_t * const p_ctrl, 261 uart_info_t * const p_info); 262 263 /** Close UART device. 264 * @par Implemented as 265 * - R_SCI_UartClose() 266 * 267 * @param[in] p_ctrl Pointer to the UART control block. 268 */ 269 ssp_err_t (* close)(uart_ctrl_t * const p_ctrl); 270 271 /** Get version. 272 * @par Implemented as 273 * - R_SCI_UartVersionGet() 274 * 275 * @param[in] p_version Pointer to the memory to store the version information. 276 */ 277 ssp_err_t (* versionGet)(ssp_version_t * p_version); 278 279 /** 280 * Abort ongoing transfer. 281 * @par Implemented as 282 * - R_SCI_UartAbort() 283 * 284 * @param[in] p_ctrl Pointer to the UART control block. 285 * @param[in] communication_to_abort Type of abort request. 286 */ 287 ssp_err_t (* communicationAbort)(uart_ctrl_t * const p_ctrl, uart_dir_t communication_to_abort); 288 } uart_api_t; 289 290 /** This structure encompasses everything that is needed to use an instance of this interface. */ 291 typedef struct st_uart_instance 292 { 293 uart_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 294 uart_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 295 uart_api_t const * p_api; ///< Pointer to the API structure for this instance 296 } uart_instance_t; 297 298 299 /** @} (end defgroup UART_API) */ 300 301 /* Common macro for SSP header files. There is also a corresponding SSP_HEADER macro at the top of this file. */ 302 SSP_FOOTER 303 304 #endif /* R_UART_API_H */ 305