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   The ArpDevice() function provides a standard way for a device driver to
 131   enumerate the entire SMBus or specific devices on the bus.
 132
 133   @param This           A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 134
 135   @param ArpAll         A Boolean expression that indicates if the
 136                         host drivers need to enumerate all the devices
 137                         or enumerate only the device that is
 138                         identified by SmbusUdid. If ArpAll is TRUE,
 139                         SmbusUdid and SlaveAddress are optional. If
 140                         ArpAll is FALSE, ArpDevice will enumerate
 141                         SmbusUdid and the address will be at
 142                         SlaveAddress.
 143
 144   @param SmbusUdid      The Unique Device Identifier (UDID) that is
 145                         associated with this device. Type
 146                         EFI_SMBUS_UDID is defined in
 147                         EFI_PEI_SMBUS_PPI.ArpDevice() in the
 148                         Platform Initialization SMBus PPI
 149                         Specification.
 150
 151   @param SlaveAddress   The SMBus slave address that is
 152                         associated with an SMBus UDID.
 153
 154   @retval EFI_SUCCESS           The last data that was returned from the
 155                                 access matched the poll exit criteria.
 156
 157   @retval EFI_CRC_ERROR         Checksum is not correct (PEC is
 158                                 incorrect).
 159
 160   @retval EFI_TIMEOUT           Timeout expired before the operation was
 161                                 completed. Timeout is determined by the
 162                                 SMBus host controller device.
 163
 164   @retval EFI_OUT_OF_RESOURCES  The request could not be
 165                                 completed due to a lack of
 166                                 resources.
 167
 168   @retval EFI_DEVICE_ERROR      The request was not completed
 169                                 because a failure was reflected in
 170                                 the Host Status Register bit. Device
 171                                 Errors are a result of a transaction
 172                                 collision, illegal command field,
 173                                 unclaimed cycle (host initiated), or
 174                                 bus errors (collisions).
 175
 176   @retval EFI_UNSUPPORTED       ArpDevice, GetArpMap, and Notify are
 177                                 not implemented by this driver.
 178
 179 **/
 180 typedef
 181 EFI_STATUS
 182 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE)(
 183   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 184   IN        BOOLEAN                   ArpAll,
 185   IN        EFI_SMBUS_UDID            *SmbusUdid    OPTIONAL,
 186   IN OUT    EFI_SMBUS_DEVICE_ADDRESS  *SlaveAddress OPTIONAL
 187   );
 188
 189 /**
 190   The GetArpMap() function returns the mapping of all the SMBus devices
 191   that were enumerated by the SMBus host driver.
 192
 193   @param This           A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 194
 195   @param Length         Size of the buffer that contains the SMBus
 196                         device map.
 197
 198   @param SmbusDeviceMap The pointer to the device map as
 199                         enumerated by the SMBus controller
 200                         driver.
 201
 202   @retval EFI_SUCCESS       The SMBus returned the current device map.
 203
 204   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 205                             not implemented by this driver.
 206
 207 **/
 208 typedef
 209 EFI_STATUS
 210 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP)(
 211   IN CONST  EFI_SMBUS_HC_PROTOCOL   *This,
 212   IN OUT    UINTN                   *Length,
 213   IN OUT    EFI_SMBUS_DEVICE_MAP    **SmbusDeviceMap
 214   );
 215
 216 /**
 217   The notify function does some actions.
 218
 219   @param SlaveAddress
 220   The SMBUS hardware address to which the SMBUS device is preassigned or allocated.
 221
 222   @param Data
 223   Data of the SMBus host notify command that the caller wants to be called.
 224
 225   @return EFI_STATUS
 226 **/
 227 typedef
 228 EFI_STATUS
 229 (EFIAPI *EFI_SMBUS_NOTIFY_FUNCTION)(
 230   IN        EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 231   IN        UINTN                     Data
 232   );
 233
 234 /**
 235
 236   The Notify() function registers all the callback functions to
 237   allow the bus driver to call these functions when the
 238   SlaveAddress/Data pair happens.
 239
 240   @param  This            A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
 241
 242   @param  SlaveAddress    Address that the host controller detects
 243                           as sending a message and calls all the registered function.
 244
 245   @param  Data            Data that the host controller detects as sending
 246                           message and calls all the registered function.
 247
 248
 249   @param  NotifyFunction  The function to call when the bus
 250                           driver detects the SlaveAddress and
 251                           Data pair.
 252
 253   @retval EFI_SUCCESS       NotifyFunction was registered.
 254
 255   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
 256                             not implemented by this driver.
 257
 258 **/
 259 typedef
 260 EFI_STATUS
 261 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_NOTIFY)(
 262   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
 263   IN        EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
 264   IN        UINTN                     Data,
 265   IN        EFI_SMBUS_NOTIFY_FUNCTION NotifyFunction
 266   );
 267
 268 ///
 269 /// The EFI_SMBUS_HC_PROTOCOL provides SMBus host controller management and basic data
 270 /// transactions over SMBus. There is one EFI_SMBUS_HC_PROTOCOL instance for each SMBus
 271 /// host controller.
 272 ///
 273 struct _EFI_SMBUS_HC_PROTOCOL {
 274   EFI_SMBUS_HC_EXECUTE_OPERATION       Execute;
 275   EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE     ArpDevice;
 276   EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP    GetArpMap;
 277   EFI_SMBUS_HC_PROTOCOL_NOTIFY         Notify;
 278 };
 279
 280 extern EFI_GUID  gEfiSmbusHcProtocolGuid;
 281
 282 #endif