#include "InternalPlatDriOverrideDxe.h"

Data Structures
struct	_PLATFORM_OVERRIDE_ITEM

struct	_DRIVER_IMAGE_INFO

struct	_DEVICE_PATH_STACK_ITEM

Macros
#define	PLATFORM_OVERRIDE_ITEM_SIGNATURE SIGNATURE_32('p','d','o','i')

#define	DRIVER_IMAGE_INFO_SIGNATURE SIGNATURE_32('p','d','i','i')

#define	DEVICE_PATH_STACK_ITEM_SIGNATURE SIGNATURE_32('d','p','s','i')

Typedefs
typedef struct _PLATFORM_OVERRIDE_ITEM	PLATFORM_OVERRIDE_ITEM

typedef struct _DRIVER_IMAGE_INFO	DRIVER_IMAGE_INFO

typedef struct _DEVICE_PATH_STACK_ITEM	DEVICE_PATH_STACK_ITEM

Functions
EFI_STATUS EFIAPI	PushDevPathStack (IN EFI_DEVICE_PATH_PROTOCOL *DevicePath)

EFI_STATUS EFIAPI	PopDevPathStack (OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath)

BOOLEAN EFIAPI	CheckExistInStack (IN EFI_DEVICE_PATH_PROTOCOL *DevicePath)

EFI_STATUS EFIAPI	UpdateFvFileDevicePath (IN OUT EFI_DEVICE_PATH_PROTOCOL *DevicePath, IN EFI_GUID FileGuid, IN EFI_HANDLE CallerImageHandle)

VOID *EFIAPI	GetVariableAndSize (IN CHAR16 Name, IN EFI_GUID VendorGuid, OUT UINTN *VariableSize)

EFI_STATUS EFIAPI	ConnectDevicePath (IN EFI_DEVICE_PATH_PROTOCOL *DevicePathToConnect)

EFI_STATUS EFIAPI	FreeMappingDatabase (IN OUT LIST_ENTRY *MappingDataBase)

EFI_STATUS EFIAPI	InitOverridesMapping (OUT LIST_ENTRY *MappingDataBase)

UINTN EFIAPI	GetOneItemNeededSize (IN LIST_ENTRY *OverrideItemListIndex)

EFI_STATUS EFIAPI	DeleteOverridesVariables (VOID)

EFI_STATUS EFIAPI	SaveOverridesMapping (IN LIST_ENTRY *MappingDataBase)

EFI_DRIVER_BINDING_PROTOCOL *EFIAPI	GetBindingProtocolFromImageHandle (IN EFI_HANDLE ImageHandle, OUT EFI_HANDLE *BindingHandle)

EFI_TPL	GetCurrentTpl (VOID)

EFI_STATUS EFIAPI	GetDriverFromMapping (IN EFI_HANDLE ControllerHandle, IN OUT EFI_HANDLE DriverImageHandle, IN LIST_ENTRY MappingDataBase, IN EFI_HANDLE CallerImageHandle)

EFI_STATUS EFIAPI	CheckMapping (IN EFI_DEVICE_PATH_PROTOCOL ControllerDevicePath, IN EFI_DEVICE_PATH_PROTOCOL DriverImageDevicePath OPTIONAL, IN LIST_ENTRY MappingDataBase, OUT UINT32 DriverInfoNum OPTIONAL, OUT UINT32 *DriverImageNO OPTIONAL)

EFI_STATUS EFIAPI	InsertDriverImage (IN EFI_DEVICE_PATH_PROTOCOL ControllerDevicePath, IN EFI_DEVICE_PATH_PROTOCOL DriverImageDevicePath, IN LIST_ENTRY *MappingDataBase, IN UINT32 DriverImageNO)

EFI_STATUS EFIAPI	DeleteDriverImage (IN EFI_DEVICE_PATH_PROTOCOL ControllerDevicePath, IN EFI_DEVICE_PATH_PROTOCOL DriverImageDevicePath, IN LIST_ENTRY *MappingDataBase)

Variables
LIST_ENTRY	mDevicePathStack = INITIALIZE_LIST_HEAD_VARIABLE (mDevicePathStack)

Detailed Description

Implementation of the shared functions to do the platform driver vverride mapping.

Copyright (c) 2007 - 2019, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file PlatDriOverrideLib.c.

Macro Definition Documentation

◆ DEVICE_PATH_STACK_ITEM_SIGNATURE

#define DEVICE_PATH_STACK_ITEM_SIGNATURE SIGNATURE_32('d','p','s','i')

Definition at line 34 of file PlatDriOverrideLib.c.

◆ DRIVER_IMAGE_INFO_SIGNATURE

#define DRIVER_IMAGE_INFO_SIGNATURE SIGNATURE_32('p','d','i','i')

Definition at line 24 of file PlatDriOverrideLib.c.

◆ PLATFORM_OVERRIDE_ITEM_SIGNATURE

#define PLATFORM_OVERRIDE_ITEM_SIGNATURE SIGNATURE_32('p','d','o','i')

Definition at line 11 of file PlatDriOverrideLib.c.

Function Documentation

◆ CheckExistInStack()

BOOLEAN EFIAPI CheckExistInStack ( IN EFI_DEVICE_PATH_PROTOCOL * DevicePath )

Check whether a controller device path is in a globle device path list

Parameters

DevicePath The controller device path to check

Return values

TRUE	DevicePath exists in the stack.
FALSE	DevicePath does not exist in the stack.

Definition at line 115 of file PlatDriOverrideLib.c.

◆ CheckMapping()

EFI_STATUS EFIAPI CheckMapping	(	IN EFI_DEVICE_PATH_PROTOCOL *	ControllerDevicePath,
		IN EFI_DEVICE_PATH_PROTOCOL *DriverImageDevicePath	OPTIONAL,
		IN LIST_ENTRY *	MappingDataBase,
		OUT UINT32 *DriverInfoNum	OPTIONAL,
		OUT UINT32 *DriverImageNO	OPTIONAL
	)

Check mapping database whether already has the mapping info which records the input Controller to input DriverImage.

Parameters

ControllerDevicePath	The controller device path is to be check.
DriverImageDevicePath	The driver image device path is to be check.
MappingDataBase	Mapping database list entry pointer
DriverInfoNum	the controller's total override driver number
DriverImageNO	The driver order number for the input DriverImage. If the DriverImageDevicePath is NULL, DriverImageNO is not set.

Return values

EFI_INVALID_PARAMETER	ControllerDevicePath or MappingDataBase is NULL.
EFI_NOT_FOUND	ControllerDevicePath is not found in MappingDataBase or DriverImageDevicePath is not found in the found DriverImage Info list.
EFI_SUCCESS	The controller's total override driver number and input DriverImage's order number is correctly return.

Definition at line 1594 of file PlatDriOverrideLib.c.

◆ ConnectDevicePath()

EFI_STATUS EFIAPI ConnectDevicePath ( IN EFI_DEVICE_PATH_PROTOCOL * DevicePathToConnect )

Connect to the handle to a device on the device path.

This function will create all handles associate with every device path node. If the handle associate with one device path node can not be created success, then still give one chance to do the dispatch, which load the missing drivers if possible.

Parameters

DevicePathToConnect The device path which will be connected, it can be a multi-instance device path

Return values

EFI_SUCCESS	All handles associate with every device path node have been created
EFI_OUT_OF_RESOURCES	There is no resource to create new handles
EFI_NOT_FOUND	Create the handle associate with one device path node failed

Definition at line 449 of file PlatDriOverrideLib.c.

◆ DeleteDriverImage()

EFI_STATUS EFIAPI DeleteDriverImage	(	IN EFI_DEVICE_PATH_PROTOCOL *	ControllerDevicePath,
		IN EFI_DEVICE_PATH_PROTOCOL *	DriverImageDevicePath,
		IN LIST_ENTRY *	MappingDataBase
	)

Delete a controller's override driver from the mapping database.

Parameters

ControllerDevicePath	The controller device path will be deleted when all drivers images on it are removed.
DriverImageDevicePath	The driver image device path will be delete. If NULL, all driver image will be delete.
MappingDataBase	Mapping database list entry pointer

Return values

EFI_INVALID_PARAMETER	ControllerDevicePath is NULL, or MappingDataBase is NULL
EFI_NOT_FOUND	ControllerDevicePath is not found in MappingDataBase or DriverImageDevicePath is not found in the found DriverImage Info list.
EFI_SUCCESS	Delete the specified driver successfully.

Definition at line 1861 of file PlatDriOverrideLib.c.

◆ DeleteOverridesVariables()

EFI_STATUS EFIAPI DeleteOverridesVariables ( VOID )

Deletes all environment variable(s) that contain the override mappings from Controller Device Path to a set of Driver Device Paths.

Return values

EFI_SUCCESS Delete all variable(s) successfully.

Definition at line 887 of file PlatDriOverrideLib.c.

◆ FreeMappingDatabase()

EFI_STATUS EFIAPI FreeMappingDatabase ( IN OUT LIST_ENTRY * MappingDataBase )

Free all the mapping database memory resource and initialize the mapping list entry.

Parameters

MappingDataBase Mapping database list entry pointer

Return values

EFI_SUCCESS	Mapping database successfully freed
EFI_INVALID_PARAMETER	MappingDataBase is NULL

Definition at line 563 of file PlatDriOverrideLib.c.

◆ GetBindingProtocolFromImageHandle()

EFI_DRIVER_BINDING_PROTOCOL *EFIAPI GetBindingProtocolFromImageHandle	(	IN EFI_HANDLE	ImageHandle,
		OUT EFI_HANDLE *	BindingHandle
	)

Get the first Binding protocol which has the specific image handle.

Parameters

ImageHandle	The Image handle
BindingHandle	The BindingHandle of the found Driver Binding protocol. If Binding protocol is not found, it is set to NULL.

Returns: Pointer into the Binding Protocol interface

Return values

NULL	The parameter is not valid or the binding protocol is not found.

Definition at line 1134 of file PlatDriOverrideLib.c.

◆ GetCurrentTpl()

EFI_TPL GetCurrentTpl ( VOID )

Return the current TPL.

Returns: Current TPL

Definition at line 1200 of file PlatDriOverrideLib.c.

◆ GetDriverFromMapping()

EFI_STATUS EFIAPI GetDriverFromMapping	(	IN EFI_HANDLE	ControllerHandle,
		IN OUT EFI_HANDLE *	DriverImageHandle,
		IN LIST_ENTRY *	MappingDataBase,
		IN EFI_HANDLE	CallerImageHandle
	)

Retrieves the image handle of the platform override driver for a controller in the system from the memory mapping database.

Parameters

ControllerHandle	The device handle of the controller to check if a driver override exists.
DriverImageHandle	On input, the previously returnd driver image handle. On output, a pointer to the next driver handle. Passing in a pointer to NULL, will return the first driver handle for ControllerHandle.
MappingDataBase	Mapping database list entry pointer
CallerImageHandle	The caller driver's image handle, for UpdateFvFileDevicePath use.

Return values

EFI_INVALID_PARAMETER	The handle specified by ControllerHandle is not a valid handle. Or DriverImagePath is not a device path that was returned on a previous call to GetDriverPath().
EFI_NOT_FOUND	A driver override for ControllerHandle was not found.
EFI_UNSUPPORTED	The operation is not supported.
EFI_SUCCESS	The driver override for ControllerHandle was returned in DriverImagePath.

Definition at line 1239 of file PlatDriOverrideLib.c.

