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