[J-u-boot.git] / doc / README.mediatek

# SPDX-License-Identifier: GPL-2.0+
#
# Copyright (C) 2018 MediaTek Inc.
# Ryder Lee <[email protected]>


This document describes how to compile the U-Boot and how to change U-Boot
configuration about the MediaTek SoCs.


Build Procedure
===============
	-Set the cross compiler:

		# export CROSS_COMPILE=/path/to/toolchain/arm-linux-gnueabi-

	-Clean-up old residuals:

		# make mrproper

	-Configure the U-Boot:

		# make <defconfig_file>
		# make

		- For the MT7623n bananapi R2 board use "mt7623n_bpir2_defconfig"
		- For the MT7629 reference board use "mt7629_rfb_defconfig"


Boot sequence
=============
	-Bootrom -> MTK preloader -> U-Boot

		- MT7623n

	This version of U-Boot doesn't implement SPL. So, MTK preloader binary
	is needed to boot up:

	https://github.com/BPI-SINOVOIP/BPI-R2-bsp/tree/master/mt-pack/mtk/bpi-r2/bin


	-Bootrom -> SPL -> U-Boot

		- MT7629


Configuration update
====================
	To update the U-Boot configuration, please refer to doc/README.kconfig


MediaTek image header
=====================
Currently there are two image headers used for MediaTek chips:

	- BootROM image header. This header is used by the first stage bootloader. It records
	  the desired compatible boot device, integrity information and its load address.

	  The on-chip BootROM will firstly verify integrity and compatibility of the bootloader.

	  If verification passed, the BootROM will then load the bootloader into on-chip SRAM,
	  and pass control to it.

	  Note that this header is actually a combination of three independent headers:
	  Device header, BRLYT header and GFH header.

	  Used by U-Boot SPL of MT7629 and preloader of MT7623.


	- MediaTek legacy image header. This header was originally used by the legacy image. It
	  basically records the load address, image size and image name.

	  After all low level initializations passed, the preloader will locate the LK image and
	  load it into DRAM, and pass control to it.

	  Now this header is used by U-Boot of MT7623.


To generate these two headers with mkimage:

	# mkimage -T mtk_image -a <load_addr> -n <option_string> -d <input_file> <image_file>

	- mtk_image means using MediaTek's header generation method.


	- load_addr is the load address of this image.
	  For first stage bootloader like U-Boot SPL or preloader, it usually points to the
	  on-chip SRAM.

	  For second stage bootloader like U-Boot, it usually points to the DRAM.


	- option_string contains options to generate the header.

	  The option string is using the follow format:
		key1=value1;key2=value2;...

	  The following key names are valid:
		lk: If lk=1, LK image header is used. Otherwise BootROM image header is used.

		lkname: The name of the LK image header. The maximum length is 32.
			The default value is "U-Boot".

		media: Desired boot device. The valid values are:
		nand : Parallel NAND
		snand: Serial NAND
		nor  : Serial NOR
		emmc : eMMC
		sdmmc: SD

	   nandinfo: Desired NAND device type, a combination of page size, oob size and
		     optional device capacity. Valid types are:
		2k+64    : for Serial NAND, 2KiB page size + 64B oob size
		2k+120   : for Serial NAND, 2KiB page size + 120B oob size
		2k+128   : for Serial NAND, 2KiB page size + 128B oob size
		4k+256   : for Serial NAND, 4KiB page size + 256B oob size
		1g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 1Gbit size
		2g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 2Gbit size
		4g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 4Gbit size
		2g:2k+128: for Parallel NAND, 2KiB page size + 128B oob size, total 2Gbit size
		4g:2k+128: for Parallel NAND, 2KiB page size + 128B oob size, total 4Gbit size


MT7629 partitions on Serial NOR
===============================

	Start      End       Size       Description
	00000000 - 0000ffff: 64KiB      U-Boot SPL
	00010000 - 0005ffff: 320KiB     U-Boot
	00060000 - 0006ffff: 64KiB      U-Boot env / MediaTek NVRAM
	00070000 - 000affff: 256KiB     RF calibration data
	000b0000 - xxxxxxxx: all left   Firmware image


BPi-R2 (MT7623N) partitions on SD
=================================
	Please note that the last two partitions can vary from different Linux distributions
	depending on the MBR partition table.

	Start      End       Size       Description
	00000000 - 000001ff: 512B       Device header (with MBR partition table)
	00000200 - 000007ff: 1536B      BRLYT header
	00000800 - 0004ffff: 318KiB     Preloader (with GFH header)
	00050000 - 000fffff: 704KiB     U-Boot
	00100000 - 063fffff: 99MiB      Reserved
	06400000 - 163fffff: 256MiB     Partition 1 (FAT32)
	16400000 - xxxxxxxx: all left   Partition 2 (ext4)


Upgrading notice on Serial NOR
==============================
Example: MT7629

	The command sf is used to operate the Serial NOR device:

	- To probe current NOR flash:

		# sf probe

	- To erase a region:

		# sf erase <offset> <len>

	- To write data to an offset:

		# sf write <data_addr> <offset> <len>

	- To boot kernel:

		# bootm 0x300b0000

	The memory address range 0x30000000 - 0x3fffffff is mapped to the NOR flash.
	The DRAM starts at 0x40000000.

	Please note that the output binary u-boot-mtk.bin is a combination of SPL and U-Boot,
	and it should be write to beginning of the flash.

	Otherwise you should use standalone files:

		spl/u-boot-spl-mtk.bin for SPL,
		u-boot.img for U-Boot.


Upgrading notice on SD / eMMC
=============================
Example: MT7623

	Normally only Preloader and U-Boot can be upgraded within U-Boot, and other partitions
	should be written in PC.

	- To probe current SD card / eMMC:

		# mmc dev 0 for eMMC
		# mmc dev 1 for SD

	- To erase a region:

		# mmc erase <blk_offset> <blk_num>

	- To write data to a block offset:

		# mmc write <data_addr> <blk_offset> <blk_num>

	- To load kernel image from partition 1:

		# fatload mmc 0:1 <load_address> <path_to_kernel_uImage> for eMMC
		# fatload mmc 1:1 <load_address> <path_to_kernel_uImage> for SD

	- To boot kernel:

		# bootm <load_address>

	The DRAM starts at 0x80000000.

	Please note that we use block offset and block count for SD card, not the byte offset.
	The block size is always 512 bytes for SD card.


Documentation
=============
	http://wiki.banana-pi.org/Banana_Pi_BPI-R2
Commit	Line	Data
3ba286e0 RL	1	# SPDX-License-Identifier: GPL-2.0+
	2	#
	3	# Copyright (C) 2018 MediaTek Inc.
	4	# Ryder Lee <[email protected]>
	5
	6
	7	This document describes how to compile the U-Boot and how to change U-Boot
	8	configuration about the MediaTek SoCs.
	9
	10
	11	Build Procedure
	12	===============
	13	-Set the cross compiler:
	14
	15	# export CROSS_COMPILE=/path/to/toolchain/arm-linux-gnueabi-
	16
	17	-Clean-up old residuals:
	18
	19	# make mrproper
	20
	21	-Configure the U-Boot:
	22
	23	# make <defconfig_file>
	24	# make
	25
	26	- For the MT7623n bananapi R2 board use "mt7623n_bpir2_defconfig"
	27	- For the MT7629 reference board use "mt7629_rfb_defconfig"
	28
	29
	30	Boot sequence
	31	=============
	32	-Bootrom -> MTK preloader -> U-Boot
	33
	34	- MT7623n
	35
	36	This version of U-Boot doesn't implement SPL. So, MTK preloader binary
	37	is needed to boot up:
	38
	39	https://github.com/BPI-SINOVOIP/BPI-R2-bsp/tree/master/mt-pack/mtk/bpi-r2/bin
	40
	41
	42	-Bootrom -> SPL -> U-Boot
	43
	44	- MT7629
	45
	46
	47	Configuration update
	48	====================
	49	To update the U-Boot configuration, please refer to doc/README.kconfig
	50
	51
	52	MediaTek image header
	53	=====================
	54	Currently there are two image headers used for MediaTek chips:
	55
	56	- BootROM image header. This header is used by the first stage bootloader. It records
	57	the desired compatible boot device, integrity information and its load address.
	58
	59	The on-chip BootROM will firstly verify integrity and compatibility of the bootloader.
	60
	61	If verification passed, the BootROM will then load the bootloader into on-chip SRAM,
	62	and pass control to it.
	63
	64	Note that this header is actually a combination of three independent headers:
65	Device header, BRLYT header and GFH header.
66
67	Used by U-Boot SPL of MT7629 and preloader of MT7623.
68
69
70	- MediaTek legacy image header. This header was originally used by the legacy image. It
71	basically records the load address, image size and image name.
72
73	After all low level initializations passed, the preloader will locate the LK image and
74	load it into DRAM, and pass control to it.
75
76	Now this header is used by U-Boot of MT7623.
77
78
79	To generate these two headers with mkimage:
80
81	# mkimage -T mtk_image -a <load_addr> -n <option_string> -d <input_file> <image_file>
82
83	- mtk_image means using MediaTek's header generation method.
84
85
86	- load_addr is the load address of this image.
87	For first stage bootloader like U-Boot SPL or preloader, it usually points to the
88	on-chip SRAM.
89
90	For second stage bootloader like U-Boot, it usually points to the DRAM.
91
92
93	- option_string contains options to generate the header.
94
95	The option string is using the follow format:
96	key1=value1;key2=value2;...
97
98	The following key names are valid:
99	lk: If lk=1, LK image header is used. Otherwise BootROM image header is used.
100
101	lkname: The name of the LK image header. The maximum length is 32.
102	The default value is "U-Boot".
103
104	media: Desired boot device. The valid values are:
105	nand : Parallel NAND
106	snand: Serial NAND
107	nor : Serial NOR
108	emmc : eMMC
109	sdmmc: SD
110
111	nandinfo: Desired NAND device type, a combination of page size, oob size and
112	optional device capacity. Valid types are:
113	2k+64 : for Serial NAND, 2KiB page size + 64B oob size
114	2k+120 : for Serial NAND, 2KiB page size + 120B oob size
115	2k+128 : for Serial NAND, 2KiB page size + 128B oob size
116	4k+256 : for Serial NAND, 4KiB page size + 256B oob size
117	1g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 1Gbit size
118	2g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 2Gbit size
119	4g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 4Gbit size
120	2g:2k+128: for Parallel NAND, 2KiB page size + 128B oob size, total 2Gbit size
121	4g:2k+128: for Parallel NAND, 2KiB page size + 128B oob size, total 4Gbit size
122
123
124	MT7629 partitions on Serial NOR
125	===============================
126
127	Start End Size Description
128	00000000 - 0000ffff: 64KiB U-Boot SPL
129	00010000 - 0005ffff: 320KiB U-Boot
130	00060000 - 0006ffff: 64KiB U-Boot env / MediaTek NVRAM
131	00070000 - 000affff: 256KiB RF calibration data
132	000b0000 - xxxxxxxx: all left Firmware image
133
134
135	BPi-R2 (MT7623N) partitions on SD
136	=================================
137	Please note that the last two partitions can vary from different Linux distributions
138	depending on the MBR partition table.
139
140	Start End Size Description
141	00000000 - 000001ff: 512B Device header (with MBR partition table)
142	00000200 - 000007ff: 1536B BRLYT header
143	00000800 - 0004ffff: 318KiB Preloader (with GFH header)
144	00050000 - 000fffff: 704KiB U-Boot
145	00100000 - 063fffff: 99MiB Reserved
146	06400000 - 163fffff: 256MiB Partition 1 (FAT32)
147	16400000 - xxxxxxxx: all left Partition 2 (ext4)
148
149
150	Upgrading notice on Serial NOR
151	==============================
152	Example: MT7629
153
154	The command sf is used to operate the Serial NOR device:
155
156	- To probe current NOR flash:
157
158	# sf probe
159
160	- To erase a region:
161
162	# sf erase <offset> <len>
163
164	- To write data to an offset:
165
166	# sf write <data_addr> <offset> <len>
167
168	- To boot kernel:
169
170	# bootm 0x300b0000
171
172	The memory address range 0x30000000 - 0x3fffffff is mapped to the NOR flash.
173	The DRAM starts at 0x40000000.
174
175	Please note that the output binary u-boot-mtk.bin is a combination of SPL and U-Boot,
176	and it should be write to beginning of the flash.
177
178	Otherwise you should use standalone files:
179
180	spl/u-boot-spl-mtk.bin for SPL,
181	u-boot.img for U-Boot.
182
183
184	Upgrading notice on SD / eMMC
185	=============================
186	Example: MT7623
187
188	Normally only Preloader and U-Boot can be upgraded within U-Boot, and other partitions
189	should be written in PC.
190
191	- To probe current SD card / eMMC:
192
193	# mmc dev 0 for eMMC
194	# mmc dev 1 for SD
195
196	- To erase a region:
197
198	# mmc erase <blk_offset> <blk_num>
199
200	- To write data to a block offset:
201
202	# mmc write <data_addr> <blk_offset> <blk_num>
203
204	- To load kernel image from partition 1:
205
206	# fatload mmc 0:1 <load_address> <path_to_kernel_uImage> for eMMC
207	# fatload mmc 1:1 <load_address> <path_to_kernel_uImage> for SD
208
209	- To boot kernel:
210
211	# bootm <load_address>
212
213	The DRAM starts at 0x80000000.
214
215	Please note that we use block offset and block count for SD card, not the byte offset.
216	The block size is always 512 bytes for SD card.
217
218
219	Documentation
220	=============
221	http://wiki.banana-pi.org/Banana_Pi_BPI-R2