◆ GetOneItemNeededSize()

UINTN EFIAPI GetOneItemNeededSize ( IN LIST_ENTRY * OverrideItemListIndex )

Calculate the needed size in NV variable for recording a specific PLATFORM_OVERRIDE_ITEM info.

Parameters

OverrideItemListIndex Pointer to the list of a specific PLATFORM_OVERRIDE_ITEM

Returns: The needed size number

Definition at line 840 of file PlatDriOverrideLib.c.

◆ GetVariableAndSize()

VOID *EFIAPI GetVariableAndSize	(	IN CHAR16 *	Name,
		IN EFI_GUID *	VendorGuid,
		OUT UINTN *	VariableSize
	)

Gets the data and size of a variable.

Read the EFI variable (VendorGuid/Name) and return a dynamically allocated buffer, and the size of the buffer. If failure return NULL.

Parameters

Name	String part of EFI variable name
VendorGuid	GUID part of EFI variable name
VariableSize	Returns the size of the EFI variable that was read

Returns: Dynamically allocated memory that contains a copy of the EFI variable. Caller is responsible freeing the buffer.

Return values

NULL	Variable was not read

Definition at line 390 of file PlatDriOverrideLib.c.

◆ InitOverridesMapping()

EFI_STATUS EFIAPI InitOverridesMapping ( OUT LIST_ENTRY * MappingDataBase )

Create the mapping database according to variable.

