2 Declaration of internal functions in BaseLib.
4 Copyright (c) 2006 - 2008, 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>
30 Shifts a 64-bit integer left between 0 and 63 bits. The low bits
31 are filled with zeros. The shifted value is returned.
33 This function shifts the 64-bit value Operand to the left by Count bits. The
34 low Count bits are set to zero. The shifted value is returned.
36 @param Operand The 64-bit operand to shift left.
37 @param Count The number of bits to shift left.
39 @return Operand << Count
44 InternalMathLShiftU64 (
50 Shifts a 64-bit integer right between 0 and 63 bits. This high bits
51 are filled with zeros. The shifted value is returned.
53 This function shifts the 64-bit value Operand to the right by Count bits. The
54 high Count bits are set to zero. The shifted value is returned.
56 @param Operand The 64-bit operand to shift right.
57 @param Count The number of bits to shift right.
59 @return Operand >> Count
64 InternalMathRShiftU64 (
70 Shifts a 64-bit integer right between 0 and 63 bits. The high bits
71 are filled with original integer's bit 63. The shifted value is returned.
73 This function shifts the 64-bit value Operand to the right by Count bits. The
74 high Count bits are set to bit 63 of Operand. The shifted value is returned.
76 @param Operand The 64-bit operand to shift right.
77 @param Count The number of bits to shift right.
79 @return Operand arithmetically shifted right by Count
84 InternalMathARShiftU64 (
90 Rotates a 64-bit integer left between 0 and 63 bits, filling
91 the low bits with the high bits that were rotated.
93 This function rotates the 64-bit value Operand to the left by Count bits. The
94 low Count bits are fill with the high Count bits of Operand. The rotated
97 @param Operand The 64-bit operand to rotate left.
98 @param Count The number of bits to rotate left.
100 @return Operand <<< Count
105 InternalMathLRotU64 (
111 Rotates a 64-bit integer right between 0 and 63 bits, filling
112 the high bits with the high low bits that were rotated.
114 This function rotates the 64-bit value Operand to the right by Count bits.
115 The high Count bits are fill with the low Count bits of Operand. The rotated
118 @param Operand The 64-bit operand to rotate right.
119 @param Count The number of bits to rotate right.
121 @return Operand >>> Count
126 InternalMathRRotU64 (
132 Switches the endianess of a 64-bit integer.
134 This function swaps the bytes in a 64-bit unsigned value to switch the value
135 from little endian to big endian or vice versa. The byte swapped value is
138 @param Operand A 64-bit unsigned value.
140 @return The byte swapped Operand.
145 InternalMathSwapBytes64 (
150 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer
151 and generates a 64-bit unsigned result.
153 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
154 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
155 bit unsigned result is returned.
157 @param Multiplicand A 64-bit unsigned value.
158 @param Multiplier A 32-bit unsigned value.
160 @return Multiplicand * Multiplier
165 InternalMathMultU64x32 (
166 IN UINT64 Multiplicand
,
171 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer
172 and generates a 64-bit unsigned result.
174 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
175 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
176 bit unsigned result is returned.
178 @param Multiplicand A 64-bit unsigned value.
179 @param Multiplier A 64-bit unsigned value.
181 @return Multiplicand * Multiplier
186 InternalMathMultU64x64 (
187 IN UINT64 Multiplicand
,
192 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
193 generates a 64-bit unsigned result.
195 This function divides the 64-bit unsigned value Dividend by the 32-bit
196 unsigned value Divisor and generates a 64-bit unsigned quotient. This
197 function returns the 64-bit unsigned quotient.
199 @param Dividend A 64-bit unsigned value.
200 @param Divisor A 32-bit unsigned value.
202 @return Dividend / Divisor
207 InternalMathDivU64x32 (
213 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
214 generates a 32-bit unsigned remainder.
216 This function divides the 64-bit unsigned value Dividend by the 32-bit
217 unsigned value Divisor and generates a 32-bit remainder. This function
218 returns the 32-bit unsigned remainder.
220 @param Dividend A 64-bit unsigned value.
221 @param Divisor A 32-bit unsigned value.
223 @return Dividend % Divisor
228 InternalMathModU64x32 (
234 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
235 generates a 64-bit unsigned result and an optional 32-bit unsigned remainder.
237 This function divides the 64-bit unsigned value Dividend by the 32-bit
238 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
239 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
240 This function returns the 64-bit unsigned quotient.
242 @param Dividend A 64-bit unsigned value.
243 @param Divisor A 32-bit unsigned value.
244 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
245 optional and may be NULL.
247 @return Dividend / Divisor
252 InternalMathDivRemU64x32 (
255 OUT UINT32
*Remainder OPTIONAL
259 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and
260 generates a 64-bit unsigned result and an optional 64-bit unsigned remainder.
262 This function divides the 64-bit unsigned value Dividend by the 64-bit
263 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
264 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
265 This function returns the 64-bit unsigned quotient.
267 @param Dividend A 64-bit unsigned value.
268 @param Divisor A 64-bit unsigned value.
269 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
270 optional and may be NULL.
272 @return Dividend / Divisor
277 InternalMathDivRemU64x64 (
280 OUT UINT64
*Remainder OPTIONAL
284 Divides a 64-bit signed integer by a 64-bit signed integer and
285 generates a 64-bit signed result and an optional 64-bit signed remainder.
287 This function divides the 64-bit signed value Dividend by the 64-bit
288 signed value Divisor and generates a 64-bit signed quotient. If Remainder
289 is not NULL, then the 64-bit signed remainder is returned in Remainder.
290 This function returns the 64-bit signed quotient.
292 @param Dividend A 64-bit signed value.
293 @param Divisor A 64-bit signed value.
294 @param Remainder A pointer to a 64-bit signed value. This parameter is
295 optional and may be NULL.
297 @return Dividend / Divisor
302 InternalMathDivRemS64x64 (
305 OUT INT64
*Remainder OPTIONAL
309 Transfers control to a function starting with a new stack.
311 Transfers control to the function specified by EntryPoint using the
312 new stack specified by NewStack and passing in the parameters specified
313 by Context1 and Context2. Context1 and Context2 are optional and may
314 be NULL. The function EntryPoint must never return.
315 Marker will be ignored on IA-32, x64, and EBC.
316 IPF CPUs expect one additional parameter of type VOID * that specifies
317 the new backing store pointer.
319 If EntryPoint is NULL, then ASSERT().
320 If NewStack is NULL, then ASSERT().
322 @param EntryPoint A pointer to function to call with the new stack.
323 @param Context1 A pointer to the context to pass into the EntryPoint
325 @param Context2 A pointer to the context to pass into the EntryPoint
327 @param NewStack A pointer to the new stack to use for the EntryPoint
329 @param Marker VA_LIST marker for the variable argument list.
334 InternalSwitchStack (
335 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
336 IN VOID
*Context1
, OPTIONAL
337 IN VOID
*Context2
, OPTIONAL
344 Worker function that locates the Node in the List.
346 By searching the List, finds the location of the Node in List. At the same time,
347 verifies the validity of this list.
349 If List is NULL, then ASSERT().
350 If List->ForwardLink is NULL, then ASSERT().
351 If List->backLink is NULL, then ASSERT().
352 If Node is NULL, then ASSERT();
353 If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
354 of nodes in ListHead, including the ListHead node, is greater than or
355 equal to PcdMaximumLinkedListLength, then ASSERT().
357 @param List A pointer to a node in a linked list.
358 @param Node A pointer to one nod.
360 @retval TRUE Node is in List
361 @retval FALSE Node isn't in List, or List is invalid
367 IN CONST LIST_ENTRY
*List
,
368 IN CONST LIST_ENTRY
*Node
373 Performs an atomic increment of an 32-bit unsigned integer.
375 Performs an atomic increment of the 32-bit unsigned integer specified by
376 Value and returns the incremented value. The increment operation must be
377 performed using MP safe mechanisms. The state of the return value is not
378 guaranteed to be MP safe.
380 @param Value A pointer to the 32-bit value to increment.
382 @return The incremented value.
387 InternalSyncIncrement (
388 IN
volatile UINT32
*Value
393 Performs an atomic decrement of an 32-bit unsigned integer.
395 Performs an atomic decrement of the 32-bit unsigned integer specified by
396 Value and returns the decrement value. The decrement operation must be
397 performed using MP safe mechanisms. The state of the return value is not
398 guaranteed to be MP safe.
400 @param Value A pointer to the 32-bit value to decrement.
402 @return The decrement value.
407 InternalSyncDecrement (
408 IN
volatile UINT32
*Value
413 Performs an atomic compare exchange operation on a 32-bit unsigned integer.
415 Performs an atomic compare exchange operation on the 32-bit unsigned integer
416 specified by Value. If Value is equal to CompareValue, then Value is set to
417 ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,
418 then Value is returned. The compare exchange operation must be performed using
421 @param Value A pointer to the 32-bit value for the compare exchange
423 @param CompareValue 32-bit value used in compare operation.
424 @param ExchangeValue 32-bit value used in exchange operation.
426 @return The original *Value before exchange.
431 InternalSyncCompareExchange32 (
432 IN
volatile UINT32
*Value
,
433 IN UINT32 CompareValue
,
434 IN UINT32 ExchangeValue
439 Performs an atomic compare exchange operation on a 64-bit unsigned integer.
441 Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
442 by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and
443 CompareValue is returned. If Value is not equal to CompareValue, then Value is returned.
444 The compare exchange operation must be performed using MP safe mechanisms.
446 @param Value A pointer to the 64-bit value for the compare exchange
448 @param CompareValue 64-bit value used in compare operation.
449 @param ExchangeValue 64-bit value used in exchange operation.
451 @return The original *Value before exchange.
456 InternalSyncCompareExchange64 (
457 IN
volatile UINT64
*Value
,
458 IN UINT64 CompareValue
,
459 IN UINT64 ExchangeValue
464 Worker function that returns a bit field from Operand.
466 Returns the bitfield specified by the StartBit and the EndBit from Operand.
468 @param Operand Operand on which to perform the bitfield operation.
469 @param StartBit The ordinal of the least significant bit in the bit field.
470 @param EndBit The ordinal of the most significant bit in the bit field.
472 @return The bit field read.
478 IN
unsigned int Operand
,
485 Worker function that reads a bit field from Operand, performs a bitwise OR,
486 and returns the result.
488 Performs a bitwise OR between the bit field specified by StartBit and EndBit
489 in Operand and the value specified by AndData. All other bits in Operand are
490 preserved. The new value is returned.
492 @param Operand Operand on which to perform the bitfield operation.
493 @param StartBit The ordinal of the least significant bit in the bit field.
494 @param EndBit The ordinal of the most significant bit in the bit field.
495 @param OrData The value to OR with the read value from the value
497 @return The new value.
503 IN
unsigned int Operand
,
506 IN
unsigned int OrData
511 Worker function that reads a bit field from Operand, performs a bitwise AND,
512 and returns the result.
514 Performs a bitwise AND between the bit field specified by StartBit and EndBit
515 in Operand and the value specified by AndData. All other bits in Operand are
516 preserved. The new value is returned.
518 @param Operand Operand on which to perform the bitfield operation.
519 @param StartBit The ordinal of the least significant bit in the bit field.
520 @param EndBit The ordinal of the most significant bit in the bit field.
521 @param AndData The value to And with the read value from the value
523 @return The new value.
529 IN
unsigned int Operand
,
532 IN
unsigned int AndData
537 Worker function that checks ASSERT condition for JumpBuffer
539 Checks ASSERT condition for JumpBuffer.
541 If JumpBuffer is NULL, then ASSERT().
542 For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
544 @param JumpBuffer A pointer to CPU context buffer.
549 InternalAssertJumpBuffer (
550 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
555 Restores the CPU context that was saved with SetJump().
557 Restores the CPU context from the buffer specified by JumpBuffer.
558 This function never returns to the caller.
559 Instead is resumes execution based on the state of JumpBuffer.
561 @param JumpBuffer A pointer to CPU context buffer.
562 @param Value The value to return when the SetJump() context is restored.
568 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
574 // Ia32 and x64 specific functions
576 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
579 Reads the current Global Descriptor Table Register(GDTR) descriptor.
581 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
582 function is only available on IA-32 and X64.
584 @param Gdtr Pointer to a GDTR descriptor.
589 InternalX86ReadGdtr (
590 OUT IA32_DESCRIPTOR
*Gdtr
594 Writes the current Global Descriptor Table Register (GDTR) descriptor.
596 Writes and the current GDTR descriptor specified by Gdtr. This function is
597 only available on IA-32 and X64.
599 @param Gdtr Pointer to a GDTR descriptor.
604 InternalX86WriteGdtr (
605 IN CONST IA32_DESCRIPTOR
*Gdtr
609 Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.
611 Reads and returns the current IDTR descriptor and returns it in Idtr. This
612 function is only available on IA-32 and X64.
614 @param Idtr Pointer to a IDTR descriptor.
619 InternalX86ReadIdtr (
620 OUT IA32_DESCRIPTOR
*Idtr
624 Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.
626 Writes the current IDTR descriptor and returns it in Idtr. This function is
627 only available on IA-32 and X64.
629 @param Idtr Pointer to a IDTR descriptor.
634 InternalX86WriteIdtr (
635 IN CONST IA32_DESCRIPTOR
*Idtr
639 Save the current floating point/SSE/SSE2 context to a buffer.
641 Saves the current floating point/SSE/SSE2 state to the buffer specified by
642 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
643 available on IA-32 and X64.
645 @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
651 OUT IA32_FX_BUFFER
*Buffer
655 Restores the current floating point/SSE/SSE2 context from a buffer.
657 Restores the current floating point/SSE/SSE2 state from the buffer specified
658 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
659 only available on IA-32 and X64.
661 @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
666 InternalX86FxRestore (
667 IN CONST IA32_FX_BUFFER
*Buffer
671 Enables the 32-bit paging mode on the CPU.
673 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
674 must be properly initialized prior to calling this service. This function
675 assumes the current execution mode is 32-bit protected mode. This function is
676 only available on IA-32. After the 32-bit paging mode is enabled, control is
677 transferred to the function specified by EntryPoint using the new stack
678 specified by NewStack and passing in the parameters specified by Context1 and
679 Context2. Context1 and Context2 are optional and may be NULL. The function
680 EntryPoint must never return.
682 There are a number of constraints that must be followed before calling this
684 1) Interrupts must be disabled.
685 2) The caller must be in 32-bit protected mode with flat descriptors. This
686 means all descriptors must have a base of 0 and a limit of 4GB.
687 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
689 4) CR3 must point to valid page tables that will be used once the transition
690 is complete, and those page tables must guarantee that the pages for this
691 function and the stack are identity mapped.
693 @param EntryPoint A pointer to function to call with the new stack after
695 @param Context1 A pointer to the context to pass into the EntryPoint
696 function as the first parameter after paging is enabled.
697 @param Context2 A pointer to the context to pass into the EntryPoint
698 function as the second parameter after paging is enabled.
699 @param NewStack A pointer to the new stack to use for the EntryPoint
700 function after paging is enabled.
705 InternalX86EnablePaging32 (
706 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
707 IN VOID
*Context1
, OPTIONAL
708 IN VOID
*Context2
, OPTIONAL
713 Disables the 32-bit paging mode on the CPU.
715 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
716 mode. This function assumes the current execution mode is 32-paged protected
717 mode. This function is only available on IA-32. After the 32-bit paging mode
718 is disabled, control is transferred to the function specified by EntryPoint
719 using the new stack specified by NewStack and passing in the parameters
720 specified by Context1 and Context2. Context1 and Context2 are optional and
721 may be NULL. The function EntryPoint must never return.
723 There are a number of constraints that must be followed before calling this
725 1) Interrupts must be disabled.
726 2) The caller must be in 32-bit paged mode.
727 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
728 4) CR3 must point to valid page tables that guarantee that the pages for
729 this function and the stack are identity mapped.
731 @param EntryPoint A pointer to function to call with the new stack after
733 @param Context1 A pointer to the context to pass into the EntryPoint
734 function as the first parameter after paging is disabled.
735 @param Context2 A pointer to the context to pass into the EntryPoint
736 function as the second parameter after paging is
738 @param NewStack A pointer to the new stack to use for the EntryPoint
739 function after paging is disabled.
744 InternalX86DisablePaging32 (
745 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
746 IN VOID
*Context1
, OPTIONAL
747 IN VOID
*Context2
, OPTIONAL
752 Enables the 64-bit paging mode on the CPU.
754 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
755 must be properly initialized prior to calling this service. This function
756 assumes the current execution mode is 32-bit protected mode with flat
757 descriptors. This function is only available on IA-32. After the 64-bit
758 paging mode is enabled, control is transferred to the function specified by
759 EntryPoint using the new stack specified by NewStack and passing in the
760 parameters specified by Context1 and Context2. Context1 and Context2 are
761 optional and may be 0. The function EntryPoint must never return.
763 @param Cs The 16-bit selector to load in the CS before EntryPoint
764 is called. The descriptor in the GDT that this selector
765 references must be setup for long mode.
766 @param EntryPoint The 64-bit virtual address of the function to call with
767 the new stack after paging is enabled.
768 @param Context1 The 64-bit virtual address of the context to pass into
769 the EntryPoint function as the first parameter after
771 @param Context2 The 64-bit virtual address of the context to pass into
772 the EntryPoint function as the second parameter after
774 @param NewStack The 64-bit virtual address of the new stack to use for
775 the EntryPoint function after paging is enabled.
780 InternalX86EnablePaging64 (
782 IN UINT64 EntryPoint
,
783 IN UINT64 Context1
, OPTIONAL
784 IN UINT64 Context2
, OPTIONAL
789 Disables the 64-bit paging mode on the CPU.
791 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
792 mode. This function assumes the current execution mode is 64-paging mode.
793 This function is only available on X64. After the 64-bit paging mode is
794 disabled, control is transferred to the function specified by EntryPoint
795 using the new stack specified by NewStack and passing in the parameters
796 specified by Context1 and Context2. Context1 and Context2 are optional and
797 may be 0. The function EntryPoint must never return.
799 @param Cs The 16-bit selector to load in the CS before EntryPoint
800 is called. The descriptor in the GDT that this selector
801 references must be setup for 32-bit protected mode.
802 @param EntryPoint The 64-bit virtual address of the function to call with
803 the new stack after paging is disabled.
804 @param Context1 The 64-bit virtual address of the context to pass into
805 the EntryPoint function as the first parameter after
807 @param Context2 The 64-bit virtual address of the context to pass into
808 the EntryPoint function as the second parameter after
810 @param NewStack The 64-bit virtual address of the new stack to use for
811 the EntryPoint function after paging is disabled.
816 InternalX86DisablePaging64 (
818 IN UINT32 EntryPoint
,
819 IN UINT32 Context1
, OPTIONAL
820 IN UINT32 Context2
, OPTIONAL
825 #elif defined (MDE_CPU_IPF)
828 // IPF specific functions
832 Transfers control to a function starting with a new stack.
834 Transfers control to the function specified by EntryPoint using the new stack
835 specified by NewStack and passing in the parameters specified by Context1 and
836 Context2. Context1 and Context2 are optional and may be NULL. The function
837 EntryPoint must never return.
839 If EntryPoint is NULL, then ASSERT().
840 If NewStack is NULL, then ASSERT().
842 @param EntryPoint A pointer to function to call with the new stack.
843 @param Context1 A pointer to the context to pass into the EntryPoint
845 @param Context2 A pointer to the context to pass into the EntryPoint
847 @param NewStack A pointer to the new stack to use for the EntryPoint
849 @param NewBsp A pointer to the new memory location for RSE backing
855 AsmSwitchStackAndBackingStore (
856 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
857 IN VOID
*Context1
, OPTIONAL
858 IN VOID
*Context2
, OPTIONAL