1/*++
2
3Copyright (c) 2006 - 2007, Intel Corporation. All rights reserved.<BR>
4This program and the accompanying materials
5are licensed and made available under the terms and conditions of the BSD License
6which accompanies this distribution.  The full text of the license may be found at
7http://opensource.org/licenses/bsd-license.php
8
9THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
11
12Module Name:
13
14  DevicePathUtilities.h
15
16Abstract:
17
18--*/
19
20#ifndef _DEVICE_PATH_UTILITIES_PROTOCOL_H_
21#define _DEVICE_PATH_UTILITIES_PROTOCOL_H_
22
23//
24// Device Path Utilities protocol
25//
26#define EFI_DEVICE_PATH_UTILITIES_PROTOCOL_GUID \
27  { \
28    0x379be4e, 0xd706, 0x437d, {0xb0, 0x37, 0xed, 0xb8, 0x2f, 0xb7, 0x72, 0xa4}  \
29  }
30
31typedef
32UINTN
33(EFIAPI *EFI_DEVICE_PATH_UTILS_GET_DEVICE_PATH_SIZE) (
34  IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath
35  )
36/*++
37
38  Routine Description:
39    Returns the size of the device path, in bytes.
40
41  Arguments:
42    DevicePath  -   Points to the start of the EFI device path.
43
44  Returns:
45    Size        -   Size of the specified device path, in bytes, including the end-of-path tag.
46
47--*/
48;
49
50typedef
51EFI_DEVICE_PATH_PROTOCOL*
52(EFIAPI *EFI_DEVICE_PATH_UTILS_DUP_DEVICE_PATH) (
53  IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath
54  )
55/*++
56
57  Routine Description:
58    Create a duplicate of the specified path.
59
60  Arguments:
61    DevicePath  -   Points to the source EFI device path.
62
63  Returns:
64    Pointer     -   A pointer to the duplicate device path.
65    NULL        -   Insufficient memory.
66
67--*/
68;
69
70typedef
71EFI_DEVICE_PATH_PROTOCOL*
72(EFIAPI *EFI_DEVICE_PATH_UTILS_APPEND_PATH) (
73  IN CONST EFI_DEVICE_PATH_PROTOCOL *Src1,
74  IN CONST EFI_DEVICE_PATH_PROTOCOL *Src2
75  )
76/*++
77
78  Routine Description:
79    Create a new path by appending the second device path to the first.
80
81  Arguments:
82    Src1      -   Points to the first device path. If NULL, then it is ignored.
83    Src2      -   Points to the second device path. If NULL, then it is ignored.
84
85  Returns:
86    Pointer   -   A pointer to the newly created device path.
87    NULL      -   Memory could not be allocated
88                  or either DevicePath or DeviceNode is NULL.
89
90--*/
91;
92
93typedef
94EFI_DEVICE_PATH_PROTOCOL*
95(EFIAPI *EFI_DEVICE_PATH_UTILS_APPEND_NODE) (
96  IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
97  IN CONST EFI_DEVICE_PATH_PROTOCOL *DeviceNode
98  )
99/*++
100
101  Routine Description:
102    Creates a new path by appending the device node to the device path.
103
104  Arguments:
105    DevicePath   -   Points to the device path.
106    DeviceNode   -   Points to the device node.
107
108  Returns:
109    Pointer      -   A pointer to the allocated device node.
110    NULL         -   Memory could not be allocated
111                     or either DevicePath or DeviceNode is NULL.
112
113--*/
114;
115
116typedef
117EFI_DEVICE_PATH_PROTOCOL*
118(EFIAPI *EFI_DEVICE_PATH_UTILS_APPEND_INSTANCE) (
119  IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
120  IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathInstance
121  )
122/*++
123
124  Routine Description:
125    Creates a new path by appending the specified device path instance to the specified device path.
126
127  Arguments:
128    DevicePath           -   Points to the device path. If NULL, then ignored.
129    DevicePathInstance   -   Points to the device path instance.
130
131  Returns:
132    Pointer              -   A pointer to the newly created device path
133    NULL                 -   Memory could not be allocated or DevicePathInstance is NULL.
134
135--*/
136;
137
138typedef
139EFI_DEVICE_PATH_PROTOCOL*
140(EFIAPI *EFI_DEVICE_PATH_UTILS_GET_NEXT_INSTANCE) (
141  IN  OUT EFI_DEVICE_PATH_PROTOCOL  **DevicePathInstance,
142  OUT UINTN                         *DevicePathInstanceSize
143  )
144/*++
145
146  Routine Description:
147    Creates a copy of the current device path instance and returns a pointer to the next device path instance.
148
149  Arguments:
150    DevicePathInstance       -   On input, this holds the pointer to the current device path
151                                 instance. On output, this holds the pointer to the next
152                                 device path instance or NULL if there are no more device
153                                 path instances in the device path.
154    DevicePathInstanceSize   -   On output, this holds the size of the device path instance,
155                                 in bytes or zero, if DevicePathInstance is zero.
156
157  Returns:
158    Pointer                  -   A pointer to the copy of the current device path instance.
159    NULL                     -   DevicePathInstace was NULL on entry or there was insufficient memory.
160
161--*/
162;
163
164typedef
165BOOLEAN
166(EFIAPI *EFI_DEVICE_PATH_UTILS_IS_MULTI_INSTANCE) (
167  IN CONST EFI_DEVICE_PATH_PROTOCOL         *DevicePath
168  )
169/*++
170
171  Routine Description:
172    Returns whether a device path is multi-instance.
173
174  Arguments:
175    DevicePath  -   Points to the device path. If NULL, then ignored.
176
177  Returns:
178    TRUE        -   The device path has more than one instance
179    FALSE       -   The device path is empty or contains only a single instance.
180
181--*/
182;
183
184typedef
185EFI_DEVICE_PATH_PROTOCOL*
186(EFIAPI *EFI_DEVICE_PATH_UTILS_CREATE_NODE) (
187  IN UINT8                          NodeType,
188  IN UINT8                          NodeSubType,
189  IN UINT16                         NodeLength
190  )
191/*++
192
193  Routine Description:
194    Creates a device node
195
196  Arguments:
197    NodeType     -    NodeType is the device node type (EFI_DEVICE_PATH.Type) for
198                      the new device node.
199    NodeSubType  -    NodeSubType is the device node sub-type
200                      EFI_DEVICE_PATH.SubType) for the new device node.
201    NodeLength   -    NodeLength is the length of the device node
202                      (EFI_DEVICE_PATH.Length) for the new device node.
203
204  Returns:
205    Pointer      -    A pointer to the newly created device node.
206    NULL         -    NodeLength is less than
207                      the size of the header or there was insufficient memory.
208
209--*/
210;
211
212typedef struct {
213  EFI_DEVICE_PATH_UTILS_GET_DEVICE_PATH_SIZE GetDevicePathSize;
214  EFI_DEVICE_PATH_UTILS_DUP_DEVICE_PATH      DuplicateDevicePath;
215  EFI_DEVICE_PATH_UTILS_APPEND_PATH          AppendDevicePath;
216  EFI_DEVICE_PATH_UTILS_APPEND_NODE          AppendDeviceNode;
217  EFI_DEVICE_PATH_UTILS_APPEND_INSTANCE      AppendDevicePathInstance;
218  EFI_DEVICE_PATH_UTILS_GET_NEXT_INSTANCE    GetNextDevicePathInstance;
219  EFI_DEVICE_PATH_UTILS_IS_MULTI_INSTANCE    IsDevicePathMultiInstance;
220  EFI_DEVICE_PATH_UTILS_CREATE_NODE          CreateDeviceNode;
221} EFI_DEVICE_PATH_UTILITIES_PROTOCOL;
222
223extern EFI_GUID gEfiDevicePathUtilitiesProtocolGuid;
224
225#endif
226