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 /** Dma flag. The value <b>1</b> indicates that the buffer of this message is DMA safe. */ 85 I2C_FLAG_DMA = (0x1 << 9), 86 /** Non-ACK read flag. The value <b>1</b> indicates that no ACK signal is sent during the read process. */ 87 I2C_FLAG_READ_NO_ACK = (0x1 << 11), 88 /** Ignoring no-ACK flag. The value <b>1</b> indicates that the non-ACK signal is ignored. */ 89 I2C_FLAG_IGNORE_NO_ACK = (0x1 << 12), 90 /** 91 * No START condition flag. The value <b>1</b> indicates that there is no START condition for the message 92 * transfer. 93 */ 94 I2C_FLAG_NO_START = (0x1 << 14), 95 /** STOP condition flag. The value <b>1</b> indicates that the current transfer ends with a STOP condition. */ 96 I2C_FLAG_STOP = (0x1 << 15), 97 }; 98 99 /** 100 * @brief Obtains the handle of an I2C controller. 101 * 102 * You must call this function before accessing the I2C bus. 103 * 104 * @param number Indicates the I2C controller ID. 105 * 106 * @return Returns the pointer to the {@link DevHandle} of the I2C controller if the operation is successful; 107 * returns <b>NULL</b> otherwise. 108 * @since 1.0 109 */ 110 DevHandle I2cOpen(int16_t number); 111 112 /** 113 * @brief Releases the handle of an I2C controller. 114 * 115 * If you no longer need to access the I2C controller, you should call this function to close its handle so as 116 * to release unused memory resources. 117 * 118 * @param handle Indicates the pointer to the device handle of the I2C controller. 119 * 120 * @since 1.0 121 */ 122 void I2cClose(DevHandle handle); 123 124 /** 125 * @brief Launches a custom transfer to an I2C device. 126 * 127 * @param handle Indicates the pointer to the device handle of the I2C controller obtained via {@link I2cOpen}. 128 * @param msgs Indicates the pointer to the I2C transfer message structure array. 129 * @param count Indicates the length of the message structure array. 130 * 131 * @return Returns the number of transferred message structures if the operation is successful; 132 * returns a negative value otherwise. 133 * @see I2cMsg 134 * @attention This function does not limit the number of message structures specified by <b>count</b> or the data 135 * length of each message structure. The specific I2C controller determines the maximum number and data length allowed. 136 * 137 * @since 1.0 138 */ 139 int32_t I2cTransfer(DevHandle handle, struct I2cMsg *msgs, int16_t count); 140 141 /** 142 * @brief Enumerates I2C I/O commands. 143 * 144 * @since 1.0 145 */ 146 enum I2cIoCmd { 147 I2C_IO_TRANSFER = 0, /**< Execute one or more I2C messages. */ 148 I2C_IO_OPEN = 1, /**< Open the I2C device. */ 149 I2C_IO_CLOSE = 2, /**< Close the I2C device. */ 150 }; 151 152 /** 153 * @brief The following i2c interfaces are only available for the mini platform 154 * 155 * @since 1.0 156 */ 157 158 int32_t I2cRead(DevHandle handle, uint8_t *buf, uint16_t len); 159 160 int32_t I2cWrite(DevHandle handle, uint8_t *buf, uint16_t len); 161 162 #ifdef __cplusplus 163 #if __cplusplus 164 } 165 #endif 166 #endif /* __cplusplus */ 167 168 #endif /* I2C_IF_H */ 169 /** @} */ 170