[v1] docs: fix INTRODUCE description in xenstore.txt

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

Posted by Juergen Gross 4 days, 5 hours ago

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@suse.com>
---
 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.
+
 RELEASE			<domid>|
 	Manually requests that xenstored disconnect from the domain.
 	The event channel is unbound at the xenstored end and the page
-- 
2.43.0

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

Posted by Andrew Cooper 3 days, 15 hours ago

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@suse.com>
> ---
>  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.
---

~Andrew

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

Posted by Jürgen Groß 3 days, 7 hours ago

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@suse.com>
>> ---
>>   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.


Juergen

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

Posted by Andrew Cooper 2 days, 14 hours ago

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@suse.com>
>>> ---
>>>   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

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

Posted by Andrii Sultanov 4 days, 2 hours ago

Unrelated to the contents of this patch, but talking about docs/misc/xenstore.txt:
it also mentions GET/SET_QUOTA calls, but these are not part of the xs_wire.h,
and instead can only be used as sub-arguments to CONTROL calls.

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

Posted by Jürgen Groß 4 days, 2 hours ago

On 05.03.25 13:13, Andrii Sultanov wrote:
> Unrelated to the contents of this patch, but talking about docs/misc/xenstore.txt:
> it also mentions GET/SET_QUOTA calls, but these are not part of the xs_wire.h,
> and instead can only be used as sub-arguments to CONTROL calls.
> 

I have a patch series in work adding those, plus the functionality in
xenstored and xl/libxl.

If wanted I can post the xs_wire.h patch before the rest of the series.

Juergen