Re: [Xen-devel] [PATCH v3 3/9] docs: add feature document for Xen hypervisor sysfs-like support

[Jürgen Groß <jgross@xxxxxxxx>]

On 21.01.20 14:14, Julien Grall wrote:
> Hi Juergen.
>
> On 21/01/2020 08:43, Juergen Gross wrote:
> > 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@xxxxxxxx>
> > ---
> > 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)
> > ---
> >   docs/features/hypervisorfs.pandoc | 86 
> > +++++++++++++++++++++++++++++++++++
> >   docs/misc/hypfs-paths.pandoc      | 95 
> > +++++++++++++++++++++++++++++++++++++++
> >   2 files changed, 181 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..8e5deaacfb
> > --- /dev/null
> > +++ b/docs/features/hypervisorfs.pandoc
> > @@ -0,0 +1,86 @@
> > +% 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
> I would like to get some consitency in the formatting at least within a 
> same file. In this case, you seem to mostly use a single space the full 
> stop. So I think you want to use single space here too.
Either is fine with me.

I'm going to use a single space in case no one steps up and asks for
double spaces after full stops.

> > +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.
> > +
> > +* hypercall interface specification
> > +    * `xen/include/public/filesystem.h`
> > +* hypervisor internal files
> > +    * `xen/include/xen/filesystem.h`
> > +    * `xen/common/filesystem.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
> > +---------- -------- -------- -------------------------------------------
> > +2019-10-02 1        Xen 4.13 Document written
> Does this want any update? Such as using 4.14 rather than 4.13.
Uh, yes.

> > +---------- -------- -------- -------------------------------------------
> > diff --git a/docs/misc/hypfs-paths.pandoc b/docs/misc/hypfs-paths.pandoc
> > new file mode 100644
> > index 0000000000..67de8d2cf8
> > --- /dev/null
> > +++ b/docs/misc/hypfs-paths.pandoc
> > @@ -0,0 +1,95 @@
> > +# 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
> > +  ")".
> > +
> > +Additional TAGS may follow as a comma separated set of the following
> > +tags enclosed in square brackets.
> It may be clearer if you replace a full stop with :.
Okay.

> However, I am not sure what are actually the tags? Do you have a 
> concrete example how they can be used?
I'll add this one:

/cpu-bugs/active-pv/xpti (0|1) [w,X86,PV]

> > +
> > +* w -- Path is writable by the user. This capability is usually
> > +  limited to the control domain (e.g. dom0).
> > +* ARM | ARM32 | X86: the path is available for the respective 
> > architecture
> > +  only.
> How about Arm64? Also, if it is support by both arm64 and arm32, should 
> we use ARM or ARM32,ARM64?
ARM64 should be added and I'd suggest to use "ARM" instead of
"ARM32,ARM64".

> > +* 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.
> > +
> > +## 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.
Juergen

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel