2 Declaration of internal functions in BaseLib.
4 Copyright (c) 2006 - 2019, 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 numerical value.
475 This internal function only deal with Unicode character
476 which maps to a valid hexadecimal ASII character, i.e.
477 L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other
478 Unicode character, the value returned does not make sense.
480 @param Char The character to convert.
482 @return The numerical value converted.
487 InternalHexCharToUintn (
493 Check if a Unicode character is a hexadecimal character.
495 This internal function checks if a Unicode character is a
496 decimal character. The valid hexadecimal character is
497 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
500 @param Char The character to check against.
502 @retval TRUE If the Char is a hexadecmial character.
503 @retval FALSE If the Char is not a hexadecmial character.
508 InternalIsHexaDecimalDigitCharacter (
514 Check if a ASCII character is a decimal character.
516 This internal function checks if a Unicode character is a
517 decimal character. The valid decimal character is from
520 @param Char The character to check against.
522 @retval TRUE If the Char is a decmial character.
523 @retval FALSE If the Char is not a decmial character.
528 InternalAsciiIsDecimalDigitCharacter (
534 Check if a ASCII character is a hexadecimal character.
536 This internal function checks if a ASCII character is a
537 decimal character. The valid hexadecimal character is
538 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
541 @param Char The character to check against.
543 @retval TRUE If the Char is a hexadecmial character.
544 @retval FALSE If the Char is not a hexadecmial character.
549 InternalAsciiIsHexaDecimalDigitCharacter (
555 Convert a ASCII character to numerical value.
557 This internal function only deal with Unicode character
558 which maps to a valid hexadecimal ASII character, i.e.
559 '0' to '9', 'a' to 'f' or 'A' to 'F'. For other
560 ASCII character, the value returned does not make sense.
562 @param Char The character to convert.
564 @return The numerical value converted.
569 InternalAsciiHexCharToUintn (
575 // Ia32 and x64 specific functions
577 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
580 Reads the current Global Descriptor Table Register(GDTR) descriptor.
582 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
583 function is only available on IA-32 and x64.
585 @param Gdtr The pointer to a GDTR descriptor.
590 InternalX86ReadGdtr (
591 OUT IA32_DESCRIPTOR
*Gdtr
595 Writes the current Global Descriptor Table Register (GDTR) descriptor.
597 Writes and the current GDTR descriptor specified by Gdtr. This function is
598 only available on IA-32 and x64.
600 @param Gdtr The pointer to a GDTR descriptor.
605 InternalX86WriteGdtr (
606 IN CONST IA32_DESCRIPTOR
*Gdtr
610 Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.
612 Reads and returns the current IDTR descriptor and returns it in Idtr. This
613 function is only available on IA-32 and x64.
615 @param Idtr The pointer to an IDTR descriptor.
620 InternalX86ReadIdtr (
621 OUT IA32_DESCRIPTOR
*Idtr
625 Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.
627 Writes the current IDTR descriptor and returns it in Idtr. This function is
628 only available on IA-32 and x64.
630 @param Idtr The pointer to an IDTR descriptor.
635 InternalX86WriteIdtr (
636 IN CONST IA32_DESCRIPTOR
*Idtr
640 Save the current floating point/SSE/SSE2 context to a buffer.
642 Saves the current floating point/SSE/SSE2 state to the buffer specified by
643 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
644 available on IA-32 and x64.
646 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
652 OUT IA32_FX_BUFFER
*Buffer
656 Restores the current floating point/SSE/SSE2 context from a buffer.
658 Restores the current floating point/SSE/SSE2 state from the buffer specified
659 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
660 only available on IA-32 and x64.
662 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
667 InternalX86FxRestore (
668 IN CONST IA32_FX_BUFFER
*Buffer
672 Enables the 32-bit paging mode on the CPU.
674 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
675 must be properly initialized prior to calling this service. This function
676 assumes the current execution mode is 32-bit protected mode. This function is
677 only available on IA-32. After the 32-bit paging mode is enabled, control is
678 transferred to the function specified by EntryPoint using the new stack
679 specified by NewStack and passing in the parameters specified by Context1 and
680 Context2. Context1 and Context2 are optional and may be NULL. The function
681 EntryPoint must never return.
683 There are a number of constraints that must be followed before calling this
685 1) Interrupts must be disabled.
686 2) The caller must be in 32-bit protected mode with flat descriptors. This
687 means all descriptors must have a base of 0 and a limit of 4GB.
688 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
690 4) CR3 must point to valid page tables that will be used once the transition
691 is complete, and those page tables must guarantee that the pages for this
692 function and the stack are identity mapped.
694 @param EntryPoint A pointer to function to call with the new stack after
696 @param Context1 A pointer to the context to pass into the EntryPoint
697 function as the first parameter after paging is enabled.
698 @param Context2 A pointer to the context to pass into the EntryPoint
699 function as the second parameter after paging is enabled.
700 @param NewStack A pointer to the new stack to use for the EntryPoint
701 function after paging is enabled.
706 InternalX86EnablePaging32 (
707 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
708 IN VOID
*Context1
, OPTIONAL
709 IN VOID
*Context2
, OPTIONAL
714 Disables the 32-bit paging mode on the CPU.
716 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
717 mode. This function assumes the current execution mode is 32-paged protected
718 mode. This function is only available on IA-32. After the 32-bit paging mode
719 is disabled, control is transferred to the function specified by EntryPoint
720 using the new stack specified by NewStack and passing in the parameters
721 specified by Context1 and Context2. Context1 and Context2 are optional and
722 may be NULL. The function EntryPoint must never return.
724 There are a number of constraints that must be followed before calling this
726 1) Interrupts must be disabled.
727 2) The caller must be in 32-bit paged mode.
728 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
729 4) CR3 must point to valid page tables that guarantee that the pages for
730 this function and the stack are identity mapped.
732 @param EntryPoint A pointer to function to call with the new stack after
734 @param Context1 A pointer to the context to pass into the EntryPoint
735 function as the first parameter after paging is disabled.
736 @param Context2 A pointer to the context to pass into the EntryPoint
737 function as the second parameter after paging is
739 @param NewStack A pointer to the new stack to use for the EntryPoint
740 function after paging is disabled.
745 InternalX86DisablePaging32 (
746 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
747 IN VOID
*Context1
, OPTIONAL
748 IN VOID
*Context2
, OPTIONAL
753 Enables the 64-bit paging mode on the CPU.
755 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
756 must be properly initialized prior to calling this service. This function
757 assumes the current execution mode is 32-bit protected mode with flat
758 descriptors. This function is only available on IA-32. After the 64-bit
759 paging mode is enabled, control is transferred to the function specified by
760 EntryPoint using the new stack specified by NewStack and passing in the
761 parameters specified by Context1 and Context2. Context1 and Context2 are
762 optional and may be 0. The function EntryPoint must never return.
764 @param Cs The 16-bit selector to load in the CS before EntryPoint
765 is called. The descriptor in the GDT that this selector
766 references must be setup for long mode.
767 @param EntryPoint The 64-bit virtual address of the function to call with
768 the new stack after paging is enabled.
769 @param Context1 The 64-bit virtual address of the context to pass into
770 the EntryPoint function as the first parameter after
772 @param Context2 The 64-bit virtual address of the context to pass into
773 the EntryPoint function as the second parameter after
775 @param NewStack The 64-bit virtual address of the new stack to use for
776 the EntryPoint function after paging is enabled.
781 InternalX86EnablePaging64 (
783 IN UINT64 EntryPoint
,
784 IN UINT64 Context1
, OPTIONAL
785 IN UINT64 Context2
, OPTIONAL
790 Disables the 64-bit paging mode on the CPU.
792 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
793 mode. This function assumes the current execution mode is 64-paging mode.
794 This function is only available on x64. After the 64-bit paging mode is
795 disabled, control is transferred to the function specified by EntryPoint
796 using the new stack specified by NewStack and passing in the parameters
797 specified by Context1 and Context2. Context1 and Context2 are optional and
798 may be 0. The function EntryPoint must never return.
800 @param Cs The 16-bit selector to load in the CS before EntryPoint
801 is called. The descriptor in the GDT that this selector
802 references must be setup for 32-bit protected mode.
803 @param EntryPoint The 64-bit virtual address of the function to call with
804 the new stack after paging is disabled.
805 @param Context1 The 64-bit virtual address of the context to pass into
806 the EntryPoint function as the first parameter after
808 @param Context2 The 64-bit virtual address of the context to pass into
809 the EntryPoint function as the second parameter after
811 @param NewStack The 64-bit virtual address of the new stack to use for
812 the EntryPoint function after paging is disabled.
817 InternalX86DisablePaging64 (
819 IN UINT32 EntryPoint
,
820 IN UINT32 Context1
, OPTIONAL
821 IN UINT32 Context2
, OPTIONAL
826 Generates a 16-bit random number through RDRAND instruction.
828 @param[out] Rand Buffer pointer to store the random result.
830 @retval TRUE RDRAND call was successful.
831 @retval FALSE Failed attempts to call RDRAND.
836 InternalX86RdRand16 (
841 Generates a 32-bit random number through RDRAND instruction.
843 @param[out] Rand Buffer pointer to store the random result.
845 @retval TRUE RDRAND call was successful.
846 @retval FALSE Failed attempts to call RDRAND.
851 InternalX86RdRand32 (
856 Generates a 64-bit random number through RDRAND instruction.
859 @param[out] Rand Buffer pointer to store the random result.
861 @retval TRUE RDRAND call was successful.
862 @retval FALSE Failed attempts to call RDRAND.
867 InternalX86RdRand64 (