MdeModulePkg/Universal/DevicePathDxe/DevicePath.h

   1 /** @file
   2   Definition for Device Path Utilities driver
   3
   4 Copyright (c) 2006 - 2010, Intel Corporation. <BR>
   5 All rights reserved. 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]  = 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 #pragma pack(1)
 114
 115 typedef struct {
 116   EFI_DEVICE_PATH_PROTOCOL  Header;
 117   EFI_GUID                  Guid;
 118   UINT8                     VendorDefinedData[1];
 119 } VENDOR_DEFINED_HARDWARE_DEVICE_PATH;
 120
 121 typedef struct {
 122   EFI_DEVICE_PATH_PROTOCOL  Header;
 123   EFI_GUID                  Guid;
 124   UINT8                     VendorDefinedData[1];
 125 } VENDOR_DEFINED_MESSAGING_DEVICE_PATH;
 126
 127 typedef struct {
 128   EFI_DEVICE_PATH_PROTOCOL  Header;
 129   EFI_GUID                  Guid;
 130   UINT8                     VendorDefinedData[1];
 131 } VENDOR_DEFINED_MEDIA_DEVICE_PATH;
 132
 133 typedef struct {
 134   EFI_DEVICE_PATH_PROTOCOL  Header;
 135   UINT32                    Hid;
 136   UINT32                    Uid;
 137   UINT32                    Cid;
 138   CHAR8                     HidUidCidStr[3];
 139 } ACPI_EXTENDED_HID_DEVICE_PATH_WITH_STR;
 140
 141 typedef struct {
 142   EFI_DEVICE_PATH_PROTOCOL  Header;
 143   UINT16                    NetworkProtocol;
 144   UINT16                    LoginOption;
 145   UINT64                    Lun;
 146   UINT16                    TargetPortalGroupTag;
 147   CHAR8                     TargetName[1];
 148 } ISCSI_DEVICE_PATH_WITH_NAME;
 149
 150 typedef struct {
 151   EFI_DEVICE_PATH_PROTOCOL  Header;
 152   EFI_GUID                  Guid;
 153   UINT8                     VendorDefinedData[1];
 154 } VENDOR_DEVICE_PATH_WITH_DATA;
 155
 156 #pragma pack()
 157
 158 /**
 159   Converts a device node to its string representation.
 160
 161   @param DeviceNode        A Pointer to the device node to be converted.
 162   @param DisplayOnly       If DisplayOnly is TRUE, then the shorter text representation
 163                            of the display node is used, where applicable. If DisplayOnly
 164                            is FALSE, then the longer text representation of the display node
 165                            is used.
 166   @param AllowShortcuts    If AllowShortcuts is TRUE, then the shortcut forms of text
 167                            representation for a device node can be used, where applicable.
 168
 169   @return A pointer to the allocated text representation of the device node or NULL if DeviceNode
 170           is NULL or there was insufficient memory.
 171
 172 **/
 173 CHAR16 *
 174 EFIAPI
 175 ConvertDeviceNodeToText (
 176   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DeviceNode,
 177   IN BOOLEAN                         DisplayOnly,
 178   IN BOOLEAN                         AllowShortcuts
 179   );
 180
 181 /**
 182   Converts a device path to its text representation.
 183
 184   @param DevicePath      A Pointer to the device to be converted.
 185   @param DisplayOnly     If DisplayOnly is TRUE, then the shorter text representation
 186                          of the display node is used, where applicable. If DisplayOnly
 187                          is FALSE, then the longer text representation of the display node
 188                          is used.
 189   @param AllowShortcuts  If AllowShortcuts is TRUE, then the shortcut forms of text
 190                          representation for a device node can be used, where applicable.
 191
 192   @return A pointer to the allocated text representation of the device path or
 193           NULL if DeviceNode is NULL or there was insufficient memory.
 194
 195 **/
 196 CHAR16 *
 197 EFIAPI
 198 ConvertDevicePathToText (
 199   IN CONST EFI_DEVICE_PATH_PROTOCOL   *DevicePath,
 200   IN BOOLEAN                          DisplayOnly,
 201   IN BOOLEAN                          AllowShortcuts
 202   );
 203
 204 /**
 205   Convert text to the binary representation of a device node.
 206
 207   @param TextDeviceNode  TextDeviceNode points to the text representation of a device
 208                          node. Conversion starts with the first character and continues
 209                          until the first non-device node character.
 210
 211   @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was
 212           insufficient memory or text unsupported.
 213
 214 **/
 215 EFI_DEVICE_PATH_PROTOCOL *
 216 EFIAPI
 217 ConvertTextToDeviceNode (
 218   IN CONST CHAR16 *TextDeviceNode
 219   );
 220
 221 /**
 222   Convert text to the binary representation of a device path.
 223
 224
 225   @param TextDevicePath  TextDevicePath points to the text representation of a device
 226                          path. Conversion starts with the first character and continues
 227                          until the first non-device node character.
 228
 229   @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or
 230           there was insufficient memory.
 231
 232 **/
 233 EFI_DEVICE_PATH_PROTOCOL *
 234 EFIAPI
 235 ConvertTextToDevicePath (
 236   IN CONST CHAR16 *TextDevicePath
 237   );
 238
 239 /**
 240   Returns the size of a device path in bytes.
 241
 242   This function returns the size, in bytes, of the device path data structure specified by
 243   DevicePath including the end of device path node.  If DevicePath is NULL, then 0 is returned.
 244
 245   @param  DevicePath                 A pointer to a device path data structure.
 246
 247   @return The size of a device path in bytes.
 248
 249 **/
 250 UINTN
 251 EFIAPI
 252 GetDevicePathSizeProtocolInterface (
 253   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 254   );
 255
 256 /**
 257   Creates a new device path by appending a second device path to a first device path.
 258
 259   This function allocates space for a new copy of the device path specified by DevicePath.  If
 260   DevicePath is NULL, then NULL is returned.  If the memory is successfully allocated, then the
 261   contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer
 262   is returned.  Otherwise, NULL is returned.
 263
 264   @param  DevicePath                 A pointer to a device path data structure.
 265
 266   @return A pointer to the duplicated device path.
 267
 268 **/
 269 EFI_DEVICE_PATH_PROTOCOL *
 270 EFIAPI
 271 DuplicateDevicePathProtocolInterface (
 272   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 273   );
 274
 275 /**
 276   Creates a new device path by appending a second device path to a first device path.
 277
 278   This function creates a new device path by appending a copy of SecondDevicePath to a copy of
 279   FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path device node from
 280   SecondDevicePath is retained. The newly created device path is returned.
 281   If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned.
 282   If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned.
 283   If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is
 284   returned.
 285   If there is not enough memory for the newly allocated buffer, then NULL is returned.
 286   The memory for the new device path is allocated from EFI boot services memory. It is the
 287   responsibility of the caller to free the memory allocated.
 288
 289   @param  FirstDevicePath            A pointer to a device path data structure.
 290   @param  SecondDevicePath           A pointer to a device path data structure.
 291
 292   @return A pointer to the new device path.
 293
 294 **/
 295 EFI_DEVICE_PATH_PROTOCOL *
 296 EFIAPI
 297 AppendDevicePathProtocolInterface (
 298   IN CONST EFI_DEVICE_PATH_PROTOCOL *FirstDevicePath,
 299   IN CONST EFI_DEVICE_PATH_PROTOCOL *SecondDevicePath
 300   );
 301
 302 /**
 303   Creates a new path by appending the device node to the device path.
 304
 305   This function creates a new device path by appending a copy of the device node specified by
 306   DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer.
 307   The end-of-device-path device node is moved after the end of the appended device node.
 308   If DevicePathNode is NULL then a copy of DevicePath is returned.
 309   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device path device
 310   node is returned.
 311   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node
 312   is returned.
 313   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 314   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 315   free the memory allocated.
 316
 317   @param  DevicePath                 A pointer to a device path data structure.
 318   @param  DevicePathNode             A pointer to a single device path node.
 319
 320   @return A pointer to the new device path.
 321
 322 **/
 323 EFI_DEVICE_PATH_PROTOCOL *
 324 EFIAPI
 325 AppendDeviceNodeProtocolInterface (
 326   IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
 327   IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathNode
 328   );
 329
 330 /**
 331   Creates a new device path by appending the specified device path instance to the specified device
 332   path.
 333
 334   This function creates a new device path by appending a copy of the device path instance specified
 335   by DevicePathInstance to a copy of the device path specified by DevicePath in a allocated buffer.
 336   The end-of-device-path device node is moved after the end of the appended device path instance
 337   and a new end-of-device-path-instance node is inserted between.
 338   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
 339   If DevicePathInstance is NULL, then NULL is returned.
 340   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 341   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 342   free the memory allocated.
 343
 344   @param  DevicePath                 A pointer to a device path data structure.
 345   @param  DevicePathInstance         A pointer to a device path instance.
 346
 347   @return A pointer to the new device path.
 348
 349 **/
 350 EFI_DEVICE_PATH_PROTOCOL *
 351 EFIAPI
 352 AppendDevicePathInstanceProtocolInterface (
 353   IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
 354   IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathInstance
 355   );
 356
 357 /**
 358   Creates a copy of the current device path instance and returns a pointer to the next device path
 359   instance.
 360
 361   This function creates a copy of the current device path instance. It also updates DevicePath to
 362   point to the next device path instance in the device path (or NULL if no more) and updates Size
 363   to hold the size of the device path instance copy.
 364   If DevicePath is NULL, then NULL is returned.
 365   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 366   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 367   free the memory allocated.
 368   If Size is NULL, then ASSERT().
 369
 370   @param  DevicePath                 On input, this holds the pointer to the current device path
 371                                      instance. On output, this holds the pointer to the next device
 372                                      path instance or NULL if there are no more device path
 373                                      instances in the device path pointer to a device path data
 374                                      structure.
 375   @param  Size                       On output, this holds the size of the device path instance, in
 376                                      bytes or zero, if DevicePath is NULL.
 377
 378   @return A pointer to the current device path instance.
 379
 380 **/
 381 EFI_DEVICE_PATH_PROTOCOL *
 382 EFIAPI
 383 GetNextDevicePathInstanceProtocolInterface (
 384   IN OUT EFI_DEVICE_PATH_PROTOCOL   **DevicePath,
 385   OUT UINTN                         *Size
 386   );
 387
 388 /**
 389   Determines if a device path is single or multi-instance.
 390
 391   This function returns TRUE if the device path specified by DevicePath is multi-instance.
 392   Otherwise, FALSE is returned.  If DevicePath is NULL, then FALSE is returned.
 393
 394   @param  DevicePath                 A pointer to a device path data structure.
 395
 396   @retval  TRUE                      DevicePath is multi-instance.
 397   @retval  FALSE                     DevicePath is not multi-instance or DevicePath is NULL.
 398
 399 **/
 400 BOOLEAN
 401 EFIAPI
 402 IsDevicePathMultiInstanceProtocolInterface (
 403   IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath
 404   );
 405
 406 /**
 407   Creates a copy of the current device path instance and returns a pointer to the next device path
 408   instance.
 409
 410   This function creates a new device node in a newly allocated buffer of size NodeLength and
 411   initializes the device path node header with NodeType and NodeSubType.  The new device path node
 412   is returned.
 413   If NodeLength is smaller than a device path header, then NULL is returned.
 414   If there is not enough memory to allocate space for the new device path, then NULL is returned.
 415   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
 416   free the memory allocated.
 417
 418   @param  NodeType                   The device node type for the new device node.
 419   @param  NodeSubType                The device node sub-type for the new device node.
 420   @param  NodeLength                 The length of the new device node.
 421
 422   @return The new device path.
 423
 424 **/
 425 EFI_DEVICE_PATH_PROTOCOL *
 426 EFIAPI
 427 CreateDeviceNodeProtocolInterface (
 428   IN UINT8  NodeType,
 429   IN UINT8  NodeSubType,
 430   IN UINT16 NodeLength
 431   );
 432
 433 #endif