Return to qmp-spec.txt CVS log

Up to [Qemu by Fabrice Bellard] / qemu / QMP

Annotation of qemu/QMP/qmp-spec.txt, revision 1.1

1.1     ! root        1:            QEMU Monitor Protocol Specification - Version 0.1
        !             2: 
        !             3: 1. Introduction
        !             4: ===============
        !             5: 
        !             6: This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol
        !             7: which is available for applications to control QEMU at the machine-level.
        !             8: 
        !             9: To enable QMP support, QEMU has to be run in "control mode". This is done by
        !            10: starting QEMU with the appropriate command-line options. Please, refer to the
        !            11: QEMU manual page for more information.
        !            12: 
        !            13: 2. Protocol Specification
        !            14: =========================
        !            15: 
        !            16: This section details the protocol format. For the purpose of this document
        !            17: "Client" is any application which is communicating with QEMU in control mode,
        !            18: and "Server" is QEMU itself.
        !            19: 
        !            20: JSON data structures, when mentioned in this document, are always in the
        !            21: following format:
        !            22: 
        !            23:     json-DATA-STRUCTURE-NAME
        !            24: 
        !            25: Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by
        !            26: the JSON standard:
        !            27: 
        !            28: http://www.ietf.org/rfc/rfc4627.txt
        !            29: 
        !            30: For convenience, json-object members and json-array elements mentioned in
        !            31: this document will be in a certain order. However, in real protocol usage
        !            32: they can be in ANY order, thus no particular order should be assumed.
        !            33: 
        !            34: 2.1 General Definitions
        !            35: -----------------------
        !            36: 
        !            37: 2.1.1 All interactions transmitted by the Server are json-objects, always
        !            38:       terminating with CRLF
        !            39: 
        !            40: 2.1.2 All json-objects members are mandatory when not specified otherwise
        !            41: 
        !            42: 2.2 Server Greeting
        !            43: -------------------
        !            44: 
        !            45: Right when connected the Server will issue a greeting message, which signals
        !            46: that the connection has been successfully established and that the Server is
        !            47: waiting for commands.
        !            48: 
        !            49: The format is:
        !            50: 
        !            51: { "QMP": { "capabilities": json-array } }
        !            52: 
        !            53:  Where,
        !            54: 
        !            55: - The "capabilities" member specify the availability of features beyond the
        !            56:   baseline specification
        !            57: 
        !            58: 2.3 Issuing Commands
        !            59: --------------------
        !            60: 
        !            61: The format for command execution is:
        !            62: 
        !            63: { "execute": json-string, "arguments": json-object, "id": json-value }
        !            64: 
        !            65:  Where,
        !            66: 
        !            67: - The "execute" member identifies the command to be executed by the Server
        !            68: - The "arguments" member is used to pass any arguments required for the
        !            69:   execution of the command, it is optional when no arguments are required
        !            70: - The "id" member is a transaction identification associated with the
        !            71:   command execution, it is optional and will be part of the response if
        !            72:   provided
        !            73: 
        !            74: 2.4 Commands Responses
        !            75: ----------------------
        !            76: 
        !            77: There are two possible responses which the Server will issue as the result
        !            78: of a command execution: success or error.
        !            79: 
        !            80: 2.4.1 success
        !            81: -------------
        !            82: 
        !            83: The success response is issued when the command execution has finished
        !            84: without errors.
        !            85: 
        !            86: The format is:
        !            87: 
        !            88: { "return": json-object, "id": json-value }
        !            89: 
        !            90:  Where,
        !            91: 
        !            92: - The "return" member contains the command returned data, which is defined
        !            93:   in a per-command basis or an empty json-object if the command does not
        !            94:   return data
        !            95: - The "id" member contains the transaction identification associated
        !            96:   with the command execution (if issued by the Client)
        !            97: 
        !            98: 2.4.2 error
        !            99: -----------
        !           100: 
        !           101: The error response is issued when the command execution could not be
        !           102: completed because of an error condition.
        !           103: 
        !           104: The format is:
        !           105: 
        !           106: { "error": { "class": json-string, "data": json-object, "desc": json-string },
        !           107:   "id": json-value }
        !           108: 
        !           109:  Where,
        !           110: 
        !           111: - The "class" member contains the error class name (eg. "ServiceUnavailable")
        !           112: - The "data" member contains specific error data and is defined in a
        !           113:   per-command basis, it will be an empty json-object if the error has no data
        !           114: - The "desc" member is a human-readable error message. Clients should
        !           115:   not attempt to parse this message.
        !           116: - The "id" member contains the transaction identification associated with
        !           117:   the command execution (if issued by the Client)
        !           118: 
        !           119: NOTE: Some errors can occur before the Server is able to read the "id" member,
        !           120: in these cases the "id" member will not be part of the error response, even
        !           121: if provided by the client.
        !           122: 
        !           123: 2.5 Asynchronous events
        !           124: -----------------------
        !           125: 
        !           126: As a result of state changes, the Server may send messages unilaterally
        !           127: to the Client at any time. They are called 'asynchronous events'.
        !           128: 
        !           129: The format is:
        !           130: 
        !           131: { "event": json-string, "data": json-object,
        !           132:   "timestamp": { "seconds": json-number, "microseconds": json-number } }
        !           133: 
        !           134:  Where,
        !           135: 
        !           136: - The "event" member contains the event's name
        !           137: - The "data" member contains event specific data, which is defined in a
        !           138:   per-event basis, it is optional
        !           139: - The "timestamp" member contains the exact time of when the event occurred
        !           140:   in the Server. It is a fixed json-object with time in seconds and
        !           141:   microseconds
        !           142: 
        !           143: For a listing of supported asynchronous events, please, refer to the
        !           144: qmp-events.txt file.
        !           145: 
        !           146: 3. QMP Examples
        !           147: ===============
        !           148: 
        !           149: This section provides some examples of real QMP usage, in all of them
        !           150: 'C' stands for 'Client' and 'S' stands for 'Server'.
        !           151: 
        !           152: 3.1 Server greeting
        !           153: -------------------
        !           154: 
        !           155: S: {"QMP": {"capabilities": []}}
        !           156: 
        !           157: 3.2 Simple 'stop' execution
        !           158: ---------------------------
        !           159: 
        !           160: C: { "execute": "stop" }
        !           161: S: {"return": {}}
        !           162: 
        !           163: 3.3 KVM information
        !           164: -------------------
        !           165: 
        !           166: C: { "execute": "query-kvm", "id": "example" }
        !           167: S: {"return": {"enabled": true, "present": true}, "id": "example"}
        !           168: 
        !           169: 3.4 Parsing error
        !           170: ------------------
        !           171: 
        !           172: C: { "execute": }
        !           173: S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
        !           174: {}}}
        !           175: 
        !           176: 3.5 Powerdown event
        !           177: -------------------
        !           178: 
        !           179: S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
        !           180: "POWERDOWN"}
        !           181: 
        !           182: 4. Compatibility Considerations
        !           183: --------------------------------
        !           184: 
        !           185: In order to achieve maximum compatibility between versions, Clients must not 
        !           186: assume any particular:
        !           187: 
        !           188: - Size of json-objects or length of json-arrays
        !           189: - Order of json-object members or json-array elements
        !           190: - Amount of errors generated by a command, that is, new errors can be added
        !           191:   to any existing command in newer versions of the Server
        !           192: 
        !           193: Additionally, Clients should always:
        !           194: 
        !           195: - Check the capabilities json-array at connection time
        !           196: - Check the availability of commands with 'query-commands' before issuing them
        !           197: 
        !           198: 5. Recommendations to Client implementors
        !           199: -----------------------------------------
        !           200: 
        !           201: 5.1 The Server should be always started in pause mode, thus the Client is
        !           202:     able to perform any setup procedure without the risk of race conditions
        !           203:     and related problems

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.