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>
Peter Fang