diff mbox series

[v4,1/6] doc: board: toradex: add colibri_imx7.rst

Message ID 20200212144034.17291-2-igor.opaniuk@gmail.com
State Superseded
Headers show
Series doc: board: toradex reST documentation | expand

Commit Message

Igor Opaniuk Feb. 12, 2020, 2:40 p.m. UTC
From: Igor Opaniuk <igor.opaniuk at toradex.com>

- add initial index for toradex boards reST documentation
- add initial colibri_imx7.rst doc 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 at toradex.com>
---

 doc/board/index.rst                |   1 +
 doc/board/toradex/colibri_imx7.rst | 127 +++++++++++++++++++++++++++++
 doc/board/toradex/index.rst        |   9 ++
 3 files changed, 137 insertions(+)
 create mode 100644 doc/board/toradex/colibri_imx7.rst
 create mode 100644 doc/board/toradex/index.rst

Comments

Bin Meng Feb. 12, 2020, 2:47 p.m. UTC | #1
On Wed, Feb 12, 2020 at 10:40 PM Igor Opaniuk <igor.opaniuk at gmail.com> wrote:
>
> From: Igor Opaniuk <igor.opaniuk at toradex.com>
>
> - add initial index for toradex boards reST documentation
> - add initial colibri_imx7.rst doc 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 at toradex.com>
> ---
>
>  doc/board/index.rst                |   1 +
>  doc/board/toradex/colibri_imx7.rst | 127 +++++++++++++++++++++++++++++
>  doc/board/toradex/index.rst        |   9 ++
>  3 files changed, 137 insertions(+)
>  create mode 100644 doc/board/toradex/colibri_imx7.rst
>  create mode 100644 doc/board/toradex/index.rst
>
> diff --git a/doc/board/index.rst b/doc/board/index.rst
> index 00e72f57cd..f2f5907b8c 100644
> --- a/doc/board/index.rst
> +++ b/doc/board/index.rst
> @@ -15,4 +15,5 @@ Board-specific doc
>     intel/index
>     renesas/index
>     sifive/index
> +   toradex/index
>     xilinx/index
> diff --git a/doc/board/toradex/colibri_imx7.rst b/doc/board/toradex/colibri_imx7.rst
> new file mode 100644
> index 0000000000..6128a000e1
> --- /dev/null
> +++ b/doc/board/toradex/colibri_imx7.rst
> @@ -0,0 +1,127 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +Colibri iMX7
> +=======================

I suspect there will be build warnings. The length of === should be
the same as the length of "Colibri iMX7"

Please fix this globally in this series.

You can type "make htmldocs" in this U-Boot source tree to check build results.

> +
> +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).
> +
> +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``)
> +
> +
> +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.zero-padded`` binary to the primary eMMC hardware
> +boot area partition:
> +
> +.. code-block:: bash
> +
> +
> +    => load mmc 1:1 $loadaddr u-boot-dtb.imx.zero-padded
> +    => 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.ready
> +    => run update_uboot
> diff --git a/doc/board/toradex/index.rst b/doc/board/toradex/index.rst
> new file mode 100644
> index 0000000000..aa418d6bad
> --- /dev/null
> +++ b/doc/board/toradex/index.rst
> @@ -0,0 +1,9 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +Toradex
> +=======
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   colibri_imx7
> --

Reviewed-by: Bin Meng <bmeng.cn at gmail.com>
Igor Opaniuk Feb. 12, 2020, 3 p.m. UTC | #2
Hi Bin,

On Wed, Feb 12, 2020 at 4:47 PM Bin Meng <bmeng.cn at gmail.com> wrote:
>
> On Wed, Feb 12, 2020 at 10:40 PM Igor Opaniuk <igor.opaniuk at gmail.com> wrote:
> >
> > From: Igor Opaniuk <igor.opaniuk at toradex.com>
> >
> > - add initial index for toradex boards reST documentation
> > - add initial colibri_imx7.rst doc 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 at toradex.com>
> > ---
> >
> >  doc/board/index.rst                |   1 +
> >  doc/board/toradex/colibri_imx7.rst | 127 +++++++++++++++++++++++++++++
> >  doc/board/toradex/index.rst        |   9 ++
> >  3 files changed, 137 insertions(+)
> >  create mode 100644 doc/board/toradex/colibri_imx7.rst
> >  create mode 100644 doc/board/toradex/index.rst
> >
> > diff --git a/doc/board/index.rst b/doc/board/index.rst
> > index 00e72f57cd..f2f5907b8c 100644
> > --- a/doc/board/index.rst
> > +++ b/doc/board/index.rst
> > @@ -15,4 +15,5 @@ Board-specific doc
> >     intel/index
> >     renesas/index
> >     sifive/index
> > +   toradex/index
> >     xilinx/index
> > diff --git a/doc/board/toradex/colibri_imx7.rst b/doc/board/toradex/colibri_imx7.rst
> > new file mode 100644
> > index 0000000000..6128a000e1
> > --- /dev/null
> > +++ b/doc/board/toradex/colibri_imx7.rst
> > @@ -0,0 +1,127 @@
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +
> > +Colibri iMX7
> > +=======================
>
> I suspect there will be build warnings. The length of === should be
> the same as the length of "Colibri iMX7"
Thanks for reporting.
make htmldocs doesn't report anything, but I'll fix it.

u-boot-imx.git$ make htmldocs
  SPHINX  htmldocs --> file:///home/xdev/toradex/reps/u-boot-imx.git/doc/output
  PARSE   include/linker_lists.h
Running Sphinx v1.6.7
Warning: The Sphinx 'sphinx_rtd_theme' HTML theme was not found. Make
sure you have the theme installed to produce pretty HTML output.
Falling back to the default theme.
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 87 source files that are out of date
updating environment: 87 added, 0 changed, 0 removed
./cmd/bootefi.c:222: warning: Function parameter or member 'fdt' not
described in 'efi_install_fdt'
./cmd/bootefi.c:222: warning: Excess function parameter 'fdt_addr'
description in 'efi_install_fdt'
reading sources... [100%] uefi/uefi
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] uefi/uefi
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.


>
> Please fix this globally in this series.
>
> You can type "make htmldocs" in this U-Boot source tree to check build results.
>
> > +
> > +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).
> > +
> > +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``)
> > +
> > +
> > +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.zero-padded`` binary to the primary eMMC hardware
> > +boot area partition:
> > +
> > +.. code-block:: bash
> > +
> > +
> > +    => load mmc 1:1 $loadaddr u-boot-dtb.imx.zero-padded
> > +    => 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.ready
> > +    => run update_uboot
> > diff --git a/doc/board/toradex/index.rst b/doc/board/toradex/index.rst
> > new file mode 100644
> > index 0000000000..aa418d6bad
> > --- /dev/null
> > +++ b/doc/board/toradex/index.rst
> > @@ -0,0 +1,9 @@
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +
> > +Toradex
> > +=======
> > +
> > +.. toctree::
> > +   :maxdepth: 2
> > +
> > +   colibri_imx7
> > --
>
> Reviewed-by: Bin Meng <bmeng.cn at gmail.com>
diff mbox series

Patch

diff --git a/doc/board/index.rst b/doc/board/index.rst
index 00e72f57cd..f2f5907b8c 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -15,4 +15,5 @@  Board-specific doc
    intel/index
    renesas/index
    sifive/index
+   toradex/index
    xilinx/index
diff --git a/doc/board/toradex/colibri_imx7.rst b/doc/board/toradex/colibri_imx7.rst
new file mode 100644
index 0000000000..6128a000e1
--- /dev/null
+++ b/doc/board/toradex/colibri_imx7.rst
@@ -0,0 +1,127 @@ 
+.. SPDX-License-Identifier: GPL-2.0+
+
+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).
+
+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``)
+
+
+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.zero-padded`` binary to the primary eMMC hardware
+boot area partition:
+
+.. code-block:: bash
+
+
+    => load mmc 1:1 $loadaddr u-boot-dtb.imx.zero-padded
+    => 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.ready
+    => run update_uboot
diff --git a/doc/board/toradex/index.rst b/doc/board/toradex/index.rst
new file mode 100644
index 0000000000..aa418d6bad
--- /dev/null
+++ b/doc/board/toradex/index.rst
@@ -0,0 +1,9 @@ 
+.. SPDX-License-Identifier: GPL-2.0+
+
+Toradex
+=======
+
+.. toctree::
+   :maxdepth: 2
+
+   colibri_imx7