Add limitation clarification for usage of AsmPrepareThunk16(), AsmThunk16(), AsmPrepa...

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

diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h
index 6f25f236bc3ab8a101547b29dc46c2883aee68b4..d704e98f5ffe97d29839ca9f73249dff3df10af9 100644 (file)
--- a/MdePkg/Include/Library/BaseLib.h
+++ b/MdePkg/Include/Library/BaseLib.h
@@ -175,9 +175,11 @@ StrCpy (
   If Length > 0 and Source is NULL, then ASSERT().\r
   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().\r
   If Source and Destination overlap, then ASSERT().\r
   If Length > 0 and Source is NULL, then ASSERT().\r
   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().\r
   If Source and Destination overlap, then ASSERT().\r

+  If PcdMaximumUnicodeStringLength is not zero, and Length is greater than \r
+  PcdMaximumUnicodeStringLength, then ASSERT().\r

   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r

-  PcdMaximumUnicodeStringLength Unicode characters not including the\r
-  Null-terminator, then ASSERT().\r
+  PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,\r
+  then ASSERT().\r

 \r
   @param  Destination Pointer to a Null-terminated Unicode string.\r
   @param  Source      Pointer to a Null-terminated Unicode string.\r
 \r
   @param  Destination Pointer to a Null-terminated Unicode string.\r
   @param  Source      Pointer to a Null-terminated Unicode string.\r


@@ -295,12 +297,14 @@ StrCmp (
   If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().\r
   If Length > 0 and SecondString is NULL, then ASSERT().\r
   If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().\r
   If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().\r
   If Length > 0 and SecondString is NULL, then ASSERT().\r
   If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().\r

-  If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more\r
-  than PcdMaximumUnicodeStringLength Unicode characters not including the\r
-  Null-terminator, then ASSERT().\r
-  If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more\r
-  than PcdMaximumUnicodeStringLength Unicode characters not including the\r
-  Null-terminator, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and Length is greater than\r
+  PcdMaximumUnicodeStringLength, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than\r
+  PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,\r
+  then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than\r
+  PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,\r
+  then ASSERT().\r

 \r
   @param  FirstString   Pointer to a Null-terminated Unicode string.\r
   @param  SecondString  Pointer to a Null-terminated Unicode string.\r
 \r
   @param  FirstString   Pointer to a Null-terminated Unicode string.\r
   @param  SecondString  Pointer to a Null-terminated Unicode string.\r


@@ -377,16 +381,17 @@ StrCat (
   If Length > 0 and Source is NULL, then ASSERT().\r
   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().\r
   If Source and Destination overlap, then ASSERT().\r
   If Length > 0 and Source is NULL, then ASSERT().\r
   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().\r
   If Source and Destination overlap, then ASSERT().\r

+  If PcdMaximumUnicodeStringLength is not zero, and Length is greater than \r
+  PcdMaximumUnicodeStringLength, then ASSERT().\r

   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more\r
   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more\r

-  than PcdMaximumUnicodeStringLength Unicode characters not including the\r
+  than PcdMaximumUnicodeStringLength Unicode characters, not including the\r

   Null-terminator, then ASSERT().\r
   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
   Null-terminator, then ASSERT().\r
   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r

-  PcdMaximumUnicodeStringLength Unicode characters not including the\r
+  PcdMaximumUnicodeStringLength Unicode characters, not including the\r

   Null-terminator, then ASSERT().\r
   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination\r
   Null-terminator, then ASSERT().\r
   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination\r

-  and Source results in a Unicode string with more than\r
-  PcdMaximumUnicodeStringLength Unicode characters not including the\r
-  Null-terminator, then ASSERT().\r
+  and Source results in a Unicode string with more than PcdMaximumUnicodeStringLength\r
+  Unicode characters, not including the Null-terminator, then ASSERT().\r

 \r
   @param  Destination Pointer to a Null-terminated Unicode string.\r
   @param  Source      Pointer to a Null-terminated Unicode string.\r
 \r
   @param  Destination Pointer to a Null-terminated Unicode string.\r
   @param  Source      Pointer to a Null-terminated Unicode string.\r


@@ -682,8 +687,10 @@ AsciiStrCpy (
   If Destination is NULL, then ASSERT().\r
   If Source is NULL, then ASSERT().\r
   If Source and Destination overlap, then ASSERT().\r
   If Destination is NULL, then ASSERT().\r
   If Source is NULL, then ASSERT().\r
   If Source and Destination overlap, then ASSERT().\r

+  If PcdMaximumAsciiStringLength is not zero, and Length is greater than \r
+  PcdMaximumAsciiStringLength, then ASSERT().\r

   If PcdMaximumAsciiStringLength is not zero, and Source contains more than\r
   If PcdMaximumAsciiStringLength is not zero, and Source contains more than\r

-  PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
+  PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,\r

   then ASSERT().\r
 \r
   @param  Destination Pointer to a Null-terminated ASCII string.\r
   then ASSERT().\r
 \r
   @param  Destination Pointer to a Null-terminated ASCII string.\r


@@ -834,11 +841,13 @@ AsciiStriCmp (
 \r
   If Length > 0 and FirstString is NULL, then ASSERT().\r
   If Length > 0 and SecondString is NULL, then ASSERT().\r
 \r
   If Length > 0 and FirstString is NULL, then ASSERT().\r
   If Length > 0 and SecondString is NULL, then ASSERT().\r

-  If PcdMaximumAsciiStringLength is not zero and FirstString contains more than\r
-  PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
+  If PcdMaximumAsciiStringLength is not zero, and Length is greater than \r
+  PcdMaximumAsciiStringLength, then ASSERT().\r
+  If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than\r
+  PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,\r

   then ASSERT().\r
   then ASSERT().\r

-  If PcdMaximumAsciiStringLength is not zero and SecondString contains more than\r
-  PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
+  If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than\r
+  PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,\r

   then ASSERT().\r
 \r
   @param  FirstString   Pointer to a Null-terminated ASCII string.\r
   then ASSERT().\r
 \r
   @param  FirstString   Pointer to a Null-terminated ASCII string.\r


@@ -909,15 +918,17 @@ AsciiStrCat (
   If Length > 0 and Destination is NULL, then ASSERT().\r
   If Length > 0 and Source is NULL, then ASSERT().\r
   If Source and Destination overlap, then ASSERT().\r
   If Length > 0 and Destination is NULL, then ASSERT().\r
   If Length > 0 and Source is NULL, then ASSERT().\r
   If Source and Destination overlap, then ASSERT().\r

+  If PcdMaximumAsciiStringLength is not zero, and Length is greater than\r
+  PcdMaximumAsciiStringLength, then ASSERT().\r

   If PcdMaximumAsciiStringLength is not zero, and Destination contains more than\r
   If PcdMaximumAsciiStringLength is not zero, and Destination contains more than\r

-  PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
+  PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,\r

   then ASSERT().\r
   If PcdMaximumAsciiStringLength is not zero, and Source contains more than\r
   then ASSERT().\r
   If PcdMaximumAsciiStringLength is not zero, and Source contains more than\r

-  PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
+  PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,\r

   then ASSERT().\r
   If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and\r
   Source results in a ASCII string with more than PcdMaximumAsciiStringLength\r
   then ASSERT().\r
   If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and\r
   Source results in a ASCII string with more than PcdMaximumAsciiStringLength\r

-  ASCII characters not including the Null-terminator, then ASSERT().\r
+  ASCII characters, not including the Null-terminator, then ASSERT().\r

 \r
   @param  Destination Pointer to a Null-terminated ASCII string.\r
   @param  Source      Pointer to a Null-terminated ASCII string.\r
 \r
   @param  Destination Pointer to a Null-terminated ASCII string.\r
   @param  Source      Pointer to a Null-terminated ASCII string.\r


@@ -6995,7 +7006,7 @@ AsmDisablePaging64 (
   in ExtraStackSize. If parameters are passed to the 16-bit real mode code,\r
   then the actual minimum stack size is ExtraStackSize plus the maximum number\r
   of bytes that need to be passed to the 16-bit real mode code.\r
   in ExtraStackSize. If parameters are passed to the 16-bit real mode code,\r
   then the actual minimum stack size is ExtraStackSize plus the maximum number\r
   of bytes that need to be passed to the 16-bit real mode code.\r

-\r
+  \r

   If RealModeBufferSize is NULL, then ASSERT().\r
   If ExtraStackSize is NULL, then ASSERT().\r
 \r
   If RealModeBufferSize is NULL, then ASSERT().\r
   If ExtraStackSize is NULL, then ASSERT().\r
 \r


@@ -7019,6 +7030,9 @@ AsmGetThunk16Properties (
   Prepares all structures a code required to use AsmThunk16().\r
 \r
   Prepares all structures and code required to use AsmThunk16().\r
   Prepares all structures a code required to use AsmThunk16().\r
 \r
   Prepares all structures and code required to use AsmThunk16().\r

+  \r
+  This interface is limited to be used in physical mode but can not be used in \r
+  virtual mode with paging.\r

 \r
   If ThunkContext is NULL, then ASSERT().\r
 \r
 \r
   If ThunkContext is NULL, then ASSERT().\r
 \r


@@ -7079,6 +7093,9 @@ AsmPrepareThunk16 (
   If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in \r
   ThunkAttributes, then ASSERT().\r
 \r
   If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in \r
   ThunkAttributes, then ASSERT().\r
 \r

+  This interface is limited to be used in physical mode but can not be used in \r
+  virtual mode with paging.\r
+\r

   @param  ThunkContext  A pointer to the context structure that describes the\r
                         16-bit real mode code to call.\r
 \r
   @param  ThunkContext  A pointer to the context structure that describes the\r
                         16-bit real mode code to call.\r
 \r


@@ -7101,6 +7118,9 @@ AsmThunk16 (
   real mode thunk, then it is more efficient if AsmPrepareThunk16() is called\r
   once and AsmThunk16() can be called for each 16-bit real mode thunk.\r
 \r
   real mode thunk, then it is more efficient if AsmPrepareThunk16() is called\r
   once and AsmThunk16() can be called for each 16-bit real mode thunk.\r
 \r

+  This interface is limited to be used in physical mode but can not be used in \r
+  virtual mode with paging.\r
+\r

   See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.\r
 \r
   @param  ThunkContext  A pointer to the context structure that describes the\r
   See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.\r
 \r
   @param  ThunkContext  A pointer to the context structure that describes the\r