MdePkg/Include/Pi/PiI2c.h

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