Changeset 80639 in vbox for trunk/src/VBox/Devices/VirtIO

Timestamp:

Sep 6, 2019 5:41:59 PM (5 years ago)

Author:

vboxsync

Message:

Storage/DevVirtioSCSI.cpp: Start to fix/implement ejection notification. Improve interface header file API comments.

Location:

trunk/src/VBox/Devices/VirtIO

Files:

• Virtio_1_0.cpp (modified) (1 diff)
• Virtio_1_0.h (modified) (4 diffs)

trunk/src/VBox/Devices/VirtIO/Virtio_1_0.cpp

@@ -35 +35 @@
 #define INSTANCE(pVirtio) pVirtio->szInstance
 #define QUEUENAME(qIdx) (pVirtio->virtqProxy[qIdx].szVirtqName)
-#define CBQUEUENAME(qIdx) RTStrNLen(QUEUENAME(qIdx), sizeof(QUEUENAME(qIdx)))
-/**
-
+
+/**
  * Formats the logging of a memory-mapped I/O input or output value
  *

trunk/src/VBox/Devices/VirtIO/Virtio_1_0.h

@@ -185 +185 @@
 
 /**
- * Removes descriptor [chain] from queue and converts it to scatter/gather data
- * in the vector whose pointer was returned from VirtioQueueAttach.
+ * Removes descriptor chain from avail ring of indicated queue and converts it to
+ * scatter/gather buffer (whose segments contain guest phys. data pointers)
  *
  * @param hVirtio   - Handle for VirtIO framework
@@ -213 +213 @@
 
 /**
- * Writes scatter/gather segment contained in queue's bufVec.aSegsIn[] array to
- * physical memory assigned by the guest driver. The data won't be seen by the
- * driver until the next virtioQueueSync() call.
+ * Writes a scatter/gather buffer (whose segments point to virtual memory) to next
+ * available descriptor chain (consisting of segments pointing to guest phys. memory),
+ * for the indicated virtq. The data won't be seen by the guest until the next
+ * client call to virtioQueueSync(), which puts aforementioned descriptor
+ * chain's head index on the indicated virtq's used ring (see VirtIO 1.0
+ * specification, Section 2.4 "Virtqueues").
  *
  * @param hVirtio   - Handle for VirtIO framework
@@ -233 +236 @@
 
 /**
- * Updates virtq's "used ring" descriptor index to match the current bufVec's
- * index, thus exposing the data added to the used ring by all virtioQueuePut()
- * calls since the last sync. This should be called after one or more virtQueuePut()
- * calls to inform the guest driver there is data in the queue. Explicit
- * notifications will be sent to the guest depending on VirtIO features negotiated
- * and conditions.
+ * Updates the indicated virtq's "used ring" descriptor index to match the
+ * current write-head index, thus exposing the data added to the used ring by all
+ * virtioQueuePut() calls since the last sync. This should be called after one or
+ * more virtQueuePut() calls to inform the guest driver there is data in the queue.
+ * Explicit notifications (e.g. interrupt or MSI-X) will be sent to the guest,
+ * depending on VirtIO features negotiated and conditions, otherwise the guest
+ * will detect the update by polling. (see VirtIO 1.0
+ * specification, Section 2.4 "Virtqueues").
  *
  * @param hVirtio   - Handle for VirtIO framework
@@ -306 +311 @@
 /**
  * Log memory-mapped I/O input or output value.
+ *
  * This is designed to be invoked by macros that can make contextual assumptions
- * (e.g. implicitly derive some of the parameters). It is exposed for the VirtIO
- * client doing the device-specific implementation in order to log in a similar fashion
- * accesses to the device-specific MMIO configuration structure. Macros that leverage
- * this function are in Virtio_1_0_impl.h and can be used as an example of how to use
- * this effectively for the device-specific code.
+ * (e.g. implicitly derive MACRO parameters from the invoking function). It is exposed
+ * for the VirtIO client doing the device-specific implementation in order to log in a
+ * similar fashion accesses to the device-specific MMIO configuration structure. Macros
+ * that leverage this function are in Virtio_1_0_impl.h and can be used as an example
+ * of how to use this effectively for the device-specific code.
  *
  * @param   pszFunc     - To avoid displaying this function's name via __FUNCTION__ or LogFunc()