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