#include <Library/QemuFwCfgLib.h>
#include <Library/DebugLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/UefiBootManagerLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/UefiRuntimeServicesTableLib.h>
#include <Library/BaseLib.h>
#include <Library/PrintLib.h>
#include <Library/DevicePathLib.h>
#include <Library/QemuBootOrderLib.h>
#include <Library/BaseMemoryLib.h>
#include <Guid/GlobalVariable.h>
#include <Guid/VirtioMmioTransport.h>
#include "ExtraRootBusMap.h"

Data Structures
struct	SUBSTRING

struct	BOOT_ORDER

struct	ACTIVE_OPTION

struct	OFW_NODE

union	VIRTIO_MMIO_BASE_ADDRESS

Macros
#define	TRANSLATION_OUTPUT_SIZE 0x100

#define	BRIDGE_TRANSLATION_OUTPUT_SIZE 0x40

#define	REQUIRED_PCI_OFW_NODES 2

#define	REQUIRED_MMIO_OFW_NODES 1

#define	EXAMINED_OFW_NODES 6

Functions
STATIC BOOLEAN	IsAlnum (IN CHAR8 Chr)

STATIC BOOLEAN	IsDriverNamePunct (IN CHAR8 Chr)

STATIC BOOLEAN	IsPrintNotDelim (IN CHAR8 Chr)

STATIC BOOLEAN	SubstringEq (IN SUBSTRING Substring, IN CONST CHAR8 *String)

STATIC RETURN_STATUS	ParseUnitAddressHexList (IN SUBSTRING UnitAddress, OUT UINT64 Result, IN OUT UINTN NumResults)

STATIC RETURN_STATUS	BootOrderAppend (IN OUT BOOT_ORDER BootOrder, IN OUT ACTIVE_OPTION ActiveOption)

STATIC RETURN_STATUS	CollectActiveOptions (IN CONST EFI_BOOT_MANAGER_LOAD_OPTION BootOptions, IN UINTN BootOptionCount, OUT ACTIVE_OPTION ActiveOption, OUT UINTN Count)

STATIC RETURN_STATUS	ParseOfwNode (IN OUT CONST CHAR8 *Ptr, OUT OFW_NODE OfwNode, OUT BOOLEAN *IsFinal)

STATIC RETURN_STATUS	TranslatePciOfwNodes (IN CONST OFW_NODE OfwNode, IN UINTN NumNodes, IN CONST EXTRA_ROOT_BUS_MAP ExtraPciRoots, OUT CHAR16 Translated, IN OUT UINTN TranslatedSize)

STATIC RETURN_STATUS	TranslateMmioOfwNodes (IN CONST OFW_NODE OfwNode, IN UINTN NumNodes, OUT CHAR16 Translated, IN OUT UINTN *TranslatedSize)

STATIC RETURN_STATUS	TranslateOfwNodes (IN CONST OFW_NODE OfwNode, IN UINTN NumNodes, IN CONST EXTRA_ROOT_BUS_MAP ExtraPciRoots, OUT CHAR16 Translated, IN OUT UINTN TranslatedSize)

STATIC RETURN_STATUS	TranslateOfwPath (IN OUT CONST CHAR8 *Ptr, IN CONST EXTRA_ROOT_BUS_MAP ExtraPciRoots, OUT CHAR16 Translated, IN OUT UINTN TranslatedSize)

RETURN_STATUS EFIAPI	ConnectDevicesFromQemu (VOID)

VOID EFIAPI	StoreQemuBootOrder (VOID)

STATIC BOOLEAN	Match (IN CONST CHAR16 Translated, IN UINTN TranslatedLength, IN EFI_DEVICE_PATH_PROTOCOL DevicePath)

STATIC RETURN_STATUS	BootOrderComplete (IN OUT BOOT_ORDER BootOrder, IN OUT ACTIVE_OPTION ActiveOption, IN UINTN ActiveCount)

STATIC VOID	PruneBootVariables (IN CONST ACTIVE_OPTION *ActiveOption, IN UINTN ActiveCount)

RETURN_STATUS EFIAPI	SetBootOrderFromQemu (VOID)

UINT16 EFIAPI	GetFrontPageTimeoutFromQemu (VOID)

Detailed Description

Rewrite the BootOrder NvVar based on QEMU's "bootorder" fw_cfg file.

SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file QemuBootOrderLib.c.

Macro Definition Documentation

◆ BRIDGE_TRANSLATION_OUTPUT_SIZE

#define BRIDGE_TRANSLATION_OUTPUT_SIZE 0x40

Output buffer size for OpenFirmware to UEFI device path fragment translation, in CHAR16's, for a sequence of PCI bridges.

Definition at line 35 of file QemuBootOrderLib.c.

◆ EXAMINED_OFW_NODES

#define EXAMINED_OFW_NODES 6

Definition at line 42 of file QemuBootOrderLib.c.

◆ REQUIRED_MMIO_OFW_NODES

#define REQUIRED_MMIO_OFW_NODES 1

Definition at line 41 of file QemuBootOrderLib.c.

◆ REQUIRED_PCI_OFW_NODES

#define REQUIRED_PCI_OFW_NODES 2

Numbers of nodes in OpenFirmware device paths that are required and examined.

Definition at line 40 of file QemuBootOrderLib.c.

◆ TRANSLATION_OUTPUT_SIZE

#define TRANSLATION_OUTPUT_SIZE 0x100

OpenFirmware to UEFI device path translation output buffer size in CHAR16's.

Definition at line 29 of file QemuBootOrderLib.c.

Function Documentation

◆ BootOrderAppend()

STATIC RETURN_STATUS BootOrderAppend	(	IN OUT BOOT_ORDER *	BootOrder,
		IN OUT ACTIVE_OPTION *	ActiveOption
	)

Append an active boot option to BootOrder, reallocating the latter if needed.

Parameters

[in,out]	BootOrder	The structure pointing to the array and holding allocation and usage counters.
[in]	ActiveOption	The active boot option whose ID should be appended to the array.

Return values

RETURN_SUCCESS	ID of ActiveOption appended.
RETURN_OUT_OF_RESOURCES	Memory reallocation failed.

Definition at line 271 of file QemuBootOrderLib.c.

◆ BootOrderComplete()

STATIC RETURN_STATUS BootOrderComplete	(	IN OUT BOOT_ORDER *	BootOrder,
		IN OUT ACTIVE_OPTION *	ActiveOption,
		IN UINTN	ActiveCount
	)

Append some of the unselected active boot options to the boot order.

This function should accommodate any further policy changes in "boot option survival". Currently we're adding back everything that starts with neither PciRoot() nor HD() nor a virtio-mmio VenHw() node.

Parameters

[in,out]	BootOrder	The structure holding the boot order to complete. The caller is responsible for initializing (and potentially populating) it before calling this function.
[in,out]	ActiveOption	The array of active boot options to scan. Entries marked as Appended will be skipped. Those of the rest that satisfy the survival policy will be added to BootOrder with BootOrderAppend().
[in]	ActiveCount	Number of elements in ActiveOption.

Return values

RETURN_SUCCESS BootOrder has been extended with any eligible boot options.

Returns: Error codes returned by BootOrderAppend().

Definition at line 1998 of file QemuBootOrderLib.c.

◆ CollectActiveOptions()

STATIC RETURN_STATUS CollectActiveOptions	(	IN CONST EFI_BOOT_MANAGER_LOAD_OPTION *	BootOptions,
		IN UINTN	BootOptionCount,
		OUT ACTIVE_OPTION **	ActiveOption,
		OUT UINTN *	Count
	)

Create an array of ACTIVE_OPTION elements for a boot option array.

Parameters

[in]	BootOptions	A boot option array, created with EfiBootManagerRefreshAllBootOption () and EfiBootManagerGetLoadOptions ().
[in]	BootOptionCount	The number of elements in BootOptions.
[out]	ActiveOption	Pointer to the first element in the new array. The caller is responsible for freeing the array with FreePool() after use.
[out]	Count	Number of elements in the new array.

Return values

RETURN_SUCCESS	The ActiveOption array has been created.
RETURN_NOT_FOUND	No active entry has been found in BootOptions.
RETURN_OUT_OF_RESOURCES	Memory allocation failed.

Definition at line 328 of file QemuBootOrderLib.c.

◆ ConnectDevicesFromQemu()

RETURN_STATUS EFIAPI ConnectDevicesFromQemu ( VOID )

Connect devices based on the boot order retrieved from QEMU.

Attempt to retrieve the "bootorder" fw_cfg file from QEMU. Translate the OpenFirmware device paths therein to UEFI device path fragments. Connect the devices identified by the UEFI devpath prefixes as narrowly as possible, then connect all their child devices, recursively.

If this function fails, then platform BDS should fall back to EfiBootManagerConnectAll(), or some other method for connecting any expected boot devices.

Return values

RETURN_SUCCESS	The "bootorder" fw_cfg file has been parsed, and the referenced device-subtrees have been connected.
RETURN_UNSUPPORTED	QEMU's fw_cfg is not supported.
RETURN_NOT_FOUND	Empty or nonexistent "bootorder" fw_cfg file.
RETURN_INVALID_PARAMETER	Parse error in the "bootorder" fw_cfg file.
RETURN_OUT_OF_RESOURCES	Memory allocation failed.

Returns: Error statuses propagated from underlying functions.

Definition at line 1571 of file QemuBootOrderLib.c.

◆ GetFrontPageTimeoutFromQemu()

UINT16 EFIAPI GetFrontPageTimeoutFromQemu ( VOID )

Calculate the number of seconds we should be showing the FrontPage progress bar for.

Returns: The TimeoutDefault argument for PlatformBdsEnterFrontPage().

Definition at line 2373 of file QemuBootOrderLib.c.

◆ IsAlnum()

STATIC BOOLEAN IsAlnum ( IN CHAR8 Chr )

Simple character classification routines, corresponding to POSIX class names and ASCII encoding.

Definition at line 50 of file QemuBootOrderLib.c.

◆ IsDriverNamePunct()

STATIC BOOLEAN IsDriverNamePunct ( IN CHAR8 Chr )

Definition at line 62 of file QemuBootOrderLib.c.

◆ IsPrintNotDelim()

STATIC BOOLEAN IsPrintNotDelim ( IN CHAR8 Chr )

Definition at line 73 of file QemuBootOrderLib.c.

◆ Match()

STATIC BOOLEAN Match	(	IN CONST CHAR16 *	Translated,
		IN UINTN	TranslatedLength,
		IN EFI_DEVICE_PATH_PROTOCOL *	DevicePath
	)

Convert the UEFI DevicePath to full text representation with DevPathToText, then match the UEFI device path fragment in Translated against it.

Parameters

[in]	Translated	UEFI device path fragment, translated from OpenFirmware format, to search for.
[in]	TranslatedLength	The length of Translated in CHAR16's.
[in]	DevicePath	Boot option device path whose textual rendering to search in.
[in]	DevPathToText	Binary-to-text conversion protocol for DevicePath.

Return values

TRUE	If Translated was found at the beginning of DevicePath after converting the latter to text.
FALSE	If DevicePath was NULL, or it could not be converted, or there was no match.

Definition at line 1857 of file QemuBootOrderLib.c.

◆ ParseOfwNode()

STATIC RETURN_STATUS ParseOfwNode	(	IN OUT CONST CHAR8 **	Ptr,
		OUT OFW_NODE *	OfwNode,
		OUT BOOLEAN *	IsFinal
	)

Parse an OpenFirmware device path node into the caller-allocated OFW_NODE structure, and advance in the input string.

The node format is mostly parsed after IEEE 1275-1994, 3.2.1.1 "Node names" (a leading slash is expected and not returned):

/driver-name@unit-address[:device-arguments][<LF>]

A single trailing <LF> character is consumed but not returned. A trailing <LF> or NUL character terminates the device path.

The function relies on ASCII encoding.

Parameters

[in,out]	Ptr	Address of the pointer pointing to the start of the node string. After successful parsing *Ptr is set to the byte immediately following the consumed characters. On error it points to the byte that caused the error. The input string is never modified.
[out]	OfwNode	The members of this structure point into the input string, designating components of the node. Separators are never included. If "device-arguments" is missing, then DeviceArguments.Ptr is set to NULL. All components that are present have nonzero length.

If the call doesn't succeed, the contents of this structure is indeterminate.

Parameters

[out] IsFinal In case of successful parsing, this parameter signals whether the node just parsed is the final node in the device path. The call after a final node will attempt to start parsing the next path. If the call doesn't succeed, then this parameter is not changed.

Return values

RETURN_SUCCESS	Parsing successful.
RETURN_NOT_FOUND	Parsing terminated. *Ptr was (and is) pointing to an empty string.
RETURN_INVALID_PARAMETER	Parse error.

Definition at line 429 of file QemuBootOrderLib.c.

◆ ParseUnitAddressHexList()

STATIC RETURN_STATUS ParseUnitAddressHexList	(	IN SUBSTRING	UnitAddress,
		OUT UINT64 *	Result,
		IN OUT UINTN *	NumResults
	)

Parse a comma-separated list of hexadecimal integers into the elements of an UINT64 array.

Whitespace, "0x" prefixes, leading or trailing commas, sequences of commas, or an empty string are not allowed; they are rejected.

The function relies on ASCII encoding.

Parameters

[in]	UnitAddress	The substring to parse.
[out]	Result	The array, allocated by the caller, to receive the parsed values. This parameter may be NULL if NumResults is zero on input.
[in,out]	NumResults	On input, the number of elements allocated for Result. On output, the number of elements it has taken (or would have taken) to parse the string fully.

Return values

RETURN_SUCCESS	UnitAddress has been fully parsed. NumResults is set to the number of parsed values; the corresponding elements have been set in Result. The rest of Result's elements are unchanged.
RETURN_BUFFER_TOO_SMALL	UnitAddress has been fully parsed. NumResults is set to the number of parsed values, but elements have been stored only up to the input value of NumResults, which is less than what has been parsed.
RETURN_INVALID_PARAMETER	Parse error. The contents of Results is indeterminate. NumResults has not been changed.

Definition at line 166 of file QemuBootOrderLib.c.

◆ PruneBootVariables()

STATIC VOID PruneBootVariables	(	IN CONST ACTIVE_OPTION *	ActiveOption,
		IN UINTN	ActiveCount
	)

Delete Boot#### variables that stand for such active boot options that have been dropped (ie. have not been selected by either matching or "survival policy").

Parameters

[in]	ActiveOption	The array of active boot options to scan. Each entry not marked as appended will trigger the deletion of the matching Boot#### variable.
[in]	ActiveCount	Number of elements in ActiveOption.

Definition at line 2109 of file QemuBootOrderLib.c.

◆ SetBootOrderFromQemu()

RETURN_STATUS EFIAPI SetBootOrderFromQemu ( VOID )

Set the boot order based on configuration retrieved from QEMU.

Attempt to retrieve the "bootorder" fw_cfg file from QEMU. Translate the OpenFirmware device paths therein to UEFI device path fragments. Match the translated fragments against the current list of boot options, and rewrite the BootOrder NvVar so that it corresponds to the order described in fw_cfg.

Platform BDS should call this function after connecting any expected boot devices and calling EfiBootManagerRefreshAllBootOption ().

Return values

RETURN_SUCCESS	BootOrder NvVar rewritten.
RETURN_UNSUPPORTED	QEMU's fw_cfg is not supported.
RETURN_NOT_FOUND	Empty or nonexistent "bootorder" fw_cfg file, or no match found between the "bootorder" fw_cfg file and BootOptionList.
RETURN_INVALID_PARAMETER	Parse error in the "bootorder" fw_cfg file.
RETURN_OUT_OF_RESOURCES	Memory allocation failed.

Returns: Values returned by gBS->LocateProtocol () or gRT->SetVariable ().

Definition at line 2172 of file QemuBootOrderLib.c.

◆ StoreQemuBootOrder()

VOID EFIAPI StoreQemuBootOrder ( VOID )

Write qemu boot order to uefi variables.

Attempt to retrieve the "bootorder" fw_cfg file from QEMU. Translate the OpenFirmware device paths therein to UEFI device path fragments.

On Success store the device path in VMMBootOrderNNNN variables.

Definition at line 1716 of file QemuBootOrderLib.c.

◆ SubstringEq()

STATIC BOOLEAN SubstringEq	(	IN SUBSTRING	Substring,
		IN CONST CHAR8 *	String
	)

Check if Substring and String have identical contents.

The function relies on the restriction that a SUBSTRING cannot have embedded NULs either.

Parameters

[in]	Substring	The SUBSTRING input to the comparison.
[in]	String	The ASCII string input to the comparison.

Returns: Whether the inputs have identical contents.

Definition at line 106 of file QemuBootOrderLib.c.

◆ TranslateMmioOfwNodes()

STATIC RETURN_STATUS TranslateMmioOfwNodes	(	IN CONST OFW_NODE *	OfwNode,
		IN UINTN	NumNodes,
		OUT CHAR16 *	Translated,
		IN OUT UINTN *	TranslatedSize
	)

Translate an MMIO-like array of OpenFirmware device nodes to a UEFI device path fragment.

Parameters

[in]	OfwNode	Array of OpenFirmware device nodes to translate, constituting the beginning of an OpenFirmware device path.
[in]	NumNodes	Number of elements in OfwNode.
[out]	Translated	Destination array receiving the UEFI path fragment, allocated by the caller. If the return value differs from RETURN_SUCCESS, its contents is indeterminate.
[in,out]	TranslatedSize	On input, the number of CHAR16's in Translated. On RETURN_SUCCESS this parameter is assigned the number of non-NUL CHAR16's written to Translated. In case of other return values, TranslatedSize is indeterminate.

Return values

RETURN_SUCCESS	Translation successful.
RETURN_BUFFER_TOO_SMALL	The translation does not fit into the number of bytes provided.
RETURN_UNSUPPORTED	The array of OpenFirmware device nodes can't be translated in the current implementation.

Definition at line 1170 of file QemuBootOrderLib.c.

◆ TranslateOfwNodes()

STATIC RETURN_STATUS TranslateOfwNodes	(	IN CONST OFW_NODE *	OfwNode,
		IN UINTN	NumNodes,
		IN CONST EXTRA_ROOT_BUS_MAP *	ExtraPciRoots,
		OUT CHAR16 *	Translated,
		IN OUT UINTN *	TranslatedSize
	)

Translate an array of OpenFirmware device nodes to a UEFI device path fragment.

Parameters

[in]	OfwNode	Array of OpenFirmware device nodes to translate, constituting the beginning of an OpenFirmware device path.
[in]	NumNodes	Number of elements in OfwNode.
[in]	ExtraPciRoots	An EXTRA_ROOT_BUS_MAP object created with CreateExtraRootBusMap(), to be used for translating positions of extra root buses to bus numbers.
[out]	Translated	Destination array receiving the UEFI path fragment, allocated by the caller. If the return value differs from RETURN_SUCCESS, its contents is indeterminate.
[in,out]	TranslatedSize	On input, the number of CHAR16's in Translated. On RETURN_SUCCESS this parameter is assigned the number of non-NUL CHAR16's written to Translated. In case of other return values, TranslatedSize is indeterminate.

Return values

RETURN_SUCCESS	Translation successful.
RETURN_BUFFER_TOO_SMALL	The translation does not fit into the number of bytes provided.
RETURN_UNSUPPORTED	The array of OpenFirmware device nodes can't be translated in the current implementation.
RETURN_PROTOCOL_ERROR	The array of OpenFirmware device nodes has been (partially) recognized, but it contains a logic error / doesn't match system state.

Definition at line 1360 of file QemuBootOrderLib.c.

◆ TranslateOfwPath()

STATIC RETURN_STATUS TranslateOfwPath	(	IN OUT CONST CHAR8 **	Ptr,
		IN CONST EXTRA_ROOT_BUS_MAP *	ExtraPciRoots,
		OUT CHAR16 *	Translated,
		IN OUT UINTN *	TranslatedSize
	)

Translate an OpenFirmware device path fragment to a UEFI device path fragment, and advance in the input string.

Parameters

