VirtualBox

source: vbox/trunk/include/VBox/vmm/pdmdev.h@ 81964

Last change on this file since 81964 was 81961, checked in by vboxsync, 6 years ago

DevHPET,PDM: Split structures and refactored registration. bugref:9218
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 337.5 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, Devices.
3 */
4
5/*
6 * Copyright (C) 2006-2019 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef VBOX_INCLUDED_vmm_pdmdev_h
27#define VBOX_INCLUDED_vmm_pdmdev_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <VBox/vmm/pdmcritsect.h>
33#include <VBox/vmm/pdmqueue.h>
34#include <VBox/vmm/pdmtask.h>
35#ifdef IN_RING3
36# include <VBox/vmm/pdmthread.h>
37#endif
38#include <VBox/vmm/pdmifs.h>
39#include <VBox/vmm/pdmins.h>
40#include <VBox/vmm/pdmcommon.h>
41#include <VBox/vmm/pdmpcidev.h>
42#include <VBox/vmm/iom.h>
43#include <VBox/vmm/tm.h>
44#include <VBox/vmm/ssm.h>
45#include <VBox/vmm/cfgm.h>
46#include <VBox/vmm/dbgf.h>
47#include <VBox/err.h> /* VINF_EM_DBG_STOP, also 120+ source files expecting this. */
48#include <iprt/stdarg.h>
49#include <iprt/list.h>
50
51
52RT_C_DECLS_BEGIN
53
54/** @defgroup grp_pdm_device The PDM Devices API
55 * @ingroup grp_pdm
56 * @{
57 */
58
59/**
60 * Construct a device instance for a VM.
61 *
62 * @returns VBox status.
63 * @param pDevIns The device instance data. If the registration structure
64 * is needed, it can be accessed thru pDevIns->pReg.
65 * @param iInstance Instance number. Use this to figure out which registers
66 * and such to use. The instance number is also found in
67 * pDevIns->iInstance, but since it's likely to be
68 * frequently used PDM passes it as parameter.
69 * @param pCfg Configuration node handle for the driver. This is
70 * expected to be in high demand in the constructor and is
71 * therefore passed as an argument. When using it at other
72 * times, it can be found in pDevIns->pCfg.
73 */
74typedef DECLCALLBACK(int) FNPDMDEVCONSTRUCT(PPDMDEVINS pDevIns, int iInstance, PCFGMNODE pCfg);
75/** Pointer to a FNPDMDEVCONSTRUCT() function. */
76typedef FNPDMDEVCONSTRUCT *PFNPDMDEVCONSTRUCT;
77
78/**
79 * Destruct a device instance.
80 *
81 * Most VM resources are freed by the VM. This callback is provided so that any non-VM
82 * resources can be freed correctly.
83 *
84 * @returns VBox status.
85 * @param pDevIns The device instance data.
86 *
87 * @remarks The device critical section is not entered. The routine may delete
88 * the critical section, so the caller cannot exit it.
89 */
90typedef DECLCALLBACK(int) FNPDMDEVDESTRUCT(PPDMDEVINS pDevIns);
91/** Pointer to a FNPDMDEVDESTRUCT() function. */
92typedef FNPDMDEVDESTRUCT *PFNPDMDEVDESTRUCT;
93
94/**
95 * Device relocation callback.
96 *
97 * This is called when the instance data has been relocated in raw-mode context
98 * (RC). It is also called when the RC hypervisor selects changes. The device
99 * must fixup all necessary pointers and re-query all interfaces to other RC
100 * devices and drivers.
101 *
102 * Before the RC code is executed the first time, this function will be called
103 * with a 0 delta so RC pointer calculations can be one in one place.
104 *
105 * @param pDevIns Pointer to the device instance.
106 * @param offDelta The relocation delta relative to the old location.
107 *
108 * @remarks A relocation CANNOT fail.
109 *
110 * @remarks The device critical section is not entered. The relocations should
111 * not normally require any locking.
112 */
113typedef DECLCALLBACK(void) FNPDMDEVRELOCATE(PPDMDEVINS pDevIns, RTGCINTPTR offDelta);
114/** Pointer to a FNPDMDEVRELOCATE() function. */
115typedef FNPDMDEVRELOCATE *PFNPDMDEVRELOCATE;
116
117/**
118 * Power On notification.
119 *
120 * @returns VBox status.
121 * @param pDevIns The device instance data.
122 *
123 * @remarks Caller enters the device critical section.
124 */
125typedef DECLCALLBACK(void) FNPDMDEVPOWERON(PPDMDEVINS pDevIns);
126/** Pointer to a FNPDMDEVPOWERON() function. */
127typedef FNPDMDEVPOWERON *PFNPDMDEVPOWERON;
128
129/**
130 * Reset notification.
131 *
132 * @returns VBox status.
133 * @param pDevIns The device instance data.
134 *
135 * @remarks Caller enters the device critical section.
136 */
137typedef DECLCALLBACK(void) FNPDMDEVRESET(PPDMDEVINS pDevIns);
138/** Pointer to a FNPDMDEVRESET() function. */
139typedef FNPDMDEVRESET *PFNPDMDEVRESET;
140
141/**
142 * Soft reset notification.
143 *
144 * This is mainly for emulating the 286 style protected mode exits, in which
145 * most devices should remain in their current state.
146 *
147 * @returns VBox status.
148 * @param pDevIns The device instance data.
149 * @param fFlags PDMVMRESET_F_XXX (only bits relevant to soft resets).
150 *
151 * @remarks Caller enters the device critical section.
152 */
153typedef DECLCALLBACK(void) FNPDMDEVSOFTRESET(PPDMDEVINS pDevIns, uint32_t fFlags);
154/** Pointer to a FNPDMDEVSOFTRESET() function. */
155typedef FNPDMDEVSOFTRESET *PFNPDMDEVSOFTRESET;
156
157/** @name PDMVMRESET_F_XXX - VM reset flags.
158 * These flags are used both for FNPDMDEVSOFTRESET and for hardware signalling
159 * reset via PDMDevHlpVMReset.
160 * @{ */
161/** Unknown reason. */
162#define PDMVMRESET_F_UNKNOWN UINT32_C(0x00000000)
163/** GIM triggered reset. */
164#define PDMVMRESET_F_GIM UINT32_C(0x00000001)
165/** The last source always causing hard resets. */
166#define PDMVMRESET_F_LAST_ALWAYS_HARD PDMVMRESET_F_GIM
167/** ACPI triggered reset. */
168#define PDMVMRESET_F_ACPI UINT32_C(0x0000000c)
169/** PS/2 system port A (92h) reset. */
170#define PDMVMRESET_F_PORT_A UINT32_C(0x0000000d)
171/** Keyboard reset. */
172#define PDMVMRESET_F_KBD UINT32_C(0x0000000e)
173/** Tripple fault. */
174#define PDMVMRESET_F_TRIPLE_FAULT UINT32_C(0x0000000f)
175/** Reset source mask. */
176#define PDMVMRESET_F_SRC_MASK UINT32_C(0x0000000f)
177/** @} */
178
179/**
180 * Suspend notification.
181 *
182 * @returns VBox status.
183 * @param pDevIns The device instance data.
184 * @thread EMT(0)
185 *
186 * @remarks Caller enters the device critical section.
187 */
188typedef DECLCALLBACK(void) FNPDMDEVSUSPEND(PPDMDEVINS pDevIns);
189/** Pointer to a FNPDMDEVSUSPEND() function. */
190typedef FNPDMDEVSUSPEND *PFNPDMDEVSUSPEND;
191
192/**
193 * Resume notification.
194 *
195 * @returns VBox status.
196 * @param pDevIns The device instance data.
197 *
198 * @remarks Caller enters the device critical section.
199 */
200typedef DECLCALLBACK(void) FNPDMDEVRESUME(PPDMDEVINS pDevIns);
201/** Pointer to a FNPDMDEVRESUME() function. */
202typedef FNPDMDEVRESUME *PFNPDMDEVRESUME;
203
204/**
205 * Power Off notification.
206 *
207 * This is always called when VMR3PowerOff is called.
208 * There will be no callback when hot plugging devices.
209 *
210 * @param pDevIns The device instance data.
211 * @thread EMT(0)
212 *
213 * @remarks Caller enters the device critical section.
214 */
215typedef DECLCALLBACK(void) FNPDMDEVPOWEROFF(PPDMDEVINS pDevIns);
216/** Pointer to a FNPDMDEVPOWEROFF() function. */
217typedef FNPDMDEVPOWEROFF *PFNPDMDEVPOWEROFF;
218
219/**
220 * Attach command.
221 *
222 * This is called to let the device attach to a driver for a specified LUN
223 * at runtime. This is not called during VM construction, the device
224 * constructor has to attach to all the available drivers.
225 *
226 * This is like plugging in the keyboard or mouse after turning on the PC.
227 *
228 * @returns VBox status code.
229 * @param pDevIns The device instance.
230 * @param iLUN The logical unit which is being attached.
231 * @param fFlags Flags, combination of the PDM_TACH_FLAGS_* \#defines.
232 *
233 * @remarks Caller enters the device critical section.
234 */
235typedef DECLCALLBACK(int) FNPDMDEVATTACH(PPDMDEVINS pDevIns, unsigned iLUN, uint32_t fFlags);
236/** Pointer to a FNPDMDEVATTACH() function. */
237typedef FNPDMDEVATTACH *PFNPDMDEVATTACH;
238
239/**
240 * Detach notification.
241 *
242 * This is called when a driver is detaching itself from a LUN of the device.
243 * The device should adjust its state to reflect this.
244 *
245 * This is like unplugging the network cable to use it for the laptop or
246 * something while the PC is still running.
247 *
248 * @param pDevIns The device instance.
249 * @param iLUN The logical unit which is being detached.
250 * @param fFlags Flags, combination of the PDMDEVATT_FLAGS_* \#defines.
251 *
252 * @remarks Caller enters the device critical section.
253 */
254typedef DECLCALLBACK(void) FNPDMDEVDETACH(PPDMDEVINS pDevIns, unsigned iLUN, uint32_t fFlags);
255/** Pointer to a FNPDMDEVDETACH() function. */
256typedef FNPDMDEVDETACH *PFNPDMDEVDETACH;
257
258/**
259 * Query the base interface of a logical unit.
260 *
261 * @returns VBOX status code.
262 * @param pDevIns The device instance.
263 * @param iLUN The logicial unit to query.
264 * @param ppBase Where to store the pointer to the base interface of the LUN.
265 *
266 * @remarks The device critical section is not entered.
267 */
268typedef DECLCALLBACK(int) FNPDMDEVQUERYINTERFACE(PPDMDEVINS pDevIns, unsigned iLUN, PPDMIBASE *ppBase);
269/** Pointer to a FNPDMDEVQUERYINTERFACE() function. */
270typedef FNPDMDEVQUERYINTERFACE *PFNPDMDEVQUERYINTERFACE;
271
272/**
273 * Init complete notification (after ring-0 & RC init since 5.1).
274 *
275 * This can be done to do communication with other devices and other
276 * initialization which requires everything to be in place.
277 *
278 * @returns VBOX status code.
279 * @param pDevIns The device instance.
280 *
281 * @remarks Caller enters the device critical section.
282 */
283typedef DECLCALLBACK(int) FNPDMDEVINITCOMPLETE(PPDMDEVINS pDevIns);
284/** Pointer to a FNPDMDEVINITCOMPLETE() function. */
285typedef FNPDMDEVINITCOMPLETE *PFNPDMDEVINITCOMPLETE;
286
287
288/**
289 * The context of a pfnMemSetup call.
290 */
291typedef enum PDMDEVMEMSETUPCTX
292{
293 /** Invalid zero value. */
294 PDMDEVMEMSETUPCTX_INVALID = 0,
295 /** After construction. */
296 PDMDEVMEMSETUPCTX_AFTER_CONSTRUCTION,
297 /** After reset. */
298 PDMDEVMEMSETUPCTX_AFTER_RESET,
299 /** Type size hack. */
300 PDMDEVMEMSETUPCTX_32BIT_HACK = 0x7fffffff
301} PDMDEVMEMSETUPCTX;
302
303
304/**
305 * PDM Device Registration Structure.
306 *
307 * This structure is used when registering a device from VBoxInitDevices() in HC
308 * Ring-3. PDM will continue use till the VM is terminated.
309 *
310 * @note The first part is the same in every context.
311 */
312typedef struct PDMDEVREGR3
313{
314 /** Structure version. PDM_DEVREGR3_VERSION defines the current version. */
315 uint32_t u32Version;
316 /** Reserved, must be zero. */
317 uint32_t uReserved0;
318 /** Device name, must match the ring-3 one. */
319 char szName[32];
320 /** Flags, combination of the PDM_DEVREG_FLAGS_* \#defines. */
321 uint32_t fFlags;
322 /** Device class(es), combination of the PDM_DEVREG_CLASS_* \#defines. */
323 uint32_t fClass;
324 /** Maximum number of instances (per VM). */
325 uint32_t cMaxInstances;
326 /** The shared data structure version number. */
327 uint32_t uSharedVersion;
328 /** Size of the instance data. */
329 uint32_t cbInstanceShared;
330 /** Size of the ring-0 instance data. */
331 uint32_t cbInstanceCC;
332 /** Size of the raw-mode instance data. */
333 uint32_t cbInstanceRC;
334 /** Max number of PCI devices. */
335 uint16_t cMaxPciDevices;
336 /** Max number of MSI-X vectors in any of the PCI devices. */
337 uint16_t cMaxMsixVectors;
338 /** The description of the device. The UTF-8 string pointed to shall, like this structure,
339 * remain unchanged from registration till VM destruction. */
340 const char *pszDescription;
341
342 /** Name of the raw-mode context module (no path).
343 * Only evalutated if PDM_DEVREG_FLAGS_RC is set. */
344 const char *pszRCMod;
345 /** Name of the ring-0 module (no path).
346 * Only evalutated if PDM_DEVREG_FLAGS_R0 is set. */
347 const char *pszR0Mod;
348
349 /** Construct instance - required. */
350 PFNPDMDEVCONSTRUCT pfnConstruct;
351 /** Destruct instance - optional.
352 * Critical section NOT entered (will be destroyed). */
353 PFNPDMDEVDESTRUCT pfnDestruct;
354 /** Relocation command - optional.
355 * Critical section NOT entered. */
356 PFNPDMDEVRELOCATE pfnRelocate;
357 /**
358 * Memory setup callback.
359 *
360 * @param pDevIns The device instance data.
361 * @param enmCtx Indicates the context of the call.
362 * @remarks The critical section is entered prior to calling this method.
363 */
364 DECLR3CALLBACKMEMBER(void, pfnMemSetup, (PPDMDEVINS pDevIns, PDMDEVMEMSETUPCTX enmCtx));
365 /** Power on notification - optional.
366 * Critical section is entered. */
367 PFNPDMDEVPOWERON pfnPowerOn;
368 /** Reset notification - optional.
369 * Critical section is entered. */
370 PFNPDMDEVRESET pfnReset;
371 /** Suspend notification - optional.
372 * Critical section is entered. */
373 PFNPDMDEVSUSPEND pfnSuspend;
374 /** Resume notification - optional.
375 * Critical section is entered. */
376 PFNPDMDEVRESUME pfnResume;
377 /** Attach command - optional.
378 * Critical section is entered. */
379 PFNPDMDEVATTACH pfnAttach;
380 /** Detach notification - optional.
381 * Critical section is entered. */
382 PFNPDMDEVDETACH pfnDetach;
383 /** Query a LUN base interface - optional.
384 * Critical section is NOT entered. */
385 PFNPDMDEVQUERYINTERFACE pfnQueryInterface;
386 /** Init complete notification - optional.
387 * Critical section is entered. */
388 PFNPDMDEVINITCOMPLETE pfnInitComplete;
389 /** Power off notification - optional.
390 * Critical section is entered. */
391 PFNPDMDEVPOWEROFF pfnPowerOff;
392 /** Software system reset notification - optional.
393 * Critical section is entered. */
394 PFNPDMDEVSOFTRESET pfnSoftReset;
395
396 /** @name Reserved for future extensions, must be zero.
397 * @{ */
398 DECLR3CALLBACKMEMBER(int, pfnReserved0, (PPDMDEVINS pDevIns));
399 DECLR3CALLBACKMEMBER(int, pfnReserved1, (PPDMDEVINS pDevIns));
400 DECLR3CALLBACKMEMBER(int, pfnReserved2, (PPDMDEVINS pDevIns));
401 DECLR3CALLBACKMEMBER(int, pfnReserved3, (PPDMDEVINS pDevIns));
402 DECLR3CALLBACKMEMBER(int, pfnReserved4, (PPDMDEVINS pDevIns));
403 DECLR3CALLBACKMEMBER(int, pfnReserved5, (PPDMDEVINS pDevIns));
404 DECLR3CALLBACKMEMBER(int, pfnReserved6, (PPDMDEVINS pDevIns));
405 DECLR3CALLBACKMEMBER(int, pfnReserved7, (PPDMDEVINS pDevIns));
406 /** @} */
407
408 /** Initialization safty marker. */
409 uint32_t u32VersionEnd;
410} PDMDEVREGR3;
411/** Pointer to a PDM Device Structure. */
412typedef PDMDEVREGR3 *PPDMDEVREGR3;
413/** Const pointer to a PDM Device Structure. */
414typedef PDMDEVREGR3 const *PCPDMDEVREGR3;
415/** Current DEVREGR3 version number. */
416#define PDM_DEVREGR3_VERSION PDM_VERSION_MAKE(0xffff, 4, 0)
417
418
419/** PDM Device Flags.
420 * @{ */
421/** This flag is used to indicate that the device has a R0 component. */
422#define PDM_DEVREG_FLAGS_R0 UINT32_C(0x00000001)
423/** Requires the ring-0 component, ignore configuration values. */
424#define PDM_DEVREG_FLAGS_REQUIRE_R0 UINT32_C(0x00000002)
425/** Requires the ring-0 component, ignore configuration values. */
426#define PDM_DEVREG_FLAGS_OPT_IN_R0 UINT32_C(0x00000004)
427
428/** This flag is used to indicate that the device has a RC component. */
429#define PDM_DEVREG_FLAGS_RC UINT32_C(0x00000010)
430/** Requires the raw-mode component, ignore configuration values. */
431#define PDM_DEVREG_FLAGS_REQUIRE_RC UINT32_C(0x00000020)
432/** Requires the raw-mode component, ignore configuration values. */
433#define PDM_DEVREG_FLAGS_OPT_IN_RC UINT32_C(0x00000040)
434
435/** Convenience: PDM_DEVREG_FLAGS_R0 + PDM_DEVREG_FLAGS_RC */
436#define PDM_DEVREG_FLAGS_RZ (PDM_DEVREG_FLAGS_R0 | PDM_DEVREG_FLAGS_RC)
437
438/** @def PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT
439 * The bit count for the current host.
440 * @note Superfluous, but still around for hysterical raisins. */
441#if HC_ARCH_BITS == 32
442# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT UINT32_C(0x00000100)
443#elif HC_ARCH_BITS == 64
444# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT UINT32_C(0x00000200)
445#else
446# error Unsupported HC_ARCH_BITS value.
447#endif
448/** The host bit count mask. */
449#define PDM_DEVREG_FLAGS_HOST_BITS_MASK UINT32_C(0x00000300)
450
451/** The device support only 32-bit guests. */
452#define PDM_DEVREG_FLAGS_GUEST_BITS_32 UINT32_C(0x00001000)
453/** The device support only 64-bit guests. */
454#define PDM_DEVREG_FLAGS_GUEST_BITS_64 UINT32_C(0x00002000)
455/** The device support both 32-bit & 64-bit guests. */
456#define PDM_DEVREG_FLAGS_GUEST_BITS_32_64 UINT32_C(0x00003000)
457/** @def PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT
458 * The guest bit count for the current compilation. */
459#if GC_ARCH_BITS == 32
460# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_32
461#elif GC_ARCH_BITS == 64
462# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_32_64
463#else
464# error Unsupported GC_ARCH_BITS value.
465#endif
466/** The guest bit count mask. */
467#define PDM_DEVREG_FLAGS_GUEST_BITS_MASK UINT32_C(0x00003000)
468
469/** A convenience. */
470#define PDM_DEVREG_FLAGS_DEFAULT_BITS (PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT | PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT)
471
472/** Indicates that the device needs to be notified before the drivers when suspending. */
473#define PDM_DEVREG_FLAGS_FIRST_SUSPEND_NOTIFICATION UINT32_C(0x00010000)
474/** Indicates that the device needs to be notified before the drivers when powering off. */
475#define PDM_DEVREG_FLAGS_FIRST_POWEROFF_NOTIFICATION UINT32_C(0x00020000)
476/** Indicates that the device needs to be notified before the drivers when resetting. */
477#define PDM_DEVREG_FLAGS_FIRST_RESET_NOTIFICATION UINT32_C(0x00040000)
478
479/** This flag is used to indicate that the device has been converted to the
480 * new device style. */
481#define PDM_DEVREG_FLAGS_NEW_STYLE UINT32_C(0x80000000)
482
483/** @} */
484
485
486/** PDM Device Classes.
487 * The order is important, lower bit earlier instantiation.
488 * @{ */
489/** Architecture device. */
490#define PDM_DEVREG_CLASS_ARCH RT_BIT(0)
491/** Architecture BIOS device. */
492#define PDM_DEVREG_CLASS_ARCH_BIOS RT_BIT(1)
493/** PCI bus brigde. */
494#define PDM_DEVREG_CLASS_BUS_PCI RT_BIT(2)
495/** ISA bus brigde. */
496#define PDM_DEVREG_CLASS_BUS_ISA RT_BIT(3)
497/** Input device (mouse, keyboard, joystick, HID, ...). */
498#define PDM_DEVREG_CLASS_INPUT RT_BIT(4)
499/** Interrupt controller (PIC). */
500#define PDM_DEVREG_CLASS_PIC RT_BIT(5)
501/** Interval controoler (PIT). */
502#define PDM_DEVREG_CLASS_PIT RT_BIT(6)
503/** RTC/CMOS. */
504#define PDM_DEVREG_CLASS_RTC RT_BIT(7)
505/** DMA controller. */
506#define PDM_DEVREG_CLASS_DMA RT_BIT(8)
507/** VMM Device. */
508#define PDM_DEVREG_CLASS_VMM_DEV RT_BIT(9)
509/** Graphics device, like VGA. */
510#define PDM_DEVREG_CLASS_GRAPHICS RT_BIT(10)
511/** Storage controller device. */
512#define PDM_DEVREG_CLASS_STORAGE RT_BIT(11)
513/** Network interface controller. */
514#define PDM_DEVREG_CLASS_NETWORK RT_BIT(12)
515/** Audio. */
516#define PDM_DEVREG_CLASS_AUDIO RT_BIT(13)
517/** USB HIC. */
518#define PDM_DEVREG_CLASS_BUS_USB RT_BIT(14)
519/** ACPI. */
520#define PDM_DEVREG_CLASS_ACPI RT_BIT(15)
521/** Serial controller device. */
522#define PDM_DEVREG_CLASS_SERIAL RT_BIT(16)
523/** Parallel controller device */
524#define PDM_DEVREG_CLASS_PARALLEL RT_BIT(17)
525/** Host PCI pass-through device */
526#define PDM_DEVREG_CLASS_HOST_DEV RT_BIT(18)
527/** Misc devices (always last). */
528#define PDM_DEVREG_CLASS_MISC RT_BIT(31)
529/** @} */
530
531
532/**
533 * PDM Device Registration Structure, ring-0.
534 *
535 * This structure is used when registering a device from VBoxInitDevices() in HC
536 * Ring-0. PDM will continue use till the VM is terminated.
537 */
538typedef struct PDMDEVREGR0
539{
540 /** Structure version. PDM_DEVREGR0_VERSION defines the current version. */
541 uint32_t u32Version;
542 /** Reserved, must be zero. */
543 uint32_t uReserved0;
544 /** Device name, must match the ring-3 one. */
545 char szName[32];
546 /** Flags, combination of the PDM_DEVREG_FLAGS_* \#defines. */
547 uint32_t fFlags;
548 /** Device class(es), combination of the PDM_DEVREG_CLASS_* \#defines. */
549 uint32_t fClass;
550 /** Maximum number of instances (per VM). */
551 uint32_t cMaxInstances;
552 /** The shared data structure version number. */
553 uint32_t uSharedVersion;
554 /** Size of the instance data. */
555 uint32_t cbInstanceShared;
556 /** Size of the ring-0 instance data. */
557 uint32_t cbInstanceCC;
558 /** Size of the raw-mode instance data. */
559 uint32_t cbInstanceRC;
560 /** Max number of PCI devices. */
561 uint16_t cMaxPciDevices;
562 /** Max number of MSI-X vectors in any of the PCI devices. */
563 uint16_t cMaxMsixVectors;
564 /** The description of the device. The UTF-8 string pointed to shall, like this structure,
565 * remain unchanged from registration till VM destruction. */
566 const char *pszDescription;
567
568 /**
569 * Early construction callback (optional).
570 *
571 * This is called right after the device instance structure has been allocated
572 * and before the ring-3 constructor gets called.
573 *
574 * @returns VBox status code.
575 * @param pDevIns The device instance data.
576 * @note The destructure is always called, regardless of the return status.
577 */
578 DECLR0CALLBACKMEMBER(int, pfnEarlyConstruct, (PPDMDEVINS pDevIns));
579
580 /**
581 * Regular construction callback (optional).
582 *
583 * This is called after (or during) the ring-3 constructor.
584 *
585 * @returns VBox status code.
586 * @param pDevIns The device instance data.
587 * @note The destructure is always called, regardless of the return status.
588 */
589 DECLR0CALLBACKMEMBER(int, pfnConstruct, (PPDMDEVINS pDevIns));
590
591 /**
592 * Destructor (optional).
593 *
594 * This is called after the ring-3 destruction. This is not called if ring-3
595 * fails to trigger it (e.g. process is killed or crashes).
596 *
597 * @param pDevIns The device instance data.
598 */
599 DECLR0CALLBACKMEMBER(void, pfnDestruct, (PPDMDEVINS pDevIns));
600
601 /**
602 * Final destructor (optional).
603 *
604 * This is called right before the memory is freed, which happens when the
605 * VM/GVM object is destroyed. This is always called.
606 *
607 * @param pDevIns The device instance data.
608 */
609 DECLR0CALLBACKMEMBER(void, pfnFinalDestruct, (PPDMDEVINS pDevIns));
610
611 /**
612 * Generic request handler (optional).
613 *
614 * @param pDevIns The device instance data.
615 * @param uReq Device specific request.
616 * @param uArg Request argument.
617 */
618 DECLR0CALLBACKMEMBER(int, pfnRequest, (PPDMDEVINS pDevIns, uint32_t uReq, uint64_t uArg));
619
620 /** @name Reserved for future extensions, must be zero.
621 * @{ */
622 DECLR0CALLBACKMEMBER(int, pfnReserved0, (PPDMDEVINS pDevIns));
623 DECLR0CALLBACKMEMBER(int, pfnReserved1, (PPDMDEVINS pDevIns));
624 DECLR0CALLBACKMEMBER(int, pfnReserved2, (PPDMDEVINS pDevIns));
625 DECLR0CALLBACKMEMBER(int, pfnReserved3, (PPDMDEVINS pDevIns));
626 DECLR0CALLBACKMEMBER(int, pfnReserved4, (PPDMDEVINS pDevIns));
627 DECLR0CALLBACKMEMBER(int, pfnReserved5, (PPDMDEVINS pDevIns));
628 DECLR0CALLBACKMEMBER(int, pfnReserved6, (PPDMDEVINS pDevIns));
629 DECLR0CALLBACKMEMBER(int, pfnReserved7, (PPDMDEVINS pDevIns));
630 /** @} */
631
632 /** Initialization safty marker. */
633 uint32_t u32VersionEnd;
634} PDMDEVREGR0;
635/** Pointer to a ring-0 PDM device registration structure. */
636typedef PDMDEVREGR0 *PPDMDEVREGR0;
637/** Pointer to a const ring-0 PDM device registration structure. */
638typedef PDMDEVREGR0 const *PCPDMDEVREGR0;
639/** Current DEVREGR0 version number. */
640#define PDM_DEVREGR0_VERSION PDM_VERSION_MAKE(0xff80, 1, 0)
641
642
643/**
644 * PDM Device Registration Structure, raw-mode
645 *
646 * At the moment, this structure is mostly here to match the other two contexts.
647 */
648typedef struct PDMDEVREGRC
649{
650 /** Structure version. PDM_DEVREGRC_VERSION defines the current version. */
651 uint32_t u32Version;
652 /** Reserved, must be zero. */
653 uint32_t uReserved0;
654 /** Device name, must match the ring-3 one. */
655 char szName[32];
656 /** Flags, combination of the PDM_DEVREG_FLAGS_* \#defines. */
657 uint32_t fFlags;
658 /** Device class(es), combination of the PDM_DEVREG_CLASS_* \#defines. */
659 uint32_t fClass;
660 /** Maximum number of instances (per VM). */
661 uint32_t cMaxInstances;
662 /** The shared data structure version number. */
663 uint32_t uSharedVersion;
664 /** Size of the instance data. */
665 uint32_t cbInstanceShared;
666 /** Size of the ring-0 instance data. */
667 uint32_t cbInstanceCC;
668 /** Size of the raw-mode instance data. */
669 uint32_t cbInstanceRC;
670 /** Max number of PCI devices. */
671 uint16_t cMaxPciDevices;
672 /** Max number of MSI-X vectors in any of the PCI devices. */
673 uint16_t cMaxMsixVectors;
674 /** The description of the device. The UTF-8 string pointed to shall, like this structure,
675 * remain unchanged from registration till VM destruction. */
676 const char *pszDescription;
677
678 /**
679 * Constructor callback.
680 *
681 * This is called much later than both the ring-0 and ring-3 constructors, since
682 * raw-mode v2 require a working VMM to run actual code.
683 *
684 * @returns VBox status code.
685 * @param pDevIns The device instance data.
686 * @note The destructure is always called, regardless of the return status.
687 */
688 DECLRGCALLBACKMEMBER(int, pfnConstruct, (PPDMDEVINS pDevIns));
689
690 /** @name Reserved for future extensions, must be zero.
691 * @{ */
692 DECLRCCALLBACKMEMBER(int, pfnReserved0, (PPDMDEVINS pDevIns));
693 DECLRCCALLBACKMEMBER(int, pfnReserved1, (PPDMDEVINS pDevIns));
694 DECLRCCALLBACKMEMBER(int, pfnReserved2, (PPDMDEVINS pDevIns));
695 DECLRCCALLBACKMEMBER(int, pfnReserved3, (PPDMDEVINS pDevIns));
696 DECLRCCALLBACKMEMBER(int, pfnReserved4, (PPDMDEVINS pDevIns));
697 DECLRCCALLBACKMEMBER(int, pfnReserved5, (PPDMDEVINS pDevIns));
698 DECLRCCALLBACKMEMBER(int, pfnReserved6, (PPDMDEVINS pDevIns));
699 DECLRCCALLBACKMEMBER(int, pfnReserved7, (PPDMDEVINS pDevIns));
700 /** @} */
701
702 /** Initialization safty marker. */
703 uint32_t u32VersionEnd;
704} PDMDEVREGRC;
705/** Pointer to a raw-mode PDM device registration structure. */
706typedef PDMDEVREGRC *PPDMDEVREGRC;
707/** Pointer to a const raw-mode PDM device registration structure. */
708typedef PDMDEVREGRC const *PCPDMDEVREGRC;
709/** Current DEVREGRC version number. */
710#define PDM_DEVREGRC_VERSION PDM_VERSION_MAKE(0xff81, 1, 0)
711
712
713
714/** @def PDM_DEVREG_VERSION
715 * Current DEVREG version number. */
716/** @typedef PDMDEVREGR3
717 * A current context PDM device registration structure. */
718/** @typedef PPDMDEVREGR3
719 * Pointer to a current context PDM device registration structure. */
720/** @typedef PCPDMDEVREGR3
721 * Pointer to a const current context PDM device registration structure. */
722#if defined(IN_RING3) || defined(DOXYGEN_RUNNING)
723# define PDM_DEVREG_VERSION PDM_DEVREGR3_VERSION
724typedef PDMDEVREGR3 PDMDEVREG;
725typedef PPDMDEVREGR3 PPDMDEVREG;
726typedef PCPDMDEVREGR3 PCPDMDEVREG;
727#elif defined(IN_RING0)
728# define PDM_DEVREG_VERSION PDM_DEVREGR0_VERSION
729typedef PDMDEVREGR0 PDMDEVREG;
730typedef PPDMDEVREGR0 PPDMDEVREG;
731typedef PCPDMDEVREGR0 PCPDMDEVREG;
732#elif defined(IN_RC)
733# define PDM_DEVREG_VERSION PDM_DEVREGRC_VERSION
734typedef PDMDEVREGRC PDMDEVREG;
735typedef PPDMDEVREGRC PPDMDEVREG;
736typedef PCPDMDEVREGRC PCPDMDEVREG;
737#else
738# error "Not IN_RING3, IN_RING0 or IN_RC"
739#endif
740
741
742/**
743 * Device registrations for ring-0 modules.
744 *
745 * This structure is used directly and must therefore reside in persistent
746 * memory (i.e. the data section).
747 */
748typedef struct PDMDEVMODREGR0
749{
750 /** The structure version (PDM_DEVMODREGR0_VERSION). */
751 uint32_t u32Version;
752 /** Number of devices in the array papDevRegs points to. */
753 uint32_t cDevRegs;
754 /** Pointer to device registration structures. */
755 PCPDMDEVREGR0 *papDevRegs;
756 /** The ring-0 module handle - PDM internal, fingers off. */
757 void *hMod;
758 /** List entry - PDM internal, fingers off. */
759 RTLISTNODE ListEntry;
760} PDMDEVMODREGR0;
761/** Pointer to device registriations for a ring-0 module. */
762typedef PDMDEVMODREGR0 *PPDMDEVMODREGR0;
763/** Current PDMDEVMODREGR0 version number. */
764#define PDM_DEVMODREGR0_VERSION PDM_VERSION_MAKE(0xff85, 1, 0)
765
766
767/** @name IRQ Level for use with the *SetIrq APIs.
768 * @{
769 */
770/** Assert the IRQ (can assume value 1). */
771#define PDM_IRQ_LEVEL_HIGH RT_BIT(0)
772/** Deassert the IRQ (can assume value 0). */
773#define PDM_IRQ_LEVEL_LOW 0
774/** flip-flop - deassert and then assert the IRQ again immediately. */
775#define PDM_IRQ_LEVEL_FLIP_FLOP (RT_BIT(1) | PDM_IRQ_LEVEL_HIGH)
776/** @} */
777
778/**
779 * Registration record for MSI/MSI-X emulation.
780 */
781typedef struct PDMMSIREG
782{
783 /** Number of MSI interrupt vectors, 0 if MSI not supported */
784 uint16_t cMsiVectors;
785 /** Offset of MSI capability */
786 uint8_t iMsiCapOffset;
787 /** Offset of next capability to MSI */
788 uint8_t iMsiNextOffset;
789 /** If we support 64-bit MSI addressing */
790 bool fMsi64bit;
791 /** If we do not support per-vector masking */
792 bool fMsiNoMasking;
793
794 /** Number of MSI-X interrupt vectors, 0 if MSI-X not supported */
795 uint16_t cMsixVectors;
796 /** Offset of MSI-X capability */
797 uint8_t iMsixCapOffset;
798 /** Offset of next capability to MSI-X */
799 uint8_t iMsixNextOffset;
800 /** Value of PCI BAR (base addresss register) assigned by device for MSI-X page access */
801 uint8_t iMsixBar;
802} PDMMSIREG;
803typedef PDMMSIREG *PPDMMSIREG;
804
805/**
806 * PCI Bus registration structure.
807 * All the callbacks, except the PCIBIOS hack, are working on PCI devices.
808 */
809typedef struct PDMPCIBUSREGR3
810{
811 /** Structure version number. PDM_PCIBUSREGR3_VERSION defines the current version. */
812 uint32_t u32Version;
813
814 /**
815 * Registers the device with the default PCI bus.
816 *
817 * @returns VBox status code.
818 * @param pDevIns Device instance of the PCI Bus.
819 * @param pPciDev The PCI device structure.
820 * @param fFlags Reserved for future use, PDMPCIDEVREG_F_MBZ.
821 * @param uPciDevNo PDMPCIDEVREG_DEV_NO_FIRST_UNUSED, or a specific
822 * device number (0-31).
823 * @param uPciFunNo PDMPCIDEVREG_FUN_NO_FIRST_UNUSED, or a specific
824 * function number (0-7).
825 * @param pszName Device name (static but not unique).
826 *
827 * @remarks Caller enters the PDM critical section.
828 */
829 DECLR3CALLBACKMEMBER(int, pfnRegisterR3,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t fFlags,
830 uint8_t uPciDevNo, uint8_t uPciFunNo, const char *pszName));
831
832 /**
833 * Initialize MSI or MSI-X emulation support in a PCI device.
834 *
835 * This cannot handle all corner cases of the MSI/MSI-X spec, but for the
836 * vast majority of device emulation it covers everything necessary. It's
837 * fully automatic, taking care of all BAR and config space requirements,
838 * and interrupt delivery is done using PDMDevHlpPCISetIrq and friends.
839 * When MSI/MSI-X is enabled then the iIrq parameter is redefined to take
840 * the vector number (otherwise it has the usual INTA-D meaning for PCI).
841 *
842 * A device not using this can still offer MSI/MSI-X. In this case it's
843 * completely up to the device (in the MSI-X case) to create/register the
844 * necessary MMIO BAR, handle all config space/BAR updating and take care
845 * of delivering the interrupts appropriately.
846 *
847 * @returns VBox status code.
848 * @param pDevIns Device instance of the PCI Bus.
849 * @param pPciDev The PCI device structure.
850 * @param pMsiReg MSI emulation registration structure
851 * @remarks Caller enters the PDM critical section.
852 */
853 DECLR3CALLBACKMEMBER(int, pfnRegisterMsiR3,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, PPDMMSIREG pMsiReg));
854
855 /**
856 * Registers a I/O region (memory mapped or I/O ports) for a PCI device.
857 *
858 * @returns VBox status code.
859 * @param pDevIns Device instance of the PCI Bus.
860 * @param pPciDev The PCI device structure.
861 * @param iRegion The region number.
862 * @param cbRegion Size of the region.
863 * @param enmType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or
864 * PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally with
865 * PCI_ADDRESS_SPACE_BAR64 or'ed in.
866 * @param fFlags PDMPCIDEV_IORGN_F_XXX.
867 * @param hHandle An I/O port, MMIO or MMIO2 handle according to
868 * @a fFlags, UINT64_MAX if no handle is passed
869 * (old style).
870 * @param pfnMapUnmap Callback for doing the mapping. Optional if a handle
871 * is given.
872 * @remarks Caller enters the PDM critical section.
873 */
874 DECLR3CALLBACKMEMBER(int, pfnIORegionRegisterR3,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion,
875 RTGCPHYS cbRegion, PCIADDRESSSPACE enmType, uint32_t fFlags,
876 uint64_t hHandle, PFNPCIIOREGIONMAP pfnMapUnmap));
877
878 /**
879 * Register PCI configuration space read/write intercept callbacks.
880 *
881 * @param pDevIns Device instance of the PCI Bus.
882 * @param pPciDev The PCI device structure.
883 * @param pfnRead Pointer to the user defined PCI config read function.
884 * @param pfnWrite Pointer to the user defined PCI config write function.
885 * to call default PCI config write function. Can be NULL.
886 * @remarks Caller enters the PDM critical section.
887 * @thread EMT
888 */
889 DECLR3CALLBACKMEMBER(void, pfnInterceptConfigAccesses,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
890 PFNPCICONFIGREAD pfnRead, PFNPCICONFIGWRITE pfnWrite));
891
892 /**
893 * Perform a PCI configuration space write, bypassing interception.
894 *
895 * This is for devices that make use of PDMDevHlpPCIInterceptConfigAccesses().
896 *
897 * @returns Strict VBox status code (mainly DBGFSTOP).
898 * @param pDevIns Device instance of the PCI Bus.
899 * @param pPciDev The PCI device which config space is being read.
900 * @param uAddress The config space address.
901 * @param cb The size of the read: 1, 2 or 4 bytes.
902 * @param u32Value The value to write.
903 * @note The caller (PDM) does not enter the PDM critsect, but it is possible
904 * that the (root) bus will have done that already.
905 */
906 DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnConfigWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
907 uint32_t uAddress, unsigned cb, uint32_t u32Value));
908
909 /**
910 * Perform a PCI configuration space read, bypassing interception.
911 *
912 * This is for devices that make use of PDMDevHlpPCIInterceptConfigAccesses().
913 *
914 * @returns Strict VBox status code (mainly DBGFSTOP).
915 * @param pDevIns Device instance of the PCI Bus.
916 * @param pPciDev The PCI device which config space is being read.
917 * @param uAddress The config space address.
918 * @param cb The size of the read: 1, 2 or 4 bytes.
919 * @param pu32Value Where to return the value.
920 * @note The caller (PDM) does not enter the PDM critsect, but it is possible
921 * that the (root) bus will have done that already.
922 */
923 DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnConfigRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
924 uint32_t uAddress, unsigned cb, uint32_t *pu32Value));
925
926 /**
927 * Set the IRQ for a PCI device.
928 *
929 * @param pDevIns Device instance of the PCI Bus.
930 * @param pPciDev The PCI device structure.
931 * @param iIrq IRQ number to set.
932 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
933 * @param uTagSrc The IRQ tag and source (for tracing).
934 * @remarks Caller enters the PDM critical section.
935 */
936 DECLR3CALLBACKMEMBER(void, pfnSetIrqR3,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel, uint32_t uTagSrc));
937
938 /** Marks the end of the structure with PDM_PCIBUSREGR3_VERSION. */
939 uint32_t u32EndVersion;
940} PDMPCIBUSREGR3;
941/** Pointer to a PCI bus registration structure. */
942typedef PDMPCIBUSREGR3 *PPDMPCIBUSREGR3;
943/** Current PDMPCIBUSREGR3 version number. */
944#define PDM_PCIBUSREGR3_VERSION PDM_VERSION_MAKE(0xff86, 2, 0)
945
946/**
947 * PCI Bus registration structure for ring-0.
948 */
949typedef struct PDMPCIBUSREGR0
950{
951 /** Structure version number. PDM_PCIBUSREGR0_VERSION defines the current version. */
952 uint32_t u32Version;
953 /** The PCI bus number (from ring-3 registration). */
954 uint32_t iBus;
955 /**
956 * Set the IRQ for a PCI device.
957 *
958 * @param pDevIns Device instance of the PCI Bus.
959 * @param pPciDev The PCI device structure.
960 * @param iIrq IRQ number to set.
961 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
962 * @param uTagSrc The IRQ tag and source (for tracing).
963 * @remarks Caller enters the PDM critical section.
964 */
965 DECLR0CALLBACKMEMBER(void, pfnSetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel, uint32_t uTagSrc));
966 /** Marks the end of the structure with PDM_PCIBUSREGR0_VERSION. */
967 uint32_t u32EndVersion;
968} PDMPCIBUSREGR0;
969/** Pointer to a PCI bus ring-0 registration structure. */
970typedef PDMPCIBUSREGR0 *PPDMPCIBUSREGR0;
971/** Current PDMPCIBUSREGR0 version number. */
972#define PDM_PCIBUSREGR0_VERSION PDM_VERSION_MAKE(0xff87, 1, 0)
973
974/**
975 * PCI Bus registration structure for raw-mode.
976 */
977typedef struct PDMPCIBUSREGRC
978{
979 /** Structure version number. PDM_PCIBUSREGRC_VERSION defines the current version. */
980 uint32_t u32Version;
981 /** The PCI bus number (from ring-3 registration). */
982 uint32_t iBus;
983 /**
984 * Set the IRQ for a PCI device.
985 *
986 * @param pDevIns Device instance of the PCI Bus.
987 * @param pPciDev The PCI device structure.
988 * @param iIrq IRQ number to set.
989 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
990 * @param uTagSrc The IRQ tag and source (for tracing).
991 * @remarks Caller enters the PDM critical section.
992 */
993 DECLRCCALLBACKMEMBER(void, pfnSetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel, uint32_t uTagSrc));
994 /** Marks the end of the structure with PDM_PCIBUSREGRC_VERSION. */
995 uint32_t u32EndVersion;
996} PDMPCIBUSREGRC;
997/** Pointer to a PCI bus raw-mode registration structure. */
998typedef PDMPCIBUSREGRC *PPDMPCIBUSREGRC;
999/** Current PDMPCIBUSREGRC version number. */
1000#define PDM_PCIBUSREGRC_VERSION PDM_VERSION_MAKE(0xff88, 1, 0)
1001
1002/** PCI bus registration structure for the current context. */
1003typedef CTX_SUFF(PDMPCIBUSREG) PDMPCIBUSREGCC;
1004/** Pointer to a PCI bus registration structure for the current context. */
1005typedef CTX_SUFF(PPDMPCIBUSREG) PPDMPCIBUSREGCC;
1006/** PCI bus registration structure version for the current context. */
1007#define PDM_PCIBUSREGCC_VERSION CTX_MID(PDM_PCIBUSREG,_VERSION)
1008
1009
1010/**
1011 * PCI Bus RC helpers.
1012 */
1013typedef struct PDMPCIHLPRC
1014{
1015 /** Structure version. PDM_PCIHLPRC_VERSION defines the current version. */
1016 uint32_t u32Version;
1017
1018 /**
1019 * Set an ISA IRQ.
1020 *
1021 * @param pDevIns PCI device instance.
1022 * @param iIrq IRQ number to set.
1023 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1024 * @param uTagSrc The IRQ tag and source (for tracing).
1025 * @thread EMT only.
1026 */
1027 DECLRCCALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
1028
1029 /**
1030 * Set an I/O-APIC IRQ.
1031 *
1032 * @param pDevIns PCI device instance.
1033 * @param iIrq IRQ number to set.
1034 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1035 * @param uTagSrc The IRQ tag and source (for tracing).
1036 * @thread EMT only.
1037 */
1038 DECLRCCALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
1039
1040 /**
1041 * Send an MSI.
1042 *
1043 * @param pDevIns PCI device instance.
1044 * @param GCPhys Physical address MSI request was written.
1045 * @param uValue Value written.
1046 * @param uTagSrc The IRQ tag and source (for tracing).
1047 * @thread EMT only.
1048 */
1049 DECLRCCALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue, uint32_t uTagSrc));
1050
1051
1052 /**
1053 * Acquires the PDM lock.
1054 *
1055 * @returns VINF_SUCCESS on success.
1056 * @returns rc if we failed to acquire the lock.
1057 * @param pDevIns The PCI device instance.
1058 * @param rc What to return if we fail to acquire the lock.
1059 */
1060 DECLRCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1061
1062 /**
1063 * Releases the PDM lock.
1064 *
1065 * @param pDevIns The PCI device instance.
1066 */
1067 DECLRCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1068
1069 /**
1070 * Gets a bus by it's PDM ordinal (typically the parent bus).
1071 *
1072 * @returns Pointer to the device instance of the bus.
1073 * @param pDevIns The PCI bus device instance.
1074 * @param idxPdmBus The PDM ordinal value of the bus to get.
1075 */
1076 DECLRCCALLBACKMEMBER(PPDMDEVINS, pfnGetBusByNo,(PPDMDEVINS pDevIns, uint32_t idxPdmBus));
1077
1078 /** Just a safety precaution. */
1079 uint32_t u32TheEnd;
1080} PDMPCIHLPRC;
1081/** Pointer to PCI helpers. */
1082typedef RCPTRTYPE(PDMPCIHLPRC *) PPDMPCIHLPRC;
1083/** Pointer to const PCI helpers. */
1084typedef RCPTRTYPE(const PDMPCIHLPRC *) PCPDMPCIHLPRC;
1085
1086/** Current PDMPCIHLPRC version number. */
1087#define PDM_PCIHLPRC_VERSION PDM_VERSION_MAKE(0xfffd, 3, 0)
1088
1089
1090/**
1091 * PCI Bus R0 helpers.
1092 */
1093typedef struct PDMPCIHLPR0
1094{
1095 /** Structure version. PDM_PCIHLPR0_VERSION defines the current version. */
1096 uint32_t u32Version;
1097
1098 /**
1099 * Set an ISA IRQ.
1100 *
1101 * @param pDevIns PCI device instance.
1102 * @param iIrq IRQ number to set.
1103 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1104 * @param uTagSrc The IRQ tag and source (for tracing).
1105 * @thread EMT only.
1106 */
1107 DECLR0CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
1108
1109 /**
1110 * Set an I/O-APIC IRQ.
1111 *
1112 * @param pDevIns PCI device instance.
1113 * @param iIrq IRQ number to set.
1114 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1115 * @param uTagSrc The IRQ tag and source (for tracing).
1116 * @thread EMT only.
1117 */
1118 DECLR0CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
1119
1120 /**
1121 * Send an MSI.
1122 *
1123 * @param pDevIns PCI device instance.
1124 * @param GCPhys Physical address MSI request was written.
1125 * @param uValue Value written.
1126 * @param uTagSrc The IRQ tag and source (for tracing).
1127 * @thread EMT only.
1128 */
1129 DECLR0CALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue, uint32_t uTagSrc));
1130
1131 /**
1132 * Acquires the PDM lock.
1133 *
1134 * @returns VINF_SUCCESS on success.
1135 * @returns rc if we failed to acquire the lock.
1136 * @param pDevIns The PCI device instance.
1137 * @param rc What to return if we fail to acquire the lock.
1138 */
1139 DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1140
1141 /**
1142 * Releases the PDM lock.
1143 *
1144 * @param pDevIns The PCI device instance.
1145 */
1146 DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1147
1148 /**
1149 * Gets a bus by it's PDM ordinal (typically the parent bus).
1150 *
1151 * @returns Pointer to the device instance of the bus.
1152 * @param pDevIns The PCI bus device instance.
1153 * @param idxPdmBus The PDM ordinal value of the bus to get.
1154 */
1155 DECLR0CALLBACKMEMBER(PPDMDEVINS, pfnGetBusByNo,(PPDMDEVINS pDevIns, uint32_t idxPdmBus));
1156
1157 /** Just a safety precaution. */
1158 uint32_t u32TheEnd;
1159} PDMPCIHLPR0;
1160/** Pointer to PCI helpers. */
1161typedef R0PTRTYPE(PDMPCIHLPR0 *) PPDMPCIHLPR0;
1162/** Pointer to const PCI helpers. */
1163typedef R0PTRTYPE(const PDMPCIHLPR0 *) PCPDMPCIHLPR0;
1164
1165/** Current PDMPCIHLPR0 version number. */
1166#define PDM_PCIHLPR0_VERSION PDM_VERSION_MAKE(0xfffc, 4, 0)
1167
1168/**
1169 * PCI device helpers.
1170 */
1171typedef struct PDMPCIHLPR3
1172{
1173 /** Structure version. PDM_PCIHLPR3_VERSION defines the current version. */
1174 uint32_t u32Version;
1175
1176 /**
1177 * Set an ISA IRQ.
1178 *
1179 * @param pDevIns The PCI device instance.
1180 * @param iIrq IRQ number to set.
1181 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1182 * @param uTagSrc The IRQ tag and source (for tracing).
1183 */
1184 DECLR3CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
1185
1186 /**
1187 * Set an I/O-APIC IRQ.
1188 *
1189 * @param pDevIns The PCI device instance.
1190 * @param iIrq IRQ number to set.
1191 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1192 * @param uTagSrc The IRQ tag and source (for tracing).
1193 */
1194 DECLR3CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
1195
1196 /**
1197 * Send an MSI.
1198 *
1199 * @param pDevIns PCI device instance.
1200 * @param GCPhys Physical address MSI request was written.
1201 * @param uValue Value written.
1202 * @param uTagSrc The IRQ tag and source (for tracing).
1203 */
1204 DECLR3CALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue, uint32_t uTagSrc));
1205
1206 /**
1207 * Checks if the given address is an MMIO2 or pre-registered MMIO base address.
1208 *
1209 * @returns true/false accordingly.
1210 * @param pDevIns The PCI device instance.
1211 * @param pOwner The owner of the memory, optional.
1212 * @param GCPhys The address to check.
1213 * @sa PGMR3PhysMMIOExIsBase
1214 */
1215 DECLR3CALLBACKMEMBER(bool, pfnIsMMIOExBase,(PPDMDEVINS pDevIns, PPDMDEVINS pOwner, RTGCPHYS GCPhys));
1216
1217 /**
1218 * Acquires the PDM lock.
1219 *
1220 * @returns VINF_SUCCESS on success.
1221 * @returns Fatal error on failure.
1222 * @param pDevIns The PCI device instance.
1223 * @param rc Dummy for making the interface identical to the RC and R0 versions.
1224 */
1225 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1226
1227 /**
1228 * Releases the PDM lock.
1229 *
1230 * @param pDevIns The PCI device instance.
1231 */
1232 DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1233
1234 /**
1235 * Gets a bus by it's PDM ordinal (typically the parent bus).
1236 *
1237 * @returns Pointer to the device instance of the bus.
1238 * @param pDevIns The PCI bus device instance.
1239 * @param idxPdmBus The PDM ordinal value of the bus to get.
1240 */
1241 DECLR3CALLBACKMEMBER(PPDMDEVINS, pfnGetBusByNo,(PPDMDEVINS pDevIns, uint32_t idxPdmBus));
1242
1243 /** Just a safety precaution. */
1244 uint32_t u32TheEnd;
1245} PDMPCIHLPR3;
1246/** Pointer to PCI helpers. */
1247typedef R3PTRTYPE(PDMPCIHLPR3 *) PPDMPCIHLPR3;
1248/** Pointer to const PCI helpers. */
1249typedef R3PTRTYPE(const PDMPCIHLPR3 *) PCPDMPCIHLPR3;
1250
1251/** Current PDMPCIHLPR3 version number. */
1252#define PDM_PCIHLPR3_VERSION PDM_VERSION_MAKE(0xfffb, 4, 0)
1253
1254
1255/**
1256 * Programmable Interrupt Controller registration structure (all contexts).
1257 */
1258typedef struct PDMPICREG
1259{
1260 /** Structure version number. PDM_PICREG_VERSION defines the current version. */
1261 uint32_t u32Version;
1262
1263 /**
1264 * Set the an IRQ.
1265 *
1266 * @param pDevIns Device instance of the PIC.
1267 * @param iIrq IRQ number to set.
1268 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1269 * @param uTagSrc The IRQ tag and source (for tracing).
1270 * @remarks Caller enters the PDM critical section.
1271 */
1272 DECLCALLBACKMEMBER(void, pfnSetIrq)(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc);
1273
1274 /**
1275 * Get a pending interrupt.
1276 *
1277 * @returns Pending interrupt number.
1278 * @param pDevIns Device instance of the PIC.
1279 * @param puTagSrc Where to return the IRQ tag and source.
1280 * @remarks Caller enters the PDM critical section.
1281 */
1282 DECLCALLBACKMEMBER(int, pfnGetInterrupt)(PPDMDEVINS pDevIns, uint32_t *puTagSrc);
1283
1284 /** Just a safety precaution. */
1285 uint32_t u32TheEnd;
1286} PDMPICREG;
1287/** Pointer to a PIC registration structure. */
1288typedef PDMPICREG *PPDMPICREG;
1289
1290/** Current PDMPICREG version number. */
1291#define PDM_PICREG_VERSION PDM_VERSION_MAKE(0xfffa, 3, 0)
1292
1293/**
1294 * PIC helpers, same in all contexts.
1295 */
1296typedef struct PDMPICHLP
1297{
1298 /** Structure version. PDM_PICHLP_VERSION defines the current version. */
1299 uint32_t u32Version;
1300
1301 /**
1302 * Set the interrupt force action flag.
1303 *
1304 * @param pDevIns Device instance of the PIC.
1305 */
1306 DECLCALLBACKMEMBER(void, pfnSetInterruptFF)(PPDMDEVINS pDevIns);
1307
1308 /**
1309 * Clear the interrupt force action flag.
1310 *
1311 * @param pDevIns Device instance of the PIC.
1312 */
1313 DECLCALLBACKMEMBER(void, pfnClearInterruptFF)(PPDMDEVINS pDevIns);
1314
1315 /**
1316 * Acquires the PDM lock.
1317 *
1318 * @returns VINF_SUCCESS on success.
1319 * @returns rc if we failed to acquire the lock.
1320 * @param pDevIns The PIC device instance.
1321 * @param rc What to return if we fail to acquire the lock.
1322 */
1323 DECLCALLBACKMEMBER(int, pfnLock)(PPDMDEVINS pDevIns, int rc);
1324
1325 /**
1326 * Releases the PDM lock.
1327 *
1328 * @param pDevIns The PIC device instance.
1329 */
1330 DECLCALLBACKMEMBER(void, pfnUnlock)(PPDMDEVINS pDevIns);
1331
1332 /** Just a safety precaution. */
1333 uint32_t u32TheEnd;
1334} PDMPICHLP;
1335/** Pointer to PIC helpers. */
1336typedef PDMPICHLP *PPDMPICHLP;
1337/** Pointer to const PIC helpers. */
1338typedef const PDMPICHLP *PCPDMPICHLP;
1339
1340/** Current PDMPICHLP version number. */
1341#define PDM_PICHLP_VERSION PDM_VERSION_MAKE(0xfff9, 3, 0)
1342
1343
1344/**
1345 * Firmware registration structure.
1346 */
1347typedef struct PDMFWREG
1348{
1349 /** Struct version+magic number (PDM_FWREG_VERSION). */
1350 uint32_t u32Version;
1351
1352 /**
1353 * Checks whether this is a hard or soft reset.
1354 *
1355 * The current definition of soft reset is what the PC BIOS does when CMOS[0xF]
1356 * is 5, 9 or 0xA.
1357 *
1358 * @returns true if hard reset, false if soft.
1359 * @param pDevIns Device instance of the firmware.
1360 * @param fFlags PDMRESET_F_XXX passed to the PDMDevHlpVMReset API.
1361 */
1362 DECLR3CALLBACKMEMBER(bool, pfnIsHardReset,(PPDMDEVINS pDevIns, uint32_t fFlags));
1363
1364 /** Just a safety precaution. */
1365 uint32_t u32TheEnd;
1366} PDMFWREG;
1367/** Pointer to a FW registration structure. */
1368typedef PDMFWREG *PPDMFWREG;
1369/** Pointer to a const FW registration structure. */
1370typedef PDMFWREG const *PCPDMFWREG;
1371
1372/** Current PDMFWREG version number. */
1373#define PDM_FWREG_VERSION PDM_VERSION_MAKE(0xffdd, 1, 0)
1374
1375/**
1376 * Firmware R3 helpers.
1377 */
1378typedef struct PDMFWHLPR3
1379{
1380 /** Structure version. PDM_FWHLP_VERSION defines the current version. */
1381 uint32_t u32Version;
1382
1383 /** Just a safety precaution. */
1384 uint32_t u32TheEnd;
1385} PDMFWHLPR3;
1386
1387/** Pointer to FW R3 helpers. */
1388typedef R3PTRTYPE(PDMFWHLPR3 *) PPDMFWHLPR3;
1389/** Pointer to const FW R3 helpers. */
1390typedef R3PTRTYPE(const PDMFWHLPR3 *) PCPDMFWHLPR3;
1391
1392/** Current PDMFWHLPR3 version number. */
1393#define PDM_FWHLPR3_VERSION PDM_VERSION_MAKE(0xffdb, 1, 0)
1394
1395
1396/**
1397 * APIC mode argument for apicR3SetCpuIdFeatureLevel.
1398 *
1399 * Also used in saved-states, CFGM don't change existing values.
1400 */
1401typedef enum PDMAPICMODE
1402{
1403 /** Invalid 0 entry. */
1404 PDMAPICMODE_INVALID = 0,
1405 /** No APIC. */
1406 PDMAPICMODE_NONE,
1407 /** Standard APIC (X86_CPUID_FEATURE_EDX_APIC). */
1408 PDMAPICMODE_APIC,
1409 /** Intel X2APIC (X86_CPUID_FEATURE_ECX_X2APIC). */
1410 PDMAPICMODE_X2APIC,
1411 /** The usual 32-bit paranoia. */
1412 PDMAPICMODE_32BIT_HACK = 0x7fffffff
1413} PDMAPICMODE;
1414
1415/**
1416 * APIC irq argument for pfnSetInterruptFF and pfnClearInterruptFF.
1417 */
1418typedef enum PDMAPICIRQ
1419{
1420 /** Invalid 0 entry. */
1421 PDMAPICIRQ_INVALID = 0,
1422 /** Normal hardware interrupt. */
1423 PDMAPICIRQ_HARDWARE,
1424 /** NMI. */
1425 PDMAPICIRQ_NMI,
1426 /** SMI. */
1427 PDMAPICIRQ_SMI,
1428 /** ExtINT (HW interrupt via PIC). */
1429 PDMAPICIRQ_EXTINT,
1430 /** Interrupt arrived, needs to be updated to the IRR. */
1431 PDMAPICIRQ_UPDATE_PENDING,
1432 /** The usual 32-bit paranoia. */
1433 PDMAPICIRQ_32BIT_HACK = 0x7fffffff
1434} PDMAPICIRQ;
1435
1436
1437/**
1438 * I/O APIC registration structure (all contexts).
1439 */
1440typedef struct PDMIOAPICREG
1441{
1442 /** Struct version+magic number (PDM_IOAPICREG_VERSION). */
1443 uint32_t u32Version;
1444
1445 /**
1446 * Set an IRQ.
1447 *
1448 * @param pDevIns Device instance of the I/O APIC.
1449 * @param iIrq IRQ number to set.
1450 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1451 * @param uTagSrc The IRQ tag and source (for tracing).
1452 *
1453 * @remarks Caller enters the PDM critical section
1454 * Actually, as per 2018-07-21 this isn't true (bird).
1455 */
1456 DECLCALLBACKMEMBER(void, pfnSetIrq)(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc);
1457
1458 /**
1459 * Send a MSI.
1460 *
1461 * @param pDevIns Device instance of the I/O APIC.
1462 * @param GCPhys Request address.
1463 * @param uValue Request value.
1464 * @param uTagSrc The IRQ tag and source (for tracing).
1465 *
1466 * @remarks Caller enters the PDM critical section
1467 * Actually, as per 2018-07-21 this isn't true (bird).
1468 */
1469 DECLCALLBACKMEMBER(void, pfnSendMsi)(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue, uint32_t uTagSrc);
1470
1471 /**
1472 * Set the EOI for an interrupt vector.
1473 *
1474 * @returns Strict VBox status code - only the following informational status codes:
1475 * @retval VINF_IOM_R3_MMIO_WRITE if the I/O APIC lock is contenteded and we're in R0 or RC.
1476 * @retval VINF_SUCCESS
1477 *
1478 * @param pDevIns Device instance of the I/O APIC.
1479 * @param u8Vector The vector.
1480 *
1481 * @remarks Caller enters the PDM critical section
1482 * Actually, as per 2018-07-21 this isn't true (bird).
1483 */
1484 DECLCALLBACKMEMBER(VBOXSTRICTRC, pfnSetEoi)(PPDMDEVINS pDevIns, uint8_t u8Vector);
1485
1486 /** Just a safety precaution. */
1487 uint32_t u32TheEnd;
1488} PDMIOAPICREG;
1489/** Pointer to an APIC registration structure. */
1490typedef PDMIOAPICREG *PPDMIOAPICREG;
1491
1492/** Current PDMAPICREG version number. */
1493#define PDM_IOAPICREG_VERSION PDM_VERSION_MAKE(0xfff2, 6, 0)
1494
1495
1496/**
1497 * IOAPIC helpers, same in all contexts.
1498 */
1499typedef struct PDMIOAPICHLP
1500{
1501 /** Structure version. PDM_IOAPICHLP_VERSION defines the current version. */
1502 uint32_t u32Version;
1503
1504 /**
1505 * Private interface between the IOAPIC and APIC.
1506 *
1507 * @returns status code.
1508 * @param pDevIns Device instance of the IOAPIC.
1509 * @param u8Dest See APIC implementation.
1510 * @param u8DestMode See APIC implementation.
1511 * @param u8DeliveryMode See APIC implementation.
1512 * @param uVector See APIC implementation.
1513 * @param u8Polarity See APIC implementation.
1514 * @param u8TriggerMode See APIC implementation.
1515 * @param uTagSrc The IRQ tag and source (for tracing).
1516 *
1517 * @sa APICBusDeliver()
1518 */
1519 DECLCALLBACKMEMBER(int, pfnApicBusDeliver)(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
1520 uint8_t uVector, uint8_t u8Polarity, uint8_t u8TriggerMode, uint32_t uTagSrc);
1521
1522 /**
1523 * Acquires the PDM lock.
1524 *
1525 * @returns VINF_SUCCESS on success.
1526 * @returns rc if we failed to acquire the lock.
1527 * @param pDevIns The IOAPIC device instance.
1528 * @param rc What to return if we fail to acquire the lock.
1529 */
1530 DECLCALLBACKMEMBER(int, pfnLock)(PPDMDEVINS pDevIns, int rc);
1531
1532 /**
1533 * Releases the PDM lock.
1534 *
1535 * @param pDevIns The IOAPIC device instance.
1536 */
1537 DECLCALLBACKMEMBER(void, pfnUnlock)(PPDMDEVINS pDevIns);
1538
1539 /** Just a safety precaution. */
1540 uint32_t u32TheEnd;
1541} PDMIOAPICHLP;
1542/** Pointer to IOAPIC helpers. */
1543typedef PDMIOAPICHLP * PPDMIOAPICHLP;
1544/** Pointer to const IOAPIC helpers. */
1545typedef const PDMIOAPICHLP * PCPDMIOAPICHLP;
1546
1547/** Current PDMIOAPICHLP version number. */
1548#define PDM_IOAPICHLP_VERSION PDM_VERSION_MAKE(0xfff0, 2, 0)
1549
1550
1551/**
1552 * HPET registration structure.
1553 */
1554typedef struct PDMHPETREG
1555{
1556 /** Struct version+magic number (PDM_HPETREG_VERSION). */
1557 uint32_t u32Version;
1558} PDMHPETREG;
1559/** Pointer to an HPET registration structure. */
1560typedef PDMHPETREG *PPDMHPETREG;
1561
1562/** Current PDMHPETREG version number. */
1563#define PDM_HPETREG_VERSION PDM_VERSION_MAKE(0xffe2, 1, 0)
1564
1565/**
1566 * HPET RC helpers.
1567 *
1568 * @remarks Keep this around in case HPET will need PDM interaction in again RC
1569 * at some later point.
1570 */
1571typedef struct PDMHPETHLPRC
1572{
1573 /** Structure version. PDM_HPETHLPRC_VERSION defines the current version. */
1574 uint32_t u32Version;
1575
1576 /** Just a safety precaution. */
1577 uint32_t u32TheEnd;
1578} PDMHPETHLPRC;
1579
1580/** Pointer to HPET RC helpers. */
1581typedef RCPTRTYPE(PDMHPETHLPRC *) PPDMHPETHLPRC;
1582/** Pointer to const HPET RC helpers. */
1583typedef RCPTRTYPE(const PDMHPETHLPRC *) PCPDMHPETHLPRC;
1584
1585/** Current PDMHPETHLPRC version number. */
1586#define PDM_HPETHLPRC_VERSION PDM_VERSION_MAKE(0xffee, 2, 0)
1587
1588
1589/**
1590 * HPET R0 helpers.
1591 *
1592 * @remarks Keep this around in case HPET will need PDM interaction in again R0
1593 * at some later point.
1594 */
1595typedef struct PDMHPETHLPR0
1596{
1597 /** Structure version. PDM_HPETHLPR0_VERSION defines the current version. */
1598 uint32_t u32Version;
1599
1600 /** Just a safety precaution. */
1601 uint32_t u32TheEnd;
1602} PDMHPETHLPR0;
1603
1604/** Pointer to HPET R0 helpers. */
1605typedef R0PTRTYPE(PDMHPETHLPR0 *) PPDMHPETHLPR0;
1606/** Pointer to const HPET R0 helpers. */
1607typedef R0PTRTYPE(const PDMHPETHLPR0 *) PCPDMHPETHLPR0;
1608
1609/** Current PDMHPETHLPR0 version number. */
1610#define PDM_HPETHLPR0_VERSION PDM_VERSION_MAKE(0xffed, 2, 0)
1611
1612/**
1613 * HPET R3 helpers.
1614 */
1615typedef struct PDMHPETHLPR3
1616{
1617 /** Structure version. PDM_HPETHLP_VERSION defines the current version. */
1618 uint32_t u32Version;
1619
1620 /**
1621 * Set legacy mode on PIT and RTC.
1622 *
1623 * @returns VINF_SUCCESS on success.
1624 * @returns rc if we failed to set legacy mode.
1625 * @param pDevIns Device instance of the HPET.
1626 * @param fActivated Whether legacy mode is activated or deactivated.
1627 */
1628 DECLR3CALLBACKMEMBER(int, pfnSetLegacyMode,(PPDMDEVINS pDevIns, bool fActivated));
1629
1630
1631 /**
1632 * Set IRQ, bypassing ISA bus override rules.
1633 *
1634 * @returns VINF_SUCCESS on success.
1635 * @returns rc if we failed to set legacy mode.
1636 * @param pDevIns Device instance of the HPET.
1637 * @param iIrq IRQ number to set.
1638 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1639 */
1640 DECLR3CALLBACKMEMBER(int, pfnSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
1641
1642 /** Just a safety precaution. */
1643 uint32_t u32TheEnd;
1644} PDMHPETHLPR3;
1645
1646/** Pointer to HPET R3 helpers. */
1647typedef R3PTRTYPE(PDMHPETHLPR3 *) PPDMHPETHLPR3;
1648/** Pointer to const HPET R3 helpers. */
1649typedef R3PTRTYPE(const PDMHPETHLPR3 *) PCPDMHPETHLPR3;
1650
1651/** Current PDMHPETHLPR3 version number. */
1652#define PDM_HPETHLPR3_VERSION PDM_VERSION_MAKE(0xffec, 3, 0)
1653
1654
1655/**
1656 * Raw PCI device registration structure.
1657 */
1658typedef struct PDMPCIRAWREG
1659{
1660 /** Struct version+magic number (PDM_PCIRAWREG_VERSION). */
1661 uint32_t u32Version;
1662 /** Just a safety precaution. */
1663 uint32_t u32TheEnd;
1664} PDMPCIRAWREG;
1665/** Pointer to a raw PCI registration structure. */
1666typedef PDMPCIRAWREG *PPDMPCIRAWREG;
1667
1668/** Current PDMPCIRAWREG version number. */
1669#define PDM_PCIRAWREG_VERSION PDM_VERSION_MAKE(0xffe1, 1, 0)
1670
1671/**
1672 * Raw PCI device raw-mode context helpers.
1673 */
1674typedef struct PDMPCIRAWHLPRC
1675{
1676 /** Structure version and magic number (PDM_PCIRAWHLPRC_VERSION). */
1677 uint32_t u32Version;
1678 /** Just a safety precaution. */
1679 uint32_t u32TheEnd;
1680} PDMPCIRAWHLPRC;
1681/** Pointer to a raw PCI deviec raw-mode context helper structure. */
1682typedef RCPTRTYPE(PDMPCIRAWHLPRC *) PPDMPCIRAWHLPRC;
1683/** Pointer to a const raw PCI deviec raw-mode context helper structure. */
1684typedef RCPTRTYPE(const PDMPCIRAWHLPRC *) PCPDMPCIRAWHLPRC;
1685
1686/** Current PDMPCIRAWHLPRC version number. */
1687#define PDM_PCIRAWHLPRC_VERSION PDM_VERSION_MAKE(0xffe0, 1, 0)
1688
1689/**
1690 * Raw PCI device ring-0 context helpers.
1691 */
1692typedef struct PDMPCIRAWHLPR0
1693{
1694 /** Structure version and magic number (PDM_PCIRAWHLPR0_VERSION). */
1695 uint32_t u32Version;
1696 /** Just a safety precaution. */
1697 uint32_t u32TheEnd;
1698} PDMPCIRAWHLPR0;
1699/** Pointer to a raw PCI deviec ring-0 context helper structure. */
1700typedef R0PTRTYPE(PDMPCIRAWHLPR0 *) PPDMPCIRAWHLPR0;
1701/** Pointer to a const raw PCI deviec ring-0 context helper structure. */
1702typedef R0PTRTYPE(const PDMPCIRAWHLPR0 *) PCPDMPCIRAWHLPR0;
1703
1704/** Current PDMPCIRAWHLPR0 version number. */
1705#define PDM_PCIRAWHLPR0_VERSION PDM_VERSION_MAKE(0xffdf, 1, 0)
1706
1707
1708/**
1709 * Raw PCI device ring-3 context helpers.
1710 */
1711typedef struct PDMPCIRAWHLPR3
1712{
1713 /** Undefined structure version and magic number. */
1714 uint32_t u32Version;
1715
1716 /**
1717 * Gets the address of the RC raw PCI device helpers.
1718 *
1719 * This should be called at both construction and relocation time to obtain
1720 * the correct address of the RC helpers.
1721 *
1722 * @returns RC pointer to the raw PCI device helpers.
1723 * @param pDevIns Device instance of the raw PCI device.
1724 */
1725 DECLR3CALLBACKMEMBER(PCPDMPCIRAWHLPRC, pfnGetRCHelpers,(PPDMDEVINS pDevIns));
1726
1727 /**
1728 * Gets the address of the R0 raw PCI device helpers.
1729 *
1730 * This should be called at both construction and relocation time to obtain
1731 * the correct address of the R0 helpers.
1732 *
1733 * @returns R0 pointer to the raw PCI device helpers.
1734 * @param pDevIns Device instance of the raw PCI device.
1735 */
1736 DECLR3CALLBACKMEMBER(PCPDMPCIRAWHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
1737
1738 /** Just a safety precaution. */
1739 uint32_t u32TheEnd;
1740} PDMPCIRAWHLPR3;
1741/** Pointer to raw PCI R3 helpers. */
1742typedef R3PTRTYPE(PDMPCIRAWHLPR3 *) PPDMPCIRAWHLPR3;
1743/** Pointer to const raw PCI R3 helpers. */
1744typedef R3PTRTYPE(const PDMPCIRAWHLPR3 *) PCPDMPCIRAWHLPR3;
1745
1746/** Current PDMPCIRAWHLPR3 version number. */
1747#define PDM_PCIRAWHLPR3_VERSION PDM_VERSION_MAKE(0xffde, 1, 0)
1748
1749
1750#ifdef IN_RING3
1751
1752/**
1753 * DMA Transfer Handler.
1754 *
1755 * @returns Number of bytes transferred.
1756 * @param pDevIns Device instance of the DMA.
1757 * @param pvUser User pointer.
1758 * @param uChannel Channel number.
1759 * @param off DMA position.
1760 * @param cb Block size.
1761 * @remarks The device lock is not taken, however, the DMA device lock is held.
1762 */
1763typedef DECLCALLBACK(uint32_t) FNDMATRANSFERHANDLER(PPDMDEVINS pDevIns, void *pvUser, unsigned uChannel, uint32_t off, uint32_t cb);
1764/** Pointer to a FNDMATRANSFERHANDLER(). */
1765typedef FNDMATRANSFERHANDLER *PFNDMATRANSFERHANDLER;
1766
1767/**
1768 * DMA Controller registration structure.
1769 */
1770typedef struct PDMDMAREG
1771{
1772 /** Structure version number. PDM_DMACREG_VERSION defines the current version. */
1773 uint32_t u32Version;
1774
1775 /**
1776 * Execute pending transfers.
1777 *
1778 * @returns A more work indiciator. I.e. 'true' if there is more to be done, and 'false' if all is done.
1779 * @param pDevIns Device instance of the DMAC.
1780 * @remarks No locks held, called on EMT(0) as a form of serialization.
1781 */
1782 DECLR3CALLBACKMEMBER(bool, pfnRun,(PPDMDEVINS pDevIns));
1783
1784 /**
1785 * Register transfer function for DMA channel.
1786 *
1787 * @param pDevIns Device instance of the DMAC.
1788 * @param uChannel Channel number.
1789 * @param pfnTransferHandler Device specific transfer function.
1790 * @param pvUser User pointer to be passed to the callback.
1791 * @remarks No locks held, called on an EMT.
1792 */
1793 DECLR3CALLBACKMEMBER(void, pfnRegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
1794
1795 /**
1796 * Read memory
1797 *
1798 * @returns Number of bytes read.
1799 * @param pDevIns Device instance of the DMAC.
1800 * @param uChannel Channel number.
1801 * @param pvBuffer Pointer to target buffer.
1802 * @param off DMA position.
1803 * @param cbBlock Block size.
1804 * @remarks No locks held, called on an EMT.
1805 */
1806 DECLR3CALLBACKMEMBER(uint32_t, pfnReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock));
1807
1808 /**
1809 * Write memory
1810 *
1811 * @returns Number of bytes written.
1812 * @param pDevIns Device instance of the DMAC.
1813 * @param uChannel Channel number.
1814 * @param pvBuffer Memory to write.
1815 * @param off DMA position.
1816 * @param cbBlock Block size.
1817 * @remarks No locks held, called on an EMT.
1818 */
1819 DECLR3CALLBACKMEMBER(uint32_t, pfnWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock));
1820
1821 /**
1822 * Set the DREQ line.
1823 *
1824 * @param pDevIns Device instance of the DMAC.
1825 * @param uChannel Channel number.
1826 * @param uLevel Level of the line.
1827 * @remarks No locks held, called on an EMT.
1828 */
1829 DECLR3CALLBACKMEMBER(void, pfnSetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
1830
1831 /**
1832 * Get channel mode
1833 *
1834 * @returns Channel mode.
1835 * @param pDevIns Device instance of the DMAC.
1836 * @param uChannel Channel number.
1837 * @remarks No locks held, called on an EMT.
1838 */
1839 DECLR3CALLBACKMEMBER(uint8_t, pfnGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
1840
1841} PDMDMACREG;
1842/** Pointer to a DMAC registration structure. */
1843typedef PDMDMACREG *PPDMDMACREG;
1844
1845/** Current PDMDMACREG version number. */
1846#define PDM_DMACREG_VERSION PDM_VERSION_MAKE(0xffeb, 1, 0)
1847
1848
1849/**
1850 * DMA Controller device helpers.
1851 */
1852typedef struct PDMDMACHLP
1853{
1854 /** Structure version. PDM_DMACHLP_VERSION defines the current version. */
1855 uint32_t u32Version;
1856
1857 /* to-be-defined */
1858
1859} PDMDMACHLP;
1860/** Pointer to DMAC helpers. */
1861typedef PDMDMACHLP *PPDMDMACHLP;
1862/** Pointer to const DMAC helpers. */
1863typedef const PDMDMACHLP *PCPDMDMACHLP;
1864
1865/** Current PDMDMACHLP version number. */
1866#define PDM_DMACHLP_VERSION PDM_VERSION_MAKE(0xffea, 1, 0)
1867
1868#endif /* IN_RING3 */
1869
1870
1871
1872/**
1873 * RTC registration structure.
1874 */
1875typedef struct PDMRTCREG
1876{
1877 /** Structure version number. PDM_RTCREG_VERSION defines the current version. */
1878 uint32_t u32Version;
1879 uint32_t u32Alignment; /**< structure size alignment. */
1880
1881 /**
1882 * Write to a CMOS register and update the checksum if necessary.
1883 *
1884 * @returns VBox status code.
1885 * @param pDevIns Device instance of the RTC.
1886 * @param iReg The CMOS register index.
1887 * @param u8Value The CMOS register value.
1888 * @remarks Caller enters the device critical section.
1889 */
1890 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
1891
1892 /**
1893 * Read a CMOS register.
1894 *
1895 * @returns VBox status code.
1896 * @param pDevIns Device instance of the RTC.
1897 * @param iReg The CMOS register index.
1898 * @param pu8Value Where to store the CMOS register value.
1899 * @remarks Caller enters the device critical section.
1900 */
1901 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
1902
1903} PDMRTCREG;
1904/** Pointer to a RTC registration structure. */
1905typedef PDMRTCREG *PPDMRTCREG;
1906/** Pointer to a const RTC registration structure. */
1907typedef const PDMRTCREG *PCPDMRTCREG;
1908
1909/** Current PDMRTCREG version number. */
1910#define PDM_RTCREG_VERSION PDM_VERSION_MAKE(0xffe9, 2, 0)
1911
1912
1913/**
1914 * RTC device helpers.
1915 */
1916typedef struct PDMRTCHLP
1917{
1918 /** Structure version. PDM_RTCHLP_VERSION defines the current version. */
1919 uint32_t u32Version;
1920
1921 /* to-be-defined */
1922
1923} PDMRTCHLP;
1924/** Pointer to RTC helpers. */
1925typedef PDMRTCHLP *PPDMRTCHLP;
1926/** Pointer to const RTC helpers. */
1927typedef const PDMRTCHLP *PCPDMRTCHLP;
1928
1929/** Current PDMRTCHLP version number. */
1930#define PDM_RTCHLP_VERSION PDM_VERSION_MAKE(0xffe8, 1, 0)
1931
1932
1933
1934/** @name Flags for PCI I/O region registration
1935 * @{ */
1936/** No handle is passed. */
1937#define PDMPCIDEV_IORGN_F_NO_HANDLE UINT32_C(0x00000000)
1938/** An I/O port handle is passed. */
1939#define PDMPCIDEV_IORGN_F_IOPORT_HANDLE UINT32_C(0x00000001)
1940/** An MMIO range handle is passed. */
1941#define PDMPCIDEV_IORGN_F_MMIO_HANDLE UINT32_C(0x00000002)
1942/** An MMIO2 handle is passed. */
1943#define PDMPCIDEV_IORGN_F_MMIO2_HANDLE UINT32_C(0x00000003)
1944/** Handle type mask. */
1945#define PDMPCIDEV_IORGN_F_HANDLE_MASK UINT32_C(0x00000003)
1946/** New-style (mostly wrt callbacks). */
1947#define PDMPCIDEV_IORGN_F_NEW_STYLE UINT32_C(0x00000004)
1948/** Mask of valid flags. */
1949#define PDMPCIDEV_IORGN_F_VALID_MASK UINT32_C(0x00000007)
1950/** @} */
1951
1952
1953#ifdef IN_RING3
1954
1955/** @name Special values for PDMDEVHLPR3::pfnPCIRegister parameters.
1956 * @{ */
1957/** Same device number (and bus) as the previous PCI device registered with the PDM device.
1958 * This is handy when registering multiple PCI device functions and the device
1959 * number is left up to the PCI bus. In order to facilitate one PDM device
1960 * instance for each PCI function, this searches earlier PDM device
1961 * instances as well. */
1962# define PDMPCIDEVREG_DEV_NO_SAME_AS_PREV UINT8_C(0xfd)
1963/** Use the first unused device number (all functions must be unused). */
1964# define PDMPCIDEVREG_DEV_NO_FIRST_UNUSED UINT8_C(0xfe)
1965/** Use the first unused device function. */
1966# define PDMPCIDEVREG_FUN_NO_FIRST_UNUSED UINT8_C(0xff)
1967
1968/** The device and function numbers are not mandatory, just suggestions. */
1969# define PDMPCIDEVREG_F_NOT_MANDATORY_NO RT_BIT_32(0)
1970/** Registering a PCI bridge device. */
1971# define PDMPCIDEVREG_F_PCI_BRIDGE RT_BIT_32(1)
1972/** Valid flag mask. */
1973# define PDMPCIDEVREG_F_VALID_MASK UINT32_C(0x00000003)
1974/** @} */
1975
1976/** Current PDMDEVHLPR3 version number. */
1977#define PDM_DEVHLPR3_VERSION PDM_VERSION_MAKE_PP(0xffe7, 36, 0)
1978
1979/**
1980 * PDM Device API.
1981 */
1982typedef struct PDMDEVHLPR3
1983{
1984 /** Structure version. PDM_DEVHLPR3_VERSION defines the current version. */
1985 uint32_t u32Version;
1986
1987 /** @name I/O ports
1988 * @{ */
1989 /**
1990 * Creates a range of I/O ports for a device.
1991 *
1992 * The I/O port range must be mapped in a separately call. Any ring-0 and
1993 * raw-mode context callback handlers needs to be set up in the respective
1994 * contexts.
1995 *
1996 * @returns VBox status.
1997 * @param pDevIns The device instance to register the ports with.
1998 * @param cPorts Number of ports to register.
1999 * @param fFlags IOM_IOPORT_F_XXX.
2000 * @param pPciDev The PCI device the range is associated with, if
2001 * applicable.
2002 * @param iPciRegion The PCI device region in the high 16-bit word and
2003 * sub-region in the low 16-bit word. UINT32_MAX if NA.
2004 * @param pfnOut Pointer to function which is gonna handle OUT
2005 * operations. Optional.
2006 * @param pfnIn Pointer to function which is gonna handle IN operations.
2007 * Optional.
2008 * @param pfnOutStr Pointer to function which is gonna handle string OUT
2009 * operations. Optional.
2010 * @param pfnInStr Pointer to function which is gonna handle string IN
2011 * operations. Optional.
2012 * @param pvUser User argument to pass to the callbacks.
2013 * @param pszDesc Pointer to description string. This must not be freed.
2014 * @param paExtDescs Extended per-port descriptions, optional. Partial range
2015 * coverage is allowed. This must not be freed.
2016 * @param phIoPorts Where to return the I/O port range handle.
2017 *
2018 * @remarks Caller enters the device critical section prior to invoking the
2019 * registered callback methods.
2020 *
2021 * @sa PDMDevHlpIoPortSetUpContext, PDMDevHlpIoPortMap,
2022 * PDMDevHlpIoPortUnmap.
2023 */
2024 DECLR3CALLBACKMEMBER(int, pfnIoPortCreateEx,(PPDMDEVINS pDevIns, RTIOPORT cPorts, uint32_t fFlags, PPDMPCIDEV pPciDev,
2025 uint32_t iPciRegion, PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
2026 PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, RTR3PTR pvUser,
2027 const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts));
2028
2029 /**
2030 * Maps an I/O port range.
2031 *
2032 * @returns VBox status.
2033 * @param pDevIns The device instance to register the ports with.
2034 * @param hIoPorts The I/O port range handle.
2035 * @param Port Where to map the range.
2036 * @sa PDMDevHlpIoPortUnmap, PDMDevHlpIoPortSetUpContext,
2037 * PDMDevHlpIoPortCreate, PDMDevHlpIoPortCreateEx.
2038 */
2039 DECLR3CALLBACKMEMBER(int, pfnIoPortMap,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts, RTIOPORT Port));
2040
2041 /**
2042 * Unmaps an I/O port range.
2043 *
2044 * @returns VBox status.
2045 * @param pDevIns The device instance to register the ports with.
2046 * @param hIoPorts The I/O port range handle.
2047 * @sa PDMDevHlpIoPortMap, PDMDevHlpIoPortSetUpContext,
2048 * PDMDevHlpIoPortCreate, PDMDevHlpIoPortCreateEx.
2049 */
2050 DECLR3CALLBACKMEMBER(int, pfnIoPortUnmap,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts));
2051
2052 /**
2053 * Gets the mapping address of the I/O port range @a hIoPorts.
2054 *
2055 * @returns Mapping address (0..65535) or UINT32_MAX if not mapped (or invalid
2056 * parameters).
2057 * @param pDevIns The device instance to register the ports with.
2058 * @param hIoPorts The I/O port range handle.
2059 */
2060 DECLR3CALLBACKMEMBER(uint32_t, pfnIoPortGetMappingAddress,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts));
2061 /** @} */
2062
2063 /**
2064 * Register a number of I/O ports with a device.
2065 *
2066 * These callbacks are of course for the host context (HC).
2067 * Register HC handlers before guest context (GC) handlers! There must be a
2068 * HC handler for every GC handler!
2069 *
2070 * @returns VBox status.
2071 * @param pDevIns The device instance to register the ports with.
2072 * @param Port First port number in the range.
2073 * @param cPorts Number of ports to register.
2074 * @param pvUser User argument.
2075 * @param pfnOut Pointer to function which is gonna handle OUT operations.
2076 * @param pfnIn Pointer to function which is gonna handle IN operations.
2077 * @param pfnOutStr Pointer to function which is gonna handle string OUT operations.
2078 * @param pfnInStr Pointer to function which is gonna handle string IN operations.
2079 * @param pszDesc Pointer to description string. This must not be freed.
2080 * @remarks Caller enters the device critical section prior to invoking the
2081 * registered callback methods.
2082 * @deprecated
2083 */
2084 DECLR3CALLBACKMEMBER(int, pfnIOPortRegister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTHCPTR pvUser,
2085 PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,
2086 PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc));
2087
2088 /**
2089 * Register a number of I/O ports with a device for RC.
2090 *
2091 * These callbacks are for the raw-mode context (RC). Register ring-3 context
2092 * (R3) handlers before raw-mode context handlers! There must be a R3 handler
2093 * for every RC handler!
2094 *
2095 * @returns VBox status.
2096 * @param pDevIns The device instance to register the ports with
2097 * and which RC module to resolve the names
2098 * against.
2099 * @param Port First port number in the range.
2100 * @param cPorts Number of ports to register.
2101 * @param pvUser User argument.
2102 * @param pszOut Name of the RC function which is gonna handle OUT operations.
2103 * @param pszIn Name of the RC function which is gonna handle IN operations.
2104 * @param pszOutStr Name of the RC function which is gonna handle string OUT operations.
2105 * @param pszInStr Name of the RC function which is gonna handle string IN operations.
2106 * @param pszDesc Pointer to description string. This must not be freed.
2107 * @remarks Caller enters the device critical section prior to invoking the
2108 * registered callback methods.
2109 * @deprecated
2110 */
2111 DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterRC,(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTRCPTR pvUser,
2112 const char *pszOut, const char *pszIn,
2113 const char *pszOutStr, const char *pszInStr, const char *pszDesc));
2114
2115 /**
2116 * Register a number of I/O ports with a device.
2117 *
2118 * These callbacks are of course for the ring-0 host context (R0).
2119 * Register R3 (HC) handlers before R0 (R0) handlers! There must be a R3 (HC) handler for every R0 handler!
2120 *
2121 * @returns VBox status.
2122 * @param pDevIns The device instance to register the ports with.
2123 * @param Port First port number in the range.
2124 * @param cPorts Number of ports to register.
2125 * @param pvUser User argument. (if pointer, then it must be in locked memory!)
2126 * @param pszOut Name of the R0 function which is gonna handle OUT operations.
2127 * @param pszIn Name of the R0 function which is gonna handle IN operations.
2128 * @param pszOutStr Name of the R0 function which is gonna handle string OUT operations.
2129 * @param pszInStr Name of the R0 function which is gonna handle string IN operations.
2130 * @param pszDesc Pointer to description string. This must not be freed.
2131 * @remarks Caller enters the device critical section prior to invoking the
2132 * registered callback methods.
2133 * @deprecated
2134 */
2135 DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterR0,(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTR0PTR pvUser,
2136 const char *pszOut, const char *pszIn,
2137 const char *pszOutStr, const char *pszInStr, const char *pszDesc));
2138
2139 /**
2140 * Deregister I/O ports.
2141 *
2142 * This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.
2143 *
2144 * @returns VBox status.
2145 * @param pDevIns The device instance owning the ports.
2146 * @param Port First port number in the range.
2147 * @param cPorts Number of ports to deregister.
2148 */
2149 DECLR3CALLBACKMEMBER(int, pfnIOPortDeregister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts));
2150
2151 /** @name MMIO
2152 * @{ */
2153 /**
2154 * Creates a memory mapped I/O (MMIO) region for a device.
2155 *
2156 * The MMIO region must be mapped in a separately call. Any ring-0 and
2157 * raw-mode context callback handlers needs to be set up in the respective
2158 * contexts.
2159 *
2160 * @returns VBox status.
2161 * @param pDevIns The device instance to register the ports with.
2162 * @param cbRegion The size of the region in bytes.
2163 * @param fFlags Flags, IOMMMIO_FLAGS_XXX.
2164 * @param pPciDev The PCI device the range is associated with, if
2165 * applicable.
2166 * @param iPciRegion The PCI device region in the high 16-bit word and
2167 * sub-region in the low 16-bit word. UINT32_MAX if NA.
2168 * @param pfnWrite Pointer to function which is gonna handle Write
2169 * operations.
2170 * @param pfnRead Pointer to function which is gonna handle Read
2171 * operations.
2172 * @param pfnFill Pointer to function which is gonna handle Fill/memset
2173 * operations. (optional)
2174 * @param pvUser User argument to pass to the callbacks.
2175 * @param pszDesc Pointer to description string. This must not be freed.
2176 * @param phRegion Where to return the MMIO region handle.
2177 *
2178 * @remarks Caller enters the device critical section prior to invoking the
2179 * registered callback methods.
2180 *
2181 * @sa PDMDevHlpMmioSetUpContext, PDMDevHlpMmioMap, PDMDevHlpMmioUnmap.
2182 */
2183 DECLR3CALLBACKMEMBER(int, pfnMmioCreateEx,(PPDMDEVINS pDevIns, RTGCPHYS cbRegion,
2184 uint32_t fFlags, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
2185 PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill,
2186 void *pvUser, const char *pszDesc, PIOMMMIOHANDLE phRegion));
2187
2188 /**
2189 * Maps a memory mapped I/O (MMIO) region (into the guest physical address space).
2190 *
2191 * @returns VBox status.
2192 * @param pDevIns The device instance the region is associated with.
2193 * @param hRegion The MMIO region handle.
2194 * @param GCPhys Where to map the region.
2195 * @note An MMIO range may overlap with base memory if a lot of RAM is
2196 * configured for the VM, in which case we'll drop the base memory
2197 * pages. Presently we will make no attempt to preserve anything that
2198 * happens to be present in the base memory that is replaced, this is
2199 * technically incorrect but it's just not worth the effort to do
2200 * right, at least not at this point.
2201 * @sa PDMDevHlpMmioUnmap, PDMDevHlpMmioCreate, PDMDevHlpMmioCreateEx,
2202 * PDMDevHlpMmioSetUpContext
2203 */
2204 DECLR3CALLBACKMEMBER(int, pfnMmioMap,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS GCPhys));
2205
2206 /**
2207 * Unmaps a memory mapped I/O (MMIO) region.
2208 *
2209 * @returns VBox status.
2210 * @param pDevIns The device instance the region is associated with.
2211 * @param hRegion The MMIO region handle.
2212 * @sa PDMDevHlpMmioMap, PDMDevHlpMmioCreate, PDMDevHlpMmioCreateEx,
2213 * PDMDevHlpMmioSetUpContext
2214 */
2215 DECLR3CALLBACKMEMBER(int, pfnMmioUnmap,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion));
2216
2217 /**
2218 * Reduces the length of a MMIO range.
2219 *
2220 * This is for implementations of PDMPCIDEV::pfnRegionLoadChangeHookR3 and will
2221 * only work during saved state restore. It will not call the PCI bus code, as
2222 * that is expected to restore the saved resource configuration.
2223 *
2224 * It just adjusts the mapping length of the region so that when pfnMmioMap is
2225 * called it will only map @a cbRegion bytes and not the value set during
2226 * registration.
2227 *
2228 * @return VBox status code.
2229 * @param pDevIns The device owning the range.
2230 * @param hRegion The MMIO region handle.
2231 * @param cbRegion The new size, must be smaller.
2232 */
2233 DECLR3CALLBACKMEMBER(int, pfnMmioReduce,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS cbRegion));
2234
2235 /**
2236 * Gets the mapping address of the MMIO region @a hRegion.
2237 *
2238 * @returns Mapping address, NIL_RTGCPHYS if not mapped (or invalid parameters).
2239 * @param pDevIns The device instance to register the ports with.
2240 * @param hRegion The MMIO region handle.
2241 */
2242 DECLR3CALLBACKMEMBER(RTGCPHYS, pfnMmioGetMappingAddress,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion));
2243 /** @} */
2244
2245 /**
2246 * Register a Memory Mapped I/O (MMIO) region.
2247 *
2248 * These callbacks are of course for the ring-3 context (R3). Register HC
2249 * handlers before raw-mode context (RC) and ring-0 context (R0) handlers! There
2250 * must be a R3 handler for every RC and R0 handler!
2251 *
2252 * @returns VBox status.
2253 * @param pDevIns The device instance to register the MMIO with.
2254 * @param GCPhysStart First physical address in the range.
2255 * @param cbRange The size of the range (in bytes).
2256 * @param pvUser User argument.
2257 * @param pfnWrite Pointer to function which is gonna handle Write operations.
2258 * @param pfnRead Pointer to function which is gonna handle Read operations.
2259 * @param pfnFill Pointer to function which is gonna handle Fill/memset operations. (optional)
2260 * @param fFlags Flags, IOMMMIO_FLAGS_XXX.
2261 * @param pszDesc Pointer to description string. This must not be freed.
2262 * @remarks Caller enters the device critical section prior to invoking the
2263 * registered callback methods.
2264 * @deprecated
2265 */
2266 DECLR3CALLBACKMEMBER(int, pfnMMIORegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTGCPHYS cbRange, RTHCPTR pvUser,
2267 PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, PFNIOMMMIOFILL pfnFill,
2268 uint32_t fFlags, const char *pszDesc));
2269
2270 /**
2271 * Register a Memory Mapped I/O (MMIO) region for RC.
2272 *
2273 * These callbacks are for the raw-mode context (RC). Register ring-3 context
2274 * (R3) handlers before guest context handlers! There must be a R3 handler for
2275 * every RC handler!
2276 *
2277 * @returns VBox status.
2278 * @param pDevIns The device instance to register the MMIO with.
2279 * @param GCPhysStart First physical address in the range.
2280 * @param cbRange The size of the range (in bytes).
2281 * @param pvUser User argument.
2282 * @param pszWrite Name of the RC function which is gonna handle Write operations.
2283 * @param pszRead Name of the RC function which is gonna handle Read operations.
2284 * @param pszFill Name of the RC function which is gonna handle Fill/memset operations. (optional)
2285 * @remarks Caller enters the device critical section prior to invoking the
2286 * registered callback methods.
2287 * @deprecated
2288 */
2289 DECLR3CALLBACKMEMBER(int, pfnMMIORegisterRC,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTGCPHYS cbRange, RTRCPTR pvUser,
2290 const char *pszWrite, const char *pszRead, const char *pszFill));
2291
2292 /**
2293 * Register a Memory Mapped I/O (MMIO) region for R0.
2294 *
2295 * These callbacks are for the ring-0 host context (R0). Register ring-3
2296 * constext (R3) handlers before R0 handlers! There must be a R3 handler for
2297 * every R0 handler!
2298 *
2299 * @returns VBox status.
2300 * @param pDevIns The device instance to register the MMIO with.
2301 * @param GCPhysStart First physical address in the range.
2302 * @param cbRange The size of the range (in bytes).
2303 * @param pvUser User argument. (if pointer, then it must be in locked memory!)
2304 * @param pszWrite Name of the RC function which is gonna handle Write operations.
2305 * @param pszRead Name of the RC function which is gonna handle Read operations.
2306 * @param pszFill Name of the RC function which is gonna handle Fill/memset operations. (optional)
2307 * @remarks Caller enters the device critical section prior to invoking the
2308 * registered callback methods.
2309 * @deprecated
2310 */
2311 DECLR3CALLBACKMEMBER(int, pfnMMIORegisterR0,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTGCPHYS cbRange, RTR0PTR pvUser,
2312 const char *pszWrite, const char *pszRead, const char *pszFill));
2313
2314 /**
2315 * Deregister a Memory Mapped I/O (MMIO) region.
2316 *
2317 * This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.
2318 *
2319 * @returns VBox status.
2320 * @param pDevIns The device instance owning the MMIO region(s).
2321 * @param GCPhysStart First physical address in the range.
2322 * @param cbRange The size of the range (in bytes).
2323 * @deprecated
2324 */
2325 DECLR3CALLBACKMEMBER(int, pfnMMIODeregister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTGCPHYS cbRange));
2326
2327 /** @name MMIO2
2328 * @{ */
2329 /**
2330 * Creates a MMIO2 region.
2331 *
2332 * As mentioned elsewhere, MMIO2 is just RAM spelled differently. It's RAM
2333 * associated with a device. It is also non-shared memory with a permanent
2334 * ring-3 mapping and page backing (presently).
2335 *
2336 * @returns VBox status.
2337 * @param pDevIns The device instance.
2338 * @param pPciDev The PCI device the region is associated with, or
2339 * NULL if no PCI device association.
2340 * @param iPciRegion The region number. Use the PCI region number as
2341 * this must be known to the PCI bus device too. If
2342 * it's not associated with the PCI device, then
2343 * any number up to UINT8_MAX is fine.
2344 * @param cbRegion The size (in bytes) of the region.
2345 * @param fFlags Reserved for future use, must be zero.
2346 * @param pszDesc Pointer to description string. This must not be
2347 * freed.
2348 * @param ppvMapping Where to store the address of the ring-3 mapping
2349 * of the memory.
2350 * @param phRegion Where to return the MMIO2 region handle.
2351 *
2352 * @thread EMT(0)
2353 */
2354 DECLR3CALLBACKMEMBER(int, pfnMmio2Create,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iPciRegion, RTGCPHYS cbRegion,
2355 uint32_t fFlags, const char *pszDesc, void **ppvMapping, PPGMMMIO2HANDLE phRegion));
2356
2357 /**
2358 * Destroys a MMIO2 region, unmapping it and freeing the memory.
2359 *
2360 * Any physical access handlers registered for the region must be deregistered
2361 * before calling this function.
2362 *
2363 * @returns VBox status code.
2364 * @param pDevIns The device instance.
2365 * @param hRegion The MMIO2 region handle.
2366 * @thread EMT.
2367 */
2368 DECLR3CALLBACKMEMBER(int, pfnMmio2Destroy,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion));
2369
2370 /**
2371 * Maps a MMIO2 region (into the guest physical address space).
2372 *
2373 * @returns VBox status.
2374 * @param pDevIns The device instance the region is associated with.
2375 * @param hRegion The MMIO2 region handle.
2376 * @param GCPhys Where to map the region.
2377 * @note A MMIO2 region overlap with base memory if a lot of RAM is
2378 * configured for the VM, in which case we'll drop the base memory
2379 * pages. Presently we will make no attempt to preserve anything that
2380 * happens to be present in the base memory that is replaced, this is
2381 * technically incorrect but it's just not worth the effort to do
2382 * right, at least not at this point.
2383 * @sa PDMDevHlpMmio2Unmap, PDMDevHlpMmio2Create, PDMDevHlpMmio2SetUpContext
2384 */
2385 DECLR3CALLBACKMEMBER(int, pfnMmio2Map,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS GCPhys));
2386
2387 /**
2388 * Unmaps a MMIO2 region.
2389 *
2390 * @returns VBox status.
2391 * @param pDevIns The device instance the region is associated with.
2392 * @param hRegion The MMIO2 region handle.
2393 * @sa PDMDevHlpMmio2Map, PDMDevHlpMmio2Create, PDMDevHlpMmio2SetUpContext
2394 */
2395 DECLR3CALLBACKMEMBER(int, pfnMmio2Unmap,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion));
2396
2397 /**
2398 * Reduces the length of a MMIO range.
2399 *
2400 * This is for implementations of PDMPCIDEV::pfnRegionLoadChangeHookR3 and will
2401 * only work during saved state restore. It will not call the PCI bus code, as
2402 * that is expected to restore the saved resource configuration.
2403 *
2404 * It just adjusts the mapping length of the region so that when pfnMmioMap is
2405 * called it will only map @a cbRegion bytes and not the value set during
2406 * registration.
2407 *
2408 * @return VBox status code.
2409 * @param pDevIns The device owning the range.
2410 * @param hRegion The MMIO2 region handle.
2411 * @param cbRegion The new size, must be smaller.
2412 */
2413 DECLR3CALLBACKMEMBER(int, pfnMmio2Reduce,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS cbRegion));
2414
2415 /**
2416 * Gets the mapping address of the MMIO region @a hRegion.
2417 *
2418 * @returns Mapping address, NIL_RTGCPHYS if not mapped (or invalid parameters).
2419 * @param pDevIns The device instance to register the ports with.
2420 * @param hRegion The MMIO2 region handle.
2421 */
2422 DECLR3CALLBACKMEMBER(RTGCPHYS, pfnMmio2GetMappingAddress,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion));
2423
2424 /**
2425 * Changes the number of an MMIO2 or pre-registered MMIO region.
2426 *
2427 * This should only be used to deal with saved state problems, so there is no
2428 * convenience inline wrapper for this method.
2429 *
2430 * @returns VBox status code.
2431 * @param pDevIns The device instance.
2432 * @param hRegion The MMIO2 region handle.
2433 * @param iNewRegion The new region index.
2434 *
2435 * @sa @bugref{9359}
2436 */
2437 DECLR3CALLBACKMEMBER(int, pfnMmio2ChangeRegionNo,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, uint32_t iNewRegion));
2438 /** @} */
2439
2440 /**
2441 * Allocate and register a MMIO2 region.
2442 *
2443 * As mentioned elsewhere, MMIO2 is just RAM spelled differently. It's RAM
2444 * associated with a device. It is also non-shared memory with a permanent
2445 * ring-3 mapping and page backing (presently).
2446 *
2447 * @returns VBox status.
2448 * @param pDevIns The device instance.
2449 * @param pPciDev The PCI device the region is associated with, or
2450 * NULL if no PCI device association.
2451 * @param iRegion The region number. Use the PCI region number as
2452 * this must be known to the PCI bus device too. If
2453 * it's not associated with the PCI device, then
2454 * any number up to UINT8_MAX is fine.
2455 * @param cb The size (in bytes) of the region.
2456 * @param fFlags Reserved for future use, must be zero.
2457 * @param ppv Where to store the address of the ring-3 mapping
2458 * of the memory.
2459 * @param pszDesc Pointer to description string. This must not be
2460 * freed.
2461 * @thread EMT.
2462 * @deprecated
2463 */
2464 DECLR3CALLBACKMEMBER(int, pfnMMIO2Register,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS cb,
2465 uint32_t fFlags, void **ppv, const char *pszDesc));
2466
2467 /**
2468 * Deregisters and frees a MMIO or MMIO2 region.
2469 *
2470 * Any physical (and virtual) access handlers registered for the region must
2471 * be deregistered before calling this function (MMIO2 only).
2472 *
2473 * @returns VBox status code.
2474 * @param pDevIns The device instance.
2475 * @param pPciDev The PCI device the region is associated with, or
2476 * NULL if not associated with any.
2477 * @param iRegion The region number used during registration.
2478 * @thread EMT.
2479 * @deprecated
2480 */
2481 DECLR3CALLBACKMEMBER(int, pfnMMIOExDeregister,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion));
2482
2483 /**
2484 * Maps a MMIO or MMIO2 region into the physical memory space.
2485 *
2486 * A MMIO2 range or a pre-registered MMIO range may overlap with base memory if
2487 * a lot of RAM is configured for the VM, in which case we'll drop the base
2488 * memory pages. Presently we will make no attempt to preserve anything that
2489 * happens to be present in the base memory that is replaced, this is of course
2490 * incorrect but it's too much effort.
2491 *
2492 * @returns VBox status code.
2493 * @param pDevIns The device instance.
2494 * @param pPciDev The PCI device the region is associated with, or
2495 * NULL if not associated with any.
2496 * @param iRegion The region number used during registration.
2497 * @param GCPhys The physical address to map it at.
2498 * @thread EMT.
2499 * @deprecated for MMIO
2500 */
2501 DECLR3CALLBACKMEMBER(int, pfnMMIOExMap,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS GCPhys));
2502
2503 /**
2504 * Unmaps a MMIO or MMIO2 region previously mapped using pfnMMIOExMap.
2505 *
2506 * @returns VBox status code.
2507 * @param pDevIns The device instance.
2508 * @param pPciDev The PCI device the region is associated with, or
2509 * NULL if not associated with any.
2510 * @param iRegion The region number used during registration.
2511 * @param GCPhys The physical address it's currently mapped at.
2512 * @thread EMT.
2513 * @deprecated for MMIO
2514 */
2515 DECLR3CALLBACKMEMBER(int, pfnMMIOExUnmap,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS GCPhys));
2516
2517 /**
2518 * Reduces the length of a MMIO2 or pre-registered MMIO range.
2519 *
2520 * This is for implementations of PDMPCIDEV::pfnRegionLoadChangeHookR3 and will
2521 * only work during saved state restore. It will not call the PCI bus code, as
2522 * that is expected to restore the saved resource configuration.
2523 *
2524 * It just adjusts the mapping length of the region so that when pfnMMIOExMap is
2525 * called it will only map @a cbRegion bytes and not the value set during
2526 * registration.
2527 *
2528 * @return VBox status code.
2529 * @param pDevIns The device owning the range.
2530 * @param pPciDev The PCI device the region is associated with, or
2531 * NULL if not associated with any.
2532 * @param iRegion The region.
2533 * @param cbRegion The new size, must be smaller.
2534 */
2535 DECLR3CALLBACKMEMBER(int, pfnMMIOExReduce,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS cbRegion));
2536
2537 /**
2538 * Maps a portion of an MMIO2 region into the hypervisor region.
2539 *
2540 * Callers of this API must never deregister the MMIO2 region before the
2541 * VM is powered off.
2542 *
2543 * @return VBox status code.
2544 * @param pDevIns The device owning the MMIO2 memory.
2545 * @param pPciDev The PCI device the region is associated with, or
2546 * NULL if not associated with any.
2547 * @param iRegion The region.
2548 * @param off The offset into the region. Will be rounded down
2549 * to closest page boundary.
2550 * @param cb The number of bytes to map. Will be rounded up
2551 * to the closest page boundary.
2552 * @param pszDesc Mapping description.
2553 * @param pRCPtr Where to store the RC address.
2554 */
2555 DECLR3CALLBACKMEMBER(int, pfnMMHyperMapMMIO2,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS off,
2556 RTGCPHYS cb, const char *pszDesc, PRTRCPTR pRCPtr));
2557
2558 /**
2559 * Maps a portion of an MMIO2 region into kernel space (host).
2560 *
2561 * The kernel mapping will become invalid when the MMIO2 memory is deregistered
2562 * or the VM is terminated.
2563 *
2564 * @return VBox status code.
2565 * @param pDevIns The device owning the MMIO2 memory.
2566 * @param pPciDev The PCI device the region is associated with, or
2567 * NULL if not associated with any.
2568 * @param iRegion The region.
2569 * @param off The offset into the region. Must be page
2570 * aligned.
2571 * @param cb The number of bytes to map. Must be page
2572 * aligned.
2573 * @param pszDesc Mapping description.
2574 * @param pR0Ptr Where to store the R0 address.
2575 */
2576 DECLR3CALLBACKMEMBER(int, pfnMMIO2MapKernel,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS off,
2577 RTGCPHYS cb, const char *pszDesc, PRTR0PTR pR0Ptr));
2578
2579 /**
2580 * Register a ROM (BIOS) region.
2581 *
2582 * It goes without saying that this is read-only memory. The memory region must be
2583 * in unassigned memory. I.e. from the top of the address space or on the PC in
2584 * the 0xa0000-0xfffff range.
2585 *
2586 * @returns VBox status.
2587 * @param pDevIns The device instance owning the ROM region.
2588 * @param GCPhysStart First physical address in the range.
2589 * Must be page aligned!
2590 * @param cbRange The size of the range (in bytes).
2591 * Must be page aligned!
2592 * @param pvBinary Pointer to the binary data backing the ROM image.
2593 * @param cbBinary The size of the binary pointer. This must
2594 * be equal or smaller than @a cbRange.
2595 * @param fFlags Shadow ROM flags, PGMPHYS_ROM_FLAGS_* in pgm.h.
2596 * @param pszDesc Pointer to description string. This must not be freed.
2597 *
2598 * @remark There is no way to remove the rom, automatically on device cleanup or
2599 * manually from the device yet. At present I doubt we need such features...
2600 */
2601 DECLR3CALLBACKMEMBER(int, pfnROMRegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange,
2602 const void *pvBinary, uint32_t cbBinary, uint32_t fFlags, const char *pszDesc));
2603
2604 /**
2605 * Changes the protection of shadowed ROM mapping.
2606 *
2607 * This is intented for use by the system BIOS, chipset or device in question to
2608 * change the protection of shadowed ROM code after init and on reset.
2609 *
2610 * @param pDevIns The device instance.
2611 * @param GCPhysStart Where the mapping starts.
2612 * @param cbRange The size of the mapping.
2613 * @param enmProt The new protection type.
2614 */
2615 DECLR3CALLBACKMEMBER(int, pfnROMProtectShadow,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, PGMROMPROT enmProt));
2616
2617 /**
2618 * Register a save state data unit.
2619 *
2620 * @returns VBox status.
2621 * @param pDevIns The device instance.
2622 * @param uVersion Data layout version number.
2623 * @param cbGuess The approximate amount of data in the unit.
2624 * Only for progress indicators.
2625 * @param pszBefore Name of data unit which we should be put in
2626 * front of. Optional (NULL).
2627 *
2628 * @param pfnLivePrep Prepare live save callback, optional.
2629 * @param pfnLiveExec Execute live save callback, optional.
2630 * @param pfnLiveVote Vote live save callback, optional.
2631 *
2632 * @param pfnSavePrep Prepare save callback, optional.
2633 * @param pfnSaveExec Execute save callback, optional.
2634 * @param pfnSaveDone Done save callback, optional.
2635 *
2636 * @param pfnLoadPrep Prepare load callback, optional.
2637 * @param pfnLoadExec Execute load callback, optional.
2638 * @param pfnLoadDone Done load callback, optional.
2639 * @remarks Caller enters the device critical section prior to invoking the
2640 * registered callback methods.
2641 */
2642 DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess, const char *pszBefore,
2643 PFNSSMDEVLIVEPREP pfnLivePrep, PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVLIVEVOTE pfnLiveVote,
2644 PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
2645 PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone));
2646
2647 /** @name Exported SSM Functions
2648 * @{ */
2649 DECLR3CALLBACKMEMBER(int, pfnSSMPutStruct,(PSSMHANDLE pSSM, const void *pvStruct, PCSSMFIELD paFields));
2650 DECLR3CALLBACKMEMBER(int, pfnSSMPutStructEx,(PSSMHANDLE pSSM, const void *pvStruct, size_t cbStruct, uint32_t fFlags, PCSSMFIELD paFields, void *pvUser));
2651 DECLR3CALLBACKMEMBER(int, pfnSSMPutBool,(PSSMHANDLE pSSM, bool fBool));
2652 DECLR3CALLBACKMEMBER(int, pfnSSMPutU8,(PSSMHANDLE pSSM, uint8_t u8));
2653 DECLR3CALLBACKMEMBER(int, pfnSSMPutS8,(PSSMHANDLE pSSM, int8_t i8));
2654 DECLR3CALLBACKMEMBER(int, pfnSSMPutU16,(PSSMHANDLE pSSM, uint16_t u16));
2655 DECLR3CALLBACKMEMBER(int, pfnSSMPutS16,(PSSMHANDLE pSSM, int16_t i16));
2656 DECLR3CALLBACKMEMBER(int, pfnSSMPutU32,(PSSMHANDLE pSSM, uint32_t u32));
2657 DECLR3CALLBACKMEMBER(int, pfnSSMPutS32,(PSSMHANDLE pSSM, int32_t i32));
2658 DECLR3CALLBACKMEMBER(int, pfnSSMPutU64,(PSSMHANDLE pSSM, uint64_t u64));
2659 DECLR3CALLBACKMEMBER(int, pfnSSMPutS64,(PSSMHANDLE pSSM, int64_t i64));
2660 DECLR3CALLBACKMEMBER(int, pfnSSMPutU128,(PSSMHANDLE pSSM, uint128_t u128));
2661 DECLR3CALLBACKMEMBER(int, pfnSSMPutS128,(PSSMHANDLE pSSM, int128_t i128));
2662 DECLR3CALLBACKMEMBER(int, pfnSSMPutUInt,(PSSMHANDLE pSSM, RTUINT u));
2663 DECLR3CALLBACKMEMBER(int, pfnSSMPutSInt,(PSSMHANDLE pSSM, RTINT i));
2664 DECLR3CALLBACKMEMBER(int, pfnSSMPutGCUInt,(PSSMHANDLE pSSM, RTGCUINT u));
2665 DECLR3CALLBACKMEMBER(int, pfnSSMPutGCUIntReg,(PSSMHANDLE pSSM, RTGCUINTREG u));
2666 DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPhys32,(PSSMHANDLE pSSM, RTGCPHYS32 GCPhys));
2667 DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPhys64,(PSSMHANDLE pSSM, RTGCPHYS64 GCPhys));
2668 DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPhys,(PSSMHANDLE pSSM, RTGCPHYS GCPhys));
2669 DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPtr,(PSSMHANDLE pSSM, RTGCPTR GCPtr));
2670 DECLR3CALLBACKMEMBER(int, pfnSSMPutGCUIntPtr,(PSSMHANDLE pSSM, RTGCUINTPTR GCPtr));
2671 DECLR3CALLBACKMEMBER(int, pfnSSMPutRCPtr,(PSSMHANDLE pSSM, RTRCPTR RCPtr));
2672 DECLR3CALLBACKMEMBER(int, pfnSSMPutIOPort,(PSSMHANDLE pSSM, RTIOPORT IOPort));
2673 DECLR3CALLBACKMEMBER(int, pfnSSMPutSel,(PSSMHANDLE pSSM, RTSEL Sel));
2674 DECLR3CALLBACKMEMBER(int, pfnSSMPutMem,(PSSMHANDLE pSSM, const void *pv, size_t cb));
2675 DECLR3CALLBACKMEMBER(int, pfnSSMPutStrZ,(PSSMHANDLE pSSM, const char *psz));
2676 DECLR3CALLBACKMEMBER(int, pfnSSMGetStruct,(PSSMHANDLE pSSM, void *pvStruct, PCSSMFIELD paFields));
2677 DECLR3CALLBACKMEMBER(int, pfnSSMGetStructEx,(PSSMHANDLE pSSM, void *pvStruct, size_t cbStruct, uint32_t fFlags, PCSSMFIELD paFields, void *pvUser));
2678 DECLR3CALLBACKMEMBER(int, pfnSSMGetBool,(PSSMHANDLE pSSM, bool *pfBool));
2679 DECLR3CALLBACKMEMBER(int, pfnSSMGetBoolV,(PSSMHANDLE pSSM, bool volatile *pfBool));
2680 DECLR3CALLBACKMEMBER(int, pfnSSMGetU8,(PSSMHANDLE pSSM, uint8_t *pu8));
2681 DECLR3CALLBACKMEMBER(int, pfnSSMGetU8V,(PSSMHANDLE pSSM, uint8_t volatile *pu8));
2682 DECLR3CALLBACKMEMBER(int, pfnSSMGetS8,(PSSMHANDLE pSSM, int8_t *pi8));
2683 DECLR3CALLBACKMEMBER(int, pfnSSMGetS8V,(PSSMHANDLE pSSM, int8_t volatile *pi8));
2684 DECLR3CALLBACKMEMBER(int, pfnSSMGetU16,(PSSMHANDLE pSSM, uint16_t *pu16));
2685 DECLR3CALLBACKMEMBER(int, pfnSSMGetU16V,(PSSMHANDLE pSSM, uint16_t volatile *pu16));
2686 DECLR3CALLBACKMEMBER(int, pfnSSMGetS16,(PSSMHANDLE pSSM, int16_t *pi16));
2687 DECLR3CALLBACKMEMBER(int, pfnSSMGetS16V,(PSSMHANDLE pSSM, int16_t volatile *pi16));
2688 DECLR3CALLBACKMEMBER(int, pfnSSMGetU32,(PSSMHANDLE pSSM, uint32_t *pu32));
2689 DECLR3CALLBACKMEMBER(int, pfnSSMGetU32V,(PSSMHANDLE pSSM, uint32_t volatile *pu32));
2690 DECLR3CALLBACKMEMBER(int, pfnSSMGetS32,(PSSMHANDLE pSSM, int32_t *pi32));
2691 DECLR3CALLBACKMEMBER(int, pfnSSMGetS32V,(PSSMHANDLE pSSM, int32_t volatile *pi32));
2692 DECLR3CALLBACKMEMBER(int, pfnSSMGetU64,(PSSMHANDLE pSSM, uint64_t *pu64));
2693 DECLR3CALLBACKMEMBER(int, pfnSSMGetU64V,(PSSMHANDLE pSSM, uint64_t volatile *pu64));
2694 DECLR3CALLBACKMEMBER(int, pfnSSMGetS64,(PSSMHANDLE pSSM, int64_t *pi64));
2695 DECLR3CALLBACKMEMBER(int, pfnSSMGetS64V,(PSSMHANDLE pSSM, int64_t volatile *pi64));
2696 DECLR3CALLBACKMEMBER(int, pfnSSMGetU128,(PSSMHANDLE pSSM, uint128_t *pu128));
2697 DECLR3CALLBACKMEMBER(int, pfnSSMGetU128V,(PSSMHANDLE pSSM, uint128_t volatile *pu128));
2698 DECLR3CALLBACKMEMBER(int, pfnSSMGetS128,(PSSMHANDLE pSSM, int128_t *pi128));
2699 DECLR3CALLBACKMEMBER(int, pfnSSMGetS128V,(PSSMHANDLE pSSM, int128_t volatile *pi128));
2700 DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys32,(PSSMHANDLE pSSM, PRTGCPHYS32 pGCPhys));
2701 DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys32V,(PSSMHANDLE pSSM, RTGCPHYS32 volatile *pGCPhys));
2702 DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys64,(PSSMHANDLE pSSM, PRTGCPHYS64 pGCPhys));
2703 DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys64V,(PSSMHANDLE pSSM, RTGCPHYS64 volatile *pGCPhys));
2704 DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys,(PSSMHANDLE pSSM, PRTGCPHYS pGCPhys));
2705 DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhysV,(PSSMHANDLE pSSM, RTGCPHYS volatile *pGCPhys));
2706 DECLR3CALLBACKMEMBER(int, pfnSSMGetUInt,(PSSMHANDLE pSSM, PRTUINT pu));
2707 DECLR3CALLBACKMEMBER(int, pfnSSMGetSInt,(PSSMHANDLE pSSM, PRTINT pi));
2708 DECLR3CALLBACKMEMBER(int, pfnSSMGetGCUInt,(PSSMHANDLE pSSM, PRTGCUINT pu));
2709 DECLR3CALLBACKMEMBER(int, pfnSSMGetGCUIntReg,(PSSMHANDLE pSSM, PRTGCUINTREG pu));
2710 DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPtr,(PSSMHANDLE pSSM, PRTGCPTR pGCPtr));
2711 DECLR3CALLBACKMEMBER(int, pfnSSMGetGCUIntPtr,(PSSMHANDLE pSSM, PRTGCUINTPTR pGCPtr));
2712 DECLR3CALLBACKMEMBER(int, pfnSSMGetRCPtr,(PSSMHANDLE pSSM, PRTRCPTR pRCPtr));
2713 DECLR3CALLBACKMEMBER(int, pfnSSMGetIOPort,(PSSMHANDLE pSSM, PRTIOPORT pIOPort));
2714 DECLR3CALLBACKMEMBER(int, pfnSSMGetSel,(PSSMHANDLE pSSM, PRTSEL pSel));
2715 DECLR3CALLBACKMEMBER(int, pfnSSMGetMem,(PSSMHANDLE pSSM, void *pv, size_t cb));
2716 DECLR3CALLBACKMEMBER(int, pfnSSMGetStrZ,(PSSMHANDLE pSSM, char *psz, size_t cbMax));
2717 DECLR3CALLBACKMEMBER(int, pfnSSMGetStrZEx,(PSSMHANDLE pSSM, char *psz, size_t cbMax, size_t *pcbStr));
2718 DECLR3CALLBACKMEMBER(int, pfnSSMSkip,(PSSMHANDLE pSSM, size_t cb));
2719 DECLR3CALLBACKMEMBER(int, pfnSSMSkipToEndOfUnit,(PSSMHANDLE pSSM));
2720 DECLR3CALLBACKMEMBER(int, pfnSSMSetLoadError,(PSSMHANDLE pSSM, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(6, 7));
2721 DECLR3CALLBACKMEMBER(int, pfnSSMSetLoadErrorV,(PSSMHANDLE pSSM, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
2722 DECLR3CALLBACKMEMBER(int, pfnSSMSetCfgError,(PSSMHANDLE pSSM, RT_SRC_POS_DECL, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6));
2723 DECLR3CALLBACKMEMBER(int, pfnSSMSetCfgErrorV,(PSSMHANDLE pSSM, RT_SRC_POS_DECL, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(5, 0));
2724 DECLR3CALLBACKMEMBER(int, pfnSSMHandleGetStatus,(PSSMHANDLE pSSM));
2725 DECLR3CALLBACKMEMBER(SSMAFTER, pfnSSMHandleGetAfter,(PSSMHANDLE pSSM));
2726 DECLR3CALLBACKMEMBER(bool, pfnSSMHandleIsLiveSave,(PSSMHANDLE pSSM));
2727 DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleMaxDowntime,(PSSMHANDLE pSSM));
2728 DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleHostBits,(PSSMHANDLE pSSM));
2729 DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleRevision,(PSSMHANDLE pSSM));
2730 DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleVersion,(PSSMHANDLE pSSM));
2731 /** @} */
2732
2733 /**
2734 * Creates a timer.
2735 *
2736 * @returns VBox status.
2737 * @param pDevIns The device instance.
2738 * @param enmClock The clock to use on this timer.
2739 * @param pfnCallback Callback function.
2740 * @param pvUser User argument for the callback.
2741 * @param fFlags Flags, see TMTIMER_FLAGS_*.
2742 * @param pszDesc Pointer to description string which must stay around
2743 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
2744 * @param ppTimer Where to store the timer on success.
2745 * @remarks Caller enters the device critical section prior to invoking the
2746 * callback.
2747 */
2748 DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback,
2749 void *pvUser, uint32_t fFlags, const char *pszDesc, PPTMTIMERR3 ppTimer));
2750
2751 /**
2752 * Creates a timer w/ a cross context handle.
2753 *
2754 * @returns VBox status.
2755 * @param pDevIns The device instance.
2756 * @param enmClock The clock to use on this timer.
2757 * @param pfnCallback Callback function.
2758 * @param pvUser User argument for the callback.
2759 * @param fFlags Flags, see TMTIMER_FLAGS_*.
2760 * @param pszDesc Pointer to description string which must stay around
2761 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
2762 * @param phTimer Where to store the timer handle on success.
2763 * @remarks Caller enters the device critical section prior to invoking the
2764 * callback.
2765 */
2766 DECLR3CALLBACKMEMBER(int, pfnTimerCreate,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback,
2767 void *pvUser, uint32_t fFlags, const char *pszDesc, PTMTIMERHANDLE phTimer));
2768
2769 /**
2770 * Translates a timer handle to a pointer.
2771 *
2772 * @returns The time address.
2773 * @param pDevIns The device instance.
2774 * @param hTimer The timer handle.
2775 */
2776 DECLR3CALLBACKMEMBER(PTMTIMERR3, pfnTimerToPtr,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2777
2778 /** @name Timer handle method wrappers
2779 * @{ */
2780 DECLR3CALLBACKMEMBER(uint64_t, pfnTimerFromMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicroSecs));
2781 DECLR3CALLBACKMEMBER(uint64_t, pfnTimerFromMilli,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliSecs));
2782 DECLR3CALLBACKMEMBER(uint64_t, pfnTimerFromNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanoSecs));
2783 DECLR3CALLBACKMEMBER(uint64_t, pfnTimerGet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2784 DECLR3CALLBACKMEMBER(uint64_t, pfnTimerGetFreq,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2785 DECLR3CALLBACKMEMBER(uint64_t, pfnTimerGetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2786 DECLR3CALLBACKMEMBER(bool, pfnTimerIsActive,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2787 DECLR3CALLBACKMEMBER(bool, pfnTimerIsLockOwner,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2788 DECLR3CALLBACKMEMBER(int, pfnTimerLock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, int rcBusy));
2789 DECLR3CALLBACKMEMBER(int, pfnTimerSet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t uExpire));
2790 DECLR3CALLBACKMEMBER(int, pfnTimerSetFrequencyHint,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint32_t uHz));
2791 DECLR3CALLBACKMEMBER(int, pfnTimerSetMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicrosToNext));
2792 DECLR3CALLBACKMEMBER(int, pfnTimerSetMillies,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliesToNext));
2793 DECLR3CALLBACKMEMBER(int, pfnTimerSetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanosToNext));
2794 DECLR3CALLBACKMEMBER(int, pfnTimerSetRelative,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cTicksToNext, uint64_t *pu64Now));
2795 DECLR3CALLBACKMEMBER(int, pfnTimerStop,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2796 DECLR3CALLBACKMEMBER(void, pfnTimerUnlock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2797 DECLR3CALLBACKMEMBER(int, pfnTimerSetCritSect,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect));
2798 DECLR3CALLBACKMEMBER(int, pfnTimerSave,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM));
2799 DECLR3CALLBACKMEMBER(int, pfnTimerLoad,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM));
2800 DECLR3CALLBACKMEMBER(int, pfnTimerDestroy,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2801 /** @sa TMR3TimerSkip */
2802 DECLR3CALLBACKMEMBER(int, pfnTimerSkipLoad,(PSSMHANDLE pSSM, bool *pfActive));
2803 /** @} */
2804
2805 /**
2806 * Get the real world UTC time adjusted for VM lag, user offset and warpdrive.
2807 *
2808 * @returns pTime.
2809 * @param pDevIns The device instance.
2810 * @param pTime Where to store the time.
2811 */
2812 DECLR3CALLBACKMEMBER(PRTTIMESPEC, pfnTMUtcNow,(PPDMDEVINS pDevIns, PRTTIMESPEC pTime));
2813
2814 /** @name Exported CFGM Functions.
2815 * @{ */
2816 DECLR3CALLBACKMEMBER(bool, pfnCFGMExists,( PCFGMNODE pNode, const char *pszName));
2817 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryType,( PCFGMNODE pNode, const char *pszName, PCFGMVALUETYPE penmType));
2818 DECLR3CALLBACKMEMBER(int, pfnCFGMQuerySize,( PCFGMNODE pNode, const char *pszName, size_t *pcb));
2819 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryInteger,( PCFGMNODE pNode, const char *pszName, uint64_t *pu64));
2820 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryIntegerDef,( PCFGMNODE pNode, const char *pszName, uint64_t *pu64, uint64_t u64Def));
2821 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryString,( PCFGMNODE pNode, const char *pszName, char *pszString, size_t cchString));
2822 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryStringDef,( PCFGMNODE pNode, const char *pszName, char *pszString, size_t cchString, const char *pszDef));
2823 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryBytes,( PCFGMNODE pNode, const char *pszName, void *pvData, size_t cbData));
2824 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU64,( PCFGMNODE pNode, const char *pszName, uint64_t *pu64));
2825 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU64Def,( PCFGMNODE pNode, const char *pszName, uint64_t *pu64, uint64_t u64Def));
2826 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS64,( PCFGMNODE pNode, const char *pszName, int64_t *pi64));
2827 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS64Def,( PCFGMNODE pNode, const char *pszName, int64_t *pi64, int64_t i64Def));
2828 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU32,( PCFGMNODE pNode, const char *pszName, uint32_t *pu32));
2829 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU32Def,( PCFGMNODE pNode, const char *pszName, uint32_t *pu32, uint32_t u32Def));
2830 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS32,( PCFGMNODE pNode, const char *pszName, int32_t *pi32));
2831 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS32Def,( PCFGMNODE pNode, const char *pszName, int32_t *pi32, int32_t i32Def));
2832 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU16,( PCFGMNODE pNode, const char *pszName, uint16_t *pu16));
2833 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU16Def,( PCFGMNODE pNode, const char *pszName, uint16_t *pu16, uint16_t u16Def));
2834 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS16,( PCFGMNODE pNode, const char *pszName, int16_t *pi16));
2835 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS16Def,( PCFGMNODE pNode, const char *pszName, int16_t *pi16, int16_t i16Def));
2836 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU8,( PCFGMNODE pNode, const char *pszName, uint8_t *pu8));
2837 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU8Def,( PCFGMNODE pNode, const char *pszName, uint8_t *pu8, uint8_t u8Def));
2838 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS8,( PCFGMNODE pNode, const char *pszName, int8_t *pi8));
2839 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS8Def,( PCFGMNODE pNode, const char *pszName, int8_t *pi8, int8_t i8Def));
2840 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryBool,( PCFGMNODE pNode, const char *pszName, bool *pf));
2841 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryBoolDef,( PCFGMNODE pNode, const char *pszName, bool *pf, bool fDef));
2842 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPort,( PCFGMNODE pNode, const char *pszName, PRTIOPORT pPort));
2843 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPortDef,( PCFGMNODE pNode, const char *pszName, PRTIOPORT pPort, RTIOPORT PortDef));
2844 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryUInt,( PCFGMNODE pNode, const char *pszName, unsigned int *pu));
2845 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryUIntDef,( PCFGMNODE pNode, const char *pszName, unsigned int *pu, unsigned int uDef));
2846 DECLR3CALLBACKMEMBER(int, pfnCFGMQuerySInt,( PCFGMNODE pNode, const char *pszName, signed int *pi));
2847 DECLR3CALLBACKMEMBER(int, pfnCFGMQuerySIntDef,( PCFGMNODE pNode, const char *pszName, signed int *pi, signed int iDef));
2848 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPtr,( PCFGMNODE pNode, const char *pszName, void **ppv));
2849 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPtrDef,( PCFGMNODE pNode, const char *pszName, void **ppv, void *pvDef));
2850 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtr,( PCFGMNODE pNode, const char *pszName, PRTGCPTR pGCPtr));
2851 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrDef,( PCFGMNODE pNode, const char *pszName, PRTGCPTR pGCPtr, RTGCPTR GCPtrDef));
2852 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrU,( PCFGMNODE pNode, const char *pszName, PRTGCUINTPTR pGCPtr));
2853 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrUDef,( PCFGMNODE pNode, const char *pszName, PRTGCUINTPTR pGCPtr, RTGCUINTPTR GCPtrDef));
2854 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrS,( PCFGMNODE pNode, const char *pszName, PRTGCINTPTR pGCPtr));
2855 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrSDef,( PCFGMNODE pNode, const char *pszName, PRTGCINTPTR pGCPtr, RTGCINTPTR GCPtrDef));
2856 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryStringAlloc,( PCFGMNODE pNode, const char *pszName, char **ppszString));
2857 DECLR3CALLBACKMEMBER(int, pfnCFGMQueryStringAllocDef,(PCFGMNODE pNode, const char *pszName, char **ppszString, const char *pszDef));
2858 DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetParent,(PCFGMNODE pNode));
2859 DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetChild,(PCFGMNODE pNode, const char *pszPath));
2860 DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetChildF,(PCFGMNODE pNode, const char *pszPathFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3));
2861 DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetChildFV,(PCFGMNODE pNode, const char *pszPathFormat, va_list Args) RT_IPRT_FORMAT_ATTR(3, 0));
2862 DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetFirstChild,(PCFGMNODE pNode));
2863 DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetNextChild,(PCFGMNODE pCur));
2864 DECLR3CALLBACKMEMBER(int, pfnCFGMGetName,(PCFGMNODE pCur, char *pszName, size_t cchName));
2865 DECLR3CALLBACKMEMBER(size_t, pfnCFGMGetNameLen,(PCFGMNODE pCur));
2866 DECLR3CALLBACKMEMBER(bool, pfnCFGMAreChildrenValid,(PCFGMNODE pNode, const char *pszzValid));
2867 DECLR3CALLBACKMEMBER(PCFGMLEAF, pfnCFGMGetFirstValue,(PCFGMNODE pCur));
2868 DECLR3CALLBACKMEMBER(PCFGMLEAF, pfnCFGMGetNextValue,(PCFGMLEAF pCur));
2869 DECLR3CALLBACKMEMBER(int, pfnCFGMGetValueName,(PCFGMLEAF pCur, char *pszName, size_t cchName));
2870 DECLR3CALLBACKMEMBER(size_t, pfnCFGMGetValueNameLen,(PCFGMLEAF pCur));
2871 DECLR3CALLBACKMEMBER(CFGMVALUETYPE, pfnCFGMGetValueType,(PCFGMLEAF pCur));
2872 DECLR3CALLBACKMEMBER(bool, pfnCFGMAreValuesValid,(PCFGMNODE pNode, const char *pszzValid));
2873 DECLR3CALLBACKMEMBER(int, pfnCFGMValidateConfig,(PCFGMNODE pNode, const char *pszNode,
2874 const char *pszValidValues, const char *pszValidNodes,
2875 const char *pszWho, uint32_t uInstance));
2876 /** @} */
2877
2878 /**
2879 * Read physical memory.
2880 *
2881 * @returns VINF_SUCCESS (for now).
2882 * @param pDevIns The device instance.
2883 * @param GCPhys Physical address start reading from.
2884 * @param pvBuf Where to put the read bits.
2885 * @param cbRead How many bytes to read.
2886 * @thread Any thread, but the call may involve the emulation thread.
2887 */
2888 DECLR3CALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
2889
2890 /**
2891 * Write to physical memory.
2892 *
2893 * @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
2894 * @param pDevIns The device instance.
2895 * @param GCPhys Physical address to write to.
2896 * @param pvBuf What to write.
2897 * @param cbWrite How many bytes to write.
2898 * @thread Any thread, but the call may involve the emulation thread.
2899 */
2900 DECLR3CALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
2901
2902 /**
2903 * Requests the mapping of a guest page into ring-3.
2904 *
2905 * When you're done with the page, call pfnPhysReleasePageMappingLock() ASAP to
2906 * release it.
2907 *
2908 * This API will assume your intention is to write to the page, and will
2909 * therefore replace shared and zero pages. If you do not intend to modify the
2910 * page, use the pfnPhysGCPhys2CCPtrReadOnly() API.
2911 *
2912 * @returns VBox status code.
2913 * @retval VINF_SUCCESS on success.
2914 * @retval VERR_PGM_PHYS_PAGE_RESERVED it it's a valid page but has no physical
2915 * backing or if the page has any active access handlers. The caller
2916 * must fall back on using PGMR3PhysWriteExternal.
2917 * @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if it's not a valid physical address.
2918 *
2919 * @param pDevIns The device instance.
2920 * @param GCPhys The guest physical address of the page that
2921 * should be mapped.
2922 * @param fFlags Flags reserved for future use, MBZ.
2923 * @param ppv Where to store the address corresponding to
2924 * GCPhys.
2925 * @param pLock Where to store the lock information that
2926 * pfnPhysReleasePageMappingLock needs.
2927 *
2928 * @remark Avoid calling this API from within critical sections (other than the
2929 * PGM one) because of the deadlock risk when we have to delegating the
2930 * task to an EMT.
2931 * @thread Any.
2932 */
2933 DECLR3CALLBACKMEMBER(int, pfnPhysGCPhys2CCPtr,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void **ppv,
2934 PPGMPAGEMAPLOCK pLock));
2935
2936 /**
2937 * Requests the mapping of a guest page into ring-3, external threads.
2938 *
2939 * When you're done with the page, call pfnPhysReleasePageMappingLock() ASAP to
2940 * release it.
2941 *
2942 * @returns VBox status code.
2943 * @retval VINF_SUCCESS on success.
2944 * @retval VERR_PGM_PHYS_PAGE_RESERVED it it's a valid page but has no physical
2945 * backing or if the page as an active ALL access handler. The caller
2946 * must fall back on using PGMPhysRead.
2947 * @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if it's not a valid physical address.
2948 *
2949 * @param pDevIns The device instance.
2950 * @param GCPhys The guest physical address of the page that
2951 * should be mapped.
2952 * @param fFlags Flags reserved for future use, MBZ.
2953 * @param ppv Where to store the address corresponding to
2954 * GCPhys.
2955 * @param pLock Where to store the lock information that
2956 * pfnPhysReleasePageMappingLock needs.
2957 *
2958 * @remark Avoid calling this API from within critical sections.
2959 * @thread Any.
2960 */
2961 DECLR3CALLBACKMEMBER(int, pfnPhysGCPhys2CCPtrReadOnly,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags,
2962 void const **ppv, PPGMPAGEMAPLOCK pLock));
2963
2964 /**
2965 * Release the mapping of a guest page.
2966 *
2967 * This is the counter part of pfnPhysGCPhys2CCPtr and
2968 * pfnPhysGCPhys2CCPtrReadOnly.
2969 *
2970 * @param pDevIns The device instance.
2971 * @param pLock The lock structure initialized by the mapping
2972 * function.
2973 */
2974 DECLR3CALLBACKMEMBER(void, pfnPhysReleasePageMappingLock,(PPDMDEVINS pDevIns, PPGMPAGEMAPLOCK pLock));
2975
2976 /**
2977 * Read guest physical memory by virtual address.
2978 *
2979 * @param pDevIns The device instance.
2980 * @param pvDst Where to put the read bits.
2981 * @param GCVirtSrc Guest virtual address to start reading from.
2982 * @param cb How many bytes to read.
2983 * @thread The emulation thread.
2984 */
2985 DECLR3CALLBACKMEMBER(int, pfnPhysReadGCVirt,(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb));
2986
2987 /**
2988 * Write to guest physical memory by virtual address.
2989 *
2990 * @param pDevIns The device instance.
2991 * @param GCVirtDst Guest virtual address to write to.
2992 * @param pvSrc What to write.
2993 * @param cb How many bytes to write.
2994 * @thread The emulation thread.
2995 */
2996 DECLR3CALLBACKMEMBER(int, pfnPhysWriteGCVirt,(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb));
2997
2998 /**
2999 * Convert a guest virtual address to a guest physical address.
3000 *
3001 * @returns VBox status code.
3002 * @param pDevIns The device instance.
3003 * @param GCPtr Guest virtual address.
3004 * @param pGCPhys Where to store the GC physical address
3005 * corresponding to GCPtr.
3006 * @thread The emulation thread.
3007 * @remark Careful with page boundaries.
3008 */
3009 DECLR3CALLBACKMEMBER(int, pfnPhysGCPtr2GCPhys, (PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTGCPHYS pGCPhys));
3010
3011 /**
3012 * Allocate memory which is associated with current VM instance
3013 * and automatically freed on it's destruction.
3014 *
3015 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
3016 * @param pDevIns The device instance.
3017 * @param cb Number of bytes to allocate.
3018 */
3019 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVINS pDevIns, size_t cb));
3020
3021 /**
3022 * Allocate memory which is associated with current VM instance
3023 * and automatically freed on it's destruction. The memory is ZEROed.
3024 *
3025 * @returns Pointer to allocated memory. The memory is *NOT* zero-ed.
3026 * @param pDevIns The device instance.
3027 * @param cb Number of bytes to allocate.
3028 */
3029 DECLR3CALLBACKMEMBER(void *, pfnMMHeapAllocZ,(PPDMDEVINS pDevIns, size_t cb));
3030
3031 /**
3032 * Free memory allocated with pfnMMHeapAlloc() and pfnMMHeapAllocZ().
3033 *
3034 * @param pDevIns The device instance.
3035 * @param pv Pointer to the memory to free.
3036 */
3037 DECLR3CALLBACKMEMBER(void, pfnMMHeapFree,(PPDMDEVINS pDevIns, void *pv));
3038
3039 /**
3040 * Gets the VM state.
3041 *
3042 * @returns VM state.
3043 * @param pDevIns The device instance.
3044 * @thread Any thread (just keep in mind that it's volatile info).
3045 */
3046 DECLR3CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
3047
3048 /**
3049 * Checks if the VM was teleported and hasn't been fully resumed yet.
3050 *
3051 * @returns true / false.
3052 * @param pDevIns The device instance.
3053 * @thread Any thread.
3054 */
3055 DECLR3CALLBACKMEMBER(bool, pfnVMTeleportedAndNotFullyResumedYet,(PPDMDEVINS pDevIns));
3056
3057 /**
3058 * Set the VM error message
3059 *
3060 * @returns rc.
3061 * @param pDevIns The device instance.
3062 * @param rc VBox status code.
3063 * @param SRC_POS Use RT_SRC_POS.
3064 * @param pszFormat Error message format string.
3065 * @param ... Error message arguments.
3066 */
3067 DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
3068 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(6, 7));
3069
3070 /**
3071 * Set the VM error message
3072 *
3073 * @returns rc.
3074 * @param pDevIns The device instance.
3075 * @param rc VBox status code.
3076 * @param SRC_POS Use RT_SRC_POS.
3077 * @param pszFormat Error message format string.
3078 * @param va Error message arguments.
3079 */
3080 DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
3081 const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
3082
3083 /**
3084 * Set the VM runtime error message
3085 *
3086 * @returns VBox status code.
3087 * @param pDevIns The device instance.
3088 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
3089 * @param pszErrorId Error ID string.
3090 * @param pszFormat Error message format string.
3091 * @param ... Error message arguments.
3092 */
3093 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
3094 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5));
3095
3096 /**
3097 * Set the VM runtime error message
3098 *
3099 * @returns VBox status code.
3100 * @param pDevIns The device instance.
3101 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
3102 * @param pszErrorId Error ID string.
3103 * @param pszFormat Error message format string.
3104 * @param va Error message arguments.
3105 */
3106 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
3107 const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0));
3108
3109 /**
3110 * Stops the VM and enters the debugger to look at the guest state.
3111 *
3112 * Use the PDMDeviceDBGFStop() inline function with the RT_SRC_POS macro instead of
3113 * invoking this function directly.
3114 *
3115 * @returns VBox status code which must be passed up to the VMM.
3116 * @param pDevIns The device instance.
3117 * @param pszFile Filename of the assertion location.
3118 * @param iLine The linenumber of the assertion location.
3119 * @param pszFunction Function of the assertion location.
3120 * @param pszFormat Message. (optional)
3121 * @param args Message parameters.
3122 */
3123 DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction,
3124 const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(5, 0));
3125
3126 /**
3127 * Register a info handler with DBGF.
3128 *
3129 * @returns VBox status code.
3130 * @param pDevIns The device instance.
3131 * @param pszName The identifier of the info.
3132 * @param pszDesc The description of the info and any arguments
3133 * the handler may take.
3134 * @param pfnHandler The handler function to be called to display the
3135 * info.
3136 */
3137 DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMDEVINS pDevIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDEV pfnHandler));
3138
3139 /**
3140 * Register a info handler with DBGF, argv style.
3141 *
3142 * @returns VBox status code.
3143 * @param pDevIns The device instance.
3144 * @param pszName The identifier of the info.
3145 * @param pszDesc The description of the info and any arguments
3146 * the handler may take.
3147 * @param pfnHandler The handler function to be called to display the
3148 * info.
3149 */
3150 DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegisterArgv,(PPDMDEVINS pDevIns, const char *pszName, const char *pszDesc, PFNDBGFINFOARGVDEV pfnHandler));
3151
3152 /**
3153 * Registers a set of registers for a device.
3154 *
3155 * The @a pvUser argument of the getter and setter callbacks will be
3156 * @a pDevIns. The register names will be prefixed by the device name followed
3157 * immediately by the instance number.
3158 *
3159 * @returns VBox status code.
3160 * @param pDevIns The device instance.
3161 * @param paRegisters The register descriptors.
3162 *
3163 * @remarks The device critical section is NOT entered prior to working the
3164 * callbacks registered via this helper!
3165 */
3166 DECLR3CALLBACKMEMBER(int, pfnDBGFRegRegister,(PPDMDEVINS pDevIns, PCDBGFREGDESC paRegisters));
3167
3168 /**
3169 * Gets the trace buffer handle.
3170 *
3171 * This is used by the macros found in VBox/vmm/dbgftrace.h and is not
3172 * really inteded for direct usage, thus no inline wrapper function.
3173 *
3174 * @returns Trace buffer handle or NIL_RTTRACEBUF.
3175 * @param pDevIns The device instance.
3176 */
3177 DECLR3CALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
3178
3179 /**
3180 * Registers a statistics sample.
3181 *
3182 * @param pDevIns Device instance of the DMA.
3183 * @param pvSample Pointer to the sample.
3184 * @param enmType Sample type. This indicates what pvSample is
3185 * pointing at.
3186 * @param pszName Sample name, unix path style. If this does not
3187 * start with a '/', the default prefix will be
3188 * prepended, otherwise it will be used as-is.
3189 * @param enmUnit Sample unit.
3190 * @param pszDesc Sample description.
3191 */
3192 DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc));
3193
3194 /**
3195 * Same as pfnSTAMRegister except that the name is specified in a
3196 * RTStrPrintfV like fashion.
3197 *
3198 * @returns VBox status.
3199 * @param pDevIns Device instance of the DMA.
3200 * @param pvSample Pointer to the sample.
3201 * @param enmType Sample type. This indicates what pvSample is
3202 * pointing at.
3203 * @param enmVisibility Visibility type specifying whether unused
3204 * statistics should be visible or not.
3205 * @param enmUnit Sample unit.
3206 * @param pszDesc Sample description.
3207 * @param pszName Sample name format string, unix path style. If
3208 * this does not start with a '/', the default
3209 * prefix will be prepended, otherwise it will be
3210 * used as-is.
3211 * @param args Arguments to the format string.
3212 */
3213 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType,
3214 STAMVISIBILITY enmVisibility, STAMUNIT enmUnit, const char *pszDesc,
3215 const char *pszName, va_list args) RT_IPRT_FORMAT_ATTR(7, 0));
3216
3217 /**
3218 * Registers a PCI device with the default PCI bus.
3219 *
3220 * If a PDM device has more than one PCI device, they must be registered in the
3221 * order of PDMDEVINSR3::apPciDevs.
3222 *
3223 * @returns VBox status code.
3224 * @param pDevIns The device instance.
3225 * @param pPciDev The PCI device structure.
3226 * This must be kept in the instance data.
3227 * The PCI configuration must be initialized before registration.
3228 * @param fFlags Reserved for future use, PDMPCIDEVREG_F_MBZ.
3229 * @param uPciDevNo PDMPCIDEVREG_DEV_NO_FIRST_UNUSED,
3230 * PDMPCIDEVREG_DEV_NO_SAME_AS_PREV, or a specific
3231 * device number (0-31). This will be ignored if
3232 * the CFGM configuration contains a PCIDeviceNo
3233 * value.
3234 * @param uPciFunNo PDMPCIDEVREG_FUN_NO_FIRST_UNUSED, or a specific
3235 * function number (0-7). This will be ignored if
3236 * the CFGM configuration contains a PCIFunctionNo
3237 * value.
3238 * @param pszName Device name, if NULL PDMDEVREG::szName is used.
3239 * The pointer is saved, so don't free or changed.
3240 * @note The PCI device configuration is now implicit from the apPciDevs
3241 * index, meaning that the zero'th entry is the primary one and
3242 * subsequent uses CFGM subkeys "PciDev1", "PciDev2" and so on.
3243 */
3244 DECLR3CALLBACKMEMBER(int, pfnPCIRegister,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t fFlags,
3245 uint8_t uPciDevNo, uint8_t uPciFunNo, const char *pszName));
3246
3247 /**
3248 * Initialize MSI or MSI-X emulation support for the given PCI device.
3249 *
3250 * @see PDMPCIBUSREG::pfnRegisterMsiR3 for details.
3251 *
3252 * @returns VBox status code.
3253 * @param pDevIns The device instance.
3254 * @param pPciDev The PCI device. NULL is an alias for the first
3255 * one registered.
3256 * @param pMsiReg MSI emulation registration structure.
3257 */
3258 DECLR3CALLBACKMEMBER(int, pfnPCIRegisterMsi,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, PPDMMSIREG pMsiReg));
3259
3260 /**
3261 * Registers a I/O region (memory mapped or I/O ports) for a PCI device.
3262 *
3263 * @returns VBox status code.
3264 * @param pDevIns The device instance.
3265 * @param pPciDev The PCI device structure. If NULL the default
3266 * PCI device for this device instance is used.
3267 * @param iRegion The region number.
3268 * @param cbRegion Size of the region.
3269 * @param enmType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
3270 * @param fFlags PDMPCIDEV_IORGN_F_XXX.
3271 * @param hHandle An I/O port, MMIO or MMIO2 handle according to
3272 * @a fFlags, UINT64_MAX if no handle is passed
3273 * (old style).
3274 * @param pfnMapUnmap Callback for doing the mapping, optional when a
3275 * handle is specified. The callback will be
3276 * invoked holding only the PDM lock. The device
3277 * lock will _not_ be taken (due to lock order).
3278 */
3279 DECLR3CALLBACKMEMBER(int, pfnPCIIORegionRegister,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion,
3280 RTGCPHYS cbRegion, PCIADDRESSSPACE enmType, uint32_t fFlags,
3281 uint64_t hHandle, PFNPCIIOREGIONMAP pfnMapUnmap));
3282
3283 /**
3284 * Register PCI configuration space read/write callbacks.
3285 *
3286 * @returns VBox status code.
3287 * @param pDevIns The device instance.
3288 * @param pPciDev The PCI device structure. If NULL the default
3289 * PCI device for this device instance is used.
3290 * @param pfnRead Pointer to the user defined PCI config read function.
3291 * to call default PCI config read function. Can be NULL.
3292 * @param pfnWrite Pointer to the user defined PCI config write function.
3293 * @remarks The callbacks will be invoked holding the PDM lock. The device lock
3294 * is NOT take because that is very likely be a lock order violation.
3295 * @thread EMT(0)
3296 * @note Only callable during VM creation.
3297 * @sa PDMDevHlpPCIConfigRead, PDMDevHlpPCIConfigWrite
3298 */
3299 DECLR3CALLBACKMEMBER(int, pfnPCIInterceptConfigAccesses,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
3300 PFNPCICONFIGREAD pfnRead, PFNPCICONFIGWRITE pfnWrite));
3301
3302 /**
3303 * Perform a PCI configuration space write.
3304 *
3305 * This is for devices that make use of PDMDevHlpPCIInterceptConfigAccesses().
3306 *
3307 * @returns Strict VBox status code (mainly DBGFSTOP).
3308 * @param pDevIns The device instance.
3309 * @param pPciDev The PCI device which config space is being read.
3310 * @param uAddress The config space address.
3311 * @param cb The size of the read: 1, 2 or 4 bytes.
3312 * @param u32Value The value to write.
3313 */
3314 DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnPCIConfigWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
3315 uint32_t uAddress, unsigned cb, uint32_t u32Value));
3316
3317 /**
3318 * Perform a PCI configuration space read.
3319 *
3320 * This is for devices that make use of PDMDevHlpPCIInterceptConfigAccesses().
3321 *
3322 * @returns Strict VBox status code (mainly DBGFSTOP).
3323 * @param pDevIns The device instance.
3324 * @param pPciDev The PCI device which config space is being read.
3325 * @param uAddress The config space address.
3326 * @param cb The size of the read: 1, 2 or 4 bytes.
3327 * @param pu32Value Where to return the value.
3328 */
3329 DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnPCIConfigRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
3330 uint32_t uAddress, unsigned cb, uint32_t *pu32Value));
3331
3332 /**
3333 * Bus master physical memory read.
3334 *
3335 * @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
3336 * VERR_EM_MEMORY. The informational status shall NOT be propagated!
3337 * @param pDevIns The device instance.
3338 * @param pPciDev The PCI device structure. If NULL the default
3339 * PCI device for this device instance is used.
3340 * @param GCPhys Physical address start reading from.
3341 * @param pvBuf Where to put the read bits.
3342 * @param cbRead How many bytes to read.
3343 * @thread Any thread, but the call may involve the emulation thread.
3344 */
3345 DECLR3CALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
3346
3347 /**
3348 * Bus master physical memory write.
3349 *
3350 * @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
3351 * VERR_EM_MEMORY. The informational status shall NOT be propagated!
3352 * @param pDevIns The device instance.
3353 * @param pPciDev The PCI device structure. If NULL the default
3354 * PCI device for this device instance is used.
3355 * @param GCPhys Physical address to write to.
3356 * @param pvBuf What to write.
3357 * @param cbWrite How many bytes to write.
3358 * @thread Any thread, but the call may involve the emulation thread.
3359 */
3360 DECLR3CALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
3361
3362 /**
3363 * Sets the IRQ for the given PCI device.
3364 *
3365 * @param pDevIns The device instance.
3366 * @param pPciDev The PCI device structure. If NULL the default
3367 * PCI device for this device instance is used.
3368 * @param iIrq IRQ number to set.
3369 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3370 * @thread Any thread, but will involve the emulation thread.
3371 */
3372 DECLR3CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
3373
3374 /**
3375 * Sets the IRQ for the given PCI device, but doesn't wait for EMT to process
3376 * the request when not called from EMT.
3377 *
3378 * @param pDevIns The device instance.
3379 * @param pPciDev The PCI device structure. If NULL the default
3380 * PCI device for this device instance is used.
3381 * @param iIrq IRQ number to set.
3382 * @param iLevel IRQ level.
3383 * @thread Any thread, but will involve the emulation thread.
3384 */
3385 DECLR3CALLBACKMEMBER(void, pfnPCISetIrqNoWait,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
3386
3387 /**
3388 * Set ISA IRQ for a device.
3389 *
3390 * @param pDevIns The device instance.
3391 * @param iIrq IRQ number to set.
3392 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3393 * @thread Any thread, but will involve the emulation thread.
3394 */
3395 DECLR3CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3396
3397 /**
3398 * Set the ISA IRQ for a device, but don't wait for EMT to process
3399 * the request when not called from EMT.
3400 *
3401 * @param pDevIns The device instance.
3402 * @param iIrq IRQ number to set.
3403 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3404 * @thread Any thread, but will involve the emulation thread.
3405 */
3406 DECLR3CALLBACKMEMBER(void, pfnISASetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3407
3408 /**
3409 * Send an MSI straight to the I/O APIC.
3410 *
3411 * @param pDevIns PCI device instance.
3412 * @param GCPhys Physical address MSI request was written.
3413 * @param uValue Value written.
3414 * @thread Any thread, but will involve the emulation thread.
3415 */
3416 DECLR3CALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue));
3417
3418 /**
3419 * Attaches a driver (chain) to the device.
3420 *
3421 * The first call for a LUN this will serve as a registration of the LUN. The pBaseInterface and
3422 * the pszDesc string will be registered with that LUN and kept around for PDMR3QueryDeviceLun().
3423 *
3424 * @returns VBox status code.
3425 * @param pDevIns The device instance.
3426 * @param iLun The logical unit to attach.
3427 * @param pBaseInterface Pointer to the base interface for that LUN. (device side / down)
3428 * @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up)
3429 * @param pszDesc Pointer to a string describing the LUN. This string must remain valid
3430 * for the live of the device instance.
3431 */
3432 DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMDEVINS pDevIns, uint32_t iLun, PPDMIBASE pBaseInterface,
3433 PPDMIBASE *ppBaseInterface, const char *pszDesc));
3434
3435 /**
3436 * Detaches an attached driver (chain) from the device again.
3437 *
3438 * @returns VBox status code.
3439 * @param pDevIns The device instance.
3440 * @param pDrvIns The driver instance to detach.
3441 * @param fFlags Flags, combination of the PDMDEVATT_FLAGS_* \#defines.
3442 */
3443 DECLR3CALLBACKMEMBER(int, pfnDriverDetach,(PPDMDEVINS pDevIns, PPDMDRVINS pDrvIns, uint32_t fFlags));
3444
3445 /** @name Exported PDM Queue Functions
3446 * @{ */
3447 /**
3448 * Create a queue.
3449 *
3450 * @returns VBox status code.
3451 * @param pDevIns The device instance.
3452 * @param cbItem The size of a queue item.
3453 * @param cItems The number of items in the queue.
3454 * @param cMilliesInterval The number of milliseconds between polling the queue.
3455 * If 0 then the emulation thread will be notified whenever an item arrives.
3456 * @param pfnCallback The consumer function.
3457 * @param fRZEnabled Set if the queue should work in RC and R0.
3458 * @param pszName The queue base name. The instance number will be
3459 * appended automatically.
3460 * @param ppQueue Where to store the queue pointer on success.
3461 * @thread The emulation thread.
3462 * @remarks The device critical section will NOT be entered before calling the
3463 * callback. No locks will be held, but for now it's safe to assume
3464 * that only one EMT will do queue callbacks at any one time.
3465 */
3466 DECLR3CALLBACKMEMBER(int, pfnQueueCreatePtr,(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
3467 PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char *pszName,
3468 PPDMQUEUE *ppQueue));
3469
3470 /**
3471 * Create a queue.
3472 *
3473 * @returns VBox status code.
3474 * @param pDevIns The device instance.
3475 * @param cbItem The size of a queue item.
3476 * @param cItems The number of items in the queue.
3477 * @param cMilliesInterval The number of milliseconds between polling the queue.
3478 * If 0 then the emulation thread will be notified whenever an item arrives.
3479 * @param pfnCallback The consumer function.
3480 * @param fRZEnabled Set if the queue should work in RC and R0.
3481 * @param pszName The queue base name. The instance number will be
3482 * appended automatically.
3483 * @param phQueue Where to store the queue handle on success.
3484 * @thread EMT(0)
3485 * @remarks The device critical section will NOT be entered before calling the
3486 * callback. No locks will be held, but for now it's safe to assume
3487 * that only one EMT will do queue callbacks at any one time.
3488 */
3489 DECLR3CALLBACKMEMBER(int, pfnQueueCreate,(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
3490 PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char *pszName,
3491 PDMQUEUEHANDLE *phQueue));
3492
3493 DECLR3CALLBACKMEMBER(PPDMQUEUE, pfnQueueToPtr,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
3494 DECLR3CALLBACKMEMBER(PPDMQUEUEITEMCORE, pfnQueueAlloc,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
3495 DECLR3CALLBACKMEMBER(void, pfnQueueInsert,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem));
3496 DECLR3CALLBACKMEMBER(void, pfnQueueInsertEx,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem, uint64_t cNanoMaxDelay));
3497 DECLR3CALLBACKMEMBER(bool, pfnQueueFlushIfNecessary,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
3498 /** @} */
3499
3500 /** @name PDM Task
3501 * @{ */
3502 /**
3503 * Create an asynchronous ring-3 task.
3504 *
3505 * @returns VBox status code.
3506 * @param pDevIns The device instance.
3507 * @param fFlags PDMTASK_F_XXX
3508 * @param pszName The function name or similar. Used for statistics,
3509 * so no slashes.
3510 * @param pfnCallback The task function.
3511 * @param pvUser User argument for the task function.
3512 * @param phTask Where to return the task handle.
3513 * @thread EMT(0)
3514 */
3515 DECLR3CALLBACKMEMBER(int, pfnTaskCreate,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszName,
3516 PFNPDMTASKDEV pfnCallback, void *pvUser, PDMTASKHANDLE *phTask));
3517 /**
3518 * Triggers the running the given task.
3519 *
3520 * @returns VBox status code.
3521 * @retval VINF_ALREADY_POSTED is the task is already pending.
3522 * @param pDevIns The device instance.
3523 * @param hTask The task to trigger.
3524 * @thread Any thread.
3525 */
3526 DECLR3CALLBACKMEMBER(int, pfnTaskTrigger,(PPDMDEVINS pDevIns, PDMTASKHANDLE hTask));
3527 /** @} */
3528
3529 /** @name SUP Event Semaphore Wrappers (single release / auto reset)
3530 * These semaphores can be signalled from ring-0.
3531 * @{ */
3532 /** @sa SUPSemEventCreate */
3533 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventCreate,(PPDMDEVINS pDevIns, PSUPSEMEVENT phEvent));
3534 /** @sa SUPSemEventClose */
3535 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventClose,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent));
3536 /** @sa SUPSemEventSignal */
3537 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventSignal,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent));
3538 /** @sa SUPSemEventWaitNoResume */
3539 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint32_t cMillies));
3540 /** @sa SUPSemEventWaitNsAbsIntr */
3541 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t uNsTimeout));
3542 /** @sa SUPSemEventWaitNsRelIntr */
3543 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t cNsTimeout));
3544 /** @sa SUPSemEventGetResolution */
3545 DECLR3CALLBACKMEMBER(uint32_t, pfnSUPSemEventGetResolution,(PPDMDEVINS pDevIns));
3546 /** @} */
3547
3548 /** @name SUP Multi Event Semaphore Wrappers (multiple release / manual reset)
3549 * These semaphores can be signalled from ring-0.
3550 * @{ */
3551 /** @sa SUPSemEventMultiCreate */
3552 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiCreate,(PPDMDEVINS pDevIns, PSUPSEMEVENTMULTI phEventMulti));
3553 /** @sa SUPSemEventMultiClose */
3554 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiClose,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
3555 /** @sa SUPSemEventMultiSignal */
3556 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiSignal,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
3557 /** @sa SUPSemEventMultiReset */
3558 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiReset,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
3559 /** @sa SUPSemEventMultiWaitNoResume */
3560 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint32_t cMillies));
3561 /** @sa SUPSemEventMultiWaitNsAbsIntr */
3562 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t uNsTimeout));
3563 /** @sa SUPSemEventMultiWaitNsRelIntr */
3564 DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t cNsTimeout));
3565 /** @sa SUPSemEventMultiGetResolution */
3566 DECLR3CALLBACKMEMBER(uint32_t, pfnSUPSemEventMultiGetResolution,(PPDMDEVINS pDevIns));
3567 /** @} */
3568
3569 /**
3570 * Initializes a PDM critical section.
3571 *
3572 * The PDM critical sections are derived from the IPRT critical sections, but
3573 * works in RC and R0 as well.
3574 *
3575 * @returns VBox status code.
3576 * @param pDevIns The device instance.
3577 * @param pCritSect Pointer to the critical section.
3578 * @param SRC_POS Use RT_SRC_POS.
3579 * @param pszNameFmt Format string for naming the critical section.
3580 * For statistics and lock validation.
3581 * @param va Arguments for the format string.
3582 */
3583 DECLR3CALLBACKMEMBER(int, pfnCritSectInit,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RT_SRC_POS_DECL,
3584 const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
3585
3586 /**
3587 * Gets the NOP critical section.
3588 *
3589 * @returns The ring-3 address of the NOP critical section.
3590 * @param pDevIns The device instance.
3591 */
3592 DECLR3CALLBACKMEMBER(PPDMCRITSECT, pfnCritSectGetNop,(PPDMDEVINS pDevIns));
3593
3594 /**
3595 * Gets the NOP critical section.
3596 *
3597 * @returns The ring-0 address of the NOP critical section.
3598 * @param pDevIns The device instance.
3599 * @deprecated
3600 */
3601 DECLR3CALLBACKMEMBER(R0PTRTYPE(PPDMCRITSECT), pfnCritSectGetNopR0,(PPDMDEVINS pDevIns));
3602
3603 /**
3604 * Gets the NOP critical section.
3605 *
3606 * @returns The raw-mode context address of the NOP critical section.
3607 * @param pDevIns The device instance.
3608 * @deprecated
3609 */
3610 DECLR3CALLBACKMEMBER(RCPTRTYPE(PPDMCRITSECT), pfnCritSectGetNopRC,(PPDMDEVINS pDevIns));
3611
3612 /**
3613 * Changes the device level critical section from the automatically created
3614 * default to one desired by the device constructor.
3615 *
3616 * For ring-0 and raw-mode capable devices, the call must be repeated in each of
3617 * the additional contexts.
3618 *
3619 * @returns VBox status code.
3620 * @param pDevIns The device instance.
3621 * @param pCritSect The critical section to use. NULL is not
3622 * valid, instead use the NOP critical
3623 * section.
3624 */
3625 DECLR3CALLBACKMEMBER(int, pfnSetDeviceCritSect,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
3626
3627 /** @name Exported PDM Critical Section Functions
3628 * @{ */
3629 DECLR3CALLBACKMEMBER(bool, pfnCritSectYield,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
3630 DECLR3CALLBACKMEMBER(int, pfnCritSectEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy));
3631 DECLR3CALLBACKMEMBER(int, pfnCritSectEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
3632 DECLR3CALLBACKMEMBER(int, pfnCritSectTryEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
3633 DECLR3CALLBACKMEMBER(int, pfnCritSectTryEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
3634 DECLR3CALLBACKMEMBER(int, pfnCritSectLeave,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
3635 DECLR3CALLBACKMEMBER(bool, pfnCritSectIsOwner,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
3636 DECLR3CALLBACKMEMBER(bool, pfnCritSectIsInitialized,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
3637 DECLR3CALLBACKMEMBER(bool, pfnCritSectHasWaiters,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
3638 DECLR3CALLBACKMEMBER(uint32_t, pfnCritSectGetRecursion,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
3639 DECLR3CALLBACKMEMBER(int, pfnCritSectScheduleExitEvent,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, SUPSEMEVENT hEventToSignal));
3640 DECLR3CALLBACKMEMBER(int, pfnCritSectDelete,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
3641 /** @} */
3642
3643 /**
3644 * Creates a PDM thread.
3645 *
3646 * This differs from the RTThreadCreate() API in that PDM takes care of suspending,
3647 * resuming, and destroying the thread as the VM state changes.
3648 *
3649 * @returns VBox status code.
3650 * @param pDevIns The device instance.
3651 * @param ppThread Where to store the thread 'handle'.
3652 * @param pvUser The user argument to the thread function.
3653 * @param pfnThread The thread function.
3654 * @param pfnWakeup The wakup callback. This is called on the EMT
3655 * thread when a state change is pending.
3656 * @param cbStack See RTThreadCreate.
3657 * @param enmType See RTThreadCreate.
3658 * @param pszName See RTThreadCreate.
3659 * @remarks The device critical section will NOT be entered prior to invoking
3660 * the function pointers.
3661 */
3662 DECLR3CALLBACKMEMBER(int, pfnThreadCreate,(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
3663 PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
3664
3665 /** @name Exported PDM Thread Functions
3666 * @{ */
3667 DECLR3CALLBACKMEMBER(int, pfnThreadDestroy,(PPDMTHREAD pThread, int *pRcThread));
3668 DECLR3CALLBACKMEMBER(int, pfnThreadIAmSuspending,(PPDMTHREAD pThread));
3669 DECLR3CALLBACKMEMBER(int, pfnThreadIAmRunning,(PPDMTHREAD pThread));
3670 DECLR3CALLBACKMEMBER(int, pfnThreadSleep,(PPDMTHREAD pThread, RTMSINTERVAL cMillies));
3671 DECLR3CALLBACKMEMBER(int, pfnThreadSuspend,(PPDMTHREAD pThread));
3672 DECLR3CALLBACKMEMBER(int, pfnThreadResume,(PPDMTHREAD pThread));
3673 /** @} */
3674
3675 /**
3676 * Set up asynchronous handling of a suspend, reset or power off notification.
3677 *
3678 * This shall only be called when getting the notification. It must be called
3679 * for each one.
3680 *
3681 * @returns VBox status code.
3682 * @param pDevIns The device instance.
3683 * @param pfnAsyncNotify The callback.
3684 * @thread EMT(0)
3685 * @remarks The caller will enter the device critical section prior to invoking
3686 * the callback.
3687 */
3688 DECLR3CALLBACKMEMBER(int, pfnSetAsyncNotification, (PPDMDEVINS pDevIns, PFNPDMDEVASYNCNOTIFY pfnAsyncNotify));
3689
3690 /**
3691 * Notify EMT(0) that the device has completed the asynchronous notification
3692 * handling.
3693 *
3694 * This can be called at any time, spurious calls will simply be ignored.
3695 *
3696 * @param pDevIns The device instance.
3697 * @thread Any
3698 */
3699 DECLR3CALLBACKMEMBER(void, pfnAsyncNotificationCompleted, (PPDMDEVINS pDevIns));
3700
3701 /**
3702 * Register the RTC device.
3703 *
3704 * @returns VBox status code.
3705 * @param pDevIns The device instance.
3706 * @param pRtcReg Pointer to a RTC registration structure.
3707 * @param ppRtcHlp Where to store the pointer to the helper
3708 * functions.
3709 */
3710 DECLR3CALLBACKMEMBER(int, pfnRTCRegister,(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp));
3711
3712 /**
3713 * Register a PCI Bus.
3714 *
3715 * @returns VBox status code, but the positive values 0..31 are used to indicate
3716 * bus number rather than informational status codes.
3717 * @param pDevIns The device instance.
3718 * @param pPciBusReg Pointer to PCI bus registration structure.
3719 * @param ppPciHlp Where to store the pointer to the PCI Bus
3720 * helpers.
3721 * @param piBus Where to return the PDM bus number. Optional.
3722 */
3723 DECLR3CALLBACKMEMBER(int, pfnPCIBusRegister,(PPDMDEVINS pDevIns, PPDMPCIBUSREGR3 pPciBusReg,
3724 PCPDMPCIHLPR3 *ppPciHlp, uint32_t *piBus));
3725
3726 /**
3727 * Register the PIC device.
3728 *
3729 * @returns VBox status code.
3730 * @param pDevIns The device instance.
3731 * @param pPicReg Pointer to a PIC registration structure.
3732 * @param ppPicHlp Where to store the pointer to the ring-3 PIC
3733 * helpers.
3734 * @sa PDMDevHlpPICSetUpContext
3735 */
3736 DECLR3CALLBACKMEMBER(int, pfnPICRegister,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp));
3737
3738 /**
3739 * Register the APIC device.
3740 *
3741 * @returns VBox status code.
3742 * @param pDevIns The device instance.
3743 */
3744 DECLR3CALLBACKMEMBER(int, pfnAPICRegister,(PPDMDEVINS pDevIns));
3745
3746 /**
3747 * Register the I/O APIC device.
3748 *
3749 * @returns VBox status code.
3750 * @param pDevIns The device instance.
3751 * @param pIoApicReg Pointer to a I/O APIC registration structure.
3752 * @param ppIoApicHlp Where to store the pointer to the IOAPIC
3753 * helpers.
3754 */
3755 DECLR3CALLBACKMEMBER(int, pfnIoApicRegister,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp));
3756
3757 /**
3758 * Register the HPET device.
3759 *
3760 * @returns VBox status code.
3761 * @param pDevIns The device instance.
3762 * @param pHpetReg Pointer to a HPET registration structure.
3763 * @param ppHpetHlpR3 Where to store the pointer to the HPET
3764 * helpers.
3765 */
3766 DECLR3CALLBACKMEMBER(int, pfnHpetRegister,(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPR3 *ppHpetHlpR3));
3767
3768 /**
3769 * Register a raw PCI device.
3770 *
3771 * @returns VBox status code.
3772 * @param pDevIns The device instance.
3773 * @param pPciRawReg Pointer to a raw PCI registration structure.
3774 * @param ppPciRawHlpR3 Where to store the pointer to the raw PCI
3775 * device helpers.
3776 */
3777 DECLR3CALLBACKMEMBER(int, pfnPciRawRegister,(PPDMDEVINS pDevIns, PPDMPCIRAWREG pPciRawReg, PCPDMPCIRAWHLPR3 *ppPciRawHlpR3));
3778
3779 /**
3780 * Register the DMA device.
3781 *
3782 * @returns VBox status code.
3783 * @param pDevIns The device instance.
3784 * @param pDmacReg Pointer to a DMAC registration structure.
3785 * @param ppDmacHlp Where to store the pointer to the DMA helpers.
3786 */
3787 DECLR3CALLBACKMEMBER(int, pfnDMACRegister,(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp));
3788
3789 /**
3790 * Register transfer function for DMA channel.
3791 *
3792 * @returns VBox status code.
3793 * @param pDevIns The device instance.
3794 * @param uChannel Channel number.
3795 * @param pfnTransferHandler Device specific transfer callback function.
3796 * @param pvUser User pointer to pass to the callback.
3797 * @thread EMT
3798 */
3799 DECLR3CALLBACKMEMBER(int, pfnDMARegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
3800
3801 /**
3802 * Read memory.
3803 *
3804 * @returns VBox status code.
3805 * @param pDevIns The device instance.
3806 * @param uChannel Channel number.
3807 * @param pvBuffer Pointer to target buffer.
3808 * @param off DMA position.
3809 * @param cbBlock Block size.
3810 * @param pcbRead Where to store the number of bytes which was
3811 * read. optional.
3812 * @thread EMT
3813 */
3814 DECLR3CALLBACKMEMBER(int, pfnDMAReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbRead));
3815
3816 /**
3817 * Write memory.
3818 *
3819 * @returns VBox status code.
3820 * @param pDevIns The device instance.
3821 * @param uChannel Channel number.
3822 * @param pvBuffer Memory to write.
3823 * @param off DMA position.
3824 * @param cbBlock Block size.
3825 * @param pcbWritten Where to store the number of bytes which was
3826 * written. optional.
3827 * @thread EMT
3828 */
3829 DECLR3CALLBACKMEMBER(int, pfnDMAWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbWritten));
3830
3831 /**
3832 * Set the DREQ line.
3833 *
3834 * @returns VBox status code.
3835 * @param pDevIns Device instance.
3836 * @param uChannel Channel number.
3837 * @param uLevel Level of the line.
3838 * @thread EMT
3839 */
3840 DECLR3CALLBACKMEMBER(int, pfnDMASetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
3841
3842 /**
3843 * Get channel mode.
3844 *
3845 * @returns Channel mode. See specs.
3846 * @param pDevIns The device instance.
3847 * @param uChannel Channel number.
3848 * @thread EMT
3849 */
3850 DECLR3CALLBACKMEMBER(uint8_t, pfnDMAGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
3851
3852 /**
3853 * Schedule DMA execution.
3854 *
3855 * @param pDevIns The device instance.
3856 * @thread Any thread.
3857 */
3858 DECLR3CALLBACKMEMBER(void, pfnDMASchedule,(PPDMDEVINS pDevIns));
3859
3860 /**
3861 * Write CMOS value and update the checksum(s).
3862 *
3863 * @returns VBox status code.
3864 * @param pDevIns The device instance.
3865 * @param iReg The CMOS register index.
3866 * @param u8Value The CMOS register value.
3867 * @thread EMT
3868 */
3869 DECLR3CALLBACKMEMBER(int, pfnCMOSWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
3870
3871 /**
3872 * Read CMOS value.
3873 *
3874 * @returns VBox status code.
3875 * @param pDevIns The device instance.
3876 * @param iReg The CMOS register index.
3877 * @param pu8Value Where to store the CMOS register value.
3878 * @thread EMT
3879 */
3880 DECLR3CALLBACKMEMBER(int, pfnCMOSRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
3881
3882 /**
3883 * Assert that the current thread is the emulation thread.
3884 *
3885 * @returns True if correct.
3886 * @returns False if wrong.
3887 * @param pDevIns The device instance.
3888 * @param pszFile Filename of the assertion location.
3889 * @param iLine The linenumber of the assertion location.
3890 * @param pszFunction Function of the assertion location.
3891 */
3892 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction));
3893
3894 /**
3895 * Assert that the current thread is NOT the emulation thread.
3896 *
3897 * @returns True if correct.
3898 * @returns False if wrong.
3899 * @param pDevIns The device instance.
3900 * @param pszFile Filename of the assertion location.
3901 * @param iLine The linenumber of the assertion location.
3902 * @param pszFunction Function of the assertion location.
3903 */
3904 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDEVINS pDevIns, const char *pszFile, unsigned iLine, const char *pszFunction));
3905
3906 /**
3907 * Resolves the symbol for a raw-mode context interface.
3908 *
3909 * @returns VBox status code.
3910 * @param pDevIns The device instance.
3911 * @param pvInterface The interface structure.
3912 * @param cbInterface The size of the interface structure.
3913 * @param pszSymPrefix What to prefix the symbols in the list with
3914 * before resolving them. This must start with
3915 * 'dev' and contain the driver name.
3916 * @param pszSymList List of symbols corresponding to the interface.
3917 * There is generally a there is generally a define
3918 * holding this list associated with the interface
3919 * definition (INTERFACE_SYM_LIST). For more
3920 * details see PDMR3LdrGetInterfaceSymbols.
3921 * @thread EMT
3922 */
3923 DECLR3CALLBACKMEMBER(int, pfnLdrGetRCInterfaceSymbols,(PPDMDEVINS pDevIns, void *pvInterface, size_t cbInterface,
3924 const char *pszSymPrefix, const char *pszSymList));
3925
3926 /**
3927 * Resolves the symbol for a ring-0 context interface.
3928 *
3929 * @returns VBox status code.
3930 * @param pDevIns The device instance.
3931 * @param pvInterface The interface structure.
3932 * @param cbInterface The size of the interface structure.
3933 * @param pszSymPrefix What to prefix the symbols in the list with
3934 * before resolving them. This must start with
3935 * 'dev' and contain the driver name.
3936 * @param pszSymList List of symbols corresponding to the interface.
3937 * There is generally a there is generally a define
3938 * holding this list associated with the interface
3939 * definition (INTERFACE_SYM_LIST). For more
3940 * details see PDMR3LdrGetInterfaceSymbols.
3941 * @thread EMT
3942 */
3943 DECLR3CALLBACKMEMBER(int, pfnLdrGetR0InterfaceSymbols,(PPDMDEVINS pDevIns, void *pvInterface, size_t cbInterface,
3944 const char *pszSymPrefix, const char *pszSymList));
3945
3946 /**
3947 * Calls the PDMDEVREGR0::pfnRequest callback (in ring-0 context).
3948 *
3949 * @returns VBox status code.
3950 * @retval VERR_INVALID_FUNCTION if the callback member is NULL.
3951 * @retval VERR_ACCESS_DENIED if the device isn't ring-0 capable.
3952 *
3953 * @param pDevIns The device instance.
3954 * @param uOperation The operation to perform.
3955 * @param u64Arg 64-bit integer argument.
3956 * @thread EMT
3957 */
3958 DECLR3CALLBACKMEMBER(int, pfnCallR0,(PPDMDEVINS pDevIns, uint32_t uOperation, uint64_t u64Arg));
3959
3960 /**
3961 * Gets the reason for the most recent VM suspend.
3962 *
3963 * @returns The suspend reason. VMSUSPENDREASON_INVALID is returned if no
3964 * suspend has been made or if the pDevIns is invalid.
3965 * @param pDevIns The device instance.
3966 */
3967 DECLR3CALLBACKMEMBER(VMSUSPENDREASON, pfnVMGetSuspendReason,(PPDMDEVINS pDevIns));
3968
3969 /**
3970 * Gets the reason for the most recent VM resume.
3971 *
3972 * @returns The resume reason. VMRESUMEREASON_INVALID is returned if no
3973 * resume has been made or if the pDevIns is invalid.
3974 * @param pDevIns The device instance.
3975 */
3976 DECLR3CALLBACKMEMBER(VMRESUMEREASON, pfnVMGetResumeReason,(PPDMDEVINS pDevIns));
3977
3978 /**
3979 * Requests the mapping of multiple guest page into ring-3.
3980 *
3981 * When you're done with the pages, call pfnPhysBulkReleasePageMappingLocks()
3982 * ASAP to release them.
3983 *
3984 * This API will assume your intention is to write to the pages, and will
3985 * therefore replace shared and zero pages. If you do not intend to modify the
3986 * pages, use the pfnPhysBulkGCPhys2CCPtrReadOnly() API.
3987 *
3988 * @returns VBox status code.
3989 * @retval VINF_SUCCESS on success.
3990 * @retval VERR_PGM_PHYS_PAGE_RESERVED if any of the pages has no physical
3991 * backing or if any of the pages the page has any active access
3992 * handlers. The caller must fall back on using PGMR3PhysWriteExternal.
3993 * @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if @a paGCPhysPages contains
3994 * an invalid physical address.
3995 *
3996 * @param pDevIns The device instance.
3997 * @param cPages Number of pages to lock.
3998 * @param paGCPhysPages The guest physical address of the pages that
3999 * should be mapped (@a cPages entries).
4000 * @param fFlags Flags reserved for future use, MBZ.
4001 * @param papvPages Where to store the ring-3 mapping addresses
4002 * corresponding to @a paGCPhysPages.
4003 * @param paLocks Where to store the locking information that
4004 * pfnPhysBulkReleasePageMappingLock needs (@a cPages
4005 * in length).
4006 *
4007 * @remark Avoid calling this API from within critical sections (other than the
4008 * PGM one) because of the deadlock risk when we have to delegating the
4009 * task to an EMT.
4010 * @thread Any.
4011 * @since 6.0.6
4012 */
4013 DECLR3CALLBACKMEMBER(int, pfnPhysBulkGCPhys2CCPtr,(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
4014 uint32_t fFlags, void **papvPages, PPGMPAGEMAPLOCK paLocks));
4015
4016 /**
4017 * Requests the mapping of multiple guest page into ring-3, for reading only.
4018 *
4019 * When you're done with the pages, call pfnPhysBulkReleasePageMappingLocks()
4020 * ASAP to release them.
4021 *
4022 * @returns VBox status code.
4023 * @retval VINF_SUCCESS on success.
4024 * @retval VERR_PGM_PHYS_PAGE_RESERVED if any of the pages has no physical
4025 * backing or if any of the pages the page has an active ALL access
4026 * handler. The caller must fall back on using PGMR3PhysWriteExternal.
4027 * @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if @a paGCPhysPages contains
4028 * an invalid physical address.
4029 *
4030 * @param pDevIns The device instance.
4031 * @param cPages Number of pages to lock.
4032 * @param paGCPhysPages The guest physical address of the pages that
4033 * should be mapped (@a cPages entries).
4034 * @param fFlags Flags reserved for future use, MBZ.
4035 * @param papvPages Where to store the ring-3 mapping addresses
4036 * corresponding to @a paGCPhysPages.
4037 * @param paLocks Where to store the lock information that
4038 * pfnPhysReleasePageMappingLock needs (@a cPages
4039 * in length).
4040 *
4041 * @remark Avoid calling this API from within critical sections.
4042 * @thread Any.
4043 * @since 6.0.6
4044 */
4045 DECLR3CALLBACKMEMBER(int, pfnPhysBulkGCPhys2CCPtrReadOnly,(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
4046 uint32_t fFlags, void const **papvPages, PPGMPAGEMAPLOCK paLocks));
4047
4048 /**
4049 * Release the mappings of multiple guest pages.
4050 *
4051 * This is the counter part of pfnPhysBulkGCPhys2CCPtr and
4052 * pfnPhysBulkGCPhys2CCPtrReadOnly.
4053 *
4054 * @param pDevIns The device instance.
4055 * @param cPages Number of pages to unlock.
4056 * @param paLocks The lock structures initialized by the mapping
4057 * function (@a cPages in length).
4058 * @thread Any.
4059 * @since 6.0.6
4060 */
4061 DECLR3CALLBACKMEMBER(void, pfnPhysBulkReleasePageMappingLocks,(PPDMDEVINS pDevIns, uint32_t cPages, PPGMPAGEMAPLOCK paLocks));
4062
4063 /**
4064 * Changes the number of an MMIO2 or pre-registered MMIO region.
4065 *
4066 * This should only be used to deal with saved state problems, so there is no
4067 * convenience inline wrapper for this method.
4068 *
4069 * @returns VBox status code.
4070 * @param pDevIns The device instance.
4071 * @param pPciDev The PCI device the region is associated with, or
4072 * NULL if not associated with any.
4073 * @param iRegion The region.
4074 * @param iNewRegion The new region index.
4075 *
4076 * @sa @bugref{9359}
4077 */
4078 DECLR3CALLBACKMEMBER(int, pfnMMIOExChangeRegionNo,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion,
4079 uint32_t iNewRegion));
4080
4081 /** Space reserved for future members.
4082 * @{ */
4083 DECLR3CALLBACKMEMBER(void, pfnReserved1,(void));
4084 DECLR3CALLBACKMEMBER(void, pfnReserved2,(void));
4085 DECLR3CALLBACKMEMBER(void, pfnReserved3,(void));
4086 DECLR3CALLBACKMEMBER(void, pfnReserved4,(void));
4087 DECLR3CALLBACKMEMBER(void, pfnReserved5,(void));
4088 DECLR3CALLBACKMEMBER(void, pfnReserved6,(void));
4089 DECLR3CALLBACKMEMBER(void, pfnReserved7,(void));
4090 DECLR3CALLBACKMEMBER(void, pfnReserved8,(void));
4091 DECLR3CALLBACKMEMBER(void, pfnReserved9,(void));
4092 DECLR3CALLBACKMEMBER(void, pfnReserved10,(void));
4093 /** @} */
4094
4095
4096 /** API available to trusted devices only.
4097 *
4098 * These APIs are providing unrestricted access to the guest and the VM,
4099 * or they are interacting intimately with PDM.
4100 *
4101 * @{
4102 */
4103
4104 /**
4105 * Gets the user mode VM handle. Restricted API.
4106 *
4107 * @returns User mode VM Handle.
4108 * @param pDevIns The device instance.
4109 */
4110 DECLR3CALLBACKMEMBER(PUVM, pfnGetUVM,(PPDMDEVINS pDevIns));
4111
4112 /**
4113 * Gets the global VM handle. Restricted API.
4114 *
4115 * @returns VM Handle.
4116 * @param pDevIns The device instance.
4117 */
4118 DECLR3CALLBACKMEMBER(PVMCC, pfnGetVM,(PPDMDEVINS pDevIns));
4119
4120 /**
4121 * Gets the VMCPU handle. Restricted API.
4122 *
4123 * @returns VMCPU Handle.
4124 * @param pDevIns The device instance.
4125 */
4126 DECLR3CALLBACKMEMBER(PVMCPU, pfnGetVMCPU,(PPDMDEVINS pDevIns));
4127
4128 /**
4129 * The the VM CPU ID of the current thread (restricted API).
4130 *
4131 * @returns The VMCPUID of the calling thread, NIL_VMCPUID if not EMT.
4132 * @param pDevIns The device instance.
4133 */
4134 DECLR3CALLBACKMEMBER(VMCPUID, pfnGetCurrentCpuId,(PPDMDEVINS pDevIns));
4135
4136 /**
4137 * Registers the VMM device heap or notifies about mapping/unmapping.
4138 *
4139 * This interface serves three purposes:
4140 *
4141 * -# Register the VMM device heap during device construction
4142 * for the HM to use.
4143 * -# Notify PDM/HM that it's mapped into guest address
4144 * space (i.e. usable).
4145 * -# Notify PDM/HM that it is being unmapped from the guest
4146 * address space (i.e. not usable).
4147 *
4148 * @returns VBox status code.
4149 * @param pDevIns The device instance.
4150 * @param GCPhys The physical address if mapped, NIL_RTGCPHYS if
4151 * not mapped.
4152 * @param pvHeap Ring 3 heap pointer.
4153 * @param cbHeap Size of the heap.
4154 * @thread EMT.
4155 */
4156 DECLR3CALLBACKMEMBER(int, pfnRegisterVMMDevHeap,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTR3PTR pvHeap, unsigned cbHeap));
4157
4158 /**
4159 * Registers the firmware (BIOS, EFI) device with PDM.
4160 *
4161 * The firmware provides a callback table and gets a special PDM helper table.
4162 * There can only be one firmware device for a VM.
4163 *
4164 * @returns VBox status code.
4165 * @param pDevIns The device instance.
4166 * @param pFwReg Firmware registration structure.
4167 * @param ppFwHlp Where to return the firmware helper structure.
4168 * @remarks Only valid during device construction.
4169 * @thread EMT(0)
4170 */
4171 DECLR3CALLBACKMEMBER(int, pfnFirmwareRegister,(PPDMDEVINS pDevIns, PCPDMFWREG pFwReg, PCPDMFWHLPR3 *ppFwHlp));
4172
4173 /**
4174 * Resets the VM.
4175 *
4176 * @returns The appropriate VBox status code to pass around on reset.
4177 * @param pDevIns The device instance.
4178 * @param fFlags PDMVMRESET_F_XXX flags.
4179 * @thread The emulation thread.
4180 */
4181 DECLR3CALLBACKMEMBER(int, pfnVMReset,(PPDMDEVINS pDevIns, uint32_t fFlags));
4182
4183 /**
4184 * Suspends the VM.
4185 *
4186 * @returns The appropriate VBox status code to pass around on suspend.
4187 * @param pDevIns The device instance.
4188 * @thread The emulation thread.
4189 */
4190 DECLR3CALLBACKMEMBER(int, pfnVMSuspend,(PPDMDEVINS pDevIns));
4191
4192 /**
4193 * Suspends, saves and powers off the VM.
4194 *
4195 * @returns The appropriate VBox status code to pass around.
4196 * @param pDevIns The device instance.
4197 * @thread An emulation thread.
4198 */
4199 DECLR3CALLBACKMEMBER(int, pfnVMSuspendSaveAndPowerOff,(PPDMDEVINS pDevIns));
4200
4201 /**
4202 * Power off the VM.
4203 *
4204 * @returns The appropriate VBox status code to pass around on power off.
4205 * @param pDevIns The device instance.
4206 * @thread The emulation thread.
4207 */
4208 DECLR3CALLBACKMEMBER(int, pfnVMPowerOff,(PPDMDEVINS pDevIns));
4209
4210 /**
4211 * Checks if the Gate A20 is enabled or not.
4212 *
4213 * @returns true if A20 is enabled.
4214 * @returns false if A20 is disabled.
4215 * @param pDevIns The device instance.
4216 * @thread The emulation thread.
4217 */
4218 DECLR3CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
4219
4220 /**
4221 * Enables or disables the Gate A20.
4222 *
4223 * @param pDevIns The device instance.
4224 * @param fEnable Set this flag to enable the Gate A20; clear it
4225 * to disable.
4226 * @thread The emulation thread.
4227 */
4228 DECLR3CALLBACKMEMBER(void, pfnA20Set,(PPDMDEVINS pDevIns, bool fEnable));
4229
4230 /**
4231 * Get the specified CPUID leaf for the virtual CPU associated with the calling
4232 * thread.
4233 *
4234 * @param pDevIns The device instance.
4235 * @param iLeaf The CPUID leaf to get.
4236 * @param pEax Where to store the EAX value.
4237 * @param pEbx Where to store the EBX value.
4238 * @param pEcx Where to store the ECX value.
4239 * @param pEdx Where to store the EDX value.
4240 * @thread EMT.
4241 */
4242 DECLR3CALLBACKMEMBER(void, pfnGetCpuId,(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t *pEax, uint32_t *pEbx, uint32_t *pEcx, uint32_t *pEdx));
4243
4244 /**
4245 * Get the current virtual clock time in a VM. The clock frequency must be
4246 * queried separately.
4247 *
4248 * @returns Current clock time.
4249 * @param pDevIns The device instance.
4250 */
4251 DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
4252
4253 /**
4254 * Get the frequency of the virtual clock.
4255 *
4256 * @returns The clock frequency (not variable at run-time).
4257 * @param pDevIns The device instance.
4258 */
4259 DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
4260
4261 /**
4262 * Get the current virtual clock time in a VM, in nanoseconds.
4263 *
4264 * @returns Current clock time (in ns).
4265 * @param pDevIns The device instance.
4266 */
4267 DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
4268
4269 /**
4270 * Gets the support driver session.
4271 *
4272 * This is intended for working with the semaphore API.
4273 *
4274 * @returns Support driver session handle.
4275 * @param pDevIns The device instance.
4276 */
4277 DECLR3CALLBACKMEMBER(PSUPDRVSESSION, pfnGetSupDrvSession,(PPDMDEVINS pDevIns));
4278
4279 /**
4280 * Queries a generic object from the VMM user.
4281 *
4282 * @returns Pointer to the object if found, NULL if not.
4283 * @param pDevIns The device instance.
4284 * @param pUuid The UUID of what's being queried. The UUIDs and
4285 * the usage conventions are defined by the user.
4286 *
4287 * @note It is strictly forbidden to call this internally in VBox! This
4288 * interface is exclusively for hacks in externally developed devices.
4289 */
4290 DECLR3CALLBACKMEMBER(void *, pfnQueryGenericUserObject,(PPDMDEVINS pDevIns, PCRTUUID pUuid));
4291
4292 /** @} */
4293
4294 /** Just a safety precaution. (PDM_DEVHLPR3_VERSION) */
4295 uint32_t u32TheEnd;
4296} PDMDEVHLPR3;
4297#endif /* !IN_RING3 || DOXYGEN_RUNNING */
4298/** Pointer to the R3 PDM Device API. */
4299typedef R3PTRTYPE(struct PDMDEVHLPR3 *) PPDMDEVHLPR3;
4300/** Pointer to the R3 PDM Device API, const variant. */
4301typedef R3PTRTYPE(const struct PDMDEVHLPR3 *) PCPDMDEVHLPR3;
4302
4303
4304/**
4305 * PDM Device API - RC Variant.
4306 */
4307typedef struct PDMDEVHLPRC
4308{
4309 /** Structure version. PDM_DEVHLPRC_VERSION defines the current version. */
4310 uint32_t u32Version;
4311
4312 /**
4313 * Sets up raw-mode context callback handlers for an I/O port range.
4314 *
4315 * The range must have been registered in ring-3 first using
4316 * PDMDevHlpIoPortCreate() or PDMDevHlpIoPortCreateEx().
4317 *
4318 * @returns VBox status.
4319 * @param pDevIns The device instance to register the ports with.
4320 * @param hIoPorts The I/O port range handle.
4321 * @param pfnOut Pointer to function which is gonna handle OUT
4322 * operations. Optional.
4323 * @param pfnIn Pointer to function which is gonna handle IN operations.
4324 * Optional.
4325 * @param pfnOutStr Pointer to function which is gonna handle string OUT
4326 * operations. Optional.
4327 * @param pfnInStr Pointer to function which is gonna handle string IN
4328 * operations. Optional.
4329 * @param pvUser User argument to pass to the callbacks.
4330 *
4331 * @remarks Caller enters the device critical section prior to invoking the
4332 * registered callback methods.
4333 *
4334 * @sa PDMDevHlpIoPortCreate, PDMDevHlpIoPortCreateEx, PDMDevHlpIoPortMap,
4335 * PDMDevHlpIoPortUnmap.
4336 */
4337 DECLRCCALLBACKMEMBER(int, pfnIoPortSetUpContextEx,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
4338 PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
4339 PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr,
4340 void *pvUser));
4341
4342 /**
4343 * Sets up raw-mode context callback handlers for an MMIO region.
4344 *
4345 * The region must have been registered in ring-3 first using
4346 * PDMDevHlpMmioCreate() or PDMDevHlpMmioCreateEx().
4347 *
4348 * @returns VBox status.
4349 * @param pDevIns The device instance to register the ports with.
4350 * @param hRegion The MMIO region handle.
4351 * @param pfnWrite Pointer to function which is gonna handle Write
4352 * operations.
4353 * @param pfnRead Pointer to function which is gonna handle Read
4354 * operations.
4355 * @param pfnFill Pointer to function which is gonna handle Fill/memset
4356 * operations. (optional)
4357 * @param pvUser User argument to pass to the callbacks.
4358 *
4359 * @remarks Caller enters the device critical section prior to invoking the
4360 * registered callback methods.
4361 *
4362 * @sa PDMDevHlpMmioCreate, PDMDevHlpMmioCreateEx, PDMDevHlpMmioMap,
4363 * PDMDevHlpMmioUnmap.
4364 */
4365 DECLRCCALLBACKMEMBER(int, pfnMmioSetUpContextEx,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, PFNIOMMMIONEWWRITE pfnWrite,
4366 PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser));
4367
4368 /**
4369 * Sets up a raw-mode mapping for an MMIO2 region.
4370 *
4371 * The region must have been created in ring-3 first using
4372 * PDMDevHlpMmio2Create().
4373 *
4374 * @returns VBox status.
4375 * @param pDevIns The device instance to register the ports with.
4376 * @param hRegion The MMIO2 region handle.
4377 * @param offSub Start of what to map into raw-mode. Must be page aligned.
4378 * @param cbSub Number of bytes to map into raw-mode. Must be page
4379 * aligned. Zero is an alias for everything.
4380 * @param ppvMapping Where to return the mapping corresponding to @a offSub.
4381 * @thread EMT(0)
4382 * @note Only available at VM creation time.
4383 *
4384 * @sa PDMDevHlpMmio2Create().
4385 */
4386 DECLRCCALLBACKMEMBER(int, pfnMmio2SetUpContext,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion,
4387 size_t offSub, size_t cbSub, void **ppvMapping));
4388
4389 /**
4390 * Bus master physical memory read from the given PCI device.
4391 *
4392 * @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
4393 * VERR_EM_MEMORY. The informational status shall NOT be propagated!
4394 * @param pDevIns The device instance.
4395 * @param pPciDev The PCI device structure. If NULL the default
4396 * PCI device for this device instance is used.
4397 * @param GCPhys Physical address start reading from.
4398 * @param pvBuf Where to put the read bits.
4399 * @param cbRead How many bytes to read.
4400 * @thread Any thread, but the call may involve the emulation thread.
4401 */
4402 DECLRCCALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
4403 void *pvBuf, size_t cbRead));
4404
4405 /**
4406 * Bus master physical memory write from the given PCI device.
4407 *
4408 * @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
4409 * VERR_EM_MEMORY. The informational status shall NOT be propagated!
4410 * @param pDevIns The device instance.
4411 * @param pPciDev The PCI device structure. If NULL the default
4412 * PCI device for this device instance is used.
4413 * @param GCPhys Physical address to write to.
4414 * @param pvBuf What to write.
4415 * @param cbWrite How many bytes to write.
4416 * @thread Any thread, but the call may involve the emulation thread.
4417 */
4418 DECLRCCALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
4419 const void *pvBuf, size_t cbWrite));
4420
4421 /**
4422 * Set the IRQ for the given PCI device.
4423 *
4424 * @param pDevIns Device instance.
4425 * @param pPciDev The PCI device structure. If NULL the default
4426 * PCI device for this device instance is used.
4427 * @param iIrq IRQ number to set.
4428 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
4429 * @thread Any thread, but will involve the emulation thread.
4430 */
4431 DECLRCCALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
4432
4433 /**
4434 * Set ISA IRQ for a device.
4435 *
4436 * @param pDevIns Device instance.
4437 * @param iIrq IRQ number to set.
4438 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
4439 * @thread Any thread, but will involve the emulation thread.
4440 */
4441 DECLRCCALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4442
4443 /**
4444 * Send an MSI straight to the I/O APIC.
4445 *
4446 * @param pDevIns PCI device instance.
4447 * @param GCPhys Physical address MSI request was written.
4448 * @param uValue Value written.
4449 * @thread Any thread, but will involve the emulation thread.
4450 */
4451 DECLRCCALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue));
4452
4453 /**
4454 * Read physical memory.
4455 *
4456 * @returns VINF_SUCCESS (for now).
4457 * @param pDevIns Device instance.
4458 * @param GCPhys Physical address start reading from.
4459 * @param pvBuf Where to put the read bits.
4460 * @param cbRead How many bytes to read.
4461 */
4462 DECLRCCALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
4463
4464 /**
4465 * Write to physical memory.
4466 *
4467 * @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
4468 * @param pDevIns Device instance.
4469 * @param GCPhys Physical address to write to.
4470 * @param pvBuf What to write.
4471 * @param cbWrite How many bytes to write.
4472 */
4473 DECLRCCALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
4474
4475 /**
4476 * Checks if the Gate A20 is enabled or not.
4477 *
4478 * @returns true if A20 is enabled.
4479 * @returns false if A20 is disabled.
4480 * @param pDevIns Device instance.
4481 * @thread The emulation thread.
4482 */
4483 DECLRCCALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
4484
4485 /**
4486 * Gets the VM state.
4487 *
4488 * @returns VM state.
4489 * @param pDevIns The device instance.
4490 * @thread Any thread (just keep in mind that it's volatile info).
4491 */
4492 DECLRCCALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
4493
4494 /**
4495 * Set the VM error message
4496 *
4497 * @returns rc.
4498 * @param pDevIns Driver instance.
4499 * @param rc VBox status code.
4500 * @param SRC_POS Use RT_SRC_POS.
4501 * @param pszFormat Error message format string.
4502 * @param ... Error message arguments.
4503 */
4504 DECLRCCALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
4505 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(6, 7));
4506
4507 /**
4508 * Set the VM error message
4509 *
4510 * @returns rc.
4511 * @param pDevIns Driver instance.
4512 * @param rc VBox status code.
4513 * @param SRC_POS Use RT_SRC_POS.
4514 * @param pszFormat Error message format string.
4515 * @param va Error message arguments.
4516 */
4517 DECLRCCALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
4518 const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
4519
4520 /**
4521 * Set the VM runtime error message
4522 *
4523 * @returns VBox status code.
4524 * @param pDevIns Device instance.
4525 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
4526 * @param pszErrorId Error ID string.
4527 * @param pszFormat Error message format string.
4528 * @param ... Error message arguments.
4529 */
4530 DECLRCCALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
4531 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5));
4532
4533 /**
4534 * Set the VM runtime error message
4535 *
4536 * @returns VBox status code.
4537 * @param pDevIns Device instance.
4538 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
4539 * @param pszErrorId Error ID string.
4540 * @param pszFormat Error message format string.
4541 * @param va Error message arguments.
4542 */
4543 DECLRCCALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
4544 const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0));
4545
4546 /**
4547 * Gets the VM handle. Restricted API.
4548 *
4549 * @returns VM Handle.
4550 * @param pDevIns Device instance.
4551 */
4552 DECLRCCALLBACKMEMBER(PVMCC, pfnGetVM,(PPDMDEVINS pDevIns));
4553
4554 /**
4555 * Gets the VMCPU handle. Restricted API.
4556 *
4557 * @returns VMCPU Handle.
4558 * @param pDevIns The device instance.
4559 */
4560 DECLRCCALLBACKMEMBER(PVMCPUCC, pfnGetVMCPU,(PPDMDEVINS pDevIns));
4561
4562 /**
4563 * The the VM CPU ID of the current thread (restricted API).
4564 *
4565 * @returns The VMCPUID of the calling thread, NIL_VMCPUID if not EMT.
4566 * @param pDevIns The device instance.
4567 */
4568 DECLRCCALLBACKMEMBER(VMCPUID, pfnGetCurrentCpuId,(PPDMDEVINS pDevIns));
4569
4570 /**
4571 * Get the current virtual clock time in a VM. The clock frequency must be
4572 * queried separately.
4573 *
4574 * @returns Current clock time.
4575 * @param pDevIns The device instance.
4576 */
4577 DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
4578
4579 /**
4580 * Get the frequency of the virtual clock.
4581 *
4582 * @returns The clock frequency (not variable at run-time).
4583 * @param pDevIns The device instance.
4584 */
4585 DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
4586
4587 /**
4588 * Get the current virtual clock time in a VM, in nanoseconds.
4589 *
4590 * @returns Current clock time (in ns).
4591 * @param pDevIns The device instance.
4592 */
4593 DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
4594
4595 /**
4596 * Gets the NOP critical section.
4597 *
4598 * @returns The ring-3 address of the NOP critical section.
4599 * @param pDevIns The device instance.
4600 */
4601 DECLRCCALLBACKMEMBER(PPDMCRITSECT, pfnCritSectGetNop,(PPDMDEVINS pDevIns));
4602
4603 /**
4604 * Changes the device level critical section from the automatically created
4605 * default to one desired by the device constructor.
4606 *
4607 * Must first be done in ring-3.
4608 *
4609 * @returns VBox status code.
4610 * @param pDevIns The device instance.
4611 * @param pCritSect The critical section to use. NULL is not
4612 * valid, instead use the NOP critical
4613 * section.
4614 */
4615 DECLRCCALLBACKMEMBER(int, pfnSetDeviceCritSect,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
4616
4617 /** @name Exported PDM Critical Section Functions
4618 * @{ */
4619 DECLRCCALLBACKMEMBER(int, pfnCritSectEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy));
4620 DECLRCCALLBACKMEMBER(int, pfnCritSectEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
4621 DECLRCCALLBACKMEMBER(int, pfnCritSectTryEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
4622 DECLRCCALLBACKMEMBER(int, pfnCritSectTryEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
4623 DECLRCCALLBACKMEMBER(int, pfnCritSectLeave,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
4624 DECLRCCALLBACKMEMBER(bool, pfnCritSectIsOwner,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4625 DECLRCCALLBACKMEMBER(bool, pfnCritSectIsInitialized,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4626 DECLRCCALLBACKMEMBER(bool, pfnCritSectHasWaiters,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4627 DECLRCCALLBACKMEMBER(uint32_t, pfnCritSectGetRecursion,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4628 /** @} */
4629
4630 /**
4631 * Gets the trace buffer handle.
4632 *
4633 * This is used by the macros found in VBox/vmm/dbgftrace.h and is not
4634 * really inteded for direct usage, thus no inline wrapper function.
4635 *
4636 * @returns Trace buffer handle or NIL_RTTRACEBUF.
4637 * @param pDevIns The device instance.
4638 */
4639 DECLRCCALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
4640
4641 /**
4642 * Sets up the PCI bus for the raw-mode context.
4643 *
4644 * This must be called after ring-3 has registered the PCI bus using
4645 * PDMDevHlpPCIBusRegister().
4646 *
4647 * @returns VBox status code.
4648 * @param pDevIns The device instance.
4649 * @param pPciBusReg The PCI bus registration information for raw-mode,
4650 * considered volatile.
4651 * @param ppPciHlp Where to return the raw-mode PCI bus helpers.
4652 */
4653 DECLRCCALLBACKMEMBER(int, pfnPCIBusSetUpContext,(PPDMDEVINS pDevIns, PPDMPCIBUSREGRC pPciBusReg, PCPDMPCIHLPRC *ppPciHlp));
4654
4655 /**
4656 * Sets up the PIC for the ring-0 context.
4657 *
4658 * This must be called after ring-3 has registered the PIC using
4659 * PDMDevHlpPICRegister().
4660 *
4661 * @returns VBox status code.
4662 * @param pDevIns The device instance.
4663 * @param pPicReg The PIC registration information for ring-0,
4664 * considered volatile and copied.
4665 * @param ppPicHlp Where to return the ring-0 PIC helpers.
4666 */
4667 DECLRCCALLBACKMEMBER(int, pfnPICSetUpContext,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp));
4668
4669 /**
4670 * Sets up the IOAPIC for the ring-0 context.
4671 *
4672 * This must be called after ring-3 has registered the PIC using
4673 * PDMDevHlpIoApicRegister().
4674 *
4675 * @returns VBox status code.
4676 * @param pDevIns The device instance.
4677 * @param pIoApicReg The PIC registration information for ring-0,
4678 * considered volatile and copied.
4679 * @param ppIoApicHlp Where to return the ring-0 IOAPIC helpers.
4680 */
4681 DECLRCCALLBACKMEMBER(int, pfnIoApicSetUpContext,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp));
4682
4683 /**
4684 * Sets up the HPET for the raw-mode context.
4685 *
4686 * This must be called after ring-3 has registered the PIC using
4687 * PDMDevHlpHpetRegister().
4688 *
4689 * @returns VBox status code.
4690 * @param pDevIns The device instance.
4691 * @param pHpetReg The PIC registration information for raw-mode,
4692 * considered volatile and copied.
4693 * @param ppHpetHlp Where to return the raw-mode HPET helpers.
4694 */
4695 DECLRCCALLBACKMEMBER(int, pfnHpetSetUpContext,(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPRC *ppHpetHlp));
4696
4697 /** Space reserved for future members.
4698 * @{ */
4699 DECLRCCALLBACKMEMBER(void, pfnReserved1,(void));
4700 DECLRCCALLBACKMEMBER(void, pfnReserved2,(void));
4701 DECLRCCALLBACKMEMBER(void, pfnReserved3,(void));
4702 DECLRCCALLBACKMEMBER(void, pfnReserved4,(void));
4703 DECLRCCALLBACKMEMBER(void, pfnReserved5,(void));
4704 DECLRCCALLBACKMEMBER(void, pfnReserved6,(void));
4705 DECLRCCALLBACKMEMBER(void, pfnReserved7,(void));
4706 DECLRCCALLBACKMEMBER(void, pfnReserved8,(void));
4707 DECLRCCALLBACKMEMBER(void, pfnReserved9,(void));
4708 DECLRCCALLBACKMEMBER(void, pfnReserved10,(void));
4709 /** @} */
4710
4711 /** Just a safety precaution. */
4712 uint32_t u32TheEnd;
4713} PDMDEVHLPRC;
4714/** Pointer PDM Device RC API. */
4715typedef RGPTRTYPE(struct PDMDEVHLPRC *) PPDMDEVHLPRC;
4716/** Pointer PDM Device RC API. */
4717typedef RGPTRTYPE(const struct PDMDEVHLPRC *) PCPDMDEVHLPRC;
4718
4719/** Current PDMDEVHLP version number. */
4720#define PDM_DEVHLPRC_VERSION PDM_VERSION_MAKE(0xffe6, 13, 0)
4721
4722
4723/**
4724 * PDM Device API - R0 Variant.
4725 */
4726typedef struct PDMDEVHLPR0
4727{
4728 /** Structure version. PDM_DEVHLPR0_VERSION defines the current version. */
4729 uint32_t u32Version;
4730
4731 /**
4732 * Sets up ring-0 callback handlers for an I/O port range.
4733 *
4734 * The range must have been created in ring-3 first using
4735 * PDMDevHlpIoPortCreate() or PDMDevHlpIoPortCreateEx().
4736 *
4737 * @returns VBox status.
4738 * @param pDevIns The device instance to register the ports with.
4739 * @param hIoPorts The I/O port range handle.
4740 * @param pfnOut Pointer to function which is gonna handle OUT
4741 * operations. Optional.
4742 * @param pfnIn Pointer to function which is gonna handle IN operations.
4743 * Optional.
4744 * @param pfnOutStr Pointer to function which is gonna handle string OUT
4745 * operations. Optional.
4746 * @param pfnInStr Pointer to function which is gonna handle string IN
4747 * operations. Optional.
4748 * @param pvUser User argument to pass to the callbacks.
4749 *
4750 * @remarks Caller enters the device critical section prior to invoking the
4751 * registered callback methods.
4752 *
4753 * @sa PDMDevHlpIoPortCreate(), PDMDevHlpIoPortCreateEx(),
4754 * PDMDevHlpIoPortMap(), PDMDevHlpIoPortUnmap().
4755 */
4756 DECLR0CALLBACKMEMBER(int, pfnIoPortSetUpContextEx,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
4757 PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
4758 PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr,
4759 void *pvUser));
4760
4761 /**
4762 * Sets up ring-0 callback handlers for an MMIO region.
4763 *
4764 * The region must have been created in ring-3 first using
4765 * PDMDevHlpMmioCreate(), PDMDevHlpMmioCreateEx(), PDMDevHlpMmioCreateAndMap(),
4766 * PDMDevHlpMmioCreateExAndMap() or PDMDevHlpPCIIORegionCreateMmio().
4767 *
4768 * @returns VBox status.
4769 * @param pDevIns The device instance to register the ports with.
4770 * @param hRegion The MMIO region handle.
4771 * @param pfnWrite Pointer to function which is gonna handle Write
4772 * operations.
4773 * @param pfnRead Pointer to function which is gonna handle Read
4774 * operations.
4775 * @param pfnFill Pointer to function which is gonna handle Fill/memset
4776 * operations. (optional)
4777 * @param pvUser User argument to pass to the callbacks.
4778 *
4779 * @remarks Caller enters the device critical section prior to invoking the
4780 * registered callback methods.
4781 *
4782 * @sa PDMDevHlpMmioCreate(), PDMDevHlpMmioCreateEx(), PDMDevHlpMmioMap(),
4783 * PDMDevHlpMmioUnmap().
4784 */
4785 DECLR0CALLBACKMEMBER(int, pfnMmioSetUpContextEx,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, PFNIOMMMIONEWWRITE pfnWrite,
4786 PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser));
4787
4788 /**
4789 * Sets up a ring-0 mapping for an MMIO2 region.
4790 *
4791 * The region must have been created in ring-3 first using
4792 * PDMDevHlpMmio2Create().
4793 *
4794 * @returns VBox status.
4795 * @param pDevIns The device instance to register the ports with.
4796 * @param hRegion The MMIO2 region handle.
4797 * @param offSub Start of what to map into ring-0. Must be page aligned.
4798 * @param cbSub Number of bytes to map into ring-0. Must be page
4799 * aligned. Zero is an alias for everything.
4800 * @param ppvMapping Where to return the mapping corresponding to @a offSub.
4801 *
4802 * @thread EMT(0)
4803 * @note Only available at VM creation time.
4804 *
4805 * @sa PDMDevHlpMmio2Create().
4806 */
4807 DECLR0CALLBACKMEMBER(int, pfnMmio2SetUpContext,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, size_t offSub, size_t cbSub,
4808 void **ppvMapping));
4809
4810 /**
4811 * Bus master physical memory read from the given PCI device.
4812 *
4813 * @returns VINF_SUCCESS or VERR_PDM_NOT_PCI_BUS_MASTER, later maybe
4814 * VERR_EM_MEMORY.
4815 * @param pDevIns The device instance.
4816 * @param pPciDev The PCI device structure. If NULL the default
4817 * PCI device for this device instance is used.
4818 * @param GCPhys Physical address start reading from.
4819 * @param pvBuf Where to put the read bits.
4820 * @param cbRead How many bytes to read.
4821 * @thread Any thread, but the call may involve the emulation thread.
4822 */
4823 DECLR0CALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
4824 void *pvBuf, size_t cbRead));
4825
4826 /**
4827 * Bus master physical memory write from the given PCI device.
4828 *
4829 * @returns VINF_SUCCESS or VERR_PDM_NOT_PCI_BUS_MASTER, later maybe
4830 * VERR_EM_MEMORY.
4831 * @param pDevIns The device instance.
4832 * @param pPciDev The PCI device structure. If NULL the default
4833 * PCI device for this device instance is used.
4834 * @param GCPhys Physical address to write to.
4835 * @param pvBuf What to write.
4836 * @param cbWrite How many bytes to write.
4837 * @thread Any thread, but the call may involve the emulation thread.
4838 */
4839 DECLR0CALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
4840 const void *pvBuf, size_t cbWrite));
4841
4842 /**
4843 * Set the IRQ for the given PCI device.
4844 *
4845 * @param pDevIns Device instance.
4846 * @param pPciDev The PCI device structure. If NULL the default
4847 * PCI device for this device instance is used.
4848 * @param iIrq IRQ number to set.
4849 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
4850 * @thread Any thread, but will involve the emulation thread.
4851 */
4852 DECLR0CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
4853
4854 /**
4855 * Set ISA IRQ for a device.
4856 *
4857 * @param pDevIns Device instance.
4858 * @param iIrq IRQ number to set.
4859 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
4860 * @thread Any thread, but will involve the emulation thread.
4861 */
4862 DECLR0CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4863
4864 /**
4865 * Send an MSI straight to the I/O APIC.
4866 *
4867 * @param pDevIns PCI device instance.
4868 * @param GCPhys Physical address MSI request was written.
4869 * @param uValue Value written.
4870 * @thread Any thread, but will involve the emulation thread.
4871 */
4872 DECLR0CALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue));
4873
4874 /**
4875 * Read physical memory.
4876 *
4877 * @returns VINF_SUCCESS (for now).
4878 * @param pDevIns Device instance.
4879 * @param GCPhys Physical address start reading from.
4880 * @param pvBuf Where to put the read bits.
4881 * @param cbRead How many bytes to read.
4882 */
4883 DECLR0CALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
4884
4885 /**
4886 * Write to physical memory.
4887 *
4888 * @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
4889 * @param pDevIns Device instance.
4890 * @param GCPhys Physical address to write to.
4891 * @param pvBuf What to write.
4892 * @param cbWrite How many bytes to write.
4893 */
4894 DECLR0CALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
4895
4896 /**
4897 * Checks if the Gate A20 is enabled or not.
4898 *
4899 * @returns true if A20 is enabled.
4900 * @returns false if A20 is disabled.
4901 * @param pDevIns Device instance.
4902 * @thread The emulation thread.
4903 */
4904 DECLR0CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
4905
4906 /**
4907 * Gets the VM state.
4908 *
4909 * @returns VM state.
4910 * @param pDevIns The device instance.
4911 * @thread Any thread (just keep in mind that it's volatile info).
4912 */
4913 DECLR0CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
4914
4915 /**
4916 * Set the VM error message
4917 *
4918 * @returns rc.
4919 * @param pDevIns Driver instance.
4920 * @param rc VBox status code.
4921 * @param SRC_POS Use RT_SRC_POS.
4922 * @param pszFormat Error message format string.
4923 * @param ... Error message arguments.
4924 */
4925 DECLR0CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
4926 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(6, 7));
4927
4928 /**
4929 * Set the VM error message
4930 *
4931 * @returns rc.
4932 * @param pDevIns Driver instance.
4933 * @param rc VBox status code.
4934 * @param SRC_POS Use RT_SRC_POS.
4935 * @param pszFormat Error message format string.
4936 * @param va Error message arguments.
4937 */
4938 DECLR0CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
4939 const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
4940
4941 /**
4942 * Set the VM runtime error message
4943 *
4944 * @returns VBox status code.
4945 * @param pDevIns Device instance.
4946 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
4947 * @param pszErrorId Error ID string.
4948 * @param pszFormat Error message format string.
4949 * @param ... Error message arguments.
4950 */
4951 DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
4952 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5));
4953
4954 /**
4955 * Set the VM runtime error message
4956 *
4957 * @returns VBox status code.
4958 * @param pDevIns Device instance.
4959 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
4960 * @param pszErrorId Error ID string.
4961 * @param pszFormat Error message format string.
4962 * @param va Error message arguments.
4963 */
4964 DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
4965 const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0));
4966
4967 /**
4968 * Gets the VM handle. Restricted API.
4969 *
4970 * @returns VM Handle.
4971 * @param pDevIns Device instance.
4972 */
4973 DECLR0CALLBACKMEMBER(PVMCC, pfnGetVM,(PPDMDEVINS pDevIns));
4974
4975 /**
4976 * Gets the VMCPU handle. Restricted API.
4977 *
4978 * @returns VMCPU Handle.
4979 * @param pDevIns The device instance.
4980 */
4981 DECLR0CALLBACKMEMBER(PVMCPUCC, pfnGetVMCPU,(PPDMDEVINS pDevIns));
4982
4983 /**
4984 * The the VM CPU ID of the current thread (restricted API).
4985 *
4986 * @returns The VMCPUID of the calling thread, NIL_VMCPUID if not EMT.
4987 * @param pDevIns The device instance.
4988 */
4989 DECLR0CALLBACKMEMBER(VMCPUID, pfnGetCurrentCpuId,(PPDMDEVINS pDevIns));
4990
4991 /**
4992 * Translates a timer handle to a pointer.
4993 *
4994 * @returns The time address.
4995 * @param pDevIns The device instance.
4996 * @param hTimer The timer handle.
4997 */
4998 DECLR0CALLBACKMEMBER(PTMTIMERR0, pfnTimerToPtr,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
4999
5000 /** @name Timer handle method wrappers
5001 * @{ */
5002 DECLR0CALLBACKMEMBER(uint64_t, pfnTimerFromMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicroSecs));
5003 DECLR0CALLBACKMEMBER(uint64_t, pfnTimerFromMilli,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliSecs));
5004 DECLR0CALLBACKMEMBER(uint64_t, pfnTimerFromNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanoSecs));
5005 DECLR0CALLBACKMEMBER(uint64_t, pfnTimerGet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5006 DECLR0CALLBACKMEMBER(uint64_t, pfnTimerGetFreq,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5007 DECLR0CALLBACKMEMBER(uint64_t, pfnTimerGetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5008 DECLR0CALLBACKMEMBER(bool, pfnTimerIsActive,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5009 DECLR0CALLBACKMEMBER(bool, pfnTimerIsLockOwner,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5010 DECLR0CALLBACKMEMBER(int, pfnTimerLock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, int rcBusy));
5011 DECLR0CALLBACKMEMBER(int, pfnTimerSet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t uExpire));
5012 DECLR0CALLBACKMEMBER(int, pfnTimerSetFrequencyHint,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint32_t uHz));
5013 DECLR0CALLBACKMEMBER(int, pfnTimerSetMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicrosToNext));
5014 DECLR0CALLBACKMEMBER(int, pfnTimerSetMillies,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliesToNext));
5015 DECLR0CALLBACKMEMBER(int, pfnTimerSetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanosToNext));
5016 DECLR0CALLBACKMEMBER(int, pfnTimerSetRelative,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cTicksToNext, uint64_t *pu64Now));
5017 DECLR0CALLBACKMEMBER(int, pfnTimerStop,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5018 DECLR0CALLBACKMEMBER(void, pfnTimerUnlock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5019 /** @} */
5020
5021 /**
5022 * Get the current virtual clock time in a VM. The clock frequency must be
5023 * queried separately.
5024 *
5025 * @returns Current clock time.
5026 * @param pDevIns The device instance.
5027 */
5028 DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
5029
5030 /**
5031 * Get the frequency of the virtual clock.
5032 *
5033 * @returns The clock frequency (not variable at run-time).
5034 * @param pDevIns The device instance.
5035 */
5036 DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
5037
5038 /**
5039 * Get the current virtual clock time in a VM, in nanoseconds.
5040 *
5041 * @returns Current clock time (in ns).
5042 * @param pDevIns The device instance.
5043 */
5044 DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
5045
5046 /** @name Exported PDM Queue Functions
5047 * @{ */
5048 DECLR0CALLBACKMEMBER(PPDMQUEUE, pfnQueueToPtr,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
5049 DECLR0CALLBACKMEMBER(PPDMQUEUEITEMCORE, pfnQueueAlloc,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
5050 DECLR0CALLBACKMEMBER(void, pfnQueueInsert,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem));
5051 DECLR0CALLBACKMEMBER(void, pfnQueueInsertEx,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem, uint64_t cNanoMaxDelay));
5052 DECLR0CALLBACKMEMBER(bool, pfnQueueFlushIfNecessary,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
5053 /** @} */
5054
5055 /** @name PDM Task
5056 * @{ */
5057 /**
5058 * Triggers the running the given task.
5059 *
5060 * @returns VBox status code.
5061 * @retval VINF_ALREADY_POSTED is the task is already pending.
5062 * @param pDevIns The device instance.
5063 * @param hTask The task to trigger.
5064 * @thread Any thread.
5065 */
5066 DECLR0CALLBACKMEMBER(int, pfnTaskTrigger,(PPDMDEVINS pDevIns, PDMTASKHANDLE hTask));
5067 /** @} */
5068
5069 /** @name SUP Event Semaphore Wrappers (single release / auto reset)
5070 * These semaphores can be signalled from ring-0.
5071 * @{ */
5072 /** @sa SUPSemEventSignal */
5073 DECLR0CALLBACKMEMBER(int, pfnSUPSemEventSignal,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent));
5074 /** @sa SUPSemEventWaitNoResume */
5075 DECLR0CALLBACKMEMBER(int, pfnSUPSemEventWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint32_t cMillies));
5076 /** @sa SUPSemEventWaitNsAbsIntr */
5077 DECLR0CALLBACKMEMBER(int, pfnSUPSemEventWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t uNsTimeout));
5078 /** @sa SUPSemEventWaitNsRelIntr */
5079 DECLR0CALLBACKMEMBER(int, pfnSUPSemEventWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t cNsTimeout));
5080 /** @sa SUPSemEventGetResolution */
5081 DECLR0CALLBACKMEMBER(uint32_t, pfnSUPSemEventGetResolution,(PPDMDEVINS pDevIns));
5082 /** @} */
5083
5084 /** @name SUP Multi Event Semaphore Wrappers (multiple release / manual reset)
5085 * These semaphores can be signalled from ring-0.
5086 * @{ */
5087 /** @sa SUPSemEventMultiSignal */
5088 DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiSignal,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
5089 /** @sa SUPSemEventMultiReset */
5090 DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiReset,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
5091 /** @sa SUPSemEventMultiWaitNoResume */
5092 DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint32_t cMillies));
5093 /** @sa SUPSemEventMultiWaitNsAbsIntr */
5094 DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t uNsTimeout));
5095 /** @sa SUPSemEventMultiWaitNsRelIntr */
5096 DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t cNsTimeout));
5097 /** @sa SUPSemEventMultiGetResolution */
5098 DECLR0CALLBACKMEMBER(uint32_t, pfnSUPSemEventMultiGetResolution,(PPDMDEVINS pDevIns));
5099 /** @} */
5100
5101 /**
5102 * Gets the NOP critical section.
5103 *
5104 * @returns The ring-3 address of the NOP critical section.
5105 * @param pDevIns The device instance.
5106 */
5107 DECLR0CALLBACKMEMBER(PPDMCRITSECT, pfnCritSectGetNop,(PPDMDEVINS pDevIns));
5108
5109 /**
5110 * Changes the device level critical section from the automatically created
5111 * default to one desired by the device constructor.
5112 *
5113 * Must first be done in ring-3.
5114 *
5115 * @returns VBox status code.
5116 * @param pDevIns The device instance.
5117 * @param pCritSect The critical section to use. NULL is not
5118 * valid, instead use the NOP critical
5119 * section.
5120 */
5121 DECLR0CALLBACKMEMBER(int, pfnSetDeviceCritSect,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5122
5123 /** @name Exported PDM Critical Section Functions
5124 * @{ */
5125 DECLR0CALLBACKMEMBER(int, pfnCritSectEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy));
5126 DECLR0CALLBACKMEMBER(int, pfnCritSectEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5127 DECLR0CALLBACKMEMBER(int, pfnCritSectTryEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5128 DECLR0CALLBACKMEMBER(int, pfnCritSectTryEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5129 DECLR0CALLBACKMEMBER(int, pfnCritSectLeave,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5130 DECLR0CALLBACKMEMBER(bool, pfnCritSectIsOwner,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5131 DECLR0CALLBACKMEMBER(bool, pfnCritSectIsInitialized,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5132 DECLR0CALLBACKMEMBER(bool, pfnCritSectHasWaiters,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5133 DECLR0CALLBACKMEMBER(uint32_t, pfnCritSectGetRecursion,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5134 DECLR0CALLBACKMEMBER(int, pfnCritSectScheduleExitEvent,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, SUPSEMEVENT hEventToSignal));
5135 /** @} */
5136
5137 /**
5138 * Gets the trace buffer handle.
5139 *
5140 * This is used by the macros found in VBox/vmm/dbgftrace.h and is not
5141 * really inteded for direct usage, thus no inline wrapper function.
5142 *
5143 * @returns Trace buffer handle or NIL_RTTRACEBUF.
5144 * @param pDevIns The device instance.
5145 */
5146 DECLR0CALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
5147
5148 /**
5149 * Sets up the PCI bus for the ring-0 context.
5150 *
5151 * This must be called after ring-3 has registered the PCI bus using
5152 * PDMDevHlpPCIBusRegister().
5153 *
5154 * @returns VBox status code.
5155 * @param pDevIns The device instance.
5156 * @param pPciBusReg The PCI bus registration information for ring-0,
5157 * considered volatile and copied.
5158 * @param ppPciHlp Where to return the ring-0 PCI bus helpers.
5159 */
5160 DECLR0CALLBACKMEMBER(int, pfnPCIBusSetUpContext,(PPDMDEVINS pDevIns, PPDMPCIBUSREGR0 pPciBusReg, PCPDMPCIHLPR0 *ppPciHlp));
5161
5162 /**
5163 * Sets up the PIC for the ring-0 context.
5164 *
5165 * This must be called after ring-3 has registered the PIC using
5166 * PDMDevHlpPICRegister().
5167 *
5168 * @returns VBox status code.
5169 * @param pDevIns The device instance.
5170 * @param pPicReg The PIC registration information for ring-0,
5171 * considered volatile and copied.
5172 * @param ppPicHlp Where to return the ring-0 PIC helpers.
5173 */
5174 DECLR0CALLBACKMEMBER(int, pfnPICSetUpContext,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp));
5175
5176 /**
5177 * Sets up the IOAPIC for the ring-0 context.
5178 *
5179 * This must be called after ring-3 has registered the PIC using
5180 * PDMDevHlpIoApicRegister().
5181 *
5182 * @returns VBox status code.
5183 * @param pDevIns The device instance.
5184 * @param pIoApicReg The PIC registration information for ring-0,
5185 * considered volatile and copied.
5186 * @param ppIoApicHlp Where to return the ring-0 IOAPIC helpers.
5187 */
5188 DECLR0CALLBACKMEMBER(int, pfnIoApicSetUpContext,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp));
5189
5190 /**
5191 * Sets up the HPET for the ring-0 context.
5192 *
5193 * This must be called after ring-3 has registered the PIC using
5194 * PDMDevHlpHpetRegister().
5195 *
5196 * @returns VBox status code.
5197 * @param pDevIns The device instance.
5198 * @param pHpetReg The PIC registration information for ring-0,
5199 * considered volatile and copied.
5200 * @param ppHpetHlp Where to return the ring-0 HPET helpers.
5201 */
5202 DECLR0CALLBACKMEMBER(int, pfnHpetSetUpContext,(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPR0 *ppHpetHlp));
5203
5204 /** Space reserved for future members.
5205 * @{ */
5206 DECLR0CALLBACKMEMBER(void, pfnReserved1,(void));
5207 DECLR0CALLBACKMEMBER(void, pfnReserved2,(void));
5208 DECLR0CALLBACKMEMBER(void, pfnReserved3,(void));
5209 DECLR0CALLBACKMEMBER(void, pfnReserved4,(void));
5210 DECLR0CALLBACKMEMBER(void, pfnReserved5,(void));
5211 DECLR0CALLBACKMEMBER(void, pfnReserved6,(void));
5212 DECLR0CALLBACKMEMBER(void, pfnReserved7,(void));
5213 DECLR0CALLBACKMEMBER(void, pfnReserved8,(void));
5214 DECLR0CALLBACKMEMBER(void, pfnReserved9,(void));
5215 DECLR0CALLBACKMEMBER(void, pfnReserved10,(void));
5216 /** @} */
5217
5218 /** Just a safety precaution. */
5219 uint32_t u32TheEnd;
5220} PDMDEVHLPR0;
5221/** Pointer PDM Device R0 API. */
5222typedef R0PTRTYPE(struct PDMDEVHLPR0 *) PPDMDEVHLPR0;
5223/** Pointer PDM Device GC API. */
5224typedef R0PTRTYPE(const struct PDMDEVHLPR0 *) PCPDMDEVHLPR0;
5225
5226/** Current PDMDEVHLP version number. */
5227#define PDM_DEVHLPR0_VERSION PDM_VERSION_MAKE(0xffe5, 14, 0)
5228
5229
5230/**
5231 * PDM Device Instance.
5232 */
5233typedef struct PDMDEVINSR3
5234{
5235 /** Structure version. PDM_DEVINSR3_VERSION defines the current version. */
5236 uint32_t u32Version;
5237 /** Device instance number. */
5238 uint32_t iInstance;
5239 /** Size of the ring-3, raw-mode and shared bits. */
5240 uint32_t cbRing3;
5241 /** Set if ring-0 context is enabled. */
5242 bool fR0Enabled;
5243 /** Set if raw-mode context is enabled. */
5244 bool fRCEnabled;
5245 /** Alignment padding. */
5246 bool afReserved[2];
5247 /** Pointer the HC PDM Device API. */
5248 PCPDMDEVHLPR3 pHlpR3;
5249 /** Pointer to the shared device instance data. */
5250 RTR3PTR pvInstanceDataR3;
5251 /** Pointer to the device instance data for ring-3. */
5252 RTR3PTR pvInstanceDataForR3;
5253 /** The critical section for the device.
5254 *
5255 * TM and IOM will enter this critical section before calling into the device
5256 * code. PDM will when doing power on, power off, reset, suspend and resume
5257 * notifications. SSM will currently not, but this will be changed later on.
5258 *
5259 * The device gets a critical section automatically assigned to it before
5260 * the constructor is called. If the constructor wishes to use a different
5261 * critical section, it calls PDMDevHlpSetDeviceCritSect() to change it
5262 * very early on.
5263 */
5264 R3PTRTYPE(PPDMCRITSECT) pCritSectRoR3;
5265 /** Pointer to device registration structure. */
5266 R3PTRTYPE(PCPDMDEVREG) pReg;
5267 /** Configuration handle. */
5268 R3PTRTYPE(PCFGMNODE) pCfg;
5269 /** The base interface of the device.
5270 *
5271 * The device constructor initializes this if it has any
5272 * device level interfaces to export. To obtain this interface
5273 * call PDMR3QueryDevice(). */
5274 PDMIBASE IBase;
5275
5276 /** Tracing indicator. */
5277 uint32_t fTracing;
5278 /** The tracing ID of this device. */
5279 uint32_t idTracing;
5280
5281 /** Ring-3 pointer to the raw-mode device instance. */
5282 R3PTRTYPE(struct PDMDEVINSRC *) pDevInsForRCR3;
5283 /** Raw-mode address of the raw-mode device instance. */
5284 RTRGPTR pDevInsForRC;
5285 /** Ring-3 pointer to the raw-mode instance data. */
5286 RTR3PTR pvInstanceDataForRCR3;
5287
5288 /** PCI device structure size. */
5289 uint32_t cbPciDev;
5290 /** Number of PCI devices in apPciDevs. */
5291 uint32_t cPciDevs;
5292 /** Pointer to the PCI devices for this device.
5293 * (Allocated after the shared instance data.)
5294 * @note If we want to extend this beyond 8 sub-functions/devices, those 1 or
5295 * two devices ever needing it can use cbPciDev and do the address
5296 * calculations that for entries 8+. */
5297 R3PTRTYPE(struct PDMPCIDEV *) apPciDevs[8];
5298
5299 /** Temporarily. */
5300 R0PTRTYPE(struct PDMDEVINSR0 *) pDevInsR0RemoveMe;
5301 /** Temporarily. */
5302 RTR0PTR pvInstanceDataR0;
5303 /** Temporarily. */
5304 RTRCPTR pvInstanceDataRC;
5305 /** Align the internal data more naturally. */
5306 uint32_t au32Padding[HC_ARCH_BITS == 32 ? 13 : 11];
5307
5308 /** Internal data. */
5309 union
5310 {
5311#ifdef PDMDEVINSINT_DECLARED
5312 PDMDEVINSINTR3 s;
5313#endif
5314 uint8_t padding[HC_ARCH_BITS == 32 ? 0x30 : 0x50];
5315 } Internal;
5316
5317 /** Device instance data for ring-3. The size of this area is defined
5318 * in the PDMDEVREG::cbInstanceR3 field. */
5319 char achInstanceData[8];
5320} PDMDEVINSR3;
5321
5322/** Current PDMDEVINSR3 version number. */
5323#define PDM_DEVINSR3_VERSION PDM_VERSION_MAKE(0xff82, 4, 0)
5324
5325/** Converts a pointer to the PDMDEVINSR3::IBase to a pointer to PDMDEVINS. */
5326#define PDMIBASE_2_PDMDEV(pInterface) ( (PPDMDEVINS)((char *)(pInterface) - RT_UOFFSETOF(PDMDEVINS, IBase)) )
5327
5328
5329/**
5330 * PDM ring-0 device instance.
5331 */
5332typedef struct PDMDEVINSR0
5333{
5334 /** Structure version. PDM_DEVINSR0_VERSION defines the current version. */
5335 uint32_t u32Version;
5336 /** Device instance number. */
5337 uint32_t iInstance;
5338
5339 /** Pointer the HC PDM Device API. */
5340 PCPDMDEVHLPR0 pHlpR0;
5341 /** Pointer to the shared device instance data. */
5342 RTR0PTR pvInstanceDataR0;
5343 /** Pointer to the device instance data for ring-0. */
5344 RTR0PTR pvInstanceDataForR0;
5345 /** The critical section for the device.
5346 *
5347 * TM and IOM will enter this critical section before calling into the device
5348 * code. PDM will when doing power on, power off, reset, suspend and resume
5349 * notifications. SSM will currently not, but this will be changed later on.
5350 *
5351 * The device gets a critical section automatically assigned to it before
5352 * the constructor is called. If the constructor wishes to use a different
5353 * critical section, it calls PDMDevHlpSetDeviceCritSect() to change it
5354 * very early on.
5355 */
5356 R0PTRTYPE(PPDMCRITSECT) pCritSectRoR0;
5357 /** Pointer to the ring-0 device registration structure. */
5358 R0PTRTYPE(PCPDMDEVREGR0) pReg;
5359 /** Ring-3 address of the ring-3 device instance. */
5360 R3PTRTYPE(struct PDMDEVINSR3 *) pDevInsForR3;
5361 /** Ring-0 pointer to the ring-3 device instance. */
5362 R0PTRTYPE(struct PDMDEVINSR3 *) pDevInsForR3R0;
5363 /** Ring-0 pointer to the ring-3 instance data. */
5364 RTR0PTR pvInstanceDataForR3R0;
5365 /** Raw-mode address of the raw-mode device instance. */
5366 RGPTRTYPE(struct PDMDEVINSRC *) pDevInsForRC;
5367 /** Ring-0 pointer to the raw-mode device instance. */
5368 R0PTRTYPE(struct PDMDEVINSRC *) pDevInsForRCR0;
5369 /** Ring-0 pointer to the raw-mode instance data. */
5370 RTR0PTR pvInstanceDataForRCR0;
5371
5372 /** PCI device structure size. */
5373 uint32_t cbPciDev;
5374 /** Number of PCI devices in apPciDevs. */
5375 uint32_t cPciDevs;
5376 /** Pointer to the PCI devices for this device.
5377 * (Allocated after the shared instance data.)
5378 * @note If we want to extend this beyond 8 sub-functions/devices, those 1 or
5379 * two devices ever needing it can use cbPciDev and do the address
5380 * calculations that for entries 8+. */
5381 R0PTRTYPE(struct PDMPCIDEV *) apPciDevs[8];
5382
5383 /** Align the internal data more naturally. */
5384 uint32_t au32Padding[HC_ARCH_BITS == 32 ? 3 : 2 + 4];
5385
5386 /** Internal data. */
5387 union
5388 {
5389#ifdef PDMDEVINSINT_DECLARED
5390 PDMDEVINSINTR0 s;
5391#endif
5392 uint8_t padding[HC_ARCH_BITS == 32 ? 0x20 : 0x40];
5393 } Internal;
5394
5395 /** Device instance data for ring-0. The size of this area is defined
5396 * in the PDMDEVREG::cbInstanceR0 field. */
5397 char achInstanceData[8];
5398} PDMDEVINSR0;
5399
5400/** Current PDMDEVINSR0 version number. */
5401#define PDM_DEVINSR0_VERSION PDM_VERSION_MAKE(0xff83, 4, 0)
5402
5403
5404/**
5405 * PDM raw-mode device instance.
5406 */
5407typedef struct PDMDEVINSRC
5408{
5409 /** Structure version. PDM_DEVINSRC_VERSION defines the current version. */
5410 uint32_t u32Version;
5411 /** Device instance number. */
5412 uint32_t iInstance;
5413
5414 /** Pointer the HC PDM Device API. */
5415 PCPDMDEVHLPRC pHlpRC;
5416 /** Pointer to the shared device instance data. */
5417 RTRGPTR pvInstanceDataRC;
5418 /** Pointer to the device instance data for raw-mode. */
5419 RTRGPTR pvInstanceDataForRC;
5420 /** The critical section for the device.
5421 *
5422 * TM and IOM will enter this critical section before calling into the device
5423 * code. PDM will when doing power on, power off, reset, suspend and resume
5424 * notifications. SSM will currently not, but this will be changed later on.
5425 *
5426 * The device gets a critical section automatically assigned to it before
5427 * the constructor is called. If the constructor wishes to use a different
5428 * critical section, it calls PDMDevHlpSetDeviceCritSect() to change it
5429 * very early on.
5430 */
5431 RGPTRTYPE(PPDMCRITSECT) pCritSectRoRC;
5432 /** Pointer to the raw-mode device registration structure. */
5433 RGPTRTYPE(PCPDMDEVREGRC) pReg;
5434
5435 /** PCI device structure size. */
5436 uint32_t cbPciDev;
5437 /** Number of PCI devices in apPciDevs. */
5438 uint32_t cPciDevs;
5439 /** Pointer to the PCI devices for this device.
5440 * (Allocated after the shared instance data.) */
5441 RGPTRTYPE(struct PDMPCIDEV *) apPciDevs[8];
5442
5443 /** Align the internal data more naturally. */
5444 uint32_t au32Padding[14];
5445
5446 /** Internal data. */
5447 union
5448 {
5449#ifdef PDMDEVINSINT_DECLARED
5450 PDMDEVINSINTRC s;
5451#endif
5452 uint8_t padding[0x10];
5453 } Internal;
5454
5455 /** Device instance data for ring-0. The size of this area is defined
5456 * in the PDMDEVREG::cbInstanceR0 field. */
5457 char achInstanceData[8];
5458} PDMDEVINSRC;
5459
5460/** Current PDMDEVINSR0 version number. */
5461#define PDM_DEVINSRC_VERSION PDM_VERSION_MAKE(0xff84, 4, 0)
5462
5463
5464/** @def PDM_DEVINS_VERSION
5465 * Current PDMDEVINS version number. */
5466/** @typedef PDMDEVINS
5467 * The device instance structure for the current context. */
5468#ifdef IN_RING3
5469# define PDM_DEVINS_VERSION PDM_DEVINSR3_VERSION
5470typedef PDMDEVINSR3 PDMDEVINS;
5471#elif defined(IN_RING0)
5472# define PDM_DEVINS_VERSION PDM_DEVINSR0_VERSION
5473typedef PDMDEVINSR0 PDMDEVINS;
5474#elif defined(IN_RC)
5475# define PDM_DEVINS_VERSION PDM_DEVINSRC_VERSION
5476typedef PDMDEVINSRC PDMDEVINS;
5477#else
5478# error "Missing context defines: IN_RING0, IN_RING3, IN_RC"
5479#endif
5480
5481/**
5482 * Get the pointer to an PCI device.
5483 * @note Returns NULL if @a a_idxPciDev is out of bounds.
5484 */
5485#define PDMDEV_GET_PPCIDEV(a_pDevIns, a_idxPciDev) \
5486 ( (uintptr_t)(a_idxPciDev) < RT_ELEMENTS((a_pDevIns)->apPciDevs) ? (a_pDevIns)->apPciDevs[(uintptr_t)(a_idxPciDev)] \
5487 : PDMDEV_CALC_PPCIDEV(a_pDevIns, a_idxPciDev) )
5488
5489/**
5490 * Calc the pointer to of a given PCI device.
5491 * @note Returns NULL if @a a_idxPciDev is out of bounds.
5492 */
5493#define PDMDEV_CALC_PPCIDEV(a_pDevIns, a_idxPciDev) \
5494 ( (uintptr_t)(a_idxPciDev) < (a_pDevIns)->cPciDevs \
5495 ? (PPDMPCIDEV)((uint8_t *)((a_pDevIns)->apPciDevs[0]) + (a_pDevIns->cbPciDev) * (uintptr_t)(a_idxPciDev)) \
5496 : (PPDMPCIDEV)NULL )
5497
5498
5499/**
5500 * Checks the structure versions of the device instance and device helpers,
5501 * returning if they are incompatible.
5502 *
5503 * This is for use in the constructor.
5504 *
5505 * @param pDevIns The device instance pointer.
5506 */
5507#define PDMDEV_CHECK_VERSIONS_RETURN(pDevIns) \
5508 do \
5509 { \
5510 PPDMDEVINS pDevInsTypeCheck = (pDevIns); NOREF(pDevInsTypeCheck); \
5511 AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->u32Version, PDM_DEVINS_VERSION), \
5512 ("DevIns=%#x mine=%#x\n", (pDevIns)->u32Version, PDM_DEVINS_VERSION), \
5513 VERR_PDM_DEVINS_VERSION_MISMATCH); \
5514 AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->CTX_SUFF(pHlp)->u32Version, CTX_MID(PDM_DEVHLP,_VERSION)), \
5515 ("DevHlp=%#x mine=%#x\n", (pDevIns)->CTX_SUFF(pHlp)->u32Version, CTX_MID(PDM_DEVHLP,_VERSION)), \
5516 VERR_PDM_DEVHLP_VERSION_MISMATCH); \
5517 } while (0)
5518
5519/**
5520 * Quietly checks the structure versions of the device instance and device
5521 * helpers, returning if they are incompatible.
5522 *
5523 * This is for use in the destructor.
5524 *
5525 * @param pDevIns The device instance pointer.
5526 */
5527#define PDMDEV_CHECK_VERSIONS_RETURN_QUIET(pDevIns) \
5528 do \
5529 { \
5530 PPDMDEVINS pDevInsTypeCheck = (pDevIns); NOREF(pDevInsTypeCheck); \
5531 if (RT_LIKELY(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->u32Version, PDM_DEVINS_VERSION) )) \
5532 { /* likely */ } else return VERR_PDM_DEVINS_VERSION_MISMATCH; \
5533 if (RT_LIKELY(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->CTX_SUFF(pHlp)->u32Version, CTX_MID(PDM_DEVHLP,_VERSION)) )) \
5534 { /* likely */ } else return VERR_PDM_DEVHLP_VERSION_MISMATCH; \
5535 } while (0)
5536
5537/**
5538 * Wrapper around CFGMR3ValidateConfig for the root config for use in the
5539 * constructor - returns on failure.
5540 *
5541 * This should be invoked after having initialized the instance data
5542 * sufficiently for the correct operation of the destructor. The destructor is
5543 * always called!
5544 *
5545 * @param pDevIns Pointer to the PDM device instance.
5546 * @param pszValidValues Patterns describing the valid value names. See
5547 * RTStrSimplePatternMultiMatch for details on the
5548 * pattern syntax.
5549 * @param pszValidNodes Patterns describing the valid node (key) names.
5550 * Pass empty string if no valid nodes.
5551 */
5552#define PDMDEV_VALIDATE_CONFIG_RETURN(pDevIns, pszValidValues, pszValidNodes) \
5553 do \
5554 { \
5555 int rcValCfg = pDevIns->pHlpR3->pfnCFGMValidateConfig((pDevIns)->pCfg, "/", pszValidValues, pszValidNodes, \
5556 (pDevIns)->pReg->szName, (pDevIns)->iInstance); \
5557 if (RT_SUCCESS(rcValCfg)) \
5558 { /* likely */ } else return rcValCfg; \
5559 } while (0)
5560
5561/** @def PDMDEV_ASSERT_EMT
5562 * Assert that the current thread is the emulation thread.
5563 */
5564#ifdef VBOX_STRICT
5565# define PDMDEV_ASSERT_EMT(pDevIns) pDevIns->pHlpR3->pfnAssertEMT(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5566#else
5567# define PDMDEV_ASSERT_EMT(pDevIns) do { } while (0)
5568#endif
5569
5570/** @def PDMDEV_ASSERT_OTHER
5571 * Assert that the current thread is NOT the emulation thread.
5572 */
5573#ifdef VBOX_STRICT
5574# define PDMDEV_ASSERT_OTHER(pDevIns) pDevIns->pHlpR3->pfnAssertOther(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5575#else
5576# define PDMDEV_ASSERT_OTHER(pDevIns) do { } while (0)
5577#endif
5578
5579/** @def PDMDEV_ASSERT_VMLOCK_OWNER
5580 * Assert that the current thread is owner of the VM lock.
5581 */
5582#ifdef VBOX_STRICT
5583# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) pDevIns->pHlpR3->pfnAssertVMLock(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5584#else
5585# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) do { } while (0)
5586#endif
5587
5588/** @def PDMDEV_SET_ERROR
5589 * Set the VM error. See PDMDevHlpVMSetError() for printf like message formatting.
5590 */
5591#define PDMDEV_SET_ERROR(pDevIns, rc, pszError) \
5592 PDMDevHlpVMSetError(pDevIns, rc, RT_SRC_POS, "%s", pszError)
5593
5594/** @def PDMDEV_SET_RUNTIME_ERROR
5595 * Set the VM runtime error. See PDMDevHlpVMSetRuntimeError() for printf like message formatting.
5596 */
5597#define PDMDEV_SET_RUNTIME_ERROR(pDevIns, fFlags, pszErrorId, pszError) \
5598 PDMDevHlpVMSetRuntimeError(pDevIns, fFlags, pszErrorId, "%s", pszError)
5599
5600/** @def PDMDEVINS_2_RCPTR
5601 * Converts a PDM Device instance pointer a RC PDM Device instance pointer.
5602 */
5603#ifdef IN_RC
5604# define PDMDEVINS_2_RCPTR(pDevIns) (pDevIns)
5605#else
5606# define PDMDEVINS_2_RCPTR(pDevIns) ( (pDevIns)->pDevInsForRC )
5607#endif
5608
5609/** @def PDMDEVINS_2_R3PTR
5610 * Converts a PDM Device instance pointer a R3 PDM Device instance pointer.
5611 */
5612#ifdef IN_RING3
5613# define PDMDEVINS_2_R3PTR(pDevIns) (pDevIns)
5614#else
5615# define PDMDEVINS_2_R3PTR(pDevIns) ( (pDevIns)->pDevInsForR3 )
5616#endif
5617
5618/** @def PDMDEVINS_2_R0PTR
5619 * Converts a PDM Device instance pointer a R0 PDM Device instance pointer.
5620 */
5621#ifdef IN_RING0
5622# define PDMDEVINS_2_R0PTR(pDevIns) (pDevIns)
5623#else
5624# define PDMDEVINS_2_R0PTR(pDevIns) ( (pDevIns)->pDevInsR0RemoveMe )
5625#endif
5626
5627/** @def PDMDEVINS_DATA_2_R0_REMOVE_ME
5628 * Converts a PDM device instance data pointer to a ring-0 one.
5629 * @deprecated
5630 */
5631#ifdef IN_RING0
5632# define PDMDEVINS_DATA_2_R0_REMOVE_ME(pDevIns, pvCC) (pvCC)
5633#else
5634# define PDMDEVINS_DATA_2_R0_REMOVE_ME(pDevIns, pvCC) ( (pDevIns)->pvInstanceDataR0 + (uintptr_t)(pvCC) - (uintptr_t)(pDevIns)->CTX_SUFF(pvInstanceData) )
5635#endif
5636
5637
5638/** @def PDMDEVINS_2_DATA
5639 * This is a safer edition of PDMINS_2_DATA that checks that the size of the
5640 * target type is same as PDMDEVREG::cbInstanceShared in strict builds.
5641 *
5642 * @note Do no use this macro in common code working on a core structure which
5643 * device specific code has expanded.
5644 */
5645#if defined(VBOX_STRICT) && defined(RT_COMPILER_SUPPORTS_LAMBDA)
5646# define PDMDEVINS_2_DATA(a_pDevIns, a_PtrType) \
5647 ([](PPDMDEVINS a_pLambdaDevIns) -> a_PtrType \
5648 { \
5649 a_PtrType pLambdaRet = (a_PtrType)(a_pLambdaDevIns)->CTX_SUFF(pvInstanceData); \
5650 Assert(sizeof(*pLambdaRet) == a_pLambdaDevIns->pReg->cbInstanceShared); \
5651 return pLambdaRet; \
5652 }(a_pDevIns))
5653#else
5654# define PDMDEVINS_2_DATA(a_pDevIns, a_PtrType) ( (a_PtrType)(a_pDevIns)->CTX_SUFF(pvInstanceData) )
5655#endif
5656
5657/** @def PDMDEVINS_2_DATA_CC
5658 * This is a safer edition of PDMINS_2_DATA_CC that checks that the size of the
5659 * target type is same as PDMDEVREG::cbInstanceCC in strict builds.
5660 *
5661 * @note Do no use this macro in common code working on a core structure which
5662 * device specific code has expanded.
5663 */
5664#if defined(VBOX_STRICT) && defined(RT_COMPILER_SUPPORTS_LAMBDA)
5665# define PDMDEVINS_2_DATA_CC(a_pDevIns, a_PtrType) \
5666 ([](PPDMDEVINS a_pLambdaDevIns) -> a_PtrType \
5667 { \
5668 a_PtrType pLambdaRet = (a_PtrType)&(a_pLambdaDevIns)->achInstanceData[0]; \
5669 Assert(sizeof(*pLambdaRet) == a_pLambdaDevIns->pReg->cbInstanceCC); \
5670 return pLambdaRet; \
5671 }(a_pDevIns))
5672#else
5673# define PDMDEVINS_2_DATA_CC(a_pDevIns, a_PtrType) ( (a_PtrType)(void *)&(a_pDevIns)->achInstanceData[0] )
5674#endif
5675
5676
5677#ifdef IN_RING3
5678
5679/**
5680 * @copydoc PDMDEVHLPR3::pfnIOPortRegister
5681 */
5682DECLINLINE(int) PDMDevHlpIOPortRegister(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTHCPTR pvUser,
5683 PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,
5684 PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc)
5685{
5686 return pDevIns->pHlpR3->pfnIOPortRegister(pDevIns, Port, cPorts, pvUser, pfnOut, pfnIn, pfnOutStr, pfnInStr, pszDesc);
5687}
5688
5689/**
5690 * @copydoc PDMDEVHLPR3::pfnIOPortRegisterRC
5691 */
5692DECLINLINE(int) PDMDevHlpIOPortRegisterRC(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTRCPTR pvUser,
5693 const char *pszOut, const char *pszIn, const char *pszOutStr,
5694 const char *pszInStr, const char *pszDesc)
5695{
5696 return pDevIns->pHlpR3->pfnIOPortRegisterRC(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);
5697}
5698
5699/**
5700 * @copydoc PDMDEVHLPR3::pfnIOPortRegisterR0
5701 */
5702DECLINLINE(int) PDMDevHlpIOPortRegisterR0(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTR0PTR pvUser,
5703 const char *pszOut, const char *pszIn, const char *pszOutStr,
5704 const char *pszInStr, const char *pszDesc)
5705{
5706 return pDevIns->pHlpR3->pfnIOPortRegisterR0(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);
5707}
5708
5709/**
5710 * @copydoc PDMDEVHLPR3::pfnIOPortDeregister
5711 */
5712DECLINLINE(int) PDMDevHlpIOPortDeregister(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts)
5713{
5714 return pDevIns->pHlpR3->pfnIOPortDeregister(pDevIns, Port, cPorts);
5715}
5716
5717/**
5718 * Combines PDMDevHlpIoPortCreate() & PDMDevHlpIoPortMap().
5719 */
5720DECLINLINE(int) PDMDevHlpIoPortCreateAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, PFNIOMIOPORTNEWOUT pfnOut,
5721 PFNIOMIOPORTNEWIN pfnIn, const char *pszDesc, PCIOMIOPORTDESC paExtDescs,
5722 PIOMIOPORTHANDLE phIoPorts)
5723{
5724 int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, NULL, UINT32_MAX,
5725 pfnOut, pfnIn, NULL, NULL, NULL, pszDesc, paExtDescs, phIoPorts);
5726 if (RT_SUCCESS(rc))
5727 rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
5728 return rc;
5729}
5730
5731/**
5732 * Combines PDMDevHlpIoPortCreate() & PDMDevHlpIoPortMap(), but with pvUser.
5733 */
5734DECLINLINE(int) PDMDevHlpIoPortCreateUAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, PFNIOMIOPORTNEWOUT pfnOut,
5735 PFNIOMIOPORTNEWIN pfnIn, void *pvUser,
5736 const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
5737{
5738 int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, NULL, UINT32_MAX,
5739 pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
5740 if (RT_SUCCESS(rc))
5741 rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
5742 return rc;
5743}
5744
5745/**
5746 * Combines PDMDevHlpIoPortCreate() & PDMDevHlpIoPortMap(), but with flags.
5747 */
5748DECLINLINE(int) PDMDevHlpIoPortCreateFlagsAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, uint32_t fFlags,
5749 PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
5750 const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
5751{
5752 int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, fFlags, NULL, UINT32_MAX,
5753 pfnOut, pfnIn, NULL, NULL, NULL, pszDesc, paExtDescs, phIoPorts);
5754 if (RT_SUCCESS(rc))
5755 rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
5756 return rc;
5757}
5758
5759/**
5760 * Combines PDMDevHlpIoPortCreateEx() & PDMDevHlpIoPortMap().
5761 */
5762DECLINLINE(int) PDMDevHlpIoPortCreateExAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, uint32_t fFlags,
5763 PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
5764 PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, void *pvUser,
5765 const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
5766{
5767 int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, fFlags, NULL, UINT32_MAX,
5768 pfnOut, pfnIn, pfnOutStr, pfnInStr, pvUser, pszDesc, paExtDescs, phIoPorts);
5769 if (RT_SUCCESS(rc))
5770 rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
5771 return rc;
5772}
5773
5774/**
5775 * @sa PDMDevHlpIoPortCreateEx
5776 */
5777DECLINLINE(int) PDMDevHlpIoPortCreate(PPDMDEVINS pDevIns, RTIOPORT cPorts, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
5778 PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn, void *pvUser, const char *pszDesc,
5779 PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
5780{
5781 return pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, pPciDev, iPciRegion,
5782 pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
5783}
5784
5785
5786/**
5787 * @sa PDMDevHlpIoPortCreateEx
5788 */
5789DECLINLINE(int) PDMDevHlpIoPortCreateIsa(PPDMDEVINS pDevIns, RTIOPORT cPorts, PFNIOMIOPORTNEWOUT pfnOut,
5790 PFNIOMIOPORTNEWIN pfnIn, void *pvUser, const char *pszDesc,
5791 PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
5792{
5793 return pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, NULL, UINT32_MAX,
5794 pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
5795}
5796
5797/**
5798 * @copydoc PDMDEVHLPR3::pfnIoPortCreateEx
5799 */
5800DECLINLINE(int) PDMDevHlpIoPortCreateEx(PPDMDEVINS pDevIns, RTIOPORT cPorts, uint32_t fFlags, PPDMPCIDEV pPciDev,
5801 uint32_t iPciRegion, PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
5802 PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, void *pvUser,
5803 const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
5804{
5805 return pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, fFlags, pPciDev, iPciRegion,
5806 pfnOut, pfnIn, pfnOutStr, pfnInStr, pvUser, pszDesc, paExtDescs, phIoPorts);
5807}
5808
5809/**
5810 * @copydoc PDMDEVHLPR3::pfnIoPortMap
5811 */
5812DECLINLINE(int) PDMDevHlpIoPortMap(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts, RTIOPORT Port)
5813{
5814 return pDevIns->pHlpR3->pfnIoPortMap(pDevIns, hIoPorts, Port);
5815}
5816
5817/**
5818 * @copydoc PDMDEVHLPR3::pfnIoPortUnmap
5819 */
5820DECLINLINE(int) PDMDevHlpIoPortUnmap(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts)
5821{
5822 return pDevIns->pHlpR3->pfnIoPortUnmap(pDevIns, hIoPorts);
5823}
5824
5825/**
5826 * @copydoc PDMDEVHLPR3::pfnIoPortGetMappingAddress
5827 */
5828DECLINLINE(uint32_t) PDMDevHlpIoPortGetMappingAddress(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts)
5829{
5830 return pDevIns->pHlpR3->pfnIoPortGetMappingAddress(pDevIns, hIoPorts);
5831}
5832
5833
5834#endif /* IN_RING3 */
5835#if !defined(IN_RING3) || defined(DOXYGEN_RUNNING)
5836
5837/**
5838 * @sa PDMDevHlpIoPortSetUpContextEx
5839 */
5840DECLINLINE(int) PDMDevHlpIoPortSetUpContext(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
5841 PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn, void *pvUser)
5842{
5843 return pDevIns->CTX_SUFF(pHlp)->pfnIoPortSetUpContextEx(pDevIns, hIoPorts, pfnOut, pfnIn, NULL, NULL, pvUser);
5844}
5845
5846/**
5847 * @copydoc PDMDEVHLPR0::pfnIoPortSetUpContextEx
5848 */
5849DECLINLINE(int) PDMDevHlpIoPortSetUpContextEx(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
5850 PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
5851 PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, void *pvUser)
5852{
5853 return pDevIns->CTX_SUFF(pHlp)->pfnIoPortSetUpContextEx(pDevIns, hIoPorts, pfnOut, pfnIn, pfnOutStr, pfnInStr, pvUser);
5854}
5855
5856#endif /* !IN_RING3 || DOXYGEN_RUNNING */
5857#ifdef IN_RING3
5858
5859/**
5860 * @sa PDMDevHlpMmioCreateEx
5861 */
5862DECLINLINE(int) PDMDevHlpMmioCreate(PPDMDEVINS pDevIns, RTGCPHYS cbRegion, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
5863 PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, void *pvUser,
5864 uint32_t fFlags, const char *pszDesc, PIOMMMIOHANDLE phRegion)
5865{
5866 return pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pPciDev, iPciRegion,
5867 pfnWrite, pfnRead, NULL, pvUser, pszDesc, phRegion);
5868}
5869
5870/**
5871 * @copydoc PDMDEVHLPR3::pfnMmioCreateEx
5872 */
5873DECLINLINE(int) PDMDevHlpMmioCreateEx(PPDMDEVINS pDevIns, RTGCPHYS cbRegion,
5874 uint32_t fFlags, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
5875 PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill,
5876 void *pvUser, const char *pszDesc, PIOMMMIOHANDLE phRegion)
5877{
5878 return pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pPciDev, iPciRegion,
5879 pfnWrite, pfnRead, pfnFill, pvUser, pszDesc, phRegion);
5880}
5881
5882/**
5883 * @sa PDMDevHlpMmioCreate and PDMDevHlpMmioMap
5884 */
5885DECLINLINE(int) PDMDevHlpMmioCreateAndMap(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPHYS cbRegion,
5886 PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead,
5887 uint32_t fFlags, const char *pszDesc, PIOMMMIOHANDLE phRegion)
5888{
5889 int rc = pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, NULL /*pPciDev*/, UINT32_MAX /*iPciRegion*/,
5890 pfnWrite, pfnRead, NULL /*pfnFill*/, NULL /*pvUser*/, pszDesc, phRegion);
5891 if (RT_SUCCESS(rc))
5892 rc = pDevIns->pHlpR3->pfnMmioMap(pDevIns, *phRegion, GCPhys);
5893 return rc;
5894}
5895
5896/**
5897 * @sa PDMDevHlpMmioCreateEx and PDMDevHlpMmioMap
5898 */
5899DECLINLINE(int) PDMDevHlpMmioCreateExAndMap(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPHYS cbRegion, uint32_t fFlags,
5900 PPDMPCIDEV pPciDev, uint32_t iPciRegion, PFNIOMMMIONEWWRITE pfnWrite,
5901 PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser,
5902 const char *pszDesc, PIOMMMIOHANDLE phRegion)
5903{
5904 int rc = pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pPciDev, iPciRegion,
5905 pfnWrite, pfnRead, pfnFill, pvUser, pszDesc, phRegion);
5906 if (RT_SUCCESS(rc))
5907 rc = pDevIns->pHlpR3->pfnMmioMap(pDevIns, *phRegion, GCPhys);
5908 return rc;
5909}
5910
5911/**
5912 * @copydoc PDMDEVHLPR3::pfnMmioMap
5913 */
5914DECLINLINE(int) PDMDevHlpMmioMap(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS GCPhys)
5915{
5916 return pDevIns->pHlpR3->pfnMmioMap(pDevIns, hRegion, GCPhys);
5917}
5918
5919/**
5920 * @copydoc PDMDEVHLPR3::pfnMmioUnmap
5921 */
5922DECLINLINE(int) PDMDevHlpMmioUnmap(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion)
5923{
5924 return pDevIns->pHlpR3->pfnMmioUnmap(pDevIns, hRegion);
5925}
5926
5927/**
5928 * @copydoc PDMDEVHLPR3::pfnMmioReduce
5929 */
5930DECLINLINE(int) PDMDevHlpMmioReduce(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS cbRegion)
5931{
5932 return pDevIns->pHlpR3->pfnMmioReduce(pDevIns, hRegion, cbRegion);
5933}
5934
5935/**
5936 * @copydoc PDMDEVHLPR3::pfnMmioGetMappingAddress
5937 */
5938DECLINLINE(RTGCPHYS) PDMDevHlpMmioGetMappingAddress(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion)
5939{
5940 return pDevIns->pHlpR3->pfnMmioGetMappingAddress(pDevIns, hRegion);
5941}
5942
5943#endif /* IN_RING3 */
5944#if !defined(IN_RING3) || defined(DOXYGEN_RUNNING)
5945
5946/**
5947 * @sa PDMDevHlpMmioSetUpContextEx
5948 */
5949DECLINLINE(int) PDMDevHlpMmioSetUpContext(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion,
5950 PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, void *pvUser)
5951{
5952 return pDevIns->CTX_SUFF(pHlp)->pfnMmioSetUpContextEx(pDevIns, hRegion, pfnWrite, pfnRead, NULL, pvUser);
5953}
5954
5955/**
5956 * @copydoc PDMDEVHLPR0::pfnMmioSetUpContextEx
5957 */
5958DECLINLINE(int) PDMDevHlpMmioSetUpContextEx(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, PFNIOMMMIONEWWRITE pfnWrite,
5959 PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser)
5960{
5961 return pDevIns->CTX_SUFF(pHlp)->pfnMmioSetUpContextEx(pDevIns, hRegion, pfnWrite, pfnRead, pfnFill, pvUser);
5962}
5963
5964#endif /* !IN_RING3 || DOXYGEN_RUNNING */
5965#ifdef IN_RING3
5966
5967/**
5968 * Register a Memory Mapped I/O (MMIO) region.
5969 *
5970 * These callbacks are of course for the ring-3 context (R3). Register HC
5971 * handlers before raw-mode context (RC) and ring-0 context (R0) handlers! There
5972 * must be a R3 handler for every RC and R0 handler!
5973 *
5974 * @returns VBox status.
5975 * @param pDevIns The device instance to register the MMIO with.
5976 * @param GCPhysStart First physical address in the range.
5977 * @param cbRange The size of the range (in bytes).
5978 * @param pvUser User argument.
5979 * @param fFlags Flags, IOMMMIO_FLAGS_XXX.
5980 * @param pfnWrite Pointer to function which is gonna handle Write operations.
5981 * @param pfnRead Pointer to function which is gonna handle Read operations.
5982 * @param pszDesc Pointer to description string. This must not be freed.
5983 */
5984DECLINLINE(int) PDMDevHlpMMIORegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTGCPHYS cbRange, RTHCPTR pvUser,
5985 uint32_t fFlags, PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, const char *pszDesc)
5986{
5987 return pDevIns->pHlpR3->pfnMMIORegister(pDevIns, GCPhysStart, cbRange, pvUser, pfnWrite, pfnRead, NULL /*pfnFill*/,
5988 fFlags, pszDesc);
5989}
5990
5991/**
5992 * Register a Memory Mapped I/O (MMIO) region for RC.
5993 *
5994 * These callbacks are for the raw-mode context (RC). Register ring-3 context
5995 * (R3) handlers before guest context handlers! There must be a R3 handler for
5996 * every RC handler!
5997 *
5998 * @returns VBox status.
5999 * @param pDevIns The device instance to register the MMIO with.
6000 * @param GCPhysStart First physical address in the range.
6001 * @param cbRange The size of the range (in bytes).
6002 * @param pvUser User argument.
6003 * @param pszWrite Name of the RC function which is gonna handle Write operations.
6004 * @param pszRead Name of the RC function which is gonna handle Read operations.
6005 */
6006DECLINLINE(int) PDMDevHlpMMIORegisterRC(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTGCPHYS cbRange, RTRCPTR pvUser,
6007 const char *pszWrite, const char *pszRead)
6008{
6009 return pDevIns->pHlpR3->pfnMMIORegisterRC(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, NULL /*pszFill*/);
6010}
6011
6012/**
6013 * Register a Memory Mapped I/O (MMIO) region for R0.
6014 *
6015 * These callbacks are for the ring-0 host context (R0). Register ring-3
6016 * constext (R3) handlers before R0 handlers! There must be a R3 handler for
6017 * every R0 handler!
6018 *
6019 * @returns VBox status.
6020 * @param pDevIns The device instance to register the MMIO with.
6021 * @param GCPhysStart First physical address in the range.
6022 * @param cbRange The size of the range (in bytes).
6023 * @param pvUser User argument. (if pointer, then it must be in locked memory!)
6024 * @param pszWrite Name of the RC function which is gonna handle Write operations.
6025 * @param pszRead Name of the RC function which is gonna handle Read operations.
6026 * @remarks Caller enters the device critical section prior to invoking the
6027 * registered callback methods.
6028 */
6029DECLINLINE(int) PDMDevHlpMMIORegisterR0(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTGCPHYS cbRange, RTR0PTR pvUser,
6030 const char *pszWrite, const char *pszRead)
6031{
6032 return pDevIns->pHlpR3->pfnMMIORegisterR0(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, NULL /*pszFill*/);
6033}
6034
6035/**
6036 * @copydoc PDMDEVHLPR3::pfnMMIORegister
6037 */
6038DECLINLINE(int) PDMDevHlpMMIORegisterEx(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTGCPHYS cbRange, RTHCPTR pvUser,
6039 uint32_t fFlags, PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead,
6040 PFNIOMMMIOFILL pfnFill, const char *pszDesc)
6041{
6042 return pDevIns->pHlpR3->pfnMMIORegister(pDevIns, GCPhysStart, cbRange, pvUser, pfnWrite, pfnRead, pfnFill,
6043 fFlags, pszDesc);
6044}
6045
6046/**
6047 * @copydoc PDMDEVHLPR3::pfnMMIORegisterRC
6048 */
6049DECLINLINE(int) PDMDevHlpMMIORegisterRCEx(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTGCPHYS cbRange, RTRCPTR pvUser,
6050 const char *pszWrite, const char *pszRead, const char *pszFill)
6051{
6052 return pDevIns->pHlpR3->pfnMMIORegisterRC(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill);
6053}
6054
6055/**
6056 * @copydoc PDMDEVHLPR3::pfnMMIORegisterR0
6057 */
6058DECLINLINE(int) PDMDevHlpMMIORegisterR0Ex(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTGCPHYS cbRange, RTR0PTR pvUser,
6059 const char *pszWrite, const char *pszRead, const char *pszFill)
6060{
6061 return pDevIns->pHlpR3->pfnMMIORegisterR0(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill);
6062}
6063
6064/**
6065 * @copydoc PDMDEVHLPR3::pfnMMIODeregister
6066 */
6067DECLINLINE(int) PDMDevHlpMMIODeregister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTGCPHYS cbRange)
6068{
6069 return pDevIns->pHlpR3->pfnMMIODeregister(pDevIns, GCPhysStart, cbRange);
6070}
6071
6072/**
6073 * @copydoc PDMDEVHLPR3::pfnMmio2Create
6074 */
6075DECLINLINE(int) PDMDevHlpMmio2Create(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iPciRegion, RTGCPHYS cbRegion,
6076 uint32_t fFlags, const char *pszDesc, void **ppvMapping, PPGMMMIO2HANDLE phRegion)
6077{
6078 return pDevIns->pHlpR3->pfnMmio2Create(pDevIns, pPciDev, iPciRegion, cbRegion, fFlags, pszDesc, ppvMapping, phRegion);
6079}
6080
6081/**
6082 * @copydoc PDMDEVHLPR3::pfnMmio2Map
6083 */
6084DECLINLINE(int) PDMDevHlpMmio2Map(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS GCPhys)
6085{
6086 return pDevIns->pHlpR3->pfnMmio2Map(pDevIns, hRegion, GCPhys);
6087}
6088
6089/**
6090 * @copydoc PDMDEVHLPR3::pfnMmio2Unmap
6091 */
6092DECLINLINE(int) PDMDevHlpMmio2Unmap(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion)
6093{
6094 return pDevIns->pHlpR3->pfnMmio2Unmap(pDevIns, hRegion);
6095}
6096
6097/**
6098 * @copydoc PDMDEVHLPR3::pfnMmio2Reduce
6099 */
6100DECLINLINE(int) PDMDevHlpMmio2Reduce(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS cbRegion)
6101{
6102 return pDevIns->pHlpR3->pfnMmio2Reduce(pDevIns, hRegion, cbRegion);
6103}
6104
6105/**
6106 * @copydoc PDMDEVHLPR3::pfnMmio2GetMappingAddress
6107 */
6108DECLINLINE(RTGCPHYS) PDMDevHlpMmio2GetMappingAddress(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion)
6109{
6110 return pDevIns->pHlpR3->pfnMmio2GetMappingAddress(pDevIns, hRegion);
6111}
6112
6113#endif /* IN_RING3 */
6114#if !defined(IN_RING3) || defined(DOXYGEN_RUNNING)
6115
6116/**
6117 * @copydoc PDMDEVHLPR0::pfnMmio2SetUpContext
6118 */
6119DECLINLINE(int) PDMDevHlpMmio2SetUpContext(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion,
6120 size_t offSub, size_t cbSub, void **ppvMapping)
6121{
6122 return pDevIns->CTX_SUFF(pHlp)->pfnMmio2SetUpContext(pDevIns, hRegion, offSub, cbSub, ppvMapping);
6123}
6124
6125#endif /* !IN_RING3 || DOXYGEN_RUNNING */
6126#ifdef IN_RING3
6127
6128/**
6129 * @copydoc PDMDEVHLPR3::pfnMMIO2Register
6130 */
6131DECLINLINE(int) PDMDevHlpMMIO2Register(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS cb,
6132 uint32_t fFlags, void **ppv, const char *pszDesc)
6133{
6134 return pDevIns->pHlpR3->pfnMMIO2Register(pDevIns, pPciDev, iRegion, cb, fFlags, ppv, pszDesc);
6135}
6136
6137/**
6138 * @copydoc PDMDEVHLPR3::pfnMMIOExDeregister
6139 * @param pPciDev The PCI device the region is associated with, use
6140 * NULL to indicate it is not associated with a device.
6141 */
6142DECLINLINE(int) PDMDevHlpMMIOExDeregister(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion)
6143{
6144 return pDevIns->pHlpR3->pfnMMIOExDeregister(pDevIns, pPciDev, iRegion);
6145}
6146
6147/**
6148 * @copydoc PDMDEVHLPR3::pfnMMIOExMap
6149 * @param pPciDev The PCI device the region is associated with, use
6150 * NULL to indicate it is not associated with a device.
6151 */
6152DECLINLINE(int) PDMDevHlpMMIOExMap(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS GCPhys)
6153{
6154 return pDevIns->pHlpR3->pfnMMIOExMap(pDevIns, pPciDev, iRegion, GCPhys);
6155}
6156
6157/**
6158 * @copydoc PDMDEVHLPR3::pfnMMIOExUnmap
6159 * @param pPciDev The PCI device the region is associated with, use
6160 * NULL to indicate it is not associated with a device.
6161 */
6162DECLINLINE(int) PDMDevHlpMMIOExUnmap(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS GCPhys)
6163{
6164 return pDevIns->pHlpR3->pfnMMIOExUnmap(pDevIns, pPciDev, iRegion, GCPhys);
6165}
6166
6167/**
6168 * @copydoc PDMDEVHLPR3::pfnMMIOExReduce
6169 */
6170DECLINLINE(int) PDMDevHlpMMIOExReduce(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS cbRegion)
6171{
6172 return pDevIns->pHlpR3->pfnMMIOExReduce(pDevIns, pPciDev, iRegion, cbRegion);
6173}
6174
6175#ifdef VBOX_WITH_RAW_MODE_KEEP
6176/**
6177 * @copydoc PDMDEVHLPR3::pfnMMHyperMapMMIO2
6178 */
6179DECLINLINE(int) PDMDevHlpMMHyperMapMMIO2(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS off, RTGCPHYS cb,
6180 const char *pszDesc, PRTRCPTR pRCPtr)
6181{
6182 return pDevIns->pHlpR3->pfnMMHyperMapMMIO2(pDevIns, pPciDev, iRegion, off, cb, pszDesc, pRCPtr);
6183}
6184#endif
6185
6186/**
6187 * @copydoc PDMDEVHLPR3::pfnMMIO2MapKernel
6188 */
6189DECLINLINE(int) PDMDevHlpMMIO2MapKernel(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS off, RTGCPHYS cb,
6190 const char *pszDesc, PRTR0PTR pR0Ptr)
6191{
6192 return pDevIns->pHlpR3->pfnMMIO2MapKernel(pDevIns, pPciDev, iRegion, off, cb, pszDesc, pR0Ptr);
6193}
6194
6195/**
6196 * @copydoc PDMDEVHLPR3::pfnROMRegister
6197 */
6198DECLINLINE(int) PDMDevHlpROMRegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange,
6199 const void *pvBinary, uint32_t cbBinary, uint32_t fFlags, const char *pszDesc)
6200{
6201 return pDevIns->pHlpR3->pfnROMRegister(pDevIns, GCPhysStart, cbRange, pvBinary, cbBinary, fFlags, pszDesc);
6202}
6203
6204/**
6205 * @copydoc PDMDEVHLPR3::pfnROMProtectShadow
6206 */
6207DECLINLINE(int) PDMDevHlpROMProtectShadow(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, PGMROMPROT enmProt)
6208{
6209 return pDevIns->pHlpR3->pfnROMProtectShadow(pDevIns, GCPhysStart, cbRange, enmProt);
6210}
6211
6212/**
6213 * Register a save state data unit.
6214 *
6215 * @returns VBox status.
6216 * @param pDevIns The device instance.
6217 * @param uVersion Data layout version number.
6218 * @param cbGuess The approximate amount of data in the unit.
6219 * Only for progress indicators.
6220 * @param pfnSaveExec Execute save callback, optional.
6221 * @param pfnLoadExec Execute load callback, optional.
6222 */
6223DECLINLINE(int) PDMDevHlpSSMRegister(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess,
6224 PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVLOADEXEC pfnLoadExec)
6225{
6226 return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, NULL /*pszBefore*/,
6227 NULL /*pfnLivePrep*/, NULL /*pfnLiveExec*/, NULL /*pfnLiveDone*/,
6228 NULL /*pfnSavePrep*/, pfnSaveExec, NULL /*pfnSaveDone*/,
6229 NULL /*pfnLoadPrep*/, pfnLoadExec, NULL /*pfnLoadDone*/);
6230}
6231
6232/**
6233 * Register a save state data unit with a live save callback as well.
6234 *
6235 * @returns VBox status.
6236 * @param pDevIns The device instance.
6237 * @param uVersion Data layout version number.
6238 * @param cbGuess The approximate amount of data in the unit.
6239 * Only for progress indicators.
6240 * @param pfnLiveExec Execute live callback, optional.
6241 * @param pfnSaveExec Execute save callback, optional.
6242 * @param pfnLoadExec Execute load callback, optional.
6243 */
6244DECLINLINE(int) PDMDevHlpSSMRegister3(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess,
6245 PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVLOADEXEC pfnLoadExec)
6246{
6247 return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, NULL /*pszBefore*/,
6248 NULL /*pfnLivePrep*/, pfnLiveExec, NULL /*pfnLiveDone*/,
6249 NULL /*pfnSavePrep*/, pfnSaveExec, NULL /*pfnSaveDone*/,
6250 NULL /*pfnLoadPrep*/, pfnLoadExec, NULL /*pfnLoadDone*/);
6251}
6252
6253/**
6254 * @copydoc PDMDEVHLPR3::pfnSSMRegister
6255 */
6256DECLINLINE(int) PDMDevHlpSSMRegisterEx(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess, const char *pszBefore,
6257 PFNSSMDEVLIVEPREP pfnLivePrep, PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVLIVEVOTE pfnLiveVote,
6258 PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
6259 PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone)
6260{
6261 return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, pszBefore,
6262 pfnLivePrep, pfnLiveExec, pfnLiveVote,
6263 pfnSavePrep, pfnSaveExec, pfnSaveDone,
6264 pfnLoadPrep, pfnLoadExec, pfnLoadDone);
6265}
6266
6267/**
6268 * @copydoc PDMDEVHLPR3::pfnTMTimerCreate
6269 */
6270DECLINLINE(int) PDMDevHlpTMTimerCreate(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, void *pvUser,
6271 uint32_t fFlags, const char *pszDesc, PPTMTIMERR3 ppTimer)
6272{
6273 return pDevIns->pHlpR3->pfnTMTimerCreate(pDevIns, enmClock, pfnCallback, pvUser, fFlags, pszDesc, ppTimer);
6274}
6275
6276/**
6277 * @copydoc PDMDEVHLPR3::pfnTimerCreate
6278 */
6279DECLINLINE(int) PDMDevHlpTimerCreate(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, void *pvUser,
6280 uint32_t fFlags, const char *pszDesc, PTMTIMERHANDLE phTimer)
6281{
6282 return pDevIns->pHlpR3->pfnTimerCreate(pDevIns, enmClock, pfnCallback, pvUser, fFlags, pszDesc, phTimer);
6283}
6284
6285#endif /* IN_RING3 */
6286
6287/**
6288 * @copydoc PDMDEVHLPR3::pfnTimerToPtr
6289 */
6290DECLINLINE(PTMTIMER) PDMDevHlpTimerToPtr(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6291{
6292 return pDevIns->CTX_SUFF(pHlp)->pfnTimerToPtr(pDevIns, hTimer);
6293}
6294
6295/**
6296 * @copydoc PDMDEVHLPR3::pfnTimerFromMicro
6297 */
6298DECLINLINE(uint64_t) PDMDevHlpTimerFromMicro(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicroSecs)
6299{
6300 return pDevIns->CTX_SUFF(pHlp)->pfnTimerFromMicro(pDevIns, hTimer, cMicroSecs);
6301}
6302
6303/**
6304 * @copydoc PDMDEVHLPR3::pfnTimerFromMilli
6305 */
6306DECLINLINE(uint64_t) PDMDevHlpTimerFromMilli(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliSecs)
6307{
6308 return pDevIns->CTX_SUFF(pHlp)->pfnTimerFromMilli(pDevIns, hTimer, cMilliSecs);
6309}
6310
6311/**
6312 * @copydoc PDMDEVHLPR3::pfnTimerFromNano
6313 */
6314DECLINLINE(uint64_t) PDMDevHlpTimerFromNano(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanoSecs)
6315{
6316 return pDevIns->CTX_SUFF(pHlp)->pfnTimerFromNano(pDevIns, hTimer, cNanoSecs);
6317}
6318
6319/**
6320 * @copydoc PDMDEVHLPR3::pfnTimerGet
6321 */
6322DECLINLINE(uint64_t) PDMDevHlpTimerGet(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6323{
6324 return pDevIns->CTX_SUFF(pHlp)->pfnTimerGet(pDevIns, hTimer);
6325}
6326
6327/**
6328 * @copydoc PDMDEVHLPR3::pfnTimerGetFreq
6329 */
6330DECLINLINE(uint64_t) PDMDevHlpTimerGetFreq(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6331{
6332 return pDevIns->CTX_SUFF(pHlp)->pfnTimerGetFreq(pDevIns, hTimer);
6333}
6334
6335/**
6336 * @copydoc PDMDEVHLPR3::pfnTimerGetNano
6337 */
6338DECLINLINE(uint64_t) PDMDevHlpTimerGetNano(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6339{
6340 return pDevIns->CTX_SUFF(pHlp)->pfnTimerGetNano(pDevIns, hTimer);
6341}
6342
6343/**
6344 * @copydoc PDMDEVHLPR3::pfnTimerIsActive
6345 */
6346DECLINLINE(bool) PDMDevHlpTimerIsActive(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6347{
6348 return pDevIns->CTX_SUFF(pHlp)->pfnTimerIsActive(pDevIns, hTimer);
6349}
6350
6351/**
6352 * @copydoc PDMDEVHLPR3::pfnTimerIsLockOwner
6353 */
6354DECLINLINE(bool) PDMDevHlpTimerIsLockOwner(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6355{
6356 return pDevIns->CTX_SUFF(pHlp)->pfnTimerIsLockOwner(pDevIns, hTimer);
6357}
6358
6359/**
6360 * @copydoc PDMDEVHLPR3::pfnTimerLock
6361 */
6362DECLINLINE(int) PDMDevHlpTimerLock(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, int rcBusy)
6363{
6364 return pDevIns->CTX_SUFF(pHlp)->pfnTimerLock(pDevIns, hTimer, rcBusy);
6365}
6366
6367/**
6368 * @copydoc PDMDEVHLPR3::pfnTimerSet
6369 */
6370DECLINLINE(int) PDMDevHlpTimerSet(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t uExpire)
6371{
6372 return pDevIns->CTX_SUFF(pHlp)->pfnTimerSet(pDevIns, hTimer, uExpire);
6373}
6374
6375/**
6376 * @copydoc PDMDEVHLPR3::pfnTimerSetFrequencyHint
6377 */
6378DECLINLINE(int) PDMDevHlpTimerSetFrequencyHint(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint32_t uHz)
6379{
6380 return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetFrequencyHint(pDevIns, hTimer, uHz);
6381}
6382
6383/**
6384 * @copydoc PDMDEVHLPR3::pfnTimerSetMicro
6385 */
6386DECLINLINE(int) PDMDevHlpTimerSetMicro(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicrosToNext)
6387{
6388 return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetMicro(pDevIns, hTimer, cMicrosToNext);
6389}
6390
6391/**
6392 * @copydoc PDMDEVHLPR3::pfnTimerSetMillies
6393 */
6394DECLINLINE(int) PDMDevHlpTimerSetMillies(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliesToNext)
6395{
6396 return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetMillies(pDevIns, hTimer, cMilliesToNext);
6397}
6398
6399/**
6400 * @copydoc PDMDEVHLPR3::pfnTimerSetNano
6401 */
6402DECLINLINE(int) PDMDevHlpTimerSetNano(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanosToNext)
6403{
6404 return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetNano(pDevIns, hTimer, cNanosToNext);
6405}
6406
6407/**
6408 * @copydoc PDMDEVHLPR3::pfnTimerSetRelative
6409 */
6410DECLINLINE(int) PDMDevHlpTimerSetRelative(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cTicksToNext, uint64_t *pu64Now)
6411{
6412 return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetRelative(pDevIns, hTimer, cTicksToNext, pu64Now);
6413}
6414
6415/**
6416 * @copydoc PDMDEVHLPR3::pfnTimerStop
6417 */
6418DECLINLINE(int) PDMDevHlpTimerStop(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6419{
6420 return pDevIns->CTX_SUFF(pHlp)->pfnTimerStop(pDevIns, hTimer);
6421}
6422
6423/**
6424 * @copydoc PDMDEVHLPR3::pfnTimerUnlock
6425 */
6426DECLINLINE(void) PDMDevHlpTimerUnlock(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6427{
6428 pDevIns->CTX_SUFF(pHlp)->pfnTimerUnlock(pDevIns, hTimer);
6429}
6430
6431#ifdef IN_RING3
6432
6433/**
6434 * @copydoc PDMDEVHLPR3::pfnTimerSetCritSect
6435 */
6436DECLINLINE(int) PDMDevHlpTimerSetCritSect(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect)
6437{
6438 return pDevIns->pHlpR3->pfnTimerSetCritSect(pDevIns, hTimer, pCritSect);
6439}
6440
6441/**
6442 * @copydoc PDMDEVHLPR3::pfnTimerSave
6443 */
6444DECLINLINE(int) PDMDevHlpTimerSave(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM)
6445{
6446 return pDevIns->pHlpR3->pfnTimerSave(pDevIns, hTimer, pSSM);
6447}
6448
6449/**
6450 * @copydoc PDMDEVHLPR3::pfnTimerLoad
6451 */
6452DECLINLINE(int) PDMDevHlpTimerLoad(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM)
6453{
6454 return pDevIns->pHlpR3->pfnTimerLoad(pDevIns, hTimer, pSSM);
6455}
6456
6457/**
6458 * @copydoc PDMDEVHLPR3::pfnTimerDestroy
6459 */
6460DECLINLINE(int) PDMDevHlpTimerDestroy(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6461{
6462 return pDevIns->pHlpR3->pfnTimerDestroy(pDevIns, hTimer);
6463}
6464
6465/**
6466 * @copydoc PDMDEVHLPR3::pfnTMUtcNow
6467 */
6468DECLINLINE(PRTTIMESPEC) PDMDevHlpTMUtcNow(PPDMDEVINS pDevIns, PRTTIMESPEC pTime)
6469{
6470 return pDevIns->pHlpR3->pfnTMUtcNow(pDevIns, pTime);
6471}
6472
6473#endif
6474
6475/**
6476 * @copydoc PDMDEVHLPR3::pfnPhysRead
6477 */
6478DECLINLINE(int) PDMDevHlpPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
6479{
6480 return pDevIns->CTX_SUFF(pHlp)->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
6481}
6482
6483/**
6484 * @copydoc PDMDEVHLPR3::pfnPhysWrite
6485 */
6486DECLINLINE(int) PDMDevHlpPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
6487{
6488 return pDevIns->CTX_SUFF(pHlp)->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
6489}
6490
6491#ifdef IN_RING3
6492
6493/**
6494 * @copydoc PDMDEVHLPR3::pfnPhysGCPhys2CCPtr
6495 */
6496DECLINLINE(int) PDMDevHlpPhysGCPhys2CCPtr(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void **ppv, PPGMPAGEMAPLOCK pLock)
6497{
6498 return pDevIns->CTX_SUFF(pHlp)->pfnPhysGCPhys2CCPtr(pDevIns, GCPhys, fFlags, ppv, pLock);
6499}
6500
6501/**
6502 * @copydoc PDMDEVHLPR3::pfnPhysGCPhys2CCPtrReadOnly
6503 */
6504DECLINLINE(int) PDMDevHlpPhysGCPhys2CCPtrReadOnly(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void const **ppv,
6505 PPGMPAGEMAPLOCK pLock)
6506{
6507 return pDevIns->CTX_SUFF(pHlp)->pfnPhysGCPhys2CCPtrReadOnly(pDevIns, GCPhys, fFlags, ppv, pLock);
6508}
6509
6510/**
6511 * @copydoc PDMDEVHLPR3::pfnPhysReleasePageMappingLock
6512 */
6513DECLINLINE(void) PDMDevHlpPhysReleasePageMappingLock(PPDMDEVINS pDevIns, PPGMPAGEMAPLOCK pLock)
6514{
6515 pDevIns->CTX_SUFF(pHlp)->pfnPhysReleasePageMappingLock(pDevIns, pLock);
6516}
6517
6518/**
6519 * @copydoc PDMDEVHLPR3::pfnPhysBulkGCPhys2CCPtr
6520 */
6521DECLINLINE(int) PDMDevHlpPhysBulkGCPhys2CCPtr(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
6522 uint32_t fFlags, void **papvPages, PPGMPAGEMAPLOCK paLocks)
6523{
6524 return pDevIns->CTX_SUFF(pHlp)->pfnPhysBulkGCPhys2CCPtr(pDevIns, cPages, paGCPhysPages, fFlags, papvPages, paLocks);
6525}
6526
6527/**
6528 * @copydoc PDMDEVHLPR3::pfnPhysBulkGCPhys2CCPtrReadOnly
6529 */
6530DECLINLINE(int) PDMDevHlpPhysBulkGCPhys2CCPtrReadOnly(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
6531 uint32_t fFlags, void const **papvPages, PPGMPAGEMAPLOCK paLocks)
6532{
6533 return pDevIns->CTX_SUFF(pHlp)->pfnPhysBulkGCPhys2CCPtrReadOnly(pDevIns, cPages, paGCPhysPages, fFlags, papvPages, paLocks);
6534}
6535
6536/**
6537 * @copydoc PDMDEVHLPR3::pfnPhysBulkReleasePageMappingLocks
6538 */
6539DECLINLINE(void) PDMDevHlpPhysBulkReleasePageMappingLocks(PPDMDEVINS pDevIns, uint32_t cPages, PPGMPAGEMAPLOCK paLocks)
6540{
6541 pDevIns->CTX_SUFF(pHlp)->pfnPhysBulkReleasePageMappingLocks(pDevIns, cPages, paLocks);
6542}
6543
6544/**
6545 * @copydoc PDMDEVHLPR3::pfnPhysReadGCVirt
6546 */
6547DECLINLINE(int) PDMDevHlpPhysReadGCVirt(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb)
6548{
6549 return pDevIns->pHlpR3->pfnPhysReadGCVirt(pDevIns, pvDst, GCVirtSrc, cb);
6550}
6551
6552/**
6553 * @copydoc PDMDEVHLPR3::pfnPhysWriteGCVirt
6554 */
6555DECLINLINE(int) PDMDevHlpPhysWriteGCVirt(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb)
6556{
6557 return pDevIns->pHlpR3->pfnPhysWriteGCVirt(pDevIns, GCVirtDst, pvSrc, cb);
6558}
6559
6560/**
6561 * @copydoc PDMDEVHLPR3::pfnPhysGCPtr2GCPhys
6562 */
6563DECLINLINE(int) PDMDevHlpPhysGCPtr2GCPhys(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTGCPHYS pGCPhys)
6564{
6565 return pDevIns->pHlpR3->pfnPhysGCPtr2GCPhys(pDevIns, GCPtr, pGCPhys);
6566}
6567
6568/**
6569 * @copydoc PDMDEVHLPR3::pfnMMHeapAlloc
6570 */
6571DECLINLINE(void *) PDMDevHlpMMHeapAlloc(PPDMDEVINS pDevIns, size_t cb)
6572{
6573 return pDevIns->pHlpR3->pfnMMHeapAlloc(pDevIns, cb);
6574}
6575
6576/**
6577 * @copydoc PDMDEVHLPR3::pfnMMHeapAllocZ
6578 */
6579DECLINLINE(void *) PDMDevHlpMMHeapAllocZ(PPDMDEVINS pDevIns, size_t cb)
6580{
6581 return pDevIns->pHlpR3->pfnMMHeapAllocZ(pDevIns, cb);
6582}
6583
6584/**
6585 * @copydoc PDMDEVHLPR3::pfnMMHeapFree
6586 */
6587DECLINLINE(void) PDMDevHlpMMHeapFree(PPDMDEVINS pDevIns, void *pv)
6588{
6589 pDevIns->pHlpR3->pfnMMHeapFree(pDevIns, pv);
6590}
6591#endif /* IN_RING3 */
6592
6593/**
6594 * @copydoc PDMDEVHLPR3::pfnVMState
6595 */
6596DECLINLINE(VMSTATE) PDMDevHlpVMState(PPDMDEVINS pDevIns)
6597{
6598 return pDevIns->CTX_SUFF(pHlp)->pfnVMState(pDevIns);
6599}
6600
6601#ifdef IN_RING3
6602/**
6603 * @copydoc PDMDEVHLPR3::pfnVMTeleportedAndNotFullyResumedYet
6604 */
6605DECLINLINE(bool) PDMDevHlpVMTeleportedAndNotFullyResumedYet(PPDMDEVINS pDevIns)
6606{
6607 return pDevIns->pHlpR3->pfnVMTeleportedAndNotFullyResumedYet(pDevIns);
6608}
6609#endif /* IN_RING3 */
6610
6611/**
6612 * @copydoc PDMDEVHLPR3::pfnVMSetError
6613 */
6614DECLINLINE(int) RT_IPRT_FORMAT_ATTR(6, 7) PDMDevHlpVMSetError(PPDMDEVINS pDevIns, const int rc, RT_SRC_POS_DECL,
6615 const char *pszFormat, ...)
6616{
6617 va_list va;
6618 va_start(va, pszFormat);
6619 pDevIns->CTX_SUFF(pHlp)->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
6620 va_end(va);
6621 return rc;
6622}
6623
6624/**
6625 * @copydoc PDMDEVHLPR3::pfnVMSetRuntimeError
6626 */
6627DECLINLINE(int) RT_IPRT_FORMAT_ATTR(4, 5) PDMDevHlpVMSetRuntimeError(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
6628 const char *pszFormat, ...)
6629{
6630 va_list va;
6631 int rc;
6632 va_start(va, pszFormat);
6633 rc = pDevIns->CTX_SUFF(pHlp)->pfnVMSetRuntimeErrorV(pDevIns, fFlags, pszErrorId, pszFormat, va);
6634 va_end(va);
6635 return rc;
6636}
6637
6638/**
6639 * VBOX_STRICT wrapper for pHlp->pfnDBGFStopV.
6640 *
6641 * @returns VBox status code which must be passed up to the VMM. This will be
6642 * VINF_SUCCESS in non-strict builds.
6643 * @param pDevIns The device instance.
6644 * @param SRC_POS Use RT_SRC_POS.
6645 * @param pszFormat Message. (optional)
6646 * @param ... Message parameters.
6647 */
6648DECLINLINE(int) RT_IPRT_FORMAT_ATTR(5, 6) PDMDevHlpDBGFStop(PPDMDEVINS pDevIns, RT_SRC_POS_DECL, const char *pszFormat, ...)
6649{
6650#ifdef VBOX_STRICT
6651# ifdef IN_RING3
6652 int rc;
6653 va_list args;
6654 va_start(args, pszFormat);
6655 rc = pDevIns->pHlpR3->pfnDBGFStopV(pDevIns, RT_SRC_POS_ARGS, pszFormat, args);
6656 va_end(args);
6657 return rc;
6658# else
6659 NOREF(pDevIns);
6660 NOREF(pszFile);
6661 NOREF(iLine);
6662 NOREF(pszFunction);
6663 NOREF(pszFormat);
6664 return VINF_EM_DBG_STOP;
6665# endif
6666#else
6667 NOREF(pDevIns);
6668 NOREF(pszFile);
6669 NOREF(iLine);
6670 NOREF(pszFunction);
6671 NOREF(pszFormat);
6672 return VINF_SUCCESS;
6673#endif
6674}
6675
6676#ifdef IN_RING3
6677
6678/**
6679 * @copydoc PDMDEVHLPR3::pfnDBGFInfoRegister
6680 */
6681DECLINLINE(int) PDMDevHlpDBGFInfoRegister(PPDMDEVINS pDevIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDEV pfnHandler)
6682{
6683 return pDevIns->pHlpR3->pfnDBGFInfoRegister(pDevIns, pszName, pszDesc, pfnHandler);
6684}
6685
6686/**
6687 * @copydoc PDMDEVHLPR3::pfnDBGFInfoRegisterArgv
6688 */
6689DECLINLINE(int) PDMDevHlpDBGFInfoRegisterArgv(PPDMDEVINS pDevIns, const char *pszName, const char *pszDesc, PFNDBGFINFOARGVDEV pfnHandler)
6690{
6691 return pDevIns->pHlpR3->pfnDBGFInfoRegisterArgv(pDevIns, pszName, pszDesc, pfnHandler);
6692}
6693
6694/**
6695 * @copydoc PDMDEVHLPR3::pfnDBGFRegRegister
6696 */
6697DECLINLINE(int) PDMDevHlpDBGFRegRegister(PPDMDEVINS pDevIns, PCDBGFREGDESC paRegisters)
6698{
6699 return pDevIns->pHlpR3->pfnDBGFRegRegister(pDevIns, paRegisters);
6700}
6701
6702/**
6703 * @copydoc PDMDEVHLPR3::pfnSTAMRegister
6704 */
6705DECLINLINE(void) PDMDevHlpSTAMRegister(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
6706{
6707 pDevIns->pHlpR3->pfnSTAMRegister(pDevIns, pvSample, enmType, pszName, enmUnit, pszDesc);
6708}
6709
6710/**
6711 * Same as pfnSTAMRegister except that the name is specified in a
6712 * RTStrPrintf like fashion.
6713 *
6714 * @returns VBox status.
6715 * @param pDevIns Device instance of the DMA.
6716 * @param pvSample Pointer to the sample.
6717 * @param enmType Sample type. This indicates what pvSample is
6718 * pointing at.
6719 * @param enmVisibility Visibility type specifying whether unused
6720 * statistics should be visible or not.
6721 * @param enmUnit Sample unit.
6722 * @param pszDesc Sample description.
6723 * @param pszName Sample name format string, unix path style. If
6724 * this does not start with a '/', the default
6725 * prefix will be prepended, otherwise it will be
6726 * used as-is.
6727 * @param ... Arguments to the format string.
6728 */
6729DECLINLINE(void) RT_IPRT_FORMAT_ATTR(7, 8) PDMDevHlpSTAMRegisterF(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType,
6730 STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
6731 const char *pszDesc, const char *pszName, ...)
6732{
6733 va_list va;
6734 va_start(va, pszName);
6735 pDevIns->pHlpR3->pfnSTAMRegisterV(pDevIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
6736 va_end(va);
6737}
6738
6739/**
6740 * Registers the device with the default PCI bus.
6741 *
6742 * @returns VBox status code.
6743 * @param pDevIns The device instance.
6744 * @param pPciDev The PCI device structure.
6745 * This must be kept in the instance data.
6746 * The PCI configuration must be initialized before registration.
6747 */
6748DECLINLINE(int) PDMDevHlpPCIRegister(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev)
6749{
6750 return pDevIns->pHlpR3->pfnPCIRegister(pDevIns, pPciDev, 0 /*fFlags*/,
6751 PDMPCIDEVREG_DEV_NO_FIRST_UNUSED, PDMPCIDEVREG_FUN_NO_FIRST_UNUSED, NULL);
6752}
6753
6754/**
6755 * @copydoc PDMDEVHLPR3::pfnPCIRegister
6756 */
6757DECLINLINE(int) PDMDevHlpPCIRegisterEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t fFlags,
6758 uint8_t uPciDevNo, uint8_t uPciFunNo, const char *pszName)
6759{
6760 return pDevIns->pHlpR3->pfnPCIRegister(pDevIns, pPciDev, fFlags, uPciDevNo, uPciFunNo, pszName);
6761}
6762
6763/**
6764 * Initialize MSI emulation support for the first PCI device.
6765 *
6766 * @returns VBox status code.
6767 * @param pDevIns The device instance.
6768 * @param pMsiReg MSI emulation registration structure.
6769 */
6770DECLINLINE(int) PDMDevHlpPCIRegisterMsi(PPDMDEVINS pDevIns, PPDMMSIREG pMsiReg)
6771{
6772 return pDevIns->pHlpR3->pfnPCIRegisterMsi(pDevIns, NULL, pMsiReg);
6773}
6774
6775/**
6776 * @copydoc PDMDEVHLPR3::pfnPCIRegisterMsi
6777 */
6778DECLINLINE(int) PDMDevHlpPCIRegisterMsiEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, PPDMMSIREG pMsiReg)
6779{
6780 return pDevIns->pHlpR3->pfnPCIRegisterMsi(pDevIns, pPciDev, pMsiReg);
6781}
6782
6783/**
6784 * Registers a I/O region (memory mapped or I/O ports) for the default PCI
6785 * device.
6786 *
6787 * @returns VBox status code.
6788 * @param pDevIns The device instance.
6789 * @param iRegion The region number.
6790 * @param cbRegion Size of the region.
6791 * @param enmType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
6792 * @param pfnMapUnmap Callback for doing the mapping.
6793 * @remarks The callback will be invoked holding the PDM lock. The device lock
6794 * is NOT take because that is very likely be a lock order violation.
6795 * @remarks Old callback style, won't get unmap calls.
6796 */
6797DECLINLINE(int) PDMDevHlpPCIIORegionRegister(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion,
6798 PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnMapUnmap)
6799{
6800 return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, enmType,
6801 PDMPCIDEV_IORGN_F_NO_HANDLE, UINT64_MAX, pfnMapUnmap);
6802}
6803
6804/**
6805 * @sa PDMDEVHLPR3::pfnPCIIORegionRegister
6806 * @remarks Old callback style, won't get unmap calls.
6807 */
6808DECLINLINE(int) PDMDevHlpPCIIORegionRegisterEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion, RTGCPHYS cbRegion,
6809 PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnMapUnmap)
6810{
6811 return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pPciDev, iRegion, cbRegion, enmType,
6812 PDMPCIDEV_IORGN_F_NO_HANDLE, UINT64_MAX, pfnMapUnmap);
6813}
6814
6815/**
6816 * Registers a I/O port region for the default PCI device.
6817 *
6818 * @returns VBox status code.
6819 * @param pDevIns The device instance.
6820 * @param iRegion The region number.
6821 * @param cbRegion Size of the region.
6822 * @param hIoPorts Handle to the I/O port region.
6823 */
6824DECLINLINE(int) PDMDevHlpPCIIORegionRegisterIo(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion, IOMIOPORTHANDLE hIoPorts)
6825{
6826 return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, PCI_ADDRESS_SPACE_IO,
6827 PDMPCIDEV_IORGN_F_IOPORT_HANDLE | PDMPCIDEV_IORGN_F_NEW_STYLE, hIoPorts, NULL);
6828}
6829
6830/**
6831 * Registers a I/O port region for the default PCI device, custom map/unmap.
6832 *
6833 * @returns VBox status code.
6834 * @param pDevIns The device instance.
6835 * @param iRegion The region number.
6836 * @param cbRegion Size of the region.
6837 * @param pfnMapUnmap Callback for doing the mapping, optional. The
6838 * callback will be invoked holding only the PDM lock.
6839 * The device lock will _not_ be taken (due to lock
6840 * order).
6841 */
6842DECLINLINE(int) PDMDevHlpPCIIORegionRegisterIoCustom(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion,
6843 PFNPCIIOREGIONMAP pfnMapUnmap)
6844{
6845 return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, PCI_ADDRESS_SPACE_IO,
6846 PDMPCIDEV_IORGN_F_NO_HANDLE | PDMPCIDEV_IORGN_F_NEW_STYLE,
6847 UINT64_MAX, pfnMapUnmap);
6848}
6849
6850/**
6851 * Combines PDMDevHlpIoPortCreate and PDMDevHlpPCIIORegionRegisterIo, creating
6852 * and registering an I/O port region for the default PCI device.
6853 *
6854 * @returns VBox status code.
6855 * @param pDevIns The device instance to register the ports with.
6856 * @param cPorts The count of I/O ports in the region (the size).
6857 * @param iPciRegion The PCI device region.
6858 * @param pfnOut Pointer to function which is gonna handle OUT
6859 * operations. Optional.
6860 * @param pfnIn Pointer to function which is gonna handle IN operations.
6861 * Optional.
6862 * @param pvUser User argument to pass to the callbacks.
6863 * @param pszDesc Pointer to description string. This must not be freed.
6864 * @param paExtDescs Extended per-port descriptions, optional. Partial range
6865 * coverage is allowed. This must not be freed.
6866 * @param phIoPorts Where to return the I/O port range handle.
6867 *
6868 */
6869DECLINLINE(int) PDMDevHlpPCIIORegionCreateIo(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTIOPORT cPorts,
6870 PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn, void *pvUser,
6871 const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6872
6873{
6874 int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0 /*fFlags*/, pDevIns->apPciDevs[0], iPciRegion << 16,
6875 pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
6876 if (RT_SUCCESS(rc))
6877 rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cPorts, PCI_ADDRESS_SPACE_IO,
6878 PDMPCIDEV_IORGN_F_IOPORT_HANDLE | PDMPCIDEV_IORGN_F_NEW_STYLE,
6879 *phIoPorts, NULL /*pfnMapUnmap*/);
6880 return rc;
6881}
6882
6883/**
6884 * Registers an MMIO region for the default PCI device.
6885 *
6886 * @returns VBox status code.
6887 * @param pDevIns The device instance.
6888 * @param iRegion The region number.
6889 * @param cbRegion Size of the region.
6890 * @param enmType PCI_ADDRESS_SPACE_MEM or
6891 * PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
6892 * PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
6893 * @param hMmioRegion Handle to the MMIO region.
6894 * @param pfnMapUnmap Callback for doing the mapping, optional. The
6895 * callback will be invoked holding only the PDM lock.
6896 * The device lock will _not_ be taken (due to lock
6897 * order).
6898 */
6899DECLINLINE(int) PDMDevHlpPCIIORegionRegisterMmio(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion, PCIADDRESSSPACE enmType,
6900 IOMMMIOHANDLE hMmioRegion, PFNPCIIOREGIONMAP pfnMapUnmap)
6901{
6902 return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, enmType,
6903 PDMPCIDEV_IORGN_F_MMIO_HANDLE | PDMPCIDEV_IORGN_F_NEW_STYLE,
6904 hMmioRegion, pfnMapUnmap);
6905}
6906
6907/**
6908 * Registers an MMIO region for the default PCI device, extended version.
6909 *
6910 * @returns VBox status code.
6911 * @param pDevIns The device instance.
6912 * @param pPciDev The PCI device structure.
6913 * @param iRegion The region number.
6914 * @param cbRegion Size of the region.
6915 * @param enmType PCI_ADDRESS_SPACE_MEM or
6916 * PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
6917 * PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
6918 * @param hMmioRegion Handle to the MMIO region.
6919 * @param pfnMapUnmap Callback for doing the mapping, optional. The
6920 * callback will be invoked holding only the PDM lock.
6921 * The device lock will _not_ be taken (due to lock
6922 * order).
6923 */
6924DECLINLINE(int) PDMDevHlpPCIIORegionRegisterMmioEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion,
6925 RTGCPHYS cbRegion, PCIADDRESSSPACE enmType, IOMMMIOHANDLE hMmioRegion,
6926 PFNPCIIOREGIONMAP pfnMapUnmap)
6927{
6928 return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pPciDev, iRegion, cbRegion, enmType,
6929 PDMPCIDEV_IORGN_F_MMIO_HANDLE | PDMPCIDEV_IORGN_F_NEW_STYLE,
6930 hMmioRegion, pfnMapUnmap);
6931}
6932
6933/**
6934 * Combines PDMDevHlpMmioCreate and PDMDevHlpPCIIORegionRegisterMmio, creating
6935 * and registering an MMIO region for the default PCI device.
6936 *
6937 * @returns VBox status code.
6938 * @param pDevIns The device instance to register the ports with.
6939 * @param cbRegion The size of the region in bytes.
6940 * @param iPciRegion The PCI device region.
6941 * @param enmType PCI_ADDRESS_SPACE_MEM or
6942 * PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
6943 * PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
6944 * @param fFlags Flags, IOMMMIO_FLAGS_XXX.
6945 * @param pfnWrite Pointer to function which is gonna handle Write
6946 * operations.
6947 * @param pfnRead Pointer to function which is gonna handle Read
6948 * operations.
6949 * @param pvUser User argument to pass to the callbacks.
6950 * @param pszDesc Pointer to description string. This must not be freed.
6951 * @param phRegion Where to return the MMIO region handle.
6952 *
6953 */
6954DECLINLINE(int) PDMDevHlpPCIIORegionCreateMmio(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTGCPHYS cbRegion, PCIADDRESSSPACE enmType,
6955 PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, void *pvUser,
6956 uint32_t fFlags, const char *pszDesc, PIOMMMIOHANDLE phRegion)
6957
6958{
6959 int rc = pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pDevIns->apPciDevs[0], iPciRegion << 16,
6960 pfnWrite, pfnRead, NULL /*pfnFill*/, pvUser, pszDesc, phRegion);
6961 if (RT_SUCCESS(rc))
6962 rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cbRegion, enmType,
6963 PDMPCIDEV_IORGN_F_MMIO_HANDLE | PDMPCIDEV_IORGN_F_NEW_STYLE,
6964 *phRegion, NULL /*pfnMapUnmap*/);
6965 return rc;
6966}
6967
6968
6969/**
6970 * Registers an MMIO2 region for the default PCI device.
6971 *
6972 * @returns VBox status code.
6973 * @param pDevIns The device instance.
6974 * @param iRegion The region number.
6975 * @param cbRegion Size of the region.
6976 * @param enmType PCI_ADDRESS_SPACE_MEM or
6977 * PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
6978 * PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
6979 * @param hMmio2Region Handle to the MMIO2 region.
6980 */
6981DECLINLINE(int) PDMDevHlpPCIIORegionRegisterMmio2(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion,
6982 PCIADDRESSSPACE enmType, PGMMMIO2HANDLE hMmio2Region)
6983{
6984 return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, enmType,
6985 PDMPCIDEV_IORGN_F_MMIO2_HANDLE | PDMPCIDEV_IORGN_F_NEW_STYLE,
6986 hMmio2Region, NULL);
6987}
6988
6989/**
6990 * Combines PDMDevHlpMmio2Create and PDMDevHlpPCIIORegionRegisterMmio2, creating
6991 * and registering an MMIO2 region for the default PCI device, extended edition.
6992 *
6993 * @returns VBox status code.
6994 * @param pDevIns The device instance to register the ports with.
6995 * @param cbRegion The size of the region in bytes.
6996 * @param iPciRegion The PCI device region.
6997 * @param enmType PCI_ADDRESS_SPACE_MEM or
6998 * PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
6999 * PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
7000 * @param pszDesc Pointer to description string. This must not be freed.
7001 * @param ppvMapping Where to store the address of the ring-3 mapping of
7002 * the memory.
7003 * @param phRegion Where to return the MMIO2 region handle.
7004 *
7005 */
7006DECLINLINE(int) PDMDevHlpPCIIORegionCreateMmio2(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTGCPHYS cbRegion,
7007 PCIADDRESSSPACE enmType, const char *pszDesc,
7008 void **ppvMapping, PPGMMMIO2HANDLE phRegion)
7009
7010{
7011 int rc = pDevIns->pHlpR3->pfnMmio2Create(pDevIns, pDevIns->apPciDevs[0], iPciRegion << 16, cbRegion, 0 /*fFlags*/,
7012 pszDesc, ppvMapping, phRegion);
7013 if (RT_SUCCESS(rc))
7014 rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cbRegion, enmType,
7015 PDMPCIDEV_IORGN_F_MMIO2_HANDLE, *phRegion, NULL /*pfnCallback*/);
7016 return rc;
7017}
7018
7019/**
7020 * Combines PDMDevHlpMmio2Create and PDMDevHlpPCIIORegionRegisterMmio2, creating
7021 * and registering an MMIO2 region for the default PCI device.
7022 *
7023 * @returns VBox status code.
7024 * @param pDevIns The device instance to register the ports with.
7025 * @param cbRegion The size of the region in bytes.
7026 * @param iPciRegion The PCI device region.
7027 * @param enmType PCI_ADDRESS_SPACE_MEM or
7028 * PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
7029 * PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
7030 * @param fMmio2Flags To be defined, must be zero.
7031 * @param pfnMapUnmap Callback for doing the mapping, optional. The
7032 * callback will be invoked holding only the PDM lock.
7033 * The device lock will _not_ be taken (due to lock
7034 * order).
7035 * @param pszDesc Pointer to description string. This must not be freed.
7036 * @param ppvMapping Where to store the address of the ring-3 mapping of
7037 * the memory.
7038 * @param phRegion Where to return the MMIO2 region handle.
7039 *
7040 */
7041DECLINLINE(int) PDMDevHlpPCIIORegionCreateMmio2Ex(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTGCPHYS cbRegion,
7042 PCIADDRESSSPACE enmType, uint32_t fMmio2Flags, PFNPCIIOREGIONMAP pfnMapUnmap,
7043 const char *pszDesc, void **ppvMapping, PPGMMMIO2HANDLE phRegion)
7044
7045{
7046 int rc = pDevIns->pHlpR3->pfnMmio2Create(pDevIns, pDevIns->apPciDevs[0], iPciRegion << 16, cbRegion, fMmio2Flags,
7047 pszDesc, ppvMapping, phRegion);
7048 if (RT_SUCCESS(rc))
7049 rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cbRegion, enmType,
7050 PDMPCIDEV_IORGN_F_MMIO2_HANDLE, *phRegion, pfnMapUnmap);
7051 return rc;
7052}
7053
7054/**
7055 * @copydoc PDMDEVHLPR3::pfnPCIInterceptConfigAccesses
7056 */
7057DECLINLINE(int) PDMDevHlpPCIInterceptConfigAccesses(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
7058 PFNPCICONFIGREAD pfnRead, PFNPCICONFIGWRITE pfnWrite)
7059{
7060 return pDevIns->pHlpR3->pfnPCIInterceptConfigAccesses(pDevIns, pPciDev, pfnRead, pfnWrite);
7061}
7062
7063/**
7064 * @copydoc PDMDEVHLPR3::pfnPCIConfigRead
7065 */
7066DECLINLINE(VBOXSTRICTRC) PDMDevHlpPCIConfigRead(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t uAddress,
7067 unsigned cb, uint32_t *pu32Value)
7068{
7069 return pDevIns->pHlpR3->pfnPCIConfigRead(pDevIns, pPciDev, uAddress, cb, pu32Value);
7070}
7071
7072/**
7073 * @copydoc PDMDEVHLPR3::pfnPCIConfigWrite
7074 */
7075DECLINLINE(VBOXSTRICTRC) PDMDevHlpPCIConfigWrite(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t uAddress,
7076 unsigned cb, uint32_t u32Value)
7077{
7078 return pDevIns->pHlpR3->pfnPCIConfigWrite(pDevIns, pPciDev, uAddress, cb, u32Value);
7079}
7080
7081#endif /* IN_RING3 */
7082
7083/**
7084 * Bus master physical memory read from the default PCI device.
7085 *
7086 * @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
7087 * VERR_EM_MEMORY. The informational status shall NOT be propagated!
7088 * @param pDevIns The device instance.
7089 * @param GCPhys Physical address start reading from.
7090 * @param pvBuf Where to put the read bits.
7091 * @param cbRead How many bytes to read.
7092 * @thread Any thread, but the call may involve the emulation thread.
7093 */
7094DECLINLINE(int) PDMDevHlpPCIPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
7095{
7096 return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, NULL, GCPhys, pvBuf, cbRead);
7097}
7098
7099/**
7100 * @copydoc PDMDEVHLPR3::pfnPCIPhysRead
7101 */
7102DECLINLINE(int) PDMDevHlpPCIPhysReadEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
7103{
7104 return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, pPciDev, GCPhys, pvBuf, cbRead);
7105}
7106
7107/**
7108 * Bus master physical memory write from the default PCI device.
7109 *
7110 * @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
7111 * VERR_EM_MEMORY. The informational status shall NOT be propagated!
7112 * @param pDevIns The device instance.
7113 * @param GCPhys Physical address to write to.
7114 * @param pvBuf What to write.
7115 * @param cbWrite How many bytes to write.
7116 * @thread Any thread, but the call may involve the emulation thread.
7117 */
7118DECLINLINE(int) PDMDevHlpPCIPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
7119{
7120 return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, NULL, GCPhys, pvBuf, cbWrite);
7121}
7122
7123/**
7124 * @copydoc PDMDEVHLPR3::pfnPCIPhysWrite
7125 */
7126DECLINLINE(int) PDMDevHlpPCIPhysWriteEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
7127{
7128 return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, pPciDev, GCPhys, pvBuf, cbWrite);
7129}
7130
7131/**
7132 * Sets the IRQ for the default PCI device.
7133 *
7134 * @param pDevIns The device instance.
7135 * @param iIrq IRQ number to set.
7136 * @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
7137 * @thread Any thread, but will involve the emulation thread.
7138 */
7139DECLINLINE(void) PDMDevHlpPCISetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
7140{
7141 pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, NULL, iIrq, iLevel);
7142}
7143
7144/**
7145 * @copydoc PDMDEVHLPR3::pfnPCISetIrq
7146 */
7147DECLINLINE(void) PDMDevHlpPCISetIrqEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel)
7148{
7149 pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, pPciDev, iIrq, iLevel);
7150}
7151
7152/**
7153 * Sets the IRQ for the given PCI device, but doesn't wait for EMT to process
7154 * the request when not called from EMT.
7155 *
7156 * @param pDevIns The device instance.
7157 * @param iIrq IRQ number to set.
7158 * @param iLevel IRQ level.
7159 * @thread Any thread, but will involve the emulation thread.
7160 */
7161DECLINLINE(void) PDMDevHlpPCISetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
7162{
7163 pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, NULL, iIrq, iLevel);
7164}
7165
7166/**
7167 * @copydoc PDMDEVHLPR3::pfnPCISetIrqNoWait
7168 */
7169DECLINLINE(void) PDMDevHlpPCISetIrqNoWaitEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel)
7170{
7171 pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, pPciDev, iIrq, iLevel);
7172}
7173
7174/**
7175 * @copydoc PDMDEVHLPR3::pfnISASetIrq
7176 */
7177DECLINLINE(void) PDMDevHlpISASetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
7178{
7179 pDevIns->CTX_SUFF(pHlp)->pfnISASetIrq(pDevIns, iIrq, iLevel);
7180}
7181
7182/**
7183 * @copydoc PDMDEVHLPR3::pfnISASetIrqNoWait
7184 */
7185DECLINLINE(void) PDMDevHlpISASetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
7186{
7187 pDevIns->CTX_SUFF(pHlp)->pfnISASetIrq(pDevIns, iIrq, iLevel);
7188}
7189
7190/**
7191 * @copydoc PDMDEVHLPR3::pfnIoApicSendMsi
7192 */
7193DECLINLINE(void) PDMDevHlpIoApicSendMsi(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue)
7194{
7195 pDevIns->CTX_SUFF(pHlp)->pfnIoApicSendMsi(pDevIns, GCPhys, uValue);
7196}
7197
7198#ifdef IN_RING3
7199
7200/**
7201 * @copydoc PDMDEVHLPR3::pfnDriverAttach
7202 */
7203DECLINLINE(int) PDMDevHlpDriverAttach(PPDMDEVINS pDevIns, uint32_t iLun, PPDMIBASE pBaseInterface, PPDMIBASE *ppBaseInterface, const char *pszDesc)
7204{
7205 return pDevIns->pHlpR3->pfnDriverAttach(pDevIns, iLun, pBaseInterface, ppBaseInterface, pszDesc);
7206}
7207
7208/**
7209 * @copydoc PDMDEVHLPR3::pfnDriverDetach
7210 */
7211DECLINLINE(int) PDMDevHlpDriverDetach(PPDMDEVINS pDevIns, PPDMDRVINS pDrvIns, uint32_t fFlags)
7212{
7213 return pDevIns->pHlpR3->pfnDriverDetach(pDevIns, pDrvIns, fFlags);
7214}
7215
7216/**
7217 * @copydoc PDMDEVHLPR3::pfnQueueCreatePtr
7218 */
7219DECLINLINE(int) PDMDevHlpQueueCreate(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
7220 PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char *pszName, PPDMQUEUE *ppQueue)
7221{
7222 return pDevIns->pHlpR3->pfnQueueCreatePtr(pDevIns, cbItem, cItems, cMilliesInterval, pfnCallback, fRZEnabled, pszName, ppQueue);
7223}
7224
7225/**
7226 * @copydoc PDMDEVHLPR3::pfnQueueCreate
7227 */
7228DECLINLINE(int) PDMDevHlpQueueCreateNew(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
7229 PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char *pszName, PDMQUEUEHANDLE *phQueue)
7230{
7231 return pDevIns->pHlpR3->pfnQueueCreate(pDevIns, cbItem, cItems, cMilliesInterval, pfnCallback, fRZEnabled, pszName, phQueue);
7232}
7233
7234#endif /* IN_RING3 */
7235
7236/**
7237 * @copydoc PDMDEVHLPR3::pfnQueueAlloc
7238 */
7239DECLINLINE(PPDMQUEUEITEMCORE) PDMDevHlpQueueAlloc(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue)
7240{
7241 return pDevIns->CTX_SUFF(pHlp)->pfnQueueAlloc(pDevIns, hQueue);
7242}
7243
7244/**
7245 * @copydoc PDMDEVHLPR3::pfnQueueInsert
7246 */
7247DECLINLINE(void) PDMDevHlpQueueInsert(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem)
7248{
7249 pDevIns->CTX_SUFF(pHlp)->pfnQueueInsert(pDevIns, hQueue, pItem);
7250}
7251
7252/**
7253 * @copydoc PDMDEVHLPR3::pfnQueueInsertEx
7254 */
7255DECLINLINE(void) PDMDevHlpQueueInsertEx(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem, uint64_t cNanoMaxDelay)
7256{
7257 pDevIns->CTX_SUFF(pHlp)->pfnQueueInsertEx(pDevIns, hQueue, pItem, cNanoMaxDelay);
7258}
7259
7260/**
7261 * @copydoc PDMDEVHLPR3::pfnQueueFlushIfNecessary
7262 */
7263DECLINLINE(bool) PDMDevHlpQueueFlushIfNecessary(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue)
7264{
7265 return pDevIns->CTX_SUFF(pHlp)->pfnQueueFlushIfNecessary(pDevIns, hQueue);
7266}
7267
7268#ifdef IN_RING3
7269/**
7270 * @copydoc PDMDEVHLPR3::pfnTaskCreate
7271 */
7272DECLINLINE(int) PDMDevHlpTaskCreate(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszName,
7273 PFNPDMTASKDEV pfnCallback, void *pvUser, PDMTASKHANDLE *phTask)
7274{
7275 return pDevIns->pHlpR3->pfnTaskCreate(pDevIns, fFlags, pszName, pfnCallback, pvUser, phTask);
7276}
7277#endif
7278
7279/**
7280 * @copydoc PDMDEVHLPR3::pfnTaskTrigger
7281 */
7282DECLINLINE(int) PDMDevHlpTaskTrigger(PPDMDEVINS pDevIns, PDMTASKHANDLE hTask)
7283{
7284 return pDevIns->CTX_SUFF(pHlp)->pfnTaskTrigger(pDevIns, hTask);
7285}
7286
7287#ifdef IN_RING3
7288
7289/**
7290 * @copydoc PDMDEVHLPR3::pfnSUPSemEventCreate
7291 */
7292DECLINLINE(int) PDMDevHlpSUPSemEventCreate(PPDMDEVINS pDevIns, PSUPSEMEVENT phEvent)
7293{
7294 return pDevIns->pHlpR3->pfnSUPSemEventCreate(pDevIns, phEvent);
7295}
7296
7297/**
7298 * @copydoc PDMDEVHLPR3::pfnSUPSemEventClose
7299 */
7300DECLINLINE(int) PDMDevHlpSUPSemEventClose(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent)
7301{
7302 return pDevIns->pHlpR3->pfnSUPSemEventClose(pDevIns, hEvent);
7303}
7304
7305#endif /* IN_RING3 */
7306
7307/**
7308 * @copydoc PDMDEVHLPR3::pfnSUPSemEventSignal
7309 */
7310DECLINLINE(int) PDMDevHlpSUPSemEventSignal(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent)
7311{
7312 return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventSignal(pDevIns, hEvent);
7313}
7314
7315/**
7316 * @copydoc PDMDEVHLPR3::pfnSUPSemEventWaitNoResume
7317 */
7318DECLINLINE(int) PDMDevHlpSUPSemEventWaitNoResume(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint32_t cMillies)
7319{
7320 return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventWaitNoResume(pDevIns, hEvent, cMillies);
7321}
7322
7323/**
7324 * @copydoc PDMDEVHLPR3::pfnSUPSemEventWaitNsAbsIntr
7325 */
7326DECLINLINE(int) PDMDevHlpSUPSemEventWaitNsAbsIntr(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t uNsTimeout)
7327{
7328 return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventWaitNsAbsIntr(pDevIns, hEvent, uNsTimeout);
7329}
7330
7331/**
7332 * @copydoc PDMDEVHLPR3::pfnSUPSemEventWaitNsRelIntr
7333 */
7334DECLINLINE(int) PDMDevHlpSUPSemEventWaitNsRelIntr(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t cNsTimeout)
7335{
7336 return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventWaitNsRelIntr(pDevIns, hEvent, cNsTimeout);
7337}
7338
7339/**
7340 * @copydoc PDMDEVHLPR3::pfnSUPSemEventGetResolution
7341 */
7342DECLINLINE(uint32_t) PDMDevHlpSUPSemEventGetResolution(PPDMDEVINS pDevIns)
7343{
7344 return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventGetResolution(pDevIns);
7345}
7346
7347#ifdef IN_RING3
7348
7349/**
7350 * @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiCreate
7351 */
7352DECLINLINE(int) PDMDevHlpSUPSemEventMultiCreate(PPDMDEVINS pDevIns, PSUPSEMEVENTMULTI phEventMulti)
7353{
7354 return pDevIns->pHlpR3->pfnSUPSemEventMultiCreate(pDevIns, phEventMulti);
7355}
7356
7357/**
7358 * @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiClose
7359 */
7360DECLINLINE(int) PDMDevHlpSUPSemEventMultiClose(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti)
7361{
7362 return pDevIns->pHlpR3->pfnSUPSemEventMultiClose(pDevIns, hEventMulti);
7363}
7364
7365#endif /* IN_RING3 */
7366
7367/**
7368 * @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiSignal
7369 */
7370DECLINLINE(int) PDMDevHlpSUPSemEventMultiSignal(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti)
7371{
7372 return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiSignal(pDevIns, hEventMulti);
7373}
7374
7375/**
7376 * @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiReset
7377 */
7378DECLINLINE(int) PDMDevHlpSUPSemEventMultiReset(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti)
7379{
7380 return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiReset(pDevIns, hEventMulti);
7381}
7382
7383/**
7384 * @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiWaitNoResume
7385 */
7386DECLINLINE(int) PDMDevHlpSUPSemEventMultiWaitNoResume(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint32_t cMillies)
7387{
7388 return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiWaitNsRelIntr(pDevIns, hEventMulti, cMillies);
7389}
7390
7391/**
7392 * @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiWaitNsAbsIntr
7393 */
7394DECLINLINE(int) PDMDevHlpSUPSemEventMultiWaitNsAbsIntr(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t uNsTimeout)
7395{
7396 return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiWaitNsAbsIntr(pDevIns, hEventMulti, uNsTimeout);
7397}
7398
7399/**
7400 * @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiWaitNsRelIntr
7401 */
7402DECLINLINE(int) PDMDevHlpSUPSemEventMultiWaitNsRelIntr(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t cNsTimeout)
7403{
7404 return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiWaitNsRelIntr(pDevIns, hEventMulti, cNsTimeout);
7405}
7406
7407/**
7408 * @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiGetResolution
7409 */
7410DECLINLINE(uint32_t) PDMDevHlpSUPSemEventMultiGetResolution(PPDMDEVINS pDevIns)
7411{
7412 return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiGetResolution(pDevIns);
7413}
7414
7415#ifdef IN_RING3
7416
7417/**
7418 * Initializes a PDM critical section.
7419 *
7420 * The PDM critical sections are derived from the IPRT critical sections, but
7421 * works in RC and R0 as well.
7422 *
7423 * @returns VBox status code.
7424 * @param pDevIns The device instance.
7425 * @param pCritSect Pointer to the critical section.
7426 * @param SRC_POS Use RT_SRC_POS.
7427 * @param pszNameFmt Format string for naming the critical section.
7428 * For statistics and lock validation.
7429 * @param ... Arguments for the format string.
7430 */
7431DECLINLINE(int) RT_IPRT_FORMAT_ATTR(6, 7) PDMDevHlpCritSectInit(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RT_SRC_POS_DECL,
7432 const char *pszNameFmt, ...)
7433{
7434 int rc;
7435 va_list va;
7436 va_start(va, pszNameFmt);
7437 rc = pDevIns->pHlpR3->pfnCritSectInit(pDevIns, pCritSect, RT_SRC_POS_ARGS, pszNameFmt, va);
7438 va_end(va);
7439 return rc;
7440}
7441
7442#endif /* IN_RING3 */
7443
7444/**
7445 * @copydoc PDMDEVHLPR3::pfnCritSectGetNop
7446 */
7447DECLINLINE(PPDMCRITSECT) PDMDevHlpCritSectGetNop(PPDMDEVINS pDevIns)
7448{
7449 return pDevIns->CTX_SUFF(pHlp)->pfnCritSectGetNop(pDevIns);
7450}
7451
7452#ifdef IN_RING3
7453
7454/**
7455 * @copydoc PDMDEVHLPR3::pfnCritSectGetNopR0
7456 */
7457DECLINLINE(R0PTRTYPE(PPDMCRITSECT)) PDMDevHlpCritSectGetNopR0(PPDMDEVINS pDevIns)
7458{
7459 return pDevIns->pHlpR3->pfnCritSectGetNopR0(pDevIns);
7460}
7461
7462/**
7463 * @copydoc PDMDEVHLPR3::pfnCritSectGetNopRC
7464 */
7465DECLINLINE(RCPTRTYPE(PPDMCRITSECT)) PDMDevHlpCritSectGetNopRC(PPDMDEVINS pDevIns)
7466{
7467 return pDevIns->pHlpR3->pfnCritSectGetNopRC(pDevIns);
7468}
7469
7470#endif /* IN_RING3 */
7471
7472/**
7473 * @copydoc PDMDEVHLPR3::pfnSetDeviceCritSect
7474 */
7475DECLINLINE(int) PDMDevHlpSetDeviceCritSect(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
7476{
7477 return pDevIns->CTX_SUFF(pHlp)->pfnSetDeviceCritSect(pDevIns, pCritSect);
7478}
7479
7480/**
7481 * @copydoc PDMCritSectEnter
7482 * @param pDevIns The device instance.
7483 */
7484DECLINLINE(int) PDMDevHlpCritSectEnter(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy)
7485{
7486 return pDevIns->CTX_SUFF(pHlp)->pfnCritSectEnter(pDevIns, pCritSect, rcBusy);
7487}
7488
7489/**
7490 * @copydoc PDMCritSectEnterDebug
7491 * @param pDevIns The device instance.
7492 */
7493DECLINLINE(int) PDMDevHlpCritSectEnterDebug(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL)
7494{
7495 return pDevIns->CTX_SUFF(pHlp)->pfnCritSectEnterDebug(pDevIns, pCritSect, rcBusy, uId, RT_SRC_POS_ARGS);
7496}
7497
7498/**
7499 * @copydoc PDMCritSectTryEnter
7500 * @param pDevIns The device instance.
7501 */
7502DECLINLINE(int) PDMDevHlpCritSectTryEnter(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
7503{
7504 return pDevIns->CTX_SUFF(pHlp)->pfnCritSectTryEnter(pDevIns, pCritSect);
7505}
7506
7507/**
7508 * @copydoc PDMCritSectTryEnterDebug
7509 * @param pDevIns The device instance.
7510 */
7511DECLINLINE(int) PDMDevHlpCritSectTryEnterDebug(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL)
7512{
7513 return pDevIns->CTX_SUFF(pHlp)->pfnCritSectTryEnterDebug(pDevIns, pCritSect, uId, RT_SRC_POS_ARGS);
7514}
7515
7516/**
7517 * @copydoc PDMCritSectLeave
7518 * @param pDevIns The device instance.
7519 */
7520DECLINLINE(int) PDMDevHlpCritSectLeave(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
7521{
7522 return pDevIns->CTX_SUFF(pHlp)->pfnCritSectLeave(pDevIns, pCritSect);
7523}
7524
7525/**
7526 * @copydoc PDMCritSectIsOwner
7527 * @param pDevIns The device instance.
7528 */
7529DECLINLINE(bool) PDMDevHlpCritSectIsOwner(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
7530{
7531 return pDevIns->CTX_SUFF(pHlp)->pfnCritSectIsOwner(pDevIns, pCritSect);
7532}
7533
7534/**
7535 * @copydoc PDMCritSectIsInitialized
7536 * @param pDevIns The device instance.
7537 */
7538DECLINLINE(bool) PDMDevHlpCritSectIsInitialized(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
7539{
7540 return pDevIns->CTX_SUFF(pHlp)->pfnCritSectIsInitialized(pDevIns, pCritSect);
7541}
7542
7543/**
7544 * @copydoc PDMCritSectHasWaiters
7545 * @param pDevIns The device instance.
7546 */
7547DECLINLINE(bool) PDMDevHlpCritSectHasWaiters(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
7548{
7549 return pDevIns->CTX_SUFF(pHlp)->pfnCritSectHasWaiters(pDevIns, pCritSect);
7550}
7551
7552/**
7553 * @copydoc PDMCritSectGetRecursion
7554 * @param pDevIns The device instance.
7555 */
7556DECLINLINE(uint32_t) PDMDevHlpCritSectGetRecursion(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
7557{
7558 return pDevIns->CTX_SUFF(pHlp)->pfnCritSectGetRecursion(pDevIns, pCritSect);
7559}
7560
7561#if defined(IN_RING3) || defined(IN_RING0)
7562/**
7563 * @copydoc PDMHCCritSectScheduleExitEvent
7564 * @param pDevIns The device instance.
7565 */
7566DECLINLINE(int) PDMDevHlpCritSectScheduleExitEvent(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, SUPSEMEVENT hEventToSignal)
7567{
7568 return pDevIns->CTX_SUFF(pHlp)->pfnCritSectScheduleExitEvent(pDevIns, pCritSect, hEventToSignal);
7569}
7570#endif
7571
7572/* Strict build: Remap the two enter calls to the debug versions. */
7573#ifdef VBOX_STRICT
7574# ifdef IPRT_INCLUDED_asm_h
7575# define PDMDevHlpCritSectEnter(pDevIns, pCritSect, rcBusy) PDMDevHlpCritSectEnterDebug((pDevIns), (pCritSect), (rcBusy), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
7576# define PDMDevHlpCritSectTryEnter(pDevIns, pCritSect) PDMDevHlpCritSectTryEnterDebug((pDevIns), (pCritSect), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
7577# else
7578# define PDMDevHlpCritSectEnter(pDevIns, pCritSect, rcBusy) PDMDevHlpCritSectEnterDebug((pDevIns), (pCritSect), (rcBusy), 0, RT_SRC_POS)
7579# define PDMDevHlpCritSectTryEnter(pDevIns, pCritSect) PDMDevHlpCritSectTryEnterDebug((pDevIns), (pCritSect), 0, RT_SRC_POS)
7580# endif
7581#endif
7582
7583#if defined(IN_RING3) || defined(DOXYGEN_RUNNING)
7584
7585/**
7586 * @copydoc PDMR3CritSectDelete
7587 * @param pDevIns The device instance.
7588 */
7589DECLINLINE(int) PDMDevHlpCritSectDelete(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
7590{
7591 return pDevIns->pHlpR3->pfnCritSectDelete(pDevIns, pCritSect);
7592}
7593
7594/**
7595 * @copydoc PDMDEVHLPR3::pfnThreadCreate
7596 */
7597DECLINLINE(int) PDMDevHlpThreadCreate(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
7598 PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
7599{
7600 return pDevIns->pHlpR3->pfnThreadCreate(pDevIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
7601}
7602
7603/**
7604 * @copydoc PDMR3ThreadDestroy
7605 * @param pDevIns The device instance.
7606 */
7607DECLINLINE(int) PDMDevHlpThreadDestroy(PPDMDEVINS pDevIns, PPDMTHREAD pThread, int *pRcThread)
7608{
7609 return pDevIns->pHlpR3->pfnThreadDestroy(pThread, pRcThread);
7610}
7611
7612/**
7613 * @copydoc PDMR3ThreadIAmSuspending
7614 * @param pDevIns The device instance.
7615 */
7616DECLINLINE(int) PDMDevHlpThreadIAmSuspending(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
7617{
7618 return pDevIns->pHlpR3->pfnThreadIAmSuspending(pThread);
7619}
7620
7621/**
7622 * @copydoc PDMR3ThreadIAmRunning
7623 * @param pDevIns The device instance.
7624 */
7625DECLINLINE(int) PDMDevHlpThreadIAmRunning(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
7626{
7627 return pDevIns->pHlpR3->pfnThreadIAmRunning(pThread);
7628}
7629
7630/**
7631 * @copydoc PDMR3ThreadSleep
7632 * @param pDevIns The device instance.
7633 */
7634DECLINLINE(int) PDMDevHlpThreadSleep(PPDMDEVINS pDevIns, PPDMTHREAD pThread, RTMSINTERVAL cMillies)
7635{
7636 return pDevIns->pHlpR3->pfnThreadSleep(pThread, cMillies);
7637}
7638
7639/**
7640 * @copydoc PDMR3ThreadSuspend
7641 * @param pDevIns The device instance.
7642 */
7643DECLINLINE(int) PDMDevHlpThreadSuspend(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
7644{
7645 return pDevIns->pHlpR3->pfnThreadSuspend(pThread);
7646}
7647
7648/**
7649 * @copydoc PDMR3ThreadResume
7650 * @param pDevIns The device instance.
7651 */
7652DECLINLINE(int) PDMDevHlpThreadResume(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
7653{
7654 return pDevIns->pHlpR3->pfnThreadResume(pThread);
7655}
7656
7657/**
7658 * @copydoc PDMDEVHLPR3::pfnSetAsyncNotification
7659 */
7660DECLINLINE(int) PDMDevHlpSetAsyncNotification(PPDMDEVINS pDevIns, PFNPDMDEVASYNCNOTIFY pfnAsyncNotify)
7661{
7662 return pDevIns->pHlpR3->pfnSetAsyncNotification(pDevIns, pfnAsyncNotify);
7663}
7664
7665/**
7666 * @copydoc PDMDEVHLPR3::pfnAsyncNotificationCompleted
7667 */
7668DECLINLINE(void) PDMDevHlpAsyncNotificationCompleted(PPDMDEVINS pDevIns)
7669{
7670 pDevIns->pHlpR3->pfnAsyncNotificationCompleted(pDevIns);
7671}
7672
7673/**
7674 * @copydoc PDMDEVHLPR3::pfnA20Set
7675 */
7676DECLINLINE(void) PDMDevHlpA20Set(PPDMDEVINS pDevIns, bool fEnable)
7677{
7678 pDevIns->pHlpR3->pfnA20Set(pDevIns, fEnable);
7679}
7680
7681/**
7682 * @copydoc PDMDEVHLPR3::pfnRTCRegister
7683 */
7684DECLINLINE(int) PDMDevHlpRTCRegister(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp)
7685{
7686 return pDevIns->pHlpR3->pfnRTCRegister(pDevIns, pRtcReg, ppRtcHlp);
7687}
7688
7689/**
7690 * @copydoc PDMDEVHLPR3::pfnPCIBusRegister
7691 */
7692DECLINLINE(int) PDMDevHlpPCIBusRegister(PPDMDEVINS pDevIns, PPDMPCIBUSREGR3 pPciBusReg, PCPDMPCIHLPR3 *ppPciHlp, uint32_t *piBus)
7693{
7694 return pDevIns->pHlpR3->pfnPCIBusRegister(pDevIns, pPciBusReg, ppPciHlp, piBus);
7695}
7696
7697/**
7698 * @copydoc PDMDEVHLPR3::pfnPICRegister
7699 */
7700DECLINLINE(int) PDMDevHlpPICRegister(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp)
7701{
7702 return pDevIns->pHlpR3->pfnPICRegister(pDevIns, pPicReg, ppPicHlp);
7703}
7704
7705/**
7706 * @copydoc PDMDEVHLPR3::pfnAPICRegister
7707 */
7708DECLINLINE(int) PDMDevHlpAPICRegister(PPDMDEVINS pDevIns)
7709{
7710 return pDevIns->pHlpR3->pfnAPICRegister(pDevIns);
7711}
7712
7713/**
7714 * @copydoc PDMDEVHLPR3::pfnIoApicRegister
7715 */
7716DECLINLINE(int) PDMDevHlpIoApicRegister(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp)
7717{
7718 return pDevIns->pHlpR3->pfnIoApicRegister(pDevIns, pIoApicReg, ppIoApicHlp);
7719}
7720
7721/**
7722 * @copydoc PDMDEVHLPR3::pfnHpetRegister
7723 */
7724DECLINLINE(int) PDMDevHlpHpetRegister(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPR3 *ppHpetHlpR3)
7725{
7726 return pDevIns->pHlpR3->pfnHpetRegister(pDevIns, pHpetReg, ppHpetHlpR3);
7727}
7728
7729/**
7730 * @copydoc PDMDEVHLPR3::pfnPciRawRegister
7731 */
7732DECLINLINE(int) PDMDevHlpPciRawRegister(PPDMDEVINS pDevIns, PPDMPCIRAWREG pPciRawReg, PCPDMPCIRAWHLPR3 *ppPciRawHlpR3)
7733{
7734 return pDevIns->pHlpR3->pfnPciRawRegister(pDevIns, pPciRawReg, ppPciRawHlpR3);
7735}
7736
7737/**
7738 * @copydoc PDMDEVHLPR3::pfnDMACRegister
7739 */
7740DECLINLINE(int) PDMDevHlpDMACRegister(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp)
7741{
7742 return pDevIns->pHlpR3->pfnDMACRegister(pDevIns, pDmacReg, ppDmacHlp);
7743}
7744
7745/**
7746 * @copydoc PDMDEVHLPR3::pfnDMARegister
7747 */
7748DECLINLINE(int) PDMDevHlpDMARegister(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser)
7749{
7750 return pDevIns->pHlpR3->pfnDMARegister(pDevIns, uChannel, pfnTransferHandler, pvUser);
7751}
7752
7753/**
7754 * @copydoc PDMDEVHLPR3::pfnDMAReadMemory
7755 */
7756DECLINLINE(int) PDMDevHlpDMAReadMemory(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbRead)
7757{
7758 return pDevIns->pHlpR3->pfnDMAReadMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbRead);
7759}
7760
7761/**
7762 * @copydoc PDMDEVHLPR3::pfnDMAWriteMemory
7763 */
7764DECLINLINE(int) PDMDevHlpDMAWriteMemory(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t *pcbWritten)
7765{
7766 return pDevIns->pHlpR3->pfnDMAWriteMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbWritten);
7767}
7768
7769/**
7770 * @copydoc PDMDEVHLPR3::pfnDMASetDREQ
7771 */
7772DECLINLINE(int) PDMDevHlpDMASetDREQ(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel)
7773{
7774 return pDevIns->pHlpR3->pfnDMASetDREQ(pDevIns, uChannel, uLevel);
7775}
7776
7777/**
7778 * @copydoc PDMDEVHLPR3::pfnDMAGetChannelMode
7779 */
7780DECLINLINE(uint8_t) PDMDevHlpDMAGetChannelMode(PPDMDEVINS pDevIns, unsigned uChannel)
7781{
7782 return pDevIns->pHlpR3->pfnDMAGetChannelMode(pDevIns, uChannel);
7783}
7784
7785/**
7786 * @copydoc PDMDEVHLPR3::pfnDMASchedule
7787 */
7788DECLINLINE(void) PDMDevHlpDMASchedule(PPDMDEVINS pDevIns)
7789{
7790 pDevIns->pHlpR3->pfnDMASchedule(pDevIns);
7791}
7792
7793/**
7794 * @copydoc PDMDEVHLPR3::pfnCMOSWrite
7795 */
7796DECLINLINE(int) PDMDevHlpCMOSWrite(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value)
7797{
7798 return pDevIns->pHlpR3->pfnCMOSWrite(pDevIns, iReg, u8Value);
7799}
7800
7801/**
7802 * @copydoc PDMDEVHLPR3::pfnCMOSRead
7803 */
7804DECLINLINE(int) PDMDevHlpCMOSRead(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value)
7805{
7806 return pDevIns->pHlpR3->pfnCMOSRead(pDevIns, iReg, pu8Value);
7807}
7808
7809/**
7810 * @copydoc PDMDEVHLPR3::pfnCallR0
7811 */
7812DECLINLINE(int) PDMDevHlpCallR0(PPDMDEVINS pDevIns, uint32_t uOperation, uint64_t u64Arg)
7813{
7814 return pDevIns->pHlpR3->pfnCallR0(pDevIns, uOperation, u64Arg);
7815}
7816
7817/**
7818 * @copydoc PDMDEVHLPR3::pfnVMGetSuspendReason
7819 */
7820DECLINLINE(VMSUSPENDREASON) PDMDevHlpVMGetSuspendReason(PPDMDEVINS pDevIns)
7821{
7822 return pDevIns->pHlpR3->pfnVMGetSuspendReason(pDevIns);
7823}
7824
7825/**
7826 * @copydoc PDMDEVHLPR3::pfnVMGetResumeReason
7827 */
7828DECLINLINE(VMRESUMEREASON) PDMDevHlpVMGetResumeReason(PPDMDEVINS pDevIns)
7829{
7830 return pDevIns->pHlpR3->pfnVMGetResumeReason(pDevIns);
7831}
7832
7833/**
7834 * @copydoc PDMDEVHLPR3::pfnGetUVM
7835 */
7836DECLINLINE(PUVM) PDMDevHlpGetUVM(PPDMDEVINS pDevIns)
7837{
7838 return pDevIns->CTX_SUFF(pHlp)->pfnGetUVM(pDevIns);
7839}
7840
7841#endif /* IN_RING3 || DOXYGEN_RUNNING */
7842
7843#if !defined(IN_RING3) || defined(DOXYGEN_RUNNING)
7844
7845/**
7846 * @copydoc PDMDEVHLPR0::pfnPCIBusSetUpContext
7847 */
7848DECLINLINE(int) PDMDevHlpPCIBusSetUpContext(PPDMDEVINS pDevIns, CTX_SUFF(PPDMPCIBUSREG) pPciBusReg, CTX_SUFF(PCPDMPCIHLP) *ppPciHlp)
7849{
7850 return pDevIns->CTX_SUFF(pHlp)->pfnPCIBusSetUpContext(pDevIns, pPciBusReg, ppPciHlp);
7851}
7852
7853/**
7854 * @copydoc PDMDEVHLPR0::pfnPICSetUpContext
7855 */
7856DECLINLINE(int) PDMDevHlpPICSetUpContext(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp)
7857{
7858 return pDevIns->CTX_SUFF(pHlp)->pfnPICSetUpContext(pDevIns, pPicReg, ppPicHlp);
7859}
7860
7861/**
7862 * @copydoc PDMDEVHLPR0::pfnIoApicSetUpContext
7863 */
7864DECLINLINE(int) PDMDevHlpIoApicSetUpContext(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp)
7865{
7866 return pDevIns->CTX_SUFF(pHlp)->pfnIoApicSetUpContext(pDevIns, pIoApicReg, ppIoApicHlp);
7867}
7868
7869/**
7870 * @copydoc PDMDEVHLPR0::pfnHpetSetUpContext
7871 */
7872DECLINLINE(int) PDMDevHlpHpetSetUpContext(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, CTX_SUFF(PCPDMHPETHLP) *ppHpetHlp)
7873{
7874 return pDevIns->CTX_SUFF(pHlp)->pfnHpetSetUpContext(pDevIns, pHpetReg, ppHpetHlp);
7875}
7876
7877#endif /* !IN_RING3 || DOXYGEN_RUNNING */
7878
7879/**
7880 * @copydoc PDMDEVHLPR3::pfnGetVM
7881 */
7882DECLINLINE(PVMCC) PDMDevHlpGetVM(PPDMDEVINS pDevIns)
7883{
7884 return pDevIns->CTX_SUFF(pHlp)->pfnGetVM(pDevIns);
7885}
7886
7887/**
7888 * @copydoc PDMDEVHLPR3::pfnGetVMCPU
7889 */
7890DECLINLINE(PVMCPUCC) PDMDevHlpGetVMCPU(PPDMDEVINS pDevIns)
7891{
7892 return pDevIns->CTX_SUFF(pHlp)->pfnGetVMCPU(pDevIns);
7893}
7894
7895/**
7896 * @copydoc PDMDEVHLPR3::pfnGetCurrentCpuId
7897 */
7898DECLINLINE(VMCPUID) PDMDevHlpGetCurrentCpuId(PPDMDEVINS pDevIns)
7899{
7900 return pDevIns->CTX_SUFF(pHlp)->pfnGetCurrentCpuId(pDevIns);
7901}
7902
7903/**
7904 * @copydoc PDMDEVHLPR3::pfnTMTimeVirtGet
7905 */
7906DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGet(PPDMDEVINS pDevIns)
7907{
7908 return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGet(pDevIns);
7909}
7910
7911/**
7912 * @copydoc PDMDEVHLPR3::pfnTMTimeVirtGetFreq
7913 */
7914DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGetFreq(PPDMDEVINS pDevIns)
7915{
7916 return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGetFreq(pDevIns);
7917}
7918
7919/**
7920 * @copydoc PDMDEVHLPR3::pfnTMTimeVirtGetFreq
7921 */
7922DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGetNano(PPDMDEVINS pDevIns)
7923{
7924 return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGetNano(pDevIns);
7925}
7926
7927#ifdef IN_RING3
7928
7929/**
7930 * @copydoc PDMDEVHLPR3::pfnRegisterVMMDevHeap
7931 */
7932DECLINLINE(int) PDMDevHlpRegisterVMMDevHeap(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTR3PTR pvHeap, unsigned cbHeap)
7933{
7934 return pDevIns->pHlpR3->pfnRegisterVMMDevHeap(pDevIns, GCPhys, pvHeap, cbHeap);
7935}
7936
7937/**
7938 * @copydoc PDMDEVHLPR3::pfnFirmwareRegister
7939 */
7940DECLINLINE(int) PDMDevHlpFirmwareRegister(PPDMDEVINS pDevIns, PCPDMFWREG pFwReg, PCPDMFWHLPR3 *ppFwHlp)
7941{
7942 return pDevIns->pHlpR3->pfnFirmwareRegister(pDevIns, pFwReg, ppFwHlp);
7943}
7944
7945/**
7946 * @copydoc PDMDEVHLPR3::pfnVMReset
7947 */
7948DECLINLINE(int) PDMDevHlpVMReset(PPDMDEVINS pDevIns, uint32_t fFlags)
7949{
7950 return pDevIns->pHlpR3->pfnVMReset(pDevIns, fFlags);
7951}
7952
7953/**
7954 * @copydoc PDMDEVHLPR3::pfnVMSuspend
7955 */
7956DECLINLINE(int) PDMDevHlpVMSuspend(PPDMDEVINS pDevIns)
7957{
7958 return pDevIns->pHlpR3->pfnVMSuspend(pDevIns);
7959}
7960
7961/**
7962 * @copydoc PDMDEVHLPR3::pfnVMSuspendSaveAndPowerOff
7963 */
7964DECLINLINE(int) PDMDevHlpVMSuspendSaveAndPowerOff(PPDMDEVINS pDevIns)
7965{
7966 return pDevIns->pHlpR3->pfnVMSuspendSaveAndPowerOff(pDevIns);
7967}
7968
7969/**
7970 * @copydoc PDMDEVHLPR3::pfnVMPowerOff
7971 */
7972DECLINLINE(int) PDMDevHlpVMPowerOff(PPDMDEVINS pDevIns)
7973{
7974 return pDevIns->pHlpR3->pfnVMPowerOff(pDevIns);
7975}
7976
7977#endif /* IN_RING3 */
7978
7979/**
7980 * @copydoc PDMDEVHLPR3::pfnA20IsEnabled
7981 */
7982DECLINLINE(bool) PDMDevHlpA20IsEnabled(PPDMDEVINS pDevIns)
7983{
7984 return pDevIns->CTX_SUFF(pHlp)->pfnA20IsEnabled(pDevIns);
7985}
7986
7987#ifdef IN_RING3
7988
7989/**
7990 * @copydoc PDMDEVHLPR3::pfnGetCpuId
7991 */
7992DECLINLINE(void) PDMDevHlpGetCpuId(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t *pEax, uint32_t *pEbx, uint32_t *pEcx, uint32_t *pEdx)
7993{
7994 pDevIns->pHlpR3->pfnGetCpuId(pDevIns, iLeaf, pEax, pEbx, pEcx, pEdx);
7995}
7996
7997/**
7998 * @copydoc PDMDEVHLPR3::pfnGetSupDrvSession
7999 */
8000DECLINLINE(PSUPDRVSESSION) PDMDevHlpGetSupDrvSession(PPDMDEVINS pDevIns)
8001{
8002 return pDevIns->pHlpR3->pfnGetSupDrvSession(pDevIns);
8003}
8004
8005/**
8006 * @copydoc PDMDEVHLPR3::pfnQueryGenericUserObject
8007 */
8008DECLINLINE(void *) PDMDevHlpQueryGenericUserObject(PPDMDEVINS pDevIns, PCRTUUID pUuid)
8009{
8010 return pDevIns->pHlpR3->pfnQueryGenericUserObject(pDevIns, pUuid);
8011}
8012
8013/** Wrapper around SSMR3GetU32 for simplifying getting enum values saved as uint32_t. */
8014# define PDMDEVHLP_SSM_GET_ENUM32_RET(a_pHlp, a_pSSM, a_enmDst, a_EnumType) \
8015 do { \
8016 uint32_t u32GetEnumTmp = 0; \
8017 int rcGetEnum32Tmp = (a_pHlp)->pfnSSMGetU32((a_pSSM), &u32GetEnumTmp); \
8018 AssertRCReturn(rcGetEnum32Tmp, rcGetEnum32Tmp); \
8019 (a_enmDst) = (a_EnumType)u32GetEnumTmp; \
8020 AssertCompile(sizeof(a_EnumType) == sizeof(u32GetEnumTmp)); \
8021 } while (0)
8022
8023/** Wrapper around SSMR3GetU8 for simplifying getting enum values saved as uint8_t. */
8024# define PDMDEVHLP_SSM_GET_ENUM8_RET(a_pHlp, a_pSSM, a_enmDst, a_EnumType) \
8025 do { \
8026 uint8_t bGetEnumTmp = 0; \
8027 int rcGetEnum32Tmp = (a_pHlp)->pfnSSMGetU8((a_pSSM), &bGetEnumTmp); \
8028 AssertRCReturn(rcGetEnum32Tmp, rcGetEnum32Tmp); \
8029 (a_enmDst) = (a_EnumType)bGetEnumTmp; \
8030 } while (0)
8031
8032#endif /* IN_RING3 */
8033
8034/** Pointer to callbacks provided to the VBoxDeviceRegister() call. */
8035typedef struct PDMDEVREGCB *PPDMDEVREGCB;
8036
8037/**
8038 * Callbacks for VBoxDeviceRegister().
8039 */
8040typedef struct PDMDEVREGCB
8041{
8042 /** Interface version.
8043 * This is set to PDM_DEVREG_CB_VERSION. */
8044 uint32_t u32Version;
8045
8046 /**
8047 * Registers a device with the current VM instance.
8048 *
8049 * @returns VBox status code.
8050 * @param pCallbacks Pointer to the callback table.
8051 * @param pReg Pointer to the device registration record.
8052 * This data must be permanent and readonly.
8053 */
8054 DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMDEVREGCB pCallbacks, PCPDMDEVREG pReg));
8055} PDMDEVREGCB;
8056
8057/** Current version of the PDMDEVREGCB structure. */
8058#define PDM_DEVREG_CB_VERSION PDM_VERSION_MAKE(0xffe3, 1, 0)
8059
8060
8061/**
8062 * The VBoxDevicesRegister callback function.
8063 *
8064 * PDM will invoke this function after loading a device module and letting
8065 * the module decide which devices to register and how to handle conflicts.
8066 *
8067 * @returns VBox status code.
8068 * @param pCallbacks Pointer to the callback table.
8069 * @param u32Version VBox version number.
8070 */
8071typedef DECLCALLBACK(int) FNPDMVBOXDEVICESREGISTER(PPDMDEVREGCB pCallbacks, uint32_t u32Version);
8072
8073/** @} */
8074
8075RT_C_DECLS_END
8076
8077#endif /* !VBOX_INCLUDED_vmm_pdmdev_h */
Note: See TracBrowser for help on using the repository browser.

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