Refine the comments and code to follow spec.

Signed-off-by: Eric Dong <eric.dong@intel.com>
Reviewed-by: Liming Gao <liming.gao@intel.com>
git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@14573 6f19259b-4bc3-4df7-8a09-765794883524

diff --git a/MdeModulePkg/Universal/HiiDatabaseDxe/ConfigRouting.c b/MdeModulePkg/Universal/HiiDatabaseDxe/ConfigRouting.c
index 40d0230b4d6f416e044e56e8f26bf61c84a83b90..d6705d02473edecb5555b851e0e5cdb96e285c42 100644 (file)
--- a/MdeModulePkg/Universal/HiiDatabaseDxe/ConfigRouting.c
+++ b/MdeModulePkg/Universal/HiiDatabaseDxe/ConfigRouting.c
@@ -3767,9 +3767,9 @@ Done:
                                  instance.\r
   @param  Results                Null-terminated Unicode string in\r
                                  <MultiConfigAltResp> format which has all values\r
-                                 filled in for the names in the Request string.\r
-                                 String to be allocated by the  called function.\r
-                                 De-allocation is up to the caller.\r
+                                 filled in for the entirety of the current HII \r
+                                 database. String to be allocated by the  called \r
+                                 function. De-allocation is up to the caller.\r
 \r
   @retval EFI_SUCCESS            The Results string is filled with the values\r
                                  corresponding to all requested names.\r
@@ -4482,8 +4482,9 @@ Exit:
                                  (see below)  is returned.\r
   @param  BlockSize              The length of the Block in units of UINT8.  On\r
                                  input, this is the size of the Block. On output,\r
-                                 if successful, contains the index of the  last\r
-                                 modified byte in the Block.\r
+                                 if successful, contains the largest index of the\r
+                                 modified byte in the Block, or the required buffer\r
+                                 size if the Block is not large enough.\r
   @param  Progress               On return, points to an element of the ConfigResp\r
                                  string filled in with the offset of the most\r
                                  recent '&' before the first failing name / value\r
@@ -4503,7 +4504,8 @@ Exit:
                                  value pair. Block is left updated and\r
                                  Progress points at the '&' preceding the first\r
                                  non-<BlockName>.\r
-  @retval EFI_DEVICE_ERROR       Block not large enough. Progress undefined.\r
+  @retval EFI_BUFFER_TOO_SMALL   Block not large enough. Progress undefined. \r
+                                 BlockSize is updated with the required buffer size.\r
   @retval EFI_NOT_FOUND          Target for the specified routing data was not found.\r
                                  Progress points to the "G" in "GUID" of the errant\r
                                  routing data.\r
