doc: board: toradex: add colibri_imx7.rst

- 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@toradex.com> Reviewed-by: Bin Meng <bmeng.cn@gmail.com> Reviewed-by: Oleksandr Suvorov <oleksandr.suvorov@toradex.com> Tested-by: Bin Meng <bmeng.cn@gmail.com> [bmeng: make title underline the same length as the title itself] Signed-off-by: Bin Meng <bmeng.cn@gmail.com>

doc: board: toradex: add colibri_imx7.rst
- 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@toradex.com> Reviewed-by: Bin Meng <bmeng.cn@gmail.com> Reviewed-by: Oleksandr Suvorov <oleksandr.suvorov@toradex.com> Tested-by: Bin Meng <bmeng.cn@gmail.com> [bmeng: make title underline the same length as the title itself] Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
Igor Opaniuk · Bin Meng
1 parent 7149d38005
Showing 3 changed files with 137 additions and 0 deletions Side-by-side Diff
doc/board/index.rst
doc/board/toradex/colibri_imx7.rst
doc/board/toradex/index.rst
@@ -17,5 +17,6 @@
    rockchip/index
    sifive/index
    st/index
+   toradex/index
    xilinx/index
+.. 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
+.. SPDX-License-Identifier: GPL-2.0+
+
+Toradex
+=======
+
+.. toctree::
+   :maxdepth: 2
+
+   colibri_imx7
...	...	@@ -17,5 +17,6 @@
17	17	rockchip/index
18	18	sifive/index
19	19	st/index
	20	+ toradex/index
20	21	xilinx/index
	1	+.. SPDX-License-Identifier: GPL-2.0+
	2	+
	3	+Colibri iMX7
	4	+============
	5	+
	6	+Quick Start
	7	+-----------
	8	+
	9	+- Build U-Boot
	10	+- NAND IMX image adjustments before flashing
	11	+- Flashing manually U-Boot to eMMC
	12	+- Flashing manually U-Boot to NAND
	13	+- Using ``update_uboot`` script
	14	+
	15	+Build U-Boot
	16	+------------
	17	+
	18	+.. code-block:: bash
	19	+
	20	+ $ export CROSS_COMPILE=arm-linux-gnueabi-
	21	+ $ export ARCH=arm
	22	+ $ make colibri_imx7_emmc_defconfig # For NAND: colibri_imx7_defconfig
	23	+ $ make
	24	+
	25	+After build succeeds, you will obtain final ``u-boot-dtb.imx`` IMX specific
	26	+image, ready for flashing (but check next section for additional
	27	+adjustments).
	28	+
	29	+Final IMX program image includes (section ``6.6.7`` from `IMX7DRM
	30	+<https://www.nxp.com/webapp/Download?colCode=IMX7DRM>`_):
	31	+
	32	+* Image vector table (IVT) for BootROM
	33	+* Boot data -indicates the program image location, program image size
	34	+ in bytes, and the plugin flag.
	35	+* Device configuration data
	36	+* User image: U-Boot image (``u-boot-dtb.bin``)
	37	+
	38	+
	39	+IMX image adjustments prior to flashing
	40	+---------------------------------------
	41	+
	42	+1. U-Boot for both Colibri iMX7 NAND and eMMC versions
	43	+is built with HABv4 support (`AN4581.pdf
	44	+<https://www.nxp.com/docs/en/application-note/AN4581.pdf>`_)
	45	+enabled by default, which requires to generate a proper
	46	+Command Sequence File (CSF) by srktool from NXP (not included in the
	47	+U-Boot tree, check additional details in introduction_habv4.txt)
	48	+and concatenate it to the final ``u-boot-dtb.imx``.
	49	+
	50	+2. In case if you don't want to generate a proper ``CSF`` (for any reason),
	51	+you still need to pad the IMX image so i has the same size as specified in
	52	+in Boot Data section of IMX image.
	53	+To obtain this value, run:
	54	+
	55	+.. code-block:: bash
	56	+
	57	+ $ od -X -N 0x30 u-boot-dtb.imx
	58	+ 0000000 402000d1 87800000 00000000 877ff42c
	59	+ 0000020 877ff420 877ff400 878a5000 00000000
	60	+ ^^^^^^^^
	61	+ 0000040 877ff000 000a8060 00000000 40b401d2
	62	+ ^^^^^^^^ ^^^^^^^^
	63	+
	64	+Where:
	65	+
	66	+* ``877ff400`` - IVT self address
	67	+* ``877ff000`` - Program image address
	68	+* ``000a8060`` - Program image size
	69	+
	70	+To calculate the padding:
	71	+
	72	+* IVT offset = ``0x877ff400`` - ``0x877ff000`` = ``0x400``
	73	+* Program image size = ``0xa8060`` - ``0x400`` = ``0xa7c60``
	74	+
	75	+and then pad the image:
	76	+
	77	+.. code-block:: bash
	78	+
	79	+ $ objcopy -I binary -O binary --pad-to 0xa7c60 --gap-fill=0x00 \
	80	+ u-boot-dtb.imx u-boot-dtb.imx.zero-padded
	81	+
	82	+3. Also, according to requirement from ``6.6.7.1``, the final image
	83	+should have ``0x400`` offset for initial IVT table.
	84	+
	85	+For eMMC setup we handle this by flashing it to ``0x400``, howewer
	86	+for NAND setup we adjust the image prior to flashing, adding padding in the
	87	+beginning of the image.
	88	+
	89	+.. code-block:: bash
	90	+
	91	+ $ dd if=u-boot-dtb.imx.zero-padded of=u-boot-dtb.imx.ready bs=1024 seek=1
	92	+
	93	+Flash U-Boot IMX image to eMMC
	94	+------------------------------
	95	+
	96	+Flash the ``u-boot-dtb.imx.zero-padded`` binary to the primary eMMC hardware
	97	+boot area partition:
	98	+
	99	+.. code-block:: bash
	100	+
	101	+
	102	+ => load mmc 1:1 $loadaddr u-boot-dtb.imx.zero-padded
	103	+ => setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200
	104	+ => mmc dev 0 1
	105	+ => mmc write ${loadaddr} 0x2 ${blkcnt}
	106	+
	107	+Flash U-Boot IMX image to NAND
	108	+------------------------------
	109	+
	110	+.. code-block:: bash
	111	+
	112	+ => load mmc 1:1 $loadaddr u-boot-dtb.imx.ready
	113	+ => nand erase.part u-boot1
	114	+ => nand write ${loadaddr} u-boot1 ${filesize}
	115	+ => nand erase.part u-boot2
	116	+ => nand write ${loadaddr} u-boot2 ${filesize}
	117	+
	118	+Using update_uboot script
	119	+-------------------------
	120	+
	121	+You can also usb U-Boot env update_uboot script,
	122	+which wraps all eMMC/NAND specific command invocation:
	123	+
	124	+.. code-block:: bash
	125	+
	126	+ => load mmc 1:1 $loadaddr u-boot-dtb.imx.ready
	127	+ => run update_uboot
	1	+.. SPDX-License-Identifier: GPL-2.0+
	2	+
	3	+Toradex
	4	+=======
	5	+
	6	+.. toctree::
	7	+ :maxdepth: 2
	8	+
	9	+ colibri_imx7