2 Declaration of internal functions in BaseLib.
4 Copyright (c) 2006 - 2007, Intel Corporation<BR>
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
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.
15 #ifndef __BASE_LIB_INTERNALS__
16 #define __BASE_LIB_INTERNALS__
19 #include <Library/BaseLib.h>
20 #include <Library/BaseMemoryLib.h>
21 #include <Library/DebugLib.h>
22 #include <Library/TimerLib.h>
23 #include <Library/PcdLib.h>
26 #define QUIENT_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 / 10)
27 #define REMINDER_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 % 10)
29 #define QUIENT_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 / 16)
30 #define REMINDER_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 % 16)
32 #define QUIENT_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 / 10)
33 #define REMINDER_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 % 10)
35 #define QUIENT_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 / 16)
36 #define REMINDER_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 % 16)
43 Shifts a 64-bit integer left between 0 and 63 bits. The low bits
44 are filled with zeros. The shifted value is returned.
46 This function shifts the 64-bit value Operand to the left by Count bits. The
47 low Count bits are set to zero. The shifted value is returned.
49 @param Operand The 64-bit operand to shift left.
50 @param Count The number of bits to shift left.
52 @return Operand << Count
57 InternalMathLShiftU64 (
63 Shifts a 64-bit integer right between 0 and 63 bits. This high bits
64 are filled with zeros. The shifted value is returned.
66 This function shifts the 64-bit value Operand to the right by Count bits. The
67 high Count bits are set to zero. The shifted value is returned.
69 @param Operand The 64-bit operand to shift right.
70 @param Count The number of bits to shift right.
72 @return Operand >> Count
77 InternalMathRShiftU64 (
83 Shifts a 64-bit integer right between 0 and 63 bits. The high bits
84 are filled with original integer's bit 63. The shifted value is returned.
86 This function shifts the 64-bit value Operand to the right by Count bits. The
87 high Count bits are set to bit 63 of Operand. The shifted value is returned.
89 @param Operand The 64-bit operand to shift right.
90 @param Count The number of bits to shift right.
92 @return Operand arithmetically shifted right by Count
97 InternalMathARShiftU64 (
103 Rotates a 64-bit integer left between 0 and 63 bits, filling
104 the low bits with the high bits that were rotated.
106 This function rotates the 64-bit value Operand to the left by Count bits. The
107 low Count bits are fill with the high Count bits of Operand. The rotated
110 @param Operand The 64-bit operand to rotate left.
111 @param Count The number of bits to rotate left.
113 @return Operand <<< Count
118 InternalMathLRotU64 (
124 Rotates a 64-bit integer right between 0 and 63 bits, filling
125 the high bits with the high low bits that were rotated.
127 This function rotates the 64-bit value Operand to the right by Count bits.
128 The high Count bits are fill with the low Count bits of Operand. The rotated
131 @param Operand The 64-bit operand to rotate right.
132 @param Count The number of bits to rotate right.
134 @return Operand >>> Count
139 InternalMathRRotU64 (
145 Switches the endianess of a 64-bit integer.
147 This function swaps the bytes in a 64-bit unsigned value to switch the value
148 from little endian to big endian or vice versa. The byte swapped value is
151 @param Operand A 64-bit unsigned value.
153 @return The byte swaped Operand.
158 InternalMathSwapBytes64 (
163 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer
164 and generates a 64-bit unsigned result.
166 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
167 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
168 bit unsigned result is returned.
170 @param Multiplicand A 64-bit unsigned value.
171 @param Multiplier A 32-bit unsigned value.
173 @return Multiplicand * Multiplier
178 InternalMathMultU64x32 (
179 IN UINT64 Multiplicand
,
184 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer
185 and generates a 64-bit unsigned result.
187 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
188 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
189 bit unsigned result is returned.
191 @param Multiplicand A 64-bit unsigned value.
192 @param Multiplier A 64-bit unsigned value.
194 @return Multiplicand * Multiplier
199 InternalMathMultU64x64 (
200 IN UINT64 Multiplicand
,
205 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
206 generates a 64-bit unsigned result.
208 This function divides the 64-bit unsigned value Dividend by the 32-bit
209 unsigned value Divisor and generates a 64-bit unsigned quotient. This
210 function returns the 64-bit unsigned quotient.
212 @param Dividend A 64-bit unsigned value.
213 @param Divisor A 32-bit unsigned value.
215 @return Dividend / Divisor
220 InternalMathDivU64x32 (
226 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
227 generates a 32-bit unsigned remainder.
229 This function divides the 64-bit unsigned value Dividend by the 32-bit
230 unsigned value Divisor and generates a 32-bit remainder. This function
231 returns the 32-bit unsigned remainder.
233 @param Dividend A 64-bit unsigned value.
234 @param Divisor A 32-bit unsigned value.
236 @return Dividend % Divisor
241 InternalMathModU64x32 (
247 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
248 generates a 64-bit unsigned result and an optional 32-bit unsigned remainder.
250 This function divides the 64-bit unsigned value Dividend by the 32-bit
251 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
252 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
253 This function returns the 64-bit unsigned quotient.
255 @param Dividend A 64-bit unsigned value.
256 @param Divisor A 32-bit unsigned value.
257 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
258 optional and may be NULL.
260 @return Dividend / Divisor
265 InternalMathDivRemU64x32 (
268 OUT UINT32
*Remainder
272 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and
273 generates a 64-bit unsigned result and an optional 64-bit unsigned remainder.
275 This function divides the 64-bit unsigned value Dividend by the 64-bit
276 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
277 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
278 This function returns the 64-bit unsigned quotient.
280 @param Dividend A 64-bit unsigned value.
281 @param Divisor A 64-bit unsigned value.
282 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
283 optional and may be NULL.
285 @return Dividend / Divisor
290 InternalMathDivRemU64x64 (
293 OUT UINT64
*Remainder
297 Divides a 64-bit signed integer by a 64-bit signed integer and
298 generates a 64-bit signed result and a optional 64-bit signed remainder.
300 This function divides the 64-bit unsigned value Dividend by the 64-bit
301 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
302 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
303 This function returns the 64-bit unsigned quotient.
305 @param Dividend A 64-bit signed value.
306 @param Divisor A 64-bit signed value.
307 @param Remainder A pointer to a 64-bit signed value. This parameter is
308 optional and may be NULL.
310 @return Dividend / Divisor
314 InternalMathDivRemS64x64 (
317 OUT INT64
*Remainder OPTIONAL
321 Transfers control to a function starting with a new stack.
323 Transfers control to the function specified by EntryPoint using the
324 new stack specified by NewStack and passing in the parameters specified
325 by Context1 and Context2. Context1 and Context2 are optional and may
326 be NULL. The function EntryPoint must never return.
327 Marker will be ignored on IA-32, x64, and EBC.
328 IPF CPUs expect one additional parameter of type VOID * that specifies
329 the new backing store pointer.
331 If EntryPoint is NULL, then ASSERT().
332 If NewStack is NULL, then ASSERT().
334 @param EntryPoint A pointer to function to call with the new stack.
335 @param Context1 A pointer to the context to pass into the EntryPoint
337 @param Context2 A pointer to the context to pass into the EntryPoint
339 @param NewStack A pointer to the new stack to use for the EntryPoint
341 @param Marker VA_LIST marker for the variable argument list.
346 InternalSwitchStack (
347 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
348 IN VOID
*Context1
, OPTIONAL
349 IN VOID
*Context2
, OPTIONAL
356 Worker function that locates the Node in the List
358 By searching the List, finds the location of the Node in List. At the same time,
359 verifies the validity of this list.
361 If List is NULL, then ASSERT().
362 If List->ForwardLink is NULL, then ASSERT().
363 If List->backLink is NULL, then ASSERT().
364 If Node is NULL, then ASSERT();
365 If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
366 of nodes in ListHead, including the ListHead node, is greater than or
367 equal to PcdMaximumLinkedListLength, then ASSERT().
369 @param List A pointer to a node in a linked list.
370 @param Node A pointer to one nod.
372 @retval TRUE Node is in List
373 @retval FALSE Node isn't in List, or List is invalid
378 IN CONST LIST_ENTRY
*List
,
379 IN CONST LIST_ENTRY
*Node
384 Performs an atomic increment of an 32-bit unsigned integer.
386 Performs an atomic increment of the 32-bit unsigned integer specified by
387 Value and returns the incremented value. The increment operation must be
388 performed using MP safe mechanisms. The state of the return value is not
389 guaranteed to be MP safe.
391 @param Value A pointer to the 32-bit value to increment.
393 @return The incremented value.
398 InternalSyncIncrement (
399 IN
volatile UINT32
*Value
404 Performs an atomic decrement of an 32-bit unsigned integer.
406 Performs an atomic decrement of the 32-bit unsigned integer specified by
407 Value and returns the decrement value. The decrement operation must be
408 performed using MP safe mechanisms. The state of the return value is not
409 guaranteed to be MP safe.
411 @param Value A pointer to the 32-bit value to decrement.
413 @return The decrement value.
418 InternalSyncDecrement (
419 IN
volatile UINT32
*Value
424 Performs an atomic compare exchange operation on a 32-bit unsigned integer.
426 Performs an atomic compare exchange operation on the 32-bit unsigned integer
427 specified by Value. If Value is equal to CompareValue, then Value is set to
428 ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,
429 then Value is returned. The compare exchange operation must be performed using
432 @param Value A pointer to the 32-bit value for the compare exchange
434 @param CompareValue 32-bit value used in compare operation.
435 @param ExchangeValue 32-bit value used in exchange operation.
437 @return The original *Value before exchange.
442 InternalSyncCompareExchange32 (
443 IN
volatile UINT32
*Value
,
444 IN UINT32 CompareValue
,
445 IN UINT32 ExchangeValue
450 Performs an atomic compare exchange operation on a 64-bit unsigned integer.
452 Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
453 by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and
454 CompareValue is returned. If Value is not equal to CompareValue, then Value is returned.
455 The compare exchange operation must be performed using MP safe mechanisms.
457 @param Value A pointer to the 64-bit value for the compare exchange
459 @param CompareValue 64-bit value used in compare operation.
460 @param ExchangeValue 64-bit value used in exchange operation.
462 @return The original *Value before exchange.
467 InternalSyncCompareExchange64 (
468 IN
volatile UINT64
*Value
,
469 IN UINT64 CompareValue
,
470 IN UINT64 ExchangeValue
475 Worker function that returns a bit field from Operand
477 Returns the bitfield specified by the StartBit and the EndBit from Operand.
479 @param Operand Operand on which to perform the bitfield operation.
480 @param StartBit The ordinal of the least significant bit in the bit field.
481 @param EndBit The ordinal of the most significant bit in the bit field.
483 @return The bit field read.
488 IN
unsigned int Operand
,
495 Worker function that reads a bit field from Operand, performs a bitwise OR,
496 and returns the result.
498 Performs a bitwise OR between the bit field specified by StartBit and EndBit
499 in Operand and the value specified by AndData. All other bits in Operand are
500 preserved. The new value is returned.
502 @param Operand Operand on which to perform the bitfield operation.
503 @param StartBit The ordinal of the least significant bit in the bit field.
504 @param EndBit The ordinal of the most significant bit in the bit field.
505 @param OrData The value to OR with the read value from the value
507 @return The new value.
512 IN
unsigned int Operand
,
515 IN
unsigned int OrData
520 Worker function that reads a bit field from Operand, performs a bitwise AND,
521 and returns the result.
523 Performs a bitwise AND between the bit field specified by StartBit and EndBit
524 in Operand and the value specified by AndData. All other bits in Operand are
525 preserved. The new value is returned.
527 @param Operand Operand on which to perform the bitfield operation.
528 @param StartBit The ordinal of the least significant bit in the bit field.
529 @param EndBit The ordinal of the most significant bit in the bit field.
530 @param AndData The value to And with the read value from the value
532 @return The new value.
537 IN
unsigned int Operand
,
540 IN
unsigned int AndData
545 Worker function that checks ASSERT condition for JumpBuffer
547 Checks ASSERT condition for JumpBuffer.
549 If JumpBuffer is NULL, then ASSERT().
550 For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
552 @param JumpBuffer A pointer to CPU context buffer.
556 InternalAssertJumpBuffer (
557 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
562 Restores the CPU context that was saved with SetJump().
564 Restores the CPU context from the buffer specified by JumpBuffer.
565 This function never returns to the caller.
566 Instead is resumes execution based on the state of JumpBuffer.
568 @param JumpBuffer A pointer to CPU context buffer.
569 @param Value The value to return when the SetJump() context is restored.
575 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
581 // Ia32 and x64 specific functions
583 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
586 Reads the current Global Descriptor Table Register(GDTR) descriptor.
588 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
589 function is only available on IA-32 and X64.
591 @param Gdtr Pointer to a GDTR descriptor.
596 InternalX86ReadGdtr (
597 OUT IA32_DESCRIPTOR
*Gdtr
601 Writes the current Global Descriptor Table Register (GDTR) descriptor.
603 Writes and the current GDTR descriptor specified by Gdtr. This function is
604 only available on IA-32 and X64.
606 @param Gdtr Pointer to a GDTR descriptor.
611 InternalX86WriteGdtr (
612 IN CONST IA32_DESCRIPTOR
*Gdtr
616 Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.
618 Reads and returns the current IDTR descriptor and returns it in Idtr. This
619 function is only available on IA-32 and X64.
621 @param Idtr Pointer to a IDTR descriptor.
626 InternalX86ReadIdtr (
627 OUT IA32_DESCRIPTOR
*Idtr
631 Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.
633 Writes the current IDTR descriptor and returns it in Idtr. This function is
634 only available on IA-32 and X64.
636 @param Idtr Pointer to a IDTR descriptor.
641 InternalX86WriteIdtr (
642 IN CONST IA32_DESCRIPTOR
*Idtr
646 Save the current floating point/SSE/SSE2 context to a buffer.
648 Saves the current floating point/SSE/SSE2 state to the buffer specified by
649 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
650 available on IA-32 and X64.
652 @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
658 OUT IA32_FX_BUFFER
*Buffer
662 Restores the current floating point/SSE/SSE2 context from a buffer.
664 Restores the current floating point/SSE/SSE2 state from the buffer specified
665 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
666 only available on IA-32 and X64.
668 @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
673 InternalX86FxRestore (
674 IN CONST IA32_FX_BUFFER
*Buffer
678 Enables the 32-bit paging mode on the CPU.
680 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
681 must be properly initialized prior to calling this service. This function
682 assumes the current execution mode is 32-bit protected mode. This function is
683 only available on IA-32. After the 32-bit paging mode is enabled, control is
684 transferred to the function specified by EntryPoint using the new stack
685 specified by NewStack and passing in the parameters specified by Context1 and
686 Context2. Context1 and Context2 are optional and may be NULL. The function
687 EntryPoint must never return.
689 There are a number of constraints that must be followed before calling this
691 1) Interrupts must be disabled.
692 2) The caller must be in 32-bit protected mode with flat descriptors. This
693 means all descriptors must have a base of 0 and a limit of 4GB.
694 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
696 4) CR3 must point to valid page tables that will be used once the transition
697 is complete, and those page tables must guarantee that the pages for this
698 function and the stack are identity mapped.
700 @param EntryPoint A pointer to function to call with the new stack after
702 @param Context1 A pointer to the context to pass into the EntryPoint
703 function as the first parameter after paging is enabled.
704 @param Context2 A pointer to the context to pass into the EntryPoint
705 function as the second parameter after paging is enabled.
706 @param NewStack A pointer to the new stack to use for the EntryPoint
707 function after paging is enabled.
712 InternalX86EnablePaging32 (
713 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
714 IN VOID
*Context1
, OPTIONAL
715 IN VOID
*Context2
, OPTIONAL
720 Disables the 32-bit paging mode on the CPU.
722 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
723 mode. This function assumes the current execution mode is 32-paged protected
724 mode. This function is only available on IA-32. After the 32-bit paging mode
725 is disabled, control is transferred to the function specified by EntryPoint
726 using the new stack specified by NewStack and passing in the parameters
727 specified by Context1 and Context2. Context1 and Context2 are optional and
728 may be NULL. The function EntryPoint must never return.
730 There are a number of constraints that must be followed before calling this
732 1) Interrupts must be disabled.
733 2) The caller must be in 32-bit paged mode.
734 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
735 4) CR3 must point to valid page tables that guarantee that the pages for
736 this function and the stack are identity mapped.
738 @param EntryPoint A pointer to function to call with the new stack after
740 @param Context1 A pointer to the context to pass into the EntryPoint
741 function as the first parameter after paging is disabled.
742 @param Context2 A pointer to the context to pass into the EntryPoint
743 function as the second parameter after paging is
745 @param NewStack A pointer to the new stack to use for the EntryPoint
746 function after paging is disabled.
751 InternalX86DisablePaging32 (
752 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
753 IN VOID
*Context1
, OPTIONAL
754 IN VOID
*Context2
, OPTIONAL
759 Enables the 64-bit paging mode on the CPU.
761 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
762 must be properly initialized prior to calling this service. This function
763 assumes the current execution mode is 32-bit protected mode with flat
764 descriptors. This function is only available on IA-32. After the 64-bit
765 paging mode is enabled, control is transferred to the function specified by
766 EntryPoint using the new stack specified by NewStack and passing in the
767 parameters specified by Context1 and Context2. Context1 and Context2 are
768 optional and may be 0. The function EntryPoint must never return.
770 @param Cs The 16-bit selector to load in the CS before EntryPoint
771 is called. The descriptor in the GDT that this selector
772 references must be setup for long mode.
773 @param EntryPoint The 64-bit virtual address of the function to call with
774 the new stack after paging is enabled.
775 @param Context1 The 64-bit virtual address of the context to pass into
776 the EntryPoint function as the first parameter after
778 @param Context2 The 64-bit virtual address of the context to pass into
779 the EntryPoint function as the second parameter after
781 @param NewStack The 64-bit virtual address of the new stack to use for
782 the EntryPoint function after paging is enabled.
787 InternalX86EnablePaging64 (
789 IN UINT64 EntryPoint
,
790 IN UINT64 Context1
, OPTIONAL
791 IN UINT64 Context2
, OPTIONAL
796 Disables the 64-bit paging mode on the CPU.
798 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
799 mode. This function assumes the current execution mode is 64-paging mode.
800 This function is only available on X64. After the 64-bit paging mode is
801 disabled, control is transferred to the function specified by EntryPoint
802 using the new stack specified by NewStack and passing in the parameters
803 specified by Context1 and Context2. Context1 and Context2 are optional and
804 may be 0. The function EntryPoint must never return.
806 @param Cs The 16-bit selector to load in the CS before EntryPoint
807 is called. The descriptor in the GDT that this selector
808 references must be setup for 32-bit protected mode.
809 @param EntryPoint The 64-bit virtual address of the function to call with
810 the new stack after paging is disabled.
811 @param Context1 The 64-bit virtual address of the context to pass into
812 the EntryPoint function as the first parameter after
814 @param Context2 The 64-bit virtual address of the context to pass into
815 the EntryPoint function as the second parameter after
817 @param NewStack The 64-bit virtual address of the new stack to use for
818 the EntryPoint function after paging is disabled.
823 InternalX86DisablePaging64 (
825 IN UINT32 EntryPoint
,
826 IN UINT32 Context1
, OPTIONAL
827 IN UINT32 Context2
, OPTIONAL
832 #elif defined (MDE_CPU_IPF)
835 // IPF specific functions
839 Transfers control to a function starting with a new stack.
841 Transfers control to the function specified by EntryPoint using the new stack
842 specified by NewStack and passing in the parameters specified by Context1 and
843 Context2. Context1 and Context2 are optional and may be NULL. The function
844 EntryPoint must never return.
846 If EntryPoint is NULL, then ASSERT().
847 If NewStack is NULL, then ASSERT().
849 @param EntryPoint A pointer to function to call with the new stack.
850 @param Context1 A pointer to the context to pass into the EntryPoint
852 @param Context2 A pointer to the context to pass into the EntryPoint
854 @param NewStack A pointer to the new stack to use for the EntryPoint
856 @param NewBsp A pointer to the new memory location for RSE backing
862 AsmSwitchStackAndBackingStore (
863 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
864 IN VOID
*Context1
, OPTIONAL
865 IN VOID
*Context2
, OPTIONAL