1 /** @file 2 Provides string functions, linked list functions, math functions, synchronization 3 functions, file path functions, and CPU architecture-specific functions. 4 5 Copyright (c) 2006 - 2021, Intel Corporation. All rights reserved.<BR> 6 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR> 7 Copyright (c) Microsoft Corporation.<BR> 8 Portions Copyright (c) 2020, Hewlett Packard Enterprise Development LP. All rights reserved.<BR> 9 Portions Copyright (c) 2022, Loongson Technology Corporation Limited. All rights reserved.<BR> 10 11 SPDX-License-Identifier: BSD-2-Clause-Patent 12 13 **/ 14 15 #ifndef __BASE_LIB__ 16 #define __BASE_LIB__ 17 18 // 19 // Definitions for architecture-specific types 20 // 21 #if defined (MDE_CPU_IA32) 22 /// 23 /// The IA-32 architecture context buffer used by SetJump() and LongJump(). 24 /// 25 typedef struct { 26 UINT32 Ebx; 27 UINT32 Esi; 28 UINT32 Edi; 29 UINT32 Ebp; 30 UINT32 Esp; 31 UINT32 Eip; 32 UINT32 Ssp; 33 } BASE_LIBRARY_JUMP_BUFFER; 34 35 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4 36 37 #endif // defined (MDE_CPU_IA32) 38 39 #if defined (MDE_CPU_X64) 40 /// 41 /// The x64 architecture context buffer used by SetJump() and LongJump(). 42 /// 43 typedef struct { 44 UINT64 Rbx; 45 UINT64 Rsp; 46 UINT64 Rbp; 47 UINT64 Rdi; 48 UINT64 Rsi; 49 UINT64 R12; 50 UINT64 R13; 51 UINT64 R14; 52 UINT64 R15; 53 UINT64 Rip; 54 UINT64 MxCsr; 55 UINT8 XmmBuffer[160]; ///< XMM6-XMM15. 56 UINT64 Ssp; 57 } BASE_LIBRARY_JUMP_BUFFER; 58 59 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 60 61 #endif // defined (MDE_CPU_X64) 62 63 #if defined (MDE_CPU_EBC) 64 /// 65 /// The EBC context buffer used by SetJump() and LongJump(). 66 /// 67 typedef struct { 68 UINT64 R0; 69 UINT64 R1; 70 UINT64 R2; 71 UINT64 R3; 72 UINT64 IP; 73 } BASE_LIBRARY_JUMP_BUFFER; 74 75 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 76 77 #endif // defined (MDE_CPU_EBC) 78 79 #if defined (MDE_CPU_ARM) 80 81 typedef struct { 82 UINT32 R3; ///< A copy of R13. 83 UINT32 R4; 84 UINT32 R5; 85 UINT32 R6; 86 UINT32 R7; 87 UINT32 R8; 88 UINT32 R9; 89 UINT32 R10; 90 UINT32 R11; 91 UINT32 R12; 92 UINT32 R14; 93 } BASE_LIBRARY_JUMP_BUFFER; 94 95 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4 96 97 #endif // defined (MDE_CPU_ARM) 98 99 #if defined (MDE_CPU_AARCH64) 100 typedef struct { 101 // GP regs 102 UINT64 X19; 103 UINT64 X20; 104 UINT64 X21; 105 UINT64 X22; 106 UINT64 X23; 107 UINT64 X24; 108 UINT64 X25; 109 UINT64 X26; 110 UINT64 X27; 111 UINT64 X28; 112 UINT64 FP; 113 UINT64 LR; 114 UINT64 IP0; 115 116 // FP regs 117 UINT64 D8; 118 UINT64 D9; 119 UINT64 D10; 120 UINT64 D11; 121 UINT64 D12; 122 UINT64 D13; 123 UINT64 D14; 124 UINT64 D15; 125 } BASE_LIBRARY_JUMP_BUFFER; 126 127 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 128 129 #endif // defined (MDE_CPU_AARCH64) 130 131 #if defined (MDE_CPU_RISCV64) 132 /// 133 /// The RISC-V architecture context buffer used by SetJump() and LongJump(). 134 /// 135 typedef struct { 136 UINT64 RA; 137 UINT64 S0; 138 UINT64 S1; 139 UINT64 S2; 140 UINT64 S3; 141 UINT64 S4; 142 UINT64 S5; 143 UINT64 S6; 144 UINT64 S7; 145 UINT64 S8; 146 UINT64 S9; 147 UINT64 S10; 148 UINT64 S11; 149 UINT64 SP; 150 } BASE_LIBRARY_JUMP_BUFFER; 151 152 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 153 154 VOID 155 RiscVSetSupervisorScratch ( 156 IN UINT64 157 ); 158 159 UINT64 160 RiscVGetSupervisorScratch ( 161 VOID 162 ); 163 164 VOID 165 RiscVSetSupervisorStvec ( 166 IN UINT64 167 ); 168 169 UINT64 170 RiscVGetSupervisorStvec ( 171 VOID 172 ); 173 174 UINT64 175 RiscVGetSupervisorTrapCause ( 176 VOID 177 ); 178 179 VOID 180 RiscVSetSupervisorAddressTranslationRegister ( 181 IN UINT64 182 ); 183 184 UINT64 185 RiscVReadTimer ( 186 VOID 187 ); 188 189 VOID 190 RiscVEnableTimerInterrupt ( 191 VOID 192 ); 193 194 VOID 195 RiscVDisableTimerInterrupt ( 196 VOID 197 ); 198 199 VOID 200 RiscVClearPendingTimerInterrupt ( 201 VOID 202 ); 203 204 #endif // defined (MDE_CPU_RISCV64) 205 206 #if defined (MDE_CPU_LOONGARCH64) 207 /// 208 /// The LoongArch architecture context buffer used by SetJump() and LongJump() 209 /// 210 typedef struct { 211 UINT64 S0; 212 UINT64 S1; 213 UINT64 S2; 214 UINT64 S3; 215 UINT64 S4; 216 UINT64 S5; 217 UINT64 S6; 218 UINT64 S7; 219 UINT64 S8; 220 UINT64 SP; 221 UINT64 FP; 222 UINT64 RA; 223 } BASE_LIBRARY_JUMP_BUFFER; 224 225 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 226 227 #endif // defined (MDE_CPU_LOONGARCH64) 228 229 // 230 // String Services 231 // 232 233 /** 234 Returns the length of a Null-terminated Unicode string. 235 236 This function is similar as strlen_s defined in C11. 237 238 If String is not aligned on a 16-bit boundary, then ASSERT(). 239 240 @param String A pointer to a Null-terminated Unicode string. 241 @param MaxSize The maximum number of Destination Unicode 242 char, including terminating null char. 243 244 @retval 0 If String is NULL. 245 @retval MaxSize If there is no null character in the first MaxSize characters of String. 246 @return The number of characters that percede the terminating null character. 247 248 **/ 249 UINTN 250 EFIAPI 251 StrnLenS ( 252 IN CONST CHAR16 *String, 253 IN UINTN MaxSize 254 ); 255 256 /** 257 Returns the size of a Null-terminated Unicode string in bytes, including the 258 Null terminator. 259 260 This function returns the size of the Null-terminated Unicode string 261 specified by String in bytes, including the Null terminator. 262 263 If String is not aligned on a 16-bit boundary, then ASSERT(). 264 265 @param String A pointer to a Null-terminated Unicode string. 266 @param MaxSize The maximum number of Destination Unicode 267 char, including the Null terminator. 268 269 @retval 0 If String is NULL. 270 @retval (sizeof (CHAR16) * (MaxSize + 1)) 271 If there is no Null terminator in the first MaxSize characters of 272 String. 273 @return The size of the Null-terminated Unicode string in bytes, including 274 the Null terminator. 275 276 **/ 277 UINTN 278 EFIAPI 279 StrnSizeS ( 280 IN CONST CHAR16 *String, 281 IN UINTN MaxSize 282 ); 283 284 /** 285 Copies the string pointed to by Source (including the terminating null char) 286 to the array pointed to by Destination. 287 288 This function is similar as strcpy_s defined in C11. 289 290 If Destination is not aligned on a 16-bit boundary, then ASSERT(). 291 If Source is not aligned on a 16-bit boundary, then ASSERT(). 292 293 If an error is returned, then the Destination is unmodified. 294 295 @param Destination A pointer to a Null-terminated Unicode string. 296 @param DestMax The maximum number of Destination Unicode 297 char, including terminating null char. 298 @param Source A pointer to a Null-terminated Unicode string. 299 300 @retval RETURN_SUCCESS String is copied. 301 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source). 302 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 303 If Source is NULL. 304 If PcdMaximumUnicodeStringLength is not zero, 305 and DestMax is greater than 306 PcdMaximumUnicodeStringLength. 307 If DestMax is 0. 308 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 309 **/ 310 RETURN_STATUS 311 EFIAPI 312 StrCpyS ( 313 OUT CHAR16 *Destination, 314 IN UINTN DestMax, 315 IN CONST CHAR16 *Source 316 ); 317 318 /** 319 Copies not more than Length successive char from the string pointed to by 320 Source to the array pointed to by Destination. If no null char is copied from 321 Source, then Destination[Length] is always set to null. 322 323 This function is similar as strncpy_s defined in C11. 324 325 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT(). 326 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT(). 327 328 If an error is returned, then the Destination is unmodified. 329 330 @param Destination A pointer to a Null-terminated Unicode string. 331 @param DestMax The maximum number of Destination Unicode 332 char, including terminating null char. 333 @param Source A pointer to a Null-terminated Unicode string. 334 @param Length The maximum number of Unicode characters to copy. 335 336 @retval RETURN_SUCCESS String is copied. 337 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than 338 MIN(StrLen(Source), Length). 339 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 340 If Source is NULL. 341 If PcdMaximumUnicodeStringLength is not zero, 342 and DestMax is greater than 343 PcdMaximumUnicodeStringLength. 344 If DestMax is 0. 345 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 346 **/ 347 RETURN_STATUS 348 EFIAPI 349 StrnCpyS ( 350 OUT CHAR16 *Destination, 351 IN UINTN DestMax, 352 IN CONST CHAR16 *Source, 353 IN UINTN Length 354 ); 355 356 /** 357 Appends a copy of the string pointed to by Source (including the terminating 358 null char) to the end of the string pointed to by Destination. 359 360 This function is similar as strcat_s defined in C11. 361 362 If Destination is not aligned on a 16-bit boundary, then ASSERT(). 363 If Source is not aligned on a 16-bit boundary, then ASSERT(). 364 365 If an error is returned, then the Destination is unmodified. 366 367 @param Destination A pointer to a Null-terminated Unicode string. 368 @param DestMax The maximum number of Destination Unicode 369 char, including terminating null char. 370 @param Source A pointer to a Null-terminated Unicode string. 371 372 @retval RETURN_SUCCESS String is appended. 373 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than 374 StrLen(Destination). 375 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT 376 greater than StrLen(Source). 377 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 378 If Source is NULL. 379 If PcdMaximumUnicodeStringLength is not zero, 380 and DestMax is greater than 381 PcdMaximumUnicodeStringLength. 382 If DestMax is 0. 383 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 384 **/ 385 RETURN_STATUS 386 EFIAPI 387 StrCatS ( 388 IN OUT CHAR16 *Destination, 389 IN UINTN DestMax, 390 IN CONST CHAR16 *Source 391 ); 392 393 /** 394 Appends not more than Length successive char from the string pointed to by 395 Source to the end of the string pointed to by Destination. If no null char is 396 copied from Source, then Destination[StrLen(Destination) + Length] is always 397 set to null. 398 399 This function is similar as strncat_s defined in C11. 400 401 If Destination is not aligned on a 16-bit boundary, then ASSERT(). 402 If Source is not aligned on a 16-bit boundary, then ASSERT(). 403 404 If an error is returned, then the Destination is unmodified. 405 406 @param Destination A pointer to a Null-terminated Unicode string. 407 @param DestMax The maximum number of Destination Unicode 408 char, including terminating null char. 409 @param Source A pointer to a Null-terminated Unicode string. 410 @param Length The maximum number of Unicode characters to copy. 411 412 @retval RETURN_SUCCESS String is appended. 413 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than 414 StrLen(Destination). 415 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT 416 greater than MIN(StrLen(Source), Length). 417 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 418 If Source is NULL. 419 If PcdMaximumUnicodeStringLength is not zero, 420 and DestMax is greater than 421 PcdMaximumUnicodeStringLength. 422 If DestMax is 0. 423 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 424 **/ 425 RETURN_STATUS 426 EFIAPI 427 StrnCatS ( 428 IN OUT CHAR16 *Destination, 429 IN UINTN DestMax, 430 IN CONST CHAR16 *Source, 431 IN UINTN Length 432 ); 433 434 /** 435 Convert a Null-terminated Unicode decimal string to a value of type UINTN. 436 437 This function outputs a value of type UINTN by interpreting the contents of 438 the Unicode string specified by String as a decimal number. The format of the 439 input Unicode string String is: 440 441 [spaces] [decimal digits]. 442 443 The valid decimal digit character is in the range [0-9]. The function will 444 ignore the pad space, which includes spaces or tab characters, before 445 [decimal digits]. The running zero in the beginning of [decimal digits] will 446 be ignored. Then, the function stops at the first character that is a not a 447 valid decimal character or a Null-terminator, whichever one comes first. 448 449 If String is not aligned in a 16-bit boundary, then ASSERT(). 450 451 If String has no valid decimal digits in the above format, then 0 is stored 452 at the location pointed to by Data. 453 If the number represented by String exceeds the range defined by UINTN, then 454 MAX_UINTN is stored at the location pointed to by Data. 455 456 If EndPointer is not NULL, a pointer to the character that stopped the scan 457 is stored at the location pointed to by EndPointer. If String has no valid 458 decimal digits right after the optional pad spaces, the value of String is 459 stored at the location pointed to by EndPointer. 460 461 @param String Pointer to a Null-terminated Unicode string. 462 @param EndPointer Pointer to character that stops scan. 463 @param Data Pointer to the converted value. 464 465 @retval RETURN_SUCCESS Value is translated from String. 466 @retval RETURN_INVALID_PARAMETER If String is NULL. 467 If Data is NULL. 468 If PcdMaximumUnicodeStringLength is not 469 zero, and String contains more than 470 PcdMaximumUnicodeStringLength Unicode 471 characters, not including the 472 Null-terminator. 473 @retval RETURN_UNSUPPORTED If the number represented by String exceeds 474 the range defined by UINTN. 475 476 **/ 477 RETURN_STATUS 478 EFIAPI 479 StrDecimalToUintnS ( 480 IN CONST CHAR16 *String, 481 OUT CHAR16 **EndPointer OPTIONAL, 482 OUT UINTN *Data 483 ); 484 485 /** 486 Convert a Null-terminated Unicode decimal string to a value of type UINT64. 487 488 This function outputs a value of type UINT64 by interpreting the contents of 489 the Unicode string specified by String as a decimal number. The format of the 490 input Unicode string String is: 491 492 [spaces] [decimal digits]. 493 494 The valid decimal digit character is in the range [0-9]. The function will 495 ignore the pad space, which includes spaces or tab characters, before 496 [decimal digits]. The running zero in the beginning of [decimal digits] will 497 be ignored. Then, the function stops at the first character that is a not a 498 valid decimal character or a Null-terminator, whichever one comes first. 499 500 If String is not aligned in a 16-bit boundary, then ASSERT(). 501 502 If String has no valid decimal digits in the above format, then 0 is stored 503 at the location pointed to by Data. 504 If the number represented by String exceeds the range defined by UINT64, then 505 MAX_UINT64 is stored at the location pointed to by Data. 506 507 If EndPointer is not NULL, a pointer to the character that stopped the scan 508 is stored at the location pointed to by EndPointer. If String has no valid 509 decimal digits right after the optional pad spaces, the value of String is 510 stored at the location pointed to by EndPointer. 511 512 @param String Pointer to a Null-terminated Unicode string. 513 @param EndPointer Pointer to character that stops scan. 514 @param Data Pointer to the converted value. 515 516 @retval RETURN_SUCCESS Value is translated from String. 517 @retval RETURN_INVALID_PARAMETER If String is NULL. 518 If Data is NULL. 519 If PcdMaximumUnicodeStringLength is not 520 zero, and String contains more than 521 PcdMaximumUnicodeStringLength Unicode 522 characters, not including the 523 Null-terminator. 524 @retval RETURN_UNSUPPORTED If the number represented by String exceeds 525 the range defined by UINT64. 526 527 **/ 528 RETURN_STATUS 529 EFIAPI 530 StrDecimalToUint64S ( 531 IN CONST CHAR16 *String, 532 OUT CHAR16 **EndPointer OPTIONAL, 533 OUT UINT64 *Data 534 ); 535 536 /** 537 Convert a Null-terminated Unicode hexadecimal string to a value of type 538 UINTN. 539 540 This function outputs a value of type UINTN by interpreting the contents of 541 the Unicode string specified by String as a hexadecimal number. The format of 542 the input Unicode string String is: 543 544 [spaces][zeros][x][hexadecimal digits]. 545 546 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 547 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. 548 If "x" appears in the input string, it must be prefixed with at least one 0. 549 The function will ignore the pad space, which includes spaces or tab 550 characters, before [zeros], [x] or [hexadecimal digit]. The running zero 551 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts 552 after [x] or the first valid hexadecimal digit. Then, the function stops at 553 the first character that is a not a valid hexadecimal character or NULL, 554 whichever one comes first. 555 556 If String is not aligned in a 16-bit boundary, then ASSERT(). 557 558 If String has no valid hexadecimal digits in the above format, then 0 is 559 stored at the location pointed to by Data. 560 If the number represented by String exceeds the range defined by UINTN, then 561 MAX_UINTN is stored at the location pointed to by Data. 562 563 If EndPointer is not NULL, a pointer to the character that stopped the scan 564 is stored at the location pointed to by EndPointer. If String has no valid 565 hexadecimal digits right after the optional pad spaces, the value of String 566 is stored at the location pointed to by EndPointer. 567 568 @param String Pointer to a Null-terminated Unicode string. 569 @param EndPointer Pointer to character that stops scan. 570 @param Data Pointer to the converted value. 571 572 @retval RETURN_SUCCESS Value is translated from String. 573 @retval RETURN_INVALID_PARAMETER If String is NULL. 574 If Data is NULL. 575 If PcdMaximumUnicodeStringLength is not 576 zero, and String contains more than 577 PcdMaximumUnicodeStringLength Unicode 578 characters, not including the 579 Null-terminator. 580 @retval RETURN_UNSUPPORTED If the number represented by String exceeds 581 the range defined by UINTN. 582 583 **/ 584 RETURN_STATUS 585 EFIAPI 586 StrHexToUintnS ( 587 IN CONST CHAR16 *String, 588 OUT CHAR16 **EndPointer OPTIONAL, 589 OUT UINTN *Data 590 ); 591 592 /** 593 Convert a Null-terminated Unicode hexadecimal string to a value of type 594 UINT64. 595 596 This function outputs a value of type UINT64 by interpreting the contents of 597 the Unicode string specified by String as a hexadecimal number. The format of 598 the input Unicode string String is: 599 600 [spaces][zeros][x][hexadecimal digits]. 601 602 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 603 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. 604 If "x" appears in the input string, it must be prefixed with at least one 0. 605 The function will ignore the pad space, which includes spaces or tab 606 characters, before [zeros], [x] or [hexadecimal digit]. The running zero 607 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts 608 after [x] or the first valid hexadecimal digit. Then, the function stops at 609 the first character that is a not a valid hexadecimal character or NULL, 610 whichever one comes first. 611 612 If String is not aligned in a 16-bit boundary, then ASSERT(). 613 614 If String has no valid hexadecimal digits in the above format, then 0 is 615 stored at the location pointed to by Data. 616 If the number represented by String exceeds the range defined by UINT64, then 617 MAX_UINT64 is stored at the location pointed to by Data. 618 619 If EndPointer is not NULL, a pointer to the character that stopped the scan 620 is stored at the location pointed to by EndPointer. If String has no valid 621 hexadecimal digits right after the optional pad spaces, the value of String 622 is stored at the location pointed to by EndPointer. 623 624 @param String Pointer to a Null-terminated Unicode string. 625 @param EndPointer Pointer to character that stops scan. 626 @param Data Pointer to the converted value. 627 628 @retval RETURN_SUCCESS Value is translated from String. 629 @retval RETURN_INVALID_PARAMETER If String is NULL. 630 If Data is NULL. 631 If PcdMaximumUnicodeStringLength is not 632 zero, and String contains more than 633 PcdMaximumUnicodeStringLength Unicode 634 characters, not including the 635 Null-terminator. 636 @retval RETURN_UNSUPPORTED If the number represented by String exceeds 637 the range defined by UINT64. 638 639 **/ 640 RETURN_STATUS 641 EFIAPI 642 StrHexToUint64S ( 643 IN CONST CHAR16 *String, 644 OUT CHAR16 **EndPointer OPTIONAL, 645 OUT UINT64 *Data 646 ); 647 648 /** 649 Returns the length of a Null-terminated Ascii string. 650 651 This function is similar as strlen_s defined in C11. 652 653 @param String A pointer to a Null-terminated Ascii string. 654 @param MaxSize The maximum number of Destination Ascii 655 char, including terminating null char. 656 657 @retval 0 If String is NULL. 658 @retval MaxSize If there is no null character in the first MaxSize characters of String. 659 @return The number of characters that percede the terminating null character. 660 661 **/ 662 UINTN 663 EFIAPI 664 AsciiStrnLenS ( 665 IN CONST CHAR8 *String, 666 IN UINTN MaxSize 667 ); 668 669 /** 670 Returns the size of a Null-terminated Ascii string in bytes, including the 671 Null terminator. 672 673 This function returns the size of the Null-terminated Ascii string specified 674 by String in bytes, including the Null terminator. 675 676 @param String A pointer to a Null-terminated Ascii string. 677 @param MaxSize The maximum number of Destination Ascii 678 char, including the Null terminator. 679 680 @retval 0 If String is NULL. 681 @retval (sizeof (CHAR8) * (MaxSize + 1)) 682 If there is no Null terminator in the first MaxSize characters of 683 String. 684 @return The size of the Null-terminated Ascii string in bytes, including the 685 Null terminator. 686 687 **/ 688 UINTN 689 EFIAPI 690 AsciiStrnSizeS ( 691 IN CONST CHAR8 *String, 692 IN UINTN MaxSize 693 ); 694 695 /** 696 Copies the string pointed to by Source (including the terminating null char) 697 to the array pointed to by Destination. 698 699 This function is similar as strcpy_s defined in C11. 700 701 If an error is returned, then the Destination is unmodified. 702 703 @param Destination A pointer to a Null-terminated Ascii string. 704 @param DestMax The maximum number of Destination Ascii 705 char, including terminating null char. 706 @param Source A pointer to a Null-terminated Ascii string. 707 708 @retval RETURN_SUCCESS String is copied. 709 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source). 710 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 711 If Source is NULL. 712 If PcdMaximumAsciiStringLength is not zero, 713 and DestMax is greater than 714 PcdMaximumAsciiStringLength. 715 If DestMax is 0. 716 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 717 **/ 718 RETURN_STATUS 719 EFIAPI 720 AsciiStrCpyS ( 721 OUT CHAR8 *Destination, 722 IN UINTN DestMax, 723 IN CONST CHAR8 *Source 724 ); 725 726 /** 727 Copies not more than Length successive char from the string pointed to by 728 Source to the array pointed to by Destination. If no null char is copied from 729 Source, then Destination[Length] is always set to null. 730 731 This function is similar as strncpy_s defined in C11. 732 733 If an error is returned, then the Destination is unmodified. 734 735 @param Destination A pointer to a Null-terminated Ascii string. 736 @param DestMax The maximum number of Destination Ascii 737 char, including terminating null char. 738 @param Source A pointer to a Null-terminated Ascii string. 739 @param Length The maximum number of Ascii characters to copy. 740 741 @retval RETURN_SUCCESS String is copied. 742 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than 743 MIN(StrLen(Source), Length). 744 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 745 If Source is NULL. 746 If PcdMaximumAsciiStringLength is not zero, 747 and DestMax is greater than 748 PcdMaximumAsciiStringLength. 749 If DestMax is 0. 750 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 751 **/ 752 RETURN_STATUS 753 EFIAPI 754 AsciiStrnCpyS ( 755 OUT CHAR8 *Destination, 756 IN UINTN DestMax, 757 IN CONST CHAR8 *Source, 758 IN UINTN Length 759 ); 760 761 /** 762 Appends a copy of the string pointed to by Source (including the terminating 763 null char) to the end of the string pointed to by Destination. 764 765 This function is similar as strcat_s defined in C11. 766 767 If an error is returned, then the Destination is unmodified. 768 769 @param Destination A pointer to a Null-terminated Ascii string. 770 @param DestMax The maximum number of Destination Ascii 771 char, including terminating null char. 772 @param Source A pointer to a Null-terminated Ascii string. 773 774 @retval RETURN_SUCCESS String is appended. 775 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than 776 StrLen(Destination). 777 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT 778 greater than StrLen(Source). 779 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 780 If Source is NULL. 781 If PcdMaximumAsciiStringLength is not zero, 782 and DestMax is greater than 783 PcdMaximumAsciiStringLength. 784 If DestMax is 0. 785 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 786 **/ 787 RETURN_STATUS 788 EFIAPI 789 AsciiStrCatS ( 790 IN OUT CHAR8 *Destination, 791 IN UINTN DestMax, 792 IN CONST CHAR8 *Source 793 ); 794 795 /** 796 Appends not more than Length successive char from the string pointed to by 797 Source to the end of the string pointed to by Destination. If no null char is 798 copied from Source, then Destination[StrLen(Destination) + Length] is always 799 set to null. 800 801 This function is similar as strncat_s defined in C11. 802 803 If an error is returned, then the Destination is unmodified. 804 805 @param Destination A pointer to a Null-terminated Ascii string. 806 @param DestMax The maximum number of Destination Ascii 807 char, including terminating null char. 808 @param Source A pointer to a Null-terminated Ascii string. 809 @param Length The maximum number of Ascii characters to copy. 810 811 @retval RETURN_SUCCESS String is appended. 812 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than 813 StrLen(Destination). 814 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT 815 greater than MIN(StrLen(Source), Length). 816 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 817 If Source is NULL. 818 If PcdMaximumAsciiStringLength is not zero, 819 and DestMax is greater than 820 PcdMaximumAsciiStringLength. 821 If DestMax is 0. 822 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 823 **/ 824 RETURN_STATUS 825 EFIAPI 826 AsciiStrnCatS ( 827 IN OUT CHAR8 *Destination, 828 IN UINTN DestMax, 829 IN CONST CHAR8 *Source, 830 IN UINTN Length 831 ); 832 833 /** 834 Convert a Null-terminated Ascii decimal string to a value of type UINTN. 835 836 This function outputs a value of type UINTN by interpreting the contents of 837 the Ascii string specified by String as a decimal number. The format of the 838 input Ascii string String is: 839 840 [spaces] [decimal digits]. 841 842 The valid decimal digit character is in the range [0-9]. The function will 843 ignore the pad space, which includes spaces or tab characters, before 844 [decimal digits]. The running zero in the beginning of [decimal digits] will 845 be ignored. Then, the function stops at the first character that is a not a 846 valid decimal character or a Null-terminator, whichever one comes first. 847 848 If String has no valid decimal digits in the above format, then 0 is stored 849 at the location pointed to by Data. 850 If the number represented by String exceeds the range defined by UINTN, then 851 MAX_UINTN is stored at the location pointed to by Data. 852 853 If EndPointer is not NULL, a pointer to the character that stopped the scan 854 is stored at the location pointed to by EndPointer. If String has no valid 855 decimal digits right after the optional pad spaces, the value of String is 856 stored at the location pointed to by EndPointer. 857 858 @param String Pointer to a Null-terminated Ascii string. 859 @param EndPointer Pointer to character that stops scan. 860 @param Data Pointer to the converted value. 861 862 @retval RETURN_SUCCESS Value is translated from String. 863 @retval RETURN_INVALID_PARAMETER If String is NULL. 864 If Data is NULL. 865 If PcdMaximumAsciiStringLength is not zero, 866 and String contains more than 867 PcdMaximumAsciiStringLength Ascii 868 characters, not including the 869 Null-terminator. 870 @retval RETURN_UNSUPPORTED If the number represented by String exceeds 871 the range defined by UINTN. 872 873 **/ 874 RETURN_STATUS 875 EFIAPI 876 AsciiStrDecimalToUintnS ( 877 IN CONST CHAR8 *String, 878 OUT CHAR8 **EndPointer OPTIONAL, 879 OUT UINTN *Data 880 ); 881 882 /** 883 Convert a Null-terminated Ascii decimal string to a value of type UINT64. 884 885 This function outputs a value of type UINT64 by interpreting the contents of 886 the Ascii string specified by String as a decimal number. The format of the 887 input Ascii string String is: 888 889 [spaces] [decimal digits]. 890 891 The valid decimal digit character is in the range [0-9]. The function will 892 ignore the pad space, which includes spaces or tab characters, before 893 [decimal digits]. The running zero in the beginning of [decimal digits] will 894 be ignored. Then, the function stops at the first character that is a not a 895 valid decimal character or a Null-terminator, whichever one comes first. 896 897 If String has no valid decimal digits in the above format, then 0 is stored 898 at the location pointed to by Data. 899 If the number represented by String exceeds the range defined by UINT64, then 900 MAX_UINT64 is stored at the location pointed to by Data. 901 902 If EndPointer is not NULL, a pointer to the character that stopped the scan 903 is stored at the location pointed to by EndPointer. If String has no valid 904 decimal digits right after the optional pad spaces, the value of String is 905 stored at the location pointed to by EndPointer. 906 907 @param String Pointer to a Null-terminated Ascii string. 908 @param EndPointer Pointer to character that stops scan. 909 @param Data Pointer to the converted value. 910 911 @retval RETURN_SUCCESS Value is translated from String. 912 @retval RETURN_INVALID_PARAMETER If String is NULL. 913 If Data is NULL. 914 If PcdMaximumAsciiStringLength is not zero, 915 and String contains more than 916 PcdMaximumAsciiStringLength Ascii 917 characters, not including the 918 Null-terminator. 919 @retval RETURN_UNSUPPORTED If the number represented by String exceeds 920 the range defined by UINT64. 921 922 **/ 923 RETURN_STATUS 924 EFIAPI 925 AsciiStrDecimalToUint64S ( 926 IN CONST CHAR8 *String, 927 OUT CHAR8 **EndPointer OPTIONAL, 928 OUT UINT64 *Data 929 ); 930 931 /** 932 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN. 933 934 This function outputs a value of type UINTN by interpreting the contents of 935 the Ascii string specified by String as a hexadecimal number. The format of 936 the input Ascii string String is: 937 938 [spaces][zeros][x][hexadecimal digits]. 939 940 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 941 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If 942 "x" appears in the input string, it must be prefixed with at least one 0. The 943 function will ignore the pad space, which includes spaces or tab characters, 944 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or 945 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or 946 the first valid hexadecimal digit. Then, the function stops at the first 947 character that is a not a valid hexadecimal character or Null-terminator, 948 whichever on comes first. 949 950 If String has no valid hexadecimal digits in the above format, then 0 is 951 stored at the location pointed to by Data. 952 If the number represented by String exceeds the range defined by UINTN, then 953 MAX_UINTN is stored at the location pointed to by Data. 954 955 If EndPointer is not NULL, a pointer to the character that stopped the scan 956 is stored at the location pointed to by EndPointer. If String has no valid 957 hexadecimal digits right after the optional pad spaces, the value of String 958 is stored at the location pointed to by EndPointer. 959 960 @param String Pointer to a Null-terminated Ascii string. 961 @param EndPointer Pointer to character that stops scan. 962 @param Data Pointer to the converted value. 963 964 @retval RETURN_SUCCESS Value is translated from String. 965 @retval RETURN_INVALID_PARAMETER If String is NULL. 966 If Data is NULL. 967 If PcdMaximumAsciiStringLength is not zero, 968 and String contains more than 969 PcdMaximumAsciiStringLength Ascii 970 characters, not including the 971 Null-terminator. 972 @retval RETURN_UNSUPPORTED If the number represented by String exceeds 973 the range defined by UINTN. 974 975 **/ 976 RETURN_STATUS 977 EFIAPI 978 AsciiStrHexToUintnS ( 979 IN CONST CHAR8 *String, 980 OUT CHAR8 **EndPointer OPTIONAL, 981 OUT UINTN *Data 982 ); 983 984 /** 985 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64. 986 987 This function outputs a value of type UINT64 by interpreting the contents of 988 the Ascii string specified by String as a hexadecimal number. The format of 989 the input Ascii string String is: 990 991 [spaces][zeros][x][hexadecimal digits]. 992 993 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 994 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If 995 "x" appears in the input string, it must be prefixed with at least one 0. The 996 function will ignore the pad space, which includes spaces or tab characters, 997 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or 998 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or 999 the first valid hexadecimal digit. Then, the function stops at the first 1000 character that is a not a valid hexadecimal character or Null-terminator, 1001 whichever on comes first. 1002 1003 If String has no valid hexadecimal digits in the above format, then 0 is 1004 stored at the location pointed to by Data. 1005 If the number represented by String exceeds the range defined by UINT64, then 1006 MAX_UINT64 is stored at the location pointed to by Data. 1007 1008 If EndPointer is not NULL, a pointer to the character that stopped the scan 1009 is stored at the location pointed to by EndPointer. If String has no valid 1010 hexadecimal digits right after the optional pad spaces, the value of String 1011 is stored at the location pointed to by EndPointer. 1012 1013 @param String Pointer to a Null-terminated Ascii string. 1014 @param EndPointer Pointer to character that stops scan. 1015 @param Data Pointer to the converted value. 1016 1017 @retval RETURN_SUCCESS Value is translated from String. 1018 @retval RETURN_INVALID_PARAMETER If String is NULL. 1019 If Data is NULL. 1020 If PcdMaximumAsciiStringLength is not zero, 1021 and String contains more than 1022 PcdMaximumAsciiStringLength Ascii 1023 characters, not including the 1024 Null-terminator. 1025 @retval RETURN_UNSUPPORTED If the number represented by String exceeds 1026 the range defined by UINT64. 1027 1028 **/ 1029 RETURN_STATUS 1030 EFIAPI 1031 AsciiStrHexToUint64S ( 1032 IN CONST CHAR8 *String, 1033 OUT CHAR8 **EndPointer OPTIONAL, 1034 OUT UINT64 *Data 1035 ); 1036 1037 /** 1038 Returns the length of a Null-terminated Unicode string. 1039 1040 This function returns the number of Unicode characters in the Null-terminated 1041 Unicode string specified by String. 1042 1043 If String is NULL, then ASSERT(). 1044 If String is not aligned on a 16-bit boundary, then ASSERT(). 1045 If PcdMaximumUnicodeStringLength is not zero, and String contains more than 1046 PcdMaximumUnicodeStringLength Unicode characters not including the 1047 Null-terminator, then ASSERT(). 1048 1049 @param String Pointer to a Null-terminated Unicode string. 1050 1051 @return The length of String. 1052 1053 **/ 1054 UINTN 1055 EFIAPI 1056 StrLen ( 1057 IN CONST CHAR16 *String 1058 ); 1059 1060 /** 1061 Returns the size of a Null-terminated Unicode string in bytes, including the 1062 Null terminator. 1063 1064 This function returns the size, in bytes, of the Null-terminated Unicode string 1065 specified by String. 1066 1067 If String is NULL, then ASSERT(). 1068 If String is not aligned on a 16-bit boundary, then ASSERT(). 1069 If PcdMaximumUnicodeStringLength is not zero, and String contains more than 1070 PcdMaximumUnicodeStringLength Unicode characters not including the 1071 Null-terminator, then ASSERT(). 1072 1073 @param String The pointer to a Null-terminated Unicode string. 1074 1075 @return The size of String. 1076 1077 **/ 1078 UINTN 1079 EFIAPI 1080 StrSize ( 1081 IN CONST CHAR16 *String 1082 ); 1083 1084 /** 1085 Compares two Null-terminated Unicode strings, and returns the difference 1086 between the first mismatched Unicode characters. 1087 1088 This function compares the Null-terminated Unicode string FirstString to the 1089 Null-terminated Unicode string SecondString. If FirstString is identical to 1090 SecondString, then 0 is returned. Otherwise, the value returned is the first 1091 mismatched Unicode character in SecondString subtracted from the first 1092 mismatched Unicode character in FirstString. 1093 1094 If FirstString is NULL, then ASSERT(). 1095 If FirstString is not aligned on a 16-bit boundary, then ASSERT(). 1096 If SecondString is NULL, then ASSERT(). 1097 If SecondString is not aligned on a 16-bit boundary, then ASSERT(). 1098 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more 1099 than PcdMaximumUnicodeStringLength Unicode characters not including the 1100 Null-terminator, then ASSERT(). 1101 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more 1102 than PcdMaximumUnicodeStringLength Unicode characters, not including the 1103 Null-terminator, then ASSERT(). 1104 1105 @param FirstString The pointer to a Null-terminated Unicode string. 1106 @param SecondString The pointer to a Null-terminated Unicode string. 1107 1108 @retval 0 FirstString is identical to SecondString. 1109 @return others FirstString is not identical to SecondString. 1110 1111 **/ 1112 INTN 1113 EFIAPI 1114 StrCmp ( 1115 IN CONST CHAR16 *FirstString, 1116 IN CONST CHAR16 *SecondString 1117 ); 1118 1119 /** 1120 Compares up to a specified length the contents of two Null-terminated Unicode strings, 1121 and returns the difference between the first mismatched Unicode characters. 1122 1123 This function compares the Null-terminated Unicode string FirstString to the 1124 Null-terminated Unicode string SecondString. At most, Length Unicode 1125 characters will be compared. If Length is 0, then 0 is returned. If 1126 FirstString is identical to SecondString, then 0 is returned. Otherwise, the 1127 value returned is the first mismatched Unicode character in SecondString 1128 subtracted from the first mismatched Unicode character in FirstString. 1129 1130 If Length > 0 and FirstString is NULL, then ASSERT(). 1131 If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT(). 1132 If Length > 0 and SecondString is NULL, then ASSERT(). 1133 If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT(). 1134 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than 1135 PcdMaximumUnicodeStringLength, then ASSERT(). 1136 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than 1137 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, 1138 then ASSERT(). 1139 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than 1140 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, 1141 then ASSERT(). 1142 1143 @param FirstString The pointer to a Null-terminated Unicode string. 1144 @param SecondString The pointer to a Null-terminated Unicode string. 1145 @param Length The maximum number of Unicode characters to compare. 1146 1147 @retval 0 FirstString is identical to SecondString. 1148 @return others FirstString is not identical to SecondString. 1149 1150 **/ 1151 INTN 1152 EFIAPI 1153 StrnCmp ( 1154 IN CONST CHAR16 *FirstString, 1155 IN CONST CHAR16 *SecondString, 1156 IN UINTN Length 1157 ); 1158 1159 /** 1160 Returns the first occurrence of a Null-terminated Unicode sub-string 1161 in a Null-terminated Unicode string. 1162 1163 This function scans the contents of the Null-terminated Unicode string 1164 specified by String and returns the first occurrence of SearchString. 1165 If SearchString is not found in String, then NULL is returned. If 1166 the length of SearchString is zero, then String is returned. 1167 1168 If String is NULL, then ASSERT(). 1169 If String is not aligned on a 16-bit boundary, then ASSERT(). 1170 If SearchString is NULL, then ASSERT(). 1171 If SearchString is not aligned on a 16-bit boundary, then ASSERT(). 1172 1173 If PcdMaximumUnicodeStringLength is not zero, and SearchString 1174 or String contains more than PcdMaximumUnicodeStringLength Unicode 1175 characters, not including the Null-terminator, then ASSERT(). 1176 1177 @param String The pointer to a Null-terminated Unicode string. 1178 @param SearchString The pointer to a Null-terminated Unicode string to search for. 1179 1180 @retval NULL If the SearchString does not appear in String. 1181 @return others If there is a match. 1182 1183 **/ 1184 CHAR16 * 1185 EFIAPI 1186 StrStr ( 1187 IN CONST CHAR16 *String, 1188 IN CONST CHAR16 *SearchString 1189 ); 1190 1191 /** 1192 Convert a Null-terminated Unicode decimal string to a value of 1193 type UINTN. 1194 1195 This function returns a value of type UINTN by interpreting the contents 1196 of the Unicode string specified by String as a decimal number. The format 1197 of the input Unicode string String is: 1198 1199 [spaces] [decimal digits]. 1200 1201 The valid decimal digit character is in the range [0-9]. The 1202 function will ignore the pad space, which includes spaces or 1203 tab characters, before [decimal digits]. The running zero in the 1204 beginning of [decimal digits] will be ignored. Then, the function 1205 stops at the first character that is a not a valid decimal character 1206 or a Null-terminator, whichever one comes first. 1207 1208 If String is NULL, then ASSERT(). 1209 If String is not aligned in a 16-bit boundary, then ASSERT(). 1210 If String has only pad spaces, then 0 is returned. 1211 If String has no pad spaces or valid decimal digits, 1212 then 0 is returned. 1213 If the number represented by String overflows according 1214 to the range defined by UINTN, then MAX_UINTN is returned. 1215 1216 If PcdMaximumUnicodeStringLength is not zero, and String contains 1217 more than PcdMaximumUnicodeStringLength Unicode characters not including 1218 the Null-terminator, then ASSERT(). 1219 1220 @param String The pointer to a Null-terminated Unicode string. 1221 1222 @retval Value translated from String. 1223 1224 **/ 1225 UINTN 1226 EFIAPI 1227 StrDecimalToUintn ( 1228 IN CONST CHAR16 *String 1229 ); 1230 1231 /** 1232 Convert a Null-terminated Unicode decimal string to a value of 1233 type UINT64. 1234 1235 This function returns a value of type UINT64 by interpreting the contents 1236 of the Unicode string specified by String as a decimal number. The format 1237 of the input Unicode string String is: 1238 1239 [spaces] [decimal digits]. 1240 1241 The valid decimal digit character is in the range [0-9]. The 1242 function will ignore the pad space, which includes spaces or 1243 tab characters, before [decimal digits]. The running zero in the 1244 beginning of [decimal digits] will be ignored. Then, the function 1245 stops at the first character that is a not a valid decimal character 1246 or a Null-terminator, whichever one comes first. 1247 1248 If String is NULL, then ASSERT(). 1249 If String is not aligned in a 16-bit boundary, then ASSERT(). 1250 If String has only pad spaces, then 0 is returned. 1251 If String has no pad spaces or valid decimal digits, 1252 then 0 is returned. 1253 If the number represented by String overflows according 1254 to the range defined by UINT64, then MAX_UINT64 is returned. 1255 1256 If PcdMaximumUnicodeStringLength is not zero, and String contains 1257 more than PcdMaximumUnicodeStringLength Unicode characters not including 1258 the Null-terminator, then ASSERT(). 1259 1260 @param String The pointer to a Null-terminated Unicode string. 1261 1262 @retval Value translated from String. 1263 1264 **/ 1265 UINT64 1266 EFIAPI 1267 StrDecimalToUint64 ( 1268 IN CONST CHAR16 *String 1269 ); 1270 1271 /** 1272 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN. 1273 1274 This function returns a value of type UINTN by interpreting the contents 1275 of the Unicode string specified by String as a hexadecimal number. 1276 The format of the input Unicode string String is: 1277 1278 [spaces][zeros][x][hexadecimal digits]. 1279 1280 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 1281 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. 1282 If "x" appears in the input string, it must be prefixed with at least one 0. 1283 The function will ignore the pad space, which includes spaces or tab characters, 1284 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or 1285 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the 1286 first valid hexadecimal digit. Then, the function stops at the first character 1287 that is a not a valid hexadecimal character or NULL, whichever one comes first. 1288 1289 If String is NULL, then ASSERT(). 1290 If String is not aligned in a 16-bit boundary, then ASSERT(). 1291 If String has only pad spaces, then zero is returned. 1292 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, 1293 then zero is returned. 1294 If the number represented by String overflows according to the range defined by 1295 UINTN, then MAX_UINTN is returned. 1296 1297 If PcdMaximumUnicodeStringLength is not zero, and String contains more than 1298 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, 1299 then ASSERT(). 1300 1301 @param String The pointer to a Null-terminated Unicode string. 1302 1303 @retval Value translated from String. 1304 1305 **/ 1306 UINTN 1307 EFIAPI 1308 StrHexToUintn ( 1309 IN CONST CHAR16 *String 1310 ); 1311 1312 /** 1313 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64. 1314 1315 This function returns a value of type UINT64 by interpreting the contents 1316 of the Unicode string specified by String as a hexadecimal number. 1317 The format of the input Unicode string String is 1318 1319 [spaces][zeros][x][hexadecimal digits]. 1320 1321 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 1322 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. 1323 If "x" appears in the input string, it must be prefixed with at least one 0. 1324 The function will ignore the pad space, which includes spaces or tab characters, 1325 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or 1326 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the 1327 first valid hexadecimal digit. Then, the function stops at the first character that is 1328 a not a valid hexadecimal character or NULL, whichever one comes first. 1329 1330 If String is NULL, then ASSERT(). 1331 If String is not aligned in a 16-bit boundary, then ASSERT(). 1332 If String has only pad spaces, then zero is returned. 1333 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, 1334 then zero is returned. 1335 If the number represented by String overflows according to the range defined by 1336 UINT64, then MAX_UINT64 is returned. 1337 1338 If PcdMaximumUnicodeStringLength is not zero, and String contains more than 1339 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, 1340 then ASSERT(). 1341 1342 @param String The pointer to a Null-terminated Unicode string. 1343 1344 @retval Value translated from String. 1345 1346 **/ 1347 UINT64 1348 EFIAPI 1349 StrHexToUint64 ( 1350 IN CONST CHAR16 *String 1351 ); 1352 1353 /** 1354 Convert a Null-terminated Unicode string to IPv6 address and prefix length. 1355 1356 This function outputs a value of type IPv6_ADDRESS and may output a value 1357 of type UINT8 by interpreting the contents of the Unicode string specified 1358 by String. The format of the input Unicode string String is as follows: 1359 1360 X:X:X:X:X:X:X:X[/P] 1361 1362 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and 1363 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low 1364 memory address and high byte is stored in high memory address. P contains decimal 1365 digit characters in the range [0-9]. The running zero in the beginning of P will 1366 be ignored. /P is optional. 1367 1368 When /P is not in the String, the function stops at the first character that is 1369 not a valid hexadecimal digit character after eight X's are converted. 1370 1371 When /P is in the String, the function stops at the first character that is not 1372 a valid decimal digit character after P is converted. 1373 1374 "::" can be used to compress one or more groups of X when X contains only 0. 1375 The "::" can only appear once in the String. 1376 1377 If String is not aligned in a 16-bit boundary, then ASSERT(). 1378 1379 If EndPointer is not NULL and Address is translated from String, a pointer 1380 to the character that stopped the scan is stored at the location pointed to 1381 by EndPointer. 1382 1383 @param String Pointer to a Null-terminated Unicode string. 1384 @param EndPointer Pointer to character that stops scan. 1385 @param Address Pointer to the converted IPv6 address. 1386 @param PrefixLength Pointer to the converted IPv6 address prefix 1387 length. MAX_UINT8 is returned when /P is 1388 not in the String. 1389 1390 @retval RETURN_SUCCESS Address is translated from String. 1391 @retval RETURN_INVALID_PARAMETER If String is NULL. 1392 If Data is NULL. 1393 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal 1394 digit characters. 1395 If String contains "::" and number of X 1396 is not less than 8. 1397 If P starts with character that is not a 1398 valid decimal digit character. 1399 If the decimal number converted from P 1400 exceeds 128. 1401 1402 **/ 1403 RETURN_STATUS 1404 EFIAPI 1405 StrToIpv6Address ( 1406 IN CONST CHAR16 *String, 1407 OUT CHAR16 **EndPointer OPTIONAL, 1408 OUT IPv6_ADDRESS *Address, 1409 OUT UINT8 *PrefixLength OPTIONAL 1410 ); 1411 1412 /** 1413 Convert a Null-terminated Unicode string to IPv4 address and prefix length. 1414 1415 This function outputs a value of type IPv4_ADDRESS and may output a value 1416 of type UINT8 by interpreting the contents of the Unicode string specified 1417 by String. The format of the input Unicode string String is as follows: 1418 1419 D.D.D.D[/P] 1420 1421 D and P are decimal digit characters in the range [0-9]. The running zero in 1422 the beginning of D and P will be ignored. /P is optional. 1423 1424 When /P is not in the String, the function stops at the first character that is 1425 not a valid decimal digit character after four D's are converted. 1426 1427 When /P is in the String, the function stops at the first character that is not 1428 a valid decimal digit character after P is converted. 1429 1430 If String is not aligned in a 16-bit boundary, then ASSERT(). 1431 1432 If EndPointer is not NULL and Address is translated from String, a pointer 1433 to the character that stopped the scan is stored at the location pointed to 1434 by EndPointer. 1435 1436 @param String Pointer to a Null-terminated Unicode string. 1437 @param EndPointer Pointer to character that stops scan. 1438 @param Address Pointer to the converted IPv4 address. 1439 @param PrefixLength Pointer to the converted IPv4 address prefix 1440 length. MAX_UINT8 is returned when /P is 1441 not in the String. 1442 1443 @retval RETURN_SUCCESS Address is translated from String. 1444 @retval RETURN_INVALID_PARAMETER If String is NULL. 1445 If Data is NULL. 1446 @retval RETURN_UNSUPPORTED If String is not in the correct format. 1447 If any decimal number converted from D 1448 exceeds 255. 1449 If the decimal number converted from P 1450 exceeds 32. 1451 1452 **/ 1453 RETURN_STATUS 1454 EFIAPI 1455 StrToIpv4Address ( 1456 IN CONST CHAR16 *String, 1457 OUT CHAR16 **EndPointer OPTIONAL, 1458 OUT IPv4_ADDRESS *Address, 1459 OUT UINT8 *PrefixLength OPTIONAL 1460 ); 1461 1462 #define GUID_STRING_LENGTH 36 1463 1464 /** 1465 Convert a Null-terminated Unicode GUID string to a value of type 1466 EFI_GUID. 1467 1468 This function outputs a GUID value by interpreting the contents of 1469 the Unicode string specified by String. The format of the input 1470 Unicode string String consists of 36 characters, as follows: 1471 1472 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp 1473 1474 The pairs aa - pp are two characters in the range [0-9], [a-f] and 1475 [A-F], with each pair representing a single byte hexadecimal value. 1476 1477 The mapping between String and the EFI_GUID structure is as follows: 1478 aa Data1[24:31] 1479 bb Data1[16:23] 1480 cc Data1[8:15] 1481 dd Data1[0:7] 1482 ee Data2[8:15] 1483 ff Data2[0:7] 1484 gg Data3[8:15] 1485 hh Data3[0:7] 1486 ii Data4[0:7] 1487 jj Data4[8:15] 1488 kk Data4[16:23] 1489 ll Data4[24:31] 1490 mm Data4[32:39] 1491 nn Data4[40:47] 1492 oo Data4[48:55] 1493 pp Data4[56:63] 1494 1495 If String is not aligned in a 16-bit boundary, then ASSERT(). 1496 1497 @param String Pointer to a Null-terminated Unicode string. 1498 @param Guid Pointer to the converted GUID. 1499 1500 @retval RETURN_SUCCESS Guid is translated from String. 1501 @retval RETURN_INVALID_PARAMETER If String is NULL. 1502 If Data is NULL. 1503 @retval RETURN_UNSUPPORTED If String is not as the above format. 1504 1505 **/ 1506 RETURN_STATUS 1507 EFIAPI 1508 StrToGuid ( 1509 IN CONST CHAR16 *String, 1510 OUT GUID *Guid 1511 ); 1512 1513 /** 1514 Convert a Null-terminated Unicode hexadecimal string to a byte array. 1515 1516 This function outputs a byte array by interpreting the contents of 1517 the Unicode string specified by String in hexadecimal format. The format of 1518 the input Unicode string String is: 1519 1520 [XX]* 1521 1522 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F]. 1523 The function decodes every two hexadecimal digit characters as one byte. The 1524 decoding stops after Length of characters and outputs Buffer containing 1525 (Length / 2) bytes. 1526 1527 If String is not aligned in a 16-bit boundary, then ASSERT(). 1528 1529 @param String Pointer to a Null-terminated Unicode string. 1530 @param Length The number of Unicode characters to decode. 1531 @param Buffer Pointer to the converted bytes array. 1532 @param MaxBufferSize The maximum size of Buffer. 1533 1534 @retval RETURN_SUCCESS Buffer is translated from String. 1535 @retval RETURN_INVALID_PARAMETER If String is NULL. 1536 If Data is NULL. 1537 If Length is not multiple of 2. 1538 If PcdMaximumUnicodeStringLength is not zero, 1539 and Length is greater than 1540 PcdMaximumUnicodeStringLength. 1541 @retval RETURN_UNSUPPORTED If Length of characters from String contain 1542 a character that is not valid hexadecimal 1543 digit characters, or a Null-terminator. 1544 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2). 1545 **/ 1546 RETURN_STATUS 1547 EFIAPI 1548 StrHexToBytes ( 1549 IN CONST CHAR16 *String, 1550 IN UINTN Length, 1551 OUT UINT8 *Buffer, 1552 IN UINTN MaxBufferSize 1553 ); 1554 1555 /** 1556 Convert a Null-terminated Unicode string to a Null-terminated 1557 ASCII string. 1558 1559 This function is similar to AsciiStrCpyS. 1560 1561 This function converts the content of the Unicode string Source 1562 to the ASCII string Destination by copying the lower 8 bits of 1563 each Unicode character. The function terminates the ASCII string 1564 Destination by appending a Null-terminator character at the end. 1565 1566 The caller is responsible to make sure Destination points to a buffer with size 1567 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes. 1568 1569 If any Unicode characters in Source contain non-zero value in 1570 the upper 8 bits, then ASSERT(). 1571 1572 If Source is not aligned on a 16-bit boundary, then ASSERT(). 1573 1574 If an error is returned, then the Destination is unmodified. 1575 1576 @param Source The pointer to a Null-terminated Unicode string. 1577 @param Destination The pointer to a Null-terminated ASCII string. 1578 @param DestMax The maximum number of Destination Ascii 1579 char, including terminating null char. 1580 1581 @retval RETURN_SUCCESS String is converted. 1582 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source). 1583 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 1584 If Source is NULL. 1585 If PcdMaximumAsciiStringLength is not zero, 1586 and DestMax is greater than 1587 PcdMaximumAsciiStringLength. 1588 If PcdMaximumUnicodeStringLength is not zero, 1589 and DestMax is greater than 1590 PcdMaximumUnicodeStringLength. 1591 If DestMax is 0. 1592 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 1593 1594 **/ 1595 RETURN_STATUS 1596 EFIAPI 1597 UnicodeStrToAsciiStrS ( 1598 IN CONST CHAR16 *Source, 1599 OUT CHAR8 *Destination, 1600 IN UINTN DestMax 1601 ); 1602 1603 /** 1604 Convert not more than Length successive characters from a Null-terminated 1605 Unicode string to a Null-terminated Ascii string. If no null char is copied 1606 from Source, then Destination[Length] is always set to null. 1607 1608 This function converts not more than Length successive characters from the 1609 Unicode string Source to the Ascii string Destination by copying the lower 8 1610 bits of each Unicode character. The function terminates the Ascii string 1611 Destination by appending a Null-terminator character at the end. 1612 1613 The caller is responsible to make sure Destination points to a buffer with size 1614 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes. 1615 1616 If any Unicode characters in Source contain non-zero value in the upper 8 1617 bits, then ASSERT(). 1618 If Source is not aligned on a 16-bit boundary, then ASSERT(). 1619 1620 If an error is returned, then the Destination is unmodified. 1621 1622 @param Source The pointer to a Null-terminated Unicode string. 1623 @param Length The maximum number of Unicode characters to 1624 convert. 1625 @param Destination The pointer to a Null-terminated Ascii string. 1626 @param DestMax The maximum number of Destination Ascii 1627 char, including terminating null char. 1628 @param DestinationLength The number of Unicode characters converted. 1629 1630 @retval RETURN_SUCCESS String is converted. 1631 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 1632 If Source is NULL. 1633 If DestinationLength is NULL. 1634 If PcdMaximumAsciiStringLength is not zero, 1635 and Length or DestMax is greater than 1636 PcdMaximumAsciiStringLength. 1637 If PcdMaximumUnicodeStringLength is not 1638 zero, and Length or DestMax is greater than 1639 PcdMaximumUnicodeStringLength. 1640 If DestMax is 0. 1641 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than 1642 MIN(StrLen(Source), Length). 1643 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 1644 1645 **/ 1646 RETURN_STATUS 1647 EFIAPI 1648 UnicodeStrnToAsciiStrS ( 1649 IN CONST CHAR16 *Source, 1650 IN UINTN Length, 1651 OUT CHAR8 *Destination, 1652 IN UINTN DestMax, 1653 OUT UINTN *DestinationLength 1654 ); 1655 1656 /** 1657 Returns the length of a Null-terminated ASCII string. 1658 1659 This function returns the number of ASCII characters in the Null-terminated 1660 ASCII string specified by String. 1661 1662 If Length > 0 and Destination is NULL, then ASSERT(). 1663 If Length > 0 and Source is NULL, then ASSERT(). 1664 If PcdMaximumAsciiStringLength is not zero and String contains more than 1665 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 1666 then ASSERT(). 1667 1668 @param String The pointer to a Null-terminated ASCII string. 1669 1670 @return The length of String. 1671 1672 **/ 1673 UINTN 1674 EFIAPI 1675 AsciiStrLen ( 1676 IN CONST CHAR8 *String 1677 ); 1678 1679 /** 1680 Returns the size of a Null-terminated ASCII string in bytes, including the 1681 Null terminator. 1682 1683 This function returns the size, in bytes, of the Null-terminated ASCII string 1684 specified by String. 1685 1686 If String is NULL, then ASSERT(). 1687 If PcdMaximumAsciiStringLength is not zero and String contains more than 1688 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 1689 then ASSERT(). 1690 1691 @param String The pointer to a Null-terminated ASCII string. 1692 1693 @return The size of String. 1694 1695 **/ 1696 UINTN 1697 EFIAPI 1698 AsciiStrSize ( 1699 IN CONST CHAR8 *String 1700 ); 1701 1702 /** 1703 Compares two Null-terminated ASCII strings, and returns the difference 1704 between the first mismatched ASCII characters. 1705 1706 This function compares the Null-terminated ASCII string FirstString to the 1707 Null-terminated ASCII string SecondString. If FirstString is identical to 1708 SecondString, then 0 is returned. Otherwise, the value returned is the first 1709 mismatched ASCII character in SecondString subtracted from the first 1710 mismatched ASCII character in FirstString. 1711 1712 If FirstString is NULL, then ASSERT(). 1713 If SecondString is NULL, then ASSERT(). 1714 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than 1715 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 1716 then ASSERT(). 1717 If PcdMaximumAsciiStringLength is not zero and SecondString contains more 1718 than PcdMaximumAsciiStringLength ASCII characters not including the 1719 Null-terminator, then ASSERT(). 1720 1721 @param FirstString The pointer to a Null-terminated ASCII string. 1722 @param SecondString The pointer to a Null-terminated ASCII string. 1723 1724 @retval ==0 FirstString is identical to SecondString. 1725 @retval !=0 FirstString is not identical to SecondString. 1726 1727 **/ 1728 INTN 1729 EFIAPI 1730 AsciiStrCmp ( 1731 IN CONST CHAR8 *FirstString, 1732 IN CONST CHAR8 *SecondString 1733 ); 1734 1735 /** 1736 Performs a case insensitive comparison of two Null-terminated ASCII strings, 1737 and returns the difference between the first mismatched ASCII characters. 1738 1739 This function performs a case insensitive comparison of the Null-terminated 1740 ASCII string FirstString to the Null-terminated ASCII string SecondString. If 1741 FirstString is identical to SecondString, then 0 is returned. Otherwise, the 1742 value returned is the first mismatched lower case ASCII character in 1743 SecondString subtracted from the first mismatched lower case ASCII character 1744 in FirstString. 1745 1746 If FirstString is NULL, then ASSERT(). 1747 If SecondString is NULL, then ASSERT(). 1748 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than 1749 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 1750 then ASSERT(). 1751 If PcdMaximumAsciiStringLength is not zero and SecondString contains more 1752 than PcdMaximumAsciiStringLength ASCII characters not including the 1753 Null-terminator, then ASSERT(). 1754 1755 @param FirstString The pointer to a Null-terminated ASCII string. 1756 @param SecondString The pointer to a Null-terminated ASCII string. 1757 1758 @retval ==0 FirstString is identical to SecondString using case insensitive 1759 comparisons. 1760 @retval !=0 FirstString is not identical to SecondString using case 1761 insensitive comparisons. 1762 1763 **/ 1764 INTN 1765 EFIAPI 1766 AsciiStriCmp ( 1767 IN CONST CHAR8 *FirstString, 1768 IN CONST CHAR8 *SecondString 1769 ); 1770 1771 /** 1772 Compares two Null-terminated ASCII strings with maximum lengths, and returns 1773 the difference between the first mismatched ASCII characters. 1774 1775 This function compares the Null-terminated ASCII string FirstString to the 1776 Null-terminated ASCII string SecondString. At most, Length ASCII characters 1777 will be compared. If Length is 0, then 0 is returned. If FirstString is 1778 identical to SecondString, then 0 is returned. Otherwise, the value returned 1779 is the first mismatched ASCII character in SecondString subtracted from the 1780 first mismatched ASCII character in FirstString. 1781 1782 If Length > 0 and FirstString is NULL, then ASSERT(). 1783 If Length > 0 and SecondString is NULL, then ASSERT(). 1784 If PcdMaximumAsciiStringLength is not zero, and Length is greater than 1785 PcdMaximumAsciiStringLength, then ASSERT(). 1786 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than 1787 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1788 then ASSERT(). 1789 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than 1790 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1791 then ASSERT(). 1792 1793 @param FirstString The pointer to a Null-terminated ASCII string. 1794 @param SecondString The pointer to a Null-terminated ASCII string. 1795 @param Length The maximum number of ASCII characters for compare. 1796 1797 @retval ==0 FirstString is identical to SecondString. 1798 @retval !=0 FirstString is not identical to SecondString. 1799 1800 **/ 1801 INTN 1802 EFIAPI 1803 AsciiStrnCmp ( 1804 IN CONST CHAR8 *FirstString, 1805 IN CONST CHAR8 *SecondString, 1806 IN UINTN Length 1807 ); 1808 1809 /** 1810 Returns the first occurrence of a Null-terminated ASCII sub-string 1811 in a Null-terminated ASCII string. 1812 1813 This function scans the contents of the ASCII string specified by String 1814 and returns the first occurrence of SearchString. If SearchString is not 1815 found in String, then NULL is returned. If the length of SearchString is zero, 1816 then String is returned. 1817 1818 If String is NULL, then ASSERT(). 1819 If SearchString is NULL, then ASSERT(). 1820 1821 If PcdMaximumAsciiStringLength is not zero, and SearchString or 1822 String contains more than PcdMaximumAsciiStringLength Unicode characters 1823 not including the Null-terminator, then ASSERT(). 1824 1825 @param String The pointer to a Null-terminated ASCII string. 1826 @param SearchString The pointer to a Null-terminated ASCII string to search for. 1827 1828 @retval NULL If the SearchString does not appear in String. 1829 @retval others If there is a match return the first occurrence of SearchingString. 1830 If the length of SearchString is zero,return String. 1831 1832 **/ 1833 CHAR8 * 1834 EFIAPI 1835 AsciiStrStr ( 1836 IN CONST CHAR8 *String, 1837 IN CONST CHAR8 *SearchString 1838 ); 1839 1840 /** 1841 Convert a Null-terminated ASCII decimal string to a value of type 1842 UINTN. 1843 1844 This function returns a value of type UINTN by interpreting the contents 1845 of the ASCII string String as a decimal number. The format of the input 1846 ASCII string String is: 1847 1848 [spaces] [decimal digits]. 1849 1850 The valid decimal digit character is in the range [0-9]. The function will 1851 ignore the pad space, which includes spaces or tab characters, before the digits. 1852 The running zero in the beginning of [decimal digits] will be ignored. Then, the 1853 function stops at the first character that is a not a valid decimal character or 1854 Null-terminator, whichever on comes first. 1855 1856 If String has only pad spaces, then 0 is returned. 1857 If String has no pad spaces or valid decimal digits, then 0 is returned. 1858 If the number represented by String overflows according to the range defined by 1859 UINTN, then MAX_UINTN is returned. 1860 If String is NULL, then ASSERT(). 1861 If PcdMaximumAsciiStringLength is not zero, and String contains more than 1862 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 1863 then ASSERT(). 1864 1865 @param String The pointer to a Null-terminated ASCII string. 1866 1867 @retval The value translated from String. 1868 1869 **/ 1870 UINTN 1871 EFIAPI 1872 AsciiStrDecimalToUintn ( 1873 IN CONST CHAR8 *String 1874 ); 1875 1876 /** 1877 Convert a Null-terminated ASCII decimal string to a value of type 1878 UINT64. 1879 1880 This function returns a value of type UINT64 by interpreting the contents 1881 of the ASCII string String as a decimal number. The format of the input 1882 ASCII string String is: 1883 1884 [spaces] [decimal digits]. 1885 1886 The valid decimal digit character is in the range [0-9]. The function will 1887 ignore the pad space, which includes spaces or tab characters, before the digits. 1888 The running zero in the beginning of [decimal digits] will be ignored. Then, the 1889 function stops at the first character that is a not a valid decimal character or 1890 Null-terminator, whichever on comes first. 1891 1892 If String has only pad spaces, then 0 is returned. 1893 If String has no pad spaces or valid decimal digits, then 0 is returned. 1894 If the number represented by String overflows according to the range defined by 1895 UINT64, then MAX_UINT64 is returned. 1896 If String is NULL, then ASSERT(). 1897 If PcdMaximumAsciiStringLength is not zero, and String contains more than 1898 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 1899 then ASSERT(). 1900 1901 @param String The pointer to a Null-terminated ASCII string. 1902 1903 @retval Value translated from String. 1904 1905 **/ 1906 UINT64 1907 EFIAPI 1908 AsciiStrDecimalToUint64 ( 1909 IN CONST CHAR8 *String 1910 ); 1911 1912 /** 1913 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN. 1914 1915 This function returns a value of type UINTN by interpreting the contents of 1916 the ASCII string String as a hexadecimal number. The format of the input ASCII 1917 string String is: 1918 1919 [spaces][zeros][x][hexadecimal digits]. 1920 1921 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 1922 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" 1923 appears in the input string, it must be prefixed with at least one 0. The function 1924 will ignore the pad space, which includes spaces or tab characters, before [zeros], 1925 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits] 1926 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal 1927 digit. Then, the function stops at the first character that is a not a valid 1928 hexadecimal character or Null-terminator, whichever on comes first. 1929 1930 If String has only pad spaces, then 0 is returned. 1931 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then 1932 0 is returned. 1933 1934 If the number represented by String overflows according to the range defined by UINTN, 1935 then MAX_UINTN is returned. 1936 If String is NULL, then ASSERT(). 1937 If PcdMaximumAsciiStringLength is not zero, 1938 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including 1939 the Null-terminator, then ASSERT(). 1940 1941 @param String The pointer to a Null-terminated ASCII string. 1942 1943 @retval Value translated from String. 1944 1945 **/ 1946 UINTN 1947 EFIAPI 1948 AsciiStrHexToUintn ( 1949 IN CONST CHAR8 *String 1950 ); 1951 1952 /** 1953 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64. 1954 1955 This function returns a value of type UINT64 by interpreting the contents of 1956 the ASCII string String as a hexadecimal number. The format of the input ASCII 1957 string String is: 1958 1959 [spaces][zeros][x][hexadecimal digits]. 1960 1961 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 1962 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" 1963 appears in the input string, it must be prefixed with at least one 0. The function 1964 will ignore the pad space, which includes spaces or tab characters, before [zeros], 1965 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits] 1966 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal 1967 digit. Then, the function stops at the first character that is a not a valid 1968 hexadecimal character or Null-terminator, whichever on comes first. 1969 1970 If String has only pad spaces, then 0 is returned. 1971 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then 1972 0 is returned. 1973 1974 If the number represented by String overflows according to the range defined by UINT64, 1975 then MAX_UINT64 is returned. 1976 If String is NULL, then ASSERT(). 1977 If PcdMaximumAsciiStringLength is not zero, 1978 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including 1979 the Null-terminator, then ASSERT(). 1980 1981 @param String The pointer to a Null-terminated ASCII string. 1982 1983 @retval Value translated from String. 1984 1985 **/ 1986 UINT64 1987 EFIAPI 1988 AsciiStrHexToUint64 ( 1989 IN CONST CHAR8 *String 1990 ); 1991 1992 /** 1993 Convert a Null-terminated ASCII string to IPv6 address and prefix length. 1994 1995 This function outputs a value of type IPv6_ADDRESS and may output a value 1996 of type UINT8 by interpreting the contents of the ASCII string specified 1997 by String. The format of the input ASCII string String is as follows: 1998 1999 X:X:X:X:X:X:X:X[/P] 2000 2001 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and 2002 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low 2003 memory address and high byte is stored in high memory address. P contains decimal 2004 digit characters in the range [0-9]. The running zero in the beginning of P will 2005 be ignored. /P is optional. 2006 2007 When /P is not in the String, the function stops at the first character that is 2008 not a valid hexadecimal digit character after eight X's are converted. 2009 2010 When /P is in the String, the function stops at the first character that is not 2011 a valid decimal digit character after P is converted. 2012 2013 "::" can be used to compress one or more groups of X when X contains only 0. 2014 The "::" can only appear once in the String. 2015 2016 If EndPointer is not NULL and Address is translated from String, a pointer 2017 to the character that stopped the scan is stored at the location pointed to 2018 by EndPointer. 2019 2020 @param String Pointer to a Null-terminated ASCII string. 2021 @param EndPointer Pointer to character that stops scan. 2022 @param Address Pointer to the converted IPv6 address. 2023 @param PrefixLength Pointer to the converted IPv6 address prefix 2024 length. MAX_UINT8 is returned when /P is 2025 not in the String. 2026 2027 @retval RETURN_SUCCESS Address is translated from String. 2028 @retval RETURN_INVALID_PARAMETER If String is NULL. 2029 If Data is NULL. 2030 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal 2031 digit characters. 2032 If String contains "::" and number of X 2033 is not less than 8. 2034 If P starts with character that is not a 2035 valid decimal digit character. 2036 If the decimal number converted from P 2037 exceeds 128. 2038 2039 **/ 2040 RETURN_STATUS 2041 EFIAPI 2042 AsciiStrToIpv6Address ( 2043 IN CONST CHAR8 *String, 2044 OUT CHAR8 **EndPointer OPTIONAL, 2045 OUT IPv6_ADDRESS *Address, 2046 OUT UINT8 *PrefixLength OPTIONAL 2047 ); 2048 2049 /** 2050 Convert a Null-terminated ASCII string to IPv4 address and prefix length. 2051 2052 This function outputs a value of type IPv4_ADDRESS and may output a value 2053 of type UINT8 by interpreting the contents of the ASCII string specified 2054 by String. The format of the input ASCII string String is as follows: 2055 2056 D.D.D.D[/P] 2057 2058 D and P are decimal digit characters in the range [0-9]. The running zero in 2059 the beginning of D and P will be ignored. /P is optional. 2060 2061 When /P is not in the String, the function stops at the first character that is 2062 not a valid decimal digit character after four D's are converted. 2063 2064 When /P is in the String, the function stops at the first character that is not 2065 a valid decimal digit character after P is converted. 2066 2067 If EndPointer is not NULL and Address is translated from String, a pointer 2068 to the character that stopped the scan is stored at the location pointed to 2069 by EndPointer. 2070 2071 @param String Pointer to a Null-terminated ASCII string. 2072 @param EndPointer Pointer to character that stops scan. 2073 @param Address Pointer to the converted IPv4 address. 2074 @param PrefixLength Pointer to the converted IPv4 address prefix 2075 length. MAX_UINT8 is returned when /P is 2076 not in the String. 2077 2078 @retval RETURN_SUCCESS Address is translated from String. 2079 @retval RETURN_INVALID_PARAMETER If String is NULL. 2080 If Data is NULL. 2081 @retval RETURN_UNSUPPORTED If String is not in the correct format. 2082 If any decimal number converted from D 2083 exceeds 255. 2084 If the decimal number converted from P 2085 exceeds 32. 2086 2087 **/ 2088 RETURN_STATUS 2089 EFIAPI 2090 AsciiStrToIpv4Address ( 2091 IN CONST CHAR8 *String, 2092 OUT CHAR8 **EndPointer OPTIONAL, 2093 OUT IPv4_ADDRESS *Address, 2094 OUT UINT8 *PrefixLength OPTIONAL 2095 ); 2096 2097 /** 2098 Convert a Null-terminated ASCII GUID string to a value of type 2099 EFI_GUID. 2100 2101 This function outputs a GUID value by interpreting the contents of 2102 the ASCII string specified by String. The format of the input 2103 ASCII string String consists of 36 characters, as follows: 2104 2105 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp 2106 2107 The pairs aa - pp are two characters in the range [0-9], [a-f] and 2108 [A-F], with each pair representing a single byte hexadecimal value. 2109 2110 The mapping between String and the EFI_GUID structure is as follows: 2111 aa Data1[24:31] 2112 bb Data1[16:23] 2113 cc Data1[8:15] 2114 dd Data1[0:7] 2115 ee Data2[8:15] 2116 ff Data2[0:7] 2117 gg Data3[8:15] 2118 hh Data3[0:7] 2119 ii Data4[0:7] 2120 jj Data4[8:15] 2121 kk Data4[16:23] 2122 ll Data4[24:31] 2123 mm Data4[32:39] 2124 nn Data4[40:47] 2125 oo Data4[48:55] 2126 pp Data4[56:63] 2127 2128 @param String Pointer to a Null-terminated ASCII string. 2129 @param Guid Pointer to the converted GUID. 2130 2131 @retval RETURN_SUCCESS Guid is translated from String. 2132 @retval RETURN_INVALID_PARAMETER If String is NULL. 2133 If Data is NULL. 2134 @retval RETURN_UNSUPPORTED If String is not as the above format. 2135 2136 **/ 2137 RETURN_STATUS 2138 EFIAPI 2139 AsciiStrToGuid ( 2140 IN CONST CHAR8 *String, 2141 OUT GUID *Guid 2142 ); 2143 2144 /** 2145 Convert a Null-terminated ASCII hexadecimal string to a byte array. 2146 2147 This function outputs a byte array by interpreting the contents of 2148 the ASCII string specified by String in hexadecimal format. The format of 2149 the input ASCII string String is: 2150 2151 [XX]* 2152 2153 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F]. 2154 The function decodes every two hexadecimal digit characters as one byte. The 2155 decoding stops after Length of characters and outputs Buffer containing 2156 (Length / 2) bytes. 2157 2158 @param String Pointer to a Null-terminated ASCII string. 2159 @param Length The number of ASCII characters to decode. 2160 @param Buffer Pointer to the converted bytes array. 2161 @param MaxBufferSize The maximum size of Buffer. 2162 2163 @retval RETURN_SUCCESS Buffer is translated from String. 2164 @retval RETURN_INVALID_PARAMETER If String is NULL. 2165 If Data is NULL. 2166 If Length is not multiple of 2. 2167 If PcdMaximumAsciiStringLength is not zero, 2168 and Length is greater than 2169 PcdMaximumAsciiStringLength. 2170 @retval RETURN_UNSUPPORTED If Length of characters from String contain 2171 a character that is not valid hexadecimal 2172 digit characters, or a Null-terminator. 2173 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2). 2174 **/ 2175 RETURN_STATUS 2176 EFIAPI 2177 AsciiStrHexToBytes ( 2178 IN CONST CHAR8 *String, 2179 IN UINTN Length, 2180 OUT UINT8 *Buffer, 2181 IN UINTN MaxBufferSize 2182 ); 2183 2184 /** 2185 Convert one Null-terminated ASCII string to a Null-terminated 2186 Unicode string. 2187 2188 This function is similar to StrCpyS. 2189 2190 This function converts the contents of the ASCII string Source to the Unicode 2191 string Destination. The function terminates the Unicode string Destination by 2192 appending a Null-terminator character at the end. 2193 2194 The caller is responsible to make sure Destination points to a buffer with size 2195 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes. 2196 2197 If Destination is not aligned on a 16-bit boundary, then ASSERT(). 2198 2199 If an error is returned, then the Destination is unmodified. 2200 2201 @param Source The pointer to a Null-terminated ASCII string. 2202 @param Destination The pointer to a Null-terminated Unicode string. 2203 @param DestMax The maximum number of Destination Unicode 2204 char, including terminating null char. 2205 2206 @retval RETURN_SUCCESS String is converted. 2207 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source). 2208 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 2209 If Source is NULL. 2210 If PcdMaximumUnicodeStringLength is not zero, 2211 and DestMax is greater than 2212 PcdMaximumUnicodeStringLength. 2213 If PcdMaximumAsciiStringLength is not zero, 2214 and DestMax is greater than 2215 PcdMaximumAsciiStringLength. 2216 If DestMax is 0. 2217 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 2218 2219 **/ 2220 RETURN_STATUS 2221 EFIAPI 2222 AsciiStrToUnicodeStrS ( 2223 IN CONST CHAR8 *Source, 2224 OUT CHAR16 *Destination, 2225 IN UINTN DestMax 2226 ); 2227 2228 /** 2229 Convert not more than Length successive characters from a Null-terminated 2230 Ascii string to a Null-terminated Unicode string. If no null char is copied 2231 from Source, then Destination[Length] is always set to null. 2232 2233 This function converts not more than Length successive characters from the 2234 Ascii string Source to the Unicode string Destination. The function 2235 terminates the Unicode string Destination by appending a Null-terminator 2236 character at the end. 2237 2238 The caller is responsible to make sure Destination points to a buffer with 2239 size not smaller than 2240 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes. 2241 2242 If Destination is not aligned on a 16-bit boundary, then ASSERT(). 2243 2244 If an error is returned, then Destination and DestinationLength are 2245 unmodified. 2246 2247 @param Source The pointer to a Null-terminated Ascii string. 2248 @param Length The maximum number of Ascii characters to convert. 2249 @param Destination The pointer to a Null-terminated Unicode string. 2250 @param DestMax The maximum number of Destination Unicode char, 2251 including terminating null char. 2252 @param DestinationLength The number of Ascii characters converted. 2253 2254 @retval RETURN_SUCCESS String is converted. 2255 @retval RETURN_INVALID_PARAMETER If Destination is NULL. 2256 If Source is NULL. 2257 If DestinationLength is NULL. 2258 If PcdMaximumUnicodeStringLength is not 2259 zero, and Length or DestMax is greater than 2260 PcdMaximumUnicodeStringLength. 2261 If PcdMaximumAsciiStringLength is not zero, 2262 and Length or DestMax is greater than 2263 PcdMaximumAsciiStringLength. 2264 If DestMax is 0. 2265 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than 2266 MIN(AsciiStrLen(Source), Length). 2267 @retval RETURN_ACCESS_DENIED If Source and Destination overlap. 2268 2269 **/ 2270 RETURN_STATUS 2271 EFIAPI 2272 AsciiStrnToUnicodeStrS ( 2273 IN CONST CHAR8 *Source, 2274 IN UINTN Length, 2275 OUT CHAR16 *Destination, 2276 IN UINTN DestMax, 2277 OUT UINTN *DestinationLength 2278 ); 2279 2280 /** 2281 Convert a Unicode character to upper case only if 2282 it maps to a valid small-case ASCII character. 2283 2284 This internal function only deal with Unicode character 2285 which maps to a valid small-case ASCII character, i.e. 2286 L'a' to L'z'. For other Unicode character, the input character 2287 is returned directly. 2288 2289 @param Char The character to convert. 2290 2291 @retval LowerCharacter If the Char is with range L'a' to L'z'. 2292 @retval Unchanged Otherwise. 2293 2294 **/ 2295 CHAR16 2296 EFIAPI 2297 CharToUpper ( 2298 IN CHAR16 Char 2299 ); 2300 2301 /** 2302 Converts a lowercase Ascii character to upper one. 2303 2304 If Chr is lowercase Ascii character, then converts it to upper one. 2305 2306 If Value >= 0xA0, then ASSERT(). 2307 If (Value & 0x0F) >= 0x0A, then ASSERT(). 2308 2309 @param Chr one Ascii character 2310 2311 @return The uppercase value of Ascii character 2312 2313 **/ 2314 CHAR8 2315 EFIAPI 2316 AsciiCharToUpper ( 2317 IN CHAR8 Chr 2318 ); 2319 2320 /** 2321 Convert binary data to a Base64 encoded ascii string based on RFC4648. 2322 2323 Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize. 2324 The Ascii string is produced by converting the data string specified by Source and SourceLength. 2325 2326 @param Source Input UINT8 data 2327 @param SourceLength Number of UINT8 bytes of data 2328 @param Destination Pointer to output string buffer 2329 @param DestinationSize Size of ascii buffer. Set to 0 to get the size needed. 2330 Caller is responsible for passing in buffer of DestinationSize 2331 2332 @retval RETURN_SUCCESS When ascii buffer is filled in. 2333 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL. 2334 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination). 2335 @retval RETURN_BUFFER_TOO_SMALL If SourceLength is 0 and DestinationSize is <1. 2336 @retval RETURN_BUFFER_TOO_SMALL If Destination is NULL or DestinationSize is smaller than required buffersize. 2337 2338 **/ 2339 RETURN_STATUS 2340 EFIAPI 2341 Base64Encode ( 2342 IN CONST UINT8 *Source, 2343 IN UINTN SourceLength, 2344 OUT CHAR8 *Destination OPTIONAL, 2345 IN OUT UINTN *DestinationSize 2346 ); 2347 2348 /** 2349 Decode Base64 ASCII encoded data to 8-bit binary representation, based on 2350 RFC4648. 2351 2352 Decoding occurs according to "Table 1: The Base 64 Alphabet" in RFC4648. 2353 2354 Whitespace is ignored at all positions: 2355 - 0x09 ('\t') horizontal tab 2356 - 0x0A ('\n') new line 2357 - 0x0B ('\v') vertical tab 2358 - 0x0C ('\f') form feed 2359 - 0x0D ('\r') carriage return 2360 - 0x20 (' ') space 2361 2362 The minimum amount of required padding (with ASCII 0x3D, '=') is tolerated 2363 and enforced at the end of the Base64 ASCII encoded data, and only there. 2364 2365 Other characters outside of the encoding alphabet cause the function to 2366 reject the Base64 ASCII encoded data. 2367 2368 @param[in] Source Array of CHAR8 elements containing the Base64 2369 ASCII encoding. May be NULL if SourceSize is 2370 zero. 2371 2372 @param[in] SourceSize Number of CHAR8 elements in Source. 2373 2374 @param[out] Destination Array of UINT8 elements receiving the decoded 2375 8-bit binary representation. Allocated by the 2376 caller. May be NULL if DestinationSize is 2377 zero on input. If NULL, decoding is 2378 performed, but the 8-bit binary 2379 representation is not stored. If non-NULL and 2380 the function returns an error, the contents 2381 of Destination are indeterminate. 2382 2383 @param[in,out] DestinationSize On input, the number of UINT8 elements that 2384 the caller allocated for Destination. On 2385 output, if the function returns 2386 RETURN_SUCCESS or RETURN_BUFFER_TOO_SMALL, 2387 the number of UINT8 elements that are 2388 required for decoding the Base64 ASCII 2389 representation. If the function returns a 2390 value different from both RETURN_SUCCESS and 2391 RETURN_BUFFER_TOO_SMALL, then DestinationSize 2392 is indeterminate on output. 2393 2394 @retval RETURN_SUCCESS SourceSize CHAR8 elements at Source have 2395 been decoded to on-output DestinationSize 2396 UINT8 elements at Destination. Note that 2397 RETURN_SUCCESS covers the case when 2398 DestinationSize is zero on input, and 2399 Source decodes to zero bytes (due to 2400 containing at most ignored whitespace). 2401 2402 @retval RETURN_BUFFER_TOO_SMALL The input value of DestinationSize is not 2403 large enough for decoding SourceSize CHAR8 2404 elements at Source. The required number of 2405 UINT8 elements has been stored to 2406 DestinationSize. 2407 2408 @retval RETURN_INVALID_PARAMETER DestinationSize is NULL. 2409 2410 @retval RETURN_INVALID_PARAMETER Source is NULL, but SourceSize is not zero. 2411 2412 @retval RETURN_INVALID_PARAMETER Destination is NULL, but DestinationSize is 2413 not zero on input. 2414 2415 @retval RETURN_INVALID_PARAMETER Source is non-NULL, and (Source + 2416 SourceSize) would wrap around MAX_ADDRESS. 2417 2418 @retval RETURN_INVALID_PARAMETER Destination is non-NULL, and (Destination + 2419 DestinationSize) would wrap around 2420 MAX_ADDRESS, as specified on input. 2421 2422 @retval RETURN_INVALID_PARAMETER None of Source and Destination are NULL, 2423 and CHAR8[SourceSize] at Source overlaps 2424 UINT8[DestinationSize] at Destination, as 2425 specified on input. 2426 2427 @retval RETURN_INVALID_PARAMETER Invalid CHAR8 element encountered in 2428 Source. 2429 **/ 2430 RETURN_STATUS 2431 EFIAPI 2432 Base64Decode ( 2433 IN CONST CHAR8 *Source OPTIONAL, 2434 IN UINTN SourceSize, 2435 OUT UINT8 *Destination OPTIONAL, 2436 IN OUT UINTN *DestinationSize 2437 ); 2438 2439 /** 2440 Converts an 8-bit value to an 8-bit BCD value. 2441 2442 Converts the 8-bit value specified by Value to BCD. The BCD value is 2443 returned. 2444 2445 If Value >= 100, then ASSERT(). 2446 2447 @param Value The 8-bit value to convert to BCD. Range 0..99. 2448 2449 @return The BCD value. 2450 2451 **/ 2452 UINT8 2453 EFIAPI 2454 DecimalToBcd8 ( 2455 IN UINT8 Value 2456 ); 2457 2458 /** 2459 Converts an 8-bit BCD value to an 8-bit value. 2460 2461 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit 2462 value is returned. 2463 2464 If Value >= 0xA0, then ASSERT(). 2465 If (Value & 0x0F) >= 0x0A, then ASSERT(). 2466 2467 @param Value The 8-bit BCD value to convert to an 8-bit value. 2468 2469 @return The 8-bit value is returned. 2470 2471 **/ 2472 UINT8 2473 EFIAPI 2474 BcdToDecimal8 ( 2475 IN UINT8 Value 2476 ); 2477 2478 // 2479 // File Path Manipulation Functions 2480 // 2481 2482 /** 2483 Removes the last directory or file entry in a path. 2484 2485 @param[in, out] Path The pointer to the path to modify. 2486 2487 @retval FALSE Nothing was found to remove. 2488 @retval TRUE A directory or file was removed. 2489 **/ 2490 BOOLEAN 2491 EFIAPI 2492 PathRemoveLastItem ( 2493 IN OUT CHAR16 *Path 2494 ); 2495 2496 /** 2497 Function to clean up paths. 2498 - Single periods in the path are removed. 2499 - Double periods in the path are removed along with a single parent directory. 2500 - Forward slashes L'/' are converted to backward slashes L'\'. 2501 2502 This will be done inline and the existing buffer may be larger than required 2503 upon completion. 2504 2505 @param[in] Path The pointer to the string containing the path. 2506 2507 @return Returns Path, otherwise returns NULL to indicate that an error has occurred. 2508 **/ 2509 CHAR16 * 2510 EFIAPI 2511 PathCleanUpDirectories ( 2512 IN CHAR16 *Path 2513 ); 2514 2515 // 2516 // Linked List Functions and Macros 2517 // 2518 2519 /** 2520 Initializes the head node of a doubly linked list that is declared as a 2521 global variable in a module. 2522 2523 Initializes the forward and backward links of a new linked list. After 2524 initializing a linked list with this macro, the other linked list functions 2525 may be used to add and remove nodes from the linked list. This macro results 2526 in smaller executables by initializing the linked list in the data section, 2527 instead if calling the InitializeListHead() function to perform the 2528 equivalent operation. 2529 2530 @param ListHead The head note of a list to initialize. 2531 2532 **/ 2533 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)} 2534 2535 /** 2536 Iterates over each node in a doubly linked list using each node's forward link. 2537 2538 @param Entry A pointer to a list node used as a loop cursor during iteration 2539 @param ListHead The head node of the doubly linked list 2540 2541 **/ 2542 #define BASE_LIST_FOR_EACH(Entry, ListHead) \ 2543 for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink) 2544 2545 /** 2546 Iterates over each node in a doubly linked list using each node's forward link 2547 with safety against node removal. 2548 2549 This macro uses NextEntry to temporarily store the next list node so the node 2550 pointed to by Entry may be deleted in the current loop iteration step and 2551 iteration can continue from the node pointed to by NextEntry. 2552 2553 @param Entry A pointer to a list node used as a loop cursor during iteration 2554 @param NextEntry A pointer to a list node used to temporarily store the next node 2555 @param ListHead The head node of the doubly linked list 2556 2557 **/ 2558 #define BASE_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \ 2559 for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\ 2560 Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink) 2561 2562 /** 2563 Checks whether FirstEntry and SecondEntry are part of the same doubly-linked 2564 list. 2565 2566 If FirstEntry is NULL, then ASSERT(). 2567 If FirstEntry->ForwardLink is NULL, then ASSERT(). 2568 If FirstEntry->BackLink is NULL, then ASSERT(). 2569 If SecondEntry is NULL, then ASSERT(); 2570 If PcdMaximumLinkedListLength is not zero, and List contains more than 2571 PcdMaximumLinkedListLength nodes, then ASSERT(). 2572 2573 @param FirstEntry A pointer to a node in a linked list. 2574 @param SecondEntry A pointer to the node to locate. 2575 2576 @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry. 2577 @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry, 2578 or FirstEntry is invalid. 2579 2580 **/ 2581 BOOLEAN 2582 EFIAPI 2583 IsNodeInList ( 2584 IN CONST LIST_ENTRY *FirstEntry, 2585 IN CONST LIST_ENTRY *SecondEntry 2586 ); 2587 2588 /** 2589 Initializes the head node of a doubly linked list, and returns the pointer to 2590 the head node of the doubly linked list. 2591 2592 Initializes the forward and backward links of a new linked list. After 2593 initializing a linked list with this function, the other linked list 2594 functions may be used to add and remove nodes from the linked list. It is up 2595 to the caller of this function to allocate the memory for ListHead. 2596 2597 If ListHead is NULL, then ASSERT(). 2598 2599 @param ListHead A pointer to the head node of a new doubly linked list. 2600 2601 @return ListHead 2602 2603 **/ 2604 LIST_ENTRY * 2605 EFIAPI 2606 InitializeListHead ( 2607 IN OUT LIST_ENTRY *ListHead 2608 ); 2609 2610 /** 2611 Adds a node to the beginning of a doubly linked list, and returns the pointer 2612 to the head node of the doubly linked list. 2613 2614 Adds the node Entry at the beginning of the doubly linked list denoted by 2615 ListHead, and returns ListHead. 2616 2617 If ListHead is NULL, then ASSERT(). 2618 If Entry is NULL, then ASSERT(). 2619 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or 2620 InitializeListHead(), then ASSERT(). 2621 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number 2622 of nodes in ListHead, including the ListHead node, is greater than or 2623 equal to PcdMaximumLinkedListLength, then ASSERT(). 2624 2625 @param ListHead A pointer to the head node of a doubly linked list. 2626 @param Entry A pointer to a node that is to be inserted at the beginning 2627 of a doubly linked list. 2628 2629 @return ListHead 2630 2631 **/ 2632 LIST_ENTRY * 2633 EFIAPI 2634 InsertHeadList ( 2635 IN OUT LIST_ENTRY *ListHead, 2636 IN OUT LIST_ENTRY *Entry 2637 ); 2638 2639 /** 2640 Adds a node to the end of a doubly linked list, and returns the pointer to 2641 the head node of the doubly linked list. 2642 2643 Adds the node Entry to the end of the doubly linked list denoted by ListHead, 2644 and returns ListHead. 2645 2646 If ListHead is NULL, then ASSERT(). 2647 If Entry is NULL, then ASSERT(). 2648 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or 2649 InitializeListHead(), then ASSERT(). 2650 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number 2651 of nodes in ListHead, including the ListHead node, is greater than or 2652 equal to PcdMaximumLinkedListLength, then ASSERT(). 2653 2654 @param ListHead A pointer to the head node of a doubly linked list. 2655 @param Entry A pointer to a node that is to be added at the end of the 2656 doubly linked list. 2657 2658 @return ListHead 2659 2660 **/ 2661 LIST_ENTRY * 2662 EFIAPI 2663 InsertTailList ( 2664 IN OUT LIST_ENTRY *ListHead, 2665 IN OUT LIST_ENTRY *Entry 2666 ); 2667 2668 /** 2669 Retrieves the first node of a doubly linked list. 2670 2671 Returns the first node of a doubly linked list. List must have been 2672 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(). 2673 If List is empty, then List is returned. 2674 2675 If List is NULL, then ASSERT(). 2676 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or 2677 InitializeListHead(), then ASSERT(). 2678 If PcdMaximumLinkedListLength is not zero, and the number of nodes 2679 in List, including the List node, is greater than or equal to 2680 PcdMaximumLinkedListLength, then ASSERT(). 2681 2682 @param List A pointer to the head node of a doubly linked list. 2683 2684 @return The first node of a doubly linked list. 2685 @retval List The list is empty. 2686 2687 **/ 2688 LIST_ENTRY * 2689 EFIAPI 2690 GetFirstNode ( 2691 IN CONST LIST_ENTRY *List 2692 ); 2693 2694 /** 2695 Retrieves the next node of a doubly linked list. 2696 2697 Returns the node of a doubly linked list that follows Node. 2698 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE() 2699 or InitializeListHead(). If List is empty, then List is returned. 2700 2701 If List is NULL, then ASSERT(). 2702 If Node is NULL, then ASSERT(). 2703 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or 2704 InitializeListHead(), then ASSERT(). 2705 If PcdMaximumLinkedListLength is not zero, and List contains more than 2706 PcdMaximumLinkedListLength nodes, then ASSERT(). 2707 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT(). 2708 2709 @param List A pointer to the head node of a doubly linked list. 2710 @param Node A pointer to a node in the doubly linked list. 2711 2712 @return The pointer to the next node if one exists. Otherwise List is returned. 2713 2714 **/ 2715 LIST_ENTRY * 2716 EFIAPI 2717 GetNextNode ( 2718 IN CONST LIST_ENTRY *List, 2719 IN CONST LIST_ENTRY *Node 2720 ); 2721 2722 /** 2723 Retrieves the previous node of a doubly linked list. 2724 2725 Returns the node of a doubly linked list that precedes Node. 2726 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE() 2727 or InitializeListHead(). If List is empty, then List is returned. 2728 2729 If List is NULL, then ASSERT(). 2730 If Node is NULL, then ASSERT(). 2731 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or 2732 InitializeListHead(), then ASSERT(). 2733 If PcdMaximumLinkedListLength is not zero, and List contains more than 2734 PcdMaximumLinkedListLength nodes, then ASSERT(). 2735 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT(). 2736 2737 @param List A pointer to the head node of a doubly linked list. 2738 @param Node A pointer to a node in the doubly linked list. 2739 2740 @return The pointer to the previous node if one exists. Otherwise List is returned. 2741 2742 **/ 2743 LIST_ENTRY * 2744 EFIAPI 2745 GetPreviousNode ( 2746 IN CONST LIST_ENTRY *List, 2747 IN CONST LIST_ENTRY *Node 2748 ); 2749 2750 /** 2751 Checks to see if a doubly linked list is empty or not. 2752 2753 Checks to see if the doubly linked list is empty. If the linked list contains 2754 zero nodes, this function returns TRUE. Otherwise, it returns FALSE. 2755 2756 If ListHead is NULL, then ASSERT(). 2757 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or 2758 InitializeListHead(), then ASSERT(). 2759 If PcdMaximumLinkedListLength is not zero, and the number of nodes 2760 in List, including the List node, is greater than or equal to 2761 PcdMaximumLinkedListLength, then ASSERT(). 2762 2763 @param ListHead A pointer to the head node of a doubly linked list. 2764 2765 @retval TRUE The linked list is empty. 2766 @retval FALSE The linked list is not empty. 2767 2768 **/ 2769 BOOLEAN 2770 EFIAPI 2771 IsListEmpty ( 2772 IN CONST LIST_ENTRY *ListHead 2773 ); 2774 2775 /** 2776 Determines if a node in a doubly linked list is the head node of a the same 2777 doubly linked list. This function is typically used to terminate a loop that 2778 traverses all the nodes in a doubly linked list starting with the head node. 2779 2780 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the 2781 nodes in the doubly linked list specified by List. List must have been 2782 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(). 2783 2784 If List is NULL, then ASSERT(). 2785 If Node is NULL, then ASSERT(). 2786 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(), 2787 then ASSERT(). 2788 If PcdMaximumLinkedListLength is not zero, and the number of nodes 2789 in List, including the List node, is greater than or equal to 2790 PcdMaximumLinkedListLength, then ASSERT(). 2791 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal 2792 to List, then ASSERT(). 2793 2794 @param List A pointer to the head node of a doubly linked list. 2795 @param Node A pointer to a node in the doubly linked list. 2796 2797 @retval TRUE Node is the head of the doubly-linked list pointed by List. 2798 @retval FALSE Node is not the head of the doubly-linked list pointed by List. 2799 2800 **/ 2801 BOOLEAN 2802 EFIAPI 2803 IsNull ( 2804 IN CONST LIST_ENTRY *List, 2805 IN CONST LIST_ENTRY *Node 2806 ); 2807 2808 /** 2809 Determines if a node the last node in a doubly linked list. 2810 2811 Returns TRUE if Node is the last node in the doubly linked list specified by 2812 List. Otherwise, FALSE is returned. List must have been initialized with 2813 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(). 2814 2815 If List is NULL, then ASSERT(). 2816 If Node is NULL, then ASSERT(). 2817 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or 2818 InitializeListHead(), then ASSERT(). 2819 If PcdMaximumLinkedListLength is not zero, and the number of nodes 2820 in List, including the List node, is greater than or equal to 2821 PcdMaximumLinkedListLength, then ASSERT(). 2822 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT(). 2823 2824 @param List A pointer to the head node of a doubly linked list. 2825 @param Node A pointer to a node in the doubly linked list. 2826 2827 @retval TRUE Node is the last node in the linked list. 2828 @retval FALSE Node is not the last node in the linked list. 2829 2830 **/ 2831 BOOLEAN 2832 EFIAPI 2833 IsNodeAtEnd ( 2834 IN CONST LIST_ENTRY *List, 2835 IN CONST LIST_ENTRY *Node 2836 ); 2837 2838 /** 2839 Swaps the location of two nodes in a doubly linked list, and returns the 2840 first node after the swap. 2841 2842 If FirstEntry is identical to SecondEntry, then SecondEntry is returned. 2843 Otherwise, the location of the FirstEntry node is swapped with the location 2844 of the SecondEntry node in a doubly linked list. SecondEntry must be in the 2845 same double linked list as FirstEntry and that double linked list must have 2846 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(). 2847 SecondEntry is returned after the nodes are swapped. 2848 2849 If FirstEntry is NULL, then ASSERT(). 2850 If SecondEntry is NULL, then ASSERT(). 2851 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the 2852 same linked list, then ASSERT(). 2853 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the 2854 linked list containing the FirstEntry and SecondEntry nodes, including 2855 the FirstEntry and SecondEntry nodes, is greater than or equal to 2856 PcdMaximumLinkedListLength, then ASSERT(). 2857 2858 @param FirstEntry A pointer to a node in a linked list. 2859 @param SecondEntry A pointer to another node in the same linked list. 2860 2861 @return SecondEntry. 2862 2863 **/ 2864 LIST_ENTRY * 2865 EFIAPI 2866 SwapListEntries ( 2867 IN OUT LIST_ENTRY *FirstEntry, 2868 IN OUT LIST_ENTRY *SecondEntry 2869 ); 2870 2871 /** 2872 Removes a node from a doubly linked list, and returns the node that follows 2873 the removed node. 2874 2875 Removes the node Entry from a doubly linked list. It is up to the caller of 2876 this function to release the memory used by this node if that is required. On 2877 exit, the node following Entry in the doubly linked list is returned. If 2878 Entry is the only node in the linked list, then the head node of the linked 2879 list is returned. 2880 2881 If Entry is NULL, then ASSERT(). 2882 If Entry is the head node of an empty list, then ASSERT(). 2883 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the 2884 linked list containing Entry, including the Entry node, is greater than 2885 or equal to PcdMaximumLinkedListLength, then ASSERT(). 2886 2887 @param Entry A pointer to a node in a linked list. 2888 2889 @return Entry. 2890 2891 **/ 2892 LIST_ENTRY * 2893 EFIAPI 2894 RemoveEntryList ( 2895 IN CONST LIST_ENTRY *Entry 2896 ); 2897 2898 // 2899 // Math Services 2900 // 2901 2902 /** 2903 Prototype for comparison function for any two element types. 2904 2905 @param[in] Buffer1 The pointer to first buffer. 2906 @param[in] Buffer2 The pointer to second buffer. 2907 2908 @retval 0 Buffer1 equal to Buffer2. 2909 @return <0 Buffer1 is less than Buffer2. 2910 @return >0 Buffer1 is greater than Buffer2. 2911 **/ 2912 typedef 2913 INTN 2914 (EFIAPI *BASE_SORT_COMPARE)( 2915 IN CONST VOID *Buffer1, 2916 IN CONST VOID *Buffer2 2917 ); 2918 2919 /** 2920 This function is identical to perform QuickSort, 2921 except that is uses the pre-allocated buffer so the in place sorting does not need to 2922 allocate and free buffers constantly. 2923 2924 Each element must be equal sized. 2925 2926 if BufferToSort is NULL, then ASSERT. 2927 if CompareFunction is NULL, then ASSERT. 2928 if BufferOneElement is NULL, then ASSERT. 2929 if ElementSize is < 1, then ASSERT. 2930 2931 if Count is < 2 then perform no action. 2932 2933 @param[in, out] BufferToSort on call a Buffer of (possibly sorted) elements 2934 on return a buffer of sorted elements 2935 @param[in] Count the number of elements in the buffer to sort 2936 @param[in] ElementSize Size of an element in bytes 2937 @param[in] CompareFunction The function to call to perform the comparison 2938 of any 2 elements 2939 @param[out] BufferOneElement Caller provided buffer whose size equals to ElementSize. 2940 It's used by QuickSort() for swapping in sorting. 2941 **/ 2942 VOID 2943 EFIAPI 2944 QuickSort ( 2945 IN OUT VOID *BufferToSort, 2946 IN CONST UINTN Count, 2947 IN CONST UINTN ElementSize, 2948 IN BASE_SORT_COMPARE CompareFunction, 2949 OUT VOID *BufferOneElement 2950 ); 2951 2952 /** 2953 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled 2954 with zeros. The shifted value is returned. 2955 2956 This function shifts the 64-bit value Operand to the left by Count bits. The 2957 low Count bits are set to zero. The shifted value is returned. 2958 2959 If Count is greater than 63, then ASSERT(). 2960 2961 @param Operand The 64-bit operand to shift left. 2962 @param Count The number of bits to shift left. 2963 2964 @return Operand << Count. 2965 2966 **/ 2967 UINT64 2968 EFIAPI 2969 LShiftU64 ( 2970 IN UINT64 Operand, 2971 IN UINTN Count 2972 ); 2973 2974 /** 2975 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are 2976 filled with zeros. The shifted value is returned. 2977 2978 This function shifts the 64-bit value Operand to the right by Count bits. The 2979 high Count bits are set to zero. The shifted value is returned. 2980 2981 If Count is greater than 63, then ASSERT(). 2982 2983 @param Operand The 64-bit operand to shift right. 2984 @param Count The number of bits to shift right. 2985 2986 @return Operand >> Count 2987 2988 **/ 2989 UINT64 2990 EFIAPI 2991 RShiftU64 ( 2992 IN UINT64 Operand, 2993 IN UINTN Count 2994 ); 2995 2996 /** 2997 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled 2998 with original integer's bit 63. The shifted value is returned. 2999 3000 This function shifts the 64-bit value Operand to the right by Count bits. The 3001 high Count bits are set to bit 63 of Operand. The shifted value is returned. 3002 3003 If Count is greater than 63, then ASSERT(). 3004 3005 @param Operand The 64-bit operand to shift right. 3006 @param Count The number of bits to shift right. 3007 3008 @return Operand >> Count 3009 3010 **/ 3011 UINT64 3012 EFIAPI 3013 ARShiftU64 ( 3014 IN UINT64 Operand, 3015 IN UINTN Count 3016 ); 3017 3018 /** 3019 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits 3020 with the high bits that were rotated. 3021 3022 This function rotates the 32-bit value Operand to the left by Count bits. The 3023 low Count bits are fill with the high Count bits of Operand. The rotated 3024 value is returned. 3025 3026 If Count is greater than 31, then ASSERT(). 3027 3028 @param Operand The 32-bit operand to rotate left. 3029 @param Count The number of bits to rotate left. 3030 3031 @return Operand << Count 3032 3033 **/ 3034 UINT32 3035 EFIAPI 3036 LRotU32 ( 3037 IN UINT32 Operand, 3038 IN UINTN Count 3039 ); 3040 3041 /** 3042 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits 3043 with the low bits that were rotated. 3044 3045 This function rotates the 32-bit value Operand to the right by Count bits. 3046 The high Count bits are fill with the low Count bits of Operand. The rotated 3047 value is returned. 3048 3049 If Count is greater than 31, then ASSERT(). 3050 3051 @param Operand The 32-bit operand to rotate right. 3052 @param Count The number of bits to rotate right. 3053 3054 @return Operand >> Count 3055 3056 **/ 3057 UINT32 3058 EFIAPI 3059 RRotU32 ( 3060 IN UINT32 Operand, 3061 IN UINTN Count 3062 ); 3063 3064 /** 3065 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits 3066 with the high bits that were rotated. 3067 3068 This function rotates the 64-bit value Operand to the left by Count bits. The 3069 low Count bits are fill with the high Count bits of Operand. The rotated 3070 value is returned. 3071 3072 If Count is greater than 63, then ASSERT(). 3073 3074 @param Operand The 64-bit operand to rotate left. 3075 @param Count The number of bits to rotate left. 3076 3077 @return Operand << Count 3078 3079 **/ 3080 UINT64 3081 EFIAPI 3082 LRotU64 ( 3083 IN UINT64 Operand, 3084 IN UINTN Count 3085 ); 3086 3087 /** 3088 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits 3089 with the high low bits that were rotated. 3090 3091 This function rotates the 64-bit value Operand to the right by Count bits. 3092 The high Count bits are fill with the low Count bits of Operand. The rotated 3093 value is returned. 3094 3095 If Count is greater than 63, then ASSERT(). 3096 3097 @param Operand The 64-bit operand to rotate right. 3098 @param Count The number of bits to rotate right. 3099 3100 @return Operand >> Count 3101 3102 **/ 3103 UINT64 3104 EFIAPI 3105 RRotU64 ( 3106 IN UINT64 Operand, 3107 IN UINTN Count 3108 ); 3109 3110 /** 3111 Returns the bit position of the lowest bit set in a 32-bit value. 3112 3113 This function computes the bit position of the lowest bit set in the 32-bit 3114 value specified by Operand. If Operand is zero, then -1 is returned. 3115 Otherwise, a value between 0 and 31 is returned. 3116 3117 @param Operand The 32-bit operand to evaluate. 3118 3119 @retval 0..31 The lowest bit set in Operand was found. 3120 @retval -1 Operand is zero. 3121 3122 **/ 3123 INTN 3124 EFIAPI 3125 LowBitSet32 ( 3126 IN UINT32 Operand 3127 ); 3128 3129 /** 3130 Returns the bit position of the lowest bit set in a 64-bit value. 3131 3132 This function computes the bit position of the lowest bit set in the 64-bit 3133 value specified by Operand. If Operand is zero, then -1 is returned. 3134 Otherwise, a value between 0 and 63 is returned. 3135 3136 @param Operand The 64-bit operand to evaluate. 3137 3138 @retval 0..63 The lowest bit set in Operand was found. 3139 @retval -1 Operand is zero. 3140 3141 3142 **/ 3143 INTN 3144 EFIAPI 3145 LowBitSet64 ( 3146 IN UINT64 Operand 3147 ); 3148 3149 /** 3150 Returns the bit position of the highest bit set in a 32-bit value. Equivalent 3151 to log2(x). 3152 3153 This function computes the bit position of the highest bit set in the 32-bit 3154 value specified by Operand. If Operand is zero, then -1 is returned. 3155 Otherwise, a value between 0 and 31 is returned. 3156 3157 @param Operand The 32-bit operand to evaluate. 3158 3159 @retval 0..31 Position of the highest bit set in Operand if found. 3160 @retval -1 Operand is zero. 3161 3162 **/ 3163 INTN 3164 EFIAPI 3165 HighBitSet32 ( 3166 IN UINT32 Operand 3167 ); 3168 3169 /** 3170 Returns the bit position of the highest bit set in a 64-bit value. Equivalent 3171 to log2(x). 3172 3173 This function computes the bit position of the highest bit set in the 64-bit 3174 value specified by Operand. If Operand is zero, then -1 is returned. 3175 Otherwise, a value between 0 and 63 is returned. 3176 3177 @param Operand The 64-bit operand to evaluate. 3178 3179 @retval 0..63 Position of the highest bit set in Operand if found. 3180 @retval -1 Operand is zero. 3181 3182 **/ 3183 INTN 3184 EFIAPI 3185 HighBitSet64 ( 3186 IN UINT64 Operand 3187 ); 3188 3189 /** 3190 Returns the value of the highest bit set in a 32-bit value. Equivalent to 3191 1 << log2(x). 3192 3193 This function computes the value of the highest bit set in the 32-bit value 3194 specified by Operand. If Operand is zero, then zero is returned. 3195 3196 @param Operand The 32-bit operand to evaluate. 3197 3198 @return 1 << HighBitSet32(Operand) 3199 @retval 0 Operand is zero. 3200 3201 **/ 3202 UINT32 3203 EFIAPI 3204 GetPowerOfTwo32 ( 3205 IN UINT32 Operand 3206 ); 3207 3208 /** 3209 Returns the value of the highest bit set in a 64-bit value. Equivalent to 3210 1 << log2(x). 3211 3212 This function computes the value of the highest bit set in the 64-bit value 3213 specified by Operand. If Operand is zero, then zero is returned. 3214 3215 @param Operand The 64-bit operand to evaluate. 3216 3217 @return 1 << HighBitSet64(Operand) 3218 @retval 0 Operand is zero. 3219 3220 **/ 3221 UINT64 3222 EFIAPI 3223 GetPowerOfTwo64 ( 3224 IN UINT64 Operand 3225 ); 3226 3227 /** 3228 Switches the endianness of a 16-bit integer. 3229 3230 This function swaps the bytes in a 16-bit unsigned value to switch the value 3231 from little endian to big endian or vice versa. The byte swapped value is 3232 returned. 3233 3234 @param Value A 16-bit unsigned value. 3235 3236 @return The byte swapped Value. 3237 3238 **/ 3239 UINT16 3240 EFIAPI 3241 SwapBytes16 ( 3242 IN UINT16 Value 3243 ); 3244 3245 /** 3246 Switches the endianness of a 32-bit integer. 3247 3248 This function swaps the bytes in a 32-bit unsigned value to switch the value 3249 from little endian to big endian or vice versa. The byte swapped value is 3250 returned. 3251 3252 @param Value A 32-bit unsigned value. 3253 3254 @return The byte swapped Value. 3255 3256 **/ 3257 UINT32 3258 EFIAPI 3259 SwapBytes32 ( 3260 IN UINT32 Value 3261 ); 3262 3263 /** 3264 Switches the endianness of a 64-bit integer. 3265 3266 This function swaps the bytes in a 64-bit unsigned value to switch the value 3267 from little endian to big endian or vice versa. The byte swapped value is 3268 returned. 3269 3270 @param Value A 64-bit unsigned value. 3271 3272 @return The byte swapped Value. 3273 3274 **/ 3275 UINT64 3276 EFIAPI 3277 SwapBytes64 ( 3278 IN UINT64 Value 3279 ); 3280 3281 /** 3282 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and 3283 generates a 64-bit unsigned result. 3284 3285 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit 3286 unsigned value Multiplier and generates a 64-bit unsigned result. This 64- 3287 bit unsigned result is returned. 3288 3289 @param Multiplicand A 64-bit unsigned value. 3290 @param Multiplier A 32-bit unsigned value. 3291 3292 @return Multiplicand * Multiplier 3293 3294 **/ 3295 UINT64 3296 EFIAPI 3297 MultU64x32 ( 3298 IN UINT64 Multiplicand, 3299 IN UINT32 Multiplier 3300 ); 3301 3302 /** 3303 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and 3304 generates a 64-bit unsigned result. 3305 3306 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit 3307 unsigned value Multiplier and generates a 64-bit unsigned result. This 64- 3308 bit unsigned result is returned. 3309 3310 @param Multiplicand A 64-bit unsigned value. 3311 @param Multiplier A 64-bit unsigned value. 3312 3313 @return Multiplicand * Multiplier. 3314 3315 **/ 3316 UINT64 3317 EFIAPI 3318 MultU64x64 ( 3319 IN UINT64 Multiplicand, 3320 IN UINT64 Multiplier 3321 ); 3322 3323 /** 3324 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a 3325 64-bit signed result. 3326 3327 This function multiples the 64-bit signed value Multiplicand by the 64-bit 3328 signed value Multiplier and generates a 64-bit signed result. This 64-bit 3329 signed result is returned. 3330 3331 @param Multiplicand A 64-bit signed value. 3332 @param Multiplier A 64-bit signed value. 3333 3334 @return Multiplicand * Multiplier 3335 3336 **/ 3337 INT64 3338 EFIAPI 3339 MultS64x64 ( 3340 IN INT64 Multiplicand, 3341 IN INT64 Multiplier 3342 ); 3343 3344 /** 3345 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates 3346 a 64-bit unsigned result. 3347 3348 This function divides the 64-bit unsigned value Dividend by the 32-bit 3349 unsigned value Divisor and generates a 64-bit unsigned quotient. This 3350 function returns the 64-bit unsigned quotient. 3351 3352 If Divisor is 0, then ASSERT(). 3353 3354 @param Dividend A 64-bit unsigned value. 3355 @param Divisor A 32-bit unsigned value. 3356 3357 @return Dividend / Divisor. 3358 3359 **/ 3360 UINT64 3361 EFIAPI 3362 DivU64x32 ( 3363 IN UINT64 Dividend, 3364 IN UINT32 Divisor 3365 ); 3366 3367 /** 3368 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates 3369 a 32-bit unsigned remainder. 3370 3371 This function divides the 64-bit unsigned value Dividend by the 32-bit 3372 unsigned value Divisor and generates a 32-bit remainder. This function 3373 returns the 32-bit unsigned remainder. 3374 3375 If Divisor is 0, then ASSERT(). 3376 3377 @param Dividend A 64-bit unsigned value. 3378 @param Divisor A 32-bit unsigned value. 3379 3380 @return Dividend % Divisor. 3381 3382 **/ 3383 UINT32 3384 EFIAPI 3385 ModU64x32 ( 3386 IN UINT64 Dividend, 3387 IN UINT32 Divisor 3388 ); 3389 3390 /** 3391 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates 3392 a 64-bit unsigned result and an optional 32-bit unsigned remainder. 3393 3394 This function divides the 64-bit unsigned value Dividend by the 32-bit 3395 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder 3396 is not NULL, then the 32-bit unsigned remainder is returned in Remainder. 3397 This function returns the 64-bit unsigned quotient. 3398 3399 If Divisor is 0, then ASSERT(). 3400 3401 @param Dividend A 64-bit unsigned value. 3402 @param Divisor A 32-bit unsigned value. 3403 @param Remainder A pointer to a 32-bit unsigned value. This parameter is 3404 optional and may be NULL. 3405 3406 @return Dividend / Divisor. 3407 3408 **/ 3409 UINT64 3410 EFIAPI 3411 DivU64x32Remainder ( 3412 IN UINT64 Dividend, 3413 IN UINT32 Divisor, 3414 OUT UINT32 *Remainder OPTIONAL 3415 ); 3416 3417 /** 3418 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates 3419 a 64-bit unsigned result and an optional 64-bit unsigned remainder. 3420 3421 This function divides the 64-bit unsigned value Dividend by the 64-bit 3422 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder 3423 is not NULL, then the 64-bit unsigned remainder is returned in Remainder. 3424 This function returns the 64-bit unsigned quotient. 3425 3426 If Divisor is 0, then ASSERT(). 3427 3428 @param Dividend A 64-bit unsigned value. 3429 @param Divisor A 64-bit unsigned value. 3430 @param Remainder A pointer to a 64-bit unsigned value. This parameter is 3431 optional and may be NULL. 3432 3433 @return Dividend / Divisor. 3434 3435 **/ 3436 UINT64 3437 EFIAPI 3438 DivU64x64Remainder ( 3439 IN UINT64 Dividend, 3440 IN UINT64 Divisor, 3441 OUT UINT64 *Remainder OPTIONAL 3442 ); 3443 3444 /** 3445 Divides a 64-bit signed integer by a 64-bit signed integer and generates a 3446 64-bit signed result and a optional 64-bit signed remainder. 3447 3448 This function divides the 64-bit signed value Dividend by the 64-bit signed 3449 value Divisor and generates a 64-bit signed quotient. If Remainder is not 3450 NULL, then the 64-bit signed remainder is returned in Remainder. This 3451 function returns the 64-bit signed quotient. 3452 3453 It is the caller's responsibility to not call this function with a Divisor of 0. 3454 If Divisor is 0, then the quotient and remainder should be assumed to be 3455 the largest negative integer. 3456 3457 If Divisor is 0, then ASSERT(). 3458 3459 @param Dividend A 64-bit signed value. 3460 @param Divisor A 64-bit signed value. 3461 @param Remainder A pointer to a 64-bit signed value. This parameter is 3462 optional and may be NULL. 3463 3464 @return Dividend / Divisor. 3465 3466 **/ 3467 INT64 3468 EFIAPI 3469 DivS64x64Remainder ( 3470 IN INT64 Dividend, 3471 IN INT64 Divisor, 3472 OUT INT64 *Remainder OPTIONAL 3473 ); 3474 3475 /** 3476 Reads a 16-bit value from memory that may be unaligned. 3477 3478 This function returns the 16-bit value pointed to by Buffer. The function 3479 guarantees that the read operation does not produce an alignment fault. 3480 3481 If the Buffer is NULL, then ASSERT(). 3482 3483 @param Buffer The pointer to a 16-bit value that may be unaligned. 3484 3485 @return The 16-bit value read from Buffer. 3486 3487 **/ 3488 UINT16 3489 EFIAPI 3490 ReadUnaligned16 ( 3491 IN CONST UINT16 *Buffer 3492 ); 3493 3494 /** 3495 Writes a 16-bit value to memory that may be unaligned. 3496 3497 This function writes the 16-bit value specified by Value to Buffer. Value is 3498 returned. The function guarantees that the write operation does not produce 3499 an alignment fault. 3500 3501 If the Buffer is NULL, then ASSERT(). 3502 3503 @param Buffer The pointer to a 16-bit value that may be unaligned. 3504 @param Value 16-bit value to write to Buffer. 3505 3506 @return The 16-bit value to write to Buffer. 3507 3508 **/ 3509 UINT16 3510 EFIAPI 3511 WriteUnaligned16 ( 3512 OUT UINT16 *Buffer, 3513 IN UINT16 Value 3514 ); 3515 3516 /** 3517 Reads a 24-bit value from memory that may be unaligned. 3518 3519 This function returns the 24-bit value pointed to by Buffer. The function 3520 guarantees that the read operation does not produce an alignment fault. 3521 3522 If the Buffer is NULL, then ASSERT(). 3523 3524 @param Buffer The pointer to a 24-bit value that may be unaligned. 3525 3526 @return The 24-bit value read from Buffer. 3527 3528 **/ 3529 UINT32 3530 EFIAPI 3531 ReadUnaligned24 ( 3532 IN CONST UINT32 *Buffer 3533 ); 3534 3535 /** 3536 Writes a 24-bit value to memory that may be unaligned. 3537 3538 This function writes the 24-bit value specified by Value to Buffer. Value is 3539 returned. The function guarantees that the write operation does not produce 3540 an alignment fault. 3541 3542 If the Buffer is NULL, then ASSERT(). 3543 3544 @param Buffer The pointer to a 24-bit value that may be unaligned. 3545 @param Value 24-bit value to write to Buffer. 3546 3547 @return The 24-bit value to write to Buffer. 3548 3549 **/ 3550 UINT32 3551 EFIAPI 3552 WriteUnaligned24 ( 3553 OUT UINT32 *Buffer, 3554 IN UINT32 Value 3555 ); 3556 3557 /** 3558 Reads a 32-bit value from memory that may be unaligned. 3559 3560 This function returns the 32-bit value pointed to by Buffer. The function 3561 guarantees that the read operation does not produce an alignment fault. 3562 3563 If the Buffer is NULL, then ASSERT(). 3564 3565 @param Buffer The pointer to a 32-bit value that may be unaligned. 3566 3567 @return The 32-bit value read from Buffer. 3568 3569 **/ 3570 UINT32 3571 EFIAPI 3572 ReadUnaligned32 ( 3573 IN CONST UINT32 *Buffer 3574 ); 3575 3576 /** 3577 Writes a 32-bit value to memory that may be unaligned. 3578 3579 This function writes the 32-bit value specified by Value to Buffer. Value is 3580 returned. The function guarantees that the write operation does not produce 3581 an alignment fault. 3582 3583 If the Buffer is NULL, then ASSERT(). 3584 3585 @param Buffer The pointer to a 32-bit value that may be unaligned. 3586 @param Value 32-bit value to write to Buffer. 3587 3588 @return The 32-bit value to write to Buffer. 3589 3590 **/ 3591 UINT32 3592 EFIAPI 3593 WriteUnaligned32 ( 3594 OUT UINT32 *Buffer, 3595 IN UINT32 Value 3596 ); 3597 3598 /** 3599 Reads a 64-bit value from memory that may be unaligned. 3600 3601 This function returns the 64-bit value pointed to by Buffer. The function 3602 guarantees that the read operation does not produce an alignment fault. 3603 3604 If the Buffer is NULL, then ASSERT(). 3605 3606 @param Buffer The pointer to a 64-bit value that may be unaligned. 3607 3608 @return The 64-bit value read from Buffer. 3609 3610 **/ 3611 UINT64 3612 EFIAPI 3613 ReadUnaligned64 ( 3614 IN CONST UINT64 *Buffer 3615 ); 3616 3617 /** 3618 Writes a 64-bit value to memory that may be unaligned. 3619 3620 This function writes the 64-bit value specified by Value to Buffer. Value is 3621 returned. The function guarantees that the write operation does not produce 3622 an alignment fault. 3623 3624 If the Buffer is NULL, then ASSERT(). 3625 3626 @param Buffer The pointer to a 64-bit value that may be unaligned. 3627 @param Value 64-bit value to write to Buffer. 3628 3629 @return The 64-bit value to write to Buffer. 3630 3631 **/ 3632 UINT64 3633 EFIAPI 3634 WriteUnaligned64 ( 3635 OUT UINT64 *Buffer, 3636 IN UINT64 Value 3637 ); 3638 3639 // 3640 // Bit Field Functions 3641 // 3642 3643 /** 3644 Returns a bit field from an 8-bit value. 3645 3646 Returns the bitfield specified by the StartBit and the EndBit from Operand. 3647 3648 If 8-bit operations are not supported, then ASSERT(). 3649 If StartBit is greater than 7, then ASSERT(). 3650 If EndBit is greater than 7, then ASSERT(). 3651 If EndBit is less than StartBit, then ASSERT(). 3652 3653 @param Operand Operand on which to perform the bitfield operation. 3654 @param StartBit The ordinal of the least significant bit in the bit field. 3655 Range 0..7. 3656 @param EndBit The ordinal of the most significant bit in the bit field. 3657 Range 0..7. 3658 3659 @return The bit field read. 3660 3661 **/ 3662 UINT8 3663 EFIAPI 3664 BitFieldRead8 ( 3665 IN UINT8 Operand, 3666 IN UINTN StartBit, 3667 IN UINTN EndBit 3668 ); 3669 3670 /** 3671 Writes a bit field to an 8-bit value, and returns the result. 3672 3673 Writes Value to the bit field specified by the StartBit and the EndBit in 3674 Operand. All other bits in Operand are preserved. The new 8-bit value is 3675 returned. 3676 3677 If 8-bit operations are not supported, then ASSERT(). 3678 If StartBit is greater than 7, then ASSERT(). 3679 If EndBit is greater than 7, then ASSERT(). 3680 If EndBit is less than StartBit, then ASSERT(). 3681 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 3682 3683 @param Operand Operand on which to perform the bitfield operation. 3684 @param StartBit The ordinal of the least significant bit in the bit field. 3685 Range 0..7. 3686 @param EndBit The ordinal of the most significant bit in the bit field. 3687 Range 0..7. 3688 @param Value New value of the bit field. 3689 3690 @return The new 8-bit value. 3691 3692 **/ 3693 UINT8 3694 EFIAPI 3695 BitFieldWrite8 ( 3696 IN UINT8 Operand, 3697 IN UINTN StartBit, 3698 IN UINTN EndBit, 3699 IN UINT8 Value 3700 ); 3701 3702 /** 3703 Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the 3704 result. 3705 3706 Performs a bitwise OR between the bit field specified by StartBit 3707 and EndBit in Operand and the value specified by OrData. All other bits in 3708 Operand are preserved. The new 8-bit value is returned. 3709 3710 If 8-bit operations are not supported, then ASSERT(). 3711 If StartBit is greater than 7, then ASSERT(). 3712 If EndBit is greater than 7, then ASSERT(). 3713 If EndBit is less than StartBit, then ASSERT(). 3714 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 3715 3716 @param Operand Operand on which to perform the bitfield operation. 3717 @param StartBit The ordinal of the least significant bit in the bit field. 3718 Range 0..7. 3719 @param EndBit The ordinal of the most significant bit in the bit field. 3720 Range 0..7. 3721 @param OrData The value to OR with the read value from the value 3722 3723 @return The new 8-bit value. 3724 3725 **/ 3726 UINT8 3727 EFIAPI 3728 BitFieldOr8 ( 3729 IN UINT8 Operand, 3730 IN UINTN StartBit, 3731 IN UINTN EndBit, 3732 IN UINT8 OrData 3733 ); 3734 3735 /** 3736 Reads a bit field from an 8-bit value, performs a bitwise AND, and returns 3737 the result. 3738 3739 Performs a bitwise AND between the bit field specified by StartBit and EndBit 3740 in Operand and the value specified by AndData. All other bits in Operand are 3741 preserved. The new 8-bit value is returned. 3742 3743 If 8-bit operations are not supported, then ASSERT(). 3744 If StartBit is greater than 7, then ASSERT(). 3745 If EndBit is greater than 7, then ASSERT(). 3746 If EndBit is less than StartBit, then ASSERT(). 3747 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 3748 3749 @param Operand Operand on which to perform the bitfield operation. 3750 @param StartBit The ordinal of the least significant bit in the bit field. 3751 Range 0..7. 3752 @param EndBit The ordinal of the most significant bit in the bit field. 3753 Range 0..7. 3754 @param AndData The value to AND with the read value from the value. 3755 3756 @return The new 8-bit value. 3757 3758 **/ 3759 UINT8 3760 EFIAPI 3761 BitFieldAnd8 ( 3762 IN UINT8 Operand, 3763 IN UINTN StartBit, 3764 IN UINTN EndBit, 3765 IN UINT8 AndData 3766 ); 3767 3768 /** 3769 Reads a bit field from an 8-bit value, performs a bitwise AND followed by a 3770 bitwise OR, and returns the result. 3771 3772 Performs a bitwise AND between the bit field specified by StartBit and EndBit 3773 in Operand and the value specified by AndData, followed by a bitwise 3774 OR with value specified by OrData. All other bits in Operand are 3775 preserved. The new 8-bit value is returned. 3776 3777 If 8-bit operations are not supported, then ASSERT(). 3778 If StartBit is greater than 7, then ASSERT(). 3779 If EndBit is greater than 7, then ASSERT(). 3780 If EndBit is less than StartBit, then ASSERT(). 3781 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 3782 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 3783 3784 @param Operand Operand on which to perform the bitfield operation. 3785 @param StartBit The ordinal of the least significant bit in the bit field. 3786 Range 0..7. 3787 @param EndBit The ordinal of the most significant bit in the bit field. 3788 Range 0..7. 3789 @param AndData The value to AND with the read value from the value. 3790 @param OrData The value to OR with the result of the AND operation. 3791 3792 @return The new 8-bit value. 3793 3794 **/ 3795 UINT8 3796 EFIAPI 3797 BitFieldAndThenOr8 ( 3798 IN UINT8 Operand, 3799 IN UINTN StartBit, 3800 IN UINTN EndBit, 3801 IN UINT8 AndData, 3802 IN UINT8 OrData 3803 ); 3804 3805 /** 3806 Returns a bit field from a 16-bit value. 3807 3808 Returns the bitfield specified by the StartBit and the EndBit from Operand. 3809 3810 If 16-bit operations are not supported, then ASSERT(). 3811 If StartBit is greater than 15, then ASSERT(). 3812 If EndBit is greater than 15, then ASSERT(). 3813 If EndBit is less than StartBit, then ASSERT(). 3814 3815 @param Operand Operand on which to perform the bitfield operation. 3816 @param StartBit The ordinal of the least significant bit in the bit field. 3817 Range 0..15. 3818 @param EndBit The ordinal of the most significant bit in the bit field. 3819 Range 0..15. 3820 3821 @return The bit field read. 3822 3823 **/ 3824 UINT16 3825 EFIAPI 3826 BitFieldRead16 ( 3827 IN UINT16 Operand, 3828 IN UINTN StartBit, 3829 IN UINTN EndBit 3830 ); 3831 3832 /** 3833 Writes a bit field to a 16-bit value, and returns the result. 3834 3835 Writes Value to the bit field specified by the StartBit and the EndBit in 3836 Operand. All other bits in Operand are preserved. The new 16-bit value is 3837 returned. 3838 3839 If 16-bit operations are not supported, then ASSERT(). 3840 If StartBit is greater than 15, then ASSERT(). 3841 If EndBit is greater than 15, then ASSERT(). 3842 If EndBit is less than StartBit, then ASSERT(). 3843 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 3844 3845 @param Operand Operand on which to perform the bitfield operation. 3846 @param StartBit The ordinal of the least significant bit in the bit field. 3847 Range 0..15. 3848 @param EndBit The ordinal of the most significant bit in the bit field. 3849 Range 0..15. 3850 @param Value New value of the bit field. 3851 3852 @return The new 16-bit value. 3853 3854 **/ 3855 UINT16 3856 EFIAPI 3857 BitFieldWrite16 ( 3858 IN UINT16 Operand, 3859 IN UINTN StartBit, 3860 IN UINTN EndBit, 3861 IN UINT16 Value 3862 ); 3863 3864 /** 3865 Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the 3866 result. 3867 3868 Performs a bitwise OR between the bit field specified by StartBit 3869 and EndBit in Operand and the value specified by OrData. All other bits in 3870 Operand are preserved. The new 16-bit value is returned. 3871 3872 If 16-bit operations are not supported, then ASSERT(). 3873 If StartBit is greater than 15, then ASSERT(). 3874 If EndBit is greater than 15, then ASSERT(). 3875 If EndBit is less than StartBit, then ASSERT(). 3876 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 3877 3878 @param Operand Operand on which to perform the bitfield operation. 3879 @param StartBit The ordinal of the least significant bit in the bit field. 3880 Range 0..15. 3881 @param EndBit The ordinal of the most significant bit in the bit field. 3882 Range 0..15. 3883 @param OrData The value to OR with the read value from the value 3884 3885 @return The new 16-bit value. 3886 3887 **/ 3888 UINT16 3889 EFIAPI 3890 BitFieldOr16 ( 3891 IN UINT16 Operand, 3892 IN UINTN StartBit, 3893 IN UINTN EndBit, 3894 IN UINT16 OrData 3895 ); 3896 3897 /** 3898 Reads a bit field from a 16-bit value, performs a bitwise AND, and returns 3899 the result. 3900 3901 Performs a bitwise AND between the bit field specified by StartBit and EndBit 3902 in Operand and the value specified by AndData. All other bits in Operand are 3903 preserved. The new 16-bit value is returned. 3904 3905 If 16-bit operations are not supported, then ASSERT(). 3906 If StartBit is greater than 15, then ASSERT(). 3907 If EndBit is greater than 15, then ASSERT(). 3908 If EndBit is less than StartBit, then ASSERT(). 3909 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 3910 3911 @param Operand Operand on which to perform the bitfield operation. 3912 @param StartBit The ordinal of the least significant bit in the bit field. 3913 Range 0..15. 3914 @param EndBit The ordinal of the most significant bit in the bit field. 3915 Range 0..15. 3916 @param AndData The value to AND with the read value from the value 3917 3918 @return The new 16-bit value. 3919 3920 **/ 3921 UINT16 3922 EFIAPI 3923 BitFieldAnd16 ( 3924 IN UINT16 Operand, 3925 IN UINTN StartBit, 3926 IN UINTN EndBit, 3927 IN UINT16 AndData 3928 ); 3929 3930 /** 3931 Reads a bit field from a 16-bit value, performs a bitwise AND followed by a 3932 bitwise OR, and returns the result. 3933 3934 Performs a bitwise AND between the bit field specified by StartBit and EndBit 3935 in Operand and the value specified by AndData, followed by a bitwise 3936 OR with value specified by OrData. All other bits in Operand are 3937 preserved. The new 16-bit value is returned. 3938 3939 If 16-bit operations are not supported, then ASSERT(). 3940 If StartBit is greater than 15, then ASSERT(). 3941 If EndBit is greater than 15, then ASSERT(). 3942 If EndBit is less than StartBit, then ASSERT(). 3943 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 3944 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 3945 3946 @param Operand Operand on which to perform the bitfield operation. 3947 @param StartBit The ordinal of the least significant bit in the bit field. 3948 Range 0..15. 3949 @param EndBit The ordinal of the most significant bit in the bit field. 3950 Range 0..15. 3951 @param AndData The value to AND with the read value from the value. 3952 @param OrData The value to OR with the result of the AND operation. 3953 3954 @return The new 16-bit value. 3955 3956 **/ 3957 UINT16 3958 EFIAPI 3959 BitFieldAndThenOr16 ( 3960 IN UINT16 Operand, 3961 IN UINTN StartBit, 3962 IN UINTN EndBit, 3963 IN UINT16 AndData, 3964 IN UINT16 OrData 3965 ); 3966 3967 /** 3968 Returns a bit field from a 32-bit value. 3969 3970 Returns the bitfield specified by the StartBit and the EndBit from Operand. 3971 3972 If 32-bit operations are not supported, then ASSERT(). 3973 If StartBit is greater than 31, then ASSERT(). 3974 If EndBit is greater than 31, then ASSERT(). 3975 If EndBit is less than StartBit, then ASSERT(). 3976 3977 @param Operand Operand on which to perform the bitfield operation. 3978 @param StartBit The ordinal of the least significant bit in the bit field. 3979 Range 0..31. 3980 @param EndBit The ordinal of the most significant bit in the bit field. 3981 Range 0..31. 3982 3983 @return The bit field read. 3984 3985 **/ 3986 UINT32 3987 EFIAPI 3988 BitFieldRead32 ( 3989 IN UINT32 Operand, 3990 IN UINTN StartBit, 3991 IN UINTN EndBit 3992 ); 3993 3994 /** 3995 Writes a bit field to a 32-bit value, and returns the result. 3996 3997 Writes Value to the bit field specified by the StartBit and the EndBit in 3998 Operand. All other bits in Operand are preserved. The new 32-bit value is 3999 returned. 4000 4001 If 32-bit operations are not supported, then ASSERT(). 4002 If StartBit is greater than 31, then ASSERT(). 4003 If EndBit is greater than 31, then ASSERT(). 4004 If EndBit is less than StartBit, then ASSERT(). 4005 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 4006 4007 @param Operand Operand on which to perform the bitfield operation. 4008 @param StartBit The ordinal of the least significant bit in the bit field. 4009 Range 0..31. 4010 @param EndBit The ordinal of the most significant bit in the bit field. 4011 Range 0..31. 4012 @param Value New value of the bit field. 4013 4014 @return The new 32-bit value. 4015 4016 **/ 4017 UINT32 4018 EFIAPI 4019 BitFieldWrite32 ( 4020 IN UINT32 Operand, 4021 IN UINTN StartBit, 4022 IN UINTN EndBit, 4023 IN UINT32 Value 4024 ); 4025 4026 /** 4027 Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the 4028 result. 4029 4030 Performs a bitwise OR between the bit field specified by StartBit 4031 and EndBit in Operand and the value specified by OrData. All other bits in 4032 Operand are preserved. The new 32-bit value is returned. 4033 4034 If 32-bit operations are not supported, then ASSERT(). 4035 If StartBit is greater than 31, then ASSERT(). 4036 If EndBit is greater than 31, then ASSERT(). 4037 If EndBit is less than StartBit, then ASSERT(). 4038 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 4039 4040 @param Operand Operand on which to perform the bitfield operation. 4041 @param StartBit The ordinal of the least significant bit in the bit field. 4042 Range 0..31. 4043 @param EndBit The ordinal of the most significant bit in the bit field. 4044 Range 0..31. 4045 @param OrData The value to OR with the read value from the value. 4046 4047 @return The new 32-bit value. 4048 4049 **/ 4050 UINT32 4051 EFIAPI 4052 BitFieldOr32 ( 4053 IN UINT32 Operand, 4054 IN UINTN StartBit, 4055 IN UINTN EndBit, 4056 IN UINT32 OrData 4057 ); 4058 4059 /** 4060 Reads a bit field from a 32-bit value, performs a bitwise AND, and returns 4061 the result. 4062 4063 Performs a bitwise AND between the bit field specified by StartBit and EndBit 4064 in Operand and the value specified by AndData. All other bits in Operand are 4065 preserved. The new 32-bit value is returned. 4066 4067 If 32-bit operations are not supported, then ASSERT(). 4068 If StartBit is greater than 31, then ASSERT(). 4069 If EndBit is greater than 31, then ASSERT(). 4070 If EndBit is less than StartBit, then ASSERT(). 4071 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 4072 4073 @param Operand Operand on which to perform the bitfield operation. 4074 @param StartBit The ordinal of the least significant bit in the bit field. 4075 Range 0..31. 4076 @param EndBit The ordinal of the most significant bit in the bit field. 4077 Range 0..31. 4078 @param AndData The value to AND with the read value from the value 4079 4080 @return The new 32-bit value. 4081 4082 **/ 4083 UINT32 4084 EFIAPI 4085 BitFieldAnd32 ( 4086 IN UINT32 Operand, 4087 IN UINTN StartBit, 4088 IN UINTN EndBit, 4089 IN UINT32 AndData 4090 ); 4091 4092 /** 4093 Reads a bit field from a 32-bit value, performs a bitwise AND followed by a 4094 bitwise OR, and returns the result. 4095 4096 Performs a bitwise AND between the bit field specified by StartBit and EndBit 4097 in Operand and the value specified by AndData, followed by a bitwise 4098 OR with value specified by OrData. All other bits in Operand are 4099 preserved. The new 32-bit value is returned. 4100 4101 If 32-bit operations are not supported, then ASSERT(). 4102 If StartBit is greater than 31, then ASSERT(). 4103 If EndBit is greater than 31, then ASSERT(). 4104 If EndBit is less than StartBit, then ASSERT(). 4105 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 4106 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 4107 4108 @param Operand Operand on which to perform the bitfield operation. 4109 @param StartBit The ordinal of the least significant bit in the bit field. 4110 Range 0..31. 4111 @param EndBit The ordinal of the most significant bit in the bit field. 4112 Range 0..31. 4113 @param AndData The value to AND with the read value from the value. 4114 @param OrData The value to OR with the result of the AND operation. 4115 4116 @return The new 32-bit value. 4117 4118 **/ 4119 UINT32 4120 EFIAPI 4121 BitFieldAndThenOr32 ( 4122 IN UINT32 Operand, 4123 IN UINTN StartBit, 4124 IN UINTN EndBit, 4125 IN UINT32 AndData, 4126 IN UINT32 OrData 4127 ); 4128 4129 /** 4130 Returns a bit field from a 64-bit value. 4131 4132 Returns the bitfield specified by the StartBit and the EndBit from Operand. 4133 4134 If 64-bit operations are not supported, then ASSERT(). 4135 If StartBit is greater than 63, then ASSERT(). 4136 If EndBit is greater than 63, then ASSERT(). 4137 If EndBit is less than StartBit, then ASSERT(). 4138 4139 @param Operand Operand on which to perform the bitfield operation. 4140 @param StartBit The ordinal of the least significant bit in the bit field. 4141 Range 0..63. 4142 @param EndBit The ordinal of the most significant bit in the bit field. 4143 Range 0..63. 4144 4145 @return The bit field read. 4146 4147 **/ 4148 UINT64 4149 EFIAPI 4150 BitFieldRead64 ( 4151 IN UINT64 Operand, 4152 IN UINTN StartBit, 4153 IN UINTN EndBit 4154 ); 4155 4156 /** 4157 Writes a bit field to a 64-bit value, and returns the result. 4158 4159 Writes Value to the bit field specified by the StartBit and the EndBit in 4160 Operand. All other bits in Operand are preserved. The new 64-bit value is 4161 returned. 4162 4163 If 64-bit operations are not supported, then ASSERT(). 4164 If StartBit is greater than 63, then ASSERT(). 4165 If EndBit is greater than 63, then ASSERT(). 4166 If EndBit is less than StartBit, then ASSERT(). 4167 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 4168 4169 @param Operand Operand on which to perform the bitfield operation. 4170 @param StartBit The ordinal of the least significant bit in the bit field. 4171 Range 0..63. 4172 @param EndBit The ordinal of the most significant bit in the bit field. 4173 Range 0..63. 4174 @param Value New value of the bit field. 4175 4176 @return The new 64-bit value. 4177 4178 **/ 4179 UINT64 4180 EFIAPI 4181 BitFieldWrite64 ( 4182 IN UINT64 Operand, 4183 IN UINTN StartBit, 4184 IN UINTN EndBit, 4185 IN UINT64 Value 4186 ); 4187 4188 /** 4189 Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the 4190 result. 4191 4192 Performs a bitwise OR between the bit field specified by StartBit 4193 and EndBit in Operand and the value specified by OrData. All other bits in 4194 Operand are preserved. The new 64-bit value is returned. 4195 4196 If 64-bit operations are not supported, then ASSERT(). 4197 If StartBit is greater than 63, then ASSERT(). 4198 If EndBit is greater than 63, then ASSERT(). 4199 If EndBit is less than StartBit, then ASSERT(). 4200 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 4201 4202 @param Operand Operand on which to perform the bitfield operation. 4203 @param StartBit The ordinal of the least significant bit in the bit field. 4204 Range 0..63. 4205 @param EndBit The ordinal of the most significant bit in the bit field. 4206 Range 0..63. 4207 @param OrData The value to OR with the read value from the value 4208 4209 @return The new 64-bit value. 4210 4211 **/ 4212 UINT64 4213 EFIAPI 4214 BitFieldOr64 ( 4215 IN UINT64 Operand, 4216 IN UINTN StartBit, 4217 IN UINTN EndBit, 4218 IN UINT64 OrData 4219 ); 4220 4221 /** 4222 Reads a bit field from a 64-bit value, performs a bitwise AND, and returns 4223 the result. 4224 4225 Performs a bitwise AND between the bit field specified by StartBit and EndBit 4226 in Operand and the value specified by AndData. All other bits in Operand are 4227 preserved. The new 64-bit value is returned. 4228 4229 If 64-bit operations are not supported, then ASSERT(). 4230 If StartBit is greater than 63, then ASSERT(). 4231 If EndBit is greater than 63, then ASSERT(). 4232 If EndBit is less than StartBit, then ASSERT(). 4233 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 4234 4235 @param Operand Operand on which to perform the bitfield operation. 4236 @param StartBit The ordinal of the least significant bit in the bit field. 4237 Range 0..63. 4238 @param EndBit The ordinal of the most significant bit in the bit field. 4239 Range 0..63. 4240 @param AndData The value to AND with the read value from the value 4241 4242 @return The new 64-bit value. 4243 4244 **/ 4245 UINT64 4246 EFIAPI 4247 BitFieldAnd64 ( 4248 IN UINT64 Operand, 4249 IN UINTN StartBit, 4250 IN UINTN EndBit, 4251 IN UINT64 AndData 4252 ); 4253 4254 /** 4255 Reads a bit field from a 64-bit value, performs a bitwise AND followed by a 4256 bitwise OR, and returns the result. 4257 4258 Performs a bitwise AND between the bit field specified by StartBit and EndBit 4259 in Operand and the value specified by AndData, followed by a bitwise 4260 OR with value specified by OrData. All other bits in Operand are 4261 preserved. The new 64-bit value is returned. 4262 4263 If 64-bit operations are not supported, then ASSERT(). 4264 If StartBit is greater than 63, then ASSERT(). 4265 If EndBit is greater than 63, then ASSERT(). 4266 If EndBit is less than StartBit, then ASSERT(). 4267 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 4268 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 4269 4270 @param Operand Operand on which to perform the bitfield operation. 4271 @param StartBit The ordinal of the least significant bit in the bit field. 4272 Range 0..63. 4273 @param EndBit The ordinal of the most significant bit in the bit field. 4274 Range 0..63. 4275 @param AndData The value to AND with the read value from the value. 4276 @param OrData The value to OR with the result of the AND operation. 4277 4278 @return The new 64-bit value. 4279 4280 **/ 4281 UINT64 4282 EFIAPI 4283 BitFieldAndThenOr64 ( 4284 IN UINT64 Operand, 4285 IN UINTN StartBit, 4286 IN UINTN EndBit, 4287 IN UINT64 AndData, 4288 IN UINT64 OrData 4289 ); 4290 4291 /** 4292 Reads a bit field from a 32-bit value, counts and returns 4293 the number of set bits. 4294 4295 Counts the number of set bits in the bit field specified by 4296 StartBit and EndBit in Operand. The count is returned. 4297 4298 If StartBit is greater than 31, then ASSERT(). 4299 If EndBit is greater than 31, then ASSERT(). 4300 If EndBit is less than StartBit, then ASSERT(). 4301 4302 @param Operand Operand on which to perform the bitfield operation. 4303 @param StartBit The ordinal of the least significant bit in the bit field. 4304 Range 0..31. 4305 @param EndBit The ordinal of the most significant bit in the bit field. 4306 Range 0..31. 4307 4308 @return The number of bits set between StartBit and EndBit. 4309 4310 **/ 4311 UINT8 4312 EFIAPI 4313 BitFieldCountOnes32 ( 4314 IN UINT32 Operand, 4315 IN UINTN StartBit, 4316 IN UINTN EndBit 4317 ); 4318 4319 /** 4320 Reads a bit field from a 64-bit value, counts and returns 4321 the number of set bits. 4322 4323 Counts the number of set bits in the bit field specified by 4324 StartBit and EndBit in Operand. The count is returned. 4325 4326 If StartBit is greater than 63, then ASSERT(). 4327 If EndBit is greater than 63, then ASSERT(). 4328 If EndBit is less than StartBit, then ASSERT(). 4329 4330 @param Operand Operand on which to perform the bitfield operation. 4331 @param StartBit The ordinal of the least significant bit in the bit field. 4332 Range 0..63. 4333 @param EndBit The ordinal of the most significant bit in the bit field. 4334 Range 0..63. 4335 4336 @return The number of bits set between StartBit and EndBit. 4337 4338 **/ 4339 UINT8 4340 EFIAPI 4341 BitFieldCountOnes64 ( 4342 IN UINT64 Operand, 4343 IN UINTN StartBit, 4344 IN UINTN EndBit 4345 ); 4346 4347 // 4348 // Base Library Checksum Functions 4349 // 4350 4351 /** 4352 Returns the sum of all elements in a buffer in unit of UINT8. 4353 During calculation, the carry bits are dropped. 4354 4355 This function calculates the sum of all elements in a buffer 4356 in unit of UINT8. The carry bits in result of addition are dropped. 4357 The result is returned as UINT8. If Length is Zero, then Zero is 4358 returned. 4359 4360 If Buffer is NULL, then ASSERT(). 4361 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 4362 4363 @param Buffer The pointer to the buffer to carry out the sum operation. 4364 @param Length The size, in bytes, of Buffer. 4365 4366 @return Sum The sum of Buffer with carry bits dropped during additions. 4367 4368 **/ 4369 UINT8 4370 EFIAPI 4371 CalculateSum8 ( 4372 IN CONST UINT8 *Buffer, 4373 IN UINTN Length 4374 ); 4375 4376 /** 4377 Returns the two's complement checksum of all elements in a buffer 4378 of 8-bit values. 4379 4380 This function first calculates the sum of the 8-bit values in the 4381 buffer specified by Buffer and Length. The carry bits in the result 4382 of addition are dropped. Then, the two's complement of the sum is 4383 returned. If Length is 0, then 0 is returned. 4384 4385 If Buffer is NULL, then ASSERT(). 4386 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 4387 4388 @param Buffer The pointer to the buffer to carry out the checksum operation. 4389 @param Length The size, in bytes, of Buffer. 4390 4391 @return Checksum The two's complement checksum of Buffer. 4392 4393 **/ 4394 UINT8 4395 EFIAPI 4396 CalculateCheckSum8 ( 4397 IN CONST UINT8 *Buffer, 4398 IN UINTN Length 4399 ); 4400 4401 /** 4402 Returns the sum of all elements in a buffer of 16-bit values. During 4403 calculation, the carry bits are dropped. 4404 4405 This function calculates the sum of the 16-bit values in the buffer 4406 specified by Buffer and Length. The carry bits in result of addition are dropped. 4407 The 16-bit result is returned. If Length is 0, then 0 is returned. 4408 4409 If Buffer is NULL, then ASSERT(). 4410 If Buffer is not aligned on a 16-bit boundary, then ASSERT(). 4411 If Length is not aligned on a 16-bit boundary, then ASSERT(). 4412 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 4413 4414 @param Buffer The pointer to the buffer to carry out the sum operation. 4415 @param Length The size, in bytes, of Buffer. 4416 4417 @return Sum The sum of Buffer with carry bits dropped during additions. 4418 4419 **/ 4420 UINT16 4421 EFIAPI 4422 CalculateSum16 ( 4423 IN CONST UINT16 *Buffer, 4424 IN UINTN Length 4425 ); 4426 4427 /** 4428 Returns the two's complement checksum of all elements in a buffer of 4429 16-bit values. 4430 4431 This function first calculates the sum of the 16-bit values in the buffer 4432 specified by Buffer and Length. The carry bits in the result of addition 4433 are dropped. Then, the two's complement of the sum is returned. If Length 4434 is 0, then 0 is returned. 4435 4436 If Buffer is NULL, then ASSERT(). 4437 If Buffer is not aligned on a 16-bit boundary, then ASSERT(). 4438 If Length is not aligned on a 16-bit boundary, then ASSERT(). 4439 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 4440 4441 @param Buffer The pointer to the buffer to carry out the checksum operation. 4442 @param Length The size, in bytes, of Buffer. 4443 4444 @return Checksum The two's complement checksum of Buffer. 4445 4446 **/ 4447 UINT16 4448 EFIAPI 4449 CalculateCheckSum16 ( 4450 IN CONST UINT16 *Buffer, 4451 IN UINTN Length 4452 ); 4453 4454 /** 4455 Returns the sum of all elements in a buffer of 32-bit values. During 4456 calculation, the carry bits are dropped. 4457 4458 This function calculates the sum of the 32-bit values in the buffer 4459 specified by Buffer and Length. The carry bits in result of addition are dropped. 4460 The 32-bit result is returned. If Length is 0, then 0 is returned. 4461 4462 If Buffer is NULL, then ASSERT(). 4463 If Buffer is not aligned on a 32-bit boundary, then ASSERT(). 4464 If Length is not aligned on a 32-bit boundary, then ASSERT(). 4465 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 4466 4467 @param Buffer The pointer to the buffer to carry out the sum operation. 4468 @param Length The size, in bytes, of Buffer. 4469 4470 @return Sum The sum of Buffer with carry bits dropped during additions. 4471 4472 **/ 4473 UINT32 4474 EFIAPI 4475 CalculateSum32 ( 4476 IN CONST UINT32 *Buffer, 4477 IN UINTN Length 4478 ); 4479 4480 /** 4481 Returns the two's complement checksum of all elements in a buffer of 4482 32-bit values. 4483 4484 This function first calculates the sum of the 32-bit values in the buffer 4485 specified by Buffer and Length. The carry bits in the result of addition 4486 are dropped. Then, the two's complement of the sum is returned. If Length 4487 is 0, then 0 is returned. 4488 4489 If Buffer is NULL, then ASSERT(). 4490 If Buffer is not aligned on a 32-bit boundary, then ASSERT(). 4491 If Length is not aligned on a 32-bit boundary, then ASSERT(). 4492 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 4493 4494 @param Buffer The pointer to the buffer to carry out the checksum operation. 4495 @param Length The size, in bytes, of Buffer. 4496 4497 @return Checksum The two's complement checksum of Buffer. 4498 4499 **/ 4500 UINT32 4501 EFIAPI 4502 CalculateCheckSum32 ( 4503 IN CONST UINT32 *Buffer, 4504 IN UINTN Length 4505 ); 4506 4507 /** 4508 Returns the sum of all elements in a buffer of 64-bit values. During 4509 calculation, the carry bits are dropped. 4510 4511 This function calculates the sum of the 64-bit values in the buffer 4512 specified by Buffer and Length. The carry bits in result of addition are dropped. 4513 The 64-bit result is returned. If Length is 0, then 0 is returned. 4514 4515 If Buffer is NULL, then ASSERT(). 4516 If Buffer is not aligned on a 64-bit boundary, then ASSERT(). 4517 If Length is not aligned on a 64-bit boundary, then ASSERT(). 4518 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 4519 4520 @param Buffer The pointer to the buffer to carry out the sum operation. 4521 @param Length The size, in bytes, of Buffer. 4522 4523 @return Sum The sum of Buffer with carry bits dropped during additions. 4524 4525 **/ 4526 UINT64 4527 EFIAPI 4528 CalculateSum64 ( 4529 IN CONST UINT64 *Buffer, 4530 IN UINTN Length 4531 ); 4532 4533 /** 4534 Returns the two's complement checksum of all elements in a buffer of 4535 64-bit values. 4536 4537 This function first calculates the sum of the 64-bit values in the buffer 4538 specified by Buffer and Length. The carry bits in the result of addition 4539 are dropped. Then, the two's complement of the sum is returned. If Length 4540 is 0, then 0 is returned. 4541 4542 If Buffer is NULL, then ASSERT(). 4543 If Buffer is not aligned on a 64-bit boundary, then ASSERT(). 4544 If Length is not aligned on a 64-bit boundary, then ASSERT(). 4545 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 4546 4547 @param Buffer The pointer to the buffer to carry out the checksum operation. 4548 @param Length The size, in bytes, of Buffer. 4549 4550 @return Checksum The two's complement checksum of Buffer. 4551 4552 **/ 4553 UINT64 4554 EFIAPI 4555 CalculateCheckSum64 ( 4556 IN CONST UINT64 *Buffer, 4557 IN UINTN Length 4558 ); 4559 4560 /** 4561 Computes and returns a 32-bit CRC for a data buffer. 4562 CRC32 value bases on ITU-T V.42. 4563 4564 If Buffer is NULL, then ASSERT(). 4565 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 4566 4567 @param[in] Buffer A pointer to the buffer on which the 32-bit CRC is to be computed. 4568 @param[in] Length The number of bytes in the buffer Data. 4569 4570 @retval Crc32 The 32-bit CRC was computed for the data buffer. 4571 4572 **/ 4573 UINT32 4574 EFIAPI 4575 CalculateCrc32 ( 4576 IN VOID *Buffer, 4577 IN UINTN Length 4578 ); 4579 4580 /** 4581 Calculates the CRC16-ANSI checksum of the given buffer. 4582 4583 @param[in] Buffer Pointer to the buffer. 4584 @param[in] Length Length of the buffer, in bytes. 4585 @param[in] InitialValue Initial value of the CRC. 4586 4587 @return The CRC16-ANSI checksum. 4588 **/ 4589 UINT16 4590 EFIAPI 4591 CalculateCrc16Ansi ( 4592 IN CONST VOID *Buffer, 4593 IN UINTN Length, 4594 IN UINT16 InitialValue 4595 ); 4596 4597 /** 4598 Calculates the CRC32c checksum of the given buffer. 4599 4600 @param[in] Buffer Pointer to the buffer. 4601 @param[in] Length Length of the buffer, in bytes. 4602 @param[in] InitialValue Initial value of the CRC. 4603 4604 @return The CRC32c checksum. 4605 **/ 4606 UINT32 4607 EFIAPI 4608 CalculateCrc32c ( 4609 IN CONST VOID *Buffer, 4610 IN UINTN Length, 4611 IN UINT32 InitialValue 4612 ); 4613 4614 // 4615 // Base Library CPU Functions 4616 // 4617 4618 /** 4619 Function entry point used when a stack switch is requested with SwitchStack() 4620 4621 @param Context1 Context1 parameter passed into SwitchStack(). 4622 @param Context2 Context2 parameter passed into SwitchStack(). 4623 **/ 4624 typedef 4625 VOID 4626 (EFIAPI *SWITCH_STACK_ENTRY_POINT)( 4627 IN VOID *Context1 OPTIONAL, 4628 IN VOID *Context2 OPTIONAL 4629 ); 4630 4631 /** 4632 Used to serialize load and store operations. 4633 4634 All loads and stores that proceed calls to this function are guaranteed to be 4635 globally visible when this function returns. 4636 4637 **/ 4638 VOID 4639 EFIAPI 4640 MemoryFence ( 4641 VOID 4642 ); 4643 4644 /** 4645 Saves the current CPU context that can be restored with a call to LongJump() 4646 and returns 0. 4647 4648 Saves the current CPU context in the buffer specified by JumpBuffer and 4649 returns 0. The initial call to SetJump() must always return 0. Subsequent 4650 calls to LongJump() cause a non-zero value to be returned by SetJump(). 4651 4652 If JumpBuffer is NULL, then ASSERT(). 4653 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT(). 4654 4655 NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific. 4656 The same structure must never be used for more than one CPU architecture context. 4657 For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module. 4658 SetJump()/LongJump() is not currently supported for the EBC processor type. 4659 4660 @param JumpBuffer A pointer to CPU context buffer. 4661 4662 @retval 0 Indicates a return from SetJump(). 4663 4664 **/ 4665 RETURNS_TWICE 4666 UINTN 4667 EFIAPI 4668 SetJump ( 4669 OUT BASE_LIBRARY_JUMP_BUFFER *JumpBuffer 4670 ); 4671 4672 /** 4673 Restores the CPU context that was saved with SetJump(). 4674 4675 Restores the CPU context from the buffer specified by JumpBuffer. This 4676 function never returns to the caller. Instead is resumes execution based on 4677 the state of JumpBuffer. 4678 4679 If JumpBuffer is NULL, then ASSERT(). 4680 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT(). 4681 If Value is 0, then ASSERT(). 4682 4683 @param JumpBuffer A pointer to CPU context buffer. 4684 @param Value The value to return when the SetJump() context is 4685 restored and must be non-zero. 4686 4687 **/ 4688 VOID 4689 EFIAPI 4690 LongJump ( 4691 IN BASE_LIBRARY_JUMP_BUFFER *JumpBuffer, 4692 IN UINTN Value 4693 ); 4694 4695 /** 4696 Enables CPU interrupts. 4697 4698 **/ 4699 VOID 4700 EFIAPI 4701 EnableInterrupts ( 4702 VOID 4703 ); 4704 4705 /** 4706 Disables CPU interrupts. 4707 4708 **/ 4709 VOID 4710 EFIAPI 4711 DisableInterrupts ( 4712 VOID 4713 ); 4714 4715 /** 4716 Disables CPU interrupts and returns the interrupt state prior to the disable 4717 operation. 4718 4719 @retval TRUE CPU interrupts were enabled on entry to this call. 4720 @retval FALSE CPU interrupts were disabled on entry to this call. 4721 4722 **/ 4723 BOOLEAN 4724 EFIAPI 4725 SaveAndDisableInterrupts ( 4726 VOID 4727 ); 4728 4729 /** 4730 Enables CPU interrupts for the smallest window required to capture any 4731 pending interrupts. 4732 4733 **/ 4734 VOID 4735 EFIAPI 4736 EnableDisableInterrupts ( 4737 VOID 4738 ); 4739 4740 /** 4741 Retrieves the current CPU interrupt state. 4742 4743 Returns TRUE if interrupts are currently enabled. Otherwise 4744 returns FALSE. 4745 4746 @retval TRUE CPU interrupts are enabled. 4747 @retval FALSE CPU interrupts are disabled. 4748 4749 **/ 4750 BOOLEAN 4751 EFIAPI 4752 GetInterruptState ( 4753 VOID 4754 ); 4755 4756 /** 4757 Set the current CPU interrupt state. 4758 4759 Sets the current CPU interrupt state to the state specified by 4760 InterruptState. If InterruptState is TRUE, then interrupts are enabled. If 4761 InterruptState is FALSE, then interrupts are disabled. InterruptState is 4762 returned. 4763 4764 @param InterruptState TRUE if interrupts should enabled. FALSE if 4765 interrupts should be disabled. 4766 4767 @return InterruptState 4768 4769 **/ 4770 BOOLEAN 4771 EFIAPI 4772 SetInterruptState ( 4773 IN BOOLEAN InterruptState 4774 ); 4775 4776 /** 4777 Requests CPU to pause for a short period of time. 4778 4779 Requests CPU to pause for a short period of time. Typically used in MP 4780 systems to prevent memory starvation while waiting for a spin lock. 4781 4782 **/ 4783 VOID 4784 EFIAPI 4785 CpuPause ( 4786 VOID 4787 ); 4788 4789 /** 4790 Transfers control to a function starting with a new stack. 4791 4792 Transfers control to the function specified by EntryPoint using the 4793 new stack specified by NewStack and passing in the parameters specified 4794 by Context1 and Context2. Context1 and Context2 are optional and may 4795 be NULL. The function EntryPoint must never return. This function 4796 supports a variable number of arguments following the NewStack parameter. 4797 These additional arguments are ignored on IA-32, x64, and EBC architectures. 4798 Itanium processors expect one additional parameter of type VOID * that specifies 4799 the new backing store pointer. 4800 4801 If EntryPoint is NULL, then ASSERT(). 4802 If NewStack is NULL, then ASSERT(). 4803 4804 @param EntryPoint A pointer to function to call with the new stack. 4805 @param Context1 A pointer to the context to pass into the EntryPoint 4806 function. 4807 @param Context2 A pointer to the context to pass into the EntryPoint 4808 function. 4809 @param NewStack A pointer to the new stack to use for the EntryPoint 4810 function. 4811 @param ... This variable argument list is ignored for IA-32, x64, and 4812 EBC architectures. For Itanium processors, this variable 4813 argument list is expected to contain a single parameter of 4814 type VOID * that specifies the new backing store pointer. 4815 4816 4817 **/ 4818 VOID 4819 EFIAPI 4820 SwitchStack ( 4821 IN SWITCH_STACK_ENTRY_POINT EntryPoint, 4822 IN VOID *Context1 OPTIONAL, 4823 IN VOID *Context2 OPTIONAL, 4824 IN VOID *NewStack, 4825 ... 4826 ); 4827 4828 /** 4829 Generates a breakpoint on the CPU. 4830 4831 Generates a breakpoint on the CPU. The breakpoint must be implemented such 4832 that code can resume normal execution after the breakpoint. 4833 4834 **/ 4835 VOID 4836 EFIAPI 4837 CpuBreakpoint ( 4838 VOID 4839 ); 4840 4841 /** 4842 Executes an infinite loop. 4843 4844 Forces the CPU to execute an infinite loop. A debugger may be used to skip 4845 past the loop and the code that follows the loop must execute properly. This 4846 implies that the infinite loop must not cause the code that follow it to be 4847 optimized away. 4848 4849 **/ 4850 VOID 4851 EFIAPI 4852 CpuDeadLoop ( 4853 VOID 4854 ); 4855 4856 /** 4857 Uses as a barrier to stop speculative execution. 4858 4859 Ensures that no later instruction will execute speculatively, until all prior 4860 instructions have completed. 4861 4862 **/ 4863 VOID 4864 EFIAPI 4865 SpeculationBarrier ( 4866 VOID 4867 ); 4868 4869 #if defined (MDE_CPU_X64) || defined (MDE_CPU_IA32) 4870 4871 /** 4872 The TDCALL instruction causes a VM exit to the Intel TDX module. It is 4873 used to call guest-side Intel TDX functions, either local or a TD exit 4874 to the host VMM, as selected by Leaf. 4875 4876 @param[in] Leaf Leaf number of TDCALL instruction 4877 @param[in] Arg1 Arg1 4878 @param[in] Arg2 Arg2 4879 @param[in] Arg3 Arg3 4880 @param[in,out] Results Returned result of the Leaf function 4881 4882 @return 0 A successful call 4883 @return Other See individual leaf functions 4884 **/ 4885 UINTN 4886 EFIAPI 4887 TdCall ( 4888 IN UINT64 Leaf, 4889 IN UINT64 Arg1, 4890 IN UINT64 Arg2, 4891 IN UINT64 Arg3, 4892 IN OUT VOID *Results 4893 ); 4894 4895 /** 4896 TDVMALL is a leaf function 0 for TDCALL. It helps invoke services from the 4897 host VMM to pass/receive information. 4898 4899 @param[in] Leaf Number of sub-functions 4900 @param[in] Arg1 Arg1 4901 @param[in] Arg2 Arg2 4902 @param[in] Arg3 Arg3 4903 @param[in] Arg4 Arg4 4904 @param[in,out] Results Returned result of the sub-function 4905 4906 @return 0 A successful call 4907 @return Other See individual sub-functions 4908 4909 **/ 4910 UINTN 4911 EFIAPI 4912 TdVmCall ( 4913 IN UINT64 Leaf, 4914 IN UINT64 Arg1, 4915 IN UINT64 Arg2, 4916 IN UINT64 Arg3, 4917 IN UINT64 Arg4, 4918 IN OUT VOID *Results 4919 ); 4920 4921 /** 4922 Probe if TD is enabled. 4923 4924 @return TRUE TD is enabled. 4925 @return FALSE TD is not enabled. 4926 **/ 4927 BOOLEAN 4928 EFIAPI 4929 TdIsEnabled ( 4930 VOID 4931 ); 4932 4933 #endif 4934 4935 #if defined (MDE_CPU_X64) 4936 // 4937 // The page size for the PVALIDATE instruction 4938 // 4939 typedef enum { 4940 PvalidatePageSize4K = 0, 4941 PvalidatePageSize2MB, 4942 } PVALIDATE_PAGE_SIZE; 4943 4944 // 4945 // PVALIDATE Return Code. 4946 // 4947 #define PVALIDATE_RET_SUCCESS 0 4948 #define PVALIDATE_RET_FAIL_INPUT 1 4949 #define PVALIDATE_RET_SIZE_MISMATCH 6 4950 4951 // 4952 // The PVALIDATE instruction did not make any changes to the RMP entry. 4953 // 4954 #define PVALIDATE_RET_NO_RMPUPDATE 255 4955 4956 /** 4957 Execute a PVALIDATE instruction to validate or to rescinds validation of a guest 4958 page's RMP entry. 4959 4960 The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1. 4961 4962 The function is available on X64. 4963 4964 @param[in] PageSize The page size to use. 4965 @param[in] Validate If TRUE, validate the guest virtual address 4966 otherwise invalidate the guest virtual address. 4967 @param[in] Address The guest virtual address. 4968 4969 @retval PVALIDATE_RET_SUCCESS The PVALIDATE instruction succeeded, and 4970 updated the RMP entry. 4971 @retval PVALIDATE_RET_NO_RMPUPDATE The PVALIDATE instruction succeeded, but 4972 did not update the RMP entry. 4973 @return Failure code from the PVALIDATE 4974 instruction. 4975 **/ 4976 UINT32 4977 EFIAPI 4978 AsmPvalidate ( 4979 IN PVALIDATE_PAGE_SIZE PageSize, 4980 IN BOOLEAN Validate, 4981 IN PHYSICAL_ADDRESS Address 4982 ); 4983 4984 // 4985 // RDX settings for RMPADJUST 4986 // 4987 #define RMPADJUST_VMPL_MAX 3 4988 #define RMPADJUST_VMPL_MASK 0xFF 4989 #define RMPADJUST_VMPL_SHIFT 0 4990 #define RMPADJUST_PERMISSION_MASK_MASK 0xFF 4991 #define RMPADJUST_PERMISSION_MASK_SHIFT 8 4992 #define RMPADJUST_VMSA_PAGE_BIT BIT16 4993 4994 /** 4995 Adjusts the permissions of an SEV-SNP guest page. 4996 4997 Executes a RMPADJUST instruction with the register state specified by Rax, 4998 Rcx, and Rdx. Returns Eax. This function is only available on X64. 4999 5000 The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1. 5001 5002 @param[in] Rax The value to load into RAX before executing the RMPADJUST 5003 instruction. 5004 @param[in] Rcx The value to load into RCX before executing the RMPADJUST 5005 instruction. 5006 @param[in] Rdx The value to load into RDX before executing the RMPADJUST 5007 instruction. 5008 5009 @return Eax 5010 **/ 5011 UINT32 5012 EFIAPI 5013 AsmRmpAdjust ( 5014 IN UINT64 Rax, 5015 IN UINT64 Rcx, 5016 IN UINT64 Rdx 5017 ); 5018 5019 #endif 5020 5021 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64) 5022 /// 5023 /// IA32 and x64 Specific Functions. 5024 /// Byte packed structure for 16-bit Real Mode EFLAGS. 5025 /// 5026 typedef union { 5027 struct { 5028 UINT32 CF : 1; ///< Carry Flag. 5029 UINT32 Reserved_0 : 1; ///< Reserved. 5030 UINT32 PF : 1; ///< Parity Flag. 5031 UINT32 Reserved_1 : 1; ///< Reserved. 5032 UINT32 AF : 1; ///< Auxiliary Carry Flag. 5033 UINT32 Reserved_2 : 1; ///< Reserved. 5034 UINT32 ZF : 1; ///< Zero Flag. 5035 UINT32 SF : 1; ///< Sign Flag. 5036 UINT32 TF : 1; ///< Trap Flag. 5037 UINT32 IF : 1; ///< Interrupt Enable Flag. 5038 UINT32 DF : 1; ///< Direction Flag. 5039 UINT32 OF : 1; ///< Overflow Flag. 5040 UINT32 IOPL : 2; ///< I/O Privilege Level. 5041 UINT32 NT : 1; ///< Nested Task. 5042 UINT32 Reserved_3 : 1; ///< Reserved. 5043 } Bits; 5044 UINT16 Uint16; 5045 } IA32_FLAGS16; 5046 5047 /// 5048 /// Byte packed structure for EFLAGS/RFLAGS. 5049 /// 32-bits on IA-32. 5050 /// 64-bits on x64. The upper 32-bits on x64 are reserved. 5051 /// 5052 typedef union { 5053 struct { 5054 UINT32 CF : 1; ///< Carry Flag. 5055 UINT32 Reserved_0 : 1; ///< Reserved. 5056 UINT32 PF : 1; ///< Parity Flag. 5057 UINT32 Reserved_1 : 1; ///< Reserved. 5058 UINT32 AF : 1; ///< Auxiliary Carry Flag. 5059 UINT32 Reserved_2 : 1; ///< Reserved. 5060 UINT32 ZF : 1; ///< Zero Flag. 5061 UINT32 SF : 1; ///< Sign Flag. 5062 UINT32 TF : 1; ///< Trap Flag. 5063 UINT32 IF : 1; ///< Interrupt Enable Flag. 5064 UINT32 DF : 1; ///< Direction Flag. 5065 UINT32 OF : 1; ///< Overflow Flag. 5066 UINT32 IOPL : 2; ///< I/O Privilege Level. 5067 UINT32 NT : 1; ///< Nested Task. 5068 UINT32 Reserved_3 : 1; ///< Reserved. 5069 UINT32 RF : 1; ///< Resume Flag. 5070 UINT32 VM : 1; ///< Virtual 8086 Mode. 5071 UINT32 AC : 1; ///< Alignment Check. 5072 UINT32 VIF : 1; ///< Virtual Interrupt Flag. 5073 UINT32 VIP : 1; ///< Virtual Interrupt Pending. 5074 UINT32 ID : 1; ///< ID Flag. 5075 UINT32 Reserved_4 : 10; ///< Reserved. 5076 } Bits; 5077 UINTN UintN; 5078 } IA32_EFLAGS32; 5079 5080 /// 5081 /// Byte packed structure for Control Register 0 (CR0). 5082 /// 32-bits on IA-32. 5083 /// 64-bits on x64. The upper 32-bits on x64 are reserved. 5084 /// 5085 typedef union { 5086 struct { 5087 UINT32 PE : 1; ///< Protection Enable. 5088 UINT32 MP : 1; ///< Monitor Coprocessor. 5089 UINT32 EM : 1; ///< Emulation. 5090 UINT32 TS : 1; ///< Task Switched. 5091 UINT32 ET : 1; ///< Extension Type. 5092 UINT32 NE : 1; ///< Numeric Error. 5093 UINT32 Reserved_0 : 10; ///< Reserved. 5094 UINT32 WP : 1; ///< Write Protect. 5095 UINT32 Reserved_1 : 1; ///< Reserved. 5096 UINT32 AM : 1; ///< Alignment Mask. 5097 UINT32 Reserved_2 : 10; ///< Reserved. 5098 UINT32 NW : 1; ///< Mot Write-through. 5099 UINT32 CD : 1; ///< Cache Disable. 5100 UINT32 PG : 1; ///< Paging. 5101 } Bits; 5102 UINTN UintN; 5103 } IA32_CR0; 5104 5105 /// 5106 /// Byte packed structure for Control Register 4 (CR4). 5107 /// 32-bits on IA-32. 5108 /// 64-bits on x64. The upper 32-bits on x64 are reserved. 5109 /// 5110 typedef union { 5111 struct { 5112 UINT32 VME : 1; ///< Virtual-8086 Mode Extensions. 5113 UINT32 PVI : 1; ///< Protected-Mode Virtual Interrupts. 5114 UINT32 TSD : 1; ///< Time Stamp Disable. 5115 UINT32 DE : 1; ///< Debugging Extensions. 5116 UINT32 PSE : 1; ///< Page Size Extensions. 5117 UINT32 PAE : 1; ///< Physical Address Extension. 5118 UINT32 MCE : 1; ///< Machine Check Enable. 5119 UINT32 PGE : 1; ///< Page Global Enable. 5120 UINT32 PCE : 1; ///< Performance Monitoring Counter 5121 ///< Enable. 5122 UINT32 OSFXSR : 1; ///< Operating System Support for 5123 ///< FXSAVE and FXRSTOR instructions 5124 UINT32 OSXMMEXCPT : 1; ///< Operating System Support for 5125 ///< Unmasked SIMD Floating Point 5126 ///< Exceptions. 5127 UINT32 UMIP : 1; ///< User-Mode Instruction Prevention. 5128 UINT32 LA57 : 1; ///< Linear Address 57bit. 5129 UINT32 VMXE : 1; ///< VMX Enable. 5130 UINT32 SMXE : 1; ///< SMX Enable. 5131 UINT32 Reserved_3 : 1; ///< Reserved. 5132 UINT32 FSGSBASE : 1; ///< FSGSBASE Enable. 5133 UINT32 PCIDE : 1; ///< PCID Enable. 5134 UINT32 OSXSAVE : 1; ///< XSAVE and Processor Extended States Enable. 5135 UINT32 Reserved_4 : 1; ///< Reserved. 5136 UINT32 SMEP : 1; ///< SMEP Enable. 5137 UINT32 SMAP : 1; ///< SMAP Enable. 5138 UINT32 PKE : 1; ///< Protection-Key Enable. 5139 UINT32 Reserved_5 : 9; ///< Reserved. 5140 } Bits; 5141 UINTN UintN; 5142 } IA32_CR4; 5143 5144 /// 5145 /// Byte packed structure for a segment descriptor in a GDT/LDT. 5146 /// 5147 typedef union { 5148 struct { 5149 UINT32 LimitLow : 16; 5150 UINT32 BaseLow : 16; 5151 UINT32 BaseMid : 8; 5152 UINT32 Type : 4; 5153 UINT32 S : 1; 5154 UINT32 DPL : 2; 5155 UINT32 P : 1; 5156 UINT32 LimitHigh : 4; 5157 UINT32 AVL : 1; 5158 UINT32 L : 1; 5159 UINT32 DB : 1; 5160 UINT32 G : 1; 5161 UINT32 BaseHigh : 8; 5162 } Bits; 5163 UINT64 Uint64; 5164 } IA32_SEGMENT_DESCRIPTOR; 5165 5166 /// 5167 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor. 5168 /// 5169 #pragma pack (1) 5170 typedef struct { 5171 UINT16 Limit; 5172 UINTN Base; 5173 } IA32_DESCRIPTOR; 5174 #pragma pack () 5175 5176 #define IA32_IDT_GATE_TYPE_TASK 0x85 5177 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86 5178 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87 5179 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E 5180 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F 5181 5182 #define IA32_GDT_TYPE_TSS 0x9 5183 #define IA32_GDT_ALIGNMENT 8 5184 5185 #if defined (MDE_CPU_IA32) 5186 /// 5187 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor. 5188 /// 5189 typedef union { 5190 struct { 5191 UINT32 OffsetLow : 16; ///< Offset bits 15..0. 5192 UINT32 Selector : 16; ///< Selector. 5193 UINT32 Reserved_0 : 8; ///< Reserved. 5194 UINT32 GateType : 8; ///< Gate Type. See #defines above. 5195 UINT32 OffsetHigh : 16; ///< Offset bits 31..16. 5196 } Bits; 5197 UINT64 Uint64; 5198 } IA32_IDT_GATE_DESCRIPTOR; 5199 5200 #pragma pack (1) 5201 // 5202 // IA32 Task-State Segment Definition 5203 // 5204 typedef struct { 5205 UINT16 PreviousTaskLink; 5206 UINT16 Reserved_2; 5207 UINT32 ESP0; 5208 UINT16 SS0; 5209 UINT16 Reserved_10; 5210 UINT32 ESP1; 5211 UINT16 SS1; 5212 UINT16 Reserved_18; 5213 UINT32 ESP2; 5214 UINT16 SS2; 5215 UINT16 Reserved_26; 5216 UINT32 CR3; 5217 UINT32 EIP; 5218 UINT32 EFLAGS; 5219 UINT32 EAX; 5220 UINT32 ECX; 5221 UINT32 EDX; 5222 UINT32 EBX; 5223 UINT32 ESP; 5224 UINT32 EBP; 5225 UINT32 ESI; 5226 UINT32 EDI; 5227 UINT16 ES; 5228 UINT16 Reserved_74; 5229 UINT16 CS; 5230 UINT16 Reserved_78; 5231 UINT16 SS; 5232 UINT16 Reserved_82; 5233 UINT16 DS; 5234 UINT16 Reserved_86; 5235 UINT16 FS; 5236 UINT16 Reserved_90; 5237 UINT16 GS; 5238 UINT16 Reserved_94; 5239 UINT16 LDTSegmentSelector; 5240 UINT16 Reserved_98; 5241 UINT16 T; 5242 UINT16 IOMapBaseAddress; 5243 } IA32_TASK_STATE_SEGMENT; 5244 5245 typedef union { 5246 struct { 5247 UINT32 LimitLow : 16; ///< Segment Limit 15..00 5248 UINT32 BaseLow : 16; ///< Base Address 15..00 5249 UINT32 BaseMid : 8; ///< Base Address 23..16 5250 UINT32 Type : 4; ///< Type (1 0 B 1) 5251 UINT32 Reserved_43 : 1; ///< 0 5252 UINT32 DPL : 2; ///< Descriptor Privilege Level 5253 UINT32 P : 1; ///< Segment Present 5254 UINT32 LimitHigh : 4; ///< Segment Limit 19..16 5255 UINT32 AVL : 1; ///< Available for use by system software 5256 UINT32 Reserved_52 : 2; ///< 0 0 5257 UINT32 G : 1; ///< Granularity 5258 UINT32 BaseHigh : 8; ///< Base Address 31..24 5259 } Bits; 5260 UINT64 Uint64; 5261 } IA32_TSS_DESCRIPTOR; 5262 #pragma pack () 5263 5264 #endif // defined (MDE_CPU_IA32) 5265 5266 #if defined (MDE_CPU_X64) 5267 /// 5268 /// Byte packed structure for an x64 Interrupt Gate Descriptor. 5269 /// 5270 typedef union { 5271 struct { 5272 UINT32 OffsetLow : 16; ///< Offset bits 15..0. 5273 UINT32 Selector : 16; ///< Selector. 5274 UINT32 Reserved_0 : 8; ///< Reserved. 5275 UINT32 GateType : 8; ///< Gate Type. See #defines above. 5276 UINT32 OffsetHigh : 16; ///< Offset bits 31..16. 5277 UINT32 OffsetUpper : 32; ///< Offset bits 63..32. 5278 UINT32 Reserved_1 : 32; ///< Reserved. 5279 } Bits; 5280 struct { 5281 UINT64 Uint64; 5282 UINT64 Uint64_1; 5283 } Uint128; 5284 } IA32_IDT_GATE_DESCRIPTOR; 5285 5286 #pragma pack (1) 5287 // 5288 // IA32 Task-State Segment Definition 5289 // 5290 typedef struct { 5291 UINT32 Reserved_0; 5292 UINT64 RSP0; 5293 UINT64 RSP1; 5294 UINT64 RSP2; 5295 UINT64 Reserved_28; 5296 UINT64 IST[7]; 5297 UINT64 Reserved_92; 5298 UINT16 Reserved_100; 5299 UINT16 IOMapBaseAddress; 5300 } IA32_TASK_STATE_SEGMENT; 5301 5302 typedef union { 5303 struct { 5304 UINT32 LimitLow : 16; ///< Segment Limit 15..00 5305 UINT32 BaseLow : 16; ///< Base Address 15..00 5306 UINT32 BaseMidl : 8; ///< Base Address 23..16 5307 UINT32 Type : 4; ///< Type (1 0 B 1) 5308 UINT32 Reserved_43 : 1; ///< 0 5309 UINT32 DPL : 2; ///< Descriptor Privilege Level 5310 UINT32 P : 1; ///< Segment Present 5311 UINT32 LimitHigh : 4; ///< Segment Limit 19..16 5312 UINT32 AVL : 1; ///< Available for use by system software 5313 UINT32 Reserved_52 : 2; ///< 0 0 5314 UINT32 G : 1; ///< Granularity 5315 UINT32 BaseMidh : 8; ///< Base Address 31..24 5316 UINT32 BaseHigh : 32; ///< Base Address 63..32 5317 UINT32 Reserved_96 : 32; ///< Reserved 5318 } Bits; 5319 struct { 5320 UINT64 Uint64; 5321 UINT64 Uint64_1; 5322 } Uint128; 5323 } IA32_TSS_DESCRIPTOR; 5324 #pragma pack () 5325 5326 #endif // defined (MDE_CPU_X64) 5327 5328 /// 5329 /// Byte packed structure for an FP/SSE/SSE2 context. 5330 /// 5331 typedef struct { 5332 UINT8 Buffer[512]; 5333 } IA32_FX_BUFFER; 5334 5335 /// 5336 /// Structures for the 16-bit real mode thunks. 5337 /// 5338 typedef struct { 5339 UINT32 Reserved1; 5340 UINT32 Reserved2; 5341 UINT32 Reserved3; 5342 UINT32 Reserved4; 5343 UINT8 BL; 5344 UINT8 BH; 5345 UINT16 Reserved5; 5346 UINT8 DL; 5347 UINT8 DH; 5348 UINT16 Reserved6; 5349 UINT8 CL; 5350 UINT8 CH; 5351 UINT16 Reserved7; 5352 UINT8 AL; 5353 UINT8 AH; 5354 UINT16 Reserved8; 5355 } IA32_BYTE_REGS; 5356 5357 typedef struct { 5358 UINT16 DI; 5359 UINT16 Reserved1; 5360 UINT16 SI; 5361 UINT16 Reserved2; 5362 UINT16 BP; 5363 UINT16 Reserved3; 5364 UINT16 SP; 5365 UINT16 Reserved4; 5366 UINT16 BX; 5367 UINT16 Reserved5; 5368 UINT16 DX; 5369 UINT16 Reserved6; 5370 UINT16 CX; 5371 UINT16 Reserved7; 5372 UINT16 AX; 5373 UINT16 Reserved8; 5374 } IA32_WORD_REGS; 5375 5376 typedef struct { 5377 UINT32 EDI; 5378 UINT32 ESI; 5379 UINT32 EBP; 5380 UINT32 ESP; 5381 UINT32 EBX; 5382 UINT32 EDX; 5383 UINT32 ECX; 5384 UINT32 EAX; 5385 UINT16 DS; 5386 UINT16 ES; 5387 UINT16 FS; 5388 UINT16 GS; 5389 IA32_EFLAGS32 EFLAGS; 5390 UINT32 Eip; 5391 UINT16 CS; 5392 UINT16 SS; 5393 } IA32_DWORD_REGS; 5394 5395 typedef union { 5396 IA32_DWORD_REGS E; 5397 IA32_WORD_REGS X; 5398 IA32_BYTE_REGS H; 5399 } IA32_REGISTER_SET; 5400 5401 /// 5402 /// Byte packed structure for an 16-bit real mode thunks. 5403 /// 5404 typedef struct { 5405 IA32_REGISTER_SET *RealModeState; 5406 VOID *RealModeBuffer; 5407 UINT32 RealModeBufferSize; 5408 UINT32 ThunkAttributes; 5409 } THUNK_CONTEXT; 5410 5411 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001 5412 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002 5413 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004 5414 5415 /// 5416 /// Type definition for representing labels in NASM source code that allow for 5417 /// the patching of immediate operands of IA32 and X64 instructions. 5418 /// 5419 /// While the type is technically defined as a function type (note: not a 5420 /// pointer-to-function type), such labels in NASM source code never stand for 5421 /// actual functions, and identifiers declared with this function type should 5422 /// never be called. This is also why the EFIAPI calling convention specifier 5423 /// is missing from the typedef, and why the typedef does not follow the usual 5424 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID 5425 /// return type and the VOID argument list are merely artifacts. 5426 /// 5427 typedef VOID (X86_ASSEMBLY_PATCH_LABEL) ( 5428 VOID 5429 ); 5430 5431 /** 5432 Retrieves CPUID information. 5433 5434 Executes the CPUID instruction with EAX set to the value specified by Index. 5435 This function always returns Index. 5436 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax. 5437 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx. 5438 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx. 5439 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx. 5440 This function is only available on IA-32 and x64. 5441 5442 @param Index The 32-bit value to load into EAX prior to invoking the CPUID 5443 instruction. 5444 @param Eax The pointer to the 32-bit EAX value returned by the CPUID 5445 instruction. This is an optional parameter that may be NULL. 5446 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID 5447 instruction. This is an optional parameter that may be NULL. 5448 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID 5449 instruction. This is an optional parameter that may be NULL. 5450 @param Edx The pointer to the 32-bit EDX value returned by the CPUID 5451 instruction. This is an optional parameter that may be NULL. 5452 5453 @return Index. 5454 5455 **/ 5456 UINT32 5457 EFIAPI 5458 AsmCpuid ( 5459 IN UINT32 Index, 5460 OUT UINT32 *Eax OPTIONAL, 5461 OUT UINT32 *Ebx OPTIONAL, 5462 OUT UINT32 *Ecx OPTIONAL, 5463 OUT UINT32 *Edx OPTIONAL 5464 ); 5465 5466 /** 5467 Retrieves CPUID information using an extended leaf identifier. 5468 5469 Executes the CPUID instruction with EAX set to the value specified by Index 5470 and ECX set to the value specified by SubIndex. This function always returns 5471 Index. This function is only available on IA-32 and x64. 5472 5473 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax. 5474 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx. 5475 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx. 5476 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx. 5477 5478 @param Index The 32-bit value to load into EAX prior to invoking the 5479 CPUID instruction. 5480 @param SubIndex The 32-bit value to load into ECX prior to invoking the 5481 CPUID instruction. 5482 @param Eax The pointer to the 32-bit EAX value returned by the CPUID 5483 instruction. This is an optional parameter that may be 5484 NULL. 5485 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID 5486 instruction. This is an optional parameter that may be 5487 NULL. 5488 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID 5489 instruction. This is an optional parameter that may be 5490 NULL. 5491 @param Edx The pointer to the 32-bit EDX value returned by the CPUID 5492 instruction. This is an optional parameter that may be 5493 NULL. 5494 5495 @return Index. 5496 5497 **/ 5498 UINT32 5499 EFIAPI 5500 AsmCpuidEx ( 5501 IN UINT32 Index, 5502 IN UINT32 SubIndex, 5503 OUT UINT32 *Eax OPTIONAL, 5504 OUT UINT32 *Ebx OPTIONAL, 5505 OUT UINT32 *Ecx OPTIONAL, 5506 OUT UINT32 *Edx OPTIONAL 5507 ); 5508 5509 /** 5510 Set CD bit and clear NW bit of CR0 followed by a WBINVD. 5511 5512 Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0, 5513 and executing a WBINVD instruction. This function is only available on IA-32 and x64. 5514 5515 **/ 5516 VOID 5517 EFIAPI 5518 AsmDisableCache ( 5519 VOID 5520 ); 5521 5522 /** 5523 Perform a WBINVD and clear both the CD and NW bits of CR0. 5524 5525 Enables the caches by executing a WBINVD instruction and then clear both the CD and NW 5526 bits of CR0 to 0. This function is only available on IA-32 and x64. 5527 5528 **/ 5529 VOID 5530 EFIAPI 5531 AsmEnableCache ( 5532 VOID 5533 ); 5534 5535 /** 5536 Returns the lower 32-bits of a Machine Specific Register(MSR). 5537 5538 Reads and returns the lower 32-bits of the MSR specified by Index. 5539 No parameter checking is performed on Index, and some Index values may cause 5540 CPU exceptions. The caller must either guarantee that Index is valid, or the 5541 caller must set up exception handlers to catch the exceptions. This function 5542 is only available on IA-32 and x64. 5543 5544 @param Index The 32-bit MSR index to read. 5545 5546 @return The lower 32 bits of the MSR identified by Index. 5547 5548 **/ 5549 UINT32 5550 EFIAPI 5551 AsmReadMsr32 ( 5552 IN UINT32 Index 5553 ); 5554 5555 /** 5556 Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value. 5557 The upper 32-bits of the MSR are set to zero. 5558 5559 Writes the 32-bit value specified by Value to the MSR specified by Index. The 5560 upper 32-bits of the MSR write are set to zero. The 32-bit value written to 5561 the MSR is returned. No parameter checking is performed on Index or Value, 5562 and some of these may cause CPU exceptions. The caller must either guarantee 5563 that Index and Value are valid, or the caller must establish proper exception 5564 handlers. This function is only available on IA-32 and x64. 5565 5566 @param Index The 32-bit MSR index to write. 5567 @param Value The 32-bit value to write to the MSR. 5568 5569 @return Value 5570 5571 **/ 5572 UINT32 5573 EFIAPI 5574 AsmWriteMsr32 ( 5575 IN UINT32 Index, 5576 IN UINT32 Value 5577 ); 5578 5579 /** 5580 Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and 5581 writes the result back to the 64-bit MSR. 5582 5583 Reads the 64-bit MSR specified by Index, performs a bitwise OR 5584 between the lower 32-bits of the read result and the value specified by 5585 OrData, and writes the result to the 64-bit MSR specified by Index. The lower 5586 32-bits of the value written to the MSR is returned. No parameter checking is 5587 performed on Index or OrData, and some of these may cause CPU exceptions. The 5588 caller must either guarantee that Index and OrData are valid, or the caller 5589 must establish proper exception handlers. This function is only available on 5590 IA-32 and x64. 5591 5592 @param Index The 32-bit MSR index to write. 5593 @param OrData The value to OR with the read value from the MSR. 5594 5595 @return The lower 32-bit value written to the MSR. 5596 5597 **/ 5598 UINT32 5599 EFIAPI 5600 AsmMsrOr32 ( 5601 IN UINT32 Index, 5602 IN UINT32 OrData 5603 ); 5604 5605 /** 5606 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes 5607 the result back to the 64-bit MSR. 5608 5609 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the 5610 lower 32-bits of the read result and the value specified by AndData, and 5611 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of 5612 the value written to the MSR is returned. No parameter checking is performed 5613 on Index or AndData, and some of these may cause CPU exceptions. The caller 5614 must either guarantee that Index and AndData are valid, or the caller must 5615 establish proper exception handlers. This function is only available on IA-32 5616 and x64. 5617 5618 @param Index The 32-bit MSR index to write. 5619 @param AndData The value to AND with the read value from the MSR. 5620 5621 @return The lower 32-bit value written to the MSR. 5622 5623 **/ 5624 UINT32 5625 EFIAPI 5626 AsmMsrAnd32 ( 5627 IN UINT32 Index, 5628 IN UINT32 AndData 5629 ); 5630 5631 /** 5632 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR 5633 on the lower 32-bits, and writes the result back to the 64-bit MSR. 5634 5635 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the 5636 lower 32-bits of the read result and the value specified by AndData 5637 preserving the upper 32-bits, performs a bitwise OR between the 5638 result of the AND operation and the value specified by OrData, and writes the 5639 result to the 64-bit MSR specified by Address. The lower 32-bits of the value 5640 written to the MSR is returned. No parameter checking is performed on Index, 5641 AndData, or OrData, and some of these may cause CPU exceptions. The caller 5642 must either guarantee that Index, AndData, and OrData are valid, or the 5643 caller must establish proper exception handlers. This function is only 5644 available on IA-32 and x64. 5645 5646 @param Index The 32-bit MSR index to write. 5647 @param AndData The value to AND with the read value from the MSR. 5648 @param OrData The value to OR with the result of the AND operation. 5649 5650 @return The lower 32-bit value written to the MSR. 5651 5652 **/ 5653 UINT32 5654 EFIAPI 5655 AsmMsrAndThenOr32 ( 5656 IN UINT32 Index, 5657 IN UINT32 AndData, 5658 IN UINT32 OrData 5659 ); 5660 5661 /** 5662 Reads a bit field of an MSR. 5663 5664 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is 5665 specified by the StartBit and the EndBit. The value of the bit field is 5666 returned. The caller must either guarantee that Index is valid, or the caller 5667 must set up exception handlers to catch the exceptions. This function is only 5668 available on IA-32 and x64. 5669 5670 If StartBit is greater than 31, then ASSERT(). 5671 If EndBit is greater than 31, then ASSERT(). 5672 If EndBit is less than StartBit, then ASSERT(). 5673 5674 @param Index The 32-bit MSR index to read. 5675 @param StartBit The ordinal of the least significant bit in the bit field. 5676 Range 0..31. 5677 @param EndBit The ordinal of the most significant bit in the bit field. 5678 Range 0..31. 5679 5680 @return The bit field read from the MSR. 5681 5682 **/ 5683 UINT32 5684 EFIAPI 5685 AsmMsrBitFieldRead32 ( 5686 IN UINT32 Index, 5687 IN UINTN StartBit, 5688 IN UINTN EndBit 5689 ); 5690 5691 /** 5692 Writes a bit field to an MSR. 5693 5694 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit 5695 field is specified by the StartBit and the EndBit. All other bits in the 5696 destination MSR are preserved. The lower 32-bits of the MSR written is 5697 returned. The caller must either guarantee that Index and the data written 5698 is valid, or the caller must set up exception handlers to catch the exceptions. 5699 This function is only available on IA-32 and x64. 5700 5701 If StartBit is greater than 31, then ASSERT(). 5702 If EndBit is greater than 31, then ASSERT(). 5703 If EndBit is less than StartBit, then ASSERT(). 5704 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 5705 5706 @param Index The 32-bit MSR index to write. 5707 @param StartBit The ordinal of the least significant bit in the bit field. 5708 Range 0..31. 5709 @param EndBit The ordinal of the most significant bit in the bit field. 5710 Range 0..31. 5711 @param Value New value of the bit field. 5712 5713 @return The lower 32-bit of the value written to the MSR. 5714 5715 **/ 5716 UINT32 5717 EFIAPI 5718 AsmMsrBitFieldWrite32 ( 5719 IN UINT32 Index, 5720 IN UINTN StartBit, 5721 IN UINTN EndBit, 5722 IN UINT32 Value 5723 ); 5724 5725 /** 5726 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the 5727 result back to the bit field in the 64-bit MSR. 5728 5729 Reads the 64-bit MSR specified by Index, performs a bitwise OR 5730 between the read result and the value specified by OrData, and writes the 5731 result to the 64-bit MSR specified by Index. The lower 32-bits of the value 5732 written to the MSR are returned. Extra left bits in OrData are stripped. The 5733 caller must either guarantee that Index and the data written is valid, or 5734 the caller must set up exception handlers to catch the exceptions. This 5735 function is only available on IA-32 and x64. 5736 5737 If StartBit is greater than 31, then ASSERT(). 5738 If EndBit is greater than 31, then ASSERT(). 5739 If EndBit is less than StartBit, then ASSERT(). 5740 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 5741 5742 @param Index The 32-bit MSR index to write. 5743 @param StartBit The ordinal of the least significant bit in the bit field. 5744 Range 0..31. 5745 @param EndBit The ordinal of the most significant bit in the bit field. 5746 Range 0..31. 5747 @param OrData The value to OR with the read value from the MSR. 5748 5749 @return The lower 32-bit of the value written to the MSR. 5750 5751 **/ 5752 UINT32 5753 EFIAPI 5754 AsmMsrBitFieldOr32 ( 5755 IN UINT32 Index, 5756 IN UINTN StartBit, 5757 IN UINTN EndBit, 5758 IN UINT32 OrData 5759 ); 5760 5761 /** 5762 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the 5763 result back to the bit field in the 64-bit MSR. 5764 5765 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the 5766 read result and the value specified by AndData, and writes the result to the 5767 64-bit MSR specified by Index. The lower 32-bits of the value written to the 5768 MSR are returned. Extra left bits in AndData are stripped. The caller must 5769 either guarantee that Index and the data written is valid, or the caller must 5770 set up exception handlers to catch the exceptions. This function is only 5771 available on IA-32 and x64. 5772 5773 If StartBit is greater than 31, then ASSERT(). 5774 If EndBit is greater than 31, then ASSERT(). 5775 If EndBit is less than StartBit, then ASSERT(). 5776 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 5777 5778 @param Index The 32-bit MSR index to write. 5779 @param StartBit The ordinal of the least significant bit in the bit field. 5780 Range 0..31. 5781 @param EndBit The ordinal of the most significant bit in the bit field. 5782 Range 0..31. 5783 @param AndData The value to AND with the read value from the MSR. 5784 5785 @return The lower 32-bit of the value written to the MSR. 5786 5787 **/ 5788 UINT32 5789 EFIAPI 5790 AsmMsrBitFieldAnd32 ( 5791 IN UINT32 Index, 5792 IN UINTN StartBit, 5793 IN UINTN EndBit, 5794 IN UINT32 AndData 5795 ); 5796 5797 /** 5798 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a 5799 bitwise OR, and writes the result back to the bit field in the 5800 64-bit MSR. 5801 5802 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a 5803 bitwise OR between the read result and the value specified by 5804 AndData, and writes the result to the 64-bit MSR specified by Index. The 5805 lower 32-bits of the value written to the MSR are returned. Extra left bits 5806 in both AndData and OrData are stripped. The caller must either guarantee 5807 that Index and the data written is valid, or the caller must set up exception 5808 handlers to catch the exceptions. This function is only available on IA-32 5809 and x64. 5810 5811 If StartBit is greater than 31, then ASSERT(). 5812 If EndBit is greater than 31, then ASSERT(). 5813 If EndBit is less than StartBit, then ASSERT(). 5814 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 5815 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 5816 5817 @param Index The 32-bit MSR index to write. 5818 @param StartBit The ordinal of the least significant bit in the bit field. 5819 Range 0..31. 5820 @param EndBit The ordinal of the most significant bit in the bit field. 5821 Range 0..31. 5822 @param AndData The value to AND with the read value from the MSR. 5823 @param OrData The value to OR with the result of the AND operation. 5824 5825 @return The lower 32-bit of the value written to the MSR. 5826 5827 **/ 5828 UINT32 5829 EFIAPI 5830 AsmMsrBitFieldAndThenOr32 ( 5831 IN UINT32 Index, 5832 IN UINTN StartBit, 5833 IN UINTN EndBit, 5834 IN UINT32 AndData, 5835 IN UINT32 OrData 5836 ); 5837 5838 /** 5839 Returns a 64-bit Machine Specific Register(MSR). 5840 5841 Reads and returns the 64-bit MSR specified by Index. No parameter checking is 5842 performed on Index, and some Index values may cause CPU exceptions. The 5843 caller must either guarantee that Index is valid, or the caller must set up 5844 exception handlers to catch the exceptions. This function is only available 5845 on IA-32 and x64. 5846 5847 @param Index The 32-bit MSR index to read. 5848 5849 @return The value of the MSR identified by Index. 5850 5851 **/ 5852 UINT64 5853 EFIAPI 5854 AsmReadMsr64 ( 5855 IN UINT32 Index 5856 ); 5857 5858 /** 5859 Writes a 64-bit value to a Machine Specific Register(MSR), and returns the 5860 value. 5861 5862 Writes the 64-bit value specified by Value to the MSR specified by Index. The 5863 64-bit value written to the MSR is returned. No parameter checking is 5864 performed on Index or Value, and some of these may cause CPU exceptions. The 5865 caller must either guarantee that Index and Value are valid, or the caller 5866 must establish proper exception handlers. This function is only available on 5867 IA-32 and x64. 5868 5869 @param Index The 32-bit MSR index to write. 5870 @param Value The 64-bit value to write to the MSR. 5871 5872 @return Value 5873 5874 **/ 5875 UINT64 5876 EFIAPI 5877 AsmWriteMsr64 ( 5878 IN UINT32 Index, 5879 IN UINT64 Value 5880 ); 5881 5882 /** 5883 Reads a 64-bit MSR, performs a bitwise OR, and writes the result 5884 back to the 64-bit MSR. 5885 5886 Reads the 64-bit MSR specified by Index, performs a bitwise OR 5887 between the read result and the value specified by OrData, and writes the 5888 result to the 64-bit MSR specified by Index. The value written to the MSR is 5889 returned. No parameter checking is performed on Index or OrData, and some of 5890 these may cause CPU exceptions. The caller must either guarantee that Index 5891 and OrData are valid, or the caller must establish proper exception handlers. 5892 This function is only available on IA-32 and x64. 5893 5894 @param Index The 32-bit MSR index to write. 5895 @param OrData The value to OR with the read value from the MSR. 5896 5897 @return The value written back to the MSR. 5898 5899 **/ 5900 UINT64 5901 EFIAPI 5902 AsmMsrOr64 ( 5903 IN UINT32 Index, 5904 IN UINT64 OrData 5905 ); 5906 5907 /** 5908 Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the 5909 64-bit MSR. 5910 5911 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the 5912 read result and the value specified by OrData, and writes the result to the 5913 64-bit MSR specified by Index. The value written to the MSR is returned. No 5914 parameter checking is performed on Index or OrData, and some of these may 5915 cause CPU exceptions. The caller must either guarantee that Index and OrData 5916 are valid, or the caller must establish proper exception handlers. This 5917 function is only available on IA-32 and x64. 5918 5919 @param Index The 32-bit MSR index to write. 5920 @param AndData The value to AND with the read value from the MSR. 5921 5922 @return The value written back to the MSR. 5923 5924 **/ 5925 UINT64 5926 EFIAPI 5927 AsmMsrAnd64 ( 5928 IN UINT32 Index, 5929 IN UINT64 AndData 5930 ); 5931 5932 /** 5933 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise 5934 OR, and writes the result back to the 64-bit MSR. 5935 5936 Reads the 64-bit MSR specified by Index, performs a bitwise AND between read 5937 result and the value specified by AndData, performs a bitwise OR 5938 between the result of the AND operation and the value specified by OrData, 5939 and writes the result to the 64-bit MSR specified by Index. The value written 5940 to the MSR is returned. No parameter checking is performed on Index, AndData, 5941 or OrData, and some of these may cause CPU exceptions. The caller must either 5942 guarantee that Index, AndData, and OrData are valid, or the caller must 5943 establish proper exception handlers. This function is only available on IA-32 5944 and x64. 5945 5946 @param Index The 32-bit MSR index to write. 5947 @param AndData The value to AND with the read value from the MSR. 5948 @param OrData The value to OR with the result of the AND operation. 5949 5950 @return The value written back to the MSR. 5951 5952 **/ 5953 UINT64 5954 EFIAPI 5955 AsmMsrAndThenOr64 ( 5956 IN UINT32 Index, 5957 IN UINT64 AndData, 5958 IN UINT64 OrData 5959 ); 5960 5961 /** 5962 Reads a bit field of an MSR. 5963 5964 Reads the bit field in the 64-bit MSR. The bit field is specified by the 5965 StartBit and the EndBit. The value of the bit field is returned. The caller 5966 must either guarantee that Index is valid, or the caller must set up 5967 exception handlers to catch the exceptions. This function is only available 5968 on IA-32 and x64. 5969 5970 If StartBit is greater than 63, then ASSERT(). 5971 If EndBit is greater than 63, then ASSERT(). 5972 If EndBit is less than StartBit, then ASSERT(). 5973 5974 @param Index The 32-bit MSR index to read. 5975 @param StartBit The ordinal of the least significant bit in the bit field. 5976 Range 0..63. 5977 @param EndBit The ordinal of the most significant bit in the bit field. 5978 Range 0..63. 5979 5980 @return The value read from the MSR. 5981 5982 **/ 5983 UINT64 5984 EFIAPI 5985 AsmMsrBitFieldRead64 ( 5986 IN UINT32 Index, 5987 IN UINTN StartBit, 5988 IN UINTN EndBit 5989 ); 5990 5991 /** 5992 Writes a bit field to an MSR. 5993 5994 Writes Value to a bit field in a 64-bit MSR. The bit field is specified by 5995 the StartBit and the EndBit. All other bits in the destination MSR are 5996 preserved. The MSR written is returned. The caller must either guarantee 5997 that Index and the data written is valid, or the caller must set up exception 5998 handlers to catch the exceptions. This function is only available on IA-32 and x64. 5999 6000 If StartBit is greater than 63, then ASSERT(). 6001 If EndBit is greater than 63, then ASSERT(). 6002 If EndBit is less than StartBit, then ASSERT(). 6003 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 6004 6005 @param Index The 32-bit MSR index to write. 6006 @param StartBit The ordinal of the least significant bit in the bit field. 6007 Range 0..63. 6008 @param EndBit The ordinal of the most significant bit in the bit field. 6009 Range 0..63. 6010 @param Value New value of the bit field. 6011 6012 @return The value written back to the MSR. 6013 6014 **/ 6015 UINT64 6016 EFIAPI 6017 AsmMsrBitFieldWrite64 ( 6018 IN UINT32 Index, 6019 IN UINTN StartBit, 6020 IN UINTN EndBit, 6021 IN UINT64 Value 6022 ); 6023 6024 /** 6025 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and 6026 writes the result back to the bit field in the 64-bit MSR. 6027 6028 Reads the 64-bit MSR specified by Index, performs a bitwise OR 6029 between the read result and the value specified by OrData, and writes the 6030 result to the 64-bit MSR specified by Index. The value written to the MSR is 6031 returned. Extra left bits in OrData are stripped. The caller must either 6032 guarantee that Index and the data written is valid, or the caller must set up 6033 exception handlers to catch the exceptions. This function is only available 6034 on IA-32 and x64. 6035 6036 If StartBit is greater than 63, then ASSERT(). 6037 If EndBit is greater than 63, then ASSERT(). 6038 If EndBit is less than StartBit, then ASSERT(). 6039 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 6040 6041 @param Index The 32-bit MSR index to write. 6042 @param StartBit The ordinal of the least significant bit in the bit field. 6043 Range 0..63. 6044 @param EndBit The ordinal of the most significant bit in the bit field. 6045 Range 0..63. 6046 @param OrData The value to OR with the read value from the bit field. 6047 6048 @return The value written back to the MSR. 6049 6050 **/ 6051 UINT64 6052 EFIAPI 6053 AsmMsrBitFieldOr64 ( 6054 IN UINT32 Index, 6055 IN UINTN StartBit, 6056 IN UINTN EndBit, 6057 IN UINT64 OrData 6058 ); 6059 6060 /** 6061 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the 6062 result back to the bit field in the 64-bit MSR. 6063 6064 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the 6065 read result and the value specified by AndData, and writes the result to the 6066 64-bit MSR specified by Index. The value written to the MSR is returned. 6067 Extra left bits in AndData are stripped. The caller must either guarantee 6068 that Index and the data written is valid, or the caller must set up exception 6069 handlers to catch the exceptions. This function is only available on IA-32 6070 and x64. 6071 6072 If StartBit is greater than 63, then ASSERT(). 6073 If EndBit is greater than 63, then ASSERT(). 6074 If EndBit is less than StartBit, then ASSERT(). 6075 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 6076 6077 @param Index The 32-bit MSR index to write. 6078 @param StartBit The ordinal of the least significant bit in the bit field. 6079 Range 0..63. 6080 @param EndBit The ordinal of the most significant bit in the bit field. 6081 Range 0..63. 6082 @param AndData The value to AND with the read value from the bit field. 6083 6084 @return The value written back to the MSR. 6085 6086 **/ 6087 UINT64 6088 EFIAPI 6089 AsmMsrBitFieldAnd64 ( 6090 IN UINT32 Index, 6091 IN UINTN StartBit, 6092 IN UINTN EndBit, 6093 IN UINT64 AndData 6094 ); 6095 6096 /** 6097 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a 6098 bitwise OR, and writes the result back to the bit field in the 6099 64-bit MSR. 6100 6101 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by 6102 a bitwise OR between the read result and the value specified by 6103 AndData, and writes the result to the 64-bit MSR specified by Index. The 6104 value written to the MSR is returned. Extra left bits in both AndData and 6105 OrData are stripped. The caller must either guarantee that Index and the data 6106 written is valid, or the caller must set up exception handlers to catch the 6107 exceptions. This function is only available on IA-32 and x64. 6108 6109 If StartBit is greater than 63, then ASSERT(). 6110 If EndBit is greater than 63, then ASSERT(). 6111 If EndBit is less than StartBit, then ASSERT(). 6112 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 6113 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). 6114 6115 @param Index The 32-bit MSR index to write. 6116 @param StartBit The ordinal of the least significant bit in the bit field. 6117 Range 0..63. 6118 @param EndBit The ordinal of the most significant bit in the bit field. 6119 Range 0..63. 6120 @param AndData The value to AND with the read value from the bit field. 6121 @param OrData The value to OR with the result of the AND operation. 6122 6123 @return The value written back to the MSR. 6124 6125 **/ 6126 UINT64 6127 EFIAPI 6128 AsmMsrBitFieldAndThenOr64 ( 6129 IN UINT32 Index, 6130 IN UINTN StartBit, 6131 IN UINTN EndBit, 6132 IN UINT64 AndData, 6133 IN UINT64 OrData 6134 ); 6135 6136 /** 6137 Reads the current value of the EFLAGS register. 6138 6139 Reads and returns the current value of the EFLAGS register. This function is 6140 only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a 6141 64-bit value on x64. 6142 6143 @return EFLAGS on IA-32 or RFLAGS on x64. 6144 6145 **/ 6146 UINTN 6147 EFIAPI 6148 AsmReadEflags ( 6149 VOID 6150 ); 6151 6152 /** 6153 Reads the current value of the Control Register 0 (CR0). 6154 6155 Reads and returns the current value of CR0. This function is only available 6156 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6157 x64. 6158 6159 @return The value of the Control Register 0 (CR0). 6160 6161 **/ 6162 UINTN 6163 EFIAPI 6164 AsmReadCr0 ( 6165 VOID 6166 ); 6167 6168 /** 6169 Reads the current value of the Control Register 2 (CR2). 6170 6171 Reads and returns the current value of CR2. This function is only available 6172 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6173 x64. 6174 6175 @return The value of the Control Register 2 (CR2). 6176 6177 **/ 6178 UINTN 6179 EFIAPI 6180 AsmReadCr2 ( 6181 VOID 6182 ); 6183 6184 /** 6185 Reads the current value of the Control Register 3 (CR3). 6186 6187 Reads and returns the current value of CR3. This function is only available 6188 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6189 x64. 6190 6191 @return The value of the Control Register 3 (CR3). 6192 6193 **/ 6194 UINTN 6195 EFIAPI 6196 AsmReadCr3 ( 6197 VOID 6198 ); 6199 6200 /** 6201 Reads the current value of the Control Register 4 (CR4). 6202 6203 Reads and returns the current value of CR4. This function is only available 6204 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6205 x64. 6206 6207 @return The value of the Control Register 4 (CR4). 6208 6209 **/ 6210 UINTN 6211 EFIAPI 6212 AsmReadCr4 ( 6213 VOID 6214 ); 6215 6216 /** 6217 Writes a value to Control Register 0 (CR0). 6218 6219 Writes and returns a new value to CR0. This function is only available on 6220 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6221 6222 @param Cr0 The value to write to CR0. 6223 6224 @return The value written to CR0. 6225 6226 **/ 6227 UINTN 6228 EFIAPI 6229 AsmWriteCr0 ( 6230 UINTN Cr0 6231 ); 6232 6233 /** 6234 Writes a value to Control Register 2 (CR2). 6235 6236 Writes and returns a new value to CR2. This function is only available on 6237 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6238 6239 @param Cr2 The value to write to CR2. 6240 6241 @return The value written to CR2. 6242 6243 **/ 6244 UINTN 6245 EFIAPI 6246 AsmWriteCr2 ( 6247 UINTN Cr2 6248 ); 6249 6250 /** 6251 Writes a value to Control Register 3 (CR3). 6252 6253 Writes and returns a new value to CR3. This function is only available on 6254 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6255 6256 @param Cr3 The value to write to CR3. 6257 6258 @return The value written to CR3. 6259 6260 **/ 6261 UINTN 6262 EFIAPI 6263 AsmWriteCr3 ( 6264 UINTN Cr3 6265 ); 6266 6267 /** 6268 Writes a value to Control Register 4 (CR4). 6269 6270 Writes and returns a new value to CR4. This function is only available on 6271 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6272 6273 @param Cr4 The value to write to CR4. 6274 6275 @return The value written to CR4. 6276 6277 **/ 6278 UINTN 6279 EFIAPI 6280 AsmWriteCr4 ( 6281 UINTN Cr4 6282 ); 6283 6284 /** 6285 Reads the current value of Debug Register 0 (DR0). 6286 6287 Reads and returns the current value of DR0. This function is only available 6288 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6289 x64. 6290 6291 @return The value of Debug Register 0 (DR0). 6292 6293 **/ 6294 UINTN 6295 EFIAPI 6296 AsmReadDr0 ( 6297 VOID 6298 ); 6299 6300 /** 6301 Reads the current value of Debug Register 1 (DR1). 6302 6303 Reads and returns the current value of DR1. This function is only available 6304 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6305 x64. 6306 6307 @return The value of Debug Register 1 (DR1). 6308 6309 **/ 6310 UINTN 6311 EFIAPI 6312 AsmReadDr1 ( 6313 VOID 6314 ); 6315 6316 /** 6317 Reads the current value of Debug Register 2 (DR2). 6318 6319 Reads and returns the current value of DR2. This function is only available 6320 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6321 x64. 6322 6323 @return The value of Debug Register 2 (DR2). 6324 6325 **/ 6326 UINTN 6327 EFIAPI 6328 AsmReadDr2 ( 6329 VOID 6330 ); 6331 6332 /** 6333 Reads the current value of Debug Register 3 (DR3). 6334 6335 Reads and returns the current value of DR3. This function is only available 6336 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6337 x64. 6338 6339 @return The value of Debug Register 3 (DR3). 6340 6341 **/ 6342 UINTN 6343 EFIAPI 6344 AsmReadDr3 ( 6345 VOID 6346 ); 6347 6348 /** 6349 Reads the current value of Debug Register 4 (DR4). 6350 6351 Reads and returns the current value of DR4. This function is only available 6352 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6353 x64. 6354 6355 @return The value of Debug Register 4 (DR4). 6356 6357 **/ 6358 UINTN 6359 EFIAPI 6360 AsmReadDr4 ( 6361 VOID 6362 ); 6363 6364 /** 6365 Reads the current value of Debug Register 5 (DR5). 6366 6367 Reads and returns the current value of DR5. This function is only available 6368 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6369 x64. 6370 6371 @return The value of Debug Register 5 (DR5). 6372 6373 **/ 6374 UINTN 6375 EFIAPI 6376 AsmReadDr5 ( 6377 VOID 6378 ); 6379 6380 /** 6381 Reads the current value of Debug Register 6 (DR6). 6382 6383 Reads and returns the current value of DR6. This function is only available 6384 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6385 x64. 6386 6387 @return The value of Debug Register 6 (DR6). 6388 6389 **/ 6390 UINTN 6391 EFIAPI 6392 AsmReadDr6 ( 6393 VOID 6394 ); 6395 6396 /** 6397 Reads the current value of Debug Register 7 (DR7). 6398 6399 Reads and returns the current value of DR7. This function is only available 6400 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on 6401 x64. 6402 6403 @return The value of Debug Register 7 (DR7). 6404 6405 **/ 6406 UINTN 6407 EFIAPI 6408 AsmReadDr7 ( 6409 VOID 6410 ); 6411 6412 /** 6413 Writes a value to Debug Register 0 (DR0). 6414 6415 Writes and returns a new value to DR0. This function is only available on 6416 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6417 6418 @param Dr0 The value to write to Dr0. 6419 6420 @return The value written to Debug Register 0 (DR0). 6421 6422 **/ 6423 UINTN 6424 EFIAPI 6425 AsmWriteDr0 ( 6426 UINTN Dr0 6427 ); 6428 6429 /** 6430 Writes a value to Debug Register 1 (DR1). 6431 6432 Writes and returns a new value to DR1. This function is only available on 6433 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6434 6435 @param Dr1 The value to write to Dr1. 6436 6437 @return The value written to Debug Register 1 (DR1). 6438 6439 **/ 6440 UINTN 6441 EFIAPI 6442 AsmWriteDr1 ( 6443 UINTN Dr1 6444 ); 6445 6446 /** 6447 Writes a value to Debug Register 2 (DR2). 6448 6449 Writes and returns a new value to DR2. This function is only available on 6450 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6451 6452 @param Dr2 The value to write to Dr2. 6453 6454 @return The value written to Debug Register 2 (DR2). 6455 6456 **/ 6457 UINTN 6458 EFIAPI 6459 AsmWriteDr2 ( 6460 UINTN Dr2 6461 ); 6462 6463 /** 6464 Writes a value to Debug Register 3 (DR3). 6465 6466 Writes and returns a new value to DR3. This function is only available on 6467 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6468 6469 @param Dr3 The value to write to Dr3. 6470 6471 @return The value written to Debug Register 3 (DR3). 6472 6473 **/ 6474 UINTN 6475 EFIAPI 6476 AsmWriteDr3 ( 6477 UINTN Dr3 6478 ); 6479 6480 /** 6481 Writes a value to Debug Register 4 (DR4). 6482 6483 Writes and returns a new value to DR4. This function is only available on 6484 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6485 6486 @param Dr4 The value to write to Dr4. 6487 6488 @return The value written to Debug Register 4 (DR4). 6489 6490 **/ 6491 UINTN 6492 EFIAPI 6493 AsmWriteDr4 ( 6494 UINTN Dr4 6495 ); 6496 6497 /** 6498 Writes a value to Debug Register 5 (DR5). 6499 6500 Writes and returns a new value to DR5. This function is only available on 6501 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6502 6503 @param Dr5 The value to write to Dr5. 6504 6505 @return The value written to Debug Register 5 (DR5). 6506 6507 **/ 6508 UINTN 6509 EFIAPI 6510 AsmWriteDr5 ( 6511 UINTN Dr5 6512 ); 6513 6514 /** 6515 Writes a value to Debug Register 6 (DR6). 6516 6517 Writes and returns a new value to DR6. This function is only available on 6518 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6519 6520 @param Dr6 The value to write to Dr6. 6521 6522 @return The value written to Debug Register 6 (DR6). 6523 6524 **/ 6525 UINTN 6526 EFIAPI 6527 AsmWriteDr6 ( 6528 UINTN Dr6 6529 ); 6530 6531 /** 6532 Writes a value to Debug Register 7 (DR7). 6533 6534 Writes and returns a new value to DR7. This function is only available on 6535 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64. 6536 6537 @param Dr7 The value to write to Dr7. 6538 6539 @return The value written to Debug Register 7 (DR7). 6540 6541 **/ 6542 UINTN 6543 EFIAPI 6544 AsmWriteDr7 ( 6545 UINTN Dr7 6546 ); 6547 6548 /** 6549 Reads the current value of Code Segment Register (CS). 6550 6551 Reads and returns the current value of CS. This function is only available on 6552 IA-32 and x64. 6553 6554 @return The current value of CS. 6555 6556 **/ 6557 UINT16 6558 EFIAPI 6559 AsmReadCs ( 6560 VOID 6561 ); 6562 6563 /** 6564 Reads the current value of Data Segment Register (DS). 6565 6566 Reads and returns the current value of DS. This function is only available on 6567 IA-32 and x64. 6568 6569 @return The current value of DS. 6570 6571 **/ 6572 UINT16 6573 EFIAPI 6574 AsmReadDs ( 6575 VOID 6576 ); 6577 6578 /** 6579 Reads the current value of Extra Segment Register (ES). 6580 6581 Reads and returns the current value of ES. This function is only available on 6582 IA-32 and x64. 6583 6584 @return The current value of ES. 6585 6586 **/ 6587 UINT16 6588 EFIAPI 6589 AsmReadEs ( 6590 VOID 6591 ); 6592 6593 /** 6594 Reads the current value of FS Data Segment Register (FS). 6595 6596 Reads and returns the current value of FS. This function is only available on 6597 IA-32 and x64. 6598 6599 @return The current value of FS. 6600 6601 **/ 6602 UINT16 6603 EFIAPI 6604 AsmReadFs ( 6605 VOID 6606 ); 6607 6608 /** 6609 Reads the current value of GS Data Segment Register (GS). 6610 6611 Reads and returns the current value of GS. This function is only available on 6612 IA-32 and x64. 6613 6614 @return The current value of GS. 6615 6616 **/ 6617 UINT16 6618 EFIAPI 6619 AsmReadGs ( 6620 VOID 6621 ); 6622 6623 /** 6624 Reads the current value of Stack Segment Register (SS). 6625 6626 Reads and returns the current value of SS. This function is only available on 6627 IA-32 and x64. 6628 6629 @return The current value of SS. 6630 6631 **/ 6632 UINT16 6633 EFIAPI 6634 AsmReadSs ( 6635 VOID 6636 ); 6637 6638 /** 6639 Reads the current value of Task Register (TR). 6640 6641 Reads and returns the current value of TR. This function is only available on 6642 IA-32 and x64. 6643 6644 @return The current value of TR. 6645 6646 **/ 6647 UINT16 6648 EFIAPI 6649 AsmReadTr ( 6650 VOID 6651 ); 6652 6653 /** 6654 Reads the current Global Descriptor Table Register(GDTR) descriptor. 6655 6656 Reads and returns the current GDTR descriptor and returns it in Gdtr. This 6657 function is only available on IA-32 and x64. 6658 6659 If Gdtr is NULL, then ASSERT(). 6660 6661 @param Gdtr The pointer to a GDTR descriptor. 6662 6663 **/ 6664 VOID 6665 EFIAPI 6666 AsmReadGdtr ( 6667 OUT IA32_DESCRIPTOR *Gdtr 6668 ); 6669 6670 /** 6671 Writes the current Global Descriptor Table Register (GDTR) descriptor. 6672 6673 Writes and the current GDTR descriptor specified by Gdtr. This function is 6674 only available on IA-32 and x64. 6675 6676 If Gdtr is NULL, then ASSERT(). 6677 6678 @param Gdtr The pointer to a GDTR descriptor. 6679 6680 **/ 6681 VOID 6682 EFIAPI 6683 AsmWriteGdtr ( 6684 IN CONST IA32_DESCRIPTOR *Gdtr 6685 ); 6686 6687 /** 6688 Reads the current Interrupt Descriptor Table Register(IDTR) descriptor. 6689 6690 Reads and returns the current IDTR descriptor and returns it in Idtr. This 6691 function is only available on IA-32 and x64. 6692 6693 If Idtr is NULL, then ASSERT(). 6694 6695 @param Idtr The pointer to a IDTR descriptor. 6696 6697 **/ 6698 VOID 6699 EFIAPI 6700 AsmReadIdtr ( 6701 OUT IA32_DESCRIPTOR *Idtr 6702 ); 6703 6704 /** 6705 Writes the current Interrupt Descriptor Table Register(IDTR) descriptor. 6706 6707 Writes the current IDTR descriptor and returns it in Idtr. This function is 6708 only available on IA-32 and x64. 6709 6710 If Idtr is NULL, then ASSERT(). 6711 6712 @param Idtr The pointer to a IDTR descriptor. 6713 6714 **/ 6715 VOID 6716 EFIAPI 6717 AsmWriteIdtr ( 6718 IN CONST IA32_DESCRIPTOR *Idtr 6719 ); 6720 6721 /** 6722 Reads the current Local Descriptor Table Register(LDTR) selector. 6723 6724 Reads and returns the current 16-bit LDTR descriptor value. This function is 6725 only available on IA-32 and x64. 6726 6727 @return The current selector of LDT. 6728 6729 **/ 6730 UINT16 6731 EFIAPI 6732 AsmReadLdtr ( 6733 VOID 6734 ); 6735 6736 /** 6737 Writes the current Local Descriptor Table Register (LDTR) selector. 6738 6739 Writes and the current LDTR descriptor specified by Ldtr. This function is 6740 only available on IA-32 and x64. 6741 6742 @param Ldtr 16-bit LDTR selector value. 6743 6744 **/ 6745 VOID 6746 EFIAPI 6747 AsmWriteLdtr ( 6748 IN UINT16 Ldtr 6749 ); 6750 6751 /** 6752 Save the current floating point/SSE/SSE2 context to a buffer. 6753 6754 Saves the current floating point/SSE/SSE2 state to the buffer specified by 6755 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only 6756 available on IA-32 and x64. 6757 6758 If Buffer is NULL, then ASSERT(). 6759 If Buffer is not aligned on a 16-byte boundary, then ASSERT(). 6760 6761 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context. 6762 6763 **/ 6764 VOID 6765 EFIAPI 6766 AsmFxSave ( 6767 OUT IA32_FX_BUFFER *Buffer 6768 ); 6769 6770 /** 6771 Restores the current floating point/SSE/SSE2 context from a buffer. 6772 6773 Restores the current floating point/SSE/SSE2 state from the buffer specified 6774 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is 6775 only available on IA-32 and x64. 6776 6777 If Buffer is NULL, then ASSERT(). 6778 If Buffer is not aligned on a 16-byte boundary, then ASSERT(). 6779 If Buffer was not saved with AsmFxSave(), then ASSERT(). 6780 6781 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context. 6782 6783 **/ 6784 VOID 6785 EFIAPI 6786 AsmFxRestore ( 6787 IN CONST IA32_FX_BUFFER *Buffer 6788 ); 6789 6790 /** 6791 Reads the current value of 64-bit MMX Register #0 (MM0). 6792 6793 Reads and returns the current value of MM0. This function is only available 6794 on IA-32 and x64. 6795 6796 @return The current value of MM0. 6797 6798 **/ 6799 UINT64 6800 EFIAPI 6801 AsmReadMm0 ( 6802 VOID 6803 ); 6804 6805 /** 6806 Reads the current value of 64-bit MMX Register #1 (MM1). 6807 6808 Reads and returns the current value of MM1. This function is only available 6809 on IA-32 and x64. 6810 6811 @return The current value of MM1. 6812 6813 **/ 6814 UINT64 6815 EFIAPI 6816 AsmReadMm1 ( 6817 VOID 6818 ); 6819 6820 /** 6821 Reads the current value of 64-bit MMX Register #2 (MM2). 6822 6823 Reads and returns the current value of MM2. This function is only available 6824 on IA-32 and x64. 6825 6826 @return The current value of MM2. 6827 6828 **/ 6829 UINT64 6830 EFIAPI 6831 AsmReadMm2 ( 6832 VOID 6833 ); 6834 6835 /** 6836 Reads the current value of 64-bit MMX Register #3 (MM3). 6837 6838 Reads and returns the current value of MM3. This function is only available 6839 on IA-32 and x64. 6840 6841 @return The current value of MM3. 6842 6843 **/ 6844 UINT64 6845 EFIAPI 6846 AsmReadMm3 ( 6847 VOID 6848 ); 6849 6850 /** 6851 Reads the current value of 64-bit MMX Register #4 (MM4). 6852 6853 Reads and returns the current value of MM4. This function is only available 6854 on IA-32 and x64. 6855 6856 @return The current value of MM4. 6857 6858 **/ 6859 UINT64 6860 EFIAPI 6861 AsmReadMm4 ( 6862 VOID 6863 ); 6864 6865 /** 6866 Reads the current value of 64-bit MMX Register #5 (MM5). 6867 6868 Reads and returns the current value of MM5. This function is only available 6869 on IA-32 and x64. 6870 6871 @return The current value of MM5. 6872 6873 **/ 6874 UINT64 6875 EFIAPI 6876 AsmReadMm5 ( 6877 VOID 6878 ); 6879 6880 /** 6881 Reads the current value of 64-bit MMX Register #6 (MM6). 6882 6883 Reads and returns the current value of MM6. This function is only available 6884 on IA-32 and x64. 6885 6886 @return The current value of MM6. 6887 6888 **/ 6889 UINT64 6890 EFIAPI 6891 AsmReadMm6 ( 6892 VOID 6893 ); 6894 6895 /** 6896 Reads the current value of 64-bit MMX Register #7 (MM7). 6897 6898 Reads and returns the current value of MM7. This function is only available 6899 on IA-32 and x64. 6900 6901 @return The current value of MM7. 6902 6903 **/ 6904 UINT64 6905 EFIAPI 6906 AsmReadMm7 ( 6907 VOID 6908 ); 6909 6910 /** 6911 Writes the current value of 64-bit MMX Register #0 (MM0). 6912 6913 Writes the current value of MM0. This function is only available on IA32 and 6914 x64. 6915 6916 @param Value The 64-bit value to write to MM0. 6917 6918 **/ 6919 VOID 6920 EFIAPI 6921 AsmWriteMm0 ( 6922 IN UINT64 Value 6923 ); 6924 6925 /** 6926 Writes the current value of 64-bit MMX Register #1 (MM1). 6927 6928 Writes the current value of MM1. This function is only available on IA32 and 6929 x64. 6930 6931 @param Value The 64-bit value to write to MM1. 6932 6933 **/ 6934 VOID 6935 EFIAPI 6936 AsmWriteMm1 ( 6937 IN UINT64 Value 6938 ); 6939 6940 /** 6941 Writes the current value of 64-bit MMX Register #2 (MM2). 6942 6943 Writes the current value of MM2. This function is only available on IA32 and 6944 x64. 6945 6946 @param Value The 64-bit value to write to MM2. 6947 6948 **/ 6949 VOID 6950 EFIAPI 6951 AsmWriteMm2 ( 6952 IN UINT64 Value 6953 ); 6954 6955 /** 6956 Writes the current value of 64-bit MMX Register #3 (MM3). 6957 6958 Writes the current value of MM3. This function is only available on IA32 and 6959 x64. 6960 6961 @param Value The 64-bit value to write to MM3. 6962 6963 **/ 6964 VOID 6965 EFIAPI 6966 AsmWriteMm3 ( 6967 IN UINT64 Value 6968 ); 6969 6970 /** 6971 Writes the current value of 64-bit MMX Register #4 (MM4). 6972 6973 Writes the current value of MM4. This function is only available on IA32 and 6974 x64. 6975 6976 @param Value The 64-bit value to write to MM4. 6977 6978 **/ 6979 VOID 6980 EFIAPI 6981 AsmWriteMm4 ( 6982 IN UINT64 Value 6983 ); 6984 6985 /** 6986 Writes the current value of 64-bit MMX Register #5 (MM5). 6987 6988 Writes the current value of MM5. This function is only available on IA32 and 6989 x64. 6990 6991 @param Value The 64-bit value to write to MM5. 6992 6993 **/ 6994 VOID 6995 EFIAPI 6996 AsmWriteMm5 ( 6997 IN UINT64 Value 6998 ); 6999 7000 /** 7001 Writes the current value of 64-bit MMX Register #6 (MM6). 7002 7003 Writes the current value of MM6. This function is only available on IA32 and 7004 x64. 7005 7006 @param Value The 64-bit value to write to MM6. 7007 7008 **/ 7009 VOID 7010 EFIAPI 7011 AsmWriteMm6 ( 7012 IN UINT64 Value 7013 ); 7014 7015 /** 7016 Writes the current value of 64-bit MMX Register #7 (MM7). 7017 7018 Writes the current value of MM7. This function is only available on IA32 and 7019 x64. 7020 7021 @param Value The 64-bit value to write to MM7. 7022 7023 **/ 7024 VOID 7025 EFIAPI 7026 AsmWriteMm7 ( 7027 IN UINT64 Value 7028 ); 7029 7030 /** 7031 Reads the current value of Time Stamp Counter (TSC). 7032 7033 Reads and returns the current value of TSC. This function is only available 7034 on IA-32 and x64. 7035 7036 @return The current value of TSC 7037 7038 **/ 7039 UINT64 7040 EFIAPI 7041 AsmReadTsc ( 7042 VOID 7043 ); 7044 7045 /** 7046 Reads the current value of a Performance Counter (PMC). 7047 7048 Reads and returns the current value of performance counter specified by 7049 Index. This function is only available on IA-32 and x64. 7050 7051 @param Index The 32-bit Performance Counter index to read. 7052 7053 @return The value of the PMC specified by Index. 7054 7055 **/ 7056 UINT64 7057 EFIAPI 7058 AsmReadPmc ( 7059 IN UINT32 Index 7060 ); 7061 7062 /** 7063 Sets up a monitor buffer that is used by AsmMwait(). 7064 7065 Executes a MONITOR instruction with the register state specified by Eax, Ecx 7066 and Edx. Returns Eax. This function is only available on IA-32 and x64. 7067 7068 @param Eax The value to load into EAX or RAX before executing the MONITOR 7069 instruction. 7070 @param Ecx The value to load into ECX or RCX before executing the MONITOR 7071 instruction. 7072 @param Edx The value to load into EDX or RDX before executing the MONITOR 7073 instruction. 7074 7075 @return Eax 7076 7077 **/ 7078 UINTN 7079 EFIAPI 7080 AsmMonitor ( 7081 IN UINTN Eax, 7082 IN UINTN Ecx, 7083 IN UINTN Edx 7084 ); 7085 7086 /** 7087 Executes an MWAIT instruction. 7088 7089 Executes an MWAIT instruction with the register state specified by Eax and 7090 Ecx. Returns Eax. This function is only available on IA-32 and x64. 7091 7092 @param Eax The value to load into EAX or RAX before executing the MONITOR 7093 instruction. 7094 @param Ecx The value to load into ECX or RCX before executing the MONITOR 7095 instruction. 7096 7097 @return Eax 7098 7099 **/ 7100 UINTN 7101 EFIAPI 7102 AsmMwait ( 7103 IN UINTN Eax, 7104 IN UINTN Ecx 7105 ); 7106 7107 /** 7108 Executes a WBINVD instruction. 7109 7110 Executes a WBINVD instruction. This function is only available on IA-32 and 7111 x64. 7112 7113 **/ 7114 VOID 7115 EFIAPI 7116 AsmWbinvd ( 7117 VOID 7118 ); 7119 7120 /** 7121 Executes a INVD instruction. 7122 7123 Executes a INVD instruction. This function is only available on IA-32 and 7124 x64. 7125 7126 **/ 7127 VOID 7128 EFIAPI 7129 AsmInvd ( 7130 VOID 7131 ); 7132 7133 /** 7134 Flushes a cache line from all the instruction and data caches within the 7135 coherency domain of the CPU. 7136 7137 Flushed the cache line specified by LinearAddress, and returns LinearAddress. 7138 This function is only available on IA-32 and x64. 7139 7140 @param LinearAddress The address of the cache line to flush. If the CPU is 7141 in a physical addressing mode, then LinearAddress is a 7142 physical address. If the CPU is in a virtual 7143 addressing mode, then LinearAddress is a virtual 7144 address. 7145 7146 @return LinearAddress. 7147 **/ 7148 VOID * 7149 EFIAPI 7150 AsmFlushCacheLine ( 7151 IN VOID *LinearAddress 7152 ); 7153 7154 /** 7155 Enables the 32-bit paging mode on the CPU. 7156 7157 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables 7158 must be properly initialized prior to calling this service. This function 7159 assumes the current execution mode is 32-bit protected mode. This function is 7160 only available on IA-32. After the 32-bit paging mode is enabled, control is 7161 transferred to the function specified by EntryPoint using the new stack 7162 specified by NewStack and passing in the parameters specified by Context1 and 7163 Context2. Context1 and Context2 are optional and may be NULL. The function 7164 EntryPoint must never return. 7165 7166 If the current execution mode is not 32-bit protected mode, then ASSERT(). 7167 If EntryPoint is NULL, then ASSERT(). 7168 If NewStack is NULL, then ASSERT(). 7169 7170 There are a number of constraints that must be followed before calling this 7171 function: 7172 1) Interrupts must be disabled. 7173 2) The caller must be in 32-bit protected mode with flat descriptors. This 7174 means all descriptors must have a base of 0 and a limit of 4GB. 7175 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat 7176 descriptors. 7177 4) CR3 must point to valid page tables that will be used once the transition 7178 is complete, and those page tables must guarantee that the pages for this 7179 function and the stack are identity mapped. 7180 7181 @param EntryPoint A pointer to function to call with the new stack after 7182 paging is enabled. 7183 @param Context1 A pointer to the context to pass into the EntryPoint 7184 function as the first parameter after paging is enabled. 7185 @param Context2 A pointer to the context to pass into the EntryPoint 7186 function as the second parameter after paging is enabled. 7187 @param NewStack A pointer to the new stack to use for the EntryPoint 7188 function after paging is enabled. 7189 7190 **/ 7191 VOID 7192 EFIAPI 7193 AsmEnablePaging32 ( 7194 IN SWITCH_STACK_ENTRY_POINT EntryPoint, 7195 IN VOID *Context1 OPTIONAL, 7196 IN VOID *Context2 OPTIONAL, 7197 IN VOID *NewStack 7198 ); 7199 7200 /** 7201 Disables the 32-bit paging mode on the CPU. 7202 7203 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected 7204 mode. This function assumes the current execution mode is 32-paged protected 7205 mode. This function is only available on IA-32. After the 32-bit paging mode 7206 is disabled, control is transferred to the function specified by EntryPoint 7207 using the new stack specified by NewStack and passing in the parameters 7208 specified by Context1 and Context2. Context1 and Context2 are optional and 7209 may be NULL. The function EntryPoint must never return. 7210 7211 If the current execution mode is not 32-bit paged mode, then ASSERT(). 7212 If EntryPoint is NULL, then ASSERT(). 7213 If NewStack is NULL, then ASSERT(). 7214 7215 There are a number of constraints that must be followed before calling this 7216 function: 7217 1) Interrupts must be disabled. 7218 2) The caller must be in 32-bit paged mode. 7219 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode. 7220 4) CR3 must point to valid page tables that guarantee that the pages for 7221 this function and the stack are identity mapped. 7222 7223 @param EntryPoint A pointer to function to call with the new stack after 7224 paging is disabled. 7225 @param Context1 A pointer to the context to pass into the EntryPoint 7226 function as the first parameter after paging is disabled. 7227 @param Context2 A pointer to the context to pass into the EntryPoint 7228 function as the second parameter after paging is 7229 disabled. 7230 @param NewStack A pointer to the new stack to use for the EntryPoint 7231 function after paging is disabled. 7232 7233 **/ 7234 VOID 7235 EFIAPI 7236 AsmDisablePaging32 ( 7237 IN SWITCH_STACK_ENTRY_POINT EntryPoint, 7238 IN VOID *Context1 OPTIONAL, 7239 IN VOID *Context2 OPTIONAL, 7240 IN VOID *NewStack 7241 ); 7242 7243 /** 7244 Enables the 64-bit paging mode on the CPU. 7245 7246 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables 7247 must be properly initialized prior to calling this service. This function 7248 assumes the current execution mode is 32-bit protected mode with flat 7249 descriptors. This function is only available on IA-32. After the 64-bit 7250 paging mode is enabled, control is transferred to the function specified by 7251 EntryPoint using the new stack specified by NewStack and passing in the 7252 parameters specified by Context1 and Context2. Context1 and Context2 are 7253 optional and may be 0. The function EntryPoint must never return. 7254 7255 If the current execution mode is not 32-bit protected mode with flat 7256 descriptors, then ASSERT(). 7257 If EntryPoint is 0, then ASSERT(). 7258 If NewStack is 0, then ASSERT(). 7259 7260 @param Cs The 16-bit selector to load in the CS before EntryPoint 7261 is called. The descriptor in the GDT that this selector 7262 references must be setup for long mode. 7263 @param EntryPoint The 64-bit virtual address of the function to call with 7264 the new stack after paging is enabled. 7265 @param Context1 The 64-bit virtual address of the context to pass into 7266 the EntryPoint function as the first parameter after 7267 paging is enabled. 7268 @param Context2 The 64-bit virtual address of the context to pass into 7269 the EntryPoint function as the second parameter after 7270 paging is enabled. 7271 @param NewStack The 64-bit virtual address of the new stack to use for 7272 the EntryPoint function after paging is enabled. 7273 7274 **/ 7275 VOID 7276 EFIAPI 7277 AsmEnablePaging64 ( 7278 IN UINT16 Cs, 7279 IN UINT64 EntryPoint, 7280 IN UINT64 Context1 OPTIONAL, 7281 IN UINT64 Context2 OPTIONAL, 7282 IN UINT64 NewStack 7283 ); 7284 7285 /** 7286 Disables the 64-bit paging mode on the CPU. 7287 7288 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected 7289 mode. This function assumes the current execution mode is 64-paging mode. 7290 This function is only available on x64. After the 64-bit paging mode is 7291 disabled, control is transferred to the function specified by EntryPoint 7292 using the new stack specified by NewStack and passing in the parameters 7293 specified by Context1 and Context2. Context1 and Context2 are optional and 7294 may be 0. The function EntryPoint must never return. 7295 7296 If the current execution mode is not 64-bit paged mode, then ASSERT(). 7297 If EntryPoint is 0, then ASSERT(). 7298 If NewStack is 0, then ASSERT(). 7299 7300 @param Cs The 16-bit selector to load in the CS before EntryPoint 7301 is called. The descriptor in the GDT that this selector 7302 references must be setup for 32-bit protected mode. 7303 @param EntryPoint The 64-bit virtual address of the function to call with 7304 the new stack after paging is disabled. 7305 @param Context1 The 64-bit virtual address of the context to pass into 7306 the EntryPoint function as the first parameter after 7307 paging is disabled. 7308 @param Context2 The 64-bit virtual address of the context to pass into 7309 the EntryPoint function as the second parameter after 7310 paging is disabled. 7311 @param NewStack The 64-bit virtual address of the new stack to use for 7312 the EntryPoint function after paging is disabled. 7313 7314 **/ 7315 VOID 7316 EFIAPI 7317 AsmDisablePaging64 ( 7318 IN UINT16 Cs, 7319 IN UINT32 EntryPoint, 7320 IN UINT32 Context1 OPTIONAL, 7321 IN UINT32 Context2 OPTIONAL, 7322 IN UINT32 NewStack 7323 ); 7324 7325 // 7326 // 16-bit thunking services 7327 // 7328 7329 /** 7330 Retrieves the properties for 16-bit thunk functions. 7331 7332 Computes the size of the buffer and stack below 1MB required to use the 7333 AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This 7334 buffer size is returned in RealModeBufferSize, and the stack size is returned 7335 in ExtraStackSize. If parameters are passed to the 16-bit real mode code, 7336 then the actual minimum stack size is ExtraStackSize plus the maximum number 7337 of bytes that need to be passed to the 16-bit real mode code. 7338 7339 If RealModeBufferSize is NULL, then ASSERT(). 7340 If ExtraStackSize is NULL, then ASSERT(). 7341 7342 @param RealModeBufferSize A pointer to the size of the buffer below 1MB 7343 required to use the 16-bit thunk functions. 7344 @param ExtraStackSize A pointer to the extra size of stack below 1MB 7345 that the 16-bit thunk functions require for 7346 temporary storage in the transition to and from 7347 16-bit real mode. 7348 7349 **/ 7350 VOID 7351 EFIAPI 7352 AsmGetThunk16Properties ( 7353 OUT UINT32 *RealModeBufferSize, 7354 OUT UINT32 *ExtraStackSize 7355 ); 7356 7357 /** 7358 Prepares all structures a code required to use AsmThunk16(). 7359 7360 Prepares all structures and code required to use AsmThunk16(). 7361 7362 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the 7363 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1. 7364 7365 If ThunkContext is NULL, then ASSERT(). 7366 7367 @param ThunkContext A pointer to the context structure that describes the 7368 16-bit real mode code to call. 7369 7370 **/ 7371 VOID 7372 EFIAPI 7373 AsmPrepareThunk16 ( 7374 IN OUT THUNK_CONTEXT *ThunkContext 7375 ); 7376 7377 /** 7378 Transfers control to a 16-bit real mode entry point and returns the results. 7379 7380 Transfers control to a 16-bit real mode entry point and returns the results. 7381 AsmPrepareThunk16() must be called with ThunkContext before this function is used. 7382 This function must be called with interrupts disabled. 7383 7384 The register state from the RealModeState field of ThunkContext is restored just prior 7385 to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState, 7386 which is used to set the interrupt state when a 16-bit real mode entry point is called. 7387 Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState. 7388 The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to 7389 the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function. 7390 The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction, 7391 so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment 7392 and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry 7393 point must exit with a RETF instruction. The register state is captured into RealModeState immediately 7394 after the RETF instruction is executed. 7395 7396 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts, 7397 or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure 7398 the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode. 7399 7400 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts, 7401 then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode. 7402 This includes the base vectors, the interrupt masks, and the edge/level trigger mode. 7403 7404 If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code 7405 is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits. 7406 7407 If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in 7408 ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to 7409 disable the A20 mask. 7410 7411 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in 7412 ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails, 7413 then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports. 7414 7415 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in 7416 ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports. 7417 7418 If ThunkContext is NULL, then ASSERT(). 7419 If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT(). 7420 If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in 7421 ThunkAttributes, then ASSERT(). 7422 7423 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the 7424 virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1. 7425 7426 @param ThunkContext A pointer to the context structure that describes the 7427 16-bit real mode code to call. 7428 7429 **/ 7430 VOID 7431 EFIAPI 7432 AsmThunk16 ( 7433 IN OUT THUNK_CONTEXT *ThunkContext 7434 ); 7435 7436 /** 7437 Prepares all structures and code for a 16-bit real mode thunk, transfers 7438 control to a 16-bit real mode entry point, and returns the results. 7439 7440 Prepares all structures and code for a 16-bit real mode thunk, transfers 7441 control to a 16-bit real mode entry point, and returns the results. If the 7442 caller only need to perform a single 16-bit real mode thunk, then this 7443 service should be used. If the caller intends to make more than one 16-bit 7444 real mode thunk, then it is more efficient if AsmPrepareThunk16() is called 7445 once and AsmThunk16() can be called for each 16-bit real mode thunk. 7446 7447 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the 7448 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1. 7449 7450 See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions. 7451 7452 @param ThunkContext A pointer to the context structure that describes the 7453 16-bit real mode code to call. 7454 7455 **/ 7456 VOID 7457 EFIAPI 7458 AsmPrepareAndThunk16 ( 7459 IN OUT THUNK_CONTEXT *ThunkContext 7460 ); 7461 7462 /** 7463 Generates a 16-bit random number through RDRAND instruction. 7464 7465 if Rand is NULL, then ASSERT(). 7466 7467 @param[out] Rand Buffer pointer to store the random result. 7468 7469 @retval TRUE RDRAND call was successful. 7470 @retval FALSE Failed attempts to call RDRAND. 7471 7472 **/ 7473 BOOLEAN 7474 EFIAPI 7475 AsmRdRand16 ( 7476 OUT UINT16 *Rand 7477 ); 7478 7479 /** 7480 Generates a 32-bit random number through RDRAND instruction. 7481 7482 if Rand is NULL, then ASSERT(). 7483 7484 @param[out] Rand Buffer pointer to store the random result. 7485 7486 @retval TRUE RDRAND call was successful. 7487 @retval FALSE Failed attempts to call RDRAND. 7488 7489 **/ 7490 BOOLEAN 7491 EFIAPI 7492 AsmRdRand32 ( 7493 OUT UINT32 *Rand 7494 ); 7495 7496 /** 7497 Generates a 64-bit random number through RDRAND instruction. 7498 7499 if Rand is NULL, then ASSERT(). 7500 7501 @param[out] Rand Buffer pointer to store the random result. 7502 7503 @retval TRUE RDRAND call was successful. 7504 @retval FALSE Failed attempts to call RDRAND. 7505 7506 **/ 7507 BOOLEAN 7508 EFIAPI 7509 AsmRdRand64 ( 7510 OUT UINT64 *Rand 7511 ); 7512 7513 /** 7514 Load given selector into TR register. 7515 7516 @param[in] Selector Task segment selector 7517 **/ 7518 VOID 7519 EFIAPI 7520 AsmWriteTr ( 7521 IN UINT16 Selector 7522 ); 7523 7524 /** 7525 Performs a serializing operation on all load-from-memory instructions that 7526 were issued prior the AsmLfence function. 7527 7528 Executes a LFENCE instruction. This function is only available on IA-32 and x64. 7529 7530 **/ 7531 VOID 7532 EFIAPI 7533 AsmLfence ( 7534 VOID 7535 ); 7536 7537 /** 7538 Executes a XGETBV instruction 7539 7540 Executes a XGETBV instruction. This function is only available on IA-32 and 7541 x64. 7542 7543 @param[in] Index Extended control register index 7544 7545 @return The current value of the extended control register 7546 **/ 7547 UINT64 7548 EFIAPI 7549 AsmXGetBv ( 7550 IN UINT32 Index 7551 ); 7552 7553 /** 7554 Executes a XSETBV instruction to write a 64-bit value to a Extended Control 7555 Register(XCR), and returns the value. 7556 7557 Writes the 64-bit value specified by Value to the XCR specified by Index. The 7558 64-bit value written to the XCR is returned. No parameter checking is 7559 performed on Index or Value, and some of these may cause CPU exceptions. The 7560 caller must either guarantee that Index and Value are valid, or the caller 7561 must establish proper exception handlers. This function is only available on 7562 IA-32 and x64. 7563 7564 @param Index The 32-bit XCR index to write. 7565 @param Value The 64-bit value to write to the XCR. 7566 7567 @return Value 7568 7569 **/ 7570 UINT64 7571 EFIAPI 7572 AsmXSetBv ( 7573 IN UINT32 Index, 7574 IN UINT64 Value 7575 ); 7576 7577 /** 7578 Executes a VMGEXIT instruction (VMMCALL with a REP prefix) 7579 7580 Executes a VMGEXIT instruction. This function is only available on IA-32 and 7581 x64. 7582 7583 **/ 7584 VOID 7585 EFIAPI 7586 AsmVmgExit ( 7587 VOID 7588 ); 7589 7590 /** 7591 Patch the immediate operand of an IA32 or X64 instruction such that the byte, 7592 word, dword or qword operand is encoded at the end of the instruction's 7593 binary representation. 7594 7595 This function should be used to update object code that was compiled with 7596 NASM from assembly source code. Example: 7597 7598 NASM source code: 7599 7600 mov eax, strict dword 0 ; the imm32 zero operand will be patched 7601 ASM_PFX(gPatchCr3): 7602 mov cr3, eax 7603 7604 C source code: 7605 7606 X86_ASSEMBLY_PATCH_LABEL gPatchCr3; 7607 PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4); 7608 7609 @param[out] InstructionEnd Pointer right past the instruction to patch. The 7610 immediate operand to patch is expected to 7611 comprise the trailing bytes of the instruction. 7612 If InstructionEnd is closer to address 0 than 7613 ValueSize permits, then ASSERT(). 7614 7615 @param[in] PatchValue The constant to write to the immediate operand. 7616 The caller is responsible for ensuring that 7617 PatchValue can be represented in the byte, word, 7618 dword or qword operand (as indicated through 7619 ValueSize); otherwise ASSERT(). 7620 7621 @param[in] ValueSize The size of the operand in bytes; must be 1, 2, 7622 4, or 8. ASSERT() otherwise. 7623 **/ 7624 VOID 7625 EFIAPI 7626 PatchInstructionX86 ( 7627 OUT X86_ASSEMBLY_PATCH_LABEL *InstructionEnd, 7628 IN UINT64 PatchValue, 7629 IN UINTN ValueSize 7630 ); 7631 7632 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64) 7633 #endif // !defined (__BASE_LIB__) 7634