capstone: Update to upstream "next" branch
[qemu.git] / qapi / char.json
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 backend
21 #                 (eg. with the chardev=... option) is in open or closed state
22 #                 (since 2.1)
23 #
24 # Notes: @filename is encoded using the QEMU command line character device
25 #        encoding.  See the QEMU man page for details.
26 #
27 # Since: 0.14.0
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.0
42 #
43 # Example:
44 #
45 # -> { "execute": "query-chardev" }
46 # <- {
47 #       "return": [
48 #          {
49 #             "label": "charchannel0",
50 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
51 #             "frontend-open": false
52 #          },
53 #          {
54 #             "label": "charmonitor",
55 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
56 #             "frontend-open": true
57 #          },
58 #          {
59 #             "label": "charserial0",
60 #             "filename": "pty:/dev/pts/2",
61 #             "frontend-open": true
62 #          }
63 #       ]
64 #    }
65 #
66 ##
67 { 'command': 'query-chardev', 'returns': ['ChardevInfo'],
68   'allow-preconfig': true }
69
70 ##
71 # @ChardevBackendInfo:
72 #
73 # Information about a character device backend
74 #
75 # @name: The backend name
76 #
77 # Since: 2.0
78 ##
79 { 'struct': 'ChardevBackendInfo', 'data': {'name': 'str'} }
80
81 ##
82 # @query-chardev-backends:
83 #
84 # Returns information about character device backends.
85 #
86 # Returns: a list of @ChardevBackendInfo
87 #
88 # Since: 2.0
89 #
90 # Example:
91 #
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 #    }
109 #
110 ##
111 { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
112
113 ##
114 # @DataFormat:
115 #
116 # An enumeration of data format.
117 #
118 # @utf8: Data is a UTF-8 string (RFC 3629)
119 #
120 # @base64: Data is Base64 encoded binary (RFC 3548)
121 #
122 # Since: 1.4
123 ##
124 { 'enum': 'DataFormat',
125   'data': [ 'utf8', 'base64' ] }
126
127 ##
128 # @ringbuf-write:
129 #
130 # Write to a ring buffer character device.
131 #
132 # @device: the ring buffer character device name
133 #
134 # @data: data to write
135 #
136 # @format: data encoding (default 'utf8').
137 #
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.
143 #
144 # Returns: Nothing on success
145 #
146 # Since: 1.4
147 #
148 # Example:
149 #
150 # -> { "execute": "ringbuf-write",
151 #      "arguments": { "device": "foo",
152 #                     "data": "abcdefgh",
153 #                     "format": "utf8" } }
154 # <- { "return": {} }
155 #
156 ##
157 { 'command': 'ringbuf-write',
158   'data': { 'device': 'str',
159             'data': 'str',
160            '*format': 'DataFormat'} }
161
162 ##
163 # @ringbuf-read:
164 #
165 # Read from a ring buffer character device.
166 #
167 # @device: the ring buffer character device name
168 #
169 # @size: how many bytes to read at most
170 #
171 # @format: data encoding (default 'utf8').
172 #
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.
181 #
182 # Returns: data read from the device
183 #
184 # Since: 1.4
185 #
186 # Example:
187 #
188 # -> { "execute": "ringbuf-read",
189 #      "arguments": { "device": "foo",
190 #                     "size": 1000,
191 #                     "format": "utf8" } }
192 # <- { "return": "abcdefgh" }
193 #
194 ##
195 { 'command': 'ringbuf-read',
196   'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
197   'returns': 'str' }
198
199 ##
200 # @ChardevCommon:
201 #
202 # Configuration shared across all chardev backends
203 #
204 # @logfile: The name of a logfile to save output
205 # @logappend: true to append instead of truncate
206 #             (default to false to truncate)
207 #
208 # Since: 2.6
209 ##
210 { 'struct': 'ChardevCommon',
211   'data': { '*logfile': 'str',
212             '*logappend': 'bool' } }
213
214 ##
215 # @ChardevFile:
216 #
217 # Configuration info for file chardevs.
218 #
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)
223 #
224 # Since: 1.4
225 ##
226 { 'struct': 'ChardevFile',
227   'data': { '*in': 'str',
228             'out': 'str',
229             '*append': 'bool' },
230   'base': 'ChardevCommon' }
231
232 ##
233 # @ChardevHostdev:
234 #
235 # Configuration info for device and pipe chardevs.
236 #
237 # @device: The name of the special file for the device,
238 #          i.e. /dev/ttyS0 on Unix or COM1: on Windows
239 #
240 # Since: 1.4
241 ##
242 { 'struct': 'ChardevHostdev',
243   'data': { 'device': 'str' },
244   'base': 'ChardevCommon' }
245
246 ##
247 # @ChardevSocket:
248 #
249 # Configuration info for (stream) socket chardevs.
250 #
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)
274 #
275 # Since: 1.4
276 ##
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' }
289
290 ##
291 # @ChardevUdp:
292 #
293 # Configuration info for datagram socket chardevs.
294 #
295 # @remote: remote address
296 # @local: local address
297 #
298 # Since: 1.5
299 ##
300 { 'struct': 'ChardevUdp',
301   'data': { 'remote': 'SocketAddressLegacy',
302             '*local': 'SocketAddressLegacy' },
303   'base': 'ChardevCommon' }
304
305 ##
306 # @ChardevMux:
307 #
308 # Configuration info for mux chardevs.
309 #
310 # @chardev: name of the base chardev.
311 #
312 # Since: 1.5
313 ##
314 { 'struct': 'ChardevMux',
315   'data': { 'chardev': 'str' },
316   'base': 'ChardevCommon' }
317
318 ##
319 # @ChardevStdio:
320 #
321 # Configuration info for stdio chardevs.
322 #
323 # @signal: Allow signals (such as SIGINT triggered by ^C)
324 #          be delivered to qemu.  Default: true in -nographic mode,
325 #          false otherwise.
326 #
327 # Since: 1.5
328 ##
329 { 'struct': 'ChardevStdio',
330   'data': { '*signal': 'bool' },
331   'base': 'ChardevCommon' }
332
333
334 ##
335 # @ChardevSpiceChannel:
336 #
337 # Configuration info for spice vm channel chardevs.
338 #
339 # @type: kind of channel (for example vdagent).
340 #
341 # Since: 1.5
342 ##
343 { 'struct': 'ChardevSpiceChannel',
344   'data': { 'type': 'str' },
345   'base': 'ChardevCommon',
346   'if': 'defined(CONFIG_SPICE)' }
347
348 ##
349 # @ChardevSpicePort:
350 #
351 # Configuration info for spice port chardevs.
352 #
353 # @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
354 #
355 # Since: 1.5
356 ##
357 { 'struct': 'ChardevSpicePort',
358   'data': { 'fqdn': 'str' },
359   'base': 'ChardevCommon',
360   'if': 'defined(CONFIG_SPICE)' }
361
362 ##
363 # @ChardevVC:
364 #
365 # Configuration info for virtual console chardevs.
366 #
367 # @width:  console width,  in pixels
368 # @height: console height, in pixels
369 # @cols:   console width,  in chars
370 # @rows:   console height, in chars
371 #
372 # Since: 1.5
373 ##
374 { 'struct': 'ChardevVC',
375   'data': { '*width': 'int',
376             '*height': 'int',
377             '*cols': 'int',
378             '*rows': 'int' },
379   'base': 'ChardevCommon' }
380
381 ##
382 # @ChardevRingbuf:
383 #
384 # Configuration info for ring buffer chardevs.
385 #
386 # @size: ring buffer size, must be power of two, default is 65536
387 #
388 # Since: 1.5
389 ##
390 { 'struct': 'ChardevRingbuf',
391   'data': { '*size': 'int' },
392   'base': 'ChardevCommon' }
393
394 ##
395 # @ChardevBackend:
396 #
397 # Configuration info for the new chardev backend.
398 #
399 # Since: 1.4 (testdev since 2.2, wctablet since 2.9)
400 ##
401 { 'union': 'ChardevBackend',
402   'data': { 'file': 'ChardevFile',
403             'serial': 'ChardevHostdev',
404             'parallel': 'ChardevHostdev',
405             'pipe': 'ChardevHostdev',
406             'socket': 'ChardevSocket',
407             'udp': 'ChardevUdp',
408             'pty': 'ChardevCommon',
409             'null': 'ChardevCommon',
410             'mux': 'ChardevMux',
411             'msmouse': 'ChardevCommon',
412             'wctablet': 'ChardevCommon',
413             'braille': 'ChardevCommon',
414             'testdev': 'ChardevCommon',
415             'stdio': 'ChardevStdio',
416             'console': 'ChardevCommon',
417             'spicevmc': { 'type': 'ChardevSpiceChannel',
418                           'if': 'defined(CONFIG_SPICE)' },
419             'spiceport': { 'type': 'ChardevSpicePort',
420                            'if': 'defined(CONFIG_SPICE)' },
421             'vc': 'ChardevVC',
422             'ringbuf': 'ChardevRingbuf',
423             # next one is just for compatibility
424             'memory': 'ChardevRingbuf' } }
425
426 ##
427 # @ChardevReturn:
428 #
429 # Return info about the chardev backend just created.
430 #
431 # @pty: name of the slave pseudoterminal device, present if
432 #       and only if a chardev of type 'pty' was created
433 #
434 # Since: 1.4
435 ##
436 { 'struct' : 'ChardevReturn',
437   'data': { '*pty': 'str' } }
438
439 ##
440 # @chardev-add:
441 #
442 # Add a character device backend
443 #
444 # @id: the chardev's ID, must be unique
445 # @backend: backend type and parameters
446 #
447 # Returns: ChardevReturn.
448 #
449 # Since: 1.4
450 #
451 # Example:
452 #
453 # -> { "execute" : "chardev-add",
454 #      "arguments" : { "id" : "foo",
455 #                      "backend" : { "type" : "null", "data" : {} } } }
456 # <- { "return": {} }
457 #
458 # -> { "execute" : "chardev-add",
459 #      "arguments" : { "id" : "bar",
460 #                      "backend" : { "type" : "file",
461 #                                    "data" : { "out" : "/tmp/bar.log" } } } }
462 # <- { "return": {} }
463 #
464 # -> { "execute" : "chardev-add",
465 #      "arguments" : { "id" : "baz",
466 #                      "backend" : { "type" : "pty", "data" : {} } } }
467 # <- { "return": { "pty" : "/dev/pty/42" } }
468 #
469 ##
470 { 'command': 'chardev-add',
471   'data': { 'id': 'str',
472             'backend': 'ChardevBackend' },
473   'returns': 'ChardevReturn' }
474
475 ##
476 # @chardev-change:
477 #
478 # Change a character device backend
479 #
480 # @id: the chardev's ID, must exist
481 # @backend: new backend type and parameters
482 #
483 # Returns: ChardevReturn.
484 #
485 # Since: 2.10
486 #
487 # Example:
488 #
489 # -> { "execute" : "chardev-change",
490 #      "arguments" : { "id" : "baz",
491 #                      "backend" : { "type" : "pty", "data" : {} } } }
492 # <- { "return": { "pty" : "/dev/pty/42" } }
493 #
494 # -> {"execute" : "chardev-change",
495 #     "arguments" : {
496 #         "id" : "charchannel2",
497 #         "backend" : {
498 #             "type" : "socket",
499 #             "data" : {
500 #                 "addr" : {
501 #                     "type" : "unix" ,
502 #                     "data" : {
503 #                         "path" : "/tmp/charchannel2.socket"
504 #                     }
505 #                  },
506 #                  "server" : true,
507 #                  "wait" : false }}}}
508 # <- {"return": {}}
509 #
510 ##
511 { 'command': 'chardev-change',
512   'data': { 'id': 'str',
513             'backend': 'ChardevBackend' },
514   'returns': 'ChardevReturn' }
515
516 ##
517 # @chardev-remove:
518 #
519 # Remove a character device backend
520 #
521 # @id: the chardev's ID, must exist and not be in use
522 #
523 # Returns: Nothing on success
524 #
525 # Since: 1.4
526 #
527 # Example:
528 #
529 # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
530 # <- { "return": {} }
531 #
532 ##
533 { 'command': 'chardev-remove',
534   'data': { 'id': 'str' } }
535
536 ##
537 # @chardev-send-break:
538 #
539 # Send a break to a character device
540 #
541 # @id: the chardev's ID, must exist
542 #
543 # Returns: Nothing on success
544 #
545 # Since: 2.10
546 #
547 # Example:
548 #
549 # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
550 # <- { "return": {} }
551 #
552 ##
553 { 'command': 'chardev-send-break',
554   'data': { 'id': 'str' } }
555
556 ##
557 # @VSERPORT_CHANGE:
558 #
559 # Emitted when the guest opens or closes a virtio-serial port.
560 #
561 # @id: device identifier of the virtio-serial port
562 #
563 # @open: true if the guest has opened the virtio-serial port
564 #
565 # Note: This event is rate-limited.
566 #
567 # Since: 2.1
568 #
569 # Example:
570 #
571 # <- { "event": "VSERPORT_CHANGE",
572 #      "data": { "id": "channel0", "open": true },
573 #      "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
574 #
575 ##
576 { 'event': 'VSERPORT_CHANGE',
577   'data': { 'id': 'str',
578             'open': 'bool' } }