From: vanjeff Date: Wed, 19 Jul 2006 17:37:07 +0000 (+0000) Subject: 1. added functions header for BaseUefiDecompressLi X-Git-Tag: edk2-stable201903~24821 X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=1ea5ca46c7eefe66a01cb4db3b72fc0e5a04e2cb 1. added functions header for BaseUefiDecompressLi 2. added some internal functions header for BaseLib 3. added EFIAPI for some internal assembly files declare git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@1050 6f19259b-4bc3-4df7-8a09-765794883524 --- 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;