3 Copyright (c) 2004 - 2006, Intel Corporation. All rights reserved.<BR>
4 This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19 Declaration of internal functions in BaseLib.
23 #ifndef __BASE_LIB_INTERNALS_H__
24 #define __BASE_LIB_INTERNALS_H__
26 #include "EdkIIGlueBase.h"
28 #define QUIENT_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 / 10)
29 #define REMINDER_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 % 10)
31 #define QUIENT_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 / 16)
32 #define REMINDER_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 % 16)
34 #define QUIENT_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 / 10)
35 #define REMINDER_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 % 10)
37 #define QUIENT_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 / 16)
38 #define REMINDER_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 % 16)
45 Shifts a 64-bit integer left between 0 and 63 bits. The low bits
46 are filled with zeros. The shifted value is returned.
48 This function shifts the 64-bit value Operand to the left by Count bits. The
49 low Count bits are set to zero. The shifted value is returned.
51 @param Operand The 64-bit operand to shift left.
52 @param Count The number of bits to shift left.
54 @return Operand << Count
59 InternalMathLShiftU64 (
65 Shifts a 64-bit integer right between 0 and 63 bits. This high bits
66 are filled with zeros. The shifted value is returned.
68 This function shifts the 64-bit value Operand to the right by Count bits. The
69 high Count bits are set to zero. The shifted value is returned.
71 @param Operand The 64-bit operand to shift right.
72 @param Count The number of bits to shift right.
74 @return Operand >> Count
79 InternalMathRShiftU64 (
85 Shifts a 64-bit integer right between 0 and 63 bits. The high bits
86 are filled with original integer's bit 63. The shifted value is returned.
88 This function shifts the 64-bit value Operand to the right by Count bits. The
89 high Count bits are set to bit 63 of Operand. The shifted value is returned.
91 @param Operand The 64-bit operand to shift right.
92 @param Count The number of bits to shift right.
94 @return Operand arithmetically shifted right by Count
99 InternalMathARShiftU64 (
105 Rotates a 64-bit integer left between 0 and 63 bits, filling
106 the low bits with the high bits that were rotated.
108 This function rotates the 64-bit value Operand to the left by Count bits. The
109 low Count bits are fill with the high Count bits of Operand. The rotated
112 @param Operand The 64-bit operand to rotate left.
113 @param Count The number of bits to rotate left.
115 @return Operand <<< Count
120 InternalMathLRotU64 (
126 Rotates a 64-bit integer right between 0 and 63 bits, filling
127 the high bits with the high low bits that were rotated.
129 This function rotates the 64-bit value Operand to the right by Count bits.
130 The high Count bits are fill with the low Count bits of Operand. The rotated
133 @param Operand The 64-bit operand to rotate right.
134 @param Count The number of bits to rotate right.
136 @return Operand >>> Count
141 InternalMathRRotU64 (
147 Switches the endianess of a 64-bit integer.
149 This function swaps the bytes in a 64-bit unsigned value to switch the value
150 from little endian to big endian or vice versa. The byte swapped value is
153 @param Operand A 64-bit unsigned value.
155 @return The byte swaped Operand.
160 InternalMathSwapBytes64 (
165 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer
166 and generates a 64-bit unsigned result.
168 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
169 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
170 bit unsigned result is returned.
172 @param Multiplicand A 64-bit unsigned value.
173 @param Multiplier A 32-bit unsigned value.
175 @return Multiplicand * Multiplier
180 InternalMathMultU64x32 (
181 IN UINT64 Multiplicand
,
186 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer
187 and generates a 64-bit unsigned result.
189 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
190 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
191 bit unsigned result is returned.
193 @param Multiplicand A 64-bit unsigned value.
194 @param Multiplier A 64-bit unsigned value.
196 @return Multiplicand * Multiplier
201 InternalMathMultU64x64 (
202 IN UINT64 Multiplicand
,
207 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
208 generates a 64-bit unsigned result.
210 This function divides the 64-bit unsigned value Dividend by the 32-bit
211 unsigned value Divisor and generates a 64-bit unsigned quotient. This
212 function returns the 64-bit unsigned quotient.
214 @param Dividend A 64-bit unsigned value.
215 @param Divisor A 32-bit unsigned value.
217 @return Dividend / Divisor
222 InternalMathDivU64x32 (
228 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
229 generates a 32-bit unsigned remainder.
231 This function divides the 64-bit unsigned value Dividend by the 32-bit
232 unsigned value Divisor and generates a 32-bit remainder. This function
233 returns the 32-bit unsigned remainder.
235 @param Dividend A 64-bit unsigned value.
236 @param Divisor A 32-bit unsigned value.
238 @return Dividend % Divisor
243 InternalMathModU64x32 (
249 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
250 generates a 64-bit unsigned result and an optional 32-bit unsigned remainder.
252 This function divides the 64-bit unsigned value Dividend by the 32-bit
253 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
254 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
255 This function returns the 64-bit unsigned quotient.
257 @param Dividend A 64-bit unsigned value.
258 @param Divisor A 32-bit unsigned value.
259 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
260 optional and may be NULL.
262 @return Dividend / Divisor
267 InternalMathDivRemU64x32 (
270 OUT UINT32
*Remainder
274 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and
275 generates a 64-bit unsigned result and an optional 64-bit unsigned remainder.
277 This function divides the 64-bit unsigned value Dividend by the 64-bit
278 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
279 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
280 This function returns the 64-bit unsigned quotient.
282 @param Dividend A 64-bit unsigned value.
283 @param Divisor A 64-bit unsigned value.
284 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
285 optional and may be NULL.
287 @return Dividend / Divisor
292 InternalMathDivRemU64x64 (
295 OUT UINT64
*Remainder
299 Divides a 64-bit signed integer by a 64-bit signed integer and
300 generates a 64-bit signed result and a optional 64-bit signed remainder.
302 This function divides the 64-bit unsigned value Dividend by the 64-bit
303 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
304 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
305 This function returns the 64-bit unsigned quotient.
307 @param Dividend A 64-bit signed value.
308 @param Divisor A 64-bit signed value.
309 @param Remainder A pointer to a 64-bit signed value. This parameter is
310 optional and may be NULL.
312 @return Dividend / Divisor
316 InternalMathDivRemS64x64 (
319 OUT INT64
*Remainder OPTIONAL
323 Transfers control to a function starting with a new stack.
325 Transfers control to the function specified by EntryPoint using the
326 new stack specified by NewStack and passing in the parameters specified
327 by Context1 and Context2. Context1 and Context2 are optional and may
328 be NULL. The function EntryPoint must never return.
329 Marker will be ignored on IA-32, x64, and EBC.
330 IPF CPUs expect one additional parameter of type VOID * that specifies
331 the new backing store pointer.
333 If EntryPoint is NULL, then ASSERT().
334 If NewStack is NULL, then ASSERT().
336 @param EntryPoint A pointer to function to call with the new stack.
337 @param Context1 A pointer to the context to pass into the EntryPoint
339 @param Context2 A pointer to the context to pass into the EntryPoint
341 @param NewStack A pointer to the new stack to use for the EntryPoint
343 @param Marker VA_LIST marker for the variable argument list.
348 InternalSwitchStack (
349 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
350 IN VOID
*Context1
, OPTIONAL
351 IN VOID
*Context2
, OPTIONAL
358 Worker function that locates the Node in the List
360 By searching the List, finds the location of the Node in List. At the same time,
361 verifies the validity of this list.
363 If List is NULL, then ASSERT().
364 If List->ForwardLink is NULL, then ASSERT().
365 If List->backLink is NULL, then ASSERT().
366 If Node is NULL, then ASSERT();
367 If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
368 of nodes in ListHead, including the ListHead node, is greater than or
369 equal to PcdMaximumLinkedListLength, then ASSERT().
371 @param List A pointer to a node in a linked list.
372 @param Node A pointer to one nod.
374 @retval TRUE Node is in List
375 @retval FALSE Node isn't in List, or List is invalid
380 IN CONST LIST_ENTRY
*List
,
381 IN CONST LIST_ENTRY
*Node
386 Performs an atomic increment of an 32-bit unsigned integer.
388 Performs an atomic increment of the 32-bit unsigned integer specified by
389 Value and returns the incremented value. The increment operation must be
390 performed using MP safe mechanisms. The state of the return value is not
391 guaranteed to be MP safe.
393 @param Value A pointer to the 32-bit value to increment.
395 @return The incremented value.
400 InternalSyncIncrement (
401 IN
volatile UINT32
*Value
406 Performs an atomic decrement of an 32-bit unsigned integer.
408 Performs an atomic decrement of the 32-bit unsigned integer specified by
409 Value and returns the decrement value. The decrement operation must be
410 performed using MP safe mechanisms. The state of the return value is not
411 guaranteed to be MP safe.
413 @param Value A pointer to the 32-bit value to decrement.
415 @return The decrement value.
420 InternalSyncDecrement (
421 IN
volatile UINT32
*Value
426 Performs an atomic compare exchange operation on a 32-bit unsigned integer.
428 Performs an atomic compare exchange operation on the 32-bit unsigned integer
429 specified by Value. If Value is equal to CompareValue, then Value is set to
430 ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,
431 then Value is returned. The compare exchange operation must be performed using
434 @param Value A pointer to the 32-bit value for the compare exchange
436 @param CompareValue 32-bit value used in compare operation.
437 @param ExchangeValue 32-bit value used in exchange operation.
439 @return The original *Value before exchange.
444 InternalSyncCompareExchange32 (
445 IN
volatile UINT32
*Value
,
446 IN UINT32 CompareValue
,
447 IN UINT32 ExchangeValue
452 Performs an atomic compare exchange operation on a 64-bit unsigned integer.
454 Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
455 by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and
456 CompareValue is returned. If Value is not equal to CompareValue, then Value is returned.
457 The compare exchange operation must be performed using MP safe mechanisms.
459 @param Value A pointer to the 64-bit value for the compare exchange
461 @param CompareValue 64-bit value used in compare operation.
462 @param ExchangeValue 64-bit value used in exchange operation.
464 @return The original *Value before exchange.
469 InternalSyncCompareExchange64 (
470 IN
volatile UINT64
*Value
,
471 IN UINT64 CompareValue
,
472 IN UINT64 ExchangeValue
477 Worker function that returns a bit field from Operand
479 Returns the bitfield specified by the StartBit and the EndBit from Operand.
481 @param Operand Operand on which to perform the bitfield operation.
482 @param StartBit The ordinal of the least significant bit in the bit field.
483 @param EndBit The ordinal of the most significant bit in the bit field.
485 @return The bit field read.
490 IN
unsigned int Operand
,
497 Worker function that reads a bit field from Operand, performs a bitwise OR,
498 and returns the result.
500 Performs a bitwise OR between the bit field specified by StartBit and EndBit
501 in Operand and the value specified by AndData. All other bits in Operand are
502 preserved. The new value is returned.
504 @param Operand Operand on which to perform the bitfield operation.
505 @param StartBit The ordinal of the least significant bit in the bit field.
506 @param EndBit The ordinal of the most significant bit in the bit field.
507 @param OrData The value to OR with the read value from the value
509 @return The new value.
514 IN
unsigned int Operand
,
517 IN
unsigned int OrData
522 Worker function that reads a bit field from Operand, performs a bitwise AND,
523 and returns the result.
525 Performs a bitwise AND between the bit field specified by StartBit and EndBit
526 in Operand and the value specified by AndData. All other bits in Operand are
527 preserved. The new value is returned.
529 @param Operand Operand on which to perform the bitfield operation.
530 @param StartBit The ordinal of the least significant bit in the bit field.
531 @param EndBit The ordinal of the most significant bit in the bit field.
532 @param AndData The value to And with the read value from the value
534 @return The new value.
539 IN
unsigned int Operand
,
542 IN
unsigned int AndData
547 Worker function that checks ASSERT condition for JumpBuffer
549 Checks ASSERT condition for JumpBuffer.
551 If JumpBuffer is NULL, then ASSERT().
552 For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
554 @param JumpBuffer A pointer to CPU context buffer.
559 InternalAssertJumpBuffer (
560 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
565 Restores the CPU context that was saved with SetJump().
567 Restores the CPU context from the buffer specified by JumpBuffer.
568 This function never returns to the caller.
569 Instead is resumes execution based on the state of JumpBuffer.
571 @param JumpBuffer A pointer to CPU context buffer.
572 @param Value The value to return when the SetJump() context is restored.
578 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
584 // Ia32 and x64 specific functions
586 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
589 Reads the current Global Descriptor Table Register(GDTR) descriptor.
591 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
592 function is only available on IA-32 and X64.
594 @param Gdtr Pointer to a GDTR descriptor.
599 InternalX86ReadGdtr (
600 OUT IA32_DESCRIPTOR
*Gdtr
604 Writes the current Global Descriptor Table Register (GDTR) descriptor.
606 Writes and the current GDTR descriptor specified by Gdtr. This function is
607 only available on IA-32 and X64.
609 @param Gdtr Pointer to a GDTR descriptor.
614 InternalX86WriteGdtr (
615 IN CONST IA32_DESCRIPTOR
*Gdtr
619 Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.
621 Reads and returns the current IDTR descriptor and returns it in Idtr. This
622 function is only available on IA-32 and X64.
624 @param Idtr Pointer to a IDTR descriptor.
629 InternalX86ReadIdtr (
630 OUT IA32_DESCRIPTOR
*Idtr
634 Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.
636 Writes the current IDTR descriptor and returns it in Idtr. This function is
637 only available on IA-32 and X64.
639 @param Idtr Pointer to a IDTR descriptor.
644 InternalX86WriteIdtr (
645 IN CONST IA32_DESCRIPTOR
*Idtr
649 Save the current floating point/SSE/SSE2 context to a buffer.
651 Saves the current floating point/SSE/SSE2 state to the buffer specified by
652 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
653 available on IA-32 and X64.
655 @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
661 OUT IA32_FX_BUFFER
*Buffer
665 Restores the current floating point/SSE/SSE2 context from a buffer.
667 Restores the current floating point/SSE/SSE2 state from the buffer specified
668 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
669 only available on IA-32 and X64.
671 @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
676 InternalX86FxRestore (
677 IN CONST IA32_FX_BUFFER
*Buffer
681 Enables the 32-bit paging mode on the CPU.
683 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
684 must be properly initialized prior to calling this service. This function
685 assumes the current execution mode is 32-bit protected mode. This function is
686 only available on IA-32. After the 32-bit paging mode is enabled, control is
687 transferred to the function specified by EntryPoint using the new stack
688 specified by NewStack and passing in the parameters specified by Context1 and
689 Context2. Context1 and Context2 are optional and may be NULL. The function
690 EntryPoint must never return.
692 There are a number of constraints that must be followed before calling this
694 1) Interrupts must be disabled.
695 2) The caller must be in 32-bit protected mode with flat descriptors. This
696 means all descriptors must have a base of 0 and a limit of 4GB.
697 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
699 4) CR3 must point to valid page tables that will be used once the transition
700 is complete, and those page tables must guarantee that the pages for this
701 function and the stack are identity mapped.
703 @param EntryPoint A pointer to function to call with the new stack after
705 @param Context1 A pointer to the context to pass into the EntryPoint
706 function as the first parameter after paging is enabled.
707 @param Context2 A pointer to the context to pass into the EntryPoint
708 function as the second parameter after paging is enabled.
709 @param NewStack A pointer to the new stack to use for the EntryPoint
710 function after paging is enabled.
715 InternalX86EnablePaging32 (
716 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
717 IN VOID
*Context1
, OPTIONAL
718 IN VOID
*Context2
, OPTIONAL
723 Disables the 32-bit paging mode on the CPU.
725 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
726 mode. This function assumes the current execution mode is 32-paged protected
727 mode. This function is only available on IA-32. After the 32-bit paging mode
728 is disabled, control is transferred to the function specified by EntryPoint
729 using the new stack specified by NewStack and passing in the parameters
730 specified by Context1 and Context2. Context1 and Context2 are optional and
731 may be NULL. The function EntryPoint must never return.
733 There are a number of constraints that must be followed before calling this
735 1) Interrupts must be disabled.
736 2) The caller must be in 32-bit paged mode.
737 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
738 4) CR3 must point to valid page tables that guarantee that the pages for
739 this function and the stack are identity mapped.
741 @param EntryPoint A pointer to function to call with the new stack after
743 @param Context1 A pointer to the context to pass into the EntryPoint
744 function as the first parameter after paging is disabled.
745 @param Context2 A pointer to the context to pass into the EntryPoint
746 function as the second parameter after paging is
748 @param NewStack A pointer to the new stack to use for the EntryPoint
749 function after paging is disabled.
754 InternalX86DisablePaging32 (
755 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
756 IN VOID
*Context1
, OPTIONAL
757 IN VOID
*Context2
, OPTIONAL
762 Enables the 64-bit paging mode on the CPU.
764 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
765 must be properly initialized prior to calling this service. This function
766 assumes the current execution mode is 32-bit protected mode with flat
767 descriptors. This function is only available on IA-32. After the 64-bit
768 paging mode is enabled, control is transferred to the function specified by
769 EntryPoint using the new stack specified by NewStack and passing in the
770 parameters specified by Context1 and Context2. Context1 and Context2 are
771 optional and may be 0. The function EntryPoint must never return.
773 @param Cs The 16-bit selector to load in the CS before EntryPoint
774 is called. The descriptor in the GDT that this selector
775 references must be setup for long mode.
776 @param EntryPoint The 64-bit virtual address of the function to call with
777 the new stack after paging is enabled.
778 @param Context1 The 64-bit virtual address of the context to pass into
779 the EntryPoint function as the first parameter after
781 @param Context2 The 64-bit virtual address of the context to pass into
782 the EntryPoint function as the second parameter after
784 @param NewStack The 64-bit virtual address of the new stack to use for
785 the EntryPoint function after paging is enabled.
790 InternalX86EnablePaging64 (
792 IN UINT64 EntryPoint
,
793 IN UINT64 Context1
, OPTIONAL
794 IN UINT64 Context2
, OPTIONAL
799 Disables the 64-bit paging mode on the CPU.
801 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
802 mode. This function assumes the current execution mode is 64-paging mode.
803 This function is only available on X64. After the 64-bit paging mode is
804 disabled, control is transferred to the function specified by EntryPoint
805 using the new stack specified by NewStack and passing in the parameters
806 specified by Context1 and Context2. Context1 and Context2 are optional and
807 may be 0. The function EntryPoint must never return.
809 @param Cs The 16-bit selector to load in the CS before EntryPoint
810 is called. The descriptor in the GDT that this selector
811 references must be setup for 32-bit protected mode.
812 @param EntryPoint The 64-bit virtual address of the function to call with
813 the new stack after paging is disabled.
814 @param Context1 The 64-bit virtual address of the context to pass into
815 the EntryPoint function as the first parameter after
817 @param Context2 The 64-bit virtual address of the context to pass into
818 the EntryPoint function as the second parameter after
820 @param NewStack The 64-bit virtual address of the new stack to use for
821 the EntryPoint function after paging is disabled.
826 InternalX86DisablePaging64 (
828 IN UINT32 EntryPoint
,
829 IN UINT32 Context1
, OPTIONAL
830 IN UINT32 Context2
, OPTIONAL
835 #elif defined (MDE_CPU_IPF)
838 // IPF specific functions
842 Transfers control to a function starting with a new stack.
844 Transfers control to the function specified by EntryPoint using the new stack
845 specified by NewStack and passing in the parameters specified by Context1 and
846 Context2. Context1 and Context2 are optional and may be NULL. The function
847 EntryPoint must never return.
849 If EntryPoint is NULL, then ASSERT().
850 If NewStack is NULL, then ASSERT().
852 @param EntryPoint A pointer to function to call with the new stack.
853 @param Context1 A pointer to the context to pass into the EntryPoint
855 @param Context2 A pointer to the context to pass into the EntryPoint
857 @param NewStack A pointer to the new stack to use for the EntryPoint
859 @param NewBsp A pointer to the new memory location for RSE backing
865 AsmSwitchStackAndBackingStore (
866 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
867 IN VOID
*Context1
, OPTIONAL
868 IN VOID
*Context2
, OPTIONAL