VirtualBox

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

Last change on this file since 8006 was 7768, checked in by vboxsync, 16 years ago

Added a VMState dev/usb/drvhlp.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 33.4 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 */
63typedef DECLCALLBACK(int) FNPDMDRVCONSTRUCT(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle);
64/** Pointer to a FNPDMDRVCONSTRUCT() function. */
65typedef 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 */
75typedef DECLCALLBACK(void) FNPDMDRVDESTRUCT(PPDMDRVINS pDrvIns);
76/** Pointer to a FNPDMDRVDESTRUCT() function. */
77typedef 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 */
95typedef 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. */
99typedef FNPDMDRVIOCTL *PFNPDMDRVIOCTL;
100
101/**
102 * Power On notification.
103 *
104 * @param pDrvIns The driver instance data.
105 */
106typedef DECLCALLBACK(void) FNPDMDRVPOWERON(PPDMDRVINS pDrvIns);
107/** Pointer to a FNPDMDRVPOWERON() function. */
108typedef FNPDMDRVPOWERON *PFNPDMDRVPOWERON;
109
110/**
111 * Reset notification.
112 *
113 * @returns VBox status.
114 * @param pDrvIns The driver instance data.
115 */
116typedef DECLCALLBACK(void) FNPDMDRVRESET(PPDMDRVINS pDrvIns);
117/** Pointer to a FNPDMDRVRESET() function. */
118typedef FNPDMDRVRESET *PFNPDMDRVRESET;
119
120/**
121 * Suspend notification.
122 *
123 * @returns VBox status.
124 * @param pDrvIns The driver instance data.
125 */
126typedef DECLCALLBACK(void) FNPDMDRVSUSPEND(PPDMDRVINS pDrvIns);
127/** Pointer to a FNPDMDRVSUSPEND() function. */
128typedef FNPDMDRVSUSPEND *PFNPDMDRVSUSPEND;
129
130/**
131 * Resume notification.
132 *
133 * @returns VBox status.
134 * @param pDrvIns The driver instance data.
135 */
136typedef DECLCALLBACK(void) FNPDMDRVRESUME(PPDMDRVINS pDrvIns);
137/** Pointer to a FNPDMDRVRESUME() function. */
138typedef FNPDMDRVRESUME *PFNPDMDRVRESUME;
139
140/**
141 * Power Off notification.
142 *
143 * @param pDrvIns The driver instance data.
144 */
145typedef DECLCALLBACK(void) FNPDMDRVPOWEROFF(PPDMDRVINS pDrvIns);
146/** Pointer to a FNPDMDRVPOWEROFF() function. */
147typedef 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 */
159typedef DECLCALLBACK(void) FNPDMDRVDETACH(PPDMDRVINS pDrvIns);
160/** Pointer to a FNPDMDRVDETACH() function. */
161typedef 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 */
170typedef 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. */
210typedef PDMDRVREG *PPDMDRVREG;
211/** Const pointer to a PDM Driver Structure. */
212typedef 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 */
272typedef 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. */
307typedef 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 */
317typedef 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. */
326typedef PDMUSBHUBHLP *PPDMUSBHUBHLP;
327/** Pointer to const PCI helpers. */
328typedef const PDMUSBHUBHLP *PCPDMUSBHUBHLP;
329/** Pointer to const PCI helpers pointer. */
330typedef 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 */
342typedef DECLCALLBACK(void) FNPDMDRVPOLLER(PPDMDRVINS pDrvIns);
343/** Pointer to a FNPDMDRVPOLLER function. */
344typedef FNPDMDRVPOLLER *PFNPDMDRVPOLLER;
345
346#ifdef IN_RING3
347/**
348 * PDM Driver API.
349 */
350typedef 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
658 /**
659 * Gets the VM state.
660 *
661 * @returns VM state.
662 * @param pDrvIns The driver instance.
663 * @thread Any thread (just keep in mind that it's volatile info).
664 */
665 DECLR3CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDRVINS pDrvIns));
666
667#ifdef VBOX_WITH_PDM_ASYNC_COMPLETION
668 /**
669 * Creates a async completion template for a driver instance.
670 *
671 * The template is used when creating new completion tasks.
672 *
673 * @returns VBox status code.
674 * @param pDrvIns The driver instance.
675 * @param ppTemplate Where to store the template pointer on success.
676 * @param pfnCompleted The completion callback routine.
677 * @param pszDesc Description.
678 */
679 DECLR3CALLBACKMEMBER(int, pfnPDMAsyncCompletionTemplateCreate,(PPDMDRVINS pDrvIns, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate,
680 PFNPDMASYNCCOMPLETEDRV pfnCompleted, const char *pszDesc));
681#endif
682
683 /** Just a safety precaution. */
684 uint32_t u32TheEnd;
685} PDMDRVHLP;
686/** Pointer PDM Driver API. */
687typedef PDMDRVHLP *PPDMDRVHLP;
688/** Pointer const PDM Driver API. */
689typedef const PDMDRVHLP *PCPDMDRVHLP;
690
691/** Current DRVHLP version number. */
692#define PDM_DRVHLP_VERSION 0x90020001
693
694
695
696/**
697 * PDM Driver Instance.
698 */
699typedef struct PDMDRVINS
700{
701 /** Structure version. PDM_DRVINS_VERSION defines the current version. */
702 uint32_t u32Version;
703
704 /** Internal data. */
705 union
706 {
707#ifdef PDMDRVINSINT_DECLARED
708 PDMDRVINSINT s;
709#endif
710 uint8_t padding[HC_ARCH_BITS == 32 ? 32 : 64];
711 } Internal;
712
713 /** Pointer the PDM Driver API. */
714 R3PTRTYPE(PCPDMDRVHLP) pDrvHlp;
715 /** Pointer to driver registration structure. */
716 R3PTRTYPE(PCPDMDRVREG) pDrvReg;
717 /** Configuration handle. */
718 R3PTRTYPE(PCFGMNODE) pCfgHandle;
719 /** Driver instance number. */
720 RTUINT iInstance;
721 /** Pointer to the base interface of the device/driver instance above. */
722 R3PTRTYPE(PPDMIBASE) pUpBase;
723 /** Pointer to the base interface of the driver instance below. */
724 R3PTRTYPE(PPDMIBASE) pDownBase;
725 /** The base interface of the driver.
726 * The driver constructor initializes this. */
727 PDMIBASE IBase;
728 /* padding to make achInstanceData aligned at 16 byte boundrary. */
729 uint32_t au32Padding[HC_ARCH_BITS == 32 ? 3 : 1];
730 /** Pointer to driver instance data. */
731 R3PTRTYPE(void *) pvInstanceData;
732 /** Driver instance data. The size of this area is defined
733 * in the PDMDRVREG::cbInstanceData field. */
734 char achInstanceData[4];
735} PDMDRVINS;
736
737/** Current DRVREG version number. */
738#define PDM_DRVINS_VERSION 0xa0010000
739
740/** Converts a pointer to the PDMDRVINS::IBase to a pointer to PDMDRVINS. */
741#define PDMIBASE_2_PDMDRV(pInterface) ( (PPDMDRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDRVINS, IBase)) )
742
743/**
744 * @copydoc PDMDRVHLP::pfnVMSetError
745 */
746DECLINLINE(int) PDMDrvHlpVMSetError(PPDMDRVINS pDrvIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
747{
748 va_list va;
749 va_start(va, pszFormat);
750 pDrvIns->pDrvHlp->pfnVMSetErrorV(pDrvIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
751 va_end(va);
752 return rc;
753}
754
755/** @def PDMDRV_SET_ERROR
756 * Set the VM error. See PDMDrvHlpVMSetError() for printf like message formatting.
757 */
758#define PDMDRV_SET_ERROR(pDrvIns, rc, pszError) \
759 PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, "%s", pszError)
760
761/**
762 * @copydoc PDMDRVHLP::pfnVMSetRuntimeError
763 */
764DECLINLINE(int) PDMDrvHlpVMSetRuntimeError(PPDMDRVINS pDrvIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...)
765{
766 va_list va;
767 int rc;
768 va_start(va, pszFormat);
769 rc = pDrvIns->pDrvHlp->pfnVMSetRuntimeErrorV(pDrvIns, fFatal, pszErrorID, pszFormat, va);
770 va_end(va);
771 return rc;
772}
773
774/** @def PDMDRV_SET_RUNTIME_ERROR
775 * Set the VM runtime error. See PDMDrvHlpVMSetRuntimeError() for printf like message formatting.
776 */
777#define PDMDRV_SET_RUNTIME_ERROR(pDrvIns, fFatal, pszErrorID, pszError) \
778 PDMDrvHlpVMSetRuntimeError(pDrvIns, fFatal, pszErrorID, "%s", pszError)
779
780#endif /* IN_RING3 */
781
782
783/** @def PDMDRV_ASSERT_EMT
784 * Assert that the current thread is the emulation thread.
785 */
786#ifdef VBOX_STRICT
787# define PDMDRV_ASSERT_EMT(pDrvIns) pDrvIns->pDrvHlp->pfnAssertEMT(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
788#else
789# define PDMDRV_ASSERT_EMT(pDrvIns) do { } while (0)
790#endif
791
792/** @def PDMDRV_ASSERT_OTHER
793 * Assert that the current thread is NOT the emulation thread.
794 */
795#ifdef VBOX_STRICT
796# define PDMDRV_ASSERT_OTHER(pDrvIns) pDrvIns->pDrvHlp->pfnAssertOther(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
797#else
798# define PDMDRV_ASSERT_OTHER(pDrvIns) do { } while (0)
799#endif
800
801
802#ifdef IN_RING3
803/**
804 * @copydoc PDMDRVHLP::pfnSTAMRegister
805 */
806DECLINLINE(void) PDMDrvHlpSTAMRegister(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
807{
808 pDrvIns->pDrvHlp->pfnSTAMRegister(pDrvIns, pvSample, enmType, pszName, enmUnit, pszDesc);
809}
810
811/**
812 * @copydoc PDMDRVHLP::pfnSTAMRegisterF
813 */
814DECLINLINE(void) PDMDrvHlpSTAMRegisterF(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
815 const char *pszDesc, const char *pszName, ...)
816{
817 va_list va;
818 va_start(va, pszName);
819 pDrvIns->pDrvHlp->pfnSTAMRegisterV(pDrvIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
820 va_end(va);
821}
822
823/**
824 * @copydoc PDMDRVHLP::pfnUSBRegisterHub
825 */
826DECLINLINE(int) PDMDrvHlpUSBRegisterHub(PPDMDRVINS pDrvIns, uint32_t fVersions, uint32_t cPorts, PCPDMUSBHUBREG pUsbHubReg, PPCPDMUSBHUBHLP ppUsbHubHlp)
827{
828 return pDrvIns->pDrvHlp->pfnUSBRegisterHub(pDrvIns, fVersions, cPorts, pUsbHubReg, ppUsbHubHlp);
829}
830
831/**
832 * @copydoc PDMDRVHLP::pfnPDMThreadCreate
833 */
834DECLINLINE(int) PDMDrvHlpPDMThreadCreate(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
835 PFNPDMTHREADWAKEUPDRV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
836{
837 return pDrvIns->pDrvHlp->pfnPDMThreadCreate(pDrvIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
838}
839
840/**
841 * @copydoc PDMDRVHLP::pfnVMState
842 */
843DECLINLINE(VMSTATE) PDMDrvHlpVMState(PPDMDRVINS pDrvIns)
844{
845 return pDrvIns->pDrvHlp->pfnVMState(pDrvIns);
846}
847
848#ifdef VBOX_WITH_PDM_ASYNC_COMPLETION
849/**
850 * @copydoc PDMDRVHLP::pfnPDMAsyncCompletionTemplateCreate
851 */
852DECLINLINE(int) PDMDrvHlpPDMAsyncCompletionTemplateCreate(PPDMDRVINS pDrvIns, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate,
853 PFNPDMASYNCCOMPLETEDRV pfnCompleted, const char *pszDesc)
854{
855 return pDrvIns->pDrvHlp->pfnPDMAsyncCompletionTemplateCreate(pDrvIns, ppTemplate, pfnCompleted, pszDesc);
856}
857#endif
858
859#endif /* IN_RING3 */
860
861
862
863/** Pointer to callbacks provided to the VBoxDriverRegister() call. */
864typedef struct PDMDRVREGCB *PPDMDRVREGCB;
865/** Pointer to const callbacks provided to the VBoxDriverRegister() call. */
866typedef const struct PDMDRVREGCB *PCPDMDRVREGCB;
867
868/**
869 * Callbacks for VBoxDriverRegister().
870 */
871typedef struct PDMDRVREGCB
872{
873 /** Interface version.
874 * This is set to PDM_DRVREG_CB_VERSION. */
875 uint32_t u32Version;
876
877 /**
878 * Registers a driver with the current VM instance.
879 *
880 * @returns VBox status code.
881 * @param pCallbacks Pointer to the callback table.
882 * @param pDrvReg Pointer to the driver registration record.
883 * This data must be permanent and readonly.
884 */
885 DECLR3CALLBACKMEMBER(int, pfnRegister,(PCPDMDRVREGCB pCallbacks, PCPDMDRVREG pDrvReg));
886} PDMDRVREGCB;
887
888/** Current version of the PDMDRVREGCB structure. */
889#define PDM_DRVREG_CB_VERSION 0xb0010000
890
891
892/**
893 * The VBoxDriverRegister callback function.
894 *
895 * PDM will invoke this function after loading a driver module and letting
896 * the module decide which drivers to register and how to handle conflicts.
897 *
898 * @returns VBox status code.
899 * @param pCallbacks Pointer to the callback table.
900 * @param u32Version VBox version number.
901 */
902typedef DECLCALLBACK(int) FNPDMVBOXDRIVERSREGISTER(PCPDMDRVREGCB pCallbacks, uint32_t u32Version);
903
904/**
905 * Register external drivers
906 *
907 * @returns VBox status code.
908 * @param pVM The VM to operate on.
909 * @param pfnCallback Driver registration callback
910 */
911PDMR3DECL(int) PDMR3RegisterDrivers(PVM pVM, FNPDMVBOXDRIVERSREGISTER pfnCallback);
912
913/** @} */
914
915__END_DECLS
916
917#endif
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use