docs: specify stability of hypfs path documentation
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
@@ -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
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
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
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
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
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 documentationIn 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
Signed-off-by Juergen Gross <[email protected]>---
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@@ -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
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 documentationIn 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
Signed-off-by Juergen Gross <[email protected]>---
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...
Release-acked-by Paul Durrant <[email protected]>
Thanks!
Juergen