[libvirt] [libvirt-virshcmdref 01/14] update documentation for command attach-device

[Hu Tao]

---
 source/attach-device.xml |  143 ++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 137 insertions(+), 6 deletions(-)

diff --git a/source/attach-device.xml b/source/attach-device.xml
index efa46f0..18e3262 100644
--- a/source/attach-device.xml
+++ b/source/attach-device.xml
@@ -5,20 +5,151 @@
 
   <description>
     <text>
-      Attach device from an XML file
+      Attach a device from an XML file
     </text>
   </description>
 
-  <options />
+  <options>
+    <parameter requirement="required">
+      <keyword requirement="optional">--domain</keyword>
+      <value type="string" requirement="required">domain</value>
+      <description>
+        <text>
+          domain name, id or uuid
+        </text>
+        <text>
+          "--domain" itself is optional
+        </text>
+      </description>
+    </parameter>
+    <parameter requirement="required">
+      <keyword requirement="optional">--file</keyword>
+      <value type="string" requirement="required">file</value>
+      <description>
+        <text>
+          the XML file describing the device to be attached
+        </text>
+        <text>
+          "--file" itself is optional
+        </text>
+      </description>
+    </parameter>
+    <parameter requirement="optional">
+      <keyword requirement="required">--persistent</keyword>
+      <description>
+        <text>
+          with this option, the XML file of domain will be updated
+        </text>
+      </description>
+    </parameter>
+  </options>
 
   <availability from="0.2.3" />
  
   <notes />
  
-  <examples type="usage" />
+  <examples type="usage">
+    <example>
+      <terminal>
+virsh # <bold>attach-device</bold> <value>example-domain</value> <value>/tmp/new-nic.xml</value></terminal>
+      <text>
+        Attaches a NIC which is defined by <value>/tmp/new-nic.xml</value> to domain <value>example-domain</value>.
+      </text>
+    </example>
+  </examples>
 
-  <examples type="fullcontext" />
-
-  <reference type="seealso" />
+  <examples type="fullcontext">
+    <example>
+      <text>
+        In this example we will attach a NIC to a running domain which doesn't have a NIC.
+        The domain is defined as:
+      </text>
+      <terminal>
+<domain type='kvm'>
+  <name>example-domain</name>
+  <uuid>6853c36f-af03-4968-a31d-1f3a9c3f699a</uuid>
+  <memory>1048576</memory>
+  <currentMemory>1048576</currentMemory>
+  <vcpu>1</vcpu>
+  <os>
+    <type arch='x86_64' machine='pc-0.12'>hvm</type>
+    <boot dev='hd'/>
+  </os>
+  <features>
+    <acpi/>
+    <apic/>
+    <pae/>
+  </features>
+  <clock offset='utc'/>
+  <on_poweroff>destroy</on_poweroff>
+  <on_reboot>restart</on_reboot>
+  <on_crash>restart</on_crash>
+  <devices>
+    <emulator>/usr/local/bin/qemu-system-x86_64</emulator>
+    <disk type='file' device='disk'>
+      <driver name='qemu' type='raw' cache='writeback'/>
+      <source file='/mnt/data/libvirt-images/vm2.img'/>
+      <target dev='vda' bus='virtio'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x04' function='0x0'/>
+    </disk>
+    <input type='mouse' bus='ps2'/>
+    <graphics type='vnc' port='-1' autoport='yes'/>
+    <video>
+      <model type='cirrus' vram='9216' heads='1'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0'/>
+    </video>
+    <memballoon model='virtio'>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x0'/>
+    </memballoon>
+  </devices>
+</domain></terminal>
+      <text>
+        Bring up the domain. From the output of <value>lspci</value> we can see that there is no NIC
+        present.
+      </text>
+      <terminal>00:00.0 Host bridge: Intel Corporation 440FX - 82441FX PMC [Natoma] (rev 02)
+00:01.0 ISA bridge: Intel Corporation 82371SB PIIX3 ISA [Natoma/Triton II]
+00:01.1 IDE interface: Intel Corporation 82371SB PIIX3 IDE [Natoma/Triton II]
+00:01.2 USB Controller: Intel Corporation 82371SB PIIX3 USB [Natoma/Triton II] (rev 01)
+00:01.3 Bridge: Intel Corporation 82371AB/EB/MB PIIX4 ACPI (rev 03)
+00:02.0 VGA compatible controller: Cirrus Logic GD 5446
+00:03.0 RAM memory: Red Hat, Inc Virtio memory balloon
+00:04.0 SCSI storage controller: Red Hat, Inc Virtio block device</terminal>
+      <text>
+        Now we attach a NIC to the domain:
+      </text>
+      <terminal>virsh # <bold>attach-device</bold> <value>example-domain</value> <value>/tmp/new-nic.xml</value></terminal>
+      <text>
+        the content of <value>/tmp/new-nic.xml</value> is:
+      </text>
+      <terminal>
+<interface type='network'>
+  <source network='default'/>
+</interface></terminal>
+      <text>
+        We can see that the attached NIC is listed by <value>lspci</value>:
+      </text>
+      <terminal>00:00.0 Host bridge: Intel Corporation 440FX - 82441FX PMC [Natoma] (rev 02)
+00:01.0 ISA bridge: Intel Corporation 82371SB PIIX3 ISA [Natoma/Triton II]
+00:01.1 IDE interface: Intel Corporation 82371SB PIIX3 IDE [Natoma/Triton II]
+00:01.2 USB Controller: Intel Corporation 82371SB PIIX3 USB [Natoma/Triton II] (rev 01)
+00:01.3 Bridge: Intel Corporation 82371AB/EB/MB PIIX4 ACPI (rev 03)
+00:02.0 VGA compatible controller: Cirrus Logic GD 5446
+00:03.0 RAM memory: Red Hat, Inc Virtio memory balloon
+00:04.0 SCSI storage controller: Red Hat, Inc Virtio block device
+00:05.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL-8139/8139C/8139C+ (rev 20)</terminal>
+    </example>
+  </examples>
 
+  <reference type="seealso">
+    <item>
+      <link type="internal" href="detach-device" />
+      <name>
+        detach-device
+      </name>
+      <description>
+        Detach a device from an XML file
+      </description>
+    </item>
+  </reference>
 </command>
-- 
1.7.3.1