1.Updated some functions header of BaseLib with new MWG spec
[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 @param Value A pointer to the 32-bit value for the compare exchange
2478 operation.
2479 @param CompareValue 32-bit value used in compare operation.
2480 @param ExchangeValue 32-bit value used in exchange operation.
2481
2482 @return The original *Value before exchange.
2483
2484 **/
2485 UINT32
2486 EFIAPI
2487 InterlockedCompareExchange32 (
2488 IN OUT UINT32 *Value,
2489 IN UINT32 CompareValue,
2490 IN UINT32 ExchangeValue
2491 );
2492
2493 /**
2494 Performs an atomic compare exchange operation on a 64-bit unsigned integer.
2495
2496 @param Value A pointer to the 64-bit value for the compare exchange
2497 operation.
2498 @param CompareValue 64-bit value used in compare operation.
2499 @param ExchangeValue 64-bit value used in exchange operation.
2500
2501 @return The original *Value before exchange.
2502
2503 **/
2504 UINT64
2505 EFIAPI
2506 InterlockedCompareExchange64 (
2507 IN OUT UINT64 *Value,
2508 IN UINT64 CompareValue,
2509 IN UINT64 ExchangeValue
2510 );
2511
2512 /**
2513 Performs an atomic compare exchange operation on a pointer value.
2514
2515 Performs an atomic compare exchange operation on the pointer value specified
2516 by Value. If Value is equal to CompareValue, then Value is set to
2517 ExchangeValue and CompareValue is returned. If Value is not equal to
2518 CompareValue, then Value is returned. The compare exchange operation must be
2519 performed using MP safe mechanisms.
2520
2521 If Value is NULL, then ASSERT().
2522
2523 @param Value A pointer to the pointer value for the compare exchange
2524 operation.
2525 @param CompareValue Pointer value used in compare operation.
2526 @param ExchangeValue Pointer value used in exchange operation.
2527
2528 **/
2529 VOID *
2530 EFIAPI
2531 InterlockedCompareExchangePointer (
2532 IN OUT VOID **Value,
2533 IN VOID *CompareValue,
2534 IN VOID *ExchangeValue
2535 );
2536
2537 //
2538 // Base Library CPU Functions
2539 //
2540 typedef
2541 VOID
2542 (EFIAPI *SWITCH_STACK_ENTRY_POINT) (
2543 IN VOID *Context1, OPTIONAL
2544 IN VOID *Context2 OPTIONAL
2545 );
2546
2547 /**
2548 Used to serialize load and store operations.
2549
2550 All loads and stores that proceed calls to this function are guaranteed to be
2551 globally visible when this function returns.
2552
2553 **/
2554 VOID
2555 EFIAPI
2556 MemoryFence (
2557 VOID
2558 );
2559
2560 /**
2561 Saves the current CPU context that can be restored with a call to LongJump()
2562 and returns 0.
2563
2564 Saves the current CPU context in the buffer specified by JumpBuffer and
2565 returns 0. The initial call to SetJump() must always return 0. Subsequent
2566 calls to LongJump() cause a non-zero value to be returned by SetJump().
2567
2568 If JumpBuffer is NULL, then ASSERT().
2569
2570 @param JumpBuffer A pointer to CPU context buffer.
2571
2572 @retval 0 Indicates a return from SetJump().
2573
2574 **/
2575 UINTN
2576 EFIAPI
2577 SetJump (
2578 OUT BASE_LIBRARY_JUMP_BUFFER *JumpBuffer
2579 );
2580
2581 /**
2582 Restores the CPU context that was saved with SetJump().
2583
2584 Restores the CPU context from the buffer specified by JumpBuffer. This
2585 function never returns to the caller. Instead is resumes execution based on
2586 the state of JumpBuffer.
2587
2588 If JumpBuffer is NULL, then ASSERT().
2589 If Value is 0, then ASSERT().
2590
2591 @param JumpBuffer A pointer to CPU context buffer.
2592 @param Value The value to return when the SetJump() context is
2593 restored and must be non-zero.
2594
2595 **/
2596 VOID
2597 EFIAPI
2598 LongJump (
2599 IN BASE_LIBRARY_JUMP_BUFFER *JumpBuffer,
2600 IN UINTN Value
2601 );
2602
2603 /**
2604 Enables CPU interrupts.
2605
2606 Enables CPU interrupts.
2607
2608 **/
2609 VOID
2610 EFIAPI
2611 EnableInterrupts (
2612 VOID
2613 );
2614
2615 /**
2616 Disables CPU interrupts.
2617
2618 Disables CPU interrupts.
2619
2620 **/
2621 VOID
2622 EFIAPI
2623 DisableInterrupts (
2624 VOID
2625 );
2626
2627 /**
2628 Disables CPU interrupts and returns the interrupt state prior to the disable
2629 operation.
2630
2631 Disables CPU interrupts and returns the interrupt state prior to the disable
2632 operation.
2633
2634 @retval TRUE CPU interrupts were enabled on entry to this call.
2635 @retval FALSE CPU interrupts were disabled on entry to this call.
2636
2637 **/
2638 BOOLEAN
2639 EFIAPI
2640 SaveAndDisableInterrupts (
2641 VOID
2642 );
2643
2644 /**
2645 Enables CPU interrupts for the smallest window required to capture any
2646 pending interrupts.
2647
2648 Enables CPU interrupts for the smallest window required to capture any
2649 pending interrupts.
2650
2651 **/
2652 VOID
2653 EFIAPI
2654 EnableDisableInterrupts (
2655 VOID
2656 );
2657
2658 /**
2659 Retrieves the current CPU interrupt state.
2660
2661 Retrieves the current CPU interrupt state. Returns TRUE is interrupts are
2662 currently enabled. Otherwise returns FALSE.
2663
2664 @retval TRUE CPU interrupts are enabled.
2665 @retval FALSE CPU interrupts are disabled.
2666
2667 **/
2668 BOOLEAN
2669 EFIAPI
2670 GetInterruptState (
2671 VOID
2672 );
2673
2674 /**
2675 Set the current CPU interrupt state.
2676
2677 Sets the current CPU interrupt state to the state specified by
2678 InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
2679 InterruptState is FALSE, then interrupts are disabled. InterruptState is
2680 returned.
2681
2682 @param InterruptState TRUE if interrupts should enabled. FALSE if
2683 interrupts should be disabled.
2684
2685 @return InterruptState
2686
2687 **/
2688 BOOLEAN
2689 EFIAPI
2690 SetInterruptState (
2691 IN BOOLEAN InterruptState
2692 );
2693
2694 /**
2695 Places the CPU in a sleep state until an interrupt is received.
2696
2697 Places the CPU in a sleep state until an interrupt is received. If interrupts
2698 are disabled prior to calling this function, then the CPU will be placed in a
2699 sleep state indefinitely.
2700
2701 **/
2702 VOID
2703 EFIAPI
2704 CpuSleep (
2705 VOID
2706 );
2707
2708 /**
2709 Requests CPU to pause for a short period of time.
2710
2711 Requests CPU to pause for a short period of time. Typically used in MP
2712 systems to prevent memory starvation while waiting for a spin lock.
2713
2714 **/
2715 VOID
2716 EFIAPI
2717 CpuPause (
2718 VOID
2719 );
2720
2721 /**
2722 Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU.
2723
2724 Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU.
2725
2726 **/
2727 VOID
2728 EFIAPI
2729 CpuFlushTlb (
2730 VOID
2731 );
2732
2733 /**
2734 Transfers control to a function starting with a new stack.
2735
2736 Transfers control to the function specified by EntryPoint using the new stack
2737 specified by NewStack and passing in the parameters specified by Context1 and
2738 Context2. Context1 and Context2 are optional and may be NULL. The function
2739 EntryPoint must never return.
2740
2741 If EntryPoint is NULL, then ASSERT().
2742 If NewStack is NULL, then ASSERT().
2743
2744 @param EntryPoint A pointer to function to call with the new stack.
2745 @param Context1 A pointer to the context to pass into the EntryPoint
2746 function.
2747 @param Context2 A pointer to the context to pass into the EntryPoint
2748 function.
2749 @param NewStack A pointer to the new stack to use for the EntryPoint
2750 function.
2751
2752 **/
2753 VOID
2754 EFIAPI
2755 SwitchStack (
2756 IN SWITCH_STACK_ENTRY_POINT EntryPoint,
2757 IN VOID *Context1, OPTIONAL
2758 IN VOID *Context2, OPTIONAL
2759 IN VOID *NewStack
2760 );
2761
2762 /**
2763 Generates a breakpoint on the CPU.
2764
2765 Generates a breakpoint on the CPU. The breakpoint must be implemented such
2766 that code can resume normal execution after the breakpoint.
2767
2768 **/
2769 VOID
2770 EFIAPI
2771 CpuBreakpoint (
2772 VOID
2773 );
2774
2775 /**
2776 Executes an infinite loop.
2777
2778 Forces the CPU to execute an infinite loop. A debugger may be used to skip
2779 past the loop and the code that follows the loop must execute properly. This
2780 implies that the infinite loop must not cause the code that follow it to be
2781 optimized away.
2782
2783 **/
2784 VOID
2785 EFIAPI
2786 CpuDeadLoop (
2787 VOID
2788 );
2789
2790 //
2791 // IA32 and X64 Specific Functions
2792 //
2793 //
2794 // Byte packed structure for 16-bit Real Mode EFLAGS
2795 //
2796 typedef union {
2797 struct {
2798 UINT32 CF:1; // Carry Flag
2799 UINT32 Reserved_0:1; // Reserved
2800 UINT32 PF:1; // Parity Flag
2801 UINT32 Reserved_1:1; // Reserved
2802 UINT32 AF:1; // Auxiliary Carry Flag
2803 UINT32 Reserved_2:1; // Reserved
2804 UINT32 ZF:1; // Zero Flag
2805 UINT32 SF:1; // Sign Flag
2806 UINT32 TF:1; // Trap Flag
2807 UINT32 IF:1; // Interrupt Enable Flag
2808 UINT32 DF:1; // Direction Flag
2809 UINT32 OF:1; // Overflow Flag
2810 UINT32 IOPL:2; // I/O Privilege Level
2811 UINT32 NT:1; // Nested Task
2812 UINT32 Reserved_3:1; // Reserved
2813 } Bits;
2814 UINT16 Uint16;
2815 } IA32_FLAGS16;
2816
2817 //
2818 // Byte packed structure for EFLAGS/RFLAGS
2819 // 32-bits on IA-32
2820 // 64-bits on X64. The upper 32-bits on X64 are reserved
2821 //
2822 typedef union {
2823 struct {
2824 UINT32 CF:1; // Carry Flag
2825 UINT32 Reserved_0:1; // Reserved
2826 UINT32 PF:1; // Parity Flag
2827 UINT32 Reserved_1:1; // Reserved
2828 UINT32 AF:1; // Auxiliary Carry Flag
2829 UINT32 Reserved_2:1; // Reserved
2830 UINT32 ZF:1; // Zero Flag
2831 UINT32 SF:1; // Sign Flag
2832 UINT32 TF:1; // Trap Flag
2833 UINT32 IF:1; // Interrupt Enable Flag
2834 UINT32 DF:1; // Direction Flag
2835 UINT32 OF:1; // Overflow Flag
2836 UINT32 IOPL:2; // I/O Privilege Level
2837 UINT32 NT:1; // Nested Task
2838 UINT32 Reserved_3:1; // Reserved
2839 UINT32 RF:1; // Resume Flag
2840 UINT32 VM:1; // Virtual 8086 Mode
2841 UINT32 AC:1; // Alignment Check
2842 UINT32 VIF:1; // Virtual Interrupt Flag
2843 UINT32 VIP:1; // Virtual Interrupt Pending
2844 UINT32 ID:1; // ID Flag
2845 UINT32 Reserved_4:10; // Reserved
2846 } Bits;
2847 UINTN UintN;
2848 } IA32_EFLAGS32;
2849
2850 //
2851 // Byte packed structure for Control Register 0 (CR0)
2852 // 32-bits on IA-32
2853 // 64-bits on X64. The upper 32-bits on X64 are reserved
2854 //
2855 typedef union {
2856 struct {
2857 UINT32 PE:1; // Protection Enable
2858 UINT32 MP:1; // Monitor Coprocessor
2859 UINT32 EM:1; // Emulation
2860 UINT32 TS:1; // Task Switched
2861 UINT32 ET:1; // Extension Type
2862 UINT32 NE:1; // Numeric Error
2863 UINT32 Reserved_0:10; // Reserved
2864 UINT32 WP:1; // Write Protect
2865 UINT32 Reserved_1:1; // Reserved
2866 UINT32 AM:1; // Alignment Mask
2867 UINT32 Reserved_2:10; // Reserved
2868 UINT32 NW:1; // Mot Write-through
2869 UINT32 CD:1; // Cache Disable
2870 UINT32 PG:1; // Paging
2871 } Bits;
2872 UINTN UintN;
2873 } IA32_CR0;
2874
2875 //
2876 // Byte packed structure for Control Register 4 (CR4)
2877 // 32-bits on IA-32
2878 // 64-bits on X64. The upper 32-bits on X64 are reserved
2879 //
2880 typedef union {
2881 struct {
2882 UINT32 VME:1; // Virtual-8086 Mode Extensions
2883 UINT32 PVI:1; // Protected-Mode Virtual Interrupts
2884 UINT32 TSD:1; // Time Stamp Disable
2885 UINT32 DE:1; // Debugging Extensions
2886 UINT32 PSE:1; // Page Size Extensions
2887 UINT32 PAE:1; // Physical Address Extension
2888 UINT32 MCE:1; // Machine Check Enable
2889 UINT32 PGE:1; // Page Global Enable
2890 UINT32 PCE:1; // Performance Monitoring Counter
2891 // Enable
2892 UINT32 OSFXSR:1; // Operating System Support for
2893 // FXSAVE and FXRSTOR instructions
2894 UINT32 OSXMMEXCPT:1; // Operating System Support for
2895 // Unmasked SIMD Floating Point
2896 // Exceptions
2897 UINT32 Reserved_0:2; // Reserved
2898 UINT32 VMXE:1; // VMX Enable
2899 UINT32 Reserved_1:18; // Reseved
2900 } Bits;
2901 UINTN UintN;
2902 } IA32_CR4;
2903
2904 //
2905 // Byte packed structure for an IDTR, GDTR, LDTR descriptor
2906 /// @bug How to make this structure byte-packed in a compiler independent way?
2907 //
2908 typedef struct {
2909 UINT16 Limit;
2910 UINTN Base;
2911 } IA32_DESCRIPTOR;
2912
2913 #define IA32_IDT_GATE_TYPE_TASK 0x85
2914 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86
2915 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87
2916 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E
2917 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F
2918
2919 //
2920 // Byte packed structure for an Interrupt Gate Descriptor
2921 //
2922 typedef union {
2923 struct {
2924 UINT32 OffsetLow:16; // Offset bits 15..0
2925 UINT32 Selector:16; // Selector
2926 UINT32 Reserved_0:8; // Reserved
2927 UINT32 GateType:8; // Gate Type. See #defines above
2928 UINT32 OffsetHigh:16; // Offset bits 31..16
2929 } Bits;
2930 UINT64 Uint64;
2931 } IA32_IDT_GATE_DESCRIPTOR;
2932
2933 //
2934 // Byte packed structure for an FP/SSE/SSE2 context
2935 //
2936 typedef struct {
2937 UINT8 Buffer[512];
2938 } IA32_FX_BUFFER;
2939
2940 //
2941 // Structures for the 16-bit real mode thunks
2942 //
2943 typedef struct {
2944 UINT32 Reserved1;
2945 UINT32 Reserved2;
2946 UINT32 Reserved3;
2947 UINT32 Reserved4;
2948 UINT8 BL;
2949 UINT8 BH;
2950 UINT16 Reserved5;
2951 UINT8 DL;
2952 UINT8 DH;
2953 UINT16 Reserved6;
2954 UINT8 CL;
2955 UINT8 CH;
2956 UINT16 Reserved7;
2957 UINT8 AL;
2958 UINT8 AH;
2959 UINT16 Reserved8;
2960 } IA32_BYTE_REGS;
2961
2962 typedef struct {
2963 UINT16 DI;
2964 UINT16 Reserved1;
2965 UINT16 SI;
2966 UINT16 Reserved2;
2967 UINT16 BP;
2968 UINT16 Reserved3;
2969 UINT16 SP;
2970 UINT16 Reserved4;
2971 UINT16 BX;
2972 UINT16 Reserved5;
2973 UINT16 DX;
2974 UINT16 Reserved6;
2975 UINT16 CX;
2976 UINT16 Reserved7;
2977 UINT16 AX;
2978 UINT16 Reserved8;
2979 } IA32_WORD_REGS;
2980
2981 typedef struct {
2982 UINT32 EDI;
2983 UINT32 ESI;
2984 UINT32 EBP;
2985 UINT32 ESP;
2986 UINT32 EBX;
2987 UINT32 EDX;
2988 UINT32 ECX;
2989 UINT32 EAX;
2990 UINT16 DS;
2991 UINT16 ES;
2992 UINT16 FS;
2993 UINT16 GS;
2994 IA32_EFLAGS32 EFLAGS;
2995 UINT32 Eip;
2996 UINT16 CS;
2997 UINT16 SS;
2998 } IA32_DWORD_REGS;
2999
3000 typedef union {
3001 IA32_DWORD_REGS E;
3002 IA32_WORD_REGS X;
3003 IA32_BYTE_REGS H;
3004 } IA32_REGISTER_SET;
3005
3006 //
3007 // Byte packed structure for an 16-bit real mode thunks
3008 //
3009 typedef struct {
3010 IA32_REGISTER_SET *RealModeState;
3011 VOID *RealModeBuffer;
3012 UINT32 RealModeBufferSize;
3013 UINT32 ThunkAttributes;
3014 } THUNK_CONTEXT;
3015
3016 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001
3017 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002
3018 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
3019
3020 /**
3021 Retrieves CPUID information.
3022
3023 Executes the CPUID instruction with EAX set to the value specified by Index.
3024 This function always returns Index.
3025 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
3026 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
3027 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
3028 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
3029 This function is only available on IA-32 and X64.
3030
3031 @param Index The 32-bit value to load into EAX prior to invoking the CPUID
3032 instruction.
3033 @param Eax Pointer to the 32-bit EAX value returned by the CPUID
3034 instruction. This is an optional parameter that may be NULL.
3035 @param Ebx Pointer to the 32-bit EBX value returned by the CPUID
3036 instruction. This is an optional parameter that may be NULL.
3037 @param Ecx Pointer to the 32-bit ECX value returned by the CPUID
3038 instruction. This is an optional parameter that may be NULL.
3039 @param Edx Pointer to the 32-bit EDX value returned by the CPUID
3040 instruction. This is an optional parameter that may be NULL.
3041
3042 @return Index
3043
3044 **/
3045 UINT32
3046 EFIAPI
3047 AsmCpuid (
3048 IN UINT32 Index,
3049 OUT UINT32 *Eax, OPTIONAL
3050 OUT UINT32 *Ebx, OPTIONAL
3051 OUT UINT32 *Ecx, OPTIONAL
3052 OUT UINT32 *Edx OPTIONAL
3053 );
3054
3055 /**
3056 Retrieves CPUID information using an extended leaf identifier.
3057
3058 Executes the CPUID instruction with EAX set to the value specified by Index
3059 and ECX set to the value specified by SubIndex. This function always returns
3060 Index. This function is only available on IA-32 and x64.
3061
3062 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
3063 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
3064 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
3065 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
3066
3067 @param Index The 32-bit value to load into EAX prior to invoking the
3068 CPUID instruction.
3069 @param SubIndex The 32-bit value to load into ECX prior to invoking the
3070 CPUID instruction.
3071 @param Eax Pointer to the 32-bit EAX value returned by the CPUID
3072 instruction. This is an optional parameter that may be
3073 NULL.
3074 @param Ebx Pointer to the 32-bit EBX value returned by the CPUID
3075 instruction. This is an optional parameter that may be
3076 NULL.
3077 @param Ecx Pointer to the 32-bit ECX value returned by the CPUID
3078 instruction. This is an optional parameter that may be
3079 NULL.
3080 @param Edx Pointer to the 32-bit EDX value returned by the CPUID
3081 instruction. This is an optional parameter that may be
3082 NULL.
3083
3084 @return Index
3085
3086 **/
3087 UINT32
3088 EFIAPI
3089 AsmCpuidEx (
3090 IN UINT32 Index,
3091 IN UINT32 SubIndex,
3092 OUT UINT32 *Eax, OPTIONAL
3093 OUT UINT32 *Ebx, OPTIONAL
3094 OUT UINT32 *Ecx, OPTIONAL
3095 OUT UINT32 *Edx OPTIONAL
3096 );
3097
3098 /**
3099 Returns the lower 32-bits of a Machine Specific Register(MSR).
3100
3101 Reads and returns the lower 32-bits of the MSR specified by Index.
3102 No parameter checking is performed on Index, and some Index values may cause
3103 CPU exceptions. The caller must either guarantee that Index is valid, or the
3104 caller must set up exception handlers to catch the exceptions. This function
3105 is only available on IA-32 and X64.
3106
3107 @param Index The 32-bit MSR index to read.
3108
3109 @return The lower 32 bits of the MSR identified by Index.
3110
3111 **/
3112 UINT32
3113 EFIAPI
3114 AsmReadMsr32 (
3115 IN UINT32 Index
3116 );
3117
3118 /**
3119 Zero-extend a 32-bit value and writes it to a Machine Specific Register(MSR).
3120
3121 Writes the 32-bit value specified by Value to the MSR specified by Index. The
3122 upper 32-bits of the MSR write are set to zero. The 32-bit value written to
3123 the MSR is returned. No parameter checking is performed on Index or Value,
3124 and some of these may cause CPU exceptions. The caller must either guarantee
3125 that Index and Value are valid, or the caller must establish proper exception
3126 handlers. This function is only available on IA-32 and X64.
3127
3128 @param Index The 32-bit MSR index to write.
3129 @param Value The 32-bit value to write to the MSR.
3130
3131 @return Value
3132
3133 **/
3134 UINT32
3135 EFIAPI
3136 AsmWriteMsr32 (
3137 IN UINT32 Index,
3138 IN UINT32 Value
3139 );
3140
3141 /**
3142 Reads a 64-bit MSR, performs a bitwise inclusive OR on the lower 32-bits, and
3143 writes the result back to the 64-bit MSR.
3144
3145 Reads the 64-bit MSR specified by Index, performs a bitwise inclusive OR
3146 between the lower 32-bits of the read result and the value specified by
3147 OrData, and writes the result to the 64-bit MSR specified by Index. The lower
3148 32-bits of the value written to the MSR is returned. No parameter checking is
3149 performed on Index or OrData, and some of these may cause CPU exceptions. The
3150 caller must either guarantee that Index and OrData are valid, or the caller
3151 must establish proper exception handlers. This function is only available on
3152 IA-32 and X64.
3153
3154 @param Index The 32-bit MSR index to write.
3155 @param OrData The value to OR with the read value from the MSR.
3156
3157 @return The lower 32-bit value written to the MSR.
3158
3159 **/
3160 UINT32
3161 EFIAPI
3162 AsmMsrOr32 (
3163 IN UINT32 Index,
3164 IN UINT32 OrData
3165 );
3166
3167 /**
3168 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
3169 the result back to the 64-bit MSR.
3170
3171 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
3172 lower 32-bits of the read result and the value specified by AndData, and
3173 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
3174 the value written to the MSR is returned. No parameter checking is performed
3175 on Index or AndData, and some of these may cause CPU exceptions. The caller
3176 must either guarantee that Index and AndData are valid, or the caller must
3177 establish proper exception handlers. This function is only available on IA-32
3178 and X64.
3179
3180 @param Index The 32-bit MSR index to write.
3181 @param AndData The value to AND with the read value from the MSR.
3182
3183 @return The lower 32-bit value written to the MSR.
3184
3185 **/
3186 UINT32
3187 EFIAPI
3188 AsmMsrAnd32 (
3189 IN UINT32 Index,
3190 IN UINT32 AndData
3191 );
3192
3193 /**
3194 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise inclusive OR
3195 on the lower 32-bits, and writes the result back to the 64-bit MSR.
3196
3197 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
3198 lower 32-bits of the read result and the value specified by AndData
3199 preserving the upper 32-bits, performs a bitwise inclusive OR between the
3200 result of the AND operation and the value specified by OrData, and writes the
3201 result to the 64-bit MSR specified by Address. The lower 32-bits of the value
3202 written to the MSR is returned. No parameter checking is performed on Index,
3203 AndData, or OrData, and some of these may cause CPU exceptions. The caller
3204 must either guarantee that Index, AndData, and OrData are valid, or the
3205 caller must establish proper exception handlers. This function is only
3206 available on IA-32 and X64.
3207
3208 @param Index The 32-bit MSR index to write.
3209 @param AndData The value to AND with the read value from the MSR.
3210 @param OrData The value to OR with the result of the AND operation.
3211
3212 @return The lower 32-bit value written to the MSR.
3213
3214 **/
3215 UINT32
3216 EFIAPI
3217 AsmMsrAndThenOr32 (
3218 IN UINT32 Index,
3219 IN UINT32 AndData,
3220 IN UINT32 OrData
3221 );
3222
3223 /**
3224 Reads a bit field of an MSR.
3225
3226 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
3227 specified by the StartBit and the EndBit. The value of the bit field is
3228 returned. The caller must either guarantee that Index is valid, or the caller
3229 must set up exception handlers to catch the exceptions. This function is only
3230 available on IA-32 and X64.
3231
3232 If StartBit is greater than 31, then ASSERT().
3233 If EndBit is greater than 31, then ASSERT().
3234 If EndBit is less than StartBit, then ASSERT().
3235
3236 @param Index The 32-bit MSR index to read.
3237 @param StartBit The ordinal of the least significant bit in the bit field.
3238 Range 0..31.
3239 @param EndBit The ordinal of the most significant bit in the bit field.
3240 Range 0..31.
3241
3242 @return The bit field read from the MSR.
3243
3244 **/
3245 UINT32
3246 EFIAPI
3247 AsmMsrBitFieldRead32 (
3248 IN UINT32 Index,
3249 IN UINTN StartBit,
3250 IN UINTN EndBit
3251 );
3252
3253 /**
3254 Writes a bit field to an MSR.
3255
3256 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
3257 field is specified by the StartBit and the EndBit. All other bits in the
3258 destination MSR are preserved. The lower 32-bits of the MSR written is
3259 returned. Extra left bits in Value are stripped. The caller must either
3260 guarantee that Index and the data written is valid, or the caller must set up
3261 exception handlers to catch the exceptions. This function is only available
3262 on IA-32 and X64.
3263
3264 If StartBit is greater than 31, then ASSERT().
3265 If EndBit is greater than 31, then ASSERT().
3266 If EndBit is less than StartBit, then ASSERT().
3267
3268 @param Index The 32-bit MSR index to write.
3269 @param StartBit The ordinal of the least significant bit in the bit field.
3270 Range 0..31.
3271 @param EndBit The ordinal of the most significant bit in the bit field.
3272 Range 0..31.
3273 @param Value New value of the bit field.
3274
3275 @return The lower 32-bit of the value written to the MSR.
3276
3277 **/
3278 UINT32
3279 EFIAPI
3280 AsmMsrBitFieldWrite32 (
3281 IN UINT32 Index,
3282 IN UINTN StartBit,
3283 IN UINTN EndBit,
3284 IN UINT32 Value
3285 );
3286
3287 /**
3288 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
3289 result back to the bit field in the 64-bit MSR.
3290
3291 Reads the 64-bit MSR specified by Index, performs a bitwise inclusive OR
3292 between the read result and the value specified by OrData, and writes the
3293 result to the 64-bit MSR specified by Index. The lower 32-bits of the value
3294 written to the MSR are returned. Extra left bits in OrData are stripped. The
3295 caller must either guarantee that Index and the data written is valid, or
3296 the caller must set up exception handlers to catch the exceptions. This
3297 function is only available on IA-32 and X64.
3298
3299 If StartBit is greater than 31, then ASSERT().
3300 If EndBit is greater than 31, then ASSERT().
3301 If EndBit is less than StartBit, then ASSERT().
3302
3303 @param Index The 32-bit MSR index to write.
3304 @param StartBit The ordinal of the least significant bit in the bit field.
3305 Range 0..31.
3306 @param EndBit The ordinal of the most significant bit in the bit field.
3307 Range 0..31.
3308 @param OrData The value to OR with the read value from the MSR.
3309
3310 @return The lower 32-bit of the value written to the MSR.
3311
3312 **/
3313 UINT32
3314 EFIAPI
3315 AsmMsrBitFieldOr32 (
3316 IN UINT32 Index,
3317 IN UINTN StartBit,
3318 IN UINTN EndBit,
3319 IN UINT32 OrData
3320 );
3321
3322 /**
3323 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
3324 result back to the bit field in the 64-bit MSR.
3325
3326 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
3327 read result and the value specified by AndData, and writes the result to the
3328 64-bit MSR specified by Index. The lower 32-bits of the value written to the
3329 MSR are returned. Extra left bits in AndData are stripped. The caller must
3330 either guarantee that Index and the data written is valid, or the caller must
3331 set up exception handlers to catch the exceptions. This function is only
3332 available on IA-32 and X64.
3333
3334 If StartBit is greater than 31, then ASSERT().
3335 If EndBit is greater than 31, then ASSERT().
3336 If EndBit is less than StartBit, then ASSERT().
3337
3338 @param Index The 32-bit MSR index to write.
3339 @param StartBit The ordinal of the least significant bit in the bit field.
3340 Range 0..31.
3341 @param EndBit The ordinal of the most significant bit in the bit field.
3342 Range 0..31.
3343 @param AndData The value to AND with the read value from the MSR.
3344
3345 @return The lower 32-bit of the value written to the MSR.
3346
3347 **/
3348 UINT32
3349 EFIAPI
3350 AsmMsrBitFieldAnd32 (
3351 IN UINT32 Index,
3352 IN UINTN StartBit,
3353 IN UINTN EndBit,
3354 IN UINT32 AndData
3355 );
3356
3357 /**
3358 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
3359 bitwise inclusive OR, and writes the result back to the bit field in the
3360 64-bit MSR.
3361
3362 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
3363 bitwise inclusive OR between the read result and the value specified by
3364 AndData, and writes the result to the 64-bit MSR specified by Index. The
3365 lower 32-bits of the value written to the MSR are returned. Extra left bits
3366 in both AndData and OrData are stripped. The caller must either guarantee
3367 that Index and the data written is valid, or the caller must set up exception
3368 handlers to catch the exceptions. This function is only available on IA-32
3369 and X64.
3370
3371 If StartBit is greater than 31, then ASSERT().
3372 If EndBit is greater than 31, then ASSERT().
3373 If EndBit is less than StartBit, then ASSERT().
3374
3375 @param Index The 32-bit MSR index to write.
3376 @param StartBit The ordinal of the least significant bit in the bit field.
3377 Range 0..31.
3378 @param EndBit The ordinal of the most significant bit in the bit field.
3379 Range 0..31.
3380 @param AndData The value to AND with the read value from the MSR.
3381 @param OrData The value to OR with the result of the AND operation.
3382
3383 @return The lower 32-bit of the value written to the MSR.
3384
3385 **/
3386 UINT32
3387 EFIAPI
3388 AsmMsrBitFieldAndThenOr32 (
3389 IN UINT32 Index,
3390 IN UINTN StartBit,
3391 IN UINTN EndBit,
3392 IN UINT32 AndData,
3393 IN UINT32 OrData
3394 );
3395
3396 /**
3397 Returns a 64-bit Machine Specific Register(MSR).
3398
3399 Reads and returns the 64-bit MSR specified by Index. No parameter checking is
3400 performed on Index, and some Index values may cause CPU exceptions. The
3401 caller must either guarantee that Index is valid, or the caller must set up
3402 exception handlers to catch the exceptions. This function is only available
3403 on IA-32 and X64.
3404
3405 @param Index The 32-bit MSR index to read.
3406
3407 @return The value of the MSR identified by Index.
3408
3409 **/
3410 UINT64
3411 EFIAPI
3412 AsmReadMsr64 (
3413 IN UINT32 Index
3414 );
3415
3416 /**
3417 Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
3418 value.
3419
3420 Writes the 64-bit value specified by Value to the MSR specified by Index. The
3421 64-bit value written to the MSR is returned. No parameter checking is
3422 performed on Index or Value, and some of these may cause CPU exceptions. The
3423 caller must either guarantee that Index and Value are valid, or the caller
3424 must establish proper exception handlers. This function is only available on
3425 IA-32 and X64.
3426
3427 @param Index The 32-bit MSR index to write.
3428 @param Value The 64-bit value to write to the MSR.
3429
3430 @return Value
3431
3432 **/
3433 UINT64
3434 EFIAPI
3435 AsmWriteMsr64 (
3436 IN UINT32 Index,
3437 IN UINT64 Value
3438 );
3439
3440 /**
3441 Reads a 64-bit MSR, performs a bitwise inclusive OR, and writes the result
3442 back to the 64-bit MSR.
3443
3444 Reads the 64-bit MSR specified by Index, performs a bitwise inclusive OR
3445 between the read result and the value specified by OrData, and writes the
3446 result to the 64-bit MSR specified by Index. The value written to the MSR is
3447 returned. No parameter checking is performed on Index or OrData, and some of
3448 these may cause CPU exceptions. The caller must either guarantee that Index
3449 and OrData are valid, or the caller must establish proper exception handlers.
3450 This function is only available on IA-32 and X64.
3451
3452 @param Index The 32-bit MSR index to write.
3453 @param OrData The value to OR with the read value from the MSR.
3454
3455 @return The value written back to the MSR.
3456
3457 **/
3458 UINT64
3459 EFIAPI
3460 AsmMsrOr64 (
3461 IN UINT32 Index,
3462 IN UINT64 OrData
3463 );
3464
3465 /**
3466 Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
3467 64-bit MSR.
3468
3469 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
3470 read result and the value specified by OrData, and writes the result to the
3471 64-bit MSR specified by Index. The value written to the MSR is returned. No
3472 parameter checking is performed on Index or OrData, and some of these may
3473 cause CPU exceptions. The caller must either guarantee that Index and OrData
3474 are valid, or the caller must establish proper exception handlers. This
3475 function is only available on IA-32 and X64.
3476
3477 @param Index The 32-bit MSR index to write.
3478 @param AndData The value to AND with the read value from the MSR.
3479
3480 @return The value written back to the MSR.
3481
3482 **/
3483 UINT64
3484 EFIAPI
3485 AsmMsrAnd64 (
3486 IN UINT32 Index,
3487 IN UINT64 AndData
3488 );
3489
3490 /**
3491 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise inclusive
3492 OR, and writes the result back to the 64-bit MSR.
3493
3494 Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
3495 result and the value specified by AndData, performs a bitwise inclusive OR
3496 between the result of the AND operation and the value specified by OrData,
3497 and writes the result to the 64-bit MSR specified by Index. The value written
3498 to the MSR is returned. No parameter checking is performed on Index, AndData,
3499 or OrData, and some of these may cause CPU exceptions. The caller must either
3500 guarantee that Index, AndData, and OrData are valid, or the caller must
3501 establish proper exception handlers. This function is only available on IA-32
3502 and X64.
3503
3504 @param Index The 32-bit MSR index to write.
3505 @param AndData The value to AND with the read value from the MSR.
3506 @param OrData The value to OR with the result of the AND operation.
3507
3508 @return The value written back to the MSR.
3509
3510 **/
3511 UINT64
3512 EFIAPI
3513 AsmMsrAndThenOr64 (
3514 IN UINT32 Index,
3515 IN UINT64 AndData,
3516 IN UINT64 OrData
3517 );
3518
3519 /**
3520 Reads a bit field of an MSR.
3521
3522 Reads the bit field in the 64-bit MSR. The bit field is specified by the
3523 StartBit and the EndBit. The value of the bit field is returned. The caller
3524 must either guarantee that Index is valid, or the caller must set up
3525 exception handlers to catch the exceptions. This function is only available
3526 on IA-32 and X64.
3527
3528 If StartBit is greater than 63, then ASSERT().
3529 If EndBit is greater than 63, then ASSERT().
3530 If EndBit is less than StartBit, then ASSERT().
3531
3532 @param Index The 32-bit MSR index to read.
3533 @param StartBit The ordinal of the least significant bit in the bit field.
3534 Range 0..63.
3535 @param EndBit The ordinal of the most significant bit in the bit field.
3536 Range 0..63.
3537
3538 @return The value read from the MSR.
3539
3540 **/
3541 UINT64
3542 EFIAPI
3543 AsmMsrBitFieldRead64 (
3544 IN UINT32 Index,
3545 IN UINTN StartBit,
3546 IN UINTN EndBit
3547 );
3548
3549 /**
3550 Writes a bit field to an MSR.
3551
3552 Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
3553 the StartBit and the EndBit. All other bits in the destination MSR are
3554 preserved. The MSR written is returned. Extra left bits in Value are
3555 stripped. The caller must either guarantee that Index and the data written is
3556 valid, or the caller must set up exception handlers to catch the exceptions.
3557 This function is only available on IA-32 and X64.
3558
3559 If StartBit is greater than 63, then ASSERT().
3560 If EndBit is greater than 63, then ASSERT().
3561 If EndBit is less than StartBit, then ASSERT().
3562
3563 @param Index The 32-bit MSR index to write.
3564 @param StartBit The ordinal of the least significant bit in the bit field.
3565 Range 0..63.
3566 @param EndBit The ordinal of the most significant bit in the bit field.
3567 Range 0..63.
3568 @param Value New value of the bit field.
3569
3570 @return The value written back to the MSR.
3571
3572 **/
3573 UINT64
3574 EFIAPI
3575 AsmMsrBitFieldWrite64 (
3576 IN UINT32 Index,
3577 IN UINTN StartBit,
3578 IN UINTN EndBit,
3579 IN UINT64 Value
3580 );
3581
3582 /**
3583 Reads a bit field in a 64-bit MSR, performs a bitwise inclusive OR, and
3584 writes the result back to the bit field in the 64-bit MSR.
3585
3586 Reads the 64-bit MSR specified by Index, performs a bitwise inclusive OR
3587 between the read result and the value specified by OrData, and writes the
3588 result to the 64-bit MSR specified by Index. The value written to the MSR is
3589 returned. Extra left bits in OrData are stripped. The caller must either
3590 guarantee that Index and the data written is valid, or the caller must set up
3591 exception handlers to catch the exceptions. This function is only available
3592 on IA-32 and X64.
3593
3594 If StartBit is greater than 63, then ASSERT().
3595 If EndBit is greater than 63, then ASSERT().
3596 If EndBit is less than StartBit, then ASSERT().
3597
3598 @param Index The 32-bit MSR index to write.
3599 @param StartBit The ordinal of the least significant bit in the bit field.
3600 Range 0..63.
3601 @param EndBit The ordinal of the most significant bit in the bit field.
3602 Range 0..63.
3603 @param OrData The value to OR with the read value from the bit field.
3604
3605 @return The value written back to the MSR.
3606
3607 **/
3608 UINT64
3609 EFIAPI
3610 AsmMsrBitFieldOr64 (
3611 IN UINT32 Index,
3612 IN UINTN StartBit,
3613 IN UINTN EndBit,
3614 IN UINT64 OrData
3615 );
3616
3617 /**
3618 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
3619 result back to the bit field in the 64-bit MSR.
3620
3621 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
3622 read result and the value specified by AndData, and writes the result to the
3623 64-bit MSR specified by Index. The value written to the MSR is returned.
3624 Extra left bits in AndData are stripped. The caller must either guarantee
3625 that Index and the data written is valid, or the caller must set up exception
3626 handlers to catch the exceptions. This function is only available on IA-32
3627 and X64.
3628
3629 If StartBit is greater than 63, then ASSERT().
3630 If EndBit is greater than 63, then ASSERT().
3631 If EndBit is less than StartBit, then ASSERT().
3632
3633 @param Index The 32-bit MSR index to write.
3634 @param StartBit The ordinal of the least significant bit in the bit field.
3635 Range 0..63.
3636 @param EndBit The ordinal of the most significant bit in the bit field.
3637 Range 0..63.
3638 @param AndData The value to AND with the read value from the bit field.
3639
3640 @return The value written back to the MSR.
3641
3642 **/
3643 UINT64
3644 EFIAPI
3645 AsmMsrBitFieldAnd64 (
3646 IN UINT32 Index,
3647 IN UINTN StartBit,
3648 IN UINTN EndBit,
3649 IN UINT64 AndData
3650 );
3651
3652 /**
3653 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
3654 bitwise inclusive OR, and writes the result back to the bit field in the
3655 64-bit MSR.
3656
3657 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
3658 a bitwise inclusive OR between the read result and the value specified by
3659 AndData, and writes the result to the 64-bit MSR specified by Index. The
3660 value written to the MSR is returned. Extra left bits in both AndData and
3661 OrData are stripped. The caller must either guarantee that Index and the data
3662 written is valid, or the caller must set up exception handlers to catch the
3663 exceptions. This function is only available on IA-32 and X64.
3664
3665 If StartBit is greater than 63, then ASSERT().
3666 If EndBit is greater than 63, then ASSERT().
3667 If EndBit is less than StartBit, then ASSERT().
3668
3669 @param Index The 32-bit MSR index to write.
3670 @param StartBit The ordinal of the least significant bit in the bit field.
3671 Range 0..63.
3672 @param EndBit The ordinal of the most significant bit in the bit field.
3673 Range 0..63.
3674 @param AndData The value to AND with the read value from the bit field.
3675 @param OrData The value to OR with the result of the AND operation.
3676
3677 @return The value written back to the MSR.
3678