pdmdrv.h@ 3880

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

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

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

Download in other formats: