VirtualBox

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

Last change on this file since 78235 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.9 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
35RT_C_DECLS_BEGIN
36
37/** @defgroup grp_pdm_pciraw The raw PCI Devices API
38 * @ingroup grp_pdm
39 * @{
40 */
41
42typedef struct PDMIPCIRAW *PPDMIPCIRAW;
43typedef 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
60typedef struct PDMIPCIRAWUP *PPDMIPCIRAWUP;
61typedef 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
159 DECLR3CALLBACKMEMBER(int, pfnPioRead, (PPDMIPCIRAWUP pInterface,
160 RTIOPORT uPort,
161 uint32_t *puValue,
162 unsigned cb));
163
164
165 /**
166 * Request MMIO write. This callback is only called if driver wants to receive MMIO via
167 * pu32Flags argument of pfnPciDeviceConstructStart().
168 *
169 * @returns status code
170 * @param pInterface Pointer to this interface structure.
171 * @param Address Guest physical address.
172 * @todo Why is this documented as guest physical
173 * address and given a host ring-0 address type?
174 * @param pvValue Address of value to write.
175 * @param cb Access width.
176 *
177 * @thread EMT thread.
178 */
179 DECLR3CALLBACKMEMBER(int, pfnMmioWrite, (PPDMIPCIRAWUP pInterface,
180 RTR0PTR Address,
181 void const *pvValue,
182 unsigned cb));
183
184 /**
185 * Request MMIO read.
186 *
187 * @returns status code
188 * @param pInterface Pointer to this interface structure.
189 * @param Address Guest physical address.
190 * @todo Why is this documented as guest physical
191 * address and given a host ring-0 address type?
192 * @param pvValue Place to store read value.
193 * @param cb Access width.
194 *
195 * @thread EMT thread.
196 */
197
198 DECLR3CALLBACKMEMBER(int, pfnMmioRead, (PPDMIPCIRAWUP pInterface,
199 RTR0PTR Address,
200 void *pvValue,
201 unsigned cb));
202
203 /**
204 * Host PCI config space accessors.
205 */
206 /**
207 * Request driver to write value to host device's PCI config space.
208 * Host specific way (PIO or MCFG) is used to perform actual operation.
209 *
210 * @returns status code
211 * @param pInterface Pointer to this interface structure.
212 * @param offCfgSpace Offset in PCI config space.
213 * @param pvValue Value to write.
214 * @param cb Access width.
215 *
216 * @thread EMT thread.
217 */
218 DECLR3CALLBACKMEMBER(int, pfnPciCfgWrite, (PPDMIPCIRAWUP pInterface,
219 uint32_t offCfgSpace,
220 void *pvValue,
221 unsigned cb));
222 /**
223 * Request driver to read value from host device's PCI config space.
224 * Host specific way (PIO or MCFG) is used to perform actual operation.
225 *
226 * @returns status code
227 * @param pInterface Pointer to this interface structure.
228 * @param offCfgSpace Offset in PCI config space.
229 * @param pvValue Where to store read value.
230 * @param cb Access width.
231 *
232 * @thread EMT thread.
233 */
234 DECLR3CALLBACKMEMBER(int, pfnPciCfgRead, (PPDMIPCIRAWUP pInterface,
235 uint32_t offCfgSpace,
236 void *pvValue,
237 unsigned cb));
238
239 /**
240 * Request to enable interrupt notifications. Please note that this is purely
241 * R3 interface, so it's up to implementor to perform necessary machinery
242 * for communications with host OS kernel driver. Typical implementation will start
243 * userland thread waiting on shared semaphore (such as using SUPSEMEVENT),
244 * notified by the kernel interrupt handler, and then will call
245 * upper port pfnInterruptRequest() based on data provided by the driver.
246 * This apporach is taken, as calling VBox code from an asyncronous R0
247 * interrupt handler when VMM may not be even running doesn't look
248 * like a good idea.
249 *
250 * @returns status code
251 * @param pInterface Pointer to this interface structure.
252 * @param uGuestIrq Guest IRQ to be passed to pfnInterruptRequest().
253 *
254 * @thread Any thread, pfnInterruptRequest() will be usually invoked on a dedicated thread.
255 */
256 DECLR3CALLBACKMEMBER(int, pfnEnableInterruptNotifications, (PPDMIPCIRAWUP pInterface, uint8_t uGuestIrq));
257
258 /**
259 * Request to disable interrupt notifications.
260 *
261 * @returns status code
262 * @param pInterface Pointer to this interface structure.
263 *
264 * @thread Any thread.
265 */
266 DECLR3CALLBACKMEMBER(int, pfnDisableInterruptNotifications, (PPDMIPCIRAWUP pInterface));
267
268 /** @name Notification APIs.
269 * @{
270 */
271
272 /**
273 * Notify driver when raw PCI device construction starts.
274 *
275 * Have to be the first operation as initializes internal state and opens host
276 * device driver.
277 *
278 * @returns status code
279 * @param pInterface Pointer to this interface structure.
280 * @param uHostPciAddress Host PCI address of device attached.
281 * @param uGuestPciAddress Guest PCI address of device attached.
282 * @param pszDeviceName Human readable device name.
283 * @param fDeviceFlags Flags for the host device.
284 * @param pfFlags Flags for virtual device, from the upper driver.
285 *
286 * @thread Any thread.
287 */
288 DECLR3CALLBACKMEMBER(int, pfnPciDeviceConstructStart, (PPDMIPCIRAWUP pInterface,
289 uint32_t uHostPciAddress,
290 uint32_t uGuestPciAddress,
291 const char *pszDeviceName,
292 uint32_t fDeviceFlags,
293 uint32_t *pfFlags));
294
295 /**
296 * Notify driver when raw PCI device construction completes, so that it may
297 * perform further actions depending on success or failure of this operation.
298 * Standard action is to raise global IHostPciDevicePlugEvent.
299 *
300 * @param pInterface Pointer to this interface structure.
301 * @param rc Result code of the operation.
302 *
303 * @thread Any thread.
304 */
305 DECLR3CALLBACKMEMBER(void, pfnPciDeviceConstructComplete, (PPDMIPCIRAWUP pInterface, int rc));
306
307 /**
308 * Notify driver on finalization of raw PCI device.
309 *
310 * @param pInterface Pointer to this interface structure.
311 * @param fFlags Flags.
312 *
313 * @thread Any thread.
314 */
315 DECLR3CALLBACKMEMBER(int, pfnPciDeviceDestruct, (PPDMIPCIRAWUP pInterface, uint32_t fFlags));
316
317 /**
318 * Notify driver on guest power state change.
319 *
320 * @param pInterface Pointer to this interface structure.
321 * @param enmState New power state.
322 * @param pu64Param State-specific in/out parameter. For now only used during power-on to provide VM caps.
323 *
324 * @thread Any thread.
325 */
326 DECLR3CALLBACKMEMBER(int, pfnPciDevicePowerStateChange, (PPDMIPCIRAWUP pInterface,
327 PCIRAWPOWERSTATE enmState,
328 uint64_t *pu64Param));
329
330 /**
331 * Notify driver about runtime error.
332 *
333 * @param pInterface Pointer to this interface structure.
334 * @param fFatal If error is fatal.
335 * @param pszErrorId Error ID.
336 * @param pszMessage Error message.
337 *
338 * @thread Any thread.
339 */
340 DECLR3CALLBACKMEMBER(int, pfnReportRuntimeError, (PPDMIPCIRAWUP pInterface,
341 bool fFatal,
342 const char *pszErrorId,
343 const char *pszMessage));
344 /** @} */
345} PDMIPCIRAWUP;
346
347/**
348 * Init R0 PCI module.
349 */
350PCIRAWR0DECL(int) PciRawR0Init(void);
351/**
352 * Process request (in R0).
353 */
354PCIRAWR0DECL(int) PciRawR0ProcessReq(PGVM pGVM, PVM pVM, PSUPDRVSESSION pSession, PPCIRAWSENDREQ pReq);
355/**
356 * Terminate R0 PCI module.
357 */
358PCIRAWR0DECL(void) PciRawR0Term(void);
359
360/**
361 * Per-VM R0 module init.
362 */
363PCIRAWR0DECL(int) PciRawR0InitVM(PGVM pGVM, PVM pVM);
364
365/**
366 * Per-VM R0 module termination routine.
367 */
368PCIRAWR0DECL(void) PciRawR0TermVM(PGVM pGVM, PVM pVM);
369
370/**
371 * Flags returned by pfnPciDeviceConstructStart(), to notify device
372 * how it shall handle device IO traffic.
373 */
374typedef enum PCIRAWDEVICEFLAGS
375{
376 /** Intercept port IO (R3 PIO always go to the driver). */
377 PCIRAWRFLAG_CAPTURE_PIO = (1 << 0),
378 /** Intercept MMIO. */
379 PCIRAWRFLAG_CAPTURE_MMIO = (1 << 1),
380 /** Allow bus mastering by physical device (requires IOMMU). */
381 PCIRAWRFLAG_ALLOW_BM = (1 << 2),
382 /** Allow R3 MMIO mapping. */
383 PCIRAWRFLAG_ALLOW_R3MAP = (1 << 3),
384
385 /** The usual 32-bit type blow up. */
386 PCIRAWRFLAG_32BIT_HACK = 0x7fffffff
387} PCIRAWDEVICEFLAGS;
388
389#define PDMIPCIRAWUP_IID "06daa17f-097b-4ebe-a626-15f467b1de12"
390#define PDMIPCIRAW_IID "68c6e4c4-4223-47e0-9134-e3c297992543"
391
392/** @} */
393
394RT_C_DECLS_END
395
396#endif /* !VBOX_INCLUDED_vmm_pdmpci_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