doc/README.mediatek

   1 # SPDX-License-Identifier: GPL-2.0+
   2 #
   3 # Copyright (C) 2018 MediaTek Inc.
   4 # Ryder Lee <ryder.lee@kernel.org>
   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