MdePkg/Include/Library/S3PciLib.h

   1 /** @file
   2   The PCI configuration Library Services that carry out PCI configuration and 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 #ifndef __S3_PCI_LIB_H__
  13 #define __S3_PCI_LIB_H__
  14
  15 /**
  16   Macro that converts PCI Bus, PCI Device, PCI Function and PCI Register to an
  17   address that can be passed to the S3 PCI Library functions.
  18
  19   @param  Bus       The PCI Bus number. Range 0..255.
  20   @param  Device    The PCI Device number. Range 0..31.
  21   @param  Function  The PCI Function number. Range 0..7.
  22   @param  Register  The PCI Register number. Range 0..255 for PCI. Range 0..4095
  23                     for PCI Express.
  24
  25   @return The encoded PCI address.
  26
  27 **/
  28 #define S3_PCI_LIB_ADDRESS(Bus, Device, Function, Register)   \
  29   (((Register) & 0xfff) | (((Function) & 0x07) << 12) | (((Device) & 0x1f) << 15) | (((Bus) & 0xff) << 20))
  30
  31 /**
  32
  33   Reads and returns the 8-bit PCI configuration register specified by Address,
  34   and saves the value in the S3 script to be replayed on S3 resume.
  35   This function must guarantee that all PCI read and write operations are
  36   serialized.
  37
  38   If Address > 0x0FFFFFFF, then ASSERT().
  39
  40   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
  41                        Register.
  42
  43   @return   The value read from the PCI configuration register.
  44
  45 **/
  46 UINT8
  47 EFIAPI
  48 S3PciRead8 (
  49   IN UINTN  Address
  50   );
  51
  52 /**
  53   Writes an 8-bit PCI configuration register, and saves the value in the S3
  54   script to be replayed on S3 resume.
  55
  56   Writes the 8-bit PCI configuration register specified by Address with the
  57   value specified by Value. Value is returned. This function must guarantee
  58   that all PCI read and write operations are serialized.
  59
  60   If Address > 0x0FFFFFFF, then ASSERT().
  61
  62   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
  63                        Register.
  64   @param[in] Value     The value to write.
  65
  66   @return   The value written to the PCI configuration register.
  67
  68 **/
  69 UINT8
  70 EFIAPI
  71 S3PciWrite8 (
  72   IN UINTN  Address,
  73   IN UINT8  Value
  74   );
  75
  76 /**
  77   Performs a bitwise OR of an 8-bit PCI configuration register with
  78   an 8-bit value, and saves the value in the S3 script to be replayed on S3 resume.
  79
  80   Reads the 8-bit PCI configuration register specified by Address, performs a
  81   bitwise OR between the read result and the value specified by
  82   OrData, and writes the result to the 8-bit PCI configuration register
  83   specified by Address. The value written to the PCI configuration register is
  84   returned. This function must guarantee that all PCI read and write operations
  85   are serialized.
  86
  87   If Address > 0x0FFFFFFF, then ASSERT().
  88
  89   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
  90                        Register.
  91   @param[in] OrData    The value to OR with the PCI configuration register.
  92
  93   @return   The value written back to the PCI configuration register.
  94
  95 **/
  96 UINT8
  97 EFIAPI
  98 S3PciOr8 (
  99   IN UINTN  Address,
 100   IN UINT8  OrData
 101   );
 102
 103 /**
 104   Performs a bitwise AND of an 8-bit PCI configuration register with an 8-bit
 105   value, and saves the value in the S3 script to be replayed on S3 resume.
 106
 107   Reads the 8-bit PCI configuration register specified by Address, performs a
 108   bitwise AND between the read result and the value specified by AndData, and
 109   writes the result to the 8-bit PCI configuration register specified by
 110   Address. The value written to the PCI configuration register is returned.
 111   This function must guarantee that all PCI read and write operations are
 112   serialized.
 113
 114   If Address > 0x0FFFFFFF, then ASSERT().
 115
 116   @param[in]  Address   The address that encodes the PCI Bus, Device, Function and
 117                         Register.
 118   @param[in]  AndData   The value to AND with the PCI configuration register.
 119
 120   @return   The value written back to the PCI configuration register.
 121
 122 **/
 123 UINT8
 124 EFIAPI
 125 S3PciAnd8 (
 126   IN UINTN  Address,
 127   IN UINT8  AndData
 128   );
 129
 130 /**
 131   Performs a bitwise AND of an 8-bit PCI configuration register with an 8-bit
 132   value, followed a  bitwise OR with another 8-bit value, and saves
 133   the value in the S3 script to be replayed on S3 resume.
 134
 135   Reads the 8-bit PCI configuration register specified by Address, performs a
 136   bitwise AND between the read result and the value specified by AndData,
 137   performs a bitwise OR between the result of the AND operation and
 138   the value specified by OrData, and writes the result to the 8-bit PCI
 139   configuration register specified by Address. The value written to the PCI
 140   configuration register is returned. This function must guarantee that all PCI
 141   read and write operations are serialized.
 142
 143   If Address > 0x0FFFFFFF, then ASSERT().
 144
 145   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 146                        Register.
 147   @param[in] AndData   The value to AND with the PCI configuration register.
 148   @param[in] OrData    The value to OR with the result of the AND operation.
 149
 150   @return   The value written back to the PCI configuration register.
 151
 152 **/
 153 UINT8
 154 EFIAPI
 155 S3PciAndThenOr8 (
 156   IN UINTN  Address,
 157   IN UINT8  AndData,
 158   IN UINT8  OrData
 159   );
 160
 161 /**
 162   Reads a bit field of a PCI configuration register, and saves the value in
 163   the S3 script to be replayed on S3 resume.
 164
 165   Reads the bit field in an 8-bit PCI configuration register. The bit field is
 166   specified by the StartBit and the EndBit. The value of the bit field is
 167   returned.
 168
 169   If Address > 0x0FFFFFFF, then ASSERT().
 170   If StartBit is greater than 7, then ASSERT().
 171   If EndBit is greater than 7, then ASSERT().
 172   If EndBit is less than StartBit, then ASSERT().
 173
 174   @param[in] Address    The PCI configuration register to read.
 175   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 176                         Range 0..7.
 177   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 178                         Range 0..7.
 179
 180   @return   The value of the bit field read from the PCI configuration register.
 181
 182 **/
 183 UINT8
 184 EFIAPI
 185 S3PciBitFieldRead8 (
 186   IN UINTN  Address,
 187   IN UINTN  StartBit,
 188   IN UINTN  EndBit
 189   );
 190
 191 /**
 192   Writes a bit field to a PCI configuration register, and saves the value in
 193   the S3 script to be replayed on S3 resume.
 194
 195   Writes Value to the bit field of the PCI configuration register. The bit
 196   field is specified by the StartBit and the EndBit. All other bits in the
 197   destination PCI configuration register are preserved. The new value of the
 198   8-bit register is returned.
 199
 200   If Address > 0x0FFFFFFF, then ASSERT().
 201   If StartBit is greater than 7, then ASSERT().
 202   If EndBit is greater than 7, then ASSERT().
 203   If EndBit is less than StartBit, then ASSERT().
 204   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 205
 206   @param[in] Address    The PCI configuration register to write.
 207   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 208                         Range 0..7.
 209   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 210                         Range 0..7.
 211   @param[in] Value      New value of the bit field.
 212
 213   @return   The value written back to the PCI configuration register.
 214
 215 **/
 216 UINT8
 217 EFIAPI
 218 S3PciBitFieldWrite8 (
 219   IN UINTN  Address,
 220   IN UINTN  StartBit,
 221   IN UINTN  EndBit,
 222   IN UINT8  Value
 223   );
 224
 225 /**
 226   Reads a bit field in an 8-bit PCI configuration, performs a bitwise OR, and
 227   writes the result back to the bit field in the 8-bit port, and saves the value
 228   in the S3 script to be replayed on S3 resume.
 229
 230   Reads the 8-bit PCI configuration register specified by Address, performs a
 231   bitwise OR between the read result and the value specified by
 232   OrData, and writes the result to the 8-bit PCI configuration register
 233   specified by Address. The value written to the PCI configuration register is
 234   returned. This function must guarantee that all PCI read and write operations
 235   are serialized. Extra left bits in OrData are stripped.
 236
 237   If Address > 0x0FFFFFFF, then ASSERT().
 238   If StartBit is greater than 7, then ASSERT().
 239   If EndBit is greater than 7, then ASSERT().
 240   If EndBit is less than StartBit, then ASSERT().
 241   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 242
 243   @param[in] Address    The PCI configuration register to write.
 244   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 245                         Range 0..7.
 246   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 247                         Range 0..7.
 248   @param[in] OrData     The value to OR with the PCI configuration register.
 249
 250   @return   The value written back to the PCI configuration register.
 251
 252 **/
 253 UINT8
 254 EFIAPI
 255 S3PciBitFieldOr8 (
 256   IN UINTN  Address,
 257   IN UINTN  StartBit,
 258   IN UINTN  EndBit,
 259   IN UINT8  OrData
 260   );
 261
 262 /**
 263   Reads a bit field in an 8-bit PCI configuration register, performs a bitwise
 264   AND, and writes the result back to the bit field in the 8-bit register and
 265   saves the value in the S3 script to be replayed on S3 resume.
 266
 267   Reads the 8-bit PCI configuration register specified by Address, performs a
 268   bitwise AND between the read result and the value specified by AndData, and
 269   writes the result to the 8-bit PCI configuration register specified by
 270   Address. The value written to the PCI configuration register is returned.
 271   This function must guarantee that all PCI read and write operations are
 272   serialized. Extra left bits in AndData are stripped.
 273
 274   If Address > 0x0FFFFFFF, then ASSERT().
 275   If StartBit is greater than 7, then ASSERT().
 276   If EndBit is greater than 7, then ASSERT().
 277   If EndBit is less than StartBit, then ASSERT().
 278   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 279
 280   @param[in] Address    The PCI configuration register to write.
 281   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 282                         Range 0..7.
 283   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 284                         Range 0..7.
 285   @param[in] AndData    The value to AND with the PCI configuration register.
 286
 287   @return   The value written back to the PCI configuration register.
 288
 289 **/
 290 UINT8
 291 EFIAPI
 292 S3PciBitFieldAnd8 (
 293   IN UINTN  Address,
 294   IN UINTN  StartBit,
 295   IN UINTN  EndBit,
 296   IN UINT8  AndData
 297   );
 298
 299 /**
 300   Reads a bit field in an 8-bit Address, performs a bitwise AND followed by a
 301   bitwise OR, and writes the result back to the bit field in the
 302   8-bit port, and saves the value in the S3 script to be replayed on S3 resume.
 303
 304   Reads the 8-bit PCI configuration register specified by Address, performs a
 305   bitwise AND followed by a bitwise OR between the read result and
 306   the value specified by AndData, and writes the result to the 8-bit PCI
 307   configuration register specified by Address. The value written to the PCI
 308   configuration register is returned. This function must guarantee that all PCI
 309   read and write operations are serialized. Extra left bits in both AndData and
 310   OrData are stripped.
 311
 312   If Address > 0x0FFFFFFF, then ASSERT().
 313   If StartBit is greater than 7, then ASSERT().
 314   If EndBit is greater than 7, then ASSERT().
 315   If EndBit is less than StartBit, then ASSERT().
 316   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 317   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 318
 319   @param[in] Address    The PCI configuration register to write.
 320   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 321                         Range 0..7.
 322   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 323                         Range 0..7.
 324   @param[in] AndData    The value to AND with the PCI configuration register.
 325   @param[in] OrData     The value to OR with the result of the AND operation.
 326
 327   @return   The value written back to the PCI configuration register.
 328
 329 **/
 330 UINT8
 331 EFIAPI
 332 S3PciBitFieldAndThenOr8 (
 333   IN UINTN  Address,
 334   IN UINTN  StartBit,
 335   IN UINTN  EndBit,
 336   IN UINT8  AndData,
 337   IN UINT8  OrData
 338   );
 339
 340 /**
 341   Reads a 16-bit PCI configuration register, and saves the value in the S3
 342   script to be replayed on S3 resume.
 343
 344   Reads and returns the 16-bit PCI configuration register specified by Address.
 345   This function must guarantee that all PCI read and write operations are
 346   serialized.
 347
 348   If Address > 0x0FFFFFFF, then ASSERT().
 349   If Address is not aligned on a 16-bit boundary, then ASSERT().
 350
 351   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 352                        Register.
 353
 354   @return   The read value from the PCI configuration register.
 355
 356 **/
 357 UINT16
 358 EFIAPI
 359 S3PciRead16 (
 360   IN UINTN  Address
 361   );
 362
 363 /**
 364   Writes a 16-bit PCI configuration register, and saves the value in the S3
 365   script to be replayed on S3 resume.
 366
 367   Writes the 16-bit PCI configuration register specified by Address with the
 368   value specified by Value. Value is returned. This function must guarantee
 369   that all PCI read and write operations are serialized.
 370
 371   If Address > 0x0FFFFFFF, then ASSERT().
 372   If Address is not aligned on a 16-bit boundary, then ASSERT().
 373
 374   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 375                        Register.
 376   @param[in] Value     The value to write.
 377
 378   @return   The value written to the PCI configuration register.
 379
 380 **/
 381 UINT16
 382 EFIAPI
 383 S3PciWrite16 (
 384   IN UINTN   Address,
 385   IN UINT16  Value
 386   );
 387
 388 /**
 389   Performs a bitwise OR of a 16-bit PCI configuration register with
 390   a 16-bit value, and saves the value in the S3 script to be replayed on S3 resume.
 391
 392   Reads the 16-bit PCI configuration register specified by Address, performs a
 393   bitwise OR between the read result and the value specified by
 394   OrData, and writes the result to the 16-bit PCI configuration register
 395   specified by Address. The value written to the PCI configuration register is
 396   returned. This function must guarantee that all PCI read and write operations
 397   are serialized.
 398
 399   If Address > 0x0FFFFFFF, then ASSERT().
 400   If Address is not aligned on a 16-bit boundary, then ASSERT().
 401
 402   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 403                        Register.
 404   @param[in] OrData    The value to OR with the PCI configuration register.
 405
 406   @return   The value written back to the PCI configuration register.
 407
 408 **/
 409 UINT16
 410 EFIAPI
 411 S3PciOr16 (
 412   IN UINTN   Address,
 413   IN UINT16  OrData
 414   );
 415
 416 /**
 417   Performs a bitwise AND of a 16-bit PCI configuration register with a 16-bit
 418   value, and saves the value in the S3 script to be replayed on S3 resume.
 419
 420   Reads the 16-bit PCI configuration register specified by Address, performs a
 421   bitwise AND between the read result and the value specified by AndData, and
 422   writes the result to the 16-bit PCI configuration register specified by
 423   Address. The value written to the PCI configuration register is returned.
 424   This function must guarantee that all PCI read and write operations are
 425   serialized.
 426
 427   If Address > 0x0FFFFFFF, then ASSERT().
 428   If Address is not aligned on a 16-bit boundary, then ASSERT().
 429
 430   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 431                        Register.
 432   @param[in] AndData   The value to AND with the PCI configuration register.
 433
 434   @return   The value written back to the PCI configuration register.
 435
 436 **/
 437 UINT16
 438 EFIAPI
 439 S3PciAnd16 (
 440   IN UINTN   Address,
 441   IN UINT16  AndData
 442   );
 443
 444 /**
 445   Performs a bitwise AND of a 16-bit PCI configuration register with a 16-bit
 446   value, followed a  bitwise OR with another 16-bit value, and saves
 447   the value in the S3 script to be replayed on S3 resume.
 448
 449   Reads the 16-bit PCI configuration register specified by Address, performs a
 450   bitwise AND between the read result and the value specified by AndData,
 451   performs a bitwise OR between the result of the AND operation and
 452   the value specified by OrData, and writes the result to the 16-bit PCI
 453   configuration register specified by Address. The value written to the PCI
 454   configuration register is returned. This function must guarantee that all PCI
 455   read and write operations are serialized.
 456
 457   If Address > 0x0FFFFFFF, then ASSERT().
 458   If Address is not aligned on a 16-bit boundary, then ASSERT().
 459
 460   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 461                        Register.
 462   @param[in] AndData   The value to AND with the PCI configuration register.
 463   @param[in] OrData    The value to OR with the result of the AND operation.
 464
 465   @return   The value written back to the PCI configuration register.
 466
 467 **/
 468 UINT16
 469 EFIAPI
 470 S3PciAndThenOr16 (
 471   IN UINTN   Address,
 472   IN UINT16  AndData,
 473   IN UINT16  OrData
 474   );
 475
 476 /**
 477   Reads a bit field of a PCI configuration register, and saves the value in
 478   the S3 script to be replayed on S3 resume.
 479
 480   Reads the bit field in a 16-bit PCI configuration register. The bit field is
 481   specified by the StartBit and the EndBit. The value of the bit field is
 482   returned.
 483
 484   If Address > 0x0FFFFFFF, then ASSERT().
 485   If Address is not aligned on a 16-bit boundary, then ASSERT().
 486   If StartBit is greater than 15, then ASSERT().
 487   If EndBit is greater than 15, then ASSERT().
 488   If EndBit is less than StartBit, then ASSERT().
 489
 490   @param[in] Address    The PCI configuration register to read.
 491   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 492                         Range 0..15.
 493   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 494                         Range 0..15.
 495
 496   @return   The value of the bit field read from the PCI configuration register.
 497
 498 **/
 499 UINT16
 500 EFIAPI
 501 S3PciBitFieldRead16 (
 502   IN UINTN  Address,
 503   IN UINTN  StartBit,
 504   IN UINTN  EndBit
 505   );
 506
 507 /**
 508   Writes a bit field to a PCI configuration register, and saves the value in
 509   the S3 script to be replayed on S3 resume.
 510
 511   Writes Value to the bit field of the PCI configuration register. The bit
 512   field is specified by the StartBit and the EndBit. All other bits in the
 513   destination PCI configuration register are preserved. The new value of the
 514   16-bit register is returned.
 515
 516   If Address > 0x0FFFFFFF, then ASSERT().
 517   If Address is not aligned on a 16-bit boundary, then ASSERT().
 518   If StartBit is greater than 15, then ASSERT().
 519   If EndBit is greater than 15, then ASSERT().
 520   If EndBit is less than StartBit, then ASSERT().
 521   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 522
 523   @param[in] Address    The PCI configuration register to write.
 524   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 525                         Range 0..15.
 526   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 527                         Range 0..15.
 528   @param[in] Value      New value of the bit field.
 529
 530   @return   The value written back to the PCI configuration register.
 531
 532 **/
 533 UINT16
 534 EFIAPI
 535 S3PciBitFieldWrite16 (
 536   IN UINTN   Address,
 537   IN UINTN   StartBit,
 538   IN UINTN   EndBit,
 539   IN UINT16  Value
 540   );
 541
 542 /**
 543   Reads a bit field in a 16-bit PCI configuration, performs a bitwise OR, and
 544   writes the result back to the bit field in the 16-bit port, and saves the value
 545   in the S3 script to be replayed on S3 resume.
 546
 547   Reads the 16-bit PCI configuration register specified by Address, performs a
 548   bitwise OR between the read result and the value specified by
 549   OrData, and writes the result to the 16-bit PCI configuration register
 550   specified by Address. The value written to the PCI configuration register is
 551   returned. This function must guarantee that all PCI read and write operations
 552   are serialized. Extra left bits in OrData are stripped.
 553
 554   If Address > 0x0FFFFFFF, then ASSERT().
 555   If Address is not aligned on a 16-bit boundary, then ASSERT().
 556   If StartBit is greater than 15, then ASSERT().
 557   If EndBit is greater than 15, then ASSERT().
 558   If EndBit is less than StartBit, then ASSERT().
 559   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 560
 561   @param[in] Address    The PCI configuration register to write.
 562   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 563                         Range 0..15.
 564   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 565                         Range 0..15.
 566   @param[in] OrData     The value to OR with the PCI configuration register.
 567
 568   @return   The value written back to the PCI configuration register.
 569
 570 **/
 571 UINT16
 572 EFIAPI
 573 S3PciBitFieldOr16 (
 574   IN UINTN   Address,
 575   IN UINTN   StartBit,
 576   IN UINTN   EndBit,
 577   IN UINT16  OrData
 578   );
 579
 580 /**
 581   Reads a bit field in a 16-bit PCI configuration register, performs a bitwise
 582   AND, and writes the result back to the bit field in the 16-bit register and
 583   saves the value in the S3 script to be replayed on S3 resume.
 584
 585   Reads the 16-bit PCI configuration register specified by Address, performs a
 586   bitwise AND between the read result and the value specified by AndData, and
 587   writes the result to the 16-bit PCI configuration register specified by
 588   Address. The value written to the PCI configuration register is returned.
 589   This function must guarantee that all PCI read and write operations are
 590   serialized. Extra left bits in AndData are stripped.
 591
 592   If Address > 0x0FFFFFFF, then ASSERT().
 593   If Address is not aligned on a 16-bit boundary, then ASSERT().
 594   If StartBit is greater than 15, then ASSERT().
 595   If EndBit is greater than 15, then ASSERT().
 596   If EndBit is less than StartBit, then ASSERT().
 597   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 598
 599   @param[in] Address    The PCI configuration register to write.
 600   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 601                         Range 0..15.
 602   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 603                         Range 0..15.
 604   @param[in] AndData    The value to AND with the PCI configuration register.
 605
 606   @return   The value written back to the PCI configuration register.
 607
 608 **/
 609 UINT16
 610 EFIAPI
 611 S3PciBitFieldAnd16 (
 612   IN UINTN   Address,
 613   IN UINTN   StartBit,
 614   IN UINTN   EndBit,
 615   IN UINT16  AndData
 616   );
 617
 618 /**
 619   Reads a bit field in a 16-bit Address, performs a bitwise AND followed by a
 620   bitwise OR, and writes the result back to the bit field in the
 621   16-bit port, and saves the value in the S3 script to be replayed on S3 resume.
 622
 623   Reads the 16-bit PCI configuration register specified by Address, performs a
 624   bitwise AND followed by a bitwise OR between the read result and
 625   the value specified by AndData, and writes the result to the 16-bit PCI
 626   configuration register specified by Address. The value written to the PCI
 627   configuration register is returned. This function must guarantee that all PCI
 628   read and write operations are serialized. Extra left bits in both AndData and
 629   OrData are stripped.
 630
 631   If Address > 0x0FFFFFFF, then ASSERT().
 632   If Address is not aligned on a 16-bit boundary, then ASSERT().
 633   If StartBit is greater than 15, then ASSERT().
 634   If EndBit is greater than 15, then ASSERT().
 635   If EndBit is less than StartBit, then ASSERT().
 636   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 637   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 638
 639   @param[in] Address    The PCI configuration register to write.
 640   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 641                         Range 0..15.
 642   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 643                         Range 0..15.
 644   @param[in] AndData    The value to AND with the PCI configuration register.
 645   @param[in] OrData     The value to OR with the result of the AND operation.
 646
 647   @return   The value written back to the PCI configuration register.
 648
 649 **/
 650 UINT16
 651 EFIAPI
 652 S3PciBitFieldAndThenOr16 (
 653   IN UINTN   Address,
 654   IN UINTN   StartBit,
 655   IN UINTN   EndBit,
 656   IN UINT16  AndData,
 657   IN UINT16  OrData
 658   );
 659
 660 /**
 661   Reads a 32-bit PCI configuration register, and saves the value in the S3
 662   script to be replayed on S3 resume.
 663
 664   Reads and returns the 32-bit PCI configuration register specified by Address.
 665   This function must guarantee that all PCI read and write operations are
 666   serialized.
 667
 668   If Address > 0x0FFFFFFF, then ASSERT().
 669   If Address is not aligned on a 32-bit boundary, then ASSERT().
 670
 671   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 672                        Register.
 673
 674   @return   The read value from the PCI configuration register.
 675
 676 **/
 677 UINT32
 678 EFIAPI
 679 S3PciRead32 (
 680   IN UINTN  Address
 681   );
 682
 683 /**
 684   Writes a 32-bit PCI configuration register, and saves the value in the S3
 685   script to be replayed on S3 resume.
 686
 687   Writes the 32-bit PCI configuration register specified by Address with the
 688   value specified by Value. Value is returned. This function must guarantee
 689   that all PCI read and write operations are serialized.
 690
 691   If Address > 0x0FFFFFFF, then ASSERT().
 692   If Address is not aligned on a 32-bit boundary, then ASSERT().
 693
 694   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 695                        Register.
 696   @param[in] Value     The value to write.
 697
 698   @return   The value written to the PCI configuration register.
 699
 700 **/
 701 UINT32
 702 EFIAPI
 703 S3PciWrite32 (
 704   IN UINTN   Address,
 705   IN UINT32  Value
 706   );
 707
 708 /**
 709   Performs a bitwise OR of a 32-bit PCI configuration register with
 710   a 32-bit value, and saves the value in the S3 script to be replayed on S3 resume.
 711
 712   Reads the 32-bit PCI configuration register specified by Address, performs a
 713   bitwise OR between the read result and the value specified by
 714   OrData, and writes the result to the 32-bit PCI configuration register
 715   specified by Address. The value written to the PCI configuration register is
 716   returned. This function must guarantee that all PCI read and write operations
 717   are serialized.
 718
 719   If Address > 0x0FFFFFFF, then ASSERT().
 720   If Address is not aligned on a 32-bit boundary, then ASSERT().
 721
 722   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 723                        Register.
 724   @param[in] OrData    The value to OR with the PCI configuration register.
 725
 726   @return   The value written back to the PCI configuration register.
 727
 728 **/
 729 UINT32
 730 EFIAPI
 731 S3PciOr32 (
 732   IN UINTN   Address,
 733   IN UINT32  OrData
 734   );
 735
 736 /**
 737   Performs a bitwise AND of a 32-bit PCI configuration register with a 32-bit
 738   value, and saves the value in the S3 script to be replayed on S3 resume.
 739
 740   Reads the 32-bit PCI configuration register specified by Address, performs a
 741   bitwise AND between the read result and the value specified by AndData, and
 742   writes the result to the 32-bit PCI configuration register specified by
 743   Address. The value written to the PCI configuration register is returned.
 744   This function must guarantee that all PCI read and write operations are
 745   serialized.
 746
 747   If Address > 0x0FFFFFFF, then ASSERT().
 748   If Address is not aligned on a 32-bit boundary, then ASSERT().
 749
 750   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 751                        Register.
 752   @param[in] AndData   The value to AND with the PCI configuration register.
 753
 754   @return   The value written back to the PCI configuration register.
 755
 756 **/
 757 UINT32
 758 EFIAPI
 759 S3PciAnd32 (
 760   IN UINTN   Address,
 761   IN UINT32  AndData
 762   );
 763
 764 /**
 765   Performs a bitwise AND of a 32-bit PCI configuration register with a 32-bit
 766   value, followed a  bitwise OR with another 32-bit value, and saves
 767   the value in the S3 script to be replayed on S3 resume.
 768
 769   Reads the 32-bit PCI configuration register specified by Address, performs a
 770   bitwise AND between the read result and the value specified by AndData,
 771   performs a bitwise OR between the result of the AND operation and
 772   the value specified by OrData, and writes the result to the 32-bit PCI
 773   configuration register specified by Address. The value written to the PCI
 774   configuration register is returned. This function must guarantee that all PCI
 775   read and write operations are serialized.
 776
 777   If Address > 0x0FFFFFFF, then ASSERT().
 778   If Address is not aligned on a 32-bit boundary, then ASSERT().
 779
 780   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 781                        Register.
 782   @param[in] AndData   The value to AND with the PCI configuration register.
 783   @param[in] OrData    The value to OR with the result of the AND operation.
 784
 785   @return   The value written back to the PCI configuration register.
 786
 787 **/
 788 UINT32
 789 EFIAPI
 790 S3PciAndThenOr32 (
 791   IN UINTN   Address,
 792   IN UINT32  AndData,
 793   IN UINT32  OrData
 794   );
 795
 796 /**
 797   Reads a bit field of a PCI configuration register, and saves the value in
 798   the S3 script to be replayed on S3 resume.
 799
 800   Reads the bit field in a 32-bit PCI configuration register. The bit field is
 801   specified by the StartBit and the EndBit. The value of the bit field is
 802   returned.
 803
 804   If Address > 0x0FFFFFFF, then ASSERT().
 805   If Address is not aligned on a 32-bit boundary, then ASSERT().
 806   If StartBit is greater than 31, then ASSERT().
 807   If EndBit is greater than 31, then ASSERT().
 808   If EndBit is less than StartBit, then ASSERT().
 809
 810   @param[in] Address    The PCI configuration register to read.
 811   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 812                         Range 0..31.
 813   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 814                         Range 0..31.
 815
 816   @return   The value of the bit field read from the PCI configuration register.
 817
 818 **/
 819 UINT32
 820 EFIAPI
 821 S3PciBitFieldRead32 (
 822   IN UINTN  Address,
 823   IN UINTN  StartBit,
 824   IN UINTN  EndBit
 825   );
 826
 827 /**
 828   Writes a bit field to a PCI configuration register, and saves the value in
 829   the S3 script to be replayed on S3 resume.
 830
 831   Writes Value to the bit field of the PCI configuration register. The bit
 832   field is specified by the StartBit and the EndBit. All other bits in the
 833   destination PCI configuration register are preserved. The new value of the
 834   32-bit register is returned.
 835
 836   If Address > 0x0FFFFFFF, then ASSERT().
 837   If Address is not aligned on a 32-bit boundary, then ASSERT().
 838   If StartBit is greater than 31, then ASSERT().
 839   If EndBit is greater than 31, then ASSERT().
 840   If EndBit is less than StartBit, then ASSERT().
 841   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 842
 843   @param[in] Address    The PCI configuration register to write.
 844   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 845                         Range 0..31.
 846   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 847                         Range 0..31.
 848   @param[in] Value      New value of the bit field.
 849
 850   @return   The value written back to the PCI configuration register.
 851
 852 **/
 853 UINT32
 854 EFIAPI
 855 S3PciBitFieldWrite32 (
 856   IN UINTN   Address,
 857   IN UINTN   StartBit,
 858   IN UINTN   EndBit,
 859   IN UINT32  Value
 860   );
 861
 862 /**
 863   Reads a bit field in a 32-bit PCI configuration, performs a bitwise OR, and
 864   writes the result back to the bit field in the 32-bit port, and saves the value
 865   in the S3 script to be replayed on S3 resume.
 866
 867   Reads the 32-bit PCI configuration register specified by Address, performs a
 868   bitwise OR between the read result and the value specified by
 869   OrData, and writes the result to the 32-bit PCI configuration register
 870   specified by Address. The value written to the PCI configuration register is
 871   returned. This function must guarantee that all PCI read and write operations
 872   are serialized. Extra left bits in OrData are stripped.
 873
 874   If Address > 0x0FFFFFFF, then ASSERT().
 875   If Address is not aligned on a 32-bit boundary, then ASSERT().
 876   If StartBit is greater than 31, then ASSERT().
 877   If EndBit is greater than 31, then ASSERT().
 878   If EndBit is less than StartBit, then ASSERT().
 879   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 880
 881   @param[in] Address    The PCI configuration register to write.
 882   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 883                         Range 0..31.
 884   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 885                         Range 0..31.
 886   @param[in] OrData     The value to OR with the PCI configuration register.
 887
 888   @return   The value written back to the PCI configuration register.
 889
 890 **/
 891 UINT32
 892 EFIAPI
 893 S3PciBitFieldOr32 (
 894   IN UINTN   Address,
 895   IN UINTN   StartBit,
 896   IN UINTN   EndBit,
 897   IN UINT32  OrData
 898   );
 899
 900 /**
 901   Reads a bit field in a 32-bit PCI configuration register, performs a bitwise
 902   AND, and writes the result back to the bit field in the 32-bit register and
 903   saves the value in the S3 script to be replayed on S3 resume.
 904
 905   Reads the 32-bit PCI configuration register specified by Address, performs a
 906   bitwise AND between the read result and the value specified by AndData, and
 907   writes the result to the 32-bit PCI configuration register specified by
 908   Address. The value written to the PCI configuration register is returned.
 909   This function must guarantee that all PCI read and write operations are
 910   serialized. Extra left bits in AndData are stripped.
 911
 912   If Address > 0x0FFFFFFF, then ASSERT().
 913   If Address is not aligned on a 32-bit boundary, then ASSERT().
 914   If StartBit is greater than 31, then ASSERT().
 915   If EndBit is greater than 31, then ASSERT().
 916   If EndBit is less than StartBit, then ASSERT().
 917   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 918
 919   @param[in] Address    The PCI configuration register to write.
 920   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 921                         Range 0..31.
 922   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 923                         Range 0..31.
 924   @param[in] AndData    The value to AND with the PCI configuration register.
 925
 926   @return   The value written back to the PCI configuration register.
 927
 928 **/
 929 UINT32
 930 EFIAPI
 931 S3PciBitFieldAnd32 (
 932   IN UINTN   Address,
 933   IN UINTN   StartBit,
 934   IN UINTN   EndBit,
 935   IN UINT32  AndData
 936   );
 937
 938 /**
 939   Reads a bit field in a 32-bit Address, performs a bitwise AND followed by a
 940   bitwise OR, and writes the result back to the bit field in the
 941   32-bit port, and saves 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 followed by a bitwise OR between the read result and
 945   the value specified by AndData, and writes the result to the 32-bit PCI
 946   configuration register specified by Address. The value written to the PCI
 947   configuration register is returned. This function must guarantee that all PCI
 948   read and write operations are serialized. Extra left bits in both AndData and
 949   OrData are stripped.
 950
 951   If Address > 0x0FFFFFFF, then ASSERT().
 952   If Address is not aligned on a 32-bit boundary, then ASSERT().
 953   If StartBit is greater than 31, then ASSERT().
 954   If EndBit is greater than 31, then ASSERT().
 955   If EndBit is less than StartBit, then ASSERT().
 956   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 957   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 958
 959   @param[in] Address    The PCI configuration register to write.
 960   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 961                         Range 0..31.
 962   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 963                         Range 0..31.
 964   @param[in] AndData    The value to AND with the PCI configuration register.
 965   @param[in] OrData     The value to OR with the result of the AND operation.
 966
 967   @return   The value written back to the PCI configuration register.
 968
 969 **/
 970 UINT32
 971 EFIAPI
 972 S3PciBitFieldAndThenOr32 (
 973   IN UINTN   Address,
 974   IN UINTN   StartBit,
 975   IN UINTN   EndBit,
 976   IN UINT32  AndData,
 977   IN UINT32  OrData
 978   );
 979
 980 /**
 981   Reads a range of PCI configuration registers into a caller supplied buffer,
 982   and saves the value in the S3 script to be replayed on S3 resume.
 983
 984   Reads the range of PCI configuration registers specified by StartAddress and
 985   Size into the buffer specified by Buffer. This function only allows the PCI
 986   configuration registers from a single PCI function to be read. Size is
 987   returned. When possible 32-bit PCI configuration read cycles are used to read
 988   from StartAdress to StartAddress + Size. Due to alignment restrictions, 8-bit
 989   and 16-bit PCI configuration read cycles may be used at the beginning and the
 990   end of the range.
 991
 992   If StartAddress > 0x0FFFFFFF, then ASSERT().
 993   If ((StartAddress & 0xFFF) + Size) > 0x1000, then ASSERT().
 994   If Size > 0 and Buffer is NULL, then ASSERT().
 995
 996   @param[in]  StartAddress   Starting address that encodes the PCI Bus, Device,
 997                              Function and Register.
 998   @param[in]  Size           Size in bytes of the transfer.
 999   @param[out] Buffer         The pointer to a buffer receiving the data read.
1000
1001   @return   Size.
1002
1003 **/
1004 UINTN
1005 EFIAPI
1006 S3PciReadBuffer (
1007   IN  UINTN  StartAddress,
1008   IN  UINTN  Size,
1009   OUT VOID   *Buffer
1010   );
1011
1012 /**
1013   Copies the data in a caller supplied buffer to a specified range of PCI
1014   configuration space, and saves the value in the S3 script to be replayed on S3
1015   resume.
1016
1017   Writes the range of PCI configuration registers specified by StartAddress and
1018   Size from the buffer specified by Buffer. This function only allows the PCI
1019   configuration registers from a single PCI function to be written. Size is
1020   returned. When possible 32-bit PCI configuration write cycles are used to
1021   write from StartAdress to StartAddress + Size. Due to alignment restrictions,
1022   8-bit and 16-bit PCI configuration write cycles may be used at the beginning
1023   and the end of the range.
1024
1025   If StartAddress > 0x0FFFFFFF, then ASSERT().
1026   If ((StartAddress & 0xFFF) + Size) > 0x1000, then ASSERT().
1027   If Size > 0 and Buffer is NULL, then ASSERT().
1028
1029   @param[in] StartAddress   Starting address that encodes the PCI Bus, Device,
1030                             Function and Register.
1031   @param[in] Size           Size in bytes of the transfer.
1032   @param[in] Buffer         The pointer to a buffer containing the data to write.
1033
1034   @return   Size.
1035
1036 **/
1037 UINTN
1038 EFIAPI
1039 S3PciWriteBuffer (
1040   IN UINTN  StartAddress,
1041   IN UINTN  Size,
1042   IN VOID   *Buffer
1043   );
1044
1045 #endif