[dts] [PATCH v1 16/16] doc: add descriptions for multiple virtual machine module

[Marvin Liu <yong.liu@intel.com>]

Signed-off-by: Marvin Liu <yong.liu@intel.com>

diff --git a/doc/dts_gsg/index.rst b/doc/dts_gsg/index.rst
index 05587af..fbd16dc 100644
--- a/doc/dts_gsg/index.rst
+++ b/doc/dts_gsg/index.rst
@@ -41,3 +41,4 @@ Getting Started Guide
     review
     virtualization
     scenario
+    multiple_vm
diff --git a/doc/dts_gsg/multiple_vm.rst b/doc/dts_gsg/multiple_vm.rst
new file mode 100644
index 0000000..85eca26
--- /dev/null
+++ b/doc/dts_gsg/multiple_vm.rst
@@ -0,0 +1,87 @@
+Multiple Virtual Machines Management
+====================================
+
+When managing multiple virtual machines, waiting around 2 minutes for each VM will be exhausted. So DTS imported parallel threads model into multiple VMs management scenario.
+
+.. note::
+    Critical resources and actions which can't be handled in parallel have been protected by function level lock.
+
+Command arguments
+-----------------
+
+Multiple VMs module support start VMs or send commands to VMs in parallel with specified arguments format.
+
+Arguments for "start" command:
+
+.. table::
+
+    +-----------------+----------------------------------+----------------+-------------+
+    | name            | Description                      | Default value  | Must have   |
+    |                 |                                  |                |             |
+    +-----------------+----------------------------------+----------------+-------------+
+    | name            | virtual machine name             | N/A            | Yes         |
+    +-----------------+----------------------------------+----------------+-------------+
+    | dut_id          | index of DUT                     | 0              | No          |
+    +-----------------+----------------------------------+----------------+-------------+
+    | autodetect_topo | whether detect network topology  | False          | No          |
+    |                 | automatically                    |                |             |
+    +-----------------+----------------------------------+----------------+-------------+
+    | virt_config     | virtual machine config location  | N/A            | Alternative |
+    +-----------------+----------------------------------+----------------+-------------+
+    | virt_params     | local parameters of virutal      | N/A            | Alternative |
+    |                 | machine                          |                |             |
+    +-----------------+----------------------------------+----------------+-------------+
+
+Arguments for "cmd" command:
+
+.. table::
+
+    +-----------------+----------------------------------+----------------+-------------+
+    | name            | Description                      | Default value  | Must have   |
+    |                 |                                  |                |             |
+    +-----------------+----------------------------------+----------------+-------------+
+    | name            | virtual machine name             | N/A            | Yes         |
+    +-----------------+----------------------------------+----------------+-------------+
+    | dut_id          | index of DUT                     | 0              | No          |
+    +-----------------+----------------------------------+----------------+-------------+
+    | commands        | list of commands which will be   | N/A            | Yes         |
+    |                 | sent into the vitual machine     |                |             |
+    +-----------------+----------------------------------+----------------+-------------+
+    | expects         | list of expect output of the     | N/A            | Yes         |
+    |                 | commands                         |                |             |
+    +-----------------+----------------------------------+----------------+-------------+
+    | timeouts        | list of timeout value of the     | N/A            | Yes         |
+    |                 | commands                         |                |             |
+    +-----------------+----------------------------------+----------------+-------------+
+
+.. note::
+    If there's nothing expected for the command, still need to define expected string as blank
+
+Multiple module will catagorize and save the result value after all tasks have been done. Later users can retrieve the result by function get_parallel_result.
+
+Sample Code
+-----------
+
+.. code-block:: console
+
+    vm_task = MultipleVM(max_vm=self.VM_NUM, duts=self.duts)
+
+    for dut_id in range(len(self.duts)):
+        for vm_idx in range(VM_NUM):
+            vm_name = "vm%d" % vm_idx
+            args = {'name': vm_name,
+                    'dut_id': dut_id,
+                    'autodetect_topo': False,
+                    'virt_params': {
+                        'qemu': [{'path': '/usr/local/bin/qemu-system-x86_64'}],
+                        'cpu': [{'model': 'host', 'number': '1', 'cpupin': ''}],
+                        'mem': [{'size': '1024', 'hugepage': 'yes'}],
+                        'disk': [{'file': '/storage/vm-image/%s.qcow2' % vm_name}],
+                        'login': [{'user': 'root', 'password': 'root'}],
+                        'device': None}
+                    }
+
+            vm_task.add_parallel_task(action="start", config=args)
+
+    vm_task.do_parallel_task()
+    print vm_task.get_parallel_result()
diff --git a/doc/dts_gsg/virtualization.rst b/doc/dts_gsg/virtualization.rst
index 1848563..2328603 100644
--- a/doc/dts_gsg/virtualization.rst
+++ b/doc/dts_gsg/virtualization.rst
@@ -84,6 +84,15 @@ For network access, should disable guest firewall service.
 
     systemctl disable firewalld.service
 
+Console connection
+""""""""""""""""""
+
+Enable virtual machine serial console in kernel command line, DTS will manage virtual machine through serial port.
+
+.. code-block:: console
+
+   console=ttyS0,115200
+
 Suite Programing
 ----------------
 
@@ -310,34 +319,27 @@ Enable KVM
 
 DTS enable KVM full virtualization support as default. This option will significant improve the speed of virtual machine.
 
-Qemu Guest Agent
+Qemu Serial Port
 """"""""""""""""
 
-Qemu monitor supply one method to interact with qemu process. DTS can monitor guest status by command supplied by qemu guest agent. Qemu guest agent is based on virtio-serial devices. 
+Qemu serial port is the default method to interact with guest OS. DTS can monitor guest status/manage guest network by serial port.
 
 .. code-block:: console
 
-	-device virtio-serial -device virtserialport,chardev=vm_qga0,name=org.qemu.guest_agent.0 
-	-daemonize -monitor unix:/tmp/vm_monitor.sock,server,nowait
+    -serial telnet::7000,server,nowait
 
-Check whether guest os has been started up.
+DTS will check the output from serial port and determine whether guest os has been started up. The prompt string for guest login session can be configured by parameter "start".
 
 .. code-block:: console
 
-	qemu-ga-client address=/tmp/{vm_name}_qga0.sock ping 120
+    start =
+        wait_seconds=120,login_timeout=60,login_prompt=login:,password_prompt=Password:;
 
 .. note::	
 
-	We only wait two minutes for guest os start up. For guest os only has few hardware and we has disabled most services, so 2 minutes is enough.
-	This command will be return when guest os is ready, so DTS will not wait 2 minutes for each time. 
+	Default timeout for guest OS start up is 2 minutes. For guest os only has few hardware and we has disabled most services, so 2 minutes is enough. If guest OS can't start up in 2 minutes, DTS will try to restart it once.
 
-Check whether guest os default interface has been up.
-
-.. code-block:: console
-
-	qemu-ga-client address=/tmp/{vm_name}_qga0.sock ifconfig
-	
-DTS will wait for guest os default interface upped and get auto dhcp address. After that DTS can connect to guest by ssh connections. 
+DTS will check default interface upped and utilize dhcp to retrieve address. After that DTS can connect to guest by ssh connections.
 
 .. code-block:: console
 
@@ -349,15 +351,15 @@ DTS will wait for guest os default interface upped and get auto dhcp address. Af
 			inet6 fe80::200:ff:feb9:fed7  prefixlen 64
 			ether 00:00:00:b9:fe:d7
 
-Power down  guest os.
+Power down guest os by serial port.
 
 .. code-block:: console
 
-	qemu-ga-client address=/tmp/{vm_name}_qga0.sock powerdown
+    init 0
 	
 .. note::
 
-	For more information about qemu guest agent, please reference to http://wiki.qemu.org/Features/QAPI/GuestAgent.
+	For more information about qemu serial port, please reference to https://qemu.weilnetz.de/doc/qemu-doc.html.
 	
 Qemu Monitor
 """"""""""""
@@ -396,7 +398,7 @@ Connection to monitor socket on DUT.
     For More detail information about qemu monitor. https://en.wikibooks.org/wiki/QEMU/Monitor#info
 
 Qemu Machine
-""""""""""
+""""""""""""
 
 DTS set default qemu machine type as virt for Aarch64. This option is mandatory for qemu-system-aarch64.
 
-- 
1.9.3