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