1# Xenhypfs Paths 2 3This document attempts to define all the paths which are available 4in the Xen hypervisor file system (hypfs). 5 6The hypervisor file system can be accessed via the xenhypfs tool. 7 8The availability of the hypervisor file system depends on the hypervisor 9config option CONFIG_HYPFS, which is on per default. 10 11## Notation 12 13The hypervisor file system is similar to the Linux kernel's sysfs. 14In this document directories are always specified with a trailing "/". 15 16The following notation conventions apply: 17 18 DIRECTORY/ 19 20 PATH = VALUES [TAGS] 21 22The first syntax defines a directory. It normally contains related 23entries and the general scope of the directory is described. 24 25The second syntax defines a file entry containing values which are 26either set by the hypervisor or, if the file is writable, can be set 27by the user. 28 29PATH can contain simple regex constructs following the Perl compatible 30regexp syntax described in pcre(3) or perlre(1). 31 32A hypervisor file system entry name can be any 0-delimited byte string 33not containing any '/' character. The names "." and ".." are reserved 34for file system internal use. 35 36VALUES are strings and can take the following forms (note that this represents 37only the syntax used in this document): 38 39* STRING -- an arbitrary 0-delimited byte string. 40* INTEGER -- An integer, in decimal representation unless otherwise 41 noted. 42* "a literal string" -- literal strings are contained within quotes. 43* (VALUE | VALUE | ... ) -- a set of alternatives. Alternatives are 44 separated by a "|" and all the alternatives are enclosed in "(" and 45 ")". 46* {VALUE, VALUE, ... } -- a list of possible values separated by "," and 47 enclosed in "{" and "}". 48 49Additional TAGS may follow as a comma separated set of the following 50tags enclosed in square brackets. 51 52* w -- Path is writable by the user. This capability is usually 53 limited to the control domain (e.g. dom0). 54* ARM | ARM32 | ARM64 | X86: the path is available for the respective 55 architecture only. 56* PV -- Path is valid for PV capable hypervisors only. 57* HVM -- Path is valid for HVM capable hypervisors only. 58* CONFIG_* -- Path is valid only in case the hypervisor was built with 59 the respective config option. 60 61So an entry could look like this: 62 63 /cpu-bugs/active-pv/xpti = ("No"|{"dom0", "domU", "PCID-on"}) [w,X86,PV] 64 65Possible values would be "No" or a list of "dom0", "domU", and "PCID-on" with 66the list elements separated by spaces, e.g. "dom0 PCID-on". 67The entry would be writable and it would exist on X86 only and only if the 68hypervisor is configured to support PV guests. 69 70# Stability 71 72Path *presence* is not stable, but path *meaning* is always stable: if a tool 73you write finds a path present, it can rely on behavior in future versions of 74the hypervisors, and in different configurations. Specifically: 75 761. Conditions under which paths are used may be extended, restricted, or 77 removed. For example, a path that's always available only on ARM systems 78 may become available on x86; or a path available on both systems may be 79 restricted to only appearing on ARM systems. Paths may also disappear 80 entirely. 812. However, the meaning of a path will never change. If a path is present, 82 it will always have exactly the meaning that it always had. In order to 83 maintain this, removed paths should be retained with the tag [REMOVED]. 84 The path may be restored *only* if the restored version of the path is 85 compatible with the previous functionality. 86 87## Example 88 89A populated Xen hypervisor file system might look like the following example: 90 91 / 92 buildinfo/ directory containing build-time data 93 config contents of .config file used to build Xen 94 cpu-bugs/ x86: directory of cpu bug information 95 l1tf "Vulnerable" or "Not vulnerable" 96 mds "Vulnerable" or "Not vulnerable" 97 meltdown "Vulnerable" or "Not vulnerable" 98 spec-store-bypass "Vulnerable" or "Not vulnerable" 99 spectre-v1 "Vulnerable" or "Not vulnerable" 100 spectre-v2 "Vulnerable" or "Not vulnerable" 101 mitigations/ directory of mitigation settings 102 bti-thunk "N/A", "RETPOLINE", "LFENCE" or "JMP" 103 spec-ctrl "No", "IBRS+" or "IBRS-" 104 ibpb "No" or "Yes" 105 l1d-flush "No" or "Yes" 106 md-clear "No" or "VERW" 107 l1tf-barrier "No" or "Yes" 108 active-hvm/ directory for mitigations active in hvm doamins 109 msr-spec-ctrl "No" or "Yes" 110 rsb "No" or "Yes" 111 eager-fpu "No" or "Yes" 112 md-clear "No" or "Yes" 113 active-pv/ directory for mitigations active in pv doamins 114 msr-spec-ctrl "No" or "Yes" 115 rsb "No" or "Yes" 116 eager-fpu "No" or "Yes" 117 md-clear "No" or "Yes" 118 xpti "No" or list of "dom0", "domU", "PCID-on" 119 l1tf-shadow "No" or list of "dom0", "domU" 120 params/ directory with hypervisor parameter values 121 (boot/runtime parameters) 122 123## General Paths 124 125#### / 126 127The root of the hypervisor file system. 128 129#### /buildinfo/ 130 131A directory containing static information generated while building the 132hypervisor. 133 134#### /buildinfo/changeset = STRING 135 136Git commit of the hypervisor. 137 138#### /buildinfo/compileinfo/ 139 140A directory containing information about compilation of Xen. 141 142#### /buildinfo/compileinfo/compile_by = STRING 143 144Information who compiled the hypervisor. 145 146#### /buildinfo/compileinfo/compile_date = STRING 147 148Date of the hypervisor compilation. 149 150#### /buildinfo/compileinfo/compile_domain = STRING 151 152Information about the compile domain. 153 154#### /buildinfo/compileinfo/compiler = STRING 155 156The compiler used to build Xen. 157 158#### /buildinfo/config = STRING [CONFIG_HYPFS_CONFIG] 159 160The contents of the `xen/.config` file at the time of the hypervisor build. 161 162#### /buildinfo/version/ 163 164A directory containing version information of the hypervisor. 165 166#### /buildinfo/version/extra = STRING 167 168Extra version information. 169 170#### /buildinfo/version/major = INTEGER 171 172The major version of Xen. 173 174#### /buildinfo/version/minor = INTEGER 175 176The minor version of Xen. 177 178#### /params/ 179 180A directory of runtime parameters. 181 182#### /params/* 183 184The individual parameters. The description of the different parameters can be 185found in `docs/misc/xen-command-line.pandoc`. 186