[v2] colibri_imx7: add readme.rst doc

From: Igor Opaniuk <igor.opaniuk@toradex.com>

Add initial readme.rst file which provides all needed information
for obtaining a workable image ready for flashing
for both eMMC/NAND versions of Colibri iMX7.

Signed-off-by: Igor Opaniuk <igor.opaniuk@toradex.com>
Reviewed-by: Oleksandr Suvorov <oleksandr.suvorov@toradex.com>
---

v2:
- Converted to reStructuredText format [Bin Meng]

 board/toradex/colibri_imx7/readme.rst | 128 ++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)
 create mode 100644 board/toradex/colibri_imx7/readme.rst

Hi Igor,

On Tue, Feb 11, 2020 at 7:34 PM Igor Opaniuk <igor.opaniuk@gmail.com> wrote:
>
> From: Igor Opaniuk <igor.opaniuk@toradex.com>
>
> Add initial readme.rst file which provides all needed information
> for obtaining a workable image ready for flashing
> for both eMMC/NAND versions of Colibri iMX7.

Thank you for converting the doc to reST format!

>
> Signed-off-by: Igor Opaniuk <igor.opaniuk@toradex.com>
> Reviewed-by: Oleksandr Suvorov <oleksandr.suvorov@toradex.com>
> ---
>
> v2:
> - Converted to reStructuredText format [Bin Meng]
>
>  board/toradex/colibri_imx7/readme.rst | 128 ++++++++++++++++++++++++++

Please put the reST file into doc/board/ directory, and organize it
like other boards:

1. create doc/board/toradex/colibri_imx7.rst file
2. create doc/board/toradex/index.rst file
3. update doc/board/index.rst file

In the U-Boot root directory, type 'make htmldocs' to see if there is
any build error or warning.

>  1 file changed, 128 insertions(+)
>  create mode 100644 board/toradex/colibri_imx7/readme.rst
>
> diff --git a/board/toradex/colibri_imx7/readme.rst b/board/toradex/colibri_imx7/readme.rst
> new file mode 100644
> index 0000000000..e914f23c53
> --- /dev/null
> +++ b/board/toradex/colibri_imx7/readme.rst
> @@ -0,0 +1,128 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +U-Boot for Colibri iMX7
> +=======================
> +
> +Quick Start
> +-----------
> +
> +- Build U-Boot
> +- NAND IMX image adjustments before flashing
> +- Flashing manually U-Boot to eMMC
> +- Flashing manually U-Boot to NAND
> +- Using ``update_uboot`` script
> +
> +Build U-Boot
> +------------
> +
> +.. code-block:: bash
> +
> +    $ export CROSS_COMPILE=arm-linux-gnueabi-
> +    $ export ARCH=arm
> +    $ make colibri_imx7_emmc_defconfig # For NAND: colibri_imx7_defconfig
> +    $ make
> +
> +After build succeeds, you will obtain final ``u-boot-dtb.imx`` IMX specific
> +image, ready for flashing (but check next section for additional
> +adjustments for NAND).
> +
> +Final IMX program image includes (section ``6.6.7`` from `IMX7DRM
> +<https://www.nxp.com/webapp/Download?colCode=IMX7DRM>`_):
> +
> +* **Image vector table** (IVT) for BootROM
> +* **Boot data** -indicates the program image location, program image size
> +  in bytes, and the plugin flag.
> +* **Device configuration data**
> +* **User image**: U-Boot image (``u-boot-dtb.bin``)
> +
> +
> +NAND IMX image adjustments prior to flashing
> +--------------------------------------------
> +
> +1. U-Boot for both Colibri iMX7 NAND and eMMC versions
> +is built with HABv4 support (`AN4581.pdf
> +<https://www.nxp.com/docs/en/application-note/AN4581.pdf>`_)
> +enabled by default, which requires to generate a proper
> +Command Sequence File (CSF) by srktool from NXP (not included in the
> +U-Boot tree, check additional details in introduction_habv4.txt)
> +and concatenate it to the final ``u-boot-dtb.imx``.
> +
> +2. In case if you don't want to generate a proper ``CSF`` (for any reason),
> +you still need to pad the IMX image so i has the same size as specified in
> +in **Boot Data** section of IMX image.
> +To obtain this value, run:
> +
> +.. code-block:: bash
> +
> +    $ od -X -N 0x30 u-boot-dtb.imx
> +    0000000    402000d1 87800000 00000000 877ff42c
> +    0000020    877ff420 877ff400 878a5000 00000000
> +                        ^^^^^^^^
> +    0000040    877ff000 000a8060 00000000 40b401d2
> +               ^^^^^^^^ ^^^^^^^^
> +
> +Where:
> +
> +* ``877ff400`` - IVT self address
> +* ``877ff000`` - Program image address
> +* ``000a8060`` - Program image size
> +
> +To calculate the padding:
> +
> +* IVT offset = ``0x877ff400`` - ``0x877ff000`` = ``0x400``
> +* Program image size = ``0xa8060`` - ``0x400`` = ``0xa7c60``
> +
> +and then pad the image:
> +
> +.. code-block:: bash
> +
> +    $ objcopy -I binary -O binary --pad-to 0xa7c60 --gap-fill=0x00 \
> +        u-boot-dtb.imx u-boot-dtb.imx.zero-padded
> +
> +3. Also, according to requirement from ``6.6.7.1``, the final image
> +should have ``0x400`` offset for initial IVT table.
> +
> +For eMMC setup we handle this by flashing it to ``0x400``, howewer
> +for NAND setup we adjust the image prior to flashing, adding padding in the
> +beginning of the image.
> +
> +.. code-block:: bash
> +
> +    $ dd if=u-boot-dtb.imx.zero-padded of=u-boot-dtb.imx.ready bs=1024 seek=1
> +
> +Flash U-Boot IMX image to eMMC
> +------------------------------
> +
> +Flash the ``u-boot-dtb.imx`` binary to the primary eMMC hardware
> +boot area partition:
> +
> +.. code-block:: bash
> +
> +
> +    => load mmc 1:1 $loadaddr u-boot-dtb.imx
> +    => setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200
> +    => mmc dev 0 1
> +    => mmc write ${loadaddr} 0x2 ${blkcnt}
> +
> +Flash U-boot IMX image to NAND

