1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef R_I2C_MASTER_API_H 8 #define R_I2C_MASTER_API_H 9 10 /*******************************************************************************************************************//** 11 * @ingroup RENESAS_INTERFACES 12 * @defgroup I2C_MASTER_API I2C Master Interface 13 * @brief Interface for I2C master communication. 14 * 15 * @section I2C_MASTER_API_SUMMARY Summary 16 * The I2C master interface provides a common API for I2C HAL drivers. The I2C master interface supports: 17 * - Interrupt driven transmit/receive processing 18 * - Callback function support which can return an event code 19 * 20 * Implemented by: 21 * - @ref RIIC_MASTER 22 * 23 * @{ 24 **********************************************************************************************************************/ 25 26 /*********************************************************************************************************************** 27 * Includes 28 **********************************************************************************************************************/ 29 30 /* Register definitions, common services and error codes. */ 31 #include "bsp_api.h" 32 #include "r_transfer_api.h" 33 34 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 35 FSP_HEADER 36 37 /********************************************************************************************************************** 38 * Macro definitions 39 **********************************************************************************************************************/ 40 41 /********************************************************************************************************************** 42 * Typedef definitions 43 **********************************************************************************************************************/ 44 45 /** Communication speed options */ 46 typedef enum e_i2c_master_rate 47 { 48 I2C_MASTER_RATE_STANDARD = 100000, ///< 100 kHz 49 I2C_MASTER_RATE_FAST = 400000, ///< 400 kHz 50 I2C_MASTER_RATE_FASTPLUS = 1000000 ///< 1 MHz 51 } i2c_master_rate_t; 52 53 /** Addressing mode options */ 54 typedef enum e_i2c_master_addr_mode 55 { 56 I2C_MASTER_ADDR_MODE_7BIT = 1, ///< Use 7-bit addressing mode 57 I2C_MASTER_ADDR_MODE_10BIT = 2, ///< Use 10-bit addressing mode 58 } i2c_master_addr_mode_t; 59 60 /** Callback events */ 61 typedef enum e_i2c_master_event 62 { 63 I2C_MASTER_EVENT_ABORTED = 1, ///< A transfer was aborted 64 I2C_MASTER_EVENT_RX_COMPLETE = 2, ///< A receive operation was completed successfully 65 I2C_MASTER_EVENT_TX_COMPLETE = 3 ///< A transmit operation was completed successfully 66 } i2c_master_event_t; 67 68 /** I2C callback parameter definition */ 69 typedef struct st_i2c_master_callback_args 70 { 71 void const * p_context; ///< Pointer to user-provided context 72 i2c_master_event_t event; ///< Event code 73 } i2c_master_callback_args_t; 74 75 /** I2C status indicators */ 76 typedef struct st_i2c_master_status 77 { 78 bool open; ///< True if driver is open 79 } i2c_master_status_t; 80 81 /** I2C configuration block */ 82 typedef struct st_i2c_master_cfg 83 { 84 /** Generic configuration */ 85 uint8_t channel; ///< Identifier recognizable by implementation 86 i2c_master_rate_t rate; ///< Device's maximum clock rate from enum i2c_rate_t 87 uint32_t slave; ///< The address of the slave device 88 i2c_master_addr_mode_t addr_mode; ///< Indicates how slave fields should be interpreted 89 uint8_t ipl; ///< Interrupt priority level. Same for RXI, TXI, TEI and ERI. 90 IRQn_Type rxi_irq; ///< Receive IRQ number 91 IRQn_Type txi_irq; ///< Transmit IRQ number 92 IRQn_Type tei_irq; ///< Transmit end IRQ number 93 IRQn_Type eri_irq; ///< Error IRQ number 94 95 /** DTC support */ 96 transfer_instance_t const * p_transfer_tx; ///< DTC instance for I2C transmit.Set to NULL if unused. 97 transfer_instance_t const * p_transfer_rx; ///< DTC instance for I2C receive. Set to NULL if unused. 98 99 /** Parameters to control software behavior */ 100 void (* p_callback)(i2c_master_callback_args_t * p_args); ///< Pointer to callback function 101 void const * p_context; ///< Pointer to the user-provided context 102 103 /** Implementation-specific configuration */ 104 void const * p_extend; ///< Any configuration data needed by the hardware 105 } i2c_master_cfg_t; 106 107 /** I2C control block. Allocate an instance specific control block to pass into the I2C API calls. 108 * @par Implemented as 109 * - iic_master_instance_ctrl_t 110 */ 111 typedef void i2c_master_ctrl_t; 112 113 /** Interface definition for I2C access as master */ 114 typedef struct st_i2c_master_api 115 { 116 /** Opens the I2C Master driver and initializes the hardware. 117 * @par Implemented as 118 * - @ref R_RIIC_MASTER_Open() 119 * 120 * @param[in] p_ctrl Pointer to control block. Must be declared by user. Elements are set here. 121 * @param[in] p_cfg Pointer to configuration structure. 122 */ 123 fsp_err_t (* open)(i2c_master_ctrl_t * const p_ctrl, i2c_master_cfg_t const * const p_cfg); 124 125 /** Performs a read operation on an I2C Master device. 126 * @par Implemented as 127 * - @ref R_RIIC_MASTER_Read() 128 * 129 * @param[in] p_ctrl Pointer to control block set in i2c_api_master_t::open call. 130 * @param[in] p_dest Pointer to the location to store read data. 131 * @param[in] bytes Number of bytes to read. 132 * @param[in] restart Specify if the restart condition should be issued after reading. 133 */ 134 fsp_err_t (* read)(i2c_master_ctrl_t * const p_ctrl, uint8_t * const p_dest, uint32_t const bytes, 135 bool const restart); 136 137 /** Performs a write operation on an I2C Master device. 138 * @par Implemented as 139 * - @ref R_RIIC_MASTER_Write() 140 * 141 * @param[in] p_ctrl Pointer to control block set in i2c_api_master_t::open call. 142 * @param[in] p_src Pointer to the location to get write data from. 143 * @param[in] bytes Number of bytes to write. 144 * @param[in] restart Specify if the restart condition should be issued after writing. 145 */ 146 fsp_err_t (* write)(i2c_master_ctrl_t * const p_ctrl, uint8_t * const p_src, uint32_t const bytes, 147 bool const restart); 148 149 /** Performs a reset of the peripheral. 150 * @par Implemented as 151 * - @ref R_RIIC_MASTER_Abort() 152 * 153 * @param[in] p_ctrl Pointer to control block set in i2c_api_master_t::open call. 154 */ 155 fsp_err_t (* abort)(i2c_master_ctrl_t * const p_ctrl); 156 157 /** Sets address of the slave device without reconfiguring the bus. 158 * @par Implemented as 159 * - @ref R_RIIC_MASTER_SlaveAddressSet() 160 * 161 * @param[in] p_ctrl Pointer to control block set in i2c_api_master_t::open call. 162 * @param[in] slave_address Address of the slave device. 163 * @param[in] address_mode Addressing mode. 164 */ 165 fsp_err_t (* slaveAddressSet)(i2c_master_ctrl_t * const p_ctrl, uint32_t const slave, 166 i2c_master_addr_mode_t const addr_mode); 167 168 /** 169 * Specify callback function and optional context pointer and working memory pointer. 170 * @par Implemented as 171 * - @ref R_RIIC_MASTER_CallbackSet() 172 * 173 * @param[in] p_ctrl Pointer to the RIIC Master control block. 174 * @param[in] p_callback Callback function 175 * @param[in] p_context Pointer to send to callback function 176 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 177 * Callback arguments allocated here are only valid during the callback. 178 */ 179 fsp_err_t (* callbackSet)(i2c_master_ctrl_t * const p_api_ctrl, void (* p_callback)(i2c_master_callback_args_t *), 180 void const * const p_context, i2c_master_callback_args_t * const p_callback_memory); 181 182 /** Gets the status of the configured I2C device. 183 * @par Implemented as 184 * - @ref R_RIIC_MASTER_StatusGet() 185 * 186 * @param[in] p_ctrl Pointer to the RIIC Master control block. 187 * @param[out] p_status Pointer to store current status. 188 */ 189 fsp_err_t (* statusGet)(i2c_master_ctrl_t * const p_api_ctrl, i2c_master_status_t * p_status); 190 191 /** Closes the driver and releases the I2C Master device. 192 * @par Implemented as 193 * - @ref R_RIIC_MASTER_Close() 194 * 195 * @param[in] p_ctrl Pointer to control block set in i2c_api_master_t::open call. 196 */ 197 fsp_err_t (* close)(i2c_master_ctrl_t * const p_ctrl); 198 } i2c_master_api_t; 199 200 /** This structure encompasses everything that is needed to use an instance of this interface. */ 201 typedef struct st_i2c_master_instance 202 { 203 i2c_master_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 204 i2c_master_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 205 i2c_master_api_t const * p_api; ///< Pointer to the API structure for this instance 206 } i2c_master_instance_t; 207 208 /******************************************************************************************************************//** 209 * @} (end addtogroup I2C_MASTER_API) 210 *********************************************************************************************************************/ 211 212 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 213 FSP_FOOTER 214 215 #endif 216
