pdmdrv.h@ 7581

Last change on this file since 7581 was 6221, checked in by vboxsync, 17 years ago
PDM async completion template creation wrapper third attempt
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 33.0 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, Drivers.
3	*/
4
5	/*
6	* Copyright (C) 2006-2007 innotek GmbH
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___VBox_pdmdrv_h
27	#define ___VBox_pdmdrv_h
28
29	#include <VBox/pdmqueue.h>
30	#include <VBox/pdmcritsect.h>
31	#include <VBox/pdmthread.h>
32	#include <VBox/pdmifs.h>
33	#include <VBox/pdmins.h>
34	#include <VBox/tm.h>
35	#include <VBox/ssm.h>
36	#include <VBox/cfgm.h>
37	#include <VBox/dbgf.h>
38	#include <VBox/mm.h>
39	#include <VBox/err.h>
40	#include <iprt/stdarg.h>
41
42	#ifdef VBOX_WITH_PDM_ASYNC_COMPLETION
43	# include <VBox/pdmasynccompletion.h>
44	#endif
45
46	__BEGIN_DECLS
47
48	/** @defgroup grp_pdm_driver Drivers
49	* @ingroup grp_pdm
50	* @{
51	*/
52
53	/**
54	* Construct a driver instance for a VM.
55	*
56	* @returns VBox status.
57	* @param pDrvIns The driver instance data.
58	* If the registration structure is needed, pDrvIns->pDrvReg points to it.
59	* @param pCfgHandle Configuration node handle for the driver. Use this to obtain the configuration
60	* of the driver instance. It's also found in pDrvIns->pCfgHandle as it's expected
61	* to be used frequently in this function.
62	*/
63	typedef DECLCALLBACK(int) FNPDMDRVCONSTRUCT(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle);
64	/** Pointer to a FNPDMDRVCONSTRUCT() function. */
65	typedef FNPDMDRVCONSTRUCT *PFNPDMDRVCONSTRUCT;
66
67	/**
68	* Destruct a driver instance.
69	*
70	* Most VM resources are freed by the VM. This callback is provided so that
71	* any non-VM resources can be freed correctly.
72	*
73	* @param pDrvIns The driver instance data.
74	*/
75	typedef DECLCALLBACK(void) FNPDMDRVDESTRUCT(PPDMDRVINS pDrvIns);
76	/** Pointer to a FNPDMDRVDESTRUCT() function. */
77	typedef FNPDMDRVDESTRUCT *PFNPDMDRVDESTRUCT;
78
79	/**
80	* Driver I/O Control interface.
81	*
82	* This is used by external components, such as the COM interface, to
83	* communicate with a driver using a driver specific interface. Generally,
84	* the driver interfaces are used for this task.
85	*
86	* @returns VBox status code.
87	* @param pDrvIns Pointer to the driver instance.
88	* @param uFunction Function to perform.
89	* @param pvIn Pointer to input data.
90	* @param cbIn Size of input data.
91	* @param pvOut Pointer to output data.
92	* @param cbOut Size of output data.
93	* @param pcbOut Where to store the actual size of the output data.
94	*/
95	typedef DECLCALLBACK(int) FNPDMDRVIOCTL(PPDMDRVINS pDrvIns, RTUINT uFunction,
96	void *pvIn, RTUINT cbIn,
97	void *pvOut, RTUINT cbOut, PRTUINT pcbOut);
98	/** Pointer to a FNPDMDRVIOCTL() function. */
99	typedef FNPDMDRVIOCTL *PFNPDMDRVIOCTL;
100
101	/**
102	* Power On notification.
103	*
104	* @param pDrvIns The driver instance data.
105	*/
106	typedef DECLCALLBACK(void) FNPDMDRVPOWERON(PPDMDRVINS pDrvIns);
107	/** Pointer to a FNPDMDRVPOWERON() function. */
108	typedef FNPDMDRVPOWERON *PFNPDMDRVPOWERON;
109
110	/**
111	* Reset notification.
112	*
113	* @returns VBox status.
114	* @param pDrvIns The driver instance data.
115	*/
116	typedef DECLCALLBACK(void) FNPDMDRVRESET(PPDMDRVINS pDrvIns);
117	/** Pointer to a FNPDMDRVRESET() function. */
118	typedef FNPDMDRVRESET *PFNPDMDRVRESET;
119
120	/**
121	* Suspend notification.
122	*
123	* @returns VBox status.
124	* @param pDrvIns The driver instance data.
125	*/
126	typedef DECLCALLBACK(void) FNPDMDRVSUSPEND(PPDMDRVINS pDrvIns);
127	/** Pointer to a FNPDMDRVSUSPEND() function. */
128	typedef FNPDMDRVSUSPEND *PFNPDMDRVSUSPEND;
129
130	/**
131	* Resume notification.
132	*
133	* @returns VBox status.
134	* @param pDrvIns The driver instance data.
135	*/
136	typedef DECLCALLBACK(void) FNPDMDRVRESUME(PPDMDRVINS pDrvIns);
137	/** Pointer to a FNPDMDRVRESUME() function. */
138	typedef FNPDMDRVRESUME *PFNPDMDRVRESUME;
139
140	/**
141	* Power Off notification.
142	*
143	* @param pDrvIns The driver instance data.
144	*/
145	typedef DECLCALLBACK(void) FNPDMDRVPOWEROFF(PPDMDRVINS pDrvIns);
146	/** Pointer to a FNPDMDRVPOWEROFF() function. */
147	typedef FNPDMDRVPOWEROFF *PFNPDMDRVPOWEROFF;
148
149	/**
150	* Detach notification.
151	*
152	* This is called when a driver below it in the chain is detaching itself
153	* from it. The driver should adjust it's state to reflect this.
154	*
155	* This is like ejecting a cdrom or floppy.
156	*
157	* @param pDrvIns The driver instance.
158	*/
159	typedef DECLCALLBACK(void) FNPDMDRVDETACH(PPDMDRVINS pDrvIns);
160	/** Pointer to a FNPDMDRVDETACH() function. */
161	typedef FNPDMDRVDETACH *PFNPDMDRVDETACH;
162
163
164
165	/** PDM Driver Registration Structure,
166	* This structure is used when registering a driver from
167	* VBoxInitDrivers() (HC Ring-3). PDM will continue use till
168	* the VM is terminated.
169	*/
170	typedef struct PDMDRVREG
171	{
172	/** Structure version. PDM_DRVREG_VERSION defines the current version. */
173	uint32_t u32Version;
174	/** Driver name. */
175	char szDriverName[32];
176	/** The description of the driver. The UTF-8 string pointed to shall, like this structure,
177	* remain unchanged from registration till VM destruction. */
178	const char *pszDescription;
179
180	/** Flags, combination of the PDM_DRVREG_FLAGS_* \#defines. */
181	RTUINT fFlags;
182	/** Driver class(es), combination of the PDM_DRVREG_CLASS_* \#defines. */
183	RTUINT fClass;
184	/** Maximum number of instances (per VM). */
185	RTUINT cMaxInstances;
186	/** Size of the instance data. */
187	RTUINT cbInstance;
188
189	/** Construct instance - required. */
190	PFNPDMDRVCONSTRUCT pfnConstruct;
191	/** Destruct instance - optional. */
192	PFNPDMDRVDESTRUCT pfnDestruct;
193	/** I/O control - optional. */
194	PFNPDMDRVIOCTL pfnIOCtl;
195	/** Power on notification - optional. */
196	PFNPDMDRVPOWERON pfnPowerOn;
197	/** Reset notification - optional. */
198	PFNPDMDRVRESET pfnReset;
199	/** Suspend notification - optional. */
200	PFNPDMDRVSUSPEND pfnSuspend;
201	/** Resume notification - optional. */
202	PFNPDMDRVRESUME pfnResume;
203	/** Detach notification - optional. */
204	PFNPDMDRVDETACH pfnDetach;
205	/** Power off notification - optional. */
206	PFNPDMDRVPOWEROFF pfnPowerOff;
207
208	} PDMDRVREG;
209	/** Pointer to a PDM Driver Structure. */
210	typedef PDMDRVREG *PPDMDRVREG;
211	/** Const pointer to a PDM Driver Structure. */
212	typedef PDMDRVREG const *PCPDMDRVREG;
213
214	/** Current DRVREG version number. */
215	#define PDM_DRVREG_VERSION 0x80010000
216
217	/** PDM Device Flags.
218	* @{ */
219	/** @def PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT
220	* The bit count for the current host. */
221	#if HC_ARCH_BITS == 32
222	# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT 0x000000001
223	#elif HC_ARCH_BITS == 64
224	# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT 0x000000002
225	#else
226	# error Unsupported HC_ARCH_BITS value.
227	#endif
228	/** The host bit count mask. */
229	#define PDM_DRVREG_FLAGS_HOST_BITS_MASK 0x000000003
230
231	/** @} */
232
233
234	/** PDM Driver Classes.
235	* @{ */
236	/** Mouse input driver. */
237	#define PDM_DRVREG_CLASS_MOUSE RT_BIT(0)
238	/** Keyboard input driver. */
239	#define PDM_DRVREG_CLASS_KEYBOARD RT_BIT(1)
240	/** Display driver. */
241	#define PDM_DRVREG_CLASS_DISPLAY RT_BIT(2)
242	/** Network transport driver. */
243	#define PDM_DRVREG_CLASS_NETWORK RT_BIT(3)
244	/** Block driver. */
245	#define PDM_DRVREG_CLASS_BLOCK RT_BIT(4)
246	/** Media driver. */
247	#define PDM_DRVREG_CLASS_MEDIA RT_BIT(5)
248	/** Mountable driver. */
249	#define PDM_DRVREG_CLASS_MOUNTABLE RT_BIT(6)
250	/** Audio driver. */
251	#define PDM_DRVREG_CLASS_AUDIO RT_BIT(7)
252	/** VMMDev driver. */
253	#define PDM_DRVREG_CLASS_VMMDEV RT_BIT(8)
254	/** Status driver. */
255	#define PDM_DRVREG_CLASS_STATUS RT_BIT(9)
256	/** ACPI driver. */
257	#define PDM_DRVREG_CLASS_ACPI RT_BIT(10)
258	/** USB related driver. */
259	#define PDM_DRVREG_CLASS_USB RT_BIT(11)
260	/** ISCSI Transport related driver. */
261	#define PDM_DRVREG_CLASS_ISCSITRANSPORT RT_BIT(12)
262	/** Char driver. */
263	#define PDM_DRVREG_CLASS_CHAR RT_BIT(13)
264	/** Stream driver. */
265	#define PDM_DRVREG_CLASS_STREAM RT_BIT(14)
266	/** @} */
267
268
269	/**
270	* USB hub registration structure.
271	*/
272	typedef struct PDMUSBHUBREG
273	{
274	/** Structure version number. PDM_USBHUBREG_VERSION defines the current version. */
275	uint32_t u32Version;
276
277	/**
278	* Request the hub to attach of the specified device.
279	*
280	* @returns VBox status code.
281	* @param pDrvIns The hub instance.
282	* @param pUsbIns The device to attach.
283	* @param piPort Where to store the port number the device was attached to.
284	* @thread EMT.
285	*/
286	DECLR3CALLBACKMEMBER(int, pfnAttachDevice,(PPDMDRVINS pDrvIns, PPDMUSBINS pUsbIns, uint32_t *piPort));
287
288	/**
289	* Request the hub to detach of the specified device.
290	*
291	* The device has previously been attached to the hub with the
292	* pfnAttachDevice call. This call is not currently expected to
293	* fail.
294	*
295	* @returns VBox status code.
296	* @param pDrvIns The hub instance.
297	* @param pUsbIns The device to detach.
298	* @param iPort The port number returned by the attach call.
299	* @thread EMT.
300	*/
301	DECLR3CALLBACKMEMBER(int, pfnDetachDevice,(PPDMDRVINS pDrvIns, PPDMUSBINS pUsbIns, uint32_t iPort));
302
303	/** Counterpart to u32Version, same value. */
304	uint32_t u32TheEnd;
305	} PDMUSBHUBREG;
306	/** Pointer to a const USB hub registration structure. */
307	typedef const PDMUSBHUBREG *PCPDMUSBHUBREG;
308
309	/** Current PDMUSBHUBREG version number. */
310	#define PDM_USBHUBREG_VERSION 0xeb010000
311
312
313	/**
314	* USB hub helpers.
315	* This is currently just a place holder.
316	*/
317	typedef struct PDMUSBHUBHLP
318	{
319	/** Structure version. PDM_USBHUBHLP_VERSION defines the current version. */
320	uint32_t u32Version;
321
322	/** Just a safety precaution. */
323	uint32_t u32TheEnd;
324	} PDMUSBHUBHLP;
325	/** Pointer to PCI helpers. */
326	typedef PDMUSBHUBHLP *PPDMUSBHUBHLP;
327	/** Pointer to const PCI helpers. */
328	typedef const PDMUSBHUBHLP *PCPDMUSBHUBHLP;
329	/** Pointer to const PCI helpers pointer. */
330	typedef PCPDMUSBHUBHLP *PPCPDMUSBHUBHLP;
331
332	/** Current PDMUSBHUBHLP version number. */
333	#define PDM_USBHUBHLP_VERSION 0xea010000
334
335
336
337	/**
338	* Poller callback.
339	*
340	* @param pDrvIns The driver instance.
341	*/
342	typedef DECLCALLBACK(void) FNPDMDRVPOLLER(PPDMDRVINS pDrvIns);
343	/** Pointer to a FNPDMDRVPOLLER function. */
344	typedef FNPDMDRVPOLLER *PFNPDMDRVPOLLER;
345
346	#ifdef IN_RING3
347	/**
348	* PDM Driver API.
349	*/
350	typedef struct PDMDRVHLP
351	{
352	/** Structure version. PDM_DRVHLP_VERSION defines the current version. */
353	uint32_t u32Version;
354
355	/**
356	* Attaches a driver (chain) to the driver.
357	*
358	* @returns VBox status code.
359	* @param pDrvIns Driver instance.
360	* @param ppBaseInterface Where to store the pointer to the base interface.
361	*/
362	DECLR3CALLBACKMEMBER(int, pfnAttach,(PPDMDRVINS pDrvIns, PPDMIBASE *ppBaseInterface));
363
364	/**
365	* Detach the driver the drivers below us.
366	*
367	* @returns VBox status code.
368	* @param pDrvIns Driver instance.
369	*/
370	DECLR3CALLBACKMEMBER(int, pfnDetach,(PPDMDRVINS pDrvIns));
371
372	/**
373	* Detach the driver from the driver above it and destroy this
374	* driver and all drivers below it.
375	*
376	* @returns VBox status code.
377	* @param pDrvIns Driver instance.
378	*/
379	DECLR3CALLBACKMEMBER(int, pfnDetachSelf,(PPDMDRVINS pDrvIns));
380
381	/**
382	* Prepare a media mount.
383	*
384	* The driver must not have anything attached to itself
385	* when calling this function as the purpose is to set up the configuration
386	* of an future attachment.
387	*
388	* @returns VBox status code
389	* @param pDrvIns Driver instance.
390	* @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have
391	* constructed a configuration which can be attached to the bottom driver.
392	* @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.
393	*/
394	DECLR3CALLBACKMEMBER(int, pfnMountPrepare,(PPDMDRVINS pDrvIns, const char pszFilename, const char pszCoreDriver));
395
396	/**
397	* Assert that the current thread is the emulation thread.
398	*
399	* @returns True if correct.
400	* @returns False if wrong.
401	* @param pDrvIns Driver instance.
402	* @param pszFile Filename of the assertion location.
403	* @param iLine Linenumber of the assertion location.
404	* @param pszFunction Function of the assertion location.
405	*/
406	DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDRVINS pDrvIns, const char pszFile, unsigned iLine, const char pszFunction));
407
408	/**
409	* Assert that the current thread is NOT the emulation thread.
410	*
411	* @returns True if correct.
412	* @returns False if wrong.
413	* @param pDrvIns Driver instance.
414	* @param pszFile Filename of the assertion location.
415	* @param iLine Linenumber of the assertion location.
416	* @param pszFunction Function of the assertion location.
417	*/
418	DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDRVINS pDrvIns, const char pszFile, unsigned iLine, const char pszFunction));
419
420	/**
421	* Set the VM error message
422	*
423	* @returns rc.
424	* @param pDrvIns Driver instance.
425	* @param rc VBox status code.
426	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
427	* @param pszFormat Error message format string.
428	* @param ... Error message arguments.
429	*/
430	DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
431
432	/**
433	* Set the VM error message
434	*
435	* @returns rc.
436	* @param pDrvIns Driver instance.
437	* @param rc VBox status code.
438	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
439	* @param pszFormat Error message format string.
440	* @param va Error message arguments.
441	*/
442	DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
443
444	/**
445	* Set the VM runtime error message
446	*
447	* @returns VBox status code.
448	* @param pDrvIns Driver instance.
449	* @param fFatal Whether it is a fatal error or not.
450	* @param pszErrorID Error ID string.
451	* @param pszFormat Error message format string.
452	* @param ... Error message arguments.
453	*/
454	DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDRVINS pDrvIns, bool fFatal, const char pszErrorID, const char pszFormat, ...));
455
456	/**
457	* Set the VM runtime error message
458	*
459	* @returns VBox status code.
460	* @param pDrvIns Driver instance.
461	* @param fFatal Whether it is a fatal error or not.
462	* @param pszErrorID Error ID string.
463	* @param pszFormat Error message format string.
464	* @param va Error message arguments.
465	*/
466	DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDRVINS pDrvIns, bool fFatal, const char pszErrorID, const char pszFormat, va_list va));
467
468	/**
469	* Create a queue.
470	*
471	* @returns VBox status code.
472	* @param pDrvIns Driver instance.
473	* @param cbItem Size a queue item.
474	* @param cItems Number of items in the queue.
475	* @param cMilliesInterval Number of milliseconds between polling the queue.
476	* If 0 then the emulation thread will be notified whenever an item arrives.
477	* @param pfnCallback The consumer function.
478	* @param ppQueue Where to store the queue handle on success.
479	* @thread The emulation thread.
480	*/
481	DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, PFNPDMQUEUEDRV pfnCallback, PPDMQUEUE *ppQueue));
482
483	/**
484	* Register a poller function.
485	* TEMPORARY HACK FOR NETWORKING! DON'T USE!
486	*
487	* @returns VBox status code.
488	* @param pDrvIns Driver instance.
489	* @param pfnPoller The callback function.
490	*/
491	DECLR3CALLBACKMEMBER(int, pfnPDMPollerRegister,(PPDMDRVINS pDrvIns, PFNPDMDRVPOLLER pfnPoller));
492
493	/**
494	* Query the virtual timer frequency.
495	*
496	* @returns Frequency in Hz.
497	* @param pDrvIns Driver instance.
498	* @thread Any thread.
499	*/
500	DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualFreq,(PPDMDRVINS pDrvIns));
501
502	/**
503	* Query the virtual time.
504	*
505	* @returns The current virtual time.
506	* @param pDrvIns Driver instance.
507	* @thread Any thread.
508	*/
509	DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualTime,(PPDMDRVINS pDrvIns));
510
511	/**
512	* Creates a timer.
513	*
514	* @returns VBox status.
515	* @param pDrvIns Driver instance.
516	* @param enmClock The clock to use on this timer.
517	* @param pfnCallback Callback function.
518	* @param pszDesc Pointer to description string which must stay around
519	* until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
520	* @param ppTimer Where to store the timer on success.
521	*/
522	DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDRVINS pDrvIns, TMCLOCK enmClock, PFNTMTIMERDRV pfnCallback, const char *pszDesc, PPTMTIMERR3 ppTimer));
523
524	/**
525	* Register a save state data unit.
526	*
527	* @returns VBox status.
528	* @param pDrvIns Driver instance.
529	* @param pszName Data unit name.
530	* @param u32Instance The instance identifier of the data unit.
531	* This must together with the name be unique.
532	* @param u32Version Data layout version number.
533	* @param cbGuess The approximate amount of data in the unit.
534	* Only for progress indicators.
535	* @param pfnSavePrep Prepare save callback, optional.
536	* @param pfnSaveExec Execute save callback, optional.
537	* @param pfnSaveDone Done save callback, optional.
538	* @param pfnLoadPrep Prepare load callback, optional.
539	* @param pfnLoadExec Execute load callback, optional.
540	* @param pfnLoadDone Done load callback, optional.
541	*/
542	DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
543	PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
544	PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone));
545
546	/**
547	* Deregister a save state data unit.
548	*
549	* @returns VBox status.
550	* @param pDrvIns Driver instance.
551	* @param pszName Data unit name.
552	* @param u32Instance The instance identifier of the data unit.
553	* This must together with the name be unique.
554	*/
555	DECLR3CALLBACKMEMBER(int, pfnSSMDeregister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance));
556
557	/**
558	* Registers a statistics sample if statistics are enabled.
559	*
560	* @param pDrvIns Driver instance.
561	* @param pvSample Pointer to the sample.
562	* @param enmType Sample type. This indicates what pvSample is pointing at.
563	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
564	* Further nesting is possible.
565	* @param enmUnit Sample unit.
566	* @param pszDesc Sample description.
567	*/
568	DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDRVINS pDrvIns, void pvSample, STAMTYPE enmType, const char pszName,
569	STAMUNIT enmUnit, const char *pszDesc));
570
571	/**
572	* Same as pfnSTAMRegister except that the name is specified in a
573	* RTStrPrintf like fashion.
574	*
575	* @returns VBox status.
576	* @param pDrvIns Driver instance.
577	* @param pvSample Pointer to the sample.
578	* @param enmType Sample type. This indicates what pvSample is pointing at.
579	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
580	* @param enmUnit Sample unit.
581	* @param pszDesc Sample description.
582	* @param pszName The sample name format string.
583	* @param ... Arguments to the format string.
584	*/
585	DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
586	STAMUNIT enmUnit, const char pszDesc, const char pszName, ...));
587
588	/**
589	* Same as pfnSTAMRegister except that the name is specified in a
590	* RTStrPrintfV like fashion.
591	*
592	* @returns VBox status.
593	* @param pDrvIns Driver instance.
594	* @param pvSample Pointer to the sample.
595	* @param enmType Sample type. This indicates what pvSample is pointing at.
596	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
597	* @param enmUnit Sample unit.
598	* @param pszDesc Sample description.
599	* @param pszName The sample name format string.
600	* @param args Arguments to the format string.
601	*/
602	DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
603	STAMUNIT enmUnit, const char pszDesc, const char pszName, va_list args));
604
605	/**
606	* Calls the HC R0 VMM entry point, in a safer but slower manner than SUPCallVMMR0.
607	*
608	* When entering using this call the R0 components can call into the host kernel
609	* (i.e. use the SUPR0 and RT APIs).
610	*
611	* See VMMR0Entry() for more details.
612	*
613	* @returns error code specific to uFunction.
614	* @param pDrvIns The driver instance.
615	* @param uOperation Operation to execute.
616	* This is limited to services.
617	* @param pvArg Pointer to argument structure or if cbArg is 0 just an value.
618	* @param cbArg The size of the argument. This is used to copy whatever the argument
619	* points at into a kernel buffer to avoid problems like the user page
620	* being invalidated while we're executing the call.
621	*/
622	DECLR3CALLBACKMEMBER(int, pfnSUPCallVMMR0Ex,(PPDMDRVINS pDrvIns, unsigned uOperation, void *pvArg, unsigned cbArg));
623
624	/**
625	* Registers a USB HUB.
626	*
627	* @returns VBox status code.
628	* @param pDrvIns The driver instance.
629	* @param fVersions Indicates the kinds of USB devices that can be attached to this HUB.
630	* @param cPorts The number of ports.
631	* @param pUsbHubReg The hub callback structure that PDMUsb uses to interact with it.
632	* @param ppUsbHubHlp The helper callback structure that the hub uses to talk to PDMUsb.
633	*
634	* @thread EMT.
635	*/
636	DECLR3CALLBACKMEMBER(int, pfnUSBRegisterHub,(PPDMDRVINS pDrvIns, uint32_t fVersions, uint32_t cPorts, PCPDMUSBHUBREG pUsbHubReg, PPCPDMUSBHUBHLP ppUsbHubHlp));
637
638	/**
639	* Creates a PDM thread.
640	*
641	* This differs from the RTThreadCreate() API in that PDM takes care of suspending,
642	* resuming, and destroying the thread as the VM state changes.
643	*
644	* @returns VBox status code.
645	* @param pDrvIns The driver instance.
646	* @param ppThread Where to store the thread 'handle'.
647	* @param pvUser The user argument to the thread function.
648	* @param pfnThread The thread function.
649	* @param pfnWakeup The wakup callback. This is called on the EMT thread when
650	* a state change is pending.
651	* @param cbStack See RTThreadCreate.
652	* @param enmType See RTThreadCreate.
653	* @param pszName See RTThreadCreate.
654	*/
655	DECLR3CALLBACKMEMBER(int, pfnPDMThreadCreate,(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
656	PFNPDMTHREADWAKEUPDRV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
657	#ifdef VBOX_WITH_PDM_ASYNC_COMPLETION
658	/**
659	* Creates a async completion template for a driver instance.
660	*
661	* The template is used when creating new completion tasks.
662	*
663	* @returns VBox status code.
664	* @param pDrvIns The driver instance.
665	* @param ppTemplate Where to store the template pointer on success.
666	* @param pfnCompleted The completion callback routine.
667	* @param pszDesc Description.
668	*/
669	DECLR3CALLBACKMEMBER(int, pfnPDMAsyncCompletionTemplateCreate,(PPDMDRVINS pDrvIns, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate,
670	PFNPDMASYNCCOMPLETEDRV pfnCompleted, const char *pszDesc));
671	#endif
672
673	/** Just a safety precaution. */
674	uint32_t u32TheEnd;
675	} PDMDRVHLP;
676	/** Pointer PDM Driver API. */
677	typedef PDMDRVHLP *PPDMDRVHLP;
678	/** Pointer const PDM Driver API. */
679	typedef const PDMDRVHLP *PCPDMDRVHLP;
680
681	/** Current DRVHLP version number. */
682	#define PDM_DRVHLP_VERSION 0x90020000
683
684
685
686	/**
687	* PDM Driver Instance.
688	*/
689	typedef struct PDMDRVINS
690	{
691	/** Structure version. PDM_DRVINS_VERSION defines the current version. */
692	uint32_t u32Version;
693
694	/** Internal data. */
695	union
696	{
697	#ifdef PDMDRVINSINT_DECLARED
698	PDMDRVINSINT s;
699	#endif
700	uint8_t padding[HC_ARCH_BITS == 32 ? 32 : 64];
701	} Internal;
702
703	/** Pointer the PDM Driver API. */
704	R3PTRTYPE(PCPDMDRVHLP) pDrvHlp;
705	/** Pointer to driver registration structure. */
706	R3PTRTYPE(PCPDMDRVREG) pDrvReg;
707	/** Configuration handle. */
708	R3PTRTYPE(PCFGMNODE) pCfgHandle;
709	/** Driver instance number. */
710	RTUINT iInstance;
711	/** Pointer to the base interface of the device/driver instance above. */
712	R3PTRTYPE(PPDMIBASE) pUpBase;
713	/** Pointer to the base interface of the driver instance below. */
714	R3PTRTYPE(PPDMIBASE) pDownBase;
715	/** The base interface of the driver.
716	* The driver constructor initializes this. */
717	PDMIBASE IBase;
718	/* padding to make achInstanceData aligned at 16 byte boundrary. */
719	uint32_t au32Padding[HC_ARCH_BITS == 32 ? 3 : 1];
720	/** Pointer to driver instance data. */
721	R3PTRTYPE(void *) pvInstanceData;
722	/** Driver instance data. The size of this area is defined
723	* in the PDMDRVREG::cbInstanceData field. */
724	char achInstanceData[4];
725	} PDMDRVINS;
726
727	/** Current DRVREG version number. */
728	#define PDM_DRVINS_VERSION 0xa0010000
729
730	/** Converts a pointer to the PDMDRVINS::IBase to a pointer to PDMDRVINS. */
731	#define PDMIBASE_2_PDMDRV(pInterface) ( (PPDMDRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDRVINS, IBase)) )
732
733	/**
734	* @copydoc PDMDRVHLP::pfnVMSetError
735	*/
736	DECLINLINE(int) PDMDrvHlpVMSetError(PPDMDRVINS pDrvIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
737	{
738	va_list va;
739	va_start(va, pszFormat);
740	pDrvIns->pDrvHlp->pfnVMSetErrorV(pDrvIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
741	va_end(va);
742	return rc;
743	}
744
745	/** @def PDMDRV_SET_ERROR
746	* Set the VM error. See PDMDrvHlpVMSetError() for printf like message formatting.
747	*/
748	#define PDMDRV_SET_ERROR(pDrvIns, rc, pszError) \
749	PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, "%s", pszError)
750
751	/**
752	* @copydoc PDMDRVHLP::pfnVMSetRuntimeError
753	*/
754	DECLINLINE(int) PDMDrvHlpVMSetRuntimeError(PPDMDRVINS pDrvIns, bool fFatal, const char pszErrorID, const char pszFormat, ...)
755	{
756	va_list va;
757	int rc;
758	va_start(va, pszFormat);
759	rc = pDrvIns->pDrvHlp->pfnVMSetRuntimeErrorV(pDrvIns, fFatal, pszErrorID, pszFormat, va);
760	va_end(va);
761	return rc;
762	}
763
764	/** @def PDMDRV_SET_RUNTIME_ERROR
765	* Set the VM runtime error. See PDMDrvHlpVMSetRuntimeError() for printf like message formatting.
766	*/
767	#define PDMDRV_SET_RUNTIME_ERROR(pDrvIns, fFatal, pszErrorID, pszError) \
768	PDMDrvHlpVMSetRuntimeError(pDrvIns, fFatal, pszErrorID, "%s", pszError)
769
770	#endif /* IN_RING3 */
771
772
773	/** @def PDMDRV_ASSERT_EMT
774	* Assert that the current thread is the emulation thread.
775	*/
776	#ifdef VBOX_STRICT
777	# define PDMDRV_ASSERT_EMT(pDrvIns) pDrvIns->pDrvHlp->pfnAssertEMT(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
778	#else
779	# define PDMDRV_ASSERT_EMT(pDrvIns) do { } while (0)
780	#endif
781
782	/** @def PDMDRV_ASSERT_OTHER
783	* Assert that the current thread is NOT the emulation thread.
784	*/
785	#ifdef VBOX_STRICT
786	# define PDMDRV_ASSERT_OTHER(pDrvIns) pDrvIns->pDrvHlp->pfnAssertOther(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
787	#else
788	# define PDMDRV_ASSERT_OTHER(pDrvIns) do { } while (0)
789	#endif
790
791
792	#ifdef IN_RING3
793	/**
794	* @copydoc PDMDRVHLP::pfnSTAMRegister
795	*/
796	DECLINLINE(void) PDMDrvHlpSTAMRegister(PPDMDRVINS pDrvIns, void pvSample, STAMTYPE enmType, const char pszName, STAMUNIT enmUnit, const char *pszDesc)
797	{
798	pDrvIns->pDrvHlp->pfnSTAMRegister(pDrvIns, pvSample, enmType, pszName, enmUnit, pszDesc);
799	}
800
801	/**
802	* @copydoc PDMDRVHLP::pfnSTAMRegisterF
803	*/
804	DECLINLINE(void) PDMDrvHlpSTAMRegisterF(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
805	const char pszDesc, const char pszName, ...)
806	{
807	va_list va;
808	va_start(va, pszName);
809	pDrvIns->pDrvHlp->pfnSTAMRegisterV(pDrvIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
810	va_end(va);
811	}
812
813	/**
814	* @copydoc PDMDRVHLP::pfnUSBRegisterHub
815	*/
816	DECLINLINE(int) PDMDrvHlpUSBRegisterHub(PPDMDRVINS pDrvIns, uint32_t fVersions, uint32_t cPorts, PCPDMUSBHUBREG pUsbHubReg, PPCPDMUSBHUBHLP ppUsbHubHlp)
817	{
818	return pDrvIns->pDrvHlp->pfnUSBRegisterHub(pDrvIns, fVersions, cPorts, pUsbHubReg, ppUsbHubHlp);
819	}
820
821	/**
822	* @copydoc PDMDRVHLP::pfnPDMThreadCreate
823	*/
824	DECLINLINE(int) PDMDrvHlpPDMThreadCreate(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
825	PFNPDMTHREADWAKEUPDRV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
826	{
827	return pDrvIns->pDrvHlp->pfnPDMThreadCreate(pDrvIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
828	}
829
830	#ifdef VBOX_WITH_PDM_ASYNC_COMPLETION
831	/**
832	* @copydoc PDMDRVHLP::pfnPDMAsyncCompletionTemplateCreate
833	*/
834	DECLINLINE(int) PDMDrvHlpPDMAsyncCompletionTemplateCreate(PPDMDRVINS pDrvIns, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate,
835	PFNPDMASYNCCOMPLETEDRV pfnCompleted, const char *pszDesc)
836	{
837	return pDrvIns->pDrvHlp->pfnPDMAsyncCompletionTemplateCreate(pDrvIns, ppTemplate, pfnCompleted, pszDesc);
838	}
839	#endif
840
841	#endif /* IN_RING3 */
842
843
844
845	/** Pointer to callbacks provided to the VBoxDriverRegister() call. */
846	typedef struct PDMDRVREGCB *PPDMDRVREGCB;
847	/** Pointer to const callbacks provided to the VBoxDriverRegister() call. */
848	typedef const struct PDMDRVREGCB *PCPDMDRVREGCB;
849
850	/**
851	* Callbacks for VBoxDriverRegister().
852	*/
853	typedef struct PDMDRVREGCB
854	{
855	/** Interface version.
856	* This is set to PDM_DRVREG_CB_VERSION. */
857	uint32_t u32Version;
858
859	/**
860	* Registers a driver with the current VM instance.
861	*
862	* @returns VBox status code.
863	* @param pCallbacks Pointer to the callback table.
864	* @param pDrvReg Pointer to the driver registration record.
865	* This data must be permanent and readonly.
866	*/
867	DECLR3CALLBACKMEMBER(int, pfnRegister,(PCPDMDRVREGCB pCallbacks, PCPDMDRVREG pDrvReg));
868	} PDMDRVREGCB;
869
870	/** Current version of the PDMDRVREGCB structure. */
871	#define PDM_DRVREG_CB_VERSION 0xb0010000
872
873
874	/**
875	* The VBoxDriverRegister callback function.
876	*
877	* PDM will invoke this function after loading a driver module and letting
878	* the module decide which drivers to register and how to handle conflicts.
879	*
880	* @returns VBox status code.
881	* @param pCallbacks Pointer to the callback table.
882	* @param u32Version VBox version number.
883	*/
884	typedef DECLCALLBACK(int) FNPDMVBOXDRIVERSREGISTER(PCPDMDRVREGCB pCallbacks, uint32_t u32Version);
885
886	/**
887	* Register external drivers
888	*
889	* @returns VBox status code.
890	* @param pVM The VM to operate on.
891	* @param pfnCallback Driver registration callback
892	*/
893	PDMR3DECL(int) PDMR3RegisterDrivers(PVM pVM, FNPDMVBOXDRIVERSREGISTER pfnCallback);
894
895	/** @} */
896
897	__END_DECLS
898
899	#endif

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

source: vbox/trunk/include/VBox/pdmdrv.h@ 7581

Download in other formats: