rawpci.h@ 61128

Last change on this file since 61128 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
32	RT_C_DECLS_BEGIN
33
34	/**
35	* Handle for the raw PCI device.
36	*/
37	typedef uint32_t PCIRAWDEVHANDLE;
38
39	/**
40	* Handle for the ISR.
41	*/
42	typedef uint32_t PCIRAWISRHANDLE;
43
44	/**
45	* Physical memory action enumeration.
46	*/
47	typedef 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	*/
60	typedef 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. */
68	struct 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	*/
87	typedef DECLCALLBACK(int) FNRAWPCICONTIGPHYSMEMINFO(struct RAWPCIPERVM *pVmData, RTHCPHYS HCPhysStart,
88	RTGCPHYS GCPhysStart, uint64_t cbMem, PCIRAWMEMINFOACTION enmAction);
89	typedef FNRAWPCICONTIGPHYSMEMINFO *PFNRAWPCICONTIGPHYSMEMINFO;
90
91	/** Data being part of the VM structure. */
92	typedef 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;
101	typedef RAWPCIPERVM *PRAWPCIPERVM;
102
103	/** Parameters buffer for PCIRAWR0_DO_OPEN_DEVICE call */
104	typedef 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 */
115	typedef struct
116	{
117	/* in */
118	uint32_t fFlags;
119	} PCIRAWREQCLOSEDEVICE;
120
121	/** Parameters buffer for PCIRAWR0_DO_GET_REGION_INFO call */
122	typedef 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. */
134	typedef 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. */
147	typedef 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. */
158	typedef 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. */
167	typedef struct
168	{
169	/* in */
170	uint16_t iPort;
171	uint16_t cb;
172	/* out */
173	uint32_t iValue;
174	} PCIRAWREQPIOREAD;
175
176	/** Memory operand. */
177	typedef 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. */
190	typedef struct
191	{
192	/* in */
193	RTR0PTR Address;
194	PCIRAWMEMLOC Value;
195	} PCIRAWREQMMIOWRITE;
196
197	/** Parameters buffer for PCIRAWR0_DO_MMIO_READ call. */
198	typedef 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. */
207	typedef struct
208	{
209	/* in */
210	uint32_t iOffset;
211	PCIRAWMEMLOC Value;
212	} PCIRAWREQPCICFGWRITE;
213
214	/** Parameters buffer for PCIRAWR0_DO_PCICFG_READ call. */
215	typedef 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. */
224	typedef 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. */
233	typedef 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	*/
244	typedef 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;
274	typedef PCIRAWSENDREQ *PPCIRAWSENDREQ;
275
276	/**
277	* Operations performed by the driver.
278	*/
279	typedef 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	*/
318	typedef 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. */
336	typedef struct RAWPCIFACTORY *PRAWPCIFACTORY;
337	typedef 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	*/
347	typedef DECLCALLBACK(bool) FNRAWPCIISR(void *pvContext, int32_t iIrq);
348	typedef 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	*/
356	typedef 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	*/
489	typedef 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	*/
558	typedef 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	*/
570	typedef 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
586	RT_C_DECLS_END
587
588	/* #define VBOX_WITH_SHARED_PCI_INTERRUPTS */
589
590	#endif

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: