pdmpci.h@ 81366

Last change on this file since 81366 was 81366, checked in by vboxsync, 5 years ago
vmm/pdmpci.h: doxygen
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 15.8 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, raw PCI Devices. (VMM)
3	*/
4
5	/*
6	* Copyright (C) 2010-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_pdmpci_h
27	#define VBOX_INCLUDED_vmm_pdmpci_h
28	#ifndef RT_WITHOUT_PRAGMA_ONCE
29	# pragma once
30	#endif
31
32	#include <VBox/types.h>
33	#include <VBox/rawpci.h>
34
35	RT_C_DECLS_BEGIN
36
37	/** @defgroup grp_pdm_pciraw The raw PCI Devices API
38	* @ingroup grp_pdm
39	* @{
40	*/
41
42	typedef struct PDMIPCIRAW *PPDMIPCIRAW;
43	typedef struct PDMIPCIRAW
44	{
45	/**
46	* Notify virtual device that interrupt has arrived.
47	* For this callback to be called, interface have to be
48	* registered with PDMIPCIRAWUP::pfnRegisterInterruptListener.
49	*
50	* @note no level parameter, as we can only support flip-flop.
51	*
52	* @param pInterface Pointer to this interface structure.
53	* @param iGuestIrq Guest interrupt number, passed earlier when registering listener.
54	*
55	* @thread Any thread.
56	*/
57	DECLR3CALLBACKMEMBER(int, pfnInterruptRequest,(PPDMIPCIRAW pInterface, int32_t iGuestIrq));
58	} PDMIPCIRAW;
59
60	typedef struct PDMIPCIRAWUP *PPDMIPCIRAWUP;
61	typedef struct PDMIPCIRAWUP
62	{
63	/**
64	* Host PCI MMIO access function.
65	*/
66
67	/**
68	* Request driver info about PCI region on host PCI device.
69	*
70	* @returns true, if region is present, and out parameters are correct
71	* @param pInterface Pointer to this interface structure.
72	* @param iRegion Region number.
73	* @param pGCPhysRegion Where to store region base address (guest).
74	* @param pcbRegion Where to store region size.
75	*
76	* @param pfFlags If region is MMIO or IO.
77	* @thread Any thread.
78	*/
79	DECLR3CALLBACKMEMBER(bool, pfnGetRegionInfo, (PPDMIPCIRAWUP pInterface,
80	uint32_t iRegion,
81	RTGCPHYS *pGCPhysRegion,
82	uint64_t *pcbRegion,
83	uint32_t *pfFlags));
84
85	/**
86	* Request driver to map part of host device's MMIO region to the VM process and maybe kernel.
87	* Shall only be issued within earlier obtained with pfnGetRegionInfo()
88	* host physical address ranges for the device BARs. Even if failed, device still may function
89	* using pfnMmio* and pfnPio* operations, just much slower.
90	*
91	* @returns status code
92	* @param pInterface Pointer to this interface structure.
93	* @param iRegion Number of the region.
94	* @param StartAddress Host physical address of start.
95	* @param cbRegion Size of the region.
96	* @param fFlags Flags, currently lowest significant bit set if R0 mapping requested too
97	* @param ppvAddressR3 Where to store mapped region address for R3 (can be 0, if cannot map into userland)
98	* @param ppvAddressR0 Where to store mapped region address for R0 (can be 0, if cannot map into kernel)
99	*
100	* @thread Any thread.
101	*/
102	DECLR3CALLBACKMEMBER(int, pfnMapRegion, (PPDMIPCIRAWUP pInterface,
103	uint32_t iRegion,
104	RTHCPHYS StartAddress,
105	uint64_t cbRegion,
106	uint32_t fFlags,
107	PRTR3PTR ppvAddressR3,
108	PRTR0PTR ppvAddressR0));
109
110	/**
111	* Request driver to unmap part of host device's MMIO region to the VM process.
112	* Shall only be issued with pointer earlier obtained with pfnMapRegion().
113	*
114	* @returns status code
115	* @param pInterface Pointer to this interface structure
116	* @param iRegion Number of the region.
117	* @param StartAddress Host physical address of start.
118	* @param cbRegion Size of the region.
119	* @param pvAddressR3 R3 address of mapped region.
120	* @param pvAddressR0 R0 address of mapped region.
121	*
122	* @thread Any thread.
123	*/
124	DECLR3CALLBACKMEMBER(int, pfnUnmapRegion, (PPDMIPCIRAWUP pInterface,
125	uint32_t iRegion,
126	RTHCPHYS StartAddress,
127	uint64_t cbRegion,
128	RTR3PTR pvAddressR3,
129	RTR0PTR pvAddressR0));
130
131	/**
132	* Request port IO write.
133	*
134	* @returns status code
135	* @param pInterface Pointer to this interface structure.
136	* @param uPort I/O port address.
137	* @param uValue Value to write.
138	* @param cb Access width.
139	*
140	* @thread EMT thread.
141	*/
142	DECLR3CALLBACKMEMBER(int, pfnPioWrite, (PPDMIPCIRAWUP pInterface,
143	RTIOPORT uPort,
144	uint32_t uValue,
145	unsigned cb));
146
147	/**
148	* Request port IO read.
149	*
150	* @returns status code
151	* @param pInterface Pointer to this interface structure.
152	* @param uPort I/O port address.
153	* @param puValue Place to store read value.
154	* @param cb Access width.
155	*
156	* @thread EMT thread.
157	*/
158	DECLR3CALLBACKMEMBER(int, pfnPioRead, (PPDMIPCIRAWUP pInterface,
159	RTIOPORT uPort,
160	uint32_t *puValue,
161	unsigned cb));
162
163
164	/**
165	* Request MMIO write.
166	*
167	* This callback is only called if driver wants to receive MMIO via pu32Flags
168	* argument of pfnPciDeviceConstructStart().
169	*
170	* @returns status code
171	* @param pInterface Pointer to this interface structure.
172	* @param Address Guest physical address.
173	* @param pvValue Address of value to write.
174	* @param cb Access width.
175	*
176	* @todo Why is this @a Address documented as guest physical
177	* address and given a host ring-0 address type?
178	*
179	* @thread EMT thread.
180	*/
181	DECLR3CALLBACKMEMBER(int, pfnMmioWrite, (PPDMIPCIRAWUP pInterface,
182	RTR0PTR Address,
183	void const *pvValue,
184	unsigned cb));
185
186	/**
187	* Request MMIO read.
188	*
189	* @returns status code
190	* @param pInterface Pointer to this interface structure.
191	* @param Address Guest physical address.
192	* @param pvValue Place to store read value.
193	* @param cb Access width.
194	*
195	* @todo Why is this @a Address documented as guest physical
196	* address and given a host ring-0 address type?
197	*
198	* @thread EMT thread.
199	*/
200	DECLR3CALLBACKMEMBER(int, pfnMmioRead, (PPDMIPCIRAWUP pInterface,
201	RTR0PTR Address,
202	void *pvValue,
203	unsigned cb));
204
205	/**
206	* Host PCI config space accessors.
207	*/
208	/**
209	* Request driver to write value to host device's PCI config space.
210	* Host specific way (PIO or MCFG) is used to perform actual operation.
211	*
212	* @returns status code
213	* @param pInterface Pointer to this interface structure.
214	* @param offCfgSpace Offset in PCI config space.
215	* @param pvValue Value to write.
216	* @param cb Access width.
217	*
218	* @thread EMT thread.
219	*/
220	DECLR3CALLBACKMEMBER(int, pfnPciCfgWrite, (PPDMIPCIRAWUP pInterface,
221	uint32_t offCfgSpace,
222	void *pvValue,
223	unsigned cb));
224	/**
225	* Request driver to read value from host device's PCI config space.
226	* Host specific way (PIO or MCFG) is used to perform actual operation.
227	*
228	* @returns status code
229	* @param pInterface Pointer to this interface structure.
230	* @param offCfgSpace Offset in PCI config space.
231	* @param pvValue Where to store read value.
232	* @param cb Access width.
233	*
234	* @thread EMT thread.
235	*/
236	DECLR3CALLBACKMEMBER(int, pfnPciCfgRead, (PPDMIPCIRAWUP pInterface,
237	uint32_t offCfgSpace,
238	void *pvValue,
239	unsigned cb));
240
241	/**
242	* Request to enable interrupt notifications. Please note that this is purely
243	* R3 interface, so it's up to implementor to perform necessary machinery
244	* for communications with host OS kernel driver. Typical implementation will start
245	* userland thread waiting on shared semaphore (such as using SUPSEMEVENT),
246	* notified by the kernel interrupt handler, and then will call
247	* upper port pfnInterruptRequest() based on data provided by the driver.
248	* This apporach is taken, as calling VBox code from an asyncronous R0
249	* interrupt handler when VMM may not be even running doesn't look
250	* like a good idea.
251	*
252	* @returns status code
253	* @param pInterface Pointer to this interface structure.
254	* @param uGuestIrq Guest IRQ to be passed to pfnInterruptRequest().
255	*
256	* @thread Any thread, pfnInterruptRequest() will be usually invoked on a dedicated thread.
257	*/
258	DECLR3CALLBACKMEMBER(int, pfnEnableInterruptNotifications, (PPDMIPCIRAWUP pInterface, uint8_t uGuestIrq));
259
260	/**
261	* Request to disable interrupt notifications.
262	*
263	* @returns status code
264	* @param pInterface Pointer to this interface structure.
265	*
266	* @thread Any thread.
267	*/
268	DECLR3CALLBACKMEMBER(int, pfnDisableInterruptNotifications, (PPDMIPCIRAWUP pInterface));
269
270	/** @name Notification APIs.
271	* @{
272	*/
273
274	/**
275	* Notify driver when raw PCI device construction starts.
276	*
277	* Have to be the first operation as initializes internal state and opens host
278	* device driver.
279	*
280	* @returns status code
281	* @param pInterface Pointer to this interface structure.
282	* @param uHostPciAddress Host PCI address of device attached.
283	* @param uGuestPciAddress Guest PCI address of device attached.
284	* @param pszDeviceName Human readable device name.
285	* @param fDeviceFlags Flags for the host device.
286	* @param pfFlags Flags for virtual device, from the upper driver.
287	*
288	* @thread Any thread.
289	*/
290	DECLR3CALLBACKMEMBER(int, pfnPciDeviceConstructStart, (PPDMIPCIRAWUP pInterface,
291	uint32_t uHostPciAddress,
292	uint32_t uGuestPciAddress,
293	const char *pszDeviceName,
294	uint32_t fDeviceFlags,
295	uint32_t *pfFlags));
296
297	/**
298	* Notify driver when raw PCI device construction completes, so that it may
299	* perform further actions depending on success or failure of this operation.
300	* Standard action is to raise global IHostPciDevicePlugEvent.
301	*
302	* @param pInterface Pointer to this interface structure.
303	* @param rc Result code of the operation.
304	*
305	* @thread Any thread.
306	*/
307	DECLR3CALLBACKMEMBER(void, pfnPciDeviceConstructComplete, (PPDMIPCIRAWUP pInterface, int rc));
308
309	/**
310	* Notify driver on finalization of raw PCI device.
311	*
312	* @param pInterface Pointer to this interface structure.
313	* @param fFlags Flags.
314	*
315	* @thread Any thread.
316	*/
317	DECLR3CALLBACKMEMBER(int, pfnPciDeviceDestruct, (PPDMIPCIRAWUP pInterface, uint32_t fFlags));
318
319	/**
320	* Notify driver on guest power state change.
321	*
322	* @param pInterface Pointer to this interface structure.
323	* @param enmState New power state.
324	* @param pu64Param State-specific in/out parameter. For now only used during power-on to provide VM caps.
325	*
326	* @thread Any thread.
327	*/
328	DECLR3CALLBACKMEMBER(int, pfnPciDevicePowerStateChange, (PPDMIPCIRAWUP pInterface,
329	PCIRAWPOWERSTATE enmState,
330	uint64_t *pu64Param));
331
332	/**
333	* Notify driver about runtime error.
334	*
335	* @param pInterface Pointer to this interface structure.
336	* @param fFatal If error is fatal.
337	* @param pszErrorId Error ID.
338	* @param pszMessage Error message.
339	*
340	* @thread Any thread.
341	*/
342	DECLR3CALLBACKMEMBER(int, pfnReportRuntimeError, (PPDMIPCIRAWUP pInterface,
343	bool fFatal,
344	const char *pszErrorId,
345	const char *pszMessage));
346	/** @} */
347	} PDMIPCIRAWUP;
348
349	/**
350	* Init R0 PCI module.
351	*/
352	PCIRAWR0DECL(int) PciRawR0Init(void);
353	/**
354	* Process request (in R0).
355	*/
356	PCIRAWR0DECL(int) PciRawR0ProcessReq(PGVM pGVM, PSUPDRVSESSION pSession, PPCIRAWSENDREQ pReq);
357	/**
358	* Terminate R0 PCI module.
359	*/
360	PCIRAWR0DECL(void) PciRawR0Term(void);
361
362	/**
363	* Per-VM R0 module init.
364	*/
365	PCIRAWR0DECL(int) PciRawR0InitVM(PGVM pGVM);
366
367	/**
368	* Per-VM R0 module termination routine.
369	*/
370	PCIRAWR0DECL(void) PciRawR0TermVM(PGVM pGVM);
371
372	/**
373	* Flags returned by pfnPciDeviceConstructStart(), to notify device
374	* how it shall handle device IO traffic.
375	*/
376	typedef enum PCIRAWDEVICEFLAGS
377	{
378	/** Intercept port IO (R3 PIO always go to the driver). */
379	PCIRAWRFLAG_CAPTURE_PIO = (1 << 0),
380	/** Intercept MMIO. */
381	PCIRAWRFLAG_CAPTURE_MMIO = (1 << 1),
382	/** Allow bus mastering by physical device (requires IOMMU). */
383	PCIRAWRFLAG_ALLOW_BM = (1 << 2),
384	/** Allow R3 MMIO mapping. */
385	PCIRAWRFLAG_ALLOW_R3MAP = (1 << 3),
386
387	/** The usual 32-bit type blow up. */
388	PCIRAWRFLAG_32BIT_HACK = 0x7fffffff
389	} PCIRAWDEVICEFLAGS;
390
391	#define PDMIPCIRAWUP_IID "06daa17f-097b-4ebe-a626-15f467b1de12"
392	#define PDMIPCIRAW_IID "68c6e4c4-4223-47e0-9134-e3c297992543"
393
394	/** @} */
395
396	RT_C_DECLS_END
397
398	#endif /* !VBOX_INCLUDED_vmm_pdmpci_h */

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

source: vbox/trunk/include/VBox/vmm/pdmpci.h@ 81366

Download in other formats: