Commit 876c6751 authored by Peter Xu's avatar Peter Xu Committed by Eric Blake
Browse files

qapi: introduce new cmd option "allow-oob" 

Here "oob" stands for "Out-Of-Band".  When "allow-oob" is set, it means
the command allows out-of-band execution.

The "oob" idea is proposed by Markus Armbruster in following thread:

  https://lists.gnu.org/archive/html/qemu-devel/2017-09/msg02057.html



This new "allow-oob" boolean will be exposed by "query-qmp-schema" as
well for command entries, so that QMP clients can know which commands
can be used in out-of-band calls. For example the command "migrate"
originally looks like:

  {"name": "migrate", "ret-type": "17", "meta-type": "command",
   "arg-type": "86"}

And it'll be changed into:

  {"name": "migrate", "ret-type": "17", "allow-oob": false,
   "meta-type": "command", "arg-type": "86"}

This patch only provides the QMP interface level changes.  It does not
contain the real out-of-band execution implementation yet.

Suggested-by: default avatarMarkus Armbruster <armbru@redhat.com>
Reviewed-by: default avatarStefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: default avatarFam Zheng <famz@redhat.com>
Signed-off-by: default avatarPeter Xu <peterx@redhat.com>
Message-Id: <20180309090006.10018-18-peterx@redhat.com>
Reviewed-by: default avatarEric Blake <eblake@redhat.com>
[eblake: rebase on introspection done by qlit]
Signed-off-by: default avatarEric Blake <eblake@redhat.com>
parent bf1e7301

include/qapi/qmp/dispatch.h

+3 −2
Original line number Diff line number Diff line
@@ -21,7 +21,8 @@ typedef void (QmpCommandFunc)(QDict *, QObject **, Error **); 
typedef enum QmpCommandOptions

{

    QCO_NO_OPTIONS            =  0x0,

    QCO_NO_SUCCESS_RESP = 0x1,

    QCO_NO_SUCCESS_RESP       =  (1U << 0),

    QCO_ALLOW_OOB             =  (1U << 1),

} QmpCommandOptions;



typedef struct QmpCommand

qapi/introspect.json

+5 −1
Original line number Diff line number Diff line
@@ -259,12 +259,16 @@ 
#

# @ret-type: the name of the command's result type.

#

# @allow-oob: whether the command allows out-of-band execution.

#             (Since: 2.12)

#

# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)

#

# Since: 2.5

##

{ 'struct': 'SchemaInfoCommand',

  'data': { 'arg-type': 'str', 'ret-type': 'str' } }

  'data': { 'arg-type': 'str', 'ret-type': 'str',

            'allow-oob': 'bool' } }



##

# @SchemaInfoEvent:

scripts/qapi/commands.py

+13 −5
Original line number Diff line number Diff line
@@ -193,10 +193,18 @@ out: 
    return ret





def gen_register_command(name, success_response):

    options = 'QCO_NO_OPTIONS'

def gen_register_command(name, success_response, allow_oob):

    options = []



    if not success_response:

        options = 'QCO_NO_SUCCESS_RESP'

        options += ['QCO_NO_SUCCESS_RESP']

    if allow_oob:

        options += ['QCO_ALLOW_OOB']



    if not options:

        options = ['QCO_NO_OPTIONS']



    options = " | ".join(options)



    ret = mcgen('''

    qmp_register_command(cmds, "%(name)s",
@@ -268,7 +276,7 @@ void %(c_prefix)sqmp_init_marshal(QmpCommandList *cmds); 
        genc.add(gen_registry(self._regy, self._prefix))



    def visit_command(self, name, info, arg_type, ret_type,

                      gen, success_response, boxed):

                      gen, success_response, boxed, allow_oob):

        if not gen:

            return

        self._genh.add(gen_command_decl(name, arg_type, boxed, ret_type))
@@ -277,7 +285,7 @@ void %(c_prefix)sqmp_init_marshal(QmpCommandList *cmds); 
            self._genc.add(gen_marshal_output(ret_type))

        self._genh.add(gen_marshal_decl(name))

        self._genc.add(gen_marshal(name, arg_type, boxed, ret_type))

        self._regy += gen_register_command(name, success_response)

        self._regy += gen_register_command(name, success_response, allow_oob)





def gen_commands(schema, output_dir, prefix):

scripts/qapi/common.py

+10 −5
Original line number Diff line number Diff line
@@ -921,7 +921,8 @@ def check_exprs(exprs): 
        elif 'command' in expr:

            meta = 'command'

            check_keys(expr_elem, 'command', [],

                       ['data', 'returns', 'gen', 'success-response', 'boxed'])

                       ['data', 'returns', 'gen', 'success-response',

                        'boxed', 'allow-oob'])

        elif 'event' in expr:

            meta = 'event'

            check_keys(expr_elem, 'event', [], ['data', 'boxed'])
@@ -1044,7 +1045,7 @@ class QAPISchemaVisitor(object): 
        pass



    def visit_command(self, name, info, arg_type, ret_type,

                      gen, success_response, boxed):

                      gen, success_response, boxed, allow_oob):

        pass



    def visit_event(self, name, info, arg_type, boxed):
@@ -1421,7 +1422,7 @@ class QAPISchemaAlternateType(QAPISchemaType): 


class QAPISchemaCommand(QAPISchemaEntity):

    def __init__(self, name, info, doc, arg_type, ret_type,

                 gen, success_response, boxed):

                 gen, success_response, boxed, allow_oob):

        QAPISchemaEntity.__init__(self, name, info, doc)

        assert not arg_type or isinstance(arg_type, str)

        assert not ret_type or isinstance(ret_type, str)
@@ -1432,6 +1433,7 @@ class QAPISchemaCommand(QAPISchemaEntity): 
        self.gen = gen

        self.success_response = success_response

        self.boxed = boxed

        self.allow_oob = allow_oob



    def check(self, schema):

        if self._arg_type_name:
@@ -1455,7 +1457,8 @@ class QAPISchemaCommand(QAPISchemaEntity): 
    def visit(self, visitor):

        visitor.visit_command(self.name, self.info,

                              self.arg_type, self.ret_type,

                              self.gen, self.success_response, self.boxed)

                              self.gen, self.success_response,

                              self.boxed, self.allow_oob)





class QAPISchemaEvent(QAPISchemaEntity):
@@ -1674,6 +1677,7 @@ class QAPISchema(object): 
        gen = expr.get('gen', True)

        success_response = expr.get('success-response', True)

        boxed = expr.get('boxed', False)

        allow_oob = expr.get('allow-oob', False)

        if isinstance(data, OrderedDict):

            data = self._make_implicit_object_type(

                name, info, doc, 'arg', self._make_members(data, info))
@@ -1681,7 +1685,8 @@ class QAPISchema(object): 
            assert len(rets) == 1

            rets = self._make_array_type(rets[0], info)

        self._def_entity(QAPISchemaCommand(name, info, doc, data, rets,

                                           gen, success_response, boxed))

                                           gen, success_response,

                                           boxed, allow_oob))



    def _def_event(self, expr, info, doc):

        name = expr['event']

scripts/qapi/doc.py

+1 −1
Original line number Diff line number Diff line
@@ -227,7 +227,7 @@ class QAPISchemaGenDocVisitor(qapi.common.QAPISchemaVisitor): 
                               body=texi_entity(doc, 'Members')))



    def visit_command(self, name, info, arg_type, ret_type,

                      gen, success_response, boxed):

                      gen, success_response, boxed, allow_oob):

        doc = self.cur_doc

        if boxed:

            body = texi_body(doc)