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