[2/2] zynq: document how to use custom ps7_init files

Since U-Boot supported SPL for Zynq boards at v2014.04 release, it
became much easier to build a system.  At that time, however, users
still needed to manually copy ps7_init.c/h to the U-Boot source tree
to generate a working SPL image because ps7_init.c/h output from
Xilinx tools are not compatible with GPL.

Later, the license problem was solved when Xilinx tools became able
to output the GPL-compatible variants (ps7_init_gpl.c/h) as well.
U-Boot v2015.07 or later includes ps7_init_gpl.c/h for major Zynq
boards so that users can build a boot image straight away.

Now Buildroot supports 3 boards (Zedboard, MicroZed, ZC706) without
any manual intervention.  This is a good thing itself, but commit
b9cd72cdbfe3 ("zynq_zc706: bump U-Boot to xilinx-v2016.2") entirely
dropped the information about custom ps7_init files.

This commit provides up-to-date guidance for how to customize the
ps7_init files.

Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
---

 board/zynq/readme.txt | 44 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 37 insertions(+), 7 deletions(-)

Masahiro,

On Sun, Jul 31, 2016 at 12:43 AM, Masahiro Yamada
<yamada.masahiro@socionext.com> wrote:
> Since U-Boot supported SPL for Zynq boards at v2014.04 release, it
> became much easier to build a system.  At that time, however, users
> still needed to manually copy ps7_init.c/h to the U-Boot source tree
> to generate a working SPL image because ps7_init.c/h output from
> Xilinx tools are not compatible with GPL.
>
> Later, the license problem was solved when Xilinx tools became able
> to output the GPL-compatible variants (ps7_init_gpl.c/h) as well.
> U-Boot v2015.07 or later includes ps7_init_gpl.c/h for major Zynq
> boards so that users can build a boot image straight away.
>
> Now Buildroot supports 3 boards (Zedboard, MicroZed, ZC706) without
> any manual intervention.  This is a good thing itself, but commit
> b9cd72cdbfe3 ("zynq_zc706: bump U-Boot to xilinx-v2016.2") entirely
> dropped the information about custom ps7_init files.
>
> This commit provides up-to-date guidance for how to customize the
> ps7_init files.
>
> Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
> ---
>
>  board/zynq/readme.txt | 44 +++++++++++++++++++++++++++++++++++++-------
>  1 file changed, 37 insertions(+), 7 deletions(-)
>
> diff --git a/board/zynq/readme.txt b/board/zynq/readme.txt
> index 51e28b6..debb163 100644
> --- a/board/zynq/readme.txt
> +++ b/board/zynq/readme.txt
> @@ -6,13 +6,6 @@ Currently, three boards are natively supported by Buildroot:
>   - Avnet ZedBoard (zynq_zed_defconfig)
>   - Avnet MicroZed (zynq_microzed_defconfig)

Did you mean to remove the previous two lines?

>
> -The following build procedure focuses on them, but you can adjust it to your
> -board even if it is not listed above.  Major Zynq-based boards are supported by
> -U-Boot, and their Device Trees are merged in Linux Kernel.  If your board is the
> -case, booting the kernel is a piece of cake.  All you need to do is to change:
> - - Kernel Device Tree file name (BR2_LINUX_KERNEL_INTREE_DTS_NAME)
> - - U-Boot board defconfig (BR2_TARGET_UBOOT_BOARD_KCONFIG)
> -
>  Steps to create a working system for a Zynq board:
>
>  1) Configuration (do one of the following)
> @@ -50,3 +43,40 @@ References:
>
>   - Zedboard/Microzed information including schematics, reference designs, and
>     manuals are available from http://www.zedboard.org .

Did you mean to remove this line?

> +
> +Support for other boards:
> +
> +You may want to build a system for other boards (for ex. Digilent Zybo board).

Reword:
If you want to build a system for other boards.....

> +U-Boot supports major Zynq-based boards, and their Device Trees are mostly
> +merged in Linux Kernel.  If your board is the case, booting the kernel is a
> +piece of cake.  All you need to do is to tweak:

Reword:
Most major Zynq-based boards have U-Boot and Kernel support.  If your
board happens to be supported, booting the kernel and using U-Boot
just requires the following Buildroot updates:

> + - Kernel Device Tree file name (BR2_LINUX_KERNEL_INTREE_DTS_NAME)
> + - U-Boot board defconfig (BR2_TARGET_UBOOT_BOARD_DEFCONFIG)
> +
> +Custom ps7_init_gpl.c/h support:
> +
> +To generate a working boot.bin image, ps7_init_gpl.c/h are required in the
> +U-Boot source tree.  Those files are output from the Xilinx tools, but for
> +convenience, U-Boot includes the default ps7_init_gpl.c/h of popular boards.

