/** @file\r
HII Library implementation that uses DXE protocols and services.\r
\r
- Copyright (c) 2006, Intel Corporation<BR>\r
+ Copyright (c) 2006 - 2008, Intel Corporation<BR>\r
All rights reserved. This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution. The full text of the license may be found at\r
\r
#include "InternalHiiLib.h"\r
\r
-CONST EFI_HII_DATABASE_PROTOCOL *mHiiDatabaseProt;\r
-CONST EFI_HII_STRING_PROTOCOL *mHiiStringProt;\r
-BOOLEAN mHiiProtocolsInitialized = FALSE;\r
-\r
+CONST EFI_HII_DATABASE_PROTOCOL *mHiiDatabaseProt = NULL;\r
+CONST EFI_HII_STRING_PROTOCOL *mHiiStringProt = NULL;\r
\r
/**\r
-\r
This function locate Hii relative protocols for later usage.\r
+ \r
+ The constructor function caches the protocol pointer of HII Database Protocol\r
+ and Hii String Protocol.\r
+ \r
+ It will ASSERT() if either of the protocol can't be located.\r
\r
- @param VOID\r
+ @param ImageHandle The firmware allocated handle for the EFI image.\r
+ @param SystemTable A pointer to the EFI System Table.\r
\r
- @retval VOID\r
+ @retval EFI_SUCCESS The constructor always returns EFI_SUCCESS.\r
\r
**/\r
-VOID\r
-LocateHiiProtocols (\r
- VOID\r
+EFI_STATUS\r
+EFIAPI\r
+HiiLibConstructor (\r
+ IN EFI_HANDLE ImageHandle,\r
+ IN EFI_SYSTEM_TABLE *SystemTable\r
)\r
{\r
EFI_STATUS Status;\r
\r
- if (mHiiProtocolsInitialized) {\r
- return;\r
- }\r
-\r
Status = gBS->LocateProtocol (&gEfiHiiDatabaseProtocolGuid, NULL, (VOID **) &mHiiDatabaseProt);\r
ASSERT_EFI_ERROR (Status);\r
\r
Status = gBS->LocateProtocol (&gEfiHiiStringProtocolGuid, NULL, (VOID **) &mHiiStringProt);\r
ASSERT_EFI_ERROR (Status);\r
\r
- mHiiProtocolsInitialized = TRUE;\r
+ return EFI_SUCCESS;\r
}\r
\r
\r
\r
+/**\r
+ This funciton build the package list based on the package number,\r
+ the GUID of the package list and the list of pointer which point to\r
+ package header that defined by UEFI VFR compiler and StringGather\r
+ tool.\r
+\r
+ #pragma pack (push, 1)\r
+ typedef struct {\r
+ UINT32 BinaryLength;\r
+ EFI_HII_PACKAGE_HEADER PackageHeader;\r
+ } EDKII_AUTOGEN_PACKAGES_HEADER;\r
+ #pragma pack (pop)\r
+\r
+ If there is not enough resource for the new package list,\r
+ the function will ASSERT.\r
+\r
+ @param NumberOfPackages The number of packages be \r
+ @param GuidId The GUID for the package list to be generated.\r
+ @param Marker The variable argument list. Each entry represent a specific package header that is\r
+ generated by VFR compiler and StrGather tool. The first 4 bytes is a UINT32 value\r
+ that indicate the overall length of the package.\r
+\r
+ @return The pointer to the package list header.\r
+\r
+**/\r
EFI_HII_PACKAGE_LIST_HEADER *\r
InternalHiiLibPreparePackages (\r
IN UINTN NumberOfPackages,\r
- IN CONST EFI_GUID *GuidId, OPTIONAL\r
- VA_LIST Marker\r
+ IN CONST EFI_GUID *GuidId,\r
+ IN VA_LIST Marker\r
)\r
{\r
EFI_HII_PACKAGE_LIST_HEADER *PackageListHeader;\r
PackageListLength = sizeof (EFI_HII_PACKAGE_LIST_HEADER);\r
\r
MarkerBackup = Marker;\r
- \r
+\r
+ //\r
+ // Count the lenth of the final package list.\r
+ //\r
for (Index = 0; Index < NumberOfPackages; Index++) {\r
CopyMem (&PackageLength, VA_ARG (Marker, VOID *), sizeof (UINT32));\r
+ //\r
+ // Do not count the BinaryLength field.\r
+ //\r
PackageListLength += (PackageLength - sizeof (UINT32));\r
}\r
\r
PackageListLength += sizeof (EFI_HII_PACKAGE_HEADER);\r
PackageListHeader = AllocateZeroPool (PackageListLength);\r
ASSERT (PackageListHeader != NULL);\r
- CopyMem (&PackageListHeader->PackageListGuid, GuidId, sizeof (EFI_GUID));\r
+ \r
+ CopyGuid (&PackageListHeader->PackageListGuid, GuidId);\r
PackageListHeader->PackageLength = PackageListLength;\r
\r
PackageListData = ((UINT8 *) PackageListHeader) + sizeof (EFI_HII_PACKAGE_LIST_HEADER);\r
\r
Marker = MarkerBackup;\r
+ //\r
+ // Prepare the final package list.\r
+ //\r
for (Index = 0; Index < NumberOfPackages; Index++) {\r
PackageArray = (UINT8 *) VA_ARG (Marker, VOID *);\r
+ //\r
+ // CopyMem is used for UINT32 to cover the unaligned address access.\r
+ //\r
CopyMem (&PackageLength, PackageArray, sizeof (UINT32));\r
PackageLength -= sizeof (UINT32);\r
PackageArray += sizeof (UINT32);\r
return PackageListHeader;\r
}\r
\r
+/**\r
+ Assemble EFI_HII_PACKAGE_LIST according to the passed in packages.\r
+\r
+ If GuidId is NULL, then ASSERT.\r
+ If not enough resource to complete the operation, then ASSERT.\r
+\r
+ @param NumberOfPackages Number of packages.\r
+ @param GuidId Package GUID.\r
+ @param ... Variable argument list for packages to be assembled.\r
+\r
+ @return Pointer of EFI_HII_PACKAGE_LIST_HEADER.\r
+\r
+**/\r
EFI_HII_PACKAGE_LIST_HEADER *\r
EFIAPI\r
HiiLibPreparePackageList (\r
}\r
\r
\r
+/**\r
+ This function allocates pool for an EFI_HII_PACKAGE_LIST structure\r
+ with additional space that is big enough to host all packages described by the variable \r
+ argument list of package pointers. The allocated structure is initialized using NumberOfPackages, \r
+ GuidId, and the variable length argument list of package pointers.\r
+\r
+ Then, EFI_HII_PACKAGE_LIST will be register to the default System HII Database. The\r
+ Handle to the newly registered Package List is returned throught HiiHandle.\r
+\r
+ If HiiHandle is NULL, then ASSERT.\r
+\r
+ @param NumberOfPackages The number of HII packages to register.\r
+ @param GuidId Package List GUID ID.\r
+ @param DriverHandle Optional. If not NULL, the DriverHandle on which an instance of DEVICE_PATH_PROTOCOL is installed.\r
+ This DriverHandle uniquely defines the device that the added packages are associated with.\r
+ @param HiiHandle On output, the HiiHandle is update with the handle which can be used to retrieve the Package \r
+ List later. If the functions failed to add the package to the default HII database, this value will\r
+ be set to NULL.\r
+ @param ... The variable argument list describing all HII Package.\r
+\r
+ @return EFI_SUCCESS If the packages are successfully added to the default HII database.\r
+ @return EFI_OUT_OF_RESOURCE Not enough resource to complete the operation.\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
HiiLibAddPackages (\r
IN UINTN NumberOfPackages,\r
IN CONST EFI_GUID *GuidId,\r
IN EFI_HANDLE DriverHandle, OPTIONAL\r
- OUT EFI_HII_HANDLE *HiiHandle, OPTIONAL\r
+ OUT EFI_HII_HANDLE *HiiHandle,\r
...\r
)\r
{\r
\r
ASSERT (HiiHandle != NULL);\r
\r
- LocateHiiProtocols ();\r
-\r
VA_START (Args, HiiHandle);\r
PackageListHeader = InternalHiiLibPreparePackages (NumberOfPackages, GuidId, Args);\r
\r
return Status;\r
}\r
\r
+/**\r
+ Removes a package list from the default HII database.\r
+\r
+ If HiiHandle is NULL, then ASSERT.\r
+ If HiiHandle is not a valid EFI_HII_HANDLE in the default HII database, then ASSERT.\r
+\r
+ @param HiiHandle The handle that was previously registered to the data base that is requested for removal.\r
+ List later.\r
+\r
+**/\r
VOID\r
EFIAPI\r
HiiLibRemovePackages (\r
)\r
{\r
EFI_STATUS Status;\r
- ASSERT (HiiHandle != NULL);\r
-\r
- LocateHiiProtocols ();\r
+ ASSERT (IsHiiHandleRegistered (HiiHandle));\r
\r
Status = mHiiDatabaseProt->RemovePackageList (mHiiDatabaseProt, HiiHandle);\r
ASSERT_EFI_ERROR (Status);\r
}\r
\r
\r
+/**\r
+ Determines the handles that are currently active in the database.\r
+ It's the caller's responsibility to free handle buffer.\r
+\r
+ If HandleBufferLength is NULL, then ASSERT.\r
+ If HiiHandleBuffer is NULL, then ASSERT.\r
+\r
+ @param HandleBufferLength On input, a pointer to the length of the handle\r
+ buffer. On output, the length of the handle buffer\r
+ that is required for the handles found.\r
+ @param HiiHandleBuffer Pointer to an array of Hii Handles returned.\r
+\r
+ @retval EFI_SUCCESS Get an array of Hii Handles successfully.\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
HiiLibGetHiiHandles (\r
\r
BufferLength = 0;\r
\r
- LocateHiiProtocols ();\r
-\r
//\r
// Try to find the actual buffer size for HiiHandle Buffer.\r
//\r
\r
if (Status == EFI_BUFFER_TOO_SMALL) {\r
*HiiHandleBuffer = AllocateZeroPool (BufferLength);\r
+ ASSERT (*HiiHandleBuffer != NULL);\r
Status = mHiiDatabaseProt->ListPackageLists (\r
mHiiDatabaseProt,\r
EFI_HII_PACKAGE_TYPE_ALL,\r
return Status;\r
}\r
\r
+/**\r
+ Extract Hii package list GUID for given HII handle.\r
+\r
+ If HiiHandle could not be found in the default HII database, then ASSERT.\r
+ If Guid is NULL, then ASSERT.\r
+\r
+ @param Handle Hii handle\r
+ @param Guid Package list GUID\r
+\r
+ @retval EFI_SUCCESS Successfully extract GUID from Hii database.\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
HiiLibExtractGuidFromHiiHandle (\r
EFI_HII_PACKAGE_LIST_HEADER *HiiPackageList;\r
\r
ASSERT (Guid != NULL);\r
+ ASSERT (IsHiiHandleRegistered (Handle));\r
\r
//\r
// Get HII PackageList\r
BufferSize = 0;\r
HiiPackageList = NULL;\r
\r
- LocateHiiProtocols ();\r
-\r
Status = mHiiDatabaseProt->ExportPackageLists (mHiiDatabaseProt, Handle, &BufferSize, HiiPackageList);\r
ASSERT (Status != EFI_NOT_FOUND);\r
\r
Status = mHiiDatabaseProt->ExportPackageLists (mHiiDatabaseProt, Handle, &BufferSize, HiiPackageList);\r
}\r
if (EFI_ERROR (Status)) {\r
+ FreePool (HiiPackageList);\r
return Status;\r
}\r
\r
//\r
// Extract GUID\r
//\r
- CopyMem (Guid, &HiiPackageList->PackageListGuid, sizeof (EFI_GUID));\r
+ CopyGuid (Guid, &HiiPackageList->PackageListGuid);\r
\r
- gBS->FreePool (HiiPackageList);\r
+ FreePool (HiiPackageList);\r
\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+ Find HII Handle in the default HII database associated with given Device Path.\r
+\r
+ If DevicePath is NULL, then ASSERT.\r
+\r
+ @param DevicePath Device Path associated with the HII package list\r
+ handle.\r
+\r
+ @retval Handle HII package list Handle associated with the Device\r
+ Path.\r
+ @retval NULL Hii Package list handle is not found.\r
+\r
+**/\r
EFI_HII_HANDLE\r
EFIAPI\r
HiiLibDevicePathToHiiHandle (\r
break;\r
}\r
}\r
- gBS->FreePool (Handles);\r
+ FreePool (Handles);\r
\r
if (DriverHandle == NULL) {\r
return NULL;\r
}\r
\r
- LocateHiiProtocols ();\r
-\r
//\r
// Retrieve all Hii Handles from HII database\r
//\r
HiiHandles\r
);\r
if (Status == EFI_BUFFER_TOO_SMALL) {\r
- gBS->FreePool (HiiHandles);\r
+ FreePool (HiiHandles);\r
HiiHandles = AllocatePool (BufferSize);\r
ASSERT (HiiHandles != NULL);\r
\r
}\r
\r
if (EFI_ERROR (Status)) {\r
- gBS->FreePool (HiiHandles);\r
+ FreePool (HiiHandles);\r
return NULL;\r
}\r
\r
}\r
}\r
\r
- gBS->FreePool (HiiHandles);\r
+ FreePool (HiiHandles);\r
return HiiHandle;\r
}\r
\r
+/**\r
+ Exports the contents of one or all package lists in the HII database into a buffer.\r
+\r
+ If Handle is not NULL and not a valid EFI_HII_HANDLE registered in the database, \r
+ then ASSERT.\r
+ If PackageListHeader is NULL, then ASSERT.\r
+ If PackageListSize is NULL, then ASSERT.\r
+\r
+ @param Handle The HII Handle.\r
+ @param PackageListHeader A pointer to a buffer that will contain the results of \r
+ the export function.\r
+ @param PackageListSize On output, the length of the buffer that is required for the exported data.\r
+\r
+ @retval EFI_SUCCESS Package exported.\r
+\r
+ @retval EFI_OUT_OF_RESOURCES Not enought memory to complete the operations.\r
+\r
+**/\r
+EFI_STATUS \r
+EFIAPI\r
+HiiLibExportPackageLists (\r
+ IN EFI_HII_HANDLE Handle,\r
+ OUT EFI_HII_PACKAGE_LIST_HEADER **PackageListHeader,\r
+ OUT UINTN *PackageListSize\r
+ )\r
+{\r
+ EFI_STATUS Status;\r
+ UINTN Size;\r
+ EFI_HII_PACKAGE_LIST_HEADER *PackageListHdr;\r
+\r
+ ASSERT (PackageListSize != NULL);\r
+ ASSERT (PackageListHeader != NULL);\r
+\r
+ if (Handle != NULL) {\r
+ ASSERT (IsHiiHandleRegistered (Handle));\r
+ }\r
+\r
+ Size = 0;\r
+ PackageListHdr = NULL;\r
+ Status = mHiiDatabaseProt->ExportPackageLists (\r
+ mHiiDatabaseProt,\r
+ Handle,\r
+ &Size,\r
+ PackageListHdr\r
+ );\r
+ ASSERT_EFI_ERROR (Status != EFI_BUFFER_TOO_SMALL);\r
+ \r
+ if (Status == EFI_BUFFER_TOO_SMALL) {\r
+ PackageListHdr = AllocateZeroPool (Size);\r
+ \r
+ if (PackageListHeader == NULL) {\r
+ return EFI_OUT_OF_RESOURCES;\r
+ } else {\r
+ Status = mHiiDatabaseProt->ExportPackageLists (\r
+ mHiiDatabaseProt,\r
+ Handle,\r
+ &Size,\r
+ PackageListHdr\r
+ );\r
+ }\r
+ }\r
+\r
+ if (!EFI_ERROR (Status)) {\r
+ *PackageListHeader = PackageListHdr;\r
+ *PackageListSize = Size;\r
+ } else {\r
+ FreePool (PackageListHdr);\r
+ }\r
+\r
+ return Status;\r
+}\r
+\r
+/**\r
+ \r
+ This function returns a list of the package handles of the \r
+ specified type that are currently active in the HII database. The \r
+ pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package \r
+ handles to be listed.\r
+\r
+ If HandleBufferLength is NULL, then ASSERT.\r
+ If HandleBuffer is NULL, the ASSERT.\r
+ If PackageType is EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is\r
+ NULL, then ASSERT.\r
+ If PackageType is not EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is not\r
+ NULL, then ASSERT.\r
+ \r
+ \r
+ @param PackageType Specifies the package type of the packages\r
+ to list or EFI_HII_PACKAGE_TYPE_ALL for\r
+ all packages to be listed.\r
+ \r
+ @param PackageGuid If PackageType is\r
+ EFI_HII_PACKAGE_TYPE_GUID, then this is\r
+ the pointer to the GUID which must match\r
+ the Guid field of\r
+ EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it\r
+ must be NULL.\r
+ \r
+ @param HandleBufferLength On output, the length of the handle buffer\r
+ that is required for the handles found.\r
+\r
+ @param HandleBuffer On output, an array of EFI_HII_HANDLE instances returned.\r
+ The caller is responcible to free this pointer allocated.\r
+\r
+ @retval EFI_SUCCESS The matching handles are outputed successfully.\r
+ HandleBufferLength is updated with the actual length.\r
+ @retval EFI_OUT_OF_RESOURCES Not enough resource to complete the operation.\r
+ @retval EFI_NOT_FOUND No matching handle could not be found in database.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+HiiLibListPackageLists (\r
+ IN UINT8 PackageType,\r
+ IN CONST EFI_GUID *PackageGuid,\r
+ OUT UINTN *HandleBufferLength,\r
+ OUT EFI_HII_HANDLE **HandleBuffer\r
+ )\r
+{\r
+ EFI_STATUS Status;\r
+ \r
+ ASSERT (HandleBufferLength != NULL);\r
+ ASSERT (HandleBuffer != NULL);\r
+ \r
+ *HandleBufferLength = 0;\r
+ *HandleBuffer = NULL;\r
+\r
+ if (PackageType == EFI_HII_PACKAGE_TYPE_GUID) {\r
+ ASSERT (PackageGuid != NULL);\r
+ } else {\r
+ ASSERT (PackageGuid == NULL);\r
+ }\r
+\r
+ Status = mHiiDatabaseProt->ListPackageLists (\r
+ mHiiDatabaseProt,\r
+ PackageType,\r
+ PackageGuid,\r
+ HandleBufferLength,\r
+ *HandleBuffer\r
+ );\r
+ if (EFI_ERROR (Status) && (Status != EFI_BUFFER_TOO_SMALL)) {\r
+ //\r
+ // No packages is registered to UEFI HII Database, just return.\r
+ // \r
+ //\r
+ return Status;\r
+ }\r
+\r
+ *HandleBuffer = AllocateZeroPool (*HandleBufferLength);\r
+ \r
+ if (*HandleBuffer == NULL) {\r
+ return EFI_OUT_OF_RESOURCES;\r
+ }\r
+ \r
+ return mHiiDatabaseProt->ListPackageLists (\r
+ mHiiDatabaseProt,\r
+ PackageType,\r
+ PackageGuid,\r
+ HandleBufferLength,\r
+ *HandleBuffer\r
+ );\r
+ \r
+}\r
+/**\r
+ This function check if the Hii Handle is a valid handle registered\r
+ in the HII database.\r
+\r
+ @param HiiHandle The HII Handle.\r
+\r
+ @retval TRUE If it is a valid HII handle.\r
+ @retval FALSE If it is a invalid HII handle.\r
+**/\r
BOOLEAN\r
IsHiiHandleRegistered (\r
EFI_HII_HANDLE HiiHandle\r
HiiPackageList = NULL;\r
BufferSize = 0;\r
\r
- LocateHiiProtocols ();\r
-\r
Status = mHiiDatabaseProt->ExportPackageLists (\r
mHiiDatabaseProt,\r
HiiHandle,\r
projects / mirror_edk2.git / blobdiff