mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-06-21 13:08:42 +00:00
Merge remote-tracking branch 'documentation/master'
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This commit is contained in:
Geoffroy Van Cutsem
commit
b533db6401
6
.gitignore
vendored
6
.gitignore
vendored
@ -3,3 +3,9 @@ hypervisor/bsp/uefi/include/bsp/version.h
|
|||||||
hypervisor/bsp/sbl/include/bsp/version.h
|
hypervisor/bsp/sbl/include/bsp/version.h
|
||||||
devicemdodel/build/
|
devicemdodel/build/
|
||||||
devicemodel/include/version.h
|
devicemodel/include/version.h
|
||||||
|
doxygen
|
||||||
|
_build
|
||||||
|
*.bak
|
||||||
|
*.sav
|
||||||
|
*.log
|
||||||
|
*.warnings
|
||||||
|
|||||||
55
.known-issues/README
Normal file
55
.known-issues/README
Normal file
@ -0,0 +1,55 @@
|
|||||||
|
This directory contains configuration files to ignore errors found in
|
||||||
|
the build and test process which are known to the developers and for
|
||||||
|
now can be safely ignored.
|
||||||
|
|
||||||
|
To use:
|
||||||
|
|
||||||
|
$ cd <build directory>
|
||||||
|
$ make SOMETHING >& result
|
||||||
|
$ scripts/filter-known-issues.py result
|
||||||
|
|
||||||
|
It is included in the source tree so if anyone has to submit anything
|
||||||
|
that triggers some kind of error that is a false positive, it can
|
||||||
|
include the "ignore me" file, properly documented.
|
||||||
|
|
||||||
|
Each file can contain one or more multiline Python regular expressions
|
||||||
|
(https://docs.python.org/2/library/re.html#regular-expression-syntax)
|
||||||
|
that match an error message. Multiple regular expressions are
|
||||||
|
separated by comment blocks (that start with #). Note that an empty
|
||||||
|
line still is considered part of the multiline regular expression.
|
||||||
|
|
||||||
|
For example
|
||||||
|
|
||||||
|
---beginning---
|
||||||
|
#
|
||||||
|
# This testcase always fails, pending fix ZEP-1234
|
||||||
|
#
|
||||||
|
.*/tests/kernel/grumpy .* FAIL
|
||||||
|
#
|
||||||
|
# Documentation issue, masks:
|
||||||
|
#
|
||||||
|
# /home/e/inaky/z/kernel.git/doc/api/io_interfaces.rst:28: WARNING: Invalid definition: Expected identifier in nested name. [error at 19]
|
||||||
|
# struct dev_config::@65 dev_config::bits
|
||||||
|
# -------------------^
|
||||||
|
#
|
||||||
|
^(?P<filename>.+/doc/api/io_interfaces.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^\s+struct dev_config::@[0-9]+ dev_config::bits.*
|
||||||
|
^\s+-+\^
|
||||||
|
---end---
|
||||||
|
|
||||||
|
Note you want to:
|
||||||
|
|
||||||
|
- use relateive paths; instead of
|
||||||
|
/home/me/mydir/zephyr/something/somewhere.c you will want
|
||||||
|
^.*/something/somewhere.c (as they will depend on where it is being
|
||||||
|
built)
|
||||||
|
|
||||||
|
- Replace line numbers with [0-9]+, as they will change
|
||||||
|
|
||||||
|
- (?P<filename>[-._/\w]+/something/somewhere.c) saves the match on
|
||||||
|
that file path in a "variable" called 'filename' that later you can
|
||||||
|
match with (?P=filename) if you want to match multiple lines of the
|
||||||
|
same error message.
|
||||||
|
|
||||||
|
Can get really twisted and interesting in terms of regexps; they are
|
||||||
|
powerful, so start small :)
|
||||||
59
.known-issues/doc/hypercall.conf
Normal file
59
.known-issues/doc/hypercall.conf
Normal file
@ -0,0 +1,59 @@
|
|||||||
|
#
|
||||||
|
# Hypercall
|
||||||
|
#
|
||||||
|
#
|
||||||
|
^(?P<filename>[-._/\w]+/api/hypercall_api.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^.*union vhm_request::\@0 vhm_request::\@1
|
||||||
|
^[- \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^.*union vhm_request::\@2 vhm_request::reqs
|
||||||
|
^[- \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^.*union vhm_request_buffer::\@3 vhm_request_buffer::\@4
|
||||||
|
^[- \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^[ \t]*
|
||||||
|
^[ \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^[ \t]*
|
||||||
|
^[ \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^[ \t]*
|
||||||
|
^[ \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^[ \t]*
|
||||||
|
^[ \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
|
||||||
|
^.*vhm_request.reqs
|
||||||
|
^[- \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^.*union hc_ptdev_irq::\@5 hc_ptdev_irq::is
|
||||||
|
^[- \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^[ \t]*
|
||||||
|
^[ \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^[ \t]*
|
||||||
|
^[ \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
|
||||||
|
^.*hc_ptdev_irq.is
|
||||||
|
^[- \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^[ \t]*
|
||||||
|
^[ \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^[ \t]*
|
||||||
|
^[ \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^[ \t]*
|
||||||
|
^[ \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
|
||||||
|
^.*hc_ptdev_irq.is.intx
|
||||||
|
^[- \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
|
||||||
|
^[ \t]*
|
||||||
|
^[ \t]*\^
|
||||||
|
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
|
||||||
|
^.*hc_ptdev_irq.is.msix
|
||||||
|
^[- \t]*\^
|
||||||
|
#
|
||||||
6
CODEOWNERS
Normal file
6
CODEOWNERS
Normal file
@ -0,0 +1,6 @@
|
|||||||
|
# CODEOWNERS for autoreview assigning in github
|
||||||
|
|
||||||
|
# Get all docs reviewed
|
||||||
|
*.rst @dbkinder
|
||||||
|
|
||||||
|
* @dbkinder
|
||||||
3
LICENSE
Normal file
3
LICENSE
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
ARCN Project Documentation is under a Creative Commons Attribution 4.0
|
||||||
|
International License (CC BY 4.0). For details, see
|
||||||
|
https://creativecommons.org/licenses/by/4.0/.
|
||||||
70
Makefile
Normal file
70
Makefile
Normal file
@ -0,0 +1,70 @@
|
|||||||
|
# Minimal makefile for Sphinx documentation
|
||||||
|
#
|
||||||
|
|
||||||
|
ifeq ($(VERBOSE),1)
|
||||||
|
Q =
|
||||||
|
else
|
||||||
|
Q = @
|
||||||
|
endif
|
||||||
|
|
||||||
|
# You can set these variables from the command line.
|
||||||
|
SPHINXOPTS ?= -q
|
||||||
|
SPHINXBUILD = sphinx-build
|
||||||
|
SPHINXPROJ = "Project ACRN"
|
||||||
|
SOURCEDIR = .
|
||||||
|
BUILDDIR = _build
|
||||||
|
|
||||||
|
DOC_TAG ?= development
|
||||||
|
RELEASE ?= latest
|
||||||
|
PUBLISHDIR = ../projectacrn.github.io/$(RELEASE)
|
||||||
|
|
||||||
|
# Put it first so that "make" without argument is like "make help".
|
||||||
|
help:
|
||||||
|
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||||
|
@echo ""
|
||||||
|
@echo "make pullsource"
|
||||||
|
@echo " fetch and merge upstream source for the project ACRN code repos"
|
||||||
|
@echo ""
|
||||||
|
@echo "make publish"
|
||||||
|
@echo " publish generated html to projectacrn.github.io site:"
|
||||||
|
@echo " specify RELEASE=name to publish as a tagged release version"
|
||||||
|
@echo " and placed in a version subfolder"
|
||||||
|
|
||||||
|
.PHONY: help Makefile
|
||||||
|
|
||||||
|
pullsource:
|
||||||
|
$(Q)scripts/pullsource.sh
|
||||||
|
|
||||||
|
|
||||||
|
# Generate the doxygen xml (for Sphinx) and copy the doxygen html to the
|
||||||
|
# api folder for publishing along with the Sphinx-generated API docs.
|
||||||
|
|
||||||
|
#doxy: pullsource
|
||||||
|
doxy:
|
||||||
|
$(Q)(cat acrn.doxyfile) | doxygen - > doc.log 2>&1
|
||||||
|
|
||||||
|
html: doxy
|
||||||
|
-$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O) >> doc.log 2>&1
|
||||||
|
$(Q)./scripts/filter-doc-log.sh doc.log
|
||||||
|
|
||||||
|
|
||||||
|
# Remove generated content (Sphinx and doxygen)
|
||||||
|
|
||||||
|
clean:
|
||||||
|
rm -fr $(BUILDDIR) doxygen
|
||||||
|
|
||||||
|
# Copy material over to the GitHub pages staging repo
|
||||||
|
# along with a README
|
||||||
|
|
||||||
|
publish:
|
||||||
|
rm -fr $(PUBLISHDIR)/*
|
||||||
|
cp -r $(BUILDDIR)/html/* $(PUBLISHDIR)
|
||||||
|
cp scripts/publish-README.md $(PUBLISHDIR)/../README.md
|
||||||
|
cp scripts/publish-index.html $(PUBLISHDIR)/../index.html
|
||||||
|
cd $(PUBLISHDIR)/..; git add -A; git commit -s -m "publish $(RELEASE)"; git push origin master;
|
||||||
|
|
||||||
|
|
||||||
|
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||||
|
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||||
|
%: Makefile doxy
|
||||||
|
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||||
5
README.md
Normal file
5
README.md
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
# Project ACRN Documentation Repo
|
||||||
|
|
||||||
|
This repository hold the source and configuration files used to generate the
|
||||||
|
Project ACRN documentation web site published to
|
||||||
|
https://projectacrn.github.io
|
||||||
22
_templates/breadcrumbs.html
Normal file
22
_templates/breadcrumbs.html
Normal file
@ -0,0 +1,22 @@
|
|||||||
|
{% extends "!breadcrumbs.html" %}
|
||||||
|
{% block breadcrumbs_aside %}
|
||||||
|
|
||||||
|
<li class="wy-breadcrumbs-aside">
|
||||||
|
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
|
||||||
|
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||||
|
<span class="fa fa-book"> Project ACRN</span>
|
||||||
|
version: {{ current_version }}
|
||||||
|
<span class="fa fa-caret-down"></span>
|
||||||
|
</span>
|
||||||
|
<div class="rst-other-versions">
|
||||||
|
<dl>
|
||||||
|
<dt>Versions</dt>
|
||||||
|
{% for slug, url in versions %}
|
||||||
|
<dd><a href="{{ url }}">{{ slug }}</a></dd>
|
||||||
|
{% endfor %}
|
||||||
|
</dl>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</li>
|
||||||
|
{# {{ super() }} #}
|
||||||
|
{% endblock %}
|
||||||
8
_templates/footer.html
Normal file
8
_templates/footer.html
Normal file
@ -0,0 +1,8 @@
|
|||||||
|
{% extends "!footer.html" %}
|
||||||
|
{% block extrafooter %}
|
||||||
|
<p class="extrafooter">Documentation licensed under <a rel="license"
|
||||||
|
href="http://creativecommons.org/licenses/by/4.0/">(CC BY 4.0) <img
|
||||||
|
alt="Creative Commons License" style="border-width:0"
|
||||||
|
src="https://i.creativecommons.org/l/by/4.0/80x15.png" /></a></p>
|
||||||
|
{{ super() }}
|
||||||
|
{% endblock %}
|
||||||
2464
acrn.doxyfile
Normal file
2464
acrn.doxyfile
Normal file
File diff suppressed because it is too large
Load Diff
13
api/devicemodel_api.rst
Normal file
13
api/devicemodel_api.rst
Normal file
@ -0,0 +1,13 @@
|
|||||||
|
.. _devicemodel_apis:
|
||||||
|
|
||||||
|
Device Model APIs
|
||||||
|
#################
|
||||||
|
|
||||||
|
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
|
||||||
13
api/hypercall_api.rst
Normal file
13
api/hypercall_api.rst
Normal file
@ -0,0 +1,13 @@
|
|||||||
|
.. _hypercall_apis:
|
||||||
|
|
||||||
|
Hypercall APIs
|
||||||
|
##############
|
||||||
|
|
||||||
|
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
|
||||||
18
api/index.rst
Normal file
18
api/index.rst
Normal file
@ -0,0 +1,18 @@
|
|||||||
|
.. _acrn_apis:
|
||||||
|
|
||||||
|
API Documentation
|
||||||
|
#################
|
||||||
|
|
||||||
|
Welcome to Project ACRN :abbr:`API (Application Programing
|
||||||
|
Interface)` documentation.
|
||||||
|
|
||||||
|
This section contains the API documentation automatically extracted from
|
||||||
|
the code. If you are looking for a specific API, enter it on the search
|
||||||
|
box. The search results display all sections containing information
|
||||||
|
about that API.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
hypercall_api.rst
|
||||||
|
devicemodel_api.rst
|
||||||
282
conf.py
Normal file
282
conf.py
Normal file
@ -0,0 +1,282 @@
|
|||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
#
|
||||||
|
# Project ACRN documentation build configuration file, created by
|
||||||
|
# sphinx-quickstart on Wed Jan 10 20:51:29 2018.
|
||||||
|
#
|
||||||
|
# This file is execfile()d with the current directory set to its
|
||||||
|
# containing dir.
|
||||||
|
#
|
||||||
|
# Note that not all possible configuration values are present in this
|
||||||
|
# autogenerated file.
|
||||||
|
#
|
||||||
|
# All configuration values have a default; values that are commented out
|
||||||
|
# serve to show the default.
|
||||||
|
|
||||||
|
# If extensions (or modules to document with autodoc) are in another directory,
|
||||||
|
# add these directories to sys.path here. If the directory is relative to the
|
||||||
|
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||||
|
#
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
sys.path.insert(0, os.path.abspath('.'))
|
||||||
|
|
||||||
|
|
||||||
|
# -- General configuration ------------------------------------------------
|
||||||
|
|
||||||
|
# If your documentation needs a minimal Sphinx version, state it here.
|
||||||
|
#
|
||||||
|
# needs_sphinx = '1.0'
|
||||||
|
|
||||||
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
|
# ones.
|
||||||
|
extensions = ['breathe']
|
||||||
|
|
||||||
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
|
templates_path = ['_templates']
|
||||||
|
|
||||||
|
# The suffix(es) of source filenames.
|
||||||
|
# You can specify multiple suffix as a list of string:
|
||||||
|
#
|
||||||
|
# source_suffix = ['.rst', '.md']
|
||||||
|
source_suffix = '.rst'
|
||||||
|
|
||||||
|
# The master toctree document.
|
||||||
|
master_doc = 'index'
|
||||||
|
|
||||||
|
# General information about the project.
|
||||||
|
project = u'Project ACRN™'
|
||||||
|
copyright = u'2018, Project ACRN'
|
||||||
|
author = u'Project ARCN developers'
|
||||||
|
|
||||||
|
# The version info for the project you're documenting, acts as replacement for
|
||||||
|
# |version| and |release|, also used in various other places throughout the
|
||||||
|
# built documents.
|
||||||
|
|
||||||
|
# The following code tries to extract the information by reading the
|
||||||
|
# Makefile from the acrn-hypervisor repo by finding these lines:
|
||||||
|
# MAJOR_VERSION=0
|
||||||
|
# MINOR_VERSION=1
|
||||||
|
# RC_VERSION=1
|
||||||
|
|
||||||
|
try:
|
||||||
|
version_major = None
|
||||||
|
version_minor = None
|
||||||
|
version_rc = None
|
||||||
|
for line in open(os.path.normpath("../acrn-hypervisor/Makefile")) :
|
||||||
|
# remove comments
|
||||||
|
line = line.split('#', 1)[0]
|
||||||
|
line = line.rstrip()
|
||||||
|
if (line.count("=") == 1) :
|
||||||
|
key, val = [x.strip() for x in line.split('=', 2)]
|
||||||
|
if key == 'MAJOR_VERSION':
|
||||||
|
version_major = val
|
||||||
|
if key == 'MINOR_VERSION':
|
||||||
|
version_minor = val
|
||||||
|
if key == 'RC_VERSION':
|
||||||
|
version_rc = val
|
||||||
|
if version_major and version_minor and version_rc :
|
||||||
|
break
|
||||||
|
except:
|
||||||
|
pass
|
||||||
|
finally:
|
||||||
|
if version_major and version_minor and version_rc :
|
||||||
|
version = release = "v " + version_major + '.' + version_minor
|
||||||
|
if int(version_rc) > 0 :
|
||||||
|
version = release = version + '-rc' + version_rc
|
||||||
|
else:
|
||||||
|
sys.stderr.write('Warning: Could not extract hypervisor version from Makefile\n')
|
||||||
|
version = release = "unknown"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#
|
||||||
|
# The short X.Y version.
|
||||||
|
# version = u'0.1'
|
||||||
|
# The full version, including alpha/beta/rc tags.
|
||||||
|
# release = u'0.1'
|
||||||
|
|
||||||
|
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||||
|
# for a list of supported languages.
|
||||||
|
#
|
||||||
|
# This is also used if you do content translation via gettext catalogs.
|
||||||
|
# Usually you set "language" from the command line for these cases.
|
||||||
|
language = None
|
||||||
|
|
||||||
|
# List of patterns, relative to source directory, that match files and
|
||||||
|
# directories to ignore when looking for source files.
|
||||||
|
# This patterns also effect to html_static_path and html_extra_path
|
||||||
|
exclude_patterns = ['_build' ]
|
||||||
|
|
||||||
|
# The name of the Pygments (syntax highlighting) style to use.
|
||||||
|
pygments_style = 'sphinx'
|
||||||
|
|
||||||
|
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||||
|
todo_include_todos = False
|
||||||
|
|
||||||
|
# -- Options for HTML output ----------------------------------------------
|
||||||
|
|
||||||
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||||
|
# a list of builtin themes.
|
||||||
|
#
|
||||||
|
try:
|
||||||
|
import sphinx_rtd_theme
|
||||||
|
except ImportError:
|
||||||
|
html_theme = 'alabaster'
|
||||||
|
# This is required for the alabaster theme
|
||||||
|
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
|
||||||
|
html_sidebars = {
|
||||||
|
'**': [
|
||||||
|
'relations.html', # needs 'show_related': True theme option to display
|
||||||
|
'searchbox.html',
|
||||||
|
]
|
||||||
|
}
|
||||||
|
sys.stderr.write('Warning: sphinx_rtd_theme missing. Use pip to install it.\n')
|
||||||
|
else:
|
||||||
|
html_theme = "sphinx_rtd_theme"
|
||||||
|
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||||
|
html_theme_options = {
|
||||||
|
'canonical_url': '',
|
||||||
|
'analytics_id': '',
|
||||||
|
'logo_only': False,
|
||||||
|
'display_version': True,
|
||||||
|
'prev_next_buttons_location': 'None',
|
||||||
|
# Toc options
|
||||||
|
'collapse_navigation': False,
|
||||||
|
'sticky_navigation': True,
|
||||||
|
'navigation_depth': 4,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
# Here's where we (manually) list the document versions maintained on
|
||||||
|
# the published doc website. On a daily basis we publish to the
|
||||||
|
# /latest folder but when releases are made, we publish to a /<relnum>
|
||||||
|
# folder (specified via RELEASE=name on the make command).
|
||||||
|
|
||||||
|
if tags.has('release'):
|
||||||
|
current_version = version
|
||||||
|
else:
|
||||||
|
version = current_version = "latest"
|
||||||
|
|
||||||
|
html_context = {
|
||||||
|
'current_version': current_version,
|
||||||
|
'versions': ( ("latest", "/latest/"),
|
||||||
|
# ("0.1-rc4", "/0.1-rc4/"),
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
# Theme options are theme-specific and customize the look and feel of a theme
|
||||||
|
# further. For a list of options available for each theme, see the
|
||||||
|
# documentation.
|
||||||
|
#
|
||||||
|
# html_theme_options = {}
|
||||||
|
|
||||||
|
html_logo = 'images/ACRN_Logo_300w.png'
|
||||||
|
html_favicon = 'images/ACRN-favicon-32x32.png'
|
||||||
|
|
||||||
|
numfig = True
|
||||||
|
#numfig_secnum_depth = (2)
|
||||||
|
numfig_format = {'figure': 'Figure %s', 'table': 'Table %s', 'code-block': 'Code Block %s'}
|
||||||
|
|
||||||
|
# Add any paths that contain custom static files (such as style sheets) here,
|
||||||
|
# relative to this directory. They are copied after the builtin static files,
|
||||||
|
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||||
|
html_static_path = ['static']
|
||||||
|
|
||||||
|
def setup(app):
|
||||||
|
app.add_stylesheet("acrn-custom.css")
|
||||||
|
|
||||||
|
# Custom sidebar templates, must be a dictionary that maps document names
|
||||||
|
# to template names.
|
||||||
|
#
|
||||||
|
|
||||||
|
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
|
||||||
|
html_show_sphinx = False
|
||||||
|
|
||||||
|
# If true, links to the reST sources are added to the pages.
|
||||||
|
html_show_sourcelink = False
|
||||||
|
|
||||||
|
# If not '', a 'Last updated on:' timestamp is inserted at every page
|
||||||
|
# bottom,
|
||||||
|
# using the given strftime format.
|
||||||
|
html_last_updated_fmt = '%b %d, %Y'
|
||||||
|
|
||||||
|
# -- Options for HTMLHelp output ------------------------------------------
|
||||||
|
|
||||||
|
# Output file base name for HTML help builder.
|
||||||
|
htmlhelp_basename = 'ACRN Project Help'
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for LaTeX output ---------------------------------------------
|
||||||
|
|
||||||
|
latex_elements = {
|
||||||
|
# The paper size ('letterpaper' or 'a4paper').
|
||||||
|
#
|
||||||
|
# 'papersize': 'letterpaper',
|
||||||
|
|
||||||
|
# The font size ('10pt', '11pt' or '12pt').
|
||||||
|
#
|
||||||
|
# 'pointsize': '10pt',
|
||||||
|
|
||||||
|
# Additional stuff for the LaTeX preamble.
|
||||||
|
#
|
||||||
|
# 'preamble': '',
|
||||||
|
|
||||||
|
# Latex figure (float) alignment
|
||||||
|
#
|
||||||
|
# 'figure_align': 'htbp',
|
||||||
|
}
|
||||||
|
|
||||||
|
# Grouping the document tree into LaTeX files. List of tuples
|
||||||
|
# (source start file, target name, title,
|
||||||
|
# author, documentclass [howto, manual, or own class]).
|
||||||
|
latex_documents = [
|
||||||
|
(master_doc, 'acrn.tex', u'Project ACRN Documentation',
|
||||||
|
u'Project ACRN', 'manual'),
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for manual page output ---------------------------------------
|
||||||
|
|
||||||
|
# One entry per manual page. List of tuples
|
||||||
|
# (source start file, name, description, authors, manual section).
|
||||||
|
man_pages = [
|
||||||
|
(master_doc, 'acrn', u'Project ACRN Documentation',
|
||||||
|
[author], 1)
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for Texinfo output -------------------------------------------
|
||||||
|
|
||||||
|
# Grouping the document tree into Texinfo files. List of tuples
|
||||||
|
# (source start file, target name, title, author,
|
||||||
|
# dir menu entry, description, category)
|
||||||
|
texinfo_documents = [
|
||||||
|
(master_doc, 'Project ACRN', u'Project ACRN Documentation',
|
||||||
|
author, 'Project ACRN',
|
||||||
|
'IoT-Optimized Hypervisor for Intel Architecture',
|
||||||
|
'Miscellaneous'),
|
||||||
|
]
|
||||||
|
|
||||||
|
rst_epilog = """
|
||||||
|
.. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN
|
||||||
|
:ltrim:
|
||||||
|
.. |trade| unicode:: U+02122 .. TRADEMARK SIGN
|
||||||
|
:ltrim:
|
||||||
|
.. |reg| unicode:: U+000AE .. REGISTERED TRADEMARK SIGN
|
||||||
|
:ltrim:
|
||||||
|
.. |deg| unicode:: U+000B0 .. DEGREE SIGN
|
||||||
|
:ltrim:
|
||||||
|
.. |plusminus| unicode:: U+000B1 .. PLUS-MINUS SIGN
|
||||||
|
:rtrim:
|
||||||
|
.. |micro| unicode:: U+000B5 .. MICRO SIGN
|
||||||
|
:rtrim:
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
breathe_projects = {
|
||||||
|
"Project ACRN" : "doxygen/xml",
|
||||||
|
}
|
||||||
|
breathe_default_project = "Project ACRN"
|
||||||
|
breathe_default_members = ('members', 'undoc-members', 'content-only')
|
||||||
447
contribute.rst
Normal file
447
contribute.rst
Normal file
@ -0,0 +1,447 @@
|
|||||||
|
.. _contribute:
|
||||||
|
|
||||||
|
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_header 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 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 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
|
||||||
|
|
||||||
|
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 discusions 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 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
|
||||||
|
|
||||||
|
#. `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.)
|
||||||
|
|
||||||
|
#. 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
|
||||||
|
|
||||||
|
#. 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, add -p if you want to be more specific]
|
||||||
|
|
||||||
|
(or to have all changed files added 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 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.
|
||||||
|
|
||||||
|
#. 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 do 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
|
||||||
|
|
||||||
|
then::
|
||||||
|
|
||||||
|
git fetch --all
|
||||||
|
git rebase --ignore-whitespace upstream/master
|
||||||
|
|
||||||
|
The ``--ignore-whitespace`` option stops git apply (called by rebase) from changing
|
||||||
|
any whitespace. Continuing::
|
||||||
|
|
||||||
|
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 #<issue number>
|
||||||
|
|
||||||
|
See `Closing issues using keywords
|
||||||
|
<https://help.github.com/articles/closing-issues-using-keywords>`_
|
||||||
|
for more information about this GitHub feature.
|
||||||
|
|
||||||
|
|
||||||
|
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
|
||||||
194
custom-doxygen/DoxygenLayout.xml
Normal file
194
custom-doxygen/DoxygenLayout.xml
Normal file
@ -0,0 +1,194 @@
|
|||||||
|
<doxygenlayout version="1.0">
|
||||||
|
<!-- Generated by doxygen 1.8.13 -->
|
||||||
|
<!-- Navigation index tabs for HTML output -->
|
||||||
|
<navindex>
|
||||||
|
<tab type="mainpage" visible="yes" title=""/>
|
||||||
|
<tab type="pages" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="modules" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="namespaces" visible="yes" title="">
|
||||||
|
<tab type="namespacelist" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="namespacemembers" visible="yes" title="" intro=""/>
|
||||||
|
</tab>
|
||||||
|
<tab type="classes" visible="yes" title="">
|
||||||
|
<tab type="classlist" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
|
||||||
|
<tab type="hierarchy" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="classmembers" visible="yes" title="" intro=""/>
|
||||||
|
</tab>
|
||||||
|
<tab type="files" visible="yes" title="">
|
||||||
|
<tab type="filelist" visible="yes" title="" intro=""/>
|
||||||
|
<tab type="globals" visible="yes" title="" intro=""/>
|
||||||
|
</tab>
|
||||||
|
<tab type="examples" visible="yes" title="" intro=""/>
|
||||||
|
</navindex>
|
||||||
|
|
||||||
|
<!-- Layout definition for a class page -->
|
||||||
|
<class>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<includes visible="$SHOW_INCLUDE_FILES"/>
|
||||||
|
<inheritancegraph visible="$CLASS_GRAPH"/>
|
||||||
|
<collaborationgraph visible="$COLLABORATION_GRAPH"/>
|
||||||
|
<memberdecl>
|
||||||
|
<nestedclasses visible="yes" title=""/>
|
||||||
|
<publictypes title=""/>
|
||||||
|
<services title=""/>
|
||||||
|
<interfaces title=""/>
|
||||||
|
<publicslots title=""/>
|
||||||
|
<signals title=""/>
|
||||||
|
<publicmethods title=""/>
|
||||||
|
<publicstaticmethods title=""/>
|
||||||
|
<publicattributes title=""/>
|
||||||
|
<publicstaticattributes title=""/>
|
||||||
|
<protectedtypes title=""/>
|
||||||
|
<protectedslots title=""/>
|
||||||
|
<protectedmethods title=""/>
|
||||||
|
<protectedstaticmethods title=""/>
|
||||||
|
<protectedattributes title=""/>
|
||||||
|
<protectedstaticattributes title=""/>
|
||||||
|
<packagetypes title=""/>
|
||||||
|
<packagemethods title=""/>
|
||||||
|
<packagestaticmethods title=""/>
|
||||||
|
<packageattributes title=""/>
|
||||||
|
<packagestaticattributes title=""/>
|
||||||
|
<properties title=""/>
|
||||||
|
<events title=""/>
|
||||||
|
<privatetypes title=""/>
|
||||||
|
<privateslots title=""/>
|
||||||
|
<privatemethods title=""/>
|
||||||
|
<privatestaticmethods title=""/>
|
||||||
|
<privateattributes title=""/>
|
||||||
|
<privatestaticattributes title=""/>
|
||||||
|
<friends title=""/>
|
||||||
|
<related title="" subtitle=""/>
|
||||||
|
<membergroups visible="yes"/>
|
||||||
|
</memberdecl>
|
||||||
|
<detaileddescription title=""/>
|
||||||
|
<memberdef>
|
||||||
|
<inlineclasses title=""/>
|
||||||
|
<typedefs title=""/>
|
||||||
|
<enums title=""/>
|
||||||
|
<services title=""/>
|
||||||
|
<interfaces title=""/>
|
||||||
|
<constructors title=""/>
|
||||||
|
<functions title=""/>
|
||||||
|
<related title=""/>
|
||||||
|
<variables title=""/>
|
||||||
|
<properties title=""/>
|
||||||
|
<events title=""/>
|
||||||
|
</memberdef>
|
||||||
|
<allmemberslink visible="yes"/>
|
||||||
|
<usedfiles visible="$SHOW_USED_FILES"/>
|
||||||
|
<authorsection visible="yes"/>
|
||||||
|
</class>
|
||||||
|
|
||||||
|
<!-- Layout definition for a namespace page -->
|
||||||
|
<namespace>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<memberdecl>
|
||||||
|
<nestednamespaces visible="yes" title=""/>
|
||||||
|
<constantgroups visible="yes" title=""/>
|
||||||
|
<classes visible="yes" title=""/>
|
||||||
|
<typedefs title=""/>
|
||||||
|
<enums title=""/>
|
||||||
|
<functions title=""/>
|
||||||
|
<variables title=""/>
|
||||||
|
<membergroups visible="yes"/>
|
||||||
|
</memberdecl>
|
||||||
|
<detaileddescription title=""/>
|
||||||
|
<memberdef>
|
||||||
|
<inlineclasses title=""/>
|
||||||
|
<typedefs title=""/>
|
||||||
|
<enums title=""/>
|
||||||
|
<functions title=""/>
|
||||||
|
<variables title=""/>
|
||||||
|
</memberdef>
|
||||||
|
<authorsection visible="yes"/>
|
||||||
|
</namespace>
|
||||||
|
|
||||||
|
<!-- Layout definition for a file page -->
|
||||||
|
<file>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<includes visible="$SHOW_INCLUDE_FILES"/>
|
||||||
|
<includegraph visible="$INCLUDE_GRAPH"/>
|
||||||
|
<includedbygraph visible="$INCLUDED_BY_GRAPH"/>
|
||||||
|
<sourcelink visible="yes"/>
|
||||||
|
<memberdecl>
|
||||||
|
<classes visible="yes" title=""/>
|
||||||
|
<namespaces visible="yes" title=""/>
|
||||||
|
<constantgroups visible="yes" title=""/>
|
||||||
|
<defines title=""/>
|
||||||
|
<typedefs title=""/>
|
||||||
|
<enums title=""/>
|
||||||
|
<functions title=""/>
|
||||||
|
<variables title=""/>
|
||||||
|
<membergroups visible="yes"/>
|
||||||
|
</memberdecl>
|
||||||
|
<detaileddescription title=""/>
|
||||||
|
<memberdef>
|
||||||
|
<inlineclasses title=""/>
|
||||||
|
<defines title=""/>
|
||||||
|
<typedefs title=""/>
|
||||||
|
<enums title=""/>
|
||||||
|
<functions title=""/>
|
||||||
|
<variables title=""/>
|
||||||
|
</memberdef>
|
||||||
|
<authorsection/>
|
||||||
|
</file>
|
||||||
|
|
||||||
|
<!-- Layout definition for a group page -->
|
||||||
|
<group>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<groupgraph visible="$GROUP_GRAPHS"/>
|
||||||
|
<memberdecl>
|
||||||
|
<nestedgroups visible="yes" title=""/>
|
||||||
|
<dirs visible="yes" title=""/>
|
||||||
|
<files visible="yes" title=""/>
|
||||||
|
<namespaces visible="yes" title=""/>
|
||||||
|
<classes visible="yes" title=""/>
|
||||||
|
<defines title=""/>
|
||||||
|
<typedefs title=""/>
|
||||||
|
<enums title=""/>
|
||||||
|
<enumvalues title=""/>
|
||||||
|
<functions title=""/>
|
||||||
|
<variables title=""/>
|
||||||
|
<signals title=""/>
|
||||||
|
<publicslots title=""/>
|
||||||
|
<protectedslots title=""/>
|
||||||
|
<privateslots title=""/>
|
||||||
|
<events title=""/>
|
||||||
|
<properties title=""/>
|
||||||
|
<friends title=""/>
|
||||||
|
<membergroups visible="yes"/>
|
||||||
|
</memberdecl>
|
||||||
|
<detaileddescription title=""/>
|
||||||
|
<memberdef>
|
||||||
|
<pagedocs/>
|
||||||
|
<inlineclasses title=""/>
|
||||||
|
<defines title=""/>
|
||||||
|
<typedefs title=""/>
|
||||||
|
<enums title=""/>
|
||||||
|
<enumvalues title=""/>
|
||||||
|
<functions title=""/>
|
||||||
|
<variables title=""/>
|
||||||
|
<signals title=""/>
|
||||||
|
<publicslots title=""/>
|
||||||
|
<protectedslots title=""/>
|
||||||
|
<privateslots title=""/>
|
||||||
|
<events title=""/>
|
||||||
|
<properties title=""/>
|
||||||
|
<friends title=""/>
|
||||||
|
</memberdef>
|
||||||
|
<authorsection visible="yes"/>
|
||||||
|
</group>
|
||||||
|
|
||||||
|
<!-- Layout definition for a directory page -->
|
||||||
|
<directory>
|
||||||
|
<briefdescription visible="yes"/>
|
||||||
|
<directorygraph visible="yes"/>
|
||||||
|
<memberdecl>
|
||||||
|
<dirs visible="yes"/>
|
||||||
|
<files visible="yes"/>
|
||||||
|
</memberdecl>
|
||||||
|
<detaileddescription title=""/>
|
||||||
|
</directory>
|
||||||
|
</doxygenlayout>
|
||||||
34
custom-doxygen/customdoxygen.css
Normal file
34
custom-doxygen/customdoxygen.css
Normal file
@ -0,0 +1,34 @@
|
|||||||
|
/* Custom CSS */
|
||||||
|
|
||||||
|
code {
|
||||||
|
font-family: Monaco,Menlo,Consolas,"Courier New",monospace;
|
||||||
|
background-color: #D8D8D8;
|
||||||
|
padding: 0 0.25em 0 0.25em;
|
||||||
|
}
|
||||||
|
|
||||||
|
pre.fragment {
|
||||||
|
display: block;
|
||||||
|
font-family: Monaco,Menlo,Consolas,"Courier New",monospace;
|
||||||
|
padding: 1rem;
|
||||||
|
word-break: break-all;
|
||||||
|
word-wrap: break-word;
|
||||||
|
white-space: pre;
|
||||||
|
background-color: #D8D8D8;
|
||||||
|
}
|
||||||
|
|
||||||
|
#projectlogo
|
||||||
|
{
|
||||||
|
vertical-align: middle;
|
||||||
|
}
|
||||||
|
|
||||||
|
#projectname
|
||||||
|
{
|
||||||
|
font: 200% Tahoma, Arial,sans-serif;
|
||||||
|
color: #006469;
|
||||||
|
|
||||||
|
}
|
||||||
|
|
||||||
|
#projectbrief
|
||||||
|
{
|
||||||
|
color: #006469;
|
||||||
|
}
|
||||||
21
custom-doxygen/footer.html
Normal file
21
custom-doxygen/footer.html
Normal file
@ -0,0 +1,21 @@
|
|||||||
|
<!-- HTML footer for doxygen 1.8.13-->
|
||||||
|
<!-- start footer part -->
|
||||||
|
<!--BEGIN GENERATE_TREEVIEW-->
|
||||||
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||||||
|
<ul>
|
||||||
|
$navpath
|
||||||
|
<li class="footer">$generatedby
|
||||||
|
<a href="http://www.doxygen.org/index.html">
|
||||||
|
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
<!--END GENERATE_TREEVIEW-->
|
||||||
|
<!--BEGIN !GENERATE_TREEVIEW-->
|
||||||
|
<hr class="footer"/><address class="footer"><small>
|
||||||
|
$generatedby  <a href="http://www.doxygen.org/index.html">
|
||||||
|
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
|
||||||
|
</a> $doxygenversion
|
||||||
|
</small></address>
|
||||||
|
<!--END !GENERATE_TREEVIEW-->
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
56
custom-doxygen/header.html
Normal file
56
custom-doxygen/header.html
Normal file
@ -0,0 +1,56 @@
|
|||||||
|
<!-- HTML header for doxygen 1.8.13-->
|
||||||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||||
|
<head>
|
||||||
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||||||
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||||||
|
<meta name="generator" content="Doxygen $doxygenversion"/>
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||||||
|
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
|
||||||
|
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
|
||||||
|
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
|
||||||
|
<script type="text/javascript" src="$relpath^jquery.js"></script>
|
||||||
|
<script type="text/javascript" src="$relpath^dynsections.js"></script>
|
||||||
|
$treeview
|
||||||
|
$search
|
||||||
|
$mathjax
|
||||||
|
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
|
||||||
|
$extrastylesheet
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||||||
|
|
||||||
|
<!--BEGIN TITLEAREA-->
|
||||||
|
<div id="titlearea">
|
||||||
|
<table cellspacing="0" cellpadding="0">
|
||||||
|
<tbody>
|
||||||
|
<tr style="height: 56px;">
|
||||||
|
<!--BEGIN PROJECT_LOGO-->
|
||||||
|
<td id="projectlogo"><a href="/"><img alt="Logo" src="$relpath^$projectlogo"/></a></td>
|
||||||
|
<!--END PROJECT_LOGO-->
|
||||||
|
<!--BEGIN PROJECT_NAME-->
|
||||||
|
<td id="projectalign" style="padding-left: 0.5em;">
|
||||||
|
<div id="projectname">$projectname
|
||||||
|
<!--BEGIN PROJECT_NUMBER--> <span id="projectnumber">$projectnumber</span><!--END PROJECT_NUMBER-->
|
||||||
|
</div>
|
||||||
|
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
|
||||||
|
</td>
|
||||||
|
<!--END PROJECT_NAME-->
|
||||||
|
<!--BEGIN !PROJECT_NAME-->
|
||||||
|
<!--BEGIN PROJECT_BRIEF-->
|
||||||
|
<td style="padding-left: 0.5em;">
|
||||||
|
<div id="projectbrief">$projectbrief</div>
|
||||||
|
</td>
|
||||||
|
<!--END PROJECT_BRIEF-->
|
||||||
|
<!--END !PROJECT_NAME-->
|
||||||
|
<!--BEGIN DISABLE_INDEX-->
|
||||||
|
<!--BEGIN SEARCHENGINE-->
|
||||||
|
<td>$searchbox</td>
|
||||||
|
<!--END SEARCHENGINE-->
|
||||||
|
<!--END DISABLE_INDEX-->
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
</div>
|
||||||
|
<!--END TITLEAREA-->
|
||||||
|
<!-- end header part -->
|
||||||
9
custom-doxygen/mainpage.md
Normal file
9
custom-doxygen/mainpage.md
Normal file
@ -0,0 +1,9 @@
|
|||||||
|
# API Documentation {#index}
|
||||||
|
|
||||||
|
Project ACRN is a flexible and lighweight hypervisor, built with
|
||||||
|
real-time and safety-criticality in mind. It streamlines
|
||||||
|
embedded development through a scalable open source reference platform
|
||||||
|
that addresses embedded developers' needs.
|
||||||
|
|
||||||
|
You can get an alternate view this API material in the [Project ACRN
|
||||||
|
documentation](../).
|
||||||
1613
custom-doxygen/standard-doxygen.css
Normal file
1613
custom-doxygen/standard-doxygen.css
Normal file
File diff suppressed because it is too large
Load Diff
BIN
getting_started/images/gsg-bootmenu.png
Normal file
BIN
getting_started/images/gsg-bootmenu.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 123 KiB |
BIN
getting_started/images/gsg-sos-console.png
Normal file
BIN
getting_started/images/gsg-sos-console.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
BIN
getting_started/images/gsg-successful-boot.png
Normal file
BIN
getting_started/images/gsg-successful-boot.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
387
getting_started/index.rst
Normal file
387
getting_started/index.rst
Normal file
@ -0,0 +1,387 @@
|
|||||||
|
.. _getting_started:
|
||||||
|
|
||||||
|
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 the ACRN
|
||||||
|
hypervisor and the `Clear Linux`_ Service OS and Guest OS on the Intel
|
||||||
|
|reg| NUC.
|
||||||
|
|
||||||
|
.. _Clear Linux: https://clearlinux.org
|
||||||
|
|
||||||
|
Hardware setup
|
||||||
|
**************
|
||||||
|
|
||||||
|
The Intel |reg| NUC (NUC6CAYH) is the supported reference target
|
||||||
|
platform for ACRN work, as described in :ref:`hardware`, and is the only
|
||||||
|
platform currently tested with these setup instructions.
|
||||||
|
|
||||||
|
The recommended NUC hardware configuration is:
|
||||||
|
|
||||||
|
- NUC: `NUC Kit
|
||||||
|
NUC6CAYH <https://www.intel.com/content/www/us/en/products/boards-kits/nuc/kits/nuc6cayh.html>`__
|
||||||
|
- `UEFI BIOS (version 0047) <https://downloadcenter.intel.com/product/95062/Intel-NUC-Kit-NUC6CAYH>`__.
|
||||||
|
- Memory: 8G DDR3
|
||||||
|
- SSD: 120G SATA
|
||||||
|
|
||||||
|
Software setup
|
||||||
|
**************
|
||||||
|
|
||||||
|
Firmware update on the NUC
|
||||||
|
==========================
|
||||||
|
|
||||||
|
You may need to update to the latest UEFI firmware for the NUC hardware.
|
||||||
|
Follow these `BIOS Update Instructions
|
||||||
|
<https://www.intel.com/content/www/us/en/support/articles/000005636.html>`__
|
||||||
|
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, 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 22140 or newer. The instructions below
|
||||||
|
have been validated with version 22140 and need some adjustment to work
|
||||||
|
with newer versions. You will see a note when the instruction needs to be
|
||||||
|
adjusted.
|
||||||
|
|
||||||
|
#. Download the compressed Clear installer image from
|
||||||
|
https://download.clearlinux.org/releases/22140/clear/clear-22140-installer.img.xz
|
||||||
|
and follow the `Clear Linux installation guide
|
||||||
|
<https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install>`__
|
||||||
|
as a starting point for installing Clear Linux onto your NUC. Follow the recommended
|
||||||
|
options for choosing an **Automatic** installation type, and using the NUC's
|
||||||
|
storage as the target device for installation (overwriting the existing data
|
||||||
|
and creating three partitions on the NUC's SSD drive).
|
||||||
|
|
||||||
|
#. After installation is complete, boot into Clear Linux, login as
|
||||||
|
**root**, and set a password.
|
||||||
|
|
||||||
|
#. Clear Linux is set to automatically update itself. We recommend that you disable
|
||||||
|
this feature to have more control over when the updates happen. Use this command
|
||||||
|
to disable the autoupdate feature:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# swupd autoupdate --disable
|
||||||
|
|
||||||
|
#. Use the ``swupd bundle-add`` command and add these Clear Linux bundles:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# swupd bundle-add vim network-basic service-os kernel-pk
|
||||||
|
|
||||||
|
.. table:: Clear Linux bundles
|
||||||
|
:widths: auto
|
||||||
|
:name: CL-bundles
|
||||||
|
|
||||||
|
+--------------------+---------------------------------------------------+
|
||||||
|
| Bundle | Description |
|
||||||
|
+====================+===================================================+
|
||||||
|
| vim | vim text editor |
|
||||||
|
+--------------------+---------------------------------------------------+
|
||||||
|
| network-basic | Run network utilities and modify network settings |
|
||||||
|
+--------------------+---------------------------------------------------+
|
||||||
|
| service-os | Add the acrn hypervisor, the acrn devicemodel and |
|
||||||
|
| | Service OS kernel |
|
||||||
|
+--------------------+---------------------------------------------------+
|
||||||
|
| kernel-pk | Run the Intel "PK" kernel(product kernel source) |
|
||||||
|
| | and enterprise-style kernel with backports |
|
||||||
|
+--------------------+---------------------------------------------------+
|
||||||
|
|
||||||
|
Add the ACRN hypervisor to the EFI Partition
|
||||||
|
============================================
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# mount /dev/sda1 /mnt
|
||||||
|
|
||||||
|
# ls -1 /mnt/EFI/org.clearlinux
|
||||||
|
bootloaderx64.efi
|
||||||
|
kernel-org.clearlinux.native.4.16.6-563
|
||||||
|
kernel-org.clearlinux.pk414-sos.4.14.34-28
|
||||||
|
kernel-org.clearlinux.pk414-standard.4.14.34-28
|
||||||
|
loaderx64.efi
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
The Clear Linux project releases updates often, sometimes
|
||||||
|
twice a day, so make note of the specific kernel versions (``*-sos``
|
||||||
|
and ``*-standard``) listed on your system,
|
||||||
|
as you will need them later.
|
||||||
|
|
||||||
|
#. Put the ``acrn.efi`` hypervisor application (included in the Clear
|
||||||
|
Linux release) on the EFI partition with:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# mkdir /mnt/EFI/acrn
|
||||||
|
# cp /usr/share/acrn/acrn.efi /mnt/EFI/acrn/
|
||||||
|
|
||||||
|
#. Configure the EFI firmware to boot the ACRN hypervisor by default
|
||||||
|
|
||||||
|
The ACRN hypervisor (``acrn.efi``) is an EFI executable
|
||||||
|
loaded directly by the platform EFI firmware. It then in turns loads the
|
||||||
|
Service OS bootloader. Use the ``efibootmgr`` utility to configure the EFI
|
||||||
|
firmware and add a new entry that loads the ACRN hypervisor.
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda1 -p 1 -L ACRN
|
||||||
|
# cd /mnt/EFI/org.clearlinux/
|
||||||
|
# cp bootloaderx64.efi bootloaderx64_origin.efi
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
Be aware that a Clearlinux update that includes a kernel upgrade will
|
||||||
|
reset the boot option changes you just made.. A Clearlinux update could
|
||||||
|
happen automatically (if you have
|
||||||
|
not disabled it as described above), if you later install a new
|
||||||
|
bundle to your system, or simply if you decide to trigger an update
|
||||||
|
manually. Whenever that happens, double-check the platform boot order
|
||||||
|
using ``efibootmgr -v`` and modify it if needed.
|
||||||
|
|
||||||
|
#. Create a boot entry for the ACRN Service OS by copying a provided ``acrn.conf``
|
||||||
|
and editing it to account for the kernel versions noted in a previous step.
|
||||||
|
|
||||||
|
It must contain these settings:
|
||||||
|
|
||||||
|
+-----------+----------------------------------------------------------------+
|
||||||
|
| Setting | Description |
|
||||||
|
+===========+================================================================+
|
||||||
|
| title | Text to show in the boot menu |
|
||||||
|
+-----------+----------------------------------------------------------------+
|
||||||
|
| linux | Linux kernel for the Service OS (\*-sos) |
|
||||||
|
+-----------+----------------------------------------------------------------+
|
||||||
|
| options | Options to pass to the Service OS kernel (kernel parameters) |
|
||||||
|
+-----------+----------------------------------------------------------------+
|
||||||
|
|
||||||
|
A starter acrn.conf configuration file is included in the Clear Linux release and is
|
||||||
|
also available in the acrn-hypervisor GitHub repo as `acrn.conf
|
||||||
|
<https://github.com/projectacrn/acrn-hypervisor/tree/master/bsp/uefi/clearlinux/acrn.conf>`__
|
||||||
|
as shown here:
|
||||||
|
|
||||||
|
.. literalinclude:: ../../acrn-hypervisor/bsp/uefi/clearlinux/acrn.conf
|
||||||
|
:caption: acrn-hypervisor/bsp/uefi/clearlinux/acrn.conf
|
||||||
|
|
||||||
|
On the NUC, copy the ``acrn.conf`` file to the EFI partition we mounted earlier:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# cp /usr/share/acrn/demo/acrn.conf /mnt/loader/entries/
|
||||||
|
|
||||||
|
You will need to edit this file to adjust the kernel version (``linux`` section)
|
||||||
|
and also insert the ``PARTUUID`` of your ``/dev/sda3`` partition
|
||||||
|
(``root=PARTUUID=<><UUID of rootfs partition>``) in the ``options`` section.
|
||||||
|
|
||||||
|
Use ``blkid`` to find out what your ``/dev/sda3`` ``PARTUUID`` value is.
|
||||||
|
|
||||||
|
#. Add a timeout period for Systemd-Boot to wait, otherwise it will not
|
||||||
|
present the boot menu and will always boot the base Clear Linux
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# clr-boot-manager set-timeout 20
|
||||||
|
# clr-boot-manager update
|
||||||
|
|
||||||
|
#. Reboot and select "The ACRN Service OS" to boot, as shown in
|
||||||
|
:numref:`gsg-bootmenu`:
|
||||||
|
|
||||||
|
.. figure:: images/gsg-bootmenu.png
|
||||||
|
:align: center
|
||||||
|
:width: 650px
|
||||||
|
:name: gsg-bootmenu
|
||||||
|
|
||||||
|
ACRN Service OS Boot menu
|
||||||
|
|
||||||
|
#. After booting up the ACRN hypervisor, the Service OS will be launched
|
||||||
|
automatically by default, as shown in :numref:`gsg-sos-console`:
|
||||||
|
|
||||||
|
.. figure:: images/gsg-sos-console.png
|
||||||
|
:align: center
|
||||||
|
:name: gsg-sos-console
|
||||||
|
|
||||||
|
Service OS Console
|
||||||
|
|
||||||
|
.. note:: You may need to hit ``Enter`` to get a clean login prompt
|
||||||
|
|
||||||
|
#. From here you can login as root using the password you set previously when
|
||||||
|
you installed Clear Linux.
|
||||||
|
|
||||||
|
Create a Network Bridge
|
||||||
|
=======================
|
||||||
|
|
||||||
|
Without a network bridge, the SOS and UOS are not able to talk to each
|
||||||
|
other.
|
||||||
|
|
||||||
|
A sample `bridge.sh
|
||||||
|
<https://github.com/projectacrn/acrn-devicemodel/tree/master/samples/bridge.sh>`__
|
||||||
|
is included in the Clear Linux release, and
|
||||||
|
is also available in the acrn-devicemodel GitHub repo (in the samples
|
||||||
|
folder) as shown here:
|
||||||
|
|
||||||
|
.. literalinclude:: ../../acrn-devicemodel/samples/bridge.sh
|
||||||
|
:caption: acrn-devicemodel/samples/bridge.sh
|
||||||
|
:language: bash
|
||||||
|
|
||||||
|
By default, the script is located in the ``/usr/share/acrn/demo/``
|
||||||
|
directory. Run it to create a network bridge:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# cd /usr/share/acrn/demo/
|
||||||
|
# ./bridge.sh
|
||||||
|
# cd
|
||||||
|
|
||||||
|
Set up Reference UOS
|
||||||
|
====================
|
||||||
|
|
||||||
|
#. On your NUC, download the pre-built reference Clear Linux UOS image into your
|
||||||
|
(root) home directory:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# cd ~
|
||||||
|
# curl -O https://download.clearlinux.org/releases/22140/clear/clear-22140-kvm.img.xz
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
In case you want to use or try out a newer version of Clear Linux as the UOS, you can
|
||||||
|
download the latest from http://download.clearlinux.org/image. Make sure to adjust the steps
|
||||||
|
described below accordingly (image file name and kernel modules version).
|
||||||
|
|
||||||
|
#. Uncompress it:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# unxz clear-22140-kvm.img.xz
|
||||||
|
|
||||||
|
#. Deploy the UOS kernel modules to UOS virtual disk image (note: you'll need to use
|
||||||
|
the same **standard** image version number noted in step 1 above):
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# losetup -f -P --show /root/clear-22140-kvm.img
|
||||||
|
# mount /dev/loop0p3 /mnt
|
||||||
|
# cp -r /usr/lib/modules/4.14.34-28.pk414-standard /mnt/lib/modules/
|
||||||
|
# umount /mnt
|
||||||
|
# sync
|
||||||
|
|
||||||
|
#. Edit and Run the launch_uos.sh script to launch the UOS.
|
||||||
|
|
||||||
|
A sample `launch_uos.sh
|
||||||
|
<https://github.com/projectacrn/acrn-devicemodel/tree/master/samples/launch_uos.sh>`__
|
||||||
|
is included in the Clear Linux release, and
|
||||||
|
is also available in the acrn-devicemodel GitHub repo (in the samples
|
||||||
|
folder) as shown here:
|
||||||
|
|
||||||
|
.. literalinclude:: ../../acrn-devicemodel/samples/launch_uos.sh
|
||||||
|
:caption: acrn-devicemodel/samples/launch_uos.sh
|
||||||
|
:language: bash
|
||||||
|
:emphasize-lines: 22,24
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
In case you have downloaded a different Clear Linux image than the one above
|
||||||
|
(``clear-22140-kvm.img.xz``), you will need to modify the Clear Linux file name
|
||||||
|
and version number highlighted above (the ``-s 3,virtio-blk`` argument) to match
|
||||||
|
what you have downloaded above. Likewise, you may need to adjust the kernel file
|
||||||
|
name on the second line highlighted (check the exact name to be used using:
|
||||||
|
``ls /usr/lib/kernel/org.clearlinux*-standard*``).
|
||||||
|
|
||||||
|
By default, the script is located in the ``/usr/share/acrn/demo/``
|
||||||
|
directory. You can edit it there, and then run it to launch the User OS:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
# cd /usr/share/acrn/demo/
|
||||||
|
# ./launch_uos.sh
|
||||||
|
|
||||||
|
#. At this point, you've successfully booted the ACRN hypervisor,
|
||||||
|
SOS, and UOS:
|
||||||
|
|
||||||
|
.. figure:: images/gsg-successful-boot.png
|
||||||
|
:align: center
|
||||||
|
:name: gsg-successful-boot
|
||||||
|
|
||||||
|
|
||||||
|
Build ACRN from Source
|
||||||
|
**********************
|
||||||
|
|
||||||
|
If you would like to build ACRN hypervisor and device model from source,
|
||||||
|
follow these steps.
|
||||||
|
|
||||||
|
Install build tools and dependencies
|
||||||
|
====================================
|
||||||
|
|
||||||
|
ARCN development is supported on popular Linux distributions,
|
||||||
|
each with their own way to install development tools:
|
||||||
|
|
||||||
|
* On a Clear Linux development system, install the ``os-clr-on-clr`` bundle to get
|
||||||
|
the necessary tools:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ sudo swupd bundle-add os-clr-on-clr
|
||||||
|
|
||||||
|
* On a Ubuntu/Debian development system:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ sudo apt install git \
|
||||||
|
gnu-efi \
|
||||||
|
libssl-dev \
|
||||||
|
libpciaccess-dev \
|
||||||
|
uuid-dev
|
||||||
|
|
||||||
|
* On a Fedora/Redhat development system:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ sudo dnf install gcc \
|
||||||
|
gnu-efi-devel \
|
||||||
|
libuuid-devel \
|
||||||
|
openssl-devel \
|
||||||
|
libpciaccess-devel
|
||||||
|
|
||||||
|
* On a CentOS development system:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ sudo yum install gcc \
|
||||||
|
gnu-efi-devel \
|
||||||
|
libuuid-devel \
|
||||||
|
openssl-devel \
|
||||||
|
libpciaccess-devel
|
||||||
|
|
||||||
|
Build the hypervisor and device model
|
||||||
|
=====================================
|
||||||
|
|
||||||
|
#. Download the ACRN hypervisor and build it.
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ git clone https://github.com/projectacrn/acrn-hypervisor
|
||||||
|
$ cd acrn-hypervisor
|
||||||
|
$ make PLATFORM=uefi
|
||||||
|
|
||||||
|
The build results are found in the ``build`` directory.
|
||||||
|
|
||||||
|
#. Download the ACRN device model and build it.
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ git clone https://github.com/projectacrn/acrn-devicemodel
|
||||||
|
$ cd acrn-devicemodel
|
||||||
|
$ make
|
||||||
|
|
||||||
|
The build results are found in the ``build`` directory.
|
||||||
|
|
||||||
|
Follow the same instructions to boot and test the images you created
|
||||||
|
from your build.
|
||||||
114
glossary.rst
Normal file
114
glossary.rst
Normal file
@ -0,0 +1,114 @@
|
|||||||
|
:orphan:
|
||||||
|
|
||||||
|
.. _glossary:
|
||||||
|
|
||||||
|
Glossary of Terms
|
||||||
|
#################
|
||||||
|
|
||||||
|
.. glossary::
|
||||||
|
:sorted:
|
||||||
|
|
||||||
|
API
|
||||||
|
Application Program Interface: A defined set of routines and protocols for
|
||||||
|
building application software.
|
||||||
|
|
||||||
|
ACPI
|
||||||
|
Advanced Configuration and Power Interface
|
||||||
|
|
||||||
|
BIOS
|
||||||
|
Basic Input/Output System.
|
||||||
|
|
||||||
|
GPU
|
||||||
|
Graphics Processing Unit
|
||||||
|
|
||||||
|
I2C
|
||||||
|
Inter-Integrated Circuit
|
||||||
|
|
||||||
|
IC
|
||||||
|
Instrument Cluster
|
||||||
|
|
||||||
|
IVE
|
||||||
|
In-Vehicle Experience
|
||||||
|
|
||||||
|
IVI
|
||||||
|
In-vehicle Infotainment
|
||||||
|
|
||||||
|
OS
|
||||||
|
Operating System
|
||||||
|
|
||||||
|
OSPM
|
||||||
|
Operating System Power Management
|
||||||
|
|
||||||
|
PCI
|
||||||
|
Peripheral Component Interface.
|
||||||
|
|
||||||
|
PM
|
||||||
|
Power Management
|
||||||
|
|
||||||
|
Pass-Through Devices
|
||||||
|
Physical devices (typically PCI) exclusively assigned to a guest. In
|
||||||
|
the Project ACRN architecture, pass-through devices are owned by the
|
||||||
|
foreground OS.
|
||||||
|
|
||||||
|
PV
|
||||||
|
Para-virtualization (See
|
||||||
|
https://en.wikipedia.org/wiki/Paravirtualization)
|
||||||
|
|
||||||
|
RSE
|
||||||
|
Rear Seat Entertainment
|
||||||
|
|
||||||
|
SDC
|
||||||
|
Software Defined Cockpit
|
||||||
|
|
||||||
|
SOS
|
||||||
|
Service OS
|
||||||
|
|
||||||
|
UEFI
|
||||||
|
Unified Extensible Firmare Interface. UEFI replaces the
|
||||||
|
traditional BIOS on PCs, while also providing BIOS emulation for
|
||||||
|
backward compatibility. UEFI can run in 32-bit or 64-bit mode and, more
|
||||||
|
important, support Secure Boot, checking the OS validity to ensure no
|
||||||
|
malware has tampered with the boot process.
|
||||||
|
|
||||||
|
UOS
|
||||||
|
User OS (also known as Guest OS)
|
||||||
|
|
||||||
|
VHM
|
||||||
|
Virtio and Hypervisor Service Module
|
||||||
|
|
||||||
|
VM
|
||||||
|
Virtual Machine
|
||||||
|
|
||||||
|
VMM
|
||||||
|
Virtual Machine Monitor
|
||||||
|
|
||||||
|
VMX
|
||||||
|
Virtual Machine Extension
|
||||||
|
|
||||||
|
Virtio-BE
|
||||||
|
Back-End, VirtIO framework provides front-end driver and back-end driver
|
||||||
|
for IO mediators, developer has habit of using Shorthand. So they say
|
||||||
|
Virtio-BE and Virtio-FE
|
||||||
|
|
||||||
|
Virtio-FE
|
||||||
|
Front-End, VirtIO framework provides front-end driver and back-end
|
||||||
|
driver for IO mediators, developer has habit of using Shorthand. So
|
||||||
|
they say Virtio-BE and Virtio-FE
|
||||||
|
|
||||||
|
VT
|
||||||
|
Intel Virtualization Technology
|
||||||
|
|
||||||
|
VT-d
|
||||||
|
Virtualization Technology for Directed I/O
|
||||||
|
|
||||||
|
IDT
|
||||||
|
Interrupt Descriptor Table: a data structure used by the x86
|
||||||
|
architecture to implement an interrupt vector table. The IDT is used
|
||||||
|
to determine the correct response to interrupts and exceptions.
|
||||||
|
|
||||||
|
ISR
|
||||||
|
Interrupt Service Routine: Also known as an interrupt handler, an ISR
|
||||||
|
is a callback function whose execution is triggered by a hardware
|
||||||
|
interrupt (or software interrupt instructions) and is used to handle
|
||||||
|
high-priority conditions that require interrupting the current code
|
||||||
|
executing on the processor.
|
||||||
32
hardware.rst
Normal file
32
hardware.rst
Normal file
@ -0,0 +1,32 @@
|
|||||||
|
.. _hardware:
|
||||||
|
|
||||||
|
Supported Hardware
|
||||||
|
##################
|
||||||
|
|
||||||
|
We welcome community contributions to help build Project ACRN support
|
||||||
|
for a broad collection of architectures and platforms.
|
||||||
|
|
||||||
|
This initial release of Project ACRN has been tested on the following
|
||||||
|
hardware platform.
|
||||||
|
|
||||||
|
Intel Apollo Lake NUC
|
||||||
|
*********************
|
||||||
|
|
||||||
|
* `Intel NUC Kit NUC6CAYH Reference
|
||||||
|
<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
|
||||||
27
howtos/index.rst
Normal file
27
howtos/index.rst
Normal file
@ -0,0 +1,27 @@
|
|||||||
|
.. _howtos:
|
||||||
|
|
||||||
|
How-Tos
|
||||||
|
#######
|
||||||
|
|
||||||
|
Our technical documentation for Project ACRN is being developed right
|
||||||
|
along with the features. Here are some how-to technical notes that help
|
||||||
|
explain how you can use ACRN capabilities.
|
||||||
|
|
||||||
|
|
||||||
|
Technical Notes
|
||||||
|
===============
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
:glob:
|
||||||
|
|
||||||
|
tech/*
|
||||||
|
|
||||||
|
Process Notes
|
||||||
|
=============
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
:glob:
|
||||||
|
|
||||||
|
process/*
|
||||||
BIN
howtos/process/acrn-doc-fork.png
Normal file
BIN
howtos/process/acrn-doc-fork.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
219
howtos/process/docbuild.rst
Normal file
219
howtos/process/docbuild.rst
Normal file
@ -0,0 +1,219 @@
|
|||||||
|
.. _acrn_doc:
|
||||||
|
|
||||||
|
ACRN documentation generation
|
||||||
|
#############################
|
||||||
|
|
||||||
|
These instructions will walk you through generating the Project ACRN's
|
||||||
|
documentation and publishing it to https://projectacrn.github.io.
|
||||||
|
You can also use these instructions to generate the ARCN documentation
|
||||||
|
on your local system.
|
||||||
|
|
||||||
|
Documentation overview
|
||||||
|
**********************
|
||||||
|
|
||||||
|
Project ACRN content is written using the reStructuredText markup
|
||||||
|
language (.rst file extension) with Sphinx extensions, and processed
|
||||||
|
using Sphinx to create a formatted stand-alone website. Developers can
|
||||||
|
view this content either in its raw form as .rst markup files, or you
|
||||||
|
can generate the HTML content and view it with a web browser directly on
|
||||||
|
your workstation.
|
||||||
|
|
||||||
|
You can read details about `reStructuredText`_, and `Sphinx`_ from
|
||||||
|
their respective websites.
|
||||||
|
|
||||||
|
The project's documentation contains the following items:
|
||||||
|
|
||||||
|
* ReStructuredText source files used to generate documentation found at the
|
||||||
|
http://projectacrn.github.io website. All of the reStructuredText sources
|
||||||
|
are found in this acrn-documentation repo.
|
||||||
|
|
||||||
|
* Doxygen-generated material used to create all API-specific documents
|
||||||
|
found at http://projectacrn.github.io/api/. Clones of the
|
||||||
|
acrn-hypervisor and acrn-devicemodel repos are also used to access the
|
||||||
|
header files for the the public APIs, but more about that later.
|
||||||
|
|
||||||
|
The reStructuredText files are processed by the Sphinx documentation system,
|
||||||
|
and make use of the breathe extension for including the doxygen-generated API
|
||||||
|
material.
|
||||||
|
|
||||||
|
|
||||||
|
Set up the documentation working folders
|
||||||
|
****************************************
|
||||||
|
|
||||||
|
You'll need git installed to get the working folders set up:
|
||||||
|
|
||||||
|
* For an Ubuntu development system use:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
sudo apt-get install git
|
||||||
|
|
||||||
|
* For a Fedora development system use
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
sudo dnf install git
|
||||||
|
|
||||||
|
Because we need up-to-date header files to generate API docs, doc
|
||||||
|
generation assumes the three repos are cloned as sibling folders.
|
||||||
|
Here's the recommended folder setup for documentation contributions and
|
||||||
|
generation:
|
||||||
|
|
||||||
|
.. code-block: none
|
||||||
|
|
||||||
|
projectacrn/
|
||||||
|
acrn-documentation/
|
||||||
|
acrn-hypervisor/
|
||||||
|
acrn-devicemodel/
|
||||||
|
|
||||||
|
It's best if these folders are ssh clones of your personal forks of the
|
||||||
|
upstream project ACRN repos (though https clones work too):
|
||||||
|
|
||||||
|
#. Use your browser to visit https://github.com/projectacrn. One at a
|
||||||
|
time, visit the **acrn-documentation**, **acrn-hypervisor**, and
|
||||||
|
**acrn-devicemodel** repos and do a fork to your personal GitHub account.
|
||||||
|
|
||||||
|
.. image:: acrn-doc-fork.png
|
||||||
|
:align: center
|
||||||
|
|
||||||
|
#. At a command prompt, create the working folder and clone the three
|
||||||
|
repositories to your local computer:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
cd ~
|
||||||
|
mkdir projectacrn && cd projectacrn
|
||||||
|
git clone git@github.com:<github-username>/acrn-documentation.git
|
||||||
|
git clone git@github.com:<github-username>/acrn-hypervisor.git
|
||||||
|
git clone git@github.com:<github-username>/acrn-devicemodel.git
|
||||||
|
|
||||||
|
#. For each of the cloned local repos, tell git about the upstream repos:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
cd acrn-documentation
|
||||||
|
git remote add upstream git@github.com:projectacrn/acrn-documentation.git
|
||||||
|
cd ../acrn-hypervisor
|
||||||
|
git remote add upstream git@github.com:projectacrn/acrn-hypervisor.git
|
||||||
|
cd ../acrn-devicemodel
|
||||||
|
git remote add upstream git@github.com:projectacrn/acrn-devicemodel.git
|
||||||
|
cd ..
|
||||||
|
|
||||||
|
#. If you haven't do so already, be sure to configure git with your name
|
||||||
|
and email address for the signed-off-by line in your commit messages:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
git config --global user.name "David Developer"
|
||||||
|
git config --global user.email "david.developer@company.com"
|
||||||
|
|
||||||
|
Installing the documentation tools
|
||||||
|
**********************************
|
||||||
|
|
||||||
|
Our documentation processing has been tested to run with:
|
||||||
|
|
||||||
|
* Python 3.6.3
|
||||||
|
* Doxygen version 1.8.13
|
||||||
|
* Sphinx version 1.6.7
|
||||||
|
* Breathe version 4.7.3
|
||||||
|
* docutils version 0.14
|
||||||
|
* sphinx_rtd_theme version 0.2.4
|
||||||
|
|
||||||
|
Depending on your Linux version, install the needed tools:
|
||||||
|
|
||||||
|
* For Ubuntu use:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
sudo apt-get install doxygen python3-pip python3-wheel make
|
||||||
|
|
||||||
|
* For Fedora use:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
sudo dnf install doxygen python3-pip python3-wheel make
|
||||||
|
|
||||||
|
And for either Linux environment, install the remaining python-based
|
||||||
|
tools:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
cd ~/projectacrn/acrn-documentation
|
||||||
|
pip3 install --user -r scripts/requirements.txt
|
||||||
|
|
||||||
|
And with that you're ready to generate the documentation.
|
||||||
|
|
||||||
|
Documentation presentation theme
|
||||||
|
********************************
|
||||||
|
|
||||||
|
Sphinx supports easy customization of the generated documentation
|
||||||
|
appearance through the use of themes. Replace the theme files and do
|
||||||
|
another ``make htmldocs`` and the output layout and style is changed.
|
||||||
|
The ``read-the-docs`` theme is installed as part of the
|
||||||
|
``requirements.txt`` list above.
|
||||||
|
|
||||||
|
Running the documentation processors
|
||||||
|
************************************
|
||||||
|
|
||||||
|
The acrn-documentation directory has all the .rst source files, extra tools, and Makefile for
|
||||||
|
generating a local copy of the ACRN technical documentation.
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
cd ~/projectacrn/acrn-documentation
|
||||||
|
make html
|
||||||
|
|
||||||
|
Depending on your development system, it will take about 15 seconds to
|
||||||
|
collect and generate the HTML content. When done, you can view the HTML
|
||||||
|
output with your browser started at ``~/projectacrn/acrn-documentation/_build/html/index.html``
|
||||||
|
|
||||||
|
Publishing content
|
||||||
|
******************
|
||||||
|
|
||||||
|
If you have push rights to the projectacrn repo called
|
||||||
|
projectacrn.github.io, you can update the public project documentation
|
||||||
|
found at https://projectacrn.github.io.
|
||||||
|
|
||||||
|
You'll need to do a one-time clone the upstream repo:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
git clone git@github.com:projectacrn/projectacrn.github.io.git
|
||||||
|
|
||||||
|
Then, after you've verified the generated HTML from ``make html`` looks
|
||||||
|
good, you can push directly to the publishing site with:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
make publish
|
||||||
|
|
||||||
|
This will delete everything in the publishing repo (in case the new version has
|
||||||
|
deleted files) and push a copy of the newly-generated HTML content
|
||||||
|
directly to the GitHub pages publishing repo. The public site at
|
||||||
|
https://projectacrn.github.io will be updated (nearly) immediately
|
||||||
|
so it's best to verify the locally generated html before publishing.
|
||||||
|
|
||||||
|
Filtering expected warnings
|
||||||
|
***************************
|
||||||
|
|
||||||
|
Alas, there are some known issues with the doxygen/Sphinx/Breathe
|
||||||
|
processing that generates warnings for some constructs, in particular
|
||||||
|
around unnamed structures in nested unions or structs.
|
||||||
|
While these issues are being considered for fixing in
|
||||||
|
Sphinx/Breathe, we've added a post-processing filter on the output of
|
||||||
|
the documentation build process to check for "expected" messages from the
|
||||||
|
generation process output.
|
||||||
|
|
||||||
|
The output from the Sphinx build is processed by the python script
|
||||||
|
``scripts/filter-known-issues.py`` together with a set of filter
|
||||||
|
configuration files in the ``.known-issues/doc`` folder. (This
|
||||||
|
filtering is done as part of the ``Makefile``.)
|
||||||
|
|
||||||
|
If you're contributing components included in the ACRN API
|
||||||
|
documentation and run across these warnings, you can include filtering
|
||||||
|
them out as "expected" warnings by adding a conf file to the
|
||||||
|
``.known-issues/doc`` folder, following the example of other conf files
|
||||||
|
found there.
|
||||||
|
|
||||||
|
.. _reStructuredText: http://sphinx-doc.org/rest.html
|
||||||
|
.. _Sphinx: http://sphinx-doc.org/
|
||||||
6
howtos/tech/placeholder.rst
Normal file
6
howtos/tech/placeholder.rst
Normal file
@ -0,0 +1,6 @@
|
|||||||
|
.. _wip:
|
||||||
|
|
||||||
|
Work in Progress
|
||||||
|
################
|
||||||
|
|
||||||
|
This is a placeholder doc for technical how-to articles in-progress.
|
||||||
BIN
images/ACRN-favicon-32x32.png
Normal file
BIN
images/ACRN-favicon-32x32.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.6 KiB |
BIN
images/ACRN_Logo_300w.png
Normal file
BIN
images/ACRN_Logo_300w.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
BIN
images/ACRN_Logo_56h.png
Normal file
BIN
images/ACRN_Logo_56h.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
BIN
images/ACRNlogo.png
Normal file
BIN
images/ACRNlogo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 6.5 KiB |
40
index.rst
Normal file
40
index.rst
Normal file
@ -0,0 +1,40 @@
|
|||||||
|
.. _ACRN_home:
|
||||||
|
|
||||||
|
Project ACRN documentation
|
||||||
|
##########################
|
||||||
|
|
||||||
|
Welcome to the Project ACRN (version |version|) documentation.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. _BSD 3-clause license:
|
||||||
|
https://github.com/projectacrn/acrn-hypervisor/blob/master/LICENSE
|
||||||
|
|
||||||
|
.. _Project ACRN GitHub repo: https://github.com/projectacrn
|
||||||
|
|
||||||
|
|
||||||
|
Sections
|
||||||
|
********
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
introduction/index.rst
|
||||||
|
hardware.rst
|
||||||
|
getting_started/index.rst
|
||||||
|
primer/index.rst
|
||||||
|
howtos/index.rst
|
||||||
|
release_notes.rst
|
||||||
|
contribute.rst
|
||||||
|
api/index.rst
|
||||||
|
|
||||||
|
Indices and Tables
|
||||||
|
******************
|
||||||
|
|
||||||
|
* :ref:`glossary`
|
||||||
|
* :ref:`genindex`
|
||||||
BIN
introduction/images/IVI-block.png
Normal file
BIN
introduction/images/IVI-block.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
BIN
introduction/images/VMX-brief.png
Normal file
BIN
introduction/images/VMX-brief.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
BIN
introduction/images/architecture.png
Normal file
BIN
introduction/images/architecture.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 61 KiB |
BIN
introduction/images/boot-flow.png
Normal file
BIN
introduction/images/boot-flow.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
BIN
introduction/images/device-model.png
Normal file
BIN
introduction/images/device-model.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
BIN
introduction/images/device-passthrough.png
Normal file
BIN
introduction/images/device-passthrough.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
BIN
introduction/images/io-emulation-path.png
Normal file
BIN
introduction/images/io-emulation-path.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
BIN
introduction/images/virtio-architecture.png
Normal file
BIN
introduction/images/virtio-architecture.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
BIN
introduction/images/virtio-framework-kernel.png
Normal file
BIN
introduction/images/virtio-framework-kernel.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 68 KiB |
BIN
introduction/images/virtio-framework-userland.png
Normal file
BIN
introduction/images/virtio-framework-userland.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 66 KiB |
573
introduction/index.rst
Normal file
573
introduction/index.rst
Normal file
@ -0,0 +1,573 @@
|
|||||||
|
.. _introduction:
|
||||||
|
|
||||||
|
Introduction to Project ACRN
|
||||||
|
############################
|
||||||
|
|
||||||
|
The open source project ACRN defines a device hypervisor reference stack
|
||||||
|
and an architecture for running multiple software subsystems, managed
|
||||||
|
securely, on a consolidated system by means of a virtual machine
|
||||||
|
manager. It also defines a reference framework implementation for
|
||||||
|
virtual device emulation, called the "ACRN Device Model".
|
||||||
|
|
||||||
|
The ACRN Hypervisor is a Type 1 reference hypervisor stack, running
|
||||||
|
directly on the bare-metal hardware, and is suitable for a variety of
|
||||||
|
IoT and embedded device solutions. The ACRN hypervisor addresses the gap
|
||||||
|
that currently exists between datacenter hypervisors, and hard
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
hypervisor vendors to build solutions with a reference I/O mediation
|
||||||
|
solution.
|
||||||
|
|
||||||
|
In this scenario, an automotive SDC system consists of the Instrument
|
||||||
|
Cluster (IC) system, the In-Vehicle Infotainment (IVI) system, and one
|
||||||
|
or more Rear Seat Entertainment (RSE) systems. Each system is running as
|
||||||
|
an isolated Virtual Machine (VM) for overall system safety
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
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
|
||||||
|
OEMs can use this reference stack to run their own VMs, together with
|
||||||
|
IC, IVI, and RSE VMs. The Service OS runs as VM0 (also known as Dom0 in
|
||||||
|
other hypervisors) and the User OS runs as VM1, (also known as DomU).
|
||||||
|
|
||||||
|
:numref:`ivi-block` shows an example block diagram of using the ACRN
|
||||||
|
hypervisor.
|
||||||
|
|
||||||
|
.. figure:: images/IVI-block.png
|
||||||
|
:align: center
|
||||||
|
:name: ivi-block
|
||||||
|
|
||||||
|
Service OS and User OS on top of ACRN 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.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
The yellow color parts in :numref:`ivi-block` are part of the project
|
||||||
|
ACRN software stack. This is a reference architecture diagram and not
|
||||||
|
all features mentioned are fully functional. Other blocks will come from
|
||||||
|
other (open source) projects and are listed here for reference only.
|
||||||
|
|
||||||
|
For example: the Service OS and Linux Guest can come from the Clear
|
||||||
|
Linux project at https://clearlinux.org and (in later updates) the
|
||||||
|
Android as a Guest support can come from https://01.org/android-ia.
|
||||||
|
|
||||||
|
For the current ACRN-supported feature list, please see
|
||||||
|
:ref:`release_notes`.
|
||||||
|
|
||||||
|
Licensing
|
||||||
|
*********
|
||||||
|
.. _BSD-3-Clause: https://opensource.org/licenses/BSD-3-Clause
|
||||||
|
|
||||||
|
Both the ACRN hypervisor and ACRN Device model software are provided
|
||||||
|
under the permissive `BSD-3-Clause`_ license, which allows
|
||||||
|
*"redistribution and use in source and binary forms, with or without
|
||||||
|
modification"* together with the intact copyright notice and
|
||||||
|
disclaimers noted in the license.
|
||||||
|
|
||||||
|
|
||||||
|
ACRN Device Model, Service OS, and User OS
|
||||||
|
******************************************
|
||||||
|
|
||||||
|
To keep the hypervisor code base as small and efficient as possible, the
|
||||||
|
bulk of the device model implementation resides in the Service OS to
|
||||||
|
provide sharing and other capabilities. The details of which devices are
|
||||||
|
shared and the mechanism used for their sharing is described in
|
||||||
|
`pass-through`_ section below.
|
||||||
|
|
||||||
|
The Service OS runs with the system's highest virtual machine priority
|
||||||
|
to ensure required device time-sensitive requirements and system quality
|
||||||
|
of service (QoS). Service OS tasks run with mixed priority. Upon a
|
||||||
|
callback servicing a particular User OS request, the corresponding
|
||||||
|
software (or mediator) in the Service OS inherits the User OS priority.
|
||||||
|
There may also be additional low-priority background tasks within the
|
||||||
|
Service OS.
|
||||||
|
|
||||||
|
In the automotive example we described above, the User OS is the central
|
||||||
|
hub of vehicle control and in-vehicle entertainment. It provides support
|
||||||
|
for radio and entertainment options, control of the vehicle climate
|
||||||
|
control, and vehicle navigation displays. It also provides connectivity
|
||||||
|
options for using USB, Bluetooth, and WiFi for third-party device
|
||||||
|
interaction with the vehicle, such as Android Auto\* or Apple CarPlay*,
|
||||||
|
and many other features.
|
||||||
|
|
||||||
|
Boot Sequence
|
||||||
|
*************
|
||||||
|
|
||||||
|
In :numref:`boot-flow` we show a verified Boot Sequence with UEFI
|
||||||
|
on an Intel |reg| Architecture platform NUC (see :ref:`hardware`).
|
||||||
|
|
||||||
|
.. figure:: images/boot-flow.png
|
||||||
|
:align: center
|
||||||
|
:name: boot-flow
|
||||||
|
|
||||||
|
ACRN Hypervisor Boot Flow
|
||||||
|
|
||||||
|
The Boot process proceeds as follows:
|
||||||
|
|
||||||
|
#. 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
|
||||||
|
#. Virtual bootloader starts the User-side verified boot process
|
||||||
|
|
||||||
|
|
||||||
|
ACRN Hypervisor Architecture
|
||||||
|
****************************
|
||||||
|
|
||||||
|
ACRN hypervisor is a Type 1 hypervisor, running directly on bare-metal
|
||||||
|
hardware. It implements a hybrid VMM architecture, using a privileged
|
||||||
|
service VM, running the Service OS that manages the I/O devices and
|
||||||
|
provides I/O mediation. Multiple User VMs are supported, with each of
|
||||||
|
them running Linux\* or Android\* OS as the User OS .
|
||||||
|
|
||||||
|
Running systems in separate VMs provides isolation between other VMs and
|
||||||
|
their applications, reducing potential attack surfaces and minimizing
|
||||||
|
safety interference. However, running the systems in separate VMs may
|
||||||
|
introduce additional latency for applications.
|
||||||
|
|
||||||
|
:numref:`ACRN-architecture` shows the ACRN hypervisor architecture, with
|
||||||
|
the automotive example IC VM and service VM together. The Service OS
|
||||||
|
(SOS) owns most of the devices including the platform devices, and
|
||||||
|
provides I/O mediation. Some of the PCIe devices may be passed through
|
||||||
|
to the User OSes via the VM configuration. The SOS runs the IC
|
||||||
|
applications and hypervisor-specific applications together, such as the
|
||||||
|
ACRN device model, and ACRN VM manager.
|
||||||
|
|
||||||
|
ACRN hypervisor also runs the ACRN VM manager to collect running
|
||||||
|
information of the User OS, and controls the User VM such as starting,
|
||||||
|
stopping, and pausing a VM, pausing or resuming a virtual CPU.
|
||||||
|
|
||||||
|
.. figure:: images/architecture.png
|
||||||
|
:align: center
|
||||||
|
:name: ACRN-architecture
|
||||||
|
|
||||||
|
ACRN Hypervisor Architecture
|
||||||
|
|
||||||
|
ACRN hypervisor takes advantage of Intel Virtualization Technology
|
||||||
|
(Intel VT), and ACRN hypervisor runs in Virtual Machine Extension (VMX)
|
||||||
|
root operation, or host mode, or VMM mode. All the guests, including
|
||||||
|
UOS and SOS, run in VMX non-root operation, or guest mode. (Hereafter,
|
||||||
|
we use the terms VMM mode and Guest mode for simplicity).
|
||||||
|
|
||||||
|
The VMM mode has 4 protection rings, but runs the ACRN hypervisor in
|
||||||
|
ring 0 privilege only, leaving rings 1-3 unused. The guest (including
|
||||||
|
SOS & UOS), running in Guest mode, also has its own four protection
|
||||||
|
rings (ring 0 to 3). The User kernel runs in ring 0 of guest mode, and
|
||||||
|
user land applications run in ring 3 of User mode (ring 1 & 2 are
|
||||||
|
usually not used by commercial OSes).
|
||||||
|
|
||||||
|
.. figure:: images/VMX-brief.png
|
||||||
|
:align: center
|
||||||
|
:name: VMX-brief
|
||||||
|
|
||||||
|
VMX Brief
|
||||||
|
|
||||||
|
As shown in :numref:`VMX-brief`, VMM mode and guest mode are switched
|
||||||
|
through VM Exit and VM Entry. When the bootloader hands off control to
|
||||||
|
the ACRN hypervisor, the processor hasn't enabled VMX operation yet. The
|
||||||
|
ACRN hypervisor needs to enable VMX operation thru a VMXON instruction
|
||||||
|
first. Initially, the processor stays in VMM mode when the VMX operation
|
||||||
|
is enabled. It enters guest mode thru a VM resume instruction (or first
|
||||||
|
time VM launch), and returns back to VMM mode thru a VM exit event. VM
|
||||||
|
exit occurs in response to certain instructions and events.
|
||||||
|
|
||||||
|
The behavior of processor execution in guest mode is controlled by a
|
||||||
|
virtual machine control structure (VMCS). VMCS contains the guest state
|
||||||
|
(loaded at VM Entry, and saved at VM Exit), the host state, (loaded at
|
||||||
|
the time of VM exit), and the guest execution controls. ACRN hypervisor
|
||||||
|
creates a VMCS data structure for each virtual CPU, and uses the VMCS to
|
||||||
|
configure the behavior of the processor running in guest mode.
|
||||||
|
|
||||||
|
When the execution of the guest hits a sensitive instruction, a VM exit
|
||||||
|
event may happen as defined in the VMCS configuration. Control goes back
|
||||||
|
to the ACRN hypervisor when the VM exit happens. The ACRN hypervisor
|
||||||
|
emulates the guest instruction (if the exit was due to privilege issue)
|
||||||
|
and resumes the guest to its next instruction, or fixes the VM exit
|
||||||
|
reason (for example if a guest memory page is not mapped yet) and resume
|
||||||
|
the guest to re-execute the instruction.
|
||||||
|
|
||||||
|
Note that the address space used in VMM mode is different from that in
|
||||||
|
guest mode. The guest mode and VMM mode use different memory mapping
|
||||||
|
tables, and therefore the ACRN hypervisor is protected from guest
|
||||||
|
access. The ACRN hypervisor uses EPT to map the guest address, using the
|
||||||
|
guest page table to map from guest linear address to guest physical
|
||||||
|
address, and using the EPT table to map from guest physical address to
|
||||||
|
machine physical address or host physical address (HPA).
|
||||||
|
|
||||||
|
ACRN Device Model Architecture
|
||||||
|
******************************
|
||||||
|
|
||||||
|
Because devices may need to be shared between VMs, device emulation is
|
||||||
|
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
|
||||||
|
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
|
||||||
|
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
|
||||||
|
also used by a large number of independent hypervisors. This model is
|
||||||
|
advantageous, because the device emulation is independent of the
|
||||||
|
hypervisor and can therefore be shared for other hypervisors. It also
|
||||||
|
permits arbitrary device emulation without having to burden the
|
||||||
|
hypervisor (which operates in a privileged state) with this
|
||||||
|
functionality.
|
||||||
|
|
||||||
|
* The third variation on hypervisor-based device emulation is
|
||||||
|
**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.
|
||||||
|
|
||||||
|
.. _XEN project:
|
||||||
|
https://wiki.xenproject.org/wiki/Understanding_the_Virtualization_Spectrum
|
||||||
|
|
||||||
|
In the device emulation models discussed above, there's a price to pay
|
||||||
|
for sharing devices. Whether device emulation is performed in the
|
||||||
|
hypervisor, or in user space within an independent VM, overhead exists.
|
||||||
|
This overhead is worthwhile as long as the devices need to be shared by
|
||||||
|
multiple guest operating systems. If sharing is not necessary, then
|
||||||
|
there are more efficient methods for accessing devices, for example
|
||||||
|
"pass-through".
|
||||||
|
|
||||||
|
ACRN device model is a placeholder of the UOS. It allocates memory for
|
||||||
|
the User OS, configures and initializes the devices used by the UOS,
|
||||||
|
loads the virtual firmware, initializes the virtual CPU state, and
|
||||||
|
invokes the ACRN hypervisor service to execute the guest instructions.
|
||||||
|
ACRN Device model is an application running in the Service OS that
|
||||||
|
emulates devices based on command line configuration, as shown in
|
||||||
|
the architecture diagram :numref:`device-model` below:
|
||||||
|
|
||||||
|
.. figure:: images/device-model.png
|
||||||
|
:align: center
|
||||||
|
:name: device-model
|
||||||
|
|
||||||
|
ACRN Device Model
|
||||||
|
|
||||||
|
ACRN Device model incorporates these three aspects:
|
||||||
|
|
||||||
|
**Device Emulation**:
|
||||||
|
ACRN Device model provides device emulation routines that register
|
||||||
|
their I/O handlers to the I/O dispatcher. When there is an I/O request
|
||||||
|
from the User OS device, the I/O dispatcher sends this request to the
|
||||||
|
corresponding device emulation routine.
|
||||||
|
|
||||||
|
**I/O Path**:
|
||||||
|
see `ACRN-io-mediator`_ below
|
||||||
|
|
||||||
|
**VHM**:
|
||||||
|
The Virtio and Hypervisor Service Module is a kernel module in the
|
||||||
|
Service OS acting as a middle layer to support the device model. The VHM
|
||||||
|
and its client handling flow is described below:
|
||||||
|
|
||||||
|
#. ACRN hypervisor IOREQ is forwarded to the VHM by an upcall
|
||||||
|
notification to the SOS.
|
||||||
|
#. VHM will mark the IOREQ as "in process" so that the same IOREQ will
|
||||||
|
not pick up again. The IOREQ will be sent to the client for handling.
|
||||||
|
Meanwhile, the VHM is ready for another IOREQ.
|
||||||
|
#. IOREQ clients are either an SOS Userland application or a Service OS
|
||||||
|
Kernel space module. Once the IOREQ is processed and completed, the
|
||||||
|
Client will issue an IOCTL call to the VHM to notify an IOREQ state
|
||||||
|
change. The VHM then checks and hypercalls to ACRN hypervisor
|
||||||
|
notifying it that the IOREQ has completed.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
Userland: dm as ACRN Device Model.
|
||||||
|
|
||||||
|
Kernel space: VBS-K, MPT Service, VHM itself
|
||||||
|
|
||||||
|
.. _pass-through:
|
||||||
|
|
||||||
|
Device pass through
|
||||||
|
*******************
|
||||||
|
|
||||||
|
At the highest level, device pass-through is about providing isolation
|
||||||
|
of a device to a given guest operating system so that the device can be
|
||||||
|
used exclusively by that guest.
|
||||||
|
|
||||||
|
.. figure:: images/device-passthrough.png
|
||||||
|
:align: center
|
||||||
|
:name: device-passthrough
|
||||||
|
|
||||||
|
Device Passthrough
|
||||||
|
|
||||||
|
Near-native performance can be achieved by using device passthrough.
|
||||||
|
This is ideal for networking applications (or those with high disk I/O
|
||||||
|
needs) that have not adopted virtualization because of contention and
|
||||||
|
performance degradation through the hypervisor (using a driver in the
|
||||||
|
hypervisor or through the hypervisor to a user space emulation).
|
||||||
|
Assigning devices to specific guests is also useful when those devices
|
||||||
|
inherently wouldn't be shared. For example, if a system includes
|
||||||
|
multiple video adapters, those adapters could be passed through to
|
||||||
|
unique guest domains.
|
||||||
|
|
||||||
|
Finally, there may be specialized PCI devices that only one guest domain
|
||||||
|
uses, so they should be passed through to the guest. Individual USB
|
||||||
|
ports could be isolated to a given domain too, or a serial port (which
|
||||||
|
is itself not shareable) could be isolated to a particular guest. In
|
||||||
|
ACRN hypervisor, we support USB controller Pass through only and we
|
||||||
|
don't support pass through for a legacy serial port, (for example
|
||||||
|
0x3f8).
|
||||||
|
|
||||||
|
|
||||||
|
Hardware support for device passthrough
|
||||||
|
=======================================
|
||||||
|
|
||||||
|
Intel's current processor architectures provides support for device
|
||||||
|
pass-through with VT-d. VT-d maps guest physical address to machine
|
||||||
|
physical address, so device can use guest physical address directly.
|
||||||
|
When this mapping occurs, the hardware takes care of access (and
|
||||||
|
protection), and the guest operating system can use the device as if it
|
||||||
|
were a non-virtualized system. In addition to mapping guest to physical
|
||||||
|
memory, isolation prevents this device from accessing memory belonging
|
||||||
|
to other guests or the hypervisor.
|
||||||
|
|
||||||
|
Another innovation that helps interrupts scale to large numbers of VMs
|
||||||
|
is called Message Signaled Interrupts (MSI). Rather than relying on
|
||||||
|
physical interrupt pins to be associated with a guest, MSI transforms
|
||||||
|
interrupts into messages that are more easily virtualized (scaling to
|
||||||
|
thousands of individual interrupts). MSI has been available since PCI
|
||||||
|
version 2.2 but is also available in PCI Express (PCIe), where it allows
|
||||||
|
fabrics to scale to many devices. MSI is ideal for I/O virtualization,
|
||||||
|
as it allows isolation of interrupt sources (as opposed to physical pins
|
||||||
|
that must be multiplexed or routed through software).
|
||||||
|
|
||||||
|
Hypervisor support for device passthrough
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
By using the latest virtualization-enhanced processor architectures,
|
||||||
|
hypervisors and virtualization solutions can support device
|
||||||
|
pass-through (using VT-d), including Xen, KVM, and ACRN hypervisor.
|
||||||
|
In most cases, the guest operating system (User
|
||||||
|
OS) must be compiled to support pass-through, by using
|
||||||
|
kernel build-time options. Hiding the devices from the host VM may also
|
||||||
|
be required (as is done with Xen using pciback). Some restrictions apply
|
||||||
|
in PCI, for example, PCI devices behind a PCIe-to-PCI bridge must be
|
||||||
|
assigned to the same guest OS. PCIe does not have this restriction.
|
||||||
|
|
||||||
|
.. _ACRN-io-mediator:
|
||||||
|
|
||||||
|
ACRN I/O mediator
|
||||||
|
*****************
|
||||||
|
|
||||||
|
:numref:`io-emulation-path` shows the flow of an example I/O emulation path.
|
||||||
|
|
||||||
|
.. figure:: images/io-emulation-path.png
|
||||||
|
:align: center
|
||||||
|
:name: io-emulation-path
|
||||||
|
|
||||||
|
I/O Emulation Path
|
||||||
|
|
||||||
|
Following along with the numbered items in :numref:`io-emulation-path`:
|
||||||
|
|
||||||
|
1. When a guest execute an I/O instruction (PIO or MMIO), a VM exit happens.
|
||||||
|
ACRN hypervisor takes control, and analyzes the the VM
|
||||||
|
exit reason, which is a VMX_EXIT_REASON_IO_INSTRUCTION for PIO access.
|
||||||
|
2. ACRN hypervisor fetches and analyzes the guest instruction, and
|
||||||
|
notices it is a PIO instruction (``in AL, 20h`` in this example), and put
|
||||||
|
the decoded information (including the PIO address, size of access,
|
||||||
|
read/write, and target register) into the shared page, and
|
||||||
|
notify/interrupt the SOS to process.
|
||||||
|
3. The Virtio and hypervisor service module (VHM) in SOS receives the
|
||||||
|
interrupt, and queries the IO request ring to get the PIO instruction
|
||||||
|
details.
|
||||||
|
4. It checks to see if any kernel device claims
|
||||||
|
ownership of the IO port: if a kernel module claimed it, the kernel
|
||||||
|
module is activated to execute its processing APIs. Otherwise, the VHM
|
||||||
|
module leaves the IO request in the shared page and wakes up the
|
||||||
|
device model thread to process.
|
||||||
|
5. The ACRN device model follow the same mechanism as the VHM. The I/O
|
||||||
|
processing thread of device model queries the IO request ring to get the
|
||||||
|
PIO instruction details and checks to see if any (guest) device emulation
|
||||||
|
module claims ownership of the IO port: if a module claimed it,
|
||||||
|
the module is invoked to execute its processing APIs.
|
||||||
|
6. After the ACRN device module completes the emulation (port IO 20h access
|
||||||
|
in this example), (say uDev1 here), uDev1 puts the result into the
|
||||||
|
shared page (in register AL in this example).
|
||||||
|
7. ACRN device model then returns control to ACRN hypervisor to indicate the
|
||||||
|
completion of an IO instruction emulation, typically thru VHM/hypercall.
|
||||||
|
8. The ACRN hypervisor then knows IO emulation is complete, and copies
|
||||||
|
the result to the guest register context.
|
||||||
|
9. The ACRN hypervisor finally advances the guest IP to
|
||||||
|
indicate completion of instruction execution, and resumes the guest.
|
||||||
|
|
||||||
|
The MMIO path is very similar, except the VM exit reason is different. MMIO
|
||||||
|
access usually is trapped thru VMX_EXIT_REASON_EPT_VIOLATION in
|
||||||
|
the hypervisor.
|
||||||
|
|
||||||
|
Virtio framework architecture
|
||||||
|
*****************************
|
||||||
|
|
||||||
|
.. _Virtio spec:
|
||||||
|
http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html
|
||||||
|
|
||||||
|
Virtio is an abstraction for a set of common emulated devices in any
|
||||||
|
type of hypervisor. In the ACRN reference stack, our
|
||||||
|
implementation is compatible with `Virtio spec`_ 0.9 and 1.0. By
|
||||||
|
following this spec, virtual environments and guests
|
||||||
|
should have a straightforward, efficient, standard and extensible
|
||||||
|
mechanism for virtual devices, rather than boutique per-environment or
|
||||||
|
per-OS mechanisms.
|
||||||
|
|
||||||
|
Virtio provides a common frontend driver framework which not only
|
||||||
|
standardizes device interfaces, but also increases code reuse across
|
||||||
|
different virtualization platforms.
|
||||||
|
|
||||||
|
.. figure:: images/virtio-architecture.png
|
||||||
|
:align: center
|
||||||
|
:name: virtio-architecture
|
||||||
|
|
||||||
|
Virtio Architecture
|
||||||
|
|
||||||
|
To better understand Virtio, especially its usage in
|
||||||
|
the ACRN project, several key concepts of Virtio are highlighted
|
||||||
|
here:
|
||||||
|
|
||||||
|
**Front-End Virtio driver** (a.k.a. frontend driver, or FE driver in this document)
|
||||||
|
Virtio adopts a frontend-backend architecture, which enables a simple
|
||||||
|
but flexible framework for both frontend and backend Virtio driver. The
|
||||||
|
FE driver provides APIs to configure the interface, pass messages, produce
|
||||||
|
requests, and notify backend Virtio driver. As a result, the FE driver
|
||||||
|
is easy to implement and the performance overhead of emulating device is
|
||||||
|
eliminated.
|
||||||
|
|
||||||
|
**Back-End Virtio driver** (a.k.a. backend driver, or BE driver in this document)
|
||||||
|
Similar to FE driver, the BE driver, runs either in user-land or
|
||||||
|
kernel-land of host OS. The BE driver consumes requests from FE driver
|
||||||
|
and send them to the host's native device driver. Once the requests are
|
||||||
|
done by the host native device driver, the BE driver notifies the FE
|
||||||
|
driver about the completeness of the requests.
|
||||||
|
|
||||||
|
**Straightforward**: Virtio devices as standard devices on existing Buses
|
||||||
|
Instead of creating new device buses from scratch, Virtio devices are
|
||||||
|
built on existing buses. This gives a straightforward way for both FE
|
||||||
|
and BE drivers to interact with each other. For example, FE driver could
|
||||||
|
read/write registers of the device, and the virtual device could
|
||||||
|
interrupt FE driver, on behalf of the BE driver, in case of something is
|
||||||
|
happening. Currently Virtio supports PCI/PCIe bus and MMIO bus. In
|
||||||
|
ACRN project, only PCI/PCIe bus is supported, and all the Virtio devices
|
||||||
|
share the same vendor ID 0x1AF4.
|
||||||
|
|
||||||
|
**Efficient**: batching operation is encouraged
|
||||||
|
Batching operation and deferred notification are important to achieve
|
||||||
|
high-performance I/O, since notification between FE and BE driver
|
||||||
|
usually involves an expensive exit of the guest. Therefore batching
|
||||||
|
operating and notification suppression are highly encouraged if
|
||||||
|
possible. This will give an efficient implementation for the performance
|
||||||
|
critical devices.
|
||||||
|
|
||||||
|
**Standard: virtqueue**
|
||||||
|
All the Virtio devices share a standard ring buffer and descriptor
|
||||||
|
mechanism, called a virtqueue, shown in Figure 6. A virtqueue
|
||||||
|
is a queue of scatter-gather buffers. There are three important
|
||||||
|
methods on virtqueues:
|
||||||
|
|
||||||
|
* ``add_buf`` is for adding a request/response buffer in a virtqueue
|
||||||
|
* ``get_buf`` is for getting a response/request in a virtqueue, and
|
||||||
|
* ``kick`` is for notifying the other side for a virtqueue to
|
||||||
|
consume buffers.
|
||||||
|
|
||||||
|
The virtqueues are created in guest physical memory by the FE drivers.
|
||||||
|
The BE drivers only need to parse the virtqueue structures to obtain
|
||||||
|
the requests and get the requests done. How virtqueue is organized is
|
||||||
|
specific to the User OS. In the implementation of Virtio in Linux, the
|
||||||
|
virtqueue is implemented as a ring buffer structure called vring.
|
||||||
|
|
||||||
|
In ACRN, the virtqueue APIs can be leveraged
|
||||||
|
directly so users don't need to worry about the details of the
|
||||||
|
virtqueue. Refer to the User OS for
|
||||||
|
more details about the virtqueue implementations.
|
||||||
|
|
||||||
|
**Extensible: feature bits**
|
||||||
|
A simple extensible feature negotiation mechanism exists for each virtual
|
||||||
|
device and its driver. Each virtual device could claim its
|
||||||
|
device specific features while the corresponding driver could respond to
|
||||||
|
the device with the subset of features the driver understands. The
|
||||||
|
feature mechanism enables forward and backward compatibility for the
|
||||||
|
virtual device and driver.
|
||||||
|
|
||||||
|
In the ACRN reference stack, we implement user-land and kernel
|
||||||
|
space as shown in :numref:`virtio-framework-userland`:
|
||||||
|
|
||||||
|
.. figure:: images/virtio-framework-userland.png
|
||||||
|
:align: center
|
||||||
|
:name: virtio-framework-userland
|
||||||
|
|
||||||
|
Virtio Framework - User Land
|
||||||
|
|
||||||
|
In the Virtio user-land framework, the implementation is compatible with
|
||||||
|
Virtio Spec 0.9/1.0. The VBS-U is statically linked with Device Model,
|
||||||
|
and communicates with Device Model through the PCIe interface: PIO/MMIO
|
||||||
|
or MSI/MSIx. VBS-U accesses Virtio APIs through user space vring service
|
||||||
|
API helpers. User space vring service API helpers access shared ring
|
||||||
|
through remote memory map (mmap). VHM maps UOS memory with the help of
|
||||||
|
ACRN Hypervisor.
|
||||||
|
|
||||||
|
.. figure:: images/virtio-framework-kernel.png
|
||||||
|
:align: center
|
||||||
|
:name: virtio-framework-kernel
|
||||||
|
|
||||||
|
Virtio Framework - Kernel Space
|
||||||
|
|
||||||
|
VBS-U offloads data plane processing to VBS-K. VBS-U initializes VBS-K
|
||||||
|
at the right timings, for example. The FE driver sets
|
||||||
|
VIRTIO_CONFIG_S_DRIVER_OK to avoid unnecessary device configuration
|
||||||
|
changes while running. VBS-K can access shared rings through VBS-K
|
||||||
|
virtqueue APIs. VBS-K virtqueue APIs are similar to VBS-U virtqueue
|
||||||
|
APIs. VBS-K registers as VHM client(s) to handle a continuous range of
|
||||||
|
registers
|
||||||
|
|
||||||
|
There may be one or more VHM-clients for each VBS-K, and there can be a
|
||||||
|
single VHM-client for all VBS-Ks as well. VBS-K notifies FE through VHM
|
||||||
|
interrupt APIs.
|
||||||
66
introduction/index.rst.sav
Normal file
66
introduction/index.rst.sav
Normal file
@ -0,0 +1,66 @@
|
|||||||
|
.. _introduction:
|
||||||
|
|
||||||
|
Introducing Project ACRN
|
||||||
|
########################
|
||||||
|
|
||||||
|
The open source project ACRN, defines a device hypervisor reference
|
||||||
|
stack and an architecture for running multiple software subsystems,
|
||||||
|
managed securely, on a consolidated system by means of a virtual machine
|
||||||
|
manager. It also defines a reference framework implementation for
|
||||||
|
virtual device emulation, called the “ACRN Device Model”.
|
||||||
|
|
||||||
|
The ACRN Hypervisor is a Type 1 reference hypervisor stack, running
|
||||||
|
directly on the bare-metal hardware, and is suitable for a variety of
|
||||||
|
IoT and embedded device solutions. The ACRN hypervisor addresses the gap
|
||||||
|
that currently exists between datacenter hypervisors, and hard
|
||||||
|
partitioning hypervisors. The ACRN hypervisor architecture partitions
|
||||||
|
the system into different functional domains, with carefully selected
|
||||||
|
guest OS sharing optimiztionsfor IoT and embedded devices.
|
||||||
|
|
||||||
|
Automotive use case scenario
|
||||||
|
****************************
|
||||||
|
|
||||||
|
A good 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, Project ACRN provides the basis for embedded
|
||||||
|
hypervisor vendors to build solutions with a reference I/O mediation
|
||||||
|
solution.
|
||||||
|
|
||||||
|
For example, an automotive SDC system consists of the Instrument Cluster
|
||||||
|
(IC) system, the In-Vehicle Infotainment (IVI) system, and one or more
|
||||||
|
Rear Seat Entertainment (RSE) systems. Each system can run on the same
|
||||||
|
hardware as isolated Virtual Machines (VM), for overall system safety
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
The ACRN hypervisor supports both Linux* VM and Android* VM as a User
|
||||||
|
OS, with the User OS managed by the ACRN hypervisor. Developers and OEMs
|
||||||
|
can use this reference stack to run their own VMs, together with the IC,
|
||||||
|
IVI, and RSE VMs. The Service OS runs as VM0, (also known as Dom0 in
|
||||||
|
other hypervisors), and the User OS runs as VM1, (also known as DomU).
|
||||||
BIN
primer/images/primer-dma-address-mapping.png
Normal file
BIN
primer/images/primer-dma-address-mapping.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
BIN
primer/images/primer-host-gdt.png
Normal file
BIN
primer/images/primer-host-gdt.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 66 KiB |
BIN
primer/images/primer-hypervisor-interrupt.png
Normal file
BIN
primer/images/primer-hypervisor-interrupt.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 85 KiB |
BIN
primer/images/primer-mem-layout.png
Normal file
BIN
primer/images/primer-mem-layout.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
BIN
primer/images/primer-pirq-routing.png
Normal file
BIN
primer/images/primer-pirq-routing.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
BIN
primer/images/primer-pv-mapping.png
Normal file
BIN
primer/images/primer-pv-mapping.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
BIN
primer/images/primer-sos-ept-mapping.png
Normal file
BIN
primer/images/primer-sos-ept-mapping.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
BIN
primer/images/primer-symmetric-io.png
Normal file
BIN
primer/images/primer-symmetric-io.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 89 KiB |
BIN
primer/images/primer-uos-ept-mapping.png
Normal file
BIN
primer/images/primer-uos-ept-mapping.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
BIN
primer/images/primer-virtio-net.png
Normal file
BIN
primer/images/primer-virtio-net.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 73 KiB |
903
primer/index.rst
Normal file
903
primer/index.rst
Normal file
@ -0,0 +1,903 @@
|
|||||||
|
.. _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 hypervisor and the
|
||||||
|
ACRN device model source tree provides the following top-level
|
||||||
|
directories:
|
||||||
|
|
||||||
|
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
|
||||||
|
=============================
|
||||||
|
|
||||||
|
**core/**
|
||||||
|
ACRN Device model core logic (main loop, SOS interface, etc.)
|
||||||
|
|
||||||
|
**hw/**
|
||||||
|
Hardware emulation code, with the following subdirectories:
|
||||||
|
|
||||||
|
**acpi/**
|
||||||
|
ACPI table generator.
|
||||||
|
|
||||||
|
**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/**
|
||||||
|
include files for all public APIs (doxygen comments in these source
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
**primer/**
|
||||||
|
ReST files and images for the Developer Primer
|
||||||
|
|
||||||
|
**images/**
|
||||||
|
Image files not specific to a document (logos, and such)
|
||||||
|
|
||||||
|
**introduction/**
|
||||||
|
ReST files and images for the Introduction to Project ACRN
|
||||||
|
|
||||||
|
**scripts/**
|
||||||
|
Files used to assist building the documentation set
|
||||||
|
|
||||||
|
**static/**
|
||||||
|
Sphinx folder for extras added to the generated output (such as custom
|
||||||
|
CSS additions)
|
||||||
|
|
||||||
|
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
|
||||||
58
release_notes.rst
Normal file
58
release_notes.rst
Normal file
@ -0,0 +1,58 @@
|
|||||||
|
.. _release_notes:
|
||||||
|
|
||||||
|
Release Notes
|
||||||
|
#############
|
||||||
|
|
||||||
|
Version 0.1 release (March 2018)
|
||||||
|
********************************
|
||||||
|
|
||||||
|
In March 2018, Intel announced the open source Project ACRN at the
|
||||||
|
`Embedded Linux Conference and OpenIoT Summit North America 2018
|
||||||
|
<ELC18>`_.
|
||||||
|
|
||||||
|
.. _ELC18:
|
||||||
|
https://events.linuxfoundation.org/events/elc-openiot-north-america-2018/
|
||||||
|
|
||||||
|
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. 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's key features include:
|
||||||
|
|
||||||
|
* Small footprint
|
||||||
|
* Built with real-time in mind
|
||||||
|
* Virtualization of embedded IoT device functions
|
||||||
|
* Safety-critical workload considerations
|
||||||
|
* Adaptable
|
||||||
|
* Open Source
|
||||||
|
|
||||||
|
This version 0.1 release has the following software components:
|
||||||
|
|
||||||
|
* The ACRN Hypervisor
|
||||||
|
* The ACRN Device Model
|
||||||
|
* The ACRN Virtio framework
|
||||||
|
* The ACRN Block & NIC & console Virtio drivers
|
||||||
|
* The ACRN Virtio Backend Service(VBS) & Virtio and Hypervisor Service Module(VHM).
|
||||||
|
|
||||||
|
Version 0.1 features include:
|
||||||
|
|
||||||
|
* ACRN hypervisor (Type 1 hypervisor)
|
||||||
|
* A hybrid VMM architecture implementation
|
||||||
|
* Multiple User OS supported
|
||||||
|
* VM management - such as VM start/stop/pause, virtual CPU pause/resume
|
||||||
|
* CPU virtualization
|
||||||
|
* Memory virtualization
|
||||||
|
* I/O emulation
|
||||||
|
* Virtual interrupt
|
||||||
|
* VT-x and VT-d support
|
||||||
|
* Hypercall for guest
|
||||||
|
* Device emulation
|
||||||
|
* Device pass-through mechanism
|
||||||
|
* Device Emulation mechanism
|
||||||
|
* Virtio console
|
||||||
|
* Virt-network
|
||||||
49
scripts/filter-doc-log.sh
Executable file
49
scripts/filter-doc-log.sh
Executable file
@ -0,0 +1,49 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
# run the filter-known-issues.py script to remove "expected" warning
|
||||||
|
# messages from the output of the document build process and write
|
||||||
|
# the filtered output to stdout
|
||||||
|
#
|
||||||
|
# Only argument is the name of the log file saved by the build.
|
||||||
|
|
||||||
|
KI_SCRIPT=scripts/filter-known-issues.py
|
||||||
|
CONFIG_DIR=.known-issues/doc
|
||||||
|
|
||||||
|
LOG_FILE=$1
|
||||||
|
|
||||||
|
if [ -z "${LOG_FILE}" ]; then
|
||||||
|
echo "Error in $0: missing input parameter <logfile>"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# When running in background, detached from terminal jobs, tput will
|
||||||
|
# fail; we usually can tell because there is no TERM env variable.
|
||||||
|
if [ -z "${TERM:-}" -o "${TERM:-}" = dumb ]; then
|
||||||
|
TPUT="true"
|
||||||
|
red=''
|
||||||
|
green=''
|
||||||
|
else
|
||||||
|
TPUT="tput"
|
||||||
|
red='\E[31m'
|
||||||
|
green='\e[32m'
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [ -s "${LOG_FILE}" ]; then
|
||||||
|
$KI_SCRIPT --config-dir ${CONFIG_DIR} ${LOG_FILE} > doc.warnings 2>&1
|
||||||
|
if [ -s doc.warnings ]; then
|
||||||
|
echo
|
||||||
|
echo -e "${red}New errors/warnings found, please fix them:"
|
||||||
|
echo -e "=============================================="
|
||||||
|
$TPUT sgr0
|
||||||
|
echo
|
||||||
|
cat doc.warnings
|
||||||
|
echo
|
||||||
|
else
|
||||||
|
echo -e "${green}No new errors/warnings."
|
||||||
|
$TPUT sgr0
|
||||||
|
fi
|
||||||
|
|
||||||
|
else
|
||||||
|
echo "Error in $0: logfile \"${LOG_FILE}\" not found."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
254
scripts/filter-known-issues.py
Executable file
254
scripts/filter-known-issues.py
Executable file
@ -0,0 +1,254 @@
|
|||||||
|
#! /usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Filters a file, classifying output in errors, warnings and discarding
|
||||||
|
the rest.
|
||||||
|
|
||||||
|
Given a set of regular expresions read from files named *.conf in the
|
||||||
|
given configuration path(s), of the format:
|
||||||
|
|
||||||
|
#
|
||||||
|
# Comments for multiline regex 1...
|
||||||
|
#
|
||||||
|
MULTILINEPYTHONREGEX
|
||||||
|
MULTILINEPYTHONREGEX
|
||||||
|
MULTILINEPYTHONREGEX
|
||||||
|
#
|
||||||
|
# Comments for multiline regex 2...
|
||||||
|
#
|
||||||
|
#WARNING
|
||||||
|
MULTILINEPYTHONREGEX2
|
||||||
|
MULTILINEPYTHONREGEX2
|
||||||
|
|
||||||
|
Anything matched by MULTILINEPYTHONREGEX will be considered something
|
||||||
|
to be filtered out and not printed.
|
||||||
|
|
||||||
|
Anything matched by MULTILINEPYHONREGEX with a #WARNING tag in the
|
||||||
|
comment means (optional) means that it describes something that is
|
||||||
|
considered to be a warning. Print it to stderr.
|
||||||
|
|
||||||
|
Anything leftover is considred to be errors, printed to stdout.
|
||||||
|
|
||||||
|
"""
|
||||||
|
import argparse
|
||||||
|
import logging
|
||||||
|
import mmap
|
||||||
|
import os
|
||||||
|
import re
|
||||||
|
import sre_constants
|
||||||
|
import sys
|
||||||
|
import traceback
|
||||||
|
|
||||||
|
exclude_regexs = []
|
||||||
|
|
||||||
|
# first is a list of one or more comment lines
|
||||||
|
# followed by a list of non-comments which describe a multiline regex
|
||||||
|
config_regex = \
|
||||||
|
b"(?P<comment>(^\s*#.*\n)+)" \
|
||||||
|
b"(?P<regex>(^[^#].*\n)+)"
|
||||||
|
|
||||||
|
|
||||||
|
def config_import_file(filename):
|
||||||
|
"""
|
||||||
|
Imports regular expresions from any file *.conf in the given path,
|
||||||
|
format as given in the main doc
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
with open(filename, "rb") as f:
|
||||||
|
mm = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ)
|
||||||
|
# That regex basically selects any block of
|
||||||
|
# lines that is not a comment block. The
|
||||||
|
# finditer() finds all the blocks and selects
|
||||||
|
# the bits of mmapped-file that comprises
|
||||||
|
# each--we compile it into a regex and append.
|
||||||
|
for m in re.finditer(config_regex, mm, re.MULTILINE):
|
||||||
|
origin = "%s:%s-%s" % (filename, m.start(), m.end())
|
||||||
|
gd = m.groupdict()
|
||||||
|
comment = gd['comment']
|
||||||
|
regex = gd['regex']
|
||||||
|
try:
|
||||||
|
r = re.compile(regex, re.MULTILINE)
|
||||||
|
except sre_constants.error as e:
|
||||||
|
logging.error("%s: bytes %d-%d: bad regex: %s",
|
||||||
|
filename, m.start(), m.end(), e)
|
||||||
|
raise
|
||||||
|
logging.debug("%s: found regex at bytes %d-%d: %s",
|
||||||
|
filename, m.start(), m.end(), regex)
|
||||||
|
if b'#WARNING' in comment:
|
||||||
|
exclude_regexs.append((r, origin, ('warning',)))
|
||||||
|
else:
|
||||||
|
exclude_regexs.append((r, origin, ()))
|
||||||
|
logging.debug("%s: loaded", filename)
|
||||||
|
except Exception as e:
|
||||||
|
logging.error("E: %s: can't load config file: %s" % (filename, e))
|
||||||
|
raise
|
||||||
|
|
||||||
|
|
||||||
|
def config_import_path(path):
|
||||||
|
"""
|
||||||
|
Imports regular expresions from any file *.conf in the given path
|
||||||
|
"""
|
||||||
|
file_regex = re.compile(".*\.conf$")
|
||||||
|
try:
|
||||||
|
for dirpath, dirnames, filenames in os.walk(path):
|
||||||
|
for _filename in sorted(filenames):
|
||||||
|
filename = os.path.join(dirpath, _filename)
|
||||||
|
if not file_regex.search(_filename):
|
||||||
|
logging.debug("%s: ignored", filename)
|
||||||
|
continue
|
||||||
|
config_import_file(filename)
|
||||||
|
except Exception as e:
|
||||||
|
raise Exception(
|
||||||
|
"E: %s: can't load config files: %s %s" %
|
||||||
|
(path, e, traceback.format_exc()))
|
||||||
|
|
||||||
|
|
||||||
|
def config_import(paths):
|
||||||
|
"""
|
||||||
|
Imports regular expresions from any file *.conf in the list of paths.
|
||||||
|
|
||||||
|
If a path is "" or None, the list of paths until then is flushed
|
||||||
|
and only the new ones are considered.
|
||||||
|
"""
|
||||||
|
_paths = []
|
||||||
|
# Go over the list, flush it if the user gave an empty path ("")
|
||||||
|
for path in paths:
|
||||||
|
if path == "" or path is None:
|
||||||
|
logging.debug("flushing current config list: %s", _paths)
|
||||||
|
_paths = []
|
||||||
|
else:
|
||||||
|
_paths.append(path)
|
||||||
|
logging.debug("config list: %s", _paths)
|
||||||
|
for path in _paths:
|
||||||
|
config_import_path(path)
|
||||||
|
|
||||||
|
|
||||||
|
arg_parser = argparse.ArgumentParser(
|
||||||
|
description=__doc__,
|
||||||
|
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||||
|
arg_parser.add_argument("-v", "--verbosity", action="count", default=0,
|
||||||
|
help="increase verbosity")
|
||||||
|
arg_parser.add_argument("-q", "--quiet", action="count", default=0,
|
||||||
|
help="decrease verbosity")
|
||||||
|
arg_parser.add_argument("-e", "--errors", action="store", default=None,
|
||||||
|
help="file where to store errors")
|
||||||
|
arg_parser.add_argument("-w", "--warnings", action="store", default=None,
|
||||||
|
help="file where to store warnings")
|
||||||
|
arg_parser.add_argument("-c", "--config-dir", action="append", nargs="?",
|
||||||
|
default=[".known-issues/"],
|
||||||
|
help="configuration directory (multiple can be "
|
||||||
|
"given; if none given, clears the current list) "
|
||||||
|
"%(default)s")
|
||||||
|
arg_parser.add_argument("FILENAMEs", nargs="+",
|
||||||
|
help="files to filter")
|
||||||
|
args = arg_parser.parse_args()
|
||||||
|
|
||||||
|
logging.basicConfig(level=40 - 10 * (args.verbosity - args.quiet),
|
||||||
|
format="%(levelname)s: %(message)s")
|
||||||
|
|
||||||
|
path = ".known-issues/"
|
||||||
|
logging.debug("Reading configuration from directory `%s`", path)
|
||||||
|
config_import(args.config_dir)
|
||||||
|
|
||||||
|
exclude_ranges = []
|
||||||
|
|
||||||
|
if args.warnings:
|
||||||
|
warnings = open(args.warnings, "w")
|
||||||
|
else:
|
||||||
|
warnings = None
|
||||||
|
if args.errors:
|
||||||
|
errors = open(args.errors, "w")
|
||||||
|
else:
|
||||||
|
errors = None
|
||||||
|
|
||||||
|
|
||||||
|
def report_error(data):
|
||||||
|
sys.stdout.write(data)
|
||||||
|
if errors:
|
||||||
|
errors.write(data)
|
||||||
|
|
||||||
|
|
||||||
|
def report_warning(data):
|
||||||
|
sys.stderr.write(data)
|
||||||
|
if warnings:
|
||||||
|
warnings.write(data)
|
||||||
|
|
||||||
|
|
||||||
|
if args.warnings:
|
||||||
|
warnings = open(args.warnings, "w")
|
||||||
|
else:
|
||||||
|
warnings = None
|
||||||
|
if args.errors:
|
||||||
|
errors = open(args.errors, "w")
|
||||||
|
else:
|
||||||
|
errors = None
|
||||||
|
|
||||||
|
|
||||||
|
def report_error(data):
|
||||||
|
sys.stdout.write(data.decode('utf-8'))
|
||||||
|
if errors:
|
||||||
|
errors.write(data)
|
||||||
|
|
||||||
|
|
||||||
|
def report_warning(data):
|
||||||
|
sys.stderr.write(data)
|
||||||
|
if warnings:
|
||||||
|
warnings.write(data)
|
||||||
|
|
||||||
|
|
||||||
|
for filename in args.FILENAMEs:
|
||||||
|
if os.stat(filename).st_size == 0:
|
||||||
|
continue # skip empty log files
|
||||||
|
try:
|
||||||
|
with open(filename, "r+b") as f:
|
||||||
|
logging.info("%s: filtering", filename)
|
||||||
|
# Yeah, this should be more protected in case of exception
|
||||||
|
# and such, but this is a short running program...
|
||||||
|
mm = mmap.mmap(f.fileno(), 0)
|
||||||
|
for ex, origin, flags in exclude_regexs:
|
||||||
|
logging.info("%s: searching from %s: %s",
|
||||||
|
filename, origin, ex.pattern)
|
||||||
|
for m in re.finditer(ex.pattern, mm, re.MULTILINE):
|
||||||
|
logging.info("%s: %s-%s: match from from %s %s",
|
||||||
|
filename, m.start(), m.end(), origin, flags)
|
||||||
|
if 'warning' in flags:
|
||||||
|
exclude_ranges.append((m.start(), m.end(), True))
|
||||||
|
else:
|
||||||
|
exclude_ranges.append((m.start(), m.end(), False))
|
||||||
|
|
||||||
|
exclude_ranges = sorted(exclude_ranges, key=lambda r: r[0])
|
||||||
|
logging.warning(
|
||||||
|
"%s: ranges excluded: %s",
|
||||||
|
filename,
|
||||||
|
exclude_ranges)
|
||||||
|
|
||||||
|
# Decide what to do with what has been filtered; warnings
|
||||||
|
# go to stderr and warnings file, errors to stdout, what
|
||||||
|
# is ignored is just dumped.
|
||||||
|
offset = 0
|
||||||
|
for b, e, warning in exclude_ranges:
|
||||||
|
mm.seek(offset)
|
||||||
|
if b > offset:
|
||||||
|
# We have something not caught by a filter, an error
|
||||||
|
logging.info("%s: error range (%d, %d), from %d %dB",
|
||||||
|
filename, offset, b, offset, b - offset)
|
||||||
|
report_error(mm.read(b - offset))
|
||||||
|
mm.seek(b)
|
||||||
|
if warning == True: # A warning, print it
|
||||||
|
mm.seek(b)
|
||||||
|
logging.info("%s: warning range (%d, %d), from %d %dB",
|
||||||
|
filename, b, e, offset, e - b)
|
||||||
|
report_warning(mm.read(e - b))
|
||||||
|
else: # Exclude, ignore it
|
||||||
|
d = b - offset
|
||||||
|
logging.info("%s: exclude range (%d, %d), from %d %dB",
|
||||||
|
filename, b, e, offset, d)
|
||||||
|
offset = e
|
||||||
|
mm.seek(offset)
|
||||||
|
if len(mm) != offset:
|
||||||
|
logging.info("%s: error final range from %d %dB",
|
||||||
|
filename, offset, len(mm))
|
||||||
|
report_error(mm.read(len(mm) - offset - 1))
|
||||||
|
del mm
|
||||||
|
except Exception as e:
|
||||||
|
logging.error("%s: cannot load: %s", filename, e)
|
||||||
|
raise
|
||||||
5
scripts/publish-README.md
Normal file
5
scripts/publish-README.md
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
# projectacrn.github.io
|
||||||
|
This is the Project ACRN Documentation Publishing site for GitHub Pages.
|
||||||
|
Content changes are not made directly in this repo. Instead, edit content
|
||||||
|
in the acrn-documentation repo, re-generate the HTML with Sphinx, and push
|
||||||
|
the updated content here for publishing.
|
||||||
10
scripts/publish-index.html
Normal file
10
scripts/publish-index.html
Normal file
@ -0,0 +1,10 @@
|
|||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<title>ACRN Hypervisor documentation</title>
|
||||||
|
<meta http-equiv="refresh" content="0; URL=latest/index.html">
|
||||||
|
<meta name="keywords" content="automatic redirection">
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
Please visit the <a href="/latest/">latest ACRN documentation</a>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
30
scripts/pullsource.sh
Executable file
30
scripts/pullsource.sh
Executable file
@ -0,0 +1,30 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
q="--quiet"
|
||||||
|
|
||||||
|
# pull fresh copies of the ACRN source for use by doxygen
|
||||||
|
|
||||||
|
if [ ! -d "../acrn-hypervisor" ]; then
|
||||||
|
echo Repo for acrn-hypervisor is missing.
|
||||||
|
exit -1
|
||||||
|
fi
|
||||||
|
if [ ! -d "../acrn-devicemodel" ]; then
|
||||||
|
echo Repo for acrn-devicemodel is missing.
|
||||||
|
exit -1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Assumes origin (personal) and upstream (project) remote repos are
|
||||||
|
# setup
|
||||||
|
|
||||||
|
cd ../acrn-hypervisor
|
||||||
|
git checkout $q master;
|
||||||
|
git fetch $q upstream
|
||||||
|
git merge $q upstream/master
|
||||||
|
git push $q origin master
|
||||||
|
|
||||||
|
|
||||||
|
cd ../acrn-devicemodel
|
||||||
|
git checkout $q master;
|
||||||
|
git fetch $q upstream
|
||||||
|
git merge $q upstream/master
|
||||||
|
git push $q origin master
|
||||||
4
scripts/requirements.txt
Normal file
4
scripts/requirements.txt
Normal file
@ -0,0 +1,4 @@
|
|||||||
|
breathe==4.7.3
|
||||||
|
sphinx==1.6.7
|
||||||
|
docutils==0.14
|
||||||
|
sphinx_rtd_theme
|
||||||
113
static/acrn-custom.css
Normal file
113
static/acrn-custom.css
Normal file
@ -0,0 +1,113 @@
|
|||||||
|
/* -- Extra CSS styles for ACRN content (RTD theme) ----------------------- */
|
||||||
|
|
||||||
|
/* make the page width fill the window */
|
||||||
|
.wy-nav-content {
|
||||||
|
max-width: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* (temporarily) add an under development tagline to the bread crumb
|
||||||
|
.wy-breadcrumbs::after {
|
||||||
|
content: " (Content under development)";
|
||||||
|
background-color: #FFFACD;
|
||||||
|
color: red;
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
|
*/
|
||||||
|
|
||||||
|
/* tweak doc version selection
|
||||||
|
.rst-versions {
|
||||||
|
position: static;
|
||||||
|
border-top: none;
|
||||||
|
padding: 0px;
|
||||||
|
} */
|
||||||
|
|
||||||
|
.rst-versions .rst-current-version {
|
||||||
|
padding: 5px;
|
||||||
|
background-color: #2980B9;
|
||||||
|
color: #80FF80;
|
||||||
|
}
|
||||||
|
|
||||||
|
.rst-versions .rst-other-versions {
|
||||||
|
padding: 5px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.rst-other-versions dl {
|
||||||
|
margin-bottom: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* code block highlight color in rtd changed to lime green, no no no */
|
||||||
|
|
||||||
|
.rst-content tt.literal, .rst-content code.literal, .highlight {
|
||||||
|
background: #f0f0f0;
|
||||||
|
}
|
||||||
|
.rst-content tt.literal, .rst-content code.literal {
|
||||||
|
color: #000000;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Make the version number more visible */
|
||||||
|
.wy-side-nav-search>div.version {
|
||||||
|
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;
|
||||||
|
margin-top: 1em;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* add a colon after the figure/table number (before the caption) */
|
||||||
|
span.caption-number::after {
|
||||||
|
content: ": ";
|
||||||
|
}
|
||||||
|
|
||||||
|
p.extrafooter {
|
||||||
|
text-align: right;
|
||||||
|
margin-top: -36px;
|
||||||
|
}
|
||||||
|
|
||||||
|
table.align-center {
|
||||||
|
display: table !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
.code-block-caption {
|
||||||
|
color: #000;
|
||||||
|
font: italic 85%/1 arial,sans-serif;
|
||||||
|
padding: 1em 0;
|
||||||
|
text-align: center;
|
||||||
|
}
|
||||||
|
`
|
||||||
|
/* make .. hlist:: tables fill the page */
|
||||||
|
table.hlist {
|
||||||
|
width: 95% !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* override rtd theme white-space no-wrap in table heading and content */
|
||||||
|
th,td {
|
||||||
|
white-space: normal !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* dbk tweak for doxygen-generated API headings (for RTD theme) */
|
||||||
|
.rst-content dl.group>dt, .rst-content dl.group>dd>p {
|
||||||
|
display:none !important;
|
||||||
|
}
|
||||||
|
.rst-content dl.group {
|
||||||
|
margin: 0 0 12px 0px;
|
||||||
|
}
|
||||||
|
.rst-content dl.group>dd {
|
||||||
|
margin-left: 0 !important;
|
||||||
|
}
|
||||||
|
.rst-content p.breathe-sectiondef-title {
|
||||||
|
text-decoration: underline; /* dbk for API sub-headings */
|
||||||
|
font-size: 1.25rem;
|
||||||
|
font-weight: bold;
|
||||||
|
margin-bottom: 12px;
|
||||||
|
}
|
||||||
|
.rst-content div.breathe-sectiondef {
|
||||||
|
padding-left: 0 !important;
|
||||||
|
}
|
||||||
4
static/jquery.js
vendored
Normal file
4
static/jquery.js
vendored
Normal file
File diff suppressed because one or more lines are too long
Loading…
Reference in New Issue
Block a user