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 <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. 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  @param Operation Signifies the particular SMBus
  55                   hardware protocol instance 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
  68
  69  @param Length    Signifies the number of bytes that this operation will do.
  70                   The maximum number of bytes can be revision
  71                   specific and operation specific. This field
  72                   will contain the actual number of bytes that
  73                   are executed for this operation. Not all
  74                   operations require this argument.
  75
  76   @param Buffer   Contains the value of data to execute to the
  77                   SMBus slave device. Not all operations require
  78                   this argument. The length of this buffer is
  79                   identified by Length.
  80
  81
  82   @retval EFI_SUCCESS           The last data that was returned from the
  83                                 access matched the poll exit criteria.
  84
  85   @retval EFI_CRC_ERROR         Checksum is not correct (PEC is 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
 138   enumerate the entire SMBus or specific devices on the bus.
 139
 140   @param This           A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 141
 142   @param ArpAll         A Boolean expression that indicates if the
 143                         host drivers need to enumerate all the devices
 144                         or enumerate only the device that is
 145                         identified by SmbusUdid. If ArpAll is TRUE,
 146                         SmbusUdid and SlaveAddress are optional. If
 147                         ArpAll is FALSE, ArpDevice will enumerate
 148                         SmbusUdid and the address will be at
 149                         SlaveAddress.
 150
 151   @param SmbusUdid      The Unique Device Identifier (UDID) that is
 152                         associated with this device. Type
 153                         EFI_SMBUS_UDID is defined in
 154                         EFI_PEI_SMBUS_PPI.ArpDevice() in the
 155                         Platform Initialization SMBus PPI
 156                         Specification.
 157
 158   @param SlaveAddress   The SMBus slave address that is
 159                         associated with an SMBus UDID.
 160
 161   @retval EFI_SUCCESS           The last data that was returned from the
 162                                 access matched the poll exit criteria.
 163
 164   @retval EFI_CRC_ERROR         Checksum is not correct (PEC is
 165                                 incorrect).
 166
 167   @retval EFI_TIMEOUT           Timeout expired before the operation was
 168                                 completed. Timeout is determined by the
 169                                 SMBus host controller device.
 170
 171   @retval EFI_OUT_OF_RESOURCES  The request could not be
 172                                 completed due to a lack of
 173                                 resources.
 174
 175   @retval EFI_DEVICE_ERROR      The request was not completed
 176                                 because a failure was reflected in
 177                                 the Host Status Register bit. Device
 178                                 Errors are a result of a transaction
 179                                 collision, illegal command field,
 180                                 unclaimed cycle (host initiated), or
 181                                 bus errors (collisions).
 182
 183   @retval EFI_UNSUPPORTED       ArpDevice, GetArpMap, and Notify are
 184                                 not implemented by this driver.
 185
 186 **/
 187 typedef
 188 EFI_STATUS
 189 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE)(
 190   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 191   IN CONST  BOOLEAN                   ArpAll,
 192   IN CONST  EFI_SMBUS_UDID            *SmbusUdid,   OPTIONAL
 193   IN OUT    EFI_SMBUS_DEVICE_ADDRESS  *SlaveAddress OPTIONAL
 194 );
 195
 196
 197 /**
 198   The GetArpMap() function returns the mapping of all the SMBus devices
 199   that were enumerated by the SMBus host driver.
 200
 201   @param This           A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 202
 203   @param Length         Size of the buffer that contains the SMBus
 204                         device map.
 205
 206   @param SmbusDeviceMap The pointer to the device map as
 207                         enumerated by the SMBus controller
 208                         driver.
 209
 210   @retval EFI_SUCCESS       The SMBus returned the current device map.
 211
 212   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 213                             not implemented by this driver.
 214
 215 **/
 216 typedef
 217 EFI_STATUS
 218 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP)(
 219   IN CONST  EFI_SMBUS_HC_PROTOCOL   *This,
 220   IN OUT    UINTN                   *Length,
 221   IN OUT    EFI_SMBUS_DEVICE_MAP    **SmbusDeviceMap
 222 );
 223
 224 /**
 225   The notify function does some actions.
 226
 227   @param SlaveAddress
 228   The SMBUS hardware address to which the SMBUS device is preassigned or allocated.
 229
 230   @param Data
 231   Data of the SMBus host notify command that the caller wants to be called.
 232
 233   @return EFI_STATUS
 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 that calls all the registered function.
 253
 254   @param  Data            Data that the host controller detects as sending
 255                           message, and that 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 struct _EFI_SMBUS_HC_PROTOCOL {
 284   EFI_SMBUS_HC_EXECUTE_OPERATION    Execute;
 285   EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE  ArpDevice;
 286   EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP GetArpMap;
 287   EFI_SMBUS_HC_PROTOCOL_NOTIFY      Notify;
 288 };
 289
 290
 291 extern EFI_GUID gEfiSmbusHcProtocolGuid;
 292
 293 #endif
 294