pdmapi.h@ 99760

Last change on this file since 99760 was 98103, checked in by vboxsync, 23 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 16.6 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-2023 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
52	struct PDMDEVMODREGR0;
53
54	RT_C_DECLS_BEGIN
55
56	/** @defgroup grp_pdm The Pluggable Device Manager API
57	* @ingroup grp_vmm
58	* @{
59	*/
60
61	VMMDECL(int) PDMGetInterrupt(PVMCPUCC pVCpu, uint8_t *pu8Interrupt);
62	VMMDECL(int) PDMIsaSetIrq(PVMCC pVM, uint8_t u8Irq, uint8_t u8Level, uint32_t uTagSrc);
63	VMM_INT_DECL(bool) PDMHasIoApic(PVM pVM);
64	VMM_INT_DECL(bool) PDMHasApic(PVM pVM);
65	VMM_INT_DECL(PPDMDEVINS) PDMDeviceRing0IdxToInstance(PVMCC pVM, uint64_t idxR0Device);
66	VMM_INT_DECL(int) PDMIoApicSetIrq(PVM pVM, PCIBDF uBusDevFn, uint8_t u8Irq, uint8_t u8Level, uint32_t uTagSrc);
67	VMM_INT_DECL(void) PDMIoApicBroadcastEoi(PVMCC pVM, uint8_t uVector);
68	VMM_INT_DECL(void) PDMIoApicSendMsi(PVMCC pVM, PCIBDF uBusDevFn, PCMSIMSG pMsi, uint32_t uTagSrc);
69	VMM_INT_DECL(int) PDMVmmDevHeapR3ToGCPhys(PVM pVM, RTR3PTR pv, RTGCPHYS *pGCPhys);
70	VMM_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	*/
81	typedef DECLCALLBACKTYPE(void, FNPDMVMMDEVHEAPNOTIFY,(PVM pVM, void *pvAllocation, RTGCPHYS GCPhysAllocation));
82	/** Pointer (ring-3) to a FNPDMVMMDEVHEAPNOTIFY function. */
83	typedef 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	*/
90	VMMR3_INT_DECL(int) PDMR3InitUVM(PUVM pUVM);
91	VMMR3_INT_DECL(int) PDMR3LdrLoadVMMR0U(PUVM pUVM);
92	VMMR3_INT_DECL(int) PDMR3Init(PVM pVM);
93	VMMR3_INT_DECL(int) PDMR3InitCompleted(PVM pVM, VMINITCOMPLETED enmWhat);
94	VMMR3DECL(void) PDMR3PowerOn(PVM pVM);
95	VMMR3_INT_DECL(bool) PDMR3GetResetInfo(PVM pVM, uint32_t fOverride, uint32_t *pfResetFlags);
96	VMMR3_INT_DECL(void) PDMR3ResetCpu(PVMCPU pVCpu);
97	VMMR3_INT_DECL(void) PDMR3Reset(PVM pVM);
98	VMMR3_INT_DECL(void) PDMR3MemSetup(PVM pVM, bool fAtReset);
99	VMMR3_INT_DECL(void) PDMR3SoftReset(PVM pVM, uint32_t fResetFlags);
100	VMMR3_INT_DECL(void) PDMR3Suspend(PVM pVM);
101	VMMR3_INT_DECL(void) PDMR3Resume(PVM pVM);
102	VMMR3DECL(void) PDMR3PowerOff(PVM pVM);
103	VMMR3_INT_DECL(void) PDMR3Relocate(PVM pVM, RTGCINTPTR offDelta);
104	VMMR3_INT_DECL(int) PDMR3Term(PVM pVM);
105	VMMR3_INT_DECL(void) PDMR3TermUVM(PUVM pUVM);
106	VMMR3_INT_DECL(bool) PDMR3HasLoadedState(PVM pVM);
107
108	/** PDM loader context indicator. */
109	typedef 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	*/
139	typedef 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. */
142	typedef FNPDMR3ENUM *PFNPDMR3ENUM;
143	VMMR3DECL(int) PDMR3LdrEnumModules(PVM pVM, PFNPDMR3ENUM pfnCallback, void *pvArg);
144	VMMR3_INT_DECL(void) PDMR3LdrRelocateU(PUVM pUVM, RTGCINTPTR offDelta);
145	VMMR3_INT_DECL(int) PDMR3LdrLoadR0(PUVM pUVM, const char pszModule, const char pszSearchPath);
146	VMMR3_INT_DECL(int) PDMR3LdrGetSymbolR3(PVM pVM, const char pszModule, const char pszSymbol, void **ppvValue);
147	VMMR3DECL(int) PDMR3LdrGetSymbolR0(PVM pVM, const char pszModule, const char pszSymbol, PRTR0PTR ppvValue);
148	VMMR3DECL(int) PDMR3LdrGetSymbolR0Lazy(PVM pVM, const char pszModule, const char pszSearchPath, const char *pszSymbol, PRTR0PTR ppvValue);
149	VMMR3DECL(int) PDMR3LdrLoadRC(PVM pVM, const char pszFilename, const char pszName);
150	VMMR3DECL(int) PDMR3LdrGetSymbolRC(PVM pVM, const char pszModule, const char pszSymbol, PRTRCPTR pRCPtrValue);
151	VMMR3DECL(int) PDMR3LdrGetSymbolRCLazy(PVM pVM, const char pszModule, const char pszSearchPath, const char *pszSymbol,
152	PRTRCPTR pRCPtrValue);
153	VMMR3_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);
157	VMMR3_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);
161	VMMR3_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
166	VMMR3DECL(int) PDMR3QueryDevice(PUVM pUVM, const char *pszDevice, unsigned iInstance, PPPDMIBASE ppBase);
167	VMMR3DECL(int) PDMR3QueryDeviceLun(PUVM pUVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPPDMIBASE ppBase);
168	VMMR3DECL(int) PDMR3QueryLun(PUVM pUVM, const char *pszDevice, unsigned iInstance, unsigned iLun, PPPDMIBASE ppBase);
169	VMMR3DECL(int) PDMR3QueryDriverOnLun(PUVM pUVM, const char *pszDevice, unsigned iInstance, unsigned iLun,
170	const char *pszDriver, PPPDMIBASE ppBase);
171	VMMR3DECL(int) PDMR3DeviceAttach(PUVM pUVM, const char *pszDevice, unsigned iInstance, unsigned iLun, uint32_t fFlags,
172	PPDMIBASE *ppBase);
173	VMMR3DECL(int) PDMR3DeviceDetach(PUVM pUVM, const char *pszDevice, unsigned iInstance, unsigned iLun, uint32_t fFlags);
174	VMMR3_INT_DECL(PPDMCRITSECT) PDMR3DevGetCritSect(PVM pVM, PPDMDEVINS pDevIns);
175	VMMR3DECL(int) PDMR3DriverAttach(PUVM pUVM, const char *pszDevice, unsigned iDevIns, unsigned iLun, uint32_t fFlags,
176	PPPDMIBASE ppBase);
177	VMMR3DECL(int) PDMR3DriverDetach(PUVM pUVM, const char *pszDevice, unsigned iDevIns, unsigned iLun,
178	const char *pszDriver, unsigned iOccurrence, uint32_t fFlags);
179	VMMR3DECL(int) PDMR3DriverReattach(PUVM pVM, const char *pszDevice, unsigned iDevIns, unsigned iLun,
180	const char *pszDriver, unsigned iOccurrence, uint32_t fFlags, PCFGMNODE pCfg,
181	PPPDMIBASE ppBase);
182	VMMR3DECL(void) PDMR3DmaRun(PVM pVM);
183
184	VMMR3_INT_DECL(int) PDMR3VmmDevHeapAlloc(PVM pVM, size_t cbSize, PFNPDMVMMDEVHEAPNOTIFY pfnNotify, RTR3PTR *ppv);
185	VMMR3_INT_DECL(int) PDMR3VmmDevHeapFree(PVM pVM, RTR3PTR pv);
186	VMMR3_INT_DECL(int) PDMR3TracingConfig(PVM pVM, const char *pszName, size_t cchName, bool fEnable, bool fApply);
187	VMMR3_INT_DECL(bool) PDMR3TracingAreAll(PVM pVM, bool fEnabled);
188	VMMR3_INT_DECL(int) PDMR3TracingQueryConfig(PVM pVM, char *pszConfig, size_t cbConfig);
189	/** @} */
190	#endif /* IN_RING3 */
191
192
193
194	/** @defgroup grp_pdm_rc The PDM Raw-Mode Context API
195	* @{
196	*/
197	/** @} */
198
199
200
201	/** @defgroup grp_pdm_r0 The PDM Ring-0 Context API
202	* @{
203	*/
204	VMMR0_INT_DECL(void) PDMR0Init(void *hMod);
205	VMMR0DECL(int) PDMR0DeviceRegisterModule(void hMod, struct PDMDEVMODREGR0 pModReg);
206	VMMR0DECL(int) PDMR0DeviceDeregisterModule(void hMod, struct PDMDEVMODREGR0 pModReg);
207
208	VMMR0_INT_DECL(void) PDMR0InitPerVMData(PGVM pGVM);
209	VMMR0_INT_DECL(void) PDMR0CleanupVM(PGVM pGVM);
210
211	/**
212	* Request buffer for PDMR0DriverCallReqHandler / VMMR0_DO_PDM_DRIVER_CALL_REQ_HANDLER.
213	* @see PDMR0DriverCallReqHandler.
214	*/
215	typedef struct PDMDRIVERCALLREQHANDLERREQ
216	{
217	/** The header. */
218	SUPVMMR0REQHDR Hdr;
219	/** The driver instance. */
220	PPDMDRVINSR0 pDrvInsR0;
221	/** The operation. */
222	uint32_t uOperation;
223	/** Explicit alignment padding. */
224	uint32_t u32Alignment;
225	/** Optional 64-bit integer argument. */
226	uint64_t u64Arg;
227	} PDMDRIVERCALLREQHANDLERREQ;
228	/** Pointer to a PDMR0DriverCallReqHandler / VMMR0_DO_PDM_DRIVER_CALL_REQ_HANDLER
229	* request buffer. */
230	typedef PDMDRIVERCALLREQHANDLERREQ *PPDMDRIVERCALLREQHANDLERREQ;
231
232	VMMR0_INT_DECL(int) PDMR0DriverCallReqHandler(PGVM pGVM, PPDMDRIVERCALLREQHANDLERREQ pReq);
233
234
235	/**
236	* Request buffer for PDMR0DeviceCreateReqHandler / VMMR0_DO_PDM_DEVICE_CREATE.
237	* @see PDMR0DeviceCreateReqHandler.
238	*/
239	typedef struct PDMDEVICECREATEREQ
240	{
241	/** The header. */
242	SUPVMMR0REQHDR Hdr;
243	/** Out: Where to return the address of the ring-3 device instance. */
244	PPDMDEVINSR3 pDevInsR3;
245
246	/** Copy of PDMDEVREGR3::fFlags for matching with PDMDEVREGR0::fFlags. */
247	uint32_t fFlags;
248	/** Copy of PDMDEVREGR3::fClass for matching with PDMDEVREGR0::fFlags. */
249	uint32_t fClass;
250	/** Copy of PDMDEVREGR3::cMaxInstances for matching with
251	* PDMDEVREGR0::cMaxInstances. */
252	uint32_t cMaxInstances;
253	/** Copy of PDMDEVREGR3::uSharedVersion for matching with
254	* PDMDEVREGR0::uSharedVersion. */
255	uint32_t uSharedVersion;
256	/** Copy of PDMDEVREGR3::cbInstanceShared for matching with
257	* PDMDEVREGR0::cbInstanceShared. */
258	uint32_t cbInstanceShared;
259	/** Copy of PDMDEVREGR3::cbInstanceCC. */
260	uint32_t cbInstanceR3;
261	/** Copy of PDMDEVREGR3::cbInstanceRC for matching with
262	* PDMDEVREGR0::cbInstanceRC. */
263	uint32_t cbInstanceRC;
264	/** Copy of PDMDEVREGR3::cMaxPciDevices for matching with
265	* PDMDEVREGR0::cMaxPciDevices. */
266	uint16_t cMaxPciDevices;
267	/** Copy of PDMDEVREGR3::cMaxMsixVectors for matching with
268	* PDMDEVREGR0::cMaxMsixVectors. */
269	uint16_t cMaxMsixVectors;
270
271	/** The device instance ordinal. */
272	uint32_t iInstance;
273	/** Set if the raw-mode component is desired. */
274	bool fRCEnabled;
275	/** Explicit padding. */
276	bool afReserved[3];
277	/** DBGF tracer event source handle if configured. */
278	DBGFTRACEREVTSRC hDbgfTracerEvtSrc;
279
280	/** In: Device name. */
281	char szDevName[32];
282	/** In: The module name (no path). */
283	char szModName[32];
284	} PDMDEVICECREATEREQ;
285	/** Pointer to a PDMR0DeviceCreate / VMMR0_DO_PDM_DEVICE_CREATE request buffer. */
286	typedef PDMDEVICECREATEREQ *PPDMDEVICECREATEREQ;
287
288	VMMR0_INT_DECL(int) PDMR0DeviceCreateReqHandler(PGVM pGVM, PPDMDEVICECREATEREQ pReq);
289
290	/**
291	* The ring-0 device call to make.
292	*/
293	typedef enum PDMDEVICEGENCALL
294	{
295	PDMDEVICEGENCALL_INVALID = 0,
296	PDMDEVICEGENCALL_CONSTRUCT,
297	PDMDEVICEGENCALL_DESTRUCT,
298	PDMDEVICEGENCALL_REQUEST,
299	PDMDEVICEGENCALL_END,
300	PDMDEVICEGENCALL_32BIT_HACK = 0x7fffffff
301	} PDMDEVICEGENCALL;
302
303	/**
304	* Request buffer for PDMR0DeviceGenCallReqHandler / VMMR0_DO_PDM_DEVICE_GEN_CALL.
305	* @see PDMR0DeviceGenCallReqHandler.
306	*/
307	typedef struct PDMDEVICEGENCALLREQ
308	{
309	/** The header. */
310	SUPVMMR0REQHDR Hdr;
311	/** The ring-3 device instance. */
312	PPDMDEVINSR3 pDevInsR3;
313	/** The ring-0 device handle. */
314	uint32_t idxR0Device;
315	/** The call to make. */
316	PDMDEVICEGENCALL enmCall;
317	union
318	{
319	/** PDMDEVICEGENCALL_REQUEST: */
320	struct
321	{
322	/** The request argument. */
323	uint64_t uArg;
324	/** The request number. */
325	uint32_t uReq;
326	} Req;
327	/** Size padding. */
328	uint64_t au64[3];
329	} Params;
330	} PDMDEVICEGENCALLREQ;
331	/** Pointer to a PDMR0DeviceGenCallReqHandler / VMMR0_DO_PDM_DEVICE_GEN_CALL request buffer. */
332	typedef PDMDEVICEGENCALLREQ *PPDMDEVICEGENCALLREQ;
333
334	VMMR0_INT_DECL(int) PDMR0DeviceGenCallReqHandler(PGVM pGVM, PPDMDEVICEGENCALLREQ pReq, VMCPUID idCpu);
335
336	/**
337	* Request buffer for PDMR0DeviceCompatSetCritSectReqHandler / VMMR0_DO_PDM_DEVICE_COMPAT_SET_CRITSECT
338	* @see PDMR0DeviceCompatSetCritSectReqHandler.
339	*/
340	typedef struct PDMDEVICECOMPATSETCRITSECTREQ
341	{
342	/** The header. */
343	SUPVMMR0REQHDR Hdr;
344	/** The ring-3 device instance. */
345	PPDMDEVINSR3 pDevInsR3;
346	/** The ring-0 device handle. */
347	uint32_t idxR0Device;
348	/** The critical section address (ring-3). */
349	R3PTRTYPE(PPDMCRITSECT) pCritSectR3;
350	} PDMDEVICECOMPATSETCRITSECTREQ;
351	/** Pointer to a PDMR0DeviceGenCallReqHandler / VMMR0_DO_PDM_DEVICE_GEN_CALL request buffer. */
352	typedef PDMDEVICECOMPATSETCRITSECTREQ *PPDMDEVICECOMPATSETCRITSECTREQ;
353
354	VMMR0_INT_DECL(int) PDMR0DeviceCompatSetCritSectReqHandler(PGVM pGVM, PPDMDEVICECOMPATSETCRITSECTREQ pReq);
355
356
357	/**
358	* Request buffer for PDMR0QueueCreateReqHandler / VMMR0_DO_PDM_QUEUE_CREATE.
359	* @see PDMR0QueueCreateReqHandler.
360	*/
361	typedef struct PDMQUEUECREATEREQ
362	{
363	/** The header. */
364	SUPVMMR0REQHDR Hdr;
365
366	/** Number of queue items. */
367	uint32_t cItems;
368	/** Queue item size. */
369	uint32_t cbItem;
370	/** Owner type (PDMQUEUETYPE). */
371	uint32_t enmType;
372	/** The ring-3 owner pointer. */
373	RTR3PTR pvOwner;
374	/** The ring-3 callback function address. */
375	RTR3PTR pfnCallback;
376	/** The queue name. */
377	char szName[40];
378
379	/** Output: The queue handle. */
380	PDMQUEUEHANDLE hQueue;
381	} PDMQUEUECREATEREQ;
382	/** Pointer to a PDMR0QueueCreateReqHandler / VMMR0_DO_PDM_QUEUE_CREATE request buffer. */
383	typedef PDMQUEUECREATEREQ *PPDMQUEUECREATEREQ;
384
385	VMMR0_INT_DECL(int) PDMR0QueueCreateReqHandler(PGVM pGVM, PPDMQUEUECREATEREQ pReq);
386
387	/** @} */
388
389	RT_C_DECLS_END
390
391	/** @} */
392
393	#endif /* !VBOX_INCLUDED_vmm_pdmapi_h */

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: