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