Changeset 84819 in vbox for trunk

Timestamp:

Jun 12, 2020 8:00:27 PM (5 years ago)

Author:

vboxsync

Message:

Virtio/VirtioCore.cpp, Network/DevVirtioNet_1_0.cpp, Storage/DevVirtioSCSI.cpp: Renamed Virtio_1_0.cpp/h to VirtioCore.cpp/h to be consistent with bird's extraction of the common Virtio code to VIRTIOCORE. Further improved the API function names and comments, and changed key variables to simplify things and more clearly reflect their relationship to VirtIO architecture. For example PVIRTIO_DESC_CHAIN_T pDescChain becomes PVIRTQBUF pVirtqBuf and added comments above the VIRTQBUF typedef to explain what's going on. Moved all the API function descriptions into the header file.

Location:

trunk/src/VBox/Devices

Files:

• Makefile.kmk (modified) (3 diffs)
• Network/DevVirtioNet_1_0.cpp (modified) (53 diffs)
• Storage/DevVirtioSCSI.cpp (modified) (62 diffs)
• VirtIO/VirtioCore.cpp (moved) (moved from trunk/src/VBox/Devices/VirtIO/Virtio_1_0.cpp ) (45 diffs)
• VirtIO/VirtioCore.h (moved) (moved from trunk/src/VBox/Devices/VirtIO/Virtio_1_0.h ) (12 diffs)

trunk/src/VBox/Devices/Makefile.kmk

@@ -481 +481 @@
   VBoxDD_SOURCES        += \
         VirtIO/Virtio.cpp \
-        VirtIO/Virtio_1_0.cpp \
+        VirtIO/VirtioCore.cpp \
         Network/DevVirtioNet.cpp
  endif
@@ -970 +970 @@
    VBoxDDRC_SOURCES     += \
         VirtIO/Virtio.cpp \
-        VirtIO/Virtio_1_0.cpp \
+        VirtIO/VirtioCore.cpp \
         Network/DevVirtioNet.cpp
   endif
@@ -1169 +1169 @@
   VBoxDDR0_SOURCES      += \
         VirtIO/Virtio.cpp \
-        VirtIO/Virtio_1_0.cpp \
+        VirtIO/VirtioCore.cpp \
         Network/DevVirtioNet.cpp
  endif

trunk/src/VBox/Devices/Network/DevVirtioNet_1_0.cpp

@@ -55 +55 @@
 # include <iprt/uuid.h>
 #endif
-#include "../VirtIO/Virtio_1_0.h"
+#include "../VirtIO/VirtioCore.h"
 
 #include "VBoxDD.h"
@@ -67 +67 @@
 #define VIRTIONET_PREALLOCATE_RX_SEG_COUNT     32
 
-#define VIRTQNAME(idxVirtq)       (pThis->aVirtqs[idxVirtq]->szName)
-#define CBVIRTQNAME(idxVirtq)     RTStrNLen(VIRTQNAME(idxVirtq), sizeof(VIRTQNAME(idxVirtq)))
+#define VIRTQNAME(uVirtqNbr)       (pThis->aVirtqs[uVirtqNbr]->szName)
+#define CBVIRTQNAME(uVirtqNbr)     RTStrNLen(VIRTQNAME(uVirtqNbr), sizeof(VIRTQNAME(uVirtqNbr)))
 #define FEATURE_ENABLED(feature)  RT_BOOL(pThis->fNegotiatedFeatures & VIRTIONET_F_##feature)
 #define FEATURE_DISABLED(feature) (!FEATURE_ENABLED(feature))
 #define FEATURE_OFFERED(feature)  VIRTIONET_HOST_FEATURES_OFFERED & VIRTIONET_F_##feature
 
-#define IS_VIRTQ_EMPTY(pDevIns, pVirtio, idxVirtq) \
-            (virtioCoreVirtqAvailCount(pDevIns, pVirtio, idxVirtq) == 0)
+#define IS_VIRTQ_EMPTY(pDevIns, pVirtio, uVirtqNbr) \
+            (virtioCoreVirtqAvailCount(pDevIns, pVirtio, uVirtqNbr) == 0)
 
 #define SET_LINK_UP(pState) \
@@ -227 +227 @@
 };
 #pragma pack()
-typedef virtio_net_pkt_hdr VIRTIONET_PKT_HDR_T, *PVIRTIONET_PKT_HDR_T;
-AssertCompileSize(VIRTIONET_PKT_HDR_T, 12);
+typedef virtio_net_pkt_hdr VIRTIONETPKTHDR, *PVIRTIONETPKTHDR;
+AssertCompileSize(VIRTIONETPKTHDR, 12);
 
 /* Control virtq: Command entry (VirtIO 1.0, 5.1.6.5) */
@@ -615 +615 @@
  * @callback_method_impl{VIRTIOCORER0,pfnVirtqNotified}
  */
-static DECLCALLBACK(void) virtioNetVirtqNotified(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq)
+static DECLCALLBACK(void) virtioNetVirtqNotified(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
 {
     RT_NOREF(pVirtio);
     PVIRTIONET pThis = PDMDEVINS_2_DATA(pDevIns, PVIRTIONET);
 
-    PVIRTIONETVIRTQ  pVirtq = &pThis->aVirtqs[idxVirtq];
+    PVIRTIONETVIRTQ  pVirtq  = &pThis->aVirtqs[uVirtqNbr];
     PVIRTIONETWORKER pWorker = pVirtq->pWorker;
 
@@ -627 +627 @@
 #endif
 
-    if (IS_RX_VIRTQ(idxVirtq))
-    {
-        uint16_t cBufsAvailable = virtioCoreVirtqAvailCount(pDevIns, pVirtio, idxVirtq);
+    if (IS_RX_VIRTQ(uVirtqNbr))
+    {
+        uint16_t cBufsAvailable = virtioCoreVirtqAvailCount(pDevIns, pVirtio, uVirtqNbr);
 
         if (cBufsAvailable)
@@ -641 +641 @@
                     pThis->szInst, pVirtq->szName));
     }
-    else if (IS_TX_VIRTQ(idxVirtq) || IS_CTRL_VIRTQ(idxVirtq))
+    else if (IS_TX_VIRTQ(uVirtqNbr) || IS_CTRL_VIRTQ(uVirtqNbr))
     {
         /* Wake queue's worker thread up if sleeping (e.g. a Tx queue, or the control queue */
@@ -663 +663 @@
     }
     else
-        LogRelFunc(("%s unrecognized queue %s (idx=%d) notified\n", pThis->szInst, pVirtq->szName, idxVirtq));
+        LogRelFunc(("%s unrecognized queue %s (idx=%d) notified\n", pThis->szInst, pVirtq->szName, uVirtqNbr));
 }
 
@@ -769 +769 @@
 
 #ifdef LOG_ENABLED
-void virtioNetDumpGcPhysRxBuf(PPDMDEVINS pDevIns, PVIRTIONET_PKT_HDR_T pRxPktHdr,
+void virtioNetDumpGcPhysRxBuf(PPDMDEVINS pDevIns, PVIRTIONETPKTHDR pRxPktHdr,
                      uint16_t cDescs, uint8_t *pvBuf, uint16_t cb, RTGCPHYS GCPhysRxBuf, uint8_t cbRxBuf)
 {
@@ -789 +789 @@
                         pRxPktHdr->uChksumStart, pRxPktHdr->uChksumOffset, pRxPktHdr->uNumBuffers));
 
-        virtioCoreHexDump((uint8_t *)pRxPktHdr, sizeof(VIRTIONET_PKT_HDR_T), 0, "Dump of virtual rPktHdr");
+        virtioCoreHexDump((uint8_t *)pRxPktHdr, sizeof(VIRTIONETPKTHDR), 0, "Dump of virtual rPktHdr");
     }
     virtioNetR3PacketDump(pThis, (const uint8_t *)pvBuf, cb, "<-- Incoming");
@@ -841 +841 @@
         pHlp->pfnPrintf(pHlp, "Virtq information:\n\n");
 
-        for (int idxVirtq = 0; idxVirtq < pThis->cVirtVirtqs; idxVirtq++)
+        for (int uVirtqNbr = 0; uVirtqNbr < pThis->cVirtVirtqs; uVirtqNbr++)
         {
-            PVIRTIONETVIRTQ pVirtq = &pThis->aVirtqs[idxVirtq];
+            PVIRTIONETVIRTQ pVirtq = &pThis->aVirtqs[uVirtqNbr];
 
             if (pVirtq->fHasWorker)
@@ -873 +873 @@
             }
             pHlp->pfnPrintf(pHlp, "\n");
-            virtioCoreR3VirtqInfo(pDevIns, pHlp, pszArgs, idxVirtq);
+            virtioCoreR3VirtqInfo(pDevIns, pHlp, pszArgs, uVirtqNbr);
             pHlp->pfnPrintf(pHlp, "    ---------------------------------------------------------------------\n");
             pHlp->pfnPrintf(pHlp, "\n");
@@ -963 +963 @@
 
     }
-    pHlp->pfnPrintf(pHlp, "\n");
-    virtioCoreR3Info(pDevIns, pHlp, pszArgs);
+    /** @todo implement this
+      * pHlp->pfnPrintf(pHlp, "\n");
+      * virtioCoreR3Info(pDevIns, pHlp, pszArgs);
+      */
     pHlp->pfnPrintf(pHlp, "\n");
 }
@@ -1139 +1141 @@
     pHlp->pfnSSMGetU16(     pSSM, &pThis->cWorkers);
 
-    for (int idxVirtq = 0; idxVirtq < pThis->cVirtVirtqs; idxVirtq++)
-        pHlp->pfnSSMGetBool(pSSM, &pThis->aVirtqs[idxVirtq].fAttachedToVirtioCore);
+    for (int uVirtqNbr = 0; uVirtqNbr < pThis->cVirtVirtqs; uVirtqNbr++)
+        pHlp->pfnSSMGetBool(pSSM, &pThis->aVirtqs[uVirtqNbr].fAttachedToVirtioCore);
 
     int rc;
@@ -1228 +1230 @@
     pHlp->pfnSSMPutU16(     pSSM, pThis->cWorkers);
 
-    for (int idxVirtq = 0; idxVirtq < pThis->cVirtVirtqs; idxVirtq++)
-        pHlp->pfnSSMPutBool(pSSM, pThis->aVirtqs[idxVirtq].fAttachedToVirtioCore);
+    for (int uVirtqNbr = 0; uVirtqNbr < pThis->cVirtVirtqs; uVirtqNbr++)
+        pHlp->pfnSSMPutBool(pSSM, pThis->aVirtqs[uVirtqNbr].fAttachedToVirtioCore);
 
     /* Save config area */
@@ -1489 +1491 @@
         rc = VINF_SUCCESS;
     }
-    virtioCoreVirtqNotifyEnable(&pThis->Virtio, pRxVirtq->idx, rc == VERR_INVALID_STATE /* fEnable */);
+    virtioCoreVirtqEnableNotify(&pThis->Virtio, pRxVirtq->idx, rc == VERR_INVALID_STATE /* fEnable */);
     return rc;
 }
