docs: Emphasize that devices have to be inside the <devices> element

Also cleanup indentation of domain XML examples.

docs/formatdomain.html.in

@@ -28,8 +28,8 @@
 
     <h3><a name="elementsMetadata">General metadata</a></h3>
 
-    <pre>
+<pre>
-      &lt;domain type='xen' id='3'&gt;
+&lt;domain type='xen' id='3'&gt;
   &lt;name&gt;fv0&lt;/name&gt;
   &lt;uuid&gt;4dea22b31d52d8f32516782e98ab3fa0&lt;/uuid&gt;
   ...</pre>
@@ -66,7 +66,7 @@
       to obtain/find the boot image.
     </p>
 
-    <pre>
+<pre>
   ...
   &lt;os&gt;
     &lt;type&gt;hvm&lt;/type&gt;
@@ -109,7 +109,7 @@
       An example is <code>pygrub</code> with Xen.
     </p>
 
-    <pre>
+<pre>
   ...
   &lt;bootloader&gt;/usr/bin/pygrub&lt;/bootloader&gt;
   &lt;bootloader_args&gt;--append single&lt;/bootloader_args&gt;
@@ -139,7 +139,7 @@
       is usually available for both para and full virtualized guests.
     </p>
 
-    <pre>
+<pre>
   ...
   &lt;os&gt;
     &lt;type&gt;hvm&lt;/type&gt;
@@ -172,7 +172,7 @@
 
     <h3><a name="elementsResources">Basic resources</a></h3>
 
-    <pre>
+<pre>
   ...
   &lt;memory&gt;524288&lt;/memory&gt;
   &lt;currentMemory&gt;524288&lt;/currentMemory&gt;
@@ -209,7 +209,7 @@
       <span class="since">Since 0.7.5</span>
     </p>
 
-    <pre>
+<pre>
   ...
   &lt;cpu match='exact'&gt;
     &lt;model&gt;core2duo&lt;/model&gt;
@@ -224,7 +224,7 @@
       <span class="since">Since 0.7.6</span>
     </p>
 
-    <pre>
+<pre>
   ...
   &lt;cpu&gt;
     &lt;topology sockets='1' cores='2' threads='1'/&gt;
@@ -305,7 +305,7 @@
       re-configured for the first post-install bootup.
     </p>
 
-    <pre>
+<pre>
   ...
   &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
   &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
@@ -350,7 +350,7 @@
       toggled on/off.
     </p>
 
-    <pre>
+<pre>
   ...
   &lt;features&gt;
     &lt;pae/&gt;
@@ -386,7 +386,7 @@
       it to be in so called 'localtime'.
     </p>
 
-    <pre>
+<pre>
   ...
   &lt;clock offset="localtime"/&gt;
   ...</pre>
@@ -408,10 +408,11 @@
       <span class="since">Since 0.1.3</span>
     </p>
 
-    <pre>
+<pre>
   ...
   &lt;devices&gt;
     &lt;emulator&gt;/usr/lib/xen/bin/qemu-dm&lt;/emulator&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -433,8 +434,9 @@
       element.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;disk type='file'&gt;
       &lt;driver name="tap" type="aio" cache="default"&gt;
       &lt;source file='/var/lib/xen/images/fv0'/&gt;
@@ -444,6 +446,7 @@
       &lt;/encryption&gt;
       &lt;shareable/&gt;
     &lt;/disk&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -500,23 +503,29 @@
       0.4.4 for USB and 0.6.0 for PCI (KVM only)</span>:
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;hostdev mode='subsystem' type='usb'&gt;
       &lt;source&gt;
         &lt;vendor id='0x1234'/&gt;
         &lt;product id='0xbeef'/&gt;
       &lt;/source&gt;
     &lt;/hostdev&gt;
+  &lt;/devices&gt;
   ...</pre>
+
     <p>or:</p>
-    <pre>
+
+<pre>
   ...
+  &lt;devices&gt;
     &lt;hostdev mode='subsystem' type='pci'&gt;
       &lt;source&gt;
         &lt;address bus='0x06' slot='0x02' function='0x0'/&gt;
       &lt;/source&gt;
     &lt;/hostdev&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -556,13 +565,15 @@
 
     <h4><a name="elementsNICS">Network interfaces</a></h4>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='bridge'&gt;
       &lt;source bridge='xenbr0'/&gt;
       &lt;mac address='00:16:3e:5d:c7:9e'/&gt;
       &lt;script path='vif-bridge'/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSVirtual">Virtual network</a></h5>
@@ -589,8 +600,9 @@
       <a href="#elementsNICSTargetOverride">overriding the target element</a>).
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='network'&gt;
       &lt;source network='default'/&gt;
     &lt;/interface&gt;
@@ -600,6 +612,7 @@
       &lt;target dev='vnet7'/&gt;
       &lt;mac address="11:22:33:44:55:66"/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSBridge">Bridge to LAN</a></h5>
@@ -623,17 +636,19 @@
       full incoming &amp; outgoing net access just like a physical machine.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='bridge'&gt;
       &lt;source bridge='br0'/&gt;
     &lt;/interface&gt;
-
+    ...
     &lt;interface type='bridge'&gt;
       &lt;source bridge='br0'/&gt;
       &lt;target dev='vnet7'/&gt;
       &lt;mac address="11:22:33:44:55:66"/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSSlirp">Userspace SLIRP stack</a></h5>
@@ -647,13 +662,15 @@
       VMs to have outgoing access.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='user'/&gt;
     ...
     &lt;interface type='user'&gt;
       &lt;mac address="11:22:33:44:55:66"/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
 
@@ -669,14 +686,16 @@
       overridden.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='ethernet'/&gt;
     ...
     &lt;interface type='ethernet'&gt;
       &lt;target dev='vnet7'/&gt;
       &lt;script path='/etc/qemu-ifup-mynet'/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSMulticast">Multicast tunnel</a></h5>
@@ -693,11 +712,13 @@
       multicast address block.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='mcast'&gt;
       &lt;source address='230.0.0.1' port='5558'/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSTCP">TCP tunnel</a></h5>
@@ -711,8 +732,9 @@
       network access, one of the VMs should have a 2nd NIC which is connected
       to one of the first 4 network types and do the appropriate routing.</p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='server'&gt;
       &lt;source address='192.168.0.1' port='5558'/&gt;
     &lt;/interface&gt;
@@ -720,17 +742,20 @@
     &lt;interface type='client'&gt;
     &lt;source address='192.168.0.1' port='5558'/&gt;
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h5><a name="elementsNICSModel">Setting the NIC model</a></h5>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='network'&gt;
       &lt;source network='default'/&gt;
       &lt;target dev='vnet1'/&gt;
       <b>&lt;model type='ne2k_pci'/&gt;</b>
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -757,12 +782,14 @@ qemu-kvm -net nic,model=? /dev/null
 
     <h5><a name="elementsNICSTargetOverride">Overriding the target element</a></h5>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;interface type='network'&gt;
       &lt;source network='default'/&gt;
       <b>&lt;target dev='vnet1'/&gt;</b>
     &lt;/interface&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -783,9 +810,11 @@ qemu-kvm -net nic,model=? /dev/null
       to provide a graphics tablet for absolute cursor movement.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;input type='mouse' bus='usb'/&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -807,12 +836,14 @@ qemu-kvm -net nic,model=? /dev/null
       admin.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;graphics type='sdl' display=':0.0'/&gt;
     &lt;graphics type='vnc' port='5904'/&gt;
     &lt;graphics type='rdp' autoport='yes' multiUser='yes' /&gt;
     &lt;graphics type='desktop' fullscreen='yes'/&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -867,13 +898,15 @@ qemu-kvm -net nic,model=? /dev/null
       A video device.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;video&gt;
       &lt;model type='vga' vram='8192' heads='1'&gt;
         &lt;acceleration accel3d='yes' accel3d='yes'/&gt;
       &lt;/model&gt;
     &lt;/video&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -907,8 +940,9 @@ qemu-kvm -net nic,model=? /dev/null
       all classed as character devices and so represented using the same syntax.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;parallel type='pty'&gt;
       &lt;source path='/dev/pts/2'/&gt;
       &lt;target port='0'/&gt;
@@ -926,7 +960,7 @@ qemu-kvm -net nic,model=? /dev/null
       &lt;target type='guestfwd' address='10.0.2.1' port='4600'/&gt;
     &lt;/channel&gt;
   &lt;/devices&gt;
-      &lt;/domain&gt;</pre>
+  ...</pre>
 
     <p>
       In each of these directives, the top-level element name (parallel, serial,
@@ -949,12 +983,14 @@ qemu-kvm -net nic,model=? /dev/null
 
     <h6><a name="elementCharParallel">Parallel port</a></h6>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;parallel type='pty'&gt;
       &lt;source path='/dev/pts/2'/&gt;
       &lt;target port='0'/&gt;
     &lt;/parallel&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -965,12 +1001,14 @@ qemu-kvm -net nic,model=? /dev/null
 
     <h6><a name="elementCharSerial">Serial port</a></h6>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type='pty'&gt;
       &lt;source path='/dev/pts/3'/&gt;
       &lt;target port='0'/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -987,12 +1025,14 @@ qemu-kvm -net nic,model=? /dev/null
       virtualized guests without a paravirtualized console.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;console type='pty'&gt;
       &lt;source path='/dev/pts/4'/&gt;
       &lt;target port='0'/&gt;
     &lt;/console&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -1008,12 +1048,14 @@ qemu-kvm -net nic,model=? /dev/null
       guest.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;channel type='unix'&gt;
       &lt;source mode='bind' path='/tmp/guestfwd'/&gt;
       &lt;target type='guestfwd' address='10.0.2.1' port='4600'/&gt;
     &lt;/channel&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -1045,11 +1087,13 @@ qemu-kvm -net nic,model=? /dev/null
       into the virtual machine's logfile
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;console type='stdio'&gt;
       &lt;target port='1'&gt;
     &lt;/console&gt;
+  &lt;/devices&gt;
   ...</pre>
 
 
@@ -1060,12 +1104,14 @@ qemu-kvm -net nic,model=? /dev/null
       device is written to the file.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="file"&gt;
       &lt;source path="/var/log/vm/vm-serial.log"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharVC">Virtual console</a></h6>
@@ -1076,11 +1122,13 @@ qemu-kvm -net nic,model=? /dev/null
       hotkey sequence such as "ctrl+alt+3"
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type='vc'&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharNull">Null device</a></h6>
@@ -1090,11 +1138,13 @@ qemu-kvm -net nic,model=? /dev/null
       provided to the input. All data written is discarded.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type='null'&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharPTY">Pseudo TTY</a></h6>
@@ -1105,12 +1155,14 @@ qemu-kvm -net nic,model=? /dev/null
       serial port locally.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="pty"&gt;
       &lt;source path="/dev/pts/3"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
@@ -1130,12 +1182,14 @@ qemu-kvm -net nic,model=? /dev/null
       port.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="dev"&gt;
       &lt;source path="/dev/ttyS0"/&gt;
       &lt;target port="1"/&gt;
   &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharPipe">Named pipe</a></h6>
@@ -1145,12 +1199,14 @@ qemu-kvm -net nic,model=? /dev/null
       more info.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="pipe"&gt;
       &lt;source path="/tmp/mypipe"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharTCP">TCP client/server</a></h6>
@@ -1160,34 +1216,39 @@ qemu-kvm -net nic,model=? /dev/null
       remote server.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="tcp"&gt;
       &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
       &lt;protocol type="raw"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
    ...</pre>
 
     <p>
       Or as a TCP server waiting for a client connection.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="tcp"&gt;
       &lt;source mode="bind" host="127.0.0.1" service="2445"/&gt;
       &lt;protocol type="raw"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <p>
       Alternatively you can use telnet instead of raw TCP.
     <p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="tcp"&gt;
       &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
       &lt;protocol type="telnet"/&gt;
@@ -1199,6 +1260,7 @@ qemu-kvm -net nic,model=? /dev/null
       &lt;protocol type="telnet"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharUDP">UDP network console</a></h6>
@@ -1208,13 +1270,15 @@ qemu-kvm -net nic,model=? /dev/null
       sending and receiving packets. This is a lossy service.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="udp"&gt;
       &lt;source mode="bind" host="0.0.0.0" service="2445"/&gt;
       &lt;source mode="connect" host="0.0.0.0" service="2445"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <h6><a name="elementsCharUNIX">UNIX domain socket client/server</a></h6>
@@ -1224,12 +1288,14 @@ qemu-kvm -net nic,model=? /dev/null
       accepting connections from local clients.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;serial type="unix"&gt;
       &lt;source mode="bind" path="/tmp/foo"/&gt;
       &lt;target port="1"/&gt;
     &lt;/serial&gt;
+  &lt;/devices&gt;
   ...</pre>
 
 
@@ -1240,9 +1306,11 @@ qemu-kvm -net nic,model=? /dev/null
       <code>sound</code> element. <span class="since">Since 0.4.3</span>
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;sound model='es1370'/&gt;
+  &lt;/devices&gt;
   ...</pre>
 
     <dl>
@@ -1276,15 +1344,19 @@ qemu-kvm -net nic,model=? /dev/null
       libvirt.
     </p>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;watchdog model='i6300esb'/&gt;
+  &lt;/devices&gt;
   ...</pre>
 
-    <pre>
+<pre>
   ...
+  &lt;devices&gt;
     &lt;watchdog model='i6300esb' action='poweroff'/&gt;
-      ...</pre>
+  &lt;/devices&gt;
+&lt;/domain&gt;</pre>
 
     <dl>
       <dt><code>model</code></dt>