xref: /openbmc/u-boot/doc/README.uniphier (revision 445277b9)
1U-Boot for UniPhier SoC family
2==============================
3
4
5Recommended toolchains
6----------------------
7
8The UniPhier platform is well tested with Linaro toolchains.
9You can download pre-built toolchains from:
10
11    http://www.linaro.org/downloads/
12
13
14Compile the source
15------------------
16
17The source can be configured and built with the following commands:
18
19    $ make <defconfig>
20    $ make CROSS_COMPILE=<toolchain-prefix> DEVICE_TREE=<device-tree>
21
22The recommended <toolchain-prefix> is `arm-linux-gnueabihf-` for 32bit SoCs,
23`aarch64-linux-gnu-` for 64bit SoCs, but you may wish to change it to use your
24favorite compiler.
25
26The following tables show <defconfig> and <device-tree> for each board.
27
2832bit SoC boards:
29
30 Board         | <defconfig>                 | <device-tree>
31---------------|-----------------------------|------------------------------
32LD4 reference  | uniphier_ld4_sld8_defconfig | uniphier-ld4-ref (default)
33sld8 reference | uniphier_ld4_sld8_defconfig | uniphier-sld8-def
34Pro4 reference | uniphier_v7_defconfig       | uniphier-pro4-ref
35Pro4 Ace       | uniphier_v7_defconfig       | uniphier-pro4-ace
36Pro4 Sanji     | uniphier_v7_defconfig       | uniphier-pro4-sanji
37Pro5 4KBOX     | uniphier_v7_defconfig       | uniphier-pro5-4kbox
38PXs2 Gentil    | uniphier_v7_defconfig       | uniphier-pxs2-gentil
39PXs2 Vodka     | uniphier_v7_defconfig       | uniphier-pxs2-vodka (default)
40LD6b reference | uniphier_v7_defconfig       | uniphier-ld6b-ref
41
4264bit SoC boards:
43
44 Board         | <defconfig>           | <device-tree>
45---------------|-----------------------|----------------------------
46LD11 reference | uniphier_v8_defconfig | uniphier-ld11-ref
47LD11 Global    | uniphier_v8_defconfig | uniphier-ld11-global
48LD20 reference | uniphier_v8_defconfig | uniphier-ld20-ref (default)
49LD20 Global    | uniphier_v8_defconfig | uniphier-ld20-global
50PXs3 reference | uniphier_v8_defconfig | uniphier-pxs3-ref
51
52For example, to compile the source for PXs2 Vodka board, run the following:
53
54    $ make uniphier_v7_defconfig
55    $ make CROSS_COMPILE=arm-linux-gnueabihf- DEVICE_TREE=uniphier-pxs2-vodka
56
57The device tree marked as (default) can be omitted.  `uniphier-pxs2-vodka` is
58the default device tree for the configuration `uniphier_v7_defconfig`, so the
59following gives the same result.
60
61    $ make uniphier_v7_defconfig
62    $ make CROSS_COMPILE=arm-linux-gnueabihf-
63
64
65Booting 32bit SoC boards
66------------------------
67
68The build command will generate the following:
69- u-boot.bin
70- spl/u-boot.bin
71
72U-Boot can boot UniPhier 32bit SoC boards by itself.  Flash the generated images
73to the storage device (NAND or eMMC) on your board.
74
75 - spl/u-boot-spl.bin at the offset address 0x00000000
76 - u-boot.bin         at the offset address 0x00020000
77
78The `u-boot-with-spl.bin` is the concatenation of the two (with appropriate
79padding), so you can also do:
80
81 - u-boot-with-spl.bin at the offset address 0x00000000
82
83If a TFTP server is available, the images can be easily updated.
84Just copy the u-boot-spl.bin and u-boot.bin to the TFTP public directory,
85and run the following command at the U-Boot command line:
86
87To update the images in NAND:
88
89    => run nandupdate
90
91To update the images in eMMC:
92
93    => run emmcupdate
94
95
96Booting 64bit SoC boards
97------------------------
98
99The build command will generate the following:
100- u-boot.bin
101
102However, U-Boot is not the first stage loader for UniPhier 64bit SoC boards.
103U-Boot serves as a non-secure boot loader loaded by [ARM Trusted Firmware],
104so you need to provide the `u-boot.bin` to the build command of ARM Trusted
105Firmware.
106
107[ARM Trusted Firmware]: https://github.com/ARM-software/arm-trusted-firmware
108
109
110Verified Boot
111-------------
112
113U-Boot supports an image verification method called "Verified Boot".
114This is a brief tutorial to utilize this feature for the UniPhier platform.
115You will find details documents in the doc/uImage.FIT directory.
116
117Here, we take LD20 reference board for example, but it should work for any
118other boards including 32 bit SoCs.
119
1201. Generate key to sign with
121
122  $ mkdir keys
123  $ openssl genpkey -algorithm RSA -out keys/dev.key \
124    -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537
125  $ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
126
127Two files "dev.key" and "dev.crt" will be created.  The base name is arbitrary,
128but need to match to the "key-name-hint" property described below.
129
1302. Describe FIT source
131
132You need to write an FIT (Flattened Image Tree) source file to describe the
133structure of the image container.
134
135The following is an example for a simple usecase:
136
137---------------------------------------->8----------------------------------------
138/dts-v1/;
139
140/ {
141	description = "Kernel, DTB and Ramdisk for UniPhier LD20 Reference Board";
142	#address-cells = <1>;
143
144	images {
145		kernel {
146			description = "linux";
147			data = /incbin/("PATH/TO/YOUR/LINUX/DIR/arch/arm64/boot/Image.gz");
148			type = "kernel";
149			arch = "arm64";
150			os = "linux";
151			compression = "gzip";
152			load = <0x82080000>;
153			entry = <0x82080000>;
154			hash-1 {
155				algo = "sha256";
156			};
157		};
158
159		fdt-1 {
160			description = "fdt";
161			data = /incbin/("PATH/TO/YOUR/LINUX/DIR/arch/arm64/boot/dts/socionext/uniphier-ld20-ref.dtb");
162			type = "flat_dt";
163			arch = "arm64";
164			compression = "none";
165			hash-1 {
166				algo = "sha256";
167			};
168		};
169
170		ramdisk {
171			description = "ramdisk";
172			data = /incbin/("PATH/TO/YOUR/ROOTFS/DIR/rootfs.cpio");
173			type = "ramdisk";
174			arch = "arm64";
175			os = "linux";
176			compression = "none";
177			hash-1 {
178				algo = "sha256";
179			};
180		};
181	};
182
183	configurations {
184		default = "config-1";
185
186		config-1 {
187			description = "Configuration0";
188			kernel = "kernel";
189			fdt = "fdt-1";
190			ramdisk = "ramdisk";
191			signature-1 {
192				algo = "sha256,rsa2048";
193				key-name-hint = "dev";
194				sign-images = "kernel", "fdt", "ramdisk";
195			};
196		};
197	};
198};
199---------------------------------------->8----------------------------------------
200
201You need to change the three '/incbin/' lines, depending on the location of
202your kernel image, device tree blob, and init ramdisk.  The "load" and "entry"
203properties also need to be adjusted if you want to change the physical placement
204of the kernel.
205
206The "key-name-hint" must specify the key name you have created in the step 1.
207
208The FIT file name is arbitrary.  Let's say you saved it into "fit.its".
209
2103. Compile U-Boot with FIT and signature enabled
211
212To use the Verified Boot, you need to enable the following two options:
213  CONFIG_FIT
214  CONFIG_FIT_SIGNATURE
215
216They are disabled by default for UniPhier defconfig files.  So, you need to
217tweak the configuration from "make menuconfig" or friends.
218
219  $ make uniphier_v8_defconfig
220  $ make menuconfig
221      [ enable CONFIG_FIT and CONFIG_FIT_SIGNATURE ]
222  $ make CROSS_COMPILE=aarch64-linux-gnu-
223
2244. Build the image tree blob
225
226After building U-Boot, you will see tools/mkimage.  With this tool, you can
227create an image tree blob as follows:
228
229  $ tools/mkimage -f fit.its -k keys -K dts/dt.dtb -r -F fitImage
230
231The -k option must specify the key directory you have created in step 1.
232
233A file "fitImage" will be created.  This includes kernel, DTB, Init-ramdisk,
234hash data for each of the three, and signature data.
235
236The public key needed for the run-time verification is stored in "dts/dt.dtb".
237
2385. Compile U-Boot again
239
240Since the "dt.dtb" has been updated in step 4, you need to re-compile the
241U-Boot.
242
243  $ make CROSS_COMPILE=aarch64-linux-gnu-
244
245The re-compiled "u-boot.bin" is appended with DTB that contains the public key.
246
2476. Flash the image
248
249Flash the "fitImage" to a storage device (NAND, eMMC, or whatever) on your
250board.
251
252Please note the "u-boot.bin" must be signed, and verified by someone when it is
253loaded.  For ARMv8 SoCs, the "someone" is generally ARM Trusted Firmware BL2.
254ARM Trusted Firmware supports an image authentication mechanism called Trusted
255Board Boot (TBB).  The verification process must be chained from the moment of
256the system reset.  If the Chain of Trust has a breakage somewhere, the verified
257boot process is entirely pointless.
258
2597. Boot verified kernel
260
261Load the fitImage to memory and run the following from the U-Boot command line.
262
263  > bootm <addr>
264
265Here, <addr> is the base address of the fitImage.
266
267If it is successful, you will see messages like follows:
268
269---------------------------------------->8----------------------------------------
270## Loading kernel from FIT Image at 84100000 ...
271   Using 'config-1' configuration
272   Verifying Hash Integrity ... sha256,rsa2048:dev+ OK
273   Trying 'kernel' kernel subimage
274     Description:  linux
275     Created:      2017-10-20  14:32:29 UTC
276     Type:         Kernel Image
277     Compression:  gzip compressed
278     Data Start:   0x841000c8
279     Data Size:    6957818 Bytes = 6.6 MiB
280     Architecture: AArch64
281     OS:           Linux
282     Load Address: 0x82080000
283     Entry Point:  0x82080000
284     Hash algo:    sha256
285     Hash value:   82a37b7f11ae55f4e07aa25bf77e4067cb9dc1014d52d6cd4d588f92eee3aaad
286   Verifying Hash Integrity ... sha256+ OK
287## Loading ramdisk from FIT Image at 84100000 ...
288   Using 'config-1' configuration
289   Trying 'ramdisk' ramdisk subimage
290     Description:  ramdisk
291     Created:      2017-10-20  14:32:29 UTC
292     Type:         RAMDisk Image
293     Compression:  uncompressed
294     Data Start:   0x847a5cc0
295     Data Size:    5264365 Bytes = 5 MiB
296     Architecture: AArch64
297     OS:           Linux
298     Load Address: unavailable
299     Entry Point:  unavailable
300     Hash algo:    sha256
301     Hash value:   44980a2874154a2e31ed59222c9f8ea968867637f35c81e4107a984de7014deb
302   Verifying Hash Integrity ... sha256+ OK
303## Loading fdt from FIT Image at 84100000 ...
304   Using 'config-1' configuration
305   Trying 'fdt-1' fdt subimage
306     Description:  fdt
307     Created:      2017-10-20  14:32:29 UTC
308     Type:         Flat Device Tree
309     Compression:  uncompressed
310     Data Start:   0x847a2cb0
311     Data Size:    12111 Bytes = 11.8 KiB
312     Architecture: AArch64
313     Hash algo:    sha256
314     Hash value:   c517099db537f6d325e6be46b25c871a41331ad5af0283883fd29d40bfc14e1d
315   Verifying Hash Integrity ... sha256+ OK
316   Booting using the fdt blob at 0x847a2cb0
317   Uncompressing Kernel Image ... OK
318   reserving fdt memory region: addr=80000000 size=2000000
319   Loading Device Tree to 000000009fffa000, end 000000009fffff4e ... OK
320
321Starting kernel ...
322---------------------------------------->8----------------------------------------
323
324Please pay attention to the lines that start with "Verifying Hash Integrity".
325
326"Verifying Hash Integrity ... sha256,rsa2048:dev+ OK" means the signature check
327passed.
328
329"Verifying Hash Integrity ... sha256+ OK" (3 times) means the hash check passed
330for kernel, DTB, and Init ramdisk.
331
332If they are not displayed, the Verified Boot is not working.
333
334
335UniPhier specific commands
336--------------------------
337
338 - pinmon (enabled by CONFIG_CMD_PINMON)
339     shows the boot mode pins that has been latched at the power-on reset
340
341 - ddrphy (enabled by CONFIG_CMD_DDRPHY_DUMP)
342     shows the DDR PHY parameters set by the PHY training
343
344 - ddrmphy (enabled by CONFIG_CMD_DDRMPHY_DUMP)
345     shows the DDR Multi PHY parameters set by the PHY training
346
347
348Supported devices
349-----------------
350
351 - UART (on-chip)
352 - NAND
353 - SD/eMMC
354 - USB 2.0 (EHCI)
355 - USB 3.0 (xHCI)
356 - GPIO
357 - LAN (on-board SMSC9118)
358 - I2C
359 - EEPROM (connected to the on-board I2C bus)
360 - Support card (SRAM, NOR flash, some peripherals)
361
362
363Micro Support Card
364------------------
365
366The recommended bit switch settings are as follows:
367
368 SW2    OFF(1)/ON(0)   Description
369 ------------------------------------------
370 bit 1   <----         BKSZ[0]
371 bit 2   ---->         BKSZ[1]
372 bit 3   <----         SoC Bus Width 16/32
373 bit 4   <----         SERIAL_SEL[0]
374 bit 5   ---->         SERIAL_SEL[1]
375 bit 6   ---->         BOOTSWAP_EN
376 bit 7   <----         CS1/CS5
377 bit 8   <----         SOC_SERIAL_DISABLE
378
379 SW8    OFF(1)/ON(0)   Description
380 ------------------------------------------
381 bit 1    <----        CS1_SPLIT
382 bit 2    <----        CASE9_ON
383 bit 3    <----        CASE10_ON
384 bit 4  Don't Care     Reserve
385 bit 5  Don't Care     Reserve
386 bit 6  Don't Care     Reserve
387 bit 7    ---->        BURST_EN
388 bit 8    ---->        FLASHBUS32_16
389
390The BKSZ[1:0] specifies the address range of memory slot and peripherals
391as follows:
392
393 BKSZ    Description              RAM slot            Peripherals
394 --------------------------------------------------------------------
395 0b00   15MB RAM / 1MB Peri    00000000-00efffff    00f00000-00ffffff
396 0b01   31MB RAM / 1MB Peri    00000000-01efffff    01f00000-01ffffff
397 0b10   64MB RAM / 1MB Peri    00000000-03efffff    03f00000-03ffffff
398 0b11  127MB RAM / 1MB Peri    00000000-07efffff    07f00000-07ffffff
399
400Set BSKZ[1:0] to 0b01 for U-Boot.
401This mode is the most handy because EA[24] is always supported by the save pin
402mode of the system bus.  On the other hand, EA[25] is not supported for some
403newer SoCs.  Even if it is, EA[25] is not connected on most of the boards.
404
405--
406Masahiro Yamada <yamada.masahiro@socionext.com>
407Oct. 2017
408