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