Device Model APIs¶
This section contains APIs for the Service VM Device Model services. Sources
for the Device Model are found in the devicemodel
folder of the ACRN
hypervisor GitHub repo.
- group acrn_virtio
virtio API
vhost APIs
APIs for virtio backend in kernel module.
Defines
-
VRING_PAGE_BITS¶
-
VIRTIO_TYPE_NET¶
-
VIRTIO_TYPE_BLOCK¶
-
VIRTIO_TYPE_CONSOLE¶
-
VIRTIO_TYPE_ENTROPY¶
-
VIRTIO_TYPE_BALLOON¶
-
VIRTIO_TYPE_IOMEMORY¶
-
VIRTIO_TYPE_RPMSG¶
-
VIRTIO_TYPE_SCSI¶
-
VIRTIO_TYPE_9P¶
-
VIRTIO_TYPE_INPUT¶
-
VIRTIO_TYPE_RPMB¶
-
VIRTIO_TYPE_HECI¶
-
VIRTIO_TYPE_AUDIO¶
-
VIRTIO_TYPE_IPU¶
-
VIRTIO_TYPE_TSN¶
-
VIRTIO_TYPE_HYPERDMABUF¶
-
VIRTIO_TYPE_HDCP¶
-
VIRTIO_TYPE_COREU¶
-
VIRTIO_TYPE_GPIO¶
-
VIRTIO_TYPE_I2C¶
-
VIRTIO_TYPE_GPU¶
-
INTEL_VENDOR_ID¶
-
ORACLE_VENDOR_ID¶
-
VIRTIO_VENDOR¶
-
VIRTIO_DEV_NET¶
-
VIRTIO_DEV_BLOCK¶
-
VIRTIO_DEV_CONSOLE¶
-
VIRTIO_DEV_RANDOM¶
-
VIRTIO_DEV_GPU¶
-
VIRTIO_DEV_VSOCK¶
-
VIRTIO_DEV_RPMB¶
-
VIRTIO_DEV_HECI¶
-
VIRTIO_DEV_AUDIO¶
-
VIRTIO_DEV_IPU¶
-
VIRTIO_DEV_TSN¶
-
VIRTIO_DEV_HYPERDMABUF¶
-
VIRTIO_DEV_HDCP¶
-
VIRTIO_DEV_COREU¶
-
VIRTIO_DEV_GPIO¶
-
VIRTIO_DEV_I2C¶
-
VIRTIO_CONFIG_S_NEEDS_RESET¶
-
VIRTIO_PCI_ISR_QUEUES¶
-
VIRTIO_USE_MSIX¶
-
VIRTIO_EVENT_IDX¶
-
VIRTIO_BROKED¶
-
VIRTIO_LEGACY_PIO_BAR_IDX¶
-
VIRTIO_MODERN_PIO_BAR_IDX¶
-
VIRTIO_MODERN_MMIO_BAR_IDX¶
-
VIRTIO_CAP_COMMON_OFFSET¶
-
VIRTIO_CAP_COMMON_SIZE¶
-
VIRTIO_CAP_ISR_OFFSET¶
-
VIRTIO_CAP_ISR_SIZE¶
-
VIRTIO_CAP_DEVICE_OFFSET¶
-
VIRTIO_CAP_DEVICE_SIZE¶
-
VIRTIO_CAP_NOTIFY_OFFSET¶
-
VIRTIO_CAP_NOTIFY_SIZE¶
-
VIRTIO_MODERN_MEM_BAR_SIZE¶
-
VIRTIO_MODERN_NOTIFY_OFF_MULT¶
-
VIRTIO_PCI_CAP_COMMON_CFG¶
-
VIRTIO_PCI_CAP_NOTIFY_CFG¶
-
VIRTIO_PCI_CAP_ISR_CFG¶
-
VIRTIO_PCI_CAP_DEVICE_CFG¶
-
VIRTIO_PCI_CAP_PCI_CFG¶
-
VIRTIO_BASE_LOCK(vb)¶
-
VIRTIO_BASE_UNLOCK(vb)¶
-
VQ_ALLOC¶
-
VQ_BROKED¶
-
VQ_AVAIL_EVENT_IDX(vq)¶
-
VQ_USED_EVENT_IDX(vq)¶
-
VIRTIO_SUCCESS¶
-
VIRTIO_ERROR_REENTER¶
-
VIRTIO_ERROR_FD_OPEN_FAILED¶
-
VIRTIO_ERROR_MEM_ALLOC_FAILED¶
-
VIRTIO_ERROR_START¶
-
VIRTIO_ERROR_GENERAL¶
Enums
Functions
-
static inline bool vq_ring_ready(struct virtio_vq_info *vq)¶
Is this ring ready for I/O?
- Parameters
vq – Pointer to struct virtio_vq_info.
- Returns
false on not ready and true on ready.
-
static inline bool vq_has_descs(struct virtio_vq_info *vq)¶
Are there “available” descriptors?
This does not count how many, just returns true if there is any.
- Parameters
vq – Pointer to struct virtio_vq_info.
- Returns
false on not available and true on available.
-
static inline void vq_interrupt(struct virtio_base *vb, struct virtio_vq_info *vq)¶
Deliver an interrupt to guest on the given virtqueue.
The interrupt could be MSI-X or a generic MSI interrupt.
- Parameters
vb – Pointer to struct virtio_base.
vq – Pointer to struct virtio_vq_info.
- Returns
None
-
static inline void virtio_config_changed(struct virtio_base *vb)¶
Deliver an config changed interrupt to guest.
MSI-X or a generic MSI interrupt with config changed event.
- Parameters
vb – Pointer to struct virtio_base.
- Returns
None
-
void virtio_linkup(struct virtio_base *base, struct virtio_ops *vops, void *pci_virtio_dev, struct pci_vdev *dev, struct virtio_vq_info *queues, int backend_type)¶
Link a virtio_base to its constants, the virtio device, and the PCI emulation.
- Parameters
base – Pointer to struct virtio_base.
vops – Pointer to struct virtio_ops.
pci_virtio_dev – Pointer to instance of certain virtio device.
dev – Pointer to struct pci_vdev which emulates a PCI device.
queues – Pointer to struct virtio_vq_info, normally an array.
backend_type – can be VBSU, VBSK or VHOST
- Returns
None
-
int acrn_parse_virtio_poll_interval(const char *optarg)¶
Get the virtio poll parameters.
- Parameters
optarg – Pointer to parameters string.
- Returns
fail -1 success 0
-
int virtio_interrupt_init(struct virtio_base *base, int use_msix)¶
Initialize MSI-X vector capabilities if we’re to use MSI-X, or MSI capabilities if not.
Wrapper function for virtio_intr_init() for cases we directly use BAR 1 for MSI-X capabilities.
- Parameters
base – Pointer to struct virtio_base.
use_msix – If using MSI-X.
- Returns
0 on success and non-zero on fail.
-
int virtio_intr_init(struct virtio_base *base, int barnum, int use_msix)¶
Initialize MSI-X vector capabilities if we’re to use MSI-X, or MSI capabilities if not.
We assume we want one MSI-X vector per queue, here, plus one for the config vec.
- Parameters
base – Pointer to struct virtio_base.
barnum – Which BAR[0..5] to use.
use_msix – If using MSI-X.
- Returns
0 on success and non-zero on fail.
-
void virtio_reset_dev(struct virtio_base *base)¶
Reset device (device-wide).
This erases all queues, i.e., all the queues become invalid. But we don’t wipe out the internal pointers, by just clearing the VQ_ALLOC flag.
It resets negotiated features to “none”. If MSI-X is enabled, this also resets all the vectors to NO_VECTOR.
- Parameters
base – Pointer to struct virtio_base.
- Returns
None
-
void virtio_set_io_bar(struct virtio_base *base, int barnum)¶
Set I/O BAR (usually 0) to map PCI config registers.
- Parameters
base – Pointer to struct virtio_base.
barnum – Which BAR[0..5] to use.
- Returns
None
-
int vq_getchain(struct virtio_vq_info *vq, uint16_t *pidx, struct iovec *iov, int n_iov, uint16_t *flags)¶
Walk through the chain of descriptors involved in a request and put them into a given iov[] array.
- Parameters
vq – Pointer to struct virtio_vq_info.
pidx – Pointer to available ring position.
iov – Pointer to iov[] array prepared by caller.
n_iov – Size of iov[] array.
flags – Pointer to a uint16_t array which will contain flag of each descriptor.
- Returns
number of descriptors.
-
void vq_retchain(struct virtio_vq_info *vq)¶
Return the currently-first request chain back to the available ring.
- Parameters
vq – Pointer to struct virtio_vq_info.
- Returns
None
-
void vq_relchain(struct virtio_vq_info *vq, uint16_t idx, uint32_t iolen)¶
Return specified request chain to the guest, setting its I/O length to the provided value.
- Parameters
vq – Pointer to struct virtio_vq_info.
idx – Pointer to available ring position, returned by vq_getchain().
iolen – Number of data bytes to be returned to frontend.
- Returns
None
-
void vq_endchains(struct virtio_vq_info *vq, int used_all_avail)¶
Driver has finished processing “available” chains and calling vq_relchain on each one.
If driver used all the available chains, used_all_avail need to be set to 1.
- Parameters
vq – Pointer to struct virtio_vq_info.
used_all_avail – Flag indicating if driver used all available chains.
- Returns
None
-
void vq_clear_used_ring_flags(struct virtio_base *base, struct virtio_vq_info *vq)¶
Helper function for clearing used ring flags.
Driver should always use this helper function to clear used ring flags. For virtio poll mode, in order to avoid trap, we should never really clear used ring flags.
- Parameters
base – Pointer to struct virtio_base.
vq – Pointer to struct virtio_vq_info.
- Returns
None
-
uint64_t virtio_pci_read(struct vmctx *ctx, int vcpu, struct pci_vdev *dev, int baridx, uint64_t offset, int size)¶
Handle PCI configuration space reads.
Handle virtio standard register reads, and dispatch other reads to actual virtio device driver.
- Parameters
ctx – Pointer to struct vmctx representing VM context.
vcpu – VCPU ID.
dev – Pointer to struct pci_vdev which emulates a PCI device.
baridx – Which BAR[0..5] to use.
offset – Register offset in bytes within a BAR region.
size – Access range in bytes.
- Returns
register value.
-
void virtio_pci_write(struct vmctx *ctx, int vcpu, struct pci_vdev *dev, int baridx, uint64_t offset, int size, uint64_t value)¶
Handle PCI configuration space writes.
Handle virtio standard register writes, and dispatch other writes to actual virtio device driver.
- Parameters
ctx – Pointer to struct vmctx representing VM context.
vcpu – VCPU ID.
dev – Pointer to struct pci_vdev which emulates a PCI device.
baridx – Which BAR[0..5] to use.
offset – Register offset in bytes within a BAR region.
size – Access range in bytes.
value – Data value to be written into register.
- Returns
None
-
int virtio_set_modern_bar(struct virtio_base *base, bool use_notify_pio)¶
Set modern BAR (usually 4) to map PCI config registers.
Set modern MMIO BAR (usually 4) to map virtio 1.0 capabilities and optional set modern PIO BAR (usually 2) to map notify capability. This interface is only valid for modern virtio.
- Parameters
base – Pointer to struct virtio_base.
use_notify_pio – Whether use pio for notify capability.
- Returns
0 on success and non-zero on fail.
-
int vbs_kernel_reset(int fd)¶
Virtio kernel module reset.
- Parameters
fd – File descriptor representing virtio backend in kernel module.
- Returns
0 on OK and non-zero on error.
-
int vbs_kernel_start(int fd, struct vbs_dev_info *dev, struct vbs_vqs_info *vqs)¶
Virtio kernel module start.
- Parameters
fd – File descriptor representing virtio backend in kernel module.
dev – Pointer to struct vbs_dev_info.
vqs – Pointer to struct vbs_vqs_info.
- Returns
0 on OK and non-zero on error.
-
int vbs_kernel_stop(int fd)¶
Virtio kernel module stop.
- Parameters
fd – File descriptor representing virtio backend in kernel module.
- Returns
0 on OK and non-zero on error.
-
struct virtio_base¶
- #include <virtio.h>
Base component to any virtio device.
-
struct virtio_ops¶
- #include <virtio.h>
Virtio specific operation functions for this type of virtio device.
-
struct virtio_vq_info¶
- #include <virtio.h>
Virtqueue data structure.
Data structure allocated (statically) per virtual queue.
Drivers may change qsize after a reset. When the guest OS requests a device reset, the hypervisor first calls vb->vo->reset(); then the data structure below is reinitialized (for each virtqueue: vb->vo->nvq).
The remaining fields should only be fussed-with by the generic code.
Note: the addresses of desc, avail, and vq_used are all computable from each other, but it’s a lot simpler if we just keep a pointer to each one. The event indices are similarly (but more easily) computable, and this time we’ll compute them: they’re just XX_ring[N].
-
VRING_PAGE_BITS¶