* Update and simplify our What is ACRN document.
* Removed SDC disussion and out-of-date best known configuration
descriptions and scenario block diagrams
* Removed I/O Mediator discussion from "What is ACRN" and move
referenced label to content in the HLD overview (that was duplicated in
"What is ACRN")
* Updated images for scenarios and removed obsolete images
* Add references to new overview docs and GSG
* Add general description of VMs in example scenarios
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Summarize the ACRN contributing guidelines (fully documented in a
separate document) and add to the top level of our project repo (as
expected by GitHub and our Technical Steering Committee)
Also, tweak the mailing list reference to recommend acrn-users instead
of acrn-dev
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Removed the Porting and Adaptation to Different Platforms section in hv-ioc-virt.rst, because it was blank.
Signed-off-by: Amy Reyes <amy.reyes@intel.com>
Fix broken links in the Virtio-Net HLD that point at the network
scripts in the source code repository.
Tracked-On: #6542
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
Default e820 mem map in hld-devicemodel.rst is
mismatched with sw_load_common.c,update the doc
to align with code.
Signed-off-by: Liu, Hang1 <hang1.liu@intel.com>
We no longer need to generate API documentation for the upstreamed
gvt-g kernel additions so we can remove the doc generation dependency on
the acrn-kernel repo (and all use of the kerneldoc extension). We also
remove GVT-g API documentation and porting guide that are obsolete with
ACRN v2.6 and referenced this API documentation.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Replace rdstc() and get_tsc_khz() with their architectural agnostic
counterparts cpu_ticks() and cpu_tickrate().
Tracked-On: #5920
Signed-off-by: Yi Liang <yi.liang@intel.com>
get_ept_entry() actually returns the EPTP of a VM. So rename it to
get_eptp() for readability.
Tracked-On: #5923
Signed-off-by: Shuo A Liu <shuo.a.liu@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
The current permission-checking and dispatching mechanism of hypercalls is
not unified because:
1. Some hypercalls require the exact vCPU initiating the call, while the
others only need to know the VM.
2. Different hypercalls have different permission requirements: the
trusty-related ones are enabled by a guest flag, while the others
require the initiating VM to be the Service OS.
Without a unified logic it could be hard to scale when more kinds of
hypercalls are added later.
The objectives of this patch are as follows.
1. All hypercalls have the same prototype and are dispatched by a unified
logic.
2. Permissions are checked by a unified logic without consulting the
hypercall ID.
To achieve the first objective, this patch modifies the type of the first
parameter of hcall_* functions (which are the callbacks implementing the
hypercalls) from `struct acrn_vm *` to `struct acrn_vcpu *`. The
doxygen-style documentations are updated accordingly.
To achieve the second objective, this patch adds to `struct hc_dispatch` a
`permission_flags` field which specifies the guest flags that must ALL be
set for a VM to be able to invoke the hypercall. The default value (which
is 0UL) indicates that this hypercall is for SOS only. Currently only the
`permission_flag` of trusty-related hypercalls have the non-zero value
GUEST_FLAG_SECURE_WORLD_ENABLED.
With `permission_flag`, the permission checking logic of hypercalls is
unified as follows.
1. General checks
i. If the VM is neither SOS nor having any guest flag that allows
certain hypercalls, it gets #UD upon executing the `vmcall`
instruction.
ii. If the VM is allowed to execute the `vmcall` instruction, but
attempts to execute it in ring 1, 2 or 3, the VM gets #GP(0).
2. Hypercall-specific checks
i. If the hypercall is for SOS (i.e. `permission_flag` is 0), the
initiating VM must be SOS and the specified target VM cannot be a
pre-launched VM. Otherwise the hypercall returns -EINVAL without
further actions.
ii. If the hypercall requires certain guest flags, the initiating VM
must have all the required flags. Otherwise the hypercall returns
-EINVAL without further actions.
iii. A hypercall with an unknown hypercall ID makes the hypercall
returns -EINVAL without further actions.
The logic above is different from the current implementation in the
following aspects.
1. A pre-launched VM now gets #UD (rather than #GP(0)) when it attempts
to execute `vmcall` in ring 1, 2 or 3.
2. A pre-launched VM now gets #UD (rather than the return value -EPERM)
when it attempts to execute a trusty hypercall in ring 0.
3. The SOS now gets the return value -EINVAL (rather than -EPERM) when it
attempts to invoke a trusty hypercall.
4. A post-launched VM with trusty support now gets the return value
-EINVAL (rather than #UD) when it attempts to invoke a non-trusty
hypercall or an invalid hypercall.
v1 -> v2:
- Update documentation that describe hypercall behavior.
- Fix Doxygen warnings
Tracked-On: #5924
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
Update missing captions on figures to remove remaining broken references
during latexpdf building. Also, require doing a "make html" before
doing a "make latexpdf" to build all the artifacts needed for running
the latexpdf build. (We might change that later if needed.)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This patch modifies the instructions that lead users to modify predefined
scenario XMLs under ``misc/config_tools/data`` which is not a preferred
way. It is recommended to make and edit a local copy, instead.
Also fixes a few references to ``misc/vm_configs`` which has been moved.
v2:
* fix typos in paths
* explain on the candidate values of ``port_base`` and ``irq`` fields
Tracked-On: #5644
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Starting from v2.4, ACRN configuration uses solely XML files to store
configuration data and customized scripts to manipulate
configurations. This patch updates the HLD of compile-time configuration to
reflect this properly.
As the refinement to the configuration toolset itself is still ongoing,
this patch only adds brief introduction to the key generated files involved
in ACRN configuration. More details will be added after the refinement
completes.
Tracked-On: #5644
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Signed-off-by: Benjamin Fitch <benjamin.fitch@intel.com>
Update the list of arguments and parameters that the ACRN
Device Model ('acrn-dm') can take.
Tracked-On: #5781
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
After grand update of all titles to use title-case, we found some more
that needed a manual tweak.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
After grand update of all titles to use title-case, we found a few that
needed a manual tweak.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
While we hoped to make the headings consistent over time while doing
other edits, we should instead just make the squirrels happy and do them
all at once or they'll likely never be made consistent.
A python script was used to find the headings, and then a call to
https://pypi.org/project/titlecase to transform the title. A visual
inspection was used to tweak a few unexpected resulting titles.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
With the new ACRN configuration architecture, we no longer use Kconfig
files. Remove the Kconfig option documentation scripting (genrest.py)
Python dependencies, and Makefile commands, and change references in the
documentation from the Kconfig option (such as
:option:`CONFIG_MEM_LOGLEVEL`) to the new schema definition-based option
documentation (:option:`hv.DEBUG_OPTION.MEM_LOGLEVEL`).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Links to files in the GitHub repo's master branch should be to the files
within the branch being generated. For example, in the v2.1
documentation, links should be to the v2.1 branch contents. (Previously
links were being made to the master branch in all our archived content.)
This creates a problem when we want to remove an obsolete file in the
master branch but can't because older documentaiton incorrectly depends
on it.
This new extension defines a :acrn_file: and :acrn_raw: role that will
create links to the given file within the current commit branch.
This PR also replaces docs with hard-coded links to files in the master
branch with uses of these new roles to create links to files.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Did a partial run of ACRN documents through Acrolinx to catch additional
spelling and grammar fixes missed during regular reviews.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Ivshmem hv-land solution emulates the ivshmem device in hypervisor
and the shared memory is reserved in the hypervisor's memory space.
And it can provide inter-vm communication for both pre-launched and
post-launched VMs.
This patch introduces the ivshmem hv-land solution including what
ivshmem hv-land is and how to use it.
Signed-off-by: Yuan Liu <yuan1.liu@intel.com>
A previous update changed "slave" to "secondary", but the code comments
were changed to use "client", so update the documentation to match.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Replace white/black master/slave terms with alternatives. We're not
changing "master" when used in the context of GitHub branches. GitHub
advises they have a plan to help this transition. In the text body we
rever to the "master" branch as the "main" branch, but leave any urls or
code-block commands still using "master".
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Also clear Linux is no longer supported either as SOS or post-launched VM kernel.
- When it mentions clear Linux, mostly replaced by Ubuntu.
- remove all contents re/lated to "UEFI boot".
- remove the term de-privilege mode, and direct mode as well.
Tracked-On: #5197
Signed-off-by: Zide Chen <zide.chen@intel.com>
- add a rule for pointer arithmetic operation
- add a rule about ABI conformance
- update GCC reference
Signed-off-by: Shiqing Gao <shiqing.gao@intel.com>
As noticed in PR #5134 scenario configurations were moved out of the
hypervisor folder over to the misc folder (within the acrn-hypervisor
repo). Fix references and make them all consistent (referencing
misc/vm_configs)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Doc was merged but not included in the TOC (CI indicated a pass on that
PR even though doc build failed). This fixes that undetected error.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Besides PCI passthru, ACRN can support passthru of a set of page-aligned
MMIO resources. One example is to passthru a TPM device which includes
a set of page aligned MMIO resources.
Signed-off-by: Li Fei1 <fei1.li@intel.com>
Given the recent changes in the way ACRN configures RDT features,
this patch updates the documentation as well to provide clear
guidelines to the user.
Tracked-On: #5063
Signed-off-by: Vijay Dhanraj <vijay.dhanraj@intel.com>
ACRN 2.0 introduced Inter-VM communication feature by enabling the ivshmem v1.0 protocol/channel to communication
between VMs. To support the community's application Security Development Lifecycle (SDL), we provide a security hardening
guideline with some pointers to consider when using this channel by userspace application in case of additional security
requirments for Confidentiality, Integrity, or Authenticity.
Signed-off-by: Mostafa Naeem <mostafa.elsaid@intel.com>
While changes to documentation can be submitted directly as PRs, changes
to code must be first submitted for approval to the developer mailing
list. Update the contribution guidelines to talk about this.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Attempt to replace all the variations of "pass-thru", "pass thru", "pass
through", and "pass-through" to be "passthrough" (except for doc labels
and in code or API uses)
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the 'ivshmem' document to clarify the existence of two similar
mechanisms to expose this device to User VMs. One is implemented in the ACRN
Device Model and another (future) is implemented in the hypervisor.
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
There are some subtle syntax errors in some documents that, while they
render OK (most of the time), are being caught by rstcheck (a
restructuredText linter). This PR fixes most of the issues encountered.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Using ``.. rst-class:: rst-columns`` wasn't processed correctly because
of an error in the acrn-custom.css file. Fix that, update the
documentation guidelines, and make use of the multi-column display in
documents where the toctree created a long list. Now it will
appear in columns.
Also tweaked the toctree listing to use bold for the first-level items
(making a multi-column display look better, particularly when it has
subsections).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Convert UTF-8 characters (typically pasted from Word for smart quotes
and such) into equivalent ASCII characters.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Update the doc writing guidelines to include some new capabilities
(multi-column display, numbered instruction steps) and add more
information about writing tables.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Stray non-ASCII characters can creep in when pasting from Word or Google
Docs, particularly for "smart" single and double quotes and non-breaking
spaces. Change these to their ASCII equivalents. Also fixed some very
long lines of text to wrap at 80-ish characters.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This patch updates CAT documentation as well as adds
documentation support for newly added MBA feature.
Signed-off-by: Vijay Dhanraj <vijay.dhanraj@intel.com>
Introduce Split Device Model feature for ACRN. Now we only implement pass through
PCI(e) device of it.
Tracked-On: #4371
Signed-off-by: Li Fei1 <fei1.li@intel.com>
Fix links in documentation that have moved (e.g.,
clearlinux.org/documentation moved to docs.01.org/clearlinux/latest).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
One argument is missing for the function ptirq_alloc_entry.
This patch fixes the doc generation error.
Tracked-On: #3882
Signed-off-by: Binbin Wu <binbin.wu@intel.com>
Fixed misspellings and rst formatting issues.
Added ptdev.h to the list of include file for doxygen
Tracked-On: #3882
Signed-off-by: Binbin Wu <binbin.wu@intel.com>
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
Now we split passthrough PCI device from DM to HV, we could remove all the passthrough
PCI device unused code.
Tracked-On: #4371
Signed-off-by: Li Fei1 <fei1.li@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
ptirq_msix_remap doesn't do the real remap, that's the vmsi_remap and vmsix_remap_entry
does. ptirq_msix_remap only did the preparation.
Tracked-On: #3475
Signed-off-by: Li Fei1 <fei1.li@intel.com>
