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