EFI DEVICE PATH UTILITIES PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Creates and manipulates device paths and device nodes.

Contents

GUID

#define EFI_DEVICE_PATH_UTILITIES_PROTOCOL_GUID \
  {0x379be4e,0xd706,0x437d,0xb0,0x37,0xed,0xb8,0x2f,0xb7,0x72,0xa4 }

Protocol Interface Structure

#include EFI_PROTOCOL_CONSUMER(DevicePathUtilities)

extern EFI_GUID gEfiDevicePathUtilitiesProtocolGuid;
typedef struct _EFI_DEVICE_PATH_UTILITIES_PROTOCOL {
  EFI_DEVICE_PATH_UTILS_GET_DEVICE_PATH_SIZE GetDevicePathSize;
  EFI_DEVICE_PATH_UTILS_DUP_DEVICE_PATH      DuplicateDevicePath;
  EFI_DEVICE_PATH_UTILS_APPEND_PATH          AppendDevicePath;
  EFI_DEVICE_PATH_UTILS_APPEND_NODE          AppendDeviceNode;
  EFI_DEVICE_PATH_UTILS_APPEND_INSTANCE      AppendDevicePathInstance;
  EFI_DEVICE_PATH_UTILS_GET_NEXT_INSTANCE    GetNextDevicePathInstance;
  EFI_DEVICE_PATH_UTILS_IS_MULTI_INSTANCE    IsDevicePathMultiInstance;
  EFI_DEVICE_PATH_UTILS_CREATE_NODE          CreateDeviceNode; 

} EFI_DEVICE_PATH_UTILITIES_PROTOCOL;

Members

Member Description
GetDevicePathSize Returns the size of the specified device path, in bytes.
DuplicateDevicePath Duplicates a device path structure.
AppendDeviceNode Appends the device node to the specified device path.
AppendDevicePath Appends the device path to the specified device path.
AppendDevicePathInstance Appends a device path instance to another device path.
GetNextDevicePathInstance Retrieves the next device path instance from a device path data structure.
IsDevicePathMultiInstance Returns TRUE if this is a multi-instance device path.
CreateDeviceNode Allocates memory for a device node with the specified type and sub-type.

Description

The EFI_DEVICE_PATH_UTILITIES_PROTOCOL provides common utilities for creating a manipulating device paths and device nodes.

GetDevicePathSize()

Returns the size of the device path, in bytes.

Prototype

typedef
UINTN
(EFIAPI *EFI_DEVICE_PATH_UTILS_GET_DEVICE_PATH_SIZE) (
  IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath
  );

Parameters

Parameter Description
DevicePath Points to the start of the EFI device path.

Description
This function returns the size of the specified device path, in bytes, including the end-of-path tag. If DevicePath is NULL then zero is returned.

DuplicateDevicePath()

Create a duplicate of the specified path.

Prototype

typedef
EFI_DEVICE_PATH_PROTOCOL*
(EFIAPI *EFI_DEVICE_PATH_UTILS_DUP_DEVICE_PATH) (
  IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
  );

Parameters

Member Description
DevicePath Points to the source device path.

Description
This function creates a duplicate of the specified device path. The memory is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated. If DevicePath is NULL then NULL will be returned and no memory will be allocated.

Returns
This function returns a pointer to the duplicate device path or NULL if there was insufficient memory.

AppendDevicePath()

Create a new path by appending the second device path to the first.

Prototype

typedef
EFI_DEVICE_PATH_PROTOCOL*
(EFIAPI *EFI_DEVICE_PATH_UTILS_APPEND_PATH) (
  IN CONST EFI_DEVICE_PATH_PROTOCOL *Src1,
  IN CONST EFI_DEVICE_PATH_PROTOCOL *Src2
  );

Parameters

Member Description
Src1 Points to the first device path.
Src2 Points to the second device path.

Description
This function creates a new device path by appending a copy of the second device path to a copy of the first device path in a newly allocated buffer. Only the end-of-device-path device node from the second device path is retained. If Src1 is NULL and Src2 is non-NULL, then a duplicate of Src2 is returned. If Src1 is non-NULL and Src2 is NULL, then a duplicate of Src1 is returned. If Src1 and Src2 are both NULL, then a copy of an end-of-device-path is returned.

The memory is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated.

Returns
This function returns a pointer to the newly created device path or NULL if memory could not be allocate.

AppendDeviceNode()

