Merge remote-tracking branch 'remotes/armbru/tags/pull-qmp-2015-05-05' into staging

                      QEMU Machine Protocol Specification

0. About This Document

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

Copyright (C) 2009-2015 Red Hat, Inc.

This work is licensed under the terms of the GNU GPL, version 2 or

later. See the COPYING file in the top-level directory.

1. Introduction

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

This document specifies the QEMU Machine Protocol (QMP), a JSON-based protocol

which is available for applications to operate QEMU at the machine-level.

This document specifies the QEMU Machine Protocol (QMP), a JSON-based

protocol which is available for applications to operate QEMU at the

machine-level.  It is also in use by the QEMU Guest Agent (QGA), which

is available for host applications to interact with the guest

operating system.

2. Protocol Specification

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

    json-DATA-STRUCTURE-NAME

Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by

the JSON standard:

Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined

by the JSON standard:

http://www.ietf.org/rfc/rfc7159.txt

http://www.ietf.org/rfc/rfc4627.txt

The protocol is always encoded in UTF-8 except for synchronization

bytes (documented below); although thanks to json-string escape

sequences, the server will reply using only the strict ASCII subset.

For convenience, json-object members and json-array elements mentioned in

this document will be in a certain order. However, in real protocol usage

they can be in ANY order, thus no particular order should be assumed.

For convenience, json-object members mentioned in this document will

be in a certain order. However, in real protocol usage they can be in

ANY order, thus no particular order should be assumed. On the other

hand, use of json-array elements presumes that preserving order is

important unless specifically documented otherwise.  Repeating a key

within a json-object gives unpredictable results.

Also for convenience, the server will accept an extension of

'single-quoted' strings in place of the usual "double-quoted"

json-string, and both input forms of strings understand an additional

escape sequence of "\'" for a single quote. The server will only use

double quoting on output.

2.1 General Definitions

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

- The "version" member contains the Server's version information (the format

  is the same of the query-version command)

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

  baseline specification

  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

2.2.1 Capabilities

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

As of the date this document was last revised, no server or client

capability strings have been defined.

2.3 Issuing Commands

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

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

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

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

  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 optional and will be part of the response if

  provided

  provided. The "id" member can be any json-value, although most

  clients merely use a json-number incremented for each successive

  command

2.4 Commands Responses

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

The format of a success response is:

{ "return": json-object, "id": json-value }

{ "return": json-value, "id": json-value }

 Where,

- The "return" member contains the command returned data, which is defined

  in a per-command basis or an empty json-object if the command does not

  return data

- The "return" member contains the data returned by the command, which

  is defined on a per-command basis (usually a json-object or

  json-array of json-objects, but sometimes a json-number, json-string,

  or json-array of json-strings); it is an empty json-object if the

  command does not return data

- The "id" member contains the transaction identification associated

  with the command execution if issued by the Client

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

As a result of state changes, the Server may send messages unilaterally

to the Client at any time. They are called "asynchronous events".

to the Client at any time, when not in the middle of any other

response. They are called "asynchronous events".

The format of asynchronous events is:

- The "event" member contains the event's name

- The "data" member contains event specific data, which is defined in a

  per-event basis, it is optional

- The "timestamp" member contains the exact time of when the event occurred

  in the Server. It is a fixed json-object with time in seconds and

  microseconds

- The "timestamp" member contains the exact time of when the event

  occurred in the Server. It is a fixed json-object with time in

  seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if

  there is a failure to retrieve host time, both members of the

  timestamp will be set to -1.

For a listing of supported asynchronous events, please, refer to the

qmp-events.txt file.

2.5 QGA Synchronization

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

When using QGA, an additional synchronization feature is built into

the protocol.  If the Client sends a raw 0xFF sentinel byte (not valid

JSON), then the Server will reset its state and discard all pending

data prior to the sentinel.  Conversely, if the Client makes use of

the 'guest-sync-delimited' command, the Server will send a raw 0xFF

sentinel byte prior to its response, to aid the Client in discarding

any data prior to the sentinel.

3. QMP Examples

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

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

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

3.2 Simple 'stop' execution

3.2 Client QMP negotiation

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

C: { "execute": "qmp_capabilities" }

S: { "return": {}}

3.3 Simple 'stop' execution

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

C: { "execute": "stop" }

S: { "return": {} }

3.3 KVM information

3.4 KVM information

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

C: { "execute": "query-kvm", "id": "example" }

S: { "return": { "enabled": true, "present": true }, "id": "example"}

3.4 Parsing error

3.5 Parsing error

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

C: { "execute": }

S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }

3.5 Powerdown event

3.6 Powerdown event

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

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

    "event": "POWERDOWN" }

4. Capabilities Negotiation

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

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

When a Client successfully establishes a connection, the Server is in

Capabilities Negotiation mode.

messages are delivered.

5 Compatibility Considerations

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

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

All protocol changes or new features which modify the protocol format in an

incompatible way are disabled by default and will be advertised by the

- Amount of errors generated by a command, that is, new errors can be added

  to any existing command in newer versions of the Server

Any command or field name beginning with "x-" is deemed experimental,

and may be withdrawn or changed in an incompatible manner in a future

release.

Of course, the Server does guarantee to send valid JSON.  But apart from

this, a Client should be "conservative in what they send, and liberal in

what they accept".

6. Downstream extension of QMP

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

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

We recommend that downstream consumers of QEMU do *not* modify QMP.

Management tools should be able to support both upstream and downstream

    info = qmp_query_version(NULL);

    monitor_printf(mon, "%" PRId64 ".%" PRId64 ".%" PRId64 "%s\n",

                   info->qemu.major, info->qemu.minor, info->qemu.micro,

                   info->qemu->major, info->qemu->minor, info->qemu->micro,

                   info->package);

    qapi_free_VersionInfo(info);

                   dev->slot, dev->function);

    monitor_printf(mon, "    ");

    if (dev->class_info.has_desc) {

        monitor_printf(mon, "%s", dev->class_info.desc);

    if (dev->class_info->has_desc) {

        monitor_printf(mon, "%s", dev->class_info->desc);

    } else {

        monitor_printf(mon, "Class %04" PRId64, dev->class_info.q_class);

        monitor_printf(mon, "Class %04" PRId64, dev->class_info->q_class);

    }

    monitor_printf(mon, ": PCI device %04" PRIx64 ":%04" PRIx64 "\n",

                   dev->id.vendor, dev->id.device);

                   dev->id->vendor, dev->id->device);

    if (dev->has_irq) {

        monitor_printf(mon, "      IRQ %" PRId64 ".\n", dev->irq);

    if (dev->has_pci_bridge) {

        monitor_printf(mon, "      BUS %" PRId64 ".\n",

                       dev->pci_bridge->bus.number);

                       dev->pci_bridge->bus->number);

        monitor_printf(mon, "      secondary bus %" PRId64 ".\n",

                       dev->pci_bridge->bus.secondary);

                       dev->pci_bridge->bus->secondary);

        monitor_printf(mon, "      subordinate bus %" PRId64 ".\n",

                       dev->pci_bridge->bus.subordinate);

                       dev->pci_bridge->bus->subordinate);

        monitor_printf(mon, "      IO range [0x%04"PRIx64", 0x%04"PRIx64"]\n",

                       dev->pci_bridge->bus.io_range->base,

                       dev->pci_bridge->bus.io_range->limit);

                       dev->pci_bridge->bus->io_range->base,

                       dev->pci_bridge->bus->io_range->limit);

        monitor_printf(mon,

                       "      memory range [0x%08"PRIx64", 0x%08"PRIx64"]\n",

                       dev->pci_bridge->bus.memory_range->base,

                       dev->pci_bridge->bus.memory_range->limit);

                       dev->pci_bridge->bus->memory_range->base,

                       dev->pci_bridge->bus->memory_range->limit);

        monitor_printf(mon, "      prefetchable memory range "

                       "[0x%08"PRIx64", 0x%08"PRIx64"]\n",

                       dev->pci_bridge->bus.prefetchable_range->base,

                       dev->pci_bridge->bus.prefetchable_range->limit);

                       dev->pci_bridge->bus->prefetchable_range->base,

                       dev->pci_bridge->bus->prefetchable_range->limit);

    }

    for (region = dev->regions; region; region = region->next) {

                                           int bus_num)

{

    PciBridgeInfo *info;

    PciMemoryRange *range;

    info = g_malloc0(sizeof(*info));

    info = g_new0(PciBridgeInfo, 1);

    info->bus.number = dev->config[PCI_PRIMARY_BUS];

    info->bus.secondary = dev->config[PCI_SECONDARY_BUS];

    info->bus.subordinate = dev->config[PCI_SUBORDINATE_BUS];

    info->bus = g_new0(PciBusInfo, 1);

    info->bus->number = dev->config[PCI_PRIMARY_BUS];

    info->bus->secondary = dev->config[PCI_SECONDARY_BUS];

    info->bus->subordinate = dev->config[PCI_SUBORDINATE_BUS];

    info->bus.io_range = g_malloc0(sizeof(*info->bus.io_range));

    info->bus.io_range->base = pci_bridge_get_base(dev, PCI_BASE_ADDRESS_SPACE_IO);

    info->bus.io_range->limit = pci_bridge_get_limit(dev, PCI_BASE_ADDRESS_SPACE_IO);

    range = info->bus->io_range = g_new0(PciMemoryRange, 1);

    range->base = pci_bridge_get_base(dev, PCI_BASE_ADDRESS_SPACE_IO);

    range->limit = pci_bridge_get_limit(dev, PCI_BASE_ADDRESS_SPACE_IO);

    info->bus.memory_range = g_malloc0(sizeof(*info->bus.memory_range));

    info->bus.memory_range->base = pci_bridge_get_base(dev, PCI_BASE_ADDRESS_SPACE_MEMORY);

    info->bus.memory_range->limit = pci_bridge_get_limit(dev, PCI_BASE_ADDRESS_SPACE_MEMORY);

    range = info->bus->memory_range = g_new0(PciMemoryRange, 1);

    range->base = pci_bridge_get_base(dev, PCI_BASE_ADDRESS_SPACE_MEMORY);

    range->limit = pci_bridge_get_limit(dev, PCI_BASE_ADDRESS_SPACE_MEMORY);

    info->bus.prefetchable_range = g_malloc0(sizeof(*info->bus.prefetchable_range));

    info->bus.prefetchable_range->base = pci_bridge_get_base(dev, PCI_BASE_ADDRESS_MEM_PREFETCH);

    info->bus.prefetchable_range->limit = pci_bridge_get_limit(dev, PCI_BASE_ADDRESS_MEM_PREFETCH);

    range = info->bus->prefetchable_range = g_new0(PciMemoryRange, 1);

    range->base = pci_bridge_get_base(dev, PCI_BASE_ADDRESS_MEM_PREFETCH);

    range->limit = pci_bridge_get_limit(dev, PCI_BASE_ADDRESS_MEM_PREFETCH);

    if (dev->config[PCI_SECONDARY_BUS] != 0) {

        PCIBus *child_bus = pci_find_bus_nr(bus, dev->config[PCI_SECONDARY_BUS]);

    uint8_t type;

    int class;

    info = g_malloc0(sizeof(*info));

    info = g_new0(PciDeviceInfo, 1);

    info->bus = bus_num;

    info->slot = PCI_SLOT(dev->devfn);

    info->function = PCI_FUNC(dev->devfn);

    info->class_info = g_new0(PciDeviceClass, 1);

    class = pci_get_word(dev->config + PCI_CLASS_DEVICE);

    info->class_info.q_class = class;

    info->class_info->q_class = class;

    desc = get_class_desc(class);

    if (desc->desc) {

        info->class_info.has_desc = true;

        info->class_info.desc = g_strdup(desc->desc);

        info->class_info->has_desc = true;

        info->class_info->desc = g_strdup(desc->desc);

    }

    info->id.vendor = pci_get_word(dev->config + PCI_VENDOR_ID);

    info->id.device = pci_get_word(dev->config + PCI_DEVICE_ID);

    info->id = g_new0(PciDeviceId, 1);

    info->id->vendor = pci_get_word(dev->config + PCI_VENDOR_ID);

    info->id->device = pci_get_word(dev->config + PCI_DEVICE_ID);

    info->regions = qmp_query_pci_regions(dev);

    info->qdev_id = g_strdup(dev->qdev.id ? dev->qdev.id : "");