blob: 2529c2d8b20443b91af61af4c2945020b6e87670 [file] [log] [blame]
Laurent Viviera5ebce32022-08-11 08:24:39 -04001# -*- Mode: Python -*-
2# vim: filetype=python
3#
4
5##
6# = Virtio devices
7##
8
9##
10# @VirtioInfo:
11#
12# Basic information about a given VirtIODevice
13#
14# @path: The VirtIODevice's canonical QOM path
15#
16# @name: Name of the VirtIODevice
17#
Han Han58379af2022-11-01 09:46:47 +080018# Since: 7.2
Laurent Viviera5ebce32022-08-11 08:24:39 -040019##
20{ 'struct': 'VirtioInfo',
21 'data': { 'path': 'str',
22 'name': 'str' } }
23
24##
25# @x-query-virtio:
26#
27# Returns a list of all realized VirtIODevices
28#
29# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +020030#
Laurent Viviera5ebce32022-08-11 08:24:39 -040031# @unstable: This command is meant for debugging.
32#
33# Returns: List of gathered VirtIODevices
34#
Han Han58379af2022-11-01 09:46:47 +080035# Since: 7.2
Laurent Viviera5ebce32022-08-11 08:24:39 -040036#
John Snow14b48aa2024-07-16 22:13:08 -040037# .. qmp-example::
Laurent Viviera5ebce32022-08-11 08:24:39 -040038#
Markus Armbrusterd23055b2024-02-16 15:58:34 +010039# -> { "execute": "x-query-virtio" }
40# <- { "return": [
41# {
42# "name": "virtio-input",
43# "path": "/machine/peripheral-anon/device[4]/virtio-backend"
44# },
45# {
46# "name": "virtio-crypto",
47# "path": "/machine/peripheral/crypto0/virtio-backend"
48# },
49# {
50# "name": "virtio-scsi",
51# "path": "/machine/peripheral-anon/device[2]/virtio-backend"
52# },
53# {
54# "name": "virtio-net",
55# "path": "/machine/peripheral-anon/device[1]/virtio-backend"
56# },
57# {
58# "name": "virtio-serial",
59# "path": "/machine/peripheral-anon/device[0]/virtio-backend"
60# }
61# ]
62# }
Laurent Viviera5ebce32022-08-11 08:24:39 -040063##
Laurent Viviera5ebce32022-08-11 08:24:39 -040064{ 'command': 'x-query-virtio',
65 'returns': [ 'VirtioInfo' ],
66 'features': [ 'unstable' ] }
Laurent Vivier90c066c2022-08-11 08:24:40 -040067
68##
69# @VhostStatus:
70#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020071# Information about a vhost device. This information will only be
Laurent Vivier90c066c2022-08-11 08:24:40 -040072# displayed if the vhost device is active.
73#
74# @n-mem-sections: vhost_dev n_mem_sections
75#
76# @n-tmp-sections: vhost_dev n_tmp_sections
77#
78# @nvqs: vhost_dev nvqs (number of virtqueues being used)
79#
80# @vq-index: vhost_dev vq_index
81#
82# @features: vhost_dev features
83#
84# @acked-features: vhost_dev acked_features
85#
86# @backend-features: vhost_dev backend_features
87#
88# @protocol-features: vhost_dev protocol_features
89#
90# @max-queues: vhost_dev max_queues
91#
92# @backend-cap: vhost_dev backend_cap
93#
94# @log-enabled: vhost_dev log_enabled flag
95#
96# @log-size: vhost_dev log_size
97#
Han Han58379af2022-11-01 09:46:47 +080098# Since: 7.2
Laurent Vivier90c066c2022-08-11 08:24:40 -040099##
Laurent Vivier90c066c2022-08-11 08:24:40 -0400100{ 'struct': 'VhostStatus',
101 'data': { 'n-mem-sections': 'int',
102 'n-tmp-sections': 'int',
103 'nvqs': 'uint32',
104 'vq-index': 'int',
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400105 'features': 'VirtioDeviceFeatures',
106 'acked-features': 'VirtioDeviceFeatures',
107 'backend-features': 'VirtioDeviceFeatures',
108 'protocol-features': 'VhostDeviceProtocols',
Laurent Vivier90c066c2022-08-11 08:24:40 -0400109 'max-queues': 'uint64',
110 'backend-cap': 'uint64',
111 'log-enabled': 'bool',
112 'log-size': 'uint64' } }
113
114##
115# @VirtioStatus:
116#
117# Full status of the virtio device with most VirtIODevice members.
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200118# Also includes the full status of the corresponding vhost device if
119# the vhost device is active.
Laurent Vivier90c066c2022-08-11 08:24:40 -0400120#
121# @name: VirtIODevice name
122#
123# @device-id: VirtIODevice ID
124#
125# @vhost-started: VirtIODevice vhost_started flag
126#
127# @guest-features: VirtIODevice guest_features
128#
129# @host-features: VirtIODevice host_features
130#
131# @backend-features: VirtIODevice backend_features
132#
133# @device-endian: VirtIODevice device_endian
134#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200135# @num-vqs: VirtIODevice virtqueue count. This is the number of
136# active virtqueues being used by the VirtIODevice.
Laurent Vivier90c066c2022-08-11 08:24:40 -0400137#
138# @status: VirtIODevice configuration status (VirtioDeviceStatus)
139#
140# @isr: VirtIODevice ISR
141#
142# @queue-sel: VirtIODevice queue_sel
143#
144# @vm-running: VirtIODevice vm_running flag
145#
146# @broken: VirtIODevice broken flag
147#
148# @disabled: VirtIODevice disabled flag
149#
150# @use-started: VirtIODevice use_started flag
151#
152# @started: VirtIODevice started flag
153#
154# @start-on-kick: VirtIODevice start_on_kick flag
155#
156# @disable-legacy-check: VirtIODevice disabled_legacy_check flag
157#
158# @bus-name: VirtIODevice bus_name
159#
160# @use-guest-notifier-mask: VirtIODevice use_guest_notifier_mask flag
161#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200162# @vhost-dev: Corresponding vhost device info for a given
163# VirtIODevice. Present if the given VirtIODevice has an active
164# vhost device.
Laurent Vivier90c066c2022-08-11 08:24:40 -0400165#
Han Han58379af2022-11-01 09:46:47 +0800166# Since: 7.2
Laurent Vivier90c066c2022-08-11 08:24:40 -0400167##
Laurent Vivier90c066c2022-08-11 08:24:40 -0400168{ 'struct': 'VirtioStatus',
169 'data': { 'name': 'str',
170 'device-id': 'uint16',
171 'vhost-started': 'bool',
172 'device-endian': 'str',
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400173 'guest-features': 'VirtioDeviceFeatures',
174 'host-features': 'VirtioDeviceFeatures',
175 'backend-features': 'VirtioDeviceFeatures',
Laurent Vivier90c066c2022-08-11 08:24:40 -0400176 'num-vqs': 'int',
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400177 'status': 'VirtioDeviceStatus',
Laurent Vivier90c066c2022-08-11 08:24:40 -0400178 'isr': 'uint8',
179 'queue-sel': 'uint16',
180 'vm-running': 'bool',
181 'broken': 'bool',
182 'disabled': 'bool',
183 'use-started': 'bool',
184 'started': 'bool',
185 'start-on-kick': 'bool',
186 'disable-legacy-check': 'bool',
187 'bus-name': 'str',
188 'use-guest-notifier-mask': 'bool',
189 '*vhost-dev': 'VhostStatus' } }
190
191##
192# @x-query-virtio-status:
193#
194# Poll for a comprehensive status of a given virtio device
195#
196# @path: Canonical QOM path of the VirtIODevice
197#
198# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200199#
Laurent Vivier90c066c2022-08-11 08:24:40 -0400200# @unstable: This command is meant for debugging.
201#
202# Returns: VirtioStatus of the virtio device
203#
Han Han58379af2022-11-01 09:46:47 +0800204# Since: 7.2
Laurent Vivier90c066c2022-08-11 08:24:40 -0400205#
John Snow6f07c592024-07-16 22:13:10 -0400206# .. qmp-example::
207# :annotated:
Laurent Vivier90c066c2022-08-11 08:24:40 -0400208#
John Snow6f07c592024-07-16 22:13:10 -0400209# Poll for the status of virtio-crypto (no vhost-crypto active)
210# ::
Laurent Vivier90c066c2022-08-11 08:24:40 -0400211#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100212# -> { "execute": "x-query-virtio-status",
213# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" }
214# }
215# <- { "return": {
216# "device-endian": "little",
217# "bus-name": "",
218# "disable-legacy-check": false,
219# "name": "virtio-crypto",
220# "started": true,
221# "device-id": 20,
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400222# "backend-features": {
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100223# "transports": [],
224# "dev-features": []
225# },
226# "start-on-kick": false,
227# "isr": 1,
228# "broken": false,
229# "status": {
230# "statuses": [
231# "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
232# "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
233# "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
234# "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
235# ]
236# },
237# "num-vqs": 2,
238# "guest-features": {
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400239# "dev-features": [],
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400240# "transports": [
241# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
242# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
243# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
244# ]
245# },
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100246# "host-features": {
247# "unknown-dev-features": 1073741824,
248# "dev-features": [],
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400249# "transports": [
250# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
251# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400252# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
253# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
254# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
255# ]
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100256# },
257# "use-guest-notifier-mask": true,
258# "vm-running": true,
259# "queue-sel": 1,
260# "disabled": false,
261# "vhost-started": false,
262# "use-started": true
263# }
264# }
265#
John Snow6f07c592024-07-16 22:13:10 -0400266# .. qmp-example::
267# :annotated:
268#
269# Poll for the status of virtio-net (vhost-net is active)
270# ::
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100271#
272# -> { "execute": "x-query-virtio-status",
273# "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" }
274# }
275# <- { "return": {
276# "device-endian": "little",
277# "bus-name": "",
278# "disabled-legacy-check": false,
279# "name": "virtio-net",
280# "started": true,
281# "device-id": 1,
282# "vhost-dev": {
283# "n-tmp-sections": 4,
284# "n-mem-sections": 4,
285# "max-queues": 1,
286# "backend-cap": 2,
287# "log-size": 0,
288# "backend-features": {
289# "dev-features": [],
290# "transports": []
291# },
292# "nvqs": 2,
293# "protocol-features": {
294# "protocols": []
295# },
296# "vq-index": 0,
297# "log-enabled": false,
298# "acked-features": {
299# "dev-features": [
300# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
301# ],
302# "transports": [
303# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
304# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
305# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
306# ]
307# },
308# "features": {
309# "dev-features": [
310# "VHOST_F_LOG_ALL: Logging write descriptors supported",
311# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
312# ],
313# "transports": [
314# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
315# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
316# "VIRTIO_F_IOMMU_PLATFORM: Device can be used on IOMMU platform",
317# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
318# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
319# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
320# ]
321# }
322# },
323# "backend-features": {
324# "dev-features": [
325# "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
326# "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
327# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
328# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
329# "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
330# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
331# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
332# "VIRTIO_NET_F_CTRL_VQ: Control channel available",
333# "VIRTIO_NET_F_STATUS: Configuration status field available",
334# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
335# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
336# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
337# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
338# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
339# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
340# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
341# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
342# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
343# "VIRTIO_NET_F_MAC: Device has given MAC address",
344# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
345# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
346# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
347# ],
348# "transports": [
349# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
350# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
351# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
352# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
353# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
354# ]
355# },
356# "start-on-kick": false,
357# "isr": 1,
358# "broken": false,
359# "status": {
360# "statuses": [
361# "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
362# "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
363# "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
364# "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
365# ]
366# },
367# "num-vqs": 3,
368# "guest-features": {
369# "dev-features": [
370# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
371# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
372# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
373# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
374# "VIRTIO_NET_F_CTRL_VQ: Control channel available",
375# "VIRTIO_NET_F_STATUS: Configuration status field available",
376# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
377# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
378# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
379# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
380# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
381# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
382# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
383# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
384# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
385# "VIRTIO_NET_F_MAC: Device has given MAC address",
386# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
387# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
388# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
389# ],
390# "transports": [
391# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
392# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
393# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
394# ]
395# },
396# "host-features": {
397# "dev-features": [
398# "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
399# "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
400# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
401# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
402# "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
403# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
404# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
405# "VIRTIO_NET_F_CTRL_VQ: Control channel available",
406# "VIRTIO_NET_F_STATUS: Configuration status field available",
407# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
408# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
409# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
410# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
411# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
412# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
413# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
414# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
415# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
416# "VIRTIO_NET_F_MAC: Device has given MAC address",
417# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
418# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
419# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
420# ],
421# "transports": [
422# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
423# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
424# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
425# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
426# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
427# ]
428# },
429# "use-guest-notifier-mask": true,
430# "vm-running": true,
431# "queue-sel": 2,
432# "disabled": false,
433# "vhost-started": true,
434# "use-started": true
435# }
436# }
Laurent Vivier90c066c2022-08-11 08:24:40 -0400437##
Laurent Vivier90c066c2022-08-11 08:24:40 -0400438{ 'command': 'x-query-virtio-status',
439 'data': { 'path': 'str' },
440 'returns': 'VirtioStatus',
441 'features': [ 'unstable' ] }
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400442
443##
444# @VirtioDeviceStatus:
445#
446# A structure defined to list the configuration statuses of a virtio
447# device
448#
449# @statuses: List of decoded configuration statuses of the virtio
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200450# device
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400451#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200452# @unknown-statuses: Virtio device statuses bitmap that have not been
453# decoded
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400454#
Han Han58379af2022-11-01 09:46:47 +0800455# Since: 7.2
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400456##
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400457{ 'struct': 'VirtioDeviceStatus',
458 'data': { 'statuses': [ 'str' ],
459 '*unknown-statuses': 'uint8' } }
460
461##
462# @VhostDeviceProtocols:
463#
464# A structure defined to list the vhost user protocol features of a
465# Vhost User device
466#
467# @protocols: List of decoded vhost user protocol features of a vhost
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200468# user device
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400469#
470# @unknown-protocols: Vhost user device protocol features bitmap that
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200471# have not been decoded
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400472#
Han Han58379af2022-11-01 09:46:47 +0800473# Since: 7.2
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400474##
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400475{ 'struct': 'VhostDeviceProtocols',
476 'data': { 'protocols': [ 'str' ],
477 '*unknown-protocols': 'uint64' } }
478
479##
480# @VirtioDeviceFeatures:
481#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200482# The common fields that apply to most Virtio devices. Some devices
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400483# may not have their own device-specific features (e.g. virtio-rng).
484#
485# @transports: List of transport features of the virtio device
486#
487# @dev-features: List of device-specific features (if the device has
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200488# unique features)
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400489#
490# @unknown-dev-features: Virtio device features bitmap that have not
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200491# been decoded
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400492#
Han Han58379af2022-11-01 09:46:47 +0800493# Since: 7.2
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400494##
Laurent Vivierf3034ad2022-08-11 08:24:41 -0400495{ 'struct': 'VirtioDeviceFeatures',
496 'data': { 'transports': [ 'str' ],
497 '*dev-features': [ 'str' ],
498 '*unknown-dev-features': 'uint64' } }
Laurent Vivier07536dd2022-08-11 08:24:42 -0400499
500##
501# @VirtQueueStatus:
502#
503# Information of a VirtIODevice VirtQueue, including most members of
504# the VirtQueue data structure.
505#
506# @name: Name of the VirtIODevice that uses this VirtQueue
507#
508# @queue-index: VirtQueue queue_index
509#
510# @inuse: VirtQueue inuse
511#
512# @vring-num: VirtQueue vring.num
513#
514# @vring-num-default: VirtQueue vring.num_default
515#
516# @vring-align: VirtQueue vring.align
517#
518# @vring-desc: VirtQueue vring.desc (descriptor area)
519#
520# @vring-avail: VirtQueue vring.avail (driver area)
521#
522# @vring-used: VirtQueue vring.used (device area)
523#
524# @last-avail-idx: VirtQueue last_avail_idx or return of vhost_dev
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200525# vhost_get_vring_base (if vhost active)
Laurent Vivier07536dd2022-08-11 08:24:42 -0400526#
527# @shadow-avail-idx: VirtQueue shadow_avail_idx
528#
529# @used-idx: VirtQueue used_idx
530#
531# @signalled-used: VirtQueue signalled_used
532#
533# @signalled-used-valid: VirtQueue signalled_used_valid flag
534#
Han Han58379af2022-11-01 09:46:47 +0800535# Since: 7.2
Laurent Vivier07536dd2022-08-11 08:24:42 -0400536##
Laurent Vivier07536dd2022-08-11 08:24:42 -0400537{ 'struct': 'VirtQueueStatus',
538 'data': { 'name': 'str',
539 'queue-index': 'uint16',
540 'inuse': 'uint32',
541 'vring-num': 'uint32',
542 'vring-num-default': 'uint32',
543 'vring-align': 'uint32',
544 'vring-desc': 'uint64',
545 'vring-avail': 'uint64',
546 'vring-used': 'uint64',
547 '*last-avail-idx': 'uint16',
548 '*shadow-avail-idx': 'uint16',
549 'used-idx': 'uint16',
550 'signalled-used': 'uint16',
551 'signalled-used-valid': 'bool' } }
552
553##
554# @x-query-virtio-queue-status:
555#
556# Return the status of a given VirtIODevice's VirtQueue
557#
558# @path: VirtIODevice canonical QOM path
559#
560# @queue: VirtQueue index to examine
561#
562# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200563#
Laurent Vivier07536dd2022-08-11 08:24:42 -0400564# @unstable: This command is meant for debugging.
565#
566# Returns: VirtQueueStatus of the VirtQueue
567#
John Snowd461c272024-06-26 18:21:16 -0400568# .. note:: last_avail_idx will not be displayed in the case where the
569# selected VirtIODevice has a running vhost device and the
570# VirtIODevice VirtQueue index (queue) does not exist for the
Markus Armbruster01bed0f2024-07-29 08:52:20 +0200571# corresponding vhost device vhost_virtqueue. Also,
572# shadow_avail_idx will not be displayed in the case where the
573# selected VirtIODevice has a running vhost device.
Laurent Vivier07536dd2022-08-11 08:24:42 -0400574#
Han Han58379af2022-11-01 09:46:47 +0800575# Since: 7.2
Laurent Vivier07536dd2022-08-11 08:24:42 -0400576#
John Snow6f07c592024-07-16 22:13:10 -0400577# .. qmp-example::
578# :annotated:
Laurent Vivier07536dd2022-08-11 08:24:42 -0400579#
John Snow6f07c592024-07-16 22:13:10 -0400580# Get VirtQueueStatus for virtio-vsock (vhost-vsock running)
581# ::
Laurent Vivier07536dd2022-08-11 08:24:42 -0400582#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100583# -> { "execute": "x-query-virtio-queue-status",
584# "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
585# "queue": 1 }
586# }
587# <- { "return": {
588# "signalled-used": 0,
589# "inuse": 0,
590# "name": "vhost-vsock",
591# "vring-align": 4096,
592# "vring-desc": 5217370112,
593# "signalled-used-valid": false,
594# "vring-num-default": 128,
595# "vring-avail": 5217372160,
596# "queue-index": 1,
597# "last-avail-idx": 0,
598# "vring-used": 5217372480,
599# "used-idx": 0,
600# "vring-num": 128
601# }
602# }
Laurent Vivier07536dd2022-08-11 08:24:42 -0400603#
John Snow6f07c592024-07-16 22:13:10 -0400604# .. qmp-example::
605# :annotated:
606#
607# Get VirtQueueStatus for virtio-serial (no vhost)
608# ::
Laurent Vivier07536dd2022-08-11 08:24:42 -0400609#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100610# -> { "execute": "x-query-virtio-queue-status",
611# "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend",
612# "queue": 20 }
613# }
614# <- { "return": {
615# "signalled-used": 0,
616# "inuse": 0,
617# "name": "virtio-serial",
618# "vring-align": 4096,
619# "vring-desc": 5182074880,
620# "signalled-used-valid": false,
621# "vring-num-default": 128,
622# "vring-avail": 5182076928,
623# "queue-index": 20,
624# "last-avail-idx": 0,
625# "vring-used": 5182077248,
626# "used-idx": 0,
627# "shadow-avail-idx": 0,
628# "vring-num": 128
629# }
630# }
Laurent Vivier07536dd2022-08-11 08:24:42 -0400631##
Laurent Vivier07536dd2022-08-11 08:24:42 -0400632{ 'command': 'x-query-virtio-queue-status',
633 'data': { 'path': 'str', 'queue': 'uint16' },
634 'returns': 'VirtQueueStatus',
635 'features': [ 'unstable' ] }
636
637##
638# @VirtVhostQueueStatus:
639#
640# Information of a vhost device's vhost_virtqueue, including most
641# members of the vhost_dev vhost_virtqueue data structure.
642#
643# @name: Name of the VirtIODevice that uses this vhost_virtqueue
644#
645# @kick: vhost_virtqueue kick
646#
647# @call: vhost_virtqueue call
648#
649# @desc: vhost_virtqueue desc
650#
651# @avail: vhost_virtqueue avail
652#
653# @used: vhost_virtqueue used
654#
655# @num: vhost_virtqueue num
656#
Markus Armbrusterf972ed52024-03-22 15:09:00 +0100657# @desc-phys: vhost_virtqueue desc_phys (descriptor area physical
658# address)
Laurent Vivier07536dd2022-08-11 08:24:42 -0400659#
660# @desc-size: vhost_virtqueue desc_size
661#
Markus Armbrusterf972ed52024-03-22 15:09:00 +0100662# @avail-phys: vhost_virtqueue avail_phys (driver area physical
663# address)
Laurent Vivier07536dd2022-08-11 08:24:42 -0400664#
665# @avail-size: vhost_virtqueue avail_size
666#
Markus Armbrusterf972ed52024-03-22 15:09:00 +0100667# @used-phys: vhost_virtqueue used_phys (device area physical address)
Laurent Vivier07536dd2022-08-11 08:24:42 -0400668#
669# @used-size: vhost_virtqueue used_size
670#
Han Han58379af2022-11-01 09:46:47 +0800671# Since: 7.2
Laurent Vivier07536dd2022-08-11 08:24:42 -0400672##
Laurent Vivier07536dd2022-08-11 08:24:42 -0400673{ 'struct': 'VirtVhostQueueStatus',
674 'data': { 'name': 'str',
675 'kick': 'int',
676 'call': 'int',
677 'desc': 'uint64',
678 'avail': 'uint64',
679 'used': 'uint64',
680 'num': 'int',
681 'desc-phys': 'uint64',
682 'desc-size': 'uint32',
683 'avail-phys': 'uint64',
684 'avail-size': 'uint32',
685 'used-phys': 'uint64',
686 'used-size': 'uint32' } }
687
688##
689# @x-query-virtio-vhost-queue-status:
690#
691# Return information of a given vhost device's vhost_virtqueue
692#
693# @path: VirtIODevice canonical QOM path
694#
695# @queue: vhost_virtqueue index to examine
696#
697# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200698#
Laurent Vivier07536dd2022-08-11 08:24:42 -0400699# @unstable: This command is meant for debugging.
700#
701# Returns: VirtVhostQueueStatus of the vhost_virtqueue
702#
Han Han58379af2022-11-01 09:46:47 +0800703# Since: 7.2
Laurent Vivier07536dd2022-08-11 08:24:42 -0400704#
John Snowa9eab6e2024-07-16 22:13:09 -0400705# .. qmp-example::
706# :title: Get vhost_virtqueue status for vhost-crypto
Laurent Vivier07536dd2022-08-11 08:24:42 -0400707#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100708# -> { "execute": "x-query-virtio-vhost-queue-status",
709# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
710# "queue": 0 }
711# }
712# <- { "return": {
713# "avail-phys": 5216124928,
714# "name": "virtio-crypto",
715# "used-phys": 5216127040,
716# "avail-size": 2054,
717# "desc-size": 16384,
718# "used-size": 8198,
719# "desc": 140141447430144,
720# "num": 1024,
721# "call": 0,
722# "avail": 140141447446528,
723# "desc-phys": 5216108544,
724# "used": 140141447448640,
725# "kick": 0
726# }
727# }
Laurent Vivier07536dd2022-08-11 08:24:42 -0400728#
John Snowa9eab6e2024-07-16 22:13:09 -0400729# .. qmp-example::
730# :title: Get vhost_virtqueue status for vhost-vsock
Laurent Vivier07536dd2022-08-11 08:24:42 -0400731#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100732# -> { "execute": "x-query-virtio-vhost-queue-status",
733# "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
734# "queue": 0 }
735# }
736# <- { "return": {
737# "avail-phys": 5182261248,
738# "name": "vhost-vsock",
739# "used-phys": 5182261568,
740# "avail-size": 262,
741# "desc-size": 2048,
742# "used-size": 1030,
743# "desc": 140141413580800,
744# "num": 128,
745# "call": 0,
746# "avail": 140141413582848,
747# "desc-phys": 5182259200,
748# "used": 140141413583168,
749# "kick": 0
750# }
751# }
Laurent Vivier07536dd2022-08-11 08:24:42 -0400752##
Laurent Vivier07536dd2022-08-11 08:24:42 -0400753{ 'command': 'x-query-virtio-vhost-queue-status',
754 'data': { 'path': 'str', 'queue': 'uint16' },
755 'returns': 'VirtVhostQueueStatus',
756 'features': [ 'unstable' ] }
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400757
758##
759# @VirtioRingDesc:
760#
761# Information regarding the vring descriptor area
762#
763# @addr: Guest physical address of the descriptor area
764#
765# @len: Length of the descriptor area
766#
767# @flags: List of descriptor flags
768#
Han Han58379af2022-11-01 09:46:47 +0800769# Since: 7.2
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400770##
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400771{ 'struct': 'VirtioRingDesc',
772 'data': { 'addr': 'uint64',
773 'len': 'uint32',
774 'flags': [ 'str' ] } }
775
776##
777# @VirtioRingAvail:
778#
779# Information regarding the avail vring (a.k.a. driver area)
780#
781# @flags: VRingAvail flags
782#
783# @idx: VRingAvail index
784#
785# @ring: VRingAvail ring[] entry at provided index
786#
Han Han58379af2022-11-01 09:46:47 +0800787# Since: 7.2
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400788##
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400789{ 'struct': 'VirtioRingAvail',
790 'data': { 'flags': 'uint16',
791 'idx': 'uint16',
792 'ring': 'uint16' } }
793
794##
795# @VirtioRingUsed:
796#
797# Information regarding the used vring (a.k.a. device area)
798#
799# @flags: VRingUsed flags
800#
801# @idx: VRingUsed index
802#
Han Han58379af2022-11-01 09:46:47 +0800803# Since: 7.2
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400804##
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400805{ 'struct': 'VirtioRingUsed',
806 'data': { 'flags': 'uint16',
807 'idx': 'uint16' } }
808
809##
810# @VirtioQueueElement:
811#
812# Information regarding a VirtQueue's VirtQueueElement including
813# descriptor, driver, and device areas
814#
815# @name: Name of the VirtIODevice that uses this VirtQueue
816#
817# @index: Index of the element in the queue
818#
819# @descs: List of descriptors (VirtioRingDesc)
820#
821# @avail: VRingAvail info
822#
823# @used: VRingUsed info
824#
Han Han58379af2022-11-01 09:46:47 +0800825# Since: 7.2
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400826##
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400827{ 'struct': 'VirtioQueueElement',
828 'data': { 'name': 'str',
829 'index': 'uint32',
830 'descs': [ 'VirtioRingDesc' ],
831 'avail': 'VirtioRingAvail',
832 'used': 'VirtioRingUsed' } }
833
834##
835# @x-query-virtio-queue-element:
836#
837# Return the information about a VirtQueue's VirtQueueElement
838#
839# @path: VirtIODevice canonical QOM path
840#
841# @queue: VirtQueue index to examine
842#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200843# @index: Index of the element in the queue (default: head of the
844# queue)
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400845#
846# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200847#
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400848# @unstable: This command is meant for debugging.
849#
850# Returns: VirtioQueueElement information
851#
Han Han58379af2022-11-01 09:46:47 +0800852# Since: 7.2
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400853#
John Snowa9eab6e2024-07-16 22:13:09 -0400854# .. qmp-example::
855# :title: Introspect on virtio-net's VirtQueue 0 at index 5
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400856#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100857# -> { "execute": "x-query-virtio-queue-element",
858# "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend",
859# "queue": 0,
860# "index": 5 }
861# }
862# <- { "return": {
863# "index": 5,
864# "name": "virtio-net",
865# "descs": [
866# {
867# "flags": ["write"],
868# "len": 1536,
869# "addr": 5257305600
870# }
871# ],
872# "avail": {
873# "idx": 256,
874# "flags": 0,
875# "ring": 5
876# },
877# "used": {
878# "idx": 13,
879# "flags": 0
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400880# }
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400881# }
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100882# }
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400883#
John Snowa9eab6e2024-07-16 22:13:09 -0400884# .. qmp-example::
885# :title: Introspect on virtio-crypto's VirtQueue 1 at head
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400886#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100887# -> { "execute": "x-query-virtio-queue-element",
888# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
889# "queue": 1 }
890# }
891# <- { "return": {
892# "index": 0,
893# "name": "virtio-crypto",
894# "descs": [
895# {
896# "flags": [],
897# "len": 0,
898# "addr": 8080268923184214134
899# }
900# ],
901# "avail": {
902# "idx": 280,
903# "flags": 0,
904# "ring": 0
905# },
906# "used": {
907# "idx": 280,
908# "flags": 0
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400909# }
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400910# }
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100911# }
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400912#
John Snowa9eab6e2024-07-16 22:13:09 -0400913# .. qmp-example::
914# :title: Introspect on virtio-scsi's VirtQueue 2 at head
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400915#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100916# -> { "execute": "x-query-virtio-queue-element",
917# "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend",
918# "queue": 2 }
919# }
920# <- { "return": {
921# "index": 19,
922# "name": "virtio-scsi",
923# "descs": [
924# {
925# "flags": ["used", "indirect", "write"],
926# "len": 4099327944,
927# "addr": 12055409292258155293
928# }
929# ],
930# "avail": {
931# "idx": 1147,
932# "flags": 0,
933# "ring": 19
934# },
935# "used": {
936# "idx": 280,
937# "flags": 0
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400938# }
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400939# }
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100940# }
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400941##
Laurent Vivier1ee7bb52022-08-11 08:24:43 -0400942{ 'command': 'x-query-virtio-queue-element',
943 'data': { 'path': 'str', 'queue': 'uint16', '*index': 'uint16' },
944 'returns': 'VirtioQueueElement',
945 'features': [ 'unstable' ] }
Stefan Hajnoczicf03a152023-12-20 08:47:54 -0500946
947##
948# @IOThreadVirtQueueMapping:
949#
950# Describes the subset of virtqueues assigned to an IOThread.
951#
952# @iothread: the id of IOThread object
953#
Markus Armbruster209e64d2024-03-22 15:09:08 +0100954# @vqs: an optional array of virtqueue indices that will be handled by
955# this IOThread. When absent, virtqueues are assigned round-robin
956# across all IOThreadVirtQueueMappings provided. Either all
957# IOThreadVirtQueueMappings must have @vqs or none of them must
958# have it.
Stefan Hajnoczicf03a152023-12-20 08:47:54 -0500959#
960# Since: 9.0
961##
962
963{ 'struct': 'IOThreadVirtQueueMapping',
964 'data': { 'iothread': 'str', '*vqs': ['uint16'] } }
965
966##
967# @DummyVirtioForceArrays:
968#
Markus Armbruster209e64d2024-03-22 15:09:08 +0100969# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList
970# internally
Stefan Hajnoczicf03a152023-12-20 08:47:54 -0500971#
972# Since: 9.0
973##
974
975{ 'struct': 'DummyVirtioForceArrays',
976 'data': { 'unused-iothread-vq-mapping': ['IOThreadVirtQueueMapping'] } }
Eric Auger965bc082024-02-27 17:55:48 +0100977
978##
979# @GranuleMode:
980#
981# @4k: granule page size of 4KiB
982#
983# @8k: granule page size of 8KiB
984#
985# @16k: granule page size of 16KiB
986#
987# @64k: granule page size of 64KiB
988#
989# @host: granule matches the host page size
990#
991# Since: 9.0
992##
993{ 'enum': 'GranuleMode',
994 'data': [ '4k', '8k', '16k', '64k', 'host' ] }