iPXE
ManagedNetwork.h
Go to the documentation of this file.
1 /** @file
2  EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL as defined in UEFI 2.0.
3  EFI_MANAGED_NETWORK_PROTOCOL as defined in UEFI 2.0.
4 
5 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
6 This program and the accompanying materials are licensed and made available under
7 the terms and conditions of the BSD License that accompanies this distribution.
8 The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php.
10 
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13 
14  @par Revision Reference:
15  This Protocol is introduced in UEFI Specification 2.0
16 
17 **/
18 
19 #ifndef __EFI_MANAGED_NETWORK_PROTOCOL_H__
20 #define __EFI_MANAGED_NETWORK_PROTOCOL_H__
21 
22 FILE_LICENCE ( BSD3 );
23 
25 
26 #define EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL_GUID \
27  { \
28  0xf36ff770, 0xa7e1, 0x42cf, {0x9e, 0xd2, 0x56, 0xf0, 0xf2, 0x71, 0xf4, 0x4c } \
29  }
30 
31 #define EFI_MANAGED_NETWORK_PROTOCOL_GUID \
32  { \
33  0x7ab33a91, 0xace5, 0x4326, { 0xb5, 0x72, 0xe7, 0xee, 0x33, 0xd3, 0x9f, 0x16 } \
34  }
35 
37 
38 typedef struct {
39  ///
40  /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed
41  /// from the MNP receive queue will be dropped if its receive timeout expires.
42  ///
44  ///
45  /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed
46  /// from the MNP transmit queue will be dropped if its receive timeout expires.
47  ///
49  ///
50  /// Ethernet type II 16-bit protocol type in host byte order. Valid
51  /// values are zero and 1,500 to 65,535.
52  ///
54  ///
55  /// Set to TRUE to receive packets that are sent to the network
56  /// device MAC address. The startup default value is FALSE.
57  ///
59  ///
60  /// Set to TRUE to receive packets that are sent to any of the
61  /// active multicast groups. The startup default value is FALSE.
62  ///
64  ///
65  /// Set to TRUE to receive packets that are sent to the network
66  /// device broadcast address. The startup default value is FALSE.
67  ///
69  ///
70  /// Set to TRUE to receive packets that are sent to any MAC address.
71  /// The startup default value is FALSE.
72  ///
74  ///
75  /// Set to TRUE to drop queued packets when the configuration
76  /// is changed. The startup default value is FALSE.
77  ///
79  ///
80  /// Set to TRUE to timestamp all packets when they are received
81  /// by the MNP. Note that timestamps may be unsupported in some
82  /// MNP implementations. The startup default value is FALSE.
83  ///
85  ///
86  /// Set to TRUE to disable background polling in this MNP
87  /// instance. Note that background polling may not be supported in
88  /// all MNP implementations. The startup default value is FALSE,
89  /// unless background polling is not supported.
90  ///
93 
94 typedef struct {
110 
111 typedef struct {
115 
116 typedef struct {
119  UINT16 ProtocolType; //OPTIONAL
121  UINT16 HeaderLength; //OPTIONAL
125 
126 
127 typedef struct {
128  ///
129  /// This Event will be signaled after the Status field is updated
130  /// by the MNP. The type of Event must be
131  /// EFI_NOTIFY_SIGNAL. The Task Priority Level (TPL) of
132  /// Event must be lower than or equal to TPL_CALLBACK.
133  ///
135  ///
136  /// The status that is returned to the caller at the end of the operation
137  /// to indicate whether this operation completed successfully.
138  ///
140  union {
141  ///
142  /// When this token is used for receiving, RxData is a pointer to the EFI_MANAGED_NETWORK_RECEIVE_DATA.
143  ///
145  ///
146  /// When this token is used for transmitting, TxData is a pointer to the EFI_MANAGED_NETWORK_TRANSMIT_DATA.
147  ///
149  } Packet;
151 
152 /**
153  Returns the operational parameters for the current MNP child driver.
154 
155  @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
156  @param MnpConfigData The pointer to storage for MNP operational parameters.
157  @param SnpModeData The pointer to storage for SNP operational parameters.
158 
159  @retval EFI_SUCCESS The operation completed successfully.
160  @retval EFI_INVALID_PARAMETER This is NULL.
161  @retval EFI_UNSUPPORTED The requested feature is unsupported in this MNP implementation.
162  @retval EFI_NOT_STARTED This MNP child driver instance has not been configured. The default
163  values are returned in MnpConfigData if it is not NULL.
164  @retval Other The mode data could not be read.
165 
166 **/
167 typedef
173  );
174 
175 /**
176  Sets or clears the operational parameters for the MNP child driver.
177 
178  @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
179  @param MnpConfigData The pointer to configuration data that will be assigned to the MNP
180  child driver instance. If NULL, the MNP child driver instance is
181  reset to startup defaults and all pending transmit and receive
182  requests are flushed.
183 
184  @retval EFI_SUCCESS The operation completed successfully.
185  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
186  @retval EFI_OUT_OF_RESOURCES Required system resources (usually memory) could not be
187  allocated.
188  @retval EFI_UNSUPPORTED The requested feature is unsupported in this [MNP]
189  implementation.
190  @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
191  @retval Other The MNP child driver instance has been reset to startup defaults.
192 
193 **/
194 typedef
199  );
200 
201 /**
202  Translates an IP multicast address to a hardware (MAC) multicast address.
203 
204  @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
205  @param Ipv6Flag Set to TRUE to if IpAddress is an IPv6 multicast address.
206  Set to FALSE if IpAddress is an IPv4 multicast address.
207  @param IpAddress The pointer to the multicast IP address (in network byte order) to convert.
208  @param MacAddress The pointer to the resulting multicast MAC address.
209 
210  @retval EFI_SUCCESS The operation completed successfully.
211  @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:
212  - This is NULL.
213  - IpAddress is NULL.
214  - *IpAddress is not a valid multicast IP address.
215  - MacAddress is NULL.
216  @retval EFI_NOT_STARTED This MNP child driver instance has not been configured.
217  @retval EFI_UNSUPPORTED The requested feature is unsupported in this MNP implementation.
218  @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
219  @retval Other The address could not be converted.
220 
221 **/
222 typedef
226  IN BOOLEAN Ipv6Flag,
227  IN EFI_IP_ADDRESS *IpAddress,
228  OUT EFI_MAC_ADDRESS *MacAddress
229  );
230 
231 /**
232  Enables and disables receive filters for multicast address.
233 
234  @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
235  @param JoinFlag Set to TRUE to join this multicast group.
236  Set to FALSE to leave this multicast group.
237  @param MacAddress The pointer to the multicast MAC group (address) to join or leave.
238 
239  @retval EFI_SUCCESS The requested operation completed successfully.
240  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
241  - This is NULL.
242  - JoinFlag is TRUE and MacAddress is NULL.
243  - *MacAddress is not a valid multicast MAC address.
244  @retval EFI_NOT_STARTED This MNP child driver instance has not been configured.
245  @retval EFI_ALREADY_STARTED The supplied multicast group is already joined.
246  @retval EFI_NOT_FOUND The supplied multicast group is not joined.
247  @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
248  @retval EFI_UNSUPPORTED The requested feature is unsupported in this MNP implementation.
249  @retval Other The requested operation could not be completed.
250 
251 **/
252 typedef
256  IN BOOLEAN JoinFlag,
257  IN EFI_MAC_ADDRESS *MacAddress OPTIONAL
258  );
259 
260 /**
261  Places asynchronous outgoing data packets into the transmit queue.
262 
263  @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
264  @param Token The pointer to a token associated with the transmit data descriptor.
265 
266  @retval EFI_SUCCESS The transmit completion token was cached.
267  @retval EFI_NOT_STARTED This MNP child driver instance has not been configured.
268  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
269  @retval EFI_ACCESS_DENIED The transmit completion token is already in the transmit queue.
270  @retval EFI_OUT_OF_RESOURCES The transmit data could not be queued due to a lack of system resources
271  (usually memory).
272  @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
273  @retval EFI_NOT_READY The transmit request could not be queued because the transmit queue is full.
274 
275 **/
276 typedef
281  );
282 
283 /**
284  Places an asynchronous receiving request into the receiving queue.
285 
286  @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
287  @param Token The pointer to a token associated with the receive data descriptor.
288 
289  @retval EFI_SUCCESS The receive completion token was cached.
290  @retval EFI_NOT_STARTED This MNP child driver instance has not been configured.
291  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
292  - This is NULL.
293  - Token is NULL.
294  - Token.Event is NULL.
295  @retval EFI_OUT_OF_RESOURCES The transmit data could not be queued due to a lack of system resources
296  (usually memory).
297  @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
298  @retval EFI_ACCESS_DENIED The receive completion token was already in the receive queue.
299  @retval EFI_NOT_READY The receive request could not be queued because the receive queue is full.
300 
301 **/
302 typedef
307  );
308 
309 
310 /**
311  Aborts an asynchronous transmit or receive request.
312 
313  @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
314  @param Token The pointer to a token that has been issued by
315  EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or
316  EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If
317  NULL, all pending tokens are aborted.
318 
319  @retval EFI_SUCCESS The asynchronous I/O request was aborted and Token.Event
320  was signaled. When Token is NULL, all pending requests were
321  aborted and their events were signaled.
322  @retval EFI_NOT_STARTED This MNP child driver instance has not been configured.
323  @retval EFI_INVALID_PARAMETER This is NULL.
324  @retval EFI_NOT_FOUND When Token is not NULL, the asynchronous I/O request was
325  not found in the transmit or receive queue. It has either completed
326  or was not issued by Transmit() and Receive().
327 
328 **/
329 typedef
334  );
335 
336 /**
337  Polls for incoming data packets and processes outgoing data packets.
338 
339  @param This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
340 
341  @retval EFI_SUCCESS Incoming or outgoing data was processed.
342  @retval EFI_NOT_STARTED This MNP child driver instance has not been configured.
343  @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
344  @retval EFI_NOT_READY No incoming or outgoing data was processed. Consider increasing
345  the polling rate.
346  @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
347  Consider increasing the polling rate.
348 
349 **/
350 typedef
354  );
355 
356 ///
357 /// The MNP is used by network applications (and drivers) to
358 /// perform raw (unformatted) asynchronous network packet I/O.
359 ///
369 };
370 
373 
374 #endif
#define OPTIONAL
Passing the datum to the function is optional, and a NULL is passed if the value is not supplied.
Definition: Base.h:340
EFI_STATUS(EFIAPI * EFI_MANAGED_NETWORK_TRANSMIT)(IN EFI_MANAGED_NETWORK_PROTOCOL *This, IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token)
Places asynchronous outgoing data packets into the transmit queue.
EFI_MANAGED_NETWORK_TRANSMIT Transmit
EFI_STATUS(EFIAPI * EFI_MANAGED_NETWORK_GROUPS)(IN EFI_MANAGED_NETWORK_PROTOCOL *This, IN BOOLEAN JoinFlag, IN EFI_MAC_ADDRESS *MacAddress OPTIONAL)
Enables and disables receive filters for multicast address.
EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC McastIpToMac
The MNP is used by network applications (and drivers) to perform raw (unformatted) asynchronous netwo...
128 bit buffer containing a unique identifier value.
Definition: Base.h:263
32-byte buffer containing a network Media Access Control address.
Definition: UefiBaseType.h:102
VOID * EFI_EVENT
Handle to an event structure.
Definition: UefiBaseType.h:43
unsigned char BOOLEAN
Definition: ProcessorBind.h:61
EFI_MANAGED_NETWORK_GROUPS Groups
EFI_GUID gEfiManagedNetworkProtocolGuid
unsigned int UINT32
Definition: ProcessorBind.h:56
BOOLEAN DisableBackgroundPolling
Set to TRUE to disable background polling in this MNP instance.
EFI_MANAGED_NETWORK_POLL Poll
BOOLEAN EnableMulticastReceive
Set to TRUE to receive packets that are sent to any of the active multicast groups.
UINT32 ReceivedQueueTimeoutValue
Timeout value for a UEFI one-shot timer event.
EFI_STATUS(EFIAPI * EFI_MANAGED_NETWORK_CONFIGURE)(IN EFI_MANAGED_NETWORK_PROTOCOL *This, IN EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL)
Sets or clears the operational parameters for the MNP child driver.
#define OUT
Definition: mlx_utils.h:29
16-byte buffer aligned on a 4-byte boundary.
Definition: UefiBaseType.h:110
The EFI_SIMPLE_NETWORK_PROTOCOL provides services to initialize a network interface,...
EFI_STATUS(EFIAPI * EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC)(IN EFI_MANAGED_NETWORK_PROTOCOL *This, IN BOOLEAN Ipv6Flag, IN EFI_IP_ADDRESS *IpAddress, OUT EFI_MAC_ADDRESS *MacAddress)
Translates an IP multicast address to a hardware (MAC) multicast address.
EFI_STATUS(EFIAPI * EFI_MANAGED_NETWORK_RECEIVE)(IN EFI_MANAGED_NETWORK_PROTOCOL *This, IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token)
Places an asynchronous receiving request into the receiving queue.
unsigned short UINT16
Definition: ProcessorBind.h:58
BOOLEAN EnableBroadcastReceive
Set to TRUE to receive packets that are sent to the network device broadcast address.
#define EFIAPI
EFI_MANAGED_NETWORK_CANCEL Cancel
FILE_LICENCE(BSD3)
#define VOID
Undeclared type.
Definition: Base.h:319
UINT16 ProtocolTypeFilter
Ethernet type II 16-bit protocol type in host byte order.
EFI Time Abstraction: Year: 1900 - 9999 Month: 1 - 12 Day: 1 - 31 Hour: 0 - 23 Minute: 0 - 59 Second:...
Definition: UefiBaseType.h:74
#define IN
Definition: mlx_utils.h:28
EFI_STATUS(EFIAPI * EFI_MANAGED_NETWORK_GET_MODE_DATA)(IN EFI_MANAGED_NETWORK_PROTOCOL *This, OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL, OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL)
Returns the operational parameters for the current MNP child driver.
EFI_EVENT Event
This Event will be signaled after the Status field is updated by the MNP.
EFI_STATUS Status
The status that is returned to the caller at the end of the operation to indicate whether this operat...
BOOLEAN EnablePromiscuousReceive
Set to TRUE to receive packets that are sent to any MAC address.
EFI_GUID gEfiManagedNetworkServiceBindingProtocolGuid
EFI_MANAGED_NETWORK_RECEIVE Receive
EFI_MANAGED_NETWORK_RECEIVE_DATA * RxData
When this token is used for receiving, RxData is a pointer to the EFI_MANAGED_NETWORK_RECEIVE_DATA.
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:35
EFI_STATUS(EFIAPI * EFI_MANAGED_NETWORK_CANCEL)(IN EFI_MANAGED_NETWORK_PROTOCOL *This, IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token OPTIONAL)
Aborts an asynchronous transmit or receive request.
EFI_MANAGED_NETWORK_CONFIGURE Configure
BOOLEAN EnableReceiveTimestamps
Set to TRUE to timestamp all packets when they are received by the MNP.
EFI_MANAGED_NETWORK_GET_MODE_DATA GetModeData
UINT32 TransmitQueueTimeoutValue
Timeout value for a UEFI one-shot timer event.
BOOLEAN EnableUnicastReceive
Set to TRUE to receive packets that are sent to the network device MAC address.
EFI_STATUS(EFIAPI * EFI_MANAGED_NETWORK_POLL)(IN EFI_MANAGED_NETWORK_PROTOCOL *This)
Polls for incoming data packets and processes outgoing data packets.
BOOLEAN FlushQueuesOnReset
Set to TRUE to drop queued packets when the configuration is changed.
EFI_MANAGED_NETWORK_TRANSMIT_DATA * TxData
When this token is used for transmitting, TxData is a pointer to the EFI_MANAGED_NETWORK_TRANSMIT_DAT...