[xen master] docs: fix INTRODUCE description in xenstore.txt

[patchbot@xxxxxxx]

commit 56b237263b33451aae46115729f97d8a110c6b5d
Author:     Juergen Gross <jgross@xxxxxxxx>
AuthorDate: Thu Mar 6 08:47:52 2025 +0100
Commit:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
CommitDate: Mon Mar 10 15:05:09 2025 +0000

    docs: fix INTRODUCE description in xenstore.txt
    
    The description of the Xenstore INTRODUCE command is still referencing
    xend. Fix that.
    
    The <evtchn> description is starting with a grammatically wrong
    sentence. Fix that.
    
    While at it, make clear that the Xenstore implementation is allowed
    to ignore the specified gfn and use the Xenstore reserved grant id
    GNTTAB_RESERVED_XENSTORE instead.
    
    Signed-off-by: Juergen Gross <jgross@xxxxxxxx>
    Reviewed-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
---
 docs/misc/xenstore.txt | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
index 38015835b1..7e1f031520 100644
--- a/docs/misc/xenstore.txt
+++ b/docs/misc/xenstore.txt
@@ -286,19 +286,32 @@ TRANSACTION_END           F|
 INTRODUCE              <domid>|<gfn>|<evtchn>|?
        Notifies xenstored to communicate with this domain.
 
-       INTRODUCE is currently only used by xend (during domain
+       INTRODUCE is currently only used by xen tools (during domain
        startup and various forms of restore and resume), and
        xenstored prevents its use other than by dom0.
 
        <domid> must be a real domain id (not 0 and not a special
        DOMID_... value).  <gfn> must be a page in that domain
-       represented in signed decimal (!).  <evtchn> must be event
-       channel is an unbound event channel in <domid> (likewise in
-       decimal), on which xenstored will call bind_interdomain.
+       represented in signed decimal (!).  <evtchn> is an unbound
+       event channel in <domid> (likewise in decimal), on which
+       xenstored will call bind_interdomain.
+
        Violations of these rules may result in undefined behaviour;
        for example passing a high-bit-set 32-bit gfn as an unsigned
        decimal will attempt to use 0x7fffffff instead (!).
 
+       The <gfn> field is used by xenstoreds which use foreign
+       mapping to access the ring page.
+
+       Alternatively, Grant 1 (GNTTAB_RESERVED_XENSTORE) is reserved
+       for the same purpose, and is populated by the domain builder
+       on behalf of the guest.  This mechanism is preferred because
+       it reduces the permissions that xenstored needs in order to
+       function.
+
+       Both <gfn> and Grant 1 need to agree, because implementations
+       of xenstored will use one and ignore the other.
+
 RELEASE                        <domid>|
        Manually requests that xenstored disconnect from the domain.
        The event channel is unbound at the xenstored end and the page
--
generated by git-patchbot for /home/xen/git/xen.git#master