This should be U-Boot

> +------------------------------
> +
> +.. code-block:: bash
> +
> +    => load mmc 1:1 $loadaddr u-boot-dtb.imx.ready
> +    => nand erase.part u-boot1
> +    => nand write ${loadaddr} u-boot1 ${filesize}
> +    => nand erase.part u-boot2
> +    => nand write ${loadaddr} u-boot2 ${filesize}
> +
> +Using update_uboot script
> +-------------------------
> +
> +You can also usb U-boot env update_uboot script,

U-Boot

> +which wraps all eMMC/NAND specific command invocation:
> +
> +.. code-block:: bash
> +
> +    => load mmc 1:1 $loadaddr u-boot-dtb.imx
> +    => run update_uboot
> +
> --

Regards,
Bin

On Tue, 2020-02-11 at 13:34 +0200, Igor Opaniuk wrote:
> From: Igor Opaniuk <igor.opaniuk@toradex.com>
> 
> Add initial readme.rst file which provides all needed information
> for obtaining a workable image ready for flashing
> for both eMMC/NAND versions of Colibri iMX7.
> 
> Signed-off-by: Igor Opaniuk <igor.opaniuk@toradex.com>
> Reviewed-by: Oleksandr Suvorov <oleksandr.suvorov@toradex.com>
> ---
> 
> v2:
> - Converted to reStructuredText format [Bin Meng]
> 
>  board/toradex/colibri_imx7/readme.rst | 128 ++++++++++++++++++++++++++
>  1 file changed, 128 insertions(+)
>  create mode 100644 board/toradex/colibri_imx7/readme.rst
> 
> diff --git a/board/toradex/colibri_imx7/readme.rst b/board/toradex/colibri_imx7/readme.rst
> new file mode 100644
> index 0000000000..e914f23c53
> --- /dev/null
> +++ b/board/toradex/colibri_imx7/readme.rst
> @@ -0,0 +1,128 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +U-Boot for Colibri iMX7
> +=======================
> +
> +Quick Start
> +-----------
> +
> +- Build U-Boot
> +- NAND IMX image adjustments before flashing
> +- Flashing manually U-Boot to eMMC
> +- Flashing manually U-Boot to NAND
> +- Using ``update_uboot`` script
> +
> +Build U-Boot
> +------------
> +
> +.. code-block:: bash
> +
> +    $ export CROSS_COMPILE=arm-linux-gnueabi-
> +    $ export ARCH=arm
> +    $ make colibri_imx7_emmc_defconfig # For NAND: colibri_imx7_defconfig
> +    $ make
> +
> +After build succeeds, you will obtain final ``u-boot-dtb.imx`` IMX specific
... the final ...
> +image, ready for flashing (but check next section for additional
> +adjustments for NAND).
> +
> +Final IMX program image includes (section ``6.6.7`` from `IMX7DRM
> +<https://www.nxp.com/webapp/Download?colCode=IMX7DRM>`_):
> +
> +* **Image vector table** (IVT) for BootROM
> +* **Boot data** -indicates the program image location, program image size
> +  in bytes, and the plugin flag.
> +* **Device configuration data**
> +* **User image**: U-Boot image (``u-boot-dtb.bin``)
> +
> +
> +NAND IMX image adjustments prior to flashing
> +--------------------------------------------
> +
> +1. U-Boot for both Colibri iMX7 NAND and eMMC versions
> +is built with HABv4 support (`AN4581.pdf
> +<https://www.nxp.com/docs/en/application-note/AN4581.pdf>`_)
> +enabled by default, which requires to generate a proper
> +Command Sequence File (CSF) by srktool from NXP (not included in the
> +U-Boot tree, check additional details in introduction_habv4.txt)
> +and concatenate it to the final ``u-boot-dtb.imx``.
> +
> +2. In case if you don't want to generate a proper ``CSF`` (for any reason),
> +you still need to pad the IMX image so i has the same size as specified in
> +in **Boot Data** section of IMX image.
> +To obtain this value, run:
> +
> +.. code-block:: bash
> +
> +    $ od -X -N 0x30 u-boot-dtb.imx
> +    0000000    402000d1 87800000 00000000 877ff42c
> +    0000020    877ff420 877ff400 878a5000 00000000
> +                        ^^^^^^^^
> +    0000040    877ff000 000a8060 00000000 40b401d2
> +               ^^^^^^^^ ^^^^^^^^
> +
> +Where:
> +
> +* ``877ff400`` - IVT self address
> +* ``877ff000`` - Program image address
> +* ``000a8060`` - Program image size
> +
> +To calculate the padding:
> +
> +* IVT offset = ``0x877ff400`` - ``0x877ff000`` = ``0x400``
> +* Program image size = ``0xa8060`` - ``0x400`` = ``0xa7c60``
> +
> +and then pad the image:
> +
> +.. code-block:: bash
> +
> +    $ objcopy -I binary -O binary --pad-to 0xa7c60 --gap-fill=0x00 \
> +        u-boot-dtb.imx u-boot-dtb.imx.zero-padded

This is under the heading NAND, but the text refers both to NAND and eMMC.
Is 1. and 2. really only for NAND?

> +
> +3. Also, according to requirement from ``6.6.7.1``, the final image
> +should have ``0x400`` offset for initial IVT table.
> +
> +For eMMC setup we handle this by flashing it to ``0x400``, howewer
> +for NAND setup we adjust the image prior to flashing, adding padding in the
> +beginning of the image.
> +
> +.. code-block:: bash
> +
> +    $ dd if=u-boot-dtb.imx.zero-padded of=u-boot-dtb.imx.ready bs=1024 seek=1
> +
> +Flash U-Boot IMX image to eMMC
> +------------------------------
> +
> +Flash the ``u-boot-dtb.imx`` binary to the primary eMMC hardware
> +boot area partition:

That hints that we directly use the U-Boot make output. E.g. the steps 1. 2. and 3. are not needed.

> +
> +.. code-block:: bash
> +
> +
> +    => load mmc 1:1 $loadaddr u-boot-dtb.imx
> +    => setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200
> +    => mmc dev 0 1
> +    => mmc write ${loadaddr} 0x2 ${blkcnt}
> +
> +Flash U-boot IMX image to NAND
> +------------------------------
> +
> +.. code-block:: bash
> +
> +    => load mmc 1:1 $loadaddr u-boot-dtb.imx.ready
> +    => nand erase.part u-boot1
> +    => nand write ${loadaddr} u-boot1 ${filesize}
> +    => nand erase.part u-boot2
> +    => nand write ${loadaddr} u-boot2 ${filesize}
> +
> +Using update_uboot script
> +-------------------------
> +
> +You can also usb U-boot env update_uboot script,
> +which wraps all eMMC/NAND specific command invocation:
> +
> +.. code-block:: bash
> +
> +    => load mmc 1:1 $loadaddr u-boot-dtb.imx
> +    => run update_uboot
> +