From 63fd853df3b3e255664f4d6e838ff906900f6e8d Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Tue, 3 Nov 2020 13:04:46 -0800 Subject: [PATCH] doc: improve GSG navigation Feedback suggests we add more top-level navigation to the getting started guides, so let's include a local TOC as well as using the "numbered-step" style to top-level steps. Signed-off-by: David B. Kinder --- doc/getting-started/building-from-source.rst | 7 ++-- doc/getting-started/rt_industry_ubuntu.rst | 32 ++++++++++++------- doc/tutorials/using_hybrid_mode_on_nuc.rst | 21 +++++++++--- doc/tutorials/using_partition_mode_on_nuc.rst | 16 ++++++++-- 4 files changed, 54 insertions(+), 22 deletions(-) diff --git a/doc/getting-started/building-from-source.rst b/doc/getting-started/building-from-source.rst index 1a80bcee0..aae678cd9 100644 --- a/doc/getting-started/building-from-source.rst +++ b/doc/getting-started/building-from-source.rst @@ -3,9 +3,6 @@ Build ACRN from Source ###################### -Introduction -************ - Following a general embedded-system programming model, the ACRN hypervisor is designed to be customized at build time per hardware platform and per usage scenario, rather than one binary for all @@ -40,6 +37,10 @@ the ACRN hypervisor for the following reasons: Build the ACRN hypervisor, device model, and tools from source by following these steps. +.. contents:: + :local: + :depth: 1 + .. _install-build-tools-dependencies: .. rst-class:: numbered-step diff --git a/doc/getting-started/rt_industry_ubuntu.rst b/doc/getting-started/rt_industry_ubuntu.rst index aeccc39ac..566987c55 100644 --- a/doc/getting-started/rt_industry_ubuntu.rst +++ b/doc/getting-started/rt_industry_ubuntu.rst @@ -3,6 +3,10 @@ Getting Started Guide for ACRN Industry Scenario with Ubuntu Service VM ####################################################################### +.. contents:: + :local: + :depth: 1 + Verified version **************** @@ -23,13 +27,13 @@ Prerequisites - Ethernet cables - A grub-2.04-7 bootloader with the following patch: - http://git.savannah.gnu.org/cgit/grub.git/commit/?id=0f3f5b7c13fa9b677a64cf11f20eca0f850a2b20: multiboot2: Set min address for mbi allocation to 0x1000 + http://git.savannah.gnu.org/cgit/grub.git/commit/?id=0f3f5b7c13fa9b677a64cf11f20eca0f850a2b20: + multiboot2: Set min address for mbi allocation to 0x1000 -Install Ubuntu for the Service and User VMs -******************************************* +.. rst-class:: numbered-step Hardware Connection -=================== +******************* Connect the WHL Maxtang with the appropriate external devices. @@ -42,11 +46,10 @@ Connect the WHL Maxtang with the appropriate external devices. .. figure:: images/rt-ind-ubun-hw-2.png -Install the Ubuntu User VM (RTVM) on the SATA disk -================================================== +.. rst-class:: numbered-step -Install Ubuntu on the SATA disk -------------------------------- +Install the Ubuntu User VM (RTVM) on the SATA disk +************************************************** .. note:: The WHL Maxtang machine contains both an NVMe and SATA disk. Before you install the Ubuntu User VM on the SATA disk, either @@ -74,11 +77,10 @@ Install Ubuntu on the SATA disk This Ubuntu installation will be modified later (see `Build and Install the RT kernel for the Ubuntu User VM`_) to turn it into a real-time User VM (RTVM). -Install the Ubuntu Service VM on the NVMe disk -============================================== +.. rst-class:: numbered-step -Install Ubuntu on the NVMe disk -------------------------------- +Install the Ubuntu Service VM on the NVMe disk +********************************************** .. note:: Before you install the Ubuntu Service VM on the NVMe disk, either remove the SATA disk or disable it in the BIOS. Disable it by going to: @@ -106,6 +108,8 @@ Install Ubuntu on the NVMe disk .. note:: Set ``acrn`` as the username for the Ubuntu Service VM. +.. rst-class:: numbered-step + Build and Install ACRN on Ubuntu ******************************** @@ -402,6 +406,8 @@ Follow these instructions to build the RT kernel. $ sudo cp -r /mnt/lib/modules/lib/modules/4.19.72-rt25 /mnt/lib/modules/ $ sudo cd ~ && sudo umount /mnt && sync +.. rst-class:: numbered-step + Launch the RTVM *************** @@ -601,6 +607,8 @@ Run cyclictest :-q: quiet mode; print a summary only on exit :-H 30000 --histfile=test.log: dump the latency histogram to a local file +.. rst-class:: numbered-step + Launch the Windows VM ********************* diff --git a/doc/tutorials/using_hybrid_mode_on_nuc.rst b/doc/tutorials/using_hybrid_mode_on_nuc.rst index 97a60747a..365797342 100644 --- a/doc/tutorials/using_hybrid_mode_on_nuc.rst +++ b/doc/tutorials/using_hybrid_mode_on_nuc.rst @@ -2,11 +2,10 @@ Getting Started Guide for ACRN hybrid mode ########################################## + ACRN hypervisor supports a hybrid scenario where the User VM (such as Zephyr or Ubuntu) runs in a pre-launched VM or in a post-launched VM that is -launched by a Device model in the Service VM. The following guidelines -describe how to set up the ACRN hypervisor hybrid scenario on the Intel NUC, -as shown in :numref:`hybrid_scenario_on_nuc`. +launched by a Device model in the Service VM. .. figure:: images/hybrid_scenario_on_nuc.png :align: center @@ -15,6 +14,14 @@ as shown in :numref:`hybrid_scenario_on_nuc`. The Hybrid scenario on the Intel NUC +The following guidelines +describe how to set up the ACRN hypervisor hybrid scenario on the Intel NUC, +as shown in :numref:`hybrid_scenario_on_nuc`. + +.. contents:: + :local: + :depth: 1 + Prerequisites ************* - Use the `Intel NUC Kit NUC7i7DNHE `_. @@ -22,6 +29,8 @@ Prerequisites - Install Ubuntu 18.04 on your SATA device or on the NVME disk of your Intel NUC. +.. rst-class:: numbered-step + Update Ubuntu GRUB ****************** @@ -78,8 +87,10 @@ Perform the following to update Ubuntu GRUB so it can boot the hypervisor and lo the ACRN hypervisor on the Intel NUC's display. The GRUB loader will boot the hypervisor, and the hypervisor will start the VMs automatically. -Hybrid Scenario Startup Checking -******************************** +.. rst-class:: numbered-step + +Hybrid Scenario Startup Check +***************************** #. Use these steps to verify that the hypervisor is properly running: a. Log in to the ACRN hypervisor shell from the serial console. diff --git a/doc/tutorials/using_partition_mode_on_nuc.rst b/doc/tutorials/using_partition_mode_on_nuc.rst index ebeb1400a..68e191add 100644 --- a/doc/tutorials/using_partition_mode_on_nuc.rst +++ b/doc/tutorials/using_partition_mode_on_nuc.rst @@ -10,6 +10,10 @@ guidelines provide step-by-step instructions on how to set up the ACRN hypervisor logical partition scenario on Intel NUC while running two pre-launched VMs. +.. contents:: + :local: + :depth: 1 + Validated Versions ****************** @@ -35,6 +39,8 @@ Prerequisites The two pre-launched VMs will mount the root file systems via the SATA controller and the USB controller respectively. +.. rst-class:: numbered-step + Update kernel image and modules of pre-launched VM ************************************************** #. On your development workstation, clone the ACRN kernel source tree, and @@ -97,6 +103,8 @@ Update kernel image and modules of pre-launched VM $ sudo cp /bzImage /boot/ +.. rst-class:: numbered-step + Update ACRN hypervisor image **************************** @@ -179,6 +187,8 @@ Update ACRN hypervisor image #. Copy the ``acrn.bin``, ``ACPI_VM0.bin``, and ``ACPI_VM1.bin`` from the removable disk to ``/boot`` directory. +.. rst-class:: numbered-step + Update Ubuntu GRUB to boot hypervisor and load kernel image *********************************************************** @@ -237,8 +247,10 @@ Update Ubuntu GRUB to boot hypervisor and load kernel image the Intel NUC's display. The GRUB loader will boot the hypervisor, and the hypervisor will automatically start the two pre-launched VMs. -Logical partition scenario startup checking -******************************************* +.. rst-class:: numbered-step + +Logical partition scenario startup check +**************************************** #. Use these steps to verify that the hypervisor is properly running: