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
INTEL_VENDOR_ID
ORACLE_VENDOR_ID
VIRTIO_VENDOR
VIRTIO_DEV_NET
VIRTIO_DEV_BLOCK
VIRTIO_DEV_CONSOLE
VIRTIO_DEV_RANDOM
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

enum [anonymous]

Values:

enumerator BACKEND_UNKNOWN
enumerator BACKEND_VBSU
enumerator BACKEND_VBSK
enumerator BACKEND_VHOST
enumerator BACKEND_MAX
enum VBS_K_STATUS

Values:

enumerator VIRTIO_DEV_INITIAL
enumerator VIRTIO_DEV_PRE_INIT
enumerator VIRTIO_DEV_INIT_FAILED
enumerator VIRTIO_DEV_INIT_SUCCESS
enumerator VIRTIO_DEV_START_FAILED
enumerator VIRTIO_DEV_STARTED

Functions

bool vq_ring_ready(struct virtio_vq_info *vq)

Is this ring ready for I/O?

Return

false on not ready and true on ready.

Parameters

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.

Return

false on not available and true on available.

Parameters

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.

Return

None

Parameters

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.

Return

None

Parameters

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.

Return

None

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

int acrn_parse_virtio_poll_interval(const char *optarg)

Get the virtio poll parameters.

Return

fail -1 success 0

Parameters

  • optarg: Pointer to parameters string.

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.

Return

0 on success and non-zero on fail.

Parameters

  • base: Pointer to struct virtio_base.

  • use_msix: If using MSI-X.

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.

Return

0 on success and non-zero on fail.

Parameters

  • base: Pointer to struct virtio_base.

  • barnum: Which BAR[0..5] to use.

  • use_msix: If using MSI-X.

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.

Return

None

Parameters

void virtio_set_io_bar(struct virtio_base *base, int barnum)

Set I/O BAR (usually 0) to map PCI config registers.

Return

None

Parameters

  • base: Pointer to struct virtio_base.

  • barnum: Which BAR[0..5] to use.

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.

Return

number of descriptors.

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.

void vq_retchain(struct virtio_vq_info *vq)

Return the currently-first request chain back to the available ring.

Return

None

Parameters

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.

Return

None

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.

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.

Return

None

Parameters

  • vq: Pointer to struct virtio_vq_info.

  • used_all_avail: Flag indicating if driver used all available chains.

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.

Return

None

Parameters

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.

Return

register value.

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.

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.

Return

None

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.

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.

Return

0 on success and non-zero on fail.

Parameters

  • base: Pointer to struct virtio_base.

  • use_notify_pio: Whether use pio for notify capability.

int vbs_kernel_reset(int fd)

Virtio kernel module reset.

Return

0 on OK and non-zero on error.

Parameters

  • fd: File descriptor representing virtio backend in kernel module.

int vbs_kernel_start(int fd, struct vbs_dev_info *dev, struct vbs_vqs_info *vqs)

Virtio kernel module start.

Return

0 on OK and non-zero on error.

Parameters

  • fd: File descriptor representing virtio backend in kernel module.

  • dev: Pointer to struct vbs_dev_info.

  • vqs: Pointer to struct vbs_vqs_info.

int vbs_kernel_stop(int fd)

Virtio kernel module stop.

Return

0 on OK and non-zero on error.

Parameters

  • fd: File descriptor representing virtio backend in kernel module.

int vhost_dev_init(struct vhost_dev *vdev, struct virtio_base *base, int fd, int vq_idx, uint64_t vhost_features, uint64_t vhost_ext_features, uint32_t busyloop_timeout)

vhost_dev initialization.

This interface is called to initialize the vhost_dev. It must be called before the actual feature negotiation with the guest OS starts.

Return

0 on success and -1 on failure.

Parameters

  • vdev: Pointer to struct vhost_dev.

  • base: Pointer to struct virtio_base.

  • fd: fd of the vhost chardev.

  • vq_idx: The first virtqueue which would be used by this vhost dev.

  • vhost_features: Subset of vhost features which would be enabled.

  • vhost_ext_features: Specific vhost internal features to be enabled.

  • busyloop_timeout: Busy loop timeout in us.

int vhost_dev_deinit(struct vhost_dev *vdev)

vhost_dev cleanup.

This interface is called to cleanup the vhost_dev.

Return

0 on success and -1 on failure.

Parameters

int vhost_dev_start(struct vhost_dev *vdev)

start vhost data plane.

This interface is called to start the data plane in vhost.

Return

0 on success and -1 on failure.

Parameters

int vhost_dev_stop(struct vhost_dev *vdev)

stop vhost data plane.

This interface is called to stop the data plane in vhost.

Return

0 on success and -1 on failure.

Parameters

int vhost_net_set_backend(struct vhost_dev *vdev, int backend_fd)

set backend fd of vhost net.

This interface is called to set the backend fd (for example tap fd) to vhost.

Return

0 on success and -1 on failure.

Parameters

  • vdev: Pointer to struct vhost_dev.

  • backend_fd: fd of backend (for example tap fd).

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].

struct vhost_vq
#include <vhost.h>
struct vhost_dev
#include <vhost.h>