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