1 /* ----------------------------------------------------------------------------- 2 * SPDX-License-Identifier: Zlib 3 * Copyright (c) 2013-2014 ARM Ltd. 4 * 5 * This software is provided 'as-is', without any express or implied warranty. 6 * In no event will the authors be held liable for any damages arising from 7 * the use of this software. Permission is granted to anyone to use this 8 * software for any purpose, including commercial applications, and to alter 9 * it and redistribute it freely, subject to the following restrictions: 10 * 11 * 1. The origin of this software must not be misrepresented; you must not 12 * claim that you wrote the original software. If you use this software in 13 * a product, an acknowledgment in the product documentation would be 14 * appreciated but is not required. 15 * 16 * 2. Altered source versions must be plainly marked as such, and must not be 17 * misrepresented as being the original software. 18 * 19 * 3. This notice may not be removed or altered from any source distribution. 20 * 21 * 22 * $Date: 9. May 2014 23 * $Revision: V2.02 24 * 25 * Project: I2C (Inter-Integrated Circuit) Driver definitions 26 * -------------------------------------------------------------------------- */ 27 28 /* History: 29 * Version 2.02 30 * Removed function ARM_I2C_MasterTransfer in order to simplify drivers 31 * and added back parameter "xfer_pending" to functions 32 * ARM_I2C_MasterTransmit and ARM_I2C_MasterReceive 33 * Version 2.01 34 * Added function ARM_I2C_MasterTransfer and removed parameter "xfer_pending" 35 * from functions ARM_I2C_MasterTransmit and ARM_I2C_MasterReceive 36 * Added function ARM_I2C_GetDataCount 37 * Removed flag "address_nack" from ARM_I2C_STATUS 38 * Replaced events ARM_I2C_EVENT_MASTER_DONE and ARM_I2C_EVENT_SLAVE_DONE 39 * with event ARM_I2C_EVENT_TRANSFER_DONE 40 * Added event ARM_I2C_EVENT_TRANSFER_INCOMPLETE 41 * Removed parameter "arg" from function ARM_I2C_SignalEvent 42 * Version 2.00 43 * New simplified driver: 44 * complexity moved to upper layer (especially data handling) 45 * more unified API for different communication interfaces 46 * Added: 47 * Slave Mode 48 * Changed prefix ARM_DRV -> ARM_DRIVER 49 * Version 1.10 50 * Namespace prefix ARM_ added 51 * Version 1.00 52 * Initial release 53 */ 54 55 #ifndef __DRIVER_I2C_H 56 #define __DRIVER_I2C_H 57 58 #include "Driver_Common.h" 59 60 61 #define ARM_I2C_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,02) /* API version */ 62 63 64 /****** I2C Control Codes *****/ 65 66 #define ARM_I2C_OWN_ADDRESS (0x01) ///< Set Own Slave Address; arg = address 67 #define ARM_I2C_BUS_SPEED (0x02) ///< Set Bus Speed; arg = speed 68 #define ARM_I2C_BUS_CLEAR (0x03) ///< Execute Bus clear: send nine clock pulses 69 #define ARM_I2C_ABORT_TRANSFER (0x04) ///< Abort Master/Slave Transmit/Receive 70 71 /*----- I2C Bus Speed -----*/ 72 #define ARM_I2C_BUS_SPEED_STANDARD (0x01) ///< Standard Speed (100kHz) 73 #define ARM_I2C_BUS_SPEED_FAST (0x02) ///< Fast Speed (400kHz) 74 #define ARM_I2C_BUS_SPEED_FAST_PLUS (0x03) ///< Fast+ Speed ( 1MHz) 75 #define ARM_I2C_BUS_SPEED_HIGH (0x04) ///< High Speed (3.4MHz) 76 77 78 /****** I2C Address Flags *****/ 79 80 #define ARM_I2C_ADDRESS_10BIT 0x0400 ///< 10-bit address flag 81 #define ARM_I2C_ADDRESS_GC 0x8000 ///< General Call flag 82 83 84 /** 85 \brief I2C Status 86 */ 87 typedef struct _ARM_I2C_STATUS { 88 unsigned int busy : 1; ///< Busy flag 89 unsigned int mode : 1; ///< Mode: 0=Slave, 1=Master 90 unsigned int direction : 1; ///< Direction: 0=Transmitter, 1=Receiver 91 unsigned int general_call : 1; ///< General Call indication (cleared on start of next Slave operation) 92 unsigned int arbitration_lost : 1; ///< Master lost arbitration (cleared on start of next Master operation) 93 unsigned int bus_error : 1; ///< Bus error detected (cleared on start of next Master/Slave operation) 94 } ARM_I2C_STATUS; 95 96 97 /****** I2C Event *****/ 98 #define ARM_I2C_EVENT_TRANSFER_DONE (1UL << 0) ///< Master/Slave Transmit/Receive finished 99 #define ARM_I2C_EVENT_TRANSFER_INCOMPLETE (1UL << 1) ///< Master/Slave Transmit/Receive incomplete transfer 100 #define ARM_I2C_EVENT_SLAVE_TRANSMIT (1UL << 2) ///< Slave Transmit operation requested 101 #define ARM_I2C_EVENT_SLAVE_RECEIVE (1UL << 3) ///< Slave Receive operation requested 102 #define ARM_I2C_EVENT_ADDRESS_NACK (1UL << 4) ///< Address not acknowledged from Slave 103 #define ARM_I2C_EVENT_GENERAL_CALL (1UL << 5) ///< General Call indication 104 #define ARM_I2C_EVENT_ARBITRATION_LOST (1UL << 6) ///< Master lost arbitration 105 #define ARM_I2C_EVENT_BUS_ERROR (1UL << 7) ///< Bus error detected (START/STOP at illegal position) 106 #define ARM_I2C_EVENT_BUS_CLEAR (1UL << 8) ///< Bus clear finished 107 108 109 // Function documentation 110 /** 111 \fn ARM_DRIVER_VERSION ARM_I2C_GetVersion (void) 112 \brief Get driver version. 113 \return \ref ARM_DRIVER_VERSION 114 115 \fn ARM_I2C_CAPABILITIES ARM_I2C_GetCapabilities (void) 116 \brief Get driver capabilities. 117 \return \ref ARM_I2C_CAPABILITIES 118 119 \fn int32_t ARM_I2C_Initialize (ARM_I2C_SignalEvent_t cb_event) 120 \brief Initialize I2C Interface. 121 \param[in] cb_event Pointer to \ref ARM_I2C_SignalEvent 122 \return \ref execution_status 123 124 \fn int32_t ARM_I2C_Uninitialize (void) 125 \brief De-initialize I2C Interface. 126 \return \ref execution_status 127 128 \fn int32_t ARM_I2C_PowerControl (ARM_POWER_STATE state) 129 \brief Control I2C Interface Power. 130 \param[in] state Power state 131 \return \ref execution_status 132 133 \fn int32_t ARM_I2C_MasterTransmit (uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending) 134 \brief Start transmitting data as I2C Master. 135 \param[in] addr Slave address (7-bit or 10-bit) 136 \param[in] data Pointer to buffer with data to transmit to I2C Slave 137 \param[in] num Number of data bytes to transmit 138 \param[in] xfer_pending Transfer operation is pending - Stop condition will not be generated 139 \return \ref execution_status 140 141 \fn int32_t ARM_I2C_MasterReceive (uint32_t addr, uint8_t *data, uint32_t num, bool xfer_pending) 142 \brief Start receiving data as I2C Master. 143 \param[in] addr Slave address (7-bit or 10-bit) 144 \param[out] data Pointer to buffer for data to receive from I2C Slave 145 \param[in] num Number of data bytes to receive 146 \param[in] xfer_pending Transfer operation is pending - Stop condition will not be generated 147 \return \ref execution_status 148 149 \fn int32_t ARM_I2C_SlaveTransmit (const uint8_t *data, uint32_t num) 150 \brief Start transmitting data as I2C Slave. 151 \param[in] data Pointer to buffer with data to transmit to I2C Master 152 \param[in] num Number of data bytes to transmit 153 \return \ref execution_status 154 155 \fn int32_t ARM_I2C_SlaveReceive (uint8_t *data, uint32_t num) 156 \brief Start receiving data as I2C Slave. 157 \param[out] data Pointer to buffer for data to receive from I2C Master 158 \param[in] num Number of data bytes to receive 159 \return \ref execution_status 160 161 \fn int32_t ARM_I2C_GetDataCount (void) 162 \brief Get transferred data count. 163 \return number of data bytes transferred; -1 when Slave is not addressed by Master 164 165 \fn int32_t ARM_I2C_Control (uint32_t control, uint32_t arg) 166 \brief Control I2C Interface. 167 \param[in] control Operation 168 \param[in] arg Argument of operation (optional) 169 \return \ref execution_status 170 171 \fn ARM_I2C_STATUS ARM_I2C_GetStatus (void) 172 \brief Get I2C status. 173 \return I2C status \ref ARM_I2C_STATUS 174 175 \fn void ARM_I2C_SignalEvent (uint32_t event) 176 \brief Signal I2C Events. 177 \param[in] event \ref I2C_events notification mask 178 */ 179 180 typedef void (*ARM_I2C_SignalEvent_t) (uint32_t event); ///< Pointer to \ref ARM_I2C_SignalEvent : Signal I2C Event. 181 182 183 /** 184 \brief I2C Driver Capabilities. 185 */ 186 typedef struct _ARM_I2C_CAPABILITIES { 187 uint32_t address_10_bit : 1; ///< supports 10-bit addressing 188 } ARM_I2C_CAPABILITIES; 189 190 191 /** 192 \brief Access structure of the I2C Driver. 193 */ 194 typedef struct _ARM_DRIVER_I2C { 195 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_I2C_GetVersion : Get driver version. 196 ARM_I2C_CAPABILITIES (*GetCapabilities)(void); ///< Pointer to \ref ARM_I2C_GetCapabilities : Get driver capabilities. 197 int32_t (*Initialize) (ARM_I2C_SignalEvent_t cb_event); ///< Pointer to \ref ARM_I2C_Initialize : Initialize I2C Interface. 198 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_I2C_Uninitialize : De-initialize I2C Interface. 199 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_I2C_PowerControl : Control I2C Interface Power. 200 int32_t (*MasterTransmit) (uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending); ///< Pointer to \ref ARM_I2C_MasterTransmit : Start transmitting data as I2C Master. 201 int32_t (*MasterReceive) (uint32_t addr, uint8_t *data, uint32_t num, bool xfer_pending); ///< Pointer to \ref ARM_I2C_MasterReceive : Start receiving data as I2C Master. 202 int32_t (*SlaveTransmit) ( const uint8_t *data, uint32_t num); ///< Pointer to \ref ARM_I2C_SlaveTransmit : Start transmitting data as I2C Slave. 203 int32_t (*SlaveReceive) ( uint8_t *data, uint32_t num); ///< Pointer to \ref ARM_I2C_SlaveReceive : Start receiving data as I2C Slave. 204 int32_t (*GetDataCount) (void); ///< Pointer to \ref ARM_I2C_GetDataCount : Get transferred data count. 205 int32_t (*Control) (uint32_t control, uint32_t arg); ///< Pointer to \ref ARM_I2C_Control : Control I2C Interface. 206 ARM_I2C_STATUS (*GetStatus) (void); ///< Pointer to \ref ARM_I2C_GetStatus : Get I2C status. 207 } const ARM_DRIVER_I2C; 208 209 #endif /* __DRIVER_I2C_H */ 210
