[U-Boot] [PATCH v8 3/3] Odroid-XU3: Add documentation for Odroid-XU3

[Przemyslaw Marczak <p.marczak@samsung.com>]

Hello Hyungwon,

Now we will have some ambiguous naming:
"doc/README.odroid" and "doc/README.odroid-xu3"

Please update the first name to Odroid U3 or make it as a common for 
both Odroids, since the documentation you add is at most word by word 
the same - maybe better is to add U3 and  XU3 sections.

On 11/14/2014 07:25 AM, Hyungwon Hwang wrote:
> This patch adds documentation for Odroid-XU3. This documentation is
> based on that of Odroid (doc/README-odroid) made by Przemyslaw Marczak.
> The documentation includes basic information about boot media layout,
> environment, partition layout, and the instruction to burn the u-boot
> image to boot media.
>
> Signed-off-by: Hyungwon Hwang <human.hwang@samsung.com>
> Tested-by: Lukasz Majewski <l.majewski@samsung.com>
> Acked-by: Lukasz Majewski <l.majewski@samsung.com>
> Cc: Minkyu Kang <mk7.kang@samsung.com>
> Cc: Lukasz Majewski <l.majewski@samsung.com>
> ---
> Changes for v6:
> - Newly added
>
> Changes for v7:
> - Fix several errata in the documentation
>
> Changes for v8:
> - None
>
>   doc/README.odroid-xu3 | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 134 insertions(+)
>   create mode 100644 doc/README.odroid-xu3
>
> diff --git a/doc/README.odroid-xu3 b/doc/README.odroid-xu3
> new file mode 100644
> index 0000000..7171435
> --- /dev/null
> +++ b/doc/README.odroid-xu3
> @@ -0,0 +1,134 @@
> + U-boot for Odroid XU3
> +========================
> +
> +1. Summary
> +==========
> +This is a quick instruction for setup Odroid boards based on Exynos5422.
> +Exynos5422 is almost the same with Exynos5800 which is a variant of Exynos5422
> +for Chromebook.
> +
> +Board config: odroid-xu3_config
> +
> +2. Supported devices
> +====================
> +This U-BOOT config can be used on the board:
> +- Odroid XU3
> +with CPU Exynos 5422 and 2GB of RAM
> +
> +3. Boot sequence
> +================
> +iROM->BL1->(BL2 + TrustZone)->U-BOOT
> +
> +To boot up, this version of U-BOOT needs BL1, BL2, and TrustZone binary.
> +It can be downloaded from:
> +https://github.com/hardkernel/u-boot/tree/odroidxu3-v2012.07/sd_fuse/hardkernel
> +
> +4. Boot media layout
> +====================
> +The table below shows SD/eMMC cards layout for U-boot.
> +The block offset is starting from 0 and the block size is 512B.
> + -------------------------------------
> +|  Binary   | Block offset| part type |
> +|   name    | SD   | eMMC |(eMMC only)|
> + -------------------------------------
> +| Bl1       | 1    | 0    |  1 (boot) |
> +| Bl2       | 31   | 30   |  1 (boot) |
> +| U-boot    | 63   | 62   |  1 (boot) |

I think, that the tzsw offset is wrong here. Please check it.

> +| Tzsw      | 2111 | 2110 |  1 (boot) |
> +| Uboot Env | 2560 | 2560 |  0 (user) |
> + -------------------------------------
> +
> +5. Prepare the SD boot card - with SD card reader
> +=================================================
> +To prepare bootable media you need boot binaries provided by hardkernel.
> +The files from the link in point 3.
> +- bl1.bin.hardkernel
> +- bl2.bin.hardkernel
> +- tzsw.bin.hardkernel
> +- u-boot.bin.hardkernel
> +
> +This is all you need to boot this board. You can write the binaries to SD card
> +just by executing sd_fusing.sh. You cannot use this script to write binaries to
> +eMMC card.It is valid only for SD card.
> +
> +*note
> +You cannot access the eMMC protected part (the first 8MB roughly) using an
> +ordinary eMMC reader.
> +
> +*note:
> +If you build u-boot by yourself, you will find u-boot.bin and u-boot-dtb.bin
> +as the build result. You have to use u-boot-dtb.bin instead of u-boot.bin.
> +
> +quick steps for Linux:
> +- Download all files from the link at point 3.
> +- put any SD card into the SD reader
> +- check the device with "dmesg"
> +- run ./sd_fusing.sh /dev/sdX - where X is SD card device (but not a partition)
> +Check if Hardkernel U-boot is booting, and next do the same with your U-boot.
> +
> +6. Prepare the eMMC boot card
> +   with a eMMC card reader (boot from eMMC card slot)
> +=====================================================
> +To boot the device from the eMMC slot you should use a special card reader
> +which supports eMMC partition switch. All of the boot binaries are stored
> +on the eMMC boot partition which is normally hidden.
> +
> +The "sd_fusing.sh" script can be used after updating offsets of binaries
> +according to the table from point 4. Be sure that you are working on the right
> +eMMC partition - its size is usually very small, about 1-4 MiB.
> +
> +7. Prepare the eMMC boot card
> +   with a SD card reader (boot from SD card slot)
> +=================================================
> +If you have an eMMC->microSD adapter you can prepare the card as in point 5.
> +But then the device can boot only from the SD card slot.
> +
> +8. Prepare the boot media using Hardkernel U-boot
> +=================================================
> +You can update the U-boot to the custom one if you have a working bootloader
> +delivered with the board on the eMMC/SD card. Then follow the steps:
> +- install the android fastboot tool
> +- connect a micro usb cable to the board
> +- on the U-boot prompt, run command: fastboot (as a root)
> +- on the host, run command: "fastboot flash bootloader u-boot-dtb.bin"
> +- the custom U-boot should start after the board resets.
> +
> +9. Partition layout
> +====================
> +Default U-boot environment is setup for fixed partition layout.
> +
> +Partition table: MSDOS. Disk layout and files as listed in the table below.
> + ----- ------ ------ ------ -------- ---------------------------------
> +| Num | Name |  FS  | Size | Offset |         Reguired files          |
> +|     |      | Type |  MiB |  MiB   |                                 |
> + ----- ------ ------ ------ -------- ---------------------------------
> +|  1  | BOOT | fat  |  100 |   2    |  kernel, fdt**                  |
> +|  2  | ROOT | ext4 |   -  |        |  any Linux system               |
> + ----- ------ ------ ------ -------- ---------------------------------
> +
> +**note:
> +Supported fdt files are:
> +- exynos5422-odroidxu3.dtb
> +
> +Supported kernel files are:
> +- Image.itb
> +- zImage
> +- uImage
> +
> +10. The environment and booting the kernel
> +==========================================
> +There are three macros defined in config for various boot options:
> +Two for both, kernel with device tree support and also without it:
> +- boot_uimg - load uImage
> +- boot_zimg - load zImage
> +If proper fdt file exists then it will be automatically loaded,
> +so for old kernel types, please remove fdt file from boot partition.
> +
> +The third boot option for multi image support (more info: doc/uImage.FIT/)
> +- boot_fit - for binary file: "Image.itb"
> +
> +Default boot command: "autoboot"
> +And the boot sequence is:
> +- boot_fit - if "Image.itb" exists
> +- boot_zimg - if "zImage" exists
> +- boot_uimg - if "uImage" exists
>

Best regards,
-- 
Przemyslaw Marczak
Samsung R&D Institute Poland
Samsung Electronics
p.marczak at samsung.com