MdeModulePkg/Universal/DevicePathDxe/DevicePath.h

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