Please add the following sentence:
These files may need to be updated for any programmable logic
customizations which impact ps7_init (clock/pin setup & mapping/AXI
bridge setup/etc).

> +See board/xilinx/zynq/ directory of U-Boot for natively supported ps7_init
> +files.  If the ps7_init files for your board are not found in U-Boot, you need
> +to add them by yourself.  (You can still override the existing ones if you want
> +to customize them for your purpose.)
> +
> +1) Start with a defconfig supported by Buildroot (for ex. Zedboard)
> +    make zynq_zed_defconfig
> +
> +2) make uboot-menuconfig
> +    Visit the following menu and enable CONFIG_ZYNQ_CUSTOM_INIT.
> +
> +    ARM architecture  --->
> +       [*] Use custom ps7_init provided by Xilinx tool
> +
> +3) Copy ps7_init_gpl.c/h generated by the Xilinx tools into
> +   output/build/uboot-xilinx-v2016.2/board/xilinx/zynq/custom_hw_platform/

Update:
 output/build/uboot-xilinx-<pkg version>/board/xilinx/zynq/custom_hw_platform/

> +
> +4) make
> +
> +*Notice*
> +While the build will successfully complete with/without the ps7_init_gpl.*
> +files, the boot.bin generated without ones will not be functional at all.
> --
> 1.9.1
>

Otherwise looks good, care to update for a v2?

Hi Matthew,

Thanks for your comments!


2016-08-02 11:10 GMT+09:00 Matthew Weber <matthew.weber@rockwellcollins.com>:
> Masahiro,
>
> On Sun, Jul 31, 2016 at 12:43 AM, Masahiro Yamada
> <yamada.masahiro@socionext.com> wrote:
>> Since U-Boot supported SPL for Zynq boards at v2014.04 release, it
>> became much easier to build a system.  At that time, however, users
>> still needed to manually copy ps7_init.c/h to the U-Boot source tree
>> to generate a working SPL image because ps7_init.c/h output from
>> Xilinx tools are not compatible with GPL.
>>
>> Later, the license problem was solved when Xilinx tools became able
>> to output the GPL-compatible variants (ps7_init_gpl.c/h) as well.
>> U-Boot v2015.07 or later includes ps7_init_gpl.c/h for major Zynq
>> boards so that users can build a boot image straight away.
>>
>> Now Buildroot supports 3 boards (Zedboard, MicroZed, ZC706) without
>> any manual intervention.  This is a good thing itself, but commit
>> b9cd72cdbfe3 ("zynq_zc706: bump U-Boot to xilinx-v2016.2") entirely
>> dropped the information about custom ps7_init files.
>>
>> This commit provides up-to-date guidance for how to customize the
>> ps7_init files.
>>
>> Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
>> ---
>>
>>  board/zynq/readme.txt | 44 +++++++++++++++++++++++++++++++++++++-------
>>  1 file changed, 37 insertions(+), 7 deletions(-)
>>
>> diff --git a/board/zynq/readme.txt b/board/zynq/readme.txt
>> index 51e28b6..debb163 100644
>> --- a/board/zynq/readme.txt
>> +++ b/board/zynq/readme.txt
>> @@ -6,13 +6,6 @@ Currently, three boards are natively supported by Buildroot:
>>   - Avnet ZedBoard (zynq_zed_defconfig)
>>   - Avnet MicroZed (zynq_microzed_defconfig)
>
> Did you mean to remove the previous two lines?


No.  '-' is for itemization.



>>
>> -The following build procedure focuses on them, but you can adjust it to your
>> -board even if it is not listed above.  Major Zynq-based boards are supported by
>> -U-Boot, and their Device Trees are merged in Linux Kernel.  If your board is the
>> -case, booting the kernel is a piece of cake.  All you need to do is to change:
>> - - Kernel Device Tree file name (BR2_LINUX_KERNEL_INTREE_DTS_NAME)
>> - - U-Boot board defconfig (BR2_TARGET_UBOOT_BOARD_KCONFIG)
>> -
>>  Steps to create a working system for a Zynq board:
>>
>>  1) Configuration (do one of the following)
>> @@ -50,3 +43,40 @@ References:
>>
>>   - Zedboard/Microzed information including schematics, reference designs, and
>>     manuals are available from http://www.zedboard.org .
>
> Did you mean to remove this line?

Not at all.
I think the patch format is not broken
because this was sent by "git send-email".


> Otherwise looks good, care to update for a v2?



I am OK with all the suggestions for reword.


If you do not mind, I'd like to hand over this to you.
Could you rephrase them in a way you think better, and send v2 please?

I am not a native English speaker and I believe you will do a better job.