diff mbox series

[v2] docs: specify stability of hypfs path documentation

Message ID 20200713140338.16172-1-jgross@suse.com (mailing list archive)
State Superseded
Headers show
Series [v2] docs: specify stability of hypfs path documentation | expand

Commit Message

Jürgen Groß July 13, 2020, 2:03 p.m. UTC
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>
Release-acked-by: Paul Durrant <paul@xen.org>
---
V2: reworded as requested by Jan Beulich
---
 docs/misc/hypfs-paths.pandoc | 8 ++++++++
 1 file changed, 8 insertions(+)

Comments

Jan Beulich July 13, 2020, 2:47 p.m. UTC | #1
On 13.07.2020 16:03, Juergen Gross wrote:
> 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>
> Release-acked-by: Paul Durrant <paul@xen.org>

Acked-by: Jan Beulich <jbeulich@suse.com>

However, I'd like agreement by at least one other REST maintainer on
...

> @@ -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.
>  
> +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. A path once assigned meaning won't go
> +away altogether or change its meaning, though.

... the newly imposed guarantee we're now making. We really want to
avoid declaring something as stable without being quite certain we
can keep it stable.

Jan
George Dunlap July 15, 2020, 2:37 p.m. UTC | #2
> On Jul 13, 2020, at 3:47 PM, Jan Beulich <JBeulich@suse.com> wrote:
> 
> On 13.07.2020 16:03, Juergen Gross wrote:
>> 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>
>> Release-acked-by: Paul Durrant <paul@xen.org>
> 
> Acked-by: Jan Beulich <jbeulich@suse.com>
> 
> However, I'd like agreement by at least one other REST maintainer on
> ...
> 
>> @@ -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.
>> 
>> +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. A path once assigned meaning won't go
>> +away altogether or change its meaning, though.
> 
> ... the newly imposed guarantee we're now making. We really want to
> avoid declaring something as stable without being quite certain we
> can keep it stable.

The declaration of new nodes must all happen in this file, right?  So as long as the maintainer(s) fo this file are aware of that, and it’s commented so that people know that expecation, I think it’s OK.

But I think this paragraph isn’t very clear to me what “might be extended or reduced …but won’t go away altogether”.

IT sounds like you’re saying:

1. Paths listed without conditions will always be available

2. Paths listed with conditions may be extended: i.e., a node currently listed as PV might also become available for HVM guests

3. Paths listed with conditions might have those conditions reduced, but will never entirely disappear.  So something currently listed as PV might be reduced to CONFIG_HAS_FOO, but won’t be completely removed.

Is that what you meant?

 -George
Jürgen Groß July 15, 2020, 2:41 p.m. UTC | #3
On 15.07.20 16:37, George Dunlap wrote:
> 
> 
>> On Jul 13, 2020, at 3:47 PM, Jan Beulich <JBeulich@suse.com> wrote:
>>
>> On 13.07.2020 16:03, Juergen Gross wrote:
>>> 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>
>>> Release-acked-by: Paul Durrant <paul@xen.org>
>>
>> Acked-by: Jan Beulich <jbeulich@suse.com>
>>
>> However, I'd like agreement by at least one other REST maintainer on
>> ...
>>
>>> @@ -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.
>>>
>>> +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. A path once assigned meaning won't go
>>> +away altogether or change its meaning, though.
>>
>> ... the newly imposed guarantee we're now making. We really want to
>> avoid declaring something as stable without being quite certain we
>> can keep it stable.
> 
> The declaration of new nodes must all happen in this file, right?  So as long as the maintainer(s) fo this file are aware of that, and it’s commented so that people know that expecation, I think it’s OK.
> 
> But I think this paragraph isn’t very clear to me what “might be extended or reduced …but won’t go away altogether”.
> 
> IT sounds like you’re saying:
> 
> 1. Paths listed without conditions will always be available
> 
> 2. Paths listed with conditions may be extended: i.e., a node currently listed as PV might also become available for HVM guests
> 
> 3. Paths listed with conditions might have those conditions reduced, but will never entirely disappear.  So something currently listed as PV might be reduced to CONFIG_HAS_FOO, but won’t be completely removed.
> 
> Is that what you meant?

Yes.


