MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.h

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