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 length 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 length 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 through 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
286 ASSERT (HandleBufferLength
!= NULL
);
287 ASSERT (HiiHandleBuffer
!= NULL
);
289 *HandleBufferLength
= 0;
290 *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 (*HandleBufferLength
);
305 ASSERT (*HiiHandleBuffer
!= NULL
);
306 Status
= mHiiDatabaseProt
->ListPackageLists (
308 EFI_HII_PACKAGE_TYPE_ALL
,
314 if (EFI_ERROR (Status
)) {
315 FreePool (*HiiHandleBuffer
);
316 *HiiHandleBuffer
= NULL
;
324 Extract Hii package list GUID for given HII handle.
326 If HiiHandle could not be found in the default HII database, then ASSERT.
327 If Guid is NULL, then ASSERT.
329 @param Handle Hii handle
330 @param Guid Package list GUID
332 @retval EFI_SUCCESS Successfully extract GUID from Hii database.
337 HiiLibExtractGuidFromHiiHandle (
338 IN EFI_HII_HANDLE Handle
,
344 EFI_HII_PACKAGE_LIST_HEADER
*HiiPackageList
;
346 ASSERT (Guid
!= NULL
);
347 ASSERT (IsHiiHandleRegistered (Handle
));
350 // Get HII PackageList
353 HiiPackageList
= NULL
;
355 Status
= mHiiDatabaseProt
->ExportPackageLists (mHiiDatabaseProt
, Handle
, &BufferSize
, HiiPackageList
);
356 ASSERT (Status
!= EFI_NOT_FOUND
);
358 if (Status
== EFI_BUFFER_TOO_SMALL
) {
359 HiiPackageList
= AllocatePool (BufferSize
);
360 ASSERT (HiiPackageList
!= NULL
);
362 Status
= mHiiDatabaseProt
->ExportPackageLists (mHiiDatabaseProt
, Handle
, &BufferSize
, HiiPackageList
);
364 if (EFI_ERROR (Status
)) {
365 FreePool (HiiPackageList
);
372 CopyGuid (Guid
, &HiiPackageList
->PackageListGuid
);
374 FreePool (HiiPackageList
);
380 Find HII Handle in the default HII database associated with given Device Path.
382 If DevicePath is NULL, then ASSERT.
384 @param DevicePath Device Path associated with the HII package list
387 @retval Handle HII package list Handle associated with the Device
389 @retval NULL Hii Package list handle is not found.
394 HiiLibDevicePathToHiiHandle (
395 IN EFI_DEVICE_PATH_PROTOCOL
*DevicePath
399 EFI_DEVICE_PATH_PROTOCOL
*TmpDevicePath
;
406 EFI_HANDLE DriverHandle
;
407 EFI_HII_HANDLE
*HiiHandles
;
408 EFI_HII_HANDLE HiiHandle
;
410 ASSERT (DevicePath
!= NULL
);
413 // Locate Device Path Protocol handle buffer
415 Status
= gBS
->LocateHandleBuffer (
417 &gEfiDevicePathProtocolGuid
,
422 if (EFI_ERROR (Status
)) {
427 // Search Driver Handle by Device Path
430 BufferSize
= GetDevicePathSize (DevicePath
);
431 for(Index
= 0; Index
< HandleCount
; Index
++) {
432 Handle
= Handles
[Index
];
433 gBS
->HandleProtocol (Handle
, &gEfiDevicePathProtocolGuid
, (VOID
**) &TmpDevicePath
);
436 // Check whether DevicePath match
438 Size
= GetDevicePathSize (TmpDevicePath
);
439 if ((Size
== BufferSize
) && CompareMem (DevicePath
, TmpDevicePath
, Size
) == 0) {
440 DriverHandle
= Handle
;
446 if (DriverHandle
== NULL
) {
451 // Retrieve all Hii Handles from HII database
454 HiiHandles
= AllocatePool (BufferSize
);
455 ASSERT (HiiHandles
!= NULL
);
456 Status
= mHiiDatabaseProt
->ListPackageLists (
458 EFI_HII_PACKAGE_TYPE_ALL
,
463 if (Status
== EFI_BUFFER_TOO_SMALL
) {
464 FreePool (HiiHandles
);
465 HiiHandles
= AllocatePool (BufferSize
);
466 ASSERT (HiiHandles
!= NULL
);
468 Status
= mHiiDatabaseProt
->ListPackageLists (
470 EFI_HII_PACKAGE_TYPE_ALL
,
477 if (EFI_ERROR (Status
)) {
478 FreePool (HiiHandles
);
483 // Search Hii Handle by Driver Handle
486 HandleCount
= BufferSize
/ sizeof (EFI_HII_HANDLE
);
487 for (Index
= 0; Index
< HandleCount
; Index
++) {
488 Status
= mHiiDatabaseProt
->GetPackageListHandle (
493 if (!EFI_ERROR (Status
) && (Handle
== DriverHandle
)) {
494 HiiHandle
= HiiHandles
[Index
];
499 FreePool (HiiHandles
);
504 Exports the contents of one or all package lists in the HII database into a buffer.
506 If Handle is not NULL and not a valid EFI_HII_HANDLE registered in the database,
508 If PackageListHeader is NULL, then ASSERT.
509 If PackageListSize is NULL, then ASSERT.
511 @param Handle The HII Handle.
512 @param PackageListHeader A pointer to a buffer that will contain the results of
514 @param PackageListSize On output, the length of the buffer that is required for the exported data.
516 @retval EFI_SUCCESS Package exported.
518 @retval EFI_OUT_OF_RESOURCES Not enought memory to complete the operations.
523 HiiLibExportPackageLists (
524 IN EFI_HII_HANDLE Handle
,
525 OUT EFI_HII_PACKAGE_LIST_HEADER
**PackageListHeader
,
526 OUT UINTN
*PackageListSize
531 EFI_HII_PACKAGE_LIST_HEADER
*PackageListHdr
;
533 ASSERT (PackageListSize
!= NULL
);
534 ASSERT (PackageListHeader
!= NULL
);
536 if (Handle
!= NULL
) {
537 ASSERT (IsHiiHandleRegistered (Handle
));
541 PackageListHdr
= NULL
;
542 Status
= mHiiDatabaseProt
->ExportPackageLists (
548 ASSERT_EFI_ERROR (Status
!= EFI_BUFFER_TOO_SMALL
);
550 if (Status
== EFI_BUFFER_TOO_SMALL
) {
551 PackageListHdr
= AllocateZeroPool (Size
);
553 if (PackageListHeader
== NULL
) {
554 return EFI_OUT_OF_RESOURCES
;
556 Status
= mHiiDatabaseProt
->ExportPackageLists (
565 if (!EFI_ERROR (Status
)) {
566 *PackageListHeader
= PackageListHdr
;
567 *PackageListSize
= Size
;
569 FreePool (PackageListHdr
);
577 This function returns a list of the package handles of the
578 specified type that are currently active in the HII database. The
579 pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package
580 handles to be listed.
582 If HandleBufferLength is NULL, then ASSERT.
583 If HandleBuffer is NULL, the ASSERT.
584 If PackageType is EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is
586 If PackageType is not EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is not
590 @param PackageType Specifies the package type of the packages
591 to list or EFI_HII_PACKAGE_TYPE_ALL for
592 all packages to be listed.
594 @param PackageGuid If PackageType is
595 EFI_HII_PACKAGE_TYPE_GUID, then this is
596 the pointer to the GUID which must match
598 EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
601 @param HandleBufferLength On output, the length of the handle buffer
602 that is required for the handles found.
604 @param HandleBuffer On output, an array of EFI_HII_HANDLE instances returned.
605 The caller is responcible to free this pointer allocated.
607 @retval EFI_SUCCESS The matching handles are outputed successfully.
608 HandleBufferLength is updated with the actual length.
609 @retval EFI_OUT_OF_RESOURCES Not enough resource to complete the operation.
610 @retval EFI_NOT_FOUND No matching handle could not be found in database.
614 HiiLibListPackageLists (
615 IN UINT8 PackageType
,
616 IN CONST EFI_GUID
*PackageGuid
,
617 IN OUT UINTN
*HandleBufferLength
,
618 OUT EFI_HII_HANDLE
**HandleBuffer
623 ASSERT (HandleBufferLength
!= NULL
);
624 ASSERT (HandleBuffer
!= NULL
);
626 *HandleBufferLength
= 0;
627 *HandleBuffer
= NULL
;
629 if (PackageType
== EFI_HII_PACKAGE_TYPE_GUID
) {
630 ASSERT (PackageGuid
!= NULL
);
632 ASSERT (PackageGuid
== NULL
);
635 Status
= mHiiDatabaseProt
->ListPackageLists (
642 if (EFI_ERROR (Status
) && (Status
!= EFI_BUFFER_TOO_SMALL
)) {
644 // No packages is registered to UEFI HII Database, just return.
650 *HandleBuffer
= AllocateZeroPool (*HandleBufferLength
);
652 if (*HandleBuffer
== NULL
) {
653 return EFI_OUT_OF_RESOURCES
;
656 return mHiiDatabaseProt
->ListPackageLists (
666 This function check if the Hii Handle is a valid handle registered
669 @param HiiHandle The HII Handle.
671 @retval TRUE If it is a valid HII handle.
672 @retval FALSE If it is a invalid HII handle.
675 IsHiiHandleRegistered (
676 EFI_HII_HANDLE HiiHandle
681 EFI_HII_PACKAGE_LIST_HEADER
*HiiPackageList
;
683 ASSERT (HiiHandle
!= NULL
);
685 HiiPackageList
= NULL
;
688 Status
= mHiiDatabaseProt
->ExportPackageLists (
695 return (BOOLEAN
) (Status
== EFI_BUFFER_TOO_SMALL
);