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