1 /** 2 * @file i2c.h 3 * @brief Inter-integrated circuit (I2C) communications interface driver. 4 */ 5 6 /* **************************************************************************** 7 * Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved. 8 * 9 * Permission is hereby granted, free of charge, to any person obtaining a 10 * copy of this software and associated documentation files (the "Software"), 11 * to deal in the Software without restriction, including without limitation 12 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 13 * and/or sell copies of the Software, and to permit persons to whom the 14 * Software is furnished to do so, subject to the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be included 17 * in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 20 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 22 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES 23 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 24 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 25 * OTHER DEALINGS IN THE SOFTWARE. 26 * 27 * Except as contained in this notice, the name of Maxim Integrated 28 * Products, Inc. shall not be used except as stated in the Maxim Integrated 29 * Products, Inc. Branding Policy. 30 * 31 * The mere transfer of this software does not imply any licenses 32 * of trade secrets, proprietary technology, copyrights, patents, 33 * trademarks, maskwork rights, or any other form of intellectual 34 * property whatsoever. Maxim Integrated Products, Inc. retains all 35 * ownership rights. 36 * 37 * $Date: 2019-06-28 09:42:42 -0500 (Fri, 28 Jun 2019) $ 38 * $Revision: 44330 $ 39 * 40 *************************************************************************** */ 41 42 #ifndef _I2C_H_ 43 #define _I2C_H_ 44 45 #include <stdint.h> 46 #include "i2c_regs.h" 47 #include "mxc_sys.h" 48 49 /** 50 * @defgroup i2c I2C 51 * @ingroup periphlibs 52 * @{ 53 */ 54 55 /***** Definitions *****/ 56 57 /// @brief I2C Speed Modes 58 typedef enum { 59 I2C_STD_MODE = 100000, //!< 100KHz Bus Speed 60 I2C_FAST_MODE = 400000, //!< 400KHz Bus Speed 61 I2C_FASTPLUS_MODE = 1000000, //!< 1MHz Bus Speed 62 I2C_HS_MODE = 3400000 //!< 3.4MHz Bus Speed 63 } i2c_speed_t; 64 65 //State for Master 66 typedef enum { 67 I2C_STATE_READING = 0, 68 I2C_STATE_WRITING = 1 69 } i2c_state_t; 70 71 // @brief Enable/Disable TXFIFO Autoflush mode 72 typedef enum { 73 I2C_AUTOFLUSH_ENABLE = 0, 74 I2C_AUTOFLUSH_DISABLE = 1 75 } i2c_autoflush_disable_t; 76 77 // @brief I2C Transaction request. 78 typedef struct i2c_req i2c_req_t; 79 struct i2c_req { 80 81 uint8_t addr; /**< @parblock I2C 7-bit Address left aligned, bit 7 to bit 1. 82 * Only supports 7-bit addressing. LSb of the given address 83 * will be used as the read/write bit, the @p addr <b>will 84 * not be shifted</b>. Used for <em>both master</em> and 85 * @em slave transactions. @endparblock 86 */ 87 const uint8_t *tx_data; ///< Data for mater write/slave read. 88 uint8_t *rx_data; ///< Data for master read/slave write. 89 unsigned tx_len; ///< Length of tx data. 90 unsigned rx_len; ///< Length of rx. 91 unsigned tx_num; ///< Number of tx bytes sent. 92 unsigned rx_num; ///< Number of rx bytes sent. 93 i2c_state_t state; ///< Read or Write. 94 95 /** 96 * @details 0 to send a stop bit at the end of the transaction, 97 otherwise send a restart. Only used in master trasnactions. 98 */ 99 int restart; /**< @parblock Restart or stop bit indicator. 100 * @arg 0 to send a stop bit at the end of the transaction 101 * @arg Non-zero to send a restart at end of the transaction 102 * @note Only used for Master transactions. 103 * @endparblock 104 */ 105 i2c_autoflush_disable_t sw_autoflush_disable; ///< Enable/Disable autoflush. 106 107 /** 108 * @brief Callback for asynchronous request. 109 * @param i2c_req_t* Pointer to the transaction request. 110 * @param int Error code. 111 */ 112 void (*callback)(i2c_req_t*, int); 113 }; 114 115 /***** Function Prototypes *****/ 116 117 /** 118 * @brief Initialize and enable I2C. 119 * @param i2c Pointer to I2C peripheral registers. 120 * @param i2cspeed desired speed (I2C mode) 121 * @param sys_cfg System configuration object 122 * @returns \c #E_NO_ERROR if everything is successful, 123 * @ref MXC_Error_Codes if an error occurred. 124 */ 125 int I2C_Init(mxc_i2c_regs_t * i2c, i2c_speed_t i2cspeed, const sys_cfg_i2c_t* sys_cfg); 126 127 /** 128 * @brief Shutdown I2C module. 129 * @param i2c Pointer to the I2C registers. 130 * @returns #E_NO_ERROR I2C shutdown successfully, @ref MXC_Error_Codes "error" if 131 * unsuccessful. 132 */ 133 int I2C_Shutdown(mxc_i2c_regs_t *i2c); 134 135 /** 136 * @brief Master write data. Will block until transaction is complete. 137 * @param i2c Pointer to I2C regs. 138 * @param addr @parblock I2C 7-bit Address left aligned, bit 7 to bit 1. 139 * Only supports 7-bit addressing. LSb of the given address 140 * will be used as the read/write bit, the \p addr <b>will 141 * not be shifted</b>. Used for <em>both master</em> and 142 * @em slave transactions. @endparblock 143 * @param data Data to be written. 144 * @param len Number of bytes to Write. 145 * @param restart 0 to send a stop bit at the end of the transaction, 146 otherwise send a restart. 147 * @returns Bytes transacted if everything is successful, 148 * @ref MXC_Error_Codes if an error occurred. 149 */ 150 int I2C_MasterWrite(mxc_i2c_regs_t *i2c, uint8_t addr, const uint8_t* data, int len, int restart); 151 152 /** 153 * @brief Master read data. Will block until transaction is complete. 154 * @param i2c Pointer to I2C regs. 155 * @param addr @parblock I2C 7-bit Address left aligned, bit 7 to bit 1. 156 * Only supports 7-bit addressing. LSb of the given address 157 * will be used as the read/write bit, the @p addr <b>will 158 * not be shifted</b>. Used for <em>both master</em> and 159 * @em slave transactions. @endparblock 160 * @param data Data to be written. 161 * @param len Number of bytes to Write. 162 * @param restart 0 to send a stop bit at the end of the transaction, 163 otherwise send a restart. 164 * @returns Bytes transacted if everything is successful, @ref MXC_Error_Codes if an error occurred. 165 */ 166 int I2C_MasterRead(mxc_i2c_regs_t *i2c, uint8_t addr, uint8_t* data, int len, int restart); 167 168 /** 169 * @brief Slave read data. Will block until transaction is complete. 170 * @param i2c Pointer to I2C regs. 171 * @param addr @parblock I2C 7-bit Address left aligned, bit 7 to bit 1. 172 * Only supports 7-bit addressing. LSb of the given address 173 * will be used as the read/write bit, the @p addr <b>will 174 * not be shifted</b>. Used for <em>both master</em> and 175 * @em slave transactions. @endparblock 176 * @param read_data Buffer that the master will read from. 177 * @param read_len Number of bytes the master can read. 178 * @param write_data Buffer that the master will write to. 179 * @param write_len Number of bytes the master can write. 180 * @param tx_num Number of bytes transmitted by the slave. 181 * @param rx_num Number of bytes received by the slave. 182 * @param sw_autoflush_disable TX Autoflush enabled by default.Set this bit to disable autoflush manually. 183 * @returns #E_NO_ERROR if everything is successful, @ref MXC_Error_Codes if an error occurred. 184 */ 185 int I2C_Slave(mxc_i2c_regs_t *i2c, uint8_t addr, const uint8_t* read_data, 186 int read_len, uint8_t* write_data, int write_len, int* tx_num, 187 int* rx_num, i2c_autoflush_disable_t sw_autoflush_disable); 188 189 /** 190 * @brief Master Read and Write Asynchronous. 191 * @param i2c Pointer to I2C regs. 192 * @param req Request for an I2C transaction. 193 * @returns #E_NO_ERROR if everything is successful, @ref MXC_Error_Codes if an error occurred. 194 */ 195 int I2C_MasterAsync(mxc_i2c_regs_t *i2c, i2c_req_t *req); 196 197 /** 198 * @brief Slave Read and Write Asynchronous. 199 * @param i2c Pointer to I2C regs. 200 * @param req Request for an I2C transaction. 201 * @returns #E_NO_ERROR if everything is successful, @ref MXC_Error_Codes if an error occurred. 202 */ 203 int I2C_SlaveAsync(mxc_i2c_regs_t *i2c, i2c_req_t *req); 204 /** 205 * @brief I2C interrupt handler. 206 * @details This function should be called by the application from the interrupt 207 * handler if I2C interrupts are enabled. Alternately, this function 208 * can be periodically called by the application if I2C interrupts are 209 * disabled. 210 * @param i2c Base address of the I2C module. 211 */ 212 void I2C_Handler(mxc_i2c_regs_t *i2c); 213 214 /** 215 * @brief Drain all of the data in the RXFIFO. 216 * @param i2c Pointer to I2C regs. 217 */ 218 void I2C_DrainRX(mxc_i2c_regs_t *i2c); 219 220 /** 221 * @brief Drain all of the data in the TXFIFO. 222 * @param i2c Pointer to I2C regs. 223 */ 224 void I2C_DrainTX(mxc_i2c_regs_t *i2c); 225 226 /** 227 * @brief Abort Async request based on the request you want to abort. 228 * @param req Pointer to I2C Transaction. 229 */ 230 int I2C_AbortAsync(i2c_req_t *req); 231 232 /** 233 * @brief Enable and Set Timeout 234 * 235 * @param i2c pointer to I2C regs 236 * @param[in] us micro seconds to delay 237 * 238 * @return E_NO_ERROR or E_BAD_PARAM if delay is to long. 239 */ 240 int I2C_SetTimeout(mxc_i2c_regs_t *i2c, int us); 241 242 /** 243 * @brief clear and disable timeout 244 * 245 * @param i2c pointer to I2C regs 246 */ 247 void I2C_ClearTimeout(mxc_i2c_regs_t *i2c); 248 249 /**@} end of group i2c */ 250 #endif /* _I2C_H_ */ 251