2 Declaration of internal functions in BaseLib.
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5 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/PcdLib.h>
29 Shifts a 64-bit integer left between 0 and 63 bits. The low bits
30 are filled with zeros. The shifted value is returned.
32 This function shifts the 64-bit value Operand to the left by Count bits. The
33 low Count bits are set to zero. The shifted value is returned.
35 @param Operand The 64-bit operand to shift left.
36 @param Count The number of bits to shift left.
38 @return Operand << Count
43 InternalMathLShiftU64 (
49 Shifts a 64-bit integer right between 0 and 63 bits. The high bits
50 are filled with zeros. The shifted value is returned.
52 This function shifts the 64-bit value Operand to the right by Count bits. The
53 high Count bits are set to zero. The shifted value is returned.
55 @param Operand The 64-bit operand to shift right.
56 @param Count The number of bits to shift right.
58 @return Operand >> Count
63 InternalMathRShiftU64 (
69 Shifts a 64-bit integer right between 0 and 63 bits. The high bits
70 are filled with original integer's bit 63. The shifted value is returned.
72 This function shifts the 64-bit value Operand to the right by Count bits. The
73 high Count bits are set to bit 63 of Operand. The shifted value is returned.
75 @param Operand The 64-bit operand to shift right.
76 @param Count The number of bits to shift right.
78 @return Operand arithmetically shifted right by Count
83 InternalMathARShiftU64 (
89 Rotates a 64-bit integer left between 0 and 63 bits, filling
90 the low bits with the high bits that were rotated.
92 This function rotates the 64-bit value Operand to the left by Count bits. The
93 low Count bits are filled with the high Count bits of Operand. The rotated
96 @param Operand The 64-bit operand to rotate left.
97 @param Count The number of bits to rotate left.
99 @return Operand <<< Count
104 InternalMathLRotU64 (
110 Rotates a 64-bit integer right between 0 and 63 bits, filling
111 the high bits with the high low bits that were rotated.
113 This function rotates the 64-bit value Operand to the right by Count bits.
114 The high Count bits are filled with the low Count bits of Operand. The rotated
117 @param Operand The 64-bit operand to rotate right.
118 @param Count The number of bits to rotate right.
120 @return Operand >>> Count
125 InternalMathRRotU64 (
131 Switches the endianess of a 64-bit integer.
133 This function swaps the bytes in a 64-bit unsigned value to switch the value
134 from little endian to big endian or vice versa. The byte swapped value is
137 @param Operand A 64-bit unsigned value.
139 @return The byte swapped Operand.
144 InternalMathSwapBytes64 (
149 Multiplies a 64-bit unsigned integer by a 32-bit unsigned integer
150 and generates a 64-bit unsigned result.
152 This function multiplies the 64-bit unsigned value Multiplicand by the 32-bit
153 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
154 bit unsigned result is returned.
156 @param Multiplicand A 64-bit unsigned value.
157 @param Multiplier A 32-bit unsigned value.
159 @return Multiplicand * Multiplier
164 InternalMathMultU64x32 (
165 IN UINT64 Multiplicand
,
170 Multiplies a 64-bit unsigned integer by a 64-bit unsigned integer
171 and generates a 64-bit unsigned result.
173 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
174 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
175 bit unsigned result is returned.
177 @param Multiplicand A 64-bit unsigned value.
178 @param Multiplier A 64-bit unsigned value.
180 @return Multiplicand * Multiplier
185 InternalMathMultU64x64 (
186 IN UINT64 Multiplicand
,
191 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
192 generates a 64-bit unsigned result.
194 This function divides the 64-bit unsigned value Dividend by the 32-bit
195 unsigned value Divisor and generates a 64-bit unsigned quotient. This
196 function returns the 64-bit unsigned quotient.
198 @param Dividend A 64-bit unsigned value.
199 @param Divisor A 32-bit unsigned value.
201 @return Dividend / Divisor
206 InternalMathDivU64x32 (
212 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
213 generates a 32-bit unsigned remainder.
215 This function divides the 64-bit unsigned value Dividend by the 32-bit
216 unsigned value Divisor and generates a 32-bit remainder. This function
217 returns the 32-bit unsigned remainder.
219 @param Dividend A 64-bit unsigned value.
220 @param Divisor A 32-bit unsigned value.
222 @return Dividend % Divisor
227 InternalMathModU64x32 (
233 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
234 generates a 64-bit unsigned result and an optional 32-bit unsigned remainder.
236 This function divides the 64-bit unsigned value Dividend by the 32-bit
237 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
238 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
239 This function returns the 64-bit unsigned quotient.
241 @param Dividend A 64-bit unsigned value.
242 @param Divisor A 32-bit unsigned value.
243 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
244 optional and may be NULL.
246 @return Dividend / Divisor
251 InternalMathDivRemU64x32 (
254 OUT UINT32
*Remainder OPTIONAL
258 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and
259 generates a 64-bit unsigned result and an optional 64-bit unsigned remainder.
261 This function divides the 64-bit unsigned value Dividend by the 64-bit
262 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
263 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
264 This function returns the 64-bit unsigned quotient.
266 @param Dividend A 64-bit unsigned value.
267 @param Divisor A 64-bit unsigned value.
268 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
269 optional and may be NULL.
271 @return Dividend / Divisor
276 InternalMathDivRemU64x64 (
279 OUT UINT64
*Remainder OPTIONAL
283 Divides a 64-bit signed integer by a 64-bit signed integer and
284 generates a 64-bit signed result and an optional 64-bit signed remainder.
286 This function divides the 64-bit signed value Dividend by the 64-bit
287 signed value Divisor and generates a 64-bit signed quotient. If Remainder
288 is not NULL, then the 64-bit signed remainder is returned in Remainder.
289 This function returns the 64-bit signed quotient.
291 @param Dividend A 64-bit signed value.
292 @param Divisor A 64-bit signed value.
293 @param Remainder A pointer to a 64-bit signed value. This parameter is
294 optional and may be NULL.
296 @return Dividend / Divisor
301 InternalMathDivRemS64x64 (
304 OUT INT64
*Remainder OPTIONAL
308 Transfers control to a function starting with a new stack.
310 Transfers control to the function specified by EntryPoint using the
311 new stack specified by NewStack and passing in the parameters specified
312 by Context1 and Context2. Context1 and Context2 are optional and may
313 be NULL. The function EntryPoint must never return.
314 Marker will be ignored on IA-32, x64, and EBC.
315 IPF CPUs expect one additional parameter of type VOID * that specifies
316 the new backing store pointer.
318 If EntryPoint is NULL, then ASSERT().
319 If NewStack is NULL, then ASSERT().
321 @param EntryPoint A pointer to function to call with the new stack.
322 @param Context1 A pointer to the context to pass into the EntryPoint
324 @param Context2 A pointer to the context to pass into the EntryPoint
326 @param NewStack A pointer to the new stack to use for the EntryPoint
328 @param Marker VA_LIST marker for the variable argument list.
333 InternalSwitchStack (
334 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
335 IN VOID
*Context1
, OPTIONAL
336 IN VOID
*Context2
, OPTIONAL
343 Worker function that returns a bit field from Operand.
345 Returns the bitfield specified by the StartBit and the EndBit from Operand.
347 @param Operand Operand on which to perform the bitfield operation.
348 @param StartBit The ordinal of the least significant bit in the bit field.
349 @param EndBit The ordinal of the most significant bit in the bit field.
351 @return The bit field read.
364 Worker function that reads a bit field from Operand, performs a bitwise OR,
365 and returns the result.
367 Performs a bitwise OR between the bit field specified by StartBit and EndBit
368 in Operand and the value specified by AndData. All other bits in Operand are
369 preserved. The new value is returned.
371 @param Operand Operand on which to perform the bitfield operation.
372 @param StartBit The ordinal of the least significant bit in the bit field.
373 @param EndBit The ordinal of the most significant bit in the bit field.
374 @param OrData The value to OR with the read value from the value
376 @return The new value.
390 Worker function that reads a bit field from Operand, performs a bitwise AND,
391 and returns the result.
393 Performs a bitwise AND between the bit field specified by StartBit and EndBit
394 in Operand and the value specified by AndData. All other bits in Operand are
395 preserved. The new value is returned.
397 @param Operand Operand on which to perform the bitfield operation.
398 @param StartBit The ordinal of the least significant bit in the bit field.
399 @param EndBit The ordinal of the most significant bit in the bit field.
400 @param AndData The value to And with the read value from the value
402 @return The new value.
416 Worker function that checks ASSERT condition for JumpBuffer
418 Checks ASSERT condition for JumpBuffer.
420 If JumpBuffer is NULL, then ASSERT().
421 For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
423 @param JumpBuffer A pointer to CPU context buffer.
428 InternalAssertJumpBuffer (
429 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
434 Restores the CPU context that was saved with SetJump().
436 Restores the CPU context from the buffer specified by JumpBuffer.
437 This function never returns to the caller.
438 Instead is resumes execution based on the state of JumpBuffer.
440 @param JumpBuffer A pointer to CPU context buffer.
441 @param Value The value to return when the SetJump() context is restored.
447 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
453 Check if a Unicode character is a decimal character.
455 This internal function checks if a Unicode character is a
456 decimal character. The valid decimal character is from
459 @param Char The character to check against.
461 @retval TRUE If the Char is a decmial character.
462 @retval FALSE If the Char is not a decmial character.
467 InternalIsDecimalDigitCharacter (
473 Convert a Unicode character to upper case only if
474 it maps to a valid small-case ASCII character.
476 This internal function only deal with Unicode character
477 which maps to a valid small-case ASCII character, i.e.
478 L'a' to L'z'. For other Unicode character, the input character
479 is returned directly.
481 @param Char The character to convert.
483 @retval LowerCharacter If the Char is with range L'a' to L'z'.
484 @retval Unchanged Otherwise.
489 InternalCharToUpper (
495 Convert a Unicode character to numerical value.
497 This internal function only deal with Unicode character
498 which maps to a valid hexadecimal ASII character, i.e.
499 L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other
500 Unicode character, the value returned does not make sense.
502 @param Char The character to convert.
504 @return The numerical value converted.
509 InternalHexCharToUintn (
515 Check if a Unicode character is a hexadecimal character.
517 This internal function checks if a Unicode character is a
518 decimal character. The valid hexadecimal character is
519 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
522 @param Char The character to check against.
524 @retval TRUE If the Char is a hexadecmial character.
525 @retval FALSE If the Char is not a hexadecmial character.
530 InternalIsHexaDecimalDigitCharacter (
536 Check if a ASCII character is a decimal character.
538 This internal function checks if a Unicode character is a
539 decimal character. The valid decimal character is from
542 @param Char The character to check against.
544 @retval TRUE If the Char is a decmial character.
545 @retval FALSE If the Char is not a decmial character.
550 InternalAsciiIsDecimalDigitCharacter (
556 Converts a lowercase Ascii character to upper one.
558 If Chr is lowercase Ascii character, then converts it to upper one.
560 If Value >= 0xA0, then ASSERT().
561 If (Value & 0x0F) >= 0x0A, then ASSERT().
563 @param Chr one Ascii character
565 @return The uppercase value of Ascii character
570 InternalBaseLibAsciiToUpper (
576 Check if a ASCII character is a hexadecimal character.
578 This internal function checks if a ASCII character is a
579 decimal character. The valid hexadecimal character is
580 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
583 @param Char The character to check against.
585 @retval TRUE If the Char is a hexadecmial character.
586 @retval FALSE If the Char is not a hexadecmial character.
591 InternalAsciiIsHexaDecimalDigitCharacter (
597 Convert a ASCII character to numerical value.
599 This internal function only deal with Unicode character
600 which maps to a valid hexadecimal ASII character, i.e.
601 '0' to '9', 'a' to 'f' or 'A' to 'F'. For other
602 ASCII character, the value returned does not make sense.
604 @param Char The character to convert.
606 @return The numerical value converted.
611 InternalAsciiHexCharToUintn (
617 // Ia32 and x64 specific functions
619 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
622 Reads the current Global Descriptor Table Register(GDTR) descriptor.
624 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
625 function is only available on IA-32 and x64.
627 @param Gdtr The pointer to a GDTR descriptor.
632 InternalX86ReadGdtr (
633 OUT IA32_DESCRIPTOR
*Gdtr
637 Writes the current Global Descriptor Table Register (GDTR) descriptor.
639 Writes and the current GDTR descriptor specified by Gdtr. This function is
640 only available on IA-32 and x64.
642 @param Gdtr The pointer to a GDTR descriptor.
647 InternalX86WriteGdtr (
648 IN CONST IA32_DESCRIPTOR
*Gdtr
652 Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.
654 Reads and returns the current IDTR descriptor and returns it in Idtr. This
655 function is only available on IA-32 and x64.
657 @param Idtr The pointer to an IDTR descriptor.
662 InternalX86ReadIdtr (
663 OUT IA32_DESCRIPTOR
*Idtr
667 Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.
669 Writes the current IDTR descriptor and returns it in Idtr. This function is
670 only available on IA-32 and x64.
672 @param Idtr The pointer to an IDTR descriptor.
677 InternalX86WriteIdtr (
678 IN CONST IA32_DESCRIPTOR
*Idtr
682 Save the current floating point/SSE/SSE2 context to a buffer.
684 Saves the current floating point/SSE/SSE2 state to the buffer specified by
685 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
686 available on IA-32 and x64.
688 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
694 OUT IA32_FX_BUFFER
*Buffer
698 Restores the current floating point/SSE/SSE2 context from a buffer.
700 Restores the current floating point/SSE/SSE2 state from the buffer specified
701 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
702 only available on IA-32 and x64.
704 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
709 InternalX86FxRestore (
710 IN CONST IA32_FX_BUFFER
*Buffer
714 Enables the 32-bit paging mode on the CPU.
716 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
717 must be properly initialized prior to calling this service. This function
718 assumes the current execution mode is 32-bit protected mode. This function is
719 only available on IA-32. After the 32-bit paging mode is enabled, control is
720 transferred to the function specified by EntryPoint using the new stack
721 specified by NewStack and passing in the parameters specified by Context1 and
722 Context2. Context1 and Context2 are optional and may be NULL. The function
723 EntryPoint must never return.
725 There are a number of constraints that must be followed before calling this
727 1) Interrupts must be disabled.
728 2) The caller must be in 32-bit protected mode with flat descriptors. This
729 means all descriptors must have a base of 0 and a limit of 4GB.
730 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
732 4) CR3 must point to valid page tables that will be used once the transition
733 is complete, and those page tables must guarantee that the pages for this
734 function and the stack are identity mapped.
736 @param EntryPoint A pointer to function to call with the new stack after
738 @param Context1 A pointer to the context to pass into the EntryPoint
739 function as the first parameter after paging is enabled.
740 @param Context2 A pointer to the context to pass into the EntryPoint
741 function as the second parameter after paging is enabled.
742 @param NewStack A pointer to the new stack to use for the EntryPoint
743 function after paging is enabled.
748 InternalX86EnablePaging32 (
749 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
750 IN VOID
*Context1
, OPTIONAL
751 IN VOID
*Context2
, OPTIONAL
756 Disables the 32-bit paging mode on the CPU.
758 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
759 mode. This function assumes the current execution mode is 32-paged protected
760 mode. This function is only available on IA-32. After the 32-bit paging mode
761 is disabled, control is transferred to the function specified by EntryPoint
762 using the new stack specified by NewStack and passing in the parameters
763 specified by Context1 and Context2. Context1 and Context2 are optional and
764 may be NULL. The function EntryPoint must never return.
766 There are a number of constraints that must be followed before calling this
768 1) Interrupts must be disabled.
769 2) The caller must be in 32-bit paged mode.
770 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
771 4) CR3 must point to valid page tables that guarantee that the pages for
772 this function and the stack are identity mapped.
774 @param EntryPoint A pointer to function to call with the new stack after
776 @param Context1 A pointer to the context to pass into the EntryPoint
777 function as the first parameter after paging is disabled.
778 @param Context2 A pointer to the context to pass into the EntryPoint
779 function as the second parameter after paging is
781 @param NewStack A pointer to the new stack to use for the EntryPoint
782 function after paging is disabled.
787 InternalX86DisablePaging32 (
788 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
789 IN VOID
*Context1
, OPTIONAL
790 IN VOID
*Context2
, OPTIONAL
795 Enables the 64-bit paging mode on the CPU.
797 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
798 must be properly initialized prior to calling this service. This function
799 assumes the current execution mode is 32-bit protected mode with flat
800 descriptors. This function is only available on IA-32. After the 64-bit
801 paging mode is enabled, control is transferred to the function specified by
802 EntryPoint using the new stack specified by NewStack and passing in the
803 parameters specified by Context1 and Context2. Context1 and Context2 are
804 optional and may be 0. The function EntryPoint must never return.
806 @param Cs The 16-bit selector to load in the CS before EntryPoint
807 is called. The descriptor in the GDT that this selector
808 references must be setup for long mode.
809 @param EntryPoint The 64-bit virtual address of the function to call with
810 the new stack after paging is enabled.
811 @param Context1 The 64-bit virtual address of the context to pass into
812 the EntryPoint function as the first parameter after
814 @param Context2 The 64-bit virtual address of the context to pass into
815 the EntryPoint function as the second parameter after
817 @param NewStack The 64-bit virtual address of the new stack to use for
818 the EntryPoint function after paging is enabled.
823 InternalX86EnablePaging64 (
825 IN UINT64 EntryPoint
,
826 IN UINT64 Context1
, OPTIONAL
827 IN UINT64 Context2
, OPTIONAL
832 Disables the 64-bit paging mode on the CPU.
834 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
835 mode. This function assumes the current execution mode is 64-paging mode.
836 This function is only available on x64. After the 64-bit paging mode is
837 disabled, control is transferred to the function specified by EntryPoint
838 using the new stack specified by NewStack and passing in the parameters
839 specified by Context1 and Context2. Context1 and Context2 are optional and
840 may be 0. The function EntryPoint must never return.
842 @param Cs The 16-bit selector to load in the CS before EntryPoint
843 is called. The descriptor in the GDT that this selector
844 references must be setup for 32-bit protected mode.
845 @param EntryPoint The 64-bit virtual address of the function to call with
846 the new stack after paging is disabled.
847 @param Context1 The 64-bit virtual address of the context to pass into
848 the EntryPoint function as the first parameter after
850 @param Context2 The 64-bit virtual address of the context to pass into
851 the EntryPoint function as the second parameter after
853 @param NewStack The 64-bit virtual address of the new stack to use for
854 the EntryPoint function after paging is disabled.
859 InternalX86DisablePaging64 (
861 IN UINT32 EntryPoint
,
862 IN UINT32 Context1
, OPTIONAL
863 IN UINT32 Context2
, OPTIONAL
868 Generates a 16-bit random number through RDRAND instruction.
870 @param[out] Rand Buffer pointer to store the random result.
872 @retval TRUE RDRAND call was successful.
873 @retval FALSE Failed attempts to call RDRAND.
878 InternalX86RdRand16 (
883 Generates a 32-bit random number through RDRAND instruction.
885 @param[out] Rand Buffer pointer to store the random result.
887 @retval TRUE RDRAND call was successful.
888 @retval FALSE Failed attempts to call RDRAND.
893 InternalX86RdRand32 (
898 Generates a 64-bit random number through RDRAND instruction.
901 @param[out] Rand Buffer pointer to store the random result.
903 @retval TRUE RDRAND call was successful.
904 @retval FALSE Failed attempts to call RDRAND.
909 InternalX86RdRand64 (