From: Juergen Gross <jgross@suse.com>
To: xen-devel@lists.xenproject.org
Cc: Juergen Gross <jgross@suse.com>,
Stefano Stabellini <sstabellini@kernel.org>,
Julien Grall <julien@xen.org>, Wei Liu <wl@xen.org>,
Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>,
Andrew Cooper <andrew.cooper3@citrix.com>,
Ian Jackson <ian.jackson@eu.citrix.com>,
George Dunlap <george.dunlap@citrix.com>,
Jan Beulich <jbeulich@suse.com>
Subject: [Xen-devel] [PATCH v6 03/12] docs: add feature document for Xen hypervisor sysfs-like support
Date: Wed, 26 Feb 2020 13:46:56 +0100 [thread overview]
Message-ID: <20200226124705.29212-4-jgross@suse.com> (raw)
In-Reply-To: <20200226124705.29212-1-jgross@suse.com>
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>
---
V1:
- remove the "--" prefixes of the sub-commands of the user tool
(Jan Beulich)
- rename xenfs to xenhypfs (Jan Beulich)
- add "tree" and "write" options to user tool
V2:
- move example tree to the paths description (Ian Jackson)
- specify allowed characters for keys and values (Ian Jackson)
V3:
- correct introduction (writable entries)
V4:
- add list specification
- add entry example (Julien Grall)
- correct date and Xen version (Julien Grall)
- add ARM64 as possible architecture (Julien Grall)
- add version description to the feature doc (Jan Beulich)
---
docs/features/hypervisorfs.pandoc | 92 +++++++++++++++++++++++++++++++++
docs/misc/hypfs-paths.pandoc | 105 ++++++++++++++++++++++++++++++++++++++
2 files changed, 197 insertions(+)
create mode 100644 docs/features/hypervisorfs.pandoc
create mode 100644 docs/misc/hypfs-paths.pandoc
diff --git a/docs/features/hypervisorfs.pandoc b/docs/features/hypervisorfs.pandoc
new file mode 100644
index 0000000000..a0a0ead057
--- /dev/null
+++ b/docs/features/hypervisorfs.pandoc
@@ -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
+---------- -------- -------- -------------------------------------------
diff --git a/docs/misc/hypfs-paths.pandoc b/docs/misc/hypfs-paths.pandoc
new file mode 100644
index 0000000000..b9f50f6998
--- /dev/null
+++ b/docs/misc/hypfs-paths.pandoc
@@ -0,0 +1,105 @@
+# 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:
+
+* 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".
+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.
--
2.16.4
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
next prev parent reply other threads:[~2020-02-26 12:47 UTC|newest]
Thread overview: 50+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-26 12:46 [Xen-devel] [PATCH v6 00/12] Add hypervisor sysfs-like support Juergen Gross
2020-02-26 12:46 ` [Xen-devel] [PATCH v6 01/12] xen: allow only sizeof(bool) variables for boolean_param() Juergen Gross
2020-03-03 16:40 ` Jan Beulich
2020-03-09 11:43 ` Julien Grall
2020-03-09 11:55 ` Jan Beulich
2020-03-09 13:01 ` Jürgen Groß
2020-03-09 13:06 ` Jan Beulich
2020-03-09 14:06 ` Jürgen Groß
2020-02-26 12:46 ` [Xen-devel] [PATCH v6 02/12] xen: add a generic way to include binary files as variables Juergen Gross
2020-02-26 12:46 ` Juergen Gross [this message]
2020-03-09 11:48 ` [Xen-devel] [PATCH v6 03/12] docs: add feature document for Xen hypervisor sysfs-like support Julien Grall
2020-03-25 14:05 ` Jürgen Groß
2020-02-26 12:46 ` [Xen-devel] [PATCH v6 04/12] xen: add basic hypervisor filesystem support Juergen Gross
2020-03-03 16:59 ` Jan Beulich
2020-03-04 12:00 ` Jürgen Groß
2020-03-04 13:03 ` Jan Beulich
2020-03-04 14:39 ` Jürgen Groß
2020-03-04 15:07 ` Jan Beulich
2020-03-04 15:14 ` Jürgen Groß
2020-03-04 15:21 ` Jan Beulich
2020-03-06 6:06 ` Jürgen Groß
2020-03-06 8:19 ` Jan Beulich
2020-02-26 12:46 ` [Xen-devel] [PATCH v6 05/12] libs: add libxenhypfs Juergen Gross
2020-02-26 12:46 ` [Xen-devel] [PATCH v6 06/12] tools: add xenfs tool Juergen Gross
2020-02-26 12:47 ` [Xen-devel] [PATCH v6 07/12] xen: provide version information in hypfs Juergen Gross
2020-02-26 12:47 ` [Xen-devel] [PATCH v6 08/12] xen: add /buildinfo/config entry to hypervisor filesystem Juergen Gross
2020-03-04 10:49 ` Jan Beulich
2020-03-04 12:06 ` Jürgen Groß
2020-03-04 13:04 ` Jan Beulich
2020-02-26 12:47 ` [Xen-devel] [PATCH v6 09/12] xen: add runtime parameter access support to hypfs Juergen Gross
2020-03-04 11:32 ` Jan Beulich
2020-03-04 15:07 ` Jürgen Groß
2020-03-04 15:19 ` Jan Beulich
2020-03-04 16:31 ` Jürgen Groß
2020-03-04 16:56 ` Jan Beulich
2020-03-05 6:01 ` Jürgen Groß
2020-03-05 8:26 ` Jan Beulich
2020-03-06 6:42 ` Jürgen Groß
2020-03-06 8:20 ` Jan Beulich
2020-03-06 8:47 ` Jürgen Groß
2020-03-06 9:04 ` Jan Beulich
2020-03-06 9:20 ` Jürgen Groß
2020-03-06 9:22 ` Jan Beulich
2020-03-06 9:27 ` Jürgen Groß
2020-03-23 10:38 ` Julien Grall
2020-02-26 12:47 ` [Xen-devel] [PATCH v6 10/12] tools/libxl: use libxenhypfs for setting xen runtime parameters Juergen Gross
2020-02-26 12:47 ` [Xen-devel] [PATCH v6 11/12] tools/libxc: remove xc_set_parameters() Juergen Gross
2020-02-26 12:47 ` [Xen-devel] [PATCH v6 12/12] xen: remove XEN_SYSCTL_set_parameter support Juergen Gross
2020-03-04 11:45 ` Jan Beulich
2020-03-04 14:40 ` Jürgen Groß
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200226124705.29212-4-jgross@suse.com \
--to=jgross@suse.com \
--cc=andrew.cooper3@citrix.com \
--cc=george.dunlap@citrix.com \
--cc=ian.jackson@eu.citrix.com \
--cc=jbeulich@suse.com \
--cc=julien@xen.org \
--cc=konrad.wilk@oracle.com \
--cc=sstabellini@kernel.org \
--cc=wl@xen.org \
--cc=xen-devel@lists.xenproject.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).