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-virtio-devices.rst

@@ -1,7 +1,8 @@
+.. _hld-virtio-devices:
 .. _virtio-hld:
 
-Virtio high-level design
+Virtio devices high-level design
-########################
+################################
 
 The ACRN Hypervisor follows the `Virtual I/O Device (virtio)
 specification
@@ -37,9 +38,6 @@ service (VBS) APIs, and virtqueue (VQ) APIs, as shown in
    information from the shared memory between the frontend and backend
    device drivers.
 
-Virtio Device
-*************
-
 Virtio framework is the para-virtualization specification that ACRN
 follows to implement I/O virtualization of performance-critical
 devices such as audio, eAVB/TSN, IPU, and CSMU devices. This section gives
@@ -49,8 +47,8 @@ ACRN's virtio architectures, and elaborates on ACRN virtio APIs. Finally
 this section will introduce all the virtio devices currently supported
 by ACRN.
 
-Introduction
+Virtio introduction
-============
+*******************
 
 Virtio is an abstraction layer over devices in a para-virtualized
 hypervisor. Virtio was developed by Rusty Russell when he worked at IBM
@@ -69,7 +67,7 @@ Given the advantages of virtio, ACRN also follows the virtio
 specification.
 
 Key Concepts
-============
+************
 
 To better understand virtio, especially its usage in ACRN, we'll
 highlight several key virtio concepts important to ACRN:
@@ -178,13 +176,13 @@ Virtio Device Discovery
   Device ID indicates which virtio device is supported by the device.
 
 Virtio Frameworks
-=================
+*****************
 
 This section describes the overall architecture of virtio, and then
 introduce ACRN specific implementations of the virtio framework.
 
 Architecture
-------------
+============
 
 Virtio adopts a frontend-backend
 architecture, as shown in :numref:`virtio-arch`. Basically the FE and BE driver
@@ -216,7 +214,7 @@ virtqueues, feature mechanisms, configuration space, and buses.
    Virtio Frontend/Backend Layered Architecture
 
 Virtio Framework Considerations
--------------------------------
+===============================
 
 How to realize the virtio framework is specific to a
 hypervisor implementation. In ACRN, the virtio framework implementations
@@ -236,7 +234,7 @@ The next two sections introduce ACRN's two implementations of the virtio
 framework.
 
 User-Land Virtio Framework
---------------------------
+==========================
 
 The architecture of ACRN user-land virtio framework (VBS-U) is shown in
 :numref:`virtio-userland`.
@@ -265,7 +263,7 @@ virtqueue through the user-level vring service API helpers.
    ACRN User-Land Virtio Framework
 
 Kernel-Land Virtio Framework
-----------------------------
+============================
 
 The architecture of ACRN kernel-land virtio framework (VBS-K) is shown
 in :numref:`virtio-kernelland`.
@@ -298,7 +296,7 @@ driver development.
    ACRN Kernel-Land Virtio Framework
 
 Virtio APIs
-===========
+***********
 
 This section provides details on the ACRN virtio APIs. As outlined previously,
 the ACRN virtio APIs can be divided into three groups: DM_APIs,
@@ -306,7 +304,7 @@ VBS_APIs, and VQ_APIs. The following sections will elaborate on
 these APIs.
 
 VBS-U Key Data Structures
--------------------------
+=========================
 
 The key data structures for VBS-U are listed as following, and their
 relationships are shown in :numref:`VBS-U-data`.
@@ -341,7 +339,7 @@ virtio_ops`` abstracts a series of virtio callbacks to be provided by
 device owner.
 
 VBS-K Key Data Structures
--------------------------
+=========================
 
 The key data structures for VBS-K are listed as follows, and their
 relationships are shown in :numref:`VBS-K-data`.
@@ -422,8 +420,10 @@ APIs provided by DM
 APIs provided by VBS-K modules in service OS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+[API Material from doxygen comments]
+
 VQ APIs
--------
+=======
 
 The virtqueue APIs, or VQ APIs, are used by a BE device driver to
 access the virtqueues shared by the FE driver. The VQ APIs abstract the
@@ -452,11 +452,10 @@ requests from a FE driver.
       vq_endchains(vq, 1);
    }
 
-Current Virtio Devices
+Supported Virtio Devices
-======================
+************************
 
-This section introduces the status of the current virtio devices
+All the BE virtio drivers are implemented using the
-supported in ACRN. All the BE virtio drivers are implemented using the
 ACRN virtio APIs, and the FE drivers are reusing the standard Linux FE
 virtio drivers. For the devices with FE drivers available in the Linux
 kernel, they should use standard virtio Vendor ID/Device ID and
@@ -488,155 +487,13 @@ their temporary IDs are listed in the following table.
    | COREU        | 0x8086      | 0x8608      | 0x8086      | 0xFFF8      |
    +--------------+-------------+-------------+-------------+-------------+
 
-Virtio-rnd
+The following sections introduce the status of virtio devices currently
-==========
+supported in ACRN.
 
-The virtio-rnd entropy device supplies high-quality randomness for guest
+.. toctree::
-use. The virtio device ID of the virtio-rnd device is 4, and it supports
+   :maxdepth: 1
-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
+   virtio-blk
-bytes of random data onto the virtqueue.
+   virtio-net
-
+   virtio-console
-To launch the virtio-rnd device, use the following virtio command::
+   virtio-rnd
-
-   -s <slot>,virtio-rnd
-
-To verify the correctness in user OS, use the following
-command::
-
-   od /dev/random
-
-Virtio-blk
-==========
-
-The virtio-blk device is a simple virtual block device. The FE driver
-places read, write, and other requests onto the virtqueue, so that the
-BE driver can process them accordingly.
-
-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. The
-feature bits supported by the BE device are shown as follows:
-
-VTBLK_F_SEG_MAX(bit 2)
-  Maximum number of segments in a request is in seg_max.
-VTBLK_F_BLK_SIZE(bit 6)
-  block size of disk is in blk_size.
-VTBLK_F_FLUSH(bit 9)
-  cache flush command support.
-VTBLK_F_TOPOLOGY(bit 10)
-  device exports information on optimal I/O alignment.
-
-To use the virtio-blk device, use the following virtio command::
-
-   -s <slot>,virtio-blk,<filepath>[,options]
-   
-   options:
-
-   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 page cache. Needs to be flushed to the physical storage.
-
-   ro: open file with readonly mode.
-
-   sectorsize:
-   1> sectorsize=<sector size>/<physical sector size>
-   2> sectorsize=<sector size>
-   default values for sector size and physical sector size are 512
-
-   range:
-   range=<start lba in file>/<sub file size>
-
-Successful booting of the User OS verifies the correctness of the
-device.
-
-Virtio-net
-==========
-
-The virtio-net device is a virtual Ethernet device. The virtio device ID
-of the virtio-net is 1, and ACRN's virtio-net device supports twp
-virtqueues, one for transmitting packets and the other for receiving
-packets. The FE driver places empty buffers onto one virtqueue for
-receiving packets, and enqueue outgoing packets onto another virtqueue
-for transmission. Currently the size of each virtqueue is 1000,
-configurable in the source code.
-
-To access the external network from user OS, as shown in
-:numref:`virtio-network`, a L2 virtual switch should be created in the
-service OS, and the BE driver is bonded to a tap/tun device linking
-under the L2 virtual switch.
-
-.. figure:: images/virtio-hld-image7.png
-   :width: 900px
-   :align: center
-   :name: virtio-network
-
-   Virtio-net Accessing External Network
-
-Currently the feature bits supported by the BE device are shown as
-follows:
-
-VIRTIO_NET_F_MAC(bit 5)
-  device has given MAC address.
-VIRTIO_NET_F_MRG_RXBUF(bit 15)
-  BE driver can merge receive buffers.
-VIRTIO_NET_F_STATUS(bit 16)
-  configuration status field is available.
-VIRTIO_F_NOTIFY_ON_EMPTY(bit 24)
-  device will issue an interrupt if
-  it runs out of available descriptors on a virtqueue.
-
-To enable the virtio-net device, use the following virtio command::
-
-   -s <slot>,virtio-net,<vale/tap/vmnet>
-
-To verify the correctness of the device, access the external
-network within the user OS.
-
-Virtio-console
-==============
-
-The virtio-console device is a simple device for data input and output.
-The virtio device ID of the virtio-console device is 3. A device could
-have one or up to 16 ports in ACRN. Each port has a pair of input and
-output virtqueues. A device has a pair of control virtqueues, which are
-used to communicate information between the FE and BE drivers. Currently
-the size of each virtqueue is 64, configurable in the source code.
-
-Similar to virtio-net device, two virtqueues specific to a port are
-transmitting virtqueue and receiving virtqueue. The FE driver places
-empty buffers onto the receiving virtqueue for incoming data, and
-enqueues outgoing characters onto transmitting virtqueue.
-
-Currently the feature bits supported by the BE device are shown as
-follows:
-
-VTCON_F_SIZE(bit 0)
-  configuration columns and rows are valid.
-VTCON_F_MULTIPORT(bit 1)
-  device supports multiple ports, and control
-  virtqueues will be used.
-VTCON_F_EMERG_WRITE(bit 2)
-  device supports emergency write.
-
-To use the virtio-console device, use the following virtio command::
-
-   -s <slot>,virtio-console,[@]<stdio|tty|pty|sock>:<portname>[=portpath]
-
-.. note::
-
-   Here are some notes about the virtio-console device:
-
-   - ``@`` : marks the port as a console port, otherwise it is a normal
-     virtio serial port
-   - stdio/tty/pty: tty capable, which means :kbd:`TAB` and :kbd:`BACKSPACE`
-     are supported as in regular terminals
-   - When tty are used, please make sure the redirected tty is sleep, e.g. by
-     "sleep 2d" command, and will not read input from stdin before it is used
-     by virtio-console to redirect guest output;
-   - Claiming multiple virtio serial ports as consoles are supported, however
-     the guest Linux will only use one of them, through "console=hvcN" kernel
-     parameters, as the hvc.

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-net.rst

@@ -1,10 +1,7 @@
-.. net-virt-hld:
+.. _virtio-net:
 
-Network Virtualization
+Virtio-net
-######################
+##########
-
-Introduction
-************
 
 Virtio-net is the para-virtualization solution used in ACRN for
 networking. The ACRN device model emulates virtual NICs for UOS and the
@@ -12,9 +9,6 @@ frontend virtio network driver, simulating the virtual NIC and following
 the virtio specification. (Refer to :ref:`introduction` and
 :ref:`virtio-hld` background introductions to ACRN and Virtio.)
 
-Supported Features Notes
-************************
-
 Here are some notes about Virtio-net support in ACRN:
 
 - Legacy devices are supported, modern devices are not supported
@@ -25,7 +19,7 @@ Here are some notes about Virtio-net support in ACRN:
 - NIC multiple queues are not supported
 
 Network Virtualization Architecture
-===================================
+***********************************
 
 ACRN's network virtualization architecture is shown below in
 :numref:`net-virt-arch`, and illustrates the many necessary network
@@ -109,10 +103,9 @@ ACRN network virtualization.
 Initialization in Device Model
 ==============================
 
-virtio_net_init
+**virtio_net_init**
----------------
 
-- Present frontend a virtual PCI based NIC
+- Present frontend for a virtual PCI based NIC
 - Setup control plan callbacks
 - Setup data plan callbacks, including TX, RX
 - Setup tap backend
@@ -120,14 +113,12 @@ virtio_net_init
 Initialization in virtio-net Frontend Driver
 ============================================
 
-virtio_pci_probe
+**virtio_pci_probe**
-----------------
 
 - Construct virtio device using virtual pci device and register it to
   virtio bus
 
-virtio_dev_probe --> virtnet_probe --> init_vqs
+**virtio_dev_probe --> virtnet_probe --> init_vqs**
------------------------------------------------
 
 - Register network driver
 - Setup shared virtqueues
@@ -138,8 +129,7 @@ ACRN UOS TX FLOW
 The following shows the ACRN UOS network TX flow, using TCP as an
 example, showing the flow through each layer:
 
-UOS TCP Layer
+**UOS TCP Layer**
--------------
 
 .. code-block:: c
 
@@ -149,8 +139,7 @@ UOS TCP Layer
                tcp_write_xmit -->
                    tcp_transmit_skb -->
 
-UOS IP Layer
+**UOS IP Layer**
-------------
 
 .. code-block:: c
 
@@ -164,8 +153,7 @@ UOS IP Layer
                                neigh_output -->
                                    neigh_resolve_output -->
 
-UOS MAC Layer
+**UOS MAC Layer**
--------------
 
 .. code-block:: c
 
@@ -177,8 +165,7 @@ UOS MAC Layer
                        __netdev_start_xmit -->
 
 
-UOS MAC Layer virtio-net Frontend Driver
+**UOS MAC Layer virtio-net Frontend Driver**
-----------------------------------------
 
 .. code-block:: c
 
@@ -192,8 +179,7 @@ UOS MAC Layer virtio-net Frontend Driver
                vp_notify -->
                    iowrite16 -->    // trap here, HV will first get notified
 
-ACRN Hypervisor
+**ACRN Hypervisor**
----------------
 
 .. code-block:: c
 
@@ -203,8 +189,7 @@ ACRN Hypervisor
                acrn_insert_request_wait -->
                    fire_vhm_interrupt -->  // interrupt SOS, VHM will get notified
 
-VHM Module
+**VHM Module**
-----------
 
 .. code-block:: c
 
@@ -215,8 +200,7 @@ VHM Module
                    acrn_ioreq_notify_client -->
                        wake_up_interruptible --> // wake up DM to handle ioreq
 
-ACRN Device Model / virtio-net Backend Driver
+**ACRN Device Model / virtio-net Backend Driver**
----------------------------------------------
 
 .. code-block:: c
 
@@ -232,8 +216,7 @@ ACRN Device Model / virtio-net Backend Driver
                                        virtio_net_tap_tx -->
                                            writev -->    // write data to tap device
 
-SOS TAP Device Forwarding
+**SOS TAP Device Forwarding**
--------------------------
 
 .. code-block:: c
 
@@ -250,8 +233,7 @@ SOS TAP Device Forwarding
                                            __netif_receive_skb_core -->
 
 
-SOS Bridge Forwarding
+**SOS Bridge Forwarding**
----------------------
 
 .. code-block:: c
 
@@ -262,8 +244,7 @@ SOS Bridge Forwarding
                    br_forward_finish -->
                        br_dev_queue_push_xmit -->
 
-SOS MAC Layer
+**SOS MAC Layer**
--------------
 
 .. code-block:: c
 
@@ -275,8 +256,7 @@ SOS MAC Layer
                        __netdev_start_xmit -->
 
 
-SOS MAC Layer IGB Driver
+**SOS MAC Layer IGB Driver**
-------------------------
 
 .. code-block:: c
 
@@ -290,8 +270,7 @@ Let's start by receiving a device interrupt. (Note that the hypervisor
 will first get notified when receiving an interrupt even in passthrough
 cases.)
 
-Hypervisor Interrupt Dispatch
+**Hypervisor Interrupt Dispatch**
------------------------------
 
 .. code-block:: c
 
@@ -303,8 +282,7 @@ Hypervisor Interrupt Dispatch
                      ptdev_enqueue_softirq --> // Interrupt will be delivered in bottom-half softirq
 
 
-Hypervisor Interrupt Injection
+**Hypervisor Interrupt Injection**
-------------------------------
 
 .. code-block:: c
 
@@ -314,8 +292,7 @@ Hypervisor Interrupt Injection
 
    start_vcpu -->                  // VM Entry here, will process the pending interrupts
 
-SOS MAC Layer IGB Driver
+**SOS MAC Layer IGB Driver**
-------------------------
 
 .. code-block:: c
 
@@ -329,8 +306,7 @@ SOS MAC Layer IGB Driver
                            __netif_receive_skb -->
                                __netif_receive_skb_core --
 
-SOS Bridge Forwarding
+**SOS Bridge Forwarding**
----------------------
 
 .. code-block:: c
 
@@ -341,8 +317,7 @@ SOS Bridge Forwarding
                    br_forward_finish -->
                        br_dev_queue_push_xmit -->
 
-SOS MAC Layer
+**SOS MAC Layer**
--------------
 
 .. code-block:: c
 
@@ -353,15 +328,13 @@ SOS MAC Layer
                    netdev_start_xmit -->
                        __netdev_start_xmit -->
 
-SOS MAC Layer TAP Driver
+**SOS MAC Layer TAP Driver**
-------------------------
 
 .. code-block:: c
 
    tun_net_xmit --> // Notify and wake up reader process
 
-ACRN Device Model / virtio-net Backend Driver
+**ACRN Device Model / virtio-net Backend Driver**
----------------------------------------------
 
 .. code-block:: c
 
@@ -371,16 +344,14 @@ ACRN Device Model / virtio-net Backend Driver
                vq_interrupt -->
                    pci_generate_msi -->
 
-VHM Module
+**VHM Module**
-----------
 
 .. code-block:: c
 
    vhm_dev_ioctl -->                // process the IOCTL and call hypercall to inject interrupt
        hcall_inject_msi -->
 
-ACRN Hypervisor
+**ACRN Hypervisor**
----------------
 
 .. code-block:: c
 
@@ -389,8 +360,7 @@ ACRN Hypervisor
            hcall_inject_msi -->     // insert interrupt into UOS
                vlapic_intr_msi -->
 
-UOS MAC Layer virtio_net Frontend Driver
+**UOS MAC Layer virtio_net Frontend Driver**
-----------------------------------------
 
 .. code-block:: c
 
@@ -402,8 +372,7 @@ UOS MAC Layer virtio_net Frontend Driver
                        virtnet_receive -->
                            receive_buf -->
 
-UOS MAC Layer
+**UOS MAC Layer**
--------------
 
 .. code-block:: c
 
@@ -413,8 +382,7 @@ UOS MAC Layer
                __netif_receive_skb -->
                    __netif_receive_skb_core -->
 
-UOS IP Layer
+**UOS IP Layer**
-------------
 
 .. code-block:: c
 
@@ -425,8 +393,7 @@ UOS IP Layer
                    ip_local_deliver_finish -->
 
 
-UOS TCP Layer
+**UOS TCP Layer**
--------------
 
 .. code-block:: c
 
@@ -554,3 +521,5 @@ the native bandwidgh. For high speed NIC (e.g.  10Gb or above), it is
 necessary to separate the data plane from the control plane. We can use
 vhost for acceleration. For most IoT scenarios, processing in user space
 is simple and reasonable.
+
+

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
 ************