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