VirtioCore.h@ 85109

Last change on this file since 85109 was 85109, checked in by vboxsync, 4 years ago
Resolved other part of xtracker #9766. Rearranged structs, arrays and pointers to improve cache locality (impacts: Network/DevVirtioNet.cpp, DevVirtioNet_1_0.cpp, and VirtIO/VirtioCore.*)
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 47.2 KB

Line
1	/* $Id: VirtioCore.h 85109 2020-07-08 14:03:45Z vboxsync $ */
2
3	/** @file
4	* VirtioCore.h - Virtio Declarations
5	*/
6
7	/*
8	* Copyright (C) 2009-2020 Oracle Corporation
9	*
10	* This file is part of VirtualBox Open Source Edition (OSE), as
11	* available from http://www.virtualbox.org. This file is free software;
12	* you can redistribute it and/or modify it under the terms of the GNU
13	* General Public License (GPL) as published by the Free Software
14	* Foundation, in version 2 as it comes in the "COPYING" file of the
15	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
16	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
17	*/
18
19	#ifndef VBOX_INCLUDED_SRC_VirtIO_VirtioCore_h
20	#define VBOX_INCLUDED_SRC_VirtIO_VirtioCore_h
21	#ifndef RT_WITHOUT_PRAGMA_ONCE
22	# pragma once
23	#endif
24
25	#include <iprt/ctype.h>
26	#include <iprt/sg.h>
27
28	#ifdef LOG_ENABLED
29	# define VIRTIO_HEX_DUMP(logLevel, pv, cb, base, title) \
30	do { \
31	if (LogIsItEnabled(logLevel, LOG_GROUP)) \
32	virtioCoreHexDump((pv), (cb), (base), (title)); \
33	} while (0)
34	#else
35	# define VIRTIO_HEX_DUMP(logLevel, pv, cb, base, title) do { } while (0)
36	#endif
37
38	/** Pointer to the shared VirtIO state. */
39	typedef struct VIRTIOCORE *PVIRTIOCORE;
40	/** Pointer to the ring-3 VirtIO state. */
41	typedef struct VIRTIOCORER3 *PVIRTIOCORER3;
42	/** Pointer to the ring-0 VirtIO state. */
43	typedef struct VIRTIOCORER0 *PVIRTIOCORER0;
44	/** Pointer to the raw-mode VirtIO state. */
45	typedef struct VIRTIOCORERC *PVIRTIOCORERC;
46	/** Pointer to the instance data for the current context. */
47	typedef CTX_SUFF(PVIRTIOCORE) PVIRTIOCORECC;
48
49	#define VIRTIO_MAX_VIRTQ_NAME_SIZE 32 /*< Maximum length of a queue name /
50	#define VIRTQ_MAX_ENTRIES 1024 /*< Max size (# desc elements) of a virtq /
51	#define VIRTQ_MAX_COUNT 24 /*< Max queues we allow guest to create /
52	#define VIRTIO_NOTIFY_OFFSET_MULTIPLIER 2 /*< VirtIO Notify Cap. MMIO config param /
53	#define VIRTIO_REGION_PCI_CAP 2 /*< BAR for VirtIO Cap. MMIO (impl specific) /
54	#define VIRTIO_REGION_MSIX_CAP 0 /*< Bar for MSI-X handling /
55
56
57	/** The following virtioCoreGCPhysChain*() functions mimic the functionality of the related RT s/g functions,
58	* except they work with the data type GCPhys rather than void *
59	*/
60	typedef struct VIRTIOSGSEG /*< An S/G entry /
61	{
62	RTGCPHYS GCPhys; /*< Pointer to the segment buffer /
63	size_t cbSeg; /*< Size of the segment buffer /
64	} VIRTIOSGSEG;
65
66	typedef VIRTIOSGSEG PVIRTIOSGSEG, *PPVIRTIOSGSEG;
67	typedef const VIRTIOSGSEG *PCVIRTIOSGSEG;
68
69	typedef struct VIRTIOSGBUF
70	{
71	PVIRTIOSGSEG paSegs; /*< Pointer to the scatter/gather array /
72	unsigned cSegs; /*< Number of segs in scatter/gather array /
73	unsigned idxSeg; /*< Current segment we are in /
74	RTGCPHYS GCPhysCur; /*< Ptr to byte within the current seg /
75	size_t cbSegLeft; /*< # of bytes left in the current segment /
76	} VIRTIOSGBUF;
77
78	typedef VIRTIOSGBUF PVIRTIOSGBUF, *PPVIRTIOSGBUF;
79	typedef const VIRTIOSGBUF *PCVIRTIOSGBUF;
80
81	/**
82	* VirtIO buffers are descriptor chains (scatter-gather vectors). Each buffer is described
83	* by the index of its head descriptor, which in optionally chains to another descriptor and so on.
84	* Each descriptor, e.g. [len, GCPhys] pair in the chain represents either an OUT segment (e.g. guest-to-host)
85	* or an IN segment (host-to-guest). A VIRTQBUF is created and retured from a call to virtioCoreR3VirtqAvailBufPeek()
86	* or virtioCoreR3VirtqAvailBufGet(). That function consolodates the VirtIO descriptor chain into a
87	* representation, where pSgPhysSend is GCPhys s/g buffer containing all of the OUT descriptors and pSgPhysReturn \
88	* is a GCPhys s/g buffer containing all of IN descriptors to be filled with data on the host to return to the
89	* guest.
90	*/
91	typedef struct VIRTQBUF
92	{
93	uint32_t u32Magic; /*< Magic value, VIRTQBUF_MAGIC. /
94	uint16_t uVirtq; /*< VirtIO index of associated virtq /
95	uint16_t pad;
96	uint32_t volatile cRefs; /*< Reference counter. /
97	uint32_t uHeadIdx; /*< Head idx of associated desc chain /
98	size_t cbPhysSend; /*< Total size of src buffer /
99	PVIRTIOSGBUF pSgPhysSend; /*< Phys S/G buf for data from guest /
100	size_t cbPhysReturn; /*< Total size of dst buffer /
101	PVIRTIOSGBUF pSgPhysReturn; /*< Phys S/G buf to store result for guest /
102
103	/** @name Internal (bird combined 5 allocations into a single), fingers off.
104	* @{ */
105	VIRTIOSGBUF SgBufIn;
106	VIRTIOSGBUF SgBufOut;
107	VIRTIOSGSEG aSegsIn[VIRTQ_MAX_ENTRIES];
108	VIRTIOSGSEG aSegsOut[VIRTQ_MAX_ENTRIES];
109	/** @} */
110	} VIRTQBUF_T;
111
112	/** Pointers to a Virtio descriptor chain. */
113	typedef VIRTQBUF_T PVIRTQBUF, *PPVIRTQBUF;
114
115	/** Magic value for VIRTQBUF_T::u32Magic. */
116	#define VIRTQBUF_MAGIC UINT32_C(0x19600219)
117
118	typedef struct VIRTIOPCIPARAMS
119	{
120	uint16_t uDeviceId; /*< PCI Cfg Device ID /
121	uint16_t uClassBase; /*< PCI Cfg Base Class /
122	uint16_t uClassSub; /*< PCI Cfg Subclass /
123	uint16_t uClassProg; /*< PCI Cfg Programming Interface Class /
124	uint16_t uSubsystemId; /*< PCI Cfg Card Manufacturer Vendor ID /
125	uint16_t uInterruptLine; /*< PCI Cfg Interrupt line /
126	uint16_t uInterruptPin; /*< PCI Cfg Interrupt pin /
127	} VIRTIOPCIPARAMS, *PVIRTIOPCIPARAMS;
128
129	#define VIRTIO_F_VERSION_1 RT_BIT_64(32) /*< Required feature bit for 1.0 devices /
130	#define VIRTIO_F_INDIRECT_DESC RT_BIT_64(28) /*< Allow descs to point to list of descs /
131	#define VIRTIO_F_EVENT_IDX RT_BIT_64(29) /*< Allow notification disable for n elems /
132	#define VIRTIO_F_RING_INDIRECT_DESC RT_BIT_64(28) /*< Doc bug: Goes under two names in spec /
133	#define VIRTIO_F_RING_EVENT_IDX RT_BIT_64(29) /*< Doc bug: Goes under two names in spec /
134
135	#define VIRTIO_DEV_INDEPENDENT_FEATURES_OFFERED ( 0 ) /*< TBD: Add VIRTIO_F_INDIRECT_DESC /
136
137	#define VIRTIO_ISR_VIRTQ_INTERRUPT RT_BIT_32(0) /*< Virtq interrupt bit of ISR register /
138	#define VIRTIO_ISR_DEVICE_CONFIG RT_BIT_32(1) /*< Device configuration changed bit of ISR /
139	#define DEVICE_PCI_VENDOR_ID_VIRTIO 0x1AF4 /*< Guest driver locates dev via (mandatory) /
140	#define DEVICE_PCI_REVISION_ID_VIRTIO 1 /*< VirtIO 1.0 non-transitional drivers >= 1 /
141
142	/** Reserved (negotiated) Feature Bits (e.g. device independent features, VirtIO 1.0 spec,section 6) */
143
144	#define VIRTIO_MSI_NO_VECTOR 0xffff /*< Vector value to disable MSI for queue /
145
146	/** Device Status field constants (from Virtio 1.0 spec) */
147	#define VIRTIO_STATUS_ACKNOWLEDGE 0x01 /*< Guest driver: Located this VirtIO device /
148	#define VIRTIO_STATUS_DRIVER 0x02 /*< Guest driver: Can drive this VirtIO dev. /
149	#define VIRTIO_STATUS_DRIVER_OK 0x04 /*< Guest driver: Driver set-up and ready /
150	#define VIRTIO_STATUS_FEATURES_OK 0x08 /*< Guest driver: Feature negotiation done /
151	#define VIRTIO_STATUS_FAILED 0x80 /*< Guest driver: Fatal error, gave up /
152	#define VIRTIO_STATUS_DEVICE_NEEDS_RESET 0x40 /*< Device experienced unrecoverable error /
153
154	typedef enum VIRTIOVMSTATECHANGED
155	{
156	kvirtIoVmStateChangedInvalid = 0,
157	kvirtIoVmStateChangedReset,
158	kvirtIoVmStateChangedSuspend,
159	kvirtIoVmStateChangedPowerOff,
160	kvirtIoVmStateChangedResume,
161	kvirtIoVmStateChangedFor32BitHack = 0x7fffffff
162	} VIRTIOVMSTATECHANGED;
163
164	/** @def Virtio Device PCI Capabilities type codes */
165	#define VIRTIO_PCI_CAP_COMMON_CFG 1 /*< Common configuration PCI capability ID /
166	#define VIRTIO_PCI_CAP_NOTIFY_CFG 2 /*< Notification area PCI capability ID /
167	#define VIRTIO_PCI_CAP_ISR_CFG 3 /*< ISR PCI capability id /
168	#define VIRTIO_PCI_CAP_DEVICE_CFG 4 /*< Device-specific PCI cfg capability ID /
169	#define VIRTIO_PCI_CAP_PCI_CFG 5 /*< PCI CFG capability ID /
170
171	#define VIRTIO_PCI_CAP_ID_VENDOR 0x09 /*< Vendor-specific PCI CFG Device Cap. ID /
172
173	/**
174	* The following is the PCI capability struct common to all VirtIO capability types
175	*/
176	typedef struct virtio_pci_cap
177	{
178	/* All little-endian */
179	uint8_t uCapVndr; /*< Generic PCI field: PCI_CAP_ID_VNDR /
180	uint8_t uCapNext; /*< Generic PCI field: next ptr. /
181	uint8_t uCapLen; /*< Generic PCI field: capability length /
182	uint8_t uCfgType; /*< Identifies the structure. /
183	uint8_t uBar; /*< Where to find it. /
184	uint8_t uPadding[3]; /*< Pad to full dword. /
185	uint32_t uOffset; /*< Offset within bar. (L.E.) /
186	uint32_t uLength; /*< Length of struct, in bytes. (L.E.) /
187	} VIRTIO_PCI_CAP_T, *PVIRTIO_PCI_CAP_T;
188
189	/**
190	* VirtIO 1.0 Capabilities' related MMIO-mapped structs:
191	*
192	* Note: virtio_pci_device_cap is dev-specific, implemented by client. Definition unknown here.
193	*/
194	typedef struct virtio_pci_common_cfg
195	{
196	/* Device-specific fields */
197	uint32_t uDeviceFeaturesSelect; /*< RW (driver selects device features) /
198	uint32_t uDeviceFeatures; /*< RO (device reports features to driver) /
199	uint32_t uDriverFeaturesSelect; /*< RW (driver selects driver features) /
200	uint32_t uDriverFeatures; /*< RW (driver-accepted device features) /
201	uint16_t uMsixConfig; /*< RW (driver sets MSI-X config vector) /
202	uint16_t uNumVirtqs; /*< RO (device specifies max queues) /
203	uint8_t fDeviceStatus; /*< RW (driver writes device status, 0=reset) /
204	uint8_t uConfigGeneration; /*< RO (device changes when changing configs) /
205
206	/* Virtq-specific fields (values reflect (via MMIO) info related to queue indicated by uVirtqSelect. */
207	uint16_t uVirtqSelect; /*< RW (selects queue focus for these fields) /
208	uint16_t uSize; /*< RW (queue size, 0 - 2^n) /
209	uint16_t uMsix; /*< RW (driver selects MSI-X queue vector) /
210	uint16_t uEnable; /*< RW (driver controls usability of queue) /
211	uint16_t uNotifyOffset; /*< RO (offset into virtqueue; see spec) /
212	uint64_t GCPhysVirtqDesc; /*< RW (driver writes desc table phys addr) /
213	uint64_t GCPhysVirtqAvail; /*< RW (driver writes avail ring phys addr) /
214	uint64_t GCPhysVirtqUsed; /*< RW (driver writes used ring phys addr) /
215	} VIRTIO_PCI_COMMON_CFG_T, *PVIRTIO_PCI_COMMON_CFG_T;
216
217	typedef struct virtio_pci_notify_cap
218	{
219	struct virtio_pci_cap pciCap; /*< Notification MMIO mapping capability /
220	uint32_t uNotifyOffMultiplier; /*< notify_off_multiplier /
221	} VIRTIO_PCI_NOTIFY_CAP_T, *PVIRTIO_PCI_NOTIFY_CAP_T;
222
223	typedef struct virtio_pci_cfg_cap
224	{
225	struct virtio_pci_cap pciCap; /*< Cap. defines the BAR/off/len to access /
226	uint8_t uPciCfgData[4]; /*< I/O buf for above cap. /
227	} VIRTIO_PCI_CFG_CAP_T, *PVIRTIO_PCI_CFG_CAP_T;
228
229	/**
230	* PCI capability data locations (PCI CFG and MMIO).
231	*/
232	typedef struct VIRTIO_PCI_CAP_LOCATIONS_T
233	{
234	uint16_t offMmio;
235	uint16_t cbMmio;
236	uint16_t offPci;
237	uint16_t cbPci;
238	} VIRTIO_PCI_CAP_LOCATIONS_T;
239
240	typedef struct VIRTQUEUE
241	{
242	RTGCPHYS GCPhysVirtqDesc; /*< (MMIO) PhysAdr per-Q desc structs GUEST /
243	RTGCPHYS GCPhysVirtqAvail; /*< (MMIO) PhysAdr per-Q avail structs GUEST /
244	RTGCPHYS GCPhysVirtqUsed; /*< (MMIO) PhysAdr per-Q used structs GUEST /
245	uint16_t uNotifyOffset; /*< (MMIO) per-Q notify offset HOST /
246	uint16_t uMsix; /*< (MMIO) Per-queue vector for MSI-X GUEST /
247	uint16_t uEnable; /*< (MMIO) Per-queue enable GUEST /
248	uint16_t uSize; /*< (MMIO) Per-queue size HOST/GUEST /
249	uint16_t uAvailIdxShadow; /*< Consumer's position in avail ring /
250	uint16_t uUsedIdxShadow; /*< Consumer's position in used ring /
251	bool fUsedRingEvent; /*< Flags if used idx to notify guest reached /
252	uint16_t uVirtq; /*< Index of this queue /
253	char szName[32]; /*< Dev-specific name of queue /
254	uint8_t padding[3];
255	} VIRTQUEUE, *PVIRTQUEUE;
256
257	/**
258	* The core/common state of the VirtIO PCI devices, shared edition.
259	*/
260	typedef struct VIRTIOCORE
261	{
262	char szInstance[16]; /*< Instance name, e.g. "VIRTIOSCSI0" /
263	PPDMDEVINS pDevInsR0; /*< Client device instance /
264	PPDMDEVINS pDevInsR3; /*< Client device instance /
265	VIRTQUEUE aVirtqueues[VIRTQ_MAX_COUNT]; /*< (MMIO) VirtIO contexts for queues /
266	uint64_t uDeviceFeatures; /*< (MMIO) Host features offered HOST /
267	uint64_t uDriverFeatures; /*< (MMIO) Host features accepted GUEST /
268	uint32_t uDeviceFeaturesSelect; /*< (MMIO) hi/lo select uDeviceFeatures GUEST /
269	uint32_t uDriverFeaturesSelect; /*< (MMIO) hi/lo select uDriverFeatures GUEST /
270	uint32_t uMsixConfig; /*< (MMIO) MSI-X vector GUEST /
271	uint8_t fDeviceStatus; /*< (MMIO) Device Status GUEST /
272	uint8_t uPrevDeviceStatus; /*< (MMIO) Prev Device Status GUEST /
273	uint8_t uConfigGeneration; /*< (MMIO) Device config sequencer HOST /
274
275	/** @name The locations of the capability structures in PCI config space and the BAR.
276	* @{ */
277	VIRTIO_PCI_CAP_LOCATIONS_T LocPciCfgCap; /*< VIRTIO_PCI_CFG_CAP_T /
278	VIRTIO_PCI_CAP_LOCATIONS_T LocNotifyCap; /*< VIRTIO_PCI_NOTIFY_CAP_T /
279	VIRTIO_PCI_CAP_LOCATIONS_T LocCommonCfgCap; /*< VIRTIO_PCI_CAP_T /
280	VIRTIO_PCI_CAP_LOCATIONS_T LocIsrCap; /*< VIRTIO_PCI_CAP_T /
281	VIRTIO_PCI_CAP_LOCATIONS_T LocDeviceCap; /*< VIRTIO_PCI_CAP_T + custom data. /
282	/** @} */
283
284	uint16_t uVirtqSelect; /*< (MMIO) queue selector GUEST /
285	bool fGenUpdatePending; /*< If set, update cfg gen after driver reads /
286	uint8_t uPciCfgDataOff; /*< Offset to PCI configuration data area /
287	uint8_t uISR; /*< Interrupt Status Register. /
288	uint8_t fMsiSupport; /*< Flag set if using MSI instead of ISR /
289	/** The MMIO handle for the PCI capability region (\#2). */
290	IOMMMIOHANDLE hMmioPciCap;
291
292	/** @name Statistics
293	* @{ */
294	STAMCOUNTER StatDescChainsAllocated;
295	STAMCOUNTER StatDescChainsFreed;
296	STAMCOUNTER StatDescChainsSegsIn;
297	STAMCOUNTER StatDescChainsSegsOut;
298	/** @} */
299	} VIRTIOCORE;
300
301	#define MAX_NAME 64
302
303	/**
304	* The core/common state of the VirtIO PCI devices, ring-3 edition.
305	*/
306	typedef struct VIRTIOCORER3
307	{
308	/** @name Callbacks filled by the device before calling virtioCoreR3Init.
309	* @{ */
310	/**
311	* Implementation-specific client callback to notify client of significant device status
312	* changes.
313	*
314	* @param pVirtio Pointer to the shared virtio state.
315	* @param pVirtioCC Pointer to the ring-3 virtio state.
316	* @param fDriverOk True if guest driver is okay (thus queues, etc... are
317	* valid)
318	*/
319	DECLCALLBACKMEMBER(void, pfnStatusChanged)(PVIRTIOCORE pVirtio, PVIRTIOCORECC pVirtioCC, uint32_t fDriverOk);
320
321	/**
322	* Implementation-specific client callback to access VirtIO Device-specific capabilities
323	* (other VirtIO capabilities and features are handled in VirtIO implementation)
324	*
325	* @param pDevIns The device instance.
326	* @param offCap Offset within device specific capabilities struct.
327	* @param pvBuf Buffer in which to save read data.
328	* @param cbToRead Number of bytes to read.
329	*/
330	DECLCALLBACKMEMBER(int, pfnDevCapRead)(PPDMDEVINS pDevIns, uint32_t offCap, void *pvBuf, uint32_t cbToRead);
331
332	/**
333	* Implementation-specific client ballback to access VirtIO Device-specific capabilities
334	* (other VirtIO capabilities and features are handled in VirtIO implementation)
335	*
336	* @param pDevIns The device instance.
337	* @param offCap Offset within device specific capabilities struct.
338	* @param pvBuf Buffer with the bytes to write.
339	* @param cbToWrite Number of bytes to write.
340	*/
341	DECLCALLBACKMEMBER(int, pfnDevCapWrite)(PPDMDEVINS pDevIns, uint32_t offCap, const void *pvBuf, uint32_t cbWrite);
342
343
344	/**
345	* When guest-to-host queue notifications are enabled, the guest driver notifies the host
346	* that the avail queue has buffers, and this callback informs the client.
347	*
348	* @param pVirtio Pointer to the shared virtio state.
349	* @param pVirtioCC Pointer to the ring-3 virtio state.
350	* @param uVirtqNbr Index of the notified queue
351	*/
352	DECLCALLBACKMEMBER(void, pfnVirtqNotified)(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
353
354	/** @} */
355
356	R3PTRTYPE(PVIRTIO_PCI_CFG_CAP_T) pPciCfgCap; /*< Pointer to struct in PCI config area. /
357	R3PTRTYPE(PVIRTIO_PCI_NOTIFY_CAP_T) pNotifyCap; /*< Pointer to struct in PCI config area. /
358	R3PTRTYPE(PVIRTIO_PCI_CAP_T) pCommonCfgCap; /*< Pointer to struct in PCI config area. /
359	R3PTRTYPE(PVIRTIO_PCI_CAP_T) pIsrCap; /*< Pointer to struct in PCI config area. /
360	R3PTRTYPE(PVIRTIO_PCI_CAP_T) pDeviceCap; /*< Pointer to struct in PCI config area. /
361
362	uint32_t cbDevSpecificCfg; /*< Size of client's dev-specific config data /
363	R3PTRTYPE(uint8_t ) pbDevSpecificCfg; /< Pointer to client's struct /
364	R3PTRTYPE(uint8_t ) pbPrevDevSpecificCfg; /< Previous read dev-specific cfg of client /
365	bool fGenUpdatePending; /*< If set, update cfg gen after driver reads /
366	char pcszMmioName[MAX_NAME]; /*< MMIO mapping name /
367	} VIRTIOCORER3;
368
369	/**
370	* The core/common state of the VirtIO PCI devices, ring-0 edition.
371	*/
372	typedef struct VIRTIOCORER0
373	{
374	/**
375	* When guest-to-host queue notifications are enabled, the guest driver notifies the host
376	* that the avail queue has buffers, and this callback informs the client.
377	*
378	* @param pVirtio Pointer to the shared virtio state.
379	* @param pVirtioCC Pointer to the ring-3 virtio state.
380	* @param uVirtqNbr Index of the notified queue
381	*/
382	DECLCALLBACKMEMBER(void, pfnVirtqNotified)(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
383
384	} VIRTIOCORER0;
385
386	/**
387	* The core/common state of the VirtIO PCI devices, raw-mode edition.
388	*/
389	typedef struct VIRTIOCORERC
390	{
391	uint64_t uUnusedAtTheMoment;
392	} VIRTIOCORERC;
393
394
395	/** @typedef VIRTIOCORECC
396	* The instance data for the current context. */
397	typedef CTX_SUFF(VIRTIOCORE) VIRTIOCORECC;
398
399
400	/** @name API for VirtIO parent device
401	* @{ */
402
403	/**
404	* Initiate orderly reset procedure. This is an exposed API for clients that might need it.
405	* Invoked by client to reset the device and driver (see VirtIO 1.0 section 2.1.1/2.1.2)
406	*
407	* @param pVirtio Pointer to the virtio state.
408	*/
409	void virtioCoreResetAll(PVIRTIOCORE pVirtio);
410
411	/**
412	* 'Attaches' the inheriting device-specific code's queue state to VirtIO core
413	* queue management, informing the core of the name of the queue associated spec-defined
414	* device specific queue number (which also happens to be the index into VirtIO's array
415	* of queue structs]. uVirtqNbr is used as the 'handle' for virt queues in this API.
416	* They are unambiguous (the VirtIO specification defines how virtq numbers are assigned
417	* for each device type), and it helps prevent muddying of the core state by devices
418	* and vice versa by eliminating direct access to otherwise private structs.
419	*
420	* @param pVirtio Pointer to the shared virtio state.
421	* @param uVirtqNbr Virtq number
422	* @param pcszName Name to give queue
423	*
424	* @returns VBox status code.
425	*/
426	int virtioCoreR3VirtqAttach(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, const char *pcszName);
427
428	/**
429	* Enables or disables a virtq
430	*
431	* @param pVirtio Pointer to the shared virtio state.
432	* @param uVirtqNbr Virtq number
433	* @param fEnable Flags whether to enable or disable the virtq
434	*
435	*/
436	void virtioCoreVirtqEnable(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, bool fEnable);
437
438	/**
439	* Enable or disable notification for the specified queue.
440	*
441	* I.e. The notification enable mode informs guest driver whether or not to to notify the
442	* host device (via MMIO access to the queue notification area described in VirtIO 1.0, Section 4.1.4.4
443	* "Notification structure layout" whenever the guest driver adds a new entry to the avail ring of the queue).
444	*
445	* Note: In the VirtIO world, the device sets flags in the used ring to communicate to the driver how to
446	* handle notifications for the avail ring and the drivers sets flags in the avail ring to communicate
447	* to the device how to handle sending interrupts for the used ring.
448	*
449	* @param pVirtio Pointer to the shared virtio state.
450	* @param uVirtqNbr Virtq number
451	* @param fEnable Selects notification mode (enabled or disabled)
452	*/
453	void virtioCoreVirtqEnableNotify(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, bool fEnable);
454
455	/**
456	* Notifies guest (via ISR or MSI-X) of device configuration change
457	*
458	* @param pVirtio Pointer to the shared virtio state.
459	*/
460	void virtioCoreNotifyConfigChanged(PVIRTIOCORE pVirtio);
461
462	/**
463	* Displays the VirtIO spec-related features offered by the core component,
464	* as well as which features have been negotiated and accepted or declined by the guest driver,
465	* providing a summary view of the configuration the device is operating with.
466	*
467	* @param pVirtio Pointer to the shared virtio state.
468	* @param pHlp Pointer to the debug info hlp struct
469	*/
470	void virtioCorePrintFeatures(VIRTIOCORE *pVirtio, PCDBGFINFOHLP pHlp);
471
472	/*
473	* Debuging assist feature displays the state of the VirtIO core code, which includes
474	* an overview of the state of all of the queues.
475	*
476	* This can be invoked when running the VirtualBox debugger, or from the command line
477	* using the command: "VboxManage debugvm <VM name or id> info <device name> [args]"
478	*
479	* Example: VBoxManage debugvm myVnetVm info "virtio-net" help
480	*
481	* This is implemented currently to be invoked by the inheriting device-specific code
482	* (see DevVirtioNet for an example, which receives the debugvm callback directly).
483	* DevVirtioNet lists the available sub-options if no arguments are provided. In that
484	* example this virtq info related function is invoked hierarchically when virtio-net
485	* displays its device-specific queue info.
486	*
487	* @param pDevIns The device instance.
488	* @param pHlp Pointer to the debug info hlp struct
489	* @param pszArgs Arguments to function
490	*/
491	void virtioCoreR3VirtqInfo(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs, int uVirtqNbr);
492
493	/**
494	* Returns the number of avail bufs in the virtq.
495	*
496	* @param pDevIns The device instance.
497	* @param pVirtio Pointer to the shared virtio state.
498	* @param uVirtqNbr Virtqueue to return the count of buffers available for.
499	*/
500	uint16_t virtioCoreVirtqAvailBufCount(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
501
502	/**
503	* This function is identical to virtioCoreR3VirtqAvailBufGet(), except it doesn't 'consume'
504	* the buffer from the avail ring of the virtq. The peek operation becomes identical to a get
505	* operation if virtioCoreR3VirtqAvailRingNext() is called to consume the buffer from the avail ring,
506	* at which point virtioCoreR3VirtqUsedBufPut() must be called to complete the roundtrip
507	* transaction by putting the descriptor on the used ring.
508	*
509	*
510	* @param pDevIns The device instance.
511	* @param pVirtio Pointer to the shared virtio state.
512	* @param uVirtqNbr Virtq number
513	* @param ppVirtqBuf Address to store pointer to descriptor chain that contains the
514	* pre-processed transaction information pulled from the virtq.
515	*
516	* @returns VBox status code:
517	* @retval VINF_SUCCESS Success
518	* @retval VERR_INVALID_STATE VirtIO not in ready state (asserted).
519	* @retval VERR_NOT_AVAILABLE If the queue is empty.
520	*/
521	int virtioCoreR3VirtqAvailBufPeek(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
522	PPVIRTQBUF ppVirtqBuf);
523
524	/**
525	* This function fetches the next buffer (descriptor chain) from the VirtIO "avail" ring of
526	* indicated queue, and converts the buf's s/g vectors into OUT (e.g. guest-to-host)
527	* components and and IN (host-to-guest) components.
528	*
529	* The caller is responsible for GCPhys to host virtual memory conversions. If the
530	* virtq buffer being peeked at is "consumed", virtioCoreR3VirtqAvailRingNext() must
531	* be called and in that case virtioCoreR3VirtqUsedBufPut() must be called to
532	* complete the roundtrip virtq transaction.
533	*
534	* @param pDevIns The device instance.
535	* @param pVirtio Pointer to the shared virtio state.
536	* @param uVirtqNbr Virtq number
537	* @param ppVirtqBuf Address to store pointer to descriptor chain that contains the
538	* pre-processed transaction information pulled from the virtq.
539	* Returned reference must be released by calling
540	* virtioCoreR3VirtqBufRelease().
541	* @param fRemove flags whether to remove desc chain from queue (false = peek)
542	*
543	* @returns VBox status code:
544	* @retval VINF_SUCCESS Success
545	* @retval VERR_INVALID_STATE VirtIO not in ready state (asserted).
546	* @retval VERR_NOT_AVAILABLE If the queue is empty.
547	*/
548	int virtioCoreR3VirtqAvailBufGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
549	PPVIRTQBUF ppVirtqBuf, bool fRemove);
550
551	/**
552	* Fetches a specific descriptor chain using avail ring of indicated queue and converts the descriptor
553	* chain into its OUT (to device) and IN to guest components.
554	*
555	* The caller is responsible for GCPhys to host virtual memory conversions and must
556	* return the virtq buffer using virtioCoreR3VirtqUsedBufPut() to complete the roundtrip
557	* virtq transaction.
558	* *
559	* @param pDevIns The device instance.
560	* @param pVirtio Pointer to the shared virtio state.
561	* @param uVirtqNbr Virtq number
562	* @param ppVirtqBuf Address to store pointer to descriptor chain that contains the
563	* pre-processed transaction information pulled from the virtq.
564	* Returned reference must be released by calling
565	* virtioCoreR3VirtqBufRelease().
566	* @param fRemove flags whether to remove desc chain from queue (false = peek)
567	*
568	* @returns VBox status code:
569	* @retval VINF_SUCCESS Success
570	* @retval VERR_INVALID_STATE VirtIO not in ready state (asserted).
571	* @retval VERR_NOT_AVAILABLE If the queue is empty.
572	*/
573	int virtioCoreR3VirtqAvailBufGet(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr,
574	uint16_t uHeadIdx, PPVIRTQBUF ppVirtqBuf);
575
576	/**
577	* Returns data to the guest to complete a transaction initiated by virtioCoreR3VirtqAvailBufGet(),
578	* or virtioCoreR3VirtqAvailBufPeek()/virtioCoreR3VirtqBufSync() call pairs to complete each
579	* intervening a roundtrip transaction, wherein I/O transactions are always initiated by
580	* the guest and completed by the host. In other words, for the host to send any data to the
581	* guest, the guest must provide buffers, for the host to fill, via the avail ring of the
582	* virtq.
583	*
584	* At some some point virtioCoreR3VirtqUsedRingSync() must be called to return data to the guest,
585	* completing all pending virtioCoreR3VirtqAvailBufPut() transactions that have accumulated since
586	* the last call to virtioCoreR3VirtqUsedRingSync()
587
588	* @note This does a write-ahead to the used ring of the guest's queue. The data
589	* written won't be seen by the guest until the next call to virtioCoreVirtqSyncUsedRing()
590	*
591	*
592	* @param pDevIns The device instance (for reading).
593	* @param pVirtio Pointer to the shared virtio state.
594	* @param uVirtqNbr Virtq number
595	*
596	* @param pSgVirtReturn Points to scatter-gather buffer of virtual memory
597	* segments the caller is returning to the guest.
598	*
599	* @param pVirtqBuf This contains the context of the scatter-gather
600	* buffer originally pulled from the queue.
601	*
602	* @param fFence If true, put up copy fence (memory barrier) after
603	* copying to guest phys. mem.
604	*
605	* @returns VBox status code.
606	* @retval VINF_SUCCESS Success
607	* @retval VERR_INVALID_STATE VirtIO not in ready state
608	* @retval VERR_NOT_AVAILABLE Virtq is empty
609	*
610	* @note This function will not release any reference to pVirtqBuf. The
611	* caller must take care of that.
612	*/
613	int virtioCoreR3VirtqUsedBufPut(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr, PRTSGBUF pSgVirtReturn,
614	PVIRTQBUF pVirtqBuf, bool fFence);
615	/**
616	* Advance index of avail ring to next entry in specified virtq (see virtioCoreR3VirtqAvailBufPeek())
617	*
618	* @param pVirtio Pointer to the virtio state.
619	* @param uVirtqNbr Index of queue
620	*/
621	int virtioCoreR3VirtqAvailBufNext(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
622
623	/**
624	* Add some bytes to a virtq (s/g) buffer, converting them from virtual memory to GCPhys
625	*
626	* To be performant it is left to the caller to validate the size of the buffer with regard
627	* to data being pulled from it to avoid underruns.
628	*
629	* @param pVirtio Pointer to the shared virtio state.
630	* @param pVirtqBuf output: virtq buffer
631	* @param pv input: virtual memory buffer to receive bytes
632	* @param cb number of bytes to add to the s/g buffer.
633	*/
634	void virtioCoreR3VirqBufFill(PVIRTIOCORE pVirtio, PVIRTQBUF pVirtqBuf, void *pv, size_t cb);
635
636	/**
637	* Extract some bytes out of a virtq (s/g) buffer, converting them from GCPhys to virtual memory
638	*
639	* To be performant it is left to the caller to validate the size of the buffer with regard
640	* to data being pulled from it to avoid underruns.
641	*
642	* @param pVirtio Pointer to the shared virtio state.
643	* @param pVirtqBuf input: virtq buffer
644	* @param pv output: virtual memory buffer to receive bytes
645	* @param cb number of bytes to Drain from buffer
646	*/
647	void virtioCoreR3VirtqBufDrain(PVIRTIOCORE pVirtio, PVIRTQBUF pVirtqBuf, void *pv, size_t cb);
648
649	/**
650	* Updates indicated virtq's "used ring" descriptor index to match "shadow" index that tracks
651	* pending buffers added to the used ring, thus exposing all the data added by virtioCoreR3VirtqUsedBufPut()
652	* to the "used ring" since the last virtioCoreVirtqSyncUsedRing().
653	*
654	* This must be invoked after one or more virtioCoreR3VirtqUsedBufPut() calls to inform guest driver
655	* there is data in the queue. If enabled by guest, IRQ or MSI-X signalling will notify guest
656	* proactively, otherwise guest detect updates by polling. (see VirtIO 1.0, Section 2.4 "Virtqueues").
657	*
658	* @param pDevIns The device instance.
659	* @param pVirtio Pointer to the shared virtio state.
660	* @param uVirtqNbr Virtq number
661	*
662	* @returns VBox status code.
663	* @retval VINF_SUCCESS Success
664	* @retval VERR_INVALID_STATE VirtIO not in ready state
665	*/
666	int virtioCoreVirtqSyncUsedRing(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, uint16_t uVirtqNbr);
667
668	/**
669	* Retains a reference to the given descriptor chain.
670	*
671	* @param pVirtqBuf The descriptor chain to reference.
672	*
673	* @returns New reference count.
674	* @retval UINT32_MAX on invalid parameter.
675	*/
676	uint32_t virtioCoreR3VirtqBufRetain(PVIRTQBUF pVirtqBuf);
677
678	/**
679	* Releases a reference to the given descriptor chain.
680	*
681	* @param pVirtio Pointer to the shared virtio state.
682	* @param pVirtqBuf The descriptor chain to reference. NULL is quietly
683	* ignored (returns 0).
684	* @returns New reference count.
685	* @retval 0 if freed or invalid parameter.
686	*/
687	uint32_t virtioCoreR3VirtqBufRelease(PVIRTIOCORE pVirtio, PVIRTQBUF pVirtqBuf);
688
689	/**
690	* Return queue enable state
691	*
692	* @param pVirtio Pointer to the virtio state.
693	* @param uVirtqNbr Virtq number.
694	*
695	* @returns true or false indicating queue is enabled or not.
696	*/
697	DECLINLINE(bool) virtioCoreIsVirtqEnabled(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
698	{
699	Assert(uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqueues));
700	return pVirtio->aVirtqueues[uVirtqNbr].uEnable != 0;
701	}
702
703	/**
704	* Get name of queue, via uVirtqNbr, assigned during virtioCoreR3VirtqAttach()
705	*
706	* @param pVirtio Pointer to the virtio state.
707	* @param uVirtqNbr Virtq number.
708	*
709	* @returns Pointer to read-only queue name.
710	*/
711	DECLINLINE(const char *) virtioCoreVirtqGetName(PVIRTIOCORE pVirtio, uint16_t uVirtqNbr)
712	{
713	Assert((size_t)uVirtqNbr < RT_ELEMENTS(pVirtio->aVirtqueues));
714	return pVirtio->aVirtqueues[uVirtqNbr].szName;
715	}
716
717	/**
718	* Get features VirtIO is running with now. This is used by device-specific code to identify
719	* the the device's operational configuration after features have been negotiated with guest
720	* VirtIO driver. In the feature negotiation scheme, the host offers features it can support
721	* and guest accepts among those offered which features it can or will enable. The accepted
722	* features define the operational mode of VirtIO device. A mask reflecting the generic
723	* Virtio (core) features and device-specific features are offered in the core-initialization
724	* call by the device-specific code.
725	*
726	* @param pVirtio Pointer to the virtio state.
727	*
728	* @returns Features the guest driver has accepted, finalizing the operational features
729	*/
730	DECLINLINE(uint64_t) virtioCoreGetNegotiatedFeatures(PVIRTIOCORE pVirtio)
731	{
732	return pVirtio->uDriverFeatures;
733	}
734
735	/**
736	* Get the the name of the VM state change associated with the enumeration variable
737	*
738	* @param enmState VM state (enumeration value)
739	*
740	* @returns associated text.
741	*/
742	const char *virtioCoreGetStateChangeText(VIRTIOVMSTATECHANGED enmState);
743
744	/**
745	* Log memory-mapped I/O input or output value.
746	*
747	* This is to be invoked by macros that assume they are invoked in functions with
748	* the relevant arguments. (See Virtio_1_0.cpp).
749	*
750	* It is exposed via the API so inheriting device-specific clients can provide similar
751	* logging capabilities for a consistent look-and-feel.
752	*
753	* @param pszFunc To avoid displaying this function's name via __FUNCTION__ or LogFunc()
754	* @param pszMember Name of struct member
755	* @param pv pointer to value
756	* @param cb size of value
757	* @param uOffset offset into member where value starts
758	* @param fWrite True if write I/O
759	* @param fHasIndex True if the member is indexed
760	* @param idx The index if fHasIndex
761	*/
762	void virtioCoreLogMappedIoValue(const char pszFunc, const char pszMember, uint32_t uMemberSize,
763	const void *pv, uint32_t cb, uint32_t uOffset,
764	int fWrite, int fHasIndex, uint32_t idx);
765
766	/**
767	* Debug assist for any consumer device code that inherits VIRTIOCORE
768	*
769	* Does a formatted hex dump using Log(()), recommend using VIRTIO_HEX_DUMP() macro to
770	* control enabling of logging efficiently.
771	*
772	* @param pv pointer to buffer to dump contents of
773	* @param cb count of characters to dump from buffer
774	* @param uBase base address of per-row address prefixing of hex output
775	* @param pszTitle Optional title. If present displays title that lists
776	* provided text with value of cb to indicate size next to it.
777	*/
778	void virtioCoreHexDump(uint8_t pv, uint32_t cb, uint32_t uBase, const char pszTitle);
779
780	/**
781	* Debug assist for any consumer device code that inherits VIRTIOCORE
782	&
783	* Do a hex dump of memory in guest physical context
784	*
785	* @param GCPhys pointer to buffer to dump contents of
786	* @param cb count of characters to dump from buffer
787	* @param uBase base address of per-row address prefixing of hex output
788	* @param pszTitle Optional title. If present displays title that lists
789	* provided text with value of cb to indicate size next to it.
790	*/
791	void virtioCoreGCPhysHexDump(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint16_t cb, uint32_t uBase, const char *pszTitle);
792
793	/**
794	* The following API is functions identically to the similarly-named calls pertaining to the RTSGBUF
795	*/
796
797	/**
798	* Calculate the length of a GCPhys s/g buffer by tallying the size of each segment.
799	*
800	* @param pGcSgBuf Guest Context (GCPhys) S/G buffer to calculate length of
801	*/
802	DECLINLINE(size_t) virtioCoreGCPhysChainCalcBufSize(PCVIRTIOSGBUF pGcSgBuf)
803	{
804	size_t cb = 0;
805	unsigned i = pGcSgBuf->cSegs;
806	while (i-- > 0)
807	cb += pGcSgBuf->paSegs[i].cbSeg;
808	return cb;
809	}
810
811	void virtioCoreGCPhysChainInit(PVIRTIOSGBUF pGcSgBuf, PVIRTIOSGSEG paSegs, size_t cSegs);
812	void virtioCoreGCPhysChainReset(PVIRTIOSGBUF pGcSgBuf);
813	RTGCPHYS virtioCoreGCPhysChainGetNextSeg(PVIRTIOSGBUF pGcSgBuf, size_t *pcbSeg);
814	RTGCPHYS virtioCoreGCPhysChainAdvance(PVIRTIOSGBUF pGcSgBuf, size_t cbAdvance);
815	size_t virtioCoreGCPhysChainCalcBufSize(PCVIRTIOSGBUF pGcSgBuf);
816
817
818	/** Misc VM and PDM boilerplate */
819	int virtioCoreR3SaveExec(PVIRTIOCORE pVirtio, PCPDMDEVHLPR3 pHlp, PSSMHANDLE pSSM);
820	int virtioCoreR3LoadExec(PVIRTIOCORE pVirtio, PCPDMDEVHLPR3 pHlp, PSSMHANDLE pSSM);
821	void virtioCoreR3VmStateChanged(PVIRTIOCORE pVirtio, VIRTIOVMSTATECHANGED enmState);
822	void virtioCoreR3Term(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, PVIRTIOCORECC pVirtioCC);
823	int virtioCoreR3Init(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio, PVIRTIOCORECC pVirtioCC, PVIRTIOPCIPARAMS pPciParams,
824	const char pcszInstance, uint64_t fDevSpecificFeatures, void pvDevSpecificCfg, uint16_t cbDevSpecificCfg);
825	int virtioCoreRZInit(PPDMDEVINS pDevIns, PVIRTIOCORE pVirtio);
826	const char *virtioCoreGetStateChangeText(VIRTIOVMSTATECHANGED enmState);
827
828	/*
829	* The following macros assist with handling/logging MMIO accesses to VirtIO dev-specific config area,
830	* in a way that enhances code readability and debug logging consistency.
831	*
832	* cb, pv and fWrite are implicit parameters and must be defined by the invoker.
833	*/
834
835	#ifdef LOG_ENABLED
836
837	# define VIRTIO_DEV_CONFIG_LOG_ACCESS(member, tCfgStruct, uOffsetOfAccess) \
838	if (LogIs7Enabled()) { \
839	uint32_t uMbrOffset = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
840	uint32_t uMbrSize = RT_SIZEOFMEMB(tCfgStruct, member); \
841	virtioCoreLogMappedIoValue(__FUNCTION__, #member, uMbrSize, pv, cb, uMbrOffset, fWrite, false, 0); \
842	}
843
844	# define VIRTIO_DEV_CONFIG_LOG_INDEXED_ACCESS(member, tCfgStruct, uOffsetOfAccess, uIdx) \
845	if (LogIs7Enabled()) { \
846	uint32_t uMbrOffset = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
847	uint32_t uMbrSize = RT_SIZEOFMEMB(tCfgStruct, member); \
848	virtioCoreLogMappedIoValue(__FUNCTION__, #member, uMbrSize, pv, cb, uMbrOffset, fWrite, true, uIdx); \
849	}
850	#else
851	# define VIRTIO_DEV_CONFIG_LOG_ACCESS(member, tCfgStruct, uMbrOffset) do { } while (0)
852	# define VIRTIO_DEV_CONFIG_LOG_INDEXED_ACCESS(member, tCfgStruct, uMbrOffset, uIdx) do { } while (0)
853	#endif
854
855	DECLINLINE(bool) virtioCoreMatchMember(uint32_t uOffset, uint32_t cb, uint32_t uMemberOff,
856	size_t uMemberSize, bool fSubFieldMatch)
857	{
858	/* Test for 8-byte field always (accessed as two 32-bit components) */
859	if (uMemberSize == 8)
860	return (cb == sizeof(uint32_t)) && (uOffset == uMemberOff \|\| uOffset == (uMemberOff + sizeof(uint32_t)));
861
862	if (fSubFieldMatch)
863	return (uOffset >= uMemberOff) && (cb <= uMemberSize - (uOffset - uMemberOff));
864
865	/* Test for exact match */
866	return (uOffset == uMemberOff) && (cb == uMemberSize);
867	}
868
869	/**
870	* Yields boolean true if uOffsetOfAccess falls within bytes of specified member of config struct
871	*/
872	#define VIRTIO_DEV_CONFIG_SUBMATCH_MEMBER(member, tCfgStruct, uOffsetOfAccess) \
873	virtioCoreMatchMember(uOffsetOfAccess, cb, \
874	RT_UOFFSETOF(tCfgStruct, member), \
875	RT_SIZEOFMEMB(tCfgStruct, member), true /* fSubfieldMatch */)
876
877	#define VIRTIO_DEV_CONFIG_MATCH_MEMBER(member, tCfgStruct, uOffsetOfAccess) \
878	virtioCoreMatchMember(uOffsetOfAccess, cb, \
879	RT_UOFFSETOF(tCfgStruct, member), \
880	RT_SIZEOFMEMB(tCfgStruct, member), false /* fSubfieldMatch */)
881
882	/**
883	* Copy reads or copy writes specified member field of config struct (based on fWrite),
884	* the memory described by cb and pv.
885	*
886	* cb, pv and fWrite are implicit parameters and must be defined by the invoker.
887	*/
888	#define VIRTIO_DEV_CONFIG_ACCESS(member, tCfgStruct, uOffsetOfAccess, pCfgStruct) \
889	do \
890	{ \
891	uint32_t uOffsetInMember = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
892	if (fWrite) \
893	memcpy(((char *)&(pCfgStruct)->member) + uOffsetInMember, pv, cb); \
894	else \
895	memcpy(pv, ((const char *)&(pCfgStruct)->member) + uOffsetInMember, cb); \
896	VIRTIO_DEV_CONFIG_LOG_ACCESS(member, tCfgStruct, uOffsetOfAccess); \
897	} while(0)
898
899	/**
900	* Copies bytes into memory described by cb, pv from the specified member field of the config struct.
901	* The operation is a nop and logs error if implied parameter fWrite is true.
902	*
903	* cb, pv and fWrite are implicit parameters and must be defined by the invoker.
904	*/
905	#define VIRTIO_DEV_CONFIG_ACCESS_READONLY(member, tCfgStruct, uOffsetOfAccess, pCfgStruct) \
906	do \
907	{ \
908	uint32_t uOffsetInMember = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
909	if (fWrite) \
910	LogFunc(("Guest attempted to write readonly virtio config struct (member %s)\n", #member)); \
911	else \
912	{ \
913	memcpy(pv, ((const char *)&(pCfgStruct)->member) + uOffsetInMember, cb); \
914	VIRTIO_DEV_CONFIG_LOG_ACCESS(member, tCfgStruct, uOffsetOfAccess); \
915	} \
916	} while(0)
917
918	/**
919	* Copies into or out of specified member field of config struct (based on fWrite),
920	* the memory described by cb and pv.
921	*
922	* cb, pv and fWrite are implicit parameters and must be defined by the invoker.
923	*/
924	#define VIRTIO_DEV_CONFIG_ACCESS_INDEXED(member, uIdx, tCfgStruct, uOffsetOfAccess, pCfgStruct) \
925	do \
926	{ \
927	uint32_t uOffsetInMember = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
928	if (fWrite) \
929	memcpy(((char *)&(pCfgStruct[uIdx].member)) + uOffsetInMember, pv, cb); \
930	else \
931	memcpy(pv, ((const char *)&(pCfgStruct[uIdx].member)) + uOffsetInMember, cb); \
932	VIRTIO_DEV_CONFIG_LOG_INDEXED_ACCESS(member, tCfgStruct, uOffsetOfAccess, uIdx); \
933	} while(0)
934
935	/**
936	* Copies bytes into memory described by cb, pv from the specified member field of the config struct.
937	* The operation is a nop and logs error if implied parameter fWrite is true.
938	*
939	* cb, pv and fWrite are implicit parameters and must be defined by the invoker.
940	*/
941	#define VIRTIO_DEV_CONFIG_ACCESS_INDEXED_READONLY(member, uidx, tCfgStruct, uOffsetOfAccess, pCfgStruct) \
942	do \
943	{ \
944	uint32_t uOffsetInMember = uOffsetOfAccess - RT_UOFFSETOF(tCfgStruct, member); \
945	if (fWrite) \
946	LogFunc(("Guest attempted to write readonly virtio config struct (member %s)\n", #member)); \
947	else \
948	{ \
949	memcpy(pv, ((const char *)&(pCfgStruct[uIdx].member)) + uOffsetInMember, cb); \
950	VIRTIO_DEV_CONFIG_LOG_INDEXED_ACCESS(member, tCfgStruct, uOffsetOfAccess, uIdx); \
951	} \
952	} while(0)
953
954	/** @} */
955
956	/** @name API for VirtIO parent device
957	* @{ */
958
959	#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@ 85109

Download in other formats: