VirtualBox

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

Last change on this file since 69028 was 65117, checked in by vboxsync, 8 years ago

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