Juergen
Jan Beulich July 16, 2020, 10:11 a.m. UTC | #4
On 15.07.2020 16:37, George Dunlap wrote:
> IT sounds like you’re saying:
> 
> 1. Paths listed without conditions will always be available
> 
> 2. Paths listed with conditions may be extended: i.e., a node currently listed as PV might also become available for HVM guests
> 
> 3. Paths listed with conditions might have those conditions reduced, but will never entirely disappear.  So something currently listed as PV might be reduced to CONFIG_HAS_FOO, but won’t be completely removed.
> 
> Is that what you meant?

I see Jürgen replied "yes" to this, but I'm not sure about 1.
above: I think it's quite reasonable to expect that paths without
condition may gain a condition. Just like paths now having a
condition and (perhaps temporarily) losing it shouldn't all of
the sudden become "always available" when they weren't meant to
be.

As far a 3. goes, I'm also unsure in how far this is any better
stability wise (from a consumer pov) than allowing paths to
entirely disappear.

Jan
Jürgen Groß July 16, 2020, 10:31 a.m. UTC | #5
On 16.07.20 12:11, Jan Beulich wrote:
> On 15.07.2020 16:37, George Dunlap wrote:
>> IT sounds like you’re saying:
>>
>> 1. Paths listed without conditions will always be available
>>
>> 2. Paths listed with conditions may be extended: i.e., a node currently listed as PV might also become available for HVM guests
>>
>> 3. Paths listed with conditions might have those conditions reduced, but will never entirely disappear.  So something currently listed as PV might be reduced to CONFIG_HAS_FOO, but won’t be completely removed.
>>
>> Is that what you meant?
> 
> I see Jürgen replied "yes" to this, but I'm not sure about 1.
> above: I think it's quite reasonable to expect that paths without
> condition may gain a condition. Just like paths now having a
> condition and (perhaps temporarily) losing it shouldn't all of
> the sudden become "always available" when they weren't meant to
> be.
> 
> As far a 3. goes, I'm also unsure in how far this is any better
> stability wise (from a consumer pov) than allowing paths to
> entirely disappear.

The idea is that any user tool using hypfs can rely on paths under 1 to
exist, while the ones under 3 might not be there due to the hypervisor
config or the used system.

A path not being allowed to entirely disappear ensures that it remains
in the documentation, so the same path can't be reused for something
different in future.


Juergen
Jan Beulich July 16, 2020, 11:24 a.m. UTC | #6
On 16.07.2020 12:31, Jürgen Groß wrote:
> On 16.07.20 12:11, Jan Beulich wrote:
>> On 15.07.2020 16:37, George Dunlap wrote:
>>> IT sounds like you’re saying:
>>>
>>> 1. Paths listed without conditions will always be available
>>>
>>> 2. Paths listed with conditions may be extended: i.e., a node currently listed as PV might also become available for HVM guests
>>>
>>> 3. Paths listed with conditions might have those conditions reduced, but will never entirely disappear.  So something currently listed as PV might be reduced to CONFIG_HAS_FOO, but won’t be completely removed.
>>>
>>> Is that what you meant?
>>
>> I see Jürgen replied "yes" to this, but I'm not sure about 1.
>> above: I think it's quite reasonable to expect that paths without
>> condition may gain a condition. Just like paths now having a
>> condition and (perhaps temporarily) losing it shouldn't all of
>> the sudden become "always available" when they weren't meant to
>> be.
>>
>> As far a 3. goes, I'm also unsure in how far this is any better
>> stability wise (from a consumer pov) than allowing paths to
>> entirely disappear.
> 
> The idea is that any user tool using hypfs can rely on paths under 1 to
> exist, while the ones under 3 might not be there due to the hypervisor
> config or the used system.
> 
> A path not being allowed to entirely disappear ensures that it remains
> in the documentation, so the same path can't be reused for something
> different in future.

And then how do you deal with a condition getting dropped, and
later wanting to get re-added? Do we need a placeholder condition
like [ALWAYS] or [TRUE]?

Jan
Jürgen Groß July 16, 2020, 11:34 a.m. UTC | #7
On 16.07.20 13:24, Jan Beulich wrote:
> On 16.07.2020 12:31, Jürgen Groß wrote:
>> On 16.07.20 12:11, Jan Beulich wrote:
>>> On 15.07.2020 16:37, George Dunlap wrote:
>>>> IT sounds like you’re saying:
>>>>
>>>> 1. Paths listed without conditions will always be available
>>>>
>>>> 2. Paths listed with conditions may be extended: i.e., a node currently listed as PV might also become available for HVM guests
>>>>
>>>> 3. Paths listed with conditions might have those conditions reduced, but will never entirely disappear.  So something currently listed as PV might be reduced to CONFIG_HAS_FOO, but won’t be completely removed.
>>>>
>>>> Is that what you meant?
>>>
>>> I see Jürgen replied "yes" to this, but I'm not sure about 1.
>>> above: I think it's quite reasonable to expect that paths without
>>> condition may gain a condition. Just like paths now having a
>>> condition and (perhaps temporarily) losing it shouldn't all of
>>> the sudden become "always available" when they weren't meant to
>>> be.
>>>
>>> As far a 3. goes, I'm also unsure in how far this is any better
>>> stability wise (from a consumer pov) than allowing paths to
>>> entirely disappear.
>>
>> The idea is that any user tool using hypfs can rely on paths under 1 to
>> exist, while the ones under 3 might not be there due to the hypervisor
>> config or the used system.
>>
>> A path not being allowed to entirely disappear ensures that it remains
>> in the documentation, so the same path can't be reused for something
>> different in future.
> 
> And then how do you deal with a condition getting dropped, and
> later wanting to get re-added? Do we need a placeholder condition
> like [ALWAYS] or [TRUE]?

Dropping a condition has to be considered very carefully, same as
introducing a new path without any condition.

In worst case you can still go with [CONFIG_HYPFS].


Juergen
George Dunlap July 16, 2020, 2:20 p.m. UTC | #8
> On Jul 16, 2020, at 12:34 PM, Jürgen Groß <jgross@suse.com> wrote:
> 
> On 16.07.20 13:24, Jan Beulich wrote:
>> On 16.07.2020 12:31, Jürgen Groß wrote:
>>> On 16.07.20 12:11, Jan Beulich wrote:
>>>> On 15.07.2020 16:37, George Dunlap wrote:
>>>>> IT sounds like you’re saying:
>>>>> 
>>>>> 1. Paths listed without conditions will always be available
>>>>> 
>>>>> 2. Paths listed with conditions may be extended: i.e., a node currently listed as PV might also become available for HVM guests
>>>>> 
>>>>> 3. Paths listed with conditions might have those conditions reduced, but will never entirely disappear.  So something currently listed as PV might be reduced to CONFIG_HAS_FOO, but won’t be completely removed.
>>>>> 
>>>>> Is that what you meant?
>>>> 
>>>> I see Jürgen replied "yes" to this, but I'm not sure about 1.
>>>> above: I think it's quite reasonable to expect that paths without
>>>> condition may gain a condition. Just like paths now having a
>>>> condition and (perhaps temporarily) losing it shouldn't all of
>>>> the sudden become "always available" when they weren't meant to
>>>> be.
>>>> 
>>>> As far a 3. goes, I'm also unsure in how far this is any better
>>>> stability wise (from a consumer pov) than allowing paths to
>>>> entirely disappear.
>>> 
>>> The idea is that any user tool using hypfs can rely on paths under 1 to
>>> exist, while the ones under 3 might not be there due to the hypervisor
>>> config or the used system.
>>> 
>>> A path not being allowed to entirely disappear ensures that it remains
>>> in the documentation, so the same path can't be reused for something
>>> different in future.
>> And then how do you deal with a condition getting dropped, and
>> later wanting to get re-added? Do we need a placeholder condition
>> like [ALWAYS] or [TRUE]?
> 
> Dropping a condition has to be considered very carefully, same as
> introducing a new path without any condition.
> 
> In worst case you can still go with [CONFIG_HYPFS].

Couldn’t we just have a section of the document for dead paths that aren’t allowed to be used?

Alternately, we could have a tag for entries we don’t want used anymore; [DEAD] or [OBSOLETE] maybe? [DEFUNCT]? [REMOVED]?

So I think I’d write a separate section, like this:

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

Thoughts?

 -George
Jürgen Groß July 16, 2020, 2:34 p.m. UTC | #9
On 16.07.20 16:20, George Dunlap wrote:
> 
> 
>> On Jul 16, 2020, at 12:34 PM, Jürgen Groß <jgross@suse.com> wrote:
>>
>> On 16.07.20 13:24, Jan Beulich wrote:
>>> On 16.07.2020 12:31, Jürgen Groß wrote:
>>>> On 16.07.20 12:11, Jan Beulich wrote:
>>>>> On 15.07.2020 16:37, George Dunlap wrote:
>>>>>> IT sounds like you’re saying:
>>>>>>
>>>>>> 1. Paths listed without conditions will always be available
>>>>>>
>>>>>> 2. Paths listed with conditions may be extended: i.e., a node currently listed as PV might also become available for HVM guests
>>>>>>
>>>>>> 3. Paths listed with conditions might have those conditions reduced, but will never entirely disappear.  So something currently listed as PV might be reduced to CONFIG_HAS_FOO, but won’t be completely removed.
>>>>>>
>>>>>> Is that what you meant?
>>>>>
>>>>> I see Jürgen replied "yes" to this, but I'm not sure about 1.
>>>>> above: I think it's quite reasonable to expect that paths without
>>>>> condition may gain a condition. Just like paths now having a
>>>>> condition and (perhaps temporarily) losing it shouldn't all of
>>>>> the sudden become "always available" when they weren't meant to
>>>>> be.
>>>>>
>>>>> As far a 3. goes, I'm also unsure in how far this is any better
>>>>> stability wise (from a consumer pov) than allowing paths to
>>>>> entirely disappear.
>>>>
>>>> The idea is that any user tool using hypfs can rely on paths under 1 to
>>>> exist, while the ones under 3 might not be there due to the hypervisor
>>>> config or the used system.
>>>>
>>>> A path not being allowed to entirely disappear ensures that it remains
>>>> in the documentation, so the same path can't be reused for something
>>>> different in future.
>>> And then how do you deal with a condition getting dropped, and
>>> later wanting to get re-added? Do we need a placeholder condition
>>> like [ALWAYS] or [TRUE]?
>>
>> Dropping a condition has to be considered very carefully, same as
>> introducing a new path without any condition.
>>
>> In worst case you can still go with [CONFIG_HYPFS].
> 
> Couldn’t we just have a section of the document for dead paths that aren’t allowed to be used?
> 
> Alternately, we could have a tag for entries we don’t want used anymore; [DEAD] or [OBSOLETE] maybe? [DEFUNCT]? [REMOVED]?
> 
> So I think I’d write a separate section, like this:
> 
> ~~
> # 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.
> ~~~
> 
> Thoughts?

Would work for me, too.


Juergen
George Dunlap July 20, 2020, 10:19 a.m. UTC | #10
> On Jul 16, 2020, at 3:34 PM, Jürgen Groß <jgross@suse.com> wrote:
> 
> On 16.07.20 16:20, George Dunlap wrote:
>>> On Jul 16, 2020, at 12:34 PM, Jürgen Groß <jgross@suse.com> wrote:
>>> 
>>> On 16.07.20 13:24, Jan Beulich wrote:
>>>> On 16.07.2020 12:31, Jürgen Groß wrote:
>>>>> On 16.07.20 12:11, Jan Beulich wrote:
>>>>>> On 15.07.2020 16:37, George Dunlap wrote:
>>>>>>> IT sounds like you’re saying:
>>>>>>> 
>>>>>>> 1. Paths listed without conditions will always be available
>>>>>>> 
>>>>>>> 2. Paths listed with conditions may be extended: i.e., a node currently listed as PV might also become available for HVM guests
>>>>>>> 
>>>>>>> 3. Paths listed with conditions might have those conditions reduced, but will never entirely disappear.  So something currently listed as PV might be reduced to CONFIG_HAS_FOO, but won’t be completely removed.
>>>>>>> 
>>>>>>> Is that what you meant?
>>>>>> 
>>>>>> I see Jürgen replied "yes" to this, but I'm not sure about 1.
>>>>>> above: I think it's quite reasonable to expect that paths without
>>>>>> condition may gain a condition. Just like paths now having a
>>>>>> condition and (perhaps temporarily) losing it shouldn't all of
>>>>>> the sudden become "always available" when they weren't meant to
>>>>>> be.
>>>>>> 
>>>>>> As far a 3. goes, I'm also unsure in how far this is any better
>>>>>> stability wise (from a consumer pov) than allowing paths to
>>>>>> entirely disappear.
>>>>> 
>>>>> The idea is that any user tool using hypfs can rely on paths under 1 to
>>>>> exist, while the ones under 3 might not be there due to the hypervisor
>>>>> config or the used system.
>>>>> 
>>>>> A path not being allowed to entirely disappear ensures that it remains
>>>>> in the documentation, so the same path can't be reused for something
>>>>> different in future.
>>>> And then how do you deal with a condition getting dropped, and
>>>> later wanting to get re-added? Do we need a placeholder condition
>>>> like [ALWAYS] or [TRUE]?
>>> 
>>> Dropping a condition has to be considered very carefully, same as
>>> introducing a new path without any condition.
>>> 
>>> In worst case you can still go with [CONFIG_HYPFS].
>> Couldn’t we just have a section of the document for dead paths that aren’t allowed to be used?
>> Alternately, we could have a tag for entries we don’t want used anymore; [DEAD] or [OBSOLETE] maybe? [DEFUNCT]? [REMOVED]?
>> So I think I’d write a separate section, like this:
>> ~~
>> # 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.
>> ~~~
>> Thoughts?
> 
> Would work for me, too.

