MdePkg/Library/BaseS3SmbusLib/S3SmbusLib.c

   1 /** @file
   2   Smbus Library Services that do SMBus transactions and also 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
  20 #include <Base.h>
  21
  22 #include <Library/DebugLib.h>
  23 #include <Library/S3BootScriptLib.h>
  24 #include <Library/SmbusLib.h>
  25 #include <Library/S3SmbusLib.h>
  26
  27 /**
  28   Saves an SMBus operation to S3 script to be replayed on S3 resume.
  29
  30   This function provides a standard way to save SMBus operation to S3 boot Script.
  31   The data can either be of the Length byte, word, or a block of data.
  32   If it falis to save S3 boot script, then ASSERT ().
  33
  34   @param  SmbusOperation  Signifies which particular SMBus hardware protocol instance that it will use to
  35                           execute the SMBus transactions.
  36   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
  37                           SMBUS Command, SMBUS Data Length, and PEC.
  38   @param  Length          Signifies the number of bytes that this operation will do. The maximum number of
  39                           bytes can be revision specific and operation specific.
  40   @param  Buffer          Contains the value of data to execute to the SMBus slave device. Not all operations
  41                           require this argument. The length of this buffer is identified by Length.
  42
  43 **/
  44 VOID
  45 InternalSaveSmBusExecToBootScript (
  46   IN     EFI_SMBUS_OPERATION        SmbusOperation,
  47   IN     UINTN                      SmBusAddress,
  48   IN     UINTN                      Length,
  49   IN OUT VOID                       *Buffer
  50   )
  51 {
  52   RETURN_STATUS                Status;
  53
  54   Status = S3BootScriptSaveSmbusExecute (
  55              SmBusAddress,
  56              SmbusOperation,
  57             &Length,
  58              Buffer
  59              );
  60   ASSERT (Status == RETURN_SUCCESS);
  61 }
  62
  63 /**
  64   Executes an SMBUS quick read command and saves the value in the S3 script to be replayed
  65   on S3 resume.
  66
  67   Executes an SMBUS quick read command on the SMBUS device specified by SmBusAddress.
  68   Only the SMBUS slave address field of SmBusAddress is required.
  69   If Status is not NULL, then the status of the executed command is returned in Status.
  70   If PEC is set in SmBusAddress, then ASSERT().
  71   If Command in SmBusAddress is not zero, then ASSERT().
  72   If Length in SmBusAddress is not zero, then ASSERT().
  73   If any reserved bits of SmBusAddress are set, then ASSERT().
  74
  75   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
  76                           SMBUS Command, SMBUS Data Length, and PEC.
  77   @param  Status          Return status for the executed command.
  78                           This is an optional parameter and may be NULL.
  79
  80 **/
  81 VOID
  82 EFIAPI
  83 S3SmBusQuickRead (
  84   IN  UINTN                     SmBusAddress,
  85   OUT RETURN_STATUS             *Status       OPTIONAL
  86   )
  87 {
  88   SmBusQuickRead (SmBusAddress, Status);
  89
  90   InternalSaveSmBusExecToBootScript (EfiSmbusQuickRead, SmBusAddress, 0, NULL);
  91 }
  92
  93 /**
  94   Executes an SMBUS quick write command and saves the value in the S3 script to be replayed
  95   on S3 resume.
  96
  97   Executes an SMBUS quick write command on the SMBUS device specified by SmBusAddress.
  98   Only the SMBUS slave address field of SmBusAddress is required.
  99   If Status is not NULL, then the status of the executed command is returned in Status.
 100   If PEC is set in SmBusAddress, then ASSERT().
 101   If Command in SmBusAddress is not zero, then ASSERT().
 102   If Length in SmBusAddress is not zero, then ASSERT().
 103   If any reserved bits of SmBusAddress are set, then ASSERT().
 104
 105   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 106                           SMBUS Command, SMBUS Data Length, and PEC.
 107   @param  Status          Return status for the executed command.
 108                           This is an optional parameter and may be NULL.
 109
 110 **/
 111 VOID
 112 EFIAPI
 113 S3SmBusQuickWrite (
 114   IN  UINTN                     SmBusAddress,
 115   OUT RETURN_STATUS             *Status       OPTIONAL
 116   )
 117 {
 118   SmBusQuickWrite (SmBusAddress, Status);
 119
 120   InternalSaveSmBusExecToBootScript (EfiSmbusQuickWrite, SmBusAddress, 0, NULL);
 121 }
 122
 123 /**
 124   Executes an SMBUS receive byte command and saves the value in the S3 script to be replayed
 125   on S3 resume.
 126
 127   Executes an SMBUS receive byte command on the SMBUS device specified by SmBusAddress.
 128   Only the SMBUS slave address field of SmBusAddress is required.
 129   The byte received from the SMBUS is returned.
 130   If Status is not NULL, then the status of the executed command is returned in Status.
 131   If Command in SmBusAddress is not zero, then ASSERT().
 132   If Length in SmBusAddress is not zero, then ASSERT().
 133   If any reserved bits of SmBusAddress are set, then ASSERT().
 134
 135   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 136                           SMBUS Command, SMBUS Data Length, and PEC.
 137   @param  Status          Return status for the executed command.
 138                           This is an optional parameter and may be NULL.
 139
 140   @return The byte received from the SMBUS.
 141
 142 **/
 143 UINT8
 144 EFIAPI
 145 S3SmBusReceiveByte (
 146   IN  UINTN          SmBusAddress,
 147   OUT RETURN_STATUS  *Status        OPTIONAL
 148   )
 149 {
 150   UINT8   Byte;
 151
 152   Byte = SmBusReceiveByte (SmBusAddress, Status);
 153
 154   InternalSaveSmBusExecToBootScript (EfiSmbusReceiveByte, SmBusAddress, 1, &Byte);
 155
 156   return Byte;
 157 }
 158
 159 /**
 160   Executes an SMBUS send byte command and saves the value in the S3 script to be replayed
 161   on S3 resume.
 162
 163   Executes an SMBUS send byte command on the SMBUS device specified by SmBusAddress.
 164   The byte specified by Value is sent.
 165   Only the SMBUS slave address field of SmBusAddress is required.  Value is returned.
 166   If Status is not NULL, then the status of the executed command is returned in Status.
 167   If Command in SmBusAddress is not zero, then ASSERT().
 168   If Length in SmBusAddress is not zero, then ASSERT().
 169   If any reserved bits of SmBusAddress are set, then ASSERT().
 170
 171   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 172                           SMBUS Command, SMBUS Data Length, and PEC.
 173   @param  Value           The 8-bit value to send.
 174   @param  Status          Return status for the executed command.
 175                           This is an optional parameter and may be NULL.
 176
 177   @return The parameter of Value.
 178
 179 **/
 180 UINT8
 181 EFIAPI
 182 S3SmBusSendByte (
 183   IN  UINTN          SmBusAddress,
 184   IN  UINT8          Value,
 185   OUT RETURN_STATUS  *Status        OPTIONAL
 186   )
 187 {
 188   UINT8   Byte;
 189
 190   Byte = SmBusSendByte (SmBusAddress, Value, Status);
 191
 192   InternalSaveSmBusExecToBootScript (EfiSmbusSendByte, SmBusAddress, 1, &Byte);
 193
 194   return Byte;
 195 }
 196
 197 /**
 198   Executes an SMBUS read data byte command and saves the value in the S3 script to be replayed
 199   on S3 resume.
 200
 201   Executes an SMBUS read data byte command on the SMBUS device specified by SmBusAddress.
 202   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 203   The 8-bit value read from the SMBUS is returned.
 204   If Status is not NULL, then the status of the executed command is returned in Status.
 205   If Length in SmBusAddress is not zero, then ASSERT().
 206   If any reserved bits of SmBusAddress are set, then ASSERT().
 207
 208   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 209                           SMBUS Command, SMBUS Data Length, and PEC.
 210   @param  Status          Return status for the executed command.
 211                           This is an optional parameter and may be NULL.
 212
 213   @return The byte read from the SMBUS.
 214
 215 **/
 216 UINT8
 217 EFIAPI
 218 S3SmBusReadDataByte (
 219   IN  UINTN          SmBusAddress,
 220   OUT RETURN_STATUS  *Status        OPTIONAL
 221   )
 222 {
 223   UINT8   Byte;
 224
 225   Byte = SmBusReadDataByte (SmBusAddress, Status);
 226
 227   InternalSaveSmBusExecToBootScript (EfiSmbusReadByte, SmBusAddress, 1, &Byte);
 228
 229   return Byte;
 230 }
 231
 232 /**
 233   Executes an SMBUS write data byte command and saves the value in the S3 script to be replayed
 234   on S3 resume.
 235
 236   Executes an SMBUS write data byte command on the SMBUS device specified by SmBusAddress.
 237   The 8-bit value specified by Value is written.
 238   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 239   Value is returned.
 240   If Status is not NULL, then the status of the executed command is returned in Status.
 241   If Length in SmBusAddress is not zero, then ASSERT().
 242   If any reserved bits of SmBusAddress are set, then ASSERT().
 243
 244   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 245                           SMBUS Command, SMBUS Data Length, and PEC.
 246   @param  Value           The 8-bit value to write.
 247   @param  Status          Return status for the executed command.
 248                           This is an optional parameter and may be NULL.
 249
 250   @return The parameter of Value.
 251
 252 **/
 253 UINT8
 254 EFIAPI
 255 S3SmBusWriteDataByte (
 256   IN  UINTN          SmBusAddress,
 257   IN  UINT8          Value,
 258   OUT RETURN_STATUS  *Status        OPTIONAL
 259   )
 260 {
 261   UINT8   Byte;
 262
 263   Byte = SmBusWriteDataByte (SmBusAddress, Value, Status);
 264
 265   InternalSaveSmBusExecToBootScript (EfiSmbusWriteByte, SmBusAddress, 1, &Byte);
 266
 267   return Byte;
 268 }
 269
 270 /**
 271   Executes an SMBUS read data word command and saves the value in the S3 script to be replayed
 272   on S3 resume.
 273
 274   Executes an SMBUS read data word command on the SMBUS device specified by SmBusAddress.
 275   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 276   The 16-bit value read from the SMBUS is returned.
 277   If Status is not NULL, then the status of the executed command is returned in Status.
 278   If Length in SmBusAddress is not zero, then ASSERT().
 279   If any reserved bits of SmBusAddress are set, then ASSERT().
 280
 281   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 282                           SMBUS Command, SMBUS Data Length, and PEC.
 283   @param  Status          Return status for the executed command.
 284                           This is an optional parameter and may be NULL.
 285
 286   @return The byte read from the SMBUS.
 287
 288 **/
 289 UINT16
 290 EFIAPI
 291 S3SmBusReadDataWord (
 292   IN  UINTN          SmBusAddress,
 293   OUT RETURN_STATUS  *Status        OPTIONAL
 294   )
 295 {
 296   UINT16  Word;
 297
 298   Word = SmBusReadDataWord (SmBusAddress, Status);
 299
 300   InternalSaveSmBusExecToBootScript (EfiSmbusReadWord, SmBusAddress, 2, &Word);
 301
 302   return Word;
 303 }
 304
 305 /**
 306   Executes an SMBUS write data word command and saves the value in the S3 script to be replayed
 307   on S3 resume.
 308
 309   Executes an SMBUS write data word command on the SMBUS device specified by SmBusAddress.
 310   The 16-bit value specified by Value is written.
 311   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 312   Value is returned.
 313   If Status is not NULL, then the status of the executed command is returned in Status.
 314   If Length in SmBusAddress is not zero, then ASSERT().
 315   If any reserved bits of SmBusAddress are set, then ASSERT().
 316
 317   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 318                           SMBUS Command, SMBUS Data Length, and PEC.
 319   @param  Value           The 16-bit value to write.
 320   @param  Status          Return status for the executed command.
 321                           This is an optional parameter and may be NULL.
 322
 323   @return The parameter of Value.
 324
 325 **/
 326 UINT16
 327 EFIAPI
 328 S3SmBusWriteDataWord (
 329   IN  UINTN          SmBusAddress,
 330   IN  UINT16         Value,
 331   OUT RETURN_STATUS  *Status        OPTIONAL
 332   )
 333 {
 334   UINT16  Word;
 335
 336   Word = SmBusWriteDataWord (SmBusAddress, Value, Status);
 337
 338   InternalSaveSmBusExecToBootScript (EfiSmbusWriteWord, SmBusAddress, 2, &Word);
 339
 340   return Word;
 341 }
 342
 343 /**
 344   Executes an SMBUS process call command and saves the value in the S3 script to be replayed
 345   on S3 resume.
 346
 347   Executes an SMBUS process call command on the SMBUS device specified by SmBusAddress.
 348   The 16-bit value specified by Value is written.
 349   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 350   The 16-bit value returned by the process call command is returned.
 351   If Status is not NULL, then the status of the executed command is returned in Status.
 352   If Length in SmBusAddress is not zero, then ASSERT().
 353   If any reserved bits of SmBusAddress are set, then ASSERT().
 354
 355   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 356                           SMBUS Command, SMBUS Data Length, and PEC.
 357   @param  Value           The 16-bit value to write.
 358   @param  Status          Return status for the executed command.
 359                           This is an optional parameter and may be NULL.
 360
 361   @return The 16-bit value returned by the process call command.
 362
 363 **/
 364 UINT16
 365 EFIAPI
 366 S3SmBusProcessCall (
 367   IN  UINTN          SmBusAddress,
 368   IN  UINT16         Value,
 369   OUT RETURN_STATUS  *Status        OPTIONAL
 370   )
 371 {
 372   UINT16  Word;
 373
 374   Word = SmBusProcessCall (SmBusAddress, Value, Status);
 375
 376   InternalSaveSmBusExecToBootScript (EfiSmbusProcessCall, SmBusAddress, 2, &Value);
 377
 378   return Word;
 379 }
 380
 381 /**
 382   Executes an SMBUS read block command and saves the value in the S3 script to be replayed
 383   on S3 resume.
 384
 385   Executes an SMBUS read block command on the SMBUS device specified by SmBusAddress.
 386   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 387   Bytes are read from the SMBUS and stored in Buffer.
 388   The number of bytes read is returned, and will never return a value larger than 32-bytes.
 389   If Status is not NULL, then the status of the executed command is returned in Status.
 390   It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
 391   SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes.
 392   If Length in SmBusAddress is not zero, then ASSERT().
 393   If Buffer is NULL, then ASSERT().
 394   If any reserved bits of SmBusAddress are set, then ASSERT().
 395
 396   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 397                           SMBUS Command, SMBUS Data Length, and PEC.
 398   @param  Buffer          Pointer to the buffer to store the bytes read from the SMBUS.
 399   @param  Status          Return status for the executed command.
 400                           This is an optional parameter and may be NULL.
 401
 402   @return The number of bytes read.
 403
 404 **/
 405 UINTN
 406 EFIAPI
 407 S3SmBusReadBlock (
 408   IN  UINTN          SmBusAddress,
 409   OUT VOID           *Buffer,
 410   OUT RETURN_STATUS  *Status        OPTIONAL
 411   )
 412 {
 413   UINTN   Length;
 414
 415   Length = SmBusReadBlock (SmBusAddress, Buffer, Status);
 416
 417   InternalSaveSmBusExecToBootScript (EfiSmbusReadBlock, SmBusAddress, Length, Buffer);
 418
 419   return Length;
 420 }
 421
 422 /**
 423   Executes an SMBUS write block command and saves the value in the S3 script to be replayed
 424   on S3 resume.
 425
 426   Executes an SMBUS write block command on the SMBUS device specified by SmBusAddress.
 427   The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required.
 428   Bytes are written to the SMBUS from Buffer.
 429   The number of bytes written is returned, and will never return a value larger than 32-bytes.
 430   If Status is not NULL, then the status of the executed command is returned in Status.
 431   If Length in SmBusAddress is zero or greater than 32, then ASSERT().
 432   If Buffer is NULL, then ASSERT().
 433   If any reserved bits of SmBusAddress are set, then ASSERT().
 434
 435   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 436                           SMBUS Command, SMBUS Data Length, and PEC.
 437   @param  Buffer          Pointer to the buffer to store the bytes read from the SMBUS.
 438   @param  Status          Return status for the executed command.
 439                           This is an optional parameter and may be NULL.
 440
 441   @return The number of bytes written.
 442
 443 **/
 444 UINTN
 445 EFIAPI
 446 S3SmBusWriteBlock (
 447   IN  UINTN          SmBusAddress,
 448   OUT VOID           *Buffer,
 449   OUT RETURN_STATUS  *Status        OPTIONAL
 450   )
 451 {
 452   UINTN  Length;
 453
 454   Length = SmBusWriteBlock (SmBusAddress, Buffer, Status);
 455
 456   InternalSaveSmBusExecToBootScript (EfiSmbusWriteBlock, SmBusAddress, SMBUS_LIB_LENGTH (SmBusAddress), Buffer);
 457
 458   return Length;
 459 }
 460
 461 /**
 462   Executes an SMBUS block process call command and saves the value in the S3 script to be replayed
 463   on S3 resume.
 464
 465   Executes an SMBUS block process call command on the SMBUS device specified by SmBusAddress.
 466   The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required.
 467   Bytes are written to the SMBUS from WriteBuffer.  Bytes are then read from the SMBUS into ReadBuffer.
 468   If Status is not NULL, then the status of the executed command is returned in Status.
 469   It is the caller's responsibility to make sure ReadBuffer is large enough for the total number of bytes read.
 470   SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes.
 471   If Length in SmBusAddress is zero or greater than 32, then ASSERT().
 472   If WriteBuffer is NULL, then ASSERT().
 473   If ReadBuffer is NULL, then ASSERT().
 474   If any reserved bits of SmBusAddress are set, then ASSERT().
 475
 476   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 477                           SMBUS Command, SMBUS Data Length, and PEC.
 478   @param  WriteBuffer     Pointer to the buffer of bytes to write to the SMBUS.
 479   @param  ReadBuffer      Pointer to the buffer of bytes to read from the SMBUS.
 480   @param  Status          Return status for the executed command.
 481                           This is an optional parameter and may be NULL.
 482
 483   @return The number of bytes written.
 484
 485 **/
 486 UINTN
 487 EFIAPI
 488 S3SmBusBlockProcessCall (
 489   IN  UINTN          SmBusAddress,
 490   IN  VOID           *WriteBuffer,
 491   OUT VOID           *ReadBuffer,
 492   OUT RETURN_STATUS  *Status        OPTIONAL
 493   )
 494 {
 495   UINTN   Length;
 496
 497   Length = SmBusBlockProcessCall (SmBusAddress, WriteBuffer, ReadBuffer, Status);
 498
 499   InternalSaveSmBusExecToBootScript (EfiSmbusBWBRProcessCall, SmBusAddress, SMBUS_LIB_LENGTH (SmBusAddress), ReadBuffer);
 500
 501   return Length;
 502 }