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