[in,out]	Ptr	Address of the pointer pointing to the start of the path string. After successful translation (RETURN_SUCCESS) or at least successful parsing (RETURN_UNSUPPORTED, RETURN_BUFFER_TOO_SMALL), *Ptr is set to the byte immediately following the consumed characters. In other error cases, it points to the byte that caused the error.
[in]	ExtraPciRoots	An EXTRA_ROOT_BUS_MAP object created with CreateExtraRootBusMap(), to be used for translating positions of extra root buses to bus numbers.
[out]	Translated	Destination array receiving the UEFI path fragment, allocated by the caller. If the return value differs from RETURN_SUCCESS, its contents is indeterminate.
[in,out]	TranslatedSize	On input, the number of CHAR16's in Translated. On RETURN_SUCCESS this parameter is assigned the number of non-NUL CHAR16's written to Translated. In case of other return values, TranslatedSize is indeterminate.

Return values

RETURN_SUCCESS	Translation successful.
RETURN_BUFFER_TOO_SMALL	The OpenFirmware device path was parsed successfully, but its translation did not fit into the number of bytes provided. Further calls to this function are possible.
RETURN_UNSUPPORTED	The OpenFirmware device path was parsed successfully, but it can't be translated in the current implementation. Further calls to this function are possible.
RETURN_PROTOCOL_ERROR	The OpenFirmware device path has been (partially) recognized, but it contains a logic error / doesn't match system state. Further calls to this function are possible.
RETURN_NOT_FOUND	Translation terminated. On input, Ptr was pointing to the empty string or "HALT". On output, Ptr points to the empty string (ie. "HALT" is consumed transparently when present).
RETURN_INVALID_PARAMETER	Parse error. This is a permanent error.

Definition at line 1457 of file QemuBootOrderLib.c.

◆ TranslatePciOfwNodes()

STATIC RETURN_STATUS TranslatePciOfwNodes	(	IN CONST OFW_NODE *	OfwNode,
		IN UINTN	NumNodes,
		IN CONST EXTRA_ROOT_BUS_MAP *	ExtraPciRoots,
		OUT CHAR16 *	Translated,
		IN OUT UINTN *	TranslatedSize
	)

Translate a PCI-like array of OpenFirmware device nodes to a UEFI device path fragment.

Parameters

[in]	OfwNode	Array of OpenFirmware device nodes to translate, constituting the beginning of an OpenFirmware device path.
[in]	NumNodes	Number of elements in OfwNode.
[in]	ExtraPciRoots	An EXTRA_ROOT_BUS_MAP object created with CreateExtraRootBusMap(), to be used for translating positions of extra root buses to bus numbers.
[out]	Translated	Destination array receiving the UEFI path fragment, allocated by the caller. If the return value differs from RETURN_SUCCESS, its contents is indeterminate.
[in,out]	TranslatedSize	On input, the number of CHAR16's in Translated. On RETURN_SUCCESS this parameter is assigned the number of non-NUL CHAR16's written to Translated. In case of other return values, TranslatedSize is indeterminate.

Return values

RETURN_SUCCESS	Translation successful.
RETURN_BUFFER_TOO_SMALL	The translation does not fit into the number of bytes provided.
RETURN_UNSUPPORTED	The array of OpenFirmware device nodes can't be translated in the current implementation.
RETURN_PROTOCOL_ERROR	The initial OpenFirmware node refers to an extra PCI root bus (by serial number) that is invalid according to ExtraPciRoots.

Definition at line 600 of file QemuBootOrderLib.c.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ BRIDGE_TRANSLATION_OUTPUT_SIZE

◆ EXAMINED_OFW_NODES

◆ REQUIRED_MMIO_OFW_NODES

◆ REQUIRED_PCI_OFW_NODES

◆ TRANSLATION_OUTPUT_SIZE

Function Documentation

◆ BootOrderAppend()

◆ BootOrderComplete()

◆ CollectActiveOptions()

◆ ConnectDevicesFromQemu()

◆ GetFrontPageTimeoutFromQemu()

◆ IsAlnum()

◆ IsDriverNamePunct()

◆ IsPrintNotDelim()

◆ Match()

◆ ParseOfwNode()

◆ ParseUnitAddressHexList()

◆ PruneBootVariables()

◆ SetBootOrderFromQemu()

◆ StoreQemuBootOrder()

◆ SubstringEq()

◆ TranslateMmioOfwNodes()

◆ TranslateOfwNodes()

◆ TranslateOfwPath()

◆ TranslatePciOfwNodes()