VirtualBox

source: vbox/trunk/include/VBox/pdmusb.h@ 8006

Last change on this file since 8006 was 7768, checked in by vboxsync, 16 years ago

Added a VMState dev/usb/drvhlp.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 30.0 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, USB Devices.
3 */
4
5/*
6 * Copyright (C) 2006-2007 innotek GmbH
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_pdmusb_h
27#define ___VBox_pdmusb_h
28
29#include <VBox/pdmqueue.h>
30#include <VBox/pdmcritsect.h>
31#include <VBox/pdmthread.h>
32#include <VBox/pdmifs.h>
33#include <VBox/tm.h>
34#include <VBox/ssm.h>
35#include <VBox/cfgm.h>
36#include <VBox/dbgf.h>
37#include <VBox/mm.h>
38#include <VBox/err.h>
39#include <VBox/vusb.h>
40#include <iprt/stdarg.h>
41
42__BEGIN_DECLS
43
44/** @defgroup grp_pdm_usbdev USB Devices
45 * @ingroup grp_pdm
46 * @{
47 */
48
49/**
50 * USB descriptor cache.
51 *
52 * This structure is owned by the USB device but provided to the PDM/VUSB layer
53 * thru the PDMUSBREG::pfnGetDescriptorCache method. PDM/VUSB will use the
54 * information here to map addresses to endpoints, perform SET_CONFIGURATION
55 * requests, and optionally perform GET_DESCRIPTOR requests (see flag).
56 *
57 * Currently, only device and configuration descriptors are cached.
58 */
59typedef struct PDMUSBDESCCACHE
60{
61 /** USB device descriptor */
62 PCVUSBDESCDEVICE pDevice;
63 /** USB Descriptor arrays (pDev->bNumConfigurations) */
64 PCVUSBDESCCONFIGEX paConfigs;
65 /** Use the cached descriptors for GET_DESCRIPTOR requests. */
66 bool fUseCachedDescriptors;
67} PDMUSBDESCCACHE;
68/** Pointer to an USB descriptor cache. */
69typedef PDMUSBDESCCACHE *PPDMUSBDESCCACHE;
70/** Pointer to a const USB descriptor cache. */
71typedef const PDMUSBDESCCACHE *PCPDMUSBDESCCACHE;
72
73
74
75/** PDM USB Device Registration Structure,
76 *
77 * This structure is used when registering a device from VBoxUsbRegister() in HC Ring-3.
78 * The PDM will make use of this structure untill the VM is destroyed.
79 */
80typedef struct PDMUSBREG
81{
82 /** Structure version. PDM_DEVREG_VERSION defines the current version. */
83 uint32_t u32Version;
84 /** Device name. */
85 char szDeviceName[32];
86 /** The description of the device. The UTF-8 string pointed to shall, like this structure,
87 * remain unchanged from registration till VM destruction. */
88 const char *pszDescription;
89
90 /** Flags, combination of the PDM_USBREG_FLAGS_* \#defines. */
91 RTUINT fFlags;
92 /** Maximum number of instances (per VM). */
93 RTUINT cMaxInstances;
94 /** Size of the instance data. */
95 RTUINT cbInstance;
96
97
98 /**
99 * Construct an USB device instance for a VM.
100 *
101 * @returns VBox status.
102 * @param pUsbIns The USB device instance data.
103 * If the registration structure is needed, pUsbDev->pDevReg points to it.
104 * @param iInstance Instance number. Use this to figure out which registers and such to use.
105 * The instance number is also found in pUsbDev->iInstance, but since it's
106 * likely to be freqently used PDM passes it as parameter.
107 * @param pCfg Configuration node handle for the device. Use this to obtain the configuration
108 * of the device instance. It's also found in pUsbDev->pCfg, but since it's
109 * primary usage will in this function it's passed as a parameter.
110 * @param pCfgGlobal Handle to the global device configuration. Also found in pUsbDev->pCfgGlobal.
111 * @remarks This callback is required.
112 */
113 DECLR3CALLBACKMEMBER(int, pfnConstruct,(PPDMUSBINS pUsbIns, int iInstance, PCFGMNODE pCfg, PCFGMNODE pCfgGlobal));
114
115 /**
116 * Destruct an USB device instance.
117 *
118 * Most VM resources are freed by the VM. This callback is provided so that any non-VM
119 * resources can be freed correctly.
120 *
121 * This method will be called regardless of the pfnConstruc result to avoid
122 * complicated failure paths.
123 *
124 * @param pUsbIns The USB device instance data.
125 * @remarks Optional.
126 */
127 DECLR3CALLBACKMEMBER(void, pfnDestruct,(PPDMUSBINS pUsbIns));
128
129
130 /**
131 * Init complete notification.
132 *
133 * This can be done to do communication with other devices and other
134 * initialization which requires everything to be in place.
135 *
136 * @returns VBOX status code.
137 * @param pUsbIns The USB device instance data.
138 * @remarks Optional.
139 * @remarks Not called when hotplugged.
140 */
141 DECLR3CALLBACKMEMBER(int, pfnVMInitComplete,(PPDMUSBINS pUsbIns));
142
143 /**
144 * VM Power On notification.
145 *
146 * @returns VBox status.
147 * @param pUsbIns The USB device instance data.
148 * @remarks Optional.
149 */
150 DECLR3CALLBACKMEMBER(void, pfnVMPowerOn,(PPDMUSBINS pUsbIns));
151
152 /**
153 * VM Reset notification.
154 *
155 * @returns VBox status.
156 * @param pUsbIns The USB device instance data.
157 * @remarks Optional.
158 */
159 DECLR3CALLBACKMEMBER(void, pfnVMReset,(PPDMUSBINS pUsbIns));
160
161 /**
162 * VM Suspend notification.
163 *
164 * @returns VBox status.
165 * @param pUsbIns The USB device instance data.
166 * @remarks Optional.
167 */
168 DECLR3CALLBACKMEMBER(void, pfnVMSuspend,(PPDMUSBINS pUsbIns));
169
170 /**
171 * VM Resume notification.
172 *
173 * @returns VBox status.
174 * @param pUsbIns The USB device instance data.
175 * @remarks Optional.
176 */
177 DECLR3CALLBACKMEMBER(void, pfnVMResume,(PPDMUSBINS pUsbIns));
178
179 /**
180 * VM Power Off notification.
181 *
182 * @param pUsbIns The USB device instance data.
183 */
184 DECLR3CALLBACKMEMBER(void, pfnVMPowerOff,(PPDMUSBINS pUsbIns));
185
186 /**
187 * Called after the constructor when attaching a device at run time.
188 *
189 * This can be used to do tasks normally assigned to pfnInitComplete and/or pfnVMPowerOn.
190 *
191 * @returns VBox status.
192 * @param pUsbIns The USB device instance data.
193 * @remarks Optional.
194 */
195 DECLR3CALLBACKMEMBER(void, pfnHotPlugged,(PPDMUSBINS pUsbIns));
196
197 /**
198 * Called before the destructor when a device is unplugged at run time.
199 *
200 * This can be used to do tasks normally assigned to pfnVMSuspend and/or pfnVMPowerOff.
201 *
202 * @returns VBox status.
203 * @param pUsbIns The USB device instance data.
204 * @remarks Optional.
205 */
206 DECLR3CALLBACKMEMBER(void, pfnHotUnplugged,(PPDMUSBINS pUsbIns));
207 /**
208 * Driver Attach command.
209 *
210 * This is called to let the USB device attach to a driver for a specified LUN
211 * at runtime. This is not called during VM construction, the device constructor
212 * have to attach to all the available drivers.
213 *
214 * @returns VBox status code.
215 * @param pUsbIns The USB device instance data.
216 * @param iLUN The logical unit which is being detached.
217 * @remarks Optional.
218 */
219 DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMUSBINS pUsbIns, unsigned iLUN));
220
221 /**
222 * Driver Detach notification.
223 *
224 * This is called when a driver is detaching itself from a LUN of the device.
225 * The device should adjust it's state to reflect this.
226 *
227 * @param pUsbIns The USB device instance data.
228 * @param iLUN The logical unit which is being detached.
229 * @remarks Optional.
230 */
231 DECLR3CALLBACKMEMBER(void, pfnDriverDetach,(PPDMUSBINS pUsbIns, unsigned iLUN));
232
233 /**
234 * Query the base interface of a logical unit.
235 *
236 * @returns VBOX status code.
237 * @param pUsbIns The USB device instance data.
238 * @param iLUN The logicial unit to query.
239 * @param ppBase Where to store the pointer to the base interface of the LUN.
240 * @remarks Optional.
241 */
242 DECLR3CALLBACKMEMBER(int, pfnQueryInterface,(PPDMUSBINS pUsbIns, unsigned iLUN, PPDMIBASE *ppBase));
243
244 /**
245 * Requests the USB device to reset.
246 *
247 * @returns VBox status code.
248 * @param pUsbIns The USB device instance.
249 * @param fResetOnLinux A hint to the usb proxy.
250 * Don't use this unless you're the linux proxy device.
251 * @thread Any thread.
252 * @remarks Optional.
253 */
254 DECLR3CALLBACKMEMBER(int, pfnUsbReset,(PPDMUSBINS pUsbIns, bool fResetOnLinux));
255
256 /**
257 * Query device and configuration descriptors for the caching and servicing
258 * relevant GET_DESCRIPTOR requests.
259 *
260 * @returns Pointer to the descriptor cache (read-only).
261 * @param pUsbIns The USB device instance.
262 * @remarks Mandatory.
263 */
264 DECLR3CALLBACKMEMBER(PCPDMUSBDESCCACHE, pfnUsbGetDescriptorCache,(PPDMUSBINS pUsbIns));
265
266 /**
267 * SET_CONFIGURATION request.
268 *
269 * @returns VBox status code.
270 * @param pUsbIns The USB device instance.
271 * @param bConfigurationValue The bConfigurationValue of the new configuration.
272 * @param pvOldCfgDesc Internal - for the device proxy.
273 * @param pvOldIfState Internal - for the device proxy.
274 * @param pvNewCfgDesc Internal - for the device proxy.
275 * @remarks Optional.
276 */
277 DECLR3CALLBACKMEMBER(int, pfnUsbSetConfiguration,(PPDMUSBINS pUsbIns, uint8_t bConfigurationValue,
278 const void *pvOldCfgDesc, const void *pvOldIfState, const void *pvNewCfgDesc));
279
280 /**
281 * SET_INTERFACE request.
282 *
283 * @returns VBox status code.
284 * @param pUsbIns The USB device instance.
285 * @param bInterfaceNumber The interface number.
286 * @param bAlternateSetting The alternate setting.
287 * @remarks Optional.
288 */
289 DECLR3CALLBACKMEMBER(int, pfnUsbSetInterface,(PPDMUSBINS pUsbIns, uint8_t bInterfaceNumber, uint8_t bAlternateSetting));
290
291 /**
292 * Clears the halted state of an endpoint. (Optional)
293 *
294 * This called when VUSB sees a CLEAR_FEATURE(ENDPOINT_HALT) on request
295 * on the zero pipe.
296 *
297 * @returns VBox status code.
298 * @param pUsbIns The USB device instance.
299 * @param uEndpoint The endpoint to clear.
300 * @remarks Optional.
301 */
302 DECLR3CALLBACKMEMBER(int, pfnUsbClearHaltedEndpoint,(PPDMUSBINS pUsbIns, unsigned uEndpoint));
303
304 /**
305 * Allocates an URB.
306 *
307 * This can be used to make use of shared user/kernel mode buffers.
308 *
309 * @returns VBox status code.
310 * @param pUsbIns The USB device instance.
311 * @param cbData The size of the data buffer.
312 * @param cTds The number of TDs.
313 * @param enmType The type of URB.
314 * @param ppUrb Where to store the allocated URB.
315 * @remarks Optional.
316 * @remarks Not implemented yet.
317 */
318 DECLR3CALLBACKMEMBER(int, pfnUrbNew,(PPDMUSBINS pUsbIns, size_t cbData, size_t cTds, VUSBXFERTYPE enmType, PVUSBURB *ppUrb));
319
320 /**
321 * Queues an URB for processing.
322 *
323 * @returns VBox status code.
324 * @retval VINF_SUCCESS on success.
325 * @retval VERR_VUSB_DEVICE_NOT_ATTACHED if the device has been disconnected.
326 * @retval VERR_VUSB_FAILED_TO_QUEUE_URB as a general failure kind of thing.
327 * @retval TBD - document new stuff!
328 *
329 * @param pUsbIns The USB device instance.
330 * @param pUrb The URB to process.
331 * @remarks Mandatory.
332 */
333 DECLR3CALLBACKMEMBER(int, pfnUrbQueue,(PPDMUSBINS pUsbIns, PVUSBURB pUrb));
334
335 /**
336 * Cancels an URB.
337 *
338 * @returns VBox status code.
339 * @param pUsbIns The USB device instance.
340 * @param pUrb The URB to cancel.
341 * @remarks Mandatory.
342 */
343 DECLR3CALLBACKMEMBER(int, pfnUrbCancel,(PPDMUSBINS pUsbIns, PVUSBURB pUrb));
344
345 /**
346 * Reaps an URB.
347 *
348 * @returns A ripe URB, NULL if none.
349 * @param pUsbIns The USB device instance.
350 * @param cMillies How log to wait for an URB to become ripe.
351 * @remarks Mandatory.
352 */
353 DECLR3CALLBACKMEMBER(PVUSBURB, pfnUrbReap,(PPDMUSBINS pUsbIns, unsigned cMillies));
354
355
356 /** Just some init precaution. Must be set to PDM_USBREG_VERSION. */
357 uint32_t u32TheEnd;
358} PDMUSBREG;
359/** Pointer to a PDM USB Device Structure. */
360typedef PDMUSBREG *PPDMUSBREG;
361/** Const pointer to a PDM USB Device Structure. */
362typedef PDMUSBREG const *PCPDMUSBREG;
363
364/** Current USBREG version number. */
365#define PDM_USBREG_VERSION 0xed010000
366
367/** PDM USB Device Flags.
368 * @{ */
369/* none yet */
370/** @} */
371
372#ifdef IN_RING3
373/**
374 * PDM USB Device API.
375 */
376typedef struct PDMUSBHLP
377{
378 /** Structure version. PDM_USBHLP_VERSION defines the current version. */
379 uint32_t u32Version;
380
381 /**
382 * Attaches a driver (chain) to the USB device.
383 *
384 * The first call for a LUN this will serve as a registartion of the LUN. The pBaseInterface and
385 * the pszDesc string will be registered with that LUN and kept around for PDMR3QueryUSBDeviceLun().
386 *
387 * @returns VBox status code.
388 * @param pUsbIns The USB device instance.
389 * @param iLun The logical unit to attach.
390 * @param pBaseInterface Pointer to the base interface for that LUN. (device side / down)
391 * @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up)
392 * @param pszDesc Pointer to a string describing the LUN. This string must remain valid
393 * for the live of the device instance.
394 */
395 DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMUSBINS pUsbIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE *ppBaseInterface, const char *pszDesc));
396
397 /**
398 * Assert that the current thread is the emulation thread.
399 *
400 * @returns True if correct.
401 * @returns False if wrong.
402 * @param pUsbIns The USB device instance.
403 * @param pszFile Filename of the assertion location.
404 * @param iLine Linenumber of the assertion location.
405 * @param pszFunction Function of the assertion location.
406 */
407 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMUSBINS pUsbIns, const char *pszFile, unsigned iLine, const char *pszFunction));
408
409 /**
410 * Assert that the current thread is NOT the emulation thread.
411 *
412 * @returns True if correct.
413 * @returns False if wrong.
414 * @param pUsbIns The USB device instance.
415 * @param pszFile Filename of the assertion location.
416 * @param iLine Linenumber of the assertion location.
417 * @param pszFunction Function of the assertion location.
418 */
419 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMUSBINS pUsbIns, const char *pszFile, unsigned iLine, const char *pszFunction));
420
421 /**
422 * Stops the VM and enters the debugger to look at the guest state.
423 *
424 * Use the PDMUsbDBGFStop() inline function with the RT_SRC_POS macro instead of
425 * invoking this function directly.
426 *
427 * @returns VBox status code which must be passed up to the VMM.
428 * @param pUsbIns The USB device instance.
429 * @param pszFile Filename of the assertion location.
430 * @param iLine The linenumber of the assertion location.
431 * @param pszFunction Function of the assertion location.
432 * @param pszFormat Message. (optional)
433 * @param va Message parameters.
434 */
435 DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMUSBINS pUsbIns, const char *pszFile, unsigned iLine, const char *pszFunction, const char *pszFormat, va_list va));
436
437 /**
438 * Register a info handler with DBGF,
439 *
440 * @returns VBox status code.
441 * @param pUsbIns The USB device instance.
442 * @param pszName The identifier of the info.
443 * @param pszDesc The description of the info and any arguments the handler may take.
444 * @param pfnHandler The handler function to be called to display the info.
445 */
446/** @todo DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMUSBINS pUsbIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERUSB pfnHandler)); */
447
448 /**
449 * Allocate memory which is associated with current VM instance
450 * and automatically freed on it's destruction.
451 *
452 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
453 * @param pUsbIns The USB device instance.
454 * @param cb Number of bytes to allocate.
455 */
456 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMUSBINS pUsbIns, size_t cb));
457
458 /**
459 * Allocate memory which is associated with current VM instance
460 * and automatically freed on it's destruction. The memory is ZEROed.
461 *
462 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
463 * @param pUsbIns The USB device instance.
464 * @param cb Number of bytes to allocate.
465 */
466 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAllocZ,(PPDMUSBINS pUsbIns, size_t cb));
467
468 /**
469 * Create a queue.
470 *
471 * @returns VBox status code.
472 * @param pUsbIns The USB device instance.
473 * @param cbItem Size a queue item.
474 * @param cItems Number of items in the queue.
475 * @param cMilliesInterval Number of milliseconds between polling the queue.
476 * If 0 then the emulation thread will be notified whenever an item arrives.
477 * @param pfnCallback The consumer function.
478 * @param ppQueue Where to store the queue handle on success.
479 * @thread The emulation thread.
480 */
481/** @todo DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMUSBINS pUsbIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, PFNPDMQUEUEUSB pfnCallback, PPDMQUEUE *ppQueue)); */
482
483 /**
484 * Register a save state data unit.
485 *
486 * @returns VBox status.
487 * @param pUsbIns The USB device instance.
488 * @param pszName Data unit name.
489 * @param u32Instance The instance identifier of the data unit.
490 * This must together with the name be unique.
491 * @param u32Version Data layout version number.
492 * @param cbGuess The approximate amount of data in the unit.
493 * Only for progress indicators.
494 * @param pfnSavePrep Prepare save callback, optional.
495 * @param pfnSaveExec Execute save callback, optional.
496 * @param pfnSaveDone Done save callback, optional.
497 * @param pfnLoadPrep Prepare load callback, optional.
498 * @param pfnLoadExec Execute load callback, optional.
499 * @param pfnLoadDone Done load callback, optional.
500 */
501/** @todo DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMUSBINS pUsbIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
502 PFNSSMUSBSAVEPREP pfnSavePrep, PFNSSMUSBSAVEEXEC pfnSaveExec, PFNSSMUSBSAVEDONE pfnSaveDone,
503 PFNSSMUSBLOADPREP pfnLoadPrep, PFNSSMUSBLOADEXEC pfnLoadExec, PFNSSMUSBLOADDONE pfnLoadDone)); */
504
505 /**
506 * Register a STAM sample.
507 *
508 * Use the PDMUsbHlpSTAMRegister wrapper.
509 *
510 * @returns VBox status.
511 * @param pUsbIns The USB device instance.
512 * @param pvSample Pointer to the sample.
513 * @param enmType Sample type. This indicates what pvSample is pointing at.
514 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
515 * @param enmUnit Sample unit.
516 * @param pszDesc Sample description.
517 * @param pszName The sample name format string.
518 * @param va Arguments to the format string.
519 */
520 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMUSBINS pUsbIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
521 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list va));
522
523 /**
524 * Creates a timer.
525 *
526 * @returns VBox status.
527 * @param pUsbIns The USB device instance.
528 * @param enmClock The clock to use on this timer.
529 * @param pfnCallback Callback function.
530 * @param pszDesc Pointer to description string which must stay around
531 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
532 * @param ppTimer Where to store the timer on success.
533 */
534/** @todo DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMUSBINS pUsbIns, TMCLOCK enmClock, PFNTMTIMERUSB pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer)); */
535
536 /**
537 * Set the VM error message
538 *
539 * @returns rc.
540 * @param pUsbIns The USB device instance.
541 * @param rc VBox status code.
542 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
543 * @param pszFormat Error message format string.
544 * @param va Error message arguments.
545 */
546 DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMUSBINS pUsbIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
547
548 /**
549 * Set the VM runtime error message
550 *
551 * @returns VBox status code.
552 * @param pUsbIns The USB device instance.
553 * @param fFatal Whether it is a fatal error or not.
554 * @param pszErrorID Error ID string.
555 * @param pszFormat Error message format string.
556 * @param va Error message arguments.
557 */
558 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMUSBINS pUsbIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));
559
560 /**
561 * Gets the VM state.
562 *
563 * @returns VM state.
564 * @param pUsbIns The USB device instance.
565 * @thread Any thread (just keep in mind that it's volatile info).
566 */
567 DECLR3CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMUSBINS pUsbIns));
568
569 /** Just a safety precaution. */
570 uint32_t u32TheEnd;
571} PDMUSBHLP;
572/** Pointer PDM USB Device API. */
573typedef PDMUSBHLP *PPDMUSBHLP;
574/** Pointer const PDM USB Device API. */
575typedef const PDMUSBHLP *PCPDMUSBHLP;
576
577/** Current USBHLP version number. */
578#define PDM_USBHLP_VERSION 0xec020001
579
580#endif /* IN_RING3 */
581
582/**
583 * PDM USB Device Instance.
584 */
585typedef struct PDMUSBINS
586{
587 /** Structure version. PDM_USBINS_VERSION defines the current version. */
588 uint32_t u32Version;
589 /** USB device instance number. */
590 RTUINT iInstance;
591 /** The base interface of the device.
592 * The device constructor initializes this if it has any device level
593 * interfaces to export. To obtain this interface call PDMR3QueryUSBDevice(). */
594 PDMIBASE IBase;
595#if HC_ARCH_BITS == 32
596 uint32_t u32Alignment; /**< Alignment padding. */
597#endif
598
599 /** Internal data. */
600 union
601 {
602#ifdef PDMUSBINSINT_DECLARED
603 PDMUSBINSINT s;
604#endif
605 uint8_t padding[HC_ARCH_BITS == 32 ? 64 : 96];
606 } Internal;
607
608 /** Pointer the PDM USB Device API. */
609 R3PTRTYPE(PCPDMUSBHLP) pUsbHlp;
610 /** Pointer to the USB device registration structure. */
611 R3PTRTYPE(PCPDMUSBREG) pUsbReg;
612 /** Configuration handle. */
613 R3PTRTYPE(PCFGMNODE) pCfg;
614 /** The (device) global configuration handle. */
615 R3PTRTYPE(PCFGMNODE) pCfgGlobal;
616 /** Pointer to device instance data. */
617 R3PTRTYPE(void *) pvInstanceDataR3;
618 /** Pointer to the VUSB Device structure.
619 * Internal to VUSB, don't touch.
620 * @todo Moved this to PDMUSBINSINT. */
621 R3PTRTYPE(void *) pvVUsbDev2;
622 /** Device name for using when logging.
623 * The constructor sets this and the destructor frees it. */
624 R3PTRTYPE(char *) pszName;
625 /** Padding to make achInstanceData aligned at 32 byte boundrary. */
626 uint32_t au32Padding[HC_ARCH_BITS == 32 ? 5 : 2];
627 /** Device instance data. The size of this area is defined
628 * in the PDMUSBREG::cbInstanceData field. */
629 char achInstanceData[8];
630} PDMUSBINS;
631
632/** Current USBINS version number. */
633#define PDM_USBINS_VERSION 0xf3010000
634
635/** Converts a pointer to the PDMUSBINS::IBase to a pointer to PDMUSBINS. */
636#define PDMIBASE_2_PDMUSB(pInterface) ( (PPDMUSBINS)((char *)(pInterface) - RT_OFFSETOF(PDMUSBINS, IBase)) )
637
638
639/** @def PDMUSB_ASSERT_EMT
640 * Assert that the current thread is the emulation thread.
641 */
642#ifdef VBOX_STRICT
643# define PDMUSB_ASSERT_EMT(pUsbIns) pUsbIns->pUsbHlp->pfnAssertEMT(pUsbIns, __FILE__, __LINE__, __FUNCTION__)
644#else
645# define PDMUSB_ASSERT_EMT(pUsbIns) do { } while (0)
646#endif
647
648/** @def PDMUSB_ASSERT_OTHER
649 * Assert that the current thread is NOT the emulation thread.
650 */
651#ifdef VBOX_STRICT
652# define PDMUSB_ASSERT_OTHER(pUsbIns) pUsbIns->pUsbHlp->pfnAssertOther(pUsbIns, __FILE__, __LINE__, __FUNCTION__)
653#else
654# define PDMUSB_ASSERT_OTHER(pUsbIns) do { } while (0)
655#endif
656
657/** @def PDMUSB_SET_ERROR
658 * Set the VM error. See PDMDevHlpVMSetError() for printf like message formatting.
659 */
660#define PDMUSB_SET_ERROR(pUsbIns, rc, pszError) \
661 PDMDevHlpVMSetError(pUsbIns, rc, RT_SRC_POS, "%s", pszError)
662
663/** @def PDMUSB_SET_RUNTIME_ERROR
664 * Set the VM runtime error. See PDMDevHlpVMSetRuntimeError() for printf like message formatting.
665 */
666#define PDMUSB_SET_RUNTIME_ERROR(pUsbIns, fFatal, pszErrorID, pszError) \
667 PDMDevHlpVMSetRuntimeError(pUsbIns, fFatal, pszErrorID, "%s", pszError)
668
669
670#ifdef IN_RING3
671
672/**
673 * VBOX_STRICT wrapper for pUsbHlp->pfnDBGFStopV.
674 *
675 * @returns VBox status code which must be passed up to the VMM.
676 * @param pUsbIns Device instance.
677 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
678 * @param pszFormat Message. (optional)
679 * @param ... Message parameters.
680 */
681DECLINLINE(int) PDMUsbDBGFStop(PPDMUSBINS pUsbIns, RT_SRC_POS_DECL, const char *pszFormat, ...)
682{
683#ifdef VBOX_STRICT
684 int rc;
685 va_list va;
686 va_start(va, pszFormat);
687 rc = pUsbIns->pUsbHlp->pfnDBGFStopV(pUsbIns, RT_SRC_POS_ARGS, pszFormat, va);
688 va_end(va);
689 return rc;
690#else
691 return VINF_SUCCESS;
692#endif
693}
694
695/**
696 * @copydoc PDMUSBHLP::pfnVMState
697 */
698DECLINLINE(VMSTATE) PDMUsbHlpVMState(PPDMUSBINS pUsbIns)
699{
700 return pUsbIns->pUsbHlp->pfnVMState(pUsbIns);
701}
702
703#endif /* IN_RING3 */
704
705
706
707/** Pointer to callbacks provided to the VBoxUsbRegister() call. */
708typedef const struct PDMUSBREGCB *PCPDMUSBREGCB;
709
710/**
711 * Callbacks for VBoxUSBDeviceRegister().
712 */
713typedef struct PDMUSBREGCB
714{
715 /** Interface version.
716 * This is set to PDM_USBREG_CB_VERSION. */
717 uint32_t u32Version;
718
719 /**
720 * Registers a device with the current VM instance.
721 *
722 * @returns VBox status code.
723 * @param pCallbacks Pointer to the callback table.
724 * @param pDevReg Pointer to the device registration record.
725 * This data must be permanent and readonly.
726 */
727 DECLR3CALLBACKMEMBER(int, pfnRegister,(PCPDMUSBREGCB pCallbacks, PCPDMUSBREG pDevReg));
728
729 /**
730 * Allocate memory which is associated with current VM instance
731 * and automatically freed on it's destruction.
732 *
733 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
734 * @param pCallbacks Pointer to the callback table.
735 * @param cb Number of bytes to allocate.
736 */
737 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PCPDMUSBREGCB pCallbacks, size_t cb));
738} PDMUSBREGCB;
739
740/** Current version of the PDMUSBREGCB structure. */
741#define PDM_USBREG_CB_VERSION 0xee010000
742
743
744/**
745 * The VBoxUsbRegister callback function.
746 *
747 * PDM will invoke this function after loading a USB device module and letting
748 * the module decide which devices to register and how to handle conflicts.
749 *
750 * @returns VBox status code.
751 * @param pCallbacks Pointer to the callback table.
752 * @param u32Version VBox version number.
753 */
754typedef DECLCALLBACK(int) FNPDMVBOXUSBREGISTER(PCPDMUSBREGCB pCallbacks, uint32_t u32Version);
755
756
757/**
758 * Creates a USB proxy device instance.
759 *
760 * This will find an appropriate HUB for the USB device, create the necessary CFGM stuff
761 * and try instantiate the proxy device.
762 *
763 * @returns VBox status code.
764 * @param pVM The VM handle.
765 * @param pUuid The UUID thats to be associated with the device.
766 * @param fRemote Whether it's a remove or local device.
767 * @param pszAddress The address string.
768 * @param pvBackend Pointer to the backend.
769 * @param iUsbVersion The preferred USB version.
770 * @param fMaskedIfs The interfaces to hide from the guest.
771 */
772PDMR3DECL(int) PDMR3USBCreateProxyDevice(PVM pVM, PCRTUUID pUuid, bool fRemote, const char *pszAddress, void *pvBackend,
773 uint32_t iUsbVersion, uint32_t fMaskedIfs);
774
775/**
776 * Detaches and destroys a USB device.
777 *
778 * @returns VBox status code.
779 * @param pVM The VM handle.
780 * @param pUuid The UUID associated with the device to detach.
781 * @thread EMT
782 */
783PDMR3DECL(int) PDMR3USBDetachDevice(PVM pVM, PCRTUUID pUuid);
784
785/**
786 * Checks if there are any USB hubs attached.
787 *
788 * @returns true / false accordingly.
789 * @param pVM Pointer to the shared VM structure.
790 */
791PDMR3DECL(bool) PDMR3USBHasHub(PVM pVM);
792
793
794/** @} */
795
796__END_DECLS
797
798#endif
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use