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