← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/virtualbox-ose/gutsy

« back to all changes in this revision

Viewing changes to include/VBox/pdmdrv.h

  • Committer: Bazaar Package Importer
  • Author(s): Steve Kowalik
  • Date: 2007-09-08 16:44:58 UTC
  • Revision ID: james.westby@ubuntu.com-20070908164458-wao29470vqtr8ksy
Tags: upstream-1.5.0-dfsg2
Import upstream version 1.5.0-dfsg2

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/VBox/pdmdrv.h
 
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