MdePkg/Include/Library/DevicePathLib.h

   1 /** @file
   2   Device Path services.
   3
   4   Copyright (c) 2006, Intel Corporation
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __DEVICE_PATH_LIB_H__
  16 #define __DEVICE_PATH_LIB_H__
  17
  18 #include <Library/BaseLib.h>
  19
  20 #define END_DEVICE_PATH_LENGTH               (sizeof (EFI_DEVICE_PATH_PROTOCOL))
  21 #define DevicePathNodeLength(Node)           ReadUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0])
  22 #define NextDevicePathNode(Node)             ((EFI_DEVICE_PATH_PROTOCOL *)((UINT8 *)(Node) + DevicePathNodeLength(Node)))
  23 #define DevicePathType(Node)                 (((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Type)
  24 #define DevicePathSubType(Node)              (((EFI_DEVICE_PATH_PROTOCOL *)(Node))->SubType)
  25 #define IsDevicePathEndType(Node)            (DevicePathType (Node) == END_DEVICE_PATH_TYPE)
  26 #define IsDevicePathEnd(Node)                (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_ENTIRE_DEVICE_PATH_SUBTYPE)
  27 #define IsDevicePathEndInstance(Node)        (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_INSTANCE_DEVICE_PATH_SUBTYPE)
  28
  29 #define SetDevicePathNodeLength(Node,NodeLength)  WriteUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0], (UINT16)(NodeLength))
  30 #define SetDevicePathEndNode(Node)  {                                   \
  31           DevicePathType (Node)    = END_DEVICE_PATH_TYPE;              \
  32           DevicePathSubType (Node) = END_ENTIRE_DEVICE_PATH_SUBTYPE;    \
  33           SetDevicePathNodeLength ((Node), END_DEVICE_PATH_LENGTH);       \
  34           }
  35
  36 /**
  37   Returns the size of a device path in bytes.
  38
  39   This function returns the size, in bytes, of the device path data structure specified by
  40   DevicePath including the end of device path node.  If DevicePath is NULL, then 0 is returned.
  41
  42   @param  DevicePath                 A pointer to a device path data structure.
  43
  44   @return The size of a device path in bytes.
  45
  46 **/
  47 UINTN
  48 EFIAPI
  49 GetDevicePathSize (
  50   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
  51   );
  52
  53 /**
  54   Creates a new device path by appending a second device path to a first device path.
  55
  56   This function allocates space for a new copy of the device path specified by DevicePath.  If
  57   DevicePath is NULL, then NULL is returned.  If the memory is successfully allocated, then the
  58   contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer
  59   is returned.  Otherwise, NULL is returned.
  60
  61   @param  DevicePath                 A pointer to a device path data structure.
  62
  63   @return A pointer to the duplicated device path.
  64
  65 **/
  66 EFI_DEVICE_PATH_PROTOCOL *
  67 EFIAPI
  68 DuplicateDevicePath (
  69   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
  70   );
  71
  72 /**
  73   Creates a new device path by appending a second device path to a first device path.
  74
  75   This function creates a new device path by appending a copy of SecondDevicePath to a copy of
  76   FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path device node from
  77   SecondDevicePath is retained. The newly created device path is returned.
  78   If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned.
  79   If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned.
  80   If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is
  81   returned.
  82   If there is not enough memory for the newly allocated buffer, then NULL is returned.
  83   The memory for the new device path is allocated from EFI boot services memory. It is the
  84   responsibility of the caller to free the memory allocated.
  85
  86   @param  FirstDevicePath            A pointer to a device path data structure.
  87   @param  SecondDevicePath           A pointer to a device path data structure.
  88
  89   @return A pointer to the new device path.
  90
  91 **/
  92 EFI_DEVICE_PATH_PROTOCOL *
  93 EFIAPI
  94 AppendDevicePath (
  95   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,  OPTIONAL
  96   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath  OPTIONAL
  97   );
  98
  99 /**
 100   Creates a new path by appending the device node to the device path.
 101
 102   This function creates a new device path by appending a copy of the device node specified by
 103   DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer.
 104   The end-of-device-path device node is moved after the end of the appended device node.
 105   If DevicePathNode is NULL then a copy of DevicePath is returned.
 106   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device path device
 107   node is returned.
 108   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node
 109   is returned.
 110   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 111   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 112   free the memory allocated.
 113
 114   @param  DevicePath                 A pointer to a device path data structure.
 115   @param  DevicePathNode             A pointer to a single device path node.
 116
 117   @return A pointer to the new device path.
 118
 119 **/
 120 EFI_DEVICE_PATH_PROTOCOL *
 121 EFIAPI
 122 AppendDevicePathNode (
 123   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,     OPTIONAL
 124   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode  OPTIONAL
 125   );
 126
 127 /**
 128   Creates a new device path by appending the specified device path instance to the specified device
 129   path.
 130
 131   This function creates a new device path by appending a copy of the device path instance specified
 132   by DevicePathInstance to a copy of the device path secified by DevicePath in a allocated buffer.
 133   The end-of-device-path device node is moved after the end of the appended device path instance
 134   and a new end-of-device-path-instance node is inserted between.
 135   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
 136   If DevicePathInstance is NULL, then NULL is returned.
 137   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 138   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 139   free the memory allocated.
 140
 141   @param  DevicePath                 A pointer to a device path data structure.
 142   @param  DevicePathInstance         A pointer to a device path instance.
 143
 144   @return A pointer to the new device path.
 145
 146 **/
 147 EFI_DEVICE_PATH_PROTOCOL *
 148 EFIAPI
 149 AppendDevicePathInstance (
 150   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,        OPTIONAL
 151   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathInstance OPTIONAL
 152   );
 153
 154 /**
 155   Creates a copy of the current device path instance and returns a pointer to the next device path
 156   instance.
 157
 158   This function creates a copy of the current device path instance. It also updates DevicePath to
 159   point to the next device path instance in the device path (or NULL if no more) and updates Size
 160   to hold the size of the device path instance copy.
 161   If DevicePath is NULL, then NULL is returned.
 162   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 163   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 164   free the memory allocated.
 165   If Size is NULL, then ASSERT().
 166
 167   @param  DevicePath                 On input, this holds the pointer to the current device path
 168                                      instance. On output, this holds the pointer to the next device
 169                                      path instance or NULL if there are no more device path
 170                                      instances in the device path pointer to a device path data
 171                                      structure.
 172   @param  Size                       On output, this holds the size of the device path instance, in
 173                                      bytes or zero, if DevicePath is NULL.
 174
 175   @return A pointer to the current device path instance.
 176
 177 **/
 178 EFI_DEVICE_PATH_PROTOCOL *
 179 EFIAPI
 180 GetNextDevicePathInstance (
 181   IN OUT EFI_DEVICE_PATH_PROTOCOL    **DevicePath,
 182   OUT UINTN                          *Size
 183   );
 184
 185 /**
 186   Creates a copy of the current device path instance and returns a pointer to the next device path
 187   instance.
 188
 189   This function creates a new device node in a newly allocated buffer of size NodeLength and
 190   initializes the device path node header with NodeType and NodeSubType.  The new device path node
 191   is returned.
 192   If NodeLength is smaller than a device path header, then NULL is returned.
 193   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 194   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 195   free the memory allocated.
 196
 197   @param  NodeType                   The device node type for the new device node.
 198   @param  NodeSubType                The device node sub-type for the new device node.
 199   @param  NodeLength                 The length of the new device node.
 200
 201   @return The new device path.
 202
 203 **/
 204 EFI_DEVICE_PATH_PROTOCOL *
 205 EFIAPI
 206 CreateDeviceNode (
 207   IN UINT8                           NodeType,
 208   IN UINT8                           NodeSubType,
 209   IN UINT16                          NodeLength
 210   );
 211
 212 /**
 213   Determines if a device path is single or multi-instance.
 214
 215   This function returns TRUE if the device path specified by DevicePath is multi-instance.
 216   Otherwise, FALSE is returned.  If DevicePath is NULL, then FALSE is returned.
 217
 218   @param  DevicePath                 A pointer to a device path data structure.
 219
 220   @retval  TRUE                      DevicePath is multi-instance.
 221   @retval  FALSE                     DevicePath is not multi-instance or DevicePath is NULL.
 222
 223 **/
 224 BOOLEAN
 225 EFIAPI
 226 IsDevicePathMultiInstance (
 227   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 228   );
 229
 230 /**
 231   Retrieves the device path protocol from a handle.
 232
 233   This function returns the device path protocol from the handle specified by Handle.  If Handle is
 234   NULL or Handle does not contain a device path protocol, then NULL is returned.
 235
 236   @param  Handle                     The handle from which to retrieve the device path protocol.
 237
 238   @return The device path protocol from the handle specified by Handle.
 239
 240 **/
 241 EFI_DEVICE_PATH_PROTOCOL *
 242 EFIAPI
 243 DevicePathFromHandle (
 244   IN EFI_HANDLE                      Handle
 245   );
 246
 247 /**
 248   Allocates a device path for a file and appends it to an existing device path.
 249
 250   If Device is a valid device handle that contains a device path protocol, then a device path for
 251   the file specified by FileName  is allocated and appended to the device path associated with the
 252   handle Device.  The allocated device path is returned.  If Device is NULL or Device is a handle
 253   that does not support the device path protocol, then a device path containing a single device
 254   path node for the file specified by FileName is allocated and returned.
 255   If FileName is NULL, then ASSERT().
 256
 257   @param  Device                     A pointer to a device handle.  This parameter is optional and
 258                                      may be NULL.
 259   @param  FileName                   A pointer to a Null-terminated Unicode string.
 260
 261   @return The allocated device path.
 262
 263 **/
 264 EFI_DEVICE_PATH_PROTOCOL *
 265 EFIAPI
 266 FileDevicePath (
 267   IN EFI_HANDLE                      Device,     OPTIONAL
 268   IN CONST CHAR16                    *FileName
 269   );
 270
 271 #endif