xref: /openbmc/qemu/qapi/ui.json (revision 0e2a7611)
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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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': '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# @KeyValueKind:
829#
830# Since: 1.3
831##
832{ 'enum': 'KeyValueKind',
833  'data': [ 'number', 'qcode' ] }
834
835##
836# @IntWrapper:
837#
838# Since: 1.3
839##
840{ 'struct': 'IntWrapper',
841  'data': { 'data': 'int' } }
842
843##
844# @QKeyCodeWrapper:
845#
846# Since: 1.3
847##
848{ 'struct': 'QKeyCodeWrapper',
849  'data': { 'data': 'QKeyCode' } }
850
851##
852# @KeyValue:
853#
854# Represents a keyboard key.
855#
856# Since: 1.3
857##
858{ 'union': 'KeyValue',
859  'base': { 'type': 'KeyValueKind' },
860  'discriminator': 'type',
861  'data': {
862    'number': 'IntWrapper',
863    'qcode': 'QKeyCodeWrapper' } }
864
865##
866# @send-key:
867#
868# Send keys to guest.
869#
870# @keys: An array of @KeyValue elements. All @KeyValues in this array are
871#        simultaneously sent to the guest. A @KeyValue.number value is sent
872#        directly to the guest, while @KeyValue.qcode must be a valid
873#        @QKeyCode value
874#
875# @hold-time: time to delay key up events, milliseconds. Defaults
876#             to 100
877#
878# Returns: - Nothing on success
879#          - If key is unknown or redundant, InvalidParameter
880#
881# Since: 1.3
882#
883# Example:
884#
885# -> { "execute": "send-key",
886#      "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
887#                               { "type": "qcode", "data": "alt" },
888#                               { "type": "qcode", "data": "delete" } ] } }
889# <- { "return": {} }
890#
891##
892{ 'command': 'send-key',
893  'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } }
894
895##
896# @InputButton:
897#
898# Button of a pointer input device (mouse, tablet).
899#
900# @side: front side button of a 5-button mouse (since 2.9)
901#
902# @extra: rear side button of a 5-button mouse (since 2.9)
903#
904# Since: 2.0
905##
906{ 'enum'  : 'InputButton',
907  'data'  : [ 'left', 'middle', 'right', 'wheel-up', 'wheel-down', 'side',
908  'extra' ] }
909
910##
911# @InputAxis:
912#
913# Position axis of a pointer input device (mouse, tablet).
914#
915# Since: 2.0
916##
917{ 'enum'  : 'InputAxis',
918  'data'  : [ 'x', 'y' ] }
919
920##
921# @InputKeyEvent:
922#
923# Keyboard input event.
924#
925# @key:    Which key this event is for.
926# @down:   True for key-down and false for key-up events.
927#
928# Since: 2.0
929##
930{ 'struct'  : 'InputKeyEvent',
931  'data'  : { 'key'     : 'KeyValue',
932              'down'    : 'bool' } }
933
934##
935# @InputBtnEvent:
936#
937# Pointer button input event.
938#
939# @button: Which button this event is for.
940# @down:   True for key-down and false for key-up events.
941#
942# Since: 2.0
943##
944{ 'struct'  : 'InputBtnEvent',
945  'data'  : { 'button'  : 'InputButton',
946              'down'    : 'bool' } }
947
948##
949# @InputMoveEvent:
950#
951# Pointer motion input event.
952#
953# @axis: Which axis is referenced by @value.
954# @value: Pointer position.  For absolute coordinates the
955#         valid range is 0 -> 0x7ffff
956#
957# Since: 2.0
958##
959{ 'struct'  : 'InputMoveEvent',
960  'data'  : { 'axis'    : 'InputAxis',
961              'value'   : 'int' } }
962
963##
964# @InputEventKind:
965#
966# Since: 2.0
967##
968{ 'enum': 'InputEventKind',
969  'data': [ 'key', 'btn', 'rel', 'abs' ] }
970
971##
972# @InputKeyEventWrapper:
973#
974# Since: 2.0
975##
976{ 'struct': 'InputKeyEventWrapper',
977  'data': { 'data': 'InputKeyEvent' } }
978
979##
980# @InputBtnEventWrapper:
981#
982# Since: 2.0
983##
984{ 'struct': 'InputBtnEventWrapper',
985  'data': { 'data': 'InputBtnEvent' } }
986
987##
988# @InputMoveEventWrapper:
989#
990# Since: 2.0
991##
992{ 'struct': 'InputMoveEventWrapper',
993  'data': { 'data': 'InputMoveEvent' } }
994
995##
996# @InputEvent:
997#
998# Input event union.
999#
1000# @type: the input type, one of:
1001#
1002#        - 'key': Input event of Keyboard
1003#        - 'btn': Input event of pointer buttons
1004#        - 'rel': Input event of relative pointer motion
1005#        - 'abs': Input event of absolute pointer motion
1006#
1007# Since: 2.0
1008##
1009{ 'union' : 'InputEvent',
1010  'base': { 'type': 'InputEventKind' },
1011  'discriminator': 'type',
1012  'data'  : { 'key'     : 'InputKeyEventWrapper',
1013              'btn'     : 'InputBtnEventWrapper',
1014              'rel'     : 'InputMoveEventWrapper',
1015              'abs'     : 'InputMoveEventWrapper' } }
1016
1017##
1018# @input-send-event:
1019#
1020# Send input event(s) to guest.
1021#
1022# The @device and @head parameters can be used to send the input event
1023# to specific input devices in case (a) multiple input devices of the
1024# same kind are added to the virtual machine and (b) you have
1025# configured input routing (see docs/multiseat.txt) for those input
1026# devices.  The parameters work exactly like the device and head
1027# properties of input devices.  If @device is missing, only devices
1028# that have no input routing config are admissible.  If @device is
1029# specified, both input devices with and without input routing config
1030# are admissible, but devices with input routing config take
1031# precedence.
1032#
1033# @device: display device to send event(s) to.
1034# @head: head to send event(s) to, in case the
1035#        display device supports multiple scanouts.
1036# @events: List of InputEvent union.
1037#
1038# Returns: Nothing on success.
1039#
1040# Since: 2.6
1041#
1042# Note: The consoles are visible in the qom tree, under
1043#       /backend/console[$index]. They have a device link and head property,
1044#       so it is possible to map which console belongs to which device and
1045#       display.
1046#
1047# Example:
1048#
1049# 1. Press left mouse button.
1050#
1051# -> { "execute": "input-send-event",
1052#     "arguments": { "device": "video0",
1053#                    "events": [ { "type": "btn",
1054#                    "data" : { "down": true, "button": "left" } } ] } }
1055# <- { "return": {} }
1056#
1057# -> { "execute": "input-send-event",
1058#     "arguments": { "device": "video0",
1059#                    "events": [ { "type": "btn",
1060#                    "data" : { "down": false, "button": "left" } } ] } }
1061# <- { "return": {} }
1062#
1063# 2. Press ctrl-alt-del.
1064#
1065# -> { "execute": "input-send-event",
1066#      "arguments": { "events": [
1067#         { "type": "key", "data" : { "down": true,
1068#           "key": {"type": "qcode", "data": "ctrl" } } },
1069#         { "type": "key", "data" : { "down": true,
1070#           "key": {"type": "qcode", "data": "alt" } } },
1071#         { "type": "key", "data" : { "down": true,
1072#           "key": {"type": "qcode", "data": "delete" } } } ] } }
1073# <- { "return": {} }
1074#
1075# 3. Move mouse pointer to absolute coordinates (20000, 400).
1076#
1077# -> { "execute": "input-send-event" ,
1078#   "arguments": { "events": [
1079#                { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
1080#                { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
1081# <- { "return": {} }
1082#
1083##
1084{ 'command': 'input-send-event',
1085  'data': { '*device': 'str',
1086            '*head'  : 'int',
1087            'events' : [ 'InputEvent' ] } }
1088
1089##
1090# @DisplayGTK:
1091#
1092# GTK display options.
1093#
1094# @grab-on-hover: Grab keyboard input on mouse hover.
1095# @zoom-to-fit: Zoom guest display to fit into the host window.  When
1096#               turned off the host window will be resized instead.
1097#               In case the display device can notify the guest on
1098#               window resizes (virtio-gpu) this will default to "on",
1099#               assuming the guest will resize the display to match
1100#               the window size then.  Otherwise it defaults to "off".
1101#               Since 3.1
1102#
1103# Since: 2.12
1104#
1105##
1106{ 'struct'  : 'DisplayGTK',
1107  'data'    : { '*grab-on-hover' : 'bool',
1108                '*zoom-to-fit'   : 'bool'  } }
1109
1110##
1111# @DisplayEGLHeadless:
1112#
1113# EGL headless display options.
1114#
1115# @rendernode: Which DRM render node should be used. Default is the first
1116#              available node on the host.
1117#
1118# Since: 3.1
1119#
1120##
1121{ 'struct'  : 'DisplayEGLHeadless',
1122  'data'    : { '*rendernode' : 'str' } }
1123
1124 ##
1125 # @DisplayGLMode:
1126 #
1127 # Display OpenGL mode.
1128 #
1129 # @off: Disable OpenGL (default).
1130 # @on: Use OpenGL, pick context type automatically.
1131 #      Would better be named 'auto' but is called 'on' for backward
1132 #      compatibility with bool type.
1133 # @core: Use OpenGL with Core (desktop) Context.
1134 # @es: Use OpenGL with ES (embedded systems) Context.
1135 #
1136 # Since: 3.0
1137 #
1138 ##
1139{ 'enum'    : 'DisplayGLMode',
1140  'data'    : [ 'off', 'on', 'core', 'es' ] }
1141
1142##
1143# @DisplayCurses:
1144#
1145# Curses display options.
1146#
1147# @charset:       Font charset used by guest (default: CP437).
1148#
1149# Since: 4.0
1150#
1151##
1152{ 'struct'  : 'DisplayCurses',
1153  'data'    : { '*charset'       : 'str' } }
1154
1155##
1156# @DisplayType:
1157#
1158# Display (user interface) type.
1159#
1160# @default: The default user interface, selecting from the first available
1161#           of gtk, sdl, cocoa, and vnc.
1162#
1163# @none: No user interface or video output display. The guest will
1164#        still see an emulated graphics card, but its output will not
1165#        be displayed to the QEMU user.
1166#
1167# @gtk: The GTK user interface.
1168#
1169# @sdl: The SDL user interface.
1170#
1171# @egl-headless: No user interface, offload GL operations to a local
1172#                DRI device. Graphical display need to be paired with
1173#                VNC or Spice. (Since 3.1)
1174#
1175# @curses: Display video output via curses.  For graphics device
1176#          models which support a text mode, QEMU can display this
1177#          output using a curses/ncurses interface. Nothing is
1178#          displayed when the graphics device is in graphical mode or
1179#          if the graphics device does not support a text
1180#          mode. Generally only the VGA device models support text
1181#          mode.
1182#
1183# @cocoa: The Cocoa user interface.
1184#
1185# @spice-app: Set up a Spice server and run the default associated
1186#             application to connect to it. The server will redirect
1187#             the serial console and QEMU monitors. (Since 4.0)
1188#
1189# Since: 2.12
1190#
1191##
1192{ 'enum'    : 'DisplayType',
1193  'data'    : [
1194    { 'name': 'default' },
1195    { 'name': 'none' },
1196    { 'name': 'gtk', 'if': 'CONFIG_GTK' },
1197    { 'name': 'sdl', 'if': 'CONFIG_SDL' },
1198    { 'name': 'egl-headless',
1199              'if': { 'all': ['CONFIG_OPENGL', 'CONFIG_GBM'] } },
1200    { 'name': 'curses', 'if': 'CONFIG_CURSES' },
1201    { 'name': 'cocoa', 'if': 'CONFIG_COCOA' },
1202    { 'name': 'spice-app', 'if': 'CONFIG_SPICE'} ] }
1203
1204##
1205# @DisplayOptions:
1206#
1207# Display (user interface) options.
1208#
1209# @type:          Which DisplayType qemu should use.
1210# @full-screen:   Start user interface in fullscreen mode (default: off).
1211# @window-close:  Allow to quit qemu with window close button (default: on).
1212# @show-cursor:   Force showing the mouse cursor (default: off).
1213#                 (since: 5.0)
1214# @gl:            Enable OpenGL support (default: off).
1215#
1216# Since: 2.12
1217#
1218##
1219{ 'union'   : 'DisplayOptions',
1220  'base'    : { 'type'           : 'DisplayType',
1221                '*full-screen'   : 'bool',
1222                '*window-close'  : 'bool',
1223                '*show-cursor'   : 'bool',
1224                '*gl'            : 'DisplayGLMode' },
1225  'discriminator' : 'type',
1226  'data'    : {
1227      'gtk': { 'type': 'DisplayGTK', 'if': 'CONFIG_GTK' },
1228      'curses': { 'type': 'DisplayCurses', 'if': 'CONFIG_CURSES' },
1229      'egl-headless': { 'type': 'DisplayEGLHeadless',
1230                        'if': { 'all': ['CONFIG_OPENGL', 'CONFIG_GBM'] } }
1231  }
1232}
1233
1234##
1235# @query-display-options:
1236#
1237# Returns information about display configuration
1238#
1239# Returns: @DisplayOptions
1240#
1241# Since: 3.1
1242#
1243##
1244{ 'command': 'query-display-options',
1245  'returns': 'DisplayOptions' }
1246
1247##
1248# @DisplayReloadType:
1249#
1250# Available DisplayReload types.
1251#
1252# @vnc: VNC display
1253#
1254# Since: 6.0
1255#
1256##
1257{ 'enum': 'DisplayReloadType',
1258  'data': ['vnc'] }
1259
1260##
1261# @DisplayReloadOptionsVNC:
1262#
1263# Specify the VNC reload options.
1264#
1265# @tls-certs: reload tls certs or not.
1266#
1267# Since: 6.0
1268#
1269##
1270{ 'struct': 'DisplayReloadOptionsVNC',
1271  'data': { '*tls-certs': 'bool' } }
1272
1273##
1274# @DisplayReloadOptions:
1275#
1276# Options of the display configuration reload.
1277#
1278# @type: Specify the display type.
1279#
1280# Since: 6.0
1281#
1282##
1283{ 'union': 'DisplayReloadOptions',
1284  'base': {'type': 'DisplayReloadType'},
1285  'discriminator': 'type',
1286  'data': { 'vnc': 'DisplayReloadOptionsVNC' } }
1287
1288##
1289# @display-reload:
1290#
1291# Reload display configuration.
1292#
1293# Returns: Nothing on success.
1294#
1295# Since: 6.0
1296#
1297# Example:
1298#
1299# -> { "execute": "display-reload",
1300#      "arguments": { "type": "vnc", "tls-certs": true  } }
1301# <- { "return": {} }
1302#
1303##
1304{ 'command': 'display-reload',
1305  'data': 'DisplayReloadOptions',
1306  'boxed' : true }
1307