VirtualBox

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

Last change on this file since 92989 was 90833, checked in by vboxsync, 3 years ago

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