qemu/QMP
Amos Kong b1be42803b net: add support of mac-programming over macvtap in QEMU side
Currently macvtap based macvlan device is working in promiscuous
mode, we want to implement mac-programming over macvtap through
Libvirt for better performance.

Design:
 QEMU notifies Libvirt when rx-filter config is changed in guest,
 then Libvirt query the rx-filter information by a monitor command,
 and sync the change to macvtap device. Related rx-filter config
 of the nic contains main mac, rx-mode items and vlan table.

This patch adds a QMP event to notify management of rx-filter change,
and adds a monitor command for management to query rx-filter
information.

Test:
 If we repeatedly add/remove vlan, and change macaddr of vlan
 interfaces in guest by a loop script.

Result:
 The events will flood the QMP client(management), management takes
 too much resource to process the events.

 Event_throttle API (set rate to 1 ms) can avoid the events to flood
 QMP client, but it could cause an unexpected delay (~1ms), guests
 guests normally expect rx-filter updates immediately.

 So we use a flag for each nic to avoid events flooding, the event
 is emitted once until the query command is executed. The flag
 implementation could not introduce unexpected delay.

There maybe exist an uncontrollable delay if we let Libvirt do the
real change, guests normally expect rx-filter updates immediately.
But it's another separate issue, we can investigate it when the
work in Libvirt side is done.

Michael S. Tsirkin: tweaked to enable events on start
Michael S. Tsirkin: fixed not to crash when no id
Michael S. Tsirkin: fold in patch:
   "additional fixes for mac-programming feature"
Amos Kong: always notify QMP client if mactable is changed
Amos Kong: return NULL list if no net client supports rx-filter query

Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Amos Kong <akong@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
2013-07-15 21:23:08 +03:00
..
README QMP: Drop vm-info example script 2010-11-17 09:51:07 -02:00
qemu-ga-client Add qemu-ga-client script 2012-09-26 10:45:02 -03:00
qmp qmp: add test tool for QMP 2011-12-06 11:40:00 -02:00
qmp-events.txt net: add support of mac-programming over macvtap in QEMU side 2013-07-15 21:23:08 +03:00
qmp-shell qmp: fix handling of cmd with Equals in qmp-shell 2013-05-15 08:58:43 -04:00
qmp-spec.txt qmp: switch to the new error format on the wire 2012-08-13 14:17:53 -03:00
qmp.py qmp: add pull_event function 2012-10-24 10:26:22 +02:00
qom-fuse qom: quick and dirty QOM filesystem based on FUSE 2012-04-26 13:14:57 -05:00
qom-get qom: add test tools 2012-02-22 12:18:26 -06:00
qom-list qom: add test tools 2012-02-22 12:18:26 -06:00
qom-set qom: add test tools 2012-02-22 12:18:26 -06:00

README

                          QEMU Monitor Protocol
                          =====================

Introduction
-------------

The QEMU Monitor Protocol (QMP) allows applications to communicate with
QEMU's Monitor.

QMP is JSON[1] based and currently has the following features:

- Lightweight, text-based, easy to parse data format
- Asynchronous messages support (ie. events)
- Capabilities Negotiation

For detailed information on QMP's usage, please, refer to the following files:

o qmp-spec.txt      QEMU Monitor Protocol current specification
o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
o qmp-events.txt    List of available asynchronous events

There is also a simple Python script called 'qmp-shell' available.

IMPORTANT: It's strongly recommended to read the 'Stability Considerations'
section in the qmp-commands.txt file before making any serious use of QMP.


[1] http://www.json.org

Usage
-----

To enable QMP, you need a QEMU monitor instance in "control mode". There are
two ways of doing this.

The simplest one is using the '-qmp' command-line option. The following
example makes QMP available on localhost port 4444:

  $ qemu [...] -qmp tcp:localhost:4444,server

However, in order to have more complex combinations, like multiple monitors,
the '-mon' command-line option should be used along with the '-chardev' one.
For instance, the following example creates one user monitor on stdio and one
QMP monitor on localhost port 4444.

   $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
                -chardev socket,id=mon1,host=localhost,port=4444,server \
                -mon chardev=mon1,mode=control

Please, refer to QEMU's manpage for more information.

Simple Testing
--------------

To manually test QMP one can connect with telnet and issue commands by hand:

$ telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
{"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
{ "execute": "qmp_capabilities" }
{"return": {}}
{ "execute": "query-version" }
{"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}}

Development Process
-------------------

When changing QMP's interface (by adding new commands, events or modifying
existing ones) it's mandatory to update the relevant documentation, which is
one (or more) of the files listed in the 'Introduction' section*.

Also, it's strongly recommended to send the documentation patch first, before
doing any code change. This is so because:

  1. Avoids the code dictating the interface

  2. Review can improve your interface.  Letting that happen before
     you implement it can save you work.

* The qmp-commands.txt file is generated from the qmp-commands.hx one, which
  is the file that should be edited.

Homepage
--------

http://wiki.qemu.org/QMP