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

[Julien Grall <julien@xen.org>]

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.

> +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.

> +---------- -------- -------- -------------------------------------------
> 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 :.

However, I am not sure what are actually the tags? Do you have a 
concrete example how they can be used?

> +
> +* 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?

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

Cheers,

-- 
Julien Grall

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