pdmusb.h@ 4506

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

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

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

Download in other formats: