BaseTools/Source/C/DevicePath/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) 2017, Intel Corporation. All rights reserved.<BR>
  12   This program and the accompanying materials
  13   are licensed and made available under the terms and conditions of the BSD License
  14   which accompanies this distribution.  The full text of the license may be found at
  15   http://opensource.org/licenses/bsd-license.php.
  16
  17   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  18   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  19
  20 **/
  21
  22
  23 #include "UefiDevicePathLib.h"
  24
  25 /**
  26   Returns the size of a device path in bytes.
  27
  28   This function returns the size, in bytes, of the device path data structure
  29   specified by DevicePath including the end of device path node.
  30   If DevicePath is NULL or invalid, then 0 is returned.
  31
  32   @param  DevicePath  A pointer to a device path data structure.
  33
  34   @retval 0           If DevicePath is NULL or invalid.
  35   @retval Others      The size of a device path in bytes.
  36
  37 **/
  38 UINTN
  39 GetDevicePathSize (
  40    CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
  41   )
  42 {
  43   return UefiDevicePathLibGetDevicePathSize (DevicePath);
  44 }
  45
  46 /**
  47   Creates a new copy of an existing device path.
  48
  49   This function allocates space for a new copy of the device path specified by DevicePath.
  50   If DevicePath is NULL, then NULL is returned.  If the memory is successfully
  51   allocated, then the contents of DevicePath are copied to the newly allocated
  52   buffer, and a pointer to that buffer is returned.  Otherwise, NULL is returned.
  53   The memory for the new device path is allocated from EFI boot services memory.
  54   It is the responsibility of the caller to free the memory allocated.
  55
  56   @param  DevicePath    A pointer to a device path data structure.
  57
  58   @retval NULL          DevicePath is NULL or invalid.
  59   @retval Others        A pointer to the duplicated device path.
  60
  61 **/
  62 EFI_DEVICE_PATH_PROTOCOL *
  63 DuplicateDevicePath (
  64    CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
  65   )
  66 {
  67   return UefiDevicePathLibDuplicateDevicePath (DevicePath);
  68 }
  69
  70 /**
  71   Creates a new device path by appending a second device path to a first device path.
  72
  73   This function creates a new device path by appending a copy of SecondDevicePath
  74   to a copy of FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path
  75   device node from SecondDevicePath is retained. The newly created device path is
  76   returned. If FirstDevicePath is NULL, then it is ignored, and a duplicate of
  77   SecondDevicePath is returned.  If SecondDevicePath is NULL, then it is ignored,
  78   and a duplicate of FirstDevicePath is returned. If both FirstDevicePath and
  79   SecondDevicePath are NULL, then a copy of an end-of-device-path is returned.
  80
  81   If there is not enough memory for the newly allocated buffer, then NULL is returned.
  82   The memory for the new device path is allocated from EFI boot services memory.
  83   It is the responsibility of the caller to free the memory allocated.
  84
  85   @param  FirstDevicePath            A pointer to a device path data structure.
  86   @param  SecondDevicePath           A pointer to a device path data structure.
  87
  88   @retval NULL      If there is not enough memory for the newly allocated buffer.
  89   @retval NULL      If FirstDevicePath or SecondDevicePath is invalid.
  90   @retval Others    A pointer to the new device path if success.
  91                     Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
  92
  93 **/
  94 EFI_DEVICE_PATH_PROTOCOL *
  95 AppendDevicePath (
  96    CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,  OPTIONAL
  97    CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath  OPTIONAL
  98   )
  99 {
 100   return UefiDevicePathLibAppendDevicePath (FirstDevicePath, SecondDevicePath);
 101 }
 102
 103 /**
 104   Creates a new path by appending the device node to the device path.
 105
 106   This function creates a new device path by appending a copy of the device node
 107   specified by DevicePathNode to a copy of the device path specified by DevicePath
 108   in an allocated buffer. The end-of-device-path device node is moved after the
 109   end of the appended device node.
 110   If DevicePathNode is NULL then a copy of DevicePath is returned.
 111   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device
 112   path device node is returned.
 113   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path
 114   device node is returned.
 115   If there is not enough memory to allocate space for the new device path, then
 116   NULL is returned.
 117   The memory is allocated from EFI boot services memory. It is the responsibility
 118   of the caller to free the memory allocated.
 119
 120   @param  DevicePath                 A pointer to a device path data structure.
 121   @param  DevicePathNode             A pointer to a single device path node.
 122
 123   @retval NULL      If there is not enough memory for the new device path.
 124   @retval Others    A pointer to the new device path if success.
 125                     A copy of DevicePathNode followed by an end-of-device-path node
 126                     if both FirstDevicePath and SecondDevicePath are NULL.
 127                     A copy of an end-of-device-path node if both FirstDevicePath
 128                     and SecondDevicePath are NULL.
 129
 130 **/
 131 EFI_DEVICE_PATH_PROTOCOL *
 132 AppendDevicePathNode (
 133    CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,     OPTIONAL
 134    CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode  OPTIONAL
 135   )
 136 {
 137   return UefiDevicePathLibAppendDevicePathNode (DevicePath, DevicePathNode);
 138 }
 139
 140 /**
 141   Creates a new device path by appending the specified device path instance to the specified device
 142   path.
 143
 144   This function creates a new device path by appending a copy of the device path
 145   instance specified by DevicePathInstance to a copy of the device path specified
 146   by DevicePath in a allocated buffer.
 147   The end-of-device-path device node is moved after the end of the appended device
 148   path instance and a new end-of-device-path-instance node is inserted between.
 149   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
 150   If DevicePathInstance is NULL, then NULL is returned.
 151   If DevicePath or DevicePathInstance is invalid, then NULL is returned.
 152   If there is not enough memory to allocate space for the new device path, then
 153   NULL is returned.
 154   The memory is allocated from EFI boot services memory. It is the responsibility
 155   of the caller to free the memory allocated.
 156
 157   @param  DevicePath                 A pointer to a device path data structure.
 158   @param  DevicePathInstance         A pointer to a device path instance.
 159
 160   @return A pointer to the new device path.
 161
 162 **/
 163 EFI_DEVICE_PATH_PROTOCOL *
 164 AppendDevicePathInstance (
 165    CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,        OPTIONAL
 166    CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathInstance OPTIONAL
 167   )
 168 {
 169   return UefiDevicePathLibAppendDevicePathInstance (DevicePath, DevicePathInstance);
 170 }
 171
 172 /**
 173   Creates a copy of the current device path instance and returns a pointer to the next device path
 174   instance.
 175
 176   This function creates a copy of the current device path instance. It also updates
 177   DevicePath to point to the next device path instance in the device path (or NULL
 178   if no more) and updates Size to hold the size of the device path instance copy.
 179   If DevicePath is NULL, then NULL is returned.
 180   If DevicePath points to a invalid device path, then NULL is returned.
 181   If there is not enough memory to allocate space for the new device path, then
 182   NULL is returned.
 183   The memory is allocated from EFI boot services memory. It is the responsibility
 184   of the caller to free the memory allocated.
 185   If Size is NULL, then ASSERT().
 186
 187   @param  DevicePath                 On input, this holds the pointer to the current
 188                                      device path instance. On output, this holds
 189                                      the pointer to the next device path instance
 190                                      or NULL if there are no more device path
 191                                      instances in the device path pointer to a
 192                                      device path data structure.
 193   @param  Size                       On output, this holds the size of the device
 194                                      path instance, in bytes or zero, if DevicePath
 195                                      is NULL.
 196
 197   @return A pointer to the current device path instance.
 198
 199 **/
 200 EFI_DEVICE_PATH_PROTOCOL *
 201 GetNextDevicePathInstance (
 202     EFI_DEVICE_PATH_PROTOCOL    **DevicePath,
 203    UINTN                          *Size
 204   )
 205 {
 206   return UefiDevicePathLibGetNextDevicePathInstance (DevicePath, Size);
 207 }
 208
 209 /**
 210   Creates a device node.
 211
 212   This function creates a new device node in a newly allocated buffer of size
 213   NodeLength and initializes the device path node header with NodeType and NodeSubType.
 214   The new device path node is returned.
 215   If NodeLength is smaller than a device path header, then NULL is returned.
 216   If there is not enough memory to allocate space for the new device path, then
 217   NULL is returned.
 218   The memory is allocated from EFI boot services memory. It is the responsibility
 219   of the caller to free the memory allocated.
 220
 221   @param  NodeType                   The device node type for the new device node.
 222   @param  NodeSubType                The device node sub-type for the new device node.
 223   @param  NodeLength                 The length of the new device node.
 224
 225   @return The new device path.
 226
 227 **/
 228 EFI_DEVICE_PATH_PROTOCOL *
 229 CreateDeviceNode (
 230    UINT8                           NodeType,
 231    UINT8                           NodeSubType,
 232    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 IsDevicePathMultiInstance (
 255    CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 256   )
 257 {
 258   return UefiDevicePathLibIsDevicePathMultiInstance (DevicePath);
 259 }
 260
 261 /**
 262   Convert text to the binary representation of a device node.
 263
 264   @param TextDeviceNode  TextDeviceNode points to the text representation of a device
 265                          node. Conversion starts with the first character and continues
 266                          until the first non-device node character.
 267
 268   @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was
 269           insufficient memory or text unsupported.
 270
 271 **/
 272 EFI_DEVICE_PATH_PROTOCOL *
 273 ConvertTextToDeviceNode (
 274    CONST CHAR16 *TextDeviceNode
 275   )
 276 {
 277   return UefiDevicePathLibConvertTextToDeviceNode (TextDeviceNode);
 278 }
 279
 280 /**
 281   Convert text to the binary representation of a device path.
 282
 283
 284   @param TextDevicePath  TextDevicePath points to the text representation of a device
 285                          path. Conversion starts with the first character and continues
 286                          until the first non-device node character.
 287
 288   @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or
 289           there was insufficient memory.
 290
 291 **/
 292 EFI_DEVICE_PATH_PROTOCOL *
 293 ConvertTextToDevicePath (
 294    CONST CHAR16 *TextDevicePath
 295  )
 296 {
 297   return UefiDevicePathLibConvertTextToDevicePath (TextDevicePath);
 298 }