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