VirtualBox

source: vbox/trunk/include/VBox/vmm/pdmapi.h

Last change on this file was 106061, checked in by vboxsync, 8 weeks ago

Copyright year updates by scm.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 17.8 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, Core API.
3 *
4 * The 'Core API' has been put in a different header because everyone
5 * is currently including pdm.h. So, pdm.h is for including all of the
6 * PDM stuff, while pdmapi.h is for the core stuff.
7 */
8
9/*
10 * Copyright (C) 2006-2024 Oracle and/or its affiliates.
11 *
12 * This file is part of VirtualBox base platform packages, as
13 * available from https://www.virtualbox.org.
14 *
15 * This program is free software; you can redistribute it and/or
16 * modify it under the terms of the GNU General Public License
17 * as published by the Free Software Foundation, in version 3 of the
18 * License.
19 *
20 * This program is distributed in the hope that it will be useful, but
21 * WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23 * General Public License for more details.
24 *
25 * You should have received a copy of the GNU General Public License
26 * along with this program; if not, see <https://www.gnu.org/licenses>.
27 *
28 * The contents of this file may alternatively be used under the terms
29 * of the Common Development and Distribution License Version 1.0
30 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
31 * in the VirtualBox distribution, in which case the provisions of the
32 * CDDL are applicable instead of those of the GPL.
33 *
34 * You may elect to license modified versions of this file under the
35 * terms and conditions of either the GPL or the CDDL or both.
36 *
37 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
38 */
39
40#ifndef VBOX_INCLUDED_vmm_pdmapi_h
41#define VBOX_INCLUDED_vmm_pdmapi_h
42#ifndef RT_WITHOUT_PRAGMA_ONCE
43# pragma once
44#endif
45
46#include <VBox/vmm/pdmcommon.h>
47#ifdef IN_RING3
48# include <VBox/vmm/vmapi.h>
49#endif
50#include <VBox/sup.h>
51
52struct PDMDEVMODREGR0;
53
54RT_C_DECLS_BEGIN
55
56/** @defgroup grp_pdm The Pluggable Device Manager API
57 * @ingroup grp_vmm
58 * @{
59 */
60
61VMMDECL(int) PDMGetInterrupt(PVMCPUCC pVCpu, uint8_t *pu8Interrupt);
62VMMDECL(int) PDMIsaSetIrq(PVMCC pVM, uint8_t u8Irq, uint8_t u8Level, uint32_t uTagSrc);
63VMM_INT_DECL(bool) PDMHasIoApic(PVM pVM);
64VMM_INT_DECL(bool) PDMHasApic(PVM pVM);
65VMM_INT_DECL(PPDMDEVINS) PDMDeviceRing0IdxToInstance(PVMCC pVM, uint64_t idxR0Device);
66VMM_INT_DECL(int) PDMIoApicSetIrq(PVM pVM, PCIBDF uBusDevFn, uint8_t u8Irq, uint8_t u8Level, uint32_t uTagSrc);
67VMM_INT_DECL(void) PDMIoApicBroadcastEoi(PVMCC pVM, uint8_t uVector);
68VMM_INT_DECL(void) PDMIoApicSendMsi(PVMCC pVM, PCIBDF uBusDevFn, PCMSIMSG pMsi, uint32_t uTagSrc);
69VMM_INT_DECL(int) PDMVmmDevHeapR3ToGCPhys(PVM pVM, RTR3PTR pv, RTGCPHYS *pGCPhys);
70VMM_INT_DECL(bool) PDMVmmDevHeapIsEnabled(PVM pVM);
71
72/**
73 * Mapping/unmapping callback for an VMMDev heap allocation.
74 *
75 * @param pVM The cross context VM structure.
76 * @param pvAllocation The allocation address (ring-3).
77 * @param GCPhysAllocation The guest physical address of the mapping if
78 * it's being mapped, NIL_RTGCPHYS if it's being
79 * unmapped.
80 */
81typedef DECLCALLBACKTYPE(void, FNPDMVMMDEVHEAPNOTIFY,(PVM pVM, void *pvAllocation, RTGCPHYS GCPhysAllocation));
82/** Pointer (ring-3) to a FNPDMVMMDEVHEAPNOTIFY function. */
83typedef R3PTRTYPE(FNPDMVMMDEVHEAPNOTIFY *) PFNPDMVMMDEVHEAPNOTIFY;
84
85
86#if defined(IN_RING3) || defined(DOXYGEN_RUNNING)
87/** @defgroup grp_pdm_r3 The PDM Host Context Ring-3 API
88 * @{
89 */
90VMMR3_INT_DECL(int) PDMR3InitUVM(PUVM pUVM);
91VMMR3_INT_DECL(int) PDMR3LdrLoadVMMR0U(PUVM pUVM);
92VMMR3_INT_DECL(int) PDMR3Init(PVM pVM);
93VMMR3_INT_DECL(int) PDMR3InitCompleted(PVM pVM, VMINITCOMPLETED enmWhat);
94VMMR3DECL(void) PDMR3PowerOn(PVM pVM);
95VMMR3_INT_DECL(bool) PDMR3GetResetInfo(PVM pVM, uint32_t fOverride, uint32_t *pfResetFlags);
96VMMR3_INT_DECL(void) PDMR3ResetCpu(PVMCPU pVCpu);
97VMMR3_INT_DECL(void) PDMR3Reset(PVM pVM);
98VMMR3_INT_DECL(void) PDMR3MemSetup(PVM pVM, bool fAtReset);
99VMMR3_INT_DECL(void) PDMR3SoftReset(PVM pVM, uint32_t fResetFlags);
100VMMR3_INT_DECL(void) PDMR3Suspend(PVM pVM);
101VMMR3_INT_DECL(void) PDMR3Resume(PVM pVM);
102VMMR3DECL(void) PDMR3PowerOff(PVM pVM);
103VMMR3_INT_DECL(void) PDMR3Relocate(PVM pVM, RTGCINTPTR offDelta);
104VMMR3_INT_DECL(int) PDMR3Term(PVM pVM);
105VMMR3_INT_DECL(void) PDMR3TermUVM(PUVM pUVM);
106VMMR3_INT_DECL(bool) PDMR3HasLoadedState(PVM pVM);
107
108/** PDM loader context indicator. */
109typedef enum PDMLDRCTX
110{
111 /** Invalid zero value. */
112 PDMLDRCTX_INVALID = 0,
113 /** Ring-0 context. */
114 PDMLDRCTX_RING_0,
115 /** Ring-3 context. */
116 PDMLDRCTX_RING_3,
117 /** Raw-mode context. */
118 PDMLDRCTX_RAW_MODE,
119 /** End of valid context values. */
120 PDMLDRCTX_END,
121 /** 32-bit type hack. */
122 PDMLDRCTX_32BIT_HACK = 0x7fffffff
123} PDMLDRCTX;
124
125/**
126 * Module enumeration callback function.
127 *
128 * @returns VBox status.
129 * Failure will stop the search and return the return code.
130 * Warnings will be ignored and not returned.
131 * @param pVM The cross context VM structure.
132 * @param pszFilename Module filename.
133 * @param pszName Module name. (short and unique)
134 * @param ImageBase Address where to executable image is loaded.
135 * @param cbImage Size of the executable image.
136 * @param enmCtx The context the module is loaded into.
137 * @param pvArg User argument.
138 */
139typedef DECLCALLBACKTYPE(int, FNPDMR3ENUM,(PVM pVM, const char *pszFilename, const char *pszName,
140 RTUINTPTR ImageBase, size_t cbImage, PDMLDRCTX enmCtx, void *pvArg));
141/** Pointer to a FNPDMR3ENUM() function. */
142typedef FNPDMR3ENUM *PFNPDMR3ENUM;
143VMMR3DECL(int) PDMR3LdrEnumModules(PVM pVM, PFNPDMR3ENUM pfnCallback, void *pvArg);
144VMMR3_INT_DECL(void) PDMR3LdrRelocateU(PUVM pUVM, RTGCINTPTR offDelta);
145VMMR3_INT_DECL(int) PDMR3LdrLoadR0(PUVM pUVM, const char *pszModule, const char *pszSearchPath);
146VMMR3_INT_DECL(int) PDMR3LdrGetSymbolR3(PVM pVM, const char *pszModule, const char *pszSymbol, void **ppvValue);
147VMMR3DECL(int) PDMR3LdrGetSymbolR0(PVM pVM, const char *pszModule, const char *pszSymbol, PRTR0PTR ppvValue);
148VMMR3DECL(int) PDMR3LdrGetSymbolR0Lazy(PVM pVM, const char *pszModule, const char *pszSearchPath, const char *pszSymbol, PRTR0PTR ppvValue);
149VMMR3DECL(int) PDMR3LdrLoadRC(PVM pVM, const char *pszFilename, const char *pszName);
150VMMR3DECL(int) PDMR3LdrGetSymbolRC(PVM pVM, const char *pszModule, const char *pszSymbol, PRTRCPTR pRCPtrValue);
151VMMR3DECL(int) PDMR3LdrGetSymbolRCLazy(PVM pVM, const char *pszModule, const char *pszSearchPath, const char *pszSymbol,
152 PRTRCPTR pRCPtrValue);
153VMMR3_INT_DECL(int) PDMR3LdrQueryRCModFromPC(PVM pVM, RTRCPTR uPC,
154 char *pszModName, size_t cchModName, PRTRCPTR pMod,
155 char *pszNearSym1, size_t cchNearSym1, PRTRCPTR pNearSym1,
156 char *pszNearSym2, size_t cchNearSym2, PRTRCPTR pNearSym2);
157VMMR3_INT_DECL(int) PDMR3LdrQueryR0ModFromPC(PVM pVM, RTR0PTR uPC,
158 char *pszModName, size_t cchModName, PRTR0PTR pMod,
159 char *pszNearSym1, size_t cchNearSym1, PRTR0PTR pNearSym1,
160 char *pszNearSym2, size_t cchNearSym2, PRTR0PTR pNearSym2);
161VMMR3_INT_DECL(int) PDMR3LdrGetInterfaceSymbols(PVM pVM, void *pvInterface, size_t cbInterface,
162 const char *pszModule, const char *pszSearchPath,
163 const char *pszSymPrefix, const char *pszSymList,
164 bool fRing0OrRC);
165
166VMMR3DECL(int) PDMR3QueryDevice(PUVM pUVM, const char *pszDevice, unsigned iInstance, PPPDMIBASE ppBase);
167VMMR3DECL(int) PDMR3QueryDeviceLun(PUVM pUVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPPDMIBASE ppBase);
168VMMR3DECL(int) PDMR3QueryLun(PUVM pUVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPPDMIBASE ppBase);
169VMMR3DECL(int) PDMR3QueryDriverOnLun(PUVM pUVM, const char *pszDevice, unsigned iInstance, unsigned iLun,
170 const char *pszDriver, PPPDMIBASE ppBase);
171
172VMMR3DECL(int) PDMR3DeviceAttach(PUVM pUVM, const char *pszDevice, unsigned iInstance, unsigned iLun, uint32_t fFlags,
173 PPDMIBASE *ppBase);
174VMMR3DECL(int) PDMR3DeviceDetach(PUVM pUVM, const char *pszDevice, unsigned iInstance, unsigned iLun, uint32_t fFlags);
175VMMR3_INT_DECL(PPDMCRITSECT) PDMR3DevGetCritSect(PVM pVM, PPDMDEVINS pDevIns);
176VMMR3DECL(int) PDMR3DriverAttach(PUVM pUVM, const char *pszDevice, unsigned iDevIns, unsigned iLun, uint32_t fFlags,
177 PPPDMIBASE ppBase);
178VMMR3DECL(int) PDMR3DriverDetach(PUVM pUVM, const char *pszDevice, unsigned iDevIns, unsigned iLun,
179 const char *pszDriver, unsigned iOccurrence, uint32_t fFlags);
180VMMR3DECL(int) PDMR3DriverReattach(PUVM pVM, const char *pszDevice, unsigned iDevIns, unsigned iLun,
181 const char *pszDriver, unsigned iOccurrence, uint32_t fFlags, PCFGMNODE pCfg,
182 PPPDMIBASE ppBase);
183/**
184 * Driver instance enumeration callback function.
185 *
186 * @returns VBox status code. Failures will stop the enumeration and be
187 * returned, informational statuses will be ignored and not returned.
188 * @param pIBase The base interface of the driver.
189 * @param uDrvInstance The driver instance number.
190 * @param fUsbDev Set if @a pszDevice is a USB device, clear if a
191 * regular device.
192 * @param pszDevice The device the driver is attached to.
193 * @param uDevInstance The device instance number.
194 * @param uLun The LUN on the device this instance is attached to.
195 * @param pvUser User argument.
196 *
197 * @note Called owning the core PDM list lock in shared mode.
198 */
199typedef DECLCALLBACKTYPE(int, FNPDMENUMDRVINS,(PPDMIBASE pIBase, uint32_t uDrvInstance, bool fUsbDev, const char *pszDevice,
200 uint32_t uDevInstance, unsigned uLun, void *pvUser));
201/** Pointer to a FNPDMENUMDRVINS() function. */
202typedef FNPDMENUMDRVINS *PFNPDMENUMDRVINS;
203VMMR3DECL(int) PDMR3DriverEnumInstances(PUVM pUVM, const char *pszDriver, PFNPDMENUMDRVINS pfnCallback, void *pvUser);
204
205VMMR3DECL(void) PDMR3DmaRun(PVM pVM);
206
207VMMR3_INT_DECL(int) PDMR3VmmDevHeapAlloc(PVM pVM, size_t cbSize, PFNPDMVMMDEVHEAPNOTIFY pfnNotify, RTR3PTR *ppv);
208VMMR3_INT_DECL(int) PDMR3VmmDevHeapFree(PVM pVM, RTR3PTR pv);
209VMMR3_INT_DECL(int) PDMR3TracingConfig(PVM pVM, const char *pszName, size_t cchName, bool fEnable, bool fApply);
210VMMR3_INT_DECL(bool) PDMR3TracingAreAll(PVM pVM, bool fEnabled);
211VMMR3_INT_DECL(int) PDMR3TracingQueryConfig(PVM pVM, char *pszConfig, size_t cbConfig);
212/** @} */
213#endif /* IN_RING3 */
214
215
216
217/** @defgroup grp_pdm_rc The PDM Raw-Mode Context API
218 * @{
219 */
220/** @} */
221
222
223
224/** @defgroup grp_pdm_r0 The PDM Ring-0 Context API
225 * @{
226 */
227VMMR0_INT_DECL(void) PDMR0Init(void *hMod);
228VMMR0DECL(int) PDMR0DeviceRegisterModule(void *hMod, struct PDMDEVMODREGR0 *pModReg);
229VMMR0DECL(int) PDMR0DeviceDeregisterModule(void *hMod, struct PDMDEVMODREGR0 *pModReg);
230
231VMMR0_INT_DECL(void) PDMR0InitPerVMData(PGVM pGVM);
232VMMR0_INT_DECL(void) PDMR0CleanupVM(PGVM pGVM);
233
234/**
235 * Request buffer for PDMR0DriverCallReqHandler / VMMR0_DO_PDM_DRIVER_CALL_REQ_HANDLER.
236 * @see PDMR0DriverCallReqHandler.
237 */
238typedef struct PDMDRIVERCALLREQHANDLERREQ
239{
240 /** The header. */
241 SUPVMMR0REQHDR Hdr;
242 /** The driver instance. */
243 PPDMDRVINSR0 pDrvInsR0;
244 /** The operation. */
245 uint32_t uOperation;
246 /** Explicit alignment padding. */
247 uint32_t u32Alignment;
248 /** Optional 64-bit integer argument. */
249 uint64_t u64Arg;
250} PDMDRIVERCALLREQHANDLERREQ;
251/** Pointer to a PDMR0DriverCallReqHandler / VMMR0_DO_PDM_DRIVER_CALL_REQ_HANDLER
252 * request buffer. */
253typedef PDMDRIVERCALLREQHANDLERREQ *PPDMDRIVERCALLREQHANDLERREQ;
254
255VMMR0_INT_DECL(int) PDMR0DriverCallReqHandler(PGVM pGVM, PPDMDRIVERCALLREQHANDLERREQ pReq);
256
257
258/**
259 * Request buffer for PDMR0DeviceCreateReqHandler / VMMR0_DO_PDM_DEVICE_CREATE.
260 * @see PDMR0DeviceCreateReqHandler.
261 */
262typedef struct PDMDEVICECREATEREQ
263{
264 /** The header. */
265 SUPVMMR0REQHDR Hdr;
266 /** Out: Where to return the address of the ring-3 device instance. */
267 PPDMDEVINSR3 pDevInsR3;
268
269 /** Copy of PDMDEVREGR3::fFlags for matching with PDMDEVREGR0::fFlags. */
270 uint32_t fFlags;
271 /** Copy of PDMDEVREGR3::fClass for matching with PDMDEVREGR0::fFlags. */
272 uint32_t fClass;
273 /** Copy of PDMDEVREGR3::cMaxInstances for matching with
274 * PDMDEVREGR0::cMaxInstances. */
275 uint32_t cMaxInstances;
276 /** Copy of PDMDEVREGR3::uSharedVersion for matching with
277 * PDMDEVREGR0::uSharedVersion. */
278 uint32_t uSharedVersion;
279 /** Copy of PDMDEVREGR3::cbInstanceShared for matching with
280 * PDMDEVREGR0::cbInstanceShared. */
281 uint32_t cbInstanceShared;
282 /** Copy of PDMDEVREGR3::cbInstanceCC. */
283 uint32_t cbInstanceR3;
284 /** Copy of PDMDEVREGR3::cbInstanceRC for matching with
285 * PDMDEVREGR0::cbInstanceRC. */
286 uint32_t cbInstanceRC;
287 /** Copy of PDMDEVREGR3::cMaxPciDevices for matching with
288 * PDMDEVREGR0::cMaxPciDevices. */
289 uint16_t cMaxPciDevices;
290 /** Copy of PDMDEVREGR3::cMaxMsixVectors for matching with
291 * PDMDEVREGR0::cMaxMsixVectors. */
292 uint16_t cMaxMsixVectors;
293
294 /** The device instance ordinal. */
295 uint32_t iInstance;
296 /** Set if the raw-mode component is desired. */
297 bool fRCEnabled;
298 /** Explicit padding. */
299 bool afReserved[3];
300 /** DBGF tracer event source handle if configured. */
301 DBGFTRACEREVTSRC hDbgfTracerEvtSrc;
302
303 /** In: Device name. */
304 char szDevName[32];
305 /** In: The module name (no path). */
306 char szModName[32];
307} PDMDEVICECREATEREQ;
308/** Pointer to a PDMR0DeviceCreate / VMMR0_DO_PDM_DEVICE_CREATE request buffer. */
309typedef PDMDEVICECREATEREQ *PPDMDEVICECREATEREQ;
310
311VMMR0_INT_DECL(int) PDMR0DeviceCreateReqHandler(PGVM pGVM, PPDMDEVICECREATEREQ pReq);
312
313/**
314 * The ring-0 device call to make.
315 */
316typedef enum PDMDEVICEGENCALL
317{
318 PDMDEVICEGENCALL_INVALID = 0,
319 PDMDEVICEGENCALL_CONSTRUCT,
320 PDMDEVICEGENCALL_DESTRUCT,
321 PDMDEVICEGENCALL_REQUEST,
322 PDMDEVICEGENCALL_END,
323 PDMDEVICEGENCALL_32BIT_HACK = 0x7fffffff
324} PDMDEVICEGENCALL;
325
326/**
327 * Request buffer for PDMR0DeviceGenCallReqHandler / VMMR0_DO_PDM_DEVICE_GEN_CALL.
328 * @see PDMR0DeviceGenCallReqHandler.
329 */
330typedef struct PDMDEVICEGENCALLREQ
331{
332 /** The header. */
333 SUPVMMR0REQHDR Hdr;
334 /** The ring-3 device instance. */
335 PPDMDEVINSR3 pDevInsR3;
336 /** The ring-0 device handle. */
337 uint32_t idxR0Device;
338 /** The call to make. */
339 PDMDEVICEGENCALL enmCall;
340 union
341 {
342 /** PDMDEVICEGENCALL_REQUEST: */
343 struct
344 {
345 /** The request argument. */
346 uint64_t uArg;
347 /** The request number. */
348 uint32_t uReq;
349 } Req;
350 /** Size padding. */
351 uint64_t au64[3];
352 } Params;
353} PDMDEVICEGENCALLREQ;
354/** Pointer to a PDMR0DeviceGenCallReqHandler / VMMR0_DO_PDM_DEVICE_GEN_CALL request buffer. */
355typedef PDMDEVICEGENCALLREQ *PPDMDEVICEGENCALLREQ;
356
357VMMR0_INT_DECL(int) PDMR0DeviceGenCallReqHandler(PGVM pGVM, PPDMDEVICEGENCALLREQ pReq, VMCPUID idCpu);
358
359/**
360 * Request buffer for PDMR0DeviceCompatSetCritSectReqHandler / VMMR0_DO_PDM_DEVICE_COMPAT_SET_CRITSECT
361 * @see PDMR0DeviceCompatSetCritSectReqHandler.
362 */
363typedef struct PDMDEVICECOMPATSETCRITSECTREQ
364{
365 /** The header. */
366 SUPVMMR0REQHDR Hdr;
367 /** The ring-3 device instance. */
368 PPDMDEVINSR3 pDevInsR3;
369 /** The ring-0 device handle. */
370 uint32_t idxR0Device;
371 /** The critical section address (ring-3). */
372 R3PTRTYPE(PPDMCRITSECT) pCritSectR3;
373} PDMDEVICECOMPATSETCRITSECTREQ;
374/** Pointer to a PDMR0DeviceGenCallReqHandler / VMMR0_DO_PDM_DEVICE_GEN_CALL request buffer. */
375typedef PDMDEVICECOMPATSETCRITSECTREQ *PPDMDEVICECOMPATSETCRITSECTREQ;
376
377VMMR0_INT_DECL(int) PDMR0DeviceCompatSetCritSectReqHandler(PGVM pGVM, PPDMDEVICECOMPATSETCRITSECTREQ pReq);
378
379
380/**
381 * Request buffer for PDMR0QueueCreateReqHandler / VMMR0_DO_PDM_QUEUE_CREATE.
382 * @see PDMR0QueueCreateReqHandler.
383 */
384typedef struct PDMQUEUECREATEREQ
385{
386 /** The header. */
387 SUPVMMR0REQHDR Hdr;
388
389 /** Number of queue items. */
390 uint32_t cItems;
391 /** Queue item size. */
392 uint32_t cbItem;
393 /** Owner type (PDMQUEUETYPE). */
394 uint32_t enmType;
395 /** The ring-3 owner pointer. */
396 RTR3PTR pvOwner;
397 /** The ring-3 callback function address. */
398 RTR3PTR pfnCallback;
399 /** The queue name. */
400 char szName[40];
401
402 /** Output: The queue handle. */
403 PDMQUEUEHANDLE hQueue;
404} PDMQUEUECREATEREQ;
405/** Pointer to a PDMR0QueueCreateReqHandler / VMMR0_DO_PDM_QUEUE_CREATE request buffer. */
406typedef PDMQUEUECREATEREQ *PPDMQUEUECREATEREQ;
407
408VMMR0_INT_DECL(int) PDMR0QueueCreateReqHandler(PGVM pGVM, PPDMQUEUECREATEREQ pReq);
409
410/** @} */
411
412RT_C_DECLS_END
413
414/** @} */
415
416#endif /* !VBOX_INCLUDED_vmm_pdmapi_h */
Note: See TracBrowser for help on using the repository browser.

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