| blob | 74fc27c7029a80a0bb1d2bf1e775aae458f0e712 |
1 # -*- Mode: Python -*-
2 # vim: filetype=python
3 #
5 ##
6 # = Virtio devices
7 ##
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 #
18 # Since: 7.2
19 ##
20 { 'struct': 'VirtioInfo',
21 'data': { 'path': 'str',
22 'name': 'str' } }
24 ##
25 # @x-query-virtio:
26 #
27 # Returns a list of all realized VirtIODevices
28 #
29 # Features:
30 #
31 # @unstable: This command is meant for debugging.
32 #
33 # Returns: List of gathered VirtIODevices
34 #
35 # Since: 7.2
36 #
37 # Example:
38 #
39 # -> { "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 # }
63 ##
64 { 'command': 'x-query-virtio',
65 'returns': [ 'VirtioInfo' ],
66 'features': [ 'unstable' ] }
68 ##
69 # @VhostStatus:
70 #
71 # Information about a vhost device. This information will only be
72 # 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 #
98 # Since: 7.2
99 ##
100 { 'struct': 'VhostStatus',
101 'data': { 'n-mem-sections': 'int',
102 'n-tmp-sections': 'int',
103 'nvqs': 'uint32',
104 'vq-index': 'int',
105 'features': 'VirtioDeviceFeatures',
106 'acked-features': 'VirtioDeviceFeatures',
107 'backend-features': 'VirtioDeviceFeatures',
108 'protocol-features': 'VhostDeviceProtocols',
109 'max-queues': 'uint64',
110 'backend-cap': 'uint64',
111 'log-enabled': 'bool',
112 'log-size': 'uint64' } }
114 ##
115 # @VirtioStatus:
116 #
117 # Full status of the virtio device with most VirtIODevice members.
118 # Also includes the full status of the corresponding vhost device if
119 # the vhost device is active.
120 #
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 #
135 # @num-vqs: VirtIODevice virtqueue count. This is the number of
136 # active virtqueues being used by the VirtIODevice.
137 #
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 #
162 # @vhost-dev: Corresponding vhost device info for a given
163 # VirtIODevice. Present if the given VirtIODevice has an active
164 # vhost device.
165 #
166 # Since: 7.2
167 ##
168 { 'struct': 'VirtioStatus',
169 'data': { 'name': 'str',
170 'device-id': 'uint16',
171 'vhost-started': 'bool',
172 'device-endian': 'str',
173 'guest-features': 'VirtioDeviceFeatures',
174 'host-features': 'VirtioDeviceFeatures',
175 'backend-features': 'VirtioDeviceFeatures',
176 'num-vqs': 'int',
177 'status': 'VirtioDeviceStatus',
178 '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' } }
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:
199 #
200 # @unstable: This command is meant for debugging.
201 #
202 # Returns: VirtioStatus of the virtio device
203 #
204 # Since: 7.2
205 #
206 # Examples:
207 #
208 # 1. Poll for the status of virtio-crypto (no vhost-crypto active)
209 #
210 # -> { "execute": "x-query-virtio-status",
211 # "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" }
212 # }
213 # <- { "return": {
214 # "device-endian": "little",
215 # "bus-name": "",
216 # "disable-legacy-check": false,
217 # "name": "virtio-crypto",
218 # "started": true,
219 # "device-id": 20,
220 # "backend-features": {
221 # "transports": [],
222 # "dev-features": []
223 # },
224 # "start-on-kick": false,
225 # "isr": 1,
226 # "broken": false,
227 # "status": {
228 # "statuses": [
229 # "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
230 # "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
231 # "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
232 # "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
233 # ]
234 # },
235 # "num-vqs": 2,
236 # "guest-features": {
237 # "dev-features": [],
238 # "transports": [
239 # "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
240 # "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
241 # "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
242 # ]
243 # },
244 # "host-features": {
245 # "unknown-dev-features": 1073741824,
246 # "dev-features": [],
247 # "transports": [
248 # "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
249 # "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
250 # "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
251 # "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
252 # "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
253 # ]
254 # },
255 # "use-guest-notifier-mask": true,
256 # "vm-running": true,
257 # "queue-sel": 1,
258 # "disabled": false,
259 # "vhost-started": false,
260 # "use-started": true
261 # }
262 # }
263 #
264 # 2. Poll for the status of virtio-net (vhost-net is active)
265 #
266 # -> { "execute": "x-query-virtio-status",
267 # "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" }
268 # }
269 # <- { "return": {
270 # "device-endian": "little",
271 # "bus-name": "",
272 # "disabled-legacy-check": false,
273 # "name": "virtio-net",
274 # "started": true,
275 # "device-id": 1,
276 # "vhost-dev": {
277 # "n-tmp-sections": 4,
278 # "n-mem-sections": 4,
279 # "max-queues": 1,
280 # "backend-cap": 2,
281 # "log-size": 0,
282 # "backend-features": {
283 # "dev-features": [],
284 # "transports": []
285 # },
286 # "nvqs": 2,
287 # "protocol-features": {
288 # "protocols": []
289 # },
290 # "vq-index": 0,
291 # "log-enabled": false,
292 # "acked-features": {
293 # "dev-features": [
294 # "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
295 # ],
296 # "transports": [
297 # "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
298 # "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
299 # "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
300 # ]
301 # },
302 # "features": {
303 # "dev-features": [
304 # "VHOST_F_LOG_ALL: Logging write descriptors supported",
305 # "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
306 # ],
307 # "transports": [
308 # "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
309 # "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
310 # "VIRTIO_F_IOMMU_PLATFORM: Device can be used on IOMMU platform",
311 # "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
312 # "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
313 # "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
314 # ]
315 # }
316 # },
317 # "backend-features": {
318 # "dev-features": [
319 # "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
320 # "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
321 # "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
322 # "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
323 # "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
324 # "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
325 # "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
326 # "VIRTIO_NET_F_CTRL_VQ: Control channel available",
327 # "VIRTIO_NET_F_STATUS: Configuration status field available",
328 # "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
329 # "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
330 # "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
331 # "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
332 # "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
333 # "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
334 # "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
335 # "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
336 # "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
337 # "VIRTIO_NET_F_MAC: Device has given MAC address",
338 # "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
339 # "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
340 # "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
341 # ],
342 # "transports": [
343 # "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
344 # "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
345 # "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
346 # "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
347 # "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
348 # ]
349 # },
350 # "start-on-kick": false,
351 # "isr": 1,
352 # "broken": false,
353 # "status": {
354 # "statuses": [
355 # "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
356 # "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
357 # "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
358 # "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
359 # ]
360 # },
361 # "num-vqs": 3,
362 # "guest-features": {
363 # "dev-features": [
364 # "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
365 # "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
366 # "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
367 # "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
368 # "VIRTIO_NET_F_CTRL_VQ: Control channel available",
369 # "VIRTIO_NET_F_STATUS: Configuration status field available",
370 # "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
371 # "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
372 # "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
373 # "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
374 # "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
375 # "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
376 # "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
377 # "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
378 # "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
379 # "VIRTIO_NET_F_MAC: Device has given MAC address",
380 # "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
381 # "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
382 # "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
383 # ],
384 # "transports": [
385 # "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
386 # "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
387 # "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
388 # ]
389 # },
390 # "host-features": {
391 # "dev-features": [
392 # "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
393 # "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
394 # "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
395 # "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
396 # "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
397 # "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
398 # "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
399 # "VIRTIO_NET_F_CTRL_VQ: Control channel available",
400 # "VIRTIO_NET_F_STATUS: Configuration status field available",
401 # "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
402 # "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
403 # "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
404 # "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
405 # "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
406 # "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
407 # "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
408 # "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
409 # "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
410 # "VIRTIO_NET_F_MAC: Device has given MAC address",
411 # "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
412 # "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
413 # "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
414 # ],
415 # "transports": [
416 # "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
417 # "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
418 # "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
419 # "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
420 # "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
421 # ]
422 # },
423 # "use-guest-notifier-mask": true,
424 # "vm-running": true,
425 # "queue-sel": 2,
426 # "disabled": false,
427 # "vhost-started": true,
428 # "use-started": true
429 # }
430 # }
431 ##
432 { 'command': 'x-query-virtio-status',
433 'data': { 'path': 'str' },
434 'returns': 'VirtioStatus',
435 'features': [ 'unstable' ] }
437 ##
438 # @VirtioDeviceStatus:
439 #
440 # A structure defined to list the configuration statuses of a virtio
441 # device
442 #
443 # @statuses: List of decoded configuration statuses of the virtio
444 # device
445 #
446 # @unknown-statuses: Virtio device statuses bitmap that have not been
447 # decoded
448 #
449 # Since: 7.2
450 ##
451 { 'struct': 'VirtioDeviceStatus',
452 'data': { 'statuses': [ 'str' ],
453 '*unknown-statuses': 'uint8' } }
455 ##
456 # @VhostDeviceProtocols:
457 #
458 # A structure defined to list the vhost user protocol features of a
459 # Vhost User device
460 #
461 # @protocols: List of decoded vhost user protocol features of a vhost
462 # user device
463 #
464 # @unknown-protocols: Vhost user device protocol features bitmap that
465 # have not been decoded
466 #
467 # Since: 7.2
468 ##
469 { 'struct': 'VhostDeviceProtocols',
470 'data': { 'protocols': [ 'str' ],
471 '*unknown-protocols': 'uint64' } }
473 ##
474 # @VirtioDeviceFeatures:
475 #
476 # The common fields that apply to most Virtio devices. Some devices
477 # may not have their own device-specific features (e.g. virtio-rng).
478 #
479 # @transports: List of transport features of the virtio device
480 #
481 # @dev-features: List of device-specific features (if the device has
482 # unique features)
483 #
484 # @unknown-dev-features: Virtio device features bitmap that have not
485 # been decoded
486 #
487 # Since: 7.2
488 ##
489 { 'struct': 'VirtioDeviceFeatures',
490 'data': { 'transports': [ 'str' ],
491 '*dev-features': [ 'str' ],
492 '*unknown-dev-features': 'uint64' } }
494 ##
495 # @VirtQueueStatus:
496 #
497 # Information of a VirtIODevice VirtQueue, including most members of
498 # the VirtQueue data structure.
499 #
500 # @name: Name of the VirtIODevice that uses this VirtQueue
501 #
502 # @queue-index: VirtQueue queue_index
503 #
504 # @inuse: VirtQueue inuse
505 #
506 # @vring-num: VirtQueue vring.num
507 #
508 # @vring-num-default: VirtQueue vring.num_default
509 #
510 # @vring-align: VirtQueue vring.align
511 #
512 # @vring-desc: VirtQueue vring.desc (descriptor area)
513 #
514 # @vring-avail: VirtQueue vring.avail (driver area)
515 #
516 # @vring-used: VirtQueue vring.used (device area)
517 #
518 # @last-avail-idx: VirtQueue last_avail_idx or return of vhost_dev
519 # vhost_get_vring_base (if vhost active)
520 #
521 # @shadow-avail-idx: VirtQueue shadow_avail_idx
522 #
523 # @used-idx: VirtQueue used_idx
524 #
525 # @signalled-used: VirtQueue signalled_used
526 #
527 # @signalled-used-valid: VirtQueue signalled_used_valid flag
528 #
529 # Since: 7.2
530 ##
531 { 'struct': 'VirtQueueStatus',
532 'data': { 'name': 'str',
533 'queue-index': 'uint16',
534 'inuse': 'uint32',
535 'vring-num': 'uint32',
536 'vring-num-default': 'uint32',
537 'vring-align': 'uint32',
538 'vring-desc': 'uint64',
539 'vring-avail': 'uint64',
540 'vring-used': 'uint64',
541 '*last-avail-idx': 'uint16',
542 '*shadow-avail-idx': 'uint16',
543 'used-idx': 'uint16',
544 'signalled-used': 'uint16',
545 'signalled-used-valid': 'bool' } }
547 ##
548 # @x-query-virtio-queue-status:
549 #
550 # Return the status of a given VirtIODevice's VirtQueue
551 #
552 # @path: VirtIODevice canonical QOM path
553 #
554 # @queue: VirtQueue index to examine
555 #
556 # Features:
557 #
558 # @unstable: This command is meant for debugging.
559 #
560 # Returns: VirtQueueStatus of the VirtQueue
561 #
562 # Notes: last_avail_idx will not be displayed in the case where the
563 # selected VirtIODevice has a running vhost device and the
564 # VirtIODevice VirtQueue index (queue) does not exist for the
565 # corresponding vhost device vhost_virtqueue. Also,
566 # shadow_avail_idx will not be displayed in the case where the
567 # selected VirtIODevice has a running vhost device.
568 #
569 # Since: 7.2
570 #
571 # Examples:
572 #
573 # 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running)
574 #
575 # -> { "execute": "x-query-virtio-queue-status",
576 # "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
577 # "queue": 1 }
578 # }
579 # <- { "return": {
580 # "signalled-used": 0,
581 # "inuse": 0,
582 # "name": "vhost-vsock",
583 # "vring-align": 4096,
584 # "vring-desc": 5217370112,
585 # "signalled-used-valid": false,
586 # "vring-num-default": 128,
587 # "vring-avail": 5217372160,
588 # "queue-index": 1,
589 # "last-avail-idx": 0,
590 # "vring-used": 5217372480,
591 # "used-idx": 0,
592 # "vring-num": 128
593 # }
594 # }
595 #
596 # 2. Get VirtQueueStatus for virtio-serial (no vhost)
597 #
598 # -> { "execute": "x-query-virtio-queue-status",
599 # "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend",
600 # "queue": 20 }
601 # }
602 # <- { "return": {
603 # "signalled-used": 0,
604 # "inuse": 0,
605 # "name": "virtio-serial",
606 # "vring-align": 4096,
607 # "vring-desc": 5182074880,
608 # "signalled-used-valid": false,
609 # "vring-num-default": 128,
610 # "vring-avail": 5182076928,
611 # "queue-index": 20,
612 # "last-avail-idx": 0,
613 # "vring-used": 5182077248,
614 # "used-idx": 0,
615 # "shadow-avail-idx": 0,
616 # "vring-num": 128
617 # }
618 # }
619 ##
620 { 'command': 'x-query-virtio-queue-status',
621 'data': { 'path': 'str', 'queue': 'uint16' },
622 'returns': 'VirtQueueStatus',
623 'features': [ 'unstable' ] }
625 ##
626 # @VirtVhostQueueStatus:
627 #
628 # Information of a vhost device's vhost_virtqueue, including most
629 # members of the vhost_dev vhost_virtqueue data structure.
630 #
631 # @name: Name of the VirtIODevice that uses this vhost_virtqueue
632 #
633 # @kick: vhost_virtqueue kick
634 #
635 # @call: vhost_virtqueue call
636 #
637 # @desc: vhost_virtqueue desc
638 #
639 # @avail: vhost_virtqueue avail
640 #
641 # @used: vhost_virtqueue used
642 #
643 # @num: vhost_virtqueue num
644 #
645 # @desc-phys: vhost_virtqueue desc_phys (descriptor area physical
646 # address)
647 #
648 # @desc-size: vhost_virtqueue desc_size
649 #
650 # @avail-phys: vhost_virtqueue avail_phys (driver area physical
651 # address)
652 #
653 # @avail-size: vhost_virtqueue avail_size
654 #
655 # @used-phys: vhost_virtqueue used_phys (device area physical address)
656 #
657 # @used-size: vhost_virtqueue used_size
658 #
659 # Since: 7.2
660 ##
661 { 'struct': 'VirtVhostQueueStatus',
662 'data': { 'name': 'str',
663 'kick': 'int',
664 'call': 'int',
665 'desc': 'uint64',
666 'avail': 'uint64',
667 'used': 'uint64',
668 'num': 'int',
669 'desc-phys': 'uint64',
670 'desc-size': 'uint32',
671 'avail-phys': 'uint64',
672 'avail-size': 'uint32',
673 'used-phys': 'uint64',
674 'used-size': 'uint32' } }
676 ##
677 # @x-query-virtio-vhost-queue-status:
678 #
679 # Return information of a given vhost device's vhost_virtqueue
680 #
681 # @path: VirtIODevice canonical QOM path
682 #
683 # @queue: vhost_virtqueue index to examine
684 #
685 # Features:
686 #
687 # @unstable: This command is meant for debugging.
688 #
689 # Returns: VirtVhostQueueStatus of the vhost_virtqueue
690 #
691 # Since: 7.2
692 #
693 # Examples:
694 #
695 # 1. Get vhost_virtqueue status for vhost-crypto
696 #
697 # -> { "execute": "x-query-virtio-vhost-queue-status",
698 # "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
699 # "queue": 0 }
700 # }
701 # <- { "return": {
702 # "avail-phys": 5216124928,
703 # "name": "virtio-crypto",
704 # "used-phys": 5216127040,
705 # "avail-size": 2054,
706 # "desc-size": 16384,
707 # "used-size": 8198,
708 # "desc": 140141447430144,
709 # "num": 1024,
710 # "call": 0,
711 # "avail": 140141447446528,
712 # "desc-phys": 5216108544,
713 # "used": 140141447448640,
714 # "kick": 0
715 # }
716 # }
717 #
718 # 2. Get vhost_virtqueue status for vhost-vsock
719 #
720 # -> { "execute": "x-query-virtio-vhost-queue-status",
721 # "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
722 # "queue": 0 }
723 # }
724 # <- { "return": {
725 # "avail-phys": 5182261248,
726 # "name": "vhost-vsock",
727 # "used-phys": 5182261568,
728 # "avail-size": 262,
729 # "desc-size": 2048,
730 # "used-size": 1030,
731 # "desc": 140141413580800,
732 # "num": 128,
733 # "call": 0,
734 # "avail": 140141413582848,
735 # "desc-phys": 5182259200,
736 # "used": 140141413583168,
737 # "kick": 0
738 # }
739 # }
740 ##
741 { 'command': 'x-query-virtio-vhost-queue-status',
742 'data': { 'path': 'str', 'queue': 'uint16' },
743 'returns': 'VirtVhostQueueStatus',
744 'features': [ 'unstable' ] }
746 ##
747 # @VirtioRingDesc:
748 #
749 # Information regarding the vring descriptor area
750 #
751 # @addr: Guest physical address of the descriptor area
752 #
753 # @len: Length of the descriptor area
754 #
755 # @flags: List of descriptor flags
756 #
757 # Since: 7.2
758 ##
759 { 'struct': 'VirtioRingDesc',
760 'data': { 'addr': 'uint64',
761 'len': 'uint32',
762 'flags': [ 'str' ] } }
764 ##
765 # @VirtioRingAvail:
766 #
767 # Information regarding the avail vring (a.k.a. driver area)
768 #
769 # @flags: VRingAvail flags
770 #
771 # @idx: VRingAvail index
772 #
773 # @ring: VRingAvail ring[] entry at provided index
774 #
775 # Since: 7.2
776 ##
777 { 'struct': 'VirtioRingAvail',
778 'data': { 'flags': 'uint16',
779 'idx': 'uint16',
780 'ring': 'uint16' } }
782 ##
783 # @VirtioRingUsed:
784 #
785 # Information regarding the used vring (a.k.a. device area)
786 #
787 # @flags: VRingUsed flags
788 #
789 # @idx: VRingUsed index
790 #
791 # Since: 7.2
792 ##
793 { 'struct': 'VirtioRingUsed',
794 'data': { 'flags': 'uint16',
795 'idx': 'uint16' } }
797 ##
798 # @VirtioQueueElement:
799 #
800 # Information regarding a VirtQueue's VirtQueueElement including
801 # descriptor, driver, and device areas
802 #
803 # @name: Name of the VirtIODevice that uses this VirtQueue
804 #
805 # @index: Index of the element in the queue
806 #
807 # @descs: List of descriptors (VirtioRingDesc)
808 #
809 # @avail: VRingAvail info
810 #
811 # @used: VRingUsed info
812 #
813 # Since: 7.2
814 ##
815 { 'struct': 'VirtioQueueElement',
816 'data': { 'name': 'str',
817 'index': 'uint32',
818 'descs': [ 'VirtioRingDesc' ],
819 'avail': 'VirtioRingAvail',
820 'used': 'VirtioRingUsed' } }
822 ##
823 # @x-query-virtio-queue-element:
824 #
825 # Return the information about a VirtQueue's VirtQueueElement
826 #
827 # @path: VirtIODevice canonical QOM path
828 #
829 # @queue: VirtQueue index to examine
830 #
831 # @index: Index of the element in the queue (default: head of the
832 # queue)
833 #
834 # Features:
835 #
836 # @unstable: This command is meant for debugging.
837 #
838 # Returns: VirtioQueueElement information
839 #
840 # Since: 7.2
841 #
842 # Examples:
843 #
844 # 1. Introspect on virtio-net's VirtQueue 0 at index 5
845 #
846 # -> { "execute": "x-query-virtio-queue-element",
847 # "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend",
848 # "queue": 0,
849 # "index": 5 }
850 # }
851 # <- { "return": {
852 # "index": 5,
853 # "name": "virtio-net",
854 # "descs": [
855 # {
856 # "flags": ["write"],
857 # "len": 1536,
858 # "addr": 5257305600
859 # }
860 # ],
861 # "avail": {
862 # "idx": 256,
863 # "flags": 0,
864 # "ring": 5
865 # },
866 # "used": {
867 # "idx": 13,
868 # "flags": 0
869 # }
870 # }
871 # }
872 #
873 # 2. Introspect on virtio-crypto's VirtQueue 1 at head
874 #
875 # -> { "execute": "x-query-virtio-queue-element",
876 # "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
877 # "queue": 1 }
878 # }
879 # <- { "return": {
880 # "index": 0,
881 # "name": "virtio-crypto",
882 # "descs": [
883 # {
884 # "flags": [],
885 # "len": 0,
886 # "addr": 8080268923184214134
887 # }
888 # ],
889 # "avail": {
890 # "idx": 280,
891 # "flags": 0,
892 # "ring": 0
893 # },
894 # "used": {
895 # "idx": 280,
896 # "flags": 0
897 # }
898 # }
899 # }
900 #
901 # 3. Introspect on virtio-scsi's VirtQueue 2 at head
902 #
903 # -> { "execute": "x-query-virtio-queue-element",
904 # "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend",
905 # "queue": 2 }
906 # }
907 # <- { "return": {
908 # "index": 19,
909 # "name": "virtio-scsi",
910 # "descs": [
911 # {
912 # "flags": ["used", "indirect", "write"],
913 # "len": 4099327944,
914 # "addr": 12055409292258155293
915 # }
916 # ],
917 # "avail": {
918 # "idx": 1147,
919 # "flags": 0,
920 # "ring": 19
921 # },
922 # "used": {
923 # "idx": 280,
924 # "flags": 0
925 # }
926 # }
927 # }
928 ##
929 { 'command': 'x-query-virtio-queue-element',
930 'data': { 'path': 'str', 'queue': 'uint16', '*index': 'uint16' },
931 'returns': 'VirtioQueueElement',
932 'features': [ 'unstable' ] }
934 ##
935 # @IOThreadVirtQueueMapping:
936 #
937 # Describes the subset of virtqueues assigned to an IOThread.
938 #
939 # @iothread: the id of IOThread object
940 #
941 # @vqs: an optional array of virtqueue indices that will be handled by
942 # this IOThread. When absent, virtqueues are assigned round-robin
943 # across all IOThreadVirtQueueMappings provided. Either all
944 # IOThreadVirtQueueMappings must have @vqs or none of them must
945 # have it.
946 #
947 # Since: 9.0
948 ##
950 { 'struct': 'IOThreadVirtQueueMapping',
951 'data': { 'iothread': 'str', '*vqs': ['uint16'] } }
953 ##
954 # @DummyVirtioForceArrays:
955 #
956 # Not used by QMP; hack to let us use IOThreadVirtQueueMappingList
957 # internally
958 #
959 # Since: 9.0
960 ##
962 { 'struct': 'DummyVirtioForceArrays',
963 'data': { 'unused-iothread-vq-mapping': ['IOThreadVirtQueueMapping'] } }
965 ##
966 # @GranuleMode:
967 #
968 # @4k: granule page size of 4KiB
969 #
970 # @8k: granule page size of 8KiB
971 #
972 # @16k: granule page size of 16KiB
973 #
974 # @64k: granule page size of 64KiB
975 #
976 # @host: granule matches the host page size
977 #
978 # Since: 9.0
979 ##
980 { 'enum': 'GranuleMode',
981 'data': [ '4k', '8k', '16k', '64k', 'host' ] }