1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup I2C 11 * @{ 12 * 13 * @brief Provides standard Inter-Integrated Circuit (I2C) interfaces. 14 * 15 * This module allows a driver to perform operations on an I2C controller for accessing devices on the I2C bus, 16 * including creating and destroying I2C controller handles as well as reading and writing data. 17 * 18 * @since 1.0 19 */ 20 21 /** 22 * @file i2c_if.h 23 * 24 * @brief Declares the standard I2C interface functions. 25 * 26 * @since 1.0 27 */ 28 29 #ifndef I2C_IF_H 30 #define I2C_IF_H 31 32 #include "platform_if.h" 33 34 #ifdef __cplusplus 35 #if __cplusplus 36 extern "C" { 37 #endif 38 #endif /* __cplusplus */ 39 40 /** 41 * @brief Defines the I2C transfer message used during custom transfers. 42 * 43 * @attention This structure does not limit the data transfer length specified by <b>len</b>. 44 * The specific I2C controller determines the maximum length allowed. \n 45 * The device address <b>addr</b> indicates the original device address and does not need to 46 * contain the read/write flag bit. 47 * 48 * @since 1.0 49 */ 50 struct I2cMsg { 51 /** Address of the I2C device */ 52 uint16_t addr; 53 /** Address of the buffer for storing transferred data */ 54 uint8_t *buf; 55 /** Length of the transferred data */ 56 uint16_t len; 57 /** 58 * Transfer Mode Flag | Description 59 * ------------| ----------------------- 60 * I2C_FLAG_READ | Read flag 61 * I2C_FLAG_ADDR_10BIT | 10-bit addressing flag 62 * I2C_FLAG_READ_NO_ACK | No-ACK read flag 63 * I2C_FLAG_IGNORE_NO_ACK | Ignoring no-ACK flag 64 * I2C_FLAG_NO_START | No START condition flag 65 * I2C_FLAG_STOP | STOP condition flag 66 */ 67 uint16_t flags; 68 }; 69 70 /** 71 * @brief Enumerates flags used for transferring I2C messages. 72 * 73 * Multiple flags can be used to jointly control a single I2C message transfer. 74 * If a bit is set to <b>1</b>, the corresponding feature is enabled. If a bit is set to <b>0</b>, 75 * the corresponding feature is disabled. 76 * 77 * @since 1.0 78 */ 79 enum I2cFlag { 80 /** Read flag. The value <b>1</b> indicates the read operation, and <b>0</b> indicates the write operation. */ 81 I2C_FLAG_READ = (0x1 << 0), 82 /** 10-bit addressing flag. The value <b>1</b> indicates that a 10-bit address is used. */ 83 I2C_FLAG_ADDR_10BIT = (0x1 << 4), 84 /** Non-ACK read flag. The value <b>1</b> indicates that no ACK signal is sent during the read process. */ 85 I2C_FLAG_READ_NO_ACK = (0x1 << 11), 86 /** Ignoring no-ACK flag. The value <b>1</b> indicates that the non-ACK signal is ignored. */ 87 I2C_FLAG_IGNORE_NO_ACK = (0x1 << 12), 88 /** 89 * No START condition flag. The value <b>1</b> indicates that there is no START condition for the message 90 * transfer. 91 */ 92 I2C_FLAG_NO_START = (0x1 << 14), 93 /** STOP condition flag. The value <b>1</b> indicates that the current transfer ends with a STOP condition. */ 94 I2C_FLAG_STOP = (0x1 << 15), 95 }; 96 97 /** 98 * @brief Obtains the handle of an I2C controller. 99 * 100 * You must call this function before accessing the I2C bus. 101 * 102 * @param number Indicates the I2C controller ID. 103 * 104 * @return Returns the pointer to the {@link DevHandle} of the I2C controller if the operation is successful; 105 * returns <b>NULL</b> otherwise. 106 * @since 1.0 107 */ 108 DevHandle I2cOpen(int16_t number); 109 110 /** 111 * @brief Releases the handle of an I2C controller. 112 * 113 * If you no longer need to access the I2C controller, you should call this function to close its handle so as 114 * to release unused memory resources. 115 * 116 * @param handle Indicates the pointer to the device handle of the I2C controller. 117 * 118 * @since 1.0 119 */ 120 void I2cClose(DevHandle handle); 121 122 /** 123 * @brief Launches a custom transfer to an I2C device. 124 * 125 * @param handle Indicates the pointer to the device handle of the I2C controller obtained via {@link I2cOpen}. 126 * @param msgs Indicates the pointer to the I2C transfer message structure array. 127 * @param count Indicates the length of the message structure array. 128 * 129 * @return Returns the number of transferred message structures if the operation is successful; 130 * returns a negative value otherwise. 131 * @see I2cMsg 132 * @attention This function does not limit the number of message structures specified by <b>count</b> or the data 133 * length of each message structure. The specific I2C controller determines the maximum number and data length allowed. 134 * 135 * @since 1.0 136 */ 137 int32_t I2cTransfer(DevHandle handle, struct I2cMsg *msgs, int16_t count); 138 139 /** 140 * @brief Enumerates I2C I/O commands. 141 * 142 * @since 1.0 143 */ 144 enum I2cIoCmd { 145 I2C_IO_TRANSFER = 0, /**< Execute one or more I2C messages. */ 146 I2C_IO_OPEN = 1, /**< Open the I2C device. */ 147 I2C_IO_CLOSE = 2, /**< Close the I2C device. */ 148 }; 149 150 #ifdef __cplusplus 151 #if __cplusplus 152 } 153 #endif 154 #endif /* __cplusplus */ 155 156 #endif /* I2C_IF_H */ 157 /** @} */ 158