Read the environment variable(s) that contain the override mappings from Controller Device Path to a set of Driver Device Paths, and create the mapping database in memory with those variable info. VariableLayout{

NotEnd indicate whether the variable is the last one, and has no subsequent variable need to load. Each variable has MaximumVariableSize limitation, so we maybe need multiple variables to store large mapping infos. The variable(s) name rule is PlatDriOver, PlatDriOver1, PlatDriOver2, ....

UINT32 NotEnd; //Zero is the last one.

The entry which contains the mapping that Controller Device Path to a set of Driver Device Paths There are often multi mapping entries in a variable.

UINT32 SIGNATURE; //SIGNATURE_32('p','d','o','i') UINT32 DriverNum; EFI_DEVICE_PATH_PROTOCOL ControllerDevicePath[]; EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; ...... UINT32 NotEnd; //Zero is the last one. UINT32 SIGNATURE; UINT32 DriverNum; EFI_DEVICE_PATH_PROTOCOL ControllerDevicePath[]; EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; EFI_DEVICE_PATH_PROTOCOL DriverDevicePath[]; ...... }

Parameters

MappingDataBase Mapping database list entry pointer

Return values

EFI_SUCCESS	Create the mapping database in memory successfully
EFI_INVALID_PARAMETER	MappingDataBase pointer is null
EFI_NOT_FOUND	Cannot find the 'PlatDriOver' NV variable
EFI_VOLUME_CORRUPTED	The found NV variable is corrupted

Definition at line 660 of file PlatDriOverrideLib.c.

◆ InsertDriverImage()

EFI_STATUS EFIAPI InsertDriverImage	(	IN EFI_DEVICE_PATH_PROTOCOL *	ControllerDevicePath,
		IN EFI_DEVICE_PATH_PROTOCOL *	DriverImageDevicePath,
		IN LIST_ENTRY *	MappingDataBase,
		IN UINT32	DriverImageNO
	)

Insert a driver image as a controller's override driver into the mapping database. The driver image's order number is indicated by DriverImageNO.

Parameters

ControllerDevicePath	The controller device path need to add a override driver image item
DriverImageDevicePath	The driver image device path need to be insert
MappingDataBase	Mapping database list entry pointer
DriverImageNO	The inserted order number. If this number is taken, the larger available number will be used.

Return values

EFI_INVALID_PARAMETER	ControllerDevicePath is NULL, or DriverImageDevicePath is NULL or MappingDataBase is NULL
EFI_ALREADY_STARTED	The input Controller to input DriverImage has been recorded into the mapping database.
EFI_SUCCESS	The Controller and DriverImage are inserted into the mapping database successfully.

Definition at line 1724 of file PlatDriOverrideLib.c.

◆ PopDevPathStack()

EFI_STATUS EFIAPI PopDevPathStack ( OUT EFI_DEVICE_PATH_PROTOCOL ** DevicePath )

Pop a controller device path from a globle device path list

Parameters

DevicePath The controller device path popped from stack

Return values

EFI_SUCCESS	Controller device path successfully popped.
EFI_NOT_FOUND	Stack is empty.

Definition at line 78 of file PlatDriOverrideLib.c.

◆ PushDevPathStack()

EFI_STATUS EFIAPI PushDevPathStack ( IN EFI_DEVICE_PATH_PROTOCOL * DevicePath )

Push a controller device path into a globle device path list.

Parameters

DevicePath The controller device path to push into stack

Return values

EFI_SUCCESS Device path successfully pushed into the stack.

Definition at line 53 of file PlatDriOverrideLib.c.

◆ SaveOverridesMapping()

EFI_STATUS EFIAPI SaveOverridesMapping ( IN LIST_ENTRY * MappingDataBase )

Save the memory mapping database into NV environment variable(s).

Parameters

MappingDataBase Mapping database list entry pointer

Return values

EFI_SUCCESS	Save memory mapping database successfully
EFI_INVALID_PARAMETER	MappingDataBase pointer is null

Definition at line 955 of file PlatDriOverrideLib.c.

◆ UpdateFvFileDevicePath()

EFI_STATUS EFIAPI UpdateFvFileDevicePath	(	IN OUT EFI_DEVICE_PATH_PROTOCOL **	DevicePath,
		IN EFI_GUID *	FileGuid,
		IN EFI_HANDLE	CallerImageHandle
	)

Update the FV file device path if it is not valid.

According to a file GUID, check a Fv file device path is valid. If it is invalid, try to return the valid device path. FV address maybe changes for memory layout adjust from time to time, use this function could promise the Fv file device path is right.

Parameters

DevicePath	On input, the FV file device path to check On output, the updated valid FV file device path
FileGuid	The FV file GUID
CallerImageHandle	Image handle of the caller

Return values

EFI_INVALID_PARAMETER	the input DevicePath or FileGuid is invalid parameter
EFI_UNSUPPORTED	the input DevicePath does not contain FV file GUID at all
EFI_ALREADY_STARTED	the input DevicePath has pointed to FV file, it is valid
EFI_SUCCESS	Successfully updated the invalid DevicePath, and return the updated device path in DevicePath

Definition at line 164 of file PlatDriOverrideLib.c.

Variable Documentation

◆ mDevicePathStack

LIST_ENTRY mDevicePathStack = INITIALIZE_LIST_HEAD_VARIABLE (mDevicePathStack)

Definition at line 41 of file PlatDriOverrideLib.c.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ DEVICE_PATH_STACK_ITEM_SIGNATURE

◆ DRIVER_IMAGE_INFO_SIGNATURE

◆ PLATFORM_OVERRIDE_ITEM_SIGNATURE

Function Documentation

◆ CheckExistInStack()

◆ CheckMapping()

◆ ConnectDevicePath()

◆ DeleteDriverImage()

◆ DeleteOverridesVariables()

◆ FreeMappingDatabase()

◆ GetBindingProtocolFromImageHandle()

◆ GetCurrentTpl()

◆ GetDriverFromMapping()

◆ GetOneItemNeededSize()

◆ GetVariableAndSize()

◆ InitOverridesMapping()

◆ InsertDriverImage()

◆ PopDevPathStack()

◆ PushDevPathStack()

◆ SaveOverridesMapping()

◆ UpdateFvFileDevicePath()

Variable Documentation

◆ mDevicePathStack