Patchwork [v4,1/2] qemu-ga: Add schema documentation for types

login
register
mail settings
Submitter Michael Roth
Date Jan. 17, 2012, 4:37 p.m.
Message ID <1326818263-21528-1-git-send-email-mdroth@linux.vnet.ibm.com>
Download mbox | patch
Permalink /patch/136500/
State New
Headers show

Comments

Michael Roth - Jan. 17, 2012, 4:37 p.m.
Document guest agent schema types in similar fashion as qmp schema
types.

Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
---
 qapi-schema-guest.json |  118 +++++++++++++++++++++++++++++++++++++++---------
 1 files changed, 97 insertions(+), 21 deletions(-)
Luiz Capitulino - Jan. 17, 2012, 5:03 p.m.
On Tue, 17 Jan 2012 10:37:42 -0600
Michael Roth <mdroth@linux.vnet.ibm.com> wrote:

> Document guest agent schema types in similar fashion as qmp schema
> types.
> 
> Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>

Reviewed-by: Luiz Capitulino <lcapitulino@redhat.com>

Btw Michael, you could apply this series and my guest-suspend one in a branch
and send a pull request to Anthony... But maybe it's better to wait until
tomorrow though, so that we give people more time to review.

> ---
>  qapi-schema-guest.json |  118 +++++++++++++++++++++++++++++++++++++++---------
>  1 files changed, 97 insertions(+), 21 deletions(-)
> 
> diff --git a/qapi-schema-guest.json b/qapi-schema-guest.json
> index 5f8a18d..706925d 100644
> --- a/qapi-schema-guest.json
> +++ b/qapi-schema-guest.json
> @@ -37,17 +37,42 @@
>  { 'command': 'guest-ping' }
>  
>  ##
> -# @guest-info:
> +# @GuestAgentCommandInfo:
>  #
> -# Get some information about the guest agent.
> +# Information about guest agent commands.
>  #
> -# Since: 0.15.0
> +# @name: name of the command
> +#
> +# @enabled: whether command is currently enabled by guest admin
> +#
> +# Since 1.1.0
>  ##
>  { 'type': 'GuestAgentCommandInfo',
>    'data': { 'name': 'str', 'enabled': 'bool' } }
> +
> +##
> +# @GuestAgentInfo
> +#
> +# Information about guest agent.
> +#
> +# @version: guest agent version
> +#
> +# @supported_commands: Information about guest agent commands
> +#
> +# Since 0.15.0
> +##
>  { 'type': 'GuestAgentInfo',
>    'data': { 'version': 'str',
>              'supported_commands': ['GuestAgentCommandInfo'] } }
> +##
> +# @guest-info:
> +#
> +# Get some information about the guest agent.
> +#
> +# Returns: @GuestAgentInfo
> +#
> +# Since: 0.15.0
> +##
>  { 'command': 'guest-info',
>    'returns': 'GuestAgentInfo' }
>  
> @@ -98,6 +123,23 @@
>    'data': { 'handle': 'int' } }
>  
>  ##
> +# @GuestFileRead
> +#
> +# Result of guest agent file-read operation
> +#
> +# @count: number of bytes read (note: count is *before*
> +#         base64-encoding is applied)
> +#
> +# @buf-b64: base64-encoded bytes read
> +#
> +# @eof: whether EOF was encountered during read operation.
> +#
> +# Since: 0.15.0
> +##
> +{ 'type': 'GuestFileRead',
> +  'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
> +
> +##
>  # @guest-file-read:
>  #
>  # Read from an open file in the guest. Data will be base64-encoded
> @@ -106,19 +148,30 @@
>  #
>  # @count: #optional maximum number of bytes to read (default is 4KB)
>  #
> -# Returns: GuestFileRead on success. Note: count is number of bytes read
> -#          *before* base64 encoding bytes read.
> +# Returns: @GuestFileRead on success.
>  #
>  # Since: 0.15.0
>  ##
> -{ 'type': 'GuestFileRead',
> -  'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
> -
>  { 'command': 'guest-file-read',
>    'data':    { 'handle': 'int', '*count': 'int' },
>    'returns': 'GuestFileRead' }
>  
>  ##
> +# @GuestFileWrite
> +#
> +# Result of guest agent file-write operation
> +#
> +# @count: number of bytes written (note: count is actual bytes
> +#         written, after base64-decoding of provided buffer)
> +#
> +# @eof: whether EOF was encountered during write operation.
> +#
> +# Since: 0.15.0
> +##
> +{ 'type': 'GuestFileWrite',
> +  'data': { 'count': 'int', 'eof': 'bool' } }
> +
> +##
>  # @guest-file-write:
>  #
>  # Write to an open file in the guest.
> @@ -130,17 +183,29 @@
>  # @count: #optional bytes to write (actual bytes, after base64-decode),
>  #         default is all content in buf-b64 buffer after base64 decoding
>  #
> -# Returns: GuestFileWrite on success. Note: count is the number of bytes
> -#          base64-decoded bytes written
> +# Returns: @GuestFileWrite on success.
>  #
>  # Since: 0.15.0
>  ##
> -{ 'type': 'GuestFileWrite',
> -  'data': { 'count': 'int', 'eof': 'bool' } }
>  { 'command': 'guest-file-write',
>    'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
>    'returns': 'GuestFileWrite' }
>  
> +
> +##
> +# @GuestFileSeek
> +#
> +# Result of guest agent file-seek operation
> +#
> +# @position: current file position
> +#
> +# @eof: whether EOF was encountered during file seek
> +#
> +# Since: 0.15.0
> +##
> +{ 'type': 'GuestFileSeek',
> +  'data': { 'position': 'int', 'eof': 'bool' } }
> +
>  ##
>  # @guest-file-seek:
>  #
> @@ -154,13 +219,10 @@
>  #
>  # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
>  #
> -# Returns: GuestFileSeek on success.
> +# Returns: @GuestFileSeek on success.
>  #
>  # Since: 0.15.0
>  ##
> -{ 'type': 'GuestFileSeek',
> -  'data': { 'position': 'int', 'eof': 'bool' } }
> -
>  { 'command': 'guest-file-seek',
>    'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
>    'returns': 'GuestFileSeek' }
> @@ -180,18 +242,32 @@
>    'data': { 'handle': 'int' } }
>  
>  ##
> -# @guest-fsfreeze-status:
> +# @GuestFsFreezeStatus
>  #
> -# Get guest fsfreeze state. error state indicates failure to thaw 1 or more
> -# previously frozen filesystems, or failure to open a previously cached
> -# filesytem (filesystem unmounted/directory changes, etc).
> +# An enumation of filesystem freeze states
>  #
> -# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
> +# @thawed: filesystems thawed/unfrozen
> +#
> +# @frozen: all non-network guest filesystems frozen
> +#
> +# @error: failure to thaw 1 or more
> +#         previously frozen filesystems, or failure to open a previously
> +#         cached filesytem (filesystem unmounted/directory changes, etc).
>  #
>  # Since: 0.15.0
>  ##
>  { 'enum': 'GuestFsfreezeStatus',
>    'data': [ 'thawed', 'frozen', 'error' ] }
> +
> +##
> +# @guest-fsfreeze-status:
> +#
> +# Get guest fsfreeze state. error state indicates
> +#
> +# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
> +#
> +# Since: 0.15.0
> +##
>  { 'command': 'guest-fsfreeze-status',
>    'returns': 'GuestFsfreezeStatus' }
>

Patch

diff --git a/qapi-schema-guest.json b/qapi-schema-guest.json
index 5f8a18d..706925d 100644
--- a/qapi-schema-guest.json
+++ b/qapi-schema-guest.json
@@ -37,17 +37,42 @@ 
 { 'command': 'guest-ping' }
 
 ##
-# @guest-info:
+# @GuestAgentCommandInfo:
 #
-# Get some information about the guest agent.
+# Information about guest agent commands.
 #
-# Since: 0.15.0
+# @name: name of the command
+#
+# @enabled: whether command is currently enabled by guest admin
+#
+# Since 1.1.0
 ##
 { 'type': 'GuestAgentCommandInfo',
   'data': { 'name': 'str', 'enabled': 'bool' } }
+
+##
+# @GuestAgentInfo
+#
+# Information about guest agent.
+#
+# @version: guest agent version
+#
+# @supported_commands: Information about guest agent commands
+#
+# Since 0.15.0
+##
 { 'type': 'GuestAgentInfo',
   'data': { 'version': 'str',
             'supported_commands': ['GuestAgentCommandInfo'] } }
+##
+# @guest-info:
+#
+# Get some information about the guest agent.
+#
+# Returns: @GuestAgentInfo
+#
+# Since: 0.15.0
+##
 { 'command': 'guest-info',
   'returns': 'GuestAgentInfo' }
 
@@ -98,6 +123,23 @@ 
   'data': { 'handle': 'int' } }
 
 ##
