/*********************************************************************************************************************** * Copyright [2020-2021] Renesas Electronics Corporation and/or its affiliates. All Rights Reserved. * * This software and documentation are supplied by Renesas Electronics America Inc. and may only be used with products * of Renesas Electronics Corp. and its affiliates ("Renesas"). No other uses are authorized. Renesas products are * sold pursuant to Renesas terms and conditions of sale. Purchasers are solely responsible for the selection and use * of Renesas products and Renesas assumes no liability. No license, express or implied, to any intellectual property * right is granted by Renesas. This software is protected under all applicable laws, including copyright laws. Renesas * reserves the right to change or discontinue this software and/or this documentation. THE SOFTWARE AND DOCUMENTATION * IS DELIVERED TO YOU "AS IS," AND RENESAS MAKES NO REPRESENTATIONS OR WARRANTIES, AND TO THE FULLEST EXTENT * PERMISSIBLE UNDER APPLICABLE LAW, DISCLAIMS ALL WARRANTIES, WHETHER EXPLICITLY OR IMPLICITLY, INCLUDING WARRANTIES * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT, WITH RESPECT TO THE SOFTWARE OR * DOCUMENTATION. RENESAS SHALL HAVE NO LIABILITY ARISING OUT OF ANY SECURITY VULNERABILITY OR BREACH. TO THE MAXIMUM * EXTENT PERMITTED BY LAW, IN NO EVENT WILL RENESAS BE LIABLE TO YOU IN CONNECTION WITH THE SOFTWARE OR DOCUMENTATION * (OR ANY PERSON OR ENTITY CLAIMING RIGHTS DERIVED FROM YOU) FOR ANY LOSS, DAMAGES, OR CLAIMS WHATSOEVER, INCLUDING, * WITHOUT LIMITATION, ANY DIRECT, CONSEQUENTIAL, SPECIAL, INDIRECT, PUNITIVE, OR INCIDENTAL DAMAGES; ANY LOST PROFITS, * OTHER ECONOMIC DAMAGE, PROPERTY DAMAGE, OR PERSONAL INJURY; AND EVEN IF RENESAS HAS BEEN ADVISED OF THE POSSIBILITY * OF SUCH LOSS, DAMAGES, CLAIMS OR COSTS. **********************************************************************************************************************/ /*******************************************************************************************************************//** * @ingroup RENESAS_INTERFACES * @defgroup UART_API UART Interface * @brief Interface for UART communications. * * @section UART_INTERFACE_SUMMARY Summary * The UART interface provides common APIs for UART HAL drivers. The UART interface supports the following features: * - Full-duplex UART communication * - Interrupt driven transmit/receive processing * - Callback function with returned event code * - Runtime baud-rate change * - Hardware resource locking during a transaction * - CTS/RTS hardware flow control support (with an associated IOPORT pin) * * Implemented by: * - @ref SCI_UART * * @{ **********************************************************************************************************************/ #ifndef R_UART_API_H #define R_UART_API_H /*********************************************************************************************************************** * Includes **********************************************************************************************************************/ /* Includes board and MCU related header files. */ #include "bsp_api.h" #include "r_transfer_api.h" /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ FSP_HEADER /********************************************************************************************************************** * Macro definitions **********************************************************************************************************************/ /********************************************************************************************************************** * Typedef definitions **********************************************************************************************************************/ /** UART Event codes */ typedef enum e_sf_event { UART_EVENT_RX_COMPLETE = (1UL << 0), ///< Receive complete event UART_EVENT_TX_COMPLETE = (1UL << 1), ///< Transmit complete event UART_EVENT_RX_CHAR = (1UL << 2), ///< Character received UART_EVENT_ERR_PARITY = (1UL << 3), ///< Parity error event UART_EVENT_ERR_FRAMING = (1UL << 4), ///< Mode fault error event UART_EVENT_ERR_OVERFLOW = (1UL << 5), ///< FIFO Overflow error event UART_EVENT_BREAK_DETECT = (1UL << 6), ///< Break detect error event UART_EVENT_TX_DATA_EMPTY = (1UL << 7), ///< Last byte is transmitting, ready for more data } uart_event_t; /** UART Data bit length definition */ typedef enum e_uart_data_bits { UART_DATA_BITS_8, ///< Data bits 8-bit UART_DATA_BITS_7, ///< Data bits 7-bit UART_DATA_BITS_9 ///< Data bits 9-bit } uart_data_bits_t; /** UART Parity definition */ typedef enum e_uart_parity { UART_PARITY_OFF = 0U, ///< No parity UART_PARITY_EVEN = 2U, ///< Even parity UART_PARITY_ODD = 3U, ///< Odd parity } uart_parity_t; /** UART Stop bits definition */ typedef enum e_uart_stop_bits { UART_STOP_BITS_1 = 0U, ///< Stop bit 1-bit UART_STOP_BITS_2 = 1U, ///< Stop bits 2-bit } uart_stop_bits_t; /** UART transaction definition */ typedef enum e_uart_dir { UART_DIR_RX_TX = 3U, ///< Both RX and TX UART_DIR_RX = 1U, ///< Only RX UART_DIR_TX = 2U, ///< Only TX } uart_dir_t; /** UART driver specific information */ typedef struct st_uart_info { /** Maximum bytes that can be written at this time. Only applies if uart_cfg_t::p_transfer_tx is not NULL. */ uint32_t write_bytes_max; /** Maximum bytes that are available to read at one time. Only applies if uart_cfg_t::p_transfer_rx is not NULL. */ uint32_t read_bytes_max; } uart_info_t; /** UART Callback parameter definition */ typedef struct st_uart_callback_arg { uint32_t channel; ///< Device channel number uart_event_t event; ///< Event code /** Contains the next character received for the events UART_EVENT_RX_CHAR, UART_EVENT_ERR_PARITY, * UART_EVENT_ERR_FRAMING, or UART_EVENT_ERR_OVERFLOW. Otherwise unused. */ uint32_t data; void const * p_context; ///< Context provided to user during callback } uart_callback_args_t; /** UART Configuration */ typedef struct st_uart_cfg { /* UART generic configuration */ uint8_t channel; ///< Select a channel corresponding to the channel number of the hardware. uart_data_bits_t data_bits; ///< Data bit length (8 or 7 or 9) uart_parity_t parity; ///< Parity type (none or odd or even) uart_stop_bits_t stop_bits; ///< Stop bit length (1 or 2) uint8_t rxi_ipl; ///< Receive interrupt priority IRQn_Type rxi_irq; ///< Receive interrupt IRQ number uint8_t txi_ipl; ///< Transmit interrupt priority IRQn_Type txi_irq; ///< Transmit interrupt IRQ number uint8_t tei_ipl; ///< Transmit end interrupt priority IRQn_Type tei_irq; ///< Transmit end interrupt IRQ number uint8_t eri_ipl; ///< Error interrupt priority IRQn_Type eri_irq; ///< Error interrupt IRQ number /** Optional transfer instance used to receive multiple bytes without interrupts. Set to NULL if unused. * If NULL, the number of bytes allowed in the read API is limited to one byte at a time. */ transfer_instance_t const * p_transfer_rx; /** Optional transfer instance used to send multiple bytes without interrupts. Set to NULL if unused. * If NULL, the number of bytes allowed in the write APIs is limited to one byte at a time. */ transfer_instance_t const * p_transfer_tx; /* Configuration for UART Event processing */ void (* p_callback)(uart_callback_args_t * p_args); ///< Pointer to callback function void const * p_context; ///< User defined context passed into callback function /* Pointer to UART peripheral specific configuration */ void const * p_extend; ///< UART hardware dependent configuration } uart_cfg_t; /** UART control block. Allocate an instance specific control block to pass into the UART API calls. * @par Implemented as * - sci_uart_instance_ctrl_t */ typedef void uart_ctrl_t; /** Shared Interface definition for UART */ typedef struct st_uart_api { /** Open UART device. * @par Implemented as * - @ref R_SCI_UART_Open() * * @param[in,out] p_ctrl Pointer to the UART control block. Must be declared by user. Value set here. * @param[in] uart_cfg_t Pointer to UART configuration structure. All elements of this structure must be set by * user. */ fsp_err_t (* open)(uart_ctrl_t * const p_ctrl, uart_cfg_t const * const p_cfg); /** Read from UART device. The read buffer is used until the read is complete. When a transfer is complete, the * callback is called with event UART_EVENT_RX_COMPLETE. Bytes received outside an active transfer are received in * the callback function with event UART_EVENT_RX_CHAR. * The maximum transfer size is reported by infoGet(). * @par Implemented as * - @ref R_SCI_UART_Read() * * @param[in] p_ctrl Pointer to the UART control block for the channel. * @param[in] p_dest Destination address to read data from. * @param[in] bytes Read data length. */ fsp_err_t (* read)(uart_ctrl_t * const p_ctrl, uint8_t * const p_dest, uint32_t const bytes); /** Write to UART device. The write buffer is used until write is complete. Do not overwrite write buffer * contents until the write is finished. When the write is complete (all bytes are fully transmitted on the wire), * the callback called with event UART_EVENT_TX_COMPLETE. * The maximum transfer size is reported by infoGet(). * @par Implemented as * - @ref R_SCI_UART_Write() * * @param[in] p_ctrl Pointer to the UART control block. * @param[in] p_src Source address to write data to. * @param[in] bytes Write data length. */ fsp_err_t (* write)(uart_ctrl_t * const p_ctrl, uint8_t const * const p_src, uint32_t const bytes); /** Change baud rate. * @warning Calling this API aborts any in-progress transmission and disables reception until the new baud * settings have been applied. * * @par Implemented as * - @ref R_SCI_UART_BaudSet() * * @param[in] p_ctrl Pointer to the UART control block. * @param[in] p_baudrate_info Pointer to module specific information for configuring baud rate. */ fsp_err_t (* baudSet)(uart_ctrl_t * const p_ctrl, void const * const p_baudrate_info); /** Get the driver specific information. * @par Implemented as * - @ref R_SCI_UART_InfoGet() * * @param[in] p_ctrl Pointer to the UART control block. * @param[in] baudrate Baud rate in bps. */ fsp_err_t (* infoGet)(uart_ctrl_t * const p_ctrl, uart_info_t * const p_info); /** * Abort ongoing transfer. * @par Implemented as * - @ref R_SCI_UART_Abort() * * @param[in] p_ctrl Pointer to the UART control block. * @param[in] communication_to_abort Type of abort request. */ fsp_err_t (* communicationAbort)(uart_ctrl_t * const p_ctrl, uart_dir_t communication_to_abort); /** * Specify callback function and optional context pointer and working memory pointer. * @par Implemented as * - R_SCI_Uart_CallbackSet() * * @param[in] p_ctrl Pointer to the UART control block. * @param[in] p_callback Callback function * @param[in] p_context Pointer to send to callback function * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. * Callback arguments allocated here are only valid during the callback. */ fsp_err_t (* callbackSet)(uart_ctrl_t * const p_api_ctrl, void (* p_callback)(uart_callback_args_t *), void const * const p_context, uart_callback_args_t * const p_callback_memory); /** Close UART device. * @par Implemented as * - @ref R_SCI_UART_Close() * * @param[in] p_ctrl Pointer to the UART control block. */ fsp_err_t (* close)(uart_ctrl_t * const p_ctrl); } uart_api_t; /** This structure encompasses everything that is needed to use an instance of this interface. */ typedef struct st_uart_instance { uart_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance uart_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance uart_api_t const * p_api; ///< Pointer to the API structure for this instance } uart_instance_t; /** @} (end defgroup UART_API) */ /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ FSP_FOOTER #endif