VirtualBox

source: vbox/trunk/src/VBox/Devices/Network/DrvIntNet.cpp@ 91942

Last change on this file since 91942 was 91883, checked in by vboxsync, 3 years ago

Devices/Network: Change the network drivers to access the CFGM API through the driver helper callback table only, bugref:10074 [some missing calls to CFGMR3*]
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 74.5 KB
Line 
1/* $Id: DrvIntNet.cpp 91883 2021-10-20 11:47:48Z vboxsync $ */
2/** @file
3 * DrvIntNet - Internal network transport driver.
4 */
5
6/*
7 * Copyright (C) 2006-2020 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18
19/*********************************************************************************************************************************
20* Header Files *
21*********************************************************************************************************************************/
22#define LOG_GROUP LOG_GROUP_DRV_INTNET
23#include <VBox/vmm/pdmdrv.h>
24#include <VBox/vmm/pdmnetinline.h>
25#include <VBox/vmm/pdmnetifs.h>
26#include <VBox/vmm/cfgm.h>
27#include <VBox/intnet.h>
28#include <VBox/intnetinline.h>
29#include <VBox/vmm/vmm.h>
30#include <VBox/sup.h>
31#include <VBox/err.h>
32
33#include <VBox/param.h>
34#include <VBox/log.h>
35#include <iprt/asm.h>
36#include <iprt/assert.h>
37#include <iprt/ctype.h>
38#include <iprt/memcache.h>
39#include <iprt/net.h>
40#include <iprt/semaphore.h>
41#include <iprt/string.h>
42#include <iprt/time.h>
43#include <iprt/thread.h>
44#include <iprt/uuid.h>
45#if defined(RT_OS_DARWIN) && defined(IN_RING3)
46# include <iprt/system.h>
47#endif
48
49#include "VBoxDD.h"
50
51
52/*********************************************************************************************************************************
53* Defined Constants And Macros *
54*********************************************************************************************************************************/
55/** Enables the ring-0 part. */
56#define VBOX_WITH_DRVINTNET_IN_R0
57
58
59/*********************************************************************************************************************************
60* Structures and Typedefs *
61*********************************************************************************************************************************/
62/**
63 * The state of the asynchronous thread.
64 */
65typedef enum RECVSTATE
66{
67 /** The thread is suspended. */
68 RECVSTATE_SUSPENDED = 1,
69 /** The thread is running. */
70 RECVSTATE_RUNNING,
71 /** The thread must (/has) terminate. */
72 RECVSTATE_TERMINATE,
73 /** The usual 32-bit type blowup. */
74 RECVSTATE_32BIT_HACK = 0x7fffffff
75} RECVSTATE;
76
77/**
78 * Internal networking driver instance data.
79 *
80 * @implements PDMINETWORKUP
81 */
82typedef struct DRVINTNET
83{
84 /** The network interface. */
85 PDMINETWORKUP INetworkUpR3;
86 /** The network interface. */
87 R3PTRTYPE(PPDMINETWORKDOWN) pIAboveNet;
88 /** The network config interface.
89 * Can (in theory at least) be NULL. */
90 R3PTRTYPE(PPDMINETWORKCONFIG) pIAboveConfigR3;
91 /** Pointer to the driver instance (ring-3). */
92 PPDMDRVINSR3 pDrvInsR3;
93 /** Pointer to the communication buffer (ring-3). */
94 R3PTRTYPE(PINTNETBUF) pBufR3;
95 /** Ring-3 base interface for the ring-0 context. */
96 PDMIBASER0 IBaseR0;
97 /** Ring-3 base interface for the raw-mode context. */
98 PDMIBASERC IBaseRC;
99 RTR3PTR R3PtrAlignment;
100
101 /** The network interface for the ring-0 context. */
102 PDMINETWORKUPR0 INetworkUpR0;
103 /** Pointer to the driver instance (ring-0). */
104 PPDMDRVINSR0 pDrvInsR0;
105 /** Pointer to the communication buffer (ring-0). */
106 R0PTRTYPE(PINTNETBUF) pBufR0;
107
108 /** The network interface for the raw-mode context. */
109 PDMINETWORKUPRC INetworkUpRC;
110 /** Pointer to the driver instance. */
111 PPDMDRVINSRC pDrvInsRC;
112 RTRCPTR RCPtrAlignment;
113
114 /** The transmit lock. */
115 PDMCRITSECT XmitLock;
116 /** Interface handle. */
117 INTNETIFHANDLE hIf;
118 /** The receive thread state. */
119 RECVSTATE volatile enmRecvState;
120 /** The receive thread. */
121 RTTHREAD hRecvThread;
122 /** The event semaphore that the receive thread waits on. */
123 RTSEMEVENT hRecvEvt;
124 /** The transmit thread. */
125 PPDMTHREAD pXmitThread;
126 /** The event semaphore that the transmit thread waits on. */
127 SUPSEMEVENT hXmitEvt;
128 /** The support driver session handle. */
129 PSUPDRVSESSION pSupDrvSession;
130 /** Scatter/gather descriptor cache. */
131 RTMEMCACHE hSgCache;
132 /** Set if the link is down.
133 * When the link is down all incoming packets will be dropped. */
134 bool volatile fLinkDown;
135 /** Set when the xmit thread has been signalled. (atomic) */
136 bool volatile fXmitSignalled;
137 /** Set if the transmit thread the one busy transmitting. */
138 bool volatile fXmitOnXmitThread;
139 /** The xmit thread should process the ring ASAP. */
140 bool fXmitProcessRing;
141 /** Set if data transmission should start immediately and deactivate
142 * as late as possible. */
143 bool fActivateEarlyDeactivateLate;
144 /** Padding. */
145 bool afReserved[HC_ARCH_BITS == 64 ? 3 : 3];
146 /** Scratch space for holding the ring-0 scatter / gather descriptor.
147 * The PDMSCATTERGATHER::fFlags member is used to indicate whether it is in
148 * use or not. Always accessed while owning the XmitLock. */
149 union
150 {
151 PDMSCATTERGATHER Sg;
152 uint8_t padding[8 * sizeof(RTUINTPTR)];
153 } u;
154 /** The network name. */
155 char szNetwork[INTNET_MAX_NETWORK_NAME];
156
157 /** Number of GSO packets sent. */
158 STAMCOUNTER StatSentGso;
159 /** Number of GSO packets received. */
160 STAMCOUNTER StatReceivedGso;
161 /** Number of packets send from ring-0. */
162 STAMCOUNTER StatSentR0;
163 /** The number of times we've had to wake up the xmit thread to continue the
164 * ring-0 job. */
165 STAMCOUNTER StatXmitWakeupR0;
166 /** The number of times we've had to wake up the xmit thread to continue the
167 * ring-3 job. */
168 STAMCOUNTER StatXmitWakeupR3;
169 /** The times the xmit thread has been told to process the ring. */
170 STAMCOUNTER StatXmitProcessRing;
171#ifdef VBOX_WITH_STATISTICS
172 /** Profiling packet transmit runs. */
173 STAMPROFILE StatTransmit;
174 /** Profiling packet receive runs. */
175 STAMPROFILEADV StatReceive;
176#endif /* VBOX_WITH_STATISTICS */
177#ifdef LOG_ENABLED
178 /** The nano ts of the last transfer. */
179 uint64_t u64LastTransferTS;
180 /** The nano ts of the last receive. */
181 uint64_t u64LastReceiveTS;
182#endif
183} DRVINTNET;
184AssertCompileMemberAlignment(DRVINTNET, XmitLock, 8);
185AssertCompileMemberAlignment(DRVINTNET, StatSentGso, 8);
186/** Pointer to instance data of the internal networking driver. */
187typedef DRVINTNET *PDRVINTNET;
188
189/**
190 * Config value to flag translation structure.
191 */
192typedef struct DRVINTNETFLAG
193{
194 /** The value. */
195 const char *pszChoice;
196 /** The corresponding flag. */
197 uint32_t fFlag;
198} DRVINTNETFLAG;
199/** Pointer to a const flag value translation. */
200typedef DRVINTNETFLAG const *PCDRVINTNETFLAG;
201
202
203#ifdef IN_RING3
204
205
206/**
207 * Updates the MAC address on the kernel side.
208 *
209 * @returns VBox status code.
210 * @param pThis The driver instance.
211 */
212static int drvR3IntNetUpdateMacAddress(PDRVINTNET pThis)
213{
214 if (!pThis->pIAboveConfigR3)
215 return VINF_SUCCESS;
216
217 INTNETIFSETMACADDRESSREQ SetMacAddressReq;
218 SetMacAddressReq.Hdr.u32Magic = SUPVMMR0REQHDR_MAGIC;
219 SetMacAddressReq.Hdr.cbReq = sizeof(SetMacAddressReq);
220 SetMacAddressReq.pSession = NIL_RTR0PTR;
221 SetMacAddressReq.hIf = pThis->hIf;
222 int rc = pThis->pIAboveConfigR3->pfnGetMac(pThis->pIAboveConfigR3, &SetMacAddressReq.Mac);
223 if (RT_SUCCESS(rc))
224 rc = PDMDrvHlpSUPCallVMMR0Ex(pThis->pDrvInsR3, VMMR0_DO_INTNET_IF_SET_MAC_ADDRESS,
225 &SetMacAddressReq, sizeof(SetMacAddressReq));
226
227 Log(("drvR3IntNetUpdateMacAddress: %.*Rhxs rc=%Rrc\n", sizeof(SetMacAddressReq.Mac), &SetMacAddressReq.Mac, rc));
228 return rc;
229}
230
231
232/**
233 * Sets the kernel interface active or inactive.
234 *
235 * Worker for poweron, poweroff, suspend and resume.
236 *
237 * @returns VBox status code.
238 * @param pThis The driver instance.
239 * @param fActive The new state.
240 */
241static int drvR3IntNetSetActive(PDRVINTNET pThis, bool fActive)
242{
243 if (!pThis->pIAboveConfigR3)
244 return VINF_SUCCESS;
245
246 INTNETIFSETACTIVEREQ SetActiveReq;
247 SetActiveReq.Hdr.u32Magic = SUPVMMR0REQHDR_MAGIC;
248 SetActiveReq.Hdr.cbReq = sizeof(SetActiveReq);
249 SetActiveReq.pSession = NIL_RTR0PTR;
250 SetActiveReq.hIf = pThis->hIf;
251 SetActiveReq.fActive = fActive;
252 int rc = PDMDrvHlpSUPCallVMMR0Ex(pThis->pDrvInsR3, VMMR0_DO_INTNET_IF_SET_ACTIVE,
253 &SetActiveReq, sizeof(SetActiveReq));
254
255 Log(("drvR3IntNetSetActive: fActive=%d rc=%Rrc\n", fActive, rc));
256 AssertRC(rc);
257 return rc;
258}
259
260#endif /* IN_RING3 */
261
262/* -=-=-=-=- PDMINETWORKUP -=-=-=-=- */
263
264#ifndef IN_RING3
265/**
266 * Helper for signalling the xmit thread.
267 *
268 * @returns VERR_TRY_AGAIN (convenience).
269 * @param pThis The instance data..
270 */
271DECLINLINE(int) drvR0IntNetSignalXmit(PDRVINTNET pThis)
272{
273 /// @todo if (!ASMAtomicXchgBool(&pThis->fXmitSignalled, true)) - needs careful optimizing.
274 {
275 int rc = SUPSemEventSignal(pThis->pSupDrvSession, pThis->hXmitEvt);
276 AssertRC(rc);
277 STAM_REL_COUNTER_INC(&pThis->CTX_SUFF(StatXmitWakeup));
278 }
279 return VERR_TRY_AGAIN;
280}
281#endif /* !IN_RING3 */
282
283
284/**
285 * Helper for processing the ring-0 consumer side of the xmit ring.
286 *
287 * The caller MUST own the xmit lock.
288 *
289 * @returns Status code from IntNetR0IfSend, except for VERR_TRY_AGAIN.
290 * @param pThis The instance data..
291 */
292DECLINLINE(int) drvIntNetProcessXmit(PDRVINTNET pThis)
293{
294 Assert(PDMDrvHlpCritSectIsOwner(pThis->CTX_SUFF(pDrvIns), &pThis->XmitLock));
295
296#ifdef IN_RING3
297 INTNETIFSENDREQ SendReq;
298 SendReq.Hdr.u32Magic = SUPVMMR0REQHDR_MAGIC;
299 SendReq.Hdr.cbReq = sizeof(SendReq);
300 SendReq.pSession = NIL_RTR0PTR;
301 SendReq.hIf = pThis->hIf;
302 int rc = PDMDrvHlpSUPCallVMMR0Ex(pThis->pDrvInsR3, VMMR0_DO_INTNET_IF_SEND, &SendReq, sizeof(SendReq));
303#else
304 int rc = IntNetR0IfSend(pThis->hIf, pThis->pSupDrvSession);
305 if (rc == VERR_TRY_AGAIN)
306 {
307 ASMAtomicUoWriteBool(&pThis->fXmitProcessRing, true);
308 drvR0IntNetSignalXmit(pThis);
309 rc = VINF_SUCCESS;
310 }
311#endif
312 return rc;
313}
314
315
316
317/**
318 * @interface_method_impl{PDMINETWORKUP,pfnBeginXmit}
319 */
320PDMBOTHCBDECL(int) drvIntNetUp_BeginXmit(PPDMINETWORKUP pInterface, bool fOnWorkerThread)
321{
322 PDRVINTNET pThis = RT_FROM_MEMBER(pInterface, DRVINTNET, CTX_SUFF(INetworkUp));
323#ifndef IN_RING3
324 Assert(!fOnWorkerThread);
325#endif
326
327 int rc = PDMDrvHlpCritSectTryEnter(pThis->CTX_SUFF(pDrvIns), &pThis->XmitLock);
328 if (RT_SUCCESS(rc))
329 {
330 if (fOnWorkerThread)
331 {
332 ASMAtomicUoWriteBool(&pThis->fXmitOnXmitThread, true);
333 ASMAtomicWriteBool(&pThis->fXmitSignalled, false);
334 }
335 }
336 else if (rc == VERR_SEM_BUSY)
337 {
338 /** @todo Does this actually make sense if the other dude is an EMT and so
339 * forth? I seriously think this is ring-0 only...
340 * We might end up waking up the xmit thread unnecessarily here, even when in
341 * ring-0... This needs some more thought and optimizations when the ring-0 bits
342 * are working. */
343#ifdef IN_RING3
344 if ( !fOnWorkerThread
345 /*&& !ASMAtomicUoReadBool(&pThis->fXmitOnXmitThread)
346 && ASMAtomicCmpXchgBool(&pThis->fXmitSignalled, true, false)*/)
347 {
348 rc = SUPSemEventSignal(pThis->pSupDrvSession, pThis->hXmitEvt);
349 AssertRC(rc);
350 }
351 rc = VERR_TRY_AGAIN;
352#else /* IN_RING0 */
353 rc = drvR0IntNetSignalXmit(pThis);
354#endif /* IN_RING0 */
355 }
356 return rc;
357}
358
359
360/**
361 * @interface_method_impl{PDMINETWORKUP,pfnAllocBuf}
362 */
363PDMBOTHCBDECL(int) drvIntNetUp_AllocBuf(PPDMINETWORKUP pInterface, size_t cbMin,
364 PCPDMNETWORKGSO pGso, PPPDMSCATTERGATHER ppSgBuf)
365{
366 PDRVINTNET pThis = RT_FROM_MEMBER(pInterface, DRVINTNET, CTX_SUFF(INetworkUp));
367 int rc = VINF_SUCCESS;
368 Assert(cbMin < UINT32_MAX / 2);
369 Assert(PDMDrvHlpCritSectIsOwner(pThis->CTX_SUFF(pDrvIns), &pThis->XmitLock));
370
371 /*
372 * Allocate a S/G descriptor.
373 * This shouldn't normally fail as the NICs usually won't allocate more
374 * than one buffer at a time and the SG gets freed on sending.
375 */
376#ifdef IN_RING3
377 PPDMSCATTERGATHER pSgBuf = (PPDMSCATTERGATHER)RTMemCacheAlloc(pThis->hSgCache);
378 if (!pSgBuf)
379 return VERR_NO_MEMORY;
380#else
381 PPDMSCATTERGATHER pSgBuf = &pThis->u.Sg;
382 if (RT_UNLIKELY(pSgBuf->fFlags != 0))
383 return drvR0IntNetSignalXmit(pThis);
384#endif
385
386 /*
387 * Allocate room in the ring buffer.
388 *
389 * In ring-3 we may have to process the xmit ring before there is
390 * sufficient buffer space since we might have stacked up a few frames to the
391 * trunk while in ring-0. (There is not point of doing this in ring-0.)
392 */
393 PINTNETHDR pHdr = NULL; /* gcc silliness */
394 if (pGso)
395 rc = IntNetRingAllocateGsoFrame(&pThis->CTX_SUFF(pBuf)->Send, (uint32_t)cbMin, pGso,
396 &pHdr, &pSgBuf->aSegs[0].pvSeg);
397 else
398 rc = IntNetRingAllocateFrame(&pThis->CTX_SUFF(pBuf)->Send, (uint32_t)cbMin,
399 &pHdr, &pSgBuf->aSegs[0].pvSeg);
400#ifdef IN_RING3
401 if ( RT_FAILURE(rc)
402 && pThis->CTX_SUFF(pBuf)->cbSend >= cbMin * 2 + sizeof(INTNETHDR))
403 {
404 drvIntNetProcessXmit(pThis);
405 if (pGso)
406 rc = IntNetRingAllocateGsoFrame(&pThis->CTX_SUFF(pBuf)->Send, (uint32_t)cbMin, pGso,
407 &pHdr, &pSgBuf->aSegs[0].pvSeg);
408 else
409 rc = IntNetRingAllocateFrame(&pThis->CTX_SUFF(pBuf)->Send, (uint32_t)cbMin,
410 &pHdr, &pSgBuf->aSegs[0].pvSeg);
411 }
412#endif
413 if (RT_SUCCESS(rc))
414 {
415 /*
416 * Set up the S/G descriptor and return successfully.
417 */
418 pSgBuf->fFlags = PDMSCATTERGATHER_FLAGS_MAGIC | PDMSCATTERGATHER_FLAGS_OWNER_1;
419 pSgBuf->cbUsed = 0;
420 pSgBuf->cbAvailable = cbMin;
421 pSgBuf->pvAllocator = pHdr;
422 pSgBuf->pvUser = pGso ? (PPDMNETWORKGSO)pSgBuf->aSegs[0].pvSeg - 1 : NULL;
423 pSgBuf->cSegs = 1;
424 pSgBuf->aSegs[0].cbSeg = cbMin;
425
426 *ppSgBuf = pSgBuf;
427 return VINF_SUCCESS;
428 }
429
430#ifdef IN_RING3
431 /*
432 * If the above fails, then we're really out of space. There are nobody
433 * competing with us here because of the xmit lock.
434 */
435 rc = VERR_NO_MEMORY;
436 RTMemCacheFree(pThis->hSgCache, pSgBuf);
437
438#else /* IN_RING0 */
439 /*
440 * If the request is reasonable, kick the xmit thread and tell it to
441 * process the xmit ring ASAP.
442 */
443 if (pThis->CTX_SUFF(pBuf)->cbSend >= cbMin * 2 + sizeof(INTNETHDR))
444 {
445 pThis->fXmitProcessRing = true;
446 rc = drvR0IntNetSignalXmit(pThis);
447 }
448 else
449 rc = VERR_NO_MEMORY;
450 pSgBuf->fFlags = 0;
451#endif /* IN_RING0 */
452 return rc;
453}
454
455
456/**
457 * @interface_method_impl{PDMINETWORKUP,pfnFreeBuf}
458 */
459PDMBOTHCBDECL(int) drvIntNetUp_FreeBuf(PPDMINETWORKUP pInterface, PPDMSCATTERGATHER pSgBuf)
460{
461 PDRVINTNET pThis = RT_FROM_MEMBER(pInterface, DRVINTNET, CTX_SUFF(INetworkUp));
462 PINTNETHDR pHdr = (PINTNETHDR)pSgBuf->pvAllocator;
463#ifdef IN_RING0
464 Assert(pSgBuf == &pThis->u.Sg);
465#endif
466 Assert(pSgBuf->fFlags == (PDMSCATTERGATHER_FLAGS_MAGIC | PDMSCATTERGATHER_FLAGS_OWNER_1));
467 Assert(pSgBuf->cbUsed <= pSgBuf->cbAvailable);
468 Assert( pHdr->u8Type == INTNETHDR_TYPE_FRAME
469 || pHdr->u8Type == INTNETHDR_TYPE_GSO);
470 Assert(PDMDrvHlpCritSectIsOwner(pThis->CTX_SUFF(pDrvIns), &pThis->XmitLock));
471
472 /** @todo LATER: try unalloc the frame. */
473 pHdr->u8Type = INTNETHDR_TYPE_PADDING;
474 IntNetRingCommitFrame(&pThis->CTX_SUFF(pBuf)->Send, pHdr);
475
476#ifdef IN_RING3
477 RTMemCacheFree(pThis->hSgCache, pSgBuf);
478#else
479 pSgBuf->fFlags = 0;
480#endif
481 return VINF_SUCCESS;
482}
483
484
485/**
486 * @interface_method_impl{PDMINETWORKUP,pfnSendBuf}
487 */
488PDMBOTHCBDECL(int) drvIntNetUp_SendBuf(PPDMINETWORKUP pInterface, PPDMSCATTERGATHER pSgBuf, bool fOnWorkerThread)
489{
490 PDRVINTNET pThis = RT_FROM_MEMBER(pInterface, DRVINTNET, CTX_SUFF(INetworkUp));
491 STAM_PROFILE_START(&pThis->StatTransmit, a);
492 RT_NOREF_PV(fOnWorkerThread);
493
494 AssertPtr(pSgBuf);
495 Assert(pSgBuf->fFlags == (PDMSCATTERGATHER_FLAGS_MAGIC | PDMSCATTERGATHER_FLAGS_OWNER_1));
496 Assert(pSgBuf->cbUsed <= pSgBuf->cbAvailable);
497 Assert(PDMDrvHlpCritSectIsOwner(pThis->CTX_SUFF(pDrvIns), &pThis->XmitLock));
498
499 if (pSgBuf->pvUser)
500 STAM_COUNTER_INC(&pThis->StatSentGso);
501
502 /*
503 * Commit the frame and push it thru the switch.
504 */
505 PINTNETHDR pHdr = (PINTNETHDR)pSgBuf->pvAllocator;
506 IntNetRingCommitFrameEx(&pThis->CTX_SUFF(pBuf)->Send, pHdr, pSgBuf->cbUsed);
507 int rc = drvIntNetProcessXmit(pThis);
508 STAM_PROFILE_STOP(&pThis->StatTransmit, a);
509
510 /*
511 * Free the descriptor and return.
512 */
513#ifdef IN_RING3
514 RTMemCacheFree(pThis->hSgCache, pSgBuf);
515#else
516 STAM_REL_COUNTER_INC(&pThis->StatSentR0);
517 pSgBuf->fFlags = 0;
518#endif
519 return rc;
520}
521
522
523/**
524 * @interface_method_impl{PDMINETWORKUP,pfnEndXmit}
525 */
526PDMBOTHCBDECL(void) drvIntNetUp_EndXmit(PPDMINETWORKUP pInterface)
527{
528 PDRVINTNET pThis = RT_FROM_MEMBER(pInterface, DRVINTNET, CTX_SUFF(INetworkUp));
529 ASMAtomicUoWriteBool(&pThis->fXmitOnXmitThread, false);
530 PDMDrvHlpCritSectLeave(pThis->CTX_SUFF(pDrvIns), &pThis->XmitLock);
531}
532
533
534/**
535 * @interface_method_impl{PDMINETWORKUP,pfnSetPromiscuousMode}
536 */
537PDMBOTHCBDECL(void) drvIntNetUp_SetPromiscuousMode(PPDMINETWORKUP pInterface, bool fPromiscuous)
538{
539 PDRVINTNET pThis = RT_FROM_MEMBER(pInterface, DRVINTNET, CTX_SUFF(INetworkUp));
540
541#ifdef IN_RING3
542 INTNETIFSETPROMISCUOUSMODEREQ Req;
543 Req.Hdr.u32Magic = SUPVMMR0REQHDR_MAGIC;
544 Req.Hdr.cbReq = sizeof(Req);
545 Req.pSession = NIL_RTR0PTR;
546 Req.hIf = pThis->hIf;
547 Req.fPromiscuous = fPromiscuous;
548 int rc = PDMDrvHlpSUPCallVMMR0Ex(pThis->pDrvInsR3, VMMR0_DO_INTNET_IF_SET_PROMISCUOUS_MODE, &Req, sizeof(Req));
549#else /* IN_RING0 */
550 int rc = IntNetR0IfSetPromiscuousMode(pThis->hIf, pThis->pSupDrvSession, fPromiscuous);
551#endif /* IN_RING0 */
552
553 LogFlow(("drvIntNetUp_SetPromiscuousMode: fPromiscuous=%RTbool\n", fPromiscuous));
554 AssertRC(rc);
555}
556
557#ifdef IN_RING3
558
559/**
560 * @interface_method_impl{PDMINETWORKUP,pfnNotifyLinkChanged}
561 */
562static DECLCALLBACK(void) drvR3IntNetUp_NotifyLinkChanged(PPDMINETWORKUP pInterface, PDMNETWORKLINKSTATE enmLinkState)
563{
564 PDRVINTNET pThis = RT_FROM_MEMBER(pInterface, DRVINTNET, CTX_SUFF(INetworkUp));
565 bool fLinkDown;
566 switch (enmLinkState)
567 {
568 case PDMNETWORKLINKSTATE_DOWN:
569 case PDMNETWORKLINKSTATE_DOWN_RESUME:
570 fLinkDown = true;
571 break;
572 default:
573 AssertMsgFailed(("enmLinkState=%d\n", enmLinkState));
574 RT_FALL_THRU();
575 case PDMNETWORKLINKSTATE_UP:
576 fLinkDown = false;
577 break;
578 }
579 LogFlow(("drvR3IntNetUp_NotifyLinkChanged: enmLinkState=%d %d->%d\n", enmLinkState, pThis->fLinkDown, fLinkDown));
580 ASMAtomicXchgSize(&pThis->fLinkDown, fLinkDown);
581}
582
583
584/* -=-=-=-=- Transmit Thread -=-=-=-=- */
585
586/**
587 * Async I/O thread for deferred packet transmission.
588 *
589 * @returns VBox status code. Returning failure will naturally terminate the thread.
590 * @param pDrvIns The internal networking driver instance.
591 * @param pThread The thread.
592 */
593static DECLCALLBACK(int) drvR3IntNetXmitThread(PPDMDRVINS pDrvIns, PPDMTHREAD pThread)
594{
595 PDRVINTNET pThis = PDMINS_2_DATA(pDrvIns, PDRVINTNET);
596
597 while (pThread->enmState == PDMTHREADSTATE_RUNNING)
598 {
599 /*
600 * Transmit any pending packets.
601 */
602 /** @todo Optimize this. We shouldn't call pfnXmitPending unless asked for.
603 * Also there is no need to call drvIntNetProcessXmit if we also
604 * called pfnXmitPending and send one or more frames. */
605 if (ASMAtomicXchgBool(&pThis->fXmitProcessRing, false))
606 {
607 STAM_REL_COUNTER_INC(&pThis->StatXmitProcessRing);
608 PDMDrvHlpCritSectEnter(pDrvIns, &pThis->XmitLock, VERR_IGNORED);
609 drvIntNetProcessXmit(pThis);
610 PDMDrvHlpCritSectLeave(pDrvIns, &pThis->XmitLock);
611 }
612
613 pThis->pIAboveNet->pfnXmitPending(pThis->pIAboveNet);
614
615 if (ASMAtomicXchgBool(&pThis->fXmitProcessRing, false))
616 {
617 STAM_REL_COUNTER_INC(&pThis->StatXmitProcessRing);
618 PDMDrvHlpCritSectEnter(pDrvIns, &pThis->XmitLock, VERR_IGNORED);
619 drvIntNetProcessXmit(pThis);
620 PDMDrvHlpCritSectLeave(pDrvIns, &pThis->XmitLock);
621 }
622
623 /*
624 * Block until we've got something to send or is supposed
625 * to leave the running state.
626 */
627 int rc = SUPSemEventWaitNoResume(pThis->pSupDrvSession, pThis->hXmitEvt, RT_INDEFINITE_WAIT);
628 AssertLogRelMsgReturn(RT_SUCCESS(rc) || rc == VERR_INTERRUPTED, ("%Rrc\n", rc), rc);
629 if (RT_UNLIKELY(pThread->enmState != PDMTHREADSTATE_RUNNING))
630 break;
631
632 }
633
634 /* The thread is being initialized, suspended or terminated. */
635 return VINF_SUCCESS;
636}
637
638
639/**
640 * @copydoc FNPDMTHREADWAKEUPDRV
641 */
642static DECLCALLBACK(int) drvR3IntNetXmitWakeUp(PPDMDRVINS pDrvIns, PPDMTHREAD pThread)
643{
644 RT_NOREF(pThread);
645 PDRVINTNET pThis = PDMINS_2_DATA(pDrvIns, PDRVINTNET);
646 return SUPSemEventSignal(pThis->pSupDrvSession, pThis->hXmitEvt);
647}
648
649
650/* -=-=-=-=- Receive Thread -=-=-=-=- */
651
652/**
653 * Wait for space to become available up the driver/device chain.
654 *
655 * @returns VINF_SUCCESS if space is available.
656 * @returns VERR_STATE_CHANGED if the state changed.
657 * @returns VBox status code on other errors.
658 * @param pThis Pointer to the instance data.
659 */
660static int drvR3IntNetRecvWaitForSpace(PDRVINTNET pThis)
661{
662 LogFlow(("drvR3IntNetRecvWaitForSpace:\n"));
663 STAM_PROFILE_ADV_STOP(&pThis->StatReceive, a);
664 int rc = pThis->pIAboveNet->pfnWaitReceiveAvail(pThis->pIAboveNet, RT_INDEFINITE_WAIT);
665 STAM_PROFILE_ADV_START(&pThis->StatReceive, a);
666 LogFlow(("drvR3IntNetRecvWaitForSpace: returns %Rrc\n", rc));
667 return rc;
668}
669
670
671/**
672 * Executes async I/O (RUNNING mode).
673 *
674 * @returns VERR_STATE_CHANGED if the state changed.
675 * @returns Appropriate VBox status code (error) on fatal error.
676 * @param pThis The driver instance data.
677 */
678static int drvR3IntNetRecvRun(PDRVINTNET pThis)
679{
680 PPDMDRVINS pDrvIns = pThis->pDrvInsR3;
681 LogFlow(("drvR3IntNetRecvRun: pThis=%p\n", pThis));
682
683 /*
684 * The running loop - processing received data and waiting for more to arrive.
685 */
686 STAM_PROFILE_ADV_START(&pThis->StatReceive, a);
687 PINTNETBUF pBuf = pThis->CTX_SUFF(pBuf);
688 PINTNETRINGBUF pRingBuf = &pBuf->Recv;
689 for (;;)
690 {
691 /*
692 * Process the receive buffer.
693 */
694 PINTNETHDR pHdr;
695 while ((pHdr = IntNetRingGetNextFrameToRead(pRingBuf)) != NULL)
696 {
697 /*
698 * Check the state and then inspect the packet.
699 */
700 if (pThis->enmRecvState != RECVSTATE_RUNNING)
701 {
702 STAM_PROFILE_ADV_STOP(&pThis->StatReceive, a);
703 LogFlow(("drvR3IntNetRecvRun: returns VERR_STATE_CHANGED (state changed - #0)\n"));
704 return VERR_STATE_CHANGED;
705 }
706
707 Log2(("pHdr=%p offRead=%#x: %.8Rhxs\n", pHdr, pRingBuf->offReadX, pHdr));
708 uint8_t u8Type = pHdr->u8Type;
709 if ( ( u8Type == INTNETHDR_TYPE_FRAME
710 || u8Type == INTNETHDR_TYPE_GSO)
711 && !pThis->fLinkDown)
712 {
713 /*
714 * Check if there is room for the frame and pass it up.
715 */
716 size_t cbFrame = pHdr->cbFrame;
717 int rc = pThis->pIAboveNet->pfnWaitReceiveAvail(pThis->pIAboveNet, 0);
718 if (rc == VINF_SUCCESS)
719 {
720 if (u8Type == INTNETHDR_TYPE_FRAME)
721 {
722 /*
723 * Normal frame.
724 */
725#ifdef LOG_ENABLED
726 if (LogIsEnabled())
727 {
728 uint64_t u64Now = RTTimeProgramNanoTS();
729 LogFlow(("drvR3IntNetRecvRun: %-4d bytes at %llu ns deltas: r=%llu t=%llu\n",
730 cbFrame, u64Now, u64Now - pThis->u64LastReceiveTS, u64Now - pThis->u64LastTransferTS));
731 pThis->u64LastReceiveTS = u64Now;
732 Log2(("drvR3IntNetRecvRun: cbFrame=%#x\n"
733 "%.*Rhxd\n",
734 cbFrame, cbFrame, IntNetHdrGetFramePtr(pHdr, pBuf)));
735 }
736#endif
737 rc = pThis->pIAboveNet->pfnReceive(pThis->pIAboveNet, IntNetHdrGetFramePtr(pHdr, pBuf), cbFrame);
738 AssertRC(rc);
739
740 /* skip to the next frame. */
741 IntNetRingSkipFrame(pRingBuf);
742 }
743 else
744 {
745 /*
746 * Generic segment offload frame (INTNETHDR_TYPE_GSO).
747 */
748 STAM_COUNTER_INC(&pThis->StatReceivedGso);
749 PCPDMNETWORKGSO pGso = IntNetHdrGetGsoContext(pHdr, pBuf);
750 if (PDMNetGsoIsValid(pGso, cbFrame, cbFrame - sizeof(PDMNETWORKGSO)))
751 {
752 if ( !pThis->pIAboveNet->pfnReceiveGso
753 || RT_FAILURE(pThis->pIAboveNet->pfnReceiveGso(pThis->pIAboveNet,
754 (uint8_t *)(pGso + 1),
755 pHdr->cbFrame - sizeof(PDMNETWORKGSO),
756 pGso)))
757 {
758 /*
759 * This is where we do the offloading since this NIC
760 * does not support large receive offload (LRO).
761 */
762 cbFrame -= sizeof(PDMNETWORKGSO);
763
764 uint8_t abHdrScratch[256];
765 uint32_t const cSegs = PDMNetGsoCalcSegmentCount(pGso, cbFrame);
766#ifdef LOG_ENABLED
767 if (LogIsEnabled())
768 {
769 uint64_t u64Now = RTTimeProgramNanoTS();
770 LogFlow(("drvR3IntNetRecvRun: %-4d bytes at %llu ns deltas: r=%llu t=%llu; GSO - %u segs\n",
771 cbFrame, u64Now, u64Now - pThis->u64LastReceiveTS, u64Now - pThis->u64LastTransferTS, cSegs));
772 pThis->u64LastReceiveTS = u64Now;
773 Log2(("drvR3IntNetRecvRun: cbFrame=%#x type=%d cbHdrsTotal=%#x cbHdrsSeg=%#x Hdr1=%#x Hdr2=%#x MMS=%#x\n"
774 "%.*Rhxd\n",
775 cbFrame, pGso->u8Type, pGso->cbHdrsTotal, pGso->cbHdrsSeg, pGso->offHdr1, pGso->offHdr2, pGso->cbMaxSeg,
776 cbFrame - sizeof(*pGso), pGso + 1));
777 }
778#endif
779 for (uint32_t iSeg = 0; iSeg < cSegs; iSeg++)
780 {
781 uint32_t cbSegFrame;
782 void *pvSegFrame = PDMNetGsoCarveSegmentQD(pGso, (uint8_t *)(pGso + 1), cbFrame,
783 abHdrScratch, iSeg, cSegs, &cbSegFrame);
784 rc = drvR3IntNetRecvWaitForSpace(pThis);
785 if (RT_FAILURE(rc))
786 {
787 Log(("drvR3IntNetRecvRun: drvR3IntNetRecvWaitForSpace -> %Rrc; iSeg=%u cSegs=%u\n", rc, iSeg, cSegs));
788 break; /* we drop the rest. */
789 }
790 rc = pThis->pIAboveNet->pfnReceive(pThis->pIAboveNet, pvSegFrame, cbSegFrame);
791 AssertRC(rc);
792 }
793 }
794 }
795 else
796 {
797 AssertMsgFailed(("cbFrame=%#x type=%d cbHdrsTotal=%#x cbHdrsSeg=%#x Hdr1=%#x Hdr2=%#x MMS=%#x\n",
798 cbFrame, pGso->u8Type, pGso->cbHdrsTotal, pGso->cbHdrsSeg, pGso->offHdr1, pGso->offHdr2, pGso->cbMaxSeg));
799 STAM_REL_COUNTER_INC(&pBuf->cStatBadFrames);
800 }
801
802 IntNetRingSkipFrame(pRingBuf);
803 }
804 }
805 else
806 {
807 /*
808 * Wait for sufficient space to become available and then retry.
809 */
810 rc = drvR3IntNetRecvWaitForSpace(pThis);
811 if (RT_FAILURE(rc))
812 {
813 if (rc == VERR_INTERRUPTED)
814 {
815 /*
816 * NIC is going down, likely because the VM is being reset. Skip the frame.
817 */
818 AssertMsg(IntNetIsValidFrameType(pHdr->u8Type), ("Unknown frame type %RX16! offRead=%#x\n", pHdr->u8Type, pRingBuf->offReadX));
819 IntNetRingSkipFrame(pRingBuf);
820 }
821 else
822 {
823 STAM_PROFILE_ADV_STOP(&pThis->StatReceive, a);
824 LogFlow(("drvR3IntNetRecvRun: returns %Rrc (wait-for-space)\n", rc));
825 return rc;
826 }
827 }
828 }
829 }
830 else
831 {
832 /*
833 * Link down or unknown frame - skip to the next frame.
834 */
835 AssertMsg(IntNetIsValidFrameType(pHdr->u8Type), ("Unknown frame type %RX16! offRead=%#x\n", pHdr->u8Type, pRingBuf->offReadX));
836 IntNetRingSkipFrame(pRingBuf);
837 STAM_REL_COUNTER_INC(&pBuf->cStatBadFrames);
838 }
839 } /* while more received data */
840
841 /*
842 * Wait for data, checking the state before we block.
843 */
844 if (pThis->enmRecvState != RECVSTATE_RUNNING)
845 {
846 STAM_PROFILE_ADV_STOP(&pThis->StatReceive, a);
847 LogFlow(("drvR3IntNetRecvRun: returns VINF_SUCCESS (state changed - #1)\n"));
848 return VERR_STATE_CHANGED;
849 }
850 INTNETIFWAITREQ WaitReq;
851 WaitReq.Hdr.u32Magic = SUPVMMR0REQHDR_MAGIC;
852 WaitReq.Hdr.cbReq = sizeof(WaitReq);
853 WaitReq.pSession = NIL_RTR0PTR;
854 WaitReq.hIf = pThis->hIf;
855 WaitReq.cMillies = 30000; /* 30s - don't wait forever, timeout now and then. */
856 STAM_PROFILE_ADV_STOP(&pThis->StatReceive, a);
857 int rc = PDMDrvHlpSUPCallVMMR0Ex(pDrvIns, VMMR0_DO_INTNET_IF_WAIT, &WaitReq, sizeof(WaitReq));
858 if ( RT_FAILURE(rc)
859 && rc != VERR_TIMEOUT
860 && rc != VERR_INTERRUPTED)
861 {
862 LogFlow(("drvR3IntNetRecvRun: returns %Rrc\n", rc));
863 return rc;
864 }
865 STAM_PROFILE_ADV_START(&pThis->StatReceive, a);
866 }
867}
868
869
870/**
871 * Asynchronous I/O thread for handling receive.
872 *
873 * @returns VINF_SUCCESS (ignored).
874 * @param hThreadSelf Thread handle.
875 * @param pvUser Pointer to a DRVINTNET structure.
876 */
877static DECLCALLBACK(int) drvR3IntNetRecvThread(RTTHREAD hThreadSelf, void *pvUser)
878{
879 RT_NOREF(hThreadSelf);
880 PDRVINTNET pThis = (PDRVINTNET)pvUser;
881 LogFlow(("drvR3IntNetRecvThread: pThis=%p\n", pThis));
882 STAM_PROFILE_ADV_START(&pThis->StatReceive, a);
883
884 /*
885 * The main loop - acting on state.
886 */
887 for (;;)
888 {
889 RECVSTATE enmRecvState = pThis->enmRecvState;
890 switch (enmRecvState)
891 {
892 case RECVSTATE_SUSPENDED:
893 {
894 int rc = RTSemEventWait(pThis->hRecvEvt, 30000);
895 if ( RT_FAILURE(rc)
896 && rc != VERR_TIMEOUT)
897 {
898 LogFlow(("drvR3IntNetRecvThread: returns %Rrc\n", rc));
899 return rc;
900 }
901 break;
902 }
903
904 case RECVSTATE_RUNNING:
905 {
906 int rc = drvR3IntNetRecvRun(pThis);
907 if ( rc != VERR_STATE_CHANGED
908 && RT_FAILURE(rc))
909 {
910 LogFlow(("drvR3IntNetRecvThread: returns %Rrc\n", rc));
911 return rc;
912 }
913 break;
914 }
915
916 default:
917 AssertMsgFailed(("Invalid state %d\n", enmRecvState));
918 RT_FALL_THRU();
919 case RECVSTATE_TERMINATE:
920 LogFlow(("drvR3IntNetRecvThread: returns VINF_SUCCESS\n"));
921 return VINF_SUCCESS;
922 }
923 }
924}
925
926
927/* -=-=-=-=- PDMIBASERC -=-=-=-=- */
928
929/**
930 * @interface_method_impl{PDMIBASERC,pfnQueryInterface}
931 */
932static DECLCALLBACK(RTRCPTR) drvR3IntNetIBaseRC_QueryInterface(PPDMIBASERC pInterface, const char *pszIID)
933{
934 PDRVINTNET pThis = RT_FROM_MEMBER(pInterface, DRVINTNET, IBaseRC);
935
936#if 0
937 PDMIBASERC_RETURN_INTERFACE(pThis->pDrvInsR3, pszIID, PDMINETWORKUP, &pThis->INetworkUpRC);
938#else
939 RT_NOREF(pThis, pszIID);
940#endif
941 return NIL_RTRCPTR;
942}
943
944
945/* -=-=-=-=- PDMIBASER0 -=-=-=-=- */
946
947/**
948 * @interface_method_impl{PDMIBASER0,pfnQueryInterface}
949 */
950static DECLCALLBACK(RTR0PTR) drvR3IntNetIBaseR0_QueryInterface(PPDMIBASER0 pInterface, const char *pszIID)
951{
952 PDRVINTNET pThis = RT_FROM_MEMBER(pInterface, DRVINTNET, IBaseR0);
953#ifdef VBOX_WITH_DRVINTNET_IN_R0
954 PDMIBASER0_RETURN_INTERFACE(pThis->pDrvInsR3, pszIID, PDMINETWORKUP, &pThis->INetworkUpR0);
955#endif
956 return NIL_RTR0PTR;
957}
958
959
960/* -=-=-=-=- PDMIBASE -=-=-=-=- */
961
962/**
963 * @interface_method_impl{PDMIBASE,pfnQueryInterface}
964 */
965static DECLCALLBACK(void *) drvR3IntNetIBase_QueryInterface(PPDMIBASE pInterface, const char *pszIID)
966{
967 PPDMDRVINS pDrvIns = PDMIBASE_2_PDMDRV(pInterface);
968 PDRVINTNET pThis = PDMINS_2_DATA(pDrvIns, PDRVINTNET);
969
970 PDMIBASE_RETURN_INTERFACE(pszIID, PDMIBASE, &pDrvIns->IBase);
971 PDMIBASE_RETURN_INTERFACE(pszIID, PDMIBASER0, &pThis->IBaseR0);
972 PDMIBASE_RETURN_INTERFACE(pszIID, PDMIBASERC, &pThis->IBaseRC);
973 PDMIBASE_RETURN_INTERFACE(pszIID, PDMINETWORKUP, &pThis->INetworkUpR3);
974 return NULL;
975}
976
977
978/* -=-=-=-=- PDMDRVREG -=-=-=-=- */
979
980/**
981 * Power Off notification.
982 *
983 * @param pDrvIns The driver instance.
984 */
985static DECLCALLBACK(void) drvR3IntNetPowerOff(PPDMDRVINS pDrvIns)
986{
987 LogFlow(("drvR3IntNetPowerOff\n"));
988 PDRVINTNET pThis = PDMINS_2_DATA(pDrvIns, PDRVINTNET);
989 if (!pThis->fActivateEarlyDeactivateLate)
990 {
991 ASMAtomicXchgSize(&pThis->enmRecvState, RECVSTATE_SUSPENDED);
992 drvR3IntNetSetActive(pThis, false /* fActive */);
993 }
994}
995
996
997/**
998 * drvR3IntNetResume helper.
999 */
1000static int drvR3IntNetResumeSend(PDRVINTNET pThis, const void *pvBuf, size_t cb)
1001{
1002 /*
1003 * Add the frame to the send buffer and push it onto the network.
1004 */
1005 int rc = IntNetRingWriteFrame(&pThis->pBufR3->Send, pvBuf, (uint32_t)cb);
1006 if ( rc == VERR_BUFFER_OVERFLOW
1007 && pThis->pBufR3->cbSend < cb)
1008 {
1009 INTNETIFSENDREQ SendReq;
1010 SendReq.Hdr.u32Magic = SUPVMMR0REQHDR_MAGIC;
1011 SendReq.Hdr.cbReq = sizeof(SendReq);
1012 SendReq.pSession = NIL_RTR0PTR;
1013 SendReq.hIf = pThis->hIf;
1014 PDMDrvHlpSUPCallVMMR0Ex(pThis->pDrvInsR3, VMMR0_DO_INTNET_IF_SEND, &SendReq, sizeof(SendReq));
1015
1016 rc = IntNetRingWriteFrame(&pThis->pBufR3->Send, pvBuf, (uint32_t)cb);
1017 }
1018
1019 if (RT_SUCCESS(rc))
1020 {
1021 INTNETIFSENDREQ SendReq;
1022 SendReq.Hdr.u32Magic = SUPVMMR0REQHDR_MAGIC;
1023 SendReq.Hdr.cbReq = sizeof(SendReq);
1024 SendReq.pSession = NIL_RTR0PTR;
1025 SendReq.hIf = pThis->hIf;
1026 rc = PDMDrvHlpSUPCallVMMR0Ex(pThis->pDrvInsR3, VMMR0_DO_INTNET_IF_SEND, &SendReq, sizeof(SendReq));
1027 }
1028
1029 AssertRC(rc);
1030 return rc;
1031}
1032
1033
1034/**
1035 * Resume notification.
1036 *
1037 * @param pDrvIns The driver instance.
1038 */
1039static DECLCALLBACK(void) drvR3IntNetResume(PPDMDRVINS pDrvIns)
1040{
1041 LogFlow(("drvR3IntNetPowerResume\n"));
1042 PDRVINTNET pThis = PDMINS_2_DATA(pDrvIns, PDRVINTNET);
1043 VMRESUMEREASON enmReason = PDMDrvHlpVMGetResumeReason(pDrvIns);
1044
1045 if (!pThis->fActivateEarlyDeactivateLate)
1046 {
1047 ASMAtomicXchgSize(&pThis->enmRecvState, RECVSTATE_RUNNING);
1048 RTSemEventSignal(pThis->hRecvEvt);
1049 drvR3IntNetUpdateMacAddress(pThis); /* (could be a state restore) */
1050 drvR3IntNetSetActive(pThis, true /* fActive */);
1051 }
1052
1053 switch (enmReason)
1054 {
1055 case VMRESUMEREASON_HOST_RESUME:
1056 {
1057 uint32_t u32TrunkType;
1058 int rc = pDrvIns->pHlpR3->pfnCFGMQueryU32(pDrvIns->pCfg, "TrunkType", &u32TrunkType);
1059 AssertRC(rc);
1060
1061 /*
1062 * Only do the disconnect for bridged networking. Host-only and
1063 * internal networks are not affected by a host resume.
1064 */
1065 if ( RT_SUCCESS(rc)
1066 && u32TrunkType == kIntNetTrunkType_NetFlt)
1067 {
1068 rc = pThis->pIAboveConfigR3->pfnSetLinkState(pThis->pIAboveConfigR3,
1069 PDMNETWORKLINKSTATE_DOWN_RESUME);
1070 AssertRC(rc);
1071 }
1072 break;
1073 }
1074 case VMRESUMEREASON_TELEPORTED:
1075 case VMRESUMEREASON_TELEPORT_FAILED:
1076 {
1077 if ( PDMDrvHlpVMTeleportedAndNotFullyResumedYet(pDrvIns)
1078 && pThis->pIAboveConfigR3)
1079 {
1080 /*
1081 * We've just been teleported and need to drop a hint to the switch
1082 * since we're likely to have changed to a different port. We just
1083 * push out some ethernet frame that doesn't mean anything to anyone.
1084 * For this purpose ethertype 0x801e was chosen since it was registered
1085 * to Sun (dunno what it is/was used for though).
1086 */
1087 union
1088 {
1089 RTNETETHERHDR Hdr;
1090 uint8_t ab[128];
1091 } Frame;
1092 RT_ZERO(Frame);
1093 Frame.Hdr.DstMac.au16[0] = 0xffff;
1094 Frame.Hdr.DstMac.au16[1] = 0xffff;
1095 Frame.Hdr.DstMac.au16[2] = 0xffff;
1096 Frame.Hdr.EtherType = RT_H2BE_U16_C(0x801e);
1097 int rc = pThis->pIAboveConfigR3->pfnGetMac(pThis->pIAboveConfigR3,
1098 &Frame.Hdr.SrcMac);
1099 if (RT_SUCCESS(rc))
1100 rc = drvR3IntNetResumeSend(pThis, &Frame, sizeof(Frame));
1101 if (RT_FAILURE(rc))
1102 LogRel(("IntNet#%u: Sending dummy frame failed: %Rrc\n",
1103 pDrvIns->iInstance, rc));
1104 }
1105 break;
1106 }
1107 default: /* ignore every other resume reason else */
1108 break;
1109 } /* end of switch(enmReason) */
1110}
1111
1112
1113/**
1114 * Suspend notification.
1115 *
1116 * @param pDrvIns The driver instance.
1117 */
1118static DECLCALLBACK(void) drvR3IntNetSuspend(PPDMDRVINS pDrvIns)
1119{
1120 LogFlow(("drvR3IntNetPowerSuspend\n"));
1121 PDRVINTNET pThis = PDMINS_2_DATA(pDrvIns, PDRVINTNET);
1122 if (!pThis->fActivateEarlyDeactivateLate)
1123 {
1124 ASMAtomicXchgSize(&pThis->enmRecvState, RECVSTATE_SUSPENDED);
1125 drvR3IntNetSetActive(pThis, false /* fActive */);
1126 }
1127}
1128
1129
1130/**
1131 * Power On notification.
1132 *
1133 * @param pDrvIns The driver instance.
1134 */
1135static DECLCALLBACK(void) drvR3IntNetPowerOn(PPDMDRVINS pDrvIns)
1136{
1137 LogFlow(("drvR3IntNetPowerOn\n"));
1138 PDRVINTNET pThis = PDMINS_2_DATA(pDrvIns, PDRVINTNET);
1139 if (!pThis->fActivateEarlyDeactivateLate)
1140 {
1141 ASMAtomicXchgSize(&pThis->enmRecvState, RECVSTATE_RUNNING);
1142 RTSemEventSignal(pThis->hRecvEvt);
1143 drvR3IntNetUpdateMacAddress(pThis);
1144 drvR3IntNetSetActive(pThis, true /* fActive */);
1145 }
1146}
1147
1148
1149/**
1150 * @interface_method_impl{PDMDRVREG,pfnRelocate}
1151 */
1152static DECLCALLBACK(void) drvR3IntNetRelocate(PPDMDRVINS pDrvIns, RTGCINTPTR offDelta)
1153{
1154 /* nothing to do here yet */
1155 RT_NOREF(pDrvIns, offDelta);
1156}
1157
1158
1159/**
1160 * Destruct a driver instance.
1161 *
1162 * Most VM resources are freed by the VM. This callback is provided so that any non-VM
1163 * resources can be freed correctly.
1164 *
1165 * @param pDrvIns The driver instance data.
1166 */
1167static DECLCALLBACK(void) drvR3IntNetDestruct(PPDMDRVINS pDrvIns)
1168{
1169 LogFlow(("drvR3IntNetDestruct\n"));
1170 PDRVINTNET pThis = PDMINS_2_DATA(pDrvIns, PDRVINTNET);
1171 PDMDRV_CHECK_VERSIONS_RETURN_VOID(pDrvIns);
1172
1173 /*
1174 * Indicate to the receive thread that it's time to quit.
1175 */
1176 ASMAtomicXchgSize(&pThis->enmRecvState, RECVSTATE_TERMINATE);
1177 ASMAtomicXchgSize(&pThis->fLinkDown, true);
1178 RTSEMEVENT hRecvEvt = pThis->hRecvEvt;
1179 pThis->hRecvEvt = NIL_RTSEMEVENT;
1180
1181 if (hRecvEvt != NIL_RTSEMEVENT)
1182 RTSemEventSignal(hRecvEvt);
1183
1184 if (pThis->hIf != INTNET_HANDLE_INVALID)
1185 {
1186 INTNETIFABORTWAITREQ AbortWaitReq;
1187 AbortWaitReq.Hdr.u32Magic = SUPVMMR0REQHDR_MAGIC;
1188 AbortWaitReq.Hdr.cbReq = sizeof(AbortWaitReq);
1189 AbortWaitReq.pSession = NIL_RTR0PTR;
1190 AbortWaitReq.hIf = pThis->hIf;
1191 AbortWaitReq.fNoMoreWaits = true;
1192 int rc = PDMDrvHlpSUPCallVMMR0Ex(pDrvIns, VMMR0_DO_INTNET_IF_ABORT_WAIT, &AbortWaitReq, sizeof(AbortWaitReq));
1193 AssertMsg(RT_SUCCESS(rc) || rc == VERR_SEM_DESTROYED, ("%Rrc\n", rc)); RT_NOREF_PV(rc);
1194 }
1195
1196 /*
1197 * Wait for the threads to terminate.
1198 */
1199 if (pThis->pXmitThread)
1200 {
1201 int rc = PDMR3ThreadDestroy(pThis->pXmitThread, NULL);
1202 AssertRC(rc);
1203 pThis->pXmitThread = NULL;
1204 }
1205
1206 if (pThis->hRecvThread != NIL_RTTHREAD)
1207 {
1208 int rc = RTThreadWait(pThis->hRecvThread, 5000, NULL);
1209 AssertRC(rc);
1210 pThis->hRecvThread = NIL_RTTHREAD;
1211 }
1212
1213 /*
1214 * Deregister statistics in case we're being detached.
1215 */
1216 if (pThis->pBufR3)
1217 {
1218 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->Recv.cStatFrames);
1219 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->Recv.cbStatWritten);
1220 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->Recv.cOverflows);
1221 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->Send.cStatFrames);
1222 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->Send.cbStatWritten);
1223 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->Send.cOverflows);
1224 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->cStatYieldsOk);
1225 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->cStatYieldsNok);
1226 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->cStatLost);
1227 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->cStatBadFrames);
1228 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->StatSend1);
1229 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->StatSend2);
1230 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->StatRecv1);
1231 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->StatRecv2);
1232 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->pBufR3->StatReserved);
1233 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->StatReceivedGso);
1234 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->StatSentGso);
1235#ifdef VBOX_WITH_STATISTICS
1236 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->StatReceive);
1237 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->StatTransmit);
1238#endif
1239 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->StatXmitWakeupR0);
1240 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->StatXmitWakeupR3);
1241 PDMDrvHlpSTAMDeregister(pDrvIns, &pThis->StatXmitProcessRing);
1242 }
1243
1244 /*
1245 * Close the interface
1246 */
1247 if (pThis->hIf != INTNET_HANDLE_INVALID)
1248 {
1249 INTNETIFCLOSEREQ CloseReq;
1250 CloseReq.Hdr.u32Magic = SUPVMMR0REQHDR_MAGIC;
1251 CloseReq.Hdr.cbReq = sizeof(CloseReq);
1252 CloseReq.pSession = NIL_RTR0PTR;
1253 CloseReq.hIf = pThis->hIf;
1254 pThis->hIf = INTNET_HANDLE_INVALID;
1255 int rc = PDMDrvHlpSUPCallVMMR0Ex(pDrvIns, VMMR0_DO_INTNET_IF_CLOSE, &CloseReq, sizeof(CloseReq));
1256 AssertRC(rc);
1257 }
1258
1259
1260 /*
1261 * Destroy the semaphores, S/G cache and xmit lock.
1262 */
1263 if (hRecvEvt != NIL_RTSEMEVENT)
1264 RTSemEventDestroy(hRecvEvt);
1265
1266 if (pThis->hXmitEvt != NIL_SUPSEMEVENT)
1267 {
1268 SUPSemEventClose(pThis->pSupDrvSession, pThis->hXmitEvt);
1269 pThis->hXmitEvt = NIL_SUPSEMEVENT;
1270 }
1271
1272 RTMemCacheDestroy(pThis->hSgCache);
1273 pThis->hSgCache = NIL_RTMEMCACHE;
1274
1275 if (PDMDrvHlpCritSectIsInitialized(pDrvIns, &pThis->XmitLock))
1276 PDMDrvHlpCritSectDelete(pDrvIns, &pThis->XmitLock);
1277}
1278
1279
1280/**
1281 * Queries a policy config value and translates it into open network flag.
1282 *
1283 * @returns VBox status code (error set on failure).
1284 * @param pDrvIns The driver instance.
1285 * @param pszName The value name.
1286 * @param paFlags The open network flag descriptors.
1287 * @param cFlags The number of descriptors.
1288 * @param fFlags The fixed flag.
1289 * @param pfFlags The flags variable to update.
1290 */
1291static int drvIntNetR3CfgGetPolicy(PPDMDRVINS pDrvIns, const char *pszName, PCDRVINTNETFLAG paFlags, size_t cFlags,
1292 uint32_t fFixedFlag, uint32_t *pfFlags)
1293{
1294 PCPDMDRVHLPR3 pHlp = pDrvIns->pHlpR3;
1295
1296 char szValue[64];
1297 int rc = pHlp->pfnCFGMQueryString(pDrvIns->pCfg, pszName, szValue, sizeof(szValue));
1298 if (RT_FAILURE(rc))
1299 {
1300 if (rc == VERR_CFGM_VALUE_NOT_FOUND)
1301 return VINF_SUCCESS;
1302 return PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS,
1303 N_("Configuration error: Failed to query value of \"%s\""), pszName);
1304 }
1305
1306 /*
1307 * Check for +fixed first, so it can be stripped off.
1308 */
1309 char *pszSep = strpbrk(szValue, "+,;");
1310 if (pszSep)
1311 {
1312 *pszSep++ = '\0';
1313 const char *pszFixed = RTStrStripL(pszSep);
1314 if (strcmp(pszFixed, "fixed"))
1315 {
1316 *pszSep = '+';
1317 return PDMDrvHlpVMSetError(pDrvIns, VERR_INVALID_PARAMETER, RT_SRC_POS,
1318 N_("Configuration error: The value of \"%s\" is unknown: \"%s\""), pszName, szValue);
1319 }
1320 *pfFlags |= fFixedFlag;
1321 RTStrStripR(szValue);
1322 }
1323
1324 /*
1325 * Match against the flag values.
1326 */
1327 size_t i = cFlags;
1328 while (i-- > 0)
1329 if (!strcmp(paFlags[i].pszChoice, szValue))
1330 {
1331 *pfFlags |= paFlags[i].fFlag;
1332 return VINF_SUCCESS;
1333 }
1334
1335 if (!strcmp(szValue, "none"))
1336 return VINF_SUCCESS;
1337
1338 if (!strcmp(szValue, "fixed"))
1339 {
1340 *pfFlags |= fFixedFlag;
1341 return VINF_SUCCESS;
1342 }
1343
1344 return PDMDrvHlpVMSetError(pDrvIns, VERR_INVALID_PARAMETER, RT_SRC_POS,
1345 N_("Configuration error: The value of \"%s\" is unknown: \"%s\""), pszName, szValue);
1346}
1347
1348
1349/**
1350 * Construct a TAP network transport driver instance.
1351 *
1352 * @copydoc FNPDMDRVCONSTRUCT
1353 */
1354static DECLCALLBACK(int) drvR3IntNetConstruct(PPDMDRVINS pDrvIns, PCFGMNODE pCfg, uint32_t fFlags)
1355{
1356 RT_NOREF(fFlags);
1357 PDMDRV_CHECK_VERSIONS_RETURN(pDrvIns);
1358 PDRVINTNET pThis = PDMINS_2_DATA(pDrvIns, PDRVINTNET);
1359 PCPDMDRVHLPR3 pHlp = pDrvIns->pHlpR3;
1360 bool f;
1361
1362 /*
1363 * Init the static parts.
1364 */
1365 pThis->pDrvInsR3 = pDrvIns;
1366#ifdef VBOX_WITH_DRVINTNET_IN_R0
1367 pThis->pDrvInsR0 = PDMDRVINS_2_R0PTR(pDrvIns);
1368#endif
1369 pThis->hIf = INTNET_HANDLE_INVALID;
1370 pThis->hRecvThread = NIL_RTTHREAD;
1371 pThis->hRecvEvt = NIL_RTSEMEVENT;
1372 pThis->pXmitThread = NULL;
1373 pThis->hXmitEvt = NIL_SUPSEMEVENT;
1374 pThis->pSupDrvSession = PDMDrvHlpGetSupDrvSession(pDrvIns);
1375 pThis->hSgCache = NIL_RTMEMCACHE;
1376 pThis->enmRecvState = RECVSTATE_SUSPENDED;
1377 pThis->fActivateEarlyDeactivateLate = false;
1378 /* IBase* */
1379 pDrvIns->IBase.pfnQueryInterface = drvR3IntNetIBase_QueryInterface;
1380 pThis->IBaseR0.pfnQueryInterface = drvR3IntNetIBaseR0_QueryInterface;
1381 pThis->IBaseRC.pfnQueryInterface = drvR3IntNetIBaseRC_QueryInterface;
1382 /* INetworkUp */
1383 pThis->INetworkUpR3.pfnBeginXmit = drvIntNetUp_BeginXmit;
1384 pThis->INetworkUpR3.pfnAllocBuf = drvIntNetUp_AllocBuf;
1385 pThis->INetworkUpR3.pfnFreeBuf = drvIntNetUp_FreeBuf;
1386 pThis->INetworkUpR3.pfnSendBuf = drvIntNetUp_SendBuf;
1387 pThis->INetworkUpR3.pfnEndXmit = drvIntNetUp_EndXmit;
1388 pThis->INetworkUpR3.pfnSetPromiscuousMode = drvIntNetUp_SetPromiscuousMode;
1389 pThis->INetworkUpR3.pfnNotifyLinkChanged = drvR3IntNetUp_NotifyLinkChanged;
1390
1391 /*
1392 * Validate the config.
1393 */
1394 PDMDRV_VALIDATE_CONFIG_RETURN(pDrvIns,
1395 "Network"
1396 "|Trunk"
1397 "|TrunkType"
1398 "|ReceiveBufferSize"
1399 "|SendBufferSize"
1400 "|SharedMacOnWire"
1401 "|RestrictAccess"
1402 "|RequireExactPolicyMatch"
1403 "|RequireAsRestrictivePolicy"
1404 "|AccessPolicy"
1405 "|PromiscPolicyClients"
1406 "|PromiscPolicyHost"
1407 "|PromiscPolicyWire"
1408 "|IfPolicyPromisc"
1409 "|TrunkPolicyHost"
1410 "|TrunkPolicyWire"
1411 "|IsService"
1412 "|IgnoreConnectFailure"
1413 "|Workaround1",
1414 "");
1415
1416 /*
1417 * Check that no-one is attached to us.
1418 */
1419 AssertMsgReturn(PDMDrvHlpNoAttach(pDrvIns) == VERR_PDM_NO_ATTACHED_DRIVER,
1420 ("Configuration error: Not possible to attach anything to this driver!\n"),
1421 VERR_PDM_DRVINS_NO_ATTACH);
1422
1423 /*
1424 * Query the network port interface.
1425 */
1426 pThis->pIAboveNet = PDMIBASE_QUERY_INTERFACE(pDrvIns->pUpBase, PDMINETWORKDOWN);
1427 if (!pThis->pIAboveNet)
1428 {
1429 AssertMsgFailed(("Configuration error: the above device/driver didn't export the network port interface!\n"));
1430 return VERR_PDM_MISSING_INTERFACE_ABOVE;
1431 }
1432 pThis->pIAboveConfigR3 = PDMIBASE_QUERY_INTERFACE(pDrvIns->pUpBase, PDMINETWORKCONFIG);
1433
1434 /*
1435 * Read the configuration.
1436 */
1437 INTNETOPENREQ OpenReq;
1438 RT_ZERO(OpenReq);
1439 OpenReq.Hdr.cbReq = sizeof(OpenReq);
1440 OpenReq.Hdr.u32Magic = SUPVMMR0REQHDR_MAGIC;
1441 OpenReq.pSession = NIL_RTR0PTR;
1442
1443 /** @cfgm{Network, string}
1444 * The name of the internal network to connect to.
1445 */
1446 int rc = pHlp->pfnCFGMQueryString(pCfg, "Network", OpenReq.szNetwork, sizeof(OpenReq.szNetwork));
1447 if (RT_FAILURE(rc))
1448 return PDMDRV_SET_ERROR(pDrvIns, rc,
1449 N_("Configuration error: Failed to get the \"Network\" value"));
1450 strcpy(pThis->szNetwork, OpenReq.szNetwork);
1451
1452 /** @cfgm{TrunkType, uint32_t, kIntNetTrunkType_None}
1453 * The trunk connection type see INTNETTRUNKTYPE.
1454 */
1455 uint32_t u32TrunkType;
1456 rc = pHlp->pfnCFGMQueryU32(pCfg, "TrunkType", &u32TrunkType);
1457 if (rc == VERR_CFGM_VALUE_NOT_FOUND)
1458 u32TrunkType = kIntNetTrunkType_None;
1459 else if (RT_FAILURE(rc))
1460 return PDMDRV_SET_ERROR(pDrvIns, rc,
1461 N_("Configuration error: Failed to get the \"TrunkType\" value"));
1462 OpenReq.enmTrunkType = (INTNETTRUNKTYPE)u32TrunkType;
1463
1464 /** @cfgm{Trunk, string, ""}
1465 * The name of the trunk connection.
1466 */
1467 rc = pHlp->pfnCFGMQueryString(pCfg, "Trunk", OpenReq.szTrunk, sizeof(OpenReq.szTrunk));
1468 if (rc == VERR_CFGM_VALUE_NOT_FOUND)
1469 OpenReq.szTrunk[0] = '\0';
1470 else if (RT_FAILURE(rc))
1471 return PDMDRV_SET_ERROR(pDrvIns, rc,
1472 N_("Configuration error: Failed to get the \"Trunk\" value"));
1473
1474 OpenReq.fFlags = 0;
1475
1476 /** @cfgm{SharedMacOnWire, boolean, false}
1477 * Whether to shared the MAC address of the host interface when using the wire. When
1478 * attaching to a wireless NIC this option is usually a requirement.
1479 */
1480 bool fSharedMacOnWire;
1481 rc = pHlp->pfnCFGMQueryBoolDef(pCfg, "SharedMacOnWire", &fSharedMacOnWire, false);
1482 if (RT_FAILURE(rc))
1483 return PDMDRV_SET_ERROR(pDrvIns, rc,
1484 N_("Configuration error: Failed to get the \"SharedMacOnWire\" value"));
1485 if (fSharedMacOnWire)
1486 OpenReq.fFlags |= INTNET_OPEN_FLAGS_SHARED_MAC_ON_WIRE;
1487
1488 /** @cfgm{RestrictAccess, boolean, true}
1489 * Whether to restrict the access to the network or if it should be public.
1490 * Everyone on the computer can connect to a public network.
1491 * @deprecated Use AccessPolicy instead.
1492 */
1493 rc = pHlp->pfnCFGMQueryBool(pCfg, "RestrictAccess", &f);
1494 if (RT_SUCCESS(rc))
1495 {
1496 if (f)
1497 OpenReq.fFlags |= INTNET_OPEN_FLAGS_ACCESS_RESTRICTED;
1498 else
1499 OpenReq.fFlags |= INTNET_OPEN_FLAGS_ACCESS_PUBLIC;
1500 OpenReq.fFlags |= INTNET_OPEN_FLAGS_ACCESS_FIXED;
1501 }
1502 else if (rc != VERR_CFGM_VALUE_NOT_FOUND)
1503 return PDMDRV_SET_ERROR(pDrvIns, rc,
1504 N_("Configuration error: Failed to get the \"RestrictAccess\" value"));
1505
1506 /** @cfgm{RequireExactPolicyMatch, boolean, false}
1507 * Whether to require that the current security and promiscuous policies of
1508 * the network is exactly as the ones specified in this open network
1509 * request. Use this with RequireAsRestrictivePolicy to prevent
1510 * restrictions from being lifted. If no further policy changes are
1511 * desired, apply the relevant fixed flags. */
1512 rc = pHlp->pfnCFGMQueryBoolDef(pCfg, "RequireExactPolicyMatch", &f, false);
1513 if (RT_FAILURE(rc))
1514 return PDMDRV_SET_ERROR(pDrvIns, rc,
1515 N_("Configuration error: Failed to get the \"RequireExactPolicyMatch\" value"));
1516 if (f)
1517 OpenReq.fFlags |= INTNET_OPEN_FLAGS_REQUIRE_EXACT;
1518
1519 /** @cfgm{RequireAsRestrictivePolicy, boolean, false}
1520 * Whether to require that the security and promiscuous policies of the
1521 * network is at least as restrictive as specified this request specifies
1522 * and prevent them being lifted later on.
1523 */
1524 rc = pHlp->pfnCFGMQueryBoolDef(pCfg, "RequireAsRestrictivePolicy", &f, false);
1525 if (RT_FAILURE(rc))
1526 return PDMDRV_SET_ERROR(pDrvIns, rc,
1527 N_("Configuration error: Failed to get the \"RequireAsRestrictivePolicy\" value"));
1528 if (f)
1529 OpenReq.fFlags |= INTNET_OPEN_FLAGS_REQUIRE_AS_RESTRICTIVE_POLICIES;
1530
1531 /** @cfgm{AccessPolicy, string, "none"}
1532 * The access policy of the network:
1533 * public, public+fixed, restricted, restricted+fixed, none or fixed.
1534 *
1535 * A "public" network is accessible to everyone on the same host, while a
1536 * "restricted" one is only accessible to VMs & services started by the
1537 * same user. The "none" policy, which is the default, means no policy
1538 * change or choice is made and that the current (existing network) or
1539 * default (new) policy should be used. */
1540 static const DRVINTNETFLAG s_aAccessPolicyFlags[] =
1541 {
1542 { "public", INTNET_OPEN_FLAGS_ACCESS_PUBLIC },
1543 { "restricted", INTNET_OPEN_FLAGS_ACCESS_RESTRICTED }
1544 };
1545 rc = drvIntNetR3CfgGetPolicy(pDrvIns, "AccessPolicy", &s_aAccessPolicyFlags[0], RT_ELEMENTS(s_aAccessPolicyFlags),
1546 INTNET_OPEN_FLAGS_ACCESS_FIXED, &OpenReq.fFlags);
1547 AssertRCReturn(rc, rc);
1548
1549 /** @cfgm{PromiscPolicyClients, string, "none"}
1550 * The network wide promiscuous mode policy for client (non-trunk)
1551 * interfaces: allow, allow+fixed, deny, deny+fixed, none or fixed. */
1552 static const DRVINTNETFLAG s_aPromiscPolicyClient[] =
1553 {
1554 { "allow", INTNET_OPEN_FLAGS_PROMISC_ALLOW_CLIENTS },
1555 { "deny", INTNET_OPEN_FLAGS_PROMISC_DENY_CLIENTS }
1556 };
1557 rc = drvIntNetR3CfgGetPolicy(pDrvIns, "PromiscPolicyClients", &s_aPromiscPolicyClient[0], RT_ELEMENTS(s_aPromiscPolicyClient),
1558 INTNET_OPEN_FLAGS_PROMISC_FIXED, &OpenReq.fFlags);
1559 AssertRCReturn(rc, rc);
1560 /** @cfgm{PromiscPolicyHost, string, "none"}
1561 * The promiscuous mode policy for the trunk-host
1562 * connection: allow, allow+fixed, deny, deny+fixed, none or fixed. */
1563 static const DRVINTNETFLAG s_aPromiscPolicyHost[] =
1564 {
1565 { "allow", INTNET_OPEN_FLAGS_PROMISC_ALLOW_TRUNK_HOST },
1566 { "deny", INTNET_OPEN_FLAGS_PROMISC_DENY_TRUNK_HOST }
1567 };
1568 rc = drvIntNetR3CfgGetPolicy(pDrvIns, "PromiscPolicyHost", &s_aPromiscPolicyHost[0], RT_ELEMENTS(s_aPromiscPolicyHost),
1569 INTNET_OPEN_FLAGS_PROMISC_FIXED, &OpenReq.fFlags);
1570 AssertRCReturn(rc, rc);
1571 /** @cfgm{PromiscPolicyWire, string, "none"}
1572 * The promiscuous mode policy for the trunk-host
1573 * connection: allow, allow+fixed, deny, deny+fixed, none or fixed. */
1574 static const DRVINTNETFLAG s_aPromiscPolicyWire[] =
1575 {
1576 { "allow", INTNET_OPEN_FLAGS_PROMISC_ALLOW_TRUNK_WIRE },
1577 { "deny", INTNET_OPEN_FLAGS_PROMISC_DENY_TRUNK_WIRE }
1578 };
1579 rc = drvIntNetR3CfgGetPolicy(pDrvIns, "PromiscPolicyWire", &s_aPromiscPolicyWire[0], RT_ELEMENTS(s_aPromiscPolicyWire),
1580 INTNET_OPEN_FLAGS_PROMISC_FIXED, &OpenReq.fFlags);
1581 AssertRCReturn(rc, rc);
1582
1583
1584 /** @cfgm{IfPolicyPromisc, string, "none"}
1585 * The promiscuous mode policy for this
1586 * interface: deny, deny+fixed, allow-all, allow-all+fixed, allow-network,
1587 * allow-network+fixed, none or fixed. */
1588 static const DRVINTNETFLAG s_aIfPolicyPromisc[] =
1589 {
1590 { "allow-all", INTNET_OPEN_FLAGS_IF_PROMISC_ALLOW | INTNET_OPEN_FLAGS_IF_PROMISC_SEE_TRUNK },
1591 { "allow-network", INTNET_OPEN_FLAGS_IF_PROMISC_ALLOW | INTNET_OPEN_FLAGS_IF_PROMISC_NO_TRUNK },
1592 { "deny", INTNET_OPEN_FLAGS_IF_PROMISC_DENY }
1593 };
1594 rc = drvIntNetR3CfgGetPolicy(pDrvIns, "IfPolicyPromisc", &s_aIfPolicyPromisc[0], RT_ELEMENTS(s_aIfPolicyPromisc),
1595 INTNET_OPEN_FLAGS_IF_FIXED, &OpenReq.fFlags);
1596 AssertRCReturn(rc, rc);
1597
1598
1599 /** @cfgm{TrunkPolicyHost, string, "none"}
1600 * The trunk-host policy: promisc, promisc+fixed, enabled, enabled+fixed,
1601 * disabled, disabled+fixed, none or fixed
1602 *
1603 * This can be used to prevent packages to be routed to the host. */
1604 static const DRVINTNETFLAG s_aTrunkPolicyHost[] =
1605 {
1606 { "promisc", INTNET_OPEN_FLAGS_TRUNK_HOST_ENABLED | INTNET_OPEN_FLAGS_TRUNK_HOST_PROMISC_MODE },
1607 { "enabled", INTNET_OPEN_FLAGS_TRUNK_HOST_ENABLED },
1608 { "disabled", INTNET_OPEN_FLAGS_TRUNK_HOST_DISABLED }
1609 };
1610 rc = drvIntNetR3CfgGetPolicy(pDrvIns, "TrunkPolicyHost", &s_aTrunkPolicyHost[0], RT_ELEMENTS(s_aTrunkPolicyHost),
1611 INTNET_OPEN_FLAGS_TRUNK_FIXED, &OpenReq.fFlags);
1612 AssertRCReturn(rc, rc);
1613 /** @cfgm{TrunkPolicyWire, string, "none"}
1614 * The trunk-host policy: promisc, promisc+fixed, enabled, enabled+fixed,
1615 * disabled, disabled+fixed, none or fixed.
1616 *
1617 * This can be used to prevent packages to be routed to the wire. */
1618 static const DRVINTNETFLAG s_aTrunkPolicyWire[] =
1619 {
1620 { "promisc", INTNET_OPEN_FLAGS_TRUNK_WIRE_ENABLED | INTNET_OPEN_FLAGS_TRUNK_WIRE_PROMISC_MODE },
1621 { "enabled", INTNET_OPEN_FLAGS_TRUNK_WIRE_ENABLED },
1622 { "disabled", INTNET_OPEN_FLAGS_TRUNK_WIRE_DISABLED }
1623 };
1624 rc = drvIntNetR3CfgGetPolicy(pDrvIns, "TrunkPolicyWire", &s_aTrunkPolicyWire[0], RT_ELEMENTS(s_aTrunkPolicyWire),
1625 INTNET_OPEN_FLAGS_TRUNK_FIXED, &OpenReq.fFlags);
1626 AssertRCReturn(rc, rc);
1627
1628
1629 /** @cfgm{ReceiveBufferSize, uint32_t, 318 KB}
1630 * The size of the receive buffer.
1631 */
1632 rc = pHlp->pfnCFGMQueryU32(pCfg, "ReceiveBufferSize", &OpenReq.cbRecv);
1633 if (rc == VERR_CFGM_VALUE_NOT_FOUND)
1634 OpenReq.cbRecv = 318 * _1K ;
1635 else if (RT_FAILURE(rc))
1636 return PDMDRV_SET_ERROR(pDrvIns, rc,
1637 N_("Configuration error: Failed to get the \"ReceiveBufferSize\" value"));
1638
1639 /** @cfgm{SendBufferSize, uint32_t, 196 KB}
1640 * The size of the send (transmit) buffer.
1641 * This should be more than twice the size of the larges frame size because
1642 * the ring buffer is very simple and doesn't support splitting up frames
1643 * nor inserting padding. So, if this is too close to the frame size the
1644 * header will fragment the buffer such that the frame won't fit on either
1645 * side of it and the code will get very upset about it all.
1646 */
1647 rc = pHlp->pfnCFGMQueryU32(pCfg, "SendBufferSize", &OpenReq.cbSend);
1648 if (rc == VERR_CFGM_VALUE_NOT_FOUND)
1649 OpenReq.cbSend = RT_ALIGN_Z(VBOX_MAX_GSO_SIZE * 3, _1K);
1650 else if (RT_FAILURE(rc))
1651 return PDMDRV_SET_ERROR(pDrvIns, rc,
1652 N_("Configuration error: Failed to get the \"SendBufferSize\" value"));
1653 if (OpenReq.cbSend < 128)
1654 return PDMDRV_SET_ERROR(pDrvIns, rc,
1655 N_("Configuration error: The \"SendBufferSize\" value is too small"));
1656 if (OpenReq.cbSend < VBOX_MAX_GSO_SIZE * 3)
1657 LogRel(("DrvIntNet: Warning! SendBufferSize=%u, Recommended minimum size %u butes.\n", OpenReq.cbSend, VBOX_MAX_GSO_SIZE * 4));
1658
1659 /** @cfgm{IsService, boolean, true}
1660 * This alterns the way the thread is suspended and resumed. When it's being used by
1661 * a service such as LWIP/iSCSI it shouldn't suspend immediately like for a NIC.
1662 */
1663 rc = pHlp->pfnCFGMQueryBool(pCfg, "IsService", &pThis->fActivateEarlyDeactivateLate);
1664 if (rc == VERR_CFGM_VALUE_NOT_FOUND)
1665 pThis->fActivateEarlyDeactivateLate = false;
1666 else if (RT_FAILURE(rc))
1667 return PDMDRV_SET_ERROR(pDrvIns, rc,
1668 N_("Configuration error: Failed to get the \"IsService\" value"));
1669
1670
1671 /** @cfgm{IgnoreConnectFailure, boolean, false}
1672 * When set only raise a runtime error if we cannot connect to the internal
1673 * network. */
1674 bool fIgnoreConnectFailure;
1675 rc = pHlp->pfnCFGMQueryBoolDef(pCfg, "IgnoreConnectFailure", &fIgnoreConnectFailure, false);
1676 if (RT_FAILURE(rc))
1677 return PDMDRV_SET_ERROR(pDrvIns, rc,
1678 N_("Configuration error: Failed to get the \"IgnoreConnectFailure\" value"));
1679
1680 /** @cfgm{Workaround1, boolean, depends}
1681 * Enables host specific workarounds, the default is depends on the whether
1682 * we think the host requires it or not.
1683 */
1684 bool fWorkaround1 = false;
1685#ifdef RT_OS_DARWIN
1686 if (OpenReq.fFlags & INTNET_OPEN_FLAGS_SHARED_MAC_ON_WIRE)
1687 {
1688 char szKrnlVer[256];
1689 RTSystemQueryOSInfo(RTSYSOSINFO_RELEASE, szKrnlVer, sizeof(szKrnlVer));
1690 if (strcmp(szKrnlVer, "10.7.0") >= 0)
1691 {
1692 LogRel(("IntNet#%u: Enables the workaround (ip_tos=0) for the little endian ip header checksum problem\n"));
1693 fWorkaround1 = true;
1694 }
1695 }
1696#endif
1697 rc = pHlp->pfnCFGMQueryBoolDef(pCfg, "Workaround1", &fWorkaround1, fWorkaround1);
1698 if (RT_FAILURE(rc))
1699 return PDMDRV_SET_ERROR(pDrvIns, rc,
1700 N_("Configuration error: Failed to get the \"Workaround1\" value"));
1701 if (fWorkaround1)
1702 OpenReq.fFlags |= INTNET_OPEN_FLAGS_WORKAROUND_1;
1703
1704 LogRel(("IntNet#%u: szNetwork={%s} enmTrunkType=%d szTrunk={%s} fFlags=%#x cbRecv=%u cbSend=%u fIgnoreConnectFailure=%RTbool\n",
1705 pDrvIns->iInstance, OpenReq.szNetwork, OpenReq.enmTrunkType, OpenReq.szTrunk, OpenReq.fFlags,
1706 OpenReq.cbRecv, OpenReq.cbSend, fIgnoreConnectFailure));
1707
1708#ifdef RT_OS_DARWIN
1709 /* Temporary hack: attach to a network with the name 'if=en0' and you're hitting the wire. */
1710 if ( !OpenReq.szTrunk[0]
1711 && OpenReq.enmTrunkType == kIntNetTrunkType_None
1712 && !strncmp(pThis->szNetwork, RT_STR_TUPLE("if=en"))
1713 && RT_C_IS_DIGIT(pThis->szNetwork[sizeof("if=en") - 1])
1714 && !pThis->szNetwork[sizeof("if=en")])
1715 {
1716 OpenReq.enmTrunkType = kIntNetTrunkType_NetFlt;
1717 strcpy(OpenReq.szTrunk, &pThis->szNetwork[sizeof("if=") - 1]);
1718 }
1719 /* Temporary hack: attach to a network with the name 'wif=en0' and you're on the air. */
1720 if ( !OpenReq.szTrunk[0]
1721 && OpenReq.enmTrunkType == kIntNetTrunkType_None
1722 && !strncmp(pThis->szNetwork, RT_STR_TUPLE("wif=en"))
1723 && RT_C_IS_DIGIT(pThis->szNetwork[sizeof("wif=en") - 1])
1724 && !pThis->szNetwork[sizeof("wif=en")])
1725 {
1726 OpenReq.enmTrunkType = kIntNetTrunkType_NetFlt;
1727 OpenReq.fFlags |= INTNET_OPEN_FLAGS_SHARED_MAC_ON_WIRE;
1728 strcpy(OpenReq.szTrunk, &pThis->szNetwork[sizeof("wif=") - 1]);
1729 }
1730#endif /* DARWIN */
1731
1732 /*
1733 * Create the event semaphore, S/G cache and xmit critsect.
1734 */
1735 rc = RTSemEventCreate(&pThis->hRecvEvt);
1736 if (RT_FAILURE(rc))
1737 return rc;
1738 rc = RTMemCacheCreate(&pThis->hSgCache, sizeof(PDMSCATTERGATHER), 0, UINT32_MAX, NULL, NULL, pThis, 0);
1739 if (RT_FAILURE(rc))
1740 return rc;
1741 rc = PDMDrvHlpCritSectInit(pDrvIns, &pThis->XmitLock, RT_SRC_POS, "IntNetXmit");
1742 if (RT_FAILURE(rc))
1743 return rc;
1744
1745 /*
1746 * Create the interface.
1747 */
1748 OpenReq.hIf = INTNET_HANDLE_INVALID;
1749 rc = PDMDrvHlpSUPCallVMMR0Ex(pDrvIns, VMMR0_DO_INTNET_OPEN, &OpenReq, sizeof(OpenReq));
1750 if (RT_FAILURE(rc))
1751 {
1752 if (fIgnoreConnectFailure)
1753 {
1754 /*
1755 * During VM restore it is fatal if the network is not available because the
1756 * VM settings are locked and the user has no chance to fix network settings.
1757 * Therefore don't abort but just raise a runtime warning.
1758 */
1759 PDMDrvHlpVMSetRuntimeError(pDrvIns, 0 /*fFlags*/, "HostIfNotConnecting",
1760 N_ ("Cannot connect to the network interface '%s'. The virtual "
1761 "network card will appear to work but the guest will not "
1762 "be able to connect. Please choose a different network in the "
1763 "network settings"), OpenReq.szTrunk);
1764
1765 return VERR_PDM_NO_ATTACHED_DRIVER;
1766 }
1767 return PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS,
1768 N_("Failed to open/create the internal network '%s'"), pThis->szNetwork);
1769 }
1770
1771 AssertRelease(OpenReq.hIf != INTNET_HANDLE_INVALID);
1772 pThis->hIf = OpenReq.hIf;
1773 Log(("IntNet%d: hIf=%RX32 '%s'\n", pDrvIns->iInstance, pThis->hIf, pThis->szNetwork));
1774
1775 /*
1776 * Get default buffer.
1777 */
1778 INTNETIFGETBUFFERPTRSREQ GetBufferPtrsReq;
1779 GetBufferPtrsReq.Hdr.u32Magic = SUPVMMR0REQHDR_MAGIC;
1780 GetBufferPtrsReq.Hdr.cbReq = sizeof(GetBufferPtrsReq);
1781 GetBufferPtrsReq.pSession = NIL_RTR0PTR;
1782 GetBufferPtrsReq.hIf = pThis->hIf;
1783 GetBufferPtrsReq.pRing3Buf = NULL;
1784 GetBufferPtrsReq.pRing0Buf = NIL_RTR0PTR;
1785 rc = PDMDrvHlpSUPCallVMMR0Ex(pDrvIns, VMMR0_DO_INTNET_IF_GET_BUFFER_PTRS, &GetBufferPtrsReq, sizeof(GetBufferPtrsReq));
1786 if (RT_FAILURE(rc))
1787 return PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS,
1788 N_("Failed to get ring-3 buffer for the newly created interface to '%s'"), pThis->szNetwork);
1789 AssertRelease(RT_VALID_PTR(GetBufferPtrsReq.pRing3Buf));
1790 pThis->pBufR3 = GetBufferPtrsReq.pRing3Buf;
1791 pThis->pBufR0 = GetBufferPtrsReq.pRing0Buf;
1792
1793 /*
1794 * Register statistics.
1795 */
1796 PDMDrvHlpSTAMRegCounterEx(pDrvIns, &pThis->pBufR3->Recv.cbStatWritten, "Bytes/Received", STAMUNIT_BYTES, "Number of received bytes.");
1797 PDMDrvHlpSTAMRegCounterEx(pDrvIns, &pThis->pBufR3->Send.cbStatWritten, "Bytes/Sent", STAMUNIT_BYTES, "Number of sent bytes.");
1798 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->pBufR3->Recv.cOverflows, "Overflows/Recv", "Number overflows.");
1799 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->pBufR3->Send.cOverflows, "Overflows/Sent", "Number overflows.");
1800 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->pBufR3->Recv.cStatFrames, "Packets/Received", "Number of received packets.");
1801 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->pBufR3->Send.cStatFrames, "Packets/Sent", "Number of sent packets.");
1802 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->StatReceivedGso, "Packets/Received-Gso", "The GSO portion of the received packets.");
1803 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->StatSentGso, "Packets/Sent-Gso", "The GSO portion of the sent packets.");
1804 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->StatSentR0, "Packets/Sent-R0", "The ring-0 portion of the sent packets.");
1805
1806 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->pBufR3->cStatLost, "Packets/Lost", "Number of lost packets.");
1807 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->pBufR3->cStatYieldsNok, "YieldOk", "Number of times yielding helped fix an overflow.");
1808 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->pBufR3->cStatYieldsOk, "YieldNok", "Number of times yielding didn't help fix an overflow.");
1809 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->pBufR3->cStatBadFrames, "BadFrames", "Number of bad frames seed by the consumers.");
1810 PDMDrvHlpSTAMRegProfile(pDrvIns, &pThis->pBufR3->StatSend1, "Send1", "Profiling IntNetR0IfSend.");
1811 PDMDrvHlpSTAMRegProfile(pDrvIns, &pThis->pBufR3->StatSend2, "Send2", "Profiling sending to the trunk.");
1812 PDMDrvHlpSTAMRegProfile(pDrvIns, &pThis->pBufR3->StatRecv1, "Recv1", "Reserved for future receive profiling.");
1813 PDMDrvHlpSTAMRegProfile(pDrvIns, &pThis->pBufR3->StatRecv2, "Recv2", "Reserved for future receive profiling.");
1814 PDMDrvHlpSTAMRegProfile(pDrvIns, &pThis->pBufR3->StatReserved, "Reserved", "Reserved for future use.");
1815#ifdef VBOX_WITH_STATISTICS
1816 PDMDrvHlpSTAMRegProfileAdv(pDrvIns, &pThis->StatReceive, "Receive", "Profiling packet receive runs.");
1817 PDMDrvHlpSTAMRegProfile(pDrvIns, &pThis->StatTransmit, "Transmit", "Profiling packet transmit runs.");
1818#endif
1819 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->StatXmitWakeupR0, "XmitWakeup-R0", "Xmit thread wakeups from ring-0.");
1820 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->StatXmitWakeupR3, "XmitWakeup-R3", "Xmit thread wakeups from ring-3.");
1821 PDMDrvHlpSTAMRegCounter(pDrvIns, &pThis->StatXmitProcessRing, "XmitProcessRing", "Time xmit thread was told to process the ring.");
1822
1823 /*
1824 * Create the async I/O threads.
1825 * Note! Using a PDM thread here doesn't fit with the IsService=true operation.
1826 */
1827 rc = RTThreadCreate(&pThis->hRecvThread, drvR3IntNetRecvThread, pThis, 0,
1828 RTTHREADTYPE_IO, RTTHREADFLAGS_WAITABLE, "INTNET-RECV");
1829 if (RT_FAILURE(rc))
1830 {
1831 AssertRC(rc);
1832 return rc;
1833 }
1834
1835 rc = SUPSemEventCreate(pThis->pSupDrvSession, &pThis->hXmitEvt);
1836 AssertRCReturn(rc, rc);
1837
1838 rc = PDMDrvHlpThreadCreate(pDrvIns, &pThis->pXmitThread, pThis,
1839 drvR3IntNetXmitThread, drvR3IntNetXmitWakeUp, 0, RTTHREADTYPE_IO, "INTNET-XMIT");
1840 AssertRCReturn(rc, rc);
1841
1842#ifdef VBOX_WITH_DRVINTNET_IN_R0
1843 /*
1844 * Resolve the ring-0 context interface addresses.
1845 */
1846 rc = pDrvIns->pHlpR3->pfnLdrGetR0InterfaceSymbols(pDrvIns, &pThis->INetworkUpR0, sizeof(pThis->INetworkUpR0),
1847 "drvIntNetUp_", PDMINETWORKUP_SYM_LIST);
1848 AssertLogRelRCReturn(rc, rc);
1849#endif
1850
1851 /*
1852 * Activate data transmission as early as possible
1853 */
1854 if (pThis->fActivateEarlyDeactivateLate)
1855 {
1856 ASMAtomicXchgSize(&pThis->enmRecvState, RECVSTATE_RUNNING);
1857 RTSemEventSignal(pThis->hRecvEvt);
1858
1859 drvR3IntNetUpdateMacAddress(pThis);
1860 drvR3IntNetSetActive(pThis, true /* fActive */);
1861 }
1862
1863 return rc;
1864}
1865
1866
1867
1868/**
1869 * Internal networking transport driver registration record.
1870 */
1871const PDMDRVREG g_DrvIntNet =
1872{
1873 /* u32Version */
1874 PDM_DRVREG_VERSION,
1875 /* szName */
1876 "IntNet",
1877 /* szRCMod */
1878 "VBoxDDRC.rc",
1879 /* szR0Mod */
1880 "VBoxDDR0.r0",
1881 /* pszDescription */
1882 "Internal Networking Transport Driver",
1883 /* fFlags */
1884#ifdef VBOX_WITH_DRVINTNET_IN_R0
1885 PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT | PDM_DRVREG_FLAGS_R0,
1886#else
1887 PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT,
1888#endif
1889 /* fClass. */
1890 PDM_DRVREG_CLASS_NETWORK,
1891 /* cMaxInstances */
1892 ~0U,
1893 /* cbInstance */
1894 sizeof(DRVINTNET),
1895 /* pfnConstruct */
1896 drvR3IntNetConstruct,
1897 /* pfnDestruct */
1898 drvR3IntNetDestruct,
1899 /* pfnRelocate */
1900 drvR3IntNetRelocate,
1901 /* pfnIOCtl */
1902 NULL,
1903 /* pfnPowerOn */
1904 drvR3IntNetPowerOn,
1905 /* pfnReset */
1906 NULL,
1907 /* pfnSuspend */
1908 drvR3IntNetSuspend,
1909 /* pfnResume */
1910 drvR3IntNetResume,
1911 /* pfnAttach */
1912 NULL,
1913 /* pfnDetach */
1914 NULL,
1915 /* pfnPowerOff */
1916 drvR3IntNetPowerOff,
1917 /* pfnSoftReset */
1918 NULL,
1919 /* u32EndVersion */
1920 PDM_DRVREG_VERSION
1921};
1922
1923#endif /* IN_RING3 */
1924
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette