Snp.h@ 89989

Last change on this file since 89989 was 85718, checked in by vboxsync, 4 years ago
Devices/EFI: Merge edk-stable202005 and make it build, bugref:4643
Property svn:eol-style set to `native`
File size: 44.9 KB

Line
1	/** @file
2	Declaration of structures and functions for SnpDxe driver.
3
4	Copyright (c) 2004 - 2019, Intel Corporation. All rights reserved.<BR>
5	SPDX-License-Identifier: BSD-2-Clause-Patent
6
7	**/
8	#ifndef _SNP_H_
9	#define _SNP_H_
10
11
12	#include <Uefi.h>
13
14	#include <Protocol/SimpleNetwork.h>
15	#include <Protocol/PciIo.h>
16	#include <Protocol/NetworkInterfaceIdentifier.h>
17	#include <Protocol/DevicePath.h>
18
19	#include <Guid/EventGroup.h>
20
21	#include <Library/DebugLib.h>
22	#include <Library/BaseMemoryLib.h>
23	#include <Library/UefiDriverEntryPoint.h>
24	#include <Library/UefiBootServicesTableLib.h>
25	#include <Library/BaseLib.h>
26	#include <Library/UefiLib.h>
27	#include <Library/MemoryAllocationLib.h>
28	#include <Library/PrintLib.h>
29	#include <Library/PcdLib.h>
30
31	#include <IndustryStandard/Pci.h>
32	#include <IndustryStandard/Acpi.h>
33
34	#define FOUR_GIGABYTES (UINT64) 0x100000000ULL
35
36
37	#define SNP_DRIVER_SIGNATURE SIGNATURE_32 ('s', 'n', 'd', 's')
38	#define MAX_MAP_LENGTH 100
39
40	#define PCI_BAR_IO_MASK 0x00000003
41	#define PCI_BAR_IO_MODE 0x00000001
42
43	#define PCI_BAR_MEM_MASK 0x0000000F
44	#define PCI_BAR_MEM_MODE 0x00000000
45	#define PCI_BAR_MEM_64BIT 0x00000004
46
47	#define SNP_TX_BUFFER_INCREASEMENT MAX_XMIT_BUFFERS
48	#define SNP_MAX_TX_BUFFER_NUM 65536
49
50	typedef
51	EFI_STATUS
52	(EFIAPI *ISSUE_UNDI32_COMMAND) (
53	UINT64 Cdb
54	);
55
56	typedef struct {
57	UINT32 Signature;
58	EFI_LOCK Lock;
59
60	EFI_SIMPLE_NETWORK_PROTOCOL Snp;
61	EFI_SIMPLE_NETWORK_MODE Mode;
62
63	EFI_HANDLE DeviceHandle;
64	EFI_DEVICE_PATH_PROTOCOL *DevicePath;
65
66	//
67	// Local instance data needed by SNP driver
68	//
69	// Pointer to S/W UNDI API entry point
70	// This will be NULL for H/W UNDI
71	//
72	ISSUE_UNDI32_COMMAND IssueUndi32Command;
73
74	BOOLEAN IsSwUndi;
75
76	//
77	// undi interface number, if one undi manages more nics
78	//
79	PXE_IFNUM IfNum;
80
81	//
82	// Allocated tx/rx buffer that was passed to UNDI Initialize.
83	//
84	UINT32 TxRxBufferSize;
85	VOID *TxRxBuffer;
86	//
87	// mappable buffers for receive and fill header for undi3.0
88	// these will be used if the user buffers are above 4GB limit (instead of
89	// mapping the user buffers)
90	//
91	UINT8 *ReceiveBufffer;
92	VOID *ReceiveBufferUnmap;
93	UINT8 *FillHeaderBuffer;
94	VOID *FillHeaderBufferUnmap;
95
96	EFI_PCI_IO_PROTOCOL *PciIo;
97	UINT8 IoBarIndex;
98	UINT8 MemoryBarIndex;
99
100	//
101	// Buffers for command descriptor block, command parameter block
102	// and data block.
103	//
104	PXE_CDB Cdb;
105	VOID *Cpb;
106	VOID *CpbUnmap;
107	VOID *Db;
108
109	//
110	// UNDI structure, we need to remember the init info for a long time!
111	//
112	PXE_DB_GET_INIT_INFO InitInfo;
113
114	VOID *SnpDriverUnmap;
115	//
116	// when ever we map an address, we must remember it's address and the un-map
117	// cookie so that we can unmap later
118	//
119	struct MAP_LIST {
120	EFI_PHYSICAL_ADDRESS VirtualAddress;
121	VOID *MapCookie;
122	} MapList[MAX_MAP_LENGTH];
123
124	EFI_EVENT ExitBootServicesEvent;
125
126	//
127	// Whether UNDI support reporting media status from GET_STATUS command,
128	// i.e. PXE_STATFLAGS_GET_STATUS_NO_MEDIA_SUPPORTED or
129	// PXE_STATFLAGS_GET_STATUS_NO_MEDIA_NOT_SUPPORTED
130	//
131	BOOLEAN MediaStatusSupported;
132
133	//
134	// Whether UNDI support cable detect for INITIALIZE command,
135	// i.e. PXE_STATFLAGS_CABLE_DETECT_SUPPORTED or
136	// PXE_STATFLAGS_CABLE_DETECT_NOT_SUPPORTED
137	//
138	BOOLEAN CableDetectSupported;
139
140	//
141	// Array of the recycled transmit buffer address from UNDI.
142	//
143	UINT64 *RecycledTxBuf;
144	//
145	// The maximum number of recycled buffer pointers in RecycledTxBuf.
146	//
147	UINT32 MaxRecycledTxBuf;
148	//
149	// Current number of recycled buffer pointers in RecycledTxBuf.
150	//
151	UINT32 RecycledTxBufCount;
152	} SNP_DRIVER;
153
154	#define EFI_SIMPLE_NETWORK_DEV_FROM_THIS(a) CR (a, SNP_DRIVER, Snp, SNP_DRIVER_SIGNATURE)
155
156	//
157	// Global Variables
158	//
159	extern EFI_DRIVER_BINDING_PROTOCOL gSimpleNetworkDriverBinding;
160	extern EFI_COMPONENT_NAME_PROTOCOL gSimpleNetworkComponentName;
161	extern EFI_COMPONENT_NAME2_PROTOCOL gSimpleNetworkComponentName2;
162
163	/**
164	this routine calls undi to start the interface and changes the snp state.
165
166	@param Snp pointer to snp driver structure
167
168	@retval EFI_DEVICE_ERROR UNDI could not be started
169	@retval EFI_SUCCESS UNDI is started successfully
170
171	**/
172	EFI_STATUS
173	PxeStart (
174	IN SNP_DRIVER *Snp
175	);
176
177	/**
178	this routine calls undi to stop the interface and changes the snp state.
179
180	@param Snp pointer to snp driver structure
181
182	@retval EFI_INVALID_PARAMETER invalid parameter
183	@retval EFI_NOT_STARTED SNP is not started
184	@retval EFI_DEVICE_ERROR SNP is not initialized
185	@retval EFI_UNSUPPORTED operation unsupported
186
187	**/
188	EFI_STATUS
189	PxeStop (
190	SNP_DRIVER *Snp
191	);
192
193	/**
194	this routine calls undi to initialize the interface.
195
196	@param Snp pointer to snp driver structure
197	@param CableDetectFlag Do/don't detect the cable (depending on what undi supports)
198
199	@retval EFI_SUCCESS UNDI is initialized successfully
200	@retval EFI_DEVICE_ERROR UNDI could not be initialized
201	@retval Other other errors
202
203	**/
204	EFI_STATUS
205	PxeInit (
206	SNP_DRIVER *Snp,
207	UINT16 CableDetectFlag
208	);
209
210	/**
211	this routine calls undi to shut down the interface.
212
213	@param Snp pointer to snp driver structure
214
215	@retval EFI_SUCCESS UNDI is shut down successfully
216	@retval EFI_DEVICE_ERROR UNDI could not be shut down
217
218	**/
219	EFI_STATUS
220	PxeShutdown (
221	IN SNP_DRIVER *Snp
222	);
223
224	/**
225	this routine calls undi to read the MAC address of the NIC and updates the
226	mode structure with the address.
227
228	@param Snp pointer to snp driver structure.
229
230	@retval EFI_SUCCESS the MAC address of the NIC is read successfully.
231	@retval EFI_DEVICE_ERROR failed to read the MAC address of the NIC.
232
233	**/
234	EFI_STATUS
235	PxeGetStnAddr (
236	SNP_DRIVER *Snp
237	);
238
239	/**
240	Call undi to get the status of the interrupts, get the list of recycled transmit
241	buffers that completed transmitting. The recycled transmit buffer address will
242	be saved into Snp->RecycledTxBuf. This function will also update the MediaPresent
243	field of EFI_SIMPLE_NETWORK_MODE if UNDI support it.
244
245	@param[in] Snp Pointer to snp driver structure.
246	@param[out] InterruptStatusPtr A non null pointer to contain the interrupt
247	status.
248	@param[in] GetTransmittedBuf Set to TRUE to retrieve the recycled transmit
249	buffer address.
250
251	@retval EFI_SUCCESS The status of the network interface was retrieved.
252	@retval EFI_DEVICE_ERROR The command could not be sent to the network
253	interface.
254
255	**/
256	EFI_STATUS
257	PxeGetStatus (
258	IN SNP_DRIVER *Snp,
259	OUT UINT32 *InterruptStatusPtr,
260	IN BOOLEAN GetTransmittedBuf
261	);
262
263	/**
264	This is a callback routine supplied to UNDI3.1 at undi_start time.
265	UNDI call this routine when it wants to have exclusive access to a critical
266	section of the code/data.
267	New callbacks for 3.1:
268	there won't be a virtual2physical callback for UNDI 3.1 because undi3.1 uses
269	the MemMap call to map the required address by itself!
270
271	@param UniqueId This was supplied to UNDI at Undi_Start, SNP uses this to
272	store Undi interface context (Undi does not read or write
273	this variable)
274	@param Enable non-zero indicates acquire
275	zero indicates release
276	**/
277	VOID
278	EFIAPI
279	SnpUndi32CallbackBlock (
280	IN UINT64 UniqueId,
281	IN UINT32 Enable
282	);
283
284	/**
285	This is a callback routine supplied to UNDI at undi_start time.
286	UNDI call this routine with the number of micro seconds when it wants to
287	pause.
288
289	@param UniqueId This was supplied to UNDI at Undi_Start, SNP uses this to
290	store Undi interface context (Undi does not read or write
291	this variable)
292	@param MicroSeconds number of micro seconds to pause, usually multiple of 10.
293	**/
294	VOID
295	EFIAPI
296	SnpUndi32CallbackDelay (
297	IN UINT64 UniqueId,
298	IN UINT64 MicroSeconds
299	);
300
301	/**
302	This is a callback routine supplied to UNDI at undi_start time.
303	This is the IO routine for UNDI3.1 to start CPB.
304
305	@param UniqueId This was supplied to UNDI at Undi_Start, SNP uses this
306	to store Undi interface context (Undi does not read or
307	write this variable)
308	@param ReadOrWrite indicates read or write, IO or Memory.
309	@param NumBytes number of bytes to read or write.
310	@param MemOrPortAddr IO or memory address to read from or write to.
311	@param BufferPtr memory location to read into or that contains the bytes
312	to write.
313	**/
314	VOID
315	EFIAPI
316	SnpUndi32CallbackMemio (
317	IN UINT64 UniqueId,
318	IN UINT8 ReadOrWrite,
319	IN UINT8 NumBytes,
320	IN UINT64 MemOrPortAddr,
321	IN OUT UINT64 BufferPtr
322	);
323
324	/**
325	This is a callback routine supplied to UNDI at undi_start time.
326	UNDI call this routine when it has to map a CPU address to a device
327	address.
328
329	@param UniqueId - This was supplied to UNDI at Undi_Start, SNP uses this to store
330	Undi interface context (Undi does not read or write this variable)
331	@param CpuAddr - Virtual address to be mapped!
332	@param NumBytes - size of memory to be mapped
333	@param Direction - direction of data flow for this memory's usage:
334	cpu->device, device->cpu or both ways
335	@param DeviceAddrPtr - pointer to return the mapped device address
336
337	**/
338	VOID
339	EFIAPI
340	SnpUndi32CallbackMap (
341	IN UINT64 UniqueId,
342	IN UINT64 CpuAddr,
343	IN UINT32 NumBytes,
344	IN UINT32 Direction,
345	IN OUT UINT64 DeviceAddrPtr
346	);
347
348	/**
349	This is a callback routine supplied to UNDI at undi_start time.
350	UNDI call this routine when it wants to unmap an address that was previously
351	mapped using map callback.
352
353	@param UniqueId This was supplied to UNDI at Undi_Start, SNP uses this to store.
354	Undi interface context (Undi does not read or write this variable)
355	@param CpuAddr Virtual address that was mapped!
356	@param NumBytes size of memory mapped
357	@param Direction direction of data flow for this memory's usage:
358	cpu->device, device->cpu or both ways
359	@param DeviceAddr the mapped device address
360
361	**/
362	VOID
363	EFIAPI
364	SnpUndi32CallbackUnmap (
365	IN UINT64 UniqueId,
366	IN UINT64 CpuAddr,
367	IN UINT32 NumBytes,
368	IN UINT32 Direction,
369	IN UINT64 DeviceAddr
370	);
371
372	/**
373	This is a callback routine supplied to UNDI at undi_start time.
374	UNDI call this routine when it wants synchronize the virtual buffer contents
375	with the mapped buffer contents. The virtual and mapped buffers need not
376	correspond to the same physical memory (especially if the virtual address is
377	> 4GB). Depending on the direction for which the buffer is mapped, undi will
378	need to synchronize their contents whenever it writes to/reads from the buffer
379	using either the cpu address or the device address.
380
381	EFI does not provide a sync call, since virt=physical, we should just do
382	the synchronization ourself here!
383
384	@param UniqueId This was supplied to UNDI at Undi_Start, SNP uses this to store
385	Undi interface context (Undi does not read or write this variable)
386	@param CpuAddr Virtual address that was mapped!
387	@param NumBytes size of memory mapped.
388	@param Direction direction of data flow for this memory's usage:
389	cpu->device, device->cpu or both ways.
390	@param DeviceAddr the mapped device address.
391
392	**/
393	VOID
394	EFIAPI
395	SnpUndi32CallbackSync (
396	IN UINT64 UniqueId,
397	IN UINT64 CpuAddr,
398	IN UINT32 NumBytes,
399	IN UINT32 Direction,
400	IN UINT64 DeviceAddr
401	);
402
403	/**
404	Changes the state of a network interface from "stopped" to "started".
405
406	This function starts a network interface. If the network interface successfully
407	starts, then EFI_SUCCESS will be returned.
408
409	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
410
411	@retval EFI_SUCCESS The network interface was started.
412	@retval EFI_ALREADY_STARTED The network interface is already in the started state.
413	@retval EFI_INVALID_PARAMETER This parameter was NULL or did not point to a valid
414	EFI_SIMPLE_NETWORK_PROTOCOL structure.
415	@retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
416	@retval EFI_UNSUPPORTED This function is not supported by the network interface.
417
418	**/
419	EFI_STATUS
420	EFIAPI
421	SnpUndi32Start (
422	IN EFI_SIMPLE_NETWORK_PROTOCOL *This
423	);
424
425	/**
426	Changes the state of a network interface from "started" to "stopped".
427
428	This function stops a network interface. This call is only valid if the network
429	interface is in the started state. If the network interface was successfully
430	stopped, then EFI_SUCCESS will be returned.
431
432	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
433
434
435	@retval EFI_SUCCESS The network interface was stopped.
436	@retval EFI_NOT_STARTED The network interface has not been started.
437	@retval EFI_INVALID_PARAMETER This parameter was NULL or did not point to a valid
438	EFI_SIMPLE_NETWORK_PROTOCOL structure.
439	@retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
440	@retval EFI_UNSUPPORTED This function is not supported by the network interface.
441
442	**/
443	EFI_STATUS
444	EFIAPI
445	SnpUndi32Stop (
446	IN EFI_SIMPLE_NETWORK_PROTOCOL *This
447	);
448
449	/**
450	Resets a network adapter and allocates the transmit and receive buffers
451	required by the network interface; optionally, also requests allocation of
452	additional transmit and receive buffers.
453
454	This function allocates the transmit and receive buffers required by the network
455	interface. If this allocation fails, then EFI_OUT_OF_RESOURCES is returned.
456	If the allocation succeeds and the network interface is successfully initialized,
457	then EFI_SUCCESS will be returned.
458
459	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
460
461	@param ExtraRxBufferSize The size, in bytes, of the extra receive buffer space
462	that the driver should allocate for the network interface.
463	Some network interfaces will not be able to use the
464	extra buffer, and the caller will not know if it is
465	actually being used.
466	@param ExtraTxBufferSize The size, in bytes, of the extra transmit buffer space
467	that the driver should allocate for the network interface.
468	Some network interfaces will not be able to use the
469	extra buffer, and the caller will not know if it is
470	actually being used.
471
472	@retval EFI_SUCCESS The network interface was initialized.
473	@retval EFI_NOT_STARTED The network interface has not been started.
474	@retval EFI_OUT_OF_RESOURCES There was not enough memory for the transmit and
475	receive buffers.
476	@retval EFI_INVALID_PARAMETER This parameter was NULL or did not point to a valid
477	EFI_SIMPLE_NETWORK_PROTOCOL structure.
478	@retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
479	@retval EFI_UNSUPPORTED The increased buffer size feature is not supported.
480
481	**/
482	EFI_STATUS
483	EFIAPI
484	SnpUndi32Initialize (
485	IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
486	IN UINTN ExtraRxBufferSize OPTIONAL,
487	IN UINTN ExtraTxBufferSize OPTIONAL
488	);
489
490	/**
491	Resets a network adapter and reinitializes it with the parameters that were
492	provided in the previous call to Initialize().
493
494	This function resets a network adapter and reinitializes it with the parameters
495	that were provided in the previous call to Initialize(). The transmit and
496	receive queues are emptied and all pending interrupts are cleared.
497	Receive filters, the station address, the statistics, and the multicast-IP-to-HW
498	MAC addresses are not reset by this call. If the network interface was
499	successfully reset, then EFI_SUCCESS will be returned. If the driver has not
500	been initialized, EFI_DEVICE_ERROR will be returned.
501
502	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
503	@param ExtendedVerification Indicates that the driver may perform a more
504	exhaustive verification operation of the device
505	during reset.
506
507	@retval EFI_SUCCESS The network interface was reset.
508	@retval EFI_NOT_STARTED The network interface has not been started.
509	@retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
510	@retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
511	@retval EFI_UNSUPPORTED This function is not supported by the network interface.
512
513	**/
514	EFI_STATUS
515	EFIAPI
516	SnpUndi32Reset (
517	IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
518	IN BOOLEAN ExtendedVerification
519	);
520
521	/**
522	Resets a network adapter and leaves it in a state that is safe for another
523	driver to initialize.
524
525	This function releases the memory buffers assigned in the Initialize() call.
526	Pending transmits and receives are lost, and interrupts are cleared and disabled.
527	After this call, only the Initialize() and Stop() calls may be used. If the
528	network interface was successfully shutdown, then EFI_SUCCESS will be returned.
529	If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
530
531	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
532
533	@retval EFI_SUCCESS The network interface was shutdown.
534	@retval EFI_NOT_STARTED The network interface has not been started.
535	@retval EFI_INVALID_PARAMETER This parameter was NULL or did not point to a valid
536	EFI_SIMPLE_NETWORK_PROTOCOL structure.
537	@retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
538
539	**/
540	EFI_STATUS
541	EFIAPI
542	SnpUndi32Shutdown (
543	IN EFI_SIMPLE_NETWORK_PROTOCOL *This
544	);
545
546	/**
547	Manages the multicast receive filters of a network interface.
548
549	This function is used enable and disable the hardware and software receive
550	filters for the underlying network device.
551	The receive filter change is broken down into three steps:
552	* The filter mask bits that are set (ON) in the Enable parameter are added to
553	the current receive filter settings.
554	* The filter mask bits that are set (ON) in the Disable parameter are subtracted
555	from the updated receive filter settings.
556	* If the resulting receive filter setting is not supported by the hardware a
557	more liberal setting is selected.
558	If the same bits are set in the Enable and Disable parameters, then the bits
559	in the Disable parameter takes precedence.
560	If the ResetMCastFilter parameter is TRUE, then the multicast address list
561	filter is disabled (irregardless of what other multicast bits are set in the
562	Enable and Disable parameters). The SNP->Mode->MCastFilterCount field is set
563	to zero. The Snp->Mode->MCastFilter contents are undefined.
564	After enabling or disabling receive filter settings, software should verify
565	the new settings by checking the Snp->Mode->ReceiveFilterSettings,
566	Snp->Mode->MCastFilterCount and Snp->Mode->MCastFilter fields.
567	Note: Some network drivers and/or devices will automatically promote receive
568	filter settings if the requested setting can not be honored. For example, if
569	a request for four multicast addresses is made and the underlying hardware
570	only supports two multicast addresses the driver might set the promiscuous
571	or promiscuous multicast receive filters instead. The receiving software is
572	responsible for discarding any extra packets that get through the hardware
573	receive filters.
574	Note: Note: To disable all receive filter hardware, the network driver must
575	be Shutdown() and Stopped(). Calling ReceiveFilters() with Disable set to
576	Snp->Mode->ReceiveFilterSettings will make it so no more packets are
577	returned by the Receive() function, but the receive hardware may still be
578	moving packets into system memory before inspecting and discarding them.
579	Unexpected system errors, reboots and hangs can occur if an OS is loaded
580	and the network devices are not Shutdown() and Stopped().
581	If ResetMCastFilter is TRUE, then the multicast receive filter list on the
582	network interface will be reset to the default multicast receive filter list.
583	If ResetMCastFilter is FALSE, and this network interface allows the multicast
584	receive filter list to be modified, then the MCastFilterCnt and MCastFilter
585	are used to update the current multicast receive filter list. The modified
586	receive filter list settings can be found in the MCastFilter field of
587	EFI_SIMPLE_NETWORK_MODE. If the network interface does not allow the multicast
588	receive filter list to be modified, then EFI_INVALID_PARAMETER will be returned.
589	If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
590	If the receive filter mask and multicast receive filter list have been
591	successfully updated on the network interface, EFI_SUCCESS will be returned.
592
593	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
594	@param Enable A bit mask of receive filters to enable on the network
595	interface.
596	@param Disable A bit mask of receive filters to disable on the network
597	interface. For backward compatibility with EFI 1.1
598	platforms, the EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST bit
599	must be set when the ResetMCastFilter parameter is TRUE.
600	@param ResetMCastFilter Set to TRUE to reset the contents of the multicast
601	receive filters on the network interface to their
602	default values.
603	@param MCastFilterCnt Number of multicast HW MAC addresses in the new MCastFilter
604	list. This value must be less than or equal to the
605	MCastFilterCnt field of EFI_SIMPLE_NETWORK_MODE.
606	This field is optional if ResetMCastFilter is TRUE.
607	@param MCastFilter A pointer to a list of new multicast receive filter HW
608	MAC addresses. This list will replace any existing
609	multicast HW MAC address list. This field is optional
610	if ResetMCastFilter is TRUE.
611
612	@retval EFI_SUCCESS The multicast receive filter list was updated.
613	@retval EFI_NOT_STARTED The network interface has not been started.
614	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
615	* This is NULL
616	* There are bits set in Enable that are not set
617	in Snp->Mode->ReceiveFilterMask
618	* There are bits set in Disable that are not set
619	in Snp->Mode->ReceiveFilterMask
620	* Multicast is being enabled (the
621	EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST bit is
622	set in Enable, it is not set in Disable, and
623	ResetMCastFilter is FALSE) and MCastFilterCount
624	is zero
625	* Multicast is being enabled and MCastFilterCount
626	is greater than Snp->Mode->MaxMCastFilterCount
627	* Multicast is being enabled and MCastFilter is NULL
628	* Multicast is being enabled and one or more of
629	the addresses in the MCastFilter list are not
630	valid multicast MAC addresses
631	@retval EFI_DEVICE_ERROR One or more of the following conditions is TRUE:
632	* The network interface has been started but has
633	not been initialized
634	* An unexpected error was returned by the
635	underlying network driver or device
636	@retval EFI_UNSUPPORTED This function is not supported by the network
637	interface.
638
639	**/
640	EFI_STATUS
641	EFIAPI
642	SnpUndi32ReceiveFilters (
643	IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
644	IN UINT32 Enable,
645	IN UINT32 Disable,
646	IN BOOLEAN ResetMCastFilter,
647	IN UINTN MCastFilterCnt, OPTIONAL
648	IN EFI_MAC_ADDRESS *MCastFilter OPTIONAL
649	);
650
651	/**
652	Modifies or resets the current station address, if supported.
653
654	This function modifies or resets the current station address of a network
655	interface, if supported. If Reset is TRUE, then the current station address is
656	set to the network interface's permanent address. If Reset is FALSE, and the
657	network interface allows its station address to be modified, then the current
658	station address is changed to the address specified by New. If the network
659	interface does not allow its station address to be modified, then
660	EFI_INVALID_PARAMETER will be returned. If the station address is successfully
661	updated on the network interface, EFI_SUCCESS will be returned. If the driver
662	has not been initialized, EFI_DEVICE_ERROR will be returned.
663
664	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
665	@param Reset Flag used to reset the station address to the network interface's
666	permanent address.
667	@param New New station address to be used for the network interface.
668
669
670	@retval EFI_SUCCESS The network interface's station address was updated.
671	@retval EFI_NOT_STARTED The Simple Network Protocol interface has not been
672	started by calling Start().
673	@retval EFI_INVALID_PARAMETER The New station address was not accepted by the NIC.
674	@retval EFI_INVALID_PARAMETER Reset is FALSE and New is NULL.
675	@retval EFI_DEVICE_ERROR The Simple Network Protocol interface has not
676	been initialized by calling Initialize().
677	@retval EFI_DEVICE_ERROR An error occurred attempting to set the new
678	station address.
679	@retval EFI_UNSUPPORTED The NIC does not support changing the network
680	interface's station address.
681
682	**/
683	EFI_STATUS
684	EFIAPI
685	SnpUndi32StationAddress (
686	IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
687	IN BOOLEAN Reset,
688	IN EFI_MAC_ADDRESS *New OPTIONAL
689	);
690
691	/**
692	Resets or collects the statistics on a network interface.
693
694	This function resets or collects the statistics on a network interface. If the
695	size of the statistics table specified by StatisticsSize is not big enough for
696	all the statistics that are collected by the network interface, then a partial
697	buffer of statistics is returned in StatisticsTable, StatisticsSize is set to
698	the size required to collect all the available statistics, and
699	EFI_BUFFER_TOO_SMALL is returned.
700	If StatisticsSize is big enough for all the statistics, then StatisticsTable
701	will be filled, StatisticsSize will be set to the size of the returned
702	StatisticsTable structure, and EFI_SUCCESS is returned.
703	If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
704	If Reset is FALSE, and both StatisticsSize and StatisticsTable are NULL, then
705	no operations will be performed, and EFI_SUCCESS will be returned.
706	If Reset is TRUE, then all of the supported statistics counters on this network
707	interface will be reset to zero.
708
709	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
710	@param Reset Set to TRUE to reset the statistics for the network interface.
711	@param StatisticsSize On input the size, in bytes, of StatisticsTable. On output
712	the size, in bytes, of the resulting table of statistics.
713	@param StatisticsTable A pointer to the EFI_NETWORK_STATISTICS structure that
714	contains the statistics. Type EFI_NETWORK_STATISTICS is
715	defined in "Related Definitions" below.
716
717	@retval EFI_SUCCESS The requested operation succeeded.
718	@retval EFI_NOT_STARTED The Simple Network Protocol interface has not been
719	started by calling Start().
720	@retval EFI_BUFFER_TOO_SMALL StatisticsSize is not NULL and StatisticsTable is
721	NULL. The current buffer size that is needed to
722	hold all the statistics is returned in StatisticsSize.
723	@retval EFI_BUFFER_TOO_SMALL StatisticsSize is not NULL and StatisticsTable is
724	not NULL. The current buffer size that is needed
725	to hold all the statistics is returned in
726	StatisticsSize. A partial set of statistics is
727	returned in StatisticsTable.
728	@retval EFI_INVALID_PARAMETER StatisticsSize is NULL and StatisticsTable is not
729	NULL.
730	@retval EFI_DEVICE_ERROR The Simple Network Protocol interface has not
731	been initialized by calling Initialize().
732	@retval EFI_DEVICE_ERROR An error was encountered collecting statistics
733	from the NIC.
734	@retval EFI_UNSUPPORTED The NIC does not support collecting statistics
735	from the network interface.
736
737	**/
738	EFI_STATUS
739	EFIAPI
740	SnpUndi32Statistics (
741	IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
742	IN BOOLEAN Reset,
743	IN OUT UINTN *StatisticsSize, OPTIONAL
744	IN OUT EFI_NETWORK_STATISTICS *StatisticsTable OPTIONAL
745	);
746
747	/**
748	Converts a multicast IP address to a multicast HW MAC address.
749
750	This function converts a multicast IP address to a multicast HW MAC address
751	for all packet transactions. If the mapping is accepted, then EFI_SUCCESS will
752	be returned.
753
754	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
755	@param IPv6 Set to TRUE if the multicast IP address is IPv6 [RFC 2460].
756	Set to FALSE if the multicast IP address is IPv4 [RFC 791].
757	@param IP The multicast IP address that is to be converted to a multicast
758	HW MAC address.
759	@param MAC The multicast HW MAC address that is to be generated from IP.
760
761	@retval EFI_SUCCESS The multicast IP address was mapped to the
762	multicast HW MAC address.
763	@retval EFI_NOT_STARTED The Simple Network Protocol interface has not
764	been started by calling Start().
765	@retval EFI_INVALID_PARAMETER IP is NULL.
766	@retval EFI_INVALID_PARAMETER MAC is NULL.
767	@retval EFI_INVALID_PARAMETER IP does not point to a valid IPv4 or IPv6
768	multicast address.
769	@retval EFI_DEVICE_ERROR The Simple Network Protocol interface has not
770	been initialized by calling Initialize().
771	@retval EFI_UNSUPPORTED IPv6 is TRUE and the implementation does not
772	support IPv6 multicast to MAC address conversion.
773
774	**/
775	EFI_STATUS
776	EFIAPI
777	SnpUndi32McastIpToMac (
778	IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
779	IN BOOLEAN IPv6,
780	IN EFI_IP_ADDRESS *IP,
781	OUT EFI_MAC_ADDRESS *MAC
782	);
783
784	/**
785	Performs read and write operations on the NVRAM device attached to a network
786	interface.
787
788	This function performs read and write operations on the NVRAM device attached
789	to a network interface. If ReadWrite is TRUE, a read operation is performed.
790	If ReadWrite is FALSE, a write operation is performed. Offset specifies the
791	byte offset at which to start either operation. Offset must be a multiple of
792	NvRamAccessSize , and it must have a value between zero and NvRamSize.
793	BufferSize specifies the length of the read or write operation. BufferSize must
794	also be a multiple of NvRamAccessSize, and Offset + BufferSize must not exceed
795	NvRamSize.
796	If any of the above conditions is not met, then EFI_INVALID_PARAMETER will be
797	returned.
798	If all the conditions are met and the operation is "read," the NVRAM device
799	attached to the network interface will be read into Buffer and EFI_SUCCESS
800	will be returned. If this is a write operation, the contents of Buffer will be
801	used to update the contents of the NVRAM device attached to the network
802	interface and EFI_SUCCESS will be returned.
803
804	It does the basic checking on the input parameters and retrieves snp structure
805	and then calls the read_nvdata() call which does the actual reading
806
807	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
808	@param ReadWrite TRUE for read operations, FALSE for write operations.
809	@param Offset Byte offset in the NVRAM device at which to start the read or
810	write operation. This must be a multiple of NvRamAccessSize
811	and less than NvRamSize. (See EFI_SIMPLE_NETWORK_MODE)
812	@param BufferSize The number of bytes to read or write from the NVRAM device.
813	This must also be a multiple of NvramAccessSize.
814	@param Buffer A pointer to the data buffer.
815
816	@retval EFI_SUCCESS The NVRAM access was performed.
817	@retval EFI_NOT_STARTED The network interface has not been started.
818	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
819	* The This parameter is NULL
820	* The This parameter does not point to a valid
821	EFI_SIMPLE_NETWORK_PROTOCOL structure
822	* The Offset parameter is not a multiple of
823	EFI_SIMPLE_NETWORK_MODE.NvRamAccessSize
824	* The Offset parameter is not less than
825	EFI_SIMPLE_NETWORK_MODE.NvRamSize
826	* The BufferSize parameter is not a multiple of
827	EFI_SIMPLE_NETWORK_MODE.NvRamAccessSize
828	* The Buffer parameter is NULL
829	@retval EFI_DEVICE_ERROR The command could not be sent to the network
830	interface.
831	@retval EFI_UNSUPPORTED This function is not supported by the network
832	interface.
833
834	**/
835	EFI_STATUS
836	EFIAPI
837	SnpUndi32NvData (
838	IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
839	IN BOOLEAN ReadWrite,
840	IN UINTN Offset,
841	IN UINTN BufferSize,
842	IN OUT VOID *Buffer
843	);
844
845	/**
846	Reads the current interrupt status and recycled transmit buffer status from a
847	network interface.
848
849	This function gets the current interrupt and recycled transmit buffer status
850	from the network interface. The interrupt status is returned as a bit mask in
851	InterruptStatus. If InterruptStatus is NULL, the interrupt status will not be
852	read. If TxBuf is not NULL, a recycled transmit buffer address will be retrieved.
853	If a recycled transmit buffer address is returned in TxBuf, then the buffer has
854	been successfully transmitted, and the status for that buffer is cleared. If
855	the status of the network interface is successfully collected, EFI_SUCCESS
856	will be returned. If the driver has not been initialized, EFI_DEVICE_ERROR will
857	be returned.
858
859	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
860	@param InterruptStatus A pointer to the bit mask of the currently active
861	interrupts (see "Related Definitions"). If this is NULL,
862	the interrupt status will not be read from the device.
863	If this is not NULL, the interrupt status will be read
864	from the device. When the interrupt status is read, it
865	will also be cleared. Clearing the transmit interrupt does
866	not empty the recycled transmit buffer array.
867	@param TxBuf Recycled transmit buffer address. The network interface
868	will not transmit if its internal recycled transmit
869	buffer array is full. Reading the transmit buffer does
870	not clear the transmit interrupt. If this is NULL, then
871	the transmit buffer status will not be read. If there
872	are no transmit buffers to recycle and TxBuf is not NULL,
873	TxBuf will be set to NULL.
874
875	@retval EFI_SUCCESS The status of the network interface was retrieved.
876	@retval EFI_NOT_STARTED The network interface has not been started.
877	@retval EFI_INVALID_PARAMETER This parameter was NULL or did not point to a valid
878	EFI_SIMPLE_NETWORK_PROTOCOL structure.
879	@retval EFI_DEVICE_ERROR The command could not be sent to the network
880	interface.
881
882	**/
883	EFI_STATUS
884	EFIAPI
885	SnpUndi32GetStatus (
886	IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
887	OUT UINT32 *InterruptStatus, OPTIONAL
888	OUT VOID **TxBuf OPTIONAL
889	);
890
891	/**
892	Places a packet in the transmit queue of a network interface.
893
894	This function places the packet specified by Header and Buffer on the transmit
895	queue. If HeaderSize is nonzero and HeaderSize is not equal to
896	This->Mode->MediaHeaderSize, then EFI_INVALID_PARAMETER will be returned. If
897	BufferSize is less than This->Mode->MediaHeaderSize, then EFI_BUFFER_TOO_SMALL
898	will be returned. If Buffer is NULL, then EFI_INVALID_PARAMETER will be
899	returned. If HeaderSize is nonzero and DestAddr or Protocol is NULL, then
900	EFI_INVALID_PARAMETER will be returned. If the transmit engine of the network
901	interface is busy, then EFI_NOT_READY will be returned. If this packet can be
902	accepted by the transmit engine of the network interface, the packet contents
903	specified by Buffer will be placed on the transmit queue of the network
904	interface, and EFI_SUCCESS will be returned. GetStatus() can be used to
905	determine when the packet has actually been transmitted. The contents of the
906	Buffer must not be modified until the packet has actually been transmitted.
907	The Transmit() function performs nonblocking I/O. A caller who wants to perform
908	blocking I/O, should call Transmit(), and then GetStatus() until the
909	transmitted buffer shows up in the recycled transmit buffer.
910	If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
911
912	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
913	@param HeaderSize The size, in bytes, of the media header to be filled in by the
914	Transmit() function. If HeaderSize is nonzero, then it must
915	be equal to This->Mode->MediaHeaderSize and the DestAddr and
916	Protocol parameters must not be NULL.
917	@param BufferSize The size, in bytes, of the entire packet (media header and
918	data) to be transmitted through the network interface.
919	@param Buffer A pointer to the packet (media header followed by data) to be
920	transmitted. This parameter cannot be NULL. If HeaderSize is
921	zero, then the media header in Buffer must already be filled
922	in by the caller. If HeaderSize is nonzero, then the media
923	header will be filled in by the Transmit() function.
924	@param SrcAddr The source HW MAC address. If HeaderSize is zero, then this
925	parameter is ignored. If HeaderSize is nonzero and SrcAddr
926	is NULL, then This->Mode->CurrentAddress is used for the
927	source HW MAC address.
928	@param DestAddr The destination HW MAC address. If HeaderSize is zero, then
929	this parameter is ignored.
930	@param Protocol The type of header to build. If HeaderSize is zero, then this
931	parameter is ignored. See RFC 1700, section "Ether Types,"
932	for examples.
933
934	@retval EFI_SUCCESS The packet was placed on the transmit queue.
935	@retval EFI_NOT_STARTED The network interface has not been started.
936	@retval EFI_NOT_READY The network interface is too busy to accept this
937	transmit request.
938	@retval EFI_BUFFER_TOO_SMALL The BufferSize parameter is too small.
939	@retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported
940	value.
941	@retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
942	@retval EFI_UNSUPPORTED This function is not supported by the network interface.
943
944	**/
945	EFI_STATUS
946	EFIAPI
947	SnpUndi32Transmit (
948	IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
949	IN UINTN HeaderSize,
950	IN UINTN BufferSize,
951	IN VOID *Buffer,
952	IN EFI_MAC_ADDRESS *SrcAddr, OPTIONAL
953	IN EFI_MAC_ADDRESS *DestAddr, OPTIONAL
954	IN UINT16 *Protocol OPTIONAL
955	);
956
957	/**
958	Receives a packet from a network interface.
959
960	This function retrieves one packet from the receive queue of a network interface.
961	If there are no packets on the receive queue, then EFI_NOT_READY will be
962	returned. If there is a packet on the receive queue, and the size of the packet
963	is smaller than BufferSize, then the contents of the packet will be placed in
964	Buffer, and BufferSize will be updated with the actual size of the packet.
965	In addition, if SrcAddr, DestAddr, and Protocol are not NULL, then these values
966	will be extracted from the media header and returned. EFI_SUCCESS will be
967	returned if a packet was successfully received.
968	If BufferSize is smaller than the received packet, then the size of the receive
969	packet will be placed in BufferSize and EFI_BUFFER_TOO_SMALL will be returned.
970	If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
971
972	@param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
973	@param HeaderSize The size, in bytes, of the media header received on the network
974	interface. If this parameter is NULL, then the media header size
975	will not be returned.
976	@param BufferSize On entry, the size, in bytes, of Buffer. On exit, the size, in
977	bytes, of the packet that was received on the network interface.
978	@param Buffer A pointer to the data buffer to receive both the media
979	header and the data.
980	@param SrcAddr The source HW MAC address. If this parameter is NULL, the HW
981	MAC source address will not be extracted from the media header.
982	@param DestAddr The destination HW MAC address. If this parameter is NULL,
983	the HW MAC destination address will not be extracted from
984	the media header.
985	@param Protocol The media header type. If this parameter is NULL, then the
986	protocol will not be extracted from the media header. See
987	RFC 1700 section "Ether Types" for examples.
988
989	@retval EFI_SUCCESS The received data was stored in Buffer, and
990	BufferSize has been updated to the number of
991	bytes received.
992	@retval EFI_NOT_STARTED The network interface has not been started.
993	@retval EFI_NOT_READY No packets have been received on the network interface.
994	@retval EFI_BUFFER_TOO_SMALL BufferSize is too small for the received packets.
995	BufferSize has been updated to the required size.
996	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
997	* The This parameter is NULL
998	* The This parameter does not point to a valid
999	EFI_SIMPLE_NETWORK_PROTOCOL structure.
1000	* The BufferSize parameter is NULL
1001	* The Buffer parameter is NULL
1002	@retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
1003
1004	**/
1005	EFI_STATUS
1006	EFIAPI
1007	SnpUndi32Receive (
1008	IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
1009	OUT UINTN *HeaderSize OPTIONAL,
1010	IN OUT UINTN *BufferSize,
1011	OUT VOID *Buffer,
1012	OUT EFI_MAC_ADDRESS *SrcAddr OPTIONAL,
1013	OUT EFI_MAC_ADDRESS *DestAddr OPTIONAL,
1014	OUT UINT16 *Protocol OPTIONAL
1015	);
1016
1017	/**
1018	Notification call back function for WaitForPacket event.
1019
1020	@param Event EFI Event.
1021	@param SnpPtr Pointer to SNP_DRIVER structure.
1022
1023	**/
1024	VOID
1025	EFIAPI
1026	SnpWaitForPacketNotify (
1027	EFI_EVENT Event,
1028	VOID *SnpPtr
1029	);
1030
1031	#define SNP_MEM_PAGES(x) (((x) - 1) / 4096 + 1)
1032
1033
1034	#endif /* _SNP_H_ */

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

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/NetworkPkg/SnpDxe/Snp.h@ 89989

Download in other formats: