Patchwork [v6,3/4] guest agent: add guest agent commands schema file

login
register
mail settings
Submitter Michael Roth
Date July 5, 2011, 1:21 p.m.
Message ID <1309872100-27912-4-git-send-email-mdroth@linux.vnet.ibm.com>
Download mbox | patch
Permalink /patch/103311/
State New
Headers show

Comments

Michael Roth - July 5, 2011, 1:21 p.m.
Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
---
 qapi-schema-guest.json |  204 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 204 insertions(+), 0 deletions(-)
 create mode 100644 qapi-schema-guest.json
Luiz Capitulino - July 8, 2011, 3:08 p.m.
On Tue,  5 Jul 2011 08:21:39 -0500
Michael Roth <mdroth@linux.vnet.ibm.com> wrote:

> 
> Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
> ---
>  qapi-schema-guest.json |  204 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 204 insertions(+), 0 deletions(-)
>  create mode 100644 qapi-schema-guest.json

I think this should be folded in the next patch.

More comments below.

> 
> diff --git a/qapi-schema-guest.json b/qapi-schema-guest.json
> new file mode 100644
> index 0000000..367b42d
> --- /dev/null
> +++ b/qapi-schema-guest.json
> @@ -0,0 +1,204 @@
> +# *-*- Mode: Python -*-*
> +
> +##
> +# @guest-sync:
> +#
> +# Echo back a unique integer value
> +#
> +# This is used by clients talking to the guest agent over the
> +# wire to ensure the stream is in sync and doesn't contain stale
> +# data from previous client. All guest agent responses should be
> +# ignored until the provided unique integer value is returned,
> +# and it is up to the client to handle stale whole or
> +# partially-delivered JSON text in such a way that this response
> +# can be obtained.
> +#
> +# Such clients should also preceed this command
> +# with a 0xFF byte to make such the guest agent flushes any
> +# partially read JSON data from a previous session.
> +#
> +# @id: randomly generated 64-bit integer
> +#
> +# Returns: The unique integer id passed in by the client
> +#
> +# Since: 0.15.0
> +##
> +{ 'command': 'guest-sync'
> +  'data':    { 'id': 'int' },
> +  'returns': 'int' }
> +
> +##
> +# @guest-ping:
> +#
> +# Ping the guest agent, a non-error return implies success
> +#
> +# Since: 0.15.0
> +##
> +{ 'command': 'guest-ping' }
> +
> +##
> +# @guest-info:
> +#
> +# Get some information about the guest agent.
> +#
> +# Since: 0.15.0
> +##
> +{ 'type': 'GuestAgentInfo', 'data': {'version': 'str'} }
> +{ 'command': 'guest-info',
> +  'returns': 'GuestAgentInfo' }
> +
> +##
> +# @guest-shutdown:
> +#
> +# Initiate guest-activated shutdown. Note: this is an asynchronous
> +# shutdown request, with no guaruntee of successful shutdown. Errors
> +# will be logged to guest's syslog.
> +#
> +# @mode: "halt", "powerdown", or "reboot"
> +#
> +# Returns: Nothing on success
> +#
> +# Since: 0.15.0
> +##
> +{ 'command': 'guest-shutdown', 'data': { 'mode': 'str' } }

Shouldn't 'mode' be optional?

> +
> +##
> +# @guest-file-open:
> +#
> +# Open a file in the guest and retrieve a file handle for it
> +#
> +# @filepath: Full path to the file in the guest to open.
> +#
> +# @mode: #optional open mode, as per fopen(), "r" is the default.
> +#
> +# Returns: Guest file handle on success.
> +#          If @filepath cannot be opened, OpenFileFailed
> +#
> +# Since: 0.15.0
> +##
> +{ 'command': 'guest-file-open',
> +  'data':    { 'filepath': 'str', '*mode': 'str' },
> +  'returns': 'int' }

You can use 'file-path'. Actually, I'd use just 'path'.

> +
> +##
> +# @guest-file-read:
> +#
> +# Read from an open file in the guest
> +#
> +# @filehandle: filehandle returned by guest-file-open
> +#
> +# @count: maximum number of bytes to read
> +#
> +# Returns: GuestFileRead on success.
> +#          If @filehandle is not open, OpenFileFailed
> +#
> +# Since: 0.15.0
> +##
> +{ 'type': 'GuestFileRead',
> +  'data': { 'count': 'int', 'buf': 'str', 'eof': 'bool' } }
> +
> +{ 'command': 'guest-file-read',
> +  'data':    { 'filehandle': 'int', 'count': 'int' },
> +  'returns': 'GuestFileRead' }

file-handle. Also, we have to say that the returned data is base64-encoded.

> +
> +##
> +# @guest-file-write:
> +#
> +# Write to an open file in the guest
> +#
> +# @filehandle: filehandle returned by guest-file-open
> +#
> +# @data_b64: base64-encoded string representing data to be written
> +#
> +# @count: bytes to write (actual bytes, after b64-decode)
> +#
> +# Returns: GuestFileWrite on success.
> +#          If @filehandle is not opened, OpenFileFailed
> +#
> +# Since: 0.15.0
> +##
> +{ 'type': 'GuestFileWrite',
> +  'data': { 'count': 'int', 'eof': 'bool' } }
> +{ 'command': 'guest-file-write',
> +  'data':    { 'filehandle': 'int', 'data_b64': 'str', 'count': 'int' },
> +  'returns': 'GuestFileWrite' }

data-b64

> +
> +##
> +# @guest-file-seek:
> +#
> +# Seek to a position in the file, as with fseek(), and return the
> +# current file position afterward. Also encapsulates ftell()'s
> +# functionality, just Set offset=0, whence=SEEK_CUR.
> +#
> +# @filehandle: filehandle returned by guest-file-open
> +#
> +# @offset: bytes to skip over in the file stream
> +#
> +# @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
> +#
> +# Returns: GuestFileSeek on success.
> +#          If @filehandle is not opened, OpenFileFailed
> +#
> +# Since: 0.15.0
> +##
> +{ 'type': 'GuestFileSeek',
> +  'data': { 'position': 'int', 'eof': 'bool' } }
> +
> +{ 'command': 'guest-file-seek',
> +  'data':    { 'filehandle': 'int', 'offset': 'int', 'whence': 'int' },
> +  'returns': 'GuestFileSeek' }
> +
> +##
> +# @guest-file-close:
> +#
> +# Close an open file in the guest
> +#
> +# @filehandle: filehandle returned by guest-file-open
> +#
> +# Returns: Nothing on success.
> +#          If @filehandle is not opened, OpenFileFailed
> +#
> +# Since: 0.15.0
> +##
> +{ 'command': 'guest-file-close',
> +  'data': { 'filehandle': 'int' } }
> +
> +##
> +# @guest-fsfreeze-status:
> +#
> +# get guest fsfreeze state
> +#
> +# Returns: GuestFsfreezeStatus (enumeration starts at 1)
> +#
> +# Since: 0.15.0
> +##
> +{ 'enum': 'GuestFsfreezeStatus',
> +  'data': [ 'thawed', 'inprogress', 'frozen', 'error' ] }
> +{ 'command': 'guest-fsfreeze-status',
> +  'returns': 'GuestFsfreezeStatus' }

hmm, I thought a qapi command implementation would return an enum (ie. int),
but the qapi would translate it to a string and return the string to the
client. However, this returns an int (as explained above).

Did I misunderstand how the qapi handles enums then?

