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

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