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