#include "InternalBm.h"
#include <Library/VariablePolicyHelperLib.h>

Data Structures
struct	BM_COLLECT_LOAD_OPTIONS_PARAM

Functions
VOID	BmForEachVariable (BM_VARIABLE_VISITOR Visitor, VOID *Context)

EFI_STATUS	BmGetFreeOptionNumber (IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE LoadOptionType, OUT UINT16 *FreeOptionNumber)

EFI_STATUS EFIAPI	EfiBootManagerLoadOptionToVariable (IN CONST EFI_BOOT_MANAGER_LOAD_OPTION *Option)

EFI_STATUS	BmAddOptionNumberToOrderVariable (IN CHAR16 *OptionOrderName, IN UINT16 OptionNumber, IN UINTN Position)

EFI_STATUS EFIAPI	EfiBootManagerAddLoadOptionVariable (IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *Option, IN UINTN Position)

VOID EFIAPI	EfiBootManagerSortLoadOptionVariable (EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType, SORT_COMPARE CompareFunction)

EFI_STATUS EFIAPI	EfiBootManagerInitializeLoadOption (IN OUT EFI_BOOT_MANAGER_LOAD_OPTION Option, IN UINTN OptionNumber, IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType, IN UINT32 Attributes, IN CHAR16 Description, IN EFI_DEVICE_PATH_PROTOCOL FilePath, IN UINT8 OptionalData OPTIONAL, IN UINT32 OptionalDataSize)

INTN EFIAPI	EfiBootManagerFindLoadOption (IN CONST EFI_BOOT_MANAGER_LOAD_OPTION Key, IN CONST EFI_BOOT_MANAGER_LOAD_OPTION Array, IN UINTN Count)

EFI_STATUS EFIAPI	EfiBootManagerDeleteLoadOptionVariable (IN UINTN OptionNumber, IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType)

UINTN	BmGetDevicePathSizeEx (IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, IN UINTN MaxSize)

UINTN	BmStrSizeEx (IN CONST CHAR16 *String, IN UINTN MaxStringLen)

BOOLEAN	BmValidateOption (UINT8 *Variable, UINTN VariableSize)

BOOLEAN EFIAPI	EfiBootManagerIsValidLoadOptionVariableName (IN CHAR16 VariableName, OUT EFI_BOOT_MANAGER_LOAD_OPTION_TYPE OptionType OPTIONAL, OUT UINT16 *OptionNumber OPTIONAL)

EFI_STATUS EFIAPI	EfiBootManagerVariableToLoadOptionEx (IN CHAR16 VariableName, IN EFI_GUID VendorGuid, IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *Option)

EFI_STATUS EFIAPI	EfiBootManagerVariableToLoadOption (IN CHAR16 VariableName, IN OUT EFI_BOOT_MANAGER_LOAD_OPTION Option)

VOID	BmCollectLoadOptions (IN CHAR16 Name, IN EFI_GUID Guid, IN VOID *Context)

EFI_BOOT_MANAGER_LOAD_OPTION *EFIAPI	EfiBootManagerGetLoadOptions (OUT UINTN *OptionCount, IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE LoadOptionType)

EFI_STATUS EFIAPI	EfiBootManagerFreeLoadOption (IN EFI_BOOT_MANAGER_LOAD_OPTION *LoadOption)

EFI_STATUS EFIAPI	EfiBootManagerFreeLoadOptions (IN EFI_BOOT_MANAGER_LOAD_OPTION *Option, IN UINTN OptionCount)

BOOLEAN	BmIsLoadOptionPeHeaderValid (IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE Type, IN VOID *FileBuffer, IN UINTN FileSize)

VOID *	BmGetNextLoadOptionBuffer (IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE Type, IN EFI_DEVICE_PATH_PROTOCOL FilePath, OUT EFI_DEVICE_PATH_PROTOCOL FullPath, OUT UINTN FileSize)

EFI_STATUS EFIAPI	EfiBootManagerProcessLoadOption (IN EFI_BOOT_MANAGER_LOAD_OPTION *LoadOption)

Variables
GLOBAL_REMOVE_IF_UNREFERENCED CHAR16 *	mBmLoadOptionName []

GLOBAL_REMOVE_IF_UNREFERENCED CHAR16 *	mBmLoadOptionOrderName []

Detailed Description

Load option library functions which relate with creating and processing load options.

Copyright (c) 2011 - 2019, Intel Corporation. All rights reserved.
(C) Copyright 2015-2018 Hewlett Packard Enterprise Development LP
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file BmLoadOption.c.

Function Documentation

◆ BmAddOptionNumberToOrderVariable()

EFI_STATUS BmAddOptionNumberToOrderVariable	(	IN CHAR16 *	OptionOrderName,
		IN UINT16	OptionNumber,
		IN UINTN	Position
	)

Update order variable .

Parameters

OptionOrderName	Order variable name which need to be updated.
OptionNumber	Option number for the new option.
Position	Position of the new load option to put in the ****Order variable.

Return values

EFI_SUCCESS	The boot#### or driver#### have been successfully registered.
EFI_ALREADY_STARTED	The option number of Option is being used already.
EFI_STATUS	Return the status of gRT->SetVariable ().

Definition at line 290 of file BmLoadOption.c.

◆ BmCollectLoadOptions()

VOID BmCollectLoadOptions	(	IN CHAR16 *	Name,
		IN EFI_GUID *	Guid,
		IN VOID *	Context
	)

Visitor function to collect the Platform Recovery load options or OS Recovery load options from NV storage.

Parameters

Name	Variable name.
Guid	Variable GUID.
Context	The same context passed to BmForEachVariable.

Definition at line 1022 of file BmLoadOption.c.

◆ BmForEachVariable()

VOID BmForEachVariable	(	BM_VARIABLE_VISITOR	Visitor,
		VOID *	Context
	)

Call Visitor function for each variable in variable storage.

Parameters

Visitor	Visitor function.
Context	The context passed to Visitor function.

Definition at line 37 of file BmLoadOption.c.

◆ BmGetDevicePathSizeEx()

UINTN BmGetDevicePathSizeEx	(	IN CONST EFI_DEVICE_PATH_PROTOCOL *	DevicePath,
		IN UINTN	MaxSize
	)

Returns the size of a device path in bytes.

This function returns the size, in bytes, of the device path data structure specified by DevicePath including the end of device path node. If DevicePath is NULL, then 0 is returned. If the length of the device path is bigger than MaxSize, also return 0 to indicate this is an invalidate device path.

Parameters

DevicePath	A pointer to a device path data structure.
MaxSize	Max valid device path size. If big than this size, return error.

Return values

0	An invalid device path.
Others	The size of a device path in bytes.

Definition at line 656 of file BmLoadOption.c.

◆ BmGetFreeOptionNumber()

EFI_STATUS BmGetFreeOptionNumber	(	IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE	LoadOptionType,
		OUT UINT16 *	FreeOptionNumber
	)

Get the Option Number that wasn't used.

Parameters

LoadOptionType	The load option type.
FreeOptionNumber	Return the minimal free option number.

Return values

EFI_SUCCESS	The option number is found and will be returned.
EFI_OUT_OF_RESOURCES	There is no free option number that can be used.
EFI_INVALID_PARAMETER	FreeOptionNumber is NULL

Definition at line 85 of file BmLoadOption.c.

◆ BmGetNextLoadOptionBuffer()

VOID * BmGetNextLoadOptionBuffer	(	IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE	Type,
		IN EFI_DEVICE_PATH_PROTOCOL *	FilePath,
		OUT EFI_DEVICE_PATH_PROTOCOL **	FullPath,
		OUT UINTN *	FileSize
	)

Return the next matched load option buffer. The routine keeps calling BmGetNextLoadOptionDevicePath() until a valid load option is read.

Parameters

Type	The load option type. It's used to check whether the load option is valid. When it's LoadOptionTypeMax, the routine only guarantees the load option is a valid PE image but doesn't guarantee the PE's subsystem type is valid.
FilePath	The device path pointing to a load option. It could be a short-form device path.
FullPath	Return the next full device path of the load option after short-form device path expanding. Caller is responsible to free it. NULL to return the first matched full device path.
FileSize	Return the load option size.

Returns: The load option buffer. Caller is responsible to free the memory.

Definition at line 1313 of file BmLoadOption.c.

◆ BmIsLoadOptionPeHeaderValid()

BOOLEAN BmIsLoadOptionPeHeaderValid	(	IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE	Type,
		IN VOID *	FileBuffer,
		IN UINTN	FileSize
	)

