Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/813736/?format=api
{ "id": 813736, "url": "http://patchwork.ozlabs.org/api/patches/813736/?format=api", "web_url": "http://patchwork.ozlabs.org/project/qemu-devel/patch/1505375436-28439-14-git-send-email-peterx@redhat.com/", "project": { "id": 14, "url": "http://patchwork.ozlabs.org/api/projects/14/?format=api", "name": "QEMU Development", "link_name": "qemu-devel", "list_id": "qemu-devel.nongnu.org", "list_email": "qemu-devel@nongnu.org", "web_url": "", "scm_url": "", "webscm_url": "", "list_archive_url": "", "list_archive_url_format": "", "commit_url_format": "" }, "msgid": "<1505375436-28439-14-git-send-email-peterx@redhat.com>", "list_archive_url": null, "date": "2017-09-14T07:50:34", "name": "[RFC,13/15] qapi: introduce new cmd option \"allow-oob\"", "commit_ref": null, "pull_url": null, "state": "new", "archived": false, "hash": "ce9e7e829eceb20297c14bbb05a2b98cb9decdef", "submitter": { "id": 67717, "url": "http://patchwork.ozlabs.org/api/people/67717/?format=api", "name": "Peter Xu", "email": "peterx@redhat.com" }, "delegate": null, "mbox": "http://patchwork.ozlabs.org/project/qemu-devel/patch/1505375436-28439-14-git-send-email-peterx@redhat.com/mbox/", "series": [ { "id": 3043, "url": "http://patchwork.ozlabs.org/api/series/3043/?format=api", "web_url": "http://patchwork.ozlabs.org/project/qemu-devel/list/?series=3043", "date": "2017-09-14T07:50:21", "name": "QMP: out-of-band (OOB) execution support", "version": 1, "mbox": "http://patchwork.ozlabs.org/series/3043/mbox/" } ], "comments": "http://patchwork.ozlabs.org/api/patches/813736/comments/", "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/813736/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org>", "X-Original-To": "incoming@patchwork.ozlabs.org", "Delivered-To": "patchwork-incoming@bilbo.ozlabs.org", "Authentication-Results": [ "ozlabs.org;\n\tspf=pass (mailfrom) smtp.mailfrom=nongnu.org\n\t(client-ip=2001:4830:134:3::11; helo=lists.gnu.org;\n\tenvelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n\treceiver=<UNKNOWN>)", "ext-mx02.extmail.prod.ext.phx2.redhat.com;\n\tdmarc=none (p=none dis=none) header.from=redhat.com", "ext-mx02.extmail.prod.ext.phx2.redhat.com;\n\tspf=fail smtp.mailfrom=peterx@redhat.com" ], "Received": [ "from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11])\n\t(using TLSv1 with cipher AES256-SHA (256/256 bits))\n\t(No client certificate requested)\n\tby ozlabs.org (Postfix) with ESMTPS id 3xt9t92cFgz9sRm\n\tfor <incoming@patchwork.ozlabs.org>;\n\tThu, 14 Sep 2017 17:59:45 +1000 (AEST)", "from localhost ([::1]:46218 helo=lists.gnu.org)\n\tby lists.gnu.org with esmtp (Exim 4.71) (envelope-from\n\t<qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org>)\n\tid 1dsP3n-00061t-Er\n\tfor incoming@patchwork.ozlabs.org; Thu, 14 Sep 2017 03:59:43 -0400", "from eggs.gnu.org ([2001:4830:134:3::10]:52830)\n\tby lists.gnu.org with esmtp (Exim 4.71)\n\t(envelope-from <peterx@redhat.com>) id 1dsOwe-0007S9-6n\n\tfor qemu-devel@nongnu.org; Thu, 14 Sep 2017 03:52:22 -0400", "from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)\n\t(envelope-from <peterx@redhat.com>) id 1dsOwb-0008Cg-O1\n\tfor qemu-devel@nongnu.org; Thu, 14 Sep 2017 03:52:20 -0400", "from mx1.redhat.com ([209.132.183.28]:40734)\n\tby eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32)\n\t(Exim 4.71) (envelope-from <peterx@redhat.com>) id 1dsOwb-0008Am-Fm\n\tfor qemu-devel@nongnu.org; Thu, 14 Sep 2017 03:52:17 -0400", "from smtp.corp.redhat.com\n\t(int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12])\n\t(using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))\n\t(No client certificate requested)\n\tby mx1.redhat.com (Postfix) with ESMTPS id 71450883AB;\n\tThu, 14 Sep 2017 07:52:16 +0000 (UTC)", "from pxdev.xzpeter.org.com (dhcp-15-224.nay.redhat.com\n\t[10.66.15.224])\n\tby smtp.corp.redhat.com (Postfix) with ESMTP id E3934619BE;\n\tThu, 14 Sep 2017 07:52:11 +0000 (UTC)" ], "DMARC-Filter": "OpenDMARC Filter v1.3.2 mx1.redhat.com 71450883AB", "From": "Peter Xu <peterx@redhat.com>", "To": "qemu-devel@nongnu.org", "Date": "Thu, 14 Sep 2017 15:50:34 +0800", "Message-Id": "<1505375436-28439-14-git-send-email-peterx@redhat.com>", "In-Reply-To": "<1505375436-28439-1-git-send-email-peterx@redhat.com>", "References": "<1505375436-28439-1-git-send-email-peterx@redhat.com>", "X-Scanned-By": "MIMEDefang 2.79 on 10.5.11.12", "X-Greylist": "Sender IP whitelisted, not delayed by milter-greylist-4.5.16\n\t(mx1.redhat.com [10.5.110.26]);\n\tThu, 14 Sep 2017 07:52:16 +0000 (UTC)", "X-detected-operating-system": "by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic]\n\t[fuzzy]", "X-Received-From": "209.132.183.28", "Subject": "[Qemu-devel] [RFC 13/15] qapi: introduce new cmd option \"allow-oob\"", "X-BeenThere": "qemu-devel@nongnu.org", "X-Mailman-Version": "2.1.21", "Precedence": "list", "List-Id": "<qemu-devel.nongnu.org>", "List-Unsubscribe": "<https://lists.nongnu.org/mailman/options/qemu-devel>,\n\t<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>", "List-Archive": "<http://lists.nongnu.org/archive/html/qemu-devel/>", "List-Post": "<mailto:qemu-devel@nongnu.org>", "List-Help": "<mailto:qemu-devel-request@nongnu.org?subject=help>", "List-Subscribe": "<https://lists.nongnu.org/mailman/listinfo/qemu-devel>,\n\t<mailto:qemu-devel-request@nongnu.org?subject=subscribe>", "Cc": "Laurent Vivier <lvivier@redhat.com>, Fam Zheng <famz@redhat.com>, Juan\n\tQuintela <quintela@redhat.com>, Markus Armbruster <armbru@redhat.com>,\n\tpeterx@redhat.com, mdroth@linux.vnet.ibm.com,\n\tStefan Hajnoczi <shajnocz@redhat.com>, =?utf-8?q?Marc-Andr=C3=A9_Lure?=\n\t=?utf-8?q?au?= <marcandre.lureau@gmail.com>,\n\tPaolo Bonzini <pbonzini@redhat.com>, \"Dr . David Alan Gilbert\"\n\t<dgilbert@redhat.com>", "Errors-To": "qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org", "Sender": "\"Qemu-devel\"\n\t<qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org>" }, "content": "Here \"oob\" stands for \"Out-Of-Band\". When \"allow-oob\" is set, it means\nthe command allows out-of-band execution. Please see the spec update\nfor more details.\n\nThe \"oob\" idea is proposed by Markus Armbruster in following thread:\n\n https://lists.gnu.org/archive/html/qemu-devel/2017-09/msg02057.html\n\nThis new \"allow-oob\" boolean will be exposed by \"query-qmp-schema\" as\nwell for command entries, so that QMP clients can know which command can\nbe used as out-of-band calls. For example the command \"migrate\"\noriginally looks like:\n\n {\"name\": \"migrate\", \"ret-type\": \"17\", \"meta-type\": \"command\",\n \"arg-type\": \"86\"}\n\nAnd it'll be changed into:\n\n {\"name\": \"migrate\", \"ret-type\": \"17\", \"allow-oob\": false,\n \"meta-type\": \"command\", \"arg-type\": \"86\"}\n\nThis patch only provides the QMP interface level changes. It does not\ncontains the real out-of-band execution implementation yet.\n\nSuggested-by: Markus Armbruster <armbru@redhat.com>\nSigned-off-by: Peter Xu <peterx@redhat.com>\n---\n docs/devel/qapi-code-gen.txt | 41 ++++++++++++++++++++++++++++++++++++-----\n include/qapi/qmp/dispatch.h | 1 +\n qapi/introspect.json | 6 +++++-\n scripts/qapi-commands.py | 19 ++++++++++++++-----\n scripts/qapi-introspect.py | 10 ++++++++--\n scripts/qapi.py | 15 ++++++++++-----\n scripts/qapi2texi.py | 2 +-\n tests/qapi-schema/test-qapi.py | 2 +-\n 8 files changed, 76 insertions(+), 20 deletions(-)", "diff": "diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt\nindex f04c63f..61fa167 100644\n--- a/docs/devel/qapi-code-gen.txt\n+++ b/docs/devel/qapi-code-gen.txt\n@@ -556,7 +556,8 @@ following example objects:\n \n Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,\n '*returns': TYPE-NAME, '*boxed': true,\n- '*gen': false, '*success-response': false }\n+ '*gen': false, '*success-response': false,\n+ '*allow-oob': false }\n \n Commands are defined by using a dictionary containing several members,\n where three members are most common. The 'command' member is a\n@@ -636,6 +637,34 @@ possible, the command expression should include the optional key\n 'success-response' with boolean value false. So far, only QGA makes\n use of this member.\n \n+Most of the QMP commands are handled sequentially in such a order.\n+Firstly, the JSON Parser parses the command request into some internal\n+message, then it delivers the message to QMP dispatchers; secondly,\n+the QMP dispatchers will handle the commands one by one in time order,\n+respond when necessary. For some commands that always complete\n+\"quickly\" can instead be executed directly during parsing, at the QMP\n+client's request. This kind of commands that allow direct execution\n+is called \"out-of-band\" (\"oob\" as shortcut) commands. the response can\n+overtake prior in-band commands' responses. By default, commands are\n+always in-band. We need to explicitly specify \"allow-oob\" to \"True\"\n+to show that one command can be run out-of-band.\n+\n+One thing to mention is that, although out-of-band execution of\n+commands benefit from quick and asynchronous execution, it need to\n+satisfy at least the following:\n+\n+(1) It is extremely quick and never blocks, so that its execution will\n+ not block parsing routine of any other monitors.\n+\n+(2) It does not need BQL, since the parser can be run without BQL,\n+ while the dispatcher is always with BQL held.\n+\n+If not, the command is not suitable to be allowed to run out-of-band,\n+and it should set its \"allow-oob\" to \"False\". Whether a command is\n+allowed to run out-of-band can also be introspected using\n+query-qmp-schema command. Please see the section \"Client JSON\n+Protocol introspection\" for more information.\n+\n \n === Events ===\n \n@@ -739,10 +768,12 @@ references by name.\n QAPI schema definitions not reachable that way are omitted.\n \n The SchemaInfo for a command has meta-type \"command\", and variant\n-members \"arg-type\" and \"ret-type\". On the wire, the \"arguments\"\n-member of a client's \"execute\" command must conform to the object type\n-named by \"arg-type\". The \"return\" member that the server passes in a\n-success response conforms to the type named by \"ret-type\".\n+members \"arg-type\", \"ret-type\" and \"allow-oob\". On the wire, the\n+\"arguments\" member of a client's \"execute\" command must conform to the\n+object type named by \"arg-type\". The \"return\" member that the server\n+passes in a success response conforms to the type named by\n+\"ret-type\". When \"allow-oob\" is set, it means the command supports\n+out-of-band execution.\n \n If the command takes no arguments, \"arg-type\" names an object type\n without members. Likewise, if the command returns nothing, \"ret-type\"\ndiff --git a/include/qapi/qmp/dispatch.h b/include/qapi/qmp/dispatch.h\nindex 20578dc..b767988 100644\n--- a/include/qapi/qmp/dispatch.h\n+++ b/include/qapi/qmp/dispatch.h\n@@ -23,6 +23,7 @@ typedef enum QmpCommandOptions\n {\n QCO_NO_OPTIONS = 0x0,\n QCO_NO_SUCCESS_RESP = 0x1,\n+ QCO_ALLOW_OOB = 0x2,\n } QmpCommandOptions;\n \n typedef struct QmpCommand\ndiff --git a/qapi/introspect.json b/qapi/introspect.json\nindex 5b3e6e9..57cc137 100644\n--- a/qapi/introspect.json\n+++ b/qapi/introspect.json\n@@ -259,12 +259,16 @@\n #\n # @ret-type: the name of the command's result type.\n #\n+# @allow-oob: whether the command allows out-of-band execution.\n+# (Since: 2.11)\n+#\n # TODO: @success-response (currently irrelevant, because it's QGA, not QMP)\n #\n # Since: 2.5\n ##\n { 'struct': 'SchemaInfoCommand',\n- 'data': { 'arg-type': 'str', 'ret-type': 'str' } }\n+ 'data': { 'arg-type': 'str', 'ret-type': 'str',\n+ 'allow-oob': 'bool' } }\n \n ##\n # @SchemaInfoEvent:\ndiff --git a/scripts/qapi-commands.py b/scripts/qapi-commands.py\nindex 974d0a4..b2b0bc0 100644\n--- a/scripts/qapi-commands.py\n+++ b/scripts/qapi-commands.py\n@@ -192,10 +192,18 @@ out:\n return ret\n \n \n-def gen_register_command(name, success_response):\n- options = 'QCO_NO_OPTIONS'\n+def gen_register_command(name, success_response, allow_oob):\n+ options = []\n+\n if not success_response:\n- options = 'QCO_NO_SUCCESS_RESP'\n+ options += ['QCO_NO_SUCCESS_RESP']\n+ if allow_oob:\n+ options += ['QCO_ALLOW_OOB']\n+\n+ if not options:\n+ options = ['QCO_NO_OPTIONS']\n+\n+ options = \" | \".join(options)\n \n ret = mcgen('''\n qmp_register_command(cmds, \"%(name)s\",\n@@ -241,7 +249,7 @@ class QAPISchemaGenCommandVisitor(QAPISchemaVisitor):\n self._visited_ret_types = None\n \n def visit_command(self, name, info, arg_type, ret_type,\n- gen, success_response, boxed):\n+ gen, success_response, boxed, allow_oob):\n if not gen:\n return\n self.decl += gen_command_decl(name, arg_type, boxed, ret_type)\n@@ -250,7 +258,8 @@ class QAPISchemaGenCommandVisitor(QAPISchemaVisitor):\n self.defn += gen_marshal_output(ret_type)\n self.decl += gen_marshal_decl(name)\n self.defn += gen_marshal(name, arg_type, boxed, ret_type)\n- self._regy += gen_register_command(name, success_response)\n+ self._regy += gen_register_command(name, success_response,\n+ allow_oob)\n \n \n (input_file, output_dir, do_c, do_h, prefix, opts) = parse_command_line()\ndiff --git a/scripts/qapi-introspect.py b/scripts/qapi-introspect.py\nindex 032bcea..9fbf88b 100644\n--- a/scripts/qapi-introspect.py\n+++ b/scripts/qapi-introspect.py\n@@ -28,6 +28,11 @@ def to_json(obj, level=0):\n to_json(obj[key], level + 1))\n for key in sorted(obj.keys())]\n ret = '{' + ', '.join(elts) + '}'\n+ elif isinstance(obj, bool):\n+ if obj:\n+ ret = 'true'\n+ else:\n+ ret = 'false'\n else:\n assert False # not implemented\n if level == 1:\n@@ -154,12 +159,13 @@ const char %(c_name)s[] = %(c_string)s;\n for m in variants.variants]})\n \n def visit_command(self, name, info, arg_type, ret_type,\n- gen, success_response, boxed):\n+ gen, success_response, boxed, allow_oob):\n arg_type = arg_type or self._schema.the_empty_object_type\n ret_type = ret_type or self._schema.the_empty_object_type\n self._gen_json(name, 'command',\n {'arg-type': self._use_type(arg_type),\n- 'ret-type': self._use_type(ret_type)})\n+ 'ret-type': self._use_type(ret_type),\n+ 'allow-oob': allow_oob})\n \n def visit_event(self, name, info, arg_type, boxed):\n arg_type = arg_type or self._schema.the_empty_object_type\ndiff --git a/scripts/qapi.py b/scripts/qapi.py\nindex 62dc52e..f411b8f 100644\n--- a/scripts/qapi.py\n+++ b/scripts/qapi.py\n@@ -920,7 +920,8 @@ def check_exprs(exprs):\n elif 'command' in expr:\n meta = 'command'\n check_keys(expr_elem, 'command', [],\n- ['data', 'returns', 'gen', 'success-response', 'boxed'])\n+ ['data', 'returns', 'gen', 'success-response',\n+ 'boxed', 'allow-oob'])\n elif 'event' in expr:\n meta = 'event'\n check_keys(expr_elem, 'event', [], ['data', 'boxed'])\n@@ -1031,7 +1032,7 @@ class QAPISchemaVisitor(object):\n pass\n \n def visit_command(self, name, info, arg_type, ret_type,\n- gen, success_response, boxed):\n+ gen, success_response, boxed, allow_oob):\n pass\n \n def visit_event(self, name, info, arg_type, boxed):\n@@ -1398,7 +1399,7 @@ class QAPISchemaAlternateType(QAPISchemaType):\n \n class QAPISchemaCommand(QAPISchemaEntity):\n def __init__(self, name, info, doc, arg_type, ret_type,\n- gen, success_response, boxed):\n+ gen, success_response, boxed, allow_oob):\n QAPISchemaEntity.__init__(self, name, info, doc)\n assert not arg_type or isinstance(arg_type, str)\n assert not ret_type or isinstance(ret_type, str)\n@@ -1409,6 +1410,7 @@ class QAPISchemaCommand(QAPISchemaEntity):\n self.gen = gen\n self.success_response = success_response\n self.boxed = boxed\n+ self.allow_oob = allow_oob\n \n def check(self, schema):\n if self._arg_type_name:\n@@ -1432,7 +1434,8 @@ class QAPISchemaCommand(QAPISchemaEntity):\n def visit(self, visitor):\n visitor.visit_command(self.name, self.info,\n self.arg_type, self.ret_type,\n- self.gen, self.success_response, self.boxed)\n+ self.gen, self.success_response,\n+ self.boxed, self.allow_oob)\n \n \n class QAPISchemaEvent(QAPISchemaEntity):\n@@ -1640,6 +1643,7 @@ class QAPISchema(object):\n gen = expr.get('gen', True)\n success_response = expr.get('success-response', True)\n boxed = expr.get('boxed', False)\n+ allow_oob = expr.get('allow-oob', False)\n if isinstance(data, OrderedDict):\n data = self._make_implicit_object_type(\n name, info, doc, 'arg', self._make_members(data, info))\n@@ -1647,7 +1651,8 @@ class QAPISchema(object):\n assert len(rets) == 1\n rets = self._make_array_type(rets[0], info)\n self._def_entity(QAPISchemaCommand(name, info, doc, data, rets,\n- gen, success_response, boxed))\n+ gen, success_response,\n+ boxed, allow_oob))\n \n def _def_event(self, expr, info, doc):\n name = expr['event']\ndiff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py\nindex a317526..0ac0df5 100755\n--- a/scripts/qapi2texi.py\n+++ b/scripts/qapi2texi.py\n@@ -236,7 +236,7 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):\n body=texi_entity(doc, 'Members'))\n \n def visit_command(self, name, info, arg_type, ret_type,\n- gen, success_response, boxed):\n+ gen, success_response, boxed, allow_oob):\n doc = self.cur_doc\n if self.out:\n self.out += '\\n'\ndiff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py\nindex c7724d3..6749e9e 100644\n--- a/tests/qapi-schema/test-qapi.py\n+++ b/tests/qapi-schema/test-qapi.py\n@@ -36,7 +36,7 @@ class QAPISchemaTestVisitor(QAPISchemaVisitor):\n self._print_variants(variants)\n \n def visit_command(self, name, info, arg_type, ret_type,\n- gen, success_response, boxed):\n+ gen, success_response, boxed, allow_oob):\n print 'command %s %s -> %s' % \\\n (name, arg_type and arg_type.name, ret_type and ret_type.name)\n print ' gen=%s success_response=%s boxed=%s' % \\\n", "prefixes": [ "RFC", "13/15" ] }