doc: general edit for typos

Fix typos and misspellings, and tweak CSS for spacing before lists.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2018-03-13 11:59:40 -07:00 committed by Jack Ren
parent 44b0ec0413
commit b170e295a7
10 changed files with 146 additions and 93 deletions

View File

@ -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

View File

@ -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

View File

@ -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 <acrnusj@gmail.com>
@ -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

View File

@ -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
<https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install>`__
@ -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.

View File

@ -16,3 +16,17 @@ Intel Apollo Lake NUC
<https://www.intel.com/content/www/us/en/products/boards-kits/nuc/kits/nuc6cayh.html>`_
* 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

View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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:

View File

@ -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;