+# @GuestFileRead
+#
+# Result of guest agent file-read operation
+#
+# @count: number of bytes read (note: count is *before*
+#         base64-encoding is applied)
+#
+# @buf-b64: base64-encoded bytes read
+#
+# @eof: whether EOF was encountered during read operation.
+#
+# Since: 0.15.0
+##
+{ 'type': 'GuestFileRead',
+  'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
+
+##
 # @guest-file-read:
 #
 # Read from an open file in the guest. Data will be base64-encoded
@@ -106,19 +148,30 @@ 
 #
 # @count: #optional maximum number of bytes to read (default is 4KB)
 #
-# Returns: GuestFileRead on success. Note: count is number of bytes read
-#          *before* base64 encoding bytes read.
+# Returns: @GuestFileRead on success.
 #
 # Since: 0.15.0
 ##
-{ 'type': 'GuestFileRead',
-  'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
-
 { 'command': 'guest-file-read',
   'data':    { 'handle': 'int', '*count': 'int' },
   'returns': 'GuestFileRead' }
 
 ##
+# @GuestFileWrite
+#
+# Result of guest agent file-write operation
+#
+# @count: number of bytes written (note: count is actual bytes
+#         written, after base64-decoding of provided buffer)
+#
+# @eof: whether EOF was encountered during write operation.
+#
+# Since: 0.15.0
+##
+{ 'type': 'GuestFileWrite',
+  'data': { 'count': 'int', 'eof': 'bool' } }
+
+##
 # @guest-file-write:
 #
 # Write to an open file in the guest.
@@ -130,17 +183,29 @@ 
 # @count: #optional bytes to write (actual bytes, after base64-decode),
 #         default is all content in buf-b64 buffer after base64 decoding
 #
-# Returns: GuestFileWrite on success. Note: count is the number of bytes
-#          base64-decoded bytes written
+# Returns: @GuestFileWrite on success.
 #
 # Since: 0.15.0
 ##
-{ 'type': 'GuestFileWrite',
-  'data': { 'count': 'int', 'eof': 'bool' } }
 { 'command': 'guest-file-write',
   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
   'returns': 'GuestFileWrite' }
 
+
+##
+# @GuestFileSeek
+#
+# Result of guest agent file-seek operation
+#
+# @position: current file position
+#
+# @eof: whether EOF was encountered during file seek
+#
+# Since: 0.15.0
+##
+{ 'type': 'GuestFileSeek',
+  'data': { 'position': 'int', 'eof': 'bool' } }
+
 ##
 # @guest-file-seek:
 #
@@ -154,13 +219,10 @@ 
 #
 # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
 #
-# Returns: GuestFileSeek on success.
+# Returns: @GuestFileSeek on success.
 #
 # Since: 0.15.0
 ##
-{ 'type': 'GuestFileSeek',
-  'data': { 'position': 'int', 'eof': 'bool' } }
-
 { 'command': 'guest-file-seek',
   'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
   'returns': 'GuestFileSeek' }
@@ -180,18 +242,32 @@ 
   'data': { 'handle': 'int' } }
 
 ##
-# @guest-fsfreeze-status:
+# @GuestFsFreezeStatus
 #
-# Get guest fsfreeze state. error state indicates failure to thaw 1 or more
-# previously frozen filesystems, or failure to open a previously cached
-# filesytem (filesystem unmounted/directory changes, etc).
+# An enumation of filesystem freeze states
 #
-# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
+# @thawed: filesystems thawed/unfrozen
+#
+# @frozen: all non-network guest filesystems frozen
+#
+# @error: failure to thaw 1 or more
+#         previously frozen filesystems, or failure to open a previously
+#         cached filesytem (filesystem unmounted/directory changes, etc).
 #
 # Since: 0.15.0
 ##
 { 'enum': 'GuestFsfreezeStatus',
   'data': [ 'thawed', 'frozen', 'error' ] }
+
+##
+# @guest-fsfreeze-status:
+#
+# Get guest fsfreeze state. error state indicates
+#
+# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
+#
+# Since: 0.15.0
+##
 { 'command': 'guest-fsfreeze-status',
   'returns': 'GuestFsfreezeStatus' }