pdmusb.h@ 4014

Last change on this file since 4014 was 4014, checked in by vboxsync, 17 years ago
Use pdmdrv.h and pdmdev.h where appropirate.
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 21.7 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 as published by the Free Software Foundation,
12	* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13	* distribution. VirtualBox OSE is distributed in the hope that it will
14	* be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* If you received this file as part of a commercial VirtualBox
17	* distribution, then only the terms of your commercial VirtualBox
18	* license agreement apply instead of the previous paragraph.
19	*/
20
21	#ifndef ___VBox_pdmusb_h
22	#define ___VBox_pdmusb_h
23
24	#include <VBox/pdmqueue.h>
25	#include <VBox/pdmcritsect.h>
26	#include <VBox/pdmthread.h>
27	#include <VBox/pdmifs.h>
28	#include <VBox/tm.h>
29	#include <VBox/ssm.h>
30	#include <VBox/cfgm.h>
31	#include <VBox/dbgf.h>
32	#include <VBox/mm.h>
33	#include <VBox/err.h>
34	#include <iprt/stdarg.h>
35
36	__BEGIN_DECLS
37
38	/** @defgroup grp_pdm_usbdev USB Devices
39	* @ingroup grp_pdm
40	* @{
41	*/
42
43
44	/** PDM USB Device Registration Structure,
45	*
46	* This structure is used when registering a device from VBoxUsbRegister() in HC Ring-3.
47	* The PDM will make use of this structure untill the VM is destroyed.
48	*/
49	typedef struct PDMUSBREG
50	{
51	/** Structure version. PDM_DEVREG_VERSION defines the current version. */
52	uint32_t u32Version;
53	/** Device name. */
54	char szDeviceName[32];
55	/** The description of the device. The UTF-8 string pointed to shall, like this structure,
56	* remain unchanged from registration till VM destruction. */
57	const char *pszDescription;
58
59	/** Flags, combination of the PDM_USBREG_FLAGS_* \#defines. */
60	RTUINT fFlags;
61	/** Maximum number of instances (per VM). */
62	RTUINT cMaxInstances;
63	/** Size of the instance data. */
64	RTUINT cbInstance;
65
66
67	/**
68	* Construct an USB device instance for a VM.
69	*
70	* @returns VBox status.
71	* @param pUsbIns The USB device instance data.
72	* If the registration structure is needed, pUsbDev->pDevReg points to it.
73	* @param iInstance Instance number. Use this to figure out which registers and such to use.
74	* The instance number is also found in pUsbDev->iInstance, but since it's
75	* likely to be freqently used PDM passes it as parameter.
76	* @param pCfg Configuration node handle for the device. Use this to obtain the configuration
77	* of the device instance. It's also found in pUsbDev->pCfg, but since it's
78	* primary usage will in this function it's passed as a parameter.
79	* @param pCfgGlobal Handle to the global device configuration. Also found in pUsbDev->pCfgGlobal.
80	* @remarks This callback is required.
81	*/
82	DECLR3CALLBACKMEMBER(int, pfnConstruct,(PPDMUSBINS pUsbIns, int iInstance, PCFGMNODE pCfg, PCFGMNODE pCfgGlobal));
83
84	/**
85	* Init complete notification.
86	*
87	* This can be done to do communication with other devices and other
88	* initialization which requires everything to be in place.
89	*
90	* @returns VBOX status code.
91	* @param pUsbIns The USB device instance data.
92	* @remarks Optional.
93	*/
94	DECLR3CALLBACKMEMBER(int, pfnInitComplete,(PPDMUSBINS pUsbIns));
95
96	/**
97	* Destruct an USB device instance.
98	*
99	* Most VM resources are freed by the VM. This callback is provided so that any non-VM
100	* resources can be freed correctly.
101	*
102	* This method will be called regardless of the pfnConstruc result to avoid
103	* complicated failure paths.
104	*
105	* @returns VBox status.
106	* @param pUsbIns The USB device instance data.
107	* @remarks Optional.
108	*/
109	DECLR3CALLBACKMEMBER(int, pfnDestruct,(PPDMUSBINS pUsbIns));
110
111	/**
112	* Power On notification.
113	*
114	* @returns VBox status.
115	* @param pUsbIns The USB device instance data.
116	* @remarks Optional.
117	*/
118	DECLR3CALLBACKMEMBER(void, pfnPowerOn,(PPDMUSBINS pUsbIns));
119
120	/**
121	* Reset notification.
122	*
123	* @returns VBox status.
124	* @param pUsbIns The USB device instance data.
125	* @remarks Optional.
126	*/
127	DECLR3CALLBACKMEMBER(void, pfnReset,(PPDMUSBINS pUsbIns));
128
129	/**
130	* Suspend notification.
131	*
132	* @returns VBox status.
133	* @param pUsbIns The USB device instance data.
134	* @remarks Optional.
135	*/
136	DECLR3CALLBACKMEMBER(void, pfnSuspend,(PPDMUSBINS pUsbIns));
137
138	/**
139	* Resume notification.
140	*
141	* @returns VBox status.
142	* @param pUsbIns The USB device instance data.
143	* @remarks Optional.
144	*/
145	DECLR3CALLBACKMEMBER(void, pfnResume,(PPDMUSBINS pUsbIns));
146
147	/**
148	* Power Off notification.
149	*
150	* @param pUsbIns The USB device instance data.
151	*/
152	DECLR3CALLBACKMEMBER(void, pfnPowerOff,(PPDMUSBINS pUsbIns));
153
154	/**
155	* Attach command.
156	*
157	* This is called to let the USB device attach to a driver for a specified LUN
158	* at runtime. This is not called during VM construction, the device constructor
159	* have to attach to all the available drivers.
160	*
161	* @returns VBox status code.
162	* @param pUsbIns The USB device instance data.
163	* @param iLUN The logical unit which is being detached.
164	* @remarks Optional.
165	*/
166	DECLR3CALLBACKMEMBER(int, pfnAttach,(PPDMUSBINS pUsbIns, unsigned iLUN));
167
168	/**
169	* Detach notification.
170	*
171	* This is called when a driver is detaching itself from a LUN of the device.
172	* The device should adjust it's state to reflect this.
173	*
174	* @param pUsbIns The USB device instance data.
175	* @param iLUN The logical unit which is being detached.
176	* @remarks Optional.
177	*/
178	DECLR3CALLBACKMEMBER(void, pfnDetach,(PPDMUSBINS pUsbIns, unsigned iLUN));
179
180	/**
181	* Query the base interface of a logical unit.
182	*
183	* @returns VBOX status code.
184	* @param pUsbIns The USB device instance data.
185	* @param iLUN The logicial unit to query.
186	* @param ppBase Where to store the pointer to the base interface of the LUN.
187	* @remarks Optional.
188	*/
189	DECLR3CALLBACKMEMBER(int, pfnQueryInterface,(PPDMUSBINS pUsbIns, unsigned iLUN, PPDMIBASE *ppBase));
190
191	/** Just some init precaution. Must be set to PDM_USBREG_VERSION. */
192	uint32_t u32TheEnd;
193	} PDMUSBREG;
194	/** Pointer to a PDM USB Device Structure. */
195	typedef PDMUSBREG *PPDMUSBREG;
196	/** Const pointer to a PDM USB Device Structure. */
197	typedef PDMUSBREG const *PCPDMUSBREG;
198
199	/** Current USBREG version number. */
200	#define PDM_USBREG_VERSION 0xed010000
201
202	/** PDM USB Device Flags.
203	* @{ */
204	/* none yet */
205	/** @} */
206
207	#ifdef IN_RING3
208	/**
209	* PDM USB Device API.
210	*/
211	typedef struct PDMUSBHLP
212	{
213	/** Structure version. PDM_USBHLP_VERSION defines the current version. */
214	uint32_t u32Version;
215
216	/**
217	* Attaches a driver (chain) to the USB device.
218	*
219	* The first call for a LUN this will serve as a registartion of the LUN. The pBaseInterface and
220	* the pszDesc string will be registered with that LUN and kept around for PDMR3QueryUSBDeviceLun().
221	*
222	* @returns VBox status code.
223	* @param pUsbIns The USB device instance.
224	* @param iLun The logical unit to attach.
225	* @param pBaseInterface Pointer to the base interface for that LUN. (device side / down)
226	* @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up)
227	* @param pszDesc Pointer to a string describing the LUN. This string must remain valid
228	* for the live of the device instance.
229	*/
230	DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMUSBINS pUsbIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE ppBaseInterface, const char pszDesc));
231
232	/**
233	* Assert that the current thread is the emulation thread.
234	*
235	* @returns True if correct.
236	* @returns False if wrong.
237	* @param pUsbIns The USB device instance.
238	* @param pszFile Filename of the assertion location.
239	* @param iLine Linenumber of the assertion location.
240	* @param pszFunction Function of the assertion location.
241	*/
242	DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMUSBINS pUsbIns, const char pszFile, unsigned iLine, const char pszFunction));
243
244	/**
245	* Assert that the current thread is NOT the emulation thread.
246	*
247	* @returns True if correct.
248	* @returns False if wrong.
249	* @param pUsbIns The USB device instance.
250	* @param pszFile Filename of the assertion location.
251	* @param iLine Linenumber of the assertion location.
252	* @param pszFunction Function of the assertion location.
253	*/
254	DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMUSBINS pUsbIns, const char pszFile, unsigned iLine, const char pszFunction));
255
256	/**
257	* Stops the VM and enters the debugger to look at the guest state.
258	*
259	* Use the PDMUsbDBGFStop() inline function with the RT_SRC_POS macro instead of
260	* invoking this function directly.
261	*
262	* @returns VBox status code which must be passed up to the VMM.
263	* @param pUsbIns The USB device instance.
264	* @param pszFile Filename of the assertion location.
265	* @param iLine The linenumber of the assertion location.
266	* @param pszFunction Function of the assertion location.
267	* @param pszFormat Message. (optional)
268	* @param va Message parameters.
269	*/
270	DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMUSBINS pUsbIns, const char pszFile, unsigned iLine, const char pszFunction, const char *pszFormat, va_list va));
271
272	/**
273	* Register a info handler with DBGF,
274	*
275	* @returns VBox status code.
276	* @param pUsbIns The USB device instance.
277	* @param pszName The identifier of the info.
278	* @param pszDesc The description of the info and any arguments the handler may take.
279	* @param pfnHandler The handler function to be called to display the info.
280	*/
281	/** @todo DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMUSBINS pUsbIns, const char pszName, const char pszDesc, PFNDBGFHANDLERUSB pfnHandler)); */
282
283	/**
284	* Allocate memory which is associated with current VM instance
285	* and automatically freed on it's destruction.
286	*
287	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
288	* @param pUsbIns The USB device instance.
289	* @param cb Number of bytes to allocate.
290	*/
291	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMUSBINS pUsbIns, size_t cb));
292
293	/**
294	* Allocate memory which is associated with current VM instance
295	* and automatically freed on it's destruction. The memory is ZEROed.
296	*
297	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
298	* @param pUsbIns The USB device instance.
299	* @param cb Number of bytes to allocate.
300	*/
301	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAllocZ,(PPDMUSBINS pUsbIns, size_t cb));
302
303	/**
304	* Create a queue.
305	*
306	* @returns VBox status code.
307	* @param pUsbIns The USB device instance.
308	* @param cbItem Size a queue item.
309	* @param cItems Number of items in the queue.
310	* @param cMilliesInterval Number of milliseconds between polling the queue.
311	* If 0 then the emulation thread will be notified whenever an item arrives.
312	* @param pfnCallback The consumer function.
313	* @param ppQueue Where to store the queue handle on success.
314	* @thread The emulation thread.
315	*/
316	/** @todo DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMUSBINS pUsbIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, PFNPDMQUEUEUSB pfnCallback, PPDMQUEUE ppQueue)); /
317
318	/**
319	* Register a save state data unit.
320	*
321	* @returns VBox status.
322	* @param pUsbIns The USB device instance.
323	* @param pszName Data unit name.
324	* @param u32Instance The instance identifier of the data unit.
325	* This must together with the name be unique.
326	* @param u32Version Data layout version number.
327	* @param cbGuess The approximate amount of data in the unit.
328	* Only for progress indicators.
329	* @param pfnSavePrep Prepare save callback, optional.
330	* @param pfnSaveExec Execute save callback, optional.
331	* @param pfnSaveDone Done save callback, optional.
332	* @param pfnLoadPrep Prepare load callback, optional.
333	* @param pfnLoadExec Execute load callback, optional.
334	* @param pfnLoadDone Done load callback, optional.
335	*/
336	/** @todo DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMUSBINS pUsbIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
337	PFNSSMUSBSAVEPREP pfnSavePrep, PFNSSMUSBSAVEEXEC pfnSaveExec, PFNSSMUSBSAVEDONE pfnSaveDone,
338	PFNSSMUSBLOADPREP pfnLoadPrep, PFNSSMUSBLOADEXEC pfnLoadExec, PFNSSMUSBLOADDONE pfnLoadDone)); */
339
340	/**
341	* Register a STAM sample.
342	*
343	* Use the PDMUsbHlpSTAMRegister wrapper.
344	*
345	* @returns VBox status.
346	* @param pUsbIns The USB device instance.
347	* @param pvSample Pointer to the sample.
348	* @param enmType Sample type. This indicates what pvSample is pointing at.
349	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
350	* @param enmUnit Sample unit.
351	* @param pszDesc Sample description.
352	* @param pszName The sample name format string.
353	* @param va Arguments to the format string.
354	*/
355	DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMUSBINS pUsbIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
356	STAMUNIT enmUnit, const char pszDesc, const char pszName, va_list va));
357
358	/**
359	* Creates a timer.
360	*
361	* @returns VBox status.
362	* @param pUsbIns The USB device instance.
363	* @param enmClock The clock to use on this timer.
364	* @param pfnCallback Callback function.
365	* @param pszDesc Pointer to description string which must stay around
366	* until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
367	* @param ppTimer Where to store the timer on success.
368	*/
369	/** @todo DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMUSBINS pUsbIns, TMCLOCK enmClock, PFNTMTIMERUSB pfnCallback, const char pszDesc, PPTMTIMERHC ppTimer)); /
370
371	/**
372	* Set the VM error message
373	*
374	* @returns rc.
375	* @param pUsbIns The USB device instance.
376	* @param rc VBox status code.
377	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
378	* @param pszFormat Error message format string.
379	* @param va Error message arguments.
380	*/
381	DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMUSBINS pUsbIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
382
383	/**
384	* Set the VM runtime error message
385	*
386	* @returns VBox status code.
387	* @param pUsbIns The USB device instance.
388	* @param fFatal Whether it is a fatal error or not.
389	* @param pszErrorID Error ID string.
390	* @param pszFormat Error message format string.
391	* @param va Error message arguments.
392	*/
393	DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMUSBINS pUsbIns, bool fFatal, const char pszErrorID, const char pszFormat, va_list va));
394
395	/** Just a safety precaution. */
396	uint32_t u32TheEnd;
397	} PDMUSBHLP;
398	/** Pointer PDM USB Device API. */
399	typedef PDMUSBHLP *PPDMUSBHLP;
400	/** Pointer const PDM USB Device API. */
401	typedef const PDMUSBHLP *PCPDMUSBHLP;
402
403	/** Current USBHLP version number. */
404	#define PDM_USBHLP_VERSION 0xec020000
405
406	#endif /* IN_RING3 */
407
408	/**
409	* PDM USB Device Instance.
410	*/
411	typedef struct PDMUSBINS
412	{
413	/** Structure version. PDM_USBINS_VERSION defines the current version. */
414	uint32_t u32Version;
415	/** USB device instance number. */
416	RTUINT iInstance;
417	/** The base interface of the device.
418	* The device constructor initializes this if it has any device level
419	* interfaces to export. To obtain this interface call PDMR3QueryUSBDevice(). */
420	PDMIBASE IBase;
421
422	/** Internal data. */
423	union
424	{
425	#ifdef PDMUSBINSINT_DECLARED
426	PDMUSBINSINT s;
427	#endif
428	uint8_t padding[HC_ARCH_BITS == 32 ? 48 : 96];
429	} Internal;
430
431	/** Pointer the PDM USB Device API. */
432	R3PTRTYPE(PCPDMUSBHLP) pUsbHlp;
433	/** Pointer to the USB device registration structure. */
434	R3PTRTYPE(PCPDMUSBREG) pUsbReg;
435	/** Configuration handle. */
436	R3PTRTYPE(PCFGMNODE) pCfg;
437	/** The (device) global configuration handle. */
438	R3PTRTYPE(PCFGMNODE) pCfgGlobal;
439	/** Pointer to device instance data. */
440	R3PTRTYPE(void *) pvInstanceDataR3;
441	/* padding to make achInstanceData aligned at 32 byte boundrary. */
442	uint32_t au32Padding[HC_ARCH_BITS == 32 ? 4 : 6];
443	/** Device instance data. The size of this area is defined
444	* in the PDMUSBREG::cbInstanceData field. */
445	char achInstanceData[8];
446	} PDMUSBINS;
447
448	/** Current USBINS version number. */
449	#define PDM_USBINS_VERSION 0xf3010000
450
451	/** Converts a pointer to the PDMUSBINS::IBase to a pointer to PDMUSBINS. */
452	#define PDMIBASE_2_PDMUSB(pInterface) ( (PPDMUSBINS)((char *)(pInterface) - RT_OFFSETOF(PDMUSBINS, IBase)) )
453
454
455	/** @def PDMUSB_ASSERT_EMT
456	* Assert that the current thread is the emulation thread.
457	*/
458	#ifdef VBOX_STRICT
459	# define PDMUSB_ASSERT_EMT(pUsbIns) pUsbIns->pUsbHlp->pfnAssertEMT(pUsbIns, __FILE__, __LINE__, __FUNCTION__)
460	#else
461	# define PDMUSB_ASSERT_EMT(pUsbIns) do { } while (0)
462	#endif
463
464	/** @def PDMUSB_ASSERT_OTHER
465	* Assert that the current thread is NOT the emulation thread.
466	*/
467	#ifdef VBOX_STRICT
468	# define PDMUSB_ASSERT_OTHER(pUsbIns) pUsbIns->pUsbHlp->pfnAssertOther(pUsbIns, __FILE__, __LINE__, __FUNCTION__)
469	#else
470	# define PDMUSB_ASSERT_OTHER(pUsbIns) do { } while (0)
471	#endif
472
473	/** @def PDMUSB_SET_ERROR
474	* Set the VM error. See PDMDevHlpVMSetError() for printf like message formatting.
475	*/
476	#define PDMUSB_SET_ERROR(pUsbIns, rc, pszError) \
477	PDMDevHlpVMSetError(pUsbIns, rc, RT_SRC_POS, "%s", pszError)
478
479	/** @def PDMUSB_SET_RUNTIME_ERROR
480	* Set the VM runtime error. See PDMDevHlpVMSetRuntimeError() for printf like message formatting.
481	*/
482	#define PDMUSB_SET_RUNTIME_ERROR(pUsbIns, fFatal, pszErrorID, pszError) \
483	PDMDevHlpVMSetRuntimeError(pUsbIns, fFatal, pszErrorID, "%s", pszError)
484
485
486	#ifdef IN_RING3
487
488	/**
489	* VBOX_STRICT wrapper for pUsbHlp->pfnDBGFStopV.
490	*
491	* @returns VBox status code which must be passed up to the VMM.
492	* @param pUsbIns Device instance.
493	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
494	* @param pszFormat Message. (optional)
495	* @param ... Message parameters.
496	*/
497	DECLINLINE(int) PDMUsbDBGFStop(PPDMUSBINS pUsbIns, RT_SRC_POS_DECL, const char *pszFormat, ...)
498	{
499	#ifdef VBOX_STRICT
500	int rc;
501	va_list va;
502	va_start(va, pszFormat);
503	rc = pUsbIns->pUsbHlp->pfnDBGFStopV(pUsbIns, RT_SRC_POS_ARGS, pszFormat, va);
504	va_end(va);
505	return rc;
506	#else
507	return VINF_SUCCESS;
508	#endif
509	}
510
511
512	/* inline wrappers */
513
514	#endif
515
516
517
518	/** Pointer to callbacks provided to the VBoxUsbRegister() call. */
519	typedef const struct PDMUSBREGCB *PCPDMUSBREGCB;
520
521	/**
522	* Callbacks for VBoxUSBDeviceRegister().
523	*/
524	typedef struct PDMUSBREGCB
525	{
526	/** Interface version.
527	* This is set to PDM_USBREG_CB_VERSION. */
528	uint32_t u32Version;
529
530	/**
531	* Registers a device with the current VM instance.
532	*
533	* @returns VBox status code.
534	* @param pCallbacks Pointer to the callback table.
535	* @param pDevReg Pointer to the device registration record.
536	* This data must be permanent and readonly.
537	*/
538	DECLR3CALLBACKMEMBER(int, pfnRegister,(PCPDMUSBREGCB pCallbacks, PCPDMUSBREG pDevReg));
539
540	/**
541	* Allocate memory which is associated with current VM instance
542	* and automatically freed on it's destruction.
543	*
544	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
545	* @param pCallbacks Pointer to the callback table.
546	* @param cb Number of bytes to allocate.
547	*/
548	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PCPDMUSBREGCB pCallbacks, size_t cb));
549	} PDMUSBREGCB;
550
551	/** Current version of the PDMUSBREGCB structure. */
552	#define PDM_USBREG_CB_VERSION 0xee010000
553
554
555	/**
556	* The VBoxUsbRegister callback function.
557	*
558	* PDM will invoke this function after loading a USB device module and letting
559	* the module decide which devices to register and how to handle conflicts.
560	*
561	* @returns VBox status code.
562	* @param pCallbacks Pointer to the callback table.
563	* @param u32Version VBox version number.
564	*/
565	typedef DECLCALLBACK(int) FNPDMVBOXUSBREGISTER(PCPDMUSBREGCB pCallbacks, uint32_t u32Version);
566
567	/** @} */
568
569	__END_DECLS
570
571	#endif

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: