Tools/Source/TianoTools/Include/Protocol/Smbus.h

   1 /** @file
   2   This file declares the EFI SMBus Host Controller protocol
   3
   4   Copyright (c) 2006, Intel Corporation
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  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   Module Name:  Smbus.h
  14
  15   @par Revision Reference:
  16   This protocol is defined in Framework of EFI SMBus Host Controller Specification
  17   Version 0.9
  18
  19 **/
  20
  21 #ifndef _EFI_SMBUS_H
  22 #define _EFI_SMBUS_H
  23
  24 #define EFI_SMBUS_HC_PROTOCOL_GUID \
  25   { \
  26     0xe49d33ed, 0x513d, 0x4634, {0xb6, 0x98, 0x6f, 0x55, 0xaa, 0x75, 0x1c, 0x1b } \
  27   }
  28
  29 typedef struct _EFI_SMBUS_HC_PROTOCOL EFI_SMBUS_HC_PROTOCOL;
  30
  31 /**
  32   Executes an SMBus operation to an SMBus controller.
  33
  34   @param  This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
  35
  36   @param  SlaveAddress The SMBus slave address of the device with which to communicate.
  37
  38   @param  Command This command is transmitted by the SMBus host
  39   controller to the SMBus slave device and the interpretation is
  40   SMBus slave device specific.
  41
  42   @param  Operation Signifies which particular SMBus hardware protocol
  43   instance that it will use to execute the SMBus transactions.
  44
  45   @param  PecCheck Defines if Packet Error Code (PEC) checking is required
  46   for this operation.
  47
  48   @param  Length Signifies the number of bytes that this operation will do.
  49
  50   @param  Buffer Contains the value of data to execute to the SMBus slave device.
  51
  52   @retval EFI_SUCCESS The last data that was returned from the access
  53   matched the poll exit criteria.
  54
  55   @retval EFI_CRC_ERROR The checksum is not correct (PEC is incorrect)
  56
  57   @retval EFI_TIMEOUT Timeout expired before the operation was completed.
  58   Timeout is determined by the SMBus host controller device.
  59
  60   @retval EFI_OUT_OF_RESOURCES The request could not be completed
  61   due to a lack of resources.
  62
  63   @retval EFI_DEVICE_ERROR The request was not completed because
  64   a failure reflected in the Host Status Register bit.
  65
  66   @retval EFI_INVALID_PARAMETER Operation is not defined in EFI_SMBUS_OPERATION.
  67   Or Length/Buffer is NULL for operations except for EfiSmbusQuickRead and
  68   EfiSmbusQuickWrite. Length is outside the range of valid values.
  69
  70   @retval EFI_UNSUPPORTED The SMBus operation or PEC is not supported.
  71
  72   @retval EFI_BUFFER_TOO_SMALL Buffer is not sufficient for this operation.
  73
  74 **/
  75 typedef
  76 EFI_STATUS
  77 (EFIAPI *EFI_SMBUS_HC_EXECUTE_OPERATION) (
  78   IN EFI_SMBUS_HC_PROTOCOL              *This,
  79   IN      EFI_SMBUS_DEVICE_ADDRESS      SlaveAddress,
  80   IN      EFI_SMBUS_DEVICE_COMMAND      Command,
  81   IN      EFI_SMBUS_OPERATION           Operation,
  82   IN      BOOLEAN                       PecCheck,
  83   IN OUT  UINTN                         *Length,
  84   IN OUT  VOID                          *Buffer
  85   );
  86
  87 typedef struct {
  88   UINT32  VendorSpecificId;
  89   UINT16  SubsystemDeviceId;
  90   UINT16  SubsystemVendorId;
  91   UINT16  Interface;
  92   UINT16  DeviceId;
  93   UINT16  VendorId;
  94   UINT8   VendorRevision;
  95   UINT8   DeviceCapabilities;
  96 } EFI_SMBUS_UDID;
  97
  98 /**
  99   CallBack function can be registered in EFI_SMBUS_HC_PROTOCOL_NOTIFY.
 100
 101   @param  SlaveAddress The SMBUS hardware address to which the SMBUS
 102   device is preassigned or allocated.
 103
 104   @param  Data Data of the SMBus host notify command that
 105   the caller wants to be called.
 106
 107   @return Status Code
 108
 109 **/
 110 typedef
 111 EFI_STATUS
 112 (EFIAPI *EFI_SMBUS_NOTIFY_FUNCTION) (
 113   IN      EFI_SMBUS_DEVICE_ADDRESS      SlaveAddress,
 114   IN      UINTN                         Data
 115   );
 116
 117 /**
 118   Sets the SMBus slave device addresses for the device with a given unique ID
 119   or enumerates the entire bus.
 120
 121   @param  This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 122
 123   @param  ArpAll A Boolean expression that indicates if the host drivers need
 124   to enumerate all the devices or enumerate only the device that is identified
 125   by SmbusUdid. If ArpAll is TRUE, SmbusUdid and SlaveAddress are optional.
 126   If ArpAll is FALSE, ArpDevice will enumerate SmbusUdid and the address
 127   will be at SlaveAddress.
 128
 129   @param  SmbusUdid The Unique Device Identifier (UDID) that is associated
 130   with this device.
 131
 132   @param  SlaveAddress The SMBus slave address that is associated with an SMBus UDID.
 133
 134   @retval EFI_SUCCESS The SMBus slave device address was set.
 135
 136   @retval EFI_INVALID_PARAMETER SlaveAddress is NULL.
 137
 138   @retval EFI_OUT_OF_RESOURCES The request could not be completed
 139   due to a lack of resources.
 140
 141   @retval EFI_TIMEOUT The SMBus slave device did not respond.
 142
 143   @retval EFI_DEVICE_ERROR The request was not completed because the transaction failed.
 144
 145 **/
 146 typedef
 147 EFI_STATUS
 148 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE) (
 149   IN EFI_SMBUS_HC_PROTOCOL              *This,
 150   IN      BOOLEAN                       ArpAll,
 151   IN      EFI_SMBUS_UDID                *SmbusUdid, OPTIONAL
 152   IN OUT  EFI_SMBUS_DEVICE_ADDRESS      *SlaveAddress OPTIONAL
 153   );
 154
 155 typedef struct {
 156   EFI_SMBUS_DEVICE_ADDRESS  SmbusDeviceAddress;
 157   EFI_SMBUS_UDID            SmbusDeviceUdid;
 158 } EFI_SMBUS_DEVICE_MAP;
 159
 160 /**
 161   The GetArpMap() function returns the mapping of all the SMBus devices
 162   that are enumerated by the SMBus host driver.
 163
 164   @param  This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 165
 166   @param  Length Size of the buffer that contains the SMBus device map.
 167
 168   @param  SmbusDeviceMap The pointer to the device map as enumerated
 169   by the SMBus controller driver.
 170
 171   @retval EFI_SUCCESS The device map was returned correctly in the buffer.
 172
 173 **/
 174 typedef
 175 EFI_STATUS
 176 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP) (
 177   IN EFI_SMBUS_HC_PROTOCOL              *This,
 178   IN OUT  UINTN                         *Length,
 179   IN OUT  EFI_SMBUS_DEVICE_MAP          **SmbusDeviceMap
 180   );
 181
 182 /**
 183   The Notify() function registers all the callback functions to allow the
 184   bus driver to call these functions when the SlaveAddress/Data pair happens.
 185
 186   @param  This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 187
 188   @param  SlaveAddress Address that the host controller detects as
 189   sending a message and calls all the registered functions.
 190
 191   @param  Data Data that the host controller detects as sending a message
 192   and calls all the registered functions.
 193
 194   @param  NotifyFunction The function to call when the bus driver
 195   detects the SlaveAddress and Data pair.
 196
 197   @retval EFI_SUCCESS NotifyFunction was registered.
 198
 199 **/
 200 typedef
 201 EFI_STATUS
 202 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_NOTIFY) (
 203   IN EFI_SMBUS_HC_PROTOCOL              *This,
 204   IN      EFI_SMBUS_DEVICE_ADDRESS      SlaveAddress,
 205   IN      UINTN                         Data,
 206   IN      EFI_SMBUS_NOTIFY_FUNCTION     NotifyFunction
 207   );
 208
 209 /**
 210   @par Protocol Description:
 211   Provides basic SMBus host controller management and basic data
 212   transactions over the SMBus.
 213
 214   @param Execute
 215   Executes the SMBus operation to an SMBus slave device.
 216
 217   @param ArpDevice
 218   Allows an SMBus 2.0 device(s) to be Address Resolution Protocol (ARP)
 219
 220   @param GetArpMap
 221   Allows a driver to retrieve the address that was allocated by the SMBus
 222   host controller during enumeration/ARP.
 223
 224   @param Notify
 225   Allows a driver to register for a callback to the SMBus host
 226   controller driver when the bus issues a notification to the bus controller driver.
 227
 228 **/
 229 struct _EFI_SMBUS_HC_PROTOCOL {
 230   EFI_SMBUS_HC_EXECUTE_OPERATION    Execute;
 231   EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE  ArpDevice;
 232   EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP GetArpMap;
 233   EFI_SMBUS_HC_PROTOCOL_NOTIFY      Notify;
 234 };
 235
 236 extern EFI_GUID gEfiSmbusProtocolGuid;
 237 #endif