1 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.

1.1 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):

Additional TAGS may follow as a comma separated set of the following tags enclosed in square brackets.

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.

2 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.

2.1 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)

2.2 General Paths

2.2.0.1 /

The root of the hypervisor file system.

2.2.0.2 /buildinfo/

A directory containing static information generated while building the hypervisor.

2.2.0.3 /buildinfo/changeset = STRING

Git commit of the hypervisor.

2.2.0.4 /buildinfo/compileinfo/

A directory containing information about compilation of Xen.

2.2.0.5 /buildinfo/compileinfo/compile_by = STRING

Information who compiled the hypervisor.

2.2.0.6 /buildinfo/compileinfo/compile_date = STRING

Date of the hypervisor compilation.

2.2.0.7 /buildinfo/compileinfo/compile_domain = STRING

Information about the compile domain.

2.2.0.8 /buildinfo/compileinfo/compiler = STRING

The compiler used to build Xen.

2.2.0.9 /buildinfo/config = STRING [CONFIG_HYPFS_CONFIG]

The contents of the xen/.config file at the time of the hypervisor build.

2.2.0.10 /buildinfo/version/

A directory containing version information of the hypervisor.

2.2.0.11 /buildinfo/version/extra = STRING

Extra version information.

2.2.0.12 /buildinfo/version/major = INTEGER

The major version of Xen.

2.2.0.13 /buildinfo/version/minor = INTEGER

The minor version of Xen.

2.2.0.14 /cpupool/

A directory of all current cpupools.

2.2.0.15 /cpupool/*/

The individual cpupools. Each entry is a directory with the name being the cpupool-id (e.g. /cpupool/0/).

2.2.0.16 /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.

2.2.0.17 /params/

A directory of runtime parameters.

2.2.0.18 /params/* [w]

The individual parameters. The description of the different parameters can be found in docs/misc/xen-command-line.pandoc.