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 - 2010, 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
 212   @param[in] Address    The PCI configuration register to write.
 213   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 214                         Range 0..7.
 215   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 216                         Range 0..7.
 217   @param[in] Value      New value of the bit field.
 218
 219   @return   The value written back to the PCI configuration register.
 220
 221 **/
 222 UINT8
 223 EFIAPI
 224 S3PciBitFieldWrite8 (
 225   IN UINTN  Address,
 226   IN UINTN  StartBit,
 227   IN UINTN  EndBit,
 228   IN UINT8  Value
 229   );
 230
 231 /**
 232   Reads a bit field in an 8-bit PCI configuration, performs a bitwise OR, and
 233   writes the result back to the bit field in the 8-bit port, and saves the value
 234   in the S3 script to be replayed on S3 resume.
 235
 236   Reads the 8-bit PCI configuration register specified by Address, performs a
 237   bitwise OR between the read result and the value specified by
 238   OrData, and writes the result to the 8-bit PCI configuration register
 239   specified by Address. The value written to the PCI configuration register is
 240   returned. This function must guarantee that all PCI read and write operations
 241   are serialized. Extra left bits in OrData are stripped.
 242
 243   If Address > 0x0FFFFFFF, then ASSERT().
 244   If StartBit is greater than 7, then ASSERT().
 245   If EndBit is greater than 7, then ASSERT().
 246   If EndBit is less than StartBit, then ASSERT().
 247
 248   @param[in] Address    The PCI configuration register to write.
 249   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 250                         Range 0..7.
 251   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 252                         Range 0..7.
 253   @param[in] OrData     The value to OR with the PCI configuration register.
 254
 255   @return   The value written back to the PCI configuration register.
 256
 257 **/
 258 UINT8
 259 EFIAPI
 260 S3PciBitFieldOr8 (
 261   IN UINTN  Address,
 262   IN UINTN  StartBit,
 263   IN UINTN  EndBit,
 264   IN UINT8  OrData
 265   );
 266
 267 /**
 268   Reads a bit field in an 8-bit PCI configuration register, performs a bitwise
 269   AND, and writes the result back to the bit field in the 8-bit register and
 270   saves the value in the S3 script to be replayed on S3 resume.
 271
 272   Reads the 8-bit PCI configuration register specified by Address, performs a
 273   bitwise AND between the read result and the value specified by AndData, and
 274   writes the result to the 8-bit PCI configuration register specified by
 275   Address. The value written to the PCI configuration register is returned.
 276   This function must guarantee that all PCI read and write operations are
 277   serialized. Extra left bits in AndData are stripped.
 278
 279   If Address > 0x0FFFFFFF, then ASSERT().
 280   If StartBit is greater than 7, then ASSERT().
 281   If EndBit is greater than 7, then ASSERT().
 282   If EndBit is less than StartBit, then ASSERT().
 283
 284   @param[in] Address    The PCI configuration register to write.
 285   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 286                         Range 0..7.
 287   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 288                         Range 0..7.
 289   @param[in] AndData    The value to AND with the PCI configuration register.
 290
 291   @return   The value written back to the PCI configuration register.
 292
 293 **/
 294 UINT8
 295 EFIAPI
 296 S3PciBitFieldAnd8 (
 297   IN UINTN  Address,
 298   IN UINTN  StartBit,
 299   IN UINTN  EndBit,
 300   IN UINT8  AndData
 301   );
 302
 303 /**
 304   Reads a bit field in an 8-bit Address, performs a bitwise AND followed by a
 305   bitwise OR, and writes the result back to the bit field in the
 306   8-bit port, and saves the value in the S3 script to be replayed on S3 resume.
 307
 308   Reads the 8-bit PCI configuration register specified by Address, performs a
 309   bitwise AND followed by a bitwise OR between the read result and
 310   the value specified by AndData, and writes the result to the 8-bit PCI
 311   configuration register specified by Address. The value written to the PCI
 312   configuration register is returned. This function must guarantee that all PCI
 313   read and write operations are serialized. Extra left bits in both AndData and
 314   OrData are stripped.
 315
 316   If Address > 0x0FFFFFFF, then ASSERT().
 317   If StartBit is greater than 7, then ASSERT().
 318   If EndBit is greater than 7, then ASSERT().
 319   If EndBit is less than StartBit, then ASSERT().
 320
 321   @param[in] Address    The PCI configuration register to write.
 322   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 323                         Range 0..7.
 324   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 325                         Range 0..7.
 326   @param[in] AndData    The value to AND with the PCI configuration register.
 327   @param[in] OrData     The value to OR with the result of the AND operation.
 328
 329   @return   The value written back to the PCI configuration register.
 330
 331 **/
 332 UINT8
 333 EFIAPI
 334 S3PciBitFieldAndThenOr8 (
 335   IN UINTN  Address,
 336   IN UINTN  StartBit,
 337   IN UINTN  EndBit,
 338   IN UINT8  AndData,
 339   IN UINT8  OrData
 340   );
 341
 342 /**
 343   Reads a 16-bit PCI configuration register, and saves the value in the S3
 344   script to be replayed on S3 resume.
 345
 346   Reads and returns the 16-bit PCI configuration register specified by Address.
 347   This function must guarantee that all PCI read and write operations are
 348   serialized.
 349
 350   If Address > 0x0FFFFFFF, then ASSERT().
 351   If Address is not aligned on a 16-bit boundary, then ASSERT().
 352
 353   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 354                        Register.
 355
 356   @return   The read value from the PCI configuration register.
 357
 358 **/
 359 UINT16
 360 EFIAPI
 361 S3PciRead16 (
 362   IN UINTN  Address
 363   );
 364
 365 /**
 366   Writes a 16-bit PCI configuration register, and saves the value in the S3
 367   script to be replayed on S3 resume.
 368
 369   Writes the 16-bit PCI configuration register specified by Address with the
 370   value specified by Value. Value is returned. This function must guarantee
 371   that all PCI read and write operations are serialized.
 372
 373   If Address > 0x0FFFFFFF, then ASSERT().
 374   If Address is not aligned on a 16-bit boundary, then ASSERT().
 375
 376   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 377                        Register.
 378   @param[in] Value     The value to write.
 379
 380   @return   The value written to the PCI configuration register.
 381
 382 **/
 383 UINT16
 384 EFIAPI
 385 S3PciWrite16 (
 386   IN UINTN   Address,
 387   IN UINT16  Value
 388   );
 389
 390 /**
 391   Performs a bitwise OR of a 16-bit PCI configuration register with
 392   a 16-bit value, and saves the value in the S3 script to be replayed on S3 resume.
 393
 394   Reads the 16-bit PCI configuration register specified by Address, performs a
 395   bitwise OR between the read result and the value specified by
 396   OrData, and writes the result to the 16-bit PCI configuration register
 397   specified by Address. The value written to the PCI configuration register is
 398   returned. This function must guarantee that all PCI read and write operations
 399   are serialized.
 400
 401   If Address > 0x0FFFFFFF, then ASSERT().
 402   If Address is not aligned on a 16-bit boundary, then ASSERT().
 403
 404   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 405                        Register.
 406   @param[in] OrData    The value to OR with the PCI configuration register.
 407
 408   @return   The value written back to the PCI configuration register.
 409
 410 **/
 411 UINT16
 412 EFIAPI
 413 S3PciOr16 (
 414   IN UINTN   Address,
 415   IN UINT16  OrData
 416   );
 417
 418 /**
 419   Performs a bitwise AND of a 16-bit PCI configuration register with a 16-bit
 420   value, and saves the value in the S3 script to be replayed on S3 resume.
 421
 422   Reads the 16-bit PCI configuration register specified by Address, performs a
 423   bitwise AND between the read result and the value specified by AndData, and
 424   writes the result to the 16-bit PCI configuration register specified by
 425   Address. The value written to the PCI configuration register is returned.
 426   This function must guarantee that all PCI read and write operations are
 427   serialized.
 428
 429   If Address > 0x0FFFFFFF, then ASSERT().
 430   If Address is not aligned on a 16-bit boundary, then ASSERT().
 431
 432   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 433                        Register.
 434   @param[in] AndData   The value to AND with the PCI configuration register.
 435
 436   @return   The value written back to the PCI configuration register.
 437
 438 **/
 439 UINT16
 440 EFIAPI
 441 S3PciAnd16 (
 442   IN UINTN   Address,
 443   IN UINT16  AndData
 444   );
 445
 446 /**
 447   Performs a bitwise AND of a 16-bit PCI configuration register with a 16-bit
 448   value, followed a  bitwise OR with another 16-bit value, and saves
 449   the value in the S3 script to be replayed on S3 resume.
 450
 451   Reads the 16-bit PCI configuration register specified by Address, performs a
 452   bitwise AND between the read result and the value specified by AndData,
 453   performs a bitwise OR between the result of the AND operation and
 454   the value specified by OrData, and writes the result to the 16-bit PCI
 455   configuration register specified by Address. The value written to the PCI
 456   configuration register is returned. This function must guarantee that all PCI
 457   read and write operations are serialized.
 458
 459   If Address > 0x0FFFFFFF, then ASSERT().
 460   If Address is not aligned on a 16-bit boundary, then ASSERT().
 461
 462   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 463                        Register.
 464   @param[in] AndData   The value to AND with the PCI configuration register.
 465   @param[in] OrData    The value to OR with the result of the AND operation.
 466
 467   @return   The value written back to the PCI configuration register.
 468
 469 **/
 470 UINT16
 471 EFIAPI
 472 S3PciAndThenOr16 (
 473   IN UINTN   Address,
 474   IN UINT16  AndData,
 475   IN UINT16  OrData
 476   );
 477
 478 /**
 479   Reads a bit field of a PCI configuration register, and saves the value in
 480   the S3 script to be replayed on S3 resume.
 481
 482   Reads the bit field in a 16-bit PCI configuration register. The bit field is
 483   specified by the StartBit and the EndBit. The value of the bit field is
 484   returned.
 485
 486   If Address > 0x0FFFFFFF, then ASSERT().
 487   If Address is not aligned on a 16-bit boundary, then ASSERT().
 488   If StartBit is greater than 15, then ASSERT().
 489   If EndBit is greater than 15, then ASSERT().
 490   If EndBit is less than StartBit, then ASSERT().
 491
 492   @param[in] Address    The PCI configuration register to read.
 493   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 494                         Range 0..15.
 495   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 496                         Range 0..15.
 497
 498   @return   The value of the bit field read from the PCI configuration register.
 499
 500 **/
 501 UINT16
 502 EFIAPI
 503 S3PciBitFieldRead16 (
 504   IN UINTN  Address,
 505   IN UINTN  StartBit,
 506   IN UINTN  EndBit
 507   );
 508
 509 /**
 510   Writes a bit field to a PCI configuration register, and saves the value in
 511   the S3 script to be replayed on S3 resume.
 512
 513   Writes Value to the bit field of the PCI configuration register. The bit
 514   field is specified by the StartBit and the EndBit. All other bits in the
 515   destination PCI configuration register are preserved. The new value of the
 516   16-bit register is returned.
 517
 518   If Address > 0x0FFFFFFF, then ASSERT().
 519   If Address is not aligned on a 16-bit boundary, then ASSERT().
 520   If StartBit is greater than 15, then ASSERT().
 521   If EndBit is greater than 15, then ASSERT().
 522   If EndBit is less than StartBit, then ASSERT().
 523
 524   @param[in] Address    The PCI configuration register to write.
 525   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 526                         Range 0..15.
 527   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 528                         Range 0..15.
 529   @param[in] Value      New value of the bit field.
 530
 531   @return   The value written back to the PCI configuration register.
 532
 533 **/
 534 UINT16
 535 EFIAPI
 536 S3PciBitFieldWrite16 (
 537   IN UINTN   Address,
 538   IN UINTN   StartBit,
 539   IN UINTN   EndBit,
 540   IN UINT16  Value
 541   );
 542
 543 /**
 544   Reads a bit field in a 16-bit PCI configuration, performs a bitwise OR, and
 545   writes the result back to the bit field in the 16-bit port, and saves the value
 546   in the S3 script to be replayed on S3 resume.
 547
 548   Reads the 16-bit PCI configuration register specified by Address, performs a
 549   bitwise OR between the read result and the value specified by
 550   OrData, and writes the result to the 16-bit PCI configuration register
 551   specified by Address. The value written to the PCI configuration register is
 552   returned. This function must guarantee that all PCI read and write operations
 553   are serialized. Extra left bits in OrData are stripped.
 554
 555   If Address > 0x0FFFFFFF, then ASSERT().
 556   If Address is not aligned on a 16-bit boundary, then ASSERT().
 557   If StartBit is greater than 15, then ASSERT().
 558   If EndBit is greater than 15, then ASSERT().
 559   If EndBit is less than StartBit, 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
 598   @param[in] Address    The PCI configuration register to write.
 599   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 600                         Range 0..15.
 601   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 602                         Range 0..15.
 603   @param[in] AndData    The value to AND with the PCI configuration register.
 604
 605   @return   The value written back to the PCI configuration register.
 606
 607 **/
 608 UINT16
 609 EFIAPI
 610 S3PciBitFieldAnd16 (
 611   IN UINTN   Address,
 612   IN UINTN   StartBit,
 613   IN UINTN   EndBit,
 614   IN UINT16  AndData
 615   );
 616
 617 /**
 618   Reads a bit field in a 16-bit Address, performs a bitwise AND followed by a
 619   bitwise OR, and writes the result back to the bit field in the
 620   16-bit port, and saves the value in the S3 script to be replayed on S3 resume.
 621
 622   Reads the 16-bit PCI configuration register specified by Address, performs a
 623   bitwise AND followed by a bitwise OR between the read result and
 624   the value specified by AndData, and writes the result to the 16-bit PCI
 625   configuration register specified by Address. The value written to the PCI
 626   configuration register is returned. This function must guarantee that all PCI
 627   read and write operations are serialized. Extra left bits in both AndData and
 628   OrData are stripped.
 629
 630   If Address > 0x0FFFFFFF, then ASSERT().
 631   If Address is not aligned on a 16-bit boundary, then ASSERT().
 632   If StartBit is greater than 15, then ASSERT().
 633   If EndBit is greater than 15, then ASSERT().
 634   If EndBit is less than StartBit, then ASSERT().
 635
 636   @param[in] Address    The PCI configuration register to write.
 637   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 638                         Range 0..15.
 639   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 640                         Range 0..15.
 641   @param[in] AndData    The value to AND with the PCI configuration register.
 642   @param[in] OrData     The value to OR with the result of the AND operation.
 643
 644   @return   The value written back to the PCI configuration register.
 645
 646 **/
 647 UINT16
 648 EFIAPI
 649 S3PciBitFieldAndThenOr16 (
 650   IN UINTN   Address,
 651   IN UINTN   StartBit,
 652   IN UINTN   EndBit,
 653   IN UINT16  AndData,
 654   IN UINT16  OrData
 655   );
 656
 657 /**
 658   Reads a 32-bit PCI configuration register, and saves the value in the S3
 659   script to be replayed on S3 resume.
 660
 661   Reads and returns the 32-bit PCI configuration register specified by Address.
 662   This function must guarantee that all PCI read and write operations are
 663   serialized.
 664
 665   If Address > 0x0FFFFFFF, then ASSERT().
 666   If Address is not aligned on a 32-bit boundary, then ASSERT().
 667
 668   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 669                        Register.
 670
 671   @return   The read value from the PCI configuration register.
 672
 673 **/
 674 UINT32
 675 EFIAPI
 676 S3PciRead32 (
 677   IN UINTN  Address
 678   );
 679
 680 /**
 681   Writes a 32-bit PCI configuration register, and saves the value in the S3
 682   script to be replayed on S3 resume.
 683
 684   Writes the 32-bit PCI configuration register specified by Address with the
 685   value specified by Value. Value is returned. This function must guarantee
 686   that all PCI read and write operations are serialized.
 687
 688   If Address > 0x0FFFFFFF, then ASSERT().
 689   If Address is not aligned on a 32-bit boundary, then ASSERT().
 690
 691   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 692                        Register.
 693   @param[in] Value     The value to write.
 694
 695   @return   The value written to the PCI configuration register.
 696
 697 **/
 698 UINT32
 699 EFIAPI
 700 S3PciWrite32 (
 701   IN UINTN   Address,
 702   IN UINT32  Value
 703   );
 704
 705 /**
 706   Performs a bitwise OR of a 32-bit PCI configuration register with
 707   a 32-bit value, and saves the value in the S3 script to be replayed on S3 resume.
 708
 709   Reads the 32-bit PCI configuration register specified by Address, performs a
 710   bitwise OR between the read result and the value specified by
 711   OrData, and writes the result to the 32-bit PCI configuration register
 712   specified by Address. The value written to the PCI configuration register is
 713   returned. This function must guarantee that all PCI read and write operations
 714   are serialized.
 715
 716   If Address > 0x0FFFFFFF, then ASSERT().
 717   If Address is not aligned on a 32-bit boundary, then ASSERT().
 718
 719   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 720                        Register.
 721   @param[in] OrData    The value to OR with the PCI configuration register.
 722
 723   @return   The value written back to the PCI configuration register.
 724
 725 **/
 726 UINT32
 727 EFIAPI
 728 S3PciOr32 (
 729   IN UINTN   Address,
 730   IN UINT32  OrData
 731   );
 732
 733 /**
 734   Performs a bitwise AND of a 32-bit PCI configuration register with a 32-bit
 735   value, and saves the value in the S3 script to be replayed on S3 resume.
 736
 737   Reads the 32-bit PCI configuration register specified by Address, performs a
 738   bitwise AND between the read result and the value specified by AndData, and
 739   writes the result to the 32-bit PCI configuration register specified by
 740   Address. The value written to the PCI configuration register is returned.
 741   This function must guarantee that all PCI read and write operations are
 742   serialized.
 743
 744   If Address > 0x0FFFFFFF, then ASSERT().
 745   If Address is not aligned on a 32-bit boundary, then ASSERT().
 746
 747   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 748                        Register.
 749   @param[in] AndData   The value to AND with the PCI configuration register.
 750
 751   @return   The value written back to the PCI configuration register.
 752
 753 **/
 754 UINT32
 755 EFIAPI
 756 S3PciAnd32 (
 757   IN UINTN   Address,
 758   IN UINT32  AndData
 759   );
 760
 761 /**
 762   Performs a bitwise AND of a 32-bit PCI configuration register with a 32-bit
 763   value, followed a  bitwise OR with another 32-bit value, and saves
 764   the value in the S3 script to be replayed on S3 resume.
 765
 766   Reads the 32-bit PCI configuration register specified by Address, performs a
 767   bitwise AND between the read result and the value specified by AndData,
 768   performs a bitwise OR between the result of the AND operation and
 769   the value specified by OrData, and writes the result to the 32-bit PCI
 770   configuration register specified by Address. The value written to the PCI
 771   configuration register is returned. This function must guarantee that all PCI
 772   read and write operations are serialized.
 773
 774   If Address > 0x0FFFFFFF, then ASSERT().
 775   If Address is not aligned on a 32-bit boundary, then ASSERT().
 776
 777   @param[in] Address   The address that encodes the PCI Bus, Device, Function and
 778                        Register.
 779   @param[in] AndData   The value to AND with the PCI configuration register.
 780   @param[in] OrData    The value to OR with the result of the AND operation.
 781
 782   @return   The value written back to the PCI configuration register.
 783
 784 **/
 785 UINT32
 786 EFIAPI
 787 S3PciAndThenOr32 (
 788   IN UINTN   Address,
 789   IN UINT32  AndData,
 790   IN UINT32  OrData
 791   );
 792
 793 /**
 794   Reads a bit field of a PCI configuration register, and saves the value in
 795   the S3 script to be replayed on S3 resume.
 796
 797   Reads the bit field in a 32-bit PCI configuration register. The bit field is
 798   specified by the StartBit and the EndBit. The value of the bit field is
 799   returned.
 800
 801   If Address > 0x0FFFFFFF, then ASSERT().
 802   If Address is not aligned on a 32-bit boundary, then ASSERT().
 803   If StartBit is greater than 31, then ASSERT().
 804   If EndBit is greater than 31, then ASSERT().
 805   If EndBit is less than StartBit, then ASSERT().
 806
 807   @param[in] Address    The PCI configuration register to read.
 808   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 809                         Range 0..31.
 810   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 811                         Range 0..31.
 812
 813   @return   The value of the bit field read from the PCI configuration register.
 814
 815 **/
 816 UINT32
 817 EFIAPI
 818 S3PciBitFieldRead32 (
 819   IN UINTN  Address,
 820   IN UINTN  StartBit,
 821   IN UINTN  EndBit
 822   );
 823
 824 /**
 825   Writes a bit field to a PCI configuration register, and saves the value in
 826   the S3 script to be replayed on S3 resume.
 827
 828   Writes Value to the bit field of the PCI configuration register. The bit
 829   field is specified by the StartBit and the EndBit. All other bits in the
 830   destination PCI configuration register are preserved. The new value of the
 831   32-bit register is returned.
 832
 833   If Address > 0x0FFFFFFF, then ASSERT().
 834   If Address is not aligned on a 32-bit boundary, then ASSERT().
 835   If StartBit is greater than 31, then ASSERT().
 836   If EndBit is greater than 31, then ASSERT().
 837   If EndBit is less than StartBit, then ASSERT().
 838
 839   @param[in] Address    The PCI configuration register to write.
 840   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 841                         Range 0..31.
 842   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 843                         Range 0..31.
 844   @param[in] Value      New value of the bit field.
 845
 846   @return   The value written back to the PCI configuration register.
 847
 848 **/
 849 UINT32
 850 EFIAPI
 851 S3PciBitFieldWrite32 (
 852   IN UINTN   Address,
 853   IN UINTN   StartBit,
 854   IN UINTN   EndBit,
 855   IN UINT32  Value
 856   );
 857
 858 /**
 859   Reads a bit field in a 32-bit PCI configuration, performs a bitwise OR, and
 860   writes the result back to the bit field in the 32-bit port, and saves the value
 861   in the S3 script to be replayed on S3 resume.
 862
 863   Reads the 32-bit PCI configuration register specified by Address, performs a
 864   bitwise OR between the read result and the value specified by
 865   OrData, and writes the result to the 32-bit PCI configuration register
 866   specified by Address. The value written to the PCI configuration register is
 867   returned. This function must guarantee that all PCI read and write operations
 868   are serialized. Extra left bits in OrData are stripped.
 869
 870   If Address > 0x0FFFFFFF, then ASSERT().
 871   If Address is not aligned on a 32-bit boundary, then ASSERT().
 872   If StartBit is greater than 31, then ASSERT().
 873   If EndBit is greater than 31, then ASSERT().
 874   If EndBit is less than StartBit, then ASSERT().
 875
 876   @param[in] Address    The PCI configuration register to write.
 877   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 878                         Range 0..31.
 879   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 880                         Range 0..31.
 881   @param[in] OrData     The value to OR with the PCI configuration register.
 882
 883   @return   The value written back to the PCI configuration register.
 884
 885 **/
 886 UINT32
 887 EFIAPI
 888 S3PciBitFieldOr32 (
 889   IN UINTN   Address,
 890   IN UINTN   StartBit,
 891   IN UINTN   EndBit,
 892   IN UINT32  OrData
 893   );
 894
 895 /**
 896   Reads a bit field in a 32-bit PCI configuration register, performs a bitwise
 897   AND, and writes the result back to the bit field in the 32-bit register and
 898   saves the value in the S3 script to be replayed on S3 resume.
 899
 900   Reads the 32-bit PCI configuration register specified by Address, performs a
 901   bitwise AND between the read result and the value specified by AndData, and
 902   writes the result to the 32-bit PCI configuration register specified by
 903   Address. The value written to the PCI configuration register is returned.
 904   This function must guarantee that all PCI read and write operations are
 905   serialized. Extra left bits in AndData are stripped.
 906
 907   If Address > 0x0FFFFFFF, then ASSERT().
 908   If Address is not aligned on a 32-bit boundary, then ASSERT().
 909   If StartBit is greater than 31, then ASSERT().
 910   If EndBit is greater than 31, then ASSERT().
 911   If EndBit is less than StartBit, then ASSERT().
 912
 913   @param[in] Address    The PCI configuration register to write.
 914   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 915                         Range 0..31.
 916   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 917                         Range 0..31.
 918   @param[in] AndData    The value to AND with the PCI configuration register.
 919
 920   @return   The value written back to the PCI configuration register.
 921
 922 **/
 923 UINT32
 924 EFIAPI
 925 S3PciBitFieldAnd32 (
 926   IN UINTN   Address,
 927   IN UINTN   StartBit,
 928   IN UINTN   EndBit,
 929   IN UINT32  AndData
 930   );
 931
 932 /**
 933   Reads a bit field in a 32-bit Address, performs a bitwise AND followed by a
 934   bitwise OR, and writes the result back to the bit field in the
 935   32-bit port, and saves the value in the S3 script to be replayed on S3 resume.
 936
 937   Reads the 32-bit PCI configuration register specified by Address, performs a
 938   bitwise AND followed by a bitwise OR between the read result and
 939   the value specified by AndData, and writes the result to the 32-bit PCI
 940   configuration register specified by Address. The value written to the PCI
 941   configuration register is returned. This function must guarantee that all PCI
 942   read and write operations are serialized. Extra left bits in both AndData and
 943   OrData are stripped.
 944
 945   If Address > 0x0FFFFFFF, then ASSERT().
 946   If Address is not aligned on a 32-bit boundary, then ASSERT().
 947   If StartBit is greater than 31, then ASSERT().
 948   If EndBit is greater than 31, then ASSERT().
 949   If EndBit is less than StartBit, then ASSERT().
 950
 951   @param[in] Address    The PCI configuration register to write.
 952   @param[in] StartBit   The ordinal of the least significant bit in the bit field.
 953                         Range 0..31.
 954   @param[in] EndBit     The ordinal of the most significant bit in the bit field.
 955                         Range 0..31.
 956   @param[in] AndData    The value to AND with the PCI configuration register.
 957   @param[in] 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 S3PciBitFieldAndThenOr32 (
 965   IN UINTN   Address,
 966   IN UINTN   StartBit,
 967   IN UINTN   EndBit,
 968   IN UINT32  AndData,
 969   IN UINT32  OrData
 970   );
 971
 972 /**
 973   Reads a range of PCI configuration registers into a caller supplied buffer,
 974   and saves the value in the S3 script to be replayed on S3 resume.
 975
 976   Reads the range of PCI configuration registers specified by StartAddress and
 977   Size into the buffer specified by Buffer. This function only allows the PCI
 978   configuration registers from a single PCI function to be read. Size is
 979   returned. When possible 32-bit PCI configuration read cycles are used to read
 980   from StartAdress to StartAddress + Size. Due to alignment restrictions, 8-bit
 981   and 16-bit PCI configuration read cycles may be used at the beginning and the
 982   end of the range.
 983
 984   If StartAddress > 0x0FFFFFFF, then ASSERT().
 985   If ((StartAddress & 0xFFF) + Size) > 0x1000, then ASSERT().
 986   If Size > 0 and Buffer is NULL, then ASSERT().
 987
 988   @param[in]  StartAddress   Starting address that encodes the PCI Bus, Device,
 989                              Function and Register.
 990   @param[in]  Size           Size in bytes of the transfer.
 991   @param[out] Buffer         The pointer to a buffer receiving the data read.
 992
 993   @return   Size.
 994
 995 **/
 996 UINTN
 997 EFIAPI
 998 S3PciReadBuffer (
 999   IN  UINTN  StartAddress,
1000   IN  UINTN  Size,
1001   OUT VOID   *Buffer
1002   );
1003
1004 /**
1005   Copies the data in a caller supplied buffer to a specified range of PCI
1006   configuration space, and saves the value in the S3 script to be replayed on S3
1007   resume.
1008
1009   Writes the range of PCI configuration registers specified by StartAddress and
1010   Size from the buffer specified by Buffer. This function only allows the PCI
1011   configuration registers from a single PCI function to be written. Size is
1012   returned. When possible 32-bit PCI configuration write cycles are used to
1013   write from StartAdress to StartAddress + Size. Due to alignment restrictions,
1014   8-bit and 16-bit PCI configuration write cycles may be used at the beginning
1015   and the end of the range.
1016
1017   If StartAddress > 0x0FFFFFFF, then ASSERT().
1018   If ((StartAddress & 0xFFF) + Size) > 0x1000, then ASSERT().
1019   If Size > 0 and Buffer is NULL, then ASSERT().
1020
1021   @param[in] StartAddress   Starting address that encodes the PCI Bus, Device,
1022                             Function and Register.
1023   @param[in] Size           Size in bytes of the transfer.
1024   @param[in] Buffer         The pointer to a buffer containing the data to write.
1025
1026   @return   Size.
1027
1028 **/
1029 UINTN
1030 EFIAPI
1031 S3PciWriteBuffer (
1032   IN UINTN  StartAddress,
1033   IN UINTN  Size,
1034   IN VOID   *Buffer
1035   );
1036
1037 #endif