Default vertical alignment of "middle" doesn't look good on large
tables, so override to be "top" of the cell.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Sphinx transforms ``--`` into an en-dash within a paragraph (not within
a code, pre, or kbd block though). This presents a problem documenting
command parameters such as ``--name`` where the ``--`` is transformed
into a single en-dash. Rather than disabling all smartquote
transformations in the Sphinx conf.py (setting ``smartquotes = False``),
we fixes cases where ``--`` should not be transformed by using a block
that is ignored by the smartquote transformation.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Use a table instead of a dictionary list to make the parameter
description layout more readable.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
1, changed Clear Linux installation from "automatically" to "manually"
2, removed bundle "soft-defined-cockpit" installation
3, removed bundle "openssh-server" installation
4, add a bundle"desktop-autostart" as the default installation. so that a desktop is showing for the first time reboot after setup done
5, add a non room user with “sudoers” privilege to avoid using root directly
6, removed section "Device Manager memory allocation mechanism"
Tracked-On: #1794
Signed-off-by: ailun258 <ailin.yang@intel.com>
Change background colors of API elements to improve readability and
match configuration documentation look.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This patch adds more comment to describe functions that are
interfaces to the other modules in the hypervisor. The comments
are in doxygen-style for document generation.
Tracked-On: #1595
Signed-off-by: Li, Fei1 <fei1.li@intel.com>
To kick off the efforts on modularization, this patch introduces a document
describing the goals and general principles of modular design as well as a brief
introduction on the current status of component/module decomposition.
A detailed assignment of source files to components will be added in the future.
v2 -> v3:
* Expand mailing list address in the doc
v1 -> v2:
* Add more description on complexity measures, cyclic dependency avoidance, and
the reverse dependency of boot on hypervisor initialzation.
* Fix typos.
Tracked-On: #1842
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
1. No more mount needed, use the directory "/boot/efi"
2. The kernel of UOS stored in "~/uos-kernel-build"
3. (Pending) the image of UOS stored in "~/" or "/root"
Now it's using the memory reserve by hypervisor. So there's not
necessaty to map or ummap this region from SOS.
Tracked-On: #1942
Signed-off-by: Li, Fei1 <fei1.li@intel.com>
The Sphinx .. only:: directive is limited to handling only conditional
text and can't handling conditional use of directives. For example,
.. only:: test
.. automodule:: west.runners.core
:members:
is not handled. This PR monkey patches the handling of the existing
.. only:: directive done by Sphinx.
See https://github.com/pfalcon/sphinx_selective_exclude for details.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the 'launch_uos.sh' script for UEFI platforms to point at the latest
iot-lts2018 kernel installed by means of the
/usr/lib/kernel/default-default-iot-lts2018 symlink which is set-up by the
kernel-iot-lts2018 bundle.
Update the Getting Started Guide to reflect this minor change.
Tracked-On: #1927
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Update the 'kernel-doc' script to the latest version available from
https://github.com/projectacrn/acrn-kernel.
This solves the following error when generating the ACRN documentation:
"Unescaped left brace in regex is deprecated here (and will be fatal in Perl
5.32), passed through in regex; marked by <-- HERE in m/({ <-- HERE .*})/ at
scripts/kernel-doc line 2176."
Tracked-On: #1926
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This patch adds vtd.h to the input of doxygen and replaces hard-coded API docs
with doxygen-generated ones.
Tracked-On: #1595
Signed-off-by: Binbin Wu <binbin.wu@intel.com>
Reviewed-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
CSE FW uses an AEK (Attestation keybox Encryption Key) to encrypt the keybox
with AES-256-GCM algorithm before sending it to Android/Trusty. This key is
derived from the latest platform Seed by CSE FW with KDF (key derivation function)
HMAC-SHA256. After Trusty retrieves this encrypted keybox over HECI/MEI driver,
Trusty needs the same AEKkey to decrypt it. Hence, before Trusty launches,
Hypervisor derives the same AEK key from Platform Seed with the same algorithm
and the same derivation parameters, then sends this AEK along with Trusty vSeed
to Trusty world memory.
Since Platform Seed is only visible to Hypervisor and it must not be
sent to any guest VM, only Hypervisor can derive this AEK from this
Platform Seed, just like previous per-Trusty virtual Seed derivation.
Please note that Android Attestation Keybox is shared in a single hardware
platform, so all the Trusty instance/world can get the same AEK for
decryption even if there are multiple Android User OS/VMs running
on top of Hypervisor.
v1 --> v2:
Add detailed description why we need the patch to derive an extra key
v2 --> v3:
Convert API descriptions to Doxygen
Tracked-On: #1812
Reviewed-by: Bing Zhu <bing.zhu@intel.com>
Reviewed-by: Kai Wang <kai.z.wang@intel.com>
Signed-off-by: Chen Gang G <gang.g.chen@intel.com>
Acked-by: Bing Zhu <bing.zhu@intel.com>
-- Config MAX_EMULATED_MMIO_REGIONS 16 in Kconfig
-- Add emulated mmio array and emulated mmio regions
in vm structure
-- Remove mmio list in vm structure
-- Remove unregister_mmio_emulation_handler and
vioapic_cleanup APIs
Tracked-On: #861
Signed-off-by: Mingqiang Chi <mingqiang.chi@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
Update Getting Started Guide (GSG) with Clear Linux version and
kernel versions for ACRN v0.3.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Update the capitalization of "Tracked-On" in the documentation.
"Tracked-on" should work but it throws a warning so it's better
to make the documentation focus on using "Tracked-On" only.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Sphinx supports making a single (large) html file instead of a
full website with a collection of html pages. This ``make singlehtml``
option provides the basis for creating a Word document (for example)
via a cut-and-paste of a section of the documentation (not easily
possible when the docs are in multiple HTML files.)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
updates:
1, update Clear Linux version to 26120 support v0.3 release
2, update product kernel to kernel-iot-lts2018 since there is new named bundle
Signed-off-by: Ailun258 <ailin.yang@intel.com>
-- Add emulated port io index
-- Add emulated pio array in vm structure
-- Remove port list in vm structure
-- Remove free_io_emulation_resource/register_io_handler/
create_io_handler APIs
v2-->v3:
-- not add 'is_emulated', check len == 0U
-- Check if io_read/io_write handler is NULL before calling
-- Replace ENUM with MACRO for emulated pio index to avoid
MISRA-C violations
v1-->v2:
-- Remove EMUL_PIO_NUM in Kconfig, add emulated pio index
for PIC/PCI/UART/RTC/PM
Tracked-On: #861
Signed-off-by: Mingqiang Chi <mingqiang.chi@intel.com>
Reviewed-by: Jason Chen CJ <jason.cj.chen@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
Transcode, edit, and upload HLD 0.7 section 6.5 (Supported Virtio
Devices), merging with existing reviewed content.
Tracked-on: #1732
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This patch adds ioreq.h to the input of doxygen and replaces hard-coded API docs
with doxygen-generated ones.
Tracked-On: #1595
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Getting Started Guide: add one more bundle to be added on a Clear
Linux development machine to make sure 'make' and other development
packages are available.
ACRN Documentation Generation: expand the 'PATH' variable to include
'~/.local/bin' where 'sphinx-build' is installed.
Tracked-On: #1650
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This patch adds vtd.h to the input of doxygen and replaces hard-coded API docs
with doxygen-generated ones.
Tracked-On: #1595
Signed-off-by: Binbin Wu <binbin.wu@intel.com>
The patch adds related head files to the input of doxygen and
replaces hard-code API docs with doxygen-generated ones.
v1-->v2:
Put the 'kerneldoc' back.
V2-->V3:
Rebase
Tracked-On: #1595
Signed-off-by: Xiangyang Wu <xiangyang.wu@linux.intel.com>
Convert line endings setting for l1tf.rst doc
from windows style to unix style.
Tracked-On: #1672
Signed-off-by: Yonghua Huang <yonghua.huang@intel.com>
Sphinx/Breathe have a known problem with processing unnamed nested
structs and unions that cause a "Duplicate definition" warning.
Use our .known-issues filter to hide these in the HLD content.
Tracked-on: #1706
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Transcode, edit, and upload HLD 0.7 section 4 (Device Model)
Incorporate changes from previously edited acpi-virt.rst and delete
separate doc.
Tracked-on: #1668
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
PR #1678 requires slight tweaking of doxygen/known-issues handling to
successfully generate documentation
Tracked-on: #1595
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Transcode, edit, and upload HLD 0.7 section 3.10 (PM in hypervisor),
3.11 (Console, shell, vUART), 3.12 (Hypercall/VHM upcall), and
3.13 (Compile-time config)
Also scan/replace UTF-8 punctuation missed in previous PRs.
Add anchor targets in referenced docs.
Tracked-on: #1648
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The current defconfigs are BIOS-specific which makes it difficult to maintain
multiple defconfigs for boards running the same BIOS.
This patch re-organizes the defconfigs to be board-specific. A command line
option BOARD is introduced to specify a board on which the current build targets
at. The original PLATFORM is kept for backward compatibility which redirects to
apl-mrb and nuc6cayh for sbl and uefi, respectively.
The getting started guide is also updated accordingly.
v1 -> v2:
* Rewrite 'up2' to 'UP2'.
Tracked-On: #1588
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Reviewed-by: Anthony Xu <anthony.xu@intel.com>
transcode, edit, and upload HLD 0.7 section 3.7 (Virtual Interrupt)
Add target references in other docs as needed.
Tracked-on: #1623
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
transcode, edit, and upload HLD 0.7 section 3.6 (Timer)
Also, fix the hv sections file names to be consistent.
Tracked-on: #1623
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Tweak the 'Using partition mode on UP2' tutorial by removing
a couple of Grub menu entries that are not present by default
(nor introduced as part of the tutorial).
Also make it more obvious that there is still a default entry
called 'Ubuntu' which is the one by default.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Transcode, edit, and upload HLD 0.7 sections 3.4 (I/O emulation)
Add anchor targets to other docs reference in this section.
Update .known-issues filter for "known" doxygen/breathe errors
Tracked-on: #1592
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
When the doc log is scanned for potential "new" errors, if any are found
it wasn't returning a non-zero error code.
Tracked-on: #1514
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Replace the askew photo of a GRUB screen with a ``code-block:: console``
directive.
Tracked-On: #1160
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This patch adds tutorial about all the steps you need to take in order to use
partition mode with ACRN hypervisor on UP2.
Tracked-On: #1160
Signed-off-by: Kaige Fu <kaige.fu@intel.com>
Update HLD documentation with HLD 0.7 section 3.3 (Memory Management).
Add a referenced target link to hv-cpu-virt.rst
Tracked-on: #1590
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
ACRN hypervisor follows MISRA-C which has some inconsistencies with the Linux
kernel coding style. Namely,
* Braces are required even for single-statement blocks.
* Zero-initialisers to global variables are allowed.
* Line limit is 120 instead of 80.
This patch adds a .checkpatch.conf so that checkpatch.pl stops warning on the
exceptions above when invoked under the root directory of the acrn-hypervisor
repository.
The coding style documentation is updated accordingly.
Tracked-On: #1557
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Update the converted HLD 0.7 section 3.2 with a previously converted
static partitioning document (instead of a separate doc for this topic).
Tracked-on: #1533
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
For traceability, all changes must include a Tracked-On: line indicating
the issue driving this change.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Tracked-On: #1420
Fix one typo (in a command) in the tutorial entitled "Using
Ubuntu as the Service OS".
Add a note explaining that a script may have to be adjusted
based on the HW set-up (network interface name).
Tracked-On: #1502
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
There is a compilation error when using the stock gcc compiler
from Ubuntu 16.04. This adds a note to our Getting Started
Guide to indicate what the error is and how to work around it.
Tracked-On: #1482
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Minor update to the tutorial on how to use Ubuntu as the Service OS
with ACRN. Specifically, the instructions for making the Grub menu
visible at boot time now involved modify the /etc/default/grub file
and not the /boot/grub/grub.cfg as before.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Reorganize the high-level design docs to align with a work-in-progress
HLD document. Migrate previous web content (and images) into the new
organization.
From here we'll continue inclusion of new design chapters as they're
reviewed and edited.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The genrest.py script (used to generate config documentation from the
Kconfig files) broke when upgrading to the latest kconfiglib (10.9.1).
Copied the latest genrest.py script from the Zephyr project (where this
script and processing was developed) and things work again.
Update Makefile's call to genrest.py (toplevel Kconfig path is now found
relative to the srctree.
Update requirements.txt to match the kconfiglib version family
verified to work.
fixes: #1387
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Documentation scripts: enhance 'show-versions.py'
Modify the doc/scripts/show-versions.py script by making it
gather the list of Python modules to check the version for from
the "requirements.txt" file. It should help keep this in sync
if/when our requirements evolve.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
The genrest.py script (used to generate config documentation from the
Kconfig files) broke when upgrading to the latest kconfiglib (10.9.1).
Copied the latest genrest.py script from the Zephyr project (where this
script and processing was developed) and things work again.
Also update requirements.txt to match the kconfiglib version verified to
work.
tracked-on: #1387
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Add instructions on how to disable ('mask') the 'cbc_*' services
installed by the 'ioc-cbc-tools'. These services are not functional
on standard off-the-shelf platforms such as NUCs or UP2.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Fix the delimiting character used when adding an extra row
to a table so as to make it consistent with the other rows.
Remove an extra set of "<>"
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
The "launch_uos.sh" script has evolved and the lines that we
highlight have moved. Update the syntax to highlight the correct
lines.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Add a pointer to the documentation generation tutorial from the
Getting Started Guide (in the "Building ACRN") section.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Update the list of bundles to be installed in the Service OS. The
"desktop" bundle is no longer require as "software-defined-cockpit"
includes all media and graphics components.
Add "sudo" to the list (it was installed as part of the "desktop"
bundle previously).
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Add a note (and instruction) on how to use a specific version of
Clear Linux on a system. Picking up the image of a specific release
is not sufficient as Clear Linux always grabs the very latest image
when installing.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Added a python script that displays versions of doc building tools
(e.g., doxygen, breathe, sphinx) to help verify doc building environment
is properly set up (can help doc building problem diagnostic, as shown
in issue #1333
Update doc build documentation to reference this script.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The .. code-block:: console directive (used for white text on a black
background) didn't handle some CSS cases properly resulting in
unreadable grey text on a black background.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the doc build instructions to include how to update the version
navigation selector (bottom of the left nav panel), and make commands
for building and publishing specific tagged releases (e.g., 0.2)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update conf.py selector list to include version 0.2 documentation (and
fix an URL typo in the release notes).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Remove "DRAFT" indicator, and a few tweaks to repo description and
download instructions noticed in PR #1316
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Need to make sure the local projectacrn.github.io is in sync with the
master before starting up the publishing process.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Removed white space at the end of the line, and fixed a sentence that
did not have a space after the period.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
In special cases, we'd like to freeze doc versions based on a tag (e.g.,
tags/acrn-2018w34.4-140000p) and have that version show up on the
generated docs. (Normally the version shown is from the
hypervisor/VERSION file.)
With this patch, if DOC_TAG=release then it uses a RELEASE=name
environment variable (e.g., from the make command line) to override the
displayed version:
make DOC_TAG=release RELEASE=acrn-2018w34.4-140000p html
make DOC_TAG=release RELEASE=acrn-2018w34.4-140000p publish
Assuming you've checked out the tagged branch (both for acrn-hypervisor
and acrn-kernel), these make commands will generate and publish docs to
https://projectacrn.github.io/acrn-2018w34.4-14000p
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the ACRN documentation to use the official name of GVT-g
in ACRN to "AcrnGT" (ACRN-GT was previously widely used).
Also update the few occurences of "GVT-G" to "GVT-g" to be
consistent across our documentation. This includes a couple of
file name updates.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Break out each version release notes into a separate .rst file and an
organizing top-level release notes page.
Create a draft version for the v0.2 release notes.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the Getting Started Guide to correct the URL pointing at
the sample 'acrn.conf' file that is in the source code tree.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
The doc build process copies files using script/extract-content.py from
outside of the doc/ folder (specifically content in the tools/ folders).
The script was not copying graphviz directive files. This has been
fixed and the embedded graphviz directives are not (properly) stored in
separate image/*.dot files.
Note the extract-content.py file is derived from the Zephyr project.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
1, update contents to align latest acrn and clear Linux release
2, change /etc/grub.d/40_custom file to specify 'insmod ext2', not 'insmod ext4' and github issue- https://github.com/projectacrn/acrn-hypervisor/issues/707
3, add tap device and network sharing enabling script as the example for ubuntu SOS
4, add several tips for new user to use ubuntu as the SOS
Signed-off-by: ailun258 ailin.yang@intel.com
verified again, with user name cl-sos. it doesn't work to fix#663
but cl_sos is working, so update the user name to cl_sos. that means
clear has naming rules for user name
Add parameters introduction for virtio-blk
Signed-off-by: Conghui Chen <conghui.chen@intel.com>
Reviewed-by: Shuo Liu <shuo.a.liu@intel.com>
Reviewed-by: David B. Kinder <david.b.kinder@intel.com>
Default behavior is for figure captions below the figure, but table
captions above the table. Tweak the CSS for tables to put the caption
below instead.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
API changes to acrn-kernel/include/linux/vhm/acrn_vhm_mm.h in
https://github.com/projectacrn/acrn-kernel/pull/48 renamed functions
that were referenced in the GTG-g_api.rst document, causing the
documentation build to fail.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Two packages are needed in compiling environment with replacing commands
fdisk and debugfs.
On clear linux, they belong to os-core-dev.
Signed-off-by: Liu, Xinwu <xinwu.liu@intel.com>
Acked-by: Chen Gang <gang.c.chen@intel.com>
Acked-by: Yang Ailin <ailin.yang@intel.com>
Transcode, review, and publish GVT-G porting guide documentation. Merged
glossary entries, added anchor links in GVT-g_api for referencing from
this document.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update CSS customization to improve read-the-docs theme for our use.
Improved search results (removing most reST markup), improve display of
doc version choices.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
API doc generation includes kernel components provided by ACRN that live
in the acrn-kernel repo (not the acrn-hypervisor repo). We need to
include fetching the latest acrn-kernel sources when we do doc
generation, and update the documentation to mention we now need the
acrn-kernel repo as a sibling folder for the acrn-hypervisor repo
contents.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
During setting up ACRN hypervisor, SOS and UOC on the
intel® NUC (NUC6CAYH) board, there are few mistakes
about updating acrn.conf and efibootmgr options, this
will lead to fail to set up ACRN hypervisor, SOS and UOS
on the NUC.
About updating acrn.conf, add "hugepagesz=1G hugepages=2"
About efibootmgr options, string parameter of option "-L"
needs to add double quotation marks; "uart=disabled" in
the option "-u" since there is no serial port on NUC.
Signed-off-by: Xiangyang Wu <xiangyang.wu@intel.com>
Changes to hypercall.h altered the error pattern match used to decide if
doxygen errors are "expected". Update the pattern match.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This is API part of API-GVT-g high level design doc.
Signed-off-by: Xinyun Liu <xinyun.liu@intel.com>
Reviewed-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Reviewed-by: David B. Kinder <david.b.kinder@intel.com>
With the addition of more HLD documents, the developer-guides index was
getting too busy, so push the HLD documents down a level.
Also, the supported hardware document is buried in the getting started
section and hard to find, so promote it.
Trusty isn't really supported (yet) so drop it from the TOC for now.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Console screen shots are hard to maintain, so use the
.. code-block:: console directive to show terminal console-like display
(black background with white text)
Change existing .. code-block:: console uses to .. code-block: none
Replace screen-shot images in apl-nuc getting started guide with
text-based console display.
Update apl-nuc GSG content with v0.1 changes
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Normal publication is to the /latest/ folder. With the tagged 0.1
release, we now have an alternative frozen version of the docs.
Also, tweaked the code for collecting version information from the
VERSION file to create document version number, and Makefile needed to
create the publish directory for a new tagged version.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Include developer comments, add commit change log,
update conf.py to include url shortcuts for references to GitHub issues
and commits.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Transcribe and publish the reviewed memory managment HLD into the ACRN
doc set as a developer guide
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
A recent PR changed where the release version is maintained (was in the
hypervisor/Makefile, now in a VERSION file) and format (was a RC_VERSION
variable, now a EXTRA_VERSION variable). The doc build process uses the
version information when generating documents.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Layout of note at the end of the doc had a CSS formatting problem solved
by adding a leading sentence before the bullet list.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Add a tutorial explaining how to use Ubuntu as the Service OS
running on ACRN and providing all the device sharing services
(devicemodel) and tools to manage virtual machines.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Signed-off-by: Ailin Yang <ailin.yang@intel.com>
Update text-formatted release notes as a reST document, but still needs
work to explain the features and is mising GitHub issue links for the
known issues list.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The 'launch_uos.sh' script was updated recently and new lines
added to it. Adjust the 'emphasize-lines' directive accordingly.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Adjusted the picture sizes a bit smaller, fixed some spelling errors,
and moved the boot-flow.dot image used by trusty into the common images
folder (and renamed the image to trusty-boot-flow.dot)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
A couple of diagram were written using text characters. This
commit changes that to use pictures instead.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Move the existing Trusty document to the doc/ folder (where
it belongs) and convert the text to ReST.
The Documentation/ folder under hypervisor/ is removed as all
documents should be put under doc/.
All technical information has been preserved or was already
available in other documents.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Some ACRN kernel components are using the API documentation methods of
the Linux kernel. While they use Sphinx for generating their
documentation, they don't use doxygen to collect the API information as
we do for the rest of the project. Instead, they use their own tools
called "kerneldoc". This PR incorporates those tools into our
documentation build process.
There is a prescribed directory structure for this to work: that the
acrn-hypervisor and acrn-kernel repos are cloned to sibling folders,
e.g.:
projectacrn
acrn-hypervisor
acrn-kernel
so that documentation references from acrn_hypervisor/doc can access the
source code in ../../acrn-kernel to do the kerneldoc processing. A full
display of the kerneldoc API material for a source file in the
acrn-kernel tree can be done using a sphinx extension directive:
.. kernel-doc:: /tools/virtio/linux/scatterlist.h
where the assumed root of these file references is ../../acrn-kernel.
The format for kerneldoc comments is documented in
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html and
references to kerneldoc API material in .rst files is documented in
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#including-kernel-doc-comments
Without options, the kernel-doc directive includes all documentation
comments from the source file. With options, you can display subsets of
these comments.
The intention is to limit use of kerneldoc comments to the acrn-kernel
repo and not use them elsewhere within the ACRN project (where doxygen
comments are expected.)
While I'd prefer NOT to include the kerneldoc perl script here (it is
already in the acrn-kernel/sphinx folder), I don't want to create a
dependency on the acrn-kernel folder existing for documentation
generation, but this might be unavoidable once we have part of the API
material coming from there. We can update this in a later PR.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Rather than a "tutorial", it was suggested to move the graphviz
information to the devleoper-guides, along with the documentation
guidelines. Makes sense.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Clear Linux is a stateless system, also systemd.
https://clearlinux.org/features/stateless
This tutorial advice to modify a file in /usr/lib which is used by vendors.
Instead of that, this commit advice to use the local administration
network directory at /etc/systemd/network.
See more reference using:
man systemd.network
Fixes: 25eae47836 ("Documentation: add tutorial to set up a static IP address")
Signed-off-by: Miguel Bernal Marin <miguel.bernal.marin@linux.intel.com>
Add a tutorial on how to change the default configuration that
uses DHCP and assign a static IP address to the system.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Fix a minor rendering issue in the Getting Started Guide where a
code-block is not appearing as such.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
We've been expanding documentation, and now need to organize things a bit
cleaner and separate content into new major folders: Introduction, Getting
Started, User Guides, Developer Guides, Tutorials, and Release notes..
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Add some basic development tools needed to build the ACRN project.
These were not specifically called out (although most likely
already installed in any development system).
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Modify the Zephyr project script for creating documentation from Kconfig
files to generate the hypervisor option configuration docs. While Zephyr
uses a modified version of kconfiglib, we can use the standard
kconfiglib from Pypi (added to the requirements.txt file).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The latest versions of Sphinx and Breathe work well together so we're
updating the requirements.txt installation information (and
documentation) to use the latest versions of these tools.
Fixes: #395
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This patch adds two sections which describe how configurations can be modified
and how minimized configurations can be generated.
Also switch prerequisite python version from 2 to 3 since menuconfig.py is
python3 only.
v1 -> v2:
* Add the link to EPEL.
* Rename minimalconfig to savedefconfig in the guide.
* Split the step using a defconfig from those generating a defconfig.
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Acked-by: Anthony Xu <anthony.xu@intel.com>
Acked-by: Geoffroy VanCutsem <geoffroy.vancutsem@intel.com>
On some system, the current doxygen configuration file will
generate a warning if CLANG_ASSISTED_PARSING was not enbabled
at compile time.
This is not used but the simple fact it's listed in the
configuration file (turned off) still generates the warning. So
comment out the option altogether to get a clean log output.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This patch adds a new target to build the documentation
from the top-level directory. Here is how to use it (from
the top-level source directory):
$ make doc
Or
$ make O=build-test doc
To clean all documentation build artefacts, simply call
$ make clean
Or
$ make O=build-test clean
Calling 'make' with no arguments will *not* build the
documentation by default.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This patch renames $(O) used in the documentation Makefile
(doc/Makefile) into $(OPTS) in order to avoid a namespace
conflict with $(O) used in the top-level Makefile.
This is in preparation to a new target called 'doc' that will
allow to build the documentation directly from the top-level
Makefile. This is required in order *not* to break setting a
specific build directory, e.g. 'make O=build-test'.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This update is to reflect the changes for acrnbridge to start
with systemd-networkd instead of running a script.
Signed-off-by: Tan Shen Joon <shen.joon.tan@intel.com>
Trying out the graphviz capability rather than using static images that
we can't easily modify. Also updated the site logo that was too wide.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
v4 -> v5:
* No changes.
v3 -> v4:
* No changes.
v2 -> v3:
* Update the guide before introducing the actual code.
v1 -> v2:
* Add guides on installing pip and kconfiglib.
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Reviewed-by: Kevin Tian <kevin.tian@intel.com>
Reviewed-by: Zhao Yakui <yakui.zhao@intel.com>
graphviz lets us create graphic images via a text language rather than
creating drawings in other tools (eliminating the need to keep the
sources for the images available, such as a powerpoint file).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Changes to the nested unnamed unions in type definitions require a tweak
to the pattern matching used to detect known issues reported by the API
doc generation.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This continues the editing from PR #276 with formatting and clarity
edits to have these tool documents blend in with the rest of the ACRN
documentation. It also builds on PR #307 that set up the doc build
infrastructure to allow leaving these tool docs within the tools/
folder.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the Getting Started Guide to remove some instructions that
are now obsolete and add details of the cmdline parameters that
can be passed to the ACRN hypervisor (EFI), namely:
* bootloader=
* uart=
The wording of the GSG has been made less specific to the NUC
platform so we can refer to it for new platform being supported
without causing confusion to the reader
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Fix formatting and adhere to the recommendations published by
the documentation owner when writing reST documents.
Simplify the instructions by referencing the main Getting Started
Guide. This is now possible with the latest code since what
required us to modify the source code and build the components
are now parameters we can set when installing ACRN. This
simplifies the instructions *a lot*.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This adds basic information about the new ACRN tools that have
been integrated in the the acrn-hypervisor repo (under tools/).
It also adds the build dependencies for those tools in the
different development environment that we reference.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
The tools documentation is maintained within the tools folder and
outside of the doc folder. We need to temporarily pull that content
within the doc folder for generating the documentation set. (We're using
a script developed for the Zephyr project for just this purpose.)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The sambles scripts where moved to another directory but did not update
all the references in the documentation.
Fixes: 977d48d550 ("hypervisor: install acrn.efi to /usr/lib")
Fixes: 9563e248b7 ("samples: move samples to specifi platform diretory")
Signed-off-by: Miguel Bernal Marin <miguel.bernal.marin@linux.intel.com>
DM memory allocation mechanism is better placed in the Getting Started
material, so move it there from the primer.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
acrn.efi is a binary and need to be installed to /usr/lib instead of
/usr/share.
Suggested-by: Arzhan Kinzhalin <arzhan.i.kinzhalin@intel.com>
Signed-off-by: Miguel Bernal Marin <miguel.bernal.marin@linux.intel.com>
Move the platform apl-mrb samples to devicemodel samples directory.
Add the install target to the missing samples files and re-organize the
samples directory structure to have nuc and apl-mrb samples.
Suggested-by: Arzhan Kinzhalin <arzhan.i.kinzhalin@intel.com>
Signed-off-by: Miguel Bernal Marin <miguel.bernal.marin@linux.intel.com>
Add documentation contributing information with project specific
recommentations along with some common reST and Sphinx constructs.
Reorganize contributing section to fit this new doc in.
Also
* Cleanup stray file (CODEOWNERS) from when docs were in their own repo.
* Remove licensing footer on generated pages (not really needed).
* Pull replacement strings into substitutions.txt for easier management.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Remove UEFI boot material that was causing doc build to fail (seems to
be a duplicate of material in the Getting Started Guide anyway)
Fix reST formatting for the DM memory allocation section.
Update folder layout description
Fixes: #202
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the "Contributing Guidelines" document to point at the
top-level LICENSE file that was created after the merger of
the three acrn-{hypervisor,devicemodel,documentation} repositories
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Post-merge, the doc building instructions need an update to reflect the
new diretory structure.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Documentation updates were needed to account for changes caused by the
recent merging of the three acrn-hypervisor, acrn-devicemodel, and
acrn-documentation repos.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
We've enabled GitHub issues for submitting and tracking bug and
enhancement requests for the project. Add some documentation about how
to use issues and what to expect.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Fix some formatting problems with a recent GSG update. Tweak the
custom CSS to adjust code block (and code literal) colors. Update
Makefile to document doc build options for pulling source from the other
repos and for publishing targets.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The boot process has changed a bit and the ACRN hypervisor is now
directly loaded by the platform EFI firmware. This commit reflects
those changes and also reference a newer version of Clearlinux that
includes the ACRN hypervisor that has these changes in.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Tech note articles about technology and process tips now have a place in
the ACRN documentaion.
Move the doc process documention into this new area, and add a
placeholder for tech tips for now.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Some assumptioins about the doc build process were removed to make it
easier for contributors to build local version of the docs. Assumption
now is that acrn-hypervisor and acrn-devicemodel content is up to date
rather than pulling from upstream on every build.
make pullsource will do an upstream pull manually
make html generates local docs
Also fixed broken link in the README.md file (moved the tech doc root)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Include more doxygen info, flag undocumented material, update
.known_issues matching for known doxygen/sphinx issues
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
add navigation to (manually) maintained list (in conf.py) of versioned
docs, and update generating and publishing processes to be
version-aware.
Adds a file to redirect root references to /latest folder now (since we
can't update the server redirects). Might break some links to pages
within the site from external sites.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the build dependency for Fedora. 'gnu-efi' was listed as
a dependency but it's actually 'gnu-efi-devel' that we need else
the header file ('efi.h') is not installed.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Add a new document describing how doc building and publishing
works and how to setup a doc working directory and build tools to make
it so.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Add the 'gnu-efi' dependency required to build the ACRN hypervisor
with "PLATFORM=uefi" on Fedora. 'gnu-efi-devel' is required on CentOS.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Make the Getting Started Guide instructions more specific and
comprehensive for Clear Linux version 21260 (version of reference)
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Handle version retrieval better when comments are present.
Add warning if Sphinx theme (read_the_docs) is missing.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Add instructions on how to build the hypervisor and device model
on other operating systems such as Ubuntu/Debian, Fedora/doc/Redhat
and CentOS.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Per Project ACRN governance, documentation is under a Creative Commons
Attribution 4.0 International License (CC BY 4.0). This patch updates
this information, and adds a tagline to documentation mentioning this
license.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
make the doc build process quiet and add filtering of known (Sphinx)
issues. Scripting comes from the open source Zephyr project.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
changed 3 to support latest image release
1, deleted one bundle installation -os-clr-on-clr-dev
2, changed the default configuration file path to /usr/share/acrn/demo
3, after installed service os bundle, all the configuration files and scripts were installed, no need to download manually any more
Simplify the publishing process to projectacrn.github.io by making
commits directly to the projectacrn/projectacrn.github.io repo (rather
than to a personal repo, doing a PR, and processing the PR). This
eliminates manual processing in an otherwise automated publishing
process: PR reviews aren't needed for this step.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Initial version of Getting Started Guide doc (and images).
Need to replace images with better ones.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Developer Primer and images, and a tweak to figure formatting
also renamed from Hypervisor Primer to just Developer Primer since the
doc talks about Device Model too.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Change display of RC_VERSION on documents to be
vMAJOR_VERSION.MINOR_VERSION-rcRC_VERSION
if RC_VERSION is non-zero, otherwise only
vMAJOR_VERSION.MINOR_VERSION
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Doc version tracking with acrn-hypervisor version now to be
MAJOR_VERSION . MINOR_VERSION . RC_VERSION
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Add the "Introduction of Project Acorn" doc.
Also adds improvements to the doc generation processes, content styles,
removed doxygen-generated API material.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Peter Fang