Merge remote-tracking branch 'remotes/armbru/tags/pull-monitor-2018-07-03-v2' into staging

In rare cases, QAPI cannot express a type-safe representation of a

corresponding Client JSON Protocol command.  You then have to suppress

generation of a marshalling function by including a key 'gen' with

boolean value false, and instead write your own function.  Please try

to avoid adding new commands that rely on this, and instead use

type-safe unions.  For an example of this usage:

boolean value false, and instead write your own function.  For

example:

 { 'command': 'netdev_add',

   'data': {'type': 'str', 'id': 'str'},

   'gen': false }

Please try to avoid adding new commands that rely on this, and instead

use type-safe unions.

Normally, the QAPI schema is used to describe synchronous exchanges,

where a response is expected.  But in some cases, the action of a

command is expected to change state in a way that a successful

response is not possible (although the command will still return a

normal dictionary error on failure).  When a successful reply is not

possible, the command expression should include the optional key

possible, the command expression includes the optional key

'success-response' with boolean value false.  So far, only QGA makes

use of this member.

A command can be declared to support Out-Of-Band (OOB) execution.  By

default, commands do not support OOB.  To declare a command that

supports it, the schema includes an extra 'allow-oob' field.  For

example:

Key 'allow-oob' declares whether the command supports out-of-band

(OOB) execution.  It defaults to false.  For example:

 { 'command': 'migrate_recover',

   'data': { 'uri': 'str' }, 'allow-oob': true }

To execute a command with out-of-band priority, the client specifies

the "control" field in the request, with "run-oob" set to

true. Example:

 => { "execute": "command-support-oob",

      "arguments": { ... },

      "control": { "run-oob": true } }

 <= { "return": { } }

Without it, even the commands that support out-of-band execution will

still be run in-band.

See qmp-spec.txt for out-of-band execution syntax and semantics.

Under normal QMP command execution, the following apply to each

command:

Commands supporting out-of-band execution can still be executed

in-band.

- They are executed in order,

- They run only in main thread of QEMU,

- They run with the BQL held.

When a command is executed in-band, its handler runs in the main

thread with the BQL held.

When a command is executed with OOB, the following changes occur:

When a command is executed out-of-band, its handler runs in a

dedicated monitor I/O thread with the BQL *not* held.

- They can be completed before a pending in-band command,

- They run in a dedicated monitor thread,

- They run with the BQL not held.

An OOB-capable command handler must satisfy the following conditions:

OOB command handlers must satisfy the following conditions:

- It terminates quickly,

- It does not invoke system calls that may block,

- It terminates quickly.

- It does not invoke system calls that may block.

- It does not access guest RAM that may block when userfaultfd is

  enabled for postcopy live migration,

  enabled for postcopy live migration.

- It takes only "fast" locks, i.e. all critical sections protected by

  any lock it takes also satisfy the conditions for OOB command

  handler code.

requires synchronization, but OOB commands can't take the BQL or any

other "slow" lock.

If in doubt, do not implement OOB execution support.

When in doubt, do not implement OOB execution support.

A command may use the optional 'allow-preconfig' key to permit its execution

at early runtime configuration stage (preconfig runstate).

If not specified then a command defaults to 'allow-preconfig': false.

Key 'allow-preconfig' declares whether the command is available before

the machine is built.  It defaults to false.  For example:

An example of declaring a command that is enabled during preconfig:

 { 'command': 'qmp_capabilities',

   'data': { '*enable': [ 'QMPCapability' ] },

   'allow-preconfig': true }

QMP is available before the machine is built only when QEMU was

started with --preconfig.

=== Events ===

Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,

    "QMP": {

        "version": {

            "qemu": {

                "micro": 50, 

                "minor": 6, 

                "major": 1

                "micro": 0,

                "minor": 0,

                "major": 3

            },

            "package": ""

            "package": "v3.0.0"

        },

        "capabilities": [

            "oob"

        ]

    }

}

  is the same of the query-version command)

- The "capabilities" member specify the availability of features beyond the

  baseline specification; the order of elements in this array has no

  particular significance, so a client must search the entire array

  when looking for a particular capability

  particular significance.

2.2.1 Capabilities

------------------

Currently supported capabilities are:

- "oob": the QMP server supports "Out-Of-Band" (OOB) command

  execution.  For more details, please see the "run-oob" parameter in

  the "Issuing Commands" section below.  Not all commands allow this

  "oob" execution.  The "query-qmp-schema" command can be used to

  inspect which commands support "oob" execution.

QMP clients can get a list of supported QMP capabilities of the QMP

server in the greeting message mentioned above.  By default, all the

capabilities are off.  To enable any QMP capabilities, the QMP client

