| Message ID | 20200121084330.18309-4-jgross@suse.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Add hypervisor sysfs-like support | expand |
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,
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
On 21/01/2020 14:17, Jürgen Groß wrote: > On 21.01.20 14:14, Julien Grall wrote: >> 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". I am happy with that. Cheers,
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 +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 +---------- -------- -------- ------------------------------------------- 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. + +* 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. +* 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.
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