RE: [PATCH v3] docs: specify stability of hypfs path documentation

[Paul Durrant <xadimgnik@xxxxxxxxx>]

> -----Original Message-----
> From: Juergen Gross <jgross@xxxxxxxx>
> Sent: 20 July 2020 12:22
> To: xen-devel@xxxxxxxxxxxxxxxxxxxx
> Cc: paul@xxxxxxx; Juergen Gross <jgross@xxxxxxxx>; Andrew Cooper 
> <andrew.cooper3@xxxxxxxxxx>; George
> Dunlap <george.dunlap@xxxxxxxxxx>; Ian Jackson <ian.jackson@xxxxxxxxxxxxx>; 
> Jan Beulich
> <jbeulich@xxxxxxxx>; Julien Grall <julien@xxxxxxx>; Stefano Stabellini 
> <sstabellini@xxxxxxxxxx>; Wei
> Liu <wl@xxxxxxx>
> Subject: [PATCH v3] 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).
> 
> Signed-off-by: Juergen Gross <jgross@xxxxxxxx>
> Release-acked-by: Paul Durrant <paul@xxxxxxx>

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

  Paul

> ---
> 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(+)
> 
> diff --git a/docs/misc/hypfs-paths.pandoc b/docs/misc/hypfs-paths.pandoc
> index a111c6f25c..68d83d9245 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.
> @@ -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