xref: /openbmc/qemu/qapi/ui.json (revision 5111edaf)
1# -*- Mode: Python -*-
2# vim: filetype=python
3#
4
5##
6# = Remote desktop
7##
8
9{ 'include': 'common.json' }
10{ 'include': 'sockets.json' }
11
12##
13# @set_password:
14#
15# Sets the password of a remote display session.
16#
17# @protocol: - 'vnc' to modify the VNC server password
18#            - 'spice' to modify the Spice server password
19#
20# @password: the new password
21#
22# @connected: how to handle existing clients when changing the
23#             password.  If nothing is specified, defaults to 'keep'
24#             'fail' to fail the command if clients are connected
25#             'disconnect' to disconnect existing clients
26#             'keep' to maintain existing clients
27#
28# Returns: - Nothing on success
29#          - If Spice is not enabled, DeviceNotFound
30#
31# Since: 0.14
32#
33# Example:
34#
35# -> { "execute": "set_password", "arguments": { "protocol": "vnc",
36#                                                "password": "secret" } }
37# <- { "return": {} }
38#
39##
40{ 'command': 'set_password',
41  'data': {'protocol': 'str', 'password': 'str', '*connected': 'str'} }
42
43##
44# @expire_password:
45#
46# Expire the password of a remote display server.
47#
48# @protocol: the name of the remote display protocol 'vnc' or 'spice'
49#
50# @time: when to expire the password.
51#
52#        - 'now' to expire the password immediately
53#        - 'never' to cancel password expiration
54#        - '+INT' where INT is the number of seconds from now (integer)
55#        - 'INT' where INT is the absolute time in seconds
56#
57# Returns: - Nothing on success
58#          - If @protocol is 'spice' and Spice is not active, DeviceNotFound
59#
60# Since: 0.14
61#
62# Notes: Time is relative to the server and currently there is no way to
63#        coordinate server time with client time.  It is not recommended to
64#        use the absolute time version of the @time parameter unless you're
65#        sure you are on the same machine as the QEMU instance.
66#
67# Example:
68#
69# -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
70#                                                   "time": "+60" } }
71# <- { "return": {} }
72#
73##
74{ 'command': 'expire_password', 'data': {'protocol': 'str', 'time': 'str'} }
75
76##
77# @screendump:
78#
79# Write a PPM of the VGA screen to a file.
80#
81# @filename: the path of a new PPM file to store the image
82#
83# @device: ID of the display device that should be dumped. If this parameter
84#          is missing, the primary display will be used. (Since 2.12)
85#
86# @head: head to use in case the device supports multiple heads. If this
87#        parameter is missing, head #0 will be used. Also note that the head
88#        can only be specified in conjunction with the device ID. (Since 2.12)
89#
90# Returns: Nothing on success
91#
92# Since: 0.14
93#
94# Example:
95#
96# -> { "execute": "screendump",
97#      "arguments": { "filename": "/tmp/image" } }
98# <- { "return": {} }
99#
100##
101{ 'command': 'screendump',
102  'data': {'filename': 'str', '*device': 'str', '*head': 'int'},
103  'coroutine': true }
104
105##
106# == Spice
107##
108
109##
110# @SpiceBasicInfo:
111#
112# The basic information for SPICE network connection
113#
114# @host: IP address
115#
116# @port: port number
117#
118# @family: address family
119#
120# Since: 2.1
121##
122{ 'struct': 'SpiceBasicInfo',
123  'data': { 'host': 'str',
124            'port': 'str',
125            'family': 'NetworkAddressFamily' },
126  'if': 'defined(CONFIG_SPICE)' }
127
128##
129# @SpiceServerInfo:
130#
131# Information about a SPICE server
132#
133# @auth: authentication method
134#
135# Since: 2.1
136##
137{ 'struct': 'SpiceServerInfo',
138  'base': 'SpiceBasicInfo',
139  'data': { '*auth': 'str' },
140  'if': 'defined(CONFIG_SPICE)' }
141
142##
143# @SpiceChannel:
144#
145# Information about a SPICE client channel.
146#
147# @connection-id: SPICE connection id number.  All channels with the same id
148#                 belong to the same SPICE session.
149#
150# @channel-type: SPICE channel type number.  "1" is the main control
151#                channel, filter for this one if you want to track spice
152#                sessions only
153#
154# @channel-id: SPICE channel ID number.  Usually "0", might be different when
155#              multiple channels of the same type exist, such as multiple
156#              display channels in a multihead setup
157#
158# @tls: true if the channel is encrypted, false otherwise.
159#
160# Since: 0.14
161##
162{ 'struct': 'SpiceChannel',
163  'base': 'SpiceBasicInfo',
164  'data': {'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int',
165           'tls': 'bool'},
166  'if': 'defined(CONFIG_SPICE)' }
167
168##
169# @SpiceQueryMouseMode:
170#
171# An enumeration of Spice mouse states.
172#
173# @client: Mouse cursor position is determined by the client.
174#
175# @server: Mouse cursor position is determined by the server.
176#
177# @unknown: No information is available about mouse mode used by
178#           the spice server.
179#
180# Note: spice/enums.h has a SpiceMouseMode already, hence the name.
181#
182# Since: 1.1
183##
184{ 'enum': 'SpiceQueryMouseMode',
185  'data': [ 'client', 'server', 'unknown' ],
186  'if': 'defined(CONFIG_SPICE)' }
187
188##
189# @SpiceInfo:
190#
191# Information about the SPICE session.
192#
193# @enabled: true if the SPICE server is enabled, false otherwise
194#
195# @migrated: true if the last guest migration completed and spice
196#            migration had completed as well. false otherwise. (since 1.4)
197#
198# @host: The hostname the SPICE server is bound to.  This depends on
199#        the name resolution on the host and may be an IP address.
200#
201# @port: The SPICE server's port number.
202#
203# @compiled-version: SPICE server version.
204#
205# @tls-port: The SPICE server's TLS port number.
206#
207# @auth: the current authentication type used by the server
208#
209#        - 'none'  if no authentication is being used
210#        - 'spice' uses SASL or direct TLS authentication, depending on command
211#          line options
212#
213# @mouse-mode: The mode in which the mouse cursor is displayed currently. Can
214#              be determined by the client or the server, or unknown if spice
215#              server doesn't provide this information. (since: 1.1)
216#
217# @channels: a list of @SpiceChannel for each active spice channel
218#
219# Since: 0.14
220##
221{ 'struct': 'SpiceInfo',
222  'data': {'enabled': 'bool', 'migrated': 'bool', '*host': 'str', '*port': 'int',
223           '*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str',
224           'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']},
225  'if': 'defined(CONFIG_SPICE)' }
226
227##
228# @query-spice:
229#
230# Returns information about the current SPICE server
231#
232# Returns: @SpiceInfo
233#
234# Since: 0.14
235#
236# Example:
237#
238# -> { "execute": "query-spice" }
239# <- { "return": {
240#          "enabled": true,
241#          "auth": "spice",
242#          "port": 5920,
243#          "tls-port": 5921,
244#          "host": "0.0.0.0",
245#          "channels": [
246#             {
247#                "port": "54924",
248#                "family": "ipv4",
249#                "channel-type": 1,
250#                "connection-id": 1804289383,
251#                "host": "127.0.0.1",
252#                "channel-id": 0,
253#                "tls": true
254#             },
255#             {
256#                "port": "36710",
257#                "family": "ipv4",
258#                "channel-type": 4,
259#                "connection-id": 1804289383,
260#                "host": "127.0.0.1",
261#                "channel-id": 0,
262#                "tls": false
263#             },
264#             [ ... more channels follow ... ]
265#          ]
266#       }
267#    }
268#
269##
270{ 'command': 'query-spice', 'returns': 'SpiceInfo',
271  'if': 'defined(CONFIG_SPICE)' }
272
273##
274# @SPICE_CONNECTED:
275#
276# Emitted when a SPICE client establishes a connection
277#
278# @server: server information
279#
280# @client: client information
281#
282# Since: 0.14
283#
284# Example:
285#
286# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
287#      "event": "SPICE_CONNECTED",
288#      "data": {
289#        "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
290#        "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
291#    }}
292#
293##
294{ 'event': 'SPICE_CONNECTED',
295  'data': { 'server': 'SpiceBasicInfo',
296            'client': 'SpiceBasicInfo' },
297  'if': 'defined(CONFIG_SPICE)' }
298
299##
300# @SPICE_INITIALIZED:
301#
302# Emitted after initial handshake and authentication takes place (if any)
303# and the SPICE channel is up and running
304#
305# @server: server information
306#
307# @client: client information
308#
309# Since: 0.14
310#
311# Example:
312#
313# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
314#      "event": "SPICE_INITIALIZED",
315#      "data": {"server": {"auth": "spice", "port": "5921",
316#                          "family": "ipv4", "host": "127.0.0.1"},
317#               "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
318#                          "connection-id": 1804289383, "host": "127.0.0.1",
319#                          "channel-id": 0, "tls": true}
320#    }}
321#
322##
323{ 'event': 'SPICE_INITIALIZED',
324  'data': { 'server': 'SpiceServerInfo',
325            'client': 'SpiceChannel' },
326  'if': 'defined(CONFIG_SPICE)' }
327
328##
329# @SPICE_DISCONNECTED:
330#
331# Emitted when the SPICE connection is closed
332#
333# @server: server information
334#
335# @client: client information
336#
337# Since: 0.14
338#
339# Example:
340#
341# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
342#      "event": "SPICE_DISCONNECTED",
343#      "data": {
344#        "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
345#        "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
346#    }}
347#
348##
349{ 'event': 'SPICE_DISCONNECTED',
350  'data': { 'server': 'SpiceBasicInfo',
351            'client': 'SpiceBasicInfo' },
352  'if': 'defined(CONFIG_SPICE)' }
353
354##
355# @SPICE_MIGRATE_COMPLETED:
356#
357# Emitted when SPICE migration has completed
358#
359# Since: 1.3
360#
361# Example:
362#
363# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
364#      "event": "SPICE_MIGRATE_COMPLETED" }
365#
366##
367{ 'event': 'SPICE_MIGRATE_COMPLETED',
368  'if': 'defined(CONFIG_SPICE)' }
369
370##
371# == VNC
372##
373
374##
375# @VncBasicInfo:
376#
377# The basic information for vnc network connection
378#
379# @host: IP address
380#
381# @service: The service name of the vnc port. This may depend on the host
382#           system's service database so symbolic names should not be relied
383#           on.
384#
385# @family: address family
386#
387# @websocket: true in case the socket is a websocket (since 2.3).
388#
389# Since: 2.1
390##
391{ 'struct': 'VncBasicInfo',
392  'data': { 'host': 'str',
393            'service': 'str',
394            'family': 'NetworkAddressFamily',
395            'websocket': 'bool' },
396  'if': 'defined(CONFIG_VNC)' }
397
398##
399# @VncServerInfo:
400#
401# The network connection information for server
402#
403# @auth: authentication method used for
404#        the plain (non-websocket) VNC server
405#
406# Since: 2.1
407##
408{ 'struct': 'VncServerInfo',
409  'base': 'VncBasicInfo',
410  'data': { '*auth': 'str' },
411  'if': 'defined(CONFIG_VNC)' }
412
413##
414# @VncClientInfo:
415#
416# Information about a connected VNC client.
417#
418# @x509_dname: If x509 authentication is in use, the Distinguished
419#              Name of the client.
420#
421# @sasl_username: If SASL authentication is in use, the SASL username
422#                 used for authentication.
423#
424# Since: 0.14
425##
426{ 'struct': 'VncClientInfo',
427  'base': 'VncBasicInfo',
428  'data': { '*x509_dname': 'str', '*sasl_username': 'str' },
429  'if': 'defined(CONFIG_VNC)' }
430
431##
432# @VncInfo:
433#
434# Information about the VNC session.
435#
436# @enabled: true if the VNC server is enabled, false otherwise
437#
438# @host: The hostname the VNC server is bound to.  This depends on
439#        the name resolution on the host and may be an IP address.
440#
441# @family: - 'ipv6' if the host is listening for IPv6 connections
442#          - 'ipv4' if the host is listening for IPv4 connections
443#          - 'unix' if the host is listening on a unix domain socket
444#          - 'unknown' otherwise
445#
446# @service: The service name of the server's port.  This may depends
447#           on the host system's service database so symbolic names should not
448#           be relied on.
449#
450# @auth: the current authentication type used by the server
451#
452#        - 'none' if no authentication is being used
453#        - 'vnc' if VNC authentication is being used
454#        - 'vencrypt+plain' if VEncrypt is used with plain text authentication
455#        - 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
456#        - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
457#        - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
458#        - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
459#        - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
460#        - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
461#        - 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
462#        - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth
463#
464# @clients: a list of @VncClientInfo of all currently connected clients
465#
466# Since: 0.14
467##
468{ 'struct': 'VncInfo',
469  'data': {'enabled': 'bool', '*host': 'str',
470           '*family': 'NetworkAddressFamily',
471           '*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']},
472  'if': 'defined(CONFIG_VNC)' }
473
474##
475# @VncPrimaryAuth:
476#
477# vnc primary authentication method.
478#
479# Since: 2.3
480##
481{ 'enum': 'VncPrimaryAuth',
482  'data': [ 'none', 'vnc', 'ra2', 'ra2ne', 'tight', 'ultra',
483            'tls', 'vencrypt', 'sasl' ],
484  'if': 'defined(CONFIG_VNC)' }
485
486##
487# @VncVencryptSubAuth:
488#
489# vnc sub authentication method with vencrypt.
490#
491# Since: 2.3
492##
493{ 'enum': 'VncVencryptSubAuth',
494  'data': [ 'plain',
495            'tls-none',  'x509-none',
496            'tls-vnc',   'x509-vnc',
497            'tls-plain', 'x509-plain',
498            'tls-sasl',  'x509-sasl' ],
499  'if': 'defined(CONFIG_VNC)' }
500
501##
502# @VncServerInfo2:
503#
504# The network connection information for server
505#
506# @auth: The current authentication type used by the servers
507#
508# @vencrypt: The vencrypt sub authentication type used by the
509#            servers, only specified in case auth == vencrypt.
510#
511# Since: 2.9
512##
513{ 'struct': 'VncServerInfo2',
514  'base': 'VncBasicInfo',
515  'data': { 'auth'      : 'VncPrimaryAuth',
516            '*vencrypt' : 'VncVencryptSubAuth' },
517  'if': 'defined(CONFIG_VNC)' }
518
519##
520# @VncInfo2:
521#
522# Information about a vnc server
523#
524# @id: vnc server name.
525#
526# @server: A list of @VncBasincInfo describing all listening sockets.
527#          The list can be empty (in case the vnc server is disabled).
528#          It also may have multiple entries: normal + websocket,
529#          possibly also ipv4 + ipv6 in the future.
530#
531# @clients: A list of @VncClientInfo of all currently connected clients.
532#           The list can be empty, for obvious reasons.
533#
534# @auth: The current authentication type used by the non-websockets servers
535#
536# @vencrypt: The vencrypt authentication type used by the servers,
537#            only specified in case auth == vencrypt.
538#
539# @display: The display device the vnc server is linked to.
540#
541# Since: 2.3
542##
543{ 'struct': 'VncInfo2',
544  'data': { 'id'        : 'str',
545            'server'    : ['VncServerInfo2'],
546            'clients'   : ['VncClientInfo'],
547            'auth'      : 'VncPrimaryAuth',
548            '*vencrypt' : 'VncVencryptSubAuth',
549            '*display'  : 'str' },
550  'if': 'defined(CONFIG_VNC)' }
551
552##
553# @query-vnc:
554#
555# Returns information about the current VNC server
556#
557# Returns: @VncInfo
558#
559# Since: 0.14
560#
561# Example:
562#
563# -> { "execute": "query-vnc" }
564# <- { "return": {
565#          "enabled":true,
566#          "host":"0.0.0.0",
567#          "service":"50402",
568#          "auth":"vnc",
569#          "family":"ipv4",
570#          "clients":[
571#             {
572#                "host":"127.0.0.1",
573#                "service":"50401",
574#                "family":"ipv4"
575#             }
576#          ]
577#       }
578#    }
579#
580##
581{ 'command': 'query-vnc', 'returns': 'VncInfo',
582  'if': 'defined(CONFIG_VNC)' }
583##
584# @query-vnc-servers:
585#
586# Returns a list of vnc servers.  The list can be empty.
587#
588# Returns: a list of @VncInfo2
589#
590# Since: 2.3
591##
592{ 'command': 'query-vnc-servers', 'returns': ['VncInfo2'],
593  'if': 'defined(CONFIG_VNC)' }
594
595##
596# @change-vnc-password:
597#
598# Change the VNC server password.
599#
600# @password: the new password to use with VNC authentication
601#
602# Since: 1.1
603#
604# Notes: An empty password in this command will set the password to the empty
605#        string.  Existing clients are unaffected by executing this command.
606##
607{ 'command': 'change-vnc-password',
608  'data': { 'password': 'str' },
609  'if': 'defined(CONFIG_VNC)' }
610
611##
612# @VNC_CONNECTED:
613#
614# Emitted when a VNC client establishes a connection
615#
616# @server: server information
617#
618# @client: client information
619#
620# Note: This event is emitted before any authentication takes place, thus
621#       the authentication ID is not provided
622#
623# Since: 0.13
624#
625# Example:
626#
627# <- { "event": "VNC_CONNECTED",
628#      "data": {
629#            "server": { "auth": "sasl", "family": "ipv4",
630#                        "service": "5901", "host": "0.0.0.0" },
631#            "client": { "family": "ipv4", "service": "58425",
632#                        "host": "127.0.0.1" } },
633#      "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
634#
635##
636{ 'event': 'VNC_CONNECTED',
637  'data': { 'server': 'VncServerInfo',
638            'client': 'VncBasicInfo' },
639  'if': 'defined(CONFIG_VNC)' }
640
641##
642# @VNC_INITIALIZED:
643#
644# Emitted after authentication takes place (if any) and the VNC session is
645# made active
646#
647# @server: server information
648#
649# @client: client information
650#
651# Since: 0.13
652#
653# Example:
654#
655# <-  { "event": "VNC_INITIALIZED",
656#       "data": {
657#            "server": { "auth": "sasl", "family": "ipv4",
658#                        "service": "5901", "host": "0.0.0.0"},
659#            "client": { "family": "ipv4", "service": "46089",
660#                        "host": "127.0.0.1", "sasl_username": "luiz" } },
661#       "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
662#
663##
664{ 'event': 'VNC_INITIALIZED',
665  'data': { 'server': 'VncServerInfo',
666            'client': 'VncClientInfo' },
667  'if': 'defined(CONFIG_VNC)' }
668
669##
670# @VNC_DISCONNECTED:
671#
672# Emitted when the connection is closed
673#
674# @server: server information
675#
676# @client: client information
677#
678# Since: 0.13
679#
680# Example:
681#
682# <- { "event": "VNC_DISCONNECTED",
683#      "data": {
684#            "server": { "auth": "sasl", "family": "ipv4",
685#                        "service": "5901", "host": "0.0.0.0" },
686#            "client": { "family": "ipv4", "service": "58425",
687#                        "host": "127.0.0.1", "sasl_username": "luiz" } },
688#      "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
689#
690##
691{ 'event': 'VNC_DISCONNECTED',
692  'data': { 'server': 'VncServerInfo',
693            'client': 'VncClientInfo' },
694  'if': 'defined(CONFIG_VNC)' }
695
696##
697# = Input
698##
699
700##
701# @MouseInfo:
702#
703# Information about a mouse device.
704#
705# @name: the name of the mouse device
706#
707# @index: the index of the mouse device
708#
709# @current: true if this device is currently receiving mouse events
710#
711# @absolute: true if this device supports absolute coordinates as input
712#
713# Since: 0.14
714##
715{ 'struct': 'MouseInfo',
716  'data': {'name': 'str', 'index': 'int', 'current': 'bool',
717           'absolute': 'bool'} }
718
719##
720# @query-mice:
721#
722# Returns information about each active mouse device
723#
724# Returns: a list of @MouseInfo for each device
725#
726# Since: 0.14
727#
728# Example:
729#
730# -> { "execute": "query-mice" }
731# <- { "return": [
732#          {
733#             "name":"QEMU Microsoft Mouse",
734#             "index":0,
735#             "current":false,
736#             "absolute":false
737#          },
738#          {
739#             "name":"QEMU PS/2 Mouse",
740#             "index":1,
741#             "current":true,
742#             "absolute":true
743#          }
744#       ]
745#    }
746#
747##
748{ 'command': 'query-mice', 'returns': ['MouseInfo'] }
749
750##
751# @QKeyCode:
752#
753# An enumeration of key name.
754#
755# This is used by the @send-key command.
756#
757# @unmapped: since 2.0
758# @pause: since 2.0
759# @ro: since 2.4
760# @kp_comma: since 2.4
761# @kp_equals: since 2.6
762# @power: since 2.6
763# @hiragana: since 2.9
764# @henkan: since 2.9
765# @yen: since 2.9
766#
767# @sleep: since 2.10
768# @wake: since 2.10
769# @audionext: since 2.10
770# @audioprev: since 2.10
771# @audiostop: since 2.10
772# @audioplay: since 2.10
773# @audiomute: since 2.10
774# @volumeup: since 2.10
775# @volumedown: since 2.10
776# @mediaselect: since 2.10
777# @mail: since 2.10
778# @calculator: since 2.10
779# @computer: since 2.10
780# @ac_home: since 2.10
781# @ac_back: since 2.10
782# @ac_forward: since 2.10
783# @ac_refresh: since 2.10
784# @ac_bookmarks: since 2.10
785#
786# @muhenkan: since 2.12
787# @katakanahiragana: since 2.12
788#
789# @lang1: since 6.1
790# @lang2: since 6.1
791#
792# 'sysrq' was mistakenly added to hack around the fact that
793# the ps2 driver was not generating correct scancodes sequences
794# when 'alt+print' was pressed. This flaw is now fixed and the
795# 'sysrq' key serves no further purpose. Any further use of
796# 'sysrq' will be transparently changed to 'print', so they
797# are effectively synonyms.
798#
799# Since: 1.3
800#
801##
802{ 'enum': 'QKeyCode',
803  'data': [ 'unmapped',
804            'shift', 'shift_r', 'alt', 'alt_r', 'ctrl',
805            'ctrl_r', 'menu', 'esc', '1', '2', '3', '4', '5', '6', '7', '8',
806            '9', '0', 'minus', 'equal', 'backspace', 'tab', 'q', 'w', 'e',
807            'r', 't', 'y', 'u', 'i', 'o', 'p', 'bracket_left', 'bracket_right',
808            'ret', 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'semicolon',
809            'apostrophe', 'grave_accent', 'backslash', 'z', 'x', 'c', 'v', 'b',
810            'n', 'm', 'comma', 'dot', 'slash', 'asterisk', 'spc', 'caps_lock',
811            'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10',
812            'num_lock', 'scroll_lock', 'kp_divide', 'kp_multiply',
813            'kp_subtract', 'kp_add', 'kp_enter', 'kp_decimal', 'sysrq', 'kp_0',
814            'kp_1', 'kp_2', 'kp_3', 'kp_4', 'kp_5', 'kp_6', 'kp_7', 'kp_8',
815            'kp_9', 'less', 'f11', 'f12', 'print', 'home', 'pgup', 'pgdn', 'end',
816            'left', 'up', 'down', 'right', 'insert', 'delete', 'stop', 'again',
817            'props', 'undo', 'front', 'copy', 'open', 'paste', 'find', 'cut',
818            'lf', 'help', 'meta_l', 'meta_r', 'compose', 'pause',
819            'ro', 'hiragana', 'henkan', 'yen', 'muhenkan', 'katakanahiragana',
820            'kp_comma', 'kp_equals', 'power', 'sleep', 'wake',
821            'audionext', 'audioprev', 'audiostop', 'audioplay', 'audiomute',
822            'volumeup', 'volumedown', 'mediaselect',
823            'mail', 'calculator', 'computer',
824            'ac_home', 'ac_back', 'ac_forward', 'ac_refresh', 'ac_bookmarks',
825            'lang1', 'lang2' ] }
826
827##
828# @KeyValue:
829#
830# Represents a keyboard key.
831#
832# Since: 1.3
833##
834{ 'union': 'KeyValue',
835  'data': {
836    'number': 'int',
837    'qcode': 'QKeyCode' } }
838
839##
840# @send-key:
841#
842# Send keys to guest.
843#
844# @keys: An array of @KeyValue elements. All @KeyValues in this array are
845#        simultaneously sent to the guest. A @KeyValue.number value is sent
846#        directly to the guest, while @KeyValue.qcode must be a valid
847#        @QKeyCode value
848#
849# @hold-time: time to delay key up events, milliseconds. Defaults
850#             to 100
851#
852# Returns: - Nothing on success
853#          - If key is unknown or redundant, InvalidParameter
854#
855# Since: 1.3
856#
857# Example:
858#
859# -> { "execute": "send-key",
860#      "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
861#                               { "type": "qcode", "data": "alt" },
862#                               { "type": "qcode", "data": "delete" } ] } }
863# <- { "return": {} }
864#
865##
866{ 'command': 'send-key',
867  'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } }
868
869##
870# @InputButton:
871#
872# Button of a pointer input device (mouse, tablet).
873#
874# @side: front side button of a 5-button mouse (since 2.9)
875#
876# @extra: rear side button of a 5-button mouse (since 2.9)
877#
878# Since: 2.0
879##
880{ 'enum'  : 'InputButton',
881  'data'  : [ 'left', 'middle', 'right', 'wheel-up', 'wheel-down', 'side',
882  'extra' ] }
883
884##
885# @InputAxis:
886#
887# Position axis of a pointer input device (mouse, tablet).
888#
889# Since: 2.0
890##
891{ 'enum'  : 'InputAxis',
892  'data'  : [ 'x', 'y' ] }
893
894##
895# @InputKeyEvent:
896#
897# Keyboard input event.
898#
899# @key:    Which key this event is for.
900# @down:   True for key-down and false for key-up events.
901#
902# Since: 2.0
903##
904{ 'struct'  : 'InputKeyEvent',
905  'data'  : { 'key'     : 'KeyValue',
906              'down'    : 'bool' } }
907
908##
909# @InputBtnEvent:
910#
911# Pointer button input event.
912#
913# @button: Which button this event is for.
914# @down:   True for key-down and false for key-up events.
915#
916# Since: 2.0
917##
918{ 'struct'  : 'InputBtnEvent',
919  'data'  : { 'button'  : 'InputButton',
920              'down'    : 'bool' } }
921
922##
923# @InputMoveEvent:
924#
925# Pointer motion input event.
926#
927# @axis: Which axis is referenced by @value.
928# @value: Pointer position.  For absolute coordinates the
929#         valid range is 0 -> 0x7ffff
930#
931# Since: 2.0
932##
933{ 'struct'  : 'InputMoveEvent',
934  'data'  : { 'axis'    : 'InputAxis',
935              'value'   : 'int' } }
936
937##
938# @InputEvent:
939#
940# Input event union.
941#
942# @type: the input type, one of:
943#
944#        - 'key': Input event of Keyboard
945#        - 'btn': Input event of pointer buttons
946#        - 'rel': Input event of relative pointer motion
947#        - 'abs': Input event of absolute pointer motion
948#
949# Since: 2.0
950##
951{ 'union' : 'InputEvent',
952  'data'  : { 'key'     : 'InputKeyEvent',
953              'btn'     : 'InputBtnEvent',
954              'rel'     : 'InputMoveEvent',
955              'abs'     : 'InputMoveEvent' } }
956
957##
958# @input-send-event:
959#
960# Send input event(s) to guest.
961#
962# The @device and @head parameters can be used to send the input event
963# to specific input devices in case (a) multiple input devices of the
964# same kind are added to the virtual machine and (b) you have
965# configured input routing (see docs/multiseat.txt) for those input
966# devices.  The parameters work exactly like the device and head
967# properties of input devices.  If @device is missing, only devices
968# that have no input routing config are admissible.  If @device is
969# specified, both input devices with and without input routing config
970# are admissible, but devices with input routing config take
971# precedence.
972#
973# @device: display device to send event(s) to.
974# @head: head to send event(s) to, in case the
975#        display device supports multiple scanouts.
976# @events: List of InputEvent union.
977#
978# Returns: Nothing on success.
979#
980# Since: 2.6
981#
982# Note: The consoles are visible in the qom tree, under
983#       /backend/console[$index]. They have a device link and head property,
984#       so it is possible to map which console belongs to which device and
985#       display.
986#
987# Example:
988#
989# 1. Press left mouse button.
990#
991# -> { "execute": "input-send-event",
992#     "arguments": { "device": "video0",
993#                    "events": [ { "type": "btn",
994#                    "data" : { "down": true, "button": "left" } } ] } }
995# <- { "return": {} }
996#
997# -> { "execute": "input-send-event",
998#     "arguments": { "device": "video0",
999#                    "events": [ { "type": "btn",
1000#                    "data" : { "down": false, "button": "left" } } ] } }
1001# <- { "return": {} }
1002#
1003# 2. Press ctrl-alt-del.
1004#
1005# -> { "execute": "input-send-event",
1006#      "arguments": { "events": [
1007#         { "type": "key", "data" : { "down": true,
1008#           "key": {"type": "qcode", "data": "ctrl" } } },
1009#         { "type": "key", "data" : { "down": true,
1010#           "key": {"type": "qcode", "data": "alt" } } },
1011#         { "type": "key", "data" : { "down": true,
1012#           "key": {"type": "qcode", "data": "delete" } } } ] } }
1013# <- { "return": {} }
1014#
1015# 3. Move mouse pointer to absolute coordinates (20000, 400).
1016#
1017# -> { "execute": "input-send-event" ,
1018#   "arguments": { "events": [
1019#                { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
1020#                { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
1021# <- { "return": {} }
1022#
1023##
1024{ 'command': 'input-send-event',
1025  'data': { '*device': 'str',
1026            '*head'  : 'int',
1027            'events' : [ 'InputEvent' ] } }
1028
1029##
1030# @DisplayGTK:
1031#
1032# GTK display options.
1033#
1034# @grab-on-hover: Grab keyboard input on mouse hover.
1035# @zoom-to-fit: Zoom guest display to fit into the host window.  When
1036#               turned off the host window will be resized instead.
1037#               In case the display device can notify the guest on
1038#               window resizes (virtio-gpu) this will default to "on",
1039#               assuming the guest will resize the display to match
1040#               the window size then.  Otherwise it defaults to "off".
1041#               Since 3.1
1042#
1043# Since: 2.12
1044#
1045##
1046{ 'struct'  : 'DisplayGTK',
1047  'data'    : { '*grab-on-hover' : 'bool',
1048                '*zoom-to-fit'   : 'bool'  } }
1049
1050##
1051# @DisplayEGLHeadless:
1052#
1053# EGL headless display options.
1054#
1055# @rendernode: Which DRM render node should be used. Default is the first
1056#              available node on the host.
1057#
1058# Since: 3.1
1059#
1060##
1061{ 'struct'  : 'DisplayEGLHeadless',
1062  'data'    : { '*rendernode' : 'str' } }
1063
1064 ##
1065 # @DisplayGLMode:
1066 #
1067 # Display OpenGL mode.
1068 #
1069 # @off: Disable OpenGL (default).
1070 # @on: Use OpenGL, pick context type automatically.
1071 #      Would better be named 'auto' but is called 'on' for backward
1072 #      compatibility with bool type.
1073 # @core: Use OpenGL with Core (desktop) Context.
1074 # @es: Use OpenGL with ES (embedded systems) Context.
1075 #
1076 # Since: 3.0
1077 #
1078 ##
1079{ 'enum'    : 'DisplayGLMode',
1080  'data'    : [ 'off', 'on', 'core', 'es' ] }
1081
1082##
1083# @DisplayCurses:
1084#
1085# Curses display options.
1086#
1087# @charset:       Font charset used by guest (default: CP437).
1088#
1089# Since: 4.0
1090#
1091##
1092{ 'struct'  : 'DisplayCurses',
1093  'data'    : { '*charset'       : 'str' } }
1094
1095##
1096# @DisplayType:
1097#
1098# Display (user interface) type.
1099#
1100# @default: The default user interface, selecting from the first available
1101#           of gtk, sdl, cocoa, and vnc.
1102#
1103# @none: No user interface or video output display. The guest will
1104#        still see an emulated graphics card, but its output will not
1105#        be displayed to the QEMU user.
1106#
1107# @gtk: The GTK user interface.
1108#
1109# @sdl: The SDL user interface.
1110#
1111# @egl-headless: No user interface, offload GL operations to a local
1112#                DRI device. Graphical display need to be paired with
1113#                VNC or Spice. (Since 3.1)
1114#
1115# @curses: Display video output via curses.  For graphics device
1116#          models which support a text mode, QEMU can display this
1117#          output using a curses/ncurses interface. Nothing is
1118#          displayed when the graphics device is in graphical mode or
1119#          if the graphics device does not support a text
1120#          mode. Generally only the VGA device models support text
1121#          mode.
1122#
1123# @cocoa: The Cocoa user interface.
1124#
1125# @spice-app: Set up a Spice server and run the default associated
1126#             application to connect to it. The server will redirect
1127#             the serial console and QEMU monitors. (Since 4.0)
1128#
1129# Since: 2.12
1130#
1131##
1132{ 'enum'    : 'DisplayType',
1133  'data'    : [
1134    { 'name': 'default' },
1135    { 'name': 'none' },
1136    { 'name': 'gtk', 'if': 'defined(CONFIG_GTK)' },
1137    { 'name': 'sdl', 'if': 'defined(CONFIG_SDL)' },
1138    { 'name': 'egl-headless',
1139              'if': 'defined(CONFIG_OPENGL) && defined(CONFIG_GBM)' },
1140    { 'name': 'curses', 'if': 'defined(CONFIG_CURSES)' },
1141    { 'name': 'cocoa', 'if': 'defined(CONFIG_COCOA)' },
1142    { 'name': 'spice-app', 'if': 'defined(CONFIG_SPICE)'} ] }
1143
1144##
1145# @DisplayOptions:
1146#
1147# Display (user interface) options.
1148#
1149# @type:          Which DisplayType qemu should use.
1150# @full-screen:   Start user interface in fullscreen mode (default: off).
1151# @window-close:  Allow to quit qemu with window close button (default: on).
1152# @show-cursor:   Force showing the mouse cursor (default: off).
1153#                 (since: 5.0)
1154# @gl:            Enable OpenGL support (default: off).
1155#
1156# Since: 2.12
1157#
1158##
1159{ 'union'   : 'DisplayOptions',
1160  'base'    : { 'type'           : 'DisplayType',
1161                '*full-screen'   : 'bool',
1162                '*window-close'  : 'bool',
1163                '*show-cursor'   : 'bool',
1164                '*gl'            : 'DisplayGLMode' },
1165  'discriminator' : 'type',
1166  'data'    : {
1167      'gtk': { 'type': 'DisplayGTK', 'if': 'defined(CONFIG_GTK)' },
1168      'curses': { 'type': 'DisplayCurses', 'if': 'defined(CONFIG_CURSES)' },
1169      'egl-headless': { 'type': 'DisplayEGLHeadless',
1170                        'if': 'defined(CONFIG_OPENGL) && defined(CONFIG_GBM)' }
1171  }
1172}
1173
1174##
1175# @query-display-options:
1176#
1177# Returns information about display configuration
1178#
1179# Returns: @DisplayOptions
1180#
1181# Since: 3.1
1182#
1183##
1184{ 'command': 'query-display-options',
1185  'returns': 'DisplayOptions' }
1186
1187##
1188# @DisplayReloadType:
1189#
1190# Available DisplayReload types.
1191#
1192# @vnc: VNC display
1193#
1194# Since: 6.0
1195#
1196##
1197{ 'enum': 'DisplayReloadType',
1198  'data': ['vnc'] }
1199
1200##
1201# @DisplayReloadOptionsVNC:
1202#
1203# Specify the VNC reload options.
1204#
1205# @tls-certs: reload tls certs or not.
1206#
1207# Since: 6.0
1208#
1209##
1210{ 'struct': 'DisplayReloadOptionsVNC',
1211  'data': { '*tls-certs': 'bool' } }
1212
1213##
1214# @DisplayReloadOptions:
1215#
1216# Options of the display configuration reload.
1217#
1218# @type: Specify the display type.
1219#
1220# Since: 6.0
1221#
1222##
1223{ 'union': 'DisplayReloadOptions',
1224  'base': {'type': 'DisplayReloadType'},
1225  'discriminator': 'type',
1226  'data': { 'vnc': 'DisplayReloadOptionsVNC' } }
1227
1228##
1229# @display-reload:
1230#
1231# Reload display configuration.
1232#
1233# Returns: Nothing on success.
1234#
1235# Since: 6.0
1236#
1237# Example:
1238#
1239# -> { "execute": "display-reload",
1240#      "arguments": { "type": "vnc", "tls-certs": true  } }
1241# <- { "return": {} }
1242#
1243##
1244{ 'command': 'display-reload',
1245  'data': 'DisplayReloadOptions',
1246  'boxed' : true }
1247