@@ -1495 +1497 @@
 static bool virtioNetR3RxBufsAvail(PPDMDEVINS pDevIns, PVIRTIONET pThis, PVIRTIONETVIRTQ *pRxVirtq)
 {
-    for (int idxVirtqPair = 0; idxVirtqPair < pThis->cVirtqPairs; idxVirtqPair++)
-    {
-        PVIRTIONETVIRTQ pThisRxVirtq = &pThis->aVirtqs[RXQIDX(idxVirtqPair)];
+    for (int uVirtqNbrPair = 0; uVirtqNbrPair < pThis->cVirtqPairs; uVirtqNbrPair++)
+    {
+        PVIRTIONETVIRTQ pThisRxVirtq = &pThis->aVirtqs[RXQIDX(uVirtqNbrPair)];
         if (RT_SUCCESS(virtioNetR3CheckRxBufsAvail(pDevIns, pThis, pThisRxVirtq)))
         {
@@ -1566 +1568 @@
  * @param   pCtx                The context descriptor.
  */
-DECLINLINE(PPDMNETWORKGSO) virtioNetR3SetupGsoCtx(PPDMNETWORKGSO pGso, VIRTIONET_PKT_HDR_T const *pPktHdr)
+DECLINLINE(PPDMNETWORKGSO) virtioNetR3SetupGsoCtx(PPDMNETWORKGSO pGso, VIRTIONETPKTHDR const *pPktHdr)
 {
     pGso->u8Type = PDMNETWORKGSOTYPE_INVALID;
@@ -1729 +1731 @@
 
 static int virtioNetR3CopyRxPktToGuest(PPDMDEVINS pDevIns, PVIRTIONET pThis, const void *pvBuf, size_t cb,
-                                       VIRTIONET_PKT_HDR_T *rxPktHdr, uint16_t cSegsAllocated,
+                                       VIRTIONETPKTHDR *rxPktHdr, uint16_t cSegsAllocated,
                                        PRTSGBUF pVirtSegBufToGuest, PRTSGSEG paVirtSegsToGuest,
                                        PVIRTIONETVIRTQ pRxVirtq)
@@ -1739 +1741 @@
     for (cDescs = uOffset = 0; uOffset < cb; )
     {
-        PVIRTIO_DESC_CHAIN_T pDescChain = NULL;
-
-        int rc = virtioCoreR3VirtqGet(pDevIns, &pThis->Virtio, pRxVirtq->idx, &pDescChain, true);
+        PVIRTQBUF pVirtqBuf = NULL;
+
+        int rc = virtioCoreR3VirtqBufGet(pDevIns, &pThis->Virtio, pRxVirtq->idx, &pVirtqBuf, true);
         AssertMsgReturn(rc == VINF_SUCCESS || rc == VERR_NOT_AVAILABLE, ("%Rrc\n", rc), rc);
 
         /** @todo  Find a better way to deal with this */
-        AssertMsgReturnStmt(rc == VINF_SUCCESS && pDescChain->cbPhysReturn,
+        AssertMsgReturnStmt(rc == VINF_SUCCESS && pVirtqBuf->cbPhysReturn,
                             ("Not enough Rx buffers in queue to accomodate ethernet packet\n"),
-                            virtioCoreR3DescChainRelease(&pThis->Virtio, pDescChain),
+                            virtioCoreR3VirtqBufRelease(&pThis->Virtio, pVirtqBuf),
                             VERR_INTERNAL_ERROR);
 
@@ -1754 +1756 @@
          * virtio_net_header.num_buffers, to defer updating (in GCPhys). Re-visit if needed */
 
-        AssertMsgReturnStmt(pDescChain->pSgPhysReturn->paSegs[0].cbSeg >= sizeof(VIRTIONET_PKT_HDR_T),
+        AssertMsgReturnStmt(pVirtqBuf->pSgPhysReturn->paSegs[0].cbSeg >= sizeof(VIRTIONETPKTHDR),
                             ("Desc chain's first seg has insufficient space for pkt header!\n"),
-                            virtioCoreR3DescChainRelease(&pThis->Virtio, pDescChain),
+                            virtioCoreR3VirtqBufRelease(&pThis->Virtio, pVirtqBuf),
                             VERR_INTERNAL_ERROR);
 
-        size_t cbDescChainLeft = pDescChain->cbPhysReturn;
-        uint8_t  cbHdr = sizeof(VIRTIONET_PKT_HDR_T);
+        size_t cbDescChainLeft = pVirtqBuf->cbPhysReturn;
+        uint8_t  cbHdr = sizeof(VIRTIONETPKTHDR);
 
         /* Fill the Guest Rx buffer with data received from the interface */
@@ -1776 +1778 @@
 
                 /* Calculate & cache addr of field to update after final value is known, in GCPhys mem */
-                GCPhysPktHdrNumBuffers = pDescChain->pSgPhysReturn->paSegs[0].GCPhys
-                                         + RT_UOFFSETOF(VIRTIONET_PKT_HDR_T, uNumBuffers);
+                GCPhysPktHdrNumBuffers = pVirtqBuf->pSgPhysReturn->paSegs[0].GCPhys
+                                         + RT_UOFFSETOF(VIRTIONETPKTHDR, uNumBuffers);
                 fAddPktHdr = false;
                 cSegs++;
@@ -1787 +1789 @@
                 paVirtSegsToGuest = (PRTSGSEG)RTMemRealloc(paVirtSegsToGuest, sizeof(RTSGSEG) * cSegsAllocated);
                 if (!paVirtSegsToGuest)
-                    virtioCoreR3DescChainRelease(&pThis->Virtio, pDescChain);
+                    virtioCoreR3VirtqBufRelease(&pThis->Virtio, pVirtqBuf);
                 AssertReturn(paVirtSegsToGuest, VERR_NO_MEMORY);
             }
@@ -1802 +1804 @@
             Log7Func(("Send Rx pkt to guest...\n"));
             STAM_PROFILE_START(&pThis->StatReceiveStore, a);
-            virtioCoreR3VirtqPut(pDevIns, &pThis->Virtio, pRxVirtq->idx,
-                                 pVirtSegBufToGuest, pDescChain, true /* fFence */);
+            virtioCoreR3VirtqBufPut(pDevIns, &pThis->Virtio, pRxVirtq->idx,
+                                 pVirtSegBufToGuest, pVirtqBuf, true /* fFence */);
             STAM_PROFILE_STOP(&pThis->StatReceiveStore, a);
 
@@ -1810 +1812 @@
         }
 
-        virtioCoreR3DescChainRelease(&pThis->Virtio, pDescChain);
+        virtioCoreR3VirtqBufRelease(&pThis->Virtio, pVirtqBuf);
     }
 
@@ -1853 +1855 @@
 
     LogFunc(("%s (%RTmac) pGso %s\n", pThis->szInst, pvBuf, pGso ? "present" : "not present"));
-    VIRTIONET_PKT_HDR_T rxPktHdr = { 0 };
+    VIRTIONETPKTHDR rxPktHdr = { 0 };
 
     if (pGso)
@@ -1961 +1963 @@
               selection algorithm feasible or even necessary to prevent starvation? */
 
-    for (int idxVirtqPair = 0; idxVirtqPair < pThis->cVirtqPairs; idxVirtqPair++)
-    {
-
-        PVIRTIONETVIRTQ pRxVirtq = &pThis->aVirtqs[RXQIDX(idxVirtqPair)];
+    for (int uVirtqNbrPair = 0; uVirtqNbrPair < pThis->cVirtqPairs; uVirtqNbrPair++)
+    {
+
+        PVIRTIONETVIRTQ pRxVirtq = &pThis->aVirtqs[RXQIDX(uVirtqNbrPair)];
         if (RT_SUCCESS(!virtioNetR3CheckRxBufsAvail(pDevIns, pThis, pRxVirtq)))
         {
@@ -1998 +2000 @@
 
 /* Read physical bytes from the out segment(s) of descriptor chain */
-static void virtioNetR3PullChain(PPDMDEVINS pDevIns, PVIRTIONET pThis, PVIRTIO_DESC_CHAIN_T pDescChain, void *pv, size_t cb)
+static void virtioNetR3PullChain(PPDMDEVINS pDevIns, PVIRTIONET pThis, PVIRTQBUF pVirtqBuf, void *pv, size_t cb)
 {
     uint8_t *pb = (uint8_t *)pv;
-    size_t cbLim = RT_MIN(pDescChain->cbPhysSend, cb);
+    size_t cbLim = RT_MIN(pVirtqBuf->cbPhysSend, cb);
     while (cbLim)
     {
         size_t cbSeg = cbLim;
-        RTGCPHYS GCPhys = virtioCoreSgBufGetNextSegment(pDescChain->pSgPhysSend, &cbSeg);
+        RTGCPHYS GCPhys = virtioCoreSgBufGetNextSegment(pVirtqBuf->pSgPhysSend, &cbSeg);
         PDMDevHlpPCIPhysRead(pDevIns, GCPhys, pb, cbSeg);
         pb += cbSeg;
         cbLim -= cbSeg;
-        pDescChain->cbPhysSend -= cbSeg;
+        pVirtqBuf->cbPhysSend -= cbSeg;
     }
     LogFunc(("%s Pulled %d/%d bytes from desc chain (%d bytes left)\n",
-             pThis->szInst, cb - cbLim, cb, pDescChain->cbPhysSend));
+             pThis->szInst, cb - cbLim, cb, pVirtqBuf->cbPhysSend));
     RT_NOREF(pThis);
 }
 
 static uint8_t virtioNetR3CtrlRx(PPDMDEVINS pDevIns, PVIRTIONET pThis, PVIRTIONETCC pThisCC,
-                                 PVIRTIONET_CTRL_HDR_T pCtrlPktHdr, PVIRTIO_DESC_CHAIN_T pDescChain)
+                                 PVIRTIONET_CTRL_HDR_T pCtrlPktHdr, PVIRTQBUF pVirtqBuf)
 {
 
@@ -2044 +2046 @@
 
     uint8_t fOn, fPromiscChanged = false;
-    virtioNetR3PullChain(pDevIns, pThis, pDescChain, &fOn, (size_t)RT_MIN(pDescChain->cbPhysSend, sizeof(fOn)));
+    virtioNetR3PullChain(pDevIns, pThis, pVirtqBuf, &fOn, (size_t)RT_MIN(pVirtqBuf->cbPhysSend, sizeof(fOn)));
 
     switch(pCtrlPktHdr->uCmd)
@@ -2092 +2094 @@
 
 static uint8_t virtioNetR3CtrlMac(PPDMDEVINS pDevIns, PVIRTIONET pThis, PVIRTIONETCC pThisCC,
-                                  PVIRTIONET_CTRL_HDR_T pCtrlPktHdr, PVIRTIO_DESC_CHAIN_T pDescChain)
+                                  PVIRTIONET_CTRL_HDR_T pCtrlPktHdr, PVIRTQBUF pVirtqBuf)
 {
     LogFunc(("%s Processing CTRL MAC command\n", pThis->szInst));
@@ -2104 +2106 @@
     AssertMsgReturn((v), ("DESC chain too small to process CTRL_MAC_TABLE_SET cmd\n"), VIRTIONET_ERROR)
 
-    AssertMsgReturn(pDescChain->cbPhysSend >= sizeof(*pCtrlPktHdr),
+    AssertMsgReturn(pVirtqBuf->cbPhysSend >= sizeof(*pCtrlPktHdr),
                    ("insufficient descriptor space for ctrl pkt hdr"),
                    VIRTIONET_ERROR);
 
-    size_t cbRemaining = pDescChain->cbPhysSend;
+    size_t cbRemaining = pVirtqBuf->cbPhysSend;
     switch(pCtrlPktHdr->uCmd)
     {
@@ -2115 +2117 @@
             /* Set default Rx filter MAC */
             ASSERT_CTRL_ADDR_SET(cbRemaining >= sizeof(VIRTIONET_CTRL_MAC_TABLE_LEN));
-            virtioNetR3PullChain(pDevIns, pThis, pDescChain, &pThis->rxFilterMacDefault, sizeof(VIRTIONET_CTRL_MAC_TABLE_LEN));
+            virtioNetR3PullChain(pDevIns, pThis, pVirtqBuf, &pThis->rxFilterMacDefault, sizeof(VIRTIONET_CTRL_MAC_TABLE_LEN));
             break;
         }
@@ -2124 +2126 @@
             /* Load unicast MAC filter table */
             ASSERT_CTRL_TABLE_SET(cbRemaining >= sizeof(cMacs));
-            virtioNetR3PullChain(pDevIns, pThis, pDescChain, &cMacs, sizeof(cMacs));
+            virtioNetR3PullChain(pDevIns, pThis, pVirtqBuf, &cMacs, sizeof(cMacs));
             cbRemaining -= sizeof(cMacs);
             Log7Func(("%s Guest provided %d unicast MAC Table entries\n", pThis->szInst, cMacs));
@@ -2131 +2133 @@
                 uint32_t cbMacs = cMacs * sizeof(RTMAC);
                 ASSERT_CTRL_TABLE_SET(cbRemaining >= cbMacs);
-                virtioNetR3PullChain(pDevIns, pThis, pDescChain, &pThis->aMacUnicastFilter, cbMacs);
+                virtioNetR3PullChain(pDevIns, pThis, pVirtqBuf, &pThis->aMacUnicastFilter, cbMacs);
                 cbRemaining -= cbMacs;
             }
@@ -2138 +2140 @@
             /* Load multicast MAC filter table */
             ASSERT_CTRL_TABLE_SET(cbRemaining >= sizeof(cMacs));
-            virtioNetR3PullChain(pDevIns, pThis, pDescChain, &cMacs, sizeof(cMacs));
+            virtioNetR3PullChain(pDevIns, pThis, pVirtqBuf, &cMacs, sizeof(cMacs));
             cbRemaining -= sizeof(cMacs);
             Log10Func(("%s Guest provided %d multicast MAC Table entries\n", pThis->szInst, cMacs));
@@ -2145 +2147 @@
                 uint32_t cbMacs = cMacs * sizeof(RTMAC);
                 ASSERT_CTRL_TABLE_SET(cbRemaining >= cbMacs);
-                virtioNetR3PullChain(pDevIns, pThis, pDescChain, &pThis->aMacMulticastFilter, cbMacs);
+                virtioNetR3PullChain(pDevIns, pThis, pVirtqBuf, &pThis->aMacMulticastFilter, cbMacs);
                 cbRemaining -= cbMacs;
             }
@@ -2165 +2167 @@
 
 static uint8_t virtioNetR3CtrlVlan(PPDMDEVINS pDevIns, PVIRTIONET pThis, PVIRTIONETCC pThisCC,
-                                   PVIRTIONET_CTRL_HDR_T pCtrlPktHdr, PVIRTIO_DESC_CHAIN_T pDescChain)
+                                   PVIRTIONET_CTRL_HDR_T pCtrlPktHdr, PVIRTQBUF pVirtqBuf)
 {
     LogFunc(("%s Processing CTRL VLAN command\n", pThis->szInst));
@@ -2172 +2174 @@
 
     uint16_t uVlanId;
-    size_t cbRemaining = pDescChain->cbPhysSend - sizeof(*pCtrlPktHdr);
+    size_t cbRemaining = pVirtqBuf->cbPhysSend - sizeof(*pCtrlPktHdr);
     AssertMsgReturn(cbRemaining > sizeof(uVlanId),
         ("DESC chain too small for VIRTIO_NET_CTRL_VLAN cmd processing"), VIRTIONET_ERROR);
-    virtioNetR3PullChain(pDevIns, pThis, pDescChain, &uVlanId, sizeof(uVlanId));
+    virtioNetR3PullChain(pDevIns, pThis, pVirtqBuf, &uVlanId, sizeof(uVlanId));
     AssertMsgReturn(uVlanId > VIRTIONET_MAX_VLAN_ID,
         ("%s VLAN ID out of range (VLAN ID=%u)\n", pThis->szInst, uVlanId), VIRTIONET_ERROR);
@@ -2194 +2196 @@
 
 static void virtioNetR3Ctrl(PPDMDEVINS pDevIns, PVIRTIONET pThis, PVIRTIONETCC pThisCC,
-                            PVIRTIO_DESC_CHAIN_T pDescChain)
+                            PVIRTQBUF pVirtqBuf)
 {
     LogFunc(("%s Received CTRL packet from guest\n", pThis->szInst));
 
-    if (pDescChain->cbPhysSend < 2)
+    if (pVirtqBuf->cbPhysSend < 2)
     {
         LogFunc(("%s CTRL packet from guest driver incomplete. Skipping ctrl cmd\n", pThis->szInst));
         return;
     }
-    else if (pDescChain->cbPhysReturn < sizeof(VIRTIONET_CTRL_HDR_T_ACK))
+    else if (pVirtqBuf->cbPhysReturn < sizeof(VIRTIONET_CTRL_HDR_T_ACK))
     {
         LogFunc(("%s Guest driver didn't allocate memory to receive ctrl pkt ACK. Skipping ctrl cmd\n", pThis->szInst));
@@ -2216 +2218 @@
     AssertPtrReturnVoid(pCtrlPktHdr);
 
-    AssertMsgReturnVoid(pDescChain->cbPhysSend >= sizeof(VIRTIONET_CTRL_HDR_T),
+    AssertMsgReturnVoid(pVirtqBuf->cbPhysSend >= sizeof(VIRTIONET_CTRL_HDR_T),
                         ("DESC chain too small for CTRL pkt header"));
 
-    virtioNetR3PullChain(pDevIns, pThis, pDescChain, pCtrlPktHdr,
-                         RT_MIN(pDescChain->cbPhysSend, sizeof(VIRTIONET_CTRL_HDR_T)));
+    virtioNetR3PullChain(pDevIns, pThis, pVirtqBuf, pCtrlPktHdr,
+                         RT_MIN(pVirtqBuf->cbPhysSend, sizeof(VIRTIONET_CTRL_HDR_T)));
 
     Log7Func(("%s CTRL COMMAND: class=%d command=%d\n", pThis->szInst, pCtrlPktHdr->uClass, pCtrlPktHdr->uCmd));
@@ -2228 +2230 @@
     {
         case VIRTIONET_CTRL_RX:
-            uAck = virtioNetR3CtrlRx(pDevIns, pThis, pThisCC, pCtrlPktHdr, pDescChain);
+            uAck = virtioNetR3CtrlRx(pDevIns, pThis, pThisCC, pCtrlPktHdr, pVirtqBuf);
             break;
         case VIRTIONET_CTRL_MAC:
-            uAck = virtioNetR3CtrlMac(pDevIns, pThis, pThisCC, pCtrlPktHdr, pDescChain);
+            uAck = virtioNetR3CtrlMac(pDevIns, pThis, pThisCC, pCtrlPktHdr, pVirtqBuf);
             break;
         case VIRTIONET_CTRL_VLAN:
-            uAck = virtioNetR3CtrlVlan(pDevIns, pThis, pThisCC, pCtrlPktHdr, pDescChain);
+            uAck = virtioNetR3CtrlVlan(pDevIns, pThis, pThisCC, pCtrlPktHdr, pVirtqBuf);
             break;
         case VIRTIONET_CTRL_ANNOUNCE:
@@ -2283 +2285 @@
     RTSgBufInit(pReturnSegBuf, paReturnSegs, cSegs);
 
-    virtioCoreR3VirtqPut(pDevIns, &pThis->Virtio, CTRLQIDX, pReturnSegBuf, pDescChain, true /* fFence */);
+    virtioCoreR3VirtqBufPut(pDevIns, &pThis->Virtio, CTRLQIDX, pReturnSegBuf, pVirtqBuf, true /* fFence */);
     virtioCoreVirtqSync(pDevIns, &pThis->Virtio, CTRLQIDX);
 
@@ -2296 +2298 @@
 }
 
-static int virtioNetR3ReadHeader(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, PVIRTIONET_PKT_HDR_T pPktHdr, size_t cbFrame)
+static int virtioNetR3ReadHeader(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, PVIRTIONETPKTHDR pPktHdr, size_t cbFrame)
 {
     int rc = PDMDevHlpPCIPhysRead(pDevIns, GCPhys, pPktHdr, sizeof(*pPktHdr));
@@ -2343 +2345 @@
 
 static int virtioNetR3TransmitFrame(PVIRTIONET pThis, PVIRTIONETCC pThisCC, PPDMSCATTERGATHER pSgBuf,
-                               PPDMNETWORKGSO pGso, PVIRTIONET_PKT_HDR_T pPktHdr)
+                               PPDMNETWORKGSO pGso, PVIRTIONETPKTHDR pPktHdr)
 {
     virtioNetR3PacketDump(pThis, (uint8_t *)pSgBuf->aSegs[0].pvSeg, pSgBuf->cbUsed, "--> Outgoing");
@@ -2449 +2451 @@
 
     int rc;
-    PVIRTIO_DESC_CHAIN_T pDescChain = NULL;
-    while ((rc = virtioCoreR3VirtqPeek(pVirtio->pDevInsR3, pVirtio, pTxVirtq->idx, &pDescChain)) == VINF_SUCCESS)
+    PVIRTQBUF pVirtqBuf = NULL;
+    while ((rc = virtioCoreR3VirtqBufPeek(pVirtio->pDevInsR3, pVirtio, pTxVirtq->idx, &pVirtqBuf)) == VINF_SUCCESS)
     {
         Log10Func(("%s fetched descriptor chain from %s\n", pThis->szInst, pTxVirtq->szName));
 
-        PVIRTIOSGBUF pSgPhysSend = pDescChain->pSgPhysSend;
+        PVIRTIOSGBUF pSgPhysSend = pVirtqBuf->pSgPhysSend;
         PVIRTIOSGSEG paSegsFromGuest = pSgPhysSend->paSegs;
         uint32_t cSegsFromGuest = pSgPhysSend->cSegs;
 
-        VIRTIONET_PKT_HDR_T PktHdr;
+        VIRTIONETPKTHDR PktHdr;
         size_t uSize = 0;
 
@@ -2514 +2516 @@
 
                 LogFunc((".... Copied %lu bytes to %lu byte guest buffer, residual=%lu\n",
-                     cbTotal, pDescChain->cbPhysSend, pDescChain->cbPhysSend - cbTotal));
+                     cbTotal, pVirtqBuf->cbPhysSend, pVirtqBuf->cbPhysSend - cbTotal));
 
                 rc = virtioNetR3TransmitFrame(pThis, pThisCC, pSgBufToPdmLeafDevice, pGso, &PktHdr);
@@ -2531 +2533 @@
                 Log4Func(("Failed to allocate S/G buffer: size=%u rc=%Rrc\n", uSize, rc));
                 /* Stop trying to fetch TX descriptors until we get more bandwidth. */
-                virtioCoreR3DescChainRelease(pVirtio, pDescChain);
+                virtioCoreR3VirtqBufRelease(pVirtio, pVirtqBuf);
                 break;
             }
 
             /* Remove this descriptor chain from the available ring */
-            virtioCoreR3VirtqSkip(pVirtio, pTxVirtq->idx);
+            virtioCoreR3VirtqBufSkip(pVirtio, pTxVirtq->idx);
 
             /* No data to return to guest, but call is needed put elem (e.g. desc chain) on used ring */
-            virtioCoreR3VirtqPut(pVirtio->pDevInsR3, pVirtio, pTxVirtq->idx, NULL, pDescChain, true /* fFence */);
+            virtioCoreR3VirtqBufPut(pVirtio->pDevInsR3, pVirtio, pTxVirtq->idx, NULL, pVirtqBuf, true /* fFence */);
 
             /* Update used ring idx and notify guest that we've transmitted the data it sent */
@@ -2545 +2547 @@
         }
 
-        virtioCoreR3DescChainRelease(pVirtio, pDescChain);
-        pDescChain = NULL;
+        virtioCoreR3VirtqBufRelease(pVirtio, pVirtqBuf);
+        pVirtqBuf = NULL;
     }
     virtioNetR3SetWriteLed(pThisCC, false);
@@ -2792 +2794 @@
 
     uint16_t idxWorker = CTRLWIDX + 1;
-    for (uint16_t idxVirtqPair = 0; idxVirtqPair < pThis->cVirtqPairs; idxVirtqPair++, idxWorker++)
-    {
-        PVIRTIONETVIRTQ pTxVirtq = &pThis->aVirtqs[TXQIDX(idxVirtqPair)];
-        PVIRTIONETVIRTQ pRxVirtq = &pThis->aVirtqs[RXQIDX(idxVirtqPair)];
+    for (uint16_t uVirtqNbrPair = 0; uVirtqNbrPair < pThis->cVirtqPairs; uVirtqNbrPair++, idxWorker++)
+    {
+        PVIRTIONETVIRTQ pTxVirtq = &pThis->aVirtqs[TXQIDX(uVirtqNbrPair)];
+        PVIRTIONETVIRTQ pRxVirtq = &pThis->aVirtqs[RXQIDX(uVirtqNbrPair)];
 
         rc = virtioNetR3CreateOneWorkerThread(pDevIns, pThis, idxWorker, &pThis->aWorkers[idxWorker],
@@ -2825 +2827 @@
     /** @todo Race w/guest enabling/disabling guest notifications cyclically.
               See BugRef #8651, Comment #82 */
-    virtioCoreVirtqNotifyEnable(&pThis->Virtio, pVirtq->idx, true /* fEnable */);
+    virtioCoreVirtqEnableNotify(&pThis->Virtio, pVirtq->idx, true /* fEnable */);
 
     while (pThread->enmState == PDMTHREADSTATE_RUNNING)
@@ -2857 +2859 @@
              {
                  Log10Func(("%s %s worker woken. Fetching desc chain\n", pThis->szInst, pVirtq->szName));
-                 PVIRTIO_DESC_CHAIN_T pDescChain = NULL;
-                 int rc = virtioCoreR3VirtqGet(pDevIns, &pThis->Virtio, pVirtq->idx, &pDescChain, true);
+                 PVIRTQBUF pVirtqBuf = NULL;
+                 int rc = virtioCoreR3VirtqBufGet(pDevIns, &pThis->Virtio, pVirtq->idx, &pVirtqBuf, true);
                  if (rc == VERR_NOT_AVAILABLE)
                  {
@@ -2864 +2866 @@
                     continue;
                  }
-                 virtioNetR3Ctrl(pDevIns, pThis, pThisCC, pDescChain);
-                 virtioCoreR3DescChainRelease(&pThis->Virtio, pDescChain);
+                 virtioNetR3Ctrl(pDevIns, pThis, pThisCC, pVirtqBuf);
+                 virtioCoreR3VirtqBufRelease(&pThis->Virtio, pVirtqBuf);
              }
              else /* Must be Tx queue */
@@ -2911 +2913 @@
         pThisCC->fQuiescing = false;
 
-        for (unsigned idxVirtq = 0; idxVirtq < pThis->cVirtVirtqs; idxVirtq++)
+        for (unsigned uVirtqNbr = 0; uVirtqNbr < pThis->cVirtVirtqs; uVirtqNbr++)
         {
-            PVIRTIONETVIRTQ pVirtq = &pThis->aVirtqs[idxVirtq];
-            pVirtq->idx = idxVirtq;
+            PVIRTIONETVIRTQ pVirtq = &pThis->aVirtqs[uVirtqNbr];
+            pVirtq->idx = uVirtqNbr;
             (void) virtioCoreR3VirtqAttach(&pThis->Virtio, pVirtq->idx, pVirtq->szName);
             pVirtq->fAttachedToVirtioCore = true;
             if (IS_VIRTQ_EMPTY(pThisCC->pDevIns, &pThis->Virtio, pVirtq->idx))
-                virtioCoreVirtqNotifyEnable(&pThis->Virtio, pVirtq->idx, true /* fEnable */);
+                virtioCoreVirtqEnableNotify(&pThis->Virtio, pVirtq->idx, true /* fEnable */);
         }
     }
@@ -2944 +2946 @@
         pThisCC->pDrv->pfnSetPromiscuousMode(pThisCC->pDrv, true);
 
-        for (uint16_t idxVirtq = 0; idxVirtq < pThis->cVirtVirtqs; idxVirtq++)
-            pThis->aVirtqs[idxVirtq].fAttachedToVirtioCore = false;
+        for (uint16_t uVirtqNbr = 0; uVirtqNbr < pThis->cVirtVirtqs; uVirtqNbr++)
+            pThis->aVirtqs[uVirtqNbr].fAttachedToVirtioCore = false;
     }
 }

trunk/src/VBox/Devices/Storage/DevVirtioSCSI.cpp

@@ -51 +51 @@
 # include <iprt/uuid.h>
 #endif
-#include "../VirtIO/Virtio_1_0.h"
+#include "../VirtIO/VirtioCore.h"
 
 #include "VBoxSCSI.h"
@@ -112 +112 @@
 #define VIRTQ_REQ_BASE                              2           /**< Spec-defined base index of request queues       */
 
-#define VIRTQNAME(idxVirtq) (pThis->aszVirtqNames[idxVirtq])            /**< Macro to get queue name from its index          */
-#define CBVIRTQNAME(idxVirtq) RTStrNLen(VIRTQNAME(idxVirtq), sizeof(VIRTQNAME(idxVirtq)))
-
-#define IS_REQ_VIRTQ(idxVirtq) (idxVirtq >= VIRTQ_REQ_BASE && idxVirtq < VIRTIOSCSI_VIRTQ_CNT)
+#define VIRTQNAME(uVirtqNbr) (pThis->aszVirtqNames[uVirtqNbr])            /**< Macro to get queue name from its index          */
+#define CBVIRTQNAME(uVirtqNbr) RTStrNLen(VIRTQNAME(uVirtqNbr), sizeof(VIRTQNAME(uVirtqNbr)))
+
+#define IS_REQ_VIRTQ(uVirtqNbr) (uVirtqNbr >= VIRTQ_REQ_BASE && uVirtqNbr < VIRTIOSCSI_VIRTQ_CNT)
 
 #define VIRTIO_IS_IN_DIRECTION(pMediaExTxDirEnumValue) \
@@ -123 +123 @@
     ((pMediaExTxDirEnumValue) == PDMMEDIAEXIOREQSCSITXDIR_TO_DEVICE)
 
-#define IS_VIRTQ_EMPTY(pDevIns, pVirtio, idxVirtq) \
-            (virtioCoreVirtqAvailCount(pDevIns, pVirtio, idxVirtq) == 0)
+#define IS_VIRTQ_EMPTY(pDevIns, pVirtio, uVirtqNbr) \
+            (virtioCoreVirtqAvailCount(pDevIns, pVirtio, uVirtqNbr) == 0)
 
 
@@ -557 +557 @@
     PDMMEDIAEXIOREQ                hIoReq;                      /**< Handle of I/O request                             */
     PVIRTIOSCSITARGET              pTarget;                     /**< Target                                            */
-    uint16_t                       idxVirtq;                        /**< Index of queue this request arrived on            */
-    PVIRTIO_DESC_CHAIN_T           pDescChain;                  /**< Prepared desc chain pulled from virtq avail ring  */
+    uint16_t                       uVirtqNbr;                   /**< Index of queue this request arrived on            */
+    PVIRTQBUF                      pVirtqBuf;                   /**< Prepared desc chain pulled from virtq avail ring  */
     size_t                         cbDataIn;                    /**< size of dataout buffer                            */
     size_t                         cbDataOut;                   /**< size of dataout buffer                            */
@@ -576 +576 @@
  * @todo this causes burn if I prefix with at-sign. This callback is in VIRTIOCORER0 and VIRTIOCORER3
  */
-static DECLCALLBACK(void) virtioScsiNotified(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq)
+static DECLCALLBACK(void) virtioScsiNotified(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
 {
 
@@ -582 +582 @@
     PVIRTIOSCSI pThis   = PDMDEVINS_2_DATA(pDevIns, PVIRTIOSCSI);
 
-    AssertReturnVoid(idxVirtq < VIRTIOSCSI_VIRTQ_CNT);
-    PVIRTIOSCSIWORKER pWorker = &pThis->aWorkers[idxVirtq];
+    AssertReturnVoid(uVirtqNbr < VIRTIOSCSI_VIRTQ_CNT);
+    PVIRTIOSCSIWORKER pWorker = &pThis->aWorkers[uVirtqNbr];
 
 #if defined (IN_RING3) && defined (LOG_ENABLED)
@@ -589 +589 @@
 #endif
 
-    if (idxVirtq == CONTROLQ_IDX || IS_REQ_VIRTQ(idxVirtq))
-    {
-        Log6Func(("%s has available data\n", VIRTQNAME(idxVirtq)));
+    if (uVirtqNbr == CONTROLQ_IDX || IS_REQ_VIRTQ(uVirtqNbr))
+    {
+        Log6Func(("%s has available data\n", VIRTQNAME(uVirtqNbr)));
         /* Wake queue's worker thread up if sleeping */
         if (!ASMAtomicXchgBool(&pWorker->fNotified, true))
@@ -597 +597 @@
             if (ASMAtomicReadBool(&pWorker->fSleeping))
             {
-                Log6Func(("waking %s worker.\n", VIRTQNAME(idxVirtq)));
+                Log6Func(("waking %s worker.\n", VIRTQNAME(uVirtqNbr)));
                 int rc = PDMDevHlpSUPSemEventSignal(pDevIns, pWorker->hEvtProcess);
                 AssertRC(rc);
@@ -603 +603 @@
         }
     }
-    else if (idxVirtq == EVENTQ_IDX)
-    {
-        Log3Func(("Driver queued buffer(s) to %s\n", VIRTQNAME(idxVirtq)));
+    else if (uVirtqNbr == EVENTQ_IDX)
+    {
+        Log3Func(("Driver queued buffer(s) to %s\n", VIRTQNAME(uVirtqNbr)));
 //        if (ASMAtomicXchgBool(&pThis->fEventsMissed, false))
 //            virtioScsiR3ReportEventsMissed(pDevIns, pThis, 0);
     }
     else
-        LogFunc(("Unexpected queue idx (ignoring): %d\n", idxVirtq));
+        LogFunc(("Unexpected queue idx (ignoring): %d\n", uVirtqNbr));
 }
 
@@ -621 +621 @@
     RTStrCopy(pThis->aszVirtqNames[CONTROLQ_IDX], VIRTIO_MAX_VIRTQ_NAME_SIZE, "controlq");
     RTStrCopy(pThis->aszVirtqNames[EVENTQ_IDX],   VIRTIO_MAX_VIRTQ_NAME_SIZE, "eventq");
-    for (uint16_t idxVirtq = VIRTQ_REQ_BASE; idxVirtq < VIRTQ_REQ_BASE + VIRTIOSCSI_REQ_VIRTQ_CNT; idxVirtq++)
-        RTStrPrintf(pThis->aszVirtqNames[idxVirtq], VIRTIO_MAX_VIRTQ_NAME_SIZE,
-                    "requestq<%d>", idxVirtq - VIRTQ_REQ_BASE);
+    for (uint16_t uVirtqNbr = VIRTQ_REQ_BASE; uVirtqNbr < VIRTQ_REQ_BASE + VIRTIOSCSI_REQ_VIRTQ_CNT; uVirtqNbr++)
+        RTStrPrintf(pThis->aszVirtqNames[uVirtqNbr], VIRTIO_MAX_VIRTQ_NAME_SIZE,
+                    "requestq<%d>", uVirtqNbr - VIRTQ_REQ_BASE);
 }
 
@@ -754 +754 @@
     }
 
-    PVIRTIO_DESC_CHAIN_T pDescChain = NULL;
-    int rc = virtioCoreR3VirtqGet(pDevIns, &pThis->Virtio, EVENTQ_IDX, &pDescChain, true);
+    PVIRTQBUF pVirtqBuf = NULL;
+    int rc = virtioCoreR3VirtqBufGet(pDevIns, &pThis->Virtio, EVENTQ_IDX, &pVirtqBuf, true);
     if (rc == VERR_NOT_AVAILABLE)
     {
@@ -783 +783 @@
     RTSgBufInit(&ReqSgBuf, aReqSegs, RT_ELEMENTS(aReqSegs));
 
-    rc = virtioCoreR3VirtqPut(pDevIns, &pThis->Virtio, EVENTQ_IDX, &ReqSgBuf, pDescChain, true /*fFence*/);
+    rc = virtioCoreR3VirtqBufPut(pDevIns, &pThis->Virtio, EVENTQ_IDX, &ReqSgBuf, pVirtqBuf, true /*fFence*/);
     if (rc == VINF_SUCCESS)
         virtioCoreVirtqSync(pDevIns, &pThis->Virtio, EVENTQ_IDX, false);
     else
         LogRel(("Error writing control message to guest\n"));
-    virtioCoreR3DescChainRelease(&pThis->Virtio, pDescChain);
+    virtioCoreR3VirtqBufRelease(&pThis->Virtio, pVirtqBuf);
 
     return rc;
@@ -800 +800 @@
     RTMemFree(pReq->pbSense);
     pReq->pbSense = NULL;
-    virtioCoreR3DescChainRelease(&pThis->Virtio, pReq->pDescChain);
-    pReq->pDescChain = NULL;
+    virtioCoreR3VirtqBufRelease(&pThis->Virtio, pReq->pVirtqBuf);
+    pReq->pVirtqBuf = NULL;
     pTarget->pDrvMediaEx->pfnIoReqFree(pTarget->pDrvMediaEx, pReq->hIoReq);
 }
@@ -811 +811 @@
  * @param   pThis       VirtIO SCSI shared instance data.
  * @param   pThisCC     VirtIO SCSI ring-3 instance data.
- * @param   idxVirtq        Virtq index
- * @param   pDescChain  Pointer to pre-processed descriptor chain pulled from virtq
+ * @param   uVirtqNbr        Virtq index
+ * @param   pVirtqBuf  Pointer to pre-processed descriptor chain pulled from virtq
  * @param   pRespHdr    Response header
  * @param   pbSense     Pointer to sense buffer or NULL if none.
@@ -819 +819 @@
  * @returns VINF_SUCCESS
  */
-static int virtioScsiR3ReqErr(PPDMDEVINS pDevIns, PVIRTIOSCSI pThis, PVIRTIOSCSICC pThisCC, uint16_t idxVirtq,
-                              PVIRTIO_DESC_CHAIN_T pDescChain, REQ_RESP_HDR_T *pRespHdr, uint8_t *pbSense,
+static int virtioScsiR3ReqErr(PPDMDEVINS pDevIns, PVIRTIOSCSI pThis, PVIRTIOSCSICC pThisCC, uint16_t uVirtqNbr,
+                              PVIRTQBUF pVirtqBuf, REQ_RESP_HDR_T *pRespHdr, uint8_t *pbSense,
                               size_t cbSenseCfg)
 {
@@ -853 +853 @@
         pRespHdr->uResponse = VIRTIOSCSI_S_RESET;
 
-    virtioCoreR3VirtqPut(pDevIns, &pThis->Virtio, idxVirtq, &ReqSgBuf, pDescChain, true /* fFence */);
-    virtioCoreVirtqSync(pDevIns, &pThis->Virtio, idxVirtq);
+    virtioCoreR3VirtqBufPut(pDevIns, &pThis->Virtio, uVirtqNbr, &ReqSgBuf, pVirtqBuf, true /* fFence */);
+    virtioCoreVirtqSync(pDevIns, &pThis->Virtio, uVirtqNbr);
 
     if (!ASMAtomicDecU32(&pThis->cActiveReqs) && pThisCC->fQuiescing)
@@ -872 +872 @@
  * @param   pThis       VirtIO SCSI shared instance data.
  * @param   pThisCC     VirtIO SCSI ring-3 instance data.
- * @param   idxVirtq        Virtq index
- * @param   pDescChain  Pointer to pre-processed descriptor chain pulled from virtq
+ * @param   uVirtqNbr   Virtq index
+ * @param   pVirtqBuf   Pointer to pre-processed descriptor chain pulled from virtq
  * @param   cbResidual  The number of residual bytes or something like that.
  * @param   bStatus     The SCSI status code.
@@ -883 +883 @@
  * @returns VINF_SUCCESS
  */
-static int virtioScsiR3ReqErr4(PPDMDEVINS pDevIns, PVIRTIOSCSI pThis, PVIRTIOSCSICC pThisCC, uint16_t idxVirtq,
-                               PVIRTIO_DESC_CHAIN_T pDescChain, size_t cbResidual, uint8_t bStatus, uint8_t bResponse,
+static int virtioScsiR3ReqErr4(PPDMDEVINS pDevIns, PVIRTIOSCSI pThis, PVIRTIOSCSICC pThisCC, uint16_t uVirtqNbr,
+                               PVIRTQBUF pVirtqBuf, size_t cbResidual, uint8_t bStatus, uint8_t bResponse,
                                uint8_t *pbSense, size_t cbSense, size_t cbSenseCfg)
 {
@@ -894 +894 @@
     RespHdr.uResponse        = bResponse;
 
-    return virtioScsiR3ReqErr(pDevIns, pThis, pThisCC, idxVirtq, pDescChain, &RespHdr, pbSense, cbSenseCfg);
+    return virtioScsiR3ReqErr(pDevIns, pThis, pThisCC, uVirtqNbr, pVirtqBuf, &RespHdr, pbSense, cbSenseCfg);
 }
 
@@ -993 +993 @@
     {
         LogFunc(("cbDataIn = %u, cbDataOut = %u (cbIn = %u, cbOut = %u)\n",
-                  pReq->cbDataIn, pReq->cbDataOut, pReq->pDescChain->cbPhysReturn, pReq->pDescChain->cbPhysSend));
+                  pReq->cbDataIn, pReq->cbDataOut, pReq->pVirtqBuf->cbPhysReturn, pReq->pVirtqBuf->cbPhysSend));
         LogFunc(("xfer = %lu, residual = %u\n", cbXfer, cbResidual));
         LogFunc(("xfer direction: %s, sense written = %d, sense size = %d\n",
@@ -1016 +1016 @@
         respHdr.uResidual  = pReq->cbDataIn & UINT32_MAX;
 
-        virtioScsiR3ReqErr(pDevIns, pThis, pThisCC, pReq->idxVirtq, pReq->pDescChain, &respHdr, abSense,
+        virtioScsiR3ReqErr(pDevIns, pThis, pThisCC, pReq->uVirtqNbr, pReq->pVirtqBuf, &respHdr, abSense,
                            RT_MIN(pThis->virtioScsiConfig.uSenseSize, VIRTIOSCSI_SENSE_SIZE_MAX));
     }
@@ -1037 +1037 @@
         size_t cbReqSgBuf = RTSgBufCalcTotalLength(&ReqSgBuf);
         /** @todo r=bird: Returning here looks a little bogus... */
-        AssertMsgReturn(cbReqSgBuf <= pReq->pDescChain->cbPhysReturn,
+        AssertMsgReturn(cbReqSgBuf <= pReq->pVirtqBuf->cbPhysReturn,
                        ("Guest expected less req data (space needed: %zu, avail: %u)\n",
-                        cbReqSgBuf, pReq->pDescChain->cbPhysReturn),
+                        cbReqSgBuf, pReq->pVirtqBuf->cbPhysReturn),
                         VERR_BUFFER_OVERFLOW);
 
-        virtioCoreR3VirtqPut(pDevIns, &pThis->Virtio, pReq->idxVirtq, &ReqSgBuf, pReq->pDescChain, true /* fFence TBD */);
-        virtioCoreVirtqSync(pDevIns, &pThis->Virtio, pReq->idxVirtq);
+        virtioCoreR3VirtqBufPut(pDevIns, &pThis->Virtio, pReq->uVirtqNbr, &ReqSgBuf, pReq->pVirtqBuf, true /* fFence TBD */);
+        virtioCoreVirtqSync(pDevIns, &pThis->Virtio, pReq->uVirtqNbr);
 
         Log2(("-----------------------------------------------------------------------------------------\n"));
@@ -1072 +1072 @@
         return VINF_SUCCESS;
 
-    AssertReturn(pReq->pDescChain, VERR_INVALID_PARAMETER);
-
-    PVIRTIOSGBUF pSgPhysReturn = pReq->pDescChain->pSgPhysReturn;
+    AssertReturn(pReq->pVirtqBuf, VERR_INVALID_PARAMETER);
+
+    PVIRTIOSGBUF pSgPhysReturn = pReq->pVirtqBuf->pSgPhysReturn;
     virtioCoreSgBufAdvance(pSgPhysReturn, offDst);
 
@@ -1096 +1096 @@
 
     Log3Func((".... Copied %lu bytes from %lu byte guest buffer, residual=%lu\n",
-              cbCopy, pReq->pDescChain->cbPhysReturn, pReq->pDescChain->cbPhysReturn - cbCopy));
+              cbCopy, pReq->pVirtqBuf->cbPhysReturn, pReq->pVirtqBuf->cbPhysReturn - cbCopy));
 
     return VINF_SUCCESS;
@@ -1117 +1117 @@
         return VINF_SUCCESS;
 
-    PVIRTIOSGBUF pSgPhysSend = pReq->pDescChain->pSgPhysSend;
+    PVIRTIOSGBUF pSgPhysSend = pReq->pVirtqBuf->pSgPhysSend;
     virtioCoreSgBufAdvance(pSgPhysSend, offSrc);
 
@@ -1133 +1133 @@
 
     Log2Func((".... Copied %lu bytes to %lu byte guest buffer, residual=%lu\n",
-              cbCopy, pReq->pDescChain->cbPhysReturn, pReq->pDescChain->cbPhysReturn - cbCopy));
+              cbCopy, pReq->pVirtqBuf->cbPhysReturn, pReq->pVirtqBuf->cbPhysReturn - cbCopy));
 
     return VINF_SUCCESS;
@@ -1144 +1144 @@
  */
 static int virtioScsiR3ReqSubmit(PPDMDEVINS pDevIns, PVIRTIOSCSI pThis, PVIRTIOSCSICC pThisCC,
-                                 uint16_t idxVirtq, PVIRTIO_DESC_CHAIN_T pDescChain)
+                                 uint16_t uVirtqNbr, PVIRTQBUF pVirtqBuf)
 {
 
@@ -1164 +1164 @@
      */
     size_t const cbReqHdr = sizeof(REQ_CMD_HDR_T) + cbCdb;
-    AssertReturn(pDescChain->cbPhysSend >= cbReqHdr, VERR_INVALID_PARAMETER);
+    AssertReturn(pVirtqBuf->cbPhysSend >= cbReqHdr, VERR_INVALID_PARAMETER);
 
     AssertCompile(VIRTIOSCSI_CDB_SIZE_MAX < 4096);
@@ -1182 +1182 @@
     {
         size_t cbSeg = cbReqHdr - offReq;
-        RTGCPHYS GCPhys = virtioCoreSgBufGetNextSegment(pDescChain->pSgPhysSend, &cbSeg);
+        RTGCPHYS GCPhys = virtioCoreSgBufGetNextSegment(pVirtqBuf->pSgPhysSend, &cbSeg);
         PDMDevHlpPCIPhysReadMeta(pDevIns, GCPhys, &VirtqReq.ab[offReq], cbSeg);
         offReq += cbSeg;
@@ -1218 +1218 @@
     uint32_t const offDataOut = sizeof(REQ_CMD_HDR_T)  + cbCdb;
     uint32_t const offDataIn  = sizeof(REQ_RESP_HDR_T) + cbSenseCfg;
-    size_t   const cbDataOut  = pDescChain->cbPhysSend - offDataOut;
+    size_t   const cbDataOut  = pVirtqBuf->cbPhysSend - offDataOut;
     /** @todo r=bird: Validate cbPhysReturn properly? I've just RT_MAX'ed it for now. */
-    size_t   const cbDataIn   = RT_MAX(pDescChain->cbPhysReturn, offDataIn) - offDataIn;
+    size_t   const cbDataIn   = RT_MAX(pVirtqBuf->cbPhysReturn, offDataIn) - offDataIn;
     Assert(offDataOut <= UINT16_MAX);
     Assert(offDataIn  <= UINT16_MAX);
@@ -1232 +1232 @@
     {
         Log2Func(("Error submitting request, bad LUN format\n"));
-        return virtioScsiR3ReqErr4(pDevIns, pThis, pThisCC, idxVirtq, pDescChain, cbDataIn + cbDataOut, 0 /*bStatus*/,
+        return virtioScsiR3ReqErr4(pDevIns, pThis, pThisCC, uVirtqNbr, pVirtqBuf, cbDataIn + cbDataOut, 0 /*bStatus*/,
                                    VIRTIOSCSI_S_FAILURE, NULL /*pbSense*/, 0 /*cbSense*/, cbSenseCfg);
     }
@@ -1247 +1247 @@
                               0, SCSI_SENSE_ILLEGAL_REQUEST,
                               0, 0, 0, 0, 10, SCSI_ASC_LOGICAL_UNIT_NOT_SUPPORTED, 0, 0 };
-        return virtioScsiR3ReqErr4(pDevIns, pThis, pThisCC, idxVirtq, pDescChain, cbDataIn + cbDataOut, SCSI_STATUS_CHECK_CONDITION,
+        return virtioScsiR3ReqErr4(pDevIns, pThis, pThisCC, uVirtqNbr, pVirtqBuf, cbDataIn + cbDataOut, SCSI_STATUS_CHECK_CONDITION,
                                    VIRTIOSCSI_S_BAD_TARGET, abSense, sizeof(abSense), cbSenseCfg);
     }
@@ -1258 +1258 @@
                               0, SCSI_SENSE_ILLEGAL_REQUEST,
                               0, 0, 0, 0, 10, SCSI_ASC_LOGICAL_UNIT_NOT_SUPPORTED, 0, 0 };
-        return virtioScsiR3ReqErr4(pDevIns, pThis, pThisCC, idxVirtq, pDescChain, cbDataIn + cbDataOut, SCSI_STATUS_CHECK_CONDITION,
+        return virtioScsiR3ReqErr4(pDevIns, pThis, pThisCC, uVirtqNbr, pVirtqBuf, cbDataIn + cbDataOut, SCSI_STATUS_CHECK_CONDITION,
                                    VIRTIOSCSI_S_OK, abSense, sizeof(abSense), cbSenseCfg);
     }
@@ -1266 +1266 @@
     {
         Log2Func(("Aborting req submission because reset is in progress\n"));
-        return virtioScsiR3ReqErr4(pDevIns, pThis, pThisCC, idxVirtq, pDescChain, cbDataIn + cbDataOut, SCSI_STATUS_OK,
+        return virtioScsiR3ReqErr4(pDevIns, pThis, pThisCC, uVirtqNbr, pVirtqBuf, cbDataIn + cbDataOut, SCSI_STATUS_OK,
                                    VIRTIOSCSI_S_RESET, NULL /*pbSense*/, 0 /*cbSense*/, cbSenseCfg);
     }
@@ -1277 +1277 @@
         uint8_t abSense[] = { RT_BIT(7) | SCSI_SENSE_RESPONSE_CODE_CURR_FIXED,
                               0, SCSI_SENSE_ILLEGAL_REQUEST, 0, 0, 0, 0, 10, 0, 0, 0 };
-        return virtioScsiR3ReqErr4(pDevIns, pThis, pThisCC, idxVirtq, pDescChain, cbDataIn + cbDataOut, SCSI_STATUS_CHECK_CONDITION,
+        return virtioScsiR3ReqErr4(pDevIns, pThis, pThisCC, uVirtqNbr, pVirtqBuf, cbDataIn + cbDataOut, SCSI_STATUS_CHECK_CONDITION,
                                    VIRTIOSCSI_S_FAILURE, abSense, sizeof(abSense), cbSenseCfg);
     }
@@ -1295 +1295 @@
     pReq->hIoReq      = hIoReq;
     pReq->pTarget     = pTarget;
-    pReq->idxVirtq    = idxVirtq;
+    pReq->uVirtqNbr    = uVirtqNbr;
     pReq->cbDataIn    = cbDataIn;
     pReq->cbDataOut   = cbDataOut;
-    pReq->pDescChain  = pDescChain;
-    virtioCoreR3DescChainRetain(pDescChain); /* (For pReq->pDescChain. Released by virtioScsiR3FreeReq.) */
+    pReq->pVirtqBuf  = pVirtqBuf;
+    virtioCoreR3VirtqBufRetain(pVirtqBuf); /* (For pReq->pVirtqBuf. Released by virtioScsiR3FreeReq.) */
     pReq->uDataInOff  = offDataIn;
     pReq->uDataOutOff = offDataOut;
@@ -1342 +1342 @@
         respHdr.uResponse  = VIRTIOSCSI_S_FAILURE;
         respHdr.uResidual  = (cbDataIn + cbDataOut) & UINT32_MAX;
-        virtioScsiR3ReqErr(pDevIns, pThis, pThisCC, idxVirtq, pDescChain, &respHdr, abSense, cbSenseCfg);
+        virtioScsiR3ReqErr(pDevIns, pThis, pThisCC, uVirtqNbr, pVirtqBuf, &respHdr, abSense, cbSenseCfg);
         virtioScsiR3FreeReq(pTarget, pReq);
     }
@@ -1356 +1356 @@
  * @param   pThis       VirtIO SCSI shared instance data.
  * @param   pThisCC     VirtIO SCSI ring-3 instance data.
- * @param   idxVirtq    CONTROLQ_IDX
- * @param   pDescChain  Descriptor chain to process.
+ * @param   uVirtqNbr   CONTROLQ_IDX
+ * @param   pVirtqBuf   Descriptor chain to process.
  */
 static int virtioScsiR3Ctrl(PPDMDEVINS pDevIns, PVIRTIOSCSI pThis, PVIRTIOSCSICC pThisCC,
-                            uint16_t idxVirtq, PVIRTIO_DESC_CHAIN_T pDescChain)
-{
-    AssertReturn(pDescChain->cbPhysSend >= RT_MIN(sizeof(VIRTIOSCSI_CTRL_AN_T),
+                            uint16_t uVirtqNbr, PVIRTQBUF pVirtqBuf)
+{
+    AssertReturn(pVirtqBuf->cbPhysSend >= RT_MIN(sizeof(VIRTIOSCSI_CTRL_AN_T),
                                                   sizeof(VIRTIOSCSI_CTRL_TMF_T)), 0);
 
@@ -1371 +1371 @@
     RT_ZERO(ScsiCtrlUnion);
 
-    size_t const cbCtrl = RT_MIN(pDescChain->cbPhysSend, sizeof(VIRTIO_SCSI_CTRL_UNION_T));
+    size_t const cbCtrl = RT_MIN(pVirtqBuf->cbPhysSend, sizeof(VIRTIO_SCSI_CTRL_UNION_T));
     for (size_t offCtrl = 0; offCtrl < cbCtrl; )
     {
         size_t cbSeg = cbCtrl - offCtrl;
-        RTGCPHYS GCPhys = virtioCoreSgBufGetNextSegment(pDescChain->pSgPhysSend, &cbSeg);
+        RTGCPHYS GCPhys = virtioCoreSgBufGetNextSegment(pVirtqBuf->pSgPhysSend, &cbSeg);
         PDMDevHlpPCIPhysReadMeta(pDevIns, GCPhys, &ScsiCtrlUnion.ab[offCtrl], cbSeg);
         offCtrl += cbSeg;
@@ -1381 +1381 @@
 
     AssertReturn(   (ScsiCtrlUnion.Type.uType == VIRTIOSCSI_T_TMF
-                     && pDescChain->cbPhysSend >= sizeof(VIRTIOSCSI_CTRL_TMF_T))
+                     && pVirtqBuf->cbPhysSend >= sizeof(VIRTIOSCSI_CTRL_TMF_T))
                  || ( (   ScsiCtrlUnion.Type.uType == VIRTIOSCSI_T_AN_QUERY
                        || ScsiCtrlUnion.Type.uType == VIRTIOSCSI_T_AN_SUBSCRIBE)
-                     && pDescChain->cbPhysSend >= sizeof(VIRTIOSCSI_CTRL_AN_T)),
+                     && pVirtqBuf->cbPhysSend >= sizeof(VIRTIOSCSI_CTRL_AN_T)),
                     0 /** @todo r=bird: what kind of status is '0' here? */);
 
@@ -1401 +1401 @@
             uint32_t uScsiLun = RT_MAKE_U16(ScsiCtrlUnion.Tmf.abScsiLun[3], ScsiCtrlUnion.Tmf.abScsiLun[2]) & 0x3fff;
             Log2Func(("[%s] (Target: %d LUN: %d)  Task Mgt Function: %s\n",
-                      VIRTQNAME(idxVirtq), uTarget, uScsiLun, virtioGetTMFTypeText(ScsiCtrlUnion.Tmf.uSubtype)));
+                      VIRTQNAME(uVirtqNbr), uTarget, uScsiLun, virtioGetTMFTypeText(ScsiCtrlUnion.Tmf.uSubtype)));
 
             if (uTarget >= pThis->cTargets || !pThisCC->paTargetInstances[uTarget].fPresent)
@@ -1462 +1462 @@
                 virtioGetControlAsyncMaskText(szTypeText, sizeof(szTypeText), ScsiCtrlUnion.AsyncNotify.fEventsRequested);
                 Log2Func(("[%s] (Target: %d LUN: %d)  Async. Notification Query: %s\n",
-                          VIRTQNAME(idxVirtq), uTarget, uScsiLun, szTypeText));
+                          VIRTQNAME(uVirtqNbr), uTarget, uScsiLun, szTypeText));
             }
 #endif
@@ -1487 +1487 @@
                 virtioGetControlAsyncMaskText(szTypeText, sizeof(szTypeText), ScsiCtrlUnion.AsyncNotify.fEventsRequested);
                 Log2Func(("[%s] (Target: %d LUN: %d)  Async. Notification Subscribe: %s\n",
-                          VIRTQNAME(idxVirtq), uTarget, uScsiLun, szTypeText));
+                          VIRTQNAME(uVirtqNbr), uTarget, uScsiLun, szTypeText));
             }
 #endif
