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