[Qemu-devel] [RFC] QMP: Introduce query-netdevices documentation

[Qemu-devel] [RFC] QMP: Introduce query-netdevices documentation

[Miguel Di Ciurcio Filho]

This introduces the protocol specification for querying information about
network devices available on a VM and a new monitor command that show the same
information.

Signed-off-by: Miguel Di Ciurcio Filho <miguel.filho@gmail.com>
---
 qemu-monitor.hx |   69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 69 insertions(+), 0 deletions(-)

diff --git a/qemu-monitor.hx b/qemu-monitor.hx
index f6a94f2..8600129 100644
--- a/qemu-monitor.hx
+++ b/qemu-monitor.hx
@@ -1674,6 +1674,75 @@ show the various VLANs and the associated devices
 ETEXI
 
 STEXI
+@item info netdevices
+show information about network devices
+ETEXI
+SQMP
+query-netdevices
+----------------
+
+Each device is represented by a json-object. The returned value is a json-array
+of all devices.
+
+Each json-object contain the following:
+
+- "device": device name (json-string)
+- "vlan": only present if the device is attached to a VLAN (json-int)
+- "info": json-object containing the following:
+          - "model": type of the device (json-string)
+              - Possible values: "tap", "socket", "xen", "slirp", "dump",
+                                 "vde", "ne2k_pci", "i82551", "i82557b",
+                                 "i82559er", "rtl8139", "e1000", "pcnet",
+                                 "virtio", "dp83932", "lan9118", "mcf_fec",
+                                 "xilinx-ethlite", "lance", "stellaris",
+                                 "smc91c111", "ne2k_isa", "mv88w8618",
+                                 "mipsnet", "fseth", "dp83932", "usb"
+          - "macaddr": MAC address, only present if the device is a NIC
+            (json-string)
+          - "script": path to script used to configure the device, only present
+            if "model" is "tap" (json-string)
+          - "downscript": path to script used to deconfigure the device, only
+            present if "model" is "tap" (json-string)
+          - "fd": handle to the device, only present if "model" is "vde"
+            (json-int)
+          - "ifname": name of the host device connected to the guest device,
+            only present if "model" is "tap" (json-string)
+          - "host": IP address, only present if "model" is "socket"
+            (json-string)
+          - "service": port number, only present if "model" is "socket"
+          - "family": address familyi, only present if "model" is "socket"
+            (json-string)
+                - Possible values: "ipv4"
+
+Example:
+
+-> { "execute": "query-netdevices" }
+<- {
+      "return": [
+         {
+            "device": "tap.0",
+            "vlan": 0,
+            "info": {
+               "script": "/etc/kvm/kvm-ifup",
+               "downscript": "/etc/qemu-ifdown",
+               "ifname": "tap0",
+               "model": "tap"
+            },
+         },
+         {
+           "device": "e1000.0",
+           "vlan": 0,
+           "info": {
+              "model": "e1000",
+              "macaddr": "52:54:00:12:34:56"
+           },
+         }
+      ]
+   }
+
+EQMP
+
+STEXI
 @item info chardev
 show the character devices
 ETEXI
-- 
1.7.1

[Qemu-devel] Re: [RFC] QMP: Introduce query-netdevices documentation

[Avi Kivity]

On 06/04/2010 05:06 PM, Miguel Di Ciurcio Filho wrote:
> This introduces the protocol specification for querying information about
> network devices available on a VM and a new monitor command that show the same
> information.
>
> Signed-off-by: Miguel Di Ciurcio Filho<miguel.filho@gmail.com>
> ---
>   qemu-monitor.hx |   69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 files changed, 69 insertions(+), 0 deletions(-)
>
> diff --git a/qemu-monitor.hx b/qemu-monitor.hx
> index f6a94f2..8600129 100644
> --- a/qemu-monitor.hx
> +++ b/qemu-monitor.hx
> @@ -1674,6 +1674,75 @@ show the various VLANs and the associated devices
>   ETEXI
>
>   STEXI
> +@item info netdevices
> +show information about network devices
> +ETEXI
> +SQMP
> +query-netdevices
> +----------------
> +
> +Each device is represented by a json-object. The returned value is a json-array
> +of all devices.
> +
> +Each json-object contain the following:
> +
> +- "device": device name (json-string)
> +- "vlan": only present if the device is attached to a VLAN (json-int)
> +- "info": json-object containing the following:
> +          - "model": type of the device (json-string)
> +              - Possible values: "tap", "socket", "xen", "slirp", "dump",
> +                                 "vde", "ne2k_pci", "i82551", "i82557b",
> +                                 "i82559er", "rtl8139", "e1000", "pcnet",
> +                                 "virtio", "dp83932", "lan9118", "mcf_fec",
> +                                 "xilinx-ethlite", "lance", "stellaris",
> +                                 "smc91c111", "ne2k_isa", "mv88w8618",
> +                                 "mipsnet", "fseth", "dp83932", "usb"
>    

This casts the vlan model into concrete.  I thought we wanted to move 
away from it?  Instead have separate entries for host and guest devices.

-- 
error compiling committee.c: too many arguments to function

[Qemu-devel] Re: [RFC] QMP: Introduce query-netdevices documentation

[Miguel Di Ciurcio Filho]

On Sun, Jun 6, 2010 at 12:50 PM, Avi Kivity <avi@redhat.com> wrote:
>> +Each json-object contain the following:
>> +
>> +- "device": device name (json-string)
>> +- "vlan": only present if the device is attached to a VLAN (json-int)
>> +- "info": json-object containing the following:
>> +          - "model": type of the device (json-string)
>> +              - Possible values: "tap", "socket", "xen", "slirp", "dump",
>> +                                 "vde", "ne2k_pci", "i82551", "i82557b",
>> +                                 "i82559er", "rtl8139", "e1000", "pcnet",
>> +                                 "virtio", "dp83932", "lan9118",
>> "mcf_fec",
>> +                                 "xilinx-ethlite", "lance", "stellaris",
>> +                                 "smc91c111", "ne2k_isa", "mv88w8618",
>> +                                 "mipsnet", "fseth", "dp83932", "usb"
>>
>
> This casts the vlan model into concrete.  I thought we wanted to move away
> from it?  Instead have separate entries for host and guest devices.

The vlan attribute is optional. In this case, it is a vlan inside the
context of the VM. I've searched the archives and I've found some
references about the confusion about real VLANs (802.1Q) and QEMU's
vlans. Correct me if I'm wrong, but I suppose they are completely
different animals.

When you say separate entries for host and guest devices, you mean
something like this:

$ qemu -netdev tap,id=tap0 -device e1000,netdev=tap0

This makes a 1:1 relation. So clearly tap0 is a host device, e1000.0
will be a guest device, and they are connected.

$ qemu -net tap,ifname=tap0 -net nic,model=e1000

This glues the two devices into a vlan inside the VM.

Do you mean that this second model should be deprecated?

Regards,

Miguel

[Qemu-devel] Re: [RFC] QMP: Introduce query-netdevices documentation

[Avi Kivity]

On 06/07/2010 03:57 PM, Miguel Di Ciurcio Filho wrote:
> On Sun, Jun 6, 2010 at 12:50 PM, Avi Kivity<avi@redhat.com>  wrote:
>    
>>> +Each json-object contain the following:
>>> +
>>> +- "device": device name (json-string)
>>> +- "vlan": only present if the device is attached to a VLAN (json-int)
>>> +- "info": json-object containing the following:
>>> +          - "model": type of the device (json-string)
>>> +              - Possible values: "tap", "socket", "xen", "slirp", "dump",
>>> +                                 "vde", "ne2k_pci", "i82551", "i82557b",
>>> +                                 "i82559er", "rtl8139", "e1000", "pcnet",
>>> +                                 "virtio", "dp83932", "lan9118",
>>> "mcf_fec",
>>> +                                 "xilinx-ethlite", "lance", "stellaris",
>>> +                                 "smc91c111", "ne2k_isa", "mv88w8618",
>>> +                                 "mipsnet", "fseth", "dp83932", "usb"
>>>
>>>        
>> This casts the vlan model into concrete.  I thought we wanted to move away
>> from it?  Instead have separate entries for host and guest devices.
>>      
> The vlan attribute is optional. In this case, it is a vlan inside the
> context of the VM. I've searched the archives and I've found some
> references about the confusion about real VLANs (802.1Q) and QEMU's
> vlans. Correct me if I'm wrong, but I suppose they are completely
> different animals.
>    

Right.  I'm talking about the qemu internal vlans.

> When you say separate entries for host and guest devices, you mean
> something like this:
>
> $ qemu -netdev tap,id=tap0 -device e1000,netdev=tap0
>
> This makes a 1:1 relation. So clearly tap0 is a host device, e1000.0
> will be a guest device, and they are connected.
>    

Yes.  I'd want separate queries for each, or perhaps a single query that 
returns

{ 'hostdev': some-object-with-host-device-properties-only, 'nic': 
some-object-that-describes-the-guest-nic }

> $ qemu -net tap,ifname=tap0 -net nic,model=e1000
>
> This glues the two devices into a vlan inside the VM.
>
> Do you mean that this second model should be deprecated?
>    

I think it is.  It doesn't play well with acceleration technologies like 
vhost that want a 1:1 relationship.

-- 
error compiling committee.c: too many arguments to function

[Qemu-devel] Re: [RFC] QMP: Introduce query-netdevices documentation

[Anthony Liguori]

On 06/07/2010 08:39 AM, Avi Kivity wrote:
> On 06/07/2010 03:57 PM, Miguel Di Ciurcio Filho wrote:
>> On Sun, Jun 6, 2010 at 12:50 PM, Avi Kivity<avi@redhat.com>  wrote:
>>>> +Each json-object contain the following:
>>>> +
>>>> +- "device": device name (json-string)
>>>> +- "vlan": only present if the device is attached to a VLAN (json-int)
>>>> +- "info": json-object containing the following:
>>>> +          - "model": type of the device (json-string)
>>>> +              - Possible values: "tap", "socket", "xen", "slirp", 
>>>> "dump",
>>>> +                                 "vde", "ne2k_pci", "i82551", 
>>>> "i82557b",
>>>> +                                 "i82559er", "rtl8139", "e1000", 
>>>> "pcnet",
>>>> +                                 "virtio", "dp83932", "lan9118",
>>>> "mcf_fec",
>>>> +                                 "xilinx-ethlite", "lance", 
>>>> "stellaris",
>>>> +                                 "smc91c111", "ne2k_isa", 
>>>> "mv88w8618",
>>>> +                                 "mipsnet", "fseth", "dp83932", "usb"
>>>>
>>> This casts the vlan model into concrete.  I thought we wanted to 
>>> move away
>>> from it?  Instead have separate entries for host and guest devices.
>> The vlan attribute is optional. In this case, it is a vlan inside the
>> context of the VM. I've searched the archives and I've found some
>> references about the confusion about real VLANs (802.1Q) and QEMU's
>> vlans. Correct me if I'm wrong, but I suppose they are completely
>> different animals.
>
> Right.  I'm talking about the qemu internal vlans.
>
>> When you say separate entries for host and guest devices, you mean
>> something like this:
>>
>> $ qemu -netdev tap,id=tap0 -device e1000,netdev=tap0
>>
>> This makes a 1:1 relation. So clearly tap0 is a host device, e1000.0
>> will be a guest device, and they are connected.
>
> Yes.  I'd want separate queries for each, or perhaps a single query 
> that returns
>
> { 'hostdev': some-object-with-host-device-properties-only, 'nic': 
> some-object-that-describes-the-guest-nic }

We need a query-netdev and then info qdm already provides the guest nic 
properties.  Just filter out devices that have a netdev property.

Regards,

Anthony Liguori

>> $ qemu -net tap,ifname=tap0 -net nic,model=e1000
>>
>> This glues the two devices into a vlan inside the VM.
>>
>> Do you mean that this second model should be deprecated?
>
> I think it is.  It doesn't play well with acceleration technologies 
> like vhost that want a 1:1 relationship.
>

[Qemu-devel] Re: [RFC] QMP: Introduce query-netdevices documentation

[Miguel Di Ciurcio Filho]

On Mon, Jun 7, 2010 at 10:48 AM, Anthony Liguori <anthony@codemonkey.ws> wrote:
>>>
>>> $ qemu -netdev tap,id=tap0 -device e1000,netdev=tap0
>>>
>>> This makes a 1:1 relation. So clearly tap0 is a host device, e1000.0
>>> will be a guest device, and they are connected.
>>
>> Yes.  I'd want separate queries for each, or perhaps a single query that
>> returns
>>
>> { 'hostdev': some-object-with-host-device-properties-only, 'nic':
>> some-object-that-describes-the-guest-nic }
>
> We need a query-netdev and then info qdm already provides the guest nic
> properties.  Just filter out devices that have a netdev property.
>

How about this small draft:

Possible values for "type": tap, user, vde and socket. The 'info'
object contains all the parameters available via -netdev type,args.

Notice: vlan is still there, unless the support for it is removed, IMHO.

-> { "execute": "query-netdev" }
<- {
      "return": [
         {
            "device": "tap.0",
            "vlan": 0,
            "type": "tap",
            "info": {
               "script": "/etc/qemu-ifup",
               "downscript": "/etc/qemu-ifdown",
               "ifname": "tap0",
            },
         {
            "device": "user.0",
            "type": "user",
            "info": {
               "net": "10.0.2.0",
               "netmask": "255.255.255.0"
            },
         },

[Qemu-devel] Re: [RFC] QMP: Introduce query-netdevices documentation

[Anthony Liguori]

On 06/07/2010 09:41 AM, Miguel Di Ciurcio Filho wrote:
> On Mon, Jun 7, 2010 at 10:48 AM, Anthony Liguori<anthony@codemonkey.ws>  wrote:
>    
>>>> $ qemu -netdev tap,id=tap0 -device e1000,netdev=tap0
>>>>
>>>> This makes a 1:1 relation. So clearly tap0 is a host device, e1000.0
>>>> will be a guest device, and they are connected.
>>>>          
>>> Yes.  I'd want separate queries for each, or perhaps a single query that
>>> returns
>>>
>>> { 'hostdev': some-object-with-host-device-properties-only, 'nic':
>>> some-object-that-describes-the-guest-nic }
>>>        
>> We need a query-netdev and then info qdm already provides the guest nic
>> properties.  Just filter out devices that have a netdev property.
>>
>>      
> How about this small draft:
>
> Possible values for "type": tap, user, vde and socket. The 'info'
> object contains all the parameters available via -netdev type,args.
>
> Notice: vlan is still there, unless the support for it is removed, IMHO.
>    

'id' is missing.  Really, s/device/id/ is probably the right thing to do.

vlan's are a totally separate concept.  info netdev shouldn't return 
vlan devices IMHO.  We should have a separate info vlan command that 
shows the vlan topology.

Regards,

Anthony Liguori

> ->  { "execute": "query-netdev" }
> <- {
>        "return": [
>           {
>              "device": "tap.0",
>              "vlan": 0,
>              "type": "tap",
>              "info": {
>                 "script": "/etc/qemu-ifup",
>                 "downscript": "/etc/qemu-ifdown",
>                 "ifname": "tap0",
>              },
>           {
>              "device": "user.0",
>              "type": "user",
>              "info": {
>                 "net": "10.0.2.0",
>                 "netmask": "255.255.255.0"
>              },
>           },
>    

Re: [Qemu-devel] Re: [RFC] QMP: Introduce query-netdevices documentation

[Markus Armbruster]

Miguel Di Ciurcio Filho <miguel.filho@gmail.com> writes:

> On Mon, Jun 7, 2010 at 10:48 AM, Anthony Liguori <anthony@codemonkey.ws> wrote:
>>>>
>>>> $ qemu -netdev tap,id=tap0 -device e1000,netdev=tap0
>>>>
>>>> This makes a 1:1 relation. So clearly tap0 is a host device, e1000.0
>>>> will be a guest device, and they are connected.
>>>
>>> Yes.  I'd want separate queries for each, or perhaps a single query that
>>> returns
>>>
>>> { 'hostdev': some-object-with-host-device-properties-only, 'nic':
>>> some-object-that-describes-the-guest-nic }
>>
>> We need a query-netdev and then info qdm already provides the guest nic
>> properties.  Just filter out devices that have a netdev property.
>>
>
> How about this small draft:
>
> Possible values for "type": tap, user, vde and socket. The 'info'
> object contains all the parameters available via -netdev type,args.
>
> Notice: vlan is still there, unless the support for it is removed, IMHO.

Agreed.  As long as we have VLANs, we better cover them here.

> -> { "execute": "query-netdev" }
> <- {
>       "return": [
>          {
>             "device": "tap.0",
>             "vlan": 0,
>             "type": "tap",
>             "info": {
>                "script": "/etc/qemu-ifup",
>                "downscript": "/etc/qemu-ifdown",
>                "ifname": "tap0",
>             },

This one's connected to a VLAN, namely #0.  Any guest device on the same
VLAN has a "vlan" property with the value 0.

>          {
>             "device": "user.0",
>             "type": "user",
>             "info": {
>                "net": "10.0.2.0",
>                "netmask": "255.255.255.0"
>             },
>          },

And this one's not connected to a VLAN.  It may or may not be connected
to a single guest device.  If it is, then that device has a "netdev"
property pointing to it.

For what it's worth, "info network" shows that device as "peer=ID".

[Qemu-devel] Re: [RFC] QMP: Introduce query-netdevices documentation

[Avi Kivity]

On 06/07/2010 04:48 PM, Anthony Liguori wrote:
>> Yes.  I'd want separate queries for each, or perhaps a single query 
>> that returns
>>
>> { 'hostdev': some-object-with-host-device-properties-only, 'nic': 
>> some-object-that-describes-the-guest-nic }
>
>
> We need a query-netdev and then info qdm already provides the guest 
> nic properties.  Just filter out devices that have a netdev property.

Agreed, no reason for a specialized 
'get-all-guest-devices-that-happen-to-be-nics' query.

-- 
error compiling committee.c: too many arguments to function

[Qemu-devel] Re: [RFC] QMP: Introduce query-netdevices documentation

[Miguel Di Ciurcio Filho]

On Mon, Jun 7, 2010 at 11:48 AM, Anthony Liguori <anthony@codemonkey.ws> wrote:
>>
>> How about this small draft:
>>
>> Possible values for "type": tap, user, vde and socket. The 'info'
>> object contains all the parameters available via -netdev type,args.
>>
>> Notice: vlan is still there, unless the support for it is removed, IMHO.
>>
>
> 'id' is missing.  Really, s/device/id/ is probably the right thing to do.
>

Following this logic, shouldn't query-block do the same?

-> { "execute": "query-block" }
<- {
      "return":[
         {
            "device":"ide0-hd0",
            "locked":false,
            "removable":false,
            "inserted":{
               "ro":false,
               "drv":"qcow2",
               "encrypted":false,
               "file":"disks/test.img"
            },
            "type":"hd"
         },

I actually decided to use 'device' after looking at query-block, to
keep things more uniform. I'm just an student :-D

> vlan's are a totally separate concept.  info netdev shouldn't return vlan
> devices IMHO.  We should have a separate info vlan command that shows the
> vlan topology.
>

As Markus said, if qemu supports the old vlan thing, the information
should be there. The 'vlan' attribute will be optional in the
specification anyway.

A different command to list the devices grouped by vlan is indeed a good idea.

Regards,

Miguel

Re: [Qemu-devel] Re: [RFC] QMP: Introduce query-netdevices documentation

[Miguel Di Ciurcio Filho]

On Mon, Jun 7, 2010 at 12:01 PM, Markus Armbruster <armbru@redhat.com> wrote:
>>          {
>>             "device": "user.0",
>>             "type": "user",
>>             "info": {
>>                "net": "10.0.2.0",
>>                "netmask": "255.255.255.0"
>>             },
>>          },
>
> And this one's not connected to a VLAN.  It may or may not be connected
> to a single guest device.  If it is, then that device has a "netdev"
> property pointing to it.
>
> For what it's worth, "info network" shows that device as "peer=ID".

Yes, this information is important. Should I name it 'peer' or
'netdev'? I think 'peer' would be better, because the name 'netdev'
points to 'backend network device' IMHO.

Will it be better stored in the 'info' object or the device object? I
think it should go into the device object. There will be vlan or peer
or none of them in case the netdev is just there doing nothing (odd,
but still).

          {
             "device": "user.0",
             "type": "user",
             "peer": "e1000.0";
             "info": {
                "net": "10.0.2.0",
                "netmask": "255.255.255.0"
             },
          },

Regards,

Miguel