Skip to contentSkip to conversation

docs: specify stability of hypfs path documentation

PATCH Superseded Juergen Gross 3 participants 7 messages Jul 13, 2020

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

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

---
This might be a candidate for 4.14, as hypfs is new in 4.14 and the documentation should be as clear as possible.

---
 docs/misc/hypfs-paths.pandoc | 8 ++++++++
 1 file changed, 8 insertions(+)
docs/misc/hypfs-paths.pandoc +8 -0
index a111c6f25c..7ad4b7ba95 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.
@@ -55,6 +58,11 @@ tags enclosed in square brackets.
 * CONFIG_* -- Path is valid only in case the hypervisor was built with
   the respective config option.
 
+Path availability is subject to change, e.g. a specific path specified
+for a single architecture now might be made available for other architectures
+in future, or it could be made conditional by an additional config option
+of the hypervisor.
+
 So an entry could look like this:
 
     /cpu-bugs/active-pv/xpti = ("No"|{"dom0", "domU", "PCID-on"}) [w,X86,PV]
Signature · 1 line
2.26.2
#1 lore raw

docs/misc/hypfs-paths.pandoc tags enclosed in square brackets. · line 64

Quoted 8 lines · Juergen Gross
docs/misc/hypfs-paths.pandoc +4 -0
@@ -55,6 +58,11 @@ tags enclosed in square brackets.
 * CONFIG_* -- Path is valid only in case the hypervisor was built with
   the respective config option.
 
+Path availability is subject to change, e.g. a specific path specified
+for a single architecture now might be made available for other architectures
+in future, or it could be made conditional by an additional config option
+of the hypervisor.

I agree this is worthwhile clarifying. To me, between the lines, this then suggests that paths are entirely unreliable, which I don't think is what we want. So perhaps some further clarification could be added to clarify that we're not going to arbitrarily change paths or their meaning? Or am I mistaken in understanding that this interface is meant to act ABI-like?

Jan

#2 lore raw
Quoted 5 lines · Jan Beulich
Quoted 4 lines · Juergen Gross
docs/misc/hypfs-paths.pandoc +0 -0
@@ -55,6 +58,11 @@ tags enclosed in square brackets.
  * CONFIG_* -- Path is valid only in case the hypervisor was built with
    the respective config option.
 
Quoted 11 lines

docs/misc/hypfs-paths.pandoc tags enclosed in square brackets. · line 64

Quoted 4 lines
docs/misc/hypfs-paths.pandoc +4 -0
+Path availability is subject to change, e.g. a specific path specified
+for a single architecture now might be made available for other architectures
+in future, or it could be made conditional by an additional config option
+of the hypervisor.

I agree this is worthwhile clarifying. To me, between the lines, this then suggests that paths are entirely unreliable, which I don't think is what we want. So perhaps some further clarification could be added to clarify that we're not going to arbitrarily change paths or their meaning? Or am I mistaken in understanding that this interface is meant to act ABI-like?

You are right. What about following rewording:

"In case a tag for a path indicates that this path is available in some
case only, this availability might be extended or reduced in future by modification or removal of the tag."

Juergen

#3 lore raw
Quoted 18 lines · Jürgen Groß
Quoted 5 lines · Jan Beulich
Quoted 4 lines · Juergen Gross
docs/misc/hypfs-paths.pandoc +0 -0
@@ -55,6 +58,11 @@ tags enclosed in square brackets.
  * CONFIG_* -- Path is valid only in case the hypervisor was built with
    the respective config option.
 
Quoted 11 lines

docs/misc/hypfs-paths.pandoc tags enclosed in square brackets. · line 64

Quoted 4 lines
docs/misc/hypfs-paths.pandoc +4 -0
+Path availability is subject to change, e.g. a specific path specified
+for a single architecture now might be made available for other architectures
+in future, or it could be made conditional by an additional config option
+of the hypervisor.

I agree this is worthwhile clarifying. To me, between the lines, this then suggests that paths are entirely unreliable, which I don't think is what we want. So perhaps some further clarification could be added to clarify that we're not going to arbitrarily change paths or their meaning? Or am I mistaken in understanding that this interface is meant to act ABI-like?

Quoted 5 lines

You are right. What about following rewording:

"In case a tag for a path indicates that this path is available in some
case only, this availability might be extended or reduced in future by modification or removal of the tag."

Yes, yet I'd go even further and add "A path once assigned meaning won't go away altogether or change its meaning, though" or some such.

Jan

#4 lore raw
Quoted 19 lines · Jan Beulich
Quoted 18 lines · Jürgen Groß
Quoted 16 lines · Jan Beulich

docs/misc/hypfs-paths.pandoc tags enclosed in square brackets. · line 64

Quoted 8 lines · Juergen Gross
docs/misc/hypfs-paths.pandoc +4 -0
@@ -55,6 +58,11 @@ tags enclosed in square brackets.
   * CONFIG_* -- Path is valid only in case the hypervisor was built with
     the respective config option.
 
+Path availability is subject to change, e.g. a specific path specified
+for a single architecture now might be made available for other architectures
+in future, or it could be made conditional by an additional config option
+of the hypervisor.

I agree this is worthwhile clarifying. To me, between the lines, this then suggests that paths are entirely unreliable, which I don't think is what we want. So perhaps some further clarification could be added to clarify that we're not going to arbitrarily change paths or their meaning? Or am I mistaken in understanding that this interface is meant to act ABI-like?

Quoted 8 lines
Quoted 5 lines

You are right. What about following rewording:

"In case a tag for a path indicates that this path is available in some
case only, this availability might be extended or reduced in future by modification or removal of the tag."

Yes, yet I'd go even further and add "A path once assigned meaning won't go away altogether or change its meaning, though" or some such.

Fine with me. Will send V2.

Juergen

#5 lore raw
In reply to Juergen Gross
Quoted 15 lines

-----Original Message-----
From: Juergen Gross <[email protected]>
Sent: 13 July 2020 06:17
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] 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).

Quoted 4 lines

---
This might be a candidate for 4.14, as hypfs is new in 4.14 and the documentation should be as clear as possible.

Agreed. Since this a pure documentation change it carries no risk, so once the final wording is agreed then consider it...

Quoted 32 lines
---
 docs/misc/hypfs-paths.pandoc | 8 ++++++++
 1 file changed, 8 insertions(+)
docs/misc/hypfs-paths.pandoc +8 -1
index a111c6f25c..7ad4b7ba95 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.
@@ -55,6 +58,11 @@ tags enclosed in square brackets.
 * CONFIG_* -- Path is valid only in case the hypervisor was built with
   the respective config option.
 
+Path availability is subject to change, e.g. a specific path specified
+for a single architecture now might be made available for other architectures
+in future, or it could be made conditional by an additional config option
+of the hypervisor.
+
 So an entry could look like this:
 
     /cpu-bugs/active-pv/xpti = ("No"|{"dom0", "domU", "PCID-on"}) [w,X86,PV]
--

2.26.2

#6 lore raw
Quoted 15 lines · Paul Durrant
Quoted 15 lines

-----Original Message-----
From: Juergen Gross <[email protected]>
Sent: 13 July 2020 06:17
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] 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).

Quoted 8 lines
Quoted 4 lines

---
This might be a candidate for 4.14, as hypfs is new in 4.14 and the documentation should be as clear as possible.

Agreed. Since this a pure documentation change it carries no risk, so once the final wording is agreed then consider it...

Thanks!

Juergen