Re: [Qemu-devel] [PATCH 6/6] qapi: add doc for QEvent

[Wenchao Xia <xiawenc@linux.vnet.ibm.com>]

>>    Take another think, I think I may use past tense through the doc,
>> but with more carefully meaning, such as:
>> the system has enter powerdown state.
>>    If you agree with the tense, I'd like sent the reformed doc
>> in the following, before respin.
>>
> Indeed, which is why separating the docs from the refactoring made sense
> in your series, so that we could hammer out good docs.
>
>
Hi, here is my draft for qapi-schema.json, please have a look.
Note:
1 it requires directly support of 'base', so I will sent additonal patch
support it by key word '_base' in 'data' contents.
2 some define not labeled with "since 1.8', are code move.
3 reordered.


##
# @QEvent
#
# QEMU event types
#
# Since: 1.8
##
{ 'enum': 'QEvent',
   'data': [
# system related
             'SHUTDOWN',
             'POWERDOWN',
             'RESET',
             'STOP',
             'RESUME',
             'SUSPEND',
             'SUSPEND_DISK',
             'WAKEUP',

# system virtual device related
             'RTC_CHANGE',
             'WATCHDOG',
             'DEVICE_DELETED',
             'DEVICE_TRAY_MOVED',

# block related
             'BLOCK_IO_ERROR',
             'BLOCK_IMAGE_CORRUPTED',

# block job related
             'BLOCK_JOB_COMPLETED',
             'BLOCK_JOB_CANCELLED',
             'BLOCK_JOB_ERROR',
             'BLOCK_JOB_READY',

# network related
             'NIC_RX_FILTER_CHANGED',

# vnc display related
             'VNC_CONNECTED',
             'VNC_INITIALIZED',
             'VNC_DISCONNECTED',

# spice display related
             'SPICE_CONNECTED',
             'SPICE_INITIALIZED',
             'SPICE_DISCONNECTED',
             'SPICE_MIGRATE_COMPLETED',

# guest related
             'BALLOON_CHANGE',
             'GUEST_PANICKED' ] }

##
# @EventTimestamp
#
# Reflect the time when event happens
#
# @seconds: the seconds have passed on host system
#
# @microsecnds: the microseconds have passed on host system
#
# Since: 1.8
##
{ 'type': 'EventTimestamp',
   'data': { 'seconds': 'int', 'microsecnds': 'int' } }

##
# @EventBase
#
# Base type containing properties that are available for all kind of events
#
# @event: type of the event
#
# @timestamp: the time stamp of the event, which is got from host system
#
# Since: 1.8
##
{ 'type': 'EventBase',
   'data': { 'event': 'QEvent', 'timestamp': 'EventTimestamp' } }


##
# @EventShutdown
#
# Emitted when the virtual machine shutdown, qemu terminates the 
emulation and
# exit. 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: 1.8
##
{ 'type': 'EventShutdown',
   'data': { } }

##
# @EventPowerdown
#
# Emitted when the virtual machine is powered down, qemu tries to set the
# system power control system, such as ACPI related virtual chips
#
# Since: 1.8
##
{ 'type': 'EventPowerdown',
   'data': { } }

##
# @EventReset
#
# Emitted when the virtual machine is reseted
#
# Since: 1.8
##
{ 'type': 'EventReset',
   'data': { } }

##
# @EventStop
#
# Emitted when the virtual machine is stopped
#
# Since: 1.8
##
{ 'type': 'EventStop',
   'data': { } }

##
# @EventResume
#
# Emitted when the virtual machine resumes execution
#
# Since: 1.8
##
{ 'type': 'EventResume',
   'data': { } }


##
# @EventSuspend
#
# Emitted when guest enters S3 state
#
# Since: 1.8
##
{ 'type': 'EventSuspend',
   'data': { } }

##
# @EventSuspendDisk
#
# Emitted when the guest makes a request to enter S4 state. Note QEMU shuts
# down (similar to @shutdown) when entering S4 state
#
# Since: 1.8
##
{ 'type': 'EventSuspendDisk',
   'data': { } }

##
# @EventWakeup
#
# Emitted when the guest has woken up from S3 and is running
#
# Since: 1.8
##
{ 'type': 'EventWakeup',
   'data': { } }


##
# @EventRtcChange
#
# Emitted when the guest changes the RTC time
#
# @offset: Offset between base RTC clock (as specified by -rtc base), and
#          new RTC clock value
#
# Since: 1.8
##
{ 'type': 'EventRtcChange',
   'data': {
       'data': {
           'offset': 'int'
       } } }

##
# @ActionTypeOnWatchdogExpired
#
# An enumeration of the actions taken when the watchdog device's timer is
# expired
#
# @reset: system resets
#
# @shutdown: system shutdown, note that it is similar to @powerdown, which
#            tries to set to system status and notify guest
#
# @poweroff: system poweroff, the emulator program exits
#
# @pause: system pauses, similar to @stop
#
# @pause: system enters debug state
#
# @none: nothing is done
#
# Since: 1.8
##
{ 'enum': 'ActionTypeOnWatchdogExpired',
   'data': [ 'reset', 'shutdown', 'poweroff', 'pause', 'debug', 'none' ] }

##
# @EventWatchdog
#
# Emitted when the watchdog device's timer is expired
#
# @action: Action that has been taken
#
# Since: 1.8
##
{ 'type': 'Watchdog',
   'data': {
       'data': {
           'action': 'ActionTypeOnWatchdogExpired'
       } } }

##
# @EventDeviceDeleted
#
# 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: #optional, device name
#
# @path: device path
#
# Since: 1.8
##
{ 'type': 'EventDeviceDeleted',
   'data': {
       'data': {
           '*device': 'str',
           'path'   : 'str'
       } } }

##
# @EventTrayMoved
#
# It's emitted whenever the tray of a removable device is moved by the guest
# or by HMP/QMP commands
#
# @device: device name
#
# @tray-open: true if the tray has been opened or false if it has been 
closed
#
# Since: 1.8
##
{ 'type': 'EventTrayMoved',
   'data': {
       'data': {
           'device'   : 'str',
           'tray-open': 'bool'
       } } }


##
# @IoOperationType
#
# An enumeration of the I/O operation types
#
# @read: read operation
#
# @write: write operation
#
# Since: 1.8
##
{ 'enum': 'IoOperationType',
   'data': [ 'read', 'write' ] }

##
# @BlockdevOnError:
#
# An enumeration of possible behaviors for errors on I/O operations.
# The exact meaning depends on whether the I/O was initiated by a guest
# or by a block job
#
# @report: for guest operations, report the error to the guest;
#          for jobs, cancel the job
#
# @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR
#          or BLOCK_JOB_ERROR)
#
# @enospc: same as @stop on ENOSPC, same as @report otherwise.
#
# @stop: for guest operations, stop the virtual machine;
#        for jobs, pause the job
#
# Since: 1.3
##
{ 'enum': 'BlockdevOnError',
   'data': ['report', 'ignore', 'enospc', 'stop'] }

##
# @BlockErrorInfo
#
# The error info for a block error
#
# @device: device name
#
# @operation: I/O operation
#
# @action: action that has been taken
#
# Since: 1.8
##
{ 'type': 'BlockErrorInfo',
   'data': { 'device': 'str', 'operation': 'IoOperationType',
             'action': 'BlockdevOnError' } }

##
# @EventBlockIoError
#
# Emitted when a disk I/O error occurs
#
# Since: 1.8
##
{ 'type': 'EventBlockIoError',
   'data': {
       'data': {
           '_base': 'BlockErrorInfo'
       } } }

##
# @EventBlockImageCorrupted
#
# Emitted when a disk image is being marked corrupt
#
# @device: Device name
#
# @msg: Informative message, for example, reason for the corruption
#
# @offset: If the corruption resulted from an image access, this is the 
access
#          offset into the image
# @size: If the corruption resulted from an image access, this is the access
#        size
#
# Since: 1.8
##
{ 'type': 'EventBlockImageCorrupted',
   'data': {
       'data': {
           'device': 'str',
           'msg'   : 'str',
           'offset': 'int',
           'size'  : 'int'
       } } }


##
# @BlockJobType:
#
# Type of a block job.
#
# @commit: block commit job type, see "block-commit"
#
# @stream: block stream job type, see "block-stream"
#
# @mirror: drive mirror job type, see "drive-mirror"
#
# @backup: drive backup job type, see "drive-backup"
#
# Since: 1.7
##
{ 'enum': 'BlockJobType',
   'data': ['commit', 'stream', 'mirror', 'backup'] }

