pdmusb.h@ 3856

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

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

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

Download in other formats: