[PATCH] docs/arm64: update the documention for loading XSM support

[PATCH] docs/arm64: update the documention for loading XSM support

[fu.wei]

From: Fu Wei <fu.wei@linaro.org>

This patch updates the documention for loading XSM by the module which
lacks a specific compatible string. This mechanism has been added by the
commit ca32012341f3de7d3975407fb963e6028f0d0c8b

Signed-off-by: Fu Wei <fu.wei@linaro.org>
---
 docs/misc/arm/device-tree/booting.txt | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/docs/misc/arm/device-tree/booting.txt b/docs/misc/arm/device-tree/booting.txt
index ad98bf3..f45a9c4 100644
--- a/docs/misc/arm/device-tree/booting.txt
+++ b/docs/misc/arm/device-tree/booting.txt
@@ -24,10 +24,19 @@ Each node contains the following properties:
 	string (which must always be present).
 
 	Xen will assume that the first module which lacks a more
-	specific compatible string is a "multiboot,kernel" and that
-	the second such is a "multiboot,ramdisk". Any subsequent
-	modules which lack a specific compatiblity string will not
-	receive any special treatment.
+	specific compatible string is a "multiboot,kernel". Xen will
+	detect the XSM magic from the second module which lacks of
+	a specific compatiblity string:
+	- if it's XSM, Xen will assume that the second such is a
+	"xen,xsm-policy". and also assume user won't load ramdisk;
+	- if it's not XSM, Xen will assume that the second such is a
+	"multiboot,ramdisk".
+	So if user want to load ramdisk without a specific compatiblity,
+	it must	be the 2nd one.
+	Xen will also detect the XSM Magic for the following modules
+	which lack of a specific compatiblity, and assume that the module
+	is a "xen,xsm-policy" or "multiboot,module", according to the
+	result of detection.
 
 	Xen 4.4 supported a different set of legacy compatible strings
 	which remain supported such that systems supporting both 4.4
-- 
2.5.5


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] docs/arm64: update the documention for loading XSM support

[Julien Grall]

Hello Fu Wei,

On 14/04/16 18:06, fu.wei@linaro.org wrote:
> From: Fu Wei <fu.wei@linaro.org>
>
> This patch updates the documention for loading XSM by the module which
 > lacks a specific compatible string.

s/documention/documentation/
s/which/that/

The sentence is not clear to me. I would rephrase:

"This patch updates the documentation for allowing detection of an XSM 
module that lacks a specific compatible string".

 > This mechanism has been added by the
> commit ca32012341f3de7d3975407fb963e6028f0d0c8b

Missing full stop.

>
> Signed-off-by: Fu Wei <fu.wei@linaro.org>
> ---
>   docs/misc/arm/device-tree/booting.txt | 17 +++++++++++++----
>   1 file changed, 13 insertions(+), 4 deletions(-)
>
> diff --git a/docs/misc/arm/device-tree/booting.txt b/docs/misc/arm/device-tree/booting.txt
> index ad98bf3..f45a9c4 100644
> --- a/docs/misc/arm/device-tree/booting.txt
> +++ b/docs/misc/arm/device-tree/booting.txt
> @@ -24,10 +24,19 @@ Each node contains the following properties:
>   	string (which must always be present).
>
>   	Xen will assume that the first module which lacks a more
> -	specific compatible string is a "multiboot,kernel" and that
> -	the second such is a "multiboot,ramdisk". Any subsequent
> -	modules which lack a specific compatiblity string will not
> -	receive any special treatment.
> +	specific compatible string is a "multiboot,kernel". Xen will
> +	detect the XSM magic from the second module which lacks of
> +	a specific compatiblity string:

s/compatiblity/

The sentence is not clear. You could read as: "Xen will check all the 
modules from the second module that lacks a specific compatible string".

I.e Xen will do the XSM magic check even if the module has a specific 
compatible string.

I would instead say "For the second module that lacks a specific 
compatible string, Xen will check if the module is a XSM policy:

> +	- if it's XSM, Xen will assume that the second such is a

"second such" is not clear.

> +	"xen,xsm-policy". and also assume user won't load ramdisk;

s/.//

I would drop the rest of the sentence after "and".

> +	- if it's not XSM, Xen will assume that the second such is a

"second such" is not clear.

> +	"multiboot,ramdisk".
> +	So if user want to load ramdisk without a specific compatiblity,

s/user/the user/
s/compatiblity/compatibility/

However this is a documentation for the user. So I would say "This means 
that if the ramdisk module is present and does not have a the compatible 
string "multiboot,ramdisk", then it must be always the second module".

> +	it must	be the 2nd one.
> +	Xen will also detect the XSM Magic for the following modules
> +	which lack of a specific compatiblity, and assume that the module

s/compatiblity/compatibility/

> +	is a "xen,xsm-policy" or "multiboot,module", according to the
> +	result of detection.

s/or/or a/
s/detection/the detection/

I would also invert the two paragraphs. I.e inverting "So if user.." and 
"Xen will...".

Can you also mention that this behavior was introduced by Xen 4.7. I.e 
Xen 4.6 (and downwards) still requires the module to have the compatible 
string "xen,xsm-policy" and therefore XSM won't work with GRUB.

The latter bits may need to be documented in GRUB.

>
>   	Xen 4.4 supported a different set of legacy compatible strings
>   	which remain supported such that systems supporting both 4.4
>

Regards,

-- 
Julien Grall

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] docs/arm64: update the documention for loading XSM support

[Fu Wei]

Hi Julien,

Great thanks for your review and suggestion.
I have taken almost all your suggestion, but did some modification,
please have a look:
http://lists.xen.org/archives/html/xen-devel/2016-04/msg02637.html

Thanks for your help! :-)

On 20 April 2016 at 19:27, Julien Grall <julien.grall@arm.com> wrote:
> Hello Fu Wei,
>
> On 14/04/16 18:06, fu.wei@linaro.org wrote:
>>
>> From: Fu Wei <fu.wei@linaro.org>
>>
>> This patch updates the documention for loading XSM by the module which
>
>> lacks a specific compatible string.
>
> s/documention/documentation/
> s/which/that/
>
> The sentence is not clear to me. I would rephrase:
>
> "This patch updates the documentation for allowing detection of an XSM
> module that lacks a specific compatible string".
>
>> This mechanism has been added by the
>>
>> commit ca32012341f3de7d3975407fb963e6028f0d0c8b
>
>
> Missing full stop.
>
>>
>> Signed-off-by: Fu Wei <fu.wei@linaro.org>
>> ---
>>   docs/misc/arm/device-tree/booting.txt | 17 +++++++++++++----
>>   1 file changed, 13 insertions(+), 4 deletions(-)
>>
>> diff --git a/docs/misc/arm/device-tree/booting.txt
>> b/docs/misc/arm/device-tree/booting.txt
>> index ad98bf3..f45a9c4 100644
>> --- a/docs/misc/arm/device-tree/booting.txt
>> +++ b/docs/misc/arm/device-tree/booting.txt
>> @@ -24,10 +24,19 @@ Each node contains the following properties:
>>         string (which must always be present).
>>
>>         Xen will assume that the first module which lacks a more
>> -       specific compatible string is a "multiboot,kernel" and that
>> -       the second such is a "multiboot,ramdisk". Any subsequent
>> -       modules which lack a specific compatiblity string will not
>> -       receive any special treatment.
>> +       specific compatible string is a "multiboot,kernel". Xen will
>> +       detect the XSM magic from the second module which lacks of
>> +       a specific compatiblity string:
>
>
> s/compatiblity/
>
> The sentence is not clear. You could read as: "Xen will check all the
> modules from the second module that lacks a specific compatible string".
>
> I.e Xen will do the XSM magic check even if the module has a specific
> compatible string.
>
> I would instead say "For the second module that lacks a specific compatible
> string, Xen will check if the module is a XSM policy:
>
>> +       - if it's XSM, Xen will assume that the second such is a
>
>
> "second such" is not clear.
>
>> +       "xen,xsm-policy". and also assume user won't load ramdisk;
>
>
> s/.//
>
> I would drop the rest of the sentence after "and".
>
>> +       - if it's not XSM, Xen will assume that the second such is a
>
>
> "second such" is not clear.
>
>> +       "multiboot,ramdisk".
>> +       So if user want to load ramdisk without a specific compatiblity,
>
>
> s/user/the user/
> s/compatiblity/compatibility/
>
> However this is a documentation for the user. So I would say "This means
> that if the ramdisk module is present and does not have a the compatible
> string "multiboot,ramdisk", then it must be always the second module".
>
>> +       it must be the 2nd one.
>> +       Xen will also detect the XSM Magic for the following modules
>> +       which lack of a specific compatiblity, and assume that the module
>
>
> s/compatiblity/compatibility/
>
>> +       is a "xen,xsm-policy" or "multiboot,module", according to the
>> +       result of detection.
>
>
> s/or/or a/
> s/detection/the detection/
>
> I would also invert the two paragraphs. I.e inverting "So if user.." and
> "Xen will...".
>
> Can you also mention that this behavior was introduced by Xen 4.7. I.e Xen
> 4.6 (and downwards) still requires the module to have the compatible string
> "xen,xsm-policy" and therefore XSM won't work with GRUB.
>
> The latter bits may need to be documented in GRUB.
>
>>
>>         Xen 4.4 supported a different set of legacy compatible strings
>>         which remain supported such that systems supporting both 4.4
>>
>
> Regards,
>
> --
> Julien Grall



-- 
Best regards,

Fu Wei
Software Engineer
Red Hat Software (Beijing) Co.,Ltd.Shanghai Branch
Ph: +86 21 61221326(direct)
Ph: +86 186 2020 4684 (mobile)
Room 1512, Regus One Corporate Avenue,Level 15,
One Corporate Avenue,222 Hubin Road,Huangpu District,
Shanghai,China 200021

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel