2 HII Library implementation that uses DXE protocols and services.
4 Copyright (c) 2006 - 2008, Intel Corporation<BR>
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 #include "InternalHiiLib.h"
17 CONST EFI_HII_DATABASE_PROTOCOL
*mHiiDatabaseProt
= NULL
;
18 CONST EFI_HII_STRING_PROTOCOL
*mHiiStringProt
= NULL
;
21 This function locate Hii relative protocols for later usage.
23 The constructor function caches the protocol pointer of HII Database Protocol
24 and Hii String Protocol.
26 It will ASSERT() if either of the protocol can't be located.
28 @param ImageHandle The firmware allocated handle for the EFI image.
29 @param SystemTable A pointer to the EFI System Table.
31 @retval EFI_SUCCESS The constructor always returns EFI_SUCCESS.
37 IN EFI_HANDLE ImageHandle
,
38 IN EFI_SYSTEM_TABLE
*SystemTable
43 Status
= gBS
->LocateProtocol (&gEfiHiiDatabaseProtocolGuid
, NULL
, (VOID
**) &mHiiDatabaseProt
);
44 ASSERT_EFI_ERROR (Status
);
46 Status
= gBS
->LocateProtocol (&gEfiHiiStringProtocolGuid
, NULL
, (VOID
**) &mHiiStringProt
);
47 ASSERT_EFI_ERROR (Status
);
55 This funciton build the package list based on the package number,
56 the GUID of the package list and the list of pointer which point to
57 package header that defined by UEFI VFR compiler and StringGather
60 #pragma pack (push, 1)
63 EFI_HII_PACKAGE_HEADER PackageHeader;
64 } EDKII_AUTOGEN_PACKAGES_HEADER;
67 If there is not enough resource for the new package list,
68 the function will ASSERT.
70 @param NumberOfPackages The number of packages be
71 @param GuidId The GUID for the package list to be generated.
72 @param Marker The variable argument list. Each entry represent a specific package header that is
73 generated by VFR compiler and StrGather tool. The first 4 bytes is a UINT32 value
74 that indicate the overall length of the package.
76 @return The pointer to the package list header.
79 EFI_HII_PACKAGE_LIST_HEADER
*
80 InternalHiiLibPreparePackages (
81 IN UINTN NumberOfPackages
,
82 IN CONST EFI_GUID
*GuidId
,
86 EFI_HII_PACKAGE_LIST_HEADER
*PackageListHeader
;
87 UINT8
*PackageListData
;
88 UINT32 PackageListLength
;
90 EFI_HII_PACKAGE_HEADER PackageHeader
;
95 PackageListLength
= sizeof (EFI_HII_PACKAGE_LIST_HEADER
);
97 MarkerBackup
= Marker
;
100 // Count the lenth of the final package list.
102 for (Index
= 0; Index
< NumberOfPackages
; Index
++) {
103 CopyMem (&PackageLength
, VA_ARG (Marker
, VOID
*), sizeof (UINT32
));
105 // Do not count the BinaryLength field.
107 PackageListLength
+= (PackageLength
- sizeof (UINT32
));
111 // Include the lenght of EFI_HII_PACKAGE_END
113 PackageListLength
+= sizeof (EFI_HII_PACKAGE_HEADER
);
114 PackageListHeader
= AllocateZeroPool (PackageListLength
);
115 ASSERT (PackageListHeader
!= NULL
);
117 CopyGuid (&PackageListHeader
->PackageListGuid
, GuidId
);
118 PackageListHeader
->PackageLength
= PackageListLength
;
120 PackageListData
= ((UINT8
*) PackageListHeader
) + sizeof (EFI_HII_PACKAGE_LIST_HEADER
);
122 Marker
= MarkerBackup
;
124 // Prepare the final package list.
126 for (Index
= 0; Index
< NumberOfPackages
; Index
++) {
127 PackageArray
= (UINT8
*) VA_ARG (Marker
, VOID
*);
129 // CopyMem is used for UINT32 to cover the unaligned address access.
131 CopyMem (&PackageLength
, PackageArray
, sizeof (UINT32
));
132 PackageLength
-= sizeof (UINT32
);
133 PackageArray
+= sizeof (UINT32
);
134 CopyMem (PackageListData
, PackageArray
, PackageLength
);
135 PackageListData
+= PackageLength
;
139 // Append EFI_HII_PACKAGE_END
141 PackageHeader
.Type
= EFI_HII_PACKAGE_END
;
142 PackageHeader
.Length
= sizeof (EFI_HII_PACKAGE_HEADER
);
143 CopyMem (PackageListData
, &PackageHeader
, PackageHeader
.Length
);
145 return PackageListHeader
;
149 Assemble EFI_HII_PACKAGE_LIST according to the passed in packages.
151 If GuidId is NULL, then ASSERT.
152 If not enough resource to complete the operation, then ASSERT.
154 @param NumberOfPackages Number of packages.
155 @param GuidId Package GUID.
156 @param ... Variable argument list for packages to be assembled.
158 @return Pointer of EFI_HII_PACKAGE_LIST_HEADER.
161 EFI_HII_PACKAGE_LIST_HEADER
*
163 HiiLibPreparePackageList (
164 IN UINTN NumberOfPackages
,
165 IN CONST EFI_GUID
*GuidId
,
169 EFI_HII_PACKAGE_LIST_HEADER
*PackageListHeader
;
172 ASSERT (GuidId
!= NULL
);
174 VA_START (Marker
, GuidId
);
175 PackageListHeader
= InternalHiiLibPreparePackages (NumberOfPackages
, GuidId
, Marker
);
178 return PackageListHeader
;
183 This function allocates pool for an EFI_HII_PACKAGE_LIST structure
184 with additional space that is big enough to host all packages described by the variable
185 argument list of package pointers. The allocated structure is initialized using NumberOfPackages,
186 GuidId, and the variable length argument list of package pointers.
188 Then, EFI_HII_PACKAGE_LIST will be register to the default System HII Database. The
189 Handle to the newly registered Package List is returned throught HiiHandle.
191 If HiiHandle is NULL, then ASSERT.
193 @param NumberOfPackages The number of HII packages to register.
194 @param GuidId Package List GUID ID.
195 @param DriverHandle Optional. If not NULL, the DriverHandle on which an instance of DEVICE_PATH_PROTOCOL is installed.
196 This DriverHandle uniquely defines the device that the added packages are associated with.
197 @param HiiHandle On output, the HiiHandle is update with the handle which can be used to retrieve the Package
198 List later. If the functions failed to add the package to the default HII database, this value will
200 @param ... The variable argument list describing all HII Package.
202 @return EFI_SUCCESS If the packages are successfully added to the default HII database.
203 @return EFI_OUT_OF_RESOURCE Not enough resource to complete the operation.
209 IN UINTN NumberOfPackages
,
210 IN CONST EFI_GUID
*GuidId
,
211 IN EFI_HANDLE DriverHandle
, OPTIONAL
212 OUT EFI_HII_HANDLE
*HiiHandle
,
217 EFI_HII_PACKAGE_LIST_HEADER
*PackageListHeader
;
220 ASSERT (HiiHandle
!= NULL
);
222 VA_START (Args
, HiiHandle
);
223 PackageListHeader
= InternalHiiLibPreparePackages (NumberOfPackages
, GuidId
, Args
);
225 Status
= mHiiDatabaseProt
->NewPackageList (mHiiDatabaseProt
, PackageListHeader
, DriverHandle
, HiiHandle
);
226 if (HiiHandle
!= NULL
) {
227 if (EFI_ERROR (Status
)) {
232 FreePool (PackageListHeader
);
239 Removes a package list from the default HII database.
241 If HiiHandle is NULL, then ASSERT.
242 If HiiHandle is not a valid EFI_HII_HANDLE in the default HII database, then ASSERT.
244 @param HiiHandle The handle that was previously registered to the data base that is requested for removal.
250 HiiLibRemovePackages (
251 IN EFI_HII_HANDLE HiiHandle
255 ASSERT (IsHiiHandleRegistered (HiiHandle
));
257 Status
= mHiiDatabaseProt
->RemovePackageList (mHiiDatabaseProt
, HiiHandle
);
258 ASSERT_EFI_ERROR (Status
);
263 Determines the handles that are currently active in the database.
264 It's the caller's responsibility to free handle buffer.
266 If HandleBufferLength is NULL, then ASSERT.
267 If HiiHandleBuffer is NULL, then ASSERT.
269 @param HandleBufferLength On input, a pointer to the length of the handle
270 buffer. On output, the length of the handle buffer
271 that is required for the handles found.
272 @param HiiHandleBuffer Pointer to an array of Hii Handles returned.
274 @retval EFI_SUCCESS Get an array of Hii Handles successfully.
279 HiiLibGetHiiHandles (
280 IN OUT UINTN
*HandleBufferLength
,
281 OUT EFI_HII_HANDLE
**HiiHandleBuffer
287 ASSERT (HandleBufferLength
!= NULL
);
288 ASSERT (HiiHandleBuffer
!= NULL
);
293 // Try to find the actual buffer size for HiiHandle Buffer.
295 Status
= mHiiDatabaseProt
->ListPackageLists (
297 EFI_HII_PACKAGE_TYPE_ALL
,
303 if (Status
== EFI_BUFFER_TOO_SMALL
) {
304 *HiiHandleBuffer
= AllocateZeroPool (BufferLength
);
305 ASSERT (*HiiHandleBuffer
!= NULL
);
306 Status
= mHiiDatabaseProt
->ListPackageLists (
308 EFI_HII_PACKAGE_TYPE_ALL
,
314 // we should not fail here.
316 ASSERT_EFI_ERROR (Status
);
319 *HandleBufferLength
= BufferLength
;
325 Extract Hii package list GUID for given HII handle.
327 If HiiHandle could not be found in the default HII database, then ASSERT.
328 If Guid is NULL, then ASSERT.
330 @param Handle Hii handle
331 @param Guid Package list GUID
333 @retval EFI_SUCCESS Successfully extract GUID from Hii database.
338 HiiLibExtractGuidFromHiiHandle (
339 IN EFI_HII_HANDLE Handle
,
345 EFI_HII_PACKAGE_LIST_HEADER
*HiiPackageList
;
347 ASSERT (Guid
!= NULL
);
348 ASSERT (IsHiiHandleRegistered (Handle
));
351 // Get HII PackageList
354 HiiPackageList
= NULL
;
356 Status
= mHiiDatabaseProt
->ExportPackageLists (mHiiDatabaseProt
, Handle
, &BufferSize
, HiiPackageList
);
357 ASSERT (Status
!= EFI_NOT_FOUND
);
359 if (Status
== EFI_BUFFER_TOO_SMALL
) {
360 HiiPackageList
= AllocatePool (BufferSize
);
361 ASSERT (HiiPackageList
!= NULL
);
363 Status
= mHiiDatabaseProt
->ExportPackageLists (mHiiDatabaseProt
, Handle
, &BufferSize
, HiiPackageList
);
365 if (EFI_ERROR (Status
)) {
366 FreePool (HiiPackageList
);
373 CopyGuid (Guid
, &HiiPackageList
->PackageListGuid
);
375 FreePool (HiiPackageList
);
381 Find HII Handle in the default HII database associated with given Device Path.
383 If DevicePath is NULL, then ASSERT.
385 @param DevicePath Device Path associated with the HII package list
388 @retval Handle HII package list Handle associated with the Device
390 @retval NULL Hii Package list handle is not found.
395 HiiLibDevicePathToHiiHandle (
396 IN EFI_DEVICE_PATH_PROTOCOL
*DevicePath
400 EFI_DEVICE_PATH_PROTOCOL
*TmpDevicePath
;
407 EFI_HANDLE DriverHandle
;
408 EFI_HII_HANDLE
*HiiHandles
;
409 EFI_HII_HANDLE HiiHandle
;
411 ASSERT (DevicePath
!= NULL
);
414 // Locate Device Path Protocol handle buffer
416 Status
= gBS
->LocateHandleBuffer (
418 &gEfiDevicePathProtocolGuid
,
423 if (EFI_ERROR (Status
)) {
428 // Search Driver Handle by Device Path
431 BufferSize
= GetDevicePathSize (DevicePath
);
432 for(Index
= 0; Index
< HandleCount
; Index
++) {
433 Handle
= Handles
[Index
];
434 gBS
->HandleProtocol (Handle
, &gEfiDevicePathProtocolGuid
, (VOID
**) &TmpDevicePath
);
437 // Check whether DevicePath match
439 Size
= GetDevicePathSize (TmpDevicePath
);
440 if ((Size
== BufferSize
) && CompareMem (DevicePath
, TmpDevicePath
, Size
) == 0) {
441 DriverHandle
= Handle
;
447 if (DriverHandle
== NULL
) {
452 // Retrieve all Hii Handles from HII database
455 HiiHandles
= AllocatePool (BufferSize
);
456 ASSERT (HiiHandles
!= NULL
);
457 Status
= mHiiDatabaseProt
->ListPackageLists (
459 EFI_HII_PACKAGE_TYPE_ALL
,
464 if (Status
== EFI_BUFFER_TOO_SMALL
) {
465 FreePool (HiiHandles
);
466 HiiHandles
= AllocatePool (BufferSize
);
467 ASSERT (HiiHandles
!= NULL
);
469 Status
= mHiiDatabaseProt
->ListPackageLists (
471 EFI_HII_PACKAGE_TYPE_ALL
,
478 if (EFI_ERROR (Status
)) {
479 FreePool (HiiHandles
);
484 // Search Hii Handle by Driver Handle
487 HandleCount
= BufferSize
/ sizeof (EFI_HII_HANDLE
);
488 for (Index
= 0; Index
< HandleCount
; Index
++) {
489 Status
= mHiiDatabaseProt
->GetPackageListHandle (
494 if (!EFI_ERROR (Status
) && (Handle
== DriverHandle
)) {
495 HiiHandle
= HiiHandles
[Index
];
500 FreePool (HiiHandles
);
505 Exports the contents of one or all package lists in the HII database into a buffer.
507 If Handle is not NULL and not a valid EFI_HII_HANDLE registered in the database,
509 If PackageListHeader is NULL, then ASSERT.
510 If PackageListSize is NULL, then ASSERT.
512 @param Handle The HII Handle.
513 @param PackageListHeader A pointer to a buffer that will contain the results of
515 @param PackageListSize On output, the length of the buffer that is required for the exported data.
517 @retval EFI_SUCCESS Package exported.
519 @retval EFI_OUT_OF_RESOURCES Not enought memory to complete the operations.
524 HiiLibExportPackageLists (
525 IN EFI_HII_HANDLE Handle
,
526 OUT EFI_HII_PACKAGE_LIST_HEADER
**PackageListHeader
,
527 OUT UINTN
*PackageListSize
532 EFI_HII_PACKAGE_LIST_HEADER
*PackageListHdr
;
534 ASSERT (PackageListSize
!= NULL
);
535 ASSERT (PackageListHeader
!= NULL
);
537 if (Handle
!= NULL
) {
538 ASSERT (IsHiiHandleRegistered (Handle
));
542 PackageListHdr
= NULL
;
543 Status
= mHiiDatabaseProt
->ExportPackageLists (
549 ASSERT_EFI_ERROR (Status
!= EFI_BUFFER_TOO_SMALL
);
551 if (Status
== EFI_BUFFER_TOO_SMALL
) {
552 PackageListHdr
= AllocateZeroPool (Size
);
554 if (PackageListHeader
== NULL
) {
555 return EFI_OUT_OF_RESOURCES
;
557 Status
= mHiiDatabaseProt
->ExportPackageLists (
566 if (!EFI_ERROR (Status
)) {
567 *PackageListHeader
= PackageListHdr
;
568 *PackageListSize
= Size
;
570 FreePool (PackageListHdr
);
578 This function returns a list of the package handles of the
579 specified type that are currently active in the HII database. The
580 pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package
581 handles to be listed.
583 If HandleBufferLength is NULL, then ASSERT.
584 If HandleBuffer is NULL, the ASSERT.
585 If PackageType is EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is
587 If PackageType is not EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is not
591 @param PackageType Specifies the package type of the packages
592 to list or EFI_HII_PACKAGE_TYPE_ALL for
593 all packages to be listed.
595 @param PackageGuid If PackageType is
596 EFI_HII_PACKAGE_TYPE_GUID, then this is
597 the pointer to the GUID which must match
599 EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
602 @param HandleBufferLength On output, the length of the handle buffer
603 that is required for the handles found.
605 @param HandleBuffer On output, an array of EFI_HII_HANDLE instances returned.
606 The caller is responcible to free this pointer allocated.
608 @retval EFI_SUCCESS The matching handles are outputed successfully.
609 HandleBufferLength is updated with the actual length.
610 @retval EFI_OUT_OF_RESOURCES Not enough resource to complete the operation.
611 @retval EFI_NOT_FOUND No matching handle could not be found in database.
615 HiiLibListPackageLists (
616 IN UINT8 PackageType
,
617 IN CONST EFI_GUID
*PackageGuid
,
618 IN OUT UINTN
*HandleBufferLength
,
619 OUT EFI_HII_HANDLE
**HandleBuffer
624 ASSERT (HandleBufferLength
!= NULL
);
625 ASSERT (HandleBuffer
!= NULL
);
627 *HandleBufferLength
= 0;
628 *HandleBuffer
= NULL
;
630 if (PackageType
== EFI_HII_PACKAGE_TYPE_GUID
) {
631 ASSERT (PackageGuid
!= NULL
);
633 ASSERT (PackageGuid
== NULL
);
636 Status
= mHiiDatabaseProt
->ListPackageLists (
643 if (EFI_ERROR (Status
) && (Status
!= EFI_BUFFER_TOO_SMALL
)) {
645 // No packages is registered to UEFI HII Database, just return.
651 *HandleBuffer
= AllocateZeroPool (*HandleBufferLength
);
653 if (*HandleBuffer
== NULL
) {
654 return EFI_OUT_OF_RESOURCES
;
657 return mHiiDatabaseProt
->ListPackageLists (
667 This function check if the Hii Handle is a valid handle registered
670 @param HiiHandle The HII Handle.
672 @retval TRUE If it is a valid HII handle.
673 @retval FALSE If it is a invalid HII handle.
676 IsHiiHandleRegistered (
677 EFI_HII_HANDLE HiiHandle
682 EFI_HII_PACKAGE_LIST_HEADER
*HiiPackageList
;
684 ASSERT (HiiHandle
!= NULL
);
686 HiiPackageList
= NULL
;
689 Status
= mHiiDatabaseProt
->ExportPackageLists (
696 return (BOOLEAN
) (Status
== EFI_BUFFER_TOO_SMALL
);