begriffs open source - cmsis/blob - CMSIS/Driver/Include/Driver_I2C.h

   1 /*
   2  * Copyright (c) 2013-2016 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  * http://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:        9. May 2014
  19  * $Revision:    V2.02
  20  *
  21  * Project:      I2C (Inter-Integrated Circuit) Driver definitions
  22  */
  23
  24 /* History:
  25  *  Version 2.02
  26  *    Removed function ARM_I2C_MasterTransfer in order to simplify drivers
  27  *      and added back parameter "xfer_pending" to functions
  28  *      ARM_I2C_MasterTransmit and ARM_I2C_MasterReceive
  29  *  Version 2.01
  30  *    Added function ARM_I2C_MasterTransfer and removed parameter "xfer_pending"
  31  *      from functions ARM_I2C_MasterTransmit and ARM_I2C_MasterReceive
  32  *    Added function ARM_I2C_GetDataCount
  33  *    Removed flag "address_nack" from ARM_I2C_STATUS
  34  *    Replaced events ARM_I2C_EVENT_MASTER_DONE and ARM_I2C_EVENT_SLAVE_DONE
  35  *      with event ARM_I2C_EVENT_TRANSFER_DONE
  36  *    Added event ARM_I2C_EVENT_TRANSFER_INCOMPLETE
  37  *    Removed parameter "arg" from function ARM_I2C_SignalEvent
  38  *  Version 2.00
  39  *    New simplified driver:
  40  *      complexity moved to upper layer (especially data handling)
  41  *      more unified API for different communication interfaces
  42  *    Added:
  43  *      Slave Mode
  44  *    Changed prefix ARM_DRV -> ARM_DRIVER
  45  *  Version 1.10
  46  *    Namespace prefix ARM_ added
  47  *  Version 1.00
  48  *    Initial release
  49  */
  50
  51 #ifndef DRIVER_I2C_H_
  52 #define DRIVER_I2C_H_
  53
  54 #ifdef  __cplusplus
  55 extern "C"
  56 {
  57 #endif
  58
  59 #include "Driver_Common.h"
  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   uint32_t busy             : 1;        ///< Busy flag
  89   uint32_t mode             : 1;        ///< Mode: 0=Slave, 1=Master
  90   uint32_t direction        : 1;        ///< Direction: 0=Transmitter, 1=Receiver
  91   uint32_t general_call     : 1;        ///< General Call indication (cleared on start of next Slave operation)
  92   uint32_t arbitration_lost : 1;        ///< Master lost arbitration (cleared on start of next Master operation)
  93   uint32_t 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 #ifdef  __cplusplus
 210 }
 211 #endif
 212
 213 #endif /* DRIVER_I2C_H_ */