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 - 2007, 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
  85                         incorrect).
  86
  87   @retval EFI_TIMEOUT   Timeout expired before the operation was
  88                         completed. Timeout is determined by the
  89                         SMBus host controller device.
  90
  91   @retval EFI_OUT_OF_RESOURCES  The request could not be
  92                                 completed due to a lack of
  93                                 resources.
  94
  95   @retval EFI_DEVICE_ERROR  The request was not completed
  96                             because a failure that was reflected
  97                             in the Host Status Register bit.
  98                             Device errors are a result of a
  99                             transaction collision, illegal
 100                             command field, unclaimed cycle (host
 101                             initiated), or bus errors
 102                             (collisions).
 103
 104   @retval EFI_INVALID_PARAMETER Operation is not defined in
 105                                 EFI_SMBUS_OPERATION.
 106
 107   @retval EFI_INVALID_PARAMETER Length/Buffer is NULL for
 108                                 operations except for
 109                                 EfiSmbusQuickRead and
 110                                 EfiSmbusQuickWrite. Length is
 111                                 outside the range of valid
 112                                 values.
 113
 114   @retval EFI_UNSUPPORTED   The SMBus operation or PEC is not
 115                             supported.
 116
 117   @retval EFI_BUFFER_TOO_SMALL  Buffer is not sufficient for
 118                                 this operation.
 119
 120 **/
 121 typedef
 122 EFI_STATUS
 123 (EFIAPI *EFI_SMBUS_HC_EXECUTE_OPERATION) (
 124   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 125   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 126   IN CONST  EFI_SMBUS_DEVICE_COMMAND  Command,
 127   IN CONST  EFI_SMBUS_OPERATION       Operation,
 128   IN CONST  BOOLEAN                   PecCheck,
 129   IN OUT    UINTN                     *Length,
 130   IN OUT    VOID                      *Buffer
 131 );
 132
 133
 134
 135 /**
 136
 137   The ArpDevice() function provides a standard way for a device driver to enumerate the entire
 138   SMBus or specific devices on the bus.
 139
 140
 141   @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 142
 143   @param ArpAll   A Boolean expression that indicates if the
 144                   host drivers need to enumerate all the devices
 145                   or enumerate only the device that is
 146                   identified by SmbusUdid. If ArpAll is TRUE,
 147                   SmbusUdid and SlaveAddress are optional. If
 148                   ArpAll is FALSE, ArpDevice will enumerate
 149                   SmbusUdid and the address will be at
 150                   SlaveAddress.
 151
 152   @param SmbusUdid  The Unique Device Identifier (UDID) that is
 153                     associated with this device. Type
 154                     EFI_SMBUS_UDID is defined in
 155                     EFI_PEI_SMBUS_PPI.ArpDevice() in the
 156                     Platform Initialization SMBus PPI
 157                     Specification.
 158
 159   @param SlaveAddress   The SMBus slave address that is
 160                         associated with an SMBus UDID.
 161
 162
 163
 164   @retval EFI_SUCCESS   The last data that was returned from the
 165                         access matched the poll exit criteria.
 166
 167   @retval EFI_CRC_ERROR Checksum is not correct (PEC is
 168                         incorrect).
 169
 170   @retval EFI_TIMEOUT   Timeout expired before the operation was
 171                         completed. Timeout is determined by the
 172                         SMBus host controller device.
 173
 174   @retval EFI_OUT_OF_RESOURCES  The request could not be
 175                                 completed due to a lack of
 176                                 resources.
 177
 178   @retval EFI_DEVICE_ERROR  The request was not completed
 179                             because a failure was reflected in
 180                             the Host Status Register bit. Device
 181                             Errors are a result of a transaction
 182                             collision, illegal command field,
 183                             unclaimed cycle (host initiated), or
 184                             bus errors (collisions).
 185
 186   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 187                             not implemented by this driver.
 188
 189 **/
 190 typedef
 191 EFI_STATUS
 192 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE) (
 193   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 194   IN CONST  BOOLEAN                   ArpAll,
 195   IN CONST  EFI_SMBUS_UDID            *SmbusUdid,   OPTIONAL
 196   IN OUT    EFI_SMBUS_DEVICE_ADDRESS  *SlaveAddress OPTIONAL
 197 );
 198
 199
 200 /**
 201   The GetArpMap() function returns the mapping of all the SMBus devices that were enumerated
 202   by the SMBus host driver.
 203
 204   @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 205
 206   @param Length   Size of the buffer that contains the SMBus
 207                   device map.
 208
 209   @param SmbusDeviceMap The pointer to the device map as
 210                         enumerated by the SMBus controller
 211                         driver.
 212
 213   @retval EFI_SUCCESS   The SMBus returned the current device
 214                         map.
 215
 216   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 217                             not implemented by this driver.
 218
 219 **/
 220 typedef
 221 EFI_STATUS
 222 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP) (
 223   IN CONST  EFI_SMBUS_HC_PROTOCOL   *This,
 224   IN OUT    UINTN                   *Length,
 225   IN OUT    EFI_SMBUS_DEVICE_MAP    **SmbusDeviceMap
 226 );
 227
 228
 229
 230 //
 231 // EFI_SMBUS_NOTIFY_FUNCTION
 232 //
 233 typedef
 234 EFI_STATUS
 235 (EFIAPI *EFI_SMBUS_NOTIFY_FUNCTION) (
 236   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 237   IN CONST  UINTN                     Data
 238 );
 239
 240
 241 /**
 242
 243   The Notify() function registers all the callback functions to
 244   allow the bus driver to call these functions when the
 245   SlaveAddress/Data pair happens.
 246
 247   @param  This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 248
 249   @param  SlaveAddress  Address that the host controller detects
 250                         as sending a message and calls all the registered function.
 251
 252   @param  Data  Data that the host controller detects as sending
 253                 message and calls all the registered function.
 254
 255
 256   @param  NotifyFunction  The function to call when the bus
 257                           driver detects the SlaveAddress and
 258                           Data pair.
 259
 260   @retval EFI_SUCCESS   NotifyFunction was registered.
 261
 262   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 263                             not implemented by this driver.
 264
 265 **/
 266 typedef
 267 EFI_STATUS
 268 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_NOTIFY) (
 269   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 270   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 271   IN CONST  UINTN                     Data,
 272   IN CONST  EFI_SMBUS_NOTIFY_FUNCTION NotifyFunction
 273 );
 274
 275
 276 /**
 277   The EFI_SMBUS_HC_PROTOCOL provides SMBus host controller management and basic data
 278   transactions over SMBus. There is one EFI_SMBUS_HC_PROTOCOL instance for each SMBus
 279   host controller.
 280
 281   @param Execute  Executes the SMBus operation to an SMBus slave
 282                   device. See the Execute() function description.
 283
 284   @param ArpDevice  Allows an SMBus 2.0 device(s) to be Address
 285                     Resolution Protocol (ARP).
 286
 287   @param GetArpMap  Allows a driver to retrieve the address that
 288                     was allocated by the SMBus host controller
 289                     during enumeration/ARP. See the GetArpMap()
 290                     function description.
 291
 292   @param  Notify    Allows a driver to register for a callback
 293                     to the SMBus host controller driver when the
 294                     bus issues a notification to the bus
 295                     controller driver. See the Notify() function
 296                     description.
 297 **/
 298 struct _EFI_SMBUS_HC_PROTOCOL {
 299   EFI_SMBUS_HC_EXECUTE_OPERATION    Execute;
 300   EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE  ArpDevice;
 301   EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP GetArpMap;
 302   EFI_SMBUS_HC_PROTOCOL_NOTIFY      Notify;
 303 };
 304
 305
 306 extern EFI_GUID gEfiSmbusHcProtocolGuid;
 307
 308 #endif
 309