1 /***************************************************************************//** 2 * \file cyhal_i2c.h 3 * 4 * \brief 5 * Provides a high level interface for interacting with the Infineon I2C. 6 * This interface abstracts out the chip specific details. If any chip specific 7 * functionality is necessary, or performance is critical the low level functions 8 * can be used directly. 9 * 10 ******************************************************************************** 11 * \copyright 12 * Copyright 2018-2022 Cypress Semiconductor Corporation (an Infineon company) or 13 * an affiliate of Cypress Semiconductor Corporation 14 * 15 * SPDX-License-Identifier: Apache-2.0 16 * 17 * Licensed under the Apache License, Version 2.0 (the "License"); 18 * you may not use this file except in compliance with the License. 19 * You may obtain a copy of the License at 20 * 21 * http://www.apache.org/licenses/LICENSE-2.0 22 * 23 * Unless required by applicable law or agreed to in writing, software 24 * distributed under the License is distributed on an "AS IS" BASIS, 25 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 26 * See the License for the specific language governing permissions and 27 * limitations under the License. 28 *******************************************************************************/ 29 30 /** 31 * \addtogroup group_hal_i2c I2C (Inter-Integrated Circuit) 32 * \ingroup group_hal 33 * \{ 34 * High level interface for interacting with the I2C resource. 35 * 36 * The I2C protocol is a synchronous serial interface protocol. This driver supports 37 * both master and slave mode of operation. The communication frequency and address (for slave operation) can be 38 * configured. 39 * 40 * \section section_i2c_features Features 41 * 42 * * Master or slave functionality 43 * * Configurable slave address 44 * * Configurable data rates 45 * * Configurable interrupt and callback assignment from I2C events - \ref cyhal_i2c_event_t 46 * 47 * \section section_i2c_quickstart Quick Start 48 * Initialize an I2C instance using the \ref cyhal_i2c_init and provide <b>sda</b> (I2C data) and <b>scl</b> (I2C clock) pins.<br> 49 * By default, this initializes the resource as an I2C master.<br> 50 * Configure the behavior (master/slave) and the interface (bus frequency, slave address) using the \ref cyhal_i2c_configure function. <br> 51 * See \ref subsection_i2c_snippet_1 for example initialization as master or slave. 52 * \note The clock parameter (const cyhal_clock_divider_t *clk) is optional and can be set 53 * to NULL to generate and use an available clock resource with a default frequency (CYHAL_I2C_MASTER_DEFAULT_FREQ). 54 * 55 * \section section_i2c_snippets Code Snippets 56 * 57 * \subsection subsection_i2c_snippet_1 Snippet 1: I2C Initialization and Configuration 58 * This snippet initializes an I2C resource as master or slave and assigns 59 * the <b>sda</b> and <b>scl</b> pins. 60 * 61 * Initializing as I2C master 62 * \snippet hal_i2c.c snippet_cyhal_i2c_master_init 63 * 64 * Initializing as I2C slave 65 * \snippet hal_i2c.c snippet_cyhal_i2c_slave_init 66 * 67 * \subsection subsection_i2c_snippet_2 Snippet 2: Handling events 68 * This snippet shows how to enable and handle I2C events using \ref cyhal_i2c_enable_event and \ref cyhal_i2c_register_callback.<br> 69 * The <b>callback</b> parameter of \ref cyhal_i2c_register_callback is used to pass the callback handler that will be invoked when an event occurs.<br> 70 * The <b>event</b> parameter of \ref cyhal_i2c_enable_event is used to pass the bitmasks of events ( \ref cyhal_i2c_event_t) to be enabled. 71 * 72 * \snippet hal_i2c.c snippet_cyhal_handle_i2c_events 73 * 74 * \subsection subsection_i2c_snippet_3 Snippet 3: I2C Master Asynchronous Transfer 75 * This snippet shows how to implement asynchronous transfers using \ref cyhal_i2c_master_transfer_async.<br> 76 * \ref cyhal_i2c_abort_async is used to stop the transfer, in this case when an error occurs. 77 * 78 * \snippet hal_i2c.c snippet_cyhal_async_transfer 79 * 80 * \section subsection_i2c_moreinformation More Information 81 * 82 * <b>Peripheral Driver Library (PDL)</b> 83 * * <a href="https://infineon.github.io/psoc6pdl/pdl_api_reference_manual/html/group__group__scb.html"><b> 84 PSoC™ 6 PDL: SCB (Serial Communication Block)</b></a> 85 * 86 * <b>Code examples (Github)</b> 87 * * <a href="https://github.com/infineon/mtb-example-psoc6-i2c-master" ><b> 88 PSoC™ 6 MCU: I2C Master</b></a> 89 * * <a href="https://github.com/infineon/mtb-example-psoc6-i2c-slave-callback" ><b> 90 PSoC™ 6 MCU: I2C Slave Using Callbacks</b></a> 91 */ 92 93 #pragma once 94 95 #include <stdint.h> 96 #include <stdbool.h> 97 #include "cy_result.h" 98 #include "cyhal_hw_types.h" 99 100 #if defined(__cplusplus) 101 extern "C" { 102 #endif 103 104 /** \addtogroup group_hal_results_i2c I2C HAL Results 105 * I2C specific return codes 106 * \ingroup group_hal_results 107 * \{ *//** 108 */ 109 110 /** The requested resource type is invalid */ 111 #define CYHAL_I2C_RSLT_ERR_INVALID_PIN \ 112 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 0)) 113 /** Can not reach desired data rate */ 114 #define CYHAL_I2C_RSLT_ERR_CAN_NOT_REACH_DR \ 115 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 1)) 116 /** Address size is not correct, should be 1 or two */ 117 #define CYHAL_I2C_RSLT_ERR_INVALID_ADDRESS_SIZE \ 118 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 2)) 119 /** User buffer is empty (TX and RX). Should be at least TX or RX or both buffers */ 120 #define CYHAL_I2C_RSLT_ERR_TX_RX_BUFFERS_ARE_EMPTY \ 121 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 3)) 122 /** Previous Async operation is pending */ 123 #define CYHAL_I2C_RSLT_ERR_PREVIOUS_ASYNCH_PENDING \ 124 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 4)) 125 /** Failed to register I2C pm callback */ 126 #define CYHAL_I2C_RSLT_ERR_PM_CALLBACK \ 127 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 5)) 128 /** \ref cyhal_i2c_abort_async operation failed with timeout */ 129 #define CYHAL_I2C_RSLT_ERR_ABORT_ASYNC_TIMEOUT \ 130 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 6)) 131 /** Bad argument provided */ 132 #define CYHAL_I2C_RSLT_ERR_BAD_ARGUMENT \ 133 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 7)) 134 /** Unsupported by this device */ 135 #define CYHAL_I2C_RSLT_ERR_UNSUPPORTED \ 136 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 8)) 137 /** No ACK received */ 138 #define CYHAL_I2C_RSLT_ERR_NO_ACK \ 139 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 9)) 140 /** Command error */ 141 #define CYHAL_I2C_RSLT_ERR_CMD_ERROR \ 142 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 10)) 143 /** RX or TX Buffer is not initialized */ 144 #define CYHAL_I2C_RSLT_ERR_BUFFERS_NULL_PTR \ 145 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 11)) 146 147 /** Timeout warning */ 148 #define CYHAL_I2C_RSLT_WARN_TIMEOUT \ 149 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_WARNING, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 20)) 150 /** Other operation in progress */ 151 #define CYHAL_I2C_RSLT_WARN_DEVICE_BUSY \ 152 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_WARNING, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_I2C, 21)) 153 154 /** 155 * \} 156 */ 157 158 /** Named define for Slave mode for use when initializing the \ref cyhal_i2c_cfg_t structure. */ 159 #define CYHAL_I2C_MODE_SLAVE (true) 160 /** Named define for Master mode for use when initializing the \ref cyhal_i2c_cfg_t structure. */ 161 #define CYHAL_I2C_MODE_MASTER (false) 162 163 /** Named define for default address mask for use when initializing the \ref cyhal_i2c_adv_cfg_t structure. */ 164 #define CYHAL_I2C_DEFAULT_ADDR_MASK (0xFE) 165 166 167 /** Enum to enable/disable/report interrupt cause flags. */ 168 typedef enum 169 { 170 CYHAL_I2C_EVENT_NONE = 0, /**< No event */ 171 CYHAL_I2C_SLAVE_READ_EVENT = 1 << 1, /**< Indicates that the slave was addressed and the master wants to read data. */ 172 CYHAL_I2C_SLAVE_WRITE_EVENT = 1 << 2, /**< Indicates that the slave was addressed and the master wants to write data. */ 173 CYHAL_I2C_SLAVE_RD_IN_FIFO_EVENT = 1 << 3, /**< All slave data from the configured Read buffer has been loaded into the TX FIFO. */ 174 CYHAL_I2C_SLAVE_RD_BUF_EMPTY_EVENT = 1 << 4, /**< The master has read all data out of the configured Read buffer. */ 175 CYHAL_I2C_SLAVE_RD_CMPLT_EVENT = 1 << 5, /**< Indicates the master completed reading from the slave (set by the master NAK or Stop) */ 176 CYHAL_I2C_SLAVE_WR_CMPLT_EVENT = 1 << 6, /**< Indicates the master completed writing to the slave (set by the master Stop or Restart)*/ 177 CYHAL_I2C_SLAVE_ERR_EVENT = 1 << 7, /**< Indicates the I2C hardware detected an error. */ 178 CYHAL_I2C_MASTER_WR_IN_FIFO_EVENT = 1 << 17, /**< All data specified by cyhal_i2c_master_transfer_async has been loaded into the TX FIFO. */ 179 CYHAL_I2C_MASTER_WR_CMPLT_EVENT = 1 << 18, /**< The master write started by cyhal_i2c_master_transfer_async is complete.*/ 180 CYHAL_I2C_MASTER_RD_CMPLT_EVENT = 1 << 19, /**< The master read started by cyhal_i2c_master_transfer_async is complete.*/ 181 CYHAL_I2C_MASTER_ERR_EVENT = 1 << 20, /**< Indicates the I2C hardware has detected an error. */ 182 } cyhal_i2c_event_t; 183 184 /** Enum to enable/disable/report address interrupt cause flags. */ 185 typedef enum 186 { 187 CYHAL_I2C_ADDR_EVENT_NONE = 0, /**< No event */ 188 CYHAL_I2C_GENERAL_CALL_EVENT = 1 << 1, /**< Indicates the slave was addressed by the general call address. */ 189 CYHAL_I2C_ADDR_MATCH_EVENT = 1 << 2, /**< Indicates the slave matching address received. */ 190 } cyhal_i2c_addr_event_t; 191 192 /** I2C FIFO type */ 193 typedef enum 194 { 195 CYHAL_I2C_FIFO_RX, //!< Set RX FIFO level 196 CYHAL_I2C_FIFO_TX, //!< Set TX FIFO level 197 } cyhal_i2c_fifo_type_t; 198 199 /** I2C Command ACK / NAK */ 200 typedef enum 201 { 202 CYHAL_I2C_CMD_ACK, //!< Send ACK to current byte 203 CYHAL_I2C_CMD_NAK, //!< Send NAK to current byte 204 } cyhal_i2c_command_rsp_t; 205 206 /** Enum of possible output signals from an I2C */ 207 typedef enum 208 { 209 CYHAL_I2C_OUTPUT_TRIGGER_RX_FIFO_LEVEL_REACHED, //!< Output the RX FIFO signal which is triggered when the receive FIFO has more entries than the configured level. 210 CYHAL_I2C_OUTPUT_TRIGGER_TX_FIFO_LEVEL_REACHED, //!< Output the TX FIFO signal which is triggered when the transmit FIFO has less entries than the configured level. 211 } cyhal_i2c_output_t; 212 213 /** Handler for I2C events */ 214 typedef void (*cyhal_i2c_event_callback_t)(void *callback_arg, cyhal_i2c_event_t event); 215 /** Handler for I2C address events */ 216 typedef cyhal_i2c_command_rsp_t (*cyhal_i2c_address_callback_t)(void *callback_arg, cyhal_i2c_addr_event_t event, uint8_t address); 217 218 /** @brief Initial I2C configuration */ 219 typedef struct 220 { 221 bool is_slave; /**< Operates as a slave when set to (<b>true</b>), else as a master (<b>false</b>) */ 222 uint16_t address; /**< Address of this slave resource (7-bit), should be set to 0 for master */ 223 uint32_t frequencyhal_hz; /**< Frequency that the I2C bus runs at (I2C data rate in bits per second) <br> 224 Refer to the device datasheet for the supported I2C data rates */ 225 } cyhal_i2c_cfg_t; 226 227 /** @brief I2C advanced configuration */ 228 typedef struct 229 { 230 cyhal_i2c_cfg_t basic_cfg; /**< Basic I2C configuration */ 231 uint8_t address_mask; /**< Mask of the slave resource. Not applicable for the master. */ 232 bool enable_address_callback; /**< Indicates address callback feature is enabled or disable. 233 When it's true the address callback will be invoked. */ 234 } cyhal_i2c_adv_cfg_t; 235 236 /** Initialize the I2C peripheral, and configures its specified pins. By default 237 * it is configured as a Master with a bus frequency = CYHAL_I2C_MASTER_DEFAULT_FREQ. 238 * Use \ref cyhal_i2c_configure() to change the default behavior.<br> 239 * NOTE: Master/Slave specific functions only work when the block is configured 240 * to be in that mode.<br> 241 * See \ref subsection_i2c_snippet_1 242 * 243 * @param[out] obj Pointer to an I2C object. The caller must allocate the memory 244 * for this object but the init function will initialize its contents. 245 * @param[in] sda The sda pin 246 * @param[in] scl The scl pin 247 * @param[in] clk The clock to use can be shared, if not provided a new clock will be allocated 248 * @return The status of the init request 249 * 250 */ 251 cy_rslt_t cyhal_i2c_init(cyhal_i2c_t *obj, cyhal_gpio_t sda, cyhal_gpio_t scl, const cyhal_clock_t *clk); 252 253 /** Deinitialize the i2c object 254 * 255 * @param[in,out] obj The i2c object 256 */ 257 void cyhal_i2c_free(cyhal_i2c_t *obj); 258 259 /** Configure the I2C block. 260 * NOTE: Master/Slave specific functions only work when the block is configured 261 * to be in that mode.<br> 262 * See \ref subsection_i2c_snippet_1 263 * 264 * @param[in] obj The I2C object 265 * @param[in] cfg Configuration settings to apply 266 * @return The status of the configure request 267 * 268 */ 269 cy_rslt_t cyhal_i2c_configure(cyhal_i2c_t *obj, const cyhal_i2c_cfg_t *cfg); 270 271 /** Configure the I2C block with advanced parameters. 272 * Refer to \ref cyhal_i2c_adv_cfg_t structure for the description of advanced parameters. 273 * NOTE: Master/Slave specific functions only work when the block is configured 274 * to be in that mode.<br> 275 * See \ref subsection_i2c_snippet_1 276 * 277 * @param[in] obj The I2C object 278 * @param[in] cfg Advanced configuration settings to apply 279 * @return The status of the configure request 280 * 281 */ 282 cy_rslt_t cyhal_i2c_configure_adv(cyhal_i2c_t *obj, const cyhal_i2c_adv_cfg_t *cfg); 283 284 /** 285 * I2C master blocking write 286 * 287 * This will write `size` bytes of data from the buffer pointed to by `data`. It will not return 288 * until either all of the data has been written, or the timeout has elapsed. 289 * 290 * @param[in] obj The I2C object 291 * @param[in] dev_addr device address (7-bit) 292 * @param[in] data I2C send data 293 * @param[in] size I2C send data size 294 * @param[in] timeout timeout in millisecond, set this value to 0 if you want to wait forever 295 * @param[in] send_stop whether the stop should be send, used to support repeat start conditions 296 * 297 * @return The status of the master_write request 298 */ 299 cy_rslt_t cyhal_i2c_master_write(cyhal_i2c_t *obj, uint16_t dev_addr, const uint8_t *data, uint16_t size, uint32_t timeout, bool send_stop); 300 301 /** 302 * I2C master blocking read 303 * 304 * This will read `size` bytes of data into the buffer pointed to by `data`. It will not return 305 * until either all of the data has been read, or the timeout has elapsed. 306 * 307 * @param[in] obj The I2C object 308 * @param[in] dev_addr device address (7-bit) 309 * @param[out] data I2C receive data 310 * @param[in] size I2C receive data size 311 * @param[in] timeout timeout in millisecond, set this value to 0 if you want to wait forever 312 * @param[in] send_stop whether the stop should be send, used to support repeat start conditions 313 * 314 * @return The status of the master_read request 315 */ 316 cy_rslt_t cyhal_i2c_master_read(cyhal_i2c_t *obj, uint16_t dev_addr, uint8_t *data, uint16_t size, uint32_t timeout, bool send_stop); 317 318 /** 319 * The function configures the write buffer on an I2C Slave. This is the buffer to which the master writes data to. 320 * The user needs to setup a new buffer every time (i.e. call \ref cyhal_i2c_slave_config_write_buffer and \ref cyhal_i2c_slave_config_read_buffer 321 * every time the buffer has been used up)<br> 322 * See related code example: <a href="https://github.com/infineon/mtb-example-psoc6-i2c-master" ><b>PSoC™ 6 MCU: I2C Master</b></a> 323 * 324 * @param[in] obj The I2C object 325 * @param[in] data I2C slave send data 326 * @param[in] size I2C slave send data size 327 * 328 * @return The status of the slave_config_write_buffer request 329 */ 330 cy_rslt_t cyhal_i2c_slave_config_write_buffer(cyhal_i2c_t *obj, const uint8_t *data, uint16_t size); 331 332 /** 333 * The function configures the read buffer on an I2C Slave. This is the buffer from which the master reads data from. 334 * The user needs to setup a new buffer every time (i.e. call \ref cyhal_i2c_slave_config_write_buffer and \ref cyhal_i2c_slave_config_read_buffer 335 * every time the buffer has been used up)<br> 336 * See related code example: <a href="https://github.com/infineon/mtb-example-psoc6-i2c-master" ><b>PSoC™ 6 MCU: I2C Master</b></a> 337 * 338 * @param[in] obj The I2C object 339 * @param[out] data I2C slave receive data 340 * @param[in] size I2C slave receive data size 341 * 342 * @return The status of the slave_config_read_buffer request 343 */ 344 cy_rslt_t cyhal_i2c_slave_config_read_buffer(cyhal_i2c_t *obj, uint8_t *data, uint16_t size); 345 346 347 /** Perform an I2C write using a block of data stored at the specified memory location 348 * 349 * @param[in] obj The I2C object 350 * @param[in] address device address (7-bit) 351 * @param[in] mem_addr mem address to store the written data 352 * @param[in] mem_addr_size number of bytes in the mem address 353 * @param[in] data I2C master send data 354 * @param[in] size I2C master send data size 355 * @param[in] timeout timeout in millisecond, set this value to 0 if you want to wait forever 356 * @return The status of the write request 357 */ 358 359 cy_rslt_t cyhal_i2c_master_mem_write(cyhal_i2c_t *obj, uint16_t address, uint16_t mem_addr, uint16_t mem_addr_size, const uint8_t *data, uint16_t size, uint32_t timeout); 360 361 /** Perform an I2C read using a block of data stored at the specified memory location 362 * 363 * @param[in] obj The I2C object 364 * @param[in] address device address (7-bit) 365 * @param[in] mem_addr mem address to read the data from 366 * @param[in] mem_addr_size number of bytes in the mem address 367 * @param[out] data I2C master receive data 368 * @param[in] size I2C master receive data size 369 * @param[in] timeout timeout in millisecond, set this value to 0 if you want to wait forever 370 * @return The status of the read request 371 */ 372 cy_rslt_t cyhal_i2c_master_mem_read(cyhal_i2c_t *obj, uint16_t address, uint16_t mem_addr, uint16_t mem_addr_size, uint8_t *data, uint16_t size, uint32_t timeout); 373 374 /** Initiate a non-blocking I2C master asynchronous transfer. Supports simultaneous write and read operation.<br> 375 * 376 * This will transfer `rx_size` bytes into the buffer pointed to by `rx`, while simultaneously transfering 377 * `tx_size` bytes of data from the buffer pointed to by `tx`, both in the background. 378 * When the requested quantity of data has been received, the @ref CYHAL_I2C_MASTER_RD_CMPLT_EVENT will be raised. 379 * When the requested quantity of data has been transmitted, the @ref CYHAL_I2C_MASTER_WR_CMPLT_EVENT will be raised. 380 * See @ref cyhal_i2c_register_callback and @ref cyhal_i2c_enable_event. 381 * If either of <b>tx_size</b> or <b>rx_size</b> is '0', the respective write or read operation is not performed. 382 * See \ref subsection_i2c_snippet_3 383 * 384 * @param[in] obj The I2C object 385 * @param[in] address device address (7-bit) 386 * @param[in] tx The transmit buffer 387 * @param[in] tx_size The number of bytes to transmit. Use '0' if write operation is not required. 388 * @param[out] rx The receive buffer 389 * @param[in] rx_size The number of bytes to receive. Use '0' if read operation is not required. 390 * @return The status of the master_transfer_async request 391 * 392 */ 393 cy_rslt_t cyhal_i2c_master_transfer_async(cyhal_i2c_t *obj, uint16_t address, const void *tx, size_t tx_size, void *rx, size_t rx_size); 394 395 396 /** Abort asynchronous transfer.<br> 397 *This function aborts the ongoing transfer by generating a stop condition.<br> 398 * See \ref subsection_i2c_snippet_3 399 * 400 * @param[in] obj The I2C object 401 * @return The status of the abort_async request 402 * 403 */ 404 cy_rslt_t cyhal_i2c_abort_async(cyhal_i2c_t *obj); 405 406 /** Register an I2C event callback handler<br> 407 * 408 * This function will be called when one of the events enabled by \ref cyhal_i2c_enable_event occurs. 409 * 410 * See \ref subsection_i2c_snippet_2 411 * 412 * @param[in] obj The I2C object 413 * @param[in] callback The callback handler which will be invoked when an event triggers 414 * @param[in] callback_arg Generic argument that will be provided to the callback when called 415 * 416 */ 417 void cyhal_i2c_register_callback(cyhal_i2c_t *obj, cyhal_i2c_event_callback_t callback, void *callback_arg); 418 419 /** Register an I2C address callback handler<br> 420 * 421 * This function will be called when one of the events enabled by \ref cyhal_i2c_enable_address_event occurs. 422 * NOTE: This function will not have an effect if enable_address_callback parameter of 423 * \ref cyhal_i2c_adv_cfg_t structure was false when \ref cyhal_i2c_configure_adv was called. 424 * 425 * See \ref subsection_i2c_snippet_2 426 * 427 * @param[in] obj The I2C object 428 * @param[in] callback The callback handler which will be invoked when an event triggers 429 * @param[in] callback_arg Generic argument that will be provided to the callback when called 430 * 431 */ 432 void cyhal_i2c_register_address_callback(cyhal_i2c_t *obj, cyhal_i2c_address_callback_t callback, void *callback_arg); 433 434 /** Configure and Enable or Disable I2C Interrupt. 435 * 436 * When an enabled event occurs, the function specified by \ref cyhal_i2c_register_callback will be called. 437 * 438 * See \ref subsection_i2c_snippet_2 439 * 440 * @param[in] obj The I2C object 441 * @param[in] event The I2C event type 442 * @param[in] intr_priority The priority for NVIC interrupt events 443 * @param[in] enable True to turn on interrupts, False to turn off 444 */ 445 void cyhal_i2c_enable_event(cyhal_i2c_t *obj, cyhal_i2c_event_t event, uint8_t intr_priority, bool enable); 446 447 /** Configure and Enable or Disable I2C Address Interrupt. 448 * 449 * When an enabled event occurs, the function specified by \ref cyhal_i2c_register_address_callback will be called. 450 * 451 * See \ref subsection_i2c_snippet_2 452 * 453 * @param[in] obj The I2C object 454 * @param[in] event The I2C address event type 455 * @param[in] intr_priority The priority for NVIC interrupt events 456 * @param[in] enable True to turn on interrupts, False to turn off 457 */ 458 void cyhal_i2c_enable_address_event(cyhal_i2c_t *obj, cyhal_i2c_addr_event_t event, uint8_t intr_priority, bool enable); 459 460 /** Sets a threshold level for a FIFO that will generate an interrupt and a 461 * trigger output. The RX FIFO interrupt and trigger will be activated when 462 * the receive FIFO has more entries than the threshold. The TX FIFO interrupt 463 * and trigger will be activated when the transmit FIFO has less entries than 464 * the threshold. 465 * 466 * @param[in] obj The I2C object 467 * @param[in] type FIFO type to set level for 468 * @param[in] level Level threshold to set 469 * @return The status of the level set 470 * */ 471 cy_rslt_t cyhal_i2c_set_fifo_level(cyhal_i2c_t *obj, cyhal_i2c_fifo_type_t type, uint16_t level); 472 473 /** Enables the specified output signal from an I2C. 474 * 475 * @param[in] obj The I2C object 476 * @param[in] output Which output signal to enable 477 * @param[out] source Pointer to user-allocated source signal object which 478 * will be initialized by enable_output. \p source should be passed to 479 * (dis)connect_digital functions to (dis)connect the associated endpoints. 480 * @return The status of the output enable 481 * */ 482 cy_rslt_t cyhal_i2c_enable_output(cyhal_i2c_t *obj, cyhal_i2c_output_t output, cyhal_source_t *source); 483 484 /** Disables the specified output signal from an I2C 485 * 486 * @param[in] obj The I2C object 487 * @param[in] output Which output signal to disable 488 * @return The status of the output disable 489 * */ 490 cy_rslt_t cyhal_i2c_disable_output(cyhal_i2c_t *obj, cyhal_i2c_output_t output); 491 492 /** Initialize the I2C peripheral using a configurator generated configuration struct. 493 * 494 * @param[in] obj The I2C peripheral to configure 495 * @param[in] cfg Configuration structure generated by a configurator. 496 * @return The status of the operation 497 */ 498 cy_rslt_t cyhal_i2c_init_cfg(cyhal_i2c_t *obj, const cyhal_i2c_configurator_t *cfg); 499 500 501 /** Returns the number of bytes written by the I2C master. 502 * Calling the \ref cyhal_i2c_slave_config_write_buffer API will clear the counter of bytes sent by master 503 * 504 * @param[in] obj The I2C object 505 * @return The number of bytes written by the I2C master. 506 * */ 507 uint32_t cyhal_i2c_slave_readable(cyhal_i2c_t *obj); 508 509 /** Returns the number of bytes can be read by the I2C master. 510 * Calling the \ref cyhal_i2c_slave_config_read_buffer API will clear the counter of bytes read by master 511 * 512 * @param[in] obj The I2C object 513 * @return The number of bytes can be read by the I2C master. 514 * */ 515 uint32_t cyhal_i2c_slave_writable(cyhal_i2c_t *obj); 516 517 /** Wait for master send data to RX buffer and store them to the user-defined buffer. 518 * NOTE: If size of actual data is less then expected the function copy only available data. 519 * 520 * @param[in] obj The I2C object 521 * @param[in] dst_buff Pointer on memory to store the data from the slave RX buffer. 522 * @param[in,out] size [in] The number of bytes to read, [out] number actually read. 523 * @param[in] timeout Timeout in millisecond, set this value to 0 if you don't want to wait at all. 524 * @return The status of the read request 525 * */ 526 cy_rslt_t cyhal_i2c_slave_read(cyhal_i2c_t *obj, uint8_t *dst_buff, uint16_t *size, uint32_t timeout); 527 528 /** Write data from the user-defined buffer to I2C TX buffer. 529 * NOTE: If size of actual data is less then expected the function copy only available data. 530 * 531 * @param[in] obj The I2C object 532 * @param[in] src_buff Pointer on memory to copy the data to the slave TX buffer. 533 * @param[in,out] size [in] The number of bytes to send, [out] number actually sent. 534 * @param[in] timeout Timeout in millisecond, set this value to 0 if you don't want to wait at all. 535 * @return The status of the write request 536 * */ 537 cy_rslt_t cyhal_i2c_slave_write(cyhal_i2c_t *obj, const uint8_t *src_buff, uint16_t *size, uint32_t timeout); 538 539 /** 540 * The function aborts the configured slave read buffer to be read by the master. 541 * If the master reads and "abort operation" is requested, the 542 * \ref CYHAL_I2C_SLAVE_RD_BUF_EMPTY_EVENT event occurs. 543 * 544 * @param[in] obj The I2C object 545 * 546 * @return The status of the slave_abort_read request 547 */ 548 cy_rslt_t cyhal_i2c_slave_abort_read(cyhal_i2c_t *obj); 549 550 /** Clear the I2C buffers 551 * 552 * @param[in] obj The I2C object 553 * @return The status of the clear request 554 * */ 555 cy_rslt_t cyhal_i2c_clear(cyhal_i2c_t *obj); 556 557 #if defined(__cplusplus) 558 } 559 #endif 560 561 #ifdef CYHAL_I2C_IMPL_HEADER 562 #include CYHAL_I2C_IMPL_HEADER 563 #endif /* CYHAL_I2C_IMPL_HEADER */ 564 565 /** \} group_hal_i2c */ 566
