From b170e295a7aa01f3b576a1cad8d3359ceb6b36bc Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Tue, 13 Mar 2018 11:59:40 -0700 Subject: [PATCH] doc: general edit for typos Fix typos and misspellings, and tweak CSS for spacing before lists. Signed-off-by: David B. Kinder --- doc/api/devicemodel_api.rst | 6 +++- doc/api/hypercall_api.rst | 6 +++- doc/contribute.rst | 63 ++++++++++++++++++++------------ doc/getting_started/index.rst | 38 +++++++++++--------- doc/hardware.rst | 14 ++++++++ doc/index.rst | 4 +-- doc/introduction/index.rst | 67 ++++++++++++++++++----------------- doc/primer/index.rst | 24 ++++++------- doc/release_notes.rst | 12 +++---- doc/static/acrn-custom.css | 5 +++ 10 files changed, 146 insertions(+), 93 deletions(-) diff --git a/doc/api/devicemodel_api.rst b/doc/api/devicemodel_api.rst index e40682eeb..ad91cfb75 100644 --- a/doc/api/devicemodel_api.rst +++ b/doc/api/devicemodel_api.rst @@ -3,7 +3,11 @@ Device Model APIs ################# -This section contains APIs for the SOS Device Model services. +This section contains APIs for the SOS Device Model services. Sources +for the Device Model are found in the `ACRN Device Model GitHub repo`_ + +.. _ACRN Device Model GitHub repo: + https://github.com/projectacrn/acrn-devicemodel/ .. doxygengroup:: acrn_virtio :project: Project ACRN diff --git a/doc/api/hypercall_api.rst b/doc/api/hypercall_api.rst index e9ddf2e6c..373108602 100644 --- a/doc/api/hypercall_api.rst +++ b/doc/api/hypercall_api.rst @@ -3,7 +3,11 @@ Hypercall APIs ############## -This section contains APIs for the hypercall services. +This section contains APIs for the hypercall services. Sources +for the Device Model are found in the `ACRN Hypervisor GitHub repo`_ + +.. _ACRN Hypervisor GitHub repo: + https://github.com/projectacrn/acrn-hypervisor/ .. doxygengroup:: acrn_hypercall :project: Project ACRN diff --git a/doc/contribute.rst b/doc/contribute.rst index 7c21efdf0..108e9cb73 100644 --- a/doc/contribute.rst +++ b/doc/contribute.rst @@ -78,8 +78,8 @@ agreement is shown below and at http://developercertificate.org/. DCO Sign-Off Methods ==================== -The DCO requires a sign-off message in the following format appear on each -commit in the pull request:: +The DCO requires that a sign-off message, in the following format, +appears on each commit in the pull request:: Signed-off-by: Acrnus Jones @@ -95,9 +95,9 @@ Prerequisites .. _project ACRN website: https://projectacrn.org As a contributor, you'll want to be familiar with project ACRN, how to -configure, install, and use it as explained in the `project ACRN website`_ -and how to set up your development environment as introduced in the -project ACRN `Getting Started Guide`_. +configure, install, and use it as explained on the +`project ACRN website`_, and how to set up your development environment +as introduced in the project ACRN `Getting Started Guide`_. .. _Getting Started Guide: https://projectacrn.github.io/getting_started/ @@ -114,17 +114,24 @@ Repository layout To clone the ACRN hypervisor repository use:: git clone https://github.com/projectacrn/acrn-hypervisor - + To clone the ACRN device model repository use:: git clone https://github.com/projectacrn/acrn-devicemodel +To clone the ACRN documentation repository use:: + + git clone https://github.com/projectacrn/acrn-documentation + The project ACRN directory structure is described in the `Hypervisor Primer`_ document. In addition to the ACRN hypervisor and device model itself, -you'll also find the sources for technical documentation, sample code -and supported board configurations. All of these are available for +you'll also find the sources for technical documentation available from +the `ACRN documentation site`_. All of these are available for developers to contribute to and enhance. +.. _ACRN documentation site: + https://projectacrn.github.io/ + .. _Hypervisor Primer: https://projectacrn.github.io/hypervisor_primer @@ -134,8 +141,9 @@ Submitting Issues .. _ACRN-dev mailing list: https://lists.projectacrn.org/g/acrn-dev -Before starting on a patch, first check in our issues in the `ACRN-dev -mailing list`_ system to see what's been reported on the issue you'd +Issue tracking for ACRN is done using the `ACRN-dev mailing list`_. +Before starting on a patch, first read through discussions in the `ACRN-dev +mailing list`_ to see what's been reported on the issue you'd like to address. Have a conversation on the `ACRN-dev mailing list`_ to see what others think of your issue (and proposed solution). You may find others that have encountered the issue you're finding, or that have @@ -158,7 +166,7 @@ Signed-off-by The name in the commit message ``Signed-off-by:`` line and your email must match the change authorship information. Make sure your :file:`.gitconfig` -is set up correctly: +is set up correctly by using: .. code-block:: console @@ -203,7 +211,8 @@ and test your changes thoroughly before submitting. The general GitHub workflow used by project ACRN developers uses a combination of command line Git commands and browser interaction with GitHub. As it is with Git, there are multiple ways of getting a task done. We'll describe a typical -workflow here: +workflow here for the acrn-hypervisor repo that can also be used for the +acrn-devicemodel and acrn-documentation repos: .. _Create a Fork of acrn-hypervisor: https://github.com/projectacrn/acrn-hypervisor#fork-destination-box @@ -232,14 +241,18 @@ workflow here: #. Make changes, test locally, change, test, test again, ... -#. When things look good, start the pull request process by adding your changed - files:: +#. When things look good, start the pull request process by checking + which files have not been staged:: + + git status + + Then add the changed files:: git add [file(s) that changed, add -p if you want to be more specific] - You can see files that are not yet staged using:: + (or to have all changed files added use):: - git status + git add -A #. Verify changes to be committed look as you expected:: @@ -259,9 +272,9 @@ workflow here: git push origin fix_comment_typo -#. In your web browser, go to your forked repo and click on the Compare & pull - request button for the branch you just worked on and you want to open a pull - request with. +#. In your web browser, go to your personal forked repo and click on the Compare & pull + request button for the branch you just worked on and you want to + submit to the upstream repo. #. Review the pull request changes, and verify that you are opening a pull request for the appropriate branch. The title and message from your commit message should @@ -285,7 +298,12 @@ workflow here: and use the same process described above to work on this new topic branch. #. If reviewers do request changes to your patch, you can interactively rebase - commit(s) to fix review issues. In your development repo:: + commit(s) to fix review issues. In your development repo, make the + needed changes on the branch you made the initial submission:: + + git checkout fix-comment-typo + + then:: git fetch --all git rebase --ignore-whitespace upstream/master @@ -311,8 +329,9 @@ workflow here: By force pushing your update, your original pull request will be updated with your changes so you won't need to resubmit the pull request. - - You can follow the same workflow for contributing to acrn-devicemodel. + + You can follow the same workflow for contributing to acrn-devicemodel + or acrn-documentation repos. Commit Guidelines diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst index 1009ed0d6..63f8c868c 100644 --- a/doc/getting_started/index.rst +++ b/doc/getting_started/index.rst @@ -5,9 +5,9 @@ Getting Started Guide 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 of the ACRN +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 -|reg| NUC, using the UEFI BIOS. +|reg| NUC. .. _Clear Linux: https://clearlinux.org @@ -16,7 +16,7 @@ Hardware setup The Intel |reg| NUC (NUC6CAYH) is the supported reference target platform for ACRN work, as described in :ref:`hardware`, and is the only -platform tested with these setup instructions. +platform currently tested with these setup instructions. The recommended NUC hardware configuration is: @@ -40,9 +40,11 @@ for downloading and flashing an updated BIOS for the NUC. Set up a Clear Linux Operating System ===================================== -Currently, an installable version of ARCN does not exist. Therefore, we -need to setup a base Clear Linux OS to bootstrap ACRN. -**ACRN requires Clear Linux version 21260 or newer.** +Currently, an installable version of ARCN does not exist. Therefore, you +need to setup a base Clear Linux OS to bootstrap ACRN on the NUC. You'll +need a network connection for your NUC to complete this setup. + +.. note:: ACRN requires Clear Linux version 21260 or newer. 1. Follow this `Clear Linux installation guide `__ @@ -71,11 +73,11 @@ need to setup a base Clear Linux OS to bootstrap ACRN. | /dev/sda3 | 111.3G | Linux root (x86-64) | +-------------+----------+-----------------------+ -4. After installation is complete, boot into Clear Linux and log in as - root and set a password. +4. After installation is complete, boot into Clear Linux, login as + root, and set a password. -5. Clear Linux is set to automatically update. If you do not wish for - autoupdate, issue this command: +5. Clear Linux is set to automatically update itself. If you do not want + it to autoupdate, issue this command: .. code-block:: none @@ -110,7 +112,7 @@ need to setup a base Clear Linux OS to bootstrap ACRN. Add the ACRN hypervisor to the EFI Partition ============================================ -In order to boot the ACRN SOS on the NUC, we need to add it to the EFI +In order to boot the ACRN SOS on the NUC, you'll need to add it to the EFI partition. Follow these steps: #. Mount the EFI partition and verify you have the following files: @@ -210,8 +212,9 @@ folder) as shown here: :caption: acrn-devicemodel/samples/bridge.sh :language: bash -By default, it is located in the ``/usr/share/acrn/demo/`` -directory. Use it directly by making it executable and running it: +By default, the script is located in the ``/usr/share/acrn/demo/`` +directory. Use it directly by making it executable and run it to create +a network bridge: .. code-block:: none @@ -256,8 +259,9 @@ Set up Reference UOS :caption: acrn-devicemodel/samples/launch_uos.sh :language: bash - By default, it is located in the ``/usr/share/acrn/demo/`` - directory. Use it directly by making it executable and running it: + By default, the script is located in the ``/usr/share/acrn/demo/`` + directory. Use it directly by making it executable and run it to + launch the User OS: .. code-block:: none @@ -266,7 +270,7 @@ Set up Reference UOS # ./launch_uos.sh #. At this point, you've successfully booted the ACRN system, - hypervisor, SOS and UOS: + hypervisor, SOS, and UOS: .. figure:: images/gsg-successful-boot.png :align: center @@ -277,7 +281,7 @@ Build ACRN from Source ********************** If you would like to build ACRN hypervisor and device model from source, -follow these steps: +follow these steps, using your NUC as a development system: #. On your Clear Linux system, install the os-clr-on-clr bundle to get the necessary tools. diff --git a/doc/hardware.rst b/doc/hardware.rst index 2ad50ed38..b18de43bc 100644 --- a/doc/hardware.rst +++ b/doc/hardware.rst @@ -16,3 +16,17 @@ Intel Apollo Lake NUC `_ * Intel |reg| Celeron |reg| Processor J3455 * Tested NUC with 8GB of RAM and using an 128GB SSD + +You can read a full `AnandTech review`_ of the NUC6CAYH NUC Kit and +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. + +.. _AnandTech review: + https://www.anandtech.com/show/12295/intel-nuc6cayh-arches-canyon-apollo-lake-ucff-pc-review + +.. _Amazon: + https://www.amazon.com/s/ref=nb_sb_noss_2?url=search-alias%3Daps&field-keywords=NUC6CAYH + +.. _SimplyNUC: + https://www.simplynuc.com/?s=NUC6CAYH&post_type=product diff --git a/doc/index.rst b/doc/index.rst index f5ee36689..118ebb5c5 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,8 +9,8 @@ For information about the changes and additions for releases, please consult the published :ref:`release_notes` documentation. Source code for Project ACRN is maintained in the -`Project ACRN GitHub repo`_, and is provided under the `BSD 3-clause license`_ (as found in -the LICENSE file in the project repo). +`Project ACRN GitHub repo`_, and is provided under the BSD 3-clause +license. .. _BSD 3-clause license: https://github.com/projectacrn/acrn-hypervisor/blob/doc/master/LICENSE diff --git a/doc/introduction/index.rst b/doc/introduction/index.rst index 280f8cf9f..1f14584d9 100644 --- a/doc/introduction/index.rst +++ b/doc/introduction/index.rst @@ -17,7 +17,10 @@ partitioning hypervisors. The ACRN hypervisor architecture partitions the system into different functional domains, with carefully selected guest OS sharing optimizations for IoT and embedded devices. -An interesting use case example for the ACRN Hypervisor is in automotive +Automotive Use Case Example +*************************** + +An interesting use case example for the ACRN Hypervisor is in an automotive scenario. The ACRN hypervisor can be used for building a Software Defined Cockpit (SDC) or an In-Vehicle Experience (IVE) solution. As a reference implementation, ACRN provides the basis for embedded @@ -33,28 +36,28 @@ considerations. An **Instrument Cluster (IC)** system is used to show the driver operational information about the vehicle, such as: -- the speed, the fuel level, trip mile and other driving information of - the car; -- projecting heads-up images on the windshield, with alerts for low - fuel or tire pressure; -- showing rear-view camera, and surround-view for parking assistance. +- the speed, the fuel level, trip mile and other driving information of + the car; +- projecting heads-up images on the windshield, with alerts for low + fuel or tire pressure; +- showing rear-view camera, and surround-view for parking assistance. An **In-Vehicle Infotainment (IVI)** system's capabilities can include: -- navigation systems, radios, and other entertainment systems; -- connection to mobile devices for phone calls, music, and applications - via voice recognition; -- control interaction by gesture recognition or touch. +- navigation systems, radios, and other entertainment systems; +- connection to mobile devices for phone calls, music, and applications + via voice recognition; +- control interaction by gesture recognition or touch. A **Rear Seat Entertainment (RSE)** system could run: -- entertainment system; -- virtual office; -- connection to the front-seat IVI system and mobile devices (cloud - connectivity). -- connection to mobile devices for phone calls, music, and - applications via voice recognition; -- control interaction by gesture recognition or touch +- entertainment system; +- virtual office; +- connection to the front-seat IVI system and mobile devices (cloud + connectivity). +- connection to mobile devices for phone calls, music, and + applications via voice recognition; +- control interaction by gesture recognition or touch The ACRN hypervisor can support both Linux\* VM and Android\* VM as a User OS, with the User OS managed by the ACRN hypervisor. Developers and @@ -73,14 +76,14 @@ hypervisor. This ACRN hypervisor block diagram shows: -- The ACRN hypervisor sits right on top of the bootloader for fast - booting capabilities. -- Partitioning of resources to ensure safety-critical and non-safety - critical domains are able to coexist on one platform. -- Rich I/O mediators allows various I/O devices shared across VMs, and - thus delivers a comprehensive user experience -- Multiple operating systems are supported by one SoC through efficient - virtualization. +- The ACRN hypervisor sits right on top of the bootloader for fast + booting capabilities. +- Partitioning of resources to ensure safety-critical and non-safety + critical domains are able to coexist on one platform. +- Rich I/O mediators allows various I/O devices shared across VMs, and + thus delivers a comprehensive user experience +- Multiple operating systems are supported by one SoC through efficient + virtualization. .. note:: The yellow color parts in :numref:`ivi-block` are part of the project @@ -145,11 +148,11 @@ on an Intel |reg| Architecture platform NUC (see :ref:`hardware`). The Boot process proceeds as follows: -1. UEFI verifies and boots the ACRN hypervisor and Service OS Bootloader -2. UEFI (or Service OS Bootloader) verifies and boots Service OS kernel -3. Service OS kernel verifies and loads ACRN Device Model and Virtual +#. UEFI verifies and boots the ACRN hypervisor and Service OS Bootloader +#. UEFI (or Service OS Bootloader) verifies and boots Service OS kernel +#. Service OS kernel verifies and loads ACRN Device Model and Virtual bootloader through dm-verity -4. Virtual bootloader starts the User-side verified boot process +#. Virtual bootloader starts the User-side verified boot process ACRN Hypervisor Architecture @@ -243,14 +246,14 @@ used to give VM applications (and OSes) access to these shared devices. Traditionally there are three architectural approaches to device emulation: -* The first architecture is device emulation within the hypervisor which +* The first architecture is **device emulation within the hypervisor** which is a common method implemented within the VMware\* workstation product (an operating system-based hypervisor). In this method, the hypervisor includes emulations of common devices that the various guest operating systems can share, including virtual disks, virtual network adapters, and other necessary platform elements. -* The second architecture is called user space device emulation. As the +* The second architecture is called **user space device emulation**. As the name implies, rather than the device emulation being embedded within the hypervisor, it is instead implemented in a separate user space application. QEMU, for example, provides this kind of device emulation @@ -262,7 +265,7 @@ emulation: functionality. * The third variation on hypervisor-based device emulation is - paravirtualized (PV) drivers. In this model introduced by the `XEN + **paravirtualized (PV) drivers**. In this model introduced by the `XEN project`_ the hypervisor includes the physical drivers, and each guest operating system includes a hypervisor-aware driver that works in concert with the hypervisor drivers. diff --git a/doc/primer/index.rst b/doc/primer/index.rst index 7f8d806b1..d894113f7 100644 --- a/doc/primer/index.rst +++ b/doc/primer/index.rst @@ -490,21 +490,21 @@ PIO/MMIO trap Flow Here is a description of the PIO/MMIO trap flow: -1. Instruction decoder: get the Guest Physical Address (GPA) from VM +#. Instruction decoder: get the Guest Physical Address (GPA) from VM Exit, go through gla2gpa() page walker if necessary. -2. Emulate the instruction. Here the hypervisor will have an address +#. Emulate the instruction. Here the hypervisor will have an address range check to see if the hypervisor is interested in this IO port or MMIO GPA access. -3. Hypervisor emulates vLAPIC, vIOAPIC, vPIC, and vUART only (for +#. Hypervisor emulates vLAPIC, vIOAPIC, vPIC, and vUART only (for Service OS only). Any other emulation request are forwarded to the SOS for handling. The vCPU raising the I/O request will halt until this I/O request is processed successfully. An IPI will send to vCPU0 of SOS to notify there is an I/O request waiting for service. -4. Service OS VHM module takes the I/O request and dispatches the request +#. Service OS VHM module takes the I/O request and dispatches the request to multiple clients. These clients could be SOS kernel space VBS-K, MPT, or User-land Device model. VHM I/O request server selects a default fallback client responsible to handle any I/O @@ -514,7 +514,7 @@ Here is a description of the PIO/MMIO trap flow: request falls into the client range, the I/O request server will send the request to that client. -5. Multiple clients - fallback client (Device Model in user-land), +#. Multiple clients - fallback client (Device Model in user-land), VBS-K client, MPT client. Once the I/O request emulation completes, the client updates the request status and notifies the hypervisor by a hypercall. @@ -560,12 +560,12 @@ hypervisor will support APIC-v and Post interrupts in a future release. vLAPIC provides the same feature as a native LAPIC: -- Mask/Unmask vectors -- Inject virtual vectors (Level or Edge trigger mode) to vCPU -- Notify vIOAPIC of EOI processing -- Provide TSC Timer service -- vLAPIC support CR8 to update TPR -- INIT/STARTUP handling +- Mask/Unmask vectors +- Inject virtual vectors (Level or Edge trigger mode) to vCPU +- Notify vIOAPIC of EOI processing +- Provide TSC Timer service +- vLAPIC support CR8 to update TPR +- INIT/STARTUP handling Virtual IOAPIC ============== @@ -695,7 +695,7 @@ all the Back-end Virtio drivers are implemented using the Virtio APIs and the FE drivers are re-using Linux standard Front-end Virtio drivers. Virtio-rnd -================= +========== The Virtio-rnd entropy device supplies high-quality randomness for guest use. The Virtio device ID of the Virtio-rnd device is 4, and supports diff --git a/doc/release_notes.rst b/doc/release_notes.rst index 32d81b941..8c11330b4 100644 --- a/doc/release_notes.rst +++ b/doc/release_notes.rst @@ -15,14 +15,14 @@ In March 2018, Intel announced the open source Project ACRN at the ACRN is a flexible, lightweight reference hypervisor, built with real-time and safety-criticality in mind, optimized to streamline -embedded development through an open source platform. +embedded development through an open source platform. Check out the +:ref:`introduction` for more information. The project ACRN reference code can be found on GitHub in https://github.com/projectacrn. It includes the ACRN hypervisor, the -ACRN device model and documentation. ACRN is a flexible, lightweight -hypervisor, built with real-time and safety-criticality in mind,it is -optimized to streamline embedded development through an open source -reference platform. ACRNs key features include: +ACRN device model, and documentation. + +ACRN's key features include: * Small footprint * Built with real-time in mind @@ -37,7 +37,7 @@ This version 0.1 release has the following software components: * The ACRN Device Model * The ACRN Virtio framework * The ACRN Block & NIC & console Virtio drivers -* The ACRN Virtio Backend Service(VBS) & Vibrio and Hypervisor Service Module(VHM). +* The ACRN Virtio Backend Service(VBS) & Virtio and Hypervisor Service Module(VHM). Version 0.1 features include: diff --git a/doc/static/acrn-custom.css b/doc/static/acrn-custom.css index 1fa996555..fc9f2774d 100644 --- a/doc/static/acrn-custom.css +++ b/doc/static/acrn-custom.css @@ -19,6 +19,11 @@ color: rgba(255,255,255,1); } +/* squish the space between a paragraph before a list */ +div > p + ul, div > p + ol { + margin-top: -20px; +} + /* add some space before the figure caption */ p.caption { # border-top: 1px solid;