MdePkg/Include/Library/DevicePathLib.h

   1 /** @file
   2   Provides library functions to construct and parse UEFI Device Paths.
   3
   4   This library provides defines, macros, and functions to help create and parse
   5   EFI_DEVICE_PATH_PROTOCOL structures.  The macros that help create and parse device
   6   path nodes make use of the ReadUnaligned16() and WriteUnaligned16() functions from
   7   the Base Library, so this library class has an implied dependency on the Base Library.
   8
   9 Copyright (c) 2006 - 2008, Intel Corporation<BR>
  10 All rights reserved. This program and the accompanying materials
  11 are licensed and made available under the terms and conditions of the BSD License
  12 which accompanies this distribution.  The full text of the license may be found at
  13 http://opensource.org/licenses/bsd-license.php
  14
  15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  16 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  17
  18 **/
  19
  20 #ifndef __DEVICE_PATH_LIB_H__
  21 #define __DEVICE_PATH_LIB_H__
  22
  23 #define END_DEVICE_PATH_LENGTH               (sizeof (EFI_DEVICE_PATH_PROTOCOL))
  24
  25 /**
  26   Returns the Type field of a device path node.
  27
  28   Returns the Type field of the device path node specified by Node.
  29
  30   If Node is NULL, then ASSERT().
  31
  32   @param  Node      A pointer to a device path node data structure.
  33
  34   @return The Type field of the device path node specified by Node.
  35
  36 **/
  37 UINT8
  38 DevicePathType (
  39   IN CONST VOID  *Node
  40   );
  41
  42 /**
  43   Returns the SubType field of a device path node.
  44
  45   Returns the SubType field of the device path node specified by Node.
  46
  47   If Node is NULL, then ASSERT().
  48
  49   @param  Node      A pointer to a device path node data structure.
  50
  51   @return The SubType field of the device path node specified by Node.
  52
  53 **/
  54 UINT8
  55 DevicePathSubType (
  56   IN CONST VOID  *Node
  57   );
  58
  59 /**
  60   Returns the 16-bit Length field of a device path node.
  61
  62   Returns the 16-bit Length field of the device path node specified by Node.
  63   Node is not required to be aligned on a 16-bit boundary, so it is recommended
  64   that a function such as ReadUnaligned16() be used to extract the contents of
  65   the Length field.
  66
  67   If Node is NULL, then ASSERT().
  68
  69   @param  Node      A pointer to a device path node data structure.
  70
  71   @return The 16-bit Length field of the device path node specified by Node.
  72
  73 **/
  74 UINTN
  75 DevicePathNodeLength (
  76   IN CONST VOID  *Node
  77   );
  78
  79 /**
  80   Returns a pointer to the next node in a device path.
  81
  82   Returns a pointer to the device path node that follows the device path node specified by Node.
  83
  84   If Node is NULL, then ASSERT().
  85
  86   @param  Node      A pointer to a device path node data structure.
  87
  88   @return a pointer to the device path node that follows the device path node specified by Node.
  89
  90 **/
  91 EFI_DEVICE_PATH_PROTOCOL *
  92 NextDevicePathNode (
  93   IN CONST VOID  *Node
  94   );
  95
  96 /**
  97   Determines if a device path node is an end node of a device path.
  98   This includes nodes that are the end of a device path instance and nodes that are the end of an entire device path.
  99
 100   Determines if the device path node specified by Node is an end node of a device path.
 101   This includes nodes that are the end of a device path instance and nodes that are the
 102   end of an entire device path.  If Node represents an end node of a device path,
 103   then TRUE is returned.  Otherwise, FALSE is returned.
 104
 105   If Node is NULL, then ASSERT().
 106
 107   @param  Node      A pointer to a device path node data structure.
 108
 109   @retval TRUE      The device path node specified by Node is an end node of a device path.
 110   @retval FALSE     The device path node specified by Node is not an end node of a device path.
 111
 112 **/
 113 BOOLEAN
 114 IsDevicePathEndType (
 115   IN CONST VOID  *Node
 116   );
 117
 118 /**
 119   Determines if a device path node is an end node of an entire device path.
 120
 121   Determines if a device path node specified by Node is an end node of an entire device path.
 122   If Node represents the end of an entire device path, then TRUE is returned.  Otherwise, FALSE is returned.
 123
 124   If Node is NULL, then ASSERT().
 125
 126   @param  Node      A pointer to a device path node data structure.
 127
 128   @retval TRUE      The device path node specified by Node is the end of an entire device path.
 129   @retval FALSE     The device path node specified by Node is not the end of an entire device path.
 130
 131 **/
 132 BOOLEAN
 133 IsDevicePathEnd (
 134   IN CONST VOID  *Node
 135   );
 136
 137 /**
 138   Determines if a device path node is an end node of a device path instance.
 139
 140   Determines if a device path node specified by Node is an end node of a device path instance.
 141   If Node represents the end of a device path instance, then TRUE is returned.  Otherwise, FALSE is returned.
 142
 143   If Node is NULL, then ASSERT().
 144
 145   @param  Node      A pointer to a device path node data structure.
 146
 147   @retval TRUE      The device path node specified by Node is the end of a device path instance.
 148   @retval FALSE     The device path node specified by Node is not the end of a device path instance.
 149
 150 **/
 151 BOOLEAN
 152 IsDevicePathEndInstance (
 153   IN CONST VOID  *Node
 154   );
 155
 156 /**
 157   Sets the length, in bytes, of a device path node.
 158
 159   Sets the length of the device path node specified by Node to the value specified
 160   by NodeLength.  NodeLength is returned.  Node is not required to be aligned on
 161   a 16-bit boundary, so it is recommended that a function such as WriteUnaligned16()
 162   be used to set the contents of the Length field.
 163
 164   If Node is NULL, then ASSERT().
 165   If NodeLength >= 0x10000, then ASSERT().
 166
 167   @param  Node      A pointer to a device path node data structure.
 168   @param  Length    The length, in bytes, of the device path node.
 169
 170   @return Length
 171
 172 **/
 173 UINT16
 174 SetDevicePathNodeLength (
 175   IN VOID   *Node,
 176   IN UINTN  Length
 177   );
 178
 179 /**
 180   Fills in all the fields of a device path node that is the end of an entire device path.
 181
 182   Fills in all the fields of a device path node specified by Node so Node represents
 183   the end of an entire device path.  The Type field of Node is set to
 184   END_DEVICE_PATH_TYPE, the SubType field of Node is set to
 185   END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to
 186   END_DEVICE_PATH_LENGTH.  Node is not required to be aligned on a 16-bit boundary,
 187   so it is recommended that a function such as WriteUnaligned16() be used to set
 188   the contents of the Length field.
 189
 190   If Node is NULL, then ASSERT().
 191
 192   @param  Node      A pointer to a device path node data structure.
 193
 194 **/
 195 VOID
 196 SetDevicePathEndNode (
 197   IN VOID  *Node
 198   );
 199
 200 /**
 201   Returns the size of a device path in bytes.
 202
 203   This function returns the size, in bytes, of the device path data structure specified by
 204   DevicePath including the end of device path node.  If DevicePath is NULL, then 0 is returned.
 205
 206   @param  DevicePath                 A pointer to a device path data structure.
 207
 208   @retval 0       If DevicePath is NULL.
 209   @retval Others  The size of a device path in bytes.
 210
 211 **/
 212 UINTN
 213 EFIAPI
 214 GetDevicePathSize (
 215   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 216   );
 217
 218 /**
 219   Creates a new copy of an existing device path.
 220
 221   This function allocates space for a new copy of the device path specified by DevicePath.  If
 222   DevicePath is NULL, then NULL is returned.  If the memory is successfully allocated, then the
 223   contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer
 224   is returned.  Otherwise, NULL is returned.
 225   The memory for the new device path is allocated from EFI boot services memory.
 226   It is the responsibility of the caller to free the memory allocated.
 227
 228   @param  DevicePath                 A pointer to a device path data structure.
 229
 230   @retval NULL    If DevicePath is NULL.
 231   @retval Others  A pointer to the duplicated device path.
 232
 233 **/
 234 EFI_DEVICE_PATH_PROTOCOL *
 235 EFIAPI
 236 DuplicateDevicePath (
 237   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 238   );
 239
 240 /**
 241   Creates a new device path by appending a second device path to a first device path.
 242
 243   This function creates a new device path by appending a copy of SecondDevicePath to a copy of
 244   FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path device node from
 245   SecondDevicePath is retained. The newly created device path is returned.
 246   If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned.
 247   If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned.
 248   If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is
 249   returned.
 250   If there is not enough memory for the newly allocated buffer, then NULL is returned.
 251   The memory for the new device path is allocated from EFI boot services memory. It is the
 252   responsibility of the caller to free the memory allocated.
 253
 254   @param  FirstDevicePath            A pointer to a device path data structure.
 255   @param  SecondDevicePath           A pointer to a device path data structure.
 256
 257   @retval NULL      If there is not enough memory for the newly allocated buffer.
 258   @retval Others    A pointer to the new device path if success.
 259                     Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
 260
 261 **/
 262 EFI_DEVICE_PATH_PROTOCOL *
 263 EFIAPI
 264 AppendDevicePath (
 265   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,  OPTIONAL
 266   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath  OPTIONAL
 267   );
 268
 269 /**
 270   Creates a new path by appending the device node to the device path.
 271
 272   This function creates a new device path by appending a copy of the device node specified by
 273   DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer.
 274   The end-of-device-path device node is moved after the end of the appended device node.
 275   If DevicePathNode is NULL then a copy of DevicePath is returned.
 276   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device path device
 277   node is returned.
 278   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node
 279   is returned.
 280   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 281   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 282   free the memory allocated.
 283
 284   @param  DevicePath                 A pointer to a device path data structure.
 285   @param  DevicePathNode             A pointer to a single device path node.
 286
 287   @retval NULL      If there is not enough memory for the new device path.
 288   @retval Others    A pointer to the new device path if success.
 289                     A copy of DevicePathNode followed by an end-of-device-path node
 290                     if both FirstDevicePath and SecondDevicePath are NULL.
 291                     A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL.
 292
 293 **/
 294 EFI_DEVICE_PATH_PROTOCOL *
 295 EFIAPI
 296 AppendDevicePathNode (
 297   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,     OPTIONAL
 298   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode  OPTIONAL
 299   );
 300
 301 /**
 302   Creates a new device path by appending the specified device path instance to the specified device
 303   path.
 304
 305   This function creates a new device path by appending a copy of the device path instance specified
 306   by DevicePathInstance to a copy of the device path secified by DevicePath in a allocated buffer.
 307   The end-of-device-path device node is moved after the end of the appended device path instance
 308   and a new end-of-device-path-instance node is inserted between.
 309   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
 310   If DevicePathInstance is NULL, then NULL is returned.
 311   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 312   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 313   free the memory allocated.
 314
 315   @param  DevicePath                 A pointer to a device path data structure.
 316   @param  DevicePathInstance         A pointer to a device path instance.
 317
 318   @return A pointer to the new device path.
 319
 320 **/
 321 EFI_DEVICE_PATH_PROTOCOL *
 322 EFIAPI
 323 AppendDevicePathInstance (
 324   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,        OPTIONAL
 325   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathInstance OPTIONAL
 326   );
 327
 328 /**
 329   Creates a copy of the current device path instance and returns a pointer to the next device path
 330   instance.
 331
 332   This function creates a copy of the current device path instance. It also updates DevicePath to
 333   point to the next device path instance in the device path (or NULL if no more) and updates Size
 334   to hold the size of the device path instance copy.
 335   If DevicePath is NULL, then NULL is returned.
 336   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 337   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 338   free the memory allocated.
 339   If Size is NULL, then ASSERT().
 340
 341   @param  DevicePath                 On input, this holds the pointer to the current device path
 342                                      instance. On output, this holds the pointer to the next device
 343                                      path instance or NULL if there are no more device path
 344                                      instances in the device path pointer to a device path data
 345                                      structure.
 346   @param  Size                       On output, this holds the size of the device path instance, in
 347                                      bytes or zero, if DevicePath is NULL.
 348
 349   @return A pointer to the current device path instance.
 350
 351 **/
 352 EFI_DEVICE_PATH_PROTOCOL *
 353 EFIAPI
 354 GetNextDevicePathInstance (
 355   IN OUT EFI_DEVICE_PATH_PROTOCOL    **DevicePath,
 356   OUT UINTN                          *Size
 357   );
 358
 359 /**
 360   Creates a device node.
 361
 362   This function creates a new device node in a newly allocated buffer of size NodeLength and
 363   initializes the device path node header with NodeType and NodeSubType.  The new device path node
 364   is returned.
 365   If NodeLength is smaller than a device path header, then NULL is returned.
 366   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 367   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 368   free the memory allocated.
 369
 370   @param  NodeType                   The device node type for the new device node.
 371   @param  NodeSubType                The device node sub-type for the new device node.
 372   @param  NodeLength                 The length of the new device node.
 373
 374   @return The new device path.
 375
 376 **/
 377 EFI_DEVICE_PATH_PROTOCOL *
 378 EFIAPI
 379 CreateDeviceNode (
 380   IN UINT8                           NodeType,
 381   IN UINT8                           NodeSubType,
 382   IN UINT16                          NodeLength
 383   );
 384
 385 /**
 386   Determines if a device path is single or multi-instance.
 387
 388   This function returns TRUE if the device path specified by DevicePath is multi-instance.
 389   Otherwise, FALSE is returned.  If DevicePath is NULL, then FALSE is returned.
 390
 391   @param  DevicePath                 A pointer to a device path data structure.
 392
 393   @retval  TRUE                      DevicePath is multi-instance.
 394   @retval  FALSE                     DevicePath is not multi-instance or DevicePath is NULL.
 395
 396 **/
 397 BOOLEAN
 398 EFIAPI
 399 IsDevicePathMultiInstance (
 400   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 401   );
 402
 403 /**
 404   Retrieves the device path protocol from a handle.
 405
 406   This function returns the device path protocol from the handle specified by Handle.  If Handle is
 407   NULL or Handle does not contain a device path protocol, then NULL is returned.
 408
 409   @param  Handle                     The handle from which to retrieve the device path protocol.
 410
 411   @return The device path protocol from the handle specified by Handle.
 412
 413 **/
 414 EFI_DEVICE_PATH_PROTOCOL *
 415 EFIAPI
 416 DevicePathFromHandle (
 417   IN EFI_HANDLE                      Handle
 418   );
 419
 420 /**
 421   Allocates a device path for a file and appends it to an existing device path.
 422
 423   If Device is a valid device handle that contains a device path protocol, then a device path for
 424   the file specified by FileName  is allocated and appended to the device path associated with the
 425   handle Device.  The allocated device path is returned.  If Device is NULL or Device is a handle
 426   that does not support the device path protocol, then a device path containing a single device
 427   path node for the file specified by FileName is allocated and returned.
 428   The memory for the new device path is allocated from EFI boot services memory. It is the responsibility
 429   of the caller to free the memory allocated.
 430
 431   If FileName is NULL, then ASSERT().
 432   If FileName is not aligned on a 16-bit boundary, then ASSERT().
 433
 434   @param  Device                     A pointer to a device handle.  This parameter is optional and
 435                                      may be NULL.
 436   @param  FileName                   A pointer to a Null-terminated Unicode string.
 437
 438   @return The allocated device path.
 439
 440 **/
 441 EFI_DEVICE_PATH_PROTOCOL *
 442 EFIAPI
 443 FileDevicePath (
 444   IN EFI_HANDLE                      Device,     OPTIONAL
 445   IN CONST CHAR16                    *FileName
 446   );
 447
 448 #endif