> On Jul 16, 2020, at 12:34 PM, Jürgen Groß <jgr...@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
