MdePkg/Include/Library/S3PciSegmentLib.h

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