MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.c

   1 /** @file
   2   Device Path services. The thing to remember is device paths are built out of
   3   nodes. The device path is terminated by an end node that is length
   4   sizeof(EFI_DEVICE_PATH_PROTOCOL). That would be why there is sizeof(EFI_DEVICE_PATH_PROTOCOL)
   5   all over this file.
   6
   7   The only place where multi-instance device paths are supported is in
   8   environment varibles. Multi-instance device paths should never be placed
   9   on a Handle.
  10
  11   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
  12   SPDX-License-Identifier: BSD-2-Clause-Patent
  13
  14 **/
  15
  16 #include "UefiDevicePathLib.h"
  17
  18 /**
  19   Returns the size of a device path in bytes.
  20
  21   This function returns the size, in bytes, of the device path data structure
  22   specified by DevicePath including the end of device path node.
  23   If DevicePath is NULL or invalid, then 0 is returned.
  24
  25   @param  DevicePath  A pointer to a device path data structure.
  26
  27   @retval 0           If DevicePath is NULL or invalid.
  28   @retval Others      The size of a device path in bytes.
  29
  30 **/
  31 UINTN
  32 EFIAPI
  33 GetDevicePathSize (
  34   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
  35   )
  36 {
  37   return UefiDevicePathLibGetDevicePathSize (DevicePath);
  38 }
  39
  40 /**
  41   Creates a new copy of an existing device path.
  42
  43   This function allocates space for a new copy of the device path specified by DevicePath.
  44   If DevicePath is NULL, then NULL is returned.  If the memory is successfully
  45   allocated, then the contents of DevicePath are copied to the newly allocated
  46   buffer, and a pointer to that buffer is returned.  Otherwise, NULL is returned.
  47   The memory for the new device path is allocated from EFI boot services memory.
  48   It is the responsibility of the caller to free the memory allocated.
  49
  50   @param  DevicePath    A pointer to a device path data structure.
  51
  52   @retval NULL          DevicePath is NULL or invalid.
  53   @retval Others        A pointer to the duplicated device path.
  54
  55 **/
  56 EFI_DEVICE_PATH_PROTOCOL *
  57 EFIAPI
  58 DuplicateDevicePath (
  59   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
  60   )
  61 {
  62   return UefiDevicePathLibDuplicateDevicePath (DevicePath);
  63 }
  64
  65 /**
  66   Creates a new device path by appending a second device path to a first device path.
  67
  68   This function creates a new device path by appending a copy of SecondDevicePath
  69   to a copy of FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path
  70   device node from SecondDevicePath is retained. The newly created device path is
  71   returned. If FirstDevicePath is NULL, then it is ignored, and a duplicate of
  72   SecondDevicePath is returned.  If SecondDevicePath is NULL, then it is ignored,
  73   and a duplicate of FirstDevicePath is returned. If both FirstDevicePath and
  74   SecondDevicePath are NULL, then a copy of an end-of-device-path is returned.
  75
  76   If there is not enough memory for the newly allocated buffer, then NULL is returned.
  77   The memory for the new device path is allocated from EFI boot services memory.
  78   It is the responsibility of the caller to free the memory allocated.
  79
  80   @param  FirstDevicePath            A pointer to a device path data structure.
  81   @param  SecondDevicePath           A pointer to a device path data structure.
  82
  83   @retval NULL      If there is not enough memory for the newly allocated buffer.
  84   @retval NULL      If FirstDevicePath or SecondDevicePath is invalid.
  85   @retval Others    A pointer to the new device path if success.
  86                     Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
  87
  88 **/
  89 EFI_DEVICE_PATH_PROTOCOL *
  90 EFIAPI
  91 AppendDevicePath (
  92   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath   OPTIONAL,
  93   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath  OPTIONAL
  94   )
  95 {
  96   return UefiDevicePathLibAppendDevicePath (FirstDevicePath, SecondDevicePath);
  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
 103   specified by DevicePathNode to a copy of the device path specified by DevicePath
 104   in an allocated buffer. The end-of-device-path device node is moved after the
 105   end of the appended device node.
 106   If DevicePathNode is NULL then a copy of DevicePath is returned.
 107   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device
 108   path device node is returned.
 109   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path
 110   device node is returned.
 111   If there is not enough memory to allocate space for the new device path, then
 112   NULL is returned.
 113   The memory is allocated from EFI boot services memory. It is the responsibility
 114   of the caller to free the memory allocated.
 115
 116   @param  DevicePath                 A pointer to a device path data structure.
 117   @param  DevicePathNode             A pointer to a single device path node.
 118
 119   @retval NULL      If there is not enough memory for the new device path.
 120   @retval Others    A pointer to the new device path if success.
 121                     A copy of DevicePathNode followed by an end-of-device-path node
 122                     if both FirstDevicePath and SecondDevicePath are NULL.
 123                     A copy of an end-of-device-path node if both FirstDevicePath
 124                     and SecondDevicePath are NULL.
 125
 126 **/
 127 EFI_DEVICE_PATH_PROTOCOL *
 128 EFIAPI
 129 AppendDevicePathNode (
 130   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath      OPTIONAL,
 131   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode  OPTIONAL
 132   )
 133 {
 134   return UefiDevicePathLibAppendDevicePathNode (DevicePath, DevicePathNode);
 135 }
 136
 137 /**
 138   Creates a new device path by appending the specified device path instance to the specified device
 139   path.
 140
 141   This function creates a new device path by appending a copy of the device path
 142   instance specified by DevicePathInstance to a copy of the device path specified
 143   by DevicePath in a allocated buffer.
 144   The end-of-device-path device node is moved after the end of the appended device
 145   path instance and a new end-of-device-path-instance node is inserted between.
 146   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
 147   If DevicePathInstance is NULL, then NULL is returned.
 148   If DevicePath or DevicePathInstance is invalid, then NULL is returned.
 149   If there is not enough memory to allocate space for the new device path, then
 150   NULL is returned.
 151   The memory is allocated from EFI boot services memory. It is the responsibility
 152   of the caller to free the memory allocated.
 153
 154   @param  DevicePath                 A pointer to a device path data structure.
 155   @param  DevicePathInstance         A pointer to a device path instance.
 156
 157   @return A pointer to the new device path.
 158
 159 **/
 160 EFI_DEVICE_PATH_PROTOCOL *
 161 EFIAPI
 162 AppendDevicePathInstance (
 163   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath         OPTIONAL,
 164   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathInstance OPTIONAL
 165   )
 166 {
 167   return UefiDevicePathLibAppendDevicePathInstance (DevicePath, DevicePathInstance);
 168 }
 169
 170 /**
 171   Creates a copy of the current device path instance and returns a pointer to the next device path
 172   instance.
 173
 174   This function creates a copy of the current device path instance. It also updates
 175   DevicePath to point to the next device path instance in the device path (or NULL
 176   if no more) and updates Size to hold the size of the device path instance copy.
 177   If DevicePath is NULL, then NULL is returned.
 178   If DevicePath points to a invalid device path, then NULL is returned.
 179   If there is not enough memory to allocate space for the new device path, then
 180   NULL is returned.
 181   The memory is allocated from EFI boot services memory. It is the responsibility
 182   of the caller to free the memory allocated.
 183   If Size is NULL, then ASSERT().
 184
 185   @param  DevicePath                 On input, this holds the pointer to the current
 186                                      device path instance. On output, this holds
 187                                      the pointer to the next device path instance
 188                                      or NULL if there are no more device path
 189                                      instances in the device path pointer to a
 190                                      device path data structure.
 191   @param  Size                       On output, this holds the size of the device
 192                                      path instance, in bytes or zero, if DevicePath
 193                                      is NULL.
 194
 195   @return A pointer to the current device path instance.
 196
 197 **/
 198 EFI_DEVICE_PATH_PROTOCOL *
 199 EFIAPI
 200 GetNextDevicePathInstance (
 201   IN OUT EFI_DEVICE_PATH_PROTOCOL  **DevicePath,
 202   OUT UINTN                        *Size
 203   )
 204 {
 205   return UefiDevicePathLibGetNextDevicePathInstance (DevicePath, Size);
 206 }
 207
 208 /**
 209   Creates a device node.
 210
 211   This function creates a new device node in a newly allocated buffer of size
 212   NodeLength and initializes the device path node header with NodeType and NodeSubType.
 213   The new device path node is returned.
 214   If NodeLength is smaller than a device path header, then NULL is returned.
 215   If there is not enough memory to allocate space for the new device path, then
 216   NULL is returned.
 217   The memory is allocated from EFI boot services memory. It is the responsibility
 218   of the caller to free the memory allocated.
 219
 220   @param  NodeType                   The device node type for the new device node.
 221   @param  NodeSubType                The device node sub-type for the new device node.
 222   @param  NodeLength                 The length of the new device node.
 223
 224   @return The new device path.
 225
 226 **/
 227 EFI_DEVICE_PATH_PROTOCOL *
 228 EFIAPI
 229 CreateDeviceNode (
 230   IN UINT8   NodeType,
 231   IN UINT8   NodeSubType,
 232   IN UINT16  NodeLength
 233   )
 234 {
 235   return UefiDevicePathLibCreateDeviceNode (NodeType, NodeSubType, NodeLength);
 236 }
 237
 238 /**
 239   Determines if a device path is single or multi-instance.
 240
 241   This function returns TRUE if the device path specified by DevicePath is
 242   multi-instance.
 243   Otherwise, FALSE is returned.
 244   If DevicePath is NULL or invalid, then FALSE is returned.
 245
 246   @param  DevicePath                 A pointer to a device path data structure.
 247
 248   @retval  TRUE                      DevicePath is multi-instance.
 249   @retval  FALSE                     DevicePath is not multi-instance, or DevicePath
 250                                      is NULL or invalid.
 251
 252 **/
 253 BOOLEAN
 254 EFIAPI
 255 IsDevicePathMultiInstance (
 256   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 257   )
 258 {
 259   return UefiDevicePathLibIsDevicePathMultiInstance (DevicePath);
 260 }
 261
 262 /**
 263   Converts a device node to its string representation.
 264
 265   @param DeviceNode        A Pointer to the device node to be converted.
 266   @param DisplayOnly       If DisplayOnly is TRUE, then the shorter text representation
 267                            of the display node is used, where applicable. If DisplayOnly
 268                            is FALSE, then the longer text representation of the display node
 269                            is used.
 270   @param AllowShortcuts    If AllowShortcuts is TRUE, then the shortcut forms of text
 271                            representation for a device node can be used, where applicable.
 272
 273   @return A pointer to the allocated text representation of the device node or NULL if DeviceNode
 274           is NULL or there was insufficient memory.
 275
 276 **/
 277 CHAR16 *
 278 EFIAPI
 279 ConvertDeviceNodeToText (
 280   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DeviceNode,
 281   IN BOOLEAN                         DisplayOnly,
 282   IN BOOLEAN                         AllowShortcuts
 283   )
 284 {
 285   return UefiDevicePathLibConvertDeviceNodeToText (DeviceNode, DisplayOnly, AllowShortcuts);
 286 }
 287
 288 /**
 289   Converts a device path to its text representation.
 290
 291   @param DevicePath      A Pointer to the device to be converted.
 292   @param DisplayOnly     If DisplayOnly is TRUE, then the shorter text representation
 293                          of the display node is used, where applicable. If DisplayOnly
 294                          is FALSE, then the longer text representation of the display node
 295                          is used.
 296   @param AllowShortcuts  If AllowShortcuts is TRUE, then the shortcut forms of text
 297                          representation for a device node can be used, where applicable.
 298
 299   @return A pointer to the allocated text representation of the device path or
 300           NULL if DeviceNode is NULL or there was insufficient memory.
 301
 302 **/
 303 CHAR16 *
 304 EFIAPI
 305 ConvertDevicePathToText (
 306   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,
 307   IN BOOLEAN                         DisplayOnly,
 308   IN BOOLEAN                         AllowShortcuts
 309   )
 310 {
 311   return UefiDevicePathLibConvertDevicePathToText (DevicePath, DisplayOnly, AllowShortcuts);
 312 }
 313
 314 /**
 315   Convert text to the binary representation of a device node.
 316
 317   @param TextDeviceNode  TextDeviceNode points to the text representation of a device
 318                          node. Conversion starts with the first character and continues
 319                          until the first non-device node character.
 320
 321   @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was
 322           insufficient memory or text unsupported.
 323
 324 **/
 325 EFI_DEVICE_PATH_PROTOCOL *
 326 EFIAPI
 327 ConvertTextToDeviceNode (
 328   IN CONST CHAR16  *TextDeviceNode
 329   )
 330 {
 331   return UefiDevicePathLibConvertTextToDeviceNode (TextDeviceNode);
 332 }
 333
 334 /**
 335   Convert text to the binary representation of a device path.
 336
 337
 338   @param TextDevicePath  TextDevicePath points to the text representation of a device
 339                          path. Conversion starts with the first character and continues
 340                          until the first non-device node character.
 341
 342   @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or
 343           there was insufficient memory.
 344
 345 **/
 346 EFI_DEVICE_PATH_PROTOCOL *
 347 EFIAPI
 348 ConvertTextToDevicePath (
 349   IN CONST CHAR16  *TextDevicePath
 350   )
 351 {
 352   return UefiDevicePathLibConvertTextToDevicePath (TextDevicePath);
 353 }