1 | /** @file
|
---|
2 | * PDM - Pluggable Device Manager, USB Devices.
|
---|
3 | */
|
---|
4 |
|
---|
5 | /*
|
---|
6 | * Copyright (C) 2006-2016 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_vmm_pdmusb_h
|
---|
27 | #define ___VBox_vmm_pdmusb_h
|
---|
28 |
|
---|
29 | #include <VBox/vmm/pdmqueue.h>
|
---|
30 | #include <VBox/vmm/pdmcritsect.h>
|
---|
31 | #include <VBox/vmm/pdmthread.h>
|
---|
32 | #include <VBox/vmm/pdmifs.h>
|
---|
33 | #include <VBox/vmm/pdmcommon.h>
|
---|
34 | #include <VBox/vmm/tm.h>
|
---|
35 | #include <VBox/vmm/ssm.h>
|
---|
36 | #include <VBox/vmm/cfgm.h>
|
---|
37 | #include <VBox/vmm/dbgf.h>
|
---|
38 | #include <VBox/vmm/mm.h>
|
---|
39 | #include <VBox/err.h>
|
---|
40 | #include <VBox/vusb.h>
|
---|
41 | #include <iprt/stdarg.h>
|
---|
42 |
|
---|
43 | RT_C_DECLS_BEGIN
|
---|
44 |
|
---|
45 | /** @defgroup grp_pdm_usbdev The USB Devices API
|
---|
46 | * @ingroup grp_pdm
|
---|
47 | * @{
|
---|
48 | */
|
---|
49 |
|
---|
50 |
|
---|
51 | /**
|
---|
52 | * A string entry for the USB descriptor cache.
|
---|
53 | */
|
---|
54 | typedef struct PDMUSBDESCCACHESTRING
|
---|
55 | {
|
---|
56 | /** The string index. */
|
---|
57 | uint8_t idx;
|
---|
58 | /** The UTF-8 representation of the string. */
|
---|
59 | const char *psz;
|
---|
60 | } PDMUSBDESCCACHESTRING;
|
---|
61 | /** Pointer to a const string entry. */
|
---|
62 | typedef PDMUSBDESCCACHESTRING const *PCPDMUSBDESCCACHESTRING;
|
---|
63 |
|
---|
64 |
|
---|
65 | /**
|
---|
66 | * A language entry for the USB descriptor cache.
|
---|
67 | */
|
---|
68 | typedef struct PDMUSBDESCCACHELANG
|
---|
69 | {
|
---|
70 | /** The language ID for the strings in this block. */
|
---|
71 | uint16_t idLang;
|
---|
72 | /** The number of strings in the array. */
|
---|
73 | uint16_t cStrings;
|
---|
74 | /** Pointer to an array of associated strings.
|
---|
75 | * This must be sorted in ascending order by string index as a binary lookup
|
---|
76 | * will be performed. */
|
---|
77 | PCPDMUSBDESCCACHESTRING paStrings;
|
---|
78 | } PDMUSBDESCCACHELANG;
|
---|
79 | /** Pointer to a const language entry. */
|
---|
80 | typedef PDMUSBDESCCACHELANG const *PCPDMUSBDESCCACHELANG;
|
---|
81 |
|
---|
82 |
|
---|
83 | /**
|
---|
84 | * USB descriptor cache.
|
---|
85 | *
|
---|
86 | * This structure is owned by the USB device but provided to the PDM/VUSB layer
|
---|
87 | * thru the PDMUSBREG::pfnGetDescriptorCache method. PDM/VUSB will use the
|
---|
88 | * information here to map addresses to endpoints, perform SET_CONFIGURATION
|
---|
89 | * requests, and optionally perform GET_DESCRIPTOR requests (see flag).
|
---|
90 | *
|
---|
91 | * Currently, only device and configuration descriptors are cached.
|
---|
92 | */
|
---|
93 | typedef struct PDMUSBDESCCACHE
|
---|
94 | {
|
---|
95 | /** USB device descriptor */
|
---|
96 | PCVUSBDESCDEVICE pDevice;
|
---|
97 | /** USB Descriptor arrays (pDev->bNumConfigurations) */
|
---|
98 | PCVUSBDESCCONFIGEX paConfigs;
|
---|
99 | /** Language IDs and their associated strings.
|
---|
100 | * This must be sorted in ascending order by language ID as a binary lookup
|
---|
101 | * will be used. */
|
---|
102 | PCPDMUSBDESCCACHELANG paLanguages;
|
---|
103 | /** The number of entries in the array pointed to by paLanguages. */
|
---|
104 | uint16_t cLanguages;
|
---|
105 | /** Use the cached descriptors for GET_DESCRIPTOR requests. */
|
---|
106 | bool fUseCachedDescriptors;
|
---|
107 | /** Use the cached string descriptors. */
|
---|
108 | bool fUseCachedStringsDescriptors;
|
---|
109 | } PDMUSBDESCCACHE;
|
---|
110 | /** Pointer to an USB descriptor cache. */
|
---|
111 | typedef PDMUSBDESCCACHE *PPDMUSBDESCCACHE;
|
---|
112 | /** Pointer to a const USB descriptor cache. */
|
---|
113 | typedef const PDMUSBDESCCACHE *PCPDMUSBDESCCACHE;
|
---|
114 |
|
---|
115 |
|
---|
116 | /** PDM Device Flags.
|
---|
117 | * @{ */
|
---|
118 | /** A high-speed capable USB 2.0 device (also required to support full-speed). */
|
---|
119 | #define PDM_USBREG_HIGHSPEED_CAPABLE RT_BIT(0)
|
---|
120 | /** Indicates that the device implements the saved state handlers. */
|
---|
121 | #define PDM_USBREG_SAVED_STATE_SUPPORTED RT_BIT(1)
|
---|
122 | /** A SuperSpeed USB 3.0 device. */
|
---|
123 | #define PDM_USBREG_SUPERSPEED_CAPABLE RT_BIT(2)
|
---|
124 | /** @} */
|
---|
125 |
|
---|
126 | /** PDM USB Device Registration Structure,
|
---|
127 | *
|
---|
128 | * This structure is used when registering a device from VBoxUsbRegister() in HC Ring-3.
|
---|
129 | * The PDM will make use of this structure until the VM is destroyed.
|
---|
130 | */
|
---|
131 | typedef struct PDMUSBREG
|
---|
132 | {
|
---|
133 | /** Structure version. PDM_DEVREG_VERSION defines the current version. */
|
---|
134 | uint32_t u32Version;
|
---|
135 | /** Device name. */
|
---|
136 | char szName[32];
|
---|
137 | /** The description of the device. The UTF-8 string pointed to shall, like this structure,
|
---|
138 | * remain unchanged from registration till VM destruction. */
|
---|
139 | const char *pszDescription;
|
---|
140 |
|
---|
141 | /** Flags, combination of the PDM_USBREG_FLAGS_* \#defines. */
|
---|
142 | RTUINT fFlags;
|
---|
143 | /** Maximum number of instances (per VM). */
|
---|
144 | RTUINT cMaxInstances;
|
---|
145 | /** Size of the instance data. */
|
---|
146 | RTUINT cbInstance;
|
---|
147 |
|
---|
148 |
|
---|
149 | /**
|
---|
150 | * Construct an USB device instance for a VM.
|
---|
151 | *
|
---|
152 | * @returns VBox status.
|
---|
153 | * @param pUsbIns The USB device instance data.
|
---|
154 | * If the registration structure is needed, it will be
|
---|
155 | * accessible thru pUsbDev->pReg.
|
---|
156 | * @param iInstance Instance number. Use this to figure out which registers
|
---|
157 | * and such to use. The instance number is also found in
|
---|
158 | * pUsbDev->iInstance, but since it's likely to be
|
---|
159 | * frequently used PDM passes it as parameter.
|
---|
160 | * @param pCfg Configuration node handle for the device. Use this to
|
---|
161 | * obtain the configuration of the device instance. It is
|
---|
162 | * also found in pUsbDev->pCfg, but since it is primary
|
---|
163 | * usage will in this function it is passed as a parameter.
|
---|
164 | * @param pCfgGlobal Handle to the global device configuration. Also found
|
---|
165 | * in pUsbDev->pCfgGlobal.
|
---|
166 | * @remarks This callback is required.
|
---|
167 | */
|
---|
168 | DECLR3CALLBACKMEMBER(int, pfnConstruct,(PPDMUSBINS pUsbIns, int iInstance, PCFGMNODE pCfg, PCFGMNODE pCfgGlobal));
|
---|
169 |
|
---|
170 | /**
|
---|
171 | * Destruct an USB device instance.
|
---|
172 | *
|
---|
173 | * Most VM resources are freed by the VM. This callback is provided so that any non-VM
|
---|
174 | * resources can be freed correctly.
|
---|
175 | *
|
---|
176 | * This method will be called regardless of the pfnConstruct result to avoid
|
---|
177 | * complicated failure paths.
|
---|
178 | *
|
---|
179 | * @param pUsbIns The USB device instance data.
|
---|
180 | * @remarks Optional.
|
---|
181 | */
|
---|
182 | DECLR3CALLBACKMEMBER(void, pfnDestruct,(PPDMUSBINS pUsbIns));
|
---|
183 |
|
---|
184 |
|
---|
185 | /**
|
---|
186 | * Init complete notification.
|
---|
187 | *
|
---|
188 | * This can be done to do communication with other devices and other
|
---|
189 | * initialization which requires everything to be in place.
|
---|
190 | *
|
---|
191 | * @returns VBOX status code.
|
---|
192 | * @param pUsbIns The USB device instance data.
|
---|
193 | * @remarks Optional.
|
---|
194 | * @remarks Not called when hotplugged.
|
---|
195 | */
|
---|
196 | DECLR3CALLBACKMEMBER(int, pfnVMInitComplete,(PPDMUSBINS pUsbIns));
|
---|
197 |
|
---|
198 | /**
|
---|
199 | * VM Power On notification.
|
---|
200 | *
|
---|
201 | * @returns VBox status.
|
---|
202 | * @param pUsbIns The USB device instance data.
|
---|
203 | * @remarks Optional.
|
---|
204 | */
|
---|
205 | DECLR3CALLBACKMEMBER(void, pfnVMPowerOn,(PPDMUSBINS pUsbIns));
|
---|
206 |
|
---|
207 | /**
|
---|
208 | * VM Reset notification.
|
---|
209 | *
|
---|
210 | * @returns VBox status.
|
---|
211 | * @param pUsbIns The USB device instance data.
|
---|
212 | * @remarks Optional.
|
---|
213 | */
|
---|
214 | DECLR3CALLBACKMEMBER(void, pfnVMReset,(PPDMUSBINS pUsbIns));
|
---|
215 |
|
---|
216 | /**
|
---|
217 | * VM Suspend notification.
|
---|
218 | *
|
---|
219 | * @returns VBox status.
|
---|
220 | * @param pUsbIns The USB device instance data.
|
---|
221 | * @remarks Optional.
|
---|
222 | */
|
---|
223 | DECLR3CALLBACKMEMBER(void, pfnVMSuspend,(PPDMUSBINS pUsbIns));
|
---|
224 |
|
---|
225 | /**
|
---|
226 | * VM Resume notification.
|
---|
227 | *
|
---|
228 | * @returns VBox status.
|
---|
229 | * @param pUsbIns The USB device instance data.
|
---|
230 | * @remarks Optional.
|
---|
231 | */
|
---|
232 | DECLR3CALLBACKMEMBER(void, pfnVMResume,(PPDMUSBINS pUsbIns));
|
---|
233 |
|
---|
234 | /**
|
---|
235 | * VM Power Off notification.
|
---|
236 | *
|
---|
237 | * This is only called when the VMR3PowerOff call is made on a running VM. This
|
---|
238 | * means that there is no notification if the VM was suspended before being
|
---|
239 | * powered of. There will also be no callback when hot plugging devices.
|
---|
240 | *
|
---|
241 | * @param pUsbIns The USB device instance data.
|
---|
242 | */
|
---|
243 | DECLR3CALLBACKMEMBER(void, pfnVMPowerOff,(PPDMUSBINS pUsbIns));
|
---|
244 |
|
---|
245 | /**
|
---|
246 | * Called after the constructor when attaching a device at run time.
|
---|
247 | *
|
---|
248 | * This can be used to do tasks normally assigned to pfnInitComplete and/or pfnVMPowerOn.
|
---|
249 | *
|
---|
250 | * @returns VBox status.
|
---|
251 | * @param pUsbIns The USB device instance data.
|
---|
252 | * @remarks Optional.
|
---|
253 | */
|
---|
254 | DECLR3CALLBACKMEMBER(void, pfnHotPlugged,(PPDMUSBINS pUsbIns));
|
---|
255 |
|
---|
256 | /**
|
---|
257 | * Called before the destructor when a device is unplugged at run time.
|
---|
258 | *
|
---|
259 | * This can be used to do tasks normally assigned to pfnVMSuspend and/or pfnVMPowerOff.
|
---|
260 | *
|
---|
261 | * @returns VBox status.
|
---|
262 | * @param pUsbIns The USB device instance data.
|
---|
263 | * @remarks Optional.
|
---|
264 | */
|
---|
265 | DECLR3CALLBACKMEMBER(void, pfnHotUnplugged,(PPDMUSBINS pUsbIns));
|
---|
266 | /**
|
---|
267 | * Driver Attach command.
|
---|
268 | *
|
---|
269 | * This is called to let the USB device attach to a driver for a specified LUN
|
---|
270 | * at runtime. This is not called during VM construction, the device constructor
|
---|
271 | * have to attach to all the available drivers.
|
---|
272 | *
|
---|
273 | * @returns VBox status code.
|
---|
274 | * @param pUsbIns The USB device instance data.
|
---|
275 | * @param iLUN The logical unit which is being detached.
|
---|
276 | * @param fFlags Flags, combination of the PDM_TACH_FLAGS_* \#defines.
|
---|
277 | * @remarks Optional.
|
---|
278 | */
|
---|
279 | DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMUSBINS pUsbIns, unsigned iLUN, uint32_t fFlags));
|
---|
280 |
|
---|
281 | /**
|
---|
282 | * Driver Detach notification.
|
---|
283 | *
|
---|
284 | * This is called when a driver is detaching itself from a LUN of the device.
|
---|
285 | * The device should adjust it's state to reflect this.
|
---|
286 | *
|
---|
287 | * @param pUsbIns The USB device instance data.
|
---|
288 | * @param iLUN The logical unit which is being detached.
|
---|
289 | * @param fFlags Flags, combination of the PDM_TACH_FLAGS_* \#defines.
|
---|
290 | * @remarks Optional.
|
---|
291 | */
|
---|
292 | DECLR3CALLBACKMEMBER(void, pfnDriverDetach,(PPDMUSBINS pUsbIns, unsigned iLUN, uint32_t fFlags));
|
---|
293 |
|
---|
294 | /**
|
---|
295 | * Query the base interface of a logical unit.
|
---|
296 | *
|
---|
297 | * @returns VBOX status code.
|
---|
298 | * @param pUsbIns The USB device instance data.
|
---|
299 | * @param iLUN The logicial unit to query.
|
---|
300 | * @param ppBase Where to store the pointer to the base interface of the LUN.
|
---|
301 | * @remarks Optional.
|
---|
302 | */
|
---|
303 | DECLR3CALLBACKMEMBER(int, pfnQueryInterface,(PPDMUSBINS pUsbIns, unsigned iLUN, PPDMIBASE *ppBase));
|
---|
304 |
|
---|
305 | /**
|
---|
306 | * Requests the USB device to reset.
|
---|
307 | *
|
---|
308 | * @returns VBox status code.
|
---|
309 | * @param pUsbIns The USB device instance.
|
---|
310 | * @param fResetOnLinux A hint to the usb proxy.
|
---|
311 | * Don't use this unless you're the linux proxy device.
|
---|
312 | * @thread Any thread.
|
---|
313 | * @remarks Optional.
|
---|
314 | */
|
---|
315 | DECLR3CALLBACKMEMBER(int, pfnUsbReset,(PPDMUSBINS pUsbIns, bool fResetOnLinux));
|
---|
316 |
|
---|
317 | /**
|
---|
318 | * Query device and configuration descriptors for the caching and servicing
|
---|
319 | * relevant GET_DESCRIPTOR requests.
|
---|
320 | *
|
---|
321 | * @returns Pointer to the descriptor cache (read-only).
|
---|
322 | * @param pUsbIns The USB device instance.
|
---|
323 | * @remarks Mandatory.
|
---|
324 | */
|
---|
325 | DECLR3CALLBACKMEMBER(PCPDMUSBDESCCACHE, pfnUsbGetDescriptorCache,(PPDMUSBINS pUsbIns));
|
---|
326 |
|
---|
327 | /**
|
---|
328 | * SET_CONFIGURATION request.
|
---|
329 | *
|
---|
330 | * @returns VBox status code.
|
---|
331 | * @param pUsbIns The USB device instance.
|
---|
332 | * @param bConfigurationValue The bConfigurationValue of the new configuration.
|
---|
333 | * @param pvOldCfgDesc Internal - for the device proxy.
|
---|
334 | * @param pvOldIfState Internal - for the device proxy.
|
---|
335 | * @param pvNewCfgDesc Internal - for the device proxy.
|
---|
336 | * @remarks Optional.
|
---|
337 | */
|
---|
338 | DECLR3CALLBACKMEMBER(int, pfnUsbSetConfiguration,(PPDMUSBINS pUsbIns, uint8_t bConfigurationValue,
|
---|
339 | const void *pvOldCfgDesc, const void *pvOldIfState, const void *pvNewCfgDesc));
|
---|
340 |
|
---|
341 | /**
|
---|
342 | * SET_INTERFACE request.
|
---|
343 | *
|
---|
344 | * @returns VBox status code.
|
---|
345 | * @param pUsbIns The USB device instance.
|
---|
346 | * @param bInterfaceNumber The interface number.
|
---|
347 | * @param bAlternateSetting The alternate setting.
|
---|
348 | * @remarks Optional.
|
---|
349 | */
|
---|
350 | DECLR3CALLBACKMEMBER(int, pfnUsbSetInterface,(PPDMUSBINS pUsbIns, uint8_t bInterfaceNumber, uint8_t bAlternateSetting));
|
---|
351 |
|
---|
352 | /**
|
---|
353 | * Clears the halted state of an endpoint. (Optional)
|
---|
354 | *
|
---|
355 | * This called when VUSB sees a CLEAR_FEATURE(ENDPOINT_HALT) on request
|
---|
356 | * on the zero pipe.
|
---|
357 | *
|
---|
358 | * @returns VBox status code.
|
---|
359 | * @param pUsbIns The USB device instance.
|
---|
360 | * @param uEndpoint The endpoint to clear.
|
---|
361 | * @remarks Optional.
|
---|
362 | */
|
---|
363 | DECLR3CALLBACKMEMBER(int, pfnUsbClearHaltedEndpoint,(PPDMUSBINS pUsbIns, unsigned uEndpoint));
|
---|
364 |
|
---|
365 | /**
|
---|
366 | * Allocates an URB.
|
---|
367 | *
|
---|
368 | * This can be used to make use of shared user/kernel mode buffers.
|
---|
369 | *
|
---|
370 | * @returns VBox status code.
|
---|
371 | * @param pUsbIns The USB device instance.
|
---|
372 | * @param cbData The size of the data buffer.
|
---|
373 | * @param cTds The number of TDs.
|
---|
374 | * @param enmType The type of URB.
|
---|
375 | * @param ppUrb Where to store the allocated URB.
|
---|
376 | * @remarks Optional.
|
---|
377 | * @remarks Not implemented yet.
|
---|
378 | */
|
---|
379 | DECLR3CALLBACKMEMBER(int, pfnUrbNew,(PPDMUSBINS pUsbIns, size_t cbData, size_t cTds, VUSBXFERTYPE enmType, PVUSBURB *ppUrb));
|
---|
380 |
|
---|
381 | /**
|
---|
382 | * Queues an URB for processing.
|
---|
383 | *
|
---|
384 | * @returns VBox status code.
|
---|
385 | * @retval VINF_SUCCESS on success.
|
---|
386 | * @retval VERR_VUSB_DEVICE_NOT_ATTACHED if the device has been disconnected.
|
---|
387 | * @retval VERR_VUSB_FAILED_TO_QUEUE_URB as a general failure kind of thing.
|
---|
388 | * @retval TBD - document new stuff!
|
---|
389 | *
|
---|
390 | * @param pUsbIns The USB device instance.
|
---|
391 | * @param pUrb The URB to process.
|
---|
392 | * @remarks Mandatory.
|
---|
393 | */
|
---|
394 | DECLR3CALLBACKMEMBER(int, pfnUrbQueue,(PPDMUSBINS pUsbIns, PVUSBURB pUrb));
|
---|
395 |
|
---|
396 | /**
|
---|
397 | * Cancels an URB.
|
---|
398 | *
|
---|
399 | * @returns VBox status code.
|
---|
400 | * @param pUsbIns The USB device instance.
|
---|
401 | * @param pUrb The URB to cancel.
|
---|
402 | * @remarks Mandatory.
|
---|
403 | */
|
---|
404 | DECLR3CALLBACKMEMBER(int, pfnUrbCancel,(PPDMUSBINS pUsbIns, PVUSBURB pUrb));
|
---|
405 |
|
---|
406 | /**
|
---|
407 | * Reaps an URB.
|
---|
408 | *
|
---|
409 | * @returns A ripe URB, NULL if none.
|
---|
410 | * @param pUsbIns The USB device instance.
|
---|
411 | * @param cMillies How log to wait for an URB to become ripe.
|
---|
412 | * @remarks Mandatory.
|
---|
413 | */
|
---|
414 | DECLR3CALLBACKMEMBER(PVUSBURB, pfnUrbReap,(PPDMUSBINS pUsbIns, RTMSINTERVAL cMillies));
|
---|
415 |
|
---|
416 | /**
|
---|
417 | * Wakes a thread waiting in pfnUrbReap.
|
---|
418 | *
|
---|
419 | * @returns VBox status code.
|
---|
420 | * @param pUsbIns The USB device instance.
|
---|
421 | */
|
---|
422 | DECLR3CALLBACKMEMBER(int, pfnWakeup,(PPDMUSBINS pUsbIns));
|
---|
423 |
|
---|
424 | /** Just some init precaution. Must be set to PDM_USBREG_VERSION. */
|
---|
425 | uint32_t u32TheEnd;
|
---|
426 | } PDMUSBREG;
|
---|
427 | /** Pointer to a PDM USB Device Structure. */
|
---|
428 | typedef PDMUSBREG *PPDMUSBREG;
|
---|
429 | /** Const pointer to a PDM USB Device Structure. */
|
---|
430 | typedef PDMUSBREG const *PCPDMUSBREG;
|
---|
431 |
|
---|
432 | /** Current USBREG version number. */
|
---|
433 | #define PDM_USBREG_VERSION PDM_VERSION_MAKE(0xeeff, 1, 0)
|
---|
434 |
|
---|
435 | /** PDM USB Device Flags.
|
---|
436 | * @{ */
|
---|
437 | /* none yet */
|
---|
438 | /** @} */
|
---|
439 |
|
---|
440 |
|
---|
441 | #ifdef IN_RING3
|
---|
442 |
|
---|
443 | /**
|
---|
444 | * PDM USB Device API.
|
---|
445 | */
|
---|
446 | typedef struct PDMUSBHLP
|
---|
447 | {
|
---|
448 | /** Structure version. PDM_USBHLP_VERSION defines the current version. */
|
---|
449 | uint32_t u32Version;
|
---|
450 |
|
---|
451 | /**
|
---|
452 | * Attaches a driver (chain) to the USB device.
|
---|
453 | *
|
---|
454 | * The first call for a LUN this will serve as a registration of the LUN. The pBaseInterface and
|
---|
455 | * the pszDesc string will be registered with that LUN and kept around for PDMR3QueryUSBDeviceLun().
|
---|
456 | *
|
---|
457 | * @returns VBox status code.
|
---|
458 | * @param pUsbIns The USB device instance.
|
---|
459 | * @param iLun The logical unit to attach.
|
---|
460 | * @param pBaseInterface Pointer to the base interface for that LUN. (device side / down)
|
---|
461 | * @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up)
|
---|
462 | * @param pszDesc Pointer to a string describing the LUN. This string must remain valid
|
---|
463 | * for the live of the device instance.
|
---|
464 | */
|
---|
465 | DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMUSBINS pUsbIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE *ppBaseInterface, const char *pszDesc));
|
---|
466 |
|
---|
467 | /**
|
---|
468 | * Assert that the current thread is the emulation thread.
|
---|
469 | *
|
---|
470 | * @returns True if correct.
|
---|
471 | * @returns False if wrong.
|
---|
472 | * @param pUsbIns The USB device instance.
|
---|
473 | * @param pszFile Filename of the assertion location.
|
---|
474 | * @param iLine Linenumber of the assertion location.
|
---|
475 | * @param pszFunction Function of the assertion location.
|
---|
476 | */
|
---|
477 | DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMUSBINS pUsbIns, const char *pszFile, unsigned iLine, const char *pszFunction));
|
---|
478 |
|
---|
479 | /**
|
---|
480 | * Assert that the current thread is NOT the emulation thread.
|
---|
481 | *
|
---|
482 | * @returns True if correct.
|
---|
483 | * @returns False if wrong.
|
---|
484 | * @param pUsbIns The USB device instance.
|
---|
485 | * @param pszFile Filename of the assertion location.
|
---|
486 | * @param iLine Linenumber of the assertion location.
|
---|
487 | * @param pszFunction Function of the assertion location.
|
---|
488 | */
|
---|
489 | DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMUSBINS pUsbIns, const char *pszFile, unsigned iLine, const char *pszFunction));
|
---|
490 |
|
---|
491 | /**
|
---|
492 | * Stops the VM and enters the debugger to look at the guest state.
|
---|
493 | *
|
---|
494 | * Use the PDMUsbDBGFStop() inline function with the RT_SRC_POS macro instead of
|
---|
495 | * invoking this function directly.
|
---|
496 | *
|
---|
497 | * @returns VBox status code which must be passed up to the VMM.
|
---|
498 | * @param pUsbIns The USB device instance.
|
---|
499 | * @param pszFile Filename of the assertion location.
|
---|
500 | * @param iLine The linenumber of the assertion location.
|
---|
501 | * @param pszFunction Function of the assertion location.
|
---|
502 | * @param pszFormat Message. (optional)
|
---|
503 | * @param va Message parameters.
|
---|
504 | */
|
---|
505 | DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMUSBINS pUsbIns, const char *pszFile, unsigned iLine, const char *pszFunction,
|
---|
506 | const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(5, 0));
|
---|
507 |
|
---|
508 | /**
|
---|
509 | * Register a info handler with DBGF,
|
---|
510 | *
|
---|
511 | * @returns VBox status code.
|
---|
512 | * @param pUsbIns The USB device instance.
|
---|
513 | * @param pszName The identifier of the info.
|
---|
514 | * @param pszDesc The description of the info and any arguments the handler may take.
|
---|
515 | * @param pfnHandler The handler function to be called to display the info.
|
---|
516 | */
|
---|
517 | DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMUSBINS pUsbIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERUSB pfnHandler));
|
---|
518 |
|
---|
519 | /**
|
---|
520 | * Allocate memory which is associated with current VM instance
|
---|
521 | * and automatically freed on it's destruction.
|
---|
522 | *
|
---|
523 | * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
|
---|
524 | * @param pUsbIns The USB device instance.
|
---|
525 | * @param cb Number of bytes to allocate.
|
---|
526 | */
|
---|
527 | DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMUSBINS pUsbIns, size_t cb));
|
---|
528 |
|
---|
529 | /**
|
---|
530 | * Allocate memory which is associated with current VM instance
|
---|
531 | * and automatically freed on it's destruction. The memory is ZEROed.
|
---|
532 | *
|
---|
533 | * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
|
---|
534 | * @param pUsbIns The USB device instance.
|
---|
535 | * @param cb Number of bytes to allocate.
|
---|
536 | */
|
---|
537 | DECLR3CALLBACKMEMBER(void *, pfnMMHeapAllocZ,(PPDMUSBINS pUsbIns, size_t cb));
|
---|
538 |
|
---|
539 | /**
|
---|
540 | * Create a queue.
|
---|
541 | *
|
---|
542 | * @returns VBox status code.
|
---|
543 | * @param pUsbIns The USB device instance.
|
---|
544 | * @param cbItem Size a queue item.
|
---|
545 | * @param cItems Number of items in the queue.
|
---|
546 | * @param cMilliesInterval Number of milliseconds between polling the queue.
|
---|
547 | * If 0 then the emulation thread will be notified whenever an item arrives.
|
---|
548 | * @param pfnCallback The consumer function.
|
---|
549 | * @param pszName The queue base name. The instance number will be
|
---|
550 | * appended automatically.
|
---|
551 | * @param ppQueue Where to store the queue handle on success.
|
---|
552 | * @thread The emulation thread.
|
---|
553 | */
|
---|
554 | DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMUSBINS pUsbIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
|
---|
555 | PFNPDMQUEUEUSB pfnCallback, const char *pszName, PPDMQUEUE *ppQueue));
|
---|
556 |
|
---|
557 | /**
|
---|
558 | * Register a save state data unit.
|
---|
559 | *
|
---|
560 | * @returns VBox status.
|
---|
561 | * @param pUsbIns The USB device instance.
|
---|
562 | * @param uVersion Data layout version number.
|
---|
563 | * @param cbGuess The approximate amount of data in the unit.
|
---|
564 | * Only for progress indicators.
|
---|
565 | *
|
---|
566 | * @param pfnLivePrep Prepare live save callback, optional.
|
---|
567 | * @param pfnLiveExec Execute live save callback, optional.
|
---|
568 | * @param pfnLiveVote Vote live save callback, optional.
|
---|
569 | *
|
---|
570 | * @param pfnSavePrep Prepare save callback, optional.
|
---|
571 | * @param pfnSaveExec Execute save callback, optional.
|
---|
572 | * @param pfnSaveDone Done save callback, optional.
|
---|
573 | *
|
---|
574 | * @param pfnLoadPrep Prepare load callback, optional.
|
---|
575 | * @param pfnLoadExec Execute load callback, optional.
|
---|
576 | * @param pfnLoadDone Done load callback, optional.
|
---|
577 | */
|
---|
578 | DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMUSBINS pUsbIns, uint32_t uVersion, size_t cbGuess,
|
---|
579 | PFNSSMUSBLIVEPREP pfnLivePrep, PFNSSMUSBLIVEEXEC pfnLiveExec, PFNSSMUSBLIVEVOTE pfnLiveVote,
|
---|
580 | PFNSSMUSBSAVEPREP pfnSavePrep, PFNSSMUSBSAVEEXEC pfnSaveExec, PFNSSMUSBSAVEDONE pfnSaveDone,
|
---|
581 | PFNSSMUSBLOADPREP pfnLoadPrep, PFNSSMUSBLOADEXEC pfnLoadExec, PFNSSMUSBLOADDONE pfnLoadDone));
|
---|
582 |
|
---|
583 | /**
|
---|
584 | * Register a STAM sample.
|
---|
585 | *
|
---|
586 | * Use the PDMUsbHlpSTAMRegister wrapper.
|
---|
587 | *
|
---|
588 | * @returns VBox status.
|
---|
589 | * @param pUsbIns The USB device instance.
|
---|
590 | * @param pvSample Pointer to the sample.
|
---|
591 | * @param enmType Sample type. This indicates what pvSample is pointing at.
|
---|
592 | * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
|
---|
593 | * @param enmUnit Sample unit.
|
---|
594 | * @param pszDesc Sample description.
|
---|
595 | * @param pszName The sample name format string.
|
---|
596 | * @param va Arguments to the format string.
|
---|
597 | */
|
---|
598 | DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMUSBINS pUsbIns, void *pvSample, STAMTYPE enmType,
|
---|
599 | STAMVISIBILITY enmVisibility, STAMUNIT enmUnit, const char *pszDesc,
|
---|
600 | const char *pszName, va_list va) RT_IPRT_FORMAT_ATTR(7, 0));
|
---|
601 |
|
---|
602 | /**
|
---|
603 | * Creates a timer.
|
---|
604 | *
|
---|
605 | * @returns VBox status.
|
---|
606 | * @param pUsbIns The USB device instance.
|
---|
607 | * @param enmClock The clock to use on this timer.
|
---|
608 | * @param pfnCallback Callback function.
|
---|
609 | * @param pvUser User argument for the callback.
|
---|
610 | * @param fFlags Flags, see TMTIMER_FLAGS_*.
|
---|
611 | * @param pszDesc Pointer to description string which must stay around
|
---|
612 | * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
|
---|
613 | * @param ppTimer Where to store the timer on success.
|
---|
614 | */
|
---|
615 | DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMUSBINS pUsbIns, TMCLOCK enmClock, PFNTMTIMERUSB pfnCallback, void *pvUser,
|
---|
616 | uint32_t fFlags, const char *pszDesc, PPTMTIMERR3 ppTimer));
|
---|
617 |
|
---|
618 | /**
|
---|
619 | * Set the VM error message
|
---|
620 | *
|
---|
621 | * @returns rc.
|
---|
622 | * @param pUsbIns The USB device instance.
|
---|
623 | * @param rc VBox status code.
|
---|
624 | * @param SRC_POS Use RT_SRC_POS.
|
---|
625 | * @param pszFormat Error message format string.
|
---|
626 | * @param va Error message arguments.
|
---|
627 | */
|
---|
628 | DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMUSBINS pUsbIns, int rc, RT_SRC_POS_DECL,
|
---|
629 | const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
|
---|
630 |
|
---|
631 | /**
|
---|
632 | * Set the VM runtime error message
|
---|
633 | *
|
---|
634 | * @returns VBox status code.
|
---|
635 | * @param pUsbIns The USB device instance.
|
---|
636 | * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
|
---|
637 | * @param pszErrorId Error ID string.
|
---|
638 | * @param pszFormat Error message format string.
|
---|
639 | * @param va Error message arguments.
|
---|
640 | */
|
---|
641 | DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMUSBINS pUsbIns, uint32_t fFlags, const char *pszErrorId,
|
---|
642 | const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0));
|
---|
643 |
|
---|
644 | /**
|
---|
645 | * Gets the VM state.
|
---|
646 | *
|
---|
647 | * @returns VM state.
|
---|
648 | * @param pUsbIns The USB device instance.
|
---|
649 | * @thread Any thread (just keep in mind that it's volatile info).
|
---|
650 | */
|
---|
651 | DECLR3CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMUSBINS pUsbIns));
|
---|
652 |
|
---|
653 | /**
|
---|
654 | * Creates a PDM thread.
|
---|
655 | *
|
---|
656 | * This differs from the RTThreadCreate() API in that PDM takes care of suspending,
|
---|
657 | * resuming, and destroying the thread as the VM state changes.
|
---|
658 | *
|
---|
659 | * @returns VBox status code.
|
---|
660 | * @param pUsbIns The USB device instance.
|
---|
661 | * @param ppThread Where to store the thread 'handle'.
|
---|
662 | * @param pvUser The user argument to the thread function.
|
---|
663 | * @param pfnThread The thread function.
|
---|
664 | * @param pfnWakeup The wakup callback. This is called on the EMT
|
---|
665 | * thread when a state change is pending.
|
---|
666 | * @param cbStack See RTThreadCreate.
|
---|
667 | * @param enmType See RTThreadCreate.
|
---|
668 | * @param pszName See RTThreadCreate.
|
---|
669 | */
|
---|
670 | DECLR3CALLBACKMEMBER(int, pfnThreadCreate,(PPDMUSBINS pUsbIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADUSB pfnThread,
|
---|
671 | PFNPDMTHREADWAKEUPUSB pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
|
---|
672 |
|
---|
673 | /**
|
---|
674 | * Set up asynchronous handling of a suspend, reset or power off notification.
|
---|
675 | *
|
---|
676 | * This shall only be called when getting the notification. It must be called
|
---|
677 | * for each one.
|
---|
678 | *
|
---|
679 | * @returns VBox status code.
|
---|
680 | * @param pUsbIns The USB device instance.
|
---|
681 | * @param pfnAsyncNotify The callback.
|
---|
682 | * @thread EMT(0)
|
---|
683 | */
|
---|
684 | DECLR3CALLBACKMEMBER(int, pfnSetAsyncNotification, (PPDMUSBINS pUSbIns, PFNPDMUSBASYNCNOTIFY pfnAsyncNotify));
|
---|
685 |
|
---|
686 | /**
|
---|
687 | * Notify EMT(0) that the device has completed the asynchronous notification
|
---|
688 | * handling.
|
---|
689 | *
|
---|
690 | * This can be called at any time, spurious calls will simply be ignored.
|
---|
691 | *
|
---|
692 | * @param pUsbIns The USB device instance.
|
---|
693 | * @thread Any
|
---|
694 | */
|
---|
695 | DECLR3CALLBACKMEMBER(void, pfnAsyncNotificationCompleted, (PPDMUSBINS pUsbIns));
|
---|
696 |
|
---|
697 | /**
|
---|
698 | * Gets the reason for the most recent VM suspend.
|
---|
699 | *
|
---|
700 | * @returns The suspend reason. VMSUSPENDREASON_INVALID is returned if no
|
---|
701 | * suspend has been made or if the pUsbIns is invalid.
|
---|
702 | * @param pUsbIns The driver instance.
|
---|
703 | */
|
---|
704 | DECLR3CALLBACKMEMBER(VMSUSPENDREASON, pfnVMGetSuspendReason,(PPDMUSBINS pUsbIns));
|
---|
705 |
|
---|
706 | /**
|
---|
707 | * Gets the reason for the most recent VM resume.
|
---|
708 | *
|
---|
709 | * @returns The resume reason. VMRESUMEREASON_INVALID is returned if no
|
---|
710 | * resume has been made or if the pUsbIns is invalid.
|
---|
711 | * @param pUsbIns The driver instance.
|
---|
712 | */
|
---|
713 | DECLR3CALLBACKMEMBER(VMRESUMEREASON, pfnVMGetResumeReason,(PPDMUSBINS pUsbIns));
|
---|
714 |
|
---|
715 | /** @name Space reserved for minor interface changes.
|
---|
716 | * @{ */
|
---|
717 | DECLR3CALLBACKMEMBER(void, pfnReserved0,(PPDMUSBINS pUsbIns));
|
---|
718 | DECLR3CALLBACKMEMBER(void, pfnReserved1,(PPDMUSBINS pUsbIns));
|
---|
719 | DECLR3CALLBACKMEMBER(void, pfnReserved2,(PPDMUSBINS pUsbIns));
|
---|
720 | DECLR3CALLBACKMEMBER(void, pfnReserved3,(PPDMUSBINS pUsbIns));
|
---|
721 | DECLR3CALLBACKMEMBER(void, pfnReserved4,(PPDMUSBINS pUsbIns));
|
---|
722 | DECLR3CALLBACKMEMBER(void, pfnReserved5,(PPDMUSBINS pUsbIns));
|
---|
723 | DECLR3CALLBACKMEMBER(void, pfnReserved6,(PPDMUSBINS pUsbIns));
|
---|
724 | DECLR3CALLBACKMEMBER(void, pfnReserved7,(PPDMUSBINS pUsbIns));
|
---|
725 | DECLR3CALLBACKMEMBER(void, pfnReserved8,(PPDMUSBINS pUsbIns));
|
---|
726 | DECLR3CALLBACKMEMBER(void, pfnReserved9,(PPDMUSBINS pUsbIns));
|
---|
727 | /** @} */
|
---|
728 |
|
---|
729 | /** Just a safety precaution. */
|
---|
730 | uint32_t u32TheEnd;
|
---|
731 | } PDMUSBHLP;
|
---|
732 | /** Pointer PDM USB Device API. */
|
---|
733 | typedef PDMUSBHLP *PPDMUSBHLP;
|
---|
734 | /** Pointer const PDM USB Device API. */
|
---|
735 | typedef const PDMUSBHLP *PCPDMUSBHLP;
|
---|
736 |
|
---|
737 | /** Current USBHLP version number. */
|
---|
738 | #define PDM_USBHLP_VERSION PDM_VERSION_MAKE(0xeefe, 3, 0)
|
---|
739 |
|
---|
740 | #endif /* IN_RING3 */
|
---|
741 |
|
---|
742 | /**
|
---|
743 | * PDM USB Device Instance.
|
---|
744 | */
|
---|
745 | typedef struct PDMUSBINS
|
---|
746 | {
|
---|
747 | /** Structure version. PDM_USBINS_VERSION defines the current version. */
|
---|
748 | uint32_t u32Version;
|
---|
749 | /** USB device instance number. */
|
---|
750 | uint32_t iInstance;
|
---|
751 | /** The base interface of the device.
|
---|
752 | * The device constructor initializes this if it has any device level
|
---|
753 | * interfaces to export. To obtain this interface call PDMR3QueryUSBDevice(). */
|
---|
754 | PDMIBASE IBase;
|
---|
755 | #if HC_ARCH_BITS == 32
|
---|
756 | uint32_t u32Alignment; /**< Alignment padding. */
|
---|
757 | #endif
|
---|
758 |
|
---|
759 | /** Internal data. */
|
---|
760 | union
|
---|
761 | {
|
---|
762 | #ifdef PDMUSBINSINT_DECLARED
|
---|
763 | PDMUSBINSINT s;
|
---|
764 | #endif
|
---|
765 | uint8_t padding[HC_ARCH_BITS == 32 ? 96 : 128];
|
---|
766 | } Internal;
|
---|
767 |
|
---|
768 | /** Pointer the PDM USB Device API. */
|
---|
769 | R3PTRTYPE(PCPDMUSBHLP) pHlpR3;
|
---|
770 | /** Pointer to the USB device registration structure. */
|
---|
771 | R3PTRTYPE(PCPDMUSBREG) pReg;
|
---|
772 | /** Configuration handle. */
|
---|
773 | R3PTRTYPE(PCFGMNODE) pCfg;
|
---|
774 | /** The (device) global configuration handle. */
|
---|
775 | R3PTRTYPE(PCFGMNODE) pCfgGlobal;
|
---|
776 | /** Pointer to device instance data. */
|
---|
777 | R3PTRTYPE(void *) pvInstanceDataR3;
|
---|
778 | /** Pointer to the VUSB Device structure.
|
---|
779 | * Internal to VUSB, don't touch.
|
---|
780 | * @todo Moved this to PDMUSBINSINT. */
|
---|
781 | R3PTRTYPE(void *) pvVUsbDev2;
|
---|
782 | /** Device name for using when logging.
|
---|
783 | * The constructor sets this and the destructor frees it. */
|
---|
784 | R3PTRTYPE(char *) pszName;
|
---|
785 | /** Tracing indicator. */
|
---|
786 | uint32_t fTracing;
|
---|
787 | /** The tracing ID of this device. */
|
---|
788 | uint32_t idTracing;
|
---|
789 | /** The port/device speed. HCs and emulated devices need to know. */
|
---|
790 | VUSBSPEED enmSpeed;
|
---|
791 |
|
---|
792 | /** Padding to make achInstanceData aligned at 32 byte boundary. */
|
---|
793 | uint32_t au32Padding[HC_ARCH_BITS == 32 ? 2 : 3];
|
---|
794 |
|
---|
795 | /** Device instance data. The size of this area is defined
|
---|
796 | * in the PDMUSBREG::cbInstanceData field. */
|
---|
797 | char achInstanceData[8];
|
---|
798 | } PDMUSBINS;
|
---|
799 |
|
---|
800 | /** Current USBINS version number. */
|
---|
801 | #define PDM_USBINS_VERSION PDM_VERSION_MAKE(0xeefd, 3, 0)
|
---|
802 |
|
---|
803 | /**
|
---|
804 | * Checks the structure versions of the USB device instance and USB device
|
---|
805 | * helpers, returning if they are incompatible.
|
---|
806 | *
|
---|
807 | * This shall be the first statement of the constructor!
|
---|
808 | *
|
---|
809 | * @param pUsbIns The USB device instance pointer.
|
---|
810 | */
|
---|
811 | #define PDMUSB_CHECK_VERSIONS_RETURN(pUsbIns) \
|
---|
812 | do \
|
---|
813 | { \
|
---|
814 | PPDMUSBINS pUsbInsTypeCheck = (pUsbIns); NOREF(pUsbInsTypeCheck); \
|
---|
815 | AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pUsbIns)->u32Version, PDM_USBINS_VERSION), \
|
---|
816 | ("DevIns=%#x mine=%#x\n", (pUsbIns)->u32Version, PDM_USBINS_VERSION), \
|
---|
817 | VERR_PDM_USBINS_VERSION_MISMATCH); \
|
---|
818 | AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pUsbIns)->pHlpR3->u32Version, PDM_USBHLP_VERSION), \
|
---|
819 | ("DevHlp=%#x mine=%#x\n", (pUsbIns)->pHlpR3->u32Version, PDM_USBHLP_VERSION), \
|
---|
820 | VERR_PDM_USBHLPR3_VERSION_MISMATCH); \
|
---|
821 | } while (0)
|
---|
822 |
|
---|
823 | /**
|
---|
824 | * Quietly checks the structure versions of the USB device instance and
|
---|
825 | * USB device helpers, returning if they are incompatible.
|
---|
826 | *
|
---|
827 | * This shall be invoked as the first statement in the destructor!
|
---|
828 | *
|
---|
829 | * @param pUsbIns The USB device instance pointer.
|
---|
830 | */
|
---|
831 | #define PDMUSB_CHECK_VERSIONS_RETURN_VOID(pUsbIns) \
|
---|
832 | do \
|
---|
833 | { \
|
---|
834 | PPDMUSBINS pUsbInsTypeCheck = (pUsbIns); NOREF(pUsbInsTypeCheck); \
|
---|
835 | if (RT_LIKELY(PDM_VERSION_ARE_COMPATIBLE((pUsbIns)->u32Version, PDM_USBINS_VERSION) )) \
|
---|
836 | { /* likely */ } else return; \
|
---|
837 | if (RT_LIKELY(PDM_VERSION_ARE_COMPATIBLE((pUsbIns)->pHlpR3->u32Version, PDM_USBHLP_VERSION) )) \
|
---|
838 | { /* likely */ } else return; \
|
---|
839 | } while (0)
|
---|
840 |
|
---|
841 |
|
---|
842 | /** Converts a pointer to the PDMUSBINS::IBase to a pointer to PDMUSBINS. */
|
---|
843 | #define PDMIBASE_2_PDMUSB(pInterface) ( (PPDMUSBINS)((char *)(pInterface) - RT_OFFSETOF(PDMUSBINS, IBase)) )
|
---|
844 |
|
---|
845 |
|
---|
846 | /** @def PDMUSB_ASSERT_EMT
|
---|
847 | * Assert that the current thread is the emulation thread.
|
---|
848 | */
|
---|
849 | #ifdef VBOX_STRICT
|
---|
850 | # define PDMUSB_ASSERT_EMT(pUsbIns) pUsbIns->pHlpR3->pfnAssertEMT(pUsbIns, __FILE__, __LINE__, __FUNCTION__)
|
---|
851 | #else
|
---|
852 | # define PDMUSB_ASSERT_EMT(pUsbIns) do { } while (0)
|
---|
853 | #endif
|
---|
854 |
|
---|
855 | /** @def PDMUSB_ASSERT_OTHER
|
---|
856 | * Assert that the current thread is NOT the emulation thread.
|
---|
857 | */
|
---|
858 | #ifdef VBOX_STRICT
|
---|
859 | # define PDMUSB_ASSERT_OTHER(pUsbIns) pUsbIns->pHlpR3->pfnAssertOther(pUsbIns, __FILE__, __LINE__, __FUNCTION__)
|
---|
860 | #else
|
---|
861 | # define PDMUSB_ASSERT_OTHER(pUsbIns) do { } while (0)
|
---|
862 | #endif
|
---|
863 |
|
---|
864 | /** @def PDMUSB_SET_ERROR
|
---|
865 | * Set the VM error. See PDMUsbHlpVMSetError() for printf like message
|
---|
866 | * formatting.
|
---|
867 | */
|
---|
868 | #define PDMUSB_SET_ERROR(pUsbIns, rc, pszError) \
|
---|
869 | PDMUsbHlpVMSetError(pUsbIns, rc, RT_SRC_POS, "%s", pszError)
|
---|
870 |
|
---|
871 | /** @def PDMUSB_SET_RUNTIME_ERROR
|
---|
872 | * Set the VM runtime error. See PDMUsbHlpVMSetRuntimeError() for printf like
|
---|
873 | * message formatting.
|
---|
874 | */
|
---|
875 | #define PDMUSB_SET_RUNTIME_ERROR(pUsbIns, fFlags, pszErrorId, pszError) \
|
---|
876 | PDMUsbHlpVMSetRuntimeError(pUsbIns, fFlags, pszErrorId, "%s", pszError)
|
---|
877 |
|
---|
878 |
|
---|
879 | #ifdef IN_RING3
|
---|
880 |
|
---|
881 | /**
|
---|
882 | * @copydoc PDMUSBHLP::pfnDriverAttach
|
---|
883 | */
|
---|
884 | DECLINLINE(int) PDMUsbHlpDriverAttach(PPDMUSBINS pUsbIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE *ppBaseInterface, const char *pszDesc)
|
---|
885 | {
|
---|
886 | return pUsbIns->pHlpR3->pfnDriverAttach(pUsbIns, iLun, pBaseInterface, ppBaseInterface, pszDesc);
|
---|
887 | }
|
---|
888 |
|
---|
889 | /**
|
---|
890 | * VBOX_STRICT wrapper for pHlpR3->pfnDBGFStopV.
|
---|
891 | *
|
---|
892 | * @returns VBox status code which must be passed up to the VMM.
|
---|
893 | * @param pUsbIns Device instance.
|
---|
894 | * @param SRC_POS Use RT_SRC_POS.
|
---|
895 | * @param pszFormat Message. (optional)
|
---|
896 | * @param ... Message parameters.
|
---|
897 | */
|
---|
898 | DECLINLINE(int) RT_IPRT_FORMAT_ATTR(5, 6) PDMUsbDBGFStop(PPDMUSBINS pUsbIns, RT_SRC_POS_DECL, const char *pszFormat, ...)
|
---|
899 | {
|
---|
900 | #ifdef VBOX_STRICT
|
---|
901 | int rc;
|
---|
902 | va_list va;
|
---|
903 | va_start(va, pszFormat);
|
---|
904 | rc = pUsbIns->pHlpR3->pfnDBGFStopV(pUsbIns, RT_SRC_POS_ARGS, pszFormat, va);
|
---|
905 | va_end(va);
|
---|
906 | return rc;
|
---|
907 | #else
|
---|
908 | NOREF(pUsbIns);
|
---|
909 | NOREF(pszFile);
|
---|
910 | NOREF(iLine);
|
---|
911 | NOREF(pszFunction);
|
---|
912 | NOREF(pszFormat);
|
---|
913 | return VINF_SUCCESS;
|
---|
914 | #endif
|
---|
915 | }
|
---|
916 |
|
---|
917 | /**
|
---|
918 | * @copydoc PDMUSBHLP::pfnVMState
|
---|
919 | */
|
---|
920 | DECLINLINE(VMSTATE) PDMUsbHlpVMState(PPDMUSBINS pUsbIns)
|
---|
921 | {
|
---|
922 | return pUsbIns->pHlpR3->pfnVMState(pUsbIns);
|
---|
923 | }
|
---|
924 |
|
---|
925 | /**
|
---|
926 | * @copydoc PDMUSBHLP::pfnThreadCreate
|
---|
927 | */
|
---|
928 | DECLINLINE(int) PDMUsbHlpThreadCreate(PPDMUSBINS pUsbIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADUSB pfnThread,
|
---|
929 | PFNPDMTHREADWAKEUPUSB pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
|
---|
930 | {
|
---|
931 | return pUsbIns->pHlpR3->pfnThreadCreate(pUsbIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
|
---|
932 | }
|
---|
933 |
|
---|
934 |
|
---|
935 | /**
|
---|
936 | * @copydoc PDMUSBHLP::pfnSetAsyncNotification
|
---|
937 | */
|
---|
938 | DECLINLINE(int) PDMUsbHlpSetAsyncNotification(PPDMUSBINS pUsbIns, PFNPDMUSBASYNCNOTIFY pfnAsyncNotify)
|
---|
939 | {
|
---|
940 | return pUsbIns->pHlpR3->pfnSetAsyncNotification(pUsbIns, pfnAsyncNotify);
|
---|
941 | }
|
---|
942 |
|
---|
943 | /**
|
---|
944 | * @copydoc PDMUSBHLP::pfnAsyncNotificationCompleted
|
---|
945 | */
|
---|
946 | DECLINLINE(void) PDMUsbHlpAsyncNotificationCompleted(PPDMUSBINS pUsbIns)
|
---|
947 | {
|
---|
948 | pUsbIns->pHlpR3->pfnAsyncNotificationCompleted(pUsbIns);
|
---|
949 | }
|
---|
950 |
|
---|
951 | /**
|
---|
952 | * Set the VM error message
|
---|
953 | *
|
---|
954 | * @returns rc.
|
---|
955 | * @param pUsbIns The USB device instance.
|
---|
956 | * @param rc VBox status code.
|
---|
957 | * @param SRC_POS Use RT_SRC_POS.
|
---|
958 | * @param pszFormat Error message format string.
|
---|
959 | * @param ... Error message arguments.
|
---|
960 | */
|
---|
961 | DECLINLINE(int) RT_IPRT_FORMAT_ATTR(6, 7) PDMUsbHlpVMSetError(PPDMUSBINS pUsbIns, int rc, RT_SRC_POS_DECL,
|
---|
962 | const char *pszFormat, ...)
|
---|
963 | {
|
---|
964 | va_list va;
|
---|
965 | va_start(va, pszFormat);
|
---|
966 | rc = pUsbIns->pHlpR3->pfnVMSetErrorV(pUsbIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
|
---|
967 | va_end(va);
|
---|
968 | return rc;
|
---|
969 | }
|
---|
970 |
|
---|
971 | /**
|
---|
972 | * @copydoc PDMUSBHLP::pfnMMHeapAlloc
|
---|
973 | */
|
---|
974 | DECLINLINE(void *) PDMUsbHlpMMHeapAlloc(PPDMUSBINS pUsbIns, size_t cb)
|
---|
975 | {
|
---|
976 | return pUsbIns->pHlpR3->pfnMMHeapAlloc(pUsbIns, cb);
|
---|
977 | }
|
---|
978 |
|
---|
979 | /**
|
---|
980 | * @copydoc PDMUSBHLP::pfnMMHeapAllocZ
|
---|
981 | */
|
---|
982 | DECLINLINE(void *) PDMUsbHlpMMHeapAllocZ(PPDMUSBINS pUsbIns, size_t cb)
|
---|
983 | {
|
---|
984 | return pUsbIns->pHlpR3->pfnMMHeapAllocZ(pUsbIns, cb);
|
---|
985 | }
|
---|
986 |
|
---|
987 | /**
|
---|
988 | * Frees memory allocated by PDMUsbHlpMMHeapAlloc or PDMUsbHlpMMHeapAllocZ.
|
---|
989 | *
|
---|
990 | * @param pUsbIns The USB device instance.
|
---|
991 | * @param pv The memory to free. NULL is fine.
|
---|
992 | */
|
---|
993 | DECLINLINE(void) PDMUsbHlpMMHeapFree(PPDMUSBINS pUsbIns, void *pv)
|
---|
994 | {
|
---|
995 | NOREF(pUsbIns);
|
---|
996 | MMR3HeapFree(pv);
|
---|
997 | }
|
---|
998 |
|
---|
999 | /**
|
---|
1000 | * @copydoc PDMUSBHLP::pfnTMTimerCreate
|
---|
1001 | */
|
---|
1002 | DECLINLINE(int) PDMUsbHlpTMTimerCreate(PPDMUSBINS pUsbIns, TMCLOCK enmClock, PFNTMTIMERUSB pfnCallback, void *pvUser,
|
---|
1003 | uint32_t fFlags, const char *pszDesc, PPTMTIMERR3 ppTimer)
|
---|
1004 | {
|
---|
1005 | return pUsbIns->pHlpR3->pfnTMTimerCreate(pUsbIns, enmClock, pfnCallback, pvUser, fFlags, pszDesc, ppTimer);
|
---|
1006 | }
|
---|
1007 |
|
---|
1008 | /**
|
---|
1009 | * @copydoc PDMUSBHLP::pfnSSMRegister
|
---|
1010 | */
|
---|
1011 | DECLINLINE(int) PDMUsbHlpSSMRegister(PPDMUSBINS pUsbIns, uint32_t uVersion, size_t cbGuess,
|
---|
1012 | PFNSSMUSBLIVEPREP pfnLivePrep, PFNSSMUSBLIVEEXEC pfnLiveExec, PFNSSMUSBLIVEVOTE pfnLiveVote,
|
---|
1013 | PFNSSMUSBSAVEPREP pfnSavePrep, PFNSSMUSBSAVEEXEC pfnSaveExec, PFNSSMUSBSAVEDONE pfnSaveDone,
|
---|
1014 | PFNSSMUSBLOADPREP pfnLoadPrep, PFNSSMUSBLOADEXEC pfnLoadExec, PFNSSMUSBLOADDONE pfnLoadDone)
|
---|
1015 | {
|
---|
1016 | return pUsbIns->pHlpR3->pfnSSMRegister(pUsbIns, uVersion, cbGuess,
|
---|
1017 | pfnLivePrep, pfnLiveExec, pfnLiveVote,
|
---|
1018 | pfnSavePrep, pfnSaveExec, pfnSaveDone,
|
---|
1019 | pfnLoadPrep, pfnLoadExec, pfnLoadDone);
|
---|
1020 | }
|
---|
1021 |
|
---|
1022 | #endif /* IN_RING3 */
|
---|
1023 |
|
---|
1024 |
|
---|
1025 |
|
---|
1026 | /** Pointer to callbacks provided to the VBoxUsbRegister() call. */
|
---|
1027 | typedef const struct PDMUSBREGCB *PCPDMUSBREGCB;
|
---|
1028 |
|
---|
1029 | /**
|
---|
1030 | * Callbacks for VBoxUSBDeviceRegister().
|
---|
1031 | */
|
---|
1032 | typedef struct PDMUSBREGCB
|
---|
1033 | {
|
---|
1034 | /** Interface version.
|
---|
1035 | * This is set to PDM_USBREG_CB_VERSION. */
|
---|
1036 | uint32_t u32Version;
|
---|
1037 |
|
---|
1038 | /**
|
---|
1039 | * Registers a device with the current VM instance.
|
---|
1040 | *
|
---|
1041 | * @returns VBox status code.
|
---|
1042 | * @param pCallbacks Pointer to the callback table.
|
---|
1043 | * @param pReg Pointer to the USB device registration record.
|
---|
1044 | * This data must be permanent and readonly.
|
---|
1045 | */
|
---|
1046 | DECLR3CALLBACKMEMBER(int, pfnRegister,(PCPDMUSBREGCB pCallbacks, PCPDMUSBREG pReg));
|
---|
1047 | } PDMUSBREGCB;
|
---|
1048 |
|
---|
1049 | /** Current version of the PDMUSBREGCB structure. */
|
---|
1050 | #define PDM_USBREG_CB_VERSION PDM_VERSION_MAKE(0xeefc, 1, 0)
|
---|
1051 |
|
---|
1052 |
|
---|
1053 | /**
|
---|
1054 | * The VBoxUsbRegister callback function.
|
---|
1055 | *
|
---|
1056 | * PDM will invoke this function after loading a USB device module and letting
|
---|
1057 | * the module decide which devices to register and how to handle conflicts.
|
---|
1058 | *
|
---|
1059 | * @returns VBox status code.
|
---|
1060 | * @param pCallbacks Pointer to the callback table.
|
---|
1061 | * @param u32Version VBox version number.
|
---|
1062 | */
|
---|
1063 | typedef DECLCALLBACK(int) FNPDMVBOXUSBREGISTER(PCPDMUSBREGCB pCallbacks, uint32_t u32Version);
|
---|
1064 |
|
---|
1065 | VMMR3DECL(int) PDMR3UsbCreateEmulatedDevice(PUVM pUVM, const char *pszDeviceName, PCFGMNODE pDeviceNode, PCRTUUID pUuid,
|
---|
1066 | const char *pszCaptureFilename);
|
---|
1067 | VMMR3DECL(int) PDMR3UsbCreateProxyDevice(PUVM pUVM, PCRTUUID pUuid, const char *pszBackend, const char *pszAddress, void *pvBackend,
|
---|
1068 | uint32_t iUsbVersion, uint32_t fMaskedIfs, const char *pszCaptureFilename);
|
---|
1069 | VMMR3DECL(int) PDMR3UsbDetachDevice(PUVM pUVM, PCRTUUID pUuid);
|
---|
1070 | VMMR3DECL(bool) PDMR3UsbHasHub(PUVM pUVM);
|
---|
1071 | VMMR3DECL(int) PDMR3UsbDriverAttach(PUVM pUVM, const char *pszDevice, unsigned iDevIns, unsigned iLun, uint32_t fFlags,
|
---|
1072 | PPPDMIBASE ppBase);
|
---|
1073 | VMMR3DECL(int) PDMR3UsbDriverDetach(PUVM pUVM, const char *pszDevice, unsigned iDevIns, unsigned iLun,
|
---|
1074 | const char *pszDriver, unsigned iOccurance, uint32_t fFlags);
|
---|
1075 | VMMR3DECL(int) PDMR3UsbQueryLun(PUVM pUVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
|
---|
1076 |
|
---|
1077 | /** @} */
|
---|
1078 |
|
---|
1079 | RT_C_DECLS_END
|
---|
1080 |
|
---|
1081 | #endif
|
---|