BaseTools/Source/C/DevicePath/UefiDevicePathLib.h

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