github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-09-11 05:39:45 +00:00
Code Issues Projects Releases Wiki Activity

doc: reorganize documentation

Browse Source 
We've been expanding documentation, and now need to organize things a bit
cleaner and separate content into new major folders: Introduction, Getting
Started, User Guides, Developer Guides, Tutorials, and Release notes..

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder
2018-06-28 07:55:57 -07:00
committed by David Kinder
parent 5c75f29a2d
commit 3965593df6
43 changed files with 193 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

445
doc/developer-guides/contribute_guidelines.rst Normal file
View File

@@ -0,0 +1,445 @@
.. _contribute_guidelines:
Contribution Guidelines
#######################
As an open-source project, we welcome and encourage the community to
submit patches directly to project ACRN. In our collaborative open
source environment, standards and methods for submitting changes help
reduce the chaos that can result from an active development community.
This document explains how to participate in project conversations, log
and track bugs and enhancement requests, and submit patches to the
project so your patch will be accepted quickly in the codebase.
Licensing
*********
Licensing is very important to open source projects. It helps ensure the
software continues to be available under the terms that the author
desired.
Project ACRN uses a BSD-3-Clause license, as found in the
`LICENSE <https://github.com/projectacrn/acrn-hypervisor/blob/master/LICENSE>`__
in the project's GitHub repo.
A license tells you what rights you have as a developer, as provided by
the copyright holder. It is important that the contributor fully
understands the licensing rights and agrees to them. Sometimes the
copyright holder isn't the contributor, such as when the contributor is
doing work on behalf of a company.
.. _DCO:
Developer Certification of Origin (DCO)
***************************************
To make a good faith effort to ensure licensing criteria are met,
project ACRN requires the Developer Certificate of Origin (DCO) process
to be followed.
The DCO is an attestation attached to every contribution made by every
developer. In the commit message of the contribution, (described more
fully later in this document), the developer simply adds a
``Signed-off-by`` statement and thereby agrees to the DCO.
When a developer submits a patch, it is a commitment that the
contributor has the right to submit the patch per the license. The DCO
agreement is shown below and at http://developercertificate.org/.
.. code-block:: none
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the
best of my knowledge, is covered under an appropriate open
source license and I have the right under that license to
submit that work with modifications, whether created in whole
or in part by me, under the same open source license (unless
I am permitted to submit under a different license), as
Indicated in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including
all personal information I submit with it, including my
sign-off) is maintained indefinitely and may be redistributed
consistent with this project or the open source license(s)
involved.
DCO Sign-Off Methods
====================
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>
The DCO text can either be manually added to your commit body, or you can add
either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget
to add the sign-off you can also amend a previous commit with the sign-off by
running ``git commit --amend -s``. If you've pushed your changes to GitHub
already you'll need to force push your branch after this with ``git push -f``.
.. note::
The name and email address of the account you use to submit your PR must
match the name and email address on the ``Signed-off-by`` line in
your commit message.
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 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/
You should be familiar with common developer tools such as Git and
platforms such as GitHub.
If you haven't already done so, you'll need to create a (free) GitHub account
on https://github.com and have Git tools available on your development system.
Repository layout
*****************
To clone the ACRN hypervisor repository (including the hypervisor,
devicemodel, and doc folders) use::
git clone https://github.com/projectacrn/acrn-hypervisor
The project ACRN directory structure is described in the :ref:`primer`
document. In addition to the ACRN hypervisor and device model itself,
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/
Submitting Issues
******************
.. _ACRN-dev mailing list:
https://lists.projectacrn.org/g/acrn-dev
.. _ACRN hypervisor issues:
https://github.com/projectacrn/acrn-hypervisor/issues
Issue tracking for project ACRN bugs or enhancement requests is done using
GitHub issues in the `ACRN hypervisor issues`_ list. Before submitting a
bug or enhancement request, first check to see what's already been
reported, and add to that discussion if you have additional information.
(Be sure to check both the "open" and "closed" issues.)
You should also read through discussions in the `ACRN-dev mailing list`_
to see what's been reported on or discussed. You may find others that
have encountered the issue you're finding, or that have similar ideas
for changes or additions.
If you don't find an existing issue listed in the `ACRN hypervisor issues`_
list, then click on the "New Issue" button and provide a summary title
and more detailed description of your bug or enhancement request.
When you submit an issue (bug or feature request), the triage team will
review and comment on the submission, typically within a few business
days. Use the `ACRN hypervisor issues`_ list to track the status of
your submitted issues as well, or to add additional comments.
.. _Contribution Tools:
Contribution Tools and Git Setup
********************************
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 by using:
.. code-block:: console
git config --global user.name "David Developer"
git config --global user.email "david.developer@company.com"
Coding Style
************
Use these coding guidelines to ensure that your development complies with the
project's style and naming conventions.
.. _Linux kernel coding style:
https://kernel.org/doc/html/latest/process/coding-style.html
In general, follow the `Linux kernel coding style`_, with the
following exceptions:
* Add braces to every ``if`` and ``else`` body, even for single-line code
blocks. Use the ``--ignore BRACES`` flag to make *checkpatch* stop
complaining.
* Use spaces instead of tabs to align comments after declarations, as needed.
* Use C89-style single line comments, ``/* */``. The C99-style single line
comment, ``//``, is not allowed.
* Use ``/** */`` for doxygen comments that need to appear in the documentation.
.. _Contribution workflow:
Contribution Workflow
*********************
One general practice we encourage, is to make small,
controlled changes. This practice simplifies review, makes merging and
rebasing easier, and keeps the change history clear and clean.
When contributing to project ACRN, it is also important you provide as much
information as you can about your change, update appropriate documentation,
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 for the acrn-hypervisor repo, which includes the
source files for the hypervisor, devicemodel, and documentation:
.. _Create a Fork of acrn-hypervisor:
https://github.com/projectacrn/acrn-hypervisor#fork-destination-box
#. `Create a Fork of acrn-hypervisor`_
to your personal account on GitHub. (Click on the fork button in the top
right corner of the project acrn-hypervisor repo page in GitHub.)
When you want to submit a pull request with your changes, you'll
first submit them to your personal branch, and then to the project's
master branch for review and merging by the ACRN maintainers.
#. On your development computer, clone the fork you just made::
git clone https://github.com/<your github id>/acrn-hypervisor
This would be a good time to let Git know about the upstream repo too::
git remote add upstream https://github.com/projectacrn/acrn-hypervisor.git
and verify the remote repos::
git remote -v
#. Create a topic branch (off of master) for your work (if you're addressing
an issue, we suggest including the issue number in the branch name)::
git checkout master
git checkout -b fix_comment_typo
Give your branch a short descriptive name.
#. Make changes, test locally, change, test, test again, ...
#. 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]
(or to have all changed files staged, use)::
git add -A
#. Verify changes to be committed look as you expected::
git diff --cached
#. Commit your changes to your local repo::
git commit -s
The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit
message. Your commit will be rejected without this line that indicates your
agreement with the `DCO`_. See the `Commit Guidelines`_ section
below for specific guidelines for writing your commit messages.
#. Push your topic branch with your changes to your fork in your personal
GitHub account::
git push origin fix_comment_typo
#. 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 ACRN 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
appear as well.
#. GitHub will assign one or more suggested reviewers (based on the CODEOWNERS file
in the repo). If you are a project member, you can select additional reviewers
now too. If no reviewers are selected, the ACRN triage team will
assign reviewers as appropriate.
#. Click on the submit button and your pull request is sent and awaits review.
Email will be sent as review comments are made, or you can check on your
pull request at https://github.com/projectacrn/acrn-hypervisor/pulls.
#. While you're waiting for your pull request to be accepted and merged, you can
create another branch to work on another issue. (Be sure to make your new branch
off of master and not the previous branch.)::
git checkout master
git checkout -b fix_another_issue
and use the same process described above to work on this new topic branch.
#. If reviewers request changes to your patch, you can interactively rebase
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
make the requested changes, and then::
git fetch --all
git rebase --ignore-whitespace upstream/master
This is an important step to make sure your changes are properly
merged with changes from other developers that may have happened while you
were working on your changes.
The ``--ignore-whitespace`` option
stops ``git apply`` (called by rebase) from changing
any whitespace. If any merging issues are detected you can address them
with::
git rebase -i <offending-commit-id>
In the interactive rebase editor, replace pick with edit to select a specific
commit (if there's more than one in your pull request), or remove the line to
delete a commit entirely. Then edit files to fix the issues in the review.
As before, inspect and test your changes. When ready, continue the
patch submission::
git add [file(s)]
git rebase --continue
Update commit comment if needed, and continue::
git push --force origin fix_comment_typo
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
or acrn-documentation repos.
Commit Guidelines
*****************
Changes are submitted as Git commits. Each commit message must contain:
* A short and descriptive subject line that is less than 72 characters,
followed by a blank line. The subject line must include a prefix that
identifies the subsystem being changed, followed by a colon, and a short
title, for example: ``doc: update commit guidelines instructions``.
(If you're updating an existing file, you can use
``git log <filename>`` to see what developers used as the prefix for
previous patches of this file.)
* A change description with your logic or reasoning for the changes, followed
by a blank line.
* A Signed-off-by line, ``Signed-off-by: <name> <email>`` typically added
automatically by using ``git commit -s``
* If the change addresses an issue, include a line of the form::
Fixes #<brief description about the reported issue>.
All changes and topics sent to GitHub must be well-formed, as described above.
Commit Message Body
===================
When editing the commit message, please briefly explain what your change
does and why it's needed. A change summary of ``"Fixes stuff"`` will be rejected.
.. warning::
An empty change summary body is not permitted. Even for trivial changes, please
include a summary body in the commmit message.
The description body of the commit message must include:
* **what** the change does,
* **why** you chose that approach,
* **what** assumptions were made, and
* **how** you know it works -- for example, which tests you ran.
For examples of accepted commit messages, you can refer to the acrn-hypervisor GitHub
`changelog <https://github.com/projectacrn/acrn-hypervisor/commits/master>`__.
Other Commit Expectations
=========================
* Commits must build cleanly when applied on top of each other, thus avoiding
breaking bisectability.
* Each commit must address a single identifiable issue and must be
logically self-contained. Unrelated changes should be submitted as
separate commits.
* You may submit pull request RFCs (requests for comments) to send work
proposals, progress snapshots of your work, or to get early feedback on
features or changes that will affect multiple areas in the code base.
Identifying Contribution Origin
===============================
When adding a new file to the tree, it is important to detail the source of
origin on the file, provide attributions, and detail the intended usage. In
cases where the file is an original to acrn-hypervisor, the commit message should
include the following ("Original" is the assumption if no Origin tag is
present)::
Origin: Original
In cases where the file is imported from an external project, the commit
message shall contain details regarding the original project, the location of
the project, the SHA-id of the origin commit for the file, the intended
purpose, and if the file will be maintained by the acrn-hypervisor project,
(whether or not project ACRN will contain a localized branch or if
it is a downstream copy).
For example, a copy of a locally maintained import::
Origin: Contiki OS
License: BSD 3-Clause
URL: http://www.contiki-os.org/
commit: 853207acfdc6549b10eb3e44504b1a75ae1ad63a
Purpose: Introduction of networking stack.
Maintained-by: acrn-hypervisor
For example, a copy of an externally maintained import::
Origin: Tiny Crypt
License: BSD 3-Clause
URL: https://github.com/01org/tinycrypt
commit: 08ded7f21529c39e5133688ffb93a9d0c94e5c6e
Purpose: Introduction of TinyCrypt
Maintained-by: External

395
doc/developer-guides/doc_guidelines.rst Normal file
View File

@@ -0,0 +1,395 @@
.. _doc_guidelines:
Documentation Guidelines
########################
Project ACRN content is written using the `reStructuredText`_ markup
language (``.rst`` file extension) with Sphinx extensions, and processed
using Sphinx to create a formatted standalone website. Developers can
view this content either in its raw form as ``.rst`` markup files, or (with
Sphinx installed) they can build the documentation using the Makefile
(on Linux systems) to
generate the HTML content. The HTML content can then be viewed using a
web browser. This same ``.rst`` content is also fed into the
`Project ACRN documentation`_ website.
You can read details about `reStructuredText`_
and about `Sphinx extensions`_ from their respective websites.
.. _Sphinx extensions: http://www.sphinx-doc.org/en/stable/contents.html
.. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
.. _Sphinx Inline Markup: http://sphinx-doc.org/markup/inline.html#inline-markup
.. _Project ACRN documentation: http://projectacrn.github.io
This document provides a quick reference for commonly used reST and
Sphinx-defined directives and roles used to create the documentation
you're reading.
Headings
********
Document sections are identified through their heading titles,
indicated with an underline below the title text. (While reST allows
use of both and overline and matching underline to indicate a heading,
we only use an underline indicator for headings.) For consistency in
our documentation, we define the order of characters used to indicated
the nested table of contents levels:
* Use ``#`` for the Document title underline character
* Use ``*`` for the First sub-section heading level
* Use ``=`` for the Second sub-section heading level
* Use ``-`` for the Third sub-section heading level
Additional heading level depth is discouraged.
The heading underline must be at least as long as the title it's under.
Here's an example of nested heading levels and the appropriate
underlines to use:
.. code-block:: rest
Document Title heading
######################
Section 1.0 heading
*******************
Section 2.0 heading
*******************
Section 2.1 heading
===================
Section 2.1.1 heading
---------------------
Section 2.2 heading
===================
Section 3.0 heading
*******************
Content Highlighting
********************
Some common reST inline markup samples:
* one asterisk: ``*text*`` for emphasis (*italics*),
* two asterisks: ``**text**`` for strong emphasis (**boldface**), and
* two backquotes: ````text```` for ``inline code`` samples.
ReST rules for inline markup try to be forgiving to account for common
cases of using these marks. For example using an asterisk to indicate
multiplication, such as ``2 * (x + y)`` will not be interpreted as an
unterminated italics section. For inline markup, the characters between
the beginning and ending characters must not start or end with a space,
so ``*this is italics*`` ( *this is italics*) while ``* this isn't*``
(* this isn't*).
If asterisks or backquotes appear in running text and could be confused with
inline markup delimiters, you can eliminate the confusion by adding a
backslash (``\``) before it.
Lists
*****
For bullet lists, place an asterisk (``*``) or hyphen (``-``) at
the start of a paragraph and indent continuation lines with two
spaces.
The first item in a list (or sublist) must have a blank line before it
and should be indented at the same level as the preceding paragraph
(and not indented itself).
For numbered lists
start with a ``1.`` or ``a)`` for example, and continue with autonumbering by
using a ``#`` sign and a ``.`` or ``)`` as used in the first list item.
Indent continuation lines with spaces to align with the text of first
list item:
.. code-block:: rest
* This is a bulleted list.
* It has two items, the second
item and has more than one line of reST text. Additional lines
are indented to the first character of the
text of the bullet list.
1. This is a new numbered list. If there wasn't a blank line before it,
it would be a continuation of the previous list (or paragraph).
#. It has two items too.
a) This is a numbered list using alphabetic list headings
#) It has three items (and uses autonumbering for the rest of the list)
#) Here's the third item. Use consistent punctuation on the list
number.
#. This is an autonumbered list (default is to use numbers starting
with 1).
#. This is a second-level list under the first item (also
autonumbered). Notice the indenting.
#. And a second item in the nested list.
#. And a second item back in the containing list. No blank line
needed, but it wouldn't hurt for readability.
Definition lists (with a term and its definition) are a convenient way
to document a word or phrase with an explanation. For example this reST
content:
.. code-block:: rest
The Makefile has targets that include:
html
Build the HTML output for the project
clean
Remove all generated output, restoring the folders to a
clean state.
Would be rendered as:
The Makefile has targets that include:
html
Build the HTML output for the project
clean
Remove all generated output, restoring the folders to a
clean state.
Multi-column lists
******************
If you have a long bullet list of items, where each item is short,
you can indicate the list items should be rendered in multiple columns
with a special ``hlist`` directive:
.. code-block:: rest
.. hlist::
:columns: 3
* A list of
* short items
* that should be
* displayed
* horizontally
* so it doesn't
* use up so much
* space on
* the page
This would be rendered as:
.. hlist::
:columns: 3
* A list of
* short items
* that should be
* displayed
* horizontally
* so it doesn't
* use up so much
* space on
* the page
Note the optional ``:columns:`` parameter (default is two columns), and
all the list items are indented by three spaces.
File names and Commands
***********************
Sphinx extends reST by supporting additional inline markup elements (called
"roles") used to tag text with special
meanings and allow style output formatting. (You can refer to the `Sphinx Inline Markup`_
documentation for the full list).
For example, there are roles for marking :file:`filenames`
(``:file:`name```) and command names such as :command:`make`
(``:command:`make```). You can also use the \`\`inline code\`\`
markup (double backticks) to indicate a ``filename``.
Don't use items within a single backtick, for example ```word```.
.. _internal-linking:
Internal Cross-Reference Linking
********************************
ReST links are only supported within the current file using the
notation:
.. code-block:: rest
refer to the `internal-linking`_ page
which renders as,
refer to the `internal-linking`_ page
Note the use of a trailing
underscore to indicate an outbound link. In this example, the label was
added immediately before a heading, so the text that's displayed is the
heading text itself.
With Sphinx however, we can create
link-references to any tagged text within the project documentation.
Target locations within documents are defined with a label directive:
.. code-block:: rst
.. _my label name:
Note the leading underscore indicating an inbound link.
The content immediately following
this label is the target for a ``:ref:`my label name```
reference from anywhere within the documentation set.
The label should be added immediately before a heading so there's a
natural phrase to show when referencing this label (e.g., the heading
text).
This is the same directive used to
define a label that's a reference to a URL:
.. code-block:: rest
.. _Hypervisor Wikipedia Page:
https://en.wikipedia.org/wiki/Hypervisor
To enable easy cross-page linking within the site, each file should have
a reference label before its title so it can
be referenced from another file. These reference labels must be unique
across the whole site, so generic names such as "samples" should be
avoided. For example the top of this document's ``.rst`` file is:
.. code-block:: rst
.. _doc_guidelines:
Documentation Guidelines
########################
Other ``.rst`` documents can link to this document using the ``:ref:`doc_guidelines``` tag and
it will show up as :ref:`doc_guidelines`. This type of internal cross reference works across
multiple files, and the link text is obtained from the document source so if the title changes,
the link text will update as well.
There may be times where you'd like to change the link text that's shown
in the generated document. In this case, you can add specify alternate
text using ``:ref:`alternate text <doc_guidelines>``` (renders as
:ref:`alternate text <doc_guidelines>`).
Non-ASCII Characters
********************
You can insert non-ASCII characters such as a Trademark symbol (|trade|),
by using the notation ``|trade|``. (It's also allowed to use the UTF-8
characters directly.)
Available replacement names are defined in an include file used during the Sphinx processing
of the reST files. The names of these replacement characters are the same as used in HTML
entities used to insert characters in HTML, e.g., \&trade; and are defined in the
file ``sphinx_build/substitutions.txt`` as listed here:
.. literalinclude:: ../substitutions.txt
:language: rst
We've kept the substitutions list small but others can be added as
needed by submitting a change to the ``substitutions.txt`` file.
Code and Command Examples
*************************
Use the reST ``code-block`` directive to create a highlighted block of
fixed-width text, typically used for showing formatted code or console
commands and output. Smart syntax highlighting is also supported (using the
Pygments package). You can also directly specify the highlighting language.
For example:
.. code-block:: rest
.. code-block:: c
struct _k_object {
char *name;
u8_t perms[CONFIG_MAX_THREAD_BYTES];
u8_t type;
u8_t flags;
u32_t data;
} __packed;
Note the blank line between the ``code-block`` directive and the first
line of the code-block body, and the body content is indented three
spaces (to the first non-white space of the directive name).
This would be rendered as:
.. code-block:: c
struct _k_object {
char *name;
u8_t perms[CONFIG_MAX_THREAD_BYTES];
u8_t type;
u8_t flags;
u32_t data;
} __packed;
You can specify other languages for the ``code-block`` directive,
including ``c``, ``python``, and ``rst``, and also ``console``,
``bash``, or ``shell``. If you want no syntax highlighting, use the
language ``none``, for example:
.. code-block:: rest
.. code-block:: none
This would be a block of text styled with a background
and box, but with no syntax highlighting.
Would display as:
.. code-block:: none
This would be a block of text styled with a background
and box, but with no syntax highlighting.
There's a shorthand for writing code blocks too: end the introductory
paragraph with a double colon (``::``) and indent the code block content
by three spaces. On output, only one colon will be shown. The
highlighting package makes a best guess at the type of content in the
block and highlighting purposes. This can lead to some odd
highlighting in the generated output.
Tabs, spaces, and indenting
***************************
Indenting is significant in reST file content, and using spaces is
preferred. Extra indenting can (unintentionally) change the way content
is rendered too. For lists and directives, indent the content text to
the first non-white space in the preceding line. For example:
.. code-block:: rest
* List item that spans multiple lines of text
showing where to indent the continuation line.
1. And for numbered list items, the continuation
line should align with the text of the line above.
.. code-block::
The text within a directive block should align with the
first character of the directive name.
Keep the line length for documentation less than 80 characters to make
it easier for reviewing in GitHub. Long lines because of URL references
are an allowed exception.

BIN
doc/developer-guides/images/ACRN-favicon-32x32.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.6 KiB

BIN
doc/developer-guides/images/ACRN_Logo_200w.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
doc/developer-guides/images/ACRN_Logo_300w.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

BIN
doc/developer-guides/images/ACRN_Logo_56h.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
doc/developer-guides/images/ACRNlogo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.5 KiB

BIN
doc/developer-guides/images/primer-dma-address-mapping.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
doc/developer-guides/images/primer-host-gdt.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 66 KiB

BIN
doc/developer-guides/images/primer-hypervisor-interrupt.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 85 KiB

BIN
doc/developer-guides/images/primer-mem-layout.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

BIN
doc/developer-guides/images/primer-pirq-routing.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

BIN
doc/developer-guides/images/primer-pv-mapping.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
doc/developer-guides/images/primer-sos-ept-mapping.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
doc/developer-guides/images/primer-symmetric-io.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 89 KiB

BIN
doc/developer-guides/images/primer-uos-ept-mapping.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
doc/developer-guides/images/primer-virtio-net.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB

25
doc/developer-guides/index.rst Normal file
View File

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

938
doc/developer-guides/primer.rst Normal file
View File

@@ -0,0 +1,938 @@
.. _primer:
Developer Primer
################
This Developer Primer introduces the fundamental components of ACRN and
the virtualization technology used by this open source reference stack.
Code level documentation and additional details can be found by
consulting the :ref:`acrn_apis` documentation and the `source code in
GitHub`_.
.. _source code in GitHub: https://github.com/projectacrn
The ACRN Hypervisor acts as a host with full control of the processor(s)
and the hardware (physical memory, interrupt management and I/O). It
provides the User OS with an abstraction of a virtual platform, allowing
the guest to behave as if were executing directly on a logical
processor.
.. _source tree structure:
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 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
===========================
**arch/x86/**
hypervisor architecture, which includes arch x86 related source files
to run the hypervisor, such as CPU, memory, interrupt, and VMX.
**boot/**
boot stuff mainly including ACPI related
**bsp/**
board support package, used to support NUC with UEFI
**common/**
common source files for hypervisor, which including VM hypercall
definition, VM main loop, and VM software loader
**debug/**
all debug related source files, which will not be compiled for
release version, mainly including console, uart, logmsg and shell
**include/**
include files for all public APIs (doxygen comments in these source
files are used to generate the :ref:`acrn_apis` documentation)
**lib/**
runtime service libraries
ACRN Device Model source tree
=============================
**arch/x86/**
architecture-specific source files needed for the devicemodel
**core/**
ACRN Device model core logic (main loop, SOS interface, etc.)
**hw/**
Hardware emulation code, with the following subdirectories:
**pci/**
PCI devices, including VBS-Us (Virtio backend drivers in user-space).
**platform/**
platform devices such as uart, and keyboard.
**include/**
include files for all public APIs (doxygen comments in these source
files are used to generate the :ref:`acrn_apis` documentation)
**samples/**
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
==============================
Project ACRN documentation is written using the reStructuredText markup
language (.rst file extension) with Sphinx extensions, and processed
using Sphinx to create a formatted stand-alone website, (the one you're
reading now.) Developers can view this content either in its raw form as
.rst markup files in the acrn-documentation repo, or you can generate
the HTML content and view it with a web browser directly on your
workstation, useful if you're contributing documentation to the project.
**api/**
ReST files for API document generation
**custom-doxygen/**
Customization files for doxygen-generated html output (while
generated, we currently don't include the doxygen html output but do use
the XML output to feed into the Sphinx-generation process)
**getting_started/**
ReST files and images for the Getting Started Guide
**howtos/**
ReST files and images for Technical and Process how-to articles
**images/**
Image files not specific to a document (logos, and such)
**introduction/**
ReST files and images for the Introduction to Project ACRN
**primer/**
ReST files and images for the Developer Primer
**scripts/**
Files used to assist building the documentation set
**static/**
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
******************
The ACRN hypervisor uses static partitioning of the physical CPU cores,
providing each User OS a virtualized environment containing at least one
statically assigned physical CPU core. The CPUID features for a
partitioned physical core is the same as the native CPU features. CPU
power management (Cx/Px) is managed by the User OS.
The supported Intel |reg| NUC platform (see :ref:`hardware`) has a CPU
with four cores. The Service OS is assigned one core and the other three
cores are assigned to the User OS. ``XSAVE`` and ``XRSTOR`` instructions
(used to perform a full save/restore of the extended state in the
processor to/from memory) are currently not supported in the User OS.
(The kernel boot parameters must specify ``noxsave``). Processor core
sharing among User OSes is planned for a future release.
The following sections introduce CPU virtualization related
concepts and technologies.
Host GDT
========
The ACRN hypervisor initializes the host Global Descriptor Table (GDT),
used to define the characteristics of the various memory areas during
program execution. Code Segment ``CS:0x8`` and Data Segment ``DS:0x10``
are configured as Hypervisor selectors, with their settings in host the
GDT as shown in :numref:`host-gdt`:
.. figure:: images/primer-host-gdt.png
:align: center
:name: host-gdt
Host GDT
Host IDT
========
The ACRN hypervisor installs interrupt gates for both Exceptions and
Vectors. That means exceptions and interrupts will automatically disable
interrupts. The ``HOST_GDT_RING0_CODE_SEL`` is used in the Host IDT
table.
Guest SMP Booting
=================
The Bootstrap Processor (BSP) vCPU for the User OS boots into x64 long
mode directly, while the Application Processors (AP) vCPU boots into
real mode. The virtualized Local Advanced Programmable Interrupt
Controller (vLAPIC) for the User OS in the hypervisor emulates the
INIT/STARTUP signals.
The AP vCPU belonging to the User OS begins in an infinite loop, waiting
for an INIT signal. Once the User OS issues a Startup IPI (SIPI) signal
to another vCPU, the vLAPIC traps the request, resets the target vCPU,
and then enters the ``INIT->STARTUP#1->STARTUP#2`` cycle to boot the
vCPUs for the User OS.
VMX configuration
=================
ACRN hypervisor has the Virtual Machine configuration (VMX) shown in
:numref:`VMX_MSR` below. (These configuration settings may change in the future, according to
virtualization policies.)
.. table:: VMX Configuration
:align: center
:widths: auto
:name: VMX_MSR
+----------------------------------------+----------------+---------------------------------------+
| **VMX MSR** | **Bits** | **Description** |
+========================================+================+=======================================+
| **MSR\_IA32\_VMX\_PINBASED\_CTLS** | Bit0 set | Enable External IRQ VM Exit |
+ +----------------+---------------------------------------+
| | Bit6 set | Enable HV pre-40ms Preemption timer |
+ +----------------+---------------------------------------+
| | Bit7 clr | Post interrupt did not support |
+----------------------------------------+----------------+---------------------------------------+
| **MSR\_IA32\_VMX\_PROCBASED\_CTLS** | Bit25 set | Enable I/O bitmap |
+ +----------------+---------------------------------------+
| | Bit28 set | Enable MSR bitmap |
+ +----------------+---------------------------------------+
| | Bit19,20 set | Enable CR8 store/load |
+----------------------------------------+----------------+---------------------------------------+
| **MSR\_IA32\_VMX\_PROCBASED\_CTLS2** | Bit1 set | Enable EPT |
+ +----------------+---------------------------------------+
| | Bit7 set | Allow guest real mode |
+----------------------------------------+----------------+---------------------------------------+
| **MSR\_IA32\_VMX\_EXIT\_CTLS** | Bit15 | VMX Exit auto ack vector |
+ +----------------+---------------------------------------+
| | Bit18,19 | MSR IA32\_PAT save/load |
+ +----------------+---------------------------------------+
| | Bit20,21 | MSR IA32\_EFER save/load |
+ +----------------+---------------------------------------+
| | Bit9 | 64-bit mode after VM Exit |
+----------------------------------------+----------------+---------------------------------------+
CPUID and Guest TSC calibration
===============================
User OS access to CPUID will be trapped by ACRN hypervisor, however
the ACRN hypervisor will pass through most of the native CPUID
information to the guest, except the virtualized CPUID 0x1 (to
provide fake x86_model).
The Time Stamp Counter (TSC) is a 64-bit register present on all x86
processors that counts the number of cycles since reset. ACRN hypervisor
also virtualizes ``MSR_PLATFORM_INFO`` and ``MSR_ATOM_FSB_FREQ``.
RDTSC/RDTSCP
============
User OS vCPU reads of ``RDTSC``, ``RDTSCP``, or ``MSR_IA32_TSC_AUX``
will not make the VM Exit to the hypervisor. Thus the vCPUID provided by
``MSR_IA32_TSC_AUX`` can be changed via the User OS.
The ``RDTSCP`` instruction is widely used by the ACRN hypervisor to
identify the current CPU (and read the current value of the processor's
time-stamp counter). Because there is no VM Exit for
``MSR_IA32_TSC_AUX`` msr register, the hypervisor will save and restore
the ``MSR_IA32_TSC_AUX`` value on every VM Exit and Enter. Before the
hypervisor restores the host CPU ID, we must not use a ``RDTSCP``
instruction because it would return the vCPU ID instead of host CPU ID.
CR Register virtualization
==========================
Guest CR8 access will make the VM Exit, and is emulated in the
hypervisor for vLAPIC to update its PPR register. Guest access to CR3
will not make the VM Exit.
MSR BITMAP
==========
In the ACRN hypervisor, only these module-specific registers (MSR) are
supported:
**MSR_IA32_TSC_DEADLINE**
emulates Guest TSC timer program
**MSR_PLATFORM_INFO**
emulates a fake X86 module
**MSR_ATOM_FSB_FREQ**
provides the CPU frequency directly via this MSR to avoid TSC calibration
I/O BITMAP
==========
All User OS I/O port accesses are trapped into the ACRN hypervisor by
default. Most of the Service OS I/O port accesses are not trapped into
the ACRN hypervisor, allowing the Service OS direct access to the
hardware port.
The Service OS I/O trap policy is:
**0x3F8/0x3FC**
for emulated vUART inside hypervisor for SOS only, will be trapped
**0x20/0xA0/0x460**
for vPIC emulation in hypervisor, will be trapped
**0xCF8/0xCFC**
for hypervisor PCI device interception, will be trapped
Exceptions
==========
The User OS handles its exceptions inside the VM, including page fault,
GP, etc. A #MC and #DB exception causes a VM Exit to the ACRN hypervisor
console.
Memory virtualization
*********************
ACRN hypervisor provides memory virtualization by using a static
partition of system memory. Each virtual machine owns its own contiguous
partition of memory, with the Service OS staying in lower memory and the
User OS instances in high memory. (High memory is memory which is not
permanently mapped in the kernel address space, while Low Memory is
always mapped, so you can access it in the kernel simply by
dereferencing a pointer.) In future implementations, this will evolve to
utilize EPT/VT-d.
ACRN hypervisor memory is not visible to any User OS. In the ACRN
hypervisor, there are a few memory accesses that need to work
efficiently:
- ACRN hypervisor to access host memory
- vCPU per VM to access guest memory
- vCPU per VM to access host memory
- vCPU per VM to access MMIO memory
The rest of this section introduces how these kinds of memory accesses
are managed. It gives an overview of physical memory layout,
Paravirtualization (MMU) memory mapping in the hypervisor and VMs, and
Host-Guest Extended Page Table (EPT) memory mapping for each VM.
Physical Memory Layout
======================
The Physical Memory Layout Example for Service OS & User OS is shown in
:numref:`primer-mem-layout` below:
.. figure:: images/primer-mem-layout.png
:align: center
:name: primer-mem-layout
Memory Layout
:numref:`primer-mem-layout` shows an example of physical memory layout
of the Service and User OS. The Service OS accepts the whole e820 table
(all usable memory address ranges not reserved for use by the BIOS)
after filtering out the Hypervisor memory too. From the SOS's point of
view, it takes control of all available physical memory, including User
OS memory, not used by the hypervisor (or BIOS). Each User OSes memory
is allocated from (High) SOS memory and the User OS only owns this
section of memory control.
Some of the physical memory of a 32-bit machine, needs to be sacrificed
by making it hidden so memory-mapped I/O (MMIO) devices have room to
communicate. This creates an MMIO hole for VMs to access some range of
MMIO addresses directly for communicating to devices; or they may need
the hypervisor to trap some range of MMIO to do device emulation. This
access control is done through EPT mapping.
PV (MMU) Memory Mapping in the Hypervisor
=========================================
.. figure:: images/primer-pv-mapping.png
:align: center
:name: primer-pv-mapping
ACRN Hypervisor PV Mapping Example
The ACRN hypervisor is trusted and can access and control all system
memory, as shown in :numref:`primer-pv-mapping`. Because the hypervisor
is running in protected mode, an MMU page table must be prepared for its
PV translation. To simplify things, the PV translation page table is set
as a 1:1 mapping. Some MMIO range mappings could be removed if they are
not needed. This PV page table is created when the hypervisor memory is
first initialized.
PV (MMU) Memory Mapping in VMs
==============================
As mentioned earlier, the Primary vCPU starts to run in protected mode
when its VM is started. But before it begins, a temporary PV (MMU) page
table must be prepared..
This page table is a 1:1 mapping for 4 Gb, and only lives for a short
time when the vCPU first runs. After the vCPU starts to run its kernel
image (for example Linux\*), the kernel will create its own PV page
tables, after which, the temporary page table will be obsoleted.
Host-Guest (EPT) Memory Mapping
===============================
The VMs (both SOS and UOS) need to create an Extended Page Table (EPT) to
access the host physical memory based on its guest physical memory. The
guest VMs also need to set an MMIO trap to trigger EPT violations for
device emulation (such as IOAPIC, and LAPIC). This memory layout is
shown in :numref:`primer-sos-ept-mapping`:
.. figure:: images/primer-sos-ept-mapping.png
:align: center
:name: primer-sos-ept-mapping
SOS EPT Mapping Example
The SOS takes control of all the host physical memory space: its EPT
mapping covers almost all of the host memory except that reserved for
the hypervisor (HV) and a few MMIO trap ranges for IOAPIC & LAPIC
emulation. The guest to host mapping for SOS is 1:1.
.. figure:: images/primer-uos-ept-mapping.png
:align: center
:name: primer-uos-ept-mapping
UOS EPT Mapping Example
However, for the UOS, its memory EPT mapping is linear but with an
offset (as shown in :numref:`primer-uos-ept-mapping`). The MMIO hole is
not mapped to trap all MMIO accesses from the UOS (and do emulating in
the device model). To support pass through devices in the future, some
MMIO range mapping may be added.
Graphic mediation
*****************
Intel |reg| Graphics Virtualization Technology –g (Intel |reg| GVT-g)
provides GPU sharing capability to multiple VMs by using a mediated
pass-through technique. This allows a VM to access performance critical
I/O resources (usually partitioned) directly, without intervention from
the hypervisor in most cases.
Privileged operations from this VM are trap-and-emulated to provide
secure isolation among VMs. The Hypervisor must ensure that no
vulnerability is exposed when assigning performance-critical resource to
each VM. When a performance-critical resource cannot be partitioned, a
scheduler must be implemented (either in software or hardware) to allow
time-based sharing among multiple VMs. In this case, the device must
allow the hypervisor to save and restore the hardware state associated
with the shared resource, either through direct I/O register read/write
(when there is no software invisible state) or through a device-specific
context save/restore mechanism (where there is a software invisible
state).
In the initial release of Project ACRN, graphic mediation is not
enabled, and is planned for a future release.
I/O emulation
*************
The I/O path is explained in the :ref:`ACRN-io-mediator` section of the
:ref:`introduction`. The following sections, provide additional device
assignment management and PIO/MMIO trap flow introduction.
Device Assignment Management
============================
ACRN hypervisor provides major device assignment management. Since the
hypervisor owns all native vectors and IRQs, there must be a mapping
table to handle the Guest IRQ/Vector to Host IRQ/Vector. Currently we
assign all devices to VM0 except the UART.
If a PCI device (with MSI/MSI-x) is assigned to Guest, the User OS will
program the PCI config space and set the guest vector to this device. A
Hypercall ``CWP_VM_PCI_MSIX_FIXUP`` is provided. Once the guest programs
the guest vector, the User OS may call this hypercall to notify the ACRN
hypervisor. The hypervisor allocates a host vector, creates a guest-host
mapping relation, and replaces the guest vector with a real native
vector for the device:
**PCI MSI/MSI-X**
PCI Message Signaled Interrupts (MSI/MSX-x) from
devices can be triggered from a hypercall when a guest program
vectors. All PCI devices are programed with real vectors
allocated by the Hypervisor.
**PCI/INTx**
Device assignment is triggered when the guest programs
the virtual Advanced I/O Programmable Interrupt Controller
(vIOAPC) Redirection Table Entries (RTE).
**Legacy**
Legacy devices are assigned to VM0.
User OS device assignment is similar to the above, except the User OS
doesn't call hypercall. Instead, the Guest program PCI configuration
space will be trapped into the Device Module, and Device Module may
issue hypercall to notify hypervisor the guest vector is changing.
Currently, there are two types of I/O Emulation supported: MMIO and
PORTIO trap handling. MMIO emulation is triggered by an EPT violation
VMExit only. If there is an EPT misconfiguration and VMExit occurs, the
hypervisor will halt the system. (Because the hypervisor set up all EPT
page table mapping at the beginning of the Guest boot, there should not
be an EPT misconfiguration.)
There are multiple places where I/O emulation can happen - in ACRN
hypervisor, Service OS Kernel VHM module, or in the Service OS Userland
ACRN Device Module.
PIO/MMIO trap Flow
==================
Here is a description of the PIO/MMIO trap flow:
#. Instruction decoder: get the Guest Physical Address (GPA) from VM
Exit, go through gla2gpa() page walker if necessary.
#. 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.
#. 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.
#. 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
request not handled by other clients. (The Device Manager is the
default fallback client.) Each client needs to register its I/O
range or specific PCI bus/device/function (BDF) numbers. If an I/O
request falls into the client range, the I/O request server will
send the request to that client.
#. 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.
Hypervisor picks up that request, do any necessary cleanup,
and resume the Guest vCPU.
Most I/O emulation tasks are done by the SOS CPU, and requests come from
UOS vCPUs.
Virtual interrupt
*****************
All interrupts received by the User OS comes from a virtual interrupt
injected by a virtual vLAPIC, vIOAPIC, or vPIC. All device emulation is
done inside the SOS Userspace device model. However for performance
consideration, vLAPIC, vIOAPIC, and vPIC devices are emulated inside the
ACRN hypervisor directly. From the guest point of view, vPIC uses
Virtual Wire Mode via vIOAPIC.
The symmetric I/O Mode is shown in :numref:`primer-symmetric-io`:
.. figure:: images/primer-symmetric-io.png
:align: center
:name: primer-symmetric-io
Symmetric I/O Mode
**Kernel boot param with vPIC**
add "maxcpu=0" to User OS to use PIC
**Kernel boot param with vIOAPIC**
add "maxcpu=1" (as long as not "0") User OS will use IOAPIC. Keep
IOAPIC pin2 as source of PIC.
Virtual LAPIC
=============
The LAPIC (Local Advanced Programmable interrupt Controller) is
virtualized for SOS or UOS. The vLAPIC is currently emulated by a Guest
MMIO trap to GPA address range: 0xFEE00000 - 0xFEE100000 (1MB). ACRN
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
Virtual IOAPIC
==============
A vIOAPIC is emulated by the hypervisor when the Guest accesses MMIO GPA
Range: 0xFEC00000 - 0xFEC01000. The vIOAPIC for the SOS will match the
same pin numbers as the native HW IOAPIC. The vIOAPIC for UOS only
provides 24 Pins. When a vIOAPIC PIN is asserted, the vIOAPIC calls
vLAPIC APIs to inject the vector to the Guest.
Virtual PIC
===========
A vPIC is required for TSC calculation. Normally the UOS boots with a
vIOAPIC. A vPIC is a source of external interrupts to the Guest. On
every VMExit, the hypervisor checks if there are pending external PIC
interrupts.
Virtual Interrupt Injection
===========================
The source of virtual interrupts comes from either the Device Module or
from assigned devices:
**SOS assigned devices**
As we assigned all devices to SOS directly whenever a devices'
physical interrupts come, we inject the corresponding virtual interrupts
to SOS via the vLAPIC/vIOAPIC. In this case, the SOS doesn't use the
vPIC and does not have emulated devices.
**UOS assigned devices**
Only PCI devices are assigned to UOS, and virtual interrupt injection
follows the same way as the SOS. A virtual interrupt injection operation
is triggered when a device's physical interrupt is triggered.
**UOS emulated devices**
Device Module (user-land Device Model) is responsible for UOS emulated
devices' interrupt lifecycle management. The Device Model knows when an
emulated device needs to assert a virtual IOPAIC/PIC Pin or needs to
send a virtual MSI vector to the Guest. This logic is entirely handled
by the Device Model.
:numref:`primer-hypervisor-interrupt` shows how the hypervisor handles
interrupt processing and pending interrupts (acrn_do_intr_process):
.. figure:: images/primer-hypervisor-interrupt.png
:align: center
:name: primer-hypervisor-interrupt
Hypervisor Interrupt handler
There are many cases where the Guest RFLAG.IF is cleared and interrupts
are disabled. The hypervisor will check if the Guest IRQ window is
available before injection. NMI is unmasked interrupt injection
regardless of existing guest IRQ window status. If the current IRQ
windows is not available, hypervisor enables
``MSR_IA32_VMX_PROCBASED_CTLS_IRQ_WIN`` (PROCBASED_CTRL.bit[2]) and
VMEnter directly. The injection will be done on next VMExit once the
Guest issues STI (GuestRFLAG.IF=1).
VT-x and VT-d
*************
Since 2006, Intel CPUs have supported hardware assist - VT-x
instructions, where the CPU itself traps specific guest instructions and
register accesses directly into the VMM without need for binary
translation (and modification) of the guest operating system. Guest
operating systems can be run natively without modification, although it
is common to still install virtualization-aware para-virtualized drivers
into the guests to improve functionality. One common example is access
to storage via emulated SCSI devices.
Intel CPUs and chipsets support various Virtualization Technology (VT)
features - such as VT-x and VT-d. Physical events on the platform
trigger CPU **VM Exits** (a trap into the VMM) to handle physical
events such as physical device interrupts,
In the ACRN hypervisor design, VT-d can be used to do DMA Remapping,
such as Address translation and Isolation.
:numref:`primer-dma-address-mapping` is an example of address
translation:
.. figure:: images/primer-dma-address-mapping.png
:align: center
:name: primer-dma-address-mapping
DMA address mapping
Hypercall
*********
ACRN hypervisor currently supports less than a dozen
:ref:`hypercall_apis` and VHM upcall APIs to support the necessary VM
management, IO request distribution and guest memory mappings. The
hypervisor and Service OS (SOS) reserve vector 0xF4 for hypervisor
notification to the SOS. This upcall is necessary whenever device
emulation is required by the SOS. The upcall vector 0xF4 is injected to
SOS vCPU0.
Refer to the :ref:`acrn_apis` documentation for details.
Device emulation
****************
The ACRN Device Model emulates different kinds of platform devices, such as
RTC, LPC, UART, PCI device, and Virtio block device. The most important
thing about device emulation is to handle the I/O request from different
devices. The I/O request could be PIO, MMIO, or PCI CFG SPACE access. For
example:
- a CMOS RTC device may access 0x70/0x71 PIO to get the CMOS time,
- a GPU PCI device may access its MMIO or PIO BAR space to complete
its frame buffer rendering, or
- the bootloader may access PCI devices' CFG
SPACE for BAR reprogramming.
ACRN Device Model injects interrupts/MSIs to its frontend devices when
necessary as well, for example, a RTC device needs to get its ALARM
interrupt or a PCI device with MSI capability needs to get its MSI. The
Data Model also provides a PIRQ routing mechanism for platform devices.
Virtio Devices
**************
This section introduces the Virtio devices supported by ACRN. Currently
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
one virtqueue of 64 entries (configurable in the source code). No
feature bits are defined.
When the FE driver requires random bytes, the BE device places bytes of
random data onto the virtqueue.
To launch the Virtio-rnd device, you can use the following command:
.. code-block:: bash
./acrn-dm -A -m 1168M \
-s 0:0,hostbridge \
-s 1,virtio-blk,./uos.img \
-s 2,virtio-rnd \
-k bzImage \
-B "root=/dev/vda rw rootwait noxsave maxcpus=0 nohpet \
console=hvc0 no_timer_check ignore_loglevel \
log_buf_len=16M consoleblank=0 tsc=reliable" vm1
To verify the result in user OS side, you can use the following command:
.. code-block:: bash
od /dev/random
Virtio-blk
==========
The Virtio-blk device is a simple virtual block device. The FE driver
will place read, write, and other requests onto the virtqueue, so that
the BE driver can process them accordingly.
The Virtio device ID of the Virtio-blk is 2, and it supports one
virtqueue with 64 entries, configurable in the source code. The feature
bits supported by the BE device are as follows:
**VTBLK\_F\_SEG\_MAX(bit 2)**
Maximum number of segments in a request is in seg_max.
**VTBLK\_F\_BLK\_SIZE(bit 6)**
block size of disk is in blk\_size.
**VTBLK\_F\_FLUSH(bit 9)**
cache flush command support.
**VTBLK\_F\_TOPOLOGY(bit 10)**
device exports information on optimal I/O alignment.
To use the Virtio-blk device, use the following command:
.. code-block:: bash
./acrn-dm -A -m 1168M \
-s 0:0,hostbridge \
-s 1,virtio-blk,./uos.img** \
-k bzImage -B "root=/dev/vda rw rootwait noxsave maxcpus=0 \
nohpet console=hvc0 no_timer_check ignore_loglevel \
log_buf_len=16M consoleblank=0 tsc=reliable" vm1
To verify the result, you should expect the user OS to boot
successfully.
Virtio-net
==========
The Virtio-net device is a virtual Ethernet device. The Virtio device ID
of the Virtio-net is 1. The Virtio-net device supports two virtqueues,
one for transmitting packets and the other for receiving packets. The
FE driver will place empty buffers onto one virtqueue for receiving
packets, and enqueue outgoing packets onto the other virtqueue for
transmission. Currently the size of each virtqueue is 1000, configurable
in the source code.
To access the external network from user OS, a L2 virtual switch should
be created in the service OS, and the BE driver is bonded to a tap/tun
device linking under the L2 virtual switch. See
:numref:`primer-virtio-net`:
.. figure:: images/primer-virtio-net.png
:align: center
:name: primer-virtio-net
Accessing external network from User OS
Currently the feature bits supported by the BE device are:
**VIRTIO\_NET\_F\_MAC(bit 5)**
device has given MAC address.
**VIRTIO\_NET\_F\_MRG\_RXBUF(bit 15)**
BE driver can merge receive buffers.
**VIRTIO\_NET\_F\_STATUS(bit 16)**
configuration status field is available.
**VIRTIO\_F\_NOTIFY\_ON\_EMPTY(bit 24)**
device will issue an interrupt if it runs out of available
descriptors on a virtqueue.
To enable the Virtio-net device, use the following command:
.. code-block:: bash
./acrn-dm -A -m 1168M \
-s 0:0,hostbridge \
-s 1,virtio-blk,./uos.img \
-s 2,virtio-net,tap0 \
-k bzImage -B "root=/dev/vda rw rootwait noxsave maxcpus=0 \
nohpet console=hvc0 no_timer_check ignore_loglevel \
log_buf_len=16M consoleblank=0 tsc=reliable" vm1
To verify the correctness of the device, the external
network should be accessible from the user OS.
Virtio-console
==============
The Virtio-console device is a simple device for data input and output.
The Virtio device ID of the Virtio-console device is 3. A device could
have from one to 16 ports. Each port has a pair of input and output
virtqueues used to communicate information between the FE and BE
drivers. Currently the size of each virtqueue is 64, configurable in the
source code.
Similar to Virtio-net device, the two virtqueues specific to a port are
for transmitting virtqueue and receiving virtqueue. The FE driver will
place empty buffers onto the receiving virtqueue for incoming data, and
enqueue outgoing characters onto transmitting virtqueue.
Currently the feature bits supported by the BE device are:
**VTCON\_F\_SIZE(bit 0)**
configuration columns and rows are valid.
**VTCON\_F\_MULTIPORT(bit 1)**
device supports multiple ports, and control virtqueues will be used.
**VTCON\_F\_EMERG\_WRITE(bit 2)**
device supports emergency write.
Virtio-console supports redirecting guest output to various backend
devices, including stdio/pty/tty. Users could follow the syntax below to
specify which backend to use:
.. code-block:: none
virtio-console,[@]stdio\|tty\|pty:portname[=portpath][,[@]stdio\|tty\|pty:portname[=portpath]]
For example, to use stdio as a Virtio-console backend, use the following
command:
.. code-block:: bash
./acrn-dm -A -m 1168M \
-s 0:0,hostbridge \
-s 1,virtio-blk,./uos.img \
-s 3,virtio-console,@stdio:stdio\_port \
-k bzImage -B "root=/dev/vda rw rootwait noxsave maxcpus=0 \
nohpet console=hvc0 no_timer_check ignore_loglevel \
log_buf_len=16M consoleblank=0 tsc=reliable" vm1
Then user could login into user OS:
.. code-block:: bash
Ubuntu 17.04 xubuntu hvc0
xubuntu login: root
Password:
To use pty as a virtio-console backend, use the following command:
.. code-block:: bash
./acrn-dm -A -m 1168M \
-s 0:0,hostbridge \
-s 1,virtio-blk,./uos.img \
-s 2,virtio-net,tap0 \
-s 3,virtio-console,@pty:pty\_port \
-k ./bzImage -B "root=/dev/vda rw rootwait noxsave maxcpus=0 \
nohpet console=hvc0 no_timer_check ignore_loglevel \
log_buf_len=16M consoleblank=0 tsc=reliable" vm1 &
When ACRN-DM boots User OS successfully, a similar log will be shown
as below:
.. code-block:: none
**************************************************************
virt-console backend redirected to /dev/pts/0
**************************************************************
You can then use the following command to login the User OS:
.. code-block:: bash
minicom -D /dev/pts/0
or
.. code-block:: bash
screen /dev/pts/0