Message ID | 1309872100-27912-4-git-send-email-mdroth@linux.vnet.ibm.com |
---|---|
State | New |
Headers | show |
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' }
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' } >
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' }
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