From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42020) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VYtwm-0006aN-9c for qemu-devel@nongnu.org; Wed, 23 Oct 2013 04:37:53 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VYtwd-0001Q6-6v for qemu-devel@nongnu.org; Wed, 23 Oct 2013 04:37:44 -0400 Received: from e28smtp08.in.ibm.com ([122.248.162.8]:37369) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VYtwc-0001Pt-9o for qemu-devel@nongnu.org; Wed, 23 Oct 2013 04:37:35 -0400 Received: from /spool/local by e28smtp08.in.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Wed, 23 Oct 2013 14:07:24 +0530 Received: from d28relay02.in.ibm.com (d28relay02.in.ibm.com [9.184.220.59]) by d28dlp03.in.ibm.com (Postfix) with ESMTP id 45C5C1258051 for ; Wed, 23 Oct 2013 14:07:55 +0530 (IST) Received: from d28av02.in.ibm.com (d28av02.in.ibm.com [9.184.220.64]) by d28relay02.in.ibm.com (8.13.8/8.13.8/NCO v10.0) with ESMTP id r9N8eHGo38928602 for ; Wed, 23 Oct 2013 14:10:18 +0530 Received: from d28av02.in.ibm.com (localhost [127.0.0.1]) by d28av02.in.ibm.com (8.14.4/8.14.4/NCO v10.0 AVout) with ESMTP id r9N8bKYJ027155 for ; Wed, 23 Oct 2013 14:07:20 +0530 Message-ID: <52671A3D.6030908@linux.vnet.ibm.com> Date: Wed, 23 Oct 2013 08:37:17 +0800 From: Wenchao Xia MIME-Version: 1.0 References: <1382321765-29052-1-git-send-email-xiawenc@linux.vnet.ibm.com> <1382321765-29052-7-git-send-email-xiawenc@linux.vnet.ibm.com> <526595ED.5090506@redhat.com> <5265EEDC.3080900@linux.vnet.ibm.com> <5265F506.7010603@redhat.com> In-Reply-To: <5265F506.7010603@redhat.com> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit Subject: Re: [Qemu-devel] [PATCH 6/6] qapi: add doc for QEvent List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Eric Blake Cc: kwolf@redhat.com, armbru@redhat.com, qemu-devel@nongnu.org, lcapitulino@redhat.com, stefanha@redhat.com, pbonzini@redhat.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' } }