PCI subsystem

API Reference

struct PCIIOMMUOps: callbacks structure for specific IOMMU handlers of a PCIBus

Definition

struct PCIIOMMUOps {
  AddressSpace * (*get_address_space)(PCIBus *bus, void *opaque, int devfn);
  bool (*set_iommu_device)(PCIBus *bus, void *opaque, int devfn, HostIOMMUDevice *dev, Error **errp);
  void (*unset_iommu_device)(PCIBus *bus, void *opaque, int devfn);
  void (*get_iotlb_info)(void *opaque, uint8_t *addr_width, uint32_t *min_page_size);
  void (*init_iotlb_notifier)(PCIBus *bus, void *opaque, int devfn,IOMMUNotifier *n, IOMMUNotify fn, void *user_opaque);
  void (*register_iotlb_notifier)(PCIBus *bus, void *opaque, int devfn, uint32_t pasid, IOMMUNotifier *n);
  void (*unregister_iotlb_notifier)(PCIBus *bus, void *opaque, int devfn, uint32_t pasid, IOMMUNotifier *n);
  ssize_t (*ats_request_translation)(PCIBus *bus, void *opaque, int devfn,uint32_t pasid, bool priv_req,bool exec_req, hwaddr addr,size_t length, bool no_write,IOMMUTLBEntry *result,size_t result_length, uint32_t *err_count);
  void (*pri_register_notifier)(PCIBus *bus, void *opaque, int devfn, uint32_t pasid, IOMMUPRINotifier *notifier);
  void (*pri_unregister_notifier)(PCIBus *bus, void *opaque, int devfn, uint32_t pasid);
  int (*pri_request_page)(PCIBus *bus, void *opaque, int devfn,uint32_t pasid, bool priv_req, bool exec_req,hwaddr addr, bool lpig, uint16_t prgi, bool is_read, bool is_write);
};

Members

get_address_space

get the address space for a set of devices on a PCI bus.

Mandatory callback which returns a pointer to an AddressSpace

bus: the PCIBus being accessed.

opaque: the data passed to pci_setup_iommu().

devfn: device and function number

set_iommu_device

attach a HostIOMMUDevice to a vIOMMU

Optional callback, if not implemented in vIOMMU, then vIOMMU can’t retrieve host information from the associated HostIOMMUDevice.

bus: the PCIBus of the PCI device.

opaque: the data passed to pci_setup_iommu().

devfn: device and function number of the PCI device.

dev: the HostIOMMUDevice to attach.

errp: pass an Error out only when return false

Returns: true if HostIOMMUDevice is attached or else false with errp set.

unset_iommu_device

detach a HostIOMMUDevice from a vIOMMU

Optional callback.

bus: the PCIBus of the PCI device.

opaque: the data passed to pci_setup_iommu().

devfn: device and function number of the PCI device.

get_iotlb_info

get properties required to initialize a device IOTLB.

Callback required if devices are allowed to cache translations.

opaque: the data passed to pci_setup_iommu().

addr_width: the address width of the IOMMU (output parameter).

min_page_size: the page size of the IOMMU (output parameter).

init_iotlb_notifier

initialize an IOMMU notifier.

Optional callback.

bus: the PCIBus of the PCI device.

opaque: the data passed to pci_setup_iommu().

devfn: device and function number of the PCI device.

n: the notifier to be initialized.

fn: the callback to be installed.

user_opaque: a user pointer that can be used to track a state.

register_iotlb_notifier

setup an IOTLB invalidation notifier.

Callback required if devices are allowed to cache translations.

bus: the PCIBus of the PCI device.

opaque: the data passed to pci_setup_iommu().

devfn: device and function number of the PCI device.

pasid: the pasid of the address space to watch.

n: the notifier to register.

unregister_iotlb_notifier

remove an IOTLB invalidation notifier.

Callback required if devices are allowed to cache translations.

bus: the PCIBus of the PCI device.

opaque: the data passed to pci_setup_iommu().

devfn: device and function number of the PCI device.

pasid: the pasid of the address space to stop watching.

n: the notifier to unregister.

ats_request_translation

issue an ATS request.

Callback required if devices are allowed to use the address translation service.

bus: the PCIBus of the PCI device.

opaque: the data passed to pci_setup_iommu().

devfn: device and function number of the PCI device.

pasid: the pasid of the address space to use for the request.

priv_req: privileged mode bit (PASID TLP).

exec_req: execute request bit (PASID TLP).

addr: start address of the memory range to be translated.

length: length of the memory range in bytes.

no_write: request a read-only translation (if supported).

result: buffer in which the TLB entries will be stored.

result_length: result buffer length.

err_count: number of untranslated subregions.

Returns: the number of translations stored in the result buffer, or -ENOMEM if the buffer is not large enough.

pri_register_notifier

setup the PRI completion callback.

Callback required if devices are allowed to use the page request interface.

bus: the PCIBus of the PCI device.

opaque: the data passed to pci_setup_iommu().

devfn: device and function number of the PCI device.

pasid: the pasid of the address space to track.

notifier: the notifier to register.

pri_unregister_notifier

remove the PRI completion callback.

Callback required if devices are allowed to use the page request interface.

bus: the PCIBus of the PCI device.

opaque: the data passed to pci_setup_iommu().

devfn: device and function number of the PCI device.

pasid: the pasid of the address space to stop tracking.

pri_request_page

issue a PRI request.

Callback required if devices are allowed to use the page request interface.

bus: the PCIBus of the PCI device.

opaque: the data passed to pci_setup_iommu().

devfn: device and function number of the PCI device.

pasid: the pasid of the address space to use for the request.

priv_req: privileged mode bit (PASID TLP).

exec_req: execute request bit (PASID TLP).

addr: untranslated address of the requested page.

lpig: last page in group.

prgi: page request group index.

is_read: request read access.

is_write: request write access.

Description

Allows to modify the behavior of some IOMMU operations of the PCI framework for a set of devices on a PCI bus.

int pci_iommu_get_iotlb_info(PCIDevice *dev, uint8_t *addr_width, uint32_t *min_page_size): get properties required to initialize a device IOTLB.

Parameters

PCIDevice *dev: the device that wants to get the information.
uint8_t *addr_width: the address width of the IOMMU (output parameter).
uint32_t *min_page_size: the page size of the IOMMU (output parameter).

Description

Returns 0 on success, or a negative errno otherwise.

int pci_iommu_init_iotlb_notifier(PCIDevice *dev, IOMMUNotifier *n, IOMMUNotify fn, void *opaque): initialize an IOMMU notifier.

Parameters

PCIDevice *dev: the device.
IOMMUNotifier *n: the notifier to be initialized.
IOMMUNotify fn: the callback to be installed.
void *opaque: a user pointer that can be used to track a state.

Description

This function is used by devices before registering an IOTLB notifier.

ssize_t pci_ats_request_translation(PCIDevice *dev, uint32_t pasid, bool priv_req, bool exec_req, hwaddr addr, size_t length, bool no_write, IOMMUTLBEntry *result, size_t result_length, uint32_t *err_count): perform an ATS request.

Parameters

PCIDevice *dev: the ATS-capable PCI device.
uint32_t pasid: the pasid of the address space in which the translation will be done.
bool priv_req: privileged mode bit (PASID TLP).
bool exec_req: execute request bit (PASID TLP).
hwaddr addr: start address of the memory range to be translated.
size_t length: length of the memory range in bytes.
bool no_write: request a read-only translation (if supported).
IOMMUTLBEntry *result: buffer in which the TLB entries will be stored.
size_t result_length: result buffer length.
uint32_t *err_count: number of untranslated subregions.

Description

Returns the number of translations stored in result in case of success, a negative error code otherwise. -ENOMEM is returned when the result buffer is not large enough to store all the translations.

int pci_pri_request_page(PCIDevice *dev, uint32_t pasid, bool priv_req, bool exec_req, hwaddr addr, bool lpig, uint16_t prgi, bool is_read, bool is_write): perform a PRI request.

Parameters

PCIDevice *dev: the PRI-capable PCI device.
uint32_t pasid: the pasid of the address space in which the translation will be done.
bool priv_req: privileged mode bit (PASID TLP).
bool exec_req: execute request bit (PASID TLP).
hwaddr addr: untranslated address of the requested page.
bool lpig: last page in group.
uint16_t prgi: page request group index.
bool is_read: request read access.
bool is_write: request write access.

Description

Returns 0 if the PRI request has been sent to the guest OS, an error code otherwise.

int pci_pri_register_notifier(PCIDevice *dev, uint32_t pasid, IOMMUPRINotifier *notifier): register the PRI callback for a given address space.

Parameters

PCIDevice *dev: the PRI-capable PCI device.
uint32_t pasid: the pasid of the address space to track.
IOMMUPRINotifier *notifier: the notifier to register.

Description

Returns 0 on success, an error code otherwise.

void pci_pri_unregister_notifier(PCIDevice *dev, uint32_t pasid): remove the PRI callback from a given address space.

Parameters

PCIDevice *dev: the PRI-capable PCI device.
uint32_t pasid: the pasid of the address space to stop tracking.

int pci_iommu_register_iotlb_notifier(PCIDevice *dev, uint32_t pasid, IOMMUNotifier *n): register a notifier for changes to IOMMU translation entries in a specific address space.

Parameters

PCIDevice *dev: the device that wants to get notified.
uint32_t pasid: the pasid of the address space to track.
IOMMUNotifier *n: the notifier to register.

Description

Returns 0 on success, or a negative errno otherwise.

int pci_iommu_unregister_iotlb_notifier(PCIDevice *dev, uint32_t pasid, IOMMUNotifier *n): unregister a notifier that has been registerd with pci_iommu_register_iotlb_notifier.

Parameters

PCIDevice *dev: the device that wants to stop notifications.
uint32_t pasid: the pasid of the address space to stop tracking.
IOMMUNotifier *n: the notifier to unregister.

Description

Returns 0 on success, or a negative errno otherwise.

void pci_setup_iommu(PCIBus *bus, const PCIIOMMUOps *ops, void *opaque): Initialize specific IOMMU handlers for a PCIBus

Parameters

PCIBus *bus: the PCIBus being updated.
const PCIIOMMUOps *ops: the PCIIOMMUOps
void *opaque: passed to callbacks of the ops structure.

Description

Let PCI host bridges define specific operations.