1% Hypervisor FS
2% Revision 1
3
4\clearpage
5
6# Basics
7---------------- ---------------------
8         Status: **Supported**
9
10  Architectures: all
11
12     Components: Hypervisor, toolstack
13---------------- ---------------------
14
15# Overview
16
17The Hypervisor FS is a hierarchical name-value store for reporting
18information to guests, especially dom0. It is similar to the Linux
19kernel's sysfs. Entries and directories are created by the hypervisor,
20while the toolstack is able to use a hypercall to query the entry
21values or (if allowed by the hypervisor) to modify them.
22
23# User details
24
25With:
26
27    xenhypfs ls <path>
28
29the user can list the entries of a specific path of the FS. Using:
30
31    xenhypfs cat <path>
32
33the content of an entry can be retrieved. Using:
34
35    xenhypfs write <path> <string>
36
37a writable entry can be modified. With:
38
39    xenhypfs tree
40
41the complete Hypervisor FS entry tree can be printed.
42
43The FS paths are documented in `docs/misc/hypfs-paths.pandoc`.
44
45# Technical details
46
47Access to the hypervisor filesystem is done via the stable new hypercall
48__HYPERVISOR_filesystem_op. This hypercall supports a sub-command
49XEN_HYPFS_OP_get_version which will return the highest version of the
50interface supported by the hypervisor. Additions to the interface need
51to bump the interface version. The hypervisor is required to support the
52previous interface versions, too (this implies that additions will always
53require new sub-commands in order to allow the hypervisor to decide which
54version of the interface to use).
55
56* hypercall interface specification
57    * `xen/include/public/hypfs.h`
58* hypervisor internal files
59    * `xen/include/xen/hypfs.h`
60    * `xen/common/hypfs.c`
61* `libxenhypfs`
62    * `tools/libs/libxenhypfs/*`
63* `xenhypfs`
64    * `tools/misc/xenhypfs.c`
65* path documentation
66    * `docs/misc/hypfs-paths.pandoc`
67
68# Testing
69
70Any new parameters or hardware mitigations should be verified to show up
71correctly in the filesystem.
72
73# Areas for improvement
74
75* More detailed access rights
76* Entries per domain and/or per cpupool
77
78# Known issues
79
80* None
81
82# References
83
84* None
85
86# History
87
88------------------------------------------------------------------------
89Date       Revision Version  Notes
90---------- -------- -------- -------------------------------------------
912020-01-23 1        Xen 4.14 Document written
92---------- -------- -------- -------------------------------------------
93