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