> +
> +##
> +# @guest-fsfreeze-freeze:
> +#
> +# Sync and freeze all non-network guest filesystems
> +#
> +# Returns: Number of file systems frozen
> +#          If error, -1 (unknown error) or -errno
> +#
> +# Since: 0.15.0
> +##
> +{ 'command': 'guest-fsfreeze-freeze',
> +  'returns': 'int' }
> +
> +##
> +# @guest-fsfreeze-thaw:
> +#
> +# Unfreeze frozen guest fileystems
> +#
> +# Returns: Number of file systems thawed
> +#          If error, -1 (unknown error) or -errno
> +#
> +# Since: 0.15.0
> +##
> +{ 'command': 'guest-fsfreeze-thaw',
> +  'returns': 'int' }
Michael Roth - July 8, 2011, 9:42 p.m.
On 07/08/2011 10:08 AM, Luiz Capitulino wrote:
> On Tue,  5 Jul 2011 08:21:39 -0500
> Michael Roth<mdroth@linux.vnet.ibm.com>  wrote:
>
>>
>> Signed-off-by: Michael Roth<mdroth@linux.vnet.ibm.com>
>> ---
>>   qapi-schema-guest.json |  204 ++++++++++++++++++++++++++++++++++++++++++++++++
>>   1 files changed, 204 insertions(+), 0 deletions(-)
>>   create mode 100644 qapi-schema-guest.json
>
> I think this should be folded in the next patch.
>
> More comments below.
>
>>
>> diff --git a/qapi-schema-guest.json b/qapi-schema-guest.json
>> new file mode 100644
>> index 0000000..367b42d
>> --- /dev/null
>> +++ b/qapi-schema-guest.json
>> @@ -0,0 +1,204 @@
>> +# *-*- Mode: Python -*-*
>> +
>> +##
>> +# @guest-sync:
>> +#
>> +# Echo back a unique integer value
>> +#
>> +# This is used by clients talking to the guest agent over the
>> +# wire to ensure the stream is in sync and doesn't contain stale
>> +# data from previous client. All guest agent responses should be
>> +# ignored until the provided unique integer value is returned,
>> +# and it is up to the client to handle stale whole or
>> +# partially-delivered JSON text in such a way that this response
>> +# can be obtained.
>> +#
>> +# Such clients should also preceed this command
>> +# with a 0xFF byte to make such the guest agent flushes any
>> +# partially read JSON data from a previous session.
>> +#
>> +# @id: randomly generated 64-bit integer
>> +#
>> +# Returns: The unique integer id passed in by the client
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'command': 'guest-sync'
>> +  'data':    { 'id': 'int' },
>> +  'returns': 'int' }
>> +
>> +##
>> +# @guest-ping:
>> +#
>> +# Ping the guest agent, a non-error return implies success
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'command': 'guest-ping' }
>> +
>> +##
>> +# @guest-info:
>> +#
>> +# Get some information about the guest agent.
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'type': 'GuestAgentInfo', 'data': {'version': 'str'} }
>> +{ 'command': 'guest-info',
>> +  'returns': 'GuestAgentInfo' }
>> +
>> +##
>> +# @guest-shutdown:
>> +#
>> +# Initiate guest-activated shutdown. Note: this is an asynchronous
>> +# shutdown request, with no guaruntee of successful shutdown. Errors
>> +# will be logged to guest's syslog.
>> +#
>> +# @mode: "halt", "powerdown", or "reboot"
>> +#
>> +# Returns: Nothing on success
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'command': 'guest-shutdown', 'data': { 'mode': 'str' } }
>
> Shouldn't 'mode' be optional?
>
>> +
>> +##
>> +# @guest-file-open:
>> +#
>> +# Open a file in the guest and retrieve a file handle for it
>> +#
>> +# @filepath: Full path to the file in the guest to open.
>> +#
>> +# @mode: #optional open mode, as per fopen(), "r" is the default.
>> +#
>> +# Returns: Guest file handle on success.
>> +#          If @filepath cannot be opened, OpenFileFailed
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'command': 'guest-file-open',
>> +  'data':    { 'filepath': 'str', '*mode': 'str' },
>> +  'returns': 'int' }
>
> You can use 'file-path'. Actually, I'd use just 'path'.
>
>> +
>> +##
>> +# @guest-file-read:
>> +#
>> +# Read from an open file in the guest
>> +#
>> +# @filehandle: filehandle returned by guest-file-open
>> +#
>> +# @count: maximum number of bytes to read
>> +#
>> +# Returns: GuestFileRead on success.
>> +#          If @filehandle is not open, OpenFileFailed
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'type': 'GuestFileRead',
>> +  'data': { 'count': 'int', 'buf': 'str', 'eof': 'bool' } }
>> +
>> +{ 'command': 'guest-file-read',
>> +  'data':    { 'filehandle': 'int', 'count': 'int' },
>> +  'returns': 'GuestFileRead' }
>
> file-handle. Also, we have to say that the returned data is base64-encoded.
>
>> +
>> +##
>> +# @guest-file-write:
>> +#
>> +# Write to an open file in the guest
>> +#
>> +# @filehandle: filehandle returned by guest-file-open
>> +#
>> +# @data_b64: base64-encoded string representing data to be written
>> +#
>> +# @count: bytes to write (actual bytes, after b64-decode)
>> +#
>> +# Returns: GuestFileWrite on success.
>> +#          If @filehandle is not opened, OpenFileFailed
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'type': 'GuestFileWrite',
>> +  'data': { 'count': 'int', 'eof': 'bool' } }
>> +{ 'command': 'guest-file-write',
>> +  'data':    { 'filehandle': 'int', 'data_b64': 'str', 'count': 'int' },
>> +  'returns': 'GuestFileWrite' }
>
> data-b64
>
>> +
>> +##
>> +# @guest-file-seek:
>> +#
>> +# Seek to a position in the file, as with fseek(), and return the
>> +# current file position afterward. Also encapsulates ftell()'s
>> +# functionality, just Set offset=0, whence=SEEK_CUR.
>> +#
>> +# @filehandle: filehandle returned by guest-file-open
>> +#
>> +# @offset: bytes to skip over in the file stream
>> +#
>> +# @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
>> +#
>> +# Returns: GuestFileSeek on success.
>> +#          If @filehandle is not opened, OpenFileFailed
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'type': 'GuestFileSeek',
>> +  'data': { 'position': 'int', 'eof': 'bool' } }
>> +
>> +{ 'command': 'guest-file-seek',
>> +  'data':    { 'filehandle': 'int', 'offset': 'int', 'whence': 'int' },
>> +  'returns': 'GuestFileSeek' }
>> +
>> +##
>> +# @guest-file-close:
>> +#
>> +# Close an open file in the guest
>> +#
>> +# @filehandle: filehandle returned by guest-file-open
>> +#
>> +# Returns: Nothing on success.
>> +#          If @filehandle is not opened, OpenFileFailed
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'command': 'guest-file-close',
>> +  'data': { 'filehandle': 'int' } }
>> +
>> +##
>> +# @guest-fsfreeze-status:
>> +#
>> +# get guest fsfreeze state
>> +#
>> +# Returns: GuestFsfreezeStatus (enumeration starts at 1)
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'enum': 'GuestFsfreezeStatus',
>> +  'data': [ 'thawed', 'inprogress', 'frozen', 'error' ] }
>> +{ 'command': 'guest-fsfreeze-status',
>> +  'returns': 'GuestFsfreezeStatus' }
>
> hmm, I thought a qapi command implementation would return an enum (ie. int),
> but the qapi would translate it to a string and return the string to the
> client. However, this returns an int (as explained above).
>
> Did I misunderstand how the qapi handles enums then?
>

