From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([140.186.70.92]:35851) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QfIoj-0001AK-H3 for qemu-devel@nongnu.org; Fri, 08 Jul 2011 17:42:34 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QfIoi-0002ky-BV for qemu-devel@nongnu.org; Fri, 08 Jul 2011 17:42:33 -0400 Received: from e9.ny.us.ibm.com ([32.97.182.139]:58000) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QfIoi-0002kq-4q for qemu-devel@nongnu.org; Fri, 08 Jul 2011 17:42:32 -0400 Received: from d01relay07.pok.ibm.com (d01relay07.pok.ibm.com [9.56.227.147]) by e9.ny.us.ibm.com (8.14.4/8.13.1) with ESMTP id p68LAUR5019236 for ; Fri, 8 Jul 2011 17:10:30 -0400 Received: from d01av04.pok.ibm.com (d01av04.pok.ibm.com [9.56.224.64]) by d01relay07.pok.ibm.com (8.13.8/8.13.8/NCO v10.0) with ESMTP id p68LgDAp1761420 for ; Fri, 8 Jul 2011 17:42:13 -0400 Received: from d01av04.pok.ibm.com (loopback [127.0.0.1]) by d01av04.pok.ibm.com (8.14.4/8.13.1/NCO v10.0 AVout) with ESMTP id p68LgDCB015583 for ; Fri, 8 Jul 2011 17:42:13 -0400 Message-ID: <4E1779B0.2010605@linux.vnet.ibm.com> Date: Fri, 08 Jul 2011 16:42:08 -0500 From: Michael Roth MIME-Version: 1.0 References: <1309872100-27912-1-git-send-email-mdroth@linux.vnet.ibm.com> <1309872100-27912-4-git-send-email-mdroth@linux.vnet.ibm.com> <20110708120801.236944ad@doriath> In-Reply-To: <20110708120801.236944ad@doriath> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Subject: Re: [Qemu-devel] [PATCH v6 3/4] guest agent: add guest agent commands schema file List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Luiz Capitulino Cc: aliguori@linux.vnet.ibm.com, agl@linux.vnet.ibm.com, qemu-devel@nongnu.org, Jes.Sorensen@redhat.com On 07/08/2011 10:08 AM, Luiz Capitulino wrote: > On Tue, 5 Jul 2011 08:21:39 -0500 > Michael Roth wrote: > >> >> Signed-off-by: Michael Roth >> --- >> 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' } >