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>
---
 docs/features/hypervisorfs.pandoc | 110 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 docs/features/hypervisorfs.pandoc

diff --git a/docs/features/hypervisorfs.pandoc b/docs/features/hypervisorfs.pandoc
new file mode 100644
index 0000000000..e13a3c9b0a
--- /dev/null
+++ b/docs/features/hypervisorfs.pandoc
@@ -0,0 +1,110 @@
+% Hypervisor FS
+% Revision 1
+
+\clearpage
+
+# Basics
+---------------- ---------------------
+         Status: e.g. **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, but without the functionality to directly alter
+entries values. Entries and directories are created by the hypervisor,
+while the toolstack is able to use a hypercall to query the entry
+values.
+
+# User details
+
+With:
+
+    xenfs --ls <path>
+
+the user can list the entries of a specific path of the FS. Using:
+
+    xenfs --cat <path>
+
+the content of an entry can be retrieved.
+
+The FS structure is:
+
+    /
+        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"
+        parameters/          directory with hypervisor parameter values
+                             (boot/runtime parameters)
+
+# 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`
+* `libxenfs`
+    * `tools/libs/libxenfs/*`
+* `xenfs`
+    * `tools/misc/xenfs.c`
+    
+# 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
+* Possibility to modify values via filesystem access
+
+# Known issues
+
+* None
+
+# References
+
+* None
+
+# History
+
+------------------------------------------------------------------------
+Date       Revision Version  Notes
+---------- -------- -------- -------------------------------------------
+2019-08-29 1        Xen 4.13 Document written
+---------- -------- -------- -------------------------------------------
-- 
2.16.4


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

On 11.09.2019 08:19, Juergen Gross wrote:
> +# 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, but without the functionality to directly alter
> +entries values. Entries and directories are created by the hypervisor,
> +while the toolstack is able to use a hypercall to query the entry
> +values.
> +
> +# User details
> +
> +With:
> +
> +    xenfs --ls <path>
> +
> +the user can list the entries of a specific path of the FS. Using:
> +
> +    xenfs --cat <path>
> +
> +the content of an entry can be retrieved.

Just one initial remark: I think the -- prefix to the commands
should be omitted; they should be used for option-like arguments
only.

Jan

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

On 11.09.19 11:28, Jan Beulich wrote:
> On 11.09.2019 08:19, Juergen Gross wrote:
>> +# 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, but without the functionality to directly alter
>> +entries values. Entries and directories are created by the hypervisor,
>> +while the toolstack is able to use a hypercall to query the entry
>> +values.
>> +
>> +# User details
>> +
>> +With:
>> +
>> +    xenfs --ls <path>
>> +
>> +the user can list the entries of a specific path of the FS. Using:
>> +
>> +    xenfs --cat <path>
>> +
>> +the content of an entry can be retrieved.
> 
> Just one initial remark: I think the -- prefix to the commands
> should be omitted; they should be used for option-like arguments
> only.

Fine with me.


Juergen


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