MdePkg/Library/BaseS3IoLib/S3IoLib.c

   1 /** @file
   2   I/O and MMIO Library Services that do I/O and also enable the I/O operatation
   3   to be replayed during an S3 resume.
   4
   5   Copyright (c) 2006 -2018, Intel Corporation. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #include <Base.h>
  12
  13 #include <Library/S3IoLib.h>
  14 #include <Library/DebugLib.h>
  15 #include <Library/IoLib.h>
  16 #include <Library/S3BootScriptLib.h>
  17
  18
  19 /**
  20   Saves an I/O port value to the boot script.
  21
  22   This internal worker function saves an I/O port value in the S3 script
  23   to be replayed on S3 resume.
  24
  25   If the saving process fails, then ASSERT().
  26
  27   @param  Width         The width of I/O port.
  28   @param  Port          The I/O port to write.
  29   @param  Buffer        The buffer containing value.
  30
  31 **/
  32 VOID
  33 InternalSaveIoWriteValueToBootScript (
  34   IN S3_BOOT_SCRIPT_LIB_WIDTH  Width,
  35   IN UINTN                  Port,
  36   IN VOID                   *Buffer
  37   )
  38 {
  39   RETURN_STATUS                Status;
  40
  41   Status = S3BootScriptSaveIoWrite (
  42              Width,
  43              Port,
  44              1,
  45              Buffer
  46              );
  47   ASSERT (Status == RETURN_SUCCESS);
  48 }
  49
  50 /**
  51   Saves an 8-bit I/O port value to the boot script.
  52
  53   This internal worker function saves an 8-bit I/O port value in the S3 script
  54   to be replayed on S3 resume.
  55
  56   If the saving process fails, then ASSERT().
  57
  58   @param  Port          The I/O port to write.
  59   @param  Value         The value saved to boot script.
  60
  61   @return Value.
  62
  63 **/
  64 UINT8
  65 InternalSaveIoWrite8ValueToBootScript (
  66   IN UINTN              Port,
  67   IN UINT8              Value
  68   )
  69 {
  70   InternalSaveIoWriteValueToBootScript (S3BootScriptWidthUint8, Port, &Value);
  71
  72   return Value;
  73 }
  74
  75 /**
  76   Reads an 8-bit I/O port and saves the value in the S3 script to be replayed
  77   on S3 resume.
  78
  79   Reads the 8-bit I/O port specified by Port. The 8-bit read value is returned.
  80   This function must guarantee that all I/O read and write operations are
  81   serialized.
  82
  83   If 8-bit I/O port operations are not supported, then ASSERT().
  84
  85   @param  Port          The I/O port to read.
  86
  87   @return The value read.
  88
  89 **/
  90 UINT8
  91 EFIAPI
  92 S3IoRead8 (
  93   IN UINTN              Port
  94   )
  95 {
  96   return InternalSaveIoWrite8ValueToBootScript (Port, IoRead8 (Port));
  97 }
  98
  99 /**
 100   Writes an 8-bit I/O port and saves the value in the S3 script to be replayed
 101   on S3 resume.
 102
 103   Writes the 8-bit I/O port specified by Port with the value specified by Value
 104   and returns Value. This function must guarantee that all I/O read and write
 105   operations are serialized.
 106
 107   If 8-bit I/O port operations are not supported, then ASSERT().
 108
 109   @param  Port          The I/O port to write.
 110   @param  Value         The value to write to the I/O port.
 111
 112   @return The value written the I/O port.
 113
 114 **/
 115 UINT8
 116 EFIAPI
 117 S3IoWrite8 (
 118   IN UINTN              Port,
 119   IN UINT8              Value
 120   )
 121 {
 122   return InternalSaveIoWrite8ValueToBootScript (Port, IoWrite8 (Port, Value));
 123 }
 124
 125 /**
 126   Reads an 8-bit I/O port, performs a bitwise OR, and writes the
 127   result back to the 8-bit I/O port and saves the value in the S3 script to be
 128   replayed on S3 resume.
 129
 130   Reads the 8-bit I/O port specified by Port, performs a bitwise OR
 131   between the read result and the value specified by OrData, and writes the
 132   result to the 8-bit I/O port specified by Port. The value written to the I/O
 133   port is returned. This function must guarantee that all I/O read and write
 134   operations are serialized.
 135
 136   If 8-bit I/O port operations are not supported, then ASSERT().
 137
 138   @param  Port          The I/O port to write.
 139   @param  OrData        The value to OR with the read value from the I/O port.
 140
 141   @return The value written back to the I/O port.
 142
 143 **/
 144 UINT8
 145 EFIAPI
 146 S3IoOr8 (
 147   IN UINTN              Port,
 148   IN UINT8              OrData
 149   )
 150 {
 151   return InternalSaveIoWrite8ValueToBootScript (Port, IoOr8 (Port, OrData));
 152 }
 153
 154 /**
 155   Reads an 8-bit I/O port, performs a bitwise AND, and writes the result back
 156   to the 8-bit I/O port  and saves the value in the S3 script to be replayed
 157   on S3 resume.
 158
 159   Reads the 8-bit I/O port specified by Port, performs a bitwise AND between
 160   the read result and the value specified by AndData, and writes the result to
 161   the 8-bit I/O port specified by Port. The value written to the I/O port is
 162   returned. This function must guarantee that all I/O read and write operations
 163   are serialized.
 164
 165   If 8-bit I/O port operations are not supported, then ASSERT().
 166
 167   @param  Port          The I/O port to write.
 168   @param  AndData       The value to AND with the read value from the I/O port.
 169
 170   @return The value written back to the I/O port.
 171
 172 **/
 173 UINT8
 174 EFIAPI
 175 S3IoAnd8 (
 176   IN UINTN              Port,
 177   IN UINT8              AndData
 178   )
 179 {
 180   return InternalSaveIoWrite8ValueToBootScript (Port, IoAnd8 (Port, AndData));
 181 }
 182
 183 /**
 184   Reads an 8-bit I/O port, performs a bitwise AND followed by a bitwise
 185   inclusive OR, and writes the result back to the 8-bit I/O port and saves
 186   the value in the S3 script to be replayed on S3 resume.
 187
 188   Reads the 8-bit I/O port specified by Port, performs a bitwise AND between
 189   the read result and the value specified by AndData, performs a bitwise OR
 190   between the result of the AND operation and the value specified by OrData,
 191   and writes the result to the 8-bit I/O port specified by Port. The value
 192   written to the I/O port is returned. This function must guarantee that all
 193   I/O read and write operations are serialized.
 194
 195   If 8-bit I/O port operations are not supported, then ASSERT().
 196
 197   @param  Port          The I/O port to write.
 198   @param  AndData       The value to AND with the read value from the I/O port.
 199   @param  OrData        The value to OR with the result of the AND operation.
 200
 201   @return The value written back to the I/O port.
 202
 203 **/
 204 UINT8
 205 EFIAPI
 206 S3IoAndThenOr8 (
 207   IN UINTN              Port,
 208   IN UINT8              AndData,
 209   IN UINT8              OrData
 210   )
 211 {
 212   return InternalSaveIoWrite8ValueToBootScript (Port, IoAndThenOr8 (Port, AndData, OrData));
 213 }
 214
 215 /**
 216   Reads a bit field of an I/O register and saves the value in the S3 script to
 217   be replayed on S3 resume.
 218
 219   Reads the bit field in an 8-bit I/O register. The bit field is specified by
 220   the StartBit and the EndBit. The value of the bit field is returned.
 221
 222   If 8-bit I/O port operations are not supported, then ASSERT().
 223   If StartBit is greater than 7, then ASSERT().
 224   If EndBit is greater than 7, then ASSERT().
 225   If EndBit is less than StartBit, then ASSERT().
 226
 227   @param  Port          The I/O port to read.
 228   @param  StartBit      The ordinal of the least significant bit in the bit field.
 229                         Range 0..7.
 230   @param  EndBit        The ordinal of the most significant bit in the bit field.
 231                         Range 0..7.
 232
 233   @return The value read.
 234
 235 **/
 236 UINT8
 237 EFIAPI
 238 S3IoBitFieldRead8 (
 239   IN UINTN              Port,
 240   IN UINTN              StartBit,
 241   IN UINTN              EndBit
 242   )
 243 {
 244   return InternalSaveIoWrite8ValueToBootScript (Port, IoBitFieldRead8 (Port, StartBit, EndBit));
 245 }
 246
 247 /**
 248   Writes a bit field to an I/O register and saves the value in the S3 script to
 249   be replayed on S3 resume.
 250
 251   Writes Value to the bit field of the I/O register. The bit field is specified
 252   by the StartBit and the EndBit. All other bits in the destination I/O
 253   register are preserved. The value written to the I/O port is returned. Extra
 254   left bits in Value are stripped.
 255
 256   If 8-bit I/O port operations are not supported, then ASSERT().
 257   If StartBit is greater than 7, then ASSERT().
 258   If EndBit is greater than 7, then ASSERT().
 259   If EndBit is less than StartBit, then ASSERT().
 260   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 261
 262   @param  Port          The I/O port to write.
 263   @param  StartBit      The ordinal of the least significant bit in the bit field.
 264                         Range 0..7.
 265   @param  EndBit        The ordinal of the most significant bit in the bit field.
 266                         Range 0..7.
 267   @param  Value         New value of the bit field.
 268
 269   @return The value written back to the I/O port.
 270
 271 **/
 272 UINT8
 273 EFIAPI
 274 S3IoBitFieldWrite8 (
 275   IN UINTN              Port,
 276   IN UINTN              StartBit,
 277   IN UINTN              EndBit,
 278   IN UINT8              Value
 279   )
 280 {
 281   return InternalSaveIoWrite8ValueToBootScript (Port, IoBitFieldWrite8 (Port, StartBit, EndBit, Value));
 282 }
 283
 284 /**
 285   Reads a bit field in an 8-bit port, performs a bitwise OR, and writes the
 286   result back to the bit field in the 8-bit port and saves the value in the
 287   S3 script to be replayed on S3 resume.
 288
 289   Reads the 8-bit I/O port specified by Port, performs a bitwise OR
 290   between the read result and the value specified by OrData, and writes the
 291   result to the 8-bit I/O port specified by Port. The value written to the I/O
 292   port is returned. This function must guarantee that all I/O read and write
 293   operations are serialized. Extra left bits in OrData are stripped.
 294
 295   If 8-bit I/O port operations are not supported, then ASSERT().
 296   If StartBit is greater than 7, then ASSERT().
 297   If EndBit is greater than 7, then ASSERT().
 298   If EndBit is less than StartBit, then ASSERT().
 299   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 300
 301   @param  Port          The I/O port to write.
 302   @param  StartBit      The ordinal of the least significant bit in the bit field.
 303                         Range 0..7.
 304   @param  EndBit        The ordinal of the most significant bit in the bit field.
 305                         Range 0..7.
 306   @param  OrData        The value to OR with the read value from the I/O port.
 307
 308   @return The value written back to the I/O port.
 309
 310 **/
 311 UINT8
 312 EFIAPI
 313 S3IoBitFieldOr8 (
 314   IN UINTN              Port,
 315   IN UINTN              StartBit,
 316   IN UINTN              EndBit,
 317   IN UINT8              OrData
 318   )
 319 {
 320   return InternalSaveIoWrite8ValueToBootScript (Port, IoBitFieldOr8 (Port, StartBit, EndBit, OrData));
 321 }
 322
 323 /**
 324   Reads a bit field in an 8-bit port, performs a bitwise AND, and writes the
 325   result back to the bit field in the 8-bit port  and saves the value in the
 326   S3 script to be replayed on S3 resume.
 327
 328   Reads the 8-bit I/O port specified by Port, performs a bitwise AND between
 329   the read result and the value specified by AndData, and writes the result to
 330   the 8-bit I/O port specified by Port. The value written to the I/O port is
 331   returned. This function must guarantee that all I/O read and write operations
 332   are serialized. Extra left bits in AndData are stripped.
 333
 334   If 8-bit I/O port operations are not supported, then ASSERT().
 335   If StartBit is greater than 7, then ASSERT().
 336   If EndBit is greater than 7, then ASSERT().
 337   If EndBit is less than StartBit, then ASSERT().
 338   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 339
 340   @param  Port          The I/O port to write.
 341   @param  StartBit      The ordinal of the least significant bit in the bit field.
 342                         Range 0..7.
 343   @param  EndBit        The ordinal of the most significant bit in the bit field.
 344                         Range 0..7.
 345   @param  AndData       The value to AND with the read value from the I/O port.
 346
 347   @return The value written back to the I/O port.
 348
 349 **/
 350 UINT8
 351 EFIAPI
 352 S3IoBitFieldAnd8 (
 353   IN UINTN              Port,
 354   IN UINTN              StartBit,
 355   IN UINTN              EndBit,
 356   IN UINT8              AndData
 357   )
 358 {
 359   return InternalSaveIoWrite8ValueToBootScript (Port, IoBitFieldAnd8 (Port, StartBit, EndBit, AndData));
 360 }
 361
 362 /**
 363   Reads a bit field in an 8-bit port, performs a bitwise AND followed by a
 364   bitwise OR, and writes the result back to the bit field in the
 365   8-bit port and saves the value in the S3 script to be replayed on S3 resume.
 366
 367   Reads the 8-bit I/O port specified by Port, performs a bitwise AND followed
 368   by a bitwise OR between the read result and the value specified by
 369   AndData, and writes the result to the 8-bit I/O port specified by Port. The
 370   value written to the I/O port is returned. This function must guarantee that
 371   all I/O read and write operations are serialized. Extra left bits in both
 372   AndData and OrData are stripped.
 373
 374   If 8-bit I/O port operations are not supported, then ASSERT().
 375   If StartBit is greater than 7, then ASSERT().
 376   If EndBit is greater than 7, then ASSERT().
 377   If EndBit is less than StartBit, then ASSERT().
 378   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 379   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 380
 381   @param  Port          The I/O port to write.
 382   @param  StartBit      The ordinal of the least significant bit in the bit field.
 383                         Range 0..7.
 384   @param  EndBit        The ordinal of the most significant bit in the bit field.
 385                         Range 0..7.
 386   @param  AndData       The value to AND with the read value from the I/O port.
 387   @param  OrData        The value to OR with the result of the AND operation.
 388
 389   @return The value written back to the I/O port.
 390
 391 **/
 392 UINT8
 393 EFIAPI
 394 S3IoBitFieldAndThenOr8 (
 395   IN UINTN              Port,
 396   IN UINTN              StartBit,
 397   IN UINTN              EndBit,
 398   IN UINT8              AndData,
 399   IN UINT8              OrData
 400   )
 401 {
 402   return InternalSaveIoWrite8ValueToBootScript (Port, IoBitFieldAndThenOr8 (Port, StartBit, EndBit, AndData, OrData));
 403 }
 404
 405 /**
 406   Saves a 16-bit I/O port value to the boot script.
 407
 408   This internal worker function saves a 16-bit I/O port value in the S3 script
 409   to be replayed on S3 resume.
 410
 411   If the saving process fails, then ASSERT().
 412
 413   @param  Port          The I/O port to write.
 414   @param  Value         The value saved to boot script.
 415
 416   @return Value.
 417
 418 **/
 419 UINT16
 420 InternalSaveIoWrite16ValueToBootScript (
 421   IN UINTN              Port,
 422   IN UINT16             Value
 423   )
 424 {
 425   InternalSaveIoWriteValueToBootScript (S3BootScriptWidthUint16, Port, &Value);
 426
 427   return Value;
 428 }
 429
 430 /**
 431   Reads a 16-bit I/O port and saves the value in the S3 script to be replayed
 432   on S3 resume.
 433
 434   Reads the 16-bit I/O port specified by Port. The 16-bit read value is returned.
 435   This function must guarantee that all I/O read and write operations are
 436   serialized.
 437
 438   If 16-bit I/O port operations are not supported, then ASSERT().
 439
 440   @param  Port          The I/O port to read.
 441
 442   @return The value read.
 443
 444 **/
 445 UINT16
 446 EFIAPI
 447 S3IoRead16 (
 448   IN UINTN              Port
 449   )
 450 {
 451   return InternalSaveIoWrite16ValueToBootScript (Port, IoRead16 (Port));
 452 }
 453
 454 /**
 455   Writes a 16-bit I/O port and saves the value in the S3 script to be replayed
 456   on S3 resume.
 457
 458   Writes the 16-bit I/O port specified by Port with the value specified by Value
 459   and returns Value. This function must guarantee that all I/O read and write
 460   operations are serialized.
 461
 462   If 16-bit I/O port operations are not supported, then ASSERT().
 463
 464   @param  Port          The I/O port to write.
 465   @param  Value         The value to write to the I/O port.
 466
 467   @return The value written the I/O port.
 468
 469 **/
 470 UINT16
 471 EFIAPI
 472 S3IoWrite16 (
 473   IN UINTN              Port,
 474   IN UINT16             Value
 475   )
 476 {
 477   return InternalSaveIoWrite16ValueToBootScript (Port, IoWrite16 (Port, Value));
 478 }
 479
 480 /**
 481   Reads a 16-bit I/O port, performs a bitwise OR, and writes the
 482   result back to the 16-bit I/O port and saves the value in the S3 script to
 483   be replayed on S3 resume.
 484
 485   Reads the 16-bit I/O port specified by Port, performs a bitwise OR
 486   between the read result and the value specified by OrData, and writes the
 487   result to the 16-bit I/O port specified by Port. The value written to the I/O
 488   port is returned. This function must guarantee that all I/O read and write
 489   operations are serialized.
 490
 491   If 16-bit I/O port operations are not supported, then ASSERT().
 492
 493   @param  Port          The I/O port to write.
 494   @param  OrData        The value to OR with the read value from the I/O port.
 495
 496   @return The value written back to the I/O port.
 497
 498 **/
 499 UINT16
 500 EFIAPI
 501 S3IoOr16 (
 502   IN UINTN              Port,
 503   IN UINT16             OrData
 504   )
 505 {
 506   return InternalSaveIoWrite16ValueToBootScript (Port, IoOr16 (Port, OrData));
 507 }
 508
 509 /**
 510   Reads a 16-bit I/O port, performs a bitwise AND, and writes the result back
 511   to the 16-bit I/O port  and saves the value in the S3 script to be replayed
 512   on S3 resume.
 513
 514   Reads the 16-bit I/O port specified by Port, performs a bitwise AND between
 515   the read result and the value specified by AndData, and writes the result to
 516   the 16-bit I/O port specified by Port. The value written to the I/O port is
 517   returned. This function must guarantee that all I/O read and write operations
 518   are serialized.
 519
 520   If 16-bit I/O port operations are not supported, then ASSERT().
 521
 522   @param  Port          The I/O port to write.
 523   @param  AndData       The value to AND with the read value from the I/O port.
 524
 525   @return The value written back to the I/O port.
 526
 527 **/
 528 UINT16
 529 EFIAPI
 530 S3IoAnd16 (
 531   IN UINTN              Port,
 532   IN UINT16             AndData
 533   )
 534 {
 535   return InternalSaveIoWrite16ValueToBootScript (Port, IoAnd16 (Port, AndData));
 536 }
 537
 538 /**
 539   Reads a 16-bit I/O port, performs a bitwise AND followed by a bitwise
 540   inclusive OR, and writes the result back to the 16-bit I/O port and saves
 541   the value in the S3 script to be replayed on S3 resume.
 542
 543   Reads the 16-bit I/O port specified by Port, performs a bitwise AND between
 544   the read result and the value specified by AndData, performs a bitwise OR
 545   between the result of the AND operation and the value specified by OrData,
 546   and writes the result to the 16-bit I/O port specified by Port. The value
 547   written to the I/O port is returned. This function must guarantee that all
 548   I/O read and write operations are serialized.
 549
 550   If 16-bit I/O port operations are not supported, then ASSERT().
 551
 552   @param  Port          The I/O port to write.
 553   @param  AndData       The value to AND with the read value from the I/O port.
 554   @param  OrData        The value to OR with the result of the AND operation.
 555
 556   @return The value written back to the I/O port.
 557
 558 **/
 559 UINT16
 560 EFIAPI
 561 S3IoAndThenOr16 (
 562   IN UINTN              Port,
 563   IN UINT16             AndData,
 564   IN UINT16             OrData
 565   )
 566 {
 567   return InternalSaveIoWrite16ValueToBootScript (Port, IoAndThenOr16 (Port, AndData, OrData));
 568 }
 569
 570 /**
 571   Reads a bit field of an I/O register saves the value in the S3 script to be
 572   replayed on S3 resume.
 573
 574   Reads the bit field in a 16-bit I/O register. The bit field is specified by
 575   the StartBit and the EndBit. The value of the bit field is returned.
 576
 577   If 16-bit I/O port operations are not supported, then ASSERT().
 578   If StartBit is greater than 15, then ASSERT().
 579   If EndBit is greater than 15, then ASSERT().
 580   If EndBit is less than StartBit, then ASSERT().
 581
 582   @param  Port          The I/O port to read.
 583   @param  StartBit      The ordinal of the least significant bit in the bit field.
 584                         Range 0..15.
 585   @param  EndBit        The ordinal of the most significant bit in the bit field.
 586                         Range 0..15.
 587
 588   @return The value read.
 589
 590 **/
 591 UINT16
 592 EFIAPI
 593 S3IoBitFieldRead16 (
 594   IN UINTN              Port,
 595   IN UINTN              StartBit,
 596   IN UINTN              EndBit
 597   )
 598 {
 599   return InternalSaveIoWrite16ValueToBootScript (Port, IoBitFieldRead16 (Port, StartBit, EndBit));
 600 }
 601
 602 /**
 603   Writes a bit field to an I/O register and saves the value in the S3 script
 604   to be replayed on S3 resume.
 605
 606   Writes Value to the bit field of the I/O register. The bit field is specified
 607   by the StartBit and the EndBit. All other bits in the destination I/O
 608   register are preserved. The value written to the I/O port is returned. Extra
 609   left bits in Value are stripped.
 610
 611   If 16-bit I/O port operations are not supported, then ASSERT().
 612   If StartBit is greater than 15, then ASSERT().
 613   If EndBit is greater than 15, then ASSERT().
 614   If EndBit is less than StartBit, then ASSERT().
 615   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 616
 617   @param  Port          The I/O port to write.
 618   @param  StartBit      The ordinal of the least significant bit in the bit field.
 619                         Range 0..15.
 620   @param  EndBit        The ordinal of the most significant bit in the bit field.
 621                         Range 0..15.
 622   @param  Value         New value of the bit field.
 623
 624   @return The value written back to the I/O port.
 625
 626 **/
 627 UINT16
 628 EFIAPI
 629 S3IoBitFieldWrite16 (
 630   IN UINTN              Port,
 631   IN UINTN              StartBit,
 632   IN UINTN              EndBit,
 633   IN UINT16             Value
 634   )
 635 {
 636   return InternalSaveIoWrite16ValueToBootScript (Port, IoBitFieldWrite16 (Port, StartBit, EndBit, Value));
 637 }
 638
 639 /**
 640   Reads a bit field in a 16-bit port, performs a bitwise OR, and writes the
 641   result back to the bit field in the 16-bit port and saves the value in the
 642   S3 script to be replayed on S3 resume.
 643
 644   Reads the 16-bit I/O port specified by Port, performs a bitwise OR
 645   between the read result and the value specified by OrData, and writes the
 646   result to the 16-bit I/O port specified by Port. The value written to the I/O
 647   port is returned. This function must guarantee that all I/O read and write
 648   operations are serialized. Extra left bits in OrData are stripped.
 649
 650   If 16-bit I/O port operations are not supported, then ASSERT().
 651   If StartBit is greater than 15, then ASSERT().
 652   If EndBit is greater than 15, then ASSERT().
 653   If EndBit is less than StartBit, then ASSERT().
 654   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 655
 656   @param  Port          The I/O port to write.
 657   @param  StartBit      The ordinal of the least significant bit in the bit field.
 658                         Range 0..15.
 659   @param  EndBit        The ordinal of the most significant bit in the bit field.
 660                         Range 0..15.
 661   @param  OrData        The value to OR with the read value from the I/O port.
 662
 663   @return The value written back to the I/O port.
 664
 665 **/
 666 UINT16
 667 EFIAPI
 668 S3IoBitFieldOr16 (
 669   IN UINTN              Port,
 670   IN UINTN              StartBit,
 671   IN UINTN              EndBit,
 672   IN UINT16             OrData
 673   )
 674 {
 675   return InternalSaveIoWrite16ValueToBootScript (Port, IoBitFieldOr16 (Port, StartBit, EndBit, OrData));
 676 }
 677
 678 /**
 679   Reads a bit field in a 16-bit port, performs a bitwise AND, and writes the
 680   result back to the bit field in the 16-bit port and saves the value in the
 681   S3 script to be replayed on S3 resume.
 682
 683   Reads the 16-bit I/O port specified by Port, performs a bitwise AND between
 684   the read result and the value specified by AndData, and writes the result to
 685   the 16-bit I/O port specified by Port. The value written to the I/O port is
 686   returned. This function must guarantee that all I/O read and write operations
 687   are serialized. Extra left bits in AndData are stripped.
 688
 689   If 16-bit I/O port operations are not supported, then ASSERT().
 690   If StartBit is greater than 15, then ASSERT().
 691   If EndBit is greater than 15, then ASSERT().
 692   If EndBit is less than StartBit, then ASSERT().
 693   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 694
 695   @param  Port          The I/O port to write.
 696   @param  StartBit      The ordinal of the least significant bit in the bit field.
 697                         Range 0..15.
 698   @param  EndBit        The ordinal of the most significant bit in the bit field.
 699                         Range 0..15.
 700   @param  AndData       The value to AND with the read value from the I/O port.
 701
 702   @return The value written back to the I/O port.
 703
 704 **/
 705 UINT16
 706 EFIAPI
 707 S3IoBitFieldAnd16 (
 708   IN UINTN              Port,
 709   IN UINTN              StartBit,
 710   IN UINTN              EndBit,
 711   IN UINT16             AndData
 712   )
 713 {
 714   return InternalSaveIoWrite16ValueToBootScript (Port, IoBitFieldAnd16 (Port, StartBit, EndBit, AndData));
 715 }
 716
 717 /**
 718   Reads a bit field in a 16-bit port, performs a bitwise AND followed by a
 719   bitwise OR, and writes the result back to the bit field in the
 720   16-bit port  and saves the value in the S3 script to be replayed on S3
 721   resume.
 722
 723   Reads the 16-bit I/O port specified by Port, performs a bitwise AND followed
 724   by a bitwise OR between the read result and the value specified by
 725   AndData, and writes the result to the 16-bit I/O port specified by Port. The
 726   value written to the I/O port is returned. This function must guarantee that
 727   all I/O read and write operations are serialized. Extra left bits in both
 728   AndData and OrData are stripped.
 729
 730   If 16-bit I/O port operations are not supported, then ASSERT().
 731   If StartBit is greater than 15, then ASSERT().
 732   If EndBit is greater than 15, then ASSERT().
 733   If EndBit is less than StartBit, then ASSERT().
 734   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 735   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 736
 737   @param  Port          The I/O port to write.
 738   @param  StartBit      The ordinal of the least significant bit in the bit field.
 739                         Range 0..15.
 740   @param  EndBit        The ordinal of the most significant bit in the bit field.
 741                         Range 0..15.
 742   @param  AndData       The value to AND with the read value from the I/O port.
 743   @param  OrData        The value to OR with the result of the AND operation.
 744
 745   @return The value written back to the I/O port.
 746
 747 **/
 748 UINT16
 749 EFIAPI
 750 S3IoBitFieldAndThenOr16 (
 751   IN UINTN              Port,
 752   IN UINTN              StartBit,
 753   IN UINTN              EndBit,
 754   IN UINT16             AndData,
 755   IN UINT16             OrData
 756   )
 757 {
 758   return InternalSaveIoWrite16ValueToBootScript (Port, IoBitFieldAndThenOr16 (Port, StartBit, EndBit, AndData, OrData));
 759 }
 760
 761 /**
 762   Saves a 32-bit I/O port value to the boot script.
 763
 764   This internal worker function saves a 32-bit I/O port value in the S3 script
 765   to be replayed on S3 resume.
 766
 767   If the saving process fails, then ASSERT().
 768
 769   @param  Port          The I/O port to write.
 770   @param  Value         The value saved to boot script.
 771
 772   @return Value.
 773
 774 **/
 775 UINT32
 776 InternalSaveIoWrite32ValueToBootScript (
 777   IN UINTN              Port,
 778   IN UINT32             Value
 779   )
 780 {
 781   InternalSaveIoWriteValueToBootScript (S3BootScriptWidthUint32, Port, &Value);
 782
 783   return Value;
 784 }
 785
 786 /**
 787   Reads a 32-bit I/O port and saves the value in the S3 script to be replayed
 788   on S3 resume.
 789
 790   Reads the 32-bit I/O port specified by Port. The 32-bit read value is returned.
 791   This function must guarantee that all I/O read and write operations are
 792   serialized.
 793
 794   If 32-bit I/O port operations are not supported, then ASSERT().
 795
 796   @param  Port          The I/O port to read.
 797
 798   @return The value read.
 799
 800 **/
 801 UINT32
 802 EFIAPI
 803 S3IoRead32 (
 804   IN UINTN              Port
 805   )
 806 {
 807   return InternalSaveIoWrite32ValueToBootScript (Port, IoRead32 (Port));
 808 }
 809
 810 /**
 811   Writes a 32-bit I/O port and saves the value in the S3 script to be replayed
 812   on S3 resume.
 813
 814   Writes the 32-bit I/O port specified by Port with the value specified by Value
 815   and returns Value. This function must guarantee that all I/O read and write
 816   operations are serialized.
 817
 818   If 32-bit I/O port operations are not supported, then ASSERT().
 819
 820   @param  Port          The I/O port to write.
 821   @param  Value         The value to write to the I/O port.
 822
 823   @return The value written the I/O port.
 824
 825 **/
 826 UINT32
 827 EFIAPI
 828 S3IoWrite32 (
 829   IN UINTN              Port,
 830   IN UINT32             Value
 831   )
 832 {
 833   return InternalSaveIoWrite32ValueToBootScript (Port, IoWrite32 (Port, Value));
 834 }
 835
 836 /**
 837   Reads a 32-bit I/O port, performs a bitwise OR, and writes the
 838   result back to the 32-bit I/O port and saves the value in the S3 script to
 839   be replayed on S3 resume.
 840
 841   Reads the 32-bit I/O port specified by Port, performs a bitwise OR
 842   between the read result and the value specified by OrData, and writes the
 843   result to the 32-bit I/O port specified by Port. The value written to the I/O
 844   port is returned. This function must guarantee that all I/O read and write
 845   operations are serialized.
 846
 847   If 32-bit I/O port operations are not supported, then ASSERT().
 848
 849   @param  Port          The I/O port to write.
 850   @param  OrData        The value to OR with the read value from the I/O port.
 851
 852   @return The value written back to the I/O port.
 853
 854 **/
 855 UINT32
 856 EFIAPI
 857 S3IoOr32 (
 858   IN UINTN              Port,
 859   IN UINT32             OrData
 860   )
 861 {
 862   return InternalSaveIoWrite32ValueToBootScript (Port, IoOr32 (Port, OrData));
 863 }
 864
 865 /**
 866   Reads a 32-bit I/O port, performs a bitwise AND, and writes the result back
 867   to the 32-bit I/O port and saves the value in the S3 script to be replayed
 868   on S3 resume.
 869
 870   Reads the 32-bit I/O port specified by Port, performs a bitwise AND between
 871   the read result and the value specified by AndData, and writes the result to
 872   the 32-bit I/O port specified by Port. The value written to the I/O port is
 873   returned. This function must guarantee that all I/O read and write operations
 874   are serialized.
 875
 876   If 32-bit I/O port operations are not supported, then ASSERT().
 877
 878   @param  Port          The I/O port to write.
 879   @param  AndData       The value to AND with the read value from the I/O port.
 880
 881   @return The value written back to the I/O port.
 882
 883 **/
 884 UINT32
 885 EFIAPI
 886 S3IoAnd32 (
 887   IN UINTN              Port,
 888   IN UINT32             AndData
 889   )
 890 {
 891   return InternalSaveIoWrite32ValueToBootScript (Port, IoAnd32 (Port, AndData));
 892 }
 893
 894 /**
 895   Reads a 32-bit I/O port, performs a bitwise AND followed by a bitwise
 896   inclusive OR, and writes the result back to the 32-bit I/O port and saves
 897   the value in the S3 script to be replayed on S3 resume.
 898
 899   Reads the 32-bit I/O port specified by Port, performs a bitwise AND between
 900   the read result and the value specified by AndData, performs a bitwise OR
 901   between the result of the AND operation and the value specified by OrData,
 902   and writes the result to the 32-bit I/O port specified by Port. The value
 903   written to the I/O port is returned. This function must guarantee that all
 904   I/O read and write operations are serialized.
 905
 906   If 32-bit I/O port operations are not supported, then ASSERT().
 907
 908   @param  Port          The I/O port to write.
 909   @param  AndData       The value to AND with the read value from the I/O port.
 910   @param  OrData        The value to OR with the result of the AND operation.
 911
 912   @return The value written back to the I/O port.
 913
 914 **/
 915 UINT32
 916 EFIAPI
 917 S3IoAndThenOr32 (
 918   IN UINTN              Port,
 919   IN UINT32             AndData,
 920   IN UINT32             OrData
 921   )
 922 {
 923   return InternalSaveIoWrite32ValueToBootScript (Port, IoAndThenOr32 (Port, AndData, OrData));
 924 }
 925
 926 /**
 927   Reads a bit field of an I/O register and saves the value in the S3 script to
 928   be replayed on S3 resume.
 929
 930   Reads the bit field in a 32-bit I/O register. The bit field is specified by
 931   the StartBit and the EndBit. The value of the bit field is returned.
 932
 933   If 32-bit I/O port operations are not supported, then ASSERT().
 934   If StartBit is greater than 31, then ASSERT().
 935   If EndBit is greater than 31, then ASSERT().
 936   If EndBit is less than StartBit, then ASSERT().
 937
 938   @param  Port          The I/O port to read.
 939   @param  StartBit      The ordinal of the least significant bit in the bit field.
 940                         Range 0..31.
 941   @param  EndBit        The ordinal of the most significant bit in the bit field.
 942                         Range 0..31.
 943
 944   @return The value read.
 945
 946 **/
 947 UINT32
 948 EFIAPI
 949 S3IoBitFieldRead32 (
 950   IN UINTN              Port,
 951   IN UINTN              StartBit,
 952   IN UINTN              EndBit
 953   )
 954 {
 955   return InternalSaveIoWrite32ValueToBootScript (Port, IoBitFieldRead32 (Port, StartBit, EndBit));
 956 }
 957
 958 /**
 959   Writes a bit field to an I/O register and saves the value in the S3 script to
 960   be replayed on S3 resume.
 961
 962   Writes Value to the bit field of the I/O register. The bit field is specified
 963   by the StartBit and the EndBit. All other bits in the destination I/O
 964   register are preserved. The value written to the I/O port is returned. Extra
 965   left bits in Value are stripped.
 966
 967   If 32-bit I/O port operations are not supported, then ASSERT().
 968   If StartBit is greater than 31, then ASSERT().
 969   If EndBit is greater than 31, then ASSERT().
 970   If EndBit is less than StartBit, then ASSERT().
 971   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
 972
 973   @param  Port          The I/O port to write.
 974   @param  StartBit      The ordinal of the least significant bit in the bit field.
 975                         Range 0..31.
 976   @param  EndBit        The ordinal of the most significant bit in the bit field.
 977                         Range 0..31.
 978   @param  Value         New value of the bit field.
 979
 980   @return The value written back to the I/O port.
 981
 982 **/
 983 UINT32
 984 EFIAPI
 985 S3IoBitFieldWrite32 (
 986   IN UINTN              Port,
 987   IN UINTN              StartBit,
 988   IN UINTN              EndBit,
 989   IN UINT32             Value
 990   )
 991 {
 992   return InternalSaveIoWrite32ValueToBootScript (Port, IoBitFieldWrite32 (Port, StartBit, EndBit, Value));
 993 }
 994
 995 /**
 996   Reads a bit field in a 32-bit port, performs a bitwise OR, and writes the
 997   result back to the bit field in the 32-bit port and saves the value in the
 998   S3 script to be replayed on S3 resume.
 999
1000   Reads the 32-bit I/O port specified by Port, performs a bitwise OR
1001   between the read result and the value specified by OrData, and writes the
1002   result to the 32-bit I/O port specified by Port. The value written to the I/O
1003   port is returned. This function must guarantee that all I/O read and write
1004   operations are serialized. Extra left bits in OrData are stripped.
1005
1006   If 32-bit I/O port operations are not supported, then ASSERT().
1007   If StartBit is greater than 31, then ASSERT().
1008   If EndBit is greater than 31, then ASSERT().
1009   If EndBit is less than StartBit, then ASSERT().
1010   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1011
1012   @param  Port          The I/O port to write.
1013   @param  StartBit      The ordinal of the least significant bit in the bit field.
1014                         Range 0..31.
1015   @param  EndBit        The ordinal of the most significant bit in the bit field.
1016                         Range 0..31.
1017   @param  OrData        The value to OR with the read value from the I/O port.
1018
1019   @return The value written back to the I/O port.
1020
1021 **/
1022 UINT32
1023 EFIAPI
1024 S3IoBitFieldOr32 (
1025   IN UINTN              Port,
1026   IN UINTN              StartBit,
1027   IN UINTN              EndBit,
1028   IN UINT32             OrData
1029   )
1030 {
1031   return InternalSaveIoWrite32ValueToBootScript (Port, IoBitFieldOr32 (Port, StartBit, EndBit, OrData));
1032 }
1033
1034 /**
1035   Reads a bit field in a 32-bit port, performs a bitwise AND, and writes the
1036   result back to the bit field in the 32-bit port and saves the value in the
1037   S3 script to be replayed on S3 resume.
1038
1039   Reads the 32-bit I/O port specified by Port, performs a bitwise AND between
1040   the read result and the value specified by AndData, and writes the result to
1041   the 32-bit I/O port specified by Port. The value written to the I/O port is
1042   returned. This function must guarantee that all I/O read and write operations
1043   are serialized. Extra left bits in AndData are stripped.
1044
1045   If 32-bit I/O port operations are not supported, then ASSERT().
1046   If StartBit is greater than 31, then ASSERT().
1047   If EndBit is greater than 31, then ASSERT().
1048   If EndBit is less than StartBit, then ASSERT().
1049   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1050
1051   @param  Port          The I/O port to write.
1052   @param  StartBit      The ordinal of the least significant bit in the bit field.
1053                         Range 0..31.
1054   @param  EndBit        The ordinal of the most significant bit in the bit field.
1055                         Range 0..31.
1056   @param  AndData       The value to AND with the read value from the I/O port.
1057
1058   @return The value written back to the I/O port.
1059
1060 **/
1061 UINT32
1062 EFIAPI
1063 S3IoBitFieldAnd32 (
1064   IN UINTN              Port,
1065   IN UINTN              StartBit,
1066   IN UINTN              EndBit,
1067   IN UINT32             AndData
1068   )
1069 {
1070   return InternalSaveIoWrite32ValueToBootScript (Port, IoBitFieldAnd32 (Port, StartBit, EndBit, AndData));
1071 }
1072
1073 /**
1074   Reads a bit field in a 32-bit port, performs a bitwise AND followed by a
1075   bitwise OR, and writes the result back to the bit field in the
1076   32-bit port and saves the value in the S3 script to be replayed on S3
1077   resume.
1078
1079   Reads the 32-bit I/O port specified by Port, performs a bitwise AND followed
1080   by a bitwise OR between the read result and the value specified by
1081   AndData, and writes the result to the 32-bit I/O port specified by Port. The
1082   value written to the I/O port is returned. This function must guarantee that
1083   all I/O read and write operations are serialized. Extra left bits in both
1084   AndData and OrData are stripped.
1085
1086   If 32-bit I/O port operations are not supported, then ASSERT().
1087   If StartBit is greater than 31, then ASSERT().
1088   If EndBit is greater than 31, then ASSERT().
1089   If EndBit is less than StartBit, then ASSERT().
1090   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1091   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1092
1093   @param  Port          The I/O port to write.
1094   @param  StartBit      The ordinal of the least significant bit in the bit field.
1095                         Range 0..31.
1096   @param  EndBit        The ordinal of the most significant bit in the bit field.
1097                         Range 0..31.
1098   @param  AndData       The value to AND with the read value from the I/O port.
1099   @param  OrData        The value to OR with the result of the AND operation.
1100
1101   @return The value written back to the I/O port.
1102
1103 **/
1104 UINT32
1105 EFIAPI
1106 S3IoBitFieldAndThenOr32 (
1107   IN UINTN              Port,
1108   IN UINTN              StartBit,
1109   IN UINTN              EndBit,
1110   IN UINT32             AndData,
1111   IN UINT32             OrData
1112   )
1113 {
1114   return InternalSaveIoWrite32ValueToBootScript (Port, IoBitFieldAndThenOr32 (Port, StartBit, EndBit, AndData, OrData));
1115 }
1116
1117 /**
1118   Saves a 64-bit I/O port value to the boot script.
1119
1120   This internal worker function saves a 64-bit I/O port value in the S3 script
1121   to be replayed on S3 resume.
1122
1123   If the saving process fails, then ASSERT().
1124
1125   @param  Port          The I/O port to write.
1126   @param  Value         The value saved to boot script.
1127
1128   @return Value.
1129
1130 **/
1131 UINT64
1132 InternalSaveIoWrite64ValueToBootScript (
1133   IN UINTN              Port,
1134   IN UINT64             Value
1135   )
1136 {
1137   InternalSaveIoWriteValueToBootScript (S3BootScriptWidthUint64, Port, &Value);
1138
1139   return Value;
1140 }
1141
1142 /**
1143   Reads a 64-bit I/O port and saves the value in the S3 script to be replayed
1144   on S3 resume.
1145
1146   Reads the 64-bit I/O port specified by Port. The 64-bit read value is returned.
1147   This function must guarantee that all I/O read and write operations are
1148   serialized.
1149
1150   If 64-bit I/O port operations are not supported, then ASSERT().
1151
1152   @param  Port          The I/O port to read.
1153
1154   @return The value read.
1155
1156 **/
1157 UINT64
1158 EFIAPI
1159 S3IoRead64 (
1160   IN UINTN              Port
1161   )
1162 {
1163   return InternalSaveIoWrite64ValueToBootScript (Port, IoRead64 (Port));
1164 }
1165
1166 /**
1167   Writes a 64-bit I/O port and saves the value in the S3 script to be replayed
1168   on S3 resume.
1169
1170   Writes the 64-bit I/O port specified by Port with the value specified by Value
1171   and returns Value. This function must guarantee that all I/O read and write
1172   operations are serialized.
1173
1174   If 64-bit I/O port operations are not supported, then ASSERT().
1175
1176   @param  Port          The I/O port to write.
1177   @param  Value         The value to write to the I/O port.
1178
1179   @return The value written the I/O port.
1180
1181 **/
1182 UINT64
1183 EFIAPI
1184 S3IoWrite64 (
1185   IN UINTN              Port,
1186   IN UINT64             Value
1187   )
1188 {
1189   return InternalSaveIoWrite64ValueToBootScript (Port, IoWrite64 (Port, Value));
1190 }
1191
1192 /**
1193   Reads a 64-bit I/O port, performs a bitwise OR, and writes the
1194   result back to the 64-bit I/O port and saves the value in the S3 script to
1195   be replayed on S3 resume.
1196
1197   Reads the 64-bit I/O port specified by Port, performs a bitwise OR
1198   between the read result and the value specified by OrData, and writes the
1199   result to the 64-bit I/O port specified by Port. The value written to the I/O
1200   port is returned. This function must guarantee that all I/O read and write
1201   operations are serialized.
1202
1203   If 64-bit I/O port operations are not supported, then ASSERT().
1204
1205   @param  Port          The I/O port to write.
1206   @param  OrData        The value to OR with the read value from the I/O port.
1207
1208   @return The value written back to the I/O port.
1209
1210 **/
1211 UINT64
1212 EFIAPI
1213 S3IoOr64 (
1214   IN UINTN              Port,
1215   IN UINT64             OrData
1216   )
1217 {
1218   return InternalSaveIoWrite64ValueToBootScript (Port, IoOr64 (Port, OrData));
1219 }
1220
1221 /**
1222   Reads a 64-bit I/O port, performs a bitwise AND, and writes the result back
1223   to the 64-bit I/O port and saves the value in the S3 script to be replayed
1224   on S3 resume.
1225
1226   Reads the 64-bit I/O port specified by Port, performs a bitwise AND between
1227   the read result and the value specified by AndData, and writes the result to
1228   the 64-bit I/O port specified by Port. The value written to the I/O port is
1229   returned. This function must guarantee that all I/O read and write operations
1230   are serialized.
1231
1232   If 64-bit I/O port operations are not supported, then ASSERT().
1233
1234   @param  Port          The I/O port to write.
1235   @param  AndData       The value to AND with the read value from the I/O port.
1236
1237   @return The value written back to the I/O port.
1238
1239 **/
1240 UINT64
1241 EFIAPI
1242 S3IoAnd64 (
1243   IN UINTN              Port,
1244   IN UINT64             AndData
1245   )
1246 {
1247   return InternalSaveIoWrite64ValueToBootScript (Port, IoAnd64 (Port, AndData));
1248 }
1249
1250 /**
1251   Reads a 64-bit I/O port, performs a bitwise AND followed by a bitwise
1252   inclusive OR, and writes the result back to the 64-bit I/O port and saves
1253   the value in the S3 script to be replayed on S3 resume.
1254
1255   Reads the 64-bit I/O port specified by Port, performs a bitwise AND between
1256   the read result and the value specified by AndData, performs a bitwise OR
1257   between the result of the AND operation and the value specified by OrData,
1258   and writes the result to the 64-bit I/O port specified by Port. The value
1259   written to the I/O port is returned. This function must guarantee that all
1260   I/O read and write operations are serialized.
1261
1262   If 64-bit I/O port operations are not supported, then ASSERT().
1263
1264   @param  Port          The I/O port to write.
1265   @param  AndData       The value to AND with the read value from the I/O port.
1266   @param  OrData        The value to OR with the result of the AND operation.
1267
1268   @return The value written back to the I/O port.
1269
1270 **/
1271 UINT64
1272 EFIAPI
1273 S3IoAndThenOr64 (
1274   IN UINTN              Port,
1275   IN UINT64             AndData,
1276   IN UINT64             OrData
1277   )
1278 {
1279   return InternalSaveIoWrite64ValueToBootScript (Port, IoAndThenOr64 (Port, AndData, OrData));
1280 }
1281
1282 /**
1283   Reads a bit field of an I/O register and saves the value in the S3 script to
1284   be replayed on S3 resume.
1285
1286   Reads the bit field in a 64-bit I/O register. The bit field is specified by
1287   the StartBit and the EndBit. The value of the bit field is returned.
1288
1289   If 64-bit I/O port operations are not supported, then ASSERT().
1290   If StartBit is greater than 63, then ASSERT().
1291   If EndBit is greater than 63, then ASSERT().
1292   If EndBit is less than StartBit, then ASSERT().
1293
1294   @param  Port          The I/O port to read.
1295   @param  StartBit      The ordinal of the least significant bit in the bit field.
1296                         Range 0..63.
1297   @param  EndBit        The ordinal of the most significant bit in the bit field.
1298                         Range 0..63.
1299
1300   @return The value read.
1301
1302 **/
1303 UINT64
1304 EFIAPI
1305 S3IoBitFieldRead64 (
1306   IN UINTN              Port,
1307   IN UINTN              StartBit,
1308   IN UINTN              EndBit
1309   )
1310 {
1311   return InternalSaveIoWrite64ValueToBootScript (Port, IoBitFieldRead64 (Port, StartBit, EndBit));
1312 }
1313
1314 /**
1315   Writes a bit field to an I/O register and saves the value in the S3 script to
1316   be replayed on S3 resume.
1317
1318   Writes Value to the bit field of the I/O register. The bit field is specified
1319   by the StartBit and the EndBit. All other bits in the destination I/O
1320   register are preserved. The value written to the I/O port is returned. Extra
1321   left bits in Value are stripped.
1322
1323   If 64-bit I/O port operations are not supported, then ASSERT().
1324   If StartBit is greater than 63, then ASSERT().
1325   If EndBit is greater than 63, then ASSERT().
1326   If EndBit is less than StartBit, then ASSERT().
1327   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1328
1329   @param  Port          The I/O port to write.
1330   @param  StartBit      The ordinal of the least significant bit in the bit field.
1331                         Range 0..63.
1332   @param  EndBit        The ordinal of the most significant bit in the bit field.
1333                         Range 0..63.
1334   @param  Value         New value of the bit field.
1335
1336   @return The value written back to the I/O port.
1337
1338 **/
1339 UINT64
1340 EFIAPI
1341 S3IoBitFieldWrite64 (
1342   IN UINTN              Port,
1343   IN UINTN              StartBit,
1344   IN UINTN              EndBit,
1345   IN UINT64             Value
1346   )
1347 {
1348   return InternalSaveIoWrite64ValueToBootScript (Port, IoBitFieldWrite64 (Port, StartBit, EndBit, Value));
1349 }
1350
1351 /**
1352   Reads a bit field in a 64-bit port, performs a bitwise OR, and writes the
1353   result back to the bit field in the 64-bit port and saves the value in the
1354   S3 script to be replayed on S3 resume.
1355
1356   Reads the 64-bit I/O port specified by Port, performs a bitwise OR
1357   between the read result and the value specified by OrData, and writes the
1358   result to the 64-bit I/O port specified by Port. The value written to the I/O
1359   port is returned. This function must guarantee that all I/O read and write
1360   operations are serialized. Extra left bits in OrData are stripped.
1361
1362   If 64-bit I/O port operations are not supported, then ASSERT().
1363   If StartBit is greater than 63, then ASSERT().
1364   If EndBit is greater than 63, then ASSERT().
1365   If EndBit is less than StartBit, then ASSERT().
1366   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1367
1368   @param  Port          The I/O port to write.
1369   @param  StartBit      The ordinal of the least significant bit in the bit field.
1370                         Range 0..63.
1371   @param  EndBit        The ordinal of the most significant bit in the bit field.
1372                         Range 0..63.
1373   @param  OrData        The value to OR with the read value from the I/O port.
1374
1375   @return The value written back to the I/O port.
1376
1377 **/
1378 UINT64
1379 EFIAPI
1380 S3IoBitFieldOr64 (
1381   IN UINTN              Port,
1382   IN UINTN              StartBit,
1383   IN UINTN              EndBit,
1384   IN UINT64             OrData
1385   )
1386 {
1387   return InternalSaveIoWrite64ValueToBootScript (Port, IoBitFieldOr64 (Port, StartBit, EndBit, OrData));
1388 }
1389
1390 /**
1391   Reads a bit field in a 64-bit port, performs a bitwise AND, and writes the
1392   result back to the bit field in the 64-bit port and saves the value in the
1393   S3 script to be replayed on S3 resume.
1394
1395   Reads the 64-bit I/O port specified by Port, performs a bitwise AND between
1396   the read result and the value specified by AndData, and writes the result to
1397   the 64-bit I/O port specified by Port. The value written to the I/O port is
1398   returned. This function must guarantee that all I/O read and write operations
1399   are serialized. Extra left bits in AndData are stripped.
1400
1401   If 64-bit I/O port operations are not supported, then ASSERT().
1402   If StartBit is greater than 63, then ASSERT().
1403   If EndBit is greater than 63, then ASSERT().
1404   If EndBit is less than StartBit, then ASSERT().
1405   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1406
1407   @param  Port          The I/O port to write.
1408   @param  StartBit      The ordinal of the least significant bit in the bit field.
1409                         Range 0..63.
1410   @param  EndBit        The ordinal of the most significant bit in the bit field.
1411                         Range 0..63.
1412   @param  AndData       The value to AND with the read value from the I/O port.
1413
1414   @return The value written back to the I/O port.
1415
1416 **/
1417 UINT64
1418 EFIAPI
1419 S3IoBitFieldAnd64 (
1420   IN UINTN              Port,
1421   IN UINTN              StartBit,
1422   IN UINTN              EndBit,
1423   IN UINT64             AndData
1424   )
1425 {
1426   return InternalSaveIoWrite64ValueToBootScript (Port, IoBitFieldAnd64 (Port, StartBit, EndBit, AndData));
1427 }
1428
1429 /**
1430   Reads a bit field in a 64-bit port, performs a bitwise AND followed by a
1431   bitwise OR, and writes the result back to the bit field in the
1432   64-bit port and saves the value in the S3 script to be replayed on S3
1433   resume.
1434
1435   Reads the 64-bit I/O port specified by Port, performs a bitwise AND followed
1436   by a bitwise OR between the read result and the value specified by
1437   AndData, and writes the result to the 64-bit I/O port specified by Port. The
1438   value written to the I/O port is returned. This function must guarantee that
1439   all I/O read and write operations are serialized. Extra left bits in both
1440   AndData and OrData are stripped.
1441
1442   If 64-bit I/O port operations are not supported, then ASSERT().
1443   If StartBit is greater than 63, then ASSERT().
1444   If EndBit is greater than 63, then ASSERT().
1445   If EndBit is less than StartBit, then ASSERT().
1446   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1447   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1448
1449   @param  Port          The I/O port to write.
1450   @param  StartBit      The ordinal of the least significant bit in the bit field.
1451                         Range 0..63.
1452   @param  EndBit        The ordinal of the most significant bit in the bit field.
1453                         Range 0..63.
1454   @param  AndData       The value to AND with the read value from the I/O port.
1455   @param  OrData        The value to OR with the result of the AND operation.
1456
1457   @return The value written back to the I/O port.
1458
1459 **/
1460 UINT64
1461 EFIAPI
1462 S3IoBitFieldAndThenOr64 (
1463   IN UINTN              Port,
1464   IN UINTN              StartBit,
1465   IN UINTN              EndBit,
1466   IN UINT64             AndData,
1467   IN UINT64             OrData
1468   )
1469 {
1470   return InternalSaveIoWrite64ValueToBootScript (Port, IoBitFieldAndThenOr64 (Port, StartBit, EndBit, AndData, OrData));
1471 }
1472
1473 /**
1474   Saves an MMIO register value to the boot script.
1475
1476   This internal worker function saves an MMIO register value in the S3 script
1477   to be replayed on S3 resume.
1478
1479   If the saving process fails, then ASSERT().
1480
1481   @param  Width         The width of MMIO register.
1482   @param  Address       The MMIO register to write.
1483   @param  Buffer        The buffer containing value.
1484
1485 **/
1486 VOID
1487 InternalSaveMmioWriteValueToBootScript (
1488   IN S3_BOOT_SCRIPT_LIB_WIDTH  Width,
1489   IN UINTN                  Address,
1490   IN VOID                   *Buffer
1491   )
1492 {
1493   RETURN_STATUS            Status;
1494
1495   Status = S3BootScriptSaveMemWrite (
1496              Width,
1497              Address,
1498              1,
1499              Buffer
1500              );
1501   ASSERT (Status == RETURN_SUCCESS);
1502 }
1503
1504 /**
1505   Saves an 8-bit MMIO register value to the boot script.
1506
1507   This internal worker function saves an 8-bit MMIO register value in the S3 script
1508   to be replayed on S3 resume.
1509
1510   If the saving process fails, then ASSERT().
1511
1512   @param  Address       The MMIO register to write.
1513   @param  Value         The value saved to boot script.
1514
1515   @return Value.
1516
1517 **/
1518 UINT8
1519 InternalSaveMmioWrite8ValueToBootScript (
1520   IN UINTN              Address,
1521   IN UINT8              Value
1522   )
1523 {
1524   InternalSaveMmioWriteValueToBootScript (S3BootScriptWidthUint8, Address, &Value);
1525
1526   return Value;
1527 }
1528
1529 /**
1530   Reads an 8-bit MMIO register and saves the value in the S3 script to be
1531   replayed on S3 resume.
1532
1533   Reads the 8-bit MMIO register specified by Address. The 8-bit read value is
1534   returned. This function must guarantee that all MMIO read and write
1535   operations are serialized.
1536
1537   If 8-bit MMIO register operations are not supported, then ASSERT().
1538
1539   @param  Address       The MMIO register to read.
1540
1541   @return The value read.
1542
1543 **/
1544 UINT8
1545 EFIAPI
1546 S3MmioRead8 (
1547   IN UINTN              Address
1548   )
1549 {
1550   return InternalSaveMmioWrite8ValueToBootScript (Address, MmioRead8 (Address));
1551 }
1552
1553 /**
1554   Writes an 8-bit MMIO register and saves the value in the S3 script to be
1555   replayed on S3 resume.
1556
1557   Writes the 8-bit MMIO register specified by Address with the value specified
1558   by Value and returns Value. This function must guarantee that all MMIO read
1559   and write operations are serialized.
1560
1561   If 8-bit MMIO register operations are not supported, then ASSERT().
1562
1563   @param  Address       The MMIO register to write.
1564   @param  Value         The value to write to the MMIO register.
1565
1566   @return The value written the MMIO register.
1567
1568 **/
1569 UINT8
1570 EFIAPI
1571 S3MmioWrite8 (
1572   IN UINTN              Address,
1573   IN UINT8              Value
1574   )
1575 {
1576   return InternalSaveMmioWrite8ValueToBootScript (Address, MmioWrite8 (Address, Value));
1577 }
1578
1579 /**
1580   Reads an 8-bit MMIO register, performs a bitwise OR, and writes the
1581   result back to the 8-bit MMIO register and saves the value in the S3 script
1582   to be replayed on S3 resume.
1583
1584   Reads the 8-bit MMIO register specified by Address, performs a bitwise
1585   inclusive OR between the read result and the value specified by OrData, and
1586   writes the result to the 8-bit MMIO register specified by Address. The value
1587   written to the MMIO register is returned. This function must guarantee that
1588   all MMIO read and write operations are serialized.
1589
1590   If 8-bit MMIO register operations are not supported, then ASSERT().
1591
1592   @param  Address       The MMIO register to write.
1593   @param  OrData        The value to OR with the read value from the MMIO register.
1594
1595   @return The value written back to the MMIO register.
1596
1597 **/
1598 UINT8
1599 EFIAPI
1600 S3MmioOr8 (
1601   IN UINTN              Address,
1602   IN UINT8              OrData
1603   )
1604 {
1605   return InternalSaveMmioWrite8ValueToBootScript (Address, MmioOr8 (Address, OrData));
1606 }
1607
1608 /**
1609   Reads an 8-bit MMIO register, performs a bitwise AND, and writes the result
1610   back to the 8-bit MMIO register and saves the value in the S3 script to be
1611   replayed on S3 resume.
1612
1613   Reads the 8-bit MMIO register specified by Address, performs a bitwise AND
1614   between the read result and the value specified by AndData, and writes the
1615   result to the 8-bit MMIO register specified by Address. The value written to
1616   the MMIO register is returned. This function must guarantee that all MMIO
1617   read and write operations are serialized.
1618
1619   If 8-bit MMIO register operations are not supported, then ASSERT().
1620
1621   @param  Address       The MMIO register to write.
1622   @param  AndData       The value to AND with the read value from the MMIO register.
1623
1624   @return The value written back to the MMIO register.
1625
1626 **/
1627 UINT8
1628 EFIAPI
1629 S3MmioAnd8 (
1630   IN UINTN              Address,
1631   IN UINT8              AndData
1632   )
1633 {
1634   return InternalSaveMmioWrite8ValueToBootScript (Address, MmioAnd8 (Address, AndData));
1635 }
1636
1637 /**
1638   Reads an 8-bit MMIO register, performs a bitwise AND followed by a bitwise
1639   inclusive OR, and writes the result back to the 8-bit MMIO register and saves
1640   the value in the S3 script to be replayed on S3 resume.
1641
1642   Reads the 8-bit MMIO register specified by Address, performs a bitwise AND
1643   between the read result and the value specified by AndData, performs a
1644   bitwise OR between the result of the AND operation and the value specified by
1645   OrData, and writes the result to the 8-bit MMIO register specified by
1646   Address. The value written to the MMIO register is returned. This function
1647   must guarantee that all MMIO read and write operations are serialized.
1648
1649   If 8-bit MMIO register operations are not supported, then ASSERT().
1650
1651   @param  Address       The MMIO register to write.
1652   @param  AndData       The value to AND with the read value from the MMIO register.
1653   @param  OrData        The value to OR with the result of the AND operation.
1654
1655   @return The value written back to the MMIO register.
1656
1657 **/
1658 UINT8
1659 EFIAPI
1660 S3MmioAndThenOr8 (
1661   IN UINTN              Address,
1662   IN UINT8              AndData,
1663   IN UINT8              OrData
1664   )
1665 {
1666   return InternalSaveMmioWrite8ValueToBootScript (Address, MmioAndThenOr8 (Address, AndData, OrData));
1667 }
1668
1669 /**
1670   Reads a bit field of a MMIO register and saves the value in the S3 script to
1671   be replayed on S3 resume.
1672
1673   Reads the bit field in an 8-bit MMIO register. The bit field is specified by
1674   the StartBit and the EndBit. The value of the bit field is returned.
1675
1676   If 8-bit MMIO register operations are not supported, then ASSERT().
1677   If StartBit is greater than 7, then ASSERT().
1678   If EndBit is greater than 7, then ASSERT().
1679   If EndBit is less than StartBit, then ASSERT().
1680
1681   @param  Address       MMIO register to read.
1682   @param  StartBit      The ordinal of the least significant bit in the bit field.
1683                         Range 0..7.
1684   @param  EndBit        The ordinal of the most significant bit in the bit field.
1685                         Range 0..7.
1686
1687   @return The value read.
1688
1689 **/
1690 UINT8
1691 EFIAPI
1692 S3MmioBitFieldRead8 (
1693   IN UINTN              Address,
1694   IN UINTN              StartBit,
1695   IN UINTN              EndBit
1696   )
1697 {
1698   return InternalSaveMmioWrite8ValueToBootScript (Address, MmioBitFieldRead8 (Address, StartBit, EndBit));
1699 }
1700
1701 /**
1702   Writes a bit field to an MMIO register and saves the value in the S3 script to
1703   be replayed on S3 resume.
1704
1705   Writes Value to the bit field of the MMIO register. The bit field is
1706   specified by the StartBit and the EndBit. All other bits in the destination
1707   MMIO register are preserved. The new value of the 8-bit register is returned.
1708
1709   If 8-bit MMIO register operations are not supported, then ASSERT().
1710   If StartBit is greater than 7, then ASSERT().
1711   If EndBit is greater than 7, then ASSERT().
1712   If EndBit is less than StartBit, then ASSERT().
1713   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1714
1715   @param  Address       The MMIO register to write.
1716   @param  StartBit      The ordinal of the least significant bit in the bit field.
1717                         Range 0..7.
1718   @param  EndBit        The ordinal of the most significant bit in the bit field.
1719                         Range 0..7.
1720   @param  Value         New value of the bit field.
1721
1722   @return The value written back to the MMIO register.
1723
1724 **/
1725 UINT8
1726 EFIAPI
1727 S3MmioBitFieldWrite8 (
1728   IN UINTN              Address,
1729   IN UINTN              StartBit,
1730   IN UINTN              EndBit,
1731   IN UINT8              Value
1732   )
1733 {
1734   return InternalSaveMmioWrite8ValueToBootScript (Address, MmioBitFieldWrite8 (Address, StartBit, EndBit, Value));
1735 }
1736
1737 /**
1738   Reads a bit field in an 8-bit MMIO register, performs a bitwise OR, and
1739   writes the result back to the bit field in the 8-bit MMIO register and saves
1740   the value in the S3 script to be replayed on S3 resume.
1741
1742   Reads the 8-bit MMIO register specified by Address, performs a bitwise
1743   inclusive OR between the read result and the value specified by OrData, and
1744   writes the result to the 8-bit MMIO register specified by Address. The value
1745   written to the MMIO register is returned. This function must guarantee that
1746   all MMIO read and write operations are serialized. Extra left bits in OrData
1747   are stripped.
1748
1749   If 8-bit MMIO register operations are not supported, then ASSERT().
1750   If StartBit is greater than 7, then ASSERT().
1751   If EndBit is greater than 7, then ASSERT().
1752   If EndBit is less than StartBit, then ASSERT().
1753   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1754
1755   @param  Address       The MMIO register to write.
1756   @param  StartBit      The ordinal of the least significant bit in the bit field.
1757                         Range 0..7.
1758   @param  EndBit        The ordinal of the most significant bit in the bit field.
1759                         Range 0..7.
1760   @param  OrData        The value to OR with the read value from the MMIO register.
1761
1762   @return The value written back to the MMIO register.
1763
1764 **/
1765 UINT8
1766 EFIAPI
1767 S3MmioBitFieldOr8 (
1768   IN UINTN              Address,
1769   IN UINTN              StartBit,
1770   IN UINTN              EndBit,
1771   IN UINT8              OrData
1772   )
1773 {
1774   return InternalSaveMmioWrite8ValueToBootScript (Address, MmioBitFieldOr8 (Address, StartBit, EndBit, OrData));
1775 }
1776
1777 /**
1778   Reads a bit field in an 8-bit MMIO register, performs a bitwise AND, and
1779   writes the result back to the bit field in the 8-bit MMIO register and saves
1780   the value in the S3 script to be replayed on S3 resume.
1781
1782   Reads the 8-bit MMIO register specified by Address, performs a bitwise AND
1783   between the read result and the value specified by AndData, and writes the
1784   result to the 8-bit MMIO register specified by Address. The value written to
1785   the MMIO register is returned. This function must guarantee that all MMIO
1786   read and write operations are serialized. Extra left bits in AndData are
1787   stripped.
1788
1789   If 8-bit MMIO register operations are not supported, then ASSERT().
1790   If StartBit is greater than 7, then ASSERT().
1791   If EndBit is greater than 7, then ASSERT().
1792   If EndBit is less than StartBit, then ASSERT().
1793   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1794
1795   @param  Address       The MMIO register to write.
1796   @param  StartBit      The ordinal of the least significant bit in the bit field.
1797                         Range 0..7.
1798   @param  EndBit        The ordinal of the most significant bit in the bit field.
1799                         Range 0..7.
1800   @param  AndData       The value to AND with the read value from the MMIO register.
1801
1802   @return The value written back to the MMIO register.
1803
1804 **/
1805 UINT8
1806 EFIAPI
1807 S3MmioBitFieldAnd8 (
1808   IN UINTN              Address,
1809   IN UINTN              StartBit,
1810   IN UINTN              EndBit,
1811   IN UINT8              AndData
1812   )
1813 {
1814   return InternalSaveMmioWrite8ValueToBootScript (Address, MmioBitFieldAnd8 (Address, StartBit, EndBit, AndData));
1815 }
1816
1817 /**
1818   Reads a bit field in an 8-bit MMIO register, performs a bitwise AND followed
1819   by a bitwise OR, and writes the result back to the bit field in the
1820   8-bit MMIO register  and saves the value in the S3 script to be replayed
1821   on S3 resume.
1822
1823   Reads the 8-bit MMIO register specified by Address, performs a bitwise AND
1824   followed by a bitwise OR between the read result and the value
1825   specified by AndData, and writes the result to the 8-bit MMIO register
1826   specified by Address. The value written to the MMIO register is returned.
1827   This function must guarantee that all MMIO read and write operations are
1828   serialized. Extra left bits in both AndData and OrData are stripped.
1829
1830   If 8-bit MMIO register operations are not supported, then ASSERT().
1831   If StartBit is greater than 7, then ASSERT().
1832   If EndBit is greater than 7, then ASSERT().
1833   If EndBit is less than StartBit, then ASSERT().
1834   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1835   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
1836
1837   @param  Address       The MMIO register to write.
1838   @param  StartBit      The ordinal of the least significant bit in the bit field.
1839                         Range 0..7.
1840   @param  EndBit        The ordinal of the most significant bit in the bit field.
1841                         Range 0..7.
1842   @param  AndData       The value to AND with the read value from the MMIO register.
1843   @param  OrData        The value to OR with the result of the AND operation.
1844
1845   @return The value written back to the MMIO register.
1846
1847 **/
1848 UINT8
1849 EFIAPI
1850 S3MmioBitFieldAndThenOr8 (
1851   IN UINTN              Address,
1852   IN UINTN              StartBit,
1853   IN UINTN              EndBit,
1854   IN UINT8              AndData,
1855   IN UINT8              OrData
1856   )
1857 {
1858   return InternalSaveMmioWrite8ValueToBootScript (Address, MmioBitFieldAndThenOr8 (Address, StartBit, EndBit, AndData, OrData));
1859 }
1860
1861 /**
1862   Saves a 16-bit MMIO register value to the boot script.
1863
1864   This internal worker function saves a 16-bit MMIO register value in the S3 script
1865   to be replayed on S3 resume.
1866
1867   If the saving process fails, then ASSERT().
1868
1869   @param  Address       The MMIO register to write.
1870   @param  Value         The value saved to boot script.
1871
1872   @return Value.
1873
1874 **/
1875 UINT16
1876 InternalSaveMmioWrite16ValueToBootScript (
1877   IN UINTN              Address,
1878   IN UINT16             Value
1879   )
1880 {
1881   InternalSaveMmioWriteValueToBootScript (S3BootScriptWidthUint16, Address, &Value);
1882
1883   return Value;
1884 }
1885
1886 /**
1887   Reads a 16-bit MMIO register and saves the value in the S3 script to be replayed
1888   on S3 resume.
1889
1890   Reads the 16-bit MMIO register specified by Address. The 16-bit read value is
1891   returned. This function must guarantee that all MMIO read and write
1892   operations are serialized.
1893
1894   If 16-bit MMIO register operations are not supported, then ASSERT().
1895
1896   @param  Address       The MMIO register to read.
1897
1898   @return The value read.
1899
1900 **/
1901 UINT16
1902 EFIAPI
1903 S3MmioRead16 (
1904   IN UINTN              Address
1905   )
1906 {
1907   return InternalSaveMmioWrite16ValueToBootScript (Address, MmioRead16 (Address));
1908 }
1909
1910 /**
1911   Writes a 16-bit MMIO register and saves the value in the S3 script to be replayed
1912   on S3 resume.
1913
1914   Writes the 16-bit MMIO register specified by Address with the value specified
1915   by Value and returns Value. This function must guarantee that all MMIO read
1916   and write operations are serialized and saves the value in the S3 script to be
1917   replayed on S3 resume.
1918
1919   If 16-bit MMIO register operations are not supported, then ASSERT().
1920
1921   @param  Address       The MMIO register to write.
1922   @param  Value         The value to write to the MMIO register.
1923
1924   @return The value written the MMIO register.
1925
1926 **/
1927 UINT16
1928 EFIAPI
1929 S3MmioWrite16 (
1930   IN UINTN              Address,
1931   IN UINT16             Value
1932   )
1933 {
1934   return InternalSaveMmioWrite16ValueToBootScript (Address, MmioWrite16 (Address, Value));
1935 }
1936
1937 /**
1938   Reads a 16-bit MMIO register, performs a bitwise OR, and writes the
1939   result back to the 16-bit MMIO register and saves the value in the S3 script
1940   to be replayed on S3 resume.
1941
1942   Reads the 16-bit MMIO register specified by Address, performs a bitwise
1943   inclusive OR between the read result and the value specified by OrData, and
1944   writes the result to the 16-bit MMIO register specified by Address. The value
1945   written to the MMIO register is returned. This function must guarantee that
1946   all MMIO read and write operations are serialized.
1947
1948   If 16-bit MMIO register operations are not supported, then ASSERT().
1949
1950   @param  Address       The MMIO register to write.
1951   @param  OrData        The value to OR with the read value from the MMIO register.
1952
1953   @return The value written back to the MMIO register.
1954
1955 **/
1956 UINT16
1957 EFIAPI
1958 S3MmioOr16 (
1959   IN UINTN              Address,
1960   IN UINT16             OrData
1961   )
1962 {
1963   return InternalSaveMmioWrite16ValueToBootScript (Address, MmioOr16 (Address, OrData));
1964 }
1965
1966 /**
1967   Reads a 16-bit MMIO register, performs a bitwise AND, and writes the result
1968   back to the 16-bit MMIO register and saves the value in the S3 script to be
1969   replayed on S3 resume.
1970
1971   Reads the 16-bit MMIO register specified by Address, performs a bitwise AND
1972   between the read result and the value specified by AndData, and writes the
1973   result to the 16-bit MMIO register specified by Address. The value written to
1974   the MMIO register is returned. This function must guarantee that all MMIO
1975   read and write operations are serialized.
1976
1977   If 16-bit MMIO register operations are not supported, then ASSERT().
1978
1979   @param  Address       The MMIO register to write.
1980   @param  AndData       The value to AND with the read value from the MMIO register.
1981
1982   @return The value written back to the MMIO register.
1983
1984 **/
1985 UINT16
1986 EFIAPI
1987 S3MmioAnd16 (
1988   IN UINTN              Address,
1989   IN UINT16             AndData
1990   )
1991 {
1992   return InternalSaveMmioWrite16ValueToBootScript (Address, MmioAnd16 (Address, AndData));
1993 }
1994
1995 /**
1996   Reads a 16-bit MMIO register, performs a bitwise AND followed by a bitwise
1997   inclusive OR, and writes the result back to the 16-bit MMIO register and
1998   saves the value in the S3 script to be replayed on S3 resume.
1999
2000   Reads the 16-bit MMIO register specified by Address, performs a bitwise AND
2001   between the read result and the value specified by AndData, performs a
2002   bitwise OR between the result of the AND operation and the value specified by
2003   OrData, and writes the result to the 16-bit MMIO register specified by
2004   Address. The value written to the MMIO register is returned. This function
2005   must guarantee that all MMIO read and write operations are serialized.
2006
2007   If 16-bit MMIO register operations are not supported, then ASSERT().
2008
2009   @param  Address       The MMIO register to write.
2010   @param  AndData       The value to AND with the read value from the MMIO register.
2011   @param  OrData        The value to OR with the result of the AND operation.
2012
2013   @return The value written back to the MMIO register.
2014
2015 **/
2016 UINT16
2017 EFIAPI
2018 S3MmioAndThenOr16 (
2019   IN UINTN              Address,
2020   IN UINT16             AndData,
2021   IN UINT16             OrData
2022   )
2023 {
2024   return InternalSaveMmioWrite16ValueToBootScript (Address, MmioAndThenOr16 (Address, AndData, OrData));
2025 }
2026
2027 /**
2028   Reads a bit field of a MMIO register and saves the value in the S3 script to
2029   be replayed on S3 resume.
2030
2031   Reads the bit field in a 16-bit MMIO register. The bit field is specified by
2032   the StartBit and the EndBit. The value of the bit field is returned.
2033
2034   If 16-bit MMIO register operations are not supported, then ASSERT().
2035   If StartBit is greater than 15, then ASSERT().
2036   If EndBit is greater than 15, then ASSERT().
2037   If EndBit is less than StartBit, then ASSERT().
2038
2039   @param  Address       MMIO register to read.
2040   @param  StartBit      The ordinal of the least significant bit in the bit field.
2041                         Range 0..15.
2042   @param  EndBit        The ordinal of the most significant bit in the bit field.
2043                         Range 0..15.
2044
2045   @return The value read.
2046
2047 **/
2048 UINT16
2049 EFIAPI
2050 S3MmioBitFieldRead16 (
2051   IN UINTN              Address,
2052   IN UINTN              StartBit,
2053   IN UINTN              EndBit
2054   )
2055 {
2056   return InternalSaveMmioWrite16ValueToBootScript (Address, MmioBitFieldRead16 (Address, StartBit, EndBit));
2057 }
2058
2059 /**
2060   Writes a bit field to a MMIO register and saves the value in the S3 script to
2061   be replayed on S3 resume.
2062
2063   Writes Value to the bit field of the MMIO register. The bit field is
2064   specified by the StartBit and the EndBit. All other bits in the destination
2065   MMIO register are preserved. The new value of the 16-bit register is returned.
2066
2067   If 16-bit MMIO register operations are not supported, then ASSERT().
2068   If StartBit is greater than 15, then ASSERT().
2069   If EndBit is greater than 15, then ASSERT().
2070   If EndBit is less than StartBit, then ASSERT().
2071   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2072
2073   @param  Address       The MMIO register to write.
2074   @param  StartBit      The ordinal of the least significant bit in the bit field.
2075                         Range 0..15.
2076   @param  EndBit        The ordinal of the most significant bit in the bit field.
2077                         Range 0..15.
2078   @param  Value         New value of the bit field.
2079
2080   @return The value written back to the MMIO register.
2081
2082 **/
2083 UINT16
2084 EFIAPI
2085 S3MmioBitFieldWrite16 (
2086   IN UINTN              Address,
2087   IN UINTN              StartBit,
2088   IN UINTN              EndBit,
2089   IN UINT16             Value
2090   )
2091 {
2092   return InternalSaveMmioWrite16ValueToBootScript (Address, MmioBitFieldWrite16 (Address, StartBit, EndBit, Value));
2093 }
2094
2095 /**
2096   Reads a bit field in a 16-bit MMIO register, performs a bitwise OR, and
2097   writes the result back to the bit field in the 16-bit MMIO register and
2098   saves the value in the S3 script to be replayed on S3 resume.
2099
2100   Reads the 16-bit MMIO register specified by Address, performs a bitwise
2101   inclusive OR between the read result and the value specified by OrData, and
2102   writes the result to the 16-bit MMIO register specified by Address. The value
2103   written to the MMIO register is returned. This function must guarantee that
2104   all MMIO read and write operations are serialized. Extra left bits in OrData
2105   are stripped.
2106
2107   If 16-bit MMIO register operations are not supported, then ASSERT().
2108   If StartBit is greater than 15, then ASSERT().
2109   If EndBit is greater than 15, then ASSERT().
2110   If EndBit is less than StartBit, then ASSERT().
2111   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2112
2113   @param  Address       The MMIO register to write.
2114   @param  StartBit      The ordinal of the least significant bit in the bit field.
2115                         Range 0..15.
2116   @param  EndBit        The ordinal of the most significant bit in the bit field.
2117                         Range 0..15.
2118   @param  OrData        The value to OR with the read value from the MMIO register.
2119
2120   @return The value written back to the MMIO register.
2121
2122 **/
2123 UINT16
2124 EFIAPI
2125 S3MmioBitFieldOr16 (
2126   IN UINTN              Address,
2127   IN UINTN              StartBit,
2128   IN UINTN              EndBit,
2129   IN UINT16             OrData
2130   )
2131 {
2132   return InternalSaveMmioWrite16ValueToBootScript (Address, MmioBitFieldOr16 (Address, StartBit, EndBit, OrData));
2133 }
2134
2135 /**
2136   Reads a bit field in a 16-bit MMIO register, performs a bitwise AND, and
2137   writes the result back to the bit field in the 16-bit MMIO register and
2138   saves the value in the S3 script to be replayed on S3 resume.
2139
2140   Reads the 16-bit MMIO register specified by Address, performs a bitwise AND
2141   between the read result and the value specified by AndData, and writes the
2142   result to the 16-bit MMIO register specified by Address. The value written to
2143   the MMIO register is returned. This function must guarantee that all MMIO
2144   read and write operations are serialized. Extra left bits in AndData are
2145   stripped.
2146
2147   If 16-bit MMIO register operations are not supported, then ASSERT().
2148   If StartBit is greater than 15, then ASSERT().
2149   If EndBit is greater than 15, then ASSERT().
2150   If EndBit is less than StartBit, then ASSERT().
2151   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2152
2153   @param  Address       The MMIO register to write.
2154   @param  StartBit      The ordinal of the least significant bit in the bit field.
2155                         Range 0..15.
2156   @param  EndBit        The ordinal of the most significant bit in the bit field.
2157                         Range 0..15.
2158   @param  AndData       The value to AND with the read value from the MMIO register.
2159
2160   @return The value written back to the MMIO register.
2161
2162 **/
2163 UINT16
2164 EFIAPI
2165 S3MmioBitFieldAnd16 (
2166   IN UINTN              Address,
2167   IN UINTN              StartBit,
2168   IN UINTN              EndBit,
2169   IN UINT16             AndData
2170   )
2171 {
2172   return InternalSaveMmioWrite16ValueToBootScript (Address, MmioBitFieldAnd16 (Address, StartBit, EndBit, AndData));
2173 }
2174
2175 /**
2176   Reads a bit field in a 16-bit MMIO register, performs a bitwise AND followed
2177   by a bitwise OR, and writes the result back to the bit field in the
2178   16-bit MMIO register and saves the value in the S3 script to be replayed
2179   on S3 resume.
2180
2181   Reads the 16-bit MMIO register specified by Address, performs a bitwise AND
2182   followed by a bitwise OR between the read result and the value
2183   specified by AndData, and writes the result to the 16-bit MMIO register
2184   specified by Address. The value written to the MMIO register is returned.
2185   This function must guarantee that all MMIO read and write operations are
2186   serialized. Extra left bits in both AndData and OrData are stripped.
2187
2188   If 16-bit MMIO register operations are not supported, then ASSERT().
2189   If StartBit is greater than 15, then ASSERT().
2190   If EndBit is greater than 15, then ASSERT().
2191   If EndBit is less than StartBit, then ASSERT().
2192   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2193   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2194
2195   @param  Address       The MMIO register to write.
2196   @param  StartBit      The ordinal of the least significant bit in the bit field.
2197                         Range 0..15.
2198   @param  EndBit        The ordinal of the most significant bit in the bit field.
2199                         Range 0..15.
2200   @param  AndData       The value to AND with the read value from the MMIO register.
2201   @param  OrData        The value to OR with the result of the AND operation.
2202
2203   @return The value written back to the MMIO register.
2204
2205 **/
2206 UINT16
2207 EFIAPI
2208 S3MmioBitFieldAndThenOr16 (
2209   IN UINTN              Address,
2210   IN UINTN              StartBit,
2211   IN UINTN              EndBit,
2212   IN UINT16             AndData,
2213   IN UINT16             OrData
2214   )
2215 {
2216   return InternalSaveMmioWrite16ValueToBootScript (Address, MmioBitFieldAndThenOr16 (Address, StartBit, EndBit, AndData, OrData));
2217 }
2218
2219 /**
2220   Saves a 32-bit MMIO register value to the boot script.
2221
2222   This internal worker function saves a 32-bit MMIO register value in the S3 script
2223   to be replayed on S3 resume.
2224
2225   If the saving process fails, then ASSERT().
2226
2227   @param  Address       The MMIO register to write.
2228   @param  Value         The value saved to boot script.
2229
2230   @return Value.
2231
2232 **/
2233 UINT32
2234 InternalSaveMmioWrite32ValueToBootScript (
2235   IN UINTN              Address,
2236   IN UINT32             Value
2237   )
2238 {
2239   InternalSaveMmioWriteValueToBootScript (S3BootScriptWidthUint32, Address, &Value);
2240
2241   return Value;
2242 }
2243
2244 /**
2245   Reads a 32-bit MMIO register saves the value in the S3 script to be
2246   replayed on S3 resume.
2247
2248   Reads the 32-bit MMIO register specified by Address. The 32-bit read value is
2249   returned. This function must guarantee that all MMIO read and write
2250   operations are serialized.
2251
2252   If 32-bit MMIO register operations are not supported, then ASSERT().
2253
2254   @param  Address       The MMIO register to read.
2255
2256   @return The value read.
2257
2258 **/
2259 UINT32
2260 EFIAPI
2261 S3MmioRead32 (
2262   IN UINTN              Address
2263   )
2264 {
2265   return InternalSaveMmioWrite32ValueToBootScript (Address, MmioRead32 (Address));
2266 }
2267
2268 /**
2269   Writes a 32-bit MMIO register and saves the value in the S3 script to be
2270   replayed on S3 resume.
2271
2272   Writes the 32-bit MMIO register specified by Address with the value specified
2273   by Value and returns Value. This function must guarantee that all MMIO read
2274   and write operations are serialized.
2275
2276   If 32-bit MMIO register operations are not supported, then ASSERT().
2277
2278   @param  Address       The MMIO register to write.
2279   @param  Value         The value to write to the MMIO register.
2280
2281   @return The value written the MMIO register.
2282
2283 **/
2284 UINT32
2285 EFIAPI
2286 S3MmioWrite32 (
2287   IN UINTN              Address,
2288   IN UINT32             Value
2289   )
2290 {
2291   return InternalSaveMmioWrite32ValueToBootScript (Address, MmioWrite32 (Address, Value));
2292 }
2293
2294 /**
2295   Reads a 32-bit MMIO register, performs a bitwise OR, and writes the
2296   result back to the 32-bit MMIO register and saves the value in the S3 script
2297   to be replayed on S3 resume.
2298
2299   Reads the 32-bit MMIO register specified by Address, performs a bitwise
2300   inclusive OR between the read result and the value specified by OrData, and
2301   writes the result to the 32-bit MMIO register specified by Address. The value
2302   written to the MMIO register is returned. This function must guarantee that
2303   all MMIO read and write operations are serialized.
2304
2305   If 32-bit MMIO register operations are not supported, then ASSERT().
2306
2307   @param  Address       The MMIO register to write.
2308   @param  OrData        The value to OR with the read value from the MMIO register.
2309
2310   @return The value written back to the MMIO register.
2311
2312 **/
2313 UINT32
2314 EFIAPI
2315 S3MmioOr32 (
2316   IN UINTN              Address,
2317   IN UINT32             OrData
2318   )
2319 {
2320   return InternalSaveMmioWrite32ValueToBootScript (Address, MmioOr32 (Address, OrData));
2321 }
2322
2323 /**
2324   Reads a 32-bit MMIO register, performs a bitwise AND, and writes the result
2325   back to the 32-bit MMIO register and saves the value in the S3 script to be
2326   replayed on S3 resume.
2327
2328   Reads the 32-bit MMIO register specified by Address, performs a bitwise AND
2329   between the read result and the value specified by AndData, and writes the
2330   result to the 32-bit MMIO register specified by Address. The value written to
2331   the MMIO register is returned. This function must guarantee that all MMIO
2332   read and write operations are serialized.
2333
2334   If 32-bit MMIO register operations are not supported, then ASSERT().
2335
2336   @param  Address       The MMIO register to write.
2337   @param  AndData       The value to AND with the read value from the MMIO register.
2338
2339   @return The value written back to the MMIO register.
2340
2341 **/
2342 UINT32
2343 EFIAPI
2344 S3MmioAnd32 (
2345   IN UINTN              Address,
2346   IN UINT32             AndData
2347   )
2348 {
2349   return InternalSaveMmioWrite32ValueToBootScript (Address, MmioAnd32 (Address, AndData));
2350 }
2351
2352 /**
2353   Reads a 32-bit MMIO register, performs a bitwise AND followed by a bitwise
2354   inclusive OR, and writes the result back to the 32-bit MMIO register and
2355   saves the value in the S3 script to be replayed on S3 resume.
2356
2357   Reads the 32-bit MMIO register specified by Address, performs a bitwise AND
2358   between the read result and the value specified by AndData, performs a
2359   bitwise OR between the result of the AND operation and the value specified by
2360   OrData, and writes the result to the 32-bit MMIO register specified by
2361   Address. The value written to the MMIO register is returned. This function
2362   must guarantee that all MMIO read and write operations are serialized.
2363
2364   If 32-bit MMIO register operations are not supported, then ASSERT().
2365
2366   @param  Address       The MMIO register to write.
2367   @param  AndData       The value to AND with the read value from the MMIO register.
2368   @param  OrData        The value to OR with the result of the AND operation.
2369
2370   @return The value written back to the MMIO register.
2371
2372 **/
2373 UINT32
2374 EFIAPI
2375 S3MmioAndThenOr32 (
2376   IN UINTN              Address,
2377   IN UINT32             AndData,
2378   IN UINT32             OrData
2379   )
2380 {
2381   return InternalSaveMmioWrite32ValueToBootScript (Address, MmioAndThenOr32 (Address, AndData, OrData));
2382 }
2383
2384 /**
2385   Reads a bit field of a MMIO register and saves the value in the S3 script
2386   to be replayed on S3 resume.
2387
2388   Reads the bit field in a 32-bit MMIO register. The bit field is specified by
2389   the StartBit and the EndBit. The value of the bit field is returned.
2390
2391   If 32-bit MMIO register operations are not supported, then ASSERT().
2392   If StartBit is greater than 31, then ASSERT().
2393   If EndBit is greater than 31, then ASSERT().
2394   If EndBit is less than StartBit, then ASSERT().
2395
2396   @param  Address       MMIO register to read.
2397   @param  StartBit      The ordinal of the least significant bit in the bit field.
2398                         Range 0..31.
2399   @param  EndBit        The ordinal of the most significant bit in the bit field.
2400                         Range 0..31.
2401
2402   @return The value read.
2403
2404 **/
2405 UINT32
2406 EFIAPI
2407 S3MmioBitFieldRead32 (
2408   IN UINTN              Address,
2409   IN UINTN              StartBit,
2410   IN UINTN              EndBit
2411   )
2412 {
2413   return InternalSaveMmioWrite32ValueToBootScript (Address, MmioBitFieldRead32 (Address, StartBit, EndBit));
2414 }
2415
2416 /**
2417   Writes a bit field to a MMIO register and saves the value in the S3 script
2418   to be replayed on S3 resume.
2419
2420   Writes Value to the bit field of the MMIO register. The bit field is
2421   specified by the StartBit and the EndBit. All other bits in the destination
2422   MMIO register are preserved. The new value of the 32-bit register is returned.
2423
2424   If 32-bit MMIO register operations are not supported, then ASSERT().
2425   If StartBit is greater than 31, then ASSERT().
2426   If EndBit is greater than 31, then ASSERT().
2427   If EndBit is less than StartBit, then ASSERT().
2428   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2429
2430   @param  Address       The MMIO register to write.
2431   @param  StartBit      The ordinal of the least significant bit in the bit field.
2432                         Range 0..31.
2433   @param  EndBit        The ordinal of the most significant bit in the bit field.
2434                         Range 0..31.
2435   @param  Value         New value of the bit field.
2436
2437   @return The value written back to the MMIO register.
2438
2439 **/
2440 UINT32
2441 EFIAPI
2442 S3MmioBitFieldWrite32 (
2443   IN UINTN              Address,
2444   IN UINTN              StartBit,
2445   IN UINTN              EndBit,
2446   IN UINT32             Value
2447   )
2448 {
2449   return InternalSaveMmioWrite32ValueToBootScript (Address, MmioBitFieldWrite32 (Address, StartBit, EndBit, Value));
2450 }
2451
2452 /**
2453   Reads a bit field in a 32-bit MMIO register, performs a bitwise OR, and
2454   writes the result back to the bit field in the 32-bit MMIO register and
2455   saves the value in the S3 script to be replayed on S3 resume.
2456
2457   Reads the 32-bit MMIO register specified by Address, performs a bitwise
2458   inclusive OR between the read result and the value specified by OrData, and
2459   writes the result to the 32-bit MMIO register specified by Address. The value
2460   written to the MMIO register is returned. This function must guarantee that
2461   all MMIO read and write operations are serialized. Extra left bits in OrData
2462   are stripped.
2463
2464   If 32-bit MMIO register operations are not supported, then ASSERT().
2465   If StartBit is greater than 31, then ASSERT().
2466   If EndBit is greater than 31, then ASSERT().
2467   If EndBit is less than StartBit, then ASSERT().
2468   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2469
2470   @param  Address       The MMIO register to write.
2471   @param  StartBit      The ordinal of the least significant bit in the bit field.
2472                         Range 0..31.
2473   @param  EndBit        The ordinal of the most significant bit in the bit field.
2474                         Range 0..31.
2475   @param  OrData        The value to OR with the read value from the MMIO register.
2476
2477   @return The value written back to the MMIO register.
2478
2479 **/
2480 UINT32
2481 EFIAPI
2482 S3MmioBitFieldOr32 (
2483   IN UINTN              Address,
2484   IN UINTN              StartBit,
2485   IN UINTN              EndBit,
2486   IN UINT32             OrData
2487   )
2488 {
2489   return InternalSaveMmioWrite32ValueToBootScript (Address, MmioBitFieldOr32 (Address, StartBit, EndBit, OrData));
2490 }
2491
2492 /**
2493   Reads a bit field in a 32-bit MMIO register, performs a bitwise AND, and
2494   writes the result back to the bit field in the 32-bit MMIO register and
2495   saves the value in the S3 script to be replayed on S3 resume.
2496
2497   Reads the 32-bit MMIO register specified by Address, performs a bitwise AND
2498   between the read result and the value specified by AndData, and writes the
2499   result to the 32-bit MMIO register specified by Address. The value written to
2500   the MMIO register is returned. This function must guarantee that all MMIO
2501   read and write operations are serialized. Extra left bits in AndData are
2502   stripped.
2503
2504   If 32-bit MMIO register operations are not supported, then ASSERT().
2505   If StartBit is greater than 31, then ASSERT().
2506   If EndBit is greater than 31, then ASSERT().
2507   If EndBit is less than StartBit, then ASSERT().
2508   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2509
2510   @param  Address       The MMIO register to write.
2511   @param  StartBit      The ordinal of the least significant bit in the bit field.
2512                         Range 0..31.
2513   @param  EndBit        The ordinal of the most significant bit in the bit field.
2514                         Range 0..31.
2515   @param  AndData       The value to AND with the read value from the MMIO register.
2516
2517   @return The value written back to the MMIO register.
2518
2519 **/
2520 UINT32
2521 EFIAPI
2522 S3MmioBitFieldAnd32 (
2523   IN UINTN              Address,
2524   IN UINTN              StartBit,
2525   IN UINTN              EndBit,
2526   IN UINT32             AndData
2527   )
2528 {
2529   return InternalSaveMmioWrite32ValueToBootScript (Address, MmioBitFieldAnd32 (Address, StartBit, EndBit, AndData));
2530 }
2531
2532 /**
2533   Reads a bit field in a 32-bit MMIO register, performs a bitwise AND followed
2534   by a bitwise OR, and writes the result back to the bit field in the
2535   32-bit MMIO register and saves the value in the S3 script to be replayed
2536   on S3 resume.
2537
2538   Reads the 32-bit MMIO register specified by Address, performs a bitwise AND
2539   followed by a bitwise OR between the read result and the value
2540   specified by AndData, and writes the result to the 32-bit MMIO register
2541   specified by Address. The value written to the MMIO register is returned.
2542   This function must guarantee that all MMIO read and write operations are
2543   serialized. Extra left bits in both AndData and OrData are stripped.
2544
2545   If 32-bit MMIO register operations are not supported, then ASSERT().
2546   If StartBit is greater than 31, then ASSERT().
2547   If EndBit is greater than 31, then ASSERT().
2548   If EndBit is less than StartBit, then ASSERT().
2549   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2550   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2551
2552   @param  Address       The MMIO register to write.
2553   @param  StartBit      The ordinal of the least significant bit in the bit field.
2554                         Range 0..31.
2555   @param  EndBit        The ordinal of the most significant bit in the bit field.
2556                         Range 0..31.
2557   @param  AndData       The value to AND with the read value from the MMIO register.
2558   @param  OrData        The value to OR with the result of the AND operation.
2559
2560   @return The value written back to the MMIO register.
2561
2562 **/
2563 UINT32
2564 EFIAPI
2565 S3MmioBitFieldAndThenOr32 (
2566   IN UINTN              Address,
2567   IN UINTN              StartBit,
2568   IN UINTN              EndBit,
2569   IN UINT32             AndData,
2570   IN UINT32             OrData
2571   )
2572 {
2573   return InternalSaveMmioWrite32ValueToBootScript (Address, MmioBitFieldAndThenOr32 (Address, StartBit, EndBit, AndData, OrData));
2574 }
2575
2576 /**
2577   Saves a 64-bit MMIO register value to the boot script.
2578
2579   This internal worker function saves a 64-bit MMIO register value in the S3 script
2580   to be replayed on S3 resume.
2581
2582   If the saving process fails, then ASSERT().
2583
2584   @param  Address       The MMIO register to write.
2585   @param  Value         The value saved to boot script.
2586
2587   @return Value.
2588
2589 **/
2590 UINT64
2591 InternalSaveMmioWrite64ValueToBootScript (
2592   IN UINTN              Address,
2593   IN UINT64             Value
2594   )
2595 {
2596   InternalSaveMmioWriteValueToBootScript (S3BootScriptWidthUint64, Address, &Value);
2597
2598   return Value;
2599 }
2600
2601 /**
2602   Reads a 64-bit MMIO register and saves the value in the S3 script to be
2603   replayed on S3 resume.
2604
2605   Reads the 64-bit MMIO register specified by Address. The 64-bit read value is
2606   returned. This function must guarantee that all MMIO read and write
2607   operations are serialized.
2608
2609   If 64-bit MMIO register operations are not supported, then ASSERT().
2610
2611   @param  Address       The MMIO register to read.
2612
2613   @return The value read.
2614
2615 **/
2616 UINT64
2617 EFIAPI
2618 S3MmioRead64 (
2619   IN UINTN              Address
2620   )
2621 {
2622   return InternalSaveMmioWrite64ValueToBootScript (Address, MmioRead64 (Address));
2623 }
2624
2625 /**
2626   Writes a 64-bit MMIO register and saves the value in the S3 script to be
2627   replayed on S3 resume.
2628
2629   Writes the 64-bit MMIO register specified by Address with the value specified
2630   by Value and returns Value. This function must guarantee that all MMIO read
2631   and write operations are serialized.
2632
2633   If 64-bit MMIO register operations are not supported, then ASSERT().
2634
2635   @param  Address       The MMIO register to write.
2636   @param  Value         The value to write to the MMIO register.
2637
2638   @return The value written the MMIO register.
2639
2640 **/
2641 UINT64
2642 EFIAPI
2643 S3MmioWrite64 (
2644   IN UINTN              Address,
2645   IN UINT64             Value
2646   )
2647 {
2648   return InternalSaveMmioWrite64ValueToBootScript (Address, MmioWrite64 (Address, Value));
2649 }
2650
2651 /**
2652   Reads a 64-bit MMIO register, performs a bitwise OR, and writes the
2653   result back to the 64-bit MMIO register and saves the value in the S3 script
2654   to be replayed on S3 resume.
2655
2656   Reads the 64-bit MMIO register specified by Address, performs a bitwise
2657   inclusive OR between the read result and the value specified by OrData, and
2658   writes the result to the 64-bit MMIO register specified by Address. The value
2659   written to the MMIO register is returned. This function must guarantee that
2660   all MMIO read and write operations are serialized.
2661
2662   If 64-bit MMIO register operations are not supported, then ASSERT().
2663
2664   @param  Address       The MMIO register to write.
2665   @param  OrData        The value to OR with the read value from the MMIO register.
2666
2667   @return The value written back to the MMIO register.
2668
2669 **/
2670 UINT64
2671 EFIAPI
2672 S3MmioOr64 (
2673   IN UINTN              Address,
2674   IN UINT64             OrData
2675   )
2676 {
2677   return InternalSaveMmioWrite64ValueToBootScript (Address, MmioOr64 (Address, OrData));
2678 }
2679
2680 /**
2681   Reads a 64-bit MMIO register, performs a bitwise AND, and writes the result
2682   back to the 64-bit MMIO register and saves the value in the S3 script to be
2683   replayed on S3 resume.
2684
2685   Reads the 64-bit MMIO register specified by Address, performs a bitwise AND
2686   between the read result and the value specified by AndData, and writes the
2687   result to the 64-bit MMIO register specified by Address. The value written to
2688   the MMIO register is returned. This function must guarantee that all MMIO
2689   read and write operations are serialized.
2690
2691   If 64-bit MMIO register operations are not supported, then ASSERT().
2692
2693   @param  Address       The MMIO register to write.
2694   @param  AndData       The value to AND with the read value from the MMIO register.
2695
2696   @return The value written back to the MMIO register.
2697
2698 **/
2699 UINT64
2700 EFIAPI
2701 S3MmioAnd64 (
2702   IN UINTN              Address,
2703   IN UINT64             AndData
2704   )
2705 {
2706   return InternalSaveMmioWrite64ValueToBootScript (Address, MmioAnd64 (Address, AndData));
2707 }
2708
2709 /**
2710   Reads a 64-bit MMIO register, performs a bitwise AND followed by a bitwise
2711   inclusive OR, and writes the result back to the 64-bit MMIO register and
2712   saves the value in the S3 script to be replayed on S3 resume.
2713
2714   Reads the 64-bit MMIO register specified by Address, performs a bitwise AND
2715   between the read result and the value specified by AndData, performs a
2716   bitwise OR between the result of the AND operation and the value specified by
2717   OrData, and writes the result to the 64-bit MMIO register specified by
2718   Address. The value written to the MMIO register is returned. This function
2719   must guarantee that all MMIO read and write operations are serialized.
2720
2721   If 64-bit MMIO register operations are not supported, then ASSERT().
2722
2723   @param  Address       The MMIO register to write.
2724   @param  AndData       The value to AND with the read value from the MMIO register.
2725   @param  OrData        The value to OR with the result of the AND operation.
2726
2727   @return The value written back to the MMIO register.
2728
2729 **/
2730 UINT64
2731 EFIAPI
2732 S3MmioAndThenOr64 (
2733   IN UINTN              Address,
2734   IN UINT64             AndData,
2735   IN UINT64             OrData
2736   )
2737 {
2738   return InternalSaveMmioWrite64ValueToBootScript (Address, MmioAndThenOr64 (Address, AndData, OrData));
2739 }
2740
2741 /**
2742   Reads a bit field of a MMIO register saves the value in the S3 script to
2743   be replayed on S3 resume.
2744
2745   Reads the bit field in a 64-bit MMIO register. The bit field is specified by
2746   the StartBit and the EndBit. The value of the bit field is returned.
2747
2748   If 64-bit MMIO register operations are not supported, then ASSERT().
2749   If StartBit is greater than 63, then ASSERT().
2750   If EndBit is greater than 63, then ASSERT().
2751   If EndBit is less than StartBit, then ASSERT().
2752
2753   @param  Address       MMIO register to read.
2754   @param  StartBit      The ordinal of the least significant bit in the bit field.
2755                         Range 0..63.
2756   @param  EndBit        The ordinal of the most significant bit in the bit field.
2757                         Range 0..63.
2758
2759   @return The value read.
2760
2761 **/
2762 UINT64
2763 EFIAPI
2764 S3MmioBitFieldRead64 (
2765   IN UINTN              Address,
2766   IN UINTN              StartBit,
2767   IN UINTN              EndBit
2768   )
2769 {
2770   return InternalSaveMmioWrite64ValueToBootScript (Address, MmioBitFieldRead64 (Address, StartBit, EndBit));
2771 }
2772
2773 /**
2774   Writes a bit field to a MMIO register and saves the value in the S3 script to
2775   be replayed on S3 resume.
2776
2777   Writes Value to the bit field of the MMIO register. The bit field is
2778   specified by the StartBit and the EndBit. All other bits in the destination
2779   MMIO register are preserved. The new value of the 64-bit register is returned.
2780
2781   If 64-bit MMIO register operations are not supported, then ASSERT().
2782   If StartBit is greater than 63, then ASSERT().
2783   If EndBit is greater than 63, then ASSERT().
2784   If EndBit is less than StartBit, then ASSERT().
2785   If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2786
2787   @param  Address       The MMIO register to write.
2788   @param  StartBit      The ordinal of the least significant bit in the bit field.
2789                         Range 0..63.
2790   @param  EndBit        The ordinal of the most significant bit in the bit field.
2791                         Range 0..63.
2792   @param  Value         New value of the bit field.
2793
2794   @return The value written back to the MMIO register.
2795
2796 **/
2797 UINT64
2798 EFIAPI
2799 S3MmioBitFieldWrite64 (
2800   IN UINTN              Address,
2801   IN UINTN              StartBit,
2802   IN UINTN              EndBit,
2803   IN UINT64             Value
2804   )
2805 {
2806   return InternalSaveMmioWrite64ValueToBootScript (Address, MmioBitFieldWrite64 (Address, StartBit, EndBit, Value));
2807 }
2808
2809 /**
2810   Reads a bit field in a 64-bit MMIO register, performs a bitwise OR, and
2811   writes the result back to the bit field in the 64-bit MMIO register and
2812   saves the value in the S3 script to be replayed on S3 resume.
2813
2814   Reads the 64-bit MMIO register specified by Address, performs a bitwise
2815   inclusive OR between the read result and the value specified by OrData, and
2816   writes the result to the 64-bit MMIO register specified by Address. The value
2817   written to the MMIO register is returned. This function must guarantee that
2818   all MMIO read and write operations are serialized. Extra left bits in OrData
2819   are stripped.
2820
2821   If 64-bit MMIO register operations are not supported, then ASSERT().
2822   If StartBit is greater than 63, then ASSERT().
2823   If EndBit is greater than 63, then ASSERT().
2824   If EndBit is less than StartBit, then ASSERT().
2825   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2826
2827   @param  Address       The MMIO register to write.
2828   @param  StartBit      The ordinal of the least significant bit in the bit field.
2829                         Range 0..63.
2830   @param  EndBit        The ordinal of the most significant bit in the bit field.
2831                         Range 0..63.
2832   @param  OrData        The value to OR with the read value from the MMIO register.
2833
2834   @return The value written back to the MMIO register.
2835
2836 **/
2837 UINT64
2838 EFIAPI
2839 S3MmioBitFieldOr64 (
2840   IN UINTN              Address,
2841   IN UINTN              StartBit,
2842   IN UINTN              EndBit,
2843   IN UINT64             OrData
2844   )
2845 {
2846   return InternalSaveMmioWrite64ValueToBootScript (Address, MmioBitFieldOr64 (Address, StartBit, EndBit, OrData));
2847 }
2848
2849 /**
2850   Reads a bit field in a 64-bit MMIO register, performs a bitwise AND, and
2851   writes the result back to the bit field in the 64-bit MMIO register and saves
2852   the value in the S3 script to be replayed on S3 resume.
2853
2854   Reads the 64-bit MMIO register specified by Address, performs a bitwise AND
2855   between the read result and the value specified by AndData, and writes the
2856   result to the 64-bit MMIO register specified by Address. The value written to
2857   the MMIO register is returned. This function must guarantee that all MMIO
2858   read and write operations are serialized. Extra left bits in AndData are
2859   stripped.
2860
2861   If 64-bit MMIO register operations are not supported, then ASSERT().
2862   If StartBit is greater than 63, then ASSERT().
2863   If EndBit is greater than 63, then ASSERT().
2864   If EndBit is less than StartBit, then ASSERT().
2865   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2866
2867   @param  Address       The MMIO register to write.
2868   @param  StartBit      The ordinal of the least significant bit in the bit field.
2869                         Range 0..63.
2870   @param  EndBit        The ordinal of the most significant bit in the bit field.
2871                         Range 0..63.
2872   @param  AndData       The value to AND with the read value from the MMIO register.
2873
2874   @return The value written back to the MMIO register.
2875
2876 **/
2877 UINT64
2878 EFIAPI
2879 S3MmioBitFieldAnd64 (
2880   IN UINTN              Address,
2881   IN UINTN              StartBit,
2882   IN UINTN              EndBit,
2883   IN UINT64             AndData
2884   )
2885 {
2886   return InternalSaveMmioWrite64ValueToBootScript (Address, MmioBitFieldAnd64 (Address, StartBit, EndBit, AndData));
2887 }
2888
2889 /**
2890   Reads a bit field in a 64-bit MMIO register, performs a bitwise AND followed
2891   by a bitwise OR, and writes the result back to the bit field in the
2892   64-bit MMIO register and saves the value in the S3 script to be replayed
2893   on S3 resume.
2894
2895   Reads the 64-bit MMIO register specified by Address, performs a bitwise AND
2896   followed by a bitwise OR between the read result and the value
2897   specified by AndData, and writes the result to the 64-bit MMIO register
2898   specified by Address. The value written to the MMIO register is returned.
2899   This function must guarantee that all MMIO read and write operations are
2900   serialized. Extra left bits in both AndData and OrData are stripped.
2901
2902   If 64-bit MMIO register operations are not supported, then ASSERT().
2903   If StartBit is greater than 63, then ASSERT().
2904   If EndBit is greater than 63, then ASSERT().
2905   If EndBit is less than StartBit, then ASSERT().
2906   If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2907   If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
2908
2909   @param  Address       The MMIO register to write.
2910   @param  StartBit      The ordinal of the least significant bit in the bit field.
2911                         Range 0..63.
2912   @param  EndBit        The ordinal of the most significant bit in the bit field.
2913                         Range 0..63.
2914   @param  AndData       The value to AND with the read value from the MMIO register.
2915   @param  OrData        The value to OR with the result of the AND operation.
2916
2917   @return The value written back to the MMIO register.
2918
2919 **/
2920 UINT64
2921 EFIAPI
2922 S3MmioBitFieldAndThenOr64 (
2923   IN UINTN              Address,
2924   IN UINTN              StartBit,
2925   IN UINTN              EndBit,
2926   IN UINT64             AndData,
2927   IN UINT64             OrData
2928   )
2929 {
2930   return InternalSaveMmioWrite64ValueToBootScript (Address, MmioBitFieldAndThenOr64 (Address, StartBit, EndBit, AndData, OrData));
2931 }
2932
2933 /**
2934   Copy data from MMIO region to system memory by using 8-bit access
2935   and saves the value in the S3 script to be replayed on S3 resume.
2936
2937   Copy data from MMIO region specified by starting address StartAddress
2938   to system memory specified by Buffer by using 8-bit access. The total
2939   number of byte to be copied is specified by Length. Buffer is returned.
2940
2941   If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT().
2942   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
2943
2944
2945   @param  StartAddress    Starting address for the MMIO region to be copied from.
2946   @param  Length          Size in bytes of the copy.
2947   @param  Buffer          Pointer to a system memory buffer receiving the data read.
2948
2949   @return Buffer
2950
2951 **/
2952 UINT8 *
2953 EFIAPI
2954 S3MmioReadBuffer8 (
2955   IN  UINTN       StartAddress,
2956   IN  UINTN       Length,
2957   OUT UINT8       *Buffer
2958   )
2959 {
2960   UINT8       *ReturnBuffer;
2961   RETURN_STATUS  Status;
2962
2963   ReturnBuffer = MmioReadBuffer8 (StartAddress, Length, Buffer);
2964
2965   Status = S3BootScriptSaveMemWrite (
2966              S3BootScriptWidthUint8,
2967              StartAddress,
2968              Length / sizeof (UINT8),
2969              ReturnBuffer
2970              );
2971   ASSERT (Status == RETURN_SUCCESS);
2972
2973   return ReturnBuffer;
2974 }
2975
2976 /**
2977   Copy data from MMIO region to system memory by using 16-bit access
2978   and saves the value in the S3 script to be replayed on S3 resume.
2979
2980   Copy data from MMIO region specified by starting address StartAddress
2981   to system memory specified by Buffer by using 16-bit access. The total
2982   number of byte to be copied is specified by Length. Buffer is returned.
2983
2984   If StartAddress is not aligned on a 16-bit boundary, then ASSERT().
2985
2986   If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT().
2987   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
2988
2989   If Length is not aligned on a 16-bit boundary, then ASSERT().
2990   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
2991
2992   @param  StartAddress    Starting address for the MMIO region to be copied from.
2993   @param  Length          Size in bytes of the copy.
2994   @param  Buffer          Pointer to a system memory buffer receiving the data read.
2995
2996   @return Buffer
2997
2998 **/
2999 UINT16 *
3000 EFIAPI
3001 S3MmioReadBuffer16 (
3002   IN  UINTN       StartAddress,
3003   IN  UINTN       Length,
3004   OUT UINT16      *Buffer
3005   )
3006 {
3007   UINT16       *ReturnBuffer;
3008   RETURN_STATUS   Status;
3009
3010   ReturnBuffer = MmioReadBuffer16 (StartAddress, Length, Buffer);
3011
3012   Status = S3BootScriptSaveMemWrite (
3013              S3BootScriptWidthUint16,
3014              StartAddress,
3015              Length / sizeof (UINT16),
3016              ReturnBuffer
3017              );
3018   ASSERT (Status == RETURN_SUCCESS);
3019
3020   return ReturnBuffer;
3021 }
3022
3023 /**
3024   Copy data from MMIO region to system memory by using 32-bit access
3025   and saves the value in the S3 script to be replayed on S3 resume.
3026
3027   Copy data from MMIO region specified by starting address StartAddress
3028   to system memory specified by Buffer by using 32-bit access. The total
3029   number of byte to be copied is specified by Length. Buffer is returned.
3030
3031   If StartAddress is not aligned on a 32-bit boundary, then ASSERT().
3032
3033   If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT().
3034   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3035
3036   If Length is not aligned on a 32-bit boundary, then ASSERT().
3037   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
3038
3039   @param  StartAddress    Starting address for the MMIO region to be copied from.
3040   @param  Length          Size in bytes of the copy.
3041   @param  Buffer          Pointer to a system memory buffer receiving the data read.
3042
3043   @return Buffer
3044
3045 **/
3046 UINT32 *
3047 EFIAPI
3048 S3MmioReadBuffer32 (
3049   IN  UINTN       StartAddress,
3050   IN  UINTN       Length,
3051   OUT UINT32      *Buffer
3052   )
3053 {
3054   UINT32      *ReturnBuffer;
3055   RETURN_STATUS  Status;
3056
3057   ReturnBuffer = MmioReadBuffer32 (StartAddress, Length, Buffer);
3058
3059   Status = S3BootScriptSaveMemWrite (
3060              S3BootScriptWidthUint32,
3061              StartAddress,
3062              Length / sizeof (UINT32),
3063              ReturnBuffer
3064              );
3065   ASSERT (Status == RETURN_SUCCESS);
3066
3067   return ReturnBuffer;
3068 }
3069
3070 /**
3071   Copy data from MMIO region to system memory by using 64-bit access
3072   and saves the value in the S3 script to be replayed on S3 resume.
3073
3074   Copy data from MMIO region specified by starting address StartAddress
3075   to system memory specified by Buffer by using 64-bit access. The total
3076   number of byte to be copied is specified by Length. Buffer is returned.
3077
3078   If StartAddress is not aligned on a 64-bit boundary, then ASSERT().
3079
3080   If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT().
3081   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3082
3083   If Length is not aligned on a 64-bit boundary, then ASSERT().
3084   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
3085
3086   @param  StartAddress    Starting address for the MMIO region to be copied from.
3087   @param  Length          Size in bytes of the copy.
3088   @param  Buffer          Pointer to a system memory buffer receiving the data read.
3089
3090   @return Buffer
3091
3092 **/
3093 UINT64 *
3094 EFIAPI
3095 S3MmioReadBuffer64 (
3096   IN  UINTN       StartAddress,
3097   IN  UINTN       Length,
3098   OUT UINT64      *Buffer
3099   )
3100 {
3101   UINT64      *ReturnBuffer;
3102   RETURN_STATUS  Status;
3103
3104   ReturnBuffer = MmioReadBuffer64 (StartAddress, Length, Buffer);
3105
3106   Status = S3BootScriptSaveMemWrite (
3107              S3BootScriptWidthUint64,
3108              StartAddress,
3109              Length / sizeof (UINT64),
3110              ReturnBuffer
3111              );
3112   ASSERT (Status == RETURN_SUCCESS);
3113
3114   return ReturnBuffer;
3115 }
3116
3117
3118 /**
3119   Copy data from system memory to MMIO region by using 8-bit access
3120   and saves the value in the S3 script to be replayed on S3 resume.
3121
3122   Copy data from system memory specified by Buffer to MMIO region specified
3123   by starting address StartAddress by using 8-bit access. The total number
3124   of byte to be copied is specified by Length. Buffer is returned.
3125
3126   If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT().
3127   If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT().
3128
3129
3130   @param  StartAddress    Starting address for the MMIO region to be copied to.
3131   @param  Length     Size in bytes of the copy.
3132   @param  Buffer          Pointer to a system memory buffer containing the data to write.
3133
3134   @return Buffer
3135
3136 **/
3137 UINT8 *
3138 EFIAPI
3139 S3MmioWriteBuffer8 (
3140   IN  UINTN         StartAddress,
3141   IN  UINTN         Length,
3142   IN  CONST UINT8   *Buffer
3143   )
3144 {
3145   UINT8       *ReturnBuffer;
3146   RETURN_STATUS  Status;
3147
3148   ReturnBuffer = MmioWriteBuffer8 (StartAddress, Length, Buffer);
3149
3150   Status = S3BootScriptSaveMemWrite (
3151              S3BootScriptWidthUint8,
3152              StartAddress,
3153              Length / sizeof (UINT8),
3154              ReturnBuffer
3155              );
3156   ASSERT (Status == RETURN_SUCCESS);
3157
3158   return ReturnBuffer;
3159 }
3160
3161 /**
3162   Copy data from system memory to MMIO region by using 16-bit access
3163   and saves the value in the S3 script to be replayed on S3 resume.
3164
3165   Copy data from system memory specified by Buffer to MMIO region specified
3166   by starting address StartAddress by using 16-bit access. The total number
3167   of byte to be copied is specified by Length. Buffer is returned.
3168
3169   If StartAddress is not aligned on a 16-bit boundary, then ASSERT().
3170
3171   If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT().
3172   If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT().
3173
3174   If Length is not aligned on a 16-bit boundary, then ASSERT().
3175
3176   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
3177
3178   @param  StartAddress    Starting address for the MMIO region to be copied to.
3179   @param  Length     Size in bytes of the copy.
3180   @param  Buffer          Pointer to a system memory buffer containing the data to write.
3181
3182   @return Buffer
3183
3184 **/
3185 UINT16 *
3186 EFIAPI
3187 S3MmioWriteBuffer16 (
3188   IN  UINTN        StartAddress,
3189   IN  UINTN        Length,
3190   IN  CONST UINT16 *Buffer
3191   )
3192 {
3193   UINT16      *ReturnBuffer;
3194   RETURN_STATUS  Status;
3195
3196   ReturnBuffer = MmioWriteBuffer16 (StartAddress, Length, Buffer);
3197
3198   Status = S3BootScriptSaveMemWrite (
3199              S3BootScriptWidthUint16,
3200              StartAddress,
3201              Length / sizeof (UINT16),
3202              ReturnBuffer
3203              );
3204   ASSERT (Status == RETURN_SUCCESS);
3205
3206   return ReturnBuffer;
3207 }
3208
3209
3210 /**
3211   Copy data from system memory to MMIO region by using 32-bit access
3212   and saves the value in the S3 script to be replayed on S3 resume.
3213
3214   Copy data from system memory specified by Buffer to MMIO region specified
3215   by starting address StartAddress by using 32-bit access. The total number
3216   of byte to be copied is specified by Length. Buffer is returned.
3217
3218   If StartAddress is not aligned on a 32-bit boundary, then ASSERT().
3219
3220   If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT().
3221   If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT().
3222
3223   If Length is not aligned on a 32-bit boundary, then ASSERT().
3224
3225   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
3226
3227   @param  StartAddress    Starting address for the MMIO region to be copied to.
3228   @param  Length     Size in bytes of the copy.
3229   @param  Buffer          Pointer to a system memory buffer containing the data to write.
3230
3231   @return Buffer
3232
3233 **/
3234 UINT32 *
3235 EFIAPI
3236 S3MmioWriteBuffer32 (
3237   IN  UINTN        StartAddress,
3238   IN  UINTN        Length,
3239   IN  CONST UINT32 *Buffer
3240   )
3241 {
3242   UINT32      *ReturnBuffer;
3243   RETURN_STATUS  Status;
3244
3245   ReturnBuffer = MmioWriteBuffer32 (StartAddress, Length, Buffer);
3246
3247   Status = S3BootScriptSaveMemWrite (
3248              S3BootScriptWidthUint32,
3249              StartAddress,
3250              Length / sizeof (UINT32),
3251              ReturnBuffer
3252              );
3253   ASSERT (Status == RETURN_SUCCESS);
3254
3255   return ReturnBuffer;
3256 }
3257
3258 /**
3259   Copy data from system memory to MMIO region by using 64-bit access
3260   and saves the value in the S3 script to be replayed on S3 resume.
3261
3262   Copy data from system memory specified by Buffer to MMIO region specified
3263   by starting address StartAddress by using 64-bit access. The total number
3264   of byte to be copied is specified by Length. Buffer is returned.
3265
3266   If StartAddress is not aligned on a 64-bit boundary, then ASSERT().
3267
3268   If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT().
3269   If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT().
3270
3271   If Length is not aligned on a 64-bit boundary, then ASSERT().
3272
3273   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
3274
3275   @param  StartAddress    Starting address for the MMIO region to be copied to.
3276   @param  Length     Size in bytes of the copy.
3277   @param  Buffer          Pointer to a system memory buffer containing the data to write.
3278
3279   @return Buffer
3280
3281 **/
3282 UINT64 *
3283 EFIAPI
3284 S3MmioWriteBuffer64 (
3285   IN  UINTN        StartAddress,
3286   IN  UINTN        Length,
3287   IN  CONST UINT64 *Buffer
3288   )
3289 {
3290   UINT64      *ReturnBuffer;
3291   RETURN_STATUS  Status;
3292
3293   ReturnBuffer = MmioWriteBuffer64 (StartAddress, Length, Buffer);
3294
3295   Status = S3BootScriptSaveMemWrite (
3296              S3BootScriptWidthUint64,
3297              StartAddress,
3298              Length / sizeof (UINT64),
3299              ReturnBuffer
3300              );
3301   ASSERT (Status == RETURN_SUCCESS);
3302
3303   return ReturnBuffer;
3304 }
3305