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.
13 Module Name: BaseLibInternals.h
17 #ifndef __BASE_LIB_INTERNALS__
18 #define __BASE_LIB_INTERNALS__
20 #define QUIENT_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 / 10)
21 #define REMINDER_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 % 10)
23 #define QUIENT_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 / 16)
24 #define REMINDER_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 % 16)
26 #define QUIENT_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 / 10)
27 #define REMINDER_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 % 10)
29 #define QUIENT_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 / 16)
30 #define REMINDER_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 % 16)
37 Shifts a 64-bit integer left between 0 and 63 bits. The low bits
38 are filled with zeros. The shifted value is returned.
40 This function shifts the 64-bit value Operand to the left by Count bits. The
41 low Count bits are set to zero. The shifted value is returned.
43 @param Operand The 64-bit operand to shift left.
44 @param Count The number of bits to shift left.
46 @return Operand << Count
51 InternalMathLShiftU64 (
57 Shifts a 64-bit integer right between 0 and 63 bits. This high bits
58 are filled with zeros. The shifted value is returned.
60 This function shifts the 64-bit value Operand to the right by Count bits. The
61 high Count bits are set to zero. The shifted value is returned.
63 @param Operand The 64-bit operand to shift right.
64 @param Count The number of bits to shift right.
66 @return Operand >> Count
71 InternalMathRShiftU64 (
77 Shifts a 64-bit integer right between 0 and 63 bits. The high bits
78 are filled with original integer's bit 63. The shifted value is returned.
80 This function shifts the 64-bit value Operand to the right by Count bits. The
81 high Count bits are set to bit 63 of Operand. The shifted value is returned.
83 @param Operand The 64-bit operand to shift right.
84 @param Count The number of bits to shift right.
86 @return Operand arithmetically shifted right by Count
91 InternalMathARShiftU64 (
97 Rotates a 64-bit integer left between 0 and 63 bits, filling
98 the low bits with the high bits that were rotated.
100 This function rotates the 64-bit value Operand to the left by Count bits. The
101 low Count bits are fill with the high Count bits of Operand. The rotated
104 @param Operand The 64-bit operand to rotate left.
105 @param Count The number of bits to rotate left.
107 @return Operand <<< Count
112 InternalMathLRotU64 (
118 Rotates a 64-bit integer right between 0 and 63 bits, filling
119 the high bits with the high low bits that were rotated.
121 This function rotates the 64-bit value Operand to the right by Count bits.
122 The high Count bits are fill with the low Count bits of Operand. The rotated
125 @param Operand The 64-bit operand to rotate right.
126 @param Count The number of bits to rotate right.
128 @return Operand >>> Count
133 InternalMathRRotU64 (
139 Switches the endianess of a 64-bit integer.
141 This function swaps the bytes in a 64-bit unsigned value to switch the value
142 from little endian to big endian or vice versa. The byte swapped value is
145 @param Operand A 64-bit unsigned value.
147 @return The byte swaped Operand.
152 InternalMathSwapBytes64 (
157 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer
158 and generates a 64-bit unsigned result.
160 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
161 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
162 bit unsigned result is returned.
164 @param Multiplicand A 64-bit unsigned value.
165 @param Multiplier A 32-bit unsigned value.
167 @return Multiplicand * Multiplier
172 InternalMathMultU64x32 (
173 IN UINT64 Multiplicand
,
178 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer
179 and generates a 64-bit unsigned result.
181 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
182 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
183 bit unsigned result is returned.
185 @param Multiplicand A 64-bit unsigned value.
186 @param Multiplier A 64-bit unsigned value.
188 @return Multiplicand * Multiplier
193 InternalMathMultU64x64 (
194 IN UINT64 Multiplicand
,
199 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
200 generates a 64-bit unsigned result.
202 This function divides the 64-bit unsigned value Dividend by the 32-bit
203 unsigned value Divisor and generates a 64-bit unsigned quotient. This
204 function returns the 64-bit unsigned quotient.
206 @param Dividend A 64-bit unsigned value.
207 @param Divisor A 32-bit unsigned value.
209 @return Dividend / Divisor
214 InternalMathDivU64x32 (
220 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
221 generates a 32-bit unsigned remainder.
223 This function divides the 64-bit unsigned value Dividend by the 32-bit
224 unsigned value Divisor and generates a 32-bit remainder. This function
225 returns the 32-bit unsigned remainder.
227 @param Dividend A 64-bit unsigned value.
228 @param Divisor A 32-bit unsigned value.
230 @return Dividend % Divisor
235 InternalMathModU64x32 (
241 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
242 generates a 64-bit unsigned result and an optional 32-bit unsigned remainder.
244 This function divides the 64-bit unsigned value Dividend by the 32-bit
245 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
246 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
247 This function returns the 64-bit unsigned quotient.
249 @param Dividend A 64-bit unsigned value.
250 @param Divisor A 32-bit unsigned value.
251 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
252 optional and may be NULL.
254 @return Dividend / Divisor
259 InternalMathDivRemU64x32 (
262 OUT UINT32
*Remainder
266 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and
267 generates a 64-bit unsigned result and an optional 64-bit unsigned remainder.
269 This function divides the 64-bit unsigned value Dividend by the 64-bit
270 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
271 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
272 This function returns the 64-bit unsigned quotient.
274 @param Dividend A 64-bit unsigned value.
275 @param Divisor A 64-bit unsigned value.
276 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
277 optional and may be NULL.
279 @return Dividend / Divisor
284 InternalMathDivRemU64x64 (
287 OUT UINT64
*Remainder
291 Divides a 64-bit signed integer by a 64-bit signed integer and
292 generates a 64-bit signed result and a optional 64-bit signed remainder.
294 This function divides the 64-bit unsigned value Dividend by the 64-bit
295 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
296 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
297 This function returns the 64-bit unsigned quotient.
299 @param Dividend A 64-bit signed value.
300 @param Divisor A 64-bit signed value.
301 @param Remainder A pointer to a 64-bit signed value. This parameter is
302 optional and may be NULL.
304 @return Dividend / Divisor
308 InternalMathDivRemS64x64 (
311 OUT INT64
*Remainder OPTIONAL
315 Transfers control to a function starting with a new stack.
317 Transfers control to the function specified by EntryPoint using the
318 new stack specified by NewStack and passing in the parameters specified
319 by Context1 and Context2. Context1 and Context2 are optional and may
320 be NULL. The function EntryPoint must never return.
321 Marker will be ignored on IA-32, x64, and EBC.
322 IPF CPUs expect one additional parameter of type VOID * that specifies
323 the new backing store pointer.
325 If EntryPoint is NULL, then ASSERT().
326 If NewStack is NULL, then ASSERT().
328 @param EntryPoint A pointer to function to call with the new stack.
329 @param Context1 A pointer to the context to pass into the EntryPoint
331 @param Context2 A pointer to the context to pass into the EntryPoint
333 @param NewStack A pointer to the new stack to use for the EntryPoint
335 @param Marker VA_LIST marker for the variable argument list.
340 InternalSwitchStack (
341 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
342 IN VOID
*Context1
, OPTIONAL
343 IN VOID
*Context2
, OPTIONAL
349 // Ia32 and x64 specific functions
353 Reads the current Global Descriptor Table Register(GDTR) descriptor.
355 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
356 function is only available on IA-32 and X64.
358 @param Gdtr Pointer to a GDTR descriptor.
363 InternalX86ReadGdtr (
364 OUT IA32_DESCRIPTOR
*Gdtr
368 Writes the current Global Descriptor Table Register (GDTR) descriptor.
370 Writes and the current GDTR descriptor specified by Gdtr. This function is
371 only available on IA-32 and X64.
373 @param Gdtr Pointer to a GDTR descriptor.
378 InternalX86WriteGdtr (
379 IN CONST IA32_DESCRIPTOR
*Gdtr
383 Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.
385 Reads and returns the current IDTR descriptor and returns it in Idtr. This
386 function is only available on IA-32 and X64.
388 @param Idtr Pointer to a IDTR descriptor.
393 InternalX86ReadIdtr (
394 OUT IA32_DESCRIPTOR
*Idtr
398 Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.
400 Writes the current IDTR descriptor and returns it in Idtr. This function is
401 only available on IA-32 and X64.
403 @param Idtr Pointer to a IDTR descriptor.
408 InternalX86WriteIdtr (
409 IN CONST IA32_DESCRIPTOR
*Idtr
413 Save the current floating point/SSE/SSE2 context to a buffer.
415 Saves the current floating point/SSE/SSE2 state to the buffer specified by
416 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
417 available on IA-32 and X64.
419 @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
425 OUT IA32_FX_BUFFER
*Buffer
429 Restores the current floating point/SSE/SSE2 context from a buffer.
431 Restores the current floating point/SSE/SSE2 state from the buffer specified
432 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
433 only available on IA-32 and X64.
435 @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
440 InternalX86FxRestore (
441 IN CONST IA32_FX_BUFFER
*Buffer
445 Enables the 32-bit paging mode on the CPU.
447 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
448 must be properly initialized prior to calling this service. This function
449 assumes the current execution mode is 32-bit protected mode. This function is
450 only available on IA-32. After the 32-bit paging mode is enabled, control is
451 transferred to the function specified by EntryPoint using the new stack
452 specified by NewStack and passing in the parameters specified by Context1 and
453 Context2. Context1 and Context2 are optional and may be NULL. The function
454 EntryPoint must never return.
456 There are a number of constraints that must be followed before calling this
458 1) Interrupts must be disabled.
459 2) The caller must be in 32-bit protected mode with flat descriptors. This
460 means all descriptors must have a base of 0 and a limit of 4GB.
461 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
463 4) CR3 must point to valid page tables that will be used once the transition
464 is complete, and those page tables must guarantee that the pages for this
465 function and the stack are identity mapped.
467 @param EntryPoint A pointer to function to call with the new stack after
469 @param Context1 A pointer to the context to pass into the EntryPoint
470 function as the first parameter after paging is enabled.
471 @param Context2 A pointer to the context to pass into the EntryPoint
472 function as the second parameter after paging is enabled.
473 @param NewStack A pointer to the new stack to use for the EntryPoint
474 function after paging is enabled.
479 InternalX86EnablePaging32 (
480 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
481 IN VOID
*Context1
, OPTIONAL
482 IN VOID
*Context2
, OPTIONAL
487 Disables the 32-bit paging mode on the CPU.
489 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
490 mode. This function assumes the current execution mode is 32-paged protected
491 mode. This function is only available on IA-32. After the 32-bit paging mode
492 is disabled, control is transferred to the function specified by EntryPoint
493 using the new stack specified by NewStack and passing in the parameters
494 specified by Context1 and Context2. Context1 and Context2 are optional and
495 may be NULL. The function EntryPoint must never return.
497 There are a number of constraints that must be followed before calling this
499 1) Interrupts must be disabled.
500 2) The caller must be in 32-bit paged mode.
501 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
502 4) CR3 must point to valid page tables that guarantee that the pages for
503 this function and the stack are identity mapped.
505 @param EntryPoint A pointer to function to call with the new stack after
507 @param Context1 A pointer to the context to pass into the EntryPoint
508 function as the first parameter after paging is disabled.
509 @param Context2 A pointer to the context to pass into the EntryPoint
510 function as the second parameter after paging is
512 @param NewStack A pointer to the new stack to use for the EntryPoint
513 function after paging is disabled.
518 InternalX86DisablePaging32 (
519 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
520 IN VOID
*Context1
, OPTIONAL
521 IN VOID
*Context2
, OPTIONAL
526 Enables the 64-bit paging mode on the CPU.
528 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
529 must be properly initialized prior to calling this service. This function
530 assumes the current execution mode is 32-bit protected mode with flat
531 descriptors. This function is only available on IA-32. After the 64-bit
532 paging mode is enabled, control is transferred to the function specified by
533 EntryPoint using the new stack specified by NewStack and passing in the
534 parameters specified by Context1 and Context2. Context1 and Context2 are
535 optional and may be 0. The function EntryPoint must never return.
537 @param Cs The 16-bit selector to load in the CS before EntryPoint
538 is called. The descriptor in the GDT that this selector
539 references must be setup for long mode.
540 @param EntryPoint The 64-bit virtual address of the function to call with
541 the new stack after paging is enabled.
542 @param Context1 The 64-bit virtual address of the context to pass into
543 the EntryPoint function as the first parameter after
545 @param Context2 The 64-bit virtual address of the context to pass into
546 the EntryPoint function as the second parameter after
548 @param NewStack The 64-bit virtual address of the new stack to use for
549 the EntryPoint function after paging is enabled.
554 InternalX86EnablePaging64 (
556 IN UINT64 EntryPoint
,
557 IN UINT64 Context1
, OPTIONAL
558 IN UINT64 Context2
, OPTIONAL
563 Disables the 64-bit paging mode on the CPU.
565 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
566 mode. This function assumes the current execution mode is 64-paging mode.
567 This function is only available on X64. After the 64-bit paging mode is
568 disabled, control is transferred to the function specified by EntryPoint
569 using the new stack specified by NewStack and passing in the parameters
570 specified by Context1 and Context2. Context1 and Context2 are optional and
571 may be 0. The function EntryPoint must never return.
573 @param Cs The 16-bit selector to load in the CS before EntryPoint
574 is called. The descriptor in the GDT that this selector
575 references must be setup for 32-bit protected mode.
576 @param EntryPoint The 64-bit virtual address of the function to call with
577 the new stack after paging is disabled.
578 @param Context1 The 64-bit virtual address of the context to pass into
579 the EntryPoint function as the first parameter after
581 @param Context2 The 64-bit virtual address of the context to pass into
582 the EntryPoint function as the second parameter after
584 @param NewStack The 64-bit virtual address of the new stack to use for
585 the EntryPoint function after paging is disabled.
590 InternalX86DisablePaging64 (
592 IN UINT32 EntryPoint
,
593 IN UINT32 Context1
, OPTIONAL
594 IN UINT32 Context2
, OPTIONAL
599 Worker function that locates the Node in the List
601 By searching the List, finds the location of the Node in List. At the same time,
602 verifies the validity of this list.
604 If List is NULL, then ASSERT().
605 If List->ForwardLink is NULL, then ASSERT().
606 If List->backLink is NULL, then ASSERT().
607 If Node is NULL, then ASSERT();
608 If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
609 of nodes in ListHead, including the ListHead node, is greater than or
610 equal to PcdMaximumLinkedListLength, then ASSERT().
612 @param List A pointer to a node in a linked list.
613 @param Node A pointer to one nod.
615 @retval TRUE Node is in List
616 @retval FALSE Node isn't in List, or List is invalid
621 IN CONST LIST_ENTRY
*List
,
622 IN CONST LIST_ENTRY
*Node
626 Performs an atomic increment of an 32-bit unsigned integer.
628 Performs an atomic increment of the 32-bit unsigned integer specified by
629 Value and returns the incremented value. The increment operation must be
630 performed using MP safe mechanisms. The state of the return value is not
631 guaranteed to be MP safe.
633 @param Value A pointer to the 32-bit value to increment.
635 @return The incremented value.
640 InternalSyncIncrement (
641 IN
volatile UINT32
*Value
645 Performs an atomic decrement of an 32-bit unsigned integer.
647 Performs an atomic decrement of the 32-bit unsigned integer specified by
648 Value and returns the decrement value. The decrement operation must be
649 performed using MP safe mechanisms. The state of the return value is not
650 guaranteed to be MP safe.
652 @param Value A pointer to the 32-bit value to decrement.
654 @return The decrement value.
659 InternalSyncDecrement (
660 IN
volatile UINT32
*Value
664 Performs an atomic compare exchange operation on a 32-bit unsigned integer.
666 Performs an atomic compare exchange operation on the 32-bit unsigned integer
667 specified by Value. If Value is equal to CompareValue, then Value is set to
668 ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,
669 then Value is returned. The compare exchange operation must be performed using
672 @param Value A pointer to the 32-bit value for the compare exchange
674 @param CompareValue 32-bit value used in compare operation.
675 @param ExchangeValue 32-bit value used in exchange operation.
677 @return The original *Value before exchange.
682 InternalSyncCompareExchange32 (
683 IN
volatile UINT32
*Value
,
684 IN UINT32 CompareValue
,
685 IN UINT32 ExchangeValue
689 Performs an atomic compare exchange operation on a 64-bit unsigned integer.
691 Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
692 by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and
693 CompareValue is returned. If Value is not equal to CompareValue, then Value is returned.
694 The compare exchange operation must be performed using MP safe mechanisms.
696 @param Value A pointer to the 64-bit value for the compare exchange
698 @param CompareValue 64-bit value used in compare operation.
699 @param ExchangeValue 64-bit value used in exchange operation.
701 @return The original *Value before exchange.
706 InternalSyncCompareExchange64 (
707 IN
volatile UINT64
*Value
,
708 IN UINT64 CompareValue
,
709 IN UINT64 ExchangeValue
713 Worker function that returns a bit field from Operand
715 Returns the bitfield specified by the StartBit and the EndBit from Operand.
717 @param Operand Operand on which to perform the bitfield operation.
718 @param StartBit The ordinal of the least significant bit in the bit field.
719 @param EndBit The ordinal of the most significant bit in the bit field.
721 @return The bit field read.
726 IN
unsigned int Operand
,
732 Worker function that reads a bit field from Operand, performs a bitwise OR,
733 and returns the result.
735 Performs a bitwise OR between the bit field specified by StartBit and EndBit
736 in Operand and the value specified by AndData. All other bits in Operand are
737 preserved. The new value is returned.
739 @param Operand Operand on which to perform the bitfield operation.
740 @param StartBit The ordinal of the least significant bit in the bit field.
741 @param EndBit The ordinal of the most significant bit in the bit field.
742 @param OrData The value to OR with the read value from the value
744 @return The new value.
749 IN
unsigned int Operand
,
752 IN
unsigned int OrData
756 Worker function that reads a bit field from Operand, performs a bitwise AND,
757 and returns the result.
759 Performs a bitwise AND between the bit field specified by StartBit and EndBit
760 in Operand and the value specified by AndData. All other bits in Operand are
761 preserved. The new value is returned.
763 @param Operand Operand on which to perform the bitfield operation.
764 @param StartBit The ordinal of the least significant bit in the bit field.
765 @param EndBit The ordinal of the most significant bit in the bit field.
766 @param AndData The value to And with the read value from the value
768 @return The new value.
773 IN
unsigned int Operand
,
776 IN
unsigned int AndData
780 Worker function that checks ASSERT condition for JumpBuffer
782 Checks ASSERT condition for JumpBuffer.
784 If JumpBuffer is NULL, then ASSERT().
785 For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
787 @param JumpBuffer A pointer to CPU context buffer.
791 InternalAssertJumpBuffer (
792 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
797 Restores the CPU context that was saved with SetJump().
799 Restores the CPU context from the buffer specified by JumpBuffer.
800 This function never returns to the caller.
801 Instead is resumes execution based on the state of JumpBuffer.
803 @param JumpBuffer A pointer to CPU context buffer.
804 @param Value The value to return when the SetJump() context is restored.
810 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
816 // IPF specific functions
820 Transfers control to a function starting with a new stack.
822 Transfers control to the function specified by EntryPoint using the new stack
823 specified by NewStack and passing in the parameters specified by Context1 and
824 Context2. Context1 and Context2 are optional and may be NULL. The function
825 EntryPoint must never return.
827 If EntryPoint is NULL, then ASSERT().
828 If NewStack is NULL, then ASSERT().
830 @param EntryPoint A pointer to function to call with the new stack.
831 @param Context1 A pointer to the context to pass into the EntryPoint
833 @param Context2 A pointer to the context to pass into the EntryPoint
835 @param NewStack A pointer to the new stack to use for the EntryPoint
837 @param NewBsp A pointer to the new memory location for RSE backing
843 AsmSwitchStackAndBackingStore (
844 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
845 IN VOID
*Context1
, OPTIONAL
846 IN VOID
*Context2
, OPTIONAL