VirtualBox

source: vbox/trunk/src/VBox/Devices/VirtIO/VirtioCore.h

Last change on this file was 101414, checked in by vboxsync, 7 months ago

Devices/VirtioCore: Correct check, bugref:10521
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 71.8 KB
Line 
1/* $Id: VirtioCore.h 101414 2023-10-11 08:07:50Z vboxsync $ */
2
3/** @file
4 * VirtioCore.h - Virtio Declarations
5 */
6
7/*
8 * Copyright (C) 2009-2023 Oracle and/or its affiliates.
9 *
10 * This file is part of VirtualBox base platform packages, as
11 * available from https://www.virtualbox.org.
12 *
13 * This program is free software; you can redistribute it and/or
14 * modify it under the terms of the GNU General Public License
15 * as published by the Free Software Foundation, in version 3 of the
16 * License.
17 *
18 * This program is distributed in the hope that it will be useful, but
19 * WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 * General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License
24 * along with this program; if not, see <https://www.gnu.org/licenses>.
25 *
26 * SPDX-License-Identifier: GPL-3.0-only
27 */
28
29#ifndef VBOX_INCLUDED_SRC_VirtIO_VirtioCore_h
30#define VBOX_INCLUDED_SRC_VirtIO_VirtioCore_h
31#ifndef RT_WITHOUT_PRAGMA_ONCE
32# pragma once
33#endif
34
35#include <iprt/ctype.h>
36#include <iprt/sg.h>
37#include <iprt/types.h>
38
39#ifdef LOG_ENABLED
40# define VIRTIO_HEX_DUMP(logLevel, pv, cb, base, title) \
41 do { \
42 if (LogIsItEnabled(logLevel, LOG_GROUP)) \
43 virtioCoreHexDump((pv), (cb), (base), (title)); \
44 } while (0)
45#else
46# define VIRTIO_HEX_DUMP(logLevel, pv, cb, base, title) do { } while (0)
47#endif
48
49/** Marks the start of the virtio saved state (just for sanity). */
50#define VIRTIO_SAVEDSTATE_MARKER UINT64_C(0x1133557799bbddff)
51
52/** Pointer to the shared VirtIO state. */
53typedef struct VIRTIOCORE *PVIRTIOCORE;
54/** Pointer to the ring-3 VirtIO state. */
55typedef struct VIRTIOCORER3 *PVIRTIOCORER3;
56/** Pointer to the ring-0 VirtIO state. */
57typedef struct VIRTIOCORER0 *PVIRTIOCORER0;
58/** Pointer to the raw-mode VirtIO state. */
59typedef struct VIRTIOCORERC *PVIRTIOCORERC;
60/** Pointer to the instance data for the current context. */
61typedef CTX_SUFF(PVIRTIOCORE) PVIRTIOCORECC;
62
63#define VIRTIO_MAX_VIRTQ_NAME_SIZE 32 /**< Maximum length of a queue name */
64#define VIRTQ_SIZE 1024 /**< Max size (# entries) of a virtq */
65#define VIRTQ_MAX_COUNT 24 /**< Max queues we allow guest to create */
66#define VIRTIO_NOTIFY_OFFSET_MULTIPLIER 2 /**< VirtIO Notify Cap. MMIO config param */
67#define VIRTIO_REGION_LEGACY_IO 0 /**< BAR for VirtIO legacy drivers MBZ */
68#define VIRTIO_REGION_PCI_CAP 2 /**< BAR for VirtIO Cap. MMIO (impl specific) */
69#define VIRTIO_REGION_MSIX_CAP 0 /**< Bar for MSI-X handling */
70#define VIRTIO_PAGE_SIZE 4096 /**< Page size used by VirtIO specification */
71
72/** Virtio-over-MMIO transport region size, excluding the device specific configuration area. */
73#define VIRTIO_MMIO_SIZE 256
74/** Register containing a magic value identifying a VirtIO over MMIO device - readonly. */
75#define VIRTIO_MMIO_REG_MAGIC_OFF 0
76/** Magic value read from the register. */
77# define VIRTIO_MMIO_REG_MAGIC_VALUE UINT32_C(0x74726976)
78/** Register containing th version of the MMIO transport - readonly. */
79#define VIRTIO_MMIO_REG_VERSION_OFF 4
80/** Version value read from the register. */
81# define VIRTIO_MMIO_REG_VERSION_VALUE UINT32_C(0x2)
82/** Register containing the device ID of the device - readonly. */
83#define VIRTIO_MMIO_REG_DEVICEID_OFF 8
84/** Register containing the vendor ID of the device - readonly. */
85#define VIRTIO_MMIO_REG_VENDORID_OFF 12
86/** Register containing the features the device supports - readonly. */
87#define VIRTIO_MMIO_REG_DEVICEFEAT_OFF 16
88/** Device features selection - writeonly. */
89#define VIRTIO_MMIO_REG_DEVICEFEATSEL_OFF 20
90/** Features of the device selected by the driver - writeonly. */
91#define VIRTIO_MMIO_REG_DRIVERFEAT_OFF 32
92/** - writeonly. */
93#define VIRTIO_MMIO_REG_DRIVERFEATSEL_OFF 36
94/** Virtual queue selection - writeonly. */
95#define VIRTIO_MMIO_REG_QUEUESEL_OFF 48
96/** - readonly */
97#define VIRTIO_MMIO_REG_QUEUENUMMAX_OFF 52
98/** - writeonly */
99#define VIRTIO_MMIO_REG_QUEUENUM_OFF 56
100/** - read/write. */
101#define VIRTIO_MMIO_REG_QUEUEALIGN_LEGACY_OFF 60
102/** - read/write. */
103#define VIRTIO_MMIO_REG_QUEUERDY_OFF 68
104/** - writeonly */
105#define VIRTIO_MMIO_REG_QUEUENOTIFY_OFF 80
106/** - readonly */
107#define VIRTIO_MMIO_REG_INTRSTATUS_OFF 96
108/** - writeonly */
109#define VIRTIO_MMIO_REG_INTRACK_OFF 100
110/** - read/write */
111#define VIRTIO_MMIO_REG_DEVSTATUS_OFF 112
112/** - writeonly */
113#define VIRTIO_MMIO_REG_QUEUEDESCLOW_OFF 128
114/** - writeonly */
115#define VIRTIO_MMIO_REG_QUEUEDESCHIGH_OFF 132
116/** - writeonly */
117#define VIRTIO_MMIO_REG_QUEUEDRVLOW_OFF 144
118/** - writeonly */
119#define VIRTIO_MMIO_REG_QUEUEDRVHIGH_OFF 148
120/** - writeonly */
121#define VIRTIO_MMIO_REG_QUEUEDEVLOW_OFF 160
122/** - writeonly */
123#define VIRTIO_MMIO_REG_QUEUEDEVHIGH_OFF 164
124/** - readonly */
125#define VIRTIO_MMIO_REG_CFGGEN_OFF 252
126
127
128/**
129 * @todo Move the following virtioCoreGCPhysChain*() functions mimic the functionality of the related
130 * into some VirtualBox source tree common location and out of this code.
131 *
132 * They behave identically to the S/G utilities in the RT library, except they work with that
133 * GCPhys data type specifically instead of void *, to avoid potentially disastrous mismatch
134 * between sizeof(void *) and sizeof(GCPhys).
135 *
136 */
137typedef struct VIRTIOSGSEG /**< An S/G entry */
138{
139 RTGCPHYS GCPhys; /**< Pointer to the segment buffer */
140 size_t cbSeg; /**< Size of the segment buffer */
141} VIRTIOSGSEG;
142
143typedef VIRTIOSGSEG *PVIRTIOSGSEG, **PPVIRTIOSGSEG;
144typedef const VIRTIOSGSEG *PCVIRTIOSGSEG;
145
146typedef struct VIRTIOSGBUF
147{
148 PVIRTIOSGSEG paSegs; /**< Pointer to the scatter/gather array */
149 unsigned cSegs; /**< Number of segs in scatter/gather array */
150 unsigned idxSeg; /**< Current segment we are in */
151 RTGCPHYS GCPhysCur; /**< Ptr to byte within the current seg */
152 size_t cbSegLeft; /**< # of bytes left in the current segment */
153} VIRTIOSGBUF;
154
155typedef VIRTIOSGBUF *PVIRTIOSGBUF, **PPVIRTIOSGBUF;
156typedef const VIRTIOSGBUF *PCVIRTIOSGBUF;
157
158/**
159 * VirtIO buffers are descriptor chains (e.g. scatter-gather vectors). A VirtIO buffer is referred to by the index
160 * of its head descriptor. Each descriptor optionally chains to another descriptor, and so on.
161 *
162 * For any given descriptor, each length and GCPhys pair in the chain represents either an OUT segment (e.g. guest-to-host)
163 * or an IN segment (host-to-guest).
164 *
165 * A VIRTQBUF is created and retured from a call to to either virtioCoreR3VirtqAvailBufPeek() or virtioCoreR3VirtqAvailBufGet().
166 *
167 * Those functions consolidate the VirtIO descriptor chain into a single representation where:
168 *
169 * pSgPhysSend GCPhys s/g buffer containing all of the (VirtIO) OUT descriptors
170 * pSgPhysReturn GCPhys s/g buffer containing all of the (VirtIO) IN descriptors
171 *
172 * The OUT descriptors are data sent from guest to host (dev-specific commands and/or data)
173 * The IN are to be filled with data (converted to physical) on host, to be returned to guest
174 *
175 */
176typedef struct VIRTQBUF
177{
178 uint32_t u32Magic; /**< Magic value, VIRTQBUF_MAGIC. */
179 uint16_t uVirtq; /**< VirtIO index of associated virtq */
180 uint16_t pad;
181 uint32_t volatile cRefs; /**< Reference counter. */
182 uint32_t uHeadIdx; /**< Head idx of associated desc chain */
183 size_t cbPhysSend; /**< Total size of src buffer */
184 PVIRTIOSGBUF pSgPhysSend; /**< Phys S/G buf for data from guest */
185 size_t cbPhysReturn; /**< Total size of dst buffer */
186 PVIRTIOSGBUF pSgPhysReturn; /**< Phys S/G buf to store result for guest */
187
188 /** @name Internal (bird combined 5 allocations into a single), fingers off.
189 * @{ */
190 VIRTIOSGBUF SgBufIn;
191 VIRTIOSGBUF SgBufOut;
192 VIRTIOSGSEG aSegsIn[VIRTQ_SIZE];
193 VIRTIOSGSEG aSegsOut[VIRTQ_SIZE];
194 /** @} */
195} VIRTQBUF_T;
196
197/** Pointers to a Virtio descriptor chain. */
198typedef VIRTQBUF_T *PVIRTQBUF, **PPVIRTQBUF;
199
200/** Magic value for VIRTQBUF_T::u32Magic. */
201#define VIRTQBUF_MAGIC UINT32_C(0x19600219)
202
203typedef struct VIRTIOPCIPARAMS
204{
205 uint16_t uDeviceId; /**< PCI Cfg Device ID */
206 uint16_t uClassBase; /**< PCI Cfg Base Class */
207 uint16_t uClassSub; /**< PCI Cfg Subclass */
208 uint16_t uClassProg; /**< PCI Cfg Programming Interface Class */
209 uint16_t uSubsystemId; /**< PCI Cfg Card Manufacturer Vendor ID */
210 uint16_t uInterruptLine; /**< PCI Cfg Interrupt line */
211 uint16_t uInterruptPin; /**< PCI Cfg Interrupt pin */
212 uint8_t uDeviceType; /**< Device type (used for Virtio-over-MMIO) */
213} VIRTIOPCIPARAMS, *PVIRTIOPCIPARAMS;
214
215
216/* Virtio Platform Independent Reserved Feature Bits (see 1.1 specification section 6) */
217
218#define VIRTIO_F_NOTIFY_ON_EMPTY RT_BIT_64(24) /**< Legacy feature: Force intr if no AVAIL */
219#define VIRTIO_F_ANY_LAYOUT RT_BIT_64(27) /**< Doc bug: Goes under two names in spec */
220#define VIRTIO_F_RING_INDIRECT_DESC RT_BIT_64(28) /**< Doc bug: Goes under two names in spec */
221#define VIRTIO_F_INDIRECT_DESC RT_BIT_64(28) /**< Allow descs to point to list of descs */
222#define VIRTIO_F_RING_EVENT_IDX RT_BIT_64(29) /**< Doc bug: Goes under two names in spec */
223#define VIRTIO_F_EVENT_IDX RT_BIT_64(29) /**< Allow notification disable for n elems */
224#define VIRTIO_F_BAD_FEATURE RT_BIT_64(30) /**< QEMU kludge. UNUSED as of >= VirtIO 1.0 */
225#define VIRTIO_F_VERSION_1 RT_BIT_64(32) /**< Required feature bit for 1.0 devices */
226#define VIRTIO_F_ACCESS_PLATFORM RT_BIT_64(33) /**< Funky guest mem access (VirtIO 1.1 NYI) */
227#define VIRTIO_F_RING_PACKED RT_BIT_64(34) /**< Packed Queue Layout (VirtIO 1.1 NYI) */
228#define VIRTIO_F_IN_ORDER RT_BIT_64(35) /**< Honor guest buf order (VirtIO 1.1 NYI) */
229#define VIRTIO_F_ORDER_PLATFORM RT_BIT_64(36) /**< Host mem access honored (VirtIO 1.1 NYI) */
230#define VIRTIO_F_SR_IOV RT_BIT_64(37) /**< Dev Single Root I/O virt (VirtIO 1.1 NYI) */
231#define VIRTIO_F_NOTIFICAITON_DATA RT_BIT_64(38) /**< Driver passes extra data (VirtIO 1.1 NYI) */
232
233typedef struct VIRTIO_FEATURES_LIST
234{
235 uint64_t fFeatureBit;
236 const char *pcszDesc;
237} VIRTIO_FEATURES_LIST, *PVIRTIO_FEATURES_LIST;
238
239static const VIRTIO_FEATURES_LIST s_aCoreFeatures[] =
240{
241 { VIRTIO_F_VERSION_1, " VERSION_1 Guest driver supports VirtIO specification V1.0+ (e.g. \"modern\")\n" },
242 { VIRTIO_F_RING_EVENT_IDX, " RING_EVENT_IDX Enables use_event and avail_event fields described in 2.4.7, 2.4.8\n" },
243 { VIRTIO_F_RING_INDIRECT_DESC, " RING_INDIRECT_DESC Driver can use descriptors with VIRTQ_DESC_F_INDIRECT flag set\n" },
244};
245
246#define VIRTIO_DEV_INDEPENDENT_FEATURES_OFFERED ( 0 ) /**< TBD: Add VIRTIO_F_INDIRECT_DESC */
247#define VIRTIO_DEV_INDEPENDENT_LEGACY_FEATURES_OFFERED ( 0 ) /**< Only offered to legacy drivers */
248
249#define VIRTIO_ISR_VIRTQ_INTERRUPT RT_BIT_32(0) /**< Virtq interrupt bit of ISR register */
250#define VIRTIO_ISR_DEVICE_CONFIG RT_BIT_32(1) /**< Device configuration changed bit of ISR */
251#define DEVICE_PCI_NETWORK_SUBSYSTEM 1 /**< Network Card, per VirtIO legacy spec. */
252#define DEVICE_PCI_REVISION_ID_VIRTIO_TRANS 0 /**< VirtIO Transitional device revision (MBZ) */
253#define DEVICE_PCI_REVISION_ID_VIRTIO_V1 1 /**< VirtIO device revision (SHOULD be >= 1) */
254
255#define DEVICE_PCI_VENDOR_ID_VIRTIO 0x1AF4 /**< Guest driver locates dev via (mandatory) */
256
257/**
258 * Start of the PCI device id range for non-transitional devices.
259 *
260 * "Devices ... have the PCI Device ID calculated by adding 0x1040 to
261 * the Virtio Device ID, as indicated in section [Device Types]. ...
262 * Non-transitional devices SHOULD have a PCI Device ID in the range
263 * 0x1040 to 0x107f.
264 */
265#define DEVICE_PCI_DEVICE_ID_VIRTIO_BASE 0x1040
266
267/**
268 * @name Virtio Device types as outlined in chapter 5.
269 * @{ */
270#define VIRTIO_DEVICE_TYPE_INVALID 0
271#define VIRTIO_DEVICE_TYPE_NETWORK 1
272#define VIRTIO_DEVICE_TYPE_BLOCK 2
273#define VIRTIO_DEVICE_TYPE_CONSOLE 3
274#define VIRTIO_DEVICE_TYPE_ENTROPY_SOURCE 4
275#define VIRTIO_DEVICE_TYPE_MEMORY_BALLOONING_TRAD 5
276#define VIRTIO_DEVICE_TYPE_IOMEM 6
277#define VIRTIO_DEVICE_TYPE_RPMSG 7
278#define VIRTIO_DEVICE_TYPE_SCSI_HOST 8
279#define VIRTIO_DEVICE_TYPE_9P_TRANSPORT 9
280#define VIRTIO_DEVICE_TYPE_MAC80211_WLAN 10
281#define VIRTIO_DEVICE_TYPE_RPROC_SERIAL 11
282#define VIRTIO_DEVICE_TYPE_CAIF 12
283#define VIRTIO_DEVICE_TYPE_MEMORY_BALLOONING 13
284#define VIRTIO_DEVICE_TYPE_GPU 16
285#define VIRTIO_DEVICE_TYPE_TIMER 17
286#define VIRTIO_DEVICE_TYPE_INPUT 18
287#define VIRTIO_DEVICE_TYPE_SOCKET 19
288#define VIRTIO_DEVICE_TYPE_CRYPTO 20
289#define VIRTIO_DEVICE_TYPE_SIGNAL_DIST_MOD 21
290#define VIRTIO_DEVICE_TYPE_PSTORE 22
291#define VIRTIO_DEVICE_TYPE_IOMMU 23
292#define VIRTIO_DEVICE_TYPE_MEMORY 24
293/** @} */
294
295/** Reserved (*negotiated*) Feature Bits (e.g. device independent features, VirtIO 1.0 spec,section 6) */
296
297#define VIRTIO_MSI_NO_VECTOR 0xffff /**< Vector value to disable MSI for queue */
298
299/** Device Status field constants (from Virtio 1.0 spec) */
300#define VIRTIO_STATUS_ACKNOWLEDGE 0x01 /**< Guest driver: Located this VirtIO device */
301#define VIRTIO_STATUS_DRIVER 0x02 /**< Guest driver: Can drive this VirtIO dev. */
302#define VIRTIO_STATUS_DRIVER_OK 0x04 /**< Guest driver: Driver set-up and ready */
303#define VIRTIO_STATUS_FEATURES_OK 0x08 /**< Guest driver: Feature negotiation done */
304#define VIRTIO_STATUS_FAILED 0x80 /**< Guest driver: Fatal error, gave up */
305#define VIRTIO_STATUS_DEVICE_NEEDS_RESET 0x40 /**< Device experienced unrecoverable error */
306
307typedef enum VIRTIOVMSTATECHANGED
308{
309 kvirtIoVmStateChangedInvalid = 0,
310 kvirtIoVmStateChangedReset,
311 kvirtIoVmStateChangedSuspend,
312 kvirtIoVmStateChangedPowerOff,
313 kvirtIoVmStateChangedResume,
314 kvirtIoVmStateChangedFor32BitHack = 0x7fffffff
315} VIRTIOVMSTATECHANGED;
316
317/** @def Virtio Device PCI Capabilities type codes */
318#define VIRTIO_PCI_CAP_COMMON_CFG 1 /**< Common configuration PCI capability ID */
319#define VIRTIO_PCI_CAP_NOTIFY_CFG 2 /**< Notification area PCI capability ID */
320#define VIRTIO_PCI_CAP_ISR_CFG 3 /**< ISR PCI capability id */
321#define VIRTIO_PCI_CAP_DEVICE_CFG 4 /**< Device-specific PCI cfg capability ID */
322#define VIRTIO_PCI_CAP_PCI_CFG 5 /**< PCI CFG capability ID */
323
324#define VIRTIO_PCI_CAP_ID_VENDOR 0x09 /**< Vendor-specific PCI CFG Device Cap. ID */
325
326/**
327 * The following is the PCI capability struct common to all VirtIO capability types
328 */
329typedef struct virtio_pci_cap
330{
331 /* All little-endian */
332 uint8_t uCapVndr; /**< Generic PCI field: PCI_CAP_ID_VNDR */
333 uint8_t uCapNext; /**< Generic PCI field: next ptr. */
334 uint8_t uCapLen; /**< Generic PCI field: capability length */
335 uint8_t uCfgType; /**< Identifies the structure. */
336 uint8_t uBar; /**< Where to find it. */
337 uint8_t uPadding[3]; /**< Pad to full dword. */
338 uint32_t uOffset; /**< Offset within bar. (L.E.) */
339 uint32_t uLength; /**< Length of struct, in bytes. (L.E.) */
340} VIRTIO_PCI_CAP_T, *PVIRTIO_PCI_CAP_T;
341
342/**
343 * VirtIO Legacy Capabilities' related MMIO-mapped structs (see virtio-0.9.5 spec)
344 *
345 * Note: virtio_pci_device_cap is dev-specific, implemented by client. Definition unknown here.
346 */
347typedef struct virtio_legacy_pci_common_cfg
348{
349 /* Device-specific fields */
350 uint32_t uDeviceFeatures; /**< RO (device reports features to driver) */
351 uint32_t uDriverFeatures; /**< RW (driver-accepted device features) */
352 uint32_t uVirtqPfn; /**< RW (driver writes queue page number) */
353 uint16_t uQueueSize; /**< RW (queue size, 0 - 2^n) */
354 uint16_t uVirtqSelect; /**< RW (selects queue focus for these fields) */
355 uint16_t uQueueNotify; /**< RO (offset into virtqueue; see spec) */
356 uint8_t fDeviceStatus; /**< RW (driver writes device status, 0=reset) */
357 uint8_t fIsrStatus; /**< RW (driver writes ISR status, 0=reset) */
358#ifdef LEGACY_MSIX_SUPPORTED
359 uint16_t uMsixConfig; /**< RW (driver sets MSI-X config vector) */
360 uint16_t uMsixVector; /**< RW (driver sets MSI-X config vector) */
361#endif
362} VIRTIO_LEGACY_PCI_COMMON_CFG_T, *PVIRTIO_LEGACY_PCI_COMMON_CFG_T;
363
364/**
365 * VirtIO 1.0 Capabilities' related MMIO-mapped structs:
366 *
367 * Note: virtio_pci_device_cap is dev-specific, implemented by client. Definition unknown here.
368 */
369typedef struct virtio_pci_common_cfg
370{
371 /* Device-specific fields */
372 uint32_t uDeviceFeaturesSelect; /**< RW (driver selects device features) */
373 uint32_t uDeviceFeatures; /**< RO (device reports features to driver) */
374 uint32_t uDriverFeaturesSelect; /**< RW (driver selects driver features) */
375 uint32_t uDriverFeatures; /**< RW (driver-accepted device features) */
376 uint16_t uMsixConfig; /**< RW (driver sets MSI-X config vector) */
377 uint16_t uNumVirtqs; /**< RO (device specifies max queues) */
378 uint8_t fDeviceStatus; /**< RW (driver writes device status, 0=reset) */
379 uint8_t uConfigGeneration; /**< RO (device changes when changing configs) */
380
381 /* Virtq-specific fields (values reflect (via MMIO) info related to queue indicated by uVirtqSelect. */
382 uint16_t uVirtqSelect; /**< RW (selects queue focus for these fields) */
383 uint16_t uQueueSize; /**< RW (queue size, 0 - 2^n) */
384 uint16_t uMsixVector; /**< RW (driver selects MSI-X queue vector) */
385 uint16_t uEnable; /**< RW (driver controls usability of queue) */
386 uint16_t uNotifyOffset; /**< RO (offset into virtqueue; see spec) */
387 uint64_t GCPhysVirtqDesc; /**< RW (driver writes desc table phys addr) */
388 uint64_t GCPhysVirtqAvail; /**< RW (driver writes avail ring phys addr) */
389 uint64_t GCPhysVirtqUsed; /**< RW (driver writes used ring phys addr) */
390} VIRTIO_PCI_COMMON_CFG_T, *PVIRTIO_PCI_COMMON_CFG_T;
391
392typedef struct virtio_pci_notify_cap
393{
394 struct virtio_pci_cap pciCap; /**< Notification MMIO mapping capability */
395 uint32_t uNotifyOffMultiplier; /**< notify_off_multiplier */
396} VIRTIO_PCI_NOTIFY_CAP_T, *PVIRTIO_PCI_NOTIFY_CAP_T;
397
398typedef struct virtio_pci_cfg_cap
399{
400 struct virtio_pci_cap pciCap; /**< Cap. defines the BAR/off/len to access */
401 uint8_t uPciCfgData[4]; /**< I/O buf for above cap. */
402} VIRTIO_PCI_CFG_CAP_T, *PVIRTIO_PCI_CFG_CAP_T;
403
404/**
405 * PCI capability data locations (PCI CFG and MMIO).
406 */
407typedef struct VIRTIO_PCI_CAP_LOCATIONS_T
408{
409 uint16_t offMmio;
410 uint16_t cbMmio;
411 uint16_t offPci;
412 uint16_t cbPci;
413} VIRTIO_PCI_CAP_LOCATIONS_T;
414
415typedef struct VIRTQUEUE
416{
417 RTGCPHYS GCPhysVirtqDesc; /**< (MMIO) Addr of virtq's desc ring GUEST */
418 RTGCPHYS GCPhysVirtqAvail; /**< (MMIO) Addr of virtq's avail ring GUEST */
419 RTGCPHYS GCPhysVirtqUsed; /**< (MMIO) Addr of virtq's used ring GUEST */
420 uint16_t uMsixVector; /**< (MMIO) MSI-X vector GUEST */
421 uint16_t uEnable; /**< (MMIO) Queue enable flag GUEST */
422 uint16_t uNotifyOffset; /**< (MMIO) Notification offset for queue HOST */
423 uint16_t uQueueSize; /**< (MMIO) Size of queue HOST/GUEST */
424 uint16_t uAvailIdxShadow; /**< Consumer's position in avail ring */
425 uint16_t uUsedIdxShadow; /**< Consumer's position in used ring */
426 uint16_t uVirtq; /**< Index of this queue */
427 char szName[32]; /**< Dev-specific name of queue */
428 bool fUsedRingEvent; /**< Flags if used idx to notify guest reached */
429 bool fAttached; /**< Flags if dev-specific client attached */
430} VIRTQUEUE, *PVIRTQUEUE;
431
432/**
433 * The core/common state of the VirtIO PCI devices, shared edition.
434 */
435typedef struct VIRTIOCORE
436{
437 char szInstance[16]; /**< Instance name, e.g. "VIRTIOSCSI0" */
438 PPDMDEVINS pDevInsR0; /**< Client device instance */
439 PPDMDEVINS pDevInsR3; /**< Client device instance */
440 VIRTQUEUE aVirtqueues[VIRTQ_MAX_COUNT]; /**< (MMIO) VirtIO contexts for queues */
441 uint64_t uDeviceFeatures; /**< (MMIO) Host features offered HOST */
442 uint64_t uDriverFeatures; /**< (MMIO) Host features accepted GUEST */
443 uint32_t fDriverFeaturesWritten; /**< (MMIO) Host features complete tracking */
444 uint32_t uDeviceFeaturesSelect; /**< (MMIO) hi/lo select uDeviceFeatures GUEST */
445 uint32_t uDriverFeaturesSelect; /**< (MMIO) hi/lo select uDriverFeatures GUEST */
446 uint32_t uMsixConfig; /**< (MMIO) MSI-X vector GUEST */
447 uint8_t fDeviceStatus; /**< (MMIO) Device Status GUEST */
448 uint8_t fPrevDeviceStatus; /**< (MMIO) Prev Device Status GUEST */
449 uint8_t uConfigGeneration; /**< (MMIO) Device config sequencer HOST */
450 uint16_t uQueueNotify; /**< Caches queue idx in legacy mode GUEST */
451 bool fGenUpdatePending; /**< If set, update cfg gen after driver reads */
452 uint8_t uPciCfgDataOff; /**< Offset to PCI configuration data area */
453 uint8_t uISR; /**< Interrupt Status Register. */
454 uint8_t fMsiSupport; /**< Flag set if using MSI instead of ISR */
455 uint16_t uVirtqSelect; /**< (MMIO) queue selector GUEST */
456 uint32_t fLegacyDriver; /**< Set if guest drv < VirtIO 1.0 and allowed */
457 uint32_t fOfferLegacy; /**< Set at init call from dev-specific code */
458 uint16_t uIrqMmio; /**< The interrupt number when Virtio-over-MMIO is used */
459 uint8_t uDeviceType; /**< The implemented device type for Virtio-over-MMIO */
460
461 /** @name The locations of the capability structures in PCI config space and the BAR.
462 * @{ */
463 VIRTIO_PCI_CAP_LOCATIONS_T LocPciCfgCap; /**< VIRTIO_PCI_CFG_CAP_T */
464 VIRTIO_PCI_CAP_LOCATIONS_T LocNotifyCap; /**< VIRTIO_PCI_NOTIFY_CAP_T */
465 VIRTIO_PCI_CAP_LOCATIONS_T LocCommonCfgCap; /**< VIRTIO_PCI_CAP_T */
466 VIRTIO_PCI_CAP_LOCATIONS_T LocIsrCap; /**< VIRTIO_PCI_CAP_T */
467 VIRTIO_PCI_CAP_LOCATIONS_T LocDeviceCap; /**< VIRTIO_PCI_CAP_T + custom data. */
468 /** @} */
469
470 IOMMMIOHANDLE hMmioPciCap; /**< MMIO handle of PCI cap. region (\#2) */
471 IOMIOPORTHANDLE hLegacyIoPorts; /**< Handle of legacy I/O port range. */
472
473#ifdef VBOX_WITH_STATISTICS
474 /** @name Statistics
475 * @{ */
476 STAMCOUNTER StatDescChainsAllocated;
477 STAMCOUNTER StatDescChainsFreed;
478 STAMCOUNTER StatDescChainsSegsIn;
479 STAMCOUNTER StatDescChainsSegsOut;
480 STAMPROFILEADV StatReadR3; /** I/O port and MMIO R3 Read profiling */
481 STAMPROFILEADV StatReadR0; /** I/O port and MMIO R0 Read profiling */
482 STAMPROFILEADV StatReadRC; /** I/O port and MMIO R3 Read profiling */
483 STAMPROFILEADV StatWriteR3; /** I/O port and MMIO R3 Write profiling */
484 STAMPROFILEADV StatWriteR0; /** I/O port and MMIO R3 Write profiling */
485 STAMPROFILEADV StatWriteRC; /** I/O port and MMIO R3 Write profiling */
486#endif
487 /** @} */
488
489} VIRTIOCORE;
490
491#define MAX_NAME 64
492
493/**
494 * The core/common state of the VirtIO PCI devices, ring-3 edition.
495 */
496typedef struct VIRTIOCORER3
497{
498 /** @name Callbacks filled by the device before calling virtioCoreR3Init.
499 * @{ */
500 /**
501 * Implementation-specific client callback to report VirtIO when feature negotiation is
502 * complete. It should be invoked by the VirtIO core only once.
503 *
504 * @param pVirtio Pointer to the shared virtio state.
505 * @param fDriverFeatures Bitmask of features the guest driver has accepted/declined.
506 * @param fLegacy true if legacy mode offered and until guest driver identifies itself
507 * as modern(e.g. VirtIO 1.0 featured)
508 */
509 DECLCALLBACKMEMBER(void, pfnFeatureNegotiationComplete, (PVIRTIOCORE pVirtio, uint64_t fDriverFeatures, uint32_t fLegacy));
510
511 /**
512 * Implementation-specific client callback to notify client of significant device status
513 * changes.
514 *
515 * @param pVirtio Pointer to the shared virtio state.
516 * @param pVirtioCC Pointer to the ring-3 virtio state.
517 * @param fDriverOk True if guest driver is okay (thus queues, etc... are
518 * valid)
519 */
520 DECLCALLBACKMEMBER(void, pfnStatusChanged,(PVIRTIOCORE pVirtio, PVIRTIOCORECC pVirtioCC, uint32_t fDriverOk));
521
522 /**
523 * Implementation-specific client callback to access VirtIO Device-specific capabilities
524 * (other VirtIO capabilities and features are handled in VirtIO implementation)
525 *
526 * @param pDevIns The device instance.
527 * @param offCap Offset within device specific capabilities struct.
528 * @param pvBuf Buffer in which to save read data.
529 * @param cbToRead Number of bytes to read.
530 */
531 DECLCALLBACKMEMBER(int, pfnDevCapRead,(PPDMDEVINS pDevIns, uint32_t offCap, void *pvBuf, uint32_t cbToRead));
532
533 /**
534 * Implementation-specific client callback to access VirtIO Device-specific capabilities
535 * (other VirtIO capabilities and features are handled in VirtIO implementation)
536 *
537 * @param pDevIns The device instance.
538 * @param offCap Offset within device specific capabilities struct.
539 * @param pvBuf Buffer with the bytes to write.
540 * @param cbToWrite Number of bytes to write.
541 */
542 DECLCALLBACKMEMBER(int, pfnDevCapWrite,(PPDMDEVINS pDevIns, uint32_t offCap, const void *pvBuf, uint32_t cbWrite));
543
544 /**
545 * When guest-to-host queue notifications are enabled, the guest driver notifies the host
546 * that the avail queue has buffers, and this callback informs the client.
547 *
548 * @param pVirtio Pointer to the shared virtio state.
549 * @param pVirtioCC Pointer to the ring-3 virtio state.
550 * @param uVirtqNbr Index of the notified queue
551 */
552 DECLCALLBACKMEMBER(void, pfnVirtqNotified,(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr));
553
554 /** @} */
555
556 R3PTRTYPE(PVIRTIO_PCI_CFG_CAP_T) pPciCfgCap; /**< Pointer to struct in PCI config area. */
557 R3PTRTYPE(PVIRTIO_PCI_NOTIFY_CAP_T) pNotifyCap; /**< Pointer to struct in PCI config area. */
558 R3PTRTYPE(PVIRTIO_PCI_CAP_T) pCommonCfgCap; /**< Pointer to struct in PCI config area. */
559 R3PTRTYPE(PVIRTIO_PCI_CAP_T) pIsrCap; /**< Pointer to struct in PCI config area. */
560 R3PTRTYPE(PVIRTIO_PCI_CAP_T) pDeviceCap; /**< Pointer to struct in PCI config area. */
561
562 uint32_t cbDevSpecificCfg; /**< Size of client's dev-specific config data */
563 R3PTRTYPE(uint8_t *) pbDevSpecificCfg; /**< Pointer to client's struct */
564 R3PTRTYPE(uint8_t *) pbPrevDevSpecificCfg; /**< Previous read dev-specific cfg of client */
565 bool fGenUpdatePending; /**< If set, update cfg gen after driver reads */
566 char szMmioName[MAX_NAME]; /**< MMIO mapping name */
567 char szPortIoName[MAX_NAME]; /**< PORT mapping name */
568} VIRTIOCORER3;
569
570/**
571 * The core/common state of the VirtIO PCI devices, ring-0 edition.
572 */
573typedef struct VIRTIOCORER0
574{
575 /**
576 * This callback notifies the device-specific portion of this device implementation (if guest-to-host
577 * queue notifications are enabled), that the guest driver has notified the host (this device)
578 * that the VirtIO "avail" ring of a queue has some new s/g buffers added by the guest VirtIO driver.
579 *
580 * @param pVirtio Pointer to the shared virtio state.
581 * @param pVirtioCC Pointer to the ring-3 virtio state.
582 * @param uVirtqNbr Index of the notified queue
583 */
584 DECLCALLBACKMEMBER(void, pfnVirtqNotified,(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr));
585
586} VIRTIOCORER0;
587
588/**
589 * The core/common state of the VirtIO PCI devices, raw-mode edition.
590 */
591typedef struct VIRTIOCORERC
592{
593 uint64_t uUnusedAtTheMoment;
594} VIRTIOCORERC;
595
596/** @typedef VIRTIOCORECC
597 * The instance data for the current context. */
598typedef CTX_SUFF(VIRTIOCORE) VIRTIOCORECC;
599
600/** @name API for VirtIO parent device
601 * @{ */
602
603/**
604 * Setup PCI device controller and Virtio state
605 *
606 * This should be called from PDMDEVREGR3::pfnConstruct.
607 *
608 * @param pDevIns Device instance.
609 * @param pVirtio Pointer to the shared virtio state. This
610 * must be the first member in the shared
611 * device instance data!
612 * @param pVirtioCC Pointer to the ring-3 virtio state. This
613 * must be the first member in the ring-3
614 * device instance data!
615 * @param pPciParams Values to populate industry standard PCI Configuration Space data structure
616 * @param pcszInstance Device instance name (format-specifier)
617 * @param fDevSpecificFeatures VirtIO device-specific features offered by
618 * client
619 * @param cbDevSpecificCfg Size of virtio_pci_device_cap device-specific struct
620 * @param pvDevSpecificCfg Address of client's dev-specific
621 * configuration struct.
622 */
623DECLHIDDEN(int) virtioCoreR3Init(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, PVIRTIOCORECC pVirtioCC,
624 PVIRTIOPCIPARAMS pPciParams, const char *pcszInstance,
625 uint64_t fDevSpecificFeatures, uint32_t fOfferLegacy, void *pvDevSpecificCfg, uint16_t cbDevSpecificCfg);
626/**
627 * Initiate orderly reset procedure. This is an exposed API for clients that might need it.
628 * Invoked by client to reset the device and driver (see VirtIO 1.0 section 2.1.1/2.1.2)
629 *
630 * @param pVirtio Pointer to the virtio state.
631 */
632DECLHIDDEN(void) virtioCoreResetAll(PVIRTIOCORE pVirtio);
633
634/**
635 * Resets the device state upon a VM reset for instance.
636 *
637 * @param pVirtio Pointer to the virtio state.
638 *
639 * @note Calls back into the upper device when the status changes.
640 */
641DECLHIDDEN(void) virtioCoreR3ResetDevice(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, PVIRTIOCORECC pVirtioCC);
642
643/**
644 * 'Attaches' host device-specific implementation's queue state to host VirtIO core
645 * virtqueue management infrastructure, informing the virtio core of the name of the
646 * queue to associate with the queue number.
647
648 * Note: uVirtqNbr (ordinal index) is used as the 'handle' for virtqs in this VirtioCore
649 * implementation's API (as an opaque selector into the VirtIO core's array of queues' states).
650 *
651 * Virtqueue numbers are actually VirtIO-specification defined device-specifically
652 * (i.e. they are unique within each VirtIO device type), but are in some cases scalable
653 * so only the pattern of queue numbers is defined by the spec and implementations may contain
654 * a self-determined plurality of queues.
655 *
656 * @param pVirtio Pointer to the shared virtio state.
657 * @param uVirtqNbr Virtq number
658 * @param pcszName Name to give queue
659 *
660 * @returns VBox status code.
661 */
662DECLHIDDEN(int) virtioCoreR3VirtqAttach(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, const char *pcszName);
663
664/**
665 * Detaches host device-specific implementation's queue state from the host VirtIO core
666 * virtqueue management infrastructure, informing the VirtIO core that the queue is
667 * not utilized by the device-specific code.
668 *
669 * @param pVirtio Pointer to the shared virtio state.
670 * @param uVirtqNbr Virtq number
671 * @param pcszName Name to give queue
672 *
673 * @returns VBox status code.
674 */
675DECLHIDDEN(int) virtioCoreR3VirtqDetach(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
676
677/**
678 * Checks to see whether queue is attached to core.
679 *
680 * @param pVirtio Pointer to the shared virtio state.
681 * @param uVirtqNbr Virtq number
682 *
683 * Returns boolean true or false indicating whether dev-specific reflection
684 * of queue is attached to core.
685 */
686DECLHIDDEN(bool) virtioCoreR3VirtqIsAttached(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
687
688/**
689 * Checks to see whether queue is enabled.
690 *
691 * @param pVirtio Pointer to the shared virtio state.
692 * @param uVirtqNbr Virtq number
693 *
694 * Returns boolean true or false indicating core queue enable state.
695 * There is no API function to enable the queue, because the actual enabling is handled
696 * by the guest via MMIO.
697 *
698 * NOTE: Guest VirtIO driver's claim over this state is overridden (which violates VirtIO 1.0 spec
699 * in a carefully controlled manner) in the case where the queue MUST be disabled, due to observed
700 * control queue corruption (e.g. null GCPhys virtq base addr) while restoring legacy-only device's
701 * (DevVirtioNet.cpp) as a way to flag that the queue is unusable-as-saved and must to be removed.
702 * That is all handled in the load/save exec logic. Device reset could potentially, depending on
703 * parameters passed from host VirtIO device to guest VirtIO driver, result in guest re-establishing
704 * queue, except, in that situation, the queue operational state would be valid.
705 */
706DECLHIDDEN(bool) virtioCoreR3VirtqIsEnabled(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
707
708/**
709 * Enable or disable notification for the specified queue.
710 *
711 * When queue notifications are enabled, the guest VirtIO driver notifies host VirtIO device
712 * (via MMIO, see VirtIO 1.0, 4.1.4.4 "Notification Structure Layout") whenever guest driver adds
713 * a new s/g buffer to the "avail" ring of the queue.
714 *
715 * Note: VirtIO queue layout includes flags the device controls in "used" ring to inform guest
716 * driver if it should notify host of guest's buffer additions to the "avail" ring, and
717 * conversely, the guest driver sets flags in the "avail" ring to communicate to host device
718 * whether or not to interrupt guest when it adds buffers to used ring.
719 *
720 * @param pVirtio Pointer to the shared virtio state.
721 * @param uVirtqNbr Virtq number
722 * @param fEnable Selects notification mode (enabled or disabled)
723 */
724DECLHIDDEN(void) virtioCoreVirtqEnableNotify(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, bool fEnable);
725
726/**
727 * Notifies guest (via ISR or MSI-X) of device configuration change
728 *
729 * @param pVirtio Pointer to the shared virtio state.
730 */
731DECLHIDDEN(void) virtioCoreNotifyConfigChanged(PVIRTIOCORE pVirtio);
732
733/**
734 * Displays a well-formatted human-readable translation of otherwise inscrutable bitmasks
735 * that embody features VirtIO specification definitions, indicating: Totality of features
736 * that can be implemented by host and guest, which features were offered by the host, and
737 * which were actually accepted by the guest. It displays it as a summary view of the device's
738 * finalized operational state (host-guest negotiated architecture) in such a way that shows
739 * which options are available for implementing or enabling.
740 *
741 * The non-device-specific VirtIO features list are managed by core API (e.g. implied).
742 * Only dev-specific features must be passed as parameter.
743
744 * @param pVirtio Pointer to the shared virtio state.
745 * @param pHlp Pointer to the debug info hlp struct
746 * @param s_aDevSpecificFeatures Dev-specific features (virtio-net, virtio-scsi...)
747 * @param cFeatures Number of features in aDevSpecificFeatures
748 */
749DECLHIDDEN(void) virtioCorePrintDeviceFeatures(VIRTIOCORE *pVirtio, PCDBGFINFOHLP pHlp,
750 const VIRTIO_FEATURES_LIST *aDevSpecificFeatures, int cFeatures);
751
752/*
753 * Debug-assist utility function to display state of the VirtIO core code, including
754 * an overview of the state of all of the queues.
755 *
756 * This can be invoked when running the VirtualBox debugger, or from the command line
757 * using the command: "VboxManage debugvm <VM name or id> info <device name> [args]"
758 *
759 * Example: VBoxManage debugvm myVnetVm info "virtio-net" help
760 *
761 * This is implemented currently to be invoked by the inheriting device-specific code
762 * (see the the VirtualBox virtio-net (VirtIO network controller device implementation)
763 * for an example of code that receive debugvm callback directly).
764 *
765 * DevVirtioNet lists available sub-options if no arguments are provided. In that
766 * example this virtq info related function is invoked hierarchically when virtio-net
767 * displays its device-specific queue info.
768 *
769 * @param pDevIns The device instance.
770 * @param pHlp Pointer to the debug info hlp struct
771 * @param pszArgs Arguments to function
772 */
773DECLHIDDEN(void) virtioCoreR3VirtqInfo(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs, int uVirtqNbr);
774
775/**
776 * Returns the number of avail bufs in the virtq.
777 *
778 * @param pDevIns The device instance.
779 * @param pVirtio Pointer to the shared virtio state.
780 * @param uVirtqNbr Virtqueue to return the count of buffers available for.
781 */
782DECLHIDDEN(uint16_t) virtioCoreVirtqAvailBufCount(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
783
784/**
785 * This function is identical to virtioCoreR3VirtqAvailBufGet(), *except* it doesn't consume
786 * peeked buffer from avail ring of the virtq. The function *becomes* identical to the
787 * virtioCoreR3VirtqAvailBufGet() only if virtioCoreR3VirtqAvailRingNext() is invoked to
788 * consume buf from the queue's avail ring, followed by invocation of virtioCoreR3VirtqUsedBufPut(),
789 * to hand host-processed buffer back to guest, which completes guest-initiated virtq buffer circuit.
790 *
791 * @param pDevIns The device instance.
792 * @param pVirtio Pointer to the shared virtio state.
793 * @param uVirtqNbr Virtq number
794 * @param pVirtqBuf Pointer to descriptor chain that contains the
795 * pre-processed transaction information pulled from the virtq.
796 *
797 * @returns VBox status code:
798 * @retval VINF_SUCCESS Success
799 * @retval VERR_INVALID_STATE VirtIO not in ready state (asserted).
800 * @retval VERR_NOT_AVAILABLE If the queue is empty.
801 */
802DECLHIDDEN(int) virtioCoreR3VirtqAvailBufPeek(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
803 PVIRTQBUF pVirtqBuf);
804
805/**
806 * This function fetches the next buffer (descriptor chain) from the VirtIO "avail" ring of
807 * indicated queue, separating the buf's s/g vectors into OUT (e.g. guest-to-host)
808 * components and and IN (host-to-guest) components.
809 *
810 * Caller is responsible for GCPhys to host virtual memory conversions. If the
811 * virtq buffer being peeked at is "consumed", virtioCoreR3VirtqAvailRingNext() must
812 * be called, and after that virtioCoreR3VirtqUsedBufPut() must be called to
813 * complete the buffer transfer cycle with the guest.
814 *
815 * @param pDevIns The device instance.
816 * @param pVirtio Pointer to the shared virtio state.
817 * @param uVirtqNbr Virtq number
818 * @param pVirtqBuf Pointer to descriptor chain that contains the
819 * pre-processed transaction information pulled from the virtq.
820 * @param fRemove flags whether to remove desc chain from queue (false = peek)
821 *
822 * @returns VBox status code:
823 * @retval VINF_SUCCESS Success
824 * @retval VERR_INVALID_STATE VirtIO not in ready state (asserted).
825 * @retval VERR_NOT_AVAILABLE If the queue is empty.
826 */
827DECLHIDDEN(int) virtioCoreR3VirtqAvailBufGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
828 PVIRTQBUF pVirtqBuf, bool fRemove);
829
830/**
831 * Fetches a specific descriptor chain using avail ring of indicated queue and converts the
832 * descriptor chain into its OUT (to device) and IN (to guest) components.
833 *
834 * The caller is responsible for GCPhys to host virtual memory conversions and *must*
835 * return the virtq buffer using virtioCoreR3VirtqUsedBufPut() to complete the roundtrip
836 * virtq transaction.
837 * *
838 * @param pDevIns The device instance.
839 * @param pVirtio Pointer to the shared virtio state.
840 * @param uVirtqNbr Virtq number
841 * @param pVirtqBuf Pointer to descriptor chain that contains the
842 * pre-processed transaction information pulled from the virtq.
843 * @param fRemove flags whether to remove desc chain from queue (false = peek)
844 *
845 * @returns VBox status code:
846 * @retval VINF_SUCCESS Success
847 * @retval VERR_INVALID_STATE VirtIO not in ready state (asserted).
848 * @retval VERR_NOT_AVAILABLE If the queue is empty.
849 */
850DECLHIDDEN(int) virtioCoreR3VirtqAvailBufGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
851 uint16_t uHeadIdx, PVIRTQBUF pVirtqBuf);
852
853/**
854 * Returns data to the guest to complete a transaction initiated by virtioCoreR3VirtqAvailBufGet(),
855 * (or virtioCoreR3VirtqAvailBufPeek()/virtioCoreR3VirtqBufSync() call pair), to complete each
856 * buffer transfer transaction (guest-host buffer cycle), ultimately moving each descriptor chain
857 * from the avail ring of a queue onto the used ring of the queue. Note that VirtIO buffer
858 * transactions are *always* initiated by the guest and completed by the host. In other words,
859 * for the host to send any I/O related data to the guest (and in some cases configuration data),
860 * the guest must provide buffers via the virtq's avail ring, for the host to fill.
861 *
862 * At some some point virtioCoreR3VirtqUsedRingSync() must be called to return data to the guest,
863 * completing all pending virtioCoreR3VirtqAvailBufPut() operations that have accumulated since
864 * the last call to virtioCoreR3VirtqUsedRingSync().
865
866 * @note This function effectively performs write-ahead to the used ring of the virtq.
867 * Data written won't be seen by the guest until the next call to virtioCoreVirtqUsedRingSync()
868 *
869 * @param pDevIns The device instance (for reading).
870 * @param pVirtio Pointer to the shared virtio state.
871 * @param uVirtqNbr Virtq number
872 *
873 * @param pSgVirtReturn Points to scatter-gather buffer of virtual memory
874 * segments the caller is returning to the guest.
875 *
876 * @param pVirtqBuf This contains the context of the scatter-gather
877 * buffer originally pulled from the queue.
878 *
879 * @param fFence If true (default), put up copy-fence (memory barrier) after
880 * copying to guest phys. mem.
881 *
882 * @returns VBox status code.
883 * @retval VINF_SUCCESS Success
884 * @retval VERR_INVALID_STATE VirtIO not in ready state
885 * @retval VERR_NOT_AVAILABLE Virtq is empty
886 *
887 * @note This function will not release any reference to pVirtqBuf. The
888 * caller must take care of that.
889 */
890DECLHIDDEN(int) virtioCoreR3VirtqUsedBufPut(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, PRTSGBUF pSgVirtReturn,
891 PVIRTQBUF pVirtqBuf, bool fFence = true);
892
893
894/**
895 * Quicker variant of same-named function (directly above) that it overloads,
896 * Instead, this variant accepts as input a pointer to a buffer and count,
897 * instead of S/G buffer thus doesn't have to copy between two S/G buffers and avoids some overhead.
898 *
899 * @param pDevIns The device instance (for reading).
900 * @param pVirtio Pointer to the shared virtio state.
901 * @param uVirtqNbr Virtq number
902 * @param cb Number of bytes to add to copy to phys. buf.
903 * @param pv Virtual mem buf to copy to phys buf.
904 * @param cbEnqueue How many bytes in packet to enqueue (0 = don't enqueue)
905 * @param fFence If true (default), put up copy-fence (memory barrier) after
906 * copying to guest phys. mem.
907 *
908 * @returns VBox status code.
909 * @retval VINF_SUCCESS Success
910 * @retval VERR_INVALID_STATE VirtIO not in ready state
911 * @retval VERR_NOT_AVAILABLE Virtq is empty
912 *
913 * @note This function will not release any reference to pVirtqBuf. The
914 * caller must take care of that.
915 */
916DECLHIDDEN(int) virtioCoreR3VirtqUsedBufPut(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtq, size_t cb, const void *pv,
917 PVIRTQBUF pVirtqBuf, size_t cbEnqueue, bool fFence = true);
918
919
920/**
921 * Advance index of avail ring to next entry in specified virtq (see virtioCoreR3VirtqAvailBufPeek())
922 *
923 * @param pVirtio Pointer to the virtio state.
924 * @param uVirtqNbr Index of queue
925 */
926DECLHIDDEN(int) virtioCoreR3VirtqAvailBufNext(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
927
928/**
929 * Checks to see if guest has accepted host device's VIRTIO_F_VERSION_1 (i.e. "modern")
930 * behavioral modeling, indicating guest agreed to comply with the modern VirtIO 1.0+ specification.
931 * Otherwise unavoidable presumption is that the host device is dealing with legacy VirtIO
932 * guest driver, thus must be prepared to cope with less mature architecture and behaviors
933 * from prototype era of VirtIO. (see comments in PDM-invoked device constructor for more
934 * information).
935 *
936 * @param pVirtio Pointer to the virtio state.
937 */
938DECLHIDDEN(int) virtioCoreIsLegacyMode(PVIRTIOCORE pVirtio);
939
940/**
941 * This VirtIO transitional device supports "modern" (rev 1.0+) as well as "legacy" (e.g. < 1.0) VirtIO drivers.
942 * Some legacy guest drivers are known to mishandle PCI bus mastering wherein the PCI flavor of GC phys
943 * access functions can't be used. The following wrappers select the memory access method based on whether the
944 * device is operating in legacy mode or not.
945 */
946DECLINLINE(int) virtioCoreGCPhysWrite(PVIRTIOCORE pVirtio, PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbWrite)
947{
948 int rc;
949 if ( virtioCoreIsLegacyMode(pVirtio)
950 || pVirtio->uIrqMmio)
951 rc = PDMDevHlpPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
952 else
953 rc = PDMDevHlpPCIPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
954 return rc;
955}
956
957DECLINLINE(int) virtioCoreGCPhysRead(PVIRTIOCORE pVirtio, PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
958{
959 int rc;
960 if ( virtioCoreIsLegacyMode(pVirtio)
961 || pVirtio->uIrqMmio)
962 rc = PDMDevHlpPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
963 else
964 rc = PDMDevHlpPCIPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
965 return rc;
966}
967
968/*
969 * (See comments for corresponding function in sg.h)
970 */
971DECLINLINE(void) virtioCoreGCPhysChainInit(PVIRTIOSGBUF pGcSgBuf, PVIRTIOSGSEG paSegs, size_t cSegs)
972{
973 AssertPtr(pGcSgBuf);
974 Assert((cSegs > 0 && RT_VALID_PTR(paSegs)) || (!cSegs && !paSegs));
975 Assert(cSegs < (~(unsigned)0 >> 1));
976
977 pGcSgBuf->paSegs = paSegs;
978 pGcSgBuf->cSegs = (unsigned)cSegs;
979 pGcSgBuf->idxSeg = 0;
980 if (cSegs && paSegs)
981 {
982 pGcSgBuf->GCPhysCur = paSegs[0].GCPhys;
983 pGcSgBuf->cbSegLeft = paSegs[0].cbSeg;
984 }
985 else
986 {
987 pGcSgBuf->GCPhysCur = 0;
988 pGcSgBuf->cbSegLeft = 0;
989 }
990}
991
992/*
993 * (See comments for corresponding function in sg.h)
994 */
995DECLINLINE(RTGCPHYS) virtioCoreGCPhysChainGet(PVIRTIOSGBUF pGcSgBuf, size_t *pcbData)
996{
997 size_t cbData;
998 RTGCPHYS pGcBuf;
999
1000 /* Check that the S/G buffer has memory left. */
1001 if (RT_LIKELY(pGcSgBuf->idxSeg < pGcSgBuf->cSegs || pGcSgBuf->cbSegLeft))
1002 { /* likely */ }
1003 else
1004 {
1005 *pcbData = 0;
1006 return 0;
1007 }
1008
1009 AssertMsg( pGcSgBuf->cbSegLeft <= 128 * _1M
1010 && (RTGCPHYS)pGcSgBuf->GCPhysCur >= (RTGCPHYS)pGcSgBuf->paSegs[pGcSgBuf->idxSeg].GCPhys
1011 && (RTGCPHYS)pGcSgBuf->GCPhysCur + pGcSgBuf->cbSegLeft <=
1012 (RTGCPHYS)pGcSgBuf->paSegs[pGcSgBuf->idxSeg].GCPhys + pGcSgBuf->paSegs[pGcSgBuf->idxSeg].cbSeg,
1013 ("pGcSgBuf->idxSeg=%d pGcSgBuf->cSegs=%d pGcSgBuf->GCPhysCur=%p pGcSgBuf->cbSegLeft=%zd "
1014 "pGcSgBuf->paSegs[%d].GCPhys=%p pGcSgBuf->paSegs[%d].cbSeg=%zd\n",
1015 pGcSgBuf->idxSeg, pGcSgBuf->cSegs, pGcSgBuf->GCPhysCur, pGcSgBuf->cbSegLeft,
1016 pGcSgBuf->idxSeg, pGcSgBuf->paSegs[pGcSgBuf->idxSeg].GCPhys, pGcSgBuf->idxSeg,
1017 pGcSgBuf->paSegs[pGcSgBuf->idxSeg].cbSeg));
1018
1019 cbData = RT_MIN(*pcbData, pGcSgBuf->cbSegLeft);
1020 pGcBuf = pGcSgBuf->GCPhysCur;
1021 pGcSgBuf->cbSegLeft -= cbData;
1022 if (!pGcSgBuf->cbSegLeft)
1023 {
1024 pGcSgBuf->idxSeg++;
1025
1026 if (pGcSgBuf->idxSeg < pGcSgBuf->cSegs)
1027 {
1028 pGcSgBuf->GCPhysCur = pGcSgBuf->paSegs[pGcSgBuf->idxSeg].GCPhys;
1029 pGcSgBuf->cbSegLeft = pGcSgBuf->paSegs[pGcSgBuf->idxSeg].cbSeg;
1030 }
1031 *pcbData = cbData;
1032 }
1033 else
1034 pGcSgBuf->GCPhysCur = pGcSgBuf->GCPhysCur + cbData;
1035
1036 return pGcBuf;
1037}
1038
1039/*
1040 * (See comments for corresponding function in sg.h)
1041 */
1042DECLINLINE(void) virtioCoreGCPhysChainReset(PVIRTIOSGBUF pGcSgBuf)
1043{
1044 AssertPtrReturnVoid(pGcSgBuf);
1045
1046 pGcSgBuf->idxSeg = 0;
1047 if (pGcSgBuf->cSegs)
1048 {
1049 pGcSgBuf->GCPhysCur = pGcSgBuf->paSegs[0].GCPhys;
1050 pGcSgBuf->cbSegLeft = pGcSgBuf->paSegs[0].cbSeg;
1051 }
1052 else
1053 {
1054 pGcSgBuf->GCPhysCur = 0;
1055 pGcSgBuf->cbSegLeft = 0;
1056 }
1057}
1058
1059/*
1060 * (See comments for corresponding function in sg.h)
1061 */
1062DECLINLINE(RTGCPHYS) virtioCoreGCPhysChainAdvance(PVIRTIOSGBUF pGcSgBuf, size_t cbAdvance)
1063{
1064 AssertReturn(pGcSgBuf, 0);
1065
1066 size_t cbLeft = cbAdvance;
1067 while (cbLeft)
1068 {
1069 size_t cbThisAdvance = cbLeft;
1070 virtioCoreGCPhysChainGet(pGcSgBuf, &cbThisAdvance);
1071 if (!cbThisAdvance)
1072 break;
1073
1074 cbLeft -= cbThisAdvance;
1075 }
1076 return cbAdvance - cbLeft;
1077}
1078
1079/*
1080 * (See comments for corresponding function in sg.h)
1081 */
1082DECLINLINE(RTGCPHYS) virtioCoreGCPhysChainGetNextSeg(PVIRTIOSGBUF pGcSgBuf, size_t *pcbSeg)
1083{
1084 AssertReturn(pGcSgBuf, 0);
1085 AssertPtrReturn(pcbSeg, 0);
1086
1087 if (!*pcbSeg)
1088 *pcbSeg = pGcSgBuf->cbSegLeft;
1089
1090 return virtioCoreGCPhysChainGet(pGcSgBuf, pcbSeg);
1091}
1092
1093/**
1094 * Calculate the length of a GCPhys s/g buffer by tallying the size of each segment.
1095 *
1096 * @param pGcSgBuf Guest Context (GCPhys) S/G buffer to calculate length of
1097 */
1098DECLINLINE(size_t) virtioCoreGCPhysChainCalcBufSize(PCVIRTIOSGBUF pGcSgBuf)
1099{
1100 size_t cb = 0;
1101 unsigned i = pGcSgBuf->cSegs;
1102 while (i-- > 0)
1103 cb += pGcSgBuf->paSegs[i].cbSeg;
1104 return cb;
1105}
1106
1107/*
1108 * (See comments for corresponding function in sg.h)
1109 */
1110DECLINLINE(size_t) virtioCoreGCPhysChainCalcLengthLeft(PVIRTIOSGBUF pGcSgBuf)
1111{
1112 size_t cb = pGcSgBuf->cbSegLeft;
1113 unsigned i = pGcSgBuf->cSegs;
1114 while (i-- > pGcSgBuf->idxSeg + 1)
1115 cb += pGcSgBuf->paSegs[i].cbSeg;
1116 return cb;
1117}
1118#define VIRTQNAME(a_pVirtio, a_uVirtq) ((a_pVirtio)->aVirtqueues[(a_uVirtq)].szName)
1119
1120/**
1121 * Convert and append bytes from a virtual-memory simple buffer to VirtIO guest's
1122 * physical memory described by a buffer pulled form the avail ring of a virtq.
1123 *
1124 * @param pVirtio Pointer to the shared virtio state.
1125 * @param pVirtqBuf VirtIO buffer to fill
1126 * @param pv input: virtual memory buffer to receive bytes
1127 * @param cb number of bytes to add to the s/g buffer.
1128 */
1129DECLINLINE(void) virtioCoreR3VirqBufFill(PVIRTIOCORE pVirtio, PVIRTQBUF pVirtqBuf, void *pv, size_t cb)
1130{
1131 uint8_t *pvBuf = (uint8_t *)pv;
1132 size_t cbRemain = cb, cbTotal = 0;
1133 PVIRTIOSGBUF pSgPhysReturn = pVirtqBuf->pSgPhysReturn;
1134 while (cbRemain)
1135 {
1136 size_t cbBounded = RT_MIN(pSgPhysReturn->cbSegLeft, cbRemain);
1137 Assert(cbBounded > 0);
1138 virtioCoreGCPhysWrite(pVirtio, CTX_SUFF(pVirtio->pDevIns), (RTGCPHYS)pSgPhysReturn->GCPhysCur, pvBuf, cbBounded);
1139 virtioCoreGCPhysChainAdvance(pSgPhysReturn, cbBounded);
1140 pvBuf += cbBounded;
1141 cbRemain -= cbBounded;
1142 cbTotal += cbBounded;
1143 }
1144 LogFunc(("Appended %d bytes to guest phys buf [head: %u]. %d bytes unused in buf.)\n",
1145 cbTotal, pVirtqBuf->uHeadIdx, virtioCoreGCPhysChainCalcLengthLeft(pSgPhysReturn)));
1146}
1147
1148/**
1149 * Extract some bytes from of a virtq s/g buffer, converting them from GCPhys space to
1150 * to ordinary virtual memory (i.e. making data directly accessible to host device code)
1151 *
1152 * As a performance optimization, it is left to the caller to validate buffer size.
1153 *
1154 * @param pVirtio Pointer to the shared virtio state.
1155 * @param pVirtqBuf input: virtq buffer
1156 * @param pv output: virtual memory buffer to receive bytes
1157 * @param cb number of bytes to Drain from buffer
1158 */
1159DECLINLINE(void) virtioCoreR3VirtqBufDrain(PVIRTIOCORE pVirtio, PVIRTQBUF pVirtqBuf, void *pv, size_t cb)
1160{
1161 uint8_t *pb = (uint8_t *)pv;
1162 size_t cbLim = RT_MIN(pVirtqBuf->cbPhysSend, cb);
1163 while (cbLim)
1164 {
1165 size_t cbSeg = cbLim;
1166 RTGCPHYS GCPhys = virtioCoreGCPhysChainGetNextSeg(pVirtqBuf->pSgPhysSend, &cbSeg);
1167 if (pVirtio->uIrqMmio)
1168 PDMDevHlpPhysRead(pVirtio->pDevInsR3, GCPhys, pb, cbSeg);
1169 else
1170 PDMDevHlpPCIPhysRead(pVirtio->pDevInsR3, GCPhys, pb, cbSeg);
1171 pb += cbSeg;
1172 cbLim -= cbSeg;
1173 pVirtqBuf->cbPhysSend -= cbSeg;
1174 }
1175 LogFunc(("Drained %d/%d bytes from %s buffer, head idx: %u (%d bytes left)\n",
1176 cb - cbLim, cb, VIRTQNAME(pVirtio, pVirtqBuf->uVirtq),
1177 pVirtqBuf->uHeadIdx, virtioCoreGCPhysChainCalcLengthLeft(pVirtqBuf->pSgPhysReturn)));
1178}
1179
1180#undef VIRTQNAME
1181
1182/**
1183 * Updates indicated virtq's "used ring" descriptor index to match "shadow" index that tracks
1184 * pending buffers added to the used ring, thus exposing all the data added by virtioCoreR3VirtqUsedBufPut()
1185 * to the "used ring" since the last virtioCoreVirtqUsedRingSync().
1186 *
1187 * This *must* be invoked after one or more virtioCoreR3VirtqUsedBufPut() calls to inform guest driver
1188 * there is data in the queue. If enabled by guest, IRQ or MSI-X signalling will notify guest
1189 * proactively, otherwise guest detects updates by polling. (see VirtIO 1.0, Section 2.4 "Virtqueues").
1190 *
1191 * @param pDevIns The device instance.
1192 * @param pVirtio Pointer to the shared virtio state.
1193 * @param uVirtqNbr Virtq number
1194 *
1195 * @returns VBox status code.
1196 * @retval VINF_SUCCESS Success
1197 * @retval VERR_INVALID_STATE VirtIO not in ready state
1198 */
1199DECLHIDDEN(int) virtioCoreVirtqUsedRingSync(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
1200
1201/**
1202 * Allocates a descriptor chain object with the reference count of one. Copying the reference
1203 * to this object requires a call to virtioCoreR3VirtqBufRetain. All references must be later
1204 * released with virtioCoreR3VirtqBufRelease. Just to be clear, one alloc plus one retain will
1205 * require two releases.
1206 *
1207 * @returns A descriptor chain object.
1208 *
1209 * @retval NULL if out of memory.
1210 *
1211 * NOTE: VIRTQBUF_T objects allocated on the stack will have garbage in the u32Magic field,
1212 * triggering an assertion if virtioCoreR3VirtqBufRelease is called on them.
1213 */
1214DECLHIDDEN(PVIRTQBUF) virtioCoreR3VirtqBufAlloc(void);
1215
1216/**
1217 * Retains a reference to the given descriptor chain.
1218 *
1219 * @param pVirtqBuf The descriptor chain to reference.
1220 *
1221 * @returns New reference count.
1222 * @retval UINT32_MAX on invalid parameter.
1223 */
1224DECLHIDDEN(uint32_t) virtioCoreR3VirtqBufRetain(PVIRTQBUF pVirtqBuf);
1225
1226/**
1227 * Releases a reference to the given descriptor chain.
1228 *
1229 * @param pVirtio Pointer to the shared virtio state.
1230 * @param pVirtqBuf The descriptor chain to reference. NULL is quietly
1231 * ignored (returns 0).
1232 * @returns New reference count.
1233 * @retval 0 if freed or invalid parameter.
1234 */
1235DECLHIDDEN(uint32_t) virtioCoreR3VirtqBufRelease(PVIRTIOCORE pVirtio, PVIRTQBUF pVirtqBuf);
1236
1237/**
1238 * Return queue enable state
1239 *
1240 * @param pVirtio Pointer to the virtio state.
1241 * @param uVirtqNbr Virtq number.
1242 *
1243 * @returns true or false indicating queue is enabled or not.
1244 */
1245DECLINLINE(bool) virtioCoreIsVirtqEnabled(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
1246{
1247 Assert(uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqueues));
1248 if (pVirtio->fLegacyDriver)
1249 return pVirtio->aVirtqueues[uVirtqNbr].GCPhysVirtqDesc != 0;
1250 return pVirtio->aVirtqueues[uVirtqNbr].uEnable != 0;
1251}
1252
1253/**
1254 * Get name of queue, via uVirtqNbr, assigned during virtioCoreR3VirtqAttach()
1255 *
1256 * @param pVirtio Pointer to the virtio state.
1257 * @param uVirtqNbr Virtq number.
1258 *
1259 * @returns Pointer to read-only queue name.
1260 */
1261DECLINLINE(const char *) virtioCoreVirtqGetName(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
1262{
1263 Assert((size_t)uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqueues));
1264 return pVirtio->aVirtqueues[uVirtqNbr].szName;
1265}
1266
1267/**
1268 * Get the bitmask of features VirtIO is running with. This is called by the device-specific
1269 * VirtIO implementation to identify this device's operational configuration after features
1270 * have been negotiated with guest VirtIO driver. Feature negotiation entails host indicating
1271 * to guest which features it supports, then guest accepting from among the offered, which features
1272 * it will enable. That becomes the agreement between the host and guest. The bitmask containing
1273 * virtio core features plus device-specific features is provided as a parameter to virtioCoreR3Init()
1274 * by the host side device-specific virtio implementation.
1275 *
1276 * @param pVirtio Pointer to the virtio state.
1277 *
1278 * @returns Features the guest driver has accepted, finalizing the operational features
1279 */
1280DECLINLINE(uint64_t) virtioCoreGetNegotiatedFeatures(PVIRTIOCORE pVirtio)
1281{
1282 return pVirtio->uDriverFeatures;
1283}
1284
1285/**
1286 * Get name of the VM state change associated with the enumeration variable
1287 *
1288 * @param enmState VM state (enumeration value)
1289 *
1290 * @returns associated text.
1291 */
1292DECLHIDDEN(const char *) virtioCoreGetStateChangeText(VIRTIOVMSTATECHANGED enmState);
1293
1294/**
1295 * Debug assist code for any consumer that inherits VIRTIOCORE.
1296 * Log memory-mapped I/O input or output value.
1297 *
1298 * This is to be invoked by macros that assume they are invoked in functions with
1299 * the relevant arguments. (See Virtio_1_0.cpp).
1300 *
1301 * It is exposed via the API so inheriting device-specific clients can provide similar
1302 * logging capabilities for a consistent look-and-feel.
1303 *
1304 * @param pszFunc To avoid displaying this function's name via __FUNCTION__ or LogFunc()
1305 * @param pszMember Name of struct member
1306 * @param pv pointer to value
1307 * @param cb size of value
1308 * @param uOffset offset into member where value starts
1309 * @param fWrite True if write I/O
1310 * @param fHasIndex True if the member is indexed
1311 * @param idx The index if fHasIndex
1312 */
1313DECLHIDDEN(void) virtioCoreLogMappedIoValue(const char *pszFunc, const char *pszMember, uint32_t uMemberSize,
1314 const void *pv, uint32_t cb, uint32_t uOffset,
1315 int fWrite, int fHasIndex, uint32_t idx);
1316
1317/**
1318 * Debug assist for any consumer
1319 *
1320 * Does a formatted hex dump using Log(()), recommend using VIRTIO_HEX_DUMP() macro to
1321 * control enabling of logging efficiently.
1322 *
1323 * @param pv pointer to buffer to dump contents of
1324 * @param cb count of characters to dump from buffer
1325 * @param uBase base address of per-row address prefixing of hex output
1326 * @param pszTitle Optional title. If present displays title that lists
1327 * provided text with value of cb to indicate VIRTQ_SIZE next to it.
1328 */
1329DECLHIDDEN(void) virtioCoreHexDump(uint8_t *pv, uint32_t cb, uint32_t uBase, const char *pszTitle);
1330
1331/**
1332 * Debug assist for any consumer device code
1333 * Do a hex dump of memory in guest physical context
1334 *
1335 * @param GCPhys pointer to buffer to dump contents of
1336 * @param cb count of characters to dump from buffer
1337 * @param uBase base address of per-row address prefixing of hex output
1338 * @param pszTitle Optional title. If present displays title that lists
1339 * provided text with value of cb to indicate size next to it.
1340 */
1341DECLHIDDEN(void) virtioCoreGCPhysHexDump(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint16_t cb, uint32_t uBase, const char *pszTitle);
1342
1343/**
1344 * The following API is functions identically to the similarly-named calls pertaining to the RTSGBUF
1345 */
1346
1347/** Misc VM and PDM boilerplate */
1348DECLHIDDEN(int) virtioCoreR3SaveExec(PVIRTIOCORE pVirtio, PCPDMDEVHLPR3 pHlp, PSSMHANDLE pSSM,
1349 uint32_t uVersion, uint32_t cQueues);
1350DECLHIDDEN(int) virtioCoreR3ModernDeviceLoadExec(PVIRTIOCORE pVirtio, PCPDMDEVHLPR3 pHlp, PSSMHANDLE pSSM,
1351 uint32_t uVersion, uint32_t uTestVersion, uint32_t cQueues);
1352DECLHIDDEN(int) virtioCoreR3LegacyDeviceLoadExec(PVIRTIOCORE pVirtio, PCPDMDEVHLPR3 pHlp, PSSMHANDLE pSSM,
1353 uint32_t uVersion, uint32_t uVirtioLegacy_3_1_Beta);
1354DECLHIDDEN(void) virtioCoreR3VmStateChanged(PVIRTIOCORE pVirtio, VIRTIOVMSTATECHANGED enmState);
1355DECLHIDDEN(void) virtioCoreR3Term(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, PVIRTIOCORECC pVirtioCC);
1356DECLHIDDEN(int) virtioCoreRZInit(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio);
1357DECLHIDDEN(const char *) virtioCoreGetStateChangeText(VIRTIOVMSTATECHANGED enmState);
1358
1359/*
1360 * The following macros assist with handling/logging MMIO accesses to VirtIO dev-specific config area,
1361 * in a way that enhances code readability and debug logging consistency.
1362 *
1363 * cb, pv and fWrite are implicit parameters and must be defined by the invoker.
1364 */
1365#ifdef LOG_ENABLED
1366
1367# define VIRTIO_DEV_CONFIG_LOG_ACCESS(member, tCfgStruct, uOffsetOfAccess) \
1368 if (LogIs7Enabled()) { \
1369 uint32_t uMbrOffset = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
1370 uint32_t uMbrSize = RT_SIZEOFMEMB(tCfgStruct, member); \
1371 virtioCoreLogMappedIoValue(__FUNCTION__, #member, uMbrSize, pv, cb, uMbrOffset, fWrite, false, 0); \
1372 }
1373
1374# define VIRTIO_DEV_CONFIG_LOG_INDEXED_ACCESS(member, tCfgStruct, uOffsetOfAccess, uIdx) \
1375 if (LogIs7Enabled()) { \
1376 uint32_t uMbrOffset = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
1377 uint32_t uMbrSize = RT_SIZEOFMEMB(tCfgStruct, member); \
1378 virtioCoreLogMappedIoValue(__FUNCTION__, #member, uMbrSize, pv, cb, uMbrOffset, fWrite, true, uIdx); \
1379 }
1380#else
1381# define VIRTIO_DEV_CONFIG_LOG_ACCESS(member, tCfgStruct, uMbrOffset) do { } while (0)
1382# define VIRTIO_DEV_CONFIG_LOG_INDEXED_ACCESS(member, tCfgStruct, uMbrOffset, uIdx) do { } while (0)
1383#endif
1384
1385DECLINLINE(bool) virtioCoreMatchMember(uint32_t uOffset, uint32_t cb, uint32_t uMemberOff,
1386 size_t uMemberSize, bool fSubFieldMatch)
1387{
1388 /* Test for 8-byte field (always accessed as two 32-bit components) */
1389 if (uMemberSize == 8)
1390 return (cb == sizeof(uint32_t)) && (uOffset == uMemberOff || uOffset == (uMemberOff + sizeof(uint32_t)));
1391
1392 if (fSubFieldMatch)
1393 return (uOffset >= uMemberOff) && (cb <= uMemberSize - (uOffset - uMemberOff));
1394
1395 /* Test for exact match */
1396 return (uOffset == uMemberOff) && (cb == uMemberSize);
1397}
1398
1399/**
1400 * Yields boolean true if uOffsetOfAccess falls within bytes of specified member of config struct
1401 */
1402#define VIRTIO_DEV_CONFIG_SUBMATCH_MEMBER(member, tCfgStruct, uOffsetOfAccess) \
1403 virtioCoreMatchMember(uOffsetOfAccess, cb, \
1404 RT_UOFFSETOF(tCfgStruct, member), \
1405 RT_SIZEOFMEMB(tCfgStruct, member), true /* fSubfieldMatch */)
1406
1407#define VIRTIO_DEV_CONFIG_MATCH_MEMBER(member, tCfgStruct, uOffsetOfAccess) \
1408 virtioCoreMatchMember(uOffsetOfAccess, cb, \
1409 RT_UOFFSETOF(tCfgStruct, member), \
1410 RT_SIZEOFMEMB(tCfgStruct, member), false /* fSubfieldMatch */)
1411
1412
1413
1414/**
1415 * Copy reads or copy writes specified member field of config struct (based on fWrite),
1416 * the memory described by cb and pv.
1417 *
1418 * cb, pv and fWrite are implicit parameters and must be defined by invoker.
1419 */
1420#define VIRTIO_DEV_CONFIG_ACCESS(member, tCfgStruct, uOffsetOfAccess, pCfgStruct) \
1421 do \
1422 { \
1423 uint32_t uOffsetInMember = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
1424 if (fWrite) \
1425 memcpy(((char *)&(pCfgStruct)->member) + uOffsetInMember, pv, cb); \
1426 else \
1427 memcpy(pv, ((const char *)&(pCfgStruct)->member) + uOffsetInMember, cb); \
1428 VIRTIO_DEV_CONFIG_LOG_ACCESS(member, tCfgStruct, uOffsetOfAccess); \
1429 } while(0)
1430
1431/**
1432 * Copies bytes into memory described by cb, pv from the specified member field of the config struct.
1433 * The operation is a NOP, logging an error if an implied parameter, fWrite, is boolean true.
1434 *
1435 * cb, pv and fWrite are implicit parameters and must be defined by the invoker.
1436 */
1437#define VIRTIO_DEV_CONFIG_ACCESS_READONLY(member, tCfgStruct, uOffsetOfAccess, pCfgStruct) \
1438 do \
1439 { \
1440 uint32_t uOffsetInMember = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
1441 if (fWrite) \
1442 LogFunc(("Guest attempted to write readonly virtio config struct (member %s)\n", #member)); \
1443 else \
1444 { \
1445 memcpy(pv, ((const char *)&(pCfgStruct)->member) + uOffsetInMember, cb); \
1446 VIRTIO_DEV_CONFIG_LOG_ACCESS(member, tCfgStruct, uOffsetOfAccess); \
1447 } \
1448 } while(0)
1449
1450/**
1451 * Copies into or out of specified member field of config struct (based on fWrite),
1452 * the memory described by cb and pv.
1453 *
1454 * cb, pv and fWrite are implicit parameters and must be defined by invoker.
1455 */
1456#define VIRTIO_DEV_CONFIG_ACCESS_INDEXED(member, uIdx, tCfgStruct, uOffsetOfAccess, pCfgStruct) \
1457 do \
1458 { \
1459 uint32_t uOffsetInMember = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
1460 if (fWrite) \
1461 memcpy(((char *)&(pCfgStruct[uIdx].member)) + uOffsetInMember, pv, cb); \
1462 else \
1463 memcpy(pv, ((const char *)&(pCfgStruct[uIdx].member)) + uOffsetInMember, cb); \
1464 VIRTIO_DEV_CONFIG_LOG_INDEXED_ACCESS(member, tCfgStruct, uOffsetOfAccess, uIdx); \
1465 } while(0)
1466
1467/**
1468 * Copies bytes into memory described by cb, pv from the specified member field of the config struct.
1469 * The operation is a nop and logs error if implied parameter fWrite is true.
1470 *
1471 * cb, pv and fWrite are implicit parameters and must be defined by invoker.
1472 */
1473#define VIRTIO_DEV_CONFIG_ACCESS_INDEXED_READONLY(member, uidx, tCfgStruct, uOffsetOfAccess, pCfgStruct) \
1474 do \
1475 { \
1476 uint32_t uOffsetInMember = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
1477 if (fWrite) \
1478 LogFunc(("Guest attempted to write readonly virtio config struct (member %s)\n", #member)); \
1479 else \
1480 { \
1481 memcpy(pv, ((const char *)&(pCfgStruct[uIdx].member)) + uOffsetInMember, cb); \
1482 VIRTIO_DEV_CONFIG_LOG_INDEXED_ACCESS(member, tCfgStruct, uOffsetOfAccess, uIdx); \
1483 } \
1484 } while(0)
1485
1486/** @} */
1487
1488/** @name API for VirtIO parent device
1489 * @{ */
1490
1491#endif /* !VBOX_INCLUDED_SRC_VirtIO_VirtioCore_h */
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use