MdePkg/Include/Library/S3SmbusLib.h

   1 /** @file
   2   Smbus Library Services that conduct SMBus transactions and enable the operatation
   3   to be replayed during an S3 resume. This library class maps directly on top
   4   of the SmbusLib class.
   5
   6   Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>
   7
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __S3_SMBUS_LIB_H__
  13 #define __S3_SMBUS_LIB_H__
  14
  15 /**
  16   Executes an SMBUS quick read command, and saves the value in the S3 script to be replayed
  17   on S3 resume.
  18
  19   Executes an SMBUS quick read command on the SMBUS device specified by SmBusAddress.
  20   Only the SMBUS slave address field of SmBusAddress is required.
  21   If Status is not NULL, then the status of the executed command is returned in Status.
  22   If PEC is set in SmBusAddress, then ASSERT().
  23   If Command in SmBusAddress is not zero, then ASSERT().
  24   If Length in SmBusAddress is not zero, then ASSERT().
  25   If any reserved bits of SmBusAddress are set, then ASSERT().
  26
  27   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
  28                              SMBUS Command, SMBUS Data Length, and PEC.
  29   @param[out] Status         The return status for the executed command.
  30                              This is an optional parameter and may be NULL.
  31                              RETURN_SUCCESS       The SMBUS command was executed.
  32                              RETURN_TIMEOUT       A timeout occurred while executing the SMBUS command.
  33                              RETURN_DEVICE_ERROR The request was not completed because a failure
  34                               was recorded in the Host Status Register bit.  Device errors are a result
  35                               of a transaction collision, illegal command field, unclaimed cycle
  36                               (host initiated), or bus error (collision).
  37                              RETURN_UNSUPPORTED    The SMBus operation is not supported.
  38
  39 **/
  40 VOID
  41 EFIAPI
  42 S3SmBusQuickRead (
  43   IN  UINTN          SmBusAddress,
  44   OUT RETURN_STATUS  *Status       OPTIONAL
  45   );
  46
  47 /**
  48   Executes an SMBUS quick write command, and saves the value in the S3 script to be replayed
  49   on S3 resume.
  50
  51   Executes an SMBUS quick write command on the SMBUS device specified by SmBusAddress.
  52   Only the SMBUS slave address field of SmBusAddress is required.
  53   If Status is not NULL, then the status of the executed command is returned in Status.
  54   If PEC is set in SmBusAddress, then ASSERT().
  55   If Command in SmBusAddress is not zero, then ASSERT().
  56   If Length in SmBusAddress is not zero, then ASSERT().
  57   If any reserved bits of SmBusAddress are set, then ASSERT().
  58
  59   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
  60                              SMBUS Command, SMBUS Data Length, and PEC.
  61   @param[out] Status         The return status for the executed command.
  62                              This is an optional parameter and may be NULL.
  63                              RETURN_SUCCESS      The SMBUS command was executed.
  64                              RETURN_TIMEOUT      A timeout occurred while executing the SMBUS command.
  65                              RETURN_DEVICE_ERROR The request was not completed because a failure
  66                              was recorded in the Host Status Register bit.  Device errors are a result
  67                              of a transaction collision, illegal command field, unclaimed cycle
  68                              (host initiated), or bus error (collision).
  69                              RETURN_UNSUPPORTED    The SMBus operation is not supported.
  70
  71 **/
  72 VOID
  73 EFIAPI
  74 S3SmBusQuickWrite (
  75   IN  UINTN          SmBusAddress,
  76   OUT RETURN_STATUS  *Status       OPTIONAL
  77   );
  78
  79 /**
  80   Executes an SMBUS receive byte command, and saves the value in the S3 script to be replayed
  81   on S3 resume.
  82
  83   Executes an SMBUS receive byte command on the SMBUS device specified by SmBusAddress.
  84   Only the SMBUS slave address field of SmBusAddress is required.
  85   The byte received from the SMBUS is returned.
  86   If Status is not NULL, then the status of the executed command is returned in Status.
  87   If Command in SmBusAddress is not zero, then ASSERT().
  88   If Length in SmBusAddress is not zero, then ASSERT().
  89   If any reserved bits of SmBusAddress are set, then ASSERT().
  90
  91   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
  92                              SMBUS Command, SMBUS Data Length, and PEC.
  93   @param[out] Status         The return status for the executed command.
  94                              This is an optional parameter and may be NULL.
  95                              RETURN_SUCCESS      The SMBUS command was executed.
  96                              RETURN_TIMEOUT      A timeout occurred while executing the SMBUS command.
  97                              RETURN_DEVICE_ERROR The request was not completed because a failure
  98                              was recorded in the Host Status Register bit.  Device errors are a result
  99                              of a transaction collision, illegal command field, unclaimed cycle
 100                              (host initiated), or bus error (collision).
 101                              RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect).
 102                              RETURN_UNSUPPORTED    The SMBus operation is not supported.
 103
 104   @return   The byte received from the SMBUS.
 105
 106 **/
 107 UINT8
 108 EFIAPI
 109 S3SmBusReceiveByte (
 110   IN  UINTN          SmBusAddress,
 111   OUT RETURN_STATUS  *Status        OPTIONAL
 112   );
 113
 114 /**
 115   Executes an SMBUS send byte command, and saves the value in the S3 script to be replayed
 116   on S3 resume.
 117
 118   Executes an SMBUS send byte command on the SMBUS device specified by SmBusAddress.
 119   The byte specified by Value is sent.
 120   Only the SMBUS slave address field of SmBusAddress is required.  Value is returned.
 121   If Status is not NULL, then the status of the executed command is returned in Status.
 122   If Command in SmBusAddress is not zero, then ASSERT().
 123   If Length in SmBusAddress is not zero, then ASSERT().
 124   If any reserved bits of SmBusAddress are set, then ASSERT().
 125
 126   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
 127                              SMBUS Command, SMBUS Data Length, and PEC.
 128   @param[in]  Value          The 8-bit value to send.
 129   @param[out] Status         The return status for the executed command.
 130                              This is an optional parameter and may be NULL.
 131                              RETURN_SUCCESS The SMBUS command was executed.
 132                              RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 133                              RETURN_DEVICE_ERROR  The request was not completed because a failure
 134                              was recorded in the Host Status Register bit.  Device errors are a result
 135                              of a transaction collision, illegal command field, unclaimed cycle
 136                              (host initiated), or bus errors (collisions).
 137                              RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect).
 138                              RETURN_UNSUPPORTED  The SMBus operation is not supported.
 139
 140   @return   The parameter of Value.
 141
 142 **/
 143 UINT8
 144 EFIAPI
 145 S3SmBusSendByte (
 146   IN  UINTN          SmBusAddress,
 147   IN  UINT8          Value,
 148   OUT RETURN_STATUS  *Status        OPTIONAL
 149   );
 150
 151 /**
 152   Executes an SMBUS read data byte command, and saves the value in the S3 script to be replayed
 153   on S3 resume.
 154
 155   Executes an SMBUS read data byte command on the SMBUS device specified by SmBusAddress.
 156   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 157   The 8-bit value read from the SMBUS is returned.
 158   If Status is not NULL, then the status of the executed command is returned in Status.
 159   If Length in SmBusAddress is not zero, then ASSERT().
 160   If any reserved bits of SmBusAddress are set, then ASSERT().
 161
 162   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
 163                              SMBUS Command, SMBUS Data Length, and PEC.
 164   @param[out] Status         The return status for the executed command.
 165                              This is an optional parameter and may be NULL.
 166                              RETURN_SUCCESS The SMBUS command was executed.
 167                              RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 168                              RETURN_DEVICE_ERROR  The request was not completed because a failure
 169                              was recorded in the Host Status Register bit.  Device errors are a result
 170                              of a transaction collision, illegal command field, unclaimed cycle
 171                              (host initiated), or bus error (collision).
 172                              RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect).
 173                              RETURN_UNSUPPORTED  The SMBus operation is not supported.
 174
 175   @return   The byte read from the SMBUS.
 176
 177 **/
 178 UINT8
 179 EFIAPI
 180 S3SmBusReadDataByte (
 181   IN  UINTN          SmBusAddress,
 182   OUT RETURN_STATUS  *Status        OPTIONAL
 183   );
 184
 185 /**
 186   Executes an SMBUS write data byte command, and saves the value in the S3 script to be replayed
 187   on S3 resume.
 188
 189   Executes an SMBUS write data byte command on the SMBUS device specified by SmBusAddress.
 190   The 8-bit value specified by Value is written.
 191   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 192   Value is returned.
 193   If Status is not NULL, then the status of the executed command is returned in Status.
 194   If Length in SmBusAddress is not zero, then ASSERT().
 195   If any reserved bits of SmBusAddress are set, then ASSERT().
 196
 197   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
 198                              SMBUS Command, SMBUS Data Length, and PEC.
 199   @param[in]  Value          The 8-bit value to write.
 200   @param[out] Status         The return status for the executed command.
 201                              This is an optional parameter and may be NULL.
 202                              RETURN_SUCCESS The SMBUS command was executed.
 203                              RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 204                              RETURN_DEVICE_ERROR  The request was not completed because a failure
 205                              was recorded in the Host Status Register bit.  Device errors are a result
 206                              of a transaction collision, illegal command field, unclaimed cycle
 207                              (host initiated), or bus error (collision).
 208                              RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect).
 209                              RETURN_UNSUPPORTED  The SMBus operation is not supported.
 210
 211   @return   The parameter of Value.
 212
 213 **/
 214 UINT8
 215 EFIAPI
 216 S3SmBusWriteDataByte (
 217   IN  UINTN          SmBusAddress,
 218   IN  UINT8          Value,
 219   OUT RETURN_STATUS  *Status        OPTIONAL
 220   );
 221
 222 /**
 223   Executes an SMBUS read data word command, and saves the value in the S3 script to be replayed
 224   on S3 resume.
 225
 226   Executes an SMBUS read data word command on the SMBUS device specified by SmBusAddress.
 227   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 228   The 16-bit value read from the SMBUS is returned.
 229   If Status is not NULL, then the status of the executed command is returned in Status.
 230   If Length in SmBusAddress is not zero, then ASSERT().
 231   If any reserved bits of SmBusAddress are set, then ASSERT().
 232
 233   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
 234                              SMBUS Command, SMBUS Data Length, and PEC.
 235   @param[out] Status         The return status for the executed command.
 236                              This is an optional parameter and may be NULL.
 237                              RETURN_SUCCESS The SMBUS command was executed.
 238                              RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 239                              RETURN_DEVICE_ERROR  The request was not completed because a failure
 240                              was recorded in the Host Status Register bit.  Device errors are a result
 241                              of a transaction collision, illegal command field, unclaimed cycle
 242                              (host initiated), or bus error (collision).
 243                              RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect).
 244                              RETURN_UNSUPPORTED  The SMBus operation is not supported.
 245
 246   @return   The byte read from the SMBUS.
 247
 248 **/
 249 UINT16
 250 EFIAPI
 251 S3SmBusReadDataWord (
 252   IN  UINTN          SmBusAddress,
 253   OUT RETURN_STATUS  *Status        OPTIONAL
 254   );
 255
 256 /**
 257   Executes an SMBUS write data word command, and saves the value in the S3 script to be replayed
 258   on S3 resume.
 259
 260   Executes an SMBUS write data word command on the SMBUS device specified by SmBusAddress.
 261   The 16-bit value specified by Value is written.
 262   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 263   Value is returned.
 264   If Status is not NULL, then the status of the executed command is returned in Status.
 265   If Length in SmBusAddress is not zero, then ASSERT().
 266   If any reserved bits of SmBusAddress are set, then ASSERT().
 267
 268   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
 269                              SMBUS Command, SMBUS Data Length, and PEC.
 270   @param[in]  Value          The 16-bit value to write.
 271   @param[out] Status         The return status for the executed command.
 272                              This is an optional parameter and may be NULL.
 273                              RETURN_SUCCESS The SMBUS command was executed.
 274                              RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 275                              RETURN_DEVICE_ERROR  The request was not completed because a failure
 276                              was recorded in the Host Status Register bit.  Device errors are a result
 277                              of a transaction collision, illegal command field, unclaimed cycle
 278                              (host initiated), or bus error (collision).
 279                              RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect).
 280                              RETURN_UNSUPPORTED  The SMBus operation is not supported.
 281
 282   @return   The parameter of Value.
 283
 284 **/
 285 UINT16
 286 EFIAPI
 287 S3SmBusWriteDataWord (
 288   IN  UINTN          SmBusAddress,
 289   IN  UINT16         Value,
 290   OUT RETURN_STATUS  *Status        OPTIONAL
 291   );
 292
 293 /**
 294   Executes an SMBUS process call command, and saves the value in the S3 script to be replayed
 295   on S3 resume.
 296
 297   Executes an SMBUS process call command on the SMBUS device specified by SmBusAddress.
 298   The 16-bit value specified by Value is written.
 299   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 300   The 16-bit value returned by the process call command is returned.
 301   If Status is not NULL, then the status of the executed command is returned in Status.
 302   If Length in SmBusAddress is not zero, then ASSERT().
 303   If any reserved bits of SmBusAddress are set, then ASSERT().
 304
 305   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
 306                              SMBUS Command, SMBUS Data Length, and PEC.
 307   @param[in]  Value          The 16-bit value to write.
 308   @param[out] Status         The return status for the executed command.
 309                              This is an optional parameter and may be NULL.
 310                              RETURN_SUCCESS The SMBUS command was executed.
 311                              RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 312                              RETURN_DEVICE_ERROR  The request was not completed because a failure
 313                              was recorded in the Host Status Register bit.  Device errors are a result
 314                              of a transaction collision, illegal command field, unclaimed cycle
 315                              (host initiated), or bus error (collision).
 316                              RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect).
 317                              RETURN_UNSUPPORTED  The SMBus operation is not supported.
 318
 319   @return   The 16-bit value returned by the process call command.
 320
 321 **/
 322 UINT16
 323 EFIAPI
 324 S3SmBusProcessCall (
 325   IN  UINTN          SmBusAddress,
 326   IN  UINT16         Value,
 327   OUT RETURN_STATUS  *Status        OPTIONAL
 328   );
 329
 330 /**
 331   Executes an SMBUS read block command, and saves the value in the S3 script to be replayed
 332   on S3 resume.
 333
 334   Executes an SMBUS read block command on the SMBUS device specified by SmBusAddress.
 335   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 336   Bytes are read from the SMBUS and stored in Buffer.
 337   The number of bytes read is returned, and will never return a value larger than 32-bytes.
 338   If Status is not NULL, then the status of the executed command is returned in Status.
 339   It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
 340   SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes.
 341   If Length in SmBusAddress is not zero, then ASSERT().
 342   If Buffer is NULL, then ASSERT().
 343   If any reserved bits of SmBusAddress are set, then ASSERT().
 344
 345   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
 346                              SMBUS Command, SMBUS Data Length, and PEC.
 347   @param[out] Buffer         The pointer to the buffer to store the bytes read from the SMBUS.
 348   @param[out] Status         The return status for the executed command.
 349                              This is an optional parameter and may be NULL.
 350                              RETURN_SUCCESS The SMBUS command was executed.
 351                              RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 352                              RETURN_DEVICE_ERROR  The request was not completed because a failure
 353                              was recorded in the Host Status Register bit.  Device errors are a result
 354                              of a transaction collision, illegal command field, unclaimed cycle
 355                              (host initiated), or bus error (collision).
 356                              RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect).
 357                              RETURN_UNSUPPORTED  The SMBus operation is not supported.
 358
 359   @return   The number of bytes read.
 360
 361 **/
 362 UINTN
 363 EFIAPI
 364 S3SmBusReadBlock (
 365   IN  UINTN          SmBusAddress,
 366   OUT VOID           *Buffer,
 367   OUT RETURN_STATUS  *Status        OPTIONAL
 368   );
 369
 370 /**
 371   Executes an SMBUS write block command, and saves the value in the S3 script to be replayed
 372   on S3 resume.
 373
 374   Executes an SMBUS write block command on the SMBUS device specified by SmBusAddress.
 375   The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required.
 376   Bytes are written to the SMBUS from Buffer.
 377   The number of bytes written is returned, and will never return a value larger than 32-bytes.
 378   If Status is not NULL, then the status of the executed command is returned in Status.
 379   If Length in SmBusAddress is zero or greater than 32, then ASSERT().
 380   If Buffer is NULL, then ASSERT().
 381   If any reserved bits of SmBusAddress are set, then ASSERT().
 382
 383   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
 384                              SMBUS Command, SMBUS Data Length, and PEC.
 385   @param[out] Buffer         The pointer to the buffer to store the bytes read from the SMBUS.
 386   @param[out] Status         The return status for the executed command.
 387                              This is an optional parameter and may be NULL.
 388                              RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 389                              RETURN_DEVICE_ERROR  The request was not completed because a failure
 390                              was recorded in the Host Status Register bit.  Device errors are a result
 391                              of a transaction collision, illegal command field, unclaimed cycle
 392                              (host initiated), or bus error (collision).
 393                              RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect).
 394                              RETURN_UNSUPPORTED  The SMBus operation is not supported.
 395
 396   @return   The number of bytes written.
 397
 398 **/
 399 UINTN
 400 EFIAPI
 401 S3SmBusWriteBlock (
 402   IN  UINTN          SmBusAddress,
 403   OUT VOID           *Buffer,
 404   OUT RETURN_STATUS  *Status        OPTIONAL
 405   );
 406
 407 /**
 408   Executes an SMBUS block process call command, and saves the value in the S3 script to be replayed
 409   on S3 resume.
 410
 411   Executes an SMBUS block process call command on the SMBUS device specified by SmBusAddress.
 412   The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required.
 413   Bytes are written to the SMBUS from WriteBuffer.  Bytes are then read from the SMBUS into ReadBuffer.
 414   If Status is not NULL, then the status of the executed command is returned in Status.
 415   It is the caller's responsibility to make sure ReadBuffer is large enough for the total number of bytes read.
 416   SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes.
 417   If Length in SmBusAddress is zero or greater than 32, then ASSERT().
 418   If WriteBuffer is NULL, then ASSERT().
 419   If ReadBuffer is NULL, then ASSERT().
 420   If any reserved bits of SmBusAddress are set, then ASSERT().
 421
 422   @param[in]  SmBusAddress   The address that encodes the SMBUS Slave Address,
 423                              SMBUS Command, SMBUS Data Length, and PEC.
 424   @param[in]  WriteBuffer    The pointer to the buffer of bytes to write to the SMBUS.
 425   @param[out] ReadBuffer     The pointer to the buffer of bytes to read from the SMBUS.
 426   @param[out] Status         The return status for the executed command.
 427                              This is an optional parameter and may be NULL.
 428                              RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 429                              RETURN_DEVICE_ERROR  The request was not completed because a failure
 430                              was recorded in the Host Status Register bit.  Device errors are a result
 431                              of a transaction collision, illegal command field, unclaimed cycle
 432                              (host initiated), or bus error (collision).
 433                              RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect).
 434                              RETURN_UNSUPPORTED  The SMBus operation is not supported.
 435
 436   @return   The number of bytes written.
 437
 438 **/
 439 UINTN
 440 EFIAPI
 441 S3SmBusBlockProcessCall (
 442   IN  UINTN          SmBusAddress,
 443   IN  VOID           *WriteBuffer,
 444   OUT VOID           *ReadBuffer,
 445   OUT RETURN_STATUS  *Status        OPTIONAL
 446   );
 447
 448 #endif