Merge remote-tracking branch 'remotes/ehabkost/tags/python-next-pull-request' into...
[qemu.git] / qapi / char.json
blobae19dcd1ed11209cf355700a12c26d93a409fad8
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', 'data': {'label': 'str',
29                                   'filename': 'str',
30                                   'frontend-open': 'bool'} }
33 # @query-chardev:
35 # Returns information about current character devices.
37 # Returns: a list of @ChardevInfo
39 # Since: 0.14.0
41 # Example:
43 # -> { "execute": "query-chardev" }
44 # <- {
45 #       "return": [
46 #          {
47 #             "label": "charchannel0",
48 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
49 #             "frontend-open": false
50 #          },
51 #          {
52 #             "label": "charmonitor",
53 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
54 #             "frontend-open": true
55 #          },
56 #          {
57 #             "label": "charserial0",
58 #             "filename": "pty:/dev/pts/2",
59 #             "frontend-open": true
60 #          }
61 #       ]
62 #    }
65 { 'command': 'query-chardev', 'returns': ['ChardevInfo'] }
68 # @ChardevBackendInfo:
70 # Information about a character device backend
72 # @name: The backend name
74 # Since: 2.0
76 { 'struct': 'ChardevBackendInfo', 'data': {'name': 'str'} }
79 # @query-chardev-backends:
81 # Returns information about character device backends.
83 # Returns: a list of @ChardevBackendInfo
85 # Since: 2.0
87 # Example:
89 # -> { "execute": "query-chardev-backends" }
90 # <- {
91 #       "return":[
92 #          {
93 #             "name":"udp"
94 #          },
95 #          {
96 #             "name":"tcp"
97 #          },
98 #          {
99 #             "name":"unix"
100 #          },
101 #          {
102 #             "name":"spiceport"
103 #          }
104 #       ]
105 #    }
108 { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
111 # @DataFormat:
113 # An enumeration of data format.
115 # @utf8: Data is a UTF-8 string (RFC 3629)
117 # @base64: Data is Base64 encoded binary (RFC 3548)
119 # Since: 1.4
121 { 'enum': 'DataFormat',
122   'data': [ 'utf8', 'base64' ] }
125 # @ringbuf-write:
127 # Write to a ring buffer character device.
129 # @device: the ring buffer character device name
131 # @data: data to write
133 # @format: data encoding (default 'utf8').
134 #          - base64: data must be base64 encoded text.  Its binary
135 #            decoding gets written.
136 #          - utf8: data's UTF-8 encoding is written
137 #          - data itself is always Unicode regardless of format, like
138 #            any other string.
140 # Returns: Nothing on success
142 # Since: 1.4
144 # Example:
146 # -> { "execute": "ringbuf-write",
147 #      "arguments": { "device": "foo",
148 #                     "data": "abcdefgh",
149 #                     "format": "utf8" } }
150 # <- { "return": {} }
153 { 'command': 'ringbuf-write',
154   'data': {'device': 'str', 'data': 'str',
155            '*format': 'DataFormat'} }
158 # @ringbuf-read:
160 # Read from a ring buffer character device.
162 # @device: the ring buffer character device name
164 # @size: how many bytes to read at most
166 # @format: data encoding (default 'utf8').
167 #          - base64: the data read is returned in base64 encoding.
168 #          - utf8: the data read is interpreted as UTF-8.
169 #            Bug: can screw up when the buffer contains invalid UTF-8
170 #            sequences, NUL characters, after the ring buffer lost
171 #            data, and when reading stops because the size limit is
172 #            reached.
173 #          - The return value is always Unicode regardless of format,
174 #            like any other string.
176 # Returns: data read from the device
178 # Since: 1.4
180 # Example:
182 # -> { "execute": "ringbuf-read",
183 #      "arguments": { "device": "foo",
184 #                     "size": 1000,
185 #                     "format": "utf8" } }
186 # <- { "return": "abcdefgh" }
189 { 'command': 'ringbuf-read',
190   'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
191   'returns': 'str' }
194 # @ChardevCommon:
196 # Configuration shared across all chardev backends
198 # @logfile: The name of a logfile to save output
199 # @logappend: true to append instead of truncate
200 #             (default to false to truncate)
202 # Since: 2.6
204 { 'struct': 'ChardevCommon', 'data': { '*logfile': 'str',
205                                        '*logappend': 'bool' } }
208 # @ChardevFile:
210 # Configuration info for file chardevs.
212 # @in:  The name of the input file
213 # @out: The name of the output file
214 # @append: Open the file in append mode (default false to
215 #          truncate) (Since 2.6)
217 # Since: 1.4
219 { 'struct': 'ChardevFile', 'data': { '*in' : 'str',
220                                    'out' : 'str',
221                                    '*append': 'bool' },
222   'base': 'ChardevCommon' }
225 # @ChardevHostdev:
227 # Configuration info for device and pipe chardevs.
229 # @device: The name of the special file for the device,
230 #          i.e. /dev/ttyS0 on Unix or COM1: on Windows
232 # Since: 1.4
234 { 'struct': 'ChardevHostdev', 'data': { 'device' : 'str' },
235   'base': 'ChardevCommon' }
238 # @ChardevSocket:
240 # Configuration info for (stream) socket chardevs.
242 # @addr: socket address to listen on (server=true)
243 #        or connect to (server=false)
244 # @tls-creds: the ID of the TLS credentials object (since 2.6)
245 # @server: create server socket (default: true)
246 # @wait: wait for incoming connection on server
247 #        sockets (default: false).
248 # @nodelay: set TCP_NODELAY socket option (default: false)
249 # @telnet: enable telnet protocol on server
250 #          sockets (default: false)
251 # @tn3270: enable tn3270 protocol on server
252 #          sockets (default: false) (Since: 2.10)
253 # @reconnect: For a client socket, if a socket is disconnected,
254 #          then attempt a reconnect after the given number of seconds.
255 #          Setting this to zero disables this function. (default: 0)
256 #          (Since: 2.2)
258 # Since: 1.4
260 { 'struct': 'ChardevSocket', 'data': { 'addr'       : 'SocketAddressLegacy',
261                                      '*tls-creds'  : 'str',
262                                      '*server'    : 'bool',
263                                      '*wait'      : 'bool',
264                                      '*nodelay'   : 'bool',
265                                      '*telnet'    : 'bool',
266                                      '*tn3270'    : 'bool',
267                                      '*reconnect' : 'int' },
268   'base': 'ChardevCommon' }
271 # @ChardevUdp:
273 # Configuration info for datagram socket chardevs.
275 # @remote: remote address
276 # @local: local address
278 # Since: 1.5
280 { 'struct': 'ChardevUdp', 'data': { 'remote' : 'SocketAddressLegacy',
281                                   '*local' : 'SocketAddressLegacy' },
282   'base': 'ChardevCommon' }
285 # @ChardevMux:
287 # Configuration info for mux chardevs.
289 # @chardev: name of the base chardev.
291 # Since: 1.5
293 { 'struct': 'ChardevMux', 'data': { 'chardev' : 'str' },
294   'base': 'ChardevCommon' }
297 # @ChardevStdio:
299 # Configuration info for stdio chardevs.
301 # @signal: Allow signals (such as SIGINT triggered by ^C)
302 #          be delivered to qemu.  Default: true in -nographic mode,
303 #          false otherwise.
305 # Since: 1.5
307 { 'struct': 'ChardevStdio', 'data': { '*signal' : 'bool' },
308   'base': 'ChardevCommon' }
312 # @ChardevSpiceChannel:
314 # Configuration info for spice vm channel chardevs.
316 # @type: kind of channel (for example vdagent).
318 # Since: 1.5
320 { 'struct': 'ChardevSpiceChannel', 'data': { 'type'  : 'str' },
321   'base': 'ChardevCommon' }
324 # @ChardevSpicePort:
326 # Configuration info for spice port chardevs.
328 # @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
330 # Since: 1.5
332 { 'struct': 'ChardevSpicePort', 'data': { 'fqdn'  : 'str' },
333   'base': 'ChardevCommon' }
336 # @ChardevVC:
338 # Configuration info for virtual console chardevs.
340 # @width:  console width,  in pixels
341 # @height: console height, in pixels
342 # @cols:   console width,  in chars
343 # @rows:   console height, in chars
345 # Since: 1.5
347 { 'struct': 'ChardevVC', 'data': { '*width'  : 'int',
348                                  '*height' : 'int',
349                                  '*cols'   : 'int',
350                                  '*rows'   : 'int' },
351   'base': 'ChardevCommon' }
354 # @ChardevRingbuf:
356 # Configuration info for ring buffer chardevs.
358 # @size: ring buffer size, must be power of two, default is 65536
360 # Since: 1.5
362 { 'struct': 'ChardevRingbuf', 'data': { '*size'  : 'int' },
363   'base': 'ChardevCommon' }
366 # @ChardevBackend:
368 # Configuration info for the new chardev backend.
370 # Since: 1.4 (testdev since 2.2, wctablet since 2.9)
372 { 'union': 'ChardevBackend', 'data': { 'file'   : 'ChardevFile',
373                                        'serial' : 'ChardevHostdev',
374                                        'parallel': 'ChardevHostdev',
375                                        'pipe'   : 'ChardevHostdev',
376                                        'socket' : 'ChardevSocket',
377                                        'udp'    : 'ChardevUdp',
378                                        'pty'    : 'ChardevCommon',
379                                        'null'   : 'ChardevCommon',
380                                        'mux'    : 'ChardevMux',
381                                        'msmouse': 'ChardevCommon',
382                                        'wctablet' : 'ChardevCommon',
383                                        'braille': 'ChardevCommon',
384                                        'testdev': 'ChardevCommon',
385                                        'stdio'  : 'ChardevStdio',
386                                        'console': 'ChardevCommon',
387                                        'spicevmc' : 'ChardevSpiceChannel',
388                                        'spiceport' : 'ChardevSpicePort',
389                                        'vc'     : 'ChardevVC',
390                                        'ringbuf': 'ChardevRingbuf',
391                                        # next one is just for compatibility
392                                        'memory' : 'ChardevRingbuf' } }
395 # @ChardevReturn:
397 # Return info about the chardev backend just created.
399 # @pty: name of the slave pseudoterminal device, present if
400 #       and only if a chardev of type 'pty' was created
402 # Since: 1.4
404 { 'struct' : 'ChardevReturn', 'data': { '*pty' : 'str' } }
407 # @chardev-add:
409 # Add a character device backend
411 # @id: the chardev's ID, must be unique
412 # @backend: backend type and parameters
414 # Returns: ChardevReturn.
416 # Since: 1.4
418 # Example:
420 # -> { "execute" : "chardev-add",
421 #      "arguments" : { "id" : "foo",
422 #                      "backend" : { "type" : "null", "data" : {} } } }
423 # <- { "return": {} }
425 # -> { "execute" : "chardev-add",
426 #      "arguments" : { "id" : "bar",
427 #                      "backend" : { "type" : "file",
428 #                                    "data" : { "out" : "/tmp/bar.log" } } } }
429 # <- { "return": {} }
431 # -> { "execute" : "chardev-add",
432 #      "arguments" : { "id" : "baz",
433 #                      "backend" : { "type" : "pty", "data" : {} } } }
434 # <- { "return": { "pty" : "/dev/pty/42" } }
437 { 'command': 'chardev-add', 'data': {'id'      : 'str',
438                                      'backend' : 'ChardevBackend' },
439   'returns': 'ChardevReturn' }
442 # @chardev-change:
444 # Change a character device backend
446 # @id: the chardev's ID, must exist
447 # @backend: new backend type and parameters
449 # Returns: ChardevReturn.
451 # Since: 2.10
453 # Example:
455 # -> { "execute" : "chardev-change",
456 #      "arguments" : { "id" : "baz",
457 #                      "backend" : { "type" : "pty", "data" : {} } } }
458 # <- { "return": { "pty" : "/dev/pty/42" } }
460 # -> {"execute" : "chardev-change",
461 #     "arguments" : {
462 #         "id" : "charchannel2",
463 #         "backend" : {
464 #             "type" : "socket",
465 #             "data" : {
466 #                 "addr" : {
467 #                     "type" : "unix" ,
468 #                     "data" : {
469 #                         "path" : "/tmp/charchannel2.socket"
470 #                     }
471 #                  },
472 #                  "server" : true,
473 #                  "wait" : false }}}}
474 # <- {"return": {}}
477 { 'command': 'chardev-change', 'data': {'id'      : 'str',
478                                         'backend' : 'ChardevBackend' },
479   'returns': 'ChardevReturn' }
482 # @chardev-remove:
484 # Remove a character device backend
486 # @id: the chardev's ID, must exist and not be in use
488 # Returns: Nothing on success
490 # Since: 1.4
492 # Example:
494 # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
495 # <- { "return": {} }
498 { 'command': 'chardev-remove', 'data': {'id': 'str'} }
501 # @chardev-send-break:
503 # Send a break to a character device
505 # @id: the chardev's ID, must exist
507 # Returns: Nothing on success
509 # Since: 2.10
511 # Example:
513 # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
514 # <- { "return": {} }
517 { 'command': 'chardev-send-break', 'data': {'id': 'str'} }
520 # @VSERPORT_CHANGE:
522 # Emitted when the guest opens or closes a virtio-serial port.
524 # @id: device identifier of the virtio-serial port
526 # @open: true if the guest has opened the virtio-serial port
528 # Since: 2.1
530 # Example:
532 # <- { "event": "VSERPORT_CHANGE",
533 #      "data": { "id": "channel0", "open": true },
534 #      "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
537 { 'event': 'VSERPORT_CHANGE',
538   'data': { 'id': 'str', 'open': 'bool' } }