mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-09-16 22:39:29 +00:00
doc: update virtio related functions doc comments
Update some virtio, VBS-K, vhost APIs documents. Tracked-On: #1595 Signed-off-by: Shuo Liu <shuo.a.liu@intel.com>
This commit is contained in:
Shuo Liu
David Kinder
@@ -45,7 +45,17 @@ extern bool stdio_in_use;
|
||||
|
||||
int vmexit_task_switch(struct vmctx *ctx, struct vhm_request *vhm_req,
|
||||
int *vcpu);
|
||||
void *paddr_guest2host(struct vmctx *ctx, uintptr_t addr, size_t len);
|
||||
|
||||
/**
|
||||
* @brief Convert guest physical address to host virtual address
|
||||
*
|
||||
* @param ctx Pointer to to struct vmctx representing VM context.
|
||||
* @param gaddr Guest physical address base.
|
||||
* @param len Guest physical address length.
|
||||
*
|
||||
* @return NULL on convert failed and host virtual address on successful.
|
||||
*/
|
||||
void *paddr_guest2host(struct vmctx *ctx, uintptr_t gaddr, size_t len);
|
||||
int virtio_uses_msix(void);
|
||||
void ptdev_no_reset(bool enable);
|
||||
void init_debugexit(void);
|
||||
|
||||
@@ -252,10 +252,45 @@ int pci_emul_find_capability(struct pci_vdev *dev, uint8_t capid,
|
||||
int *p_capoff);
|
||||
int pci_emul_add_msicap(struct pci_vdev *pi, int msgnum);
|
||||
int pci_emul_add_pciecap(struct pci_vdev *pi, int pcie_device_type);
|
||||
void pci_generate_msi(struct pci_vdev *pi, int msgnum);
|
||||
void pci_generate_msix(struct pci_vdev *pi, int msgnum);
|
||||
void pci_lintr_assert(struct pci_vdev *pi);
|
||||
void pci_lintr_deassert(struct pci_vdev *pi);
|
||||
|
||||
/**
|
||||
* @brief Generate a MSI interrupt to guest
|
||||
*
|
||||
* @param dev Pointer to struct pci_vdev representing virtual PCI device.
|
||||
* @param index Message data index.
|
||||
*
|
||||
* @return N/A
|
||||
*/
|
||||
void pci_generate_msi(struct pci_vdev *dev, int index);
|
||||
|
||||
/**
|
||||
* @brief Generate a MSI-X interrupt to guest
|
||||
*
|
||||
* @param dev Pointer to struct pci_vdev representing virtual PCI device.
|
||||
* @param index MSIs table entry index.
|
||||
*
|
||||
* @return N/A
|
||||
*/
|
||||
void pci_generate_msix(struct pci_vdev *dev, int index);
|
||||
|
||||
/**
|
||||
* @brief Assert INTx pin of virtual PCI device
|
||||
*
|
||||
* @param dev Pointer to struct pci_vdev representing virtual PCI device.
|
||||
*
|
||||
* @return N/A
|
||||
*/
|
||||
void pci_lintr_assert(struct pci_vdev *dev);
|
||||
|
||||
/**
|
||||
* @brief Deassert INTx pin of virtual PCI device
|
||||
*
|
||||
* @param dev Pointer to struct pci_vdev representing virtual PCI device.
|
||||
*
|
||||
* @return N/A
|
||||
*/
|
||||
void pci_lintr_deassert(struct pci_vdev *dev);
|
||||
|
||||
void pci_lintr_request(struct pci_vdev *pi);
|
||||
void pci_lintr_release(struct pci_vdev *pi);
|
||||
int pci_msi_enabled(struct pci_vdev *pi);
|
||||
@@ -282,46 +317,97 @@ int check_gsi_sharing_violation(void);
|
||||
int pciaccess_init(void);
|
||||
void pciaccess_cleanup(void);
|
||||
|
||||
/**
|
||||
* @brief Set virtual PCI device's configuration space in 1 byte width
|
||||
*
|
||||
* @param dev Pointer to struct pci_vdev representing virtual PCI device.
|
||||
* @param offset Offset in configuration space.
|
||||
* @param val Value in 1 byte.
|
||||
*
|
||||
* @return N/A
|
||||
*/
|
||||
static inline void
|
||||
pci_set_cfgdata8(struct pci_vdev *pi, int offset, uint8_t val)
|
||||
pci_set_cfgdata8(struct pci_vdev *dev, int offset, uint8_t val)
|
||||
{
|
||||
assert(offset <= PCI_REGMAX);
|
||||
*(uint8_t *)(pi->cfgdata + offset) = val;
|
||||
*(uint8_t *)(dev->cfgdata + offset) = val;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Set virtual PCI device's configuration space in 2 bytes width
|
||||
*
|
||||
* @param dev Pointer to struct pci_vdev representing virtual PCI device.
|
||||
* @param offset Offset in configuration space.
|
||||
* @param val Value in 2 bytes.
|
||||
*
|
||||
* @return N/A
|
||||
*/
|
||||
static inline void
|
||||
pci_set_cfgdata16(struct pci_vdev *pi, int offset, uint16_t val)
|
||||
pci_set_cfgdata16(struct pci_vdev *dev, int offset, uint16_t val)
|
||||
{
|
||||
assert(offset <= (PCI_REGMAX - 1) && (offset & 1) == 0);
|
||||
*(uint16_t *)(pi->cfgdata + offset) = val;
|
||||
*(uint16_t *)(dev->cfgdata + offset) = val;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Set virtual PCI device's configuration space in 4 bytes width
|
||||
*
|
||||
* @param dev Pointer to struct pci_vdev representing virtual PCI device.
|
||||
* @param offset Offset in configuration space.
|
||||
* @param val Value in 4 bytes.
|
||||
*
|
||||
* @return N/A
|
||||
*/
|
||||
static inline void
|
||||
pci_set_cfgdata32(struct pci_vdev *pi, int offset, uint32_t val)
|
||||
pci_set_cfgdata32(struct pci_vdev *dev, int offset, uint32_t val)
|
||||
{
|
||||
assert(offset <= (PCI_REGMAX - 3) && (offset & 3) == 0);
|
||||
*(uint32_t *)(pi->cfgdata + offset) = val;
|
||||
*(uint32_t *)(dev->cfgdata + offset) = val;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Get virtual PCI device's configuration space in 1 byte width
|
||||
*
|
||||
* @param dev Pointer to struct pci_vdev representing virtual PCI device.
|
||||
* @param offset Offset in configuration space.
|
||||
*
|
||||
* @return The configuration value in 1 byte.
|
||||
*/
|
||||
static inline uint8_t
|
||||
pci_get_cfgdata8(struct pci_vdev *pi, int offset)
|
||||
pci_get_cfgdata8(struct pci_vdev *dev, int offset)
|
||||
{
|
||||
assert(offset <= PCI_REGMAX);
|
||||
return (*(uint8_t *)(pi->cfgdata + offset));
|
||||
return (*(uint8_t *)(dev->cfgdata + offset));
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Get virtual PCI device's configuration space in 2 byte width
|
||||
*
|
||||
* @param dev Pointer to struct pci_vdev representing virtual PCI device.
|
||||
* @param offset Offset in configuration space.
|
||||
*
|
||||
* @return The configuration value in 2 bytes.
|
||||
*/
|
||||
static inline uint16_t
|
||||
pci_get_cfgdata16(struct pci_vdev *pi, int offset)
|
||||
pci_get_cfgdata16(struct pci_vdev *dev, int offset)
|
||||
{
|
||||
assert(offset <= (PCI_REGMAX - 1) && (offset & 1) == 0);
|
||||
return (*(uint16_t *)(pi->cfgdata + offset));
|
||||
return (*(uint16_t *)(dev->cfgdata + offset));
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Get virtual PCI device's configuration space in 4 byte width
|
||||
*
|
||||
* @param dev Pointer to struct pci_vdev representing virtual PCI device.
|
||||
* @param offset Offset in configuration space.
|
||||
*
|
||||
* @return The configuration value in 4 bytes.
|
||||
*/
|
||||
static inline uint32_t
|
||||
pci_get_cfgdata32(struct pci_vdev *pi, int offset)
|
||||
pci_get_cfgdata32(struct pci_vdev *dev, int offset)
|
||||
{
|
||||
assert(offset <= (PCI_REGMAX - 3) && (offset & 3) == 0);
|
||||
return (*(uint32_t *)(pi->cfgdata + offset));
|
||||
return (*(uint32_t *)(dev->cfgdata + offset));
|
||||
}
|
||||
|
||||
#endif /* _PCI_CORE_H_ */
|
||||
|
||||
@@ -117,113 +117,117 @@
|
||||
#define IC_EVENT_IRQFD _IC_ID(IC_ID, IC_ID_EVENT_BASE + 0x01)
|
||||
|
||||
/**
|
||||
* struct vm_memmap - EPT memory mapping info for guest
|
||||
* @brief EPT memory mapping info for guest
|
||||
*/
|
||||
struct vm_memmap {
|
||||
/** @type: memory mapping type */
|
||||
/** memory mapping type */
|
||||
uint32_t type;
|
||||
/** @using_vma: using vma_base to get vm0_gpa,
|
||||
/** using vma_base to get vm0_gpa,
|
||||
* only for type == VM_MEMMAP_SYSMEM
|
||||
*/
|
||||
uint32_t using_vma;
|
||||
/** @gpa: user OS guest physical start address of memory mapping */
|
||||
/** user OS guest physical start address of memory mapping */
|
||||
uint64_t gpa;
|
||||
/** union */
|
||||
union {
|
||||
/** @hpa: host physical start address of memory,
|
||||
/** host physical start address of memory,
|
||||
* only for type == VM_MMIO
|
||||
*/
|
||||
uint64_t hpa;
|
||||
/** @vma_base: service OS user virtual start address of
|
||||
/** service OS user virtual start address of
|
||||
* memory, only for type == VM_MEMMAP_SYSMEM &&
|
||||
* using_vma == true
|
||||
*/
|
||||
uint64_t vma_base;
|
||||
};
|
||||
/** @len: the length of memory range mapped */
|
||||
/** the length of memory range mapped */
|
||||
uint64_t len; /* mmap length */
|
||||
/** @prot: memory mapping attribute */
|
||||
/** memory mapping attribute */
|
||||
uint32_t prot; /* RWX */
|
||||
};
|
||||
|
||||
/**
|
||||
* struct ic_ptdev_irq - pass thru device irq data structure
|
||||
* @brief pass thru device irq data structure
|
||||
*/
|
||||
struct ic_ptdev_irq {
|
||||
#define IRQ_INTX 0
|
||||
#define IRQ_MSI 1
|
||||
#define IRQ_MSIX 2
|
||||
/** @type: irq type */
|
||||
/** irq type */
|
||||
uint32_t type;
|
||||
/** @virt_bdf: virtual bdf description of pass thru device */
|
||||
/** virtual bdf description of pass thru device */
|
||||
uint16_t virt_bdf; /* IN: Device virtual BDF# */
|
||||
/** @phy_bdf: physical bdf description of pass thru device */
|
||||
/** physical bdf description of pass thru device */
|
||||
uint16_t phys_bdf; /* IN: Device physical BDF# */
|
||||
/** union */
|
||||
union {
|
||||
/** struct intx - info of IOAPIC/PIC interrupt */
|
||||
/** info of IOAPIC/PIC interrupt */
|
||||
struct {
|
||||
/** @virt_pin: virtual IOAPIC pin */
|
||||
/** virtual IOAPIC pin */
|
||||
uint32_t virt_pin;
|
||||
/** @phys_pin: physical IOAPIC pin */
|
||||
/** physical IOAPIC pin */
|
||||
uint32_t phys_pin;
|
||||
/** @pic_pin: PIC pin */
|
||||
/** PIC pin */
|
||||
uint32_t is_pic_pin;
|
||||
} intx;
|
||||
|
||||
/** struct msix - info of MSI/MSIX interrupt */
|
||||
/** info of MSI/MSIX interrupt */
|
||||
struct {
|
||||
/* Keep this filed on top of msix */
|
||||
/** @vector_cnt: vector count of MSI/MSIX */
|
||||
/** vector count of MSI/MSIX */
|
||||
uint32_t vector_cnt;
|
||||
|
||||
/** @table_size: size of MSIX table(round up to 4K) */
|
||||
/** size of MSIX table(round up to 4K) */
|
||||
uint32_t table_size;
|
||||
|
||||
/** @table_paddr: physical address of MSIX table */
|
||||
/** physical address of MSIX table */
|
||||
uint64_t table_paddr;
|
||||
} msix;
|
||||
};
|
||||
};
|
||||
|
||||
/**
|
||||
* struct ioreq_notify - data strcture to notify hypervisor ioreq is handled
|
||||
*
|
||||
* @client_id: client id to identify ioreq client
|
||||
* @vcpu: identify the ioreq submitter
|
||||
* @brief data strcture to notify hypervisor ioreq is handled
|
||||
*/
|
||||
struct ioreq_notify {
|
||||
int32_t client_id;
|
||||
uint32_t vcpu;
|
||||
/** client id to identify ioreq client */
|
||||
int32_t client_id;
|
||||
/** identify the ioreq submitter */
|
||||
uint32_t vcpu;
|
||||
};
|
||||
|
||||
/**
|
||||
* struct api_version - data structure to track VHM API version
|
||||
*
|
||||
* @major_version: major version of VHM API
|
||||
* @minor_version: minor version of VHM API
|
||||
* @brief data structure to track VHM API version
|
||||
*/
|
||||
struct api_version {
|
||||
/** major version of VHM API */
|
||||
uint32_t major_version;
|
||||
/** minor version of VHM API */
|
||||
uint32_t minor_version;
|
||||
};
|
||||
|
||||
struct acrn_ioeventfd {
|
||||
#define ACRN_IOEVENTFD_FLAG_PIO 0x01
|
||||
#define ACRN_IOEVENTFD_FLAG_DATAMATCH 0x02
|
||||
#define ACRN_IOEVENTFD_FLAG_DEASSIGN 0x04
|
||||
struct acrn_ioeventfd {
|
||||
/** file descriptor of the eventfd of this ioeventfd */
|
||||
int32_t fd;
|
||||
/** flag for ioeventfd ioctl */
|
||||
uint32_t flags;
|
||||
/** base address to be monitored */
|
||||
uint64_t addr;
|
||||
/** address length */
|
||||
uint32_t len;
|
||||
uint32_t reserved;
|
||||
/** data to be matched */
|
||||
uint64_t data;
|
||||
};
|
||||
|
||||
#define ACRN_IRQFD_FLAG_DEASSIGN 0x01
|
||||
struct acrn_irqfd {
|
||||
#define ACRN_IRQFD_FLAG_DEASSIGN 0x01
|
||||
/** file descriptor of the eventfd of this irqfd */
|
||||
int32_t fd;
|
||||
/** flag for irqfd ioctl */
|
||||
uint32_t flags;
|
||||
/** MSI interrupt to be injected */
|
||||
struct acrn_msi_entry msi;
|
||||
};
|
||||
#endif /* VHM_IOCTL_DEFS_H */
|
||||
|
||||
@@ -5,12 +5,25 @@
|
||||
*
|
||||
*/
|
||||
|
||||
/**
|
||||
* @file vhost.h
|
||||
*
|
||||
* @brief VHOST APIs for ACRN Project
|
||||
*/
|
||||
|
||||
#ifndef __VHOST_H__
|
||||
#define __VHOST_H__
|
||||
|
||||
#include "virtio.h"
|
||||
#include "mevent.h"
|
||||
|
||||
/**
|
||||
* @brief vhost APIs
|
||||
*
|
||||
* @addtogroup acrn_virtio
|
||||
* @{
|
||||
*/
|
||||
|
||||
struct vhost_vq {
|
||||
int kick_fd; /**< fd of kick eventfd */
|
||||
int call_fd; /**< fd of call eventfd */
|
||||
@@ -71,7 +84,7 @@ struct vhost_dev {
|
||||
* @brief vhost_dev initialization.
|
||||
*
|
||||
* This interface is called to initialize the vhost_dev. It must be called
|
||||
* before the actual feature negoitiation with the guest OS starts.
|
||||
* before the actual feature negotiation with the guest OS starts.
|
||||
*
|
||||
* @param vdev Pointer to struct vhost_dev.
|
||||
* @param base Pointer to struct virtio_base.
|
||||
@@ -133,4 +146,7 @@ int vhost_dev_stop(struct vhost_dev *vdev);
|
||||
*/
|
||||
int vhost_net_set_backend(struct vhost_dev *vdev, int backend_fd);
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
#endif
|
||||
|
||||
@@ -698,15 +698,15 @@ struct iovec;
|
||||
* @brief Link a virtio_base to its constants, the virtio device,
|
||||
* and the PCI emulation.
|
||||
*
|
||||
* @param vb Pointer to struct virtio_base.
|
||||
* @param vo Pointer to struct virtio_ops.
|
||||
* @param base Pointer to struct virtio_base.
|
||||
* @param vops Pointer to struct virtio_ops.
|
||||
* @param pci_virtio_dev Pointer to instance of certain virtio device.
|
||||
* @param dev Pointer to struct pci_vdev which emulates a PCI device.
|
||||
* @param queues Pointer to struct virtio_vq_info, normally an array.
|
||||
*
|
||||
* @return NULL
|
||||
*/
|
||||
void virtio_linkup(struct virtio_base *vb, struct virtio_ops *vo,
|
||||
void virtio_linkup(struct virtio_base *base, struct virtio_ops *vops,
|
||||
void *pci_virtio_dev, struct pci_vdev *dev,
|
||||
struct virtio_vq_info *queues);
|
||||
|
||||
@@ -717,24 +717,27 @@ void virtio_linkup(struct virtio_base *vb, struct virtio_ops *vo,
|
||||
* Wrapper function for virtio_intr_init() for cases we directly use
|
||||
* BAR 1 for MSI-X capabilities.
|
||||
*
|
||||
* @param vb Pointer to struct virtio_base.
|
||||
* @param base Pointer to struct virtio_base.
|
||||
* @param use_msix If using MSI-X.
|
||||
*
|
||||
* @return 0 on success and non-zero on fail.
|
||||
*/
|
||||
int virtio_interrupt_init(struct virtio_base *vb, int use_msix);
|
||||
int virtio_interrupt_init(struct virtio_base *base, int use_msix);
|
||||
|
||||
/**
|
||||
* @brief Initialize MSI-X vector capabilities if we're to use MSI-X,
|
||||
* or MSI capabilities if not.
|
||||
*
|
||||
* @param vb Pointer to struct virtio_base.
|
||||
* We assume we want one MSI-X vector per queue, here, plus one
|
||||
* for the config vec.
|
||||
*
|
||||
* @param base Pointer to struct virtio_base.
|
||||
* @param barnum Which BAR[0..5] to use.
|
||||
* @param use_msix If using MSI-X.
|
||||
*
|
||||
* @return 0 on success and non-zero on fail.
|
||||
*/
|
||||
int virtio_intr_init(struct virtio_base *vb, int barnum, int use_msix);
|
||||
int virtio_intr_init(struct virtio_base *base, int barnum, int use_msix);
|
||||
|
||||
/**
|
||||
* @brief Reset device (device-wide).
|
||||
@@ -743,21 +746,24 @@ int virtio_intr_init(struct virtio_base *vb, int barnum, int use_msix);
|
||||
* But we don't wipe out the internal pointers, by just clearing
|
||||
* the VQ_ALLOC flag.
|
||||
*
|
||||
* @param vb Pointer to struct virtio_base.
|
||||
* It resets negotiated features to "none".
|
||||
* If MSI-X is enabled, this also resets all the vectors to NO_VECTOR.
|
||||
*
|
||||
* @param base Pointer to struct virtio_base.
|
||||
*
|
||||
* @return N/A
|
||||
*/
|
||||
void virtio_reset_dev(struct virtio_base *vb);
|
||||
void virtio_reset_dev(struct virtio_base *base);
|
||||
|
||||
/**
|
||||
* @brief Set I/O BAR (usually 0) to map PCI config registers.
|
||||
*
|
||||
* @param vb Pointer to struct virtio_base.
|
||||
* @param base Pointer to struct virtio_base.
|
||||
* @param barnum Which BAR[0..5] to use.
|
||||
*
|
||||
* @return N/A
|
||||
*/
|
||||
void virtio_set_io_bar(struct virtio_base *vb, int barnum);
|
||||
void virtio_set_io_bar(struct virtio_base *base, int barnum);
|
||||
|
||||
/**
|
||||
* @brief Walk through the chain of descriptors involved in a request
|
||||
|
||||
@@ -12,6 +12,13 @@
|
||||
|
||||
#include "vbs_common_if.h" /* data format between VBS-U & VBS-K */
|
||||
|
||||
/**
|
||||
* @brief APIs for virtio backend in kernel module
|
||||
*
|
||||
* @addtogroup acrn_virtio
|
||||
* @{
|
||||
*/
|
||||
|
||||
enum VBS_K_STATUS {
|
||||
VIRTIO_DEV_INITIAL = 1, /* initial status */
|
||||
VIRTIO_DEV_PRE_INIT, /* detected thru cmdline option */
|
||||
@@ -30,12 +37,37 @@ enum VBS_K_STATUS {
|
||||
#define VIRTIO_ERROR_GENERAL 5
|
||||
|
||||
/* VBS-K common ops */
|
||||
/* VBS-K reset*/
|
||||
/**
|
||||
* @brief Virtio kernel module reset.
|
||||
*
|
||||
* @param fd File descriptor representing virtio backend in kernel module.
|
||||
*
|
||||
* @return 0 on OK and non-zero on error.
|
||||
*/
|
||||
int vbs_kernel_reset(int fd);
|
||||
|
||||
/* VBS-K start/stop */
|
||||
/**
|
||||
* @brief Virtio kernel module start.
|
||||
*
|
||||
* @param fd File descriptor representing virtio backend in kernel module.
|
||||
* @param dev Pointer to struct vbs_dev_info.
|
||||
* @param vqs Pointer to struct vbs_vqs_info.
|
||||
*
|
||||
* @return 0 on OK and non-zero on error.
|
||||
*/
|
||||
int vbs_kernel_start(int fd, struct vbs_dev_info *dev,
|
||||
struct vbs_vqs_info *vqs);
|
||||
|
||||
/**
|
||||
* @brief Virtio kernel module stop.
|
||||
*
|
||||
* @param fd File descriptor representing virtio backend in kernel module.
|
||||
*
|
||||
* @return 0 on OK and non-zero on error.
|
||||
*/
|
||||
int vbs_kernel_stop(int fd);
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
#endif
|
||||
|
||||
Reference in New Issue
Block a user