Update all String related functions in BaseLib for this change introduced in Mde...
[people/mcb30/edk2.git] / edk2 / MdePkg / Include / Library / BaseLib.h
1 /** @file
2   Memory-only library functions with no library constructor/destructor
3
4   Copyright (c) 2006 - 2007, Intel Corporation
5   All rights reserved. This program and the accompanying materials
6   are licensed and made available under the terms and conditions of the BSD License
7   which accompanies this distribution.  The full text of the license may be found at
8   http://opensource.org/licenses/bsd-license.php
9
10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13   Module Name:  BaseLib.h
14
15 **/
16
17 #ifndef __BASE_LIB__
18 #define __BASE_LIB__
19
20 //
21 // Definitions for architecture specific types
22 // These include SPIN_LOCK and BASE_LIBRARY_JUMP_BUFFER
23 //
24
25 //
26 // SPIN_LOCK
27 //
28 typedef UINTN                       SPIN_LOCK;
29
30 #if   defined (MDE_CPU_IA32)
31 //
32 // IA32 context buffer used by SetJump() and LongJump()
33 //
34 typedef struct {
35   UINT32                            Ebx;
36   UINT32                            Esi;
37   UINT32                            Edi;
38   UINT32                            Ebp;
39   UINT32                            Esp;
40   UINT32                            Eip;
41 } BASE_LIBRARY_JUMP_BUFFER;
42
43 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
44
45 #elif defined (MDE_CPU_IPF)
46 //
47 // IPF context buffer used by SetJump() and LongJump()
48 //
49 typedef struct {
50   UINT64                            F2[2];
51   UINT64                            F3[2];
52   UINT64                            F4[2];
53   UINT64                            F5[2];
54   UINT64                            F16[2];
55   UINT64                            F17[2];
56   UINT64                            F18[2];
57   UINT64                            F19[2];
58   UINT64                            F20[2];
59   UINT64                            F21[2];
60   UINT64                            F22[2];
61   UINT64                            F23[2];
62   UINT64                            F24[2];
63   UINT64                            F25[2];
64   UINT64                            F26[2];
65   UINT64                            F27[2];
66   UINT64                            F28[2];
67   UINT64                            F29[2];
68   UINT64                            F30[2];
69   UINT64                            F31[2];
70   UINT64                            R4;
71   UINT64                            R5;
72   UINT64                            R6;
73   UINT64                            R7;
74   UINT64                            SP;
75   UINT64                            BR0;
76   UINT64                            BR1;
77   UINT64                            BR2;
78   UINT64                            BR3;
79   UINT64                            BR4;
80   UINT64                            BR5;
81   UINT64                            InitialUNAT;
82   UINT64                            AfterSpillUNAT;
83   UINT64                            PFS;
84   UINT64                            BSP;
85   UINT64                            Predicates;
86   UINT64                            LoopCount;
87   UINT64                            FPSR;
88 } BASE_LIBRARY_JUMP_BUFFER;
89
90 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 0x10
91
92 #elif defined (MDE_CPU_X64)
93 //
94 // X64 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 } BASE_LIBRARY_JUMP_BUFFER;
108
109 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
110
111 #elif defined (MDE_CPU_EBC)
112 //
113 // EBC context buffer used by SetJump() and LongJump()
114 //
115 typedef struct {
116   UINT64                            R0;
117   UINT64                            R1;
118   UINT64                            R2;
119   UINT64                            R3;
120   UINT64                            IP;
121 } BASE_LIBRARY_JUMP_BUFFER;
122
123 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
124
125 #else
126 #error Unknown Processor Type
127 #endif
128
129 //
130 // String Services
131 //
132
133 /**
134   Copies one Null-terminated Unicode string to another Null-terminated Unicode
135   string and returns the new Unicode string.
136
137   This function copies the contents of the Unicode string Source to the Unicode
138   string Destination, and returns Destination. If Source and Destination
139   overlap, then the results are undefined.
140
141   If Destination is NULL, then ASSERT().
142   If Destination is not aligned on a 16-bit boundary, then ASSERT().
143   If Source is NULL, then ASSERT().
144   If Source is not aligned on a 16-bit boundary, then ASSERT().
145   If Source and Destination overlap, then ASSERT().
146   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
147   PcdMaximumUnicodeStringLength Unicode characters not including the
148   Null-terminator, then ASSERT().
149
150   @param  Destination Pointer to a Null-terminated Unicode string.
151   @param  Source      Pointer to a Null-terminated Unicode string.
152
153   @return Destiantion
154
155 **/
156 CHAR16 *
157 EFIAPI
158 StrCpy (
159   OUT     CHAR16                    *Destination,
160   IN      CONST CHAR16              *Source
161   );
162 /**
163   Copies one Null-terminated Unicode string with a maximum length to another
164   Null-terminated Unicode string with a maximum length and returns the new
165   Unicode string.
166
167   This function copies the contents of the Unicode string Source to the Unicode
168   string Destination, and returns Destination. At most, Length Unicode
169   characters are copied from Source to Destination. If Length is 0, then
170   Destination is returned unmodified. If Length is greater that the number of
171   Unicode characters in Source, then Destination is padded with Null Unicode
172   characters. If Source and Destination overlap, then the results are
173   undefined.
174
175   If Length > 0 and Destination is NULL, then ASSERT().
176   If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
177   If Length > 0 and Source is NULL, then ASSERT().
178   If Length > 0 and Source is not aligned on a 16-bit bounadry, then ASSERT().
179   If Source and Destination overlap, then ASSERT().
180   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
181   PcdMaximumUnicodeStringLength Unicode characters not including the
182   Null-terminator, then ASSERT().
183
184   @param  Destination Pointer to a Null-terminated Unicode string.
185   @param  Source      Pointer to a Null-terminated Unicode string.
186   @param  Length      Maximum number of Unicode characters to copy.
187
188   @return Destination
189
190 **/
191 CHAR16 *
192 EFIAPI
193 StrnCpy (
194   OUT     CHAR16                    *Destination,
195   IN      CONST CHAR16              *Source,
196   IN      UINTN                     Length
197   );
198 /**
199   Returns the length of a Null-terminated Unicode string.
200
201   This function returns the number of Unicode characters in the Null-terminated
202   Unicode string specified by String.
203
204   If String is NULL, then ASSERT().
205   If String is not aligned on a 16-bit boundary, then ASSERT().
206   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
207   PcdMaximumUnicodeStringLength Unicode characters not including the
208   Null-terminator, then ASSERT().
209
210   @param  String  Pointer to a Null-terminated Unicode string.
211
212   @return The length of String.
213
214 **/
215 UINTN
216 EFIAPI
217 StrLen (
218   IN      CONST CHAR16              *String
219   );
220 /**
221   Returns the size of a Null-terminated Unicode string in bytes, including the
222   Null terminator.
223
224   This function returns the size, in bytes, of the Null-terminated Unicode
225   string specified by String.
226
227   If String is NULL, then ASSERT().
228   If String is not aligned on a 16-bit boundary, then ASSERT().
229   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
230   PcdMaximumUnicodeStringLength Unicode characters not including the
231   Null-terminator, then ASSERT().
232
233   @param  String  Pointer to a Null-terminated Unicode string.
234
235   @return The size of String.
236
237 **/
238 UINTN
239 EFIAPI
240 StrSize (
241   IN      CONST CHAR16              *String
242   );
243 /**
244   Compares two Null-terminated Unicode strings, and returns the difference
245   between the first mismatched Unicode characters.
246
247   This function compares the Null-terminated Unicode string FirstString to the
248   Null-terminated Unicode string SecondString. If FirstString is identical to
249   SecondString, then 0 is returned. Otherwise, the value returned is the first
250   mismatched Unicode character in SecondString subtracted from the first
251   mismatched Unicode character in FirstString.
252
253   If FirstString is NULL, then ASSERT().
254   If FirstString is not aligned on a 16-bit boundary, then ASSERT().
255   If SecondString is NULL, then ASSERT().
256   If SecondString is not aligned on a 16-bit boundary, then ASSERT().
257   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
258   than PcdMaximumUnicodeStringLength Unicode characters not including the
259   Null-terminator, then ASSERT().
260   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
261   than PcdMaximumUnicodeStringLength Unicode characters not including the
262   Null-terminator, then ASSERT().
263
264   @param  FirstString   Pointer to a Null-terminated Unicode string.
265   @param  SecondString  Pointer to a Null-terminated Unicode string.
266
267   @retval 0   FirstString is identical to SecondString.
268   @retval !=0 FirstString is not identical to SecondString.
269
270 **/
271 INTN
272 EFIAPI
273 StrCmp (
274   IN      CONST CHAR16              *FirstString,
275   IN      CONST CHAR16              *SecondString
276   );
277 /**
278   Compares two Null-terminated Unicode strings with maximum lengths, and
279   returns the difference between the first mismatched Unicode characters.
280
281   This function compares the Null-terminated Unicode string FirstString to the
282   Null-terminated Unicode string SecondString. At most, Length Unicode
283   characters will be compared. If Length is 0, then 0 is returned. If
284   FirstString is identical to SecondString, then 0 is returned. Otherwise, the
285   value returned is the first mismatched Unicode character in SecondString
286   subtracted from the first mismatched Unicode character in FirstString.
287
288   If Length > 0 and FirstString is NULL, then ASSERT().
289   If Length > 0 and FirstString is not aligned on a 16-bit bounadary, then ASSERT().
290   If Length > 0 and SecondString is NULL, then ASSERT().
291   If Length > 0 and SecondString is not aligned on a 16-bit bounadary, then ASSERT().
292   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
293   than PcdMaximumUnicodeStringLength Unicode characters not including the
294   Null-terminator, then ASSERT().
295   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
296   than PcdMaximumUnicodeStringLength Unicode characters not including the
297   Null-terminator, then ASSERT().
298
299   @param  FirstString   Pointer to a Null-terminated Unicode string.
300   @param  SecondString  Pointer to a Null-terminated Unicode string.
301   @param  Length        Maximum number of Unicode characters to compare.
302
303   @retval 0   FirstString is identical to SecondString.
304   @retval !=0 FirstString is not identical to SecondString.
305
306 **/
307 INTN
308 EFIAPI
309 StrnCmp (
310   IN      CONST CHAR16              *FirstString,
311   IN      CONST CHAR16              *SecondString,
312   IN      UINTN                     Length
313   );
314 /**
315   Concatenates one Null-terminated Unicode string to another Null-terminated
316   Unicode string, and returns the concatenated Unicode string.
317
318   This function concatenates two Null-terminated Unicode strings. The contents
319   of Null-terminated Unicode string Source are concatenated to the end of
320   Null-terminated Unicode string Destination. The Null-terminated concatenated
321   Unicode String is returned. If Source and Destination overlap, then the
322   results are undefined.
323
324   If Destination is NULL, then ASSERT().
325   If Destination is not aligned on a 16-bit bounadary, then ASSERT().
326   If Source is NULL, then ASSERT().
327   If Source is not aligned on a 16-bit bounadary, then ASSERT().
328   If Source and Destination overlap, then ASSERT().
329   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
330   than PcdMaximumUnicodeStringLength Unicode characters not including the
331   Null-terminator, then ASSERT().
332   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
333   PcdMaximumUnicodeStringLength Unicode characters not including the
334   Null-terminator, then ASSERT().
335   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
336   and Source results in a Unicode string with more than
337   PcdMaximumUnicodeStringLength Unicode characters not including the
338   Null-terminator, then ASSERT().
339
340   @param  Destination Pointer to a Null-terminated Unicode string.
341   @param  Source      Pointer to a Null-terminated Unicode string.
342
343   @return Destination
344
345 **/
346 CHAR16 *
347 EFIAPI
348 StrCat (
349   IN OUT  CHAR16                    *Destination,
350   IN      CONST CHAR16              *Source
351   );
352 /**
353   Concatenates one Null-terminated Unicode string with a maximum length to the
354   end of another Null-terminated Unicode string, and returns the concatenated
355   Unicode string.
356
357   This function concatenates two Null-terminated Unicode strings. The contents
358   of Null-terminated Unicode string Source are concatenated to the end of
359   Null-terminated Unicode string Destination, and Destination is returned. At
360   most, Length Unicode characters are concatenated from Source to the end of
361   Destination, and Destination is always Null-terminated. If Length is 0, then
362   Destination is returned unmodified. If Source and Destination overlap, then
363   the results are undefined.
364
365   If Destination is NULL, then ASSERT().
366   If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
367   If Length > 0 and Source is NULL, then ASSERT().
368   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
369   If Source and Destination overlap, then ASSERT().
370   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
371   than PcdMaximumUnicodeStringLength Unicode characters not including the
372   Null-terminator, then ASSERT().
373   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
374   PcdMaximumUnicodeStringLength Unicode characters not including the
375   Null-terminator, then ASSERT().
376   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
377   and Source results in a Unicode string with more than
378   PcdMaximumUnicodeStringLength Unicode characters not including the
379   Null-terminator, then ASSERT().
380
381   @param  Destination Pointer to a Null-terminated Unicode string.
382   @param  Source      Pointer to a Null-terminated Unicode string.
383   @param  Length      Maximum number of Unicode characters to concatenate from
384                       Source.
385
386   @return Destination
387
388 **/
389 CHAR16 *
390 EFIAPI
391 StrnCat (
392   IN OUT  CHAR16                    *Destination,
393   IN      CONST CHAR16              *Source,
394   IN      UINTN                     Length
395   );
396
397 /**
398   Returns the first occurance of a Null-terminated Unicode sub-string 
399   in a Null-terminated Unicode string.
400
401   This function scans the contents of the Null-terminated Unicode string 
402   specified by String and returns the first occurrence of SearchString.  
403   If SearchString is not found in String, then NULL is returned.  If 
404   the length of SearchString is zero, then String is 
405   returned.
406   
407   If String is NULL, then ASSERT().
408   If String is not aligned on a 16-bit boundary, then ASSERT().
409   If SearchString is NULL, then ASSERT().
410   If SearchString is not aligned on a 16-bit boundary, then ASSERT().
411
412   If PcdMaximumUnicodeStringLength is not zero, and SearchString 
413   or String contains more than PcdMaximumUnicodeStringLength Unicode 
414   characters not including the Null-terminator, then ASSERT().
415
416   @param  String                                  Pointer to a Null-terminated Unicode string.
417   @param  SearchString  Pointer to a Null-terminated Unicode string to search for.
418
419   @retval NULL            If the SearchString does not appear in String.
420   @retval !NULL           If there is a match.
421
422 **/
423 CHAR16 *
424 EFIAPI
425 StrStr (
426   IN      CONST CHAR16                *String,
427   IN      CONST CHAR16                *SearchString
428   );
429
430 /**
431   Convert a Null-terminated Unicode decimal string to a value of 
432   type UINTN.
433
434   This function returns a value of type UINTN by interpreting the contents 
435   of the Unicode string specified by String as a decimal number. The format 
436   of the input Unicode string String is:
437   
438                   [spaces] [decimal digits].
439                   
440   The valid decimal digit character is in the range [0-9]. The 
441   function will ignore the pad space, which includes spaces or 
442   tab characters, before [decimal digits]. The running zero in the 
443   beginning of [decimal digits] will be ignored. Then, the function 
444   stops at the first character that is a not a valid decimal character 
445   or a Null-terminator, whichever one comes first. 
446   
447   If String is NULL, then ASSERT().
448   If String is not aligned in a 16-bit boundary, then ASSERT().  
449   If String has only pad spaces, then 0 is returned.
450   If String has no pad spaces or valid decimal digits, 
451   then 0 is returned.
452   If the number represented by String overflows according 
453   to the range defined by UINTN, then ASSERT().
454   
455   If PcdMaximumUnicodeStringLength is not zero, and String contains 
456   more than PcdMaximumUnicodeStringLength Unicode characters not including 
457   the Null-terminator, then ASSERT().
458
459   @param  String                            Pointer to a Null-terminated Unicode string.
460
461   @retval UINTN           
462
463 **/
464 UINTN
465 EFIAPI
466 StrDecimalToUintn (
467   IN      CONST CHAR16                *String
468   );
469
470 /**
471   Convert a Null-terminated Unicode decimal string to a value of 
472   type UINT64.
473
474   This function returns a value of type UINT64 by interpreting the contents 
475   of the Unicode string specified by String as a decimal number. The format 
476   of the input Unicode string String is:
477   
478                   [spaces] [decimal digits].
479                   
480   The valid decimal digit character is in the range [0-9]. The 
481   function will ignore the pad space, which includes spaces or 
482   tab characters, before [decimal digits]. The running zero in the 
483   beginning of [decimal digits] will be ignored. Then, the function 
484   stops at the first character that is a not a valid decimal character 
485   or a Null-terminator, whichever one comes first. 
486   
487   If String is NULL, then ASSERT().
488   If String is not aligned in a 16-bit boundary, then ASSERT().  
489   If String has only pad spaces, then 0 is returned.
490   If String has no pad spaces or valid decimal digits, 
491   then 0 is returned.
492   If the number represented by String overflows according 
493   to the range defined by UINT64, then ASSERT().
494   
495   If PcdMaximumUnicodeStringLength is not zero, and String contains 
496   more than PcdMaximumUnicodeStringLength Unicode characters not including 
497   the Null-terminator, then ASSERT().
498
499   @param  String                            Pointer to a Null-terminated Unicode string.
500
501   @retval UINT64           
502
503 **/
504 UINT64
505 EFIAPI
506 StrDecimalToUint64 (
507   IN      CONST CHAR16                *String
508   );
509
510 /**
511   Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
512
513   This function returns a value of type UINTN by interpreting the contents 
514   of the Unicode string specified by String as a hexadecimal number. 
515   The format of the input Unicode string String is:
516   
517                   [spaces][zeros][x][hexadecimal digits]. 
518
519   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 
520   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. 
521   If "x" appears in the input string, it must be prefixed with at least one 0. 
522   The function will ignore the pad space, which includes spaces or tab characters, 
523   before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or 
524   [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the 
525   first valid hexadecimal digit. Then, the function stops at the first character that is 
526   a not a valid hexadecimal character or NULL, whichever one comes first.
527
528   If String is NULL, then ASSERT().
529   If String is not aligned in a 16-bit boundary, then ASSERT().
530   If String has only pad spaces, then zero is returned.
531   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, 
532   then zero is returned.
533   If the number represented by String overflows according to the range defined by 
534   UINTN, then ASSERT().
535
536   If PcdMaximumUnicodeStringLength is not zero, and String contains more than 
537   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, 
538   then ASSERT().
539
540   @param  String                            Pointer to a Null-terminated Unicode string.
541
542   @retval UINTN
543
544 **/
545 UINTN
546 EFIAPI
547 StrHexToUintn (
548   IN      CONST CHAR16                *String
549   );
550
551 /**
552   Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
553
554   This function returns a value of type UINT64 by interpreting the contents 
555   of the Unicode string specified by String as a hexadecimal number. 
556   The format of the input Unicode string String is 
557   
558                   [spaces][zeros][x][hexadecimal digits]. 
559
560   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 
561   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. 
562   If "x" appears in the input string, it must be prefixed with at least one 0. 
563   The function will ignore the pad space, which includes spaces or tab characters, 
564   before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or 
565   [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the 
566   first valid hexadecimal digit. Then, the function stops at the first character that is 
567   a not a valid hexadecimal character or NULL, whichever one comes first.
568
569   If String is NULL, then ASSERT().
570   If String is not aligned in a 16-bit boundary, then ASSERT().
571   If String has only pad spaces, then zero is returned.
572   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, 
573   then zero is returned.
574   If the number represented by String overflows according to the range defined by 
575   UINT64, then ASSERT().
576
577   If PcdMaximumUnicodeStringLength is not zero, and String contains more than 
578   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, 
579   then ASSERT().
580
581   @param  String                            Pointer to a Null-terminated Unicode string.
582
583   @retval UINT64
584
585 **/
586 UINT64
587 EFIAPI
588 StrHexToUint64 (
589   IN      CONST CHAR16                *String
590   );
591
592 /**
593   Convert one Null-terminated Unicode string to a Null-terminated 
594   ASCII string and returns the ASCII string.
595   
596   This function converts the content of the Unicode string Source 
597   to the ASCII string Destination by copying the lower 8 bits of 
598   each Unicode character. It returns Destination. 
599
600   If any Unicode characters in Source contain non-zero value in 
601   the upper 8 bits, then ASSERT().
602   
603   If Destination is NULL, then ASSERT().
604   If Source is NULL, then ASSERT().
605   If Source is not aligned on a 16-bit boundary, then ASSERT().
606   If Source and Destination overlap, then ASSERT().
607   
608   If PcdMaximumUnicodeStringLength is not zero, and Source contains 
609   more than PcdMaximumUnicodeStringLength Unicode characters not including 
610   the Null-terminator, then ASSERT().
611   
612   If PcdMaximumAsciiStringLength is not zero, and Source contains more 
613   than PcdMaximumAsciiStringLength Unicode characters not including the 
614   Null-terminator, then ASSERT().
615
616   @param  Source        Pointer to a Null-terminated Unicode string.
617   @param  Destination   Pointer to a Null-terminated ASCII string.
618
619   @reture Destination
620
621 **/
622 CHAR8 *
623 EFIAPI
624 UnicodeStrToAsciiStr (
625   IN      CONST CHAR16                *Source,
626   OUT     CHAR8                           *Destination
627   );
628
629 /**
630   Copies one Null-terminated ASCII string to another Null-terminated ASCII
631   string and returns the new ASCII string.
632
633   This function copies the contents of the ASCII string Source to the ASCII
634   string Destination, and returns Destination. If Source and Destination
635   overlap, then the results are undefined.
636
637   If Destination is NULL, then ASSERT().
638   If Source is NULL, then ASSERT().
639   If Source and Destination overlap, then ASSERT().
640   If PcdMaximumAsciiStringLength is not zero and Source contains more than
641   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
642   then ASSERT().
643
644   @param  Destination Pointer to a Null-terminated ASCII string.
645   @param  Source      Pointer to a Null-terminated ASCII string.
646
647   @return Destination
648
649 **/
650 CHAR8 *
651 EFIAPI
652 AsciiStrCpy (
653   OUT     CHAR8                     *Destination,
654   IN      CONST CHAR8               *Source
655   );
656 /**
657   Copies one Null-terminated ASCII string with a maximum length to another
658   Null-terminated ASCII string with a maximum length and returns the new ASCII
659   string.
660
661   This function copies the contents of the ASCII string Source to the ASCII
662   string Destination, and returns Destination. At most, Length ASCII characters
663   are copied from Source to Destination. If Length is 0, then Destination is
664   returned unmodified. If Length is greater that the number of ASCII characters
665   in Source, then Destination is padded with Null ASCII characters. If Source
666   and Destination overlap, then the results are undefined.
667
668   If Destination is NULL, then ASSERT().
669   If Source is NULL, then ASSERT().
670   If Source and Destination overlap, then ASSERT().
671   If PcdMaximumAsciiStringLength is not zero, and Source contains more than
672   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
673   then ASSERT().
674
675   @param  Destination Pointer to a Null-terminated ASCII string.
676   @param  Source      Pointer to a Null-terminated ASCII string.
677   @param  Length      Maximum number of ASCII characters to copy.
678
679   @return Destination
680
681 **/
682 CHAR8 *
683 EFIAPI
684 AsciiStrnCpy (
685   OUT     CHAR8                     *Destination,
686   IN      CONST CHAR8               *Source,
687   IN      UINTN                     Length
688   );
689 /**
690   Returns the length of a Null-terminated ASCII string.
691
692   This function returns the number of ASCII characters in the Null-terminated
693   ASCII string specified by String.
694
695   If Length > 0 and Destination is NULL, then ASSERT().
696   If Length > 0 and Source is NULL, then ASSERT().
697   If PcdMaximumAsciiStringLength is not zero and String contains more than
698   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
699   then ASSERT().
700
701   @param  String  Pointer to a Null-terminated ASCII string.
702
703   @return The length of String.
704
705 **/
706 UINTN
707 EFIAPI
708 AsciiStrLen (
709   IN      CONST CHAR8               *String
710   );
711 /**
712   Returns the size of a Null-terminated ASCII string in bytes, including the
713   Null terminator.
714
715   This function returns the size, in bytes, of the Null-terminated ASCII string
716   specified by String.
717
718   If String is NULL, then ASSERT().
719   If PcdMaximumAsciiStringLength is not zero and String contains more than
720   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
721   then ASSERT().
722
723   @param  String  Pointer to a Null-terminated ASCII string.
724
725   @return The size of String.
726
727 **/
728 UINTN
729 EFIAPI
730 AsciiStrSize (
731   IN      CONST CHAR8               *String
732   );
733 /**
734   Compares two Null-terminated ASCII strings, and returns the difference
735   between the first mismatched ASCII characters.
736
737   This function compares the Null-terminated ASCII string FirstString to the
738   Null-terminated ASCII string SecondString. If FirstString is identical to
739   SecondString, then 0 is returned. Otherwise, the value returned is the first
740   mismatched ASCII character in SecondString subtracted from the first
741   mismatched ASCII character in FirstString.
742
743   If FirstString is NULL, then ASSERT().
744   If SecondString is NULL, then ASSERT().
745   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
746   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
747   then ASSERT().
748   If PcdMaximumAsciiStringLength is not zero and SecondString contains more
749   than PcdMaximumAsciiStringLength ASCII characters not including the
750   Null-terminator, then ASSERT().
751
752   @param  FirstString   Pointer to a Null-terminated ASCII string.
753   @param  SecondString  Pointer to a Null-terminated ASCII string.
754
755   @retval 0   FirstString is identical to SecondString.
756   @retval !=0 FirstString is not identical to SecondString.
757
758 **/
759 INTN
760 EFIAPI
761 AsciiStrCmp (
762   IN      CONST CHAR8               *FirstString,
763   IN      CONST CHAR8               *SecondString
764   );
765 /**
766   Performs a case insensitive comparison of two Null-terminated ASCII strings,
767   and returns the difference between the first mismatched ASCII characters.
768
769   This function performs a case insensitive comparison of the Null-terminated
770   ASCII string FirstString to the Null-terminated ASCII string SecondString. If
771   FirstString is identical to SecondString, then 0 is returned. Otherwise, the
772   value returned is the first mismatched lower case ASCII character in
773   SecondString subtracted from the first mismatched lower case ASCII character
774   in FirstString.
775
776   If FirstString is NULL, then ASSERT().
777   If SecondString is NULL, then ASSERT().
778   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
779   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
780   then ASSERT().
781   If PcdMaximumAsciiStringLength is not zero and SecondString contains more
782   than PcdMaximumAsciiStringLength ASCII characters not including the
783   Null-terminator, then ASSERT().
784
785   @param  FirstString   Pointer to a Null-terminated ASCII string.
786   @param  SecondString  Pointer to a Null-terminated ASCII string.
787
788   @retval 0   FirstString is identical to SecondString using case insensitive
789               comparisons.
790   @retval !=0 FirstString is not identical to SecondString using case
791               insensitive comparisons.
792
793 **/
794 INTN
795 EFIAPI
796 AsciiStriCmp (
797   IN      CONST CHAR8               *FirstString,
798   IN      CONST CHAR8               *SecondString
799   );
800 /**
801   Compares two Null-terminated ASCII strings with maximum lengths, and returns
802   the difference between the first mismatched ASCII characters.
803
804   This function compares the Null-terminated ASCII string FirstString to the
805   Null-terminated ASCII  string SecondString. At most, Length ASCII characters
806   will be compared. If Length is 0, then 0 is returned. If FirstString is
807   identical to SecondString, then 0 is returned. Otherwise, the value returned
808   is the first mismatched ASCII character in SecondString subtracted from the
809   first mismatched ASCII character in FirstString.
810
811   If Length > 0 and FirstString is NULL, then ASSERT().
812   If Length > 0 and SecondString is NULL, then ASSERT().
813   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
814   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
815   then ASSERT().
816   If PcdMaximumAsciiStringLength is not zero and SecondString contains more than
817   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
818   then ASSERT().
819
820   @param  FirstString   Pointer to a Null-terminated ASCII string.
821   @param  SecondString  Pointer to a Null-terminated ASCII string.
822
823   @retval 0   FirstString is identical to SecondString.
824   @retval !=0 FirstString is not identical to SecondString.
825
826 **/
827 INTN
828 EFIAPI
829 AsciiStrnCmp (
830   IN      CONST CHAR8               *FirstString,
831   IN      CONST CHAR8               *SecondString,
832   IN      UINTN                     Length
833   );
834 /**
835   Concatenates one Null-terminated ASCII string to another Null-terminated
836   ASCII string, and returns the concatenated ASCII string.
837
838   This function concatenates two Null-terminated ASCII strings. The contents of
839   Null-terminated ASCII string Source are concatenated to the end of Null-
840   terminated ASCII string Destination. The Null-terminated concatenated ASCII
841   String is returned.
842
843   If Destination is NULL, then ASSERT().
844   If Source is NULL, then ASSERT().
845   If PcdMaximumAsciiStringLength is not zero and Destination contains more than
846   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
847   then ASSERT().
848   If PcdMaximumAsciiStringLength is not zero and Source contains more than
849   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
850   then ASSERT().
851   If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
852   Source results in a ASCII string with more than PcdMaximumAsciiStringLength
853   ASCII characters, then ASSERT().
854
855   @param  Destination Pointer to a Null-terminated ASCII string.
856   @param  Source      Pointer to a Null-terminated ASCII string.
857
858   @return Destination
859
860 **/
861 CHAR8 *
862 EFIAPI
863 AsciiStrCat (
864   IN OUT CHAR8    *Destination,
865   IN CONST CHAR8  *Source
866   );
867 /**
868   Concatenates one Null-terminated ASCII string with a maximum length to the
869   end of another Null-terminated ASCII string, and returns the concatenated
870   ASCII string.
871
872   This function concatenates two Null-terminated ASCII strings. The contents
873   of Null-terminated ASCII string Source are concatenated to the end of Null-
874   terminated ASCII string Destination, and Destination is returned. At most,
875   Length ASCII characters are concatenated from Source to the end of
876   Destination, and Destination is always Null-terminated. If Length is 0, then
877   Destination is returned unmodified. If Source and Destination overlap, then
878   the results are undefined.
879
880   If Length > 0 and Destination is NULL, then ASSERT().
881   If Length > 0 and Source is NULL, then ASSERT().
882   If Source and Destination overlap, then ASSERT().
883   If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
884   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
885   then ASSERT().
886   If PcdMaximumAsciiStringLength is not zero, and Source contains more than
887   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
888   then ASSERT().
889   If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
890   Source results in a ASCII string with more than PcdMaximumAsciiStringLength
891   ASCII characters not including the Null-terminator, then ASSERT().
892
893   @param  Destination Pointer to a Null-terminated ASCII string.
894   @param  Source      Pointer to a Null-terminated ASCII string.
895   @param  Length      Maximum number of ASCII characters to concatenate from
896                       Source.
897
898   @return Destination
899
900 **/
901 CHAR8 *
902 EFIAPI
903 AsciiStrnCat (
904   IN OUT  CHAR8                     *Destination,
905   IN      CONST CHAR8               *Source,
906   IN      UINTN                     Length
907   );
908
909 /**
910   Returns the first occurance of a Null-terminated ASCII sub-string 
911   in a Null-terminated ASCII string.
912
913   This function scans the contents of the ASCII string specified by String 
914   and returns the first occurrence of SearchString. If SearchString is not 
915   found in String, then NULL is returned. If the length of SearchString is zero, 
916   then String is returned.
917   
918   If String is NULL, then ASSERT().
919   If SearchString is NULL, then ASSERT().
920
921   If PcdMaximumAsciiStringLength is not zero, and SearchString or 
922   String contains more than PcdMaximumAsciiStringLength Unicode characters 
923   not including the Null-terminator, then ASSERT().
924
925   @param  String                                  Pointer to a Null-terminated ASCII string.
926   @param  SearchString    Pointer to a Null-terminated ASCII string to search for.
927
928   @retval NULL            If the SearchString does not appear in String.
929   @retval !NULL           If there is a match.
930
931 **/
932 CHAR8 *
933 EFIAPI
934 AsciiStrStr (
935   IN      CONST CHAR8                   *String,
936   IN      CONST CHAR8                   *SearchString
937   );
938
939 /**
940   Convert a Null-terminated ASCII decimal string to a value of type 
941   UINTN.
942
943   This function returns a value of type UINTN by interpreting the contents 
944   of the ASCII string String as a decimal number. The format of the input 
945   ASCII string String is:
946   
947                     [spaces] [decimal digits].
948   
949   The valid decimal digit character is in the range [0-9]. The function will 
950   ignore the pad space, which includes spaces or tab characters, before the digits. 
951   The running zero in the beginning of [decimal digits] will be ignored. Then, the 
952   function stops at the first character that is a not a valid decimal character or 
953   Null-terminator, whichever on comes first.
954   
955   If String has only pad spaces, then 0 is returned.
956   If String has no pad spaces or valid decimal digits, then 0 is returned.
957   If the number represented by String overflows according to the range defined by 
958   UINTN, then ASSERT().
959   If String is NULL, then ASSERT().
960   If PcdMaximumAsciiStringLength is not zero, and String contains more than 
961   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 
962   then ASSERT().
963
964   @param  String                            Pointer to a Null-terminated ASCII string.
965
966   @retval UINTN           
967
968 **/
969 UINTN
970 EFIAPI
971 AsciiStrDecimalToUintn (
972   IN      CONST CHAR8               *String
973   );
974
975 /**
976   Convert a Null-terminated ASCII decimal string to a value of type 
977   UINT64.
978
979   This function returns a value of type UINT64 by interpreting the contents 
980   of the ASCII string String as a decimal number. The format of the input 
981   ASCII string String is:
982   
983                     [spaces] [decimal digits].
984   
985   The valid decimal digit character is in the range [0-9]. The function will 
986   ignore the pad space, which includes spaces or tab characters, before the digits. 
987   The running zero in the beginning of [decimal digits] will be ignored. Then, the 
988   function stops at the first character that is a not a valid decimal character or 
989   Null-terminator, whichever on comes first.
990   
991   If String has only pad spaces, then 0 is returned.
992   If String has no pad spaces or valid decimal digits, then 0 is returned.
993   If the number represented by String overflows according to the range defined by 
994   UINT64, then ASSERT().
995   If String is NULL, then ASSERT().
996   If PcdMaximumAsciiStringLength is not zero, and String contains more than 
997   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 
998   then ASSERT().
999
1000   @param  String                            Pointer to a Null-terminated ASCII string.
1001
1002   @retval UINT64           
1003
1004 **/
1005 UINT64
1006 EFIAPI
1007 AsciiStrDecimalToUint64 (
1008   IN      CONST CHAR8                 *String
1009   );
1010
1011 /**
1012   Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1013
1014   This function returns a value of type UINTN by interpreting the contents of 
1015   the ASCII string String as a hexadecimal number. The format of the input ASCII 
1016   string String is:
1017   
1018                   [spaces][zeros][x][hexadecimal digits].
1019                   
1020   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 
1021   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" 
1022   appears in the input string, it must be prefixed with at least one 0. The function 
1023   will ignore the pad space, which includes spaces or tab characters, before [zeros], 
1024   [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits] 
1025   will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal 
1026   digit. Then, the function stops at the first character that is a not a valid 
1027   hexadecimal character or Null-terminator, whichever on comes first.
1028   
1029   If String has only pad spaces, then 0 is returned.
1030   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1031   0 is returned.
1032
1033   If the number represented by String overflows according to the range defined by UINTN, 
1034   then ASSERT().
1035   If String is NULL, then ASSERT().
1036   If PcdMaximumAsciiStringLength is not zero, 
1037   and String contains more than PcdMaximumAsciiStringLength ASCII characters not including 
1038   the Null-terminator, then ASSERT().
1039
1040   @param  String                            Pointer to a Null-terminated ASCII string.
1041
1042   @retval UINTN
1043
1044 **/
1045 UINTN
1046 EFIAPI
1047 AsciiStrHexToUintn (
1048   IN      CONST CHAR8                 *String
1049   );
1050
1051 /**
1052   Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1053
1054   This function returns a value of type UINT64 by interpreting the contents of 
1055   the ASCII string String as a hexadecimal number. The format of the input ASCII 
1056   string String is:
1057   
1058                   [spaces][zeros][x][hexadecimal digits].
1059                   
1060   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 
1061   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" 
1062   appears in the input string, it must be prefixed with at least one 0. The function 
1063   will ignore the pad space, which includes spaces or tab characters, before [zeros], 
1064   [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits] 
1065   will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal 
1066   digit. Then, the function stops at the first character that is a not a valid 
1067   hexadecimal character or Null-terminator, whichever on comes first.
1068   
1069   If String has only pad spaces, then 0 is returned.
1070   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1071   0 is returned.
1072
1073   If the number represented by String overflows according to the range defined by UINT64, 
1074   then ASSERT().
1075   If String is NULL, then ASSERT().
1076   If PcdMaximumAsciiStringLength is not zero, 
1077   and String contains more than PcdMaximumAsciiStringLength ASCII characters not including 
1078   the Null-terminator, then ASSERT().
1079
1080   @param  String                            Pointer to a Null-terminated ASCII string.
1081
1082   @retval UINT64
1083
1084 **/
1085 UINT64
1086 EFIAPI
1087 AsciiStrHexToUint64 (
1088   IN      CONST CHAR8                   *String
1089   );
1090
1091 /**
1092   Convert one Null-terminated ASCII string to a Null-terminated 
1093   Unicode string and returns the Unicode string.
1094
1095   This function converts the contents of the ASCII string Source to the Unicode 
1096   string Destination, and returns Destination.  The function terminates the 
1097   Unicode string Destination by appending a Null-terminator character at the end. 
1098   The caller is responsible to make sure Destination points to a buffer with size 
1099   equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
1100   
1101   If Destination is NULL, then ASSERT().
1102   If Destination is not aligned on a 16-bit boundary, then ASSERT().
1103   If Source is NULL, then ASSERT().
1104   If Source and Destination overlap, then ASSERT().
1105   If PcdMaximumAsciiStringLength is not zero, and Source contains more than 
1106   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 
1107   then ASSERT().
1108   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than 
1109   PcdMaximumUnicodeStringLength ASCII characters not including the 
1110   Null-terminator, then ASSERT().
1111
1112   @param  Source        Pointer to a Null-terminated ASCII string.
1113   @param  Destination   Pointer to a Null-terminated Unicode string.
1114
1115   @reture Destination
1116
1117 **/
1118 CHAR16 *
1119 EFIAPI
1120 AsciiStrToUnicodeStr (
1121   IN      CONST CHAR8                 *Source,
1122   OUT     CHAR16                        *Destination
1123   );
1124
1125 /**
1126   Converts an 8-bit value to an 8-bit BCD value.
1127
1128   Converts the 8-bit value specified by Value to BCD. The BCD value is
1129   returned.
1130
1131   If Value >= 100, then ASSERT().
1132
1133   @param  Value The 8-bit value to convert to BCD. Range 0..99.
1134
1135   @return The BCD value
1136
1137 **/
1138 UINT8
1139 EFIAPI
1140 DecimalToBcd8 (
1141   IN      UINT8                     Value
1142   );
1143
1144 /**
1145   Converts an 8-bit BCD value to an 8-bit value.
1146
1147   Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
1148   value is returned.
1149
1150   If Value >= 0xA0, then ASSERT().
1151   If (Value & 0x0F) >= 0x0A, then ASSERT().
1152
1153   @param  Value The 8-bit BCD value to convert to an 8-bit value.
1154
1155   @return The 8-bit value is returned.
1156
1157 **/
1158 UINT8
1159 EFIAPI
1160 BcdToDecimal8 (
1161   IN      UINT8                     Value
1162   );
1163
1164
1165 //
1166 // Linked List Functions and Macros
1167 //
1168
1169 /**
1170   Initializes the head node of a doubly linked list that is declared as a
1171   global variable in a module.
1172
1173   Initializes the forward and backward links of a new linked list. After
1174   initializing a linked list with this macro, the other linked list functions
1175   may be used to add and remove nodes from the linked list. This macro results
1176   in smaller executables by initializing the linked list in the data section,
1177   instead if calling the InitializeListHead() function to perform the
1178   equivalent operation.
1179
1180   @param  ListHead  The head note of a list to initiailize.
1181
1182 **/
1183 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead)  {&ListHead, &ListHead}
1184
1185 /**
1186   Initializes the head node of a doubly linked list, and returns the pointer to
1187   the head node of the doubly linked list.
1188
1189   Initializes the forward and backward links of a new linked list. After
1190   initializing a linked list with this function, the other linked list
1191   functions may be used to add and remove nodes from the linked list. It is up
1192   to the caller of this function to allocate the memory for ListHead.
1193
1194   If ListHead is NULL, then ASSERT().
1195
1196   @param  ListHead  A pointer to the head node of a new doubly linked list.
1197
1198   @return ListHead
1199
1200 **/
1201 LIST_ENTRY *
1202 EFIAPI
1203 InitializeListHead (
1204   IN      LIST_ENTRY                *ListHead
1205   );
1206
1207 /**
1208   Adds a node to the beginning of a doubly linked list, and returns the pointer
1209   to the head node of the doubly linked list.
1210
1211   Adds the node Entry at the beginning of the doubly linked list denoted by
1212   ListHead, and returns ListHead.
1213
1214   If ListHead is NULL, then ASSERT().
1215   If Entry is NULL, then ASSERT().
1216   If ListHead was not initialized with InitializeListHead(), then ASSERT().
1217   If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
1218   of nodes in ListHead, including the ListHead node, is greater than or
1219   equal to PcdMaximumLinkedListLength, then ASSERT().
1220
1221   @param  ListHead  A pointer to the head node of a doubly linked list.
1222   @param  Entry     A pointer to a node that is to be inserted at the beginning
1223                     of a doubly linked list.
1224
1225   @return ListHead
1226
1227 **/
1228 LIST_ENTRY *
1229 EFIAPI
1230 InsertHeadList (
1231   IN      LIST_ENTRY                *ListHead,
1232   IN      LIST_ENTRY                *Entry
1233   );
1234
1235 /**
1236   Adds a node to the end of a doubly linked list, and returns the pointer to
1237   the head node of the doubly linked list.
1238
1239   Adds the node Entry to the end of the doubly linked list denoted by ListHead,
1240   and returns ListHead.
1241
1242   If ListHead is NULL, then ASSERT().
1243   If Entry is NULL, then ASSERT().
1244   If ListHead was not initialized with InitializeListHead(), then ASSERT().
1245   If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
1246   of nodes in ListHead, including the ListHead node, is greater than or
1247   equal to PcdMaximumLinkedListLength, then ASSERT().
1248
1249   @param  ListHead  A pointer to the head node of a doubly linked list.
1250   @param  Entry     A pointer to a node that is to be added at the end of the
1251                     doubly linked list.
1252
1253   @return ListHead
1254
1255 **/
1256 LIST_ENTRY *
1257 EFIAPI
1258 InsertTailList (
1259   IN      LIST_ENTRY                *ListHead,
1260   IN      LIST_ENTRY                *Entry
1261   );
1262
1263 /**
1264   Retrieves the first node of a doubly linked list.
1265
1266   Returns the first node of a doubly linked list. List must have been
1267   initialized with InitializeListHead(). If List is empty, then NULL is
1268   returned.
1269
1270   If List is NULL, then ASSERT().
1271   If List was not initialized with InitializeListHead(), then ASSERT().
1272   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
1273   in List, including the List node, is greater than or equal to
1274   PcdMaximumLinkedListLength, then ASSERT().
1275
1276   @param  List  A pointer to the head node of a doubly linked list.
1277
1278   @return The first node of a doubly linked list.
1279   @retval NULL  The list is empty.
1280
1281 **/
1282 LIST_ENTRY *
1283 EFIAPI
1284 GetFirstNode (
1285   IN      CONST LIST_ENTRY          *List
1286   );
1287
1288 /**
1289   Retrieves the next node of a doubly linked list.
1290
1291   Returns the node of a doubly linked list that follows Node. List must have
1292   been initialized with InitializeListHead(). If List is empty, then List is
1293   returned.
1294
1295   If List is NULL, then ASSERT().
1296   If Node is NULL, then ASSERT().
1297   If List was not initialized with InitializeListHead(), then ASSERT().
1298   If PcdMaximumLinkedListLenth is not zero, and List contains more than
1299   PcdMaximumLinkedListLenth nodes, then ASSERT().
1300   If Node is not a node in List, then ASSERT().
1301
1302   @param  List  A pointer to the head node of a doubly linked list.
1303   @param  Node  A pointer to a node in the doubly linked list.
1304
1305   @return Pointer to the next node if one exists. Otherwise a null value which
1306           is actually List is returned.
1307
1308 **/
1309 LIST_ENTRY *
1310 EFIAPI
1311 GetNextNode (
1312   IN      CONST LIST_ENTRY          *List,
1313   IN      CONST LIST_ENTRY          *Node
1314   );
1315
1316 /**
1317   Checks to see if a doubly linked list is empty or not.
1318
1319   Checks to see if the doubly linked list is empty. If the linked list contains
1320   zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
1321
1322   If ListHead is NULL, then ASSERT().
1323   If ListHead was not initialized with InitializeListHead(), then ASSERT().
1324   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
1325   in List, including the List node, is greater than or equal to
1326   PcdMaximumLinkedListLength, then ASSERT().
1327
1328   @param  ListHead  A pointer to the head node of a doubly linked list.
1329
1330   @retval TRUE  The linked list is empty.
1331   @retval FALSE The linked list is not empty.
1332
1333 **/
1334 BOOLEAN
1335 EFIAPI
1336 IsListEmpty (
1337   IN      CONST LIST_ENTRY          *ListHead
1338   );
1339
1340 /**
1341   Determines if a node in a doubly linked list is null.
1342
1343   Returns FALSE if Node is one of the nodes in the doubly linked list specified
1344   by List. Otherwise, TRUE is returned. List must have been initialized with
1345   InitializeListHead().
1346
1347   If List is NULL, then ASSERT().
1348   If Node is NULL, then ASSERT().
1349   If List was not initialized with InitializeListHead(), then ASSERT().
1350   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
1351   in List, including the List node, is greater than or equal to
1352   PcdMaximumLinkedListLength, then ASSERT().
1353   If Node is not a node in List and Node is not equal to List, then ASSERT().
1354
1355   @param  List  A pointer to the head node of a doubly linked list.
1356   @param  Node  A pointer to a node in the doubly linked list.
1357
1358   @retval TRUE  Node is one of the nodes in the doubly linked list.
1359   @retval FALSE Node is not one of the nodes in the doubly linked list.
1360
1361 **/
1362 BOOLEAN
1363 EFIAPI
1364 IsNull (
1365   IN      CONST LIST_ENTRY          *List,
1366   IN      CONST LIST_ENTRY          *Node
1367   );
1368
1369 /**
1370   Determines if a node the last node in a doubly linked list.
1371
1372   Returns TRUE if Node is the last node in the doubly linked list specified by
1373   List. Otherwise, FALSE is returned. List must have been initialized with
1374   InitializeListHead().
1375
1376   If List is NULL, then ASSERT().
1377   If Node is NULL, then ASSERT().
1378   If List was not initialized with InitializeListHead(), then ASSERT().
1379   If PcdMaximumLinkedListLenth is not zero, and the number of nodes
1380   in List, including the List node, is greater than or equal to
1381   PcdMaximumLinkedListLength, then ASSERT().
1382   If Node is not a node in List, then ASSERT().
1383
1384   @param  List  A pointer to the head node of a doubly linked list.
1385   @param  Node  A pointer to a node in the doubly linked list.
1386
1387   @retval TRUE  Node is the last node in the linked list.
1388   @retval FALSE Node is not the last node in the linked list.
1389
1390 **/
1391 BOOLEAN
1392 EFIAPI
1393 IsNodeAtEnd (
1394   IN      CONST LIST_ENTRY          *List,
1395   IN      CONST LIST_ENTRY          *Node
1396   );
1397
1398 /**
1399   Swaps the location of two nodes in a doubly linked list, and returns the
1400   first node after the swap.
1401
1402   If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
1403   Otherwise, the location of the FirstEntry node is swapped with the location
1404   of the SecondEntry node in a doubly linked list. SecondEntry must be in the
1405   same double linked list as FirstEntry and that double linked list must have
1406   been initialized with InitializeListHead(). SecondEntry is returned after the
1407   nodes are swapped.
1408
1409   If FirstEntry is NULL, then ASSERT().
1410   If SecondEntry is NULL, then ASSERT().
1411   If SecondEntry and FirstEntry are not in the same linked list, then ASSERT().
1412   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
1413   linked list containing the FirstEntry and SecondEntry nodes, including
1414   the FirstEntry and SecondEntry nodes, is greater than or equal to
1415   PcdMaximumLinkedListLength, then ASSERT().
1416
1417   @param  FirstEntry  A pointer to a node in a linked list.
1418   @param  SecondEntry A pointer to another node in the same linked list.
1419
1420 **/
1421 LIST_ENTRY *
1422 EFIAPI
1423 SwapListEntries (
1424   IN      LIST_ENTRY                *FirstEntry,
1425   IN      LIST_ENTRY                *SecondEntry
1426   );
1427
1428 /**
1429   Removes a node from a doubly linked list, and returns the node that follows
1430   the removed node.
1431
1432   Removes the node Entry from a doubly linked list. It is up to the caller of
1433   this function to release the memory used by this node if that is required. On
1434   exit, the node following Entry in the doubly linked list is returned. If
1435   Entry is the only node in the linked list, then the head node of the linked
1436   list is returned.
1437
1438   If Entry is NULL, then ASSERT().
1439   If Entry is the head node of an empty list, then ASSERT().
1440   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
1441   linked list containing Entry, including the Entry node, is greater than
1442   or equal to PcdMaximumLinkedListLength, then ASSERT().
1443
1444   @param  Entry A pointer to a node in a linked list
1445
1446   @return Entry
1447
1448 **/
1449 LIST_ENTRY *
1450 EFIAPI
1451 RemoveEntryList (
1452   IN      CONST LIST_ENTRY          *Entry
1453   );
1454
1455 //
1456 // Math Services
1457 //
1458
1459 /**
1460   Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
1461   with zeros. The shifted value is returned.
1462
1463   This function shifts the 64-bit value Operand to the left by Count bits. The
1464   low Count bits are set to zero. The shifted value is returned.
1465
1466   If Count is greater than 63, then ASSERT().
1467
1468   @param  Operand The 64-bit operand to shift left.
1469   @param  Count   The number of bits to shift left.
1470
1471   @return Operand << Count
1472
1473 **/
1474 UINT64
1475 EFIAPI
1476 LShiftU64 (
1477   IN      UINT64                    Operand,
1478   IN      UINTN                     Count
1479   );
1480
1481 /**
1482   Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
1483   filled with zeros. The shifted value is returned.
1484
1485   This function shifts the 64-bit value Operand to the right by Count bits. The
1486   high Count bits are set to zero. The shifted value is returned.
1487
1488   If Count is greater than 63, then ASSERT().
1489
1490   @param  Operand The 64-bit operand to shift right.
1491   @param  Count   The number of bits to shift right.
1492
1493   @return Operand >> Count
1494
1495 **/
1496 UINT64
1497 EFIAPI
1498 RShiftU64 (
1499   IN      UINT64                    Operand,
1500   IN      UINTN                     Count
1501   );
1502
1503 /**
1504   Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
1505   with original integer's bit 63. The shifted value is returned.
1506
1507   This function shifts the 64-bit value Operand to the right by Count bits. The
1508   high Count bits are set to bit 63 of Operand.  The shifted value is returned.
1509
1510   If Count is greater than 63, then ASSERT().
1511
1512   @param  Operand The 64-bit operand to shift right.
1513   @param  Count   The number of bits to shift right.
1514
1515   @return Operand >> Count
1516
1517 **/
1518 UINT64
1519 EFIAPI
1520 ARShiftU64 (
1521   IN      UINT64                    Operand,
1522   IN      UINTN                     Count
1523   );
1524
1525 /**
1526   Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
1527   with the high bits that were rotated.
1528
1529   This function rotates the 32-bit value Operand to the left by Count bits. The
1530   low Count bits are fill with the high Count bits of Operand. The rotated
1531   value is returned.
1532
1533   If Count is greater than 31, then ASSERT().
1534
1535   @param  Operand The 32-bit operand to rotate left.
1536   @param  Count   The number of bits to rotate left.
1537
1538   @return Operand <<< Count
1539
1540 **/
1541 UINT32
1542 EFIAPI
1543 LRotU32 (
1544   IN      UINT32                    Operand,
1545   IN      UINTN                     Count
1546   );
1547
1548 /**
1549   Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
1550   with the low bits that were rotated.
1551
1552   This function rotates the 32-bit value Operand to the right by Count bits.
1553   The high Count bits are fill with the low Count bits of Operand. The rotated
1554   value is returned.
1555
1556   If Count is greater than 31, then ASSERT().
1557
1558   @param  Operand The 32-bit operand to rotate right.
1559   @param  Count   The number of bits to rotate right.
1560
1561   @return Operand >>> Count
1562
1563 **/
1564 UINT32
1565 EFIAPI
1566 RRotU32 (
1567   IN      UINT32                    Operand,
1568   IN      UINTN                     Count
1569   );
1570
1571 /**
1572   Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
1573   with the high bits that were rotated.
1574
1575   This function rotates the 64-bit value Operand to the left by Count bits. The
1576   low Count bits are fill with the high Count bits of Operand. The rotated
1577   value is returned.
1578
1579   If Count is greater than 63, then ASSERT().
1580
1581   @param  Operand The 64-bit operand to rotate left.
1582   @param  Count   The number of bits to rotate left.
1583
1584   @return Operand <<< Count
1585
1586 **/
1587 UINT64
1588 EFIAPI
1589 LRotU64 (
1590   IN      UINT64                    Operand,
1591   IN      UINTN                     Count
1592   );
1593
1594 /**
1595   Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
1596   with the high low bits that were rotated.
1597
1598   This function rotates the 64-bit value Operand to the right by Count bits.
1599   The high Count bits are fill with the low Count bits of Operand. The rotated
1600   value is returned.
1601
1602   If Count is greater than 63, then ASSERT().
1603
1604   @param  Operand The 64-bit operand to rotate right.
1605   @param  Count   The number of bits to rotate right.
1606
1607   @return Operand >>> Count
1608
1609 **/
1610 UINT64
1611 EFIAPI
1612 RRotU64 (
1613   IN      UINT64                    Operand,
1614   IN      UINTN                     Count
1615   );
1616
1617 /**
1618   Returns the bit position of the lowest bit set in a 32-bit value.
1619
1620   This function computes the bit position of the lowest bit set in the 32-bit
1621   value specified by Operand. If Operand is zero, then -1 is returned.
1622   Otherwise, a value between 0 and 31 is returned.
1623
1624   @param  Operand The 32-bit operand to evaluate.
1625
1626   @return Position of the lowest bit set in Operand if found.
1627   @retval -1 Operand is zero.
1628
1629 **/
1630 INTN
1631 EFIAPI
1632 LowBitSet32 (
1633   IN      UINT32                    Operand
1634   );
1635
1636 /**
1637   Returns the bit position of the lowest bit set in a 64-bit value.
1638
1639   This function computes the bit position of the lowest bit set in the 64-bit
1640   value specified by Operand. If Operand is zero, then -1 is returned.
1641   Otherwise, a value between 0 and 63 is returned.
1642
1643   @param  Operand The 64-bit operand to evaluate.
1644
1645   @return Position of the lowest bit set in Operand if found.
1646   @retval -1  Operand is zero.
1647
1648 **/
1649 INTN
1650 EFIAPI
1651 LowBitSet64 (
1652   IN      UINT64                    Operand
1653   );
1654
1655 /**
1656   Returns the bit position of the highest bit set in a 32-bit value. Equivalent
1657   to log2(x).
1658
1659   This function computes the bit position of the highest bit set in the 32-bit
1660   value specified by Operand. If Operand is zero, then -1 is returned.
1661   Otherwise, a value between 0 and 31 is returned.
1662
1663   @param  Operand The 32-bit operand to evaluate.
1664
1665   @return Position of the highest bit set in Operand if found.
1666   @retval -1  Operand is zero.
1667
1668 **/
1669 INTN
1670 EFIAPI
1671 HighBitSet32 (
1672   IN      UINT32                    Operand
1673   );
1674
1675 /**
1676   Returns the bit position of the highest bit set in a 64-bit value. Equivalent
1677   to log2(x).
1678
1679   This function computes the bit position of the highest bit set in the 64-bit
1680   value specified by Operand. If Operand is zero, then -1 is returned.
1681   Otherwise, a value between 0 and 63 is returned.
1682
1683   @param  Operand The 64-bit operand to evaluate.
1684
1685   @return Position of the highest bit set in Operand if found.
1686   @retval -1  Operand is zero.
1687
1688 **/
1689 INTN
1690 EFIAPI
1691 HighBitSet64 (
1692   IN      UINT64                    Operand
1693   );
1694
1695 /**
1696   Returns the value of the highest bit set in a 32-bit value. Equivalent to
1697   1 << HighBitSet32(x).
1698
1699   This function computes the value of the highest bit set in the 32-bit value
1700   specified by Operand. If Operand is zero, then zero is returned.
1701
1702   @param  Operand The 32-bit operand to evaluate.
1703
1704   @return 1 << HighBitSet32(Operand)
1705   @retval 0 Operand is zero.
1706
1707 **/
1708 UINT32
1709 EFIAPI
1710 GetPowerOfTwo32 (
1711   IN      UINT32                    Operand
1712   );
1713
1714 /**
1715   Returns the value of the highest bit set in a 64-bit value. Equivalent to
1716   1 << HighBitSet64(x).
1717
1718   This function computes the value of the highest bit set in the 64-bit value
1719   specified by Operand. If Operand is zero, then zero is returned.
1720
1721   @param  Operand The 64-bit operand to evaluate.
1722
1723   @return 1 << HighBitSet64(Operand)
1724   @retval 0 Operand is zero.
1725
1726 **/
1727 UINT64
1728 EFIAPI
1729 GetPowerOfTwo64 (
1730   IN      UINT64                    Operand
1731   );
1732
1733 /**
1734   Switches the endianess of a 16-bit integer.
1735
1736   This function swaps the bytes in a 16-bit unsigned value to switch the value
1737   from little endian to big endian or vice versa. The byte swapped value is
1738   returned.
1739
1740   @param  Operand A 16-bit unsigned value.
1741
1742   @return The byte swaped Operand.
1743
1744 **/
1745 UINT16
1746 EFIAPI
1747 SwapBytes16 (
1748   IN      UINT16                    Value
1749   );
1750
1751 /**
1752   Switches the endianess of a 32-bit integer.
1753
1754   This function swaps the bytes in a 32-bit unsigned value to switch the value
1755   from little endian to big endian or vice versa. The byte swapped value is
1756   returned.
1757
1758   @param  Operand A 32-bit unsigned value.
1759
1760   @return The byte swaped Operand.
1761
1762 **/
1763 UINT32
1764 EFIAPI
1765 SwapBytes32 (
1766   IN      UINT32                    Value
1767   );
1768
1769 /**
1770   Switches the endianess of a 64-bit integer.
1771
1772   This function swaps the bytes in a 64-bit unsigned value to switch the value
1773   from little endian to big endian or vice versa. The byte swapped value is
1774   returned.
1775
1776   @param  Operand A 64-bit unsigned value.
1777
1778   @return The byte swaped Operand.
1779
1780 **/
1781 UINT64
1782 EFIAPI
1783 SwapBytes64 (
1784   IN      UINT64                    Value
1785   );
1786
1787 /**
1788   Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
1789   generates a 64-bit unsigned result.
1790
1791   This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
1792   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
1793   bit unsigned result is returned.
1794
1795   If the result overflows, then ASSERT().
1796
1797   @param  Multiplicand  A 64-bit unsigned value.
1798   @param  Multiplier    A 32-bit unsigned value.
1799
1800   @return Multiplicand * Multiplier
1801
1802 **/
1803 UINT64
1804 EFIAPI
1805 MultU64x32 (
1806   IN      UINT64                    Multiplicand,
1807   IN      UINT32                    Multiplier
1808   );
1809
1810 /**
1811   Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
1812   generates a 64-bit unsigned result.
1813
1814   This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
1815   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
1816   bit unsigned result is returned.
1817
1818   If the result overflows, then ASSERT().
1819
1820   @param  Multiplicand  A 64-bit unsigned value.
1821   @param  Multiplier    A 64-bit unsigned value.
1822
1823   @return Multiplicand * Multiplier
1824
1825 **/
1826 UINT64
1827 EFIAPI
1828 MultU64x64 (
1829   IN      UINT64                    Multiplicand,
1830   IN      UINT64                    Multiplier
1831   );
1832
1833 /**
1834   Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
1835   64-bit signed result.
1836
1837   This function multiples the 64-bit signed value Multiplicand by the 64-bit
1838   signed value Multiplier and generates a 64-bit signed result. This 64-bit
1839   signed result is returned.
1840
1841   If the result overflows, then ASSERT().
1842
1843   @param  Multiplicand  A 64-bit signed value.
1844   @param  Multiplier    A 64-bit signed value.
1845
1846   @return Multiplicand * Multiplier
1847
1848 **/
1849 INT64
1850 EFIAPI
1851 MultS64x64 (
1852   IN      INT64                     Multiplicand,
1853   IN      INT64                     Multiplier
1854   );
1855
1856 /**
1857   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
1858   a 64-bit unsigned result.
1859
1860   This function divides the 64-bit unsigned value Dividend by the 32-bit
1861   unsigned value Divisor and generates a 64-bit unsigned quotient. This
1862   function returns the 64-bit unsigned quotient.
1863
1864   If Divisor is 0, then ASSERT().
1865
1866   @param  Dividend  A 64-bit unsigned value.
1867   @param  Divisor   A 32-bit unsigned value.
1868
1869   @return Dividend / Divisor
1870
1871 **/
1872 UINT64
1873 EFIAPI
1874 DivU64x32 (
1875   IN      UINT64                    Dividend,
1876   IN      UINT32                    Divisor
1877   );
1878
1879 /**
1880   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
1881   a 32-bit unsigned remainder.
1882
1883   This function divides the 64-bit unsigned value Dividend by the 32-bit
1884   unsigned value Divisor and generates a 32-bit remainder. This function
1885   returns the 32-bit unsigned remainder.
1886
1887   If Divisor is 0, then ASSERT().
1888
1889   @param  Dividend  A 64-bit unsigned value.
1890   @param  Divisor   A 32-bit unsigned value.
1891
1892   @return Dividend % Divisor
1893
1894 **/
1895 UINT32
1896 EFIAPI
1897 ModU64x32 (
1898   IN      UINT64                    Dividend,
1899   IN      UINT32                    Divisor
1900   );
1901
1902 /**
1903   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
1904   a 64-bit unsigned result and an optional 32-bit unsigned remainder.
1905
1906   This function divides the 64-bit unsigned value Dividend by the 32-bit
1907   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
1908   is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
1909   This function returns the 64-bit unsigned quotient.
1910
1911   If Divisor is 0, then ASSERT().
1912
1913   @param  Dividend  A 64-bit unsigned value.
1914   @param  Divisor   A 32-bit unsigned value.
1915   @param  Remainder A pointer to a 32-bit unsigned value. This parameter is
1916                     optional and may be NULL.
1917
1918   @return Dividend / Divisor
1919
1920 **/
1921 UINT64
1922 EFIAPI
1923 DivU64x32Remainder (
1924   IN      UINT64                    Dividend,
1925   IN      UINT32                    Divisor,
1926   OUT     UINT32                    *Remainder  OPTIONAL
1927   );
1928
1929 /**
1930   Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
1931   a 64-bit unsigned result and an optional 64-bit unsigned remainder.
1932
1933   This function divides the 64-bit unsigned value Dividend by the 64-bit
1934   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
1935   is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
1936   This function returns the 64-bit unsigned quotient.
1937
1938   If Divisor is 0, then ASSERT().
1939
1940   @param  Dividend  A 64-bit unsigned value.
1941   @param  Divisor   A 64-bit unsigned value.
1942   @param  Remainder A pointer to a 64-bit unsigned value. This parameter is
1943                     optional and may be NULL.
1944
1945   @return Dividend / Divisor
1946
1947 **/
1948 UINT64
1949 EFIAPI
1950 DivU64x64Remainder (
1951   IN      UINT64                    Dividend,
1952   IN      UINT64                    Divisor,
1953   OUT     UINT64                    *Remainder  OPTIONAL
1954   );
1955
1956 /**
1957   Divides a 64-bit signed integer by a 64-bit signed integer and generates a
1958   64-bit signed result and a optional 64-bit signed remainder.
1959
1960   This function divides the 64-bit signed value Dividend by the 64-bit signed
1961   value Divisor and generates a 64-bit signed quotient. If Remainder is not
1962   NULL, then the 64-bit signed remainder is returned in Remainder. This
1963   function returns the 64-bit signed quotient.
1964
1965   If Divisor is 0, then ASSERT().
1966
1967   @param  Dividend  A 64-bit signed value.
1968   @param  Divisor   A 64-bit signed value.
1969   @param  Remainder A pointer to a 64-bit signed value. This parameter is
1970                     optional and may be NULL.
1971
1972   @return Dividend / Divisor
1973
1974 **/
1975 INT64
1976 EFIAPI
1977 DivS64x64Remainder (
1978   IN      INT64                     Dividend,
1979   IN      INT64                     Divisor,
1980   OUT     INT64                     *Remainder  OPTIONAL
1981   );
1982
1983 /**
1984   Reads a 16-bit value from memory that may be unaligned.
1985
1986   This function returns the 16-bit value pointed to by Buffer. The function
1987   guarantees that the read operation does not produce an alignment fault.
1988
1989   If the Buffer is NULL, then ASSERT().
1990
1991   @param  Buffer  Pointer to a 16-bit value that may be unaligned.
1992
1993   @return *Uint16
1994
1995 **/
1996 UINT16
1997 EFIAPI
1998 ReadUnaligned16 (
1999   IN      CONST UINT16              *Uint16
2000   );
2001
2002 /**
2003   Writes a 16-bit value to memory that may be unaligned.
2004
2005   This function writes the 16-bit value specified by Value to Buffer. Value is
2006   returned. The function guarantees that the write operation does not produce
2007   an alignment fault.
2008
2009   If the Buffer is NULL, then ASSERT().
2010
2011   @param  Buffer  Pointer to a 16-bit value that may be unaligned.
2012   @param  Value   16-bit value to write to Buffer.
2013
2014   @return Value
2015
2016 **/
2017 UINT16
2018 EFIAPI
2019 WriteUnaligned16 (
2020   OUT     UINT16                    *Uint16,
2021   IN      UINT16                    Value
2022   );
2023
2024 /**
2025   Reads a 24-bit value from memory that may be unaligned.
2026
2027   This function returns the 24-bit value pointed to by Buffer. The function
2028   guarantees that the read operation does not produce an alignment fault.
2029
2030   If the Buffer is NULL, then ASSERT().
2031
2032   @param  Buffer  Pointer to a 24-bit value that may be unaligned.
2033
2034   @return The value read.
2035
2036 **/
2037 UINT32
2038 EFIAPI
2039 ReadUnaligned24 (
2040   IN      CONST UINT32              *Buffer
2041   );
2042
2043 /**
2044   Writes a 24-bit value to memory that may be unaligned.
2045
2046   This function writes the 24-bit value specified by Value to Buffer. Value is
2047   returned. The function guarantees that the write operation does not produce
2048   an alignment fault.
2049
2050   If the Buffer is NULL, then ASSERT().
2051
2052   @param  Buffer  Pointer to a 24-bit value that may be unaligned.
2053   @param  Value   24-bit value to write to Buffer.
2054
2055   @return The value written.
2056
2057 **/
2058 UINT32
2059 EFIAPI
2060 WriteUnaligned24 (
2061   OUT     UINT32                    *Buffer,
2062   IN      UINT32                    Value
2063   );
2064
2065 /**
2066   Reads a 32-bit value from memory that may be unaligned.
2067
2068   This function returns the 32-bit value pointed to by Buffer. The function
2069   guarantees that the read operation does not produce an alignment fault.
2070
2071   If the Buffer is NULL, then ASSERT().
2072
2073   @param  Buffer  Pointer to a 32-bit value that may be unaligned.
2074
2075   @return *Uint32
2076
2077 **/
2078 UINT32
2079 EFIAPI
2080 ReadUnaligned32 (
2081   IN      CONST UINT32              *Uint32
2082   );
2083
2084 /**
2085   Writes a 32-bit value to memory that may be unaligned.
2086
2087   This function writes the 32-bit value specified by Value to Buffer. Value is
2088   returned. The function guarantees that the write operation does not produce
2089   an alignment fault.
2090
2091   If the Buffer is NULL, then ASSERT().
2092
2093   @param  Buffer  Pointer to a 32-bit value that may be unaligned.
2094   @param  Value   32-bit value to write to Buffer.
2095
2096   @return Value
2097
2098 **/
2099 UINT32
2100 EFIAPI
2101 WriteUnaligned32 (
2102   OUT     UINT32                    *Uint32,
2103   IN      UINT32                    Value
2104   );
2105
2106 /**
2107   Reads a 64-bit value from memory that may be unaligned.
2108
2109   This function returns the 64-bit value pointed to by Buffer. The function
2110   guarantees that the read operation does not produce an alignment fault.
2111
2112   If the Buffer is NULL, then ASSERT().
2113
2114   @param  Buffer  Pointer to a 64-bit value that may be unaligned.
2115
2116   @return *Uint64
2117
2118 **/
2119 UINT64
2120 EFIAPI
2121 ReadUnaligned64 (
2122   IN      CONST UINT64              *Uint64
2123   );
2124
2125 /**
2126   Writes a 64-bit value to memory that may be unaligned.
2127
2128   This function writes the 64-bit value specified by Value to Buffer. Value is
2129   returned. The function guarantees that the write operation does not produce
2130   an alignment fault.
2131
2132   If the Buffer is NULL, then ASSERT().
2133
2134   @param  Buffer  Pointer to a 64-bit value that may be unaligned.
2135   @param  Value   64-bit value to write to Buffer.
2136
2137   @return Value
2138
2139 **/
2140 UINT64
2141 EFIAPI
2142 WriteUnaligned64 (
2143   OUT     UINT64                    *Uint64,
2144   IN      UINT64                    Value
2145   );
2146
2147 //
2148 // Bit Field Functions
2149 //
2150
2151 /**
2152   Returns a bit field from an 8-bit value.
2153
2154   Returns the bitfield specified by the StartBit and the EndBit from Operand.
2155
2156   If 8-bit operations are not supported, then ASSERT().
2157   If StartBit is greater than 7, then ASSERT().
2158   If EndBit is greater than 7, then ASSERT().
2159   If EndBit is less than StartBit, then ASSERT().
2160
2161   @param  Operand   Operand on which to perform the bitfield operation.
2162   @param  StartBit  The ordinal of the least significant bit in the bit field.
2163                     Range 0..7.
2164   @param  EndBit    The ordinal of the most significant bit in the bit field.
2165                     Range 0..7.
2166
2167   @return The bit field read.
2168
2169 **/
2170 UINT8
2171 EFIAPI
2172 BitFieldRead8 (
2173   IN      UINT8                     Operand,
2174   IN      UINTN                     StartBit,
2175   IN      UINTN                     EndBit
2176   );
2177
2178 /**
2179   Writes a bit field to an 8-bit value, and returns the result.
2180
2181   Writes Value to the bit field specified by the StartBit and the EndBit in
2182   Operand. All other bits in Operand are preserved. The new 8-bit value is
2183   returned.
2184
2185   If 8-bit operations are not supported, then ASSERT().
2186   If StartBit is greater than 7, then ASSERT().
2187   If EndBit is greater than 7, then ASSERT().
2188   If EndBit is less than StartBit, then ASSERT().
2189
2190   @param  Operand   Operand on which to perform the bitfield operation.
2191   @param  StartBit  The ordinal of the least significant bit in the bit field.
2192                     Range 0..7.
2193   @param  EndBit    The ordinal of the most significant bit in the bit field.
2194                     Range 0..7.
2195   @param  Value     New value of the bit field.
2196
2197   @return The new 8-bit value.
2198
2199 **/
2200 UINT8
2201 EFIAPI
2202 BitFieldWrite8 (
2203   IN      UINT8                     Operand,
2204   IN      UINTN                     StartBit,
2205   IN      UINTN                     EndBit,
2206   IN      UINT8                     Value
2207   );
2208
2209 /**
2210   Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
2211   result.
2212
2213   Performs a bitwise inclusive OR between the bit field specified by StartBit
2214   and EndBit in Operand and the value specified by OrData. All other bits in
2215   Operand are preserved. The new 8-bit value is returned.
2216
2217   If 8-bit operations are not supported, then ASSERT().
2218   If StartBit is greater than 7, then ASSERT().
2219   If EndBit is greater than 7, then ASSERT().
2220   If EndBit is less than StartBit, then ASSERT().
2221
2222   @param  Operand   Operand on which to perform the bitfield operation.
2223   @param  StartBit  The ordinal of the least significant bit in the bit field.
2224                     Range 0..7.
2225   @param  EndBit    The ordinal of the most significant bit in the bit field.
2226                     Range 0..7.
2227   @param  OrData    The value to OR with the read value from the value
2228
2229   @return The new 8-bit value.
2230
2231 **/
2232 UINT8
2233 EFIAPI
2234 BitFieldOr8 (
2235   IN      UINT8                     Operand,
2236   IN      UINTN                     StartBit,
2237   IN      UINTN                     EndBit,
2238   IN      UINT8                     OrData
2239   );
2240
2241 /**
2242   Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
2243   the result.
2244
2245   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2246   in Operand and the value specified by AndData. All other bits in Operand are
2247   preserved. The new 8-bit value is returned.
2248
2249   If 8-bit operations are not supported, then ASSERT().
2250   If StartBit is greater than 7, then ASSERT().
2251   If EndBit is greater than 7, then ASSERT().
2252   If EndBit is less than StartBit, then ASSERT().
2253
2254   @param  Operand   Operand on which to perform the bitfield operation.
2255   @param  StartBit  The ordinal of the least significant bit in the bit field.
2256                     Range 0..7.
2257   @param  EndBit    The ordinal of the most significant bit in the bit field.
2258                     Range 0..7.
2259   @param  AndData   The value to AND with the read value from the value.
2260
2261   @return The new 8-bit value.
2262
2263 **/
2264 UINT8
2265 EFIAPI
2266 BitFieldAnd8 (
2267   IN      UINT8                     Operand,
2268   IN      UINTN                     StartBit,
2269   IN      UINTN                     EndBit,
2270   IN      UINT8                     AndData
2271   );
2272
2273 /**
2274   Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
2275   bitwise OR, and returns the result.
2276
2277   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2278   in Operand and the value specified by AndData, followed by a bitwise
2279   inclusive OR with value specified by OrData. All other bits in Operand are
2280   preserved. The new 8-bit value is returned.
2281
2282   If 8-bit operations are not supported, then ASSERT().
2283   If StartBit is greater than 7, then ASSERT().
2284   If EndBit is greater than 7, then ASSERT().
2285   If EndBit is less than StartBit, then ASSERT().
2286
2287   @param  Operand   Operand on which to perform the bitfield operation.
2288   @param  StartBit  The ordinal of the least significant bit in the bit field.
2289                     Range 0..7.
2290   @param  EndBit    The ordinal of the most significant bit in the bit field.
2291                     Range 0..7.
2292   @param  AndData   The value to AND with the read value from the value.
2293   @param  OrData    The value to OR with the result of the AND operation.
2294
2295   @return The new 8-bit value.
2296
2297 **/
2298 UINT8
2299 EFIAPI
2300 BitFieldAndThenOr8 (
2301   IN      UINT8                     Operand,
2302   IN      UINTN                     StartBit,
2303   IN      UINTN                     EndBit,
2304   IN      UINT8                     AndData,
2305   IN      UINT8                     OrData
2306   );
2307
2308 /**
2309   Returns a bit field from a 16-bit value.
2310
2311   Returns the bitfield specified by the StartBit and the EndBit from Operand.
2312
2313   If 16-bit operations are not supported, then ASSERT().
2314   If StartBit is greater than 15, then ASSERT().
2315   If EndBit is greater than 15, then ASSERT().
2316   If EndBit is less than StartBit, then ASSERT().
2317
2318   @param  Operand   Operand on which to perform the bitfield operation.
2319   @param  StartBit  The ordinal of the least significant bit in the bit field.
2320                     Range 0..15.
2321   @param  EndBit    The ordinal of the most significant bit in the bit field.
2322                     Range 0..15.
2323
2324   @return The bit field read.
2325
2326 **/
2327 UINT16
2328 EFIAPI
2329 BitFieldRead16 (
2330   IN      UINT16                    Operand,
2331   IN      UINTN                     StartBit,
2332   IN      UINTN                     EndBit
2333   );
2334
2335 /**
2336   Writes a bit field to a 16-bit value, and returns the result.
2337
2338   Writes Value to the bit field specified by the StartBit and the EndBit in
2339   Operand. All other bits in Operand are preserved. The new 16-bit value is
2340   returned.
2341
2342   If 16-bit operations are not supported, then ASSERT().
2343   If StartBit is greater than 15, then ASSERT().
2344   If EndBit is greater than 15, then ASSERT().
2345   If EndBit is less than StartBit, then ASSERT().
2346
2347   @param  Operand   Operand on which to perform the bitfield operation.
2348   @param  StartBit  The ordinal of the least significant bit in the bit field.
2349                     Range 0..15.
2350   @param  EndBit    The ordinal of the most significant bit in the bit field.
2351                     Range 0..15.
2352   @param  Value     New value of the bit field.
2353
2354   @return The new 16-bit value.
2355
2356 **/
2357 UINT16
2358 EFIAPI
2359 BitFieldWrite16 (
2360   IN      UINT16                    Operand,
2361   IN      UINTN                     StartBit,
2362   IN      UINTN                     EndBit,
2363   IN      UINT16                    Value
2364   );
2365
2366 /**
2367   Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
2368   result.
2369
2370   Performs a bitwise inclusive OR between the bit field specified by StartBit
2371   and EndBit in Operand and the value specified by OrData. All other bits in
2372   Operand are preserved. The new 16-bit value is returned.
2373
2374   If 16-bit operations are not supported, then ASSERT().
2375   If StartBit is greater than 15, then ASSERT().
2376   If EndBit is greater than 15, then ASSERT().
2377   If EndBit is less than StartBit, then ASSERT().
2378
2379   @param  Operand   Operand on which to perform the bitfield operation.
2380   @param  StartBit  The ordinal of the least significant bit in the bit field.
2381                     Range 0..15.
2382   @param  EndBit    The ordinal of the most significant bit in the bit field.
2383                     Range 0..15.
2384   @param  OrData    The value to OR with the read value from the value
2385
2386   @return The new 16-bit value.
2387
2388 **/
2389 UINT16
2390 EFIAPI
2391 BitFieldOr16 (
2392   IN      UINT16                    Operand,
2393   IN      UINTN                     StartBit,
2394   IN      UINTN                     EndBit,
2395   IN      UINT16                    OrData
2396   );
2397
2398 /**
2399   Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
2400   the result.
2401
2402   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2403   in Operand and the value specified by AndData. All other bits in Operand are
2404   preserved. The new 16-bit value is returned.
2405
2406   If 16-bit operations are not supported, then ASSERT().
2407   If StartBit is greater than 15, then ASSERT().
2408   If EndBit is greater than 15, then ASSERT().
2409   If EndBit is less than StartBit, then ASSERT().
2410
2411   @param  Operand   Operand on which to perform the bitfield operation.
2412   @param  StartBit  The ordinal of the least significant bit in the bit field.
2413                     Range 0..15.
2414   @param  EndBit    The ordinal of the most significant bit in the bit field.
2415                     Range 0..15.
2416   @param  AndData   The value to AND with the read value from the value
2417
2418   @return The new 16-bit value.
2419
2420 **/
2421 UINT16
2422 EFIAPI
2423 BitFieldAnd16 (
2424   IN      UINT16                    Operand,
2425   IN      UINTN                     StartBit,
2426   IN      UINTN                     EndBit,
2427   IN      UINT16                    AndData
2428   );
2429
2430 /**
2431   Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
2432   bitwise OR, and returns the result.
2433
2434   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2435   in Operand and the value specified by AndData, followed by a bitwise
2436   inclusive OR with value specified by OrData. All other bits in Operand are
2437   preserved. The new 16-bit value is returned.
2438
2439   If 16-bit operations are not supported, then ASSERT().
2440   If StartBit is greater than 15, then ASSERT().
2441   If EndBit is greater than 15, then ASSERT().
2442   If EndBit is less than StartBit, then ASSERT().
2443
2444   @param  Operand   Operand on which to perform the bitfield operation.
2445   @param  StartBit  The ordinal of the least significant bit in the bit field.
2446                     Range 0..15.
2447   @param  EndBit    The ordinal of the most significant bit in the bit field.
2448                     Range 0..15.
2449   @param  AndData   The value to AND with the read value from the value.
2450   @param  OrData    The value to OR with the result of the AND operation.
2451
2452   @return The new 16-bit value.
2453
2454 **/
2455 UINT16
2456 EFIAPI
2457 BitFieldAndThenOr16 (
2458   IN      UINT16                    Operand,
2459   IN      UINTN                     StartBit,
2460   IN      UINTN                     EndBit,
2461   IN      UINT16                    AndData,
2462   IN      UINT16                    OrData
2463   );
2464
2465 /**
2466   Returns a bit field from a 32-bit value.
2467
2468   Returns the bitfield specified by the StartBit and the EndBit from Operand.
2469
2470   If 32-bit operations are not supported, then ASSERT().
2471   If StartBit is greater than 31, then ASSERT().
2472   If EndBit is greater than 31, then ASSERT().
2473   If EndBit is less than StartBit, then ASSERT().
2474
2475   @param  Operand   Operand on which to perform the bitfield operation.
2476   @param  StartBit  The ordinal of the least significant bit in the bit field.
2477                     Range 0..31.
2478   @param  EndBit    The ordinal of the most significant bit in the bit field.
2479                     Range 0..31.
2480
2481   @return The bit field read.
2482
2483 **/
2484 UINT32
2485 EFIAPI
2486 BitFieldRead32 (
2487   IN      UINT32                    Operand,
2488   IN      UINTN                     StartBit,
2489   IN      UINTN                     EndBit
2490   );
2491
2492 /**
2493   Writes a bit field to a 32-bit value, and returns the result.
2494
2495   Writes Value to the bit field specified by the StartBit and the EndBit in
2496   Operand. All other bits in Operand are preserved. The new 32-bit value is
2497   returned.
2498
2499   If 32-bit operations are not supported, then ASSERT().
2500   If StartBit is greater than 31, then ASSERT().
2501   If EndBit is greater than 31, then ASSERT().
2502   If EndBit is less than StartBit, then ASSERT().
2503
2504   @param  Operand   Operand on which to perform the bitfield operation.
2505   @param  StartBit  The ordinal of the least significant bit in the bit field.
2506                     Range 0..31.
2507   @param  EndBit    The ordinal of the most significant bit in the bit field.
2508                     Range 0..31.
2509   @param  Value     New value of the bit field.
2510
2511   @return The new 32-bit value.
2512
2513 **/
2514 UINT32
2515 EFIAPI
2516 BitFieldWrite32 (
2517   IN      UINT32                    Operand,
2518   IN      UINTN                     StartBit,
2519   IN      UINTN                     EndBit,
2520   IN      UINT32                    Value
2521   );
2522
2523 /**
2524   Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
2525   result.
2526
2527   Performs a bitwise inclusive OR between the bit field specified by StartBit
2528   and EndBit in Operand and the value specified by OrData. All other bits in
2529   Operand are preserved. The new 32-bit value is returned.
2530
2531   If 32-bit operations are not supported, then ASSERT().
2532   If StartBit is greater than 31, then ASSERT().
2533   If EndBit is greater than 31, then ASSERT().
2534   If EndBit is less than StartBit, then ASSERT().
2535
2536   @param  Operand   Operand on which to perform the bitfield operation.
2537   @param  StartBit  The ordinal of the least significant bit in the bit field.
2538                     Range 0..31.
2539   @param  EndBit    The ordinal of the most significant bit in the bit field.
2540                     Range 0..31.
2541   @param  OrData    The value to OR with the read value from the value
2542
2543   @return The new 32-bit value.
2544
2545 **/
2546 UINT32
2547 EFIAPI
2548 BitFieldOr32 (
2549   IN      UINT32                    Operand,
2550   IN      UINTN                     StartBit,
2551   IN      UINTN                     EndBit,
2552   IN      UINT32                    OrData
2553   );
2554
2555 /**
2556   Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
2557   the result.
2558
2559   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2560   in Operand and the value specified by AndData. All other bits in Operand are
2561   preserved. The new 32-bit value is returned.
2562
2563   If 32-bit operations are not supported, then ASSERT().
2564   If StartBit is greater than 31, then ASSERT().
2565   If EndBit is greater than 31, then ASSERT().
2566   If EndBit is less than StartBit, then ASSERT().
2567
2568   @param  Operand   Operand on which to perform the bitfield operation.
2569   @param  StartBit  The ordinal of the least significant bit in the bit field.
2570                     Range 0..31.
2571   @param  EndBit    The ordinal of the most significant bit in the bit field.
2572                     Range 0..31.
2573   @param  AndData   The value to AND with the read value from the value
2574
2575   @return The new 32-bit value.
2576
2577 **/
2578 UINT32
2579 EFIAPI
2580 BitFieldAnd32 (
2581   IN      UINT32                    Operand,
2582   IN      UINTN                     StartBit,
2583   IN      UINTN                     EndBit,
2584   IN      UINT32                    AndData
2585   );
2586
2587 /**
2588   Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
2589   bitwise OR, and returns the result.
2590
2591   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2592   in Operand and the value specified by AndData, followed by a bitwise
2593   inclusive OR with value specified by OrData. All other bits in Operand are
2594   preserved. The new 32-bit value is returned.
2595
2596   If 32-bit operations are not supported, then ASSERT().
2597   If StartBit is greater than 31, then ASSERT().
2598   If EndBit is greater than 31, then ASSERT().
2599   If EndBit is less than StartBit, then ASSERT().
2600
2601   @param  Operand   Operand on which to perform the bitfield operation.
2602   @param  StartBit  The ordinal of the least significant bit in the bit field.
2603                     Range 0..31.
2604   @param  EndBit    The ordinal of the most significant bit in the bit field.
2605                     Range 0..31.
2606   @param  AndData   The value to AND with the read value from the value.
2607   @param  OrData    The value to OR with the result of the AND operation.
2608
2609   @return The new 32-bit value.
2610
2611 **/
2612 UINT32
2613 EFIAPI
2614 BitFieldAndThenOr32 (
2615   IN      UINT32                    Operand,
2616   IN      UINTN                     StartBit,
2617   IN      UINTN                     EndBit,
2618   IN      UINT32                    AndData,
2619   IN      UINT32                    OrData
2620   );
2621
2622 /**
2623   Returns a bit field from a 64-bit value.
2624
2625   Returns the bitfield specified by the StartBit and the EndBit from Operand.
2626
2627   If 64-bit operations are not supported, then ASSERT().
2628   If StartBit is greater than 63, then ASSERT().
2629   If EndBit is greater than 63, then ASSERT().
2630   If EndBit is less than StartBit, then ASSERT().
2631
2632   @param  Operand   Operand on which to perform the bitfield operation.
2633   @param  StartBit  The ordinal of the least significant bit in the bit field.
2634                     Range 0..63.
2635   @param  EndBit    The ordinal of the most significant bit in the bit field.
2636                     Range 0..63.
2637
2638   @return The bit field read.
2639
2640 **/
2641 UINT64
2642 EFIAPI
2643 BitFieldRead64 (
2644   IN      UINT64                    Operand,
2645   IN      UINTN                     StartBit,
2646   IN      UINTN                     EndBit
2647   );
2648
2649 /**
2650   Writes a bit field to a 64-bit value, and returns the result.
2651
2652   Writes Value to the bit field specified by the StartBit and the EndBit in
2653   Operand. All other bits in Operand are preserved. The new 64-bit value is
2654   returned.
2655
2656   If 64-bit operations are not supported, then ASSERT().
2657   If StartBit is greater than 63, then ASSERT().
2658   If EndBit is greater than 63, then ASSERT().
2659   If EndBit is less than StartBit, then ASSERT().
2660
2661   @param  Operand   Operand on which to perform the bitfield operation.
2662   @param  StartBit  The ordinal of the least significant bit in the bit field.
2663                     Range 0..63.
2664   @param  EndBit    The ordinal of the most significant bit in the bit field.
2665                     Range 0..63.
2666   @param  Value     New value of the bit field.
2667
2668   @return The new 64-bit value.
2669
2670 **/
2671 UINT64
2672 EFIAPI
2673 BitFieldWrite64 (
2674   IN      UINT64                    Operand,
2675   IN      UINTN                     StartBit,
2676   IN      UINTN                     EndBit,
2677   IN      UINT64                    Value
2678   );
2679
2680 /**
2681   Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
2682   result.
2683
2684   Performs a bitwise inclusive OR between the bit field specified by StartBit
2685   and EndBit in Operand and the value specified by OrData. All other bits in
2686   Operand are preserved. The new 64-bit value is returned.
2687
2688   If 64-bit operations are not supported, then ASSERT().
2689   If StartBit is greater than 63, then ASSERT().
2690   If EndBit is greater than 63, then ASSERT().
2691   If EndBit is less than StartBit, then ASSERT().
2692
2693   @param  Operand   Operand on which to perform the bitfield operation.
2694   @param  StartBit  The ordinal of the least significant bit in the bit field.
2695                     Range 0..63.
2696   @param  EndBit    The ordinal of the most significant bit in the bit field.
2697                     Range 0..63.
2698   @param  OrData    The value to OR with the read value from the value
2699
2700   @return The new 64-bit value.
2701
2702 **/
2703 UINT64
2704 EFIAPI
2705 BitFieldOr64 (
2706   IN      UINT64                    Operand,
2707   IN      UINTN                     StartBit,
2708   IN      UINTN                     EndBit,
2709   IN      UINT64                    OrData
2710   );
2711
2712 /**
2713   Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
2714   the result.
2715
2716   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2717   in Operand and the value specified by AndData. All other bits in Operand are
2718   preserved. The new 64-bit value is returned.
2719
2720   If 64-bit operations are not supported, then ASSERT().
2721   If StartBit is greater than 63, then ASSERT().
2722   If EndBit is greater than 63, then ASSERT().
2723   If EndBit is less than StartBit, then ASSERT().
2724
2725   @param  Operand   Operand on which to perform the bitfield operation.
2726   @param  StartBit  The ordinal of the least significant bit in the bit field.
2727                     Range 0..63.
2728   @param  EndBit    The ordinal of the most significant bit in the bit field.
2729                     Range 0..63.
2730   @param  AndData   The value to AND with the read value from the value
2731
2732   @return The new 64-bit value.
2733
2734 **/
2735 UINT64
2736 EFIAPI
2737 BitFieldAnd64 (
2738   IN      UINT64                    Operand,
2739   IN      UINTN                     StartBit,
2740   IN      UINTN                     EndBit,
2741   IN      UINT64                    AndData
2742   );
2743
2744 /**
2745   Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
2746   bitwise OR, and returns the result.
2747
2748   Performs a bitwise AND between the bit field specified by StartBit and EndBit
2749   in Operand and the value specified by AndData, followed by a bitwise
2750   inclusive OR with value specified by OrData. All other bits in Operand are
2751   preserved. The new 64-bit value is returned.
2752
2753   If 64-bit operations are not supported, then ASSERT().
2754   If StartBit is greater than 63, then ASSERT().
2755   If EndBit is greater than 63, then ASSERT().
2756   If EndBit is less than StartBit, then ASSERT().
2757
2758   @param  Operand   Operand on which to perform the bitfield operation.
2759   @param  StartBit  The ordinal of the least significant bit in the bit field.
2760                     Range 0..63.
2761   @param  EndBit    The ordinal of the most significant bit in the bit field.
2762                     Range 0..63.
2763   @param  AndData   The value to AND with the read value from the value.
2764   @param  OrData    The value to OR with the result of the AND operation.
2765
2766   @return The new 64-bit value.
2767
2768 **/
2769 UINT64
2770 EFIAPI
2771 BitFieldAndThenOr64 (
2772   IN      UINT64                    Operand,
2773   IN      UINTN                     StartBit,
2774   IN      UINTN                     EndBit,
2775   IN      UINT64                    AndData,
2776   IN      UINT64                    OrData
2777   );
2778
2779 //
2780 // Base Library Synchronization Functions
2781 //
2782
2783 /**
2784   Retrieves the architecture specific spin lock alignment requirements for
2785   optimal spin lock performance.
2786
2787   This function retrieves the spin lock alignment requirements for optimal
2788   performance on a given CPU architecture. The spin lock alignment must be a
2789   power of two and is returned by this function. If there are no alignment
2790   requirements, then 1 must be returned. The spin lock synchronization
2791   functions must function correctly if the spin lock size and alignment values
2792   returned by this function are not used at all. These values are hints to the
2793   consumers of the spin lock synchronization functions to obtain optimal spin
2794   lock performance.
2795
2796   @return The architecture specific spin lock alignment.
2797
2798 **/
2799 UINTN
2800 EFIAPI
2801 GetSpinLockProperties (
2802   VOID
2803   );
2804
2805 /**
2806   Initializes a spin lock to the released state and returns the spin lock.
2807
2808   This function initializes the spin lock specified by SpinLock to the released
2809   state, and returns SpinLock. Optimal performance can be achieved by calling
2810   GetSpinLockProperties() to determine the size and alignment requirements for
2811   SpinLock.
2812
2813   If SpinLock is NULL, then ASSERT().
2814
2815   @param  SpinLock  A pointer to the spin lock to initialize to the released
2816                     state.
2817
2818   @return SpinLock
2819
2820 **/
2821 SPIN_LOCK *
2822 EFIAPI
2823 InitializeSpinLock (
2824   IN      SPIN_LOCK                 *SpinLock
2825   );
2826
2827 /**
2828   Waits until a spin lock can be placed in the acquired state.
2829
2830   This function checks the state of the spin lock specified by SpinLock. If
2831   SpinLock is in the released state, then this function places SpinLock in the
2832   acquired state and returns SpinLock. Otherwise, this function waits
2833   indefinitely for the spin lock to be released, and then places it in the
2834   acquired state and returns SpinLock. All state transitions of SpinLock must
2835   be performed using MP safe mechanisms.
2836
2837   If SpinLock is NULL, then ASSERT().
2838   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
2839   If PcdSpinLockTimeout is not zero, and SpinLock is can not be acquired in
2840   PcdSpinLockTimeout microseconds, then ASSERT().
2841
2842   @param  SpinLock  A pointer to the spin lock to place in the acquired state.
2843
2844   @return SpinLock
2845
2846 **/
2847 SPIN_LOCK *
2848 EFIAPI
2849 AcquireSpinLock (
2850   IN      SPIN_LOCK                 *SpinLock
2851   );
2852
2853 /**
2854   Attempts to place a spin lock in the acquired state.
2855
2856   This function checks the state of the spin lock specified by SpinLock. If
2857   SpinLock is in the released state, then this function places SpinLock in the
2858   acquired state and returns TRUE. Otherwise, FALSE is returned. All state
2859   transitions of SpinLock must be performed using MP safe mechanisms.
2860
2861   If SpinLock is NULL, then ASSERT().
2862   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
2863
2864   @param  SpinLock  A pointer to the spin lock to place in the acquired state.
2865
2866   @retval TRUE  SpinLock was placed in the acquired state.
2867   @retval FALSE SpinLock could not be acquired.
2868
2869 **/
2870 BOOLEAN
2871 EFIAPI
2872 AcquireSpinLockOrFail (
2873   IN      SPIN_LOCK                 *SpinLock
2874   );
2875
2876 /**
2877   Releases a spin lock.
2878
2879   This function places the spin lock specified by SpinLock in the release state
2880   and returns SpinLock.
2881
2882   If SpinLock is NULL, then ASSERT().
2883   If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().
2884
2885   @param  SpinLock  A pointer to the spin lock to release.
2886
2887   @return SpinLock
2888
2889 **/
2890 SPIN_LOCK *
2891 EFIAPI
2892 ReleaseSpinLock (
2893   IN      SPIN_LOCK                 *SpinLock
2894   );
2895
2896 /**
2897   Performs an atomic increment of an 32-bit unsigned integer.
2898
2899   Performs an atomic increment of the 32-bit unsigned integer specified by
2900   Value and returns the incremented value. The increment operation must be
2901   performed using MP safe mechanisms. The state of the return value is not
2902   guaranteed to be MP safe.
2903
2904   If Value is NULL, then ASSERT().
2905
2906   @param  Value A pointer to the 32-bit value to increment.
2907
2908   @return The incremented value.
2909
2910 **/
2911 UINT32
2912 EFIAPI
2913 InterlockedIncrement (
2914   IN      UINT32                    *Value
2915   );
2916
2917 /**
2918   Performs an atomic decrement of an 32-bit unsigned integer.
2919
2920   Performs an atomic decrement of the 32-bit unsigned integer specified by
2921   Value and returns the decremented value. The decrement operation must be
2922   performed using MP safe mechanisms. The state of the return value is not
2923   guaranteed to be MP safe.
2924
2925   If Value is NULL, then ASSERT().
2926
2927   @param  Value A pointer to the 32-bit value to decrement.
2928
2929   @return The decremented value.
2930
2931 **/
2932 UINT32
2933 EFIAPI
2934 InterlockedDecrement (
2935   IN      UINT32                    *Value
2936   );
2937
2938 /**
2939   Performs an atomic compare exchange operation on a 32-bit unsigned integer.
2940
2941   Performs an atomic compare exchange operation on the 32-bit unsigned integer
2942   specified by Value.  If Value is equal to CompareValue, then Value is set to
2943   ExchangeValue and CompareValue is returned.  If Value is not equal to CompareValue,
2944   then Value is returned.  The compare exchange operation must be performed using
2945   MP safe mechanisms.
2946
2947   If Value is NULL, then ASSERT().
2948
2949   @param  Value         A pointer to the 32-bit value for the compare exchange
2950                         operation.
2951   @param  CompareValue  32-bit value used in compare operation.
2952   @param  ExchangeValue 32-bit value used in exchange operation.
2953
2954   @return The original *Value before exchange.
2955
2956 **/
2957 UINT32
2958 EFIAPI
2959 InterlockedCompareExchange32 (
2960   IN OUT  UINT32                    *Value,
2961   IN      UINT32                    CompareValue,
2962   IN      UINT32                    ExchangeValue
2963   );
2964
2965 /**
2966   Performs an atomic compare exchange operation on a 64-bit unsigned integer.
2967
2968   Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
2969   by Value.  If Value is equal to CompareValue, then Value is set to ExchangeValue and
2970   CompareValue is returned.  If Value is not equal to CompareValue, then Value is returned.
2971   The compare exchange operation must be performed using MP safe mechanisms.
2972
2973   If Value is NULL, then ASSERT().
2974
2975   @param  Value         A pointer to the 64-bit value for the compare exchange
2976                         operation.
2977   @param  CompareValue  64-bit value used in compare operation.
2978   @param  ExchangeValue 64-bit value used in exchange operation.
2979
2980   @return The original *Value before exchange.
2981
2982 **/
2983 UINT64
2984 EFIAPI
2985 InterlockedCompareExchange64 (
2986   IN OUT  UINT64                    *Value,
2987   IN      UINT64                    CompareValue,
2988   IN      UINT64                    ExchangeValue
2989   );
2990
2991 /**
2992   Performs an atomic compare exchange operation on a pointer value.
2993
2994   Performs an atomic compare exchange operation on the pointer value specified
2995   by Value. If Value is equal to CompareValue, then Value is set to
2996   ExchangeValue and CompareValue is returned. If Value is not equal to
2997   CompareValue, then Value is returned. The compare exchange operation must be
2998   performed using MP safe mechanisms.
2999
3000   If Value is NULL, then ASSERT().
3001
3002   @param  Value         A pointer to the pointer value for the compare exchange
3003                         operation.
3004   @param  CompareValue  Pointer value used in compare operation.
3005   @param  ExchangeValue Pointer value used in exchange operation.
3006
3007 **/
3008 VOID *
3009 EFIAPI
3010 InterlockedCompareExchangePointer (
3011   IN OUT  VOID                      **Value,
3012   IN      VOID                      *CompareValue,
3013   IN      VOID                      *ExchangeValue
3014   );
3015
3016 //
3017 // Base Library Checksum Functions
3018 //
3019
3020 /**
3021   Calculate the sum of all elements in a buffer in unit of UINT8. 
3022   During calculation, the carry bits are dropped.
3023
3024   This function calculates the sum of all elements in a buffer 
3025   in unit of UINT8. The carry bits in result of addition are dropped. 
3026   The result is returned as UINT8. If Length is Zero, then Zero is 
3027   returned.
3028   
3029   If Buffer is NULL, then ASSERT().
3030   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 
3031
3032   @param  Buffer                        Pointer to the buffer to carry out the sum operation.
3033   @param  Length            The size, in bytes, of Buffer .
3034
3035   @return Sum         The sum of Buffer with carry bits dropped during additions.
3036
3037 **/
3038 UINT8
3039 EFIAPI
3040 CalculateSum8 (
3041   IN      CONST UINT8                   *Buffer,
3042   IN      UINTN                               Length
3043   );
3044
3045
3046 /**
3047   Returns the two's complement checksum of all elements in a buffer 
3048   of 8-bit values.
3049
3050   This function first calculates the sum of the 8-bit values in the 
3051   buffer specified by Buffer and Length.  The carry bits in the result 
3052   of addition are dropped. Then, the two's complement of the sum is 
3053   returned.  If Length is 0, then 0 is returned.
3054   
3055   If Buffer is NULL, then ASSERT().
3056   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3057
3058
3059   @param  Buffer                        Pointer to the buffer to carry out the checksum operation.
3060   @param  Length            The size, in bytes, of Buffer.
3061
3062   @return Checksum        The 2's complement checksum of Buffer.
3063
3064 **/
3065 UINT8
3066 EFIAPI
3067 CalculateCheckSum8 (
3068   IN      CONST UINT8                   *Buffer,
3069   IN      UINTN                               Length
3070   );
3071
3072 /**
3073   Returns the sum of all elements in a buffer of 16-bit values.  During 
3074   calculation, the carry bits are dropped.
3075
3076   This function calculates the sum of the 16-bit values in the buffer 
3077   specified by Buffer and Length. The carry bits in result of addition are dropped. 
3078   The 16-bit result is returned.  If Length is 0, then 0 is returned.  
3079   
3080   If Buffer is NULL, then ASSERT().
3081   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
3082   If Length is not aligned on a 16-bit boundary, then ASSERT().
3083   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3084
3085   @param  Buffer                        Pointer to the buffer to carry out the sum operation.
3086   @param  Length            The size, in bytes, of Buffer.
3087
3088   @return Sum         The sum of Buffer with carry bits dropped during additions.
3089
3090 **/
3091 UINT16
3092 EFIAPI
3093 CalculateSum16 (
3094   IN      CONST UINT16                  *Buffer,
3095   IN      UINTN                               Length
3096   );
3097
3098 /**
3099   Returns the two's complement checksum of all elements in a buffer of 
3100   16-bit values.
3101
3102   This function first calculates the sum of the 16-bit values in the buffer 
3103   specified by Buffer and Length.  The carry bits in the result of addition 
3104   are dropped. Then, the two's complement of the sum is returned.  If Length 
3105   is 0, then 0 is returned.
3106   
3107   If Buffer is NULL, then ASSERT().
3108   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
3109   If Length is not aligned on a 16-bit boundary, then ASSERT().
3110   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 
3111
3112   @param  Buffer                        Pointer to the buffer to carry out the checksum operation.
3113   @param  Length            The size, in bytes, of Buffer.
3114
3115   @return Checksum        The 2's complement checksum of Buffer.
3116
3117 **/
3118 UINT16
3119 EFIAPI
3120 CalculateCheckSum16 (
3121   IN      CONST UINT16                  *Buffer,
3122   IN      UINTN                               Length
3123   );
3124
3125 /**
3126   Returns the sum of all elements in a buffer of 32-bit values.  During 
3127   calculation, the carry bits are dropped.
3128
3129   This function calculates the sum of the 32-bit values in the buffer 
3130   specified by Buffer and Length. The carry bits in result of addition are dropped. 
3131   The 32-bit result is returned.  If Length is 0, then 0 is returned.  
3132   
3133   If Buffer is NULL, then ASSERT().
3134   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
3135   If Length is not aligned on a 32-bit boundary, then ASSERT().
3136   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3137
3138   @param  Buffer                        Pointer to the buffer to carry out the sum operation.
3139   @param  Length            The size, in bytes, of Buffer.
3140
3141   @return Sum         The sum of Buffer with carry bits dropped during additions.
3142
3143 **/
3144 UINT32
3145 EFIAPI
3146 CalculateSum32 (
3147   IN      CONST UINT32                  *Buffer,
3148   IN      UINTN                               Length
3149   );
3150
3151 /**
3152   Returns the two's complement checksum of all elements in a buffer of 
3153   32-bit values.
3154
3155   This function first calculates the sum of the 32-bit values in the buffer 
3156   specified by Buffer and Length.  The carry bits in the result of addition 
3157   are dropped. Then, the two's complement of the sum is returned.  If Length 
3158   is 0, then 0 is returned.
3159   
3160   If Buffer is NULL, then ASSERT().
3161   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
3162   If Length is not aligned on a 32-bit boundary, then ASSERT().
3163   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 
3164
3165   @param  Buffer                        Pointer to the buffer to carry out the checksum operation.
3166   @param  Length            The size, in bytes, of Buffer.
3167
3168   @return Checksum        The 2's complement checksum of Buffer.
3169
3170 **/
3171 UINT32
3172 EFIAPI
3173 CalculateCheckSum32 (
3174   IN      CONST UINT32                  *Buffer,
3175   IN      UINTN                               Length
3176   );
3177
3178 /**
3179   Returns the sum of all elements in a buffer of 64-bit values.  During 
3180   calculation, the carry bits are dropped.
3181
3182   This function calculates the sum of the 64-bit values in the buffer 
3183   specified by Buffer and Length. The carry bits in result of addition are dropped. 
3184   The 64-bit result is returned.  If Length is 0, then 0 is returned.  
3185   
3186   If Buffer is NULL, then ASSERT().
3187   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
3188   If Length is not aligned on a 64-bit boundary, then ASSERT().
3189   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
3190
3191   @param  Buffer                        Pointer to the buffer to carry out the sum operation.
3192   @param  Length            The size, in bytes, of Buffer.
3193
3194   @return Sum         The sum of Buffer with carry bits dropped during additions.
3195
3196 **/
3197 UINT64
3198 EFIAPI
3199 CalculateSum64 (
3200   IN      CONST UINT64                  *Buffer,
3201   IN      UINTN                               Length
3202   );
3203
3204 /**
3205   Returns the two's complement checksum of all elements in a buffer of 
3206   64-bit values.
3207
3208   This function first calculates the sum of the 64-bit values in the buffer 
3209   specified by Buffer and Length.  The carry bits in the result of addition 
3210   are dropped. Then, the two's complement of the sum is returned.  If Length 
3211   is 0, then 0 is returned.
3212   
3213   If Buffer is NULL, then ASSERT().
3214   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
3215   If Length is not aligned on a 64-bit boundary, then ASSERT().
3216   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 
3217
3218   @param  Buffer                        Pointer to the buffer to carry out the checksum operation.
3219   @param  Length            The size, in bytes, of Buffer.
3220
3221   @return Checksum        The 2's complement checksum of Buffer.
3222
3223 **/
3224 UINT64
3225 EFIAPI
3226 CalculateCheckSum64 (
3227   IN      CONST UINT64                  *Buffer,
3228   IN      UINTN                               Length
3229   );
3230
3231 //
3232 // Base Library CPU Functions
3233 //
3234 typedef
3235 VOID
3236 (EFIAPI *SWITCH_STACK_ENTRY_POINT) (
3237   IN      VOID                      *Context1,  OPTIONAL
3238   IN      VOID                      *Context2   OPTIONAL
3239   );
3240
3241 /**
3242   Used to serialize load and store operations.
3243
3244   All loads and stores that proceed calls to this function are guaranteed to be
3245   globally visible when this function returns.
3246
3247 **/
3248 VOID
3249 EFIAPI
3250 MemoryFence (
3251   VOID
3252   );
3253
3254 /**
3255   Saves the current CPU context that can be restored with a call to LongJump()
3256   and returns 0.
3257
3258   Saves the current CPU context in the buffer specified by JumpBuffer and
3259   returns 0. The initial call to SetJump() must always return 0. Subsequent
3260   calls to LongJump() cause a non-zero value to be returned by SetJump().
3261
3262   If JumpBuffer is NULL, then ASSERT().
3263   For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
3264
3265   @param  JumpBuffer  A pointer to CPU context buffer.
3266
3267   @retval 0 Indicates a return from SetJump().
3268
3269 **/
3270 UINTN
3271 EFIAPI
3272 SetJump (
3273   OUT     BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer
3274   );
3275
3276 /**
3277   Restores the CPU context that was saved with SetJump().
3278
3279   Restores the CPU context from the buffer specified by JumpBuffer. This
3280   function never returns to the caller. Instead is resumes execution based on
3281   the state of JumpBuffer.
3282
3283   If JumpBuffer is NULL, then ASSERT().
3284   For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
3285   If Value is 0, then ASSERT().
3286
3287   @param  JumpBuffer  A pointer to CPU context buffer.
3288   @param  Value       The value to return when the SetJump() context is
3289                       restored and must be non-zero.
3290
3291 **/
3292 VOID
3293 EFIAPI
3294 LongJump (
3295   IN      BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer,
3296   IN      UINTN                     Value
3297   );
3298
3299 /**
3300   Enables CPU interrupts.
3301
3302   Enables CPU interrupts.
3303
3304 **/
3305 VOID
3306 EFIAPI
3307 EnableInterrupts (
3308   VOID
3309   );
3310
3311 /**
3312   Disables CPU interrupts.
3313
3314   Disables CPU interrupts.
3315
3316 **/
3317 VOID
3318 EFIAPI
3319 DisableInterrupts (
3320   VOID
3321   );
3322
3323 /**
3324   Disables CPU interrupts and returns the interrupt state prior to the disable
3325   operation.
3326
3327   Disables CPU interrupts and returns the interrupt state prior to the disable
3328   operation.
3329
3330   @retval TRUE  CPU interrupts were enabled on entry to this call.
3331   @retval FALSE CPU interrupts were disabled on entry to this call.
3332
3333 **/
3334 BOOLEAN
3335 EFIAPI
3336 SaveAndDisableInterrupts (
3337   VOID
3338   );
3339
3340 /**
3341   Enables CPU interrupts for the smallest window required to capture any
3342   pending interrupts.
3343
3344   Enables CPU interrupts for the smallest window required to capture any
3345   pending interrupts.
3346
3347 **/
3348 VOID
3349 EFIAPI
3350 EnableDisableInterrupts (
3351   VOID
3352   );
3353
3354 /**
3355   Retrieves the current CPU interrupt state.
3356
3357   Retrieves the current CPU interrupt state. Returns TRUE is interrupts are
3358   currently enabled. Otherwise returns FALSE.
3359
3360   @retval TRUE  CPU interrupts are enabled.
3361   @retval FALSE CPU interrupts are disabled.
3362
3363 **/
3364 BOOLEAN
3365 EFIAPI
3366 GetInterruptState (
3367   VOID
3368   );
3369
3370 /**
3371   Set the current CPU interrupt state.
3372
3373   Sets the current CPU interrupt state to the state specified by
3374   InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
3375   InterruptState is FALSE, then interrupts are disabled. InterruptState is
3376   returned.
3377
3378   @param  InterruptState  TRUE if interrupts should enabled. FALSE if
3379                           interrupts should be disabled.
3380
3381   @return InterruptState
3382
3383 **/
3384 BOOLEAN
3385 EFIAPI
3386 SetInterruptState (
3387   IN      BOOLEAN                   InterruptState
3388   );
3389
3390 /**
3391   Places the CPU in a sleep state until an interrupt is received.
3392
3393   Places the CPU in a sleep state until an interrupt is received. If interrupts
3394   are disabled prior to calling this function, then the CPU will be placed in a
3395   sleep state indefinitely.
3396
3397 **/
3398 VOID
3399 EFIAPI
3400 CpuSleep (
3401   VOID
3402   );
3403
3404 /**
3405   Requests CPU to pause for a short period of time.
3406
3407   Requests CPU to pause for a short period of time. Typically used in MP
3408   systems to prevent memory starvation while waiting for a spin lock.
3409
3410 **/
3411 VOID
3412 EFIAPI
3413 CpuPause (
3414   VOID
3415   );
3416
3417 /**
3418   Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU.
3419
3420   Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU.
3421
3422 **/
3423 VOID
3424 EFIAPI
3425 CpuFlushTlb (
3426   VOID
3427   );
3428
3429 /**
3430   Transfers control to a function starting with a new stack.
3431
3432   Transfers control to the function specified by EntryPoint using the new stack
3433   specified by NewStack and passing in the parameters specified by Context1 and
3434   Context2. Context1 and Context2 are optional and may be NULL. The function
3435   EntryPoint must never return.
3436
3437   If EntryPoint is NULL, then ASSERT().
3438   If NewStack is NULL, then ASSERT().
3439
3440   @param  EntryPoint  A pointer to function to call with the new stack.
3441   @param  Context1    A pointer to the context to pass into the EntryPoint
3442                       function.
3443   @param  Context2    A pointer to the context to pass into the EntryPoint
3444                       function.
3445   @param  NewStack    A pointer to the new stack to use for the EntryPoint
3446                       function.
3447
3448 **/
3449 VOID
3450 EFIAPI
3451 SwitchStack (
3452   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
3453   IN      VOID                      *Context1,  OPTIONAL
3454   IN      VOID                      *Context2,  OPTIONAL
3455   IN      VOID                      *NewStack
3456   );
3457
3458 /**
3459   Generates a breakpoint on the CPU.
3460
3461   Generates a breakpoint on the CPU. The breakpoint must be implemented such
3462   that code can resume normal execution after the breakpoint.
3463
3464 **/
3465 VOID
3466 EFIAPI
3467 CpuBreakpoint (
3468   VOID
3469   );
3470
3471 /**
3472   Executes an infinite loop.
3473
3474   Forces the CPU to execute an infinite loop. A debugger may be used to skip
3475   past the loop and the code that follows the loop must execute properly. This
3476   implies that the infinite loop must not cause the code that follow it to be
3477   optimized away.
3478
3479 **/
3480 VOID
3481 EFIAPI
3482 CpuDeadLoop (
3483   VOID
3484   );
3485
3486 //
3487 // IA32 and X64 Specific Functions
3488 //
3489 //
3490 // Byte packed structure for 16-bit Real Mode EFLAGS
3491 //
3492 typedef union {
3493   struct {
3494     UINT32  CF:1;           // Carry Flag
3495     UINT32  Reserved_0:1;   // Reserved
3496     UINT32  PF:1;           // Parity Flag
3497     UINT32  Reserved_1:1;   // Reserved
3498     UINT32  AF:1;           // Auxiliary Carry Flag
3499     UINT32  Reserved_2:1;   // Reserved
3500     UINT32  ZF:1;           // Zero Flag
3501     UINT32  SF:1;           // Sign Flag
3502     UINT32  TF:1;           // Trap Flag
3503     UINT32  IF:1;           // Interrupt Enable Flag
3504     UINT32  DF:1;           // Direction Flag
3505     UINT32  OF:1;           // Overflow Flag
3506     UINT32  IOPL:2;         // I/O Privilege Level
3507     UINT32  NT:1;           // Nested Task
3508     UINT32  Reserved_3:1;   // Reserved
3509   } Bits;
3510   UINT16    Uint16;
3511 } IA32_FLAGS16;
3512
3513 //
3514 // Byte packed structure for EFLAGS/RFLAGS
3515 // 32-bits on IA-32
3516 // 64-bits on X64.  The upper 32-bits on X64 are reserved
3517 //
3518 typedef union {
3519   struct {
3520     UINT32  CF:1;           // Carry Flag
3521     UINT32  Reserved_0:1;   // Reserved
3522     UINT32  PF:1;           // Parity Flag
3523     UINT32  Reserved_1:1;   // Reserved
3524     UINT32  AF:1;           // Auxiliary Carry Flag
3525     UINT32  Reserved_2:1;   // Reserved
3526     UINT32  ZF:1;           // Zero Flag
3527     UINT32  SF:1;           // Sign Flag
3528     UINT32  TF:1;           // Trap Flag
3529     UINT32  IF:1;           // Interrupt Enable Flag
3530     UINT32  DF:1;           // Direction Flag
3531     UINT32  OF:1;           // Overflow Flag
3532     UINT32  IOPL:2;         // I/O Privilege Level
3533     UINT32  NT:1;           // Nested Task
3534     UINT32  Reserved_3:1;   // Reserved
3535     UINT32  RF:1;           // Resume Flag
3536     UINT32  VM:1;           // Virtual 8086 Mode
3537     UINT32  AC:1;           // Alignment Check
3538     UINT32  VIF:1;          // Virtual Interrupt Flag
3539     UINT32  VIP:1;          // Virtual Interrupt Pending
3540     UINT32  ID:1;           // ID Flag
3541     UINT32  Reserved_4:10;  // Reserved
3542   } Bits;
3543   UINTN     UintN;
3544 } IA32_EFLAGS32;
3545
3546 //
3547 // Byte packed structure for Control Register 0 (CR0)
3548 // 32-bits on IA-32
3549 // 64-bits on X64.  The upper 32-bits on X64 are reserved
3550 //
3551 typedef union {
3552   struct {
3553     UINT32  PE:1;           // Protection Enable
3554     UINT32  MP:1;           // Monitor Coprocessor
3555     UINT32  EM:1;           // Emulation
3556     UINT32  TS:1;           // Task Switched
3557     UINT32  ET:1;           // Extension Type
3558     UINT32  NE:1;           // Numeric Error
3559     UINT32  Reserved_0:10;  // Reserved
3560     UINT32  WP:1;           // Write Protect
3561     UINT32  Reserved_1:1;   // Reserved
3562     UINT32  AM:1;           // Alignment Mask
3563     UINT32  Reserved_2:10;  // Reserved
3564     UINT32  NW:1;           // Mot Write-through
3565     UINT32  CD:1;           // Cache Disable
3566     UINT32  PG:1;           // Paging
3567   } Bits;
3568   UINTN     UintN;
3569 } IA32_CR0;
3570
3571 //
3572 // Byte packed structure for Control Register 4 (CR4)
3573 // 32-bits on IA-32
3574 // 64-bits on X64.  The upper 32-bits on X64 are reserved
3575 //
3576 typedef union {
3577   struct {
3578     UINT32  VME:1;          // Virtual-8086 Mode Extensions
3579     UINT32  PVI:1;          // Protected-Mode Virtual Interrupts
3580     UINT32  TSD:1;          // Time Stamp Disable
3581     UINT32  DE:1;           // Debugging Extensions
3582     UINT32  PSE:1;          // Page Size Extensions
3583     UINT32  PAE:1;          // Physical Address Extension
3584     UINT32  MCE:1;          // Machine Check Enable
3585     UINT32  PGE:1;          // Page Global Enable
3586     UINT32  PCE:1;          // Performance Monitoring Counter
3587                             // Enable
3588     UINT32  OSFXSR:1;       // Operating System Support for
3589                             // FXSAVE and FXRSTOR instructions
3590     UINT32  OSXMMEXCPT:1;   // Operating System Support for
3591                             // Unmasked SIMD Floating Point
3592                             // Exceptions
3593     UINT32  Reserved_0:2;   // Reserved
3594     UINT32  VMXE:1;         // VMX Enable
3595     UINT32  Reserved_1:18;  // Reseved
3596   } Bits;
3597   UINTN     UintN;
3598 } IA32_CR4;
3599
3600 //
3601 // Byte packed structure for an IDTR, GDTR, LDTR descriptor
3602 /// @bug  How to make this structure byte-packed in a compiler independent way?
3603 //
3604 #pragma pack (1)
3605 typedef struct {
3606   UINT16  Limit;
3607   UINTN   Base;
3608 } IA32_DESCRIPTOR;
3609 #pragma pack ()
3610
3611 #define IA32_IDT_GATE_TYPE_TASK          0x85
3612 #define IA32_IDT_GATE_TYPE_INTERRUPT_16  0x86
3613 #define IA32_IDT_GATE_TYPE_TRAP_16       0x87
3614 #define IA32_IDT_GATE_TYPE_INTERRUPT_32  0x8E
3615 #define IA32_IDT_GATE_TYPE_TRAP_32       0x8F
3616
3617 //
3618 // Byte packed structure for an Interrupt Gate Descriptor
3619 //
3620 typedef union {
3621   struct {
3622     UINT32  OffsetLow:16;   // Offset bits 15..0
3623     UINT32  Selector:16;    // Selector
3624     UINT32  Reserved_0:8;   // Reserved
3625     UINT32  GateType:8;     // Gate Type.  See #defines above
3626     UINT32  OffsetHigh:16;  // Offset bits 31..16
3627   } Bits;
3628   UINT64  Uint64;
3629 } IA32_IDT_GATE_DESCRIPTOR;
3630
3631 //
3632 // Byte packed structure for an FP/SSE/SSE2 context
3633 //
3634 typedef struct {
3635   UINT8  Buffer[512];
3636 } IA32_FX_BUFFER;
3637
3638 //
3639 // Structures for the 16-bit real mode thunks
3640 //
3641 typedef struct {
3642   UINT32                            Reserved1;
3643   UINT32                            Reserved2;
3644   UINT32                            Reserved3;
3645   UINT32                            Reserved4;
3646   UINT8                             BL;
3647   UINT8                             BH;
3648   UINT16                            Reserved5;
3649   UINT8                             DL;
3650   UINT8                             DH;
3651   UINT16                            Reserved6;
3652   UINT8                             CL;
3653   UINT8                             CH;
3654   UINT16                            Reserved7;
3655   UINT8                             AL;
3656   UINT8                             AH;
3657   UINT16                            Reserved8;
3658 } IA32_BYTE_REGS;
3659
3660 typedef struct {
3661   UINT16                            DI;
3662   UINT16                            Reserved1;
3663   UINT16                            SI;
3664   UINT16                            Reserved2;
3665   UINT16                            BP;
3666   UINT16                            Reserved3;
3667   UINT16                            SP;
3668   UINT16                            Reserved4;
3669   UINT16                            BX;
3670   UINT16                            Reserved5;
3671   UINT16                            DX;
3672   UINT16                            Reserved6;
3673   UINT16                            CX;
3674   UINT16                            Reserved7;
3675   UINT16                            AX;
3676   UINT16                            Reserved8;
3677 } IA32_WORD_REGS;
3678
3679 typedef struct {
3680   UINT32                            EDI;
3681   UINT32                            ESI;
3682   UINT32                            EBP;
3683   UINT32                            ESP;
3684   UINT32                            EBX;
3685   UINT32                            EDX;
3686   UINT32                            ECX;
3687   UINT32                            EAX;
3688   UINT16                            DS;
3689   UINT16                            ES;
3690   UINT16                            FS;
3691   UINT16                            GS;
3692   IA32_EFLAGS32                     EFLAGS;
3693   UINT32                            Eip;
3694   UINT16                            CS;
3695   UINT16                            SS;
3696 } IA32_DWORD_REGS;
3697
3698 typedef union {
3699   IA32_DWORD_REGS                   E;
3700   IA32_WORD_REGS                    X;
3701   IA32_BYTE_REGS                    H;
3702 } IA32_REGISTER_SET;
3703
3704 //
3705 // Byte packed structure for an 16-bit real mode thunks
3706 //
3707 typedef struct {
3708   IA32_REGISTER_SET                 *RealModeState;
3709   VOID                              *RealModeBuffer;
3710   UINT32                            RealModeBufferSize;
3711   UINT32                            ThunkAttributes;
3712 } THUNK_CONTEXT;
3713
3714 #define THUNK_ATTRIBUTE_BIG_REAL_MODE             0x00000001
3715 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15   0x00000002
3716 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
3717
3718 /**
3719   Retrieves CPUID information.
3720
3721   Executes the CPUID instruction with EAX set to the value specified by Index.
3722   This function always returns Index.
3723   If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
3724   If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
3725   If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
3726   If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
3727   This function is only available on IA-32 and X64.
3728
3729   @param  Index The 32-bit value to load into EAX prior to invoking the CPUID
3730                 instruction.
3731   @param  Eax   Pointer to the 32-bit EAX value returned by the CPUID
3732                 instruction. This is an optional parameter that may be NULL.