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/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.