fuzz: add support for qos-assisted fuzz targets
[qemu/ar7.git] / qapi / char.json
blob6907b2bfdbaa367fbdb287fee652d6edcbe63e4c
1 # -*- Mode: Python -*-
4 ##
5 # = Character devices
6 ##
8 { 'include': 'sockets.json' }
11 # @ChardevInfo:
13 # Information about a character device.
15 # @label: the label of the character device
17 # @filename: the filename of the character device
19 # @frontend-open: shows whether the frontend device attached to this backend
20 #                 (eg. with the chardev=... option) is in open or closed state
21 #                 (since 2.1)
23 # Notes: @filename is encoded using the QEMU command line character device
24 #        encoding.  See the QEMU man page for details.
26 # Since: 0.14.0
28 { 'struct': 'ChardevInfo',
29   'data': { 'label': 'str',
30             'filename': 'str',
31             'frontend-open': 'bool' } }
34 # @query-chardev:
36 # Returns information about current character devices.
38 # Returns: a list of @ChardevInfo
40 # Since: 0.14.0
42 # Example:
44 # -> { "execute": "query-chardev" }
45 # <- {
46 #       "return": [
47 #          {
48 #             "label": "charchannel0",
49 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
50 #             "frontend-open": false
51 #          },
52 #          {
53 #             "label": "charmonitor",
54 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
55 #             "frontend-open": true
56 #          },
57 #          {
58 #             "label": "charserial0",
59 #             "filename": "pty:/dev/pts/2",
60 #             "frontend-open": true
61 #          }
62 #       ]
63 #    }
66 { 'command': 'query-chardev', 'returns': ['ChardevInfo'],
67   'allow-preconfig': true }
70 # @ChardevBackendInfo:
72 # Information about a character device backend
74 # @name: The backend name
76 # Since: 2.0
78 { 'struct': 'ChardevBackendInfo', 'data': {'name': 'str'} }
81 # @query-chardev-backends:
83 # Returns information about character device backends.
85 # Returns: a list of @ChardevBackendInfo
87 # Since: 2.0
89 # Example:
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 #    }
110 { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
113 # @DataFormat:
115 # An enumeration of data format.
117 # @utf8: Data is a UTF-8 string (RFC 3629)
119 # @base64: Data is Base64 encoded binary (RFC 3548)
121 # Since: 1.4
123 { 'enum': 'DataFormat',
124   'data': [ 'utf8', 'base64' ] }
127 # @ringbuf-write:
129 # Write to a ring buffer character device.
131 # @device: the ring buffer character device name
133 # @data: data to write
135 # @format: data encoding (default 'utf8').
137 #          - base64: data must be base64 encoded text.  Its binary
138 #            decoding gets written.
139 #          - utf8: data's UTF-8 encoding is written
140 #          - data itself is always Unicode regardless of format, like
141 #            any other string.
143 # Returns: Nothing on success
145 # Since: 1.4
147 # Example:
149 # -> { "execute": "ringbuf-write",
150 #      "arguments": { "device": "foo",
151 #                     "data": "abcdefgh",
152 #                     "format": "utf8" } }
153 # <- { "return": {} }
156 { 'command': 'ringbuf-write',
157   'data': { 'device': 'str',
158             'data': 'str',
159            '*format': 'DataFormat'} }
162 # @ringbuf-read:
164 # Read from a ring buffer character device.
166 # @device: the ring buffer character device name
168 # @size: how many bytes to read at most
170 # @format: data encoding (default 'utf8').
172 #          - base64: the data read is returned in base64 encoding.
173 #          - utf8: the data read is interpreted as UTF-8.
174 #            Bug: can screw up when the buffer contains invalid UTF-8
175 #            sequences, NUL characters, after the ring buffer lost
176 #            data, and when reading stops because the size limit is
177 #            reached.
178 #          - The return value is always Unicode regardless of format,
179 #            like any other string.
181 # Returns: data read from the device
183 # Since: 1.4
185 # Example:
187 # -> { "execute": "ringbuf-read",
188 #      "arguments": { "device": "foo",
189 #                     "size": 1000,
190 #                     "format": "utf8" } }
191 # <- { "return": "abcdefgh" }
194 { 'command': 'ringbuf-read',
195   'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
196   'returns': 'str' }
199 # @ChardevCommon:
201 # Configuration shared across all chardev backends
203 # @logfile: The name of a logfile to save output
204 # @logappend: true to append instead of truncate
205 #             (default to false to truncate)
207 # Since: 2.6
209 { 'struct': 'ChardevCommon',
210   'data': { '*logfile': 'str',
211             '*logappend': 'bool' } }
214 # @ChardevFile:
216 # Configuration info for file chardevs.
218 # @in:  The name of the input file
219 # @out: The name of the output file
220 # @append: Open the file in append mode (default false to
221 #          truncate) (Since 2.6)
223 # Since: 1.4
225 { 'struct': 'ChardevFile',
226   'data': { '*in': 'str',
227             'out': 'str',
228             '*append': 'bool' },
229   'base': 'ChardevCommon' }
232 # @ChardevHostdev:
234 # Configuration info for device and pipe chardevs.
236 # @device: The name of the special file for the device,
237 #          i.e. /dev/ttyS0 on Unix or COM1: on Windows
239 # Since: 1.4
241 { 'struct': 'ChardevHostdev',
242   'data': { 'device': 'str' },
243   'base': 'ChardevCommon' }
246 # @ChardevSocket:
248 # Configuration info for (stream) socket chardevs.
250 # @addr: socket address to listen on (server=true)
251 #        or connect to (server=false)
252 # @tls-creds: the ID of the TLS credentials object (since 2.6)
253 # @tls-authz: the ID of the QAuthZ authorization object against which
254 #             the client's x509 distinguished name will be validated. This
255 #             object is only resolved at time of use, so can be deleted
256 #             and recreated on the fly while the chardev server is active.
257 #             If missing, it will default to denying access (since 4.0)
258 # @server: create server socket (default: true)
259 # @wait: wait for incoming connection on server
260 #        sockets (default: false).
261 # @nodelay: set TCP_NODELAY socket option (default: false)
262 # @telnet: enable telnet protocol on server
263 #          sockets (default: false)
264 # @tn3270: enable tn3270 protocol on server
265 #          sockets (default: false) (Since: 2.10)
266 # @websocket: enable websocket protocol on server
267 #             sockets (default: false) (Since: 3.1)
268 # @reconnect: For a client socket, if a socket is disconnected,
269 #             then attempt a reconnect after the given number of seconds.
270 #             Setting this to zero disables this function. (default: 0)
271 #             (Since: 2.2)
273 # Since: 1.4
275 { 'struct': 'ChardevSocket',
276   'data': { 'addr': 'SocketAddressLegacy',
277             '*tls-creds': 'str',
278             '*tls-authz'  : 'str',
279             '*server': 'bool',
280             '*wait': 'bool',
281             '*nodelay': 'bool',
282             '*telnet': 'bool',
283             '*tn3270': 'bool',
284             '*websocket': 'bool',
285             '*reconnect': 'int' },
286   'base': 'ChardevCommon' }
289 # @ChardevUdp:
291 # Configuration info for datagram socket chardevs.
293 # @remote: remote address
294 # @local: local address
296 # Since: 1.5
298 { 'struct': 'ChardevUdp',
299   'data': { 'remote': 'SocketAddressLegacy',
300             '*local': 'SocketAddressLegacy' },
301   'base': 'ChardevCommon' }
304 # @ChardevMux:
306 # Configuration info for mux chardevs.
308 # @chardev: name of the base chardev.
310 # Since: 1.5
312 { 'struct': 'ChardevMux',
313   'data': { 'chardev': 'str' },
314   'base': 'ChardevCommon' }
317 # @ChardevStdio:
319 # Configuration info for stdio chardevs.
321 # @signal: Allow signals (such as SIGINT triggered by ^C)
322 #          be delivered to qemu.  Default: true in -nographic mode,
323 #          false otherwise.
325 # Since: 1.5
327 { 'struct': 'ChardevStdio',
328   'data': { '*signal': 'bool' },
329   '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': 'defined(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': 'defined(CONFIG_SPICE)' }
361 # @ChardevVC:
363 # Configuration info for virtual console chardevs.
365 # @width:  console width,  in pixels
366 # @height: console height, in pixels
367 # @cols:   console width,  in chars
368 # @rows:   console height, in chars
370 # Since: 1.5
372 { 'struct': 'ChardevVC',
373   'data': { '*width': 'int',
374             '*height': 'int',
375             '*cols': 'int',
376             '*rows': 'int' },
377   'base': 'ChardevCommon' }
380 # @ChardevRingbuf:
382 # Configuration info for ring buffer chardevs.
384 # @size: ring buffer size, must be power of two, default is 65536
386 # Since: 1.5
388 { 'struct': 'ChardevRingbuf',
389   'data': { '*size': 'int' },
390   'base': 'ChardevCommon' }
393 # @ChardevBackend:
395 # Configuration info for the new chardev backend.
397 # Since: 1.4 (testdev since 2.2, wctablet since 2.9)
399 { 'union': 'ChardevBackend',
400   'data': { 'file': 'ChardevFile',
401             'serial': 'ChardevHostdev',
402             'parallel': 'ChardevHostdev',
403             'pipe': 'ChardevHostdev',
404             'socket': 'ChardevSocket',
405             'udp': 'ChardevUdp',
406             'pty': 'ChardevCommon',
407             'null': 'ChardevCommon',
408             'mux': 'ChardevMux',
409             'msmouse': 'ChardevCommon',
410             'wctablet': 'ChardevCommon',
411             'braille': 'ChardevCommon',
412             'testdev': 'ChardevCommon',
413             'stdio': 'ChardevStdio',
414             'console': 'ChardevCommon',
415             'spicevmc': { 'type': 'ChardevSpiceChannel',
416                           'if': 'defined(CONFIG_SPICE)' },
417             'spiceport': { 'type': 'ChardevSpicePort',
418                            'if': 'defined(CONFIG_SPICE)' },
419             'vc': 'ChardevVC',
420             'ringbuf': 'ChardevRingbuf',
421             # next one is just for compatibility
422             'memory': 'ChardevRingbuf' } }
425 # @ChardevReturn:
427 # Return info about the chardev backend just created.
429 # @pty: name of the slave pseudoterminal device, present if
430 #       and only if a chardev of type 'pty' was created
432 # Since: 1.4
434 { 'struct' : 'ChardevReturn',
435   'data': { '*pty': 'str' } }
438 # @chardev-add:
440 # Add a character device backend
442 # @id: the chardev's ID, must be unique
443 # @backend: backend type and parameters
445 # Returns: ChardevReturn.
447 # Since: 1.4
449 # Example:
451 # -> { "execute" : "chardev-add",
452 #      "arguments" : { "id" : "foo",
453 #                      "backend" : { "type" : "null", "data" : {} } } }
454 # <- { "return": {} }
456 # -> { "execute" : "chardev-add",
457 #      "arguments" : { "id" : "bar",
458 #                      "backend" : { "type" : "file",
459 #                                    "data" : { "out" : "/tmp/bar.log" } } } }
460 # <- { "return": {} }
462 # -> { "execute" : "chardev-add",
463 #      "arguments" : { "id" : "baz",
464 #                      "backend" : { "type" : "pty", "data" : {} } } }
465 # <- { "return": { "pty" : "/dev/pty/42" } }
468 { 'command': 'chardev-add',
469   'data': { 'id': 'str',
470             'backend': 'ChardevBackend' },
471   'returns': 'ChardevReturn' }
474 # @chardev-change:
476 # Change a character device backend
478 # @id: the chardev's ID, must exist
479 # @backend: new backend type and parameters
481 # Returns: ChardevReturn.
483 # Since: 2.10
485 # Example:
487 # -> { "execute" : "chardev-change",
488 #      "arguments" : { "id" : "baz",
489 #                      "backend" : { "type" : "pty", "data" : {} } } }
490 # <- { "return": { "pty" : "/dev/pty/42" } }
492 # -> {"execute" : "chardev-change",
493 #     "arguments" : {
494 #         "id" : "charchannel2",
495 #         "backend" : {
496 #             "type" : "socket",
497 #             "data" : {
498 #                 "addr" : {
499 #                     "type" : "unix" ,
500 #                     "data" : {
501 #                         "path" : "/tmp/charchannel2.socket"
502 #                     }
503 #                  },
504 #                  "server" : true,
505 #                  "wait" : false }}}}
506 # <- {"return": {}}
509 { 'command': 'chardev-change',
510   'data': { 'id': 'str',
511             'backend': 'ChardevBackend' },
512   'returns': 'ChardevReturn' }
515 # @chardev-remove:
517 # Remove a character device backend
519 # @id: the chardev's ID, must exist and not be in use
521 # Returns: Nothing on success
523 # Since: 1.4
525 # Example:
527 # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
528 # <- { "return": {} }
531 { 'command': 'chardev-remove',
532   'data': { 'id': 'str' } }
535 # @chardev-send-break:
537 # Send a break to a character device
539 # @id: the chardev's ID, must exist
541 # Returns: Nothing on success
543 # Since: 2.10
545 # Example:
547 # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
548 # <- { "return": {} }
551 { 'command': 'chardev-send-break',
552   'data': { 'id': 'str' } }
555 # @VSERPORT_CHANGE:
557 # Emitted when the guest opens or closes a virtio-serial port.
559 # @id: device identifier of the virtio-serial port
561 # @open: true if the guest has opened the virtio-serial port
563 # Since: 2.1
565 # Example:
567 # <- { "event": "VSERPORT_CHANGE",
568 #      "data": { "id": "channel0", "open": true },
569 #      "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
572 { 'event': 'VSERPORT_CHANGE',
573   'data': { 'id': 'str',
574             'open': 'bool' } }