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@suse.com>
Reviewed-by: Andrew Cooper <andrew.cooper3@citrix.com>

diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
index 38015835b1e0139162f6f34e9f1be9eb65801679..7e1f031520b6a8ae0802e09c9c704750b26716ad 100644 (file)
--- 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