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', 'data': {'label': 'str',
  29                                   'filename': 'str',
  30                                   'frontend-open': 'bool'} }
  31
  32 ##
  33 # @query-chardev:
  34 #
  35 # Returns information about current character devices.
  36 #
  37 # Returns: a list of @ChardevInfo
  38 #
  39 # Since: 0.14.0
  40 #
  41 # Example:
  42 #
  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 #    }
  63 #
  64 ##
  65 { 'command': 'query-chardev', 'returns': ['ChardevInfo'],
  66   'allow-preconfig': true }
  67
  68 ##
  69 # @ChardevBackendInfo:
  70 #
  71 # Information about a character device backend
  72 #
  73 # @name: The backend name
  74 #
  75 # Since: 2.0
  76 ##
  77 { 'struct': 'ChardevBackendInfo', 'data': {'name': 'str'} }
  78
  79 ##
  80 # @query-chardev-backends:
  81 #
  82 # Returns information about character device backends.
  83 #
  84 # Returns: a list of @ChardevBackendInfo
  85 #
  86 # Since: 2.0
  87 #
  88 # Example:
  89 #
  90 # -> { "execute": "query-chardev-backends" }
  91 # <- {
  92 #       "return":[
  93 #          {
  94 #             "name":"udp"
  95 #          },
  96 #          {
  97 #             "name":"tcp"
  98 #          },
  99 #          {
 100 #             "name":"unix"
 101 #          },
 102 #          {
 103 #             "name":"spiceport"
 104 #          }
 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 #          - base64: data must be base64 encoded text.  Its binary
 136 #            decoding gets written.
 137 #          - utf8: data's UTF-8 encoding is written
 138 #          - data itself is always Unicode regardless of format, like
 139 #            any other string.
 140 #
 141 # Returns: Nothing on success
 142 #
 143 # Since: 1.4
 144 #
 145 # Example:
 146 #
 147 # -> { "execute": "ringbuf-write",
 148 #      "arguments": { "device": "foo",
 149 #                     "data": "abcdefgh",
 150 #                     "format": "utf8" } }
 151 # <- { "return": {} }
 152 #
 153 ##
 154 { 'command': 'ringbuf-write',
 155   'data': {'device': 'str', 'data': 'str',
 156            '*format': 'DataFormat'} }
 157
 158 ##
 159 # @ringbuf-read:
 160 #
 161 # Read from a ring buffer character device.
 162 #
 163 # @device: the ring buffer character device name
 164 #
 165 # @size: how many bytes to read at most
 166 #
 167 # @format: data encoding (default 'utf8').
 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
 172 #            data, and when reading stops because the size limit is
 173 #            reached.
 174 #          - The return value is always Unicode regardless of format,
 175 #            like any other string.
 176 #
 177 # Returns: data read from the device
 178 #
 179 # Since: 1.4
 180 #
 181 # Example:
 182 #
 183 # -> { "execute": "ringbuf-read",
 184 #      "arguments": { "device": "foo",
 185 #                     "size": 1000,
 186 #                     "format": "utf8" } }
 187 # <- { "return": "abcdefgh" }
 188 #
 189 ##
 190 { 'command': 'ringbuf-read',
 191   'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
 192   'returns': 'str' }
 193
 194 ##
 195 # @ChardevCommon:
 196 #
 197 # Configuration shared across all chardev backends
 198 #
 199 # @logfile: The name of a logfile to save output
 200 # @logappend: true to append instead of truncate
 201 #             (default to false to truncate)
 202 #
 203 # Since: 2.6
 204 ##
 205 { 'struct': 'ChardevCommon', '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 # @out: The name of the output file
 215 # @append: Open the file in append mode (default false to
 216 #          truncate) (Since 2.6)
 217 #
 218 # Since: 1.4
 219 ##
 220 { 'struct': 'ChardevFile', 'data': { '*in' : 'str',
 221                                    'out' : 'str',
 222                                    '*append': 'bool' },
 223   'base': 'ChardevCommon' }
 224
 225 ##
 226 # @ChardevHostdev:
 227 #
 228 # Configuration info for device and pipe chardevs.
 229 #
 230 # @device: The name of the special file for the device,
 231 #          i.e. /dev/ttyS0 on Unix or COM1: on Windows
 232 #
 233 # Since: 1.4
 234 ##
 235 { 'struct': 'ChardevHostdev', 'data': { 'device' : 'str' },
 236   'base': 'ChardevCommon' }
 237
 238 ##
 239 # @ChardevSocket:
 240 #
 241 # Configuration info for (stream) socket chardevs.
 242 #
 243 # @addr: socket address to listen on (server=true)
 244 #        or connect to (server=false)
 245 # @tls-creds: the ID of the TLS credentials object (since 2.6)
 246 # @server: create server socket (default: true)
 247 # @wait: wait for incoming connection on server
 248 #        sockets (default: false).
 249 # @nodelay: set TCP_NODELAY socket option (default: false)
 250 # @telnet: enable telnet protocol on server
 251 #          sockets (default: false)
 252 # @tn3270: enable tn3270 protocol on server
 253 #          sockets (default: false) (Since: 2.10)
 254 # @websocket: enable websocket protocol on server
 255 #           sockets (default: false) (Since: 3.1)
 256 # @reconnect: For a client socket, if a socket is disconnected,
 257 #          then attempt a reconnect after the given number of seconds.
 258 #          Setting this to zero disables this function. (default: 0)
 259 #          (Since: 2.2)
 260 #
 261 # Since: 1.4
 262 ##
 263 { 'struct': 'ChardevSocket', 'data': { 'addr'       : 'SocketAddressLegacy',
 264                                      '*tls-creds'  : 'str',
 265                                      '*server'    : 'bool',
 266                                      '*wait'      : 'bool',
 267                                      '*nodelay'   : 'bool',
 268                                      '*telnet'    : 'bool',
 269                                      '*tn3270'    : 'bool',
 270                                      '*websocket' : 'bool',
 271                                      '*reconnect' : 'int' },
 272   'base': 'ChardevCommon' }
 273
 274 ##
 275 # @ChardevUdp:
 276 #
 277 # Configuration info for datagram socket chardevs.
 278 #
 279 # @remote: remote address
 280 # @local: local address
 281 #
 282 # Since: 1.5
 283 ##
 284 { 'struct': 'ChardevUdp', 'data': { 'remote' : 'SocketAddressLegacy',
 285                                   '*local' : 'SocketAddressLegacy' },
 286   'base': 'ChardevCommon' }
 287
 288 ##
 289 # @ChardevMux:
 290 #
 291 # Configuration info for mux chardevs.
 292 #
 293 # @chardev: name of the base chardev.
 294 #
 295 # Since: 1.5
 296 ##
 297 { 'struct': 'ChardevMux', 'data': { 'chardev' : 'str' },
 298   'base': 'ChardevCommon' }
 299
 300 ##
 301 # @ChardevStdio:
 302 #
 303 # Configuration info for stdio chardevs.
 304 #
 305 # @signal: Allow signals (such as SIGINT triggered by ^C)
 306 #          be delivered to qemu.  Default: true in -nographic mode,
 307 #          false otherwise.
 308 #
 309 # Since: 1.5
 310 ##
 311 { 'struct': 'ChardevStdio', 'data': { '*signal' : 'bool' },
 312   'base': 'ChardevCommon' }
 313
 314
 315 ##
 316 # @ChardevSpiceChannel:
 317 #
 318 # Configuration info for spice vm channel chardevs.
 319 #
 320 # @type: kind of channel (for example vdagent).
 321 #
 322 # Since: 1.5
 323 ##
 324 { 'struct': 'ChardevSpiceChannel', 'data': { 'type'  : 'str' },
 325   'base': 'ChardevCommon' }
 326 # TODO: 'if': 'defined(CONFIG_SPICE)'
 327
 328 ##
 329 # @ChardevSpicePort:
 330 #
 331 # Configuration info for spice port chardevs.
 332 #
 333 # @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
 334 #
 335 # Since: 1.5
 336 ##
 337 { 'struct': 'ChardevSpicePort', 'data': { 'fqdn'  : 'str' },
 338   'base': 'ChardevCommon' }
 339 # TODO: 'if': 'defined(CONFIG_SPICE)'
 340
 341 ##
 342 # @ChardevVC:
 343 #
 344 # Configuration info for virtual console chardevs.
 345 #
 346 # @width:  console width,  in pixels
 347 # @height: console height, in pixels
 348 # @cols:   console width,  in chars
 349 # @rows:   console height, in chars
 350 #
 351 # Since: 1.5
 352 ##
 353 { 'struct': 'ChardevVC', 'data': { '*width'  : 'int',
 354                                  '*height' : 'int',
 355                                  '*cols'   : 'int',
 356                                  '*rows'   : 'int' },
 357   'base': 'ChardevCommon' }
 358
 359 ##
 360 # @ChardevRingbuf:
 361 #
 362 # Configuration info for ring buffer chardevs.
 363 #
 364 # @size: ring buffer size, must be power of two, default is 65536
 365 #
 366 # Since: 1.5
 367 ##
 368 { 'struct': 'ChardevRingbuf', 'data': { '*size'  : 'int' },
 369   'base': 'ChardevCommon' }
 370
 371 ##
 372 # @ChardevBackend:
 373 #
 374 # Configuration info for the new chardev backend.
 375 #
 376 # Since: 1.4 (testdev since 2.2, wctablet since 2.9)
 377 ##
 378 { 'union': 'ChardevBackend', 'data': { 'file'   : 'ChardevFile',
 379                                        'serial' : 'ChardevHostdev',
 380                                        'parallel': 'ChardevHostdev',
 381                                        'pipe'   : 'ChardevHostdev',
 382                                        'socket' : 'ChardevSocket',
 383                                        'udp'    : 'ChardevUdp',
 384                                        'pty'    : 'ChardevCommon',
 385                                        'null'   : 'ChardevCommon',
 386                                        'mux'    : 'ChardevMux',
 387                                        'msmouse': 'ChardevCommon',
 388                                        'wctablet' : 'ChardevCommon',
 389                                        'braille': 'ChardevCommon',
 390                                        'testdev': 'ChardevCommon',
 391                                        'stdio'  : 'ChardevStdio',
 392                                        'console': 'ChardevCommon',
 393                                        'spicevmc': 'ChardevSpiceChannel',
 394 # TODO: { 'type': 'ChardevSpiceChannel', 'if': 'defined(CONFIG_SPICE)' },
 395                                        'spiceport': 'ChardevSpicePort',
 396 # TODO: { 'type': 'ChardevSpicePort', 'if': 'defined(CONFIG_SPICE)' },
 397                                        'vc'     : 'ChardevVC',
 398                                        'ringbuf': 'ChardevRingbuf',
 399                                        # next one is just for compatibility
 400                                        'memory' : 'ChardevRingbuf' } }
 401
 402 ##
 403 # @ChardevReturn:
 404 #
 405 # Return info about the chardev backend just created.
 406 #
 407 # @pty: name of the slave pseudoterminal device, present if
 408 #       and only if a chardev of type 'pty' was created
 409 #
 410 # Since: 1.4
 411 ##
 412 { 'struct' : 'ChardevReturn', 'data': { '*pty' : 'str' } }
 413
 414 ##
 415 # @chardev-add:
 416 #
 417 # Add a character device backend
 418 #
 419 # @id: the chardev's ID, must be unique
 420 # @backend: backend type and parameters
 421 #
 422 # Returns: ChardevReturn.
 423 #
 424 # Since: 1.4
 425 #
 426 # Example:
 427 #
 428 # -> { "execute" : "chardev-add",
 429 #      "arguments" : { "id" : "foo",
 430 #                      "backend" : { "type" : "null", "data" : {} } } }
 431 # <- { "return": {} }
 432 #
 433 # -> { "execute" : "chardev-add",
 434 #      "arguments" : { "id" : "bar",
 435 #                      "backend" : { "type" : "file",
 436 #                                    "data" : { "out" : "/tmp/bar.log" } } } }
 437 # <- { "return": {} }
 438 #
 439 # -> { "execute" : "chardev-add",
 440 #      "arguments" : { "id" : "baz",
 441 #                      "backend" : { "type" : "pty", "data" : {} } } }
 442 # <- { "return": { "pty" : "/dev/pty/42" } }
 443 #
 444 ##
 445 { 'command': 'chardev-add', 'data': {'id'      : 'str',
 446                                      'backend' : 'ChardevBackend' },
 447   'returns': 'ChardevReturn' }
 448
 449 ##
 450 # @chardev-change:
 451 #
 452 # Change a character device backend
 453 #
 454 # @id: the chardev's ID, must exist
 455 # @backend: new backend type and parameters
 456 #
 457 # Returns: ChardevReturn.
 458 #
 459 # Since: 2.10
 460 #
 461 # Example:
 462 #
 463 # -> { "execute" : "chardev-change",
 464 #      "arguments" : { "id" : "baz",
 465 #                      "backend" : { "type" : "pty", "data" : {} } } }
 466 # <- { "return": { "pty" : "/dev/pty/42" } }
 467 #
 468 # -> {"execute" : "chardev-change",
 469 #     "arguments" : {
 470 #         "id" : "charchannel2",
 471 #         "backend" : {
 472 #             "type" : "socket",
 473 #             "data" : {
 474 #                 "addr" : {
 475 #                     "type" : "unix" ,
 476 #                     "data" : {
 477 #                         "path" : "/tmp/charchannel2.socket"
 478 #                     }
 479 #                  },
 480 #                  "server" : true,
 481 #                  "wait" : false }}}}
 482 # <- {"return": {}}
 483 #
 484 ##
 485 { 'command': 'chardev-change', 'data': {'id'      : 'str',
 486                                         'backend' : 'ChardevBackend' },
 487   'returns': 'ChardevReturn' }
 488
 489 ##
 490 # @chardev-remove:
 491 #
 492 # Remove a character device backend
 493 #
 494 # @id: the chardev's ID, must exist and not be in use
 495 #
 496 # Returns: Nothing on success
 497 #
 498 # Since: 1.4
 499 #
 500 # Example:
 501 #
 502 # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
 503 # <- { "return": {} }
 504 #
 505 ##
 506 { 'command': 'chardev-remove', 'data': {'id': 'str'} }
 507
 508 ##
 509 # @chardev-send-break:
 510 #
 511 # Send a break to a character device
 512 #
 513 # @id: the chardev's ID, must exist
 514 #
 515 # Returns: Nothing on success
 516 #
 517 # Since: 2.10
 518 #
 519 # Example:
 520 #
 521 # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
 522 # <- { "return": {} }
 523 #
 524 ##
 525 { 'command': 'chardev-send-break', 'data': {'id': 'str'} }
 526
 527 ##
 528 # @VSERPORT_CHANGE:
 529 #
 530 # Emitted when the guest opens or closes a virtio-serial port.
 531 #
 532 # @id: device identifier of the virtio-serial port
 533 #
 534 # @open: true if the guest has opened the virtio-serial port
 535 #
 536 # Since: 2.1
 537 #
 538 # Example:
 539 #
 540 # <- { "event": "VSERPORT_CHANGE",
 541 #      "data": { "id": "channel0", "open": true },
 542 #      "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
 543 #
 544 ##
 545 { 'event': 'VSERPORT_CHANGE',
 546   'data': { 'id': 'str', 'open': 'bool' } }