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

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