[PATCH v1] colibri_imx7: add README file

[Igor Opaniuk]

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

Add initial README 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>
---

 board/toradex/colibri_imx7/README | 107 ++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 board/toradex/colibri_imx7/README

diff --git a/board/toradex/colibri_imx7/README b/board/toradex/colibri_imx7/README
new file mode 100644
index 0000000000..729b572574
--- /dev/null
+++ b/board/toradex/colibri_imx7/README
@@ -0,0 +1,107 @@
+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
+============
+
+$ export CROSS_COMPILE=arm-linux-gnueabi-
+$ export ARCH=arm
+$ make colibri_imx7_emmc_defconfig # For NAND version: 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 [1]):
+1. Image vector table (IVT) for BootROM
+2. Boot data - indicates the program image location, program image size
+in bytes, and the plugin flah.
+3. Device configuration data
+4. U-Boot image itself (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 [2] 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 [3]) and concatenate it to the final u-boot-dtb.imx.
+
+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:
+$ 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:
+$ objcopy -I binary -O binary --pad-to 0xa7c60 --gap-fill=0x00 \
+u-boot-dtb.imx u-boot-dtb.imx.zero-padded
+
+-----
+
+2. Also, based on requirement from 6.6.7.1([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.
+
+$ 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:
+
+> 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
+==============================
+
+> 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:
+
+> load mmc 1:1 $loadaddr u-boot-dtb.imx
+> run update_uboot
+
+[1] https://www.nxp.com/webapp/Download?colCode=IMX7DRM
+[2] https://www.nxp.com/docs/en/application-note/AN4581.pdf
+[3] doc/imx/habv4/introduction_habv4.txt
-- 
2.17.1