[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 25/41] include/hw: attempt to document VirtIO feature variables
From: |
Michael S. Tsirkin |
Subject: |
[PULL 25/41] include/hw: attempt to document VirtIO feature variables |
Date: |
Wed, 21 Dec 2022 08:05:50 -0500 |
From: Alex Bennée <alex.bennee@linaro.org>
We have a bunch of variables associated with the device and the vhost
backend which are used inconsistently throughout the code base. Lets
start trying to bring some order by agreeing what each variable is
for.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Stefano Garzarella <sgarzare@redhat.com>
Cc: "Michael S. Tsirkin" <mst@redhat.com>
Cc: Stefan Hajnoczi <stefanha@gmail.com>
Message-Id: <20221123152134.179929-2-alex.bennee@linaro.org>
Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
include/hw/virtio/vhost.h | 25 ++++++++++++++++++++++---
include/hw/virtio/virtio.h | 19 ++++++++++++++++++-
2 files changed, 40 insertions(+), 4 deletions(-)
diff --git a/include/hw/virtio/vhost.h b/include/hw/virtio/vhost.h
index 67a6807fac..1cafa0d776 100644
--- a/include/hw/virtio/vhost.h
+++ b/include/hw/virtio/vhost.h
@@ -88,13 +88,32 @@ struct vhost_dev {
int vq_index_end;
/* if non-zero, minimum required value for max_queues */
int num_queues;
+ /**
+ * vhost feature handling requires matching the feature set
+ * offered by a backend which may be a subset of the total
+ * features eventually offered to the guest.
+ *
+ * @features: available features provided by the backend
+ * @acked_features: final negotiated features with front-end driver
+ *
+ * @backend_features: this is used in a couple of places to either
+ * store VHOST_USER_F_PROTOCOL_FEATURES to apply to
+ * VHOST_USER_SET_FEATURES or VHOST_NET_F_VIRTIO_NET_HDR. Its
+ * future use should be discouraged and the variable retired as
+ * its easy to confuse with the VirtIO backend_features.
+ */
uint64_t features;
- /** @acked_features: final set of negotiated features */
uint64_t acked_features;
- /** @backend_features: backend specific feature bits */
uint64_t backend_features;
- /** @protocol_features: final negotiated protocol features */
+
+ /**
+ * @protocol_features: is the vhost-user only feature set by
+ * VHOST_USER_SET_PROTOCOL_FEATURES. Protocol features are only
+ * negotiated if VHOST_USER_F_PROTOCOL_FEATURES has been offered
+ * by the backend (see @features).
+ */
uint64_t protocol_features;
+
uint64_t max_queues;
uint64_t backend_cap;
/* @started: is the vhost device started? */
diff --git a/include/hw/virtio/virtio.h b/include/hw/virtio/virtio.h
index acfd4df125..24561e933a 100644
--- a/include/hw/virtio/virtio.h
+++ b/include/hw/virtio/virtio.h
@@ -93,6 +93,12 @@ enum virtio_device_endian {
VIRTIO_DEVICE_ENDIAN_BIG,
};
+/**
+ * struct VirtIODevice - common VirtIO structure
+ * @name: name of the device
+ * @status: VirtIO Device Status field
+ *
+ */
struct VirtIODevice
{
DeviceState parent_obj;
@@ -100,9 +106,20 @@ struct VirtIODevice
uint8_t status;
uint8_t isr;
uint16_t queue_sel;
- uint64_t guest_features;
+ /**
+ * These fields represent a set of VirtIO features at various
+ * levels of the stack. @host_features indicates the complete
+ * feature set the VirtIO device can offer to the driver.
+ * @guest_features indicates which features the VirtIO driver has
+ * selected by writing to the feature register. Finally
+ * @backend_features represents everything supported by the
+ * backend (e.g. vhost) and could potentially be a subset of the
+ * total feature set offered by QEMU.
+ */
uint64_t host_features;
+ uint64_t guest_features;
uint64_t backend_features;
+
size_t config_len;
void *config;
uint16_t config_vector;
--
MST
- [PULL 10/41] vdpa: add vdpa-dev-pci support, (continued)
- [PULL 10/41] vdpa: add vdpa-dev-pci support, Michael S. Tsirkin, 2022/12/21
- [PULL 15/41] vhost: move iova_tree set to vhost_svq_start, Michael S. Tsirkin, 2022/12/21
- [PULL 16/41] vdpa: add vhost_vdpa_net_valid_svq_features, Michael S. Tsirkin, 2022/12/21
- [PULL 17/41] vdpa: request iova_range only once, Michael S. Tsirkin, 2022/12/21
- [PULL 18/41] vdpa: move SVQ vring features check to net/, Michael S. Tsirkin, 2022/12/21
- [PULL 20/41] vdpa: add asid parameter to vhost_vdpa_dma_map/unmap, Michael S. Tsirkin, 2022/12/21
- [PULL 24/41] vhost-user: send set log base message only once, Michael S. Tsirkin, 2022/12/21
- [PULL 26/41] acpi/tests/avocado/bits: add SPDX license identifiers for bios bits tests, Michael S. Tsirkin, 2022/12/21
- [PULL 21/41] vdpa: store x-svq parameter in VhostVDPAState, Michael S. Tsirkin, 2022/12/21
- [PULL 22/41] vdpa: add shadow_data to vhost_vdpa, Michael S. Tsirkin, 2022/12/21
- [PULL 25/41] include/hw: attempt to document VirtIO feature variables,
Michael S. Tsirkin <=
- [PULL 23/41] vdpa: always start CVQ in SVQ mode if possible, Michael S. Tsirkin, 2022/12/21
- [PULL 19/41] vdpa: allocate SVQ array unconditionally, Michael S. Tsirkin, 2022/12/21
- [PULL 27/41] vhost: fix vq dirty bitmap syncing when vIOMMU is enabled, Michael S. Tsirkin, 2022/12/21
- [PULL 29/41] pci: drop redundant PCIDeviceClass::is_bridge field, Michael S. Tsirkin, 2022/12/21
- [PULL 30/41] docs/acpi/bits: document BITS_DEBUG environment variable, Michael S. Tsirkin, 2022/12/21
- [PULL 34/41] hw/virtio: Add missing "hw/core/cpu.h" include, Michael S. Tsirkin, 2022/12/21
- [PULL 28/41] remove DEC 21154 PCI bridge, Michael S. Tsirkin, 2022/12/21
- [PULL 33/41] hw/cxl/device: Add Flex Bus Port DVSEC, Michael S. Tsirkin, 2022/12/21
- [PULL 31/41] acpi/tests/avocado/bits: add mformat as one of the dependencies, Michael S. Tsirkin, 2022/12/21
- [PULL 32/41] hw/acpi: Rename tco.c -> ich9_tco.c, Michael S. Tsirkin, 2022/12/21