9 { 'include': 'sockets.json' }
14 # Information about a character device.
16 # @label: the label of the character device
18 # @filename: the filename of the character device
20 # @frontend-open: shows whether the frontend device attached to this
21 # backend (e.g. with the chardev=... option) is in open or closed
24 # Notes: @filename is encoded using the QEMU command line character
25 # device encoding. See the QEMU man page for details.
29 { 'struct': 'ChardevInfo',
30 'data': { 'label': 'str',
32 'frontend-open': 'bool' } }
37 # Returns information about current character devices.
39 # Returns: a list of @ChardevInfo
45 # -> { "execute": "query-chardev" }
49 # "label": "charchannel0",
50 # "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
51 # "frontend-open": false
54 # "label": "charmonitor",
55 # "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
56 # "frontend-open": true
59 # "label": "charserial0",
60 # "filename": "pty:/dev/pts/2",
61 # "frontend-open": true
66 { 'command': 'query-chardev', 'returns': ['ChardevInfo'],
67 'allow-preconfig': true }
70 # @ChardevBackendInfo:
72 # Information about a character device backend
74 # @name: The backend name
78 { 'struct': 'ChardevBackendInfo', 'data': {'name': 'str'} }
81 # @query-chardev-backends:
83 # Returns information about character device backends.
85 # Returns: a list of @ChardevBackendInfo
91 # -> { "execute": "query-chardev-backends" }
109 { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
114 # An enumeration of data format.
116 # @utf8: Data is a UTF-8 string (RFC 3629)
118 # @base64: Data is Base64 encoded binary (RFC 3548)
122 { 'enum': 'DataFormat',
123 'data': [ 'utf8', 'base64' ] }
128 # Write to a ring buffer character device.
130 # @device: the ring buffer character device name
132 # @data: data to write
134 # @format: data encoding (default 'utf8').
136 # - base64: data must be base64 encoded text. Its binary decoding
138 # - utf8: data's UTF-8 encoding is written
139 # - data itself is always Unicode regardless of format, like any
142 # Returns: Nothing on success
148 # -> { "execute": "ringbuf-write",
149 # "arguments": { "device": "foo",
150 # "data": "abcdefgh",
151 # "format": "utf8" } }
152 # <- { "return": {} }
154 { 'command': 'ringbuf-write',
155 'data': { 'device': 'str',
157 '*format': 'DataFormat'} }
162 # Read from a ring buffer character device.
164 # @device: the ring buffer character device name
166 # @size: how many bytes to read at most
168 # @format: data encoding (default 'utf8').
170 # - base64: the data read is returned in base64 encoding.
171 # - utf8: the data read is interpreted as UTF-8.
172 # Bug: can screw up when the buffer contains invalid UTF-8
173 # sequences, NUL characters, after the ring buffer lost data,
174 # and when reading stops because the size limit is reached.
175 # - The return value is always Unicode regardless of format, like
178 # Returns: data read from the device
184 # -> { "execute": "ringbuf-read",
185 # "arguments": { "device": "foo",
187 # "format": "utf8" } }
188 # <- { "return": "abcdefgh" }
190 { 'command': 'ringbuf-read',
191 'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
197 # Configuration shared across all chardev backends
199 # @logfile: The name of a logfile to save output
201 # @logappend: true to append instead of truncate (default to false to
206 { 'struct': 'ChardevCommon',
207 'data': { '*logfile': 'str',
208 '*logappend': 'bool' } }
213 # Configuration info for file chardevs.
215 # @in: The name of the input file
217 # @out: The name of the output file
219 # @append: Open the file in append mode (default false to truncate)
224 { 'struct': 'ChardevFile',
225 'data': { '*in': 'str',
228 'base': 'ChardevCommon' }
233 # Configuration info for device and pipe chardevs.
235 # @device: The name of the special file for the device, i.e.
236 # /dev/ttyS0 on Unix or COM1: on Windows
240 { 'struct': 'ChardevHostdev',
241 'data': { 'device': 'str' },
242 'base': 'ChardevCommon' }
247 # Configuration info for (stream) socket chardevs.
249 # @addr: socket address to listen on (server=true) or connect to
252 # @tls-creds: the ID of the TLS credentials object (since 2.6)
254 # @tls-authz: the ID of the QAuthZ authorization object against which
255 # the client's x509 distinguished name will be validated. This
256 # object is only resolved at time of use, so can be deleted and
257 # recreated on the fly while the chardev server is active. If
258 # missing, it will default to denying access (since 4.0)
260 # @server: create server socket (default: true)
262 # @wait: wait for incoming connection on server sockets (default:
263 # false). Silently ignored with server: false. This use is
266 # @nodelay: set TCP_NODELAY socket option (default: false)
268 # @telnet: enable telnet protocol on server sockets (default: false)
270 # @tn3270: enable tn3270 protocol on server sockets (default: false)
273 # @websocket: enable websocket protocol on server sockets
274 # (default: false) (Since: 3.1)
276 # @reconnect: For a client socket, if a socket is disconnected, then
277 # attempt a reconnect after the given number of seconds. Setting
278 # this to zero disables this function. (default: 0) (Since: 2.2)
282 { 'struct': 'ChardevSocket',
283 'data': { 'addr': 'SocketAddressLegacy',
285 '*tls-authz' : 'str',
291 '*websocket': 'bool',
292 '*reconnect': 'int' },
293 'base': 'ChardevCommon' }
298 # Configuration info for datagram socket chardevs.
300 # @remote: remote address
302 # @local: local address
306 { 'struct': 'ChardevUdp',
307 'data': { 'remote': 'SocketAddressLegacy',
308 '*local': 'SocketAddressLegacy' },
309 'base': 'ChardevCommon' }
314 # Configuration info for mux chardevs.
316 # @chardev: name of the base chardev.
320 { 'struct': 'ChardevMux',
321 'data': { 'chardev': 'str' },
322 'base': 'ChardevCommon' }
327 # Configuration info for stdio chardevs.
329 # @signal: Allow signals (such as SIGINT triggered by ^C) be delivered
330 # to qemu. Default: true.
334 { 'struct': 'ChardevStdio',
335 'data': { '*signal': 'bool' },
336 'base': 'ChardevCommon' }
339 # @ChardevSpiceChannel:
341 # Configuration info for spice vm channel chardevs.
343 # @type: kind of channel (for example vdagent).
347 { 'struct': 'ChardevSpiceChannel',
348 'data': { 'type': 'str' },
349 'base': 'ChardevCommon',
350 'if': 'CONFIG_SPICE' }
355 # Configuration info for spice port chardevs.
357 # @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
361 { 'struct': 'ChardevSpicePort',
362 'data': { 'fqdn': 'str' },
363 'base': 'ChardevCommon',
364 'if': 'CONFIG_SPICE' }
369 # Configuration info for DBus chardevs.
371 # @name: name of the channel (following docs/spice-port-fqdn.txt)
375 { 'struct': 'ChardevDBus',
376 'data': { 'name': 'str' },
377 'base': 'ChardevCommon',
378 'if': 'CONFIG_DBUS_DISPLAY' }
383 # Configuration info for virtual console chardevs.
385 # @width: console width, in pixels
387 # @height: console height, in pixels
389 # @cols: console width, in chars
391 # @rows: console height, in chars
393 # Note: the options are only effective when the VNC or SDL graphical
394 # display backend is active. They are ignored with the GTK,
395 # Spice, VNC and D-Bus display backends.
399 { 'struct': 'ChardevVC',
400 'data': { '*width': 'int',
404 'base': 'ChardevCommon' }
409 # Configuration info for ring buffer chardevs.
411 # @size: ring buffer size, must be power of two, default is 65536
415 { 'struct': 'ChardevRingbuf',
416 'data': { '*size': 'int' },
417 'base': 'ChardevCommon' }
420 # @ChardevQemuVDAgent:
422 # Configuration info for qemu vdagent implementation.
424 # @mouse: enable/disable mouse, default is enabled.
426 # @clipboard: enable/disable clipboard, default is disabled.
430 { 'struct': 'ChardevQemuVDAgent',
431 'data': { '*mouse': 'bool',
432 '*clipboard': 'bool' },
433 'base': 'ChardevCommon',
434 'if': 'CONFIG_SPICE_PROTOCOL' }
437 # @ChardevBackendKind:
445 # @msmouse: Since 1.5
447 # @wctablet: Since 2.9
449 # @braille: Since 1.5
451 # @testdev: Since 2.2
455 # @console: Since 1.5
457 # @spicevmc: Since 1.5
459 # @spiceport: Since 1.5
461 # @qemu-vdagent: Since 6.1
467 # @ringbuf: Since 1.6
473 { 'enum': 'ChardevBackendKind',
489 { 'name': 'spicevmc', 'if': 'CONFIG_SPICE' },
490 { 'name': 'spiceport', 'if': 'CONFIG_SPICE' },
491 { 'name': 'qemu-vdagent', 'if': 'CONFIG_SPICE_PROTOCOL' },
492 { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' },
495 # next one is just for compatibility
499 # @ChardevFileWrapper:
501 # @data: Configuration info for file chardevs
505 { 'struct': 'ChardevFileWrapper',
506 'data': { 'data': 'ChardevFile' } }
509 # @ChardevHostdevWrapper:
511 # @data: Configuration info for device and pipe chardevs
515 { 'struct': 'ChardevHostdevWrapper',
516 'data': { 'data': 'ChardevHostdev' } }
519 # @ChardevSocketWrapper:
521 # @data: Configuration info for (stream) socket chardevs
525 { 'struct': 'ChardevSocketWrapper',
526 'data': { 'data': 'ChardevSocket' } }
529 # @ChardevUdpWrapper:
531 # @data: Configuration info for datagram socket chardevs
535 { 'struct': 'ChardevUdpWrapper',
536 'data': { 'data': 'ChardevUdp' } }
539 # @ChardevCommonWrapper:
541 # @data: Configuration shared across all chardev backends
545 { 'struct': 'ChardevCommonWrapper',
546 'data': { 'data': 'ChardevCommon' } }
549 # @ChardevMuxWrapper:
551 # @data: Configuration info for mux chardevs
555 { 'struct': 'ChardevMuxWrapper',
556 'data': { 'data': 'ChardevMux' } }
559 # @ChardevStdioWrapper:
561 # @data: Configuration info for stdio chardevs
565 { 'struct': 'ChardevStdioWrapper',
566 'data': { 'data': 'ChardevStdio' } }
569 # @ChardevSpiceChannelWrapper:
571 # @data: Configuration info for spice vm channel chardevs
575 { 'struct': 'ChardevSpiceChannelWrapper',
576 'data': { 'data': 'ChardevSpiceChannel' },
577 'if': 'CONFIG_SPICE' }
580 # @ChardevSpicePortWrapper:
582 # @data: Configuration info for spice port chardevs
586 { 'struct': 'ChardevSpicePortWrapper',
587 'data': { 'data': 'ChardevSpicePort' },
588 'if': 'CONFIG_SPICE' }
591 # @ChardevQemuVDAgentWrapper:
593 # @data: Configuration info for qemu vdagent implementation
597 { 'struct': 'ChardevQemuVDAgentWrapper',
598 'data': { 'data': 'ChardevQemuVDAgent' },
599 'if': 'CONFIG_SPICE_PROTOCOL' }
602 # @ChardevDBusWrapper:
604 # @data: Configuration info for DBus chardevs
608 { 'struct': 'ChardevDBusWrapper',
609 'data': { 'data': 'ChardevDBus' },
610 'if': 'CONFIG_DBUS_DISPLAY' }
615 # @data: Configuration info for virtual console chardevs
619 { 'struct': 'ChardevVCWrapper',
620 'data': { 'data': 'ChardevVC' } }
623 # @ChardevRingbufWrapper:
625 # @data: Configuration info for ring buffer chardevs
629 { 'struct': 'ChardevRingbufWrapper',
630 'data': { 'data': 'ChardevRingbuf' } }
635 # Configuration info for the new chardev backend.
637 # @type: backend type
641 { 'union': 'ChardevBackend',
642 'base': { 'type': 'ChardevBackendKind' },
643 'discriminator': 'type',
644 'data': { 'file': 'ChardevFileWrapper',
645 'serial': 'ChardevHostdevWrapper',
646 'parallel': 'ChardevHostdevWrapper',
647 'pipe': 'ChardevHostdevWrapper',
648 'socket': 'ChardevSocketWrapper',
649 'udp': 'ChardevUdpWrapper',
650 'pty': 'ChardevCommonWrapper',
651 'null': 'ChardevCommonWrapper',
652 'mux': 'ChardevMuxWrapper',
653 'msmouse': 'ChardevCommonWrapper',
654 'wctablet': 'ChardevCommonWrapper',
655 'braille': 'ChardevCommonWrapper',
656 'testdev': 'ChardevCommonWrapper',
657 'stdio': 'ChardevStdioWrapper',
658 'console': 'ChardevCommonWrapper',
659 'spicevmc': { 'type': 'ChardevSpiceChannelWrapper',
660 'if': 'CONFIG_SPICE' },
661 'spiceport': { 'type': 'ChardevSpicePortWrapper',
662 'if': 'CONFIG_SPICE' },
663 'qemu-vdagent': { 'type': 'ChardevQemuVDAgentWrapper',
664 'if': 'CONFIG_SPICE_PROTOCOL' },
665 'dbus': { 'type': 'ChardevDBusWrapper',
666 'if': 'CONFIG_DBUS_DISPLAY' },
667 'vc': 'ChardevVCWrapper',
668 'ringbuf': 'ChardevRingbufWrapper',
669 # next one is just for compatibility
670 'memory': 'ChardevRingbufWrapper' } }
675 # Return info about the chardev backend just created.
677 # @pty: name of the slave pseudoterminal device, present if and only
678 # if a chardev of type 'pty' was created
682 { 'struct' : 'ChardevReturn',
683 'data': { '*pty': 'str' } }
688 # Add a character device backend
690 # @id: the chardev's ID, must be unique
692 # @backend: backend type and parameters
694 # Returns: ChardevReturn.
700 # -> { "execute" : "chardev-add",
701 # "arguments" : { "id" : "foo",
702 # "backend" : { "type" : "null", "data" : {} } } }
703 # <- { "return": {} }
705 # -> { "execute" : "chardev-add",
706 # "arguments" : { "id" : "bar",
707 # "backend" : { "type" : "file",
708 # "data" : { "out" : "/tmp/bar.log" } } } }
709 # <- { "return": {} }
711 # -> { "execute" : "chardev-add",
712 # "arguments" : { "id" : "baz",
713 # "backend" : { "type" : "pty", "data" : {} } } }
714 # <- { "return": { "pty" : "/dev/pty/42" } }
716 { 'command': 'chardev-add',
717 'data': { 'id': 'str',
718 'backend': 'ChardevBackend' },
719 'returns': 'ChardevReturn' }
724 # Change a character device backend
726 # @id: the chardev's ID, must exist
728 # @backend: new backend type and parameters
730 # Returns: ChardevReturn.
736 # -> { "execute" : "chardev-change",
737 # "arguments" : { "id" : "baz",
738 # "backend" : { "type" : "pty", "data" : {} } } }
739 # <- { "return": { "pty" : "/dev/pty/42" } }
741 # -> {"execute" : "chardev-change",
743 # "id" : "charchannel2",
750 # "path" : "/tmp/charchannel2.socket"
754 # "wait" : false }}}}
757 { 'command': 'chardev-change',
758 'data': { 'id': 'str',
759 'backend': 'ChardevBackend' },
760 'returns': 'ChardevReturn' }
765 # Remove a character device backend
767 # @id: the chardev's ID, must exist and not be in use
769 # Returns: Nothing on success
775 # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
776 # <- { "return": {} }
778 { 'command': 'chardev-remove',
779 'data': { 'id': 'str' } }
782 # @chardev-send-break:
784 # Send a break to a character device
786 # @id: the chardev's ID, must exist
788 # Returns: Nothing on success
794 # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
795 # <- { "return": {} }
797 { 'command': 'chardev-send-break',
798 'data': { 'id': 'str' } }
803 # Emitted when the guest opens or closes a virtio-serial port.
805 # @id: device identifier of the virtio-serial port
807 # @open: true if the guest has opened the virtio-serial port
809 # Note: This event is rate-limited.
815 # <- { "event": "VSERPORT_CHANGE",
816 # "data": { "id": "channel0", "open": true },
817 # "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
819 { 'event': 'VSERPORT_CHANGE',
820 'data': { 'id': 'str',