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