intnet.h@ 25346

Last change on this file since 25346 was 23209, checked in by vboxsync, 15 years ago
More stupid alignment issues
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 36.7 KB

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

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

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

Download in other formats: