/** @file\r
Provide Boot Manager related library APIs.\r
\r
-Copyright (c) 2011 - 2016, Intel Corporation. All rights reserved.<BR>\r
+Copyright (c) 2011 - 2019, Intel Corporation. All rights reserved.<BR>\r
(C) Copyright 2015-2016 Hewlett Packard Enterprise Development LP<BR>\r
-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
-http://opensource.org/licenses/bsd-license.php\r
-\r
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
-\r
#ifndef _UEFI_BOOT_MANAGER_LIB_H_\r
#define _UEFI_BOOT_MANAGER_LIB_H_\r
\r
} EFI_BOOT_MANAGER_LOAD_OPTION_TYPE;\r
\r
typedef enum {\r
- LoadOptionNumberMax = 0x10000,\r
+ LoadOptionNumberMax = 0x10000,\r
LoadOptionNumberUnassigned = LoadOptionNumberMax\r
} EFI_BOOT_MANAGER_LOAD_OPTION_NUMBER;\r
\r
//\r
// Data read from UEFI NV variables\r
//\r
- UINTN OptionNumber; // #### numerical value, could be LoadOptionNumberUnassigned\r
- EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType; // LoadOptionTypeBoot or LoadOptionTypeDriver\r
- UINT32 Attributes; // Load Option Attributes\r
- CHAR16 *Description; // Load Option Description\r
- EFI_DEVICE_PATH_PROTOCOL *FilePath; // Load Option Device Path\r
- UINT8 *OptionalData; // Load Option optional data to pass into image\r
- UINT32 OptionalDataSize; // Load Option size of OptionalData\r
- EFI_GUID VendorGuid;\r
+ UINTN OptionNumber; // #### numerical value, could be LoadOptionNumberUnassigned\r
+ EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType; // LoadOptionTypeBoot or LoadOptionTypeDriver\r
+ UINT32 Attributes; // Load Option Attributes\r
+ CHAR16 *Description; // Load Option Description\r
+ EFI_DEVICE_PATH_PROTOCOL *FilePath; // Load Option Device Path\r
+ UINT8 *OptionalData; // Load Option optional data to pass into image\r
+ UINT32 OptionalDataSize; // Load Option size of OptionalData\r
+ EFI_GUID VendorGuid;\r
\r
//\r
// Used at runtime\r
//\r
- EFI_STATUS Status; // Status returned from boot attempt gBS->StartImage ()\r
- CHAR16 *ExitData; // Exit data returned from gBS->StartImage () \r
- UINTN ExitDataSize; // Size of ExitData\r
+ EFI_STATUS Status; // Status returned from boot attempt gBS->StartImage ()\r
+ CHAR16 *ExitData; // Exit data returned from gBS->StartImage ()\r
+ UINTN ExitDataSize; // Size of ExitData\r
} EFI_BOOT_MANAGER_LOAD_OPTION;\r
\r
/**\r
Returns an array of load options based on the EFI variable\r
L"BootOrder"/L"DriverOrder" and the L"Boot####"/L"Driver####" variables impled by it.\r
- #### is the hex value of the UINT16 in each BootOrder/DriverOrder entry. \r
+ #### is the hex value of the UINT16 in each BootOrder/DriverOrder entry.\r
\r
@param LoadOptionCount Returns number of entries in the array.\r
@param LoadOptionType The type of the load option.\r
EFI_BOOT_MANAGER_LOAD_OPTION *\r
EFIAPI\r
EfiBootManagerGetLoadOptions (\r
- OUT UINTN *LoadOptionCount,\r
- IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE LoadOptionType\r
+ OUT UINTN *LoadOptionCount,\r
+ IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE LoadOptionType\r
);\r
\r
/**\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerInitializeLoadOption (\r
- IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *Option,\r
- IN UINTN OptionNumber,\r
- IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType,\r
- IN UINT32 Attributes,\r
- IN CHAR16 *Description,\r
- IN EFI_DEVICE_PATH_PROTOCOL *FilePath,\r
- IN UINT8 *OptionalData,\r
- IN UINT32 OptionalDataSize\r
+ IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *Option,\r
+ IN UINTN OptionNumber,\r
+ IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType,\r
+ IN UINT32 Attributes,\r
+ IN CHAR16 *Description,\r
+ IN EFI_DEVICE_PATH_PROTOCOL *FilePath,\r
+ IN UINT8 *OptionalData,\r
+ IN UINT32 OptionalDataSize\r
);\r
\r
/**\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerVariableToLoadOption (\r
- IN CHAR16 *VariableName,\r
- IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *LoadOption\r
+ IN CHAR16 *VariableName,\r
+ IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *LoadOption\r
);\r
\r
/**\r
Create the Boot#### or Driver#### variable from the load option.\r
- \r
+\r
@param LoadOption Pointer to the load option.\r
\r
@retval EFI_SUCCESS The variable was created.\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerLoadOptionToVariable (\r
- IN CONST EFI_BOOT_MANAGER_LOAD_OPTION *LoadOption\r
+ IN CONST EFI_BOOT_MANAGER_LOAD_OPTION *LoadOption\r
);\r
\r
/**\r
- This function will update the Boot####/Driver####/SysPrep#### and the \r
- BootOrder/DriverOrder/SysPrepOrder to add a new load option.\r
+ This function will register the new Boot####, Driver#### or SysPrep#### option.\r
+ After the *#### is updated, the *Order will also be updated.\r
+\r
+ @param Option Pointer to load option to add. If on input\r
+ Option->OptionNumber is LoadOptionNumberUnassigned,\r
+ then on output Option->OptionNumber is updated to\r
+ the number of the new Boot####,\r
+ Driver#### or SysPrep#### option.\r
+ @param Position Position of the new load option to put in the ****Order variable.\r
\r
- @param Option Pointer to load option to add.\r
- @param Position Position of the new load option to put in the BootOrder/DriverOrder/SysPrepOrder.\r
+ @retval EFI_SUCCESS The *#### have been successfully registered.\r
+ @retval EFI_INVALID_PARAMETER The option number exceeds 0xFFFF.\r
+ @retval EFI_ALREADY_STARTED The option number of Option is being used already.\r
+ Note: this API only adds new load option, no replacement support.\r
+ @retval EFI_OUT_OF_RESOURCES There is no free option number that can be used when the\r
+ option number specified in the Option is LoadOptionNumberUnassigned.\r
+ @return Status codes of gRT->SetVariable ().\r
\r
- @retval EFI_SUCCESS The load option has been successfully added.\r
- @retval Others Error status returned by RT->SetVariable.\r
**/\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerAddLoadOptionVariable (\r
- IN EFI_BOOT_MANAGER_LOAD_OPTION *Option,\r
- IN UINTN Position\r
+ IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *Option,\r
+ IN UINTN Position\r
);\r
\r
/**\r
Delete the load option according to the OptionNumber and OptionType.\r
- \r
+\r
Only the BootOrder/DriverOrder is updated to remove the reference of the OptionNumber.\r
- \r
+\r
@param OptionNumber Option number of the load option.\r
@param OptionType Type of the load option.\r
\r
);\r
\r
/**\r
- Sort the load options. The DriverOrder/BootOrder variables will be re-created to \r
+ Sort the load options. The DriverOrder/BootOrder variables will be re-created to\r
reflect the new order.\r
\r
@param OptionType The type of the load option.\r
VOID\r
EFIAPI\r
EfiBootManagerSortLoadOptionVariable (\r
- IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType,\r
- IN SORT_COMPARE CompareFunction\r
+ IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType,\r
+ IN SORT_COMPARE CompareFunction\r
);\r
\r
/**\r
Return the index of the load option in the load option array.\r
\r
- The function consider two load options are equal when the \r
+ The function consider two load options are equal when the\r
OptionType, Attributes, Description, FilePath and OptionalData are equal.\r
\r
@param Key Pointer to the load option to be found.\r
INTN\r
EFIAPI\r
EfiBootManagerFindLoadOption (\r
- IN CONST EFI_BOOT_MANAGER_LOAD_OPTION *Key,\r
- IN CONST EFI_BOOT_MANAGER_LOAD_OPTION *Array,\r
- IN UINTN Count\r
+ IN CONST EFI_BOOT_MANAGER_LOAD_OPTION *Key,\r
+ IN CONST EFI_BOOT_MANAGER_LOAD_OPTION *Array,\r
+ IN UINTN Count\r
);\r
\r
//\r
///\r
/// Specifies options about how the key will be processed.\r
///\r
- EFI_BOOT_KEY_DATA KeyData;\r
+ EFI_BOOT_KEY_DATA KeyData;\r
///\r
/// The CRC-32 which should match the CRC-32 of the entire EFI_LOAD_OPTION to\r
/// which BootOption refers. If the CRC-32s do not match this value, then this key\r
/// option is ignored.\r
///\r
- UINT32 BootOptionCrc;\r
+ UINT32 BootOptionCrc;\r
///\r
/// The Boot#### option which will be invoked if this key is pressed and the boot option\r
/// is active (LOAD_OPTION_ACTIVE is set).\r
///\r
- UINT16 BootOption;\r
+ UINT16 BootOption;\r
///\r
/// The key codes to compare against those returned by the\r
/// EFI_SIMPLE_TEXT_INPUT and EFI_SIMPLE_TEXT_INPUT_EX protocols.\r
/// The number of key codes (0-3) is specified by the EFI_KEY_CODE_COUNT field in KeyOptions.\r
///\r
- EFI_INPUT_KEY Keys[3];\r
- UINT16 OptionNumber;\r
+ EFI_INPUT_KEY Keys[3];\r
+ UINT16 OptionNumber;\r
} EFI_BOOT_MANAGER_KEY_OPTION;\r
#pragma pack()\r
\r
/**\r
Start the hot key service so that the key press can trigger the boot option.\r
\r
- @param HotkeyTriggered Return the waitable event and it will be signaled \r
+ @param HotkeyTriggered Return the waitable event and it will be signaled\r
when a valid hot key is pressed.\r
\r
@retval EFI_SUCCESS The hot key service is started.\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerStartHotkeyService (\r
- IN EFI_EVENT *HotkeyTriggered\r
+ IN EFI_EVENT *HotkeyTriggered\r
);\r
\r
//\r
// Modifier for EfiBootManagerAddKeyOptionVariable and EfiBootManagerDeleteKeyOptionVariable\r
//\r
-#define EFI_BOOT_MANAGER_SHIFT_PRESSED 0x00000001\r
-#define EFI_BOOT_MANAGER_CONTROL_PRESSED 0x00000002\r
-#define EFI_BOOT_MANAGER_ALT_PRESSED 0x00000004\r
-#define EFI_BOOT_MANAGER_LOGO_PRESSED 0x00000008\r
-#define EFI_BOOT_MANAGER_MENU_KEY_PRESSED 0x00000010\r
-#define EFI_BOOT_MANAGER_SYS_REQ_PRESSED 0x00000020\r
+#define EFI_BOOT_MANAGER_SHIFT_PRESSED 0x00000001\r
+#define EFI_BOOT_MANAGER_CONTROL_PRESSED 0x00000002\r
+#define EFI_BOOT_MANAGER_ALT_PRESSED 0x00000004\r
+#define EFI_BOOT_MANAGER_LOGO_PRESSED 0x00000008\r
+#define EFI_BOOT_MANAGER_MENU_KEY_PRESSED 0x00000010\r
+#define EFI_BOOT_MANAGER_SYS_REQ_PRESSED 0x00000020\r
\r
/**\r
Add the key option.\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerAddKeyOptionVariable (\r
- OUT EFI_BOOT_MANAGER_KEY_OPTION *AddedOption, OPTIONAL\r
- IN UINT16 BootOptionNumber,\r
- IN UINT32 Modifier,\r
+ OUT EFI_BOOT_MANAGER_KEY_OPTION *AddedOption OPTIONAL,\r
+ IN UINT16 BootOptionNumber,\r
+ IN UINT32 Modifier,\r
...\r
);\r
\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerDeleteKeyOptionVariable (\r
- IN EFI_BOOT_MANAGER_KEY_OPTION *DeletedOption, OPTIONAL\r
- IN UINT32 Modifier,\r
+ IN EFI_BOOT_MANAGER_KEY_OPTION *DeletedOption OPTIONAL,\r
+ IN UINT32 Modifier,\r
...\r
);\r
\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerRegisterContinueKeyOption (\r
- IN UINT32 Modifier,\r
+ IN UINT32 Modifier,\r
...\r
);\r
\r
EfiBootManagerHotkeyBoot (\r
VOID\r
);\r
+\r
//\r
// Boot Manager boot library functions.\r
//\r
3. Non-BlockIo SimpleFileSystem - The boot option points to a device supporting\r
SimpleFileSystem Protocol, but not supporting BlockIo\r
protocol.\r
- 4. LoadFile - The boot option points to the media supporting \r
+ 4. LoadFile - The boot option points to the media supporting\r
LoadFile protocol.\r
Reference: UEFI Spec chapter 3.3 Boot Option Variables Default Boot Behavior\r
\r
Attempt to boot the EFI boot option. This routine sets L"BootCurent" and\r
signals the EFI ready to boot event. If the device path for the option starts\r
with a BBS device path a legacy boot is attempted. Short form device paths are\r
- also supported via this rountine. A device path starting with \r
+ also supported via this rountine. A device path starting with\r
MEDIA_HARDDRIVE_DP, MSG_USB_WWID_DP, MSG_USB_CLASS_DP gets expaned out\r
- to find the first device that matches. If the BootOption Device Path \r
+ to find the first device that matches. If the BootOption Device Path\r
fails the removable media boot algorithm is attempted (\EFI\BOOTIA32.EFI,\r
\EFI\BOOTX64.EFI,... only one file type is tried per processor type)\r
\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerGetBootManagerMenu (\r
- EFI_BOOT_MANAGER_LOAD_OPTION *BootOption\r
+ EFI_BOOT_MANAGER_LOAD_OPTION *BootOption\r
);\r
\r
+/**\r
+ Get the next possible full path pointing to the load option.\r
+ The routine doesn't guarantee the returned full path points to an existing\r
+ file, and it also doesn't guarantee the existing file is a valid load option.\r
+ BmGetNextLoadOptionBuffer() guarantees.\r
+\r
+ @param FilePath The device path pointing to a load option.\r
+ It could be a short-form device path.\r
+ @param FullPath The full path returned by the routine in last call.\r
+ Set to NULL in first call.\r
+\r
+ @return The next possible full path pointing to the load option.\r
+ Caller is responsible to free the memory.\r
+**/\r
+EFI_DEVICE_PATH_PROTOCOL *\r
+EFIAPI\r
+EfiBootManagerGetNextLoadOptionDevicePath (\r
+ IN EFI_DEVICE_PATH_PROTOCOL *FilePath,\r
+ IN EFI_DEVICE_PATH_PROTOCOL *FullPath\r
+ );\r
\r
/**\r
Get the load option by its device path.\r
VOID *\r
EFIAPI\r
EfiBootManagerGetLoadOptionBuffer (\r
- IN EFI_DEVICE_PATH_PROTOCOL *FilePath,\r
- OUT EFI_DEVICE_PATH_PROTOCOL **FullPath,\r
- OUT UINTN *FileSize\r
+ IN EFI_DEVICE_PATH_PROTOCOL *FilePath,\r
+ OUT EFI_DEVICE_PATH_PROTOCOL **FullPath,\r
+ OUT UINTN *FileSize\r
);\r
\r
/**\r
- The function enumerates all the legacy boot options, creates them and \r
+ The function enumerates all the legacy boot options, creates them and\r
registers them in the BootOrder variable.\r
**/\r
typedef\r
VOID\r
-(EFIAPI *EFI_BOOT_MANAGER_REFRESH_LEGACY_BOOT_OPTION) (\r
+(EFIAPI *EFI_BOOT_MANAGER_REFRESH_LEGACY_BOOT_OPTION)(\r
VOID\r
);\r
\r
**/\r
typedef\r
VOID\r
-(EFIAPI *EFI_BOOT_MANAGER_LEGACY_BOOT) (\r
+(EFIAPI *EFI_BOOT_MANAGER_LEGACY_BOOT)(\r
IN EFI_BOOT_MANAGER_LOAD_OPTION *BootOption\r
);\r
\r
VOID\r
EFIAPI\r
EfiBootManagerRegisterLegacyBootSupport (\r
- EFI_BOOT_MANAGER_REFRESH_LEGACY_BOOT_OPTION RefreshLegacyBootOption,\r
- EFI_BOOT_MANAGER_LEGACY_BOOT LegacyBoot\r
+ EFI_BOOT_MANAGER_REFRESH_LEGACY_BOOT_OPTION RefreshLegacyBootOption,\r
+ EFI_BOOT_MANAGER_LEGACY_BOOT LegacyBoot\r
);\r
\r
/**\r
**/\r
typedef\r
CHAR16 *\r
-(EFIAPI *EFI_BOOT_MANAGER_BOOT_DESCRIPTION_HANDLER) (\r
+(EFIAPI *EFI_BOOT_MANAGER_BOOT_DESCRIPTION_HANDLER)(\r
IN EFI_HANDLE Handle,\r
IN CONST CHAR16 *DefaultDescription\r
);\r
@retval EFI_OUT_OF_RESOURCES There is no resource to create new handles.\r
@retval EFI_NOT_FOUND Create the handle associate with one device path\r
node failed.\r
- @retval EFI_SECURITY_VIOLATION The user has no permission to start UEFI device \r
+ @retval EFI_SECURITY_VIOLATION The user has no permission to start UEFI device\r
drivers on the DevicePath.\r
**/\r
EFI_STATUS\r
);\r
\r
/**\r
- This function will disconnect all current system handles. \r
- \r
+ This function will disconnect all current system handles.\r
+\r
gBS->DisconnectController() is invoked for each handle exists in system handle buffer.\r
If handle is a bus type handle, all childrens also are disconnected recursively by\r
gBS->DisconnectController().\r
VOID\r
);\r
\r
-\r
//\r
// Boot Manager console library functions\r
//\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerConnectConsoleVariable (\r
- IN CONSOLE_TYPE ConsoleType\r
+ IN CONSOLE_TYPE ConsoleType\r
);\r
\r
/**\r
- Query all the children of VideoController and return the device paths of all the \r
+ Query all the children of VideoController and return the device paths of all the\r
children that support GraphicsOutput protocol.\r
\r
@param VideoController PCI handle of video controller.\r
EFI_DEVICE_PATH_PROTOCOL *\r
EFIAPI\r
EfiBootManagerGetGopDevicePath (\r
- IN EFI_HANDLE VideoController\r
+ IN EFI_HANDLE VideoController\r
);\r
\r
/**\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerConnectVideoController (\r
- EFI_HANDLE VideoController OPTIONAL\r
+ EFI_HANDLE VideoController OPTIONAL\r
);\r
\r
//\r
//\r
\r
typedef struct {\r
- EFI_DRIVER_HEALTH_PROTOCOL *DriverHealth;\r
+ EFI_DRIVER_HEALTH_PROTOCOL *DriverHealth;\r
\r
///\r
/// Driver relative handles\r
///\r
- EFI_HANDLE DriverHealthHandle;\r
- EFI_HANDLE ControllerHandle;\r
- EFI_HANDLE ChildHandle;\r
+ EFI_HANDLE DriverHealthHandle;\r
+ EFI_HANDLE ControllerHandle;\r
+ EFI_HANDLE ChildHandle;\r
\r
///\r
- /// Driver health messages of the specify Driver \r
+ /// Driver health messages of the specify Driver\r
///\r
- EFI_DRIVER_HEALTH_HII_MESSAGE *MessageList;\r
+ EFI_DRIVER_HEALTH_HII_MESSAGE *MessageList;\r
\r
///\r
/// HII relative handles\r
///\r
- EFI_HII_HANDLE HiiHandle;\r
+ EFI_HII_HANDLE HiiHandle;\r
\r
///\r
/// Driver Health status\r
///\r
- EFI_DRIVER_HEALTH_STATUS HealthStatus;\r
+ EFI_DRIVER_HEALTH_STATUS HealthStatus;\r
} EFI_BOOT_MANAGER_DRIVER_HEALTH_INFO;\r
\r
/**\r
EFI_BOOT_MANAGER_DRIVER_HEALTH_INFO *\r
EFIAPI\r
EfiBootManagerGetDriverHealthInfo (\r
- UINTN *Count\r
+ UINTN *Count\r
);\r
\r
/**\r
\r
@param LoadOption Pointer to the load option.\r
\r
- @retval EFI_INVALID_PARAMETER The load option type is invalid, \r
+ @retval EFI_INVALID_PARAMETER The load option type is invalid,\r
or the load option file path doesn't point to a valid file.\r
@retval EFI_UNSUPPORTED The load option type is of LoadOptionTypeBoot.\r
@retval EFI_SUCCESS The load option is inactive, or successfully loaded and executed.\r
EFI_STATUS\r
EFIAPI\r
EfiBootManagerProcessLoadOption (\r
- EFI_BOOT_MANAGER_LOAD_OPTION *LoadOption\r
+ EFI_BOOT_MANAGER_LOAD_OPTION *LoadOption\r
);\r
\r
/**\r
BOOLEAN\r
EFIAPI\r
EfiBootManagerIsValidLoadOptionVariableName (\r
- IN CHAR16 *VariableName,\r
- OUT EFI_BOOT_MANAGER_LOAD_OPTION_TYPE *OptionType OPTIONAL,\r
- OUT UINT16 *OptionNumber OPTIONAL\r
+ IN CHAR16 *VariableName,\r
+ OUT EFI_BOOT_MANAGER_LOAD_OPTION_TYPE *OptionType OPTIONAL,\r
+ OUT UINT16 *OptionNumber OPTIONAL\r
+ );\r
+\r
+/**\r
+ Dispatch the deferred images that are returned from all DeferredImageLoad instances.\r
+\r
+ @retval EFI_SUCCESS At least one deferred image is loaded successfully and started.\r
+ @retval EFI_NOT_FOUND There is no deferred image.\r
+ @retval EFI_ACCESS_DENIED There are deferred images but all of them are failed to load.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+EfiBootManagerDispatchDeferredImages (\r
+ VOID\r
);\r
\r
#endif\r