diff --git a/doc/contribute/index.rst b/doc/contribute/index.rst deleted file mode 100644 index 196e9f09c..000000000 --- a/doc/contribute/index.rst +++ /dev/null @@ -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 diff --git a/doc/contribute/contribute_guidelines.rst b/doc/developer-guides/contribute_guidelines.rst similarity index 100% rename from doc/contribute/contribute_guidelines.rst rename to doc/developer-guides/contribute_guidelines.rst diff --git a/doc/contribute/doc_guidelines.rst b/doc/developer-guides/doc_guidelines.rst similarity index 100% rename from doc/contribute/doc_guidelines.rst rename to doc/developer-guides/doc_guidelines.rst diff --git a/doc/developer-guides/images/ACRN-favicon-32x32.png b/doc/developer-guides/images/ACRN-favicon-32x32.png new file mode 100644 index 000000000..eb4798442 Binary files /dev/null and b/doc/developer-guides/images/ACRN-favicon-32x32.png differ diff --git a/doc/developer-guides/images/ACRN_Logo_200w.png b/doc/developer-guides/images/ACRN_Logo_200w.png new file mode 100644 index 000000000..16ed1d565 Binary files /dev/null and b/doc/developer-guides/images/ACRN_Logo_200w.png differ diff --git a/doc/developer-guides/images/ACRN_Logo_300w.png b/doc/developer-guides/images/ACRN_Logo_300w.png new file mode 100644 index 000000000..c26a69b6d Binary files /dev/null and b/doc/developer-guides/images/ACRN_Logo_300w.png differ diff --git a/doc/developer-guides/images/ACRN_Logo_56h.png b/doc/developer-guides/images/ACRN_Logo_56h.png new file mode 100644 index 000000000..df74c0efc Binary files /dev/null and b/doc/developer-guides/images/ACRN_Logo_56h.png differ diff --git a/doc/developer-guides/images/ACRNlogo.png b/doc/developer-guides/images/ACRNlogo.png new file mode 100644 index 000000000..fa9a41959 Binary files /dev/null and b/doc/developer-guides/images/ACRNlogo.png differ diff --git a/doc/primer/images/primer-dma-address-mapping.png b/doc/developer-guides/images/primer-dma-address-mapping.png similarity index 100% rename from doc/primer/images/primer-dma-address-mapping.png rename to doc/developer-guides/images/primer-dma-address-mapping.png diff --git a/doc/primer/images/primer-host-gdt.png b/doc/developer-guides/images/primer-host-gdt.png similarity index 100% rename from doc/primer/images/primer-host-gdt.png rename to doc/developer-guides/images/primer-host-gdt.png diff --git a/doc/primer/images/primer-hypervisor-interrupt.png b/doc/developer-guides/images/primer-hypervisor-interrupt.png similarity index 100% rename from doc/primer/images/primer-hypervisor-interrupt.png rename to doc/developer-guides/images/primer-hypervisor-interrupt.png diff --git a/doc/primer/images/primer-mem-layout.png b/doc/developer-guides/images/primer-mem-layout.png similarity index 100% rename from doc/primer/images/primer-mem-layout.png rename to doc/developer-guides/images/primer-mem-layout.png diff --git a/doc/primer/images/primer-pirq-routing.png b/doc/developer-guides/images/primer-pirq-routing.png similarity index 100% rename from doc/primer/images/primer-pirq-routing.png rename to doc/developer-guides/images/primer-pirq-routing.png diff --git a/doc/primer/images/primer-pv-mapping.png b/doc/developer-guides/images/primer-pv-mapping.png similarity index 100% rename from doc/primer/images/primer-pv-mapping.png rename to doc/developer-guides/images/primer-pv-mapping.png diff --git a/doc/primer/images/primer-sos-ept-mapping.png b/doc/developer-guides/images/primer-sos-ept-mapping.png similarity index 100% rename from doc/primer/images/primer-sos-ept-mapping.png rename to doc/developer-guides/images/primer-sos-ept-mapping.png diff --git a/doc/primer/images/primer-symmetric-io.png b/doc/developer-guides/images/primer-symmetric-io.png similarity index 100% rename from doc/primer/images/primer-symmetric-io.png rename to doc/developer-guides/images/primer-symmetric-io.png diff --git a/doc/primer/images/primer-uos-ept-mapping.png b/doc/developer-guides/images/primer-uos-ept-mapping.png similarity index 100% rename from doc/primer/images/primer-uos-ept-mapping.png rename to doc/developer-guides/images/primer-uos-ept-mapping.png diff --git a/doc/primer/images/primer-virtio-net.png b/doc/developer-guides/images/primer-virtio-net.png similarity index 100% rename from doc/primer/images/primer-virtio-net.png rename to doc/developer-guides/images/primer-virtio-net.png diff --git a/doc/developer-guides/index.rst b/doc/developer-guides/index.rst new file mode 100644 index 000000000..7da6f1b1c --- /dev/null +++ b/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 diff --git a/doc/primer/index.rst b/doc/developer-guides/primer.rst similarity index 100% rename from doc/primer/index.rst rename to doc/developer-guides/primer.rst diff --git a/doc/getting_started/index.rst b/doc/getting-started/apl-nuc.rst similarity index 93% rename from doc/getting_started/index.rst rename to doc/getting-started/apl-nuc.rst index f06d763a5..5605fb5da 100644 --- a/doc/getting_started/index.rst +++ b/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 `_ (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 `__ -- `UEFI BIOS (version 0047) `__. -- Memory: 8G DDR3 -- SSD: 120G SATA +- The `UP Squared board `_ (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: diff --git a/doc/hardware.rst b/doc/getting-started/hardware.rst similarity index 58% rename from doc/hardware.rst rename to doc/getting-started/hardware.rst index b66a7d861..a0e925441 100644 --- a/doc/hardware.rst +++ b/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 `_ (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 `_ and Intel `Pentium N4200 `_ SoCs. Both have been confirmed to work with ACRN. +The `UP Squared board `_ (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 `_ or contact one of the `local reseller `_. +The UP2 features Intel `Celeron N3550 +`_ +and Intel `Pentium N4200 +`_ +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 +`_ or contact one of the `local reseller +`_. + +Visit the :ref:`getting-started-up2` page for instructions on how to set +up ACRN on the UP2 board. diff --git a/doc/getting_started/images/gsg-bootmenu.png b/doc/getting-started/images/gsg-bootmenu.png similarity index 100% rename from doc/getting_started/images/gsg-bootmenu.png rename to doc/getting-started/images/gsg-bootmenu.png diff --git a/doc/getting_started/images/gsg-sos-console.png b/doc/getting-started/images/gsg-sos-console.png similarity index 100% rename from doc/getting_started/images/gsg-sos-console.png rename to doc/getting-started/images/gsg-sos-console.png diff --git a/doc/getting_started/images/gsg-successful-boot.png b/doc/getting-started/images/gsg-successful-boot.png similarity index 100% rename from doc/getting_started/images/gsg-successful-boot.png rename to doc/getting-started/images/gsg-successful-boot.png diff --git a/doc/getting_started/images/up2-gui.png b/doc/getting-started/images/up2-gui.png similarity index 100% rename from doc/getting_started/images/up2-gui.png rename to doc/getting-started/images/up2-gui.png diff --git a/doc/getting-started/index.rst b/doc/getting-started/index.rst new file mode 100644 index 000000000..2c8fc9da3 --- /dev/null +++ b/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 diff --git a/doc/getting_started/up2.rst b/doc/getting-started/up2.rst similarity index 56% rename from doc/getting_started/up2.rst rename to doc/getting-started/up2.rst index 7a21d8bb8..1fad73a98 100644 --- a/doc/getting_started/up2.rst +++ b/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 `_ (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 `_ and Intel `Pentium N4200 `_ SoCs. Both have been confirmed to work with ACRN. +The `UP Squared board `_ (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 +`_ +and Intel `Pentium N4200 +`_ +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 `_ 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 `_. 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 `_ +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 +`_. 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 @@ -36,16 +54,16 @@ You will need to keep these in mind in a few places: # mount /dev/mmcblk0p1 /mnt * When adjusting the ``acrn.conf`` file - + * Change the ``options`` line and set ``pci_devices_ignore=(0:18:1)`` * Set the ``root=`` parameter using the ``PARTUUID`` or device name directly * When configuring the EFI firmware to boot the ACRN hypervisor by default - .. code-block:: console + .. code-block:: console - # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/mmcblk0 -p 1 -L "ACRN Hypervisor" \ - -u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=mmio@0x9141e000" + # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/mmcblk0 -p 1 -L "ACRN Hypervisor" \ + -u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=mmio@0x9141e000" UP2 serial port setting ======================= @@ -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). diff --git a/doc/howtos/index.rst b/doc/howtos/index.rst deleted file mode 100644 index 8f3bedc53..000000000 --- a/doc/howtos/index.rst +++ /dev/null @@ -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/* diff --git a/doc/howtos/tech/placeholder.rst b/doc/howtos/tech/placeholder.rst deleted file mode 100644 index 01ea3aa10..000000000 --- a/doc/howtos/tech/placeholder.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _wip: - -Work in Progress -################ - -This is a placeholder doc for technical how-to articles in-progress. diff --git a/doc/index.rst b/doc/index.rst index eb7c67044..3eb8c9b44 100644 --- a/doc/index.rst +++ b/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 ****************** diff --git a/doc/howtos/process/docbuild.rst b/doc/tutorials/docbuild.rst similarity index 99% rename from doc/howtos/process/docbuild.rst rename to doc/tutorials/docbuild.rst index c679edd33..63575ad93 100644 --- a/doc/howtos/process/docbuild.rst +++ b/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 diff --git a/doc/howtos/process/graphviz.rst b/doc/tutorials/graphviz.rst similarity index 100% rename from doc/howtos/process/graphviz.rst rename to doc/tutorials/graphviz.rst diff --git a/doc/howtos/process/acrn-doc-fork.png b/doc/tutorials/images/acrn-doc-fork.png similarity index 100% rename from doc/howtos/process/acrn-doc-fork.png rename to doc/tutorials/images/acrn-doc-fork.png diff --git a/doc/howtos/process/images/boot-flow.dot b/doc/tutorials/images/boot-flow.dot similarity index 100% rename from doc/howtos/process/images/boot-flow.dot rename to doc/tutorials/images/boot-flow.dot diff --git a/doc/howtos/process/images/circle-square.dot b/doc/tutorials/images/circle-square.dot similarity index 100% rename from doc/howtos/process/images/circle-square.dot rename to doc/tutorials/images/circle-square.dot diff --git a/doc/howtos/process/images/gaspump.dot b/doc/tutorials/images/gaspump.dot similarity index 100% rename from doc/howtos/process/images/gaspump.dot rename to doc/tutorials/images/gaspump.dot diff --git a/doc/howtos/process/images/node-shape-edges.dot b/doc/tutorials/images/node-shape-edges.dot similarity index 100% rename from doc/howtos/process/images/node-shape-edges.dot rename to doc/tutorials/images/node-shape-edges.dot diff --git a/doc/howtos/process/images/record.dot b/doc/tutorials/images/record.dot similarity index 100% rename from doc/howtos/process/images/record.dot rename to doc/tutorials/images/record.dot diff --git a/doc/tutorials/index.rst b/doc/tutorials/index.rst new file mode 100644 index 000000000..19da1d670 --- /dev/null +++ b/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: + + * diff --git a/doc/user-guides/acrn-shell.rst b/doc/user-guides/acrn-shell.rst new file mode 100644 index 000000000..1b9a02505 --- /dev/null +++ b/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 + - Pauses a specific VCPU + * - vcpu_resume + - Resumes a specific VCPU + * - vcpu_dumpreg + - Dumps registers for a specific VCPU + * - vcpu_dumpmem + - 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 + - Dumps the log buffer for the physical CPU + * - trace + - Dumps a CPU's recent events within milliseconds + * - get_loglevel + - Get the loglevel + * - set_loglevel [mem_loglevel] + - Set loglevel [0 (none) - 6 (verbose)] for the console and optionally + for memory + * - cpuid [subleaf] + - Displays the CPUID leaf [subleaf], in hexadecimal + * - crash + - Triggers a system crash diff --git a/doc/user-guides/index.rst b/doc/user-guides/index.rst new file mode 100644 index 000000000..c6ce7b0e3 --- /dev/null +++ b/doc/user-guides/index.rst @@ -0,0 +1,10 @@ +.. _userguides: + +User Guides +########### + +.. toctree:: + :maxdepth: 2 + + acrn-shell.rst + tools.rst diff --git a/doc/tools.rst b/doc/user-guides/tools.rst similarity index 81% rename from doc/tools.rst rename to doc/user-guides/tools.rst index a18016692..37c2c663f 100644 --- a/doc/tools.rst +++ b/doc/user-guides/tools.rst @@ -7,4 +7,4 @@ Tools :glob: :maxdepth: 1 - tools/** + ../tools/**