From c0a3c3da98cef6286a509eb685a4ff5375f8347b Mon Sep 17 00:00:00 2001 From: Eric Dong Date: Tue, 20 Aug 2013 07:13:28 +0000 Subject: [PATCH] Refine the comments and code to follow spec. Signed-off-by: Eric Dong Reviewed-by: Liming Gao git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@14573 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Universal/HiiDatabaseDxe/ConfigRouting.c | 16 ++-- .../Universal/HiiDatabaseDxe/Database.c | 19 +++-- MdeModulePkg/Universal/HiiDatabaseDxe/Font.c | 17 +++-- .../Universal/HiiDatabaseDxe/HiiDatabase.h | 74 +++++++++++-------- .../Universal/HiiDatabaseDxe/String.c | 22 ++++-- 5 files changed, 87 insertions(+), 61 deletions(-) diff --git a/MdeModulePkg/Universal/HiiDatabaseDxe/ConfigRouting.c b/MdeModulePkg/Universal/HiiDatabaseDxe/ConfigRouting.c index 40d0230b4d..d6705d0247 100644 --- a/MdeModulePkg/Universal/HiiDatabaseDxe/ConfigRouting.c +++ b/MdeModulePkg/Universal/HiiDatabaseDxe/ConfigRouting.c @@ -3767,9 +3767,9 @@ Done: instance. @param Results Null-terminated Unicode string in format which has all values - filled in for the names in the Request string. - String to be allocated by the called function. - De-allocation is up to the caller. + filled in for the entirety of the current HII + database. String to be allocated by the called + function. De-allocation is up to the caller. @retval EFI_SUCCESS The Results string is filled with the values corresponding to all requested names. @@ -4482,8 +4482,9 @@ Exit: (see below) is returned. @param BlockSize The length of the Block in units of UINT8. On input, this is the size of the Block. On output, - if successful, contains the index of the last - modified byte in the Block. + if successful, contains the largest index of the + modified byte in the Block, or the required buffer + size if the Block is not large enough. @param Progress On return, points to an element of the ConfigResp string filled in with the offset of the most recent '&' before the first failing name / value @@ -4503,7 +4504,8 @@ Exit: value pair. Block is left updated and Progress points at the '&' preceding the first non-. - @retval EFI_DEVICE_ERROR Block not large enough. Progress undefined. + @retval EFI_BUFFER_TOO_SMALL Block not large enough. Progress undefined. + BlockSize is updated with the required buffer size. @retval EFI_NOT_FOUND Target for the specified routing data was not found. Progress points to the "G" in "GUID" of the errant routing data. @@ -4680,7 +4682,7 @@ HiiConfigToBlock ( if (MaxBlockSize > BufferSize) { *BlockSize = MaxBlockSize; if (Block != NULL) { - return EFI_DEVICE_ERROR; + return EFI_BUFFER_TOO_SMALL; } } diff --git a/MdeModulePkg/Universal/HiiDatabaseDxe/Database.c b/MdeModulePkg/Universal/HiiDatabaseDxe/Database.c index 0e16f9850e..65334ded5e 100644 --- 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. @retval EFI_SUCCESS The matching handles are outputed successfully. - HandleBufferLength is updated with the actual length. + HandleBufferLength is updated with the actual length. @retval EFI_BUFFER_TO_SMALL The HandleBufferLength parameter indicates that Handle is too small to support the number of handles. HandleBufferLength is updated with a value that will enable the data to fit. @retval EFI_NOT_FOUND No matching handle could not be found in database. - @retval EFI_INVALID_PARAMETER Handle or HandleBufferLength was NULL. - + @retval EFI_INVALID_PARAMETER HandleBufferLength was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by HandleBufferLength was not + zero and Handle was NULL. @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but - PackageGuid is not NULL, PackageType is a EFI_HII_ - PACKAGE_TYPE_GUID but PackageGuid is NULL. + PackageGuid is not NULL, PackageType is a EFI_HII_ + PACKAGE_TYPE_GUID but PackageGuid is NULL. **/ EFI_STATUS @@ -3263,7 +3264,9 @@ HiiListPackageLists ( value that will enable the data to fit. @retval EFI_NOT_FOUND The specifiecd Handle could not be found in the current database. - @retval EFI_INVALID_PARAMETER Handle or Buffer or BufferSize was NULL. + @retval EFI_INVALID_PARAMETER BufferSize was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by BufferSize was not zero + and Buffer was NULL. **/ EFI_STATUS @@ -3525,7 +3528,9 @@ HiiUnregisterPackageNotify ( number of GUIDs. KeyGuidBufferLength is updated with a value that will enable the data to fit. - @retval EFI_INVALID_PARAMETER The KeyGuidBuffer or KeyGuidBufferLength was NULL. + @retval EFI_INVALID_PARAMETER The KeyGuidBufferLength is NULL. + @retval EFI_INVALID_PARAMETER The value referenced by KeyGuidBufferLength is not + zero and KeyGuidBuffer is NULL. @retval EFI_NOT_FOUND There was no keyboard layout. **/ diff --git a/MdeModulePkg/Universal/HiiDatabaseDxe/Font.c b/MdeModulePkg/Universal/HiiDatabaseDxe/Font.c index f6f784e733..24bb502996 100644 --- 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 returned font handle or points to NULL if there are no more matching fonts. - @param StringInfoIn Upon entry, points to the font to return - information about. - If NULL, then the information about the system default - font will be returned. - @param StringInfoOut Upon return, contains the matching font's - information. If NULL, then no information is - returned. It's caller's responsibility to free - this buffer. + @param StringInfoIn Upon entry, points to the font to return information + about. If NULL, then the information about the system + default font will be returned. + @param StringInfoOut Upon return, contains the matching font's information. + If NULL, then no information is returned. This buffer + is allocated with a call to the Boot Service AllocatePool(). + It is the caller's responsibility to call the Boot + Service FreePool() when the caller no longer requires + the contents of StringInfoOut. @param String Points to the string which will be tested to determine if all characters are available. If NULL, then any font is acceptable. diff --git a/MdeModulePkg/Universal/HiiDatabaseDxe/HiiDatabase.h b/MdeModulePkg/Universal/HiiDatabaseDxe/HiiDatabase.h index e5628b5bf0..9046d9057b 100644 --- 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 returned font handle or points to NULL if there are no more matching fonts. - @param StringInfoIn Upon entry, points to the font to return - information about. If NULL, then the information about the system default - font will be returned. - @param StringInfoOut Upon return, contains the matching font's - information. If NULL, then no information is - returned. It's caller's responsibility to free - this buffer. + @param StringInfoIn Upon entry, points to the font to return information + about. If NULL, then the information about the system + default font will be returned. + @param StringInfoOut Upon return, contains the matching font's information. + If NULL, then no information is returned. This buffer + is allocated with a call to the Boot Service AllocatePool(). + It is the caller's responsibility to call the Boot + Service FreePool() when the caller no longer requires + the contents of StringInfoOut. @param String Points to the string which will be tested to determine if all characters are available. If NULL, then any font is acceptable. @@ -739,7 +741,7 @@ HiiGetGlyph ( @retval EFI_SUCCESS Matching font returned successfully. @retval EFI_NOT_FOUND No matching font was found. @retval EFI_INVALID_PARAMETER StringInfoIn is NULL. - @retval EFI_INVALID_PARAMETER StringInfoIn->FontInfoMask is an invalid combination. + @retval EFI_INVALID_PARAMETER StringInfoIn->FontInfoMask is an invalid combination. @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the request. **/ @@ -1004,13 +1006,14 @@ HiiNewString ( @retval EFI_SUCCESS The string was returned successfully. @retval EFI_NOT_FOUND The string specified by StringId is not available. - @retval EFI_NOT_FOUND The string specified by StringId is available but - not in the specified language. - The specified PackageList is not in the database. - @retval EFI_INVALID_LANGUAGE - The string specified by StringId is available but + The specified PackageList is not in the database. + @retval EFI_INVALID_LANGUAGE The string specified by StringId is available but + not in the specified language. @retval EFI_BUFFER_TOO_SMALL The buffer specified by StringSize is too small to hold the string. - @retval EFI_INVALID_PARAMETER The String or Language or StringSize was NULL. + @retval EFI_INVALID_PARAMETER The Language or StringSize was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by StringSize was not zero + and String was NULL. @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the request. @@ -1076,7 +1079,8 @@ HiiSetString ( points to the length of Languages, in bytes. @retval EFI_SUCCESS The languages were returned successfully. - @retval EFI_INVALID_PARAMETER The Languages or LanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER The LanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by LanguagesSize is not zero and Languages is NULL. @retval EFI_BUFFER_TOO_SMALL The LanguagesSize is too small to hold the list of supported languages. LanguageSize is updated to contain the required size. @@ -1117,15 +1121,16 @@ HiiGetLanguages ( in bytes. @retval EFI_SUCCESS Secondary languages were correctly returned. - @retval EFI_INVALID_PARAMETER PrimaryLanguage or SecondaryLanguages or - SecondaryLanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER PrimaryLanguage or SecondaryLanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by SecondaryLanguagesSize is not + zero and SecondaryLanguages is NULL. @retval EFI_BUFFER_TOO_SMALL The buffer specified by SecondaryLanguagesSize is too small to hold the returned information. SecondaryLanguageSize is updated to hold the size of the buffer required. @retval EFI_INVALID_LANGUAGE The language specified by PrimaryLanguage is not present in the specified package list. - @retval EFI_NOT_FOUND The specified PackageList is not in the Database. + @retval EFI_NOT_FOUND The specified PackageList is not in the Database. **/ EFI_STATUS @@ -1244,18 +1249,19 @@ HiiUpdatePackageList ( @param Handle An array of EFI_HII_HANDLE instances returned. @retval EFI_SUCCESS The matching handles are outputed successfully. - HandleBufferLength is updated with the actual length. + HandleBufferLength is updated with the actual length. @retval EFI_BUFFER_TO_SMALL The HandleBufferLength parameter indicates that Handle is too small to support the number of handles. HandleBufferLength is updated with a value that will enable the data to fit. @retval EFI_NOT_FOUND No matching handle could not be found in database. - @retval EFI_INVALID_PARAMETER Handle or HandleBufferLength was NULL. - @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but - PackageGuid is not NULL, PackageType is a EFI_HII_ - PACKAGE_TYPE_GUID but PackageGuid is NULL. - + @retval EFI_INVALID_PARAMETER HandleBufferLength was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by HandleBufferLength was not + zero and Handle was NULL. + @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but + PackageGuid is not NULL, PackageType is a EFI_HII_ + PACKAGE_TYPE_GUID but PackageGuid is NULL. **/ EFI_STATUS @@ -1293,7 +1299,9 @@ HiiListPackageLists ( a value that will enable the data to fit. @retval EFI_NOT_FOUND The specifiecd Handle could not be found in the current database. - @retval EFI_INVALID_PARAMETER Handle or Buffer or BufferSize was NULL. + @retval EFI_INVALID_PARAMETER BufferSize was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by BufferSize was not zero + and Buffer was NULL. **/ EFI_STATUS @@ -1393,8 +1401,9 @@ HiiUnregisterPackageNotify ( number of GUIDs. KeyGuidBufferLength is updated with a value that will enable the data to fit. - @retval EFI_INVALID_PARAMETER The KeyGuidBuffer or KeyGuidBufferLength was - NULL. + @retval EFI_INVALID_PARAMETER The KeyGuidBufferLength is NULL. + @retval EFI_INVALID_PARAMETER The value referenced by KeyGuidBufferLength is not + zero and KeyGuidBuffer is NULL. @retval EFI_NOT_FOUND There was no keyboard layout. **/ @@ -1549,9 +1558,9 @@ HiiConfigRoutingExtractConfig ( instance. @param Results Null-terminated Unicode string in format which has all values - filled in for the names in the Request string. - String to be allocated by the called function. - De-allocation is up to the caller. + filled in for the entirety of the current HII + database. String to be allocated by the called + function. De-allocation is up to the caller. @retval EFI_SUCCESS The Results string is filled with the values corresponding to all requested names. @@ -1674,8 +1683,9 @@ HiiBlockToConfig ( (see below) is returned. @param BlockSize The length of the Block in units of UINT8. On input, this is the size of the Block. On output, - if successful, contains the index of the last - modified byte in the Block. + if successful, contains the largest index of the + modified byte in the Block, or the required buffer + size if the Block is not large enough. @param Progress On return, points to an element of the ConfigResp string filled in with the offset of the most recent '&' before the first failing name / value @@ -1700,6 +1710,8 @@ HiiBlockToConfig ( value pair. Block is left updated and Progress points at the '&' preceding the first non-. + @retval EFI_BUFFER_TOO_SMALL Block not large enough. Progress undefined. + BlockSize is updated with the required buffer size. **/ EFI_STATUS diff --git a/MdeModulePkg/Universal/HiiDatabaseDxe/String.c b/MdeModulePkg/Universal/HiiDatabaseDxe/String.c index c55305886f..f3c0555cbc 100644 --- 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 @retval EFI_BUFFER_TOO_SMALL The buffer specified by StringSize is too small to hold the string. - @retval EFI_INVALID_PARAMETER The String or Language or StringSize was NULL. + @retval EFI_INVALID_PARAMETER The Language or StringSize was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by StringSize was not zero and String was NULL. @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the request. @@ -1775,7 +1776,8 @@ HiiSetString ( the length of Languages, in bytes. @retval EFI_SUCCESS The languages were returned successfully. - @retval EFI_INVALID_PARAMETER The Languages or LanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER The LanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by LanguagesSize is not zero and Languages is NULL. @retval EFI_BUFFER_TOO_SMALL The LanguagesSize is too small to hold the list of supported languages. LanguageSize is updated to contain the required size. @@ -1799,7 +1801,10 @@ HiiGetLanguages ( HII_STRING_PACKAGE_INSTANCE *StringPackage; UINTN ResultSize; - if (This == NULL || Languages == NULL || LanguagesSize == NULL || PackageList == NULL) { + if (This == NULL || LanguagesSize == NULL || PackageList == NULL) { + return EFI_INVALID_PARAMETER; + } + if (*LanguagesSize != 0 && Languages == NULL) { return EFI_INVALID_PARAMETER; } if (!IsHiiHandleValid (PackageList)) { @@ -1871,15 +1876,16 @@ HiiGetLanguages ( points to the length of SecondaryLanguages in bytes. @retval EFI_SUCCESS Secondary languages were correctly returned. - @retval EFI_INVALID_PARAMETER PrimaryLanguage or SecondaryLanguages or - SecondaryLanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER PrimaryLanguage or SecondaryLanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by SecondaryLanguagesSize is not + zero and SecondaryLanguages is NULL. @retval EFI_BUFFER_TOO_SMALL The buffer specified by SecondaryLanguagesSize is too small to hold the returned information. SecondaryLanguageSize is updated to hold the size of the buffer required. @retval EFI_INVALID_LANGUAGE The language specified by PrimaryLanguage is not present in the specified package list. - @retval EFI_NOT_FOUND The specified PackageList is not in the Database. + @retval EFI_NOT_FOUND The specified PackageList is not in the Database. **/ EFI_STATUS @@ -1901,10 +1907,10 @@ HiiGetSecondaryLanguages ( CHAR8 *Languages; UINTN ResultSize; - if (This == NULL || PackageList == NULL || PrimaryLanguage == NULL) { + if (This == NULL || PackageList == NULL || PrimaryLanguage == NULL || SecondaryLanguagesSize == NULL) { return EFI_INVALID_PARAMETER; } - if (SecondaryLanguages == NULL || SecondaryLanguagesSize == NULL) { + if (SecondaryLanguages == NULL && *SecondaryLanguagesSize != 0) { return EFI_INVALID_PARAMETER; } if (!IsHiiHandleValid (PackageList)) { -- 2.39.2