##
# @BlockJobInfoBase
#
# Basic info of a block job
#
# @type: Job type
#
# @device: Device name
#
# @len: Maximum progress value
#
# @offset: Current progress value. On success this is equal to len.
#          On failure this is less than len
#
# @speed: Rate limit, bytes per second
#
# Since: 1.8
##
{ 'type': 'BlockJobInfoBase',
   'data': { 'type': 'BlockJobType', 'device': 'str', 'len': 'int',
             'offset': 'int', 'speed': 'int' } }

##
# @EventBlockJobCompleted
#
# Emitted when a block job has completed
#
# @error: #optional, error message. Only present on failure. This field
#         contains a human-readable error message. There are no semantics
#         other than that streaming has failed and clients should not try to
#         interpret the error string
#
# Since: 1.8
##
{ 'type': 'EventBlockJobCompleted',
   'data': {
       'data': {
           '_base' : 'BlockJobInfoBase',
           '*error': 'str'
       } } }

##
# @EventBlockJobCancelled
#
# Emitted when a block job has been cancelled
#
# @error: #optional, error message. Only present on failure. This field
#         contains a human-readable error message. There are no semantics
#         other than that streaming has failed and clients should not try to
#         interpret the error string
#
# Since: 1.8
##
{ 'type': 'EventBlockJobCancelled',
   'data': {
       'data': {
           '_base': 'BlockJobInfoBase'
       } } }

##
# @EventBlockJobError
#
# Emitted when a block job encounters an error
#
# Since: 1.8
##
{ 'type': 'EventBlockJobError',
   'data': {
       'data': {
           '_base': 'BlockErrorInfo'
       } } }

##
# @EventBlockJobReady
#
# Emitted when a block job is ready to complete
#
# @device: device name
#
# Since: 1.8
##
{ 'type': 'EventBlockJobReady',
   'data': {
       'data': {
           'device': 'str'
       } } }

##
# @EventNicRxFilterChanged
#
# The event is emitted once until the query command is executed, the first
# event will always be emitted
#
# @name: net client name
#
# @path: device path
#
# Since: 1.8
##
{ 'type': 'EventNicRxFilterChanged',
   'data': {
       'data': {
           'name': 'str',
           'path': 'str'
       } } }


##
# @NetworkConnectionInfo
#
# The information for network connection
#
# @host: IP address
#
# @service: port number
#
# @family: address family, "ipv4" or "ipv6"
#
# Since: 1.8
##
{ 'type': 'NetworkConnectionInfo',
   'data': { 'host': 'str', 'service': 'str', 'family': 'str' } }

##
# @EventVncConnected
#
# Emitted when a VNC client establishes a connection
#
# @server: Server information
#
#   @auth: #optional, authentication method
#
# @client: Client information
#
# Since: 1.8
##
{ 'type': 'EventVncConnected',
   'data': {
       'data': {
           'server': {
               '_base': 'NetworkConnectionInfo',
               '*auth': 'str' },
           'client': 'NetworkConnectionInfo'
       } } }

##
# @EventVncInitialized
#
# Emitted after authentication takes place (if any) and the VNC session is
# made active
#
# @server: Server information
#
#   @auth: #optional, authentication method
#
# @client: Client information
#
#   @x509_dname: #optional, TLS dname
#
#   @sasl_username: #optional, SASL username
#
# Since: 1.8
##
{ 'type': 'EventVncInitialized',
   'data': {
       'data': {
           'server': {
               '_base': 'NetworkConnectionInfo',
               '*auth': 'str' },
           'client': {
               '_base'         : 'NetworkConnectionInfo',
               '*x509_dname'   : 'str',
               '*sasl_username': 'str' }
       } } }

##
# @EventVncDisconnected
#
# Emitted when the connection is closed
#
# @server: Server information
#
#   @auth: #optional, authentication method
#
# @client: Client information
#
#   @x509_dname: #optional, TLS dname
#
#   @sasl_username: #optional, SASL username
#
# Since: 1.8
##
{ 'type': 'EventVncDisconnected',
   'data': {
       'data': {
           'server': {
               '_base': 'NetworkConnectionInfo',
               '*auth': 'str' },
           'client': {
               '_base'         : 'NetworkConnectionInfo',
               '*x509_dname'   : 'str',
               '*sasl_username': 'str' }
       } } }


##
# @EventSpiceConnected
#
# Emitted when a Spice client establishes a connection
#
# @server: Server information
#
# @client: Client information
#
# Since: 1.8
##
{ 'type': 'EventSpiceConnected',
   'data': {
       'data': {
           'server': 'NetworkConnectionInfo',
           'client': 'NetworkConnectionInfo'
       } } }

##
# @EventSpiceInitialized
#
# Emitted after initial handshake and authentication takes place (if any)
# and the SPICE channel is up'n'running
#
# @server: Server information
#
#   @auth: #optional, authentication method
#
# @client: Client information
#
#   @connection-id: spice connection id. All channels with the same id
#                   belong to the same spice session
#
#   @channel-type: channel type. "1" is the main control channel, filter for
#                  this one if you want track spice sessions only
#
#   @channel-id: channel id. Usually "0", might be different needed when
#                multiple channels of the same type exist, such as multiple
#                display channels in a multihead setup
#
#   @tls: whevener the channel is encrypted
#
# Since: 1.8
##
{ 'type': 'EventSpiceInitialized',
   'data': {
       'data': {
           'server': {
               '_base': 'NetworkConnectionInfo',
               '*auth': 'str' },
           'client': {
               '_base'        : 'NetworkConnectionInfo',
               'connection-id': 'int',
               'channel-type' : 'int',
               'channel-id'   : 'int',
               'tls'          : 'bool' }
       } } }

##
# @EventSpiceDisconnected
#
# Emitted when the spice connection is closed
#
# @server: Server information
#
# @client: Client information
#
# Since: 1.8
##
{ 'type': 'EventSpiceDisconnected',
   'data': {
       'data': {
           'server': 'NetworkConnectionInfo',
           'client': 'NetworkConnectionInfo'
       } } }

##
# @EventSpiceMigrateCompleted
#
# Emitted when spice migration has completed
#
# Since: 1.8
##
{ 'type': 'EventSpiceMigrateCompleted',
   'data': { } }


##
# @EventBalloonChange
#
# 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
#
# Since: 1.8
##
{ 'type': 'EventBalloonChange',
   'data': {
       'data': {
           'actual': 'int'
       } } }

##
# @EventGuestPanicked
#
# Emitted when guest OS panic is detected
#
# @action: Action that has been taken, currently always "pause"
#
# Since: 1.8
##
{ 'type': 'EventGuestPanicked',
   'data': {
       'data': {
           'action': 'str'
       } } }


##
# @Event
#
# Emitted when an event happens
#
# Since: 1.8
##
{ 'Union': 'Event',
   'base': 'EventBase',
   'discriminator': 'event',
   'data': {
       'SHUTDOWN'               : 'EventShutdown',
       'POWERDOWN'              : 'EventPowerdown',
       'RESET'                  : 'EventReset',
       'STOP'                   : 'EventStop',
       'RESUME'                 : 'EventResume',
       'SUSPEND'                : 'EventSuspend',
       'SUSPEND_DISK'           : 'EventSuspendDisk',
       'WAKEUP'                 : 'EventWakeup',

       'RTC_CHANGE'             : 'EventRtcChange',
       'WATCHDOG'               : 'EventWatchdog',
       'DEVICE_DELETED'         : 'EventDeviceDeleted',
       'DEVICE_TRAY_MOVED'      : 'EventDeviceTrayMoved',

       'BLOCK_IO_ERROR'         : 'EventBlockIoError',
       'BLOCK_IMAGE_CORRUPTED'  : 'EventBlockImageCorrupted',

       'BLOCK_JOB_COMPLETED'    : 'EventBlockJobCompleted',
       'BLOCK_JOB_CANCELLED'    : 'EventBlockJobCancelled',
       'BLOCK_JOB_ERROR'        : 'EventBlockJobError',
       'BLOCK_JOB_READY'        : 'EventBlockJobReady',

       'NIC_RX_FILTER_CHANGED'  : 'EventNicRxFilterChanged',

       'VNC_CONNECTED'          : 'EventVncConnected',
       'VNC_INITIALIZED'        : 'EventVncInitialized',
       'VNC_DISCONNECTED'       : 'EventVncDisconnected',

       'SPICE_CONNECTED'        : 'EventSpiceConnected',
       'SPICE_INITIALIZED'      : 'EventSpiceInitialized',
       'SPICE_DISCONNECTED'     : 'EventSpiceDisconnected',
       'SPICE_MIGRATE_COMPLETED': 'EventSpiceMigrateCompleted',

       'BALLOON_CHANGE'         : 'EventBalloonChange',
       'GUEST_PANICKED'         : 'EventGuestPanicked'
   } }