xref: /illumos-gate/usr/src/boot/efi/include/Protocol/Ip6Config.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   This file provides a definition of the EFI IPv6 Configuration
3   Protocol.
4 
5 Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
7 
8 **/
9 
10 #ifndef __EFI_IP6CONFIG_PROTOCOL_H__
11 #define __EFI_IP6CONFIG_PROTOCOL_H__
12 
13 #include <Protocol/Ip6.h>
14 
15 #define EFI_IP6_CONFIG_PROTOCOL_GUID \
16   { \
17     0x937fe521, 0x95ae, 0x4d1a, {0x89, 0x29, 0x48, 0xbc, 0xd9, 0x0a, 0xd3, 0x1a } \
18   }
19 
20 typedef struct _EFI_IP6_CONFIG_PROTOCOL EFI_IP6_CONFIG_PROTOCOL;
21 
22 ///
23 /// EFI_IP6_CONFIG_DATA_TYPE
24 ///
25 typedef enum {
26   ///
27   /// The interface information of the communication
28   /// device this EFI IPv6 Configuration Protocol instance manages.
29   /// This type of data is read only.The corresponding Data is of type
30   /// EFI_IP6_CONFIG_INTERFACE_INFO.
31   ///
32   Ip6ConfigDataTypeInterfaceInfo,
33   ///
34   /// The alternative interface ID for the
35   /// communication device this EFI IPv6 Configuration Protocol
36   /// instance manages if the link local IPv6 address generated from
37   /// the interfaced ID based on the default source the EFI IPv6
38   /// Protocol uses is a duplicate address. The length of the interface
39   /// ID is 64 bit. The corresponding Data is of type
40   /// EFI_IP6_CONFIG_INTERFACE_ID.
41   ///
42   Ip6ConfigDataTypeAltInterfaceId,
43   ///
44   /// The general configuration policy for the EFI IPv6 network
45   /// stack running on the communication device this EFI IPv6
46   /// Configuration Protocol instance manages. The policy will affect
47   /// other configuration settings. The corresponding Data is of type
48   /// EFI_IP6_CONFIG_POLICY.
49   ///
50   Ip6ConfigDataTypePolicy,
51   ///
52   /// The number of consecutive
53   /// Neighbor Solicitation messages sent while performing Duplicate
54   /// Address Detection on a tentative address. A value of zero
55   /// indicates that Duplicate Address Detection will not be performed
56   /// on tentative addresses. The corresponding Data is of type
57   /// EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS.
58   ///
59   Ip6ConfigDataTypeDupAddrDetectTransmits,
60   ///
61   /// The station addresses set manually for the EFI
62   /// IPv6 network stack. It is only configurable when the policy is
63   /// Ip6ConfigPolicyManual. The corresponding Data is a
64   /// pointer to an array of EFI_IPv6_ADDRESS instances. When
65   /// DataSize is 0 and Data is NULL, the existing configuration
66   /// is cleared from the EFI IPv6 Configuration Protocol instance.
67   ///
68   Ip6ConfigDataTypeManualAddress,
69   ///
70   /// The gateway addresses set manually for the EFI IPv6
71   /// network stack running on the communication device this EFI
72   /// IPv6 Configuration Protocol manages. It is not configurable when
73   /// the policy is Ip6ConfigPolicyAutomatic. The gateway
74   /// addresses must be unicast IPv6 addresses. The corresponding
75   /// Data is a pointer to an array of EFI_IPv6_ADDRESS instances.
76   /// When DataSize is 0 and Data is NULL, the existing configuration
77   /// is cleared from the EFI IPv6 Configuration Protocol instance.
78   ///
79   Ip6ConfigDataTypeGateway,
80   ///
81   /// The DNS server list for the EFI IPv6 network stack
82   /// running on the communication device this EFI IPv6
83   /// Configuration Protocol manages. It is not configurable when the
84   /// policy is Ip6ConfigPolicyAutomatic.The DNS server
85   /// addresses must be unicast IPv6 addresses. The corresponding
86   /// Data is a pointer to an array of EFI_IPv6_ADDRESS instances.
87   /// When DataSize is 0 and Data is NULL, the existing configuration
88   /// is cleared from the EFI IPv6 Configuration Protocol instance.
89   ///
90   Ip6ConfigDataTypeDnsServer,
91   ///
92   /// The number of this enumeration memebers.
93   ///
94   Ip6ConfigDataTypeMaximum
95 } EFI_IP6_CONFIG_DATA_TYPE;
96 
97 ///
98 /// EFI_IP6_CONFIG_INTERFACE_INFO
99 /// describes the operational state of the interface this
100 /// EFI IPv6 Configuration Protocol instance manages.
101 ///
102 typedef struct {
103   ///
104   /// The name of the interface. It is a NULL-terminated string.
105   ///
106   CHAR16                  Name[32];
107   ///
108   /// The interface type of the network interface.
109   ///
110   UINT8                   IfType;
111   ///
112   /// The size, in bytes, of the network interface's hardware address.
113   ///
114   UINT32                  HwAddressSize;
115   ///
116   /// The hardware address for the network interface.
117   ///
118   EFI_MAC_ADDRESS         HwAddress;
119   ///
120   /// Number of EFI_IP6_ADDRESS_INFO structures pointed to by AddressInfo.
121   ///
122   UINT32                  AddressInfoCount;
123   ///
124   /// Pointer to an array of EFI_IP6_ADDRESS_INFO instances
125   /// which contain the local IPv6 addresses and the corresponding
126   /// prefix length information. Set to NULL if AddressInfoCount
127   /// is zero.
128   ///
129   EFI_IP6_ADDRESS_INFO    *AddressInfo;
130   ///
131   /// Number of route table entries in the following RouteTable.
132   ///
133   UINT32                  RouteCount;
134   ///
135   /// The route table of the IPv6 network stack runs on this interface.
136   /// Set to NULL if RouteCount is zero.
137   ///
138   EFI_IP6_ROUTE_TABLE     *RouteTable;
139 } EFI_IP6_CONFIG_INTERFACE_INFO;
140 
141 ///
142 /// EFI_IP6_CONFIG_INTERFACE_ID
143 /// describes the 64-bit interface ID.
144 ///
145 typedef struct {
146   UINT8    Id[8];
147 } EFI_IP6_CONFIG_INTERFACE_ID;
148 
149 ///
150 /// EFI_IP6_CONFIG_POLICY
151 /// defines the general configuration policy the EFI IPv6
152 /// Configuration Protocol supports.
153 ///
154 typedef enum {
155   ///
156   /// Under this policy, the IpI6ConfigDataTypeManualAddress,
157   /// Ip6ConfigDataTypeGateway and Ip6ConfigDataTypeDnsServer
158   /// configuration data are required to be set manually.
159   /// The EFI IPv6 Protocol will get all required configuration
160   /// such as address, prefix and gateway settings from the EFI
161   /// IPv6 Configuration protocol.
162   ///
163   Ip6ConfigPolicyManual,
164   ///
165   /// Under this policy, the IpI6ConfigDataTypeManualAddress,
166   /// Ip6ConfigDataTypeGateway and Ip6ConfigDataTypeDnsServer
167   /// configuration data are not allowed to set via SetData().
168   /// All of these configurations are retrieved from some auto
169   /// configuration mechanism.
170   /// The EFI IPv6 Protocol will use the IPv6 stateless address
171   /// autoconfiguration mechanism and/or the IPv6 stateful address
172   /// autoconfiguration mechanism described in the related RFCs to
173   /// get address and other configuration information
174   ///
175   Ip6ConfigPolicyAutomatic
176 } EFI_IP6_CONFIG_POLICY;
177 
178 ///
179 /// EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS
180 /// describes the number of consecutive Neighbor Solicitation messages sent
181 /// while performing Duplicate Address Detection on a tentative address.
182 /// The default value for a newly detected communication device is 1.
183 ///
184 typedef struct {
185   UINT32    DupAddrDetectTransmits;  ///< The number of consecutive Neighbor Solicitation messages sent.
186 } EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS;
187 
188 ///
189 /// EFI_IP6_CONFIG_MANUAL_ADDRESS
190 /// is used to set the station address information for the EFI IPv6 network
191 /// stack manually when the policy is Ip6ConfigPolicyManual.
192 ///
193 typedef struct {
194   EFI_IPv6_ADDRESS    Address;         ///< The IPv6 unicast address.
195   BOOLEAN             IsAnycast;       ///< Set to TRUE if Address is anycast.
196   UINT8               PrefixLength;    ///< The length, in bits, of the prefix associated with this Address.
197 } EFI_IP6_CONFIG_MANUAL_ADDRESS;
198 
199 /**
200   Set the configuration for the EFI IPv6 network stack running on the communication
201   device this EFI IPv6 Configuration Protocol instance manages.
202 
203   This function is used to set the configuration data of type DataType for the EFI
204   IPv6 network stack running on the communication device this EFI IPv6 Configuration
205   Protocol instance manages.
206 
207   The DataSize is used to calculate the count of structure instances in the Data for
208   some DataType that multiple structure instances are allowed.
209 
210   This function is always non-blocking. When setting some type of configuration data,
211   an asynchronous process is invoked to check the correctness of the data, such as
212   doing Duplicate Address Detection on the manually set local IPv6 addresses.
213   EFI_NOT_READY is returned immediately to indicate that such an asynchronous process
214   is invoked and the process is not finished yet. The caller willing to get the result
215   of the asynchronous process is required to call RegisterDataNotify() to register an
216   event on the specified configuration data. Once the event is signaled, the caller
217   can call GetData() to get back the configuration data in order to know the result.
218   For other types of configuration data that do not require an asynchronous configuration
219   process, the result of the operation is immediately returned.
220 
221   @param[in]     This           Pointer to the EFI_IP6_CONFIG_PROTOCOL instance.
222   @param[in]     DataType       The type of data to set.
223   @param[in]     DataSize       Size of the buffer pointed to by Data in bytes.
224   @param[in]     Data           The data buffer to set. The type of the data buffer is
225                                 associated with the DataType.
226 
227   @retval EFI_SUCCESS           The specified configuration data for the EFI IPv6
228                                 network stack is set successfully.
229   @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
230                                 - This is NULL.
231                                 - One or more fields in Data and DataSize do not match the
232                                   requirement of the data type indicated by DataType.
233   @retval EFI_WRITE_PROTECTED   The specified configuration data is read-only or the specified
234                                 configuration data can not be set under the current policy
235   @retval EFI_ACCESS_DENIED     Another set operation on the specified configuration
236                                 data is already in process.
237   @retval EFI_NOT_READY         An asynchronous process is invoked to set the specified
238                                 configuration data and the process is not finished yet.
239   @retval EFI_BAD_BUFFER_SIZE   The DataSize does not match the size of the type
240                                 indicated by DataType.
241   @retval EFI_UNSUPPORTED       This DataType is not supported.
242   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
243   @retval EFI_DEVICE_ERROR      An unexpected system error or network error occurred.
244 
245 **/
246 typedef
247 EFI_STATUS
248 (EFIAPI *EFI_IP6_CONFIG_SET_DATA)(
249   IN EFI_IP6_CONFIG_PROTOCOL    *This,
250   IN EFI_IP6_CONFIG_DATA_TYPE   DataType,
251   IN UINTN                      DataSize,
252   IN VOID                       *Data
253   );
254 
255 /**
256   Get the configuration data for the EFI IPv6 network stack running on the communication
257   device this EFI IPv6 Configuration Protocol instance manages.
258 
259   This function returns the configuration data of type DataType for the EFI IPv6 network
260   stack running on the communication device this EFI IPv6 Configuration Protocol instance
261   manages.
262 
263   The caller is responsible for allocating the buffer used to return the specified
264   configuration data and the required size will be returned to the caller if the size of
265   the buffer is too small.
266 
267   EFI_NOT_READY is returned if the specified configuration data is not ready due to an
268   already in progress asynchronous configuration process. The caller can call RegisterDataNotify()
269   to register an event on the specified configuration data. Once the asynchronous configuration
270   process is finished, the event will be signaled and a subsequent GetData() call will return
271   the specified configuration data.
272 
273   @param[in]     This           Pointer to the EFI_IP6_CONFIG_PROTOCOL instance.
274   @param[in]     DataType       The type of data to get.
275   @param[in,out] DataSize       On input, in bytes, the size of Data. On output, in bytes, the
276                                 size of buffer required to store the specified configuration data.
277   @param[in]     Data           The data buffer in which the configuration data is returned. The
278                                 type of the data buffer is associated with the DataType.
279 
280   @retval EFI_SUCCESS           The specified configuration data is got successfully.
281   @retval EFI_INVALID_PARAMETER One or more of the followings are TRUE:
282                                 - This is NULL.
283                                 - DataSize is NULL.
284                                 - Data is NULL if *DataSize is not zero.
285   @retval EFI_BUFFER_TOO_SMALL  The size of Data is too small for the specified configuration data
286                                 and the required size is returned in DataSize.
287   @retval EFI_NOT_READY         The specified configuration data is not ready due to an already in
288                                 progress asynchronous configuration process.
289   @retval EFI_NOT_FOUND         The specified configuration data is not found.
290 
291 **/
292 typedef
293 EFI_STATUS
294 (EFIAPI *EFI_IP6_CONFIG_GET_DATA)(
295   IN EFI_IP6_CONFIG_PROTOCOL    *This,
296   IN EFI_IP6_CONFIG_DATA_TYPE   DataType,
297   IN OUT UINTN                  *DataSize,
298   IN VOID                       *Data   OPTIONAL
299   );
300 
301 /**
302   Register an event that is to be signaled whenever a configuration process on the specified
303   configuration data is done.
304 
305   This function registers an event that is to be signaled whenever a configuration process
306   on the specified configuration data is done. An event can be registered for different DataType
307   simultaneously and the caller is responsible for determining which type of configuration data
308   causes the signaling of the event in such case.
309 
310   @param[in]     This           Pointer to the EFI_IP6_CONFIG_PROTOCOL instance.
311   @param[in]     DataType       The type of data to unregister the event for.
312   @param[in]     Event          The event to register.
313 
314   @retval EFI_SUCCESS           The notification event for the specified configuration data is
315                                 registered.
316   @retval EFI_INVALID_PARAMETER This is NULL or Event is NULL.
317   @retval EFI_UNSUPPORTED       The configuration data type specified by DataType is not
318                                 supported.
319   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
320   @retval EFI_ACCESS_DENIED     The Event is already registered for the DataType.
321 
322 **/
323 typedef
324 EFI_STATUS
325 (EFIAPI *EFI_IP6_CONFIG_REGISTER_NOTIFY)(
326   IN EFI_IP6_CONFIG_PROTOCOL    *This,
327   IN EFI_IP6_CONFIG_DATA_TYPE   DataType,
328   IN EFI_EVENT                  Event
329   );
330 
331 /**
332   Remove a previously registered event for the specified configuration data.
333 
334   This function removes a previously registered event for the specified configuration data.
335 
336   @param[in]     This           Pointer to the EFI_IP6_CONFIG_PROTOCOL instance.
337   @param[in]     DataType       The type of data to remove the previously registered event for.
338   @param[in]     Event          The event to unregister.
339 
340   @retval EFI_SUCCESS           The event registered for the specified configuration data is removed.
341   @retval EFI_INVALID_PARAMETER This is NULL or Event is NULL.
342   @retval EFI_NOT_FOUND         The Event has not been registered for the specified
343                                 DataType.
344 
345 **/
346 typedef
347 EFI_STATUS
348 (EFIAPI *EFI_IP6_CONFIG_UNREGISTER_NOTIFY)(
349   IN EFI_IP6_CONFIG_PROTOCOL    *This,
350   IN EFI_IP6_CONFIG_DATA_TYPE   DataType,
351   IN EFI_EVENT                  Event
352   );
353 
354 ///
355 /// The EFI_IP6_CONFIG_PROTOCOL provides the mechanism to set and get various
356 /// types of configurations for the EFI IPv6 network stack.
357 ///
358 struct _EFI_IP6_CONFIG_PROTOCOL {
359   EFI_IP6_CONFIG_SET_DATA             SetData;
360   EFI_IP6_CONFIG_GET_DATA             GetData;
361   EFI_IP6_CONFIG_REGISTER_NOTIFY      RegisterDataNotify;
362   EFI_IP6_CONFIG_UNREGISTER_NOTIFY    UnregisterDataNotify;
363 };
364 
365 extern EFI_GUID  gEfiIp6ConfigProtocolGuid;
366 
367 #endif
368