MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.h

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