MdePkg/Library/BaseS3PciLib/S3PciLib.c

   1 /** @file
   2   PCI configuration Library Services that do PCI configuration and also enable
   3   the PCI operations to be replayed during an S3 resume. This library class
   4   maps directly on top of the PciLib class.
   5
   6   Copyright (c) 2006 - 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/PciLib.h>
  17 #include <Library/S3PciLib.h>
  18
  19 #define PCILIB_TO_COMMON_ADDRESS(Address) \
  20         ((((UINTN) ((Address>>20) & 0xff)) << 24) + (((UINTN) ((Address>>15) & 0x1f)) << 16) + (((UINTN) ((Address>>12) & 0x07)) << 8) + ((UINTN) (Address & 0xfff )))
  21
  22 /**
  23   Saves a PCI configuration value to the boot script.
  24
  25   This internal worker function saves a PCI configuration value in
  26   the S3 script to be replayed on S3 resume.
  27
  28   If the saving process fails, then ASSERT().
  29
  30   @param  Width   The width of PCI configuration.
  31   @param  Address Address that encodes the PCI Bus, Device, Function and
  32                   Register.
  33   @param  Buffer  The buffer containing value.
  34
  35 **/
  36 VOID
  37 InternalSavePciWriteValueToBootScript (
  38   IN S3_BOOT_SCRIPT_LIB_WIDTH  Width,
  39   IN UINTN                     Address,
  40   IN VOID                      *Buffer
  41   )
  42 {
  43   RETURN_STATUS  Status;
  44
  45   Status = S3BootScriptSavePciCfgWrite (
  46              Width,
  47              PCILIB_TO_COMMON_ADDRESS (Address),
  48              1,
  49              Buffer
  50              );
  51   ASSERT (Status == RETURN_SUCCESS);
  52 }
  53
  54 /**
  55   Saves an 8-bit PCI configuration value to the boot script.
  56
  57   This internal worker function saves an 8-bit PCI configuration value in
  58   the S3 script to be replayed on S3 resume.
  59
  60   If the saving process fails, then ASSERT().
  61
  62   @param  Address Address that encodes the PCI Bus, Device, Function and
  63                   Register.
  64   @param  Value   The value saved to boot script.
  65
  66   @return Value.
  67
  68 **/
  69 UINT8
  70 InternalSavePciWrite8ValueToBootScript (
  71   IN UINTN  Address,
  72   IN UINT8  Value
  73   )
  74 {
  75   InternalSavePciWriteValueToBootScript (S3BootScriptWidthUint8, Address, &Value);
  76
  77   return Value;
  78 }
  79
  80 /**
  81   Reads an 8-bit PCI configuration register and saves the value in the S3
  82   script to be replayed on S3 resume.
  83
  84   Reads and returns the 8-bit PCI configuration register specified by Address.
  85   This function must guarantee that all PCI read and write operations are
  86   serialized.
  87
  88   If Address > 0x0FFFFFFF, then ASSERT().
  89
  90   @param  Address Address that encodes the PCI Bus, Device, Function and
  91                   Register.
  92
  93   @return The read value from the PCI configuration register.
  94
  95 **/
  96 UINT8
  97 EFIAPI
  98 S3PciRead8 (
  99   IN UINTN  Address
 100   )
 101 {
 102   return InternalSavePciWrite8ValueToBootScript (Address, PciRead8 (Address));
 103 }
 104
 105 /**
 106   Writes an 8-bit PCI configuration register and saves the value in the S3
 107   script to be replayed on S3 resume.
 108
 109   Writes the 8-bit PCI configuration register specified by Address with the
 110   value specified by Value. Value is returned. This function must guarantee
 111   that all PCI read and write operations are serialized.
 112
 113   If Address > 0x0FFFFFFF, then ASSERT().
 114
 115   @param  Address Address that encodes the PCI Bus, Device, Function and
 116                   Register.
 117   @param  Value   The value to write.
 118
 119   @return The value written to the PCI configuration register.
 120
 121 **/
 122 UINT8
 123 EFIAPI
 124 S3PciWrite8 (
 125   IN UINTN  Address,
 126   IN UINT8  Value
 127   )
 128 {
 129   return InternalSavePciWrite8ValueToBootScript (Address, PciWrite8 (Address, Value));
 130 }
 131
 132 /**
 133   Performs a bitwise OR of an 8-bit PCI configuration register with
 134   an 8-bit value and saves the value in the S3 script to be replayed on S3 resume.
 135
 136   Reads the 8-bit PCI configuration register specified by Address, performs a
 137   bitwise OR between the read result and the value specified by
 138   OrData, and writes the result to the 8-bit PCI configuration register
 139   specified by Address. The value written to the PCI configuration register is
 140   returned. This function must guarantee that all PCI read and write operations
 141   are serialized.
 142
 143   If Address > 0x0FFFFFFF, then ASSERT().
 144
 145   @param  Address Address that encodes the PCI Bus, Device, Function and
 146                   Register.
 147   @param  OrData  The value to OR with the PCI configuration register.
 148
 149   @return The value written back to the PCI configuration register.
 150
 151 **/
 152 UINT8
 153 EFIAPI
 154 S3PciOr8 (
 155   IN UINTN  Address,
 156   IN UINT8  OrData
 157   )
 158 {
 159   return InternalSavePciWrite8ValueToBootScript (Address, PciOr8 (Address, OrData));
 160 }
 161
 162 /**
 163   Performs a bitwise AND of an 8-bit PCI configuration register with an 8-bit
 164   value and saves the value in the S3 script to be replayed on S3 resume.
 165
 166   Reads the 8-bit PCI configuration register specified by Address, performs a
 167   bitwise AND between the read result and the value specified by AndData, and
 168   writes the result to the 8-bit PCI configuration register specified by
 169   Address. The value written to the PCI configuration register is returned.
 170   This function must guarantee that all PCI read and write operations are
 171   serialized.
 172
 173   If Address > 0x0FFFFFFF, then ASSERT().
 174
 175   @param  Address Address that encodes the PCI Bus, Device, Function and
 176                   Register.
 177   @param  AndData The value to AND with the PCI configuration register.
 178
 179   @return The value written back to the PCI configuration register.
 180
 181 **/
 182 UINT8
 183 EFIAPI
 184 S3PciAnd8 (
 185   IN UINTN  Address,
 186   IN UINT8  AndData
 187   )
 188 {
 189   return InternalSavePciWrite8ValueToBootScript (Address, PciAnd8 (Address, AndData));
 190 }
 191
 192 /**
 193   Performs a bitwise AND of an 8-bit PCI configuration register with an 8-bit
 194   value, followed a  bitwise OR with another 8-bit value and saves
 195   the value in the S3 script to be replayed on S3 resume.
 196
 197   Reads the 8-bit PCI configuration register specified by Address, performs a
 198   bitwise AND between the read result and the value specified by AndData,
 199   performs a bitwise OR between the result of the AND operation and
 200   the value specified by OrData, and writes the result to the 8-bit PCI
 201   configuration register specified by Address. The value written to the PCI
 202   configuration register is returned. This function must guarantee that all PCI
 203   read and write operations are serialized.
 204
 205   If Address > 0x0FFFFFFF, then ASSERT().
 206
 207   @param  Address Address that encodes the PCI Bus, Device, Function and
 208                   Register.
 209   @param  AndData The value to AND with the PCI configuration register.
 210   @param  OrData  The value to OR with the result of the AND operation.
 211
 212   @return The value written back to the PCI configuration register.
 213
 214 **/
 215 UINT8
 216 EFIAPI
 217 S3PciAndThenOr8 (
 218   IN UINTN  Address,
 219   IN UINT8  AndData,
 220   IN UINT8  OrData
 221   )
 222 {
 223   return InternalSavePciWrite8ValueToBootScript (Address, PciAndThenOr8 (Address, AndData, OrData));
 224 }
 225
 226 /**
 227   Reads a bit field of a PCI configuration register and saves the value in
 228   the S3 script to be replayed on S3 resume.
 229
 230   Reads the bit field in an 8-bit PCI configuration register. The bit field is
 231   specified by the StartBit and the EndBit. The value of the bit field is
 232   returned.
 233
 234   If Address > 0x0FFFFFFF, then ASSERT().
 235   If StartBit is greater than 7, then ASSERT().
 236   If EndBit is greater than 7, then ASSERT().
 237   If EndBit is less than StartBit, then ASSERT().
 238
 239   @param  Address   PCI configuration register to read.
 240   @param  StartBit  The ordinal of the least significant bit in the bit field.
 241                     Range 0..7.
 242   @param  EndBit    The ordinal of the most significant bit in the bit field.
 243                     Range 0..7.
 244
 245   @return The value of the bit field read from the PCI configuration register.
 246
 247 **/
 248 UINT8
 249 EFIAPI
 250 S3PciBitFieldRead8 (
 251   IN UINTN  Address,
 252   IN UINTN  StartBit,
 253   IN UINTN  EndBit
 254   )
 255 {
 256   return InternalSavePciWrite8ValueToBootScript (Address, PciBitFieldRead8 (Address, StartBit, EndBit));
 257 }
 258
 259 /**
 260   Writes a bit field to a PCI configuration register and saves the value in
 261   the S3 script to be replayed on S3 resume.
 262
 263   Writes Value to the bit field of the PCI configuration register. The bit
 264   field is specified by the StartBit and the EndBit. All other bits in the
 265   destination PCI configuration register are preserved. The new value of the
 266   8-bit register is returned.
 267
 268   If Address > 0x0FFFFFFF, then ASSERT().
 269   If StartBit is greater than 7, then ASSERT().
 270   If EndBit is greater than 7, then ASSERT().
 271   If EndBit is less than StartBit, then ASSERT().
 272   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 273
 274   @param  Address   PCI configuration register to write.
 275   @param  StartBit  The ordinal of the least significant bit in the bit field.
 276                     Range 0..7.
 277   @param  EndBit    The ordinal of the most significant bit in the bit field.
 278                     Range 0..7.
 279   @param  Value     New value of the bit field.
 280
 281   @return The value written back to the PCI configuration register.
 282
 283 **/
 284 UINT8
 285 EFIAPI
 286 S3PciBitFieldWrite8 (
 287   IN UINTN  Address,
 288   IN UINTN  StartBit,
 289   IN UINTN  EndBit,
 290   IN UINT8  Value
 291   )
 292 {
 293   return InternalSavePciWrite8ValueToBootScript (Address, PciBitFieldWrite8 (Address, StartBit, EndBit, Value));
 294 }
 295
 296 /**
 297   Reads a bit field in an 8-bit PCI configuration, performs a bitwise OR, and
 298   writes the result back to the bit field in the 8-bit port and saves the value
 299   in the S3 script to be replayed on S3 resume.
 300
 301   Reads the 8-bit PCI configuration register specified by Address, performs a
 302   bitwise OR between the read result and the value specified by
 303   OrData, and writes the result to the 8-bit PCI configuration register
 304   specified by Address. The value written to the PCI configuration register is
 305   returned. This function must guarantee that all PCI read and write operations
 306   are serialized. Extra left bits in OrData are stripped.
 307
 308   If Address > 0x0FFFFFFF, then ASSERT().
 309   If StartBit is greater than 7, then ASSERT().
 310   If EndBit is greater than 7, then ASSERT().
 311   If EndBit is less than StartBit, then ASSERT().
 312   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 313
 314   @param  Address   PCI configuration register to write.
 315   @param  StartBit  The ordinal of the least significant bit in the bit field.
 316                     Range 0..7.
 317   @param  EndBit    The ordinal of the most significant bit in the bit field.
 318                     Range 0..7.
 319   @param  OrData    The value to OR with the PCI configuration register.
 320
 321   @return The value written back to the PCI configuration register.
 322
 323 **/
 324 UINT8
 325 EFIAPI
 326 S3PciBitFieldOr8 (
 327   IN UINTN  Address,
 328   IN UINTN  StartBit,
 329   IN UINTN  EndBit,
 330   IN UINT8  OrData
 331   )
 332 {
 333   return InternalSavePciWrite8ValueToBootScript (Address, PciBitFieldOr8 (Address, StartBit, EndBit, OrData));
 334 }
 335
 336 /**
 337   Reads a bit field in an 8-bit PCI configuration register, performs a bitwise
 338   AND, and writes the result back to the bit field in the 8-bit register and
 339   saves the value in the S3 script to be replayed on S3 resume.
 340
 341   Reads the 8-bit PCI configuration register specified by Address, performs a
 342   bitwise AND between the read result and the value specified by AndData, and
 343   writes the result to the 8-bit PCI configuration register specified by
 344   Address. The value written to the PCI configuration register is returned.
 345   This function must guarantee that all PCI read and write operations are
 346   serialized. Extra left bits in AndData are stripped.
 347
 348   If Address > 0x0FFFFFFF, then ASSERT().
 349   If StartBit is greater than 7, then ASSERT().
 350   If EndBit is greater than 7, then ASSERT().
 351   If EndBit is less than StartBit, then ASSERT().
 352   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 353
 354   @param  Address   PCI configuration register to write.
 355   @param  StartBit  The ordinal of the least significant bit in the bit field.
 356                     Range 0..7.
 357   @param  EndBit    The ordinal of the most significant bit in the bit field.
 358                     Range 0..7.
 359   @param  AndData   The value to AND with the PCI configuration register.
 360
 361   @return The value written back to the PCI configuration register.
 362
 363 **/
 364 UINT8
 365 EFIAPI
 366 S3PciBitFieldAnd8 (
 367   IN UINTN  Address,
 368   IN UINTN  StartBit,
 369   IN UINTN  EndBit,
 370   IN UINT8  AndData
 371   )
 372 {
 373   return InternalSavePciWrite8ValueToBootScript (Address, PciBitFieldAnd8 (Address, StartBit, EndBit, AndData));
 374 }
 375
 376 /**
 377   Reads a bit field in an 8-bit Address, performs a bitwise AND followed by a
 378   bitwise OR, and writes the result back to the bit field in the
 379   8-bit port and saves the value in the S3 script to be replayed on S3 resume.
 380
 381   Reads the 8-bit PCI configuration register specified by Address, performs a
 382   bitwise AND followed by a bitwise OR between the read result and
 383   the value specified by AndData, and writes the result to the 8-bit PCI
 384   configuration register specified by Address. The value written to the PCI
 385   configuration register is returned. This function must guarantee that all PCI
 386   read and write operations are serialized. Extra left bits in both AndData and
 387   OrData are stripped.
 388
 389   If Address > 0x0FFFFFFF, then ASSERT().
 390   If StartBit is greater than 7, then ASSERT().
 391   If EndBit is greater than 7, then ASSERT().
 392   If EndBit is less than StartBit, then ASSERT().
 393   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 394   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 395
 396   @param  Address   PCI configuration register to write.
 397   @param  StartBit  The ordinal of the least significant bit in the bit field.
 398                     Range 0..7.
 399   @param  EndBit    The ordinal of the most significant bit in the bit field.
 400                     Range 0..7.
 401   @param  AndData   The value to AND with the PCI configuration register.
 402   @param  OrData    The value to OR with the result of the AND operation.
 403
 404   @return The value written back to the PCI configuration register.
 405
 406 **/
 407 UINT8
 408 EFIAPI
 409 S3PciBitFieldAndThenOr8 (
 410   IN UINTN  Address,
 411   IN UINTN  StartBit,
 412   IN UINTN  EndBit,
 413   IN UINT8  AndData,
 414   IN UINT8  OrData
 415   )
 416 {
 417   return InternalSavePciWrite8ValueToBootScript (Address, PciBitFieldAndThenOr8 (Address, StartBit, EndBit, AndData, OrData));
 418 }
 419
 420 /**
 421   Saves a 16-bit PCI configuration value to the boot script.
 422
 423   This internal worker function saves a 16-bit PCI configuration value in
 424   the S3 script to be replayed on S3 resume.
 425
 426   If the saving process fails, then ASSERT().
 427
 428   @param  Address Address that encodes the PCI Bus, Device, Function and
 429                   Register.
 430   @param  Value   The value to write.
 431
 432   @return Value.
 433
 434 **/
 435 UINT16
 436 InternalSavePciWrite16ValueToBootScript (
 437   IN UINTN   Address,
 438   IN UINT16  Value
 439   )
 440 {
 441   InternalSavePciWriteValueToBootScript (S3BootScriptWidthUint16, Address, &Value);
 442
 443   return Value;
 444 }
 445
 446 /**
 447   Reads a 16-bit PCI configuration register and saves the value in the S3
 448   script to be replayed on S3 resume.
 449
 450   Reads and returns the 16-bit PCI configuration register specified by Address.
 451   This function must guarantee that all PCI read and write operations are
 452   serialized.
 453
 454   If Address > 0x0FFFFFFF, then ASSERT().
 455   If Address is not aligned on a 16-bit boundary, then ASSERT().
 456
 457   @param  Address Address that encodes the PCI Bus, Device, Function and
 458                   Register.
 459
 460   @return The read value from the PCI configuration register.
 461
 462 **/
 463 UINT16
 464 EFIAPI
 465 S3PciRead16 (
 466   IN UINTN  Address
 467   )
 468 {
 469   return InternalSavePciWrite16ValueToBootScript (Address, PciRead16 (Address));
 470 }
 471
 472 /**
 473   Writes a 16-bit PCI configuration register and saves the value in the S3
 474   script to be replayed on S3 resume.
 475
 476   Writes the 16-bit PCI configuration register specified by Address with the
 477   value specified by Value. Value is returned. This function must guarantee
 478   that all PCI read and write operations are serialized.
 479
 480   If Address > 0x0FFFFFFF, then ASSERT().
 481   If Address is not aligned on a 16-bit boundary, then ASSERT().
 482
 483   @param  Address Address that encodes the PCI Bus, Device, Function and
 484                   Register.
 485   @param  Value   The value to write.
 486
 487   @return The value written to the PCI configuration register.
 488
 489 **/
 490 UINT16
 491 EFIAPI
 492 S3PciWrite16 (
 493   IN UINTN   Address,
 494   IN UINT16  Value
 495   )
 496 {
 497   return InternalSavePciWrite16ValueToBootScript (Address, PciWrite16 (Address, Value));
 498 }
 499
 500 /**
 501   Performs a bitwise OR of a 16-bit PCI configuration register with
 502   a 16-bit value and saves the value in the S3 script to be replayed on S3 resume.
 503
 504   Reads the 16-bit PCI configuration register specified by Address, performs a
 505   bitwise OR between the read result and the value specified by
 506   OrData, and writes the result to the 16-bit PCI configuration register
 507   specified by Address. The value written to the PCI configuration register is
 508   returned. This function must guarantee that all PCI read and write operations
 509   are serialized.
 510
 511   If Address > 0x0FFFFFFF, then ASSERT().
 512   If Address is not aligned on a 16-bit boundary, then ASSERT().
 513
 514   @param  Address Address that encodes the PCI Bus, Device, Function and
 515                   Register.
 516   @param  OrData  The value to OR with the PCI configuration register.
 517
 518   @return The value written back to the PCI configuration register.
 519
 520 **/
 521 UINT16
 522 EFIAPI
 523 S3PciOr16 (
 524   IN UINTN   Address,
 525   IN UINT16  OrData
 526   )
 527 {
 528   return InternalSavePciWrite16ValueToBootScript (Address, PciOr16 (Address, OrData));
 529 }
 530
 531 /**
 532   Performs a bitwise AND of a 16-bit PCI configuration register with a 16-bit
 533   value and saves the value in the S3 script to be replayed on S3 resume.
 534
 535   Reads the 16-bit PCI configuration register specified by Address, performs a
 536   bitwise AND between the read result and the value specified by AndData, and
 537   writes the result to the 16-bit PCI configuration register specified by
 538   Address. The value written to the PCI configuration register is returned.
 539   This function must guarantee that all PCI read and write operations are
 540   serialized.
 541
 542   If Address > 0x0FFFFFFF, then ASSERT().
 543   If Address is not aligned on a 16-bit boundary, then ASSERT().
 544
 545   @param  Address Address that encodes the PCI Bus, Device, Function and
 546                   Register.
 547   @param  AndData The value to AND with the PCI configuration register.
 548
 549   @return The value written back to the PCI configuration register.
 550
 551 **/
 552 UINT16
 553 EFIAPI
 554 S3PciAnd16 (
 555   IN UINTN   Address,
 556   IN UINT16  AndData
 557   )
 558 {
 559   return InternalSavePciWrite16ValueToBootScript (Address, PciAnd16 (Address, AndData));
 560 }
 561
 562 /**
 563   Performs a bitwise AND of a 16-bit PCI configuration register with a 16-bit
 564   value, followed a  bitwise OR with another 16-bit value and saves
 565   the value in the S3 script to be replayed on S3 resume.
 566
 567   Reads the 16-bit PCI configuration register specified by Address, performs a
 568   bitwise AND between the read result and the value specified by AndData,
 569   performs a bitwise OR between the result of the AND operation and
 570   the value specified by OrData, and writes the result to the 16-bit PCI
 571   configuration register specified by Address. The value written to the PCI
 572   configuration register is returned. This function must guarantee that all PCI
 573   read and write operations are serialized.
 574
 575   If Address > 0x0FFFFFFF, then ASSERT().
 576   If Address is not aligned on a 16-bit boundary, then ASSERT().
 577
 578   @param  Address Address that encodes the PCI Bus, Device, Function and
 579                   Register.
 580   @param  AndData The value to AND with the PCI configuration register.
 581   @param  OrData  The value to OR with the result of the AND operation.
 582
 583   @return The value written back to the PCI configuration register.
 584
 585 **/
 586 UINT16
 587 EFIAPI
 588 S3PciAndThenOr16 (
 589   IN UINTN   Address,
 590   IN UINT16  AndData,
 591   IN UINT16  OrData
 592   )
 593 {
 594   return InternalSavePciWrite16ValueToBootScript (Address, PciAndThenOr16 (Address, AndData, OrData));
 595 }
 596
 597 /**
 598   Reads a bit field of a PCI configuration register and saves the value in
 599   the S3 script to be replayed on S3 resume.
 600
 601   Reads the bit field in a 16-bit PCI configuration register. The bit field is
 602   specified by the StartBit and the EndBit. The value of the bit field is
 603   returned.
 604
 605   If Address > 0x0FFFFFFF, then ASSERT().
 606   If Address is not aligned on a 16-bit boundary, then ASSERT().
 607   If StartBit is greater than 15, then ASSERT().
 608   If EndBit is greater than 15, then ASSERT().
 609   If EndBit is less than StartBit, then ASSERT().
 610
 611   @param  Address   PCI configuration register to read.
 612   @param  StartBit  The ordinal of the least significant bit in the bit field.
 613                     Range 0..15.
 614   @param  EndBit    The ordinal of the most significant bit in the bit field.
 615                     Range 0..15.
 616
 617   @return The value of the bit field read from the PCI configuration register.
 618
 619 **/
 620 UINT16
 621 EFIAPI
 622 S3PciBitFieldRead16 (
 623   IN UINTN  Address,
 624   IN UINTN  StartBit,
 625   IN UINTN  EndBit
 626   )
 627 {
 628   return InternalSavePciWrite16ValueToBootScript (Address, PciBitFieldRead16 (Address, StartBit, EndBit));
 629 }
 630
 631 /**
 632   Writes a bit field to a PCI configuration register and saves the value in
 633   the S3 script to be replayed on S3 resume.
 634
 635   Writes Value to the bit field of the PCI configuration register. The bit
 636   field is specified by the StartBit and the EndBit. All other bits in the
 637   destination PCI configuration register are preserved. The new value of the
 638   16-bit register is returned.
 639
 640   If Address > 0x0FFFFFFF, then ASSERT().
 641   If Address is not aligned on a 16-bit boundary, then ASSERT().
 642   If StartBit is greater than 15, then ASSERT().
 643   If EndBit is greater than 15, then ASSERT().
 644   If EndBit is less than StartBit, then ASSERT().
 645   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 646
 647   @param  Address   PCI configuration register to write.
 648   @param  StartBit  The ordinal of the least significant bit in the bit field.
 649                     Range 0..15.
 650   @param  EndBit    The ordinal of the most significant bit in the bit field.
 651                     Range 0..15.
 652   @param  Value     New value of the bit field.
 653
 654   @return The value written back to the PCI configuration register.
 655
 656 **/
 657 UINT16
 658 EFIAPI
 659 S3PciBitFieldWrite16 (
 660   IN UINTN   Address,
 661   IN UINTN   StartBit,
 662   IN UINTN   EndBit,
 663   IN UINT16  Value
 664   )
 665 {
 666   return InternalSavePciWrite16ValueToBootScript (Address, PciBitFieldWrite16 (Address, StartBit, EndBit, Value));
 667 }
 668
 669 /**
 670   Reads a bit field in a 16-bit PCI configuration, performs a bitwise OR, and
 671   writes the result back to the bit field in the 16-bit port and saves the value
 672   in the S3 script to be replayed on S3 resume.
 673
 674   Reads the 16-bit PCI configuration register specified by Address, performs a
 675   bitwise OR between the read result and the value specified by
 676   OrData, and writes the result to the 16-bit PCI configuration register
 677   specified by Address. The value written to the PCI configuration register is
 678   returned. This function must guarantee that all PCI read and write operations
 679   are serialized. Extra left bits in OrData are stripped.
 680
 681   If Address > 0x0FFFFFFF, then ASSERT().
 682   If Address is not aligned on a 16-bit boundary, then ASSERT().
 683   If StartBit is greater than 15, then ASSERT().
 684   If EndBit is greater than 15, then ASSERT().
 685   If EndBit is less than StartBit, then ASSERT().
 686   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 687
 688   @param  Address   PCI configuration register to write.
 689   @param  StartBit  The ordinal of the least significant bit in the bit field.
 690                     Range 0..15.
 691   @param  EndBit    The ordinal of the most significant bit in the bit field.
 692                     Range 0..15.
 693   @param  OrData    The value to OR with the PCI configuration register.
 694
 695   @return The value written back to the PCI configuration register.
 696
 697 **/
 698 UINT16
 699 EFIAPI
 700 S3PciBitFieldOr16 (
 701   IN UINTN   Address,
 702   IN UINTN   StartBit,
 703   IN UINTN   EndBit,
 704   IN UINT16  OrData
 705   )
 706 {
 707   return InternalSavePciWrite16ValueToBootScript (Address, PciBitFieldOr16 (Address, StartBit, EndBit, OrData));
 708 }
 709
 710 /**
 711   Reads a bit field in a 16-bit PCI configuration register, performs a bitwise
 712   AND, and writes the result back to the bit field in the 16-bit register and
 713   saves the value in the S3 script to be replayed on S3 resume.
 714
 715   Reads the 16-bit PCI configuration register specified by Address, performs a
 716   bitwise AND between the read result and the value specified by AndData, and
 717   writes the result to the 16-bit PCI configuration register specified by
 718   Address. The value written to the PCI configuration register is returned.
 719   This function must guarantee that all PCI read and write operations are
 720   serialized. Extra left bits in AndData are stripped.
 721
 722   If Address > 0x0FFFFFFF, then ASSERT().
 723   If Address is not aligned on a 16-bit boundary, then ASSERT().
 724   If StartBit is greater than 15, then ASSERT().
 725   If EndBit is greater than 15, then ASSERT().
 726   If EndBit is less than StartBit, then ASSERT().
 727   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 728
 729   @param  Address   PCI configuration register to write.
 730   @param  StartBit  The ordinal of the least significant bit in the bit field.
 731                     Range 0..15.
 732   @param  EndBit    The ordinal of the most significant bit in the bit field.
 733                     Range 0..15.
 734   @param  AndData   The value to AND with the PCI configuration register.
 735
 736   @return The value written back to the PCI configuration register.
 737
 738 **/
 739 UINT16
 740 EFIAPI
 741 S3PciBitFieldAnd16 (
 742   IN UINTN   Address,
 743   IN UINTN   StartBit,
 744   IN UINTN   EndBit,
 745   IN UINT16  AndData
 746   )
 747 {
 748   return InternalSavePciWrite16ValueToBootScript (Address, PciBitFieldAnd16 (Address, StartBit, EndBit, AndData));
 749 }
 750
 751 /**
 752   Reads a bit field in a 16-bit Address, performs a bitwise AND followed by a
 753   bitwise OR, and writes the result back to the bit field in the
 754   16-bit port and saves the value in the S3 script to be replayed on S3 resume.
 755
 756   Reads the 16-bit PCI configuration register specified by Address, performs a
 757   bitwise AND followed by a bitwise OR between the read result and
 758   the value specified by AndData, and writes the result to the 16-bit PCI
 759   configuration register specified by Address. The value written to the PCI
 760   configuration register is returned. This function must guarantee that all PCI
 761   read and write operations are serialized. Extra left bits in both AndData and
 762   OrData are stripped.
 763
 764   If Address > 0x0FFFFFFF, then ASSERT().
 765   If Address is not aligned on a 16-bit boundary, then ASSERT().
 766   If StartBit is greater than 15, then ASSERT().
 767   If EndBit is greater than 15, then ASSERT().
 768   If EndBit is less than StartBit, then ASSERT().
 769   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 770   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 771
 772   @param  Address   PCI configuration register to write.
 773   @param  StartBit  The ordinal of the least significant bit in the bit field.
 774                     Range 0..15.
 775   @param  EndBit    The ordinal of the most significant bit in the bit field.
 776                     Range 0..15.
 777   @param  AndData   The value to AND with the PCI configuration register.
 778   @param  OrData    The value to OR with the result of the AND operation.
 779
 780   @return The value written back to the PCI configuration register.
 781
 782 **/
 783 UINT16
 784 EFIAPI
 785 S3PciBitFieldAndThenOr16 (
 786   IN UINTN   Address,
 787   IN UINTN   StartBit,
 788   IN UINTN   EndBit,
 789   IN UINT16  AndData,
 790   IN UINT16  OrData
 791   )
 792 {
 793   return InternalSavePciWrite16ValueToBootScript (Address, PciBitFieldAndThenOr16 (Address, StartBit, EndBit, AndData, OrData));
 794 }
 795
 796 /**
 797   Saves a 32-bit PCI configuration value to the boot script.
 798
 799   This internal worker function saves a 32-bit PCI configuration value in the S3 script
 800   to be replayed on S3 resume.
 801
 802   If the saving process fails, then ASSERT().
 803
 804   @param  Address Address that encodes the PCI Bus, Device, Function and
 805                   Register.
 806   @param  Value   The value to write.
 807
 808   @return Value.
 809
 810 **/
 811 UINT32
 812 InternalSavePciWrite32ValueToBootScript (
 813   IN UINTN   Address,
 814   IN UINT32  Value
 815   )
 816 {
 817   InternalSavePciWriteValueToBootScript (S3BootScriptWidthUint32, Address, &Value);
 818
 819   return Value;
 820 }
 821
 822 /**
 823   Reads a 32-bit PCI configuration register and saves the value in the S3
 824   script to be replayed on S3 resume.
 825
 826   Reads and returns the 32-bit PCI configuration register specified by Address.
 827   This function must guarantee that all PCI read and write operations are
 828   serialized.
 829
 830   If Address > 0x0FFFFFFF, then ASSERT().
 831   If Address is not aligned on a 32-bit boundary, then ASSERT().
 832
 833   @param  Address Address that encodes the PCI Bus, Device, Function and
 834                   Register.
 835
 836   @return The read value from the PCI configuration register.
 837
 838 **/
 839 UINT32
 840 EFIAPI
 841 S3PciRead32 (
 842   IN UINTN  Address
 843   )
 844 {
 845   return InternalSavePciWrite32ValueToBootScript (Address, PciRead32 (Address));
 846 }
 847
 848 /**
 849   Writes a 32-bit PCI configuration register and saves the value in the S3
 850   script to be replayed on S3 resume.
 851
 852   Writes the 32-bit PCI configuration register specified by Address with the
 853   value specified by Value. Value is returned. This function must guarantee
 854   that all PCI read and write operations are serialized.
 855
 856   If Address > 0x0FFFFFFF, then ASSERT().
 857   If Address is not aligned on a 32-bit boundary, then ASSERT().
 858
 859   @param  Address Address that encodes the PCI Bus, Device, Function and
 860                   Register.
 861   @param  Value   The value to write.
 862
 863   @return The value written to the PCI configuration register.
 864
 865 **/
 866 UINT32
 867 EFIAPI
 868 S3PciWrite32 (
 869   IN UINTN   Address,
 870   IN UINT32  Value
 871   )
 872 {
 873   return InternalSavePciWrite32ValueToBootScript (Address, PciWrite32 (Address, Value));
 874 }
 875
 876 /**
 877   Performs a bitwise OR of a 32-bit PCI configuration register with
 878   a 32-bit value and saves the value in the S3 script to be replayed on S3 resume.
 879
 880   Reads the 32-bit PCI configuration register specified by Address, performs a
 881   bitwise OR between the read result and the value specified by
 882   OrData, and writes the result to the 32-bit PCI configuration register
 883   specified by Address. The value written to the PCI configuration register is
 884   returned. This function must guarantee that all PCI read and write operations
 885   are serialized.
 886
 887   If Address > 0x0FFFFFFF, then ASSERT().
 888   If Address is not aligned on a 32-bit boundary, then ASSERT().
 889
 890   @param  Address Address that encodes the PCI Bus, Device, Function and
 891                   Register.
 892   @param  OrData  The value to OR with the PCI configuration register.
 893
 894   @return The value written back to the PCI configuration register.
 895
 896 **/
 897 UINT32
 898 EFIAPI
 899 S3PciOr32 (
 900   IN UINTN   Address,
 901   IN UINT32  OrData
 902   )
 903 {
 904   return InternalSavePciWrite32ValueToBootScript (Address, PciOr32 (Address, OrData));
 905 }
 906
 907 /**
 908   Performs a bitwise AND of a 32-bit PCI configuration register with a 32-bit
 909   value and saves the value in the S3 script to be replayed on S3 resume.
 910
 911   Reads the 32-bit PCI configuration register specified by Address, performs a
 912   bitwise AND between the read result and the value specified by AndData, and
 913   writes the result to the 32-bit PCI configuration register specified by
 914   Address. The value written to the PCI configuration register is returned.
 915   This function must guarantee that all PCI read and write operations are
 916   serialized.
 917
 918   If Address > 0x0FFFFFFF, then ASSERT().
 919   If Address is not aligned on a 32-bit boundary, then ASSERT().
 920
 921   @param  Address Address that encodes the PCI Bus, Device, Function and
 922                   Register.
 923   @param  AndData The value to AND with the PCI configuration register.
 924
 925   @return The value written back to the PCI configuration register.
 926
 927 **/
 928 UINT32
 929 EFIAPI
 930 S3PciAnd32 (
 931   IN UINTN   Address,
 932   IN UINT32  AndData
 933   )
 934 {
 935   return InternalSavePciWrite32ValueToBootScript (Address, PciAnd32 (Address, AndData));
 936 }
 937
 938 /**
 939   Performs a bitwise AND of a 32-bit PCI configuration register with a 32-bit
 940   value, followed a  bitwise OR with another 32-bit value and saves
 941   the value in the S3 script to be replayed on S3 resume.
 942
 943   Reads the 32-bit PCI configuration register specified by Address, performs a
 944   bitwise AND between the read result and the value specified by AndData,
 945   performs a bitwise OR between the result of the AND operation and
 946   the value specified by OrData, and writes the result to the 32-bit PCI
 947   configuration register specified by Address. The value written to the PCI
 948   configuration register is returned. This function must guarantee that all PCI
 949   read and write operations are serialized.
 950
 951   If Address > 0x0FFFFFFF, then ASSERT().
 952   If Address is not aligned on a 32-bit boundary, then ASSERT().
 953
 954   @param  Address Address that encodes the PCI Bus, Device, Function and
 955                   Register.
 956   @param  AndData The value to AND with the PCI configuration register.
 957   @param  OrData  The value to OR with the result of the AND operation.
 958
 959   @return The value written back to the PCI configuration register.
 960
 961 **/
 962 UINT32
 963 EFIAPI
 964 S3PciAndThenOr32 (
 965   IN UINTN   Address,
 966   IN UINT32  AndData,
 967   IN UINT32  OrData
 968   )
 969 {
 970   return InternalSavePciWrite32ValueToBootScript (Address, PciAndThenOr32 (Address, AndData, OrData));
 971 }
 972
 973 /**
 974   Reads a bit field of a PCI configuration register and saves the value in
 975   the S3 script to be replayed on S3 resume.
 976
 977   Reads the bit field in a 32-bit PCI configuration register. The bit field is
 978   specified by the StartBit and the EndBit. The value of the bit field is
 979   returned.
 980
 981   If Address > 0x0FFFFFFF, then ASSERT().
 982   If Address is not aligned on a 32-bit boundary, then ASSERT().
 983   If StartBit is greater than 31, then ASSERT().
 984   If EndBit is greater than 31, then ASSERT().
 985   If EndBit is less than StartBit, then ASSERT().
 986
 987   @param  Address   PCI configuration register to read.
 988   @param  StartBit  The ordinal of the least significant bit in the bit field.
 989                     Range 0..31.
 990   @param  EndBit    The ordinal of the most significant bit in the bit field.
 991                     Range 0..31.
 992
 993   @return The value of the bit field read from the PCI configuration register.
 994
 995 **/
 996 UINT32
 997 EFIAPI
 998 S3PciBitFieldRead32 (
 999   IN UINTN  Address,
1000   IN UINTN  StartBit,
1001   IN UINTN  EndBit
1002   )
1003 {
1004   return InternalSavePciWrite32ValueToBootScript (Address, PciBitFieldRead32 (Address, StartBit, EndBit));
1005 }
1006
1007 /**
1008   Writes a bit field to a PCI configuration register and saves the value in
1009   the S3 script to be replayed on S3 resume.
1010
1011   Writes Value to the bit field of the PCI configuration register. The bit
1012   field is specified by the StartBit and the EndBit. All other bits in the
1013   destination PCI configuration register are preserved. The new value of the
1014   32-bit register is returned.
1015
1016   If Address > 0x0FFFFFFF, then ASSERT().
1017   If Address is not aligned on a 32-bit boundary, then ASSERT().
1018   If StartBit is greater than 31, then ASSERT().
1019   If EndBit is greater than 31, then ASSERT().
1020   If EndBit is less than StartBit, then ASSERT().
1021   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1022
1023   @param  Address   PCI configuration register to write.
1024   @param  StartBit  The ordinal of the least significant bit in the bit field.
1025                     Range 0..31.
1026   @param  EndBit    The ordinal of the most significant bit in the bit field.
1027                     Range 0..31.
1028   @param  Value     New value of the bit field.
1029
1030   @return The value written back to the PCI configuration register.
1031
1032 **/
1033 UINT32
1034 EFIAPI
1035 S3PciBitFieldWrite32 (
1036   IN UINTN   Address,
1037   IN UINTN   StartBit,
1038   IN UINTN   EndBit,
1039   IN UINT32  Value
1040   )
1041 {
1042   return InternalSavePciWrite32ValueToBootScript (Address, PciBitFieldWrite32 (Address, StartBit, EndBit, Value));
1043 }
1044
1045 /**
1046   Reads a bit field in a 32-bit PCI configuration, performs a bitwise OR, and
1047   writes the result back to the bit field in the 32-bit port and saves the value
1048   in the S3 script to be replayed on S3 resume.
1049
1050   Reads the 32-bit PCI configuration register specified by Address, performs a
1051   bitwise OR between the read result and the value specified by
1052   OrData, and writes the result to the 32-bit PCI configuration register
1053   specified by Address. The value written to the PCI configuration register is
1054   returned. This function must guarantee that all PCI read and write operations
1055   are serialized. Extra left bits in OrData are stripped.
1056
1057   If Address > 0x0FFFFFFF, then ASSERT().
1058   If Address is not aligned on a 32-bit boundary, then ASSERT().
1059   If StartBit is greater than 31, then ASSERT().
1060   If EndBit is greater than 31, then ASSERT().
1061   If EndBit is less than StartBit, then ASSERT().
1062   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1063
1064   @param  Address   PCI configuration register to write.
1065   @param  StartBit  The ordinal of the least significant bit in the bit field.
1066                     Range 0..31.
1067   @param  EndBit    The ordinal of the most significant bit in the bit field.
1068                     Range 0..31.
1069   @param  OrData    The value to OR with the PCI configuration register.
1070
1071   @return The value written back to the PCI configuration register.
1072
1073 **/
1074 UINT32
1075 EFIAPI
1076 S3PciBitFieldOr32 (
1077   IN UINTN   Address,
1078   IN UINTN   StartBit,
1079   IN UINTN   EndBit,
1080   IN UINT32  OrData
1081   )
1082 {
1083   return InternalSavePciWrite32ValueToBootScript (Address, PciBitFieldOr32 (Address, StartBit, EndBit, OrData));
1084 }
1085
1086 /**
1087   Reads a bit field in a 32-bit PCI configuration register, performs a bitwise
1088   AND, and writes the result back to the bit field in the 32-bit register and
1089   saves the value in the S3 script to be replayed on S3 resume.
1090
1091   Reads the 32-bit PCI configuration register specified by Address, performs a
1092   bitwise AND between the read result and the value specified by AndData, and
1093   writes the result to the 32-bit PCI configuration register specified by
1094   Address. The value written to the PCI configuration register is returned.
1095   This function must guarantee that all PCI read and write operations are
1096   serialized. Extra left bits in AndData are stripped.
1097
1098   If Address > 0x0FFFFFFF, then ASSERT().
1099   If Address is not aligned on a 32-bit boundary, then ASSERT().
1100   If StartBit is greater than 31, then ASSERT().
1101   If EndBit is greater than 31, then ASSERT().
1102   If EndBit is less than StartBit, then ASSERT().
1103   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1104
1105   @param  Address   PCI configuration register to write.
1106   @param  StartBit  The ordinal of the least significant bit in the bit field.
1107                     Range 0..31.
1108   @param  EndBit    The ordinal of the most significant bit in the bit field.
1109                     Range 0..31.
1110   @param  AndData   The value to AND with the PCI configuration register.
1111
1112   @return The value written back to the PCI configuration register.
1113
1114 **/
1115 UINT32
1116 EFIAPI
1117 S3PciBitFieldAnd32 (
1118   IN UINTN   Address,
1119   IN UINTN   StartBit,
1120   IN UINTN   EndBit,
1121   IN UINT32  AndData
1122   )
1123 {
1124   return InternalSavePciWrite32ValueToBootScript (Address, PciBitFieldAnd32 (Address, StartBit, EndBit, AndData));
1125 }
1126
1127 /**
1128   Reads a bit field in a 32-bit Address, performs a bitwise AND followed by a
1129   bitwise OR, and writes the result back to the bit field in the
1130   32-bit port and saves the value in the S3 script to be replayed on S3 resume.
1131
1132   Reads the 32-bit PCI configuration register specified by Address, performs a
1133   bitwise AND followed by a bitwise OR between the read result and
1134   the value specified by AndData, and writes the result to the 32-bit PCI
1135   configuration register specified by Address. The value written to the PCI
1136   configuration register is returned. This function must guarantee that all PCI
1137   read and write operations are serialized. Extra left bits in both AndData and
1138   OrData are stripped.
1139
1140   If Address > 0x0FFFFFFF, then ASSERT().
1141   If Address is not aligned on a 32-bit boundary, then ASSERT().
1142   If StartBit is greater than 31, then ASSERT().
1143   If EndBit is greater than 31, then ASSERT().
1144   If EndBit is less than StartBit, then ASSERT().
1145   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1146   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1147
1148   @param  Address   PCI configuration register to write.
1149   @param  StartBit  The ordinal of the least significant bit in the bit field.
1150                     Range 0..31.
1151   @param  EndBit    The ordinal of the most significant bit in the bit field.
1152                     Range 0..31.
1153   @param  AndData   The value to AND with the PCI configuration register.
1154   @param  OrData    The value to OR with the result of the AND operation.
1155
1156   @return The value written back to the PCI configuration register.
1157
1158 **/
1159 UINT32
1160 EFIAPI
1161 S3PciBitFieldAndThenOr32 (
1162   IN UINTN   Address,
1163   IN UINTN   StartBit,
1164   IN UINTN   EndBit,
1165   IN UINT32  AndData,
1166   IN UINT32  OrData
1167   )
1168 {
1169   return InternalSavePciWrite32ValueToBootScript (Address, PciBitFieldAndThenOr32 (Address, StartBit, EndBit, AndData, OrData));
1170 }
1171
1172 /**
1173   Reads a range of PCI configuration registers into a caller supplied buffer
1174   and saves the value in the S3 script to be replayed on S3 resume.
1175
1176   Reads the range of PCI configuration registers specified by StartAddress and
1177   Size into the buffer specified by Buffer. This function only allows the PCI
1178   configuration registers from a single PCI function to be read. Size is
1179   returned. When possible 32-bit PCI configuration read cycles are used to read
1180   from StartAdress to StartAddress + Size. Due to alignment restrictions, 8-bit
1181   and 16-bit PCI configuration read cycles may be used at the beginning and the
1182   end of the range.
1183
1184   If StartAddress > 0x0FFFFFFF, then ASSERT().
1185   If ((StartAddress & 0xFFF) + Size) > 0x1000, then ASSERT().
1186   If Size > 0 and Buffer is NULL, then ASSERT().
1187
1188   @param  StartAddress  Starting address that encodes the PCI Bus, Device,
1189                         Function and Register.
1190   @param  Size          Size in bytes of the transfer.
1191   @param  Buffer        Pointer to a buffer receiving the data read.
1192
1193   @return Size
1194
1195 **/
1196 UINTN
1197 EFIAPI
1198 S3PciReadBuffer (
1199   IN  UINTN  StartAddress,
1200   IN  UINTN  Size,
1201   OUT VOID   *Buffer
1202   )
1203 {
1204   RETURN_STATUS  Status;
1205
1206   Status = S3BootScriptSavePciCfgWrite (
1207              S3BootScriptWidthUint8,
1208              PCILIB_TO_COMMON_ADDRESS (StartAddress),
1209              PciReadBuffer (StartAddress, Size, Buffer),
1210              Buffer
1211              );
1212   ASSERT (Status == RETURN_SUCCESS);
1213
1214   return Size;
1215 }
1216
1217 /**
1218   Copies the data in a caller supplied buffer to a specified range of PCI
1219   configuration space and saves the value in the S3 script to be replayed on S3
1220   resume.
1221
1222   Writes the range of PCI configuration registers specified by StartAddress and
1223   Size from the buffer specified by Buffer. This function only allows the PCI
1224   configuration registers from a single PCI function to be written. Size is
1225   returned. When possible 32-bit PCI configuration write cycles are used to
1226   write from StartAdress to StartAddress + Size. Due to alignment restrictions,
1227   8-bit and 16-bit PCI configuration write cycles may be used at the beginning
1228   and the end of the range.
1229
1230   If StartAddress > 0x0FFFFFFF, then ASSERT().
1231   If ((StartAddress & 0xFFF) + Size) > 0x1000, then ASSERT().
1232   If Size > 0 and Buffer is NULL, then ASSERT().
1233
1234   @param  StartAddress  Starting address that encodes the PCI Bus, Device,
1235                         Function and Register.
1236   @param  Size          Size in bytes of the transfer.
1237   @param  Buffer        Pointer to a buffer containing the data to write.
1238
1239   @return Size
1240
1241 **/
1242 UINTN
1243 EFIAPI
1244 S3PciWriteBuffer (
1245   IN UINTN  StartAddress,
1246   IN UINTN  Size,
1247   IN VOID   *Buffer
1248   )
1249 {
1250   RETURN_STATUS  Status;
1251
1252   Status = S3BootScriptSavePciCfgWrite (
1253              S3BootScriptWidthUint8,
1254              PCILIB_TO_COMMON_ADDRESS (StartAddress),
1255              PciWriteBuffer (StartAddress, Size, Buffer),
1256              Buffer
1257              );
1258   ASSERT (Status == RETURN_SUCCESS);
1259
1260   return Size;
1261 }