xref: /openbmc/qemu/qapi/char.json (revision 01bed0ff)
1# -*- Mode: Python -*-
2# vim: filetype=python
3#
4
5##
6# = Character devices
7##
8
9{ 'include': 'sockets.json' }
10
11##
12# @ChardevInfo:
13#
14# Information about a character device.
15#
16# @label: the label of the character device
17#
18# @filename: the filename of the character device
19#
20# @frontend-open: shows whether the frontend device attached to this
21#     backend (e.g. with the chardev=... option) is in open or closed
22#     state (since 2.1)
23#
24# .. note:: @filename is encoded using the QEMU command line character
25#    device encoding.  See the QEMU man page for details.
26#
27# Since: 0.14
28##
29{ 'struct': 'ChardevInfo',
30  'data': { 'label': 'str',
31            'filename': 'str',
32            'frontend-open': 'bool' } }
33
34##
35# @query-chardev:
36#
37# Returns information about current character devices.
38#
39# Returns: a list of @ChardevInfo
40#
41# Since: 0.14
42#
43# .. qmp-example::
44#
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#        }
65##
66{ 'command': 'query-chardev', 'returns': ['ChardevInfo'],
67  'allow-preconfig': true }
68
69##
70# @ChardevBackendInfo:
71#
72# Information about a character device backend
73#
74# @name: The backend name
75#
76# Since: 2.0
77##
78{ 'struct': 'ChardevBackendInfo', 'data': {'name': 'str'} }
79
80##
81# @query-chardev-backends:
82#
83# Returns information about character device backends.
84#
85# Returns: a list of @ChardevBackendInfo
86#
87# Since: 2.0
88#
89# .. qmp-example::
90#
91#     -> { "execute": "query-chardev-backends" }
92#     <- {
93#           "return":[
94#              {
95#                 "name":"udp"
96#              },
97#              {
98#                 "name":"tcp"
99#              },
100#              {
101#                 "name":"unix"
102#              },
103#              {
104#                 "name":"spiceport"
105#              }
106#           ]
107#        }
108##
109{ 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
110
111##
112# @DataFormat:
113#
114# An enumeration of data format.
115#
116# @utf8: Data is a UTF-8 string (RFC 3629)
117#
118# @base64: Data is Base64 encoded binary (RFC 3548)
119#
120# Since: 1.4
121##
122{ 'enum': 'DataFormat',
123  'data': [ 'utf8', 'base64' ] }
124
125##
126# @ringbuf-write:
127#
128# Write to a ring buffer character device.
129#
130# @device: the ring buffer character device name
131#
132# @data: data to write
133#
134# @format: data encoding (default 'utf8').
135#
136#     - base64: data must be base64 encoded text.  Its binary decoding
137#       gets written.
138#     - utf8: data's UTF-8 encoding is written
139#     - data itself is always Unicode regardless of format, like any
140#       other string.
141#
142# Since: 1.4
143#
144# .. qmp-example::
145#
146#     -> { "execute": "ringbuf-write",
147#          "arguments": { "device": "foo",
148#                         "data": "abcdefgh",
149#                         "format": "utf8" } }
150#     <- { "return": {} }
151##
152{ 'command': 'ringbuf-write',
153  'data': { 'device': 'str',
154            'data': 'str',
155           '*format': 'DataFormat'} }
156
157##
158# @ringbuf-read:
159#
160# Read from a ring buffer character device.
161#
162# @device: the ring buffer character device name
163#
164# @size: how many bytes to read at most
165#
166# @format: data encoding (default 'utf8').
167#
168#     - base64: the data read is returned in base64 encoding.
169#     - utf8: the data read is interpreted as UTF-8.
170#       Bug: can screw up when the buffer contains invalid UTF-8
171#       sequences, NUL characters, after the ring buffer lost data,
172#       and when reading stops because the size limit is reached.
173#     - The return value is always Unicode regardless of format, like
174#       any other string.
175#
176# Returns: data read from the device
177#
178# Since: 1.4
179#
180# .. qmp-example::
181#
182#     -> { "execute": "ringbuf-read",
183#          "arguments": { "device": "foo",
184#                         "size": 1000,
185#                         "format": "utf8" } }
186#     <- { "return": "abcdefgh" }
187##
188{ 'command': 'ringbuf-read',
189  'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
190  'returns': 'str' }
191
192##
193# @ChardevCommon:
194#
195# Configuration shared across all chardev backends
196#
197# @logfile: The name of a logfile to save output
198#
199# @logappend: true to append instead of truncate (default to false to
200#     truncate)
201#
202# Since: 2.6
203##
204{ 'struct': 'ChardevCommon',
205  'data': { '*logfile': 'str',
206            '*logappend': 'bool' } }
207
208##
209# @ChardevFile:
210#
211# Configuration info for file chardevs.
212#
213# @in: The name of the input file
214#
215# @out: The name of the output file
216#
217# @append: Open the file in append mode (default false to truncate)
218#     (Since 2.6)
219#
220# Since: 1.4
221##
222{ 'struct': 'ChardevFile',
223  'data': { '*in': 'str',
224            'out': 'str',
225            '*append': 'bool' },
226  'base': 'ChardevCommon' }
227
228##
229# @ChardevHostdev:
230#
231# Configuration info for device and pipe chardevs.
232#
233# @device: The name of the special file for the device, i.e.
234#     /dev/ttyS0 on Unix or COM1: on Windows
235#
236# Since: 1.4
237##
238{ 'struct': 'ChardevHostdev',
239  'data': { 'device': 'str' },
240  'base': 'ChardevCommon' }
241
242##
243# @ChardevSocket:
244#
245# Configuration info for (stream) socket chardevs.
246#
247# @addr: socket address to listen on (server=true) or connect to
248#     (server=false)
249#
250# @tls-creds: the ID of the TLS credentials object (since 2.6)
251#
252# @tls-authz: the ID of the QAuthZ authorization object against which
253#     the client's x509 distinguished name will be validated.  This
254#     object is only resolved at time of use, so can be deleted and
255#     recreated on the fly while the chardev server is active.  If
256#     missing, it will default to denying access (since 4.0)
257#
258# @server: create server socket (default: true)
259#
260# @wait: wait for incoming connection on server sockets (default:
261#     false).  Silently ignored with server: false.  This use is
262#     deprecated.
263#
264# @nodelay: set TCP_NODELAY socket option (default: false)
265#
266# @telnet: enable telnet protocol on server sockets (default: false)
267#
268# @tn3270: enable tn3270 protocol on server sockets (default: false)
269#     (Since: 2.10)
270#
271# @websocket: enable websocket protocol on server sockets
272#     (default: false) (Since: 3.1)
273#
274# @reconnect: For a client socket, if a socket is disconnected, then
275#     attempt a reconnect after the given number of seconds.  Setting
276#     this to zero disables this function.  (default: 0) (Since: 2.2)
277#
278# Since: 1.4
279##
280{ 'struct': 'ChardevSocket',
281  'data': { 'addr': 'SocketAddressLegacy',
282            '*tls-creds': 'str',
283            '*tls-authz'  : 'str',
284            '*server': 'bool',
285            '*wait': 'bool',
286            '*nodelay': 'bool',
287            '*telnet': 'bool',
288            '*tn3270': 'bool',
289            '*websocket': 'bool',
290            '*reconnect': 'int' },
291  'base': 'ChardevCommon' }
292
293##
294# @ChardevUdp:
295#
296# Configuration info for datagram socket chardevs.
297#
298# @remote: remote address
299#
300# @local: local address
301#
302# Since: 1.5
303##
304{ 'struct': 'ChardevUdp',
305  'data': { 'remote': 'SocketAddressLegacy',
306            '*local': 'SocketAddressLegacy' },
307  'base': 'ChardevCommon' }
308
309##
310# @ChardevMux:
311#
312# Configuration info for mux chardevs.
313#
314# @chardev: name of the base chardev.
315#
316# Since: 1.5
317##
318{ 'struct': 'ChardevMux',
319  'data': { 'chardev': 'str' },
320  'base': 'ChardevCommon' }
321
322##
323# @ChardevStdio:
324#
325# Configuration info for stdio chardevs.
326#
327# @signal: Allow signals (such as SIGINT triggered by ^C) be delivered
328#     to qemu.  Default: true.
329#
330# Since: 1.5
331##
332{ 'struct': 'ChardevStdio',
333  'data': { '*signal': 'bool' },
334  'base': 'ChardevCommon' }
335
336##
337# @ChardevSpiceChannel:
338#
339# Configuration info for spice vm channel chardevs.
340#
341# @type: kind of channel (for example vdagent).
342#
343# Since: 1.5
344##
345{ 'struct': 'ChardevSpiceChannel',
346  'data': { 'type': 'str' },
347  'base': 'ChardevCommon',
348  'if': 'CONFIG_SPICE' }
349
350##
351# @ChardevSpicePort:
352#
353# Configuration info for spice port chardevs.
354#
355# @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
356#
357# Since: 1.5
358##
359{ 'struct': 'ChardevSpicePort',
360  'data': { 'fqdn': 'str' },
361  'base': 'ChardevCommon',
362  'if': 'CONFIG_SPICE' }
363
364##
365# @ChardevDBus:
366#
367# Configuration info for DBus chardevs.
368#
369# @name: name of the channel (following docs/spice-port-fqdn.txt)
370#
371# Since: 7.0
372##
373{ 'struct': 'ChardevDBus',
374  'data': { 'name': 'str' },
375  'base': 'ChardevCommon',
376  'if': 'CONFIG_DBUS_DISPLAY' }
377
378##
379# @ChardevVC:
380#
381# Configuration info for virtual console chardevs.
382#
383# @width: console width, in pixels
384#
385# @height: console height, in pixels
386#
387# @cols: console width, in chars
388#
389# @rows: console height, in chars
390#
391# .. note:: The options are only effective when the VNC or SDL
392#    graphical display backend is active.  They are ignored with the
393#    GTK, Spice, VNC and D-Bus display backends.
394#
395# Since: 1.5
396##
397{ 'struct': 'ChardevVC',
398  'data': { '*width': 'int',
399            '*height': 'int',
400            '*cols': 'int',
401            '*rows': 'int' },
402  'base': 'ChardevCommon' }
403
404##
405# @ChardevRingbuf:
406#
407# Configuration info for ring buffer chardevs.
408#
409# @size: ring buffer size, must be power of two, default is 65536
410#
411# Since: 1.5
412##
413{ 'struct': 'ChardevRingbuf',
414  'data': { '*size': 'int' },
415  'base': 'ChardevCommon' }
416
417##
418# @ChardevQemuVDAgent:
419#
420# Configuration info for qemu vdagent implementation.
421#
422# @mouse: enable/disable mouse, default is enabled.
423#
424# @clipboard: enable/disable clipboard, default is disabled.
425#
426# Since: 6.1
427##
428{ 'struct': 'ChardevQemuVDAgent',
429  'data': { '*mouse': 'bool',
430            '*clipboard': 'bool' },
431  'base': 'ChardevCommon',
432  'if': 'CONFIG_SPICE_PROTOCOL' }
433
434##
435# @ChardevBackendKind:
436#
437# @pipe: Since 1.5
438#
439# @udp: Since 1.5
440#
441# @mux: Since 1.5
442#
443# @msmouse: Since 1.5
444#
445# @wctablet: Since 2.9
446#
447# @braille: Since 1.5
448#
449# @testdev: Since 2.2
450#
451# @stdio: Since 1.5
452#
453# @console: Since 1.5
454#
455# @spicevmc: Since 1.5
456#
457# @spiceport: Since 1.5
458#
459# @qemu-vdagent: Since 6.1
460#
461# @dbus: Since 7.0
462#
463# @vc: v1.5
464#
465# @ringbuf: Since 1.6
466#
467# @memory: Since 1.5
468#
469# Features:
470#
471# @deprecated: Member @memory is deprecated.  Use @ringbuf instead.
472#
473# Since: 1.4
474##
475{ 'enum': 'ChardevBackendKind',
476  'data': [ 'file',
477            { 'name': 'serial', 'if': 'HAVE_CHARDEV_SERIAL' },
478            { 'name': 'parallel', 'if': 'HAVE_CHARDEV_PARALLEL' },
479            'pipe',
480            'socket',
481            'udp',
482            'pty',
483            'null',
484            'mux',
485            'msmouse',
486            'wctablet',
487            { 'name': 'braille', 'if': 'CONFIG_BRLAPI' },
488            'testdev',
489            'stdio',
490            { 'name': 'console', 'if': 'CONFIG_WIN32' },
491            { 'name': 'spicevmc', 'if': 'CONFIG_SPICE' },
492            { 'name': 'spiceport', 'if': 'CONFIG_SPICE' },
493            { 'name': 'qemu-vdagent', 'if': 'CONFIG_SPICE_PROTOCOL' },
494            { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' },
495            'vc',
496            'ringbuf',
497            { 'name': 'memory', 'features': [ 'deprecated' ] } ] }
498
499##
500# @ChardevFileWrapper:
501#
502# @data: Configuration info for file chardevs
503#
504# Since: 1.4
505##
506{ 'struct': 'ChardevFileWrapper',
507  'data': { 'data': 'ChardevFile' } }
508
509##
510# @ChardevHostdevWrapper:
511#
512# @data: Configuration info for device and pipe chardevs
513#
514# Since: 1.4
515##
516{ 'struct': 'ChardevHostdevWrapper',
517  'data': { 'data': 'ChardevHostdev' } }
518
519##
520# @ChardevSocketWrapper:
521#
522# @data: Configuration info for (stream) socket chardevs
523#
524# Since: 1.4
525##
526{ 'struct': 'ChardevSocketWrapper',
527  'data': { 'data': 'ChardevSocket' } }
528
529##
530# @ChardevUdpWrapper:
531#
532# @data: Configuration info for datagram socket chardevs
533#
534# Since: 1.5
535##
536{ 'struct': 'ChardevUdpWrapper',
537  'data': { 'data': 'ChardevUdp' } }
538
539##
540# @ChardevCommonWrapper:
541#
542# @data: Configuration shared across all chardev backends
543#
544# Since: 2.6
545##
546{ 'struct': 'ChardevCommonWrapper',
547  'data': { 'data': 'ChardevCommon' } }
548
549##
550# @ChardevMuxWrapper:
551#
552# @data: Configuration info for mux chardevs
553#
554# Since: 1.5
555##
556{ 'struct': 'ChardevMuxWrapper',
557  'data': { 'data': 'ChardevMux' } }
558
559##
560# @ChardevStdioWrapper:
561#
562# @data: Configuration info for stdio chardevs
563#
564# Since: 1.5
565##
566{ 'struct': 'ChardevStdioWrapper',
567  'data': { 'data': 'ChardevStdio' } }
568
569##
570# @ChardevSpiceChannelWrapper:
571#
572# @data: Configuration info for spice vm channel chardevs
573#
574# Since: 1.5
575##
576{ 'struct': 'ChardevSpiceChannelWrapper',
577  'data': { 'data': 'ChardevSpiceChannel' },
578  'if': 'CONFIG_SPICE' }
579
580##
581# @ChardevSpicePortWrapper:
582#
583# @data: Configuration info for spice port chardevs
584#
585# Since: 1.5
586##
587{ 'struct': 'ChardevSpicePortWrapper',
588  'data': { 'data': 'ChardevSpicePort' },
589  'if': 'CONFIG_SPICE' }
590
591##
592# @ChardevQemuVDAgentWrapper:
593#
594# @data: Configuration info for qemu vdagent implementation
595#
596# Since: 6.1
597##
598{ 'struct': 'ChardevQemuVDAgentWrapper',
599  'data': { 'data': 'ChardevQemuVDAgent' },
600  'if': 'CONFIG_SPICE_PROTOCOL' }
601
602##
603# @ChardevDBusWrapper:
604#
605# @data: Configuration info for DBus chardevs
606#
607# Since: 7.0
608##
609{ 'struct': 'ChardevDBusWrapper',
610  'data': { 'data': 'ChardevDBus' },
611  'if': 'CONFIG_DBUS_DISPLAY' }
612
613##
614# @ChardevVCWrapper:
615#
616# @data: Configuration info for virtual console chardevs
617#
618# Since: 1.5
619##
620{ 'struct': 'ChardevVCWrapper',
621  'data': { 'data': 'ChardevVC' } }
622
623##
624# @ChardevRingbufWrapper:
625#
626# @data: Configuration info for ring buffer chardevs
627#
628# Since: 1.5
629##
630{ 'struct': 'ChardevRingbufWrapper',
631  'data': { 'data': 'ChardevRingbuf' } }
632
633##
634# @ChardevBackend:
635#
636# Configuration info for the new chardev backend.
637#
638# @type: backend type
639#
640# Since: 1.4
641##
642{ 'union': 'ChardevBackend',
643  'base': { 'type': 'ChardevBackendKind' },
644  'discriminator': 'type',
645  'data': { 'file': 'ChardevFileWrapper',
646            'serial': { 'type': 'ChardevHostdevWrapper',
647                        'if': 'HAVE_CHARDEV_SERIAL' },
648            'parallel': { 'type': 'ChardevHostdevWrapper',
649                          'if': 'HAVE_CHARDEV_PARALLEL' },
650            'pipe': 'ChardevHostdevWrapper',
651            'socket': 'ChardevSocketWrapper',
652            'udp': 'ChardevUdpWrapper',
653            'pty': 'ChardevCommonWrapper',
654            'null': 'ChardevCommonWrapper',
655            'mux': 'ChardevMuxWrapper',
656            'msmouse': 'ChardevCommonWrapper',
657            'wctablet': 'ChardevCommonWrapper',
658            'braille': { 'type': 'ChardevCommonWrapper',
659                         'if': 'CONFIG_BRLAPI' },
660            'testdev': 'ChardevCommonWrapper',
661            'stdio': 'ChardevStdioWrapper',
662            'console': { 'type': 'ChardevCommonWrapper',
663                         'if': 'CONFIG_WIN32' },
664            'spicevmc': { 'type': 'ChardevSpiceChannelWrapper',
665                          'if': 'CONFIG_SPICE' },
666            'spiceport': { 'type': 'ChardevSpicePortWrapper',
667                           'if': 'CONFIG_SPICE' },
668            'qemu-vdagent': { 'type': 'ChardevQemuVDAgentWrapper',
669                              'if': 'CONFIG_SPICE_PROTOCOL' },
670            'dbus': { 'type': 'ChardevDBusWrapper',
671                      'if': 'CONFIG_DBUS_DISPLAY' },
672            'vc': 'ChardevVCWrapper',
673            'ringbuf': 'ChardevRingbufWrapper',
674            'memory': 'ChardevRingbufWrapper' } }
675
676##
677# @ChardevReturn:
678#
679# Return info about the chardev backend just created.
680#
681# @pty: name of the slave pseudoterminal device, present if and only
682#     if a chardev of type 'pty' was created
683#
684# Since: 1.4
685##
686{ 'struct' : 'ChardevReturn',
687  'data': { '*pty': 'str' } }
688
689##
690# @chardev-add:
691#
692# Add a character device backend
693#
694# @id: the chardev's ID, must be unique
695#
696# @backend: backend type and parameters
697#
698# Returns: ChardevReturn.
699#
700# Since: 1.4
701#
702# .. qmp-example::
703#
704#     -> { "execute" : "chardev-add",
705#          "arguments" : { "id" : "foo",
706#                          "backend" : { "type" : "null", "data" : {} } } }
707#     <- { "return": {} }
708#
709# .. qmp-example::
710#
711#     -> { "execute" : "chardev-add",
712#          "arguments" : { "id" : "bar",
713#                          "backend" : { "type" : "file",
714#                                        "data" : { "out" : "/tmp/bar.log" } } } }
715#     <- { "return": {} }
716#
717# .. qmp-example::
718#
719#     -> { "execute" : "chardev-add",
720#          "arguments" : { "id" : "baz",
721#                          "backend" : { "type" : "pty", "data" : {} } } }
722#     <- { "return": { "pty" : "/dev/pty/42" } }
723##
724{ 'command': 'chardev-add',
725  'data': { 'id': 'str',
726            'backend': 'ChardevBackend' },
727  'returns': 'ChardevReturn' }
728
729##
730# @chardev-change:
731#
732# Change a character device backend
733#
734# @id: the chardev's ID, must exist
735#
736# @backend: new backend type and parameters
737#
738# Returns: ChardevReturn.
739#
740# Since: 2.10
741#
742# .. qmp-example::
743#
744#     -> { "execute" : "chardev-change",
745#          "arguments" : { "id" : "baz",
746#                          "backend" : { "type" : "pty", "data" : {} } } }
747#     <- { "return": { "pty" : "/dev/pty/42" } }
748#
749# .. qmp-example::
750#
751#     -> {"execute" : "chardev-change",
752#         "arguments" : {
753#             "id" : "charchannel2",
754#             "backend" : {
755#                 "type" : "socket",
756#                 "data" : {
757#                     "addr" : {
758#                         "type" : "unix" ,
759#                         "data" : {
760#                             "path" : "/tmp/charchannel2.socket"
761#                         }
762#                      },
763#                      "server" : true,
764#                      "wait" : false }}}}
765#     <- {"return": {}}
766##
767{ 'command': 'chardev-change',
768  'data': { 'id': 'str',
769            'backend': 'ChardevBackend' },
770  'returns': 'ChardevReturn' }
771
772##
773# @chardev-remove:
774#
775# Remove a character device backend
776#
777# @id: the chardev's ID, must exist and not be in use
778#
779# Since: 1.4
780#
781# .. qmp-example::
782#
783#     -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
784#     <- { "return": {} }
785##
786{ 'command': 'chardev-remove',
787  'data': { 'id': 'str' } }
788
789##
790# @chardev-send-break:
791#
792# Send a break to a character device
793#
794# @id: the chardev's ID, must exist
795#
796# Since: 2.10
797#
798# .. qmp-example::
799#
800#     -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
801#     <- { "return": {} }
802##
803{ 'command': 'chardev-send-break',
804  'data': { 'id': 'str' } }
805
806##
807# @VSERPORT_CHANGE:
808#
809# Emitted when the guest opens or closes a virtio-serial port.
810#
811# @id: device identifier of the virtio-serial port
812#
813# @open: true if the guest has opened the virtio-serial port
814#
815# .. note:: This event is rate-limited.
816#
817# Since: 2.1
818#
819# .. qmp-example::
820#
821#     <- { "event": "VSERPORT_CHANGE",
822#          "data": { "id": "channel0", "open": true },
823#          "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
824##
825{ 'event': 'VSERPORT_CHANGE',
826  'data': { 'id': 'str',
827            'open': 'bool' } }
828