Creates a new path by appending the device node to the device path.

Prototype

typedef
EFI_DEVICE_PATH_PROTOCOL*
(EFIAPI *EFI_DEVICE_PATH_UTILS_APPEND_NODE) (
  IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
  IN CONST EFI_DEVICE_PATH_PROTOCOL *DeviceNode
  );

Parameters

Member Description
DevicePath Points to the device path.
DeviceNode Points to the device node.

Description
This function creates a new device path by appending a copy of the specified device node to a copy of the specified device path in an allocated buffer. The end-of-device-path device node is moved after the end of the appended device node. If DeviceNode is NULL then a copy of DevicePath is returned. If DevicePath is NULL then a copy of DeviceNode, followed by an end-of-device path device node is returned. If both DeviceNode and DevicePath are NULL then a copy of an end-of-device-path device node is returned.

The memory is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated.

Returns
This function returns a pointer to the allocated device path, or NULL if there was insufficient memory.

AppendDevicePathInstance()

Creates a new path by appending the specified device path instance to the specified device path.

Prototype

typedef
EFI_DEVICE_PATH_PROTOCOL*
(EFIAPI *EFI_DEVICE_PATH_UTILS_APPEND_INSTANCE) (
  IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
  IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathInstance
  );

Parameters

Member Description
DevicePath Points to the device path. If NULL, then ignored.
DevicePathInstance Points to the device path instance

Description
This function creates a new device path by appending a copy of the specified device path instance to a copy of the specified device path in an allocated buffer. The end-of-device-path device node is moved after the end of the appended device node and a new end-of-device-path-instance node is inserted between. If DevicePath is NULL, then a copy if DevicePathInstance is returned instead.

The memory is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated.

Returns
This function returns a pointer to the newly created device path or NULL if DevicePathInstance is NULL or there was insufficient memory.

GetNextDevicePathInstance()

Creates a copy of the current device path instance and returns a pointer to the next device path instance.

Prototype

typedef
EFI_DEVICE_PATH_PROTOCOL*
(EFIAPI *EFI_DEVICE_PATH_UTILS_GET_NEXT_INSTANCE) (
  IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePathInstance,
  OUT    UINTN                    *DevicePathInstanceSize OPTIONAL
  );

Parameters

Member Description
DevicePathInstance On input, this holds the pointer to the current device path instance. On output, this holds the pointer to the next device path instance or NULL if there are no more device path instances in the device path.
DevicePathInstanceSize On output, this holds the size of the device path instance, in bytes or zero, if DevicePathInstance is NULL. If NULL, then the instance size is not output.

Description
This function creates a copy of the current device path instance. It also updates DevicePathInstance to point to the next device path instance in the device path (or NULL if no more) and updates DevicePathInstanceSize to hold the size of the device path instance copy.

The memory is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated.

Returns
This function returns a pointer to the copy of the current device path instance or NULL if DevicePathInstace was NULL on entry or there was insufficient memory.

CreateDeviceNode()

Creates a device node.

Prototype

typedef
EFI_DEVICE_PATH_PROTOCOL*
(EFIAPI *EFI_DEVICE_PATH_UTILS_CREATE_NODE) (
  IN UINT8 NodeType,
  IN UINT8 NodeSubType,
  IN UINT16 NodeLength
  );

Parameters

Member Description
NodeType NodeType is the device node type (EFI_DEVICE_PATH_PROTOCOL.Type) for the new device node.
NodeSubType NodeSubType is the device node sub-type (EFI_DEVICE_PATH_PROTOCOL.SubType) for the new device node.
NodeLength NodeLength is the length of the device node (EFI_DEVICE_PATH_PROTOCOL.Length) for the new device node.

Description
This function creates a new device node in a newly allocated buffer.

The memory is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated.

Returns
This function returns a pointer to the created device node or NULL if NodeLength is less than the size of the header or there was insufficient memory.

IsDevicePathMultiInstance()

Returns whether a device path is multi-instance.

Prototype

typedef
BOOLEAN
(EFIAPI *EFI_DEVICE_PATH_UTILS_IS_MULTI_INSTANCE) (
  IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath
  );

Parameters

Member Description
DevicePath Points to the device path. If NULL, then ignored.

Description
This function returns whether the specified device path has multiple path instances.

Returns
This function returns TRUE if the device path has more than one instance or FALSE if it is empty or contains only a single instance.


Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission

Personal tools