2 Load option library functions which relate with creating and processing load options.
4 Copyright (c) 2011 - 2017, Intel Corporation. All rights reserved.<BR>
5 (C) Copyright 2015-2016 Hewlett Packard Enterprise Development LP<BR>
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #include "InternalBm.h"
18 GLOBAL_REMOVE_IF_UNREFERENCED
19 CHAR16
*mBmLoadOptionName
[] = {
26 GLOBAL_REMOVE_IF_UNREFERENCED
27 CHAR16
*mBmLoadOptionOrderName
[] = {
28 EFI_DRIVER_ORDER_VARIABLE_NAME
,
29 EFI_SYS_PREP_ORDER_VARIABLE_NAME
,
30 EFI_BOOT_ORDER_VARIABLE_NAME
,
31 NULL
// PlatformRecovery#### doesn't have associated *Order variable
35 Call Visitor function for each variable in variable storage.
37 @param Visitor Visitor function.
38 @param Context The context passed to Visitor function.
42 BM_VARIABLE_VISITOR Visitor
,
52 NameSize
= sizeof (CHAR16
);
53 Name
= AllocateZeroPool (NameSize
);
54 ASSERT (Name
!= NULL
);
56 NewNameSize
= NameSize
;
57 Status
= gRT
->GetNextVariableName (&NewNameSize
, Name
, &Guid
);
58 if (Status
== EFI_BUFFER_TOO_SMALL
) {
59 Name
= ReallocatePool (NameSize
, NewNameSize
, Name
);
60 ASSERT (Name
!= NULL
);
61 Status
= gRT
->GetNextVariableName (&NewNameSize
, Name
, &Guid
);
62 NameSize
= NewNameSize
;
65 if (Status
== EFI_NOT_FOUND
) {
68 ASSERT_EFI_ERROR (Status
);
70 Visitor (Name
, &Guid
, Context
);
77 Get the Option Number that wasn't used.
79 @param LoadOptionType The load option type.
80 @param FreeOptionNumber Return the minimal free option number.
82 @retval EFI_SUCCESS The option number is found and will be returned.
83 @retval EFI_OUT_OF_RESOURCES There is no free option number that can be used.
84 @retval EFI_INVALID_PARAMETER FreeOptionNumber is NULL
88 BmGetFreeOptionNumber (
89 IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE LoadOptionType
,
90 OUT UINT16
*FreeOptionNumber
97 UINTN OptionOrderSize
;
100 ASSERT (FreeOptionNumber
!= NULL
);
101 ASSERT (LoadOptionType
== LoadOptionTypeDriver
||
102 LoadOptionType
== LoadOptionTypeBoot
||
103 LoadOptionType
== LoadOptionTypeSysPrep
);
105 GetEfiGlobalVariable2 (mBmLoadOptionOrderName
[LoadOptionType
], (VOID
**) &OptionOrder
, &OptionOrderSize
);
106 ASSERT ((OptionOrder
!= NULL
&& OptionOrderSize
!= 0) || (OptionOrder
== NULL
&& OptionOrderSize
== 0));
109 if (LoadOptionType
== LoadOptionTypeBoot
) {
110 GetEfiGlobalVariable2 (L
"BootNext", (VOID
**) &BootNext
, NULL
);
113 for (OptionNumber
= 0;
114 OptionNumber
< OptionOrderSize
/ sizeof (UINT16
)
115 + ((BootNext
!= NULL
) ? 1 : 0);
119 // Search in OptionOrder whether the OptionNumber exists
121 for (Index
= 0; Index
< OptionOrderSize
/ sizeof (UINT16
); Index
++) {
122 if (OptionNumber
== OptionOrder
[Index
]) {
128 // We didn't find it in the ****Order array and it doesn't equal to BootNext
129 // Otherwise, OptionNumber equals to OptionOrderSize / sizeof (UINT16) + 1
131 if ((Index
== OptionOrderSize
/ sizeof (UINT16
)) &&
132 ((BootNext
== NULL
) || (OptionNumber
!= *BootNext
))
137 if (OptionOrder
!= NULL
) {
138 FreePool (OptionOrder
);
141 if (BootNext
!= NULL
) {
146 // When BootOrder & BootNext conver all numbers in the range [0 ... 0xffff],
147 // OptionNumber equals to 0x10000 which is not valid.
149 ASSERT (OptionNumber
<= 0x10000);
150 if (OptionNumber
== 0x10000) {
151 return EFI_OUT_OF_RESOURCES
;
153 *FreeOptionNumber
= (UINT16
) OptionNumber
;
159 Create the Boot####, Driver####, SysPrep####, PlatformRecovery#### variable
160 from the load option.
162 @param LoadOption Pointer to the load option.
164 @retval EFI_SUCCESS The variable was created.
165 @retval Others Error status returned by RT->SetVariable.
169 EfiBootManagerLoadOptionToVariable (
170 IN CONST EFI_BOOT_MANAGER_LOAD_OPTION
*Option
177 CHAR16 OptionName
[BM_OPTION_NAME_LEN
];
180 EDKII_VARIABLE_LOCK_PROTOCOL
*VariableLock
;
181 UINT32 VariableAttributes
;
183 if ((Option
->OptionNumber
== LoadOptionNumberUnassigned
) ||
184 (Option
->FilePath
== NULL
) ||
185 ((UINT32
) Option
->OptionType
>= LoadOptionTypeMax
)
187 return EFI_INVALID_PARAMETER
;
191 // Convert NULL description to empty description
194 Description
= Option
->Description
;
195 if (Description
== NULL
) {
196 Description
= &NullChar
;
201 UINT16 FilePathListLength;
202 CHAR16 Description[];
203 EFI_DEVICE_PATH_PROTOCOL FilePathList[];
204 UINT8 OptionalData[];
205 TODO: FilePathList[] IS:
206 A packed array of UEFI device paths. The first element of the
207 array is a device path that describes the device and location of the
208 Image for this load option. The FilePathList[0] is specific
209 to the device type. Other device paths may optionally exist in the
210 FilePathList, but their usage is OSV specific. Each element
211 in the array is variable length, and ends at the device path end
214 VariableSize
= sizeof (Option
->Attributes
)
216 + StrSize (Description
)
217 + GetDevicePathSize (Option
->FilePath
)
218 + Option
->OptionalDataSize
;
220 Variable
= AllocatePool (VariableSize
);
221 ASSERT (Variable
!= NULL
);
224 WriteUnaligned32 ((UINT32
*) Ptr
, Option
->Attributes
);
225 Ptr
+= sizeof (Option
->Attributes
);
227 WriteUnaligned16 ((UINT16
*) Ptr
, (UINT16
) GetDevicePathSize (Option
->FilePath
));
228 Ptr
+= sizeof (UINT16
);
230 CopyMem (Ptr
, Description
, StrSize (Description
));
231 Ptr
+= StrSize (Description
);
233 CopyMem (Ptr
, Option
->FilePath
, GetDevicePathSize (Option
->FilePath
));
234 Ptr
+= GetDevicePathSize (Option
->FilePath
);
236 CopyMem (Ptr
, Option
->OptionalData
, Option
->OptionalDataSize
);
238 UnicodeSPrint (OptionName
, sizeof (OptionName
), L
"%s%04x", mBmLoadOptionName
[Option
->OptionType
], Option
->OptionNumber
);
240 VariableAttributes
= EFI_VARIABLE_BOOTSERVICE_ACCESS
| EFI_VARIABLE_RUNTIME_ACCESS
| EFI_VARIABLE_NON_VOLATILE
;
241 if (Option
->OptionType
== LoadOptionTypePlatformRecovery
) {
243 // Lock the PlatformRecovery####
245 Status
= gBS
->LocateProtocol (&gEdkiiVariableLockProtocolGuid
, NULL
, (VOID
**) &VariableLock
);
246 if (!EFI_ERROR (Status
)) {
247 Status
= VariableLock
->RequestToLock (VariableLock
, OptionName
, &gEfiGlobalVariableGuid
);
248 ASSERT_EFI_ERROR (Status
);
250 VariableAttributes
= EFI_VARIABLE_BOOTSERVICE_ACCESS
| EFI_VARIABLE_RUNTIME_ACCESS
;
253 return gRT
->SetVariable (
255 &gEfiGlobalVariableGuid
,
263 Update order variable .
265 @param OptionOrderName Order variable name which need to be updated.
266 @param OptionNumber Option number for the new option.
267 @param Position Position of the new load option to put in the ****Order variable.
269 @retval EFI_SUCCESS The boot#### or driver#### have been successfully registered.
270 @retval EFI_ALREADY_STARTED The option number of Option is being used already.
271 @retval EFI_STATUS Return the status of gRT->SetVariable ().
275 BmAddOptionNumberToOrderVariable (
276 IN CHAR16
*OptionOrderName
,
277 IN UINT16 OptionNumber
,
284 UINT16
*NewOptionOrder
;
285 UINTN OptionOrderSize
;
287 // Update the option order variable
289 GetEfiGlobalVariable2 (OptionOrderName
, (VOID
**) &OptionOrder
, &OptionOrderSize
);
290 ASSERT ((OptionOrder
!= NULL
&& OptionOrderSize
!= 0) || (OptionOrder
== NULL
&& OptionOrderSize
== 0));
292 Status
= EFI_SUCCESS
;
293 for (Index
= 0; Index
< OptionOrderSize
/ sizeof (UINT16
); Index
++) {
294 if (OptionOrder
[Index
] == OptionNumber
) {
295 Status
= EFI_ALREADY_STARTED
;
300 if (!EFI_ERROR (Status
)) {
301 Position
= MIN (Position
, OptionOrderSize
/ sizeof (UINT16
));
303 NewOptionOrder
= AllocatePool (OptionOrderSize
+ sizeof (UINT16
));
304 ASSERT (NewOptionOrder
!= NULL
);
305 if (OptionOrderSize
!= 0) {
306 CopyMem (NewOptionOrder
, OptionOrder
, Position
* sizeof (UINT16
));
307 CopyMem (&NewOptionOrder
[Position
+ 1], &OptionOrder
[Position
], OptionOrderSize
- Position
* sizeof (UINT16
));
309 NewOptionOrder
[Position
] = OptionNumber
;
311 Status
= gRT
->SetVariable (
313 &gEfiGlobalVariableGuid
,
314 EFI_VARIABLE_BOOTSERVICE_ACCESS
| EFI_VARIABLE_RUNTIME_ACCESS
| EFI_VARIABLE_NON_VOLATILE
,
315 OptionOrderSize
+ sizeof (UINT16
),
318 FreePool (NewOptionOrder
);
321 if (OptionOrder
!= NULL
) {
322 FreePool (OptionOrder
);
329 This function will register the new Boot####, Driver#### or SysPrep#### option.
330 After the *#### is updated, the *Order will also be updated.
332 @param Option Pointer to load option to add.
333 @param Position Position of the new load option to put in the ****Order variable.
335 @retval EFI_SUCCESS The *#### have been successfully registered.
336 @retval EFI_INVALID_PARAMETER The option number exceeds 0xFFFF.
337 @retval EFI_ALREADY_STARTED The option number of Option is being used already.
338 Note: this API only adds new load option, no replacement support.
339 @retval EFI_OUT_OF_RESOURCES There is no free option number that can be used when the
340 option number specified in the Option is LoadOptionNumberUnassigned.
341 @retval EFI_STATUS Return the status of gRT->SetVariable ().
346 EfiBootManagerAddLoadOptionVariable (
347 IN EFI_BOOT_MANAGER_LOAD_OPTION
*Option
,
354 if (Option
== NULL
) {
355 return EFI_INVALID_PARAMETER
;
358 if (Option
->OptionType
!= LoadOptionTypeDriver
&&
359 Option
->OptionType
!= LoadOptionTypeSysPrep
&&
360 Option
->OptionType
!= LoadOptionTypeBoot
362 return EFI_INVALID_PARAMETER
;
366 // Get the free option number if the option number is unassigned
368 if (Option
->OptionNumber
== LoadOptionNumberUnassigned
) {
369 Status
= BmGetFreeOptionNumber (Option
->OptionType
, &OptionNumber
);
370 if (EFI_ERROR (Status
)) {
373 Option
->OptionNumber
= OptionNumber
;
376 if (Option
->OptionNumber
>= LoadOptionNumberMax
) {
377 return EFI_INVALID_PARAMETER
;
380 Status
= BmAddOptionNumberToOrderVariable (mBmLoadOptionOrderName
[Option
->OptionType
], (UINT16
) Option
->OptionNumber
, Position
);
381 if (!EFI_ERROR (Status
)) {
383 // Save the Boot#### or Driver#### variable
385 Status
= EfiBootManagerLoadOptionToVariable (Option
);
386 if (EFI_ERROR (Status
)) {
388 // Remove the #### from *Order variable when the Driver####/SysPrep####/Boot#### cannot be saved.
390 EfiBootManagerDeleteLoadOptionVariable (Option
->OptionNumber
, Option
->OptionType
);
398 Sort the load option. The DriverOrder or BootOrder will be re-created to
399 reflect the new order.
401 @param OptionType Load option type
402 @param CompareFunction The comparator
406 EfiBootManagerSortLoadOptionVariable (
407 EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType
,
408 SORT_COMPARE CompareFunction
412 EFI_BOOT_MANAGER_LOAD_OPTION
*LoadOption
;
413 UINTN LoadOptionCount
;
417 LoadOption
= EfiBootManagerGetLoadOptions (&LoadOptionCount
, OptionType
);
420 // Insertion sort algorithm
425 sizeof (EFI_BOOT_MANAGER_LOAD_OPTION
),
430 // Create new ****Order variable
432 OptionOrder
= AllocatePool (LoadOptionCount
* sizeof (UINT16
));
433 ASSERT (OptionOrder
!= NULL
);
434 for (Index
= 0; Index
< LoadOptionCount
; Index
++) {
435 OptionOrder
[Index
] = (UINT16
) LoadOption
[Index
].OptionNumber
;
438 Status
= gRT
->SetVariable (
439 mBmLoadOptionOrderName
[OptionType
],
440 &gEfiGlobalVariableGuid
,
441 EFI_VARIABLE_BOOTSERVICE_ACCESS
| EFI_VARIABLE_RUNTIME_ACCESS
| EFI_VARIABLE_NON_VOLATILE
,
442 LoadOptionCount
* sizeof (UINT16
),
446 // Changing the *Order content without increasing its size with current variable implementation shouldn't fail.
448 ASSERT_EFI_ERROR (Status
);
450 FreePool (OptionOrder
);
451 EfiBootManagerFreeLoadOptions (LoadOption
, LoadOptionCount
);
455 Initialize a load option.
457 @param Option Pointer to the load option to be initialized.
458 @param OptionNumber Option number of the load option.
459 @param OptionType Type of the load option.
460 @param Attributes Attributes of the load option.
461 @param Description Description of the load option.
462 @param FilePath Device path of the load option.
463 @param OptionalData Optional data of the load option.
464 @param OptionalDataSize Size of the optional data of the load option.
466 @retval EFI_SUCCESS The load option was initialized successfully.
467 @retval EFI_INVALID_PARAMETER Option, Description or FilePath is NULL.
471 EfiBootManagerInitializeLoadOption (
472 IN OUT EFI_BOOT_MANAGER_LOAD_OPTION
*Option
,
473 IN UINTN OptionNumber
,
474 IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType
,
475 IN UINT32 Attributes
,
476 IN CHAR16
*Description
,
477 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
478 IN UINT8
*OptionalData
, OPTIONAL
479 IN UINT32 OptionalDataSize
482 if ((Option
== NULL
) || (Description
== NULL
) || (FilePath
== NULL
)) {
483 return EFI_INVALID_PARAMETER
;
486 if (((OptionalData
!= NULL
) && (OptionalDataSize
== 0)) ||
487 ((OptionalData
== NULL
) && (OptionalDataSize
!= 0))) {
488 return EFI_INVALID_PARAMETER
;
491 if ((UINT32
) OptionType
>= LoadOptionTypeMax
) {
492 return EFI_INVALID_PARAMETER
;
495 ZeroMem (Option
, sizeof (EFI_BOOT_MANAGER_LOAD_OPTION
));
496 Option
->OptionNumber
= OptionNumber
;
497 Option
->OptionType
= OptionType
;
498 Option
->Attributes
= Attributes
;
499 Option
->Description
= AllocateCopyPool (StrSize (Description
), Description
);
500 Option
->FilePath
= DuplicateDevicePath (FilePath
);
501 if (OptionalData
!= NULL
) {
502 Option
->OptionalData
= AllocateCopyPool (OptionalDataSize
, OptionalData
);
503 Option
->OptionalDataSize
= OptionalDataSize
;
511 Return the index of the load option in the load option array.
513 The function consider two load options are equal when the
514 OptionType, Attributes, Description, FilePath and OptionalData are equal.
516 @param Key Pointer to the load option to be found.
517 @param Array Pointer to the array of load options to be found.
518 @param Count Number of entries in the Array.
520 @retval -1 Key wasn't found in the Array.
521 @retval 0 ~ Count-1 The index of the Key in the Array.
525 EfiBootManagerFindLoadOption (
526 IN CONST EFI_BOOT_MANAGER_LOAD_OPTION
*Key
,
527 IN CONST EFI_BOOT_MANAGER_LOAD_OPTION
*Array
,
533 for (Index
= 0; Index
< Count
; Index
++) {
534 if ((Key
->OptionType
== Array
[Index
].OptionType
) &&
535 (Key
->Attributes
== Array
[Index
].Attributes
) &&
536 (StrCmp (Key
->Description
, Array
[Index
].Description
) == 0) &&
537 (CompareMem (Key
->FilePath
, Array
[Index
].FilePath
, GetDevicePathSize (Key
->FilePath
)) == 0) &&
538 (Key
->OptionalDataSize
== Array
[Index
].OptionalDataSize
) &&
539 (CompareMem (Key
->OptionalData
, Array
[Index
].OptionalData
, Key
->OptionalDataSize
) == 0)) {
548 Delete the load option.
550 @param OptionNumber Indicate the option number of load option
551 @param OptionType Indicate the type of load option
553 @retval EFI_INVALID_PARAMETER OptionType or OptionNumber is invalid.
554 @retval EFI_NOT_FOUND The load option cannot be found
555 @retval EFI_SUCCESS The load option was deleted
556 @retval others Status of RT->SetVariable()
560 EfiBootManagerDeleteLoadOptionVariable (
561 IN UINTN OptionNumber
,
562 IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType
566 UINTN OptionOrderSize
;
568 CHAR16 OptionName
[BM_OPTION_NAME_LEN
];
570 if (((UINT32
) OptionType
>= LoadOptionTypeMax
) || (OptionNumber
>= LoadOptionNumberMax
)) {
571 return EFI_INVALID_PARAMETER
;
574 if (OptionType
== LoadOptionTypeDriver
|| OptionType
== LoadOptionTypeSysPrep
|| OptionType
== LoadOptionTypeBoot
) {
576 // If the associated *Order exists, firstly remove the reference in *Order for
577 // Driver####, SysPrep#### and Boot####.
579 GetEfiGlobalVariable2 (mBmLoadOptionOrderName
[OptionType
], (VOID
**) &OptionOrder
, &OptionOrderSize
);
580 ASSERT ((OptionOrder
!= NULL
&& OptionOrderSize
!= 0) || (OptionOrder
== NULL
&& OptionOrderSize
== 0));
582 for (Index
= 0; Index
< OptionOrderSize
/ sizeof (UINT16
); Index
++) {
583 if (OptionOrder
[Index
] == OptionNumber
) {
584 OptionOrderSize
-= sizeof (UINT16
);
585 CopyMem (&OptionOrder
[Index
], &OptionOrder
[Index
+ 1], OptionOrderSize
- Index
* sizeof (UINT16
));
587 mBmLoadOptionOrderName
[OptionType
],
588 &gEfiGlobalVariableGuid
,
589 EFI_VARIABLE_BOOTSERVICE_ACCESS
| EFI_VARIABLE_RUNTIME_ACCESS
| EFI_VARIABLE_NON_VOLATILE
,
596 if (OptionOrder
!= NULL
) {
597 FreePool (OptionOrder
);
602 // Remove the Driver####, SysPrep####, Boot#### or PlatformRecovery#### itself.
604 UnicodeSPrint (OptionName
, sizeof (OptionName
), L
"%s%04x", mBmLoadOptionName
[OptionType
], OptionNumber
);
605 return gRT
->SetVariable (
607 &gEfiGlobalVariableGuid
,
615 Returns the size of a device path in bytes.
617 This function returns the size, in bytes, of the device path data structure
618 specified by DevicePath including the end of device path node. If DevicePath
619 is NULL, then 0 is returned. If the length of the device path is bigger than
620 MaxSize, also return 0 to indicate this is an invalidate device path.
622 @param DevicePath A pointer to a device path data structure.
623 @param MaxSize Max valid device path size. If big than this size,
626 @retval 0 An invalid device path.
627 @retval Others The size of a device path in bytes.
631 BmGetDevicePathSizeEx (
632 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
639 if (DevicePath
== NULL
) {
644 // Search for the end of the device path structure
647 while (!IsDevicePathEnd (DevicePath
)) {
648 NodeSize
= DevicePathNodeLength (DevicePath
);
653 if (Size
> MaxSize
) {
656 DevicePath
= NextDevicePathNode (DevicePath
);
658 Size
+= DevicePathNodeLength (DevicePath
);
659 if (Size
> MaxSize
) {
667 Returns the length of a Null-terminated Unicode string. If the length is
668 bigger than MaxStringLen, return length 0 to indicate that this is an
671 This function returns the number of Unicode characters in the Null-terminated
672 Unicode string specified by String.
674 If String is NULL, then ASSERT().
675 If String is not aligned on a 16-bit boundary, then ASSERT().
677 @param String A pointer to a Null-terminated Unicode string.
678 @param MaxStringLen Max string len in this string.
680 @retval 0 An invalid string.
681 @retval Others The length of String.
686 IN CONST CHAR16
*String
,
687 IN UINTN MaxStringLen
692 ASSERT (String
!= NULL
&& MaxStringLen
!= 0);
693 ASSERT (((UINTN
) String
& BIT0
) == 0);
695 for (Length
= 0; *String
!= L
'\0' && MaxStringLen
!= Length
; String
++, Length
+=2);
697 if (*String
!= L
'\0' && MaxStringLen
== Length
) {
705 Validate the Boot####, Driver####, SysPrep#### and PlatformRecovery####
706 variable (VendorGuid/Name)
708 @param Variable The variable data.
709 @param VariableSize The variable size.
711 @retval TRUE The variable data is correct.
712 @retval FALSE The variable data is corrupted.
722 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
723 UINTN DescriptionSize
;
725 if (VariableSize
<= sizeof (UINT16
) + sizeof (UINT32
)) {
730 // Skip the option attribute
732 Variable
+= sizeof (UINT32
);
735 // Get the option's device path size
737 FilePathSize
= ReadUnaligned16 ((UINT16
*) Variable
);
738 Variable
+= sizeof (UINT16
);
741 // Get the option's description string size
743 DescriptionSize
= BmStrSizeEx ((CHAR16
*) Variable
, VariableSize
- sizeof (UINT16
) - sizeof (UINT32
));
744 Variable
+= DescriptionSize
;
747 // Get the option's device path
749 DevicePath
= (EFI_DEVICE_PATH_PROTOCOL
*) Variable
;
752 // Validation boot option variable.
754 if ((FilePathSize
== 0) || (DescriptionSize
== 0)) {
758 if (sizeof (UINT32
) + sizeof (UINT16
) + DescriptionSize
+ FilePathSize
> VariableSize
) {
762 return (BOOLEAN
) (BmGetDevicePathSizeEx (DevicePath
, FilePathSize
) != 0);
766 Check whether the VariableName is a valid load option variable name
767 and return the load option type and option number.
769 @param VariableName The name of the load option variable.
770 @param OptionType Return the load option type.
771 @param OptionNumber Return the load option number.
773 @retval TRUE The variable name is valid; The load option type and
774 load option number is returned.
775 @retval FALSE The variable name is NOT valid.
779 EfiBootManagerIsValidLoadOptionVariableName (
780 IN CHAR16
*VariableName
,
781 OUT EFI_BOOT_MANAGER_LOAD_OPTION_TYPE
*OptionType OPTIONAL
,
782 OUT UINT16
*OptionNumber OPTIONAL
785 UINTN VariableNameLen
;
788 EFI_BOOT_MANAGER_LOAD_OPTION_TYPE LocalOptionType
;
789 UINT16 LocalOptionNumber
;
791 if (VariableName
== NULL
) {
795 VariableNameLen
= StrLen (VariableName
);
798 // Return FALSE when the variable name length is too small.
800 if (VariableNameLen
<= 4) {
805 // Return FALSE when the variable name doesn't start with Driver/SysPrep/Boot/PlatformRecovery.
807 for (LocalOptionType
= 0; LocalOptionType
< ARRAY_SIZE (mBmLoadOptionName
); LocalOptionType
++) {
808 if ((VariableNameLen
- 4 == StrLen (mBmLoadOptionName
[LocalOptionType
])) &&
809 (StrnCmp (VariableName
, mBmLoadOptionName
[LocalOptionType
], VariableNameLen
- 4) == 0)
814 if (LocalOptionType
== ARRAY_SIZE (mBmLoadOptionName
)) {
819 // Return FALSE when the last four characters are not hex digits.
821 LocalOptionNumber
= 0;
822 for (Index
= VariableNameLen
- 4; Index
< VariableNameLen
; Index
++) {
823 Uint
= BmCharToUint (VariableName
[Index
]);
827 LocalOptionNumber
= (UINT16
) Uint
+ LocalOptionNumber
* 0x10;
830 if (Index
!= VariableNameLen
) {
834 if (OptionType
!= NULL
) {
835 *OptionType
= LocalOptionType
;
838 if (OptionNumber
!= NULL
) {
839 *OptionNumber
= LocalOptionNumber
;
846 Build the Boot#### or Driver#### option from the VariableName.
848 @param VariableName Variable name of the load option
849 @param VendorGuid Variable GUID of the load option
850 @param Option Return the load option.
852 @retval EFI_SUCCESS Get the option just been created
853 @retval EFI_NOT_FOUND Failed to get the new option
858 EfiBootManagerVariableToLoadOptionEx (
859 IN CHAR16
*VariableName
,
860 IN EFI_GUID
*VendorGuid
,
861 IN OUT EFI_BOOT_MANAGER_LOAD_OPTION
*Option
870 EFI_DEVICE_PATH_PROTOCOL
*FilePath
;
872 UINT32 OptionalDataSize
;
874 EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType
;
877 if ((VariableName
== NULL
) || (Option
== NULL
)) {
878 return EFI_INVALID_PARAMETER
;
881 if (!EfiBootManagerIsValidLoadOptionVariableName (VariableName
, &OptionType
, &OptionNumber
)) {
882 return EFI_INVALID_PARAMETER
;
888 GetVariable2 (VariableName
, VendorGuid
, (VOID
**) &Variable
, &VariableSize
);
889 if (Variable
== NULL
) {
890 return EFI_NOT_FOUND
;
894 // Validate *#### variable data.
896 if (!BmValidateOption(Variable
, VariableSize
)) {
898 return EFI_INVALID_PARAMETER
;
902 // Get the option attribute
904 VariablePtr
= Variable
;
905 Attribute
= ReadUnaligned32 ((UINT32
*) VariablePtr
);
906 VariablePtr
+= sizeof (UINT32
);
909 // Get the option's device path size
911 FilePathSize
= ReadUnaligned16 ((UINT16
*) VariablePtr
);
912 VariablePtr
+= sizeof (UINT16
);
915 // Get the option's description string
917 Description
= (CHAR16
*) VariablePtr
;
920 // Get the option's description string size
922 VariablePtr
+= StrSize ((CHAR16
*) VariablePtr
);
925 // Get the option's device path
927 FilePath
= (EFI_DEVICE_PATH_PROTOCOL
*) VariablePtr
;
928 VariablePtr
+= FilePathSize
;
930 OptionalDataSize
= (UINT32
) (VariableSize
- ((UINTN
) VariablePtr
- (UINTN
) Variable
));
931 if (OptionalDataSize
== 0) {
934 OptionalData
= VariablePtr
;
937 Status
= EfiBootManagerInitializeLoadOption (
947 ASSERT_EFI_ERROR (Status
);
949 CopyGuid (&Option
->VendorGuid
, VendorGuid
);
956 Build the Boot#### or Driver#### option from the VariableName.
958 @param VariableName EFI Variable name indicate if it is Boot#### or Driver####
959 @param Option Return the Boot#### or Driver#### option.
961 @retval EFI_SUCCESS Get the option just been created
962 @retval EFI_NOT_FOUND Failed to get the new option
966 EfiBootManagerVariableToLoadOption (
967 IN CHAR16
*VariableName
,
968 IN OUT EFI_BOOT_MANAGER_LOAD_OPTION
*Option
971 return EfiBootManagerVariableToLoadOptionEx (VariableName
, &gEfiGlobalVariableGuid
, Option
);
975 EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType
;
977 EFI_BOOT_MANAGER_LOAD_OPTION
*Options
;
979 } BM_COLLECT_LOAD_OPTIONS_PARAM
;
982 Visitor function to collect the Platform Recovery load options or OS Recovery
983 load options from NV storage.
985 @param Name Variable name.
986 @param Guid Variable GUID.
987 @param Context The same context passed to BmForEachVariable.
990 BmCollectLoadOptions (
997 EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType
;
999 EFI_BOOT_MANAGER_LOAD_OPTION Option
;
1001 BM_COLLECT_LOAD_OPTIONS_PARAM
*Param
;
1003 Param
= (BM_COLLECT_LOAD_OPTIONS_PARAM
*) Context
;
1005 if (CompareGuid (Guid
, Param
->Guid
) && (
1006 Param
->OptionType
== LoadOptionTypePlatformRecovery
&&
1007 EfiBootManagerIsValidLoadOptionVariableName (Name
, &OptionType
, &OptionNumber
) &&
1008 OptionType
== LoadOptionTypePlatformRecovery
1010 Status
= EfiBootManagerVariableToLoadOptionEx (Name
, Guid
, &Option
);
1011 if (!EFI_ERROR (Status
)) {
1012 for (Index
= 0; Index
< Param
->OptionCount
; Index
++) {
1013 if (Param
->Options
[Index
].OptionNumber
> Option
.OptionNumber
) {
1017 Param
->Options
= ReallocatePool (
1018 Param
->OptionCount
* sizeof (EFI_BOOT_MANAGER_LOAD_OPTION
),
1019 (Param
->OptionCount
+ 1) * sizeof (EFI_BOOT_MANAGER_LOAD_OPTION
),
1022 ASSERT (Param
->Options
!= NULL
);
1023 CopyMem (&Param
->Options
[Index
+ 1], &Param
->Options
[Index
], (Param
->OptionCount
- Index
) * sizeof (EFI_BOOT_MANAGER_LOAD_OPTION
));
1024 CopyMem (&Param
->Options
[Index
], &Option
, sizeof (EFI_BOOT_MANAGER_LOAD_OPTION
));
1025 Param
->OptionCount
++;
1031 Returns an array of load options based on the EFI variable
1032 L"BootOrder"/L"DriverOrder" and the L"Boot####"/L"Driver####" variables impled by it.
1033 #### is the hex value of the UINT16 in each BootOrder/DriverOrder entry.
1035 @param LoadOptionCount Returns number of entries in the array.
1036 @param LoadOptionType The type of the load option.
1038 @retval NULL No load options exist.
1039 @retval !NULL Array of load option entries.
1042 EFI_BOOT_MANAGER_LOAD_OPTION
*
1044 EfiBootManagerGetLoadOptions (
1045 OUT UINTN
*OptionCount
,
1046 IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE LoadOptionType
1050 UINT16
*OptionOrder
;
1051 UINTN OptionOrderSize
;
1054 EFI_BOOT_MANAGER_LOAD_OPTION
*Options
;
1055 CHAR16 OptionName
[BM_OPTION_NAME_LEN
];
1056 UINT16 OptionNumber
;
1057 BM_COLLECT_LOAD_OPTIONS_PARAM Param
;
1062 if (LoadOptionType
== LoadOptionTypeDriver
|| LoadOptionType
== LoadOptionTypeSysPrep
|| LoadOptionType
== LoadOptionTypeBoot
) {
1064 // Read the BootOrder, or DriverOrder variable.
1066 GetEfiGlobalVariable2 (mBmLoadOptionOrderName
[LoadOptionType
], (VOID
**) &OptionOrder
, &OptionOrderSize
);
1067 if (OptionOrder
== NULL
) {
1071 *OptionCount
= OptionOrderSize
/ sizeof (UINT16
);
1073 Options
= AllocatePool (*OptionCount
* sizeof (EFI_BOOT_MANAGER_LOAD_OPTION
));
1074 ASSERT (Options
!= NULL
);
1077 for (Index
= 0; Index
< *OptionCount
; Index
++) {
1078 OptionNumber
= OptionOrder
[Index
];
1079 UnicodeSPrint (OptionName
, sizeof (OptionName
), L
"%s%04x", mBmLoadOptionName
[LoadOptionType
], OptionNumber
);
1081 Status
= EfiBootManagerVariableToLoadOption (OptionName
, &Options
[OptionIndex
]);
1082 if (EFI_ERROR (Status
)) {
1083 DEBUG ((EFI_D_INFO
, "[Bds] %s doesn't exist - Update ****Order variable to remove the reference!!", OptionName
));
1084 EfiBootManagerDeleteLoadOptionVariable (OptionNumber
, LoadOptionType
);
1086 ASSERT (Options
[OptionIndex
].OptionNumber
== OptionNumber
);
1091 if (OptionOrder
!= NULL
) {
1092 FreePool (OptionOrder
);
1095 if (OptionIndex
< *OptionCount
) {
1096 Options
= ReallocatePool (*OptionCount
* sizeof (EFI_BOOT_MANAGER_LOAD_OPTION
), OptionIndex
* sizeof (EFI_BOOT_MANAGER_LOAD_OPTION
), Options
);
1097 ASSERT (Options
!= NULL
);
1098 *OptionCount
= OptionIndex
;
1101 } else if (LoadOptionType
== LoadOptionTypePlatformRecovery
) {
1102 Param
.OptionType
= LoadOptionTypePlatformRecovery
;
1103 Param
.Options
= NULL
;
1104 Param
.OptionCount
= 0;
1105 Param
.Guid
= &gEfiGlobalVariableGuid
;
1107 BmForEachVariable (BmCollectLoadOptions
, (VOID
*) &Param
);
1109 *OptionCount
= Param
.OptionCount
;
1110 Options
= Param
.Options
;
1117 Free an EFI_BOOT_MANGER_LOAD_OPTION entry that was allocate by the library.
1119 @param LoadOption Pointer to boot option to Free.
1121 @return EFI_SUCCESS BootOption was freed
1122 @return EFI_NOT_FOUND BootOption == NULL
1127 EfiBootManagerFreeLoadOption (
1128 IN EFI_BOOT_MANAGER_LOAD_OPTION
*LoadOption
1131 if (LoadOption
== NULL
) {
1132 return EFI_NOT_FOUND
;
1135 if (LoadOption
->Description
!= NULL
) {
1136 FreePool (LoadOption
->Description
);
1138 if (LoadOption
->FilePath
!= NULL
) {
1139 FreePool (LoadOption
->FilePath
);
1141 if (LoadOption
->OptionalData
!= NULL
) {
1142 FreePool (LoadOption
->OptionalData
);
1149 Free an EFI_BOOT_MANGER_LOAD_OPTION array that was allocated by
1150 EfiBootManagerGetLoadOptions().
1152 @param Option Pointer to boot option array to free.
1153 @param OptionCount Number of array entries in BootOption
1155 @return EFI_SUCCESS BootOption was freed
1156 @return EFI_NOT_FOUND BootOption == NULL
1161 EfiBootManagerFreeLoadOptions (
1162 IN EFI_BOOT_MANAGER_LOAD_OPTION
*Option
,
1163 IN UINTN OptionCount
1168 if (Option
== NULL
) {
1169 return EFI_NOT_FOUND
;
1172 for (Index
= 0;Index
< OptionCount
; Index
++) {
1173 EfiBootManagerFreeLoadOption (&Option
[Index
]);
1182 Return whether the PE header of the load option is valid or not.
1184 @param[in] Type The load option type.
1185 It's used to check whether the load option is valid.
1186 When it's LoadOptionTypeMax, the routine only guarantees
1187 the load option is a valid PE image but doesn't guarantee
1188 the PE's subsystem type is valid.
1189 @param[in] FileBuffer The PE file buffer of the load option.
1190 @param[in] FileSize The size of the load option file.
1192 @retval TRUE The PE header of the load option is valid.
1193 @retval FALSE The PE header of the load option is not valid.
1196 BmIsLoadOptionPeHeaderValid (
1197 IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE Type
,
1198 IN VOID
*FileBuffer
,
1202 EFI_IMAGE_DOS_HEADER
*DosHeader
;
1203 EFI_IMAGE_OPTIONAL_HEADER_UNION
*PeHeader
;
1204 EFI_IMAGE_OPTIONAL_HEADER32
*OptionalHeader
;
1207 if (FileBuffer
== NULL
|| FileSize
== 0) {
1214 DosHeader
= (EFI_IMAGE_DOS_HEADER
*) FileBuffer
;
1215 if (FileSize
>= sizeof (EFI_IMAGE_DOS_HEADER
) &&
1216 FileSize
> DosHeader
->e_lfanew
&& DosHeader
->e_magic
== EFI_IMAGE_DOS_SIGNATURE
1219 // Read and check PE signature
1221 PeHeader
= (EFI_IMAGE_OPTIONAL_HEADER_UNION
*) ((UINT8
*) FileBuffer
+ DosHeader
->e_lfanew
);
1222 if (FileSize
>= DosHeader
->e_lfanew
+ sizeof (EFI_IMAGE_OPTIONAL_HEADER_UNION
) &&
1223 PeHeader
->Pe32
.Signature
== EFI_IMAGE_NT_SIGNATURE
1226 // Check PE32 or PE32+ magic, and machine type
1228 OptionalHeader
= (EFI_IMAGE_OPTIONAL_HEADER32
*) &PeHeader
->Pe32
.OptionalHeader
;
1229 if ((OptionalHeader
->Magic
== EFI_IMAGE_NT_OPTIONAL_HDR32_MAGIC
||
1230 OptionalHeader
->Magic
== EFI_IMAGE_NT_OPTIONAL_HDR64_MAGIC
) &&
1231 EFI_IMAGE_MACHINE_TYPE_SUPPORTED (PeHeader
->Pe32
.FileHeader
.Machine
)
1234 // Check the Subsystem:
1235 // Driver#### must be of type BootServiceDriver or RuntimeDriver
1236 // SysPrep####, Boot####, OsRecovery####, PlatformRecovery#### must be of type Application
1238 Subsystem
= OptionalHeader
->Subsystem
;
1239 if ((Type
== LoadOptionTypeMax
) ||
1240 (Type
== LoadOptionTypeDriver
&& Subsystem
== EFI_IMAGE_SUBSYSTEM_EFI_BOOT_SERVICE_DRIVER
) ||
1241 (Type
== LoadOptionTypeDriver
&& Subsystem
== EFI_IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER
) ||
1242 (Type
== LoadOptionTypeSysPrep
&& Subsystem
== EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION
) ||
1243 (Type
== LoadOptionTypeBoot
&& Subsystem
== EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION
) ||
1244 (Type
== LoadOptionTypePlatformRecovery
&& Subsystem
== EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION
)
1256 Return the next matched load option buffer.
1257 The routine keeps calling BmGetNextLoadOptionDevicePath() until a valid
1258 load option is read.
1260 @param Type The load option type.
1261 It's used to check whether the load option is valid.
1262 When it's LoadOptionTypeMax, the routine only guarantees
1263 the load option is a valid PE image but doesn't guarantee
1264 the PE's subsystem type is valid.
1265 @param FilePath The device path pointing to a load option.
1266 It could be a short-form device path.
1267 @param FullPath Return the next full device path of the load option after
1268 short-form device path expanding.
1269 Caller is responsible to free it.
1270 NULL to return the first matched full device path.
1271 @param FileSize Return the load option size.
1273 @return The load option buffer. Caller is responsible to free the memory.
1276 BmGetNextLoadOptionBuffer (
1277 IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE Type
,
1278 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
1279 OUT EFI_DEVICE_PATH_PROTOCOL
**FullPath
,
1284 EFI_DEVICE_PATH_PROTOCOL
*PreFullPath
;
1285 EFI_DEVICE_PATH_PROTOCOL
*CurFullPath
;
1286 UINTN LocalFileSize
;
1287 UINT32 AuthenticationStatus
;
1288 EFI_DEVICE_PATH_PROTOCOL
*RamDiskDevicePath
;
1292 CurFullPath
= *FullPath
;
1294 PreFullPath
= CurFullPath
;
1295 CurFullPath
= BmGetNextLoadOptionDevicePath (FilePath
, CurFullPath
);
1297 // Only free the full path created *inside* this routine
1299 if ((PreFullPath
!= NULL
) && (PreFullPath
!= *FullPath
)) {
1300 FreePool (PreFullPath
);
1302 if (CurFullPath
== NULL
) {
1305 FileBuffer
= GetFileBufferByFilePath (TRUE
, CurFullPath
, &LocalFileSize
, &AuthenticationStatus
);
1306 if ((FileBuffer
!= NULL
) && !BmIsLoadOptionPeHeaderValid (Type
, FileBuffer
, LocalFileSize
)) {
1308 // Free the RAM disk file system if the load option is invalid.
1310 RamDiskDevicePath
= BmGetRamDiskDevicePath (FilePath
);
1311 if (RamDiskDevicePath
!= NULL
) {
1312 BmDestroyRamDisk (RamDiskDevicePath
);
1313 FreePool (RamDiskDevicePath
);
1317 // Free the invalid load option buffer.
1319 FreePool (FileBuffer
);
1322 } while (FileBuffer
== NULL
);
1324 if (FileBuffer
== NULL
) {
1329 DEBUG ((DEBUG_INFO
, "[Bds] Expand "));
1330 BmPrintDp (FilePath
);
1331 DEBUG ((DEBUG_INFO
, " -> "));
1332 BmPrintDp (CurFullPath
);
1333 DEBUG ((DEBUG_INFO
, "\n"));
1335 *FullPath
= CurFullPath
;
1336 *FileSize
= LocalFileSize
;
1341 Process (load and execute) the load option.
1343 @param LoadOption Pointer to the load option.
1345 @retval EFI_INVALID_PARAMETER The load option type is invalid,
1346 or the load option file path doesn't point to a valid file.
1347 @retval EFI_UNSUPPORTED The load option type is of LoadOptionTypeBoot.
1348 @retval EFI_SUCCESS The load option is inactive, or successfully loaded and executed.
1352 EfiBootManagerProcessLoadOption (
1353 IN EFI_BOOT_MANAGER_LOAD_OPTION
*LoadOption
1357 EFI_DEVICE_PATH_PROTOCOL
*PreFullPath
;
1358 EFI_DEVICE_PATH_PROTOCOL
*CurFullPath
;
1359 EFI_HANDLE ImageHandle
;
1360 EFI_LOADED_IMAGE_PROTOCOL
*ImageInfo
;
1364 if ((UINT32
) LoadOption
->OptionType
>= LoadOptionTypeMax
) {
1365 return EFI_INVALID_PARAMETER
;
1368 if (LoadOption
->OptionType
== LoadOptionTypeBoot
) {
1369 return EFI_UNSUPPORTED
;
1373 // If a load option is not marked as LOAD_OPTION_ACTIVE,
1374 // the boot manager will not automatically load the option.
1376 if ((LoadOption
->Attributes
& LOAD_OPTION_ACTIVE
) == 0) {
1381 // Load and start the load option.
1384 DEBUG_INFO
| DEBUG_LOAD
, "Process %s%04x (%s) ...\n",
1385 mBmLoadOptionName
[LoadOption
->OptionType
], LoadOption
->OptionNumber
,
1386 LoadOption
->Description
1390 EfiBootManagerConnectDevicePath (LoadOption
->FilePath
, NULL
);
1393 // while() loop is to keep starting next matched load option if the PlatformRecovery#### returns failure status.
1396 Status
= EFI_INVALID_PARAMETER
;
1397 PreFullPath
= CurFullPath
;
1398 FileBuffer
= BmGetNextLoadOptionBuffer (LoadOption
->OptionType
, LoadOption
->FilePath
, &CurFullPath
, &FileSize
);
1399 if (PreFullPath
!= NULL
) {
1400 FreePool (PreFullPath
);
1402 if (FileBuffer
== NULL
) {
1405 Status
= gBS
->LoadImage (
1413 FreePool (FileBuffer
);
1415 if (!EFI_ERROR (Status
)) {
1416 Status
= gBS
->HandleProtocol (ImageHandle
, &gEfiLoadedImageProtocolGuid
, (VOID
**)&ImageInfo
);
1417 ASSERT_EFI_ERROR (Status
);
1419 ImageInfo
->LoadOptionsSize
= LoadOption
->OptionalDataSize
;
1420 ImageInfo
->LoadOptions
= LoadOption
->OptionalData
;
1422 // Before calling the image, enable the Watchdog Timer for the 5-minute period
1424 gBS
->SetWatchdogTimer (5 * 60, 0, 0, NULL
);
1426 LoadOption
->Status
= gBS
->StartImage (ImageHandle
, &LoadOption
->ExitDataSize
, &LoadOption
->ExitData
);
1428 DEBUG_INFO
| DEBUG_LOAD
, "%s%04x Return Status = %r\n",
1429 mBmLoadOptionName
[LoadOption
->OptionType
], LoadOption
->OptionNumber
, LoadOption
->Status
1433 // Clear the Watchdog Timer after the image returns
1435 gBS
->SetWatchdogTimer (0, 0, 0, NULL
);
1437 if ((LoadOption
->OptionType
!= LoadOptionTypePlatformRecovery
) || (LoadOption
->Status
== EFI_SUCCESS
)) {
1443 if (CurFullPath
!= NULL
) {
1444 FreePool (CurFullPath
);