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>
@ -1,4 +1,4 @@
|
||||
.. _ACPI-virt-HLD:
|
||||
.. _acpi-virt-HLD:
|
||||
|
||||
ACPI Virtualization high-level design
|
||||
#####################################
|
10
doc/developer-guides/hld/hld-devicemodel.rst
Normal file
@ -0,0 +1,10 @@
|
||||
.. _hld-devicemodel:
|
||||
|
||||
Device Model high-level design
|
||||
##############################
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
ACPI virtualization <acpi-virt>
|
11
doc/developer-guides/hld/hld-emulated-devices.rst
Normal file
@ -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>
|
11
doc/developer-guides/hld/hld-hypervisor.rst
Normal file
@ -0,0 +1,11 @@
|
||||
.. _hld-hypervisor:
|
||||
|
||||
Hypervisor high-level design
|
||||
############################
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Memory management <memmgt-hld>
|
||||
Interrupt management <interrupt-hld>
|
4
doc/developer-guides/hld/hld-overview.rst
Normal file
@ -0,0 +1,4 @@
|
||||
.. _hld-overview:
|
||||
|
||||
Overview
|
||||
########
|
4
doc/developer-guides/hld/hld-power-management.rst
Normal file
@ -0,0 +1,4 @@
|
||||
.. _hld-power-management:
|
||||
|
||||
Power Management high-level design
|
||||
##################################
|
@ -1,4 +1,4 @@
|
||||
.. _security-hld:
|
||||
.. _hld-security:
|
||||
|
||||
Security high-level design
|
||||
##########################
|
4
doc/developer-guides/hld/hld-trace-log.rst
Normal file
@ -0,0 +1,4 @@
|
||||
.. _hld-trace-log:
|
||||
|
||||
Tracing and Logging high-level design
|
||||
#####################################
|
4
doc/developer-guides/hld/hld-vm-management.rst
Normal file
@ -0,0 +1,4 @@
|
||||
.. _hld-vm-management:
|
||||
|
||||
VM Management high-level design
|
||||
###############################
|
4
doc/developer-guides/hld/hld-vsbl.rst
Normal file
@ -0,0 +1,4 @@
|
||||
.. _hld-vsbl:
|
||||
|
||||
Virtual Slim-Bootloader high-level design
|
||||
#########################################
|
Before Width: | Height: | Size: 81 KiB After Width: | Height: | Size: 81 KiB |
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 26 KiB |
Before Width: | Height: | Size: 72 KiB After Width: | Height: | Size: 72 KiB |
Before Width: | Height: | Size: 60 KiB After Width: | Height: | Size: 60 KiB |
Before Width: | Height: | Size: 34 KiB After Width: | Height: | Size: 34 KiB |
Before Width: | Height: | Size: 173 KiB After Width: | Height: | Size: 173 KiB |
Before Width: | Height: | Size: 201 KiB After Width: | Height: | Size: 201 KiB |
Before Width: | Height: | Size: 14 KiB After Width: | Height: | Size: 14 KiB |
Before Width: | Height: | Size: 147 KiB After Width: | Height: | Size: 147 KiB |
Before Width: | Height: | Size: 35 KiB After Width: | Height: | Size: 35 KiB |
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 58 KiB |
Before Width: | Height: | Size: 117 KiB After Width: | Height: | Size: 117 KiB |
Before Width: | Height: | Size: 166 KiB After Width: | Height: | Size: 166 KiB |
Before Width: | Height: | Size: 101 KiB After Width: | Height: | Size: 101 KiB |
Before Width: | Height: | Size: 71 KiB After Width: | Height: | Size: 71 KiB |
Before Width: | Height: | Size: 450 KiB After Width: | Height: | Size: 450 KiB |
Before Width: | Height: | Size: 62 KiB After Width: | Height: | Size: 62 KiB |
Before Width: | Height: | Size: 76 KiB After Width: | Height: | Size: 76 KiB |
Before Width: | Height: | Size: 75 KiB After Width: | Height: | Size: 75 KiB |
Before Width: | Height: | Size: 86 KiB After Width: | Height: | Size: 86 KiB |
Before Width: | Height: | Size: 34 KiB After Width: | Height: | Size: 34 KiB |
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 32 KiB |
Before Width: | Height: | Size: 37 KiB After Width: | Height: | Size: 37 KiB |
Before Width: | Height: | Size: 30 KiB After Width: | Height: | Size: 30 KiB |
Before Width: | Height: | Size: 36 KiB After Width: | Height: | Size: 36 KiB |
Before Width: | Height: | Size: 50 KiB After Width: | Height: | Size: 50 KiB |
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 20 KiB |
Before Width: | Height: | Size: 24 KiB After Width: | Height: | Size: 24 KiB |
Before Width: | Height: | Size: 36 KiB After Width: | Height: | Size: 36 KiB |
Before Width: | Height: | Size: 121 KiB After Width: | Height: | Size: 121 KiB |
Before Width: | Height: | Size: 29 KiB After Width: | Height: | Size: 29 KiB |
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
Before Width: | Height: | Size: 4.7 KiB After Width: | Height: | Size: 4.7 KiB |
Before Width: | Height: | Size: 23 KiB After Width: | Height: | Size: 23 KiB |
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 16 KiB |
Before Width: | Height: | Size: 11 KiB After Width: | Height: | Size: 11 KiB |
Before Width: | Height: | Size: 35 KiB After Width: | Height: | Size: 35 KiB |
Before Width: | Height: | Size: 45 KiB After Width: | Height: | Size: 45 KiB |
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 43 KiB |
Before Width: | Height: | Size: 156 KiB After Width: | Height: | Size: 156 KiB |
Before Width: | Height: | Size: 9.0 KiB After Width: | Height: | Size: 9.0 KiB |
Before Width: | Height: | Size: 377 KiB After Width: | Height: | Size: 377 KiB |
Before Width: | Height: | Size: 61 KiB After Width: | Height: | Size: 61 KiB |
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
Before Width: | Height: | Size: 52 KiB After Width: | Height: | Size: 52 KiB |
Before Width: | Height: | Size: 740 KiB After Width: | Height: | Size: 740 KiB |
Before Width: | Height: | Size: 11 KiB After Width: | Height: | Size: 11 KiB |
Before Width: | Height: | Size: 28 KiB After Width: | Height: | Size: 28 KiB |
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 50 KiB After Width: | Height: | Size: 50 KiB |
Before Width: | Height: | Size: 47 KiB After Width: | Height: | Size: 47 KiB |
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 26 KiB |
Before Width: | Height: | Size: 46 KiB After Width: | Height: | Size: 46 KiB |
Before Width: | Height: | Size: 27 KiB After Width: | Height: | Size: 27 KiB |
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
Before Width: | Height: | Size: 94 KiB After Width: | Height: | Size: 94 KiB |
BIN
doc/developer-guides/hld/images/virtio-blk-image01.png
Normal file
After Width: | Height: | Size: 142 KiB |
BIN
doc/developer-guides/hld/images/virtio-blk-image02.png
Normal file
After Width: | Height: | Size: 45 KiB |
Before Width: | Height: | Size: 156 KiB After Width: | Height: | Size: 156 KiB |
Before Width: | Height: | Size: 29 KiB After Width: | Height: | Size: 29 KiB |
Before Width: | Height: | Size: 52 KiB After Width: | Height: | Size: 52 KiB |
Before Width: | Height: | Size: 66 KiB After Width: | Height: | Size: 66 KiB |
Before Width: | Height: | Size: 72 KiB After Width: | Height: | Size: 72 KiB |
Before Width: | Height: | Size: 136 KiB After Width: | Height: | Size: 136 KiB |
Before Width: | Height: | Size: 44 KiB After Width: | Height: | Size: 44 KiB |
Before Width: | Height: | Size: 70 KiB After Width: | Height: | Size: 70 KiB |
Before Width: | Height: | Size: 86 KiB After Width: | Height: | Size: 86 KiB |
Before Width: | Height: | Size: 51 KiB After Width: | Height: | Size: 51 KiB |
Before Width: | Height: | Size: 250 KiB After Width: | Height: | Size: 250 KiB |
Before Width: | Height: | Size: 135 KiB After Width: | Height: | Size: 135 KiB |
28
doc/developer-guides/hld/index.rst
Normal file
@ -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>
|
107
doc/developer-guides/hld/virtio-blk.rst
Normal file
@ -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.
|
@ -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
|
||||
|
21
doc/developer-guides/hld/virtio-rnd.rst
Normal file
@ -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
|
@ -6,30 +6,13 @@ Developer Guides
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
primer.rst
|
||||
../api/index.rst
|
||||
../reference/kconfig/index.rst
|
||||
hld/index
|
||||
primer
|
||||
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
|
||||
doc_guidelines.rst
|
||||
graphviz.rst
|
||||
contribute_guidelines
|
||||
doc_guidelines
|
||||
graphviz
|
||||
|
@ -1,9 +1,7 @@
|
||||
:orphan:
|
||||
|
||||
.. _trusty_tee:
|
||||
|
||||
Trusty TEE on ACRN
|
||||
##################
|
||||
Trusty TEE
|
||||
##########
|
||||
|
||||
Introduction
|
||||
************
|
||||
|