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# @reconnect: For a client socket, if a socket is disconnected, 255# then attempt a reconnect after the given number of seconds. 256# Setting this to zero disables this function. (default: 0) 257# (Since: 2.2) 258# 259# Since: 1.4 260## 261{ 'struct': 'ChardevSocket', 'data': { 'addr' : 'SocketAddressLegacy', 262 '*tls-creds' : 'str', 263 '*server' : 'bool', 264 '*wait' : 'bool', 265 '*nodelay' : 'bool', 266 '*telnet' : 'bool', 267 '*tn3270' : 'bool', 268 '*reconnect' : 'int' }, 269 'base': 'ChardevCommon' } 270 271## 272# @ChardevUdp: 273# 274# Configuration info for datagram socket chardevs. 275# 276# @remote: remote address 277# @local: local address 278# 279# Since: 1.5 280## 281{ 'struct': 'ChardevUdp', 'data': { 'remote' : 'SocketAddressLegacy', 282 '*local' : 'SocketAddressLegacy' }, 283 'base': 'ChardevCommon' } 284 285## 286# @ChardevMux: 287# 288# Configuration info for mux chardevs. 289# 290# @chardev: name of the base chardev. 291# 292# Since: 1.5 293## 294{ 'struct': 'ChardevMux', 'data': { 'chardev' : 'str' }, 295 'base': 'ChardevCommon' } 296 297## 298# @ChardevStdio: 299# 300# Configuration info for stdio chardevs. 301# 302# @signal: Allow signals (such as SIGINT triggered by ^C) 303# be delivered to qemu. Default: true in -nographic mode, 304# false otherwise. 305# 306# Since: 1.5 307## 308{ 'struct': 'ChardevStdio', 'data': { '*signal' : 'bool' }, 309 'base': 'ChardevCommon' } 310 311 312## 313# @ChardevSpiceChannel: 314# 315# Configuration info for spice vm channel chardevs. 316# 317# @type: kind of channel (for example vdagent). 318# 319# Since: 1.5 320## 321{ 'struct': 'ChardevSpiceChannel', 'data': { 'type' : 'str' }, 322 'base': 'ChardevCommon' } 323# TODO: 'if': 'defined(CONFIG_SPICE)' 324 325## 326# @ChardevSpicePort: 327# 328# Configuration info for spice port chardevs. 329# 330# @fqdn: name of the channel (see docs/spice-port-fqdn.txt) 331# 332# Since: 1.5 333## 334{ 'struct': 'ChardevSpicePort', 'data': { 'fqdn' : 'str' }, 335 'base': 'ChardevCommon' } 336# TODO: 'if': 'defined(CONFIG_SPICE)' 337 338## 339# @ChardevVC: 340# 341# Configuration info for virtual console chardevs. 342# 343# @width: console width, in pixels 344# @height: console height, in pixels 345# @cols: console width, in chars 346# @rows: console height, in chars 347# 348# Since: 1.5 349## 350{ 'struct': 'ChardevVC', 'data': { '*width' : 'int', 351 '*height' : 'int', 352 '*cols' : 'int', 353 '*rows' : 'int' }, 354 'base': 'ChardevCommon' } 355 356## 357# @ChardevRingbuf: 358# 359# Configuration info for ring buffer chardevs. 360# 361# @size: ring buffer size, must be power of two, default is 65536 362# 363# Since: 1.5 364## 365{ 'struct': 'ChardevRingbuf', 'data': { '*size' : 'int' }, 366 'base': 'ChardevCommon' } 367 368## 369# @ChardevBackend: 370# 371# Configuration info for the new chardev backend. 372# 373# Since: 1.4 (testdev since 2.2, wctablet since 2.9) 374## 375{ 'union': 'ChardevBackend', 'data': { 'file' : 'ChardevFile', 376 'serial' : 'ChardevHostdev', 377 'parallel': 'ChardevHostdev', 378 'pipe' : 'ChardevHostdev', 379 'socket' : 'ChardevSocket', 380 'udp' : 'ChardevUdp', 381 'pty' : 'ChardevCommon', 382 'null' : 'ChardevCommon', 383 'mux' : 'ChardevMux', 384 'msmouse': 'ChardevCommon', 385 'wctablet' : 'ChardevCommon', 386 'braille': 'ChardevCommon', 387 'testdev': 'ChardevCommon', 388 'stdio' : 'ChardevStdio', 389 'console': 'ChardevCommon', 390 'spicevmc': 'ChardevSpiceChannel', 391# TODO: { 'type': 'ChardevSpiceChannel', 'if': 'defined(CONFIG_SPICE)' }, 392 'spiceport': 'ChardevSpicePort', 393# TODO: { 'type': 'ChardevSpicePort', 'if': 'defined(CONFIG_SPICE)' }, 394 'vc' : 'ChardevVC', 395 'ringbuf': 'ChardevRingbuf', 396 # next one is just for compatibility 397 'memory' : 'ChardevRingbuf' } } 398 399## 400# @ChardevReturn: 401# 402# Return info about the chardev backend just created. 403# 404# @pty: name of the slave pseudoterminal device, present if 405# and only if a chardev of type 'pty' was created 406# 407# Since: 1.4 408## 409{ 'struct' : 'ChardevReturn', 'data': { '*pty' : 'str' } } 410 411## 412# @chardev-add: 413# 414# Add a character device backend 415# 416# @id: the chardev's ID, must be unique 417# @backend: backend type and parameters 418# 419# Returns: ChardevReturn. 420# 421# Since: 1.4 422# 423# Example: 424# 425# -> { "execute" : "chardev-add", 426# "arguments" : { "id" : "foo", 427# "backend" : { "type" : "null", "data" : {} } } } 428# <- { "return": {} } 429# 430# -> { "execute" : "chardev-add", 431# "arguments" : { "id" : "bar", 432# "backend" : { "type" : "file", 433# "data" : { "out" : "/tmp/bar.log" } } } } 434# <- { "return": {} } 435# 436# -> { "execute" : "chardev-add", 437# "arguments" : { "id" : "baz", 438# "backend" : { "type" : "pty", "data" : {} } } } 439# <- { "return": { "pty" : "/dev/pty/42" } } 440# 441## 442{ 'command': 'chardev-add', 'data': {'id' : 'str', 443 'backend' : 'ChardevBackend' }, 444 'returns': 'ChardevReturn' } 445 446## 447# @chardev-change: 448# 449# Change a character device backend 450# 451# @id: the chardev's ID, must exist 452# @backend: new backend type and parameters 453# 454# Returns: ChardevReturn. 455# 456# Since: 2.10 457# 458# Example: 459# 460# -> { "execute" : "chardev-change", 461# "arguments" : { "id" : "baz", 462# "backend" : { "type" : "pty", "data" : {} } } } 463# <- { "return": { "pty" : "/dev/pty/42" } } 464# 465# -> {"execute" : "chardev-change", 466# "arguments" : { 467# "id" : "charchannel2", 468# "backend" : { 469# "type" : "socket", 470# "data" : { 471# "addr" : { 472# "type" : "unix" , 473# "data" : { 474# "path" : "/tmp/charchannel2.socket" 475# } 476# }, 477# "server" : true, 478# "wait" : false }}}} 479# <- {"return": {}} 480# 481## 482{ 'command': 'chardev-change', 'data': {'id' : 'str', 483 'backend' : 'ChardevBackend' }, 484 'returns': 'ChardevReturn' } 485 486## 487# @chardev-remove: 488# 489# Remove a character device backend 490# 491# @id: the chardev's ID, must exist and not be in use 492# 493# Returns: Nothing on success 494# 495# Since: 1.4 496# 497# Example: 498# 499# -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } 500# <- { "return": {} } 501# 502## 503{ 'command': 'chardev-remove', 'data': {'id': 'str'} } 504 505## 506# @chardev-send-break: 507# 508# Send a break to a character device 509# 510# @id: the chardev's ID, must exist 511# 512# Returns: Nothing on success 513# 514# Since: 2.10 515# 516# Example: 517# 518# -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } } 519# <- { "return": {} } 520# 521## 522{ 'command': 'chardev-send-break', 'data': {'id': 'str'} } 523 524## 525# @VSERPORT_CHANGE: 526# 527# Emitted when the guest opens or closes a virtio-serial port. 528# 529# @id: device identifier of the virtio-serial port 530# 531# @open: true if the guest has opened the virtio-serial port 532# 533# Since: 2.1 534# 535# Example: 536# 537# <- { "event": "VSERPORT_CHANGE", 538# "data": { "id": "channel0", "open": true }, 539# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } 540# 541## 542{ 'event': 'VSERPORT_CHANGE', 543 'data': { 'id': 'str', 'open': 'bool' } } 544