MdeModulePkg/Universal/DevicePathDxe/DevicePath.h

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