@@ -4680,7 +4682,7 @@ HiiConfigToBlock (
   if (MaxBlockSize > BufferSize) {\r
     *BlockSize = MaxBlockSize;\r
     if (Block != NULL) {\r
-      return EFI_DEVICE_ERROR;\r
+      return EFI_BUFFER_TOO_SMALL;\r
     }\r
   }\r
 \r

diff --git a/MdeModulePkg/Universal/HiiDatabaseDxe/Database.c b/MdeModulePkg/Universal/HiiDatabaseDxe/Database.c
index 0e16f9850e90d3b6b71c1e64dbe347a6238525f8..65334ded5ed30fafbfd30241edc71a47dd8e18eb 100644 (file)
--- a/MdeModulePkg/Universal/HiiDatabaseDxe/Database.c
+++ b/MdeModulePkg/Universal/HiiDatabaseDxe/Database.c
@@ -3100,17 +3100,18 @@ HiiUpdatePackageList (
   @param  Handle                 An array of EFI_HII_HANDLE instances returned.\r
 \r
   @retval EFI_SUCCESS            The matching handles are outputed successfully.\r
-                                               HandleBufferLength is updated with the actual length.\r
+                                 HandleBufferLength is updated with the actual length.\r
   @retval EFI_BUFFER_TO_SMALL    The HandleBufferLength parameter indicates that\r
                                  Handle is too small to support the number of\r
                                  handles. HandleBufferLength is updated with a\r
                                  value that will  enable the data to fit.\r
   @retval EFI_NOT_FOUND          No matching handle could not be found in database.\r
-  @retval EFI_INVALID_PARAMETER  Handle or HandleBufferLength was NULL.\r
-  \r
+  @retval EFI_INVALID_PARAMETER  HandleBufferLength was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The value referenced by HandleBufferLength was not\r
+                                 zero and Handle was NULL.\r
   @retval EFI_INVALID_PARAMETER  PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but\r
-                                                     PackageGuid is not NULL, PackageType is a EFI_HII_\r
-                                                     PACKAGE_TYPE_GUID but PackageGuid is NULL.\r
+                                 PackageGuid is not NULL, PackageType is a EFI_HII_\r
+                                 PACKAGE_TYPE_GUID but PackageGuid is NULL.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -3263,7 +3264,9 @@ HiiListPackageLists (
                                  value that will enable the data to fit.\r
   @retval EFI_NOT_FOUND          The specifiecd Handle could not be found in the\r
                                  current database.\r
-  @retval EFI_INVALID_PARAMETER  Handle or Buffer or BufferSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  BufferSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The value referenced by BufferSize was not zero \r
+                                 and Buffer was NULL.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -3525,7 +3528,9 @@ HiiUnregisterPackageNotify (
                                  number of GUIDs. KeyGuidBufferLength is\r
                                  updated with a value that will enable the data to\r
                                  fit.\r
-  @retval EFI_INVALID_PARAMETER  The KeyGuidBuffer or KeyGuidBufferLength was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The KeyGuidBufferLength is NULL.\r
+  @retval EFI_INVALID_PARAMETER  The value referenced by KeyGuidBufferLength is not\r
+                                 zero and KeyGuidBuffer is NULL.\r
   @retval EFI_NOT_FOUND          There was no keyboard layout.\r
 \r
 **/\r

diff --git a/MdeModulePkg/Universal/HiiDatabaseDxe/Font.c b/MdeModulePkg/Universal/HiiDatabaseDxe/Font.c
index f6f784e733c202f367479f8f19a88ec8dbbf8fd8..24bb502996a83b9bd3301b582521fa48d326d00f 100644 (file)
--- a/MdeModulePkg/Universal/HiiDatabaseDxe/Font.c
+++ b/MdeModulePkg/Universal/HiiDatabaseDxe/Font.c
@@ -2679,14 +2679,15 @@ Exit:
                                   with the  first font. On return, points to the\r
                                   returned font handle or points to NULL if there\r
                                   are no more matching fonts.\r
-  @param  StringInfoIn            Upon entry, points to the font to return\r
-                                  information about. \r
-                                  If NULL, then the information about the system default \r
-                                  font will be returned.\r
-  @param  StringInfoOut           Upon return, contains the matching font's\r
-                                  information.  If NULL, then no information is\r
-                                  returned. It's caller's responsibility to free\r
-                                  this buffer.\r
+  @param  StringInfoIn            Upon entry, points to the font to return information\r
+                                  about. If NULL, then the information about the system\r
+                                  default font will be returned.\r
+  @param  StringInfoOut           Upon return, contains the matching font's information.\r
+                                  If NULL, then no information is returned. This buffer\r
+                                  is allocated with a call to the Boot Service AllocatePool().\r
+                                  It is the caller's responsibility to call the Boot \r
+                                  Service FreePool() when the caller no longer requires\r
+                                  the contents of StringInfoOut.\r
   @param  String                  Points to the string which will be tested to\r
                                   determine  if all characters are available. If\r
                                   NULL, then any font  is acceptable.\r

diff --git a/MdeModulePkg/Universal/HiiDatabaseDxe/HiiDatabase.h b/MdeModulePkg/Universal/HiiDatabaseDxe/HiiDatabase.h
index e5628b5bf04cdca1ad8b0b5f6455fbd3023d5625..9046d9057b00548b47a3b10e820d4f6b91f2ce36 100644 (file)
--- a/MdeModulePkg/Universal/HiiDatabaseDxe/HiiDatabase.h
+++ b/MdeModulePkg/Universal/HiiDatabaseDxe/HiiDatabase.h
@@ -725,13 +725,15 @@ HiiGetGlyph (
                                   with the  first font. On return, points to the\r
                                   returned font handle or points to NULL if there\r
                                   are no more matching fonts.\r
-  @param  StringInfoIn            Upon entry, points to the font to return\r
-                                  information about. If NULL, then the information about the system default \r
-                                  font will be returned.\r
-  @param  StringInfoOut           Upon return, contains the matching font's\r
-                                  information.  If NULL, then no information is\r
-                                  returned. It's caller's responsibility to free\r
-                                  this buffer.\r
+  @param  StringInfoIn            Upon entry, points to the font to return information\r
+                                  about. If NULL, then the information about the system\r
+                                  default font will be returned.\r
+  @param  StringInfoOut           Upon return, contains the matching font's information.\r
+                                  If NULL, then no information is returned. This buffer\r
+                                  is allocated with a call to the Boot Service AllocatePool().\r
+                                  It is the caller's responsibility to call the Boot \r
+                                  Service FreePool() when the caller no longer requires\r
+                                  the contents of StringInfoOut.\r
   @param  String                  Points to the string which will be tested to\r
                                   determine  if all characters are available. If\r
                                   NULL, then any font  is acceptable.\r
@@ -739,7 +741,7 @@ HiiGetGlyph (
   @retval EFI_SUCCESS             Matching font returned successfully.\r
   @retval EFI_NOT_FOUND           No matching font was found.\r
   @retval EFI_INVALID_PARAMETER   StringInfoIn is NULL.\r
-  @retval EFI_INVALID_PARAMETER  StringInfoIn->FontInfoMask is an invalid combination.\r
+  @retval EFI_INVALID_PARAMETER   StringInfoIn->FontInfoMask is an invalid combination.\r
   @retval EFI_OUT_OF_RESOURCES    There were insufficient resources to complete the\r
                                   request.\r
 **/\r
@@ -1004,13 +1006,14 @@ HiiNewString (
   @retval EFI_SUCCESS             The string was returned successfully.\r
   @retval EFI_NOT_FOUND           The string specified by StringId is not\r
                                   available.\r
-  @retval EFI_NOT_FOUND           The string specified by StringId is available but\r
-                                                not in the specified language.\r
-                                                The specified PackageList is not in the database.\r
-  @retval EFI_INVALID_LANGUAGE   - The string specified by StringId is available but\r
+                                  The specified PackageList is not in the database.\r
+  @retval EFI_INVALID_LANGUAGE    The string specified by StringId is available but\r
+                                  not in the specified language.\r
   @retval EFI_BUFFER_TOO_SMALL    The buffer specified by StringSize is too small\r
                                   to  hold the string.\r
-  @retval EFI_INVALID_PARAMETER   The String or Language or StringSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER   The Language or StringSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER   The value referenced by StringSize was not zero\r
+                                  and String was NULL.\r
   @retval EFI_OUT_OF_RESOURCES    There were insufficient resources to complete the\r
                                    request.\r
 \r
@@ -1076,7 +1079,8 @@ HiiSetString (
                                   points to the length of Languages, in bytes.\r
 \r
   @retval EFI_SUCCESS             The languages were returned successfully.\r
-  @retval EFI_INVALID_PARAMETER   The Languages or LanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER   The LanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER   The value referenced by LanguagesSize is not zero and Languages is NULL.\r
   @retval EFI_BUFFER_TOO_SMALL    The LanguagesSize is too small to hold the list\r
                                   of  supported languages. LanguageSize is updated\r
                                   to contain the required size.\r
@@ -1117,15 +1121,16 @@ HiiGetLanguages (
                                   in bytes.\r
 \r
   @retval EFI_SUCCESS             Secondary languages were correctly returned.\r
-  @retval EFI_INVALID_PARAMETER   PrimaryLanguage or SecondaryLanguages or\r
-                                  SecondaryLanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER   PrimaryLanguage or SecondaryLanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER   The value referenced by SecondaryLanguagesSize is not\r
+                                  zero and SecondaryLanguages is NULL.\r
   @retval EFI_BUFFER_TOO_SMALL    The buffer specified by SecondaryLanguagesSize is\r
                                   too small to hold the returned information.\r
                                   SecondaryLanguageSize is updated to hold the size of\r
                                   the buffer required.\r
   @retval EFI_INVALID_LANGUAGE    The language specified by PrimaryLanguage is not\r
                                   present in the specified package list.\r
-  @retval EFI_NOT_FOUND          The specified PackageList is not in the Database.                                \r
+  @retval EFI_NOT_FOUND           The specified PackageList is not in the Database.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -1244,18 +1249,19 @@ HiiUpdatePackageList (
   @param  Handle                  An array of EFI_HII_HANDLE instances returned.\r
 \r
   @retval EFI_SUCCESS             The matching handles are outputed successfully.\r
-                                                HandleBufferLength is updated with the actual length.\r
+                                  HandleBufferLength is updated with the actual length.\r
   @retval EFI_BUFFER_TO_SMALL     The HandleBufferLength parameter indicates that\r
                                   Handle is too small to support the number of\r
                                   handles. HandleBufferLength is updated with a\r
                                   value that will  enable the data to fit.\r
   @retval EFI_NOT_FOUND           No matching handle could not be found in\r
                                   database.\r
-  @retval EFI_INVALID_PARAMETER   Handle or HandleBufferLength was NULL.\r
-  @retval EFI_INVALID_PARAMETER  PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but\r
-                         PackageGuid is not NULL, PackageType is a EFI_HII_\r
-                         PACKAGE_TYPE_GUID but PackageGuid is NULL.\r
-  \r
+  @retval EFI_INVALID_PARAMETER   HandleBufferLength was NULL.\r
+  @retval EFI_INVALID_PARAMETER   The value referenced by HandleBufferLength was not\r
+                                  zero and Handle was NULL.\r
+  @retval EFI_INVALID_PARAMETER   PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but\r
+                                  PackageGuid is not NULL, PackageType is a EFI_HII_\r
+                                  PACKAGE_TYPE_GUID but PackageGuid is NULL.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -1293,7 +1299,9 @@ HiiListPackageLists (
                                   a value that will enable the data to fit.\r
   @retval EFI_NOT_FOUND           The specifiecd Handle could not be found in the\r
                                   current database.\r
-  @retval EFI_INVALID_PARAMETER   Handle or Buffer or BufferSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER   BufferSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER   The value referenced by BufferSize was not zero \r
+                                  and Buffer was NULL.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -1393,8 +1401,9 @@ HiiUnregisterPackageNotify (
                                   number of GUIDs. KeyGuidBufferLength is\r
                                   updated with a value that will enable the data to\r
                                   fit.\r
-  @retval EFI_INVALID_PARAMETER   The KeyGuidBuffer or KeyGuidBufferLength was\r
-                                  NULL.\r
+  @retval EFI_INVALID_PARAMETER   The KeyGuidBufferLength is NULL.\r
+  @retval EFI_INVALID_PARAMETER   The value referenced by KeyGuidBufferLength is not\r
+                                  zero and KeyGuidBuffer is NULL.\r
   @retval EFI_NOT_FOUND           There was no keyboard layout.\r
 \r
 **/\r
@@ -1549,9 +1558,9 @@ HiiConfigRoutingExtractConfig (
                                   instance.\r
   @param  Results                 Null-terminated Unicode string in\r
                                   <MultiConfigAltResp> format which has all values\r
-                                  filled in for the names in the Request string.\r
-                                  String to be allocated by the  called function.\r
-                                  De-allocation is up to the caller.\r
+                                  filled in for the entirety of the current HII \r
+                                  database. String to be allocated by the  called \r
+                                  function. De-allocation is up to the caller.\r
 \r
   @retval EFI_SUCCESS             The Results string is filled with the values\r
                                   corresponding to all requested names.\r
@@ -1674,8 +1683,9 @@ HiiBlockToConfig (
                                   (see below)  is returned.\r
   @param  BlockSize               The length of the Block in units of UINT8.  On\r
                                   input, this is the size of the Block. On output,\r
-                                  if successful, contains the index of the  last\r
-                                  modified byte in the Block.\r
+                                  if successful, contains the largest index of the\r
+                                  modified byte in the Block, or the required buffer\r
+                                  size if the Block is not large enough.\r
   @param  Progress                On return, points to an element of the ConfigResp\r
                                    string filled in with the offset of the most\r
                                   recent '&' before the first failing name / value\r
@@ -1700,6 +1710,8 @@ HiiBlockToConfig (
                                   value pair. Block is left updated and\r
                                   Progress points at the '&' preceding the first\r
                                   non-<BlockName>.\r
+  @retval EFI_BUFFER_TOO_SMALL    Block not large enough. Progress undefined. \r
+                                  BlockSize is updated with the required buffer size.\r
 \r
 **/\r
 EFI_STATUS\r

diff --git a/MdeModulePkg/Universal/HiiDatabaseDxe/String.c b/MdeModulePkg/Universal/HiiDatabaseDxe/String.c
index c55305886f8fef38aca7afd2183dfeeb97a5f98c..f3c0555cbcb5fba5e83888c1cab2107386dd22c7 100644 (file)
--- a/MdeModulePkg/Universal/HiiDatabaseDxe/String.c
+++ b/MdeModulePkg/Universal/HiiDatabaseDxe/String.c
@@ -1590,7 +1590,8 @@ Done:
   @retval EFI_INVALID_LANGUAGE   - The string specified by StringId is available but\r
   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by StringSize is too small to\r
                                   hold the string.\r
-  @retval EFI_INVALID_PARAMETER  The String or Language or StringSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The Language or StringSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The value referenced by StringSize was not zero and String was NULL.\r
   @retval EFI_OUT_OF_RESOURCES   There were insufficient resources to complete the\r
                                  request.\r
 \r
@@ -1775,7 +1776,8 @@ HiiSetString (
                                  the length of Languages, in bytes.\r
 \r
   @retval EFI_SUCCESS            The languages were returned successfully.\r
-  @retval EFI_INVALID_PARAMETER  The Languages or LanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The LanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The value referenced by LanguagesSize is not zero and Languages is NULL.\r
   @retval EFI_BUFFER_TOO_SMALL   The LanguagesSize is too small to hold the list of\r
                                   supported languages. LanguageSize is updated to\r
                                  contain the required size.\r
@@ -1799,7 +1801,10 @@ HiiGetLanguages (
   HII_STRING_PACKAGE_INSTANCE         *StringPackage;\r
   UINTN                               ResultSize;\r
 \r
-  if (This == NULL || Languages == NULL || LanguagesSize == NULL || PackageList == NULL) {\r
+  if (This == NULL || LanguagesSize == NULL || PackageList == NULL) {\r
+    return EFI_INVALID_PARAMETER;\r
+  }\r
+  if (*LanguagesSize != 0 && Languages == NULL) {\r
     return EFI_INVALID_PARAMETER;\r
   }\r
   if (!IsHiiHandleValid (PackageList)) {\r
@@ -1871,15 +1876,16 @@ HiiGetLanguages (
                                  points to the length of SecondaryLanguages in bytes.\r
 \r
   @retval EFI_SUCCESS            Secondary languages were correctly returned.\r
-  @retval EFI_INVALID_PARAMETER  PrimaryLanguage or SecondaryLanguages or\r
-                                 SecondaryLanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  PrimaryLanguage or SecondaryLanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The value referenced by SecondaryLanguagesSize is not\r
+                                 zero and SecondaryLanguages is NULL.\r
   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by SecondaryLanguagesSize is\r
                                  too small to hold the returned information.\r
                                  SecondaryLanguageSize is updated to hold the size of\r
                                  the buffer required.\r
   @retval EFI_INVALID_LANGUAGE   The language specified by PrimaryLanguage is not\r
                                  present in the specified package list.\r
-  @retval EFI_NOT_FOUND          The specified PackageList is not in the Database.                                \r
+  @retval EFI_NOT_FOUND          The specified PackageList is not in the Database.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -1901,10 +1907,10 @@ HiiGetSecondaryLanguages (
   CHAR8                               *Languages;\r
   UINTN                               ResultSize;\r
 \r
-  if (This == NULL || PackageList == NULL || PrimaryLanguage == NULL) {\r
+  if (This == NULL || PackageList == NULL || PrimaryLanguage == NULL || SecondaryLanguagesSize == NULL) {\r
     return EFI_INVALID_PARAMETER;\r
   }\r
-  if (SecondaryLanguages == NULL || SecondaryLanguagesSize == NULL) {\r
+  if (SecondaryLanguages == NULL && *SecondaryLanguagesSize != 0) {\r
     return EFI_INVALID_PARAMETER;\r
   }\r
   if (!IsHiiHandleValid (PackageList)) {\r