Vlv2TbltDevicePkg/Include/Protocol/I2cMasterMcg.h

   1 /*++
   2
   3   Copyright (c) 2004  - 2014, Intel Corporation. All rights reserved.<BR>
   4
   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
  14
  15   \section I2cDriverStack       I2C Driver Stack
  16
  17   The following is a representation of the I<sup>2</sup>C (I2C)
  18   driver stack and an I2C bus layout.
  19
  20   <code><pre>
  21               +-----------------+
  22               |   Application   |
  23               +-----------------+
  24                        |
  25                        | Third Party or UEFI
  26                        |
  27                        V
  28  +--------+   +-----------------+
  29  | Slave  |   |   Third Party   |
  30  | Driver |   |   I2C Device    |
  31  |        |   |     Driver      |
  32  +--------+   +-----------------+
  33       |                |
  34       |          BUS   |
  35       |                |
  36       |                V
  37       |       +-----------------+
  38       |       | I2C Bus Driver  |------------------.
  39       |       +-----------------+                  |
  40       |                |                           |
  41       |         HOST   |          BUS              |
  42       |                |          CONFIGURATION    |
  43 SLAVE |                V          MANAGEMENT       | ACPI
  44       |       +-----------------+                  |
  45       |       | I2C Host Driver |----------.       |
  46       |       +-----------------+          |       |
  47       |                |                   |       |
  48       |        MASTER  |                   V       V
  49       |                |               +-------=-------------+
  50       |                V               | I2C Platform Driver |
  51       |       +-----------------+      +---------------------+
  52       `------>| I2C Port Driver |               |      |
  53               +-----------------+               |      |
  54                        |                        |      |
  55             Software   |                        |      |
  56             --------------------------------------------------
  57             Hardware   |                        |      |
  58                        |                        |      |
  59                        V                        |      |
  60               +-----------------+               |      |
  61               | I2C Controller  |               |      |
  62               +-----------------+               |      |
  63                        |                        |      |
  64             -----------------------             |      |
  65             I2C Bus    |                        |      |
  66                        |    +------------+      |      |
  67                        +----| High speed |      |      |
  68                        |    | I2C device |      |      |
  69                        |    |    0x01    |      |      |
  70                        |    +------------+      |      |
  71                        |                        |      |
  72                   +---------+  0                |      |
  73                   | Switch  |<------------------`      |
  74                   +---------+  1                       |
  75                        |                               |
  76                        |    +------------+             |
  77                        +----| Fast speed |             |
  78                        |    | I2C device |             |
  79                        |    |    0x02    |             |
  80                        |    +------------+             |
  81                        |                               |
  82                 +-------------+                        |
  83                 | Multiplexer |<-----------------------`
  84                 +-------------+
  85                  0 |       | 1
  86                    |       |
  87                    |       |
  88                    |       |    +-------------+
  89                    |       +----| Third Party |
  90                    |       |    | I2C Device  |
  91                    |       |    |  0x03, 0x04 |
  92                    |       |    +-------------+
  93                    |       |
  94                    |
  95                    |            +-------------+
  96                    +------------| Third Party |
  97                    |            | I2C Device  |
  98                    |            |  0x03, 0x04 |
  99                    |            +-------------+
 100                    |
 101   </pre></code>
 102
 103   The platform hardware designer chooses the bus layout based upon
 104   the platform, I2C chip and software requirements.  The design uses
 105   switches to truncate the bus to enable higher speed operation for a
 106   subset of devices which are placed closer to the controller.  When the
 107   switch is on, the extended bus must operate at a lower speed.  The
 108   design uses multiplexer to create separate address spaces enabling
 109   the use of multiple devices which would otherwise have conflicting
 110   addresses. See the
 111   <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C
 112   Specification</a> for more details.
 113
 114   N.B. Some operating systems may prohibit the changing of switches
 115   and multiplexers in the I2C bus.  In this case the platform hardware
 116   and software designers must select a single I2C bus configuration
 117   consisting of constant input values for the switches and multiplexers.
 118   The platform software designer must then ensure that this I2C bus
 119   configuration is enabled prior to passing control to the operating
 120   system.
 121
 122   The platform hardware designer needs to provide the platform software
 123   designer the following data for each I2C bus:
 124
 125   1.  Which controller controls this bus
 126
 127   2.  A list of logic blocks contained in one or more I2C devices:
 128
 129       a.  I2C device which contains this logic block
 130
 131       b.  Logic block slave address
 132
 133       c.  Logic block name
 134
 135   3.  For each configuration of the switches and multiplexer
 136
 137       a.  What is the maximum speed of operation
 138
 139       b.  What devices are accessible
 140
 141   4.  The settings for the switches and multiplexers when control is
 142       given to the operating system.
 143
 144   \section ThirdPartyI2cDrivers   Third Party I2C Drivers
 145
 146   This layer is I2C chip specific but platform and host controller
 147   independent.
 148
 149   Third party I2C driver writers, typically silicon vendors, need
 150   to provide:
 151
 152   1.  The device path node data that is used to select their
 153       driver.
 154
 155   2.  The order for the blocks of logic that get referenced
 156       by the entries in the slave address array.
 157
 158   3.  The hardware version of the I2C device, this value is passed
 159       to the third party I2C driver to enable it to perform work
 160       arounds for the specific hardware version.  This value should
 161       match the value in the ACPI _HRV tag.
 162
 163   The third party I2C driver uses relative addressing to abstract
 164   the platform specific details of the I2C device.  Using an
 165   example I2C device containing an accelerometer and a magnetometer
 166   which consumes two slave addresses, one for each logic block.  The
 167   third party I2C driver writer may choose to write two drivers, one
 168   for each block of logic, in which case each driver refers to the
 169   single I2C slave address using the relative value of zero (0).
 170   However if the third party I2C driver writer chooses to write a
 171   single driver which consumes multiple slave addresses then the
 172   third party I2C driver writer needs to convey the order of the
 173   I2C slave address entries in the slave address array to the
 174   platform software designer.  For the example:
 175
 176       0: Accelerometer
 177
 178       1: Magnetometer
 179
 180   The platform hardware designer picks the actual slave addresses
 181   from the I2C device's data sheet and provides this information
 182   to the platform software designer.  The platform software designer
 183   then places the slave addresses into the slave address array in the
 184   order specified by the third party I2C driver writer.  The third
 185   party driver I2C writer then indirectly references this array by
 186   specifying the index value as the relative slave address.  The
 187   relative value always starts at zero (0) and its maximum value is
 188   the number of entries in slave address array minus one.
 189
 190   The slave address is specified as a 32-bit integer to allow room
 191   for future slave address expansion.  Only the port driver knows
 192   the maximum slave address value.  All other drivers and
 193   applications must look for the EFI_NOT_FOUND status for the
 194   indication that the maximum slave address was exceeded.
 195
 196   \section I2cBusDriver         I2C Bus Driver
 197
 198   This layer is platform, host controller, and I2C chip independent.
 199
 200   The I2C bus driver creates a handle for each of the I2C devices
 201   described within the platform driver.  The I2C controller's device
 202   path is extended with the device path node provided by the platform
 203   driver and attached to the handle.  The third party I2C device driver
 204   uses the device path to determine if it may connect.  For ACPI nodes,
 205   the third party I2C driver should use the CID or CidString value.
 206
 207   The I2C bus driver validates the relative address for the I2C device
 208   and then converts the relative value to an actual I2C slave address.
 209   The request is then passed to the I2C host driver.
 210
 211   \section I2cHostDriver        I2C Host Driver
 212
 213   This layer is platform, host controller, and I2C chip independent.
 214
 215   N.B. For proper operation of the I2C bus, only the I2C bus driver
 216   and the I2C test application should connect to the I2C host driver
 217   via the EFI_I2C_HOST_DRIVER_PROTOCOL.
 218
 219   The I2C host driver may access any device on the I2C bus.  The I2C
 220   host driver has the following responsibilities:
 221
 222   1.  Limits the number of requests to the I2C port driver to one.
 223       The I2C host driver holds on to additional requests until the
 224       I2C port driver is available to process the request.  The I2C
 225       requests are issued in FIFO order to the I2C port driver.
 226
 227   2.  Enable the proper I2C bus configuration before starting the
 228       I2C request on the I2C port driver
 229
 230   I2C devices are addressed as the tuple: BusConfiguration:SlaveAddress.
 231   I2C bus configuration zero (0) is the portion of the I2C bus that
 232   connects to the host controller.  The bus configuration specifies
 233   the control values for the switches and multiplexers in the I2C bus.
 234   After the switches and multiplexers are properly configured, the I2C
 235   controller uses the slave address to access the requested I2C device.
 236
 237   Since the I2C driver stack supports asynchronous operations this
 238   layer maintains a queue of I2C requests until the I2C controller
 239   is available them.  When a request reaches the head of the queue
 240   the necessary bus configuration is enabled and then the request
 241   is sent to the I2C port driver.
 242
 243   \section I2cPortDriver        I2C Port Driver
 244
 245   This layer is I2C controller specific but platform independent.
 246
 247   This layer manipulates the I2C controller to perform an operation
 248   on the I2C bus.  This layer does not configure the I2C bus so it
 249   is up to the caller to ensure that the I2C bus is in the proper
 250   configuration before issuing the I2C request.
 251
 252   This layer typically needs the following information:
 253
 254   1.  Host controller address
 255   2.  Controller's input clock frequency
 256
 257   Depending upon the I2C controller, more data may be necessary.
 258   This layer may use any method to get these values: hard coded
 259   values, PCD values, or may choose to communicate with the platform
 260   layer using an undefined mechanism to get these values.
 261
 262   If the I2C port driver requires data from the platform driver then
 263   the I2C port driver writer needs to provide the platform interface
 264   details to the platform software designer.
 265
 266   \section I2cPlatformDriver    I2C Platform Driver
 267
 268   When enabling access to I2C devices within UEFI, this driver
 269   installs the EFI_I2C_ACPI_PROTOCOL to provide the I2C device
 270   descriptions to the I2C bus driver using the EFI_I2C_DEVICE
 271   structure.  These descriptions include the bus configuration
 272   number required for the I2C device, the slave address array
 273   and the device path.
 274
 275   The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol is optional.
 276   This protocol needs to be specified under the following conditions:
 277
 278   1.  The I2C bus must operate at a frequency greater than 100 KHz
 279   2.  The I2C bus contains switches or multiplexers.
 280
 281   The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol enables the
 282   I2C host driver to call into the I2C platform driver to enable
 283   a specific I2C bus configuration and set its maximum clock speed.
 284
 285   The platform software designer collects the data requirements
 286   from third party I2C driver writers, the I2C controller
 287   driver writer, the EFI_I2C_ACPI_PROTOCOL and
 288   EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL.  The platform
 289   software designer gets the necessary data from the platform
 290   hardware designer.  The platform software designer then builds
 291   the data structures and implements the necessary routines to
 292   construct the I2C platform driver.
 293
 294   \section I2cSwitches          Switches and Multiplexers
 295
 296   There are some I2C switches and I2C multiplexers where the control
 297   is done via I2C commands.  When the control inputs come via the
 298   same I2C bus that is being configured then the platform driver must
 299   use the EFI_I2C_MASTER_PROTOCOL that is passed to the platform
 300   driver.  While the I2C host driver makes the call to the I2C
 301   platform driver to configure the bus, the host driver keeps the
 302   I2C port driver idle, to allow the I2C platform driver preform
 303   the necessary configuration operations.
 304
 305   If however the configuration control is done via and I2C device
 306   connected to a different I2C bus (host controller), then it is
 307   possible for the platform software designer may choose between
 308   the following:
 309
 310   1.  Call into a third party I2C driver to manipulate the I2C
 311       bus control device.
 312   2.  Call into the EFI_I2C_BUS_PROTOCOL if no third party I2C
 313       driver exists for the I2C bus control device
 314   3.  Call into the EFI_I2C_HOST_PROTOCOL if the platform does
 315       not expose the I2C bus control device.
 316
 317 **/
 318
 319 #ifndef __I2C_MASTER_H__
 320 #define __I2C_MASTER_H__
 321
 322 /**
 323   Declare the forward references
 324
 325 **/
 326 typedef struct _EFI_I2C_MASTER_PROTOCOL   EFI_I2C_MASTER_PROTOCOL;  ///<  I2C master protocol
 327
 328 ///
 329 /// I2C device operation
 330 ///
 331 /// This structure provides the information necessary for an operation
 332 /// on an I2C device
 333 ///
 334 typedef struct {
 335   ///
 336   /// Number of bytes to send to the I2C device
 337   ///
 338   UINT32 WriteBytes;
 339
 340   ///
 341   /// Number of bytes to read, set to zero for write only operations
 342   ///
 343   UINT32 ReadBytes;
 344
 345   ///
 346   /// Address of the buffer containing the data to send to the I2C device.
 347   /// The WriteBuffer must be at least WriteBytes in length.
 348   ///
 349   UINT8 *WriteBuffer;
 350
 351   ///
 352   /// Address of the buffer to receive data from the I2C device. Use NULL
 353   /// for write only operations.  The ReadBuffer must be at least ReadBytes
 354   /// in length.
 355   ///
 356   UINT8 *ReadBuffer;
 357
 358   ///
 359   /// Timeout for the I2C operation in 100 ns units
 360   ///
 361   UINT32 Timeout;
 362 } EFI_I2C_REQUEST_PACKET;
 363
 364
 365 /**
 366   Set the I2C controller bus clock frequency.
 367
 368   This routine must be called at or below TPL_NOTIFY.
 369
 370   The software and controller do a best case effort of using the specified
 371   frequency for the I2C bus.  If the frequency does not match exactly then
 372   the controller will use a slightly lower frequency to avoid
 373   exceeding the operating conditions for any of the I2C devices on the bus.
 374   For example if 400 KHz was specified and the controller's divide network
 375   only supports 402 KHz or 398 KHz then the controller would be set to 398
 376   KHz.  However if the desired frequency is 400 KHz and the controller only
 377   supports 1 MHz and 100 KHz then this routine would return EFI_UNSUPPORTED.
 378
 379   @param[in] This           Address of an EFI_I2C_MASTER_PROTOCOL
 380                             structure
 381   @param[in] BusClockHertz  New I2C bus clock frequency in Hertz
 382
 383   @retval EFI_SUCCESS       The bus frequency was set successfully.
 384   @retval EFI_UNSUPPORTED   The controller does not support this frequency.
 385
 386 **/
 387 typedef
 388 EFI_STATUS
 389 (EFIAPI *EFI_I2C_MASTER_BUS_FREQUENCY_SET) (
 390   IN CONST EFI_I2C_MASTER_PROTOCOL *This,
 391   IN UINTN BusClockHertz
 392   );
 393
 394 /**
 395   Reset the I2C controller and configure it for use
 396
 397   This routine must be called at or below TPL_NOTIFY.
 398
 399   The I2C controller is reset and the I2C bus frequency is set to 100 KHz.
 400
 401   @param[in]     This       Address of an EFI_I2C_MASTER_PROTOCOL
 402                             structure
 403
 404 **/
 405 typedef
 406 VOID
 407 (EFIAPI *EFI_I2C_MASTER_RESET) (
 408   IN CONST EFI_I2C_MASTER_PROTOCOL *This
 409   );
 410
 411 /**
 412   Start an I2C operation on the host controller
 413
 414   This routine must be called at or below TPL_NOTIFY.  For synchronous
 415   requests this routine must be called at or below TPL_CALLBACK.
 416
 417   This function initiates an I2C operation on the controller.
 418
 419   The operation is performed by selecting the I2C device with its slave
 420   address and then sending all write data to the I2C device.  If read data
 421   is requested, a restart is sent followed by the slave address and then
 422   the read data is clocked into the I2C controller and placed in the read
 423   buffer.  When the operation completes, the status value is returned and
 424   then the event is set.
 425
 426   N.B. The typical consumer of this API is the I2C host driver.
 427   Extreme care must be taken by other consumers of this API to
 428   prevent confusing the third party I2C drivers due to a state
 429   change at the I2C device which the third party I2C drivers did
 430   not initiate.  I2C platform drivers may use this API within
 431   these guidelines.
 432
 433   N.B. This API supports only one operation, no queuing support
 434   exists at this layer.  This API assumes that the I2C bus is in
 435   the correct configuration for the I2C request.
 436
 437   @param[in] This           Address of an EFI_I2C_MASTER_PROTOCOL
 438                             structure
 439   @param[in] SlaveAddress   Address of the device on the I2C bus.
 440   @param[in] Event          Event to set for asynchronous operations,
 441                             NULL for synchronous operations
 442   @param[in] RequestPacket  Address of an EFI_I2C_REQUEST_PACKET
 443                             structure describing the I2C operation
 444   @param[out] I2cStatus     Optional buffer to receive the I2C operation
 445                             completion status
 446
 447   @retval EFI_SUCCESS           The operation completed successfully.
 448   @retval EFI_ABORTED           The request did not complete because the driver
 449                                 was shutdown.
 450   @retval EFI_BAD_BUFFER_SIZE   The WriteBytes or ReadBytes buffer size is too large.
 451   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the operation.
 452                                 This could indicate the slave device is not present.
 453   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
 454   @retval EFI_INVALID_PARAMETER TPL is too high
 455   @retval EFI_NOT_FOUND         SlaveAddress exceeds maximum address
 456   @retval EFI_NOT_READY         I2C bus is busy or operation pending, wait for
 457                                 the event and then read status pointed to by
 458                                 the request packet.
 459   @retval EFI_NO_RESPONSE       The I2C device is not responding to the
 460                                 slave address.  EFI_DEVICE_ERROR may also be
 461                                 returned if the controller cannot distinguish
 462                                 when the NACK occurred.
 463   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C operation
 464   @retval EFI_TIMEOUT           The transaction did not complete within an internally
 465                                 specified timeout period.
 466
 467 **/
 468 typedef
 469 EFI_STATUS
 470 (EFIAPI *EFI_I2C_MASTER_START_REQUEST) (
 471   IN CONST EFI_I2C_MASTER_PROTOCOL *This,
 472   IN UINTN SlaveAddress,
 473   IN EFI_EVENT Event OPTIONAL,
 474   IN CONST EFI_I2C_REQUEST_PACKET *RequestPacket,
 475   OUT EFI_STATUS *I2cStatus OPTIONAL
 476   );
 477
 478 ///
 479 /// I2C master mode protocol
 480 ///
 481 /// This protocol manipulates the I2C host controller to perform transactions as a
 482 /// master on the I2C bus using the current state of any switches or multiplexers
 483 /// in the I2C bus.
 484 ///
 485 struct _EFI_I2C_MASTER_PROTOCOL {
 486   ///
 487   /// Set the clock frequency for the I2C bus
 488   ///
 489   EFI_I2C_MASTER_BUS_FREQUENCY_SET BusFrequencySet;
 490
 491   ///
 492   /// Reset the I2C host controller
 493   ///
 494   EFI_I2C_MASTER_RESET Reset;
 495
 496   ///
 497   /// Start an I2C transaction in master mode on the host controller
 498   ///
 499   EFI_I2C_MASTER_START_REQUEST StartRequest;
 500
 501   ///
 502   /// The maximum number of bytes the I2C host controller
 503   /// is able to receive from the I2C bus.
 504   ///
 505   UINT32 MaximumReceiveBytes;
 506
 507   ///
 508   /// The maximum number of bytes the I2C host controller
 509   /// is able to send on the I2C bus.
 510   ///
 511   UINT32 MaximumTransmitBytes;
 512
 513   ///
 514   /// The maximum number of bytes in the I2C bus transaction.
 515   ///
 516   UINT32 MaximumTotalBytes;
 517 };
 518
 519 ///
 520 /// GUID for the EFI_I2C_MASTER_PROTOCOL
 521 ///
 522 extern EFI_GUID gEfiI2cMasterProtocolGuid;
 523
 524 #endif  //  __I2C_MASTER_H__