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