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   Module Name:  SmbusHc.h
  15
  16   @par Revision Reference: PI
  17   Version 1.00.
  18
  19 **/
  20
  21 #ifndef __SMBUS_HC_H__
  22 #define __SMBUS_HC_H__
  23
  24 #include <Ppi/Smbus2.h>
  25
  26 #define EFI_SMBUS_HC_PROTOCOL_GUID \
  27   {0xe49d33ed, 0x513d, 0x4634, { 0xb6, 0x98, 0x6f, 0x55, 0xaa, 0x75, 0x1c, 0x1b} }
  28
  29 typedef struct _EFI_SMBUS_HC_PROTOCOL EFI_SMBUS_HC_PROTOCOL;
  30
  31 /**
  32
  33   The Execute() function provides a standard way to execute an
  34   operation as defined in the System Management Bus (SMBus)
  35   Specification. The resulting transaction will be either that
  36   the SMBus slave devices accept this transaction or that this
  37   function returns with error. Status Codes Returned
  38
  39   @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
  40               SlaveAddress The SMBus slave address of the device
  41               with which to communicate. Type
  42               EFI_SMBUS_DEVICE_ADDRESS is defined in
  43               EFI_PEI_SMBUS_PPI.Execute() in the Platform
  44               Initialization SMBus PPI Specification.
  45
  46   @param Command  This command is transmitted by the SMBus host
  47                   controller to the SMBus slave device and the
  48                   interpretation is SMBus slave device specific.
  49                   It can mean the offset to a list of functions
  50                   inside an SMBus slave device. Not all
  51                   operations or slave devices support this
  52                   command's registers. Type
  53                   EFI_SMBUS_DEVICE_COMMAND is defined in
  54                   EFI_PEI_SMBUS_PPI.Execute() in the Platform
  55                   Initialization SMBus PPI Specification.
  56                   Operation Signifies which particular SMBus
  57                   hardware protocol instance that it will use to
  58                   execute the SMBus transactions. This SMBus
  59                   hardware protocol is defined by the SMBus
  60                   Specification and is not related to PI
  61                   Architecture. Type EFI_SMBUS_OPERATION is
  62                   defined in EFI_PEI_SMBUS_PPI.Execute() in the
  63                   Platform Initialization SMBus PPI
  64                   Specification.
  65
  66   @param PecCheck   Defines if Packet Error Code (PEC) checking
  67                     is required for this operation. SMBus Host
  68                     Controller Code Definitions Version 1.0
  69                     August 21, 2006 13 Length Signifies the
  70                     number of bytes that this operation will do.
  71                     The maximum number of bytes can be revision
  72                     specific and operation specific. This field
  73                     will contain the actual number of bytes that
  74                     are executed for this operation. Not all
  75                     operations require this argument.
  76
  77   @param Buffer   Contains the value of data to execute to the
  78                   SMBus slave device. Not all operations require
  79                   this argument. The length of this buffer is
  80                   identified by Length.
  81
  82
  83   @retval EFI_SUCCESS   The last data that was returned from the
  84                         access matched the poll exit criteria.
  85
  86   @retval EFI_CRC_ERROR Checksum is not correct (PEC is
  87                         incorrect).
  88
  89   @retval EFI_TIMEOUT   Timeout expired before the operation was
  90                         completed. Timeout is determined by the
  91                         SMBus host controller device.
  92
  93   @retval EFI_OUT_OF_RESOURCES  The request could not be
  94                                 completed due to a lack of
  95                                 resources.
  96
  97   @retval EFI_DEVICE_ERROR  The request was not completed
  98                             because a failure that was reflected
  99                             in the Host Status Register bit.
 100                             Device errors are a result of a
 101                             transaction collision, illegal
 102                             command field, unclaimed cycle (host
 103                             initiated), or bus errors
 104                             (collisions).
 105
 106   @retval EFI_INVALID_PARAMETER Operation is not defined in
 107                                 EFI_SMBUS_OPERATION.
 108
 109   @retval EFI_INVALID_PARAMETER Length/Buffer is NULL for
 110                                 operations except for
 111                                 EfiSmbusQuickRead and
 112                                 EfiSmbusQuickWrite. Length is
 113                                 outside the range of valid
 114                                 values.
 115
 116   @retval EFI_UNSUPPORTED   The SMBus operation or PEC is not
 117                             supported.
 118
 119   @retval EFI_BUFFER_TOO_SMALL  Buffer is not sufficient for
 120                                 this operation.
 121
 122 **/
 123 typedef
 124 EFI_STATUS
 125 (EFIAPI *EFI_SMBUS_HC_EXECUTE_OPERATION) (
 126   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 127   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 128   IN CONST  EFI_SMBUS_DEVICE_COMMAND  Command,
 129   IN CONST  EFI_SMBUS_OPERATION       Operation,
 130   IN CONST  BOOLEAN                   PecCheck,
 131   IN OUT    UINTN                     *Length,
 132   IN OUT    VOID                      *Buffer
 133 );
 134
 135
 136
 137 /**
 138
 139   The ArpDevice() function provides a standard way for a device driver to enumerate the entire
 140   SMBus or specific devices on the bus.
 141
 142
 143   @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 144
 145   @param ArpAll   A Boolean expression that indicates if the
 146                   host drivers need to enumerate all the devices
 147                   or enumerate only the device that is
 148                   identified by SmbusUdid. If ArpAll is TRUE,
 149                   SmbusUdid and SlaveAddress are optional. If
 150                   ArpAll is FALSE, ArpDevice will enumerate
 151                   SmbusUdid and the address will be at
 152                   SlaveAddress.
 153
 154   @param SmbusUdid  The Unique Device Identifier (UDID) that is
 155                     associated with this device. Type
 156                     EFI_SMBUS_UDID is defined in
 157                     EFI_PEI_SMBUS_PPI.ArpDevice() in the
 158                     Platform Initialization SMBus PPI
 159                     Specification.
 160
 161   @param SlaveAddress   The SMBus slave address that is
 162                         associated with an SMBus UDID.
 163
 164
 165
 166   @retval EFI_SUCCESS   The last data that was returned from the
 167                         access matched the poll exit criteria.
 168
 169   @retval EFI_CRC_ERROR Checksum is not correct (PEC is
 170                         incorrect).
 171
 172   @retval EFI_TIMEOUT   Timeout expired before the operation was
 173                         completed. Timeout is determined by the
 174                         SMBus host controller device.
 175
 176   @retval EFI_OUT_OF_RESOURCES  The request could not be
 177                                 completed due to a lack of
 178                                 resources.
 179
 180   @retval EFI_DEVICE_ERROR  The request was not completed
 181                             because a failure was reflected in
 182                             the Host Status Register bit. Device
 183                             Errors are a result of a transaction
 184                             collision, illegal command field,
 185                             unclaimed cycle (host initiated), or
 186                             bus errors (collisions).
 187
 188   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 189                             not implemented by this driver.
 190
 191 **/
 192 typedef
 193 EFI_STATUS
 194 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE) (
 195   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 196   IN CONST  BOOLEAN                   ArpAll,
 197   IN CONST  EFI_SMBUS_UDID            *SmbusUdid,   OPTIONAL
 198   IN OUT    EFI_SMBUS_DEVICE_ADDRESS  *SlaveAddress OPTIONAL
 199 );
 200
 201
 202 /**
 203   The GetArpMap() function returns the mapping of all the SMBus devices that were enumerated
 204   by the SMBus host driver.
 205
 206   @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 207
 208   @param Length   Size of the buffer that contains the SMBus
 209                   device map.
 210
 211   @param SmbusDeviceMap The pointer to the device map as
 212                         enumerated by the SMBus controller
 213                         driver.
 214
 215   @retval EFI_SUCCESS   The SMBus returned the current device
 216                         map.
 217
 218   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 219                             not implemented by this driver.
 220
 221 **/
 222 typedef
 223 EFI_STATUS
 224 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP) (
 225   IN CONST  EFI_SMBUS_HC_PROTOCOL   *This,
 226   IN OUT    UINTN                   *Length,
 227   IN OUT    EFI_SMBUS_DEVICE_MAP    **SmbusDeviceMap
 228 );
 229
 230
 231
 232 //
 233 // EFI_SMBUS_NOTIFY_FUNCTION
 234 //
 235 typedef
 236 EFI_STATUS
 237 (EFIAPI *EFI_SMBUS_NOTIFY_FUNCTION) (
 238   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 239   IN CONST  UINTN                     Data
 240 );
 241
 242
 243 /**
 244
 245   The Notify() function registers all the callback functions to
 246   allow the bus driver to call these functions when the
 247   SlaveAddress/Data pair happens.
 248
 249   @param  This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 250
 251   @param  SlaveAddress  Address that the host controller detects
 252                         as sending a message and calls all the registered function.
 253
 254   @param  Data  Data that the host controller detects as sending
 255                 message and calls all the registered function.
 256
 257
 258   @param  NotifyFunction  The function to call when the bus
 259                           driver detects the SlaveAddress and
 260                           Data pair.
 261
 262   @retval EFI_SUCCESS   NotifyFunction was registered.
 263
 264   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 265                             not implemented by this driver.
 266
 267 **/
 268 typedef
 269 EFI_STATUS
 270 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_NOTIFY) (
 271   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 272   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 273   IN CONST  UINTN                     Data,
 274   IN CONST  EFI_SMBUS_NOTIFY_FUNCTION NotifyFunction
 275 );
 276
 277
 278 /**
 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