So whose court is the ball in now?  Are you going to send another patch, or would you prefer I do it?

 -George
Jürgen Groß July 20, 2020, 11 a.m. UTC | #11
On 20.07.20 12:19, George Dunlap wrote:
> 
> 
>> On Jul 16, 2020, at 3:34 PM, Jürgen Groß <jgross@suse.com> wrote:
>>
>> On 16.07.20 16:20, George Dunlap wrote:
>>>> On Jul 16, 2020, at 12:34 PM, Jürgen Groß <jgross@suse.com> wrote:
>>>>
>>>> On 16.07.20 13:24, Jan Beulich wrote:
>>>>> On 16.07.2020 12:31, Jürgen Groß wrote:
>>>>>> On 16.07.20 12:11, Jan Beulich wrote:
>>>>>>> On 15.07.2020 16:37, George Dunlap wrote:
>>>>>>>> IT sounds like you’re saying:
>>>>>>>>
>>>>>>>> 1. Paths listed without conditions will always be available
>>>>>>>>
>>>>>>>> 2. Paths listed with conditions may be extended: i.e., a node currently listed as PV might also become available for HVM guests
>>>>>>>>
>>>>>>>> 3. Paths listed with conditions might have those conditions reduced, but will never entirely disappear.  So something currently listed as PV might be reduced to CONFIG_HAS_FOO, but won’t be completely removed.
>>>>>>>>
>>>>>>>> Is that what you meant?
>>>>>>>
>>>>>>> I see Jürgen replied "yes" to this, but I'm not sure about 1.
>>>>>>> above: I think it's quite reasonable to expect that paths without
>>>>>>> condition may gain a condition. Just like paths now having a
>>>>>>> condition and (perhaps temporarily) losing it shouldn't all of
>>>>>>> the sudden become "always available" when they weren't meant to
>>>>>>> be.
>>>>>>>
>>>>>>> As far a 3. goes, I'm also unsure in how far this is any better
>>>>>>> stability wise (from a consumer pov) than allowing paths to
>>>>>>> entirely disappear.
>>>>>>
>>>>>> The idea is that any user tool using hypfs can rely on paths under 1 to
>>>>>> exist, while the ones under 3 might not be there due to the hypervisor
>>>>>> config or the used system.
>>>>>>
>>>>>> A path not being allowed to entirely disappear ensures that it remains
>>>>>> in the documentation, so the same path can't be reused for something
>>>>>> different in future.
>>>>> And then how do you deal with a condition getting dropped, and
>>>>> later wanting to get re-added? Do we need a placeholder condition
>>>>> like [ALWAYS] or [TRUE]?
>>>>
>>>> Dropping a condition has to be considered very carefully, same as
>>>> introducing a new path without any condition.
>>>>
>>>> In worst case you can still go with [CONFIG_HYPFS].
>>> Couldn’t we just have a section of the document for dead paths that aren’t allowed to be used?
>>> Alternately, we could have a tag for entries we don’t want used anymore; [DEAD] or [OBSOLETE] maybe? [DEFUNCT]? [REMOVED]?
>>> So I think I’d write a separate section, like this:
>>> ~~
>>> # 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.
>>> ~~~
>>> Thoughts?
>>
>> Would work for me, too.
> 
> So whose court is the ball in now?  Are you going to send another patch, or would you prefer I do it?

I can do it. I just hoped that maybe someone else would agree to this
approach.


Juergen
diff mbox series

Patch

diff --git a/docs/misc/hypfs-paths.pandoc b/docs/misc/hypfs-paths.pandoc
index a111c6f25c..00a7cec031 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.
@@ -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.
 
+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. A path once assigned meaning won't go
+away altogether or change its meaning, though.
+
 So an entry could look like this:
 
     /cpu-bugs/active-pv/xpti = ("No"|{"dom0", "domU", "PCID-on"}) [w,X86,PV]