VirtualBox

source: vbox/trunk/include/VBox/pdmdev.h@ 4738

Last change on this file since 4738 was 4567, checked in by vboxsync, 17 years ago

Documented limitations of address conversion helpers

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 129.0 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, Devices.
3 */
4
5/*
6 * Copyright (C) 2006-2007 innotek GmbH
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License as published by the Free Software Foundation,
12 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13 * distribution. VirtualBox OSE is distributed in the hope that it will
14 * be useful, but WITHOUT ANY WARRANTY of any kind.
15 */
16
17#ifndef ___VBox_pdmdev_h
18#define ___VBox_pdmdev_h
19
20#include <VBox/pdmqueue.h>
21#include <VBox/pdmcritsect.h>
22#include <VBox/pdmthread.h>
23#include <VBox/pdmifs.h>
24#include <VBox/pdmins.h>
25#include <VBox/iom.h>
26#include <VBox/tm.h>
27#include <VBox/ssm.h>
28#include <VBox/cfgm.h>
29#include <VBox/dbgf.h>
30#include <VBox/mm.h>
31#include <VBox/err.h>
32#include <VBox/pci.h>
33#include <iprt/stdarg.h>
34
35__BEGIN_DECLS
36
37/** @defgroup grp_pdm_device Devices
38 * @ingroup grp_pdm
39 * @{
40 */
41
42/**
43 * Construct a device instance for a VM.
44 *
45 * @returns VBox status.
46 * @param pDevIns The device instance data.
47 * If the registration structure is needed, pDevIns->pDevReg points to it.
48 * @param iInstance Instance number. Use this to figure out which registers and such to use.
49 * The instance number is also found in pDevIns->iInstance, but since it's
50 * likely to be freqently used PDM passes it as parameter.
51 * @param pCfgHandle Configuration node handle for the device. Use this to obtain the configuration
52 * of the device instance. It's also found in pDevIns->pCfgHandle, but since it's
53 * primary usage will in this function it's passed as a parameter.
54 */
55typedef DECLCALLBACK(int) FNPDMDEVCONSTRUCT(PPDMDEVINS pDevIns, int iInstance, PCFGMNODE pCfgHandle);
56/** Pointer to a FNPDMDEVCONSTRUCT() function. */
57typedef FNPDMDEVCONSTRUCT *PFNPDMDEVCONSTRUCT;
58
59/**
60 * Destruct a device instance.
61 *
62 * Most VM resources are freed by the VM. This callback is provided so that any non-VM
63 * resources can be freed correctly.
64 *
65 * @returns VBox status.
66 * @param pDevIns The device instance data.
67 */
68typedef DECLCALLBACK(int) FNPDMDEVDESTRUCT(PPDMDEVINS pDevIns);
69/** Pointer to a FNPDMDEVDESTRUCT() function. */
70typedef FNPDMDEVDESTRUCT *PFNPDMDEVDESTRUCT;
71
72/**
73 * Device relocation callback.
74 *
75 * When this callback is called the device instance data, and if the
76 * device have a GC component, is being relocated, or/and the selectors
77 * have been changed. The device must use the chance to perform the
78 * necessary pointer relocations and data updates.
79 *
80 * Before the GC code is executed the first time, this function will be
81 * called with a 0 delta so GC pointer calculations can be one in one place.
82 *
83 * @param pDevIns Pointer to the device instance.
84 * @param offDelta The relocation delta relative to the old location.
85 *
86 * @remark A relocation CANNOT fail.
87 */
88typedef DECLCALLBACK(void) FNPDMDEVRELOCATE(PPDMDEVINS pDevIns, RTGCINTPTR offDelta);
89/** Pointer to a FNPDMDEVRELOCATE() function. */
90typedef FNPDMDEVRELOCATE *PFNPDMDEVRELOCATE;
91
92
93/**
94 * Device I/O Control interface.
95 *
96 * This is used by external components, such as the COM interface, to
97 * communicate with devices using a class wide interface or a device
98 * specific interface.
99 *
100 * @returns VBox status code.
101 * @param pDevIns Pointer to the device instance.
102 * @param uFunction Function to perform.
103 * @param pvIn Pointer to input data.
104 * @param cbIn Size of input data.
105 * @param pvOut Pointer to output data.
106 * @param cbOut Size of output data.
107 * @param pcbOut Where to store the actual size of the output data.
108 */
109typedef DECLCALLBACK(int) FNPDMDEVIOCTL(PPDMDEVINS pDevIns, RTUINT uFunction,
110 void *pvIn, RTUINT cbIn,
111 void *pvOut, RTUINT cbOut, PRTUINT pcbOut);
112/** Pointer to a FNPDMDEVIOCTL() function. */
113typedef FNPDMDEVIOCTL *PFNPDMDEVIOCTL;
114
115/**
116 * Power On notification.
117 *
118 * @returns VBox status.
119 * @param pDevIns The device instance data.
120 */
121typedef DECLCALLBACK(void) FNPDMDEVPOWERON(PPDMDEVINS pDevIns);
122/** Pointer to a FNPDMDEVPOWERON() function. */
123typedef FNPDMDEVPOWERON *PFNPDMDEVPOWERON;
124
125/**
126 * Reset notification.
127 *
128 * @returns VBox status.
129 * @param pDevIns The device instance data.
130 */
131typedef DECLCALLBACK(void) FNPDMDEVRESET(PPDMDEVINS pDevIns);
132/** Pointer to a FNPDMDEVRESET() function. */
133typedef FNPDMDEVRESET *PFNPDMDEVRESET;
134
135/**
136 * Suspend notification.
137 *
138 * @returns VBox status.
139 * @param pDevIns The device instance data.
140 */
141typedef DECLCALLBACK(void) FNPDMDEVSUSPEND(PPDMDEVINS pDevIns);
142/** Pointer to a FNPDMDEVSUSPEND() function. */
143typedef FNPDMDEVSUSPEND *PFNPDMDEVSUSPEND;
144
145/**
146 * Resume notification.
147 *
148 * @returns VBox status.
149 * @param pDevIns The device instance data.
150 */
151typedef DECLCALLBACK(void) FNPDMDEVRESUME(PPDMDEVINS pDevIns);
152/** Pointer to a FNPDMDEVRESUME() function. */
153typedef FNPDMDEVRESUME *PFNPDMDEVRESUME;
154
155/**
156 * Power Off notification.
157 *
158 * @param pDevIns The device instance data.
159 */
160typedef DECLCALLBACK(void) FNPDMDEVPOWEROFF(PPDMDEVINS pDevIns);
161/** Pointer to a FNPDMDEVPOWEROFF() function. */
162typedef FNPDMDEVPOWEROFF *PFNPDMDEVPOWEROFF;
163
164/**
165 * Attach command.
166 *
167 * This is called to let the device attach to a driver for a specified LUN
168 * at runtime. This is not called during VM construction, the device
169 * constructor have to attach to all the available drivers.
170 *
171 * This is like plugging in the keyboard or mouse after turning on the PC.
172 *
173 * @returns VBox status code.
174 * @param pDevIns The device instance.
175 * @param iLUN The logical unit which is being detached.
176 */
177typedef DECLCALLBACK(int) FNPDMDEVATTACH(PPDMDEVINS pDevIns, unsigned iLUN);
178/** Pointer to a FNPDMDEVATTACH() function. */
179typedef FNPDMDEVATTACH *PFNPDMDEVATTACH;
180
181/**
182 * Detach notification.
183 *
184 * This is called when a driver is detaching itself from a LUN of the device.
185 * The device should adjust it's state to reflect this.
186 *
187 * This is like unplugging the network cable to use it for the laptop or
188 * something while the PC is still running.
189 *
190 * @param pDevIns The device instance.
191 * @param iLUN The logical unit which is being detached.
192 */
193typedef DECLCALLBACK(void) FNPDMDEVDETACH(PPDMDEVINS pDevIns, unsigned iLUN);
194/** Pointer to a FNPDMDEVDETACH() function. */
195typedef FNPDMDEVDETACH *PFNPDMDEVDETACH;
196
197/**
198 * Query the base interface of a logical unit.
199 *
200 * @returns VBOX status code.
201 * @param pDevIns The device instance.
202 * @param iLUN The logicial unit to query.
203 * @param ppBase Where to store the pointer to the base interface of the LUN.
204 */
205typedef DECLCALLBACK(int) FNPDMDEVQUERYINTERFACE(PPDMDEVINS pDevIns, unsigned iLUN, PPDMIBASE *ppBase);
206/** Pointer to a FNPDMDEVQUERYINTERFACE() function. */
207typedef FNPDMDEVQUERYINTERFACE *PFNPDMDEVQUERYINTERFACE;
208
209/**
210 * Init complete notification.
211 * This can be done to do communication with other devices and other
212 * initialization which requires everything to be in place.
213 *
214 * @returns VBOX status code.
215 * @param pDevIns The device instance.
216 */
217typedef DECLCALLBACK(int) FNPDMDEVINITCOMPLETE(PPDMDEVINS pDevIns);
218/** Pointer to a FNPDMDEVINITCOMPLETE() function. */
219typedef FNPDMDEVINITCOMPLETE *PFNPDMDEVINITCOMPLETE;
220
221
222
223/** PDM Device Registration Structure,
224 * This structure is used when registering a device from
225 * VBoxInitDevices() in HC Ring-3. PDM will continue use till
226 * the VM is terminated.
227 */
228typedef struct PDMDEVREG
229{
230 /** Structure version. PDM_DEVREG_VERSION defines the current version. */
231 uint32_t u32Version;
232 /** Device name. */
233 char szDeviceName[32];
234 /** Name of guest context module (no path).
235 * Only evalutated if PDM_DEVREG_FLAGS_GC is set. */
236 char szGCMod[32];
237 /** Name of guest context module (no path).
238 * Only evalutated if PDM_DEVREG_FLAGS_GC is set. */
239 char szR0Mod[32];
240 /** The description of the device. The UTF-8 string pointed to shall, like this structure,
241 * remain unchanged from registration till VM destruction. */
242 const char *pszDescription;
243
244 /** Flags, combination of the PDM_DEVREG_FLAGS_* \#defines. */
245 RTUINT fFlags;
246 /** Device class(es), combination of the PDM_DEVREG_CLASS_* \#defines. */
247 RTUINT fClass;
248 /** Maximum number of instances (per VM). */
249 RTUINT cMaxInstances;
250 /** Size of the instance data. */
251 RTUINT cbInstance;
252
253 /** Construct instance - required. */
254 PFNPDMDEVCONSTRUCT pfnConstruct;
255 /** Destruct instance - optional. */
256 PFNPDMDEVDESTRUCT pfnDestruct;
257 /** Relocation command - optional. */
258 PFNPDMDEVRELOCATE pfnRelocate;
259 /** I/O Control interface - optional. */
260 PFNPDMDEVIOCTL pfnIOCtl;
261 /** Power on notification - optional. */
262 PFNPDMDEVPOWERON pfnPowerOn;
263 /** Reset notification - optional. */
264 PFNPDMDEVRESET pfnReset;
265 /** Suspend notification - optional. */
266 PFNPDMDEVSUSPEND pfnSuspend;
267 /** Resume notification - optional. */
268 PFNPDMDEVRESUME pfnResume;
269 /** Attach command - optional. */
270 PFNPDMDEVATTACH pfnAttach;
271 /** Detach notification - optional. */
272 PFNPDMDEVDETACH pfnDetach;
273 /** Query a LUN base interface - optional. */
274 PFNPDMDEVQUERYINTERFACE pfnQueryInterface;
275 /** Init complete notification - optional. */
276 PFNPDMDEVINITCOMPLETE pfnInitComplete;
277 /** Power off notification - optional. */
278 PFNPDMDEVPOWEROFF pfnPowerOff;
279} PDMDEVREG;
280/** Pointer to a PDM Device Structure. */
281typedef PDMDEVREG *PPDMDEVREG;
282/** Const pointer to a PDM Device Structure. */
283typedef PDMDEVREG const *PCPDMDEVREG;
284
285/** Current DEVREG version number. */
286#define PDM_DEVREG_VERSION 0xc0010000
287
288/** PDM Device Flags.
289 * @{ */
290/** This flag is used to indicate that the device has a GC component. */
291#define PDM_DEVREG_FLAGS_GC 0x00000001
292/** This flag is used to indicate that the device has a R0 component. */
293#define PDM_DEVREG_FLAGS_R0 0x00010000
294
295/** @def PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT
296 * The bit count for the current host. */
297#if HC_ARCH_BITS == 32
298# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT 0x00000002
299#elif HC_ARCH_BITS == 64
300# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT 0x00000004
301#else
302# error Unsupported HC_ARCH_BITS value.
303#endif
304/** The host bit count mask. */
305#define PDM_DEVREG_FLAGS_HOST_BITS_MASK 0x00000006
306
307/** The device support only 32-bit guests. */
308#define PDM_DEVREG_FLAGS_GUEST_BITS_32 0x00000008
309/** The device support only 64-bit guests. */
310#define PDM_DEVREG_FLAGS_GUEST_BITS_64 0x00000010
311/** The device support both 32-bit & 64-bit guests. */
312#define PDM_DEVREG_FLAGS_GUEST_BITS_32_64 0x00000018
313/** @def PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT
314 * The guest bit count for the current compilation. */
315#if GC_ARCH_BITS == 32
316# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_32
317#elif GC_ARCH_BITS == 64
318# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_64
319#else
320# error Unsupported GC_ARCH_BITS value.
321#endif
322/** The guest bit count mask. */
323#define PDM_DEVREG_FLAGS_GUEST_BITS_MASK 0x00000018
324
325/** Indicates that the devices support PAE36 on a 32-bit guest. */
326#define PDM_DEVREG_FLAGS_PAE36 0x00000020
327/** @} */
328
329
330/** PDM Device Classes.
331 * The order is important, lower bit earlier instantiation.
332 * @{ */
333/** Architecture device. */
334#define PDM_DEVREG_CLASS_ARCH BIT(0)
335/** Architecture BIOS device. */
336#define PDM_DEVREG_CLASS_ARCH_BIOS BIT(1)
337/** PCI bus brigde. */
338#define PDM_DEVREG_CLASS_BUS_PCI BIT(2)
339/** ISA bus brigde. */
340#define PDM_DEVREG_CLASS_BUS_ISA BIT(3)
341/** Input device (mouse, keyboard, joystick,..). */
342#define PDM_DEVREG_CLASS_INPUT BIT(4)
343/** Interrupt controller (PIC). */
344#define PDM_DEVREG_CLASS_PIC BIT(5)
345/** Interval controoler (PIT). */
346#define PDM_DEVREG_CLASS_PIT BIT(6)
347/** RTC/CMOS. */
348#define PDM_DEVREG_CLASS_RTC BIT(7)
349/** DMA controller. */
350#define PDM_DEVREG_CLASS_DMA BIT(8)
351/** VMM Device. */
352#define PDM_DEVREG_CLASS_VMM_DEV BIT(9)
353/** Graphics device, like VGA. */
354#define PDM_DEVREG_CLASS_GRAPHICS BIT(10)
355/** Storage controller device. */
356#define PDM_DEVREG_CLASS_STORAGE BIT(11)
357/** Network interface controller. */
358#define PDM_DEVREG_CLASS_NETWORK BIT(12)
359/** Audio. */
360#define PDM_DEVREG_CLASS_AUDIO BIT(13)
361/** USB HIC. */
362#define PDM_DEVREG_CLASS_BUS_USB BIT(14)
363/** ACPI. */
364#define PDM_DEVREG_CLASS_ACPI BIT(15)
365/** Serial controller device. */
366#define PDM_DEVREG_CLASS_SERIAL BIT(16)
367/** Parallel controller device */
368#define PDM_DEVREG_CLASS_PARALLEL BIT(17)
369/** Misc devices (always last). */
370#define PDM_DEVREG_CLASS_MISC BIT(31)
371/** @} */
372
373
374/** @name IRQ Level for use with the *SetIrq APIs.
375 * @{
376 */
377/** Assert the IRQ (can assume value 1). */
378#define PDM_IRQ_LEVEL_HIGH BIT(0)
379/** Deassert the IRQ (can assume value 0). */
380#define PDM_IRQ_LEVEL_LOW 0
381/** flip-flop - assert and then deassert it again immediately. */
382#define PDM_IRQ_LEVEL_FLIP_FLOP (BIT(1) | PDM_IRQ_LEVEL_HIGH)
383/** @} */
384
385
386/**
387 * PCI Bus registaration structure.
388 * All the callbacks, except the PCIBIOS hack, are working on PCI devices.
389 */
390typedef struct PDMPCIBUSREG
391{
392 /** Structure version number. PDM_PCIBUSREG_VERSION defines the current version. */
393 uint32_t u32Version;
394
395 /**
396 * Registers the device with the default PCI bus.
397 *
398 * @returns VBox status code.
399 * @param pDevIns Device instance of the PCI Bus.
400 * @param pPciDev The PCI device structure.
401 * Any PCI enabled device must keep this in it's instance data!
402 * Fill in the PCI data config before registration, please.
403 * @param pszName Pointer to device name (permanent, readonly). For debugging, not unique.
404 * @param iDev The device number ((dev << 3) | function) the device should have on the bus.
405 * If negative, the pci bus device will assign one.
406 */
407 DECLR3CALLBACKMEMBER(int, pfnRegisterHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, const char *pszName, int iDev));
408
409 /**
410 * Registers a I/O region (memory mapped or I/O ports) for a PCI device.
411 *
412 * @returns VBox status code.
413 * @param pDevIns Device instance of the PCI Bus.
414 * @param pPciDev The PCI device structure.
415 * @param iRegion The region number.
416 * @param cbRegion Size of the region.
417 * @param iType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
418 * @param pfnCallback Callback for doing the mapping.
419 */
420 DECLR3CALLBACKMEMBER(int, pfnIORegionRegisterHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback));
421
422 /**
423 * Register PCI configuration space read/write callbacks.
424 *
425 * @param pDevIns Device instance of the PCI Bus.
426 * @param pPciDev The PCI device structure.
427 * @param pfnRead Pointer to the user defined PCI config read function.
428 * @param ppfnReadOld Pointer to function pointer which will receive the old (default)
429 * PCI config read function. This way, user can decide when (and if)
430 * to call default PCI config read function. Can be NULL.
431 * @param pfnWrite Pointer to the user defined PCI config write function.
432 * @param pfnWriteOld Pointer to function pointer which will receive the old (default)
433 * PCI config write function. This way, user can decide when (and if)
434 * to call default PCI config write function. Can be NULL.
435 * @thread EMT
436 */
437 DECLR3CALLBACKMEMBER(void, pfnSetConfigCallbacksHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,
438 PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld));
439
440 /**
441 * Set the IRQ for a PCI device.
442 *
443 * @param pDevIns Device instance of the PCI Bus.
444 * @param pPciDev The PCI device structure.
445 * @param iIrq IRQ number to set.
446 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
447 */
448 DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iIrq, int iLevel));
449
450 /**
451 * Saves a state of the PCI device.
452 *
453 * @returns VBox status code.
454 * @param pDevIns Device instance of the PCI Bus.
455 * @param pPciDev Pointer to PCI device.
456 * @param pSSMHandle The handle to save the state to.
457 */
458 DECLR3CALLBACKMEMBER(int, pfnSaveExecHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PSSMHANDLE pSSMHandle));
459
460 /**
461 * Loads a saved PCI device state.
462 *
463 * @returns VBox status code.
464 * @param pDevIns Device instance of the PCI Bus.
465 * @param pPciDev Pointer to PCI device.
466 * @param pSSMHandle The handle to the saved state.
467 */
468 DECLR3CALLBACKMEMBER(int, pfnLoadExecHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PSSMHANDLE pSSMHandle));
469
470 /**
471 * Called to perform the job of the bios.
472 * This is only called for the first PCI Bus - it is expected to
473 * service all the PCI buses.
474 *
475 * @returns VBox status.
476 * @param pDevIns Device instance of the first bus.
477 */
478 DECLR3CALLBACKMEMBER(int, pfnFakePCIBIOSHC,(PPDMDEVINS pDevIns));
479
480 /** The name of the SetIrq GC entry point. */
481 const char *pszSetIrqGC;
482
483 /** The name of the SetIrq R0 entry point. */
484 const char *pszSetIrqR0;
485
486} PDMPCIBUSREG;
487/** Pointer to a PCI bus registration structure. */
488typedef PDMPCIBUSREG *PPDMPCIBUSREG;
489
490/** Current PDMPCIBUSREG version number. */
491#define PDM_PCIBUSREG_VERSION 0xd0020000
492
493/**
494 * PCI Bus GC helpers.
495 */
496typedef struct PDMPCIHLPGC
497{
498 /** Structure version. PDM_PCIHLPGC_VERSION defines the current version. */
499 uint32_t u32Version;
500
501 /**
502 * Set an ISA IRQ.
503 *
504 * @param pDevIns PCI device instance.
505 * @param iIrq IRQ number to set.
506 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
507 * @thread EMT only.
508 */
509 DECLGCCALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
510
511 /**
512 * Set an I/O-APIC IRQ.
513 *
514 * @param pDevIns PCI device instance.
515 * @param iIrq IRQ number to set.
516 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
517 * @thread EMT only.
518 */
519 DECLGCCALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
520
521#ifdef VBOX_WITH_PDM_LOCK
522 /**
523 * Acquires the PDM lock.
524 *
525 * @returns VINF_SUCCESS on success.
526 * @returns rc if we failed to acquire the lock.
527 * @param pDevIns The PCI device instance.
528 * @param rc What to return if we fail to acquire the lock.
529 */
530 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
531
532 /**
533 * Releases the PDM lock.
534 *
535 * @param pDevIns The PCI device instance.
536 */
537 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
538#endif
539 /** Just a safety precaution. */
540 uint32_t u32TheEnd;
541} PDMPCIHLPGC;
542/** Pointer to PCI helpers. */
543typedef GCPTRTYPE(PDMPCIHLPGC *) PPDMPCIHLPGC;
544/** Pointer to const PCI helpers. */
545typedef GCPTRTYPE(const PDMPCIHLPGC *) PCPDMPCIHLPGC;
546
547/** Current PDMPCIHLPR3 version number. */
548#define PDM_PCIHLPGC_VERSION 0xe1010000
549
550
551/**
552 * PCI Bus R0 helpers.
553 */
554typedef struct PDMPCIHLPR0
555{
556 /** Structure version. PDM_PCIHLPR0_VERSION defines the current version. */
557 uint32_t u32Version;
558
559 /**
560 * Set an ISA IRQ.
561 *
562 * @param pDevIns PCI device instance.
563 * @param iIrq IRQ number to set.
564 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
565 * @thread EMT only.
566 */
567 DECLR0CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
568
569 /**
570 * Set an I/O-APIC IRQ.
571 *
572 * @param pDevIns PCI device instance.
573 * @param iIrq IRQ number to set.
574 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
575 * @thread EMT only.
576 */
577 DECLR0CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
578
579#ifdef VBOX_WITH_PDM_LOCK
580 /**
581 * Acquires the PDM lock.
582 *
583 * @returns VINF_SUCCESS on success.
584 * @returns rc if we failed to acquire the lock.
585 * @param pDevIns The PCI device instance.
586 * @param rc What to return if we fail to acquire the lock.
587 */
588 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
589
590 /**
591 * Releases the PDM lock.
592 *
593 * @param pDevIns The PCI device instance.
594 */
595 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
596#endif
597
598 /** Just a safety precaution. */
599 uint32_t u32TheEnd;
600} PDMPCIHLPR0;
601/** Pointer to PCI helpers. */
602typedef R0PTRTYPE(PDMPCIHLPR0 *) PPDMPCIHLPR0;
603/** Pointer to const PCI helpers. */
604typedef R0PTRTYPE(const PDMPCIHLPR0 *) PCPDMPCIHLPR0;
605
606/** Current PDMPCIHLPR0 version number. */
607#define PDM_PCIHLPR0_VERSION 0xe1010000
608
609/**
610 * PCI device helpers.
611 */
612typedef struct PDMPCIHLPR3
613{
614 /** Structure version. PDM_PCIHLPR3_VERSION defines the current version. */
615 uint32_t u32Version;
616
617 /**
618 * Set an ISA IRQ.
619 *
620 * @param pDevIns The PCI device instance.
621 * @param iIrq IRQ number to set.
622 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
623 * @thread EMT only.
624 */
625 DECLR3CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
626
627 /**
628 * Set an I/O-APIC IRQ.
629 *
630 * @param pDevIns The PCI device instance.
631 * @param iIrq IRQ number to set.
632 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
633 * @thread EMT only.
634 */
635 DECLR3CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
636
637#ifdef VBOX_WITH_PDM_LOCK
638 /**
639 * Acquires the PDM lock.
640 *
641 * @returns VINF_SUCCESS on success.
642 * @returns Fatal error on failure.
643 * @param pDevIns The PCI device instance.
644 * @param rc Dummy for making the interface identical to the GC and R0 versions.
645 */
646 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
647
648 /**
649 * Releases the PDM lock.
650 *
651 * @param pDevIns The PCI device instance.
652 */
653 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
654#endif
655
656 /**
657 * Gets the address of the GC PCI Bus helpers.
658 *
659 * This should be called at both construction and relocation time
660 * to obtain the correct address of the GC helpers.
661 *
662 * @returns GC pointer to the PCI Bus helpers.
663 * @param pDevIns Device instance of the PCI Bus.
664 * @thread EMT only.
665 */
666 DECLR3CALLBACKMEMBER(PCPDMPCIHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
667
668 /**
669 * Gets the address of the R0 PCI Bus helpers.
670 *
671 * This should be called at both construction and relocation time
672 * to obtain the correct address of the GC helpers.
673 *
674 * @returns R0 pointer to the PCI Bus helpers.
675 * @param pDevIns Device instance of the PCI Bus.
676 * @thread EMT only.
677 */
678 DECLR3CALLBACKMEMBER(PCPDMPCIHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
679
680 /** Just a safety precaution. */
681 uint32_t u32TheEnd;
682} PDMPCIHLPR3;
683/** Pointer to PCI helpers. */
684typedef HCPTRTYPE(PDMPCIHLPR3 *) PPDMPCIHLPR3;
685/** Pointer to const PCI helpers. */
686typedef HCPTRTYPE(const PDMPCIHLPR3 *) PCPDMPCIHLPR3;
687
688/** Current PDMPCIHLPR3 version number. */
689#define PDM_PCIHLPR3_VERSION 0xf1010000
690
691
692/**
693 * Programmable Interrupt Controller registration structure.
694 */
695typedef struct PDMPICREG
696{
697 /** Structure version number. PDM_PICREG_VERSION defines the current version. */
698 uint32_t u32Version;
699
700 /**
701 * Set the an IRQ.
702 *
703 * @param pDevIns Device instance of the PIC.
704 * @param iIrq IRQ number to set.
705 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
706 */
707 DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
708
709 /**
710 * Get a pending interrupt.
711 *
712 * @returns Pending interrupt number.
713 * @param pDevIns Device instance of the PIC.
714 */
715 DECLR3CALLBACKMEMBER(int, pfnGetInterruptHC,(PPDMDEVINS pDevIns));
716
717 /** The name of the GC SetIrq entry point. */
718 const char *pszSetIrqGC;
719 /** The name of the GC GetInterrupt entry point. */
720 const char *pszGetInterruptGC;
721
722 /** The name of the R0 SetIrq entry point. */
723 const char *pszSetIrqR0;
724 /** The name of the R0 GetInterrupt entry point. */
725 const char *pszGetInterruptR0;
726} PDMPICREG;
727/** Pointer to a PIC registration structure. */
728typedef PDMPICREG *PPDMPICREG;
729
730/** Current PDMPICREG version number. */
731#define PDM_PICREG_VERSION 0xe0020000
732
733/**
734 * PIC GC helpers.
735 */
736typedef struct PDMPICHLPGC
737{
738 /** Structure version. PDM_PICHLPGC_VERSION defines the current version. */
739 uint32_t u32Version;
740
741 /**
742 * Set the interrupt force action flag.
743 *
744 * @param pDevIns Device instance of the PIC.
745 */
746 DECLGCCALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
747
748 /**
749 * Clear the interrupt force action flag.
750 *
751 * @param pDevIns Device instance of the PIC.
752 */
753 DECLGCCALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
754
755#ifdef VBOX_WITH_PDM_LOCK
756 /**
757 * Acquires the PDM lock.
758 *
759 * @returns VINF_SUCCESS on success.
760 * @returns rc if we failed to acquire the lock.
761 * @param pDevIns The PIC device instance.
762 * @param rc What to return if we fail to acquire the lock.
763 */
764 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
765
766 /**
767 * Releases the PDM lock.
768 *
769 * @param pDevIns The PIC device instance.
770 */
771 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
772#endif
773 /** Just a safety precaution. */
774 uint32_t u32TheEnd;
775} PDMPICHLPGC;
776
777/** Pointer to PIC GC helpers. */
778typedef GCPTRTYPE(PDMPICHLPGC *) PPDMPICHLPGC;
779/** Pointer to const PIC GC helpers. */
780typedef GCPTRTYPE(const PDMPICHLPGC *) PCPDMPICHLPGC;
781
782/** Current PDMPICHLPGC version number. */
783#define PDM_PICHLPGC_VERSION 0xfc010000
784
785
786/**
787 * PIC R0 helpers.
788 */
789typedef struct PDMPICHLPR0
790{
791 /** Structure version. PDM_PICHLPR0_VERSION defines the current version. */
792 uint32_t u32Version;
793
794 /**
795 * Set the interrupt force action flag.
796 *
797 * @param pDevIns Device instance of the PIC.
798 */
799 DECLR0CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
800
801 /**
802 * Clear the interrupt force action flag.
803 *
804 * @param pDevIns Device instance of the PIC.
805 */
806 DECLR0CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
807
808#ifdef VBOX_WITH_PDM_LOCK
809 /**
810 * Acquires the PDM lock.
811 *
812 * @returns VINF_SUCCESS on success.
813 * @returns rc if we failed to acquire the lock.
814 * @param pDevIns The PIC device instance.
815 * @param rc What to return if we fail to acquire the lock.
816 */
817 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
818
819 /**
820 * Releases the PDM lock.
821 *
822 * @param pDevIns The PCI device instance.
823 */
824 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
825#endif
826
827 /** Just a safety precaution. */
828 uint32_t u32TheEnd;
829} PDMPICHLPR0;
830
831/** Pointer to PIC R0 helpers. */
832typedef R0PTRTYPE(PDMPICHLPR0 *) PPDMPICHLPR0;
833/** Pointer to const PIC R0 helpers. */
834typedef R0PTRTYPE(const PDMPICHLPR0 *) PCPDMPICHLPR0;
835
836/** Current PDMPICHLPR0 version number. */
837#define PDM_PICHLPR0_VERSION 0xfc010000
838
839/**
840 * PIC HC helpers.
841 */
842typedef struct PDMPICHLPR3
843{
844 /** Structure version. PDM_PICHLP_VERSION defines the current version. */
845 uint32_t u32Version;
846
847 /**
848 * Set the interrupt force action flag.
849 *
850 * @param pDevIns Device instance of the PIC.
851 */
852 DECLR3CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
853
854 /**
855 * Clear the interrupt force action flag.
856 *
857 * @param pDevIns Device instance of the PIC.
858 */
859 DECLR3CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
860
861#ifdef VBOX_WITH_PDM_LOCK
862 /**
863 * Acquires the PDM lock.
864 *
865 * @returns VINF_SUCCESS on success.
866 * @returns Fatal error on failure.
867 * @param pDevIns The PIC device instance.
868 * @param rc Dummy for making the interface identical to the GC and R0 versions.
869 */
870 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
871
872 /**
873 * Releases the PDM lock.
874 *
875 * @param pDevIns The PIC device instance.
876 */
877 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
878#endif
879
880 /**
881 * Gets the address of the GC PIC helpers.
882 *
883 * This should be called at both construction and relocation time
884 * to obtain the correct address of the GC helpers.
885 *
886 * @returns GC pointer to the PIC helpers.
887 * @param pDevIns Device instance of the PIC.
888 */
889 DECLR3CALLBACKMEMBER(PCPDMPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
890
891 /**
892 * Gets the address of the R0 PIC helpers.
893 *
894 * This should be called at both construction and relocation time
895 * to obtain the correct address of the GC helpers.
896 *
897 * @returns R0 pointer to the PIC helpers.
898 * @param pDevIns Device instance of the PIC.
899 */
900 DECLR3CALLBACKMEMBER(PCPDMPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
901
902 /** Just a safety precaution. */
903 uint32_t u32TheEnd;
904} PDMPICHLPR3;
905
906/** Pointer to PIC HC helpers. */
907typedef HCPTRTYPE(PDMPICHLPR3 *) PPDMPICHLPR3;
908/** Pointer to const PIC HC helpers. */
909typedef HCPTRTYPE(const PDMPICHLPR3 *) PCPDMPICHLPR3;
910
911/** Current PDMPICHLPR3 version number. */
912#define PDM_PICHLPR3_VERSION 0xf0010000
913
914
915
916/**
917 * Advanced Programmable Interrupt Controller registration structure.
918 */
919typedef struct PDMAPICREG
920{
921 /** Structure version number. PDM_APICREG_VERSION defines the current version. */
922 uint32_t u32Version;
923
924 /**
925 * Get a pending interrupt.
926 *
927 * @returns Pending interrupt number.
928 * @param pDevIns Device instance of the APIC.
929 */
930 DECLR3CALLBACKMEMBER(int, pfnGetInterruptHC,(PPDMDEVINS pDevIns));
931
932 /**
933 * Set the APIC base.
934 *
935 * @param pDevIns Device instance of the APIC.
936 * @param u64Base The new base.
937 */
938 DECLR3CALLBACKMEMBER(void, pfnSetBaseHC,(PPDMDEVINS pDevIns, uint64_t u64Base));
939
940 /**
941 * Get the APIC base.
942 *
943 * @returns Current base.
944 * @param pDevIns Device instance of the APIC.
945 */
946 DECLR3CALLBACKMEMBER(uint64_t, pfnGetBaseHC,(PPDMDEVINS pDevIns));
947
948 /**
949 * Set the TPR (task priority register?).
950 *
951 * @param pDevIns Device instance of the APIC.
952 * @param u8TPR The new TPR.
953 */
954 DECLR3CALLBACKMEMBER(void, pfnSetTPRHC,(PPDMDEVINS pDevIns, uint8_t u8TPR));
955
956 /**
957 * Get the TPR (task priority register?).
958 *
959 * @returns The current TPR.
960 * @param pDevIns Device instance of the APIC.
961 */
962 DECLR3CALLBACKMEMBER(uint8_t, pfnGetTPRHC,(PPDMDEVINS pDevIns));
963
964 /**
965 * Private interface between the IOAPIC and APIC.
966 *
967 * This is a low-level, APIC/IOAPIC implementation specific interface
968 * which is registered with PDM only because it makes life so much
969 * simpler right now (GC bits). This is a bad bad hack! The correct
970 * way of doing this would involve some way of querying GC interfaces
971 * and relocating them. Perhaps doing some kind of device init in GC...
972 *
973 * @returns The current TPR.
974 * @param pDevIns Device instance of the APIC.
975 * @param u8Dest See APIC implementation.
976 * @param u8DestMode See APIC implementation.
977 * @param u8DeliveryMode See APIC implementation.
978 * @param iVector See APIC implementation.
979 * @param u8Polarity See APIC implementation.
980 * @param u8TriggerMode See APIC implementation.
981 */
982 DECLR3CALLBACKMEMBER(void, pfnBusDeliverHC,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
983 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
984
985 /** The name of the GC GetInterrupt entry point. */
986 const char *pszGetInterruptGC;
987 /** The name of the GC SetBase entry point. */
988 const char *pszSetBaseGC;
989 /** The name of the GC GetBase entry point. */
990 const char *pszGetBaseGC;
991 /** The name of the GC SetTPR entry point. */
992 const char *pszSetTPRGC;
993 /** The name of the GC GetTPR entry point. */
994 const char *pszGetTPRGC;
995 /** The name of the GC BusDeliver entry point. */
996 const char *pszBusDeliverGC;
997
998 /** The name of the R0 GetInterrupt entry point. */
999 const char *pszGetInterruptR0;
1000 /** The name of the R0 SetBase entry point. */
1001 const char *pszSetBaseR0;
1002 /** The name of the R0 GetBase entry point. */
1003 const char *pszGetBaseR0;
1004 /** The name of the R0 SetTPR entry point. */
1005 const char *pszSetTPRR0;
1006 /** The name of the R0 GetTPR entry point. */
1007 const char *pszGetTPRR0;
1008 /** The name of the R0 BusDeliver entry point. */
1009 const char *pszBusDeliverR0;
1010
1011} PDMAPICREG;
1012/** Pointer to an APIC registration structure. */
1013typedef PDMAPICREG *PPDMAPICREG;
1014
1015/** Current PDMAPICREG version number. */
1016#define PDM_APICREG_VERSION 0x70010000
1017
1018
1019/**
1020 * APIC GC helpers.
1021 */
1022typedef struct PDMAPICHLPGC
1023{
1024 /** Structure version. PDM_APICHLPGC_VERSION defines the current version. */
1025 uint32_t u32Version;
1026
1027 /**
1028 * Set the interrupt force action flag.
1029 *
1030 * @param pDevIns Device instance of the APIC.
1031 */
1032 DECLGCCALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
1033
1034 /**
1035 * Clear the interrupt force action flag.
1036 *
1037 * @param pDevIns Device instance of the APIC.
1038 */
1039 DECLGCCALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
1040
1041 /**
1042 * Sets or clears the APIC bit in the CPUID feature masks.
1043 *
1044 * @param pDevIns Device instance of the APIC.
1045 * @param fEnabled If true the bit is set, else cleared.
1046 */
1047 DECLGCCALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));
1048
1049#ifdef VBOX_WITH_PDM_LOCK
1050 /**
1051 * Acquires the PDM lock.
1052 *
1053 * @returns VINF_SUCCESS on success.
1054 * @returns rc if we failed to acquire the lock.
1055 * @param pDevIns The APIC device instance.
1056 * @param rc What to return if we fail to acquire the lock.
1057 */
1058 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1059
1060 /**
1061 * Releases the PDM lock.
1062 *
1063 * @param pDevIns The APIC device instance.
1064 */
1065 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1066#endif
1067 /** Just a safety precaution. */
1068 uint32_t u32TheEnd;
1069} PDMAPICHLPGC;
1070/** Pointer to APIC GC helpers. */
1071typedef GCPTRTYPE(PDMAPICHLPGC *) PPDMAPICHLPGC;
1072/** Pointer to const APIC helpers. */
1073typedef GCPTRTYPE(const PDMAPICHLPGC *) PCPDMAPICHLPGC;
1074
1075/** Current PDMAPICHLPGC version number. */
1076#define PDM_APICHLPGC_VERSION 0x60010000
1077
1078
1079/**
1080 * APIC R0 helpers.
1081 */
1082typedef struct PDMAPICHLPR0
1083{
1084 /** Structure version. PDM_APICHLPR0_VERSION defines the current version. */
1085 uint32_t u32Version;
1086
1087 /**
1088 * Set the interrupt force action flag.
1089 *
1090 * @param pDevIns Device instance of the APIC.
1091 */
1092 DECLR0CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
1093
1094 /**
1095 * Clear the interrupt force action flag.
1096 *
1097 * @param pDevIns Device instance of the APIC.
1098 */
1099 DECLR0CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
1100
1101 /**
1102 * Sets or clears the APIC bit in the CPUID feature masks.
1103 *
1104 * @param pDevIns Device instance of the APIC.
1105 * @param fEnabled If true the bit is set, else cleared.
1106 */
1107 DECLR0CALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));
1108
1109#ifdef VBOX_WITH_PDM_LOCK
1110 /**
1111 * Acquires the PDM lock.
1112 *
1113 * @returns VINF_SUCCESS on success.
1114 * @returns rc if we failed to acquire the lock.
1115 * @param pDevIns The APIC device instance.
1116 * @param rc What to return if we fail to acquire the lock.
1117 */
1118 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1119
1120 /**
1121 * Releases the PDM lock.
1122 *
1123 * @param pDevIns The APIC device instance.
1124 */
1125 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1126#endif
1127
1128 /** Just a safety precaution. */
1129 uint32_t u32TheEnd;
1130} PDMAPICHLPR0;
1131/** Pointer to APIC GC helpers. */
1132typedef GCPTRTYPE(PDMAPICHLPR0 *) PPDMAPICHLPR0;
1133/** Pointer to const APIC helpers. */
1134typedef R0PTRTYPE(const PDMAPICHLPR0 *) PCPDMAPICHLPR0;
1135
1136/** Current PDMAPICHLPR0 version number. */
1137#define PDM_APICHLPR0_VERSION 0x60010000
1138
1139/**
1140 * APIC HC helpers.
1141 */
1142typedef struct PDMAPICHLPR3
1143{
1144 /** Structure version. PDM_APICHLPR3_VERSION defines the current version. */
1145 uint32_t u32Version;
1146
1147 /**
1148 * Set the interrupt force action flag.
1149 *
1150 * @param pDevIns Device instance of the APIC.
1151 */
1152 DECLR3CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
1153
1154 /**
1155 * Clear the interrupt force action flag.
1156 *
1157 * @param pDevIns Device instance of the APIC.
1158 */
1159 DECLR3CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
1160
1161 /**
1162 * Sets or clears the APIC bit in the CPUID feature masks.
1163 *
1164 * @param pDevIns Device instance of the APIC.
1165 * @param fEnabled If true the bit is set, else cleared.
1166 */
1167 DECLR3CALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));
1168
1169#ifdef VBOX_WITH_PDM_LOCK
1170 /**
1171 * Acquires the PDM lock.
1172 *
1173 * @returns VINF_SUCCESS on success.
1174 * @returns Fatal error on failure.
1175 * @param pDevIns The APIC device instance.
1176 * @param rc Dummy for making the interface identical to the GC and R0 versions.
1177 */
1178 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1179
1180 /**
1181 * Releases the PDM lock.
1182 *
1183 * @param pDevIns The APIC device instance.
1184 */
1185 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1186#endif
1187
1188 /**
1189 * Gets the address of the GC APIC helpers.
1190 *
1191 * This should be called at both construction and relocation time
1192 * to obtain the correct address of the GC helpers.
1193 *
1194 * @returns GC pointer to the APIC helpers.
1195 * @param pDevIns Device instance of the APIC.
1196 */
1197 DECLR3CALLBACKMEMBER(PCPDMAPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
1198
1199 /**
1200 * Gets the address of the R0 APIC helpers.
1201 *
1202 * This should be called at both construction and relocation time
1203 * to obtain the correct address of the R0 helpers.
1204 *
1205 * @returns R0 pointer to the APIC helpers.
1206 * @param pDevIns Device instance of the APIC.
1207 */
1208 DECLR3CALLBACKMEMBER(PCPDMAPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
1209
1210 /** Just a safety precaution. */
1211 uint32_t u32TheEnd;
1212} PDMAPICHLPR3;
1213/** Pointer to APIC helpers. */
1214typedef HCPTRTYPE(PDMAPICHLPR3 *) PPDMAPICHLPR3;
1215/** Pointer to const APIC helpers. */
1216typedef HCPTRTYPE(const PDMAPICHLPR3 *) PCPDMAPICHLPR3;
1217
1218/** Current PDMAPICHLP version number. */
1219#define PDM_APICHLPR3_VERSION 0xfd010000
1220
1221
1222/**
1223 * I/O APIC registration structure.
1224 */
1225typedef struct PDMIOAPICREG
1226{
1227 /** Struct version+magic number (PDM_IOAPICREG_VERSION). */
1228 uint32_t u32Version;
1229
1230 /**
1231 * Set the an IRQ.
1232 *
1233 * @param pDevIns Device instance of the I/O APIC.
1234 * @param iIrq IRQ number to set.
1235 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1236 */
1237 DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
1238
1239 /** The name of the GC SetIrq entry point. */
1240 const char *pszSetIrqGC;
1241
1242 /** The name of the R0 SetIrq entry point. */
1243 const char *pszSetIrqR0;
1244} PDMIOAPICREG;
1245/** Pointer to an APIC registration structure. */
1246typedef PDMIOAPICREG *PPDMIOAPICREG;
1247
1248/** Current PDMAPICREG version number. */
1249#define PDM_IOAPICREG_VERSION 0x50010000
1250
1251
1252/**
1253 * IOAPIC GC helpers.
1254 */
1255typedef struct PDMIOAPICHLPGC
1256{
1257 /** Structure version. PDM_IOAPICHLPGC_VERSION defines the current version. */
1258 uint32_t u32Version;
1259
1260 /**
1261 * Private interface between the IOAPIC and APIC.
1262 *
1263 * See comments about this hack on PDMAPICREG::pfnBusDeliverHC.
1264 *
1265 * @returns The current TPR.
1266 * @param pDevIns Device instance of the IOAPIC.
1267 * @param u8Dest See APIC implementation.
1268 * @param u8DestMode See APIC implementation.
1269 * @param u8DeliveryMode See APIC implementation.
1270 * @param iVector See APIC implementation.
1271 * @param u8Polarity See APIC implementation.
1272 * @param u8TriggerMode See APIC implementation.
1273 */
1274 DECLGCCALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
1275 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
1276
1277#ifdef VBOX_WITH_PDM_LOCK
1278 /**
1279 * Acquires the PDM lock.
1280 *
1281 * @returns VINF_SUCCESS on success.
1282 * @returns rc if we failed to acquire the lock.
1283 * @param pDevIns The IOAPIC device instance.
1284 * @param rc What to return if we fail to acquire the lock.
1285 */
1286 DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1287
1288 /**
1289 * Releases the PDM lock.
1290 *
1291 * @param pDevIns The IOAPIC device instance.
1292 */
1293 DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1294#endif
1295
1296 /** Just a safety precaution. */
1297 uint32_t u32TheEnd;
1298} PDMIOAPICHLPGC;
1299/** Pointer to IOAPIC GC helpers. */
1300typedef GCPTRTYPE(PDMAPICHLPGC *)PPDMIOAPICHLPGC;
1301/** Pointer to const IOAPIC helpers. */
1302typedef GCPTRTYPE(const PDMIOAPICHLPGC *) PCPDMIOAPICHLPGC;
1303
1304/** Current PDMIOAPICHLPGC version number. */
1305#define PDM_IOAPICHLPGC_VERSION 0xfe010000
1306
1307
1308/**
1309 * IOAPIC R0 helpers.
1310 */
1311typedef struct PDMIOAPICHLPR0
1312{
1313 /** Structure version. PDM_IOAPICHLPR0_VERSION defines the current version. */
1314 uint32_t u32Version;
1315
1316 /**
1317 * Private interface between the IOAPIC and APIC.
1318 *
1319 * See comments about this hack on PDMAPICREG::pfnBusDeliverHC.
1320 *
1321 * @returns The current TPR.
1322 * @param pDevIns Device instance of the IOAPIC.
1323 * @param u8Dest See APIC implementation.
1324 * @param u8DestMode See APIC implementation.
1325 * @param u8DeliveryMode See APIC implementation.
1326 * @param iVector See APIC implementation.
1327 * @param u8Polarity See APIC implementation.
1328 * @param u8TriggerMode See APIC implementation.
1329 */
1330 DECLR0CALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
1331 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
1332
1333#ifdef VBOX_WITH_PDM_LOCK
1334 /**
1335 * Acquires the PDM lock.
1336 *
1337 * @returns VINF_SUCCESS on success.
1338 * @returns rc if we failed to acquire the lock.
1339 * @param pDevIns The IOAPIC device instance.
1340 * @param rc What to return if we fail to acquire the lock.
1341 */
1342 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1343
1344 /**
1345 * Releases the PDM lock.
1346 *
1347 * @param pDevIns The IOAPIC device instance.
1348 */
1349 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1350#endif
1351
1352 /** Just a safety precaution. */
1353 uint32_t u32TheEnd;
1354} PDMIOAPICHLPR0;
1355/** Pointer to IOAPIC R0 helpers. */
1356typedef R0PTRTYPE(PDMAPICHLPGC *) PPDMIOAPICHLPR0;
1357/** Pointer to const IOAPIC helpers. */
1358typedef R0PTRTYPE(const PDMIOAPICHLPR0 *) PCPDMIOAPICHLPR0;
1359
1360/** Current PDMIOAPICHLPR0 version number. */
1361#define PDM_IOAPICHLPR0_VERSION 0xfe010000
1362
1363/**
1364 * IOAPIC HC helpers.
1365 */
1366typedef struct PDMIOAPICHLPR3
1367{
1368 /** Structure version. PDM_IOAPICHLPR3_VERSION defines the current version. */
1369 uint32_t u32Version;
1370
1371 /**
1372 * Private interface between the IOAPIC and APIC.
1373 *
1374 * See comments about this hack on PDMAPICREG::pfnBusDeliverHC.
1375 *
1376 * @returns The current TPR.
1377 * @param pDevIns Device instance of the IOAPIC.
1378 * @param u8Dest See APIC implementation.
1379 * @param u8DestMode See APIC implementation.
1380 * @param u8DeliveryMode See APIC implementation.
1381 * @param iVector See APIC implementation.
1382 * @param u8Polarity See APIC implementation.
1383 * @param u8TriggerMode See APIC implementation.
1384 */
1385 DECLR3CALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
1386 uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
1387
1388#ifdef VBOX_WITH_PDM_LOCK
1389 /**
1390 * Acquires the PDM lock.
1391 *
1392 * @returns VINF_SUCCESS on success.
1393 * @returns Fatal error on failure.
1394 * @param pDevIns The IOAPIC device instance.
1395 * @param rc Dummy for making the interface identical to the GC and R0 versions.
1396 */
1397 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1398
1399 /**
1400 * Releases the PDM lock.
1401 *
1402 * @param pDevIns The IOAPIC device instance.
1403 */
1404 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1405#endif
1406
1407 /**
1408 * Gets the address of the GC IOAPIC helpers.
1409 *
1410 * This should be called at both construction and relocation time
1411 * to obtain the correct address of the GC helpers.
1412 *
1413 * @returns GC pointer to the IOAPIC helpers.
1414 * @param pDevIns Device instance of the IOAPIC.
1415 */
1416 DECLR3CALLBACKMEMBER(PCPDMIOAPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
1417
1418 /**
1419 * Gets the address of the R0 IOAPIC helpers.
1420 *
1421 * This should be called at both construction and relocation time
1422 * to obtain the correct address of the R0 helpers.
1423 *
1424 * @returns R0 pointer to the IOAPIC helpers.
1425 * @param pDevIns Device instance of the IOAPIC.
1426 */
1427 DECLR3CALLBACKMEMBER(PCPDMIOAPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
1428
1429 /** Just a safety precaution. */
1430 uint32_t u32TheEnd;
1431} PDMIOAPICHLPR3;
1432/** Pointer to IOAPIC HC helpers. */
1433typedef HCPTRTYPE(PDMIOAPICHLPR3 *) PPDMIOAPICHLPR3;
1434/** Pointer to const IOAPIC helpers. */
1435typedef HCPTRTYPE(const PDMIOAPICHLPR3 *) PCPDMIOAPICHLPR3;
1436
1437/** Current PDMIOAPICHLPR3 version number. */
1438#define PDM_IOAPICHLPR3_VERSION 0xff010000
1439
1440
1441
1442#ifdef IN_RING3
1443
1444/**
1445 * DMA Transfer Handler.
1446 *
1447 * @returns Number of bytes transferred.
1448 * @param pDevIns Device instance of the DMA.
1449 * @param pvUser User pointer.
1450 * @param uChannel Channel number.
1451 * @param off DMA position.
1452 * @param cb Block size.
1453 */
1454typedef DECLCALLBACK(uint32_t) FNDMATRANSFERHANDLER(PPDMDEVINS pDevIns, void *pvUser, unsigned uChannel, uint32_t off, uint32_t cb);
1455/** Pointer to a FNDMATRANSFERHANDLER(). */
1456typedef FNDMATRANSFERHANDLER *PFNDMATRANSFERHANDLER;
1457
1458/**
1459 * DMA Controller registration structure.
1460 */
1461typedef struct PDMDMAREG
1462{
1463 /** Structure version number. PDM_DMACREG_VERSION defines the current version. */
1464 uint32_t u32Version;
1465
1466 /**
1467 * Execute pending transfers.
1468 *
1469 * @returns A more work indiciator. I.e. 'true' if there is more to be done, and 'false' if all is done.
1470 * @param pDevIns Device instance of the DMAC.
1471 */
1472 DECLR3CALLBACKMEMBER(bool, pfnRun,(PPDMDEVINS pDevIns));
1473
1474 /**
1475 * Register transfer function for DMA channel.
1476 *
1477 * @param pDevIns Device instance of the DMAC.
1478 * @param uChannel Channel number.
1479 * @param pfnTransferHandler Device specific transfer function.
1480 * @param pvUSer User pointer to be passed to the callback.
1481 */
1482 DECLR3CALLBACKMEMBER(void, pfnRegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
1483
1484 /**
1485 * Read memory
1486 *
1487 * @returns Number of bytes read.
1488 * @param pDevIns Device instance of the DMAC.
1489 * @param pvBuffer Pointer to target buffer.
1490 * @param off DMA position.
1491 * @param cbBlock Block size.
1492 */
1493 DECLR3CALLBACKMEMBER(uint32_t, pfnReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock));
1494
1495 /**
1496 * Write memory
1497 *
1498 * @returns Number of bytes written.
1499 * @param pDevIns Device instance of the DMAC.
1500 * @param pvBuffer Memory to write.
1501 * @param off DMA position.
1502 * @param cbBlock Block size.
1503 */
1504 DECLR3CALLBACKMEMBER(uint32_t, pfnWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock));
1505
1506 /**
1507 * Set the DREQ line.
1508 *
1509 * @param pDevIns Device instance of the DMAC.
1510 * @param uChannel Channel number.
1511 * @param uLevel Level of the line.
1512 */
1513 DECLR3CALLBACKMEMBER(void, pfnSetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
1514
1515 /**
1516 * Get channel mode
1517 *
1518 * @returns Channel mode.
1519 * @param pDevIns Device instance of the DMAC.
1520 * @param uChannel Channel number.
1521 */
1522 DECLR3CALLBACKMEMBER(uint8_t, pfnGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
1523
1524} PDMDMACREG;
1525/** Pointer to a DMAC registration structure. */
1526typedef PDMDMACREG *PPDMDMACREG;
1527
1528/** Current PDMDMACREG version number. */
1529#define PDM_DMACREG_VERSION 0xf5010000
1530
1531
1532/**
1533 * DMA Controller device helpers.
1534 */
1535typedef struct PDMDMACHLP
1536{
1537 /** Structure version. PDM_DMACHLP_VERSION defines the current version. */
1538 uint32_t u32Version;
1539
1540 /* to-be-defined */
1541
1542} PDMDMACHLP;
1543/** Pointer to DMAC helpers. */
1544typedef PDMDMACHLP *PPDMDMACHLP;
1545/** Pointer to const DMAC helpers. */
1546typedef const PDMDMACHLP *PCPDMDMACHLP;
1547
1548/** Current PDMDMACHLP version number. */
1549#define PDM_DMACHLP_VERSION 0xf6010000
1550
1551#endif /* IN_RING3 */
1552
1553
1554
1555/**
1556 * RTC registration structure.
1557 */
1558typedef struct PDMRTCREG
1559{
1560 /** Structure version number. PDM_RTCREG_VERSION defines the current version. */
1561 uint32_t u32Version;
1562 uint32_t u32Alignment; /**< structure size alignment. */
1563
1564 /**
1565 * Write to a CMOS register and update the checksum if necessary.
1566 *
1567 * @returns VBox status code.
1568 * @param pDevIns Device instance of the RTC.
1569 * @param iReg The CMOS register index.
1570 * @param u8Value The CMOS register value.
1571 */
1572 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
1573
1574 /**
1575 * Read a CMOS register.
1576 *
1577 * @returns VBox status code.
1578 * @param pDevIns Device instance of the RTC.
1579 * @param iReg The CMOS register index.
1580 * @param pu8Value Where to store the CMOS register value.
1581 */
1582 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
1583
1584} PDMRTCREG;
1585/** Pointer to a RTC registration structure. */
1586typedef PDMRTCREG *PPDMRTCREG;
1587/** Pointer to a const RTC registration structure. */
1588typedef const PDMRTCREG *PCPDMRTCREG;
1589
1590/** Current PDMRTCREG version number. */
1591#define PDM_RTCREG_VERSION 0xfa010000
1592
1593
1594/**
1595 * RTC device helpers.
1596 */
1597typedef struct PDMRTCHLP
1598{
1599 /** Structure version. PDM_RTCHLP_VERSION defines the current version. */
1600 uint32_t u32Version;
1601
1602 /* to-be-defined */
1603
1604} PDMRTCHLP;
1605/** Pointer to RTC helpers. */
1606typedef PDMRTCHLP *PPDMRTCHLP;
1607/** Pointer to const RTC helpers. */
1608typedef const PDMRTCHLP *PCPDMRTCHLP;
1609
1610/** Current PDMRTCHLP version number. */
1611#define PDM_RTCHLP_VERSION 0xf6010000
1612
1613
1614
1615#ifdef IN_RING3
1616
1617/**
1618 * PDM Device API.
1619 */
1620typedef struct PDMDEVHLP
1621{
1622 /** Structure version. PDM_DEVHLP_VERSION defines the current version. */
1623 uint32_t u32Version;
1624
1625 /**
1626 * Register a number of I/O ports with a device.
1627 *
1628 * These callbacks are of course for the host context (HC).
1629 * Register HC handlers before guest context (GC) handlers! There must be a
1630 * HC handler for every GC handler!
1631 *
1632 * @returns VBox status.
1633 * @param pDevIns The device instance to register the ports with.
1634 * @param Port First port number in the range.
1635 * @param cPorts Number of ports to register.
1636 * @param pvUser User argument.
1637 * @param pfnOut Pointer to function which is gonna handle OUT operations.
1638 * @param pfnIn Pointer to function which is gonna handle IN operations.
1639 * @param pfnOutStr Pointer to function which is gonna handle string OUT operations.
1640 * @param pfnInStr Pointer to function which is gonna handle string IN operations.
1641 * @param pszDesc Pointer to description string. This must not be freed.
1642 */
1643 DECLR3CALLBACKMEMBER(int, pfnIOPortRegister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTHCPTR pvUser,
1644 PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,
1645 PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc));
1646
1647 /**
1648 * Register a number of I/O ports with a device for GC.
1649 *
1650 * These callbacks are for the host context (GC).
1651 * Register host context (HC) handlers before guest context handlers! There must be a
1652 * HC handler for every GC handler!
1653 *
1654 * @returns VBox status.
1655 * @param pDevIns The device instance to register the ports with and which GC module
1656 * to resolve the names against.
1657 * @param Port First port number in the range.
1658 * @param cPorts Number of ports to register.
1659 * @param pvUser User argument.
1660 * @param pszOut Name of the GC function which is gonna handle OUT operations.
1661 * @param pszIn Name of the GC function which is gonna handle IN operations.
1662 * @param pszOutStr Name of the GC function which is gonna handle string OUT operations.
1663 * @param pszInStr Name of the GC function which is gonna handle string IN operations.
1664 * @param pszDesc Pointer to description string. This must not be freed.
1665 */
1666 DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterGC,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTGCPTR pvUser,
1667 const char *pszOut, const char *pszIn,
1668 const char *pszOutStr, const char *pszInStr, const char *pszDesc));
1669
1670 /**
1671 * Register a number of I/O ports with a device.
1672 *
1673 * These callbacks are of course for the ring-0 host context (R0).
1674 * Register R3 (HC) handlers before R0 (R0) handlers! There must be a R3 (HC) handler for every R0 handler!
1675 *
1676 * @returns VBox status.
1677 * @param pDevIns The device instance to register the ports with.
1678 * @param Port First port number in the range.
1679 * @param cPorts Number of ports to register.
1680 * @param pvUser User argument. (if pointer, then it must be in locked memory!)
1681 * @param pszOut Name of the R0 function which is gonna handle OUT operations.
1682 * @param pszIn Name of the R0 function which is gonna handle IN operations.
1683 * @param pszOutStr Name of the R0 function which is gonna handle string OUT operations.
1684 * @param pszInStr Name of the R0 function which is gonna handle string IN operations.
1685 * @param pszDesc Pointer to description string. This must not be freed.
1686 */
1687 DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterR0,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTR0PTR pvUser,
1688 const char *pszOut, const char *pszIn,
1689 const char *pszOutStr, const char *pszInStr, const char *pszDesc));
1690
1691 /**
1692 * Deregister I/O ports.
1693 *
1694 * This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.
1695 *
1696 * @returns VBox status.
1697 * @param pDevIns The device instance owning the ports.
1698 * @param Port First port number in the range.
1699 * @param cPorts Number of ports to deregister.
1700 */
1701 DECLR3CALLBACKMEMBER(int, pfnIOPortDeregister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts));
1702
1703
1704 /**
1705 * Register a Memory Mapped I/O (MMIO) region.
1706 *
1707 * These callbacks are of course for the host context (HC).
1708 * Register HC handlers before guest context (GC) handlers! There must be a
1709 * HC handler for every GC handler!
1710 *
1711 * @returns VBox status.
1712 * @param pDevIns The device instance to register the MMIO with.
1713 * @param GCPhysStart First physical address in the range.
1714 * @param cbRange The size of the range (in bytes).
1715 * @param pvUser User argument.
1716 * @param pfnWrite Pointer to function which is gonna handle Write operations.
1717 * @param pfnRead Pointer to function which is gonna handle Read operations.
1718 * @param pfnFill Pointer to function which is gonna handle Fill/memset operations. (optional)
1719 * @param pszDesc Pointer to description string. This must not be freed.
1720 */
1721 DECLR3CALLBACKMEMBER(int, pfnMMIORegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTHCPTR pvUser,
1722 PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, PFNIOMMMIOFILL pfnFill,
1723 const char *pszDesc));
1724
1725 /**
1726 * Register a Memory Mapped I/O (MMIO) region for GC.
1727 *
1728 * These callbacks are for the guest context (GC).
1729 * Register host context (HC) handlers before guest context handlers! There must be a
1730 * HC handler for every GC handler!
1731 *
1732 * @returns VBox status.
1733 * @param pDevIns The device instance to register the MMIO with.
1734 * @param GCPhysStart First physical address in the range.
1735 * @param cbRange The size of the range (in bytes).
1736 * @param pvUser User argument.
1737 * @param pszWrite Name of the GC function which is gonna handle Write operations.
1738 * @param pszRead Name of the GC function which is gonna handle Read operations.
1739 * @param pszFill Name of the GC function which is gonna handle Fill/memset operations. (optional)
1740 * @param pszDesc Pointer to description string. This must not be freed.
1741 */
1742 DECLR3CALLBACKMEMBER(int, pfnMMIORegisterGC,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTGCPTR pvUser,
1743 const char *pszWrite, const char *pszRead, const char *pszFill,
1744 const char *pszDesc));
1745
1746 /**
1747 * Register a Memory Mapped I/O (MMIO) region for R0.
1748 *
1749 * These callbacks are for the ring-0 host context (R0).
1750 * Register R3 (HC) handlers before R0 handlers! There must be a R3 handler for every R0 handler!
1751 *
1752 * @returns VBox status.
1753 * @param pDevIns The device instance to register the MMIO with.
1754 * @param GCPhysStart First physical address in the range.
1755 * @param cbRange The size of the range (in bytes).
1756 * @param pvUser User argument. (if pointer, then it must be in locked memory!)
1757 * @param pszWrite Name of the GC function which is gonna handle Write operations.
1758 * @param pszRead Name of the GC function which is gonna handle Read operations.
1759 * @param pszFill Name of the GC function which is gonna handle Fill/memset operations. (optional)
1760 * @param pszDesc Pointer to description string. This must not be freed.
1761 */
1762 DECLR3CALLBACKMEMBER(int, pfnMMIORegisterR0,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTR0PTR pvUser,
1763 const char *pszWrite, const char *pszRead, const char *pszFill,
1764 const char *pszDesc));
1765
1766 /**
1767 * Deregister a Memory Mapped I/O (MMIO) region.
1768 *
1769 * This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.
1770 *
1771 * @returns VBox status.
1772 * @param pDevIns The device instance owning the MMIO region(s).
1773 * @param GCPhysStart First physical address in the range.
1774 * @param cbRange The size of the range (in bytes).
1775 */
1776 DECLR3CALLBACKMEMBER(int, pfnMMIODeregister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange));
1777
1778 /**
1779 * Register a ROM (BIOS) region.
1780 *
1781 * It goes without saying that this is read-only memory. The memory region must be
1782 * in unassigned memory. I.e. from the top of the address space or on the PC in
1783 * the 0xa0000-0xfffff range.
1784 *
1785 * @returns VBox status.
1786 * @param pDevIns The device instance owning the ROM region.
1787 * @param GCPhysStart First physical address in the range.
1788 * Must be page aligned!
1789 * @param cbRange The size of the range (in bytes).
1790 * Must be page aligned!
1791 * @param pvBinary Pointer to the binary data backing the ROM image.
1792 * This must be cbRange bytes big.
1793 * It will be copied and doesn't have to stick around if fShadow is clear.
1794 * @param fShadow Whether to emulate ROM shadowing. This involves leaving
1795 * the ROM writable for a while during the POST and refreshing
1796 * it at reset. When this flag is set, the memory pointed to by
1797 * pvBinary has to stick around for the lifespan of the VM.
1798 * @param pszDesc Pointer to description string. This must not be freed.
1799 *
1800 * @remark There is no way to remove the rom, automatically on device cleanup or
1801 * manually from the device yet. At present I doubt we need such features...
1802 */
1803 DECLR3CALLBACKMEMBER(int, pfnROMRegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, const void *pvBinary, bool fShadow, const char *pszDesc));
1804
1805 /**
1806 * Register a save state data unit.
1807 *
1808 * @returns VBox status.
1809 * @param pDevIns Device instance.
1810 * @param pszName Data unit name.
1811 * @param u32Instance The instance identifier of the data unit.
1812 * This must together with the name be unique.
1813 * @param u32Version Data layout version number.
1814 * @param cbGuess The approximate amount of data in the unit.
1815 * Only for progress indicators.
1816 * @param pfnSavePrep Prepare save callback, optional.
1817 * @param pfnSaveExec Execute save callback, optional.
1818 * @param pfnSaveDone Done save callback, optional.
1819 * @param pfnLoadPrep Prepare load callback, optional.
1820 * @param pfnLoadExec Execute load callback, optional.
1821 * @param pfnLoadDone Done load callback, optional.
1822 */
1823 DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDEVINS pDevIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
1824 PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
1825 PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone));
1826
1827 /**
1828 * Creates a timer.
1829 *
1830 * @returns VBox status.
1831 * @param pDevIns Device instance.
1832 * @param enmClock The clock to use on this timer.
1833 * @param pfnCallback Callback function.
1834 * @param pszDesc Pointer to description string which must stay around
1835 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
1836 * @param ppTimer Where to store the timer on success.
1837 */
1838 DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer));
1839
1840 /**
1841 * Creates an external timer.
1842 *
1843 * @returns timer pointer
1844 * @param pDevIns Device instance.
1845 * @param enmClock The clock to use on this timer.
1846 * @param pfnCallback Callback function.
1847 * @param pvUser User pointer
1848 * @param pszDesc Pointer to description string which must stay around
1849 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
1850 */
1851 DECLR3CALLBACKMEMBER(PTMTIMERHC, pfnTMTimerCreateExternal,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMEREXT pfnCallback, void *pvUser, const char *pszDesc));
1852
1853 /**
1854 * Registers the device with the default PCI bus.
1855 *
1856 * @returns VBox status code.
1857 * @param pDevIns Device instance.
1858 * @param pPciDev The PCI device structure.
1859 * Any PCI enabled device must keep this in it's instance data!
1860 * Fill in the PCI data config before registration, please.
1861 * @remark This is the simple interface, a Ex interface will be created if
1862 * more features are needed later.
1863 */
1864 DECLR3CALLBACKMEMBER(int, pfnPCIRegister,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev));
1865
1866 /**
1867 * Registers a I/O region (memory mapped or I/O ports) for a PCI device.
1868 *
1869 * @returns VBox status code.
1870 * @param pDevIns Device instance.
1871 * @param iRegion The region number.
1872 * @param cbRegion Size of the region.
1873 * @param enmType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
1874 * @param pfnCallback Callback for doing the mapping.
1875 */
1876 DECLR3CALLBACKMEMBER(int, pfnPCIIORegionRegister,(PPDMDEVINS pDevIns, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback));
1877
1878 /**
1879 * Register PCI configuration space read/write callbacks.
1880 *
1881 * @param pDevIns Device instance.
1882 * @param pPciDev The PCI device structure.
1883 * If NULL the default PCI device for this device instance is used.
1884 * @param pfnRead Pointer to the user defined PCI config read function.
1885 * @param ppfnReadOld Pointer to function pointer which will receive the old (default)
1886 * PCI config read function. This way, user can decide when (and if)
1887 * to call default PCI config read function. Can be NULL.
1888 * @param pfnWrite Pointer to the user defined PCI config write function.
1889 * @param pfnWriteOld Pointer to function pointer which will receive the old (default)
1890 * PCI config write function. This way, user can decide when (and if)
1891 * to call default PCI config write function. Can be NULL.
1892 * @thread EMT
1893 */
1894 DECLR3CALLBACKMEMBER(void, pfnPCISetConfigCallbacks,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,
1895 PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld));
1896
1897 /**
1898 * Set the IRQ for a PCI device.
1899 *
1900 * @param pDevIns Device instance.
1901 * @param iIrq IRQ number to set.
1902 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1903 * @thread Any thread, but will involve the emulation thread.
1904 */
1905 DECLR3CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
1906
1907 /**
1908 * Set the IRQ for a PCI device, but don't wait for EMT to process
1909 * the request when not called from EMT.
1910 *
1911 * @param pDevIns Device instance.
1912 * @param iIrq IRQ number to set.
1913 * @param iLevel IRQ level.
1914 * @thread Any thread, but will involve the emulation thread.
1915 */
1916 DECLR3CALLBACKMEMBER(void, pfnPCISetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
1917
1918 /**
1919 * Set ISA IRQ for a device.
1920 *
1921 * @param pDevIns Device instance.
1922 * @param iIrq IRQ number to set.
1923 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1924 * @thread Any thread, but will involve the emulation thread.
1925 */
1926 DECLR3CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
1927
1928 /**
1929 * Set the ISA IRQ for a device, but don't wait for EMT to process
1930 * the request when not called from EMT.
1931 *
1932 * @param pDevIns Device instance.
1933 * @param iIrq IRQ number to set.
1934 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1935 * @thread Any thread, but will involve the emulation thread.
1936 */
1937 DECLR3CALLBACKMEMBER(void, pfnISASetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
1938
1939 /**
1940 * Attaches a driver (chain) to the device.
1941 *
1942 * The first call for a LUN this will serve as a registartion of the LUN. The pBaseInterface and
1943 * the pszDesc string will be registered with that LUN and kept around for PDMR3QueryDeviceLun().
1944 *
1945 * @returns VBox status code.
1946 * @param pDevIns Device instance.
1947 * @param iLun The logical unit to attach.
1948 * @param pBaseInterface Pointer to the base interface for that LUN. (device side / down)
1949 * @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up)
1950 * @param pszDesc Pointer to a string describing the LUN. This string must remain valid
1951 * for the live of the device instance.
1952 */
1953 DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMDEVINS pDevIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE *ppBaseInterface, const char *pszDesc));
1954
1955 /**
1956 * Allocate memory which is associated with current VM instance
1957 * and automatically freed on it's destruction.
1958 *
1959 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
1960 * @param pDevIns Device instance.
1961 * @param cb Number of bytes to allocate.
1962 */
1963 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVINS pDevIns, size_t cb));
1964
1965 /**
1966 * Allocate memory which is associated with current VM instance
1967 * and automatically freed on it's destruction. The memory is ZEROed.
1968 *
1969 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
1970 * @param pDevIns Device instance.
1971 * @param cb Number of bytes to allocate.
1972 */
1973 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAllocZ,(PPDMDEVINS pDevIns, size_t cb));
1974
1975 /**
1976 * Free memory allocated with pfnMMHeapAlloc() and pfnMMHeapAllocZ().
1977 *
1978 * @param pDevIns Device instance.
1979 * @param pv Pointer to the memory to free.
1980 */
1981 DECLR3CALLBACKMEMBER(void, pfnMMHeapFree,(PPDMDEVINS pDevIns, void *pv));
1982
1983 /**
1984 * Set the VM error message
1985 *
1986 * @returns rc.
1987 * @param pDevIns Device instance.
1988 * @param rc VBox status code.
1989 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
1990 * @param pszFormat Error message format string.
1991 * @param ... Error message arguments.
1992 */
1993 DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
1994
1995 /**
1996 * Set the VM error message
1997 *
1998 * @returns rc.
1999 * @param pDevIns Device instance.
2000 * @param rc VBox status code.
2001 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
2002 * @param pszFormat Error message format string.
2003 * @param va Error message arguments.
2004 */
2005 DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
2006
2007 /**
2008 * Set the VM runtime error message
2009 *
2010 * @returns VBox status code.
2011 * @param pDevIns Device instance.
2012 * @param fFatal Whether it is a fatal error or not.
2013 * @param pszErrorID Error ID string.
2014 * @param pszFormat Error message format string.
2015 * @param ... Error message arguments.
2016 */
2017 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));
2018
2019 /**
2020 * Set the VM runtime error message
2021 *
2022 * @returns VBox status code.
2023 * @param pDevIns Device instance.
2024 * @param fFatal Whether it is a fatal error or not.
2025 * @param pszErrorID Error ID string.
2026 * @param pszFormat Error message format string.
2027 * @param va Error message arguments.
2028 */
2029 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));
2030
2031 /**
2032 * Assert that the current thread is the emulation thread.
2033 *
2034 * @returns True if correct.
2035 * @returns False if wrong.
2036 * @param pDevIns Device instance.
2037 * @param pszFile Filename of the assertion location.
2038 * @param iLine The linenumber of the assertion location.
2039 * @param pszFunction Function of the assertion location.
2040 */
2041 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction));
2042
2043 /**
2044 * Assert that the current thread is NOT the emulation thread.
2045 *
2046 * @returns True if correct.
2047 * @returns False if wrong.
2048 * @param pDevIns Device instance.
2049 * @param pszFile Filename of the assertion location.
2050 * @param iLine The linenumber of the assertion location.
2051 * @param pszFunction Function of the assertion location.
2052 */
2053 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction));
2054
2055 /**
2056 * Stops the VM and enters the debugger to look at the guest state.
2057 *
2058 * Use the PDMDeviceDBGFStop() inline function with the RT_SRC_POS macro instead of
2059 * invoking this function directly.
2060 *
2061 * @returns VBox status code which must be passed up to the VMM.
2062 * @param pDevIns Device instance.
2063 * @param pszFile Filename of the assertion location.
2064 * @param iLine The linenumber of the assertion location.
2065 * @param pszFunction Function of the assertion location.
2066 * @param pszFormat Message. (optional)
2067 * @param args Message parameters.
2068 */
2069 DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction, const char *pszFormat, va_list args));
2070
2071 /**
2072 * Register a info handler with DBGF,
2073 *
2074 * @returns VBox status code.
2075 * @param pDevIns Device instance.
2076 * @param pszName The identifier of the info.
2077 * @param pszDesc The description of the info and any arguments the handler may take.
2078 * @param pfnHandler The handler function to be called to display the info.
2079 */
2080 DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMDEVINS pDevIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDEV pfnHandler));
2081
2082 /**
2083 * Registers a statistics sample if statistics are enabled.
2084 *
2085 * @param pDevIns Device instance of the DMA.
2086 * @param pvSample Pointer to the sample.
2087 * @param enmType Sample type. This indicates what pvSample is pointing at.
2088 * @param pszName Sample name. The name is on this form "/<component>/<sample>".
2089 * Further nesting is possible.
2090 * @param enmUnit Sample unit.
2091 * @param pszDesc Sample description.
2092 */
2093 DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc));
2094
2095 /**
2096 * Same as pfnSTAMRegister except that the name is specified in a
2097 * RTStrPrintf like fashion.
2098 *
2099 * @returns VBox status.
2100 * @param pDevIns Device instance of the DMA.
2101 * @param pvSample Pointer to the sample.
2102 * @param enmType Sample type. This indicates what pvSample is pointing at.
2103 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
2104 * @param enmUnit Sample unit.
2105 * @param pszDesc Sample description.
2106 * @param pszName The sample name format string.
2107 * @param ... Arguments to the format string.
2108 */
2109 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
2110 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, ...));
2111
2112 /**
2113 * Same as pfnSTAMRegister except that the name is specified in a
2114 * RTStrPrintfV like fashion.
2115 *
2116 * @returns VBox status.
2117 * @param pDevIns Device instance of the DMA.
2118 * @param pvSample Pointer to the sample.
2119 * @param enmType Sample type. This indicates what pvSample is pointing at.
2120 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
2121 * @param enmUnit Sample unit.
2122 * @param pszDesc Sample description.
2123 * @param pszName The sample name format string.
2124 * @param args Arguments to the format string.
2125 */
2126 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
2127 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list args));
2128
2129 /**
2130 * Register the RTC device.
2131 *
2132 * @returns VBox status code.
2133 * @param pDevIns Device instance.
2134 * @param pRtcReg Pointer to a RTC registration structure.
2135 * @param ppRtcHlp Where to store the pointer to the helper functions.
2136 */
2137 DECLR3CALLBACKMEMBER(int, pfnRTCRegister,(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp));
2138
2139 /**
2140 * Create a queue.
2141 *
2142 * @returns VBox status code.
2143 * @param pDevIns The device instance.
2144 * @param cbItem The size of a queue item.
2145 * @param cItems The number of items in the queue.
2146 * @param cMilliesInterval The number of milliseconds between polling the queue.
2147 * If 0 then the emulation thread will be notified whenever an item arrives.
2148 * @param pfnCallback The consumer function.
2149 * @param fGCEnabled Set if the queue should work in GC too.
2150 * @param ppQueue Where to store the queue handle on success.
2151 * @thread The emulation thread.
2152 */
2153 DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDEVINS pDevIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
2154 PFNPDMQUEUEDEV pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue));
2155
2156 /**
2157 * Initializes a PDM critical section.
2158 *
2159 * The PDM critical sections are derived from the IPRT critical sections, but
2160 * works in GC as well.
2161 *
2162 * @returns VBox status code.
2163 * @param pDevIns Device instance.
2164 * @param pCritSect Pointer to the critical section.
2165 * @param pszName The name of the critical section (for statistics).
2166 */
2167 DECLR3CALLBACKMEMBER(int, pfnCritSectInit,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, const char *pszName));
2168
2169 /**
2170 * Get the real world UTC time adjusted for VM lag, user offset and warpdrive.
2171 *
2172 * @returns pTime.
2173 * @param pDevIns Device instance.
2174 * @param pTime Where to store the time.
2175 */
2176 DECLR3CALLBACKMEMBER(PRTTIMESPEC, pfnUTCNow,(PPDMDEVINS pDevIns, PRTTIMESPEC pTime));
2177
2178 /**
2179 * Creates a PDM thread.
2180 *
2181 * This differs from the RTThreadCreate() API in that PDM takes care of suspending,
2182 * resuming, and destroying the thread as the VM state changes.
2183 *
2184 * @returns VBox status code.
2185 * @param pDevIns The device instance.
2186 * @param ppThread Where to store the thread 'handle'.
2187 * @param pvUser The user argument to the thread function.
2188 * @param pfnThread The thread function.
2189 * @param pfnWakeup The wakup callback. This is called on the EMT thread when
2190 * a state change is pending.
2191 * @param cbStack See RTThreadCreate.
2192 * @param enmType See RTThreadCreate.
2193 * @param pszName See RTThreadCreate.
2194 */
2195 DECLR3CALLBACKMEMBER(int, pfnPDMThreadCreate,(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
2196 PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
2197
2198 /**
2199 * Convert a guest virtual address to a guest physical address.
2200 *
2201 * @returns VBox status code.
2202 * @param pDevIns Device instance.
2203 * @param GCPtr Guest virtual address.
2204 * @param pGCPhys Where to store the GC physical address corresponding to GCPtr.
2205 * @thread The emulation thread.
2206 * @remark Careful with page boundraries.
2207 */
2208 DECLR3CALLBACKMEMBER(int, pfnPhysGCPtr2GCPhys, (PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTGCPHYS pGCPhys));
2209
2210 /** Space reserved for future members.
2211 * @{ */
2212 DECLR3CALLBACKMEMBER(void, pfnReserved3,(void));
2213 DECLR3CALLBACKMEMBER(void, pfnReserved4,(void));
2214 DECLR3CALLBACKMEMBER(void, pfnReserved5,(void));
2215 DECLR3CALLBACKMEMBER(void, pfnReserved6,(void));
2216 DECLR3CALLBACKMEMBER(void, pfnReserved7,(void));
2217 DECLR3CALLBACKMEMBER(void, pfnReserved8,(void));
2218 DECLR3CALLBACKMEMBER(void, pfnReserved9,(void));
2219 DECLR3CALLBACKMEMBER(void, pfnReserved10,(void));
2220 /** @} */
2221
2222
2223 /** API available to trusted devices only.
2224 *
2225 * These APIs are providing unrestricted access to the guest and the VM,
2226 * or they are interacting intimately with PDM.
2227 *
2228 * @{
2229 */
2230 /**
2231 * Gets the VM handle. Restricted API.
2232 *
2233 * @returns VM Handle.
2234 * @param pDevIns Device instance.
2235 */
2236 DECLR3CALLBACKMEMBER(PVM, pfnGetVM,(PPDMDEVINS pDevIns));
2237
2238 /**
2239 * Register the PCI Bus.
2240 *
2241 * @returns VBox status code.
2242 * @param pDevIns Device instance.
2243 * @param pPciBusReg Pointer to PCI bus registration structure.
2244 * @param ppPciHlpR3 Where to store the pointer to the PCI Bus helpers.
2245 */
2246 DECLR3CALLBACKMEMBER(int, pfnPCIBusRegister,(PPDMDEVINS pDevIns, PPDMPCIBUSREG pPciBusReg, PCPDMPCIHLPR3 *ppPciHlpR3));
2247
2248 /**
2249 * Register the PIC device.
2250 *
2251 * @returns VBox status code.
2252 * @param pDevIns Device instance.
2253 * @param pPicReg Pointer to a PIC registration structure.
2254 * @param ppPicHlpR3 Where to store the pointer to the PIC HC helpers.
2255 */
2256 DECLR3CALLBACKMEMBER(int, pfnPICRegister,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLPR3 *ppPicHlpR3));
2257
2258 /**
2259 * Register the APIC device.
2260 *
2261 * @returns VBox status code.
2262 * @param pDevIns Device instance.
2263 * @param pApicReg Pointer to a APIC registration structure.
2264 * @param ppApicHlpR3 Where to store the pointer to the APIC helpers.
2265 */
2266 DECLR3CALLBACKMEMBER(int, pfnAPICRegister,(PPDMDEVINS pDevIns, PPDMAPICREG pApicReg, PCPDMAPICHLPR3 *ppApicHlpR3));
2267
2268 /**
2269 * Register the I/O APIC device.
2270 *
2271 * @returns VBox status code.
2272 * @param pDevIns Device instance.
2273 * @param pIoApicReg Pointer to a I/O APIC registration structure.
2274 * @param ppIoApicHlpR3 Where to store the pointer to the IOAPIC helpers.
2275 */
2276 DECLR3CALLBACKMEMBER(int, pfnIOAPICRegister,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLPR3 *ppIoApicHlpR3));
2277
2278 /**
2279 * Register the DMA device.
2280 *
2281 * @returns VBox status code.
2282 * @param pDevIns Device instance.
2283 * @param pDmacReg Pointer to a DMAC registration structure.
2284 * @param ppDmacHlp Where to store the pointer to the DMA helpers.
2285 */
2286 DECLR3CALLBACKMEMBER(int, pfnDMACRegister,(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp));
2287
2288 /**
2289 * Read physical memory.
2290 *
2291 * @param pDevIns Device instance.
2292 * @param GCPhys Physical address start reading from.
2293 * @param pvBuf Where to put the read bits.
2294 * @param cbRead How many bytes to read.
2295 * @thread Any thread, but the call may involve the emulation thread.
2296 */
2297 DECLR3CALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
2298
2299 /**
2300 * Write to physical memory.
2301 *
2302 * @param pDevIns Device instance.
2303 * @param GCPhys Physical address to write to.
2304 * @param pvBuf What to write.
2305 * @param cbWrite How many bytes to write.
2306 * @thread Any thread, but the call may involve the emulation thread.
2307 */
2308 DECLR3CALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
2309
2310 /**
2311 * Read guest physical memory by virtual address.
2312 *
2313 * @param pDevIns Device instance.
2314 * @param pvDst Where to put the read bits.
2315 * @param GCVirtSrc Guest virtual address to start reading from.
2316 * @param cb How many bytes to read.
2317 * @thread The emulation thread.
2318 */
2319 DECLR3CALLBACKMEMBER(int, pfnPhysReadGCVirt,(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb));
2320
2321 /**
2322 * Write to guest physical memory by virtual address.
2323 *
2324 * @param pDevIns Device instance.
2325 * @param GCVirtDst Guest virtual address to write to.
2326 * @param pvSrc What to write.
2327 * @param cb How many bytes to write.
2328 * @thread The emulation thread.
2329 */
2330 DECLR3CALLBACKMEMBER(int, pfnPhysWriteGCVirt,(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb));
2331
2332 /**
2333 * Reserve physical address space for ROM and MMIO ranges.
2334 *
2335 * @returns VBox status code.
2336 * @param pDevIns Device instance.
2337 * @param GCPhys Start physical address.
2338 * @param cbRange The size of the range.
2339 * @param pszDesc Description string.
2340 * @thread The emulation thread.
2341 */
2342 DECLR3CALLBACKMEMBER(int, pfnPhysReserve,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const char *pszDesc));
2343
2344 /**
2345 * Convert a guest physical address to a host virtual address.
2346 *
2347 * @returns VBox status code.
2348 * @param pDevIns Device instance.
2349 * @param GCPhys Start physical address.
2350 * @param cbRange The size of the range. Use 0 if you don't care about the range.
2351 * @param ppvHC Where to store the HC pointer corresponding to GCPhys.
2352 * @thread The emulation thread.
2353 *
2354 * @remark Careful with page boundraries.
2355 * @remark Do not use the mapping after you return to the caller! (it could get invalidated/changed)
2356 */
2357 DECLR3CALLBACKMEMBER(int, pfnPhys2HCVirt,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, PRTHCPTR ppvHC));
2358
2359 /**
2360 * Convert a guest virtual address to a host virtual address.
2361 *
2362 * @returns VBox status code.
2363 * @param pDevIns Device instance.
2364 * @param GCPtr Guest virtual address.
2365 * @param pHCPtr Where to store the HC pointer corresponding to GCPtr.
2366 * @thread The emulation thread.
2367 *
2368 * @remark Careful with page boundraries.
2369 * @remark Do not use the mapping after you return to the caller! (it could get invalidated/changed)
2370 */
2371 DECLR3CALLBACKMEMBER(int, pfnPhysGCPtr2HCPtr,(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTHCPTR pHCPtr));
2372
2373 /**
2374 * Checks if the Gate A20 is enabled or not.
2375 *
2376 * @returns true if A20 is enabled.
2377 * @returns false if A20 is disabled.
2378 * @param pDevIns Device instance.
2379 * @thread The emulation thread.
2380 */
2381 DECLR3CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
2382
2383 /**
2384 * Enables or disables the Gate A20.
2385 *
2386 * @param pDevIns Device instance.
2387 * @param fEnable Set this flag to enable the Gate A20; clear it to disable.
2388 * @thread The emulation thread.
2389 */
2390 DECLR3CALLBACKMEMBER(void, pfnA20Set,(PPDMDEVINS pDevIns, bool fEnable));
2391
2392 /**
2393 * Resets the VM.
2394 *
2395 * @returns The appropriate VBox status code to pass around on reset.
2396 * @param pDevIns Device instance.
2397 * @thread The emulation thread.
2398 */
2399 DECLR3CALLBACKMEMBER(int, pfnVMReset,(PPDMDEVINS pDevIns));
2400
2401 /**
2402 * Suspends the VM.
2403 *
2404 * @returns The appropriate VBox status code to pass around on suspend.
2405 * @param pDevIns Device instance.
2406 * @thread The emulation thread.
2407 */
2408 DECLR3CALLBACKMEMBER(int, pfnVMSuspend,(PPDMDEVINS pDevIns));
2409
2410 /**
2411 * Power off the VM.
2412 *
2413 * @returns The appropriate VBox status code to pass around on power off.
2414 * @param pDevIns Device instance.
2415 * @thread The emulation thread.
2416 */
2417 DECLR3CALLBACKMEMBER(int, pfnVMPowerOff,(PPDMDEVINS pDevIns));
2418
2419 /**
2420 * Acquire global VM lock
2421 *
2422 * @returns VBox status code
2423 * @param pDevIns Device instance.
2424 */
2425 DECLR3CALLBACKMEMBER(int , pfnLockVM,(PPDMDEVINS pDevIns));
2426
2427 /**
2428 * Release global VM lock
2429 *
2430 * @returns VBox status code
2431 * @param pDevIns Device instance.
2432 */
2433 DECLR3CALLBACKMEMBER(int, pfnUnlockVM,(PPDMDEVINS pDevIns));
2434
2435 /**
2436 * Check that the current thread owns the global VM lock.
2437 *
2438 * @returns boolean
2439 * @param pDevIns Device instance.
2440 * @param pszFile Filename of the assertion location.
2441 * @param iLine Linenumber of the assertion location.
2442 * @param pszFunction Function of the assertion location.
2443 */
2444 DECLR3CALLBACKMEMBER(bool, pfnAssertVMLock,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction));
2445
2446 /**
2447 * Register transfer function for DMA channel.
2448 *
2449 * @returns VBox status code.
2450 * @param pDevIns Device instance.
2451 * @param uChannel Channel number.
2452 * @param pfnTransferHandler Device specific transfer callback function.
2453 * @param pvUser User pointer to pass to the callback.
2454 * @thread EMT
2455 */
2456 DECLR3CALLBACKMEMBER(int, pfnDMARegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
2457
2458 /**
2459 * Read memory.
2460 *
2461 * @returns VBox status code.
2462 * @param pDevIns Device instance.
2463 * @param uChannel Channel number.
2464 * @param pvBuffer Pointer to target buffer.
2465 * @param off DMA position.
2466 * @param cbBlock Block size.
2467 * @param pcbRead Where to store the number of bytes which was read. optional.
2468 * @thread EMT
2469 */
2470 DECLR3CALLBACKMEMBER(int, pfnDMAReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbRead));
2471
2472 /**
2473 * Write memory.
2474 *
2475 * @returns VBox status code.
2476 * @param pDevIns Device instance.
2477 * @param uChannel Channel number.
2478 * @param pvBuffer Memory to write.
2479 * @param off DMA position.
2480 * @param cbBlock Block size.
2481 * @param pcbWritten Where to store the number of bytes which was written. optional.
2482 * @thread EMT
2483 */
2484 DECLR3CALLBACKMEMBER(int, pfnDMAWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbWritten));
2485
2486 /**
2487 * Set the DREQ line.
2488 *
2489 * @returns VBox status code.
2490 * @param pDevIns Device instance.
2491 * @param uChannel Channel number.
2492 * @param uLevel Level of the line.
2493 * @thread EMT
2494 */
2495 DECLR3CALLBACKMEMBER(int, pfnDMASetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
2496
2497 /**
2498 * Get channel mode.
2499 *
2500 * @returns Channel mode. See specs.
2501 * @param pDevIns Device instance.
2502 * @param uChannel Channel number.
2503 * @thread EMT
2504 */
2505 DECLR3CALLBACKMEMBER(uint8_t, pfnDMAGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
2506
2507 /**
2508 * Schedule DMA execution.
2509 *
2510 * @param pDevIns Device instance.
2511 * @thread Any thread.
2512 */
2513 DECLR3CALLBACKMEMBER(void, pfnDMASchedule,(PPDMDEVINS pDevIns));
2514
2515 /**
2516 * Write CMOS value and update the checksum(s).
2517 *
2518 * @returns VBox status code.
2519 * @param pDevIns Device instance.
2520 * @param iReg The CMOS register index.
2521 * @param u8Value The CMOS register value.
2522 * @thread EMT
2523 */
2524 DECLR3CALLBACKMEMBER(int, pfnCMOSWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
2525
2526 /**
2527 * Read CMOS value.
2528 *
2529 * @returns VBox status code.
2530 * @param pDevIns Device instance.
2531 * @param iReg The CMOS register index.
2532 * @param pu8Value Where to store the CMOS register value.
2533 * @thread EMT
2534 */
2535 DECLR3CALLBACKMEMBER(int, pfnCMOSRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
2536
2537 /**
2538 * Query CPUID.
2539 *
2540 * @param pDevIns Device instance.
2541 * @param iLeaf The CPUID leaf to get.
2542 * @param pEax Where to store the EAX value.
2543 * @param pEbx Where to store the EBX value.
2544 * @param pEcx Where to store the ECX value.
2545 * @param pEdx Where to store the EDX value.
2546 */
2547 DECLR3CALLBACKMEMBER(void, pfnGetCpuId,(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t *pEax, uint32_t *pEbx, uint32_t *pEcx, uint32_t *pEdx));
2548
2549 /**
2550 * Write protects a shadow ROM mapping.
2551 *
2552 * This is intented for use by the system BIOS or by the device that
2553 * employs a shadow ROM BIOS, so that the shadow ROM mapping can be
2554 * write protected once the POST is over.
2555 *
2556 * @param pDevIns Device instance.
2557 * @param GCPhysStart Where the shadow ROM mapping starts.
2558 * @param cbRange The size of the shadow ROM mapping.
2559 */
2560 DECLR3CALLBACKMEMBER(int, pfnROMProtectShadow,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange));
2561
2562 /** @} */
2563
2564 /** Just a safety precaution. (PDM_DEVHLP_VERSION) */
2565 uint32_t u32TheEnd;
2566} PDMDEVHLP;
2567#endif /* !IN_RING3 */
2568/** Pointer PDM Device API. */
2569typedef HCPTRTYPE(struct PDMDEVHLP *) PPDMDEVHLP;
2570/** Pointer PDM Device API. */
2571typedef HCPTRTYPE(const struct PDMDEVHLP *) PCPDMDEVHLP;
2572
2573/** Current PDMDEVHLP version number. */
2574#define PDM_DEVHLP_VERSION 0xf2050000
2575
2576
2577/**
2578 * PDM Device API - GC Variant.
2579 */
2580typedef struct PDMDEVHLPGC
2581{
2582 /** Structure version. PDM_DEVHLPGC_VERSION defines the current version. */
2583 uint32_t u32Version;
2584
2585 /**
2586 * Set the IRQ for a PCI device.
2587 *
2588 * @param pDevIns Device instance.
2589 * @param iIrq IRQ number to set.
2590 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
2591 * @thread Any thread, but will involve the emulation thread.
2592 */
2593 DECLGCCALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
2594
2595 /**
2596 * Set ISA IRQ for a device.
2597 *
2598 * @param pDevIns Device instance.
2599 * @param iIrq IRQ number to set.
2600 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
2601 * @thread Any thread, but will involve the emulation thread.
2602 */
2603 DECLGCCALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
2604
2605 /**
2606 * Read physical memory.
2607 *
2608 * @param pDevIns Device instance.
2609 * @param GCPhys Physical address start reading from.
2610 * @param pvBuf Where to put the read bits.
2611 * @param cbRead How many bytes to read.
2612 */
2613 DECLGCCALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
2614
2615 /**
2616 * Write to physical memory.
2617 *
2618 * @param pDevIns Device instance.
2619 * @param GCPhys Physical address to write to.
2620 * @param pvBuf What to write.
2621 * @param cbWrite How many bytes to write.
2622 */
2623 DECLGCCALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
2624
2625 /**
2626 * Checks if the Gate A20 is enabled or not.
2627 *
2628 * @returns true if A20 is enabled.
2629 * @returns false if A20 is disabled.
2630 * @param pDevIns Device instance.
2631 * @thread The emulation thread.
2632 */
2633 DECLGCCALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
2634
2635 /**
2636 * Set the VM error message
2637 *
2638 * @returns rc.
2639 * @param pDrvIns Driver instance.
2640 * @param rc VBox status code.
2641 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
2642 * @param pszFormat Error message format string.
2643 * @param ... Error message arguments.
2644 */
2645 DECLGCCALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
2646
2647 /**
2648 * Set the VM error message
2649 *
2650 * @returns rc.
2651 * @param pDrvIns Driver instance.
2652 * @param rc VBox status code.
2653 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
2654 * @param pszFormat Error message format string.
2655 * @param va Error message arguments.
2656 */
2657 DECLGCCALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
2658
2659 /**
2660 * Set the VM runtime error message
2661 *
2662 * @returns VBox status code.
2663 * @param pDevIns Device instance.
2664 * @param fFatal Whether it is a fatal error or not.
2665 * @param pszErrorID Error ID string.
2666 * @param pszFormat Error message format string.
2667 * @param ... Error message arguments.
2668 */
2669 DECLGCCALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));
2670
2671 /**
2672 * Set the VM runtime error message
2673 *
2674 * @returns VBox status code.
2675 * @param pDevIns Device instance.
2676 * @param fFatal Whether it is a fatal error or not.
2677 * @param pszErrorID Error ID string.
2678 * @param pszFormat Error message format string.
2679 * @param va Error message arguments.
2680 */
2681 DECLGCCALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));
2682
2683 /**
2684 * Set parameters for pending MMIO patch operation
2685 *
2686 * @returns VBox status code.
2687 * @param pDevIns Device instance.
2688 * @param GCPhys MMIO physical address
2689 * @param pCachedData GC pointer to cached data
2690 */
2691 DECLGCCALLBACKMEMBER(int, pfnPATMSetMMIOPatchInfo,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPTR pCachedData));
2692
2693 /** Just a safety precaution. */
2694 uint32_t u32TheEnd;
2695} PDMDEVHLPGC;
2696/** Pointer PDM Device GC API. */
2697typedef GCPTRTYPE(struct PDMDEVHLPGC *) PPDMDEVHLPGC;
2698/** Pointer PDM Device GC API. */
2699typedef GCPTRTYPE(const struct PDMDEVHLPGC *) PCPDMDEVHLPGC;
2700
2701/** Current PDMDEVHLP version number. */
2702#define PDM_DEVHLPGC_VERSION 0xfb010000
2703
2704
2705/**
2706 * PDM Device API - R0 Variant.
2707 */
2708typedef struct PDMDEVHLPR0
2709{
2710 /** Structure version. PDM_DEVHLPR0_VERSION defines the current version. */
2711 uint32_t u32Version;
2712
2713 /**
2714 * Set the IRQ for a PCI device.
2715 *
2716 * @param pDevIns Device instance.
2717 * @param iIrq IRQ number to set.
2718 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
2719 * @thread Any thread, but will involve the emulation thread.
2720 */
2721 DECLR0CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
2722
2723 /**
2724 * Set ISA IRQ for a device.
2725 *
2726 * @param pDevIns Device instance.
2727 * @param iIrq IRQ number to set.
2728 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
2729 * @thread Any thread, but will involve the emulation thread.
2730 */
2731 DECLR0CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
2732
2733 /**
2734 * Read physical memory.
2735 *
2736 * @param pDevIns Device instance.
2737 * @param GCPhys Physical address start reading from.
2738 * @param pvBuf Where to put the read bits.
2739 * @param cbRead How many bytes to read.
2740 */
2741 DECLR0CALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
2742
2743 /**
2744 * Write to physical memory.
2745 *
2746 * @param pDevIns Device instance.
2747 * @param GCPhys Physical address to write to.
2748 * @param pvBuf What to write.
2749 * @param cbWrite How many bytes to write.
2750 */
2751 DECLR0CALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
2752
2753 /**
2754 * Checks if the Gate A20 is enabled or not.
2755 *
2756 * @returns true if A20 is enabled.
2757 * @returns false if A20 is disabled.
2758 * @param pDevIns Device instance.
2759 * @thread The emulation thread.
2760 */
2761 DECLR0CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
2762
2763 /**
2764 * Set the VM error message
2765 *
2766 * @returns rc.
2767 * @param pDrvIns Driver instance.
2768 * @param rc VBox status code.
2769 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
2770 * @param pszFormat Error message format string.
2771 * @param ... Error message arguments.
2772 */
2773 DECLR0CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
2774
2775 /**
2776 * Set the VM error message
2777 *
2778 * @returns rc.
2779 * @param pDrvIns Driver instance.
2780 * @param rc VBox status code.
2781 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
2782 * @param pszFormat Error message format string.
2783 * @param va Error message arguments.
2784 */
2785 DECLR0CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
2786
2787 /**
2788 * Set the VM runtime error message
2789 *
2790 * @returns VBox status code.
2791 * @param pDevIns Device instance.
2792 * @param fFatal Whether it is a fatal error or not.
2793 * @param pszErrorID Error ID string.
2794 * @param pszFormat Error message format string.
2795 * @param ... Error message arguments.
2796 */
2797 DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...));
2798
2799 /**
2800 * Set the VM runtime error message
2801 *
2802 * @returns VBox status code.
2803 * @param pDevIns Device instance.
2804 * @param fFatal Whether it is a fatal error or not.
2805 * @param pszErrorID Error ID string.
2806 * @param pszFormat Error message format string.
2807 * @param va Error message arguments.
2808 */
2809 DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, va_list va));
2810
2811 /**
2812 * Set parameters for pending MMIO patch operation
2813 *
2814 * @returns rc.
2815 * @param pDevIns Device instance.
2816 * @param GCPhys MMIO physical address
2817 * @param pCachedData GC pointer to cached data
2818 */
2819 DECLR0CALLBACKMEMBER(int, pfnPATMSetMMIOPatchInfo,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPTR pCachedData));
2820
2821 /** Just a safety precaution. */
2822 uint32_t u32TheEnd;
2823} PDMDEVHLPR0;
2824/** Pointer PDM Device R0 API. */
2825typedef HCPTRTYPE(struct PDMDEVHLPR0 *) PPDMDEVHLPR0;
2826/** Pointer PDM Device GC API. */
2827typedef HCPTRTYPE(const struct PDMDEVHLPR0 *) PCPDMDEVHLPR0;
2828
2829/** Current PDMDEVHLP version number. */
2830#define PDM_DEVHLPR0_VERSION 0xfb010000
2831
2832
2833
2834/**
2835 * PDM Device Instance.
2836 */
2837typedef struct PDMDEVINS
2838{
2839 /** Structure version. PDM_DEVINS_VERSION defines the current version. */
2840 uint32_t u32Version;
2841 /** Device instance number. */
2842 RTUINT iInstance;
2843 /** The base interface of the device.
2844 * The device constructor initializes this if it has any
2845 * device level interfaces to export. To obtain this interface
2846 * call PDMR3QueryDevice(). */
2847 PDMIBASE IBase;
2848
2849 /** Internal data. */
2850 union
2851 {
2852#ifdef PDMDEVINSINT_DECLARED
2853 PDMDEVINSINT s;
2854#endif
2855 uint8_t padding[HC_ARCH_BITS == 32 ? 48 : 96];
2856 } Internal;
2857
2858 /** Pointer the HC PDM Device API. */
2859 R3PTRTYPE(PCPDMDEVHLP) pDevHlp;
2860 /** Pointer the R0 PDM Device API. */
2861 R0PTRTYPE(PCPDMDEVHLPR0) pDevHlpR0;
2862 /** Pointer to device registration structure. */
2863 R3PTRTYPE(PCPDMDEVREG) pDevReg;
2864 /** Configuration handle. */
2865 R3PTRTYPE(PCFGMNODE) pCfgHandle;
2866 /** Pointer to device instance data. */
2867 R3PTRTYPE(void *) pvInstanceDataR3;
2868 /** Pointer to device instance data. */
2869 R0PTRTYPE(void *) pvInstanceDataR0;
2870 /** Pointer the GC PDM Device API. */
2871 GCPTRTYPE(PCPDMDEVHLPGC) pDevHlpGC;
2872 /** Pointer to device instance data. */
2873 GCPTRTYPE(void *) pvInstanceDataGC;
2874 /* padding to make achInstanceData aligned at 32 byte boundrary. */
2875 uint32_t au32Padding[HC_ARCH_BITS == 32 ? 1 : 6];
2876 /** Device instance data. The size of this area is defined
2877 * in the PDMDEVREG::cbInstanceData field. */
2878 char achInstanceData[8];
2879} PDMDEVINS;
2880
2881/** Current DEVREG version number. */
2882#define PDM_DEVINS_VERSION 0xf3010000
2883
2884/** Converts a pointer to the PDMDEVINS::IBase to a pointer to PDMDEVINS. */
2885#define PDMIBASE_2_PDMDEV(pInterface) ( (PPDMDEVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDEVINS, IBase)) )
2886
2887
2888/** @def PDMDEV_ASSERT_EMT
2889 * Assert that the current thread is the emulation thread.
2890 */
2891#ifdef VBOX_STRICT
2892# define PDMDEV_ASSERT_EMT(pDevIns) pDevIns->pDevHlp->pfnAssertEMT(pDevIns, __FILE__, __LINE__, __FUNCTION__)
2893#else
2894# define PDMDEV_ASSERT_EMT(pDevIns) do { } while (0)
2895#endif
2896
2897/** @def PDMDEV_ASSERT_OTHER
2898 * Assert that the current thread is NOT the emulation thread.
2899 */
2900#ifdef VBOX_STRICT
2901# define PDMDEV_ASSERT_OTHER(pDevIns) pDevIns->pDevHlp->pfnAssertOther(pDevIns, __FILE__, __LINE__, __FUNCTION__)
2902#else
2903# define PDMDEV_ASSERT_OTHER(pDevIns) do { } while (0)
2904#endif
2905
2906/** @def PDMDEV_ASSERT_VMLOCK_OWNER
2907 * Assert that the current thread is owner of the VM lock.
2908 */
2909#ifdef VBOX_STRICT
2910# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) pDevIns->pDevHlp->pfnAssertVMLock(pDevIns, __FILE__, __LINE__, __FUNCTION__)
2911#else
2912# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) do { } while (0)
2913#endif
2914
2915/** @def PDMDEV_SET_ERROR
2916 * Set the VM error. See PDMDevHlpVMSetError() for printf like message formatting.
2917 */
2918#define PDMDEV_SET_ERROR(pDevIns, rc, pszError) \
2919 PDMDevHlpVMSetError(pDevIns, rc, RT_SRC_POS, "%s", pszError)
2920
2921/** @def PDMDEV_SET_RUNTIME_ERROR
2922 * Set the VM runtime error. See PDMDevHlpVMSetRuntimeError() for printf like message formatting.
2923 */
2924#define PDMDEV_SET_RUNTIME_ERROR(pDevIns, fFatal, pszErrorID, pszError) \
2925 PDMDevHlpVMSetRuntimeError(pDevIns, fFatal, pszErrorID, "%s", pszError)
2926
2927/** @def PDMDEVINS_2_GCPTR
2928 * Converts a PDM Device instance pointer a GC PDM Device instance pointer.
2929 */
2930#define PDMDEVINS_2_GCPTR(pDevIns) ( (GCPTRTYPE(PPDMDEVINS))((RTGCUINTPTR)(pDevIns)->pvInstanceDataGC - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )
2931
2932/** @def PDMDEVINS_2_R3PTR
2933 * Converts a PDM Device instance pointer a HC PDM Device instance pointer.
2934 */
2935#define PDMDEVINS_2_R3PTR(pDevIns) ( (HCPTRTYPE(PPDMDEVINS))((RTHCUINTPTR)(pDevIns)->pvInstanceDataR3 - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )
2936
2937/** @def PDMDEVINS_2_R0PTR
2938 * Converts a PDM Device instance pointer a R0 PDM Device instance pointer.
2939 */
2940#define PDMDEVINS_2_R0PTR(pDevIns) ( (R0PTRTYPE(PPDMDEVINS))((RTR0UINTPTR)(pDevIns)->pvInstanceDataR0 - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )
2941
2942
2943/**
2944 * VBOX_STRICT wrapper for pDevHlp->pfnDBGFStopV.
2945 *
2946 * @returns VBox status code which must be passed up to the VMM.
2947 * @param pDevIns Device instance.
2948 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
2949 * @param pszFormat Message. (optional)
2950 * @param ... Message parameters.
2951 */
2952DECLINLINE(int) PDMDeviceDBGFStop(PPDMDEVINS pDevIns, RT_SRC_POS_DECL, const char *pszFormat, ...)
2953{
2954#ifdef VBOX_STRICT
2955# ifdef IN_RING3
2956 int rc;
2957 va_list args;
2958 va_start(args, pszFormat);
2959 rc = pDevIns->pDevHlp->pfnDBGFStopV(pDevIns, RT_SRC_POS_ARGS, pszFormat, args);
2960 va_end(args);
2961 return rc;
2962# else
2963 return VINF_EM_DBG_STOP;
2964# endif
2965#else
2966 return VINF_SUCCESS;
2967#endif
2968}
2969
2970
2971#ifdef IN_RING3
2972/**
2973 * @copydoc PDMDEVHLP::pfnIOPortRegister
2974 */
2975DECLINLINE(int) PDMDevHlpIOPortRegister(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTHCPTR pvUser,
2976 PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,
2977 PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc)
2978{
2979 return pDevIns->pDevHlp->pfnIOPortRegister(pDevIns, Port, cPorts, pvUser, pfnOut, pfnIn, pfnOutStr, pfnInStr, pszDesc);
2980}
2981
2982/**
2983 * @copydoc PDMDEVHLP::pfnIOPortRegisterGC
2984 */
2985DECLINLINE(int) PDMDevHlpIOPortRegisterGC(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTGCPTR pvUser,
2986 const char *pszOut, const char *pszIn, const char *pszOutStr,
2987 const char *pszInStr, const char *pszDesc)
2988{
2989 return pDevIns->pDevHlp->pfnIOPortRegisterGC(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);
2990}
2991
2992/**
2993 * @copydoc PDMDEVHLP::pfnIOPortRegisterR0
2994 */
2995DECLINLINE(int) PDMDevHlpIOPortRegisterR0(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTR0PTR pvUser,
2996 const char *pszOut, const char *pszIn, const char *pszOutStr,
2997 const char *pszInStr, const char *pszDesc)
2998{
2999 return pDevIns->pDevHlp->pfnIOPortRegisterR0(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);
3000}
3001
3002/**
3003 * @copydoc PDMDEVHLP::pfnMMIORegister
3004 */
3005DECLINLINE(int) PDMDevHlpMMIORegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTHCPTR pvUser,
3006 PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, PFNIOMMMIOFILL pfnFill,
3007 const char *pszDesc)
3008{
3009 return pDevIns->pDevHlp->pfnMMIORegister(pDevIns, GCPhysStart, cbRange, pvUser, pfnWrite, pfnRead, pfnFill, pszDesc);
3010}
3011
3012/**
3013 * @copydoc PDMDEVHLP::pfnMMIORegisterGC
3014 */
3015DECLINLINE(int) PDMDevHlpMMIORegisterGC(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTGCPTR pvUser,
3016 const char *pszWrite, const char *pszRead, const char *pszFill, const char *pszDesc)
3017{
3018 return pDevIns->pDevHlp->pfnMMIORegisterGC(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill, pszDesc);
3019}
3020
3021/**
3022 * @copydoc PDMDEVHLP::pfnMMIORegisterR0
3023 */
3024DECLINLINE(int) PDMDevHlpMMIORegisterR0(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTR0PTR pvUser,
3025 const char *pszWrite, const char *pszRead, const char *pszFill, const char *pszDesc)
3026{
3027 return pDevIns->pDevHlp->pfnMMIORegisterR0(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill, pszDesc);
3028}
3029
3030/**
3031 * @copydoc PDMDEVHLP::pfnROMRegister
3032 */
3033DECLINLINE(int) PDMDevHlpROMRegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, const void *pvBinary, bool fShadow, const char *pszDesc)
3034{
3035 return pDevIns->pDevHlp->pfnROMRegister(pDevIns, GCPhysStart, cbRange, pvBinary, fShadow, pszDesc);
3036}
3037
3038/**
3039 * @copydoc PDMDEVHLP::pfnROMProtectShadow
3040 */
3041DECLINLINE(int) PDMDevHlpROMProtectShadow(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange)
3042{
3043 return pDevIns->pDevHlp->pfnROMProtectShadow(pDevIns, GCPhysStart, cbRange);
3044}
3045
3046/**
3047 * @copydoc PDMDEVHLP::pfnSSMRegister
3048 */
3049DECLINLINE(int) PDMDevHlpSSMRegister(PPDMDEVINS pDevIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
3050 PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
3051 PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone)
3052{
3053 return pDevIns->pDevHlp->pfnSSMRegister(pDevIns, pszName, u32Instance, u32Version, cbGuess,
3054 pfnSavePrep, pfnSaveExec, pfnSaveDone,
3055 pfnLoadPrep, pfnLoadExec, pfnLoadDone);
3056}
3057
3058/**
3059 * @copydoc PDMDEVHLP::pfnTMTimerCreate
3060 */
3061DECLINLINE(int) PDMDevHlpTMTimerCreate(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer)
3062{
3063 return pDevIns->pDevHlp->pfnTMTimerCreate(pDevIns, enmClock, pfnCallback, pszDesc, ppTimer);
3064}
3065
3066/**
3067 * @copydoc PDMDEVHLP::pfnPCIRegister
3068 */
3069DECLINLINE(int) PDMDevHlpPCIRegister(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev)
3070{
3071 return pDevIns->pDevHlp->pfnPCIRegister(pDevIns, pPciDev);
3072}
3073
3074/**
3075 * @copydoc PDMDEVHLP::pfnPCIIORegionRegister
3076 */
3077DECLINLINE(int) PDMDevHlpPCIIORegionRegister(PPDMDEVINS pDevIns, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback)
3078{
3079 return pDevIns->pDevHlp->pfnPCIIORegionRegister(pDevIns, iRegion, cbRegion, enmType, pfnCallback);
3080}
3081
3082/**
3083 * @copydoc PDMDEVHLP::pfnPCISetConfigCallbacks
3084 */
3085DECLINLINE(void) PDMDevHlpPCISetConfigCallbacks(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,
3086 PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld)
3087{
3088 pDevIns->pDevHlp->pfnPCISetConfigCallbacks(pDevIns, pPciDev, pfnRead, ppfnReadOld, pfnWrite, ppfnWriteOld);
3089}
3090
3091/**
3092 * @copydoc PDMDEVHLP::pfnDriverAttach
3093 */
3094DECLINLINE(int) PDMDevHlpDriverAttach(PPDMDEVINS pDevIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE *ppBaseInterface, const char *pszDesc)
3095{
3096 return pDevIns->pDevHlp->pfnDriverAttach(pDevIns, iLun, pBaseInterface, ppBaseInterface, pszDesc);
3097}
3098
3099/**
3100 * @copydoc PDMDEVHLP::pfnMMHeapAlloc
3101 */
3102DECLINLINE(void *) PDMDevHlpMMHeapAlloc(PPDMDEVINS pDevIns, size_t cb)
3103{
3104 return pDevIns->pDevHlp->pfnMMHeapAlloc(pDevIns, cb);
3105}
3106
3107/**
3108 * @copydoc PDMDEVHLP::pfnMMHeapAllocZ
3109 */
3110DECLINLINE(void *) PDMDevHlpMMHeapAllocZ(PPDMDEVINS pDevIns, size_t cb)
3111{
3112 return pDevIns->pDevHlp->pfnMMHeapAllocZ(pDevIns, cb);
3113}
3114
3115/**
3116 * @copydoc PDMDEVHLP::pfnMMHeapFree
3117 */
3118DECLINLINE(void) PDMDevHlpMMHeapFree(PPDMDEVINS pDevIns, void *pv)
3119{
3120 pDevIns->pDevHlp->pfnMMHeapFree(pDevIns, pv);
3121}
3122
3123/**
3124 * @copydoc PDMDEVHLP::pfnDBGFInfoRegister
3125 */
3126DECLINLINE(int) PDMDevHlpDBGFInfoRegister(PPDMDEVINS pDevIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDEV pfnHandler)
3127{
3128 return pDevIns->pDevHlp->pfnDBGFInfoRegister(pDevIns, pszName, pszDesc, pfnHandler);
3129}
3130
3131/**
3132 * @copydoc PDMDEVHLP::pfnSTAMRegister
3133 */
3134DECLINLINE(void) PDMDevHlpSTAMRegister(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
3135{
3136 pDevIns->pDevHlp->pfnSTAMRegister(pDevIns, pvSample, enmType, pszName, enmUnit, pszDesc);
3137}
3138
3139/**
3140 * @copydoc PDMDEVHLP::pfnSTAMRegisterF
3141 */
3142DECLINLINE(void) PDMDevHlpSTAMRegisterF(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
3143 const char *pszDesc, const char *pszName, ...)
3144{
3145 va_list va;
3146 va_start(va, pszName);
3147 pDevIns->pDevHlp->pfnSTAMRegisterV(pDevIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
3148 va_end(va);
3149}
3150
3151/**
3152 * @copydoc PDMDEVHLP::pfnPDMQueueCreate
3153 */
3154DECLINLINE(int) PDMDevHlpPDMQueueCreate(PPDMDEVINS pDevIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
3155 PFNPDMQUEUEDEV pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue)
3156{
3157 return pDevIns->pDevHlp->pfnPDMQueueCreate(pDevIns, cbItem, cItems, cMilliesInterval, pfnCallback, fGCEnabled, ppQueue);
3158}
3159
3160/**
3161 * @copydoc PDMDEVHLP::pfnCritSectInit
3162 */
3163DECLINLINE(int) PDMDevHlpCritSectInit(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, const char *pszName)
3164{
3165 return pDevIns->pDevHlp->pfnCritSectInit(pDevIns, pCritSect, pszName);
3166}
3167
3168/**
3169 * @copydoc PDMDEVHLP::pfnUTCNow
3170 */
3171DECLINLINE(PRTTIMESPEC) PDMDevHlpUTCNow(PPDMDEVINS pDevIns, PRTTIMESPEC pTime)
3172{
3173 return pDevIns->pDevHlp->pfnUTCNow(pDevIns, pTime);
3174}
3175
3176/**
3177 * @copydoc PDMDEVHLP::pfnGetVM
3178 */
3179DECLINLINE(PVM) PDMDevHlpGetVM(PPDMDEVINS pDevIns)
3180{
3181 return pDevIns->pDevHlp->pfnGetVM(pDevIns);
3182}
3183
3184/**
3185 * @copydoc PDMDEVHLP::pfnPhysReadGCVirt
3186 */
3187DECLINLINE(int) PDMDevHlpPhysReadGCVirt(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb)
3188{
3189 return pDevIns->pDevHlp->pfnPhysReadGCVirt(pDevIns, pvDst, GCVirtSrc, cb);
3190}
3191
3192/**
3193 * @copydoc PDMDEVHLP::pfnPhysWriteGCVirt
3194 */
3195DECLINLINE(int) PDMDevHlpPhysWriteGCVirt(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb)
3196{
3197 return pDevIns->pDevHlp->pfnPhysWriteGCVirt(pDevIns, GCVirtDst, pvSrc, cb);
3198}
3199
3200/**
3201 * @copydoc PDMDEVHLP::pfnPhysReserve
3202 */
3203DECLINLINE(int) PDMDevHlpPhysReserve(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const char *pszDesc)
3204{
3205 return pDevIns->pDevHlp->pfnPhysReserve(pDevIns, GCPhys, cbRange, pszDesc);
3206}
3207
3208/**
3209 * @copydoc PDMDEVHLP::pfnPhys2HCVirt
3210 */
3211DECLINLINE(int) PDMDevHlpPhys2HCVirt(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, PRTHCPTR ppvHC)
3212{
3213 return pDevIns->pDevHlp->pfnPhys2HCVirt(pDevIns, GCPhys, cbRange, ppvHC);
3214}
3215
3216/**
3217 * @copydoc PDMDEVHLP::pfnPhysGCPtr2HCPtr
3218 */
3219DECLINLINE(int) PDMDevHlpPhysGCPtr2HCPtr(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTHCPTR pHCPtr)
3220{
3221 return pDevIns->pDevHlp->pfnPhysGCPtr2HCPtr(pDevIns, GCPtr, pHCPtr);
3222}
3223
3224/**
3225 * @copydoc PDMDEVHLP::pfnPhysGCPtr2GCPhys
3226 */
3227DECLINLINE(int) PDMDevHlpPhysGCPtr2GCPhys(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTGCPHYS pGCPhys)
3228{
3229 return pDevIns->pDevHlp->pfnPhysGCPtr2GCPhys(pDevIns, GCPtr, pGCPhys);
3230}
3231
3232/**
3233 * @copydoc PDMDEVHLP::pfnA20Set
3234 */
3235DECLINLINE(void) PDMDevHlpA20Set(PPDMDEVINS pDevIns, bool fEnable)
3236{
3237 pDevIns->pDevHlp->pfnA20Set(pDevIns, fEnable);
3238}
3239
3240/**
3241 * @copydoc PDMDEVHLP::pfnVMReset
3242 */
3243DECLINLINE(int) PDMDevHlpVMReset(PPDMDEVINS pDevIns)
3244{
3245 return pDevIns->pDevHlp->pfnVMReset(pDevIns);
3246}
3247
3248/**
3249 * @copydoc PDMDEVHLP::pfnVMSuspend
3250 */
3251DECLINLINE(int) PDMDevHlpVMSuspend(PPDMDEVINS pDevIns)
3252{
3253 return pDevIns->pDevHlp->pfnVMSuspend(pDevIns);
3254}
3255
3256/**
3257 * @copydoc PDMDEVHLP::pfnVMPowerOff
3258 */
3259DECLINLINE(int) PDMDevHlpVMPowerOff(PPDMDEVINS pDevIns)
3260{
3261 return pDevIns->pDevHlp->pfnVMPowerOff(pDevIns);
3262}
3263
3264/**
3265 * @copydoc PDMDEVHLP::pfnDMARegister
3266 */
3267DECLINLINE(int) PDMDevHlpDMARegister(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser)
3268{
3269 return pDevIns->pDevHlp->pfnDMARegister(pDevIns, uChannel, pfnTransferHandler, pvUser);
3270}
3271
3272/**
3273 * @copydoc PDMDEVHLP::pfnDMAReadMemory
3274 */
3275DECLINLINE(int) PDMDevHlpDMAReadMemory(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbRead)
3276{
3277 return pDevIns->pDevHlp->pfnDMAReadMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbRead);
3278}
3279
3280/**
3281 * @copydoc PDMDEVHLP::pfnDMAWriteMemory
3282 */
3283DECLINLINE(int) PDMDevHlpDMAWriteMemory(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbWritten)
3284{
3285 return pDevIns->pDevHlp->pfnDMAWriteMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbWritten);
3286}
3287
3288/**
3289 * @copydoc PDMDEVHLP::pfnDMASetDREQ
3290 */
3291DECLINLINE(int) PDMDevHlpDMASetDREQ(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel)
3292{
3293 return pDevIns->pDevHlp->pfnDMASetDREQ(pDevIns, uChannel, uLevel);
3294}
3295
3296/**
3297 * @copydoc PDMDEVHLP::pfnDMAGetChannelMode
3298 */
3299DECLINLINE(uint8_t) PDMDevHlpDMAGetChannelMode(PPDMDEVINS pDevIns, unsigned uChannel)
3300{
3301 return pDevIns->pDevHlp->pfnDMAGetChannelMode(pDevIns, uChannel);
3302}
3303
3304/**
3305 * @copydoc PDMDEVHLP::pfnDMASchedule
3306 */
3307DECLINLINE(void) PDMDevHlpDMASchedule(PPDMDEVINS pDevIns)
3308{
3309 pDevIns->pDevHlp->pfnDMASchedule(pDevIns);
3310}
3311
3312/**
3313 * @copydoc PDMDEVHLP::pfnCMOSWrite
3314 */
3315DECLINLINE(int) PDMDevHlpCMOSWrite(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value)
3316{
3317 return pDevIns->pDevHlp->pfnCMOSWrite(pDevIns, iReg, u8Value);
3318}
3319
3320/**
3321 * @copydoc PDMDEVHLP::pfnCMOSRead
3322 */
3323DECLINLINE(int) PDMDevHlpCMOSRead(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value)
3324{
3325 return pDevIns->pDevHlp->pfnCMOSRead(pDevIns, iReg, pu8Value);
3326}
3327
3328/**
3329 * @copydoc PDMDEVHLP::pfnGetCpuId
3330 */
3331DECLINLINE(void) PDMDevHlpGetCpuId(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t *pEax, uint32_t *pEbx, uint32_t *pEcx, uint32_t *pEdx)
3332{
3333 pDevIns->pDevHlp->pfnGetCpuId(pDevIns, iLeaf, pEax, pEbx, pEcx, pEdx);
3334}
3335
3336/**
3337 * @copydoc PDMDEVHLP::pfnPDMThreadCreate
3338 */
3339DECLINLINE(int) PDMDevHlpPDMThreadCreate(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
3340 PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
3341{
3342 return pDevIns->pDevHlp->pfnPDMThreadCreate(pDevIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
3343}
3344#endif /* IN_RING3 */
3345
3346
3347/**
3348 * @copydoc PDMDEVHLP::pfnPCISetIrq
3349 */
3350DECLINLINE(void) PDMDevHlpPCISetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
3351{
3352#ifdef IN_GC
3353 pDevIns->pDevHlpGC->pfnPCISetIrq(pDevIns, iIrq, iLevel);
3354#elif defined(IN_RING0)
3355 pDevIns->pDevHlpR0->pfnPCISetIrq(pDevIns, iIrq, iLevel);
3356#else
3357 pDevIns->pDevHlp->pfnPCISetIrq(pDevIns, iIrq, iLevel);
3358#endif
3359}
3360
3361/**
3362 * @copydoc PDMDEVHLP::pfnPCISetIrqNoWait
3363 */
3364DECLINLINE(void) PDMDevHlpPCISetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
3365{
3366#ifdef IN_GC
3367 pDevIns->pDevHlpGC->pfnPCISetIrq(pDevIns, iIrq, iLevel);
3368#elif defined(IN_RING0)
3369 pDevIns->pDevHlpR0->pfnPCISetIrq(pDevIns, iIrq, iLevel);
3370#else
3371 pDevIns->pDevHlp->pfnPCISetIrqNoWait(pDevIns, iIrq, iLevel);
3372#endif
3373}
3374
3375/**
3376 * @copydoc PDMDEVHLP::pfnISASetIrq
3377 */
3378DECLINLINE(void) PDMDevHlpISASetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
3379{
3380#ifdef IN_GC
3381 pDevIns->pDevHlpGC->pfnISASetIrq(pDevIns, iIrq, iLevel);
3382#elif defined(IN_RING0)
3383 pDevIns->pDevHlpR0->pfnISASetIrq(pDevIns, iIrq, iLevel);
3384#else
3385 pDevIns->pDevHlp->pfnISASetIrq(pDevIns, iIrq, iLevel);
3386#endif
3387}
3388
3389/**
3390 * @copydoc PDMDEVHLP::pfnISASetIrqNoWait
3391 */
3392DECLINLINE(void) PDMDevHlpISASetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
3393{
3394#ifdef IN_GC
3395 pDevIns->pDevHlpGC->pfnISASetIrq(pDevIns, iIrq, iLevel);
3396#elif defined(IN_RING0)
3397 pDevIns->pDevHlpR0->pfnISASetIrq(pDevIns, iIrq, iLevel);
3398#else
3399 pDevIns->pDevHlp->pfnISASetIrqNoWait(pDevIns, iIrq, iLevel);
3400#endif
3401}
3402
3403/**
3404 * @copydoc PDMDEVHLP::pfnPhysRead
3405 */
3406DECLINLINE(void) PDMDevHlpPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
3407{
3408#ifdef IN_GC
3409 pDevIns->pDevHlpGC->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
3410#elif defined(IN_RING0)
3411 pDevIns->pDevHlpR0->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
3412#else
3413 pDevIns->pDevHlp->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
3414#endif
3415}
3416
3417/**
3418 * @copydoc PDMDEVHLP::pfnPhysWrite
3419 */
3420DECLINLINE(void) PDMDevHlpPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
3421{
3422#ifdef IN_GC
3423 pDevIns->pDevHlpGC->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
3424#elif defined(IN_RING0)
3425 pDevIns->pDevHlpR0->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
3426#else
3427 pDevIns->pDevHlp->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
3428#endif
3429}
3430
3431/**
3432 * @copydoc PDMDEVHLP::pfnA20IsEnabled
3433 */
3434DECLINLINE(bool) PDMDevHlpA20IsEnabled(PPDMDEVINS pDevIns)
3435{
3436#ifdef IN_GC
3437 return pDevIns->pDevHlpGC->pfnA20IsEnabled(pDevIns);
3438#elif defined(IN_RING0)
3439 return pDevIns->pDevHlpR0->pfnA20IsEnabled(pDevIns);
3440#else
3441 return pDevIns->pDevHlp->pfnA20IsEnabled(pDevIns);
3442#endif
3443}
3444
3445/**
3446 * @copydoc PDMDEVHLP::pfnVMSetError
3447 */
3448DECLINLINE(int) PDMDevHlpVMSetError(PPDMDEVINS pDevIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
3449{
3450 va_list va;
3451 va_start(va, pszFormat);
3452#ifdef IN_GC
3453 pDevIns->pDevHlpGC->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
3454#elif defined(IN_RING0)
3455 pDevIns->pDevHlpR0->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
3456#else
3457 pDevIns->pDevHlp->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
3458#endif
3459 va_end(va);
3460 return rc;
3461}
3462
3463/**
3464 * @copydoc PDMDEVHLP::pfnVMSetRuntimeError
3465 */
3466DECLINLINE(int) PDMDevHlpVMSetRuntimeError(PPDMDEVINS pDevIns, bool fFatal, const char *pszErrorID, const char *pszFormat, ...)
3467{
3468 va_list va;
3469 int rc;
3470 va_start(va, pszFormat);
3471#ifdef IN_GC
3472 rc = pDevIns->pDevHlpGC->pfnVMSetRuntimeErrorV(pDevIns, fFatal, pszErrorID, pszFormat, va);
3473#elif defined(IN_RING0)
3474 rc = pDevIns->pDevHlpR0->pfnVMSetRuntimeErrorV(pDevIns, fFatal, pszErrorID, pszFormat, va);
3475#else
3476 rc = pDevIns->pDevHlp->pfnVMSetRuntimeErrorV(pDevIns, fFatal, pszErrorID, pszFormat, va);
3477#endif
3478 va_end(va);
3479 return rc;
3480}
3481
3482
3483
3484/** Pointer to callbacks provided to the VBoxDeviceRegister() call. */
3485typedef struct PDMDEVREGCB *PPDMDEVREGCB;
3486
3487/**
3488 * Callbacks for VBoxDeviceRegister().
3489 */
3490typedef struct PDMDEVREGCB
3491{
3492 /** Interface version.
3493 * This is set to PDM_DEVREG_CB_VERSION. */
3494 uint32_t u32Version;
3495
3496 /**
3497 * Registers a device with the current VM instance.
3498 *
3499 * @returns VBox status code.
3500 * @param pCallbacks Pointer to the callback table.
3501 * @param pDevReg Pointer to the device registration record.
3502 * This data must be permanent and readonly.
3503 */
3504 DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMDEVREGCB pCallbacks, PCPDMDEVREG pDevReg));
3505
3506 /**
3507 * Allocate memory which is associated with current VM instance
3508 * and automatically freed on it's destruction.
3509 *
3510 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
3511 * @param pCallbacks Pointer to the callback table.
3512 * @param cb Number of bytes to allocate.
3513 */
3514 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVREGCB pCallbacks, size_t cb));
3515} PDMDEVREGCB;
3516
3517/** Current version of the PDMDEVREGCB structure. */
3518#define PDM_DEVREG_CB_VERSION 0xf4010000
3519
3520
3521/**
3522 * The VBoxDevicesRegister callback function.
3523 *
3524 * PDM will invoke this function after loading a device module and letting
3525 * the module decide which devices to register and how to handle conflicts.
3526 *
3527 * @returns VBox status code.
3528 * @param pCallbacks Pointer to the callback table.
3529 * @param u32Version VBox version number.
3530 */
3531typedef DECLCALLBACK(int) FNPDMVBOXDEVICESREGISTER(PPDMDEVREGCB pCallbacks, uint32_t u32Version);
3532
3533/** @} */
3534
3535__END_DECLS
3536
3537#endif
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