[Linaro-uefi,v2] docs/arm64: update the documention for loading XSM support

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

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.

Signed-off-by: Fu Wei <fu.wei@linaro.org>
---
v2: Improve the doc, according to the suggestion from Julien Grall.

v1: http://lists.xen.org/archives/html/xen-devel/2016-04/msg02070.html
    The first upstream version submitted in xen-devel mailing list.

 docs/misc/arm/device-tree/booting.txt | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

(CC Wei for the release-ack)

Hi Fu Wei,

On 21/04/16 12:07, fu.wei@linaro.org wrote:
> From: Fu Wei <fu.wei@linaro.org>
>
> 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.
>
> Signed-off-by: Fu Wei <fu.wei@linaro.org>

The new version looks good to me:

Acked-by: Julien Grall <julien.grall@arm.com>

Can a native speaker (Ian, Konrad, George) double-check the wording)?

Wei, this patch only update the doc. I am not sure whether we need your 
release-ack.

Regards,

> ---
> v2: Improve the doc, according to the suggestion from Julien Grall.
>
> v1: http://lists.xen.org/archives/html/xen-devel/2016-04/msg02070.html
>      The first upstream version submitted in xen-devel mailing list.
>
>   docs/misc/arm/device-tree/booting.txt | 22 ++++++++++++++++++----
>   1 file changed, 18 insertions(+), 4 deletions(-)
>
> diff --git a/docs/misc/arm/device-tree/booting.txt b/docs/misc/arm/device-tree/booting.txt
> index ad98bf3..254ba77 100644
> --- a/docs/misc/arm/device-tree/booting.txt
> +++ b/docs/misc/arm/device-tree/booting.txt
> @@ -24,10 +24,24 @@ 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 check all the modules for the XSM Magic from the second
> +	module that lacks a specific compatible string. According to the
> +	result of the detection:
> +	- if it's a XSM, Xen will assume its compatible string is a
> +	  "xen,xsm-policy";
> +	- if it's not a XSM, for the second module that lacks a specific
> +	  compatible string, Xen will assume its compatible string is a
> +	  "multiboot,ramdisk"; for the third and subsequent modules those
> +	  lacks a specific compatible string will not receive any special
> +	  treatment.
> +	This means if the ramdisk module is present and does not have the
> +	compatible string "multiboot,ramdisk", then it must always be the
> +	second module.
> +	Note: This XSM Magic detection behavior was introduced by Xen 4.7.
> +	Xen 4.6 (and downwards) still requires the XSM module to have the
> +	compatible string "xen,xsm-policy".
>
>   	Xen 4.4 supported a different set of legacy compatible strings
>   	which remain supported such that systems supporting both 4.4
>

Sorry, I forgot to mention the typo in the title:

s/documention/documentation/

On 22/04/16 17:40, Julien Grall wrote:
> (CC Wei for the release-ack)
>
> Hi Fu Wei,
>
> On 21/04/16 12:07, fu.wei@linaro.org wrote:
>> From: Fu Wei <fu.wei@linaro.org>
>>
>> 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.
>>
>> Signed-off-by: Fu Wei <fu.wei@linaro.org>
>
> The new version looks good to me:
>
> Acked-by: Julien Grall <julien.grall@arm.com>
>
> Can a native speaker (Ian, Konrad, George) double-check the wording)?
>
> Wei, this patch only update the doc. I am not sure whether we need your
> release-ack.
>
> Regards,
>
>> ---
>> v2: Improve the doc, according to the suggestion from Julien Grall.
>>
>> v1: http://lists.xen.org/archives/html/xen-devel/2016-04/msg02070.html
>>      The first upstream version submitted in xen-devel mailing list.
>>
>>   docs/misc/arm/device-tree/booting.txt | 22 ++++++++++++++++++----
>>   1 file changed, 18 insertions(+), 4 deletions(-)
>>
>> diff --git a/docs/misc/arm/device-tree/booting.txt
>> b/docs/misc/arm/device-tree/booting.txt
>> index ad98bf3..254ba77 100644
>> --- a/docs/misc/arm/device-tree/booting.txt
>> +++ b/docs/misc/arm/device-tree/booting.txt
>> @@ -24,10 +24,24 @@ 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 check all the modules for the XSM Magic from the second
>> +    module that lacks a specific compatible string. According to the
>> +    result of the detection:
>> +    - if it's a XSM, Xen will assume its compatible string is a
>> +      "xen,xsm-policy";
>> +    - if it's not a XSM, for the second module that lacks a specific
>> +      compatible string, Xen will assume its compatible string is a
>> +      "multiboot,ramdisk"; for the third and subsequent modules those
>> +      lacks a specific compatible string will not receive any special
>> +      treatment.
>> +    This means if the ramdisk module is present and does not have the
>> +    compatible string "multiboot,ramdisk", then it must always be the
>> +    second module.
>> +    Note: This XSM Magic detection behavior was introduced by Xen 4.7.
>> +    Xen 4.6 (and downwards) still requires the XSM module to have the
>> +    compatible string "xen,xsm-policy".
>>
>>       Xen 4.4 supported a different set of legacy compatible strings
>>       which remain supported such that systems supporting both 4.4
>>
>

Hi Ian,

On 22/04/16 18:29, Ian Jackson wrote:
> Julien Grall writes ("Re: [PATCH v2] docs/arm64: update the documention for loading XSM support"):
>> The new version looks good to me:
>> Acked-by: Julien Grall <julien.grall@arm.com>
>>
>> Can a native speaker (Ian, Konrad, George) double-check the wording)?
>
> I found it rather difficult to read.  See updated version, attached.

Stefano has committed the previous version with some modifications. Is 
it better to read?

Regards,

Hi Jan,

On 21 April 2016 at 19:40, Jan Beulich <JBeulich@suse.com> wrote:
>>>> On 21.04.16 at 13:07, <fu.wei@linaro.org> wrote:
>
> Please follow the patch submission rules: Mail them _to_ the list,
> _cc_-ing relevant people. Cc-ing the list twice makes little sense.
> And please also apply some common sense when deciding who to
> Cc - I don't think there's much point in Cc-ing other than ARM
> maintainers on ARM specific doc patches (arguably that should be
> reflected in ./MAINTAINERS).

Sorry for late response,
Thanks for your help, will fix my script :-)

>
> Jan
>

Hi All,

Great thanks for  all your help :-)

On 25 April 2016 at 23:25, Stefano Stabellini <sstabellini@kernel.org> wrote:
> On Mon, 25 Apr 2016, Ian Jackson wrote:
>> Julien Grall writes ("Re: [PATCH v3] docs/arm64: update the documention for loading XSM support"):
>> > Stefano has committed the previous version with some modifications. Is
>> > it better to read?
>>
>> IMO it is better than the original but I still think my proposed
>> wording is an improvement over Stefano's.
>>
>> Should I "rebase" it and resubmit ?
>
> Sure, thanks.