mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-06-20 12:42:54 +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
|
||||
devicemdodel/build/
|
||||
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