From 5c0e525c1c9c46bd4ced20385b4502a8ef642024 Mon Sep 17 00:00:00 2001
From: Stefan Berger <stefanb@us.ibm.com>
Date: Fri, 5 Mar 2010 15:41:38 +0100
Subject: [PATCH] web docs -- macvtap mode explanation

This adds more information about the different macvtap device modes,
spells out VEPA and adds a link to a pdf at the ieee site.
---
 docs/formatdomain.html.in | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 14d237198a..9041cc6a50 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -742,11 +742,34 @@
     <p>
       Provides direct attachment of the virtual machine's NIC to the given
       physial interface of the host. This setup requires the Linux macvtap
-      driver to be available. One of the modes 'vepa', 'bridge' or 'private'
+      driver to be available. One of the modes 'vepa'
+      ( <a href="http://www.ieee802.org/1/files/public/docs2009/new-evb-congdon-vepa-modular-0709-v01.pdf">
+      'Virtual  Ethernet Port Aggregator'</a>), 'bridge' or 'private'
       can be chosen for the operation mode of the macvtap device, 'vepa'
-      being the default mode.
+      being the default mode. The individual modes cause the delivery of
+      packets to behave as follows:
     </p>
 
+    <dl>
+      <dt><code>vepa</code></dt>
+      <dd>All VMs' packets are sent to the external bridge. Packets
+      whose destination is a VM on the same host as where the
+      packet originates from are sent back to the host by the VEPA
+      capable bridge (today's bridges are typically not VEPA capable).</dd>
+      <dt><code>bridge</code></dt>
+      <dd>Packets whose destination is on the same host as where they
+      originate from are directly delivered to the target macvtap device.
+      Both origin and destination devices need to be in bridge mode
+      for direct delivery. If either one of them is in <code>vepa</code> mode,
+      a VEPA capable bridge is required.
+      <dt><code>private</code></dt>
+      <dd>All packets are sent to the external bridge and will only be
+      delivered to a target VM on the same host if they are sent through an
+      external router or gateway and that device sends them back to the
+      host. This procedure is followed if either the source or destination
+      device is in <code>private</code> mode.</dd>
+    </dl>
+
 <pre>
   ...
   &lt;devices&gt;