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>

devicemodel/hw/pci/virtio/vhost.c

@@ -581,6 +581,22 @@ vhost_set_mem_table(struct vhost_dev *vdev)
 	return 0;
 }
 
+/**
+ * @brief 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.
+ *
+ * @param vdev Pointer to struct vhost_dev.
+ * @param base Pointer to struct virtio_base.
+ * @param fd fd of the vhost chardev.
+ * @param vq_idx The first virtqueue which would be used by this vhost dev.
+ * @param vhost_features Subset of vhost features which would be enabled.
+ * @param vhost_ext_features Specific vhost internal features to be enabled.
+ * @param busyloop_timeout Busy loop timeout in us.
+ *
+ * @return 0 on success and -1 on failure.
+ */
 int
 vhost_dev_init(struct vhost_dev *vdev,
 	       struct virtio_base *base,
@@ -645,6 +661,15 @@ fail:
 	return -1;
 }
 
+/**
+ * @brief vhost_dev cleanup.
+ *
+ * This interface is called to cleanup the vhost_dev.
+ *
+ * @param vdev Pointer to struct vhost_dev.
+ *
+ * @return 0 on success and -1 on failure.
+ */
 int
 vhost_dev_deinit(struct vhost_dev *vdev)
 {
@@ -661,6 +686,15 @@ vhost_dev_deinit(struct vhost_dev *vdev)
 	return 0;
 }
 
+/**
+ * @brief start vhost data plane.
+ *
+ * This interface is called to start the data plane in vhost.
+ *
+ * @param vdev Pointer to struct vhost_dev.
+ *
+ * @return 0 on success and -1 on failure.
+ */
 int
 vhost_dev_start(struct vhost_dev *vdev)
 {
@@ -736,6 +770,15 @@ fail:
 	return -1;
 }
 
+/**
+ * @brief stop vhost data plane.
+ *
+ * This interface is called to stop the data plane in vhost.
+ *
+ * @param vdev Pointer to struct vhost_dev.
+ *
+ * @return 0 on success and -1 on failure.
+ */
 int
 vhost_dev_stop(struct vhost_dev *vdev)
 {
@@ -758,6 +801,17 @@ vhost_dev_stop(struct vhost_dev *vdev)
 	return rc;
 }
 
+/**
+ * @brief set backend fd of vhost net.
+ *
+ * This interface is called to set the backend fd (for example tap fd)
+ * to vhost.
+ *
+ * @param vdev Pointer to struct vhost_dev.
+ * @param backend_fd fd of backend (for example tap fd).
+ *
+ * @return 0 on success and -1 on failure.
+ */
 int
 vhost_net_set_backend(struct vhost_dev *vdev, int backend_fd)
 {

devicemodel/hw/pci/virtio/virtio.c

@@ -45,9 +45,17 @@
  */
 #define DEV_STRUCT(vs) ((void *)(vs))
 
-/*
- * Link a virtio_base to its constants, the virtio device, and
- * the PCI emulation.
+/**
+ * @brief Link a virtio_base to its constants, the virtio device,
+ * and the PCI emulation.
+ *
+ * @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 *base, struct virtio_ops *vops,
@@ -69,14 +77,19 @@ virtio_linkup(struct virtio_base *base, struct virtio_ops *vops,
 	}
 }
 
-/*
- * Reset device (device-wide).  This erases all queues, i.e.,
- * all the queues become invalid (though we don't wipe out the
- * internal pointers, we just clear the VQ_ALLOC flag).
+/**
+ * @brief 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.
+ *
+ * @param base Pointer to struct virtio_base.
+ *
+ * @return N/A
  */
 void
 virtio_reset_dev(struct virtio_base *base)
@@ -114,8 +127,13 @@ virtio_reset_dev(struct virtio_base *base)
 	base->config_generation = 0;
 }
 
-/*
- * Set I/O BAR (usually 0) to map PCI config registers.
+/**
+ * @brief Set I/O BAR (usually 0) to map PCI config registers.
+ *
+ * @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 *base, int barnum)
@@ -131,12 +149,19 @@ virtio_set_io_bar(struct virtio_base *base, int barnum)
 	base->legacy_pio_bar_idx = barnum;
 }
 
-/*
- * Initialize MSI-X vector capabilities if we're to use MSI-X,
+/**
+ * @brief 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.
+ *
+ *
+ * @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 *base, int barnum, int use_msix)
@@ -163,12 +188,17 @@ virtio_intr_init(struct virtio_base *base, int barnum, int use_msix)
 	return 0;
 }
 
-/*
- * Initialize MSI-X vector capabilities if we're to use MSI-X,
+/**
+ * @brief Initialize MSI-X vector capabilities if we're to use MSI-X,
  * or MSI capabilities if not.
  *
- * Wrapper function for virtio_intr_init() since by default we
- * will use bar 1 for MSI-X.
+ * Wrapper function for virtio_intr_init() for cases we directly use
+ * BAR 1 for MSI-X capabilities.
+ *
+ * @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 *base, int use_msix)
@@ -1006,6 +1036,18 @@ virtio_set_modern_pio_bar(struct virtio_base *base, int barnum)
 	return 0;
 }
 
+/**
+ * @brief 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.
+ *
+ * @param base Pointer to struct virtio_base.
+ * @param use_notify_pio Whether use pio for notify capability.
+ *
+ * @return 0 on success and non-zero on fail.
+ */
 int
 virtio_set_modern_bar(struct virtio_base *base, bool use_notify_pio)
 {
@@ -1027,6 +1069,17 @@ virtio_set_modern_bar(struct virtio_base *base, bool use_notify_pio)
 	return rc;
 }
 
+/**
+ * @brief Indicate the device has experienced an error.
+ *
+ * This is called when the device has experienced an error from which it
+ * cannot re-cover. DEVICE_NEEDS_RESET is set to the device status register
+ * and a config change intr is sent to the guest driver.
+ *
+ * @param base Pointer to struct virtio_base.
+ *
+ * @return N/A
+ */
 void
 virtio_dev_error(struct virtio_base *base)
 {
@@ -1604,6 +1657,21 @@ virtio_pci_modern_pio_write(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 		pthread_mutex_unlock(base->mtx);
 }
 
+/**
+ * @brief Handle PCI configuration space reads.
+ *
+ * Handle virtio standard register reads, and dispatch other reads to
+ * actual virtio device driver.
+ *
+ * @param ctx Pointer to struct vmctx representing VM context.
+ * @param vcpu VCPU ID.
+ * @param dev Pointer to struct pci_vdev which emulates a PCI device.
+ * @param baridx Which BAR[0..5] to use.
+ * @param offset Register offset in bytes within a BAR region.
+ * @param size Access range in bytes.
+ *
+ * @return register value.
+ */
 uint64_t
 virtio_pci_read(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 		int baridx, uint64_t offset, int size)
@@ -1634,6 +1702,22 @@ virtio_pci_read(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 	return size == 1 ? 0xff : size == 2 ? 0xffff : 0xffffffff;
 }
 
+/**
+ * @brief Handle PCI configuration space writes.
+ *
+ * Handle virtio standard register writes, and dispatch other writes to
+ * actual virtio device driver.
+ *
+ * @param ctx Pointer to struct vmctx representing VM context.
+ * @param vcpu VCPU ID.
+ * @param dev Pointer to struct pci_vdev which emulates a PCI device.
+ * @param baridx Which BAR[0..5] to use.
+ * @param offset Register offset in bytes within a BAR region.
+ * @param size Access range in bytes.
+ * @param value Data value to be written into register.
+ *
+ * @return N/A
+ */
 void
 virtio_pci_write(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 		 int baridx, uint64_t offset, int size, uint64_t value)
@@ -1670,6 +1754,22 @@ virtio_pci_write(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 		base->vops->name, baridx);
 }
 
+/**
+ * @brief Handle PCI configuration space reads.
+ *
+ * Handle virtio PCI configuration space reads. Only the specific registers
+ * that need speical operation are handled in this callback. For others just
+ * fallback to pci core. This interface is only valid for virtio modern.
+ *
+ * @param ctx Pointer to struct vmctx representing VM context.
+ * @param vcpu VCPU ID.
+ * @param dev Pointer to struct pci_vdev which emulates a PCI device.
+ * @param coff Register offset in bytes within PCI configuration space.
+ * @param bytes Access range in bytes.
+ * @param rv The value returned as read.
+ *
+ * @return 0 on handled and non-zero on non-handled.
+ */
 int
 virtio_pci_modern_cfgread(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 			  int coff, int bytes, uint32_t *rv)
@@ -1719,6 +1819,22 @@ virtio_pci_modern_cfgread(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 	return -1;
 }
 
+/**
+ * @brief Handle PCI configuration space writes.
+ *
+ * Handle virtio PCI configuration space writes. Only the specific registers
+ * that need speical operation are handled in this callback. For others just
+ * fallback to pci core. This interface is only valid for virtio modern.
+ *
+ * @param ctx Pointer to struct vmctx representing VM context.
+ * @param vcpu VCPU ID.
+ * @param dev Pointer to struct pci_vdev which emulates a PCI device.
+ * @param coff Register offset in bytes within PCI configuration space.
+ * @param bytes Access range in bytes.
+ * @param val The value to write.
+ *
+ * @return 0 on handled and non-zero on non-handled.
+ */
 int
 virtio_pci_modern_cfgwrite(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 			   int coff, int bytes, uint32_t val)

devicemodel/hw/pci/virtio/virtio_kernel.c

@@ -28,7 +28,13 @@ vbs_vqs_info_set(int fd, void *arg)
 }
 
 /* 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)
 {
@@ -40,7 +46,15 @@ vbs_kernel_reset(int fd)
  * change the configuration of the virtio device after VBS-K has been
  * initialized.
  */
-/* 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)
 {
@@ -66,6 +80,13 @@ vbs_kernel_start(int fd, struct vbs_dev_info *dev, struct vbs_vqs_info *vqs)
 	return VIRTIO_SUCCESS;
 }
 
+/**
+ * @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)
 {