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