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