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

[Yann Dirson <yann.dirson@xxxxxxxx>]

Signed-off-by: Yann Dirson <yann.dirson@xxxxxxxx>
---
 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
-- 
2.30.2



Yann Dirson | Vates Platform Developer

XCP-ng & Xen Orchestra - Vates solutions
w: vates.fr | xcp-ng.org | xen-orchestra.com