mirrors/qemu
0
0
Fork 0
mirror of https://github.com/qemu/qemu.git synced 2024-12-02 08:13:34 +08:00
Code Issues Packages Projects Releases Wiki Activity
459264ef24
qemu/qapi/event.json
Markus Armbruster 1d8bda128d qapi: The #optional tag is redundant, drop 
We traditionally mark optional members #optional in the doc comment.
Before commit 3313b61, this was entirely manual.

Commit 3313b61 added some automation because its qapi2texi.py relied
on #optional to determine whether a member is optional.  This is no
longer the case since the previous commit: the only thing qapi2texi.py
still does with #optional is stripping it out.  We still reject bogus
qapi-schema.json and six places for qga/qapi-schema.json.

Thus, you can't actually rely on #optional to see whether something is
optional.  Yet we still make people add it manually.  That's just
busy-work.

Drop the code to check, fix up and strip out #optional, along with all
instances of #optional.  To keep it out, add code to reject it, to be
dropped again once the dust settles.

No change to generated documentation.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <1489582656-31133-18-git-send-email-armbru@redhat.com>
2017-03-16 07:13:02 +01:00

638 lines
14 KiB
Python
Raw Blame History

# -*- Mode: Python -*-
##
# = Other events
##
##
# @SHUTDOWN:
#
# Emitted when the virtual machine has shut down, indicating that qemu is
# about to exit.
#
# Note: If the command-line option "-no-shutdown" has been specified, qemu will
# not exit, and a STOP event will eventually follow the SHUTDOWN event
#
# Since: 0.12.0
#
# Example:
#
# <- { "event": "SHUTDOWN",
# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
#
##
{ 'event': 'SHUTDOWN' }
##
# @POWERDOWN:
#
# Emitted when the virtual machine is powered down through the power control
# system, such as via ACPI.
#
# Since: 0.12.0
#
# Example:
#
# <- { "event": "POWERDOWN",
# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
#
##
{ 'event': 'POWERDOWN' }
##
# @RESET:
#
# Emitted when the virtual machine is reset
#
# Since: 0.12.0
#
# Example:
#
# <- { "event": "RESET",
# "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
#
##
{ 'event': 'RESET' }
##
# @STOP:
#
# Emitted when the virtual machine is stopped
#
# Since: 0.12.0
#
# Example:
#
# <- { "event": "STOP",
# "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
#
##
{ 'event': 'STOP' }
##
# @RESUME:
#
# Emitted when the virtual machine resumes execution
#
# Since: 0.12.0
#
# Example:
#
# <- { "event": "RESUME",
# "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
#
##
{ 'event': 'RESUME' }
##
# @SUSPEND:
#
# Emitted when guest enters a hardware suspension state, for example, S3 state,
# which is sometimes called standby state
#
# Since: 1.1
#
# Example:
#
# <- { "event": "SUSPEND",
# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
#
##
{ 'event': 'SUSPEND' }
##
# @SUSPEND_DISK:
#
# Emitted when guest enters a hardware suspension state with data saved on
# disk, for example, S4 state, which is sometimes called hibernate state
#
# Note: QEMU shuts down (similar to event @SHUTDOWN) when entering this state
#
# Since: 1.2
#
# Example:
#
# <- { "event": "SUSPEND_DISK",
# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
#
##
{ 'event': 'SUSPEND_DISK' }
##
# @WAKEUP:
#
# Emitted when the guest has woken up from suspend state and is running
#
# Since: 1.1
#
# Example:
#
# <- { "event": "WAKEUP",
# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
#
##
{ 'event': 'WAKEUP' }
##
# @RTC_CHANGE:
#
# Emitted when the guest changes the RTC time.
#
# @offset: offset between base RTC clock (as specified by -rtc base), and
# new RTC clock value
#
# Note: This event is rate-limited.
#
# Since: 0.13.0
#
# Example:
#
# <- { "event": "RTC_CHANGE",
# "data": { "offset": 78 },
# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
#
##
{ 'event': 'RTC_CHANGE',
'data': { 'offset': 'int' } }
##
# @WATCHDOG:
#
# Emitted when the watchdog device's timer is expired
#
# @action: action that has been taken
#
# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
# followed respectively by the RESET, SHUTDOWN, or STOP events
#
# Note: This event is rate-limited.
#
# Since: 0.13.0
#
# Example:
#
# <- { "event": "WATCHDOG",
# "data": { "action": "reset" },
# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
#
##
{ 'event': 'WATCHDOG',
'data': { 'action': 'WatchdogExpirationAction' } }
##
# @DEVICE_DELETED:
#
# Emitted whenever the device removal completion is acknowledged by the guest.
# At this point, it's safe to reuse the specified device ID. Device removal can
# be initiated by the guest or by HMP/QMP commands.
#
# @device: device name
#
# @path: device path
#
# Since: 1.5
#
# Example:
#
# <- { "event": "DEVICE_DELETED",
# "data": { "device": "virtio-net-pci-0",
# "path": "/machine/peripheral/virtio-net-pci-0" },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
#
##
{ 'event': 'DEVICE_DELETED',
'data': { '*device': 'str', 'path': 'str' } }
##
# @NIC_RX_FILTER_CHANGED:
#
# Emitted once until the 'query-rx-filter' command is executed, the first event
# will always be emitted
#
# @name: net client name
#
# @path: device path
#
# Since: 1.6
#
# Example:
#
# <- { "event": "NIC_RX_FILTER_CHANGED",
# "data": { "name": "vnet0",
# "path": "/machine/peripheral/vnet0/virtio-backend" },
# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
# }
#
##
{ 'event': 'NIC_RX_FILTER_CHANGED',
'data': { '*name': 'str', 'path': 'str' } }
##
# @VNC_CONNECTED:
#
# Emitted when a VNC client establishes a connection
#
# @server: server information
#
# @client: client information
#
# Note: This event is emitted before any authentication takes place, thus
# the authentication ID is not provided
#
# Since: 0.13.0
#
# Example:
#
# <- { "event": "VNC_CONNECTED",
# "data": {
# "server": { "auth": "sasl", "family": "ipv4",
# "service": "5901", "host": "0.0.0.0" },
# "client": { "family": "ipv4", "service": "58425",
# "host": "127.0.0.1" } },
# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
#
##
{ 'event': 'VNC_CONNECTED',
'data': { 'server': 'VncServerInfo',
'client': 'VncBasicInfo' } }
##
# @VNC_INITIALIZED:
#
# Emitted after authentication takes place (if any) and the VNC session is
# made active
#
# @server: server information
#
# @client: client information
#
# Since: 0.13.0
#
# Example:
#
# <- { "event": "VNC_INITIALIZED",
# "data": {
# "server": { "auth": "sasl", "family": "ipv4",
# "service": "5901", "host": "0.0.0.0"},
# "client": { "family": "ipv4", "service": "46089",
# "host": "127.0.0.1", "sasl_username": "luiz" } },
# "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
#
##
{ 'event': 'VNC_INITIALIZED',
'data': { 'server': 'VncServerInfo',
'client': 'VncClientInfo' } }
##
# @VNC_DISCONNECTED:
#
# Emitted when the connection is closed
#
# @server: server information
#
# @client: client information
#
# Since: 0.13.0
#
# Example:
#
# <- { "event": "VNC_DISCONNECTED",
# "data": {
# "server": { "auth": "sasl", "family": "ipv4",
# "service": "5901", "host": "0.0.0.0" },
# "client": { "family": "ipv4", "service": "58425",
# "host": "127.0.0.1", "sasl_username": "luiz" } },
# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
#
##
{ 'event': 'VNC_DISCONNECTED',
'data': { 'server': 'VncServerInfo',
'client': 'VncClientInfo' } }
##
# @SPICE_CONNECTED:
#
# Emitted when a SPICE client establishes a connection
#
# @server: server information
#
# @client: client information
#
# Since: 0.14.0
#
# Example:
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
# "event": "SPICE_CONNECTED",
# "data": {
# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
# }}
#
##
{ 'event': 'SPICE_CONNECTED',
'data': { 'server': 'SpiceBasicInfo',
'client': 'SpiceBasicInfo' } }
##
# @SPICE_INITIALIZED:
#
# Emitted after initial handshake and authentication takes place (if any)
# and the SPICE channel is up and running
#
# @server: server information
#
# @client: client information
#
# Since: 0.14.0
#
# Example:
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
# "event": "SPICE_INITIALIZED",
# "data": {"server": {"auth": "spice", "port": "5921",
# "family": "ipv4", "host": "127.0.0.1"},
# "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
# "connection-id": 1804289383, "host": "127.0.0.1",
# "channel-id": 0, "tls": true}
# }}
#
##
{ 'event': 'SPICE_INITIALIZED',
'data': { 'server': 'SpiceServerInfo',
'client': 'SpiceChannel' } }
##
# @SPICE_DISCONNECTED:
#
# Emitted when the SPICE connection is closed
#
# @server: server information
#
# @client: client information
#
# Since: 0.14.0
#
# Example:
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
# "event": "SPICE_DISCONNECTED",
# "data": {
# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
# }}
#
##
{ 'event': 'SPICE_DISCONNECTED',
'data': { 'server': 'SpiceBasicInfo',
'client': 'SpiceBasicInfo' } }
##
# @SPICE_MIGRATE_COMPLETED:
#
# Emitted when SPICE migration has completed
#
# Since: 1.3
#
# Example:
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
# "event": "SPICE_MIGRATE_COMPLETED" }
#
##
{ 'event': 'SPICE_MIGRATE_COMPLETED' }
##
# @MIGRATION:
#
# Emitted when a migration event happens
#
# @status: @MigrationStatus describing the current migration status.
#
# Since: 2.4
#
# Example:
#
# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
# "event": "MIGRATION",
# "data": {"status": "completed"} }
#
##
{ 'event': 'MIGRATION',
'data': {'status': 'MigrationStatus'}}
##
# @MIGRATION_PASS:
#
# Emitted from the source side of a migration at the start of each pass
# (when it syncs the dirty bitmap)
#
# @pass: An incrementing count (starting at 1 on the first pass)
#
# Since: 2.6
#
# Example:
#
# { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
# "event": "MIGRATION_PASS", "data": {"pass": 2} }
#
##
{ 'event': 'MIGRATION_PASS',
'data': { 'pass': 'int' } }
##
# @ACPI_DEVICE_OST:
#
# Emitted when guest executes ACPI _OST method.
#
# @info: ACPIOSTInfo type as described in qapi-schema.json
#
# Since: 2.1
#
# Example:
#
# <- { "event": "ACPI_DEVICE_OST",
# "data": { "device": "d1", "slot": "0",
# "slot-type": "DIMM", "source": 1, "status": 0 } }
#
##
{ 'event': 'ACPI_DEVICE_OST',
'data': { 'info': 'ACPIOSTInfo' } }
##
# @BALLOON_CHANGE:
#
# Emitted when the guest changes the actual BALLOON level. This value is
# equivalent to the @actual field return by the 'query-balloon' command
#
# @actual: actual level of the guest memory balloon in bytes
#
# Note: this event is rate-limited.
#
# Since: 1.2
#
# Example:
#
# <- { "event": "BALLOON_CHANGE",
# "data": { "actual": 944766976 },
# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
#
##
{ 'event': 'BALLOON_CHANGE',
'data': { 'actual': 'int' } }
##
# @GUEST_PANICKED:
#
# Emitted when guest OS panic is detected
#
# @action: action that has been taken, currently always "pause"
#
# @info: information about a panic (since 2.9)
#
# Since: 1.5
#
# Example:
#
# <- { "event": "GUEST_PANICKED",
# "data": { "action": "pause" } }
#
##
{ 'event': 'GUEST_PANICKED',
'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
##
# @QUORUM_FAILURE:
#
# Emitted by the Quorum block driver if it fails to establish a quorum
#
# @reference: device name if defined else node name
#
# @sector-num: number of the first sector of the failed read operation
#
# @sectors-count: failed read operation sector count
#
# Note: This event is rate-limited.
#
# Since: 2.0
#
# Example:
#
# <- { "event": "QUORUM_FAILURE",
# "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
#
##
{ 'event': 'QUORUM_FAILURE',
'data': { 'reference': 'str', 'sector-num': 'int', 'sectors-count': 'int' } }
##
# @QUORUM_REPORT_BAD:
#
# Emitted to report a corruption of a Quorum file
#
# @type: quorum operation type (Since 2.6)
#
# @error: error message. Only present on failure. This field
# contains a human-readable error message. There are no semantics other
# than that the block layer reported an error and clients should not
# try to interpret the error string.
#
# @node-name: the graph node name of the block driver state
#
# @sector-num: number of the first sector of the failed read operation
#
# @sectors-count: failed read operation sector count
#
# Note: This event is rate-limited.
#
# Since: 2.0
#
# Example:
#
# 1. Read operation
#
# { "event": "QUORUM_REPORT_BAD",
# "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
# "type": "read" },
# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
#
# 2. Flush operation
#
# { "event": "QUORUM_REPORT_BAD",
# "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
# "type": "flush", "error": "Broken pipe" },
# "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
#
##
{ 'event': 'QUORUM_REPORT_BAD',
'data': { 'type': 'QuorumOpType', '*error': 'str', 'node-name': 'str',
'sector-num': 'int', 'sectors-count': 'int' } }
##
# @VSERPORT_CHANGE:
#
# Emitted when the guest opens or closes a virtio-serial port.
#
# @id: device identifier of the virtio-serial port
#
# @open: true if the guest has opened the virtio-serial port
#
# Since: 2.1
#
# Example:
#
# <- { "event": "VSERPORT_CHANGE",
# "data": { "id": "channel0", "open": true },
# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
#
##
{ 'event': 'VSERPORT_CHANGE',
'data': { 'id': 'str', 'open': 'bool' } }
##
# @MEM_UNPLUG_ERROR:
#
# Emitted when memory hot unplug error occurs.
#
# @device: device name
#
# @msg: Informative message
#
# Since: 2.4
#
# Example:
#
# <- { "event": "MEM_UNPLUG_ERROR"
# "data": { "device": "dimm1",
# "msg": "acpi: device unplug for unsupported device"
# },
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
#
##
{ 'event': 'MEM_UNPLUG_ERROR',
'data': { 'device': 'str', 'msg': 'str' } }
##
# @DUMP_COMPLETED:
#
# Emitted when background dump has completed
#
# @result: DumpQueryResult type described in qapi-schema.json.
#
# @error: human-readable error string that provides
# hint on why dump failed. Only presents on failure. The
# user should not try to interpret the error string.
#
# Since: 2.6
#
# Example:
#
# { "event": "DUMP_COMPLETED",
# "data": {"result": {"total": 1090650112, "status": "completed",
# "completed": 1090650112} } }
#
##
{ 'event': 'DUMP_COMPLETED' ,
'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
Reference in New Issue View Git Blame Copy Permalink