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 common header file for this module.
21 #include "CommonHeader.h"
23 #define QUIENT_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 / 10)
24 #define REMINDER_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 % 10)
26 #define QUIENT_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 / 16)
27 #define REMINDER_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 % 16)
29 #define QUIENT_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 / 10)
30 #define REMINDER_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 % 10)
32 #define QUIENT_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 / 16)
33 #define REMINDER_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 % 16)
40 Shifts a 64-bit integer left between 0 and 63 bits. The low bits
41 are filled with zeros. The shifted value is returned.
43 This function shifts the 64-bit value Operand to the left by Count bits. The
44 low Count bits are set to zero. The shifted value is returned.
46 @param Operand The 64-bit operand to shift left.
47 @param Count The number of bits to shift left.
49 @return Operand << Count
54 InternalMathLShiftU64 (
60 Shifts a 64-bit integer right between 0 and 63 bits. This high bits
61 are filled with zeros. The shifted value is returned.
63 This function shifts the 64-bit value Operand to the right by Count bits. The
64 high Count bits are set to zero. The shifted value is returned.
66 @param Operand The 64-bit operand to shift right.
67 @param Count The number of bits to shift right.
69 @return Operand >> Count
74 InternalMathRShiftU64 (
80 Shifts a 64-bit integer right between 0 and 63 bits. The high bits
81 are filled with original integer's bit 63. The shifted value is returned.
83 This function shifts the 64-bit value Operand to the right by Count bits. The
84 high Count bits are set to bit 63 of Operand. The shifted value is returned.
86 @param Operand The 64-bit operand to shift right.
87 @param Count The number of bits to shift right.
89 @return Operand arithmetically shifted right by Count
94 InternalMathARShiftU64 (
100 Rotates a 64-bit integer left between 0 and 63 bits, filling
101 the low bits with the high bits that were rotated.
103 This function rotates the 64-bit value Operand to the left by Count bits. The
104 low Count bits are fill with the high Count bits of Operand. The rotated
107 @param Operand The 64-bit operand to rotate left.
108 @param Count The number of bits to rotate left.
110 @return Operand <<< Count
115 InternalMathLRotU64 (
121 Rotates a 64-bit integer right between 0 and 63 bits, filling
122 the high bits with the high low bits that were rotated.
124 This function rotates the 64-bit value Operand to the right by Count bits.
125 The high Count bits are fill with the low Count bits of Operand. The rotated
128 @param Operand The 64-bit operand to rotate right.
129 @param Count The number of bits to rotate right.
131 @return Operand >>> Count
136 InternalMathRRotU64 (
142 Switches the endianess of a 64-bit integer.
144 This function swaps the bytes in a 64-bit unsigned value to switch the value
145 from little endian to big endian or vice versa. The byte swapped value is
148 @param Operand A 64-bit unsigned value.
150 @return The byte swaped Operand.
155 InternalMathSwapBytes64 (
160 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer
161 and generates a 64-bit unsigned result.
163 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
164 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
165 bit unsigned result is returned.
167 @param Multiplicand A 64-bit unsigned value.
168 @param Multiplier A 32-bit unsigned value.
170 @return Multiplicand * Multiplier
175 InternalMathMultU64x32 (
176 IN UINT64 Multiplicand
,
181 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer
182 and generates a 64-bit unsigned result.
184 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
185 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
186 bit unsigned result is returned.
188 @param Multiplicand A 64-bit unsigned value.
189 @param Multiplier A 64-bit unsigned value.
191 @return Multiplicand * Multiplier
196 InternalMathMultU64x64 (
197 IN UINT64 Multiplicand
,
202 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
203 generates a 64-bit unsigned result.
205 This function divides the 64-bit unsigned value Dividend by the 32-bit
206 unsigned value Divisor and generates a 64-bit unsigned quotient. This
207 function returns the 64-bit unsigned quotient.
209 @param Dividend A 64-bit unsigned value.
210 @param Divisor A 32-bit unsigned value.
212 @return Dividend / Divisor
217 InternalMathDivU64x32 (
223 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
224 generates a 32-bit unsigned remainder.
226 This function divides the 64-bit unsigned value Dividend by the 32-bit
227 unsigned value Divisor and generates a 32-bit remainder. This function
228 returns the 32-bit unsigned remainder.
230 @param Dividend A 64-bit unsigned value.
231 @param Divisor A 32-bit unsigned value.
233 @return Dividend % Divisor
238 InternalMathModU64x32 (
244 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
245 generates a 64-bit unsigned result and an optional 32-bit unsigned remainder.
247 This function divides the 64-bit unsigned value Dividend by the 32-bit
248 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
249 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
250 This function returns the 64-bit unsigned quotient.
252 @param Dividend A 64-bit unsigned value.
253 @param Divisor A 32-bit unsigned value.
254 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
255 optional and may be NULL.
257 @return Dividend / Divisor
262 InternalMathDivRemU64x32 (
265 OUT UINT32
*Remainder
269 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and
270 generates a 64-bit unsigned result and an optional 64-bit unsigned remainder.
272 This function divides the 64-bit unsigned value Dividend by the 64-bit
273 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
274 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
275 This function returns the 64-bit unsigned quotient.
277 @param Dividend A 64-bit unsigned value.
278 @param Divisor A 64-bit unsigned value.
279 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
280 optional and may be NULL.
282 @return Dividend / Divisor
287 InternalMathDivRemU64x64 (
290 OUT UINT64
*Remainder
294 Divides a 64-bit signed integer by a 64-bit signed integer and
295 generates a 64-bit signed result and a optional 64-bit signed remainder.
297 This function divides the 64-bit unsigned value Dividend by the 64-bit
298 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
299 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
300 This function returns the 64-bit unsigned quotient.
302 @param Dividend A 64-bit signed value.
303 @param Divisor A 64-bit signed value.
304 @param Remainder A pointer to a 64-bit signed value. This parameter is
305 optional and may be NULL.
307 @return Dividend / Divisor
311 InternalMathDivRemS64x64 (
314 OUT INT64
*Remainder OPTIONAL
318 Transfers control to a function starting with a new stack.
320 Transfers control to the function specified by EntryPoint using the
321 new stack specified by NewStack and passing in the parameters specified
322 by Context1 and Context2. Context1 and Context2 are optional and may
323 be NULL. The function EntryPoint must never return.
324 Marker will be ignored on IA-32, x64, and EBC.
325 IPF CPUs expect one additional parameter of type VOID * that specifies
326 the new backing store pointer.
328 If EntryPoint is NULL, then ASSERT().
329 If NewStack is NULL, then ASSERT().
331 @param EntryPoint A pointer to function to call with the new stack.
332 @param Context1 A pointer to the context to pass into the EntryPoint
334 @param Context2 A pointer to the context to pass into the EntryPoint
336 @param NewStack A pointer to the new stack to use for the EntryPoint
338 @param Marker VA_LIST marker for the variable argument list.
343 InternalSwitchStack (
344 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
345 IN VOID
*Context1
, OPTIONAL
346 IN VOID
*Context2
, OPTIONAL
353 Worker function that locates the Node in the List
355 By searching the List, finds the location of the Node in List. At the same time,
356 verifies the validity of this list.
358 If List is NULL, then ASSERT().
359 If List->ForwardLink is NULL, then ASSERT().
360 If List->backLink is NULL, then ASSERT().
361 If Node is NULL, then ASSERT();
362 If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
363 of nodes in ListHead, including the ListHead node, is greater than or
364 equal to PcdMaximumLinkedListLength, then ASSERT().
366 @param List A pointer to a node in a linked list.
367 @param Node A pointer to one nod.
369 @retval TRUE Node is in List
370 @retval FALSE Node isn't in List, or List is invalid
375 IN CONST LIST_ENTRY
*List
,
376 IN CONST LIST_ENTRY
*Node
381 Performs an atomic increment of an 32-bit unsigned integer.
383 Performs an atomic increment of the 32-bit unsigned integer specified by
384 Value and returns the incremented value. The increment operation must be
385 performed using MP safe mechanisms. The state of the return value is not
386 guaranteed to be MP safe.
388 @param Value A pointer to the 32-bit value to increment.
390 @return The incremented value.
395 InternalSyncIncrement (
396 IN
volatile UINT32
*Value
401 Performs an atomic decrement of an 32-bit unsigned integer.
403 Performs an atomic decrement of the 32-bit unsigned integer specified by
404 Value and returns the decrement value. The decrement operation must be
405 performed using MP safe mechanisms. The state of the return value is not
406 guaranteed to be MP safe.
408 @param Value A pointer to the 32-bit value to decrement.
410 @return The decrement value.
415 InternalSyncDecrement (
416 IN
volatile UINT32
*Value
421 Performs an atomic compare exchange operation on a 32-bit unsigned integer.
423 Performs an atomic compare exchange operation on the 32-bit unsigned integer
424 specified by Value. If Value is equal to CompareValue, then Value is set to
425 ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,
426 then Value is returned. The compare exchange operation must be performed using
429 @param Value A pointer to the 32-bit value for the compare exchange
431 @param CompareValue 32-bit value used in compare operation.
432 @param ExchangeValue 32-bit value used in exchange operation.
434 @return The original *Value before exchange.
439 InternalSyncCompareExchange32 (
440 IN
volatile UINT32
*Value
,
441 IN UINT32 CompareValue
,
442 IN UINT32 ExchangeValue
447 Performs an atomic compare exchange operation on a 64-bit unsigned integer.
449 Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
450 by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and
451 CompareValue is returned. If Value is not equal to CompareValue, then Value is returned.
452 The compare exchange operation must be performed using MP safe mechanisms.
454 @param Value A pointer to the 64-bit value for the compare exchange
456 @param CompareValue 64-bit value used in compare operation.
457 @param ExchangeValue 64-bit value used in exchange operation.
459 @return The original *Value before exchange.
464 InternalSyncCompareExchange64 (
465 IN
volatile UINT64
*Value
,
466 IN UINT64 CompareValue
,
467 IN UINT64 ExchangeValue
472 Worker function that returns a bit field from Operand
474 Returns the bitfield specified by the StartBit and the EndBit from Operand.
476 @param Operand Operand on which to perform the bitfield operation.
477 @param StartBit The ordinal of the least significant bit in the bit field.
478 @param EndBit The ordinal of the most significant bit in the bit field.
480 @return The bit field read.
485 IN
unsigned int Operand
,
492 Worker function that reads a bit field from Operand, performs a bitwise OR,
493 and returns the result.
495 Performs a bitwise OR between the bit field specified by StartBit and EndBit
496 in Operand and the value specified by AndData. All other bits in Operand are
497 preserved. The new value is returned.
499 @param Operand Operand on which to perform the bitfield operation.
500 @param StartBit The ordinal of the least significant bit in the bit field.
501 @param EndBit The ordinal of the most significant bit in the bit field.
502 @param OrData The value to OR with the read value from the value
504 @return The new value.
509 IN
unsigned int Operand
,
512 IN
unsigned int OrData
517 Worker function that reads a bit field from Operand, performs a bitwise AND,
518 and returns the result.
520 Performs a bitwise AND between the bit field specified by StartBit and EndBit
521 in Operand and the value specified by AndData. All other bits in Operand are
522 preserved. The new value is returned.
524 @param Operand Operand on which to perform the bitfield operation.
525 @param StartBit The ordinal of the least significant bit in the bit field.
526 @param EndBit The ordinal of the most significant bit in the bit field.
527 @param AndData The value to And with the read value from the value
529 @return The new value.
534 IN
unsigned int Operand
,
537 IN
unsigned int AndData
542 Worker function that checks ASSERT condition for JumpBuffer
544 Checks ASSERT condition for JumpBuffer.
546 If JumpBuffer is NULL, then ASSERT().
547 For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
549 @param JumpBuffer A pointer to CPU context buffer.
553 InternalAssertJumpBuffer (
554 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
559 Restores the CPU context that was saved with SetJump().
561 Restores the CPU context from the buffer specified by JumpBuffer.
562 This function never returns to the caller.
563 Instead is resumes execution based on the state of JumpBuffer.
565 @param JumpBuffer A pointer to CPU context buffer.
566 @param Value The value to return when the SetJump() context is restored.
572 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
578 // Ia32 and x64 specific functions
580 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
583 Reads the current Global Descriptor Table Register(GDTR) descriptor.
585 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
586 function is only available on IA-32 and X64.
588 @param Gdtr Pointer to a GDTR descriptor.
593 InternalX86ReadGdtr (
594 OUT IA32_DESCRIPTOR
*Gdtr
598 Writes the current Global Descriptor Table Register (GDTR) descriptor.
600 Writes and the current GDTR descriptor specified by Gdtr. This function is
601 only available on IA-32 and X64.
603 @param Gdtr Pointer to a GDTR descriptor.
608 InternalX86WriteGdtr (
609 IN CONST IA32_DESCRIPTOR
*Gdtr
613 Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.
615 Reads and returns the current IDTR descriptor and returns it in Idtr. This
616 function is only available on IA-32 and X64.
618 @param Idtr Pointer to a IDTR descriptor.
623 InternalX86ReadIdtr (
624 OUT IA32_DESCRIPTOR
*Idtr
628 Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.
630 Writes the current IDTR descriptor and returns it in Idtr. This function is
631 only available on IA-32 and X64.
633 @param Idtr Pointer to a IDTR descriptor.
638 InternalX86WriteIdtr (
639 IN CONST IA32_DESCRIPTOR
*Idtr
643 Save the current floating point/SSE/SSE2 context to a buffer.
645 Saves the current floating point/SSE/SSE2 state to the buffer specified by
646 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
647 available on IA-32 and X64.
649 @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
655 OUT IA32_FX_BUFFER
*Buffer
659 Restores the current floating point/SSE/SSE2 context from a buffer.
661 Restores the current floating point/SSE/SSE2 state from the buffer specified
662 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
663 only available on IA-32 and X64.
665 @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
670 InternalX86FxRestore (
671 IN CONST IA32_FX_BUFFER
*Buffer
675 Enables the 32-bit paging mode on the CPU.
677 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
678 must be properly initialized prior to calling this service. This function
679 assumes the current execution mode is 32-bit protected mode. This function is
680 only available on IA-32. After the 32-bit paging mode is enabled, control is
681 transferred to the function specified by EntryPoint using the new stack
682 specified by NewStack and passing in the parameters specified by Context1 and
683 Context2. Context1 and Context2 are optional and may be NULL. The function
684 EntryPoint must never return.
686 There are a number of constraints that must be followed before calling this
688 1) Interrupts must be disabled.
689 2) The caller must be in 32-bit protected mode with flat descriptors. This
690 means all descriptors must have a base of 0 and a limit of 4GB.
691 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
693 4) CR3 must point to valid page tables that will be used once the transition
694 is complete, and those page tables must guarantee that the pages for this
695 function and the stack are identity mapped.
697 @param EntryPoint A pointer to function to call with the new stack after
699 @param Context1 A pointer to the context to pass into the EntryPoint
700 function as the first parameter after paging is enabled.
701 @param Context2 A pointer to the context to pass into the EntryPoint
702 function as the second parameter after paging is enabled.
703 @param NewStack A pointer to the new stack to use for the EntryPoint
704 function after paging is enabled.
709 InternalX86EnablePaging32 (
710 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
711 IN VOID
*Context1
, OPTIONAL
712 IN VOID
*Context2
, OPTIONAL
717 Disables the 32-bit paging mode on the CPU.
719 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
720 mode. This function assumes the current execution mode is 32-paged protected
721 mode. This function is only available on IA-32. After the 32-bit paging mode
722 is disabled, control is transferred to the function specified by EntryPoint
723 using the new stack specified by NewStack and passing in the parameters
724 specified by Context1 and Context2. Context1 and Context2 are optional and
725 may be NULL. The function EntryPoint must never return.
727 There are a number of constraints that must be followed before calling this
729 1) Interrupts must be disabled.
730 2) The caller must be in 32-bit paged mode.
731 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
732 4) CR3 must point to valid page tables that guarantee that the pages for
733 this function and the stack are identity mapped.
735 @param EntryPoint A pointer to function to call with the new stack after
737 @param Context1 A pointer to the context to pass into the EntryPoint
738 function as the first parameter after paging is disabled.
739 @param Context2 A pointer to the context to pass into the EntryPoint
740 function as the second parameter after paging is
742 @param NewStack A pointer to the new stack to use for the EntryPoint
743 function after paging is disabled.
748 InternalX86DisablePaging32 (
749 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
750 IN VOID
*Context1
, OPTIONAL
751 IN VOID
*Context2
, OPTIONAL
756 Enables the 64-bit paging mode on the CPU.
758 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
759 must be properly initialized prior to calling this service. This function
760 assumes the current execution mode is 32-bit protected mode with flat
761 descriptors. This function is only available on IA-32. After the 64-bit
762 paging mode is enabled, control is transferred to the function specified by
763 EntryPoint using the new stack specified by NewStack and passing in the
764 parameters specified by Context1 and Context2. Context1 and Context2 are
765 optional and may be 0. The function EntryPoint must never return.
767 @param Cs The 16-bit selector to load in the CS before EntryPoint
768 is called. The descriptor in the GDT that this selector
769 references must be setup for long mode.
770 @param EntryPoint The 64-bit virtual address of the function to call with
771 the new stack after paging is enabled.
772 @param Context1 The 64-bit virtual address of the context to pass into
773 the EntryPoint function as the first parameter after
775 @param Context2 The 64-bit virtual address of the context to pass into
776 the EntryPoint function as the second parameter after
778 @param NewStack The 64-bit virtual address of the new stack to use for
779 the EntryPoint function after paging is enabled.
784 InternalX86EnablePaging64 (
786 IN UINT64 EntryPoint
,
787 IN UINT64 Context1
, OPTIONAL
788 IN UINT64 Context2
, OPTIONAL
793 Disables the 64-bit paging mode on the CPU.
795 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
796 mode. This function assumes the current execution mode is 64-paging mode.
797 This function is only available on X64. After the 64-bit paging mode is
798 disabled, control is transferred to the function specified by EntryPoint
799 using the new stack specified by NewStack and passing in the parameters
800 specified by Context1 and Context2. Context1 and Context2 are optional and
801 may be 0. The function EntryPoint must never return.
803 @param Cs The 16-bit selector to load in the CS before EntryPoint
804 is called. The descriptor in the GDT that this selector
805 references must be setup for 32-bit protected mode.
806 @param EntryPoint The 64-bit virtual address of the function to call with
807 the new stack after paging is disabled.
808 @param Context1 The 64-bit virtual address of the context to pass into
809 the EntryPoint function as the first parameter after
811 @param Context2 The 64-bit virtual address of the context to pass into
812 the EntryPoint function as the second parameter after
814 @param NewStack The 64-bit virtual address of the new stack to use for
815 the EntryPoint function after paging is disabled.
820 InternalX86DisablePaging64 (
822 IN UINT32 EntryPoint
,
823 IN UINT32 Context1
, OPTIONAL
824 IN UINT32 Context2
, OPTIONAL
829 #elif defined (MDE_CPU_IPF)
832 // IPF specific functions
836 Transfers control to a function starting with a new stack.
838 Transfers control to the function specified by EntryPoint using the new stack
839 specified by NewStack and passing in the parameters specified by Context1 and
840 Context2. Context1 and Context2 are optional and may be NULL. The function
841 EntryPoint must never return.
843 If EntryPoint is NULL, then ASSERT().
844 If NewStack is NULL, then ASSERT().
846 @param EntryPoint A pointer to function to call with the new stack.
847 @param Context1 A pointer to the context to pass into the EntryPoint
849 @param Context2 A pointer to the context to pass into the EntryPoint
851 @param NewStack A pointer to the new stack to use for the EntryPoint
853 @param NewBsp A pointer to the new memory location for RSE backing
859 AsmSwitchStackAndBackingStore (
860 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
861 IN VOID
*Context1
, OPTIONAL
862 IN VOID
*Context2
, OPTIONAL