@@ -1508 +1508 @@
         default:
         {
-            LogFunc(("Unknown control type extracted from %s: %u\n", VIRTQNAME(idxVirtq), ScsiCtrlUnion.Type.uType));
+            LogFunc(("Unknown control type extracted from %s: %u\n", VIRTQNAME(uVirtqNbr), ScsiCtrlUnion.Type.uType));
 
             bResponse = VIRTIOSCSI_S_FAILURE;
@@ -1527 +1527 @@
     RTSgBufInit(&ReqSgBuf, aReqSegs, cSegs);
 
-    virtioCoreR3VirtqPut(pDevIns, &pThis->Virtio, idxVirtq, &ReqSgBuf, pDescChain, true /*fFence*/);
-    virtioCoreVirtqSync(pDevIns, &pThis->Virtio, idxVirtq);
+    virtioCoreR3VirtqBufPut(pDevIns, &pThis->Virtio, uVirtqNbr, &ReqSgBuf, pVirtqBuf, true /*fFence*/);
+    virtioCoreVirtqSync(pDevIns, &pThis->Virtio, uVirtqNbr);
 
     return VINF_SUCCESS;
@@ -1547 +1547 @@
 static DECLCALLBACK(int) virtioScsiR3WorkerThread(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
 {
-    uint16_t const      idxVirtq  = (uint16_t)(uintptr_t)pThread->pvUser;
+    uint16_t const      uVirtqNbr  = (uint16_t)(uintptr_t)pThread->pvUser;
     PVIRTIOSCSI         pThis     = PDMDEVINS_2_DATA(pDevIns, PVIRTIOSCSI);
     PVIRTIOSCSICC       pThisCC   = PDMDEVINS_2_DATA_CC(pDevIns, PVIRTIOSCSICC);
-    PVIRTIOSCSIWORKER   pWorker   = &pThis->aWorkers[idxVirtq];
-    PVIRTIOSCSIWORKERR3 pWorkerR3 = &pThisCC->aWorkers[idxVirtq];
+    PVIRTIOSCSIWORKER   pWorker   = &pThis->aWorkers[uVirtqNbr];
+    PVIRTIOSCSIWORKERR3 pWorkerR3 = &pThisCC->aWorkers[uVirtqNbr];
 
     if (pThread->enmState == PDMTHREADSTATE_INITIALIZING)
@@ -1558 +1558 @@
     while (pThread->enmState == PDMTHREADSTATE_RUNNING)
     {
-        if (!pWorkerR3->cRedoDescs && IS_VIRTQ_EMPTY(pDevIns, &pThis->Virtio, idxVirtq))
+        if (!pWorkerR3->cRedoDescs && IS_VIRTQ_EMPTY(pDevIns, &pThis->Virtio, uVirtqNbr))
         {
             /* Atomic interlocks avoid missing alarm while going to sleep & notifier waking the awoken */
@@ -1565 +1565 @@
             if (!fNotificationSent)
             {
-                Log6Func(("%s worker sleeping...\n", VIRTQNAME(idxVirtq)));
+                Log6Func(("%s worker sleeping...\n", VIRTQNAME(uVirtqNbr)));
                 Assert(ASMAtomicReadBool(&pWorker->fSleeping));
                 int rc = PDMDevHlpSUPSemEventWaitNoResume(pDevIns, pWorker->hEvtProcess, RT_INDEFINITE_WAIT);
@@ -1573 +1573 @@
                 if (rc == VERR_INTERRUPTED)
                     continue;
-                Log6Func(("%s worker woken\n", VIRTQNAME(idxVirtq)));
+                Log6Func(("%s worker woken\n", VIRTQNAME(uVirtqNbr)));
                 ASMAtomicWriteBool(&pWorker->fNotified, false);
             }
@@ -1579 +1579 @@
         }
 
-        if (!pThis->afVirtqAttached[idxVirtq])
+        if (!pThis->afVirtqAttached[uVirtqNbr])
         {
-            LogFunc(("%s queue not attached, worker aborting...\n", VIRTQNAME(idxVirtq)));
+            LogFunc(("%s queue not attached, worker aborting...\n", VIRTQNAME(uVirtqNbr)));
             break;
         }
@@ -1589 +1589 @@
              for (int i = 0; i < pWorkerR3->cRedoDescs; i++)
              {
-                  PVIRTIO_DESC_CHAIN_T pDescChain;
-                  int rc = virtioCoreR3DescChainGet(pDevIns, &pThis->Virtio, idxVirtq,
-                                                    pWorkerR3->auRedoDescs[i], &pDescChain);
+                  PVIRTQBUF pVirtqBuf;
+                  int rc = virtioCoreR3VirtqBufGet(pDevIns, &pThis->Virtio, uVirtqNbr,
+                                                    pWorkerR3->auRedoDescs[i], &pVirtqBuf);
                   if (RT_FAILURE(rc))
                       LogRel(("Error fetching desc chain to redo, %Rrc", rc));
 
-                  rc = virtioScsiR3ReqSubmit(pDevIns, pThis, pThisCC, idxVirtq, pDescChain);
+                  rc = virtioScsiR3ReqSubmit(pDevIns, pThis, pThisCC, uVirtqNbr, pVirtqBuf);
                   if (RT_FAILURE(rc))
                       LogRel(("Error submitting req packet, resetting %Rrc", rc));
 
-                  virtioCoreR3DescChainRelease(&pThis->Virtio, pDescChain);
+                  virtioCoreR3VirtqBufRelease(&pThis->Virtio, pVirtqBuf);
              }
              pWorkerR3->cRedoDescs = 0;
 
-             Log6Func(("fetching next descriptor chain from %s\n", VIRTQNAME(idxVirtq)));
-             PVIRTIO_DESC_CHAIN_T pDescChain = NULL;
-             int rc = virtioCoreR3VirtqGet(pDevIns, &pThis->Virtio, idxVirtq, &pDescChain, true);
+             Log6Func(("fetching next descriptor chain from %s\n", VIRTQNAME(uVirtqNbr)));
+             PVIRTQBUF pVirtqBuf = NULL;
+             int rc = virtioCoreR3VirtqBufGet(pDevIns, &pThis->Virtio, uVirtqNbr, &pVirtqBuf, true);
              if (rc == VERR_NOT_AVAILABLE)
              {
-                 Log6Func(("Nothing found in %s\n", VIRTQNAME(idxVirtq)));
+                 Log6Func(("Nothing found in %s\n", VIRTQNAME(uVirtqNbr)));
                  continue;
              }
 
              AssertRC(rc);
-             if (idxVirtq == CONTROLQ_IDX)
-                 virtioScsiR3Ctrl(pDevIns, pThis, pThisCC, idxVirtq, pDescChain);
+             if (uVirtqNbr == CONTROLQ_IDX)
+                 virtioScsiR3Ctrl(pDevIns, pThis, pThisCC, uVirtqNbr, pVirtqBuf);
              else /* request queue index */
              {
-                 rc = virtioScsiR3ReqSubmit(pDevIns, pThis, pThisCC, idxVirtq, pDescChain);
+                 rc = virtioScsiR3ReqSubmit(pDevIns, pThis, pThisCC, uVirtqNbr, pVirtqBuf);
                  if (RT_FAILURE(rc))
                      LogRel(("Error submitting req packet, resetting %Rrc", rc));
              }
 
-             virtioCoreR3DescChainRelease(&pThis->Virtio, pDescChain);
+             virtioCoreR3VirtqBufRelease(&pThis->Virtio, pVirtqBuf);
         }
     }
@@ -1967 +1967 @@
 
     virtioScsiSetVirtqNames(pThis);
-    for (int idxVirtq = 0; idxVirtq < VIRTIOSCSI_VIRTQ_CNT; idxVirtq++)
-        pHlp->pfnSSMGetBool(pSSM, &pThis->afVirtqAttached[idxVirtq]);
+    for (int uVirtqNbr = 0; uVirtqNbr < VIRTIOSCSI_VIRTQ_CNT; uVirtqNbr++)
+        pHlp->pfnSSMGetBool(pSSM, &pThis->afVirtqAttached[uVirtqNbr]);
 
     pHlp->pfnSSMGetU32(pSSM,  &pThis->virtioScsiConfig.uNumVirtqs);
@@ -2007 +2007 @@
                                               cReqsRedo, VIRTQ_MAX_ENTRIES));
 
