MdePkg/Include/Protocol/I2cIo.h

   1 /** @file
   2   I2C I/O Protocol as defined in the PI 1.3 specification.
   3
   4   The EFI I2C I/O protocol enables the user to manipulate a single
   5   I2C device independent of the host controller and I2C design.
   6
   7   Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
   8   This program and the accompanying materials
   9   are licensed and made available under the terms and conditions of the BSD License
  10   which accompanies this distribution.  The full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16   @par Revision Reference:
  17   This protocol is from PI Version 1.3.
  18
  19 **/
  20
  21 #ifndef __I2C_IO_H__
  22 #define __I2C_IO_H__
  23
  24 #include <Pi/PiI2c.h>
  25
  26 #define EFI_I2C_IO_PROTOCOL_GUID { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }}
  27
  28 ///
  29 /// I2C I/O protocol
  30 ///
  31 /// The I2C IO protocol enables access to a specific device on the I2C
  32 /// bus.
  33 ///
  34 /// Each I2C device is identified uniquely in the system by the tuple
  35 /// DeviceGuid:DeviceIndex.  The DeviceGuid represents the manufacture
  36 /// and part number and is provided by the silicon vendor or the third
  37 /// party I2C device driver writer.  The DeviceIndex identifies the part
  38 /// within the system by using a unique number and is created by the
  39 /// board designer or the writer of the EFI_I2C_ENUMERATE_PROTOCOL.
  40 ///
  41 /// I2C slave addressing is abstracted to validate addresses and limit
  42 /// operation to the specified I2C device.  The third party providing
  43 /// the I2C device support provides an ordered list of slave addresses
  44 /// for the I2C device required to implement the EFI_I2C_ENUMERATE_PROTOCOL.
  45 /// The order of the list must be preserved.
  46 ///
  47 typedef struct _EFI_I2C_IO_PROTOCOL  EFI_I2C_IO_PROTOCOL;
  48
  49
  50 /**
  51   Queue an I2C transaction for execution on the I2C device.
  52
  53   This routine must be called at or below TPL_NOTIFY.  For synchronous
  54   requests this routine must be called at or below TPL_CALLBACK.
  55
  56   This routine queues an I2C transaction to the I2C controller for
  57   execution on the I2C bus.
  58
  59   When Event is NULL, QueueRequest() operates synchronously and returns
  60   the I2C completion status as its return value.
  61
  62   When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
  63   indicating that the asynchronous I2C transaction was queued.  The values
  64   above are returned in the buffer pointed to by I2cStatus upon the
  65   completion of the I2C transaction when I2cStatus is not NULL.
  66
  67   The upper layer driver writer provides the following to the platform
  68   vendor:
  69
  70   1.  Vendor specific GUID for the I2C part
  71   2.  Guidance on proper construction of the slave address array when the
  72       I2C device uses more than one slave address.  The I2C bus protocol
  73       uses the SlaveAddressIndex to perform relative to physical address
  74       translation to access the blocks of hardware within the I2C device.
  75
  76   @param[in] This               Pointer to an EFI_I2C_IO_PROTOCOL structure.
  77   @param[in] SlaveAddressIndex  Index value into an array of slave addresses
  78                                 for the I2C device.  The values in the array
  79                                 are specified by the board designer, with the
  80                                 third party I2C device driver writer providing
  81                                 the slave address order.
  82
  83                                 For devices that have a single slave address,
  84                                 this value must be zero.  If the I2C device
  85                                 uses more than one slave address then the
  86                                 third party (upper level) I2C driver writer
  87                                 needs to specify the order of entries in the
  88                                 slave address array.
  89
  90                                 \ref ThirdPartyI2cDrivers "Third Party I2C
  91                                 Drivers" section in I2cMaster.h.
  92   @param[in] Event              Event to signal for asynchronous transactions,
  93                                 NULL for synchronous transactions
  94   @param[in] RequestPacket      Pointer to an EFI_I2C_REQUEST_PACKET structure
  95                                 describing the I2C transaction
  96   @param[out] I2cStatus         Optional buffer to receive the I2C transaction
  97                                 completion status
  98
  99   @retval EFI_SUCCESS           The asynchronous transaction was successfully
 100                                 queued when Event is not NULL.
 101   @retval EFI_SUCCESS           The transaction completed successfully when
 102                                 Event is NULL.
 103   @retval EFI_ABORTED           The request did not complete because the driver
 104                                 binding Stop() routine was called.
 105   @retval EFI_BAD_BUFFER_SIZE   The RequestPacket->LengthInBytes value is too
 106                                 large.
 107   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the
 108                                 transaction.
 109   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
 110   @retval EFI_NOT_FOUND         Reserved bit set in the SlaveAddress parameter
 111   @retval EFI_NO_MAPPING        The EFI_I2C_HOST_PROTOCOL could not set the
 112                                 bus configuration required to access this I2C
 113                                 device.
 114   @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave
 115                                 address selected by SlaveAddressIndex.
 116                                 EFI_DEVICE_ERROR will be returned if the
 117                                 controller cannot distinguish when the NACK
 118                                 occurred.
 119   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C transaction
 120   @retval EFI_UNSUPPORTED       The controller does not support the requested
 121                                 transaction.
 122
 123 **/
 124 typedef
 125 EFI_STATUS
 126 (EFIAPI *EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST) (
 127   IN CONST EFI_I2C_IO_PROTOCOL  *This,
 128   IN UINTN                      SlaveAddressIndex,
 129   IN EFI_EVENT                  Event      OPTIONAL,
 130   IN EFI_I2C_REQUEST_PACKET     *RequestPacket,
 131   OUT EFI_STATUS                *I2cStatus OPTIONAL
 132   );
 133
 134 ///
 135 /// I2C I/O protocol
 136 ///
 137 struct _EFI_I2C_IO_PROTOCOL {
 138   ///
 139   /// Queue an I2C transaction for execution on the I2C device.
 140   ///
 141   EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST         QueueRequest;
 142
 143   ///
 144   /// Unique value assigned by the silicon manufacture or the third
 145   /// party I2C driver writer for the I2C part.  This value logically
 146   /// combines both the manufacture name and the I2C part number into
 147   /// a single value specified as a GUID.
 148   ///
 149   CONST EFI_GUID                            *DeviceGuid;
 150
 151   ///
 152   /// Unique ID of the I2C part within the system
 153   ///
 154   UINT32                                    DeviceIndex;
 155
 156   ///
 157   /// Hardware revision - ACPI _HRV value.  See the Advanced Configuration
 158   /// and Power Interface Specification, Revision 5.0  for the field format
 159   /// and the Plug and play support for I2C web-page for restriction on values.
 160   ///
 161   UINT32                                    HardwareRevision;
 162
 163   ///
 164   /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing
 165   /// the capabilities of the I2C host controller.
 166   ///
 167   CONST EFI_I2C_CONTROLLER_CAPABILITIES     *I2cControllerCapabilities;
 168 };
 169
 170 ///
 171 /// Reference to variable defined in the .DEC file
 172 ///
 173 extern EFI_GUID gEfiI2cIoProtocolGuid;
 174
 175 #endif  //  __I2C_IO_H__