VirtioCore.h@ 98103

Last change on this file since 98103 was 98103, checked in by vboxsync, 23 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 71.0 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: