MnpImpl.h@ 80721

Last change on this file since 80721 was 80721, checked in by vboxsync, 5 years ago
Devices/EFI/FirmwareNew: Start upgrade process to edk2-stable201908 (compiles on Windows and works to some extent), bugref:4643
Property svn:eol-style set to `native`
File size: 33.5 KB

Line
1	/** @file
2	Declaration of structures and functions of MnpDxe driver.
3
4	Copyright (c) 2005 - 2018, Intel Corporation. All rights reserved.<BR>
5	SPDX-License-Identifier: BSD-2-Clause-Patent
6
7	**/
8
9	#ifndef _MNP_IMPL_H_
10	#define _MNP_IMPL_H_
11
12	#include "MnpDriver.h"
13
14	#define NET_ETHER_FCS_SIZE 4
15
16	#define MNP_SYS_POLL_INTERVAL (10 * TICKS_PER_MS) // 10 milliseconds
17	#define MNP_TIMEOUT_CHECK_INTERVAL (50 * TICKS_PER_MS) // 50 milliseconds
18	#define MNP_MEDIA_DETECT_INTERVAL (500 * TICKS_PER_MS) // 500 milliseconds
19	#define MNP_TX_TIMEOUT_TIME (500 * TICKS_PER_MS) // 500 milliseconds
20	#define MNP_INIT_NET_BUFFER_NUM 512
21	#define MNP_NET_BUFFER_INCREASEMENT 64
22	#define MNP_MAX_NET_BUFFER_NUM 65536
23	#define MNP_TX_BUFFER_INCREASEMENT 32 // Same as the recycling Q length for xmit_done in UNDI command.
24	#define MNP_MAX_TX_BUFFER_NUM 65536
25
26	#define MNP_MAX_RCVD_PACKET_QUE_SIZE 256
27
28	#define MNP_RECEIVE_UNICAST 0x01
29	#define MNP_RECEIVE_BROADCAST 0x02
30
31	#define UNICAST_PACKET MNP_RECEIVE_UNICAST
32	#define BROADCAST_PACKET MNP_RECEIVE_BROADCAST
33
34	#define MNP_INSTANCE_DATA_SIGNATURE SIGNATURE_32 ('M', 'n', 'p', 'I')
35
36	#define MNP_INSTANCE_DATA_FROM_THIS(a) \
37	CR ( \
38	(a), \
39	MNP_INSTANCE_DATA, \
40	ManagedNetwork, \
41	MNP_INSTANCE_DATA_SIGNATURE \
42	)
43
44	typedef struct {
45	UINT32 Signature;
46
47	MNP_SERVICE_DATA *MnpServiceData;
48
49	EFI_HANDLE Handle;
50
51	LIST_ENTRY InstEntry;
52
53	EFI_MANAGED_NETWORK_PROTOCOL ManagedNetwork;
54
55	BOOLEAN Configured;
56	BOOLEAN Destroyed;
57
58	LIST_ENTRY GroupCtrlBlkList;
59
60	NET_MAP RxTokenMap;
61
62	LIST_ENTRY RxDeliveredPacketQueue;
63	LIST_ENTRY RcvdPacketQueue;
64	UINTN RcvdPacketQueueSize;
65
66	EFI_MANAGED_NETWORK_CONFIG_DATA ConfigData;
67
68	UINT8 ReceiveFilter;
69	} MNP_INSTANCE_DATA;
70
71	typedef struct {
72	LIST_ENTRY AddrEntry;
73	EFI_MAC_ADDRESS Address;
74	INTN RefCnt;
75	} MNP_GROUP_ADDRESS;
76
77	typedef struct {
78	LIST_ENTRY CtrlBlkEntry;
79	MNP_GROUP_ADDRESS *GroupAddress;
80	} MNP_GROUP_CONTROL_BLOCK;
81
82	typedef struct {
83	LIST_ENTRY WrapEntry;
84	MNP_INSTANCE_DATA *Instance;
85	EFI_MANAGED_NETWORK_RECEIVE_DATA RxData;
86	NET_BUF *Nbuf;
87	UINT64 TimeoutTick;
88	} MNP_RXDATA_WRAP;
89
90	#define MNP_TX_BUF_WRAP_SIGNATURE SIGNATURE_32 ('M', 'T', 'B', 'W')
91
92	typedef struct {
93	UINT32 Signature;
94	LIST_ENTRY WrapEntry; // Link to FreeTxBufList
95	LIST_ENTRY AllEntry; // Link to AllTxBufList
96	BOOLEAN InUse;
97	UINT8 TxBuf[1];
98	} MNP_TX_BUF_WRAP;
99
100	/**
101	Initialize the mnp device context data.
102
103	@param[in, out] MnpDeviceData Pointer to the mnp device context data.
104	@param[in] ImageHandle The driver image handle.
105	@param[in] ControllerHandle Handle of device to bind driver to.
106
107	@retval EFI_SUCCESS The mnp service context is initialized.
108	@retval EFI_UNSUPPORTED ControllerHandle does not support Simple Network Protocol.
109	@retval Others Other errors as indicated.
110
111	**/
112	EFI_STATUS
113	MnpInitializeDeviceData (
114	IN OUT MNP_DEVICE_DATA *MnpDeviceData,
115	IN EFI_HANDLE ImageHandle,
116	IN EFI_HANDLE ControllerHandle
117	);
118
119	/**
120	Destroy the MNP device context data.
121
122	@param[in, out] MnpDeviceData Pointer to the mnp device context data.
123	@param[in] ImageHandle The driver image handle.
124
125	**/
126	VOID
127	MnpDestroyDeviceData (
128	IN OUT MNP_DEVICE_DATA *MnpDeviceData,
129	IN EFI_HANDLE ImageHandle
130	);
131
132	/**
133	Create mnp service context data.
134
135	@param[in] MnpDeviceData Pointer to the mnp device context data.
136	@param[in] VlanId The VLAN ID.
137	@param[in] Priority The VLAN priority. If VlanId is 0,
138	Priority is ignored.
139
140	@return A pointer to MNP_SERVICE_DATA or NULL if failed to create MNP service context.
141
142	**/
143	MNP_SERVICE_DATA *
144	MnpCreateServiceData (
145	IN MNP_DEVICE_DATA *MnpDeviceData,
146	IN UINT16 VlanId,
147	IN UINT8 Priority OPTIONAL
148	);
149
150	/**
151	Initialize the mnp service context data.
152
153	@param[in, out] MnpServiceData Pointer to the mnp service context data.
154	@param[in] ImageHandle The driver image handle.
155	@param[in] ControllerHandle Handle of device to bind driver to.
156
157	@retval EFI_SUCCESS The mnp service context is initialized.
158	@retval EFI_UNSUPPORTED ControllerHandle does not support Simple Network Protocol.
159	@retval Others Other errors as indicated.
160
161	**/
162	EFI_STATUS
163	MnpInitializeServiceData (
164	IN OUT MNP_SERVICE_DATA *MnpServiceData,
165	IN EFI_HANDLE ImageHandle,
166	IN EFI_HANDLE ControllerHandle
167	);
168
169	/**
170	Destroy the MNP service context data.
171
172	@param[in, out] MnpServiceData Pointer to the mnp service context data.
173
174	@retval EFI_SUCCESS The mnp service context is destroyed.
175	@retval Others Errors as indicated.
176
177	**/
178	EFI_STATUS
179	MnpDestroyServiceData (
180	IN OUT MNP_SERVICE_DATA *MnpServiceData
181	);
182
183	/**
184	Destroy all child of the MNP service data.
185
186	@param[in, out] MnpServiceData Pointer to the mnp service context data.
187
188	@retval EFI_SUCCESS All child are destroyed.
189	@retval Others Failed to destroy all child.
190
191	**/
192	EFI_STATUS
193	MnpDestroyServiceChild (
194	IN OUT MNP_SERVICE_DATA *MnpServiceData
195	);
196
197	/**
198	Find the MNP Service Data for given VLAN ID.
199
200	@param[in] MnpDeviceData Pointer to the mnp device context data.
201	@param[in] VlanId The VLAN ID.
202
203	@return A pointer to MNP_SERVICE_DATA or NULL if not found.
204
205	**/
206	MNP_SERVICE_DATA *
207	MnpFindServiceData (
208	IN MNP_DEVICE_DATA *MnpDeviceData,
209	IN UINT16 VlanId
210	);
211
212	/**
213	Initialize the mnp instance context data.
214
215	@param[in] MnpServiceData Pointer to the mnp service context data.
216	@param[in, out] Instance Pointer to the mnp instance context data
217	to initialize.
218
219	**/
220	VOID
221	MnpInitializeInstanceData (
222	IN MNP_SERVICE_DATA *MnpServiceData,
223	IN OUT MNP_INSTANCE_DATA *Instance
224	);
225
226	/**
227	Check whether the token specified by Arg matches the token in Item.
228
229	@param[in] Map Pointer to the NET_MAP.
230	@param[in] Item Pointer to the NET_MAP_ITEM.
231	@param[in] Arg Pointer to the Arg, it's a pointer to the token to
232	check.
233
234	@retval EFI_SUCCESS The token specified by Arg is different from the
235	token in Item.
236	@retval EFI_ACCESS_DENIED The token specified by Arg is the same as that in
237	Item.
238
239	**/
240	EFI_STATUS
241	EFIAPI
242	MnpTokenExist (
243	IN NET_MAP *Map,
244	IN NET_MAP_ITEM *Item,
245	IN VOID *Arg
246	);
247
248	/**
249	Cancel the token specified by Arg if it matches the token in Item.
250
251	@param[in, out] Map Pointer to the NET_MAP.
252	@param[in, out] Item Pointer to the NET_MAP_ITEM.
253	@param[in] Arg Pointer to the Arg, it's a pointer to the
254	token to cancel.
255
256	@retval EFI_SUCCESS The Arg is NULL, and the token in Item is cancelled,
257	or the Arg isn't NULL, and the token in Item is
258	different from the Arg.
259	@retval EFI_ABORTED The Arg isn't NULL, the token in Item mathces the
260	Arg, and the token is cancelled.
261
262	**/
263	EFI_STATUS
264	EFIAPI
265	MnpCancelTokens (
266	IN OUT NET_MAP *Map,
267	IN OUT NET_MAP_ITEM *Item,
268	IN VOID *Arg
269	);
270
271	/**
272	Flush the instance's received data.
273
274	@param[in, out] Instance Pointer to the mnp instance context data.
275
276	**/
277	VOID
278	MnpFlushRcvdDataQueue (
279	IN OUT MNP_INSTANCE_DATA *Instance
280	);
281
282	/**
283	Configure the Instance using ConfigData.
284
285	@param[in, out] Instance Pointer to the mnp instance context data.
286	@param[in] ConfigData Pointer to the configuration data used to configure
287	the isntance.
288
289	@retval EFI_SUCCESS The Instance is configured.
290	@retval EFI_UNSUPPORTED EnableReceiveTimestamps is on and the
291	implementation doesn't support it.
292	@retval Others Other errors as indicated.
293
294	**/
295	EFI_STATUS
296	MnpConfigureInstance (
297	IN OUT MNP_INSTANCE_DATA *Instance,
298	IN EFI_MANAGED_NETWORK_CONFIG_DATA *ConfigData OPTIONAL
299	);
300
301	/**
302	Do the group operations for this instance.
303
304	@param[in, out] Instance Pointer to the instance context data.
305	@param[in] JoinFlag Set to TRUE to join a group. Set to TRUE to
306	leave a group/groups.
307	@param[in] MacAddress Pointer to the group address to join or leave.
308	@param[in] CtrlBlk Pointer to the group control block if JoinFlag
309	is FALSE.
310
311	@retval EFI_SUCCESS The group operation finished.
312	@retval EFI_OUT_OF_RESOURCES Failed due to lack of memory resources.
313	@retval Others Other errors as indicated.
314
315	**/
316	EFI_STATUS
317	MnpGroupOp (
318	IN OUT MNP_INSTANCE_DATA *Instance,
319	IN BOOLEAN JoinFlag,
320	IN EFI_MAC_ADDRESS *MacAddress OPTIONAL,
321	IN MNP_GROUP_CONTROL_BLOCK *CtrlBlk OPTIONAL
322	);
323
324	/**
325	Validates the Mnp transmit token.
326
327	@param[in] Instance Pointer to the Mnp instance context data.
328	@param[in] Token Pointer to the transmit token to check.
329
330	@return The Token is valid or not.
331
332	**/
333	BOOLEAN
334	MnpIsValidTxToken (
335	IN MNP_INSTANCE_DATA *Instance,
336	IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token
337	);
338
339	/**
340	Build the packet to transmit from the TxData passed in.
341
342	@param[in] MnpServiceData Pointer to the mnp service context data.
343	@param[in] TxData Pointer to the transmit data containing the information
344	to build the packet.
345	@param[out] PktBuf Pointer to record the address of the packet.
346	@param[out] PktLen Pointer to a UINT32 variable used to record the packet's
347	length.
348
349	@retval EFI_SUCCESS TxPackage is built.
350	@retval EFI_OUT_OF_RESOURCES The deliver fails due to lack of memory resource.
351
352	**/
353	EFI_STATUS
354	MnpBuildTxPacket (
355	IN MNP_SERVICE_DATA *MnpServiceData,
356	IN EFI_MANAGED_NETWORK_TRANSMIT_DATA *TxData,
357	OUT UINT8 **PktBuf,
358	OUT UINT32 *PktLen
359	);
360
361	/**
362	Synchronously send out the packet.
363
364	This functon places the packet buffer to SNP driver's tansmit queue. The packet
365	can be considered successfully sent out once SNP acccetp the packet, while the
366	packet buffer recycle is deferred for better performance.
367
368	@param[in] MnpServiceData Pointer to the mnp service context data.
369	@param[in] Packet Pointer to the pakcet buffer.
370	@param[in] Length The length of the packet.
371	@param[in, out] Token Pointer to the token the packet generated from.
372
373	@retval EFI_SUCCESS The packet is sent out.
374	@retval EFI_TIMEOUT Time out occurs, the packet isn't sent.
375	@retval EFI_DEVICE_ERROR An unexpected network error occurs.
376
377	**/
378	EFI_STATUS
379	MnpSyncSendPacket (
380	IN MNP_SERVICE_DATA *MnpServiceData,
381	IN UINT8 *Packet,
382	IN UINT32 Length,
383	IN OUT EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token
384	);
385
386	/**
387	Try to deliver the received packet to the instance.
388
389	@param[in, out] Instance Pointer to the mnp instance context data.
390
391	@retval EFI_SUCCESS The received packet is delivered, or there is no
392	packet to deliver, or there is no available receive
393	token.
394	@retval EFI_OUT_OF_RESOURCES The deliver fails due to lack of memory resource.
395
396	**/
397	EFI_STATUS
398	MnpInstanceDeliverPacket (
399	IN OUT MNP_INSTANCE_DATA *Instance
400	);
401
402	/**
403	Recycle the RxData and other resources used to hold and deliver the received
404	packet.
405
406	@param[in] Event The event this notify function registered to.
407	@param[in] Context Pointer to the context data registerd to the Event.
408
409	**/
410	VOID
411	EFIAPI
412	MnpRecycleRxData (
413	IN EFI_EVENT Event,
414	IN VOID *Context
415	);
416
417	/**
418	Try to receive a packet and deliver it.
419
420	@param[in, out] MnpDeviceData Pointer to the mnp device context data.
421
422	@retval EFI_SUCCESS add return value to function comment
423	@retval EFI_NOT_STARTED The simple network protocol is not started.
424	@retval EFI_NOT_READY No packet received.
425	@retval EFI_DEVICE_ERROR An unexpected error occurs.
426
427	**/
428	EFI_STATUS
429	MnpReceivePacket (
430	IN OUT MNP_DEVICE_DATA *MnpDeviceData
431	);
432
433	/**
434	Allocate a free NET_BUF from MnpDeviceData->FreeNbufQue. If there is none
435	in the queue, first try to allocate some and add them into the queue, then
436	fetch the NET_BUF from the updated FreeNbufQue.
437
438	@param[in, out] MnpDeviceData Pointer to the MNP_DEVICE_DATA.
439
440	@return Pointer to the allocated free NET_BUF structure, if NULL the
441	operation is failed.
442
443	**/
444	NET_BUF *
445	MnpAllocNbuf (
446	IN OUT MNP_DEVICE_DATA *MnpDeviceData
447	);
448
449	/**
450	Try to reclaim the Nbuf into the buffer pool.
451
452	@param[in, out] MnpDeviceData Pointer to the mnp device context data.
453	@param[in, out] Nbuf Pointer to the NET_BUF to free.
454
455	**/
456	VOID
457	MnpFreeNbuf (
458	IN OUT MNP_DEVICE_DATA *MnpDeviceData,
459	IN OUT NET_BUF *Nbuf
460	);
461
462	/**
463	Allocate a free TX buffer from MnpDeviceData->FreeTxBufList. If there is none
464	in the queue, first try to recycle some from SNP, then try to allocate some and add
465	them into the queue, then fetch the NET_BUF from the updated FreeTxBufList.
466
467	@param[in, out] MnpDeviceData Pointer to the MNP_DEVICE_DATA.
468
469	@return Pointer to the allocated free NET_BUF structure, if NULL the
470	operation is failed.
471
472	**/
473	UINT8 *
474	MnpAllocTxBuf (
475	IN OUT MNP_DEVICE_DATA *MnpDeviceData
476	);
477
478	/**
479	Try to recycle all the transmitted buffer address from SNP.
480
481	@param[in, out] MnpDeviceData Pointer to the mnp device context data.
482
483	@retval EFI_SUCCESS Successed to recyclethe transmitted buffer address.
484	@retval Others Failed to recyclethe transmitted buffer address.
485
486	**/
487	EFI_STATUS
488	MnpRecycleTxBuf (
489	IN OUT MNP_DEVICE_DATA *MnpDeviceData
490	);
491
492	/**
493	Remove the received packets if timeout occurs.
494
495	@param[in] Event The event this notify function registered to.
496	@param[in] Context Pointer to the context data registered to the event.
497
498	**/
499	VOID
500	EFIAPI
501	MnpCheckPacketTimeout (
502	IN EFI_EVENT Event,
503	IN VOID *Context
504	);
505
506	/**
507	Poll to update MediaPresent field in SNP ModeData by Snp.GetStatus().
508
509	@param[in] Event The event this notify function registered to.
510	@param[in] Context Pointer to the context data registered to the event.
511
512	**/
513	VOID
514	EFIAPI
515	MnpCheckMediaStatus (
516	IN EFI_EVENT Event,
517	IN VOID *Context
518	);
519
520	/**
521	Poll to receive the packets from Snp. This function is either called by upperlayer
522	protocols/applications or the system poll timer notify mechanism.
523
524	@param[in] Event The event this notify function registered to.
525	@param[in] Context Pointer to the context data registered to the event.
526
527	**/
528	VOID
529	EFIAPI
530	MnpSystemPoll (
531	IN EFI_EVENT Event,
532	IN VOID *Context
533	);
534
535	/**
536	Returns the operational parameters for the current MNP child driver. May also
537	support returning the underlying SNP driver mode data.
538
539	The GetModeData() function is used to read the current mode data (operational
540	parameters) from the MNP or the underlying SNP.
541
542	@param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
543	@param[out] MnpConfigData Pointer to storage for MNP operational parameters. Type
544	EFI_MANAGED_NETWORK_CONFIG_DATA is defined in "Related
545	Definitions" below.
546	@param[out] SnpModeData Pointer to storage for SNP operational parameters. This
547	feature may be unsupported. Type EFI_SIMPLE_NETWORK_MODE
548	is defined in the EFI_SIMPLE_NETWORK_PROTOCOL.
549
550	@retval EFI_SUCCESS The operation completed successfully.
551	@retval EFI_INVALID_PARAMETER This is NULL.
552	@retval EFI_UNSUPPORTED The requested feature is unsupported in this
553	MNP implementation.
554	@retval EFI_NOT_STARTED This MNP child driver instance has not been
555	configured. The default values are returned in
556	MnpConfigData if it is not NULL.
557	@retval Others The mode data could not be read.
558
559	**/
560	EFI_STATUS
561	EFIAPI
562	MnpGetModeData (
563	IN EFI_MANAGED_NETWORK_PROTOCOL *This,
564	OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL,
565	OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL
566	);
567
568	/**
569	Sets or clears the operational parameters for the MNP child driver.
570
571	The Configure() function is used to set, change, or reset the operational
572	parameters for the MNP child driver instance. Until the operational parameters
573	have been set, no network traffic can be sent or received by this MNP child
574	driver instance. Once the operational parameters have been reset, no more
575	traffic can be sent or received until the operational parameters have been set
576	again.
577	Each MNP child driver instance can be started and stopped independently of
578	each other by setting or resetting their receive filter settings with the
579	Configure() function.
580	After any successful call to Configure(), the MNP child driver instance is
581	started. The internal periodic timer (if supported) is enabled. Data can be
582	transmitted and may be received if the receive filters have also been enabled.
583	Note: If multiple MNP child driver instances will receive the same packet
584	because of overlapping receive filter settings, then the first MNP child
585	driver instance will receive the original packet and additional instances will
586	receive copies of the original packet.
587	Note: Warning: Receive filter settings that overlap will consume extra
588	processor and/or DMA resources and degrade system and network performance.
589
590	@param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
591	@param[in] MnpConfigData Pointer to configuration data that will be assigned
592	to the MNP child driver instance. If NULL, the MNP
593	child driver instance is reset to startup defaults
594	and all pending transmit and receive requests are
595	flushed. Type EFI_MANAGED_NETWORK_CONFIG_DATA is
596	defined in EFI_MANAGED_NETWORK_PROTOCOL.GetModeData().
597
598	@retval EFI_SUCCESS The operation completed successfully.
599	@retval EFI_INVALID_PARAMETER One or more of the following conditions is
600	TRUE:
601	* This is NULL.
602	* MnpConfigData.ProtocolTypeFilter is not
603	valid.
604	The operational data for the MNP child driver
605	instance is unchanged.
606	@retval EFI_OUT_OF_RESOURCES Required system resources (usually memory)
607	could not be allocated.
608	The MNP child driver instance has been reset to
609	startup defaults.
610	@retval EFI_UNSUPPORTED The requested feature is unsupported in
611	this [MNP] implementation. The operational data
612	for the MNP child driver instance is unchanged.
613	@retval EFI_DEVICE_ERROR An unexpected network or system error
614	occurred. The MNP child driver instance has
615	been reset to startup defaults.
616	@retval Others The MNP child driver instance has been reset to
617	startup defaults.
618
619	**/
620	EFI_STATUS
621	EFIAPI
622	MnpConfigure (
623	IN EFI_MANAGED_NETWORK_PROTOCOL *This,
624	IN EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL
625	);
626
627	/**
628	Translates an IP multicast address to a hardware (MAC) multicast address. This
629	function may be unsupported in some MNP implementations.
630
631	The McastIpToMac() function translates an IP multicast address to a hardware
632	(MAC) multicast address. This function may be implemented by calling the
633	underlying EFI_SIMPLE_NETWORK. MCastIpToMac() function, which may also be
634	unsupported in some MNP implementations.
635
636	@param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
637	@param[in] Ipv6Flag Set to TRUE to if IpAddress is an IPv6 multicast address.
638	Set to FALSE if IpAddress is an IPv4 multicast address.
639	@param[in] IpAddress Pointer to the multicast IP address (in network byte
640	order) to convert.
641	@param[out] MacAddress Pointer to the resulting multicast MAC address.
642
643	@retval EFI_SUCCESS The operation completed successfully.
644	@retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:
645	* This is NULL.
646	* IpAddress is NULL.
647	* IpAddress is not a valid multicast IP
648	address.
649	* MacAddress is NULL.
650	@retval EFI_NOT_STARTED This MNP child driver instance has not been
651	configured.
652	@retval EFI_UNSUPPORTED The requested feature is unsupported in this
653	MNP implementation.
654	@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
655	@retval Others The address could not be converted.
656	**/
657	EFI_STATUS
658	EFIAPI
659	MnpMcastIpToMac (
660	IN EFI_MANAGED_NETWORK_PROTOCOL *This,
661	IN BOOLEAN Ipv6Flag,
662	IN EFI_IP_ADDRESS *IpAddress,
663	OUT EFI_MAC_ADDRESS *MacAddress
664	);
665
666	/**
667	Enables and disables receive filters for multicast address. This function may
668	be unsupported in some MNP implementations.
669
670	The Groups() function only adds and removes multicast MAC addresses from the
671	filter list. The MNP driver does not transmit or process Internet Group
672	Management Protocol (IGMP) packets. If JoinFlag is FALSE and MacAddress is
673	NULL, then all joined groups are left.
674
675	@param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
676	@param[in] JoinFlag Set to TRUE to join this multicast group.
677	Set to FALSE to leave this multicast group.
678	@param[in] MacAddress Pointer to the multicast MAC group (address) to join or
679	leave.
680
681	@retval EFI_SUCCESS The requested operation completed successfully.
682	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
683	* This is NULL.
684	* JoinFlag is TRUE and MacAddress is NULL.
685	* MacAddress is not a valid multicast MAC
686	address.
687	* The MNP multicast group settings are
688	unchanged.
689	@retval EFI_NOT_STARTED This MNP child driver instance has not been
690	configured.
691	@retval EFI_ALREADY_STARTED The supplied multicast group is already joined.
692	@retval EFI_NOT_FOUND The supplied multicast group is not joined.
693	@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
694	The MNP child driver instance has been reset to
695	startup defaults.
696	@retval EFI_UNSUPPORTED The requested feature is unsupported in this MNP
697	implementation.
698	@retval Others The requested operation could not be completed.
699	The MNP multicast group settings are unchanged.
700
701	**/
702	EFI_STATUS
703	EFIAPI
704	MnpGroups (
705	IN EFI_MANAGED_NETWORK_PROTOCOL *This,
706	IN BOOLEAN JoinFlag,
707	IN EFI_MAC_ADDRESS *MacAddress OPTIONAL
708	);
709
710	/**
711	Places asynchronous outgoing data packets into the transmit queue.
712
713	The Transmit() function places a completion token into the transmit packet
714	queue. This function is always asynchronous.
715	The caller must fill in the Token.Event and Token.TxData fields in the
716	completion token, and these fields cannot be NULL. When the transmit operation
717	completes, the MNP updates the Token.Status field and the Token.Event is
718	signaled.
719	Note: There may be a performance penalty if the packet needs to be
720	defragmented before it can be transmitted by the network device. Systems in
721	which performance is critical should review the requirements and features of
722	the underlying communications device and drivers.
723
724
725	@param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
726	@param[in] Token Pointer to a token associated with the transmit data
727	descriptor. Type EFI_MANAGED_NETWORK_COMPLETION_TOKEN
728	is defined in "Related Definitions" below.
729
730	@retval EFI_SUCCESS The transmit completion token was cached.
731	@retval EFI_NOT_STARTED This MNP child driver instance has not been
732	configured.
733	@retval EFI_INVALID_PARAMETER One or more of the following conditions is
734	TRUE:
735	* This is NULL.
736	* Token is NULL.
737	* Token.Event is NULL.
738	* Token.TxData is NULL.
739	* Token.TxData.DestinationAddress is not
740	NULL and Token.TxData.HeaderLength is zero.
741	* Token.TxData.FragmentCount is zero.
742	* (Token.TxData.HeaderLength +
743	Token.TxData.DataLength) is not equal to the
744	sum of the
745	Token.TxData.FragmentTable[].FragmentLength
746	fields.
747	* One or more of the
748	Token.TxData.FragmentTable[].FragmentLength
749	fields is zero.
750	* One or more of the
751	Token.TxData.FragmentTable[].FragmentBufferfields
752	is NULL.
753	* Token.TxData.DataLength is greater than MTU.
754	@retval EFI_ACCESS_DENIED The transmit completion token is already in the
755	transmit queue.
756	@retval EFI_OUT_OF_RESOURCES The transmit data could not be queued due to a
757	lack of system resources (usually memory).
758	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
759	The MNP child driver instance has been reset to
760	startup defaults.
761	@retval EFI_NOT_READY The transmit request could not be queued because
762	the transmit queue is full.
763
764	**/
765	EFI_STATUS
766	EFIAPI
767	MnpTransmit (
768	IN EFI_MANAGED_NETWORK_PROTOCOL *This,
769	IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token
770	);
771
772	/**
773	Aborts an asynchronous transmit or receive request.
774
775	The Cancel() function is used to abort a pending transmit or receive request.
776	If the token is in the transmit or receive request queues, after calling this
777	function, Token.Status will be set to EFI_ABORTED and then Token.Event will be
778	signaled. If the token is not in one of the queues, which usually means that
779	the asynchronous operation has completed, this function will not signal the
780	token and EFI_NOT_FOUND is returned.
781
782	@param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
783	@param[in] Token Pointer to a token that has been issued by
784	EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or
785	EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If NULL, all
786	pending tokens are aborted.
787
788	@retval EFI_SUCCESS The asynchronous I/O request was aborted and
789	Token.Event was signaled. When Token is NULL,
790	all pending requests were aborted and their
791	events were signaled.
792	@retval EFI_NOT_STARTED This MNP child driver instance has not been
793	configured.
794	@retval EFI_INVALID_PARAMETER This is NULL.
795	@retval EFI_NOT_FOUND When Token is not NULL, the asynchronous I/O
796	request was not found in the transmit or
797	receive queue. It has either completed or was
798	not issued by Transmit() and Receive().
799
800	**/
801	EFI_STATUS
802	EFIAPI
803	MnpCancel (
804	IN EFI_MANAGED_NETWORK_PROTOCOL *This,
805	IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token OPTIONAL
806	);
807
808	/**
809	Places an asynchronous receiving request into the receiving queue.
810
811	The Receive() function places a completion token into the receive packet
812	queue. This function is always asynchronous.
813	The caller must fill in the Token.Event field in the completion token, and
814	this field cannot be NULL. When the receive operation completes, the MNP
815	updates the Token.Status and Token.RxData fields and the Token.Event is
816	signaled.
817
818	@param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
819	@param[in] Token Pointer to a token associated with the receive
820	data descriptor. Type
821	EFI_MANAGED_NETWORK_COMPLETION_TOKEN is defined in
822	EFI_MANAGED_NETWORK_PROTOCOL.Transmit().
823
824	@retval EFI_SUCCESS The receive completion token was cached.
825	@retval EFI_NOT_STARTED This MNP child driver instance has not been
826	configured.
827	@retval EFI_INVALID_PARAMETER One or more of the following conditions is
828	TRUE:
829	* This is NULL.
830	* Token is NULL.
831	* Token.Event is NULL
832	@retval EFI_OUT_OF_RESOURCES The transmit data could not be queued due to a
833	lack of system resources (usually memory).
834	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
835	The MNP child driver instance has been reset to
836	startup defaults.
837	@retval EFI_ACCESS_DENIED The receive completion token was already in the
838	receive queue.
839	@retval EFI_NOT_READY The receive request could not be queued because
840	the receive queue is full.
841
842	**/
843	EFI_STATUS
844	EFIAPI
845	MnpReceive (
846	IN EFI_MANAGED_NETWORK_PROTOCOL *This,
847	IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN *Token
848	);
849
850	/**
851	Polls for incoming data packets and processes outgoing data packets.
852
853	The Poll() function can be used by network drivers and applications to
854	increase the rate that data packets are moved between the communications
855	device and the transmit and receive queues.
856	Normally, a periodic timer event internally calls the Poll() function. But, in
857	some systems, the periodic timer event may not call Poll() fast enough to
858	transmit and/or receive all data packets without missing packets. Drivers and
859	applications that are experiencing packet loss should try calling the Poll()
860	function more often.
861
862	@param[in] This Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
863
864	@retval EFI_SUCCESS Incoming or outgoing data was processed.
865	@retval EFI_NOT_STARTED This MNP child driver instance has not been
866	configured.
867	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The
868	MNP child driver instance has been reset to startup
869	defaults.
870	@retval EFI_NOT_READY No incoming or outgoing data was processed. Consider
871	increasing the polling rate.
872	@retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive
873	queue. Consider increasing the polling rate.
874
875	**/
876	EFI_STATUS
877	EFIAPI
878	MnpPoll (
879	IN EFI_MANAGED_NETWORK_PROTOCOL *This
880	);
881
882	/**
883	Configure the Snp receive filters according to the instances' receive filter
884	settings.
885
886	@param[in] MnpDeviceData Pointer to the mnp device context data.
887
888	@retval EFI_SUCCESS The receive filters is configured.
889	@retval EFI_OUT_OF_RESOURCES The receive filters can't be configured due
890	to lack of memory resource.
891
892	**/
893	EFI_STATUS
894	MnpConfigReceiveFilters (
895	IN MNP_DEVICE_DATA *MnpDeviceData
896	);
897
898	#endif

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/NetworkPkg/MnpDxe/MnpImpl.h@ 80721

Download in other formats: