1) Added BIT0, BIT1, …, BIT63 to the Base Defines
[mirror_edk2.git] / 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;