qapi/char.json - qemu - Git at Google

 # -*- Mode: Python -*-
 # vim: filetype=python
 #

 ##
 # = Character devices
 ##

 { 'include': 'sockets.json' }

 ##
 # @ChardevInfo:
 #
 # Information about a character device.
 #
 # @label: the label of the character device
 #
 # @filename: the filename of the character device
 #
 # @frontend-open: shows whether the frontend device attached to this
 #     backend (e.g. with the chardev=... option) is in open or closed
 #     state (since 2.1)
 #
 # Notes: @filename is encoded using the QEMU command line character
 #     device encoding.  See the QEMU man page for details.
 #
 # Since: 0.14
 ##
 { 'struct': 'ChardevInfo',
   'data': { 'label': 'str',
             'filename': 'str',
             'frontend-open': 'bool' } }

 ##
 # @query-chardev:
 #
 # Returns information about current character devices.
 #
 # Returns: a list of @ChardevInfo
 #
 # Since: 0.14
 #
 # Example:
 #
 # -> { "execute": "query-chardev" }
 # <- {
 #       "return": [
 #          {
 #             "label": "charchannel0",
 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
 #             "frontend-open": false
 #          },
 #          {
 #             "label": "charmonitor",
 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
 #             "frontend-open": true
 #          },
 #          {
 #             "label": "charserial0",
 #             "filename": "pty:/dev/pts/2",
 #             "frontend-open": true
 #          }
 #       ]
 #    }
 ##
 { 'command': 'query-chardev', 'returns': ['ChardevInfo'],
   'allow-preconfig': true }

 ##
 # @ChardevBackendInfo:
 #
 # Information about a character device backend
 #
 # @name: The backend name
 #
 # Since: 2.0
 ##
 { 'struct': 'ChardevBackendInfo', 'data': {'name': 'str'} }

 ##
 # @query-chardev-backends:
 #
 # Returns information about character device backends.
 #
 # Returns: a list of @ChardevBackendInfo
 #
 # Since: 2.0
 #
 # Example:
 #
 # -> { "execute": "query-chardev-backends" }
 # <- {
 #       "return":[
 #          {
 #             "name":"udp"
 #          },
 #          {
 #             "name":"tcp"
 #          },
 #          {
 #             "name":"unix"
 #          },
 #          {
 #             "name":"spiceport"
 #          }
 #       ]
 #    }
 ##
 { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }

 ##
 # @DataFormat:
 #
 # An enumeration of data format.
 #
 # @utf8: Data is a UTF-8 string (RFC 3629)
 #
 # @base64: Data is Base64 encoded binary (RFC 3548)
 #
 # Since: 1.4
 ##
 { 'enum': 'DataFormat',
   'data': [ 'utf8', 'base64' ] }

 ##
 # @ringbuf-write:
 #
 # Write to a ring buffer character device.
 #
 # @device: the ring buffer character device name
 #
 # @data: data to write
 #
 # @format: data encoding (default 'utf8').
 #
 #     - base64: data must be base64 encoded text.  Its binary decoding
 #       gets written.
 #     - utf8: data's UTF-8 encoding is written
 #     - data itself is always Unicode regardless of format, like any
 #       other string.
 #
 # Returns: Nothing on success
 #
 # Since: 1.4
 #
 # Example:
 #
 # -> { "execute": "ringbuf-write",
 #      "arguments": { "device": "foo",
 #                     "data": "abcdefgh",
 #                     "format": "utf8" } }
 # <- { "return": {} }
 ##
 { 'command': 'ringbuf-write',
   'data': { 'device': 'str',
             'data': 'str',
            '*format': 'DataFormat'} }

 ##
 # @ringbuf-read:
 #
 # Read from a ring buffer character device.
 #
 # @device: the ring buffer character device name
 #
 # @size: how many bytes to read at most
 #
 # @format: data encoding (default 'utf8').
 #
 #     - base64: the data read is returned in base64 encoding.
 #     - utf8: the data read is interpreted as UTF-8.
 #       Bug: can screw up when the buffer contains invalid UTF-8
 #       sequences, NUL characters, after the ring buffer lost data,
 #       and when reading stops because the size limit is reached.
 #     - The return value is always Unicode regardless of format, like
 #       any other string.
 #
 # Returns: data read from the device
 #
 # Since: 1.4
 #
 # Example:
 #
 # -> { "execute": "ringbuf-read",
 #      "arguments": { "device": "foo",
 #                     "size": 1000,
 #                     "format": "utf8" } }
 # <- { "return": "abcdefgh" }
 ##
 { 'command': 'ringbuf-read',
   'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
   'returns': 'str' }

 ##
 # @ChardevCommon:
 #
 # Configuration shared across all chardev backends
 #
 # @logfile: The name of a logfile to save output
 #
 # @logappend: true to append instead of truncate (default to false to
 #     truncate)
 #
 # Since: 2.6
 ##
 { 'struct': 'ChardevCommon',
   'data': { '*logfile': 'str',
             '*logappend': 'bool' } }

 ##
 # @ChardevFile:
 #
 # Configuration info for file chardevs.
 #
 # @in: The name of the input file
 #
 # @out: The name of the output file
 #
 # @append: Open the file in append mode (default false to truncate)
 #     (Since 2.6)
 #
 # Since: 1.4
 ##
 { 'struct': 'ChardevFile',
   'data': { '*in': 'str',
             'out': 'str',
             '*append': 'bool' },
   'base': 'ChardevCommon' }

 ##
 # @ChardevHostdev:
 #
 # Configuration info for device and pipe chardevs.
 #
 # @device: The name of the special file for the device, i.e.
 #     /dev/ttyS0 on Unix or COM1: on Windows
 #
 # Since: 1.4
 ##
 { 'struct': 'ChardevHostdev',
   'data': { 'device': 'str' },
   'base': 'ChardevCommon' }

 ##
 # @ChardevSocket:
 #
 # Configuration info for (stream) socket chardevs.
 #
 # @addr: socket address to listen on (server=true) or connect to
 #     (server=false)
 #
 # @tls-creds: the ID of the TLS credentials object (since 2.6)
 #
 # @tls-authz: the ID of the QAuthZ authorization object against which
 #     the client's x509 distinguished name will be validated.  This
 #     object is only resolved at time of use, so can be deleted and
 #     recreated on the fly while the chardev server is active.  If
 #     missing, it will default to denying access (since 4.0)
 #
 # @server: create server socket (default: true)
 #
 # @wait: wait for incoming connection on server sockets (default:
 #     false). Silently ignored with server: false.  This use is
 #     deprecated.
 #
 # @nodelay: set TCP_NODELAY socket option (default: false)
 #
 # @telnet: enable telnet protocol on server sockets (default: false)
 #
 # @tn3270: enable tn3270 protocol on server sockets (default: false)
 #     (Since: 2.10)
 #
 # @websocket: enable websocket protocol on server sockets
 #     (default: false) (Since: 3.1)
 #
 # @reconnect: For a client socket, if a socket is disconnected, then
 #     attempt a reconnect after the given number of seconds.  Setting
 #     this to zero disables this function.  (default: 0) (Since: 2.2)
 #
 # Since: 1.4
 ##
 { 'struct': 'ChardevSocket',
   'data': { 'addr': 'SocketAddressLegacy',
             '*tls-creds': 'str',
             '*tls-authz'  : 'str',
             '*server': 'bool',
             '*wait': 'bool',
             '*nodelay': 'bool',
             '*telnet': 'bool',
             '*tn3270': 'bool',
             '*websocket': 'bool',
             '*reconnect': 'int' },
   'base': 'ChardevCommon' }

 ##
 # @ChardevUdp:
 #
 # Configuration info for datagram socket chardevs.
 #
 # @remote: remote address
 #
 # @local: local address
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevUdp',
   'data': { 'remote': 'SocketAddressLegacy',
             '*local': 'SocketAddressLegacy' },
   'base': 'ChardevCommon' }

 ##
 # @ChardevMux:
 #
 # Configuration info for mux chardevs.
 #
 # @chardev: name of the base chardev.
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevMux',
   'data': { 'chardev': 'str' },
   'base': 'ChardevCommon' }

 ##
 # @ChardevStdio:
 #
 # Configuration info for stdio chardevs.
 #
 # @signal: Allow signals (such as SIGINT triggered by ^C) be delivered
 #     to qemu.  Default: true.
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevStdio',
   'data': { '*signal': 'bool' },
   'base': 'ChardevCommon' }

 ##
 # @ChardevSpiceChannel:
 #
 # Configuration info for spice vm channel chardevs.
 #
 # @type: kind of channel (for example vdagent).
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevSpiceChannel',
   'data': { 'type': 'str' },
   'base': 'ChardevCommon',
   'if': 'CONFIG_SPICE' }

 ##
 # @ChardevSpicePort:
 #
 # Configuration info for spice port chardevs.
 #
 # @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevSpicePort',
   'data': { 'fqdn': 'str' },
   'base': 'ChardevCommon',
   'if': 'CONFIG_SPICE' }

 ##
 # @ChardevDBus:
 #
 # Configuration info for DBus chardevs.
 #
 # @name: name of the channel (following docs/spice-port-fqdn.txt)
 #
 # Since: 7.0
 ##
 { 'struct': 'ChardevDBus',
   'data': { 'name': 'str' },
   'base': 'ChardevCommon',
   'if': 'CONFIG_DBUS_DISPLAY' }

 ##
 # @ChardevVC:
 #
 # Configuration info for virtual console chardevs.
 #
 # @width: console width, in pixels
 #
 # @height: console height, in pixels
 #
 # @cols: console width, in chars
 #
 # @rows: console height, in chars
 #
 # Note: the options are only effective when the VNC or SDL graphical
 # display backend is active. They are ignored with the GTK, Spice, VNC
 # and D-Bus display backends.
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevVC',
   'data': { '*width': 'int',
             '*height': 'int',
             '*cols': 'int',
             '*rows': 'int' },
   'base': 'ChardevCommon' }

 ##
 # @ChardevRingbuf:
 #
 # Configuration info for ring buffer chardevs.
 #
 # @size: ring buffer size, must be power of two, default is 65536
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevRingbuf',
   'data': { '*size': 'int' },
   'base': 'ChardevCommon' }

 ##
 # @ChardevQemuVDAgent:
 #
 # Configuration info for qemu vdagent implementation.
 #
 # @mouse: enable/disable mouse, default is enabled.
 #
 # @clipboard: enable/disable clipboard, default is disabled.
 #
 # Since: 6.1
 ##
 { 'struct': 'ChardevQemuVDAgent',
   'data': { '*mouse': 'bool',
             '*clipboard': 'bool' },
   'base': 'ChardevCommon',
   'if': 'CONFIG_SPICE_PROTOCOL' }

 ##
 # @ChardevBackendKind:
 #
 # @pipe: Since 1.5
 #
 # @udp: Since 1.5
 #
 # @mux: Since 1.5
 #
 # @msmouse: Since 1.5
 #
 # @wctablet: Since 2.9
 #
 # @braille: Since 1.5
 #
 # @testdev: Since 2.2
 #
 # @stdio: Since 1.5
 #
 # @console: Since 1.5
 #
 # @spicevmc: Since 1.5
 #
 # @spiceport: Since 1.5
 #
 # @qemu-vdagent: Since 6.1
 #
 # @dbus: Since 7.0
 #
 # @vc: v1.5
 #
 # @ringbuf: Since 1.6
 #
 # @memory: Since 1.5
 #
 # Since: 1.4
 ##
 { 'enum': 'ChardevBackendKind',
   'data': [ 'file',
             'serial',
             'parallel',
             'pipe',
             'socket',
             'udp',
             'pty',
             'null',
             'mux',
             'msmouse',
             'wctablet',
             'braille',
             'testdev',
             'stdio',
             'console',
             { 'name': 'spicevmc', 'if': 'CONFIG_SPICE' },
             { 'name': 'spiceport', 'if': 'CONFIG_SPICE' },
             { 'name': 'qemu-vdagent', 'if': 'CONFIG_SPICE_PROTOCOL' },
             { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' },
             'vc',
             'ringbuf',
             # next one is just for compatibility
             'memory' ] }

 ##
 # @ChardevFileWrapper:
 #
 # Since: 1.4
 ##
 { 'struct': 'ChardevFileWrapper',
   'data': { 'data': 'ChardevFile' } }

 ##
 # @ChardevHostdevWrapper:
 #
 # Since: 1.4
 ##
 { 'struct': 'ChardevHostdevWrapper',
   'data': { 'data': 'ChardevHostdev' } }

 ##
 # @ChardevSocketWrapper:
 #
 # Since: 1.4
 ##
 { 'struct': 'ChardevSocketWrapper',
   'data': { 'data': 'ChardevSocket' } }

 ##
 # @ChardevUdpWrapper:
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevUdpWrapper',
   'data': { 'data': 'ChardevUdp' } }

 ##
 # @ChardevCommonWrapper:
 #
 # Since: 2.6
 ##
 { 'struct': 'ChardevCommonWrapper',
   'data': { 'data': 'ChardevCommon' } }

 ##
 # @ChardevMuxWrapper:
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevMuxWrapper',
   'data': { 'data': 'ChardevMux' } }

 ##
 # @ChardevStdioWrapper:
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevStdioWrapper',
   'data': { 'data': 'ChardevStdio' } }

 ##
 # @ChardevSpiceChannelWrapper:
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevSpiceChannelWrapper',
   'data': { 'data': 'ChardevSpiceChannel' },
   'if': 'CONFIG_SPICE' }

 ##
 # @ChardevSpicePortWrapper:
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevSpicePortWrapper',
   'data': { 'data': 'ChardevSpicePort' },
   'if': 'CONFIG_SPICE' }

 ##
 # @ChardevQemuVDAgentWrapper:
 #
 # Since: 6.1
 ##
 { 'struct': 'ChardevQemuVDAgentWrapper',
   'data': { 'data': 'ChardevQemuVDAgent' },
   'if': 'CONFIG_SPICE_PROTOCOL' }

 ##
 # @ChardevDBusWrapper:
 #
 # Since: 7.0
 ##
 { 'struct': 'ChardevDBusWrapper',
   'data': { 'data': 'ChardevDBus' },
   'if': 'CONFIG_DBUS_DISPLAY' }

 ##
 # @ChardevVCWrapper:
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevVCWrapper',
   'data': { 'data': 'ChardevVC' } }

 ##
 # @ChardevRingbufWrapper:
 #
 # Since: 1.5
 ##
 { 'struct': 'ChardevRingbufWrapper',
   'data': { 'data': 'ChardevRingbuf' } }

 ##
 # @ChardevBackend:
 #
 # Configuration info for the new chardev backend.
 #
 # Since: 1.4
 ##
 { 'union': 'ChardevBackend',
   'base': { 'type': 'ChardevBackendKind' },
   'discriminator': 'type',
   'data': { 'file': 'ChardevFileWrapper',
             'serial': 'ChardevHostdevWrapper',
             'parallel': 'ChardevHostdevWrapper',
             'pipe': 'ChardevHostdevWrapper',
             'socket': 'ChardevSocketWrapper',
             'udp': 'ChardevUdpWrapper',
             'pty': 'ChardevCommonWrapper',
             'null': 'ChardevCommonWrapper',
             'mux': 'ChardevMuxWrapper',
             'msmouse': 'ChardevCommonWrapper',
             'wctablet': 'ChardevCommonWrapper',
             'braille': 'ChardevCommonWrapper',
             'testdev': 'ChardevCommonWrapper',
             'stdio': 'ChardevStdioWrapper',
             'console': 'ChardevCommonWrapper',
             'spicevmc': { 'type': 'ChardevSpiceChannelWrapper',
                           'if': 'CONFIG_SPICE' },
             'spiceport': { 'type': 'ChardevSpicePortWrapper',
                            'if': 'CONFIG_SPICE' },
             'qemu-vdagent': { 'type': 'ChardevQemuVDAgentWrapper',
                               'if': 'CONFIG_SPICE_PROTOCOL' },
             'dbus': { 'type': 'ChardevDBusWrapper',
                       'if': 'CONFIG_DBUS_DISPLAY' },
             'vc': 'ChardevVCWrapper',
             'ringbuf': 'ChardevRingbufWrapper',
             # next one is just for compatibility
             'memory': 'ChardevRingbufWrapper' } }

 ##
 # @ChardevReturn:
 #
 # Return info about the chardev backend just created.
 #
 # @pty: name of the slave pseudoterminal device, present if and only
 #     if a chardev of type 'pty' was created
 #
 # Since: 1.4
 ##
 { 'struct' : 'ChardevReturn',
   'data': { '*pty': 'str' } }

 ##
 # @chardev-add:
 #
 # Add a character device backend
 #
 # @id: the chardev's ID, must be unique
 #
 # @backend: backend type and parameters
 #
 # Returns: ChardevReturn.
 #
 # Since: 1.4
 #
 # Examples:
 #
 # -> { "execute" : "chardev-add",
 #      "arguments" : { "id" : "foo",
 #                      "backend" : { "type" : "null", "data" : {} } } }
 # <- { "return": {} }
 #
 # -> { "execute" : "chardev-add",
 #      "arguments" : { "id" : "bar",
 #                      "backend" : { "type" : "file",
 #                                    "data" : { "out" : "/tmp/bar.log" } } } }
 # <- { "return": {} }
 #
 # -> { "execute" : "chardev-add",
 #      "arguments" : { "id" : "baz",
 #                      "backend" : { "type" : "pty", "data" : {} } } }
 # <- { "return": { "pty" : "/dev/pty/42" } }
 ##
 { 'command': 'chardev-add',
   'data': { 'id': 'str',
             'backend': 'ChardevBackend' },
   'returns': 'ChardevReturn' }

 ##
 # @chardev-change:
 #
 # Change a character device backend
 #
 # @id: the chardev's ID, must exist
 #
 # @backend: new backend type and parameters
 #
 # Returns: ChardevReturn.
 #
 # Since: 2.10
 #
 # Examples:
 #
 # -> { "execute" : "chardev-change",
 #      "arguments" : { "id" : "baz",
 #                      "backend" : { "type" : "pty", "data" : {} } } }
 # <- { "return": { "pty" : "/dev/pty/42" } }
 #
 # -> {"execute" : "chardev-change",
 #     "arguments" : {
 #         "id" : "charchannel2",
 #         "backend" : {
 #             "type" : "socket",
 #             "data" : {
 #                 "addr" : {
 #                     "type" : "unix" ,
 #                     "data" : {
 #                         "path" : "/tmp/charchannel2.socket"
 #                     }
 #                  },
 #                  "server" : true,
 #                  "wait" : false }}}}
 # <- {"return": {}}
 ##
 { 'command': 'chardev-change',
   'data': { 'id': 'str',
             'backend': 'ChardevBackend' },
   'returns': 'ChardevReturn' }

 ##
 # @chardev-remove:
 #
 # Remove a character device backend
 #
 # @id: the chardev's ID, must exist and not be in use
 #
 # Returns: Nothing on success
 #
 # Since: 1.4
 #
 # Example:
 #
 # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
 # <- { "return": {} }
 ##
 { 'command': 'chardev-remove',
   'data': { 'id': 'str' } }

 ##
 # @chardev-send-break:
 #
 # Send a break to a character device
 #
 # @id: the chardev's ID, must exist
 #
 # Returns: Nothing on success
 #
 # Since: 2.10
 #
 # Example:
 #
 # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
 # <- { "return": {} }
 ##
 { 'command': 'chardev-send-break',
   'data': { 'id': 'str' } }

 ##
 # @VSERPORT_CHANGE:
 #
 # Emitted when the guest opens or closes a virtio-serial port.
 #
 # @id: device identifier of the virtio-serial port
 #
 # @open: true if the guest has opened the virtio-serial port
 #
 # Note: This event is rate-limited.
 #
 # Since: 2.1
 #
 # Example:
 #
 # <- { "event": "VSERPORT_CHANGE",
 #      "data": { "id": "channel0", "open": true },
 #      "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
 ##
 { 'event': 'VSERPORT_CHANGE',
   'data': { 'id': 'str',
             'open': 'bool' } }
	# -- Mode: Python --
	# vim: filetype=python
	#

	##
	# = Character devices
	##

	{ 'include': 'sockets.json' }

	##
	# @ChardevInfo:
	#
	# Information about a character device.
	#
	# @label: the label of the character device
	#
	# @filename: the filename of the character device
	#
	# @frontend-open: shows whether the frontend device attached to this
	# backend (e.g. with the chardev=... option) is in open or closed
	# state (since 2.1)
	#
	# Notes: @filename is encoded using the QEMU command line character
	# device encoding. See the QEMU man page for details.
	#
	# Since: 0.14
	##
	{ 'struct': 'ChardevInfo',
	'data': { 'label': 'str',
	'filename': 'str',
	'frontend-open': 'bool' } }

	##
	# @query-chardev:
	#
	# Returns information about current character devices.
	#
	# Returns: a list of @ChardevInfo
	#
	# Since: 0.14
	#
	# Example:
	#
	# -> { "execute": "query-chardev" }
	# <- {
	# "return": [
	# {
	# "label": "charchannel0",
	# "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
	# "frontend-open": false
	# },
	# {
	# "label": "charmonitor",
	# "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
	# "frontend-open": true
	# },
	# {
	# "label": "charserial0",
	# "filename": "pty:/dev/pts/2",
	# "frontend-open": true
	# }
	# ]
	# }
	##
	{ 'command': 'query-chardev', 'returns': ['ChardevInfo'],
	'allow-preconfig': true }

	##
	# @ChardevBackendInfo:
	#
	# Information about a character device backend
	#
	# @name: The backend name
	#
	# Since: 2.0
	##
	{ 'struct': 'ChardevBackendInfo', 'data': {'name': 'str'} }

	##
	# @query-chardev-backends:
	#
	# Returns information about character device backends.
	#
	# Returns: a list of @ChardevBackendInfo
	#
	# Since: 2.0
	#
	# Example:
	#
	# -> { "execute": "query-chardev-backends" }
	# <- {
	# "return":[
	# {
	# "name":"udp"
	# },
	# {
	# "name":"tcp"
	# },
	# {
	# "name":"unix"
	# },
	# {
	# "name":"spiceport"
	# }
	# ]
	# }
	##
	{ 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }

	##
	# @DataFormat:
	#
	# An enumeration of data format.
	#
	# @utf8: Data is a UTF-8 string (RFC 3629)
	#
	# @base64: Data is Base64 encoded binary (RFC 3548)
	#
	# Since: 1.4
	##
	{ 'enum': 'DataFormat',
	'data': [ 'utf8', 'base64' ] }

	##
	# @ringbuf-write:
	#
	# Write to a ring buffer character device.
	#
	# @device: the ring buffer character device name
	#
	# @data: data to write
	#
	# @format: data encoding (default 'utf8').
	#
	# - base64: data must be base64 encoded text. Its binary decoding
	# gets written.
	# - utf8: data's UTF-8 encoding is written
	# - data itself is always Unicode regardless of format, like any
	# other string.
	#
	# Returns: Nothing on success
	#
	# Since: 1.4
	#
	# Example:
	#
	# -> { "execute": "ringbuf-write",
	# "arguments": { "device": "foo",
	# "data": "abcdefgh",
	# "format": "utf8" } }
	# <- { "return": {} }
	##
	{ 'command': 'ringbuf-write',
	'data': { 'device': 'str',
	'data': 'str',
	'*format': 'DataFormat'} }

	##
	# @ringbuf-read:
	#
	# Read from a ring buffer character device.
	#
	# @device: the ring buffer character device name
	#
	# @size: how many bytes to read at most
	#
	# @format: data encoding (default 'utf8').
	#
	# - base64: the data read is returned in base64 encoding.
	# - utf8: the data read is interpreted as UTF-8.
	# Bug: can screw up when the buffer contains invalid UTF-8
	# sequences, NUL characters, after the ring buffer lost data,
	# and when reading stops because the size limit is reached.
	# - The return value is always Unicode regardless of format, like
	# any other string.
	#
	# Returns: data read from the device
	#
	# Since: 1.4
	#
	# Example:
	#
	# -> { "execute": "ringbuf-read",
	# "arguments": { "device": "foo",
	# "size": 1000,
	# "format": "utf8" } }
	# <- { "return": "abcdefgh" }
	##
	{ 'command': 'ringbuf-read',
	'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
	'returns': 'str' }

	##
	# @ChardevCommon:
	#
	# Configuration shared across all chardev backends
	#
	# @logfile: The name of a logfile to save output
	#
	# @logappend: true to append instead of truncate (default to false to
	# truncate)
	#
	# Since: 2.6
	##
	{ 'struct': 'ChardevCommon',
	'data': { '*logfile': 'str',
	'*logappend': 'bool' } }

	##
	# @ChardevFile:
	#
	# Configuration info for file chardevs.
	#
	# @in: The name of the input file
	#
	# @out: The name of the output file
	#
	# @append: Open the file in append mode (default false to truncate)
	# (Since 2.6)
	#
	# Since: 1.4
	##
	{ 'struct': 'ChardevFile',
	'data': { '*in': 'str',
	'out': 'str',
	'*append': 'bool' },
	'base': 'ChardevCommon' }

	##
	# @ChardevHostdev:
	#
	# Configuration info for device and pipe chardevs.
	#
	# @device: The name of the special file for the device, i.e.
	# /dev/ttyS0 on Unix or COM1: on Windows
	#
	# Since: 1.4
	##
	{ 'struct': 'ChardevHostdev',
	'data': { 'device': 'str' },
	'base': 'ChardevCommon' }

	##
	# @ChardevSocket:
	#
	# Configuration info for (stream) socket chardevs.
	#
	# @addr: socket address to listen on (server=true) or connect to
	# (server=false)
	#
	# @tls-creds: the ID of the TLS credentials object (since 2.6)
	#
	# @tls-authz: the ID of the QAuthZ authorization object against which
	# the client's x509 distinguished name will be validated. This
	# object is only resolved at time of use, so can be deleted and
	# recreated on the fly while the chardev server is active. If
	# missing, it will default to denying access (since 4.0)
	#
	# @server: create server socket (default: true)
	#
	# @wait: wait for incoming connection on server sockets (default:
	# false). Silently ignored with server: false. This use is
	# deprecated.
	#
	# @nodelay: set TCP_NODELAY socket option (default: false)
	#
	# @telnet: enable telnet protocol on server sockets (default: false)
	#
	# @tn3270: enable tn3270 protocol on server sockets (default: false)
	# (Since: 2.10)
	#
	# @websocket: enable websocket protocol on server sockets
	# (default: false) (Since: 3.1)
	#
	# @reconnect: For a client socket, if a socket is disconnected, then
	# attempt a reconnect after the given number of seconds. Setting
	# this to zero disables this function. (default: 0) (Since: 2.2)
	#
	# Since: 1.4
	##
	{ 'struct': 'ChardevSocket',
	'data': { 'addr': 'SocketAddressLegacy',
	'*tls-creds': 'str',
	'*tls-authz' : 'str',
	'*server': 'bool',
	'*wait': 'bool',
	'*nodelay': 'bool',
	'*telnet': 'bool',
	'*tn3270': 'bool',
	'*websocket': 'bool',
	'*reconnect': 'int' },
	'base': 'ChardevCommon' }

	##
	# @ChardevUdp:
	#
	# Configuration info for datagram socket chardevs.
	#
	# @remote: remote address
	#
	# @local: local address
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevUdp',
	'data': { 'remote': 'SocketAddressLegacy',
	'*local': 'SocketAddressLegacy' },
	'base': 'ChardevCommon' }

	##
	# @ChardevMux:
	#
	# Configuration info for mux chardevs.
	#
	# @chardev: name of the base chardev.
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevMux',
	'data': { 'chardev': 'str' },
	'base': 'ChardevCommon' }

	##
	# @ChardevStdio:
	#
	# Configuration info for stdio chardevs.
	#
	# @signal: Allow signals (such as SIGINT triggered by ^C) be delivered
	# to qemu. Default: true.
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevStdio',
	'data': { '*signal': 'bool' },
	'base': 'ChardevCommon' }

	##
	# @ChardevSpiceChannel:
	#
	# Configuration info for spice vm channel chardevs.
	#
	# @type: kind of channel (for example vdagent).
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevSpiceChannel',
	'data': { 'type': 'str' },
	'base': 'ChardevCommon',
	'if': 'CONFIG_SPICE' }

	##
	# @ChardevSpicePort:
	#
	# Configuration info for spice port chardevs.
	#
	# @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevSpicePort',
	'data': { 'fqdn': 'str' },
	'base': 'ChardevCommon',
	'if': 'CONFIG_SPICE' }

	##
	# @ChardevDBus:
	#
	# Configuration info for DBus chardevs.
	#
	# @name: name of the channel (following docs/spice-port-fqdn.txt)
	#
	# Since: 7.0
	##
	{ 'struct': 'ChardevDBus',
	'data': { 'name': 'str' },
	'base': 'ChardevCommon',
	'if': 'CONFIG_DBUS_DISPLAY' }

	##
	# @ChardevVC:
	#
	# Configuration info for virtual console chardevs.
	#
	# @width: console width, in pixels
	#
	# @height: console height, in pixels
	#
	# @cols: console width, in chars
	#
	# @rows: console height, in chars
	#
	# Note: the options are only effective when the VNC or SDL graphical
	# display backend is active. They are ignored with the GTK, Spice, VNC
	# and D-Bus display backends.
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevVC',
	'data': { '*width': 'int',
	'*height': 'int',
	'*cols': 'int',
	'*rows': 'int' },
	'base': 'ChardevCommon' }

	##
	# @ChardevRingbuf:
	#
	# Configuration info for ring buffer chardevs.
	#
	# @size: ring buffer size, must be power of two, default is 65536
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevRingbuf',
	'data': { '*size': 'int' },
	'base': 'ChardevCommon' }

	##
	# @ChardevQemuVDAgent:
	#
	# Configuration info for qemu vdagent implementation.
	#
	# @mouse: enable/disable mouse, default is enabled.
	#
	# @clipboard: enable/disable clipboard, default is disabled.
	#
	# Since: 6.1
	##
	{ 'struct': 'ChardevQemuVDAgent',
	'data': { '*mouse': 'bool',
	'*clipboard': 'bool' },
	'base': 'ChardevCommon',
	'if': 'CONFIG_SPICE_PROTOCOL' }

	##
	# @ChardevBackendKind:
	#
	# @pipe: Since 1.5
	#
	# @udp: Since 1.5
	#
	# @mux: Since 1.5
	#
	# @msmouse: Since 1.5
	#
	# @wctablet: Since 2.9
	#
	# @braille: Since 1.5
	#
	# @testdev: Since 2.2
	#
	# @stdio: Since 1.5
	#
	# @console: Since 1.5
	#
	# @spicevmc: Since 1.5
	#
	# @spiceport: Since 1.5
	#
	# @qemu-vdagent: Since 6.1
	#
	# @dbus: Since 7.0
	#
	# @vc: v1.5
	#
	# @ringbuf: Since 1.6
	#
	# @memory: Since 1.5
	#
	# Since: 1.4
	##
	{ 'enum': 'ChardevBackendKind',
	'data': [ 'file',
	'serial',
	'parallel',
	'pipe',
	'socket',
	'udp',
	'pty',
	'null',
	'mux',
	'msmouse',
	'wctablet',
	'braille',
	'testdev',
	'stdio',
	'console',
	{ 'name': 'spicevmc', 'if': 'CONFIG_SPICE' },
	{ 'name': 'spiceport', 'if': 'CONFIG_SPICE' },
	{ 'name': 'qemu-vdagent', 'if': 'CONFIG_SPICE_PROTOCOL' },
	{ 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' },
	'vc',
	'ringbuf',
	# next one is just for compatibility
	'memory' ] }

	##
	# @ChardevFileWrapper:
	#
	# Since: 1.4
	##
	{ 'struct': 'ChardevFileWrapper',
	'data': { 'data': 'ChardevFile' } }

	##
	# @ChardevHostdevWrapper:
	#
	# Since: 1.4
	##
	{ 'struct': 'ChardevHostdevWrapper',
	'data': { 'data': 'ChardevHostdev' } }

	##
	# @ChardevSocketWrapper:
	#
	# Since: 1.4
	##
	{ 'struct': 'ChardevSocketWrapper',
	'data': { 'data': 'ChardevSocket' } }

	##
	# @ChardevUdpWrapper:
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevUdpWrapper',
	'data': { 'data': 'ChardevUdp' } }

	##
	# @ChardevCommonWrapper:
	#
	# Since: 2.6
	##
	{ 'struct': 'ChardevCommonWrapper',
	'data': { 'data': 'ChardevCommon' } }

	##
	# @ChardevMuxWrapper:
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevMuxWrapper',
	'data': { 'data': 'ChardevMux' } }

	##
	# @ChardevStdioWrapper:
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevStdioWrapper',
	'data': { 'data': 'ChardevStdio' } }

	##
	# @ChardevSpiceChannelWrapper:
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevSpiceChannelWrapper',
	'data': { 'data': 'ChardevSpiceChannel' },
	'if': 'CONFIG_SPICE' }

	##
	# @ChardevSpicePortWrapper:
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevSpicePortWrapper',
	'data': { 'data': 'ChardevSpicePort' },
	'if': 'CONFIG_SPICE' }

	##
	# @ChardevQemuVDAgentWrapper:
	#
	# Since: 6.1
	##
	{ 'struct': 'ChardevQemuVDAgentWrapper',
	'data': { 'data': 'ChardevQemuVDAgent' },
	'if': 'CONFIG_SPICE_PROTOCOL' }

	##
	# @ChardevDBusWrapper:
	#
	# Since: 7.0
	##
	{ 'struct': 'ChardevDBusWrapper',
	'data': { 'data': 'ChardevDBus' },
	'if': 'CONFIG_DBUS_DISPLAY' }

	##
	# @ChardevVCWrapper:
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevVCWrapper',
	'data': { 'data': 'ChardevVC' } }

	##
	# @ChardevRingbufWrapper:
	#
	# Since: 1.5
	##
	{ 'struct': 'ChardevRingbufWrapper',
	'data': { 'data': 'ChardevRingbuf' } }

	##
	# @ChardevBackend:
	#
	# Configuration info for the new chardev backend.
	#
	# Since: 1.4
	##
	{ 'union': 'ChardevBackend',
	'base': { 'type': 'ChardevBackendKind' },
	'discriminator': 'type',
	'data': { 'file': 'ChardevFileWrapper',
	'serial': 'ChardevHostdevWrapper',
	'parallel': 'ChardevHostdevWrapper',
	'pipe': 'ChardevHostdevWrapper',
	'socket': 'ChardevSocketWrapper',
	'udp': 'ChardevUdpWrapper',
	'pty': 'ChardevCommonWrapper',
	'null': 'ChardevCommonWrapper',
	'mux': 'ChardevMuxWrapper',
	'msmouse': 'ChardevCommonWrapper',
	'wctablet': 'ChardevCommonWrapper',
	'braille': 'ChardevCommonWrapper',
	'testdev': 'ChardevCommonWrapper',
	'stdio': 'ChardevStdioWrapper',
	'console': 'ChardevCommonWrapper',
	'spicevmc': { 'type': 'ChardevSpiceChannelWrapper',
	'if': 'CONFIG_SPICE' },
	'spiceport': { 'type': 'ChardevSpicePortWrapper',
	'if': 'CONFIG_SPICE' },
	'qemu-vdagent': { 'type': 'ChardevQemuVDAgentWrapper',
	'if': 'CONFIG_SPICE_PROTOCOL' },
	'dbus': { 'type': 'ChardevDBusWrapper',
	'if': 'CONFIG_DBUS_DISPLAY' },
	'vc': 'ChardevVCWrapper',
	'ringbuf': 'ChardevRingbufWrapper',
	# next one is just for compatibility
	'memory': 'ChardevRingbufWrapper' } }

	##
	# @ChardevReturn:
	#
	# Return info about the chardev backend just created.
	#
	# @pty: name of the slave pseudoterminal device, present if and only
	# if a chardev of type 'pty' was created
	#
	# Since: 1.4
	##
	{ 'struct' : 'ChardevReturn',
	'data': { '*pty': 'str' } }

	##
	# @chardev-add:
	#
	# Add a character device backend
	#
	# @id: the chardev's ID, must be unique
	#
	# @backend: backend type and parameters
	#
	# Returns: ChardevReturn.
	#
	# Since: 1.4
	#
	# Examples:
	#
	# -> { "execute" : "chardev-add",
	# "arguments" : { "id" : "foo",
	# "backend" : { "type" : "null", "data" : {} } } }
	# <- { "return": {} }
	#
	# -> { "execute" : "chardev-add",
	# "arguments" : { "id" : "bar",
	# "backend" : { "type" : "file",
	# "data" : { "out" : "/tmp/bar.log" } } } }
	# <- { "return": {} }
	#
	# -> { "execute" : "chardev-add",
	# "arguments" : { "id" : "baz",
	# "backend" : { "type" : "pty", "data" : {} } } }
	# <- { "return": { "pty" : "/dev/pty/42" } }
	##
	{ 'command': 'chardev-add',
	'data': { 'id': 'str',
	'backend': 'ChardevBackend' },
	'returns': 'ChardevReturn' }

	##
	# @chardev-change:
	#
	# Change a character device backend
	#
	# @id: the chardev's ID, must exist
	#
	# @backend: new backend type and parameters
	#
	# Returns: ChardevReturn.
	#
	# Since: 2.10
	#
	# Examples:
	#
	# -> { "execute" : "chardev-change",
	# "arguments" : { "id" : "baz",
	# "backend" : { "type" : "pty", "data" : {} } } }
	# <- { "return": { "pty" : "/dev/pty/42" } }
	#
	# -> {"execute" : "chardev-change",
	# "arguments" : {
	# "id" : "charchannel2",
	# "backend" : {
	# "type" : "socket",
	# "data" : {
	# "addr" : {
	# "type" : "unix" ,
	# "data" : {
	# "path" : "/tmp/charchannel2.socket"
	# }
	# },
	# "server" : true,
	# "wait" : false }}}}
	# <- {"return": {}}
	##
	{ 'command': 'chardev-change',
	'data': { 'id': 'str',
	'backend': 'ChardevBackend' },
	'returns': 'ChardevReturn' }

	##
	# @chardev-remove:
	#
	# Remove a character device backend
	#
	# @id: the chardev's ID, must exist and not be in use
	#
	# Returns: Nothing on success
	#
	# Since: 1.4
	#
	# Example:
	#
	# -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
	# <- { "return": {} }
	##
	{ 'command': 'chardev-remove',
	'data': { 'id': 'str' } }

	##
	# @chardev-send-break:
	#
	# Send a break to a character device
	#
	# @id: the chardev's ID, must exist
	#
	# Returns: Nothing on success
	#
	# Since: 2.10
	#
	# Example:
	#
	# -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
	# <- { "return": {} }
	##
	{ 'command': 'chardev-send-break',
	'data': { 'id': 'str' } }

	##
	# @VSERPORT_CHANGE:
	#
	# Emitted when the guest opens or closes a virtio-serial port.
	#
	# @id: device identifier of the virtio-serial port
	#
	# @open: true if the guest has opened the virtio-serial port
	#
	# Note: This event is rate-limited.
	#
	# Since: 2.1
	#
	# Example:
	#
	# <- { "event": "VSERPORT_CHANGE",
	# "data": { "id": "channel0", "open": true },
	# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
	##
	{ 'event': 'VSERPORT_CHANGE',
	'data': { 'id': 'str',
	'open': 'bool' } }