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

["Jürgen Groß" <jgross@suse.com>]

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@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)
>> ---
>>   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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel