Notes [01-AUG-2016]
===================


-----------------------------------------------------------------------
Notes (via upstream qemu-devel mailing list) from Markus Armburster
[thanks!] on how to communicate with QEMU via UNIX socket:

It's easy, as QEMU command line goes:

    -qmp unix:./qmp-sock,server,nowait

The above is syntactic sugar for something like:

    -chardev socket,id=compat_monitor1,path=./qmp-sock,server=on,wait=off
    -mon mode=control,chardev=compat_monitor1

The long form is more flexible.  If you use it, don't use
id=compat_monitor1, obviously.

Easier on the eyes as configuration file for -readconfig:

    [chardev "qmp"]
      backend = "socket"
      path = "sock-qmp"
      server = "on"
      wait = "off"

    [mon "qmp"]
      mode = "control"
      chardev = "qmp"
      pretty = "on"


Connect to it with: [13-APR-2015]

    $ socat UNIX:/var/tmp/test-qmp READLINE,history=$HOME/.qmp_history,prompt='QMP> '

Caveat (as of 14OCT2015)
------------------------

[Again, thanks to Markus.]

One plausible reason [why libvirt doesn't use it] -- it's incomplete:
works for many options, but not all]

Q: How to tell what options are supported and what doesn't? 

A: A rough, practical answer is -readconfig can read what -writeconfig
writes.

   A thorough answer is -readconfig and -writeconfig are limited to
   options implemented with "QemuOpts"[*]

   These are visible (with some warts) in `query-command-line-options`.

   See also slide 21 of:

        http://www.linux-kvm.org/images/7/7a/02x05-Aspen-Markus_Armbruster-QEMU_interface_introspection.pdf


[*] 'QemuOpts' framework was introduced in this commit:

        commit e27c88fe9eb26648e4fb282cb3761c41f06ff18a
        Author: Gerd Hoffmann <kraxel@redhat.com>
        Date:   Wed Jul 22 16:43:03 2009 +0200
        
            QemuOpts: framework for storing and parsing options.
            This stores device parameters in a better way than unparsed strings.
            
            New types:
              QemuOpt       -  one key-value pair.
              QemuOpts      -  group of key-value pairs, belonging to one
                               device, i.e. one drive.
              QemuOptsList  -  list of some kind of devices, i.e. all drives.
            
            Functions are provided to work with these types.  The plan is that some
            day we will pass around QemuOpts pointers instead of strings filled with
            "key1=value1,key2=value2".


More notes (from Markus)
------------------------

"In general, character devices provide a bidirectional pipe, but -chardev
file is write-only.  I think you want -chardev pipe. 

Here's how I use it.  Set up a local socket (any convenient
bidirectional pipe would do, actually).

Example: QMP

    # Configuration file for -readconfig                                                                                                                                                      
    [chardev "qmp"]
      backend = "socket"
      path = "sock-qmp"
      server = "on"
      wait = "off"

    [mon "qmp"]
      mode = "control"
      chardev = "qmp"
      pretty = "on"

Example: HMP

    [chardev "hmp"]
      backend = "socket"
      path = "sock-hmp"
      server = "on"
      wait = "off"

    [mon "hmp"]
      mode = "readline"
      chardev = "hmp"

Then do stuff with it.

Example: interactive QMP

    $ socat UNIX:sock-qmp READLINE,history=$HOME/.qmp_history,prompt='QMP> '

Example: interactive HMP

    $ socat UNIX:sock-hmp READLINE,history=$HOME/.hmp_history

Arguably superior to our built-in not-quite readline monitor.

Example: send QMP input from a file, capture its output in a file

    $ socat UNIX:sock-qmp STDIO <input >output
"

    * * *

[Thanks to Markus Armbruster for the tip. 01-AUG-2016]

You can examine some (but not quite all) "de-sugarings" like this:

    $ qemu-system-x86_64 -display none -S \
        -qmp unix:./qmp-sock,server,nowait -writeconfig /dev/stdout
    # qemu config file
    
    [chardev "compat_monitor0"]
      backend = "socket"
      path = "./qmp-sock"
      server = "on"
      wait = "off"
    
    [mon "compat_monitor0"]
      mode = "control"
      chardev = "compat_monitor0"
      pretty = "off"
      default = "on"


Here's the complete configuration of a long QEMU command-line

    https://kashyapc.fedorapeople.org/virt/qemu/qemu-config-from-libvirt-qemu-command-line.txt

- - -


Description (from manual page)

"-chardev socket" -- creates a two-way UNIX stream socket 

	- 'path' -- specifies the local path of the UNIX socket

    - 'id' -- any sring up to 127 characters long.  (It is used to
      uniquely identify this device in other command line directives.)

    - 'server' -- specifies that the socket shall be a listening socket

    - 'nowait' -- specifies that QEMU should not block waiting for a
      client to connect to a listening socket

"-mon" -- "Setup monitor on chardev name"

    - 'chardev' -- ID of the UNIX socket created

    - 'id' -- ID of the monitor instance

    - 'mode' -- 'control' allow to supply QEMU commands.mode where you
      can interact with it