meson: convert hw/vfio
[qemu.git] / docs / interop / qmp-intro.txt
1                           QEMU Machine Protocol
2                           =====================
3
4 Introduction
5 ------------
6
7 The QEMU Machine Protocol (QMP) allows applications to operate a
8 QEMU instance.
9
10 QMP is JSON[1] based and features the following:
11
12 - Lightweight, text-based, easy to parse data format
13 - Asynchronous messages support (ie. events)
14 - Capabilities Negotiation
15
16 For detailed information on QMP's usage, please, refer to the following files:
17
18 o qmp-spec.txt      QEMU Machine Protocol current specification
19 o qemu-qmp-ref.html QEMU QMP commands and events (auto-generated at build-time)
20
21 [1] https://www.json.org
22
23 Usage
24 -----
25
26 You can use the -qmp option to enable QMP. For example, the following
27 makes QMP available on localhost port 4444:
28
29 $ qemu [...] -qmp tcp:localhost:4444,server,nowait
30
31 However, for more flexibility and to make use of more options, the -mon
32 command-line option should be used. For instance, the following example
33 creates one HMP instance (human monitor) on stdio and one QMP instance
34 on localhost port 4444:
35
36 $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
37              -chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
38              -mon chardev=mon1,mode=control,pretty=on
39
40 Please, refer to QEMU's manpage for more information.
41
42 Simple Testing
43 --------------
44
45 To manually test QMP one can connect with telnet and issue commands by hand:
46
47 $ telnet localhost 4444
48 Trying 127.0.0.1...
49 Connected to localhost.
50 Escape character is '^]'.
51 {
52     "QMP": {
53         "version": {
54             "qemu": {
55                 "micro": 0,
56                 "minor": 0,
57                 "major": 3
58             },
59             "package": "v3.0.0"
60         },
61         "capabilities": [
62             "oob"
63         ]
64     }
65 }
66
67 { "execute": "qmp_capabilities" }
68 {
69     "return": {
70     }
71 }
72
73 { "execute": "query-status" }
74 {
75     "return": {
76         "status": "prelaunch", 
77         "singlestep": false, 
78         "running": false
79     }
80 }
81
82 Please refer to docs/interop/qemu-qmp-ref.* for a complete command
83 reference, generated from qapi/qapi-schema.json.
84
85 QMP wiki page
86 -------------
87
88 https://wiki.qemu.org/QMP