VirtualBox

source: vbox/trunk/include/VBox/rawpci.h

Last change on this file was 99739, checked in by vboxsync, 12 months ago

*: doxygen corrections (mostly about removing @returns from functions returning void).
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 19.2 KB
Line 
1/** @file
2 * Raw PCI Devices (aka PCI pass-through). (VMM)
3 */
4
5/*
6 * Copyright (C) 2010-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef VBOX_INCLUDED_rawpci_h
37#define VBOX_INCLUDED_rawpci_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <VBox/types.h>
43#include <VBox/sup.h>
44
45RT_C_DECLS_BEGIN
46
47/**
48 * Handle for the raw PCI device.
49 */
50typedef uint32_t PCIRAWDEVHANDLE;
51
52/**
53 * Handle for the ISR.
54 */
55typedef uint32_t PCIRAWISRHANDLE;
56
57/**
58 * Physical memory action enumeration.
59 */
60typedef enum PCIRAWMEMINFOACTION
61{
62 /** Pages mapped. */
63 PCIRAW_MEMINFO_MAP,
64 /** Pages unmapped. */
65 PCIRAW_MEMINFO_UNMAP,
66 /** The usual 32-bit type blow up. */
67 PCIRAW_MEMINFO_32BIT_HACK = 0x7fffffff
68} PCIRAWMEMINFOACTION;
69
70/**
71 * Per-VM capability flag bits.
72 */
73typedef enum PCIRAWVMFLAGS
74{
75 /** If we can use IOMMU in this VM. */
76 PCIRAW_VMFLAGS_HAS_IOMMU = (1 << 0),
77 PCIRAW_VMFLAGS_32BIT_HACK = 0x7fffffff
78} PCIRAWVMFLAGS;
79
80/* Forward declaration. */
81struct RAWPCIPERVM;
82
83/**
84 * Callback to notify raw PCI subsystem about mapping/unmapping of
85 * host pages to the guest. Typical usecase is to register physical
86 * RAM pages with IOMMU, so that it could allow DMA for PCI devices
87 * directly from the guest RAM.
88 * Region shall be one or more contigous (both host and guest) pages
89 * of physical memory.
90 *
91 * @returns VBox status code.
92 *
93 * @param pVmData The per VM data.
94 * @param HCPhysStart Physical address of region start on the host.
95 * @param GCPhysStart Physical address of region start on the guest.
96 * @param cbMem Region size in bytes.
97 * @param enmAction Action performed (i.e. if page was mapped
98 * or unmapped).
99 */
100typedef DECLCALLBACKTYPE(int, FNRAWPCICONTIGPHYSMEMINFO,(struct RAWPCIPERVM *pVmData, RTHCPHYS HCPhysStart,
101 RTGCPHYS GCPhysStart, uint64_t cbMem, PCIRAWMEMINFOACTION enmAction));
102typedef FNRAWPCICONTIGPHYSMEMINFO *PFNRAWPCICONTIGPHYSMEMINFO;
103
104/** Data being part of the VM structure. */
105typedef struct RAWPCIPERVM
106{
107 /** Shall only be interpreted by the host PCI driver. */
108 RTR0PTR pDriverData;
109 /** Callback called when mapping of host pages to the guest changes. */
110 PFNRAWPCICONTIGPHYSMEMINFO pfnContigMemInfo;
111 /** Flags describing VM capabilities (such as IOMMU presence). */
112 uint32_t fVmCaps;
113} RAWPCIPERVM;
114typedef RAWPCIPERVM *PRAWPCIPERVM;
115
116/** Parameters buffer for PCIRAWR0_DO_OPEN_DEVICE call */
117typedef struct
118{
119 /* in */
120 uint32_t PciAddress;
121 uint32_t fFlags;
122 /* out */
123 PCIRAWDEVHANDLE Device;
124 uint32_t fDevFlags;
125} PCIRAWREQOPENDEVICE;
126
127/** Parameters buffer for PCIRAWR0_DO_CLOSE_DEVICE call */
128typedef struct
129{
130 /* in */
131 uint32_t fFlags;
132} PCIRAWREQCLOSEDEVICE;
133
134/** Parameters buffer for PCIRAWR0_DO_GET_REGION_INFO call */
135typedef struct
136{
137 /* in */
138 int32_t iRegion;
139 /* out */
140 RTGCPHYS RegionStart;
141 uint64_t u64RegionSize;
142 bool fPresent;
143 uint32_t fFlags;
144} PCIRAWREQGETREGIONINFO;
145
146/** Parameters buffer for PCIRAWR0_DO_MAP_REGION call. */
147typedef struct
148{
149 /* in */
150 RTGCPHYS StartAddress;
151 uint64_t iRegionSize;
152 int32_t iRegion;
153 uint32_t fFlags;
154 /* out */
155 RTR3PTR pvAddressR3;
156 RTR0PTR pvAddressR0;
157} PCIRAWREQMAPREGION;
158
159/** Parameters buffer for PCIRAWR0_DO_UNMAP_REGION call. */
160typedef struct
161{
162 /* in */
163 RTGCPHYS StartAddress;
164 uint64_t iRegionSize;
165 RTR3PTR pvAddressR3;
166 RTR0PTR pvAddressR0;
167 int32_t iRegion;
168} PCIRAWREQUNMAPREGION;
169
170/** Parameters buffer for PCIRAWR0_DO_PIO_WRITE call. */
171typedef struct
172{
173 /* in */
174 uint16_t iPort;
175 uint16_t cb;
176 uint32_t iValue;
177} PCIRAWREQPIOWRITE;
178
179/** Parameters buffer for PCIRAWR0_DO_PIO_READ call. */
180typedef struct
181{
182 /* in */
183 uint16_t iPort;
184 uint16_t cb;
185 /* out */
186 uint32_t iValue;
187} PCIRAWREQPIOREAD;
188
189/** Memory operand. */
190typedef struct
191{
192 union
193 {
194 uint8_t u8;
195 uint16_t u16;
196 uint32_t u32;
197 uint64_t u64;
198 } u;
199 uint8_t cb;
200} PCIRAWMEMLOC;
201
202/** Parameters buffer for PCIRAWR0_DO_MMIO_WRITE call. */
203typedef struct
204{
205 /* in */
206 RTR0PTR Address;
207 PCIRAWMEMLOC Value;
208} PCIRAWREQMMIOWRITE;
209
210/** Parameters buffer for PCIRAWR0_DO_MMIO_READ call. */
211typedef struct
212{
213 /* in */
214 RTR0PTR Address;
215 /* inout (Value.cb is in) */
216 PCIRAWMEMLOC Value;
217} PCIRAWREQMMIOREAD;
218
219/* Parameters buffer for PCIRAWR0_DO_PCICFG_WRITE call. */
220typedef struct
221{
222 /* in */
223 uint32_t iOffset;
224 PCIRAWMEMLOC Value;
225} PCIRAWREQPCICFGWRITE;
226
227/** Parameters buffer for PCIRAWR0_DO_PCICFG_READ call. */
228typedef struct
229{
230 /* in */
231 uint32_t iOffset;
232 /* inout (Value.cb is in) */
233 PCIRAWMEMLOC Value;
234} PCIRAWREQPCICFGREAD;
235
236/** Parameters buffer for PCIRAWR0_DO_GET_IRQ call. */
237typedef struct PCIRAWREQGETIRQ
238{
239 /* in */
240 int64_t iTimeout;
241 /* out */
242 int32_t iIrq;
243} PCIRAWREQGETIRQ;
244
245/** Parameters buffer for PCIRAWR0_DO_POWER_STATE_CHANGE call. */
246typedef struct PCIRAWREQPOWERSTATECHANGE
247{
248 /* in */
249 uint32_t iState;
250 /* in/out */
251 uint64_t u64Param;
252} PCIRAWREQPOWERSTATECHANGE;
253
254/**
255 * Request buffer use for communication with the driver.
256 */
257typedef struct PCIRAWSENDREQ
258{
259 /** The request header. */
260 SUPVMMR0REQHDR Hdr;
261 /** Alternative to passing the taking the session from the VM handle.
262 * Either use this member or use the VM handle, don't do both.
263 */
264 PSUPDRVSESSION pSession;
265 /** Request type. */
266 int32_t iRequest;
267 /** Host device request targetted to. */
268 PCIRAWDEVHANDLE TargetDevice;
269 /** Call parameters. */
270 union
271 {
272 PCIRAWREQOPENDEVICE aOpenDevice;
273 PCIRAWREQCLOSEDEVICE aCloseDevice;
274 PCIRAWREQGETREGIONINFO aGetRegionInfo;
275 PCIRAWREQMAPREGION aMapRegion;
276 PCIRAWREQUNMAPREGION aUnmapRegion;
277 PCIRAWREQPIOWRITE aPioWrite;
278 PCIRAWREQPIOREAD aPioRead;
279 PCIRAWREQMMIOWRITE aMmioWrite;
280 PCIRAWREQMMIOREAD aMmioRead;
281 PCIRAWREQPCICFGWRITE aPciCfgWrite;
282 PCIRAWREQPCICFGREAD aPciCfgRead;
283 PCIRAWREQGETIRQ aGetIrq;
284 PCIRAWREQPOWERSTATECHANGE aPowerStateChange;
285 } u;
286} PCIRAWSENDREQ;
287typedef PCIRAWSENDREQ *PPCIRAWSENDREQ;
288
289/**
290 * Operations performed by the driver.
291 */
292typedef enum PCIRAWR0OPERATION
293{
294 /* Open device. */
295 PCIRAWR0_DO_OPEN_DEVICE,
296 /* Close device. */
297 PCIRAWR0_DO_CLOSE_DEVICE,
298 /* Get PCI region info. */
299 PCIRAWR0_DO_GET_REGION_INFO,
300 /* Map PCI region into VM address space. */
301 PCIRAWR0_DO_MAP_REGION,
302 /* Unmap PCI region from VM address space. */
303 PCIRAWR0_DO_UNMAP_REGION,
304 /* Perform PIO write. */
305 PCIRAWR0_DO_PIO_WRITE,
306 /* Perform PIO read. */
307 PCIRAWR0_DO_PIO_READ,
308 /* Perform MMIO write. */
309 PCIRAWR0_DO_MMIO_WRITE,
310 /* Perform MMIO read. */
311 PCIRAWR0_DO_MMIO_READ,
312 /* Perform PCI config write. */
313 PCIRAWR0_DO_PCICFG_WRITE,
314 /* Perform PCI config read. */
315 PCIRAWR0_DO_PCICFG_READ,
316 /* Get next IRQ for the device. */
317 PCIRAWR0_DO_GET_IRQ,
318 /* Enable getting IRQs for the device. */
319 PCIRAWR0_DO_ENABLE_IRQ,
320 /* Disable getting IRQs for the device. */
321 PCIRAWR0_DO_DISABLE_IRQ,
322 /* Notify driver about guest power state change. */
323 PCIRAWR0_DO_POWER_STATE_CHANGE,
324 /** The usual 32-bit type blow up. */
325 PCIRAWR0_DO_32BIT_HACK = 0x7fffffff
326} PCIRAWR0OPERATION;
327
328/**
329 * Power state enumeration.
330 */
331typedef enum PCIRAWPOWERSTATE
332{
333 /* Power on. */
334 PCIRAW_POWER_ON,
335 /* Power off. */
336 PCIRAW_POWER_OFF,
337 /* Suspend. */
338 PCIRAW_POWER_SUSPEND,
339 /* Resume. */
340 PCIRAW_POWER_RESUME,
341 /* Reset. */
342 PCIRAW_POWER_RESET,
343 /** The usual 32-bit type blow up. */
344 PCIRAW_POWER_32BIT_HACK = 0x7fffffff
345} PCIRAWPOWERSTATE;
346
347
348/** Forward declarations. */
349typedef struct RAWPCIFACTORY *PRAWPCIFACTORY;
350typedef struct RAWPCIDEVPORT *PRAWPCIDEVPORT;
351
352/**
353 * Interrupt service routine callback.
354 *
355 * @returns if interrupt was processed.
356 *
357 * @param pvContext Opaque user data passed to the handler.
358 * @param iIrq Interrupt number.
359 */
360typedef DECLCALLBACKTYPE(bool, FNRAWPCIISR,(void *pvContext, int32_t iIrq));
361typedef FNRAWPCIISR *PFNRAWPCIISR;
362
363/**
364 * This is the port on the device interface, i.e. the driver side which the
365 * host device is connected to.
366 *
367 * This is only used for the in-kernel PCI device connections.
368 */
369typedef struct RAWPCIDEVPORT
370{
371 /** Structure version number. (RAWPCIDEVPORT_VERSION) */
372 uint32_t u32Version;
373
374 /**
375 * Init device.
376 *
377 * @param pPort Pointer to this structure.
378 * @param fFlags Initialization flags.
379 */
380 DECLR0CALLBACKMEMBER(int, pfnInit,(PRAWPCIDEVPORT pPort,
381 uint32_t fFlags));
382
383
384 /**
385 * Deinit device.
386 *
387 * @param pPort Pointer to this structure.
388 * @param fFlags Initialization flags.
389 */
390 DECLR0CALLBACKMEMBER(int, pfnDeinit,(PRAWPCIDEVPORT pPort,
391 uint32_t fFlags));
392
393
394 /**
395 * Destroy device.
396 *
397 * @param pPort Pointer to this structure.
398 */
399 DECLR0CALLBACKMEMBER(int, pfnDestroy,(PRAWPCIDEVPORT pPort));
400
401 /**
402 * Get PCI region info.
403 *
404 * @param pPort Pointer to this structure.
405 * @param iRegion Region number.
406 * @param pRegionStart Where to start the region address.
407 * @param pu64RegionSize Where to store the region size.
408 * @param pfPresent Where to store if the region is present.
409 * @param pfFlags Where to store the flags.
410 */
411 DECLR0CALLBACKMEMBER(int, pfnGetRegionInfo,(PRAWPCIDEVPORT pPort,
412 int32_t iRegion,
413 RTHCPHYS *pRegionStart,
414 uint64_t *pu64RegionSize,
415 bool *pfPresent,
416 uint32_t *pfFlags));
417
418
419 /**
420 * Map PCI region.
421 *
422 * @param pPort Pointer to this structure.
423 * @param iRegion Region number.
424 * @param RegionStart Region start.
425 * @param u64RegionSize Region size.
426 * @param fFlags Flags.
427 * @param pRegionBaseR0 Where to store the R0 address.
428 */
429 DECLR0CALLBACKMEMBER(int, pfnMapRegion,(PRAWPCIDEVPORT pPort,
430 int32_t iRegion,
431 RTHCPHYS RegionStart,
432 uint64_t u64RegionSize,
433 int32_t fFlags,
434 RTR0PTR *pRegionBaseR0));
435
436 /**
437 * Unmap PCI region.
438 *
439 * @param pPort Pointer to this structure.
440 * @param iRegion Region number.
441 * @param RegionStart Region start.
442 * @param u64RegionSize Region size.
443 * @param RegionBase Base address.
444 */
445 DECLR0CALLBACKMEMBER(int, pfnUnmapRegion,(PRAWPCIDEVPORT pPort,
446 int32_t iRegion,
447 RTHCPHYS RegionStart,
448 uint64_t u64RegionSize,
449 RTR0PTR RegionBase));
450
451 /**
452 * Read device PCI register.
453 *
454 * @param pPort Pointer to this structure.
455 * @param Register PCI register.
456 * @param pValue Read value (with desired read width).
457 */
458 DECLR0CALLBACKMEMBER(int, pfnPciCfgRead,(PRAWPCIDEVPORT pPort,
459 uint32_t Register,
460 PCIRAWMEMLOC *pValue));
461
462
463 /**
464 * Write device PCI register.
465 *
466 * @param pPort Pointer to this structure.
467 * @param Register PCI register.
468 * @param pValue Write value (with desired write width).
469 */
470 DECLR0CALLBACKMEMBER(int, pfnPciCfgWrite,(PRAWPCIDEVPORT pPort,
471 uint32_t Register,
472 PCIRAWMEMLOC *pValue));
473
474 /**
475 * Request to register interrupt handler.
476 *
477 * @param pPort Pointer to this structure.
478 * @param pfnHandler Pointer to the handler.
479 * @param pIrqContext Context passed to the handler.
480 * @param phIsr Handle for the ISR, .
481 */
482 DECLR0CALLBACKMEMBER(int, pfnRegisterIrqHandler,(PRAWPCIDEVPORT pPort,
483 PFNRAWPCIISR pfnHandler,
484 void* pIrqContext,
485 PCIRAWISRHANDLE *phIsr));
486
487 /**
488 * Request to unregister interrupt handler.
489 *
490 * @param pPort Pointer to this structure.
491 * @param hIsr Handle of ISR to unregister (retured by earlier pfnRegisterIrqHandler).
492 */
493 DECLR0CALLBACKMEMBER(int, pfnUnregisterIrqHandler,(PRAWPCIDEVPORT pPort,
494 PCIRAWISRHANDLE hIsr));
495
496 /**
497 * Power state change notification.
498 *
499 * @param pPort Pointer to this structure.
500 * @param aState New power state.
501 * @param pu64Param State-specific in/out parameter.
502 */
503 DECLR0CALLBACKMEMBER(int, pfnPowerStateChange,(PRAWPCIDEVPORT pPort,
504 PCIRAWPOWERSTATE aState,
505 uint64_t *pu64Param));
506
507 /** Structure version number. (RAWPCIDEVPORT_VERSION) */
508 uint32_t u32VersionEnd;
509} RAWPCIDEVPORT;
510/** Version number for the RAWPCIDEVPORT::u32Version and RAWPCIIFPORT::u32VersionEnd fields. */
511#define RAWPCIDEVPORT_VERSION UINT32_C(0xAFBDCC02)
512
513/**
514 * The component factory interface for create a raw PCI interfaces.
515 */
516typedef struct RAWPCIFACTORY
517{
518 /**
519 * Release this factory.
520 *
521 * SUPR0ComponentQueryFactory (SUPDRVFACTORY::pfnQueryFactoryInterface to be precise)
522 * will retain a reference to the factory and the caller has to call this method to
523 * release it once the pfnCreateAndConnect call(s) has been done.
524 *
525 * @param pFactory Pointer to this structure.
526 */
527 DECLR0CALLBACKMEMBER(void, pfnRelease,(PRAWPCIFACTORY pFactory));
528
529 /**
530 * Create an instance for the specfied host PCI card and connects it
531 * to the driver.
532 *
533 *
534 * @returns VBox status code.
535 *
536 * @param pFactory Pointer to this structure.
537 * @param u32HostAddress Address of PCI device on the host.
538 * @param fFlags Creation flags.
539 * @param pVmCtx Context of VM where device is created.
540 * @param ppDevPort Where to store the pointer to the device port
541 * on success.
542 * @param pfDevFlags Where to store the device flags.
543 *
544 */
545 DECLR0CALLBACKMEMBER(int, pfnCreateAndConnect,(PRAWPCIFACTORY pFactory,
546 uint32_t u32HostAddress,
547 uint32_t fFlags,
548 PRAWPCIPERVM pVmCtx,
549 PRAWPCIDEVPORT *ppDevPort,
550 uint32_t *pfDevFlags));
551
552
553 /**
554 * Initialize per-VM data related to PCI passthrough.
555 *
556 * @returns VBox status code.
557 *
558 * @param pFactory Pointer to this structure.
559 * @param pVM The cross context VM structure.
560 * @param pVmData Pointer to PCI data.
561 */
562 DECLR0CALLBACKMEMBER(int, pfnInitVm,(PRAWPCIFACTORY pFactory,
563 PVM pVM,
564 PRAWPCIPERVM pVmData));
565
566 /**
567 * Deinitialize per-VM data related to PCI passthrough.
568 *
569 * @param pFactory Pointer to this structure.
570 * @param pVM The cross context VM structure.
571 * @param pVmData Pointer to PCI data.
572 */
573 DECLR0CALLBACKMEMBER(void, pfnDeinitVm,(PRAWPCIFACTORY pFactory,
574 PVM pVM,
575 PRAWPCIPERVM pVmData));
576} RAWPCIFACTORY;
577
578#define RAWPCIFACTORY_UUID_STR "ea089839-4171-476f-adfb-9e7ab1cbd0fb"
579
580/**
581 * Flags passed to pfnPciDeviceConstructStart(), to notify driver
582 * about options to be used to open device.
583 */
584typedef enum PCIRAWDRIVERFLAGS
585{
586 /** If runtime shall try to detach host driver. */
587 PCIRAWDRIVERRFLAG_DETACH_HOST_DRIVER = (1 << 0),
588 /** The usual 32-bit type blow up. */
589 PCIRAWDRIVERRFLAG_32BIT_HACK = 0x7fffffff
590} PCIRAWDRIVERFLAGS;
591
592/**
593 * Flags used to describe PCI region, matches to PCIADDRESSSPACE
594 * in pci.h.
595 */
596typedef enum PCIRAWADDRESSSPACE
597{
598 /** Memory. */
599 PCIRAW_ADDRESS_SPACE_MEM = 0x00,
600 /** I/O space. */
601 PCIRAW_ADDRESS_SPACE_IO = 0x01,
602 /** 32-bit BAR. */
603 PCIRAW_ADDRESS_SPACE_BAR32 = 0x00,
604 /** 64-bit BAR. */
605 PCIRAW_ADDRESS_SPACE_BAR64 = 0x04,
606 /** Prefetch memory. */
607 PCIRAW_ADDRESS_SPACE_MEM_PREFETCH = 0x08,
608 /** The usual 32-bit type blow up. */
609 PCIRAW_ADDRESS_SPACE_32BIT_HACK = 0x7fffffff
610} PCIRAWADDRESSSPACE;
611
612RT_C_DECLS_END
613
614/* #define VBOX_WITH_SHARED_PCI_INTERRUPTS */
615
616#endif /* !VBOX_INCLUDED_rawpci_h */
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use