1. added functions header for BaseUefiDecompressLi
authorvanjeff <vanjeff@de2fecce-e211-0410-80a6-f3fac2684e05>
Wed, 19 Jul 2006 17:37:07 +0000 (17:37 +0000)
committervanjeff <vanjeff@de2fecce-e211-0410-80a6-f3fac2684e05>
Wed, 19 Jul 2006 17:37:07 +0000 (17:37 +0000)
2. added some internal functions header for BaseLib
3. added EFIAPI for some internal assembly files declare

git-svn-id: https://edk2.tianocore.org/svn/edk2/trunk@1050 de2fecce-e211-0410-80a6-f3fac2684e05

26 files changed:
edk2/MdePkg/Include/Library/BaseLib.h
edk2/MdePkg/Include/Library/UefiDecompressLib.h
edk2/MdePkg/Library/BaseLib/BaseLibInternals.h
edk2/MdePkg/Library/BaseLib/BitField.c
edk2/MdePkg/Library/BaseLib/DivS64x64Remainder.c
edk2/MdePkg/Library/BaseLib/DivU64x32Remainder.c
edk2/MdePkg/Library/BaseLib/DivU64x64Remainder.c
edk2/MdePkg/Library/BaseLib/Ebc/SetJumpLongJump.c
edk2/MdePkg/Library/BaseLib/Ebc/SwitchStack.c
edk2/MdePkg/Library/BaseLib/Ebc/Synchronization.c
edk2/MdePkg/Library/BaseLib/Ia32/DivS64x64Remainder.c
edk2/MdePkg/Library/BaseLib/Ia32/InternalSwitchStack.c
edk2/MdePkg/Library/BaseLib/Ia32/Non-existing.c
edk2/MdePkg/Library/BaseLib/Ipf/Synchronization.c
edk2/MdePkg/Library/BaseLib/LinkedList.c
edk2/MdePkg/Library/BaseLib/LongJump.c
edk2/MdePkg/Library/BaseLib/Math64.c
edk2/MdePkg/Library/BaseLib/MultU64x32.c
edk2/MdePkg/Library/BaseLib/MultU64x64.c
edk2/MdePkg/Library/BaseLib/SetJump.c
edk2/MdePkg/Library/BaseLib/String.c
edk2/MdePkg/Library/BaseLib/SwitchStack.c
edk2/MdePkg/Library/BaseLib/Synchronization.c
edk2/MdePkg/Library/BaseLib/X64/Non-existing.c
edk2/MdePkg/Library/BaseLib/x86LowLevel.c
edk2/MdePkg/Library/BaseUefiDecompressLib/BaseUefiDecompressLib.c

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