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