VirtualBox

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

Last change on this file since 58803 was 58124, checked in by vboxsync, 9 years ago

include/VBox//*.h: pVM and pVCpu parameter description adjustments.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 18.1 KB
Line 
1/** @file
2 * Raw PCI Devices (aka PCI pass-through). (VMM)
3 */
4
5/*
6 * Copyright (C) 2010-2015 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 */
393 DECLR0CALLBACKMEMBER(int, pfnGetRegionInfo,(PRAWPCIDEVPORT pPort,
394 int32_t iRegion,
395 RTHCPHYS *pRegionStart,
396 uint64_t *pu64RegionSize,
397 bool *pfPresent,
398 uint32_t *pfFlags));
399
400
401 /**
402 * Map PCI region.
403 *
404 * @param pPort Pointer to this structure.
405 */
406 DECLR0CALLBACKMEMBER(int, pfnMapRegion,(PRAWPCIDEVPORT pPort,
407 int32_t iRegion,
408 RTHCPHYS RegionStart,
409 uint64_t u64RegionSize,
410 int32_t fFlags,
411 RTR0PTR *pRegionBaseR0));
412
413 /**
414 * Unmap PCI region.
415 *
416 * @param pPort Pointer to this structure.
417 */
418 DECLR0CALLBACKMEMBER(int, pfnUnmapRegion,(PRAWPCIDEVPORT pPort,
419 int32_t iRegion,
420 RTHCPHYS RegionStart,
421 uint64_t u64RegionSize,
422 RTR0PTR RegionBase));
423
424 /**
425 * Read device PCI register.
426 *
427 * @param pPort Pointer to this structure.
428 * @param Register PCI register.
429 * @param pValue Read value (with desired read width).
430 */
431 DECLR0CALLBACKMEMBER(int, pfnPciCfgRead,(PRAWPCIDEVPORT pPort,
432 uint32_t Register,
433 PCIRAWMEMLOC *pValue));
434
435
436 /**
437 * Write device PCI register.
438 *
439 * @param pPort Pointer to this structure.
440 * @param Register PCI register.
441 * @param pValue Write value (with desired write width).
442 */
443 DECLR0CALLBACKMEMBER(int, pfnPciCfgWrite,(PRAWPCIDEVPORT pPort,
444 uint32_t Register,
445 PCIRAWMEMLOC *pValue));
446
447 /**
448 * Request to register interrupt handler.
449 *
450 * @param pPort Pointer to this structure.
451 * @param pfnHandler Pointer to the handler.
452 * @param pIrqContext Context passed to the handler.
453 * @param phIsr Handle for the ISR, .
454 */
455 DECLR0CALLBACKMEMBER(int, pfnRegisterIrqHandler,(PRAWPCIDEVPORT pPort,
456 PFNRAWPCIISR pfnHandler,
457 void* pIrqContext,
458 PCIRAWISRHANDLE *phIsr));
459
460 /**
461 * Request to unregister interrupt handler.
462 *
463 * @param pPort Pointer to this structure.
464 * @param hIsr Handle of ISR to unregister (retured by earlier pfnRegisterIrqHandler).
465 */
466 DECLR0CALLBACKMEMBER(int, pfnUnregisterIrqHandler,(PRAWPCIDEVPORT pPort,
467 PCIRAWISRHANDLE hIsr));
468
469 /**
470 * Power state change notification.
471 *
472 * @param pPort Pointer to this structure.
473 * @param aState New power state.
474 * @param pu64Param State-specific in/out parameter.
475 */
476 DECLR0CALLBACKMEMBER(int, pfnPowerStateChange,(PRAWPCIDEVPORT pPort,
477 PCIRAWPOWERSTATE aState,
478 uint64_t *pu64Param));
479
480 /** Structure version number. (RAWPCIDEVPORT_VERSION) */
481 uint32_t u32VersionEnd;
482} RAWPCIDEVPORT;
483/** Version number for the RAWPCIDEVPORT::u32Version and RAWPCIIFPORT::u32VersionEnd fields. */
484#define RAWPCIDEVPORT_VERSION UINT32_C(0xAFBDCC02)
485
486/**
487 * The component factory interface for create a raw PCI interfaces.
488 */
489typedef struct RAWPCIFACTORY
490{
491 /**
492 * Release this factory.
493 *
494 * SUPR0ComponentQueryFactory (SUPDRVFACTORY::pfnQueryFactoryInterface to be precise)
495 * will retain a reference to the factory and the caller has to call this method to
496 * release it once the pfnCreateAndConnect call(s) has been done.
497 *
498 * @param pIfFactory Pointer to this structure.
499 */
500 DECLR0CALLBACKMEMBER(void, pfnRelease,(PRAWPCIFACTORY pFactory));
501
502 /**
503 * Create an instance for the specfied host PCI card and connects it
504 * to the driver.
505 *
506 *
507 * @returns VBox status code.
508 *
509 * @param pIfFactory Pointer to this structure.
510 * @param u32HostAddress Address of PCI device on the host.
511 * @param fFlags Creation flags.
512 * @param pVmCtx Context of VM where device is created.
513 * @param ppDevPort Where to store the pointer to the device port
514 * on success.
515 *
516 */
517 DECLR0CALLBACKMEMBER(int, pfnCreateAndConnect,(PRAWPCIFACTORY pFactory,
518 uint32_t u32HostAddress,
519 uint32_t fFlags,
520 PRAWPCIPERVM pVmCtx,
521 PRAWPCIDEVPORT *ppDevPort,
522 uint32_t *pfDevFlags));
523
524
525 /**
526 * Initialize per-VM data related to PCI passthrough.
527 *
528 * @returns VBox status code.
529 *
530 * @param pIfFactory Pointer to this structure.
531 * @param pVM The cross context VM structure.
532 * @param pPciData Pointer to PCI data.
533 */
534 DECLR0CALLBACKMEMBER(int, pfnInitVm,(PRAWPCIFACTORY pFactory,
535 PVM pVM,
536 PRAWPCIPERVM pPciData));
537
538 /**
539 * Deinitialize per-VM data related to PCI passthrough.
540 *
541 * @returns VBox status code.
542 *
543 * @param pIfFactory Pointer to this structure.
544 * @param pVM The cross context VM structure.
545 * @param pPciData Pointer to PCI data.
546 */
547 DECLR0CALLBACKMEMBER(void, pfnDeinitVm,(PRAWPCIFACTORY pFactory,
548 PVM pVM,
549 PRAWPCIPERVM pPciData));
550} RAWPCIFACTORY;
551
552#define RAWPCIFACTORY_UUID_STR "ea089839-4171-476f-adfb-9e7ab1cbd0fb"
553
554/**
555 * Flags passed to pfnPciDeviceConstructStart(), to notify driver
556 * about options to be used to open device.
557 */
558typedef enum PCIRAWDRIVERFLAGS
559{
560 /** If runtime shall try to detach host driver. */
561 PCIRAWDRIVERRFLAG_DETACH_HOST_DRIVER = (1 << 0),
562 /** The usual 32-bit type blow up. */
563 PCIRAWDRIVERRFLAG_32BIT_HACK = 0x7fffffff
564} PCIRAWDRIVERFLAGS;
565
566/**
567 * Flags used to describe PCI region, matches to PCIADDRESSSPACE
568 * in pci.h.
569 */
570typedef enum PCIRAWADDRESSSPACE
571{
572 /** Memory. */
573 PCIRAW_ADDRESS_SPACE_MEM = 0x00,
574 /** I/O space. */
575 PCIRAW_ADDRESS_SPACE_IO = 0x01,
576 /** 32-bit BAR. */
577 PCIRAW_ADDRESS_SPACE_BAR32 = 0x00,
578 /** 64-bit BAR. */
579 PCIRAW_ADDRESS_SPACE_BAR64 = 0x04,
580 /** Prefetch memory. */
581 PCIRAW_ADDRESS_SPACE_MEM_PREFETCH = 0x08,
582 /** The usual 32-bit type blow up. */
583 PCIRAW_ADDRESS_SPACE_32BIT_HACK = 0x7fffffff
584} PCIRAWADDRESSSPACE;
585
586RT_C_DECLS_END
587
588/* #define VBOX_WITH_SHARED_PCI_INTERRUPTS */
589
590#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