MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.h

   1 /** @file
   2   Definition for Device Path library.
   3
   4 Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _UEFI_DEVICE_PATH_LIB_H_
  10 #define _UEFI_DEVICE_PATH_LIB_H_
  11 #include <Uefi.h>
  12 #include <Protocol/DevicePathUtilities.h>
  13 #include <Protocol/DebugPort.h>
  14 #include <Protocol/DevicePathToText.h>
  15 #include <Protocol/DevicePathFromText.h>
  16 #include <Guid/PcAnsi.h>
  17 #include <Library/DebugLib.h>
  18 #include <Library/PrintLib.h>
  19 #include <Library/BaseLib.h>
  20 #include <Library/BaseMemoryLib.h>
  21 #include <Library/MemoryAllocationLib.h>
  22 #include <Library/UefiBootServicesTableLib.h>
  23 #include <Library/DevicePathLib.h>
  24 #include <Library/PcdLib.h>
  25 #include <IndustryStandard/Bluetooth.h>
  26
  27 #define IS_COMMA(a)          ((a) == L',')
  28 #define IS_HYPHEN(a)         ((a) == L'-')
  29 #define IS_DOT(a)            ((a) == L'.')
  30 #define IS_LEFT_PARENTH(a)   ((a) == L'(')
  31 #define IS_RIGHT_PARENTH(a)  ((a) == L')')
  32 #define IS_SLASH(a)          ((a) == L'/')
  33 #define IS_NULL(a)           ((a) == L'\0')
  34
  35 //
  36 // Private Data structure
  37 //
  38 typedef struct {
  39   CHAR16    *Str;
  40   UINTN     Count;
  41   UINTN     Capacity;
  42 } POOL_PRINT;
  43
  44 typedef
  45 EFI_DEVICE_PATH_PROTOCOL  *
  46 (*DEVICE_PATH_FROM_TEXT) (
  47   IN  CHAR16  *Str
  48   );
  49
  50 typedef
  51 VOID
  52 (*DEVICE_PATH_TO_TEXT) (
  53   IN OUT POOL_PRINT  *Str,
  54   IN VOID            *DevicePath,
  55   IN BOOLEAN         DisplayOnly,
  56   IN BOOLEAN         AllowShortcuts
  57   );
  58
  59 typedef struct {
  60   UINT8                  Type;
  61   UINT8                  SubType;
  62   DEVICE_PATH_TO_TEXT    Function;
  63 } DEVICE_PATH_TO_TEXT_TABLE;
  64
  65 typedef struct {
  66   UINT8     Type;
  67   CHAR16    *Text;
  68 } DEVICE_PATH_TO_TEXT_GENERIC_TABLE;
  69
  70 typedef struct {
  71   CHAR16                   *DevicePathNodeText;
  72   DEVICE_PATH_FROM_TEXT    Function;
  73 } DEVICE_PATH_FROM_TEXT_TABLE;
  74
  75 typedef struct {
  76   BOOLEAN    ClassExist;
  77   UINT8      Class;
  78   BOOLEAN    SubClassExist;
  79   UINT8      SubClass;
  80 } USB_CLASS_TEXT;
  81
  82 #define USB_CLASS_AUDIO         1
  83 #define USB_CLASS_CDCCONTROL    2
  84 #define USB_CLASS_HID           3
  85 #define USB_CLASS_IMAGE         6
  86 #define USB_CLASS_PRINTER       7
  87 #define USB_CLASS_MASS_STORAGE  8
  88 #define USB_CLASS_HUB           9
  89 #define USB_CLASS_CDCDATA       10
  90 #define USB_CLASS_SMART_CARD    11
  91 #define USB_CLASS_VIDEO         14
  92 #define USB_CLASS_DIAGNOSTIC    220
  93 #define USB_CLASS_WIRELESS      224
  94
  95 #define USB_CLASS_RESERVE         254
  96 #define USB_SUBCLASS_FW_UPDATE    1
  97 #define USB_SUBCLASS_IRDA_BRIDGE  2
  98 #define USB_SUBCLASS_TEST         3
  99
 100 #define RFC_1700_UDP_PROTOCOL  17
 101 #define RFC_1700_TCP_PROTOCOL  6
 102
 103 #pragma pack(1)
 104
 105 typedef struct {
 106   EFI_DEVICE_PATH_PROTOCOL    Header;
 107   EFI_GUID                    Guid;
 108   UINT8                       VendorDefinedData[1];
 109 } VENDOR_DEFINED_HARDWARE_DEVICE_PATH;
 110
 111 typedef struct {
 112   EFI_DEVICE_PATH_PROTOCOL    Header;
 113   EFI_GUID                    Guid;
 114   UINT8                       VendorDefinedData[1];
 115 } VENDOR_DEFINED_MESSAGING_DEVICE_PATH;
 116
 117 typedef struct {
 118   EFI_DEVICE_PATH_PROTOCOL    Header;
 119   EFI_GUID                    Guid;
 120   UINT8                       VendorDefinedData[1];
 121 } VENDOR_DEFINED_MEDIA_DEVICE_PATH;
 122
 123 typedef struct {
 124   EFI_DEVICE_PATH_PROTOCOL    Header;
 125   UINT32                      Hid;
 126   UINT32                      Uid;
 127   UINT32                      Cid;
 128   CHAR8                       HidUidCidStr[3];
 129 } ACPI_EXTENDED_HID_DEVICE_PATH_WITH_STR;
 130
 131 typedef struct {
 132   EFI_DEVICE_PATH_PROTOCOL    Header;
 133   UINT16                      NetworkProtocol;
 134   UINT16                      LoginOption;
 135   UINT64                      Lun;
 136   UINT16                      TargetPortalGroupTag;
 137   CHAR8                       TargetName[1];
 138 } ISCSI_DEVICE_PATH_WITH_NAME;
 139
 140 typedef struct {
 141   EFI_DEVICE_PATH_PROTOCOL    Header;
 142   EFI_GUID                    Guid;
 143   UINT8                       VendorDefinedData[1];
 144 } VENDOR_DEVICE_PATH_WITH_DATA;
 145
 146 #pragma pack()
 147
 148 /**
 149   Returns the size of a device path in bytes.
 150
 151   This function returns the size, in bytes, of the device path data structure
 152   specified by DevicePath including the end of device path node.
 153   If DevicePath is NULL or invalid, then 0 is returned.
 154
 155   @param  DevicePath  A pointer to a device path data structure.
 156
 157   @retval 0           If DevicePath is NULL or invalid.
 158   @retval Others      The size of a device path in bytes.
 159
 160 **/
 161 UINTN
 162 EFIAPI
 163 UefiDevicePathLibGetDevicePathSize (
 164   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 165   );
 166
 167 /**
 168   Creates a new copy of an existing device path.
 169
 170   This function allocates space for a new copy of the device path specified by DevicePath.
 171   If DevicePath is NULL, then NULL is returned.  If the memory is successfully
 172   allocated, then the contents of DevicePath are copied to the newly allocated
 173   buffer, and a pointer to that buffer is returned.  Otherwise, NULL is returned.
 174   The memory for the new device path is allocated from EFI boot services memory.
 175   It is the responsibility of the caller to free the memory allocated.
 176
 177   @param  DevicePath    A pointer to a device path data structure.
 178
 179   @retval NULL          DevicePath is NULL or invalid.
 180   @retval Others        A pointer to the duplicated device path.
 181
 182 **/
 183 EFI_DEVICE_PATH_PROTOCOL *
 184 EFIAPI
 185 UefiDevicePathLibDuplicateDevicePath (
 186   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 187   );
 188
 189 /**
 190   Creates a new device path by appending a second device path to a first device path.
 191
 192   This function creates a new device path by appending a copy of SecondDevicePath
 193   to a copy of FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path
 194   device node from SecondDevicePath is retained. The newly created device path is
 195   returned. If FirstDevicePath is NULL, then it is ignored, and a duplicate of
 196   SecondDevicePath is returned.  If SecondDevicePath is NULL, then it is ignored,
 197   and a duplicate of FirstDevicePath is returned. If both FirstDevicePath and
 198   SecondDevicePath are NULL, then a copy of an end-of-device-path is returned.
 199
 200   If there is not enough memory for the newly allocated buffer, then NULL is returned.
 201   The memory for the new device path is allocated from EFI boot services memory.
 202   It is the responsibility of the caller to free the memory allocated.
 203
 204   @param  FirstDevicePath            A pointer to a device path data structure.
 205   @param  SecondDevicePath           A pointer to a device path data structure.
 206
 207   @retval NULL      If there is not enough memory for the newly allocated buffer.
 208   @retval NULL      If FirstDevicePath or SecondDevicePath is invalid.
 209   @retval Others    A pointer to the new device path if success.
 210                     Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
 211
 212 **/
 213 EFI_DEVICE_PATH_PROTOCOL *
 214 EFIAPI
 215 UefiDevicePathLibAppendDevicePath (
 216   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath   OPTIONAL,
 217   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath  OPTIONAL
 218   );
 219
 220 /**
 221   Creates a new path by appending the device node to the device path.
 222
 223   This function creates a new device path by appending a copy of the device node
 224   specified by DevicePathNode to a copy of the device path specified by DevicePath
 225   in an allocated buffer. The end-of-device-path device node is moved after the
 226   end of the appended device node.
 227   If DevicePathNode is NULL then a copy of DevicePath is returned.
 228   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device
 229   path device node is returned.
 230   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path
 231   device node is returned.
 232   If there is not enough memory to allocate space for the new device path, then
 233   NULL is returned.
 234   The memory is allocated from EFI boot services memory. It is the responsibility
 235   of the caller to free the memory allocated.
 236
 237   @param  DevicePath                 A pointer to a device path data structure.
 238   @param  DevicePathNode             A pointer to a single device path node.
 239
 240   @retval NULL      If there is not enough memory for the new device path.
 241   @retval Others    A pointer to the new device path if success.
 242                     A copy of DevicePathNode followed by an end-of-device-path node
 243                     if both FirstDevicePath and SecondDevicePath are NULL.
 244                     A copy of an end-of-device-path node if both FirstDevicePath
 245                     and SecondDevicePath are NULL.
 246
 247 **/
 248 EFI_DEVICE_PATH_PROTOCOL *
 249 EFIAPI
 250 UefiDevicePathLibAppendDevicePathNode (
 251   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath      OPTIONAL,
 252   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode  OPTIONAL
 253   );
 254
 255 /**
 256   Creates a new device path by appending the specified device path instance to the specified device
 257   path.
 258
 259   This function creates a new device path by appending a copy of the device path
 260   instance specified by DevicePathInstance to a copy of the device path specified
 261   by DevicePath in a allocated buffer.
 262   The end-of-device-path device node is moved after the end of the appended device
 263   path instance and a new end-of-device-path-instance node is inserted between.
 264   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
 265   If DevicePathInstance is NULL, then NULL is returned.
 266   If DevicePath or DevicePathInstance is invalid, then NULL is returned.
 267   If there is not enough memory to allocate space for the new device path, then
 268   NULL is returned.
 269   The memory is allocated from EFI boot services memory. It is the responsibility
 270   of the caller to free the memory allocated.
 271
 272   @param  DevicePath                 A pointer to a device path data structure.
 273   @param  DevicePathInstance         A pointer to a device path instance.
 274
 275   @return A pointer to the new device path.
 276
 277 **/
 278 EFI_DEVICE_PATH_PROTOCOL *
 279 EFIAPI
 280 UefiDevicePathLibAppendDevicePathInstance (
 281   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath         OPTIONAL,
 282   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathInstance OPTIONAL
 283   );
 284
 285 /**
 286   Creates a copy of the current device path instance and returns a pointer to the next device path
 287   instance.
 288
 289   This function creates a copy of the current device path instance. It also updates
 290   DevicePath to point to the next device path instance in the device path (or NULL
 291   if no more) and updates Size to hold the size of the device path instance copy.
 292   If DevicePath is NULL, then NULL is returned.
 293   If DevicePath points to a invalid device path, then NULL is returned.
 294   If there is not enough memory to allocate space for the new device path, then
 295   NULL is returned.
 296   The memory is allocated from EFI boot services memory. It is the responsibility
 297   of the caller to free the memory allocated.
 298   If Size is NULL, then ASSERT().
 299
 300   @param  DevicePath                 On input, this holds the pointer to the current
 301                                      device path instance. On output, this holds
 302                                      the pointer to the next device path instance
 303                                      or NULL if there are no more device path
 304                                      instances in the device path pointer to a
 305                                      device path data structure.
 306   @param  Size                       On output, this holds the size of the device
 307                                      path instance, in bytes or zero, if DevicePath
 308                                      is NULL.
 309
 310   @return A pointer to the current device path instance.
 311
 312 **/
 313 EFI_DEVICE_PATH_PROTOCOL *
 314 EFIAPI
 315 UefiDevicePathLibGetNextDevicePathInstance (
 316   IN OUT EFI_DEVICE_PATH_PROTOCOL  **DevicePath,
 317   OUT UINTN                        *Size
 318   );
 319
 320 /**
 321   Creates a device node.
 322
 323   This function creates a new device node in a newly allocated buffer of size
 324   NodeLength and initializes the device path node header with NodeType and NodeSubType.
 325   The new device path node is returned.
 326   If NodeLength is smaller than a device path header, then NULL is returned.
 327   If there is not enough memory to allocate space for the new device path, then
 328   NULL is returned.
 329   The memory is allocated from EFI boot services memory. It is the responsibility
 330   of the caller to free the memory allocated.
 331
 332   @param  NodeType                   The device node type for the new device node.
 333   @param  NodeSubType                The device node sub-type for the new device node.
 334   @param  NodeLength                 The length of the new device node.
 335
 336   @return The new device path.
 337
 338 **/
 339 EFI_DEVICE_PATH_PROTOCOL *
 340 EFIAPI
 341 UefiDevicePathLibCreateDeviceNode (
 342   IN UINT8   NodeType,
 343   IN UINT8   NodeSubType,
 344   IN UINT16  NodeLength
 345   );
 346
 347 /**
 348   Determines if a device path is single or multi-instance.
 349
 350   This function returns TRUE if the device path specified by DevicePath is
 351   multi-instance.
 352   Otherwise, FALSE is returned.
 353   If DevicePath is NULL or invalid, then FALSE is returned.
 354
 355   @param  DevicePath                 A pointer to a device path data structure.
 356
 357   @retval  TRUE                      DevicePath is multi-instance.
 358   @retval  FALSE                     DevicePath is not multi-instance, or DevicePath
 359                                      is NULL or invalid.
 360
 361 **/
 362 BOOLEAN
 363 EFIAPI
 364 UefiDevicePathLibIsDevicePathMultiInstance (
 365   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 366   );
 367
 368 /**
 369   Converts a device path to its text representation.
 370
 371   @param DevicePath      A Pointer to the device to be converted.
 372   @param DisplayOnly     If DisplayOnly is TRUE, then the shorter text representation
 373                          of the display node is used, where applicable. If DisplayOnly
 374                          is FALSE, then the longer text representation of the display node
 375                          is used.
 376   @param AllowShortcuts  If AllowShortcuts is TRUE, then the shortcut forms of text
 377                          representation for a device node can be used, where applicable.
 378
 379   @return A pointer to the allocated text representation of the device path or
 380           NULL if DeviceNode is NULL or there was insufficient memory.
 381
 382 **/
 383 CHAR16 *
 384 EFIAPI
 385 UefiDevicePathLibConvertDevicePathToText (
 386   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,
 387   IN BOOLEAN                         DisplayOnly,
 388   IN BOOLEAN                         AllowShortcuts
 389   );
 390
 391 /**
 392   Converts a device node to its string representation.
 393
 394   @param DeviceNode        A Pointer to the device node to be converted.
 395   @param DisplayOnly       If DisplayOnly is TRUE, then the shorter text representation
 396                            of the display node is used, where applicable. If DisplayOnly
 397                            is FALSE, then the longer text representation of the display node
 398                            is used.
 399   @param AllowShortcuts    If AllowShortcuts is TRUE, then the shortcut forms of text
 400                            representation for a device node can be used, where applicable.
 401
 402   @return A pointer to the allocated text representation of the device node or NULL if DeviceNode
 403           is NULL or there was insufficient memory.
 404
 405 **/
 406 CHAR16 *
 407 EFIAPI
 408 UefiDevicePathLibConvertDeviceNodeToText (
 409   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DeviceNode,
 410   IN BOOLEAN                         DisplayOnly,
 411   IN BOOLEAN                         AllowShortcuts
 412   );
 413
 414 /**
 415   Convert text to the binary representation of a device node.
 416
 417   @param TextDeviceNode  TextDeviceNode points to the text representation of a device
 418                          node. Conversion starts with the first character and continues
 419                          until the first non-device node character.
 420
 421   @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was
 422           insufficient memory or text unsupported.
 423
 424 **/
 425 EFI_DEVICE_PATH_PROTOCOL *
 426 EFIAPI
 427 UefiDevicePathLibConvertTextToDeviceNode (
 428   IN CONST CHAR16  *TextDeviceNode
 429   );
 430
 431 /**
 432   Convert text to the binary representation of a device path.
 433
 434
 435   @param TextDevicePath  TextDevicePath points to the text representation of a device
 436                          path. Conversion starts with the first character and continues
 437                          until the first non-device node character.
 438
 439   @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or
 440           there was insufficient memory.
 441
 442 **/
 443 EFI_DEVICE_PATH_PROTOCOL *
 444 EFIAPI
 445 UefiDevicePathLibConvertTextToDevicePath (
 446   IN CONST CHAR16  *TextDevicePath
 447   );
 448
 449 #endif