xen/docs/misc/hypfs-paths.pandoc

# 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
      cpupool/               directory containing CPU Pool data
        0/                   directory for cpupool 0
          sched-gran         "cpu", "core" or "socket"
      params/                directory with hypervisor parameter values
        loglvl               "none", "error", "warning", "info", "all"

## 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`.