• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 #include <Protocol/SimpleNetwork.h>
23 
24 #define EFI_MANAGED_NETWORK_SERVICE_BINDING_PROTOCOL_GUID \
25   { \
26     0xf36ff770, 0xa7e1, 0x42cf, {0x9e, 0xd2, 0x56, 0xf0, 0xf2, 0x71, 0xf4, 0x4c } \
27   }
28 
29 #define EFI_MANAGED_NETWORK_PROTOCOL_GUID \
30   { \
31     0x7ab33a91, 0xace5, 0x4326, { 0xb5, 0x72, 0xe7, 0xee, 0x33, 0xd3, 0x9f, 0x16 } \
32   }
33 
34 typedef struct _EFI_MANAGED_NETWORK_PROTOCOL EFI_MANAGED_NETWORK_PROTOCOL;
35 
36 typedef struct {
37   ///
38   /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed
39   /// from the MNP receive queue will be dropped if its receive timeout expires.
40   ///
41   UINT32     ReceivedQueueTimeoutValue;
42   ///
43   /// Timeout value for a UEFI one-shot timer event. A packet that has not been removed
44   /// from the MNP transmit queue will be dropped if its receive timeout expires.
45   ///
46   UINT32     TransmitQueueTimeoutValue;
47   ///
48   /// Ethernet type II 16-bit protocol type in host byte order. Valid
49   /// values are zero and 1,500 to 65,535.
50   ///
51   UINT16     ProtocolTypeFilter;
52   ///
53   /// Set to TRUE to receive packets that are sent to the network
54   /// device MAC address. The startup default value is FALSE.
55   ///
56   BOOLEAN    EnableUnicastReceive;
57   ///
58   /// Set to TRUE to receive packets that are sent to any of the
59   /// active multicast groups. The startup default value is FALSE.
60   ///
61   BOOLEAN    EnableMulticastReceive;
62   ///
63   /// Set to TRUE to receive packets that are sent to the network
64   /// device broadcast address. The startup default value is FALSE.
65   ///
66   BOOLEAN    EnableBroadcastReceive;
67   ///
68   /// Set to TRUE to receive packets that are sent to any MAC address.
69   /// The startup default value is FALSE.
70   ///
71   BOOLEAN    EnablePromiscuousReceive;
72   ///
73   /// Set to TRUE to drop queued packets when the configuration
74   /// is changed. The startup default value is FALSE.
75   ///
76   BOOLEAN    FlushQueuesOnReset;
77   ///
78   /// Set to TRUE to timestamp all packets when they are received
79   /// by the MNP. Note that timestamps may be unsupported in some
80   /// MNP implementations. The startup default value is FALSE.
81   ///
82   BOOLEAN    EnableReceiveTimestamps;
83   ///
84   /// Set to TRUE to disable background polling in this MNP
85   /// instance. Note that background polling may not be supported in
86   /// all MNP implementations. The startup default value is FALSE,
87   /// unless background polling is not supported.
88   ///
89   BOOLEAN    DisableBackgroundPolling;
90 } EFI_MANAGED_NETWORK_CONFIG_DATA;
91 
92 typedef struct {
93   EFI_TIME      Timestamp;
94   EFI_EVENT     RecycleEvent;
95   UINT32        PacketLength;
96   UINT32        HeaderLength;
97   UINT32        AddressLength;
98   UINT32        DataLength;
99   BOOLEAN       BroadcastFlag;
100   BOOLEAN       MulticastFlag;
101   BOOLEAN       PromiscuousFlag;
102   UINT16        ProtocolType;
103   VOID          *DestinationAddress;
104   VOID          *SourceAddress;
105   VOID          *MediaHeader;
106   VOID          *PacketData;
107 } EFI_MANAGED_NETWORK_RECEIVE_DATA;
108 
109 typedef struct {
110   UINT32        FragmentLength;
111   VOID          *FragmentBuffer;
112 } EFI_MANAGED_NETWORK_FRAGMENT_DATA;
113 
114 typedef struct {
115   EFI_MAC_ADDRESS                   *DestinationAddress; //OPTIONAL
116   EFI_MAC_ADDRESS                   *SourceAddress;      //OPTIONAL
117   UINT16                            ProtocolType;        //OPTIONAL
118   UINT32                            DataLength;
119   UINT16                            HeaderLength;        //OPTIONAL
120   UINT16                            FragmentCount;
121   EFI_MANAGED_NETWORK_FRAGMENT_DATA FragmentTable[1];
122 } EFI_MANAGED_NETWORK_TRANSMIT_DATA;
123 
124 
125 typedef struct {
126   ///
127   /// This Event will be signaled after the Status field is updated
128   /// by the MNP. The type of Event must be
129   /// EFI_NOTIFY_SIGNAL. The Task Priority Level (TPL) of
130   /// Event must be lower than or equal to TPL_CALLBACK.
131   ///
132   EFI_EVENT                             Event;
133   ///
134   /// The status that is returned to the caller at the end of the operation
135   /// to indicate whether this operation completed successfully.
136   ///
137   EFI_STATUS                            Status;
138   union {
139     ///
140     /// When this token is used for receiving, RxData is a pointer to the EFI_MANAGED_NETWORK_RECEIVE_DATA.
141     ///
142     EFI_MANAGED_NETWORK_RECEIVE_DATA    *RxData;
143     ///
144     /// When this token is used for transmitting, TxData is a pointer to the EFI_MANAGED_NETWORK_TRANSMIT_DATA.
145     ///
146     EFI_MANAGED_NETWORK_TRANSMIT_DATA   *TxData;
147   } Packet;
148 } EFI_MANAGED_NETWORK_COMPLETION_TOKEN;
149 
150 /**
151   Returns the operational parameters for the current MNP child driver.
152 
153   @param  This          The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
154   @param  MnpConfigData The pointer to storage for MNP operational parameters.
155   @param  SnpModeData   The pointer to storage for SNP operational parameters.
156 
157   @retval EFI_SUCCESS           The operation completed successfully.
158   @retval EFI_INVALID_PARAMETER This is NULL.
159   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
160   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured. The default
161                                 values are returned in MnpConfigData if it is not NULL.
162   @retval Other                 The mode data could not be read.
163 
164 **/
165 typedef
166 EFI_STATUS
167 (EFIAPI *EFI_MANAGED_NETWORK_GET_MODE_DATA)(
168   IN  EFI_MANAGED_NETWORK_PROTOCOL     *This,
169   OUT EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData  OPTIONAL,
170   OUT EFI_SIMPLE_NETWORK_MODE          *SnpModeData    OPTIONAL
171   );
172 
173 /**
174   Sets or clears the operational parameters for the MNP child driver.
175 
176   @param  This          The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
177   @param  MnpConfigData The pointer to configuration data that will be assigned to the MNP
178                         child driver instance. If NULL, the MNP child driver instance is
179                         reset to startup defaults and all pending transmit and receive
180                         requests are flushed.
181 
182   @retval EFI_SUCCESS           The operation completed successfully.
183   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
184   @retval EFI_OUT_OF_RESOURCES  Required system resources (usually memory) could not be
185                                 allocated.
186   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this [MNP]
187                                 implementation.
188   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
189   @retval Other                 The MNP child driver instance has been reset to startup defaults.
190 
191 **/
192 typedef
193 EFI_STATUS
194 (EFIAPI *EFI_MANAGED_NETWORK_CONFIGURE)(
195   IN EFI_MANAGED_NETWORK_PROTOCOL     *This,
196   IN EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData  OPTIONAL
197   );
198 
199 /**
200   Translates an IP multicast address to a hardware (MAC) multicast address.
201 
202   @param  This       The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
203   @param  Ipv6Flag   Set to TRUE to if IpAddress is an IPv6 multicast address.
204                      Set to FALSE if IpAddress is an IPv4 multicast address.
205   @param  IpAddress  The pointer to the multicast IP address (in network byte order) to convert.
206   @param  MacAddress The pointer to the resulting multicast MAC address.
207 
208   @retval EFI_SUCCESS           The operation completed successfully.
209   @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:
210                                 - This is NULL.
211                                 - IpAddress is NULL.
212                                 - *IpAddress is not a valid multicast IP address.
213                                 - MacAddress is NULL.
214   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
215   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
216   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
217   @retval Other                 The address could not be converted.
218 
219 **/
220 typedef
221 EFI_STATUS
222 (EFIAPI *EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC)(
223   IN  EFI_MANAGED_NETWORK_PROTOCOL  *This,
224   IN  BOOLEAN                       Ipv6Flag,
225   IN  EFI_IP_ADDRESS                *IpAddress,
226   OUT EFI_MAC_ADDRESS               *MacAddress
227   );
228 
229 /**
230   Enables and disables receive filters for multicast address.
231 
232   @param  This       The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
233   @param  JoinFlag   Set to TRUE to join this multicast group.
234                      Set to FALSE to leave this multicast group.
235   @param  MacAddress The pointer to the multicast MAC group (address) to join or leave.
236 
237   @retval EFI_SUCCESS           The requested operation completed successfully.
238   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
239                                 - This is NULL.
240                                 - JoinFlag is TRUE and MacAddress is NULL.
241                                 - *MacAddress is not a valid multicast MAC address.
242   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
243   @retval EFI_ALREADY_STARTED   The supplied multicast group is already joined.
244   @retval EFI_NOT_FOUND         The supplied multicast group is not joined.
245   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
246   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP implementation.
247   @retval Other                 The requested operation could not be completed.
248 
249 **/
250 typedef
251 EFI_STATUS
252 (EFIAPI *EFI_MANAGED_NETWORK_GROUPS)(
253   IN EFI_MANAGED_NETWORK_PROTOCOL  *This,
254   IN BOOLEAN                       JoinFlag,
255   IN EFI_MAC_ADDRESS               *MacAddress  OPTIONAL
256   );
257 
258 /**
259   Places asynchronous outgoing data packets into the transmit queue.
260 
261   @param  This  The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
262   @param  Token The pointer to a token associated with the transmit data descriptor.
263 
264   @retval EFI_SUCCESS           The transmit completion token was cached.
265   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
266   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
267   @retval EFI_ACCESS_DENIED     The transmit completion token is already in the transmit queue.
268   @retval EFI_OUT_OF_RESOURCES  The transmit data could not be queued due to a lack of system resources
269                                 (usually memory).
270   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
271   @retval EFI_NOT_READY         The transmit request could not be queued because the transmit queue is full.
272 
273 **/
274 typedef
275 EFI_STATUS
276 (EFIAPI *EFI_MANAGED_NETWORK_TRANSMIT)(
277   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
278   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token
279   );
280 
281 /**
282   Places an asynchronous receiving request into the receiving queue.
283 
284   @param  This  The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
285   @param  Token The pointer to a token associated with the receive data descriptor.
286 
287   @retval EFI_SUCCESS           The receive completion token was cached.
288   @retval EFI_NOT_STARTED       This MNP child driver instance has not been configured.
289   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
290                                 - This is NULL.
291                                 - Token is NULL.
292                                 - Token.Event is NULL.
293   @retval EFI_OUT_OF_RESOURCES  The transmit data could not be queued due to a lack of system resources
294                                 (usually memory).
295   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
296   @retval EFI_ACCESS_DENIED     The receive completion token was already in the receive queue.
297   @retval EFI_NOT_READY         The receive request could not be queued because the receive queue is full.
298 
299 **/
300 typedef
301 EFI_STATUS
302 (EFIAPI *EFI_MANAGED_NETWORK_RECEIVE)(
303   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
304   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token
305   );
306 
307 
308 /**
309   Aborts an asynchronous transmit or receive request.
310 
311   @param  This  The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
312   @param  Token The pointer to a token that has been issued by
313                 EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or
314                 EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If
315                 NULL, all pending tokens are aborted.
316 
317   @retval  EFI_SUCCESS           The asynchronous I/O request was aborted and Token.Event
318                                  was signaled. When Token is NULL, all pending requests were
319                                  aborted and their events were signaled.
320   @retval  EFI_NOT_STARTED       This MNP child driver instance has not been configured.
321   @retval  EFI_INVALID_PARAMETER This is NULL.
322   @retval  EFI_NOT_FOUND         When Token is not NULL, the asynchronous I/O request was
323                                  not found in the transmit or receive queue. It has either completed
324                                  or was not issued by Transmit() and Receive().
325 
326 **/
327 typedef
328 EFI_STATUS
329 (EFIAPI *EFI_MANAGED_NETWORK_CANCEL)(
330   IN EFI_MANAGED_NETWORK_PROTOCOL          *This,
331   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token  OPTIONAL
332   );
333 
334 /**
335   Polls for incoming data packets and processes outgoing data packets.
336 
337   @param  This The pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
338 
339   @retval EFI_SUCCESS      Incoming or outgoing data was processed.
340   @retval EFI_NOT_STARTED  This MNP child driver instance has not been configured.
341   @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
342   @retval EFI_NOT_READY    No incoming or outgoing data was processed. Consider increasing
343                            the polling rate.
344   @retval EFI_TIMEOUT      Data was dropped out of the transmit and/or receive queue.
345                             Consider increasing the polling rate.
346 
347 **/
348 typedef
349 EFI_STATUS
350 (EFIAPI *EFI_MANAGED_NETWORK_POLL)(
351   IN EFI_MANAGED_NETWORK_PROTOCOL    *This
352   );
353 
354 ///
355 /// The MNP is used by network applications (and drivers) to
356 /// perform raw (unformatted) asynchronous network packet I/O.
357 ///
358 struct _EFI_MANAGED_NETWORK_PROTOCOL {
359   EFI_MANAGED_NETWORK_GET_MODE_DATA       GetModeData;
360   EFI_MANAGED_NETWORK_CONFIGURE           Configure;
361   EFI_MANAGED_NETWORK_MCAST_IP_TO_MAC     McastIpToMac;
362   EFI_MANAGED_NETWORK_GROUPS              Groups;
363   EFI_MANAGED_NETWORK_TRANSMIT            Transmit;
364   EFI_MANAGED_NETWORK_RECEIVE             Receive;
365   EFI_MANAGED_NETWORK_CANCEL              Cancel;
366   EFI_MANAGED_NETWORK_POLL                Poll;
367 };
368 
369 extern EFI_GUID gEfiManagedNetworkServiceBindingProtocolGuid;
370 extern EFI_GUID gEfiManagedNetworkProtocolGuid;
371 
372 #endif
373