doc: reorganize documentation

We've been expanding documentation, and now need to organize things a bit
cleaner and separate content into new major folders: Introduction, Getting
Started, User Guides, Developer Guides, Tutorials, and Release notes..

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

doc/contribute/index.rst

@@ -1,13 +0,0 @@
-.. _contribute:
-
-Contributing to the Project
-###########################
-
-As an open-source project, we welcome and encourage the community to submit
-patches for code, documentation, tests, and more, directly to the project.
-
-.. toctree::
-   :maxdepth: 1
-
-   contribute_guidelines.rst
-   doc_guidelines.rst

doc/developer-guides/index.rst

@@ -0,0 +1,25 @@
+.. _developer-guides:
+
+Developer Guides
+################
+
+.. toctree::
+   :maxdepth: 1
+
+   primer.rst
+   ../api/index.rst
+   ../reference/kconfig/index.rst
+
+
+Contributing to the project
+***************************
+
+As an open-source project, we welcome and encourage the community to
+submit patches for code, documentation, tests, and more, directly to the
+project.
+
+.. toctree::
+   :maxdepth: 1
+
+   contribute_guidelines.rst
+   doc_guidelines.rst

doc/getting-started/apl-nuc.rst

@@ -1,33 +1,20 @@
-.. _getting_started:
+.. _getting-started-apl-nuc:
 
-Getting Started Guide
-#####################
+Getting started guide for Intel NUC
+###################################
 
-After reading the :ref:`introduction`, use this guide to get started
-using ACRN in a reference setup.  We'll show how to set up your
-development and target hardware, and then how to boot up the ACRN
-hypervisor and the `Clear Linux`_ Service OS and Guest OS on the Intel
-(EFI) platform.
+The Intel |reg| NUC (NUC6CAYH) is the primary tested
+platform for ACRN development, and its setup is described below.
 
-.. _Clear Linux: https://clearlinux.org
 
 Hardware setup
 **************
 
-The Intel |reg| NUC (NUC6CAYH) is the supported reference target
-platform for ACRN work, as described in :ref:`hardware`, and is the main
-platform currently tested with these setup instructions. The
-`UP Squared board <http://www.up-board.org/upsquared/>`_ (UP2) is also
-known to work and the few specificities for it are described
-in :ref:`getting_started_up2`.
+Two Apollo Lake Intel platforms, described in :ref:`hardware`, are currently
+supported for ACRN development:
 
-The recommended NUC hardware configuration is:
-
-- NUC: `NUC Kit
-  NUC6CAYH <https://www.intel.com/content/www/us/en/products/boards-kits/nuc/kits/nuc6cayh.html>`__
-- `UEFI BIOS (version 0047) <https://downloadcenter.intel.com/product/95062/Intel-NUC-Kit-NUC6CAYH>`__.
-- Memory: 8G DDR3
-- SSD: 120G SATA
+- The `UP Squared board <http://www.up-board.org/upsquared/>`_ (UP2) is also
+  known to work and its setup is described in :ref:`getting-started-up2`.
 
 Firmware update on the NUC
 ==========================
@@ -44,8 +31,9 @@ Set up a Clear Linux Operating System
 =====================================
 
 Currently, an installable version of ARCN does not exist. Therefore, you
-need to setup a base Clear Linux OS to bootstrap ACRN on your platform. You'll
-need a network connection for your platform to complete this setup.
+need to setup a base Clear Linux OS and you'll build and bootstrap ACRN
+on your platform. You'll need a network connection for your platform to
+complete this setup.
 
 .. note::
    ACRN requires Clear Linux version 22140 or newer. The instructions below
@@ -163,7 +151,8 @@ partition. Follow these steps:
 
    1. ``bootloader=``: this sets the EFI executable to be loaded once the hypervisor
       is up and running. This is typically the bootloader of the Service OS and the
-      default value is to use the Clearlinux bootloader, i.e.: ``\EFI\org.clearlinux\bootloaderx64.efi``.
+      default value is to use the Clearlinux bootloader, i.e.:
+      ``\EFI\org.clearlinux\bootloaderx64.efi``.
    #. ``uart=``: this tells the hypervisor where the serial port (UART) is found or
       whether it should be disabled. There are three forms for this parameter:
 

doc/getting-started/hardware.rst

@@ -7,7 +7,7 @@ We welcome community contributions to help build Project ACRN support
 for a broad collection of architectures and platforms.
 
 This initial release of Project ACRN has been tested on the following
-hardware platform.
+hardware platforms.
 
 Intel Apollo Lake NUC
 *********************
@@ -22,6 +22,9 @@ search online for where to purchase this NUC from `Amazon`_,
 `SimplyNUC`_, and other vendors. Be sure to purchase the NUC with the
 recommended memory and storage options noted above.
 
+Visit the :ref:`getting-started-apl-nuc` page for instructions on how to set
+up ACRN on the NUC.
+
 .. _AnandTech review:
    https://www.anandtech.com/show/12295/intel-nuc6cayh-arches-canyon-apollo-lake-ucff-pc-review
 
@@ -34,8 +37,19 @@ recommended memory and storage options noted above.
 UP Squared board
 ****************
 
-The `UP Squared board <http://www.up-board.org/upsquared/>`_ (UP2) is the x86 maker board based on Intel Apollo Lake platform. The UP boards have been used in IoT, industrial automation, digital signage and more. The UP2 features Intel `Celeron N3550 <https://ark.intel.com/products/95598/Intel-Celeron-Processor-N3350-2M-Cache-up-to-2_4-GHz>`_ and Intel `Pentium N4200 <https://ark.intel.com/products/95592/Intel-Pentium-Processor-N4200-2M-Cache-up-to-2_5-GHz>`_ SoCs. Both have been confirmed to work with ACRN.
+The `UP Squared board <http://www.up-board.org/upsquared/>`_ (UP2) is
+an x86 maker board based on the Intel Apollo Lake platform. The UP boards
+are used in IoT, industrial automation, digital signage, and more.
 
-You can purchase this board directly online from `UP Shop <https://up-shop.org/>`_ or contact one of the `local reseller <http://www.up-board.org/up/local-resellers-for-up/>`_.
+The UP2 features Intel `Celeron N3550
+<https://ark.intel.com/products/95598/Intel-Celeron-Processor-N3350-2M-Cache-up-to-2_4-GHz>`_
+and Intel `Pentium N4200
+<https://ark.intel.com/products/95592/Intel-Pentium-Processor-N4200-2M-Cache-up-to-2_5-GHz>`_
+SoCs. Both have been confirmed to work with ACRN.
 
-Visit the :ref:`getting_started_up2` page for instructions on how to set up ACRN on the UP2 board.
+You can purchase this board directly online from `UP Shop
+<https://up-shop.org/>`_ or contact one of the `local reseller
+<http://www.up-board.org/up/local-resellers-for-up/>`_.
+
+Visit the :ref:`getting-started-up2` page for instructions on how to set
+up ACRN on the UP2 board.

doc/getting-started/index.rst

@@ -0,0 +1,22 @@
+.. _getting_started:
+
+Getting Started Guides
+######################
+
+After reading the :ref:`introduction`, use these guides to get started
+using ACRN in a reference setup.  We'll show how to set up your
+development and target hardware, and then how to boot up the ACRN
+hypervisor and the `Clear Linux`_ Service OS and Guest OS on the Intel
+(EFI) platform.
+
+.. _Clear Linux: https://clearlinux.org
+
+ACRN development is currently supported on Apollo Lake Intel platforms,
+described in :ref:`hardware`. Follow the setup guides listed here:
+
+.. toctree::
+   :maxdepth: 1
+
+   hardware.rst
+   apl-nuc.rst
+   up2.rst

doc/getting-started/up2.rst

@@ -1,4 +1,4 @@
-.. _getting_started_up2:
+.. _getting-started-up2:
 
 Getting started guide for UP2 board
 ###################################
@@ -6,22 +6,40 @@ Getting started guide for UP2 board
 Hardware setup
 **************
 
-The `UP Squared board <http://www.up-board.org/upsquared/>`_ (UP2) is the x86 maker board based on Intel Apollo Lake platform. The UP boards have been used in IoT, industrial automation, digital signage and more. The UP2 features Intel `Celeron N3550 <https://ark.intel.com/products/95598/Intel-Celeron-Processor-N3350-2M-Cache-up-to-2_4-GHz>`_ and Intel `Pentium N4200 <https://ark.intel.com/products/95592/Intel-Pentium-Processor-N4200-2M-Cache-up-to-2_5-GHz>`_ SoCs. Both have been confirmed to work with ACRN.
+The `UP Squared board <http://www.up-board.org/upsquared/>`_ (UP2) is
+an x86 maker board based on the Intel Apollo Lake platform. The UP boards
+are used in IoT applications, industrial automation, digital signage, and more.
+
+The UP2 features Intel `Celeron N3550
+<https://ark.intel.com/products/95598/Intel-Celeron-Processor-N3350-2M-Cache-up-to-2_4-GHz>`_
+and Intel `Pentium N4200
+<https://ark.intel.com/products/95592/Intel-Pentium-Processor-N4200-2M-Cache-up-to-2_5-GHz>`_
+SoCs. Both have been confirmed to work with ACRN.
 
 Connecting to the serial port
 =============================
 
-The UP2 board has two serial ports. Please refer to the `UP2 specifications <http://www.up-board.org/upsquared/specifications-up2/>`_ for more information.  We'll access the serial port through the I/O pins in the 40-pin HAT connector using a `USB TTL serial cable <http://www.ftdichip.com/Products/USBTTLSerial.htm>`_. Connect pin 6 (``GND``), pin 8 (``TX``) and pin 10 (``RX``) of the HAT connector to respectively the ``GND``, ``RX`` and ``TX`` pins of your USB serial cable. Plug the USB TTL serial cable into your PC and use a console emulation tool such as ``minicom`` or ``putty`` to communicate with the UP2 board for debugging.
+The UP2 board has two serial ports. Please refer to the `UP2
+specifications <http://www.up-board.org/upsquared/specifications-up2/>`_
+for more information.  We'll access the serial port through the I/O pins
+in the 40-pin HAT connector using a `USB TTL serial cable
+<http://www.ftdichip.com/Products/USBTTLSerial.htm>`_. Connect pin 6
+(``GND``), pin 8 (``TX``) and pin 10 (``RX``) of the HAT connector to
+respectively the ``GND``, ``RX`` and ``TX`` pins of your USB serial
+cable. Plug the USB TTL serial cable into your PC and use a console
+emulation tool such as ``minicom`` or ``putty`` to communicate with the
+UP2 board for debugging.
 
 Software setup
 **************
 
 Setting up the ACRN hypervisor (and associated components) on the UP2
 board is no different than other hardware platforms so please follow
-the instructions provided in the :ref:`getting_started`.
+the instructions provided in the :ref:`getting-started-apl-nuc`, with
+the additional information below.
 
 There are a few parameters specific to the UP2 board that differ from
-what is referenced in the :ref:`getting_started` section:
+what is referenced in the :ref:`getting-started-apl-nuc` section:
 
 1. Serial Port settings
 #. Storage device name
@@ -81,6 +99,5 @@ Running the hypervisor
 **********************
 
 Now that the hypervisor and Service OS have been installed on your UP2 board,
-you can proceed with the rest of the instructions in the :ref:`getting_started`
-and install the User OS (UOS).
-
+you can proceed with the rest of the instructions in the
+:ref:`getting-started-apl-nuc` and install the User OS (UOS).

doc/howtos/index.rst

@@ -1,27 +0,0 @@
-.. _howtos:
-
-How-Tos
-#######
-
-Our technical documentation for Project ACRN is being developed right
-along with the features.  Here are some how-to technical notes that help
-explain how you can use ACRN capabilities.
-
-
-Technical Notes
-===============
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   tech/*
-
-Process Notes
-=============
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   process/*

doc/howtos/tech/placeholder.rst

@@ -1,6 +0,0 @@
-.. _wip:
-
-Work in Progress
-################
-
-This is a placeholder doc for technical how-to articles in-progress.

doc/index.rst

@@ -25,16 +25,11 @@ Sections
    :maxdepth: 1
 
    introduction/index.rst
-   hardware.rst
-   getting_started/index.rst
-   getting_started/up2.rst
-   primer/index.rst
-   howtos/index.rst
+   getting-started/index.rst
+   user-guides/index.rst
+   developer-guides/index.rst
+   tutorials/index.rst
    release_notes.rst
-   contribute/index.rst
-   reference/kconfig/index.rst
-   api/index.rst
-   tools.rst
 
 Indices and Tables
 ******************

doc/tutorials/docbuild.rst

@@ -75,7 +75,7 @@ repos (though https clones work too):
 #. Use your browser to visit https://github.com/projectacrn and do a
    fork of the **acrn-hypervisor** repo to your personal GitHub account.)
 
-   .. image:: acrn-doc-fork.png
+   .. image:: images/acrn-doc-fork.png
       :align: center
 
 #. At a command prompt, create the working folder and clone the acrn-hypervisor

doc/tutorials/index.rst

@@ -0,0 +1,14 @@
+.. _tutorials:
+
+Tutorials
+#########
+
+Here are some technical notes that help explain how you can use
+and work with ACRN capabilities and its development environment.
+
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

doc/user-guides/acrn-shell.rst

@@ -0,0 +1,55 @@
+.. acrnshell:
+
+ACRN Shell Commands
+###################
+
+The ACRN hypervisor shell supports the following commands:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Command (and parameters)
+     - Description
+   * - help
+     - Displays information about supported hypervisor shell commands
+   * - vm_list
+     - Lists all VMs, displaying VM Name, VM ID, and VM State (ON=running)
+   * - vcpu_list
+     - Lists all VCPUs in all VMs
+   * - vcpu_pause <vm_id, vcpu_id>
+     - Pauses a specific VCPU
+   * - vcpu_resume <vm_id, vcpu_id>
+     - Resumes a specific VCPU
+   * - vcpu_dumpreg <vm_id, vcpu_id>
+     - Dumps registers for a specific VCPU
+   * - vcpu_dumpmem <vm_id, vcpu_id, GVA, length>
+     - Dumps memory for a specific VCPU, starting a given address, and for
+       a given length (in bytes)
+   * - vm_console
+     - Switches to the SOS's console
+   * - int
+     - Lists interrupt information per CPU
+   * - pt
+     - Shows pass-through device information
+   * - reboot
+     - Triggers a system warm reboot (immediately)
+   * - lsreq
+     - Shows ioreq information
+   * - dump_ioapic
+     - Shows native ioapic information
+   * - vmexit
+     - Shows vmexit profiling
+   * - logdump <pcpu_id>
+     - Dumps the log buffer for the physical CPU
+   * - trace <cpumask, ms>
+     - Dumps a CPU's recent events within <ms> milliseconds
+   * - get_loglevel
+     - Get the loglevel
+   * - set_loglevel <console_loglevel> [mem_loglevel]
+     - Set loglevel [0 (none) - 6 (verbose)] for the console and optionally
+       for memory
+   * - cpuid <leaf> [subleaf]
+     - Displays the CPUID leaf [subleaf], in hexadecimal
+   * - crash
+     - Triggers a system crash

doc/user-guides/index.rst

@@ -0,0 +1,10 @@
+.. _userguides:
+
+User Guides
+###########
+
+.. toctree::
+   :maxdepth: 2
+
+   acrn-shell.rst
+   tools.rst

doc/user-guides/tools.rst

@@ -7,4 +7,4 @@ Tools
    :glob:
    :maxdepth: 1
 
-   tools/**
+   ../tools/**