X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=MdePkg%2FLibrary%2FHiiLib%2FHiiLib.c;h=be3a31704d2f61799a16444bb0818d00c48fe2fd;hb=1db1f6adb4591671c044dc18d82f89845c60ecfa;hp=a1797c930f7d9f863fed9ee08e53fbde81494dcc;hpb=c67896b19fadf74d5ed0d779e7571e4ea71aef84;p=mirror_edk2.git diff --git a/MdePkg/Library/HiiLib/HiiLib.c b/MdePkg/Library/HiiLib/HiiLib.c index a1797c930f..be3a31704d 100644 --- a/MdePkg/Library/HiiLib/HiiLib.c +++ b/MdePkg/Library/HiiLib/HiiLib.c @@ -14,55 +14,71 @@ #include "InternalHiiLib.h" -EFI_HII_DATABASE_PROTOCOL *mHiiDatabaseProt; -EFI_HII_STRING_PROTOCOL *mHiiStringProt; +CONST EFI_HII_DATABASE_PROTOCOL *mHiiDatabaseProt; +CONST EFI_HII_STRING_PROTOCOL *mHiiStringProt; +BOOLEAN mHiiProtocolsInitialized = FALSE; + /** - The constructor function of Hii Library. - - The constructor function caches the value of default HII protocol instances. - @param ImageHandle The firmware allocated handle for the EFI image. - @param SystemTable A pointer to the EFI System Table. - - @retval EFI_SUCCESS The constructor always returns EFI_SUCCESS. + This function locate Hii relative protocols for later usage. **/ -EFI_STATUS -EFIAPI -UefiHiiLibConstructor ( - IN EFI_HANDLE ImageHandle, - IN EFI_SYSTEM_TABLE *SystemTable +VOID +LocateHiiProtocols ( + VOID ) { - EFI_STATUS Status; - - Status = gBS->LocateProtocol ( - &gEfiHiiDatabaseProtocolGuid, - NULL, - (VOID **) &mHiiDatabaseProt - ); + EFI_STATUS Status; + + if (mHiiProtocolsInitialized) { + // + // Only need to initialize the protocol instance once. + // + return; + } + + Status = gBS->LocateProtocol (&gEfiHiiDatabaseProtocolGuid, NULL, (VOID **) &mHiiDatabaseProt); ASSERT_EFI_ERROR (Status); - ASSERT (mHiiDatabaseProt != NULL); - Status = gBS->LocateProtocol ( - &gEfiHiiStringProtocolGuid, - NULL, - (VOID **) &mHiiStringProt - ); + Status = gBS->LocateProtocol (&gEfiHiiStringProtocolGuid, NULL, (VOID **) &mHiiStringProt); ASSERT_EFI_ERROR (Status); - ASSERT (mHiiStringProt != NULL); - return EFI_SUCCESS; + mHiiProtocolsInitialized = TRUE; } +/** + This funciton build the package list based on the package number, + the GUID of the package list and the list of pointer which point to + package header that defined by UEFI VFR compiler and StringGather + tool. + + #pragma pack (push, 1) + typedef struct { + UINT32 BinaryLength; + EFI_HII_PACKAGE_HEADER PackageHeader; + } TIANO_AUTOGEN_PACKAGES_HEADER; + #pragma pack (pop) + + If there is not enough resource for the new package list, + the function will ASSERT. + + @param NumberOfPackages The number of packages be + @param GuidId The GUID for the package list to be generated. + @param Marker The variable argument list. Each entry represent a specific package header that is + generated by VFR compiler and StrGather tool. The first 4 bytes is a UINT32 value + that indicate the overall length of the package. + + @return The pointer to the package list header. + +**/ EFI_HII_PACKAGE_LIST_HEADER * InternalHiiLibPreparePackages ( IN UINTN NumberOfPackages, - IN CONST EFI_GUID *GuidId, OPTIONAL - VA_LIST Marker + IN CONST EFI_GUID *GuidId, + IN VA_LIST Marker ) { EFI_HII_PACKAGE_LIST_HEADER *PackageListHeader; @@ -80,6 +96,9 @@ InternalHiiLibPreparePackages ( for (Index = 0; Index < NumberOfPackages; Index++) { CopyMem (&PackageLength, VA_ARG (Marker, VOID *), sizeof (UINT32)); + // + // Do not count the BinaryLength field. + // PackageListLength += (PackageLength - sizeof (UINT32)); } @@ -89,6 +108,7 @@ InternalHiiLibPreparePackages ( PackageListLength += sizeof (EFI_HII_PACKAGE_HEADER); PackageListHeader = AllocateZeroPool (PackageListLength); ASSERT (PackageListHeader != NULL); + CopyMem (&PackageListHeader->PackageListGuid, GuidId, sizeof (EFI_GUID)); PackageListHeader->PackageLength = PackageListLength; @@ -114,6 +134,20 @@ InternalHiiLibPreparePackages ( return PackageListHeader; } +/** + Assemble EFI_HII_PACKAGE_LIST according to the passed in packages. + + If GuidId is NULL, then ASSERT. + If not enough resource to complete the operation, then ASSERT. + + @param NumberOfPackages Number of packages. + @param GuidId Package GUID. + @param ... Variable argument list for packages to be assembled. + + @return EFI_HII_PACKAGE_LIST_HEADER Pointer of EFI_HII_PACKAGE_LIST_HEADER. The function will ASSERT if system has + not enough resource to complete the operation. + +**/ EFI_HII_PACKAGE_LIST_HEADER * EFIAPI HiiLibPreparePackageList ( @@ -135,13 +169,37 @@ HiiLibPreparePackageList ( } +/** + This function allocates pool for an EFI_HII_PACKAGE_LIST structure + with additional space that is big enough to host all packages described by the variable + argument list of package pointers. The allocated structure is initialized using NumberOfPackages, + GuidId, and the variable length argument list of package pointers. + + Then, EFI_HII_PACKAGE_LIST will be register to the default System HII Database. The + Handle to the newly registered Package List is returned throught HiiHandle. + + If HiiHandle is NULL, then ASSERT. + + @param NumberOfPackages The number of HII packages to register. + @param GuidId Package List GUID ID. + @param DriverHandle Optional. If not NULL, the DriverHandle on which an instance of DEVICE_PATH_PROTOCOL is installed. + This DriverHandle uniquely defines the device that the added packages are associated with. + @param HiiHandle On output, the HiiHandle is update with the handle which can be used to retrieve the Package + List later. If the functions failed to add the package to the default HII database, this value will + be set to NULL. + @param ... The variable argument list describing all HII Package. + + @return EFI_SUCCESS If the packages are successfully added to the default HII database. + @return EFI_OUT_OF_RESOURCE Not enough resource to complete the operation. + +**/ EFI_STATUS EFIAPI HiiLibAddPackages ( IN UINTN NumberOfPackages, IN CONST EFI_GUID *GuidId, IN EFI_HANDLE DriverHandle, OPTIONAL - OUT EFI_HII_HANDLE *HiiHandle, OPTIONAL + OUT EFI_HII_HANDLE *HiiHandle, ... ) { @@ -151,6 +209,8 @@ HiiLibAddPackages ( ASSERT (HiiHandle != NULL); + LocateHiiProtocols (); + VA_START (Args, HiiHandle); PackageListHeader = InternalHiiLibPreparePackages (NumberOfPackages, GuidId, Args); @@ -167,6 +227,16 @@ HiiLibAddPackages ( return Status; } +/** + Removes a package list from the default HII database. + + If HiiHandle is NULL, then ASSERT. + If HiiHandle is not a valid EFI_HII_HANDLE in the default HII database, then ASSERT. + + @param HiiHandle The handle that was previously registered to the data base that is requested for removal. + List later. + +**/ VOID EFIAPI HiiLibRemovePackages ( @@ -174,13 +244,30 @@ HiiLibRemovePackages ( ) { EFI_STATUS Status; + ASSERT (IsHiiHandleRegistered (HiiHandle)); + + LocateHiiProtocols (); - ASSERT (HiiHandle != NULL); Status = mHiiDatabaseProt->RemovePackageList (mHiiDatabaseProt, HiiHandle); ASSERT_EFI_ERROR (Status); } +/** + Determines the handles that are currently active in the database. + It's the caller's responsibility to free handle buffer. + + If HandleBufferLength is NULL, then ASSERT. + If HiiHandleBuffer is NULL, then ASSERT. + + @param HandleBufferLength On input, a pointer to the length of the handle + buffer. On output, the length of the handle buffer + that is required for the handles found. + @param HiiHandleBuffer Pointer to an array of Hii Handles returned. + + @retval EFI_SUCCESS Get an array of Hii Handles successfully. + +**/ EFI_STATUS EFIAPI HiiLibGetHiiHandles ( @@ -196,6 +283,8 @@ HiiLibGetHiiHandles ( BufferLength = 0; + LocateHiiProtocols (); + // // Try to find the actual buffer size for HiiHandle Buffer. // @@ -227,6 +316,18 @@ HiiLibGetHiiHandles ( return Status; } +/** + Extract Hii package list GUID for given HII handle. + + If HiiHandle could not be found in the default HII database, then ASSERT. + If Guid is NULL, then ASSERT. + + @param Handle Hii handle + @param Guid Package list GUID + + @retval EFI_SUCCESS Successfully extract GUID from Hii database. + +**/ EFI_STATUS EFIAPI HiiLibExtractGuidFromHiiHandle ( @@ -239,12 +340,16 @@ HiiLibExtractGuidFromHiiHandle ( EFI_HII_PACKAGE_LIST_HEADER *HiiPackageList; ASSERT (Guid != NULL); + ASSERT (IsHiiHandleRegistered (Handle)); // // Get HII PackageList // BufferSize = 0; HiiPackageList = NULL; + + LocateHiiProtocols (); + Status = mHiiDatabaseProt->ExportPackageLists (mHiiDatabaseProt, Handle, &BufferSize, HiiPackageList); ASSERT (Status != EFI_NOT_FOUND); @@ -263,11 +368,24 @@ HiiLibExtractGuidFromHiiHandle ( // CopyMem (Guid, &HiiPackageList->PackageListGuid, sizeof (EFI_GUID)); - gBS->FreePool (HiiPackageList); + FreePool (HiiPackageList); return EFI_SUCCESS; } +/** + Find HII Handle in the default HII database associated with given Device Path. + + If DevicePath is NULL, then ASSERT. + + @param DevicePath Device Path associated with the HII package list + handle. + + @retval Handle HII package list Handle associated with the Device + Path. + @retval NULL Hii Package list handle is not found. + +**/ EFI_HII_HANDLE EFIAPI HiiLibDevicePathToHiiHandle ( @@ -320,12 +438,14 @@ HiiLibDevicePathToHiiHandle ( break; } } - gBS->FreePool (Handles); + FreePool (Handles); if (DriverHandle == NULL) { return NULL; } + LocateHiiProtocols (); + // // Retrieve all Hii Handles from HII database // @@ -340,7 +460,7 @@ HiiLibDevicePathToHiiHandle ( HiiHandles ); if (Status == EFI_BUFFER_TOO_SMALL) { - gBS->FreePool (HiiHandles); + FreePool (HiiHandles); HiiHandles = AllocatePool (BufferSize); ASSERT (HiiHandles != NULL); @@ -354,7 +474,7 @@ HiiLibDevicePathToHiiHandle ( } if (EFI_ERROR (Status)) { - gBS->FreePool (HiiHandles); + FreePool (HiiHandles); return NULL; } @@ -375,10 +495,19 @@ HiiLibDevicePathToHiiHandle ( } } - gBS->FreePool (HiiHandles); + FreePool (HiiHandles); return HiiHandle; } +/** + This function check if the Hii Handle is a valid handle registered + in the HII database. + + @param HiiHandle The HII Handle. + + @retval TRUE If it is a valid HII handle. + @retval FALSE If it is a invalid HII handle. +**/ BOOLEAN IsHiiHandleRegistered ( EFI_HII_HANDLE HiiHandle @@ -392,6 +521,9 @@ IsHiiHandleRegistered ( HiiPackageList = NULL; BufferSize = 0; + + LocateHiiProtocols (); + Status = mHiiDatabaseProt->ExportPackageLists ( mHiiDatabaseProt, HiiHandle,