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 21# backend (e.g. with the chardev=... option) is in open or closed 22# state (since 2.1) 23# 24# Notes: @filename is encoded using the QEMU command line character 25# device encoding. See the QEMU man page for details. 26# 27# Since: 0.14 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 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=on", 51# "frontend-open": false 52# }, 53# { 54# "label": "charmonitor", 55# "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on", 56# "frontend-open": true 57# }, 58# { 59# "label": "charserial0", 60# "filename": "pty:/dev/pts/2", 61# "frontend-open": true 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{ '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# 136# - base64: data must be base64 encoded text. Its binary decoding 137# gets written. 138# - utf8: data's UTF-8 encoding is written 139# - data itself is always Unicode regardless of format, like any 140# other string. 141# 142# Returns: Nothing on success 143# 144# Since: 1.4 145# 146# Example: 147# 148# -> { "execute": "ringbuf-write", 149# "arguments": { "device": "foo", 150# "data": "abcdefgh", 151# "format": "utf8" } } 152# <- { "return": {} } 153## 154{ 'command': 'ringbuf-write', 155 'data': { 'device': 'str', 156 'data': 'str', 157 '*format': 'DataFormat'} } 158 159## 160# @ringbuf-read: 161# 162# Read from a ring buffer character device. 163# 164# @device: the ring buffer character device name 165# 166# @size: how many bytes to read at most 167# 168# @format: data encoding (default 'utf8'). 169# 170# - base64: the data read is returned in base64 encoding. 171# - utf8: the data read is interpreted as UTF-8. 172# Bug: can screw up when the buffer contains invalid UTF-8 173# sequences, NUL characters, after the ring buffer lost data, 174# and when reading stops because the size limit is reached. 175# - The return value is always Unicode regardless of format, like 176# any other string. 177# 178# Returns: data read from the device 179# 180# Since: 1.4 181# 182# Example: 183# 184# -> { "execute": "ringbuf-read", 185# "arguments": { "device": "foo", 186# "size": 1000, 187# "format": "utf8" } } 188# <- { "return": "abcdefgh" } 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# 201# @logappend: true to append instead of truncate (default to false to 202# truncate) 203# 204# Since: 2.6 205## 206{ 'struct': 'ChardevCommon', 207 'data': { '*logfile': 'str', 208 '*logappend': 'bool' } } 209 210## 211# @ChardevFile: 212# 213# Configuration info for file chardevs. 214# 215# @in: The name of the input file 216# 217# @out: The name of the output file 218# 219# @append: Open the file in append mode (default false to truncate) 220# (Since 2.6) 221# 222# Since: 1.4 223## 224{ 'struct': 'ChardevFile', 225 'data': { '*in': 'str', 226 'out': 'str', 227 '*append': 'bool' }, 228 'base': 'ChardevCommon' } 229 230## 231# @ChardevHostdev: 232# 233# Configuration info for device and pipe chardevs. 234# 235# @device: The name of the special file for the device, i.e. 236# /dev/ttyS0 on Unix or COM1: on Windows 237# 238# Since: 1.4 239## 240{ 'struct': 'ChardevHostdev', 241 'data': { 'device': 'str' }, 242 'base': 'ChardevCommon' } 243 244## 245# @ChardevSocket: 246# 247# Configuration info for (stream) socket chardevs. 248# 249# @addr: socket address to listen on (server=true) or connect to 250# (server=false) 251# 252# @tls-creds: the ID of the TLS credentials object (since 2.6) 253# 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 and 257# recreated on the fly while the chardev server is active. If 258# missing, it will default to denying access (since 4.0) 259# 260# @server: create server socket (default: true) 261# 262# @wait: wait for incoming connection on server sockets (default: 263# false). Silently ignored with server: false. This use is 264# deprecated. 265# 266# @nodelay: set TCP_NODELAY socket option (default: false) 267# 268# @telnet: enable telnet protocol on server sockets (default: false) 269# 270# @tn3270: enable tn3270 protocol on server sockets (default: false) 271# (Since: 2.10) 272# 273# @websocket: enable websocket protocol on server sockets 274# (default: false) (Since: 3.1) 275# 276# @reconnect: For a client socket, if a socket is disconnected, then 277# attempt a reconnect after the given number of seconds. Setting 278# this to zero disables this function. (default: 0) (Since: 2.2) 279# 280# Since: 1.4 281## 282{ 'struct': 'ChardevSocket', 283 'data': { 'addr': 'SocketAddressLegacy', 284 '*tls-creds': 'str', 285 '*tls-authz' : 'str', 286 '*server': 'bool', 287 '*wait': 'bool', 288 '*nodelay': 'bool', 289 '*telnet': 'bool', 290 '*tn3270': 'bool', 291 '*websocket': 'bool', 292 '*reconnect': 'int' }, 293 'base': 'ChardevCommon' } 294 295## 296# @ChardevUdp: 297# 298# Configuration info for datagram socket chardevs. 299# 300# @remote: remote address 301# 302# @local: local address 303# 304# Since: 1.5 305## 306{ 'struct': 'ChardevUdp', 307 'data': { 'remote': 'SocketAddressLegacy', 308 '*local': 'SocketAddressLegacy' }, 309 'base': 'ChardevCommon' } 310 311## 312# @ChardevMux: 313# 314# Configuration info for mux chardevs. 315# 316# @chardev: name of the base chardev. 317# 318# Since: 1.5 319## 320{ 'struct': 'ChardevMux', 321 'data': { 'chardev': 'str' }, 322 'base': 'ChardevCommon' } 323 324## 325# @ChardevStdio: 326# 327# Configuration info for stdio chardevs. 328# 329# @signal: Allow signals (such as SIGINT triggered by ^C) be delivered 330# to qemu. Default: true. 331# 332# Since: 1.5 333## 334{ 'struct': 'ChardevStdio', 335 'data': { '*signal': 'bool' }, 336 'base': 'ChardevCommon' } 337 338## 339# @ChardevSpiceChannel: 340# 341# Configuration info for spice vm channel chardevs. 342# 343# @type: kind of channel (for example vdagent). 344# 345# Since: 1.5 346## 347{ 'struct': 'ChardevSpiceChannel', 348 'data': { 'type': 'str' }, 349 'base': 'ChardevCommon', 350 'if': 'CONFIG_SPICE' } 351 352## 353# @ChardevSpicePort: 354# 355# Configuration info for spice port chardevs. 356# 357# @fqdn: name of the channel (see docs/spice-port-fqdn.txt) 358# 359# Since: 1.5 360## 361{ 'struct': 'ChardevSpicePort', 362 'data': { 'fqdn': 'str' }, 363 'base': 'ChardevCommon', 364 'if': 'CONFIG_SPICE' } 365 366## 367# @ChardevDBus: 368# 369# Configuration info for DBus chardevs. 370# 371# @name: name of the channel (following docs/spice-port-fqdn.txt) 372# 373# Since: 7.0 374## 375{ 'struct': 'ChardevDBus', 376 'data': { 'name': 'str' }, 377 'base': 'ChardevCommon', 378 'if': 'CONFIG_DBUS_DISPLAY' } 379 380## 381# @ChardevVC: 382# 383# Configuration info for virtual console chardevs. 384# 385# @width: console width, in pixels 386# 387# @height: console height, in pixels 388# 389# @cols: console width, in chars 390# 391# @rows: console height, in chars 392# 393# Note: the options are only effective when the VNC or SDL graphical 394# display backend is active. They are ignored with the GTK, 395# Spice, VNC and D-Bus display backends. 396# 397# Since: 1.5 398## 399{ 'struct': 'ChardevVC', 400 'data': { '*width': 'int', 401 '*height': 'int', 402 '*cols': 'int', 403 '*rows': 'int' }, 404 'base': 'ChardevCommon' } 405 406## 407# @ChardevRingbuf: 408# 409# Configuration info for ring buffer chardevs. 410# 411# @size: ring buffer size, must be power of two, default is 65536 412# 413# Since: 1.5 414## 415{ 'struct': 'ChardevRingbuf', 416 'data': { '*size': 'int' }, 417 'base': 'ChardevCommon' } 418 419## 420# @ChardevQemuVDAgent: 421# 422# Configuration info for qemu vdagent implementation. 423# 424# @mouse: enable/disable mouse, default is enabled. 425# 426# @clipboard: enable/disable clipboard, default is disabled. 427# 428# Since: 6.1 429## 430{ 'struct': 'ChardevQemuVDAgent', 431 'data': { '*mouse': 'bool', 432 '*clipboard': 'bool' }, 433 'base': 'ChardevCommon', 434 'if': 'CONFIG_SPICE_PROTOCOL' } 435 436## 437# @ChardevBackendKind: 438# 439# @pipe: Since 1.5 440# 441# @udp: Since 1.5 442# 443# @mux: Since 1.5 444# 445# @msmouse: Since 1.5 446# 447# @wctablet: Since 2.9 448# 449# @braille: Since 1.5 450# 451# @testdev: Since 2.2 452# 453# @stdio: Since 1.5 454# 455# @console: Since 1.5 456# 457# @spicevmc: Since 1.5 458# 459# @spiceport: Since 1.5 460# 461# @qemu-vdagent: Since 6.1 462# 463# @dbus: Since 7.0 464# 465# @vc: v1.5 466# 467# @ringbuf: Since 1.6 468# 469# @memory: Since 1.5 470# 471# Since: 1.4 472## 473{ 'enum': 'ChardevBackendKind', 474 'data': [ 'file', 475 'serial', 476 'parallel', 477 'pipe', 478 'socket', 479 'udp', 480 'pty', 481 'null', 482 'mux', 483 'msmouse', 484 'wctablet', 485 'braille', 486 'testdev', 487 'stdio', 488 'console', 489 { 'name': 'spicevmc', 'if': 'CONFIG_SPICE' }, 490 { 'name': 'spiceport', 'if': 'CONFIG_SPICE' }, 491 { 'name': 'qemu-vdagent', 'if': 'CONFIG_SPICE_PROTOCOL' }, 492 { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' }, 493 'vc', 494 'ringbuf', 495 # next one is just for compatibility 496 'memory' ] } 497 498## 499# @ChardevFileWrapper: 500# 501# @data: Configuration info for file chardevs 502# 503# Since: 1.4 504## 505{ 'struct': 'ChardevFileWrapper', 506 'data': { 'data': 'ChardevFile' } } 507 508## 509# @ChardevHostdevWrapper: 510# 511# @data: Configuration info for device and pipe chardevs 512# 513# Since: 1.4 514## 515{ 'struct': 'ChardevHostdevWrapper', 516 'data': { 'data': 'ChardevHostdev' } } 517 518## 519# @ChardevSocketWrapper: 520# 521# @data: Configuration info for (stream) socket chardevs 522# 523# Since: 1.4 524## 525{ 'struct': 'ChardevSocketWrapper', 526 'data': { 'data': 'ChardevSocket' } } 527 528## 529# @ChardevUdpWrapper: 530# 531# @data: Configuration info for datagram socket chardevs 532# 533# Since: 1.5 534## 535{ 'struct': 'ChardevUdpWrapper', 536 'data': { 'data': 'ChardevUdp' } } 537 538## 539# @ChardevCommonWrapper: 540# 541# @data: Configuration shared across all chardev backends 542# 543# Since: 2.6 544## 545{ 'struct': 'ChardevCommonWrapper', 546 'data': { 'data': 'ChardevCommon' } } 547 548## 549# @ChardevMuxWrapper: 550# 551# @data: Configuration info for mux chardevs 552# 553# Since: 1.5 554## 555{ 'struct': 'ChardevMuxWrapper', 556 'data': { 'data': 'ChardevMux' } } 557 558## 559# @ChardevStdioWrapper: 560# 561# @data: Configuration info for stdio chardevs 562# 563# Since: 1.5 564## 565{ 'struct': 'ChardevStdioWrapper', 566 'data': { 'data': 'ChardevStdio' } } 567 568## 569# @ChardevSpiceChannelWrapper: 570# 571# @data: Configuration info for spice vm channel chardevs 572# 573# Since: 1.5 574## 575{ 'struct': 'ChardevSpiceChannelWrapper', 576 'data': { 'data': 'ChardevSpiceChannel' }, 577 'if': 'CONFIG_SPICE' } 578 579## 580# @ChardevSpicePortWrapper: 581# 582# @data: Configuration info for spice port chardevs 583# 584# Since: 1.5 585## 586{ 'struct': 'ChardevSpicePortWrapper', 587 'data': { 'data': 'ChardevSpicePort' }, 588 'if': 'CONFIG_SPICE' } 589 590## 591# @ChardevQemuVDAgentWrapper: 592# 593# @data: Configuration info for qemu vdagent implementation 594# 595# Since: 6.1 596## 597{ 'struct': 'ChardevQemuVDAgentWrapper', 598 'data': { 'data': 'ChardevQemuVDAgent' }, 599 'if': 'CONFIG_SPICE_PROTOCOL' } 600 601## 602# @ChardevDBusWrapper: 603# 604# @data: Configuration info for DBus chardevs 605# 606# Since: 7.0 607## 608{ 'struct': 'ChardevDBusWrapper', 609 'data': { 'data': 'ChardevDBus' }, 610 'if': 'CONFIG_DBUS_DISPLAY' } 611 612## 613# @ChardevVCWrapper: 614# 615# @data: Configuration info for virtual console chardevs 616# 617# Since: 1.5 618## 619{ 'struct': 'ChardevVCWrapper', 620 'data': { 'data': 'ChardevVC' } } 621 622## 623# @ChardevRingbufWrapper: 624# 625# @data: Configuration info for ring buffer chardevs 626# 627# Since: 1.5 628## 629{ 'struct': 'ChardevRingbufWrapper', 630 'data': { 'data': 'ChardevRingbuf' } } 631 632## 633# @ChardevBackend: 634# 635# Configuration info for the new chardev backend. 636# 637# Since: 1.4 638## 639{ 'union': 'ChardevBackend', 640 'base': { 'type': 'ChardevBackendKind' }, 641 'discriminator': 'type', 642 'data': { 'file': 'ChardevFileWrapper', 643 'serial': 'ChardevHostdevWrapper', 644 'parallel': 'ChardevHostdevWrapper', 645 'pipe': 'ChardevHostdevWrapper', 646 'socket': 'ChardevSocketWrapper', 647 'udp': 'ChardevUdpWrapper', 648 'pty': 'ChardevCommonWrapper', 649 'null': 'ChardevCommonWrapper', 650 'mux': 'ChardevMuxWrapper', 651 'msmouse': 'ChardevCommonWrapper', 652 'wctablet': 'ChardevCommonWrapper', 653 'braille': 'ChardevCommonWrapper', 654 'testdev': 'ChardevCommonWrapper', 655 'stdio': 'ChardevStdioWrapper', 656 'console': 'ChardevCommonWrapper', 657 'spicevmc': { 'type': 'ChardevSpiceChannelWrapper', 658 'if': 'CONFIG_SPICE' }, 659 'spiceport': { 'type': 'ChardevSpicePortWrapper', 660 'if': 'CONFIG_SPICE' }, 661 'qemu-vdagent': { 'type': 'ChardevQemuVDAgentWrapper', 662 'if': 'CONFIG_SPICE_PROTOCOL' }, 663 'dbus': { 'type': 'ChardevDBusWrapper', 664 'if': 'CONFIG_DBUS_DISPLAY' }, 665 'vc': 'ChardevVCWrapper', 666 'ringbuf': 'ChardevRingbufWrapper', 667 # next one is just for compatibility 668 'memory': 'ChardevRingbufWrapper' } } 669 670## 671# @ChardevReturn: 672# 673# Return info about the chardev backend just created. 674# 675# @pty: name of the slave pseudoterminal device, present if and only 676# if a chardev of type 'pty' was created 677# 678# Since: 1.4 679## 680{ 'struct' : 'ChardevReturn', 681 'data': { '*pty': 'str' } } 682 683## 684# @chardev-add: 685# 686# Add a character device backend 687# 688# @id: the chardev's ID, must be unique 689# 690# @backend: backend type and parameters 691# 692# Returns: ChardevReturn. 693# 694# Since: 1.4 695# 696# Examples: 697# 698# -> { "execute" : "chardev-add", 699# "arguments" : { "id" : "foo", 700# "backend" : { "type" : "null", "data" : {} } } } 701# <- { "return": {} } 702# 703# -> { "execute" : "chardev-add", 704# "arguments" : { "id" : "bar", 705# "backend" : { "type" : "file", 706# "data" : { "out" : "/tmp/bar.log" } } } } 707# <- { "return": {} } 708# 709# -> { "execute" : "chardev-add", 710# "arguments" : { "id" : "baz", 711# "backend" : { "type" : "pty", "data" : {} } } } 712# <- { "return": { "pty" : "/dev/pty/42" } } 713## 714{ 'command': 'chardev-add', 715 'data': { 'id': 'str', 716 'backend': 'ChardevBackend' }, 717 'returns': 'ChardevReturn' } 718 719## 720# @chardev-change: 721# 722# Change a character device backend 723# 724# @id: the chardev's ID, must exist 725# 726# @backend: new backend type and parameters 727# 728# Returns: ChardevReturn. 729# 730# Since: 2.10 731# 732# Examples: 733# 734# -> { "execute" : "chardev-change", 735# "arguments" : { "id" : "baz", 736# "backend" : { "type" : "pty", "data" : {} } } } 737# <- { "return": { "pty" : "/dev/pty/42" } } 738# 739# -> {"execute" : "chardev-change", 740# "arguments" : { 741# "id" : "charchannel2", 742# "backend" : { 743# "type" : "socket", 744# "data" : { 745# "addr" : { 746# "type" : "unix" , 747# "data" : { 748# "path" : "/tmp/charchannel2.socket" 749# } 750# }, 751# "server" : true, 752# "wait" : false }}}} 753# <- {"return": {}} 754## 755{ 'command': 'chardev-change', 756 'data': { 'id': 'str', 757 'backend': 'ChardevBackend' }, 758 'returns': 'ChardevReturn' } 759 760## 761# @chardev-remove: 762# 763# Remove a character device backend 764# 765# @id: the chardev's ID, must exist and not be in use 766# 767# Returns: Nothing on success 768# 769# Since: 1.4 770# 771# Example: 772# 773# -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } 774# <- { "return": {} } 775## 776{ 'command': 'chardev-remove', 777 'data': { 'id': 'str' } } 778 779## 780# @chardev-send-break: 781# 782# Send a break to a character device 783# 784# @id: the chardev's ID, must exist 785# 786# Returns: Nothing on success 787# 788# Since: 2.10 789# 790# Example: 791# 792# -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } } 793# <- { "return": {} } 794## 795{ 'command': 'chardev-send-break', 796 'data': { 'id': 'str' } } 797 798## 799# @VSERPORT_CHANGE: 800# 801# Emitted when the guest opens or closes a virtio-serial port. 802# 803# @id: device identifier of the virtio-serial port 804# 805# @open: true if the guest has opened the virtio-serial port 806# 807# Note: This event is rate-limited. 808# 809# Since: 2.1 810# 811# Example: 812# 813# <- { "event": "VSERPORT_CHANGE", 814# "data": { "id": "channel0", "open": true }, 815# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } 816## 817{ 'event': 'VSERPORT_CHANGE', 818 'data': { 'id': 'str', 819 'open': 'bool' } } 820