Merge tag 'qemu-macppc-20230206' of https://github.com/mcayland/qemu into staging
[qemu/rayw.git] / qapi / char.json
blob923dc5056d78d3c9f90ab4f84ba1b03a3d7e01d7
1 # -*- Mode: Python -*-
2 # vim: filetype=python
5 ##
6 # = Character devices
7 ##
9 { 'include': 'sockets.json' }
12 # @ChardevInfo:
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 backend
21 #                 (eg. with the chardev=... option) is in open or closed state
22 #                 (since 2.1)
24 # Notes: @filename is encoded using the QEMU command line character device
25 #        encoding.  See the QEMU man page for details.
27 # Since: 0.14
29 { 'struct': 'ChardevInfo',
30   'data': { 'label': 'str',
31             'filename': 'str',
32             'frontend-open': 'bool' } }
35 # @query-chardev:
37 # Returns information about current character devices.
39 # Returns: a list of @ChardevInfo
41 # Since: 0.14
43 # Example:
45 # -> { "execute": "query-chardev" }
46 # <- {
47 #       "return": [
48 #          {
49 #             "label": "charchannel0",
50 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
51 #             "frontend-open": false
52 #          },
53 #          {
54 #             "label": "charmonitor",
55 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
56 #             "frontend-open": true
57 #          },
58 #          {
59 #             "label": "charserial0",
60 #             "filename": "pty:/dev/pts/2",
61 #             "frontend-open": true
62 #          }
63 #       ]
64 #    }
67 { 'command': 'query-chardev', 'returns': ['ChardevInfo'],
68   'allow-preconfig': true }
71 # @ChardevBackendInfo:
73 # Information about a character device backend
75 # @name: The backend name
77 # Since: 2.0
79 { 'struct': 'ChardevBackendInfo', 'data': {'name': 'str'} }
82 # @query-chardev-backends:
84 # Returns information about character device backends.
86 # Returns: a list of @ChardevBackendInfo
88 # Since: 2.0
90 # Example:
92 # -> { "execute": "query-chardev-backends" }
93 # <- {
94 #       "return":[
95 #          {
96 #             "name":"udp"
97 #          },
98 #          {
99 #             "name":"tcp"
100 #          },
101 #          {
102 #             "name":"unix"
103 #          },
104 #          {
105 #             "name":"spiceport"
106 #          }
107 #       ]
108 #    }
111 { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
114 # @DataFormat:
116 # An enumeration of data format.
118 # @utf8: Data is a UTF-8 string (RFC 3629)
120 # @base64: Data is Base64 encoded binary (RFC 3548)
122 # Since: 1.4
124 { 'enum': 'DataFormat',
125   'data': [ 'utf8', 'base64' ] }
128 # @ringbuf-write:
130 # Write to a ring buffer character device.
132 # @device: the ring buffer character device name
134 # @data: data to write
136 # @format: data encoding (default 'utf8').
138 #          - base64: data must be base64 encoded text.  Its binary
139 #            decoding gets written.
140 #          - utf8: data's UTF-8 encoding is written
141 #          - data itself is always Unicode regardless of format, like
142 #            any other string.
144 # Returns: Nothing on success
146 # Since: 1.4
148 # Example:
150 # -> { "execute": "ringbuf-write",
151 #      "arguments": { "device": "foo",
152 #                     "data": "abcdefgh",
153 #                     "format": "utf8" } }
154 # <- { "return": {} }
157 { 'command': 'ringbuf-write',
158   'data': { 'device': 'str',
159             'data': 'str',
160            '*format': 'DataFormat'} }
163 # @ringbuf-read:
165 # Read from a ring buffer character device.
167 # @device: the ring buffer character device name
169 # @size: how many bytes to read at most
171 # @format: data encoding (default 'utf8').
173 #          - base64: the data read is returned in base64 encoding.
174 #          - utf8: the data read is interpreted as UTF-8.
175 #            Bug: can screw up when the buffer contains invalid UTF-8
176 #            sequences, NUL characters, after the ring buffer lost
177 #            data, and when reading stops because the size limit is
178 #            reached.
179 #          - The return value is always Unicode regardless of format,
180 #            like any other string.
182 # Returns: data read from the device
184 # Since: 1.4
186 # Example:
188 # -> { "execute": "ringbuf-read",
189 #      "arguments": { "device": "foo",
190 #                     "size": 1000,
191 #                     "format": "utf8" } }
192 # <- { "return": "abcdefgh" }
195 { 'command': 'ringbuf-read',
196   'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
197   'returns': 'str' }
200 # @ChardevCommon:
202 # Configuration shared across all chardev backends
204 # @logfile: The name of a logfile to save output
205 # @logappend: true to append instead of truncate
206 #             (default to false to truncate)
208 # Since: 2.6
210 { 'struct': 'ChardevCommon',
211   'data': { '*logfile': 'str',
212             '*logappend': 'bool' } }
215 # @ChardevFile:
217 # Configuration info for file chardevs.
219 # @in: The name of the input file
220 # @out: The name of the output file
221 # @append: Open the file in append mode (default false to
222 #          truncate) (Since 2.6)
224 # Since: 1.4
226 { 'struct': 'ChardevFile',
227   'data': { '*in': 'str',
228             'out': 'str',
229             '*append': 'bool' },
230   'base': 'ChardevCommon' }
233 # @ChardevHostdev:
235 # Configuration info for device and pipe chardevs.
237 # @device: The name of the special file for the device,
238 #          i.e. /dev/ttyS0 on Unix or COM1: on Windows
240 # Since: 1.4
242 { 'struct': 'ChardevHostdev',
243   'data': { 'device': 'str' },
244   'base': 'ChardevCommon' }
247 # @ChardevSocket:
249 # Configuration info for (stream) socket chardevs.
251 # @addr: socket address to listen on (server=true)
252 #        or connect to (server=false)
253 # @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
257 #             and recreated on the fly while the chardev server is active.
258 #             If missing, it will default to denying access (since 4.0)
259 # @server: create server socket (default: true)
260 # @wait: wait for incoming connection on server
261 #        sockets (default: false).
262 #        Silently ignored with server: false.  This use is deprecated.
263 # @nodelay: set TCP_NODELAY socket option (default: false)
264 # @telnet: enable telnet protocol on server
265 #          sockets (default: false)
266 # @tn3270: enable tn3270 protocol on server
267 #          sockets (default: false) (Since: 2.10)
268 # @websocket: enable websocket protocol on server
269 #             sockets (default: false) (Since: 3.1)
270 # @reconnect: For a client socket, if a socket is disconnected,
271 #             then attempt a reconnect after the given number of seconds.
272 #             Setting this to zero disables this function. (default: 0)
273 #             (Since: 2.2)
275 # Since: 1.4
277 { 'struct': 'ChardevSocket',
278   'data': { 'addr': 'SocketAddressLegacy',
279             '*tls-creds': 'str',
280             '*tls-authz'  : 'str',
281             '*server': 'bool',
282             '*wait': 'bool',
283             '*nodelay': 'bool',
284             '*telnet': 'bool',
285             '*tn3270': 'bool',
286             '*websocket': 'bool',
287             '*reconnect': 'int' },
288   'base': 'ChardevCommon' }
291 # @ChardevUdp:
293 # Configuration info for datagram socket chardevs.
295 # @remote: remote address
296 # @local: local address
298 # Since: 1.5
300 { 'struct': 'ChardevUdp',
301   'data': { 'remote': 'SocketAddressLegacy',
302             '*local': 'SocketAddressLegacy' },
303   'base': 'ChardevCommon' }
306 # @ChardevMux:
308 # Configuration info for mux chardevs.
310 # @chardev: name of the base chardev.
312 # Since: 1.5
314 { 'struct': 'ChardevMux',
315   'data': { 'chardev': 'str' },
316   'base': 'ChardevCommon' }
319 # @ChardevStdio:
321 # Configuration info for stdio chardevs.
323 # @signal: Allow signals (such as SIGINT triggered by ^C)
324 #          be delivered to qemu.  Default: true.
326 # Since: 1.5
328 { 'struct': 'ChardevStdio',
329   'data': { '*signal': 'bool' },
330   'base': 'ChardevCommon' }
333 # @ChardevSpiceChannel:
335 # Configuration info for spice vm channel chardevs.
337 # @type: kind of channel (for example vdagent).
339 # Since: 1.5
341 { 'struct': 'ChardevSpiceChannel',
342   'data': { 'type': 'str' },
343   'base': 'ChardevCommon',
344   'if': 'CONFIG_SPICE' }
347 # @ChardevSpicePort:
349 # Configuration info for spice port chardevs.
351 # @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
353 # Since: 1.5
355 { 'struct': 'ChardevSpicePort',
356   'data': { 'fqdn': 'str' },
357   'base': 'ChardevCommon',
358   'if': 'CONFIG_SPICE' }
361 # @ChardevDBus:
363 # Configuration info for DBus chardevs.
365 # @name: name of the channel (following docs/spice-port-fqdn.txt)
367 # Since: 7.0
369 { 'struct': 'ChardevDBus',
370   'data': { 'name': 'str' },
371   'base': 'ChardevCommon',
372   'if': 'CONFIG_DBUS_DISPLAY' }
375 # @ChardevVC:
377 # Configuration info for virtual console chardevs.
379 # @width: console width, in pixels
380 # @height: console height, in pixels
381 # @cols: console width, in chars
382 # @rows: console height, in chars
384 # Since: 1.5
386 { 'struct': 'ChardevVC',
387   'data': { '*width': 'int',
388             '*height': 'int',
389             '*cols': 'int',
390             '*rows': 'int' },
391   'base': 'ChardevCommon' }
394 # @ChardevRingbuf:
396 # Configuration info for ring buffer chardevs.
398 # @size: ring buffer size, must be power of two, default is 65536
400 # Since: 1.5
402 { 'struct': 'ChardevRingbuf',
403   'data': { '*size': 'int' },
404   'base': 'ChardevCommon' }
407 # @ChardevQemuVDAgent:
409 # Configuration info for qemu vdagent implementation.
411 # @mouse: enable/disable mouse, default is enabled.
412 # @clipboard: enable/disable clipboard, default is disabled.
414 # Since: 6.1
416 { 'struct': 'ChardevQemuVDAgent',
417   'data': { '*mouse': 'bool',
418             '*clipboard': 'bool' },
419   'base': 'ChardevCommon',
420   'if': 'CONFIG_SPICE_PROTOCOL' }
423 # @ChardevBackendKind:
425 # @pipe: Since 1.5
426 # @udp: Since 1.5
427 # @mux: Since 1.5
428 # @msmouse: Since 1.5
429 # @wctablet: Since 2.9
430 # @braille: Since 1.5
431 # @testdev: Since 2.2
432 # @stdio: Since 1.5
433 # @console: Since 1.5
434 # @spicevmc: Since 1.5
435 # @spiceport: Since 1.5
436 # @qemu-vdagent: Since 6.1
437 # @dbus: Since 7.0
438 # @vc: v1.5
439 # @ringbuf: Since 1.6
440 # @memory: Since 1.5
442 # Since: 1.4
444 { 'enum': 'ChardevBackendKind',
445   'data': [ 'file',
446             'serial',
447             'parallel',
448             'pipe',
449             'socket',
450             'udp',
451             'pty',
452             'null',
453             'mux',
454             'msmouse',
455             'wctablet',
456             'braille',
457             'testdev',
458             'stdio',
459             'console',
460             { 'name': 'spicevmc', 'if': 'CONFIG_SPICE' },
461             { 'name': 'spiceport', 'if': 'CONFIG_SPICE' },
462             { 'name': 'qemu-vdagent', 'if': 'CONFIG_SPICE_PROTOCOL' },
463             { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' },
464             'vc',
465             'ringbuf',
466             # next one is just for compatibility
467             'memory' ] }
470 # @ChardevFileWrapper:
472 # Since: 1.4
474 { 'struct': 'ChardevFileWrapper',
475   'data': { 'data': 'ChardevFile' } }
478 # @ChardevHostdevWrapper:
480 # Since: 1.4
482 { 'struct': 'ChardevHostdevWrapper',
483   'data': { 'data': 'ChardevHostdev' } }
486 # @ChardevSocketWrapper:
488 # Since: 1.4
490 { 'struct': 'ChardevSocketWrapper',
491   'data': { 'data': 'ChardevSocket' } }
494 # @ChardevUdpWrapper:
496 # Since: 1.5
498 { 'struct': 'ChardevUdpWrapper',
499   'data': { 'data': 'ChardevUdp' } }
502 # @ChardevCommonWrapper:
504 # Since: 2.6
506 { 'struct': 'ChardevCommonWrapper',
507   'data': { 'data': 'ChardevCommon' } }
510 # @ChardevMuxWrapper:
512 # Since: 1.5
514 { 'struct': 'ChardevMuxWrapper',
515   'data': { 'data': 'ChardevMux' } }
518 # @ChardevStdioWrapper:
520 # Since: 1.5
522 { 'struct': 'ChardevStdioWrapper',
523   'data': { 'data': 'ChardevStdio' } }
526 # @ChardevSpiceChannelWrapper:
528 # Since: 1.5
530 { 'struct': 'ChardevSpiceChannelWrapper',
531   'data': { 'data': 'ChardevSpiceChannel' },
532   'if': 'CONFIG_SPICE' }
535 # @ChardevSpicePortWrapper:
537 # Since: 1.5
539 { 'struct': 'ChardevSpicePortWrapper',
540   'data': { 'data': 'ChardevSpicePort' },
541   'if': 'CONFIG_SPICE' }
544 # @ChardevQemuVDAgentWrapper:
546 # Since: 6.1
548 { 'struct': 'ChardevQemuVDAgentWrapper',
549   'data': { 'data': 'ChardevQemuVDAgent' },
550   'if': 'CONFIG_SPICE_PROTOCOL' }
553 # @ChardevDBusWrapper:
555 # Since: 7.0
557 { 'struct': 'ChardevDBusWrapper',
558   'data': { 'data': 'ChardevDBus' },
559   'if': 'CONFIG_DBUS_DISPLAY' }
562 # @ChardevVCWrapper:
564 # Since: 1.5
566 { 'struct': 'ChardevVCWrapper',
567   'data': { 'data': 'ChardevVC' } }
570 # @ChardevRingbufWrapper:
572 # Since: 1.5
574 { 'struct': 'ChardevRingbufWrapper',
575   'data': { 'data': 'ChardevRingbuf' } }
578 # @ChardevBackend:
580 # Configuration info for the new chardev backend.
582 # Since: 1.4
584 { 'union': 'ChardevBackend',
585   'base': { 'type': 'ChardevBackendKind' },
586   'discriminator': 'type',
587   'data': { 'file': 'ChardevFileWrapper',
588             'serial': 'ChardevHostdevWrapper',
589             'parallel': 'ChardevHostdevWrapper',
590             'pipe': 'ChardevHostdevWrapper',
591             'socket': 'ChardevSocketWrapper',
592             'udp': 'ChardevUdpWrapper',
593             'pty': 'ChardevCommonWrapper',
594             'null': 'ChardevCommonWrapper',
595             'mux': 'ChardevMuxWrapper',
596             'msmouse': 'ChardevCommonWrapper',
597             'wctablet': 'ChardevCommonWrapper',
598             'braille': 'ChardevCommonWrapper',
599             'testdev': 'ChardevCommonWrapper',
600             'stdio': 'ChardevStdioWrapper',
601             'console': 'ChardevCommonWrapper',
602             'spicevmc': { 'type': 'ChardevSpiceChannelWrapper',
603                           'if': 'CONFIG_SPICE' },
604             'spiceport': { 'type': 'ChardevSpicePortWrapper',
605                            'if': 'CONFIG_SPICE' },
606             'qemu-vdagent': { 'type': 'ChardevQemuVDAgentWrapper',
607                               'if': 'CONFIG_SPICE_PROTOCOL' },
608             'dbus': { 'type': 'ChardevDBusWrapper',
609                       'if': 'CONFIG_DBUS_DISPLAY' },
610             'vc': 'ChardevVCWrapper',
611             'ringbuf': 'ChardevRingbufWrapper',
612             # next one is just for compatibility
613             'memory': 'ChardevRingbufWrapper' } }
616 # @ChardevReturn:
618 # Return info about the chardev backend just created.
620 # @pty: name of the slave pseudoterminal device, present if
621 #       and only if a chardev of type 'pty' was created
623 # Since: 1.4
625 { 'struct' : 'ChardevReturn',
626   'data': { '*pty': 'str' } }
629 # @chardev-add:
631 # Add a character device backend
633 # @id: the chardev's ID, must be unique
634 # @backend: backend type and parameters
636 # Returns: ChardevReturn.
638 # Since: 1.4
640 # Example:
642 # -> { "execute" : "chardev-add",
643 #      "arguments" : { "id" : "foo",
644 #                      "backend" : { "type" : "null", "data" : {} } } }
645 # <- { "return": {} }
647 # -> { "execute" : "chardev-add",
648 #      "arguments" : { "id" : "bar",
649 #                      "backend" : { "type" : "file",
650 #                                    "data" : { "out" : "/tmp/bar.log" } } } }
651 # <- { "return": {} }
653 # -> { "execute" : "chardev-add",
654 #      "arguments" : { "id" : "baz",
655 #                      "backend" : { "type" : "pty", "data" : {} } } }
656 # <- { "return": { "pty" : "/dev/pty/42" } }
659 { 'command': 'chardev-add',
660   'data': { 'id': 'str',
661             'backend': 'ChardevBackend' },
662   'returns': 'ChardevReturn' }
665 # @chardev-change:
667 # Change a character device backend
669 # @id: the chardev's ID, must exist
670 # @backend: new backend type and parameters
672 # Returns: ChardevReturn.
674 # Since: 2.10
676 # Example:
678 # -> { "execute" : "chardev-change",
679 #      "arguments" : { "id" : "baz",
680 #                      "backend" : { "type" : "pty", "data" : {} } } }
681 # <- { "return": { "pty" : "/dev/pty/42" } }
683 # -> {"execute" : "chardev-change",
684 #     "arguments" : {
685 #         "id" : "charchannel2",
686 #         "backend" : {
687 #             "type" : "socket",
688 #             "data" : {
689 #                 "addr" : {
690 #                     "type" : "unix" ,
691 #                     "data" : {
692 #                         "path" : "/tmp/charchannel2.socket"
693 #                     }
694 #                  },
695 #                  "server" : true,
696 #                  "wait" : false }}}}
697 # <- {"return": {}}
700 { 'command': 'chardev-change',
701   'data': { 'id': 'str',
702             'backend': 'ChardevBackend' },
703   'returns': 'ChardevReturn' }
706 # @chardev-remove:
708 # Remove a character device backend
710 # @id: the chardev's ID, must exist and not be in use
712 # Returns: Nothing on success
714 # Since: 1.4
716 # Example:
718 # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
719 # <- { "return": {} }
722 { 'command': 'chardev-remove',
723   'data': { 'id': 'str' } }
726 # @chardev-send-break:
728 # Send a break to a character device
730 # @id: the chardev's ID, must exist
732 # Returns: Nothing on success
734 # Since: 2.10
736 # Example:
738 # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
739 # <- { "return": {} }
742 { 'command': 'chardev-send-break',
743   'data': { 'id': 'str' } }
746 # @VSERPORT_CHANGE:
748 # Emitted when the guest opens or closes a virtio-serial port.
750 # @id: device identifier of the virtio-serial port
752 # @open: true if the guest has opened the virtio-serial port
754 # Note: This event is rate-limited.
756 # Since: 2.1
758 # Example:
760 # <- { "event": "VSERPORT_CHANGE",
761 #      "data": { "id": "channel0", "open": true },
762 #      "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
765 { 'event': 'VSERPORT_CHANGE',
766   'data': { 'id': 'str',
767             'open': 'bool' } }