-        for (uint16_t idxVirtq = VIRTQ_REQ_BASE; idxVirtq < VIRTIOSCSI_VIRTQ_CNT; idxVirtq++)
+        for (uint16_t uVirtqNbr = VIRTQ_REQ_BASE; uVirtqNbr < VIRTIOSCSI_VIRTQ_CNT; uVirtqNbr++)
         {
-            PVIRTIOSCSIWORKERR3 pWorkerR3 = &pThisCC->aWorkers[idxVirtq];
+            PVIRTIOSCSIWORKERR3 pWorkerR3 = &pThisCC->aWorkers[uVirtqNbr];
             pWorkerR3->cRedoDescs = 0;
         }
@@ -2015 +2015 @@
         for (int i = 0; i < cReqsRedo; i++)
         {
-            uint16_t idxVirtq;
-            rc = pHlp->pfnSSMGetU16(pSSM, &idxVirtq);
+            uint16_t uVirtqNbr;
+            rc = pHlp->pfnSSMGetU16(pSSM, &uVirtqNbr);
             AssertRCReturn(rc, rc);
-            AssertReturn(idxVirtq < VIRTIOSCSI_VIRTQ_CNT,
+            AssertReturn(uVirtqNbr < VIRTIOSCSI_VIRTQ_CNT,
                          pHlp->pfnSSMSetLoadError(pSSM, VERR_SSM_DATA_UNIT_FORMAT_CHANGED, RT_SRC_POS,
                                                   N_("Bad queue index for re-do in saved state (%#x, max %#x)"),
-                                                  idxVirtq, VIRTIOSCSI_VIRTQ_CNT - 1));
+                                                  uVirtqNbr, VIRTIOSCSI_VIRTQ_CNT - 1));
 
             uint16_t idxHead;
@@ -2031 +2031 @@
                                                   idxHead, VIRTQ_MAX_ENTRIES - 1));
 
-            PVIRTIOSCSIWORKERR3 pWorkerR3 = &pThisCC->aWorkers[idxVirtq];
+            PVIRTIOSCSIWORKERR3 pWorkerR3 = &pThisCC->aWorkers[uVirtqNbr];
             pWorkerR3->auRedoDescs[pWorkerR3->cRedoDescs++] = idxHead;
             pWorkerR3->cRedoDescs %= VIRTQ_MAX_ENTRIES;
@@ -2045 +2045 @@
      * Nudge request queue workers
      */
-    for (int idxVirtq = VIRTQ_REQ_BASE; idxVirtq < VIRTIOSCSI_VIRTQ_CNT; idxVirtq++)
-    {
-        if (pThis->afVirtqAttached[idxVirtq])
+    for (int uVirtqNbr = VIRTQ_REQ_BASE; uVirtqNbr < VIRTIOSCSI_VIRTQ_CNT; uVirtqNbr++)
+    {
+        if (pThis->afVirtqAttached[uVirtqNbr])
         {
-            LogFunc(("Waking %s worker.\n", VIRTQNAME(idxVirtq)));
-            int rc2 = PDMDevHlpSUPSemEventSignal(pDevIns, pThis->aWorkers[idxVirtq].hEvtProcess);
+            LogFunc(("Waking %s worker.\n", VIRTQNAME(uVirtqNbr)));
+            int rc2 = PDMDevHlpSUPSemEventSignal(pDevIns, pThis->aWorkers[uVirtqNbr].hEvtProcess);
             AssertRCReturn(rc, rc2);
         }
@@ -2069 +2069 @@
     LogFunc(("SAVE EXEC!!\n"));
 
-    for (int idxVirtq = 0; idxVirtq < VIRTIOSCSI_VIRTQ_CNT; idxVirtq++)
-        pHlp->pfnSSMPutBool(pSSM, pThis->afVirtqAttached[idxVirtq]);
+    for (int uVirtqNbr = 0; uVirtqNbr < VIRTIOSCSI_VIRTQ_CNT; uVirtqNbr++)
+        pHlp->pfnSSMPutBool(pSSM, pThis->afVirtqAttached[uVirtqNbr]);
 
     pHlp->pfnSSMPutU32(pSSM,  pThis->virtioScsiConfig.uNumVirtqs);
@@ -2117 +2117 @@
                  while(--cReqsRedo)
                  {
-                    pHlp->pfnSSMPutU16(pSSM, pReq->idxVirtq);
-                    pHlp->pfnSSMPutU16(pSSM, pReq->pDescChain->uHeadIdx);
+                    pHlp->pfnSSMPutU16(pSSM, pReq->uVirtqNbr);
+                    pHlp->pfnSSMPutU16(pSSM, pReq->pVirtqBuf->uHeadIdx);
 
                     rc = pTarget->pDrvMediaEx->pfnIoReqQuerySuspendedNext(pTarget->pDrvMediaEx, hIoReq,
@@ -2335 +2335 @@
      * be awake due to new reqs coming in.
      */
-    for (uint16_t idxVirtq = 0; idxVirtq < VIRTIOSCSI_REQ_VIRTQ_CNT; idxVirtq++)
-    {
-        if (ASMAtomicReadBool(&pThis->aWorkers[idxVirtq].fSleeping))
+    for (uint16_t uVirtqNbr = 0; uVirtqNbr < VIRTIOSCSI_REQ_VIRTQ_CNT; uVirtqNbr++)
+    {
+        if (ASMAtomicReadBool(&pThis->aWorkers[uVirtqNbr].fSleeping))
         {
-            Log6Func(("waking %s worker.\n", VIRTQNAME(idxVirtq)));
-            int rc = PDMDevHlpSUPSemEventSignal(pDevIns, pThis->aWorkers[idxVirtq].hEvtProcess);
+            Log6Func(("waking %s worker.\n", VIRTQNAME(uVirtqNbr)));
+            int rc = PDMDevHlpSUPSemEventSignal(pDevIns, pThis->aWorkers[uVirtqNbr].hEvtProcess);
             AssertRC(rc);
         }
@@ -2414 +2414 @@
     pThisCC->pMediaNotify = NULL;
 
-    for (unsigned idxVirtq = 0; idxVirtq < VIRTIOSCSI_VIRTQ_CNT; idxVirtq++)
-    {
-        PVIRTIOSCSIWORKER pWorker = &pThis->aWorkers[idxVirtq];
+    for (unsigned uVirtqNbr = 0; uVirtqNbr < VIRTIOSCSI_VIRTQ_CNT; uVirtqNbr++)
+    {
+        PVIRTIOSCSIWORKER pWorker = &pThis->aWorkers[uVirtqNbr];
         if (pWorker->hEvtProcess != NIL_SUPSEMEVENT)
         {
@@ -2423 +2423 @@
         }
 
-        if (pThisCC->aWorkers[idxVirtq].pThread)
+        if (pThisCC->aWorkers[uVirtqNbr].pThread)
         {
             /* Destroy the thread. */
             int rcThread;
-            int rc = PDMDevHlpThreadDestroy(pDevIns, pThisCC->aWorkers[idxVirtq].pThread, &rcThread);
+            int rc = PDMDevHlpThreadDestroy(pDevIns, pThisCC->aWorkers[uVirtqNbr].pThread, &rcThread);
             if (RT_FAILURE(rc) || RT_FAILURE(rcThread))
                 AssertMsgFailed(("%s Failed to destroythread rc=%Rrc rcThread=%Rrc\n",
                                  __FUNCTION__, rc, rcThread));
-           pThisCC->aWorkers[idxVirtq].pThread = NULL;
+           pThisCC->aWorkers[uVirtqNbr].pThread = NULL;
         }
     }
@@ -2526 +2526 @@
 
     /* Attach the queues and create worker threads for them: */
-    for (uint16_t idxVirtq = 0; idxVirtq < VIRTIOSCSI_VIRTQ_CNT; idxVirtq++)
-    {
-        rc = virtioCoreR3VirtqAttach(&pThis->Virtio, idxVirtq, VIRTQNAME(idxVirtq));
+    for (uint16_t uVirtqNbr = 0; uVirtqNbr < VIRTIOSCSI_VIRTQ_CNT; uVirtqNbr++)
+    {
+        rc = virtioCoreR3VirtqAttach(&pThis->Virtio, uVirtqNbr, VIRTQNAME(uVirtqNbr));
         if (RT_FAILURE(rc))
             continue;
-        if (idxVirtq == CONTROLQ_IDX || IS_REQ_VIRTQ(idxVirtq))
+        if (uVirtqNbr == CONTROLQ_IDX || IS_REQ_VIRTQ(uVirtqNbr))
         {
-            rc = PDMDevHlpThreadCreate(pDevIns, &pThisCC->aWorkers[idxVirtq].pThread,
-                                       (void *)(uintptr_t)idxVirtq, virtioScsiR3WorkerThread,
-                                       virtioScsiR3WorkerWakeUp, 0, RTTHREADTYPE_IO, VIRTQNAME(idxVirtq));
+            rc = PDMDevHlpThreadCreate(pDevIns, &pThisCC->aWorkers[uVirtqNbr].pThread,
+                                       (void *)(uintptr_t)uVirtqNbr, virtioScsiR3WorkerThread,
+                                       virtioScsiR3WorkerWakeUp, 0, RTTHREADTYPE_IO, VIRTQNAME(uVirtqNbr));
             if (rc != VINF_SUCCESS)
             {
-                LogRel(("Error creating thread for Virtual Virtq %s: %Rrc\n", VIRTQNAME(idxVirtq), rc));
+                LogRel(("Error creating thread for Virtual Virtq %s: %Rrc\n", VIRTQNAME(uVirtqNbr), rc));
                 return rc;
             }
 
-            rc = PDMDevHlpSUPSemEventCreate(pDevIns, &pThis->aWorkers[idxVirtq].hEvtProcess);
+            rc = PDMDevHlpSUPSemEventCreate(pDevIns, &pThis->aWorkers[uVirtqNbr].hEvtProcess);
             if (RT_FAILURE(rc))
                 return PDMDevHlpVMSetError(pDevIns, rc, RT_SRC_POS,
                                            N_("DevVirtioSCSI: Failed to create SUP event semaphore"));
         }
-        pThis->afVirtqAttached[idxVirtq] = true;
+        pThis->afVirtqAttached[uVirtqNbr] = true;
     }
 

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

@@ -1 +1 @@
 /* $Id$ */
+
 /** @file
- * Virtio_1_0 - Virtio Common (PCI, feature & config mgt, queue mgt & proxy, notification mgt)
+ * VirtioCore - Virtio Core (PCI, feature & config mgt, queue mgt & proxy, notification mgt)
  */
 
@@ -35 +36 @@
 #include <VBox/AssertGuest.h>
 #include <VBox/vmm/pdmdev.h>
-#include "Virtio_1_0.h"
+#include "VirtioCore.h"
 
 
@@ -42 +43 @@
 *********************************************************************************************************************************/
 #define INSTANCE(a_pVirtio)                 ((a_pVirtio)->szInstance)
-#define VIRTQNAME(a_pVirtio, a_idxVirtq)    ((a_pVirtio)->aVirtqState[(a_idxVirtq)].szVirtqName)
+#define VIRTQNAME(a_pVirtio, a_uVirtqNbr)    ((a_pVirtio)->aVirtqState[(a_uVirtqNbr)].szVirtqName)
 #define IS_DRIVER_OK(a_pVirtio)             ((a_pVirtio)->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK)
 #define IS_VIRTQ_EMPTY(pDevIns, pVirtio, pVirtqState) \
@@ -135 +136 @@
 /* Internal Functions */
 
-static void virtioCoreNotifyGuestDriver(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq);
+static void virtioCoreNotifyGuestDriver(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
 static int  virtioKick(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint8_t uCause, uint16_t uVec);
 
@@ -145 +146 @@
  */
 #ifdef IN_RING3
-DECLINLINE(void) virtioReadDesc(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq,
+DECLINLINE(void) virtioReadDesc(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
                                 uint32_t idxDesc, PVIRTQ_DESC_T pDesc)
 {
     AssertMsg(pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK, ("Called with guest driver not ready\n"));
-    uint16_t const cVirtqItems = RT_MAX(pVirtio->uVirtqSize[idxVirtq], 1); /* Make sure to avoid div-by-zero. */
+    uint16_t const cVirtqItems = RT_MAX(pVirtio->uVirtqSize[uVirtqNbr], 1); /* Make sure to avoid div-by-zero. */
     PDMDevHlpPCIPhysRead(pDevIns,
-                      pVirtio->aGCPhysVirtqDesc[idxVirtq] + sizeof(VIRTQ_DESC_T) * (idxDesc % cVirtqItems),
+                      pVirtio->aGCPhysVirtqDesc[uVirtqNbr] + sizeof(VIRTQ_DESC_T) * (idxDesc % cVirtqItems),
                       pDesc, sizeof(VIRTQ_DESC_T));
 }
@@ -160 +161 @@
  */
 #ifdef IN_RING3
-DECLINLINE(uint16_t) virtioReadAvailDescIdx(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq, uint32_t availIdx)
+DECLINLINE(uint16_t) virtioReadAvailDescIdx(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, uint32_t availIdx)
 {
     uint16_t uDescIdx;
     AssertMsg(pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK, ("Called with guest driver not ready\n"));
-    uint16_t const cVirtqItems = RT_MAX(pVirtio->uVirtqSize[idxVirtq], 1); /* Make sure to avoid div-by-zero. */
+    uint16_t const cVirtqItems = RT_MAX(pVirtio->uVirtqSize[uVirtqNbr], 1); /* Make sure to avoid div-by-zero. */
     PDMDevHlpPCIPhysRead(pDevIns,
-                        pVirtio->aGCPhysVirtqAvail[idxVirtq]
+                        pVirtio->aGCPhysVirtqAvail[uVirtqNbr]
                       + RT_UOFFSETOF_DYN(VIRTQ_AVAIL_T, auRing[availIdx % cVirtqItems]),
                       &uDescIdx, sizeof(uDescIdx));
@@ -172 +173 @@
 }
 
-DECLINLINE(uint16_t) virtioReadAvailUsedEvent(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq)
+DECLINLINE(uint16_t) virtioReadAvailUsedEvent(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
 {
     uint16_t uUsedEventIdx;
@@ -178 +179 @@
     AssertMsg(pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK, ("Called with guest driver not ready\n"));
     PDMDevHlpPCIPhysRead(pDevIns,
-                      pVirtio->aGCPhysVirtqAvail[idxVirtq] + RT_UOFFSETOF_DYN(VIRTQ_AVAIL_T, auRing[pVirtio->uVirtqSize[idxVirtq]]),
+                      pVirtio->aGCPhysVirtqAvail[uVirtqNbr] + RT_UOFFSETOF_DYN(VIRTQ_AVAIL_T, auRing[pVirtio->uVirtqSize[uVirtqNbr]]),
                       &uUsedEventIdx, sizeof(uUsedEventIdx));
     return uUsedEventIdx;
@@ -184 +185 @@
 #endif
 
-DECLINLINE(uint16_t) virtioReadAvailRingIdx(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq)
+DECLINLINE(uint16_t) virtioReadAvailRingIdx(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
 {
     uint16_t uIdx = 0;
     AssertMsg(pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK, ("Called with guest driver not ready\n"));
     PDMDevHlpPCIPhysRead(pDevIns,
-                      pVirtio->aGCPhysVirtqAvail[idxVirtq] + RT_UOFFSETOF(VIRTQ_AVAIL_T, uIdx),
+                      pVirtio->aGCPhysVirtqAvail[uVirtqNbr] + RT_UOFFSETOF(VIRTQ_AVAIL_T, uIdx),
                       &uIdx, sizeof(uIdx));
     return uIdx;
 }
 
-DECLINLINE(uint16_t) virtioReadAvailRingFlags(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq)
+DECLINLINE(uint16_t) virtioReadAvailRingFlags(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
 {
     uint16_t fFlags = 0;
     AssertMsg(pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK, ("Called with guest driver not ready\n"));
     PDMDevHlpPCIPhysRead(pDevIns,
-                      pVirtio->aGCPhysVirtqAvail[idxVirtq] + RT_UOFFSETOF(VIRTQ_AVAIL_T, fFlags),
+                      pVirtio->aGCPhysVirtqAvail[uVirtqNbr] + RT_UOFFSETOF(VIRTQ_AVAIL_T, fFlags),
                       &fFlags, sizeof(fFlags));
     return fFlags;
@@ -211 +212 @@
 
 #ifdef IN_RING3
-DECLINLINE(void) virtioWriteUsedElem(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq,
+DECLINLINE(void) virtioWriteUsedElem(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
                                      uint32_t usedIdx, uint32_t uDescIdx, uint32_t uLen)
 {
     VIRTQ_USED_ELEM_T elem = { uDescIdx,  uLen };
     AssertMsg(pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK, ("Called with guest driver not ready\n"));
-    uint16_t const cVirtqItems = RT_MAX(pVirtio->uVirtqSize[idxVirtq], 1); /* Make sure to avoid div-by-zero. */
+    uint16_t const cVirtqItems = RT_MAX(pVirtio->uVirtqSize[uVirtqNbr], 1); /* Make sure to avoid div-by-zero. */
     PDMDevHlpPCIPhysWrite(pDevIns,
-                          pVirtio->aGCPhysVirtqUsed[idxVirtq] + RT_UOFFSETOF_DYN(VIRTQ_USED_T, aRing[usedIdx % cVirtqItems]),
+                          pVirtio->aGCPhysVirtqUsed[uVirtqNbr] + RT_UOFFSETOF_DYN(VIRTQ_USED_T, aRing[usedIdx % cVirtqItems]),
                           &elem, sizeof(elem));
 }
 
-DECLINLINE(void) virtioWriteUsedRingFlags(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq, uint16_t fFlags)
+DECLINLINE(void) virtioWriteUsedRingFlags(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, uint16_t fFlags)
 {
     AssertMsg(pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK, ("Called with guest driver not ready\n"));
     RT_UNTRUSTED_VALIDATED_FENCE(); /* VirtIO 1.0, Section 3.2.1.4.1 */
     PDMDevHlpPCIPhysWrite(pDevIns,
-                          pVirtio->aGCPhysVirtqUsed[idxVirtq] + RT_UOFFSETOF(VIRTQ_USED_T, fFlags),
+                          pVirtio->aGCPhysVirtqUsed[uVirtqNbr] + RT_UOFFSETOF(VIRTQ_USED_T, fFlags),
                           &fFlags, sizeof(fFlags));
 }
 #endif
 
-DECLINLINE(void) virtioWriteUsedRingIdx(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq, uint16_t uIdx)
+DECLINLINE(void) virtioWriteUsedRingIdx(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, uint16_t uIdx)
 {
     AssertMsg(pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK, ("Called with guest driver not ready\n"));
     PDMDevHlpPCIPhysWrite(pDevIns,
-                          pVirtio->aGCPhysVirtqUsed[idxVirtq] + RT_UOFFSETOF(VIRTQ_USED_T, uIdx),
+                          pVirtio->aGCPhysVirtqUsed[uVirtqNbr] + RT_UOFFSETOF(VIRTQ_USED_T, uIdx),
                           &uIdx, sizeof(uIdx));
 }
@@ -243 +244 @@
 #ifdef IN_RING3
 
-DECLINLINE(uint16_t) virtioReadUsedRingIdx(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq)
+DECLINLINE(uint16_t) virtioReadUsedRingIdx(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
 {
     uint16_t uIdx = 0;
     AssertMsg(pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK, ("Called with guest driver not ready\n"));
     PDMDevHlpPCIPhysRead(pDevIns,
-                      pVirtio->aGCPhysVirtqUsed[idxVirtq] + RT_UOFFSETOF(VIRTQ_USED_T, uIdx),
+                      pVirtio->aGCPhysVirtqUsed[uVirtqNbr] + RT_UOFFSETOF(VIRTQ_USED_T, uIdx),
                       &uIdx, sizeof(uIdx));
     return uIdx;
 }
 
-DECLINLINE(uint16_t) virtioReadUsedRingFlags(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq)
+DECLINLINE(uint16_t) virtioReadUsedRingFlags(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
 {
     uint16_t fFlags = 0;
     AssertMsg(pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK, ("Called with guest driver not ready\n"));
     PDMDevHlpPCIPhysRead(pDevIns,
-                      pVirtio->aGCPhysVirtqUsed[idxVirtq] + RT_UOFFSETOF(VIRTQ_USED_T, fFlags),
+                      pVirtio->aGCPhysVirtqUsed[uVirtqNbr] + RT_UOFFSETOF(VIRTQ_USED_T, fFlags),
                       &fFlags, sizeof(fFlags));
     return fFlags;
 }
 
-DECLINLINE(void) virtioWriteUsedAvailEvent(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq, uint32_t uAvailEventIdx)
+DECLINLINE(void) virtioWriteUsedAvailEvent(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, uint32_t uAvailEventIdx)
 {
     /** VirtIO 1.0 uAvailEventIdx (avail_event) immediately follows ring */
     AssertMsg(pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK, ("Called with guest driver not ready\n"));
     PDMDevHlpPCIPhysWrite(pDevIns,
-                          pVirtio->aGCPhysVirtqUsed[idxVirtq] + RT_UOFFSETOF_DYN(VIRTQ_USED_T, aRing[pVirtio->uVirtqSize[idxVirtq]]),
+                          pVirtio->aGCPhysVirtqUsed[uVirtqNbr] + RT_UOFFSETOF_DYN(VIRTQ_USED_T, aRing[pVirtio->uVirtqSize[uVirtqNbr]]),
                           &uAvailEventIdx, sizeof(uAvailEventIdx));
 }
@@ -277 +278 @@
 DECLINLINE(uint16_t) virtioCoreVirtqAvailCount(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, PVIRTQSTATE pVirtqState)
 {
-    uint16_t uIdx    = virtioReadAvailRingIdx(pDevIns, pVirtio, pVirtqState->idxVirtq);
+    uint16_t uIdx    = virtioReadAvailRingIdx(pDevIns, pVirtio, pVirtqState->uVirtqNbr);
     uint16_t uShadow = pVirtqState->uAvailIdxShadow;
 
@@ -287 +288 @@
 
     LogFunc(("%s has %u %s (idx=%u shadow=%u)\n",
-        VIRTQNAME(pVirtio, pVirtqState->idxVirtq), uDelta, uDelta == 1 ? "entry" : "entries",
+        VIRTQNAME(pVirtio, pVirtqState->uVirtqNbr), uDelta, uDelta == 1 ? "entry" : "entries",
         uIdx, uShadow));
 
@@ -297 +298 @@
  * @param   pDevIns     The device instance.
  * @param   pVirtio     Pointer to the shared virtio state.
- * @param   idxVirtq    Virtq number
+ * @param   uVirtqNbr    Virtq number
  *
  * @returns how many entries have been added to ring as a delta of the consumer's
  *          avail index and the queue's guest-side current avail index.
  */
-uint16_t virtioCoreVirtqAvailCount(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq)
-{
-    if (!IS_DRIVER_OK(pVirtio) || !pVirtio->uVirtqEnable[idxVirtq])
+uint16_t virtioCoreVirtqAvailCount(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
+{
+    if (!IS_DRIVER_OK(pVirtio) || !pVirtio->uVirtqEnable[uVirtqNbr])
     {
         LogRelFunc(("Driver not ready or queue not enabled\n"));
         return 0;
     }
-    return virtioCoreVirtqAvailCount(pDevIns, pVirtio, &pVirtio->aVirtqState[idxVirtq]);
+    return virtioCoreVirtqAvailCount(pDevIns, pVirtio, &pVirtio->aVirtqState[uVirtqNbr]);
 }
 
@@ -435 +436 @@
 
 #ifdef IN_RING3
+
+/** API Function: See header file*/
 void virtioCorePrintFeatures(VIRTIOCORE *pVirtio, PCDBGFINFOHLP pHlp)
 {
@@ -478 +481 @@
 
 #ifdef LOG_ENABLED
-/**
- * Debug assist for consumer device code.
- * Does a formatted hex dump using Log(()), recommend using VIRTIO_HEX_DUMP() macro to
- * control enabling of logging efficiently.
- *
- * @param   pv          pointer to buffer to dump contents of
- * @param   cb          count of characters to dump from buffer
- * @param   uBase       base address of per-row address prefixing of hex output
- * @param   pszTitle    Optional title. If present displays title that lists
- *                      provided text with value of cb to indicate size next to it.
- */
+
+/** API Function: See header file */
 void virtioCoreHexDump(uint8_t *pv, uint32_t cb, uint32_t uBase, const char *pszTitle)
 {
@@ -527 +521 @@
 }
 
-/**
- * Debug assist for consumer device code.
- * Do a hex dump of memory in guest physical context
- *
- * @param   GCPhys      pointer to buffer to dump contents of
- * @param   cb          count of characters to dump from buffer
- * @param   uBase       base address of per-row address prefixing of hex output
- * @param   pszTitle    Optional title. If present displays title that lists
- *                      provided text with value of cb to indicate size next to it.
- */
+/* API FUnction: See header file */
 void virtioCoreGCPhysHexDump(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint16_t cb, uint32_t uBase, const char *pszTitle)
 {
@@ -579 +564 @@
 #endif /* LOG_ENABLED */
 
-/**
- * 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 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 found in virtioCommonCfgAccessed() 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()
- * @param   pszMember   Name of struct member
- * @param   pv          pointer to value
- * @param   cb          size of value
- * @param   uOffset     offset into member where value starts
- * @param   fWrite      True if write I/O
- * @param   fHasIndex   True if the member is indexed
- * @param   idx         The index if fHasIndex
- */
+/** API function: See header file */
 void virtioCoreLogMappedIoValue(const char *pszFunc, const char *pszMember, uint32_t uMemberSize,
                                 const void *pv, uint32_t cb, uint32_t uOffset, int fWrite,
@@ -673 +639 @@
 #ifdef IN_RING3
 
-void virtioCoreR3Info(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs)
-{
-    RT_NOREF(pDevIns);
-    bool fNone     = pszArgs && *pszArgs == '\0';
-    bool fAll      = pszArgs && (*pszArgs == 'a' || *pszArgs == 'A'); /* "all"      */
-    bool fBasic    = pszArgs && (*pszArgs == 'b' || *pszArgs == 'B'); /* "basic"    */
-    bool fState    = pszArgs && (*pszArgs == 's' || *pszArgs == 'S'); /* "state"    */
-    bool fPointers = pszArgs && (*pszArgs == 'p' || *pszArgs == 'P'); /* "pointers" */
-    bool fVirtqs   = pszArgs && (*pszArgs == 'q' || *pszArgs == 'Q'); /* "queues    */
-    RT_NOREF6(fNone, fAll, fBasic, fState, fPointers, fVirtqs);
-    pHlp->pfnPrintf(pHlp, "");
-
-}
-
-void virtioCoreR3VirtqInfo(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs, int idxVirtq)
+/** API Fuunction: See header file */
+void virtioCoreR3VirtqInfo(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs, int uVirtqNbr)
 {
     RT_NOREF(pszArgs);
     PVIRTIOCORE pVirtio = PDMDEVINS_2_DATA(pDevIns, PVIRTIOCORE);
-    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[idxVirtq];
-
-//    bool fDump      = pszArgs && (*pszArgs == 'd' || *pszArgs == 'D'); /* "dump" (avail phys descriptor)"       */
-
-    uint16_t uAvailIdx       = virtioReadAvailRingIdx(pDevIns, pVirtio, idxVirtq);
+    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[uVirtqNbr];
+
+    /** @todo add ability to dump physical contents of any descriptor (using existing VirtIO core API function) */
+//    bool fDump      = pszArgs && (*pszArgs == 'd' || *pszArgs == 'D'); /* "dump" (avail phys descriptor)"
+
+    uint16_t uAvailIdx       = virtioReadAvailRingIdx(pDevIns, pVirtio, uVirtqNbr);
     uint16_t uAvailIdxShadow = pVirtqState->uAvailIdxShadow;
 
-    uint16_t uUsedIdx        = virtioReadUsedRingIdx(pDevIns, pVirtio, idxVirtq);
+    uint16_t uUsedIdx        = virtioReadUsedRingIdx(pDevIns, pVirtio, uVirtqNbr);
     uint16_t uUsedIdxShadow  = pVirtqState->uUsedIdxShadow;
 
-    PVIRTIO_DESC_CHAIN_T pDescChain = NULL;
+    PVIRTQBUF pVirtqBuf = NULL;
 
     bool fEmpty = IS_VIRTQ_EMPTY(pDevIns, pVirtio, pVirtqState);
 
-    LogFunc(("%s, empty = %s\n", VIRTQNAME(pVirtio, idxVirtq), fEmpty ? "true" : "false"));
+    LogFunc(("%s, empty = %s\n", VIRTQNAME(pVirtio, uVirtqNbr), fEmpty ? "true" : "false"));
 
     int cSendSegs = 0, cReturnSegs = 0;
     if (!fEmpty)
     {
-        virtioCoreR3VirtqPeek(pDevIns,  pVirtio, idxVirtq, &pDescChain);
-        cSendSegs   = pDescChain->pSgPhysSend ? pDescChain->pSgPhysSend->cSegs : 0;
-        cReturnSegs = pDescChain->pSgPhysReturn ? pDescChain->pSgPhysReturn->cSegs : 0;
-    }
-
-    bool fAvailNoInterrupt   = virtioReadAvailRingFlags(pDevIns, pVirtio, idxVirtq) & VIRTQ_AVAIL_F_NO_INTERRUPT;
-    bool fUsedNoNotify       = virtioReadUsedRingFlags(pDevIns, pVirtio, idxVirtq) & VIRTQ_USED_F_NO_NOTIFY;
-
-
-    pHlp->pfnPrintf(pHlp, "       queue enabled: ........... %s\n", pVirtio->uVirtqEnable[idxVirtq] ? "true" : "false");
-    pHlp->pfnPrintf(pHlp, "       size: .................... %d\n", pVirtio->uVirtqSize[idxVirtq]);
-    pHlp->pfnPrintf(pHlp, "       notify offset: ........... %d\n", pVirtio->uVirtqNotifyOff[idxVirtq]);
+        virtioCoreR3VirtqBufPeek(pDevIns,  pVirtio, uVirtqNbr, &pVirtqBuf);
+        cSendSegs   = pVirtqBuf->pSgPhysSend ? pVirtqBuf->pSgPhysSend->cSegs : 0;
+        cReturnSegs = pVirtqBuf->pSgPhysReturn ? pVirtqBuf->pSgPhysReturn->cSegs : 0;
+    }
+
+    bool fAvailNoInterrupt   = virtioReadAvailRingFlags(pDevIns, pVirtio, uVirtqNbr) & VIRTQ_AVAIL_F_NO_INTERRUPT;
+    bool fUsedNoNotify       = virtioReadUsedRingFlags(pDevIns, pVirtio, uVirtqNbr) & VIRTQ_USED_F_NO_NOTIFY;
+
+
+    pHlp->pfnPrintf(pHlp, "       queue enabled: ........... %s\n", pVirtio->uVirtqEnable[uVirtqNbr] ? "true" : "false");
+    pHlp->pfnPrintf(pHlp, "       size: .................... %d\n", pVirtio->uVirtqSize[uVirtqNbr]);
+    pHlp->pfnPrintf(pHlp, "       notify offset: ........... %d\n", pVirtio->uVirtqNotifyOff[uVirtqNbr]);
     if (pVirtio->fMsiSupport)
-        pHlp->pfnPrintf(pHlp, "       MSIX vector: ....... %4.4x\n", pVirtio->uVirtqMsixVector[idxVirtq]);
+        pHlp->pfnPrintf(pHlp, "       MSIX vector: ....... %4.4x\n", pVirtio->uVirtqMsixVector[uVirtqNbr]);
     pHlp->pfnPrintf(pHlp, "\n");
     pHlp->pfnPrintf(pHlp, "       avail ring (%d entries):\n", uAvailIdx - uAvailIdxShadow);
@@ -740 +694 @@
         pHlp->pfnPrintf(pHlp, "          head idx: ............. %d\n", uUsedIdx);
         pHlp->pfnPrintf(pHlp, "          segs: ................. %d\n", cSendSegs + cReturnSegs);
-        pHlp->pfnPrintf(pHlp, "          refCnt ................ %d\n", pDescChain->cRefs);
+        pHlp->pfnPrintf(pHlp, "          refCnt ................ %d\n", pVirtqBuf->cRefs);
         pHlp->pfnPrintf(pHlp, "\n");
-        pHlp->pfnPrintf(pHlp, "          host-to-guest (%d bytes):\n",      pDescChain->cbPhysSend);
+        pHlp->pfnPrintf(pHlp, "          host-to-guest (%d bytes):\n",      pVirtqBuf->cbPhysSend);
         pHlp->pfnPrintf(pHlp,     "             segs: .............. %d\n", cSendSegs);
         if (cSendSegs)
         {
-            pHlp->pfnPrintf(pHlp, "             index: ............. %d\n", pDescChain->pSgPhysSend->idxSeg);
-            pHlp->pfnPrintf(pHlp, "             unsent ............. %d\n", pDescChain->pSgPhysSend->cbSegLeft);
+            pHlp->pfnPrintf(pHlp, "             index: ............. %d\n", pVirtqBuf->pSgPhysSend->idxSeg);
+            pHlp->pfnPrintf(pHlp, "             unsent ............. %d\n", pVirtqBuf->pSgPhysSend->cbSegLeft);
         }
         pHlp->pfnPrintf(pHlp, "\n");
-        pHlp->pfnPrintf(pHlp,     "          guest-to-host (%d bytes)\n",   pDescChain->cbPhysReturn);
+        pHlp->pfnPrintf(pHlp,     "          guest-to-host (%d bytes)\n",   pVirtqBuf->cbPhysReturn);
         pHlp->pfnPrintf(pHlp,     "             segs: .............. %d\n", cReturnSegs);
         if (cReturnSegs)
         {
-            pHlp->pfnPrintf(pHlp, "             index: ............. %d\n", pDescChain->pSgPhysReturn->idxSeg);
-            pHlp->pfnPrintf(pHlp, "             unsent ............. %d\n", pDescChain->pSgPhysReturn->cbSegLeft);
+            pHlp->pfnPrintf(pHlp, "             index: ............. %d\n", pVirtqBuf->pSgPhysReturn->idxSeg);
+            pHlp->pfnPrintf(pHlp, "             unsent ............. %d\n", pVirtqBuf->pSgPhysReturn->cbSegLeft);
         }
     } else
@@ -763 +717 @@
 }
 
-/**
- * Allocate client context for client to work with VirtIO-#provided with queue
- *
- * @param   pVirtio     Pointer to the shared virtio state.
- * @param   idxVirtq    Virtq number
- * @param   pcszName    Name to give queue
- *
- * @returns VBox status code.
- */
-int virtioCoreR3VirtqAttach(PVIRTIOCORE pVirtio, uint16_t idxVirtq, const char *pcszName)
+int virtioCoreR3VirtqAttach(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, const char *pcszName)
 {
     LogFunc(("%s\n", pcszName));
-    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[idxVirtq];
-    pVirtqState->idxVirtq = idxVirtq;
+    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[uVirtqNbr];
+    pVirtqState->uVirtqNbr = uVirtqNbr;
     pVirtqState->uAvailIdxShadow = 0;
     pVirtqState->uUsedIdxShadow  = 0;
@@ -788 +733 @@
 #ifdef IN_RING3
 
-int virtioCoreR3DescChainGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq,
-                             uint16_t uHeadIdx, PPVIRTIO_DESC_CHAIN_T ppDescChain)
-{
-    AssertReturn(ppDescChain, VERR_INVALID_POINTER);
-    *ppDescChain = NULL;
-
-    Assert(idxVirtq < RT_ELEMENTS(pVirtio->aVirtqState));
-
-    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[idxVirtq];
-
-    AssertMsgReturn(IS_DRIVER_OK(pVirtio) && pVirtio->uVirtqEnable[idxVirtq],
+/** API Function: See header file */
+int virtioCoreR3VirtqBufGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
+                             uint16_t uHeadIdx, PPVIRTQBUF ppVirtqBuf)
+{
+    AssertReturn(ppVirtqBuf, VERR_INVALID_POINTER);
+    *ppVirtqBuf = NULL;
+
+    Assert(uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqState));
+
+    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[uVirtqNbr];
+
+    AssertMsgReturn(IS_DRIVER_OK(pVirtio) && pVirtio->uVirtqEnable[uVirtqNbr],
                     ("Guest driver not in ready state.\n"), VERR_INVALID_STATE);
 
@@ -809 +755 @@
      * Allocate and initialize the descriptor chain structure.
      */
-    PVIRTIO_DESC_CHAIN_T pDescChain = (PVIRTIO_DESC_CHAIN_T)RTMemAllocZ(sizeof(VIRTIO_DESC_CHAIN_T));
-    AssertReturn(pDescChain, VERR_NO_MEMORY);
-    pDescChain->u32Magic = VIRTIO_DESC_CHAIN_MAGIC;
-    pDescChain->cRefs    = 1;
-    pDescChain->uHeadIdx = uHeadIdx;
-    *ppDescChain = pDescChain;
+    PVIRTQBUF pVirtqBuf = (PVIRTQBUF)RTMemAllocZ(sizeof(VIRTQBUF_T));
+    AssertReturn(pVirtqBuf, VERR_NO_MEMORY);
+    pVirtqBuf->u32Magic = VIRTQBUF_MAGIC;
+    pVirtqBuf->cRefs    = 1;
+    pVirtqBuf->uHeadIdx = uHeadIdx;
+    *ppVirtqBuf = pVirtqBuf;
 
     /*
@@ -825 +771 @@
     uint32_t cSegsIn = 0;
     uint32_t cSegsOut = 0;
-    PVIRTIOSGSEG paSegsIn  = pDescChain->aSegsIn;
-    PVIRTIOSGSEG paSegsOut = pDescChain->aSegsOut;
+    PVIRTIOSGSEG paSegsIn  = pVirtqBuf->aSegsIn;
+    PVIRTIOSGSEG paSegsOut = pVirtqBuf->aSegsOut;
 
     do
@@ -853 +799 @@
         RT_UNTRUSTED_VALIDATED_FENCE();
 
-        virtioReadDesc(pDevIns, pVirtio, idxVirtq, uDescIdx, &desc);
+        virtioReadDesc(pDevIns, pVirtio, uVirtqNbr, uDescIdx, &desc);
 
         if (desc.fFlags & VIRTQ_DESC_F_WRITE)
         {
-            Log6Func(("%s IN  desc_idx=%u seg=%u addr=%RGp cb=%u\n", VIRTQNAME(pVirtio, idxVirtq), uDescIdx, cSegsIn, desc.GCPhysBuf, desc.cb));
+            Log6Func(("%s IN  desc_idx=%u seg=%u addr=%RGp cb=%u\n", VIRTQNAME(pVirtio, uVirtqNbr), uDescIdx, cSegsIn, desc.GCPhysBuf, desc.cb));
             cbIn += desc.cb;
             pSeg = &paSegsIn[cSegsIn++];
@@ -863 +809 @@
         else
         {
-            Log6Func(("%s OUT desc_idx=%u seg=%u addr=%RGp cb=%u\n", VIRTQNAME(pVirtio, idxVirtq), uDescIdx, cSegsOut, desc.GCPhysBuf, desc.cb));
+            Log6Func(("%s OUT desc_idx=%u seg=%u addr=%RGp cb=%u\n", VIRTQNAME(pVirtio, uVirtqNbr), uDescIdx, cSegsOut, desc.GCPhysBuf, desc.cb));
             cbOut += desc.cb;
             pSeg = &paSegsOut[cSegsOut++];
@@ -884 +830 @@
     if (cSegsIn)
     {
-        virtioCoreSgBufInit(&pDescChain->SgBufIn, paSegsIn, cSegsIn);
-        pDescChain->pSgPhysReturn = &pDescChain->SgBufIn;
-        pDescChain->cbPhysReturn  = cbIn;
+        virtioCoreSgBufInit(&pVirtqBuf->SgBufIn, paSegsIn, cSegsIn);
+        pVirtqBuf->pSgPhysReturn = &pVirtqBuf->SgBufIn;
+        pVirtqBuf->cbPhysReturn  = cbIn;
         STAM_REL_COUNTER_ADD(&pVirtio->StatDescChainsSegsIn, cSegsIn);
     }
@@ -892 +838 @@
     if (cSegsOut)
     {
-        virtioCoreSgBufInit(&pDescChain->SgBufOut, paSegsOut, cSegsOut);
-        pDescChain->pSgPhysSend   = &pDescChain->SgBufOut;
-        pDescChain->cbPhysSend    = cbOut;
+        virtioCoreSgBufInit(&pVirtqBuf->SgBufOut, paSegsOut, cSegsOut);
+        pVirtqBuf->pSgPhysSend   = &pVirtqBuf->SgBufOut;
+        pVirtqBuf->cbPhysSend    = cbOut;
         STAM_REL_COUNTER_ADD(&pVirtio->StatDescChainsSegsOut, cSegsOut);
     }
@@ -904 +850 @@
 }
 
-
-/**
- * Retains a reference to the given descriptor chain.
- *
- * @returns New reference count.
- * @retval  UINT32_MAX on invalid parameter.
- * @param   pDescChain      The descriptor chain to reference.
- */
-uint32_t virtioCoreR3DescChainRetain(PVIRTIO_DESC_CHAIN_T pDescChain)
-{
-    AssertReturn(pDescChain, UINT32_MAX);
-    AssertReturn(pDescChain->u32Magic == VIRTIO_DESC_CHAIN_MAGIC, UINT32_MAX);
-    uint32_t cRefs = ASMAtomicIncU32(&pDescChain->cRefs);
+/** API Function: See header file */
+uint32_t virtioCoreR3VirtqBufRetain(PVIRTQBUF pVirtqBuf)
+{
+    AssertReturn(pVirtqBuf, UINT32_MAX);
+    AssertReturn(pVirtqBuf->u32Magic == VIRTQBUF_MAGIC, UINT32_MAX);
+    uint32_t cRefs = ASMAtomicIncU32(&pVirtqBuf->cRefs);
     Assert(cRefs > 1);
     Assert(cRefs < 16);
@@ -923 +862 @@
 
 
-/**
- * Releases a reference to the given descriptor chain.
- *
- * @returns New reference count.
- * @retval  0 if freed or invalid parameter.
- * @param   pVirtio         Pointer to the shared virtio state.
- * @param   pDescChain      The descriptor chain to reference.  NULL is quietly
- *                          ignored (returns 0).
- */
-uint32_t virtioCoreR3DescChainRelease(PVIRTIOCORE pVirtio, PVIRTIO_DESC_CHAIN_T pDescChain)
-{
-    if (!pDescChain)
+/** API Function: See header file */
+uint32_t virtioCoreR3VirtqBufRelease(PVIRTIOCORE pVirtio, PVIRTQBUF pVirtqBuf)
+{
+    if (!pVirtqBuf)
         return 0;
-    AssertReturn(pDescChain, 0);
-    AssertReturn(pDescChain->u32Magic == VIRTIO_DESC_CHAIN_MAGIC, 0);
-    uint32_t cRefs = ASMAtomicDecU32(&pDescChain->cRefs);
+    AssertReturn(pVirtqBuf, 0);
+    AssertReturn(pVirtqBuf->u32Magic == VIRTQBUF_MAGIC, 0);
+    uint32_t cRefs = ASMAtomicDecU32(&pVirtqBuf->cRefs);
     Assert(cRefs < 16);
     if (cRefs == 0)
     {
-        pDescChain->u32Magic = ~VIRTIO_DESC_CHAIN_MAGIC;
-        RTMemFree(pDescChain);
+        pVirtqBuf->u32Magic = ~VIRTQBUF_MAGIC;
+        RTMemFree(pVirtqBuf);
         STAM_REL_COUNTER_INC(&pVirtio->StatDescChainsFreed);
     }
@@ -949 +880 @@
 }
 
-
-/*
- * Notifies guest (via ISR or MSI-X) of device configuration change
- *
- * @param   pVirtio     Pointer to the shared virtio state.
- */
+/** API Function: See header file */
 void virtioCoreNotifyConfigChanged(PVIRTIOCORE pVirtio)
 {
@@ -960 +886 @@
 }
 
-/**
- * Enable or Disable notification for the specified queue
- *
- * @param   pVirtio     Pointer to the shared virtio state.
- * @param   idxVirtq    Virtq number
- * @param   fEnable    Selects notification mode (enabled or disabled)
- */
-void virtioCoreVirtqNotifyEnable(PVIRTIOCORE pVirtio, uint16_t idxVirtq, bool fEnable)
+void virtioCoreVirtqEnableNotify(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, bool fEnable)
 {
     if (pVirtio->uDeviceStatus & VIRTIO_STATUS_DRIVER_OK)
     {
-        uint16_t fFlags = virtioReadUsedRingFlags(pVirtio->pDevInsR3, pVirtio, idxVirtq);
+        uint16_t fFlags = virtioReadUsedRingFlags(pVirtio->pDevInsR3, pVirtio, uVirtqNbr);
 
         if (fEnable)
@@ -978 +897 @@
             fFlags |= VIRTQ_USED_F_NO_NOTIFY;
 
-        virtioWriteUsedRingFlags(pVirtio->pDevInsR3, pVirtio, idxVirtq, fFlags);
-    }
-}
-
-/**
- * Initiate orderly reset procedure. This is an exposed API for clients that might need it.
- * Invoked by client to reset the device and driver (see VirtIO 1.0 section 2.1.1/2.1.2)
- *
- * @param   pVirtio     Pointer to the virtio state.
- */
+        virtioWriteUsedRingFlags(pVirtio->pDevInsR3, pVirtio, uVirtqNbr, fFlags);
+    }
+}
+
+/** API function: See Header file  */
 void virtioCoreResetAll(PVIRTIOCORE pVirtio)
 {
@@ -999 +913 @@
 }
 
-/**
- * Fetches descriptor chain using avail ring of indicated queue and converts the descriptor
- * chain into its OUT (to device) and IN to guest components, but does NOT remove it from
- * the 'avail' queue. I.e. doesn't advance the index.  This can be used with virtioVirtqSkip(),
- * which *does* advance the avail index. Together they facilitate a mechanism that allows
- * work with a queue element (descriptor chain) to be aborted if necessary, by not advancing
- * the pointer, or, upon success calling the skip function (above) to move to the next element.
- *
- * Additionally it converts the OUT desc chain data to a contiguous virtual
- * memory buffer for easy consumption by the caller. The caller must return the
- * descriptor chain pointer via virtioCoreR3VirtqPut() and then call virtioCoreVirtqSync()
- * at some point to return the data to the guest and complete the transaction.
- *
- * @param   pDevIns     The device instance.
- * @param   pVirtio     Pointer to the shared virtio state.
- * @param   idxVirtq    Virtq number
- * @param   ppDescChain Address to store pointer to descriptor chain that contains the
- *                      pre-processed transaction information pulled from the virtq.
- *
- * @returns VBox status code:
- * @retval  VINF_SUCCESS         Success
- * @retval  VERR_INVALID_STATE   VirtIO not in ready state (asserted).
- * @retval  VERR_NOT_AVAILABLE   If the queue is empty.
- */
-
-int virtioCoreR3VirtqPeek(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq,
-                         PPVIRTIO_DESC_CHAIN_T ppDescChain)
-{
-    return virtioCoreR3VirtqGet(pDevIns, pVirtio,  idxVirtq, ppDescChain, false);
-}
-
-/**
- * Skip the next entry in the specified queue (typically used with virtioCoreR3VirtqPeek())
- *
- * @param   pVirtio     Pointer to the virtio state.
- * @param   idxVirtq    Index of queue
- */
-int virtioCoreR3VirtqSkip(PVIRTIOCORE pVirtio, uint16_t idxVirtq)
-{
-    Assert(idxVirtq < RT_ELEMENTS(pVirtio->aVirtqState));
-    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[idxVirtq];
-
-    AssertMsgReturn(IS_DRIVER_OK(pVirtio) && pVirtio->uVirtqEnable[idxVirtq],
+/** API function: See Header file  */
+int virtioCoreR3VirtqBufPeek(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
+                         PPVIRTQBUF ppVirtqBuf)
+{
+    return virtioCoreR3VirtqBufGet(pDevIns, pVirtio,  uVirtqNbr, ppVirtqBuf, false);
+}
+
+/** API function: See Header file  */
+int virtioCoreR3VirtqBufSkip(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
+{
+    Assert(uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqState));
+    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[uVirtqNbr];
+
+    AssertMsgReturn(IS_DRIVER_OK(pVirtio) && pVirtio->uVirtqEnable[uVirtqNbr],
                     ("Guest driver not in ready state.\n"), VERR_INVALID_STATE);
 
@@ -1053 +938 @@
 }
 
-/**
- * Fetches descriptor chain using avail ring of indicated queue and converts the descriptor
- * chain into its OUT (to device) and IN to guest components.
- *
- * Additionally it converts the OUT desc chain data to a contiguous virtual
- * memory buffer for easy consumption by the caller. The caller must return the
- * descriptor chain pointer via virtioCoreR3VirtqPut() and then call virtioCoreVirtqSync()
- * at some point to return the data to the guest and complete the transaction.
- *
- * @param   pDevIns     The device instance.
- * @param   pVirtio     Pointer to the shared virtio state.
- * @param   idxVirtq    Virtq number
- * @param   ppDescChain Address to store pointer to descriptor chain that contains the
- *                      pre-processed transaction information pulled from the virtq.
- *                      Returned reference must be released by calling
- *                      virtioCoreR3DescChainRelease().
- * @param   fRemove     flags whether to remove desc chain from queue (false = peek)
- *
- * @returns VBox status code:
- * @retval  VINF_SUCCESS         Success
- * @retval  VERR_INVALID_STATE   VirtIO not in ready state (asserted).
- * @retval  VERR_NOT_AVAILABLE   If the queue is empty.
- */
-int virtioCoreR3VirtqGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq,
-                         PPVIRTIO_DESC_CHAIN_T ppDescChain, bool fRemove)
-{
-    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[idxVirtq];
+/** API function: See Header file  */
+int virtioCoreR3VirtqBufGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
+                         PPVIRTQBUF ppVirtqBuf, bool fRemove)
+{
+    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[uVirtqNbr];
 
     if (IS_VIRTQ_EMPTY(pDevIns, pVirtio, pVirtqState))
         return VERR_NOT_AVAILABLE;
 
-    uint16_t uHeadIdx = virtioReadAvailDescIdx(pDevIns, pVirtio, idxVirtq, pVirtqState->uAvailIdxShadow);
+    uint16_t uHeadIdx = virtioReadAvailDescIdx(pDevIns, pVirtio, uVirtqNbr, pVirtqState->uAvailIdxShadow);
 
     if (pVirtio->uDriverFeatures & VIRTIO_F_EVENT_IDX)
-        virtioWriteUsedAvailEvent(pDevIns,pVirtio, idxVirtq, pVirtqState->uAvailIdxShadow + 1);
+        virtioWriteUsedAvailEvent(pDevIns,pVirtio, uVirtqNbr, pVirtqState->uAvailIdxShadow + 1);
 
     if (fRemove)
         pVirtqState->uAvailIdxShadow++;
 
-    int rc = virtioCoreR3DescChainGet(pDevIns, pVirtio, idxVirtq, uHeadIdx, ppDescChain);
+    int rc = virtioCoreR3VirtqBufGet(pDevIns, pVirtio, uVirtqNbr, uHeadIdx, ppVirtqBuf);
     return rc;
 }
 
-/**
- * Returns data to the guest to complete a transaction initiated by virtVirtqGet().
- *
- * The caller passes in a pointer to a scatter-gather buffer of virtual memory segments
- * and a pointer to the descriptor chain context originally derived from the pulled
- * queue entry, and this function will write the virtual memory s/g buffer into the
- * guest's physical memory free the descriptor chain. The caller handles the freeing
- * (as needed) of the virtual memory buffer.
- *
- * @note This does a write-ahead to the used ring of the guest's queue. The data
- *       written won't be seen by the guest until the next call to virtioCoreVirtqSync()
- *
- *
- * @param   pDevIns         The device instance (for reading).
- * @param   pVirtio         Pointer to the shared virtio state.
- * @param   idxVirtq        Virtq number
- *
- * @param   pSgVirtReturn   Points to scatter-gather buffer of virtual memory
- *                          segments the caller is returning to the guest.
- *
- * @param   pDescChain      This contains the context of the scatter-gather
- *                          buffer originally pulled from the queue.
- *
- * @param   fFence          If true, put up copy fence (memory barrier) after
- *                          copying to guest phys. mem.
- *
- * @returns VBox status code.
- * @retval  VINF_SUCCESS       Success
- * @retval  VERR_INVALID_STATE VirtIO not in ready state
- * @retval  VERR_NOT_AVAILABLE Virtq is empty
- *
- * @note    This function will not release any reference to pDescChain.  The
- *          caller must take care of that.
- */
-int virtioCoreR3VirtqPut(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq, PRTSGBUF pSgVirtReturn,
-                         PVIRTIO_DESC_CHAIN_T pDescChain, bool fFence)
-{
-    Assert(idxVirtq < RT_ELEMENTS(pVirtio->aVirtqState));
-    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[idxVirtq];
-    PVIRTIOSGBUF pSgPhysReturn = pDescChain->pSgPhysReturn;
-
-    Assert(pDescChain->u32Magic == VIRTIO_DESC_CHAIN_MAGIC);
-    Assert(pDescChain->cRefs > 0);
+/** API function: See Header file  */
+int virtioCoreR3VirtqBufPut(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, PRTSGBUF pSgVirtReturn,
+                            PVIRTQBUF pVirtqBuf, bool fFence)
+{
+    Assert(uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqState));
+    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[uVirtqNbr];
+    PVIRTIOSGBUF pSgPhysReturn = pVirtqBuf->pSgPhysReturn;
+
+    Assert(pVirtqBuf->u32Magic == VIRTQBUF_MAGIC);
+    Assert(pVirtqBuf->cRefs > 0);
 
     AssertMsgReturn(IS_DRIVER_OK(pVirtio), ("Guest driver not in ready state.\n"), VERR_INVALID_STATE);
 
     Log6Func(("Copying client data to %s, desc chain (head desc_idx %d)\n",
-              VIRTQNAME(pVirtio, idxVirtq), virtioReadUsedRingIdx(pDevIns, pVirtio, idxVirtq)));
+              VIRTQNAME(pVirtio, uVirtqNbr), virtioReadUsedRingIdx(pDevIns, pVirtio, uVirtqNbr)));
 
     /* Copy s/g buf (virtual memory) to guest phys mem (IN direction). */
@@ -1173 +1003 @@
     /* If this write-ahead crosses threshold where the driver wants to get an event flag it */
     if (pVirtio->uDriverFeatures & VIRTIO_F_EVENT_IDX)
-        if (pVirtqState->uUsedIdxShadow == virtioReadAvailUsedEvent(pDevIns, pVirtio, idxVirtq))
+        if (pVirtqState->uUsedIdxShadow == virtioReadAvailUsedEvent(pDevIns, pVirtio, uVirtqNbr))
             pVirtqState->fVirtqRingEventThreshold = true;
 
@@ -1179 +1009 @@
      * Place used buffer's descriptor in used ring but don't update used ring's slot index.
      * That will be done with a subsequent client call to virtioCoreVirtqSync() */
-    virtioWriteUsedElem(pDevIns, pVirtio, idxVirtq, pVirtqState->uUsedIdxShadow++, pDescChain->uHeadIdx, (uint32_t)cbTotal);
+    virtioWriteUsedElem(pDevIns, pVirtio, uVirtqNbr, pVirtqState->uUsedIdxShadow++, pVirtqBuf->uHeadIdx, (uint32_t)cbTotal);
 
     if (pSgVirtReturn)
         Log6Func((".... Copied %zu bytes in %d segs to %u byte buffer, residual=%zu\n",
-                  cbTotal - cbRemain, pSgVirtReturn->cSegs, pDescChain->cbPhysReturn, pDescChain->cbPhysReturn - cbTotal));
+                  cbTotal - cbRemain, pSgVirtReturn->cSegs, pVirtqBuf->cbPhysReturn, pVirtqBuf->cbPhysReturn - cbTotal));
 
     Log6Func(("Write ahead used_idx=%u, %s used_idx=%u\n",
-              pVirtqState->uUsedIdxShadow, VIRTQNAME(pVirtio, idxVirtq), virtioReadUsedRingIdx(pDevIns, pVirtio, idxVirtq)));
+              pVirtqState->uUsedIdxShadow, VIRTQNAME(pVirtio, uVirtqNbr), virtioReadUsedRingIdx(pDevIns, pVirtio, uVirtqNbr)));
 
     return VINF_SUCCESS;
@@ -1193 +1023 @@
 #endif /* IN_RING3 */
 
+/** API function: See Header file  */
+int virtioCoreVirtqSync(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
+{
+    Assert(uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqState));
+    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[uVirtqNbr];
+
+    AssertMsgReturn(IS_DRIVER_OK(pVirtio) && pVirtio->uVirtqEnable[uVirtqNbr],
+                    ("Guest driver not in ready state.\n"), VERR_INVALID_STATE);
+
+    Log6Func(("Updating %s used_idx to %u\n",
+              VIRTQNAME(pVirtio, uVirtqNbr), pVirtqState->uUsedIdxShadow));
+
+    virtioWriteUsedRingIdx(pDevIns, pVirtio, uVirtqNbr, pVirtqState->uUsedIdxShadow);
+    virtioCoreNotifyGuestDriver(pDevIns, pVirtio, uVirtqNbr);
+
+    return VINF_SUCCESS;
+}
+
+
 /**
- * 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
- * virtioCoreR3VirtqPut() calls since the last sync. This should be called after one or
- * more virtioCoreR3VirtqPut() 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   pDevIns     The device instance.
- * @param   pVirtio     Pointer to the shared virtio state.
- * @param   idxVirtq    Virtq number
- *
- * @returns VBox status code.
- * @retval  VINF_SUCCESS       Success
- * @retval  VERR_INVALID_STATE VirtIO not in ready state
- */
-int virtioCoreVirtqSync(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq)
-{
-    Assert(idxVirtq < RT_ELEMENTS(pVirtio->aVirtqState));
-    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[idxVirtq];
-
-    AssertMsgReturn(IS_DRIVER_OK(pVirtio) && pVirtio->uVirtqEnable[idxVirtq],
-                    ("Guest driver not in ready state.\n"), VERR_INVALID_STATE);
-
-    Log6Func(("Updating %s used_idx to %u\n",
-              VIRTQNAME(pVirtio, idxVirtq), pVirtqState->uUsedIdxShadow));
-
-    virtioWriteUsedRingIdx(pDevIns, pVirtio, idxVirtq, pVirtqState->uUsedIdxShadow);
-    virtioCoreNotifyGuestDriver(pDevIns, pVirtio, idxVirtq);
-
-    return VINF_SUCCESS;
-}
-
-
-/**
- */
-static void virtioCoreVirtqNotified(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq, uint16_t uNotifyIdx)
+ */
+static void virtioCoreVirtqNotified(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, uint16_t uNotifyIdx)
 {
 
     PVIRTIOCORECC pVirtioCC = PDMDEVINS_2_DATA_CC(pDevIns, PVIRTIOCORECC);
 
-    /* See VirtIO 1.0, section 4.1.5.2 It implies that idxVirtq and uNotifyIdx should match.
+    /* See VirtIO 1.0, section 4.1.5.2 It implies that uVirtqNbr and uNotifyIdx should match.
      * Disregarding this notification may cause throughput to stop, however there's no way to know
      * which was queue was intended for wake-up if the two parameters disagree. */
 
-    AssertMsg(uNotifyIdx == idxVirtq,
+    AssertMsg(uNotifyIdx == uVirtqNbr,
                     ("Guest kicked virtq %d's notify addr w/non-corresponding virtq idx %d\n",
-                     idxVirtq, uNotifyIdx));
+                     uVirtqNbr, uNotifyIdx));
     RT_NOREF(uNotifyIdx);
 
-    AssertReturnVoid(idxVirtq < RT_ELEMENTS(pVirtio->aVirtqState));
+    AssertReturnVoid(uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqState));
     Log6Func(("%s (desc chains: %u)\n",
-        pVirtio->aVirtqState[idxVirtq].szVirtqName,
-        virtioCoreVirtqAvailCount(pDevIns, pVirtio, idxVirtq)));
+        pVirtio->aVirtqState[uVirtqNbr].szVirtqName,
+        virtioCoreVirtqAvailCount(pDevIns, pVirtio, uVirtqNbr)));
 
     /* Inform client */
-    pVirtioCC->pfnVirtqNotified(pDevIns, pVirtio, idxVirtq);
+    pVirtioCC->pfnVirtqNotified(pDevIns, pVirtio, uVirtqNbr);
 }
 
@@ -1262 +1076 @@
  * @param   pDevIns     The device instance.
  * @param   pVirtio     Pointer to the shared virtio state.
- * @param   idxVirtq    Virtq to check for guest interrupt handling preference
- */
-static void virtioCoreNotifyGuestDriver(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq)
-{
-
-    Assert(idxVirtq < RT_ELEMENTS(pVirtio->aVirtqState));
-    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[idxVirtq];
+ * @param   uVirtqNbr    Virtq to check for guest interrupt handling preference
+ */
+static void virtioCoreNotifyGuestDriver(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
+{
+
+    Assert(uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqState));
+    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[uVirtqNbr];
 
     if (!IS_DRIVER_OK(pVirtio))
@@ -1282 +1096 @@
 #ifdef IN_RING3
             Log6Func(("...kicking guest %s, VIRTIO_F_EVENT_IDX set and threshold (%d) reached\n",
-                   VIRTQNAME(pVirtio, idxVirtq), (uint16_t)virtioReadAvailUsedEvent(pDevIns, pVirtio, idxVirtq)));
+                   VIRTQNAME(pVirtio, uVirtqNbr), (uint16_t)virtioReadAvailUsedEvent(pDevIns, pVirtio, uVirtqNbr)));
 #endif
-            virtioKick(pDevIns, pVirtio, VIRTIO_ISR_VIRTQ_INTERRUPT, pVirtio->uVirtqMsixVector[idxVirtq]);
+            virtioKick(pDevIns, pVirtio, VIRTIO_ISR_VIRTQ_INTERRUPT, pVirtio->uVirtqMsixVector[uVirtqNbr]);
             pVirtqState->fVirtqRingEventThreshold = false;
             return;
@@ -1290 +1104 @@
 #ifdef IN_RING3
         Log6Func(("...skip interrupt %s, VIRTIO_F_EVENT_IDX set but threshold (%d) not reached (%d)\n",
-                   VIRTQNAME(pVirtio, idxVirtq),(uint16_t)virtioReadAvailUsedEvent(pDevIns, pVirtio, idxVirtq), pVirtqState->uUsedIdxShadow));
+                   VIRTQNAME(pVirtio, uVirtqNbr),(uint16_t)virtioReadAvailUsedEvent(pDevIns, pVirtio, uVirtqNbr), pVirtqState->uUsedIdxShadow));
 #endif
     }
@@ -1296 +1110 @@
     {
         /** If guest driver hasn't suppressed interrupts, interrupt  */
-        if (!(virtioReadAvailRingFlags(pDevIns, pVirtio, idxVirtq) & VIRTQ_AVAIL_F_NO_INTERRUPT))
-        {
-            virtioKick(pDevIns, pVirtio, VIRTIO_ISR_VIRTQ_INTERRUPT, pVirtio->uVirtqMsixVector[idxVirtq]);
+        if (!(virtioReadAvailRingFlags(pDevIns, pVirtio, uVirtqNbr) & VIRTQ_AVAIL_F_NO_INTERRUPT))
+        {
+            virtioKick(pDevIns, pVirtio, VIRTIO_ISR_VIRTQ_INTERRUPT, pVirtio->uVirtqMsixVector[uVirtqNbr]);
             return;
         }
         Log6Func(("...skipping interrupt for %s (guest set VIRTQ_AVAIL_F_NO_INTERRUPT)\n",
-                     VIRTQNAME(pVirtio, idxVirtq)));
+                     VIRTQNAME(pVirtio, uVirtqNbr)));
     }
 }
@@ -1347 +1161 @@
 
 #ifdef IN_RING3
-static void virtioResetVirtq(PVIRTIOCORE pVirtio, uint16_t idxVirtq)
-{
-    Assert(idxVirtq < RT_ELEMENTS(pVirtio->aVirtqState));
-    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[idxVirtq];
+static void virtioResetVirtq(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
+{
+    Assert(uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqState));
+    PVIRTQSTATE pVirtqState = &pVirtio->aVirtqState[uVirtqNbr];
     pVirtqState->uAvailIdxShadow = 0;
     pVirtqState->uUsedIdxShadow  = 0;
     pVirtqState->fVirtqRingEventThreshold = false;
-    pVirtio->uVirtqEnable[idxVirtq] = false;
-    pVirtio->uVirtqSize[idxVirtq] = VIRTQ_MAX_ENTRIES;
-    pVirtio->uVirtqNotifyOff[idxVirtq] = idxVirtq;
-    pVirtio->uVirtqMsixVector[idxVirtq] = idxVirtq + 2;
+    pVirtio->uVirtqEnable[uVirtqNbr] = false;
+    pVirtio->uVirtqSize[uVirtqNbr] = VIRTQ_MAX_ENTRIES;
+    pVirtio->uVirtqNotifyOff[uVirtqNbr] = uVirtqNbr;
+    pVirtio->uVirtqMsixVector[uVirtqNbr] = uVirtqNbr + 2;
     if (!pVirtio->fMsiSupport) /* VirtIO 1.0, 4.1.4.3 and 4.1.5.1.2 */
-        pVirtio->uVirtqMsixVector[idxVirtq] = VIRTIO_MSI_NO_VECTOR;
-
-    virtioLowerInterrupt(pVirtio->pDevInsR3, pVirtio->uVirtqMsixVector[idxVirtq]);
+        pVirtio->uVirtqMsixVector[uVirtqNbr] = VIRTIO_MSI_NO_VECTOR;
+
+    virtioLowerInterrupt(pVirtio->pDevInsR3, pVirtio->uVirtqMsixVector[uVirtqNbr]);
 }
 
@@ -1388 +1202 @@
         pVirtio->uMsixConfig = VIRTIO_MSI_NO_VECTOR;
 
-    for (uint16_t idxVirtq = 0; idxVirtq < VIRTQ_MAX_CNT; idxVirtq++)
-        virtioResetVirtq(pVirtio, idxVirtq);
+    for (uint16_t uVirtqNbr = 0; uVirtqNbr < VIRTQ_MAX_CNT; uVirtqNbr++)
+        virtioResetVirtq(pVirtio, uVirtqNbr);
 }
 
@@ -2026 +1840 @@
             break;
         case kvirtIoVmStateChangedResume:
-            virtioCoreNotifyGuestDriver(pVirtio->pDevInsR3, pVirtio, 0 /* idxVirtq */);
+            virtioCoreNotifyGuestDriver(pVirtio->pDevInsR3, pVirtio, 0 /* uVirtqNbr */);
             break;
         default:

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

@@ -1 +1 @@
 /* $Id$ */
+
 /** @file
- * Virtio_1_0.h - Virtio Declarations
+ * VirtioCore.h - Virtio Declarations
  */
 
@@ -93 +94 @@
 
 /**
- * Virtio descriptor chain representation.
- */
-typedef struct VIRTIO_DESC_CHAIN
-{
-    uint32_t            u32Magic;                                   /**< Magic value, VIRTIO_DESC_CHAIN_MAGIC.    */
+ * VirtIO buffers are actually descriptor chains. VirtIO's scatter-gather architecture
+ * defines a head descriptor (index into ring of descriptors), which is chained to 0 or more
+ * other descriptors that can optionally continue the chain.  This structure is VirtualBox's
+ * Virtq buffer representation, which contains a reference to the head desc chain idx and
+ * context for working with virtq buffers.
+ */
+typedef struct VIRTQBUF
+{
+    uint32_t            u32Magic;                                   /**< Magic value, VIRTQBUF_MAGIC.    */
     uint32_t volatile   cRefs;                                      /**< Reference counter. */
     uint32_t            uHeadIdx;                                   /**< Head idx of associated desc chain        */
@@ -112 +117 @@
     VIRTIOSGSEG         aSegsOut[VIRTQ_MAX_ENTRIES];
     /** @} */
-} VIRTIO_DESC_CHAIN_T;
-/** Pointer to a Virtio descriptor chain. */
-typedef VIRTIO_DESC_CHAIN_T *PVIRTIO_DESC_CHAIN_T;
-/** Pointer to a Virtio descriptor chain pointer. */
-typedef VIRTIO_DESC_CHAIN_T **PPVIRTIO_DESC_CHAIN_T;
-/** Magic value for VIRTIO_DESC_CHAIN_T::u32Magic. */
-#define VIRTIO_DESC_CHAIN_MAGIC             UINT32_C(0x19600219)
+} VIRTQBUF_T;
+
+/** Pointers to a Virtio descriptor chain. */
+typedef VIRTQBUF_T *PVIRTQBUF, **PPVIRTQBUF;
+/** Magic value for VIRTQBUF_T::u32Magic. */
+#define VIRTQBUF_MAGIC             UINT32_C(0x19600219)
 
 typedef struct VIRTIOPCIPARAMS
@@ -187 +191 @@
 typedef struct VIRTQSTATE
 {
-    uint16_t  idxVirtq;                                          /**< Index of this queue                       */
+    uint16_t  uVirtqNbr;                                          /**< Index of this queue                       */
     char      szVirtqName[32];                                   /**< Dev-specific name of queue                */
     uint16_t  uAvailIdxShadow;                                   /**< Consumer's position in avail ring         */
@@ -348 +352 @@
      * @param   pVirtio    Pointer to the shared virtio state.
      * @param   pVirtioCC  Pointer to the ring-3 virtio state.
-     * @param   idxVirtq   Index of the notified queue
+     * @param   uVirtqNbr   Index of the notified queue
      */
-    DECLCALLBACKMEMBER(void, pfnVirtqNotified)(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq);
+    DECLCALLBACKMEMBER(void, pfnVirtqNotified)(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
 
     /** @} */
@@ -381 +385 @@
      * @param   pVirtio    Pointer to the shared virtio state.
      * @param   pVirtioCC  Pointer to the ring-3 virtio state.
-     * @param   idxVirtq   Index of the notified queue
+     * @param   uVirtqNbr   Index of the notified queue
      */
-    DECLCALLBACKMEMBER(void, pfnVirtqNotified)(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq);
+    DECLCALLBACKMEMBER(void, pfnVirtqNotified)(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
 
 } VIRTIOCORER0;
@@ -405 +409 @@
  * @{ */
 
-int      virtioCoreVirtqSync(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq);
-uint16_t virtioCoreVirtqAvailCount(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq);
-void     virtioCoreVirtqEnable(PVIRTIOCORE pVirtio, uint16_t idxVirtq, bool fEnable);
-void     virtioCoreVirtqNotifyEnable(PVIRTIOCORE pVirtio, uint16_t idxVirtq, bool fEnable);
+
+/**
+ * Initiate orderly reset procedure. This is an exposed API for clients that might need it.
+ * Invoked by client to reset the device and driver (see VirtIO 1.0 section 2.1.1/2.1.2)
+ *
+ * @param   pVirtio     Pointer to the virtio state.
+ */
+void     virtioCoreResetAll(PVIRTIOCORE pVirtio);
+
+/**
+ * 'Attaches' the inheriting device-specific code's queue state to the VirtIO core
+ * queue management, informing the core of the name of the queue and number. The VirtIO core
+ * allocates the queue state information so it can handle all the core VirtiIO queue operations
+ * and dispatch callbacks, etc...
+ *
+ * @param   pVirtio     Pointer to the shared virtio state.
+ * @param   uVirtqNbr    Virtq number
+ * @param   pcszName    Name to give queue
+ *
+ * @returns VBox status code.
+ */
+int      virtioCoreR3VirtqAttach(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, const char *pcszName);
+
+/**
+ * Enables or disables a virtq
+ *
+ * @param   pVirtio     Pointer to the shared virtio state.
+ * @param   uVirtqNbr   Virtq number
+ * @param   fEnable     Flags whether to enable or disable the virtq
+ *
+ */
+
+void     virtioCoreVirtqEnable(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, bool fEnable);
+
+/**
+ * Enable or Disable notification for the specified queue
+ *
+ * @param   pVirtio     Pointer to the shared virtio state.
+ * @param   uVirtqNbr    Virtq number
+ * @param   fEnable    Selects notification mode (enabled or disabled)
+ */
+void     virtioCoreVirtqEnableNotify(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, bool fEnable);
+
+/*
+ * Notifies guest (via ISR or MSI-X) of device configuration change
+ *
+ * @param   pVirtio     Pointer to the shared virtio state.
+ */
 void     virtioCoreNotifyConfigChanged(PVIRTIOCORE pVirtio);
-void     virtioCoreResetAll(PVIRTIOCORE pVirtio);
+
+/*
+ * Displays the VirtIO spec-related features offered by the core component,
+ * as well as which features have been negotiated and accepted or declined by the guest driver,
+ * providing a summary view of the configuration the device is operating with.
+ *
+ * @param   pVirtio     Pointer to the shared virtio state.
+ * @param   pHlp        Pointer to the debug info hlp struct
+ */
 void     virtioCorePrintFeatures(VIRTIOCORE *pVirtio, PCDBGFINFOHLP pHlp);
 
-uint32_t virtioCoreR3DescChainRetain(PVIRTIO_DESC_CHAIN_T pDescChain);
-uint32_t virtioCoreR3DescChainRelease(PVIRTIOCORE pVirtio, PVIRTIO_DESC_CHAIN_T pDescChain);
-void     virtioCoreR3Info(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs);
-void     virtioCoreR3VirtqInfo(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs, int idxVirtq);
-int      virtioCoreR3VirtqAttach(PVIRTIOCORE pVirtio, uint16_t idxVirtq, const char *pcszName);
-
-int      virtioCoreR3DescChainGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq,
-                                  uint16_t uHeadIdx, PPVIRTIO_DESC_CHAIN_T ppDescChain);
-
-int      virtioCoreR3VirtqPeek(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq,
-                               PPVIRTIO_DESC_CHAIN_T ppDescChain);
-
-int      virtioCoreR3VirtqSkip(PVIRTIOCORE pVirtio, uint16_t idxVirtq);
-
-int      virtioCoreR3VirtqGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq,
-                              PPVIRTIO_DESC_CHAIN_T ppDescChain, bool fRemove);
-
-int      virtioCoreR3VirtqPut(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t idxVirtq, PRTSGBUF pSgVirtReturn,
-                              PVIRTIO_DESC_CHAIN_T pDescChain, bool fFence);
-
+/*
+ * Debuging assist feature displays the state of the VirtIO core code, which includes
+ * an overview of the state of all of the queues.
+ *
+ * This can be invoked when running the VirtualBox debugger, or from the command line
+ * using the command: "VboxManage debugvm <VM name or id> info <device name> [args]"
+ *
+ * Example:  VBoxManage debugvm myVnetVm info "virtio-net" all
+ *
+ * This is implemented currently to be invoked by the inheriting device-specific code
+ * (see DevVirtioNet for an example, which receives the debugvm command directly).
+ * That devices lists the available sub-options if no arguments are provided. In that
+ * example this virtq info related function is invoked hierarchically when virtio-net
+ * displays its device-specific queue info.
+ *
+ * @param   pDevIns     The device instance.
+ * @param   pHlp        Pointer to the debug info hlp struct
+ * @param   pszArgs     Arguments to function
+ */
+void     virtioCoreR3VirtqInfo(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs, int uVirtqNbr);
+
+/*
+ * Returns the number of avail bufs in the virtq.
+ *
+ * @param   pDevIns     The device instance.
+ * @param   pVirtio     Pointer to the shared virtio state.
+ * @param   uVirtqNbr   Virtqueue to return the count of buffers available for.
+ */
+uint16_t virtioCoreVirtqAvailCount(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
+
+/**
+ * Fetches descriptor chain using avail ring of indicated queue and converts the descriptor
+ * chain into its OUT (to device) and IN to guest components, but does NOT remove it from
+ * the 'avail' queue. I.e. doesn't advance the index.  This can be used with virtioVirtqSkip(),
+ * which *does* advance the avail index. Together they facilitate a mechanism that allows
+ * work with a queue element (descriptor chain) to be aborted if necessary, by not advancing
+ * the pointer, or, upon success calling the skip function (above) to move to the next element.
+ *
+ * Additionally it converts the OUT desc chain data to a contiguous virtual
+ * memory buffer for easy consumption by the caller. The caller must return the
+ * descriptor chain pointer via virtioCoreR3VirtqBufPut() and then call virtioCoreVirtqSync()
+ * at some point to return the data to the guest and complete the transaction.
+ *
+ * @param   pDevIns     The device instance.
+ * @param   pVirtio     Pointer to the shared virtio state.
+ * @param   uVirtqNbr   Virtq number
+ * @param   ppVirtqBuf Address to store pointer to descriptor chain that contains the
+ *                      pre-processed transaction information pulled from the virtq.
+ *
+ * @returns VBox status code:
+ * @retval  VINF_SUCCESS         Success
+ * @retval  VERR_INVALID_STATE   VirtIO not in ready state (asserted).
+ * @retval  VERR_NOT_AVAILABLE   If the queue is empty.
+ */
+int      virtioCoreR3VirtqBufPeek(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
+                                  PPVIRTQBUF ppVirtqBuf);
+
+/**
+ * Fetches the next descriptor chain using avail ring of indicated queue and converts the descriptor
+ * chain into its OUT (to device) and IN to guest components.
+ *
+ * Additionally it converts the OUT desc chain data to a contiguous virtual
+ * memory buffer for easy consumption by the caller. The caller must return the
+ * descriptor chain pointer via virtioCoreR3VirtqBufPut() and then call virtioCoreVirtqSync()
+ * at some point to return the data to the guest and complete the transaction.
+ *
+ * @param   pDevIns     The device instance.
+ * @param   pVirtio     Pointer to the shared virtio state.
+ * @param   uVirtqNbr    Virtq number
+ * @param   ppVirtqBuf Address to store pointer to descriptor chain that contains the
+ *                      pre-processed transaction information pulled from the virtq.
+ *                      Returned reference must be released by calling
+ *                      virtioCoreR3VirtqBufRelease().
+ * @param   fRemove     flags whether to remove desc chain from queue (false = peek)
+ *
+ * @returns VBox status code:
+ * @retval  VINF_SUCCESS         Success
+ * @retval  VERR_INVALID_STATE   VirtIO not in ready state (asserted).
+ * @retval  VERR_NOT_AVAILABLE   If the queue is empty.
+ */
+int      virtioCoreR3VirtqBufGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
+                                 PPVIRTQBUF ppVirtqBuf, bool fRemove);
+
+
+/**
+ * Fetches a specific descriptor chain using avail ring of indicated queue and converts the descriptor
+ * chain into its OUT (to device) and IN to guest components.
+ *
+ * Additionally it converts the OUT desc chain data to a contiguous virtual
+ * memory buffer for easy consumption by the caller. The caller must return the
+ * descriptor chain pointer via virtioCoreR3VirtqBufPut() and then call virtioCoreVirtqSync()
+ * at some point to return the data to the guest and complete the transaction.
+ *
+ * @param   pDevIns     The device instance.
+ * @param   pVirtio     Pointer to the shared virtio state.
+ * @param   uVirtqNbr    Virtq number
+ * @param   ppVirtqBuf Address to store pointer to descriptor chain that contains the
+ *                      pre-processed transaction information pulled from the virtq.
+ *                      Returned reference must be released by calling
+ *                      virtioCoreR3VirtqBufRelease().
+ * @param   fRemove     flags whether to remove desc chain from queue (false = peek)
+ *
+ * @returns VBox status code:
+ * @retval  VINF_SUCCESS         Success
+ * @retval  VERR_INVALID_STATE   VirtIO not in ready state (asserted).
+ * @retval  VERR_NOT_AVAILABLE   If the queue is empty.
+ */
+
+int      virtioCoreR3VirtqBufGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
+                                  uint16_t uHeadIdx, PPVIRTQBUF ppVirtqBuf);
+
+/**
+ * Returns data to the guest to complete a transaction initiated by virtVirtqGet().
+ *
+ * The caller passes in a pointer to a scatter-gather buffer of virtual memory segments
+ * and a pointer to the descriptor chain context originally derived from the pulled
+ * queue entry, and this function will write the virtual memory s/g buffer into the
+ * guest's physical memory free the descriptor chain. The caller handles the freeing
+ * (as needed) of the virtual memory buffer.
+ *
+ * @note This does a write-ahead to the used ring of the guest's queue. The data
+ *       written won't be seen by the guest until the next call to virtioCoreVirtqSync()
+ *
+ *
+ * @param   pDevIns         The device instance (for reading).
+ * @param   pVirtio         Pointer to the shared virtio state.
+ * @param   uVirtqNbr        Virtq number
+ *
+ * @param   pSgVirtReturn   Points to scatter-gather buffer of virtual memory
+ *                          segments the caller is returning to the guest.
+ *
+ * @param   pVirtqBuf      This contains the context of the scatter-gather
+ *                          buffer originally pulled from the queue.
+ *
+ * @param   fFence          If true, put up copy fence (memory barrier) after
+ *                          copying to guest phys. mem.
+ *
+ * @returns VBox status code.
+ * @retval  VINF_SUCCESS       Success
+ * @retval  VERR_INVALID_STATE VirtIO not in ready state
+ * @retval  VERR_NOT_AVAILABLE Virtq is empty
+ *
+ * @note    This function will not release any reference to pVirtqBuf.  The
+ *          caller must take care of that.
+ */
+
+int      virtioCoreR3VirtqBufPut(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, PRTSGBUF pSgVirtReturn,
+                                 PVIRTQBUF pVirtqBuf, bool fFence);
+
+/**
+ * Skip the next entry in the specified queue (typically used with virtioCoreR3VirtqBufPeek())
+ *
+ * @param   pVirtio     Pointer to the virtio state.
+ * @param   uVirtqNbr    Index of queue
+ */
+int      virtioCoreR3VirtqBufSkip(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
+
+/**
+ * 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
+ * virtioCoreR3VirtqBufPut() calls since the last sync. This should be called after one or
+ * more virtioCoreR3VirtqBufPut() 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   pDevIns     The device instance.
+ * @param   pVirtio     Pointer to the shared virtio state.
+ * @param   uVirtqNbr   Virtq number
+ *
+ * @returns VBox status code.
+ * @retval  VINF_SUCCESS       Success
+ * @retval  VERR_INVALID_STATE VirtIO not in ready state
+ */
+int      virtioCoreVirtqSync(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
+
+/**
+ * Retains a reference to the given descriptor chain.
+ *
+ * @returns New reference count.
+ * @retval  UINT32_MAX on invalid parameter.
+ * @param   pVirtqBuf      The descriptor chain to reference.
+ */
+uint32_t virtioCoreR3VirtqBufRetain(PVIRTQBUF pVirtqBuf);
+
+/**
+ * Releases a reference to the given descriptor chain.
+ *
+ * @returns New reference count.
+ * @retval  0 if freed or invalid parameter.
+ * @param   pVirtio         Pointer to the shared virtio state.
+ * @param   pVirtqBuf       The descriptor chain to reference.  NULL is quietly
+ *                          ignored (returns 0).
+ */
+uint32_t virtioCoreR3VirtqBufRelease(PVIRTIOCORE pVirtio, PVIRTQBUF pVirtqBuf);
 
 /**
@@ -438 +669 @@
  *
  * @param   pVirtio     Pointer to the virtio state.
- * @param   idxVirtq    Virtq number.
- * @returns   true or false indicating whether to enable queue or not
- */
-DECLINLINE(bool) virtioCoreIsVirtqEnabled(PVIRTIOCORE pVirtio, uint16_t idxVirtq)
-{
-    Assert(idxVirtq < RT_ELEMENTS(pVirtio->aVirtqState));
-    return pVirtio->uVirtqEnable[idxVirtq] != 0;
+ * @param   uVirtqNbr    Virtq number.
+ * @returns true or false indicating whether to enable queue or not
+ */
+DECLINLINE(bool) virtioCoreIsVirtqEnabled(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
+{
+    Assert(uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqState));
+    return pVirtio->uVirtqEnable[uVirtqNbr] != 0;
 }
 
 /**
- * Get name of queue, by idxVirtq, assigned at virtioCoreR3VirtqAttach()
+ * Get name of queue, by uVirtqNbr, assigned at virtioCoreR3VirtqAttach()
  *
  * @param   pVirtio     Pointer to the virtio state.
- * @param   idxVirtq    Virtq number.
+ * @param   uVirtqNbr    Virtq number.
  *
  * @returns Pointer to read-only queue name.
  */
-DECLINLINE(const char *) virtioCoreVirtqGetName(PVIRTIOCORE pVirtio, uint16_t idxVirtq)
-{
-    Assert((size_t)idxVirtq < RT_ELEMENTS(pVirtio->aVirtqState));
-    return pVirtio->aVirtqState[idxVirtq].szVirtqName;
+DECLINLINE(const char *) virtioCoreVirtqGetName(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
+{
+    Assert((size_t)uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqState));
+    return pVirtio->aVirtqState[uVirtqNbr].szVirtqName;
 }
 
@@ -470 +701 @@
     return pVirtio->uDriverFeatures;
 }
-
 
 /**
@@ -486 +716 @@
 }
 
-void virtioCoreLogMappedIoValue(const char *pszFunc, const char *pszMember, uint32_t uMemberSize,
+/**
+ * Log memory-mapped I/O input or output value.
+ *
+ * This is to be invoked by macros that assume they are invoked in functions with
+ * the relevant arguments. (See Virtio_1_0.cpp).
+ *
+ * It is exposed via the API so inheriting device-specific clients can provide similar
+ * logging capabilities for a consistent look-and-feel.
+ *
+ * @param   pszFunc     To avoid displaying this function's name via __FUNCTION__ or LogFunc()
+ * @param   pszMember   Name of struct member
+ * @param   pv          pointer to value
+ * @param   cb          size of value
+ * @param   uOffset     offset into member where value starts
+ * @param   fWrite      True if write I/O
+ * @param   fHasIndex   True if the member is indexed
+ * @param   idx         The index if fHasIndex
+ */
+const char *virtioCoreGetStateChangeText(VIRTIOVMSTATECHANGED enmState);void virtioCoreLogMappedIoValue(const char *pszFunc, const char *pszMember, uint32_t uMemberSize,
                                 const void *pv, uint32_t cb, uint32_t uOffset,
                                 int fWrite, int fHasIndex, uint32_t idx);
 
-/* Debug assist functions for consumer device code */
+/**
+ * Debug assist for any consumer device code that inherits VIRTIOCORE
+ *
+ * Does a formatted hex dump using Log(()), recommend using VIRTIO_HEX_DUMP() macro to
+ * control enabling of logging efficiently.
+ *
+ * @param   pv          pointer to buffer to dump contents of
+ * @param   cb          count of characters to dump from buffer
+ * @param   uBase       base address of per-row address prefixing of hex output
+ * @param   pszTitle    Optional title. If present displays title that lists
+ *                      provided text with value of cb to indicate size next to it.
+ */
 void virtioCoreHexDump(uint8_t *pv, uint32_t cb, uint32_t uBase, const char *pszTitle);
+
+/**
+ * Debug assist for any consumer device code that inherits VIRTIOCORE
+&
+ * Do a hex dump of memory in guest physical context
+ *
+ * @param   GCPhys      pointer to buffer to dump contents of
+ * @param   cb          count of characters to dump from buffer
+ * @param   uBase       base address of per-row address prefixing of hex output
+ * @param   pszTitle    Optional title. If present displays title that lists
+ *                      provided text with value of cb to indicate size next to it.
+ */
 void virtioCoreGCPhysHexDump(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint16_t cb, uint32_t uBase, const char *pszTitle);
 
-
+/** The following virtioCoreSgBuf*() functions mimic the functionality of the related RT s/g functions,
+ *  except they work with the data type GCPhys rather than void *
+ */
 void     virtioCoreSgBufInit(PVIRTIOSGBUF pGcSgBuf, PVIRTIOSGSEG paSegs, size_t cSegs);
 void     virtioCoreSgBufReset(PVIRTIOSGBUF pGcSgBuf);
@@ -504 +777 @@
 size_t   virtioCoreSgBufCalcTotalLength(PVIRTIOSGBUF pGcSgBuf);
 
+/** Misc VM and PDM boilerplate */
 int      virtioCoreR3SaveExec(PVIRTIOCORE pVirtio, PCPDMDEVHLPR3 pHlp, PSSMHANDLE pSSM);
 int      virtioCoreR3LoadExec(PVIRTIOCORE pVirtio, PCPDMDEVHLPR3 pHlp, PSSMHANDLE pSSM);
@@ -511 +785 @@
                       const char *pcszInstance, uint64_t fDevSpecificFeatures, void *pvDevSpecificCfg, uint16_t cbDevSpecificCfg);
 int      virtioCoreRZInit(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio);
+
+
 const char *virtioCoreGetStateChangeText(VIRTIOVMSTATECHANGED enmState);