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