VirtualBox

source: vbox/trunk/include/VBox/pdm.h@ 3234

Last change on this file since 3234 was 3159, checked in by vboxsync, 17 years ago

Increased the devhlp version since somebody might be using it externally. (don't care too much about the drvhlp version yet, so don't increase it.)

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 255.2 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager.
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#define __VBox_pdm_h__
23
24#include <VBox/cdefs.h>
25#include <VBox/types.h>
26#include <VBox/iom.h>
27#include <VBox/ssm.h>
28#include <VBox/cfgm.h>
29#include <VBox/dbgf.h>
30#include <VBox/err.h>
31#include <VBox/pci.h>
32
33#include <iprt/critsect.h>
34#include <iprt/stdarg.h>
35
36
37__BEGIN_DECLS
38
39/** @defgroup grp_pdm The Pluggable Device Manager API
40 * @{
41 */
42
43/** Source position.
44 * @deprecated Use RT_SRC_POS */
45#define PDM_SRC_POS RT_SRC_POS
46
47/** Source position declaration.
48 * @deprecated Use RT_SRC_POS_DECL */
49#define PDM_SRC_POS_DECL RT_SRC_POS_DECL
50
51/** Source position arguments.
52 * @deprecated Use RT_SRC_POS_ARGS */
53#define PDM_SRC_POS_ARGS RT_SRC_POS_ARGS
54
55
56/** @defgroup grp_pdm_queue The PDM Queue
57 * @ingroup grp_pdm
58 * @{
59 */
60
61/** Pointer to a PDM queue. Also called PDM queue handle. */
62typedef struct PDMQUEUE *PPDMQUEUE;
63
64/** Pointer to a PDM queue item core. */
65typedef struct PDMQUEUEITEMCORE *PPDMQUEUEITEMCORE;
66
67/**
68 * PDM queue item core.
69 */
70typedef struct PDMQUEUEITEMCORE
71{
72 /** Pointer to the next item in the pending list - HC Pointer. */
73 HCPTRTYPE(PPDMQUEUEITEMCORE) pNextHC;
74 /** Pointer to the next item in the pending list - GC Pointer. */
75 GCPTRTYPE(PPDMQUEUEITEMCORE) pNextGC;
76#if HC_ARCH_BITS == 64 && GC_ARCH_BITS == 32
77 uint32_t Alignment0;
78#endif
79} PDMQUEUEITEMCORE;
80
81
82/**
83 * Queue consumer callback for devices.
84 *
85 * @returns Success indicator.
86 * If false the item will not be removed and the flushing will stop.
87 * @param pDevIns The device instance.
88 * @param pItem The item to consume. Upon return this item will be freed.
89 */
90typedef DECLCALLBACK(bool) FNPDMQUEUEDEV(PPDMDEVINS pDevIns, PPDMQUEUEITEMCORE pItem);
91/** Pointer to a FNPDMQUEUEDEV(). */
92typedef FNPDMQUEUEDEV *PFNPDMQUEUEDEV;
93
94/**
95 * Queue consumer callback for drivers.
96 *
97 * @returns Success indicator.
98 * If false the item will not be removed and the flushing will stop.
99 * @param pDrvIns The driver instance.
100 * @param pItem The item to consume. Upon return this item will be freed.
101 */
102typedef DECLCALLBACK(bool) FNPDMQUEUEDRV(PPDMDRVINS pDrvIns, PPDMQUEUEITEMCORE pItem);
103/** Pointer to a FNPDMQUEUEDRV(). */
104typedef FNPDMQUEUEDRV *PFNPDMQUEUEDRV;
105
106/**
107 * Queue consumer callback for internal component.
108 *
109 * @returns Success indicator.
110 * If false the item will not be removed and the flushing will stop.
111 * @param pVM The VM handle.
112 * @param pItem The item to consume. Upon return this item will be freed.
113 */
114typedef DECLCALLBACK(bool) FNPDMQUEUEINT(PVM pVM, PPDMQUEUEITEMCORE pItem);
115/** Pointer to a FNPDMQUEUEINT(). */
116typedef FNPDMQUEUEINT *PFNPDMQUEUEINT;
117
118/**
119 * Queue consumer callback for external component.
120 *
121 * @returns Success indicator.
122 * If false the item will not be removed and the flushing will stop.
123 * @param pvUser User argument.
124 * @param pItem The item to consume. Upon return this item will be freed.
125 */
126typedef DECLCALLBACK(bool) FNPDMQUEUEEXT(void *pvUser, PPDMQUEUEITEMCORE pItem);
127/** Pointer to a FNPDMQUEUEEXT(). */
128typedef FNPDMQUEUEEXT *PFNPDMQUEUEEXT;
129
130/**
131 * Create a queue with a device owner.
132 *
133 * @returns VBox status code.
134 * @param pVM VM handle.
135 * @param pDevIns Device instance.
136 * @param cbItem Size a queue item.
137 * @param cItems Number of items in the queue.
138 * @param cMilliesInterval Number of milliseconds between polling the queue.
139 * If 0 then the emulation thread will be notified whenever an item arrives.
140 * @param pfnCallback The consumer function.
141 * @param fGCEnabled Set if the queue must be usable from GC.
142 * @param ppQueue Where to store the queue handle on success.
143 * @thread Emulation thread only.
144 */
145PDMR3DECL(int) PDMR3QueueCreateDevice(PVM pVM, PPDMDEVINS pDevIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
146 PFNPDMQUEUEDEV pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue);
147
148/**
149 * Create a queue with a driver owner.
150 *
151 * @returns VBox status code.
152 * @param pVM VM handle.
153 * @param pDrvIns Driver instance.
154 * @param cbItem Size a queue item.
155 * @param cItems Number of items in the queue.
156 * @param cMilliesInterval Number of milliseconds between polling the queue.
157 * If 0 then the emulation thread will be notified whenever an item arrives.
158 * @param pfnCallback The consumer function.
159 * @param ppQueue Where to store the queue handle on success.
160 * @thread The emulation thread.
161 */
162PDMR3DECL(int) PDMR3QueueCreateDriver(PVM pVM, PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
163 PFNPDMQUEUEDRV pfnCallback, PPDMQUEUE *ppQueue);
164
165/**
166 * Create a queue with an internal owner.
167 *
168 * @returns VBox status code.
169 * @param pVM VM handle.
170 * @param cbItem Size a queue item.
171 * @param cItems Number of items in the queue.
172 * @param cMilliesInterval Number of milliseconds between polling the queue.
173 * If 0 then the emulation thread will be notified whenever an item arrives.
174 * @param pfnCallback The consumer function.
175 * @param fGCEnabled Set if the queue must be usable from GC.
176 * @param ppQueue Where to store the queue handle on success.
177 * @thread Emulation thread only.
178 */
179PDMR3DECL(int) PDMR3QueueCreateInternal(PVM pVM, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
180 PFNPDMQUEUEINT pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue);
181
182/**
183 * Create a queue with an external owner.
184 *
185 * @returns VBox status code.
186 * @param pVM VM handle.
187 * @param cbItem Size a queue item.
188 * @param cItems Number of items in the queue.
189 * @param cMilliesInterval Number of milliseconds between polling the queue.
190 * If 0 then the emulation thread will be notified whenever an item arrives.
191 * @param pfnCallback The consumer function.
192 * @param pvUser The user argument to the consumer function.
193 * @param ppQueue Where to store the queue handle on success.
194 * @thread The emulation thread.
195 */
196PDMR3DECL(int) PDMR3QueueCreateExternal(PVM pVM, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
197 PFNPDMQUEUEEXT pfnCallback, void *pvUser, PPDMQUEUE *ppQueue);
198
199/**
200 * Destroy a queue.
201 *
202 * @returns VBox status code.
203 * @param pQueue Queue to destroy.
204 * @thread The emulation thread.
205 */
206PDMR3DECL(int) PDMR3QueueDestroy(PPDMQUEUE pQueue);
207
208/**
209 * Destroy a all queues owned by the specified device.
210 *
211 * @returns VBox status code.
212 * @param pVM VM handle.
213 * @param pDevIns Device instance.
214 * @thread Emulation thread only.
215 */
216PDMR3DECL(int) PDMR3QueueDestroyDevice(PVM pVM, PPDMDEVINS pDevIns);
217
218/**
219 * Destroy a all queues owned by the specified driver.
220 *
221 * @returns VBox status code.
222 * @param pVM VM handle.
223 * @param pDrvIns Driver instance.
224 * @thread Emulation thread only.
225 */
226PDMR3DECL(int) PDMR3QueueDestroyDriver(PVM pVM, PPDMDRVINS pDrvIns);
227
228/**
229 * Flushes pending queues.
230 * This is a forced action callback.
231 *
232 * @param pVM VM handle.
233 * @thread The emulation thread.
234 */
235PDMR3DECL(void) PDMR3QueueFlushAll(PVM pVM);
236
237/**
238 * This is a worker function used by PDMQueueFlush to perform the
239 * flush in ring-3.
240 *
241 * The queue which should be flushed is pointed to by either pQueueFlushGC,
242 * pQueueFlushHC, or pQueueue. This function will flush that queue and
243 * recalc the queue FF.
244 *
245 * @param pVM The VM handle.
246 * @param pQueue The queue to flush. Only used in Ring-3.
247 */
248PDMR3DECL(void) PDMR3QueueFlushWorker(PVM pVM, PPDMQUEUE pQueue);
249
250/**
251 * Flushes a PDM queue.
252 *
253 * @param pQueue The queue handle.
254 */
255PDMDECL(void) PDMQueueFlush(PPDMQUEUE pQueue);
256
257/**
258 * Allocate an item from a queue.
259 * The allocated item must be handed on to PDMQueueInsert() after the
260 * data has been filled in.
261 *
262 * @returns Pointer to allocated queue item.
263 * @returns NULL on failure. The queue is exhausted.
264 * @param pQueue The queue handle.
265 * @thread Any thread.
266 */
267PDMDECL(PPDMQUEUEITEMCORE) PDMQueueAlloc(PPDMQUEUE pQueue);
268
269/**
270 * Queue an item.
271 * The item must have been obtained using PDMQueueAlloc(). Once the item
272 * has been passed to this function it must not be touched!
273 *
274 * @param pQueue The queue handle.
275 * @param pItem The item to insert.
276 * @thread Any thread.
277 */
278PDMDECL(void) PDMQueueInsert(PPDMQUEUE pQueue, PPDMQUEUEITEMCORE pItem);
279
280/**
281 * Queue an item.
282 * The item must have been obtained using PDMQueueAlloc(). Once the item
283 * have been passed to this function it must not be touched!
284 *
285 * @param pQueue The queue handle.
286 * @param pItem The item to insert.
287 * @param NanoMaxDelay The maximum delay before processing the queue, in nanoseconds.
288 * This applies only to GC.
289 * @thread Any thread.
290 */
291PDMDECL(void) PDMQueueInsertEx(PPDMQUEUE pQueue, PPDMQUEUEITEMCORE pItem, uint64_t NanoMaxDelay);
292
293
294/**
295 * Gets the GC pointer for the specified queue.
296 *
297 * @returns The GC address of the queue.
298 * @returns NULL if pQueue is invalid.
299 * @param pQueue The queue handle.
300 */
301PDMDECL(GCPTRTYPE(PPDMQUEUE)) PDMQueueGCPtr(PPDMQUEUE pQueue);
302
303/** @} */
304
305
306
307/** @defgroup grp_pdm_critsect The PDM Critical Section
308 * @ingroup grp_pdm
309 * @{
310 */
311
312/**
313 * A PDM critical section.
314 * Initialize using PDMDRVHLP::pfnCritSectInit().
315 */
316typedef union PDMCRITSECT
317{
318 /** Padding. */
319 uint8_t padding[HC_ARCH_BITS == 64 ? 0xb8 : 0x80];
320#ifdef PDMCRITSECTINT_DECLARED
321 /** The internal structure (not normally visible). */
322 struct PDMCRITSECTINT s;
323#endif
324} PDMCRITSECT;
325/** Pointer to a PDM critical section. */
326typedef PDMCRITSECT *PPDMCRITSECT;
327/** Pointer to a const PDM critical section. */
328typedef const PDMCRITSECT *PCPDMCRITSECT;
329
330/**
331 * Initializes a PDM critical section for internal use.
332 *
333 * The PDM critical sections are derived from the IPRT critical sections, but
334 * works in GC as well.
335 *
336 * @returns VBox status code.
337 * @param pVM The VM handle.
338 * @param pDevIns Device instance.
339 * @param pCritSect Pointer to the critical section.
340 * @param pszName The name of the critical section (for statistics).
341 */
342PDMR3DECL(int) PDMR3CritSectInit(PVM pVM, PPDMCRITSECT pCritSect, const char *pszName);
343
344/**
345 * Leaves a critical section entered with PDMCritSectEnter().
346 *
347 * @returns VINF_SUCCESS if entered successfully.
348 * @returns rcBusy when encountering a busy critical section in GC/R0.
349 * @returns VERR_SEM_DESTROYED if the critical section is dead.
350 *
351 * @param pCritSect The PDM critical section to enter.
352 * @param rcBusy The status code to return when we're in GC or R0
353 * and the section is busy.
354 */
355PDMDECL(int) PDMCritSectEnter(PPDMCRITSECT pCritSect, int rcBusy);
356
357/**
358 * Leaves a critical section entered with PDMCritSectEnter().
359 *
360 * @param pCritSect The PDM critical section to leave.
361 */
362PDMDECL(void) PDMCritSectLeave(PPDMCRITSECT pCritSect);
363
364/**
365 * Checks the caller is the owner of the critical section.
366 *
367 * @returns true if owner.
368 * @returns false if not owner.
369 * @param pCritSect The critical section.
370 */
371PDMDECL(bool) PDMCritSectIsOwner(PCPDMCRITSECT pCritSect);
372
373/**
374 * Try enter a critical section.
375 *
376 * @returns VINF_SUCCESS on success.
377 * @returns VERR_SEM_BUSY if the critsect was owned.
378 * @returns VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
379 * @returns VERR_SEM_DESTROYED if RTCritSectDelete was called while waiting.
380 * @param pCritSect The critical section.
381 */
382PDMR3DECL(int) PDMR3CritSectTryEnter(PPDMCRITSECT pCritSect);
383
384/**
385 * Schedule a event semaphore for signalling upon critsect exit.
386 *
387 * @returns VINF_SUCCESS on success.
388 * @returns VERR_TOO_MANY_SEMAPHORES if an event was already scheduled.
389 * @returns VERR_NOT_OWNER if we're not the critsect owner.
390 * @returns VERR_SEM_DESTROYED if RTCritSectDelete was called while waiting.
391 * @param pCritSect The critical section.
392 * @param EventToSignal The semapore that should be signalled.
393 */
394PDMR3DECL(int) PDMR3CritSectScheduleExitEvent(PPDMCRITSECT pCritSect, RTSEMEVENT EventToSignal);
395
396/**
397 * Deletes the critical section.
398 *
399 * @returns VBox status code.
400 * @param pCritSect The PDM critical section to destroy.
401 */
402PDMR3DECL(int) PDMR3CritSectDelete(PPDMCRITSECT pCritSect);
403
404/**
405 * Deletes all remaining critical sections.
406 *
407 * This is called at the end of the termination process.
408 *
409 * @returns VBox status.
410 * First error code, rest is lost.
411 * @param pVM The VM handle.
412 * @remark Don't confuse this with PDMR3CritSectDelete.
413 */
414PDMDECL(int) PDMR3CritSectTerm(PVM pVM);
415
416/**
417 * Process the critical sections queued for ring-3 'leave'.
418 *
419 * @param pVM The VM handle.
420 */
421PDMR3DECL(void) PDMR3CritSectFF(PVM pVM);
422
423/** @} */
424
425
426
427/** @defgroup grp_pdm_interfaces Interfaces
428 * @ingroup grp_pdm
429 * @{
430 */
431
432/**
433 * Driver interface identficators.
434 */
435typedef enum PDMINTERFACE
436{
437 /** PDMIBASE - The interface everyone supports. */
438 PDMINTERFACE_BASE = 1,
439 /** PDMIMOUSEPORT - The mouse port interface. (Down) Coupled with PDMINTERFACE_MOUSE_CONNECTOR. */
440 PDMINTERFACE_MOUSE_PORT,
441 /** PDMIMOUSECONNECTOR - The mouse connector interface. (Up) Coupled with PDMINTERFACE_MOUSE_PORT. */
442 PDMINTERFACE_MOUSE_CONNECTOR,
443 /** PDMIKEYBOARDPORT - The keyboard port interface. (Down) Coupled with PDMINTERFACE_KEYBOARD_CONNECTOR. */
444 PDMINTERFACE_KEYBOARD_PORT,
445 /** PDMIKEYBOARDCONNECTOR - The keyboard connector interface. (Up) Coupled with PDMINTERFACE_KEYBOARD_PORT. */
446 PDMINTERFACE_KEYBOARD_CONNECTOR,
447 /** PDMIDISPLAYPORT - The display port interface. (Down) Coupled with PDMINTERFACE_DISPLAY_CONNECTOR. */
448 PDMINTERFACE_DISPLAY_PORT,
449 /** PDMIDISPLAYCONNECTOR - The display connector interface. (Up) Coupled with PDMINTERFACE_DISPLAY_PORT. */
450 PDMINTERFACE_DISPLAY_CONNECTOR,
451 /** PDMICHARPORT - The char notify interface. (Down) Coupled with PDMINTERFACE_CHAR. */
452 PDMINTERFACE_CHAR_PORT,
453 /** PDMICHAR - The char driver interface. (Up) Coupled with PDMINTERFACE_CHAR_PORT. */
454 PDMINTERFACE_CHAR,
455 /** PDMISTREAM - The stream driver interface (Up) No coupling.
456 * Used by a char driver to implement PDMINTERFACE_CHAR. */
457 PDMINTERFACE_STREAM,
458 /** PDMIBLOCKPORT - The block notify interface (Down) Coupled with PDMINTERFACE_BLOCK. */
459 PDMINTERFACE_BLOCK_PORT,
460 /** PDMIBLOCK - The block driver interface (Up) Coupled with PDMINTERFACE_BLOCK_PORT. */
461 PDMINTERFACE_BLOCK,
462 /** PDMIBLOCKBIOS - The block bios interface. (External) */
463 PDMINTERFACE_BLOCK_BIOS,
464 /** PDMIMOUNTNOTIFY - The mountable notification interface. (Down) Coupled with PDMINTERFACE_MOUNT. */
465 PDMINTERFACE_MOUNT_NOTIFY,
466 /** PDMIMOUNT - The mountable interface. (Up) Coupled with PDMINTERFACE_MOUNT_NOTIFY. */
467 PDMINTERFACE_MOUNT,
468 /** PDMIMEDIA - The media interface. (Up) No coupling.
469 * Used by a block unit driver to implement PDMINTERFACE_BLOCK and PDMINTERFACE_BLOCK_BIOS. */
470 PDMINTERFACE_MEDIA,
471 /** PDMIISCSITRANSPORT - The iSCSI transport interface (Up) No coupling.
472 * used by the iSCSI media driver. */
473 PDMINTERFACE_ISCSITRANSPORT,
474
475 /** PDMINETWORKPORT - The network port interface. (Down) Coupled with PDMINTERFACE_NETWORK_CONNECTOR. */
476 PDMINTERFACE_NETWORK_PORT,
477 /** PDMINETWORKPORT - The network connector interface. (Up) Coupled with PDMINTERFACE_NETWORK_PORT. */
478 PDMINTERFACE_NETWORK_CONNECTOR,
479 /** PDMINETWORKCONFIG - The network configuartion interface. (Main) Used by the managment api. */
480 PDMINTERFACE_NETWORK_CONFIG,
481
482 /** PDMIAUDIOCONNECTOR - The audio driver interface. (Up) No coupling. */
483 PDMINTERFACE_AUDIO_CONNECTOR,
484
485 /** PDMIAUDIOSNIFFERPORT - The Audio Sniffer Device port interface. */
486 PDMINTERFACE_AUDIO_SNIFFER_PORT,
487 /** PDMIAUDIOSNIFFERCONNECTOR - The Audio Sniffer Driver connector interface. */
488 PDMINTERFACE_AUDIO_SNIFFER_CONNECTOR,
489
490 /** PDMIVMMDEVPORT - The VMM Device port interface. */
491 PDMINTERFACE_VMMDEV_PORT,
492 /** PDMIVMMDEVCONNECTOR - The VMM Device connector interface. */
493 PDMINTERFACE_VMMDEV_CONNECTOR,
494
495 /** PDMILEDPORTS - The generic LED port interface. (Down) Coupled with PDMINTERFACE_LED_CONNECTORS. */
496 PDMINTERFACE_LED_PORTS,
497 /** PDMILEDCONNECTORS - The generic LED connector interface. (Up) Coupled with PDMINTERFACE_LED_PORTS. */
498 PDMINTERFACE_LED_CONNECTORS,
499
500 /** PDMIACPIPORT - ACPI port interface. (Down) Coupled with PDMINTERFACE_ACPI_CONNECTOR. */
501 PDMINTERFACE_ACPI_PORT,
502 /** PDMIACPICONNECTOR - ACPI connector interface. (Up) Coupled with PDMINTERFACE_ACPI_PORT. */
503 PDMINTERFACE_ACPI_CONNECTOR,
504
505 /** PDMIHGCMPORT - The Host-Guest communication manager port interface. Normally implemented by VMMDev. */
506 PDMINTERFACE_HGCM_PORT,
507 /** PDMIHGCMCONNECTOR - The Host-Guest communication manager connector interface. Normally implemented by Main::VMMDevInterface. */
508 PDMINTERFACE_HGCM_CONNECTOR,
509
510 /** VUSBIROOTHUBPORT - VUSB RootHub port interface. (Down) Coupled with PDMINTERFACE_USB_RH_CONNECTOR. */
511 PDMINTERFACE_VUSB_RH_PORT,
512 /** VUSBIROOTHUBCONNECTOR - VUSB RootHub connector interface. (Up) Coupled with PDMINTERFACE_USB_RH_PORT. */
513 PDMINTERFACE_VUSB_RH_CONNECTOR,
514 /** VUSBIROOTHUBCONNECTOR - VUSB RootHub configuration interface. (Main) Used by the managment api. */
515 PDMINTERFACE_VUSB_RH_CONFIG,
516
517 /** VUSBROOTHUBCONNECTOR - VUSB Device interface. (Up) No coupling. */
518 PDMINTERFACE_VUSB_DEVICE,
519
520 /** Maximum interface number. */
521 PDMINTERFACE_MAX
522} PDMINTERFACE;
523
524
525/**
526 * PDM Driver Base Interface.
527 */
528typedef struct PDMIBASE
529{
530 /**
531 * Queries an interface to the driver.
532 *
533 * @returns Pointer to interface.
534 * @returns NULL if the interface was not supported by the driver.
535 * @param pInterface Pointer to this interface structure.
536 * @param enmInterface The requested interface identification.
537 * @thread Any thread.
538 */
539 DECLR3CALLBACKMEMBER(void *, pfnQueryInterface,(struct PDMIBASE *pInterface, PDMINTERFACE enmInterface));
540} PDMIBASE;
541/** Pointer to a PDM Driver Base Interface. */
542typedef PDMIBASE *PPDMIBASE;
543
544
545/**
546 * Dummy interface.
547 *
548 * This is used to typedef other dummy interfaces. The purpose of a dummy
549 * interface is to validate the logical function of a driver/device and
550 * full a natural interface pair.
551 */
552typedef struct PDMIDUMMY
553{
554 RTHCPTR pvDummy;
555} PDMIDUMMY;
556
557
558/** Pointer to a mouse port interface. */
559typedef struct PDMIMOUSEPORT *PPDMIMOUSEPORT;
560/**
561 * Mouse port interface.
562 * Pair with PDMIMOUSECONNECTOR.
563 */
564typedef struct PDMIMOUSEPORT
565{
566 /**
567 * Puts a mouse event.
568 * This is called by the source of mouse events. The event will be passed up until the
569 * topmost driver, which then calls the registered event handler.
570 *
571 * @returns VBox status code.
572 * @param pInterface Pointer to this interface structure.
573 * @param i32DeltaX The X delta.
574 * @param i32DeltaY The Y delta.
575 * @param i32DeltaZ The Z delta.
576 * @param fButtonStates The button states, see the PDMIMOUSEPORT_BUTTON_* \#defines.
577 * @thread The emulation thread.
578 */
579 DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIMOUSEPORT pInterface, int32_t i32DeltaX, int32_t i32DeltaY, int32_t i32DeltaZ, uint32_t fButtonStates));
580} PDMIMOUSEPORT;
581
582/** Mouse button defines for PDMIMOUSEPORT::pfnPutEvent.
583 * @{ */
584#define PDMIMOUSEPORT_BUTTON_LEFT BIT(0)
585#define PDMIMOUSEPORT_BUTTON_RIGHT BIT(1)
586#define PDMIMOUSEPORT_BUTTON_MIDDLE BIT(2)
587/** @} */
588
589
590/**
591 * Mouse connector interface.
592 * Pair with PDMIMOUSEPORT.
593 */
594typedef PDMIDUMMY PDMIMOUSECONNECTOR;
595 /** Pointer to a mouse connector interface. */
596typedef PDMIMOUSECONNECTOR *PPDMIMOUSECONNECTOR;
597
598
599/** Pointer to a keyboard port interface. */
600typedef struct PDMIKEYBOARDPORT *PPDMIKEYBOARDPORT;
601/**
602 * Keyboard port interface.
603 * Pair with PDMIKEYBOARDCONNECTOR.
604 */
605typedef struct PDMIKEYBOARDPORT
606{
607 /**
608 * Puts a keyboard event.
609 * This is called by the source of keyboard events. The event will be passed up until the
610 * topmost driver, which then calls the registered event handler.
611 *
612 * @returns VBox status code.
613 * @param pInterface Pointer to this interface structure.
614 * @param u8KeyCode The keycode to queue.
615 * @thread The emulation thread.
616 */
617 DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIKEYBOARDPORT pInterface, uint8_t u8KeyCode));
618} PDMIKEYBOARDPORT;
619
620/**
621 * Keyboard LEDs.
622 */
623typedef enum PDMKEYBLEDS
624{
625 /** No leds. */
626 PDMKEYBLEDS_NONE = 0x0000,
627 /** Num Lock */
628 PDMKEYBLEDS_NUMLOCK = 0x0001,
629 /** Caps Lock */
630 PDMKEYBLEDS_CAPSLOCK = 0x0002,
631 /** Scroll Lock */
632 PDMKEYBLEDS_SCROLLLOCK = 0x0004
633} PDMKEYBLEDS;
634
635/** Pointer to keyboard connector interface. */
636typedef struct PDMIKEYBOARDCONNECTOR *PPDMIKEYBOARDCONNECTOR;
637
638
639/**
640 * Keyboard connector interface.
641 * Pair with PDMIKEYBOARDPORT
642 */
643typedef struct PDMIKEYBOARDCONNECTOR
644{
645 /**
646 * Notifies the the downstream driver about an LED change initiated by the guest.
647 *
648 * @param pInterface Pointer to the this interface.
649 * @param enmLeds The new led mask.
650 */
651 DECLR3CALLBACKMEMBER(void, pfnLedStatusChange,(PPDMIKEYBOARDCONNECTOR pInterface, PDMKEYBLEDS enmLeds));
652
653} PDMIKEYBOARDCONNECTOR;
654
655
656/** Pointer to a display port interface. */
657typedef struct PDMIDISPLAYPORT *PPDMIDISPLAYPORT;
658/**
659 * Display port interface.
660 * Pair with PDMIDISPLAYCONNECTOR.
661 */
662typedef struct PDMIDISPLAYPORT
663{
664 /**
665 * Update the display with any changed regions.
666 *
667 * Flushes any display changes to the memory pointed to by the
668 * PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect()
669 * while doing so.
670 *
671 * @returns VBox status code.
672 * @param pInterface Pointer to this interface.
673 * @thread The emulation thread.
674 */
675 DECLR3CALLBACKMEMBER(int, pfnUpdateDisplay,(PPDMIDISPLAYPORT pInterface));
676
677 /**
678 * Update the entire display.
679 *
680 * Flushes the entire display content to the memory pointed to by the
681 * PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect().
682 *
683 * @returns VBox status code.
684 * @param pInterface Pointer to this interface.
685 * @thread The emulation thread.
686 */
687 DECLR3CALLBACKMEMBER(int, pfnUpdateDisplayAll,(PPDMIDISPLAYPORT pInterface));
688
689 /**
690 * Return the current guest color depth in bits per pixel (bpp).
691 *
692 * As the graphics card is able to provide display updates with the bpp
693 * requested by the host, this method can be used to query the actual
694 * guest color depth.
695 *
696 * @returns VBox status code.
697 * @param pInterface Pointer to this interface.
698 * @param pcBits Where to store the current guest color depth.
699 * @thread Any thread.
700 */
701 DECLR3CALLBACKMEMBER(int, pfnQueryColorDepth,(PPDMIDISPLAYPORT pInterface, uint32_t *pcBits));
702
703 /**
704 * Sets the refresh rate and restart the timer.
705 * The rate is defined as the minimum interval between the return of
706 * one PDMIDISPLAYPORT::pfnRefresh() call to the next one.
707 *
708 * The interval timer will be restarted by this call. So at VM startup
709 * this function must be called to start the refresh cycle. The refresh
710 * rate is not saved, but have to be when resuming a loaded VM state.
711 *
712 * @returns VBox status code.
713 * @param pInterface Pointer to this interface.
714 * @param cMilliesInterval Number of millies between two refreshes.
715 * @thread Any thread.
716 */
717 DECLR3CALLBACKMEMBER(int, pfnSetRefreshRate,(PPDMIDISPLAYPORT pInterface, uint32_t cMilliesInterval));
718
719 /**
720 * Create a 32-bbp snapshot of the display.
721 *
722 * This will create a 32-bbp bitmap with dword aligned scanline length. Because
723 * of a wish for no locks in the graphics device, this must be called from the
724 * emulation thread.
725 *
726 * @param pInterface Pointer to this interface.
727 * @param pvData Pointer the buffer to copy the bits to.
728 * @param cbData Size of the buffer.
729 * @param pcx Where to store the width of the bitmap. (optional)
730 * @param pcy Where to store the height of the bitmap. (optional)
731 * @param pcbData Where to store the actual size of the bitmap. (optional)
732 * @thread The emulation thread.
733 */
734 DECLR3CALLBACKMEMBER(int, pfnSnapshot,(PPDMIDISPLAYPORT pInterface, void *pvData, size_t cbData, uint32_t *pcx, uint32_t *pcy, size_t *pcbData));
735
736 /**
737 * Copy bitmap to the display.
738 *
739 * This will convert and copy a 32-bbp bitmap (with dword aligned scanline length) to
740 * the memory pointed to by the PDMIDISPLAYCONNECTOR interface.
741 *
742 * @param pInterface Pointer to this interface.
743 * @param pvData Pointer to the bitmap bits.
744 * @param x The upper left corner x coordinate of the destination rectangle.
745 * @param y The upper left corner y coordinate of the destination rectangle.
746 * @param cx The width of the source and destination rectangles.
747 * @param cy The height of the source and destination rectangles.
748 * @thread The emulation thread.
749 * @remark This is just a convenience for using the bitmap conversions of the
750 * graphics device.
751 */
752 DECLR3CALLBACKMEMBER(int, pfnDisplayBlt,(PPDMIDISPLAYPORT pInterface, const void *pvData, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
753
754 /**
755 * Render a rectangle from guest VRAM to Framebuffer.
756 *
757 * @param pInterface Pointer to this interface.
758 * @param x The upper left corner x coordinate of the rectangle to be updated.
759 * @param y The upper left corner y coordinate of the rectangle to be updated.
760 * @param cx The width of the rectangle to be updated.
761 * @param cy The height of the rectangle to be updated.
762 * @thread The emulation thread.
763 */
764 DECLR3CALLBACKMEMBER(void, pfnUpdateDisplayRect,(PPDMIDISPLAYPORT pInterface, int32_t x, int32_t y, uint32_t cx, uint32_t cy));
765
766 /**
767 * Inform the VGA device whether the Display is directly using the guest VRAM and there is no need
768 * to render the VRAM to the framebuffer memory.
769 *
770 * @param pInterface Pointer to this interface.
771 * @param fRender Whether the VRAM content must be rendered to the framebuffer.
772 * @thread The emulation thread.
773 */
774 DECLR3CALLBACKMEMBER(void, pfnSetRenderVRAM,(PPDMIDISPLAYPORT pInterface, bool fRender));
775} PDMIDISPLAYPORT;
776
777
778/** Pointer to a display connector interface. */
779typedef struct PDMIDISPLAYCONNECTOR *PPDMIDISPLAYCONNECTOR;
780/**
781 * Display connector interface.
782 * Pair with PDMIDISPLAYPORT.
783 */
784typedef struct PDMIDISPLAYCONNECTOR
785{
786 /**
787 * Resize the display.
788 * This is called when the resolution changes. This usually happens on
789 * request from the guest os, but may also happen as the result of a reset.
790 * If the callback returns VINF_VGA_RESIZE_IN_PROGRESS, the caller (VGA device)
791 * must not access the connector and return.
792 *
793 * @returns VINF_SUCCESS if the framebuffer resize was completed,
794 * VINF_VGA_RESIZE_IN_PROGRESS if resize takes time and not yet finished.
795 * @param pInterface Pointer to this interface.
796 * @param cBits Color depth (bits per pixel) of the new video mode.
797 * @param pvVRAM Address of the guest VRAM.
798 * @param cbLine Size in bytes of a single scan line.
799 * @param cx New display width.
800 * @param cy New display height.
801 * @thread The emulation thread.
802 */
803 DECLR3CALLBACKMEMBER(int, pfnResize,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t cBits, void *pvVRAM, uint32_t cbLine, uint32_t cx, uint32_t cy));
804
805 /**
806 * Update a rectangle of the display.
807 * PDMIDISPLAYPORT::pfnUpdateDisplay is the caller.
808 *
809 * @param pInterface Pointer to this interface.
810 * @param x The upper left corner x coordinate of the rectangle.
811 * @param y The upper left corner y coordinate of the rectangle.
812 * @param cx The width of the rectangle.
813 * @param cy The height of the rectangle.
814 * @thread The emulation thread.
815 */
816 DECLR3CALLBACKMEMBER(void, pfnUpdateRect,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
817
818 /**
819 * Refresh the display.
820 *
821 * The interval between these calls is set by
822 * PDMIDISPLAYPORT::pfnSetRefreshRate(). The driver should call
823 * PDMIDISPLAYPORT::pfnUpdateDisplay() if it wishes to refresh the
824 * display. PDMIDISPLAYPORT::pfnUpdateDisplay calls pfnUpdateRect with
825 * the changed rectangles.
826 *
827 * @param pInterface Pointer to this interface.
828 * @thread The emulation thread.
829 */
830 DECLR3CALLBACKMEMBER(void, pfnRefresh,(PPDMIDISPLAYCONNECTOR pInterface));
831
832 /**
833 * Reset the display.
834 *
835 * Notification message when the graphics card has been reset.
836 *
837 * @param pInterface Pointer to this interface.
838 * @thread The emulation thread.
839 */
840 DECLR3CALLBACKMEMBER(void, pfnReset,(PPDMIDISPLAYCONNECTOR pInterface));
841
842 /**
843 * LFB video mode enter/exit.
844 *
845 * Notification message when LinearFrameBuffer video mode is enabled/disabled.
846 *
847 * @param pInterface Pointer to this interface.
848 * @param fEnabled false - LFB mode was disabled,
849 * true - an LFB mode was disabled
850 * @thread The emulation thread.
851 */
852 DECLCALLBACKMEMBER(void, pfnLFBModeChange)(PPDMIDISPLAYCONNECTOR pInterface, bool fEnabled);
853
854 /**
855 * Process the guest graphics adapter information.
856 *
857 * Direct notification from guest to the display connector.
858 *
859 * @param pInterface Pointer to this interface.
860 * @param pvVRAM Address of the guest VRAM.
861 * @param u32VRAMSize Size of the guest VRAM.
862 * @thread The emulation thread.
863 */
864 DECLCALLBACKMEMBER(void, pfnProcessAdapterData)(PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, uint32_t u32VRAMSize);
865
866 /**
867 * Process the guest display information.
868 *
869 * Direct notification from guest to the display connector.
870 *
871 * @param pInterface Pointer to this interface.
872 * @param pvVRAM Address of the guest VRAM.
873 * @param uScreenId The index of the guest display to be processed.
874 * @thread The emulation thread.
875 */
876 DECLCALLBACKMEMBER(void, pfnProcessDisplayData)(PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, unsigned uScreenId);
877
878
879 /** Read-only attributes.
880 * For preformance reasons some readonly attributes are kept in the interface.
881 * We trust the interface users to respect the readonlyness of these.
882 * @{
883 */
884 /** Pointer to the display data buffer. */
885 uint8_t *pu8Data;
886 /** Size of a scanline in the data buffer. */
887 uint32_t cbScanline;
888 /** The color depth (in bits) the graphics card is supposed to provide. */
889 uint32_t cBits;
890 /** The display width. */
891 uint32_t cx;
892 /** The display height. */
893 uint32_t cy;
894 /** @} */
895} PDMIDISPLAYCONNECTOR;
896
897
898
899/**
900 * Block drive type.
901 */
902typedef enum PDMBLOCKTYPE
903{
904 /** Error (for the query function). */
905 PDMBLOCKTYPE_ERROR = 1,
906 /** 360KB 5 1/4" floppy drive. */
907 PDMBLOCKTYPE_FLOPPY_360,
908 /** 720KB 3 1/2" floppy drive. */
909 PDMBLOCKTYPE_FLOPPY_720,
910 /** 1.2MB 5 1/4" floppy drive. */
911 PDMBLOCKTYPE_FLOPPY_1_20,
912 /** 1.44MB 3 1/2" floppy drive. */
913 PDMBLOCKTYPE_FLOPPY_1_44,
914 /** 2.88MB 3 1/2" floppy drive. */
915 PDMBLOCKTYPE_FLOPPY_2_88,
916 /** CDROM drive. */
917 PDMBLOCKTYPE_CDROM,
918 /** DVD drive. */
919 PDMBLOCKTYPE_DVD,
920 /** Hard disk drive. */
921 PDMBLOCKTYPE_HARD_DISK
922} PDMBLOCKTYPE;
923
924
925/**
926 * Block raw command data transfer direction.
927 */
928typedef enum PDMBLOCKTXDIR
929{
930 PDMBLOCKTXDIR_NONE = 0,
931 PDMBLOCKTXDIR_FROM_DEVICE,
932 PDMBLOCKTXDIR_TO_DEVICE
933} PDMBLOCKTXDIR;
934
935/**
936 * Block notify interface.
937 * Pair with PDMIBLOCK.
938 */
939typedef PDMIDUMMY PDMIBLOCKPORT;
940/** Pointer to a block notify interface (dummy). */
941typedef PDMIBLOCKPORT *PPDMIBLOCKPORT;
942
943/** Pointer to a block interface. */
944typedef struct PDMIBLOCK *PPDMIBLOCK;
945/**
946 * Block interface.
947 * Pair with PDMIBLOCKPORT.
948 */
949typedef struct PDMIBLOCK
950{
951 /**
952 * Read bits.
953 *
954 * @returns VBox status code.
955 * @param pInterface Pointer to the interface structure containing the called function pointer.
956 * @param off Offset to start reading from.
957 * @param pvBuf Where to store the read bits.
958 * @param cbRead Number of bytes to read.
959 * @thread Any thread.
960 */
961 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIBLOCK pInterface, uint64_t off, void *pvBuf, size_t cbRead));
962
963 /**
964 * Write bits.
965 *
966 * @returns VBox status code.
967 * @param pInterface Pointer to the interface structure containing the called function pointer.
968 * @param off Offset to start writing at.
969 * @param pvBuf Where to store the write bits.
970 * @param cbWrite Number of bytes to write.
971 * @thread Any thread.
972 */
973 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIBLOCK pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));
974
975 /**
976 * Make sure that the bits written are actually on the storage medium.
977 *
978 * @returns VBox status code.
979 * @param pInterface Pointer to the interface structure containing the called function pointer.
980 * @thread Any thread.
981 */
982 DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIBLOCK pInterface));
983
984 /**
985 * Send a raw command to the underlying device (CDROM).
986 * This method is optional (i.e. the function pointer may be NULL).
987 *
988 * @returns VBox status code.
989 * @param pInterface Pointer to the interface structure containing the called function pointer.
990 * @param pbCmd Offset to start reading from.
991 * @param enmTxDir Direction of transfer.
992 * @param pvBuf Pointer tp the transfer buffer.
993 * @param cbBuf Size of the transfer buffer.
994 * @param pbSenseKey Status of the command (when return value is VERR_DEV_IO_ERROR).
995 * @param cTimeoutMillies Command timeout in milliseconds.
996 * @thread Any thread.
997 */
998 DECLR3CALLBACKMEMBER(int, pfnSendCmd,(PPDMIBLOCK pInterface, const uint8_t *pbCmd, PDMBLOCKTXDIR enmTxDir, void *pvBuf, size_t *pcbBuf, uint8_t *pbSenseKey, uint32_t cTimeoutMillies));
999
1000 /**
1001 * Check if the media is readonly or not.
1002 *
1003 * @returns true if readonly.
1004 * @returns false if read/write.
1005 * @param pInterface Pointer to the interface structure containing the called function pointer.
1006 * @thread Any thread.
1007 */
1008 DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIBLOCK pInterface));
1009
1010 /**
1011 * Gets the media size in bytes.
1012 *
1013 * @returns Media size in bytes.
1014 * @param pInterface Pointer to the interface structure containing the called function pointer.
1015 * @thread Any thread.
1016 */
1017 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIBLOCK pInterface));
1018
1019 /**
1020 * Gets the block drive type.
1021 *
1022 * @returns block drive type.
1023 * @param pInterface Pointer to the interface structure containing the called function pointer.
1024 * @thread Any thread.
1025 */
1026 DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCK pInterface));
1027
1028 /**
1029 * Gets the UUID of the block drive.
1030 * Don't return the media UUID if it's removable.
1031 *
1032 * @returns VBox status code.
1033 * @param pInterface Pointer to the interface structure containing the called function pointer.
1034 * @param pUuid Where to store the UUID on success.
1035 * @thread Any thread.
1036 */
1037 DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIBLOCK pInterface, PRTUUID pUuid));
1038} PDMIBLOCK;
1039
1040
1041/** Pointer to a mount interface. */
1042typedef struct PDMIMOUNTNOTIFY *PPDMIMOUNTNOTIFY;
1043/**
1044 * Block interface.
1045 * Pair with PDMIMOUNT.
1046 */
1047typedef struct PDMIMOUNTNOTIFY
1048{
1049 /**
1050 * Called when a media is mounted.
1051 *
1052 * @param pInterface Pointer to the interface structure containing the called function pointer.
1053 * @thread The emulation thread.
1054 */
1055 DECLR3CALLBACKMEMBER(void, pfnMountNotify,(PPDMIMOUNTNOTIFY pInterface));
1056
1057 /**
1058 * Called when a media is unmounted
1059 * @param pInterface Pointer to the interface structure containing the called function pointer.
1060 * @thread The emulation thread.
1061 */
1062 DECLR3CALLBACKMEMBER(void, pfnUnmountNotify,(PPDMIMOUNTNOTIFY pInterface));
1063} PDMIMOUNTNOTIFY;
1064
1065
1066/* Pointer to mount interface. */
1067typedef struct PDMIMOUNT *PPDMIMOUNT;
1068/**
1069 * Mount interface.
1070 * Pair with PDMIMOUNTNOTIFY.
1071 */
1072typedef struct PDMIMOUNT
1073{
1074 /**
1075 * Mount a media.
1076 *
1077 * This will not unmount any currently mounted media!
1078 *
1079 * @returns VBox status code.
1080 * @param pInterface Pointer to the interface structure containing the called function pointer.
1081 * @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have
1082 * constructed a configuration which can be attached to the bottom driver.
1083 * @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.
1084 * @thread The emulation thread.
1085 */
1086 DECLR3CALLBACKMEMBER(int, pfnMount,(PPDMIMOUNT pInterface, const char *pszFilename, const char *pszCoreDriver));
1087
1088 /**
1089 * Unmount the media.
1090 *
1091 * The driver will validate and pass it on. On the rebounce it will decide whether or not to detach it self.
1092 *
1093 * @returns VBox status code.
1094 * @param pInterface Pointer to the interface structure containing the called function pointer.
1095 * @thread The emulation thread.
1096 * @param fForce Force the unmount, even for locked media.
1097 * @thread The emulation thread.
1098 */
1099 DECLR3CALLBACKMEMBER(int, pfnUnmount,(PPDMIMOUNT pInterface, bool fForce));
1100
1101 /**
1102 * Checks if a media is mounted.
1103 *
1104 * @returns true if mounted.
1105 * @returns false if not mounted.
1106 * @param pInterface Pointer to the interface structure containing the called function pointer.
1107 * @thread Any thread.
1108 */
1109 DECLR3CALLBACKMEMBER(bool, pfnIsMounted,(PPDMIMOUNT pInterface));
1110
1111 /**
1112 * Locks the media, preventing any unmounting of it.
1113 *
1114 * @returns VBox status code.
1115 * @param pInterface Pointer to the interface structure containing the called function pointer.
1116 * @thread The emulation thread.
1117 */
1118 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMIMOUNT pInterface));
1119
1120 /**
1121 * Unlocks the media, canceling previous calls to pfnLock().
1122 *
1123 * @returns VBox status code.
1124 * @param pInterface Pointer to the interface structure containing the called function pointer.
1125 * @thread The emulation thread.
1126 */
1127 DECLR3CALLBACKMEMBER(int, pfnUnlock,(PPDMIMOUNT pInterface));
1128
1129 /**
1130 * Checks if a media is locked.
1131 *
1132 * @returns true if locked.
1133 * @returns false if not locked.
1134 * @param pInterface Pointer to the interface structure containing the called function pointer.
1135 * @thread Any thread.
1136 */
1137 DECLR3CALLBACKMEMBER(bool, pfnIsLocked,(PPDMIMOUNT pInterface));
1138} PDMIBLOCKMOUNT;
1139
1140/**
1141 * BIOS translation mode.
1142 */
1143typedef enum PDMBIOSTRANSLATION
1144{
1145 /** No translation. */
1146 PDMBIOSTRANSLATION_NONE = 1,
1147 /** LBA translation. */
1148 PDMBIOSTRANSLATION_LBA,
1149 /** Automatic select mode. */
1150 PDMBIOSTRANSLATION_AUTO
1151} PDMBIOSTRANSLATION;
1152
1153/** Pointer to BIOS translation mode. */
1154typedef PDMBIOSTRANSLATION *PPDMBIOSTRANSLATION;
1155
1156/** Pointer to a media interface. */
1157typedef struct PDMIMEDIA *PPDMIMEDIA;
1158/**
1159 * Media interface.
1160 * Makes up the fundation for PDMIBLOCK and PDMIBLOCKBIOS.
1161 */
1162typedef struct PDMIMEDIA
1163{
1164 /**
1165 * Read bits.
1166 *
1167 * @returns VBox status code.
1168 * @param pInterface Pointer to the interface structure containing the called function pointer.
1169 * @param off Offset to start reading from.
1170 * @param pvBuf Where to store the read bits.
1171 * @param cbRead Number of bytes to read.
1172 * @thread Any thread.
1173 */
1174 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIMEDIA pInterface, uint64_t off, void *pvBuf, size_t cbRead));
1175
1176 /**
1177 * Write bits.
1178 *
1179 * @returns VBox status code.
1180 * @param pInterface Pointer to the interface structure containing the called function pointer.
1181 * @param off Offset to start writing at.
1182 * @param pvBuf Where to store the write bits.
1183 * @param cbWrite Number of bytes to write.
1184 * @thread Any thread.
1185 */
1186 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIMEDIA pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));
1187
1188 /**
1189 * Make sure that the bits written are actually on the storage medium.
1190 *
1191 * @returns VBox status code.
1192 * @param pInterface Pointer to the interface structure containing the called function pointer.
1193 * @thread Any thread.
1194 */
1195 DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIMEDIA pInterface));
1196
1197 /**
1198 * Get the media size in bytes.
1199 *
1200 * @returns Media size in bytes.
1201 * @param pInterface Pointer to the interface structure containing the called function pointer.
1202 * @thread Any thread.
1203 */
1204 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIMEDIA pInterface));
1205
1206 /**
1207 * Check if the media is readonly or not.
1208 *
1209 * @returns true if readonly.
1210 * @returns false if read/write.
1211 * @param pInterface Pointer to the interface structure containing the called function pointer.
1212 * @thread Any thread.
1213 */
1214 DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIMEDIA pInterface));
1215
1216 /**
1217 * Get stored media geometry - BIOS property.
1218 * This is an optional feature of a media.
1219 *
1220 * @returns VBox status code.
1221 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1222 * @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetGeometry() yet.
1223 * @param pInterface Pointer to the interface structure containing the called function pointer.
1224 * @param pcCylinders Number of cylinders.
1225 * @param pcHeads Number of heads.
1226 * @param pcSectors Number of sectors. This number is 1-based.
1227 * @remark This have no influence on the read/write operations.
1228 * @thread Any thread.
1229 */
1230 DECLR3CALLBACKMEMBER(int, pfnBiosGetGeometry,(PPDMIMEDIA pInterface, uint32_t *pcCylinders, uint32_t *pcHeads, uint32_t *pcSectors));
1231
1232 /**
1233 * Store the media geometry - BIOS property.
1234 * This is an optional feature of a media.
1235 *
1236 * @returns VBox status code.
1237 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1238 * @param pInterface Pointer to the interface structure containing the called function pointer.
1239 * @param cCylinders Number of cylinders.
1240 * @param cHeads Number of heads.
1241 * @param cSectors Number of sectors. This number is 1-based.
1242 * @remark This have no influence on the read/write operations.
1243 * @thread The emulation thread.
1244 */
1245 DECLR3CALLBACKMEMBER(int, pfnBiosSetGeometry,(PPDMIMEDIA pInterface, uint32_t cCylinders, uint32_t cHeads, uint32_t cSectors));
1246
1247 /**
1248 * Get stored geometry translation mode - BIOS property.
1249 * This is an optional feature of a media.
1250 *
1251 * @returns VBox status code.
1252 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry translation mode.
1253 * @returns VERR_PDM_TRANSLATION_NOT_SET if the translation hasn't been set using pfnBiosSetTranslation() yet.
1254 * @param pInterface Pointer to the interface structure containing the called function pointer.
1255 * @param penmTranslation Where to store the translation type.
1256 * @remark This have no influence on the read/write operations.
1257 * @thread Any thread.
1258 */
1259 DECLR3CALLBACKMEMBER(int, pfnBiosGetTranslation,(PPDMIMEDIA pInterface, PPDMBIOSTRANSLATION penmTranslation));
1260
1261 /**
1262 * Store media geometry - BIOS property.
1263 * This is an optional feature of a media.
1264 *
1265 * @returns VBox status code.
1266 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1267 * @param pInterface Pointer to the interface structure containing the called function pointer.
1268 * @param enmTranslation The translation type.
1269 * @remark This have no influence on the read/write operations.
1270 * @thread The emulation thread.
1271 */
1272 DECLR3CALLBACKMEMBER(int, pfnBiosSetTranslation,(PPDMIMEDIA pInterface, PDMBIOSTRANSLATION enmTranslation));
1273
1274 /**
1275 * Gets the UUID of the media drive.
1276 *
1277 * @returns VBox status code.
1278 * @param pInterface Pointer to the interface structure containing the called function pointer.
1279 * @param pUuid Where to store the UUID on success.
1280 * @thread Any thread.
1281 */
1282 DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIMEDIA pInterface, PRTUUID pUuid));
1283
1284} PDMIMEDIA;
1285
1286
1287/** Pointer to a block BIOS interface. */
1288typedef struct PDMIBLOCKBIOS *PPDMIBLOCKBIOS;
1289/**
1290 * Media BIOS interface.
1291 * The interface the getting and setting properties which the BIOS/CMOS care about.
1292 */
1293typedef struct PDMIBLOCKBIOS
1294{
1295 /**
1296 * Get stored media geometry - BIOS property.
1297 * This is an optional feature of a media.
1298 *
1299 * @returns VBox status code.
1300 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1301 * @param pInterface Pointer to the interface structure containing the called function pointer.
1302 * @param pcCylinders Number of cylinders.
1303 * @param pcHeads Number of heads.
1304 * @param pcSectors Number of sectors. This number is 1-based.
1305 * @remark This have no influence on the read/write operations.
1306 * @thread Any thread.
1307 */
1308 DECLR3CALLBACKMEMBER(int, pfnGetGeometry,(PPDMIBLOCKBIOS pInterface, uint32_t *pcCylinders, uint32_t *pcHeads, uint32_t *pcSectors));
1309
1310 /**
1311 * Store the media geometry - BIOS property.
1312 * This is an optional feature of a media.
1313 *
1314 * @returns VBox status code.
1315 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1316 * @param pInterface Pointer to the interface structure containing the called function pointer.
1317 * @param cCylinders Number of cylinders.
1318 * @param cHeads Number of heads.
1319 * @param cSectors Number of sectors. This number is 1-based.
1320 * @remark This have no influence on the read/write operations.
1321 * @thread The emulation thread.
1322 */
1323 DECLR3CALLBACKMEMBER(int, pfnSetGeometry,(PPDMIBLOCKBIOS pInterface, uint32_t cCylinders, uint32_t cHeads, uint32_t cSectors));
1324
1325 /**
1326 * Get stored geometry translation mode - BIOS property.
1327 * This is an optional feature of a media.
1328 *
1329 * @returns VBox status code.
1330 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry translation mode.
1331 * @param pInterface Pointer to the interface structure containing the called function pointer.
1332 * @param penmTranslation Where to store the translation type.
1333 * @remark This have no influence on the read/write operations.
1334 * @thread Any thread.
1335 */
1336 DECLR3CALLBACKMEMBER(int, pfnGetTranslation,(PPDMIBLOCKBIOS pInterface, PPDMBIOSTRANSLATION penmTranslation));
1337
1338 /**
1339 * Store media geometry - BIOS property.
1340 * This is an optional feature of a media.
1341 *
1342 * @returns VBox status code.
1343 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1344 * @param pInterface Pointer to the interface structure containing the called function pointer.
1345 * @param enmTranslation The translation type.
1346 * @remark This have no influence on the read/write operations.
1347 * @thread The emulation thread.
1348 */
1349 DECLR3CALLBACKMEMBER(int, pfnSetTranslation,(PPDMIBLOCKBIOS pInterface, PDMBIOSTRANSLATION enmTranslation));
1350
1351 /**
1352 * Checks if the device should be visible to the BIOS or not.
1353 *
1354 * @returns true if the device is visible to the BIOS.
1355 * @returns false if the device is not visible to the BIOS.
1356 * @param pInterface Pointer to the interface structure containing the called function pointer.
1357 * @thread Any thread.
1358 */
1359 DECLR3CALLBACKMEMBER(bool, pfnIsVisible,(PPDMIBLOCKBIOS pInterface));
1360
1361 /**
1362 * Gets the block drive type.
1363 *
1364 * @returns block drive type.
1365 * @param pInterface Pointer to the interface structure containing the called function pointer.
1366 * @thread Any thread.
1367 */
1368 DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCKBIOS pInterface));
1369
1370} PDMIBLOCKBIOS;
1371
1372
1373/** Pointer to a static block core driver interface. */
1374typedef struct PDMIMEDIASTATIC *PPDMIMEDIASTATIC;
1375/**
1376 * Static block core driver interface.
1377 */
1378typedef struct PDMIMEDIASTATIC
1379{
1380 /**
1381 * Check if the specified file is a format which the core driver can handle.
1382 *
1383 * @returns true / false accordingly.
1384 * @param pInterface Pointer to the interface structure containing the called function pointer.
1385 * @param pszFilename Name of the file to probe.
1386 */
1387 DECLR3CALLBACKMEMBER(bool, pfnCanHandle,(PPDMIMEDIASTATIC pInterface, const char *pszFilename));
1388} PDMIMEDIASTATIC;
1389
1390
1391/** Pointer to an iSCSI Request PDU buffer. */
1392typedef struct ISCSIREQ *PISCSIREQ;
1393/**
1394 * iSCSI Request PDU buffer (gather).
1395 */
1396typedef struct ISCSIREQ
1397{
1398 /** Length of PDU segment in bytes. */
1399 size_t cbSeg;
1400 /** Pointer to PDU segment. */
1401 const void *pcvSeg;
1402} ISCSIREQ;
1403
1404/** Pointer to an iSCSI Response PDU buffer. */
1405typedef struct ISCSIRES *PISCSIRES;
1406/**
1407 * iSCSI Response PDU buffer (scatter).
1408 */
1409typedef struct ISCSIRES
1410{
1411 /** Length of PDU segment. */
1412 size_t cbSeg;
1413 /** Pointer to PDU segment. */
1414 void *pvSeg;
1415} ISCSIRES;
1416
1417/** Pointer to an iSCSI transport driver interface. */
1418typedef struct PDMIISCSITRANSPORT *PPDMIISCSITRANSPORT;
1419/**
1420 * iSCSI transport driver interface.
1421 */
1422typedef struct PDMIISCSITRANSPORT
1423{
1424 /**
1425 * Read bytes from an iSCSI transport stream. If the connection fails, it is automatically
1426 * reopened on the next call after the error is signalled. Error recovery in this case is
1427 * the duty of the caller.
1428 *
1429 * @returns VBox status code.
1430 * @param pTransport Pointer to the interface structure containing the called function pointer.
1431 * @param pvBuf Where to store the read bits.
1432 * @param cbBuf Number of bytes to read.
1433 * @param pcbRead Actual number of bytes read.
1434 * @thread Any thread.
1435 * @todo Correct the docs.
1436 */
1437 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIISCSITRANSPORT pTransport, PISCSIRES prgResponse, unsigned int cnResponse));
1438
1439 /**
1440 * Write bytes to an iSCSI transport stream. Padding is performed when necessary. If the connection
1441 * fails, it is automatically reopened on the next call after the error is signalled. Error recovery
1442 * in this case is the duty of the caller.
1443 *
1444 * @returns VBox status code.
1445 * @param pTransport Pointer to the interface structure containing the called function pointer.
1446 * @param pvBuf Where the write bits are stored.
1447 * @param cbWrite Number of bytes to write.
1448 * @thread Any thread.
1449 * @todo Correct the docs.
1450 */
1451 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIISCSITRANSPORT pTransport, PISCSIREQ prgRequest, unsigned int cnRequest));
1452
1453 /**
1454 * Open the iSCSI transport stream.
1455 *
1456 * @returns VBox status code.
1457 * @param pTransport Pointer to the interface structure containing the called function pointer.
1458 * @param pszTargetAddress Pointer to string of the format address:port.
1459 * @thread Any thread.
1460 */
1461 DECLR3CALLBACKMEMBER(int, pfnOpen,(PPDMIISCSITRANSPORT pTransport, const char *pszTargetAddress));
1462
1463 /**
1464 * Close the iSCSI transport stream.
1465 *
1466 * @returns VBox status code.
1467 * @param pTransport Pointer to the interface structure containing the called function pointer.
1468 * @thread Any thread.
1469 */
1470 DECLR3CALLBACKMEMBER(int, pfnClose,(PPDMIISCSITRANSPORT pTransport));
1471} PDMIISCSITRANSPORT;
1472
1473
1474/** Pointer to a char port interface. */
1475typedef struct PDMICHARPORT *PPDMICHARPORT;
1476/**
1477 * Char port interface.
1478 * Pair with PDMICHAR.
1479 */
1480typedef struct PDMICHARPORT
1481{
1482 /**
1483 * Deliver data read to the device/driver.
1484 *
1485 * @returns VBox status code.
1486 * @param pInterface Pointer to the interface structure containing the called function pointer.
1487 * @param pvBuf Where the read bits are stored.
1488 * @param pcbRead Number of bytes available for reading/having been read.
1489 * @thread Any thread.
1490 */
1491 DECLR3CALLBACKMEMBER(int, pfnNotifyRead,(PPDMICHARPORT pInterface, const void *pvBuf, size_t *pcbRead));
1492} PDMICHARPORT;
1493
1494/** Pointer to a char interface. */
1495typedef struct PDMICHAR *PPDMICHAR;
1496/**
1497 * Char interface.
1498 * Pair with PDMICHARPORT.
1499 */
1500typedef struct PDMICHAR
1501{
1502 /**
1503 * Write bits.
1504 *
1505 * @returns VBox status code.
1506 * @param pInterface Pointer to the interface structure containing the called function pointer.
1507 * @param pvBuf Where to store the write bits.
1508 * @param cbWrite Number of bytes to write.
1509 * @thread Any thread.
1510 */
1511 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMICHAR pInterface, const void *pvBuf, size_t cbWrite));
1512} PDMICHAR;
1513
1514
1515/** Pointer to a stream interface. */
1516typedef struct PDMISTREAM *PPDMISTREAM;
1517/**
1518 * Stream interface.
1519 * Makes up the fundation for PDMICHAR.
1520 */
1521typedef struct PDMISTREAM
1522{
1523 /**
1524 * Read bits.
1525 *
1526 * @returns VBox status code.
1527 * @param pInterface Pointer to the interface structure containing the called function pointer.
1528 * @param pvBuf Where to store the read bits.
1529 * @param cbRead Number of bytes to read/bytes actually read.
1530 * @thread Any thread.
1531 */
1532 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMISTREAM pInterface, void *pvBuf, size_t *cbRead));
1533
1534 /**
1535 * Write bits.
1536 *
1537 * @returns VBox status code.
1538 * @param pInterface Pointer to the interface structure containing the called function pointer.
1539 * @param pvBuf Where to store the write bits.
1540 * @param cbWrite Number of bytes to write/bytes actually written.
1541 * @thread Any thread.
1542 */
1543 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMISTREAM pInterface, const void *pvBuf, size_t *cbWrite));
1544} PDMISTREAM;
1545
1546
1547/** ACPI power source identifier */
1548typedef enum PDMACPIPOWERSOURCE
1549{
1550 PDM_ACPI_POWER_SOURCE_UNKNOWN = 0,
1551 PDM_ACPI_POWER_SOURCE_OUTLET,
1552 PDM_ACPI_POWER_SOURCE_BATTERY
1553} PDMACPIPOWERSOURCE;
1554/** Pointer to ACPI battery state. */
1555typedef PDMACPIPOWERSOURCE *PPDMACPIPOWERSOURCE;
1556
1557/** ACPI battey capacity */
1558typedef enum PDMACPIBATCAPACITY
1559{
1560 PDM_ACPI_BAT_CAPACITY_MIN = 0,
1561 PDM_ACPI_BAT_CAPACITY_MAX = 100,
1562 PDM_ACPI_BAT_CAPACITY_UNKNOWN = 255
1563} PDMACPIBATCAPACITY;
1564/** Pointer to ACPI battery capacity. */
1565typedef PDMACPIBATCAPACITY *PPDMACPIBATCAPACITY;
1566
1567/** ACPI battery state. See ACPI 3.0 spec '_BST (Battery Status)' */
1568typedef enum PDMACPIBATSTATE
1569{
1570 PDM_ACPI_BAT_STATE_CHARGED = 0x00,
1571 PDM_ACPI_BAT_STATE_CHARGING = 0x01,
1572 PDM_ACPI_BAT_STATE_DISCHARGING = 0x02,
1573 PDM_ACPI_BAT_STATE_CRITICAL = 0x04
1574} PDMACPIBATSTATE;
1575/** Pointer to ACPI battery state. */
1576typedef PDMACPIBATSTATE *PPDMACPIBATSTATE;
1577
1578/** Pointer to an ACPI port interface. */
1579typedef struct PDMIACPIPORT *PPDMIACPIPORT;
1580/**
1581 * ACPI port interface.
1582 */
1583typedef struct PDMIACPIPORT
1584{
1585 /**
1586 * Send an ACPI power off event.
1587 *
1588 * @returns VBox status code
1589 * @param pInterface Pointer to the interface structure containing the called function pointer.
1590 */
1591 DECLR3CALLBACKMEMBER(int, pfnPowerButtonPress,(PPDMIACPIPORT pInterface));
1592} PDMIACPIPORT;
1593
1594/** Pointer to an ACPI connector interface. */
1595typedef struct PDMIACPICONNECTOR *PPDMIACPICONNECTOR;
1596/**
1597 * ACPI connector interface.
1598 */
1599typedef struct PDMIACPICONNECTOR
1600{
1601 /**
1602 * Get the current power source of the host system.
1603 *
1604 * @returns VBox status code
1605 * @param pInterface Pointer to the interface structure containing the called function pointer.
1606 * @param penmPowerSource Pointer to the power source result variable.
1607 */
1608 DECLR3CALLBACKMEMBER(int, pfnQueryPowerSource,(PPDMIACPICONNECTOR, PPDMACPIPOWERSOURCE penmPowerSource));
1609
1610 /**
1611 * Query the current battery status of the host system.
1612 *
1613 * @returns VBox status code?
1614 * @param pInterface Pointer to the interface structure containing the called function pointer.
1615 * @param pfPresent Is set to true if battery is present, false otherwise.
1616 * @param penmRemainingCapacity Pointer to the battery remaining capacity (0 - 100 or 255 for unknown).
1617 * @param penmBatteryState Pointer to the battery status.
1618 * @param pu32PresentRate Pointer to the present rate (0..1000 of the total capacity).
1619 */
1620 DECLR3CALLBACKMEMBER(int, pfnQueryBatteryStatus,(PPDMIACPICONNECTOR, bool *pfPresent, PPDMACPIBATCAPACITY penmRemainingCapacity,
1621 PPDMACPIBATSTATE penmBatteryState, uint32_t *pu32PresentRate));
1622} PDMIACPICONNECTOR;
1623
1624/** Pointer to a VMMDevice port interface. */
1625typedef struct PDMIVMMDEVPORT *PPDMIVMMDEVPORT;
1626/**
1627 * VMMDevice port interface.
1628 */
1629typedef struct PDMIVMMDEVPORT
1630{
1631 /**
1632 * Return the current absolute mouse position in pixels
1633 *
1634 * @returns VBox status code
1635 * @param pAbsX Pointer of result value, can be NULL
1636 * @param pAbsY Pointer of result value, can be NULL
1637 */
1638 DECLR3CALLBACKMEMBER(int, pfnQueryAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, uint32_t *pAbsX, uint32_t *pAbsY));
1639
1640 /**
1641 * Set the new absolute mouse position in pixels
1642 *
1643 * @returns VBox status code
1644 * @param absX New absolute X position
1645 * @param absY New absolute Y position
1646 */
1647 DECLR3CALLBACKMEMBER(int, pfnSetAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, uint32_t absX, uint32_t absY));
1648
1649 /**
1650 * Return the current mouse capability flags
1651 *
1652 * @returns VBox status code
1653 * @param pCapabilities Pointer of result value
1654 */
1655 DECLR3CALLBACKMEMBER(int, pfnQueryMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t *pCapabilities));
1656
1657 /**
1658 * Set the current mouse capability flag (host side)
1659 *
1660 * @returns VBox status code
1661 * @param capabilities Capability mask
1662 */
1663 DECLR3CALLBACKMEMBER(int, pfnSetMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t capabilities));
1664
1665 /**
1666 * Issue a display resolution change request.
1667 *
1668 * Note that there can only one request in the queue and that in case the guest does
1669 * not process it, issuing another request will overwrite the previous.
1670 *
1671 * @returns VBox status code
1672 * @param cx Horizontal pixel resolution (0 = do not change).
1673 * @param cy Vertical pixel resolution (0 = do not change).
1674 * @param cBits Bits per pixel (0 = do not change).
1675 * @param display The display index.
1676 */
1677 DECLR3CALLBACKMEMBER(int, pfnRequestDisplayChange,(PPDMIVMMDEVPORT pInterface, uint32_t cx, uint32_t cy, uint32_t cBits, uint32_t display));
1678
1679 /**
1680 * Pass credentials to guest.
1681 *
1682 * Note that there can only be one set of credentials and the guest may or may not
1683 * query them and may do whatever it wants with them.
1684 *
1685 * @returns VBox status code
1686 * @param pszUsername User name, may be empty (UTF-8)
1687 * @param pszPassword Password, may be empty (UTF-8)
1688 * @param pszDomain Domain name, may be empty (UTF-8)
1689 * @param fFlags Bitflags
1690 */
1691 DECLR3CALLBACKMEMBER(int, pfnSetCredentials,(PPDMIVMMDEVPORT pInterface, const char *pszUsername,
1692 const char *pszPassword, const char *pszDomain,
1693 uint32_t fFlags));
1694
1695 /**
1696 * Notify the driver about a VBVA status change.
1697 *
1698 * @returns Nothing. Because it is informational callback.
1699 * @param fEnabled Current VBVA status.
1700 */
1701 DECLCALLBACKMEMBER(void, pfnVBVAChange)(PPDMIVMMDEVPORT pInterface, bool fEnabled);
1702
1703} PDMIVMMDEVPORT;
1704
1705/** Forward declaration of the video accelerator command memory. */
1706struct _VBVAMEMORY;
1707/** Forward declaration of the guest information structure. */
1708struct VBoxGuestInfo;
1709/** Pointer to video accelerator command memory. */
1710typedef struct _VBVAMEMORY *PVBVAMEMORY;
1711
1712/** Pointer to a VMMDev connector interface. */
1713typedef struct PDMIVMMDEVCONNECTOR *PPDMIVMMDEVCONNECTOR;
1714/**
1715 * VMMDev connector interface.
1716 * Pair with PDMIVMMDEVPORT.
1717 */
1718typedef struct PDMIVMMDEVCONNECTOR
1719{
1720 /**
1721 * Report guest OS version.
1722 * Called whenever the Additions issue a guest version report request.
1723 *
1724 * @param pInterface Pointer to this interface.
1725 * @param pGuestInfo Pointer to guest information structure
1726 * @thread The emulation thread.
1727 */
1728 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestVersion,(PPDMIVMMDEVCONNECTOR pInterface, struct VBoxGuestInfo *pGuestInfo));
1729
1730 /**
1731 * Update the mouse capabilities.
1732 * This is called when the mouse capabilities change. The new capabilities
1733 * are given and the connector should update its internal state.
1734 *
1735 * @param pInterface Pointer to this interface.
1736 * @param newCapabilities New capabilities.
1737 * @thread The emulation thread.
1738 */
1739 DECLR3CALLBACKMEMBER(void, pfnUpdateMouseCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
1740
1741 /**
1742 * Update the pointer shape.
1743 * This is called when the mouse pointer shape changes. The new shape
1744 * is passed as a caller allocated buffer that will be freed after returning
1745 *
1746 * @param pInterface Pointer to this interface.
1747 * @param fVisible Visibility indicator (if false, the other parameters are undefined).
1748 * @param fAlpha Flag whether alpha channel is being passed.
1749 * @param xHot Pointer hot spot x coordinate.
1750 * @param yHot Pointer hot spot y coordinate.
1751 * @param x Pointer new x coordinate on screen.
1752 * @param y Pointer new y coordinate on screen.
1753 * @param cx Pointer width in pixels.
1754 * @param cy Pointer height in pixels.
1755 * @param cbScanline Size of one scanline in bytes.
1756 * @param pvShape New shape buffer.
1757 * @thread The emulation thread.
1758 */
1759 DECLR3CALLBACKMEMBER(void, pfnUpdatePointerShape,(PPDMIVMMDEVCONNECTOR pInterface, bool fVisible, bool fAlpha,
1760 uint32_t xHot, uint32_t yHot,
1761 uint32_t cx, uint32_t cy,
1762 void *pvShape));
1763
1764 /**
1765 * Enable or disable video acceleration on behalf of guest.
1766 *
1767 * @param pInterface Pointer to this interface.
1768 * @param fEnable Whether to enable acceleration.
1769 * @param pVbvaMemory Video accelerator memory.
1770
1771 * @return VBox rc. VINF_SUCCESS if VBVA was enabled.
1772 * @thread The emulation thread.
1773 */
1774 DECLR3CALLBACKMEMBER(int, pfnVideoAccelEnable,(PPDMIVMMDEVCONNECTOR pInterface, bool fEnable, PVBVAMEMORY pVbvaMemory));
1775
1776 /**
1777 * Force video queue processing.
1778 *
1779 * @param pInterface Pointer to this interface.
1780 * @thread The emulation thread.
1781 */
1782 DECLR3CALLBACKMEMBER(void, pfnVideoAccelFlush,(PPDMIVMMDEVCONNECTOR pInterface));
1783
1784 /**
1785 * Return whether the given video mode is supported/wanted by the host.
1786 *
1787 * @returns VBox status code
1788 * @param pInterface Pointer to this interface.
1789 * @param cy Video mode horizontal resolution in pixels.
1790 * @param cx Video mode vertical resolution in pixels.
1791 * @param cBits Video mode bits per pixel.
1792 * @param pfSupported Where to put the indicator for whether this mode is supported. (output)
1793 * @thread The emulation thread.
1794 */
1795 DECLR3CALLBACKMEMBER(int, pfnVideoModeSupported,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cx, uint32_t cy, uint32_t cBits, bool *pfSupported));
1796
1797 /**
1798 * Queries by how many pixels the height should be reduced when calculating video modes
1799 *
1800 * @returns VBox status code
1801 * @param pInterface Pointer to this interface.
1802 * @param pcyReduction Pointer to the result value.
1803 * @thread The emulation thread.
1804 */
1805 DECLR3CALLBACKMEMBER(int, pfnGetHeightReduction,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcyReduction));
1806
1807 /**
1808 * Informs about a credentials judgement result from the guest.
1809 *
1810 * @returns VBox status code
1811 * @param pInterface Pointer to this interface.
1812 * @param fFlags Judgement result flags.
1813 * @thread The emulation thread.
1814 */
1815 DECLR3CALLBACKMEMBER(int, pfnSetCredentialsJudgementResult,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t fFlags));
1816} PDMIVMMDEVCONNECTOR;
1817
1818
1819/**
1820 * MAC address.
1821 * (The first 24 bits are the 'company id', where the first bit seems to have a special meaning if set.)
1822 */
1823typedef union PDMMAC
1824{
1825 /** 8-bit view. */
1826 uint8_t au8[6];
1827 /** 16-bit view. */
1828 uint16_t au16[3];
1829} PDMMAC;
1830/** Pointer to a MAC address. */
1831typedef PDMMAC *PPDMMAC;
1832/** Pointer to a const MAC address. */
1833typedef const PDMMAC *PCPDMMAC;
1834
1835
1836/** Pointer to a network port interface */
1837typedef struct PDMINETWORKPORT *PPDMINETWORKPORT;
1838/**
1839 * Network port interface.
1840 */
1841typedef struct PDMINETWORKPORT
1842{
1843 /**
1844 * Check how much data the device/driver can receive data now.
1845 * This must be called before the pfnRecieve() method is called.
1846 *
1847 * @returns Number of bytes the device can receive now.
1848 * @param pInterface Pointer to the interface structure containing the called function pointer.
1849 * @thread EMT
1850 */
1851 DECLR3CALLBACKMEMBER(size_t, pfnCanReceive,(PPDMINETWORKPORT pInterface));
1852
1853 /**
1854 * Receive data from the network.
1855 *
1856 * @returns VBox status code.
1857 * @param pInterface Pointer to the interface structure containing the called function pointer.
1858 * @param pvBuf The available data.
1859 * @param cb Number of bytes available in the buffer.
1860 * @thread EMT
1861 */
1862 DECLR3CALLBACKMEMBER(int, pfnReceive,(PPDMINETWORKPORT pInterface, const void *pvBuf, size_t cb));
1863
1864} PDMINETWORKPORT;
1865
1866
1867/**
1868 * Network link state.
1869 */
1870typedef enum PDMNETWORKLINKSTATE
1871{
1872 /** Invalid state. */
1873 PDMNETWORKLINKSTATE_INVALID = 0,
1874 /** The link is up. */
1875 PDMNETWORKLINKSTATE_UP,
1876 /** The link is down. */
1877 PDMNETWORKLINKSTATE_DOWN,
1878 /** The link is temporarily down while resuming. */
1879 PDMNETWORKLINKSTATE_DOWN_RESUME
1880} PDMNETWORKLINKSTATE;
1881
1882
1883/** Pointer to a network connector interface */
1884typedef struct PDMINETWORKCONNECTOR *PPDMINETWORKCONNECTOR;
1885/**
1886 * Network connector interface.
1887 */
1888typedef struct PDMINETWORKCONNECTOR
1889{
1890 /**
1891 * Send data to the network.
1892 *
1893 * @returns VBox status code.
1894 * @param pInterface Pointer to the interface structure containing the called function pointer.
1895 * @param pvBuf Data to send.
1896 * @param cb Number of bytes to send.
1897 * @thread EMT
1898 */
1899 DECLR3CALLBACKMEMBER(int, pfnSend,(PPDMINETWORKCONNECTOR pInterface, const void *pvBuf, size_t cb));
1900
1901 /**
1902 * Set promiscuous mode.
1903 *
1904 * This is called when the promiscuous mode is set. This means that there doesn't have
1905 * to be a mode change when it's called.
1906 *
1907 * @param pInterface Pointer to the interface structure containing the called function pointer.
1908 * @param fPromiscuous Set if the adaptor is now in promiscuous mode. Clear if it is not.
1909 * @thread EMT
1910 */
1911 DECLR3CALLBACKMEMBER(void, pfnSetPromiscuousMode,(PPDMINETWORKCONNECTOR pInterface, bool fPromiscuous));
1912
1913 /**
1914 * Notification on link status changes.
1915 *
1916 * @param pInterface Pointer to the interface structure containing the called function pointer.
1917 * @param enmLinkState The new link state.
1918 * @thread EMT
1919 */
1920 DECLR3CALLBACKMEMBER(void, pfnNotifyLinkChanged,(PPDMINETWORKCONNECTOR pInterface, PDMNETWORKLINKSTATE enmLinkState));
1921
1922 /**
1923 * More receive buffer has become available.
1924 *
1925 * This is called when the NIC frees up receive buffers.
1926 *
1927 * @param pInterface Pointer to the interface structure containing the called function pointer.
1928 * @thread EMT
1929 */
1930 DECLR3CALLBACKMEMBER(void, pfnNotifyCanReceive,(PPDMINETWORKCONNECTOR pInterface));
1931
1932} PDMINETWORKCONNECTOR;
1933
1934
1935/** Pointer to a network config port interface */
1936typedef struct PDMINETWORKCONFIG *PPDMINETWORKCONFIG;
1937/**
1938 * Network config port interface.
1939 */
1940typedef struct PDMINETWORKCONFIG
1941{
1942 /**
1943 * Gets the current Media Access Control (MAC) address.
1944 *
1945 * @returns VBox status code.
1946 * @param pInterface Pointer to the interface structure containing the called function pointer.
1947 * @param pMac Where to store the MAC address.
1948 * @thread EMT
1949 */
1950 DECLR3CALLBACKMEMBER(int, pfnGetMac,(PPDMINETWORKCONFIG pInterface, PPDMMAC *pMac));
1951
1952 /**
1953 * Gets the new link state.
1954 *
1955 * @returns The current link state.
1956 * @param pInterface Pointer to the interface structure containing the called function pointer.
1957 * @thread EMT
1958 */
1959 DECLR3CALLBACKMEMBER(PDMNETWORKLINKSTATE, pfnGetLinkState,(PPDMINETWORKCONFIG pInterface));
1960
1961 /**
1962 * Sets the new link state.
1963 *
1964 * @returns VBox status code.
1965 * @param pInterface Pointer to the interface structure containing the called function pointer.
1966 * @param enmState The new link state
1967 * @thread EMT
1968 */
1969 DECLR3CALLBACKMEMBER(int, pfnSetLinkState,(PPDMINETWORKCONFIG pInterface, PDMNETWORKLINKSTATE enmState));
1970
1971} PDMINETWORKCONFIG;
1972
1973
1974/** Pointer to a network connector interface */
1975typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
1976/**
1977 * Audio connector interface.
1978 */
1979typedef struct PDMIAUDIOCONNECTOR
1980{
1981 DECLR3CALLBACKMEMBER(void, pfnRun,(PPDMIAUDIOCONNECTOR pInterface));
1982
1983/* DECLR3CALLBACKMEMBER(int, pfnSetRecordSource,(PPDMIAUDIOINCONNECTOR pInterface, AUDIORECSOURCE)); */
1984
1985} PDMIAUDIOCONNECTOR;
1986
1987
1988/** @todo r=bird: the two following interfaces are hacks to work around the missing audio driver
1989 * interface. This should be addressed rather than making more temporary hacks. */
1990
1991/** Pointer to a Audio Sniffer Device port interface. */
1992typedef struct PDMIAUDIOSNIFFERPORT *PPDMIAUDIOSNIFFERPORT;
1993
1994/**
1995 * Audio Sniffer port interface.
1996 */
1997typedef struct PDMIAUDIOSNIFFERPORT
1998{
1999 /**
2000 * Enables or disables sniffing. If sniffing is being enabled also sets a flag
2001 * whether the audio must be also left on the host.
2002 *
2003 * @returns VBox status code
2004 * @param pInterface Pointer to this interface.
2005 * @param fEnable 'true' for enable sniffing, 'false' to disable.
2006 * @param fKeepHostAudio Indicates whether host audio should also present
2007 * 'true' means that sound should not be played
2008 * by the audio device.
2009 */
2010 DECLR3CALLBACKMEMBER(int, pfnSetup,(PPDMIAUDIOSNIFFERPORT pInterface, bool fEnable, bool fKeepHostAudio));
2011
2012} PDMIAUDIOSNIFFERPORT;
2013
2014/** Pointer to a Audio Sniffer connector interface. */
2015typedef struct PDMIAUDIOSNIFFERCONNECTOR *PPDMIAUDIOSNIFFERCONNECTOR;
2016
2017/**
2018 * Audio Sniffer connector interface.
2019 * Pair with PDMIAUDIOSNIFFERPORT.
2020 */
2021typedef struct PDMIAUDIOSNIFFERCONNECTOR
2022{
2023 /**
2024 * AudioSniffer device calls this method when audio samples
2025 * are about to be played and sniffing is enabled.
2026 *
2027 * @param pInterface Pointer to this interface.
2028 * @param pvSamples Audio samples buffer.
2029 * @param cSamples How many complete samples are in the buffer.
2030 * @param iSampleHz The sample frequency in Hz.
2031 * @param cChannels Number of channels. 1 for mono, 2 for stereo.
2032 * @param cBits How many bits a sample for a single channel has. Normally 8 or 16.
2033 * @param fUnsigned Whether samples are unsigned values.
2034 * @thread The emulation thread.
2035 */
2036 DECLR3CALLBACKMEMBER(void, pfnAudioSamplesOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, void *pvSamples, uint32_t cSamples,
2037 int iSampleHz, int cChannels, int cBits, bool fUnsigned));
2038
2039 /**
2040 * AudioSniffer device calls this method when output volume is changed.
2041 *
2042 * @param pInterface Pointer to this interface.
2043 * @param u16LeftVolume 0..0xFFFF volume level for left channel.
2044 * @param u16RightVolume 0..0xFFFF volume level for right channel.
2045 * @thread The emulation thread.
2046 */
2047 DECLR3CALLBACKMEMBER(void, pfnAudioVolumeOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, uint16_t u16LeftVolume, uint16_t u16RightVolume));
2048
2049} PDMIAUDIOSNIFFERCONNECTOR;
2050
2051
2052/**
2053 * Generic status LED core.
2054 * Note that a unit doesn't have to support all the indicators.
2055 */
2056typedef union PDMLEDCORE
2057{
2058 /** 32-bit view. */
2059 uint32_t volatile u32;
2060 /** Bit view. */
2061 struct
2062 {
2063 /** Reading/Receiving indicator. */
2064 uint32_t fReading : 1;
2065 /** Writing/Sending indicator. */
2066 uint32_t fWriting : 1;
2067 /** Busy indicator. */
2068 uint32_t fBusy : 1;
2069 /** Error indicator. */
2070 uint32_t fError : 1;
2071 } s;
2072} PDMLEDCORE;
2073
2074/** LED bit masks for the u32 view.
2075 * @{ */
2076/** Reading/Receiving indicator. */
2077#define PDMLED_READING BIT(0)
2078/** Writing/Sending indicator. */
2079#define PDMLED_WRITING BIT(1)
2080/** Busy indicator. */
2081#define PDMLED_BUSY BIT(2)
2082/** Error indicator. */
2083#define PDMLED_ERROR BIT(3)
2084/** @} */
2085
2086
2087/**
2088 * Generic status LED.
2089 * Note that a unit doesn't have to support all the indicators.
2090 */
2091typedef struct PDMLED
2092{
2093 /** Just a magic for sanity checking. */
2094 uint32_t u32Magic;
2095 uint32_t u32Alignment; /**< structure size alignment. */
2096 /** The actual LED status.
2097 * Only the device is allowed to change this. */
2098 PDMLEDCORE Actual;
2099 /** The asserted LED status which is cleared by the reader.
2100 * The device will assert the bits but never clear them.
2101 * The driver clears them as it sees fit. */
2102 PDMLEDCORE Asserted;
2103} PDMLED;
2104
2105/** Pointer to an LED. */
2106typedef PDMLED *PPDMLED;
2107/** Pointer to a const LED. */
2108typedef const PDMLED *PCPDMLED;
2109
2110#define PDMLED_MAGIC ( 0x11335577 )
2111
2112/** Pointer to an LED ports interface. */
2113typedef struct PDMILEDPORTS *PPDMILEDPORTS;
2114/**
2115 * Interface for exporting LEDs.
2116 */
2117typedef struct PDMILEDPORTS
2118{
2119 /**
2120 * Gets the pointer to the status LED of a unit.
2121 *
2122 * @returns VBox status code.
2123 * @param pInterface Pointer to the interface structure containing the called function pointer.
2124 * @param iLUN The unit which status LED we desire.
2125 * @param ppLed Where to store the LED pointer.
2126 */
2127 DECLR3CALLBACKMEMBER(int, pfnQueryStatusLed,(PPDMILEDPORTS pInterface, unsigned iLUN, PPDMLED *ppLed));
2128
2129} PDMILEDPORTS;
2130
2131
2132/** Pointer to an LED connectors interface. */
2133typedef struct PDMILEDCONNECTORS *PPDMILEDCONNECTORS;
2134/**
2135 * Interface for reading LEDs.
2136 */
2137typedef struct PDMILEDCONNECTORS
2138{
2139 /**
2140 * Notification about a unit which have been changed.
2141 *
2142 * The driver must discard any pointers to data owned by
2143 * the unit and requery it.
2144 *
2145 * @param pInterface Pointer to the interface structure containing the called function pointer.
2146 * @param iLUN The unit number.
2147 */
2148 DECLR3CALLBACKMEMBER(void, pfnUnitChanged,(PPDMILEDCONNECTORS pInterface, unsigned iLUN));
2149} PDMILEDCONNECTORS;
2150
2151
2152/** The special status unit number */
2153#define PDM_STATUS_LUN 999
2154
2155
2156#ifdef VBOX_HGCM
2157
2158/** Abstract HGCM command structure. Used only to define a typed pointer. */
2159struct VBOXHGCMCMD;
2160
2161/** Pointer to HGCM command structure. This pointer is unique and identifies
2162 * the command being processed. The pointer is passed to HGCM connector methods,
2163 * and must be passed back to HGCM port when command is completed.
2164 */
2165typedef struct VBOXHGCMCMD *PVBOXHGCMCMD;
2166
2167/** Pointer to a HGCM port interface. */
2168typedef struct PDMIHGCMPORT *PPDMIHGCMPORT;
2169
2170/**
2171 * HGCM port interface. Normally implemented by VMMDev.
2172 */
2173typedef struct PDMIHGCMPORT
2174{
2175 /**
2176 * Notify the guest on a command completion.
2177 *
2178 * @param pInterface Pointer to this interface.
2179 * @param rc The return code (VBox error code).
2180 * @param pCmd A pointer that identifies the completed command.
2181 *
2182 * @returns VBox status code
2183 */
2184 DECLR3CALLBACKMEMBER(void, pfnCompleted,(PPDMIHGCMPORT pInterface, int32_t rc, PVBOXHGCMCMD pCmd));
2185
2186} PDMIHGCMPORT;
2187
2188
2189/** Pointer to a HGCM connector interface. */
2190typedef struct PDMIHGCMCONNECTOR *PPDMIHGCMCONNECTOR;
2191
2192/** Pointer to a HGCM function parameter. */
2193typedef struct VBOXHGCMSVCPARM *PVBOXHGCMSVCPARM;
2194
2195/** Pointer to a HGCM service location structure. */
2196typedef struct HGCMSERVICELOCATION *PHGCMSERVICELOCATION;
2197
2198/**
2199 * HGCM connector interface.
2200 * Pair with PDMIHGCMPORT.
2201 */
2202typedef struct PDMIHGCMCONNECTOR
2203{
2204 /**
2205 * Locate a service and inform it about a client connection.
2206 *
2207 * @param pInterface Pointer to this interface.
2208 * @param pCmd A pointer that identifies the command.
2209 * @param pServiceLocation Pointer to the service location structure.
2210 * @param pu32ClientID Where to store the client id for the connection.
2211 * @return VBox status code.
2212 * @thread The emulation thread.
2213 */
2214 DECLR3CALLBACKMEMBER(int, pfnConnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, PHGCMSERVICELOCATION pServiceLocation, uint32_t *pu32ClientID));
2215
2216 /**
2217 * Disconnect from service.
2218 *
2219 * @param pInterface Pointer to this interface.
2220 * @param pCmd A pointer that identifies the command.
2221 * @param u32ClientID The client id returned by the pfnConnect call.
2222 * @return VBox status code.
2223 * @thread The emulation thread.
2224 */
2225 DECLR3CALLBACKMEMBER(int, pfnDisconnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID));
2226
2227 /**
2228 * Process a guest issued command.
2229 *
2230 * @param pInterface Pointer to this interface.
2231 * @param pCmd A pointer that identifies the command.
2232 * @param u32ClientID The client id returned by the pfnConnect call.
2233 * @param u32Function Function to be performed by the service.
2234 * @param cParms Number of parameters in the array pointed to by paParams.
2235 * @param paParms Pointer to an array of parameters.
2236 * @return VBox status code.
2237 * @thread The emulation thread.
2238 */
2239 DECLR3CALLBACKMEMBER(int, pfnCall,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID, uint32_t u32Function,
2240 uint32_t cParms, PVBOXHGCMSVCPARM paParms));
2241
2242} PDMIHGCMCONNECTOR;
2243
2244#endif
2245
2246/** @} */
2247
2248
2249/** @defgroup grp_pdm_driver Drivers
2250 * @ingroup grp_pdm
2251 * @{
2252 */
2253
2254
2255/**
2256 * Construct a driver instance for a VM.
2257 *
2258 * @returns VBox status.
2259 * @param pDrvIns The driver instance data.
2260 * If the registration structure is needed, pDrvIns->pDrvReg points to it.
2261 * @param pCfgHandle Configuration node handle for the driver. Use this to obtain the configuration
2262 * of the driver instance. It's also found in pDrvIns->pCfgHandle as it's expected
2263 * to be used frequently in this function.
2264 */
2265typedef DECLCALLBACK(int) FNPDMDRVCONSTRUCT(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle);
2266/** Pointer to a FNPDMDRVCONSTRUCT() function. */
2267typedef FNPDMDRVCONSTRUCT *PFNPDMDRVCONSTRUCT;
2268
2269/**
2270 * Destruct a driver instance.
2271 *
2272 * Most VM resources are freed by the VM. This callback is provided so that
2273 * any non-VM resources can be freed correctly.
2274 *
2275 * @param pDrvIns The driver instance data.
2276 */
2277typedef DECLCALLBACK(void) FNPDMDRVDESTRUCT(PPDMDRVINS pDrvIns);
2278/** Pointer to a FNPDMDRVDESTRUCT() function. */
2279typedef FNPDMDRVDESTRUCT *PFNPDMDRVDESTRUCT;
2280
2281/**
2282 * Driver I/O Control interface.
2283 *
2284 * This is used by external components, such as the COM interface, to
2285 * communicate with a driver using a driver specific interface. Generally,
2286 * the driver interfaces are used for this task.
2287 *
2288 * @returns VBox status code.
2289 * @param pDrvIns Pointer to the driver instance.
2290 * @param uFunction Function to perform.
2291 * @param pvIn Pointer to input data.
2292 * @param cbIn Size of input data.
2293 * @param pvOut Pointer to output data.
2294 * @param cbOut Size of output data.
2295 * @param pcbOut Where to store the actual size of the output data.
2296 */
2297typedef DECLCALLBACK(int) FNPDMDRVIOCTL(PPDMDRVINS pDrvIns, RTUINT uFunction,
2298 void *pvIn, RTUINT cbIn,
2299 void *pvOut, RTUINT cbOut, PRTUINT pcbOut);
2300/** Pointer to a FNPDMDRVIOCTL() function. */
2301typedef FNPDMDRVIOCTL *PFNPDMDRVIOCTL;
2302
2303/**
2304 * Power On notification.
2305 *
2306 * @param pDrvIns The driver instance data.
2307 */
2308typedef DECLCALLBACK(void) FNPDMDRVPOWERON(PPDMDRVINS pDrvIns);
2309/** Pointer to a FNPDMDRVPOWERON() function. */
2310typedef FNPDMDRVPOWERON *PFNPDMDRVPOWERON;
2311
2312/**
2313 * Reset notification.
2314 *
2315 * @returns VBox status.
2316 * @param pDrvIns The driver instance data.
2317 */
2318typedef DECLCALLBACK(void) FNPDMDRVRESET(PPDMDRVINS pDrvIns);
2319/** Pointer to a FNPDMDRVRESET() function. */
2320typedef FNPDMDRVRESET *PFNPDMDRVRESET;
2321
2322/**
2323 * Suspend notification.
2324 *
2325 * @returns VBox status.
2326 * @param pDrvIns The driver instance data.
2327 */
2328typedef DECLCALLBACK(void) FNPDMDRVSUSPEND(PPDMDRVINS pDrvIns);
2329/** Pointer to a FNPDMDRVSUSPEND() function. */
2330typedef FNPDMDRVSUSPEND *PFNPDMDRVSUSPEND;
2331
2332/**
2333 * Resume notification.
2334 *
2335 * @returns VBox status.
2336 * @param pDrvIns The driver instance data.
2337 */
2338typedef DECLCALLBACK(void) FNPDMDRVRESUME(PPDMDRVINS pDrvIns);
2339/** Pointer to a FNPDMDRVRESUME() function. */
2340typedef FNPDMDRVRESUME *PFNPDMDRVRESUME;
2341
2342/**
2343 * Power Off notification.
2344 *
2345 * @param pDrvIns The driver instance data.
2346 */
2347typedef DECLCALLBACK(void) FNPDMDRVPOWEROFF(PPDMDRVINS pDrvIns);
2348/** Pointer to a FNPDMDRVPOWEROFF() function. */
2349typedef FNPDMDRVPOWEROFF *PFNPDMDRVPOWEROFF;
2350
2351/**
2352 * Detach notification.
2353 *
2354 * This is called when a driver below it in the chain is detaching itself
2355 * from it. The driver should adjust it's state to reflect this.
2356 *
2357 * This is like ejecting a cdrom or floppy.
2358 *
2359 * @param pDrvIns The driver instance.
2360 */
2361typedef DECLCALLBACK(void) FNPDMDRVDETACH(PPDMDRVINS pDrvIns);
2362/** Pointer to a FNPDMDRVDETACH() function. */
2363typedef FNPDMDRVDETACH *PFNPDMDRVDETACH;
2364
2365
2366
2367/** PDM Driver Registration Structure,
2368 * This structure is used when registering a driver from
2369 * VBoxInitDrivers() (HC Ring-3). PDM will continue use till
2370 * the VM is terminated.
2371 */
2372typedef struct PDMDRVREG
2373{
2374 /** Structure version. PDM_DRVREG_VERSION defines the current version. */
2375 uint32_t u32Version;
2376 /** Driver name. */
2377 char szDriverName[32];
2378 /** The description of the driver. The UTF-8 string pointed to shall, like this structure,
2379 * remain unchanged from registration till VM destruction. */
2380 const char *pszDescription;
2381
2382 /** Flags, combination of the PDM_DRVREG_FLAGS_* \#defines. */
2383 RTUINT fFlags;
2384 /** Driver class(es), combination of the PDM_DRVREG_CLASS_* \#defines. */
2385 RTUINT fClass;
2386 /** Maximum number of instances (per VM). */
2387 RTUINT cMaxInstances;
2388 /** Size of the instance data. */
2389 RTUINT cbInstance;
2390
2391 /** Construct instance - required. */
2392 PFNPDMDRVCONSTRUCT pfnConstruct;
2393 /** Destruct instance - optional. */
2394 PFNPDMDRVDESTRUCT pfnDestruct;
2395 /** I/O control - optional. */
2396 PFNPDMDRVIOCTL pfnIOCtl;
2397 /** Power on notification - optional. */
2398 PFNPDMDRVPOWERON pfnPowerOn;
2399 /** Reset notification - optional. */
2400 PFNPDMDRVRESET pfnReset;
2401 /** Suspend notification - optional. */
2402 PFNPDMDRVSUSPEND pfnSuspend;
2403 /** Resume notification - optional. */
2404 PFNPDMDRVRESUME pfnResume;
2405 /** Detach notification - optional. */
2406 PFNPDMDRVDETACH pfnDetach;
2407 /** Power off notification - optional. */
2408 PFNPDMDRVPOWEROFF pfnPowerOff;
2409
2410} PDMDRVREG;
2411/** Pointer to a PDM Driver Structure. */
2412typedef PDMDRVREG *PPDMDRVREG;
2413/** Const pointer to a PDM Driver Structure. */
2414typedef PDMDRVREG const *PCPDMDRVREG;
2415
2416/** Current DRVREG version number. */
2417#define PDM_DRVREG_VERSION 0x80010000
2418
2419/** PDM Device Flags.
2420 * @{ */
2421/** @def PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT
2422 * The bit count for the current host. */
2423#if HC_ARCH_BITS == 32
2424# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT 0x000000001
2425#elif HC_ARCH_BITS == 64
2426# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT 0x000000002
2427#else
2428# error Unsupported HC_ARCH_BITS value.
2429#endif
2430/** The host bit count mask. */
2431#define PDM_DRVREG_FLAGS_HOST_BITS_MASK 0x000000003
2432
2433/** @} */
2434
2435
2436/** PDM Driver Classes.
2437 * @{ */
2438/** Mouse input driver. */
2439#define PDM_DRVREG_CLASS_MOUSE BIT(0)
2440/** Keyboard input driver. */
2441#define PDM_DRVREG_CLASS_KEYBOARD BIT(1)
2442/** Display driver. */
2443#define PDM_DRVREG_CLASS_DISPLAY BIT(2)
2444/** Network transport driver. */
2445#define PDM_DRVREG_CLASS_NETWORK BIT(3)
2446/** Block driver. */
2447#define PDM_DRVREG_CLASS_BLOCK BIT(4)
2448/** Media driver. */
2449#define PDM_DRVREG_CLASS_MEDIA BIT(5)
2450/** Mountable driver. */
2451#define PDM_DRVREG_CLASS_MOUNTABLE BIT(6)
2452/** Audio driver. */
2453#define PDM_DRVREG_CLASS_AUDIO BIT(7)
2454/** VMMDev driver. */
2455#define PDM_DRVREG_CLASS_VMMDEV BIT(8)
2456/** Status driver. */
2457#define PDM_DRVREG_CLASS_STATUS BIT(9)
2458/** ACPI driver. */
2459#define PDM_DRVREG_CLASS_ACPI BIT(10)
2460/** USB related driver. */
2461#define PDM_DRVREG_CLASS_USB BIT(11)
2462/** ISCSI Transport related driver. */
2463#define PDM_DRVREG_CLASS_ISCSITRANSPORT BIT(12)
2464/** Char driver. */
2465#define PDM_DRVREG_CLASS_CHAR BIT(13)
2466/** Stream driver. */
2467#define PDM_DRVREG_CLASS_STREAM BIT(14)
2468/** @} */
2469
2470
2471/**
2472 * Poller callback.
2473 *
2474 * @param pDrvIns The driver instance.
2475 */
2476typedef DECLCALLBACK(void) FNPDMDRVPOLLER(PPDMDRVINS pDrvIns);
2477/** Pointer to a FNPDMDRVPOLLER function. */
2478typedef FNPDMDRVPOLLER *PFNPDMDRVPOLLER;
2479
2480#ifdef IN_RING3
2481/**
2482 * PDM Driver API.
2483 */
2484typedef struct PDMDRVHLP
2485{
2486 /** Structure version. PDM_DRVHLP_VERSION defines the current version. */
2487 uint32_t u32Version;
2488
2489 /**
2490 * Attaches a driver (chain) to the driver.
2491 *
2492 * @returns VBox status code.
2493 * @param pDrvIns Driver instance.
2494 * @param ppBaseInterface Where to store the pointer to the base interface.
2495 */
2496 DECLR3CALLBACKMEMBER(int, pfnAttach,(PPDMDRVINS pDrvIns, PPDMIBASE *ppBaseInterface));
2497
2498 /**
2499 * Detach the driver the drivers below us.
2500 *
2501 * @returns VBox status code.
2502 * @param pDrvIns Driver instance.
2503 */
2504 DECLR3CALLBACKMEMBER(int, pfnDetach,(PPDMDRVINS pDrvIns));
2505
2506 /**
2507 * Detach the driver from the driver above it and destroy this
2508 * driver and all drivers below it.
2509 *
2510 * @returns VBox status code.
2511 * @param pDrvIns Driver instance.
2512 */
2513 DECLR3CALLBACKMEMBER(int, pfnDetachSelf,(PPDMDRVINS pDrvIns));
2514
2515 /**
2516 * Prepare a media mount.
2517 *
2518 * The driver must not have anything attached to itself
2519 * when calling this function as the purpose is to set up the configuration
2520 * of an future attachment.
2521 *
2522 * @returns VBox status code
2523 * @param pDrvIns Driver instance.
2524 * @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have
2525 * constructed a configuration which can be attached to the bottom driver.
2526 * @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.
2527 */
2528 DECLR3CALLBACKMEMBER(int, pfnMountPrepare,(PPDMDRVINS pDrvIns, const char *pszFilename, const char *pszCoreDriver));
2529
2530 /**
2531 * Assert that the current thread is the emulation thread.
2532 *
2533 * @returns True if correct.
2534 * @returns False if wrong.
2535 * @param pDrvIns Driver instance.
2536 * @param pszFile Filename of the assertion location.
2537 * @param iLine Linenumber of the assertion location.
2538 * @param pszFunction Function of the assertion location.
2539 */
2540 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
2541
2542 /**
2543 * Assert that the current thread is NOT the emulation thread.
2544 *
2545 * @returns True if correct.
2546 * @returns False if wrong.
2547 * @param pDrvIns Driver instance.
2548 * @param pszFile Filename of the assertion location.
2549 * @param iLine Linenumber of the assertion location.
2550 * @param pszFunction Function of the assertion location.
2551 */
2552 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
2553
2554 /**
2555 * Set the VM error message
2556 *
2557 * @returns rc.
2558 * @param pDrvIns Driver instance.
2559 * @param rc VBox status code.
2560 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
2561 * @param pszFormat Error message format string.
2562 * @param ... Error message arguments.
2563 */
2564 DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
2565
2566 /**
2567 * Set the VM error message
2568 *
2569 * @returns rc.
2570 * @param pDrvIns Driver instance.
2571 * @param rc VBox status code.
2572 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
2573 * @param pszFormat Error message format string.
2574 * @param va Error message arguments.
2575 */
2576 DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
2577
2578 /**
2579 * Set the VM runtime error message
2580 *
2581 * @returns VBox status code.
2582 * @param pDrvIns Driver instance.
2583 * @param fFatal Whether it is a fatal error or not.
2584 * @param pszErrorID Error ID string.
2585 * @param pszFormat Error message format string.
2586 * @param ... Error message arguments.
2587 */
2588 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDRVINS pDrvIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));
2589
2590 /**
2591 * Set the VM runtime error message
2592 *
2593 * @returns VBox status code.
2594 * @param pDrvIns Driver instance.
2595 * @param fFatal Whether it is a fatal error or not.
2596 * @param pszErrorID Error ID string.
2597 * @param pszFormat Error message format string.
2598 * @param va Error message arguments.
2599 */
2600 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDRVINS pDrvIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));
2601
2602 /**
2603 * Create a queue.
2604 *
2605 * @returns VBox status code.
2606 * @param pDrvIns Driver instance.
2607 * @param cbItem Size a queue item.
2608 * @param cItems Number of items in the queue.
2609 * @param cMilliesInterval Number of milliseconds between polling the queue.
2610 * If 0 then the emulation thread will be notified whenever an item arrives.
2611 * @param pfnCallback The consumer function.
2612 * @param ppQueue Where to store the queue handle on success.
2613 * @thread The emulation thread.
2614 */
2615 DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, PFNPDMQUEUEDRV pfnCallback, PPDMQUEUE *ppQueue));
2616
2617 /**
2618 * Register a poller function.
2619 * TEMPORARY HACK FOR NETWORKING! DON'T USE!
2620 *
2621 * @returns VBox status code.
2622 * @param pDrvIns Driver instance.
2623 * @param pfnPoller The callback function.
2624 */
2625 DECLR3CALLBACKMEMBER(int, pfnPDMPollerRegister,(PPDMDRVINS pDrvIns, PFNPDMDRVPOLLER pfnPoller));
2626
2627 /**
2628 * Query the virtual timer frequency.
2629 *
2630 * @returns Frequency in Hz.
2631 * @param pDrvIns Driver instance.
2632 * @thread Any thread.
2633 */
2634 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualFreq,(PPDMDRVINS pDrvIns));
2635
2636 /**
2637 * Query the virtual time.
2638 *
2639 * @returns The current virtual time.
2640 * @param pDrvIns Driver instance.
2641 * @thread Any thread.
2642 */
2643 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualTime,(PPDMDRVINS pDrvIns));
2644
2645 /**
2646 * Creates a timer.
2647 *
2648 * @returns VBox status.
2649 * @param pDrvIns Driver instance.
2650 * @param enmClock The clock to use on this timer.
2651 * @param pfnCallback Callback function.
2652 * @param pszDesc Pointer to description string which must stay around
2653 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
2654 * @param ppTimer Where to store the timer on success.
2655 */
2656 DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDRVINS pDrvIns, TMCLOCK enmClock, PFNTMTIMERDRV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer));
2657
2658 /**
2659 * Register a save state data unit.
2660 *
2661 * @returns VBox status.
2662 * @param pDrvIns Driver instance.
2663 * @param pszName Data unit name.
2664 * @param u32Instance The instance identifier of the data unit.
2665 * This must together with the name be unique.
2666 * @param u32Version Data layout version number.
2667 * @param cbGuess The approximate amount of data in the unit.
2668 * Only for progress indicators.
2669 * @param pfnSavePrep Prepare save callback, optional.
2670 * @param pfnSaveExec Execute save callback, optional.
2671 * @param pfnSaveDone Done save callback, optional.
2672 * @param pfnLoadPrep Prepare load callback, optional.
2673 * @param pfnLoadExec Execute load callback, optional.
2674 * @param pfnLoadDone Done load callback, optional.
2675 */
2676 DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
2677 PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
2678 PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone));
2679
2680 /**
2681 * Deregister a save state data unit.
2682 *
2683 * @returns VBox status.
2684 * @param pDrvIns Driver instance.
2685 * @param pszName Data unit name.
2686 * @param u32Instance The instance identifier of the data unit.
2687 * This must together with the name be unique.
2688 */
2689 DECLR3CALLBACKMEMBER(int, pfnSSMDeregister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance));
2690
2691 /**
2692 * Registers a statistics sample if statistics are enabled.
2693 *
2694 * @param pDrvIns Driver instance.
2695 * @param pvSample Pointer to the sample.
2696 * @param enmType Sample type. This indicates what pvSample is pointing at.
2697 * @param pszName Sample name. The name is on this form "/<component>/<sample>".
2698 * Further nesting is possible.
2699 * @param enmUnit Sample unit.
2700 * @param pszDesc Sample description.
2701 */
2702 DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName,
2703 STAMUNIT enmUnit, const char *pszDesc));
2704
2705 /**
2706 * Same as pfnSTAMRegister except that the name is specified in a
2707 * RTStrPrintf like fashion.
2708 *
2709 * @returns VBox status.
2710 * @param pDrvIns Driver instance.
2711 * @param pvSample Pointer to the sample.
2712 * @param enmType Sample type. This indicates what pvSample is pointing at.
2713 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
2714 * @param enmUnit Sample unit.
2715 * @param pszDesc Sample description.
2716 * @param pszName The sample name format string.
2717 * @param ... Arguments to the format string.
2718 */
2719 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
2720 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, ...));
2721
2722 /**
2723 * Same as pfnSTAMRegister except that the name is specified in a
2724 * RTStrPrintfV like fashion.
2725 *
2726 * @returns VBox status.
2727 * @param pDrvIns Driver instance.
2728 * @param pvSample Pointer to the sample.
2729 * @param enmType Sample type. This indicates what pvSample is pointing at.
2730 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
2731 * @param enmUnit Sample unit.
2732 * @param pszDesc Sample description.
2733 * @param pszName The sample name format string.
2734 * @param args Arguments to the format string.
2735 */
2736 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
2737 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list args));
2738
2739 /**
2740 * Calls the HC R0 VMM entry point, in a safer but slower manner than SUPCallVMMR0.
2741 * When entering using this call the R0 components can call into the host kernel
2742 * (i.e. use the SUPR0 and RT APIs).
2743 *
2744 * See VMMR0Entry() for more details.
2745 *
2746 * @returns error code specific to uFunction.
2747 * @param pDrvIns The driver instance.
2748 * @param uOperation Operation to execute.
2749 * This is limited to services.
2750 * @param pvArg Pointer to argument structure or if cbArg is 0 just an value.
2751 * @param cbArg The size of the argument. This is used to copy whatever the argument
2752 * points at into a kernel buffer to avoid problems like the user page
2753 * being invalidated while we're executing the call.
2754 */
2755 DECLR3CALLBACKMEMBER(int, pfnSUPCallVMMR0Ex,(PPDMDRVINS pDrvIns, unsigned uOperation, void *pvArg, unsigned cbArg));
2756
2757 /** Just a safety precaution. */
2758 uint32_t u32TheEnd;
2759} PDMDRVHLP;
2760/** Pointer PDM Driver API. */
2761typedef PDMDRVHLP *PPDMDRVHLP;
2762/** Pointer const PDM Driver API. */
2763typedef const PDMDRVHLP *PCPDMDRVHLP;
2764
2765/** Current DRVHLP version number. */
2766#define PDM_DRVHLP_VERSION 0x90010000
2767
2768
2769
2770/**
2771 * PDM Driver Instance.
2772 */
2773typedef struct PDMDRVINS
2774{
2775 /** Structure version. PDM_DRVINS_VERSION defines the current version. */
2776 uint32_t u32Version;
2777
2778 /** Internal data. */
2779 union
2780 {
2781#ifdef PDMDRVINSINT_DECLARED
2782 PDMDRVINSINT s;
2783#endif
2784 uint8_t padding[HC_ARCH_BITS == 32 ? 32 : 64];
2785 } Internal;
2786
2787 /** Pointer the PDM Driver API. */
2788 HCPTRTYPE(PCPDMDRVHLP) pDrvHlp;
2789 /** Pointer to driver registration structure. */
2790 HCPTRTYPE(PCPDMDRVREG) pDrvReg;
2791 /** Configuration handle. */
2792 HCPTRTYPE(PCFGMNODE) pCfgHandle;
2793 /** Driver instance number. */
2794 RTUINT iInstance;
2795 /** Pointer to the base interface of the device/driver instance above. */
2796 HCPTRTYPE(PPDMIBASE) pUpBase;
2797 /** Pointer to the base interface of the driver instance below. */
2798 HCPTRTYPE(PPDMIBASE) pDownBase;
2799 /** The base interface of the driver.
2800 * The driver constructor initializes this. */
2801 PDMIBASE IBase;
2802 /* padding to make achInstanceData aligned at 16 byte boundrary. */
2803 uint32_t au32Padding[HC_ARCH_BITS == 32 ? 3 : 1];
2804 /** Pointer to driver instance data. */
2805 HCPTRTYPE(void *) pvInstanceData;
2806 /** Driver instance data. The size of this area is defined
2807 * in the PDMDRVREG::cbInstanceData field. */
2808 char achInstanceData[4];
2809} PDMDRVINS;
2810
2811/** Current DRVREG version number. */
2812#define PDM_DRVINS_VERSION 0xa0010000
2813
2814/** Converts a pointer to the PDMDRVINS::IBase to a pointer to PDMDRVINS. */
2815#define PDMIBASE_2_PDMDRV(pInterface) ( (PPDMDRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDRVINS, IBase)) )
2816
2817/**
2818 * @copydoc PDMDRVHLP::pfnVMSetError
2819 */
2820DECLINLINE(int) PDMDrvHlpVMSetError(PPDMDRVINS pDrvIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
2821{
2822 va_list va;
2823 va_start(va, pszFormat);
2824 pDrvIns->pDrvHlp->pfnVMSetErrorV(pDrvIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
2825 va_end(va);
2826 return rc;
2827}
2828
2829/** @def PDMDRV_SET_ERROR
2830 * Set the VM error. See PDMDrvHlpVMSetError() for printf like message formatting.
2831 */
2832#define PDMDRV_SET_ERROR(pDrvIns, rc, pszError) \
2833 PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, "%s", pszError)
2834
2835/**
2836 * @copydoc PDMDRVHLP::pfnVMSetRuntimeError
2837 */
2838DECLINLINE(int) PDMDrvHlpVMSetRuntimeError(PPDMDRVINS pDrvIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...)
2839{
2840 va_list va;
2841 int rc;
2842 va_start(va, pszFormat);
2843 rc = pDrvIns->pDrvHlp->pfnVMSetRuntimeErrorV(pDrvIns, fFatal, pszErrorID, pszFormat, va);
2844 va_end(va);
2845 return rc;
2846}
2847
2848/** @def PDMDRV_SET_RUNTIME_ERROR
2849 * Set the VM runtime error. See PDMDrvHlpVMSetRuntimeError() for printf like message formatting.
2850 */
2851#define PDMDRV_SET_RUNTIME_ERROR(pDrvIns, fFatal, pszErrorID, pszError) \
2852 PDMDrvHlpVMSetError(pDrvIns, fFatal, pszErrorID, "%s", pszError)
2853
2854#endif /* IN_RING3 */
2855
2856
2857/** @def PDMDRV_ASSERT_EMT
2858 * Assert that the current thread is the emulation thread.
2859 */
2860#ifdef VBOX_STRICT
2861# define PDMDRV_ASSERT_EMT(pDrvIns) pDrvIns->pDrvHlp->pfnAssertEMT(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
2862#else
2863# define PDMDRV_ASSERT_EMT(pDrvIns) do { } while (0)
2864#endif
2865
2866/** @def PDMDRV_ASSERT_OTHER
2867 * Assert that the current thread is NOT the emulation thread.
2868 */
2869#ifdef VBOX_STRICT
2870# define PDMDRV_ASSERT_OTHER(pDrvIns) pDrvIns->pDrvHlp->pfnAssertOther(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
2871#else
2872# define PDMDRV_ASSERT_OTHER(pDrvIns) do { } while (0)
2873#endif
2874
2875
2876#ifdef IN_RING3
2877/**
2878 * @copydoc PDMDRVHLP::pfnSTAMRegister
2879 */
2880DECLINLINE(void) PDMDrvHlpSTAMRegister(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
2881{
2882 pDrvIns->pDrvHlp->pfnSTAMRegister(pDrvIns, pvSample, enmType, pszName, enmUnit, pszDesc);
2883}
2884
2885/**
2886 * @copydoc PDMDRVHLP::pfnSTAMRegisterF
2887 */
2888DECLINLINE(void) PDMDrvHlpSTAMRegisterF(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
2889 const char *pszDesc, const char *pszName, ...)
2890{
2891 va_list va;
2892 va_start(va, pszName);
2893 pDrvIns->pDrvHlp->pfnSTAMRegisterV(pDrvIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
2894 va_end(va);
2895}
2896#endif /* IN_RING3 */
2897
2898
2899
2900/** Pointer to callbacks provided to the VBoxDriverRegister() call. */
2901typedef struct PDMDRVREGCB *PPDMDRVREGCB;
2902/** Pointer to const callbacks provided to the VBoxDriverRegister() call. */
2903typedef const struct PDMDRVREGCB *PCPDMDRVREGCB;
2904
2905/**
2906 * Callbacks for VBoxDriverRegister().
2907 */
2908typedef struct PDMDRVREGCB
2909{
2910 /** Interface version.
2911 * This is set to PDM_DRVREG_CB_VERSION. */
2912 uint32_t u32Version;
2913
2914 /**
2915 * Registers a driver with the current VM instance.
2916 *
2917 * @returns VBox status code.
2918 * @param pCallbacks Pointer to the callback table.
2919 * @param pDrvReg Pointer to the driver registration record.
2920 * This data must be permanent and readonly.
2921 */
2922 DECLR3CALLBACKMEMBER(int, pfnRegister,(PCPDMDRVREGCB pCallbacks, PCPDMDRVREG pDrvReg));
2923} PDMDRVREGCB;
2924
2925/** Current version of the PDMDRVREGCB structure. */
2926#define PDM_DRVREG_CB_VERSION 0xb0010000
2927
2928
2929/**
2930 * The VBoxDriverRegister callback function.
2931 *
2932 * PDM will invoke this function after loading a driver module and letting
2933 * the module decide which drivers to register and how to handle conflicts.
2934 *
2935 * @returns VBox status code.
2936 * @param pCallbacks Pointer to the callback table.
2937 * @param u32Version VBox version number.
2938 */
2939typedef DECLCALLBACK(int) FNPDMVBOXDRIVERSREGISTER(PCPDMDRVREGCB pCallbacks, uint32_t u32Version);
2940
2941/**
2942 * Register external drivers
2943 *
2944 * @returns VBox status code.
2945 * @param pVM The VM to operate on.
2946 * @param pfnCallback Driver registration callback
2947 */
2948PDMR3DECL(int) PDMR3RegisterDrivers(PVM pVM, FNPDMVBOXDRIVERSREGISTER pfnCallback);
2949
2950/** @} */
2951
2952
2953
2954
2955/** @defgroup grp_pdm_device Devices
2956 * @ingroup grp_pdm
2957 * @{
2958 */
2959
2960
2961/** @def PDMBOTHCBDECL
2962 * Macro for declaring a callback which is static in HC and exported in GC.
2963 */
2964#if defined(IN_GC) || defined(IN_RING0)
2965# define PDMBOTHCBDECL(type) DECLEXPORT(type)
2966#else
2967# define PDMBOTHCBDECL(type) static type
2968#endif
2969
2970
2971/**
2972 * Construct a device instance for a VM.
2973 *
2974 * @returns VBox status.
2975 * @param pDevIns The device instance data.
2976 * If the registration structure is needed, pDevIns->pDevReg points to it.
2977 * @param iInstance Instance number. Use this to figure out which registers and such to use.
2978 * The instance number is also found in pDevIns->iInstance, but since it's
2979 * likely to be freqently used PDM passes it as parameter.
2980 * @param pCfgHandle Configuration node handle for the device. Use this to obtain the configuration
2981 * of the device instance. It's also found in pDevIns->pCfgHandle, but since it's
2982 * primary usage will in this function it's passed as a parameter.
2983 */
2984typedef DECLCALLBACK(int) FNPDMDEVCONSTRUCT(PPDMDEVINS pDevIns, int iInstance, PCFGMNODE pCfgHandle);
2985/** Pointer to a FNPDMDEVCONSTRUCT() function. */
2986typedef FNPDMDEVCONSTRUCT *PFNPDMDEVCONSTRUCT;
2987
2988/**
2989 * Destruct a device instance.
2990 *
2991 * Most VM resources are freed by the VM. This callback is provided so that any non-VM
2992 * resources can be freed correctly.
2993 *
2994 * @returns VBox status.
2995 * @param pDevIns The device instance data.
2996 */
2997typedef DECLCALLBACK(int) FNPDMDEVDESTRUCT(PPDMDEVINS pDevIns);
2998/** Pointer to a FNPDMDEVDESTRUCT() function. */
2999typedef FNPDMDEVDESTRUCT *PFNPDMDEVDESTRUCT;
3000
3001/**
3002 * Device relocation callback.
3003 *
3004 * When this callback is called the device instance data, and if the
3005 * device have a GC component, is being relocated, or/and the selectors
3006 * have been changed. The device must use the chance to perform the
3007 * necessary pointer relocations and data updates.
3008 *
3009 * Before the GC code is executed the first time, this function will be
3010 * called with a 0 delta so GC pointer calculations can be one in one place.
3011 *
3012 * @param pDevIns Pointer to the device instance.
3013 * @param offDelta The relocation delta relative to the old location.
3014 *
3015 * @remark A relocation CANNOT fail.
3016 */
3017typedef DECLCALLBACK(void) FNPDMDEVRELOCATE(PPDMDEVINS pDevIns, RTGCINTPTR offDelta);
3018/** Pointer to a FNPDMDEVRELOCATE() function. */
3019typedef FNPDMDEVRELOCATE *PFNPDMDEVRELOCATE;
3020
3021
3022/**
3023 * Device I/O Control interface.
3024 *
3025 * This is used by external components, such as the COM interface, to
3026 * communicate with devices using a class wide interface or a device
3027 * specific interface.
3028 *
3029 * @returns VBox status code.
3030 * @param pDevIns Pointer to the device instance.
3031 * @param uFunction Function to perform.
3032 * @param pvIn Pointer to input data.
3033 * @param cbIn Size of input data.
3034 * @param pvOut Pointer to output data.
3035 * @param cbOut Size of output data.
3036 * @param pcbOut Where to store the actual size of the output data.
3037 */
3038typedef DECLCALLBACK(int) FNPDMDEVIOCTL(PPDMDEVINS pDevIns, RTUINT uFunction,
3039 void *pvIn, RTUINT cbIn,
3040 void *pvOut, RTUINT cbOut, PRTUINT pcbOut);
3041/** Pointer to a FNPDMDEVIOCTL() function. */
3042typedef FNPDMDEVIOCTL *PFNPDMDEVIOCTL;
3043
3044/**
3045 * Power On notification.
3046 *
3047 * @returns VBox status.
3048 * @param pDevIns The device instance data.
3049 */
3050typedef DECLCALLBACK(void) FNPDMDEVPOWERON(PPDMDEVINS pDevIns);
3051/** Pointer to a FNPDMDEVPOWERON() function. */
3052typedef FNPDMDEVPOWERON *PFNPDMDEVPOWERON;
3053
3054/**
3055 * Reset notification.
3056 *
3057 * @returns VBox status.
3058 * @param pDevIns The device instance data.
3059 */
3060typedef DECLCALLBACK(void) FNPDMDEVRESET(PPDMDEVINS pDevIns);
3061/** Pointer to a FNPDMDEVRESET() function. */
3062typedef FNPDMDEVRESET *PFNPDMDEVRESET;
3063
3064/**
3065 * Suspend notification.
3066 *
3067 * @returns VBox status.
3068 * @param pDevIns The device instance data.
3069 */
3070typedef DECLCALLBACK(void) FNPDMDEVSUSPEND(PPDMDEVINS pDevIns);
3071/** Pointer to a FNPDMDEVSUSPEND() function. */
3072typedef FNPDMDEVSUSPEND *PFNPDMDEVSUSPEND;
3073
3074/**
3075 * Resume notification.
3076 *
3077 * @returns VBox status.
3078 * @param pDevIns The device instance data.
3079 */
3080typedef DECLCALLBACK(void) FNPDMDEVRESUME(PPDMDEVINS pDevIns);
3081/** Pointer to a FNPDMDEVRESUME() function. */
3082typedef FNPDMDEVRESUME *PFNPDMDEVRESUME;
3083
3084/**
3085 * Power Off notification.
3086 *
3087 * @param pDevIns The device instance data.
3088 */
3089typedef DECLCALLBACK(void) FNPDMDEVPOWEROFF(PPDMDEVINS pDevIns);
3090/** Pointer to a FNPDMDEVPOWEROFF() function. */
3091typedef FNPDMDEVPOWEROFF *PFNPDMDEVPOWEROFF;
3092
3093/**
3094 * Attach command.
3095 *
3096 * This is called to let the device attach to a driver for a specified LUN
3097 * during runtime. This is not called during VM construction, the device
3098 * constructor have to attach to all the available drivers.
3099 *
3100 * This is like plugging in the keyboard or mouse after turning on the PC.
3101 *
3102 * @returns VBox status code.
3103 * @param pDevIns The device instance.
3104 * @param iLUN The logical unit which is being detached.
3105 */
3106typedef DECLCALLBACK(int) FNPDMDEVATTACH(PPDMDEVINS pDevIns, unsigned iLUN);
3107/** Pointer to a FNPDMDEVATTACH() function. */
3108typedef FNPDMDEVATTACH *PFNPDMDEVATTACH;
3109
3110/**
3111 * Detach notification.
3112 *
3113 * This is called when a driver is detaching itself from a LUN of the device.
3114 * The device should adjust it's state to reflect this.
3115 *
3116 * This is like unplugging the network cable to use it for the laptop or
3117 * something while the PC is still running.
3118 *
3119 * @param pDevIns The device instance.
3120 * @param iLUN The logical unit which is being detached.
3121 */
3122typedef DECLCALLBACK(void) FNPDMDEVDETACH(PPDMDEVINS pDevIns, unsigned iLUN);
3123/** Pointer to a FNPDMDEVDETACH() function. */
3124typedef FNPDMDEVDETACH *PFNPDMDEVDETACH;
3125
3126/**
3127 * Query the base interface of a logical unit.
3128 *
3129 * @returns VBOX status code.
3130 * @param pDevIns The device instance.
3131 * @param iLUN The logicial unit to query.
3132 * @param ppBase Where to store the pointer to the base interface of the LUN.
3133 */
3134typedef DECLCALLBACK(int) FNPDMDEVQUERYINTERFACE(PPDMDEVINS pDevIns, unsigned iLUN, PPDMIBASE *ppBase);
3135/** Pointer to a FNPDMDEVQUERYINTERFACE() function. */
3136typedef FNPDMDEVQUERYINTERFACE *PFNPDMDEVQUERYINTERFACE;
3137
3138/**
3139 * Init complete notification.
3140 * This can be done to do communication with other devices and other
3141 * initialization which requires everything to be in place.
3142 *
3143 * @returns VBOX status code.
3144 * @param pDevIns The device instance.
3145 */
3146typedef DECLCALLBACK(int) FNPDMDEVINITCOMPLETE(PPDMDEVINS pDevIns);
3147/** Pointer to a FNPDMDEVINITCOMPLETE() function. */
3148typedef FNPDMDEVINITCOMPLETE *PFNPDMDEVINITCOMPLETE;
3149
3150
3151
3152/** PDM Device Registration Structure,
3153 * This structure is used when registering a device from
3154 * VBoxInitDevices() in HC Ring-3. PDM will continue use till
3155 * the VM is terminated.
3156 */
3157typedef struct PDMDEVREG
3158{
3159 /** Structure version. PDM_DEVREG_VERSION defines the current version. */
3160 uint32_t u32Version;
3161 /** Device name. */
3162 char szDeviceName[32];
3163 /** Name of guest context module (no path).
3164 * Only evalutated if PDM_DEVREG_FLAGS_GC is set. */
3165 char szGCMod[32];
3166 /** Name of guest context module (no path).
3167 * Only evalutated if PDM_DEVREG_FLAGS_GC is set. */
3168 char szR0Mod[32];
3169 /** The description of the device. The UTF-8 string pointed to shall, like this structure,
3170 * remain unchanged from registration till VM destruction. */
3171 const char *pszDescription;
3172
3173 /** Flags, combination of the PDM_DEVREG_FLAGS_* \#defines. */
3174 RTUINT fFlags;
3175 /** Device class(es), combination of the PDM_DEVREG_CLASS_* \#defines. */
3176 RTUINT fClass;
3177 /** Maximum number of instances (per VM). */
3178 RTUINT cMaxInstances;
3179 /** Size of the instance data. */
3180 RTUINT cbInstance;
3181
3182 /** Construct instance - required. */
3183 PFNPDMDEVCONSTRUCT pfnConstruct;
3184 /** Destruct instance - optional. */
3185 PFNPDMDEVDESTRUCT pfnDestruct;
3186 /** Relocation command - optional. */
3187 PFNPDMDEVRELOCATE pfnRelocate;
3188 /** I/O Control interface - optional. */
3189 PFNPDMDEVIOCTL pfnIOCtl;
3190 /** Power on notification - optional. */
3191 PFNPDMDEVPOWERON pfnPowerOn;
3192 /** Reset notification - optional. */
3193 PFNPDMDEVRESET pfnReset;
3194 /** Suspend notification - optional. */
3195 PFNPDMDEVSUSPEND pfnSuspend;
3196 /** Resume notification - optional. */
3197 PFNPDMDEVRESUME pfnResume;
3198 /** Attach command - optional. */
3199 PFNPDMDEVATTACH pfnAttach;
3200 /** Detach notification - optional. */
3201 PFNPDMDEVDETACH pfnDetach;
3202 /** Query a LUN base interface - optional. */
3203 PFNPDMDEVQUERYINTERFACE pfnQueryInterface;
3204 /** Init complete notification - optional. */
3205 PFNPDMDEVINITCOMPLETE pfnInitComplete;
3206 /** Power off notification - optional. */
3207 PFNPDMDEVPOWEROFF pfnPowerOff;
3208} PDMDEVREG;
3209/** Pointer to a PDM Device Structure. */
3210typedef PDMDEVREG *PPDMDEVREG;
3211/** Const pointer to a PDM Device Structure. */
3212typedef PDMDEVREG const *PCPDMDEVREG;
3213
3214/** Current DEVREG version number. */
3215#define PDM_DEVREG_VERSION 0xc0010000
3216
3217/** PDM Device Flags.
3218 * @{ */
3219/** This flag is used to indicate that the device has a GC component. */
3220#define PDM_DEVREG_FLAGS_GC 0x00000001
3221/** This flag is used to indicate that the device has a R0 component. */
3222#define PDM_DEVREG_FLAGS_R0 0x00010000
3223
3224/** @def PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT
3225 * The bit count for the current host. */
3226#if HC_ARCH_BITS == 32
3227# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT 0x00000002
3228#elif HC_ARCH_BITS == 64
3229# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT 0x00000004
3230#else
3231# error Unsupported HC_ARCH_BITS value.
3232#endif
3233/** The host bit count mask. */
3234#define PDM_DEVREG_FLAGS_HOST_BITS_MASK 0x00000006
3235
3236/** The device support only 32-bit guests. */
3237#define PDM_DEVREG_FLAGS_GUEST_BITS_32 0x00000008
3238/** The device support only 64-bit guests. */
3239#define PDM_DEVREG_FLAGS_GUEST_BITS_64 0x00000010
3240/** The device support both 32-bit & 64-bit guests. */
3241#define PDM_DEVREG_FLAGS_GUEST_BITS_32_64 0x00000018
3242/** @def PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT
3243 * The guest bit count for the current compilation. */
3244#if GC_ARCH_BITS == 32
3245# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_32
3246#elif GC_ARCH_BITS == 64
3247# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_64
3248#else
3249# error Unsupported GC_ARCH_BITS value.
3250#endif
3251/** The guest bit count mask. */
3252#define PDM_DEVREG_FLAGS_GUEST_BITS_MASK 0x00000018
3253
3254/** Indicates that the devices support PAE36 on a 32-bit guest. */
3255#define PDM_DEVREG_FLAGS_PAE36 0x00000020
3256/** @} */
3257
3258
3259/** PDM Device Classes.
3260 * The order is important, lower bit earlier instantiation.
3261 * @{ */
3262/** Architecture device. */
3263#define PDM_DEVREG_CLASS_ARCH BIT(0)
3264/** Architecture BIOS device. */
3265#define PDM_DEVREG_CLASS_ARCH_BIOS BIT(1)
3266/** PCI bus brigde. */
3267#define PDM_DEVREG_CLASS_BUS_PCI BIT(2)
3268/** ISA bus brigde. */
3269#define PDM_DEVREG_CLASS_BUS_ISA BIT(3)
3270/** Input device (mouse, keyboard, joystick,..). */
3271#define PDM_DEVREG_CLASS_INPUT BIT(4)
3272/** Interrupt controller (PIC). */
3273#define PDM_DEVREG_CLASS_PIC BIT(5)
3274/** Interval controoler (PIT). */
3275#define PDM_DEVREG_CLASS_PIT BIT(6)
3276/** RTC/CMOS. */
3277#define PDM_DEVREG_CLASS_RTC BIT(7)
3278/** DMA controller. */
3279#define PDM_DEVREG_CLASS_DMA BIT(8)
3280/** VMM Device. */
3281#define PDM_DEVREG_CLASS_VMM_DEV BIT(9)
3282/** Graphics device, like VGA. */
3283#define PDM_DEVREG_CLASS_GRAPHICS BIT(10)
3284/** Storage controller device. */
3285#define PDM_DEVREG_CLASS_STORAGE BIT(11)
3286/** Network interface controller. */
3287#define PDM_DEVREG_CLASS_NETWORK BIT(12)
3288/** Audio. */
3289#define PDM_DEVREG_CLASS_AUDIO BIT(13)
3290/** USB bus? */
3291#define PDM_DEVREG_CLASS_BUS_USB BIT(14) /* ??? */
3292/** ACPI. */
3293#define PDM_DEVREG_CLASS_ACPI BIT(15)
3294/** Serial controller device. */
3295#define PDM_DEVREG_CLASS_SERIAL BIT(16)
3296/** Misc devices (always last). */
3297#define PDM_DEVREG_CLASS_MISC BIT(31)
3298/** @} */
3299
3300
3301/** @name IRQ Level for use with the *SetIrq APIs.
3302 * @{
3303 */
3304/** Assert the IRQ (can assume value 1). */
3305#define PDM_IRQ_LEVEL_HIGH BIT(0)
3306/** Deassert the IRQ (can assume value 0). */
3307#define PDM_IRQ_LEVEL_LOW 0
3308/** flip-flop - assert and then deassert it again immediately. */
3309#define PDM_IRQ_LEVEL_FLIP_FLOP (BIT(1) | PDM_IRQ_LEVEL_HIGH)
3310/** @} */
3311
3312
3313/**
3314 * PCI Bus registaration structure.
3315 * All the callbacks, except the PCIBIOS hack, are working on PCI devices.
3316 */
3317typedef struct PDMPCIBUSREG
3318{
3319 /** Structure version number. PDM_PCIBUSREG_VERSION defines the current version. */
3320 uint32_t u32Version;
3321
3322 /**
3323 * Registers the device with the default PCI bus.
3324 *
3325 * @returns VBox status code.
3326 * @param pDevIns Device instance of the PCI Bus.
3327 * @param pPciDev The PCI device structure.
3328 * Any PCI enabled device must keep this in it's instance data!
3329 * Fill in the PCI data config before registration, please.
3330 * @param pszName Pointer to device name (permanent, readonly). For debugging, not unique.
3331 * @param iDev The device number ((dev << 3) | function) the device should have on the bus.
3332 * If negative, the pci bus device will assign one.
3333 */
3334 DECLR3CALLBACKMEMBER(int, pfnRegisterHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, const char *pszName, int iDev));
3335
3336 /**
3337 * Registers a I/O region (memory mapped or I/O ports) for a PCI device.
3338 *
3339 * @returns VBox status code.
3340 * @param pDevIns Device instance of the PCI Bus.
3341 * @param pPciDev The PCI device structure.
3342 * @param iRegion The region number.
3343 * @param cbRegion Size of the region.
3344 * @param iType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
3345 * @param pfnCallback Callback for doing the mapping.
3346 */
3347 DECLR3CALLBACKMEMBER(int, pfnIORegionRegisterHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback));
3348
3349 /**
3350 * Register PCI configuration space read/write callbacks.
3351 *
3352 * @param pDevIns Device instance of the PCI Bus.
3353 * @param pPciDev The PCI device structure.
3354 * @param pfnRead Pointer to the user defined PCI config read function.
3355 * @param ppfnReadOld Pointer to function pointer which will receive the old (default)
3356 * PCI config read function. This way, user can decide when (and if)
3357 * to call default PCI config read function. Can be NULL.
3358 * @param pfnWrite Pointer to the user defined PCI config write function.
3359 * @param pfnWriteOld Pointer to function pointer which will receive the old (default)
3360 * PCI config write function. This way, user can decide when (and if)
3361 * to call default PCI config write function. Can be NULL.
3362 * @thread EMT
3363 */
3364 DECLR3CALLBACKMEMBER(void, pfnSetConfigCallbacksHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,
3365 PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld));
3366
3367 /**
3368 * Set the IRQ for a PCI device.
3369 *
3370 * @param pDevIns Device instance of the PCI Bus.
3371 * @param pPciDev The PCI device structure.
3372 * @param iIrq IRQ number to set.
3373 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3374 */
3375 DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iIrq, int iLevel));
3376
3377 /**
3378 * Saves a state of the PCI device.
3379 *
3380 * @returns VBox status code.
3381 * @param pDevIns Device instance of the PCI Bus.
3382 * @param pPciDev Pointer to PCI device.
3383 * @param pSSMHandle The handle to save the state to.
3384 */
3385 DECLR3CALLBACKMEMBER(int, pfnSaveExecHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PSSMHANDLE pSSMHandle));
3386
3387 /**
3388 * Loads a saved PCI device state.
3389 *
3390 * @returns VBox status code.
3391 * @param pDevIns Device instance of the PCI Bus.
3392 * @param pPciDev Pointer to PCI device.
3393 * @param pSSMHandle The handle to the saved state.
3394 */
3395 DECLR3CALLBACKMEMBER(int, pfnLoadExecHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PSSMHANDLE pSSMHandle));
3396
3397 /**
3398 * Called to perform the job of the bios.
3399 * This is only called for the first PCI Bus - it is expected to
3400 * service all the PCI buses.
3401 *
3402 * @returns VBox status.
3403 * @param pDevIns Device instance of the first bus.
3404 */
3405 DECLR3CALLBACKMEMBER(int, pfnFakePCIBIOSHC,(PPDMDEVINS pDevIns));
3406
3407 /** The name of the SetIrq GC entry point. */
3408 const char *pszSetIrqGC;
3409
3410 /** The name of the SetIrq R0 entry point. */
3411 const char *pszSetIrqR0;
3412
3413} PDMPCIBUSREG;
3414/** Pointer to a PCI bus registration structure. */
3415typedef PDMPCIBUSREG *PPDMPCIBUSREG;
3416
3417/** Current PDMPCIBUSREG version number. */
3418#define PDM_PCIBUSREG_VERSION 0xd0020000
3419
3420/**
3421 * PCI Bus GC helpers.
3422 */
3423typedef struct PDMPCIHLPGC
3424{
3425 /** Structure version. PDM_PCIHLPGC_VERSION defines the current version. */
3426 uint32_t u32Version;
3427
3428 /**
3429 * Set an ISA IRQ.
3430 *
3431 * @param pDevIns PCI device instance.
3432 * @param iIrq IRQ number to set.
3433 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3434 * @thread EMT only.
3435 */
3436 DECLGCCALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3437
3438 /**
3439 * Set an I/O-APIC IRQ.
3440 *
3441 * @param pDevIns PCI device instance.
3442 * @param iIrq IRQ number to set.
3443 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3444 * @thread EMT only.
3445 */
3446 DECLGCCALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3447
3448#ifdef VBOX_WITH_PDM_LOCK
3449 /**
3450 * Acquires the PDM lock.
3451 *
3452 * @returns VINF_SUCCESS on success.
3453 * @returns rc if we failed to acquire the lock.
3454 * @param pDevIns The PCI device instance.
3455 * @param rc What to return if we fail to acquire the lock.
3456 */
3457 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3458
3459 /**
3460 * Releases the PDM lock.
3461 *
3462 * @param pDevIns The PCI device instance.
3463 */
3464 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3465#endif
3466 /** Just a safety precaution. */
3467 uint32_t u32TheEnd;
3468} PDMPCIHLPGC;
3469/** Pointer to PCI helpers. */
3470typedef GCPTRTYPE(PDMPCIHLPGC *) PPDMPCIHLPGC;
3471/** Pointer to const PCI helpers. */
3472typedef GCPTRTYPE(const PDMPCIHLPGC *) PCPDMPCIHLPGC;
3473
3474/** Current PDMPCIHLPR3 version number. */
3475#define PDM_PCIHLPGC_VERSION 0xe1010000
3476
3477
3478/**
3479 * PCI Bus R0 helpers.
3480 */
3481typedef struct PDMPCIHLPR0
3482{
3483 /** Structure version. PDM_PCIHLPR0_VERSION defines the current version. */
3484 uint32_t u32Version;
3485
3486 /**
3487 * Set an ISA IRQ.
3488 *
3489 * @param pDevIns PCI device instance.
3490 * @param iIrq IRQ number to set.
3491 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3492 * @thread EMT only.
3493 */
3494 DECLR0CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3495
3496 /**
3497 * Set an I/O-APIC IRQ.
3498 *
3499 * @param pDevIns PCI device instance.
3500 * @param iIrq IRQ number to set.
3501 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3502 * @thread EMT only.
3503 */
3504 DECLR0CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3505
3506#ifdef VBOX_WITH_PDM_LOCK
3507 /**
3508 * Acquires the PDM lock.
3509 *
3510 * @returns VINF_SUCCESS on success.
3511 * @returns rc if we failed to acquire the lock.
3512 * @param pDevIns The PCI device instance.
3513 * @param rc What to return if we fail to acquire the lock.
3514 */
3515 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3516
3517 /**
3518 * Releases the PDM lock.
3519 *
3520 * @param pDevIns The PCI device instance.
3521 */
3522 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3523#endif
3524
3525 /** Just a safety precaution. */
3526 uint32_t u32TheEnd;
3527} PDMPCIHLPR0;
3528/** Pointer to PCI helpers. */
3529typedef R0PTRTYPE(PDMPCIHLPR0 *) PPDMPCIHLPR0;
3530/** Pointer to const PCI helpers. */
3531typedef R0PTRTYPE(const PDMPCIHLPR0 *) PCPDMPCIHLPR0;
3532
3533/** Current PDMPCIHLPR0 version number. */
3534#define PDM_PCIHLPR0_VERSION 0xe1010000
3535
3536/**
3537 * PCI device helpers.
3538 */
3539typedef struct PDMPCIHLPR3
3540{
3541 /** Structure version. PDM_PCIHLPR3_VERSION defines the current version. */
3542 uint32_t u32Version;
3543
3544 /**
3545 * Set an ISA IRQ.
3546 *
3547 * @param pDevIns The PCI device instance.
3548 * @param iIrq IRQ number to set.
3549 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3550 * @thread EMT only.
3551 */
3552 DECLR3CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3553
3554 /**
3555 * Set an I/O-APIC IRQ.
3556 *
3557 * @param pDevIns The PCI device instance.
3558 * @param iIrq IRQ number to set.
3559 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3560 * @thread EMT only.
3561 */
3562 DECLR3CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3563
3564#ifdef VBOX_WITH_PDM_LOCK
3565 /**
3566 * Acquires the PDM lock.
3567 *
3568 * @returns VINF_SUCCESS on success.
3569 * @returns Fatal error on failure.
3570 * @param pDevIns The PCI device instance.
3571 * @param rc Dummy for making the interface identical to the GC and R0 versions.
3572 */
3573 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3574
3575 /**
3576 * Releases the PDM lock.
3577 *
3578 * @param pDevIns The PCI device instance.
3579 */
3580 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3581#endif
3582
3583 /**
3584 * Gets the address of the GC PCI Bus helpers.
3585 *
3586 * This should be called at both construction and relocation time
3587 * to obtain the correct address of the GC helpers.
3588 *
3589 * @returns GC pointer to the PCI Bus helpers.
3590 * @param pDevIns Device instance of the PCI Bus.
3591 * @thread EMT only.
3592 */
3593 DECLR3CALLBACKMEMBER(PCPDMPCIHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
3594
3595 /**
3596 * Gets the address of the R0 PCI Bus helpers.
3597 *
3598 * This should be called at both construction and relocation time
3599 * to obtain the correct address of the GC helpers.
3600 *
3601 * @returns R0 pointer to the PCI Bus helpers.
3602 * @param pDevIns Device instance of the PCI Bus.
3603 * @thread EMT only.
3604 */
3605 DECLR3CALLBACKMEMBER(PCPDMPCIHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
3606
3607 /** Just a safety precaution. */
3608 uint32_t u32TheEnd;
3609} PDMPCIHLPR3;
3610/** Pointer to PCI helpers. */
3611typedef HCPTRTYPE(PDMPCIHLPR3 *) PPDMPCIHLPR3;
3612/** Pointer to const PCI helpers. */
3613typedef HCPTRTYPE(const PDMPCIHLPR3 *) PCPDMPCIHLPR3;
3614
3615/** Current PDMPCIHLPR3 version number. */
3616#define PDM_PCIHLPR3_VERSION 0xf1010000
3617
3618
3619/**
3620 * Programmable Interrupt Controller registration structure.
3621 */
3622typedef struct PDMPICREG
3623{
3624 /** Structure version number. PDM_PICREG_VERSION defines the current version. */
3625 uint32_t u32Version;
3626
3627 /**
3628 * Set the an IRQ.
3629 *
3630 * @param pDevIns Device instance of the PIC.
3631 * @param iIrq IRQ number to set.
3632 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3633 */
3634 DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3635
3636 /**
3637 * Get a pending interrupt.
3638 *
3639 * @returns Pending interrupt number.
3640 * @param pDevIns Device instance of the PIC.
3641 */
3642 DECLR3CALLBACKMEMBER(int, pfnGetInterruptHC,(PPDMDEVINS pDevIns));
3643
3644 /** The name of the GC SetIrq entry point. */
3645 const char *pszSetIrqGC;
3646 /** The name of the GC GetInterrupt entry point. */
3647 const char *pszGetInterruptGC;
3648
3649 /** The name of the R0 SetIrq entry point. */
3650 const char *pszSetIrqR0;
3651 /** The name of the R0 GetInterrupt entry point. */
3652 const char *pszGetInterruptR0;
3653} PDMPICREG;
3654/** Pointer to a PIC registration structure. */
3655typedef PDMPICREG *PPDMPICREG;
3656
3657/** Current PDMPICREG version number. */
3658#define PDM_PICREG_VERSION 0xe0020000
3659
3660/**
3661 * PIC GC helpers.
3662 */
3663typedef struct PDMPICHLPGC
3664{
3665 /** Structure version. PDM_PICHLPGC_VERSION defines the current version. */
3666 uint32_t u32Version;
3667
3668 /**
3669 * Set the interrupt force action flag.
3670 *
3671 * @param pDevIns Device instance of the PIC.
3672 */
3673 DECLGCCALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
3674
3675 /**
3676 * Clear the interrupt force action flag.
3677 *
3678 * @param pDevIns Device instance of the PIC.
3679 */
3680 DECLGCCALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
3681
3682#ifdef VBOX_WITH_PDM_LOCK
3683 /**
3684 * Acquires the PDM lock.
3685 *
3686 * @returns VINF_SUCCESS on success.
3687 * @returns rc if we failed to acquire the lock.
3688 * @param pDevIns The PIC device instance.
3689 * @param rc What to return if we fail to acquire the lock.
3690 */
3691 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3692
3693 /**
3694 * Releases the PDM lock.
3695 *
3696 * @param pDevIns The PIC device instance.
3697 */
3698 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3699#endif
3700 /** Just a safety precaution. */
3701 uint32_t u32TheEnd;
3702} PDMPICHLPGC;
3703
3704/** Pointer to PIC GC helpers. */
3705typedef GCPTRTYPE(PDMPICHLPGC *) PPDMPICHLPGC;
3706/** Pointer to const PIC GC helpers. */
3707typedef GCPTRTYPE(const PDMPICHLPGC *) PCPDMPICHLPGC;
3708
3709/** Current PDMPICHLPGC version number. */
3710#define PDM_PICHLPGC_VERSION 0xfc010000
3711
3712
3713/**
3714 * PIC R0 helpers.
3715 */
3716typedef struct PDMPICHLPR0
3717{
3718 /** Structure version. PDM_PICHLPR0_VERSION defines the current version. */
3719 uint32_t u32Version;
3720
3721 /**
3722 * Set the interrupt force action flag.
3723 *
3724 * @param pDevIns Device instance of the PIC.
3725 */
3726 DECLR0CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
3727
3728 /**
3729 * Clear the interrupt force action flag.
3730 *
3731 * @param pDevIns Device instance of the PIC.
3732 */
3733 DECLR0CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
3734
3735#ifdef VBOX_WITH_PDM_LOCK
3736 /**
3737 * Acquires the PDM lock.
3738 *
3739 * @returns VINF_SUCCESS on success.
3740 * @returns rc if we failed to acquire the lock.
3741 * @param pDevIns The PIC device instance.
3742 * @param rc What to return if we fail to acquire the lock.
3743 */
3744 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3745
3746 /**
3747 * Releases the PDM lock.
3748 *
3749 * @param pDevIns The PCI device instance.
3750 */
3751 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3752#endif
3753
3754 /** Just a safety precaution. */
3755 uint32_t u32TheEnd;
3756} PDMPICHLPR0;
3757
3758/** Pointer to PIC R0 helpers. */
3759typedef R0PTRTYPE(PDMPICHLPR0 *) PPDMPICHLPR0;
3760/** Pointer to const PIC R0 helpers. */
3761typedef R0PTRTYPE(const PDMPICHLPR0 *) PCPDMPICHLPR0;
3762
3763/** Current PDMPICHLPR0 version number. */
3764#define PDM_PICHLPR0_VERSION 0xfc010000
3765
3766/**
3767 * PIC HC helpers.
3768 */
3769typedef struct PDMPICHLPR3
3770{
3771 /** Structure version. PDM_PICHLP_VERSION defines the current version. */
3772 uint32_t u32Version;
3773
3774 /**
3775 * Set the interrupt force action flag.
3776 *
3777 * @param pDevIns Device instance of the PIC.
3778 */
3779 DECLR3CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
3780
3781 /**
3782 * Clear the interrupt force action flag.
3783 *
3784 * @param pDevIns Device instance of the PIC.
3785 */
3786 DECLR3CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
3787
3788#ifdef VBOX_WITH_PDM_LOCK
3789 /**
3790 * Acquires the PDM lock.
3791 *
3792 * @returns VINF_SUCCESS on success.
3793 * @returns Fatal error on failure.
3794 * @param pDevIns The PIC device instance.
3795 * @param rc Dummy for making the interface identical to the GC and R0 versions.
3796 */
3797 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3798
3799 /**
3800 * Releases the PDM lock.
3801 *
3802 * @param pDevIns The PIC device instance.
3803 */
3804 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3805#endif
3806
3807 /**
3808 * Gets the address of the GC PIC helpers.
3809 *
3810 * This should be called at both construction and relocation time
3811 * to obtain the correct address of the GC helpers.
3812 *
3813 * @returns GC pointer to the PIC helpers.
3814 * @param pDevIns Device instance of the PIC.
3815 */
3816 DECLR3CALLBACKMEMBER(PCPDMPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
3817
3818 /**
3819 * Gets the address of the R0 PIC helpers.
3820 *
3821 * This should be called at both construction and relocation time
3822 * to obtain the correct address of the GC helpers.
3823 *
3824 * @returns R0 pointer to the PIC helpers.
3825 * @param pDevIns Device instance of the PIC.
3826 */
3827 DECLR3CALLBACKMEMBER(PCPDMPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
3828
3829 /** Just a safety precaution. */
3830 uint32_t u32TheEnd;
3831} PDMPICHLPR3;
3832
3833/** Pointer to PIC HC helpers. */
3834typedef HCPTRTYPE(PDMPICHLPR3 *) PPDMPICHLPR3;
3835/** Pointer to const PIC HC helpers. */
3836typedef HCPTRTYPE(const PDMPICHLPR3 *) PCPDMPICHLPR3;
3837
3838/** Current PDMPICHLPR3 version number. */
3839#define PDM_PICHLPR3_VERSION 0xf0010000
3840
3841
3842
3843/**
3844 * Advanced Programmable Interrupt Controller registration structure.
3845 */
3846typedef struct PDMAPICREG
3847{
3848 /** Structure version number. PDM_APICREG_VERSION defines the current version. */
3849 uint32_t u32Version;
3850
3851 /**
3852 * Get a pending interrupt.
3853 *
3854 * @returns Pending interrupt number.
3855 * @param pDevIns Device instance of the APIC.
3856 */
3857 DECLR3CALLBACKMEMBER(int, pfnGetInterruptHC,(PPDMDEVINS pDevIns));
3858
3859 /**
3860 * Set the APIC base.
3861 *
3862 * @param pDevIns Device instance of the APIC.
3863 * @param u64Base The new base.
3864 */
3865 DECLR3CALLBACKMEMBER(void, pfnSetBaseHC,(PPDMDEVINS pDevIns, uint64_t u64Base));
3866
3867 /**
3868 * Get the APIC base.
3869 *
3870 * @returns Current base.
3871 * @param pDevIns Device instance of the APIC.
3872 */
3873 DECLR3CALLBACKMEMBER(uint64_t, pfnGetBaseHC,(PPDMDEVINS pDevIns));
3874
3875 /**
3876 * Set the TPR (task priority register?).
3877 *
3878 * @param pDevIns Device instance of the APIC.
3879 * @param u8TPR The new TPR.
3880 */
3881 DECLR3CALLBACKMEMBER(void, pfnSetTPRHC,(PPDMDEVINS pDevIns, uint8_t u8TPR));
3882
3883 /**
3884 * Get the TPR (task priority register?).
3885 *
3886 * @returns The current TPR.
3887 * @param pDevIns Device instance of the APIC.
3888 */
3889 DECLR3CALLBACKMEMBER(uint8_t, pfnGetTPRHC,(PPDMDEVINS pDevIns));
3890
3891 /**
3892 * Private interface between the IOAPIC and APIC.
3893 *
3894 * This is a low-level, APIC/IOAPIC implementation specific interface
3895 * which is registered with PDM only because it makes life so much
3896 * simpler right now (GC bits). This is a bad bad hack! The correct
3897 * way of doing this would involve some way of querying GC interfaces
3898 * and relocating them. Perhaps doing some kind of device init in GC...
3899 *
3900 * @returns The current TPR.
3901 * @param pDevIns Device instance of the APIC.
3902 * @param u8Dest See APIC implementation.
3903 * @param u8DestMode See APIC implementation.
3904 * @param u8DeliveryMode See APIC implementation.
3905 * @param iVector See APIC implementation.
3906 * @param u8Polarity See APIC implementation.
3907 * @param u8TriggerMode See APIC implementation.
3908 */
3909 DECLR3CALLBACKMEMBER(void, pfnBusDeliverHC,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
3910 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
3911
3912 /** The name of the GC GetInterrupt entry point. */
3913 const char *pszGetInterruptGC;
3914 /** The name of the GC SetBase entry point. */
3915 const char *pszSetBaseGC;
3916 /** The name of the GC GetBase entry point. */
3917 const char *pszGetBaseGC;
3918 /** The name of the GC SetTPR entry point. */
3919 const char *pszSetTPRGC;
3920 /** The name of the GC GetTPR entry point. */
3921 const char *pszGetTPRGC;
3922 /** The name of the GC BusDeliver entry point. */
3923 const char *pszBusDeliverGC;
3924
3925 /** The name of the R0 GetInterrupt entry point. */
3926 const char *pszGetInterruptR0;
3927 /** The name of the R0 SetBase entry point. */
3928 const char *pszSetBaseR0;
3929 /** The name of the R0 GetBase entry point. */
3930 const char *pszGetBaseR0;
3931 /** The name of the R0 SetTPR entry point. */
3932 const char *pszSetTPRR0;
3933 /** The name of the R0 GetTPR entry point. */
3934 const char *pszGetTPRR0;
3935 /** The name of the R0 BusDeliver entry point. */
3936 const char *pszBusDeliverR0;
3937
3938} PDMAPICREG;
3939/** Pointer to an APIC registration structure. */
3940typedef PDMAPICREG *PPDMAPICREG;
3941
3942/** Current PDMAPICREG version number. */
3943#define PDM_APICREG_VERSION 0x70010000
3944
3945
3946/**
3947 * APIC GC helpers.
3948 */
3949typedef struct PDMAPICHLPGC
3950{
3951 /** Structure version. PDM_APICHLPGC_VERSION defines the current version. */
3952 uint32_t u32Version;
3953
3954 /**
3955 * Set the interrupt force action flag.
3956 *
3957 * @param pDevIns Device instance of the APIC.
3958 */
3959 DECLGCCALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
3960
3961 /**
3962 * Clear the interrupt force action flag.
3963 *
3964 * @param pDevIns Device instance of the APIC.
3965 */
3966 DECLGCCALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
3967
3968 /**
3969 * Sets or clears the APIC bit in the CPUID feature masks.
3970 *
3971 * @param pDevIns Device instance of the APIC.
3972 * @param fEnabled If true the bit is set, else cleared.
3973 */
3974 DECLGCCALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));
3975
3976#ifdef VBOX_WITH_PDM_LOCK
3977 /**
3978 * Acquires the PDM lock.
3979 *
3980 * @returns VINF_SUCCESS on success.
3981 * @returns rc if we failed to acquire the lock.
3982 * @param pDevIns The APIC device instance.
3983 * @param rc What to return if we fail to acquire the lock.
3984 */
3985 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3986
3987 /**
3988 * Releases the PDM lock.
3989 *
3990 * @param pDevIns The APIC device instance.
3991 */
3992 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3993#endif
3994 /** Just a safety precaution. */
3995 uint32_t u32TheEnd;
3996} PDMAPICHLPGC;
3997/** Pointer to APIC GC helpers. */
3998typedef GCPTRTYPE(PDMAPICHLPGC *) PPDMAPICHLPGC;
3999/** Pointer to const APIC helpers. */
4000typedef GCPTRTYPE(const PDMAPICHLPGC *) PCPDMAPICHLPGC;
4001
4002/** Current PDMAPICHLPGC version number. */
4003#define PDM_APICHLPGC_VERSION 0x60010000
4004
4005
4006/**
4007 * APIC R0 helpers.
4008 */
4009typedef struct PDMAPICHLPR0
4010{
4011 /** Structure version. PDM_APICHLPR0_VERSION defines the current version. */
4012 uint32_t u32Version;
4013
4014 /**
4015 * Set the interrupt force action flag.
4016 *
4017 * @param pDevIns Device instance of the APIC.
4018 */
4019 DECLR0CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
4020
4021 /**
4022 * Clear the interrupt force action flag.
4023 *
4024 * @param pDevIns Device instance of the APIC.
4025 */
4026 DECLR0CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
4027
4028 /**
4029 * Sets or clears the APIC bit in the CPUID feature masks.
4030 *
4031 * @param pDevIns Device instance of the APIC.
4032 * @param fEnabled If true the bit is set, else cleared.
4033 */
4034 DECLR0CALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));
4035
4036#ifdef VBOX_WITH_PDM_LOCK
4037 /**
4038 * Acquires the PDM lock.
4039 *
4040 * @returns VINF_SUCCESS on success.
4041 * @returns rc if we failed to acquire the lock.
4042 * @param pDevIns The APIC device instance.
4043 * @param rc What to return if we fail to acquire the lock.
4044 */
4045 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
4046
4047 /**
4048 * Releases the PDM lock.
4049 *
4050 * @param pDevIns The APIC device instance.
4051 */
4052 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
4053#endif
4054
4055 /** Just a safety precaution. */
4056 uint32_t u32TheEnd;
4057} PDMAPICHLPR0;
4058/** Pointer to APIC GC helpers. */
4059typedef GCPTRTYPE(PDMAPICHLPR0 *) PPDMAPICHLPR0;
4060/** Pointer to const APIC helpers. */
4061typedef R0PTRTYPE(const PDMAPICHLPR0 *) PCPDMAPICHLPR0;
4062
4063/** Current PDMAPICHLPR0 version number. */
4064#define PDM_APICHLPR0_VERSION 0x60010000
4065
4066/**
4067 * APIC HC helpers.
4068 */
4069typedef struct PDMAPICHLPR3
4070{
4071 /** Structure version. PDM_APICHLPR3_VERSION defines the current version. */
4072 uint32_t u32Version;
4073
4074 /**
4075 * Set the interrupt force action flag.
4076 *
4077 * @param pDevIns Device instance of the APIC.
4078 */
4079 DECLR3CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
4080
4081 /**
4082 * Clear the interrupt force action flag.
4083 *
4084 * @param pDevIns Device instance of the APIC.
4085 */
4086 DECLR3CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
4087
4088 /**
4089 * Sets or clears the APIC bit in the CPUID feature masks.
4090 *
4091 * @param pDevIns Device instance of the APIC.
4092 * @param fEnabled If true the bit is set, else cleared.
4093 */
4094 DECLR3CALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));
4095
4096#ifdef VBOX_WITH_PDM_LOCK
4097 /**
4098 * Acquires the PDM lock.
4099 *
4100 * @returns VINF_SUCCESS on success.
4101 * @returns Fatal error on failure.
4102 * @param pDevIns The APIC device instance.
4103 * @param rc Dummy for making the interface identical to the GC and R0 versions.
4104 */
4105 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
4106
4107 /**
4108 * Releases the PDM lock.
4109 *
4110 * @param pDevIns The APIC device instance.
4111 */
4112 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
4113#endif
4114
4115 /**
4116 * Gets the address of the GC APIC helpers.
4117 *
4118 * This should be called at both construction and relocation time
4119 * to obtain the correct address of the GC helpers.
4120 *
4121 * @returns GC pointer to the APIC helpers.
4122 * @param pDevIns Device instance of the APIC.
4123 */
4124 DECLR3CALLBACKMEMBER(PCPDMAPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
4125
4126 /**
4127 * Gets the address of the R0 APIC helpers.
4128 *
4129 * This should be called at both construction and relocation time
4130 * to obtain the correct address of the R0 helpers.
4131 *
4132 * @returns R0 pointer to the APIC helpers.
4133 * @param pDevIns Device instance of the APIC.
4134 */
4135 DECLR3CALLBACKMEMBER(PCPDMAPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
4136
4137 /** Just a safety precaution. */
4138 uint32_t u32TheEnd;
4139} PDMAPICHLPR3;
4140/** Pointer to APIC helpers. */
4141typedef HCPTRTYPE(PDMAPICHLPR3 *) PPDMAPICHLPR3;
4142/** Pointer to const APIC helpers. */
4143typedef HCPTRTYPE(const PDMAPICHLPR3 *) PCPDMAPICHLPR3;
4144
4145/** Current PDMAPICHLP version number. */
4146#define PDM_APICHLPR3_VERSION 0xfd010000
4147
4148
4149/**
4150 * I/O APIC registration structure.
4151 */
4152typedef struct PDMIOAPICREG
4153{
4154 /** Struct version+magic number (PDM_IOAPICREG_VERSION). */
4155 uint32_t u32Version;
4156
4157 /**
4158 * Set the an IRQ.
4159 *
4160 * @param pDevIns Device instance of the I/O APIC.
4161 * @param iIrq IRQ number to set.
4162 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
4163 */
4164 DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4165
4166 /** The name of the GC SetIrq entry point. */
4167 const char *pszSetIrqGC;
4168
4169 /** The name of the R0 SetIrq entry point. */
4170 const char *pszSetIrqR0;
4171} PDMIOAPICREG;
4172/** Pointer to an APIC registration structure. */
4173typedef PDMIOAPICREG *PPDMIOAPICREG;
4174
4175/** Current PDMAPICREG version number. */
4176#define PDM_IOAPICREG_VERSION 0x50010000
4177
4178
4179/**
4180 * IOAPIC GC helpers.
4181 */
4182typedef struct PDMIOAPICHLPGC
4183{
4184 /** Structure version. PDM_IOAPICHLPGC_VERSION defines the current version. */
4185 uint32_t u32Version;
4186
4187 /**
4188 * Private interface between the IOAPIC and APIC.
4189 *
4190 * See comments about this hack on PDMAPICREG::pfnBusDeliverHC.
4191 *
4192 * @returns The current TPR.
4193 * @param pDevIns Device instance of the IOAPIC.
4194 * @param u8Dest See APIC implementation.
4195 * @param u8DestMode See APIC implementation.
4196 * @param u8DeliveryMode See APIC implementation.
4197 * @param iVector See APIC implementation.
4198 * @param u8Polarity See APIC implementation.
4199 * @param u8TriggerMode See APIC implementation.
4200 */
4201 DECLGCCALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
4202 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
4203
4204#ifdef VBOX_WITH_PDM_LOCK
4205 /**
4206 * Acquires the PDM lock.
4207 *
4208 * @returns VINF_SUCCESS on success.
4209 * @returns rc if we failed to acquire the lock.
4210 * @param pDevIns The IOAPIC device instance.
4211 * @param rc What to return if we fail to acquire the lock.
4212 */
4213 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
4214
4215 /**
4216 * Releases the PDM lock.
4217 *
4218 * @param pDevIns The IOAPIC device instance.
4219 */
4220 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
4221#endif
4222
4223 /** Just a safety precaution. */
4224 uint32_t u32TheEnd;
4225} PDMIOAPICHLPGC;
4226/** Pointer to IOAPIC GC helpers. */
4227typedef GCPTRTYPE(PDMAPICHLPGC *)PPDMIOAPICHLPGC;
4228/** Pointer to const IOAPIC helpers. */
4229typedef GCPTRTYPE(const PDMIOAPICHLPGC *) PCPDMIOAPICHLPGC;
4230
4231/** Current PDMIOAPICHLPGC version number. */
4232#define PDM_IOAPICHLPGC_VERSION 0xfe010000
4233
4234
4235/**
4236 * IOAPIC R0 helpers.
4237 */
4238typedef struct PDMIOAPICHLPR0
4239{
4240 /** Structure version. PDM_IOAPICHLPR0_VERSION defines the current version. */
4241 uint32_t u32Version;
4242
4243 /**
4244 * Private interface between the IOAPIC and APIC.
4245 *
4246 * See comments about this hack on PDMAPICREG::pfnBusDeliverHC.
4247 *
4248 * @returns The current TPR.
4249 * @param pDevIns Device instance of the IOAPIC.
4250 * @param u8Dest See APIC implementation.
4251 * @param u8DestMode See APIC implementation.
4252 * @param u8DeliveryMode See APIC implementation.
4253 * @param iVector See APIC implementation.
4254 * @param u8Polarity See APIC implementation.
4255 * @param u8TriggerMode See APIC implementation.
4256 */
4257 DECLR0CALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
4258 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
4259
4260#ifdef VBOX_WITH_PDM_LOCK
4261 /**
4262 * Acquires the PDM lock.
4263 *
4264 * @returns VINF_SUCCESS on success.
4265 * @returns rc if we failed to acquire the lock.
4266 * @param pDevIns The IOAPIC device instance.
4267 * @param rc What to return if we fail to acquire the lock.
4268 */
4269 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
4270
4271 /**
4272 * Releases the PDM lock.
4273 *
4274 * @param pDevIns The IOAPIC device instance.
4275 */
4276 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
4277#endif
4278
4279 /** Just a safety precaution. */
4280 uint32_t u32TheEnd;
4281} PDMIOAPICHLPR0;
4282/** Pointer to IOAPIC R0 helpers. */
4283typedef R0PTRTYPE(PDMAPICHLPGC *) PPDMIOAPICHLPR0;
4284/** Pointer to const IOAPIC helpers. */
4285typedef R0PTRTYPE(const PDMIOAPICHLPR0 *) PCPDMIOAPICHLPR0;
4286
4287/** Current PDMIOAPICHLPR0 version number. */
4288#define PDM_IOAPICHLPR0_VERSION 0xfe010000
4289
4290/**
4291 * IOAPIC HC helpers.
4292 */
4293typedef struct PDMIOAPICHLPR3
4294{
4295 /** Structure version. PDM_IOAPICHLPR3_VERSION defines the current version. */
4296 uint32_t u32Version;
4297
4298 /**
4299 * Private interface between the IOAPIC and APIC.
4300 *
4301 * See comments about this hack on PDMAPICREG::pfnBusDeliverHC.
4302 *
4303 * @returns The current TPR.
4304 * @param pDevIns Device instance of the IOAPIC.
4305 * @param u8Dest See APIC implementation.
4306 * @param u8DestMode See APIC implementation.
4307 * @param u8DeliveryMode See APIC implementation.
4308 * @param iVector See APIC implementation.
4309 * @param u8Polarity See APIC implementation.
4310 * @param u8TriggerMode See APIC implementation.
4311 */
4312 DECLR3CALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
4313 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
4314
4315#ifdef VBOX_WITH_PDM_LOCK
4316 /**
4317 * Acquires the PDM lock.
4318 *
4319 * @returns VINF_SUCCESS on success.
4320 * @returns Fatal error on failure.
4321 * @param pDevIns The IOAPIC device instance.
4322 * @param rc Dummy for making the interface identical to the GC and R0 versions.
4323 */
4324 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
4325
4326 /**
4327 * Releases the PDM lock.
4328 *
4329 * @param pDevIns The IOAPIC device instance.
4330 */
4331 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
4332#endif
4333
4334 /**
4335 * Gets the address of the GC IOAPIC helpers.
4336 *
4337 * This should be called at both construction and relocation time
4338 * to obtain the correct address of the GC helpers.
4339 *
4340 * @returns GC pointer to the IOAPIC helpers.
4341 * @param pDevIns Device instance of the IOAPIC.
4342 */
4343 DECLR3CALLBACKMEMBER(PCPDMIOAPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
4344
4345 /**
4346 * Gets the address of the R0 IOAPIC helpers.
4347 *
4348 * This should be called at both construction and relocation time
4349 * to obtain the correct address of the R0 helpers.
4350 *
4351 * @returns R0 pointer to the IOAPIC helpers.
4352 * @param pDevIns Device instance of the IOAPIC.
4353 */
4354 DECLR3CALLBACKMEMBER(PCPDMIOAPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
4355
4356 /** Just a safety precaution. */
4357 uint32_t u32TheEnd;
4358} PDMIOAPICHLPR3;
4359/** Pointer to IOAPIC HC helpers. */
4360typedef HCPTRTYPE(PDMIOAPICHLPR3 *) PPDMIOAPICHLPR3;
4361/** Pointer to const IOAPIC helpers. */
4362typedef HCPTRTYPE(const PDMIOAPICHLPR3 *) PCPDMIOAPICHLPR3;
4363
4364/** Current PDMIOAPICHLPR3 version number. */
4365#define PDM_IOAPICHLPR3_VERSION 0xff010000
4366
4367
4368
4369#ifdef IN_RING3
4370
4371/**
4372 * DMA Transfer Handler.
4373 *
4374 * @returns Number of bytes transferred.
4375 * @param pDevIns Device instance of the DMA.
4376 * @param pvUser User pointer.
4377 * @param uChannel Channel number.
4378 * @param off DMA position.
4379 * @param cb Block size.
4380 */
4381typedef DECLCALLBACK(uint32_t) FNDMATRANSFERHANDLER(PPDMDEVINS pDevIns, void *pvUser, unsigned uChannel, uint32_t off, uint32_t cb);
4382/** Pointer to a FNDMATRANSFERHANDLER(). */
4383typedef FNDMATRANSFERHANDLER *PFNDMATRANSFERHANDLER;
4384
4385/**
4386 * DMA Controller registration structure.
4387 */
4388typedef struct PDMDMAREG
4389{
4390 /** Structure version number. PDM_DMACREG_VERSION defines the current version. */
4391 uint32_t u32Version;
4392
4393 /**
4394 * Execute pending transfers.
4395 *
4396 * @returns A more work indiciator. I.e. 'true' if there is more to be done, and 'false' if all is done.
4397 * @param pDevIns Device instance of the DMAC.
4398 */
4399 DECLR3CALLBACKMEMBER(bool, pfnRun,(PPDMDEVINS pDevIns));
4400
4401 /**
4402 * Register transfer function for DMA channel.
4403 *
4404 * @param pDevIns Device instance of the DMAC.
4405 * @param uChannel Channel number.
4406 * @param pfnTransferHandler Device specific transfer function.
4407 * @param pvUSer User pointer to be passed to the callback.
4408 */
4409 DECLR3CALLBACKMEMBER(void, pfnRegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
4410
4411 /**
4412 * Read memory
4413 *
4414 * @returns Number of bytes read.
4415 * @param pDevIns Device instance of the DMAC.
4416 * @param pvBuffer Pointer to target buffer.
4417 * @param off DMA position.
4418 * @param cbBlock Block size.
4419 */
4420 DECLR3CALLBACKMEMBER(uint32_t, pfnReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock));
4421
4422 /**
4423 * Write memory
4424 *
4425 * @returns Number of bytes written.
4426 * @param pDevIns Device instance of the DMAC.
4427 * @param pvBuffer Memory to write.
4428 * @param off DMA position.
4429 * @param cbBlock Block size.
4430 */
4431 DECLR3CALLBACKMEMBER(uint32_t, pfnWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock));
4432
4433 /**
4434 * Set the DREQ line.
4435 *
4436 * @param pDevIns Device instance of the DMAC.
4437 * @param uChannel Channel number.
4438 * @param uLevel Level of the line.
4439 */
4440 DECLR3CALLBACKMEMBER(void, pfnSetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
4441
4442 /**
4443 * Get channel mode
4444 *
4445 * @returns Channel mode.
4446 * @param pDevIns Device instance of the DMAC.
4447 * @param uChannel Channel number.
4448 */
4449 DECLR3CALLBACKMEMBER(uint8_t, pfnGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
4450
4451} PDMDMACREG;
4452/** Pointer to a DMAC registration structure. */
4453typedef PDMDMACREG *PPDMDMACREG;
4454
4455/** Current PDMDMACREG version number. */
4456#define PDM_DMACREG_VERSION 0xf5010000
4457
4458
4459/**
4460 * DMA Controller device helpers.
4461 */
4462typedef struct PDMDMACHLP
4463{
4464 /** Structure version. PDM_DMACHLP_VERSION defines the current version. */
4465 uint32_t u32Version;
4466
4467 /* to-be-defined */
4468
4469} PDMDMACHLP;
4470/** Pointer to DMAC helpers. */
4471typedef PDMDMACHLP *PPDMDMACHLP;
4472/** Pointer to const DMAC helpers. */
4473typedef const PDMDMACHLP *PCPDMDMACHLP;
4474
4475/** Current PDMDMACHLP version number. */
4476#define PDM_DMACHLP_VERSION 0xf6010000
4477
4478#endif /* IN_RING3 */
4479
4480
4481
4482/**
4483 * RTC registration structure.
4484 */
4485typedef struct PDMRTCREG
4486{
4487 /** Structure version number. PDM_RTCREG_VERSION defines the current version. */
4488 uint32_t u32Version;
4489 uint32_t u32Alignment; /**< structure size alignment. */
4490
4491 /**
4492 * Write to a CMOS register and update the checksum if necessary.
4493 *
4494 * @returns VBox status code.
4495 * @param pDevIns Device instance of the RTC.
4496 * @param iReg The CMOS register index.
4497 * @param u8Value The CMOS register value.
4498 */
4499 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
4500
4501 /**
4502 * Read a CMOS register.
4503 *
4504 * @returns VBox status code.
4505 * @param pDevIns Device instance of the RTC.
4506 * @param iReg The CMOS register index.
4507 * @param pu8Value Where to store the CMOS register value.
4508 */
4509 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
4510
4511} PDMRTCREG;
4512/** Pointer to a RTC registration structure. */
4513typedef PDMRTCREG *PPDMRTCREG;
4514/** Pointer to a const RTC registration structure. */
4515typedef const PDMRTCREG *PCPDMRTCREG;
4516
4517/** Current PDMRTCREG version number. */
4518#define PDM_RTCREG_VERSION 0xfa010000
4519
4520
4521/**
4522 * RTC device helpers.
4523 */
4524typedef struct PDMRTCHLP
4525{
4526 /** Structure version. PDM_RTCHLP_VERSION defines the current version. */
4527 uint32_t u32Version;
4528
4529 /* to-be-defined */
4530
4531} PDMRTCHLP;
4532/** Pointer to RTC helpers. */
4533typedef PDMRTCHLP *PPDMRTCHLP;
4534/** Pointer to const RTC helpers. */
4535typedef const PDMRTCHLP *PCPDMRTCHLP;
4536
4537/** Current PDMRTCHLP version number. */
4538#define PDM_RTCHLP_VERSION 0xf6010000
4539
4540
4541
4542#ifdef IN_RING3
4543
4544/**
4545 * PDM Device API.
4546 */
4547typedef struct PDMDEVHLP
4548{
4549 /** Structure version. PDM_DEVHLP_VERSION defines the current version. */
4550 uint32_t u32Version;
4551
4552 /**
4553 * Register a number of I/O ports with a device.
4554 *
4555 * These callbacks are of course for the host context (HC).
4556 * Register HC handlers before guest context (GC) handlers! There must be a
4557 * HC handler for every GC handler!
4558 *
4559 * @returns VBox status.
4560 * @param pDevIns The device instance to register the ports with.
4561 * @param Port First port number in the range.
4562 * @param cPorts Number of ports to register.
4563 * @param pvUser User argument.
4564 * @param pfnOut Pointer to function which is gonna handle OUT operations.
4565 * @param pfnIn Pointer to function which is gonna handle IN operations.
4566 * @param pfnOutStr Pointer to function which is gonna handle string OUT operations.
4567 * @param pfnInStr Pointer to function which is gonna handle string IN operations.
4568 * @param pszDesc Pointer to description string. This must not be freed.
4569 */
4570 DECLR3CALLBACKMEMBER(int, pfnIOPortRegister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTHCPTR pvUser,
4571 PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,
4572 PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc));
4573
4574 /**
4575 * Register a number of I/O ports with a device for GC.
4576 *
4577 * These callbacks are for the host context (GC).
4578 * Register host context (HC) handlers before guest context handlers! There must be a
4579 * HC handler for every GC handler!
4580 *
4581 * @returns VBox status.
4582 * @param pDevIns The device instance to register the ports with and which GC module
4583 * to resolve the names against.
4584 * @param Port First port number in the range.
4585 * @param cPorts Number of ports to register.
4586 * @param pvUser User argument.
4587 * @param pszOut Name of the GC function which is gonna handle OUT operations.
4588 * @param pszIn Name of the GC function which is gonna handle IN operations.
4589 * @param pszOutStr Name of the GC function which is gonna handle string OUT operations.
4590 * @param pszInStr Name of the GC function which is gonna handle string IN operations.
4591 * @param pszDesc Pointer to description string. This must not be freed.
4592 */
4593 DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterGC,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTGCPTR pvUser,
4594 const char *pszOut, const char *pszIn,
4595 const char *pszOutStr, const char *pszInStr, const char *pszDesc));
4596
4597 /**
4598 * Register a number of I/O ports with a device.
4599 *
4600 * These callbacks are of course for the ring-0 host context (R0).
4601 * Register R3 (HC) handlers before R0 (R0) handlers! There must be a R3 (HC) handler for every R0 handler!
4602 *
4603 * @returns VBox status.
4604 * @param pDevIns The device instance to register the ports with.
4605 * @param Port First port number in the range.
4606 * @param cPorts Number of ports to register.
4607 * @param pvUser User argument. (if pointer, then it must be in locked memory!)
4608 * @param pszOut Name of the R0 function which is gonna handle OUT operations.
4609 * @param pszIn Name of the R0 function which is gonna handle IN operations.
4610 * @param pszOutStr Name of the R0 function which is gonna handle string OUT operations.
4611 * @param pszInStr Name of the R0 function which is gonna handle string IN operations.
4612 * @param pszDesc Pointer to description string. This must not be freed.
4613 */
4614 DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterR0,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTR0PTR pvUser,
4615 const char *pszOut, const char *pszIn,
4616 const char *pszOutStr, const char *pszInStr, const char *pszDesc));
4617
4618 /**
4619 * Deregister I/O ports.
4620 *
4621 * This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.
4622 *
4623 * @returns VBox status.
4624 * @param pDevIns The device instance owning the ports.
4625 * @param Port First port number in the range.
4626 * @param cPorts Number of ports to deregister.
4627 */
4628 DECLR3CALLBACKMEMBER(int, pfnIOPortDeregister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts));
4629
4630
4631 /**
4632 * Register a Memory Mapped I/O (MMIO) region.
4633 *
4634 * These callbacks are of course for the host context (HC).
4635 * Register HC handlers before guest context (GC) handlers! There must be a
4636 * HC handler for every GC handler!
4637 *
4638 * @returns VBox status.
4639 * @param pDevIns The device instance to register the MMIO with.
4640 * @param GCPhysStart First physical address in the range.
4641 * @param cbRange The size of the range (in bytes).
4642 * @param pvUser User argument.
4643 * @param pfnWrite Pointer to function which is gonna handle Write operations.
4644 * @param pfnRead Pointer to function which is gonna handle Read operations.
4645 * @param pfnFill Pointer to function which is gonna handle Fill/memset operations. (optional)
4646 * @param pszDesc Pointer to description string. This must not be freed.
4647 */
4648 DECLR3CALLBACKMEMBER(int, pfnMMIORegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTHCPTR pvUser,
4649 PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, PFNIOMMMIOFILL pfnFill,
4650 const char *pszDesc));
4651
4652 /**
4653 * Register a Memory Mapped I/O (MMIO) region for GC.
4654 *
4655 * These callbacks are for the guest context (GC).
4656 * Register host context (HC) handlers before guest context handlers! There must be a
4657 * HC handler for every GC handler!
4658 *
4659 * @returns VBox status.
4660 * @param pDevIns The device instance to register the MMIO with.
4661 * @param GCPhysStart First physical address in the range.
4662 * @param cbRange The size of the range (in bytes).
4663 * @param pvUser User argument.
4664 * @param pszWrite Name of the GC function which is gonna handle Write operations.
4665 * @param pszRead Name of the GC function which is gonna handle Read operations.
4666 * @param pszFill Name of the GC function which is gonna handle Fill/memset operations. (optional)
4667 * @param pszDesc Pointer to description string. This must not be freed.
4668 */
4669 DECLR3CALLBACKMEMBER(int, pfnMMIORegisterGC,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTGCPTR pvUser,
4670 const char *pszWrite, const char *pszRead, const char *pszFill,
4671 const char *pszDesc));
4672
4673 /**
4674 * Register a Memory Mapped I/O (MMIO) region for R0.
4675 *
4676 * These callbacks are for the ring-0 host context (R0).
4677 * Register R3 (HC) handlers before R0 handlers! There must be a R3 handler for every R0 handler!
4678 *
4679 * @returns VBox status.
4680 * @param pDevIns The device instance to register the MMIO with.
4681 * @param GCPhysStart First physical address in the range.
4682 * @param cbRange The size of the range (in bytes).
4683 * @param pvUser User argument. (if pointer, then it must be in locked memory!)
4684 * @param pszWrite Name of the GC function which is gonna handle Write operations.
4685 * @param pszRead Name of the GC function which is gonna handle Read operations.
4686 * @param pszFill Name of the GC function which is gonna handle Fill/memset operations. (optional)
4687 * @param pszDesc Pointer to description string. This must not be freed.
4688 */
4689 DECLR3CALLBACKMEMBER(int, pfnMMIORegisterR0,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTR0PTR pvUser,
4690 const char *pszWrite, const char *pszRead, const char *pszFill,
4691 const char *pszDesc));
4692
4693 /**
4694 * Deregister a Memory Mapped I/O (MMIO) region.
4695 *
4696 * This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.
4697 *
4698 * @returns VBox status.
4699 * @param pDevIns The device instance owning the MMIO region(s).
4700 * @param GCPhysStart First physical address in the range.
4701 * @param cbRange The size of the range (in bytes).
4702 */
4703 DECLR3CALLBACKMEMBER(int, pfnMMIODeregister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange));
4704
4705 /**
4706 * Register a ROM (BIOS) region.
4707 *
4708 * It goes without saying that this is read-only memory. The memory region must be
4709 * in unassigned memory. I.e. from the top of the address space or on the PC in
4710 * the 0xa0000-0xfffff range.
4711 *
4712 * @returns VBox status.
4713 * @param pDevIns The device instance owning the ROM region.
4714 * @param GCPhysStart First physical address in the range.
4715 * Must be page aligned!
4716 * @param cbRange The size of the range (in bytes).
4717 * Must be page aligned!
4718 * @param pvBinary Pointer to the binary data backing the ROM image.
4719 * This must be cbRange bytes big.
4720 * It will be copied and doesn't have to stick around.
4721 * @param pszDesc Pointer to description string. This must not be freed.
4722 * @remark There is no way to remove the rom, automatically on device cleanup or
4723 * manually from the device yet. At present I doubt we need such features...
4724 */
4725 DECLR3CALLBACKMEMBER(int, pfnROMRegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, const void *pvBinary, const char *pszDesc));
4726
4727 /**
4728 * Register a save state data unit.
4729 *
4730 * @returns VBox status.
4731 * @param pDevIns Device instance.
4732 * @param pszName Data unit name.
4733 * @param u32Instance The instance identifier of the data unit.
4734 * This must together with the name be unique.
4735 * @param u32Version Data layout version number.
4736 * @param cbGuess The approximate amount of data in the unit.
4737 * Only for progress indicators.
4738 * @param pfnSavePrep Prepare save callback, optional.
4739 * @param pfnSaveExec Execute save callback, optional.
4740 * @param pfnSaveDone Done save callback, optional.
4741 * @param pfnLoadPrep Prepare load callback, optional.
4742 * @param pfnLoadExec Execute load callback, optional.
4743 * @param pfnLoadDone Done load callback, optional.
4744 */
4745 DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDEVINS pDevIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
4746 PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
4747 PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone));
4748
4749 /**
4750 * Creates a timer.
4751 *
4752 * @returns VBox status.
4753 * @param pDevIns Device instance.
4754 * @param enmClock The clock to use on this timer.
4755 * @param pfnCallback Callback function.
4756 * @param pszDesc Pointer to description string which must stay around
4757 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
4758 * @param ppTimer Where to store the timer on success.
4759 */
4760 DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer));
4761
4762 /**
4763 * Creates an external timer.
4764 *
4765 * @returns timer pointer
4766 * @param pDevIns Device instance.
4767 * @param enmClock The clock to use on this timer.
4768 * @param pfnCallback Callback function.
4769 * @param pvUser User pointer
4770 * @param pszDesc Pointer to description string which must stay around
4771 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
4772 */
4773 DECLR3CALLBACKMEMBER(PTMTIMERHC, pfnTMTimerCreateExternal,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMEREXT pfnCallback, void *pvUser, const char *pszDesc));
4774
4775 /**
4776 * Registers the device with the default PCI bus.
4777 *
4778 * @returns VBox status code.
4779 * @param pDevIns Device instance.
4780 * @param pPciDev The PCI device structure.
4781 * Any PCI enabled device must keep this in it's instance data!
4782 * Fill in the PCI data config before registration, please.
4783 * @remark This is the simple interface, a Ex interface will be created if
4784 * more features are needed later.
4785 */
4786 DECLR3CALLBACKMEMBER(int, pfnPCIRegister,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev));
4787
4788 /**
4789 * Registers a I/O region (memory mapped or I/O ports) for a PCI device.
4790 *
4791 * @returns VBox status code.
4792 * @param pDevIns Device instance.
4793 * @param iRegion The region number.
4794 * @param cbRegion Size of the region.
4795 * @param enmType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
4796 * @param pfnCallback Callback for doing the mapping.
4797 */
4798 DECLR3CALLBACKMEMBER(int, pfnPCIIORegionRegister,(PPDMDEVINS pDevIns, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback));
4799
4800 /**
4801 * Register PCI configuration space read/write callbacks.
4802 *
4803 * @param pDevIns Device instance.
4804 * @param pPciDev The PCI device structure.
4805 * If NULL the default PCI device for this device instance is used.
4806 * @param pfnRead Pointer to the user defined PCI config read function.
4807 * @param ppfnReadOld Pointer to function pointer which will receive the old (default)
4808 * PCI config read function. This way, user can decide when (and if)
4809 * to call default PCI config read function. Can be NULL.
4810 * @param pfnWrite Pointer to the user defined PCI config write function.
4811 * @param pfnWriteOld Pointer to function pointer which will receive the old (default)
4812 * PCI config write function. This way, user can decide when (and if)
4813 * to call default PCI config write function. Can be NULL.
4814 * @thread EMT
4815 */
4816 DECLR3CALLBACKMEMBER(void, pfnPCISetConfigCallbacks,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,
4817 PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld));
4818
4819 /**
4820 * Set the IRQ for a PCI device.
4821 *
4822 * @param pDevIns Device instance.
4823 * @param iIrq IRQ number to set.
4824 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
4825 * @thread Any thread, but will involve the emulation thread.
4826 */
4827 DECLR3CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4828
4829 /**
4830 * Set the IRQ for a PCI device, but don't wait for EMT to process
4831 * the request when not called from EMT.
4832 *
4833 * @param pDevIns Device instance.
4834 * @param iIrq IRQ number to set.
4835 * @param iLevel IRQ level.
4836 * @thread Any thread, but will involve the emulation thread.
4837 */
4838 DECLR3CALLBACKMEMBER(void, pfnPCISetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4839
4840 /**
4841 * Set ISA IRQ for a device.
4842 *
4843 * @param pDevIns Device instance.
4844 * @param iIrq IRQ number to set.
4845 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
4846 * @thread Any thread, but will involve the emulation thread.
4847 */
4848 DECLR3CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4849
4850 /**
4851 * Set the ISA IRQ for a device, but don't wait for EMT to process
4852 * the request when not called from EMT.
4853 *
4854 * @param pDevIns Device instance.
4855 * @param iIrq IRQ number to set.
4856 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
4857 * @thread Any thread, but will involve the emulation thread.
4858 */
4859 DECLR3CALLBACKMEMBER(void, pfnISASetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4860
4861 /**
4862 * Attaches a driver (chain) to the device.
4863 *
4864 * The first call for a LUN this will serve as a registartion of the LUN. The pBaseInterface and
4865 * the pszDesc string will be registered with that LUN and kept around for PDMR3QueryDeviceLun().
4866 *
4867 * @returns VBox status code.
4868 * @param pDevIns Device instance.
4869 * @param iLun The logical unit to attach.
4870 * @param pBaseInterface Pointer to the base interface for that LUN. (device side / down)
4871 * @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up)
4872 * @param pszDesc Pointer to a string describing the LUN. This string must remain valid
4873 * for the live of the device instance.
4874 */
4875 DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMDEVINS pDevIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE *ppBaseInterface, const char *pszDesc));
4876
4877#if 0
4878 /* USB... */
4879
4880#endif
4881
4882 /**
4883 * Allocate memory which is associated with current VM instance
4884 * and automatically freed on it's destruction.
4885 *
4886 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
4887 * @param pDevIns Device instance.
4888 * @param cb Number of bytes to allocate.
4889 */
4890 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVINS pDevIns, size_t cb));
4891
4892 /**
4893 * Allocate memory which is associated with current VM instance
4894 * and automatically freed on it's destruction. The memory is ZEROed.
4895 *
4896 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
4897 * @param pDevIns Device instance.
4898 * @param cb Number of bytes to allocate.
4899 */
4900 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAllocZ,(PPDMDEVINS pDevIns, size_t cb));
4901
4902 /**
4903 * Free memory allocated with pfnMMHeapAlloc() and pfnMMHeapAllocZ().
4904 *
4905 * @param pDevIns Device instance.
4906 * @param pv Pointer to the memory to free.
4907 */
4908 DECLR3CALLBACKMEMBER(void, pfnMMHeapFree,(PPDMDEVINS pDevIns, void *pv));
4909
4910 /**
4911 * Set the VM error message
4912 *
4913 * @returns rc.
4914 * @param pDevIns Device instance.
4915 * @param rc VBox status code.
4916 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
4917 * @param pszFormat Error message format string.
4918 * @param ... Error message arguments.
4919 */
4920 DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
4921
4922 /**
4923 * Set the VM error message
4924 *
4925 * @returns rc.
4926 * @param pDevIns Device instance.
4927 * @param rc VBox status code.
4928 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
4929 * @param pszFormat Error message format string.
4930 * @param va Error message arguments.
4931 */
4932 DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
4933
4934 /**
4935 * Set the VM runtime error message
4936 *
4937 * @returns VBox status code.
4938 * @param pDevIns Device instance.
4939 * @param fFatal Whether it is a fatal error or not.
4940 * @param pszErrorID Error ID string.
4941 * @param pszFormat Error message format string.
4942 * @param ... Error message arguments.
4943 */
4944 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));
4945
4946 /**
4947 * Set the VM runtime error message
4948 *
4949 * @returns VBox status code.
4950 * @param pDevIns Device instance.
4951 * @param fFatal Whether it is a fatal error or not.
4952 * @param pszErrorID Error ID string.
4953 * @param pszFormat Error message format string.
4954 * @param va Error message arguments.
4955 */
4956 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));
4957
4958 /**
4959 * Assert that the current thread is the emulation thread.
4960 *
4961 * @returns True if correct.
4962 * @returns False if wrong.
4963 * @param pDevIns Device instance.
4964 * @param pszFile Filename of the assertion location.
4965 * @param iLine The linenumber of the assertion location.
4966 * @param pszFunction Function of the assertion location.
4967 */
4968 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction));
4969
4970 /**
4971 * Assert that the current thread is NOT the emulation thread.
4972 *
4973 * @returns True if correct.
4974 * @returns False if wrong.
4975 * @param pDevIns Device instance.
4976 * @param pszFile Filename of the assertion location.
4977 * @param iLine The linenumber of the assertion location.
4978 * @param pszFunction Function of the assertion location.
4979 */
4980 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction));
4981
4982 /**
4983 * Stops the VM and enters the debugger to look at the guest state.
4984 *
4985 * Use the PDMDeviceDBGFStop() inline function with the RT_SRC_POS macro instead of
4986 * invoking this function directly.
4987 *
4988 * @returns VBox status code which must be passed up to the VMM.
4989 * @param pDevIns Device instance.
4990 * @param pszFile Filename of the assertion location.
4991 * @param iLine The linenumber of the assertion location.
4992 * @param pszFunction Function of the assertion location.
4993 * @param pszFormat Message. (optional)
4994 * @param args Message parameters.
4995 */
4996 DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction, const char *pszFormat, va_list args));
4997
4998 /**
4999 * Register a info handler with DBGF,
5000 *
5001 * @returns VBox status code.
5002 * @param pDevIns Device instance.
5003 * @param pszName The identifier of the info.
5004 * @param pszDesc The description of the info and any arguments the handler may take.
5005 * @param pfnHandler The handler function to be called to display the info.
5006 */
5007 DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMDEVINS pDevIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDEV pfnHandler));
5008
5009 /**
5010 * Registers a statistics sample if statistics are enabled.
5011 *
5012 * @param pDevIns Device instance of the DMA.
5013 * @param pvSample Pointer to the sample.
5014 * @param enmType Sample type. This indicates what pvSample is pointing at.
5015 * @param pszName Sample name. The name is on this form "/<component>/<sample>".
5016 * Further nesting is possible.
5017 * @param enmUnit Sample unit.
5018 * @param pszDesc Sample description.
5019 */
5020 DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc));
5021
5022 /**
5023 * Same as pfnSTAMRegister except that the name is specified in a
5024 * RTStrPrintf like fashion.
5025 *
5026 * @returns VBox status.
5027 * @param pDevIns Device instance of the DMA.
5028 * @param pvSample Pointer to the sample.
5029 * @param enmType Sample type. This indicates what pvSample is pointing at.
5030 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
5031 * @param enmUnit Sample unit.
5032 * @param pszDesc Sample description.
5033 * @param pszName The sample name format string.
5034 * @param ... Arguments to the format string.
5035 */
5036 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
5037 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, ...));
5038
5039 /**
5040 * Same as pfnSTAMRegister except that the name is specified in a
5041 * RTStrPrintfV like fashion.
5042 *
5043 * @returns VBox status.
5044 * @param pDevIns Device instance of the DMA.
5045 * @param pvSample Pointer to the sample.
5046 * @param enmType Sample type. This indicates what pvSample is pointing at.
5047 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
5048 * @param enmUnit Sample unit.
5049 * @param pszDesc Sample description.
5050 * @param pszName The sample name format string.
5051 * @param args Arguments to the format string.
5052 */
5053 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
5054 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list args));
5055
5056 /**
5057 * Register the RTC device.
5058 *
5059 * @returns VBox status code.
5060 * @param pDevIns Device instance.
5061 * @param pRtcReg Pointer to a RTC registration structure.
5062 * @param ppRtcHlp Where to store the pointer to the helper functions.
5063 */
5064 DECLR3CALLBACKMEMBER(int, pfnRTCRegister,(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp));
5065
5066 /**
5067 * Create a queue.
5068 *
5069 * @returns VBox status code.
5070 * @param pDevIns The device instance.
5071 * @param cbItem The size of a queue item.
5072 * @param cItems The number of items in the queue.
5073 * @param cMilliesInterval The number of milliseconds between polling the queue.
5074 * If 0 then the emulation thread will be notified whenever an item arrives.
5075 * @param pfnCallback The consumer function.
5076 * @param fGCEnabled Set if the queue should work in GC too.
5077 * @param ppQueue Where to store the queue handle on success.
5078 * @thread The emulation thread.
5079 */
5080 DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDEVINS pDevIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
5081 PFNPDMQUEUEDEV pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue));
5082
5083 /**
5084 * Initializes a PDM critical section.
5085 *
5086 * The PDM critical sections are derived from the IPRT critical sections, but
5087 * works in GC as well.
5088 *
5089 * @returns VBox status code.
5090 * @param pDevIns Device instance.
5091 * @param pCritSect Pointer to the critical section.
5092 * @param pszName The name of the critical section (for statistics).
5093 */
5094 DECLR3CALLBACKMEMBER(int, pfnCritSectInit,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, const char *pszName));
5095
5096 /**
5097 * Get the real world UTC time adjusted for VM lag, user offset and warpdrive.
5098 *
5099 * @returns pTime.
5100 * @param pDevIns Device instance.
5101 * @param pTime Where to store the time.
5102 */
5103 DECLR3CALLBACKMEMBER(PRTTIMESPEC, pfnUTCNow,(PPDMDEVINS pDevIns, PRTTIMESPEC pTime));
5104
5105 /** Space reserved for future members.
5106 * @{ */
5107 DECLR3CALLBACKMEMBER(void, pfnReserved1,(void));
5108 DECLR3CALLBACKMEMBER(void, pfnReserved2,(void));
5109 DECLR3CALLBACKMEMBER(void, pfnReserved3,(void));
5110 DECLR3CALLBACKMEMBER(void, pfnReserved4,(void));
5111 DECLR3CALLBACKMEMBER(void, pfnReserved5,(void));
5112 DECLR3CALLBACKMEMBER(void, pfnReserved6,(void));
5113 DECLR3CALLBACKMEMBER(void, pfnReserved7,(void));
5114 DECLR3CALLBACKMEMBER(void, pfnReserved8,(void));
5115 DECLR3CALLBACKMEMBER(void, pfnReserved9,(void));
5116 DECLR3CALLBACKMEMBER(void, pfnReserved10,(void));
5117 /** @} */
5118
5119
5120 /** API available to trusted devices only.
5121 *
5122 * These APIs are providing unrestricted access to the guest and the VM,
5123 * or they are interacting intimately with PDM.
5124 *
5125 * @{
5126 */
5127 /**
5128 * Gets the VM handle. Restricted API.
5129 *
5130 * @returns VM Handle.
5131 * @param pDevIns Device instance.
5132 */
5133 DECLR3CALLBACKMEMBER(PVM, pfnGetVM,(PPDMDEVINS pDevIns));
5134
5135 /**
5136 * Register the PCI Bus.
5137 *
5138 * @returns VBox status code.
5139 * @param pDevIns Device instance.
5140 * @param pPciBusReg Pointer to PCI bus registration structure.
5141 * @param ppPciHlpR3 Where to store the pointer to the PCI Bus helpers.
5142 */
5143 DECLR3CALLBACKMEMBER(int, pfnPCIBusRegister,(PPDMDEVINS pDevIns, PPDMPCIBUSREG pPciBusReg, PCPDMPCIHLPR3 *ppPciHlpR3));
5144
5145 /**
5146 * Register the PIC device.
5147 *
5148 * @returns VBox status code.
5149 * @param pDevIns Device instance.
5150 * @param pPicReg Pointer to a PIC registration structure.
5151 * @param ppPicHlpR3 Where to store the pointer to the PIC HC helpers.
5152 */
5153 DECLR3CALLBACKMEMBER(int, pfnPICRegister,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLPR3 *ppPicHlpR3));
5154
5155 /**
5156 * Register the APIC device.
5157 *
5158 * @returns VBox status code.
5159 * @param pDevIns Device instance.
5160 * @param pApicReg Pointer to a APIC registration structure.
5161 * @param ppApicHlpR3 Where to store the pointer to the APIC helpers.
5162 */
5163 DECLR3CALLBACKMEMBER(int, pfnAPICRegister,(PPDMDEVINS pDevIns, PPDMAPICREG pApicReg, PCPDMAPICHLPR3 *ppApicHlpR3));
5164
5165 /**
5166 * Register the I/O APIC device.
5167 *
5168 * @returns VBox status code.
5169 * @param pDevIns Device instance.
5170 * @param pIoApicReg Pointer to a I/O APIC registration structure.
5171 * @param ppIoApicHlpR3 Where to store the pointer to the IOAPIC helpers.
5172 */
5173 DECLR3CALLBACKMEMBER(int, pfnIOAPICRegister,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLPR3 *ppIoApicHlpR3));
5174
5175 /**
5176 * Register the DMA device.
5177 *
5178 * @returns VBox status code.
5179 * @param pDevIns Device instance.
5180 * @param pDmacReg Pointer to a DMAC registration structure.
5181 * @param ppDmacHlp Where to store the pointer to the DMA helpers.
5182 */
5183 DECLR3CALLBACKMEMBER(int, pfnDMACRegister,(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp));
5184
5185 /**
5186 * Read physical memory.
5187 *
5188 * @param pDevIns Device instance.
5189 * @param GCPhys Physical address start reading from.
5190 * @param pvBuf Where to put the read bits.
5191 * @param cbRead How many bytes to read.
5192 * @thread Any thread, but the call may involve the emulation thread.
5193 */
5194 DECLR3CALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
5195
5196 /**
5197 * Write to physical memory.
5198 *
5199 * @param pDevIns Device instance.
5200 * @param GCPhys Physical address to write to.
5201 * @param pvBuf What to write.
5202 * @param cbWrite How many bytes to write.
5203 * @thread Any thread, but the call may involve the emulation thread.
5204 */
5205 DECLR3CALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
5206
5207 /**
5208 * Read guest physical memory by virtual address.
5209 *
5210 * @param pDevIns Device instance.
5211 * @param pvDst Where to put the read bits.
5212 * @param GCVirtSrc Guest virtual address to start reading from.
5213 * @param cb How many bytes to read.
5214 * @thread The emulation thread.
5215 */
5216 DECLR3CALLBACKMEMBER(int, pfnPhysReadGCVirt,(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb));
5217
5218 /**
5219 * Write to guest physical memory by virtual address.
5220 *
5221 * @param pDevIns Device instance.
5222 * @param GCVirtDst Guest virtual address to write to.
5223 * @param pvSrc What to write.
5224 * @param cb How many bytes to write.
5225 * @thread The emulation thread.
5226 */
5227 DECLR3CALLBACKMEMBER(int, pfnPhysWriteGCVirt,(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb));
5228
5229 /**
5230 * Reserve physical address space for ROM and MMIO ranges.
5231 *
5232 * @returns VBox status code.
5233 * @param pDevIns Device instance.
5234 * @param GCPhys Start physical address.
5235 * @param cbRange The size of the range.
5236 * @param pszDesc Description string.
5237 * @thread The emulation thread.
5238 */
5239 DECLR3CALLBACKMEMBER(int, pfnPhysReserve,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const char *pszDesc));
5240
5241 /**
5242 * Convert a guest physical address to a host virtual address.
5243 *
5244 * @returns VBox status code.
5245 * @param pDevIns Device instance.
5246 * @param GCPhys Start physical address.
5247 * @param cbRange The size of the range. Use 0 if you don't care about the range.
5248 * @param ppvHC Where to store the HC pointer corresponding to GCPhys.
5249 * @thread Any thread.
5250 */
5251 DECLR3CALLBACKMEMBER(int, pfnPhys2HCVirt,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, PRTHCPTR ppvHC));
5252
5253 /**
5254 * Convert a guest virtual address to a host virtual address.
5255 *
5256 * @returns VBox status code.
5257 * @param pDevIns Device instance.
5258 * @param GCPtr Guest virtual address.
5259 * @param pHCPtr Where to store the HC pointer corresponding to GCPtr.
5260 * @thread The emulation thread.
5261 * @remark Careful with page boundraries.
5262 */
5263 DECLR3CALLBACKMEMBER(int, pfnPhysGCPtr2HCPtr,(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTHCPTR pHCPtr));
5264
5265 /**
5266 * Checks if the Gate A20 is enabled or not.
5267 *
5268 * @returns true if A20 is enabled.
5269 * @returns false if A20 is disabled.
5270 * @param pDevIns Device instance.
5271 * @thread The emulation thread.
5272 */
5273 DECLR3CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
5274
5275 /**
5276 * Enables or disables the Gate A20.
5277 *
5278 * @param pDevIns Device instance.
5279 * @param fEnable Set this flag to enable the Gate A20; clear it to disable.
5280 * @thread The emulation thread.
5281 */
5282 DECLR3CALLBACKMEMBER(void, pfnA20Set,(PPDMDEVINS pDevIns, bool fEnable));
5283
5284 /**
5285 * Resets the VM.
5286 *
5287 * @returns The appropriate VBox status code to pass around on reset.
5288 * @param pDevIns Device instance.
5289 * @thread The emulation thread.
5290 */
5291 DECLR3CALLBACKMEMBER(int, pfnVMReset,(PPDMDEVINS pDevIns));
5292
5293 /**
5294 * Suspends the VM.
5295 *
5296 * @returns The appropriate VBox status code to pass around on suspend.
5297 * @param pDevIns Device instance.
5298 * @thread The emulation thread.
5299 */
5300 DECLR3CALLBACKMEMBER(int, pfnVMSuspend,(PPDMDEVINS pDevIns));
5301
5302 /**
5303 * Power off the VM.
5304 *
5305 * @returns The appropriate VBox status code to pass around on power off.
5306 * @param pDevIns Device instance.
5307 * @thread The emulation thread.
5308 */
5309 DECLR3CALLBACKMEMBER(int, pfnVMPowerOff,(PPDMDEVINS pDevIns));
5310
5311 /**
5312 * Acquire global VM lock
5313 *
5314 * @returns VBox status code
5315 * @param pDevIns Device instance.
5316 */
5317 DECLR3CALLBACKMEMBER(int , pfnLockVM,(PPDMDEVINS pDevIns));
5318
5319 /**
5320 * Release global VM lock
5321 *
5322 * @returns VBox status code
5323 * @param pDevIns Device instance.
5324 */
5325 DECLR3CALLBACKMEMBER(int, pfnUnlockVM,(PPDMDEVINS pDevIns));
5326
5327 /**
5328 * Check that the current thread owns the global VM lock.
5329 *
5330 * @returns boolean
5331 * @param pDevIns Device instance.
5332 * @param pszFile Filename of the assertion location.
5333 * @param iLine Linenumber of the assertion location.
5334 * @param pszFunction Function of the assertion location.
5335 */
5336 DECLR3CALLBACKMEMBER(bool, pfnAssertVMLock,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction));
5337
5338 /**
5339 * Register transfer function for DMA channel.
5340 *
5341 * @returns VBox status code.
5342 * @param pDevIns Device instance.
5343 * @param uChannel Channel number.
5344 * @param pfnTransferHandler Device specific transfer callback function.
5345 * @param pvUser User pointer to pass to the callback.
5346 * @thread EMT
5347 */
5348 DECLR3CALLBACKMEMBER(int, pfnDMARegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
5349
5350 /**
5351 * Read memory.
5352 *
5353 * @returns VBox status code.
5354 * @param pDevIns Device instance.
5355 * @param uChannel Channel number.
5356 * @param pvBuffer Pointer to target buffer.
5357 * @param off DMA position.
5358 * @param cbBlock Block size.
5359 * @param pcbRead Where to store the number of bytes which was read. optional.
5360 * @thread EMT
5361 */
5362 DECLR3CALLBACKMEMBER(int, pfnDMAReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbRead));
5363
5364 /**
5365 * Write memory.
5366 *
5367 * @returns VBox status code.
5368 * @param pDevIns Device instance.
5369 * @param uChannel Channel number.
5370 * @param pvBuffer Memory to write.
5371 * @param off DMA position.
5372 * @param cbBlock Block size.
5373 * @param pcbWritten Where to store the number of bytes which was written. optional.
5374 * @thread EMT
5375 */
5376 DECLR3CALLBACKMEMBER(int, pfnDMAWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbWritten));
5377
5378 /**
5379 * Set the DREQ line.
5380 *
5381 * @returns VBox status code.
5382 * @param pDevIns Device instance.
5383 * @param uChannel Channel number.
5384 * @param uLevel Level of the line.
5385 * @thread EMT
5386 */
5387 DECLR3CALLBACKMEMBER(int, pfnDMASetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
5388
5389 /**
5390 * Get channel mode.
5391 *
5392 * @returns Channel mode. See specs.
5393 * @param pDevIns Device instance.
5394 * @param uChannel Channel number.
5395 * @thread EMT
5396 */
5397 DECLR3CALLBACKMEMBER(uint8_t, pfnDMAGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
5398
5399 /**
5400 * Schedule DMA execution.
5401 *
5402 * @param pDevIns Device instance.
5403 * @thread Any thread.
5404 */
5405 DECLR3CALLBACKMEMBER(void, pfnDMASchedule,(PPDMDEVINS pDevIns));
5406
5407 /**
5408 * Write CMOS value and update the checksum(s).
5409 *
5410 * @returns VBox status code.
5411 * @param pDevIns Device instance.
5412 * @param iReg The CMOS register index.
5413 * @param u8Value The CMOS register value.
5414 * @thread EMT
5415 */
5416 DECLR3CALLBACKMEMBER(int, pfnCMOSWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
5417
5418 /**
5419 * Read CMOS value.
5420 *
5421 * @returns VBox status code.
5422 * @param pDevIns Device instance.
5423 * @param iReg The CMOS register index.
5424 * @param pu8Value Where to store the CMOS register value.
5425 * @thread EMT
5426 */
5427 DECLR3CALLBACKMEMBER(int, pfnCMOSRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
5428
5429 /**
5430 * Query CPUID.
5431 *
5432 * @param pDevIns Device instance.
5433 * @param iLeaf The CPUID leaf to get.
5434 * @param pEax Where to store the EAX value.
5435 * @param pEbx Where to store the EBX value.
5436 * @param pEcx Where to store the ECX value.
5437 * @param pEdx Where to store the EDX value.
5438 */
5439 DECLR3CALLBACKMEMBER(void, pfnGetCpuId,(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t *pEax, uint32_t *pEbx, uint32_t *pEcx, uint32_t *pEdx));
5440
5441 /** @} */
5442
5443 /** Just a safety precaution. (The value is 0.) */
5444 uint32_t u32TheEnd;
5445} PDMDEVHLP;
5446#endif /* !IN_RING3 */
5447/** Pointer PDM Device API. */
5448typedef HCPTRTYPE(struct PDMDEVHLP *) PPDMDEVHLP;
5449/** Pointer PDM Device API. */
5450typedef HCPTRTYPE(const struct PDMDEVHLP *) PCPDMDEVHLP;
5451
5452/** Current PDMDEVHLP version number. */
5453#define PDM_DEVHLP_VERSION 0xf2040000
5454
5455
5456/**
5457 * PDM Device API - GC Variant.
5458 */
5459typedef struct PDMDEVHLPGC
5460{
5461 /** Structure version. PDM_DEVHLPGC_VERSION defines the current version. */
5462 uint32_t u32Version;
5463
5464 /**
5465 * Set the IRQ for a PCI device.
5466 *
5467 * @param pDevIns Device instance.
5468 * @param iIrq IRQ number to set.
5469 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
5470 * @thread Any thread, but will involve the emulation thread.
5471 */
5472 DECLGCCALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
5473
5474 /**
5475 * Set ISA IRQ for a device.
5476 *
5477 * @param pDevIns Device instance.
5478 * @param iIrq IRQ number to set.
5479 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
5480 * @thread Any thread, but will involve the emulation thread.
5481 */
5482 DECLGCCALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
5483
5484 /**
5485 * Read physical memory.
5486 *
5487 * @param pDevIns Device instance.
5488 * @param GCPhys Physical address start reading from.
5489 * @param pvBuf Where to put the read bits.
5490 * @param cbRead How many bytes to read.
5491 */
5492 DECLGCCALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
5493
5494 /**
5495 * Write to physical memory.
5496 *
5497 * @param pDevIns Device instance.
5498 * @param GCPhys Physical address to write to.
5499 * @param pvBuf What to write.
5500 * @param cbWrite How many bytes to write.
5501 */
5502 DECLGCCALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
5503
5504 /**
5505 * Checks if the Gate A20 is enabled or not.
5506 *
5507 * @returns true if A20 is enabled.
5508 * @returns false if A20 is disabled.
5509 * @param pDevIns Device instance.
5510 * @thread The emulation thread.
5511 */
5512 DECLGCCALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
5513
5514 /**
5515 * Set the VM error message
5516 *
5517 * @returns rc.
5518 * @param pDrvIns Driver instance.
5519 * @param rc VBox status code.
5520 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
5521 * @param pszFormat Error message format string.
5522 * @param ... Error message arguments.
5523 */
5524 DECLGCCALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
5525
5526 /**
5527 * Set the VM error message
5528 *
5529 * @returns rc.
5530 * @param pDrvIns Driver instance.
5531 * @param rc VBox status code.
5532 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
5533 * @param pszFormat Error message format string.
5534 * @param va Error message arguments.
5535 */
5536 DECLGCCALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
5537
5538 /**
5539 * Set the VM runtime error message
5540 *
5541 * @returns VBox status code.
5542 * @param pDevIns Device instance.
5543 * @param fFatal Whether it is a fatal error or not.
5544 * @param pszErrorID Error ID string.
5545 * @param pszFormat Error message format string.
5546 * @param ... Error message arguments.
5547 */
5548 DECLGCCALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));
5549
5550 /**
5551 * Set the VM runtime error message
5552 *
5553 * @returns VBox status code.
5554 * @param pDevIns Device instance.
5555 * @param fFatal Whether it is a fatal error or not.
5556 * @param pszErrorID Error ID string.
5557 * @param pszFormat Error message format string.
5558 * @param va Error message arguments.
5559 */
5560 DECLGCCALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));
5561
5562 /**
5563 * Set parameters for pending MMIO patch operation
5564 *
5565 * @returns VBox status code.
5566 * @param pDevIns Device instance.
5567 * @param GCPhys MMIO physical address
5568 * @param pCachedData GC pointer to cached data
5569 */
5570 DECLGCCALLBACKMEMBER(int, pfnPATMSetMMIOPatchInfo,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPTR pCachedData));
5571
5572 /** Just a safety precaution. */
5573 uint32_t u32TheEnd;
5574} PDMDEVHLPGC;
5575/** Pointer PDM Device GC API. */
5576typedef GCPTRTYPE(struct PDMDEVHLPGC *) PPDMDEVHLPGC;
5577/** Pointer PDM Device GC API. */
5578typedef GCPTRTYPE(const struct PDMDEVHLPGC *) PCPDMDEVHLPGC;
5579
5580/** Current PDMDEVHLP version number. */
5581#define PDM_DEVHLPGC_VERSION 0xfb010000
5582
5583
5584/**
5585 * PDM Device API - R0 Variant.
5586 */
5587typedef struct PDMDEVHLPR0
5588{
5589 /** Structure version. PDM_DEVHLPR0_VERSION defines the current version. */
5590 uint32_t u32Version;
5591
5592 /**
5593 * Set the IRQ for a PCI device.
5594 *
5595 * @param pDevIns Device instance.
5596 * @param iIrq IRQ number to set.
5597 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
5598 * @thread Any thread, but will involve the emulation thread.
5599 */
5600 DECLR0CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
5601
5602 /**
5603 * Set ISA IRQ for a device.
5604 *
5605 * @param pDevIns Device instance.
5606 * @param iIrq IRQ number to set.
5607 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
5608 * @thread Any thread, but will involve the emulation thread.
5609 */
5610 DECLR0CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
5611
5612 /**
5613 * Read physical memory.
5614 *
5615 * @param pDevIns Device instance.
5616 * @param GCPhys Physical address start reading from.
5617 * @param pvBuf Where to put the read bits.
5618 * @param cbRead How many bytes to read.
5619 */
5620 DECLR0CALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
5621
5622 /**
5623 * Write to physical memory.
5624 *
5625 * @param pDevIns Device instance.
5626 * @param GCPhys Physical address to write to.
5627 * @param pvBuf What to write.
5628 * @param cbWrite How many bytes to write.
5629 */
5630 DECLR0CALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
5631
5632 /**
5633 * Checks if the Gate A20 is enabled or not.
5634 *
5635 * @returns true if A20 is enabled.
5636 * @returns false if A20 is disabled.
5637 * @param pDevIns Device instance.
5638 * @thread The emulation thread.
5639 */
5640 DECLR0CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
5641
5642 /**
5643 * Set the VM error message
5644 *
5645 * @returns rc.
5646 * @param pDrvIns Driver instance.
5647 * @param rc VBox status code.
5648 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
5649 * @param pszFormat Error message format string.
5650 * @param ... Error message arguments.
5651 */
5652 DECLR0CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
5653
5654 /**
5655 * Set the VM error message
5656 *
5657 * @returns rc.
5658 * @param pDrvIns Driver instance.
5659 * @param rc VBox status code.
5660 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
5661 * @param pszFormat Error message format string.
5662 * @param va Error message arguments.
5663 */
5664 DECLR0CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
5665
5666 /**
5667 * Set the VM runtime error message
5668 *
5669 * @returns VBox status code.
5670 * @param pDevIns Device instance.
5671 * @param fFatal Whether it is a fatal error or not.
5672 * @param pszErrorID Error ID string.
5673 * @param pszFormat Error message format string.
5674 * @param ... Error message arguments.
5675 */
5676 DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));
5677
5678 /**
5679 * Set the VM runtime error message
5680 *
5681 * @returns VBox status code.
5682 * @param pDevIns Device instance.
5683 * @param fFatal Whether it is a fatal error or not.
5684 * @param pszErrorID Error ID string.
5685 * @param pszFormat Error message format string.
5686 * @param va Error message arguments.
5687 */
5688 DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));
5689
5690 /**
5691 * Set parameters for pending MMIO patch operation
5692 *
5693 * @returns rc.
5694 * @param pDevIns Device instance.
5695 * @param GCPhys MMIO physical address
5696 * @param pCachedData GC pointer to cached data
5697 */
5698 DECLR0CALLBACKMEMBER(int, pfnPATMSetMMIOPatchInfo,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPTR pCachedData));
5699
5700 /** Just a safety precaution. */
5701 uint32_t u32TheEnd;
5702} PDMDEVHLPR0;
5703/** Pointer PDM Device R0 API. */
5704typedef HCPTRTYPE(struct PDMDEVHLPR0 *) PPDMDEVHLPR0;
5705/** Pointer PDM Device GC API. */
5706typedef HCPTRTYPE(const struct PDMDEVHLPR0 *) PCPDMDEVHLPR0;
5707
5708/** Current PDMDEVHLP version number. */
5709#define PDM_DEVHLPR0_VERSION 0xfb010000
5710
5711
5712
5713/**
5714 * PDM Device Instance.
5715 */
5716typedef struct PDMDEVINS
5717{
5718 /** Structure version. PDM_DEVINS_VERSION defines the current version. */
5719 uint32_t u32Version;
5720 /** Device instance number. */
5721 RTUINT iInstance;
5722 /** The base interface of the device.
5723 * The device constructor initializes this if it has any
5724 * device level interfaces to export. To obtain this interface
5725 * call PDMR3QueryDevice(). */
5726 PDMIBASE IBase;
5727
5728 /** Internal data. */
5729 union
5730 {
5731#ifdef PDMDEVINSINT_DECLARED
5732 PDMDEVINSINT s;
5733#endif
5734 uint8_t padding[HC_ARCH_BITS == 32 ? 48 : 96];
5735 } Internal;
5736
5737 /** Pointer the HC PDM Device API. */
5738 R3PTRTYPE(PCPDMDEVHLP) pDevHlp;
5739 /** Pointer the R0 PDM Device API. */
5740 R0PTRTYPE(PCPDMDEVHLPR0) pDevHlpR0;
5741 /** Pointer to device registration structure. */
5742 R3PTRTYPE(PCPDMDEVREG) pDevReg;
5743 /** Configuration handle. */
5744 R3PTRTYPE(PCFGMNODE) pCfgHandle;
5745 /** Pointer to device instance data. */
5746 R3PTRTYPE(void *) pvInstanceDataR3;
5747 /** Pointer to device instance data. */
5748 R0PTRTYPE(void *) pvInstanceDataR0;
5749 /** Pointer the GC PDM Device API. */
5750 GCPTRTYPE(PCPDMDEVHLPGC) pDevHlpGC;
5751 /** Pointer to device instance data. */
5752 GCPTRTYPE(void *) pvInstanceDataGC;
5753 /* padding to make achInstanceData aligned at 32 byte boundrary. */
5754 uint32_t au32Padding[HC_ARCH_BITS == 32 ? 1 : 6];
5755 /** Device instance data. The size of this area is defined
5756 * in the PDMDEVREG::cbInstanceData field. */
5757 char achInstanceData[8];
5758} PDMDEVINS;
5759
5760/** Current DEVREG version number. */
5761#define PDM_DEVINS_VERSION 0xf3010000
5762
5763/** Converts a pointer to the PDMDEVINS::IBase to a pointer to PDMDEVINS. */
5764#define PDMIBASE_2_PDMDEV(pInterface) ( (PPDMDEVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDEVINS, IBase)) )
5765
5766
5767/** @def PDMDEV_ASSERT_EMT
5768 * Assert that the current thread is the emulation thread.
5769 */
5770#ifdef VBOX_STRICT
5771# define PDMDEV_ASSERT_EMT(pDevIns) pDevIns->pDevHlp->pfnAssertEMT(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5772#else
5773# define PDMDEV_ASSERT_EMT(pDevIns) do { } while (0)
5774#endif
5775
5776/** @def PDMDEV_ASSERT_OTHER
5777 * Assert that the current thread is NOT the emulation thread.
5778 */
5779#ifdef VBOX_STRICT
5780# define PDMDEV_ASSERT_OTHER(pDevIns) pDevIns->pDevHlp->pfnAssertOther(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5781#else
5782# define PDMDEV_ASSERT_OTHER(pDevIns) do { } while (0)
5783#endif
5784
5785/** @def PDMDEV_ASSERT_VMLOCK_OWNER
5786 * Assert that the current thread is owner of the VM lock.
5787 */
5788#ifdef VBOX_STRICT
5789# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) pDevIns->pDevHlp->pfnAssertVMLock(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5790#else
5791# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) do { } while (0)
5792#endif
5793
5794/** @def PDMDEV_SET_ERROR
5795 * Set the VM error. See PDMDevHlpVMSetError() for printf like message formatting.
5796 */
5797#define PDMDEV_SET_ERROR(pDevIns, rc, pszError) \
5798 PDMDevHlpVMSetError(pDevIns, rc, RT_SRC_POS, "%s", pszError)
5799
5800/** @def PDMDEV_SET_RUNTIME_ERROR
5801 * Set the VM runtime error. See PDMDevHlpVMSetRuntimeError() for printf like message formatting.
5802 */
5803#define PDMDEV_SET_RUNTIME_ERROR(pDevIns, fFatal, pszErrorID, pszError) \
5804 PDMDevHlpVMSetRuntimeError(pDevIns, fFatal, pszErrorID, "%s", pszError)
5805
5806/** @def PDMINS2DATA
5807 * Converts a PDM Device or Driver instance pointer to a pointer to the instance data.
5808 */
5809#define PDMINS2DATA(pIns, type) ( (type)(void *)&(pIns)->achInstanceData[0] )
5810
5811/** @def PDMINS2DATA_GCPTR
5812 * Converts a PDM Device or Driver instance pointer to a GC pointer to the instance data.
5813 */
5814#define PDMINS2DATA_GCPTR(pIns) ( (pIns)->pvInstanceDataGC )
5815
5816/** @def PDMINS2DATA_R3PTR
5817 * Converts a PDM Device or Driver instance pointer to a HC pointer to the instance data.
5818 */
5819#define PDMINS2DATA_R3PTR(pIns) ( (pIns)->pvInstanceDataR3 )
5820
5821 /** @def PDMINS2DATA_R0PTR
5822 * Converts a PDM Device or Driver instance pointer to a R0 pointer to the instance data.
5823 */
5824#define PDMINS2DATA_R0PTR(pIns) ( (pIns)->pvInstanceDataR0 )
5825
5826/** @def PDMDEVINS_2_GCPTR
5827 * Converts a PDM Device instance pointer a GC PDM Device instance pointer.
5828 */
5829#define PDMDEVINS_2_GCPTR(pDevIns) ( (GCPTRTYPE(PPDMDEVINS))((RTGCUINTPTR)(pDevIns)->pvInstanceDataGC - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )
5830
5831/** @def PDMDEVINS_2_R3PTR
5832 * Converts a PDM Device instance pointer a HC PDM Device instance pointer.
5833 */
5834#define PDMDEVINS_2_R3PTR(pDevIns) ( (HCPTRTYPE(PPDMDEVINS))((RTHCUINTPTR)(pDevIns)->pvInstanceDataR3 - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )
5835
5836/** @def PDMDEVINS_2_R0PTR
5837 * Converts a PDM Device instance pointer a R0 PDM Device instance pointer.
5838 */
5839#define PDMDEVINS_2_R0PTR(pDevIns) ( (R0PTRTYPE(PPDMDEVINS))((RTR0UINTPTR)(pDevIns)->pvInstanceDataR0 - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )
5840
5841
5842/**
5843 * VBOX_STRICT wrapper for pDevHlp->pfnDBGFStopV.
5844 *
5845 * @returns VBox status code which must be passed up to the VMM.
5846 * @param pDevIns Device instance.
5847 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
5848 * @param pszFormat Message. (optional)
5849 * @param ... Message parameters.
5850 */
5851DECLINLINE(int) PDMDeviceDBGFStop(PPDMDEVINS pDevIns, RT_SRC_POS_DECL, const char *pszFormat, ...)
5852{
5853#ifdef VBOX_STRICT
5854# ifdef IN_RING3
5855 int rc;
5856 va_list args;
5857 va_start(args, pszFormat);
5858 rc = pDevIns->pDevHlp->pfnDBGFStopV(pDevIns, RT_SRC_POS_ARGS, pszFormat, args);
5859 va_end(args);
5860 return rc;
5861# else
5862 return VINF_EM_DBG_STOP;
5863# endif
5864#else
5865 return VINF_SUCCESS;
5866#endif
5867}
5868
5869
5870#ifdef IN_RING3
5871/**
5872 * @copydoc PDMDEVHLP::pfnIOPortRegister
5873 */
5874DECLINLINE(int) PDMDevHlpIOPortRegister(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTHCPTR pvUser,
5875 PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,
5876 PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc)
5877{
5878 return pDevIns->pDevHlp->pfnIOPortRegister(pDevIns, Port, cPorts, pvUser, pfnOut, pfnIn, pfnOutStr, pfnInStr, pszDesc);
5879}
5880
5881/**
5882 * @copydoc PDMDEVHLP::pfnIOPortRegisterGC
5883 */
5884DECLINLINE(int) PDMDevHlpIOPortRegisterGC(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTGCPTR pvUser,
5885 const char *pszOut, const char *pszIn, const char *pszOutStr,
5886 const char *pszInStr, const char *pszDesc)
5887{
5888 return pDevIns->pDevHlp->pfnIOPortRegisterGC(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);
5889}
5890
5891/**
5892 * @copydoc PDMDEVHLP::pfnIOPortRegisterR0
5893 */
5894DECLINLINE(int) PDMDevHlpIOPortRegisterR0(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTR0PTR pvUser,
5895 const char *pszOut, const char *pszIn, const char *pszOutStr,
5896 const char *pszInStr, const char *pszDesc)
5897{
5898 return pDevIns->pDevHlp->pfnIOPortRegisterR0(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);
5899}
5900
5901/**
5902 * @copydoc PDMDEVHLP::pfnMMIORegister
5903 */
5904DECLINLINE(int) PDMDevHlpMMIORegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTHCPTR pvUser,
5905 PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, PFNIOMMMIOFILL pfnFill,
5906 const char *pszDesc)
5907{
5908 return pDevIns->pDevHlp->pfnMMIORegister(pDevIns, GCPhysStart, cbRange, pvUser, pfnWrite, pfnRead, pfnFill, pszDesc);
5909}
5910
5911/**
5912 * @copydoc PDMDEVHLP::pfnMMIORegisterGC
5913 */
5914DECLINLINE(int) PDMDevHlpMMIORegisterGC(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTGCPTR pvUser,
5915 const char *pszWrite, const char *pszRead, const char *pszFill, const char *pszDesc)
5916{
5917 return pDevIns->pDevHlp->pfnMMIORegisterGC(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill, pszDesc);
5918}
5919
5920/**
5921 * @copydoc PDMDEVHLP::pfnMMIORegisterR0
5922 */
5923DECLINLINE(int) PDMDevHlpMMIORegisterR0(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTR0PTR pvUser,
5924 const char *pszWrite, const char *pszRead, const char *pszFill, const char *pszDesc)
5925{
5926 return pDevIns->pDevHlp->pfnMMIORegisterR0(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill, pszDesc);
5927}
5928
5929/**
5930 * @copydoc PDMDEVHLP::pfnROMRegister
5931 */
5932DECLINLINE(int) PDMDevHlpROMRegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, const void *pvBinary, const char *pszDesc)
5933{
5934 return pDevIns->pDevHlp->pfnROMRegister(pDevIns, GCPhysStart, cbRange, pvBinary, pszDesc);
5935}
5936
5937/**
5938 * @copydoc PDMDEVHLP::pfnSSMRegister
5939 */
5940DECLINLINE(int) PDMDevHlpSSMRegister(PPDMDEVINS pDevIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
5941 PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
5942 PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone)
5943{
5944 return pDevIns->pDevHlp->pfnSSMRegister(pDevIns, pszName, u32Instance, u32Version, cbGuess,
5945 pfnSavePrep, pfnSaveExec, pfnSaveDone,
5946 pfnLoadPrep, pfnLoadExec, pfnLoadDone);
5947}
5948
5949/**
5950 * @copydoc PDMDEVHLP::pfnTMTimerCreate
5951 */
5952DECLINLINE(int) PDMDevHlpTMTimerCreate(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer)
5953{
5954 return pDevIns->pDevHlp->pfnTMTimerCreate(pDevIns, enmClock, pfnCallback, pszDesc, ppTimer);
5955}
5956
5957/**
5958 * @copydoc PDMDEVHLP::pfnPCIRegister
5959 */
5960DECLINLINE(int) PDMDevHlpPCIRegister(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev)
5961{
5962 return pDevIns->pDevHlp->pfnPCIRegister(pDevIns, pPciDev);
5963}
5964
5965/**
5966 * @copydoc PDMDEVHLP::pfnPCIIORegionRegister
5967 */
5968DECLINLINE(int) PDMDevHlpPCIIORegionRegister(PPDMDEVINS pDevIns, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback)
5969{
5970 return pDevIns->pDevHlp->pfnPCIIORegionRegister(pDevIns, iRegion, cbRegion, enmType, pfnCallback);
5971}
5972
5973/**
5974 * @copydoc PDMDEVHLP::pfnPCISetConfigCallbacks
5975 */
5976DECLINLINE(void) PDMDevHlpPCISetConfigCallbacks(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,
5977 PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld)
5978{
5979 pDevIns->pDevHlp->pfnPCISetConfigCallbacks(pDevIns, pPciDev, pfnRead, ppfnReadOld, pfnWrite, ppfnWriteOld);
5980}
5981
5982/**
5983 * @copydoc PDMDEVHLP::pfnDriverAttach
5984 */
5985DECLINLINE(int) PDMDevHlpDriverAttach(PPDMDEVINS pDevIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE *ppBaseInterface, const char *pszDesc)
5986{
5987 return pDevIns->pDevHlp->pfnDriverAttach(pDevIns, iLun, pBaseInterface, ppBaseInterface, pszDesc);
5988}
5989
5990/**
5991 * @copydoc PDMDEVHLP::pfnMMHeapAlloc
5992 */
5993DECLINLINE(void *) PDMDevHlpMMHeapAlloc(PPDMDEVINS pDevIns, size_t cb)
5994{
5995 return pDevIns->pDevHlp->pfnMMHeapAlloc(pDevIns, cb);
5996}
5997
5998/**
5999 * @copydoc PDMDEVHLP::pfnMMHeapAllocZ
6000 */
6001DECLINLINE(void *) PDMDevHlpMMHeapAllocZ(PPDMDEVINS pDevIns, size_t cb)
6002{
6003 return pDevIns->pDevHlp->pfnMMHeapAllocZ(pDevIns, cb);
6004}
6005
6006/**
6007 * @copydoc PDMDEVHLP::pfnMMHeapFree
6008 */
6009DECLINLINE(void) PDMDevHlpMMHeapFree(PPDMDEVINS pDevIns, void *pv)
6010{
6011 pDevIns->pDevHlp->pfnMMHeapFree(pDevIns, pv);
6012}
6013
6014/**
6015 * @copydoc PDMDEVHLP::pfnDBGFInfoRegister
6016 */
6017DECLINLINE(int) PDMDevHlpDBGFInfoRegister(PPDMDEVINS pDevIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDEV pfnHandler)
6018{
6019 return pDevIns->pDevHlp->pfnDBGFInfoRegister(pDevIns, pszName, pszDesc, pfnHandler);
6020}
6021
6022/**
6023 * @copydoc PDMDEVHLP::pfnSTAMRegister
6024 */
6025DECLINLINE(void) PDMDevHlpSTAMRegister(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
6026{
6027 pDevIns->pDevHlp->pfnSTAMRegister(pDevIns, pvSample, enmType, pszName, enmUnit, pszDesc);
6028}
6029
6030/**
6031 * @copydoc PDMDEVHLP::pfnSTAMRegisterF
6032 */
6033DECLINLINE(void) PDMDevHlpSTAMRegisterF(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
6034 const char *pszDesc, const char *pszName, ...)
6035{
6036 va_list va;
6037 va_start(va, pszName);
6038 pDevIns->pDevHlp->pfnSTAMRegisterV(pDevIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
6039 va_end(va);
6040}
6041
6042/**
6043 * @copydoc PDMDEVHLP::pfnPDMQueueCreate
6044 */
6045DECLINLINE(int) PDMDevHlpPDMQueueCreate(PPDMDEVINS pDevIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
6046 PFNPDMQUEUEDEV pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue)
6047{
6048 return pDevIns->pDevHlp->pfnPDMQueueCreate(pDevIns, cbItem, cItems, cMilliesInterval, pfnCallback, fGCEnabled, ppQueue);
6049}
6050
6051/**
6052 * @copydoc PDMDEVHLP::pfnCritSectInit
6053 */
6054DECLINLINE(int) PDMDevHlpCritSectInit(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, const char *pszName)
6055{
6056 return pDevIns->pDevHlp->pfnCritSectInit(pDevIns, pCritSect, pszName);
6057}
6058
6059/**
6060 * @copydoc PDMDEVHLP::pfnUTCNow
6061 */
6062DECLINLINE(PRTTIMESPEC) PDMDevHlpUTCNow(PPDMDEVINS pDevIns, PRTTIMESPEC pTime)
6063{
6064 return pDevIns->pDevHlp->pfnUTCNow(pDevIns, pTime);
6065}
6066
6067/**
6068 * @copydoc PDMDEVHLP::pfnGetVM
6069 */
6070DECLINLINE(PVM) PDMDevHlpGetVM(PPDMDEVINS pDevIns)
6071{
6072 return pDevIns->pDevHlp->pfnGetVM(pDevIns);
6073}
6074
6075/**
6076 * @copydoc PDMDEVHLP::pfnPhysReadGCVirt
6077 */
6078DECLINLINE(int) PDMDevHlpPhysReadGCVirt(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb)
6079{
6080 return pDevIns->pDevHlp->pfnPhysReadGCVirt(pDevIns, pvDst, GCVirtSrc, cb);
6081}
6082
6083/**
6084 * @copydoc PDMDEVHLP::pfnPhysWriteGCVirt
6085 */
6086DECLINLINE(int) PDMDevHlpPhysWriteGCVirt(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb)
6087{
6088 return pDevIns->pDevHlp->pfnPhysWriteGCVirt(pDevIns, GCVirtDst, pvSrc, cb);
6089}
6090
6091/**
6092 * @copydoc PDMDEVHLP::pfnPhysReserve
6093 */
6094DECLINLINE(int) PDMDevHlpPhysReserve(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const char *pszDesc)
6095{
6096 return pDevIns->pDevHlp->pfnPhysReserve(pDevIns, GCPhys, cbRange, pszDesc);
6097}
6098
6099/**
6100 * @copydoc PDMDEVHLP::pfnPhys2HCVirt
6101 */
6102DECLINLINE(int) PDMDevHlpPhys2HCVirt(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, PRTHCPTR ppvHC)
6103{
6104 return pDevIns->pDevHlp->pfnPhys2HCVirt(pDevIns, GCPhys, cbRange, ppvHC);
6105}
6106
6107/**
6108 * @copydoc PDMDEVHLP::pfnPhysGCPtr2HCPtr
6109 */
6110DECLINLINE(int) PDMDevHlpPhysGCPtr2HCPtr(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTHCPTR pHCPtr)
6111{
6112 return pDevIns->pDevHlp->pfnPhysGCPtr2HCPtr(pDevIns, GCPtr, pHCPtr);
6113}
6114
6115/**
6116 * @copydoc PDMDEVHLP::pfnA20Set
6117 */
6118DECLINLINE(void) PDMDevHlpA20Set(PPDMDEVINS pDevIns, bool fEnable)
6119{
6120 pDevIns->pDevHlp->pfnA20Set(pDevIns, fEnable);
6121}
6122
6123/**
6124 * @copydoc PDMDEVHLP::pfnVMReset
6125 */
6126DECLINLINE(int) PDMDevHlpVMReset(PPDMDEVINS pDevIns)
6127{
6128 return pDevIns->pDevHlp->pfnVMReset(pDevIns);
6129}
6130
6131/**
6132 * @copydoc PDMDEVHLP::pfnVMSuspend
6133 */
6134DECLINLINE(int) PDMDevHlpVMSuspend(PPDMDEVINS pDevIns)
6135{
6136 return pDevIns->pDevHlp->pfnVMSuspend(pDevIns);
6137}
6138
6139/**
6140 * @copydoc PDMDEVHLP::pfnVMPowerOff
6141 */
6142DECLINLINE(int) PDMDevHlpVMPowerOff(PPDMDEVINS pDevIns)
6143{
6144 return pDevIns->pDevHlp->pfnVMPowerOff(pDevIns);
6145}
6146
6147/**
6148 * @copydoc PDMDEVHLP::pfnDMARegister
6149 */
6150DECLINLINE(int) PDMDevHlpDMARegister(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser)
6151{
6152 return pDevIns->pDevHlp->pfnDMARegister(pDevIns, uChannel, pfnTransferHandler, pvUser);
6153}
6154
6155/**
6156 * @copydoc PDMDEVHLP::pfnDMAReadMemory
6157 */
6158DECLINLINE(int) PDMDevHlpDMAReadMemory(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbRead)
6159{
6160 return pDevIns->pDevHlp->pfnDMAReadMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbRead);
6161}
6162
6163/**
6164 * @copydoc PDMDEVHLP::pfnDMAWriteMemory
6165 */
6166DECLINLINE(int) PDMDevHlpDMAWriteMemory(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbWritten)
6167{
6168 return pDevIns->pDevHlp->pfnDMAWriteMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbWritten);
6169}
6170
6171/**
6172 * @copydoc PDMDEVHLP::pfnDMASetDREQ
6173 */
6174DECLINLINE(int) PDMDevHlpDMASetDREQ(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel)
6175{
6176 return pDevIns->pDevHlp->pfnDMASetDREQ(pDevIns, uChannel, uLevel);
6177}
6178
6179/**
6180 * @copydoc PDMDEVHLP::pfnDMAGetChannelMode
6181 */
6182DECLINLINE(uint8_t) PDMDevHlpDMAGetChannelMode(PPDMDEVINS pDevIns, unsigned uChannel)
6183{
6184 return pDevIns->pDevHlp->pfnDMAGetChannelMode(pDevIns, uChannel);
6185}
6186
6187/**
6188 * @copydoc PDMDEVHLP::pfnDMASchedule
6189 */
6190DECLINLINE(void) PDMDevHlpDMASchedule(PPDMDEVINS pDevIns)
6191{
6192 pDevIns->pDevHlp->pfnDMASchedule(pDevIns);
6193}
6194
6195/**
6196 * @copydoc PDMDEVHLP::pfnCMOSWrite
6197 */
6198DECLINLINE(int) PDMDevHlpCMOSWrite(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value)
6199{
6200 return pDevIns->pDevHlp->pfnCMOSWrite(pDevIns, iReg, u8Value);
6201}
6202
6203/**
6204 * @copydoc PDMDEVHLP::pfnCMOSRead
6205 */
6206DECLINLINE(int) PDMDevHlpCMOSRead(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value)
6207{
6208 return pDevIns->pDevHlp->pfnCMOSRead(pDevIns, iReg, pu8Value);
6209}
6210
6211/**
6212 * @copydoc PDMDEVHLP::pfnGetCpuId
6213 */
6214DECLINLINE(void) PDMDevHlpGetCpuId(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t *pEax, uint32_t *pEbx, uint32_t *pEcx, uint32_t *pEdx)
6215{
6216 pDevIns->pDevHlp->pfnGetCpuId(pDevIns, iLeaf, pEax, pEbx, pEcx, pEdx);
6217}
6218#endif /* IN_RING3 */
6219
6220
6221/**
6222 * @copydoc PDMDEVHLP::pfnPCISetIrq
6223 */
6224DECLINLINE(void) PDMDevHlpPCISetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
6225{
6226#ifdef IN_GC
6227 pDevIns->pDevHlpGC->pfnPCISetIrq(pDevIns, iIrq, iLevel);
6228#elif defined(IN_RING0)
6229 pDevIns->pDevHlpR0->pfnPCISetIrq(pDevIns, iIrq, iLevel);
6230#else
6231 pDevIns->pDevHlp->pfnPCISetIrq(pDevIns, iIrq, iLevel);
6232#endif
6233}
6234
6235/**
6236 * @copydoc PDMDEVHLP::pfnPCISetIrqNoWait
6237 */
6238DECLINLINE(void) PDMDevHlpPCISetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
6239{
6240#ifdef IN_GC
6241 pDevIns->pDevHlpGC->pfnPCISetIrq(pDevIns, iIrq, iLevel);
6242#elif defined(IN_RING0)
6243 pDevIns->pDevHlpR0->pfnPCISetIrq(pDevIns, iIrq, iLevel);
6244#else
6245 pDevIns->pDevHlp->pfnPCISetIrqNoWait(pDevIns, iIrq, iLevel);
6246#endif
6247}
6248
6249/**
6250 * @copydoc PDMDEVHLP::pfnISASetIrq
6251 */
6252DECLINLINE(void) PDMDevHlpISASetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
6253{
6254#ifdef IN_GC
6255 pDevIns->pDevHlpGC->pfnISASetIrq(pDevIns, iIrq, iLevel);
6256#elif defined(IN_RING0)
6257 pDevIns->pDevHlpR0->pfnISASetIrq(pDevIns, iIrq, iLevel);
6258#else
6259 pDevIns->pDevHlp->pfnISASetIrq(pDevIns, iIrq, iLevel);
6260#endif
6261}
6262
6263/**
6264 * @copydoc PDMDEVHLP::pfnISASetIrqNoWait
6265 */
6266DECLINLINE(void) PDMDevHlpISASetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
6267{
6268#ifdef IN_GC
6269 pDevIns->pDevHlpGC->pfnISASetIrq(pDevIns, iIrq, iLevel);
6270#elif defined(IN_RING0)
6271 pDevIns->pDevHlpR0->pfnISASetIrq(pDevIns, iIrq, iLevel);
6272#else
6273 pDevIns->pDevHlp->pfnISASetIrqNoWait(pDevIns, iIrq, iLevel);
6274#endif
6275}
6276
6277/**
6278 * @copydoc PDMDEVHLP::pfnPhysRead
6279 */
6280DECLINLINE(void) PDMDevHlpPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
6281{
6282#ifdef IN_GC
6283 pDevIns->pDevHlpGC->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
6284#elif defined(IN_RING0)
6285 pDevIns->pDevHlpR0->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
6286#else
6287 pDevIns->pDevHlp->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
6288#endif
6289}
6290
6291/**
6292 * @copydoc PDMDEVHLP::pfnPhysWrite
6293 */
6294DECLINLINE(void) PDMDevHlpPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
6295{
6296#ifdef IN_GC
6297 pDevIns->pDevHlpGC->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
6298#elif defined(IN_RING0)
6299 pDevIns->pDevHlpR0->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
6300#else
6301 pDevIns->pDevHlp->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
6302#endif
6303}
6304
6305/**
6306 * @copydoc PDMDEVHLP::pfnA20IsEnabled
6307 */
6308DECLINLINE(bool) PDMDevHlpA20IsEnabled(PPDMDEVINS pDevIns)
6309{
6310#ifdef IN_GC
6311 return pDevIns->pDevHlpGC->pfnA20IsEnabled(pDevIns);
6312#elif defined(IN_RING0)
6313 return pDevIns->pDevHlpR0->pfnA20IsEnabled(pDevIns);
6314#else
6315 return pDevIns->pDevHlp->pfnA20IsEnabled(pDevIns);
6316#endif
6317}
6318
6319/**
6320 * @copydoc PDMDEVHLP::pfnVMSetError
6321 */
6322DECLINLINE(int) PDMDevHlpVMSetError(PPDMDEVINS pDevIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
6323{
6324 va_list va;
6325 va_start(va, pszFormat);
6326#ifdef IN_GC
6327 pDevIns->pDevHlpGC->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
6328#elif defined(IN_RING0)
6329 pDevIns->pDevHlpR0->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
6330#else
6331 pDevIns->pDevHlp->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
6332#endif
6333 va_end(va);
6334 return rc;
6335}
6336
6337/**
6338 * @copydoc PDMDEVHLP::pfnVMSetRuntimeError
6339 */
6340DECLINLINE(int) PDMDevHlpVMSetRuntimeError(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...)
6341{
6342 va_list va;
6343 int rc;
6344 va_start(va, pszFormat);
6345#ifdef IN_GC
6346 rc = pDevIns->pDevHlpGC->pfnVMSetRuntimeErrorV(pDevIns, fFatal, pszErrorID, pszFormat, va);
6347#elif defined(IN_RING0)
6348 rc = pDevIns->pDevHlpR0->pfnVMSetRuntimeErrorV(pDevIns, fFatal, pszErrorID, pszFormat, va);
6349#else
6350 rc = pDevIns->pDevHlp->pfnVMSetRuntimeErrorV(pDevIns, fFatal, pszErrorID, pszFormat, va);
6351#endif
6352 va_end(va);
6353 return rc;
6354}
6355
6356
6357
6358/** Pointer to callbacks provided to the VBoxDeviceRegister() call. */
6359typedef struct PDMDEVREGCB *PPDMDEVREGCB;
6360
6361/**
6362 * Callbacks for VBoxDeviceRegister().
6363 */
6364typedef struct PDMDEVREGCB
6365{
6366 /** Interface version.
6367 * This is set to PDM_DEVREG_CB_VERSION. */
6368 uint32_t u32Version;
6369
6370 /**
6371 * Registers a device with the current VM instance.
6372 *
6373 * @returns VBox status code.
6374 * @param pCallbacks Pointer to the callback table.
6375 * @param pDevReg Pointer to the device registration record.
6376 * This data must be permanent and readonly.
6377 */
6378 DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMDEVREGCB pCallbacks, PCPDMDEVREG pDevReg));
6379
6380 /**
6381 * Allocate memory which is associated with current VM instance
6382 * and automatically freed on it's destruction.
6383 *
6384 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
6385 * @param pCallbacks Pointer to the callback table.
6386 * @param cb Number of bytes to allocate.
6387 */
6388 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVREGCB pCallbacks, size_t cb));
6389} PDMDEVREGCB;
6390
6391/** Current version of the PDMDEVREGCB structure. */
6392#define PDM_DEVREG_CB_VERSION 0xf4010000
6393
6394
6395/**
6396 * The VBoxDevicesRegister callback function.
6397 *
6398 * PDM will invoke this function after loading a device module and letting
6399 * the module decide which devices to register and how to handle conflicts.
6400 *
6401 * @returns VBox status code.
6402 * @param pCallbacks Pointer to the callback table.
6403 * @param u32Version VBox version number.
6404 */
6405typedef DECLCALLBACK(int) FNPDMVBOXDEVICESREGISTER(PPDMDEVREGCB pCallbacks, uint32_t u32Version);
6406
6407/** @} */
6408
6409
6410
6411
6412/** @defgroup grp_pdm_services Services
6413 * @ingroup grp_pdm
6414 * @{ */
6415
6416
6417/**
6418 * Construct a service instance for a VM.
6419 *
6420 * @returns VBox status.
6421 * @param pSrvIns The service instance data.
6422 * If the registration structure is needed, pSrvIns->pReg points to it.
6423 * @param pCfg Configuration node handle for the service. Use this to obtain the configuration
6424 * of the driver instance. It's also found in pSrvIns->pCfg, but since it's primary
6425 * usage is expected in this function it is passed as a parameter.
6426 */
6427typedef DECLCALLBACK(int) FNPDMSRVCONSTRUCT(PPDMSRVINS pSrvIns, PCFGMNODE pCfg);
6428/** Pointer to a FNPDMSRVCONSTRUCT() function. */
6429typedef FNPDMSRVCONSTRUCT *PFNPDMSRVCONSTRUCT;
6430
6431/**
6432 * Destruct a driver instance.
6433 *
6434 * Most VM resources are freed by the VM. This callback is provided so that any non-VM
6435 * resources can be freed correctly.
6436 *
6437 * @param pSrvIns The service instance data.
6438 */
6439typedef DECLCALLBACK(void) FNPDMSRVDESTRUCT(PPDMSRVINS pSrvIns);
6440/** Pointer to a FNPDMSRVDESTRUCT() function. */
6441typedef FNPDMSRVDESTRUCT *PFNPDMSRVDESTRUCT;
6442
6443/**
6444 * Power On notification.
6445 *
6446 * @param pSrvIns The service instance data.
6447 */
6448typedef DECLCALLBACK(void) FNPDMSRVPOWERON(PPDMSRVINS pSrvIns);
6449/** Pointer to a FNPDMSRVPOWERON() function. */
6450typedef FNPDMSRVPOWERON *PFNPDMSRVPOWERON;
6451
6452/**
6453 * Reset notification.
6454 *
6455 * @returns VBox status.
6456 * @param pSrvIns The service instance data.
6457 */
6458typedef DECLCALLBACK(void) FNPDMSRVRESET(PPDMSRVINS pSrvIns);
6459/** Pointer to a FNPDMSRVRESET() function. */
6460typedef FNPDMSRVRESET *PFNPDMSRVRESET;
6461
6462/**
6463 * Suspend notification.
6464 *
6465 * @returns VBox status.
6466 * @param pSrvIns The service instance data.
6467 */
6468typedef DECLCALLBACK(void) FNPDMSRVSUSPEND(PPDMSRVINS pSrvIns);
6469/** Pointer to a FNPDMSRVSUSPEND() function. */
6470typedef FNPDMSRVSUSPEND *PFNPDMSRVSUSPEND;
6471
6472/**
6473 * Resume notification.
6474 *
6475 * @returns VBox status.
6476 * @param pSrvIns The service instance data.
6477 */
6478typedef DECLCALLBACK(void) FNPDMSRVRESUME(PPDMSRVINS pSrvIns);
6479/** Pointer to a FNPDMSRVRESUME() function. */
6480typedef FNPDMSRVRESUME *PFNPDMSRVRESUME;
6481
6482/**
6483 * Power Off notification.
6484 *
6485 * @param pSrvIns The service instance data.
6486 */
6487typedef DECLCALLBACK(void) FNPDMSRVPOWEROFF(PPDMSRVINS pSrvIns);
6488/** Pointer to a FNPDMSRVPOWEROFF() function. */
6489typedef FNPDMSRVPOWEROFF *PFNPDMSRVPOWEROFF;
6490
6491/**
6492 * Detach notification.
6493 *
6494 * This is called when a driver or device is detached from the service
6495 *
6496 * @param pSrvIns The service instance data.
6497 */
6498typedef DECLCALLBACK(void) FNPDMSRVDETACH(PPDMSRVINS pSrvIns, PPDMDEVINS pDevIns, PPDMDRVINS pDrvIns);
6499/** Pointer to a FNPDMSRVDETACH() function. */
6500typedef FNPDMSRVDETACH *PFNPDMSRVDETACH;
6501
6502
6503
6504/** PDM Service Registration Structure,
6505 * This structure is used when registering a driver from
6506 * VBoxServicesRegister() (HC Ring-3). PDM will continue use till
6507 * the VM is terminated.
6508 */
6509typedef struct PDMSRVREG
6510{
6511 /** Structure version. PDM_SRVREG_VERSION defines the current version. */
6512 uint32_t u32Version;
6513 /** Driver name. */
6514 char szServiceName[32];
6515 /** The description of the driver. The UTF-8 string pointed to shall, like this structure,
6516 * remain unchanged from registration till VM destruction. */
6517 const char *pszDescription;
6518
6519 /** Flags, combination of the PDM_SRVREG_FLAGS_* \#defines. */
6520 RTUINT fFlags;
6521 /** Size of the instance data. */
6522 RTUINT cbInstance;
6523
6524 /** Construct instance - required. */
6525 PFNPDMSRVCONSTRUCT pfnConstruct;
6526 /** Destruct instance - optional. */
6527 PFNPDMSRVDESTRUCT pfnDestruct;
6528 /** Power on notification - optional. */
6529 PFNPDMSRVPOWERON pfnPowerOn;
6530 /** Reset notification - optional. */
6531 PFNPDMSRVRESET pfnReset;
6532 /** Suspend notification - optional. */
6533 PFNPDMSRVSUSPEND pfnSuspend;
6534 /** Resume notification - optional. */
6535 PFNPDMSRVRESUME pfnResume;
6536 /** Detach notification - optional. */
6537 PFNPDMSRVDETACH pfnDetach;
6538 /** Power off notification - optional. */
6539 PFNPDMSRVPOWEROFF pfnPowerOff;
6540
6541} PDMSRVREG;
6542/** Pointer to a PDM Driver Structure. */
6543typedef PDMSRVREG *PPDMSRVREG;
6544/** Const pointer to a PDM Driver Structure. */
6545typedef PDMSRVREG const *PCPDMSRVREG;
6546
6547
6548
6549/**
6550 * PDM Service API.
6551 */
6552typedef struct PDMSRVHLP
6553{
6554 /** Structure version. PDM_SRVHLP_VERSION defines the current version. */
6555 uint32_t u32Version;
6556
6557 /**
6558 * Assert that the current thread is the emulation thread.
6559 *
6560 * @returns True if correct.
6561 * @returns False if wrong.
6562 * @param pSrvIns Service instance.
6563 * @param pszFile Filename of the assertion location.
6564 * @param iLine Linenumber of the assertion location.
6565 * @param pszFunction Function of the assertion location.
6566 */
6567 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMSRVINS pSrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
6568
6569 /**
6570 * Assert that the current thread is NOT the emulation thread.
6571 *
6572 * @returns True if correct.
6573 * @returns False if wrong.
6574 * @param pSrvIns Service instance.
6575 * @param pszFile Filename of the assertion location.
6576 * @param iLine Linenumber of the assertion location.
6577 * @param pszFunction Function of the assertion location.
6578 */
6579 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMSRVINS pSrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
6580
6581 /**
6582 * Creates a timer.
6583 *
6584 * @returns VBox status.
6585 * @param pVM The VM to create the timer in.
6586 * @param pSrvIns Service instance.
6587 * @param enmClock The clock to use on this timer.
6588 * @param pfnCallback Callback function.
6589 * @param pszDesc Pointer to description string which must stay around
6590 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
6591 * @param ppTimer Where to store the timer on success.
6592 */
6593 DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMSRVINS pSrvIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer));
6594
6595 /**
6596 * Query the virtual timer frequency.
6597 *
6598 * @returns Frequency in Hz.
6599 * @param pSrvIns Service instance.
6600 * @thread Any thread.
6601 */
6602 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualFreq,(PPDMSRVINS pSrvIns));
6603
6604 /**
6605 * Query the virtual time.
6606 *
6607 * @returns The current virtual time.
6608 * @param pSrvIns Service instance.
6609 * @thread Any thread.
6610 */
6611 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualTime,(PPDMSRVINS pSrvIns));
6612
6613} PDMSRVHLP;
6614/** Pointer PDM Service API. */
6615typedef PDMSRVHLP *PPDMSRVHLP;
6616/** Pointer const PDM Service API. */
6617typedef const PDMSRVHLP *PCPDMSRVHLP;
6618
6619/** Current SRVHLP version number. */
6620#define PDM_SRVHLP_VERSION 0xf9010000
6621
6622
6623/**
6624 * PDM Service Instance.
6625 */
6626typedef struct PDMSRVINS
6627{
6628 /** Structure version. PDM_SRVINS_VERSION defines the current version. */
6629 uint32_t u32Version;
6630
6631 /** Internal data. */
6632 union
6633 {
6634#ifdef PDMSRVINSINT_DECLARED
6635 PDMSRVINSINT s;
6636#endif
6637 uint8_t padding[HC_ARCH_BITS == 32 ? 32 : 32];
6638 } Internal;
6639
6640 /** Pointer the PDM Service API. */
6641 HCPTRTYPE(PCPDMSRVHLP) pHlp;
6642 /** Pointer to driver registration structure. */
6643 HCPTRTYPE(PCPDMSRVREG) pReg;
6644 /** Configuration handle. */
6645 HCPTRTYPE(PCFGMNODE) pCfg;
6646 /** The base interface of the service.
6647 * The service constructor initializes this. */
6648 PDMIBASE IBase;
6649 /* padding to make achInstanceData aligned at 16 byte boundrary. */
6650 uint32_t au32Padding[2];
6651 /** Pointer to driver instance data. */
6652 HCPTRTYPE(void *) pvInstanceData;
6653 /** Driver instance data. The size of this area is defined
6654 * in the PDMSRVREG::cbInstanceData field. */
6655 char achInstanceData[4];
6656} PDMSRVINS;
6657
6658/** Current PDMSRVREG version number. */
6659#define PDM_SRVINS_VERSION 0xf7010000
6660
6661/** Converts a pointer to the PDMSRVINS::IBase to a pointer to PDMSRVINS. */
6662#define PDMIBASE_2_PDMSRV(pInterface) ( (PPDMSRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMSRVINS, IBase)) )
6663
6664
6665
6666/** Pointer to callbacks provided to the VBoxServiceRegister() call. */
6667typedef struct PDMSRVREGCB *PPDMSRVREGCB;
6668
6669/**
6670 * Callbacks for VBoxServiceRegister().
6671 */
6672typedef struct PDMSRVREGCB
6673{
6674 /** Interface version.
6675 * This is set to PDM_SRVREG_CB_VERSION. */
6676 uint32_t u32Version;
6677
6678 /**
6679 * Registers a service with the current VM instance.
6680 *
6681 * @returns VBox status code.
6682 * @param pCallbacks Pointer to the callback table.
6683 * @param pSrvReg Pointer to the device registration record.
6684 * This data must be permanent and readonly.
6685 */
6686 DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMSRVREGCB pCallbacks, PCPDMSRVREG pSrvReg));
6687} PDMSRVREGCB;
6688
6689/** Current version of the PDMSRVREGCB structure. */
6690#define PDM_SRVREG_CB_VERSION 0xf8010000
6691
6692
6693/**
6694 * The VBoxServicesRegister callback function.
6695 *
6696 * PDM will invoke this function after loading a device module and letting
6697 * the module decide which devices to register and how to handle conflicts.
6698 *
6699 * @returns VBox status code.
6700 * @param pCallbacks Pointer to the callback table.
6701 * @param u32Version VBox version number.
6702 */
6703typedef DECLCALLBACK(int) FNPDMVBOXSERVICESREGISTER(PPDMSRVREGCB pCallbacks, uint32_t u32Version);
6704
6705
6706/** @} */
6707
6708/**
6709 * Gets the pending interrupt.
6710 *
6711 * @returns VBox status code.
6712 * @param pVM VM handle.
6713 * @param pu8Interrupt Where to store the interrupt on success.
6714 */
6715PDMDECL(int) PDMGetInterrupt(PVM pVM, uint8_t *pu8Interrupt);
6716
6717/**
6718 * Sets the pending ISA interrupt.
6719 *
6720 * @returns VBox status code.
6721 * @param pVM VM handle.
6722 * @param u8Irq The IRQ line.
6723 * @param u8Level The new level. See the PDM_IRQ_LEVEL_* \#defines.
6724 */
6725PDMDECL(int) PDMIsaSetIrq(PVM pVM, uint8_t u8Irq, uint8_t u8Level);
6726
6727/**
6728 * Sets the pending I/O APIC interrupt.
6729 *
6730 * @returns VBox status code.
6731 * @param pVM VM handle.
6732 * @param u8Irq The IRQ line.
6733 * @param u8Level The new level. See the PDM_IRQ_LEVEL_* \#defines.
6734 */
6735PDMDECL(int) PDMIoApicSetIrq(PVM pVM, uint8_t u8Irq, uint8_t u8Level);
6736
6737/**
6738 * Set the APIC base.
6739 *
6740 * @returns VBox status code.
6741 * @param pVM VM handle.
6742 * @param u64Base The new base.
6743 */
6744PDMDECL(int) PDMApicSetBase(PVM pVM, uint64_t u64Base);
6745
6746/**
6747 * Get the APIC base.
6748 *
6749 * @returns VBox status code.
6750 * @param pVM VM handle.
6751 * @param pu64Base Where to store the APIC base.
6752 */
6753PDMDECL(int) PDMApicGetBase(PVM pVM, uint64_t *pu64Base);
6754
6755/**
6756 * Set the TPR (task priority register?).
6757 *
6758 * @returns VBox status code.
6759 * @param pVM VM handle.
6760 * @param u8TPR The new TPR.
6761 */
6762PDMDECL(int) PDMApicSetTPR(PVM pVM, uint8_t u8TPR);
6763
6764/**
6765 * Get the TPR (task priority register?).
6766 *
6767 * @returns The current TPR.
6768 * @param pVM VM handle.
6769 * @param pu8TPR Where to store the TRP.
6770 */
6771PDMDECL(int) PDMApicGetTPR(PVM pVM, uint8_t *pu8TPR);
6772
6773
6774#ifdef IN_RING3
6775/** @defgroup grp_pdm_r3 The PDM Host Context Ring-3 API
6776 * @ingroup grp_pdm
6777 * @{
6778 */
6779
6780/**
6781 * Initializes the PDM.
6782 *
6783 * @returns VBox status code.
6784 * @param pVM The VM to operate on.
6785 */
6786PDMR3DECL(int) PDMR3Init(PVM pVM);
6787
6788/**
6789 * This function will notify all the devices and their
6790 * attached drivers about the VM now being powered on.
6791 *
6792 * @param pVM VM Handle.
6793 */
6794PDMR3DECL(void) PDMR3PowerOn(PVM pVM);
6795
6796/**
6797 * This function will notify all the devices and their
6798 * attached drivers about the VM now being reset.
6799 *
6800 * @param pVM VM Handle.
6801 */
6802PDMR3DECL(void) PDMR3Reset(PVM pVM);
6803
6804/**
6805 * This function will notify all the devices and their
6806 * attached drivers about the VM now being suspended.
6807 *
6808 * @param pVM VM Handle.
6809 */
6810PDMR3DECL(void) PDMR3Suspend(PVM pVM);
6811
6812/**
6813 * This function will notify all the devices and their
6814 * attached drivers about the VM now being resumed.
6815 *
6816 * @param pVM VM Handle.
6817 */
6818PDMR3DECL(void) PDMR3Resume(PVM pVM);
6819
6820/**
6821 * This function will notify all the devices and their
6822 * attached drivers about the VM being powered off.
6823 *
6824 * @param pVM VM Handle.
6825 */
6826PDMR3DECL(void) PDMR3PowerOff(PVM pVM);
6827
6828
6829/**
6830 * Applies relocations to GC modules.
6831 *
6832 * This must be done very early in the relocation
6833 * process so that components can resolve GC symbols during relocation.
6834 *
6835 * @param pVM VM handle.
6836 * @param offDelta Relocation delta relative to old location.
6837 */
6838PDMR3DECL(void) PDMR3LdrRelocate(PVM pVM, RTGCINTPTR offDelta);
6839
6840/**
6841 * Applies relocations to data and code managed by this
6842 * component. This function will be called at init and
6843 * whenever the VMM need to relocate it self inside the GC.
6844 *
6845 * @param pVM VM handle.
6846 * @param offDelta Relocation delta relative to old location.
6847 */
6848PDMR3DECL(void) PDMR3Relocate(PVM pVM, RTGCINTPTR offDelta);
6849
6850/**
6851 * Terminates the PDM.
6852 *
6853 * Termination means cleaning up and freeing all resources,
6854 * the VM it self is at this point powered off or suspended.
6855 *
6856 * @returns VBox status code.
6857 * @param pVM The VM to operate on.
6858 */
6859PDMR3DECL(int) PDMR3Term(PVM pVM);
6860
6861
6862/**
6863 * Get the address of a symbol in a given HC ring-3 module.
6864 *
6865 * @returns VBox status code.
6866 * @param pVM VM handle.
6867 * @param pszModule Module name.
6868 * @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
6869 * ordinal value rather than a string pointer.
6870 * @param ppvValue Where to store the symbol value.
6871 */
6872PDMR3DECL(int) PDMR3GetSymbolR3(PVM pVM, const char *pszModule, const char *pszSymbol, void **ppvValue);
6873
6874/**
6875 * Get the address of a symbol in a given HC ring-0 module.
6876 *
6877 * @returns VBox status code.
6878 * @param pVM VM handle.
6879 * @param pszModule Module name. If NULL the main R0 module (VMMR0.r0) is assumed.
6880 * @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
6881 * ordinal value rather than a string pointer.
6882 * @param ppvValue Where to store the symbol value.
6883 */
6884PDMR3DECL(int) PDMR3GetSymbolR0(PVM pVM, const char *pszModule, const char *pszSymbol, PRTR0PTR ppvValue);
6885
6886/**
6887 * Same as PDMR3GetSymbolR0 except that the module will be attempted loaded if not found.
6888 *
6889 * @returns VBox status code.
6890 * @param pVM VM handle.
6891 * @param pszModule Module name. If NULL the main R0 module (VMMR0.r0) is assumed.
6892 * @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
6893 * ordinal value rather than a string pointer.
6894 * @param ppvValue Where to store the symbol value.
6895 */
6896PDMR3DECL(int) PDMR3GetSymbolR0Lazy(PVM pVM, const char *pszModule, const char *pszSymbol, PRTR0PTR ppvValue);
6897
6898/**
6899 * Loads a module into the guest context (i.e. into the Hypervisor memory region).
6900 *
6901 * The external (to PDM) use of this interface is to load VMMGC.gc.
6902 *
6903 * @returns VBox status code.
6904 * @param pVM The VM to load it into.
6905 * @param pszFilename Filename of the module binary.
6906 * @param pszName Module name. Case sensitive and the length is limited!
6907 */
6908PDMR3DECL(int) PDMR3LoadGC(PVM pVM, const char *pszFilename, const char *pszName);
6909
6910/**
6911 * Get the address of a symbol in a given GC module.
6912 *
6913 * @returns VBox status code.
6914 * @param pVM VM handle.
6915 * @param pszModule Module name. If NULL the main GC module (VMMGC.gc) is assumed.
6916 * @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
6917 * ordinal value rather than a string pointer.
6918 * @param pGCPtrValue Where to store the symbol value.
6919 */
6920PDMR3DECL(int) PDMR3GetSymbolGC(PVM pVM, const char *pszModule, const char *pszSymbol, PRTGCPTR pGCPtrValue);
6921
6922/**
6923 * Same as PDMR3GetSymbolGC except that the module will be attempted loaded if not found.
6924 *
6925 * @returns VBox status code.
6926 * @param pVM VM handle.
6927 * @param pszModule Module name. If NULL the main GC module (VMMGC.gc) is assumed.
6928 * @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
6929 * ordinal value rather than a string pointer.
6930 * @param pGCPtrValue Where to store the symbol value.
6931 */
6932PDMR3DECL(int) PDMR3GetSymbolGCLazy(PVM pVM, const char *pszModule, const char *pszSymbol, PRTGCPTR pGCPtrValue);
6933
6934/**
6935 * Queries module information from an EIP.
6936 *
6937 * This is typically used to locate a crash address.
6938 *
6939 * @returns VBox status code.
6940 * @param pVM VM handle
6941 * @param uEIP EIP to locate.
6942 * @param pszModName Where to store the module name.
6943 * @param cchModName Size of the module name buffer.
6944 * @param pMod Base address of the module.
6945 * @param pszNearSym1 Name of the closes symbol from below.
6946 * @param cchNearSym1 Size of the buffer pointed to by pszNearSym1.
6947 * @param pNearSym1 The address of pszNearSym1.
6948 * @param pszNearSym2 Name of the closes symbol from below.
6949 * @param cchNearSym2 Size of the buffer pointed to by pszNearSym2.
6950 * @param pNearSym2 The address of pszNearSym2.
6951 */
6952PDMR3DECL(int) PDMR3QueryModFromEIP(PVM pVM, uint32_t uEIP,
6953 char *pszModName, unsigned cchModName, RTGCPTR *pMod,
6954 char *pszNearSym1, unsigned cchNearSym1, RTGCPTR *pNearSym1,
6955 char *pszNearSym2, unsigned cchNearSym2, RTGCPTR *pNearSym2);
6956
6957
6958/**
6959 * Module enumeration callback function.
6960 *
6961 * @returns VBox status.
6962 * Failure will stop the search and return the return code.
6963 * Warnings will be ignored and not returned.
6964 * @param pVM VM Handle.
6965 * @param pszFilename Module filename.
6966 * @param pszName Module name. (short and unique)
6967 * @param ImageBase Address where to executable image is loaded.
6968 * @param cbImage Size of the executable image.
6969 * @param fGC Set if guest context, clear if host context.
6970 * @param pvArg User argument.
6971 */
6972typedef DECLCALLBACK(int) FNPDMR3ENUM(PVM pVM, const char *pszFilename, const char *pszName, RTUINTPTR ImageBase, size_t cbImage, bool fGC);
6973/** Pointer to a FNPDMR3ENUM() function. */
6974typedef FNPDMR3ENUM *PFNPDMR3ENUM;
6975
6976
6977/**
6978 * Enumerate all PDM modules.
6979 *
6980 * @returns VBox status.
6981 * @param pVM VM Handle.
6982 * @param pfnCallback Function to call back for each of the modules.
6983 * @param pvArg User argument.
6984 */
6985PDMR3DECL(int) PDMR3EnumModules(PVM pVM, PFNPDMR3ENUM pfnCallback, void *pvArg);
6986
6987
6988/**
6989 * Queries the base interace of a device instance.
6990 *
6991 * The caller can use this to query other interfaces the device implements
6992 * and use them to talk to the device.
6993 *
6994 * @returns VBox status code.
6995 * @param pVM VM handle.
6996 * @param pszDevice Device name.
6997 * @param iInstance Device instance.
6998 * @param ppBase Where to store the pointer to the base device interface on success.
6999 * @remark We're doing any locking ATM, so don't try call this at times when the
7000 * device chain is known to be updated.
7001 */
7002PDMR3DECL(int) PDMR3QueryDevice(PVM pVM, const char *pszDevice, unsigned iInstance, PPDMIBASE *ppBase);
7003
7004/**
7005 * Queries the base interface of a device LUN.
7006 *
7007 * This differs from PDMR3QueryLun by that it returns the interface on the
7008 * device and not the top level driver.
7009 *
7010 * @returns VBox status code.
7011 * @param pVM VM Handle.
7012 * @param pszDevice Device name.
7013 * @param iInstance Device instance.
7014 * @param iLun The Logical Unit to obtain the interface of.
7015 * @param ppBase Where to store the base interface pointer.
7016 * @remark We're doing any locking ATM, so don't try call this at times when the
7017 * device chain is known to be updated.
7018 */
7019PDMR3DECL(int) PDMR3QueryDeviceLun(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
7020
7021/**
7022 * Query the interface of the top level driver on a LUN.
7023 *
7024 * @returns VBox status code.
7025 * @param pVM VM Handle.
7026 * @param pszDevice Device name.
7027 * @param iInstance Device instance.
7028 * @param iLun The Logical Unit to obtain the interface of.
7029 * @param ppBase Where to store the base interface pointer.
7030 * @remark We're doing any locking ATM, so don't try call this at times when the
7031 * device chain is known to be updated.
7032 */
7033PDMR3DECL(int) PDMR3QueryLun(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
7034
7035/**
7036 * Attaches a preconfigured driver to an existing device instance.
7037 *
7038 * This is used to change drivers and suchlike at runtime.
7039 *
7040 * @returns VBox status code.
7041 * @param pVM VM Handle.
7042 * @param pszDevice Device name.
7043 * @param iInstance Device instance.
7044 * @param iLun The Logical Unit to obtain the interface of.
7045 * @param ppBase Where to store the base interface pointer. Optional.
7046 * @thread EMT
7047 */
7048PDMR3DECL(int) PDMR3DeviceAttach(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE *ppBase);
7049
7050/**
7051 * Detaches a driver from an existing device instance.
7052 *
7053 * This is used to change drivers and suchlike at runtime.
7054 *
7055 * @returns VBox status code.
7056 * @param pVM VM Handle.
7057 * @param pszDevice Device name.
7058 * @param iInstance Device instance.
7059 * @param iLun The Logical Unit to obtain the interface of.
7060 * @thread EMT
7061 */
7062PDMR3DECL(int) PDMR3DeviceDetach(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun);
7063
7064/**
7065 * Executes pending DMA transfers.
7066 * Forced Action handler.
7067 *
7068 * @param pVM VM handle.
7069 */
7070PDMR3DECL(void) PDMR3DmaRun(PVM pVM);
7071
7072/**
7073 * Call polling function.
7074 *
7075 * @param pVM VM handle.
7076 */
7077PDMR3DECL(void) PDMR3Poll(PVM pVM);
7078
7079/**
7080 * Service a VMMCALLHOST_PDM_LOCK call.
7081 *
7082 * @returns VBox status code.
7083 * @param pVM The VM handle.
7084 */
7085PDMR3DECL(int) PDMR3LockCall(PVM pVM);
7086
7087/** @} */
7088#endif
7089
7090
7091#ifdef IN_GC
7092/** @defgroup grp_pdm_gc The PDM Guest Context API
7093 * @ingroup grp_pdm
7094 * @{
7095 */
7096/** @} */
7097#endif
7098
7099__END_DECLS
7100
7101/** @} */
7102
7103#endif
7104
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette