1 /* 2 * Copyright (c) 2013-2020 ARM Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 * 6 * Licensed under the Apache License, Version 2.0 (the License); you may 7 * not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT 14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 * $Date: 31. March 2020 19 * $Revision: V2.4 20 * 21 * Project: I2C (Inter-Integrated Circuit) Driver definitions 22 */ 23 24 /* History: 25 * Version 2.4 26 * Removed volatile from ARM_I2C_STATUS 27 * Version 2.3 28 * ARM_I2C_STATUS made volatile 29 * Version 2.2 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.1 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.0 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 #ifdef __cplusplus 59 extern "C" 60 { 61 #endif 62 63 #include "Driver_Common.h" 64 65 #define ARM_I2C_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,4) /* API version */ 66 67 68 #define _ARM_Driver_I2C_(n) Driver_I2C##n 69 #define ARM_Driver_I2C_(n) _ARM_Driver_I2C_(n) 70 71 72 /****** I2C Control Codes *****/ 73 74 #define ARM_I2C_OWN_ADDRESS (0x01UL) ///< Set Own Slave Address; arg = address 75 #define ARM_I2C_BUS_SPEED (0x02UL) ///< Set Bus Speed; arg = speed 76 #define ARM_I2C_BUS_CLEAR (0x03UL) ///< Execute Bus clear: send nine clock pulses 77 #define ARM_I2C_ABORT_TRANSFER (0x04UL) ///< Abort Master/Slave Transmit/Receive 78 79 /*----- I2C Bus Speed -----*/ 80 #define ARM_I2C_BUS_SPEED_STANDARD (0x01UL) ///< Standard Speed (100kHz) 81 #define ARM_I2C_BUS_SPEED_FAST (0x02UL) ///< Fast Speed (400kHz) 82 #define ARM_I2C_BUS_SPEED_FAST_PLUS (0x03UL) ///< Fast+ Speed ( 1MHz) 83 #define ARM_I2C_BUS_SPEED_HIGH (0x04UL) ///< High Speed (3.4MHz) 84 85 86 /****** I2C Address Flags *****/ 87 88 #define ARM_I2C_ADDRESS_10BIT (0x0400UL) ///< 10-bit address flag 89 #define ARM_I2C_ADDRESS_GC (0x8000UL) ///< General Call flag 90 91 92 /** 93 \brief I2C Status 94 */ 95 typedef struct _ARM_I2C_STATUS { 96 uint32_t busy : 1; ///< Busy flag 97 uint32_t mode : 1; ///< Mode: 0=Slave, 1=Master 98 uint32_t direction : 1; ///< Direction: 0=Transmitter, 1=Receiver 99 uint32_t general_call : 1; ///< General Call indication (cleared on start of next Slave operation) 100 uint32_t arbitration_lost : 1; ///< Master lost arbitration (cleared on start of next Master operation) 101 uint32_t bus_error : 1; ///< Bus error detected (cleared on start of next Master/Slave operation) 102 uint32_t reserved : 26; 103 } ARM_I2C_STATUS; 104 105 106 /****** I2C Event *****/ 107 #define ARM_I2C_EVENT_TRANSFER_DONE (1UL << 0) ///< Master/Slave Transmit/Receive finished 108 #define ARM_I2C_EVENT_TRANSFER_INCOMPLETE (1UL << 1) ///< Master/Slave Transmit/Receive incomplete transfer 109 #define ARM_I2C_EVENT_SLAVE_TRANSMIT (1UL << 2) ///< Addressed as Slave Transmitter but transmit operation is not set. 110 #define ARM_I2C_EVENT_SLAVE_RECEIVE (1UL << 3) ///< Addressed as Slave Receiver but receive operation is not set. 111 #define ARM_I2C_EVENT_ADDRESS_NACK (1UL << 4) ///< Address not acknowledged from Slave 112 #define ARM_I2C_EVENT_GENERAL_CALL (1UL << 5) ///< Slave addressed with general call address 113 #define ARM_I2C_EVENT_ARBITRATION_LOST (1UL << 6) ///< Master lost arbitration 114 #define ARM_I2C_EVENT_BUS_ERROR (1UL << 7) ///< Bus error detected (START/STOP at illegal position) 115 #define ARM_I2C_EVENT_BUS_CLEAR (1UL << 8) ///< Bus clear finished 116 117 118 // Function documentation 119 /** 120 \fn ARM_DRIVER_VERSION ARM_I2C_GetVersion (void) 121 \brief Get driver version. 122 \return \ref ARM_DRIVER_VERSION 123 124 \fn ARM_I2C_CAPABILITIES ARM_I2C_GetCapabilities (void) 125 \brief Get driver capabilities. 126 \return \ref ARM_I2C_CAPABILITIES 127 128 \fn int32_t ARM_I2C_Initialize (ARM_I2C_SignalEvent_t cb_event) 129 \brief Initialize I2C Interface. 130 \param[in] cb_event Pointer to \ref ARM_I2C_SignalEvent 131 \return \ref execution_status 132 133 \fn int32_t ARM_I2C_Uninitialize (void) 134 \brief De-initialize I2C Interface. 135 \return \ref execution_status 136 137 \fn int32_t ARM_I2C_PowerControl (ARM_POWER_STATE state) 138 \brief Control I2C Interface Power. 139 \param[in] state Power state 140 \return \ref execution_status 141 142 \fn int32_t ARM_I2C_MasterTransmit (uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending) 143 \brief Start transmitting data as I2C Master. 144 \param[in] addr Slave address (7-bit or 10-bit) 145 \param[in] data Pointer to buffer with data to transmit to I2C Slave 146 \param[in] num Number of data bytes to transmit 147 \param[in] xfer_pending Transfer operation is pending - Stop condition will not be generated 148 \return \ref execution_status 149 150 \fn int32_t ARM_I2C_MasterReceive (uint32_t addr, uint8_t *data, uint32_t num, bool xfer_pending) 151 \brief Start receiving data as I2C Master. 152 \param[in] addr Slave address (7-bit or 10-bit) 153 \param[out] data Pointer to buffer for data to receive from I2C Slave 154 \param[in] num Number of data bytes to receive 155 \param[in] xfer_pending Transfer operation is pending - Stop condition will not be generated 156 \return \ref execution_status 157 158 \fn int32_t ARM_I2C_SlaveTransmit (const uint8_t *data, uint32_t num) 159 \brief Start transmitting data as I2C Slave. 160 \param[in] data Pointer to buffer with data to transmit to I2C Master 161 \param[in] num Number of data bytes to transmit 162 \return \ref execution_status 163 164 \fn int32_t ARM_I2C_SlaveReceive (uint8_t *data, uint32_t num) 165 \brief Start receiving data as I2C Slave. 166 \param[out] data Pointer to buffer for data to receive from I2C Master 167 \param[in] num Number of data bytes to receive 168 \return \ref execution_status 169 170 \fn int32_t ARM_I2C_GetDataCount (void) 171 \brief Get transferred data count. 172 \return number of data bytes transferred; -1 when Slave is not addressed by Master 173 174 \fn int32_t ARM_I2C_Control (uint32_t control, uint32_t arg) 175 \brief Control I2C Interface. 176 \param[in] control Operation 177 \param[in] arg Argument of operation (optional) 178 \return \ref execution_status 179 180 \fn ARM_I2C_STATUS ARM_I2C_GetStatus (void) 181 \brief Get I2C status. 182 \return I2C status \ref ARM_I2C_STATUS 183 184 \fn void ARM_I2C_SignalEvent (uint32_t event) 185 \brief Signal I2C Events. 186 \param[in] event \ref I2C_events notification mask 187 */ 188 189 typedef void (*ARM_I2C_SignalEvent_t) (uint32_t event); ///< Pointer to \ref ARM_I2C_SignalEvent : Signal I2C Event. 190 191 192 /** 193 \brief I2C Driver Capabilities. 194 */ 195 typedef struct _ARM_I2C_CAPABILITIES { 196 uint32_t address_10_bit : 1; ///< supports 10-bit addressing 197 uint32_t reserved : 31; ///< Reserved (must be zero) 198 } ARM_I2C_CAPABILITIES; 199 200 201 /** 202 \brief Access structure of the I2C Driver. 203 */ 204 typedef struct _ARM_DRIVER_I2C { 205 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_I2C_GetVersion : Get driver version. 206 ARM_I2C_CAPABILITIES (*GetCapabilities)(void); ///< Pointer to \ref ARM_I2C_GetCapabilities : Get driver capabilities. 207 int32_t (*Initialize) (ARM_I2C_SignalEvent_t cb_event); ///< Pointer to \ref ARM_I2C_Initialize : Initialize I2C Interface. 208 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_I2C_Uninitialize : De-initialize I2C Interface. 209 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_I2C_PowerControl : Control I2C Interface Power. 210 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. 211 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. 212 int32_t (*SlaveTransmit) ( const uint8_t *data, uint32_t num); ///< Pointer to \ref ARM_I2C_SlaveTransmit : Start transmitting data as I2C Slave. 213 int32_t (*SlaveReceive) ( uint8_t *data, uint32_t num); ///< Pointer to \ref ARM_I2C_SlaveReceive : Start receiving data as I2C Slave. 214 int32_t (*GetDataCount) (void); ///< Pointer to \ref ARM_I2C_GetDataCount : Get transferred data count. 215 int32_t (*Control) (uint32_t control, uint32_t arg); ///< Pointer to \ref ARM_I2C_Control : Control I2C Interface. 216 ARM_I2C_STATUS (*GetStatus) (void); ///< Pointer to \ref ARM_I2C_GetStatus : Get I2C status. 217 } const ARM_DRIVER_I2C; 218 219 #ifdef __cplusplus 220 } 221 #endif 222 223 #endif /* DRIVER_I2C_H_ */ 224
