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