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 - 2009, 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 <IndustryStandard/SmBus.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.
  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
  55  @param Operation Signifies the particular SMBus
  56                   hardware protocol instance it will use to
  57                   execute the SMBus transactions. This SMBus
  58                   hardware protocol is defined by the SMBus
  59                   Specification and is not related to PI
  60                   Architecture. Type EFI_SMBUS_OPERATION is
  61                   defined in EFI_PEI_SMBUS_PPI.Execute() in the
  62                   Platform Initialization SMBus PPI
  63                   Specification.
  64
  65   @param PecCheck Defines if Packet Error Code (PEC) checking
  66                   is required for this operation. SMBus Host
  67                   Controller Code Definitions Version 1.0
  68                   August 21, 2006 13
  69
  70  @param Length    Signifies the 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 incorrect).
  87
  88   @retval EFI_TIMEOUT           Timeout expired before the operation was
  89                                 completed. Timeout is determined by the
  90                                 SMBus host controller device.
  91
  92   @retval EFI_OUT_OF_RESOURCES  The request could not be
  93                                 completed due to a lack of
  94                                 resources.
  95
  96   @retval EFI_DEVICE_ERROR      The request was not completed
  97                                 because a failure that was reflected
  98                                 in the Host Status Register bit.
  99                                 Device errors are a result of a
 100                                 transaction collision, illegal
 101                                 command field, unclaimed cycle (host
 102                                 initiated), or bus errors
 103                                 (collisions).
 104
 105   @retval EFI_INVALID_PARAMETER Operation is not defined in
 106                                 EFI_SMBUS_OPERATION.
 107
 108   @retval EFI_INVALID_PARAMETER Length/Buffer is NULL for
 109                                 operations except for
 110                                 EfiSmbusQuickRead and
 111                                 EfiSmbusQuickWrite. Length is
 112                                 outside the range of valid
 113                                 values.
 114
 115   @retval EFI_UNSUPPORTED       The SMBus operation or PEC is not
 116                                 supported.
 117
 118   @retval EFI_BUFFER_TOO_SMALL  Buffer is not sufficient for
 119                                 this operation.
 120
 121 **/
 122 typedef
 123 EFI_STATUS
 124 (EFIAPI *EFI_SMBUS_HC_EXECUTE_OPERATION)(
 125   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 126   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 127   IN CONST  EFI_SMBUS_DEVICE_COMMAND  Command,
 128   IN CONST  EFI_SMBUS_OPERATION       Operation,
 129   IN CONST  BOOLEAN                   PecCheck,
 130   IN OUT    UINTN                     *Length,
 131   IN OUT    VOID                      *Buffer
 132 );
 133
 134
 135
 136 /**
 137
 138   The ArpDevice() function provides a standard way for a device driver to
 139   enumerate the entire SMBus or specific devices on the bus.
 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   @retval EFI_SUCCESS           The last data that was returned from the
 163                                 access matched the poll exit criteria.
 164
 165   @retval EFI_CRC_ERROR         Checksum is not correct (PEC is
 166                                 incorrect).
 167
 168   @retval EFI_TIMEOUT           Timeout expired before the operation was
 169                                 completed. Timeout is determined by the
 170                                 SMBus host controller device.
 171
 172   @retval EFI_OUT_OF_RESOURCES  The request could not be
 173                                 completed due to a lack of
 174                                 resources.
 175
 176   @retval EFI_DEVICE_ERROR      The request was not completed
 177                                 because a failure was reflected in
 178                                 the Host Status Register bit. Device
 179                                 Errors are a result of a transaction
 180                                 collision, illegal command field,
 181                                 unclaimed cycle (host initiated), or
 182                                 bus errors (collisions).
 183
 184   @retval EFI_UNSUPPORTED       ArpDevice, GetArpMap, and Notify are
 185                                 not implemented by this driver.
 186
 187 **/
 188 typedef
 189 EFI_STATUS
 190 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE)(
 191   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 192   IN CONST  BOOLEAN                   ArpAll,
 193   IN CONST  EFI_SMBUS_UDID            *SmbusUdid,   OPTIONAL
 194   IN OUT    EFI_SMBUS_DEVICE_ADDRESS  *SlaveAddress OPTIONAL
 195 );
 196
 197
 198 /**
 199   The GetArpMap() function returns the mapping of all the SMBus devices
 200   that were enumerated by the SMBus host driver.
 201
 202   @param This           A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 203
 204   @param Length         Size of the buffer that contains the SMBus
 205                         device map.
 206
 207   @param SmbusDeviceMap The pointer to the device map as
 208                         enumerated by the SMBus controller
 209                         driver.
 210
 211   @retval EFI_SUCCESS       The SMBus returned the current device map.
 212
 213   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 214                             not implemented by this driver.
 215
 216 **/
 217 typedef
 218 EFI_STATUS
 219 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP)(
 220   IN CONST  EFI_SMBUS_HC_PROTOCOL   *This,
 221   IN OUT    UINTN                   *Length,
 222   IN OUT    EFI_SMBUS_DEVICE_MAP    **SmbusDeviceMap
 223 );
 224
 225 /**
 226   The notify function does some actions.
 227
 228   @param SlaveAddress
 229   The SMBUS hardware address to which the SMBUS device is preassigned or allocated.
 230
 231   @param Data
 232   Data of the SMBus host notify command that the caller wants to be called.
 233
 234   @return EFI_STATUS
 235 **/
 236 typedef
 237 EFI_STATUS
 238 (EFIAPI *EFI_SMBUS_NOTIFY_FUNCTION)(
 239   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 240   IN CONST  UINTN                     Data
 241 );
 242
 243
 244 /**
 245
 246   The Notify() function registers all the callback functions to
 247   allow the bus driver to call these functions when the
 248   SlaveAddress/Data pair happens.
 249
 250   @param  This            A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 251
 252   @param  SlaveAddress    Address that the host controller detects
 253                           as sending a message and calls all the registered function.
 254
 255   @param  Data            Data that the host controller detects as sending
 256                           message and calls all the registered function.
 257
 258
 259   @param  NotifyFunction  The function to call when the bus
 260                           driver detects the SlaveAddress and
 261                           Data pair.
 262
 263   @retval EFI_SUCCESS       NotifyFunction was registered.
 264
 265   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 266                             not implemented by this driver.
 267
 268 **/
 269 typedef
 270 EFI_STATUS
 271 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_NOTIFY)(
 272   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 273   IN CONST  EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 274   IN CONST  UINTN                     Data,
 275   IN CONST  EFI_SMBUS_NOTIFY_FUNCTION NotifyFunction
 276 );
 277
 278
 279 ///
 280 /// The EFI_SMBUS_HC_PROTOCOL provides SMBus host controller management and basic data
 281 /// transactions over SMBus. There is one EFI_SMBUS_HC_PROTOCOL instance for each SMBus
 282 /// host controller.
 283 ///
 284 struct _EFI_SMBUS_HC_PROTOCOL {
 285   EFI_SMBUS_HC_EXECUTE_OPERATION    Execute;
 286   EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE  ArpDevice;
 287   EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP GetArpMap;
 288   EFI_SMBUS_HC_PROTOCOL_NOTIFY      Notify;
 289 };
 290
 291
 292 extern EFI_GUID gEfiSmbusHcProtocolGuid;
 293
 294 #endif
 295