needs to send the "qmp_capabilities" command with an extra parameter

for the requested capabilities.

- "oob": the QMP server supports "out-of-band" (OOB) command

  execution, as described in section "2.3.1 Out-of-band execution".

2.3 Issuing Commands

--------------------

The format for command execution is:

{ "execute": json-string, "arguments": json-object, "id": json-value,

  "control": json-object }

{ "execute": json-string, "arguments": json-object, "id": json-value }

or

{ "exec-oob": json-string, "arguments": json-object, "id": json-value }

 Where,

- The "execute" member identifies the command to be executed by the Server

- The "execute" or "exec-oob" member identifies the command to be

  executed by the server.  The latter requests out-of-band execution.

- The "arguments" member is used to pass any arguments required for the

  execution of the command, it is optional when no arguments are

  required. Each command documents what contents will be considered

  valid when handling the json-argument

- The "id" member is a transaction identification associated with the

  command execution.  It is required for all commands if the OOB -

  capability was enabled at startup, and optional otherwise.  The same

  "id" field will be part of the response if provided. The "id" member

  can be any json-value, although most clients merely use a

  json-number incremented for each successive command

- The "control" member is optional, and currently only used for

  out-of-band execution. The handling or response of an "oob" command

  can overtake prior in-band commands.  To enable "oob" handling of a

  particular command, just provide a control field with: { "control":

  { "run-oob": true } }

  command execution, it is optional and will be part of the response

  if provided.  The "id" member can be any json-value.  A json-number

  incremented for each successive command works fine.

2.3.1 Out-of-band execution

---------------------------

The server normally reads, executes and responds to one command after

the other.  The client therefore receives command responses in issue

order.

With out-of-band execution enabled via capability negotiation (section

4.), the server reads and queues commands as they arrive.  It executes

commands from the queue one after the other.  Commands executed

out-of-band jump the queue: the command get executed right away,

possibly overtaking prior in-band commands.  The client may therefore

receive such a command's response before responses from prior in-band

commands.

To be able to match responses back to their commands, the client needs

to pass "id" with out-of-band commands.  Passing it with all commands

is recommended for clients that accept capability "oob".

If the client sends in-band commands faster than the server can

execute them, the server will eventually drop commands to limit the

queue length.  The sever sends event COMMAND_DROPPED then.

Only a few commands support out-of-band execution.  The ones that do

have "allow-oob": true in output of query-qmp-schema.

2.4 Commands Responses

----------------------

3.1 Server greeting

-------------------

S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 },

     "package": ""}, "capabilities": []}}

S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},

     "package": "v3.0.0"}, "capabilities": ["oob"] } }

3.2 Capabilities negotiation

----------------------------

3.2 Client QMP negotiation

--------------------------

C: { "execute": "qmp_capabilities" }

C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }

S: { "return": {}}

3.3 Simple 'stop' execution

S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },

    "event": "POWERDOWN" }

3.7 Out-of-band execution

-------------------------

C: { "exec-oob": "migrate-pause", "id": 42 }

S: { "id": 42,

     "error": { "class": "GenericError",

      "desc": "migrate-pause is currently only supported during postcopy-active state" } }

4. Capabilities Negotiation

===========================

                          QmpCommandFunc *fn, QmpCommandOptions options);

void qmp_unregister_command(QmpCommandList *cmds, const char *name);

QmpCommand *qmp_find_command(QmpCommandList *cmds, const char *name);

QObject *qmp_dispatch(QmpCommandList *cmds, QObject *request);

void qmp_disable_command(QmpCommandList *cmds, const char *name);

void qmp_enable_command(QmpCommandList *cmds, const char *name);

bool qmp_command_is_enabled(const QmpCommand *cmd);

const char *qmp_command_name(const QmpCommand *cmd);

bool qmp_has_success_response(const QmpCommand *cmd);

QObject *qmp_build_error_object(Error *err);

QDict *qmp_dispatch_check_obj(const QObject *request, Error **errp);

QDict *qmp_error_response(Error *err);

QDict *qmp_dispatch(QmpCommandList *cmds, QObject *request,

                    bool allow_oob);

bool qmp_is_oob(QDict *dict);

typedef void (*qmp_cmd_callback_fn)(QmpCommand *cmd, void *opaque);

QObject *qobject_from_jsonv(const char *string, va_list *ap, Error **errp)

    GCC_FMT_ATTR(1, 0);

QDict *qdict_from_jsonf_nofail(const char *string, ...) GCC_FMT_ATTR(1, 2);

QString *qobject_to_json(const QObject *obj);

QString *qobject_to_json_pretty(const QObject *obj);