pdmdrv.h@ 4693

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

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

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

Download in other formats: