MdePkg/Include/Protocol/SmbusHc.h

   1 /** @file
   2   The file provides basic SMBus host controller management
   3   and basic data transactions over the SMBus.
   4
   5   Copyright (c) 2006 - 2008, Intel Corporation
   6   All rights reserved. This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14   @par Revision Reference: PI
  15   Version 1.00.
  16
  17 **/
  18
  19 #ifndef __SMBUS_HC_H__
  20 #define __SMBUS_HC_H__
  21
  22 #include <Ppi/Smbus2.h>
  23
  24 #define EFI_SMBUS_HC_PROTOCOL_GUID \
  25   {0xe49d33ed, 0x513d, 0x4634, { 0xb6, 0x98, 0x6f, 0x55, 0xaa, 0x75, 0x1c, 0x1b} }
  26
  27 typedef struct _EFI_SMBUS_HC_PROTOCOL EFI_SMBUS_HC_PROTOCOL;
  28
  29 /**
  30
  31   The Execute() function provides a standard way to execute an
  32   operation as defined in the System Management Bus (SMBus)
  33   Specification. The resulting transaction will be either that
  34   the SMBus slave devices accept this transaction or that this
  35   function returns with error. Status Codes Returned
  36
  37   @param This     A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
  38                   SlaveAddress The SMBus slave address of the device
  39                   with which to communicate. Type
  40                   EFI_SMBUS_DEVICE_ADDRESS is defined in
  41                   EFI_PEI_SMBUS_PPI.Execute() in the Platform
  42                   Initialization SMBus PPI Specification.
  43
  44   @param Command  This command is transmitted by the SMBus host
  45                   controller to the SMBus slave device and the
  46                   interpretation is SMBus slave device specific.
  47                   It can mean the offset to a list of functions
  48                   inside an SMBus slave device. Not all
  49                   operations or slave devices support this
  50                   command's registers. Type
  51                   EFI_SMBUS_DEVICE_COMMAND is defined in
  52                   EFI_PEI_SMBUS_PPI.Execute() in the Platform
  53                   Initialization SMBus PPI Specification.
  54                   Operation Signifies which particular SMBus
  55                   hardware protocol instance that it will use to
  56                   execute the SMBus transactions. This SMBus
  57                   hardware protocol is defined by the SMBus
  58                   Specification and is not related to PI
  59                   Architecture. Type EFI_SMBUS_OPERATION is
  60                   defined in EFI_PEI_SMBUS_PPI.Execute() in the
  61                   Platform Initialization SMBus PPI
  62                   Specification.
  63
  64   @param PecCheck Defines if Packet Error Code (PEC) checking
  65                   is required for this operation. SMBus Host
  66                   Controller Code Definitions Version 1.0
  67                   August 21, 2006 13 Length Signifies the
  68                   number of bytes that this operation will do.
  69                   The maximum number of bytes can be revision
  70                   specific and operation specific. This field
  71                   will contain the actual number of bytes that
  72                   are executed for this operation. Not all
  73                   operations require this argument.
  74
  75   @param Buffer   Contains the value of data to execute to the
  76                   SMBus slave device. Not all operations require
  77                   this argument. The length of this buffer is
  78                   identified by Length.
  79
  80
  81   @retval EFI_SUCCESS           The last data that was returned from the
  82                                 access matched the poll exit criteria.
  83
  84   @retval EFI_CRC_ERROR         Checksum is not correct (PEC is incorrect).
  85
  86   @retval EFI_TIMEOUT           Timeout expired before the operation was
  87                                 completed. Timeout is determined by the
  88                                 SMBus host controller device.
  89
  90   @retval EFI_OUT_OF_RESOURCES  The request could not be
  91                                 completed due to a lack of
  92                                 resources.
  93
  94   @retval EFI_DEVICE_ERROR      The request was not completed
  95                                 because a failure that was reflected
  96                                 in the Host Status Register bit.
  97                                 Device errors are a result of a
  98                                 transaction collision, illegal
  99                                 command field, unclaimed cycle (host
 100                                 initiated), or bus errors
 101                                 (collisions).
 102
 103   @retval EFI_INVALID_PARAMETER Operation is not defined in
 104                                 EFI_SMBUS_OPERATION.
 105
 106   @retval EFI_INVALID_PARAMETER Length/Buffer is NULL for
 107                                 operations except for
 108                                 EfiSmbusQuickRead and
 109                                 EfiSmbusQuickWrite. Length is
 110                                 outside the range of valid
 111                                 values.
 112
 113   @retval EFI_UNSUPPORTED       The SMBus operation or PEC is not
 114                                 supported.
 115
 116   @retval EFI_BUFFER_TOO_SMALL  Buffer is not sufficient for
 117                                 this operation.
 118
 119 **/
 120 typedef
 121 EFI_STATUS
 122 (EFIAPI *EFI_SMBUS_HC_EXECUTE_OPERATION)(
 123   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 124   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 125   IN CONST  EFI_SMBUS_DEVICE_COMMAND  Command,
 126   IN CONST  EFI_SMBUS_OPERATION       Operation,
 127   IN CONST  BOOLEAN                   PecCheck,
 128   IN OUT    UINTN                     *Length,
 129   IN OUT    VOID                      *Buffer
 130 );
 131
 132
 133
 134 /**
 135
 136   The ArpDevice() function provides a standard way for a device driver to
 137   enumerate the entire SMBus or specific devices on the bus.
 138
 139   @param This           A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 140
 141   @param ArpAll         A Boolean expression that indicates if the
 142                         host drivers need to enumerate all the devices
 143                         or enumerate only the device that is
 144                         identified by SmbusUdid. If ArpAll is TRUE,
 145                         SmbusUdid and SlaveAddress are optional. If
 146                         ArpAll is FALSE, ArpDevice will enumerate
 147                         SmbusUdid and the address will be at
 148                         SlaveAddress.
 149
 150   @param SmbusUdid      The Unique Device Identifier (UDID) that is
 151                         associated with this device. Type
 152                         EFI_SMBUS_UDID is defined in
 153                         EFI_PEI_SMBUS_PPI.ArpDevice() in the
 154                         Platform Initialization SMBus PPI
 155                         Specification.
 156
 157   @param SlaveAddress   The SMBus slave address that is
 158                         associated with an SMBus UDID.
 159
 160   @retval EFI_SUCCESS           The last data that was returned from the
 161                                 access matched the poll exit criteria.
 162
 163   @retval EFI_CRC_ERROR         Checksum is not correct (PEC is
 164                                 incorrect).
 165
 166   @retval EFI_TIMEOUT           Timeout expired before the operation was
 167                                 completed. Timeout is determined by the
 168                                 SMBus host controller device.
 169
 170   @retval EFI_OUT_OF_RESOURCES  The request could not be
 171                                 completed due to a lack of
 172                                 resources.
 173
 174   @retval EFI_DEVICE_ERROR      The request was not completed
 175                                 because a failure was reflected in
 176                                 the Host Status Register bit. Device
 177                                 Errors are a result of a transaction
 178                                 collision, illegal command field,
 179                                 unclaimed cycle (host initiated), or
 180                                 bus errors (collisions).
 181
 182   @retval EFI_UNSUPPORTED       ArpDevice, GetArpMap, and Notify are
 183                                 not implemented by this driver.
 184
 185 **/
 186 typedef
 187 EFI_STATUS
 188 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE)(
 189   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 190   IN CONST  BOOLEAN                   ArpAll,
 191   IN CONST  EFI_SMBUS_UDID            *SmbusUdid,   OPTIONAL
 192   IN OUT    EFI_SMBUS_DEVICE_ADDRESS  *SlaveAddress OPTIONAL
 193 );
 194
 195
 196 /**
 197   The GetArpMap() function returns the mapping of all the SMBus devices
 198   that were enumerated by the SMBus host driver.
 199
 200   @param This           A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 201
 202   @param Length         Size of the buffer that contains the SMBus
 203                         device map.
 204
 205   @param SmbusDeviceMap The pointer to the device map as
 206                         enumerated by the SMBus controller
 207                         driver.
 208
 209   @retval EFI_SUCCESS       The SMBus returned the current device map.
 210
 211   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 212                             not implemented by this driver.
 213
 214 **/
 215 typedef
 216 EFI_STATUS
 217 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP)(
 218   IN CONST  EFI_SMBUS_HC_PROTOCOL   *This,
 219   IN OUT    UINTN                   *Length,
 220   IN OUT    EFI_SMBUS_DEVICE_MAP    **SmbusDeviceMap
 221 );
 222
 223 /**
 224   The notify function does some actions.
 225
 226   @param SlaveAddress
 227   The SMBUS hardware address to which the SMBUS device is preassigned or allocated.
 228
 229   @param Data
 230   Data of the SMBus host notify command that the caller wants to be called.
 231
 232   @return EFI_STATUS
 233 **/
 234 typedef
 235 EFI_STATUS
 236 (EFIAPI *EFI_SMBUS_NOTIFY_FUNCTION)(
 237   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 238   IN CONST  UINTN                     Data
 239 );
 240
 241
 242 /**
 243
 244   The Notify() function registers all the callback functions to
 245   allow the bus driver to call these functions when the
 246   SlaveAddress/Data pair happens.
 247
 248   @param  This            A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 249
 250   @param  SlaveAddress    Address that the host controller detects
 251                           as sending a message and calls all the registered function.
 252
 253   @param  Data            Data that the host controller detects as sending
 254                           message and calls all the registered function.
 255
 256
 257   @param  NotifyFunction  The function to call when the bus
 258                           driver detects the SlaveAddress and
 259                           Data pair.
 260
 261   @retval EFI_SUCCESS       NotifyFunction was registered.
 262
 263   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 264                             not implemented by this driver.
 265
 266 **/
 267 typedef
 268 EFI_STATUS
 269 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_NOTIFY)(
 270   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 271   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 272   IN CONST  UINTN                     Data,
 273   IN CONST  EFI_SMBUS_NOTIFY_FUNCTION NotifyFunction
 274 );
 275
 276
 277 /**
 278   @par Protocol Description:
 279   The EFI_SMBUS_HC_PROTOCOL provides SMBus host controller management and basic data
 280   transactions over SMBus. There is one EFI_SMBUS_HC_PROTOCOL instance for each SMBus
 281   host controller.
 282
 283   @param Execute    Executes the SMBus operation to an SMBus slave
 284                     device. See the Execute() function description.
 285
 286   @param ArpDevice  Allows an SMBus 2.0 device(s) to be Address
 287                     Resolution Protocol (ARP).
 288
 289   @param GetArpMap  Allows a driver to retrieve the address that
 290                     was allocated by the SMBus host controller
 291                     during enumeration/ARP. See the GetArpMap()
 292                     function description.
 293
 294   @param  Notify    Allows a driver to register for a callback
 295                     to the SMBus host controller driver when the
 296                     bus issues a notification to the bus
 297                     controller driver. See the Notify() function
 298                     description.
 299 **/
 300 struct _EFI_SMBUS_HC_PROTOCOL {
 301   EFI_SMBUS_HC_EXECUTE_OPERATION    Execute;
 302   EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE  ArpDevice;
 303   EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP GetArpMap;
 304   EFI_SMBUS_HC_PROTOCOL_NOTIFY      Notify;
 305 };
 306
 307
 308 extern EFI_GUID gEfiSmbusHcProtocolGuid;
 309
 310 #endif
 311