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