Snp.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: 44.8 KB

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

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

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/NetworkPkg/SnpDxe/Snp.h@ 80721

Download in other formats: