doc: reorganize HLD docs

Reorganize the high-level design docs to align with a work-in-progress
HLD document.  Migrate previous web content (and images) into the new
organization.

From here we'll continue inclusion of new design chapters as they're
reviewed and edited.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

doc/developer-guides/hld/acpi-virt.rst

@@ -1,4 +1,4 @@
-.. _ACPI-virt-HLD:
+.. _acpi-virt-HLD:
 
 ACPI Virtualization high-level design
 #####################################

doc/developer-guides/hld/hld-devicemodel.rst

@@ -0,0 +1,10 @@
+.. _hld-devicemodel:
+
+Device Model high-level design
+##############################
+
+
+.. toctree::
+   :maxdepth: 1
+
+   ACPI virtualization <acpi-virt>

doc/developer-guides/hld/hld-emulated-devices.rst

@@ -0,0 +1,11 @@
+.. _hld-emulated-devices:
+
+Emulated Devices high-level design
+##################################
+
+.. toctree::
+   :maxdepth: 1
+
+   GVT-g GPU Virtualization <hld-APL_GVT-g>
+   UART virtualization <uart-virt-hld>
+   Watchdoc virtualization <watchdog-hld>

doc/developer-guides/hld/hld-hypervisor.rst

@@ -0,0 +1,11 @@
+.. _hld-hypervisor:
+
+Hypervisor high-level design
+############################
+
+
+.. toctree::
+   :maxdepth: 1
+
+   Memory management <memmgt-hld>
+   Interrupt management <interrupt-hld>

doc/developer-guides/hld/hld-overview.rst

@@ -0,0 +1,4 @@
+.. _hld-overview:
+
+Overview
+########

doc/developer-guides/hld/hld-power-management.rst

@@ -0,0 +1,4 @@
+.. _hld-power-management:
+
+Power Management high-level design
+##################################

doc/developer-guides/hld/hld-security.rst

@@ -1,4 +1,4 @@
-.. _security-hld:
+.. _hld-security:
 
 Security high-level design
 ##########################

doc/developer-guides/hld/hld-trace-log.rst

@@ -0,0 +1,4 @@
+.. _hld-trace-log:
+
+Tracing and Logging high-level design
+#####################################

doc/developer-guides/hld/hld-vm-management.rst

@@ -0,0 +1,4 @@
+.. _hld-vm-management:
+
+VM Management high-level design
+###############################

doc/developer-guides/hld/hld-vsbl.rst

@@ -0,0 +1,4 @@
+.. _hld-vsbl:
+
+Virtual Slim-Bootloader high-level design
+#########################################

doc/developer-guides/hld/index.rst

@@ -0,0 +1,28 @@
+.. _hld:
+
+High-Level Design Guides
+########################
+
+The ACRN Hypervisor acts as a host with full control of the processor(s)
+and the hardware (physical memory, interrupt management and I/O). It
+provides the User OS with an abstraction of a virtual platform, allowing
+the guest to behave as if were executing directly on a logical
+processor.
+
+These chapters describe the ACRN architecture, high-level design,
+background, and motivation for specific areas within the ACRN hypervisor
+system.
+
+.. toctree::
+   :maxdepth: 1
+
+   Overview <hld-overview>
+   Hypervisor <hld-hypervisor>
+   Device Model <hld-devicemodel>
+   Emulated Devices <hld-emulated-devices>
+   Virtio Devices <hld-virtio-devices>
+   VM Management <hld-vm-management>
+   Power Management <hld-power-management>
+   Tracing and Logging <hld-trace-log>
+   Virtual Bootloader <hld-vsbl>
+   Security <hld-security>

doc/developer-guides/hld/virtio-blk.rst

@@ -0,0 +1,107 @@
+.. _virtio-blk:
+
+Virtio-blk
+##########
+
+The virtio-blk device is a simple virtual block device. The FE driver
+(in the UOS space) places read, write, and other requests onto the
+virtqueue, so that the BE driver (in the SOS space) can process them
+accordingly.  Communication between the FE and BE is based on the virtio
+kick and notify mechanism.
+
+The virtio device ID of the virtio-blk is ``2``, and it supports one
+virtqueue, the size of which is 64, configurable in the source code.
+
+.. figure:: images/virtio-blk-image01.png
+   :align: center
+   :width: 900px
+   :name: virtio-blk-arch
+
+   Virtio-blk architecture
+
+The feature bits supported by the BE device are shown as follows:
+
+``VIRTIO_BLK_F_SEG_MAX``
+  Maximum number of segments in a request is in seg_max.
+``VIRTIO_BLK_F_BLK_SIZE``
+  Block size of disk is in blk_size.
+``VIRTIO_BLK_F_TOPOLOGY``
+  Device exports information on optimal I/O alignment.
+``VIRTIO_RING_F_INDIRECT_DESC``
+  Support for indirect descriptors
+``VIRTIO_BLK_F_FLUSH``
+  Cache flush command support.
+``VIRTIO_BLK_F_CONFIG_WCE``
+  Device can toggle its cache between writeback and writethrough modes.
+
+
+Virtio-blk-BE design
+********************
+
+.. figure:: images/virtio-blk-image02.png
+   :align: center
+   :width: 900px
+   :name: virtio-blk-be
+
+The virtio-blk BE device is implemented as a legacy virtio device. Its
+backend media could be a file or a partition. The virtio-blk device
+supports writeback and writethrough cache mode. In writeback mode,
+virtio-blk has good write and read performance. To be safer,
+writethrough is set as the default mode, as it can make sure every write
+operation queued to the virtio-blk FE driver layer is submitted to
+hardware storage.
+
+During initialization, virito-blk will allocate 64 ioreq buffers in a
+shared ring used to store the I/O requests.  The freeq, busyq, and pendq
+shown in :numref:`virtio-blk-be` are used to manage requests. Each
+virtio-blk device starts 8 worker threads to process request
+asynchronously.
+
+
+Usage:
+******
+
+The device model configuration command syntax for virtio-blk is::
+
+   -s <slot>,virtio-blk,<filepath>[,options]
+
+- ``filepath`` is the path of a file or disk partition
+- ``options`` include:
+
+  - ``writethru``: write operation is reported completed only when the
+    data has been written to physical storage.
+  - ``writeback``: write operation is reported completed when data is
+    placed in the page cache. Needs to be flushed to the physical storage.
+  - ``ro``: open file with readonly mode.
+  - ``sectorsize``: configured as either
+    ``sectorsize=<sector size>/<physical sector size>`` or
+    ``sectorsize=<sector size>``.
+    The default values for sector size and physical sector size are 512
+  - ``range``: configured as ``range=<start lba in file>/<sub file size>``
+    meaning the virtio-blk will only access part of the file, from the
+    ``<start lba in file>`` to ``<start lba in file> + <sub file site>``.
+
+A simple example for virtio-blk:
+
+1. Prepare a file in SOS folder::
+
+      dd if=/dev/zero of=test.img bs=1M count=1024
+      mkfs.ext4 test.img
+
+#. Add virtio-blk in the DM cmdline, slot number should not duplicate
+   another device::
+
+      -s 9,virtio-blk,/root/test.img
+
+#. Launch UOS, you can find ``/dev/vdx`` in UOS.
+
+   The ``x`` in ``/dev/vdx`` is related to the slot number used.  If
+   If you start DM with two virtio-blks, and the slot numbers are 9 and 10,
+   then, the device with slot 9 will be recognized as ``/dev/vda``, and
+   the device with slot 10 will be ``/dev/vdb``
+
+#. Mount ``/dev/vdx`` to a folder in the UOS, and then you can access it.
+
+
+Successful booting of the User OS verifies the correctness of the
+device.

doc/developer-guides/hld/virtio-console.rst

@@ -1,7 +1,7 @@
-.. virtio-console:
+.. _virtio-console:
 
-Virtio-Console High-Level design
+Virtio-console
-################################
+##############
 
 The Virtio-console is a simple device for data input and output.  The
 console's virtio device ID is ``3`` and can have from 1 to 16 ports.
@@ -181,3 +181,4 @@ The File backend only supports console output to a file (no input).
 #. Add the console parameter to the guest OS kernel command line::
 
       console=hvc0
+

doc/developer-guides/hld/virtio-rnd.rst

@@ -0,0 +1,21 @@
+.. _virtio-rnd:
+
+Virtio-rnd
+##########
+
+The virtio-rnd entropy device supplies high-quality randomness for guest
+use. The virtio device ID of the virtio-rnd device is 4, and it supports
+one virtqueue, the size of which is 64, configurable in the source code.
+It has no feature bits defined.
+
+When the FE driver requires some random bytes, the BE device will place
+bytes of random data onto the virtqueue.
+
+To launch the virtio-rnd device, use the following virtio command::
+
+   -s <slot>,virtio-rnd
+
+To verify the correctness in user OS, use the following
+command::
+
+   od /dev/random

doc/developer-guides/index.rst

@@ -6,30 +6,13 @@ Developer Guides
 .. toctree::
    :maxdepth: 1
 
-   primer.rst
+   hld/index
-   ../api/index.rst
+   primer
-   ../reference/kconfig/index.rst
+   GVT-g-porting
+   trusty
+   ../api/index
+   ../reference/kconfig/index
 
-High-Level Design Guides
-************************
-
-These documents describe the high-level design, background, and motivation for
-specific areas within the ACRN hypervisor system.
-
-.. toctree::
-   :maxdepth: 1
-
-   ACPI-virt-hld.rst
-   APL_GVT-g-hld.rst
-   GVT-g-porting.rst
-   interrupt-hld.rst
-   memmgt-hld.rst
-   network-virt-hld.rst
-   security-hld.rst
-   uart-virtualization.rst
-   virtio-hld.rst
-   virtio-console.rst
-   watchdog-hld.rst
 
 Contributing to the project
 ***************************
@@ -41,6 +24,6 @@ project.
 .. toctree::
    :maxdepth: 1
 
-   contribute_guidelines.rst
+   contribute_guidelines
-   doc_guidelines.rst
+   doc_guidelines
-   graphviz.rst
+   graphviz

doc/developer-guides/trusty.rst

@@ -1,9 +1,7 @@
-:orphan:
-
 .. _trusty_tee:
 
-Trusty TEE on ACRN
+Trusty TEE
-##################
+##########
 
 Introduction
 ************