Match the comments with the implementation for Baselib::GetFirstNode.

[mirror_edk2.git] / MdePkg / Include / Library / BaseLib.h

diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h
index 6998171bd552259afdea8faeed15a4f61be88fbd..23e3376f9d852a57d7563f1ec2c03ecb530e7c4b 100644 (file)
--- a/MdePkg/Include/Library/BaseLib.h
+++ b/MdePkg/Include/Library/BaseLib.h
@@ -2,7 +2,7 @@
   Provides string functions, linked list functions, math functions, synchronization\r
   functions, and CPU architecture-specific functions.\r
 \r
-Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>\r
+Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR>\r
 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>\r
 This program and the accompanying materials\r
 are licensed and made available under the terms and conditions of the BSD License\r
@@ -146,6 +146,39 @@ typedef struct {
 \r
 #endif  // defined (MDE_CPU_ARM)\r
 \r
+#if defined (MDE_CPU_AARCH64)\r
+typedef struct {\r
+  // GP regs\r
+  UINT64    X19;\r
+  UINT64    X20;\r
+  UINT64    X21;\r
+  UINT64    X22;\r
+  UINT64    X23;\r
+  UINT64    X24;\r
+  UINT64    X25;\r
+  UINT64    X26;\r
+  UINT64    X27;\r
+  UINT64    X28;\r
+  UINT64    FP;\r
+  UINT64    LR;\r
+  UINT64    IP0;\r
+\r
+  // FP regs\r
+  UINT64    D8;\r
+  UINT64    D9;\r
+  UINT64    D10;\r
+  UINT64    D11;\r
+  UINT64    D12;\r
+  UINT64    D13;\r
+  UINT64    D14;\r
+  UINT64    D15;\r
+} BASE_LIBRARY_JUMP_BUFFER;\r
+\r
+#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8\r
+\r
+#endif  // defined (MDE_CPU_AARCH64)\r
+\r
+\r
 //\r
 // String Services\r
 //\r
@@ -1291,7 +1324,7 @@ InitializeListHead (
   If Entry is NULL, then ASSERT().\r
   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
   InitializeListHead(), then ASSERT().\r
-  If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number\r
+  If PcdMaximumLinkedListLength 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
@@ -1321,7 +1354,7 @@ InsertHeadList (
   If Entry is NULL, then ASSERT().\r
   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or \r
   InitializeListHead(), then ASSERT().\r
-  If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number\r
+  If PcdMaximumLinkedListLength 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
@@ -1350,14 +1383,14 @@ InsertTailList (
   If List is NULL, then ASSERT().\r
   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or \r
   InitializeListHead(), then ASSERT().\r
-  If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
+  If PcdMaximumLinkedListLength is not zero, and the number of nodes\r
   in List, including the List node, is greater than or equal to\r
   PcdMaximumLinkedListLength, then ASSERT().\r
 \r
   @param  List  A pointer to the head node of a doubly linked list.\r
 \r
   @return The first node of a doubly linked list.\r
-  @retval NULL  The list is empty.\r
+  @retval List  The list is empty.\r
 \r
 **/\r
 LIST_ENTRY *\r
@@ -1378,8 +1411,8 @@ GetFirstNode (
   If Node is NULL, then ASSERT().\r
   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or \r
   InitializeListHead(), then ASSERT().\r
-  If PcdMaximumLinkedListLenth is not zero, and List contains more than\r
-  PcdMaximumLinkedListLenth nodes, then ASSERT().\r
+  If PcdMaximumLinkedListLength is not zero, and List contains more than\r
+  PcdMaximumLinkedListLength nodes, then ASSERT().\r
   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().\r
 \r
   @param  List  A pointer to the head node of a doubly linked list.\r
@@ -1407,8 +1440,8 @@ GetNextNode (
   If Node is NULL, then ASSERT().\r
   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or \r
   InitializeListHead(), then ASSERT().\r
-  If PcdMaximumLinkedListLenth is not zero, and List contains more than\r
-  PcdMaximumLinkedListLenth nodes, then ASSERT().\r
+  If PcdMaximumLinkedListLength is not zero, and List contains more than\r
+  PcdMaximumLinkedListLength nodes, then ASSERT().\r
   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().\r
  \r
   @param  List  A pointer to the head node of a doubly linked list.\r
@@ -1434,7 +1467,7 @@ GetPreviousNode (
   If ListHead is NULL, then ASSERT().\r
   If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or \r
   InitializeListHead(), then ASSERT().\r
-  If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
+  If PcdMaximumLinkedListLength is not zero, and the number of nodes\r
   in List, including the List node, is greater than or equal to\r
   PcdMaximumLinkedListLength, then ASSERT().\r
 \r
@@ -1464,7 +1497,7 @@ IsListEmpty (
   If Node is NULL, then ASSERT().\r
   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(), \r
   then ASSERT().\r
-  If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
+  If PcdMaximumLinkedListLength is not zero, and the number of nodes\r
   in List, including the List node, is greater than or equal to\r
   PcdMaximumLinkedListLength, then ASSERT().\r
   If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal \r
@@ -1496,7 +1529,7 @@ IsNull (
   If Node is NULL, then ASSERT().\r
   If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
   InitializeListHead(), then ASSERT().\r
-  If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
+  If PcdMaximumLinkedListLength is not zero, and the number of nodes\r
   in List, including the List node, is greater than or equal to\r
   PcdMaximumLinkedListLength, then ASSERT().\r
   If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().\r
@@ -2343,6 +2376,7 @@ BitFieldRead8 (
   If StartBit is greater than 7, then ASSERT().\r
   If EndBit is greater than 7, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2376,6 +2410,7 @@ BitFieldWrite8 (
   If StartBit is greater than 7, then ASSERT().\r
   If EndBit is greater than 7, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2409,6 +2444,7 @@ BitFieldOr8 (
   If StartBit is greater than 7, then ASSERT().\r
   If EndBit is greater than 7, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2443,6 +2479,8 @@ BitFieldAnd8 (
   If StartBit is greater than 7, then ASSERT().\r
   If EndBit is greater than 7, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2505,6 +2543,7 @@ BitFieldRead16 (
   If StartBit is greater than 15, then ASSERT().\r
   If EndBit is greater than 15, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2538,6 +2577,7 @@ BitFieldWrite16 (
   If StartBit is greater than 15, then ASSERT().\r
   If EndBit is greater than 15, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2571,6 +2611,7 @@ BitFieldOr16 (
   If StartBit is greater than 15, then ASSERT().\r
   If EndBit is greater than 15, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2605,6 +2646,8 @@ BitFieldAnd16 (
   If StartBit is greater than 15, then ASSERT().\r
   If EndBit is greater than 15, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2667,6 +2710,7 @@ BitFieldRead32 (
   If StartBit is greater than 31, then ASSERT().\r
   If EndBit is greater than 31, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2700,6 +2744,7 @@ BitFieldWrite32 (
   If StartBit is greater than 31, then ASSERT().\r
   If EndBit is greater than 31, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2733,6 +2778,7 @@ BitFieldOr32 (
   If StartBit is greater than 31, then ASSERT().\r
   If EndBit is greater than 31, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2767,6 +2813,8 @@ BitFieldAnd32 (
   If StartBit is greater than 31, then ASSERT().\r
   If EndBit is greater than 31, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2829,6 +2877,7 @@ BitFieldRead64 (
   If StartBit is greater than 63, then ASSERT().\r
   If EndBit is greater than 63, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2862,6 +2911,7 @@ BitFieldWrite64 (
   If StartBit is greater than 63, then ASSERT().\r
   If EndBit is greater than 63, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2895,6 +2945,7 @@ BitFieldOr64 (
   If StartBit is greater than 63, then ASSERT().\r
   If EndBit is greater than 63, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -2929,6 +2980,8 @@ BitFieldAnd64 (
   If StartBit is greater than 63, then ASSERT().\r
   If EndBit is greater than 63, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\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
@@ -4932,6 +4985,28 @@ typedef union {
   UINTN     UintN;\r
 } IA32_CR4;\r
 \r
+///\r
+/// Byte packed structure for a segment descriptor in a GDT/LDT.\r
+///\r
+typedef union {\r
+  struct {\r
+    UINT32  LimitLow:16;\r
+    UINT32  BaseLow:16;\r
+    UINT32  BaseMid:8;\r
+    UINT32  Type:4;\r
+    UINT32  S:1;\r
+    UINT32  DPL:2;\r
+    UINT32  P:1;\r
+    UINT32  LimitHigh:4;\r
+    UINT32  AVL:1;\r
+    UINT32  L:1;\r
+    UINT32  DB:1;\r
+    UINT32  G:1;\r
+    UINT32  BaseHigh:8;\r
+  } Bits;\r
+  UINT64  Uint64;\r
+} IA32_SEGMENT_DESCRIPTOR;\r
+\r
 ///\r
 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.\r
 ///\r
@@ -5358,6 +5433,7 @@ AsmMsrBitFieldRead32 (
   If StartBit is greater than 31, then ASSERT().\r
   If EndBit is greater than 31, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
 \r
   @param  Index     The 32-bit MSR index to write.\r
   @param  StartBit  The ordinal of the least significant bit in the bit field.\r
@@ -5394,6 +5470,7 @@ AsmMsrBitFieldWrite32 (
   If StartBit is greater than 31, then ASSERT().\r
   If EndBit is greater than 31, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
 \r
   @param  Index     The 32-bit MSR index to write.\r
   @param  StartBit  The ordinal of the least significant bit in the bit field.\r
@@ -5430,6 +5507,7 @@ AsmMsrBitFieldOr32 (
   If StartBit is greater than 31, then ASSERT().\r
   If EndBit is greater than 31, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
 \r
   @param  Index     The 32-bit MSR index to write.\r
   @param  StartBit  The ordinal of the least significant bit in the bit field.\r
@@ -5468,6 +5546,8 @@ AsmMsrBitFieldAnd32 (
   If StartBit is greater than 31, then ASSERT().\r
   If EndBit is greater than 31, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
 \r
   @param  Index     The 32-bit MSR index to write.\r
   @param  StartBit  The ordinal of the least significant bit in the bit field.\r
@@ -5662,6 +5742,7 @@ AsmMsrBitFieldRead64 (
   If StartBit is greater than 63, then ASSERT().\r
   If EndBit is greater than 63, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
 \r
   @param  Index     The 32-bit MSR index to write.\r
   @param  StartBit  The ordinal of the least significant bit in the bit field.\r
@@ -5698,6 +5779,7 @@ AsmMsrBitFieldWrite64 (
   If StartBit is greater than 63, then ASSERT().\r
   If EndBit is greater than 63, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
 \r
   @param  Index     The 32-bit MSR index to write.\r
   @param  StartBit  The ordinal of the least significant bit in the bit field.\r
@@ -5734,6 +5816,7 @@ AsmMsrBitFieldOr64 (
   If StartBit is greater than 63, then ASSERT().\r
   If EndBit is greater than 63, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
 \r
   @param  Index     The 32-bit MSR index to write.\r
   @param  StartBit  The ordinal of the least significant bit in the bit field.\r
@@ -5771,6 +5854,8 @@ AsmMsrBitFieldAnd64 (
   If StartBit is greater than 63, then ASSERT().\r
   If EndBit is greater than 63, then ASSERT().\r
   If EndBit is less than StartBit, then ASSERT().\r
+  If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
+  If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().\r
 \r
   @param  Index     The 32-bit MSR index to write.\r
   @param  StartBit  The ordinal of the least significant bit in the bit field.\r
@@ -7100,7 +7185,7 @@ AsmGetThunk16Properties (
 VOID\r
 EFIAPI\r
 AsmPrepareThunk16 (\r
-  OUT     THUNK_CONTEXT             *ThunkContext\r
+  IN OUT  THUNK_CONTEXT             *ThunkContext\r
   );\r
 \r
 \r