1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
# 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.
The availability of the hypervisor file system depends on the hypervisor
config option CONFIG_HYPFS, which is on per default.
## 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 (note that this represents
only the syntax used in this document):
* 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
")".
* {VALUE, VALUE, ... } -- a list of possible values separated by "," and
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 | ARM64 | 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.
So an entry could look like this:
/cpu-bugs/active-pv/xpti = ("No"|{"dom0", "domU", "PCID-on"}) [w,X86,PV]
Possible values would be "No" or a list of "dom0", "domU", and "PCID-on" with
the list elements separated by spaces, e.g. "dom0 PCID-on".
The entry would be writable and it would exist on X86 only and only if the
hypervisor is configured to support PV guests.
# Stability
Path *presence* is not stable, but path *meaning* is always stable: if a tool
you write finds a path present, it can rely on behavior in future versions of
the hypervisors, and in different configurations. Specifically:
1. Conditions under which paths are used may be extended, restricted, or
removed. For example, a path that's always available only on ARM systems
may become available on x86; or a path available on both systems may be
restricted to only appearing on ARM systems. Paths may also disappear
entirely.
2. However, the meaning of a path will never change. If a path is present,
it will always have exactly the meaning that it always had. In order to
maintain this, removed paths should be retained with the tag [REMOVED].
The path may be restored *only* if the restored version of the path is
compatible with the previous functionality.
## 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.
#### /buildinfo/
A directory containing static information generated while building the
hypervisor.
#### /buildinfo/changeset = STRING
Git commit of the hypervisor.
#### /buildinfo/compileinfo/
A directory containing information about compilation of Xen.
#### /buildinfo/compileinfo/compile_by = STRING
Information who compiled the hypervisor.
#### /buildinfo/compileinfo/compile_date = STRING
Date of the hypervisor compilation.
#### /buildinfo/compileinfo/compile_domain = STRING
Information about the compile domain.
#### /buildinfo/compileinfo/compiler = STRING
The compiler used to build Xen.
#### /buildinfo/config = STRING [CONFIG_HYPFS_CONFIG]
The contents of the `xen/.config` file at the time of the hypervisor build.
#### /buildinfo/version/
A directory containing version information of the hypervisor.
#### /buildinfo/version/extra = STRING
Extra version information.
#### /buildinfo/version/major = INTEGER
The major version of Xen.
#### /buildinfo/version/minor = INTEGER
The minor version of Xen.
#### /cpupool/
A directory of all current cpupools.
#### /cpupool/*/
The individual cpupools. Each entry is a directory with the name being the
cpupool-id (e.g. /cpupool/0/).
#### /cpupool/*/sched-gran = ("cpu" | "core" | "socket") [w]
The scheduling granularity of a cpupool.
Writing a value is allowed only for cpupools with no cpu assigned and if the
architecture is supporting different scheduling granularities.
#### /params/
A directory of runtime parameters.
#### /params/* [w]
The individual parameters. The description of the different parameters can be
found in `docs/misc/xen-command-line.pandoc`.
|
