intnet.h@ 28828

Last change on this file since 28828 was 28800, checked in by vboxsync, 15 years ago
Automated rebranding to Oracle copyright/license strings via filemuncher
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 40.0 KB

Line
1	/** @file
2	* INTNET - Internal Networking. (DEV,++)
3	*/
4
5	/*
6	* Copyright (C) 2006-2010 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___VBox_intnet_h
27	#define ___VBox_intnet_h
28
29	#include <VBox/types.h>
30	#include <VBox/stam.h>
31	#include <VBox/sup.h>
32	#include <iprt/assert.h>
33	#include <iprt/asm.h>
34
35	RT_C_DECLS_BEGIN
36
37
38	/**
39	* Generic two-sided ring buffer.
40	*
41	* The deal is that there is exactly one writer and one reader.
42	* When offRead equals offWrite the buffer is empty. In the other
43	* extreme the writer will not use the last free byte in the buffer.
44	*/
45	typedef struct INTNETRINGBUF
46	{
47	/** The offset from this structure to the start of the buffer. */
48	uint32_t offStart;
49	/** The offset from this structure to the end of the buffer. (exclusive). */
50	uint32_t offEnd;
51	/** The current read offset. */
52	uint32_t volatile offReadX;
53	/** Alignment. */
54	uint32_t u32Align0;
55
56	/** The committed write offset. */
57	uint32_t volatile offWriteCom;
58	/** Writer internal current write offset.
59	* This is ahead of offWriteCom when buffer space is handed to a third party for
60	* data gathering. offWriteCom will be assigned this value by the writer then
61	* the frame is ready. */
62	uint32_t volatile offWriteInt;
63	/** The number of bytes written (not counting overflows). */
64	STAMCOUNTER cbStatWritten;
65	/** The number of frames written (not counting overflows). */
66	STAMCOUNTER cStatFrames;
67	/** The number of overflows. */
68	STAMCOUNTER cOverflows;
69	} INTNETRINGBUF;
70	AssertCompileSize(INTNETRINGBUF, 48);
71	/** Pointer to a ring buffer. */
72	typedef INTNETRINGBUF *PINTNETRINGBUF;
73
74	/** The alignment of a ring buffer. */
75	#define INTNETRINGBUF_ALIGNMENT sizeof(INTNETHDR)
76
77	/**
78	* Asserts the sanity of the specified INTNETRINGBUF structure.
79	*/
80	#define INTNETRINGBUF_ASSERT_SANITY(pRingBuf) \
81	do \
82	{ \
83	AssertPtr(pRingBuf); \
84	{ \
85	uint32_t const offWriteCom = (pRingBuf)->offWriteCom; \
86	uint32_t const offRead = (pRingBuf)->offReadX; \
87	uint32_t const offWriteInt = (pRingBuf)->offWriteInt; \
88	\
89	AssertMsg(offWriteCom == RT_ALIGN_32(offWriteCom, INTNETHDR_ALIGNMENT), ("%#x\n", offWriteCom)); \
90	AssertMsg(offWriteCom >= (pRingBuf)->offStart, ("%#x %#x\n", offWriteCom, (pRingBuf)->offStart)); \
91	AssertMsg(offWriteCom < (pRingBuf)->offEnd, ("%#x %#x\n", offWriteCom, (pRingBuf)->offEnd)); \
92	\
93	AssertMsg(offRead == RT_ALIGN_32(offRead, INTNETHDR_ALIGNMENT), ("%#x\n", offRead)); \
94	AssertMsg(offRead >= (pRingBuf)->offStart, ("%#x %#x\n", offRead, (pRingBuf)->offStart)); \
95	AssertMsg(offRead < (pRingBuf)->offEnd, ("%#x %#x\n", offRead, (pRingBuf)->offEnd)); \
96	\
97	AssertMsg(offWriteInt == RT_ALIGN_32(offWriteInt, INTNETHDR_ALIGNMENT), ("%#x\n", offWriteInt)); \
98	AssertMsg(offWriteInt >= (pRingBuf)->offStart, ("%#x %#x\n", offWriteInt, (pRingBuf)->offStart)); \
99	AssertMsg(offWriteInt < (pRingBuf)->offEnd, ("%#x %#x\n", offWriteInt, (pRingBuf)->offEnd)); \
100	AssertMsg( offRead <= offWriteCom \
101	? offWriteCom <= offWriteInt \|\| offWriteInt < offRead \
102	: offWriteCom <= offWriteInt, \
103	("W=%#x W'=%#x R=%#x\n", offWriteCom, offWriteInt, offRead)); \
104	} \
105	} while (0)
106
107
108
109	/**
110	* A interface buffer.
111	*/
112	typedef struct INTNETBUF
113	{
114	/** Magic number (INTNETBUF_MAGIC). */
115	uint32_t u32Magic;
116	/** The size of the entire buffer. */
117	uint32_t cbBuf;
118	/** The size of the send area. */
119	uint32_t cbSend;
120	/** The size of the receive area. */
121	uint32_t cbRecv;
122	/** The receive buffer. */
123	INTNETRINGBUF Recv;
124	/** The send buffer. */
125	INTNETRINGBUF Send;
126	/** Number of times yields help solve an overflow. */
127	STAMCOUNTER cStatYieldsOk;
128	/** Number of times yields didn't help solve an overflow. */
129	STAMCOUNTER cStatYieldsNok;
130	/** Number of lost packets due to overflows. */
131	STAMCOUNTER cStatLost;
132	/** Number of bad frames (both rings). */
133	STAMCOUNTER cStatBadFrames;
134	/** Reserved for future use. */
135	STAMCOUNTER aStatReserved[2];
136	} INTNETBUF;
137	AssertCompileSize(INTNETBUF, 160);
138	AssertCompileMemberOffset(INTNETBUF, Recv, 16);
139	AssertCompileMemberOffset(INTNETBUF, Send, 64);
140
141	/** Pointer to an interface buffer. */
142	typedef INTNETBUF *PINTNETBUF;
143	/** Pointer to a const interface buffer. */
144	typedef INTNETBUF const *PCINTNETBUF;
145
146	/** Magic number for INTNETBUF::u32Magic (Sir William Gerald Golding). */
147	#define INTNETBUF_MAGIC UINT32_C(0x19110919)
148
149	/**
150	* Asserts the sanity of the specified INTNETBUF structure.
151	*/
152	#define INTNETBUF_ASSERT_SANITY(pBuf) \
153	do \
154	{ \
155	AssertPtr(pBuf); \
156	Assert((pBuf)->u32Magic == INTNETBUF_MAGIC); \
157	{ \
158	uint32_t const offRecvStart = (pBuf)->Recv.offStart + RT_OFFSETOF(INTNETBUF, Recv); \
159	uint32_t const offRecvEnd = (pBuf)->Recv.offStart + RT_OFFSETOF(INTNETBUF, Recv); \
160	uint32_t const offSendStart = (pBuf)->Send.offStart + RT_OFFSETOF(INTNETBUF, Send); \
161	uint32_t const offSendEnd = (pBuf)->Send.offStart + RT_OFFSETOF(INTNETBUF, Send); \
162	\
163	Assert(offRecvEnd > offRecvStart); \
164	Assert(offRecvEnd - offRecvStart == (pBuf)->cbRecv); \
165	Assert(offRecvStart == sizeof(INTNETBUF)); \
166	\
167	Assert(offSendEnd > offSendStart); \
168	Assert(offSendEnd - offSendStart == (pBuf)->cbSend); \
169	Assert(pffSendEnd <= (pBuf)->cbBuf); \
170	\
171	Assert(offSendStart == offRecvEnd); \
172	} \
173	} while (0)
174
175
176	/** Internal networking interface handle. */
177	typedef uint32_t INTNETIFHANDLE;
178	/** Pointer to an internal networking interface handle. */
179	typedef INTNETIFHANDLE *PINTNETIFHANDLE;
180
181	/** Or mask to obscure the handle index. */
182	#define INTNET_HANDLE_MAGIC 0x88880000
183	/** Mask to extract the handle index. */
184	#define INTNET_HANDLE_INDEX_MASK 0xffff
185	/** The maximum number of handles (exclusive) */
186	#define INTNET_HANDLE_MAX 0xffff
187	/** Invalid handle. */
188	#define INTNET_HANDLE_INVALID (0)
189
190
191	/**
192	* The frame header.
193	*
194	* The header is intentionally 8 bytes long. It will always
195	* start at an 8 byte aligned address. Assuming that the buffer
196	* size is a multiple of 8 bytes, that means that we can guarantee
197	* that the entire header is contiguous in both virtual and physical
198	* memory.
199	*/
200	typedef struct INTNETHDR
201	{
202	/** Header type. This is currently serving as a magic, it
203	* can be extended later to encode special command frames and stuff. */
204	uint16_t u16Type;
205	/** The size of the frame. */
206	uint16_t cbFrame;
207	/** The offset from the start of this header to where the actual frame starts.
208	* This is used to keep the frame it self continguous in virtual memory and
209	* thereby both simplify access as well as the descriptor. */
210	int32_t offFrame;
211	} INTNETHDR;
212	AssertCompileSize(INTNETHDR, 8);
213	AssertCompileSizeAlignment(INTNETBUF, sizeof(INTNETHDR));
214	/** Pointer to a frame header.*/
215	typedef INTNETHDR *PINTNETHDR;
216	/** Pointer to a const frame header.*/
217	typedef INTNETHDR const *PCINTNETHDR;
218
219	/** The alignment of a frame header. */
220	#define INTNETHDR_ALIGNMENT sizeof(INTNETHDR)
221	AssertCompile(sizeof(INTNETHDR) == INTNETHDR_ALIGNMENT);
222	AssertCompile(INTNETHDR_ALIGNMENT <= INTNETRINGBUF_ALIGNMENT);
223
224	/** @name Frame types (INTNETHDR::u16Type).
225	* @{ */
226	/** Normal frames. */
227	#define INTNETHDR_TYPE_FRAME 0x2442
228	/** Padding frames. */
229	#define INTNETHDR_TYPE_PADDING 0x3553
230	/** Generic segment offload frames.
231	* The frame starts with a PDMNETWORKGSO structure which is followed by the
232	* header template and data. */
233	#define INTNETHDR_TYPE_GSO 0x4664
234	AssertCompileSize(PDMNETWORKGSO, 8);
235	/** @} */
236
237	/**
238	* Asserts the sanity of the specified INTNETHDR.
239	*/
240	#define INTNETHDR_ASSERT_SANITY(pHdr, pRingBuf) \
241	do \
242	{ \
243	AssertPtr(pHdr); \
244	Assert(RT_ALIGN_PT(pHdr, INTNETHDR_ALIGNMENT, INTNETHDR *) == pHdr); \
245	Assert( (pHdr)->u16Type == INTNETHDR_TYPE_FRAME \
246	\|\| (pHdr)->u16Type == INTNETHDR_TYPE_GSO \
247	\|\| (pHdr)->u16Type == INTNETHDR_TYPE_PADDING); \
248	{ \
249	uintptr_t const offHdr = (uintptr_t)pHdr - (uintptr_t)pRingBuf; \
250	uintptr_t const offFrame = offHdr + (pHdr)->offFrame; \
251	\
252	Assert(offHdr >= (pRingBuf)->offStart); \
253	Assert(offHdr < (pRingBuf)->offEnd); \
254	\
255	/* could do more thorough work here... later, perhaps. */ \
256	Assert(offFrame >= (pRingBuf)->offStart); \
257	Assert(offFrame < (pRingBuf)->offEnd); \
258	} \
259	} while (0)
260
261
262	/**
263	* Scatter / Gather segment (internal networking).
264	*/
265	typedef struct INTNETSEG
266	{
267	/** The physical address. NIL_RTHCPHYS is not set. */
268	RTHCPHYS Phys;
269	/** Pointer to the segment data. */
270	void *pv;
271	/** The segment size. */
272	uint32_t cb;
273	} INTNETSEG;
274	/** Pointer to a internal networking frame segment. */
275	typedef INTNETSEG *PINTNETSEG;
276	/** Pointer to a internal networking frame segment. */
277	typedef INTNETSEG const *PCINTNETSEG;
278
279
280	/**
281	* Scatter / Gather list (internal networking).
282	*
283	* This is used when communicating with the trunk port.
284	*/
285	typedef struct INTNETSG
286	{
287	/** Owner data, don't touch! */
288	void *pvOwnerData;
289	/** User data. */
290	void *pvUserData;
291	/** User data 2 in case anyone needs it. */
292	void *pvUserData2;
293	/** GSO context information, set the type to invalid if not relevant. */
294	PDMNETWORKGSO GsoCtx;
295	/** The total length of the scatter gather list. */
296	uint32_t cbTotal;
297	/** The number of users (references).
298	* This is used by the SGRelease code to decide when it can be freed. */
299	uint16_t volatile cUsers;
300	/** Flags, see INTNETSG_FLAGS_* */
301	uint16_t volatile fFlags;
302	#if ARCH_BITS == 64
303	/** Alignment padding. */
304	uint16_t uPadding;
305	#endif
306	/** The number of segments allocated. */
307	uint16_t cSegsAlloc;
308	/** The number of segments actually used. */
309	uint16_t cSegsUsed;
310	/** Variable sized list of segments. */
311	INTNETSEG aSegs[1];
312	} INTNETSG;
313	AssertCompileSizeAlignment(INTNETSG, 8);
314	/** Pointer to a scatter / gather list. */
315	typedef INTNETSG *PINTNETSG;
316	/** Pointer to a const scatter / gather list. */
317	typedef INTNETSG const *PCINTNETSG;
318
319	/** @name INTNETSG::fFlags definitions.
320	* @{ */
321	/** Set if the SG is free. */
322	#define INTNETSG_FLAGS_FREE RT_BIT_32(1)
323	/** Set if the SG is a temporary one that will become invalid upon return.
324	* Try to finish using it before returning, and if that's not possible copy
325	* to other buffers.
326	* When not set, the callee should always free the SG.
327	* Attempts to free it made by the callee will be quietly ignored. */
328	#define INTNETSG_FLAGS_TEMP RT_BIT_32(2)
329	/** ARP packet, IPv4 + MAC.
330	* @internal */
331	#define INTNETSG_FLAGS_ARP_IPV4 RT_BIT_32(3)
332	/** Copied to the temporary buffer.
333	* @internal */
334	#define INTNETSG_FLAGS_PKT_CP_IN_TMP RT_BIT_32(4)
335	/** @} */
336
337
338	/** @name Direction (frame source or destination)
339	* @{ */
340	/** To/From the wire. */
341	#define INTNETTRUNKDIR_WIRE RT_BIT_32(0)
342	/** To/From the host. */
343	#define INTNETTRUNKDIR_HOST RT_BIT_32(1)
344	/** Mask of valid bits. */
345	#define INTNETTRUNKDIR_VALID_MASK UINT32_C(3)
346	/** @} */
347
348	/**
349	* Switch decisions returned by INTNETTRUNKSWPORT::pfnPreRecv.
350	*/
351	typedef enum INTNETSWDECISION
352	{
353	/** The usual invalid zero value. */
354	INTNETSWDECISION_INVALID = 0,
355	/** Everywhere. */
356	INTNETSWDECISION_BROADCAST,
357	/** Only to the internal network. */
358	INTNETSWDECISION_INTNET,
359	/** Only for the trunk (host/wire). */
360	INTNETSWDECISION_TRUNK,
361	/** Used internally to indicate that the packet cannot be handled in the
362	* current context. */
363	INTNETSWDECISION_BAD_CONTEXT,
364	/** Used internally to indicate that the packet should be dropped. */
365	INTNETSWDECISION_DROP,
366	/** The usual 32-bit type expansion. */
367	INTNETSWDECISION_32BIT_HACK = 0x7fffffff
368	} INTNETSWDECISION;
369
370
371	/** Pointer to the switch side of a trunk port. */
372	typedef struct INTNETTRUNKSWPORT *PINTNETTRUNKSWPORT;
373	/**
374	* This is the port on the internal network 'switch', i.e.
375	* what the driver is connected to.
376	*
377	* This is only used for the in-kernel trunk connections.
378	*/
379	typedef struct INTNETTRUNKSWPORT
380	{
381	/** Structure version number. (INTNETTRUNKSWPORT_VERSION) */
382	uint32_t u32Version;
383
384	/**
385	* Examine the packet and figure out where it is going.
386	*
387	* This method is for making packet switching decisions in contexts where
388	* pfnRecv cannot be called or is no longer applicable. This method can be
389	* called from any context.
390	*
391	* @returns INTNETSWDECISION_BROADCAST, INTNETSWDECISION_INTNET or
392	* INTNETSWDECISION_TRUNK. The source is excluded from broadcast &
393	* trunk, of course.
394	*
395	* @param pSwitchPort Pointer to this structure.
396	* @param pvHdrs Pointer to the packet headers.
397	* @param cbHdrs Size of the packet headers. This must be at least 6
398	* bytes (the destination MAC address), but should if
399	* possibly also include any VLAN tag and network layer
400	* header (wireless mac address sharing).
401	* @param fSrc Where this frame comes from. Only one bit should be
402	* set!
403	*
404	* @remarks Will only grab the switch table spinlock (interrupt safe).
405	*/
406	DECLR0CALLBACKMEMBER(INTNETSWDECISION, pfnPreRecv,(PINTNETTRUNKSWPORT pSwitchPort,
407	void const *pvHdrs, size_t cbHdrs, uint32_t fSrc));
408
409	/**
410	* Incoming frame.
411	*
412	* The frame may be modified when the trunk port on the switch is set to share
413	* the mac address of the host when hitting the wire. Currently rames containing
414	* ARP packets are subject to this, later other protocols like NDP/ICMPv6 may
415	* need editing as well when operating in this mode.
416	*
417	* @returns true if we've handled it and it should be dropped.
418	* false if it should hit the wire/host.
419	*
420	* @param pSwitchPort Pointer to this structure.
421	* @param pSG The (scatter /) gather structure for the frame.
422	* This will only be use during the call, so a temporary one can
423	* be used. The Phys member will not be used.
424	* @param fSrc Where this frame comes from. Only one bit should be set!
425	*
426	* @remarks Will grab the network semaphore.
427	*
428	* @remarks NAT and TAP will use this interface.
429	*
430	* @todo Do any of the host require notification before frame modifications? If so,
431	* we'll add a callback to INTNETTRUNKIFPORT for this (pfnSGModifying) and
432	* a SG flag.
433	*/
434	DECLR0CALLBACKMEMBER(bool, pfnRecv,(PINTNETTRUNKSWPORT pSwitchPort, PINTNETSG pSG, uint32_t fSrc));
435
436	/**
437	* Retain a SG.
438	*
439	* @param pSwitchPort Pointer to this structure.
440	* @param pSG Pointer to the (scatter /) gather structure.
441	*
442	* @remarks Will not grab any locks.
443	*/
444	DECLR0CALLBACKMEMBER(void, pfnSGRetain,(PINTNETTRUNKSWPORT pSwitchPort, PINTNETSG pSG));
445
446	/**
447	* Release a SG.
448	*
449	* This is called by the pfnXmit code when done with a SG. This may safe
450	* be done in an asynchronous manner.
451	*
452	* @param pSwitchPort Pointer to this structure.
453	* @param pSG Pointer to the (scatter /) gather structure.
454	*
455	* @remarks Will grab the network semaphore.
456	*/
457	DECLR0CALLBACKMEMBER(void, pfnSGRelease,(PINTNETTRUNKSWPORT pSwitchPort, PINTNETSG pSG));
458
459	/**
460	* Selects whether outgoing SGs should have their physical address set.
461	*
462	* By enabling physical addresses in the scatter / gather segments it should
463	* be possible to save some unnecessary address translation and memory locking
464	* in the network stack. (Internal networking knows the physical address for
465	* all the INTNETBUF data and that it's locked memory.) There is a negative
466	* side effects though, frames that crosses page boundraries will require
467	* multiple scather / gather segments.
468	*
469	* @returns The old setting.
470	*
471	* @param pSwitchPort Pointer to this structure.
472	* @param fEnable Whether to enable or disable it.
473	*
474	* @remarks Will grab the network semaphore.
475	*/
476	DECLR0CALLBACKMEMBER(bool, pfnSetSGPhys,(PINTNETTRUNKSWPORT pSwitchPort, bool fEnable));
477
478	/**
479	* Reports the MAC address of the trunk.
480	*
481	* This is supposed to be called when creating, connection or reconnecting the
482	* trunk and when the MAC address is changed by the system admin.
483	*
484	* @param pSwitchPort Pointer to this structure.
485	* @param pMacAddr The MAC address.
486	*
487	* @remarks May take a spinlock or two.
488	*/
489	DECLR0CALLBACKMEMBER(void, pfnReportMacAddress,(PINTNETTRUNKSWPORT pSwitchPort, PCRTMAC pMacAddr));
490
491	/**
492	* Reports the promicuousness of the interface.
493	*
494	* This is supposed to be called when creating, connection or reconnecting the
495	* trunk and when the mode is changed by the system admin.
496	*
497	* @param pSwitchPort Pointer to this structure.
498	* @param fPromiscuous True if the host operates the interface in
499	* promiscuous mode, false if not.
500	*
501	* @remarks May take a spinlock or two.
502	*/
503	DECLR0CALLBACKMEMBER(void, pfnReportPromiscuousMode,(PINTNETTRUNKSWPORT pSwitchPort, bool fPromiscuous));
504
505	/**
506	* Reports the GSO capabilities of the host, wire or both.
507	*
508	* This is supposed to be used only when creating, connecting or reconnecting
509	* the trunk. It is assumed that the GSO capabilities are kind of static the
510	* rest of the time.
511	*
512	* @param pSwitchPort Pointer to this structure.
513	* @param fGsoCapabilities The GSO capability bit mask. The bits
514	* corresponds to the GSO type with the same value.
515	* @param fDst The destination mask (INTNETTRUNKDIR_XXX).
516	*
517	* @remarks Does not take any locks.
518	*/
519	DECLR0CALLBACKMEMBER(void, pfnReportGsoCapabilities,(PINTNETTRUNKSWPORT pSwitchPort, uint32_t fGsoCapabilities, uint32_t fDst));
520
521	/**
522	* Reports the no-preemption-xmit capabilities of the host and wire.
523	*
524	* This is supposed to be used only when creating, connecting or reconnecting
525	* the trunk. It is assumed that the GSO capabilities are kind of static the
526	* rest of the time.
527	*
528	* @param pSwitchPort Pointer to this structure.
529	* @param fNoPreemptDsts The destinations (INTNETTRUNKDIR_XXX) which it
530	* is safe to transmit to with preemption disabled.
531	* @param fDst The destination mask (INTNETTRUNKDIR_XXX).
532	*
533	* @remarks Does not take any locks.
534	*/
535	DECLR0CALLBACKMEMBER(void, pfnReportNoPreemptDsts,(PINTNETTRUNKSWPORT pSwitchPort, uint32_t fNoPreemptDsts));
536
537	/** Structure version number. (INTNETTRUNKSWPORT_VERSION) */
538	uint32_t u32VersionEnd;
539	} INTNETTRUNKSWPORT;
540
541	/** Version number for the INTNETTRUNKIFPORT::u32Version and INTNETTRUNKIFPORT::u32VersionEnd fields. */
542	#define INTNETTRUNKSWPORT_VERSION UINT32_C(0xA2CDf001)
543
544
545	/** Pointer to the interface side of a trunk port. */
546	typedef struct INTNETTRUNKIFPORT *PINTNETTRUNKIFPORT;
547	/**
548	* This is the port on the trunk interface, i.e. the driver
549	* side which the internal network is connected to.
550	*
551	* This is only used for the in-kernel trunk connections.
552	*
553	* @remarks The internal network side is responsible for serializing all calls
554	* to this interface. This is (assumed) to be implemented using a lock
555	* that is only ever taken before a call to this interface. The lock
556	* is referred to as the out-bound trunk port lock.
557	*/
558	typedef struct INTNETTRUNKIFPORT
559	{
560	/** Structure version number. (INTNETTRUNKIFPORT_VERSION) */
561	uint32_t u32Version;
562
563	/**
564	* Retain the object.
565	*
566	* It will normally be called while owning the internal network semaphore.
567	*
568	* @param pIfPort Pointer to this structure.
569	*
570	* @remarks The caller may own any locks or none at all, we don't care.
571	*/
572	DECLR0CALLBACKMEMBER(void, pfnRetain,(PINTNETTRUNKIFPORT pIfPort));
573
574	/**
575	* Releases the object.
576	*
577	* This must be called for every pfnRetain call.
578	*
579	*
580	* @param pIfPort Pointer to this structure.
581	*
582	* @remarks Only the out-bound trunk port lock, unless the caller is certain the
583	* call is not going to cause destruction (wont happen).
584	*/
585	DECLR0CALLBACKMEMBER(void, pfnRelease,(PINTNETTRUNKIFPORT pIfPort));
586
587	/**
588	* Disconnect from the switch and release the object.
589	*
590	* The is the counter action of the
591	* INTNETTRUNKNETFLTFACTORY::pfnCreateAndConnect method.
592	*
593	* @param pIfPort Pointer to this structure.
594	*
595	* @remarks Called holding the out-bound trunk port lock.
596	*/
597	DECLR0CALLBACKMEMBER(void, pfnDisconnectAndRelease,(PINTNETTRUNKIFPORT pIfPort));
598
599	/**
600	* Changes the active state of the interface.
601	*
602	* The interface is created in the suspended (non-active) state and then activated
603	* when the VM/network is started. It may be suspended and re-activated later
604	* for various reasons. It will finally be suspended again before disconnecting
605	* the interface from the internal network, however, this might be done immediately
606	* before disconnecting and may leave an incoming frame waiting on the internal network
607	* semaphore. So, after the final suspend a pfnWaitForIdle is always called to make sure
608	* the interface is idle before pfnDisconnectAndRelease is called.
609	*
610	* A typical operation to performed by this method is to enable/disable promiscuous
611	* mode on the host network interface. (This is the reason we cannot call this when
612	* owning any semaphores.)
613	*
614	* @returns The previous state.
615	*
616	* @param pIfPort Pointer to this structure.
617	* @param fActive True if the new state is 'active', false if the new state is 'suspended'.
618	*
619	* @remarks Called holding the out-bound trunk port lock.
620	*/
621	DECLR0CALLBACKMEMBER(bool, pfnSetActive,(PINTNETTRUNKIFPORT pIfPort, bool fActive));
622
623	/**
624	* Waits for the interface to become idle.
625	*
626	* This method must be called before disconnecting and releasing the
627	* object in order to prevent racing incoming/outgoing frames and device
628	* enabling/disabling.
629	*
630	* @returns IPRT status code (see RTSemEventWait).
631	* @param pIfPort Pointer to this structure.
632	* @param cMillies The number of milliseconds to wait. 0 means
633	* no waiting at all. Use RT_INDEFINITE_WAIT for
634	* an indefinite wait.
635	*
636	* @remarks Called holding the out-bound trunk port lock.
637	*/
638	DECLR0CALLBACKMEMBER(int, pfnWaitForIdle,(PINTNETTRUNKIFPORT pIfPort, uint32_t cMillies));
639
640	/**
641	* Gets the MAC address of the host network interface that we're attached to.
642	*
643	* @param pIfPort Pointer to this structure.
644	* @param pMac Where to store the host MAC address.
645	*
646	* @remarks Called while owning the network and the out-bound trunk port semaphores.
647	*/
648	DECLR0CALLBACKMEMBER(void, pfnGetMacAddress,(PINTNETTRUNKIFPORT pIfPort, PRTMAC pMac));
649
650	/**
651	* Tests whether the host is operating the interface is promiscuous mode.
652	*
653	* The default behavior of the internal networking 'switch' is to 'autodetect'
654	* promiscuous mode on the trunk port, which is when this method is used.
655	* For security reasons this default may of course be overridden so that the
656	* host cannot sniff at what's going on.
657	*
658	* Note that this differs from operating the trunk port on the switch in
659	* 'promiscuous' mode, because that relates to the bits going to the wire.
660	*
661	* @returns true / false.
662	*
663	* @param pIfPort Pointer to this structure.
664	*
665	* @remarks Usuaully called while owning the network and the out-bound trunk
666	* port semaphores.
667	*/
668	DECLR0CALLBACKMEMBER(bool, pfnIsPromiscuous,(PINTNETTRUNKIFPORT pIfPort));
669
670	/**
671	* Transmit a frame.
672	*
673	* @return VBox status code. Error generally means we'll drop the frame.
674	* @param pIfPort Pointer to this structure.
675	* @param pSG Pointer to the (scatter /) gather structure for the frame.
676	* This may or may not be a temporary buffer. If it's temporary
677	* the transmit operation(s) then it's required to make a copy
678	* of the frame unless it can be transmitted synchronously.
679	* @param fDst The destination mask. At least one bit will be set.
680	*
681	* @remarks Called holding the out-bound trunk port lock.
682	*
683	* @remarks TAP and NAT will use this interface for all their traffic, see pfnIsHostMac.
684	*
685	* @todo
686	*/
687	DECLR0CALLBACKMEMBER(int, pfnXmit,(PINTNETTRUNKIFPORT pIfPort, PINTNETSG pSG, uint32_t fDst));
688
689	/** Structure version number. (INTNETTRUNKIFPORT_VERSION) */
690	uint32_t u32VersionEnd;
691	} INTNETTRUNKIFPORT;
692
693	/** Version number for the INTNETTRUNKIFPORT::u32Version and INTNETTRUNKIFPORT::u32VersionEnd fields. */
694	#define INTNETTRUNKIFPORT_VERSION UINT32_C(0xA2CDe001)
695
696
697	/**
698	* The component factory interface for create a network
699	* interface filter (like VBoxNetFlt).
700	*/
701	typedef struct INTNETTRUNKFACTORY
702	{
703	/**
704	* Release this factory.
705	*
706	* SUPR0ComponentQueryFactory (SUPDRVFACTORY::pfnQueryFactoryInterface to be precise)
707	* will retain a reference to the factory and the caller has to call this method to
708	* release it once the pfnCreateAndConnect call(s) has been done.
709	*
710	* @param pIfFactory Pointer to this structure.
711	*/
712	DECLR0CALLBACKMEMBER(void, pfnRelease,(struct INTNETTRUNKFACTORY *pIfFactory));
713
714	/**
715	* Create an instance for the specfied host interface and connects it
716	* to the internal network trunk port.
717	*
718	* The initial interface active state is false (suspended).
719	*
720	*
721	* @returns VBox status code.
722	* @retval VINF_SUCCESS and *ppIfPort set on success.
723	* @retval VERR_INTNET_FLT_IF_NOT_FOUND if the interface was not found.
724	* @retval VERR_INTNET_FLT_IF_BUSY if the interface is already connected.
725	* @retval VERR_INTNET_FLT_IF_FAILED if it failed for some other reason.
726	*
727	* @param pIfFactory Pointer to this structure.
728	* @param pszName The interface name (OS specific).
729	* @param pSwitchPort Pointer to the port interface on the switch that
730	* this interface is being connected to.
731	* @param fFlags Creation flags, see below.
732	* @param ppIfPort Where to store the pointer to the interface port
733	* on success.
734	*
735	* @remarks Called while owning the network and the out-bound trunk semaphores.
736	*/
737	DECLR0CALLBACKMEMBER(int, pfnCreateAndConnect,(struct INTNETTRUNKFACTORY pIfFactory, const char pszName,
738	PINTNETTRUNKSWPORT pSwitchPort, uint32_t fFlags,
739	PINTNETTRUNKIFPORT *ppIfPort));
740	} INTNETTRUNKFACTORY;
741	/** Pointer to the trunk factory. */
742	typedef INTNETTRUNKFACTORY *PINTNETTRUNKFACTORY;
743
744	/** The UUID for the (current) trunk factory. (case sensitive) */
745	#define INTNETTRUNKFACTORY_UUID_STR "5d347cb7-98e3-411f-916a-67c4becae09b"
746
747	/** @name INTNETTRUNKFACTORY::pfnCreateAndConnect flags.
748	* @{ */
749	/** Don't put the filtered interface in promiscuous mode.
750	* This is used for wireless interface since these can misbehave if
751	* we try to put them in promiscuous mode. (Wireless interfaces are
752	* normally bridged on level 3 instead of level 2.) */
753	#define INTNETTRUNKFACTORY_FLAG_NO_PROMISC RT_BIT_32(0)
754	/** @} */
755
756
757	/**
758	* The trunk connection type.
759	*
760	* Used by IntNetR0Open and assoicated interfaces.
761	*/
762	typedef enum INTNETTRUNKTYPE
763	{
764	/** Invalid trunk type. */
765	kIntNetTrunkType_Invalid = 0,
766	/** No trunk connection. */
767	kIntNetTrunkType_None,
768	/** We don't care which kind of trunk connection if the network exists,
769	* if it doesn't exist create it without a connection. */
770	kIntNetTrunkType_WhateverNone,
771	/** VirtualBox host network interface filter driver.
772	* The trunk name is the name of the host network interface. */
773	kIntNetTrunkType_NetFlt,
774	/** VirtualBox adapter host driver. */
775	kIntNetTrunkType_NetAdp,
776	/** Nat service (ring-0). */
777	kIntNetTrunkType_SrvNat,
778	/** The end of valid types. */
779	kIntNetTrunkType_End,
780	/** The usual 32-bit hack. */
781	kIntNetTrunkType_32bitHack = 0x7fffffff
782	} INTNETTRUNKTYPE;
783
784	/** @name IntNetR0Open flags.
785	* @{ */
786	/** Share the MAC address with the host when sending something to the wire via the trunk.
787	* This is typically used when the trunk is a NetFlt for a wireless interface. */
788	#define INTNET_OPEN_FLAGS_SHARED_MAC_ON_WIRE RT_BIT_32(0)
789	/** Whether new participants should be subjected to access check or not. */
790	#define INTNET_OPEN_FLAGS_PUBLIC RT_BIT_32(1)
791	/** Ignore any requests for promiscuous mode. */
792	#define INTNET_OPEN_FLAGS_IGNORE_PROMISC RT_BIT_32(2)
793	/** Ignore any requests for promiscuous mode, quietly applied/ignored on open. */
794	#define INTNET_OPEN_FLAGS_QUIETLY_IGNORE_PROMISC RT_BIT_32(3)
795	/** Ignore any requests for promiscuous mode on the trunk wire connection. */
796	#define INTNET_OPEN_FLAGS_IGNORE_PROMISC_TRUNK_WIRE RT_BIT_32(4)
797	/** Ignore any requests for promiscuous mode on the trunk wire connection, quietly applied/ignored on open. */
798	#define INTNET_OPEN_FLAGS_QUIETLY_IGNORE_PROMISC_TRUNK_WIRE RT_BIT_32(5)
799	/** Ignore any requests for promiscuous mode on the trunk host connection. */
800	#define INTNET_OPEN_FLAGS_IGNORE_PROMISC_TRUNK_HOST RT_BIT_32(6)
801	/** Ignore any requests for promiscuous mode on the trunk host connection, quietly applied/ignored on open. */
802	#define INTNET_OPEN_FLAGS_QUIETLY_IGNORE_PROMISC_TRUNK_HOST RT_BIT_32(7)
803	/** The mask of flags which causes flag incompatibilities. */
804	#define INTNET_OPEN_FLAGS_COMPATIBILITY_XOR_MASK (RT_BIT_32(0) \| RT_BIT_32(1) \| RT_BIT_32(2) \| RT_BIT_32(4) \| RT_BIT_32(6))
805	/** The mask of flags is always ORed in, even on open. (the quiet stuff) */
806	#define INTNET_OPEN_FLAGS_SECURITY_OR_MASK (RT_BIT_32(3) \| RT_BIT_32(5) \| RT_BIT_32(7))
807	/** The mask of valid flags. */
808	#define INTNET_OPEN_FLAGS_MASK UINT32_C(0x000000ff)
809	/** @} */
810
811	/** The maximum length of a network name. */
812	#define INTNET_MAX_NETWORK_NAME 128
813
814	/** The maximum length of a trunk name. */
815	#define INTNET_MAX_TRUNK_NAME 64
816
817
818	/**
819	* Request buffer for IntNetR0OpenReq / VMMR0_DO_INTNET_OPEN.
820	* @see IntNetR0Open.
821	*/
822	typedef struct INTNETOPENREQ
823	{
824	/** The request header. */
825	SUPVMMR0REQHDR Hdr;
826	/** Alternative to passing the taking the session from the VM handle.
827	* Either use this member or use the VM handle, don't do both. */
828	PSUPDRVSESSION pSession;
829	/** The network name. (input) */
830	char szNetwork[INTNET_MAX_NETWORK_NAME];
831	/** What to connect to the trunk port. (input)
832	* This is specific to the trunk type below. */
833	char szTrunk[INTNET_MAX_TRUNK_NAME];
834	/** The type of trunk link (NAT, Filter, TAP, etc). (input) */
835	INTNETTRUNKTYPE enmTrunkType;
836	/** Flags, see INTNET_OPEN_FLAGS_. (input) /
837	uint32_t fFlags;
838	/** The size of the send buffer. (input) */
839	uint32_t cbSend;
840	/** The size of the receive buffer. (input) */
841	uint32_t cbRecv;
842	/** The handle to the network interface. (output) */
843	INTNETIFHANDLE hIf;
844	} INTNETOPENREQ;
845	/** Pointer to an IntNetR0OpenReq / VMMR0_DO_INTNET_OPEN request buffer. */
846	typedef INTNETOPENREQ *PINTNETOPENREQ;
847
848	INTNETR0DECL(int) IntNetR0OpenReq(PSUPDRVSESSION pSession, PINTNETOPENREQ pReq);
849
850
851	/**
852	* Request buffer for IntNetR0IfCloseReq / VMMR0_DO_INTNET_IF_CLOSE.
853	* @see IntNetR0IfClose.
854	*/
855	typedef struct INTNETIFCLOSEREQ
856	{
857	/** The request header. */
858	SUPVMMR0REQHDR Hdr;
859	/** Alternative to passing the taking the session from the VM handle.
860	* Either use this member or use the VM handle, don't do both. */
861	PSUPDRVSESSION pSession;
862	/** The handle to the network interface. */
863	INTNETIFHANDLE hIf;
864	} INTNETIFCLOSEREQ;
865	/** Pointer to an IntNetR0IfCloseReq / VMMR0_DO_INTNET_IF_CLOSE request
866	* buffer. */
867	typedef INTNETIFCLOSEREQ *PINTNETIFCLOSEREQ;
868
869	INTNETR0DECL(int) IntNetR0IfCloseReq(PSUPDRVSESSION pSession, PINTNETIFCLOSEREQ pReq);
870
871
872	/**
873	* Request buffer for IntNetR0IfGetRing3BufferReq /
874	* VMMR0_DO_INTNET_IF_GET_BUFFER_PTRS.
875	* @see IntNetR0IfGetRing3Buffer.
876	*/
877	typedef struct INTNETIFGETBUFFERPTRSREQ
878	{
879	/** The request header. */
880	SUPVMMR0REQHDR Hdr;
881	/** Alternative to passing the taking the session from the VM handle.
882	* Either use this member or use the VM handle, don't do both. */
883	PSUPDRVSESSION pSession;
884	/** Handle to the interface. */
885	INTNETIFHANDLE hIf;
886	/** The pointer to the ring-3 buffer. (output) */
887	R3PTRTYPE(PINTNETBUF) pRing3Buf;
888	/** The pointer to the ring-0 buffer. (output) */
889	R0PTRTYPE(PINTNETBUF) pRing0Buf;
890	} INTNETIFGETBUFFERPTRSREQ;
891	/** Pointer to an IntNetR0IfGetRing3BufferReq /
892	* VMMR0_DO_INTNET_IF_GET_BUFFER_PTRS request buffer. */
893	typedef INTNETIFGETBUFFERPTRSREQ *PINTNETIFGETBUFFERPTRSREQ;
894
895	INTNETR0DECL(int) IntNetR0IfGetBufferPtrsReq(PSUPDRVSESSION pSession, PINTNETIFGETBUFFERPTRSREQ pReq);
896
897
898	/**
899	* Request buffer for IntNetR0IfSetPromiscuousModeReq /
900	* VMMR0_DO_INTNET_IF_SET_PROMISCUOUS_MODE.
901	* @see IntNetR0IfSetPromiscuousMode.
902	*/
903	typedef struct INTNETIFSETPROMISCUOUSMODEREQ
904	{
905	/** The request header. */
906	SUPVMMR0REQHDR Hdr;
907	/** Alternative to passing the taking the session from the VM handle.
908	* Either use this member or use the VM handle, don't do both. */
909	PSUPDRVSESSION pSession;
910	/** Handle to the interface. */
911	INTNETIFHANDLE hIf;
912	/** The new promiscuous mode. */
913	bool fPromiscuous;
914	} INTNETIFSETPROMISCUOUSMODEREQ;
915	/** Pointer to an IntNetR0IfSetPromiscuousModeReq /
916	* VMMR0_DO_INTNET_IF_SET_PROMISCUOUS_MODE request buffer. */
917	typedef INTNETIFSETPROMISCUOUSMODEREQ *PINTNETIFSETPROMISCUOUSMODEREQ;
918
919	INTNETR0DECL(int) IntNetR0IfSetPromiscuousModeReq(PSUPDRVSESSION pSession, PINTNETIFSETPROMISCUOUSMODEREQ pReq);
920
921
922	/**
923	* Request buffer for IntNetR0IfSetMacAddressReq /
924	* VMMR0_DO_INTNET_IF_SET_MAC_ADDRESS.
925	* @see IntNetR0IfSetMacAddress.
926	*/
927	typedef struct INTNETIFSETMACADDRESSREQ
928	{
929	/** The request header. */
930	SUPVMMR0REQHDR Hdr;
931	/** Alternative to passing the taking the session from the VM handle.
932	* Either use this member or use the VM handle, don't do both. */
933	PSUPDRVSESSION pSession;
934	/** Handle to the interface. */
935	INTNETIFHANDLE hIf;
936	/** The new MAC address. */
937	RTMAC Mac;
938	} INTNETIFSETMACADDRESSREQ;
939	/** Pointer to an IntNetR0IfSetMacAddressReq /
940	* VMMR0_DO_INTNET_IF_SET_MAC_ADDRESS request buffer. */
941	typedef INTNETIFSETMACADDRESSREQ *PINTNETIFSETMACADDRESSREQ;
942
943	INTNETR0DECL(int) IntNetR0IfSetMacAddressReq(PSUPDRVSESSION pSession, PINTNETIFSETMACADDRESSREQ pReq);
944
945
946	/**
947	* Request buffer for IntNetR0IfSetActiveReq / VMMR0_DO_INTNET_IF_SET_ACTIVE.
948	* @see IntNetR0IfSetActive.
949	*/
950	typedef struct INTNETIFSETACTIVEREQ
951	{
952	/** The request header. */
953	SUPVMMR0REQHDR Hdr;
954	/** Alternative to passing the taking the session from the VM handle.
955	* Either use this member or use the VM handle, don't do both. */
956	PSUPDRVSESSION pSession;
957	/** Handle to the interface. */
958	INTNETIFHANDLE hIf;
959	/** The new state. */
960	bool fActive;
961	} INTNETIFSETACTIVEREQ;
962	/** Pointer to an IntNetR0IfSetActiveReq / VMMR0_DO_INTNET_IF_SET_ACTIVE
963	* request buffer. */
964	typedef INTNETIFSETACTIVEREQ *PINTNETIFSETACTIVEREQ;
965
966	INTNETR0DECL(int) IntNetR0IfSetActiveReq(PSUPDRVSESSION pSession, PINTNETIFSETACTIVEREQ pReq);
967
968
969	/**
970	* Request buffer for IntNetR0IfSendReq / VMMR0_DO_INTNET_IF_SEND.
971	* @see IntNetR0IfSend.
972	*/
973	typedef struct INTNETIFSENDREQ
974	{
975	/** The request header. */
976	SUPVMMR0REQHDR Hdr;
977	/** Alternative to passing the taking the session from the VM handle.
978	* Either use this member or use the VM handle, don't do both. */
979	PSUPDRVSESSION pSession;
980	/** Handle to the interface. */
981	INTNETIFHANDLE hIf;
982	} INTNETIFSENDREQ;
983	/** Pointer to an IntNetR0IfSend() argument package. */
984	typedef INTNETIFSENDREQ *PINTNETIFSENDREQ;
985
986	INTNETR0DECL(int) IntNetR0IfSendReq(PSUPDRVSESSION pSession, PINTNETIFSENDREQ pReq);
987
988
989	/**
990	* Request buffer for IntNetR0IfWaitReq / VMMR0_DO_INTNET_IF_WAIT.
991	* @see IntNetR0IfWait.
992	*/
993	typedef struct INTNETIFWAITREQ
994	{
995	/** The request header. */
996	SUPVMMR0REQHDR Hdr;
997	/** Alternative to passing the taking the session from the VM handle.
998	* Either use this member or use the VM handle, don't do both. */
999	PSUPDRVSESSION pSession;
1000	/** Handle to the interface. */
1001	INTNETIFHANDLE hIf;
1002	/** The number of milliseconds to wait. */
1003	uint32_t cMillies;
1004	} INTNETIFWAITREQ;
1005	/** Pointer to an IntNetR0IfWaitReq / VMMR0_DO_INTNET_IF_WAIT request buffer. */
1006	typedef INTNETIFWAITREQ *PINTNETIFWAITREQ;
1007
1008	INTNETR0DECL(int) IntNetR0IfWaitReq(PSUPDRVSESSION pSession, PINTNETIFWAITREQ pReq);
1009
1010
1011	#if defined(IN_RING0) \|\| defined(IN_INTNET_TESTCASE)
1012	/** @name
1013	* @{
1014	*/
1015
1016	INTNETR0DECL(int) IntNetR0Init(void);
1017	INTNETR0DECL(void) IntNetR0Term(void);
1018	INTNETR0DECL(int) IntNetR0Open(PSUPDRVSESSION pSession, const char *pszNetwork,
1019	INTNETTRUNKTYPE enmTrunkType, const char *pszTrunk, uint32_t fFlags,
1020	uint32_t cbSend, uint32_t cbRecv, PINTNETIFHANDLE phIf);
1021	INTNETR0DECL(uint32_t) IntNetR0GetNetworkCount(void);
1022
1023	INTNETR0DECL(int) IntNetR0IfClose(INTNETIFHANDLE hIf, PSUPDRVSESSION pSession);
1024	INTNETR0DECL(int) IntNetR0IfGetBufferPtrs(INTNETIFHANDLE hIf, PSUPDRVSESSION pSession,
1025	R3PTRTYPE(PINTNETBUF) ppRing3Buf, R0PTRTYPE(PINTNETBUF) ppRing0Buf);
1026	INTNETR0DECL(int) IntNetR0IfSetPromiscuousMode(INTNETIFHANDLE hIf, PSUPDRVSESSION pSession, bool fPromiscuous);
1027	INTNETR0DECL(int) IntNetR0IfSetMacAddress(INTNETIFHANDLE hIf, PSUPDRVSESSION pSession, PCRTMAC pMac);
1028	INTNETR0DECL(int) IntNetR0IfSetActive(INTNETIFHANDLE hIf, PSUPDRVSESSION pSession, bool fActive);
1029	INTNETR0DECL(int) IntNetR0IfSend(INTNETIFHANDLE hIf, PSUPDRVSESSION pSession);
1030	INTNETR0DECL(int) IntNetR0IfWait(INTNETIFHANDLE hIf, PSUPDRVSESSION pSession, uint32_t cMillies);
1031
1032	/** @} */
1033	#endif /* IN_RING0 */
1034
1035	RT_C_DECLS_END
1036
1037	#endif

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

source: vbox/trunk/include/VBox/intnet.h@ 28828

Download in other formats: