doc: fix primer reST errors, update folder layout

Remove UEFI boot material that was causing doc build to fail (seems to
be a duplicate of material in the Getting Started Guide anyway)

Fix reST formatting for the DM memory allocation section.

Update folder layout description

Fixes: #202

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

doc/primer/index.rst

@@ -24,9 +24,20 @@ Source Tree Structure
 
 Understanding the ACRN hypervisor and the ACRN device model source tree
 structure is helpful for locating the code associated with a particular
-hypervisor and device emulation feature. The ACRN hypervisor and the
+hypervisor and device emulation feature.
-ACRN device model source tree provides the following top-level
+
-directories:
+The ACRN source code (and documentation) are maintained in the
+https://github.com/projectacrn/acrn-hypervisor repo, with the
+hypervisor, device model, tools, and documentation in their own
+folders::
+
+   acrn-hypervisor
+   ├─ hypervisor
+   ├─ devicemodel
+   ├─ tools
+   └─ doc
+
+Here's a brief description of each of these source tree folders:
 
 ACRN hypervisor source tree
 ===========================
@@ -68,9 +79,6 @@ ACRN Device Model source tree
 **hw/**
   Hardware emulation code, with the following subdirectories:
 
-  **acpi/**
-     ACPI table generator.
-
   **pci/**
      PCI devices, including VBS-Us (Virtio backend drivers in user-space).
 
@@ -82,7 +90,24 @@ ACRN Device Model source tree
   files are used to generate the :ref:`acrn_apis` documentation)
 
 **samples/**
-  include files for all public APIs (doxygen comments in these source
+  scripts (included in the Clear Linux build) for setting up the network
+  and launching the User OS on the platform.
+
+ACRN Tools source tree
+=============================
+
+The tools folder holds source code for ACRN-provided tools such as:
+
+acrnlog
+  a userland tool to capture the log output from the currently running
+  hypervisor, and from the last previous run if the hypervisor crashed.
+
+acrnctl
+  a utility to create, delete, list, launch, and stop a User OS (UOS).
+
+acrntrace
+  a Service OS (SOS) utility to capture trace data and scripts to
+  analyze the collected data.
 
 ACRN documentation source tree
 ==============================
@@ -95,10 +120,6 @@ reading now.) Developers can view this content either in its raw form as
 the HTML content and view it with a web browser directly on your
 workstation, useful if you're contributing documentation to the project.
 
-**_templates/**
-  Sphinx configuration updates for the standard read-the-docs templates
-  used to format the generated HTML output
-
 **api/**
   ReST files for API document generation
 
@@ -129,6 +150,10 @@ workstation, useful if you're contributing documentation to the project.
   Sphinx folder for extras added to the generated output (such as custom
   CSS additions)
 
+**_templates/**
+  Sphinx configuration updates for the standard read-the-docs templates
+  used to format the generated HTML output
+
 CPU virtualization
 ******************
 
@@ -912,55 +937,39 @@ or
 
    screen /dev/pts/0
 
-UEFI Boot
-*********
-This section introduces UEFI boot support by ACRN.
 
-Usage of acrn.efi
+Device Manager memory allocation mechanism
-=================
+******************************************
 
-ACRN supports boot from UEFI FW, this section is the UEFI boot HOWTO under
+There are two Device Manager memory allocation mechanisms available:
-Clear Linux environment.
 
-The pre-condition is like below:
+- Contiguous Memory Allocator (CMA), and 
-    - You have installed the Service OS (bare-metal for now)
+- Huge Page Tables (HugeTLB).  HugeTLB is the default.
-    - CL Bootloader is "\EFI\org.clearlinux\bootloaderx64.efi"
-    - Boot device is '/dev/sda'
-    - EFI System Partition (ESP) is '1'
 
-Suggest to follow the following step:
+To choose CMA, do the following:
-1. Build out the acrn.efi image with command "make PLATFORM=uefi".
-2. Put the acrn.efi under "\EFI\acrn\"
-3. To change the default boot entry to boot the ACRN hypervisor, enter:
-    # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 \
-      -L "ACRN Hypervisor" -u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi"
-4. Update the bsp/uefi/clearlinux/acrn.conf file by filling the field
-   <UUID of rootfs partition> with the your native rootfs partition uuid.
-5. Copy bsp/uefi/clearlinux/acrn.conf to loader\\entries\\ directory.
-6. Reboot.
 
+1) Add ``cma=reserved_mem_size@recommend_memory_offset-0``, (for example
+   ``cma=2560M@0x100000000-0``) to the SOS cmdline in ``acrn.conf``
 
-DM memory allocation mechanism
+2) Start ``acrn-dm`` *without* the ``-T`` option
-==============================
 
-There are two kinds of DM memory allocation mechanism - CMA & Hugetlb, they can
+To support HugeTLB, do the following:
-be choose to support but hugetlb will become the default one.
 
-To support CMA, please make sure:
+1) Do huge page reservation
-  1) add "cma=reserved_mem_size@recommend_memory_offset-0" like
-     "cma=2560M@0x100000000-0" to the SOS cmdline in acrn.conf
-  2) start acrn-dm without "-T" option
 
-To support Hugetlb, please make sure:
+   - For 1G huge page reservation, add ``hugepagesz=1G hugepages=reserved_pg_num``
-  1) Do huge page reservation
+     (for example, ``hugepagesz=1G hugepages=4``) to the SOS cmdline in
-   - For 1G huge page reservation, add "hugepagesz=1G hugepages=reserved_pg_num"
+     ``acrn.conf`` (for EFI)
-     like "hugepagesz=1G hugepages=4" to the SOS cmdline(in acrn.conf for EFI)
+
-   - For 2M huge page reservation, after SOS start up,
+   - For 2M huge page reservation, after the SOS starts up, run the
-     echo reserved_pg_num > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
+     command::
-   - NOTE:
+
-     You can use 2M reserving method to do reservation for 1G page size, but it
+        echo reserved_pg_num > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
-     may fail.
+
-     For EFI platform, you may skip 1G page reservation by just using 2M page,
+   .. note::
-     but make sure your huge page reservation size is enough for your usage.
+      You can use 2M reserving method to do reservation for 1G page size, but it
-  2) Let acrn-dm use hugetlb
+      may fail.  For an EFI platform, you may skip 1G page reservation
-   - start acrn-dm with "-T" option
+      by using a 2M page, but make sure your huge page reservation size is
+      large enough for your usage.
+
+2)  Start ``acrn-dm`` *with* the ``-T`` option.