MdePkg/Include/Pi/PiI2c.h

   1 /** @file
   2   Include file matches things in PI.
   3
   4 Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials are licensed and made available under
   6 the terms and conditions of the BSD License that accompanies this distribution.
   7 The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php.
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   @par Revision Reference:
  14   PI Version 1.3
  15
  16 **/
  17
  18 #ifndef __PI_I2C_H__
  19 #define __PI_I2C_H__
  20
  21 ///
  22 /// A 10-bit slave address is or'ed with the following value enabling the
  23 /// I2C protocol stack to address the duplicated address space between 0
  24 //  and 127 in 10-bit mode.
  25 ///
  26 #define I2C_ADDRESSING_10_BIT     0x80000000
  27
  28 ///
  29 /// I2C controller capabilities
  30 ///
  31 /// The EFI_I2C_CONTROLLER_CAPABILITIES specifies the capabilities of the
  32 /// I2C host controller.  The StructureSizeInBytes enables variations of
  33 /// this structure to be identified if there is need to extend this
  34 /// structure in the future.
  35 ///
  36 typedef struct {
  37   ///
  38   /// Length of this data structure in bytes
  39   ///
  40   UINT32 StructureSizeInBytes;
  41
  42   ///
  43   /// The maximum number of bytes the I2C host controller is able to
  44   /// receive from the I2C bus.
  45   ///
  46   UINT32 MaximumReceiveBytes;
  47
  48   ///
  49   /// The maximum number of bytes the I2C host controller is able to send
  50   /// on the I2C  bus.
  51   ///
  52   UINT32 MaximumTransmitBytes;
  53
  54   ///
  55   /// The maximum number of bytes in the I2C bus transaction.
  56   ///
  57   UINT32 MaximumTotalBytes;
  58 } EFI_I2C_CONTROLLER_CAPABILITIES;
  59
  60 ///
  61 /// I2C device description
  62 ///
  63 /// The EFI_I2C_ENUMERATE_PROTOCOL uses the EFI_I2C_DEVICE to describe
  64 /// the platform specific details associated with an I2C device.  This
  65 /// description is passed to the I2C bus driver during enumeration where
  66 /// it is made available to the third party I2C device driver via the
  67 /// EFI_I2C_IO_PROTOCOL.
  68 ///
  69 typedef struct {
  70   ///
  71   /// Unique value assigned by the silicon manufacture or the third
  72   /// party I2C driver writer for the I2C part.  This value logically
  73   /// combines both the manufacture name and the I2C part number into
  74   /// a single value specified as a GUID.
  75   ///
  76   CONST EFI_GUID *DeviceGuid;
  77
  78   ///
  79   /// Unique ID of the I2C part within the system
  80   ///
  81   UINT32 DeviceIndex;
  82
  83   ///
  84   /// Hardware revision - ACPI _HRV value.  See the Advanced
  85   /// Configuration and Power Interface Specification, Revision 5.0
  86   /// for the field format and the Plug and play support for I2C
  87   /// web-page for restriction on values.
  88   ///
  89   /// http://www.acpi.info/spec.htm
  90   /// http://msdn.microsoft.com/en-us/library/windows/hardware/jj131711(v=vs.85).aspx
  91   ///
  92   UINT32 HardwareRevision;
  93
  94   ///
  95   /// I2C bus configuration for the I2C device
  96   ///
  97   UINT32 I2cBusConfiguration;
  98
  99   ///
 100   /// Number of slave addresses for the I2C device.
 101   ///
 102   UINT32 SlaveAddressCount;
 103
 104   ///
 105   /// Pointer to the array of slave addresses for the I2C device.
 106   ///
 107   CONST UINT32 *SlaveAddressArray;
 108 } EFI_I2C_DEVICE;
 109
 110 ///
 111 /// Define the I2C flags
 112 ///
 113 /// I2C read operation when set
 114 #define I2C_FLAG_READ               0x00000001
 115
 116 ///
 117 /// Define the flags for SMBus operation
 118 ///
 119 /// The following flags are also present in only the first I2C operation
 120 /// and are ignored when present in other operations.  These flags
 121 /// describe a particular SMB transaction as shown in the following table.
 122 ///
 123
 124 /// SMBus operation
 125 #define I2C_FLAG_SMBUS_OPERATION    0x00010000
 126
 127 /// SMBus block operation
 128 ///   The flag I2C_FLAG_SMBUS_BLOCK causes the I2C master protocol to update
 129 ///   the LengthInBytes field of the operation in the request packet with
 130 ///   the actual number of bytes read or written.  These values are only
 131 ///   valid when the entire I2C transaction is successful.
 132 ///   This flag also changes the LengthInBytes meaning to be: A maximum
 133 ///   of LengthInBytes is to be read from the device.  The first byte
 134 ///   read contains the number of bytes remaining to be read, plus an
 135 ///   optional PEC value.
 136 #define I2C_FLAG_SMBUS_BLOCK        0x00020000
 137
 138 /// SMBus process call operation
 139 #define I2C_FLAG_SMBUS_PROCESS_CALL 0x00040000
 140
 141 /// SMBus use packet error code (PEC)
 142 ///   Note that the I2C master protocol may clear the I2C_FLAG_SMBUS_PEC bit
 143 ///   to indicate that the PEC value was checked by the hardware and is
 144 ///   not appended to the returned read data.
 145 ///
 146 #define I2C_FLAG_SMBUS_PEC          0x00080000
 147
 148 //----------------------------------------------------------------------
 149 ///
 150 /// QuickRead:          OperationCount=1,
 151 ///                     LengthInBytes=0,   Flags=I2C_FLAG_READ
 152 /// QuickWrite:         OperationCount=1,
 153 ///                     LengthInBytes=0,   Flags=0
 154 ///
 155 ///
 156 /// ReceiveByte:        OperationCount=1,
 157 ///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION
 158 ///                                            | I2C_FLAG_READ
 159 /// ReceiveByte+PEC:    OperationCount=1,
 160 ///                     LengthInBytes=2,   Flags=I2C_FLAG_SMBUS_OPERATION
 161 ///                                            | I2C_FLAG_READ
 162 ///                                            | I2C_FLAG_SMBUS_PEC
 163 ///
 164 ///
 165 /// SendByte:           OperationCount=1,
 166 ///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION
 167 /// SendByte+PEC:       OperationCount=1,
 168 ///                     LengthInBytes=2,   Flags=I2C_FLAG_SMBUS_OPERATION
 169 ///                                            | I2C_FLAG_SMBUS_PEC
 170 ///
 171 ///
 172 /// ReadDataByte:       OperationCount=2,
 173 ///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION
 174 ///                     LengthInBytes=1,   Flags=I2C_FLAG_READ
 175 /// ReadDataByte+PEC:   OperationCount=2,
 176 ///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION
 177 ///                                            | I2C_FLAG_SMBUS_PEC
 178 ///                     LengthInBytes=2,   Flags=I2C_FLAG_READ
 179 ///
 180 ///
 181 /// WriteDataByte:      OperationCount=1,
 182 ///                     LengthInBytes=2,   Flags=I2C_FLAG_SMBUS_OPERATION
 183 /// WriteDataByte+PEC:  OperationCount=1,
 184 ///                     LengthInBytes=3,   Flags=I2C_FLAG_SMBUS_OPERATION
 185 ///                                            | I2C_FLAG_SMBUS_PEC
 186 ///
 187 ///
 188 /// ReadDataWord:       OperationCount=2,
 189 ///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION
 190 ///                     LengthInBytes=2,   Flags=I2C_FLAG_READ
 191 /// ReadDataWord+PEC:   OperationCount=2,
 192 ///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION
 193 ///                                            | I2C_FLAG_SMBUS_PEC
 194 ///                     LengthInBytes=3,   Flags=I2C_FLAG_READ
 195 ///
 196 ///
 197 /// WriteDataWord:      OperationCount=1,
 198 ///                     LengthInBytes=3,   Flags=I2C_FLAG_SMBUS_OPERATION
 199 /// WriteDataWord+PEC:  OperationCount=1,
 200 ///                     LengthInBytes=4,   Flags=I2C_FLAG_SMBUS_OPERATION
 201 ///                                            | I2C_FLAG_SMBUS_PEC
 202 ///
 203 ///
 204 /// ReadBlock:          OperationCount=2,
 205 ///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION
 206 ///                                            | I2C_FLAG_SMBUS_BLOCK
 207 ///                     LengthInBytes=33,  Flags=I2C_FLAG_READ
 208 /// ReadBlock+PEC:      OperationCount=2,
 209 ///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION
 210 ///                                            | I2C_FLAG_SMBUS_BLOCK
 211 ///                                            | I2C_FLAG_SMBUS_PEC
 212 ///                     LengthInBytes=34,  Flags=I2C_FLAG_READ
 213 ///
 214 ///
 215 /// WriteBlock:         OperationCount=1,
 216 ///                     LengthInBytes=N+2, Flags=I2C_FLAG_SMBUS_OPERATION
 217 ///                                            | I2C_FLAG_SMBUS_BLOCK
 218 /// WriteBlock+PEC:     OperationCount=1,
 219 ///                     LengthInBytes=N+3, Flags=I2C_FLAG_SMBUS_OPERATION
 220 ///                                            | I2C_FLAG_SMBUS_BLOCK
 221 ///                                            | I2C_FLAG_SMBUS_PEC
 222 ///
 223 ///
 224 /// ProcessCall:        OperationCount=2,
 225 ///                     LengthInBytes=3,   Flags=I2C_FLAG_SMBUS_OPERATION
 226 ///                                            | I2C_FLAG_SMBUS_PROCESS_CALL
 227 ///                     LengthInBytes=2,   Flags=I2C_FLAG_READ
 228 /// ProcessCall+PEC:    OperationCount=2,
 229 ///                     LengthInBytes=3,   Flags=I2C_FLAG_SMBUS_OPERATION
 230 ///                                            | I2C_FLAG_SMBUS_PROCESS_CALL
 231 ///                                            | I2C_FLAG_SMBUS_PEC
 232 ///                     LengthInBytes=3,   Flags=I2C_FLAG_READ
 233 ///
 234 ///
 235 /// BlkProcessCall:     OperationCount=2,
 236 ///                     LengthInBytes=N+2, Flags=I2C_FLAG_SMBUS_OPERATION
 237 ///                                            | I2C_FLAG_SMBUS_PROCESS_CALL
 238 ///                                            | I2C_FLAG_SMBUS_BLOCK
 239 ///                     LengthInBytes=33,  Flags=I2C_FLAG_READ
 240 /// BlkProcessCall+PEC: OperationCount=2,
 241 ///                     LengthInBytes=N+2, Flags=I2C_FLAG_SMBUS_OPERATION
 242 ///                                            | I2C_FLAG_SMBUS_PROCESS_CALL
 243 ///                                            | I2C_FLAG_SMBUS_BLOCK
 244 ///                                            | I2C_FLAG_SMBUS_PEC
 245 ///                     LengthInBytes=34,  Flags=I2C_FLAG_READ
 246 ///
 247 //----------------------------------------------------------------------
 248
 249 ///
 250 /// I2C device operation
 251 ///
 252 /// The EFI_I2C_OPERATION describes a subset of an I2C transaction in which
 253 /// the I2C controller is either sending or receiving bytes from the bus.
 254 /// Some transactions will consist of a single operation while others will
 255 /// be two or more.
 256 ///
 257 /// Note: Some I2C controllers do not support read or write ping (address
 258 /// only) operation and will return EFI_UNSUPPORTED status when these
 259 /// operations are requested.
 260 ///
 261 /// Note: I2C controllers which do not support complex transactions requiring
 262 /// multiple repeated start bits return EFI_UNSUPPORTED without processing
 263 /// any of the transaction.
 264 ///
 265 typedef struct {
 266   ///
 267   /// Flags to qualify the I2C operation.
 268   ///
 269   UINT32 Flags;
 270
 271   ///
 272   /// Number of bytes to send to or receive from the I2C device.  A ping
 273   /// (address only byte/bytes)  is indicated by setting the LengthInBytes
 274   /// to zero.
 275   ///
 276   UINT32 LengthInBytes;
 277
 278   ///
 279   /// Pointer to a buffer containing the data to send or to receive from
 280   /// the I2C device.  The Buffer must be at least LengthInBytes in size.
 281   ///
 282   UINT8 *Buffer;
 283 } EFI_I2C_OPERATION;
 284
 285 ///
 286 /// I2C device request
 287 ///
 288 /// The EFI_I2C_REQUEST_PACKET describes a single I2C transaction.  The
 289 /// transaction starts with a start bit followed by the first operation
 290 /// in the operation array.  Subsequent operations are separated with
 291 /// repeated start bits and the last operation is followed by a stop bit
 292 /// which concludes the transaction.  Each operation is described by one
 293 /// of the elements in the Operation array.
 294 ///
 295 typedef struct {
 296   ///
 297   /// Number of elements in the operation array
 298   ///
 299   UINTN OperationCount;
 300
 301   ///
 302   /// Description of the I2C operation
 303   ///
 304   EFI_I2C_OPERATION Operation [1];
 305 } EFI_I2C_REQUEST_PACKET;
 306
 307 #endif  //  __PI_I2C_H__