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 (eg. 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
395 { 'struct': 'ChardevVC',
396 'data': { '*width': 'int',
400 'base': 'ChardevCommon' }
405 # Configuration info for ring buffer chardevs.
407 # @size: ring buffer size, must be power of two, default is 65536
411 { 'struct': 'ChardevRingbuf',
412 'data': { '*size': 'int' },
413 'base': 'ChardevCommon' }
416 # @ChardevQemuVDAgent:
418 # Configuration info for qemu vdagent implementation.
420 # @mouse: enable/disable mouse, default is enabled.
422 # @clipboard: enable/disable clipboard, default is disabled.
426 { 'struct': 'ChardevQemuVDAgent',
427 'data': { '*mouse': 'bool',
428 '*clipboard': 'bool' },
429 'base': 'ChardevCommon',
430 'if': 'CONFIG_SPICE_PROTOCOL' }
433 # @ChardevBackendKind:
441 # @msmouse: Since 1.5
443 # @wctablet: Since 2.9
445 # @braille: Since 1.5
447 # @testdev: Since 2.2
451 # @console: Since 1.5
453 # @spicevmc: Since 1.5
455 # @spiceport: Since 1.5
457 # @qemu-vdagent: Since 6.1
463 # @ringbuf: Since 1.6
469 { 'enum': 'ChardevBackendKind',
485 { 'name': 'spicevmc', 'if': 'CONFIG_SPICE' },
486 { 'name': 'spiceport', 'if': 'CONFIG_SPICE' },
487 { 'name': 'qemu-vdagent', 'if': 'CONFIG_SPICE_PROTOCOL' },
488 { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' },
491 # next one is just for compatibility
495 # @ChardevFileWrapper:
499 { 'struct': 'ChardevFileWrapper',
500 'data': { 'data': 'ChardevFile' } }
503 # @ChardevHostdevWrapper:
507 { 'struct': 'ChardevHostdevWrapper',
508 'data': { 'data': 'ChardevHostdev' } }
511 # @ChardevSocketWrapper:
515 { 'struct': 'ChardevSocketWrapper',
516 'data': { 'data': 'ChardevSocket' } }
519 # @ChardevUdpWrapper:
523 { 'struct': 'ChardevUdpWrapper',
524 'data': { 'data': 'ChardevUdp' } }
527 # @ChardevCommonWrapper:
531 { 'struct': 'ChardevCommonWrapper',
532 'data': { 'data': 'ChardevCommon' } }
535 # @ChardevMuxWrapper:
539 { 'struct': 'ChardevMuxWrapper',
540 'data': { 'data': 'ChardevMux' } }
543 # @ChardevStdioWrapper:
547 { 'struct': 'ChardevStdioWrapper',
548 'data': { 'data': 'ChardevStdio' } }
551 # @ChardevSpiceChannelWrapper:
555 { 'struct': 'ChardevSpiceChannelWrapper',
556 'data': { 'data': 'ChardevSpiceChannel' },
557 'if': 'CONFIG_SPICE' }
560 # @ChardevSpicePortWrapper:
564 { 'struct': 'ChardevSpicePortWrapper',
565 'data': { 'data': 'ChardevSpicePort' },
566 'if': 'CONFIG_SPICE' }
569 # @ChardevQemuVDAgentWrapper:
573 { 'struct': 'ChardevQemuVDAgentWrapper',
574 'data': { 'data': 'ChardevQemuVDAgent' },
575 'if': 'CONFIG_SPICE_PROTOCOL' }
578 # @ChardevDBusWrapper:
582 { 'struct': 'ChardevDBusWrapper',
583 'data': { 'data': 'ChardevDBus' },
584 'if': 'CONFIG_DBUS_DISPLAY' }
591 { 'struct': 'ChardevVCWrapper',
592 'data': { 'data': 'ChardevVC' } }
595 # @ChardevRingbufWrapper:
599 { 'struct': 'ChardevRingbufWrapper',
600 'data': { 'data': 'ChardevRingbuf' } }
605 # Configuration info for the new chardev backend.
609 { 'union': 'ChardevBackend',
610 'base': { 'type': 'ChardevBackendKind' },
611 'discriminator': 'type',
612 'data': { 'file': 'ChardevFileWrapper',
613 'serial': 'ChardevHostdevWrapper',
614 'parallel': 'ChardevHostdevWrapper',
615 'pipe': 'ChardevHostdevWrapper',
616 'socket': 'ChardevSocketWrapper',
617 'udp': 'ChardevUdpWrapper',
618 'pty': 'ChardevCommonWrapper',
619 'null': 'ChardevCommonWrapper',
620 'mux': 'ChardevMuxWrapper',
621 'msmouse': 'ChardevCommonWrapper',
622 'wctablet': 'ChardevCommonWrapper',
623 'braille': 'ChardevCommonWrapper',
624 'testdev': 'ChardevCommonWrapper',
625 'stdio': 'ChardevStdioWrapper',
626 'console': 'ChardevCommonWrapper',
627 'spicevmc': { 'type': 'ChardevSpiceChannelWrapper',
628 'if': 'CONFIG_SPICE' },
629 'spiceport': { 'type': 'ChardevSpicePortWrapper',
630 'if': 'CONFIG_SPICE' },
631 'qemu-vdagent': { 'type': 'ChardevQemuVDAgentWrapper',
632 'if': 'CONFIG_SPICE_PROTOCOL' },
633 'dbus': { 'type': 'ChardevDBusWrapper',
634 'if': 'CONFIG_DBUS_DISPLAY' },
635 'vc': 'ChardevVCWrapper',
636 'ringbuf': 'ChardevRingbufWrapper',
637 # next one is just for compatibility
638 'memory': 'ChardevRingbufWrapper' } }
643 # Return info about the chardev backend just created.
645 # @pty: name of the slave pseudoterminal device, present if and only
646 # if a chardev of type 'pty' was created
650 { 'struct' : 'ChardevReturn',
651 'data': { '*pty': 'str' } }
656 # Add a character device backend
658 # @id: the chardev's ID, must be unique
660 # @backend: backend type and parameters
662 # Returns: ChardevReturn.
668 # -> { "execute" : "chardev-add",
669 # "arguments" : { "id" : "foo",
670 # "backend" : { "type" : "null", "data" : {} } } }
671 # <- { "return": {} }
673 # -> { "execute" : "chardev-add",
674 # "arguments" : { "id" : "bar",
675 # "backend" : { "type" : "file",
676 # "data" : { "out" : "/tmp/bar.log" } } } }
677 # <- { "return": {} }
679 # -> { "execute" : "chardev-add",
680 # "arguments" : { "id" : "baz",
681 # "backend" : { "type" : "pty", "data" : {} } } }
682 # <- { "return": { "pty" : "/dev/pty/42" } }
684 { 'command': 'chardev-add',
685 'data': { 'id': 'str',
686 'backend': 'ChardevBackend' },
687 'returns': 'ChardevReturn' }
692 # Change a character device backend
694 # @id: the chardev's ID, must exist
696 # @backend: new backend type and parameters
698 # Returns: ChardevReturn.
704 # -> { "execute" : "chardev-change",
705 # "arguments" : { "id" : "baz",
706 # "backend" : { "type" : "pty", "data" : {} } } }
707 # <- { "return": { "pty" : "/dev/pty/42" } }
709 # -> {"execute" : "chardev-change",
711 # "id" : "charchannel2",
718 # "path" : "/tmp/charchannel2.socket"
722 # "wait" : false }}}}
725 { 'command': 'chardev-change',
726 'data': { 'id': 'str',
727 'backend': 'ChardevBackend' },
728 'returns': 'ChardevReturn' }
733 # Remove a character device backend
735 # @id: the chardev's ID, must exist and not be in use
737 # Returns: Nothing on success
743 # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
744 # <- { "return": {} }
746 { 'command': 'chardev-remove',
747 'data': { 'id': 'str' } }
750 # @chardev-send-break:
752 # Send a break to a character device
754 # @id: the chardev's ID, must exist
756 # Returns: Nothing on success
762 # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
763 # <- { "return": {} }
765 { 'command': 'chardev-send-break',
766 'data': { 'id': 'str' } }
771 # Emitted when the guest opens or closes a virtio-serial port.
773 # @id: device identifier of the virtio-serial port
775 # @open: true if the guest has opened the virtio-serial port
777 # Note: This event is rate-limited.
783 # <- { "event": "VSERPORT_CHANGE",
784 # "data": { "id": "channel0", "open": true },
785 # "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
787 { 'event': 'VSERPORT_CHANGE',
788 'data': { 'id': 'str',