Re: [PATCH 1/1] doc: clarify intended usage of ~/control/ xentore path

[Julien Grall <julien@xxxxxxx>]

Hi Yann,

Adding Juergen.

On 31/05/2023 11:35, Yann Dirson wrote:
> Signed-off-by: Yann Dirson <yann.dirson@xxxxxxxx>
Reviewed-by: Julien Grall <jgrall@xxxxxxxxxx>

Cheers,

> ---
>   docs/misc/xenstore-paths.pandoc | 29 +++++++++++++++++++++++++++++
>   1 file changed, 29 insertions(+)
>
> diff --git a/docs/misc/xenstore-paths.pandoc b/docs/misc/xenstore-paths.pandoc
> index f07ef90f63..5501033893 100644
> --- a/docs/misc/xenstore-paths.pandoc
> +++ b/docs/misc/xenstore-paths.pandoc
> @@ -432,6 +432,35 @@ by udev ("0") or will be run by the toolstack directly 
> ("1").
>   
>   ### Platform Feature and Control Paths
>   
> +#### ~/control = "" []
> +
> +Directory to hold feature and control paths.  This directory is not
> +guest-writable, only the toolstack is allowed to create new child
> +nodes under this.
> +
> +Children of this nodes can have one of several types:
> +
> +* platform features: using name pattern `platform-feature-*`, they may
> +  be set by the toolstack to inform the guest, and are not writable by
> +  the guest.
> +
> +* guest features: using name pattern `feature-*`, they may be created
> +  by the toolstack with an empty value (`""`), should be set writable
> +  by the guest which can then advertize to the toolstack its
> +  (non-)usage of the feature with values `"0"` and `"1"` respectively.
> +  The lack of update by the guest can be interpreted by the toolstack
> +  as the lack of supporting software (PV driver, guest agent, ...) in
> +  the guest.
> +
> +* control nodes: using any name not matching the above pattern, they
> +  are used by the toolstack or by the guest to signal a specific
> +  condition to the other end, which is expected to watch it to react
> +  to changes.
> +
> +Note: the presence of a control node in itself advertises the
> +underlying toolstack feature, it is not necessary to add an extra
> +platform-feature for such cases.
> +
>   #### ~/control/sysrq = (""|COMMAND) [w]
>   
>   This is the PV SysRq control node. A toolstack can write a single character
--
Julien Grall