From 7a09c81b10b96b585a48910c484f9e8349a75909 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Mon, 21 May 2018 14:35:12 -0700 Subject: [PATCH] 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 --- doc/primer/index.rst | 117 +++++++++++++++++++++++-------------------- 1 file changed, 63 insertions(+), 54 deletions(-) diff --git a/doc/primer/index.rst b/doc/primer/index.rst index 8998b86bd..7bccec736 100644 --- a/doc/primer/index.rst +++ b/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 -ACRN device model source tree provides the following top-level -directories: +hypervisor and device emulation feature. + +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 -Clear Linux environment. +There are two Device Manager memory allocation mechanisms available: -The pre-condition is like below: - - You have installed the Service OS (bare-metal for now) - - CL Bootloader is "\EFI\org.clearlinux\bootloaderx64.efi" - - Boot device is '/dev/sda' - - EFI System Partition (ESP) is '1' +- Contiguous Memory Allocator (CMA), and +- Huge Page Tables (HugeTLB). HugeTLB is the default. -Suggest to follow the following step: -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 - with the your native rootfs partition uuid. -5. Copy bsp/uefi/clearlinux/acrn.conf to loader\\entries\\ directory. -6. Reboot. +To choose CMA, do the following: +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 -be choose to support but hugetlb will become the default one. +To support HugeTLB, do the following: -To support CMA, please make sure: - 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 +1) Do huge page reservation -To support Hugetlb, please make sure: - 1) Do huge page reservation - - For 1G huge page reservation, add "hugepagesz=1G hugepages=reserved_pg_num" - like "hugepagesz=1G hugepages=4" to the SOS cmdline(in acrn.conf for EFI) - - For 2M huge page reservation, after SOS start up, - echo reserved_pg_num > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages - - NOTE: - You can use 2M reserving method to do reservation for 1G page size, but it - may fail. - For EFI platform, you may skip 1G page reservation by just using 2M page, - but make sure your huge page reservation size is enough for your usage. - 2) Let acrn-dm use hugetlb - - start acrn-dm with "-T" option + - For 1G huge page reservation, add ``hugepagesz=1G hugepages=reserved_pg_num`` + (for example, ``hugepagesz=1G hugepages=4``) to the SOS cmdline in + ``acrn.conf`` (for EFI) + + - For 2M huge page reservation, after the SOS starts up, run the + command:: + + echo reserved_pg_num > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages + + .. note:: + You can use 2M reserving method to do reservation for 1G page size, but it + may fail. For an EFI platform, you may skip 1G page reservation + 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.