VLAN ID Support For Virtual Interface Of DomU
(
 Please read design document for bandwidth limit ('bwlimit') support first:
 http://sac.eng/Archives/CaseLog/arc/PSARC/2009/137/spec/design.bw.txt
)

1. Overview

Associating a VLAN ID to an interface serving as a back end device for a domU
has been highly desired in that it can separate the domU's network traffic from
each other, and from the dom0's traffic.  Thus, each traffic can be managed more
precisely and easily and dom0/domU can get more protection.

After Crossbow's integration into Nevada, it's possible to support specifying
VLAN ID while setting up a VNIC as back end NIC device attached to a domU from
within Solaris dom0 by issuing appropriate dladm command.  So, in this design,
we plan to take this approach to support a few ways to specify VLAN ID for a
specific virtual NIC device attached to a domU from within Solaris dom0:
+ Through domU configuration file:
	- XML format used by virsh
	- simple '.py' format used by xm
+ Through command line
	- 'virsh attach-interface'
	- 'xm network-attach'
	- 'virt-install'

Similar with supporting specifying bandwidth limit for a virtual NIC interface
used by a domU, we need to accept and parse VLAN ID input from command line or
configuration file and put it into xenstore for vif-vnic script to read which
will issue appropriate dladm command to set up the VNIC as the corresponding
back end device (see the code flow graph in 'bwlimit' document.

I will discuss more about each part in detail below.

2. Handle VLAN ID in vif-vnic

The changes in vif-vnic to handle VLAN ID is quite straightforward.  Vif-vnic
will read VLAN ID from xenstore and pass it to dladm command when creating the
corresponding VNIC (using -v option in dladm) as backend device for the domU.

3. Passing VLAN ID to xend

We plan to support a few ways to specify VLAN ID by end user, which are
discussed as below.

3.1 Support VLAN ID in xend

Unfortunately, xend does not have any knowledge about VLAN ID configuration.  In
order to be able to pass VLAN ID to xend, we need to teach xend to understand it
first.  We create a property named 'vlanid' to represent VLAN ID in a
configuration of a virtual interface and modify xend to be able to parse it.
Once it is parsed in xend correctly, xend will write it into xenstore as
"vlanid = 'vid'".

To be specific, in xend, this property along with all other properties for a
virtual interface is handled by NetifController class defined in
xen/xend/server/netif.py.  In NetifController, getDeviceDetails() is responsible
for parsing configuration list to get every configuration properties for a
virtual interface, which will finally be written to xenstore.  And
getDeviceConfiguration() is responsible for reading configuration from xenstore
to get every configuration properties, which will probably be passed out of xend
later.

So, we need to modify both getDeviceDetails() and getDeviceConfiguration() to
handle 'vlanid' property correctly.

3.2 In '.py' file

Once xend can parse 'vlanid' properly, we can easily add 'vlanid' property into
'.py' file to pass VLAN ID to xend like below:
vif = [ 'bridge=bge0,vlanid=1' ]

(see 'bwlimit' for how '.py' file are processed by xm command)
We need to modify configure_vifs() in xen/xm/create.py to parse the virtual
interface configuration specified in '.py' file.

3.3 In 'xm network-attach' command line

In order to support specifying VLAN ID in 'xm network-attach' command line, we
need to extend the current command line syntax to add 'vlanid' option:
vlanid=<vid>
When hotplug a virtual NIC device using 'xm network-attach', user can specify
VLAN ID like below:
# xm network-attach domu vlanid=1

(see 'bwlimit' for how 'xm network-attach' options are processed by xm command)
We need to modify xm_network_attach() in xen/xm/main.py to parse 'vlanid' option
correctly.

3.4 In XML file

3.4.1 SXP format

With the change in 3.2, 'vlanid' property can be automatically presented in SXP
by xend as below:
    (device
        (vif
            (bridge e1000g1)
            (mac 00:16:3e:56:a1:01)
            (vlanid 1)         <== VLAN ID
        )
    )
(see 'bwlimit' for more information about SXP file)

3.4.2 XML format

Unfortunately, the current implementation of virt-install/virsh/libvirt does
not support specifying VLAN ID for a virtual interface in XML format.
We have to define the format and change the code to make them understand it.

In order to insert VLAN ID into XML file, we create a new element, "vlan", and
set VLAN ID as one attribute of 'vlan' like below:
    <interface type='bridge'>
      <source bridge='e1000g1'/>
      <vlan id='1'/>            <== VLAN ID
    </interface>

3.4.3 Convert between XML and SXP

Since xend only understands SXP format, virtd is doing conversion between
XML format and SXP format as appropriate already.  So, in order to
support specifying VLAN ID in XML format, we just need to insert the
parsing and conversion code to existing virtd implementation to do
the conversion appropriately.

3.4.3.1 From XML to SXP

(see 'bwlimit' for how XML to SXP conversion is done in virtd)
we need to modify virDomainParseXMLIfDesc() for virtd to understand our
new element, "vlan", and convert it to SXP format for xend to parse.

3.4.3.2 From SXP to XML

(see 'bwlimit' for how SXP to XML conversion is done in virtd)
We need to modify xend_parse_sexp_desc() to make it understand 'vlanid' property
in SXP format and convert it to XML format for 'virsh dumpxml' to work properly.

3.5 In 'virsh attach-interface' command line

Since we can add a virtual NIC device via 'virsh attach-interface', we also want
to support specifying VLAN ID in this way.

3.5.1 Command line syntax for 'virsh attach-interface'

The first thing to do is to allow specifying VLAN ID in 'virsh attach-
interface' command line.  We need to extend the existing command line syntax as
below:
virsh attach-interface <domain> <type> <source> [--target <target>]
[--mac <mac>] [--script <script>] [--vlanid <vid>]
So that we are able to specify VLAN ID as "--vlanid 1" in command line, like:
# virsh attach-interface domu bridge bge0 --vlanid 1

To to this, we need to modify info_attach_interface and opts_attach_interface
in virsh.c to extend the command line interface appropriately.

3.5.2 Handle 'vlanid' option in virsh

(see 'bwlimit' for how 'virsh attach-interface' options are processed)
Since we have modified virDomainParseXMLIfDesc() in 3.4.3.1 to support
conversion from XML format to SXP format, the only work we need to do here is to
change cmdAttachInterface() to produce XML string describing the nic device with
VLAN ID information correctly.

3.6 In 'virt-install' command line

It is highly desired that users can specify VLAN ID for a virtual interface from
the beginning - during the installation of the domU.  Since we use virt-install
to install domU, we need to provide a well defined way to specify VLAN ID in
virt-install command line.

3.6.1 Command line syntax for virt-install

In order to support specifying VLAN ID during installation of a domU by
virt-install, we need to extend virt-install's command line syntax.  

We add one more property to '-w/--network' option named 'vlanid', like below:
# virt-install ...-w vlanid=1,mac=...
(see 'bwlimit' for more information about the new syntax of '-w/--network'
option of virt-install)

3.6.2 Handle new syntax in virt-install

(see 'bwlimit' for how the network related options are handled in virt-install)
Our work here is to change digest_networks(), get_network(), and specific
get_xml_config() for nic device to eventually make 'vlanid' property be
translated into correct XML format as discussed in 3.4.2.