Re: [PATCH] docs: fix INTRODUCE description in xenstore.txt

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 06/03/2025 7:09 am, Jürgen Groß wrote:
> On 05.03.25 23:57, Andrew Cooper wrote:
>> On 05/03/2025 8:52 am, Juergen Gross wrote:
>>> The description of the Xenstore INTRODUCE command is still referencing
>>> xend. 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>
>>> ---
>>>   docs/misc/xenstore.txt | 6 +++++-
>>>   1 file changed, 5 insertions(+), 1 deletion(-)
>>>
>>> diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
>>> index 38015835b1..d894d24d11 100644
>>> --- a/docs/misc/xenstore.txt
>>> +++ b/docs/misc/xenstore.txt
>>> @@ -286,7 +286,7 @@ 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.
>>>   @@ -299,6 +299,10 @@ INTRODUCE        <domid>|<gfn>|<evtchn>|?
>>>       for example passing a high-bit-set 32-bit gfn as an unsigned
>>>       decimal will attempt to use 0x7fffffff instead (!).
>>>   +    Xenstored might ignore the <gfn> value and use the reserved
>>> +    grant table entry GNTTAB_RESERVED_XENSTORE instead for mapping
>>> +    the Xenstore interface page of the guest.
>>
>> I'd suggest making a stronger statement than this.
>>
>> ---
>> 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 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.
>
> Fine with me.

Are you happy for me to adjust on commit, or do you want a v2 sending out?

~Andrew