/** @file\r
Provides library functions to construct and parse UEFI Device Paths.\r
\r
+ This library provides defines, macros, and functions to help create and parse \r
+ EFI_DEVICE_PATH_PROTOCOL structures. The macros that help create and parse device \r
+ path nodes make use of the ReadUnaligned16() and WriteUnaligned16() functions from \r
+ the Base Library, so this library class has an implied dependency on the Base Library.\r
+\r
Copyright (c) 2006 - 2008, Intel Corporation\r
All rights reserved. This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
#include <Library/BaseLib.h>\r
\r
#define END_DEVICE_PATH_LENGTH (sizeof (EFI_DEVICE_PATH_PROTOCOL))\r
-#define DevicePathNodeLength(Node) ReadUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0])\r
-#define NextDevicePathNode(Node) ((EFI_DEVICE_PATH_PROTOCOL *)((UINT8 *)(Node) + DevicePathNodeLength(Node)))\r
+\r
+/**\r
+ Macro that returns the Type field of a device path node.\r
+\r
+ Returns the Type field of the device path node specified by Node.\r
+\r
+ @param Node A pointer to a device path node data structure.\r
+\r
+ @return The Type field of the device path node specified by Node.\r
+\r
+**/\r
#define DevicePathType(Node) (((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Type)\r
+\r
+/**\r
+ Macro that returns the SubType field of a device path node.\r
+\r
+ Returns the SubType field of the device path node specified by Node.\r
+\r
+ @param Node A pointer to a device path node data structure.\r
+\r
+ @return The SubType field of the device path node specified by Node.\r
+\r
+**/\r
#define DevicePathSubType(Node) (((EFI_DEVICE_PATH_PROTOCOL *)(Node))->SubType)\r
+\r
+/**\r
+ Macro that returns the 16-bit Length field of a device path node.\r
+\r
+ Returns the 16-bit Length field of the device path node specified by Node.\r
+\r
+ @param Node A pointer to a device path node data structure.\r
+\r
+ @return The 16-bit Length field of the device path node specified by Node.\r
+\r
+**/\r
+#define DevicePathNodeLength(Node) ReadUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0])\r
+\r
+/**\r
+ Macro that returns a pointer to the next node in a device path.\r
+\r
+ Returns a pointer to the device path node that follows the device path node specified by Node.\r
+\r
+ @param Node A pointer to a device path node data structure.\r
+\r
+ @return a pointer to the device path node that follows the device path node specified by Node.\r
+\r
+**/\r
+#define NextDevicePathNode(Node) ((EFI_DEVICE_PATH_PROTOCOL *)((UINT8 *)(Node) + DevicePathNodeLength(Node)))\r
+\r
+/**\r
+ Macro that determines if a device path node is an end node of a device path.\r
+ This includes nodes that are the end of a device path instance and nodes that are the end of an entire device path.\r
+\r
+ Determines if the device path node specified by Node is an end node of a device path. \r
+ This includes nodes that are the end of a device path instance and nodes that are the \r
+ end of an entire device path. If Node represents an end node of a device path, \r
+ then TRUE is returned. Otherwise, FALSE is returned.\r
+\r
+ @param Node A pointer to a device path node data structure.\r
+\r
+ @retval TRUE The device path node specified by Node is an end node of a device path.\r
+ @retval FALSE The device path node specified by Node is not an end node of a device path.\r
+ \r
+**/\r
#define IsDevicePathEndType(Node) ((DevicePathType (Node) & 0x7f) == END_DEVICE_PATH_TYPE)\r
+\r
+/**\r
+ Macro that determines if a device path node is an end node of an entire device path.\r
+\r
+ Determines if a device path node specified by Node is an end node of an entire device path.\r
+ If Node represents the end of an entire device path, then TRUE is returned. Otherwise, FALSE is returned.\r
+\r
+ @param Node A pointer to a device path node data structure.\r
+\r
+ @retval TRUE The device path node specified by Node is the end of an entire device path.\r
+ @retval FALSE The device path node specified by Node is not the end of an entire device path.\r
+\r
+**/\r
#define IsDevicePathEnd(Node) (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_ENTIRE_DEVICE_PATH_SUBTYPE)\r
+\r
+/**\r
+ Macro that determines if a device path node is an end node of a device path instance.\r
+\r
+ Determines if a device path node specified by Node is an end node of a device path instance.\r
+ If Node represents the end of a device path instance, then TRUE is returned. Otherwise, FALSE is returned.\r
+\r
+ @param Node A pointer to a device path node data structure.\r
+\r
+ @retval TRUE The device path node specified by Node is the end of a device path instance.\r
+ @retval FALSE The device path node specified by Node is not the end of a device path instance.\r
+\r
+**/\r
#define IsDevicePathEndInstance(Node) (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_INSTANCE_DEVICE_PATH_SUBTYPE)\r
\r
+/**\r
+ Macro that sets the length, in bytes, of a device path node.\r
+\r
+ Sets the length of the device path node specified by Node to the value specified by Length. Length is returned.\r
+\r
+ @param Node A pointer to a device path node data structure.\r
+ @param Length The length, in bytes, of the device path node.\r
+\r
+ @return Length\r
+\r
+**/\r
#define SetDevicePathNodeLength(Node,NodeLength) WriteUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0], (UINT16)(NodeLength))\r
+\r
+/**\r
+ Macro that fills in all the fields of a device path node that is the end of an entire device path.\r
+\r
+ Fills in all the fields of a device path node specified by Node so Node represents the end of an entire device path.\r
+\r
+ @param Node A pointer to a device path node data structure.\r
+\r
+**/\r
#define SetDevicePathEndNode(Node) { \\r
DevicePathType (Node) = END_DEVICE_PATH_TYPE; \\r
DevicePathSubType (Node) = END_ENTIRE_DEVICE_PATH_SUBTYPE; \\r
DevicePath including the end of device path node. If DevicePath is NULL, then 0 is returned.\r
\r
@param DevicePath A pointer to a device path data structure.\r
-\r
- @return The size of a device path in bytes.\r
+ \r
+ @retval 0 If DevicePath is NULL.\r
+ @retval Others The size of a device path in bytes.\r
\r
**/\r
UINTN\r
DevicePath is NULL, then NULL is returned. If the memory is successfully allocated, then the\r
contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer\r
is returned. Otherwise, NULL is returned. \r
+ The memory for the new device path is allocated from EFI boot services memory. \r
+ It is the responsibility of the caller to free the memory allocated. \r
\r
@param DevicePath A pointer to a device path data structure.\r
\r
- @return A pointer to the duplicated device path.\r
-\r
+ @retval NULL If DevicePath is NULL.\r
+ @retval Others A pointer to the duplicated device path.\r
+ \r
**/\r
EFI_DEVICE_PATH_PROTOCOL *\r
EFIAPI\r
\r
@param FirstDevicePath A pointer to a device path data structure.\r
@param SecondDevicePath A pointer to a device path data structure.\r
-\r
- @return A pointer to the new device path.\r
+ \r
+ @retval NULL If there is not enough memory for the newly allocated buffer.\r
+ @retval Others A pointer to the new device path if success.\r
+ Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.\r
\r
**/\r
EFI_DEVICE_PATH_PROTOCOL *\r
@param DevicePath A pointer to a device path data structure.\r
@param DevicePathNode A pointer to a single device path node.\r
\r
- @return A pointer to the new device path.\r
+ @retval NULL If there is not enough memory for the new device path.\r
+ @retval Others A pointer to the new device path if success.\r
+ A copy of DevicePathNode followed by an end-of-device-path node \r
+ if both FirstDevicePath and SecondDevicePath are NULL.\r
+ A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL.\r
\r
**/\r
EFI_DEVICE_PATH_PROTOCOL *\r
);\r
\r
/**\r
- Creates a copy of the current device path instance and returns a pointer to the next device path\r
- instance.\r
+ Creates a device node.\r
\r
This function creates a new device node in a newly allocated buffer of size NodeLength and\r
initializes the device path node header with NodeType and NodeSubType. The new device path node\r
handle Device. The allocated device path is returned. If Device is NULL or Device is a handle\r
that does not support the device path protocol, then a device path containing a single device\r
path node for the file specified by FileName is allocated and returned.\r
+ The memory for the new device path is allocated from EFI boot services memory. It is the responsibility\r
+ of the caller to free the memory allocated.\r
+ \r
If FileName is NULL, then ASSERT().\r
+ If FileName is not aligned on a 16-bit boundary, then ASSERT().\r
\r
@param Device A pointer to a device handle. This parameter is optional and\r
may be NULL.\r
projects / mirror_edk2.git / blobdiff