commit 5a4a411bde4f73ff8ce43d6e52b77302973e8f68
Author: Juergen Gross <jgross@suse.com>
AuthorDate: Mon Jul 20 13:38:00 2020 +0200
Commit: Jan Beulich <jbeulich@suse.com>
CommitDate: Mon Jul 20 13:38:00 2020 +0200
docs: specify stability of hypfs path documentation
In docs/misc/hypfs-paths.pandoc the supported paths in the hypervisor
file system are specified. Make it more clear that path availability
might change, e.g. due to scope widening or narrowing (e.g. being
limited to a specific architecture).
Signed-off-by: Juergen Gross <jgross@suse.com>
Acked-by: Jan Beulich <jbeulich@suse.com>
Release-acked-by: Paul Durrant <paul@xen.org>
---
docs/misc/hypfs-paths.pandoc | 20 ++++++++++++++++++++
1 file changed, 20 insertions(+)
diff --git a/docs/misc/hypfs-paths.pandoc b/docs/misc/hypfs-paths.pandoc
index a111c6f25c..81d70bb80c 100644
--- a/docs/misc/hypfs-paths.pandoc
+++ b/docs/misc/hypfs-paths.pandoc
@@ -5,6 +5,9 @@ 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.
@@ -64,6 +67,23 @@ 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:
--
generated by git-patchbot for /home/xen/git/xen.git#master
Author: Juergen Gross <jgross@suse.com>
AuthorDate: Mon Jul 20 13:38:00 2020 +0200
Commit: Jan Beulich <jbeulich@suse.com>
CommitDate: Mon Jul 20 13:38:00 2020 +0200
docs: specify stability of hypfs path documentation
In docs/misc/hypfs-paths.pandoc the supported paths in the hypervisor
file system are specified. Make it more clear that path availability
might change, e.g. due to scope widening or narrowing (e.g. being
limited to a specific architecture).
Signed-off-by: Juergen Gross <jgross@suse.com>
Acked-by: Jan Beulich <jbeulich@suse.com>
Release-acked-by: Paul Durrant <paul@xen.org>
---
docs/misc/hypfs-paths.pandoc | 20 ++++++++++++++++++++
1 file changed, 20 insertions(+)
diff --git a/docs/misc/hypfs-paths.pandoc b/docs/misc/hypfs-paths.pandoc
index a111c6f25c..81d70bb80c 100644
--- a/docs/misc/hypfs-paths.pandoc
+++ b/docs/misc/hypfs-paths.pandoc
@@ -5,6 +5,9 @@ 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.
@@ -64,6 +67,23 @@ 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:
--
generated by git-patchbot for /home/xen/git/xen.git#master