pdmdrv.h@ 21644

Last change on this file since 21644 was 21363, checked in by vboxsync, 15 years ago
PDMQueue&users-thereof: Named the queues and added statistics.
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 36.0 KB

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

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

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

Download in other formats: