VirtualBox

source: vbox/trunk/src/VBox/HostDrivers/VBoxUSB/darwin/VBoxUSB.cpp@ 51488

Last change on this file since 51488 was 51488, checked in by vboxsync, 10 years ago

Experiment. Require special cookie to be served to VBoxDrv and VBoxUSB with IOServiceOpen.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 60.1 KB
Line 
1/* $Id: VBoxUSB.cpp 51488 2014-06-02 14:46:50Z vboxsync $ */
2/** @file
3 * VirtualBox USB driver for Darwin.
4 *
5 * This driver is responsible for hijacking USB devices when any of the
6 * VBoxSVC daemons requests it. It is also responsible for arbitrating
7 * access to hijacked USB devices.
8 */
9
10/*
11 * Copyright (C) 2006-2013 Oracle Corporation
12 *
13 * This file is part of VirtualBox Open Source Edition (OSE), as
14 * available from http://www.virtualbox.org. This file is free software;
15 * you can redistribute it and/or modify it under the terms of the GNU
16 * General Public License (GPL) as published by the Free Software
17 * Foundation, in version 2 as it comes in the "COPYING" file of the
18 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
19 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
20 */
21
22
23/*******************************************************************************
24* Header Files *
25*******************************************************************************/
26#define LOG_GROUP LOG_GROUP_USB_DRV
27/* Deal with conflicts first.
28 * (This is mess inherited from BSD. The *BSDs has clean this up long ago.) */
29#include <sys/param.h>
30#undef PVM
31#include <IOKit/IOLib.h> /* Assert as function */
32
33#include "VBoxUSBInterface.h"
34#include "VBoxUSBFilterMgr.h"
35#include <VBox/version.h>
36#include <VBox/usblib-darwin.h>
37#include <VBox/log.h>
38#include <iprt/types.h>
39#include <iprt/initterm.h>
40#include <iprt/assert.h>
41#include <iprt/semaphore.h>
42#include <iprt/process.h>
43#include <iprt/alloc.h>
44#include <iprt/err.h>
45#include <iprt/asm.h>
46
47#include <mach/kmod.h>
48#include <miscfs/devfs/devfs.h>
49#include <sys/conf.h>
50#include <sys/errno.h>
51#include <sys/ioccom.h>
52#include <sys/malloc.h>
53#include <sys/proc.h>
54#include <kern/task.h>
55#include <IOKit/IOService.h>
56#include <IOKit/IOUserClient.h>
57#include <IOKit/IOKitKeys.h>
58#include <IOKit/usb/USB.h>
59#include <IOKit/usb/IOUSBDevice.h>
60#include <IOKit/usb/IOUSBInterface.h>
61#include <IOKit/usb/IOUSBUserClient.h>
62
63/* private: */
64RT_C_DECLS_BEGIN
65extern void *get_bsdtask_info(task_t);
66RT_C_DECLS_END
67
68
69/*******************************************************************************
70* Defined Constants And Macros *
71*******************************************************************************/
72/** Locks the lists. */
73#define VBOXUSB_LOCK() do { int rc = RTSemFastMutexRequest(g_Mtx); AssertRC(rc); } while (0)
74/** Unlocks the lists. */
75#define VBOXUSB_UNLOCK() do { int rc = RTSemFastMutexRelease(g_Mtx); AssertRC(rc); } while (0)
76
77
78/*******************************************************************************
79* Internal Functions *
80*******************************************************************************/
81RT_C_DECLS_BEGIN
82static kern_return_t VBoxUSBStart(struct kmod_info *pKModInfo, void *pvData);
83static kern_return_t VBoxUSBStop(struct kmod_info *pKModInfo, void *pvData);
84RT_C_DECLS_END
85
86
87/*******************************************************************************
88* Structures and Typedefs *
89*******************************************************************************/
90/**
91 * The service class.
92 *
93 * This is the management service that VBoxSVC and the VMs speak to.
94 *
95 * @remark The method prototypes are ordered somewhat after their order of
96 * invocation, while the implementation is ordered by pair.
97 */
98class org_virtualbox_VBoxUSB : public IOService
99{
100 OSDeclareDefaultStructors(org_virtualbox_VBoxUSB);
101
102public:
103 /** @name IOService
104 * @{ */
105 virtual bool init(OSDictionary *pDictionary = 0);
106 virtual bool start(IOService *pProvider);
107 virtual bool open(IOService *pForClient, IOOptionBits fOptions = 0, void *pvArg = 0);
108 virtual bool terminate(IOOptionBits fOptions);
109 virtual void close(IOService *pForClient, IOOptionBits fOptions = 0);
110 virtual void stop(IOService *pProvider);
111 virtual void free();
112 /** @} */
113};
114OSDefineMetaClassAndStructors(org_virtualbox_VBoxUSB, IOService);
115
116
117/**
118 * The user client class that pairs up with org_virtualbox_VBoxUSB.
119 */
120class org_virtualbox_VBoxUSBClient : public IOUserClient
121{
122 OSDeclareDefaultStructors(org_virtualbox_VBoxUSBClient);
123
124public:
125 /** @name IOService & IOUserClient
126 * @{ */
127 virtual bool initWithTask(task_t OwningTask, void *pvSecurityId, UInt32 u32Type);
128 virtual bool start(IOService *pProvider);
129 virtual IOReturn clientClose(void);
130 virtual IOReturn clientDied(void);
131 virtual bool terminate(IOOptionBits fOptions = 0);
132 virtual bool finalize(IOOptionBits fOptions);
133 virtual void stop(IOService *pProvider);
134 virtual void free();
135 virtual IOExternalMethod *getTargetAndMethodForIndex(IOService **ppService, UInt32 iMethod);
136 /** @} */
137
138 /** @name User client methods
139 * @{ */
140 IOReturn addFilter(PUSBFILTER pFilter, PVBOXUSBADDFILTEROUT pOut, IOByteCount cbFilter, IOByteCount *pcbOut);
141 IOReturn removeFilter(uintptr_t *puId, int *prc, IOByteCount cbIn, IOByteCount *pcbOut);
142 /** @} */
143
144 static bool isClientTask(task_t ClientTask);
145
146private:
147 /** The service provider. */
148 org_virtualbox_VBoxUSB *m_pProvider;
149 /** The client task. */
150 task_t m_Task;
151 /** The client process. */
152 RTPROCESS m_Process;
153 /** Pointer to the next user client. */
154 org_virtualbox_VBoxUSBClient * volatile m_pNext;
155 /** List of user clients. Protected by g_Mtx. */
156 static org_virtualbox_VBoxUSBClient * volatile s_pHead;
157};
158OSDefineMetaClassAndStructors(org_virtualbox_VBoxUSBClient, IOUserClient);
159
160
161/**
162 * The IOUSBDevice driver class.
163 *
164 * The main purpose of this is hijack devices matching current filters.
165 *
166 * @remarks This is derived from IOUSBUserClientInit instead of IOService because we must make
167 * sure IOUSBUserClientInit::start() gets invoked for this provider. The problem is that
168 * there is some kind of magic that prevents this from happening if we boost the probe
169 * score to high. With the result that we don't have the required plugin entry for
170 * user land and consequently cannot open it.
171 *
172 * So, to avoid having to write a lot of code we just inherit from IOUSBUserClientInit
173 * and make some possibly bold assumptions about it not changing. This just means
174 * we'll have to keep an eye on the source apple releases or only call
175 * IOUSBUserClientInit::start() and hand the rest of the super calls to IOService. For
176 * now we're doing it by the C++ book.
177 */
178class org_virtualbox_VBoxUSBDevice : public IOUSBUserClientInit
179{
180 OSDeclareDefaultStructors(org_virtualbox_VBoxUSBDevice);
181
182public:
183 /** @name IOService
184 * @{ */
185 virtual bool init(OSDictionary *pDictionary = 0);
186 virtual IOService *probe(IOService *pProvider, SInt32 *pi32Score);
187 virtual bool start(IOService *pProvider);
188 virtual bool terminate(IOOptionBits fOptions = 0);
189 virtual void stop(IOService *pProvider);
190 virtual void free();
191 virtual IOReturn message(UInt32 enmMsg, IOService *pProvider, void *pvArg = 0);
192 /** @} */
193
194 static void scheduleReleaseByOwner(RTPROCESS Owner);
195private:
196 /** The interface we're driving (aka. the provider). */
197 IOUSBDevice *m_pDevice;
198 /** The owner process, meaning the VBoxSVC process. */
199 RTPROCESS volatile m_Owner;
200 /** The client process, meaning the VM process. */
201 RTPROCESS volatile m_Client;
202 /** The ID of the matching filter. */
203 uintptr_t m_uId;
204 /** Have we opened the device or not? */
205 bool volatile m_fOpen;
206 /** Should be open the device on the next close notification message? */
207 bool volatile m_fOpenOnWasClosed;
208 /** Whether to re-enumerate this device when the client closes it.
209 * This is something we'll do when the filter owner dies. */
210 bool volatile m_fReleaseOnClose;
211 /** Whether we're being unloaded or not.
212 * Only valid in stop(). */
213 bool m_fBeingUnloaded;
214 /** Pointer to the next device in the list. */
215 org_virtualbox_VBoxUSBDevice * volatile m_pNext;
216 /** Pointer to the list head. Protected by g_Mtx. */
217 static org_virtualbox_VBoxUSBDevice * volatile s_pHead;
218
219#ifdef DEBUG
220 /** The interest notifier. */
221 IONotifier *m_pNotifier;
222
223 static IOReturn MyInterestHandler(void *pvTarget, void *pvRefCon, UInt32 enmMsgType,
224 IOService *pProvider, void * pvMsgArg, vm_size_t cbMsgArg);
225#endif
226};
227OSDefineMetaClassAndStructors(org_virtualbox_VBoxUSBDevice, IOUSBUserClientInit);
228
229
230/**
231 * The IOUSBInterface driver class.
232 *
233 * The main purpose of this is hijack interfaces which device is driven
234 * by org_virtualbox_VBoxUSBDevice.
235 *
236 * @remarks See org_virtualbox_VBoxUSBDevice for why we use IOUSBUserClientInit.
237 */
238class org_virtualbox_VBoxUSBInterface : public IOUSBUserClientInit
239{
240 OSDeclareDefaultStructors(org_virtualbox_VBoxUSBInterface);
241
242public:
243 /** @name IOService
244 * @{ */
245 virtual bool init(OSDictionary *pDictionary = 0);
246 virtual IOService *probe(IOService *pProvider, SInt32 *pi32Score);
247 virtual bool start(IOService *pProvider);
248 virtual bool terminate(IOOptionBits fOptions = 0);
249 virtual void stop(IOService *pProvider);
250 virtual void free();
251 virtual IOReturn message(UInt32 enmMsg, IOService *pProvider, void *pvArg = 0);
252 /** @} */
253
254private:
255 /** The interface we're driving (aka. the provider). */
256 IOUSBInterface *m_pInterface;
257 /** Have we opened the device or not? */
258 bool volatile m_fOpen;
259 /** Should be open the device on the next close notification message? */
260 bool volatile m_fOpenOnWasClosed;
261};
262OSDefineMetaClassAndStructors(org_virtualbox_VBoxUSBInterface, IOUSBUserClientInit);
263
264
265
266
267
268/*******************************************************************************
269* Global Variables *
270*******************************************************************************/
271/*
272 * Declare the module stuff.
273 */
274RT_C_DECLS_BEGIN
275extern kern_return_t _start(struct kmod_info *pKModInfo, void *pvData);
276extern kern_return_t _stop(struct kmod_info *pKModInfo, void *pvData);
277
278KMOD_EXPLICIT_DECL(VBoxDrv, VBOX_VERSION_STRING, _start, _stop)
279DECLHIDDEN(kmod_start_func_t *) _realmain = VBoxUSBStart;
280DECLHIDDEN(kmod_stop_func_t *) _antimain = VBoxUSBStop;
281DECLHIDDEN(int) _kext_apple_cc = __APPLE_CC__;
282RT_C_DECLS_END
283
284/** Mutex protecting the lists. */
285static RTSEMFASTMUTEX g_Mtx = NIL_RTSEMFASTMUTEX;
286org_virtualbox_VBoxUSBClient * volatile org_virtualbox_VBoxUSBClient::s_pHead = NULL;
287org_virtualbox_VBoxUSBDevice * volatile org_virtualbox_VBoxUSBDevice::s_pHead = NULL;
288
289/** Global instance count - just for checking proving that everything is destroyed correctly. */
290static volatile uint32_t g_cInstances = 0;
291
292
293/**
294 * Start the kernel module.
295 */
296static kern_return_t VBoxUSBStart(struct kmod_info *pKModInfo, void *pvData)
297{
298 int rc;
299 Log(("VBoxUSBStart\n"));
300
301 /*
302 * Initialize IPRT.
303 */
304 rc = RTR0Init(0);
305 if (RT_SUCCESS(rc))
306 {
307 /*
308 * Create the spinlock.
309 */
310 rc = RTSemFastMutexCreate(&g_Mtx);
311 if (RT_SUCCESS(rc))
312 {
313 rc = VBoxUSBFilterInit();
314 if (RT_SUCCESS(rc))
315 {
316#if 0 /* testing */
317 USBFILTER Flt;
318 USBFilterInit(&Flt, USBFILTERTYPE_CAPTURE);
319 USBFilterSetNumExact(&Flt, USBFILTERIDX_VENDOR_ID, 0x096e, true);
320 uintptr_t uId;
321 rc = VBoxUSBFilterAdd(&Flt, 1, &uId);
322 printf("VBoxUSB: VBoxUSBFilterAdd #1 -> %d + %p\n", rc, uId);
323
324 USBFilterInit(&Flt, USBFILTERTYPE_CAPTURE);
325 USBFilterSetStringPattern(&Flt, USBFILTERIDX_PRODUCT_STR, "*DISK*", true);
326 rc = VBoxUSBFilterAdd(&Flt, 2, &uId);
327 printf("VBoxUSB: VBoxUSBFilterAdd #2 -> %d + %p\n", rc, uId);
328#endif
329 return KMOD_RETURN_SUCCESS;
330 }
331 printf("VBoxUSB: VBoxUSBFilterInit failed (rc=%d)\n", rc);
332 RTSemFastMutexDestroy(g_Mtx);
333 g_Mtx = NIL_RTSEMFASTMUTEX;
334 }
335 else
336 printf("VBoxUSB: RTSemFastMutexCreate failed (rc=%d)\n", rc);
337 RTR0Term();
338 }
339 else
340 printf("VBoxUSB: failed to initialize IPRT (rc=%d)\n", rc);
341
342 return KMOD_RETURN_FAILURE;
343}
344
345
346/**
347 * Stop the kernel module.
348 */
349static kern_return_t VBoxUSBStop(struct kmod_info *pKModInfo, void *pvData)
350{
351 int rc;
352 Log(("VBoxUSBStop: g_cInstances=%d\n", g_cInstances));
353
354 /** @todo Fix problem with crashing when unloading a driver that's in use. */
355
356 /*
357 * Undo the work done during start (in reverse order).
358 */
359 VBoxUSBFilterTerm();
360
361 rc = RTSemFastMutexDestroy(g_Mtx);
362 AssertRC(rc);
363 g_Mtx = NIL_RTSEMFASTMUTEX;
364
365 RTR0Term();
366
367 Log(("VBoxUSBStop - done\n"));
368 return KMOD_RETURN_SUCCESS;
369}
370
371
372
373
374
375
376/**
377 * Gets the name of a IOKit message.
378 *
379 * @returns Message name (read only).
380 * @param enmMsg The message.
381 */
382DECLINLINE(const char *) DbgGetIOKitMessageName(UInt32 enmMsg)
383{
384#ifdef DEBUG
385 switch (enmMsg)
386 {
387#define MY_CASE(enm) case enm: return #enm; break
388 MY_CASE(kIOMessageServiceIsTerminated);
389 MY_CASE(kIOMessageServiceIsSuspended);
390 MY_CASE(kIOMessageServiceIsResumed);
391 MY_CASE(kIOMessageServiceIsRequestingClose);
392 MY_CASE(kIOMessageServiceIsAttemptingOpen);
393 MY_CASE(kIOMessageServiceWasClosed);
394 MY_CASE(kIOMessageServiceBusyStateChange);
395 MY_CASE(kIOMessageServicePropertyChange);
396 MY_CASE(kIOMessageCanDevicePowerOff);
397 MY_CASE(kIOMessageDeviceWillPowerOff);
398 MY_CASE(kIOMessageDeviceWillNotPowerOff);
399 MY_CASE(kIOMessageDeviceHasPoweredOn);
400 MY_CASE(kIOMessageCanSystemPowerOff);
401 MY_CASE(kIOMessageSystemWillPowerOff);
402 MY_CASE(kIOMessageSystemWillNotPowerOff);
403 MY_CASE(kIOMessageCanSystemSleep);
404 MY_CASE(kIOMessageSystemWillSleep);
405 MY_CASE(kIOMessageSystemWillNotSleep);
406 MY_CASE(kIOMessageSystemHasPoweredOn);
407 MY_CASE(kIOMessageSystemWillRestart);
408 MY_CASE(kIOMessageSystemWillPowerOn);
409 MY_CASE(kIOUSBMessageHubResetPort);
410 MY_CASE(kIOUSBMessageHubSuspendPort);
411 MY_CASE(kIOUSBMessageHubResumePort);
412 MY_CASE(kIOUSBMessageHubIsDeviceConnected);
413 MY_CASE(kIOUSBMessageHubIsPortEnabled);
414 MY_CASE(kIOUSBMessageHubReEnumeratePort);
415 MY_CASE(kIOUSBMessagePortHasBeenReset);
416 MY_CASE(kIOUSBMessagePortHasBeenResumed);
417 MY_CASE(kIOUSBMessageHubPortClearTT);
418 MY_CASE(kIOUSBMessagePortHasBeenSuspended);
419 MY_CASE(kIOUSBMessageFromThirdParty);
420 MY_CASE(kIOUSBMessagePortWasNotSuspended);
421 MY_CASE(kIOUSBMessageExpressCardCantWake);
422// MY_CASE(kIOUSBMessageCompositeDriverReconfigured);
423#undef MY_CASE
424 }
425#endif /* DEBUG */
426 return "unknown";
427}
428
429
430
431
432
433/*
434 *
435 * org_virtualbox_VBoxUSB
436 *
437 */
438
439
440/**
441 * Initialize the object.
442 * @remark Only for logging.
443 */
444bool
445org_virtualbox_VBoxUSB::init(OSDictionary *pDictionary)
446{
447 uint32_t cInstances = ASMAtomicIncU32(&g_cInstances);
448 Log(("VBoxUSB::init([%p], %p) new g_cInstances=%d\n", this, pDictionary, cInstances));
449 if (IOService::init(pDictionary))
450 {
451 /* init members. */
452 return true;
453 }
454 ASMAtomicDecU32(&g_cInstances);
455 return false;
456}
457
458
459/**
460 * Free the object.
461 * @remark Only for logging.
462 */
463void
464org_virtualbox_VBoxUSB::free()
465{
466 uint32_t cInstances = ASMAtomicDecU32(&g_cInstances); NOREF(cInstances);
467 Log(("VBoxUSB::free([%p]) new g_cInstances=%d\n", this, cInstances));
468 IOService::free();
469}
470
471
472/**
473 * Start this service.
474 */
475bool
476org_virtualbox_VBoxUSB::start(IOService *pProvider)
477{
478 Log(("VBoxUSB::start([%p], %p {%s})\n", this, pProvider, pProvider->getName()));
479
480 if (IOService::start(pProvider))
481 {
482 /* register the service. */
483 registerService();
484 return true;
485 }
486 return false;
487}
488
489
490/**
491 * Stop this service.
492 * @remark Only for logging.
493 */
494void
495org_virtualbox_VBoxUSB::stop(IOService *pProvider)
496{
497 Log(("VBoxUSB::stop([%p], %p (%s))\n", this, pProvider, pProvider->getName()));
498 IOService::stop(pProvider);
499}
500
501
502/**
503 * Stop this service.
504 * @remark Only for logging.
505 */
506bool
507org_virtualbox_VBoxUSB::open(IOService *pForClient, IOOptionBits fOptions/* = 0*/, void *pvArg/* = 0*/)
508{
509 Log(("VBoxUSB::open([%p], %p, %#x, %p)\n", this, pForClient, fOptions, pvArg));
510 bool fRc = IOService::open(pForClient, fOptions, pvArg);
511 Log(("VBoxUSB::open([%p], %p, %#x, %p) -> %d\n", this, pForClient, fOptions, pvArg, fRc));
512 return fRc;
513}
514
515
516/**
517 * Stop this service.
518 * @remark Only for logging.
519 */
520void
521org_virtualbox_VBoxUSB::close(IOService *pForClient, IOOptionBits fOptions/* = 0*/)
522{
523 Log(("VBoxUSB::close([%p], %p, %#x)\n", this, pForClient, fOptions));
524 IOService::close(pForClient, fOptions);
525}
526
527
528/**
529 * Terminate request.
530 * @remark Only for logging.
531 */
532bool
533org_virtualbox_VBoxUSB::terminate(IOOptionBits fOptions)
534{
535 Log(("VBoxUSB::terminate([%p], %#x): g_cInstances=%d\n", this, fOptions, g_cInstances));
536 bool fRc = IOService::terminate(fOptions);
537 Log(("VBoxUSB::terminate([%p], %#x): returns %d\n", this, fOptions, fRc));
538 return fRc;
539}
540
541
542
543
544
545
546
547
548
549
550
551/*
552 *
553 * org_virtualbox_VBoxUSBClient
554 *
555 */
556
557
558/**
559 * Initializer called when the client opens the service.
560 */
561bool
562org_virtualbox_VBoxUSBClient::initWithTask(task_t OwningTask, void *pvSecurityId, UInt32 u32Type)
563{
564 if (!OwningTask)
565 {
566 Log(("VBoxUSBClient::initWithTask([%p], %p, %p, %#x) -> false (no task)\n", this, OwningTask, pvSecurityId, u32Type));
567 return false;
568 }
569 if (u32Type != VBOXUSB_DARWIN_IOSERVICE_COOKIE)
570 {
571 Log(("VBoxUSBClient::initWithTask: Bade cookie %#x\n", u32Type));
572 return false;
573 }
574
575 proc_t pProc = (proc_t)get_bsdtask_info(OwningTask); /* we need the pid */
576 Log(("VBoxUSBClient::initWithTask([%p], %p(->%p:{.pid=%d}, %p, %#x)\n",
577 this, OwningTask, pProc, pProc ? proc_pid(pProc) : -1, pvSecurityId, u32Type));
578
579 if (IOUserClient::initWithTask(OwningTask, pvSecurityId , u32Type))
580 {
581 m_pProvider = NULL;
582 m_Task = OwningTask;
583 m_Process = pProc ? proc_pid(pProc) : NIL_RTPROCESS;
584 m_pNext = NULL;
585
586 uint32_t cInstances = ASMAtomicIncU32(&g_cInstances);
587 Log(("VBoxUSBClient::initWithTask([%p], %p(->%p:{.pid=%d}, %p, %#x) -> true; new g_cInstances=%d\n",
588 this, OwningTask, pProc, pProc ? proc_pid(pProc) : -1, pvSecurityId, u32Type, cInstances));
589 return true;
590 }
591
592 Log(("VBoxUSBClient::initWithTask([%p], %p(->%p:{.pid=%d}, %p, %#x) -> false\n",
593 this, OwningTask, pProc, pProc ? proc_pid(pProc) : -1, pvSecurityId, u32Type));
594 return false;
595}
596
597
598/**
599 * Free the object.
600 * @remark Only for logging.
601 */
602void
603org_virtualbox_VBoxUSBClient::free()
604{
605 uint32_t cInstances = ASMAtomicDecU32(&g_cInstances); NOREF(cInstances);
606 Log(("VBoxUSBClient::free([%p]) new g_cInstances=%d\n", this, cInstances));
607 IOUserClient::free();
608}
609
610
611/**
612 * Start the client service.
613 */
614bool
615org_virtualbox_VBoxUSBClient::start(IOService *pProvider)
616{
617 Log(("VBoxUSBClient::start([%p], %p)\n", this, pProvider));
618 if (IOUserClient::start(pProvider))
619 {
620 m_pProvider = OSDynamicCast(org_virtualbox_VBoxUSB, pProvider);
621 if (m_pProvider)
622 {
623 /*
624 * Add ourselves to the list of user clients.
625 */
626 VBOXUSB_LOCK();
627
628 m_pNext = s_pHead;
629 s_pHead = this;
630
631 VBOXUSB_UNLOCK();
632
633 return true;
634 }
635 Log(("VBoxUSBClient::start: %p isn't org_virtualbox_VBoxUSB\n", pProvider));
636 }
637 return false;
638}
639
640
641/**
642 * Client exits normally.
643 */
644IOReturn
645org_virtualbox_VBoxUSBClient::clientClose(void)
646{
647 Log(("VBoxUSBClient::clientClose([%p:{.m_Process=%d}])\n", this, (int)m_Process));
648
649 /*
650 * Remove this process from the client list.
651 */
652 VBOXUSB_LOCK();
653
654 org_virtualbox_VBoxUSBClient *pPrev = NULL;
655 for (org_virtualbox_VBoxUSBClient *pCur = s_pHead; pCur; pCur = pCur->m_pNext)
656 {
657 if (pCur == this)
658 {
659 if (pPrev)
660 pPrev->m_pNext = m_pNext;
661 else
662 s_pHead = m_pNext;
663 m_pNext = NULL;
664 break;
665 }
666 pPrev = pCur;
667 }
668
669 VBOXUSB_UNLOCK();
670
671 /*
672 * Drop all filters owned by this client.
673 */
674 if (m_Process != NIL_RTPROCESS)
675 VBoxUSBFilterRemoveOwner(m_Process);
676
677 /*
678 * Schedule all devices owned (filtered) by this process for
679 * immediate release or release upon close.
680 */
681 if (m_Process != NIL_RTPROCESS)
682 org_virtualbox_VBoxUSBDevice::scheduleReleaseByOwner(m_Process);
683
684 /*
685 * Initiate termination.
686 */
687 m_pProvider = NULL;
688 terminate();
689
690 return kIOReturnSuccess;
691}
692
693
694/**
695 * The client exits abnormally / forgets to do cleanups.
696 * @remark Only for logging.
697 */
698IOReturn
699org_virtualbox_VBoxUSBClient::clientDied(void)
700{
701 Log(("VBoxUSBClient::clientDied([%p]) m_Task=%p R0Process=%p Process=%d\n",
702 this, m_Task, RTR0ProcHandleSelf(), RTProcSelf()));
703
704 /* IOUserClient::clientDied() calls clientClose... */
705 return IOUserClient::clientDied();
706}
707
708
709/**
710 * Terminate the service (initiate the destruction).
711 * @remark Only for logging.
712 */
713bool
714org_virtualbox_VBoxUSBClient::terminate(IOOptionBits fOptions)
715{
716 /* kIOServiceRecursing, kIOServiceRequired, kIOServiceTerminate, kIOServiceSynchronous - interesting option bits */
717 Log(("VBoxUSBClient::terminate([%p], %#x)\n", this, fOptions));
718 return IOUserClient::terminate(fOptions);
719}
720
721
722/**
723 * The final stage of the client service destruction.
724 * @remark Only for logging.
725 */
726bool
727org_virtualbox_VBoxUSBClient::finalize(IOOptionBits fOptions)
728{
729 Log(("VBoxUSBClient::finalize([%p], %#x)\n", this, fOptions));
730 return IOUserClient::finalize(fOptions);
731}
732
733
734/**
735 * Stop the client service.
736 */
737void
738org_virtualbox_VBoxUSBClient::stop(IOService *pProvider)
739{
740 Log(("VBoxUSBClient::stop([%p])\n", this));
741 IOUserClient::stop(pProvider);
742
743 /*
744 * Paranoia.
745 */
746 VBOXUSB_LOCK();
747
748 org_virtualbox_VBoxUSBClient *pPrev = NULL;
749 for (org_virtualbox_VBoxUSBClient *pCur = s_pHead; pCur; pCur = pCur->m_pNext)
750 {
751 if (pCur == this)
752 {
753 if (pPrev)
754 pPrev->m_pNext = m_pNext;
755 else
756 s_pHead = m_pNext;
757 m_pNext = NULL;
758 break;
759 }
760 pPrev = pCur;
761 }
762
763 VBOXUSB_UNLOCK();
764}
765
766
767/**
768 * Translate a user method index into a service object and an external method structure.
769 *
770 * @returns Pointer to external method structure descripting the method.
771 * NULL if the index isn't valid.
772 * @param ppService Where to store the service object on success.
773 * @param iMethod The method index.
774 */
775IOExternalMethod *
776org_virtualbox_VBoxUSBClient::getTargetAndMethodForIndex(IOService **ppService, UInt32 iMethod)
777{
778 static IOExternalMethod s_aMethods[VBOXUSBMETHOD_END] =
779 {
780 /*[VBOXUSBMETHOD_ADD_FILTER] = */
781 {
782 (IOService *)0, /* object */
783 (IOMethod)&org_virtualbox_VBoxUSBClient::addFilter, /* func */
784 kIOUCStructIStructO, /* flags - struct input (count0) and struct output (count1) */
785 sizeof(USBFILTER), /* count0 - size of the input struct. */
786 sizeof(VBOXUSBADDFILTEROUT) /* count1 - size of the return struct. */
787 },
788 /* [VBOXUSBMETHOD_FILTER_REMOVE] = */
789 {
790 (IOService *)0, /* object */
791 (IOMethod)&org_virtualbox_VBoxUSBClient::removeFilter, /* func */
792 kIOUCStructIStructO, /* flags - struct input (count0) and struct output (count1) */
793 sizeof(uintptr_t), /* count0 - size of the input (id) */
794 sizeof(int) /* count1 - size of the output (rc) */
795 },
796 };
797
798 if (RT_UNLIKELY(iMethod >= RT_ELEMENTS(s_aMethods)))
799 return NULL;
800
801 *ppService = this;
802 return &s_aMethods[iMethod];
803}
804
805
806/**
807 * Add filter user request.
808 *
809 * @returns IOKit status code.
810 * @param pFilter The filter to add.
811 * @param pOut Pointer to the output structure.
812 * @param cbFilter Size of the filter structure.
813 * @param pcbOut In/Out - sizeof(*pOut).
814 */
815IOReturn
816org_virtualbox_VBoxUSBClient::addFilter(PUSBFILTER pFilter, PVBOXUSBADDFILTEROUT pOut, IOByteCount cbFilter, IOByteCount *pcbOut)
817{
818 Log(("VBoxUSBClient::addFilter: [%p:{.m_Process=%d}] pFilter=%p pOut=%p\n", this, (int)m_Process, pFilter, pOut));
819
820 /*
821 * Validate input.
822 */
823 if (RT_UNLIKELY( cbFilter != sizeof(*pFilter)
824 || *pcbOut != sizeof(*pOut)))
825 {
826 printf("VBoxUSBClient::addFilter: cbFilter=%#x expected %#x; *pcbOut=%#x expected %#x\n",
827 (int)cbFilter, (int)sizeof(*pFilter), (int)*pcbOut, (int)sizeof(*pOut));
828 return kIOReturnBadArgument;
829 }
830
831 /*
832 * Log the filter details.
833 */
834#ifdef DEBUG
835 Log2(("VBoxUSBClient::addFilter: idVendor=%#x idProduct=%#x bcdDevice=%#x bDeviceClass=%#x bDeviceSubClass=%#x bDeviceProtocol=%#x bBus=%#x bPort=%#x\n",
836 USBFilterGetNum(pFilter, USBFILTERIDX_VENDOR_ID),
837 USBFilterGetNum(pFilter, USBFILTERIDX_PRODUCT_ID),
838 USBFilterGetNum(pFilter, USBFILTERIDX_DEVICE_REV),
839 USBFilterGetNum(pFilter, USBFILTERIDX_DEVICE_CLASS),
840 USBFilterGetNum(pFilter, USBFILTERIDX_DEVICE_SUB_CLASS),
841 USBFilterGetNum(pFilter, USBFILTERIDX_DEVICE_PROTOCOL),
842 USBFilterGetNum(pFilter, USBFILTERIDX_BUS),
843 USBFilterGetNum(pFilter, USBFILTERIDX_PORT)));
844 Log2(("VBoxUSBClient::addFilter: Manufacturer=%s Product=%s Serial=%s\n",
845 USBFilterGetString(pFilter, USBFILTERIDX_MANUFACTURER_STR) ? USBFilterGetString(pFilter, USBFILTERIDX_MANUFACTURER_STR) : "<null>",
846 USBFilterGetString(pFilter, USBFILTERIDX_PRODUCT_STR) ? USBFilterGetString(pFilter, USBFILTERIDX_PRODUCT_STR) : "<null>",
847 USBFilterGetString(pFilter, USBFILTERIDX_SERIAL_NUMBER_STR) ? USBFilterGetString(pFilter, USBFILTERIDX_SERIAL_NUMBER_STR) : "<null>"));
848#endif
849
850 /*
851 * Since we cannot query the bus number, make sure the filter
852 * isn't requiring that field to be present.
853 */
854 int rc = USBFilterSetMustBePresent(pFilter, USBFILTERIDX_BUS, false /* fMustBePresent */); AssertRC(rc);
855
856 /*
857 * Add the filter.
858 */
859 pOut->uId = 0;
860 pOut->rc = VBoxUSBFilterAdd(pFilter, m_Process, &pOut->uId);
861
862 Log(("VBoxUSBClient::addFilter: returns *pOut={.rc=%d, .uId=%p}\n", pOut->rc, (void *)pOut->uId));
863 return kIOReturnSuccess;
864}
865
866
867/**
868 * Removes filter user request.
869 *
870 * @returns IOKit status code.
871 * @param puId Where to get the filter ID.
872 * @param prc Where to store the return code.
873 * @param cbIn sizeof(*puId).
874 * @param pcbOut In/Out - sizeof(*prc).
875 */
876IOReturn
877org_virtualbox_VBoxUSBClient::removeFilter(uintptr_t *puId, int *prc, IOByteCount cbIn, IOByteCount *pcbOut)
878{
879 Log(("VBoxUSBClient::removeFilter: [%p:{.m_Process=%d}] *puId=%p m_Proc\n", this, (int)m_Process, *puId));
880
881 /*
882 * Validate input.
883 */
884 if (RT_UNLIKELY( cbIn != sizeof(*puId)
885 || *pcbOut != sizeof(*prc)))
886 {
887 printf("VBoxUSBClient::removeFilter: cbIn=%#x expected %#x; *pcbOut=%#x expected %#x\n",
888 (int)cbIn, (int)sizeof(*puId), (int)*pcbOut, (int)sizeof(*prc));
889 return kIOReturnBadArgument;
890 }
891
892 /*
893 * Remove the filter.
894 */
895 *prc = VBoxUSBFilterRemove(m_Process, *puId);
896
897 Log(("VBoxUSBClient::removeFilter: returns *prc=%d\n", *prc));
898 return kIOReturnSuccess;
899}
900
901
902/**
903 * Checks whether the specified task is a VBoxUSB client task or not.
904 *
905 * This is used to validate clients trying to open any of the device
906 * or interfaces that we've hijacked.
907 *
908 * @returns true / false.
909 * @param ClientTask The task.
910 *
911 * @remark This protecting against other user clients is not currently implemented
912 * as it turned out to be more bothersome than first imagined.
913 */
914/* static*/ bool
915org_virtualbox_VBoxUSBClient::isClientTask(task_t ClientTask)
916{
917 VBOXUSB_LOCK();
918
919 for (org_virtualbox_VBoxUSBClient *pCur = s_pHead; pCur; pCur = pCur->m_pNext)
920 if (pCur->m_Task == ClientTask)
921 {
922 VBOXUSB_UNLOCK();
923 return true;
924 }
925
926 VBOXUSB_UNLOCK();
927 return false;
928}
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943/*
944 *
945 * org_virtualbox_VBoxUSBDevice
946 *
947 */
948
949/**
950 * Initialize instance data.
951 *
952 * @returns Success indicator.
953 * @param pDictionary The dictionary that will become the registry entry's
954 * property table, or NULL. Hand it up to our parents.
955 */
956bool
957org_virtualbox_VBoxUSBDevice::init(OSDictionary *pDictionary)
958{
959 uint32_t cInstances = ASMAtomicIncU32(&g_cInstances);
960 Log(("VBoxUSBDevice::init([%p], %p) new g_cInstances=%d\n", this, pDictionary, cInstances));
961
962 m_pDevice = NULL;
963 m_Owner = NIL_RTPROCESS;
964 m_Client = NIL_RTPROCESS;
965 m_uId = ~(uintptr_t)0;
966 m_fOpen = false;
967 m_fOpenOnWasClosed = false;
968 m_fReleaseOnClose = false;
969 m_fBeingUnloaded = false;
970 m_pNext = NULL;
971#ifdef DEBUG
972 m_pNotifier = NULL;
973#endif
974
975 return IOUSBUserClientInit::init(pDictionary);
976}
977
978/**
979 * Free the object.
980 * @remark Only for logging.
981 */
982void
983org_virtualbox_VBoxUSBDevice::free()
984{
985 uint32_t cInstances = ASMAtomicDecU32(&g_cInstances); NOREF(cInstances);
986 Log(("VBoxUSBDevice::free([%p]) new g_cInstances=%d\n", this, cInstances));
987 IOUSBUserClientInit::free();
988}
989
990
991/**
992 * The device/driver probing.
993 *
994 * I/O Kit will iterate all device drivers suitable for this kind of device
995 * (this is something it figures out from the property file) and call their
996 * probe() method in order to try determine which is the best match for the
997 * device. We will match the device against the registered filters and set
998 * a ridiculously high score if we find it, thus making it extremely likely
999 * that we'll be the first driver to be started. We'll also set a couple of
1000 * attributes so that it's not necessary to do a rematch in init to find
1001 * the appropriate filter (might not be necessary..., see todo).
1002 *
1003 * @returns Service instance to be started and *pi32Score if matching.
1004 * NULL if not a device suitable for this driver.
1005 *
1006 * @param pProvider The provider instance.
1007 * @param pi32Score Where to store the probe score.
1008 */
1009IOService *
1010org_virtualbox_VBoxUSBDevice::probe(IOService *pProvider, SInt32 *pi32Score)
1011{
1012 Log(("VBoxUSBDevice::probe([%p], %p {%s}, %p={%d})\n", this,
1013 pProvider, pProvider->getName(), pi32Score, pi32Score ? *pi32Score : 0));
1014
1015 /*
1016 * Check against filters.
1017 */
1018 USBFILTER Device;
1019 USBFilterInit(&Device, USBFILTERTYPE_CAPTURE);
1020
1021 static const struct
1022 {
1023 const char *pszName;
1024 USBFILTERIDX enmIdx;
1025 bool fNumeric;
1026 } s_aProps[] =
1027 {
1028 { kUSBVendorID, USBFILTERIDX_VENDOR_ID, true },
1029 { kUSBProductID, USBFILTERIDX_PRODUCT_ID, true },
1030 { kUSBDeviceReleaseNumber, USBFILTERIDX_DEVICE_REV, true },
1031 { kUSBDeviceClass, USBFILTERIDX_DEVICE_CLASS, true },
1032 { kUSBDeviceSubClass, USBFILTERIDX_DEVICE_SUB_CLASS, true },
1033 { kUSBDeviceProtocol, USBFILTERIDX_DEVICE_PROTOCOL, true },
1034 { "PortNum", USBFILTERIDX_PORT, true },
1035 /// @todo { , USBFILTERIDX_BUS, true }, - must be derived :-/
1036 /// Seems to be the upper byte of locationID and our "grand parent" has a USBBusNumber prop.
1037 { "USB Vendor Name", USBFILTERIDX_MANUFACTURER_STR, false },
1038 { "USB Product Name", USBFILTERIDX_PRODUCT_STR, false },
1039 { "USB Serial Number", USBFILTERIDX_SERIAL_NUMBER_STR, false },
1040 };
1041 for (unsigned i = 0; i < RT_ELEMENTS(s_aProps); i++)
1042 {
1043 OSObject *pObj = pProvider->getProperty(s_aProps[i].pszName);
1044 if (!pObj)
1045 continue;
1046 if (s_aProps[i].fNumeric)
1047 {
1048 OSNumber *pNum = OSDynamicCast(OSNumber, pObj);
1049 if (pNum)
1050 {
1051 uint16_t u16 = pNum->unsigned16BitValue();
1052 Log2(("VBoxUSBDevice::probe: %d/%s - %#x (32bit=%#x)\n", i, s_aProps[i].pszName, u16, pNum->unsigned32BitValue()));
1053 int vrc = USBFilterSetNumExact(&Device, s_aProps[i].enmIdx, u16, true);
1054 if (RT_FAILURE(vrc))
1055 Log(("VBoxUSBDevice::probe: pObj=%p pNum=%p - %d/%s - rc=%d!\n", pObj, pNum, i, s_aProps[i].pszName, vrc));
1056 }
1057 else
1058 Log(("VBoxUSBDevice::probe: pObj=%p pNum=%p - %d/%s!\n", pObj, pNum, i, s_aProps[i].pszName));
1059 }
1060 else
1061 {
1062 OSString *pStr = OSDynamicCast(OSString, pObj);
1063 if (pStr)
1064 {
1065 Log2(("VBoxUSBDevice::probe: %d/%s - %s\n", i, s_aProps[i].pszName, pStr->getCStringNoCopy()));
1066 int vrc = USBFilterSetStringExact(&Device, s_aProps[i].enmIdx, pStr->getCStringNoCopy(), true);
1067 if (RT_FAILURE(vrc))
1068 Log(("VBoxUSBDevice::probe: pObj=%p pStr=%p - %d/%s - rc=%d!\n", pObj, pStr, i, s_aProps[i].pszName, vrc));
1069 }
1070 else
1071 Log(("VBoxUSBDevice::probe: pObj=%p pStr=%p - %d/%s\n", pObj, pStr, i, s_aProps[i].pszName));
1072 }
1073 }
1074 /** @todo try figure the blasted bus number */
1075
1076 /*
1077 * Run filters on it.
1078 */
1079 uintptr_t uId = 0;
1080 RTPROCESS Owner = VBoxUSBFilterMatch(&Device, &uId);
1081 USBFilterDelete(&Device);
1082 if (Owner == NIL_RTPROCESS)
1083 {
1084 Log(("VBoxUSBDevice::probe: returns NULL uId=%d\n", uId));
1085 return NULL;
1086 }
1087
1088 /*
1089 * It matched. Save the owner in the provider registry (hope that works).
1090 */
1091 IOService *pRet = IOUSBUserClientInit::probe(pProvider, pi32Score);
1092 Assert(pRet == this);
1093 m_Owner = Owner;
1094 m_uId = uId;
1095 Log(("%p: m_Owner=%d m_uId=%d\n", this, (int)m_Owner, (int)m_uId));
1096 *pi32Score = _1G;
1097 Log(("VBoxUSBDevice::probe: returns %p and *pi32Score=%d\n", pRet, *pi32Score));
1098 return pRet;
1099}
1100
1101
1102/**
1103 * Try start the device driver.
1104 *
1105 * We will do device linking, copy the filter and owner properties from the provider,
1106 * set the client property, retain the device, and try open (seize) the device.
1107 *
1108 * @returns Success indicator.
1109 * @param pProvider The provider instance.
1110 */
1111bool
1112org_virtualbox_VBoxUSBDevice::start(IOService *pProvider)
1113{
1114 Log(("VBoxUSBDevice::start([%p:{.m_Owner=%d, .m_uId=%p}], %p {%s})\n",
1115 this, m_Owner, m_uId, pProvider, pProvider->getName()));
1116
1117 m_pDevice = OSDynamicCast(IOUSBDevice, pProvider);
1118 if (!m_pDevice)
1119 {
1120 printf("VBoxUSBDevice::start([%p], %p {%s}): failed!\n", this, pProvider, pProvider->getName());
1121 return false;
1122 }
1123
1124#ifdef DEBUG
1125 /* for some extra log messages */
1126 m_pNotifier = pProvider->registerInterest(gIOGeneralInterest,
1127 &org_virtualbox_VBoxUSBDevice::MyInterestHandler,
1128 this, /* pvTarget */
1129 NULL); /* pvRefCon */
1130#endif
1131
1132 /*
1133 * Exploit IOUSBUserClientInit to process IOProviderMergeProperties.
1134 */
1135 IOUSBUserClientInit::start(pProvider); /* returns false */
1136
1137 /*
1138 * Link ourselves into the list of hijacked device.
1139 */
1140 VBOXUSB_LOCK();
1141
1142 m_pNext = s_pHead;
1143 s_pHead = this;
1144
1145 VBOXUSB_UNLOCK();
1146
1147 /*
1148 * Set the VBoxUSB properties.
1149 */
1150 if (!setProperty(VBOXUSB_OWNER_KEY, (unsigned long long)m_Owner, sizeof(m_Owner) * 8 /* bits */))
1151 Log(("VBoxUSBDevice::start: failed to set the '" VBOXUSB_OWNER_KEY "' property!\n"));
1152 if (!setProperty(VBOXUSB_CLIENT_KEY, (unsigned long long)m_Client, sizeof(m_Client) * 8 /* bits */))
1153 Log(("VBoxUSBDevice::start: failed to set the '" VBOXUSB_CLIENT_KEY "' property!\n"));
1154 if (!setProperty(VBOXUSB_FILTER_KEY, (unsigned long long)m_uId, sizeof(m_uId) * 8 /* bits */))
1155 Log(("VBoxUSBDevice::start: failed to set the '" VBOXUSB_FILTER_KEY "' property!\n"));
1156
1157 /*
1158 * Retain and open the device.
1159 */
1160 m_pDevice->retain();
1161 m_fOpen = m_pDevice->open(this, kIOServiceSeize, 0);
1162 if (!m_fOpen)
1163 Log(("VBoxUSBDevice::start: failed to open the device!\n"));
1164 m_fOpenOnWasClosed = !m_fOpen;
1165
1166 Log(("VBoxUSBDevice::start: returns %d\n", true));
1167 return true;
1168}
1169
1170
1171/**
1172 * Stop the device driver.
1173 *
1174 * We'll unlink the device, start device re-enumeration and close it. And call
1175 * the parent stop method of course.
1176 *
1177 * @param pProvider The provider instance.
1178 */
1179void
1180org_virtualbox_VBoxUSBDevice::stop(IOService *pProvider)
1181{
1182 Log(("VBoxUSBDevice::stop([%p], %p {%s})\n", this, pProvider, pProvider->getName()));
1183
1184 /*
1185 * Remove ourselves from the list of device.
1186 */
1187 VBOXUSB_LOCK();
1188
1189 org_virtualbox_VBoxUSBDevice *pPrev = NULL;
1190 for (org_virtualbox_VBoxUSBDevice *pCur = s_pHead; pCur; pCur = pCur->m_pNext)
1191 {
1192 if (pCur == this)
1193 {
1194 if (pPrev)
1195 pPrev->m_pNext = m_pNext;
1196 else
1197 s_pHead = m_pNext;
1198 m_pNext = NULL;
1199 break;
1200 }
1201 pPrev = pCur;
1202 }
1203
1204 VBOXUSB_UNLOCK();
1205
1206 /*
1207 * Should we release the device?
1208 */
1209 if (m_fBeingUnloaded)
1210 {
1211 if (m_pDevice)
1212 {
1213 IOReturn irc = m_pDevice->ReEnumerateDevice(0); NOREF(irc);
1214 Log(("VBoxUSBDevice::stop([%p], %p {%s}): m_pDevice=%p unload & ReEnumerateDevice -> %#x\n",
1215 this, pProvider, pProvider->getName(), m_pDevice, irc));
1216 }
1217 else
1218 {
1219 IOUSBDevice *pDevice = OSDynamicCast(IOUSBDevice, pProvider);
1220 if (pDevice)
1221 {
1222 IOReturn irc = pDevice->ReEnumerateDevice(0); NOREF(irc);
1223 Log(("VBoxUSBDevice::stop([%p], %p {%s}): pDevice=%p unload & ReEnumerateDevice -> %#x\n",
1224 this, pProvider, pProvider->getName(), pDevice, irc));
1225 }
1226 else
1227 Log(("VBoxUSBDevice::stop([%p], %p {%s}): failed to cast provider to IOUSBDevice\n",
1228 this, pProvider, pProvider->getName()));
1229 }
1230 }
1231 else if (m_fReleaseOnClose)
1232 {
1233 ASMAtomicWriteBool(&m_fReleaseOnClose, false);
1234 if (m_pDevice)
1235 {
1236 IOReturn irc = m_pDevice->ReEnumerateDevice(0); NOREF(irc);
1237 Log(("VBoxUSBDevice::stop([%p], %p {%s}): m_pDevice=%p close & ReEnumerateDevice -> %#x\n",
1238 this, pProvider, pProvider->getName(), m_pDevice, irc));
1239 }
1240 }
1241
1242 /*
1243 * Close and release the IOUSBDevice if didn't do that already in message().
1244 */
1245 if (m_pDevice)
1246 {
1247 /* close it */
1248 if (m_fOpen)
1249 {
1250 m_fOpenOnWasClosed = false;
1251 m_fOpen = false;
1252 m_pDevice->close(this, 0);
1253 }
1254
1255 /* release it (see start()) */
1256 m_pDevice->release();
1257 m_pDevice = NULL;
1258 }
1259
1260#ifdef DEBUG
1261 /* avoid crashing on unload. */
1262 if (m_pNotifier)
1263 {
1264 m_pNotifier->release();
1265 m_pNotifier = NULL;
1266 }
1267#endif
1268
1269 IOUSBUserClientInit::stop(pProvider);
1270 Log(("VBoxUSBDevice::stop: returns void\n"));
1271}
1272
1273
1274/**
1275 * Terminate the service (initiate the destruction).
1276 * @remark Only for logging.
1277 */
1278bool
1279org_virtualbox_VBoxUSBDevice::terminate(IOOptionBits fOptions)
1280{
1281 /* kIOServiceRecursing, kIOServiceRequired, kIOServiceTerminate, kIOServiceSynchronous - interesting option bits */
1282 Log(("VBoxUSBDevice::terminate([%p], %#x)\n", this, fOptions));
1283
1284 /*
1285 * There aren't too many reasons why we gets terminated.
1286 * The most common one is that the device is being unplugged. Another is
1287 * that we've triggered reenumeration. In both cases we'll get a
1288 * kIOMessageServiceIsTerminated message before we're stopped.
1289 *
1290 * But, when we're unloaded the provider service isn't terminated, and
1291 * for some funny reason we're frequently causing kernel panics when the
1292 * device is detached (after we're unloaded). So, for now, let's try
1293 * re-enumerate it in stop.
1294 *
1295 * To avoid creating unnecessary trouble we'll try guess if we're being
1296 * unloaded from the option bit mask. (kIOServiceRecursing is private btw.)
1297 */
1298 /** @todo would be nice if there was a documented way of doing the unload detection this, or
1299 * figure out what exactly we're doing wrong in the unload scenario. */
1300 if ((fOptions & 0xffff) == (kIOServiceRequired | kIOServiceSynchronous))
1301 m_fBeingUnloaded = true;
1302
1303 return IOUSBUserClientInit::terminate(fOptions);
1304}
1305
1306
1307/**
1308 * Intercept open requests and only let Mr. Right (the VM process) open the device.
1309 * This is where it all gets a bit complicated...
1310 *
1311 * @return Status code.
1312 *
1313 * @param enmMsg The message number.
1314 * @param pProvider Pointer to the provider instance.
1315 * @param pvArg Message argument.
1316 */
1317IOReturn
1318org_virtualbox_VBoxUSBDevice::message(UInt32 enmMsg, IOService *pProvider, void *pvArg)
1319{
1320 Log(("VBoxUSBDevice::message([%p], %#x {%s}, %p {%s}, %p) - pid=%d\n",
1321 this, enmMsg, DbgGetIOKitMessageName(enmMsg), pProvider, pProvider->getName(), pvArg, RTProcSelf()));
1322
1323 IOReturn irc;
1324 switch (enmMsg)
1325 {
1326 /*
1327 * This message is send to the current IOService client from IOService::handleOpen(),
1328 * expecting it to call pProvider->close() if it agrees to the other party seizing
1329 * the service. It is also called in IOService::didTerminate() and perhaps some other
1330 * odd places. The way to find out is to examin the pvArg, which would be including
1331 * kIOServiceSeize if it's the handleOpen case.
1332 *
1333 * How to validate that the other end is actually our VM process? Well, IOKit doesn't
1334 * provide any clue about the new client really. But fortunately, it seems like the
1335 * calling task/process context when the VM tries to open the device is the VM process.
1336 * We'll ASSUME this'll remain like this for now...
1337 */
1338 case kIOMessageServiceIsRequestingClose:
1339 irc = kIOReturnExclusiveAccess;
1340 /* If it's not a seize request, assume it's didTerminate and pray that it isn't a rouge driver.
1341 ... weird, doesn't seem to match for the post has-terminated messages. */
1342 if (!((uintptr_t)pvArg & kIOServiceSeize))
1343 {
1344 Log(("VBoxUSBDevice::message([%p],%p {%s}, %p) - pid=%d: not seize - closing...\n",
1345 this, pProvider, pProvider->getName(), pvArg, RTProcSelf()));
1346 m_fOpen = false;
1347 m_fOpenOnWasClosed = false;
1348 if (m_pDevice)
1349 m_pDevice->close(this, 0);
1350 m_Client = NIL_RTPROCESS;
1351 irc = kIOReturnSuccess;
1352 }
1353 else
1354 {
1355 if (org_virtualbox_VBoxUSBClient::isClientTask(current_task()))
1356 {
1357 Log(("VBoxUSBDevice::message([%p],%p {%s}, %p) - pid=%d task=%p: client process, closing.\n",
1358 this, pProvider, pProvider->getName(), pvArg, RTProcSelf(), current_task()));
1359 m_fOpen = false;
1360 m_fOpenOnWasClosed = false;
1361 if (m_pDevice)
1362 m_pDevice->close(this, 0);
1363 m_fOpenOnWasClosed = true;
1364 m_Client = RTProcSelf();
1365 irc = kIOReturnSuccess;
1366 }
1367 else
1368 Log(("VBoxUSBDevice::message([%p],%p {%s}, %p) - pid=%d task=%p: not client process!\n",
1369 this, pProvider, pProvider->getName(), pvArg, RTProcSelf(), current_task()));
1370 }
1371 if (!setProperty(VBOXUSB_CLIENT_KEY, (unsigned long long)m_Client, sizeof(m_Client) * 8 /* bits */))
1372 Log(("VBoxUSBDevice::message: failed to set the '" VBOXUSB_CLIENT_KEY "' property!\n"));
1373 break;
1374
1375 /*
1376 * The service was closed by the current client.
1377 * Update the client property, check for scheduled re-enumeration and re-open.
1378 *
1379 * Note that we will not be called if we're doing the closing. (Even if we was
1380 * called in that case, the code should be able to handle it.)
1381 */
1382 case kIOMessageServiceWasClosed:
1383 /*
1384 * Update the client property value.
1385 */
1386 if (m_Client != NIL_RTPROCESS)
1387 {
1388 m_Client = NIL_RTPROCESS;
1389 if (!setProperty(VBOXUSB_CLIENT_KEY, (unsigned long long)m_Client, sizeof(m_Client) * 8 /* bits */))
1390 Log(("VBoxUSBDevice::message: failed to set the '" VBOXUSB_CLIENT_KEY "' property!\n"));
1391 }
1392
1393 if (m_pDevice)
1394 {
1395 /*
1396 * Should we release the device?
1397 */
1398 if (ASMAtomicXchgBool(&m_fReleaseOnClose, false))
1399 {
1400 m_fOpenOnWasClosed = false;
1401 irc = m_pDevice->ReEnumerateDevice(0);
1402 Log(("VBoxUSBDevice::message([%p], %p {%s}) - ReEnumerateDevice() -> %#x\n",
1403 this, pProvider, pProvider->getName(), irc));
1404 }
1405 /*
1406 * Should we attempt to re-open the device?
1407 */
1408 else if (m_fOpenOnWasClosed)
1409 {
1410 Log(("VBoxUSBDevice::message: attempting to re-open the device...\n"));
1411 m_fOpenOnWasClosed = false;
1412 m_fOpen = m_pDevice->open(this, kIOServiceSeize, 0);
1413 if (!m_fOpen)
1414 Log(("VBoxUSBDevice::message: failed to open the device!\n"));
1415 m_fOpenOnWasClosed = !m_fOpen;
1416 }
1417 }
1418
1419 irc = IOUSBUserClientInit::message(enmMsg, pProvider, pvArg);
1420 break;
1421
1422 /*
1423 * The IOUSBDevice is shutting down, so close it if we've opened it.
1424 */
1425 case kIOMessageServiceIsTerminated:
1426 m_fBeingUnloaded = false;
1427 ASMAtomicWriteBool(&m_fReleaseOnClose, false);
1428 if (m_pDevice)
1429 {
1430 /* close it */
1431 if (m_fOpen)
1432 {
1433 m_fOpen = false;
1434 m_fOpenOnWasClosed = false;
1435 Log(("VBoxUSBDevice::message: closing the device (%p)...\n", m_pDevice));
1436 m_pDevice->close(this, 0);
1437 }
1438
1439 /* release it (see start()) */
1440 Log(("VBoxUSBDevice::message: releasing the device (%p)...\n", m_pDevice));
1441 m_pDevice->release();
1442 m_pDevice = NULL;
1443 }
1444
1445 irc = IOUSBUserClientInit::message(enmMsg, pProvider, pvArg);
1446 break;
1447
1448 default:
1449 irc = IOUSBUserClientInit::message(enmMsg, pProvider, pvArg);
1450 break;
1451 }
1452
1453 Log(("VBoxUSBDevice::message([%p], %#x {%s}, %p {%s}, %p) -> %#x\n",
1454 this, enmMsg, DbgGetIOKitMessageName(enmMsg), pProvider, pProvider->getName(), pvArg, irc));
1455 return irc;
1456}
1457
1458
1459/**
1460 * Schedule all devices belonging to the specified process for release.
1461 *
1462 * Devices that aren't currently in use will be released immediately.
1463 *
1464 * @param Owner The owner process.
1465 */
1466/* static */ void
1467org_virtualbox_VBoxUSBDevice::scheduleReleaseByOwner(RTPROCESS Owner)
1468{
1469 Log2(("VBoxUSBDevice::scheduleReleaseByOwner: Owner=%d\n", Owner));
1470 AssertReturnVoid(Owner && Owner != NIL_RTPROCESS);
1471
1472 /*
1473 * Walk the list of devices looking for device belonging to this process.
1474 *
1475 * If we release a device, we have to lave the spinlock and will therefore
1476 * have to restart the search.
1477 */
1478 VBOXUSB_LOCK();
1479
1480 org_virtualbox_VBoxUSBDevice *pCur;
1481 do
1482 {
1483 for (pCur = s_pHead; pCur; pCur = pCur->m_pNext)
1484 {
1485 Log2(("VBoxUSBDevice::scheduleReleaseByOwner: pCur=%p m_Owner=%d (%s) m_fReleaseOnClose=%d\n",
1486 pCur, pCur->m_Owner, pCur->m_Owner == Owner ? "match" : "mismatch", pCur->m_fReleaseOnClose));
1487 if (pCur->m_Owner == Owner)
1488 {
1489 /* make sure we won't hit it again. */
1490 pCur->m_Owner = NIL_RTPROCESS;
1491 IOUSBDevice *pDevice = pCur->m_pDevice;
1492 if ( pDevice
1493 && !pCur->m_fReleaseOnClose)
1494 {
1495 pCur->m_fOpenOnWasClosed = false;
1496 if (pCur->m_Client != NIL_RTPROCESS)
1497 {
1498 /* It's currently open, so just schedule it for re-enumeration on close. */
1499 ASMAtomicWriteBool(&pCur->m_fReleaseOnClose, true);
1500 Log(("VBoxUSBDevice::scheduleReleaseByOwner: %p {%s} - used by %d\n",
1501 pDevice, pDevice->getName(), pCur->m_Client));
1502 }
1503 else
1504 {
1505 /*
1506 * Get the USBDevice object and do the re-enumeration now.
1507 * Retain the device so we don't run into any trouble.
1508 */
1509 pDevice->retain();
1510 VBOXUSB_UNLOCK();
1511
1512 IOReturn irc = pDevice->ReEnumerateDevice(0); NOREF(irc);
1513 Log(("VBoxUSBDevice::scheduleReleaseByOwner: %p {%s} - ReEnumerateDevice -> %#x\n",
1514 pDevice, pDevice->getName(), irc));
1515
1516 pDevice->release();
1517 VBOXUSB_LOCK();
1518 break;
1519 }
1520 }
1521 }
1522 }
1523 } while (pCur);
1524
1525 VBOXUSB_UNLOCK();
1526}
1527
1528
1529#ifdef DEBUG
1530/*static*/ IOReturn
1531org_virtualbox_VBoxUSBDevice::MyInterestHandler(void *pvTarget, void *pvRefCon, UInt32 enmMsgType,
1532 IOService *pProvider, void * pvMsgArg, vm_size_t cbMsgArg)
1533{
1534 org_virtualbox_VBoxUSBDevice *pThis = (org_virtualbox_VBoxUSBDevice *)pvTarget;
1535 if (!pThis)
1536 return kIOReturnError;
1537
1538 switch (enmMsgType)
1539 {
1540 case kIOMessageServiceIsAttemptingOpen:
1541 /* pvMsgArg == the open() fOptions, so we could check for kIOServiceSeize if we care.
1542 We'll also get a kIIOServiceRequestingClose message() for that... */
1543 Log(("VBoxUSBDevice::MyInterestHandler: kIOMessageServiceIsAttemptingOpen - pvRefCon=%p pProvider=%p pvMsgArg=%p cbMsgArg=%d\n",
1544 pvRefCon, pProvider, pvMsgArg, cbMsgArg));
1545 break;
1546
1547 case kIOMessageServiceWasClosed:
1548 Log(("VBoxUSBDevice::MyInterestHandler: kIOMessageServiceWasClosed - pvRefCon=%p pProvider=%p pvMsgArg=%p cbMsgArg=%d\n",
1549 pvRefCon, pProvider, pvMsgArg, cbMsgArg));
1550 break;
1551
1552 case kIOMessageServiceIsTerminated:
1553 Log(("VBoxUSBDevice::MyInterestHandler: kIOMessageServiceIsTerminated - pvRefCon=%p pProvider=%p pvMsgArg=%p cbMsgArg=%d\n",
1554 pvRefCon, pProvider, pvMsgArg, cbMsgArg));
1555 break;
1556
1557 case kIOUSBMessagePortHasBeenReset:
1558 Log(("VBoxUSBDevice::MyInterestHandler: kIOUSBMessagePortHasBeenReset - pvRefCon=%p pProvider=%p pvMsgArg=%p cbMsgArg=%d\n",
1559 pvRefCon, pProvider, pvMsgArg, cbMsgArg));
1560 break;
1561
1562 default:
1563 Log(("VBoxUSBDevice::MyInterestHandler: %#x (%s) - pvRefCon=%p pProvider=%p pvMsgArg=%p cbMsgArg=%d\n",
1564 enmMsgType, DbgGetIOKitMessageName(enmMsgType), pvRefCon, pProvider, pvMsgArg, cbMsgArg));
1565 break;
1566 }
1567
1568 return kIOReturnSuccess;
1569}
1570#endif /* DEBUG */
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585/*
1586 *
1587 * org_virtualbox_VBoxUSBInterface
1588 *
1589 */
1590
1591/**
1592 * Initialize our data members.
1593 */
1594bool
1595org_virtualbox_VBoxUSBInterface::init(OSDictionary *pDictionary)
1596{
1597 uint32_t cInstances = ASMAtomicIncU32(&g_cInstances);
1598 Log(("VBoxUSBInterface::init([%p], %p) new g_cInstances=%d\n", this, pDictionary, cInstances));
1599
1600 m_pInterface = NULL;
1601 m_fOpen = false;
1602 m_fOpenOnWasClosed = false;
1603
1604 return IOUSBUserClientInit::init(pDictionary);
1605}
1606
1607
1608/**
1609 * Free the object.
1610 * @remark Only for logging.
1611 */
1612void
1613org_virtualbox_VBoxUSBInterface::free()
1614{
1615 uint32_t cInstances = ASMAtomicDecU32(&g_cInstances); NOREF(cInstances);
1616 Log(("VBoxUSBInterfaces::free([%p]) new g_cInstances=%d\n", this, cInstances));
1617 IOUSBUserClientInit::free();
1618}
1619
1620
1621/**
1622 * Probe the interface to see if we're the right driver for it.
1623 *
1624 * We implement this similarly to org_virtualbox_VBoxUSBDevice, except that
1625 * we don't bother matching filters but instead just check if the parent is
1626 * handled by org_virtualbox_VBoxUSBDevice or not.
1627 */
1628IOService *
1629org_virtualbox_VBoxUSBInterface::probe(IOService *pProvider, SInt32 *pi32Score)
1630{
1631 Log(("VBoxUSBInterface::probe([%p], %p {%s}, %p={%d})\n", this,
1632 pProvider, pProvider->getName(), pi32Score, pi32Score ? *pi32Score : 0));
1633
1634 /*
1635 * Check if VBoxUSBDevice is the parent's driver.
1636 */
1637 bool fHijackIt = false;
1638 const IORegistryPlane *pServicePlane = getPlane(kIOServicePlane);
1639 IORegistryEntry *pParent = pProvider->getParentEntry(pServicePlane);
1640 if (pParent)
1641 {
1642 Log(("VBoxUSBInterface::probe: pParent=%p {%s}\n", pParent, pParent->getName()));
1643
1644 OSIterator *pSiblings = pParent->getChildIterator(pServicePlane);
1645 if (pSiblings)
1646 {
1647 IORegistryEntry *pSibling;
1648 while ( (pSibling = OSDynamicCast(IORegistryEntry, pSiblings->getNextObject())) )
1649 {
1650 const OSMetaClass *pMetaClass = pSibling->getMetaClass();
1651 Log2(("sibling: %p - %s - %s\n", pMetaClass, pSibling->getName(), pMetaClass->getClassName()));
1652 if (pMetaClass == &org_virtualbox_VBoxUSBDevice::gMetaClass)
1653 {
1654 fHijackIt = true;
1655 break;
1656 }
1657 }
1658 pSiblings->release();
1659 }
1660 }
1661 if (!fHijackIt)
1662 {
1663 Log(("VBoxUSBInterface::probe: returns NULL\n"));
1664 return NULL;
1665 }
1666
1667 IOService *pRet = IOUSBUserClientInit::probe(pProvider, pi32Score);
1668 *pi32Score = _1G;
1669 Log(("VBoxUSBInterface::probe: returns %p and *pi32Score=%d - hijack it.\n", pRet, *pi32Score));
1670 return pRet;
1671}
1672
1673
1674/**
1675 * Start the driver (this), retain and open the USB interface object (pProvider).
1676 */
1677bool
1678org_virtualbox_VBoxUSBInterface::start(IOService *pProvider)
1679{
1680 Log(("VBoxUSBInterface::start([%p], %p {%s})\n", this, pProvider, pProvider->getName()));
1681
1682 /*
1683 * Exploit IOUSBUserClientInit to process IOProviderMergeProperties.
1684 */
1685 IOUSBUserClientInit::start(pProvider); /* returns false */
1686
1687 /*
1688 * Retain the and open the interface (stop() or message() cleans up).
1689 */
1690 bool fRc = true;
1691 m_pInterface = OSDynamicCast(IOUSBInterface, pProvider);
1692 if (m_pInterface)
1693 {
1694 m_pInterface->retain();
1695 m_fOpen = m_pInterface->open(this, kIOServiceSeize, 0);
1696 if (!m_fOpen)
1697 Log(("VBoxUSBInterface::start: failed to open the interface!\n"));
1698 m_fOpenOnWasClosed = !m_fOpen;
1699 }
1700 else
1701 {
1702 printf("VBoxUSBInterface::start([%p], %p {%s}): failed!\n", this, pProvider, pProvider->getName());
1703 fRc = false;
1704 }
1705
1706 Log(("VBoxUSBInterface::start: returns %d\n", fRc));
1707 return fRc;
1708}
1709
1710
1711/**
1712 * Close and release the USB interface object (pProvider) and stop the driver (this).
1713 */
1714void
1715org_virtualbox_VBoxUSBInterface::stop(IOService *pProvider)
1716{
1717 Log(("org_virtualbox_VBoxUSBInterface::stop([%p], %p {%s})\n", this, pProvider, pProvider->getName()));
1718
1719 /*
1720 * Close and release the IOUSBInterface if didn't do that already in message().
1721 */
1722 if (m_pInterface)
1723 {
1724 /* close it */
1725 if (m_fOpen)
1726 {
1727 m_fOpenOnWasClosed = false;
1728 m_fOpen = false;
1729 m_pInterface->close(this, 0);
1730 }
1731
1732 /* release it (see start()) */
1733 m_pInterface->release();
1734 m_pInterface = NULL;
1735 }
1736
1737 IOUSBUserClientInit::stop(pProvider);
1738 Log(("VBoxUSBInterface::stop: returns void\n"));
1739}
1740
1741
1742/**
1743 * Terminate the service (initiate the destruction).
1744 * @remark Only for logging.
1745 */
1746bool
1747org_virtualbox_VBoxUSBInterface::terminate(IOOptionBits fOptions)
1748{
1749 /* kIOServiceRecursing, kIOServiceRequired, kIOServiceTerminate, kIOServiceSynchronous - interesting option bits */
1750 Log(("VBoxUSBInterface::terminate([%p], %#x)\n", this, fOptions));
1751 return IOUSBUserClientInit::terminate(fOptions);
1752}
1753
1754
1755/**
1756 * @copydoc org_virtualbox_VBoxUSBDevice::message
1757 */
1758IOReturn
1759org_virtualbox_VBoxUSBInterface::message(UInt32 enmMsg, IOService *pProvider, void *pvArg)
1760{
1761 Log(("VBoxUSBInterface::message([%p], %#x {%s}, %p {%s}, %p)\n",
1762 this, enmMsg, DbgGetIOKitMessageName(enmMsg), pProvider, pProvider->getName(), pvArg));
1763
1764 IOReturn irc;
1765 switch (enmMsg)
1766 {
1767 /*
1768 * See explanation in org_virtualbox_VBoxUSBDevice::message.
1769 */
1770 case kIOMessageServiceIsRequestingClose:
1771 irc = kIOReturnExclusiveAccess;
1772 if (!((uintptr_t)pvArg & kIOServiceSeize))
1773 {
1774 Log(("VBoxUSBInterface::message([%p],%p {%s}, %p) - pid=%d: not seize - closing...\n",
1775 this, pProvider, pProvider->getName(), pvArg, RTProcSelf()));
1776 m_fOpen = false;
1777 m_fOpenOnWasClosed = false;
1778 if (m_pInterface)
1779 m_pInterface->close(this, 0);
1780 irc = kIOReturnSuccess;
1781 }
1782 else
1783 {
1784 if (org_virtualbox_VBoxUSBClient::isClientTask(current_task()))
1785 {
1786 Log(("VBoxUSBInterface::message([%p],%p {%s}, %p) - pid=%d task=%p: client process, closing.\n",
1787 this, pProvider, pProvider->getName(), pvArg, RTProcSelf(), current_task()));
1788 m_fOpen = false;
1789 m_fOpenOnWasClosed = false;
1790 if (m_pInterface)
1791 m_pInterface->close(this, 0);
1792 m_fOpenOnWasClosed = true;
1793 irc = kIOReturnSuccess;
1794 }
1795 else
1796 Log(("VBoxUSBInterface::message([%p],%p {%s}, %p) - pid=%d task=%p: not client process!\n",
1797 this, pProvider, pProvider->getName(), pvArg, RTProcSelf(), current_task()));
1798 }
1799 break;
1800
1801 /*
1802 * The service was closed by the current client, check for re-open.
1803 */
1804 case kIOMessageServiceWasClosed:
1805 if (m_pInterface && m_fOpenOnWasClosed)
1806 {
1807 Log(("VBoxUSBInterface::message: attempting to re-open the interface...\n"));
1808 m_fOpenOnWasClosed = false;
1809 m_fOpen = m_pInterface->open(this, kIOServiceSeize, 0);
1810 if (!m_fOpen)
1811 Log(("VBoxUSBInterface::message: failed to open the interface!\n"));
1812 m_fOpenOnWasClosed = !m_fOpen;
1813 }
1814
1815 irc = IOUSBUserClientInit::message(enmMsg, pProvider, pvArg);
1816 break;
1817
1818 /*
1819 * The IOUSBInterface/Device is shutting down, so close and release.
1820 */
1821 case kIOMessageServiceIsTerminated:
1822 if (m_pInterface)
1823 {
1824 /* close it */
1825 if (m_fOpen)
1826 {
1827 m_fOpen = false;
1828 m_fOpenOnWasClosed = false;
1829 m_pInterface->close(this, 0);
1830 }
1831
1832 /* release it (see start()) */
1833 m_pInterface->release();
1834 m_pInterface = NULL;
1835 }
1836
1837 irc = IOUSBUserClientInit::message(enmMsg, pProvider, pvArg);
1838 break;
1839
1840 default:
1841 irc = IOUSBUserClientInit::message(enmMsg, pProvider, pvArg);
1842 break;
1843 }
1844
1845 Log(("VBoxUSBInterface::message([%p], %#x {%s}, %p {%s}, %p) -> %#x\n",
1846 this, enmMsg, DbgGetIOKitMessageName(enmMsg), pProvider, pProvider->getName(), pvArg, irc));
1847 return irc;
1848}
1849
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