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