iPXE
BaseLib.h
Go to the documentation of this file.
1 /** @file
2  Provides string functions, linked list functions, math functions, synchronization
3  functions, file path functions, and CPU architecture-specific functions.
4 
5 Copyright (c) 2006 - 2021, Intel Corporation. All rights reserved.<BR>
6 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
7 Copyright (c) Microsoft Corporation.<BR>
8 Portions Copyright (c) 2020, Hewlett Packard Enterprise Development LP. All rights reserved.<BR>
9 Portions Copyright (c) 2022, Loongson Technology Corporation Limited. All rights reserved.<BR>
10 
11 SPDX-License-Identifier: BSD-2-Clause-Patent
12 
13 **/
14 
15 #ifndef __BASE_LIB__
16 #define __BASE_LIB__
17 
18 FILE_LICENCE ( BSD2_PATENT );
19 
20 //
21 // Definitions for architecture-specific types
22 //
23 #if defined (MDE_CPU_IA32)
24 ///
25 /// The IA-32 architecture context buffer used by SetJump() and LongJump().
26 ///
27 typedef struct {
28  UINT32 Ebx;
29  UINT32 Esi;
30  UINT32 Edi;
31  UINT32 Ebp;
32  UINT32 Esp;
33  UINT32 Eip;
34  UINT32 Ssp;
35 } BASE_LIBRARY_JUMP_BUFFER;
36 
37 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
38 
39 #endif // defined (MDE_CPU_IA32)
40 
41 #if defined (MDE_CPU_X64)
42 ///
43 /// The x64 architecture context buffer used by SetJump() and LongJump().
44 ///
45 typedef struct {
46  UINT64 Rbx;
47  UINT64 Rsp;
48  UINT64 Rbp;
49  UINT64 Rdi;
50  UINT64 Rsi;
51  UINT64 R12;
52  UINT64 R13;
53  UINT64 R14;
54  UINT64 R15;
55  UINT64 Rip;
56  UINT64 MxCsr;
57  UINT8 XmmBuffer[160]; ///< XMM6-XMM15.
58  UINT64 Ssp;
59 } BASE_LIBRARY_JUMP_BUFFER;
60 
61 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
62 
63 #endif // defined (MDE_CPU_X64)
64 
65 #if defined (MDE_CPU_EBC)
66 ///
67 /// The EBC context buffer used by SetJump() and LongJump().
68 ///
69 typedef struct {
70  UINT64 R0;
71  UINT64 R1;
72  UINT64 R2;
73  UINT64 R3;
74  UINT64 IP;
75 } BASE_LIBRARY_JUMP_BUFFER;
76 
77 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
78 
79 #endif // defined (MDE_CPU_EBC)
80 
81 #if defined (MDE_CPU_ARM)
82 
83 typedef struct {
84  UINT32 R3; ///< A copy of R13.
85  UINT32 R4;
86  UINT32 R5;
87  UINT32 R6;
88  UINT32 R7;
89  UINT32 R8;
90  UINT32 R9;
91  UINT32 R10;
92  UINT32 R11;
93  UINT32 R12;
94  UINT32 R14;
95 } BASE_LIBRARY_JUMP_BUFFER;
96 
97 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
98 
99 #endif // defined (MDE_CPU_ARM)
100 
101 #if defined (MDE_CPU_AARCH64)
102 typedef struct {
103  // GP regs
104  UINT64 X19;
105  UINT64 X20;
106  UINT64 X21;
107  UINT64 X22;
108  UINT64 X23;
109  UINT64 X24;
110  UINT64 X25;
111  UINT64 X26;
112  UINT64 X27;
113  UINT64 X28;
114  UINT64 FP;
115  UINT64 LR;
116  UINT64 IP0;
117 
118  // FP regs
119  UINT64 D8;
120  UINT64 D9;
121  UINT64 D10;
122  UINT64 D11;
123  UINT64 D12;
124  UINT64 D13;
125  UINT64 D14;
126  UINT64 D15;
127 } BASE_LIBRARY_JUMP_BUFFER;
128 
129 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
130 
131 #endif // defined (MDE_CPU_AARCH64)
132 
133 #if defined (MDE_CPU_RISCV64)
134 ///
135 /// The RISC-V architecture context buffer used by SetJump() and LongJump().
136 ///
137 typedef struct {
138  UINT64 RA;
139  UINT64 S0;
140  UINT64 S1;
141  UINT64 S2;
142  UINT64 S3;
143  UINT64 S4;
144  UINT64 S5;
145  UINT64 S6;
146  UINT64 S7;
147  UINT64 S8;
148  UINT64 S9;
149  UINT64 S10;
150  UINT64 S11;
151  UINT64 SP;
152 } BASE_LIBRARY_JUMP_BUFFER;
153 
154 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
155 
156 VOID
157 RiscVSetSupervisorScratch (
158  IN UINT64
159  );
160 
161 UINT64
162 RiscVGetSupervisorScratch (
163  VOID
164  );
165 
166 VOID
167 RiscVSetSupervisorStvec (
168  IN UINT64
169  );
170 
171 UINT64
172 RiscVGetSupervisorStvec (
173  VOID
174  );
175 
176 UINT64
177 RiscVGetSupervisorTrapCause (
178  VOID
179  );
180 
181 VOID
182 RiscVSetSupervisorAddressTranslationRegister (
183  IN UINT64
184  );
185 
186 UINT64
187 RiscVGetSupervisorAddressTranslationRegister (
188  VOID
189  );
190 
191 UINT64
192 RiscVReadTimer (
193  VOID
194  );
195 
196 VOID
197 RiscVSetSupervisorTimeCompareRegister (
198  IN UINT64
199  );
200 
201 VOID
202 RiscVEnableTimerInterrupt (
203  VOID
204  );
205 
206 VOID
207 RiscVDisableTimerInterrupt (
208  VOID
209  );
210 
211 VOID
212 RiscVClearPendingTimerInterrupt (
213  VOID
214  );
215 
216 /**
217  RISC-V invalidate instruction cache.
218 
219 **/
220 VOID
221 EFIAPI
222 RiscVInvalidateInstCacheFenceAsm (
223  VOID
224  );
225 
226 /**
227  RISC-V invalidate data cache.
228 
229 **/
230 VOID
231 EFIAPI
232 RiscVInvalidateDataCacheFenceAsm (
233  VOID
234  );
235 
236 /**
237  RISC-V flush cache block. Atomically perform a clean operation
238  followed by an invalidate operation
239 
240 **/
241 VOID
242 EFIAPI
243 RiscVCpuCacheFlushCmoAsm (
244  IN UINTN
245  );
246 
247 /**
248 Perform a write transfer to another cache or to memory if the
249 data in the copy of the cache block have been modified by a store
250 operation
251 
252 **/
253 VOID
254 EFIAPI
255 RiscVCpuCacheCleanCmoAsm (
256  IN UINTN
257  );
258 
259 /**
260 Deallocate the copy of the cache block
261 
262 **/
263 VOID
264 EFIAPI
265 RiscVCpuCacheInvalCmoAsm (
266  IN UINTN
267  );
268 
269 #endif // defined (MDE_CPU_RISCV64)
270 
271 #if defined (MDE_CPU_LOONGARCH64)
272 ///
273 /// The LoongArch architecture context buffer used by SetJump() and LongJump()
274 ///
275 typedef struct {
276  UINT64 S0;
277  UINT64 S1;
278  UINT64 S2;
279  UINT64 S3;
280  UINT64 S4;
281  UINT64 S5;
282  UINT64 S6;
283  UINT64 S7;
284  UINT64 S8;
285  UINT64 SP;
286  UINT64 FP;
287  UINT64 RA;
288 } BASE_LIBRARY_JUMP_BUFFER;
289 
290 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
291 
292 /*
293  * Set the exception base address for LoongArch.
294  *
295  * @param ExceptionBaseAddress The exception base address, must be aligned greater than or qeual to 4K .
296  */
297 VOID
298 SetExceptionBaseAddress (
299  IN UINT64
300  );
301 
302 /*
303  * Set the TlbRebase address for LoongArch.
304  *
305  * @param TlbRebaseAddress The TlbRebase address, must be aligned greater than or qeual to 4K .
306  */
307 VOID
308 SetTlbRebaseAddress (
309  IN UINT64
310  );
311 
312 /**
313  Enables local CPU interrupts.
314 
315  @param Needs to enable local interrupt bit.
316 **/
317 VOID
318 EnableLocalInterrupts (
319  IN UINT16
320  );
321 
322 /**
323  Disables local CPU interrupts.
324 
325  @param Needs to disable local interrupt bit.
326 **/
327 VOID
328 DisableLocalInterrupts (
329  IN UINT16
330  );
331 
332 /**
333  Read CPUCFG register.
334 
335  @param Index Specifies the register number of the CPUCFG to read the data.
336  @param Data A pointer to the variable used to store the CPUCFG register value.
337 **/
338 VOID
339 AsmCpucfg (
340  IN UINT32 Index,
341  OUT UINT32 *Data
342  );
343 
344 /**
345  Gets the timer count value.
346 
347  @param[] VOID
348  @retval timer count value.
349 
350 **/
351 UINTN
352 AsmReadStableCounter (
353  VOID
354  );
355 
356 /**
357  CSR read operation.
358 
359  @param[in] Select CSR read instruction select values.
360 
361  @return The return value of csrrd instruction, return -1 means no CSR instruction
362  is found.
363 **/
364 UINTN
365 CsrRead (
366  IN UINT16 Select
367  );
368 
369 /**
370  CSR write operation.
371 
372  @param[in] Select CSR write instruction select values.
373  @param[in] Value The csrwr will write the value.
374 
375  @return The return value of csrwr instruction, that is, store the old value of
376  the register, return -1 means no CSR instruction is found.
377 **/
378 UINTN
379 CsrWrite (
380  IN UINT16 Select,
381  IN UINTN Value
382  );
383 
384 /**
385  CSR exchange operation.
386 
387  @param[in] Select CSR exchange instruction select values.
388  @param[in] Value The csrxchg will write the value.
389  @param[in] Mask The csrxchg mask value.
390 
391  @return The return value of csrxchg instruction, that is, store the old value of
392  the register, return -1 means no CSR instruction is found.
393 **/
394 UINTN
395 CsrXChg (
396  IN UINT16 Select,
397  IN UINTN Value,
398  IN UINTN Mask
399  );
400 
401 /**
402  IO CSR read byte operation.
403 
404  @param[in] Select IO CSR read instruction select values.
405 
406  @return The return value of iocsrrd.b instruction.
407 
408 **/
409 UINT8
410 IoCsrRead8 (
411  IN UINTN Select
412  );
413 
414 /**
415  IO CSR read half word operation.
416 
417  @param[in] Select IO CSR read instruction select values.
418 
419  @return The return value of iocsrrd.h instruction.
420 
421 **/
422 UINT16
423 IoCsrRead16 (
424  IN UINTN Select
425  );
426 
427 /**
428  IO CSR read word operation.
429 
430  @param[in] Select IO CSR read instruction select values.
431 
432  @return The return value of iocsrrd.w instruction.
433 
434 **/
435 UINT32
436 IoCsrRead32 (
437  IN UINTN Select
438  );
439 
440 /**
441  IO CSR read double word operation. Only for LoongArch64.
442 
443  @param[in] Select IO CSR read instruction select values.
444 
445  @return The return value of iocsrrd.d instruction.
446 
447 **/
448 UINT64
449 IoCsrRead64 (
450  IN UINTN Select
451  );
452 
453 /**
454  IO CSR write byte operation.
455 
456  @param[in] Select IO CSR write instruction select values.
457  @param[in] Value The iocsrwr.b will write the value.
458 
459  @return VOID.
460 
461 **/
462 VOID
463 IoCsrWrite8 (
464  IN UINTN Select,
465  IN UINT8 Value
466  );
467 
468 /**
469  IO CSR write half word operation.
470 
471  @param[in] Select IO CSR write instruction select values.
472  @param[in] Value The iocsrwr.h will write the value.
473 
474  @return VOID.
475 
476 **/
477 VOID
478 IoCsrWrite16 (
479  IN UINTN Select,
480  IN UINT16 Value
481  );
482 
483 /**
484  IO CSR write word operation.
485 
486  @param[in] Select IO CSR write instruction select values.
487  @param[in] Value The iocsrwr.w will write the value.
488 
489  @return VOID.
490 
491 **/
492 VOID
493 IoCsrWrite32 (
494  IN UINTN Select,
495  IN UINT32 Value
496  );
497 
498 /**
499  IO CSR write double word operation. Only for LoongArch64.
500 
501  @param[in] Select IO CSR write instruction select values.
502  @param[in] Value The iocsrwr.d will write the value.
503 
504  @return VOID.
505 
506 **/
507 VOID
508 IoCsrWrite64 (
509  IN UINTN Select,
510  IN UINT64 Value
511  );
512 
513 #endif // defined (MDE_CPU_LOONGARCH64)
514 
515 //
516 // String Services
517 //
518 
519 /**
520  Returns the length of a Null-terminated Unicode string.
521 
522  This function is similar as strlen_s defined in C11.
523 
524  If String is not aligned on a 16-bit boundary, then ASSERT().
525 
526  @param String A pointer to a Null-terminated Unicode string.
527  @param MaxSize The maximum number of Destination Unicode
528  char, including terminating null char.
529 
530  @retval 0 If String is NULL.
531  @retval MaxSize If there is no null character in the first MaxSize characters of String.
532  @return The number of characters that percede the terminating null character.
533 
534 **/
535 UINTN
536 EFIAPI
537 StrnLenS (
538  IN CONST CHAR16 *String,
539  IN UINTN MaxSize
540  );
541 
542 /**
543  Returns the size of a Null-terminated Unicode string in bytes, including the
544  Null terminator.
545 
546  This function returns the size of the Null-terminated Unicode string
547  specified by String in bytes, including the Null terminator.
548 
549  If String is not aligned on a 16-bit boundary, then ASSERT().
550 
551  @param String A pointer to a Null-terminated Unicode string.
552  @param MaxSize The maximum number of Destination Unicode
553  char, including the Null terminator.
554 
555  @retval 0 If String is NULL.
556  @retval (sizeof (CHAR16) * (MaxSize + 1))
557  If there is no Null terminator in the first MaxSize characters of
558  String.
559  @return The size of the Null-terminated Unicode string in bytes, including
560  the Null terminator.
561 
562 **/
563 UINTN
564 EFIAPI
565 StrnSizeS (
566  IN CONST CHAR16 *String,
567  IN UINTN MaxSize
568  );
569 
570 /**
571  Copies the string pointed to by Source (including the terminating null char)
572  to the array pointed to by Destination.
573 
574  This function is similar as strcpy_s defined in C11.
575 
576  If Destination is not aligned on a 16-bit boundary, then ASSERT().
577  If Source is not aligned on a 16-bit boundary, then ASSERT().
578 
579  If an error is returned, then the Destination is unmodified.
580 
581  @param Destination A pointer to a Null-terminated Unicode string.
582  @param DestMax The maximum number of Destination Unicode
583  char, including terminating null char.
584  @param Source A pointer to a Null-terminated Unicode string.
585 
586  @retval RETURN_SUCCESS String is copied.
587  @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
588  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
589  If Source is NULL.
590  If PcdMaximumUnicodeStringLength is not zero,
591  and DestMax is greater than
592  PcdMaximumUnicodeStringLength.
593  If DestMax is 0.
594  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
595 **/
597 EFIAPI
598 StrCpyS (
599  OUT CHAR16 *Destination,
600  IN UINTN DestMax,
601  IN CONST CHAR16 *Source
602  );
603 
604 /**
605  Copies not more than Length successive char from the string pointed to by
606  Source to the array pointed to by Destination. If no null char is copied from
607  Source, then Destination[Length] is always set to null.
608 
609  This function is similar as strncpy_s defined in C11.
610 
611  If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
612  If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
613 
614  If an error is returned, then the Destination is unmodified.
615 
616  @param Destination A pointer to a Null-terminated Unicode string.
617  @param DestMax The maximum number of Destination Unicode
618  char, including terminating null char.
619  @param Source A pointer to a Null-terminated Unicode string.
620  @param Length The maximum number of Unicode characters to copy.
621 
622  @retval RETURN_SUCCESS String is copied.
623  @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
624  MIN(StrLen(Source), Length).
625  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
626  If Source is NULL.
627  If PcdMaximumUnicodeStringLength is not zero,
628  and DestMax is greater than
629  PcdMaximumUnicodeStringLength.
630  If DestMax is 0.
631  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
632 **/
634 EFIAPI
635 StrnCpyS (
636  OUT CHAR16 *Destination,
637  IN UINTN DestMax,
638  IN CONST CHAR16 *Source,
639  IN UINTN Length
640  );
641 
642 /**
643  Appends a copy of the string pointed to by Source (including the terminating
644  null char) to the end of the string pointed to by Destination.
645 
646  This function is similar as strcat_s defined in C11.
647 
648  If Destination is not aligned on a 16-bit boundary, then ASSERT().
649  If Source is not aligned on a 16-bit boundary, then ASSERT().
650 
651  If an error is returned, then the Destination is unmodified.
652 
653  @param Destination A pointer to a Null-terminated Unicode string.
654  @param DestMax The maximum number of Destination Unicode
655  char, including terminating null char.
656  @param Source A pointer to a Null-terminated Unicode string.
657 
658  @retval RETURN_SUCCESS String is appended.
659  @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
660  StrLen(Destination).
661  @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
662  greater than StrLen(Source).
663  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
664  If Source is NULL.
665  If PcdMaximumUnicodeStringLength is not zero,
666  and DestMax is greater than
667  PcdMaximumUnicodeStringLength.
668  If DestMax is 0.
669  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
670 **/
672 EFIAPI
673 StrCatS (
674  IN OUT CHAR16 *Destination,
675  IN UINTN DestMax,
676  IN CONST CHAR16 *Source
677  );
678 
679 /**
680  Appends not more than Length successive char from the string pointed to by
681  Source to the end of the string pointed to by Destination. If no null char is
682  copied from Source, then Destination[StrLen(Destination) + Length] is always
683  set to null.
684 
685  This function is similar as strncat_s defined in C11.
686 
687  If Destination is not aligned on a 16-bit boundary, then ASSERT().
688  If Source is not aligned on a 16-bit boundary, then ASSERT().
689 
690  If an error is returned, then the Destination is unmodified.
691 
692  @param Destination A pointer to a Null-terminated Unicode string.
693  @param DestMax The maximum number of Destination Unicode
694  char, including terminating null char.
695  @param Source A pointer to a Null-terminated Unicode string.
696  @param Length The maximum number of Unicode characters to copy.
697 
698  @retval RETURN_SUCCESS String is appended.
699  @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
700  StrLen(Destination).
701  @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
702  greater than MIN(StrLen(Source), Length).
703  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
704  If Source is NULL.
705  If PcdMaximumUnicodeStringLength is not zero,
706  and DestMax is greater than
707  PcdMaximumUnicodeStringLength.
708  If DestMax is 0.
709  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
710 **/
712 EFIAPI
713 StrnCatS (
714  IN OUT CHAR16 *Destination,
715  IN UINTN DestMax,
716  IN CONST CHAR16 *Source,
717  IN UINTN Length
718  );
719 
720 /**
721  Convert a Null-terminated Unicode decimal string to a value of type UINTN.
722 
723  This function outputs a value of type UINTN by interpreting the contents of
724  the Unicode string specified by String as a decimal number. The format of the
725  input Unicode string String is:
726 
727  [spaces] [decimal digits].
728 
729  The valid decimal digit character is in the range [0-9]. The function will
730  ignore the pad space, which includes spaces or tab characters, before
731  [decimal digits]. The running zero in the beginning of [decimal digits] will
732  be ignored. Then, the function stops at the first character that is a not a
733  valid decimal character or a Null-terminator, whichever one comes first.
734 
735  If String is not aligned in a 16-bit boundary, then ASSERT().
736 
737  If String has no valid decimal digits in the above format, then 0 is stored
738  at the location pointed to by Data.
739  If the number represented by String exceeds the range defined by UINTN, then
740  MAX_UINTN is stored at the location pointed to by Data.
741 
742  If EndPointer is not NULL, a pointer to the character that stopped the scan
743  is stored at the location pointed to by EndPointer. If String has no valid
744  decimal digits right after the optional pad spaces, the value of String is
745  stored at the location pointed to by EndPointer.
746 
747  @param String Pointer to a Null-terminated Unicode string.
748  @param EndPointer Pointer to character that stops scan.
749  @param Data Pointer to the converted value.
750 
751  @retval RETURN_SUCCESS Value is translated from String.
752  @retval RETURN_INVALID_PARAMETER If String is NULL.
753  If Data is NULL.
754  If PcdMaximumUnicodeStringLength is not
755  zero, and String contains more than
756  PcdMaximumUnicodeStringLength Unicode
757  characters, not including the
758  Null-terminator.
759  @retval RETURN_UNSUPPORTED If the number represented by String exceeds
760  the range defined by UINTN.
761 
762 **/
764 EFIAPI
766  IN CONST CHAR16 *String,
767  OUT CHAR16 **EndPointer OPTIONAL,
768  OUT UINTN *Data
769  );
770 
771 /**
772  Convert a Null-terminated Unicode decimal string to a value of type UINT64.
773 
774  This function outputs a value of type UINT64 by interpreting the contents of
775  the Unicode string specified by String as a decimal number. The format of the
776  input Unicode string String is:
777 
778  [spaces] [decimal digits].
779 
780  The valid decimal digit character is in the range [0-9]. The function will
781  ignore the pad space, which includes spaces or tab characters, before
782  [decimal digits]. The running zero in the beginning of [decimal digits] will
783  be ignored. Then, the function stops at the first character that is a not a
784  valid decimal character or a Null-terminator, whichever one comes first.
785 
786  If String is not aligned in a 16-bit boundary, then ASSERT().
787 
788  If String has no valid decimal digits in the above format, then 0 is stored
789  at the location pointed to by Data.
790  If the number represented by String exceeds the range defined by UINT64, then
791  MAX_UINT64 is stored at the location pointed to by Data.
792 
793  If EndPointer is not NULL, a pointer to the character that stopped the scan
794  is stored at the location pointed to by EndPointer. If String has no valid
795  decimal digits right after the optional pad spaces, the value of String is
796  stored at the location pointed to by EndPointer.
797 
798  @param String Pointer to a Null-terminated Unicode string.
799  @param EndPointer Pointer to character that stops scan.
800  @param Data Pointer to the converted value.
801 
802  @retval RETURN_SUCCESS Value is translated from String.
803  @retval RETURN_INVALID_PARAMETER If String is NULL.
804  If Data is NULL.
805  If PcdMaximumUnicodeStringLength is not
806  zero, and String contains more than
807  PcdMaximumUnicodeStringLength Unicode
808  characters, not including the
809  Null-terminator.
810  @retval RETURN_UNSUPPORTED If the number represented by String exceeds
811  the range defined by UINT64.
812 
813 **/
815 EFIAPI
817  IN CONST CHAR16 *String,
818  OUT CHAR16 **EndPointer OPTIONAL,
819  OUT UINT64 *Data
820  );
821 
822 /**
823  Convert a Null-terminated Unicode hexadecimal string to a value of type
824  UINTN.
825 
826  This function outputs a value of type UINTN by interpreting the contents of
827  the Unicode string specified by String as a hexadecimal number. The format of
828  the input Unicode string String is:
829 
830  [spaces][zeros][x][hexadecimal digits].
831 
832  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
833  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
834  If "x" appears in the input string, it must be prefixed with at least one 0.
835  The function will ignore the pad space, which includes spaces or tab
836  characters, before [zeros], [x] or [hexadecimal digit]. The running zero
837  before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
838  after [x] or the first valid hexadecimal digit. Then, the function stops at
839  the first character that is a not a valid hexadecimal character or NULL,
840  whichever one comes first.
841 
842  If String is not aligned in a 16-bit boundary, then ASSERT().
843 
844  If String has no valid hexadecimal digits in the above format, then 0 is
845  stored at the location pointed to by Data.
846  If the number represented by String exceeds the range defined by UINTN, then
847  MAX_UINTN is stored at the location pointed to by Data.
848 
849  If EndPointer is not NULL, a pointer to the character that stopped the scan
850  is stored at the location pointed to by EndPointer. If String has no valid
851  hexadecimal digits right after the optional pad spaces, the value of String
852  is stored at the location pointed to by EndPointer.
853 
854  @param String Pointer to a Null-terminated Unicode string.
855  @param EndPointer Pointer to character that stops scan.
856  @param Data Pointer to the converted value.
857 
858  @retval RETURN_SUCCESS Value is translated from String.
859  @retval RETURN_INVALID_PARAMETER If String is NULL.
860  If Data is NULL.
861  If PcdMaximumUnicodeStringLength is not
862  zero, and String contains more than
863  PcdMaximumUnicodeStringLength Unicode
864  characters, not including the
865  Null-terminator.
866  @retval RETURN_UNSUPPORTED If the number represented by String exceeds
867  the range defined by UINTN.
868 
869 **/
871 EFIAPI
873  IN CONST CHAR16 *String,
874  OUT CHAR16 **EndPointer OPTIONAL,
875  OUT UINTN *Data
876  );
877 
878 /**
879  Convert a Null-terminated Unicode hexadecimal string to a value of type
880  UINT64.
881 
882  This function outputs a value of type UINT64 by interpreting the contents of
883  the Unicode string specified by String as a hexadecimal number. The format of
884  the input Unicode string String is:
885 
886  [spaces][zeros][x][hexadecimal digits].
887 
888  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
889  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
890  If "x" appears in the input string, it must be prefixed with at least one 0.
891  The function will ignore the pad space, which includes spaces or tab
892  characters, before [zeros], [x] or [hexadecimal digit]. The running zero
893  before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
894  after [x] or the first valid hexadecimal digit. Then, the function stops at
895  the first character that is a not a valid hexadecimal character or NULL,
896  whichever one comes first.
897 
898  If String is not aligned in a 16-bit boundary, then ASSERT().
899 
900  If String has no valid hexadecimal digits in the above format, then 0 is
901  stored at the location pointed to by Data.
902  If the number represented by String exceeds the range defined by UINT64, then
903  MAX_UINT64 is stored at the location pointed to by Data.
904 
905  If EndPointer is not NULL, a pointer to the character that stopped the scan
906  is stored at the location pointed to by EndPointer. If String has no valid
907  hexadecimal digits right after the optional pad spaces, the value of String
908  is stored at the location pointed to by EndPointer.
909 
910  @param String Pointer to a Null-terminated Unicode string.
911  @param EndPointer Pointer to character that stops scan.
912  @param Data Pointer to the converted value.
913 
914  @retval RETURN_SUCCESS Value is translated from String.
915  @retval RETURN_INVALID_PARAMETER If String is NULL.
916  If Data is NULL.
917  If PcdMaximumUnicodeStringLength is not
918  zero, and String contains more than
919  PcdMaximumUnicodeStringLength Unicode
920  characters, not including the
921  Null-terminator.
922  @retval RETURN_UNSUPPORTED If the number represented by String exceeds
923  the range defined by UINT64.
924 
925 **/
927 EFIAPI
929  IN CONST CHAR16 *String,
930  OUT CHAR16 **EndPointer OPTIONAL,
931  OUT UINT64 *Data
932  );
933 
934 /**
935  Returns the length of a Null-terminated Ascii string.
936 
937  This function is similar as strlen_s defined in C11.
938 
939  @param String A pointer to a Null-terminated Ascii string.
940  @param MaxSize The maximum number of Destination Ascii
941  char, including terminating null char.
942 
943  @retval 0 If String is NULL.
944  @retval MaxSize If there is no null character in the first MaxSize characters of String.
945  @return The number of characters that percede the terminating null character.
946 
947 **/
948 UINTN
949 EFIAPI
951  IN CONST CHAR8 *String,
952  IN UINTN MaxSize
953  );
954 
955 /**
956  Returns the size of a Null-terminated Ascii string in bytes, including the
957  Null terminator.
958 
959  This function returns the size of the Null-terminated Ascii string specified
960  by String in bytes, including the Null terminator.
961 
962  @param String A pointer to a Null-terminated Ascii string.
963  @param MaxSize The maximum number of Destination Ascii
964  char, including the Null terminator.
965 
966  @retval 0 If String is NULL.
967  @retval (sizeof (CHAR8) * (MaxSize + 1))
968  If there is no Null terminator in the first MaxSize characters of
969  String.
970  @return The size of the Null-terminated Ascii string in bytes, including the
971  Null terminator.
972 
973 **/
974 UINTN
975 EFIAPI
977  IN CONST CHAR8 *String,
978  IN UINTN MaxSize
979  );
980 
981 /**
982  Copies the string pointed to by Source (including the terminating null char)
983  to the array pointed to by Destination.
984 
985  This function is similar as strcpy_s defined in C11.
986 
987  If an error is returned, then the Destination is unmodified.
988 
989  @param Destination A pointer to a Null-terminated Ascii string.
990  @param DestMax The maximum number of Destination Ascii
991  char, including terminating null char.
992  @param Source A pointer to a Null-terminated Ascii string.
993 
994  @retval RETURN_SUCCESS String is copied.
995  @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
996  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
997  If Source is NULL.
998  If PcdMaximumAsciiStringLength is not zero,
999  and DestMax is greater than
1000  PcdMaximumAsciiStringLength.
1001  If DestMax is 0.
1002  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1003 **/
1005 EFIAPI
1006 AsciiStrCpyS (
1007  OUT CHAR8 *Destination,
1008  IN UINTN DestMax,
1009  IN CONST CHAR8 *Source
1010  );
1011 
1012 /**
1013  Copies not more than Length successive char from the string pointed to by
1014  Source to the array pointed to by Destination. If no null char is copied from
1015  Source, then Destination[Length] is always set to null.
1016 
1017  This function is similar as strncpy_s defined in C11.
1018 
1019  If an error is returned, then the Destination is unmodified.
1020 
1021  @param Destination A pointer to a Null-terminated Ascii string.
1022  @param DestMax The maximum number of Destination Ascii
1023  char, including terminating null char.
1024  @param Source A pointer to a Null-terminated Ascii string.
1025  @param Length The maximum number of Ascii characters to copy.
1026 
1027  @retval RETURN_SUCCESS String is copied.
1028  @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1029  MIN(StrLen(Source), Length).
1030  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1031  If Source is NULL.
1032  If PcdMaximumAsciiStringLength is not zero,
1033  and DestMax is greater than
1034  PcdMaximumAsciiStringLength.
1035  If DestMax is 0.
1036  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1037 **/
1039 EFIAPI
1040 AsciiStrnCpyS (
1041  OUT CHAR8 *Destination,
1042  IN UINTN DestMax,
1043  IN CONST CHAR8 *Source,
1044  IN UINTN Length
1045  );
1046 
1047 /**
1048  Appends a copy of the string pointed to by Source (including the terminating
1049  null char) to the end of the string pointed to by Destination.
1050 
1051  This function is similar as strcat_s defined in C11.
1052 
1053  If an error is returned, then the Destination is unmodified.
1054 
1055  @param Destination A pointer to a Null-terminated Ascii string.
1056  @param DestMax The maximum number of Destination Ascii
1057  char, including terminating null char.
1058  @param Source A pointer to a Null-terminated Ascii string.
1059 
1060  @retval RETURN_SUCCESS String is appended.
1061  @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
1062  StrLen(Destination).
1063  @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
1064  greater than StrLen(Source).
1065  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1066  If Source is NULL.
1067  If PcdMaximumAsciiStringLength is not zero,
1068  and DestMax is greater than
1069  PcdMaximumAsciiStringLength.
1070  If DestMax is 0.
1071  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1072 **/
1074 EFIAPI
1075 AsciiStrCatS (
1076  IN OUT CHAR8 *Destination,
1077  IN UINTN DestMax,
1078  IN CONST CHAR8 *Source
1079  );
1080 
1081 /**
1082  Appends not more than Length successive char from the string pointed to by
1083  Source to the end of the string pointed to by Destination. If no null char is
1084  copied from Source, then Destination[StrLen(Destination) + Length] is always
1085  set to null.
1086 
1087  This function is similar as strncat_s defined in C11.
1088 
1089  If an error is returned, then the Destination is unmodified.
1090 
1091  @param Destination A pointer to a Null-terminated Ascii string.
1092  @param DestMax The maximum number of Destination Ascii
1093  char, including terminating null char.
1094  @param Source A pointer to a Null-terminated Ascii string.
1095  @param Length The maximum number of Ascii characters to copy.
1096 
1097  @retval RETURN_SUCCESS String is appended.
1098  @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
1099  StrLen(Destination).
1100  @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
1101  greater than MIN(StrLen(Source), Length).
1102  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1103  If Source is NULL.
1104  If PcdMaximumAsciiStringLength is not zero,
1105  and DestMax is greater than
1106  PcdMaximumAsciiStringLength.
1107  If DestMax is 0.
1108  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1109 **/
1111 EFIAPI
1112 AsciiStrnCatS (
1113  IN OUT CHAR8 *Destination,
1114  IN UINTN DestMax,
1115  IN CONST CHAR8 *Source,
1116  IN UINTN Length
1117  );
1118 
1119 /**
1120  Convert a Null-terminated Ascii decimal string to a value of type UINTN.
1121 
1122  This function outputs a value of type UINTN by interpreting the contents of
1123  the Ascii string specified by String as a decimal number. The format of the
1124  input Ascii string String is:
1125 
1126  [spaces] [decimal digits].
1127 
1128  The valid decimal digit character is in the range [0-9]. The function will
1129  ignore the pad space, which includes spaces or tab characters, before
1130  [decimal digits]. The running zero in the beginning of [decimal digits] will
1131  be ignored. Then, the function stops at the first character that is a not a
1132  valid decimal character or a Null-terminator, whichever one comes first.
1133 
1134  If String has no valid decimal digits in the above format, then 0 is stored
1135  at the location pointed to by Data.
1136  If the number represented by String exceeds the range defined by UINTN, then
1137  MAX_UINTN is stored at the location pointed to by Data.
1138 
1139  If EndPointer is not NULL, a pointer to the character that stopped the scan
1140  is stored at the location pointed to by EndPointer. If String has no valid
1141  decimal digits right after the optional pad spaces, the value of String is
1142  stored at the location pointed to by EndPointer.
1143 
1144  @param String Pointer to a Null-terminated Ascii string.
1145  @param EndPointer Pointer to character that stops scan.
1146  @param Data Pointer to the converted value.
1147 
1148  @retval RETURN_SUCCESS Value is translated from String.
1149  @retval RETURN_INVALID_PARAMETER If String is NULL.
1150  If Data is NULL.
1151  If PcdMaximumAsciiStringLength is not zero,
1152  and String contains more than
1153  PcdMaximumAsciiStringLength Ascii
1154  characters, not including the
1155  Null-terminator.
1156  @retval RETURN_UNSUPPORTED If the number represented by String exceeds
1157  the range defined by UINTN.
1158 
1159 **/
1161 EFIAPI
1163  IN CONST CHAR8 *String,
1164  OUT CHAR8 **EndPointer OPTIONAL,
1165  OUT UINTN *Data
1166  );
1167 
1168 /**
1169  Convert a Null-terminated Ascii decimal string to a value of type UINT64.
1170 
1171  This function outputs a value of type UINT64 by interpreting the contents of
1172  the Ascii string specified by String as a decimal number. The format of the
1173  input Ascii string String is:
1174 
1175  [spaces] [decimal digits].
1176 
1177  The valid decimal digit character is in the range [0-9]. The function will
1178  ignore the pad space, which includes spaces or tab characters, before
1179  [decimal digits]. The running zero in the beginning of [decimal digits] will
1180  be ignored. Then, the function stops at the first character that is a not a
1181  valid decimal character or a Null-terminator, whichever one comes first.
1182 
1183  If String has no valid decimal digits in the above format, then 0 is stored
1184  at the location pointed to by Data.
1185  If the number represented by String exceeds the range defined by UINT64, then
1186  MAX_UINT64 is stored at the location pointed to by Data.
1187 
1188  If EndPointer is not NULL, a pointer to the character that stopped the scan
1189  is stored at the location pointed to by EndPointer. If String has no valid
1190  decimal digits right after the optional pad spaces, the value of String is
1191  stored at the location pointed to by EndPointer.
1192 
1193  @param String Pointer to a Null-terminated Ascii string.
1194  @param EndPointer Pointer to character that stops scan.
1195  @param Data Pointer to the converted value.
1196 
1197  @retval RETURN_SUCCESS Value is translated from String.
1198  @retval RETURN_INVALID_PARAMETER If String is NULL.
1199  If Data is NULL.
1200  If PcdMaximumAsciiStringLength is not zero,
1201  and String contains more than
1202  PcdMaximumAsciiStringLength Ascii
1203  characters, not including the
1204  Null-terminator.
1205  @retval RETURN_UNSUPPORTED If the number represented by String exceeds
1206  the range defined by UINT64.
1207 
1208 **/
1210 EFIAPI
1212  IN CONST CHAR8 *String,
1213  OUT CHAR8 **EndPointer OPTIONAL,
1214  OUT UINT64 *Data
1215  );
1216 
1217 /**
1218  Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
1219 
1220  This function outputs a value of type UINTN by interpreting the contents of
1221  the Ascii string specified by String as a hexadecimal number. The format of
1222  the input Ascii string String is:
1223 
1224  [spaces][zeros][x][hexadecimal digits].
1225 
1226  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1227  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
1228  "x" appears in the input string, it must be prefixed with at least one 0. The
1229  function will ignore the pad space, which includes spaces or tab characters,
1230  before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
1231  [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
1232  the first valid hexadecimal digit. Then, the function stops at the first
1233  character that is a not a valid hexadecimal character or Null-terminator,
1234  whichever on comes first.
1235 
1236  If String has no valid hexadecimal digits in the above format, then 0 is
1237  stored at the location pointed to by Data.
1238  If the number represented by String exceeds the range defined by UINTN, then
1239  MAX_UINTN is stored at the location pointed to by Data.
1240 
1241  If EndPointer is not NULL, a pointer to the character that stopped the scan
1242  is stored at the location pointed to by EndPointer. If String has no valid
1243  hexadecimal digits right after the optional pad spaces, the value of String
1244  is stored at the location pointed to by EndPointer.
1245 
1246  @param String Pointer to a Null-terminated Ascii string.
1247  @param EndPointer Pointer to character that stops scan.
1248  @param Data Pointer to the converted value.
1249 
1250  @retval RETURN_SUCCESS Value is translated from String.
1251  @retval RETURN_INVALID_PARAMETER If String is NULL.
1252  If Data is NULL.
1253  If PcdMaximumAsciiStringLength is not zero,
1254  and String contains more than
1255  PcdMaximumAsciiStringLength Ascii
1256  characters, not including the
1257  Null-terminator.
1258  @retval RETURN_UNSUPPORTED If the number represented by String exceeds
1259  the range defined by UINTN.
1260 
1261 **/
1263 EFIAPI
1265  IN CONST CHAR8 *String,
1266  OUT CHAR8 **EndPointer OPTIONAL,
1267  OUT UINTN *Data
1268  );
1269 
1270 /**
1271  Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
1272 
1273  This function outputs a value of type UINT64 by interpreting the contents of
1274  the Ascii string specified by String as a hexadecimal number. The format of
1275  the input Ascii string String is:
1276 
1277  [spaces][zeros][x][hexadecimal digits].
1278 
1279  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1280  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
1281  "x" appears in the input string, it must be prefixed with at least one 0. The
1282  function will ignore the pad space, which includes spaces or tab characters,
1283  before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
1284  [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
1285  the first valid hexadecimal digit. Then, the function stops at the first
1286  character that is a not a valid hexadecimal character or Null-terminator,
1287  whichever on comes first.
1288 
1289  If String has no valid hexadecimal digits in the above format, then 0 is
1290  stored at the location pointed to by Data.
1291  If the number represented by String exceeds the range defined by UINT64, then
1292  MAX_UINT64 is stored at the location pointed to by Data.
1293 
1294  If EndPointer is not NULL, a pointer to the character that stopped the scan
1295  is stored at the location pointed to by EndPointer. If String has no valid
1296  hexadecimal digits right after the optional pad spaces, the value of String
1297  is stored at the location pointed to by EndPointer.
1298 
1299  @param String Pointer to a Null-terminated Ascii string.
1300  @param EndPointer Pointer to character that stops scan.
1301  @param Data Pointer to the converted value.
1302 
1303  @retval RETURN_SUCCESS Value is translated from String.
1304  @retval RETURN_INVALID_PARAMETER If String is NULL.
1305  If Data is NULL.
1306  If PcdMaximumAsciiStringLength is not zero,
1307  and String contains more than
1308  PcdMaximumAsciiStringLength Ascii
1309  characters, not including the
1310  Null-terminator.
1311  @retval RETURN_UNSUPPORTED If the number represented by String exceeds
1312  the range defined by UINT64.
1313 
1314 **/
1316 EFIAPI
1318  IN CONST CHAR8 *String,
1319  OUT CHAR8 **EndPointer OPTIONAL,
1320  OUT UINT64 *Data
1321  );
1322 
1323 /**
1324  Returns the length of a Null-terminated Unicode string.
1325 
1326  This function returns the number of Unicode characters in the Null-terminated
1327  Unicode string specified by String.
1328 
1329  If String is NULL, then ASSERT().
1330  If String is not aligned on a 16-bit boundary, then ASSERT().
1331  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1332  PcdMaximumUnicodeStringLength Unicode characters not including the
1333  Null-terminator, then ASSERT().
1334 
1335  @param String Pointer to a Null-terminated Unicode string.
1336 
1337  @return The length of String.
1338 
1339 **/
1340 UINTN
1341 EFIAPI
1342 StrLen (
1343  IN CONST CHAR16 *String
1344  );
1345 
1346 /**
1347  Returns the size of a Null-terminated Unicode string in bytes, including the
1348  Null terminator.
1349 
1350  This function returns the size, in bytes, of the Null-terminated Unicode string
1351  specified by String.
1352 
1353  If String is NULL, then ASSERT().
1354  If String is not aligned on a 16-bit boundary, then ASSERT().
1355  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1356  PcdMaximumUnicodeStringLength Unicode characters not including the
1357  Null-terminator, then ASSERT().
1358 
1359  @param String The pointer to a Null-terminated Unicode string.
1360 
1361  @return The size of String.
1362 
1363 **/
1364 UINTN
1365 EFIAPI
1366 StrSize (
1367  IN CONST CHAR16 *String
1368  );
1369 
1370 /**
1371  Compares two Null-terminated Unicode strings, and returns the difference
1372  between the first mismatched Unicode characters.
1373 
1374  This function compares the Null-terminated Unicode string FirstString to the
1375  Null-terminated Unicode string SecondString. If FirstString is identical to
1376  SecondString, then 0 is returned. Otherwise, the value returned is the first
1377  mismatched Unicode character in SecondString subtracted from the first
1378  mismatched Unicode character in FirstString.
1379 
1380  If FirstString is NULL, then ASSERT().
1381  If FirstString is not aligned on a 16-bit boundary, then ASSERT().
1382  If SecondString is NULL, then ASSERT().
1383  If SecondString is not aligned on a 16-bit boundary, then ASSERT().
1384  If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
1385  than PcdMaximumUnicodeStringLength Unicode characters not including the
1386  Null-terminator, then ASSERT().
1387  If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
1388  than PcdMaximumUnicodeStringLength Unicode characters, not including the
1389  Null-terminator, then ASSERT().
1390 
1391  @param FirstString The pointer to a Null-terminated Unicode string.
1392  @param SecondString The pointer to a Null-terminated Unicode string.
1393 
1394  @retval 0 FirstString is identical to SecondString.
1395  @return others FirstString is not identical to SecondString.
1396 
1397 **/
1398 INTN
1399 EFIAPI
1400 StrCmp (
1401  IN CONST CHAR16 *FirstString,
1402  IN CONST CHAR16 *SecondString
1403  );
1404 
1405 /**
1406  Compares up to a specified length the contents of two Null-terminated Unicode strings,
1407  and returns the difference between the first mismatched Unicode characters.
1408 
1409  This function compares the Null-terminated Unicode string FirstString to the
1410  Null-terminated Unicode string SecondString. At most, Length Unicode
1411  characters will be compared. If Length is 0, then 0 is returned. If
1412  FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1413  value returned is the first mismatched Unicode character in SecondString
1414  subtracted from the first mismatched Unicode character in FirstString.
1415 
1416  If Length > 0 and FirstString is NULL, then ASSERT().
1417  If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
1418  If Length > 0 and SecondString is NULL, then ASSERT().
1419  If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
1420  If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1421  PcdMaximumUnicodeStringLength, then ASSERT().
1422  If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
1423  PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1424  then ASSERT().
1425  If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
1426  PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1427  then ASSERT().
1428 
1429  @param FirstString The pointer to a Null-terminated Unicode string.
1430  @param SecondString The pointer to a Null-terminated Unicode string.
1431  @param Length The maximum number of Unicode characters to compare.
1432 
1433  @retval 0 FirstString is identical to SecondString.
1434  @return others FirstString is not identical to SecondString.
1435 
1436 **/
1437 INTN
1438 EFIAPI
1439 StrnCmp (
1440  IN CONST CHAR16 *FirstString,
1441  IN CONST CHAR16 *SecondString,
1442  IN UINTN Length
1443  );
1444 
1445 /**
1446  Returns the first occurrence of a Null-terminated Unicode sub-string
1447  in a Null-terminated Unicode string.
1448 
1449  This function scans the contents of the Null-terminated Unicode string
1450  specified by String and returns the first occurrence of SearchString.
1451  If SearchString is not found in String, then NULL is returned. If
1452  the length of SearchString is zero, then String is returned.
1453 
1454  If String is NULL, then ASSERT().
1455  If String is not aligned on a 16-bit boundary, then ASSERT().
1456  If SearchString is NULL, then ASSERT().
1457  If SearchString is not aligned on a 16-bit boundary, then ASSERT().
1458 
1459  If PcdMaximumUnicodeStringLength is not zero, and SearchString
1460  or String contains more than PcdMaximumUnicodeStringLength Unicode
1461  characters, not including the Null-terminator, then ASSERT().
1462 
1463  @param String The pointer to a Null-terminated Unicode string.
1464  @param SearchString The pointer to a Null-terminated Unicode string to search for.
1465 
1466  @retval NULL If the SearchString does not appear in String.
1467  @return others If there is a match.
1468 
1469 **/
1470 CHAR16 *
1471 EFIAPI
1472 StrStr (
1473  IN CONST CHAR16 *String,
1474  IN CONST CHAR16 *SearchString
1475  );
1476 
1477 /**
1478  Convert a Null-terminated Unicode decimal string to a value of
1479  type UINTN.
1480 
1481  This function returns a value of type UINTN by interpreting the contents
1482  of the Unicode string specified by String as a decimal number. The format
1483  of the input Unicode string String is:
1484 
1485  [spaces] [decimal digits].
1486 
1487  The valid decimal digit character is in the range [0-9]. The
1488  function will ignore the pad space, which includes spaces or
1489  tab characters, before [decimal digits]. The running zero in the
1490  beginning of [decimal digits] will be ignored. Then, the function
1491  stops at the first character that is a not a valid decimal character
1492  or a Null-terminator, whichever one comes first.
1493 
1494  If String is NULL, then ASSERT().
1495  If String is not aligned in a 16-bit boundary, then ASSERT().
1496  If String has only pad spaces, then 0 is returned.
1497  If String has no pad spaces or valid decimal digits,
1498  then 0 is returned.
1499  If the number represented by String overflows according
1500  to the range defined by UINTN, then MAX_UINTN is returned.
1501 
1502  If PcdMaximumUnicodeStringLength is not zero, and String contains
1503  more than PcdMaximumUnicodeStringLength Unicode characters not including
1504  the Null-terminator, then ASSERT().
1505 
1506  @param String The pointer to a Null-terminated Unicode string.
1507 
1508  @retval Value translated from String.
1509 
1510 **/
1511 UINTN
1512 EFIAPI
1514  IN CONST CHAR16 *String
1515  );
1516 
1517 /**
1518  Convert a Null-terminated Unicode decimal string to a value of
1519  type UINT64.
1520 
1521  This function returns a value of type UINT64 by interpreting the contents
1522  of the Unicode string specified by String as a decimal number. The format
1523  of the input Unicode string String is:
1524 
1525  [spaces] [decimal digits].
1526 
1527  The valid decimal digit character is in the range [0-9]. The
1528  function will ignore the pad space, which includes spaces or
1529  tab characters, before [decimal digits]. The running zero in the
1530  beginning of [decimal digits] will be ignored. Then, the function
1531  stops at the first character that is a not a valid decimal character
1532  or a Null-terminator, whichever one comes first.
1533 
1534  If String is NULL, then ASSERT().
1535  If String is not aligned in a 16-bit boundary, then ASSERT().
1536  If String has only pad spaces, then 0 is returned.
1537  If String has no pad spaces or valid decimal digits,
1538  then 0 is returned.
1539  If the number represented by String overflows according
1540  to the range defined by UINT64, then MAX_UINT64 is returned.
1541 
1542  If PcdMaximumUnicodeStringLength is not zero, and String contains
1543  more than PcdMaximumUnicodeStringLength Unicode characters not including
1544  the Null-terminator, then ASSERT().
1545 
1546  @param String The pointer to a Null-terminated Unicode string.
1547 
1548  @retval Value translated from String.
1549 
1550 **/
1551 UINT64
1552 EFIAPI
1554  IN CONST CHAR16 *String
1555  );
1556 
1557 /**
1558  Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
1559 
1560  This function returns a value of type UINTN by interpreting the contents
1561  of the Unicode string specified by String as a hexadecimal number.
1562  The format of the input Unicode string String is:
1563 
1564  [spaces][zeros][x][hexadecimal digits].
1565 
1566  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1567  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1568  If "x" appears in the input string, it must be prefixed with at least one 0.
1569  The function will ignore the pad space, which includes spaces or tab characters,
1570  before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1571  [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1572  first valid hexadecimal digit. Then, the function stops at the first character
1573  that is a not a valid hexadecimal character or NULL, whichever one comes first.
1574 
1575  If String is NULL, then ASSERT().
1576  If String is not aligned in a 16-bit boundary, then ASSERT().
1577  If String has only pad spaces, then zero is returned.
1578  If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1579  then zero is returned.
1580  If the number represented by String overflows according to the range defined by
1581  UINTN, then MAX_UINTN is returned.
1582 
1583  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1584  PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1585  then ASSERT().
1586 
1587  @param String The pointer to a Null-terminated Unicode string.
1588 
1589  @retval Value translated from String.
1590 
1591 **/
1592 UINTN
1593 EFIAPI
1594 StrHexToUintn (
1595  IN CONST CHAR16 *String
1596  );
1597 
1598 /**
1599  Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
1600 
1601  This function returns a value of type UINT64 by interpreting the contents
1602  of the Unicode string specified by String as a hexadecimal number.
1603  The format of the input Unicode string String is
1604 
1605  [spaces][zeros][x][hexadecimal digits].
1606 
1607  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1608  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1609  If "x" appears in the input string, it must be prefixed with at least one 0.
1610  The function will ignore the pad space, which includes spaces or tab characters,
1611  before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1612  [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1613  first valid hexadecimal digit. Then, the function stops at the first character that is
1614  a not a valid hexadecimal character or NULL, whichever one comes first.
1615 
1616  If String is NULL, then ASSERT().
1617  If String is not aligned in a 16-bit boundary, then ASSERT().
1618  If String has only pad spaces, then zero is returned.
1619  If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1620  then zero is returned.
1621  If the number represented by String overflows according to the range defined by
1622  UINT64, then MAX_UINT64 is returned.
1623 
1624  If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1625  PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1626  then ASSERT().
1627 
1628  @param String The pointer to a Null-terminated Unicode string.
1629 
1630  @retval Value translated from String.
1631 
1632 **/
1633 UINT64
1634 EFIAPI
1636  IN CONST CHAR16 *String
1637  );
1638 
1639 /**
1640  Convert a Null-terminated Unicode string to IPv6 address and prefix length.
1641 
1642  This function outputs a value of type IPv6_ADDRESS and may output a value
1643  of type UINT8 by interpreting the contents of the Unicode string specified
1644  by String. The format of the input Unicode string String is as follows:
1645 
1646  X:X:X:X:X:X:X:X[/P]
1647 
1648  X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1649  [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1650  memory address and high byte is stored in high memory address. P contains decimal
1651  digit characters in the range [0-9]. The running zero in the beginning of P will
1652  be ignored. /P is optional.
1653 
1654  When /P is not in the String, the function stops at the first character that is
1655  not a valid hexadecimal digit character after eight X's are converted.
1656 
1657  When /P is in the String, the function stops at the first character that is not
1658  a valid decimal digit character after P is converted.
1659 
1660  "::" can be used to compress one or more groups of X when X contains only 0.
1661  The "::" can only appear once in the String.
1662 
1663  If String is not aligned in a 16-bit boundary, then ASSERT().
1664 
1665  If EndPointer is not NULL and Address is translated from String, a pointer
1666  to the character that stopped the scan is stored at the location pointed to
1667  by EndPointer.
1668 
1669  @param String Pointer to a Null-terminated Unicode string.
1670  @param EndPointer Pointer to character that stops scan.
1671  @param Address Pointer to the converted IPv6 address.
1672  @param PrefixLength Pointer to the converted IPv6 address prefix
1673  length. MAX_UINT8 is returned when /P is
1674  not in the String.
1675 
1676  @retval RETURN_SUCCESS Address is translated from String.
1677  @retval RETURN_INVALID_PARAMETER If String is NULL.
1678  If Data is NULL.
1679  @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1680  digit characters.
1681  If String contains "::" and number of X
1682  is not less than 8.
1683  If P starts with character that is not a
1684  valid decimal digit character.
1685  If the decimal number converted from P
1686  exceeds 128.
1687 
1688 **/
1690 EFIAPI
1692  IN CONST CHAR16 *String,
1693  OUT CHAR16 **EndPointer OPTIONAL,
1695  OUT UINT8 *PrefixLength OPTIONAL
1696  );
1697 
1698 /**
1699  Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1700 
1701  This function outputs a value of type IPv4_ADDRESS and may output a value
1702  of type UINT8 by interpreting the contents of the Unicode string specified
1703  by String. The format of the input Unicode string String is as follows:
1704 
1705  D.D.D.D[/P]
1706 
1707  D and P are decimal digit characters in the range [0-9]. The running zero in
1708  the beginning of D and P will be ignored. /P is optional.
1709 
1710  When /P is not in the String, the function stops at the first character that is
1711  not a valid decimal digit character after four D's are converted.
1712 
1713  When /P is in the String, the function stops at the first character that is not
1714  a valid decimal digit character after P is converted.
1715 
1716  If String is not aligned in a 16-bit boundary, then ASSERT().
1717 
1718  If EndPointer is not NULL and Address is translated from String, a pointer
1719  to the character that stopped the scan is stored at the location pointed to
1720  by EndPointer.
1721 
1722  @param String Pointer to a Null-terminated Unicode string.
1723  @param EndPointer Pointer to character that stops scan.
1724  @param Address Pointer to the converted IPv4 address.
1725  @param PrefixLength Pointer to the converted IPv4 address prefix
1726  length. MAX_UINT8 is returned when /P is
1727  not in the String.
1728 
1729  @retval RETURN_SUCCESS Address is translated from String.
1730  @retval RETURN_INVALID_PARAMETER If String is NULL.
1731  If Data is NULL.
1732  @retval RETURN_UNSUPPORTED If String is not in the correct format.
1733  If any decimal number converted from D
1734  exceeds 255.
1735  If the decimal number converted from P
1736  exceeds 32.
1737 
1738 **/
1740 EFIAPI
1742  IN CONST CHAR16 *String,
1743  OUT CHAR16 **EndPointer OPTIONAL,
1745  OUT UINT8 *PrefixLength OPTIONAL
1746  );
1747 
1748 #define GUID_STRING_LENGTH 36
1749 
1750 /**
1751  Convert a Null-terminated Unicode GUID string to a value of type
1752  EFI_GUID.
1753 
1754  This function outputs a GUID value by interpreting the contents of
1755  the Unicode string specified by String. The format of the input
1756  Unicode string String consists of 36 characters, as follows:
1757 
1758  aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1759 
1760  The pairs aa - pp are two characters in the range [0-9], [a-f] and
1761  [A-F], with each pair representing a single byte hexadecimal value.
1762 
1763  The mapping between String and the EFI_GUID structure is as follows:
1764  aa Data1[24:31]
1765  bb Data1[16:23]
1766  cc Data1[8:15]
1767  dd Data1[0:7]
1768  ee Data2[8:15]
1769  ff Data2[0:7]
1770  gg Data3[8:15]
1771  hh Data3[0:7]
1772  ii Data4[0:7]
1773  jj Data4[8:15]
1774  kk Data4[16:23]
1775  ll Data4[24:31]
1776  mm Data4[32:39]
1777  nn Data4[40:47]
1778  oo Data4[48:55]
1779  pp Data4[56:63]
1780 
1781  If String is not aligned in a 16-bit boundary, then ASSERT().
1782 
1783  @param String Pointer to a Null-terminated Unicode string.
1784  @param Guid Pointer to the converted GUID.
1785 
1786  @retval RETURN_SUCCESS Guid is translated from String.
1787  @retval RETURN_INVALID_PARAMETER If String is NULL.
1788  If Data is NULL.
1789  @retval RETURN_UNSUPPORTED If String is not as the above format.
1790 
1791 **/
1793 EFIAPI
1794 StrToGuid (
1795  IN CONST CHAR16 *String,
1796  OUT GUID *Guid
1797  );
1798 
1799 /**
1800  Convert a Null-terminated Unicode hexadecimal string to a byte array.
1801 
1802  This function outputs a byte array by interpreting the contents of
1803  the Unicode string specified by String in hexadecimal format. The format of
1804  the input Unicode string String is:
1805 
1806  [XX]*
1807 
1808  X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1809  The function decodes every two hexadecimal digit characters as one byte. The
1810  decoding stops after Length of characters and outputs Buffer containing
1811  (Length / 2) bytes.
1812 
1813  If String is not aligned in a 16-bit boundary, then ASSERT().
1814 
1815  @param String Pointer to a Null-terminated Unicode string.
1816  @param Length The number of Unicode characters to decode.
1817  @param Buffer Pointer to the converted bytes array.
1818  @param MaxBufferSize The maximum size of Buffer.
1819 
1820  @retval RETURN_SUCCESS Buffer is translated from String.
1821  @retval RETURN_INVALID_PARAMETER If String is NULL.
1822  If Data is NULL.
1823  If Length is not multiple of 2.
1824  If PcdMaximumUnicodeStringLength is not zero,
1825  and Length is greater than
1826  PcdMaximumUnicodeStringLength.
1827  @retval RETURN_UNSUPPORTED If Length of characters from String contain
1828  a character that is not valid hexadecimal
1829  digit characters, or a Null-terminator.
1830  @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
1831 **/
1833 EFIAPI
1834 StrHexToBytes (
1835  IN CONST CHAR16 *String,
1836  IN UINTN Length,
1837  OUT UINT8 *Buffer,
1838  IN UINTN MaxBufferSize
1839  );
1840 
1841 /**
1842  Convert a Null-terminated Unicode string to a Null-terminated
1843  ASCII string.
1844 
1845  This function is similar to AsciiStrCpyS.
1846 
1847  This function converts the content of the Unicode string Source
1848  to the ASCII string Destination by copying the lower 8 bits of
1849  each Unicode character. The function terminates the ASCII string
1850  Destination by appending a Null-terminator character at the end.
1851 
1852  The caller is responsible to make sure Destination points to a buffer with size
1853  equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1854 
1855  If any Unicode characters in Source contain non-zero value in
1856  the upper 8 bits, then ASSERT().
1857 
1858  If Source is not aligned on a 16-bit boundary, then ASSERT().
1859 
1860  If an error is returned, then the Destination is unmodified.
1861 
1862  @param Source The pointer to a Null-terminated Unicode string.
1863  @param Destination The pointer to a Null-terminated ASCII string.
1864  @param DestMax The maximum number of Destination Ascii
1865  char, including terminating null char.
1866 
1867  @retval RETURN_SUCCESS String is converted.
1868  @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1869  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1870  If Source is NULL.
1871  If PcdMaximumAsciiStringLength is not zero,
1872  and DestMax is greater than
1873  PcdMaximumAsciiStringLength.
1874  If PcdMaximumUnicodeStringLength is not zero,
1875  and DestMax is greater than
1876  PcdMaximumUnicodeStringLength.
1877  If DestMax is 0.
1878  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1879 
1880 **/
1882 EFIAPI
1884  IN CONST CHAR16 *Source,
1885  OUT CHAR8 *Destination,
1886  IN UINTN DestMax
1887  );
1888 
1889 /**
1890  Convert not more than Length successive characters from a Null-terminated
1891  Unicode string to a Null-terminated Ascii string. If no null char is copied
1892  from Source, then Destination[Length] is always set to null.
1893 
1894  This function converts not more than Length successive characters from the
1895  Unicode string Source to the Ascii string Destination by copying the lower 8
1896  bits of each Unicode character. The function terminates the Ascii string
1897  Destination by appending a Null-terminator character at the end.
1898 
1899  The caller is responsible to make sure Destination points to a buffer with size
1900  equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1901 
1902  If any Unicode characters in Source contain non-zero value in the upper 8
1903  bits, then ASSERT().
1904  If Source is not aligned on a 16-bit boundary, then ASSERT().
1905 
1906  If an error is returned, then the Destination is unmodified.
1907 
1908  @param Source The pointer to a Null-terminated Unicode string.
1909  @param Length The maximum number of Unicode characters to
1910  convert.
1911  @param Destination The pointer to a Null-terminated Ascii string.
1912  @param DestMax The maximum number of Destination Ascii
1913  char, including terminating null char.
1914  @param DestinationLength The number of Unicode characters converted.
1915 
1916  @retval RETURN_SUCCESS String is converted.
1917  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1918  If Source is NULL.
1919  If DestinationLength is NULL.
1920  If PcdMaximumAsciiStringLength is not zero,
1921  and Length or DestMax is greater than
1922  PcdMaximumAsciiStringLength.
1923  If PcdMaximumUnicodeStringLength is not
1924  zero, and Length or DestMax is greater than
1925  PcdMaximumUnicodeStringLength.
1926  If DestMax is 0.
1927  @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1928  MIN(StrLen(Source), Length).
1929  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1930 
1931 **/
1933 EFIAPI
1935  IN CONST CHAR16 *Source,
1936  IN UINTN Length,
1937  OUT CHAR8 *Destination,
1938  IN UINTN DestMax,
1939  OUT UINTN *DestinationLength
1940  );
1941 
1942 /**
1943  Returns the length of a Null-terminated ASCII string.
1944 
1945  This function returns the number of ASCII characters in the Null-terminated
1946  ASCII string specified by String.
1947 
1948  If Length > 0 and Destination is NULL, then ASSERT().
1949  If Length > 0 and Source is NULL, then ASSERT().
1950  If PcdMaximumAsciiStringLength is not zero and String contains more than
1951  PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1952  then ASSERT().
1953 
1954  @param String The pointer to a Null-terminated ASCII string.
1955 
1956  @return The length of String.
1957 
1958 **/
1959 UINTN
1960 EFIAPI
1961 AsciiStrLen (
1962  IN CONST CHAR8 *String
1963  );
1964 
1965 /**
1966  Returns the size of a Null-terminated ASCII string in bytes, including the
1967  Null terminator.
1968 
1969  This function returns the size, in bytes, of the Null-terminated ASCII string
1970  specified by String.
1971 
1972  If String is NULL, then ASSERT().
1973  If PcdMaximumAsciiStringLength is not zero and String contains more than
1974  PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1975  then ASSERT().
1976 
1977  @param String The pointer to a Null-terminated ASCII string.
1978 
1979  @return The size of String.
1980 
1981 **/
1982 UINTN
1983 EFIAPI
1984 AsciiStrSize (
1985  IN CONST CHAR8 *String
1986  );
1987 
1988 /**
1989  Compares two Null-terminated ASCII strings, and returns the difference
1990  between the first mismatched ASCII characters.
1991 
1992  This function compares the Null-terminated ASCII string FirstString to the
1993  Null-terminated ASCII string SecondString. If FirstString is identical to
1994  SecondString, then 0 is returned. Otherwise, the value returned is the first
1995  mismatched ASCII character in SecondString subtracted from the first
1996  mismatched ASCII character in FirstString.
1997 
1998  If FirstString is NULL, then ASSERT().
1999  If SecondString is NULL, then ASSERT().
2000  If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
2001  PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2002  then ASSERT().
2003  If PcdMaximumAsciiStringLength is not zero and SecondString contains more
2004  than PcdMaximumAsciiStringLength ASCII characters not including the
2005  Null-terminator, then ASSERT().
2006 
2007  @param FirstString The pointer to a Null-terminated ASCII string.
2008  @param SecondString The pointer to a Null-terminated ASCII string.
2009 
2010  @retval ==0 FirstString is identical to SecondString.
2011  @retval !=0 FirstString is not identical to SecondString.
2012 
2013 **/
2014 INTN
2015 EFIAPI
2016 AsciiStrCmp (
2017  IN CONST CHAR8 *FirstString,
2018  IN CONST CHAR8 *SecondString
2019  );
2020 
2021 /**
2022  Performs a case insensitive comparison of two Null-terminated ASCII strings,
2023  and returns the difference between the first mismatched ASCII characters.
2024 
2025  This function performs a case insensitive comparison of the Null-terminated
2026  ASCII string FirstString to the Null-terminated ASCII string SecondString. If
2027  FirstString is identical to SecondString, then 0 is returned. Otherwise, the
2028  value returned is the first mismatched lower case ASCII character in
2029  SecondString subtracted from the first mismatched lower case ASCII character
2030  in FirstString.
2031 
2032  If FirstString is NULL, then ASSERT().
2033  If SecondString is NULL, then ASSERT().
2034  If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
2035  PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2036  then ASSERT().
2037  If PcdMaximumAsciiStringLength is not zero and SecondString contains more
2038  than PcdMaximumAsciiStringLength ASCII characters not including the
2039  Null-terminator, then ASSERT().
2040 
2041  @param FirstString The pointer to a Null-terminated ASCII string.
2042  @param SecondString The pointer to a Null-terminated ASCII string.
2043 
2044  @retval ==0 FirstString is identical to SecondString using case insensitive
2045  comparisons.
2046  @retval !=0 FirstString is not identical to SecondString using case
2047  insensitive comparisons.
2048 
2049 **/
2050 INTN
2051 EFIAPI
2052 AsciiStriCmp (
2053  IN CONST CHAR8 *FirstString,
2054  IN CONST CHAR8 *SecondString
2055  );
2056 
2057 /**
2058  Compares two Null-terminated ASCII strings with maximum lengths, and returns
2059  the difference between the first mismatched ASCII characters.
2060 
2061  This function compares the Null-terminated ASCII string FirstString to the
2062  Null-terminated ASCII string SecondString. At most, Length ASCII characters
2063  will be compared. If Length is 0, then 0 is returned. If FirstString is
2064  identical to SecondString, then 0 is returned. Otherwise, the value returned
2065  is the first mismatched ASCII character in SecondString subtracted from the
2066  first mismatched ASCII character in FirstString.
2067 
2068  If Length > 0 and FirstString is NULL, then ASSERT().
2069  If Length > 0 and SecondString is NULL, then ASSERT().
2070  If PcdMaximumAsciiStringLength is not zero, and Length is greater than
2071  PcdMaximumAsciiStringLength, then ASSERT().
2072  If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
2073  PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2074  then ASSERT().
2075  If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
2076  PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2077  then ASSERT().
2078 
2079  @param FirstString The pointer to a Null-terminated ASCII string.
2080  @param SecondString The pointer to a Null-terminated ASCII string.
2081  @param Length The maximum number of ASCII characters for compare.
2082 
2083  @retval ==0 FirstString is identical to SecondString.
2084  @retval !=0 FirstString is not identical to SecondString.
2085 
2086 **/
2087 INTN
2088 EFIAPI
2089 AsciiStrnCmp (
2090  IN CONST CHAR8 *FirstString,
2091  IN CONST CHAR8 *SecondString,
2092  IN UINTN Length
2093  );
2094 
2095 /**
2096  Returns the first occurrence of a Null-terminated ASCII sub-string
2097  in a Null-terminated ASCII string.
2098 
2099  This function scans the contents of the ASCII string specified by String
2100  and returns the first occurrence of SearchString. If SearchString is not
2101  found in String, then NULL is returned. If the length of SearchString is zero,
2102  then String is returned.
2103 
2104  If String is NULL, then ASSERT().
2105  If SearchString is NULL, then ASSERT().
2106 
2107  If PcdMaximumAsciiStringLength is not zero, and SearchString or
2108  String contains more than PcdMaximumAsciiStringLength Unicode characters
2109  not including the Null-terminator, then ASSERT().
2110 
2111  @param String The pointer to a Null-terminated ASCII string.
2112  @param SearchString The pointer to a Null-terminated ASCII string to search for.
2113 
2114  @retval NULL If the SearchString does not appear in String.
2115  @retval others If there is a match return the first occurrence of SearchingString.
2116  If the length of SearchString is zero,return String.
2117 
2118 **/
2119 CHAR8 *
2120 EFIAPI
2121 AsciiStrStr (
2122  IN CONST CHAR8 *String,
2123  IN CONST CHAR8 *SearchString
2124  );
2125 
2126 /**
2127  Convert a Null-terminated ASCII decimal string to a value of type
2128  UINTN.
2129 
2130  This function returns a value of type UINTN by interpreting the contents
2131  of the ASCII string String as a decimal number. The format of the input
2132  ASCII string String is:
2133 
2134  [spaces] [decimal digits].
2135 
2136  The valid decimal digit character is in the range [0-9]. The function will
2137  ignore the pad space, which includes spaces or tab characters, before the digits.
2138  The running zero in the beginning of [decimal digits] will be ignored. Then, the
2139  function stops at the first character that is a not a valid decimal character or
2140  Null-terminator, whichever on comes first.
2141 
2142  If String has only pad spaces, then 0 is returned.
2143  If String has no pad spaces or valid decimal digits, then 0 is returned.
2144  If the number represented by String overflows according to the range defined by
2145  UINTN, then MAX_UINTN is returned.
2146  If String is NULL, then ASSERT().
2147  If PcdMaximumAsciiStringLength is not zero, and String contains more than
2148  PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2149  then ASSERT().
2150 
2151  @param String The pointer to a Null-terminated ASCII string.
2152 
2153  @retval The value translated from String.
2154 
2155 **/
2156 UINTN
2157 EFIAPI
2159  IN CONST CHAR8 *String
2160  );
2161 
2162 /**
2163  Convert a Null-terminated ASCII decimal string to a value of type
2164  UINT64.
2165 
2166  This function returns a value of type UINT64 by interpreting the contents
2167  of the ASCII string String as a decimal number. The format of the input
2168  ASCII string String is:
2169 
2170  [spaces] [decimal digits].
2171 
2172  The valid decimal digit character is in the range [0-9]. The function will
2173  ignore the pad space, which includes spaces or tab characters, before the digits.
2174  The running zero in the beginning of [decimal digits] will be ignored. Then, the
2175  function stops at the first character that is a not a valid decimal character or
2176  Null-terminator, whichever on comes first.
2177 
2178  If String has only pad spaces, then 0 is returned.
2179  If String has no pad spaces or valid decimal digits, then 0 is returned.
2180  If the number represented by String overflows according to the range defined by
2181  UINT64, then MAX_UINT64 is returned.
2182  If String is NULL, then ASSERT().
2183  If PcdMaximumAsciiStringLength is not zero, and String contains more than
2184  PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2185  then ASSERT().
2186 
2187  @param String The pointer to a Null-terminated ASCII string.
2188 
2189  @retval Value translated from String.
2190 
2191 **/
2192 UINT64
2193 EFIAPI
2195  IN CONST CHAR8 *String
2196  );
2197 
2198 /**
2199  Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
2200 
2201  This function returns a value of type UINTN by interpreting the contents of
2202  the ASCII string String as a hexadecimal number. The format of the input ASCII
2203  string String is:
2204 
2205  [spaces][zeros][x][hexadecimal digits].
2206 
2207  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2208  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2209  appears in the input string, it must be prefixed with at least one 0. The function
2210  will ignore the pad space, which includes spaces or tab characters, before [zeros],
2211  [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2212  will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2213  digit. Then, the function stops at the first character that is a not a valid
2214  hexadecimal character or Null-terminator, whichever on comes first.
2215 
2216  If String has only pad spaces, then 0 is returned.
2217  If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2218  0 is returned.
2219 
2220  If the number represented by String overflows according to the range defined by UINTN,
2221  then MAX_UINTN is returned.
2222  If String is NULL, then ASSERT().
2223  If PcdMaximumAsciiStringLength is not zero,
2224  and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2225  the Null-terminator, then ASSERT().
2226 
2227  @param String The pointer to a Null-terminated ASCII string.
2228 
2229  @retval Value translated from String.
2230 
2231 **/
2232 UINTN
2233 EFIAPI
2235  IN CONST CHAR8 *String
2236  );
2237 
2238 /**
2239  Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
2240 
2241  This function returns a value of type UINT64 by interpreting the contents of
2242  the ASCII string String as a hexadecimal number. The format of the input ASCII
2243  string String is:
2244 
2245  [spaces][zeros][x][hexadecimal digits].
2246 
2247  The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2248  The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2249  appears in the input string, it must be prefixed with at least one 0. The function
2250  will ignore the pad space, which includes spaces or tab characters, before [zeros],
2251  [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2252  will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2253  digit. Then, the function stops at the first character that is a not a valid
2254  hexadecimal character or Null-terminator, whichever on comes first.
2255 
2256  If String has only pad spaces, then 0 is returned.
2257  If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2258  0 is returned.
2259 
2260  If the number represented by String overflows according to the range defined by UINT64,
2261  then MAX_UINT64 is returned.
2262  If String is NULL, then ASSERT().
2263  If PcdMaximumAsciiStringLength is not zero,
2264  and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2265  the Null-terminator, then ASSERT().
2266 
2267  @param String The pointer to a Null-terminated ASCII string.
2268 
2269  @retval Value translated from String.
2270 
2271 **/
2272 UINT64
2273 EFIAPI
2275  IN CONST CHAR8 *String
2276  );
2277 
2278 /**
2279  Convert a Null-terminated ASCII string to IPv6 address and prefix length.
2280 
2281  This function outputs a value of type IPv6_ADDRESS and may output a value
2282  of type UINT8 by interpreting the contents of the ASCII string specified
2283  by String. The format of the input ASCII string String is as follows:
2284 
2285  X:X:X:X:X:X:X:X[/P]
2286 
2287  X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
2288  [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
2289  memory address and high byte is stored in high memory address. P contains decimal
2290  digit characters in the range [0-9]. The running zero in the beginning of P will
2291  be ignored. /P is optional.
2292 
2293  When /P is not in the String, the function stops at the first character that is
2294  not a valid hexadecimal digit character after eight X's are converted.
2295 
2296  When /P is in the String, the function stops at the first character that is not
2297  a valid decimal digit character after P is converted.
2298 
2299  "::" can be used to compress one or more groups of X when X contains only 0.
2300  The "::" can only appear once in the String.
2301 
2302  If EndPointer is not NULL and Address is translated from String, a pointer
2303  to the character that stopped the scan is stored at the location pointed to
2304  by EndPointer.
2305 
2306  @param String Pointer to a Null-terminated ASCII string.
2307  @param EndPointer Pointer to character that stops scan.
2308  @param Address Pointer to the converted IPv6 address.
2309  @param PrefixLength Pointer to the converted IPv6 address prefix
2310  length. MAX_UINT8 is returned when /P is
2311  not in the String.
2312 
2313  @retval RETURN_SUCCESS Address is translated from String.
2314  @retval RETURN_INVALID_PARAMETER If String is NULL.
2315  If Data is NULL.
2316  @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
2317  digit characters.
2318  If String contains "::" and number of X
2319  is not less than 8.
2320  If P starts with character that is not a
2321  valid decimal digit character.
2322  If the decimal number converted from P
2323  exceeds 128.
2324 
2325 **/
2327 EFIAPI
2329  IN CONST CHAR8 *String,
2330  OUT CHAR8 **EndPointer OPTIONAL,
2332  OUT UINT8 *PrefixLength OPTIONAL
2333  );
2334 
2335 /**
2336  Convert a Null-terminated ASCII string to IPv4 address and prefix length.
2337 
2338  This function outputs a value of type IPv4_ADDRESS and may output a value
2339  of type UINT8 by interpreting the contents of the ASCII string specified
2340  by String. The format of the input ASCII string String is as follows:
2341 
2342  D.D.D.D[/P]
2343 
2344  D and P are decimal digit characters in the range [0-9]. The running zero in
2345  the beginning of D and P will be ignored. /P is optional.
2346 
2347  When /P is not in the String, the function stops at the first character that is
2348  not a valid decimal digit character after four D's are converted.
2349 
2350  When /P is in the String, the function stops at the first character that is not
2351  a valid decimal digit character after P is converted.
2352 
2353  If EndPointer is not NULL and Address is translated from String, a pointer
2354  to the character that stopped the scan is stored at the location pointed to
2355  by EndPointer.
2356 
2357  @param String Pointer to a Null-terminated ASCII string.
2358  @param EndPointer Pointer to character that stops scan.
2359  @param Address Pointer to the converted IPv4 address.
2360  @param PrefixLength Pointer to the converted IPv4 address prefix
2361  length. MAX_UINT8 is returned when /P is
2362  not in the String.
2363 
2364  @retval RETURN_SUCCESS Address is translated from String.
2365  @retval RETURN_INVALID_PARAMETER If String is NULL.
2366  If Data is NULL.
2367  @retval RETURN_UNSUPPORTED If String is not in the correct format.
2368  If any decimal number converted from D
2369  exceeds 255.
2370  If the decimal number converted from P
2371  exceeds 32.
2372 
2373 **/
2375 EFIAPI
2377  IN CONST CHAR8 *String,
2378  OUT CHAR8 **EndPointer OPTIONAL,
2380  OUT UINT8 *PrefixLength OPTIONAL
2381  );
2382 
2383 /**
2384  Convert a Null-terminated ASCII GUID string to a value of type
2385  EFI_GUID.
2386 
2387  This function outputs a GUID value by interpreting the contents of
2388  the ASCII string specified by String. The format of the input
2389  ASCII string String consists of 36 characters, as follows:
2390 
2391  aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
2392 
2393  The pairs aa - pp are two characters in the range [0-9], [a-f] and
2394  [A-F], with each pair representing a single byte hexadecimal value.
2395 
2396  The mapping between String and the EFI_GUID structure is as follows:
2397  aa Data1[24:31]
2398  bb Data1[16:23]
2399  cc Data1[8:15]
2400  dd Data1[0:7]
2401  ee Data2[8:15]
2402  ff Data2[0:7]
2403  gg Data3[8:15]
2404  hh Data3[0:7]
2405  ii Data4[0:7]
2406  jj Data4[8:15]
2407  kk Data4[16:23]
2408  ll Data4[24:31]
2409  mm Data4[32:39]
2410  nn Data4[40:47]
2411  oo Data4[48:55]
2412  pp Data4[56:63]
2413 
2414  @param String Pointer to a Null-terminated ASCII string.
2415  @param Guid Pointer to the converted GUID.
2416 
2417  @retval RETURN_SUCCESS Guid is translated from String.
2418  @retval RETURN_INVALID_PARAMETER If String is NULL.
2419  If Data is NULL.
2420  @retval RETURN_UNSUPPORTED If String is not as the above format.
2421 
2422 **/
2424 EFIAPI
2426  IN CONST CHAR8 *String,
2427  OUT GUID *Guid
2428  );
2429 
2430 /**
2431  Convert a Null-terminated ASCII hexadecimal string to a byte array.
2432 
2433  This function outputs a byte array by interpreting the contents of
2434  the ASCII string specified by String in hexadecimal format. The format of
2435  the input ASCII string String is:
2436 
2437  [XX]*
2438 
2439  X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
2440  The function decodes every two hexadecimal digit characters as one byte. The
2441  decoding stops after Length of characters and outputs Buffer containing
2442  (Length / 2) bytes.
2443 
2444  @param String Pointer to a Null-terminated ASCII string.
2445  @param Length The number of ASCII characters to decode.
2446  @param Buffer Pointer to the converted bytes array.
2447  @param MaxBufferSize The maximum size of Buffer.
2448 
2449  @retval RETURN_SUCCESS Buffer is translated from String.
2450  @retval RETURN_INVALID_PARAMETER If String is NULL.
2451  If Data is NULL.
2452  If Length is not multiple of 2.
2453  If PcdMaximumAsciiStringLength is not zero,
2454  and Length is greater than
2455  PcdMaximumAsciiStringLength.
2456  @retval RETURN_UNSUPPORTED If Length of characters from String contain
2457  a character that is not valid hexadecimal
2458  digit characters, or a Null-terminator.
2459  @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
2460 **/
2462 EFIAPI
2464  IN CONST CHAR8 *String,
2465  IN UINTN Length,
2466  OUT UINT8 *Buffer,
2467  IN UINTN MaxBufferSize
2468  );
2469 
2470 /**
2471  Convert one Null-terminated ASCII string to a Null-terminated
2472  Unicode string.
2473 
2474  This function is similar to StrCpyS.
2475 
2476  This function converts the contents of the ASCII string Source to the Unicode
2477  string Destination. The function terminates the Unicode string Destination by
2478  appending a Null-terminator character at the end.
2479 
2480  The caller is responsible to make sure Destination points to a buffer with size
2481  equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2482 
2483  If Destination is not aligned on a 16-bit boundary, then ASSERT().
2484 
2485  If an error is returned, then the Destination is unmodified.
2486 
2487  @param Source The pointer to a Null-terminated ASCII string.
2488  @param Destination The pointer to a Null-terminated Unicode string.
2489  @param DestMax The maximum number of Destination Unicode
2490  char, including terminating null char.
2491 
2492  @retval RETURN_SUCCESS String is converted.
2493  @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2494  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2495  If Source is NULL.
2496  If PcdMaximumUnicodeStringLength is not zero,
2497  and DestMax is greater than
2498  PcdMaximumUnicodeStringLength.
2499  If PcdMaximumAsciiStringLength is not zero,
2500  and DestMax is greater than
2501  PcdMaximumAsciiStringLength.
2502  If DestMax is 0.
2503  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2504 
2505 **/
2507 EFIAPI
2509  IN CONST CHAR8 *Source,
2510  OUT CHAR16 *Destination,
2511  IN UINTN DestMax
2512  );
2513 
2514 /**
2515  Convert not more than Length successive characters from a Null-terminated
2516  Ascii string to a Null-terminated Unicode string. If no null char is copied
2517  from Source, then Destination[Length] is always set to null.
2518 
2519  This function converts not more than Length successive characters from the
2520  Ascii string Source to the Unicode string Destination. The function
2521  terminates the Unicode string Destination by appending a Null-terminator
2522  character at the end.
2523 
2524  The caller is responsible to make sure Destination points to a buffer with
2525  size not smaller than
2526  ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2527 
2528  If Destination is not aligned on a 16-bit boundary, then ASSERT().
2529 
2530  If an error is returned, then Destination and DestinationLength are
2531  unmodified.
2532 
2533  @param Source The pointer to a Null-terminated Ascii string.
2534  @param Length The maximum number of Ascii characters to convert.
2535  @param Destination The pointer to a Null-terminated Unicode string.
2536  @param DestMax The maximum number of Destination Unicode char,
2537  including terminating null char.
2538  @param DestinationLength The number of Ascii characters converted.
2539 
2540  @retval RETURN_SUCCESS String is converted.
2541  @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2542  If Source is NULL.
2543  If DestinationLength is NULL.
2544  If PcdMaximumUnicodeStringLength is not
2545  zero, and Length or DestMax is greater than
2546  PcdMaximumUnicodeStringLength.
2547  If PcdMaximumAsciiStringLength is not zero,
2548  and Length or DestMax is greater than
2549  PcdMaximumAsciiStringLength.
2550  If DestMax is 0.
2551  @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2552  MIN(AsciiStrLen(Source), Length).
2553  @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2554 
2555 **/
2557 EFIAPI
2559  IN CONST CHAR8 *Source,
2560  IN UINTN Length,
2561  OUT CHAR16 *Destination,
2562  IN UINTN DestMax,
2563  OUT UINTN *DestinationLength
2564  );
2565 
2566 /**
2567  Convert a Unicode character to upper case only if
2568  it maps to a valid small-case ASCII character.
2569 
2570  This internal function only deal with Unicode character
2571  which maps to a valid small-case ASCII character, i.e.
2572  L'a' to L'z'. For other Unicode character, the input character
2573  is returned directly.
2574 
2575  @param Char The character to convert.
2576 
2577  @retval LowerCharacter If the Char is with range L'a' to L'z'.
2578  @retval Unchanged Otherwise.
2579 
2580 **/
2581 CHAR16
2582 EFIAPI
2583 CharToUpper (
2584  IN CHAR16 Char
2585  );
2586 
2587 /**
2588  Converts a lowercase Ascii character to upper one.
2589 
2590  If Chr is lowercase Ascii character, then converts it to upper one.
2591 
2592  If Value >= 0xA0, then ASSERT().
2593  If (Value & 0x0F) >= 0x0A, then ASSERT().
2594 
2595  @param Chr one Ascii character
2596 
2597  @return The uppercase value of Ascii character
2598 
2599 **/
2600 CHAR8
2601 EFIAPI
2603  IN CHAR8 Chr
2604  );
2605 
2606 /**
2607  Convert binary data to a Base64 encoded ascii string based on RFC4648.
2608 
2609  Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize.
2610  The Ascii string is produced by converting the data string specified by Source and SourceLength.
2611 
2612  @param Source Input UINT8 data
2613  @param SourceLength Number of UINT8 bytes of data
2614  @param Destination Pointer to output string buffer
2615  @param DestinationSize Size of ascii buffer. Set to 0 to get the size needed.
2616  Caller is responsible for passing in buffer of DestinationSize
2617 
2618  @retval RETURN_SUCCESS When ascii buffer is filled in.
2619  @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
2620  @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination).
2621  @retval RETURN_BUFFER_TOO_SMALL If SourceLength is 0 and DestinationSize is <1.
2622  @retval RETURN_BUFFER_TOO_SMALL If Destination is NULL or DestinationSize is smaller than required buffersize.
2623 
2624 **/
2626 EFIAPI
2627 Base64Encode (
2628  IN CONST UINT8 *Source,
2629  IN UINTN SourceLength,
2630  OUT CHAR8 *Destination OPTIONAL,
2631  IN OUT UINTN *DestinationSize
2632  );
2633 
2634 /**
2635  Decode Base64 ASCII encoded data to 8-bit binary representation, based on
2636  RFC4648.
2637 
2638  Decoding occurs according to "Table 1: The Base 64 Alphabet" in RFC4648.
2639 
2640  Whitespace is ignored at all positions:
2641  - 0x09 ('\t') horizontal tab
2642  - 0x0A ('\n') new line
2643  - 0x0B ('\v') vertical tab
2644  - 0x0C ('\f') form feed
2645  - 0x0D ('\r') carriage return
2646  - 0x20 (' ') space
2647 
2648  The minimum amount of required padding (with ASCII 0x3D, '=') is tolerated
2649  and enforced at the end of the Base64 ASCII encoded data, and only there.
2650 
2651  Other characters outside of the encoding alphabet cause the function to
2652  reject the Base64 ASCII encoded data.
2653 
2654  @param[in] Source Array of CHAR8 elements containing the Base64
2655  ASCII encoding. May be NULL if SourceSize is
2656  zero.
2657 
2658  @param[in] SourceSize Number of CHAR8 elements in Source.
2659 
2660  @param[out] Destination Array of UINT8 elements receiving the decoded
2661  8-bit binary representation. Allocated by the
2662  caller. May be NULL if DestinationSize is
2663  zero on input. If NULL, decoding is
2664  performed, but the 8-bit binary
2665  representation is not stored. If non-NULL and
2666  the function returns an error, the contents
2667  of Destination are indeterminate.
2668 
2669  @param[in,out] DestinationSize On input, the number of UINT8 elements that
2670  the caller allocated for Destination. On
2671  output, if the function returns
2672  RETURN_SUCCESS or RETURN_BUFFER_TOO_SMALL,
2673  the number of UINT8 elements that are
2674  required for decoding the Base64 ASCII
2675  representation. If the function returns a
2676  value different from both RETURN_SUCCESS and
2677  RETURN_BUFFER_TOO_SMALL, then DestinationSize
2678  is indeterminate on output.
2679 
2680  @retval RETURN_SUCCESS SourceSize CHAR8 elements at Source have
2681  been decoded to on-output DestinationSize
2682  UINT8 elements at Destination. Note that
2683  RETURN_SUCCESS covers the case when
2684  DestinationSize is zero on input, and
2685  Source decodes to zero bytes (due to
2686  containing at most ignored whitespace).
2687 
2688  @retval RETURN_BUFFER_TOO_SMALL The input value of DestinationSize is not
2689  large enough for decoding SourceSize CHAR8
2690  elements at Source. The required number of
2691  UINT8 elements has been stored to
2692  DestinationSize.
2693 
2694  @retval RETURN_INVALID_PARAMETER DestinationSize is NULL.
2695 
2696  @retval RETURN_INVALID_PARAMETER Source is NULL, but SourceSize is not zero.
2697 
2698  @retval RETURN_INVALID_PARAMETER Destination is NULL, but DestinationSize is
2699  not zero on input.
2700 
2701  @retval RETURN_INVALID_PARAMETER Source is non-NULL, and (Source +
2702  SourceSize) would wrap around MAX_ADDRESS.
2703 
2704  @retval RETURN_INVALID_PARAMETER Destination is non-NULL, and (Destination +
2705  DestinationSize) would wrap around
2706  MAX_ADDRESS, as specified on input.
2707 
2708  @retval RETURN_INVALID_PARAMETER None of Source and Destination are NULL,
2709  and CHAR8[SourceSize] at Source overlaps
2710  UINT8[DestinationSize] at Destination, as
2711  specified on input.
2712 
2713  @retval RETURN_INVALID_PARAMETER Invalid CHAR8 element encountered in
2714  Source.
2715 **/
2717 EFIAPI
2718 Base64Decode (
2719  IN CONST CHAR8 *Source OPTIONAL,
2720  IN UINTN SourceSize,
2721  OUT UINT8 *Destination OPTIONAL,
2722  IN OUT UINTN *DestinationSize
2723  );
2724 
2725 /**
2726  Converts an 8-bit value to an 8-bit BCD value.
2727 
2728  Converts the 8-bit value specified by Value to BCD. The BCD value is
2729  returned.
2730 
2731  If Value >= 100, then ASSERT().
2732 
2733  @param Value The 8-bit value to convert to BCD. Range 0..99.
2734 
2735  @return The BCD value.
2736 
2737 **/
2738 UINT8
2739 EFIAPI
2740 DecimalToBcd8 (
2741  IN UINT8 Value
2742  );
2743 
2744 /**
2745  Converts an 8-bit BCD value to an 8-bit value.
2746 
2747  Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2748  value is returned.
2749 
2750  If Value >= 0xA0, then ASSERT().
2751  If (Value & 0x0F) >= 0x0A, then ASSERT().
2752 
2753  @param Value The 8-bit BCD value to convert to an 8-bit value.
2754 
2755  @return The 8-bit value is returned.
2756 
2757 **/
2758 UINT8
2759 EFIAPI
2760 BcdToDecimal8 (
2761  IN UINT8 Value
2762  );
2763 
2764 //
2765 // File Path Manipulation Functions
2766 //
2767 
2768 /**
2769  Removes the last directory or file entry in a path.
2770 
2771  @param[in, out] Path The pointer to the path to modify.
2772 
2773  @retval FALSE Nothing was found to remove.
2774  @retval TRUE A directory or file was removed.
2775 **/
2776 BOOLEAN
2777 EFIAPI
2779  IN OUT CHAR16 *Path
2780  );
2781 
2782 /**
2783  Function to clean up paths.
2784  - Single periods in the path are removed.
2785  - Double periods in the path are removed along with a single parent directory.
2786  - Forward slashes L'/' are converted to backward slashes L'\'.
2787 
2788  This will be done inline and the existing buffer may be larger than required
2789  upon completion.
2790 
2791  @param[in] Path The pointer to the string containing the path.
2792 
2793  @return Returns Path, otherwise returns NULL to indicate that an error has occurred.
2794 **/
2795 CHAR16 *
2796 EFIAPI
2798  IN CHAR16 *Path
2799  );
2800 
2801 //
2802 // Linked List Functions and Macros
2803 //
2804 
2805 /**
2806  Initializes the head node of a doubly linked list that is declared as a
2807  global variable in a module.
2808 
2809  Initializes the forward and backward links of a new linked list. After
2810  initializing a linked list with this macro, the other linked list functions
2811  may be used to add and remove nodes from the linked list. This macro results
2812  in smaller executables by initializing the linked list in the data section,
2813  instead if calling the InitializeListHead() function to perform the
2814  equivalent operation.
2815 
2816  @param ListHead The head note of a list to initialize.
2817 
2818 **/
2819 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}
2820 
2821 /**
2822  Iterates over each node in a doubly linked list using each node's forward link.
2823 
2824  @param Entry A pointer to a list node used as a loop cursor during iteration
2825  @param ListHead The head node of the doubly linked list
2826 
2827 **/
2828 #define BASE_LIST_FOR_EACH(Entry, ListHead) \
2829  for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink)
2830 
2831 /**
2832  Iterates over each node in a doubly linked list using each node's forward link
2833  with safety against node removal.
2834 
2835  This macro uses NextEntry to temporarily store the next list node so the node
2836  pointed to by Entry may be deleted in the current loop iteration step and
2837  iteration can continue from the node pointed to by NextEntry.
2838 
2839  @param Entry A pointer to a list node used as a loop cursor during iteration
2840  @param NextEntry A pointer to a list node used to temporarily store the next node
2841  @param ListHead The head node of the doubly linked list
2842 
2843 **/
2844 #define BASE_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \
2845  for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\
2846  Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)
2847 
2848 /**
2849  Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
2850  list.
2851 
2852  If FirstEntry is NULL, then ASSERT().
2853  If FirstEntry->ForwardLink is NULL, then ASSERT().
2854  If FirstEntry->BackLink is NULL, then ASSERT().
2855  If SecondEntry is NULL, then ASSERT();
2856  If PcdMaximumLinkedListLength is not zero, and List contains more than
2857  PcdMaximumLinkedListLength nodes, then ASSERT().
2858 
2859  @param FirstEntry A pointer to a node in a linked list.
2860  @param SecondEntry A pointer to the node to locate.
2861 
2862  @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry.
2863  @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry,
2864  or FirstEntry is invalid.
2865 
2866 **/
2867 BOOLEAN
2868 EFIAPI
2869 IsNodeInList (
2870  IN CONST LIST_ENTRY *FirstEntry,
2871  IN CONST LIST_ENTRY *SecondEntry
2872  );
2873 
2874 /**
2875  Initializes the head node of a doubly linked list, and returns the pointer to
2876  the head node of the doubly linked list.
2877 
2878  Initializes the forward and backward links of a new linked list. After
2879  initializing a linked list with this function, the other linked list
2880  functions may be used to add and remove nodes from the linked list. It is up
2881  to the caller of this function to allocate the memory for ListHead.
2882 
2883  If ListHead is NULL, then ASSERT().
2884 
2885  @param ListHead A pointer to the head node of a new doubly linked list.
2886 
2887  @return ListHead
2888 
2889 **/
2890 LIST_ENTRY *
2891 EFIAPI
2893  IN OUT LIST_ENTRY *ListHead
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
2921  IN OUT LIST_ENTRY *ListHead,
2922  IN OUT LIST_ENTRY *Entry
2923  );
2924 
2925 /**
2926  Adds a node to the end of a doubly linked list, and returns the pointer to
2927  the head node of the doubly linked list.
2928 
2929  Adds the node Entry to the end of the doubly linked list denoted by ListHead,
2930  and returns ListHead.
2931 
2932  If ListHead is NULL, then ASSERT().
2933  If Entry is NULL, then ASSERT().
2934  If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2935  InitializeListHead(), then ASSERT().
2936  If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2937  of nodes in ListHead, including the ListHead node, is greater than or
2938  equal to PcdMaximumLinkedListLength, then ASSERT().
2939 
2940  @param ListHead A pointer to the head node of a doubly linked list.
2941  @param Entry A pointer to a node that is to be added at the end of the
2942  doubly linked list.
2943 
2944  @return ListHead
2945 
2946 **/
2947 LIST_ENTRY *
2948 EFIAPI
2950  IN OUT LIST_ENTRY *ListHead,
2951  IN OUT LIST_ENTRY *Entry
2952  );
2953 
2954 /**
2955  Retrieves the first node of a doubly linked list.
2956 
2957  Returns the first node of a doubly linked list. List must have been
2958  initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2959  If List is empty, then List is returned.
2960 
2961  If List is NULL, then ASSERT().
2962  If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2963  InitializeListHead(), then ASSERT().
2964  If PcdMaximumLinkedListLength is not zero, and the number of nodes
2965  in List, including the List node, is greater than or equal to
2966  PcdMaximumLinkedListLength, then ASSERT().
2967 
2968  @param List A pointer to the head node of a doubly linked list.
2969 
2970  @return The first node of a doubly linked list.
2971  @retval List The list is empty.
2972 
2973 **/
2974 LIST_ENTRY *
2975 EFIAPI
2976 GetFirstNode (
2977  IN CONST LIST_ENTRY *List
2978  );
2979 
2980 /**
2981  Retrieves the next node of a doubly linked list.
2982 
2983  Returns the node of a doubly linked list that follows Node.
2984  List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2985  or InitializeListHead(). If List is empty, then List is returned.
2986 
2987  If List is NULL, then ASSERT().
2988  If Node is NULL, then ASSERT().
2989  If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2990  InitializeListHead(), then ASSERT().
2991  If PcdMaximumLinkedListLength is not zero, and List contains more than
2992  PcdMaximumLinkedListLength nodes, then ASSERT().
2993  If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2994 
2995  @param List A pointer to the head node of a doubly linked list.
2996  @param Node A pointer to a node in the doubly linked list.
2997 
2998  @return The pointer to the next node if one exists. Otherwise List is returned.
2999 
3000 **/
3001 LIST_ENTRY *
3002 EFIAPI
3003 GetNextNode (
3004  IN CONST LIST_ENTRY *List,
3005  IN CONST LIST_ENTRY *Node
3006  );
3007 
3008 /**
3009  Retrieves the previous node of a doubly linked list.
3010 
3011  Returns the node of a doubly linked list that precedes Node.
3012  List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3013  or InitializeListHead(). If List is empty, then List is returned.
3014 
3015  If List is NULL, then ASSERT().
3016  If Node is NULL, then ASSERT().
3017  If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3018  InitializeListHead(), then ASSERT().
3019  If PcdMaximumLinkedListLength is not zero, and List contains more than
3020  PcdMaximumLinkedListLength nodes, then ASSERT().
3021  If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3022 
3023  @param List A pointer to the head node of a doubly linked list.
3024  @param Node A pointer to a node in the doubly linked list.
3025 
3026  @return The pointer to the previous node if one exists. Otherwise List is returned.
3027 
3028 **/
3029 LIST_ENTRY *
3030 EFIAPI
3032  IN CONST LIST_ENTRY *List,
3033  IN CONST LIST_ENTRY *Node
3034  );
3035 
3036 /**
3037  Checks to see if a doubly linked list is empty or not.
3038 
3039  Checks to see if the doubly linked list is empty. If the linked list contains
3040  zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
3041 
3042  If ListHead is NULL, then ASSERT().
3043  If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3044  InitializeListHead(), then ASSERT().
3045  If PcdMaximumLinkedListLength is not zero, and the number of nodes
3046  in List, including the List node, is greater than or equal to
3047  PcdMaximumLinkedListLength, then ASSERT().
3048 
3049  @param ListHead A pointer to the head node of a doubly linked list.
3050 
3051  @retval TRUE The linked list is empty.
3052  @retval FALSE The linked list is not empty.
3053 
3054 **/
3055 BOOLEAN
3056 EFIAPI
3057 IsListEmpty (
3058  IN CONST LIST_ENTRY *ListHead
3059  );
3060 
3061 /**
3062  Determines if a node in a doubly linked list is the head node of a the same
3063  doubly linked list. This function is typically used to terminate a loop that
3064  traverses all the nodes in a doubly linked list starting with the head node.
3065 
3066  Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the
3067  nodes in the doubly linked list specified by List. List must have been
3068  initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3069 
3070  If List is NULL, then ASSERT().
3071  If Node is NULL, then ASSERT().
3072  If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
3073  then ASSERT().
3074  If PcdMaximumLinkedListLength is not zero, and the number of nodes
3075  in List, including the List node, is greater than or equal to
3076  PcdMaximumLinkedListLength, then ASSERT().
3077  If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
3078  to List, then ASSERT().
3079 
3080  @param List A pointer to the head node of a doubly linked list.
3081  @param Node A pointer to a node in the doubly linked list.
3082 
3083  @retval TRUE Node is the head of the doubly-linked list pointed by List.
3084  @retval FALSE Node is not the head of the doubly-linked list pointed by List.
3085 
3086 **/
3087 BOOLEAN
3088 EFIAPI
3089 IsNull (
3090  IN CONST LIST_ENTRY *List,
3091  IN CONST LIST_ENTRY *Node
3092  );
3093 
3094 /**
3095  Determines if a node the last node in a doubly linked list.
3096 
3097  Returns TRUE if Node is the last node in the doubly linked list specified by
3098  List. Otherwise, FALSE is returned. List must have been initialized with
3099  INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3100 
3101  If List is NULL, then ASSERT().
3102  If Node is NULL, then ASSERT().
3103  If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3104  InitializeListHead(), then ASSERT().
3105  If PcdMaximumLinkedListLength is not zero, and the number of nodes
3106  in List, including the List node, is greater than or equal to
3107  PcdMaximumLinkedListLength, then ASSERT().
3108  If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3109 
3110  @param List A pointer to the head node of a doubly linked list.
3111  @param Node A pointer to a node in the doubly linked list.
3112 
3113  @retval TRUE Node is the last node in the linked list.
3114  @retval FALSE Node is not the last node in the linked list.
3115 
3116 **/
3117 BOOLEAN
3118 EFIAPI
3119 IsNodeAtEnd (
3120  IN CONST LIST_ENTRY *List,
3121  IN CONST LIST_ENTRY *Node
3122  );
3123 
3124 /**
3125  Swaps the location of two nodes in a doubly linked list, and returns the
3126  first node after the swap.
3127 
3128  If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
3129  Otherwise, the location of the FirstEntry node is swapped with the location
3130  of the SecondEntry node in a doubly linked list. SecondEntry must be in the
3131  same double linked list as FirstEntry and that double linked list must have
3132  been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3133  SecondEntry is returned after the nodes are swapped.
3134 
3135  If FirstEntry is NULL, then ASSERT().
3136  If SecondEntry is NULL, then ASSERT().
3137  If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
3138  same linked list, then ASSERT().
3139  If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3140  linked list containing the FirstEntry and SecondEntry nodes, including
3141  the FirstEntry and SecondEntry nodes, is greater than or equal to
3142  PcdMaximumLinkedListLength, then ASSERT().
3143 
3144  @param FirstEntry A pointer to a node in a linked list.
3145  @param SecondEntry A pointer to another node in the same linked list.
3146 
3147  @return SecondEntry.
3148 
3149 **/
3150 LIST_ENTRY *
3151 EFIAPI
3153  IN OUT LIST_ENTRY *FirstEntry,
3154  IN OUT LIST_ENTRY *SecondEntry
3155  );
3156 
3157 /**
3158  Removes a node from a doubly linked list, and returns the node that follows
3159  the removed node.
3160 
3161  Removes the node Entry from a doubly linked list. It is up to the caller of
3162  this function to release the memory used by this node if that is required. On
3163  exit, the node following Entry in the doubly linked list is returned. If
3164  Entry is the only node in the linked list, then the head node of the linked
3165  list is returned.
3166 
3167  If Entry is NULL, then ASSERT().
3168  If Entry is the head node of an empty list, then ASSERT().
3169  If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3170  linked list containing Entry, including the Entry node, is greater than
3171  or equal to PcdMaximumLinkedListLength, then ASSERT().
3172 
3173  @param Entry A pointer to a node in a linked list.
3174 
3175  @return Entry.
3176 
3177 **/
3178 LIST_ENTRY *
3179 EFIAPI
3181  IN CONST LIST_ENTRY *Entry
3182  );
3183 
3184 //
3185 // Math Services
3186 //
3187 
3188 /**
3189  Prototype for comparison function for any two element types.
3190 
3191  @param[in] Buffer1 The pointer to first buffer.
3192  @param[in] Buffer2 The pointer to second buffer.
3193 
3194  @retval 0 Buffer1 equal to Buffer2.
3195  @return <0 Buffer1 is less than Buffer2.
3196  @return >0 Buffer1 is greater than Buffer2.
3197 **/
3198 typedef
3199 INTN
3201  IN CONST VOID *Buffer1,
3202  IN CONST VOID *Buffer2
3203  );
3204 
3205 /**
3206  This function is identical to perform QuickSort,
3207  except that is uses the pre-allocated buffer so the in place sorting does not need to
3208  allocate and free buffers constantly.
3209 
3210  Each element must be equal sized.
3211 
3212  if BufferToSort is NULL, then ASSERT.
3213  if CompareFunction is NULL, then ASSERT.
3214  if BufferOneElement is NULL, then ASSERT.
3215  if ElementSize is < 1, then ASSERT.
3216 
3217  if Count is < 2 then perform no action.
3218 
3219  @param[in, out] BufferToSort on call a Buffer of (possibly sorted) elements
3220  on return a buffer of sorted elements
3221  @param[in] Count the number of elements in the buffer to sort
3222  @param[in] ElementSize Size of an element in bytes
3223  @param[in] CompareFunction The function to call to perform the comparison
3224  of any 2 elements
3225  @param[out] BufferOneElement Caller provided buffer whose size equals to ElementSize.
3226  It's used by QuickSort() for swapping in sorting.
3227 **/
3228 VOID
3229 EFIAPI
3230 QuickSort (
3231  IN OUT VOID *BufferToSort,
3232  IN CONST UINTN Count,
3233  IN CONST UINTN ElementSize,
3234  IN BASE_SORT_COMPARE CompareFunction,
3235  OUT VOID *BufferOneElement
3236  );
3237 
3238 /**
3239  Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
3240  with zeros. The shifted value is returned.
3241 
3242  This function shifts the 64-bit value Operand to the left by Count bits. The
3243  low Count bits are set to zero. The shifted value is returned.
3244 
3245  If Count is greater than 63, then ASSERT().
3246 
3247  @param Operand The 64-bit operand to shift left.
3248  @param Count The number of bits to shift left.
3249 
3250  @return Operand << Count.
3251 
3252 **/
3253 UINT64
3254 EFIAPI
3255 LShiftU64 (
3256  IN UINT64 Operand,
3257  IN UINTN Count
3258  );
3259 
3260 /**
3261  Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
3262  filled with zeros. The shifted value is returned.
3263 
3264  This function shifts the 64-bit value Operand to the right by Count bits. The
3265  high Count bits are set to zero. The shifted value is returned.
3266 
3267  If Count is greater than 63, then ASSERT().
3268 
3269  @param Operand The 64-bit operand to shift right.
3270  @param Count The number of bits to shift right.
3271 
3272  @return Operand >> Count
3273 
3274 **/
3275 UINT64
3276 EFIAPI
3277 RShiftU64 (
3278  IN UINT64 Operand,
3279  IN UINTN Count
3280  );
3281 
3282 /**
3283  Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
3284  with original integer's bit 63. The shifted value is returned.
3285 
3286  This function shifts the 64-bit value Operand to the right by Count bits. The
3287  high Count bits are set to bit 63 of Operand. The shifted value is returned.
3288 
3289  If Count is greater than 63, then ASSERT().
3290 
3291  @param Operand The 64-bit operand to shift right.
3292  @param Count The number of bits to shift right.
3293 
3294  @return Operand >> Count
3295 
3296 **/
3297 UINT64
3298 EFIAPI
3299 ARShiftU64 (
3300  IN UINT64 Operand,
3301  IN UINTN Count
3302  );
3303 
3304 /**
3305  Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
3306  with the high bits that were rotated.
3307 
3308  This function rotates the 32-bit value Operand to the left by Count bits. The
3309  low Count bits are fill with the high Count bits of Operand. The rotated
3310  value is returned.
3311 
3312  If Count is greater than 31, then ASSERT().
3313 
3314  @param Operand The 32-bit operand to rotate left.
3315  @param Count The number of bits to rotate left.
3316 
3317  @return Operand << Count
3318 
3319 **/
3320 UINT32
3321 EFIAPI
3322 LRotU32 (
3323  IN UINT32 Operand,
3324  IN UINTN Count
3325  );
3326 
3327 /**
3328  Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
3329  with the low bits that were rotated.
3330 
3331  This function rotates the 32-bit value Operand to the right by Count bits.
3332  The high Count bits are fill with the low Count bits of Operand. The rotated
3333  value is returned.
3334 
3335  If Count is greater than 31, then ASSERT().
3336 
3337  @param Operand The 32-bit operand to rotate right.
3338  @param Count The number of bits to rotate right.
3339 
3340  @return Operand >> Count
3341 
3342 **/
3343 UINT32
3344 EFIAPI
3345 RRotU32 (
3346  IN UINT32 Operand,
3347  IN UINTN Count
3348  );
3349 
3350 /**
3351  Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
3352  with the high bits that were rotated.
3353 
3354  This function rotates the 64-bit value Operand to the left by Count bits. The
3355  low Count bits are fill with the high Count bits of Operand. The rotated
3356  value is returned.
3357 
3358  If Count is greater than 63, then ASSERT().
3359 
3360  @param Operand The 64-bit operand to rotate left.
3361  @param Count The number of bits to rotate left.
3362 
3363  @return Operand << Count
3364 
3365 **/
3366 UINT64
3367 EFIAPI
3368 LRotU64 (
3369  IN UINT64 Operand,
3370  IN UINTN Count
3371  );
3372 
3373 /**
3374  Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
3375  with the high low bits that were rotated.
3376 
3377  This function rotates the 64-bit value Operand to the right by Count bits.
3378  The high Count bits are fill with the low Count bits of Operand. The rotated
3379  value is returned.
3380 
3381  If Count is greater than 63, then ASSERT().
3382 
3383  @param Operand The 64-bit operand to rotate right.
3384  @param Count The number of bits to rotate right.
3385 
3386  @return Operand >> Count
3387 
3388 **/
3389 UINT64
3390 EFIAPI
3391 RRotU64 (
3392  IN UINT64 Operand,
3393  IN UINTN Count
3394  );
3395 
3396 /**
3397  Returns the bit position of the lowest bit set in a 32-bit value.
3398 
3399  This function computes the bit position of the lowest bit set in the 32-bit
3400  value specified by Operand. If Operand is zero, then -1 is returned.
3401  Otherwise, a value between 0 and 31 is returned.
3402 
3403  @param Operand The 32-bit operand to evaluate.
3404 
3405  @retval 0..31 The lowest bit set in Operand was found.
3406  @retval -1 Operand is zero.
3407 
3408 **/
3409 INTN
3410 EFIAPI
3411 LowBitSet32 (
3412  IN UINT32 Operand
3413  );
3414 
3415 /**
3416  Returns the bit position of the lowest bit set in a 64-bit value.
3417 
3418  This function computes the bit position of the lowest bit set in the 64-bit
3419  value specified by Operand. If Operand is zero, then -1 is returned.
3420  Otherwise, a value between 0 and 63 is returned.
3421 
3422  @param Operand The 64-bit operand to evaluate.
3423 
3424  @retval 0..63 The lowest bit set in Operand was found.
3425  @retval -1 Operand is zero.
3426 
3427 
3428 **/
3429 INTN
3430 EFIAPI
3431 LowBitSet64 (
3432  IN UINT64 Operand
3433  );
3434 
3435 /**
3436  Returns the bit position of the highest bit set in a 32-bit value. Equivalent
3437  to log2(x).
3438 
3439  This function computes the bit position of the highest bit set in the 32-bit
3440  value specified by Operand. If Operand is zero, then -1 is returned.
3441  Otherwise, a value between 0 and 31 is returned.
3442 
3443  @param Operand The 32-bit operand to evaluate.
3444 
3445  @retval 0..31 Position of the highest bit set in Operand if found.
3446  @retval -1 Operand is zero.
3447 
3448 **/
3449 INTN
3450 EFIAPI
3451 HighBitSet32 (
3452  IN UINT32 Operand
3453  );
3454 
3455 /**
3456  Returns the bit position of the highest bit set in a 64-bit value. Equivalent
3457  to log2(x).
3458 
3459  This function computes the bit position of the highest bit set in the 64-bit
3460  value specified by Operand. If Operand is zero, then -1 is returned.
3461  Otherwise, a value between 0 and 63 is returned.
3462 
3463  @param Operand The 64-bit operand to evaluate.
3464 
3465  @retval 0..63 Position of the highest bit set in Operand if found.
3466  @retval -1 Operand is zero.
3467 
3468 **/
3469 INTN
3470 EFIAPI
3471 HighBitSet64 (
3472  IN UINT64 Operand
3473  );
3474 
3475 /**
3476  Returns the value of the highest bit set in a 32-bit value. Equivalent to
3477  1 << log2(x).
3478 
3479  This function computes the value of the highest bit set in the 32-bit value
3480  specified by Operand. If Operand is zero, then zero is returned.
3481 
3482  @param Operand The 32-bit operand to evaluate.
3483 
3484  @return 1 << HighBitSet32(Operand)
3485  @retval 0 Operand is zero.
3486 
3487 **/
3488 UINT32
3489 EFIAPI
3491  IN UINT32 Operand
3492  );
3493 
3494 /**
3495  Returns the value of the highest bit set in a 64-bit value. Equivalent to
3496  1 << log2(x).
3497 
3498  This function computes the value of the highest bit set in the 64-bit value
3499  specified by Operand. If Operand is zero, then zero is returned.
3500 
3501  @param Operand The 64-bit operand to evaluate.
3502 
3503  @return 1 << HighBitSet64(Operand)
3504  @retval 0 Operand is zero.
3505 
3506 **/
3507 UINT64
3508 EFIAPI
3510  IN UINT64 Operand
3511  );
3512 
3513 /**
3514  Switches the endianness of a 16-bit integer.
3515 
3516  This function swaps the bytes in a 16-bit unsigned value to switch the value
3517  from little endian to big endian or vice versa. The byte swapped value is
3518  returned.
3519 
3520  @param Value A 16-bit unsigned value.
3521 
3522  @return The byte swapped Value.
3523 
3524 **/
3525 UINT16
3526 EFIAPI
3527 SwapBytes16 (
3528  IN UINT16 Value
3529  );
3530 
3531 /**
3532  Switches the endianness of a 32-bit integer.
3533 
3534  This function swaps the bytes in a 32-bit unsigned value to switch the value
3535  from little endian to big endian or vice versa. The byte swapped value is
3536  returned.
3537 
3538  @param Value A 32-bit unsigned value.
3539 
3540  @return The byte swapped Value.
3541 
3542 **/
3543 UINT32
3544 EFIAPI
3545 SwapBytes32 (
3546  IN UINT32 Value
3547  );
3548 
3549 /**
3550  Switches the endianness of a 64-bit integer.
3551 
3552  This function swaps the bytes in a 64-bit unsigned value to switch the value
3553  from little endian to big endian or vice versa. The byte swapped value is
3554  returned.
3555 
3556  @param Value A 64-bit unsigned value.
3557 
3558  @return The byte swapped Value.
3559 
3560 **/
3561 UINT64
3562 EFIAPI
3563 SwapBytes64 (
3564  IN UINT64 Value
3565  );
3566 
3567 /**
3568  Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3569  generates a 64-bit unsigned result.
3570 
3571  This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3572  unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3573  bit unsigned result is returned.
3574 
3575  @param Multiplicand A 64-bit unsigned value.
3576  @param Multiplier A 32-bit unsigned value.
3577 
3578  @return Multiplicand * Multiplier
3579 
3580 **/
3581 UINT64
3582 EFIAPI
3583 MultU64x32 (
3584  IN UINT64 Multiplicand,
3585  IN UINT32 Multiplier
3586  );
3587 
3588 /**
3589  Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3590  generates a 64-bit unsigned result.
3591 
3592  This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3593  unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3594  bit unsigned result is returned.
3595 
3596  @param Multiplicand A 64-bit unsigned value.
3597  @param Multiplier A 64-bit unsigned value.
3598 
3599  @return Multiplicand * Multiplier.
3600 
3601 **/
3602 UINT64
3603 EFIAPI
3604 MultU64x64 (
3605  IN UINT64 Multiplicand,
3606  IN UINT64 Multiplier
3607  );
3608 
3609 /**
3610  Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3611  64-bit signed result.
3612 
3613  This function multiples the 64-bit signed value Multiplicand by the 64-bit
3614  signed value Multiplier and generates a 64-bit signed result. This 64-bit
3615  signed result is returned.
3616 
3617  @param Multiplicand A 64-bit signed value.
3618  @param Multiplier A 64-bit signed value.
3619 
3620  @return Multiplicand * Multiplier
3621 
3622 **/
3623 INT64
3624 EFIAPI
3625 MultS64x64 (
3626  IN INT64 Multiplicand,
3627  IN INT64 Multiplier
3628  );
3629 
3630 /**
3631  Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3632  a 64-bit unsigned result.
3633 
3634  This function divides the 64-bit unsigned value Dividend by the 32-bit
3635  unsigned value Divisor and generates a 64-bit unsigned quotient. This
3636  function returns the 64-bit unsigned quotient.
3637 
3638  If Divisor is 0, then ASSERT().
3639 
3640  @param Dividend A 64-bit unsigned value.
3641  @param Divisor A 32-bit unsigned value.
3642 
3643  @return Dividend / Divisor.
3644 
3645 **/
3646 UINT64
3647 EFIAPI
3648 DivU64x32 (
3649  IN UINT64 Dividend,
3650  IN UINT32 Divisor
3651  );
3652 
3653 /**
3654  Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3655  a 32-bit unsigned remainder.
3656 
3657  This function divides the 64-bit unsigned value Dividend by the 32-bit
3658  unsigned value Divisor and generates a 32-bit remainder. This function
3659  returns the 32-bit unsigned remainder.
3660 
3661  If Divisor is 0, then ASSERT().
3662 
3663  @param Dividend A 64-bit unsigned value.
3664  @param Divisor A 32-bit unsigned value.
3665 
3666  @return Dividend % Divisor.
3667 
3668 **/
3669 UINT32
3670 EFIAPI
3671 ModU64x32 (
3672  IN UINT64 Dividend,
3673  IN UINT32 Divisor
3674  );
3675 
3676 /**
3677  Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3678  a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3679 
3680  This function divides the 64-bit unsigned value Dividend by the 32-bit
3681  unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3682  is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3683  This function returns the 64-bit unsigned quotient.
3684 
3685  If Divisor is 0, then ASSERT().
3686 
3687  @param Dividend A 64-bit unsigned value.
3688  @param Divisor A 32-bit unsigned value.
3689  @param Remainder A pointer to a 32-bit unsigned value. This parameter is
3690  optional and may be NULL.
3691 
3692  @return Dividend / Divisor.
3693 
3694 **/
3695 UINT64
3696 EFIAPI
3698  IN UINT64 Dividend,
3699  IN UINT32 Divisor,
3700  OUT UINT32 *Remainder OPTIONAL
3701  );
3702 
3703 /**
3704  Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3705  a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3706 
3707  This function divides the 64-bit unsigned value Dividend by the 64-bit
3708  unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3709  is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3710  This function returns the 64-bit unsigned quotient.
3711 
3712  If Divisor is 0, then ASSERT().
3713 
3714  @param Dividend A 64-bit unsigned value.
3715  @param Divisor A 64-bit unsigned value.
3716  @param Remainder A pointer to a 64-bit unsigned value. This parameter is
3717  optional and may be NULL.
3718 
3719  @return Dividend / Divisor.
3720 
3721 **/
3722 UINT64
3723 EFIAPI
3725  IN UINT64 Dividend,
3726  IN UINT64 Divisor,
3727  OUT UINT64 *Remainder OPTIONAL
3728  );
3729 
3730 /**
3731  Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3732  64-bit signed result and a optional 64-bit signed remainder.
3733 
3734  This function divides the 64-bit signed value Dividend by the 64-bit signed
3735  value Divisor and generates a 64-bit signed quotient. If Remainder is not
3736  NULL, then the 64-bit signed remainder is returned in Remainder. This
3737  function returns the 64-bit signed quotient.
3738 
3739  It is the caller's responsibility to not call this function with a Divisor of 0.
3740  If Divisor is 0, then the quotient and remainder should be assumed to be
3741  the largest negative integer.
3742 
3743  If Divisor is 0, then ASSERT().
3744 
3745  @param Dividend A 64-bit signed value.
3746  @param Divisor A 64-bit signed value.
3747  @param Remainder A pointer to a 64-bit signed value. This parameter is
3748  optional and may be NULL.
3749 
3750  @return Dividend / Divisor.
3751 
3752 **/
3753 INT64
3754 EFIAPI
3756  IN INT64 Dividend,
3757  IN INT64 Divisor,
3758  OUT INT64 *Remainder OPTIONAL
3759  );
3760 
3761 /**
3762  Reads a 16-bit value from memory that may be unaligned.
3763 
3764  This function returns the 16-bit value pointed to by Buffer. The function
3765  guarantees that the read operation does not produce an alignment fault.
3766 
3767  If the Buffer is NULL, then ASSERT().
3768 
3769  @param Buffer The pointer to a 16-bit value that may be unaligned.
3770 
3771  @return The 16-bit value read from Buffer.
3772 
3773 **/
3774 UINT16
3775 EFIAPI
3778  );
3779 
3780 /**
3781  Writes a 16-bit value to memory that may be unaligned.
3782 
3783  This function writes the 16-bit value specified by Value to Buffer. Value is
3784  returned. The function guarantees that the write operation does not produce
3785  an alignment fault.
3786 
3787  If the Buffer is NULL, then ASSERT().
3788 
3789  @param Buffer The pointer to a 16-bit value that may be unaligned.
3790  @param Value 16-bit value to write to Buffer.
3791 
3792  @return The 16-bit value to write to Buffer.
3793 
3794 **/
3795 UINT16
3796 EFIAPI
3798  OUT UINT16 *Buffer,
3799  IN UINT16 Value
3800  );
3801 
3802 /**
3803  Reads a 24-bit value from memory that may be unaligned.
3804 
3805  This function returns the 24-bit value pointed to by Buffer. The function
3806  guarantees that the read operation does not produce an alignment fault.
3807 
3808  If the Buffer is NULL, then ASSERT().
3809 
3810  @param Buffer The pointer to a 24-bit value that may be unaligned.
3811 
3812  @return The 24-bit value read from Buffer.
3813 
3814 **/
3815 UINT32
3816 EFIAPI
3819  );
3820 
3821 /**
3822  Writes a 24-bit value to memory that may be unaligned.
3823 
3824  This function writes the 24-bit value specified by Value to Buffer. Value is
3825  returned. The function guarantees that the write operation does not produce
3826  an alignment fault.
3827 
3828  If the Buffer is NULL, then ASSERT().
3829 
3830  @param Buffer The pointer to a 24-bit value that may be unaligned.
3831  @param Value 24-bit value to write to Buffer.
3832 
3833  @return The 24-bit value to write to Buffer.
3834 
3835 **/
3836 UINT32
3837 EFIAPI
3839  OUT UINT32 *Buffer,
3840  IN UINT32 Value
3841  );
3842 
3843 /**
3844  Reads a 32-bit value from memory that may be unaligned.
3845 
3846  This function returns the 32-bit value pointed to by Buffer. The function
3847  guarantees that the read operation does not produce an alignment fault.
3848 
3849  If the Buffer is NULL, then ASSERT().
3850 
3851  @param Buffer The pointer to a 32-bit value that may be unaligned.
3852 
3853  @return The 32-bit value read from Buffer.
3854 
3855 **/
3856 UINT32
3857 EFIAPI
3860  );
3861 
3862 /**
3863  Writes a 32-bit value to memory that may be unaligned.
3864 
3865  This function writes the 32-bit value specified by Value to Buffer. Value is
3866  returned. The function guarantees that the write operation does not produce
3867  an alignment fault.
3868 
3869  If the Buffer is NULL, then ASSERT().
3870 
3871  @param Buffer The pointer to a 32-bit value that may be unaligned.
3872  @param Value 32-bit value to write to Buffer.
3873 
3874  @return The 32-bit value to write to Buffer.
3875 
3876 **/
3877 UINT32
3878 EFIAPI
3880  OUT UINT32 *Buffer,
3881  IN UINT32 Value
3882  );
3883 
3884 /**
3885  Reads a 64-bit value from memory that may be unaligned.
3886 
3887  This function returns the 64-bit value pointed to by Buffer. The function
3888  guarantees that the read operation does not produce an alignment fault.
3889 
3890  If the Buffer is NULL, then ASSERT().
3891 
3892  @param Buffer The pointer to a 64-bit value that may be unaligned.
3893 
3894  @return The 64-bit value read from Buffer.
3895 
3896 **/
3897 UINT64
3898 EFIAPI
3901  );
3902 
3903 /**
3904  Writes a 64-bit value to memory that may be unaligned.
3905 
3906  This function writes the 64-bit value specified by Value to Buffer. Value is
3907  returned. The function guarantees that the write operation does not produce
3908  an alignment fault.
3909 
3910  If the Buffer is NULL, then ASSERT().
3911 
3912  @param Buffer The pointer to a 64-bit value that may be unaligned.
3913  @param Value 64-bit value to write to Buffer.
3914 
3915  @return The 64-bit value to write to Buffer.
3916 
3917 **/
3918 UINT64
3919 EFIAPI
3921  OUT UINT64 *Buffer,
3922  IN UINT64 Value
3923  );
3924 
3925 //
3926 // Bit Field Functions
3927 //
3928 
3929 /**
3930  Returns a bit field from an 8-bit value.
3931 
3932  Returns the bitfield specified by the StartBit and the EndBit from Operand.
3933 
3934  If 8-bit operations are not supported, then ASSERT().
3935  If StartBit is greater than 7, then ASSERT().
3936  If EndBit is greater than 7, then ASSERT().
3937  If EndBit is less than StartBit, then ASSERT().
3938 
3939  @param Operand Operand on which to perform the bitfield operation.
3940  @param StartBit The ordinal of the least significant bit in the bit field.
3941  Range 0..7.
3942  @param EndBit The ordinal of the most significant bit in the bit field.
3943  Range 0..7.
3944 
3945  @return The bit field read.
3946 
3947 **/
3948 UINT8
3949 EFIAPI
3950 BitFieldRead8 (
3951  IN UINT8 Operand,
3952  IN UINTN StartBit,
3953  IN UINTN EndBit
3954  );
3955 
3956 /**
3957  Writes a bit field to an 8-bit value, and returns the result.
3958 
3959  Writes Value to the bit field specified by the StartBit and the EndBit in
3960  Operand. All other bits in Operand are preserved. The new 8-bit value is
3961  returned.
3962 
3963  If 8-bit operations are not supported, then ASSERT().
3964  If StartBit is greater than 7, then ASSERT().
3965  If EndBit is greater than 7, then ASSERT().
3966  If EndBit is less than StartBit, then ASSERT().
3967  If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3968 
3969  @param Operand Operand on which to perform the bitfield operation.
3970  @param StartBit The ordinal of the least significant bit in the bit field.
3971  Range 0..7.
3972  @param EndBit The ordinal of the most significant bit in the bit field.
3973  Range 0..7.
3974  @param Value New value of the bit field.
3975 
3976  @return The new 8-bit value.
3977 
3978 **/
3979 UINT8
3980 EFIAPI
3982  IN UINT8 Operand,
3983  IN UINTN StartBit,
3984  IN UINTN EndBit,
3985  IN UINT8 Value
3986  );
3987 
3988 /**
3989  Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
3990  result.
3991 
3992  Performs a bitwise OR between the bit field specified by StartBit
3993  and EndBit in Operand and the value specified by OrData. All other bits in
3994  Operand are preserved. The new 8-bit value is returned.
3995 
3996  If 8-bit operations are not supported, then ASSERT().
3997  If StartBit is greater than 7, then ASSERT().
3998  If EndBit is greater than 7, then ASSERT().
3999  If EndBit is less than StartBit, then ASSERT().
4000  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4001 
4002  @param Operand Operand on which to perform the bitfield operation.
4003  @param StartBit The ordinal of the least significant bit in the bit field.
4004  Range 0..7.
4005  @param EndBit The ordinal of the most significant bit in the bit field.
4006  Range 0..7.
4007  @param OrData The value to OR with the read value from the value
4008 
4009  @return The new 8-bit value.
4010 
4011 **/
4012 UINT8
4013 EFIAPI
4014 BitFieldOr8 (
4015  IN UINT8 Operand,
4016  IN UINTN StartBit,
4017  IN UINTN EndBit,
4018  IN UINT8 OrData
4019  );
4020 
4021 /**
4022  Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
4023  the result.
4024 
4025  Performs a bitwise AND between the bit field specified by StartBit and EndBit
4026  in Operand and the value specified by AndData. All other bits in Operand are
4027  preserved. The new 8-bit value is returned.
4028 
4029  If 8-bit operations are not supported, then ASSERT().
4030  If StartBit is greater than 7, then ASSERT().
4031  If EndBit is greater than 7, then ASSERT().
4032  If EndBit is less than StartBit, then ASSERT().
4033  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4034 
4035  @param Operand Operand on which to perform the bitfield operation.
4036  @param StartBit The ordinal of the least significant bit in the bit field.
4037  Range 0..7.
4038  @param EndBit The ordinal of the most significant bit in the bit field.
4039  Range 0..7.
4040  @param AndData The value to AND with the read value from the value.
4041 
4042  @return The new 8-bit value.
4043 
4044 **/
4045 UINT8
4046 EFIAPI
4047 BitFieldAnd8 (
4048  IN UINT8 Operand,
4049  IN UINTN StartBit,
4050  IN UINTN EndBit,
4051  IN UINT8 AndData
4052  );
4053 
4054 /**
4055  Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
4056  bitwise OR, and returns the result.
4057 
4058  Performs a bitwise AND between the bit field specified by StartBit and EndBit
4059  in Operand and the value specified by AndData, followed by a bitwise
4060  OR with value specified by OrData. All other bits in Operand are
4061  preserved. The new 8-bit value is returned.
4062 
4063  If 8-bit operations are not supported, then ASSERT().
4064  If StartBit is greater than 7, then ASSERT().
4065  If EndBit is greater than 7, then ASSERT().
4066  If EndBit is less than StartBit, then ASSERT().
4067  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4068  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4069 
4070  @param Operand Operand on which to perform the bitfield operation.
4071  @param StartBit The ordinal of the least significant bit in the bit field.
4072  Range 0..7.
4073  @param EndBit The ordinal of the most significant bit in the bit field.
4074  Range 0..7.
4075  @param AndData The value to AND with the read value from the value.
4076  @param OrData The value to OR with the result of the AND operation.
4077 
4078  @return The new 8-bit value.
4079 
4080 **/
4081 UINT8
4082 EFIAPI
4084  IN UINT8 Operand,
4085  IN UINTN StartBit,
4086  IN UINTN EndBit,
4087  IN UINT8 AndData,
4088  IN UINT8 OrData
4089  );
4090 
4091 /**
4092  Returns a bit field from a 16-bit value.
4093 
4094  Returns the bitfield specified by the StartBit and the EndBit from Operand.
4095 
4096  If 16-bit operations are not supported, then ASSERT().
4097  If StartBit is greater than 15, then ASSERT().
4098  If EndBit is greater than 15, then ASSERT().
4099  If EndBit is less than StartBit, then ASSERT().
4100 
4101  @param Operand Operand on which to perform the bitfield operation.
4102  @param StartBit The ordinal of the least significant bit in the bit field.
4103  Range 0..15.
4104  @param EndBit The ordinal of the most significant bit in the bit field.
4105  Range 0..15.
4106 
4107  @return The bit field read.
4108 
4109 **/
4110 UINT16
4111 EFIAPI
4113  IN UINT16 Operand,
4114  IN UINTN StartBit,
4115  IN UINTN EndBit
4116  );
4117 
4118 /**
4119  Writes a bit field to a 16-bit value, and returns the result.
4120 
4121  Writes Value to the bit field specified by the StartBit and the EndBit in
4122  Operand. All other bits in Operand are preserved. The new 16-bit value is
4123  returned.
4124 
4125  If 16-bit operations are not supported, then ASSERT().
4126  If StartBit is greater than 15, then ASSERT().
4127  If EndBit is greater than 15, then ASSERT().
4128  If EndBit is less than StartBit, then ASSERT().
4129  If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4130 
4131  @param Operand Operand on which to perform the bitfield operation.
4132  @param StartBit The ordinal of the least significant bit in the bit field.
4133  Range 0..15.
4134  @param EndBit The ordinal of the most significant bit in the bit field.
4135  Range 0..15.
4136  @param Value New value of the bit field.
4137 
4138  @return The new 16-bit value.
4139 
4140 **/
4141 UINT16
4142 EFIAPI
4144  IN UINT16 Operand,
4145  IN UINTN StartBit,
4146  IN UINTN EndBit,
4147  IN UINT16 Value
4148  );
4149 
4150 /**
4151  Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
4152  result.
4153 
4154  Performs a bitwise OR between the bit field specified by StartBit
4155  and EndBit in Operand and the value specified by OrData. All other bits in
4156  Operand are preserved. The new 16-bit value is returned.
4157 
4158  If 16-bit operations are not supported, then ASSERT().
4159  If StartBit is greater than 15, then ASSERT().
4160  If EndBit is greater than 15, then ASSERT().
4161  If EndBit is less than StartBit, then ASSERT().
4162  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4163 
4164  @param Operand Operand on which to perform the bitfield operation.
4165  @param StartBit The ordinal of the least significant bit in the bit field.
4166  Range 0..15.
4167  @param EndBit The ordinal of the most significant bit in the bit field.
4168  Range 0..15.
4169  @param OrData The value to OR with the read value from the value
4170 
4171  @return The new 16-bit value.
4172 
4173 **/
4174 UINT16
4175 EFIAPI
4176 BitFieldOr16 (
4177  IN UINT16 Operand,
4178  IN UINTN StartBit,
4179  IN UINTN EndBit,
4180  IN UINT16 OrData
4181  );
4182 
4183 /**
4184  Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
4185  the result.
4186 
4187  Performs a bitwise AND between the bit field specified by StartBit and EndBit
4188  in Operand and the value specified by AndData. All other bits in Operand are
4189  preserved. The new 16-bit value is returned.
4190 
4191  If 16-bit operations are not supported, then ASSERT().
4192  If StartBit is greater than 15, then ASSERT().
4193  If EndBit is greater than 15, then ASSERT().
4194  If EndBit is less than StartBit, then ASSERT().
4195  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4196 
4197  @param Operand Operand on which to perform the bitfield operation.
4198  @param StartBit The ordinal of the least significant bit in the bit field.
4199  Range 0..15.
4200  @param EndBit The ordinal of the most significant bit in the bit field.
4201  Range 0..15.
4202  @param AndData The value to AND with the read value from the value
4203 
4204  @return The new 16-bit value.
4205 
4206 **/
4207 UINT16
4208 EFIAPI
4209 BitFieldAnd16 (
4210  IN UINT16 Operand,
4211  IN UINTN StartBit,
4212  IN UINTN EndBit,
4213  IN UINT16 AndData
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
4246  IN UINT16 Operand,
4247  IN UINTN StartBit,
4248  IN UINTN EndBit,
4249  IN UINT16 AndData,
4250  IN UINT16 OrData
4251  );
4252 
4253 /**
4254  Returns a bit field from a 32-bit value.
4255 
4256  Returns the bitfield specified by the StartBit and the EndBit from Operand.
4257 
4258  If 32-bit operations are not supported, then ASSERT().
4259  If StartBit is greater than 31, then ASSERT().
4260  If EndBit is greater than 31, then ASSERT().
4261  If EndBit is less than StartBit, then ASSERT().
4262 
4263  @param Operand Operand on which to perform the bitfield operation.
4264  @param StartBit The ordinal of the least significant bit in the bit field.
4265  Range 0..31.
4266  @param EndBit The ordinal of the most significant bit in the bit field.
4267  Range 0..31.
4268 
4269  @return The bit field read.
4270 
4271 **/
4272 UINT32
4273 EFIAPI
4275  IN UINT32 Operand,
4276  IN UINTN StartBit,
4277  IN UINTN EndBit
4278  );
4279 
4280 /**
4281  Writes a bit field to a 32-bit value, and returns the result.
4282 
4283  Writes Value to the bit field specified by the StartBit and the EndBit in
4284  Operand. All other bits in Operand are preserved. The new 32-bit value is
4285  returned.
4286 
4287  If 32-bit operations are not supported, then ASSERT().
4288  If StartBit is greater than 31, then ASSERT().
4289  If EndBit is greater than 31, then ASSERT().
4290  If EndBit is less than StartBit, then ASSERT().
4291  If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4292 
4293  @param Operand Operand on which to perform the bitfield operation.
4294  @param StartBit The ordinal of the least significant bit in the bit field.
4295  Range 0..31.
4296  @param EndBit The ordinal of the most significant bit in the bit field.
4297  Range 0..31.
4298  @param Value New value of the bit field.
4299 
4300  @return The new 32-bit value.
4301 
4302 **/
4303 UINT32
4304 EFIAPI
4306  IN UINT32 Operand,
4307  IN UINTN StartBit,
4308  IN UINTN EndBit,
4309  IN UINT32 Value
4310  );
4311 
4312 /**
4313  Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
4314  result.
4315 
4316  Performs a bitwise OR between the bit field specified by StartBit
4317  and EndBit in Operand and the value specified by OrData. All other bits in
4318  Operand are preserved. The new 32-bit value is returned.
4319 
4320  If 32-bit operations are not supported, then ASSERT().
4321  If StartBit is greater than 31, then ASSERT().
4322  If EndBit is greater than 31, then ASSERT().
4323  If EndBit is less than StartBit, then ASSERT().
4324  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4325 
4326  @param Operand Operand on which to perform the bitfield operation.
4327  @param StartBit The ordinal of the least significant bit in the bit field.
4328  Range 0..31.
4329  @param EndBit The ordinal of the most significant bit in the bit field.
4330  Range 0..31.
4331  @param OrData The value to OR with the read value from the value.
4332 
4333  @return The new 32-bit value.
4334 
4335 **/
4336 UINT32
4337 EFIAPI
4338 BitFieldOr32 (
4339  IN UINT32 Operand,
4340  IN UINTN StartBit,
4341  IN UINTN EndBit,
4342  IN UINT32 OrData
4343  );
4344 
4345 /**
4346  Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
4347  the result.
4348 
4349  Performs a bitwise AND between the bit field specified by StartBit and EndBit
4350  in Operand and the value specified by AndData. All other bits in Operand are
4351  preserved. The new 32-bit value is returned.
4352 
4353  If 32-bit operations are not supported, then ASSERT().
4354  If StartBit is greater than 31, then ASSERT().
4355  If EndBit is greater than 31, then ASSERT().
4356  If EndBit is less than StartBit, then ASSERT().
4357  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4358 
4359  @param Operand Operand on which to perform the bitfield operation.
4360  @param StartBit The ordinal of the least significant bit in the bit field.
4361  Range 0..31.
4362  @param EndBit The ordinal of the most significant bit in the bit field.
4363  Range 0..31.
4364  @param AndData The value to AND with the read value from the value
4365 
4366  @return The new 32-bit value.
4367 
4368 **/
4369 UINT32
4370 EFIAPI
4371 BitFieldAnd32 (
4372  IN UINT32 Operand,
4373  IN UINTN StartBit,
4374  IN UINTN EndBit,
4375  IN UINT32 AndData
4376  );
4377 
4378 /**
4379  Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
4380  bitwise OR, and returns the result.
4381 
4382  Performs a bitwise AND between the bit field specified by StartBit and EndBit
4383  in Operand and the value specified by AndData, followed by a bitwise
4384  OR with value specified by OrData. All other bits in Operand are
4385  preserved. The new 32-bit value is returned.
4386 
4387  If 32-bit operations are not supported, then ASSERT().
4388  If StartBit is greater than 31, then ASSERT().
4389  If EndBit is greater than 31, then ASSERT().
4390  If EndBit is less than StartBit, then ASSERT().
4391  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4392  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4393 
4394  @param Operand Operand on which to perform the bitfield operation.
4395  @param StartBit The ordinal of the least significant bit in the bit field.
4396  Range 0..31.
4397  @param EndBit The ordinal of the most significant bit in the bit field.
4398  Range 0..31.
4399  @param AndData The value to AND with the read value from the value.
4400  @param OrData The value to OR with the result of the AND operation.
4401 
4402  @return The new 32-bit value.
4403 
4404 **/
4405 UINT32
4406 EFIAPI
4408  IN UINT32 Operand,
4409  IN UINTN StartBit,
4410  IN UINTN EndBit,
4411  IN UINT32 AndData,
4412  IN UINT32 OrData
4413  );
4414 
4415 /**
4416  Returns a bit field from a 64-bit value.
4417 
4418  Returns the bitfield specified by the StartBit and the EndBit from Operand.
4419 
4420  If 64-bit operations are not supported, then ASSERT().
4421  If StartBit is greater than 63, then ASSERT().
4422  If EndBit is greater than 63, then ASSERT().
4423  If EndBit is less than StartBit, then ASSERT().
4424 
4425  @param Operand Operand on which to perform the bitfield operation.
4426  @param StartBit The ordinal of the least significant bit in the bit field.
4427  Range 0..63.
4428  @param EndBit The ordinal of the most significant bit in the bit field.
4429  Range 0..63.
4430 
4431  @return The bit field read.
4432 
4433 **/
4434 UINT64
4435 EFIAPI
4437  IN UINT64 Operand,
4438  IN UINTN StartBit,
4439  IN UINTN EndBit
4440  );
4441 
4442 /**
4443  Writes a bit field to a 64-bit value, and returns the result.
4444 
4445  Writes Value to the bit field specified by the StartBit and the EndBit in
4446  Operand. All other bits in Operand are preserved. The new 64-bit value is
4447  returned.
4448 
4449  If 64-bit operations are not supported, then ASSERT().
4450  If StartBit is greater than 63, then ASSERT().
4451  If EndBit is greater than 63, then ASSERT().
4452  If EndBit is less than StartBit, then ASSERT().
4453  If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4454 
4455  @param Operand Operand on which to perform the bitfield operation.
4456  @param StartBit The ordinal of the least significant bit in the bit field.
4457  Range 0..63.
4458  @param EndBit The ordinal of the most significant bit in the bit field.
4459  Range 0..63.
4460  @param Value New value of the bit field.
4461 
4462  @return The new 64-bit value.
4463 
4464 **/
4465 UINT64
4466 EFIAPI
4468  IN UINT64 Operand,
4469  IN UINTN StartBit,
4470  IN UINTN EndBit,
4471  IN UINT64 Value
4472  );
4473 
4474 /**
4475  Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
4476  result.
4477 
4478  Performs a bitwise OR between the bit field specified by StartBit
4479  and EndBit in Operand and the value specified by OrData. All other bits in
4480  Operand are preserved. The new 64-bit value is returned.
4481 
4482  If 64-bit operations are not supported, then ASSERT().
4483  If StartBit is greater than 63, then ASSERT().
4484  If EndBit is greater than 63, then ASSERT().
4485  If EndBit is less than StartBit, then ASSERT().
4486  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4487 
4488  @param Operand Operand on which to perform the bitfield operation.
4489  @param StartBit The ordinal of the least significant bit in the bit field.
4490  Range 0..63.
4491  @param EndBit The ordinal of the most significant bit in the bit field.
4492  Range 0..63.
4493  @param OrData The value to OR with the read value from the value
4494 
4495  @return The new 64-bit value.
4496 
4497 **/
4498 UINT64
4499 EFIAPI
4500 BitFieldOr64 (
4501  IN UINT64 Operand,
4502  IN UINTN StartBit,
4503  IN UINTN EndBit,
4504  IN UINT64 OrData
4505  );
4506 
4507 /**
4508  Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
4509  the result.
4510 
4511  Performs a bitwise AND between the bit field specified by StartBit and EndBit
4512  in Operand and the value specified by AndData. All other bits in Operand are
4513  preserved. The new 64-bit value is returned.
4514 
4515  If 64-bit operations are not supported, then ASSERT().
4516  If StartBit is greater than 63, then ASSERT().
4517  If EndBit is greater than 63, then ASSERT().
4518  If EndBit is less than StartBit, then ASSERT().
4519  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4520 
4521  @param Operand Operand on which to perform the bitfield operation.
4522  @param StartBit The ordinal of the least significant bit in the bit field.
4523  Range 0..63.
4524  @param EndBit The ordinal of the most significant bit in the bit field.
4525  Range 0..63.
4526  @param AndData The value to AND with the read value from the value
4527 
4528  @return The new 64-bit value.
4529 
4530 **/
4531 UINT64
4532 EFIAPI
4533 BitFieldAnd64 (
4534  IN UINT64 Operand,
4535  IN UINTN StartBit,
4536  IN UINTN EndBit,
4537  IN UINT64 AndData
4538  );
4539 
4540 /**
4541  Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
4542  bitwise OR, and returns the result.
4543 
4544  Performs a bitwise AND between the bit field specified by StartBit and EndBit
4545  in Operand and the value specified by AndData, followed by a bitwise
4546  OR with value specified by OrData. All other bits in Operand are
4547  preserved. The new 64-bit value is returned.
4548 
4549  If 64-bit operations are not supported, then ASSERT().
4550  If StartBit is greater than 63, then ASSERT().
4551  If EndBit is greater than 63, then ASSERT().
4552  If EndBit is less than StartBit, then ASSERT().
4553  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4554  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4555 
4556  @param Operand Operand on which to perform the bitfield operation.
4557  @param StartBit The ordinal of the least significant bit in the bit field.
4558  Range 0..63.
4559  @param EndBit The ordinal of the most significant bit in the bit field.
4560  Range 0..63.
4561  @param AndData The value to AND with the read value from the value.
4562  @param OrData The value to OR with the result of the AND operation.
4563 
4564  @return The new 64-bit value.
4565 
4566 **/
4567 UINT64
4568 EFIAPI
4570  IN UINT64 Operand,
4571  IN UINTN StartBit,
4572  IN UINTN EndBit,
4573  IN UINT64 AndData,
4574  IN UINT64 OrData
4575  );
4576 
4577 /**
4578  Reads a bit field from a 32-bit value, counts and returns
4579  the number of set bits.
4580 
4581  Counts the number of set bits in the bit field specified by
4582  StartBit and EndBit in Operand. The count is returned.
4583 
4584  If StartBit is greater than 31, then ASSERT().
4585  If EndBit is greater than 31, then ASSERT().
4586  If EndBit is less than StartBit, then ASSERT().
4587 
4588  @param Operand Operand on which to perform the bitfield operation.
4589  @param StartBit The ordinal of the least significant bit in the bit field.
4590  Range 0..31.
4591  @param EndBit The ordinal of the most significant bit in the bit field.
4592  Range 0..31.
4593 
4594  @return The number of bits set between StartBit and EndBit.
4595 
4596 **/
4597 UINT8
4598 EFIAPI
4600  IN UINT32 Operand,
4601  IN UINTN StartBit,
4602  IN UINTN EndBit
4603  );
4604 
4605 /**
4606  Reads a bit field from a 64-bit value, counts and returns
4607  the number of set bits.
4608 
4609  Counts the number of set bits in the bit field specified by
4610  StartBit and EndBit in Operand. The count is returned.
4611 
4612  If StartBit is greater than 63, then ASSERT().
4613  If EndBit is greater than 63, then ASSERT().
4614  If EndBit is less than StartBit, then ASSERT().
4615 
4616  @param Operand Operand on which to perform the bitfield operation.
4617  @param StartBit The ordinal of the least significant bit in the bit field.
4618  Range 0..63.
4619  @param EndBit The ordinal of the most significant bit in the bit field.
4620  Range 0..63.
4621 
4622  @return The number of bits set between StartBit and EndBit.
4623 
4624 **/
4625 UINT8
4626 EFIAPI
4628  IN UINT64 Operand,
4629  IN UINTN StartBit,
4630  IN UINTN EndBit
4631  );
4632 
4633 //
4634 // Base Library Checksum Functions
4635 //
4636 
4637 /**
4638  Returns the sum of all elements in a buffer in unit of UINT8.
4639  During calculation, the carry bits are dropped.
4640 
4641  This function calculates the sum of all elements in a buffer
4642  in unit of UINT8. The carry bits in result of addition are dropped.
4643  The result is returned as UINT8. If Length is Zero, then Zero is
4644  returned.
4645 
4646  If Buffer is NULL, then ASSERT().
4647  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4648 
4649  @param Buffer The pointer to the buffer to carry out the sum operation.
4650  @param Length The size, in bytes, of Buffer.
4651 
4652  @return Sum The sum of Buffer with carry bits dropped during additions.
4653 
4654 **/
4655 UINT8
4656 EFIAPI
4657 CalculateSum8 (
4658  IN CONST UINT8 *Buffer,
4659  IN UINTN Length
4660  );
4661 
4662 /**
4663  Returns the two's complement checksum of all elements in a buffer
4664  of 8-bit values.
4665 
4666  This function first calculates the sum of the 8-bit values in the
4667  buffer specified by Buffer and Length. The carry bits in the result
4668  of addition are dropped. Then, the two's complement of the sum is
4669  returned. If Length is 0, then 0 is returned.
4670 
4671  If Buffer is NULL, then ASSERT().
4672  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4673 
4674  @param Buffer The pointer to the buffer to carry out the checksum operation.
4675  @param Length The size, in bytes, of Buffer.
4676 
4677  @return Checksum The two's complement checksum of Buffer.
4678 
4679 **/
4680 UINT8
4681 EFIAPI
4683  IN CONST UINT8 *Buffer,
4684  IN UINTN Length
4685  );
4686 
4687 /**
4688  Returns the sum of all elements in a buffer of 16-bit values. During
4689  calculation, the carry bits are dropped.
4690 
4691  This function calculates the sum of the 16-bit values in the buffer
4692  specified by Buffer and Length. The carry bits in result of addition are dropped.
4693  The 16-bit result is returned. If Length is 0, then 0 is returned.
4694 
4695  If Buffer is NULL, then ASSERT().
4696  If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4697  If Length is not aligned on a 16-bit boundary, then ASSERT().
4698  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4699 
4700  @param Buffer The pointer to the buffer to carry out the sum operation.
4701  @param Length The size, in bytes, of Buffer.
4702 
4703  @return Sum The sum of Buffer with carry bits dropped during additions.
4704 
4705 **/
4706 UINT16
4707 EFIAPI
4709  IN CONST UINT16 *Buffer,
4710  IN UINTN Length
4711  );
4712 
4713 /**
4714  Returns the two's complement checksum of all elements in a buffer of
4715  16-bit values.
4716 
4717  This function first calculates the sum of the 16-bit values in the buffer
4718  specified by Buffer and Length. The carry bits in the result of addition
4719  are dropped. Then, the two's complement of the sum is returned. If Length
4720  is 0, then 0 is returned.
4721 
4722  If Buffer is NULL, then ASSERT().
4723  If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4724  If Length is not aligned on a 16-bit boundary, then ASSERT().
4725  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4726 
4727  @param Buffer The pointer to the buffer to carry out the checksum operation.
4728  @param Length The size, in bytes, of Buffer.
4729 
4730  @return Checksum The two's complement checksum of Buffer.
4731 
4732 **/
4733 UINT16
4734 EFIAPI
4736  IN CONST UINT16 *Buffer,
4737  IN UINTN Length
4738  );
4739 
4740 /**
4741  Returns the sum of all elements in a buffer of 32-bit values. During
4742  calculation, the carry bits are dropped.
4743 
4744  This function calculates the sum of the 32-bit values in the buffer
4745  specified by Buffer and Length. The carry bits in result of addition are dropped.
4746  The 32-bit result is returned. If Length is 0, then 0 is returned.
4747 
4748  If Buffer is NULL, then ASSERT().
4749  If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4750  If Length is not aligned on a 32-bit boundary, then ASSERT().
4751  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4752 
4753  @param Buffer The pointer to the buffer to carry out the sum operation.
4754  @param Length The size, in bytes, of Buffer.
4755 
4756  @return Sum The sum of Buffer with carry bits dropped during additions.
4757 
4758 **/
4759 UINT32
4760 EFIAPI
4762  IN CONST UINT32 *Buffer,
4763  IN UINTN Length
4764  );
4765 
4766 /**
4767  Returns the two's complement checksum of all elements in a buffer of
4768  32-bit values.
4769 
4770  This function first calculates the sum of the 32-bit values in the buffer
4771  specified by Buffer and Length. The carry bits in the result of addition
4772  are dropped. Then, the two's complement of the sum is returned. If Length
4773  is 0, then 0 is returned.
4774 
4775  If Buffer is NULL, then ASSERT().
4776  If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4777  If Length is not aligned on a 32-bit boundary, then ASSERT().
4778  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4779 
4780  @param Buffer The pointer to the buffer to carry out the checksum operation.
4781  @param Length The size, in bytes, of Buffer.
4782 
4783  @return Checksum The two's complement checksum of Buffer.
4784 
4785 **/
4786 UINT32
4787 EFIAPI
4789  IN CONST UINT32 *Buffer,
4790  IN UINTN Length
4791  );
4792 
4793 /**
4794  Returns the sum of all elements in a buffer of 64-bit values. During
4795  calculation, the carry bits are dropped.
4796 
4797  This function calculates the sum of the 64-bit values in the buffer
4798  specified by Buffer and Length. The carry bits in result of addition are dropped.
4799  The 64-bit result is returned. If Length is 0, then 0 is returned.
4800 
4801  If Buffer is NULL, then ASSERT().
4802  If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4803  If Length is not aligned on a 64-bit boundary, then ASSERT().
4804  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4805 
4806  @param Buffer The pointer to the buffer to carry out the sum operation.
4807  @param Length The size, in bytes, of Buffer.
4808 
4809  @return Sum The sum of Buffer with carry bits dropped during additions.
4810 
4811 **/
4812 UINT64
4813 EFIAPI
4815  IN CONST UINT64 *Buffer,
4816  IN UINTN Length
4817  );
4818 
4819 /**
4820  Returns the two's complement checksum of all elements in a buffer of
4821  64-bit values.
4822 
4823  This function first calculates the sum of the 64-bit values in the buffer
4824  specified by Buffer and Length. The carry bits in the result of addition
4825  are dropped. Then, the two's complement of the sum is returned. If Length
4826  is 0, then 0 is returned.
4827 
4828  If Buffer is NULL, then ASSERT().
4829  If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4830  If Length is not aligned on a 64-bit boundary, then ASSERT().
4831  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4832 
4833  @param Buffer The pointer to the buffer to carry out the checksum operation.
4834  @param Length The size, in bytes, of Buffer.
4835 
4836  @return Checksum The two's complement checksum of Buffer.
4837 
4838 **/
4839 UINT64
4840 EFIAPI
4842  IN CONST UINT64 *Buffer,
4843  IN UINTN Length
4844  );
4845 
4846 /**
4847  Computes and returns a 32-bit CRC for a data buffer.
4848  CRC32 value bases on ITU-T V.42.
4849 
4850  If Buffer is NULL, then ASSERT().
4851  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4852 
4853  @param[in] Buffer A pointer to the buffer on which the 32-bit CRC is to be computed.
4854  @param[in] Length The number of bytes in the buffer Data.
4855 
4856  @retval Crc32 The 32-bit CRC was computed for the data buffer.
4857 
4858 **/
4859 UINT32
4860 EFIAPI
4862  IN VOID *Buffer,
4863  IN UINTN Length
4864  );
4865 
4866 /**
4867  Calculates the CRC16-ANSI checksum of the given buffer.
4868 
4869  @param[in] Buffer Pointer to the buffer.
4870  @param[in] Length Length of the buffer, in bytes.
4871  @param[in] InitialValue Initial value of the CRC.
4872 
4873  @return The CRC16-ANSI checksum.
4874 **/
4875 UINT16
4876 EFIAPI
4878  IN CONST VOID *Buffer,
4879  IN UINTN Length,
4880  IN UINT16 InitialValue
4881  );
4882 
4883 //
4884 // Initial value for the CRC16-ANSI algorithm, when no prior checksum has been calculated.
4885 //
4886 #define CRC16ANSI_INIT 0xffff
4887 
4888 /**
4889  Calculates the CRC32c checksum of the given buffer.
4890 
4891  @param[in] Buffer Pointer to the buffer.
4892  @param[in] Length Length of the buffer, in bytes.
4893  @param[in] InitialValue Initial value of the CRC.
4894 
4895  @return The CRC32c checksum.
4896 **/
4897 UINT32
4898 EFIAPI
4900  IN CONST VOID *Buffer,
4901  IN UINTN Length,
4902  IN UINT32 InitialValue
4903  );
4904 
4905 //
4906 // Base Library CPU Functions
4907 //
4908 
4909 /**
4910  Function entry point used when a stack switch is requested with SwitchStack()
4911 
4912  @param Context1 Context1 parameter passed into SwitchStack().
4913  @param Context2 Context2 parameter passed into SwitchStack().
4914 **/
4915 typedef
4916 VOID
4918  IN VOID *Context1 OPTIONAL,
4919  IN VOID *Context2 OPTIONAL
4920  );
4921 
4922 /**
4923  Used to serialize load and store operations.
4924 
4925  All loads and stores that proceed calls to this function are guaranteed to be
4926  globally visible when this function returns.
4927 
4928 **/
4929 VOID
4930 EFIAPI
4931 MemoryFence (
4932  VOID
4933  );
4934 
4935 /**
4936  Saves the current CPU context that can be restored with a call to LongJump()
4937  and returns 0.
4938 
4939  Saves the current CPU context in the buffer specified by JumpBuffer and
4940  returns 0. The initial call to SetJump() must always return 0. Subsequent
4941  calls to LongJump() cause a non-zero value to be returned by SetJump().
4942 
4943  If JumpBuffer is NULL, then ASSERT().
4944  For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4945 
4946  NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
4947  The same structure must never be used for more than one CPU architecture context.
4948  For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
4949  SetJump()/LongJump() is not currently supported for the EBC processor type.
4950 
4951  @param JumpBuffer A pointer to CPU context buffer.
4952 
4953  @retval 0 Indicates a return from SetJump().
4954 
4955 **/
4957 UINTN
4958 EFIAPI
4959 SetJump (
4960  OUT BASE_LIBRARY_JUMP_BUFFER *JumpBuffer
4961  );
4962 
4963 /**
4964  Restores the CPU context that was saved with SetJump().
4965 
4966  Restores the CPU context from the buffer specified by JumpBuffer. This
4967  function never returns to the caller. Instead is resumes execution based on
4968  the state of JumpBuffer.
4969 
4970  If JumpBuffer is NULL, then ASSERT().
4971  For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4972  If Value is 0, then ASSERT().
4973 
4974  @param JumpBuffer A pointer to CPU context buffer.
4975  @param Value The value to return when the SetJump() context is
4976  restored and must be non-zero.
4977 
4978 **/
4979 VOID
4980 EFIAPI
4981 LongJump (
4982  IN BASE_LIBRARY_JUMP_BUFFER *JumpBuffer,
4983  IN UINTN Value
4984  );
4985 
4986 /**
4987  Enables CPU interrupts.
4988 
4989 **/
4990 VOID
4991 EFIAPI
4993  VOID
4994  );
4995 
4996 /**
4997  Disables CPU interrupts.
4998 
4999 **/
5000 VOID
5001 EFIAPI
5003  VOID
5004  );
5005 
5006 /**
5007  Disables CPU interrupts and returns the interrupt state prior to the disable
5008  operation.
5009 
5010  @retval TRUE CPU interrupts were enabled on entry to this call.
5011  @retval FALSE CPU interrupts were disabled on entry to this call.
5012 
5013 **/
5014 BOOLEAN
5015 EFIAPI
5017  VOID
5018  );
5019 
5020 /**
5021  Enables CPU interrupts for the smallest window required to capture any
5022  pending interrupts.
5023 
5024 **/
5025 VOID
5026 EFIAPI
5028  VOID
5029  );
5030 
5031 /**
5032  Retrieves the current CPU interrupt state.
5033 
5034  Returns TRUE if interrupts are currently enabled. Otherwise
5035  returns FALSE.
5036 
5037  @retval TRUE CPU interrupts are enabled.
5038  @retval FALSE CPU interrupts are disabled.
5039 
5040 **/
5041 BOOLEAN
5042 EFIAPI
5044  VOID
5045  );
5046 
5047 /**
5048  Set the current CPU interrupt state.
5049 
5050  Sets the current CPU interrupt state to the state specified by
5051  InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
5052  InterruptState is FALSE, then interrupts are disabled. InterruptState is
5053  returned.
5054 
5055  @param InterruptState TRUE if interrupts should enabled. FALSE if
5056  interrupts should be disabled.
5057 
5058  @return InterruptState
5059 
5060 **/
5061 BOOLEAN
5062 EFIAPI
5064  IN BOOLEAN InterruptState
5065  );
5066 
5067 /**
5068  Requests CPU to pause for a short period of time.
5069 
5070  Requests CPU to pause for a short period of time. Typically used in MP
5071  systems to prevent memory starvation while waiting for a spin lock.
5072 
5073 **/
5074 VOID
5075 EFIAPI
5076 CpuPause (
5077  VOID
5078  );
5079 
5080 /**
5081  Transfers control to a function starting with a new stack.
5082 
5083  Transfers control to the function specified by EntryPoint using the
5084  new stack specified by NewStack and passing in the parameters specified
5085  by Context1 and Context2. Context1 and Context2 are optional and may
5086  be NULL. The function EntryPoint must never return. This function
5087  supports a variable number of arguments following the NewStack parameter.
5088  These additional arguments are ignored on IA-32, x64, and EBC architectures.
5089  Itanium processors expect one additional parameter of type VOID * that specifies
5090  the new backing store pointer.
5091 
5092  If EntryPoint is NULL, then ASSERT().
5093  If NewStack is NULL, then ASSERT().
5094 
5095  @param EntryPoint A pointer to function to call with the new stack.
5096  @param Context1 A pointer to the context to pass into the EntryPoint
5097  function.
5098  @param Context2 A pointer to the context to pass into the EntryPoint
5099  function.
5100  @param NewStack A pointer to the new stack to use for the EntryPoint
5101  function.
5102  @param ... This variable argument list is ignored for IA-32, x64, and
5103  EBC architectures. For Itanium processors, this variable
5104  argument list is expected to contain a single parameter of
5105  type VOID * that specifies the new backing store pointer.
5106 
5107 
5108 **/
5109 VOID
5110 EFIAPI
5111 SwitchStack (
5112  IN SWITCH_STACK_ENTRY_POINT EntryPoint,
5113  IN VOID *Context1 OPTIONAL,
5114  IN VOID *Context2 OPTIONAL,
5115  IN VOID *NewStack,
5116  ...
5117  );
5118 
5119 /**
5120  Generates a breakpoint on the CPU.
5121 
5122  Generates a breakpoint on the CPU. The breakpoint must be implemented such
5123  that code can resume normal execution after the breakpoint.
5124 
5125 **/
5126 VOID
5127 EFIAPI
5128 CpuBreakpoint (
5129  VOID
5130  );
5131 
5132 /**
5133  Executes an infinite loop.
5134 
5135  Forces the CPU to execute an infinite loop. A debugger may be used to skip
5136  past the loop and the code that follows the loop must execute properly. This
5137  implies that the infinite loop must not cause the code that follow it to be
5138  optimized away.
5139 
5140 **/
5141 VOID
5142 EFIAPI
5143 CpuDeadLoop (
5144  VOID
5145  );
5146 
5147 /**
5148  Uses as a barrier to stop speculative execution.
5149 
5150  Ensures that no later instruction will execute speculatively, until all prior
5151  instructions have completed.
5152 
5153 **/
5154 VOID
5155 EFIAPI
5157  VOID
5158  );
5159 
5160 #if defined (MDE_CPU_X64) || defined (MDE_CPU_IA32)
5161 
5162 /**
5163  The TDCALL instruction causes a VM exit to the Intel TDX module. It is
5164  used to call guest-side Intel TDX functions, either local or a TD exit
5165  to the host VMM, as selected by Leaf.
5166 
5167  @param[in] Leaf Leaf number of TDCALL instruction
5168  @param[in] Arg1 Arg1
5169  @param[in] Arg2 Arg2
5170  @param[in] Arg3 Arg3
5171  @param[in,out] Results Returned result of the Leaf function
5172 
5173  @return 0 A successful call
5174  @return Other See individual leaf functions
5175 **/
5176 UINTN
5177 EFIAPI
5178 TdCall (
5179  IN UINT64 Leaf,
5180  IN UINT64 Arg1,
5181  IN UINT64 Arg2,
5182  IN UINT64 Arg3,
5183  IN OUT VOID *Results
5184  );
5185 
5186 /**
5187  TDVMALL is a leaf function 0 for TDCALL. It helps invoke services from the
5188  host VMM to pass/receive information.
5189 
5190  @param[in] Leaf Number of sub-functions
5191  @param[in] Arg1 Arg1
5192  @param[in] Arg2 Arg2
5193  @param[in] Arg3 Arg3
5194  @param[in] Arg4 Arg4
5195  @param[in,out] Results Returned result of the sub-function
5196 
5197  @return 0 A successful call
5198  @return Other See individual sub-functions
5199 
5200 **/
5201 UINTN
5202 EFIAPI
5203 TdVmCall (
5204  IN UINT64 Leaf,
5205  IN UINT64 Arg1,
5206  IN UINT64 Arg2,
5207  IN UINT64 Arg3,
5208  IN UINT64 Arg4,
5209  IN OUT VOID *Results
5210  );
5211 
5212 /**
5213  Probe if TD is enabled.
5214 
5215  @return TRUE TD is enabled.
5216  @return FALSE TD is not enabled.
5217 **/
5218 BOOLEAN
5219 EFIAPI
5220 TdIsEnabled (
5221  VOID
5222  );
5223 
5224 #endif
5225 
5226 #if defined (MDE_CPU_X64)
5227 //
5228 // The page size for the PVALIDATE instruction
5229 //
5230 typedef enum {
5231  PvalidatePageSize4K = 0,
5232  PvalidatePageSize2MB,
5233 } PVALIDATE_PAGE_SIZE;
5234 
5235 //
5236 // PVALIDATE Return Code.
5237 //
5238 #define PVALIDATE_RET_SUCCESS 0
5239 #define PVALIDATE_RET_FAIL_INPUT 1
5240 #define PVALIDATE_RET_SIZE_MISMATCH 6
5241 
5242 //
5243 // The PVALIDATE instruction did not make any changes to the RMP entry.
5244 //
5245 #define PVALIDATE_RET_NO_RMPUPDATE 255
5246 
5247 /**
5248  Execute a PVALIDATE instruction to validate or to rescinds validation of a guest
5249  page's RMP entry.
5250 
5251  The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
5252 
5253  The function is available on X64.
5254 
5255  @param[in] PageSize The page size to use.
5256  @param[in] Validate If TRUE, validate the guest virtual address
5257  otherwise invalidate the guest virtual address.
5258  @param[in] Address The guest virtual address.
5259 
5260  @retval PVALIDATE_RET_SUCCESS The PVALIDATE instruction succeeded, and
5261  updated the RMP entry.
5262  @retval PVALIDATE_RET_NO_RMPUPDATE The PVALIDATE instruction succeeded, but
5263  did not update the RMP entry.
5264  @return Failure code from the PVALIDATE
5265  instruction.
5266 **/
5267 UINT32
5268 EFIAPI
5269 AsmPvalidate (
5270  IN PVALIDATE_PAGE_SIZE PageSize,
5271  IN BOOLEAN Validate,
5273  );
5274 
5275 //
5276 // RDX settings for RMPADJUST
5277 //
5278 #define RMPADJUST_VMPL_MAX 3
5279 #define RMPADJUST_VMPL_MASK 0xFF
5280 #define RMPADJUST_VMPL_SHIFT 0
5281 #define RMPADJUST_PERMISSION_MASK_MASK 0xFF
5282 #define RMPADJUST_PERMISSION_MASK_SHIFT 8
5283 #define RMPADJUST_VMSA_PAGE_BIT BIT16
5284 
5285 /**
5286  Adjusts the permissions of an SEV-SNP guest page.
5287 
5288  Executes a RMPADJUST instruction with the register state specified by Rax,
5289  Rcx, and Rdx. Returns Eax. This function is only available on X64.
5290 
5291  The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
5292 
5293  @param[in] Rax The value to load into RAX before executing the RMPADJUST
5294  instruction.
5295  @param[in] Rcx The value to load into RCX before executing the RMPADJUST
5296  instruction.
5297  @param[in] Rdx The value to load into RDX before executing the RMPADJUST
5298  instruction.
5299 
5300  @return Eax
5301 **/
5302 UINT32
5303 EFIAPI
5304 AsmRmpAdjust (
5305  IN UINT64 Rax,
5306  IN UINT64 Rcx,
5307  IN UINT64 Rdx
5308  );
5309 
5310 #endif
5311 
5312 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
5313 ///
5314 /// IA32 and x64 Specific Functions.
5315 /// Byte packed structure for 16-bit Real Mode EFLAGS.
5316 ///
5317 typedef union {
5318  struct {
5319  UINT32 CF : 1; ///< Carry Flag.
5320  UINT32 Reserved_0 : 1; ///< Reserved.
5321  UINT32 PF : 1; ///< Parity Flag.
5322  UINT32 Reserved_1 : 1; ///< Reserved.
5323  UINT32 AF : 1; ///< Auxiliary Carry Flag.
5324  UINT32 Reserved_2 : 1; ///< Reserved.
5325  UINT32 ZF : 1; ///< Zero Flag.
5326  UINT32 SF : 1; ///< Sign Flag.
5327  UINT32 TF : 1; ///< Trap Flag.
5328  UINT32 IF : 1; ///< Interrupt Enable Flag.
5329  UINT32 DF : 1; ///< Direction Flag.
5330  UINT32 OF : 1; ///< Overflow Flag.
5331  UINT32 IOPL : 2; ///< I/O Privilege Level.
5332  UINT32 NT : 1; ///< Nested Task.
5333  UINT32 Reserved_3 : 1; ///< Reserved.
5334  } Bits;
5335  UINT16 Uint16;
5336 } IA32_FLAGS16;
5337 
5338 ///
5339 /// Byte packed structure for EFLAGS/RFLAGS.
5340 /// 32-bits on IA-32.
5341 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5342 ///
5343 typedef union {
5344  struct {
5345  UINT32 CF : 1; ///< Carry Flag.
5346  UINT32 Reserved_0 : 1; ///< Reserved.
5347  UINT32 PF : 1; ///< Parity Flag.
5348  UINT32 Reserved_1 : 1; ///< Reserved.
5349  UINT32 AF : 1; ///< Auxiliary Carry Flag.
5350  UINT32 Reserved_2 : 1; ///< Reserved.
5351  UINT32 ZF : 1; ///< Zero Flag.
5352  UINT32 SF : 1; ///< Sign Flag.
5353  UINT32 TF : 1; ///< Trap Flag.
5354  UINT32 IF : 1; ///< Interrupt Enable Flag.
5355  UINT32 DF : 1; ///< Direction Flag.
5356  UINT32 OF : 1; ///< Overflow Flag.
5357  UINT32 IOPL : 2; ///< I/O Privilege Level.
5358  UINT32 NT : 1; ///< Nested Task.
5359  UINT32 Reserved_3 : 1; ///< Reserved.
5360  UINT32 RF : 1; ///< Resume Flag.
5361  UINT32 VM : 1; ///< Virtual 8086 Mode.
5362  UINT32 AC : 1; ///< Alignment Check.
5363  UINT32 VIF : 1; ///< Virtual Interrupt Flag.
5364  UINT32 VIP : 1; ///< Virtual Interrupt Pending.
5365  UINT32 ID : 1; ///< ID Flag.
5366  UINT32 Reserved_4 : 10; ///< Reserved.
5367  } Bits;
5368  UINTN UintN;
5369 } IA32_EFLAGS32;
5370 
5371 ///
5372 /// Byte packed structure for Control Register 0 (CR0).
5373 /// 32-bits on IA-32.
5374 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5375 ///
5376 typedef union {
5377  struct {
5378  UINT32 PE : 1; ///< Protection Enable.
5379  UINT32 MP : 1; ///< Monitor Coprocessor.
5380  UINT32 EM : 1; ///< Emulation.
5381  UINT32 TS : 1; ///< Task Switched.
5382  UINT32 ET : 1; ///< Extension Type.
5383  UINT32 NE : 1; ///< Numeric Error.
5384  UINT32 Reserved_0 : 10; ///< Reserved.
5385  UINT32 WP : 1; ///< Write Protect.
5386  UINT32 Reserved_1 : 1; ///< Reserved.
5387  UINT32 AM : 1; ///< Alignment Mask.
5388  UINT32 Reserved_2 : 10; ///< Reserved.
5389  UINT32 NW : 1; ///< Mot Write-through.
5390  UINT32 CD : 1; ///< Cache Disable.
5391  UINT32 PG : 1; ///< Paging.
5392  } Bits;
5393  UINTN UintN;
5394 } IA32_CR0;
5395 
5396 ///
5397 /// Byte packed structure for Control Register 4 (CR4).
5398 /// 32-bits on IA-32.
5399 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5400 ///
5401 typedef union {
5402  struct {
5403  UINT32 VME : 1; ///< Virtual-8086 Mode Extensions.
5404  UINT32 PVI : 1; ///< Protected-Mode Virtual Interrupts.
5405  UINT32 TSD : 1; ///< Time Stamp Disable.
5406  UINT32 DE : 1; ///< Debugging Extensions.
5407  UINT32 PSE : 1; ///< Page Size Extensions.
5408  UINT32 PAE : 1; ///< Physical Address Extension.
5409  UINT32 MCE : 1; ///< Machine Check Enable.
5410  UINT32 PGE : 1; ///< Page Global Enable.
5411  UINT32 PCE : 1; ///< Performance Monitoring Counter
5412  ///< Enable.
5413  UINT32 OSFXSR : 1; ///< Operating System Support for
5414  ///< FXSAVE and FXRSTOR instructions
5415  UINT32 OSXMMEXCPT : 1; ///< Operating System Support for
5416  ///< Unmasked SIMD Floating Point
5417  ///< Exceptions.
5418  UINT32 UMIP : 1; ///< User-Mode Instruction Prevention.
5419  UINT32 LA57 : 1; ///< Linear Address 57bit.
5420  UINT32 VMXE : 1; ///< VMX Enable.
5421  UINT32 SMXE : 1; ///< SMX Enable.
5422  UINT32 Reserved_3 : 1; ///< Reserved.
5423  UINT32 FSGSBASE : 1; ///< FSGSBASE Enable.
5424  UINT32 PCIDE : 1; ///< PCID Enable.
5425  UINT32 OSXSAVE : 1; ///< XSAVE and Processor Extended States Enable.
5426  UINT32 Reserved_4 : 1; ///< Reserved.
5427  UINT32 SMEP : 1; ///< SMEP Enable.
5428  UINT32 SMAP : 1; ///< SMAP Enable.
5429  UINT32 PKE : 1; ///< Protection-Key Enable.
5430  UINT32 Reserved_5 : 9; ///< Reserved.
5431  } Bits;
5432  UINTN UintN;
5433 } IA32_CR4;
5434 
5435 ///
5436 /// Byte packed structure for a segment descriptor in a GDT/LDT.
5437 ///
5438 typedef union {
5439  struct {
5440  UINT32 LimitLow : 16;
5441  UINT32 BaseLow : 16;
5442  UINT32 BaseMid : 8;
5443  UINT32 Type : 4;
5444  UINT32 S : 1;
5445  UINT32 DPL : 2;
5446  UINT32 P : 1;
5447  UINT32 LimitHigh : 4;
5448  UINT32 AVL : 1;
5449  UINT32 L : 1;
5450  UINT32 DB : 1;
5451  UINT32 G : 1;
5452  UINT32 BaseHigh : 8;
5453  } Bits;
5454  UINT64 Uint64;
5455 } IA32_SEGMENT_DESCRIPTOR;
5456 
5457 ///
5458 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5459 ///
5460  #pragma pack (1)
5461 typedef struct {
5462  UINT16 Limit;
5463  UINTN Base;
5464 } IA32_DESCRIPTOR;
5465  #pragma pack ()
5466 
5467 #define IA32_IDT_GATE_TYPE_TASK 0x85
5468 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86
5469 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87
5470 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E
5471 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F
5472 
5473 #define IA32_GDT_TYPE_TSS 0x9
5474 #define IA32_GDT_ALIGNMENT 8
5475 
5476  #if defined (MDE_CPU_IA32)
5477 ///
5478 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5479 ///
5480 typedef union {
5481  struct {
5482  UINT32 OffsetLow : 16; ///< Offset bits 15..0.
5483  UINT32 Selector : 16; ///< Selector.
5484  UINT32 Reserved_0 : 8; ///< Reserved.
5485  UINT32 GateType : 8; ///< Gate Type. See #defines above.
5486  UINT32 OffsetHigh : 16; ///< Offset bits 31..16.
5487  } Bits;
5488  UINT64 Uint64;
5489 } IA32_IDT_GATE_DESCRIPTOR;
5490 
5491  #pragma pack (1)
5492 //
5493 // IA32 Task-State Segment Definition
5494 //
5495 typedef struct {
5496  UINT16 PreviousTaskLink;
5497  UINT16 Reserved_2;
5498  UINT32 ESP0;
5499  UINT16 SS0;
5500  UINT16 Reserved_10;
5501  UINT32 ESP1;
5502  UINT16 SS1;
5503  UINT16 Reserved_18;
5504  UINT32 ESP2;
5505  UINT16 SS2;
5506  UINT16 Reserved_26;
5507  UINT32 CR3;
5508  UINT32 EIP;
5509  UINT32 EFLAGS;
5510  UINT32 EAX;
5511  UINT32 ECX;
5512  UINT32 EDX;
5513  UINT32 EBX;
5514  UINT32 ESP;
5515  UINT32 EBP;
5516  UINT32 ESI;
5517  UINT32 EDI;
5518  UINT16 ES;
5519  UINT16 Reserved_74;
5520  UINT16 CS;
5521  UINT16 Reserved_78;
5522  UINT16 SS;
5523  UINT16 Reserved_82;
5524  UINT16 DS;
5525  UINT16 Reserved_86;
5526  UINT16 FS;
5527  UINT16 Reserved_90;
5528  UINT16 GS;
5529  UINT16 Reserved_94;
5530  UINT16 LDTSegmentSelector;
5531  UINT16 Reserved_98;
5532  UINT16 T;
5533  UINT16 IOMapBaseAddress;
5534 } IA32_TASK_STATE_SEGMENT;
5535 
5536 typedef union {
5537  struct {
5538  UINT32 LimitLow : 16; ///< Segment Limit 15..00
5539  UINT32 BaseLow : 16; ///< Base Address 15..00
5540  UINT32 BaseMid : 8; ///< Base Address 23..16
5541  UINT32 Type : 4; ///< Type (1 0 B 1)
5542  UINT32 Reserved_43 : 1; ///< 0
5543  UINT32 DPL : 2; ///< Descriptor Privilege Level
5544  UINT32 P : 1; ///< Segment Present
5545  UINT32 LimitHigh : 4; ///< Segment Limit 19..16
5546  UINT32 AVL : 1; ///< Available for use by system software
5547  UINT32 Reserved_52 : 2; ///< 0 0
5548  UINT32 G : 1; ///< Granularity
5549  UINT32 BaseHigh : 8; ///< Base Address 31..24
5550  } Bits;
5551  UINT64 Uint64;
5552 } IA32_TSS_DESCRIPTOR;
5553  #pragma pack ()
5554 
5555  #endif // defined (MDE_CPU_IA32)
5556 
5557  #if defined (MDE_CPU_X64)
5558 ///
5559 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5560 ///
5561 typedef union {
5562  struct {
5563  UINT32 OffsetLow : 16; ///< Offset bits 15..0.
5564  UINT32 Selector : 16; ///< Selector.
5565  UINT32 Reserved_0 : 8; ///< Reserved.
5566  UINT32 GateType : 8; ///< Gate Type. See #defines above.
5567  UINT32 OffsetHigh : 16; ///< Offset bits 31..16.
5568  UINT32 OffsetUpper : 32; ///< Offset bits 63..32.
5569  UINT32 Reserved_1 : 32; ///< Reserved.
5570  } Bits;
5571  struct {
5572  UINT64 Uint64;
5573  UINT64 Uint64_1;
5574  } Uint128;
5575 } IA32_IDT_GATE_DESCRIPTOR;
5576 
5577  #pragma pack (1)
5578 //
5579 // IA32 Task-State Segment Definition
5580 //
5581 typedef struct {
5582  UINT32 Reserved_0;
5583  UINT64 RSP0;
5584  UINT64 RSP1;
5585  UINT64 RSP2;
5586  UINT64 Reserved_28;
5587  UINT64 IST[7];
5588  UINT64 Reserved_92;
5589  UINT16 Reserved_100;
5590  UINT16 IOMapBaseAddress;
5591 } IA32_TASK_STATE_SEGMENT;
5592 
5593 typedef union {
5594  struct {
5595  UINT32 LimitLow : 16; ///< Segment Limit 15..00
5596  UINT32 BaseLow : 16; ///< Base Address 15..00
5597  UINT32 BaseMidl : 8; ///< Base Address 23..16
5598  UINT32 Type : 4; ///< Type (1 0 B 1)
5599  UINT32 Reserved_43 : 1; ///< 0
5600  UINT32 DPL : 2; ///< Descriptor Privilege Level
5601  UINT32 P : 1; ///< Segment Present
5602  UINT32 LimitHigh : 4; ///< Segment Limit 19..16
5603  UINT32 AVL : 1; ///< Available for use by system software
5604  UINT32 Reserved_52 : 2; ///< 0 0
5605  UINT32 G : 1; ///< Granularity
5606  UINT32 BaseMidh : 8; ///< Base Address 31..24
5607  UINT32 BaseHigh : 32; ///< Base Address 63..32
5608  UINT32 Reserved_96 : 32; ///< Reserved
5609  } Bits;
5610  struct {
5611  UINT64 Uint64;
5612  UINT64 Uint64_1;
5613  } Uint128;
5614 } IA32_TSS_DESCRIPTOR;
5615  #pragma pack ()
5616 
5617  #endif // defined (MDE_CPU_X64)
5618 
5619 ///
5620 /// Byte packed structure for an FP/SSE/SSE2 context.
5621 ///
5622 typedef struct {
5623  UINT8 Buffer[512];
5624 } IA32_FX_BUFFER;
5625 
5626 ///
5627 /// Structures for the 16-bit real mode thunks.
5628 ///
5629 typedef struct {
5630  UINT32 Reserved1;
5631  UINT32 Reserved2;
5632  UINT32 Reserved3;
5633  UINT32 Reserved4;
5634  UINT8 BL;
5635  UINT8 BH;
5636  UINT16 Reserved5;
5637  UINT8 DL;
5638  UINT8 DH;
5639  UINT16 Reserved6;
5640  UINT8 CL;
5641  UINT8 CH;
5642  UINT16 Reserved7;
5643  UINT8 AL;
5644  UINT8 AH;
5645  UINT16 Reserved8;
5646 } IA32_BYTE_REGS;
5647 
5648 typedef struct {
5649  UINT16 DI;
5650  UINT16 Reserved1;
5651  UINT16 SI;
5652  UINT16 Reserved2;
5653  UINT16 BP;
5654  UINT16 Reserved3;
5655  UINT16 SP;
5656  UINT16 Reserved4;
5657  UINT16 BX;
5658  UINT16 Reserved5;
5659  UINT16 DX;
5660  UINT16 Reserved6;
5661  UINT16 CX;
5662  UINT16 Reserved7;
5663  UINT16 AX;
5664  UINT16 Reserved8;
5665 } IA32_WORD_REGS;
5666 
5667 typedef struct {
5668  UINT32 EDI;
5669  UINT32 ESI;
5670  UINT32 EBP;
5671  UINT32 ESP;
5672  UINT32 EBX;
5673  UINT32 EDX;
5674  UINT32 ECX;
5675  UINT32 EAX;
5676  UINT16 DS;
5677  UINT16 ES;
5678  UINT16 FS;
5679  UINT16 GS;
5680  IA32_EFLAGS32 EFLAGS;
5681  UINT32 Eip;
5682  UINT16 CS;
5683  UINT16 SS;
5684 } IA32_DWORD_REGS;
5685 
5686 typedef union {
5687  IA32_DWORD_REGS E;
5688  IA32_WORD_REGS X;
5689  IA32_BYTE_REGS H;
5690 } IA32_REGISTER_SET;
5691 
5692 ///
5693 /// Byte packed structure for an 16-bit real mode thunks.
5694 ///
5695 typedef struct {
5696  IA32_REGISTER_SET *RealModeState;
5697  VOID *RealModeBuffer;
5698  UINT32 RealModeBufferSize;
5699  UINT32 ThunkAttributes;
5700 } THUNK_CONTEXT;
5701 
5702 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001
5703 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002
5704 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
5705 
5706 ///
5707 /// Type definition for representing labels in NASM source code that allow for
5708 /// the patching of immediate operands of IA32 and X64 instructions.
5709 ///
5710 /// While the type is technically defined as a function type (note: not a
5711 /// pointer-to-function type), such labels in NASM source code never stand for
5712 /// actual functions, and identifiers declared with this function type should
5713 /// never be called. This is also why the EFIAPI calling convention specifier
5714 /// is missing from the typedef, and why the typedef does not follow the usual
5715 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5716 /// return type and the VOID argument list are merely artifacts.
5717 ///
5718 typedef VOID (X86_ASSEMBLY_PATCH_LABEL) (
5719  VOID
5720  );
5721 
5722 /**
5723  Retrieves CPUID information.
5724 
5725  Executes the CPUID instruction with EAX set to the value specified by Index.
5726  This function always returns Index.
5727  If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5728  If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5729  If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5730  If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5731  This function is only available on IA-32 and x64.
5732 
5733  @param Index The 32-bit value to load into EAX prior to invoking the CPUID
5734  instruction.
5735  @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5736  instruction. This is an optional parameter that may be NULL.
5737  @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5738  instruction. This is an optional parameter that may be NULL.
5739  @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5740  instruction. This is an optional parameter that may be NULL.
5741  @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5742  instruction. This is an optional parameter that may be NULL.
5743 
5744  @return Index.
5745 
5746 **/
5747 UINT32
5748 EFIAPI
5749 AsmCpuid (
5750  IN UINT32 Index,
5751  OUT UINT32 *Eax OPTIONAL,
5752  OUT UINT32 *Ebx OPTIONAL,
5753  OUT UINT32 *Ecx OPTIONAL,
5754  OUT UINT32 *Edx OPTIONAL
5755  );
5756 
5757 /**
5758  Retrieves CPUID information using an extended leaf identifier.
5759 
5760  Executes the CPUID instruction with EAX set to the value specified by Index
5761  and ECX set to the value specified by SubIndex. This function always returns
5762  Index. This function is only available on IA-32 and x64.
5763 
5764  If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5765  If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5766  If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5767  If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5768 
5769  @param Index The 32-bit value to load into EAX prior to invoking the
5770  CPUID instruction.
5771  @param SubIndex The 32-bit value to load into ECX prior to invoking the
5772  CPUID instruction.
5773  @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5774  instruction. This is an optional parameter that may be
5775  NULL.
5776  @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5777  instruction. This is an optional parameter that may be
5778  NULL.
5779  @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5780  instruction. This is an optional parameter that may be
5781  NULL.
5782  @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5783  instruction. This is an optional parameter that may be
5784  NULL.
5785 
5786  @return Index.
5787 
5788 **/
5789 UINT32
5790 EFIAPI
5791 AsmCpuidEx (
5792  IN UINT32 Index,
5793  IN UINT32 SubIndex,
5794  OUT UINT32 *Eax OPTIONAL,
5795  OUT UINT32 *Ebx OPTIONAL,
5796  OUT UINT32 *Ecx OPTIONAL,
5797  OUT UINT32 *Edx OPTIONAL
5798  );
5799 
5800 /**
5801  Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5802 
5803  Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5804  and executing a WBINVD instruction. This function is only available on IA-32 and x64.
5805 
5806 **/
5807 VOID
5808 EFIAPI
5809 AsmDisableCache (
5810  VOID
5811  );
5812 
5813 /**
5814  Perform a WBINVD and clear both the CD and NW bits of CR0.
5815 
5816  Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5817  bits of CR0 to 0. This function is only available on IA-32 and x64.
5818 
5819 **/
5820 VOID
5821 EFIAPI
5822 AsmEnableCache (
5823  VOID
5824  );
5825 
5826 /**
5827  Returns the lower 32-bits of a Machine Specific Register(MSR).
5828 
5829  Reads and returns the lower 32-bits of the MSR specified by Index.
5830  No parameter checking is performed on Index, and some Index values may cause
5831  CPU exceptions. The caller must either guarantee that Index is valid, or the
5832  caller must set up exception handlers to catch the exceptions. This function
5833  is only available on IA-32 and x64.
5834 
5835  @param Index The 32-bit MSR index to read.
5836 
5837  @return The lower 32 bits of the MSR identified by Index.
5838 
5839 **/
5840 UINT32
5841 EFIAPI
5842 AsmReadMsr32 (
5843  IN UINT32 Index
5844  );
5845 
5846 /**
5847  Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5848  The upper 32-bits of the MSR are set to zero.
5849 
5850  Writes the 32-bit value specified by Value to the MSR specified by Index. The
5851  upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5852  the MSR is returned. No parameter checking is performed on Index or Value,
5853  and some of these may cause CPU exceptions. The caller must either guarantee
5854  that Index and Value are valid, or the caller must establish proper exception
5855  handlers. This function is only available on IA-32 and x64.
5856 
5857  @param Index The 32-bit MSR index to write.
5858  @param Value The 32-bit value to write to the MSR.
5859 
5860  @return Value
5861 
5862 **/
5863 UINT32
5864 EFIAPI
5865 AsmWriteMsr32 (
5866  IN UINT32 Index,
5867  IN UINT32 Value
5868  );
5869 
5870 /**
5871  Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5872  writes the result back to the 64-bit MSR.
5873 
5874  Reads the 64-bit MSR specified by Index, performs a bitwise OR
5875  between the lower 32-bits of the read result and the value specified by
5876  OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5877  32-bits of the value written to the MSR is returned. No parameter checking is
5878  performed on Index or OrData, and some of these may cause CPU exceptions. The
5879  caller must either guarantee that Index and OrData are valid, or the caller
5880  must establish proper exception handlers. This function is only available on
5881  IA-32 and x64.
5882 
5883  @param Index The 32-bit MSR index to write.
5884  @param OrData The value to OR with the read value from the MSR.
5885 
5886  @return The lower 32-bit value written to the MSR.
5887 
5888 **/
5889 UINT32
5890 EFIAPI
5891 AsmMsrOr32 (
5892  IN UINT32 Index,
5893  IN UINT32 OrData
5894  );
5895 
5896 /**
5897  Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5898  the result back to the 64-bit MSR.
5899 
5900  Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5901  lower 32-bits of the read result and the value specified by AndData, and
5902  writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5903  the value written to the MSR is returned. No parameter checking is performed
5904  on Index or AndData, and some of these may cause CPU exceptions. The caller
5905  must either guarantee that Index and AndData are valid, or the caller must
5906  establish proper exception handlers. This function is only available on IA-32
5907  and x64.
5908 
5909  @param Index The 32-bit MSR index to write.
5910  @param AndData The value to AND with the read value from the MSR.
5911 
5912  @return The lower 32-bit value written to the MSR.
5913 
5914 **/
5915 UINT32
5916 EFIAPI
5917 AsmMsrAnd32 (
5918  IN UINT32 Index,
5919  IN UINT32 AndData
5920  );
5921 
5922 /**
5923  Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5924  on the lower 32-bits, and writes the result back to the 64-bit MSR.
5925 
5926  Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5927  lower 32-bits of the read result and the value specified by AndData
5928  preserving the upper 32-bits, performs a bitwise OR between the
5929  result of the AND operation and the value specified by OrData, and writes the
5930  result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5931  written to the MSR is returned. No parameter checking is performed on Index,
5932  AndData, or OrData, and some of these may cause CPU exceptions. The caller
5933  must either guarantee that Index, AndData, and OrData are valid, or the
5934  caller must establish proper exception handlers. This function is only
5935  available on IA-32 and x64.
5936 
5937  @param Index The 32-bit MSR index to write.
5938  @param AndData The value to AND with the read value from the MSR.
5939  @param OrData The value to OR with the result of the AND operation.
5940 
5941  @return The lower 32-bit value written to the MSR.
5942 
5943 **/
5944 UINT32
5945 EFIAPI
5946 AsmMsrAndThenOr32 (
5947  IN UINT32 Index,
5948  IN UINT32 AndData,
5949  IN UINT32 OrData
5950  );
5951 
5952 /**
5953  Reads a bit field of an MSR.
5954 
5955  Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5956  specified by the StartBit and the EndBit. The value of the bit field is
5957  returned. The caller must either guarantee that Index is valid, or the caller
5958  must set up exception handlers to catch the exceptions. This function is only
5959  available on IA-32 and x64.
5960 
5961  If StartBit is greater than 31, then ASSERT().
5962  If EndBit is greater than 31, then ASSERT().
5963  If EndBit is less than StartBit, then ASSERT().
5964 
5965  @param Index The 32-bit MSR index to read.
5966  @param StartBit The ordinal of the least significant bit in the bit field.
5967  Range 0..31.
5968  @param EndBit The ordinal of the most significant bit in the bit field.
5969  Range 0..31.
5970 
5971  @return The bit field read from the MSR.
5972 
5973 **/
5974 UINT32
5975 EFIAPI
5976 AsmMsrBitFieldRead32 (
5977  IN UINT32 Index,
5978  IN UINTN StartBit,
5979  IN UINTN EndBit
5980  );
5981 
5982 /**
5983  Writes a bit field to an MSR.
5984 
5985  Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
5986  field is specified by the StartBit and the EndBit. All other bits in the
5987  destination MSR are preserved. The lower 32-bits of the MSR written is
5988  returned. The caller must either guarantee that Index and the data written
5989  is valid, or the caller must set up exception handlers to catch the exceptions.
5990  This function is only available on IA-32 and x64.
5991 
5992  If StartBit is greater than 31, then ASSERT().
5993  If EndBit is greater than 31, then ASSERT().
5994  If EndBit is less than StartBit, then ASSERT().
5995  If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5996 
5997  @param Index The 32-bit MSR index to write.
5998  @param StartBit The ordinal of the least significant bit in the bit field.
5999  Range 0..31.
6000  @param EndBit The ordinal of the most significant bit in the bit field.
6001  Range 0..31.
6002  @param Value New value of the bit field.
6003 
6004  @return The lower 32-bit of the value written to the MSR.
6005 
6006 **/
6007 UINT32
6008 EFIAPI
6009 AsmMsrBitFieldWrite32 (
6010  IN UINT32 Index,
6011  IN UINTN StartBit,
6012  IN UINTN EndBit,
6013  IN UINT32 Value
6014  );
6015 
6016 /**
6017  Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
6018  result back to the bit field in the 64-bit MSR.
6019 
6020  Reads the 64-bit MSR specified by Index, performs a bitwise OR
6021  between the read result and the value specified by OrData, and writes the
6022  result to the 64-bit MSR specified by Index. The lower 32-bits of the value
6023  written to the MSR are returned. Extra left bits in OrData are stripped. The
6024  caller must either guarantee that Index and the data written is valid, or
6025  the caller must set up exception handlers to catch the exceptions. This
6026  function is only available on IA-32 and x64.
6027 
6028  If StartBit is greater than 31, then ASSERT().
6029  If EndBit is greater than 31, then ASSERT().
6030  If EndBit is less than StartBit, then ASSERT().
6031  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6032 
6033  @param Index The 32-bit MSR index to write.
6034  @param StartBit The ordinal of the least significant bit in the bit field.
6035  Range 0..31.
6036  @param EndBit The ordinal of the most significant bit in the bit field.
6037  Range 0..31.
6038  @param OrData The value to OR with the read value from the MSR.
6039 
6040  @return The lower 32-bit of the value written to the MSR.
6041 
6042 **/
6043 UINT32
6044 EFIAPI
6045 AsmMsrBitFieldOr32 (
6046  IN UINT32 Index,
6047  IN UINTN StartBit,
6048  IN UINTN EndBit,
6049  IN UINT32 OrData
6050  );
6051 
6052 /**
6053  Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6054  result back to the bit field in the 64-bit MSR.
6055 
6056  Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6057  read result and the value specified by AndData, and writes the result to the
6058  64-bit MSR specified by Index. The lower 32-bits of the value written to the
6059  MSR are returned. Extra left bits in AndData are stripped. The caller must
6060  either guarantee that Index and the data written is valid, or the caller must
6061  set up exception handlers to catch the exceptions. This function is only
6062  available on IA-32 and x64.
6063 
6064  If StartBit is greater than 31, then ASSERT().
6065  If EndBit is greater than 31, then ASSERT().
6066  If EndBit is less than StartBit, then ASSERT().
6067  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6068 
6069  @param Index The 32-bit MSR index to write.
6070  @param StartBit The ordinal of the least significant bit in the bit field.
6071  Range 0..31.
6072  @param EndBit The ordinal of the most significant bit in the bit field.
6073  Range 0..31.
6074  @param AndData The value to AND with the read value from the MSR.
6075 
6076  @return The lower 32-bit of the value written to the MSR.
6077 
6078 **/
6079 UINT32
6080 EFIAPI
6081 AsmMsrBitFieldAnd32 (
6082  IN UINT32 Index,
6083  IN UINTN StartBit,
6084  IN UINTN EndBit,
6085  IN UINT32 AndData
6086  );
6087 
6088 /**
6089  Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6090  bitwise OR, and writes the result back to the bit field in the
6091  64-bit MSR.
6092 
6093  Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
6094  bitwise OR between the read result and the value specified by
6095  AndData, and writes the result to the 64-bit MSR specified by Index. The
6096  lower 32-bits of the value written to the MSR are returned. Extra left bits
6097  in both AndData and OrData are stripped. The caller must either guarantee
6098  that Index and the data written is valid, or the caller must set up exception
6099  handlers to catch the exceptions. This function is only available on IA-32
6100  and x64.
6101 
6102  If StartBit is greater than 31, then ASSERT().
6103  If EndBit is greater than 31, then ASSERT().
6104  If EndBit is less than StartBit, then ASSERT().
6105  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6106  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6107 
6108  @param Index The 32-bit MSR index to write.
6109  @param StartBit The ordinal of the least significant bit in the bit field.
6110  Range 0..31.
6111  @param EndBit The ordinal of the most significant bit in the bit field.
6112  Range 0..31.
6113  @param AndData The value to AND with the read value from the MSR.
6114  @param OrData The value to OR with the result of the AND operation.
6115 
6116  @return The lower 32-bit of the value written to the MSR.
6117 
6118 **/
6119 UINT32
6120 EFIAPI
6121 AsmMsrBitFieldAndThenOr32 (
6122  IN UINT32 Index,
6123  IN UINTN StartBit,
6124  IN UINTN EndBit,
6125  IN UINT32 AndData,
6126  IN UINT32 OrData
6127  );
6128 
6129 /**
6130  Returns a 64-bit Machine Specific Register(MSR).
6131 
6132  Reads and returns the 64-bit MSR specified by Index. No parameter checking is
6133  performed on Index, and some Index values may cause CPU exceptions. The
6134  caller must either guarantee that Index is valid, or the caller must set up
6135  exception handlers to catch the exceptions. This function is only available
6136  on IA-32 and x64.
6137 
6138  @param Index The 32-bit MSR index to read.
6139 
6140  @return The value of the MSR identified by Index.
6141 
6142 **/
6143 UINT64
6144 EFIAPI
6145 AsmReadMsr64 (
6146  IN UINT32 Index
6147  );
6148 
6149 /**
6150  Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
6151  value.
6152 
6153  Writes the 64-bit value specified by Value to the MSR specified by Index. The
6154  64-bit value written to the MSR is returned. No parameter checking is
6155  performed on Index or Value, and some of these may cause CPU exceptions. The
6156  caller must either guarantee that Index and Value are valid, or the caller
6157  must establish proper exception handlers. This function is only available on
6158  IA-32 and x64.
6159 
6160  @param Index The 32-bit MSR index to write.
6161  @param Value The 64-bit value to write to the MSR.
6162 
6163  @return Value
6164 
6165 **/
6166 UINT64
6167 EFIAPI
6168 AsmWriteMsr64 (
6169  IN UINT32 Index,
6170  IN UINT64 Value
6171  );
6172 
6173 /**
6174  Reads a 64-bit MSR, performs a bitwise OR, and writes the result
6175  back to the 64-bit MSR.
6176 
6177  Reads the 64-bit MSR specified by Index, performs a bitwise OR
6178  between the read result and the value specified by OrData, and writes the
6179  result to the 64-bit MSR specified by Index. The value written to the MSR is
6180  returned. No parameter checking is performed on Index or OrData, and some of
6181  these may cause CPU exceptions. The caller must either guarantee that Index
6182  and OrData are valid, or the caller must establish proper exception handlers.
6183  This function is only available on IA-32 and x64.
6184 
6185  @param Index The 32-bit MSR index to write.
6186  @param OrData The value to OR with the read value from the MSR.
6187 
6188  @return The value written back to the MSR.
6189 
6190 **/
6191 UINT64
6192 EFIAPI
6193 AsmMsrOr64 (
6194  IN UINT32 Index,
6195  IN UINT64 OrData
6196  );
6197 
6198 /**
6199  Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
6200  64-bit MSR.
6201 
6202  Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6203  read result and the value specified by OrData, and writes the result to the
6204  64-bit MSR specified by Index. The value written to the MSR is returned. No
6205  parameter checking is performed on Index or OrData, and some of these may
6206  cause CPU exceptions. The caller must either guarantee that Index and OrData
6207  are valid, or the caller must establish proper exception handlers. This
6208  function is only available on IA-32 and x64.
6209 
6210  @param Index The 32-bit MSR index to write.
6211  @param AndData The value to AND with the read value from the MSR.
6212 
6213  @return The value written back to the MSR.
6214 
6215 **/
6216 UINT64
6217 EFIAPI
6218 AsmMsrAnd64 (
6219  IN UINT32 Index,
6220  IN UINT64 AndData
6221  );
6222 
6223 /**
6224  Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
6225  OR, and writes the result back to the 64-bit MSR.
6226 
6227  Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
6228  result and the value specified by AndData, performs a bitwise OR
6229  between the result of the AND operation and the value specified by OrData,
6230  and writes the result to the 64-bit MSR specified by Index. The value written
6231  to the MSR is returned. No parameter checking is performed on Index, AndData,
6232  or OrData, and some of these may cause CPU exceptions. The caller must either
6233  guarantee that Index, AndData, and OrData are valid, or the caller must
6234  establish proper exception handlers. This function is only available on IA-32
6235  and x64.
6236 
6237  @param Index The 32-bit MSR index to write.
6238  @param AndData The value to AND with the read value from the MSR.
6239  @param OrData The value to OR with the result of the AND operation.
6240 
6241  @return The value written back to the MSR.
6242 
6243 **/
6244 UINT64
6245 EFIAPI
6246 AsmMsrAndThenOr64 (
6247  IN UINT32 Index,
6248  IN UINT64 AndData,
6249  IN UINT64 OrData
6250  );
6251 
6252 /**
6253  Reads a bit field of an MSR.
6254 
6255  Reads the bit field in the 64-bit MSR. The bit field is specified by the
6256  StartBit and the EndBit. The value of the bit field is returned. The caller
6257  must either guarantee that Index is valid, or the caller must set up
6258  exception handlers to catch the exceptions. This function is only available
6259  on IA-32 and x64.
6260 
6261  If StartBit is greater than 63, then ASSERT().
6262  If EndBit is greater than 63, then ASSERT().
6263  If EndBit is less than StartBit, then ASSERT().
6264 
6265  @param Index The 32-bit MSR index to read.
6266  @param StartBit The ordinal of the least significant bit in the bit field.
6267  Range 0..63.
6268  @param EndBit The ordinal of the most significant bit in the bit field.
6269  Range 0..63.
6270 
6271  @return The value read from the MSR.
6272 
6273 **/
6274 UINT64
6275 EFIAPI
6276 AsmMsrBitFieldRead64 (
6277  IN UINT32 Index,
6278  IN UINTN StartBit,
6279  IN UINTN EndBit
6280  );
6281 
6282 /**
6283  Writes a bit field to an MSR.
6284 
6285  Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
6286  the StartBit and the EndBit. All other bits in the destination MSR are
6287  preserved. The MSR written is returned. The caller must either g