mirror of
https://github.com/xen-project/xen.git
synced 2026-10-28 02:01:24 +01:00
docs: add feature document for Xen hypervisor sysfs-like support
On the 2019 Xen developer summit there was agreement that the Xen hypervisor should gain support for a hierarchical name-value store similar to the Linux kernel's sysfs. In the beginning there should only be basic support: entries can be added from the hypervisor itself only, there is a simple hypercall interface to read the data. Add a feature document for setting the base of a discussion regarding the desired functionality and the entries to add. Signed-off-by: Juergen Gross <jgross@suse.com> Acked-by: Julien Grall <jgrall@amazon.com>
This commit is contained in:
Juergen Gross authored and Jan Beulich committed
1 parent
c48a9956e3
commit
0e9dcd0159
2 files changed
+199
No files matched your search
@@ -0,0 +1,92 @@
|
||||
% Hypervisor FS
|
||||
% Revision 1
|
||||
|
||||
\clearpage
|
||||
|
||||
# Basics
|
||||
---------------- ---------------------
|
||||
Status: **Supported**
|
||||
|
||||
Architectures: all
|
||||
|
||||
Components: Hypervisor, toolstack
|
||||
---------------- ---------------------
|
||||
|
||||
# Overview
|
||||
|
||||
The Hypervisor FS is a hierarchical name-value store for reporting
|
||||
information to guests, especially dom0. It is similar to the Linux
|
||||
kernel's sysfs. Entries and directories are created by the hypervisor,
|
||||
while the toolstack is able to use a hypercall to query the entry
|
||||
values or (if allowed by the hypervisor) to modify them.
|
||||
|
||||
# User details
|
||||
|
||||
With:
|
||||
|
||||
xenhypfs ls <path>
|
||||
|
||||
the user can list the entries of a specific path of the FS. Using:
|
||||
|
||||
xenhypfs cat <path>
|
||||
|
||||
the content of an entry can be retrieved. Using:
|
||||
|
||||
xenhypfs write <path> <string>
|
||||
|
||||
a writable entry can be modified. With:
|
||||
|
||||
xenhypfs tree
|
||||
|
||||
the complete Hypervisor FS entry tree can be printed.
|
||||
|
||||
The FS paths are documented in `docs/misc/hypfs-paths.pandoc`.
|
||||
|
||||
# Technical details
|
||||
|
||||
Access to the hypervisor filesystem is done via the stable new hypercall
|
||||
__HYPERVISOR_filesystem_op. This hypercall supports a sub-command
|
||||
XEN_HYPFS_OP_get_version which will return the highest version of the
|
||||
interface supported by the hypervisor. Additions to the interface need
|
||||
to bump the interface version. The hypervisor is required to support the
|
||||
previous interface versions, too (this implies that additions will always
|
||||
require new sub-commands in order to allow the hypervisor to decide which
|
||||
version of the interface to use).
|
||||
|
||||
* hypercall interface specification
|
||||
* `xen/include/public/hypfs.h`
|
||||
* hypervisor internal files
|
||||
* `xen/include/xen/hypfs.h`
|
||||
* `xen/common/hypfs.c`
|
||||
* `libxenhypfs`
|
||||
* `tools/libs/libxenhypfs/*`
|
||||
* `xenhypfs`
|
||||
* `tools/misc/xenhypfs.c`
|
||||
* path documentation
|
||||
* `docs/misc/hypfs-paths.pandoc`
|
||||
|
||||
# Testing
|
||||
|
||||
Any new parameters or hardware mitigations should be verified to show up
|
||||
correctly in the filesystem.
|
||||
|
||||
# Areas for improvement
|
||||
|
||||
* More detailed access rights
|
||||
* Entries per domain and/or per cpupool
|
||||
|
||||
# Known issues
|
||||
|
||||
* None
|
||||
|
||||
# References
|
||||
|
||||
* None
|
||||
|
||||
# History
|
||||
|
||||
------------------------------------------------------------------------
|
||||
Date Revision Version Notes
|
||||
---------- -------- -------- -------------------------------------------
|
||||
2020-01-23 1 Xen 4.14 Document written
|
||||
---------- -------- -------- -------------------------------------------
|
||||
@@ -0,0 +1,107 @@
|
||||
# Xenhypfs Paths
|
||||
|
||||
This document attempts to define all the paths which are available
|
||||
in the Xen hypervisor file system (hypfs).
|
||||
|
||||
The hypervisor file system can be accessed via the xenhypfs tool.
|
||||
|
||||
## Notation
|
||||
|
||||
The hypervisor file system is similar to the Linux kernel's sysfs.
|
||||
In this document directories are always specified with a trailing "/".
|
||||
|
||||
The following notation conventions apply:
|
||||
|
||||
DIRECTORY/
|
||||
|
||||
PATH = VALUES [TAGS]
|
||||
|
||||
The first syntax defines a directory. It normally contains related
|
||||
entries and the general scope of the directory is described.
|
||||
|
||||
The second syntax defines a file entry containing values which are
|
||||
either set by the hypervisor or, if the file is writable, can be set
|
||||
by the user.
|
||||
|
||||
PATH can contain simple regex constructs following the Perl compatible
|
||||
regexp syntax described in pcre(3) or perlre(1).
|
||||
|
||||
A hypervisor file system entry name can be any 0-delimited byte string
|
||||
not containing any '/' character. The names "." and ".." are reserved
|
||||
for file system internal use.
|
||||
|
||||
VALUES are strings and can take the following forms (note that this represents
|
||||
only the syntax used in this document):
|
||||
|
||||
* STRING -- an arbitrary 0-delimited byte string.
|
||||
* INTEGER -- An integer, in decimal representation unless otherwise
|
||||
noted.
|
||||
* "a literal string" -- literal strings are contained within quotes.
|
||||
* (VALUE | VALUE | ... ) -- a set of alternatives. Alternatives are
|
||||
separated by a "|" and all the alternatives are enclosed in "(" and
|
||||
")".
|
||||
* {VALUE, VALUE, ... } -- a list of possible values separated by "," and
|
||||
enclosed in "{" and "}".
|
||||
|
||||
Additional TAGS may follow as a comma separated set of the following
|
||||
tags enclosed in square brackets.
|
||||
|
||||
* w -- Path is writable by the user. This capability is usually
|
||||
limited to the control domain (e.g. dom0).
|
||||
* ARM | ARM32 | ARM64 | X86: the path is available for the respective
|
||||
architecture only.
|
||||
* PV -- Path is valid for PV capable hypervisors only.
|
||||
* HVM -- Path is valid for HVM capable hypervisors only.
|
||||
* CONFIG_* -- Path is valid only in case the hypervisor was built with
|
||||
the respective config option.
|
||||
|
||||
So an entry could look like this:
|
||||
|
||||
/cpu-bugs/active-pv/xpti = ("No"|{"dom0", "domU", "PCID-on"}) [w,X86,PV]
|
||||
|
||||
Possible values would be "No" or a list of "dom0", "domU", and "PCID-on" with
|
||||
the list elements separated by spaces, e.g. "dom0 PCID-on".
|
||||
The entry would be writable and it would exist on X86 only and only if the
|
||||
hypervisor is configured to support PV guests.
|
||||
|
||||
## Example
|
||||
|
||||
A populated Xen hypervisor file system might look like the following example:
|
||||
|
||||
/
|
||||
buildinfo/ directory containing build-time data
|
||||
config contents of .config file used to build Xen
|
||||
cpu-bugs/ x86: directory of cpu bug information
|
||||
l1tf "Vulnerable" or "Not vulnerable"
|
||||
mds "Vulnerable" or "Not vulnerable"
|
||||
meltdown "Vulnerable" or "Not vulnerable"
|
||||
spec-store-bypass "Vulnerable" or "Not vulnerable"
|
||||
spectre-v1 "Vulnerable" or "Not vulnerable"
|
||||
spectre-v2 "Vulnerable" or "Not vulnerable"
|
||||
mitigations/ directory of mitigation settings
|
||||
bti-thunk "N/A", "RETPOLINE", "LFENCE" or "JMP"
|
||||
spec-ctrl "No", "IBRS+" or "IBRS-"
|
||||
ibpb "No" or "Yes"
|
||||
l1d-flush "No" or "Yes"
|
||||
md-clear "No" or "VERW"
|
||||
l1tf-barrier "No" or "Yes"
|
||||
active-hvm/ directory for mitigations active in hvm doamins
|
||||
msr-spec-ctrl "No" or "Yes"
|
||||
rsb "No" or "Yes"
|
||||
eager-fpu "No" or "Yes"
|
||||
md-clear "No" or "Yes"
|
||||
active-pv/ directory for mitigations active in pv doamins
|
||||
msr-spec-ctrl "No" or "Yes"
|
||||
rsb "No" or "Yes"
|
||||
eager-fpu "No" or "Yes"
|
||||
md-clear "No" or "Yes"
|
||||
xpti "No" or list of "dom0", "domU", "PCID-on"
|
||||
l1tf-shadow "No" or list of "dom0", "domU"
|
||||
params/ directory with hypervisor parameter values
|
||||
(boot/runtime parameters)
|
||||
|
||||
## General Paths
|
||||
|
||||
#### /
|
||||
|
||||
The root of the hypervisor file system.
|
||||