1# SPDX-License-Identifier: GPL-2.0+ 2# 3# Copyright (C) 2015 Google. Inc 4# Written by Simon Glass <sjg@chromium.org> 5 6U-Boot on Rockchip 7================== 8 9A wide range of Rockchip SoCs are supported in mainline U-Boot 10 11 12Prerequisites 13============= 14 15You will need: 16 17 - Firefly RK3288 board or something else with a supported RockChip SoC 18 - Power connection to 5V using the supplied micro-USB power cable 19 - Separate USB serial cable attached to your computer and the Firefly 20 (connect to the micro-USB connector below the logo) 21 - rkflashtool [3] 22 - openssl (sudo apt-get install openssl) 23 - Serial UART connection [4] 24 - Suitable ARM cross compiler, e.g.: 25 sudo apt-get install gcc-4.7-arm-linux-gnueabi 26 27 28Building 29======== 30 31At present 12 RK3288 boards are supported: 32 33 - EVB RK3288 - use evb-rk3288 configuration 34 - Fennec RK3288 - use fennec-rk3288 configuration 35 - Firefly RK3288 - use firefly-rk3288 configuration 36 - Hisense Chromebook - use chromebook_jerry configuration 37 - Asus C100P Chromebook - use chromebook_minnie configuration 38 - Asus Chromebit - use chromebook_mickey configuration 39 - MiQi RK3288 - use miqi-rk3288 configuration 40 - phyCORE-RK3288 RDK - use phycore-rk3288 configuration 41 - PopMetal RK3288 - use popmetal-rk3288 configuration 42 - Radxa Rock 2 - use rock2 configuration 43 - Tinker RK3288 - use tinker-rk3288 configuration 44 - Vyasa RK3288 - use vyasa-rk3288 configuration 45 46Two RK3036 boards are supported: 47 48 - EVB RK3036 - use evb-rk3036 configuration 49 - Kylin - use kylin_rk3036 configuration 50 51One RK3328 board is supported: 52 53 - EVB RK3328 54 55Five RK3399 boards are supported (aarch64): 56 57 - EBV RK3399 - use evb_rk3399 configuration 58 - Firefly RK3399 - use the firefly_rk3399 configuration 59 - Puma - use puma_rk3399 configuration 60 - Ficus - use ficus-rk3399 configuration 61 - Rock960 (Vamrs) - use rock960-rk3399 configuration 62 63Four RK3368 boards are supported: 64 65 - Sheep - use sheep-rk3368 configuration 66 - Lion - use lion-rk3368 configuration 67 - Geekbox - use geekbox configuration 68 - EVB PX5 - use evb-px5 configuration 69 70One RK3128 board is supported: 71 72 - EVB RK3128 - use evb-rk3128 configuration 73 74One RK3229 board is supported: 75 76 - EVB RK3229 - use evb-rk3229 configuration 77 78Two RV1108 boards are supported: 79 80 - EVB RV1108 - use evb-rv1108 configuration 81 - Elgin R1 - use elgin-rv1108 configuration 82 83One RV3188 baord is supported: 84 85 - Raxda Rock - use rock configuration 86 87 88For example: 89 90 CROSS_COMPILE=arm-linux-gnueabi- make O=firefly firefly-rk3288_defconfig all 91 92(or you can use another cross compiler if you prefer) 93 94 95Writing to the board with USB 96============================= 97 98For USB to work you must get your board into ROM boot mode, either by erasing 99your MMC or (perhaps) holding the recovery button when you boot the board. 100To erase your MMC, you can boot into Linux and type (as root) 101 102 dd if=/dev/zero of=/dev/mmcblk0 bs=1M 103 104Connect your board's OTG port to your computer. 105 106To create a suitable image and write it to the board: 107 108 ./firefly-rk3288/tools/mkimage -n rk3288 -T rkimage -d \ 109 ./firefly-rk3288/spl/u-boot-spl-dtb.bin out && \ 110 cat out | openssl rc4 -K 7c4e0304550509072d2c7b38170d1711 | rkflashtool l 111 112If all goes well you should something like: 113 114 U-Boot SPL 2015.07-rc1-00383-ge345740-dirty (Jun 03 2015 - 10:06:49) 115 Card did not respond to voltage select! 116 spl: mmc init failed with error: -17 117 ### ERROR ### Please RESET the board ### 118 119You will need to reset the board before each time you try. Yes, that's all 120it does so far. If support for the Rockchip USB protocol or DFU were added 121in SPL then we could in principle load U-Boot and boot to a prompt from USB 122as several other platforms do. However it does not seem to be possible to 123use the existing boot ROM code from SPL. 124 125 126Booting from an SD card 127======================= 128 129To write an image that boots from an SD card (assumed to be /dev/sdc): 130 131 ./firefly-rk3288/tools/mkimage -n rk3288 -T rksd -d \ 132 firefly-rk3288/spl/u-boot-spl-dtb.bin out && \ 133 sudo dd if=out of=/dev/sdc seek=64 && \ 134 sudo dd if=firefly-rk3288/u-boot-dtb.img of=/dev/sdc seek=16384 135 136This puts the Rockchip header and SPL image first and then places the U-Boot 137image at block 16384 (i.e. 8MB from the start of the SD card). This 138corresponds with this setting in U-Boot: 139 140 #define CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR 0x4000 141 142Put this SD (or micro-SD) card into your board and reset it. You should see 143something like: 144 145 U-Boot 2016.01-rc2-00309-ge5bad3b-dirty (Jan 02 2016 - 23:41:59 -0700) 146 147 Model: Radxa Rock 2 Square 148 DRAM: 2 GiB 149 MMC: dwmmc@ff0f0000: 0, dwmmc@ff0c0000: 1 150 *** Warning - bad CRC, using default environment 151 152 In: serial 153 Out: vop@ff940000.vidconsole 154 Err: serial 155 Net: Net Initialization Skipped 156 No ethernet found. 157 Hit any key to stop autoboot: 0 158 => 159 160The rockchip bootrom can load and boot an initial spl, then continue to 161load a second-stage bootloader (ie. U-Boot) as soon as the control is returned 162to the bootrom. Both the RK3288 and the RK3036 use this special boot sequence. 163The configuration option enabling this is: 164 165 CONFIG_SPL_ROCKCHIP_BACK_TO_BROM=y 166 167You can create the image via the following operations: 168 169 ./firefly-rk3288/tools/mkimage -n rk3288 -T rksd -d \ 170 firefly-rk3288/spl/u-boot-spl-dtb.bin out && \ 171 cat firefly-rk3288/u-boot-dtb.bin >> out && \ 172 sudo dd if=out of=/dev/sdc seek=64 173 174If you have an HDMI cable attached you should see a video console. 175 176For evb_rk3036 board: 177 ./evb-rk3036/tools/mkimage -n rk3036 -T rksd -d evb-rk3036/spl/u-boot-spl.bin out && \ 178 cat evb-rk3036/u-boot-dtb.bin >> out && \ 179 sudo dd if=out of=/dev/sdc seek=64 180 181Note: rk3036 SDMMC and debug uart use the same iomux, so if you boot from SD, the 182 debug uart must be disabled 183 184 185Booting from an SD card on RK3288 with TPL 186========================================== 187 188Since the size of SPL can't be exceeded 0x8000 bytes in RK3288, it is not possible add 189new SPL features like Falcon mode or etc. 190 191So introduce TPL so-that adding new features to SPL is possible because now TPL should 192run minimal with code like DDR, clock etc and rest of new features in SPL. 193 194As of now TPL is added on Vyasa-RK3288 board. 195 196To write an image that boots from an SD card (assumed to be /dev/mmcblk0): 197 198 ./tools/mkimage -n rk3288 -T rksd -d ./tpl/u-boot-tpl.bin out && 199 cat ./spl/u-boot-spl-dtb.bin >> out && 200 sudo dd if=out of=/dev/mmcblk0 seek=64 && 201 sudo dd if=u-boot-dtb.img of=/dev/mmcblk0 seek=16384 202 203Booting from an SD card on RK3188 204================================= 205 206For rk3188 boards the general storage onto the card stays the same as 207described above, but the image creation needs a bit more care. 208 209The bootrom of rk3188 expects to find a small 1kb loader which returns 210control to the bootrom, after which it will load the real loader, which 211can then be up to 29kb in size and does the regular ddr init. This is 212handled by a single image (built as the SPL stage) that tests whether 213it is handled for the first or second time via code executed from the 214boot0-hook. 215 216Additionally the rk3188 requires everything the bootrom loads to be 217rc4-encrypted. Except for the very first stage the bootrom always reads 218and decodes 2kb pages, so files should be sized accordingly. 219 220# copy tpl, pad to 1020 bytes and append spl 221tools/mkimage -n rk3188 -T rksd -d spl/u-boot-spl.bin out 222 223# truncate, encode and append u-boot.bin 224truncate -s %2048 u-boot.bin 225cat u-boot.bin | split -b 512 --filter='openssl rc4 -K 7C4E0304550509072D2C7B38170D1711' >> out 226 227 228Using fastboot on rk3288 229======================== 230- Write GPT partition layout to mmc device which fastboot want to use it to 231store the image 232 233 => gpt write mmc 1 $partitions 234 235- Invoke fastboot command to prepare 236 237 => fastboot 1 238 239- Start fastboot request on PC 240 241 fastboot -i 0x2207 flash loader evb-rk3288/spl/u-boot-spl-dtb.bin 242 243You should see something like: 244 245 => fastboot 1 246 WARNING: unknown variable: partition-type:loader 247 Starting download of 357796 bytes 248 .. 249 downloading of 357796 bytes finished 250 Flashing Raw Image 251 ........ wrote 357888 bytes to 'loader' 252 253Booting from SPI 254================ 255 256To write an image that boots from SPI flash (e.g. for the Haier Chromebook): 257 258 ./chromebook_jerry/tools/mkimage -n rk3288 -T rkspi \ 259 -d chromebook_jerry/spl/u-boot-spl-dtb.bin spl.bin && \ 260 dd if=spl.bin of=spl-out.bin bs=128K conv=sync && \ 261 cat spl-out.bin chromebook_jerry/u-boot-dtb.img >out.bin && \ 262 dd if=out.bin of=out.bin.pad bs=4M conv=sync 263 264This converts the SPL image to the required SPI format by adding the Rockchip 265header and skipping every 2KB block. Then the U-Boot image is written at 266offset 128KB and the whole image is padded to 4MB which is the SPI flash size. 267The position of U-Boot is controlled with this setting in U-Boot: 268 269 #define CONFIG_SYS_SPI_U_BOOT_OFFS (128 << 10) 270 271If you have a Dediprog em100pro connected then you can write the image with: 272 273 sudo em100 -s -c GD25LQ32 -d out.bin.pad -r 274 275When booting you should see something like: 276 277 U-Boot SPL 2015.07-rc2-00215-g9a58220-dirty (Jun 23 2015 - 12:11:32) 278 279 280 U-Boot 2015.07-rc2-00215-g9a58220-dirty (Jun 23 2015 - 12:11:32 -0600) 281 282 Model: Google Jerry 283 DRAM: 2 GiB 284 MMC: 285 Using default environment 286 287 In: serial@ff690000 288 Out: serial@ff690000 289 Err: serial@ff690000 290 => 291 292Future work 293=========== 294 295Immediate priorities are: 296 297- USB host 298- USB device 299- Run CPU at full speed (code exists but we only see ~60 DMIPS maximum) 300- NAND flash 301- Boot U-Boot proper over USB OTG (at present only SPL works) 302 303 304Development Notes 305================= 306 307There are plenty of patches in the links below to help with this work. 308 309[1] https://github.com/rkchrome/uboot.git 310[2] https://github.com/linux-rockchip/u-boot-rockchip.git branch u-boot-rk3288 311[3] https://github.com/linux-rockchip/rkflashtool.git 312[4] http://wiki.t-firefly.com/index.php/Firefly-RK3288/Serial_debug/en 313 314rkimage 315------- 316 317rkimage.c produces an SPL image suitable for sending directly to the boot ROM 318over USB OTG. This is a very simple format - just the string RK32 (as 4 bytes) 319followed by u-boot-spl-dtb.bin. 320 321The boot ROM loads image to 0xff704000 which is in the internal SRAM. The SRAM 322starts at 0xff700000 and extends to 0xff718000 where we put the stack. 323 324rksd 325---- 326 327rksd.c produces an image consisting of 32KB of empty space, a header and 328u-boot-spl-dtb.bin. The header is defined by 'struct header0_info' although 329most of the fields are unused by U-Boot. We just need to specify the 330signature, a flag and the block offset and size of the SPL image. 331 332The header occupies a single block but we pad it out to 4 blocks. The header 333is encoding using RC4 with the key 7c4e0304550509072d2c7b38170d1711. The SPL 334image can be encoded too but we don't do that. 335 336The maximum size of u-boot-spl-dtb.bin which the boot ROM will read is 32KB, 337or 0x40 blocks. This is a severe and annoying limitation. There may be a way 338around this limitation, since there is plenty of SRAM, but at present the 339board refuses to boot if this limit is exceeded. 340 341The image produced is padded up to a block boundary (512 bytes). It should be 342written to the start of an SD card using dd. 343 344Since this image is set to load U-Boot from the SD card at block offset, 345CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_SECTOR, dd should be used to write 346u-boot-dtb.img to the SD card at that offset. See above for instructions. 347 348rkspi 349----- 350 351rkspi.c produces an image consisting of a header and u-boot-spl-dtb.bin. The 352resulting image is then spread out so that only the first 2KB of each 4KB 353sector is used. The header is the same as with rksd and the maximum size is 354also 32KB (before spreading). The image should be written to the start of 355SPI flash. 356 357See above for instructions on how to write a SPI image. 358 359rkmux.py 360-------- 361 362You can use this script to create #defines for SoC register access. See the 363script for usage. 364 365 366Device tree and driver model 367---------------------------- 368 369Where possible driver model is used to provide a structure to the 370functionality. Device tree is used for configuration. However these have an 371overhead and in SPL with a 32KB size limit some shortcuts have been taken. 372In general all Rockchip drivers should use these features, with SPL-specific 373modifications where required. 374 375GPT partition layout 376---------------------------- 377 378Rockchip use a unified GPT partition layout in open source support. 379With this GPT partition layout, uboot can be compatilbe with other components, 380like miniloader, trusted-os, arm-trust-firmware. 381 382There are some documents about partitions in the links below. 383http://rockchip.wikidot.com/partitions 384 385-- 386Simon Glass <sjg@chromium.org> 38724 June 2015 388