Return whether the PE header of the load option is valid or not.

Parameters

[in]	Type	The load option type. It's used to check whether the load option is valid. When it's LoadOptionTypeMax, the routine only guarantees the load option is a valid PE image but doesn't guarantee the PE's subsystem type is valid.
[in]	FileBuffer	The PE file buffer of the load option.
[in]	FileSize	The size of the load option file.

Return values

TRUE	The PE header of the load option is valid.
FALSE	The PE header of the load option is not valid.

Definition at line 1231 of file BmLoadOption.c.

◆ BmStrSizeEx()

UINTN BmStrSizeEx	(	IN CONST CHAR16 *	String,
		IN UINTN	MaxStringLen
	)

Returns the length of a Null-terminated Unicode string. If the length is bigger than MaxStringLen, return length 0 to indicate that this is an invalidate string.

This function returns the number of Unicode characters in the Null-terminated Unicode string specified by String.

If String is NULL, then ASSERT(). If String is not aligned on a 16-bit boundary, then ASSERT().

Parameters

String	A pointer to a Null-terminated Unicode string.
MaxStringLen	Max string len in this string.

Return values

0	An invalid string.
Others	The length of String.

Definition at line 713 of file BmLoadOption.c.

◆ BmValidateOption()

BOOLEAN BmValidateOption	(	UINT8 *	Variable,
		UINTN	VariableSize
	)

Validate the Boot####, Driver####, SysPrep#### and PlatformRecovery#### variable (VendorGuid/Name)

Parameters

Variable	The variable data.
VariableSize	The variable size.

Return values

TRUE	The variable data is correct.
FALSE	The variable data is corrupted.

Definition at line 745 of file BmLoadOption.c.

◆ EfiBootManagerAddLoadOptionVariable()

EFI_STATUS EFIAPI EfiBootManagerAddLoadOptionVariable	(	IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *	Option,
		IN UINTN	Position
	)

This function will register the new Boot####, Driver#### or SysPrep#### option. After the *#### is updated, the *Order will also be updated.

Parameters

Option	Pointer to load option to add. If on input Option->OptionNumber is LoadOptionNumberUnassigned, then on output Option->OptionNumber is updated to the number of the new Boot####, Driver#### or SysPrep#### option.
Position	Position of the new load option to put in the ****Order variable.

Return values

EFI_SUCCESS	The *#### have been successfully registered.
EFI_INVALID_PARAMETER	The option number exceeds 0xFFFF.
EFI_ALREADY_STARTED	The option number of Option is being used already. Note: this API only adds new load option, no replacement support.
EFI_OUT_OF_RESOURCES	There is no free option number that can be used when the option number specified in the Option is LoadOptionNumberUnassigned.

Returns: Status codes of gRT->SetVariable ().

Definition at line 367 of file BmLoadOption.c.

◆ EfiBootManagerDeleteLoadOptionVariable()

EFI_STATUS EFIAPI EfiBootManagerDeleteLoadOptionVariable	(	IN UINTN	OptionNumber,
		IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE	OptionType
	)

Delete the load option.

Parameters

OptionNumber	Indicate the option number of load option
OptionType	Indicate the type of load option

Return values

EFI_INVALID_PARAMETER	OptionType or OptionNumber is invalid.
EFI_NOT_FOUND	The load option cannot be found
EFI_SUCCESS	The load option was deleted
others	Status of RT->SetVariable()

Definition at line 584 of file BmLoadOption.c.

◆ EfiBootManagerFindLoadOption()

INTN EFIAPI EfiBootManagerFindLoadOption	(	IN CONST EFI_BOOT_MANAGER_LOAD_OPTION *	Key,
		IN CONST EFI_BOOT_MANAGER_LOAD_OPTION *	Array,
		IN UINTN	Count
	)

Return the index of the load option in the load option array.

The function consider two load options are equal when the OptionType, Attributes, Description, FilePath and OptionalData are equal.

Parameters

Key	Pointer to the load option to be found.
Array	Pointer to the array of load options to be found.
Count	Number of entries in the Array.

Return values

-1	Key wasn't found in the Array.
0	~ Count-1 The index of the Key in the Array.

Definition at line 548 of file BmLoadOption.c.

◆ EfiBootManagerFreeLoadOption()

EFI_STATUS EFIAPI EfiBootManagerFreeLoadOption ( IN EFI_BOOT_MANAGER_LOAD_OPTION * LoadOption )

Free an EFI_BOOT_MANGER_LOAD_OPTION entry that was allocate by the library.

Parameters

LoadOption Pointer to boot option to Free.

Returns: EFI_SUCCESS BootOption was freed; EFI_NOT_FOUND BootOption == NULL

Definition at line 1160 of file BmLoadOption.c.

◆ EfiBootManagerFreeLoadOptions()

EFI_STATUS EFIAPI EfiBootManagerFreeLoadOptions	(	IN EFI_BOOT_MANAGER_LOAD_OPTION *	Option,
		IN UINTN	OptionCount
	)

Free an EFI_BOOT_MANGER_LOAD_OPTION array that was allocated by EfiBootManagerGetLoadOptions().

Parameters

Option	Pointer to boot option array to free.
OptionCount	Number of array entries in BootOption

Returns: EFI_SUCCESS BootOption was freed; EFI_NOT_FOUND BootOption == NULL

Definition at line 1196 of file BmLoadOption.c.

◆ EfiBootManagerGetLoadOptions()

EFI_BOOT_MANAGER_LOAD_OPTION *EFIAPI EfiBootManagerGetLoadOptions	(	OUT UINTN *	OptionCount,
		IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE	LoadOptionType
	)

Returns an array of load options based on the EFI variable L"BootOrder"/L"DriverOrder" and the L"Boot####"/L"Driver####" variables impled by it.

is the hex value of the UINT16 in each BootOrder/DriverOrder entry.

Parameters

LoadOptionCount	Returns number of entries in the array.
LoadOptionType	The type of the load option.

Return values

NULL	No load options exist.
!NULL	Array of load option entries.

Definition at line 1078 of file BmLoadOption.c.

◆ EfiBootManagerInitializeLoadOption()

EFI_STATUS EFIAPI EfiBootManagerInitializeLoadOption	(	IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *	Option,
		IN UINTN	OptionNumber,
		IN EFI_BOOT_MANAGER_LOAD_OPTION_TYPE	OptionType,
		IN UINT32	Attributes,
		IN CHAR16 *	Description,
		IN EFI_DEVICE_PATH_PROTOCOL *	FilePath,
		IN UINT8 *OptionalData	OPTIONAL,
		IN UINT32	OptionalDataSize
	)

Initialize a load option.

Parameters

Option	Pointer to the load option to be initialized.
OptionNumber	Option number of the load option.
OptionType	Type of the load option.
Attributes	Attributes of the load option.
Description	Description of the load option.
FilePath	Device path of the load option.
OptionalData	Optional data of the load option.
OptionalDataSize	Size of the optional data of the load option.

Return values

EFI_SUCCESS	The load option was initialized successfully.
EFI_INVALID_PARAMETER	Option, Description or FilePath is NULL.

Definition at line 494 of file BmLoadOption.c.

◆ EfiBootManagerIsValidLoadOptionVariableName()

BOOLEAN EFIAPI EfiBootManagerIsValidLoadOptionVariableName	(	IN CHAR16 *	VariableName,
		OUT EFI_BOOT_MANAGER_LOAD_OPTION_TYPE *OptionType	OPTIONAL,
		OUT UINT16 *OptionNumber	OPTIONAL
	)

Check whether the VariableName is a valid load option variable name and return the load option type and option number.

Parameters

VariableName	The name of the load option variable.
OptionType	Return the load option type.
OptionNumber	Return the load option number.

Return values

TRUE	The variable name is valid; The load option type and load option number is returned.
FALSE	The variable name is NOT valid.

Definition at line 808 of file BmLoadOption.c.

◆ EfiBootManagerLoadOptionToVariable()

EFI_STATUS EFIAPI EfiBootManagerLoadOptionToVariable ( IN CONST EFI_BOOT_MANAGER_LOAD_OPTION * Option )

Create the Boot####, Driver####, SysPrep####, PlatformRecovery#### variable from the load option.

Parameters

LoadOption Pointer to the load option.

Return values

EFI_SUCCESS	The variable was created.
Others	Error status returned by RT->SetVariable.

Definition at line 170 of file BmLoadOption.c.

◆ EfiBootManagerProcessLoadOption()

EFI_STATUS EFIAPI EfiBootManagerProcessLoadOption ( IN EFI_BOOT_MANAGER_LOAD_OPTION * LoadOption )

Process (load and execute) the load option.

Parameters

LoadOption Pointer to the load option.

Return values

EFI_INVALID_PARAMETER	The load option type is invalid, or the load option file path doesn't point to a valid file.
EFI_UNSUPPORTED	The load option type is of LoadOptionTypeBoot.
EFI_SUCCESS	The load option is inactive, or successfully loaded and executed.

Definition at line 1391 of file BmLoadOption.c.

◆ EfiBootManagerSortLoadOptionVariable()

VOID EFIAPI EfiBootManagerSortLoadOptionVariable	(	EFI_BOOT_MANAGER_LOAD_OPTION_TYPE	OptionType,
		SORT_COMPARE	CompareFunction
	)

Sort the load option. The DriverOrder or BootOrder will be re-created to reflect the new order.

Parameters

OptionType	Load option type
CompareFunction	The comparator

Definition at line 429 of file BmLoadOption.c.

◆ EfiBootManagerVariableToLoadOption()

EFI_STATUS EFIAPI EfiBootManagerVariableToLoadOption	(	IN CHAR16 *	VariableName,
		IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *	Option
	)

Build the Boot#### or Driver#### option from the VariableName.

Parameters

VariableName	EFI Variable name indicate if it is Boot#### or Driver####
Option	Return the Boot#### or Driver#### option.

Return values

EFI_SUCCESS	Get the option just been created
EFI_NOT_FOUND	Failed to get the new option

Definition at line 998 of file BmLoadOption.c.

◆ EfiBootManagerVariableToLoadOptionEx()

EFI_STATUS EFIAPI EfiBootManagerVariableToLoadOptionEx	(	IN CHAR16 *	VariableName,
		IN EFI_GUID *	VendorGuid,
		IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *	Option
	)

Build the Boot#### or Driver#### option from the VariableName.

Parameters

VariableName	Variable name of the load option
VendorGuid	Variable GUID of the load option
Option	Return the load option.

Return values

EFI_SUCCESS	Get the option just been created
EFI_NOT_FOUND	Failed to get the new option

Definition at line 890 of file BmLoadOption.c.

Variable Documentation

◆ mBmLoadOptionName

GLOBAL_REMOVE_IF_UNREFERENCED CHAR16* mBmLoadOptionName[]

Initial value:

= {
  L"Driver",
  L"SysPrep",
  L"Boot",
  L"PlatformRecovery"
}

Definition at line 15 of file BmLoadOption.c.

◆ mBmLoadOptionOrderName

GLOBAL_REMOVE_IF_UNREFERENCED CHAR16* mBmLoadOptionOrderName[]

Initial value:

= {
  EFI_DRIVER_ORDER_VARIABLE_NAME,
  EFI_SYS_PREP_ORDER_VARIABLE_NAME,
  EFI_BOOT_ORDER_VARIABLE_NAME,
  NULL    
}

Definition at line 23 of file BmLoadOption.c.

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ BmAddOptionNumberToOrderVariable()

◆ BmCollectLoadOptions()

◆ BmForEachVariable()

◆ BmGetDevicePathSizeEx()

◆ BmGetFreeOptionNumber()

◆ BmGetNextLoadOptionBuffer()

◆ BmIsLoadOptionPeHeaderValid()

◆ BmStrSizeEx()

◆ BmValidateOption()

◆ EfiBootManagerAddLoadOptionVariable()

◆ EfiBootManagerDeleteLoadOptionVariable()

◆ EfiBootManagerFindLoadOption()

◆ EfiBootManagerFreeLoadOption()

◆ EfiBootManagerFreeLoadOptions()

◆ EfiBootManagerGetLoadOptions()

is the hex value of the UINT16 in each BootOrder/DriverOrder entry.

◆ EfiBootManagerInitializeLoadOption()

◆ EfiBootManagerIsValidLoadOptionVariableName()

◆ EfiBootManagerLoadOptionToVariable()

◆ EfiBootManagerProcessLoadOption()

◆ EfiBootManagerSortLoadOptionVariable()

◆ EfiBootManagerVariableToLoadOption()

◆ EfiBootManagerVariableToLoadOptionEx()

Variable Documentation

◆ mBmLoadOptionName

◆ mBmLoadOptionOrderName