Skip to contentSkip to conversation

docs: specify stability of hypfs path documentation

PATCH In review Juergen Gross 3 participants 5 messages Jul 20, 2020

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 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).

---
V2: reworded as requested by Jan Beulich
V3: reworded again as suggested by George Dunlap

---
 docs/misc/hypfs-paths.pandoc | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
docs/misc/hypfs-paths.pandoc +20 -0
index a111c6f25c..68d83d9245 100644
@@ -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:
Signature · 1 line
2.26.2
#1 lore raw
Quoted 10 lines

-----Original Message-----
From: Juergen Gross <[email protected]>
Sent: 20 July 2020 12:22
To: [email protected]
Cc: [email protected]; Juergen Gross <[email protected]>; Andrew Cooper <[email protected]>; George Dunlap <[email protected]>; Ian Jackson <[email protected]>; Jan Beulich <[email protected]>; Julien Grall <[email protected]>; Stefano Stabellini <[email protected]>; Wei Liu <[email protected]>
Subject: [PATCH v3] docs: specify stability of hypfs path documentation

Quoted 7 lines

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

TBC, this is also exempt from the commit moratorium as it really needs to be in 4.14.

Paul

Quoted 47 lines

---
V2: reworded as requested by Jan Beulich
V3: reworded again as suggested by George Dunlap

---
 docs/misc/hypfs-paths.pandoc | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
docs/misc/hypfs-paths.pandoc +20 -1
index a111c6f25c..68d83d9245 100644
@@ -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:
--

2.26.2

Acked-by on v3 1/1
#2 lore raw
In reply to Juergen Gross
Quoted 7 lines · Juergen Gross

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

Paul - should I throw this in right away, or has it now rather missed the train?

Jan

#3 lore raw
Quoted 15 lines

-----Original Message-----
From: Jan Beulich <[email protected]>
Sent: 20 July 2020 12:33
To: Juergen Gross <[email protected]>; [email protected]
Cc: [email protected]; Andrew Cooper <[email protected]>; George Dunlap <[email protected]>; Ian Jackson <[email protected]>; Julien Grall <[email protected]>; Stefano Stabellini <[email protected]>; Wei Liu <[email protected]>
Subject: Re: [PATCH v3] docs: specify stability of hypfs path documentation

Quoted 5 lines · Juergen Gross

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

Quoted 7 lines
Quoted 2 lines

Paul - should I throw this in right away, or has it now rather missed the train?

I guess our emails raced. Throw it in now.

Paul

Quoted 2 lines

Jan

#4 lore raw
Quoted 18 lines · Paul Durrant
Quoted 18 lines

-----Original Message-----
From: Jan Beulich <[email protected]>
Sent: 20 July 2020 12:33
To: Juergen Gross <[email protected]>; [email protected]
Cc: [email protected]; Andrew Cooper <[email protected]>; George Dunlap <[email protected]>; Ian Jackson <[email protected]>; Julien Grall <[email protected]>; Stefano Stabellini <[email protected]>; Wei Liu <[email protected]>
Subject: Re: [PATCH v3] docs: specify stability of hypfs path documentation

Quoted 7 lines · Juergen Gross

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

Quoted 6 lines
Quoted 4 lines

Paul - should I throw this in right away, or has it now rather missed the train?

I guess our emails raced. Throw it in now.

Indeed they did - I saw yours come in right after sending. Change is in now.

Jan