diff options
Diffstat (limited to 'MdePkg')
26 files changed, 1271 insertions, 65 deletions
diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h index ea61da14ca..6a43c16454 100644 --- a/MdePkg/Include/Library/BaseLib.h +++ b/MdePkg/Include/Library/BaseLib.h @@ -2474,6 +2474,14 @@ InterlockedDecrement ( /**
Performs an atomic compare exchange operation on a 32-bit unsigned integer.
+ Performs an atomic compare exchange operation on the 32-bit unsigned integer
+ specified by Value. If Value is equal to CompareValue, then Value is set to
+ ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,
+ then Value is returned. The compare exchange operation must be performed using
+ MP safe mechanisms.
+
+ If Value is NULL, then ASSERT().
+
@param Value A pointer to the 32-bit value for the compare exchange
operation.
@param CompareValue 32-bit value used in compare operation.
@@ -2493,6 +2501,13 @@ InterlockedCompareExchange32 ( /**
Performs an atomic compare exchange operation on a 64-bit unsigned integer.
+ Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
+ by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and
+ CompareValue is returned. If Value is not equal to CompareValue, then Value is returned.
+ The compare exchange operation must be performed using MP safe mechanisms.
+
+ If Value is NULL, then ASSERT().
+
@param Value A pointer to the 64-bit value for the compare exchange
operation.
@param CompareValue 64-bit value used in compare operation.
@@ -2566,6 +2581,7 @@ MemoryFence ( calls to LongJump() cause a non-zero value to be returned by SetJump().
If JumpBuffer is NULL, then ASSERT().
+ For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
@param JumpBuffer A pointer to CPU context buffer.
@@ -2586,6 +2602,7 @@ SetJump ( the state of JumpBuffer.
If JumpBuffer is NULL, then ASSERT().
+ For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
If Value is 0, then ASSERT().
@param JumpBuffer A pointer to CPU context buffer.
diff --git a/MdePkg/Include/Library/UefiDecompressLib.h b/MdePkg/Include/Library/UefiDecompressLib.h index d1cf2d7d08..f744abc7eb 100644 --- a/MdePkg/Include/Library/UefiDecompressLib.h +++ b/MdePkg/Include/Library/UefiDecompressLib.h @@ -17,6 +17,39 @@ #ifndef __UEFI_DECPOMPRESS_LIB_H__
#define __UEFI_DECPOMPRESS_LIB_H__
+/**
+ Retrieves the size of the uncompressed buffer and the size of the scratch buffer.
+
+ Retrieves the size of the uncompressed buffer and the temporary scratch buffer
+ required to decompress the buffer specified by Source and SourceSize.
+ If the size of the uncompressed buffer or the size of the scratch buffer cannot
+ be determined from the compressed data specified by Source and SourceData,
+ then RETURN_INVALID_PARAMETER is returned. Otherwise, the size of the uncompressed
+ buffer is returned in DestinationSize, the size of the scratch buffer is returned
+ in ScratchSize, and RETURN_SUCCESS is returned.
+ This function does not have scratch buffer available to perform a thorough
+ checking of the validity of the source data. It just retrieves the "Original Size"
+ field from the beginning bytes of the source data and output it as DestinationSize.
+ And ScratchSize is specific to the decompression implementation.
+
+ If Source is NULL, then ASSERT().
+ If DestinationSize is NULL, then ASSERT().
+ If ScratchSize is NULL, then ASSERT().
+
+ @param Source The source buffer containing the compressed data.
+ @param SourceSize The size, in bytes, of the source buffer.
+ @param DestinationSize A pointer to the size, in bytes, of the uncompressed buffer
+ that will be generated when the compressed buffer specified
+ by Source and SourceSize is decompressed..
+ @param ScratchSize A pointer to the size, in bytes, of the scratch buffer that
+ is required to decompress the compressed buffer specified
+ by Source and SourceSize.
+
+ @retval RETURN_SUCCESS The size of destination buffer and the size of scratch
+ buffer are successull retrieved.
+ @retval RETURN_INVALID_PARAMETER The source data is corrupted
+
+**/
RETURN_STATUS
EFIAPI
UefiDecompressGetInfo (
@@ -26,6 +59,32 @@ UefiDecompressGetInfo ( OUT UINT32 *ScratchSize
);
+/**
+ Decompresses a compressed source buffer.
+
+ This function is designed so that the decompression algorithm can be implemented
+ without using any memory services. As a result, this function is not allowed to
+ call any memory allocation services in its implementation. It is the caller¡¯s r
+ esponsibility to allocate and free the Destination and Scratch buffers.
+ If the compressed source data specified by Source is sucessfully decompressed
+ into Destination, then RETURN_SUCCESS is returned. If the compressed source data
+ specified by Source is not in a valid compressed data format,
+ then RETURN_INVALID_PARAMETER is returned.
+
+ If Source is NULL, then ASSERT().
+ If Destination is NULL, then ASSERT().
+ If the required scratch buffer size > 0 and Scratch is NULL, then ASSERT().
+
+ @param Source The source buffer containing the compressed data.
+ @param Destination The destination buffer to store the decompressed data
+ @param Scratch A temporary scratch buffer that is used to perform the decompression.
+ This is an optional parameter that may be NULL if the
+ required scratch buffer size is 0.
+
+ @retval RETURN_SUCCESS Decompression is successfull
+ @retval RETURN_INVALID_PARAMETER The source data is corrupted
+
+**/
RETURN_STATUS
EFIAPI
UefiDecompress (
diff --git a/MdePkg/Library/BaseLib/BaseLibInternals.h b/MdePkg/Library/BaseLib/BaseLibInternals.h index 0c32e1bd2c..3a4ff07f06 100644 --- a/MdePkg/Library/BaseLib/BaseLibInternals.h +++ b/MdePkg/Library/BaseLib/BaseLibInternals.h @@ -21,6 +21,19 @@ // Math functions
//
+/**
+ Worker functons that shifts a 64-bit integer left between 0 and 63 bits. The low bits
+ are filled with zeros. The shifted value is returned.
+
+ This function shifts the 64-bit value Operand to the left by Count bits. The
+ low Count bits are set to zero. The shifted value is returned.
+
+ @param Operand The 64-bit operand to shift left.
+ @param Count The number of bits to shift left.
+
+ @return Operand << Count
+
+**/
UINT64
EFIAPI
InternalMathLShiftU64 (
@@ -28,6 +41,19 @@ InternalMathLShiftU64 ( IN UINTN Count
);
+/**
+ Worker functon that shifts a 64-bit integer right between 0 and 63 bits. This high bits
+ are filled with zeros. The shifted value is returned.
+
+ This function shifts the 64-bit value Operand to the right by Count bits. The
+ high Count bits are set to zero. The shifted value is returned.
+
+ @param Operand The 64-bit operand to shift right.
+ @param Count The number of bits to shift right.
+
+ @return Operand >> Count
+
+**/
UINT64
EFIAPI
InternalMathRShiftU64 (
@@ -35,6 +61,19 @@ InternalMathRShiftU64 ( IN UINTN Count
);
+/**
+ Worker function that shifts a 64-bit integer right between 0 and 63 bits. The high bits
+ are filled with original integer's bit 63. The shifted value is returned.
+
+ This function shifts the 64-bit value Operand to the right by Count bits. The
+ high Count bits are set to bit 63 of Operand. The shifted value is returned.
+
+ @param Operand The 64-bit operand to shift right.
+ @param Count The number of bits to shift right.
+
+ @return Operand arithmetically shifted right by Count
+
+**/
UINT64
EFIAPI
InternalMathARShiftU64 (
@@ -42,6 +81,20 @@ InternalMathARShiftU64 ( IN UINTN Count
);
+/**
+ Worker function that rotates a 64-bit integer left between 0 and 63 bits, filling
+ the low bits with the high bits that were rotated.
+
+ This function rotates the 64-bit value Operand to the left by Count bits. The
+ low Count bits are fill with the high Count bits of Operand. The rotated
+ value is returned.
+
+ @param Operand The 64-bit operand to rotate left.
+ @param Count The number of bits to rotate left.
+
+ @return Operand <<< Count
+
+**/
UINT64
EFIAPI
InternalMathLRotU64 (
@@ -49,6 +102,20 @@ InternalMathLRotU64 ( IN UINTN Count
);
+/**
+ Worker function that rotates a 64-bit integer right between 0 and 63 bits, filling
+ the high bits with the high low bits that were rotated.
+
+ This function rotates the 64-bit value Operand to the right by Count bits.
+ The high Count bits are fill with the low Count bits of Operand. The rotated
+ value is returned.
+
+ @param Operand The 64-bit operand to rotate right.
+ @param Count The number of bits to rotate right.
+
+ @return Operand >>> Count
+
+**/
UINT64
EFIAPI
InternalMathRRotU64 (
@@ -56,12 +123,38 @@ InternalMathRRotU64 ( IN UINTN Count
);
+/**
+ Worker function that switches the endianess of a 64-bit integer.
+
+ This function swaps the bytes in a 64-bit unsigned value to switch the value
+ from little endian to big endian or vice versa. The byte swapped value is
+ returned.
+
+ @param Operand A 64-bit unsigned value.
+
+ @return The byte swaped Operand.
+
+**/
UINT64
EFIAPI
InternalMathSwapBytes64 (
IN UINT64 Operand
);
+/**
+ Worker function that multiples a 64-bit unsigned integer by a 32-bit unsigned integer
+ and generates a 64-bit unsigned result.
+
+ This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
+ unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
+ bit unsigned result is returned.
+
+ @param Multiplicand A 64-bit unsigned value.
+ @param Multiplier A 32-bit unsigned value.
+
+ @return Multiplicand * Multiplier
+
+**/
UINT64
EFIAPI
InternalMathMultU64x32 (
@@ -69,6 +162,20 @@ InternalMathMultU64x32 ( IN UINT32 Multiplier
);
+/**
+ Worker function that multiples a 64-bit unsigned integer by a 64-bit unsigned integer
+ and generates a 64-bit unsigned result.
+
+ This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
+ unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
+ bit unsigned result is returned.
+
+ @param Multiplicand A 64-bit unsigned value.
+ @param Multiplier A 64-bit unsigned value.
+
+ @return Multiplicand * Multiplier
+
+**/
UINT64
EFIAPI
InternalMathMultU64x64 (
@@ -76,6 +183,20 @@ InternalMathMultU64x64 ( IN UINT64 Multiplier
);
+/**
+ Worker function that divides a 64-bit unsigned integer by a 32-bit unsigned integer and
+ generates a 64-bit unsigned result.
+
+ This function divides the 64-bit unsigned value Dividend by the 32-bit
+ unsigned value Divisor and generates a 64-bit unsigned quotient. This
+ function returns the 64-bit unsigned quotient.
+
+ @param Dividend A 64-bit unsigned value.
+ @param Divisor A 32-bit unsigned value.
+
+ @return Dividend / Divisor
+
+**/
UINT64
EFIAPI
InternalMathDivU64x32 (
@@ -83,6 +204,20 @@ InternalMathDivU64x32 ( IN UINT32 Divisor
);
+/**
+ Worker function that divides a 64-bit unsigned integer by a 32-bit unsigned integer and
+ generates a 32-bit unsigned remainder.
+
+ This function divides the 64-bit unsigned value Dividend by the 32-bit
+ unsigned value Divisor and generates a 32-bit remainder. This function
+ returns the 32-bit unsigned remainder.
+
+ @param Dividend A 64-bit unsigned value.
+ @param Divisor A 32-bit unsigned value.
+
+ @return Dividend % Divisor
+
+**/
UINT32
EFIAPI
InternalMathModU64x32 (
@@ -90,6 +225,23 @@ InternalMathModU64x32 ( IN UINT32 Divisor
);
+/**
+ Worker function that divides a 64-bit unsigned integer by a 32-bit unsigned integer and
+ generates a 64-bit unsigned result and an optional 32-bit unsigned remainder.
+
+ This function divides the 64-bit unsigned value Dividend by the 32-bit
+ unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
+ is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
+ This function returns the 64-bit unsigned quotient.
+
+ @param Dividend A 64-bit unsigned value.
+ @param Divisor A 32-bit unsigned value.
+ @param Remainder A pointer to a 32-bit unsigned value. This parameter is
+ optional and may be NULL.
+
+ @return Dividend / Divisor
+
+**/
UINT64
EFIAPI
InternalMathDivRemU64x32 (
@@ -98,6 +250,23 @@ InternalMathDivRemU64x32 ( OUT UINT32 *Remainder
);
+/**
+ Worker function that divides a 64-bit unsigned integer by a 64-bit unsigned integer and
+ generates a 64-bit unsigned result and an optional 64-bit unsigned remainder.
+
+ This function divides the 64-bit unsigned value Dividend by the 64-bit
+ unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
+ is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
+ This function returns the 64-bit unsigned quotient.
+
+ @param Dividend A 64-bit unsigned value.
+ @param Divisor A 64-bit unsigned value.
+ @param Remainder A pointer to a 64-bit unsigned value. This parameter is
+ optional and may be NULL.
+
+ @return Dividend / Divisor
+
+**/
UINT64
EFIAPI
InternalMathDivRemU64x64 (
@@ -106,16 +275,48 @@ InternalMathDivRemU64x64 ( OUT UINT64 *Remainder
);
+/**
+ Worker function that divides a 64-bit signed integer by a 64-bit signed integer and
+ generates a 64-bit signed result and a optional 64-bit signed remainder.
+
+ This function divides the 64-bit unsigned value Dividend by the 64-bit
+ unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
+ is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
+ This function returns the 64-bit unsigned quotient.
+
+ @param Dividend A 64-bit signed value.
+ @param Divisor A 64-bit signed value.
+ @param Remainder A pointer to a 64-bit signed value. This parameter is
+ optional and may be NULL.
+
+ @return Dividend / Divisor
+
+**/
INT64
-EFIAPI
InternalMathDivRemS64x64 (
IN INT64 Dividend,
IN INT64 Divisor,
- OUT INT64 *Remainder
+ OUT INT64 *Remainder OPTIONAL
);
+/**
+ Transfers control to a function starting with a new stack.
+
+ Transfers control to the function specified by EntryPoint using the new stack
+ specified by NewStack and passing in the parameters specified by Context1 and
+ Context2. Context1 and Context2 are optional and may be NULL. The function
+ EntryPoint must never return.
+
+ @param EntryPoint A pointer to function to call with the new stack.
+ @param Context1 A pointer to the context to pass into the EntryPoint
+ function.
+ @param Context2 A pointer to the context to pass into the EntryPoint
+ function.
+ @param NewStack A pointer to the new stack to use for the EntryPoint
+ function.
+
+**/
VOID
-EFIAPI
InternalSwitchStack (
IN SWITCH_STACK_ENTRY_POINT EntryPoint,
IN VOID *Context1,
@@ -127,42 +328,131 @@ InternalSwitchStack ( // Ia32 and x64 specific functions
//
+/**
+ Reads the current Global Descriptor Table Register(GDTR) descriptor.
+
+ Reads and returns the current GDTR descriptor and returns it in Gdtr. This
+ function is only available on IA-32 and X64.
+
+ @param Gdtr Pointer to a GDTR descriptor.
+
+**/
VOID
EFIAPI
InternalX86ReadGdtr (
OUT IA32_DESCRIPTOR *Gdtr
);
+/**
+ Writes the current Global Descriptor Table Register (GDTR) descriptor.
+
+ Writes and the current GDTR descriptor specified by Gdtr. This function is
+ only available on IA-32 and X64.
+
+ @param Gdtr Pointer to a GDTR descriptor.
+
+**/
VOID
EFIAPI
InternalX86WriteGdtr (
IN CONST IA32_DESCRIPTOR *Gdtr
);
+/**
+ Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.
+
+ Reads and returns the current IDTR descriptor and returns it in Idtr. This
+ function is only available on IA-32 and X64.
+
+ @param Idtr Pointer to a IDTR descriptor.
+
+**/
VOID
EFIAPI
InternalX86ReadIdtr (
OUT IA32_DESCRIPTOR *Idtr
);
+/**
+ Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.
+
+ Writes the current IDTR descriptor and returns it in Idtr. This function is
+ only available on IA-32 and X64.
+
+ @param Idtr Pointer to a IDTR descriptor.
+
+**/
VOID
EFIAPI
InternalX86WriteIdtr (
IN CONST IA32_DESCRIPTOR *Idtr
);
+/**
+ Save the current floating point/SSE/SSE2 context to a buffer.
+
+ Saves the current floating point/SSE/SSE2 state to the buffer specified by
+ Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
+ available on IA-32 and X64.
+
+ @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
+
+**/
VOID
EFIAPI
InternalX86FxSave (
OUT IA32_FX_BUFFER *Buffer
);
+/**
+ Restores the current floating point/SSE/SSE2 context from a buffer.
+
+ Restores the current floating point/SSE/SSE2 state from the buffer specified
+ by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
+ only available on IA-32 and X64.
+
+ @param Buffer Pointer to a buffer to save the floating point/SSE/SSE2 context.
+
+**/
VOID
EFIAPI
InternalX86FxRestore (
IN CONST IA32_FX_BUFFER *Buffer
);
+/**
+ Enables the 32-bit paging mode on the CPU.
+
+ Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
+ must be properly initialized prior to calling this service. This function
+ assumes the current execution mode is 32-bit protected mode. This function is
+ only available on IA-32. After the 32-bit paging mode is enabled, control is
+ transferred to the function specified by EntryPoint using the new stack
+ specified by NewStack and passing in the parameters specified by Context1 and
+ Context2. Context1 and Context2 are optional and may be NULL. The function
+ EntryPoint must never return.
+
+ There are a number of constraints that must be followed before calling this
+ function:
+ 1) Interrupts must be disabled.
+ 2) The caller must be in 32-bit protected mode with flat descriptors. This
+ means all descriptors must have a base of 0 and a limit of 4GB.
+ 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
+ descriptors.
+ 4) CR3 must point to valid page tables that will be used once the transition
+ is complete, and those page tables must guarantee that the pages for this
+ function and the stack are identity mapped.
+
+ @param EntryPoint A pointer to function to call with the new stack after
+ paging is enabled.
+ @param Context1 A pointer to the context to pass into the EntryPoint
+ function as the first parameter after paging is enabled.
+ @param Context2 A pointer to the context to pass into the EntryPoint
+ function as the second parameter after paging is enabled.
+ @param NewStack A pointer to the new stack to use for the EntryPoint
+ function after paging is enabled.
+
+**/
VOID
EFIAPI
InternalX86EnablePaging32 (
@@ -172,6 +462,36 @@ InternalX86EnablePaging32 ( IN VOID *NewStack
);
+/**
+ Disables the 32-bit paging mode on the CPU.
+
+ Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
+ mode. This function assumes the current execution mode is 32-paged protected
+ mode. This function is only available on IA-32. After the 32-bit paging mode
+ is disabled, control is transferred to the function specified by EntryPoint
+ using the new stack specified by NewStack and passing in the parameters
+ specified by Context1 and Context2. Context1 and Context2 are optional and
+ may be NULL. The function EntryPoint must never return.
+
+ There are a number of constraints that must be followed before calling this
+ function:
+ 1) Interrupts must be disabled.
+ 2) The caller must be in 32-bit paged mode.
+ 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
+ 4) CR3 must point to valid page tables that guarantee that the pages for
+ this function and the stack are identity mapped.
+
+ @param EntryPoint A pointer to function to call with the new stack after
+ paging is disabled.
+ @param Context1 A pointer to the context to pass into the EntryPoint
+ function as the first parameter after paging is disabled.
+ @param Context2 A pointer to the context to pass into the EntryPoint
+ function as the second parameter after paging is
+ disabled.
+ @param NewStack A pointer to the new stack to use for the EntryPoint
+ function after paging is disabled.
+
+**/
VOID
EFIAPI
InternalX86DisablePaging32 (
@@ -181,6 +501,33 @@ InternalX86DisablePaging32 ( IN VOID *NewStack
);
+/**
+ Enables the 64-bit paging mode on the CPU.
+
+ Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
+ must be properly initialized prior to calling this service. This function
+ assumes the current execution mode is 32-bit protected mode with flat
+ descriptors. This function is only available on IA-32. After the 64-bit
+ paging mode is enabled, control is transferred to the function specified by
+ EntryPoint using the new stack specified by NewStack and passing in the
+ parameters specified by Context1 and Context2. Context1 and Context2 are
+ optional and may be 0. The function EntryPoint must never return.
+
+ @param Cs The 16-bit selector to load in the CS before EntryPoint
+ is called. The descriptor in the GDT that this selector
+ references must be setup for long mode.
+ @param EntryPoint The 64-bit virtual address of the function to call with
+ the new stack after paging is enabled.
+ @param Context1 The 64-bit virtual address of the context to pass into
+ the EntryPoint function as the first parameter after
+ paging is enabled.
+ @param Context2 The 64-bit virtual address of the context to pass into
+ the EntryPoint function as the second parameter after
+ paging is enabled.
+ @param NewStack The 64-bit virtual address of the new stack to use for
+ the EntryPoint function after paging is enabled.
+
+**/
VOID
EFIAPI
InternalX86EnablePaging64 (
@@ -191,6 +538,32 @@ InternalX86EnablePaging64 ( IN UINT64 NewStack
);
+/**
+ Disables the 64-bit paging mode on the CPU.
+
+ Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
+ mode. This function assumes the current execution mode is 64-paging mode.
+ This function is only available on X64. After the 64-bit paging mode is
+ disabled, control is transferred to the function specified by EntryPoint
+ using the new stack specified by NewStack and passing in the parameters
+ specified by Context1 and Context2. Context1 and Context2 are optional and
+ may be 0. The function EntryPoint must never return.
+
+ @param Cs The 16-bit selector to load in the CS before EntryPoint
+ is called. The descriptor in the GDT that this selector
+ references must be setup for 32-bit protected mode.
+ @param EntryPoint The 64-bit virtual address of the function to call with
+ the new stack after paging is disabled.
+ @param Context1 The 64-bit virtual address of the context to pass into
+ the EntryPoint function as the first parameter after
+ paging is disabled.
+ @param Context2 The 64-bit virtual address of the context to pass into
+ the EntryPoint function as the second parameter after
+ paging is disabled.
+ @param NewStack The 64-bit virtual address of the new stack to use for
+ the EntryPoint function after paging is disabled.
+
+**/
VOID
EFIAPI
InternalX86DisablePaging64 (
diff --git a/MdePkg/Library/BaseLib/BitField.c b/MdePkg/Library/BaseLib/BitField.c index 9c1aff1c6f..0b517aa974 100644 --- a/MdePkg/Library/BaseLib/BitField.c +++ b/MdePkg/Library/BaseLib/BitField.c @@ -14,8 +14,19 @@ **/
+/**
+ Worker function that returns a bit field from Operand
+
+ Returns the bitfield specified by the StartBit and the EndBit from Operand.
+
+ @param Operand Operand on which to perform the bitfield operation.
+ @param StartBit The ordinal of the least significant bit in the bit field.
+ @param EndBit The ordinal of the most significant bit in the bit field.
+
+ @return The bit field read.
+
+**/
unsigned int
-EFIAPI
BitFieldReadUint (
IN unsigned int Operand,
IN UINTN StartBit,
@@ -29,8 +40,23 @@ BitFieldReadUint ( return (Operand & ~((unsigned int)-2 << EndBit)) >> StartBit;
}
+/**
+ Worker function that reads a bit field from Operand, performs a bitwise OR,
+ and returns the result.
+
+ Performs a bitwise OR between the bit field specified by StartBit and EndBit
+ in Operand and the value specified by AndData. All other bits in Operand are
+ preserved. The new value is returned.
+
+ @param Operand Operand on which to perform the bitfield operation.
+ @param StartBit The ordinal of the least significant bit in the bit field.
+ @param EndBit The ordinal of the most significant bit in the bit field.
+ @param OrData The value to OR with the read value from the value
+
+ @return The new value.
+
+**/
unsigned int
-EFIAPI
BitFieldOrUint (
IN unsigned int Operand,
IN UINTN StartBit,
@@ -42,11 +68,26 @@ BitFieldOrUint ( // ~((unsigned int)-2 << EndBit) is a mask in which bit[0] thru bit[EndBit]
// are 1's while bit[EndBit + 1] thru the most significant bit are 0's.
//
- return Operand | ((OrData << StartBit) & ~((unsigned int)-2 << EndBit));
+ return Operand | ((OrData << StartBit) & ~((unsigned int) -2 << EndBit));
}
+/**
+ Worker function that reads a bit field from Operand, performs a bitwise AND,
+ and returns the result.
+
+ Performs a bitwise AND between the bit field specified by StartBit and EndBit
+ in Operand and the value specified by AndData. All other bits in Operand are
+ preserved. The new value is returned.
+
+ @param Operand Operand on which to perform the bitfield operation.
+ @param StartBit The ordinal of the least significant bit in the bit field.
+ @param EndBit The ordinal of the most significant bit in the bit field.
+ @param AndData The value to And with the read value from the value
+
+ @return The new value.
+
+**/
unsigned int
-EFIAPI
BitFieldAndUint (
IN unsigned int Operand,
IN UINTN StartBit,
@@ -58,7 +99,7 @@ BitFieldAndUint ( // ~((unsigned int)-2 << EndBit) is a mask in which bit[0] thru bit[EndBit]
// are 1's while bit[EndBit + 1] thru the most significant bit are 0's.
//
- return Operand & ~((~AndData << StartBit) & ~((unsigned int)-2 << EndBit));
+ return Operand & ~((~AndData << StartBit) & ~((unsigned int) -2 << EndBit));
}
/**
diff --git a/MdePkg/Library/BaseLib/DivS64x64Remainder.c b/MdePkg/Library/BaseLib/DivS64x64Remainder.c index aa28fc8ccb..efa091088e 100644 --- a/MdePkg/Library/BaseLib/DivS64x64Remainder.c +++ b/MdePkg/Library/BaseLib/DivS64x64Remainder.c @@ -38,7 +38,7 @@ EFIAPI DivS64x64Remainder (
IN INT64 Dividend,
IN INT64 Divisor,
- OUT INT64 *Remainder
+ OUT INT64 *Remainder OPTIONAL
)
{
ASSERT (Divisor != 0);
diff --git a/MdePkg/Library/BaseLib/DivU64x32Remainder.c b/MdePkg/Library/BaseLib/DivU64x32Remainder.c index aa34b31e46..e7a3094c6e 100644 --- a/MdePkg/Library/BaseLib/DivU64x32Remainder.c +++ b/MdePkg/Library/BaseLib/DivU64x32Remainder.c @@ -38,7 +38,7 @@ EFIAPI DivU64x32Remainder (
IN UINT64 Dividend,
IN UINT32 Divisor,
- OUT UINT32 *Remainder
+ OUT UINT32 *Remainder OPTIONAL
)
{
ASSERT (Divisor != 0);
diff --git a/MdePkg/Library/BaseLib/DivU64x64Remainder.c b/MdePkg/Library/BaseLib/DivU64x64Remainder.c index 0caa5295aa..c39537e4fb 100644 --- a/MdePkg/Library/BaseLib/DivU64x64Remainder.c +++ b/MdePkg/Library/BaseLib/DivU64x64Remainder.c @@ -38,7 +38,7 @@ EFIAPI DivU64x64Remainder (
IN UINT64 Dividend,
IN UINT64 Divisor,
- OUT UINT64 *Remainder
+ OUT UINT64 *Remainder OPTIONAL
)
{
ASSERT (Divisor != 0);
diff --git a/MdePkg/Library/BaseLib/Ebc/SetJumpLongJump.c b/MdePkg/Library/BaseLib/Ebc/SetJumpLongJump.c index ab7716cb94..b485d3e495 100644 --- a/MdePkg/Library/BaseLib/Ebc/SetJumpLongJump.c +++ b/MdePkg/Library/BaseLib/Ebc/SetJumpLongJump.c @@ -14,12 +14,35 @@ **/
+/**
+ Worker function that checks ASSERT condition for JumpBuffer
+
+ Checks ASSERT condition for JumpBuffer.
+
+ If JumpBuffer is NULL, then ASSERT().
+ For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
+
+ @param JumpBuffer A pointer to CPU context buffer.
+
+**/
VOID
-EFIAPI
InternalAssertJumpBuffer (
IN BASE_LIBRARY_JUMP_BUFFER *JumpBuffer
);
+/**
+ Saves the current CPU context that can be restored with a call to LongJump() and returns 0.
+
+ Saves the current CPU context in the buffer specified by JumpBuffer and returns 0. The initial
+ call to SetJump() must always return 0. Subsequent calls to LongJump() cause a non-zero
+ value to be returned by SetJump().
+
+ If JumpBuffer is NULL, then ASSERT().
+ For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
+
+ @param JumpBuffer A pointer to CPU context buffer.
+
+**/
UINTN
EFIAPI
SetJump (
@@ -30,6 +53,17 @@ SetJump ( return 0;
}
+/**
+ Restores the CPU context that was saved with SetJump().
+
+ Restores the CPU context from the buffer specified by JumpBuffer.
+ This function never returns to the caller.
+ Instead is resumes execution based on the state of JumpBuffer.
+
+ @param JumpBuffer A pointer to CPU context buffer.
+ @param Value The value to return when the SetJump() context is restored.
+
+**/
VOID
EFIAPI
InternalLongJump (
@@ -37,5 +71,8 @@ InternalLongJump ( IN UINTN Value
)
{
+ //
+ // This function cannot work on EBC
+ //
ASSERT (FALSE);
}
diff --git a/MdePkg/Library/BaseLib/Ebc/SwitchStack.c b/MdePkg/Library/BaseLib/Ebc/SwitchStack.c index 8fadd4f384..0a5464b2f9 100644 --- a/MdePkg/Library/BaseLib/Ebc/SwitchStack.c +++ b/MdePkg/Library/BaseLib/Ebc/SwitchStack.c @@ -35,7 +35,6 @@ **/
VOID
-EFIAPI
InternalSwitchStack (
IN SWITCH_STACK_ENTRY_POINT EntryPoint,
IN VOID *Context1, OPTIONAL
diff --git a/MdePkg/Library/BaseLib/Ebc/Synchronization.c b/MdePkg/Library/BaseLib/Ebc/Synchronization.c index df591b287a..5d5bc2ff11 100644 --- a/MdePkg/Library/BaseLib/Ebc/Synchronization.c +++ b/MdePkg/Library/BaseLib/Ebc/Synchronization.c @@ -26,6 +26,22 @@ InternalSyncCompareExchange32 ( ((*Value = ExchangeValue), CompareValue);
}
+/**
+ Performs an atomic compare exchange operation on a 64-bit unsigned integer.
+
+ Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
+ by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and
+ CompareValue is returned. If Value is not equal to CompareValue, then Value is returned.
+ The compare exchange operation must be performed using MP safe mechanisms.
+
+ @param Value A pointer to the 64-bit value for the compare exchange
+ operation.
+ @param CompareValue 64-bit value used in compare operation.
+ @param ExchangeValue 64-bit value used in exchange operation.
+
+ @return The original *Value before exchange.
+
+**/
UINT64
EFIAPI
InternalSyncCompareExchange64 (
@@ -38,6 +54,19 @@ InternalSyncCompareExchange64 ( ((*Value = ExchangeValue), CompareValue);
}
+/**
+ Performs an atomic increment of an 32-bit unsigned integer.
+
+ Performs an atomic increment of the 32-bit unsigned integer specified by
+ Value and returns the incremented value. The increment operation must be
+ performed using MP safe mechanisms. The state of the return value is not
+ guaranteed to be MP safe.
+
+ @param Value A pointer to the 32-bit value to increment.
+
+ @return The incremented value.
+
+**/
UINT32
EFIAPI
InternalSyncIncrement (
@@ -47,6 +76,19 @@ InternalSyncIncrement ( return ++*Value;
}
+/**
+ Performs an atomic decrement of an 32-bit unsigned integer.
+
+ Performs an atomic decrement of the 32-bit unsigned integer specified by
+ Value and returns the decrement value. The decrement operation must be
+ performed using MP safe mechanisms. The state of the return value is not
+ guaranteed to be MP safe.
+
+ @param Value A pointer to the 32-bit value to decrement.
+
+ @return The decrement value.
+
+**/
UINT32
EFIAPI
InternalSyncDecrement (
diff --git a/MdePkg/Library/BaseLib/Ia32/DivS64x64Remainder.c b/MdePkg/Library/BaseLib/Ia32/DivS64x64Remainder.c index 219f48f321..a5183429c1 100644 --- a/MdePkg/Library/BaseLib/Ia32/DivS64x64Remainder.c +++ b/MdePkg/Library/BaseLib/Ia32/DivS64x64Remainder.c @@ -16,12 +16,28 @@ #include "../BaseLibInternals.h"
+/**
+ Worker function that Divides a 64-bit signed integer by a 64-bit signed integer and
+ generates a 64-bit signed result and a optional 64-bit signed remainder.
+
+ This function divides the 64-bit unsigned value Dividend by the 64-bit
+ unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
+ is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
+ This function returns the 64-bit unsigned quotient.
+
+ @param Dividend A 64-bit signed value.
+ @param Divisor A 64-bit signed value.
+ @param Remainder A pointer to a 64-bit signed value. This parameter is
+ optional and may be NULL.
+
+ @return Dividend / Divisor
+
+**/
INT64
-EFIAPI
InternalMathDivRemS64x64 (
IN INT64 Dividend,
IN INT64 Divisor,
- OUT INT64 *Remainder
+ OUT INT64 *Remainder OPTIONAL
)
{
INT64 Quot;
diff --git a/MdePkg/Library/BaseLib/Ia32/InternalSwitchStack.c b/MdePkg/Library/BaseLib/Ia32/InternalSwitchStack.c index ab8116b4b5..484313ea67 100644 --- a/MdePkg/Library/BaseLib/Ia32/InternalSwitchStack.c +++ b/MdePkg/Library/BaseLib/Ia32/InternalSwitchStack.c @@ -32,7 +32,6 @@ **/
VOID
-EFIAPI
InternalSwitchStack (
IN SWITCH_STACK_ENTRY_POINT EntryPoint,
IN VOID *Context1,
diff --git a/MdePkg/Library/BaseLib/Ia32/Non-existing.c b/MdePkg/Library/BaseLib/Ia32/Non-existing.c index b4e50e9d7b..89ba2f2ced 100644 --- a/MdePkg/Library/BaseLib/Ia32/Non-existing.c +++ b/MdePkg/Library/BaseLib/Ia32/Non-existing.c @@ -16,6 +16,33 @@ #include "../BaseLibInternals.h"
+
+/**
+ Disables the 64-bit paging mode on the CPU.
+
+ Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
+ mode. This function assumes the current execution mode is 64-paging mode.
+ This function is only available on X64. After the 64-bit paging mode is
+ disabled, control is transferred to the function specified by EntryPoint
+ using the new stack specified by NewStack and passing in the parameters
+ specified by Context1 and Context2. Context1 and Context2 are optional and
+ may be 0. The function EntryPoint must never return.
+
+ @param Cs The 16-bit selector to load in the CS before EntryPoint
+ is called. The descriptor in the GDT that this selector
+ references must be setup for 32-bit protected mode.
+ @param EntryPoint The 64-bit virtual address of the function to call with
+ the new stack after paging is disabled.
+ @param Context1 The 64-bit virtual address of the context to pass into
+ the EntryPoint function as the first parameter after
+ paging is disabled.
+ @param Context2 The 64-bit virtual address of the context to pass into
+ the EntryPoint function as the second parameter after
+ paging is disabled.
+ @param NewStack The 64-bit virtual address of the new stack to use for
+ the EntryPoint function after paging is disabled.
+
+**/
VOID
EFIAPI
InternalX86DisablePaging64 (
@@ -26,5 +53,8 @@ InternalX86DisablePaging64 ( IN UINT32 NewStack
)
{
+ //
+ // This function cannot work on IA32 platform
+ //
ASSERT (FALSE);
}
diff --git a/MdePkg/Library/BaseLib/Ipf/Synchronization.c b/MdePkg/Library/BaseLib/Ipf/Synchronization.c index f09dbd5c00..44593e1778 100644 --- a/MdePkg/Library/BaseLib/Ipf/Synchronization.c +++ b/MdePkg/Library/BaseLib/Ipf/Synchronization.c @@ -14,6 +14,23 @@ **/
+/**
+ Performs an atomic compare exchange operation on a 32-bit unsigned integer.
+
+ Performs an atomic compare exchange operation on the 32-bit unsigned integer
+ specified by Value. If Value is equal to CompareValue, then Value is set to
+ ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,
+ then Value is returned. The compare exchange operation must be performed using
+ MP safe mechanisms.
+
+ @param Value A pointer to the 32-bit value for the compare exchange
+ operation.
+ @param CompareValue 32-bit value used in compare operation.
+ @param ExchangeValue 32-bit value used in exchange operation.
+
+ @return The original *Value before exchange.
+
+**/
UINT32
EFIAPI
InternalSyncCompareExchange32 (
@@ -22,6 +39,19 @@ InternalSyncCompareExchange32 ( IN UINT32 ExchangeValue
);
+/**
+ Performs an atomic increment of an 32-bit unsigned integer.
+
+ Performs an atomic increment of the 32-bit unsigned integer specified by
+ Value and returns the incremented value. The increment operation must be
+ performed using MP safe mechanisms. The state of the return value is not
+ guaranteed to be MP safe.
+
+ @param Value A pointer to the 32-bit value to increment.
+
+ @return The incremented value.
+
+**/
UINT32
EFIAPI
InternalSyncIncrement (
@@ -40,6 +70,19 @@ InternalSyncIncrement ( return OriginalValue + 1;
}
+/**
+ Performs an atomic decrement of an 32-bit unsigned integer.
+
+ Performs an atomic decrement of the 32-bit unsigned integer specified by
+ Value and returns the decrement value. The decrement operation must be
+ performed using MP safe mechanisms. The state of the return value is not
+ guaranteed to be MP safe.
+
+ @param Value A pointer to the 32-bit value to decrement.
+
+ @return The decrement value.
+
+**/
UINT32
EFIAPI
InternalSyncDecrement (
diff --git a/MdePkg/Library/BaseLib/LinkedList.c b/MdePkg/Library/BaseLib/LinkedList.c index 15ceb584db..6c083ef95c 100644 --- a/MdePkg/Library/BaseLib/LinkedList.c +++ b/MdePkg/Library/BaseLib/LinkedList.c @@ -14,6 +14,27 @@ **/
+/**
+ Worker function that locates the Node in the List
+
+ By searching the List, finds the location of the Node in List. At the same time,
+ verifies the validity of this list.
+
+ If List is NULL, then ASSERT().
+ If List->ForwardLink is NULL, then ASSERT().
+ If List->backLink is NULL, then ASSERT().
+ If Node is NULL, then ASSERT();
+ If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number
+ of nodes in ListHead, including the ListHead node, is greater than or
+ equal to PcdMaximumLinkedListLength, then ASSERT().
+
+ @param List A pointer to a node in a linked list.
+ @param Node A pointer to one nod.
+
+ @retval TRUE Node is in List
+ @retval FALSE Node isn't in List, or List is invalid
+
+**/
BOOLEAN
EFIAPI
IsNodeInList (
diff --git a/MdePkg/Library/BaseLib/LongJump.c b/MdePkg/Library/BaseLib/LongJump.c index 85f091e090..a18c974e91 100644 --- a/MdePkg/Library/BaseLib/LongJump.c +++ b/MdePkg/Library/BaseLib/LongJump.c @@ -14,12 +14,33 @@ **/
+/**
+ Worker function that checks ASSERT condition for JumpBuffer
+
+ Checks ASSERT condition for JumpBuffer.
+
+ If JumpBuffer is NULL, then ASSERT().
+ For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
+
+ @param JumpBuffer A pointer to CPU context buffer.
+
+**/
VOID
-EFIAPI
InternalAssertJumpBuffer (
IN BASE_LIBRARY_JUMP_BUFFER *JumpBuffer
);
+/**
+ Restores the CPU context that was saved with SetJump().
+
+ Restores the CPU context from the buffer specified by JumpBuffer.
+ This function never returns to the caller.
+ Instead is resumes execution based on the state of JumpBuffer.
+
+ @param JumpBuffer A pointer to CPU context buffer.
+ @param Value The value to return when the SetJump() context is restored.
+
+**/
VOID
EFIAPI
InternalLongJump (
@@ -35,6 +56,7 @@ InternalLongJump ( Instead is resumes execution based on the state of JumpBuffer.
If JumpBuffer is NULL, then ASSERT().
+ For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
If Value is 0, then ASSERT().
@param JumpBuffer A pointer to CPU context buffer.
diff --git a/MdePkg/Library/BaseLib/Math64.c b/MdePkg/Library/BaseLib/Math64.c index 57dcca387f..a8756967be 100644 --- a/MdePkg/Library/BaseLib/Math64.c +++ b/MdePkg/Library/BaseLib/Math64.c @@ -15,8 +15,20 @@ **/
+/**
+ Worker functons that shifts a 64-bit integer left between 0 and 63 bits. The low bits
+ are filled with zeros. The shifted value is returned.
+
+ This function shifts the 64-bit value Operand to the left by Count bits. The
+ low Count bits are set to zero. The shifted value is returned.
+
+ @param Operand The 64-bit operand to shift left.
+ @param Count The number of bits to shift left.
+
+ @return Operand << Count
+
+**/
UINT64
-EFIAPI
InternalMathLShiftU64 (
IN UINT64 Operand,
IN UINTN Count
@@ -25,6 +37,19 @@ InternalMathLShiftU64 ( return Operand << Count;
}
+/**
+ Worker functon that shifts a 64-bit integer right between 0 and 63 bits. This high bits
+ are filled with zeros. The shifted value is returned.
+
+ This function shifts the 64-bit value Operand to the right by Count bits. The
+ high Count bits are set to zero. The shifted value is returned.
+
+ @param Operand The 64-bit operand to shift right.
+ @param Count The number of bits to shift right.
+
+ @return Operand >> Count
+
+**/
UINT64
EFIAPI
InternalMathRShiftU64 (
@@ -35,6 +60,21 @@ InternalMathRShiftU64 ( return Operand >> Count;
}
+/**
+ Worker function that shifts a 64-bit integer right between 0 and 63 bits. The high bits
+ are filled with original integer's bit 63. The shifted value is returned.
+
+ This function shifts the 64-bit value Operand to the right by Count bits. The
+ high Count bits are set to bit 63 of Operand. The shifted value is returned.
+
+ If Count is greater than 63, then ASSERT().
+
+ @param Operand The 64-bit operand to shift right.
+ @param Count The number of bits to shift right.
+
+ @return Operand arithmetically shifted right by Count
+
+**/
UINT64
EFIAPI
InternalMathARShiftU64 (
@@ -59,6 +99,21 @@ InternalMathARShiftU64 ( ((INTN)Operand < 0 ? ~((UINTN)-1 >> Count) : 0);
}
+
+/**
+ Worker function that rotates a 64-bit integer left between 0 and 63 bits, filling
+ the low bits with the high bits that were rotated.
+
+ This function rotates the 64-bit value Operand to the left by Count bits. The
+ low Count bits are fill with the high Count bits of Operand. The rotated
+ value is returned.
+
+ @param Operand The 64-bit operand to rotate left.
+ @param Count The number of bits to rotate left.
+
+ @return Operand <<< Count
+
+**/
UINT64
EFIAPI
InternalMathLRotU64 (
@@ -69,6 +124,20 @@ InternalMathLRotU64 ( return (Operand << Count) | (Operand >> (64 - Count));
}
+/**
+ Worker function that rotates a 64-bit integer right between 0 and 63 bits, filling
+ the high bits with the high low bits that were rotated.
+
+ This function rotates the 64-bit value Operand to the right by Count bits.
+ The high Count bits are fill with the low Count bits of Operand. The rotated
+ value is returned.
+
+ @param Operand The 64-bit operand to rotate right.
+ @param Count The number of bits to rotate right.
+
+ @return Operand >>> Count
+
+**/
UINT64
EFIAPI
InternalMathRRotU64 (
@@ -79,6 +148,18 @@ InternalMathRRotU64 ( return (Operand >> Count) | (Operand << (64 - Count));
}
+/**
+ Worker function that switches the endianess of a 64-bit integer.
+
+ This function swaps the bytes in a 64-bit unsigned value to switch the value
+ from little endian to big endian or vice versa. The byte swapped value is
+ returned.
+
+ @param Operand A 64-bit unsigned value.
+
+ @return The byte swaped Operand.
+
+**/
UINT64
EFIAPI
InternalMathSwapBytes64 (
@@ -91,6 +172,20 @@ InternalMathSwapBytes64 ( );
}
+/**
+ Worker function that multiples a 64-bit unsigned integer by a 32-bit unsigned integer
+ and generates a 64-bit unsigned result.
+
+ This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
+ unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
+ bit unsigned result is returned.
+
+ @param Multiplicand A 64-bit unsigned value.
+ @param Multiplier A 32-bit unsigned value.
+
+ @return Multiplicand * Multiplier
+
+**/
UINT64
EFIAPI
InternalMathMultU64x32 (
@@ -101,6 +196,21 @@ InternalMathMultU64x32 ( return Multiplicand * Multiplier;
}
+
+/**
+ Worker function that multiples a 64-bit unsigned integer by a 64-bit unsigned integer
+ and generates a 64-bit unsigned result.
+
+ This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
+ unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
+ bit unsigned result is returned.
+
+ @param Multiplicand A 64-bit unsigned value.
+ @param Multiplier A 64-bit unsigned value.
+
+ @return Multiplicand * Multiplier
+
+**/
UINT64
EFIAPI
InternalMathMultU64x64 (
@@ -111,6 +221,20 @@ InternalMathMultU64x64 ( return Multiplicand * Multiplier;
}
+/**
+ Worker function that divides a 64-bit unsigned integer by a 32-bit unsigned integer and
+ generates a 64-bit unsigned result.
+
+ This function divides the 64-bit unsigned value Dividend by the 32-bit
+ unsigned value Divisor and generates a 64-bit unsigned quotient. This
+ function returns the 64-bit unsigned quotient.
+
+ @param Dividend A 64-bit unsigned value.
+ @param Divisor A 32-bit unsigned value.
+
+ @return Dividend / Divisor
+
+**/
UINT64
EFIAPI
InternalMathDivU64x32 (
@@ -121,8 +245,21 @@ InternalMathDivU64x32 ( return Dividend / Divisor;
}
+/**
+ Worker function that divides a 64-bit unsigned integer by a 32-bit unsigned integer
+ and generates a 32-bit unsigned remainder.
+
+ This function divides the 64-bit unsigned value Dividend by the 32-bit
+ unsigned value Divisor and generates a 32-bit remainder. This function
+ returns the 32-bit unsigned remainder.
+
+ @param Dividend A 64-bit unsigned value.
+ @param Divisor A 32-bit unsigned value.
+
+ @return Dividend % Divisor
+
+**/
UINT32
-EFIAPI
InternalMathModU64x32 (
IN UINT64 Dividend,
IN UINT32 Divisor
@@ -131,12 +268,28 @@ InternalMathModU64x32 ( return (UINT32)(Dividend % Divisor);
}
+/**
+ Worker function that divides a 64-bit unsigned integer by a 32-bit unsigned integer and
+ generates a 64-bit unsigned result and an optional 32-bit unsigned remainder.
+
+ This function divides the 64-bit unsigned value Dividend by the 32-bit
+ unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
+ is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
+ This function returns the 64-bit unsigned quotient.
+
+ @param Dividend A 64-bit unsigned value.
+ @param Divisor A 32-bit unsigned value.
+ @param Remainder A pointer to a 32-bit unsigned value. This parameter is
+ optional and may be NULL.
+
+ @return Dividend / Divisor
+
+**/
UINT64
-EFIAPI
InternalMathDivRemU64x32 (
IN UINT64 Dividend,
IN UINT32 Divisor,
- OUT UINT32 *Remainder
+ OUT UINT32 *Remainder OPTIONAL
)
{
if (Remainder != NULL) {
@@ -145,12 +298,28 @@ InternalMathDivRemU64x32 ( return Dividend / Divisor;
}
+/**
+ Worker function that divides a 64-bit unsigned integer by a 64-bit unsigned integer and
+ generates a 64-bit unsigned result and an optional 64-bit unsigned remainder.
+
+ This function divides the 64-bit unsigned value Dividend by the 64-bit
+ unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
+ is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
+ This function returns the 64-bit unsigned quotient.
+
+ @param Dividend A 64-bit unsigned value.
+ @param Divisor A 64-bit unsigned value.
+ @param Remainder A pointer to a 64-bit unsigned value. This parameter is
+ optional and may be NULL.
+
+ @return Dividend / Divisor
+
+**/
UINT64
-EFIAPI
InternalMathDivRemU64x64 (
IN UINT64 Dividend,
IN UINT64 Divisor,
- OUT UINT64 *Remainder
+ OUT UINT64 *Remainder OPTIONAL
)
{
if (Remainder != NULL) {
@@ -159,12 +328,28 @@ InternalMathDivRemU64x64 ( return Dividend / Divisor;
}
+/**
+ Worker function that divides a 64-bit signed integer by a 64-bit signed integer and
+ generates a 64-bit signed result and a optional 64-bit signed remainder.
+
+ This function divides the 64-bit unsigned value Dividend by the 64-bit
+ unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
+ is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
+ This function returns the 64-bit unsigned quotient.
+
+ @param Dividend A 64-bit signed value.
+ @param Divisor A 64-bit signed value.
+ @param Remainder A pointer to a 64-bit signed value. This parameter is
+ optional and may be NULL.
+
+ @return Dividend / Divisor
+
+**/
INT64
-EFIAPI
InternalMathDivRemS64x64 (
IN INT64 Dividend,
IN INT64 Divisor,
- OUT INT64 *Remainder
+ OUT INT64 *Remainder OPTIONAL
)
{
if (Remainder != NULL) {
diff --git a/MdePkg/Library/BaseLib/MultU64x32.c b/MdePkg/Library/BaseLib/MultU64x32.c index 4c30472bfa..c3a25c6f34 100644 --- a/MdePkg/Library/BaseLib/MultU64x32.c +++ b/MdePkg/Library/BaseLib/MultU64x32.c @@ -22,8 +22,6 @@ unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
bit unsigned result is returned.
- If the result overflows, then ASSERT().
-
@param Multiplicand A 64-bit unsigned value.
@param Multiplier A 32-bit unsigned value.
@@ -40,6 +38,6 @@ MultU64x32 ( UINT64 Result;
Result = InternalMathMultU64x32 (Multiplicand, Multiplier);
- // TODO: ASSERT (Result not overflow);
+
return Result;
}
diff --git a/MdePkg/Library/BaseLib/MultU64x64.c b/MdePkg/Library/BaseLib/MultU64x64.c index 6324c3e335..997abbc27e 100644 --- a/MdePkg/Library/BaseLib/MultU64x64.c +++ b/MdePkg/Library/BaseLib/MultU64x64.c @@ -22,8 +22,6 @@ unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
bit unsigned result is returned.
- If the result overflows, then ASSERT().
-
@param Multiplicand A 64-bit unsigned value.
@param Multiplier A 64-bit unsigned value.
@@ -40,6 +38,6 @@ MultU64x64 ( UINT64 Result;
Result = InternalMathMultU64x64 (Multiplicand, Multiplier);
- // TODO: ASSERT (Result not overflow);
+
return Result;
}
diff --git a/MdePkg/Library/BaseLib/SetJump.c b/MdePkg/Library/BaseLib/SetJump.c index ea70641ec2..8bac97ab47 100644 --- a/MdePkg/Library/BaseLib/SetJump.c +++ b/MdePkg/Library/BaseLib/SetJump.c @@ -10,12 +10,22 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- Module Name: SetJumpLongJump.c
+ Module Name: SetJump.c
**/
+/**
+ Worker function that checks ASSERT condition for JumpBuffer
+
+ Checks ASSERT condition for JumpBuffer.
+
+ If JumpBuffer is NULL, then ASSERT().
+ For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
+
+ @param JumpBuffer A pointer to CPU context buffer.
+
+**/
VOID
-EFIAPI
InternalAssertJumpBuffer (
IN BASE_LIBRARY_JUMP_BUFFER *JumpBuffer
)
diff --git a/MdePkg/Library/BaseLib/String.c b/MdePkg/Library/BaseLib/String.c index a59a9d08cb..2ac32254fc 100644 --- a/MdePkg/Library/BaseLib/String.c +++ b/MdePkg/Library/BaseLib/String.c @@ -617,9 +617,21 @@ AsciiStrCmp ( return *FirstString - *SecondString;
}
+/**
+ Converts a lowercase Ascii character to upper one
+
+ If Chr is lowercase Ascii character, then converts it to upper one.
+
+ If Value >= 0xA0, then ASSERT().
+ If (Value & 0x0F) >= 0x0A, then ASSERT().
+
+ @param chr one Ascii character
+
+ @return The uppercase value of Ascii character
+
+**/
STATIC
CHAR8
-EFIAPI
AsciiToUpper (
IN CHAR8 Chr
)
diff --git a/MdePkg/Library/BaseLib/SwitchStack.c b/MdePkg/Library/BaseLib/SwitchStack.c index 353efa8f6e..98d832dfd6 100644 --- a/MdePkg/Library/BaseLib/SwitchStack.c +++ b/MdePkg/Library/BaseLib/SwitchStack.c @@ -26,6 +26,7 @@ If EntryPoint is NULL, then ASSERT().
If NewStack is NULL, then ASSERT().
+ For IPF CPUs, if NewStack is not aligned on a 16-byte boundary, then ASSERT().
@param EntryPoint A pointer to function to call with the new stack.
@param Context1 A pointer to the context to pass into the EntryPoint
diff --git a/MdePkg/Library/BaseLib/Synchronization.c b/MdePkg/Library/BaseLib/Synchronization.c index 0d51956d74..cf001ce4d1 100644 --- a/MdePkg/Library/BaseLib/Synchronization.c +++ b/MdePkg/Library/BaseLib/Synchronization.c @@ -17,18 +17,61 @@ #define SPIN_LOCK_RELEASED ((SPIN_LOCK)1)
#define SPIN_LOCK_ACQUIRED ((SPIN_LOCK)2)
+/**
+ Performs an atomic increment of an 32-bit unsigned integer.
+
+ Performs an atomic increment of the 32-bit unsigned integer specified by
+ Value and returns the incremented value. The increment operation must be
+ performed using MP safe mechanisms. The state of the return value is not
+ guaranteed to be MP safe.
+
+ @param Value A pointer to the 32-bit value to increment.
+
+ @return The incremented value.
+
+**/
UINT32
EFIAPI
InternalSyncIncrement (
IN volatile UINT32 *Value
);
+/**
+ Performs an atomic decrement of an 32-bit unsigned integer.
+
+ Performs an atomic decrement of the 32-bit unsigned integer specified by
+ Value and returns the decrement value. The decrement operation must be
+ performed using MP safe mechanisms. The state of the return value is not
+ guaranteed to be MP safe.
+
+ @param Value A pointer to the 32-bit value to decrement.
+
+ @return The decrement value.
+
+**/
UINT32
EFIAPI
InternalSyncDecrement (
IN volatile UINT32 *Value
);
+/**
+ Performs an atomic compare exchange operation on a 32-bit unsigned integer.
+
+ Performs an atomic compare exchange operation on the 32-bit unsigned integer
+ specified by Value. If Value is equal to CompareValue, then Value is set to
+ ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,
+ then Value is returned. The compare exchange operation must be performed using
+ MP safe mechanisms.
+
+ @param Value A pointer to the 32-bit value for the compare exchange
+ operation.
+ @param CompareValue 32-bit value used in compare operation.
+ @param ExchangeValue 32-bit value used in exchange operation.
+
+ @return The original *Value before exchange.
+
+**/
UINT32
EFIAPI
InternalSyncCompareExchange32 (
@@ -37,6 +80,22 @@ InternalSyncCompareExchange32 ( IN UINT32 ExchangeValue
);
+/**
+ Performs an atomic compare exchange operation on a 64-bit unsigned integer.
+
+ Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
+ by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and
+ CompareValue is returned. If Value is not equal to CompareValue, then Value is returned.
+ The compare exchange operation must be performed using MP safe mechanisms.
+
+ @param Value A pointer to the 64-bit value for the compare exchange
+ operation.
+ @param CompareValue 64-bit value used in compare operation.
+ @param ExchangeValue 64-bit value used in exchange operation.
+
+ @return The original *Value before exchange.
+
+**/
UINT64
EFIAPI
InternalSyncCompareExchange64 (
@@ -267,6 +326,14 @@ InterlockedDecrement ( /**
Performs an atomic compare exchange operation on a 32-bit unsigned integer.
+ Performs an atomic compare exchange operation on the 32-bit unsigned integer
+ specified by Value. If Value is equal to CompareValue, then Value is set to
+ ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue,
+ then Value is returned. The compare exchange operation must be performed using
+ MP safe mechanisms.
+
+ If Value is NULL, then ASSERT().
+
@param Value A pointer to the 32-bit value for the compare exchange
operation.
@param CompareValue 32-bit value used in compare operation.
@@ -290,6 +357,13 @@ InterlockedCompareExchange32 ( /**
Performs an atomic compare exchange operation on a 64-bit unsigned integer.
+ Performs an atomic compare exchange operation on the 64-bit unsigned integer specified
+ by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and
+ CompareValue is returned. If Value is not equal to CompareValue, then Value is returned.
+ The compare exchange operation must be performed using MP safe mechanisms.
+
+ If Value is NULL, then ASSERT().
+
@param Value A pointer to the 64-bit value for the compare exchange
operation.
@param CompareValue 64-bit value used in compare operation.
diff --git a/MdePkg/Library/BaseLib/X64/Non-existing.c b/MdePkg/Library/BaseLib/X64/Non-existing.c index fc4fd43898..a1c4677dad 100644 --- a/MdePkg/Library/BaseLib/X64/Non-existing.c +++ b/MdePkg/Library/BaseLib/X64/Non-existing.c @@ -16,6 +16,39 @@ #include "../BaseLibInternals.h"
+/**
+ Enables the 32-bit paging mode on the CPU.
+
+ Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
+ must be properly initialized prior to calling this service. This function
+ assumes the current execution mode is 32-bit protected mode. This function is
+ only available on IA-32. After the 32-bit paging mode is enabled, control is
+ transferred to the function specified by EntryPoint using the new stack
+ specified by NewStack and passing in the parameters specified by Context1 and
+ Context2. Context1 and Context2 are optional and may be NULL. The function
+ EntryPoint must never return.
+
+ There are a number of constraints that must be followed before calling this
+ function:
+ 1) Interrupts must be disabled.
+ 2) The caller must be in 32-bit protected mode with flat descriptors. This
+ means all descriptors must have a base of 0 and a limit of 4GB.
+ 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
+ descriptors.
+ 4) CR3 must point to valid page tables that will be used once the transition
+ is complete, and those page tables must guarantee that the pages for this
+ function and the stack are identity mapped.
+
+ @param EntryPoint A pointer to function to call with the new stack after
+ paging is enabled.
+ @param Context1 A pointer to the context to pass into the EntryPoint
+ function as the first parameter after paging is enabled.
+ @param Context2 A pointer to the context to pass into the EntryPoint
+ function as the second parameter after paging is enabled.
+ @param NewStack A pointer to the new stack to use for the EntryPoint
+ function after paging is enabled.
+
+**/
VOID
EFIAPI
InternalX86EnablePaging32 (
@@ -25,9 +58,42 @@ InternalX86EnablePaging32 ( IN VOID *NewStack
)
{
+ //
+ // This function cannot work on X64 platform
+ //
ASSERT (FALSE);
}
+/**
+ Disables the 32-bit paging mode on the CPU.
+
+ Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
+ mode. This function assumes the current execution mode is 32-paged protected
+ mode. This function is only available on IA-32. After the 32-bit paging mode
+ is disabled, control is transferred to the function specified by EntryPoint
+ using the new stack specified by NewStack and passing in the parameters
+ specified by Context1 and Context2. Context1 and Context2 are optional and
+ may be NULL. The function EntryPoint must never return.
+
+ There are a number of constraints that must be followed before calling this
+ function:
+ 1) Interrupts must be disabled.
+ 2) The caller must be in 32-bit paged mode.
+ 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
+ 4) CR3 must point to valid page tables that guarantee that the pages for
+ this function and the stack are identity mapped.
+
+ @param EntryPoint A pointer to function to call with the new stack after
+ paging is disabled.
+ @param Context1 A pointer to the context to pass into the EntryPoint
+ function as the first parameter after paging is disabled.
+ @param Context2 A pointer to the context to pass into the EntryPoint
+ function as the second parameter after paging is
+ disabled.
+ @param NewStack A pointer to the new stack to use for the EntryPoint
+ function after paging is disabled.
+
+**/
VOID
EFIAPI
InternalX86DisablePaging32 (
@@ -37,9 +103,39 @@ InternalX86DisablePaging32 ( IN VOID *NewStack
)
{
+ //
+ // This function cannot work on X64 platform
+ //
ASSERT (FALSE);
}
+/**
+ Enables the 64-bit paging mode on the CPU.
+
+ Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
+ must be properly initialized prior to calling this service. This function
+ assumes the current execution mode is 32-bit protected mode with flat
+ descriptors. This function is only available on IA-32. After the 64-bit
+ paging mode is enabled, control is transferred to the function specified by
+ EntryPoint using the new stack specified by NewStack and passing in the
+ parameters specified by Context1 and Context2. Context1 and Context2 are
+ optional and may be 0. The function EntryPoint must never return.
+
+ @param Cs The 16-bit selector to load in the CS before EntryPoint
+ is called. The descriptor in the GDT that this selector
+ references must be setup for long mode.
+ @param EntryPoint The 64-bit virtual address of the function to call with
+ the new stack after paging is enabled.
+ @param Context1 The 64-bit virtual address of the context to pass into
+ the EntryPoint function as the first parameter after
+ paging is enabled.
+ @param Context2 The 64-bit virtual address of the context to pass into
+ the EntryPoint function as the second parameter after
+ paging is enabled.
+ @param NewStack The 64-bit virtual address of the new stack to use for
+ the EntryPoint function after paging is enabled.
+
+**/
VOID
EFIAPI
InternalX86EnablePaging64 (
@@ -50,5 +146,8 @@ InternalX86EnablePaging64 ( IN UINT64 NewStack
)
{
+ //
+ // This function cannot work on X64 platform
+ //
ASSERT (FALSE);
}
diff --git a/MdePkg/Library/BaseLib/x86LowLevel.c b/MdePkg/Library/BaseLib/x86LowLevel.c index 391fbbf93f..28193044bc 100644 --- a/MdePkg/Library/BaseLib/x86LowLevel.c +++ b/MdePkg/Library/BaseLib/x86LowLevel.c @@ -988,4 +988,5 @@ MemoryFence ( VOID
)
{
+ return;
}
diff --git a/MdePkg/Library/BaseUefiDecompressLib/BaseUefiDecompressLib.c b/MdePkg/Library/BaseUefiDecompressLib/BaseUefiDecompressLib.c index ee832f0b2f..c0c79c7c4a 100644 --- a/MdePkg/Library/BaseUefiDecompressLib/BaseUefiDecompressLib.c +++ b/MdePkg/Library/BaseUefiDecompressLib/BaseUefiDecompressLib.c @@ -69,9 +69,11 @@ typedef struct { } SCRATCH_DATA;
/**
+ Read NumOfBit of bits from source into mBitBuf
+
Shift mBitBuf NumOfBits left. Read in NumOfBits of bits from source.
- @param Sd The global scratch data
+ @param Sd The global scratch data
@param NumOfBits The number of bits to shift and read.
**/
@@ -81,8 +83,14 @@ FillBuf ( IN UINT16 NumOfBits
)
{
+ //
+ // Left shift NumOfBits of bits in advance
+ //
Sd->mBitBuf = (UINT32) (Sd->mBitBuf << NumOfBits);
+ //
+ // Copy data needed in bytes into mSbuBitBuf
+ //
while (NumOfBits > Sd->mBitCount) {
Sd->mBitBuf |= (UINT32) (Sd->mSubBitBuf << (NumOfBits = (UINT16) (NumOfBits - Sd->mBitCount)));
@@ -92,7 +100,6 @@ FillBuf ( // Get 1 byte into SubBitBuf
//
Sd->mCompSize--;
- Sd->mSubBitBuf = 0;
Sd->mSubBitBuf = Sd->mSrcBase[Sd->mInBuf++];
Sd->mBitCount = 8;
@@ -106,16 +113,25 @@ FillBuf ( }
}
+ //
+ // Caculate additional bit count read to update mBitCount
+ //
Sd->mBitCount = (UINT16) (Sd->mBitCount - NumOfBits);
+
+ //
+ // Copy NumOfBits of bits from mSubBitBuf into mBitBuf
+ //
Sd->mBitBuf |= Sd->mSubBitBuf >> Sd->mBitCount;
}
/**
+ Get NumOfBits of bits out from mBitBuf
+
Get NumOfBits of bits out from mBitBuf. Fill mBitBuf with subsequent
NumOfBits of bits from source. Returns NumOfBits of bits that are
popped out.
- @param Sd The global scratch data.
+ @param Sd The global scratch data.
@param NumOfBits The number of bits to pop and read.
@return The bits that are popped out.
@@ -129,8 +145,14 @@ GetBits ( {
UINT32 OutBits;
+ //
+ // Pop NumOfBits of Bits from Left
+ //
OutBits = (UINT32) (Sd->mBitBuf >> (BITBUFSIZ - NumOfBits));
+ //
+ // Fill up mBitBuf from source
+ //
FillBuf (Sd, NumOfBits);
return OutBits;
@@ -139,11 +161,14 @@ GetBits ( /**
Creates Huffman Code mapping table according to code length array.
- @param Sd The global scratch data
+ Creates Huffman Code mapping table for Extra Set, Char&Len Set
+ and Position Set according to code length array.
+
+ @param Sd The global scratch data
@param NumOfChar Number of symbols in the symbol set
- @param BitLen Code length array
+ @param BitLen Code length array
@param TableBits The width of the mapping table
- @param Table The table
+ @param Table The table
@retval 0 OK.
@retval BAD_TABLE The table is corrupted.
@@ -266,6 +291,8 @@ MakeTable ( /**
Decodes a position value.
+ Get a position value according to Position Huffman Table.
+
@param Sd the global scratch data
@return The position value decoded.
@@ -312,9 +339,12 @@ DecodeP ( /**
Reads code lengths for the Extra Set or the Position Set.
- @param Sd The global scratch data.
- @param nn Number of symbols.
- @param nbit Number of bits needed to represent nn.
+ Read in the Extra Set or Pointion Set Length Arrary, then
+ generate the Huffman code mapping for them.
+
+ @param Sd The global scratch data.
+ @param nn Number of symbols.
+ @param nbit Number of bits needed to represent nn.
@param Special The special symbol that needs to be taken care of.
@retval 0 OK.
@@ -334,9 +364,15 @@ ReadPTLen ( volatile UINT16 Index;
UINT32 Mask;
+ //
+ // Read Extra Set Code Length Array size
+ //
Number = (UINT16) GetBits (Sd, nbit);
if (Number == 0) {
+ //
+ // This represents only Huffman code used
+ //
CharC = (UINT16) GetBits (Sd, nbit);
for (Index = 0; Index < 256; Index++) {
@@ -356,6 +392,11 @@ ReadPTLen ( CharC = (UINT16) (Sd->mBitBuf >> (BITBUFSIZ - 3));
+ //
+ // If a code length is less than 7, then it is encoded as a 3-bit
+ // value. Or it is encoded as a series of "1"s followed by a
+ // terminating "0". The number of "1"s = Code length - 4.
+ //
if (CharC == 7) {
Mask = 1U << (BITBUFSIZ - 1 - 3);
while (Mask & Sd->mBitBuf) {
@@ -363,11 +404,17 @@ ReadPTLen ( CharC += 1;
}
}
-
+
FillBuf (Sd, (UINT16) ((CharC < 7) ? 3 : CharC - 3));
Sd->mPTLen[Index++] = (UINT8) CharC;
-
+
+ //
+ // For Code&Len Set,
+ // After the third length of the code length concatenation,
+ // a 2-bit value is used to indicated the number of consecutive
+ // zero lengths after the third length.
+ //
if (Index == Special) {
CharC = (UINT16) GetBits (Sd, 2);
while ((INT16) (--CharC) >= 0) {
@@ -379,12 +426,15 @@ ReadPTLen ( while (Index < nn) {
Sd->mPTLen[Index++] = 0;
}
-
+
return MakeTable (Sd, nn, Sd->mPTLen, 8, Sd->mPTTable);
}
/**
Reads code lengths for Char&Len Set.
+
+ Read in and decode the Char&Len Set Code Length Array, then
+ generate the Huffman Code mapping table for the Char&Len Set.
@param Sd the global scratch data
@@ -394,14 +444,17 @@ ReadCLen ( SCRATCH_DATA *Sd
)
{
- UINT16 Number;
- UINT16 CharC;
+ UINT16 Number;
+ UINT16 CharC;
volatile UINT16 Index;
- UINT32 Mask;
+ UINT32 Mask;
Number = (UINT16) GetBits (Sd, CBIT);
if (Number == 0) {
+ //
+ // This represents only Huffman code used
+ //
CharC = (UINT16) GetBits (Sd, CBIT);
for (Index = 0; Index < NC; Index++) {
@@ -417,7 +470,6 @@ ReadCLen ( Index = 0;
while (Index < Number) {
-
CharC = Sd->mPTTable[Sd->mBitBuf >> (BITBUFSIZ - 8)];
if (CharC >= NT) {
Mask = 1U << (BITBUFSIZ - 1 - 8);
@@ -471,6 +523,10 @@ ReadCLen ( /**
Decode a character/length value.
+
+ Read one value from mBitBuf, Get one code from mBitBuf. If it is at block boundary, generates
+ Huffman code mapping table for Extra Set, Code&Len Set and
+ Position Set.
@param Sd The global scratch data.
@@ -488,21 +544,38 @@ DecodeC ( if (Sd->mBlockSize == 0) {
//
// Starting a new block
- //
+ // Read BlockSize from block header
+ //
Sd->mBlockSize = (UINT16) GetBits (Sd, 16);
+
+ //
+ // Read in the Extra Set Code Length Arrary,
+ // Generate the Huffman code mapping table for Extra Set.
+ //
Sd->mBadTableFlag = ReadPTLen (Sd, NT, TBIT, 3);
if (Sd->mBadTableFlag != 0) {
return 0;
}
+ //
+ // Read in and decode the Char&Len Set Code Length Arrary,
+ // Generate the Huffman code mapping table for Char&Len Set.
+ //
ReadCLen (Sd);
+ //
+ // Read in the Position Set Code Length Arrary,
+ // Generate the Huffman code mapping table for the Position Set.
+ //
Sd->mBadTableFlag = ReadPTLen (Sd, MAXNP, Sd->mPBit, (UINT16) (-1));
if (Sd->mBadTableFlag != 0) {
return 0;
}
}
+ //
+ // Get one code according to Code&Set Huffman Table
+ //
Sd->mBlockSize--;
Index2 = Sd->mCTable[Sd->mBitBuf >> (BITBUFSIZ - 12)];
@@ -530,6 +603,8 @@ DecodeC ( /**
Decode the source data and put the resulting data into the destination buffer.
+ Decode the source data and put the resulting data into the destination buffer.
+
@param Sd The global scratch data
**/
@@ -547,6 +622,9 @@ Decode ( DataIdx = 0;
for (;;) {
+ //
+ // Get one code from mBitBuf
+ //
CharC = DecodeC (Sd);
if (Sd->mBadTableFlag != 0) {
return ;
@@ -559,6 +637,9 @@ Decode ( if (Sd->mOutBuf >= Sd->mOrigSize) {
return ;
} else {
+ //
+ // Write orignal character into mDstBase
+ //
Sd->mDstBase[Sd->mOutBuf++] = (UINT8) CharC;
}
@@ -567,11 +648,20 @@ Decode ( // Process a Pointer
//
CharC = (UINT16) (CharC - (UINT8_MAX + 1 - THRESHOLD));
-
+
+ //
+ // Get string length
+ //
BytesRemain = CharC;
+ //
+ // Locate string position
+ //
DataIdx = Sd->mOutBuf - DecodeP (Sd) - 1;
+ //
+ // Write BytesRemain of bytes into mDstBase
+ //
BytesRemain--;
while ((INT16) (BytesRemain) >= 0) {
Sd->mDstBase[Sd->mOutBuf++] = Sd->mDstBase[DataIdx++];
@@ -588,14 +678,35 @@ Decode ( }
/**
- The internal implementation of *_DECOMPRESS_PROTOCOL.GetInfo().
-
- @param Source The source buffer containing the compressed data.
- @param SourceSize The size of source buffer
- @param DestinationSize The size of destination buffer.
- @param ScratchSize The size of scratch buffer.
-
- @retval RETURN_SUCCESS The size of destination buffer and the size of scratch buffer are successull retrieved.
+ Retrieves the size of the uncompressed buffer and the size of the scratch buffer.
+
+ Retrieves the size of the uncompressed buffer and the temporary scratch buffer
+ required to decompress the buffer specified by Source and SourceSize.
+ If the size of the uncompressed buffer or the size of the scratch buffer cannot
+ be determined from the compressed data specified by Source and SourceData,
+ then RETURN_INVALID_PARAMETER is returned. Otherwise, the size of the uncompressed
+ buffer is returned in DestinationSize, the size of the scratch buffer is returned
+ in ScratchSize, and RETURN_SUCCESS is returned.
+ This function does not have scratch buffer available to perform a thorough
+ checking of the validity of the source data. It just retrieves the "Original Size"
+ field from the beginning bytes of the source data and output it as DestinationSize.
+ And ScratchSize is specific to the decompression implementation.
+
+ If Source is NULL, then ASSERT().
+ If DestinationSize is NULL, then ASSERT().
+ If ScratchSize is NULL, then ASSERT().
+
+ @param Source The source buffer containing the compressed data.
+ @param SourceSize The size, in bytes, of the source buffer.
+ @param DestinationSize A pointer to the size, in bytes, of the uncompressed buffer
+ that will be generated when the compressed buffer specified
+ by Source and SourceSize is decompressed..
+ @param ScratchSize A pointer to the size, in bytes, of the scratch buffer that
+ is required to decompress the compressed buffer specified
+ by Source and SourceSize.
+
+ @retval RETURN_SUCCESS The size of destination buffer and the size of scratch
+ buffer are successull retrieved.
@retval RETURN_INVALID_PARAMETER The source data is corrupted
**/
@@ -631,12 +742,27 @@ UefiDecompressGetInfo ( }
/**
- The internal implementation of *_DECOMPRESS_PROTOCOL.Decompress().
-
- @param Source The source buffer containing the compressed data.
+ Decompresses a compressed source buffer.
+
+ This function is designed so that the decompression algorithm can be implemented
+ without using any memory services. As a result, this function is not allowed to
+ call any memory allocation services in its implementation. It is the caller¡¯s r
+ esponsibility to allocate and free the Destination and Scratch buffers.
+ If the compressed source data specified by Source is sucessfully decompressed
+ into Destination, then RETURN_SUCCESS is returned. If the compressed source data
+ specified by Source is not in a valid compressed data format,
+ then RETURN_INVALID_PARAMETER is returned.
+
+ If Source is NULL, then ASSERT().
+ If Destination is NULL, then ASSERT().
+ If the required scratch buffer size > 0 and Scratch is NULL, then ASSERT().
+
+ @param Source The source buffer containing the compressed data.
@param Destination The destination buffer to store the decompressed data
- @param Scratch The buffer used internally by the decompress routine. This buffer is needed to store intermediate data.
-
+ @param Scratch A temporary scratch buffer that is used to perform the decompression.
+ This is an optional parameter that may be NULL if the
+ required scratch buffer size is 0.
+
@retval RETURN_SUCCESS Decompression is successfull
@retval RETURN_INVALID_PARAMETER The source data is corrupted
@@ -688,6 +814,9 @@ UefiDecompress ( Sd->mPBit = 4;
Sd->mSrcBase = (UINT8 *)Src;
Sd->mDstBase = Dst;
+ //
+ // CompSize and OrigSize are caculated in bytes
+ //
Sd->mCompSize = CompSize;
Sd->mOrigSize = OrigSize;
|