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 # @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)
 272 #
 273 # Since: 1.4
 274 ##
 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' }
 287
 288 ##
 289 # @ChardevUdp:
 290 #
 291 # Configuration info for datagram socket chardevs.
 292 #
 293 # @remote: remote address
 294 # @local: local address
 295 #
 296 # Since: 1.5
 297 ##
 298 { 'struct': 'ChardevUdp',
 299   'data': { 'remote': 'SocketAddressLegacy',
 300             '*local': 'SocketAddressLegacy' },
 301   'base': 'ChardevCommon' }
 302
 303 ##
 304 # @ChardevMux:
 305 #
 306 # Configuration info for mux chardevs.
 307 #
 308 # @chardev: name of the base chardev.
 309 #
 310 # Since: 1.5
 311 ##
 312 { 'struct': 'ChardevMux',
 313   'data': { 'chardev': 'str' },
 314   'base': 'ChardevCommon' }
 315
 316 ##
 317 # @ChardevStdio:
 318 #
 319 # Configuration info for stdio chardevs.
 320 #
 321 # @signal: Allow signals (such as SIGINT triggered by ^C)
 322 #          be delivered to qemu.  Default: true in -nographic mode,
 323 #          false otherwise.
 324 #
 325 # Since: 1.5
 326 ##
 327 { 'struct': 'ChardevStdio',
 328   'data': { '*signal': 'bool' },
 329   'base': 'ChardevCommon' }
 330
 331
 332 ##
 333 # @ChardevSpiceChannel:
 334 #
 335 # Configuration info for spice vm channel chardevs.
 336 #
 337 # @type: kind of channel (for example vdagent).
 338 #
 339 # Since: 1.5
 340 ##
 341 { 'struct': 'ChardevSpiceChannel',
 342   'data': { 'type': 'str' },
 343   'base': 'ChardevCommon',
 344   'if': 'defined(CONFIG_SPICE)' }
 345
 346 ##
 347 # @ChardevSpicePort:
 348 #
 349 # Configuration info for spice port chardevs.
 350 #
 351 # @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
 352 #
 353 # Since: 1.5
 354 ##
 355 { 'struct': 'ChardevSpicePort',
 356   'data': { 'fqdn': 'str' },
 357   'base': 'ChardevCommon',
 358   'if': 'defined(CONFIG_SPICE)' }
 359
 360 ##
 361 # @ChardevVC:
 362 #
 363 # Configuration info for virtual console chardevs.
 364 #
 365 # @width:  console width,  in pixels
 366 # @height: console height, in pixels
 367 # @cols:   console width,  in chars
 368 # @rows:   console height, in chars
 369 #
 370 # Since: 1.5
 371 ##
 372 { 'struct': 'ChardevVC',
 373   'data': { '*width': 'int',
 374             '*height': 'int',
 375             '*cols': 'int',
 376             '*rows': 'int' },
 377   'base': 'ChardevCommon' }
 378
 379 ##
 380 # @ChardevRingbuf:
 381 #
 382 # Configuration info for ring buffer chardevs.
 383 #
 384 # @size: ring buffer size, must be power of two, default is 65536
 385 #
 386 # Since: 1.5
 387 ##
 388 { 'struct': 'ChardevRingbuf',
 389   'data': { '*size': 'int' },
 390   'base': 'ChardevCommon' }
 391
 392 ##
 393 # @ChardevBackend:
 394 #
 395 # Configuration info for the new chardev backend.
 396 #
 397 # Since: 1.4 (testdev since 2.2, wctablet since 2.9)
 398 ##
 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' } }
 423
 424 ##
 425 # @ChardevReturn:
 426 #
 427 # Return info about the chardev backend just created.
 428 #
 429 # @pty: name of the slave pseudoterminal device, present if
 430 #       and only if a chardev of type 'pty' was created
 431 #
 432 # Since: 1.4
 433 ##
 434 { 'struct' : 'ChardevReturn',
 435   'data': { '*pty': 'str' } }
 436
 437 ##
 438 # @chardev-add:
 439 #
 440 # Add a character device backend
 441 #
 442 # @id: the chardev's ID, must be unique
 443 # @backend: backend type and parameters
 444 #
 445 # Returns: ChardevReturn.
 446 #
 447 # Since: 1.4
 448 #
 449 # Example:
 450 #
 451 # -> { "execute" : "chardev-add",
 452 #      "arguments" : { "id" : "foo",
 453 #                      "backend" : { "type" : "null", "data" : {} } } }
 454 # <- { "return": {} }
 455 #
 456 # -> { "execute" : "chardev-add",
 457 #      "arguments" : { "id" : "bar",
 458 #                      "backend" : { "type" : "file",
 459 #                                    "data" : { "out" : "/tmp/bar.log" } } } }
 460 # <- { "return": {} }
 461 #
 462 # -> { "execute" : "chardev-add",
 463 #      "arguments" : { "id" : "baz",
 464 #                      "backend" : { "type" : "pty", "data" : {} } } }
 465 # <- { "return": { "pty" : "/dev/pty/42" } }
 466 #
 467 ##
 468 { 'command': 'chardev-add',
 469   'data': { 'id': 'str',
 470             'backend': 'ChardevBackend' },
 471   'returns': 'ChardevReturn' }
 472
 473 ##
 474 # @chardev-change:
 475 #
 476 # Change a character device backend
 477 #
 478 # @id: the chardev's ID, must exist
 479 # @backend: new backend type and parameters
 480 #
 481 # Returns: ChardevReturn.
 482 #
 483 # Since: 2.10
 484 #
 485 # Example:
 486 #
 487 # -> { "execute" : "chardev-change",
 488 #      "arguments" : { "id" : "baz",
 489 #                      "backend" : { "type" : "pty", "data" : {} } } }
 490 # <- { "return": { "pty" : "/dev/pty/42" } }
 491 #
 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": {}}
 507 #
 508 ##
 509 { 'command': 'chardev-change',
 510   'data': { 'id': 'str',
 511             'backend': 'ChardevBackend' },
 512   'returns': 'ChardevReturn' }
 513
 514 ##
 515 # @chardev-remove:
 516 #
 517 # Remove a character device backend
 518 #
 519 # @id: the chardev's ID, must exist and not be in use
 520 #
 521 # Returns: Nothing on success
 522 #
 523 # Since: 1.4
 524 #
 525 # Example:
 526 #
 527 # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
 528 # <- { "return": {} }
 529 #
 530 ##
 531 { 'command': 'chardev-remove',
 532   'data': { 'id': 'str' } }
 533
 534 ##
 535 # @chardev-send-break:
 536 #
 537 # Send a break to a character device
 538 #
 539 # @id: the chardev's ID, must exist
 540 #
 541 # Returns: Nothing on success
 542 #
 543 # Since: 2.10
 544 #
 545 # Example:
 546 #
 547 # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
 548 # <- { "return": {} }
 549 #
 550 ##
 551 { 'command': 'chardev-send-break',
 552   'data': { 'id': 'str' } }
 553
 554 ##
 555 # @VSERPORT_CHANGE:
 556 #
 557 # Emitted when the guest opens or closes a virtio-serial port.
 558 #
 559 # @id: device identifier of the virtio-serial port
 560 #
 561 # @open: true if the guest has opened the virtio-serial port
 562 #
 563 # Since: 2.1
 564 #
 565 # Example:
 566 #
 567 # <- { "event": "VSERPORT_CHANGE",
 568 #      "data": { "id": "channel0", "open": true },
 569 #      "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
 570 #
 571 ##
 572 { 'event': 'VSERPORT_CHANGE',
 573   'data': { 'id': 'str',
 574             'open': 'bool' } }