xref: /illumos-gate/usr/src/boot/efi/include/Protocol/Ip4Config2.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   This file provides a definition of the EFI IPv4 Configuration II
3   Protocol.
4 
5 Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
7 
8 @par Revision Reference:
9 This Protocol is introduced in UEFI Specification 2.5
10 
11 **/
12 
13 #ifndef __EFI_IP4CONFIG2_PROTOCOL_H__
14 #define __EFI_IP4CONFIG2_PROTOCOL_H__
15 
16 #include <Protocol/Ip4.h>
17 
18 #define EFI_IP4_CONFIG2_PROTOCOL_GUID \
19   { \
20     0x5b446ed1, 0xe30b, 0x4faa, {0x87, 0x1a, 0x36, 0x54, 0xec, 0xa3, 0x60, 0x80 } \
21   }
22 
23 typedef struct _EFI_IP4_CONFIG2_PROTOCOL EFI_IP4_CONFIG2_PROTOCOL;
24 
25 ///
26 /// EFI_IP4_CONFIG2_DATA_TYPE
27 ///
28 typedef enum {
29   ///
30   /// The interface information of the communication device this EFI
31   /// IPv4 Configuration II Protocol instance manages. This type of
32   /// data is read only. The corresponding Data is of type
33   /// EFI_IP4_CONFIG2_INTERFACE_INFO.
34   ///
35   Ip4Config2DataTypeInterfaceInfo,
36   ///
37   /// The general configuration policy for the EFI IPv4 network stack
38   /// running on the communication device this EFI IPv4
39   /// Configuration II Protocol instance manages. The policy will
40   /// affect other configuration settings. The corresponding Data is of
41   /// type EFI_IP4_CONFIG2_POLICY.
42   ///
43   Ip4Config2DataTypePolicy,
44   ///
45   /// The station addresses set manually for the EFI IPv4 network
46   /// stack. It is only configurable when the policy is
47   /// Ip4Config2PolicyStatic. The corresponding Data is of
48   /// type EFI_IP4_CONFIG2_MANUAL_ADDRESS. When DataSize
49   /// is 0 and Data is NULL, the existing configuration is cleared
50   /// from the EFI IPv4 Configuration II Protocol instance.
51   ///
52   Ip4Config2DataTypeManualAddress,
53   ///
54   /// The gateway addresses set manually for the EFI IPv4 network
55   /// stack running on the communication device this EFI IPv4
56   /// Configuration II Protocol manages. It is not configurable when
57   /// the policy is Ip4Config2PolicyDhcp. The gateway
58   /// addresses must be unicast IPv4 addresses. The corresponding
59   /// Data is a pointer to an array of EFI_IPv4_ADDRESS instances.
60   /// When DataSize is 0 and Data is NULL, the existing configuration
61   /// is cleared from the EFI IPv4 Configuration II Protocol instance.
62   ///
63   Ip4Config2DataTypeGateway,
64   ///
65   /// The DNS server list for the EFI IPv4 network stack running on
66   /// the communication device this EFI IPv4 Configuration II
67   /// Protocol manages. It is not configurable when the policy is
68   /// Ip4Config2PolicyDhcp. The DNS server addresses must be
69   /// unicast IPv4 addresses. The corresponding Data is a pointer to
70   /// an array of EFI_IPv4_ADDRESS instances. When DataSize
71   /// is 0 and Data is NULL, the existing configuration is cleared
72   /// from the EFI IPv4 Configuration II Protocol instance.
73   ///
74   Ip4Config2DataTypeDnsServer,
75   Ip4Config2DataTypeMaximum
76 } EFI_IP4_CONFIG2_DATA_TYPE;
77 
78 ///
79 /// EFI_IP4_CONFIG2_INTERFACE_INFO related definitions
80 ///
81 #define EFI_IP4_CONFIG2_INTERFACE_INFO_NAME_SIZE  32
82 
83 ///
84 /// EFI_IP4_CONFIG2_INTERFACE_INFO
85 ///
86 typedef struct {
87   ///
88   /// The name of the interface. It is a NULL-terminated Unicode string.
89   ///
90   CHAR16              Name[EFI_IP4_CONFIG2_INTERFACE_INFO_NAME_SIZE];
91   ///
92   /// The interface type of the network interface. See RFC 1700,
93   /// section "Number Hardware Type".
94   ///
95   UINT8               IfType;
96   ///
97   /// The size, in bytes, of the network interface's hardware address.
98   ///
99   UINT32              HwAddressSize;
100   ///
101   /// The hardware address for the network interface.
102   ///
103   EFI_MAC_ADDRESS     HwAddress;
104   ///
105   /// The station IPv4 address of this EFI IPv4 network stack.
106   ///
107   EFI_IPv4_ADDRESS    StationAddress;
108   ///
109   /// The subnet address mask that is associated with the station address.
110   ///
111   EFI_IPv4_ADDRESS    SubnetMask;
112   ///
113   /// Size of the following RouteTable, in bytes. May be zero.
114   ///
115   UINT32              RouteTableSize;
116   ///
117   /// The route table of the IPv4 network stack runs on this interface.
118   /// Set to NULL if RouteTableSize is zero. Type EFI_IP4_ROUTE_TABLE is defined in
119   /// EFI_IP4_PROTOCOL.GetModeData().
120   ///
121   EFI_IP4_ROUTE_TABLE   *RouteTable     OPTIONAL;
122 } EFI_IP4_CONFIG2_INTERFACE_INFO;
123 
124 ///
125 /// EFI_IP4_CONFIG2_POLICY
126 ///
127 typedef enum {
128   ///
129   /// Under this policy, the Ip4Config2DataTypeManualAddress,
130   /// Ip4Config2DataTypeGateway and Ip4Config2DataTypeDnsServer configuration
131   /// data are required to be set manually. The EFI IPv4 Protocol will get all
132   /// required configuration such as IPv4 address, subnet mask and
133   /// gateway settings from the EFI IPv4 Configuration II protocol.
134   ///
135   Ip4Config2PolicyStatic,
136   ///
137   /// Under this policy, the Ip4Config2DataTypeManualAddress,
138   /// Ip4Config2DataTypeGateway and Ip4Config2DataTypeDnsServer configuration data are
139   /// not allowed to set via SetData(). All of these configurations are retrieved from DHCP
140   /// server or other auto-configuration mechanism.
141   ///
142   Ip4Config2PolicyDhcp,
143   Ip4Config2PolicyMax
144 } EFI_IP4_CONFIG2_POLICY;
145 
146 ///
147 /// EFI_IP4_CONFIG2_MANUAL_ADDRESS
148 ///
149 typedef struct {
150   ///
151   /// The IPv4 unicast address.
152   ///
153   EFI_IPv4_ADDRESS    Address;
154   ///
155   /// The subnet mask.
156   ///
157   EFI_IPv4_ADDRESS    SubnetMask;
158 } EFI_IP4_CONFIG2_MANUAL_ADDRESS;
159 
160 /**
161   Set the configuration for the EFI IPv4 network stack running on the communication device this EFI
162   IPv4 Configuration II Protocol instance manages.
163 
164   This function is used to set the configuration data of type DataType for the EFI IPv4 network stack
165   running on the communication device this EFI IPv4 Configuration II Protocol instance manages.
166   The successfully configured data is valid after system reset or power-off.
167   The DataSize is used to calculate the count of structure instances in the Data for some
168   DataType that multiple structure instances are allowed.
169   This function is always non-blocking. When setting some typeof configuration data, an
170   asynchronous process is invoked to check the correctness of the data, such as doing address conflict
171   detection on the manually set local IPv4 address. EFI_NOT_READY is returned immediately to
172   indicate that such an asynchronous process is invoked and the process is not finished yet. The caller
173   willing to get the result of the asynchronous process is required to call RegisterDataNotify()
174   to register an event on the specified configuration data. Once the event is signaled, the caller can call
175   GetData()to get back the configuration data in order to know the result. For other types of
176   configuration data that do not require an asynchronous configuration process, the result of the
177   operation is immediately returned.
178 
179   @param[in]   This               Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance.
180   @param[in]   DataType           The type of data to set.
181   @param[in]   DataSize           Size of the buffer pointed to by Data in bytes.
182   @param[in]   Data               The data buffer to set. The type ofthe data buffer is associated
183                                   with the DataType.
184 
185   @retval EFI_SUCCESS             The specified configuration data for the EFI IPv4 network stack is set
186                                   successfully.
187   @retval EFI_INVALID_PARAMETER   One or more of the following are TRUE:
188                                   This is NULL.
189                                   One or more fields in Data and DataSize do not match the
190                                   requirement of the data type indicated by DataType.
191   @retval EFI_WRITE_PROTECTED     The specified configuration data is read-only or the specified configuration
192                                   data can not be set under the current policy.
193   @retval EFI_ACCESS_DENIED       Another set operation on the specified configuration data is already in process.
194   @retval EFI_NOT_READY           An asynchronous process is invoked to set the specified configuration data and
195                                   the process is not finished yet.
196   @retval EFI_BAD_BUFFER_SIZE     The DataSize does not match the size of the type indicated by DataType.
197   @retval EFI_UNSUPPORTED         This DataType is not supported.
198   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
199   @retval EFI_DEVICE_ERROR        An unexpected system error or network error occurred.
200 **/
201 typedef
202 EFI_STATUS
203 (EFIAPI *EFI_IP4_CONFIG2_SET_DATA)(
204   IN EFI_IP4_CONFIG2_PROTOCOL   *This,
205   IN EFI_IP4_CONFIG2_DATA_TYPE  DataType,
206   IN UINTN                      DataSize,
207   IN VOID                       *Data
208   );
209 
210 /**
211   Get the configuration data for the EFI IPv4 network stack running on the communication device this
212   EFI IPv4 Configuration II Protocol instance manages.
213 
214   This function returns the configuration data of type DataType for the EFI IPv4 network stack
215   running on the communication device this EFI IPv4 Configuration II Protocol instance manages.
216   The caller is responsible for allocating the buffer usedto return the specified configuration data and
217   the required size will be returned to the caller if the size of the buffer is too small.
218   EFI_NOT_READY is returned if the specified configuration data is not ready due to an already in
219   progress asynchronous configuration process. The caller can call RegisterDataNotify() to
220   register an event on the specified configuration data. Once the asynchronous configuration process is
221   finished, the event will be signaled and a subsequent GetData() call will return the specified
222   configuration data.
223 
224   @param[in]   This               Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance.
225   @param[in]   DataType           The type of data to get.
226   @param[out]  DataSize           On input, in bytes, the size of Data. On output, in bytes, the size
227                                   of buffer required to store the specified configuration data.
228   @param[in]   Data               The data buffer in which the configuration data is returned. The
229                                   type of the data buffer is associated with the DataType. Ignored
230                                   if DataSize is 0.
231 
232   @retval EFI_SUCCESS             The specified configuration data is got successfully.
233   @retval EFI_INVALID_PARAMETER   One or more of the followings are TRUE:
234                                   This is NULL.
235                                   DataSize is NULL.
236                                   Data is NULL if *DataSizeis not zero.
237   @retval EFI_BUFFER_TOO_SMALL    The size of Data is too small for the specified configuration data
238                                   and the required size is returned in DataSize.
239   @retval EFI_NOT_READY           The specified configuration data is not ready due to an already in
240                                   progress asynchronous configuration process.
241   @retval EFI_NOT_FOUND           The specified configuration data is not found.
242 **/
243 typedef
244 EFI_STATUS
245 (EFIAPI *EFI_IP4_CONFIG2_GET_DATA)(
246   IN EFI_IP4_CONFIG2_PROTOCOL     *This,
247   IN EFI_IP4_CONFIG2_DATA_TYPE    DataType,
248   IN OUT UINTN                    *DataSize,
249   IN VOID                         *Data        OPTIONAL
250   );
251 
252 /**
253   Register an event that is to be signaled whenever a configuration process on the specified
254   configuration data is done.
255 
256   This function registers an event that is to be signaled whenever a configuration process on the
257   specified configuration data is done. An event can be registered for different DataType
258   simultaneously and the caller is responsible for determining which type of configuration data causes
259   the signaling of the event in such case.
260 
261   @param[in]   This               Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance.
262   @param[in]   DataType           The type of data to unregister the event for.
263   @param[in]   Event              The event to register.
264 
265   @retval EFI_SUCCESS             The notification event for the specified configuration data is
266                                   registered.
267   @retval EFI_INVALID_PARAMETER   This is NULL or Event is NULL.
268   @retval EFI_UNSUPPORTED         The configuration data type specified by DataType is not supported.
269   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
270   @retval EFI_ACCESS_DENIED       The Event is already registered for the DataType.
271 **/
272 typedef
273 EFI_STATUS
274 (EFIAPI *EFI_IP4_CONFIG2_REGISTER_NOTIFY)(
275   IN EFI_IP4_CONFIG2_PROTOCOL     *This,
276   IN EFI_IP4_CONFIG2_DATA_TYPE    DataType,
277   IN EFI_EVENT                    Event
278   );
279 
280 /**
281   Remove a previously registered event for the specified configuration data.
282 
283   This function removes a previously registeredevent for the specified configuration data.
284 
285   @param[in]   This               Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance.
286   @param[in]   DataType           The type of data to remove the previously registered event for.
287   @param[in]   Event              The event to unregister.
288 
289   @retval EFI_SUCCESS             The event registered for the specified configuration data is removed.
290   @retval EFI_INVALID_PARAMETER   This is NULL or Event is NULL.
291   @retval EFI_NOT_FOUND           The Eventhas not been registered for the specified DataType.
292 **/
293 typedef
294 EFI_STATUS
295 (EFIAPI *EFI_IP4_CONFIG2_UNREGISTER_NOTIFY)(
296   IN EFI_IP4_CONFIG2_PROTOCOL     *This,
297   IN EFI_IP4_CONFIG2_DATA_TYPE    DataType,
298   IN EFI_EVENT                    Event
299   );
300 
301 ///
302 /// The EFI_IP4_CONFIG2_PROTOCOL is designed to be the central repository for the common
303 /// configurations and the administrator configurable settings for the EFI IPv4 network stack.
304 /// An EFI IPv4 Configuration II Protocol instance will be installed on each communication device that
305 /// the EFI IPv4 network stack runs on.
306 ///
307 struct _EFI_IP4_CONFIG2_PROTOCOL {
308   EFI_IP4_CONFIG2_SET_DATA             SetData;
309   EFI_IP4_CONFIG2_GET_DATA             GetData;
310   EFI_IP4_CONFIG2_REGISTER_NOTIFY      RegisterDataNotify;
311   EFI_IP4_CONFIG2_UNREGISTER_NOTIFY    UnregisterDataNotify;
312 };
313 
314 extern EFI_GUID  gEfiIp4Config2ProtocolGuid;
315 
316 #endif
317