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 ea61da14ca4974ee18d910fe379cb54c6f9f5450..6a43c164547a73c40c493d716cfe059fddbe3b6b 100644 (file)
--- a/MdePkg/Include/Library/BaseLib.h
+++ b/MdePkg/Include/Library/BaseLib.h
@@ -2474,6 +2474,14 @@ InterlockedDecrement (
 /**\r
   Performs an atomic compare exchange operation on a 32-bit unsigned integer.\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
+  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
   @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
 /**\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
   @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
   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
 \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
   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
   If Value is 0, then ASSERT().\r
 \r
   @param  JumpBuffer  A pointer to CPU context buffer.\r

diff --git a/MdePkg/Include/Library/UefiDecompressLib.h b/MdePkg/Include/Library/UefiDecompressLib.h
index d1cf2d7d08a0d4c67997c9b0978e85ca25406f31..f744abc7eb864fd1cd47ed2b57b754026e032942 100644 (file)
--- a/MdePkg/Include/Library/UefiDecompressLib.h
+++ b/MdePkg/Include/Library/UefiDecompressLib.h
@@ -17,6 +17,39 @@
 #ifndef __UEFI_DECPOMPRESS_LIB_H__\r
 #define __UEFI_DECPOMPRESS_LIB_H__\r
 \r
 #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
 RETURN_STATUS\r
 EFIAPI\r
 UefiDecompressGetInfo (\r


@@ -26,6 +59,32 @@ UefiDecompressGetInfo (
   OUT UINT32      *ScratchSize\r
   );\r
 \r
   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
 RETURN_STATUS\r
 EFIAPI\r
 UefiDecompress (\r

diff --git a/MdePkg/Library/BaseLib/BaseLibInternals.h b/MdePkg/Library/BaseLib/BaseLibInternals.h
index 0c32e1bd2c46b74cbf2620bf298f4c30e7a8ab26..3a4ff07f069977d22233b9506a482b6586c2c095 100644 (file)
--- a/MdePkg/Library/BaseLib/BaseLibInternals.h
+++ b/MdePkg/Library/BaseLib/BaseLibInternals.h
@@ -21,6 +21,19 @@
 // Math functions\r
 //\r
 \r
 // 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
 UINT64\r
 EFIAPI\r
 InternalMathLShiftU64 (\r


@@ -28,6 +41,19 @@ InternalMathLShiftU64 (
   IN      UINTN                     Count\r
   );\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathRShiftU64 (\r


@@ -35,6 +61,19 @@ InternalMathRShiftU64 (
   IN      UINTN                     Count\r
   );\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathARShiftU64 (\r


@@ -42,6 +81,20 @@ InternalMathARShiftU64 (
   IN      UINTN                     Count\r
   );\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathLRotU64 (\r


@@ -49,6 +102,20 @@ InternalMathLRotU64 (
   IN      UINTN                     Count\r
   );\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathRRotU64 (\r


@@ -56,12 +123,38 @@ InternalMathRRotU64 (
   IN      UINTN                     Count\r
   );\r
 \r
   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
 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
 UINT64\r
 EFIAPI\r
 InternalMathMultU64x32 (\r


@@ -69,6 +162,20 @@ InternalMathMultU64x32 (
   IN      UINT32                    Multiplier\r
   );\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathMultU64x64 (\r


@@ -76,6 +183,20 @@ InternalMathMultU64x64 (
   IN      UINT64                    Multiplier\r
   );\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathDivU64x32 (\r


@@ -83,6 +204,20 @@ InternalMathDivU64x32 (
   IN      UINT32                    Divisor\r
   );\r
 \r
   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
 UINT32\r
 EFIAPI\r
 InternalMathModU64x32 (\r


@@ -90,6 +225,23 @@ InternalMathModU64x32 (
   IN      UINT32                    Divisor\r
   );\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathDivRemU64x32 (\r


@@ -98,6 +250,23 @@ InternalMathDivRemU64x32 (
   OUT     UINT32                    *Remainder\r
   );\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathDivRemU64x64 (\r


@@ -106,16 +275,48 @@ InternalMathDivRemU64x64 (
   OUT     UINT64                    *Remainder\r
   );\r
 \r
   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
 INT64\r

-EFIAPI\r

 InternalMathDivRemS64x64 (\r
   IN      INT64                     Dividend,\r
   IN      INT64                     Divisor,\r
 InternalMathDivRemS64x64 (\r
   IN      INT64                     Dividend,\r
   IN      INT64                     Divisor,\r

-  OUT     INT64                     *Remainder\r
+  OUT     INT64                     *Remainder  OPTIONAL\r

   );\r
 \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
 VOID\r

-EFIAPI\r

 InternalSwitchStack (\r
   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,\r
   IN      VOID                      *Context1,\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
 // 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
 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
 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
 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
 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
 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
 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
 VOID\r
 EFIAPI\r
 InternalX86EnablePaging32 (\r


@@ -172,6 +462,36 @@ InternalX86EnablePaging32 (
   IN      VOID                      *NewStack\r
   );\r
 \r
   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
 VOID\r
 EFIAPI\r
 InternalX86DisablePaging32 (\r


@@ -181,6 +501,33 @@ InternalX86DisablePaging32 (
   IN      VOID                      *NewStack\r
   );\r
 \r
   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
 VOID\r
 EFIAPI\r
 InternalX86EnablePaging64 (\r


@@ -191,6 +538,32 @@ InternalX86EnablePaging64 (
   IN      UINT64                    NewStack\r
   );\r
 \r
   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
 VOID\r
 EFIAPI\r
 InternalX86DisablePaging64 (\r

diff --git a/MdePkg/Library/BaseLib/BitField.c b/MdePkg/Library/BaseLib/BitField.c
index 9c1aff1c6f09ce6122cd1346d8173d8ac1bb4920..0b517aa974f7f505cd7a59c472df3e03a7b32305 100644 (file)
--- a/MdePkg/Library/BaseLib/BitField.c
+++ b/MdePkg/Library/BaseLib/BitField.c
@@ -14,8 +14,19 @@
 \r
 **/\r
 \r
 \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
 unsigned int\r

-EFIAPI\r

 BitFieldReadUint (\r
   IN      unsigned int              Operand,\r
   IN      UINTN                     StartBit,\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
   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
 unsigned int\r

-EFIAPI\r

 BitFieldOrUint (\r
   IN      unsigned int              Operand,\r
   IN      UINTN                     StartBit,\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
   // ~((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
 \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
 unsigned int\r

-EFIAPI\r

 BitFieldAndUint (\r
   IN      unsigned int              Operand,\r
   IN      UINTN                     StartBit,\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
   // ~((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
 }\r
 \r
 /**\r

diff --git a/MdePkg/Library/BaseLib/DivS64x64Remainder.c b/MdePkg/Library/BaseLib/DivS64x64Remainder.c
index aa28fc8ccbfa83cdefd31458f85417dab6946ce5..efa091088eb6f912cb5b71a08180bf47a09e9488 100644 (file)
--- a/MdePkg/Library/BaseLib/DivS64x64Remainder.c
+++ b/MdePkg/Library/BaseLib/DivS64x64Remainder.c
@@ -38,7 +38,7 @@ EFIAPI
 DivS64x64Remainder (\r
   IN      INT64                     Dividend,\r
   IN      INT64                     Divisor,\r
 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
   )\r
 {\r
   ASSERT (Divisor != 0);\r

diff --git a/MdePkg/Library/BaseLib/DivU64x32Remainder.c b/MdePkg/Library/BaseLib/DivU64x32Remainder.c
index aa34b31e462012b84e742c02313a9411658925fa..e7a3094c6ed0af25d570fb7ec3d1a13cd8d1153d 100644 (file)
--- a/MdePkg/Library/BaseLib/DivU64x32Remainder.c
+++ b/MdePkg/Library/BaseLib/DivU64x32Remainder.c
@@ -38,7 +38,7 @@ EFIAPI
 DivU64x32Remainder (\r
   IN      UINT64                    Dividend,\r
   IN      UINT32                    Divisor,\r
 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
   )\r
 {\r
   ASSERT (Divisor != 0);\r

diff --git a/MdePkg/Library/BaseLib/DivU64x64Remainder.c b/MdePkg/Library/BaseLib/DivU64x64Remainder.c
index 0caa5295aa5d2a06629de350a9ba773e64e2031e..c39537e4fb2e1d8d043deabf40533e76c69c5d5a 100644 (file)
--- a/MdePkg/Library/BaseLib/DivU64x64Remainder.c
+++ b/MdePkg/Library/BaseLib/DivU64x64Remainder.c
@@ -38,7 +38,7 @@ EFIAPI
 DivU64x64Remainder (\r
   IN      UINT64                    Dividend,\r
   IN      UINT64                    Divisor,\r
 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
   )\r
 {\r
   ASSERT (Divisor != 0);\r

diff --git a/MdePkg/Library/BaseLib/Ebc/SetJumpLongJump.c b/MdePkg/Library/BaseLib/Ebc/SetJumpLongJump.c
index ab7716cb94921add4e20ac8004610d55e56f1848..b485d3e495d6d11c2b4a3fed95fed277786d969d 100644 (file)
--- a/MdePkg/Library/BaseLib/Ebc/SetJumpLongJump.c
+++ b/MdePkg/Library/BaseLib/Ebc/SetJumpLongJump.c
@@ -14,12 +14,35 @@
 \r
 **/\r
 \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
 VOID\r

-EFIAPI\r

 InternalAssertJumpBuffer (\r
   IN      BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer\r
   );\r
 \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
 UINTN\r
 EFIAPI\r
 SetJump (\r


@@ -30,6 +53,17 @@ SetJump (
   return 0;\r
 }\r
 \r
   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
 VOID\r
 EFIAPI\r
 InternalLongJump (\r


@@ -37,5 +71,8 @@ InternalLongJump (
   IN      UINTN                     Value\r
   )\r
 {\r
   IN      UINTN                     Value\r
   )\r
 {\r

+  //\r
+  // This function cannot work on EBC\r
+  //\r

   ASSERT (FALSE);\r
 }\r
   ASSERT (FALSE);\r
 }\r

diff --git a/MdePkg/Library/BaseLib/Ebc/SwitchStack.c b/MdePkg/Library/BaseLib/Ebc/SwitchStack.c
index 8fadd4f384a53dc1666421f6fbe9cd2647d6cb24..0a5464b2f9274d094357ddd47f44eed6088c5c03 100644 (file)
--- a/MdePkg/Library/BaseLib/Ebc/SwitchStack.c
+++ b/MdePkg/Library/BaseLib/Ebc/SwitchStack.c
@@ -35,7 +35,6 @@
 \r
 **/\r
 VOID\r
 \r
 **/\r
 VOID\r

-EFIAPI\r

 InternalSwitchStack (\r
   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,\r
   IN      VOID                      *Context1,  OPTIONAL\r
 InternalSwitchStack (\r
   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,\r
   IN      VOID                      *Context1,  OPTIONAL\r

diff --git a/MdePkg/Library/BaseLib/Ebc/Synchronization.c b/MdePkg/Library/BaseLib/Ebc/Synchronization.c
index df591b287ab0cd032c17b3b9da687e99f48f0506..5d5bc2ff11770cbc6bdba1b08ae713c1a2178bec 100644 (file)
--- a/MdePkg/Library/BaseLib/Ebc/Synchronization.c
+++ b/MdePkg/Library/BaseLib/Ebc/Synchronization.c
@@ -26,6 +26,22 @@ InternalSyncCompareExchange32 (
            ((*Value = ExchangeValue), CompareValue);\r
 }\r
 \r
            ((*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
 UINT64\r
 EFIAPI\r
 InternalSyncCompareExchange64 (\r


@@ -38,6 +54,19 @@ InternalSyncCompareExchange64 (
            ((*Value = ExchangeValue), CompareValue);\r
 }\r
 \r
            ((*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
 UINT32\r
 EFIAPI\r
 InternalSyncIncrement (\r


@@ -47,6 +76,19 @@ InternalSyncIncrement (
   return ++*Value;\r
 }\r
 \r
   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
 UINT32\r
 EFIAPI\r
 InternalSyncDecrement (\r

diff --git a/MdePkg/Library/BaseLib/Ia32/DivS64x64Remainder.c b/MdePkg/Library/BaseLib/Ia32/DivS64x64Remainder.c
index 219f48f32126ffa5aef6e16d929274deeee5c9ab..a5183429c143ea6edff5d5372d5242078bf37e01 100644 (file)
--- a/MdePkg/Library/BaseLib/Ia32/DivS64x64Remainder.c
+++ b/MdePkg/Library/BaseLib/Ia32/DivS64x64Remainder.c
@@ -16,12 +16,28 @@
 \r
 #include "../BaseLibInternals.h"\r
 \r
 \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
 INT64\r

-EFIAPI\r

 InternalMathDivRemS64x64 (\r
   IN      INT64                     Dividend,\r
   IN      INT64                     Divisor,\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
   )\r
 {\r
   INT64                             Quot;\r

diff --git a/MdePkg/Library/BaseLib/Ia32/InternalSwitchStack.c b/MdePkg/Library/BaseLib/Ia32/InternalSwitchStack.c
index ab8116b4b5a882236fc2eff75b0a663eff0e33e3..484313ea674b3f1a3e7e80c3a647c9ea2ac1d424 100644 (file)
--- a/MdePkg/Library/BaseLib/Ia32/InternalSwitchStack.c
+++ b/MdePkg/Library/BaseLib/Ia32/InternalSwitchStack.c
@@ -32,7 +32,6 @@
 \r
 **/\r
 VOID\r
 \r
 **/\r
 VOID\r

-EFIAPI\r

 InternalSwitchStack (\r
   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,\r
   IN      VOID                      *Context1,\r
 InternalSwitchStack (\r
   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,\r
   IN      VOID                      *Context1,\r

diff --git a/MdePkg/Library/BaseLib/Ia32/Non-existing.c b/MdePkg/Library/BaseLib/Ia32/Non-existing.c
index b4e50e9d7b83ea8dd30c4eaf5527a2f0a451098c..89ba2f2ced5651ace88855b29d5bfb8290a3c3ee 100644 (file)
--- a/MdePkg/Library/BaseLib/Ia32/Non-existing.c
+++ b/MdePkg/Library/BaseLib/Ia32/Non-existing.c
@@ -16,6 +16,33 @@
 \r
 #include "../BaseLibInternals.h"\r
 \r
 \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
 VOID\r
 EFIAPI\r
 InternalX86DisablePaging64 (\r


@@ -26,5 +53,8 @@ InternalX86DisablePaging64 (
   IN      UINT32                    NewStack\r
   )\r
 {\r
   IN      UINT32                    NewStack\r
   )\r
 {\r

+  //\r
+  // This function cannot work on IA32 platform\r
+  //\r

   ASSERT (FALSE);\r
 }\r
   ASSERT (FALSE);\r
 }\r

diff --git a/MdePkg/Library/BaseLib/Ipf/Synchronization.c b/MdePkg/Library/BaseLib/Ipf/Synchronization.c
index f09dbd5c00bd69e6fad05cd0def079a9728da66a..44593e177879209a8c7cceec19d6b1cfd81079ab 100644 (file)
--- a/MdePkg/Library/BaseLib/Ipf/Synchronization.c
+++ b/MdePkg/Library/BaseLib/Ipf/Synchronization.c
@@ -14,6 +14,23 @@
 \r
 **/\r
 \r
 \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
 UINT32\r
 EFIAPI\r
 InternalSyncCompareExchange32 (\r


@@ -22,6 +39,19 @@ InternalSyncCompareExchange32 (
   IN      UINT32                    ExchangeValue\r
   );\r
 \r
   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
 UINT32\r
 EFIAPI\r
 InternalSyncIncrement (\r


@@ -40,6 +70,19 @@ InternalSyncIncrement (
   return OriginalValue + 1;\r
 }\r
 \r
   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
 UINT32\r
 EFIAPI\r
 InternalSyncDecrement (\r

diff --git a/MdePkg/Library/BaseLib/LinkedList.c b/MdePkg/Library/BaseLib/LinkedList.c
index 15ceb584db1634db79e5ab2357e9479fb6ef78ea..6c083ef95cf18c7c9e3b281e0beab2d1b73f1e8f 100644 (file)
--- a/MdePkg/Library/BaseLib/LinkedList.c
+++ b/MdePkg/Library/BaseLib/LinkedList.c
@@ -14,6 +14,27 @@
 \r
 **/\r
 \r
 \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
 BOOLEAN\r
 EFIAPI\r
 IsNodeInList (\r

diff --git a/MdePkg/Library/BaseLib/LongJump.c b/MdePkg/Library/BaseLib/LongJump.c
index 85f091e090988e8b5a3fa17b9e1cfe22809bc877..a18c974e9110faaa51f1b56080befd455eec8e12 100644 (file)
--- a/MdePkg/Library/BaseLib/LongJump.c
+++ b/MdePkg/Library/BaseLib/LongJump.c
@@ -14,12 +14,33 @@
 \r
 **/\r
 \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
 VOID\r

-EFIAPI\r

 InternalAssertJumpBuffer (\r
   IN      BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer\r
   );\r
 \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
 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
   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
   If Value is 0, then ASSERT().\r
 \r
   @param  JumpBuffer    A pointer to CPU context buffer.\r

diff --git a/MdePkg/Library/BaseLib/Math64.c b/MdePkg/Library/BaseLib/Math64.c
index 57dcca387faaecbe0b2c793e133cb71b3545a4f2..a8756967befaf73f6d2a4978ff4e0943393e05e7 100644 (file)
--- a/MdePkg/Library/BaseLib/Math64.c
+++ b/MdePkg/Library/BaseLib/Math64.c
@@ -15,8 +15,20 @@
 \r
 **/\r
 \r
 \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
 UINT64\r

-EFIAPI\r

 InternalMathLShiftU64 (\r
   IN      UINT64                    Operand,\r
   IN      UINTN                     Count\r
 InternalMathLShiftU64 (\r
   IN      UINT64                    Operand,\r
   IN      UINTN                     Count\r


@@ -25,6 +37,19 @@ InternalMathLShiftU64 (
   return Operand << Count;\r
 }\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathRShiftU64 (\r


@@ -35,6 +60,21 @@ InternalMathRShiftU64 (
   return Operand >> Count;\r
 }\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathARShiftU64 (\r


@@ -59,6 +99,21 @@ InternalMathARShiftU64 (
          ((INTN)Operand < 0 ? ~((UINTN)-1 >> Count) : 0);\r
 }\r
 \r
          ((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
 UINT64\r
 EFIAPI\r
 InternalMathLRotU64 (\r


@@ -69,6 +124,20 @@ InternalMathLRotU64 (
   return (Operand << Count) | (Operand >> (64 - Count));\r
 }\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathRRotU64 (\r


@@ -79,6 +148,18 @@ InternalMathRRotU64 (
   return (Operand >> Count) | (Operand << (64 - Count));\r
 }\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathSwapBytes64 (\r


@@ -91,6 +172,20 @@ InternalMathSwapBytes64 (
            );\r
 }\r
 \r
            );\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
 UINT64\r
 EFIAPI\r
 InternalMathMultU64x32 (\r


@@ -101,6 +196,21 @@ InternalMathMultU64x32 (
   return Multiplicand * Multiplier;\r
 }\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathMultU64x64 (\r


@@ -111,6 +221,20 @@ InternalMathMultU64x64 (
   return Multiplicand * Multiplier;\r
 }\r
 \r
   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
 UINT64\r
 EFIAPI\r
 InternalMathDivU64x32 (\r


@@ -121,8 +245,21 @@ InternalMathDivU64x32 (
   return Dividend / Divisor;\r
 }\r
 \r
   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
 UINT32\r

-EFIAPI\r

 InternalMathModU64x32 (\r
   IN      UINT64                    Dividend,\r
   IN      UINT32                    Divisor\r
 InternalMathModU64x32 (\r
   IN      UINT64                    Dividend,\r
   IN      UINT32                    Divisor\r


@@ -131,12 +268,28 @@ InternalMathModU64x32 (
   return (UINT32)(Dividend % Divisor);\r
 }\r
 \r
   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
 UINT64\r

-EFIAPI\r

 InternalMathDivRemU64x32 (\r
   IN      UINT64                    Dividend,\r
   IN      UINT32                    Divisor,\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
   )\r
 {\r
   if (Remainder != NULL) {\r


@@ -145,12 +298,28 @@ InternalMathDivRemU64x32 (
   return Dividend / Divisor;\r
 }\r
 \r
   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
 UINT64\r

-EFIAPI\r

 InternalMathDivRemU64x64 (\r
   IN      UINT64                    Dividend,\r
   IN      UINT64                    Divisor,\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
   )\r
 {\r
   if (Remainder != NULL) {\r


@@ -159,12 +328,28 @@ InternalMathDivRemU64x64 (
   return Dividend / Divisor;\r
 }\r
 \r
   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
 INT64\r

-EFIAPI\r

 InternalMathDivRemS64x64 (\r
   IN      INT64                     Dividend,\r
   IN      INT64                     Divisor,\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
   )\r
 {\r
   if (Remainder != NULL) {\r

diff --git a/MdePkg/Library/BaseLib/MultU64x32.c b/MdePkg/Library/BaseLib/MultU64x32.c
index 4c30472bfa986c887efbb00c1973d9936f271630..c3a25c6f3473314265d033be0e564e9f5caaa3f3 100644 (file)
--- 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-\r
   bit unsigned result is returned.\r
 \r
   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
   @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
   UINT64                            Result;\r
 \r
   Result = InternalMathMultU64x32 (Multiplicand, Multiplier);\r

-  // TODO: ASSERT (Result not overflow);\r
+\r

   return Result;\r
 }\r
   return Result;\r
 }\r

diff --git a/MdePkg/Library/BaseLib/MultU64x64.c b/MdePkg/Library/BaseLib/MultU64x64.c
index 6324c3e335091d02b13734a5a17d74ffe4701dc2..997abbc27e8f2259a2eaa966185f68d693b83748 100644 (file)
--- 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-\r
   bit unsigned result is returned.\r
 \r
   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
   @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
   UINT64                            Result;\r
 \r
   Result = InternalMathMultU64x64 (Multiplicand, Multiplier);\r

-  // TODO: ASSERT (Result not overflow);\r
+\r

   return Result;\r
 }\r
   return Result;\r
 }\r

diff --git a/MdePkg/Library/BaseLib/SetJump.c b/MdePkg/Library/BaseLib/SetJump.c
index ea70641ec2500f68cb971ffa1bd91ac53fd22392..8bac97ab479bce1becbd07004226d37dea5ad5aa 100644 (file)
--- 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,\r
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
   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
 **/\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
 VOID\r

-EFIAPI\r

 InternalAssertJumpBuffer (\r
   IN      BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer\r
   )\r
 InternalAssertJumpBuffer (\r
   IN      BASE_LIBRARY_JUMP_BUFFER  *JumpBuffer\r
   )\r

diff --git a/MdePkg/Library/BaseLib/String.c b/MdePkg/Library/BaseLib/String.c
index a59a9d08cbca22a3fb2d954d6a07dda6606fa247..2ac32254fcc8a070c076dcbbb7f7c2baabb5584e 100644 (file)
--- a/MdePkg/Library/BaseLib/String.c
+++ b/MdePkg/Library/BaseLib/String.c
@@ -617,9 +617,21 @@ AsciiStrCmp (
   return *FirstString - *SecondString;\r
 }\r
 \r
   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
 STATIC\r
 CHAR8\r

-EFIAPI\r

 AsciiToUpper (\r
   IN      CHAR8                     Chr\r
   )\r
 AsciiToUpper (\r
   IN      CHAR8                     Chr\r
   )\r

diff --git a/MdePkg/Library/BaseLib/SwitchStack.c b/MdePkg/Library/BaseLib/SwitchStack.c
index 353efa8f6e56a31bf426495bbe0dceb36d1129c1..98d832dfd6746dd71d4a84e2e79479e19296ee85 100644 (file)
--- a/MdePkg/Library/BaseLib/SwitchStack.c
+++ b/MdePkg/Library/BaseLib/SwitchStack.c
@@ -26,6 +26,7 @@
 \r
   If EntryPoint is NULL, then ASSERT().\r
   If NewStack is NULL, then ASSERT().\r
 \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
 \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

diff --git a/MdePkg/Library/BaseLib/Synchronization.c b/MdePkg/Library/BaseLib/Synchronization.c
index 0d51956d748f6dda9f46cd0ee43b083352c74e78..cf001ce4d155ebd66d832eef9ec520db6503faaa 100644 (file)
--- a/MdePkg/Library/BaseLib/Synchronization.c
+++ b/MdePkg/Library/BaseLib/Synchronization.c
@@ -17,18 +17,61 @@
 #define SPIN_LOCK_RELEASED          ((SPIN_LOCK)1)\r
 #define SPIN_LOCK_ACQUIRED          ((SPIN_LOCK)2)\r
 \r
 #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
 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
 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
 UINT32\r
 EFIAPI\r
 InternalSyncCompareExchange32 (\r


@@ -37,6 +80,22 @@ InternalSyncCompareExchange32 (
   IN      UINT32                    ExchangeValue\r
   );\r
 \r
   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
 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
 /**\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
   @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
 /**\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
   @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

diff --git a/MdePkg/Library/BaseLib/X64/Non-existing.c b/MdePkg/Library/BaseLib/X64/Non-existing.c
index fc4fd4389854f2c0befda831e03d94f844f62e0e..a1c4677dad0d0977d9e97e90e75733e83bd8b1fe 100644 (file)
--- a/MdePkg/Library/BaseLib/X64/Non-existing.c
+++ b/MdePkg/Library/BaseLib/X64/Non-existing.c
@@ -16,6 +16,39 @@
 \r
 #include "../BaseLibInternals.h"\r
 \r
 \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
 VOID\r
 EFIAPI\r
 InternalX86EnablePaging32 (\r


@@ -25,9 +58,42 @@ InternalX86EnablePaging32 (
   IN      VOID                      *NewStack\r
   )\r
 {\r
   IN      VOID                      *NewStack\r
   )\r
 {\r

+  //\r
+  // This function cannot work on X64 platform\r
+  //\r

   ASSERT (FALSE);\r
 }\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
 VOID\r
 EFIAPI\r
 InternalX86DisablePaging32 (\r


@@ -37,9 +103,39 @@ InternalX86DisablePaging32 (
   IN      VOID                      *NewStack\r
   )\r
 {\r
   IN      VOID                      *NewStack\r
   )\r
 {\r

+  //\r
+  // This function cannot work on X64 platform\r
+  //\r

   ASSERT (FALSE);\r
 }\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
 VOID\r
 EFIAPI\r
 InternalX86EnablePaging64 (\r


@@ -50,5 +146,8 @@ InternalX86EnablePaging64 (
   IN      UINT64                    NewStack\r
   )\r
 {\r
   IN      UINT64                    NewStack\r
   )\r
 {\r

+  //\r
+  // This function cannot work on X64 platform\r
+  //\r

   ASSERT (FALSE);\r
 }\r
   ASSERT (FALSE);\r
 }\r

diff --git a/MdePkg/Library/BaseLib/x86LowLevel.c b/MdePkg/Library/BaseLib/x86LowLevel.c
index 391fbbf93f7a0706cd825f0014db002c6fbca369..28193044bc46d7eba68db1fe039b7461907d3556 100644 (file)
--- a/MdePkg/Library/BaseLib/x86LowLevel.c
+++ b/MdePkg/Library/BaseLib/x86LowLevel.c
@@ -988,4 +988,5 @@ MemoryFence (
   VOID\r
   )\r
 {\r
   VOID\r
   )\r
 {\r

+  return;\r

 }\r
 }\r

diff --git a/MdePkg/Library/BaseUefiDecompressLib/BaseUefiDecompressLib.c b/MdePkg/Library/BaseUefiDecompressLib/BaseUefiDecompressLib.c
index ee832f0b2f577ddcbda98ac56f786b706fbf4a99..c0c79c7c4a87097e2caa99f6f95df2ef194671d5 100644 (file)
--- a/MdePkg/Library/BaseUefiDecompressLib/BaseUefiDecompressLib.c
+++ b/MdePkg/Library/BaseUefiDecompressLib/BaseUefiDecompressLib.c
@@ -69,9 +69,11 @@ typedef struct {
 } SCRATCH_DATA;\r
 \r
 /**\r
 } 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
   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
   @param  NumOfBits The number of bits to shift and read.\r
 \r
 **/\r


@@ -81,8 +83,14 @@ FillBuf (
   IN  UINT16        NumOfBits\r
   )\r
 {\r
   IN  UINT16        NumOfBits\r
   )\r
 {\r

+  //\r
+  // Left shift NumOfBits of bits in advance\r
+  //\r

   Sd->mBitBuf = (UINT32) (Sd->mBitBuf << NumOfBits);\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
   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
       // 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
       Sd->mSubBitBuf  = Sd->mSrcBase[Sd->mInBuf++];\r
       Sd->mBitCount   = 8;\r
 \r


@@ -106,16 +113,25 @@ FillBuf (
     }\r
   }\r
 \r
     }\r
   }\r
 \r

+  //\r
+  // Caculate additional bit count read to update mBitCount\r
+  //\r

   Sd->mBitCount = (UINT16) (Sd->mBitCount - NumOfBits);\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
   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
   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
   @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
   UINT32  OutBits;\r
 \r

+  //\r
+  // Pop NumOfBits of Bits from Left\r
+  //  \r

   OutBits = (UINT32) (Sd->mBitBuf >> (BITBUFSIZ - NumOfBits));\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
   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
 /**\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  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  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
 \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
 /**\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
   @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
 /**\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
   @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
   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
   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
     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
     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
     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
         CharC += 1;\r
       }\r
     }\r

-\r
+    \r

     FillBuf (Sd, (UINT16) ((CharC < 7) ? 3 : CharC - 3));\r
 \r
     Sd->mPTLen[Index++] = (UINT8) CharC;\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
     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
   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
   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
 \r
   @param  Sd the global scratch data\r
 \r


@@ -394,14 +444,17 @@ ReadCLen (
   SCRATCH_DATA  *Sd\r
   )\r
 {\r
   SCRATCH_DATA  *Sd\r
   )\r
 {\r

-  UINT16  Number;\r
-  UINT16  CharC;\r
+  UINT16           Number;\r
+  UINT16           CharC;\r

   volatile UINT16  Index;\r
   volatile UINT16  Index;\r

-  UINT32  Mask;\r
+  UINT32           Mask;\r

 \r
   Number = (UINT16) GetBits (Sd, CBIT);\r
 \r
   if (Number == 0) {\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
     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
   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
     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
 /**\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
 \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
   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
     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
     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
     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
     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
   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
 /**\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
   @param  Sd The global scratch data\r
 \r
 **/\r


@@ -547,6 +622,9 @@ Decode (
   DataIdx     = 0;\r
 \r
   for (;;) {\r
   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
     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
       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
         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
       // 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
       BytesRemain = CharC;\r
 \r

+      //\r
+      // Locate string position\r
+      //\r

       DataIdx     = Sd->mOutBuf - DecodeP (Sd) - 1;\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
       BytesRemain--;\r
       while ((INT16) (BytesRemain) >= 0) {\r
         Sd->mDstBase[Sd->mOutBuf++] = Sd->mDstBase[DataIdx++];\r


@@ -588,14 +678,35 @@ Decode (
 }\r
 \r
 /**\r
 }\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
   @retval  RETURN_INVALID_PARAMETER The source data is corrupted\r
 \r
 **/\r


@@ -631,12 +742,27 @@ UefiDecompressGetInfo (
 }\r
 \r
 /**\r
 }\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  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
   @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
   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
   Sd->mCompSize = CompSize;\r
   Sd->mOrigSize = OrigSize;\r
 \r