VirtualBox

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

Last change on this file since 29567 was 29493, checked in by vboxsync, 15 years ago

Build fix.

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