1
0
Fork 0
virtualbox/include/VBox/rawpci.h
Daniel Baumann 2b3ba1f3e4
Merging upstream version 7.1.8-dfsg.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
2025-06-24 20:41:59 +02:00

616 lines
19 KiB
C

/** @file
* Raw PCI Devices (aka PCI pass-through). (VMM)
*/
/*
* Copyright (C) 2010-2024 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
* in the VirtualBox distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
*/
#ifndef VBOX_INCLUDED_rawpci_h
#define VBOX_INCLUDED_rawpci_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include <VBox/types.h>
#include <VBox/sup.h>
RT_C_DECLS_BEGIN
/**
* Handle for the raw PCI device.
*/
typedef uint32_t PCIRAWDEVHANDLE;
/**
* Handle for the ISR.
*/
typedef uint32_t PCIRAWISRHANDLE;
/**
* Physical memory action enumeration.
*/
typedef enum PCIRAWMEMINFOACTION
{
/** Pages mapped. */
PCIRAW_MEMINFO_MAP,
/** Pages unmapped. */
PCIRAW_MEMINFO_UNMAP,
/** The usual 32-bit type blow up. */
PCIRAW_MEMINFO_32BIT_HACK = 0x7fffffff
} PCIRAWMEMINFOACTION;
/**
* Per-VM capability flag bits.
*/
typedef enum PCIRAWVMFLAGS
{
/** If we can use IOMMU in this VM. */
PCIRAW_VMFLAGS_HAS_IOMMU = (1 << 0),
PCIRAW_VMFLAGS_32BIT_HACK = 0x7fffffff
} PCIRAWVMFLAGS;
/* Forward declaration. */
struct RAWPCIPERVM;
/**
* Callback to notify raw PCI subsystem about mapping/unmapping of
* host pages to the guest. Typical usecase is to register physical
* RAM pages with IOMMU, so that it could allow DMA for PCI devices
* directly from the guest RAM.
* Region shall be one or more contigous (both host and guest) pages
* of physical memory.
*
* @returns VBox status code.
*
* @param pVmData The per VM data.
* @param HCPhysStart Physical address of region start on the host.
* @param GCPhysStart Physical address of region start on the guest.
* @param cbMem Region size in bytes.
* @param enmAction Action performed (i.e. if page was mapped
* or unmapped).
*/
typedef DECLCALLBACKTYPE(int, FNRAWPCICONTIGPHYSMEMINFO,(struct RAWPCIPERVM *pVmData, RTHCPHYS HCPhysStart,
RTGCPHYS GCPhysStart, uint64_t cbMem, PCIRAWMEMINFOACTION enmAction));
typedef FNRAWPCICONTIGPHYSMEMINFO *PFNRAWPCICONTIGPHYSMEMINFO;
/** Data being part of the VM structure. */
typedef struct RAWPCIPERVM
{
/** Shall only be interpreted by the host PCI driver. */
RTR0PTR pDriverData;
/** Callback called when mapping of host pages to the guest changes. */
PFNRAWPCICONTIGPHYSMEMINFO pfnContigMemInfo;
/** Flags describing VM capabilities (such as IOMMU presence). */
uint32_t fVmCaps;
} RAWPCIPERVM;
typedef RAWPCIPERVM *PRAWPCIPERVM;
/** Parameters buffer for PCIRAWR0_DO_OPEN_DEVICE call */
typedef struct
{
/* in */
uint32_t PciAddress;
uint32_t fFlags;
/* out */
PCIRAWDEVHANDLE Device;
uint32_t fDevFlags;
} PCIRAWREQOPENDEVICE;
/** Parameters buffer for PCIRAWR0_DO_CLOSE_DEVICE call */
typedef struct
{
/* in */
uint32_t fFlags;
} PCIRAWREQCLOSEDEVICE;
/** Parameters buffer for PCIRAWR0_DO_GET_REGION_INFO call */
typedef struct
{
/* in */
int32_t iRegion;
/* out */
RTGCPHYS RegionStart;
uint64_t u64RegionSize;
bool fPresent;
uint32_t fFlags;
} PCIRAWREQGETREGIONINFO;
/** Parameters buffer for PCIRAWR0_DO_MAP_REGION call. */
typedef struct
{
/* in */
RTGCPHYS StartAddress;
uint64_t iRegionSize;
int32_t iRegion;
uint32_t fFlags;
/* out */
RTR3PTR pvAddressR3;
RTR0PTR pvAddressR0;
} PCIRAWREQMAPREGION;
/** Parameters buffer for PCIRAWR0_DO_UNMAP_REGION call. */
typedef struct
{
/* in */
RTGCPHYS StartAddress;
uint64_t iRegionSize;
RTR3PTR pvAddressR3;
RTR0PTR pvAddressR0;
int32_t iRegion;
} PCIRAWREQUNMAPREGION;
/** Parameters buffer for PCIRAWR0_DO_PIO_WRITE call. */
typedef struct
{
/* in */
uint16_t iPort;
uint16_t cb;
uint32_t iValue;
} PCIRAWREQPIOWRITE;
/** Parameters buffer for PCIRAWR0_DO_PIO_READ call. */
typedef struct
{
/* in */
uint16_t iPort;
uint16_t cb;
/* out */
uint32_t iValue;
} PCIRAWREQPIOREAD;
/** Memory operand. */
typedef struct
{
union
{
uint8_t u8;
uint16_t u16;
uint32_t u32;
uint64_t u64;
} u;
uint8_t cb;
} PCIRAWMEMLOC;
/** Parameters buffer for PCIRAWR0_DO_MMIO_WRITE call. */
typedef struct
{
/* in */
RTR0PTR Address;
PCIRAWMEMLOC Value;
} PCIRAWREQMMIOWRITE;
/** Parameters buffer for PCIRAWR0_DO_MMIO_READ call. */
typedef struct
{
/* in */
RTR0PTR Address;
/* inout (Value.cb is in) */
PCIRAWMEMLOC Value;
} PCIRAWREQMMIOREAD;
/* Parameters buffer for PCIRAWR0_DO_PCICFG_WRITE call. */
typedef struct
{
/* in */
uint32_t iOffset;
PCIRAWMEMLOC Value;
} PCIRAWREQPCICFGWRITE;
/** Parameters buffer for PCIRAWR0_DO_PCICFG_READ call. */
typedef struct
{
/* in */
uint32_t iOffset;
/* inout (Value.cb is in) */
PCIRAWMEMLOC Value;
} PCIRAWREQPCICFGREAD;
/** Parameters buffer for PCIRAWR0_DO_GET_IRQ call. */
typedef struct PCIRAWREQGETIRQ
{
/* in */
int64_t iTimeout;
/* out */
int32_t iIrq;
} PCIRAWREQGETIRQ;
/** Parameters buffer for PCIRAWR0_DO_POWER_STATE_CHANGE call. */
typedef struct PCIRAWREQPOWERSTATECHANGE
{
/* in */
uint32_t iState;
/* in/out */
uint64_t u64Param;
} PCIRAWREQPOWERSTATECHANGE;
/**
* Request buffer use for communication with the driver.
*/
typedef struct PCIRAWSENDREQ
{
/** The request header. */
SUPVMMR0REQHDR Hdr;
/** Alternative to passing the taking the session from the VM handle.
* Either use this member or use the VM handle, don't do both.
*/
PSUPDRVSESSION pSession;
/** Request type. */
int32_t iRequest;
/** Host device request targetted to. */
PCIRAWDEVHANDLE TargetDevice;
/** Call parameters. */
union
{
PCIRAWREQOPENDEVICE aOpenDevice;
PCIRAWREQCLOSEDEVICE aCloseDevice;
PCIRAWREQGETREGIONINFO aGetRegionInfo;
PCIRAWREQMAPREGION aMapRegion;
PCIRAWREQUNMAPREGION aUnmapRegion;
PCIRAWREQPIOWRITE aPioWrite;
PCIRAWREQPIOREAD aPioRead;
PCIRAWREQMMIOWRITE aMmioWrite;
PCIRAWREQMMIOREAD aMmioRead;
PCIRAWREQPCICFGWRITE aPciCfgWrite;
PCIRAWREQPCICFGREAD aPciCfgRead;
PCIRAWREQGETIRQ aGetIrq;
PCIRAWREQPOWERSTATECHANGE aPowerStateChange;
} u;
} PCIRAWSENDREQ;
typedef PCIRAWSENDREQ *PPCIRAWSENDREQ;
/**
* Operations performed by the driver.
*/
typedef enum PCIRAWR0OPERATION
{
/* Open device. */
PCIRAWR0_DO_OPEN_DEVICE,
/* Close device. */
PCIRAWR0_DO_CLOSE_DEVICE,
/* Get PCI region info. */
PCIRAWR0_DO_GET_REGION_INFO,
/* Map PCI region into VM address space. */
PCIRAWR0_DO_MAP_REGION,
/* Unmap PCI region from VM address space. */
PCIRAWR0_DO_UNMAP_REGION,
/* Perform PIO write. */
PCIRAWR0_DO_PIO_WRITE,
/* Perform PIO read. */
PCIRAWR0_DO_PIO_READ,
/* Perform MMIO write. */
PCIRAWR0_DO_MMIO_WRITE,
/* Perform MMIO read. */
PCIRAWR0_DO_MMIO_READ,
/* Perform PCI config write. */
PCIRAWR0_DO_PCICFG_WRITE,
/* Perform PCI config read. */
PCIRAWR0_DO_PCICFG_READ,
/* Get next IRQ for the device. */
PCIRAWR0_DO_GET_IRQ,
/* Enable getting IRQs for the device. */
PCIRAWR0_DO_ENABLE_IRQ,
/* Disable getting IRQs for the device. */
PCIRAWR0_DO_DISABLE_IRQ,
/* Notify driver about guest power state change. */
PCIRAWR0_DO_POWER_STATE_CHANGE,
/** The usual 32-bit type blow up. */
PCIRAWR0_DO_32BIT_HACK = 0x7fffffff
} PCIRAWR0OPERATION;
/**
* Power state enumeration.
*/
typedef enum PCIRAWPOWERSTATE
{
/* Power on. */
PCIRAW_POWER_ON,
/* Power off. */
PCIRAW_POWER_OFF,
/* Suspend. */
PCIRAW_POWER_SUSPEND,
/* Resume. */
PCIRAW_POWER_RESUME,
/* Reset. */
PCIRAW_POWER_RESET,
/** The usual 32-bit type blow up. */
PCIRAW_POWER_32BIT_HACK = 0x7fffffff
} PCIRAWPOWERSTATE;
/** Forward declarations. */
typedef struct RAWPCIFACTORY *PRAWPCIFACTORY;
typedef struct RAWPCIDEVPORT *PRAWPCIDEVPORT;
/**
* Interrupt service routine callback.
*
* @returns if interrupt was processed.
*
* @param pvContext Opaque user data passed to the handler.
* @param iIrq Interrupt number.
*/
typedef DECLCALLBACKTYPE(bool, FNRAWPCIISR,(void *pvContext, int32_t iIrq));
typedef FNRAWPCIISR *PFNRAWPCIISR;
/**
* This is the port on the device interface, i.e. the driver side which the
* host device is connected to.
*
* This is only used for the in-kernel PCI device connections.
*/
typedef struct RAWPCIDEVPORT
{
/** Structure version number. (RAWPCIDEVPORT_VERSION) */
uint32_t u32Version;
/**
* Init device.
*
* @param pPort Pointer to this structure.
* @param fFlags Initialization flags.
*/
DECLR0CALLBACKMEMBER(int, pfnInit,(PRAWPCIDEVPORT pPort,
uint32_t fFlags));
/**
* Deinit device.
*
* @param pPort Pointer to this structure.
* @param fFlags Initialization flags.
*/
DECLR0CALLBACKMEMBER(int, pfnDeinit,(PRAWPCIDEVPORT pPort,
uint32_t fFlags));
/**
* Destroy device.
*
* @param pPort Pointer to this structure.
*/
DECLR0CALLBACKMEMBER(int, pfnDestroy,(PRAWPCIDEVPORT pPort));
/**
* Get PCI region info.
*
* @param pPort Pointer to this structure.
* @param iRegion Region number.
* @param pRegionStart Where to start the region address.
* @param pu64RegionSize Where to store the region size.
* @param pfPresent Where to store if the region is present.
* @param pfFlags Where to store the flags.
*/
DECLR0CALLBACKMEMBER(int, pfnGetRegionInfo,(PRAWPCIDEVPORT pPort,
int32_t iRegion,
RTHCPHYS *pRegionStart,
uint64_t *pu64RegionSize,
bool *pfPresent,
uint32_t *pfFlags));
/**
* Map PCI region.
*
* @param pPort Pointer to this structure.
* @param iRegion Region number.
* @param RegionStart Region start.
* @param u64RegionSize Region size.
* @param fFlags Flags.
* @param pRegionBaseR0 Where to store the R0 address.
*/
DECLR0CALLBACKMEMBER(int, pfnMapRegion,(PRAWPCIDEVPORT pPort,
int32_t iRegion,
RTHCPHYS RegionStart,
uint64_t u64RegionSize,
int32_t fFlags,
RTR0PTR *pRegionBaseR0));
/**
* Unmap PCI region.
*
* @param pPort Pointer to this structure.
* @param iRegion Region number.
* @param RegionStart Region start.
* @param u64RegionSize Region size.
* @param RegionBase Base address.
*/
DECLR0CALLBACKMEMBER(int, pfnUnmapRegion,(PRAWPCIDEVPORT pPort,
int32_t iRegion,
RTHCPHYS RegionStart,
uint64_t u64RegionSize,
RTR0PTR RegionBase));
/**
* Read device PCI register.
*
* @param pPort Pointer to this structure.
* @param Register PCI register.
* @param pValue Read value (with desired read width).
*/
DECLR0CALLBACKMEMBER(int, pfnPciCfgRead,(PRAWPCIDEVPORT pPort,
uint32_t Register,
PCIRAWMEMLOC *pValue));
/**
* Write device PCI register.
*
* @param pPort Pointer to this structure.
* @param Register PCI register.
* @param pValue Write value (with desired write width).
*/
DECLR0CALLBACKMEMBER(int, pfnPciCfgWrite,(PRAWPCIDEVPORT pPort,
uint32_t Register,
PCIRAWMEMLOC *pValue));
/**
* Request to register interrupt handler.
*
* @param pPort Pointer to this structure.
* @param pfnHandler Pointer to the handler.
* @param pIrqContext Context passed to the handler.
* @param phIsr Handle for the ISR, .
*/
DECLR0CALLBACKMEMBER(int, pfnRegisterIrqHandler,(PRAWPCIDEVPORT pPort,
PFNRAWPCIISR pfnHandler,
void* pIrqContext,
PCIRAWISRHANDLE *phIsr));
/**
* Request to unregister interrupt handler.
*
* @param pPort Pointer to this structure.
* @param hIsr Handle of ISR to unregister (retured by earlier pfnRegisterIrqHandler).
*/
DECLR0CALLBACKMEMBER(int, pfnUnregisterIrqHandler,(PRAWPCIDEVPORT pPort,
PCIRAWISRHANDLE hIsr));
/**
* Power state change notification.
*
* @param pPort Pointer to this structure.
* @param aState New power state.
* @param pu64Param State-specific in/out parameter.
*/
DECLR0CALLBACKMEMBER(int, pfnPowerStateChange,(PRAWPCIDEVPORT pPort,
PCIRAWPOWERSTATE aState,
uint64_t *pu64Param));
/** Structure version number. (RAWPCIDEVPORT_VERSION) */
uint32_t u32VersionEnd;
} RAWPCIDEVPORT;
/** Version number for the RAWPCIDEVPORT::u32Version and RAWPCIIFPORT::u32VersionEnd fields. */
#define RAWPCIDEVPORT_VERSION UINT32_C(0xAFBDCC02)
/**
* The component factory interface for create a raw PCI interfaces.
*/
typedef struct RAWPCIFACTORY
{
/**
* Release this factory.
*
* SUPR0ComponentQueryFactory (SUPDRVFACTORY::pfnQueryFactoryInterface to be precise)
* will retain a reference to the factory and the caller has to call this method to
* release it once the pfnCreateAndConnect call(s) has been done.
*
* @param pFactory Pointer to this structure.
*/
DECLR0CALLBACKMEMBER(void, pfnRelease,(PRAWPCIFACTORY pFactory));
/**
* Create an instance for the specfied host PCI card and connects it
* to the driver.
*
*
* @returns VBox status code.
*
* @param pFactory Pointer to this structure.
* @param u32HostAddress Address of PCI device on the host.
* @param fFlags Creation flags.
* @param pVmCtx Context of VM where device is created.
* @param ppDevPort Where to store the pointer to the device port
* on success.
* @param pfDevFlags Where to store the device flags.
*
*/
DECLR0CALLBACKMEMBER(int, pfnCreateAndConnect,(PRAWPCIFACTORY pFactory,
uint32_t u32HostAddress,
uint32_t fFlags,
PRAWPCIPERVM pVmCtx,
PRAWPCIDEVPORT *ppDevPort,
uint32_t *pfDevFlags));
/**
* Initialize per-VM data related to PCI passthrough.
*
* @returns VBox status code.
*
* @param pFactory Pointer to this structure.
* @param pVM The cross context VM structure.
* @param pVmData Pointer to PCI data.
*/
DECLR0CALLBACKMEMBER(int, pfnInitVm,(PRAWPCIFACTORY pFactory,
PVM pVM,
PRAWPCIPERVM pVmData));
/**
* Deinitialize per-VM data related to PCI passthrough.
*
* @param pFactory Pointer to this structure.
* @param pVM The cross context VM structure.
* @param pVmData Pointer to PCI data.
*/
DECLR0CALLBACKMEMBER(void, pfnDeinitVm,(PRAWPCIFACTORY pFactory,
PVM pVM,
PRAWPCIPERVM pVmData));
} RAWPCIFACTORY;
#define RAWPCIFACTORY_UUID_STR "ea089839-4171-476f-adfb-9e7ab1cbd0fb"
/**
* Flags passed to pfnPciDeviceConstructStart(), to notify driver
* about options to be used to open device.
*/
typedef enum PCIRAWDRIVERFLAGS
{
/** If runtime shall try to detach host driver. */
PCIRAWDRIVERRFLAG_DETACH_HOST_DRIVER = (1 << 0),
/** The usual 32-bit type blow up. */
PCIRAWDRIVERRFLAG_32BIT_HACK = 0x7fffffff
} PCIRAWDRIVERFLAGS;
/**
* Flags used to describe PCI region, matches to PCIADDRESSSPACE
* in pci.h.
*/
typedef enum PCIRAWADDRESSSPACE
{
/** Memory. */
PCIRAW_ADDRESS_SPACE_MEM = 0x00,
/** I/O space. */
PCIRAW_ADDRESS_SPACE_IO = 0x01,
/** 32-bit BAR. */
PCIRAW_ADDRESS_SPACE_BAR32 = 0x00,
/** 64-bit BAR. */
PCIRAW_ADDRESS_SPACE_BAR64 = 0x04,
/** Prefetch memory. */
PCIRAW_ADDRESS_SPACE_MEM_PREFETCH = 0x08,
/** The usual 32-bit type blow up. */
PCIRAW_ADDRESS_SPACE_32BIT_HACK = 0x7fffffff
} PCIRAWADDRESSSPACE;
RT_C_DECLS_END
/* #define VBOX_WITH_SHARED_PCI_INTERRUPTS */
#endif /* !VBOX_INCLUDED_rawpci_h */