No, I think you're right... the original code generation seemed to 
support this at least. With the switchover to visitor functions Anthony 
treated enum types as integers when handling input/output, but now that 
I look at it again there was a commented-out block that suggested a 
possible TODO here.

It could be done by generating a lookup table for each qapi-defined enum 
and then passing that to qmp_input_type_enum()/qapi_output_type_enum()

Sure would make the enum functionality more useful :) I'll see if I can 
work it into set2 without too much churn.

>> +
>> +##
>> +# @guest-fsfreeze-freeze:
>> +#
>> +# Sync and freeze all non-network guest filesystems
>> +#
>> +# Returns: Number of file systems frozen
>> +#          If error, -1 (unknown error) or -errno
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'command': 'guest-fsfreeze-freeze',
>> +  'returns': 'int' }
>> +
>> +##
>> +# @guest-fsfreeze-thaw:
>> +#
>> +# Unfreeze frozen guest fileystems
>> +#
>> +# Returns: Number of file systems thawed
>> +#          If error, -1 (unknown error) or -errno
>> +#
>> +# Since: 0.15.0
>> +##
>> +{ 'command': 'guest-fsfreeze-thaw',
>> +  'returns': 'int' }
>

Patch

diff --git a/qapi-schema-guest.json b/qapi-schema-guest.json
new file mode 100644
index 0000000..367b42d
--- /dev/null
+++ b/qapi-schema-guest.json
@@ -0,0 +1,204 @@ 
+# *-*- Mode: Python -*-*
+
+##
+# @guest-sync:
+#
+# Echo back a unique integer value
+#
+# This is used by clients talking to the guest agent over the
+# wire to ensure the stream is in sync and doesn't contain stale
+# data from previous client. All guest agent responses should be
+# ignored until the provided unique integer value is returned,
+# and it is up to the client to handle stale whole or
+# partially-delivered JSON text in such a way that this response
+# can be obtained.
+#
+# Such clients should also preceed this command
+# with a 0xFF byte to make such the guest agent flushes any
+# partially read JSON data from a previous session.
+#
+# @id: randomly generated 64-bit integer
+#
+# Returns: The unique integer id passed in by the client
+#
+# Since: 0.15.0
+##
+{ 'command': 'guest-sync'
+  'data':    { 'id': 'int' },
+  'returns': 'int' }
+
+##
+# @guest-ping:
+#
+# Ping the guest agent, a non-error return implies success
+#
+# Since: 0.15.0
+##
+{ 'command': 'guest-ping' }
+
+##
+# @guest-info:
+#
+# Get some information about the guest agent.
+#
+# Since: 0.15.0
+##
+{ 'type': 'GuestAgentInfo', 'data': {'version': 'str'} }
+{ 'command': 'guest-info',
+  'returns': 'GuestAgentInfo' }
+
+##
+# @guest-shutdown:
+#
+# Initiate guest-activated shutdown. Note: this is an asynchronous
+# shutdown request, with no guaruntee of successful shutdown. Errors
+# will be logged to guest's syslog.
+#
+# @mode: "halt", "powerdown", or "reboot"
+#
+# Returns: Nothing on success
+#
+# Since: 0.15.0
+##
+{ 'command': 'guest-shutdown', 'data': { 'mode': 'str' } }
+
+##
+# @guest-file-open:
+#
+# Open a file in the guest and retrieve a file handle for it
+#
+# @filepath: Full path to the file in the guest to open.
+#
+# @mode: #optional open mode, as per fopen(), "r" is the default.
+#
+# Returns: Guest file handle on success.
+#          If @filepath cannot be opened, OpenFileFailed
+#
+# Since: 0.15.0
+##
+{ 'command': 'guest-file-open',
+  'data':    { 'filepath': 'str', '*mode': 'str' },
+  'returns': 'int' }
+
+##
+# @guest-file-read:
+#
+# Read from an open file in the guest
+#
+# @filehandle: filehandle returned by guest-file-open
+#
+# @count: maximum number of bytes to read
+#
+# Returns: GuestFileRead on success.
+#          If @filehandle is not open, OpenFileFailed
+#
+# Since: 0.15.0
+##
+{ 'type': 'GuestFileRead',
+  'data': { 'count': 'int', 'buf': 'str', 'eof': 'bool' } }
+
+{ 'command': 'guest-file-read',
+  'data':    { 'filehandle': 'int', 'count': 'int' },
+  'returns': 'GuestFileRead' }
+
+##
+# @guest-file-write:
+#
+# Write to an open file in the guest
+#
+# @filehandle: filehandle returned by guest-file-open
+#
+# @data_b64: base64-encoded string representing data to be written
+#
+# @count: bytes to write (actual bytes, after b64-decode)
+#
+# Returns: GuestFileWrite on success.
+#          If @filehandle is not opened, OpenFileFailed
+#
+# Since: 0.15.0
+##
+{ 'type': 'GuestFileWrite',
+  'data': { 'count': 'int', 'eof': 'bool' } }
+{ 'command': 'guest-file-write',
+  'data':    { 'filehandle': 'int', 'data_b64': 'str', 'count': 'int' },
+  'returns': 'GuestFileWrite' }
+
+##
+# @guest-file-seek:
+#
+# Seek to a position in the file, as with fseek(), and return the
+# current file position afterward. Also encapsulates ftell()'s
+# functionality, just Set offset=0, whence=SEEK_CUR.
+#
+# @filehandle: filehandle returned by guest-file-open
+#
+# @offset: bytes to skip over in the file stream
+#
+# @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
+#
+# Returns: GuestFileSeek on success.
+#          If @filehandle is not opened, OpenFileFailed
+#
+# Since: 0.15.0
+##
+{ 'type': 'GuestFileSeek',
+  'data': { 'position': 'int', 'eof': 'bool' } }
+
+{ 'command': 'guest-file-seek',
+  'data':    { 'filehandle': 'int', 'offset': 'int', 'whence': 'int' },
+  'returns': 'GuestFileSeek' }
+
+##
+# @guest-file-close:
+#
+# Close an open file in the guest
+#
+# @filehandle: filehandle returned by guest-file-open
+#
+# Returns: Nothing on success.
+#          If @filehandle is not opened, OpenFileFailed
+#
+# Since: 0.15.0
+##
+{ 'command': 'guest-file-close',
+  'data': { 'filehandle': 'int' } }
+
+##
+# @guest-fsfreeze-status:
+#
+# get guest fsfreeze state
+#
+# Returns: GuestFsfreezeStatus (enumeration starts at 1)
+#
+# Since: 0.15.0
+##
+{ 'enum': 'GuestFsfreezeStatus',
+  'data': [ 'thawed', 'inprogress', 'frozen', 'error' ] }
+{ 'command': 'guest-fsfreeze-status',
+  'returns': 'GuestFsfreezeStatus' }
+
+##
+# @guest-fsfreeze-freeze:
+#
+# Sync and freeze all non-network guest filesystems
+#
+# Returns: Number of file systems frozen
+#          If error, -1 (unknown error) or -errno
+#
+# Since: 0.15.0
+##
+{ 'command': 'guest-fsfreeze-freeze',
+  'returns': 'int' }
+
+##
+# @guest-fsfreeze-thaw:
+#
+# Unfreeze frozen guest fileystems
+#
+# Returns: Number of file systems thawed
+#          If error, -1 (unknown error) or -errno
+#
+# Since: 0.15.0
+##
+{ 'command': 'guest-fsfreeze-thaw',
+  'returns': 'int' }