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