doc/README.uniphier

   1 U-Boot for UniPhier SoC family
   2 ==============================
   3
   4
   5 Recommended toolchains
   6 ----------------------
   7
   8 The UniPhier platform is well tested with Linaro toolchains.
   9 You can download pre-built toolchains from:
  10
  11     http://www.linaro.org/downloads/
  12
  13
  14 Compile the source
  15 ------------------
  16
  17 The 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
  22 The 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
  24 favorite compiler.
  25
  26 The following tables show <defconfig> and <device-tree> for each board.
  27
  28 32bit SoC boards:
  29
  30  Board         | <defconfig>                 | <device-tree>
  31 ---------------|-----------------------------|------------------------------
  32 LD4 reference  | uniphier_ld4_sld8_defconfig | uniphier-ld4-ref (default)
  33 sld8 reference | uniphier_ld4_sld8_defconfig | uniphier-sld8-def
  34 Pro4 reference | uniphier_v7_defconfig       | uniphier-pro4-ref
  35 Pro4 Ace       | uniphier_v7_defconfig       | uniphier-pro4-ace
  36 Pro4 Sanji     | uniphier_v7_defconfig       | uniphier-pro4-sanji
  37 Pro5 4KBOX     | uniphier_v7_defconfig       | uniphier-pro5-4kbox
  38 PXs2 Gentil    | uniphier_v7_defconfig       | uniphier-pxs2-gentil
  39 PXs2 Vodka     | uniphier_v7_defconfig       | uniphier-pxs2-vodka (default)
  40 LD6b reference | uniphier_v7_defconfig       | uniphier-ld6b-ref
  41
  42 64bit SoC boards:
  43
  44  Board         | <defconfig>           | <device-tree>
  45 ---------------|-----------------------|----------------------------
  46 LD11 reference | uniphier_v8_defconfig | uniphier-ld11-ref
  47 LD11 Global    | uniphier_v8_defconfig | uniphier-ld11-global
  48 LD20 reference | uniphier_v8_defconfig | uniphier-ld20-ref (default)
  49 LD20 Global    | uniphier_v8_defconfig | uniphier-ld20-global
  50 PXs3 reference | uniphier_v8_defconfig | uniphier-pxs3-ref
  51
  52 For 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
  57 The device tree marked as (default) can be omitted.  `uniphier-pxs2-vodka` is
  58 the default device tree for the configuration `uniphier_v7_defconfig`, so the
  59 following gives the same result.
  60
  61     $ make uniphier_v7_defconfig
  62     $ make CROSS_COMPILE=arm-linux-gnueabihf-
  63
  64
  65 Booting 32bit SoC boards
  66 ------------------------
  67
  68 The build command will generate the following:
  69 - u-boot.bin
  70 - spl/u-boot.bin
  71
  72 U-Boot can boot UniPhier 32bit SoC boards by itself.  Flash the generated images
  73 to 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
  78 The `u-boot-with-spl.bin` is the concatenation of the two (with appropriate
  79 padding), so you can also do:
  80
  81  - u-boot-with-spl.bin at the offset address 0x00000000
  82
  83 If a TFTP server is available, the images can be easily updated.
  84 Just copy the u-boot-spl.bin and u-boot.bin to the TFTP public directory,
  85 and run the following command at the U-Boot command line:
  86
  87 To update the images in NAND:
  88
  89     => run nandupdate
  90
  91 To update the images in eMMC:
  92
  93     => run emmcupdate
  94
  95
  96 Booting 64bit SoC boards
  97 ------------------------
  98
  99 The build command will generate the following:
 100 - u-boot.bin
 101
 102 However, U-Boot is not the first stage loader for UniPhier 64bit SoC boards.
 103 U-Boot serves as a non-secure boot loader loaded by [ARM Trusted Firmware],
 104 so you need to provide the `u-boot.bin` to the build command of ARM Trusted
 105 Firmware.
 106
 107 [ARM Trusted Firmware]: https://github.com/ARM-software/arm-trusted-firmware
 108
 109
 110 Verified Boot
 111 -------------
 112
 113 U-Boot supports an image verification method called "Verified Boot".
 114 This is a brief tutorial to utilize this feature for the UniPhier platform.
 115 You will find details documents in the doc/uImage.FIT directory.
 116
 117 Here, we take LD20 reference board for example, but it should work for any
 118 other boards including 32 bit SoCs.
 119
 120 1. 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
 127 Two files "dev.key" and "dev.crt" will be created.  The base name is arbitrary,
 128 but need to match to the "key-name-hint" property described below.
 129
 130 2. Describe FIT source
 131
 132 You need to write an FIT (Flattened Image Tree) source file to describe the
 133 structure of the image container.
 134
 135 The 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
 201 You need to change the three '/incbin/' lines, depending on the location of
 202 your kernel image, device tree blob, and init ramdisk.  The "load" and "entry"
 203 properties also need to be adjusted if you want to change the physical placement
 204 of the kernel.
 205
 206 The "key-name-hint" must specify the key name you have created in the step 1.
 207
 208 The FIT file name is arbitrary.  Let's say you saved it into "fit.its".
 209
 210 3. Compile U-Boot with FIT and signature enabled
 211
 212 To use the Verified Boot, you need to enable the following two options:
 213   CONFIG_FIT
 214   CONFIG_FIT_SIGNATURE
 215
 216 They are disabled by default for UniPhier defconfig files.  So, you need to
 217 tweak 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
 224 4. Build the image tree blob
 225
 226 After building U-Boot, you will see tools/mkimage.  With this tool, you can
 227 create an image tree blob as follows:
 228
 229   $ tools/mkimage -f fit.its -k keys -K dts/dt.dtb -r -F fitImage
 230
 231 The -k option must specify the key directory you have created in step 1.
 232
 233 A file "fitImage" will be created.  This includes kernel, DTB, Init-ramdisk,
 234 hash data for each of the three, and signature data.
 235
 236 The public key needed for the run-time verification is stored in "dts/dt.dtb".
 237
 238 5. Compile U-Boot again
 239
 240 Since the "dt.dtb" has been updated in step 4, you need to re-compile the
 241 U-Boot.
 242
 243   $ make CROSS_COMPILE=aarch64-linux-gnu-
 244
 245 The re-compiled "u-boot.bin" is appended with DTB that contains the public key.
 246
 247 6. Flash the image
 248
 249 Flash the "fitImage" to a storage device (NAND, eMMC, or whatever) on your
 250 board.
 251
 252 Please note the "u-boot.bin" must be signed, and verified by someone when it is
 253 loaded.  For ARMv8 SoCs, the "someone" is generally ARM Trusted Firmware BL2.
 254 ARM Trusted Firmware supports an image authentication mechanism called Trusted
 255 Board Boot (TBB).  The verification process must be chained from the moment of
 256 the system reset.  If the Chain of Trust has a breakage somewhere, the verified
 257 boot process is entirely pointless.
 258
 259 7. Boot verified kernel
 260
 261 Load the fitImage to memory and run the following from the U-Boot command line.
 262
 263   > bootm <addr>
 264
 265 Here, <addr> is the base address of the fitImage.
 266
 267 If 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
 321 Starting kernel ...
 322 ---------------------------------------->8----------------------------------------
 323
 324 Please pay attention to the lines that start with "Verifying Hash Integrity".
 325
 326 "Verifying Hash Integrity ... sha256,rsa2048:dev+ OK" means the signature check
 327 passed.
 328
 329 "Verifying Hash Integrity ... sha256+ OK" (3 times) means the hash check passed
 330 for kernel, DTB, and Init ramdisk.
 331
 332 If they are not displayed, the Verified Boot is not working.
 333
 334
 335 Deployment for Distro Boot
 336 --------------------------
 337
 338 UniPhier SoC family boot the kernel in a generic manner as described in
 339 doc/README.distro .
 340
 341 To boot the kernel, you need to deploy necesssary components to a file
 342 system on one of your block devices (eMMC, NAND, USB drive, etc.).
 343
 344 The components depend on the kernel image format.
 345
 346 [1] Bare images
 347
 348   - kernel
 349   - init ramdisk
 350   - device tree blob
 351   - boot configuration file (extlinux.conf)
 352
 353 Here is an exmple of the configuration file.
 354
 355 -------------------->8--------------------
 356 menu title UniPhier Boot Options.
 357
 358 timeout 50
 359 default UniPhier
 360
 361 label UniPhier
 362       kernel ../Image
 363       initrd ../rootfs.cpio.gz
 364       fdtdir ..
 365 -------------------->8--------------------
 366
 367 Then, write 'Image', 'rootfs.cpio.gz', 'uniphier-ld20-ref.dtb' (DTB depends on
 368 your board), and 'extlinux/extlinux.conf' to the file system.
 369
 370 [2] FIT
 371
 372   - FIT blob
 373   - boot configuration file (extlinux.conf)
 374
 375 -------------------->8--------------------
 376 menu title UniPhier Boot Options.
 377
 378 timeout 50
 379 default UniPhier
 380
 381 label UniPhier
 382       kernel ../fitImage
 383 -------------------->8--------------------
 384
 385 Since the init ramdisk and DTB are contained in the FIT blob,
 386 you do not need to describe them in the configuration file.
 387 Write 'fitImage' and 'extlinux/extlinux.conf' to the file system.
 388
 389
 390 UniPhier specific commands
 391 --------------------------
 392
 393  - pinmon (enabled by CONFIG_CMD_PINMON)
 394      shows the boot mode pins that has been latched at the power-on reset
 395
 396  - ddrphy (enabled by CONFIG_CMD_DDRPHY_DUMP)
 397      shows the DDR PHY parameters set by the PHY training
 398
 399  - ddrmphy (enabled by CONFIG_CMD_DDRMPHY_DUMP)
 400      shows the DDR Multi PHY parameters set by the PHY training
 401
 402
 403 Supported devices
 404 -----------------
 405
 406  - UART (on-chip)
 407  - NAND
 408  - SD/eMMC
 409  - USB 2.0 (EHCI)
 410  - USB 3.0 (xHCI)
 411  - GPIO
 412  - LAN (on-board SMSC9118)
 413  - I2C
 414  - EEPROM (connected to the on-board I2C bus)
 415  - Support card (SRAM, NOR flash, some peripherals)
 416
 417
 418 Micro Support Card
 419 ------------------
 420
 421 The recommended bit switch settings are as follows:
 422
 423  SW2    OFF(1)/ON(0)   Description
 424  ------------------------------------------
 425  bit 1   <----         BKSZ[0]
 426  bit 2   ---->         BKSZ[1]
 427  bit 3   <----         SoC Bus Width 16/32
 428  bit 4   <----         SERIAL_SEL[0]
 429  bit 5   ---->         SERIAL_SEL[1]
 430  bit 6   ---->         BOOTSWAP_EN
 431  bit 7   <----         CS1/CS5
 432  bit 8   <----         SOC_SERIAL_DISABLE
 433
 434  SW8    OFF(1)/ON(0)   Description
 435  ------------------------------------------
 436  bit 1    <----        CS1_SPLIT
 437  bit 2    <----        CASE9_ON
 438  bit 3    <----        CASE10_ON
 439  bit 4  Don't Care     Reserve
 440  bit 5  Don't Care     Reserve
 441  bit 6  Don't Care     Reserve
 442  bit 7    ---->        BURST_EN
 443  bit 8    ---->        FLASHBUS32_16
 444
 445 The BKSZ[1:0] specifies the address range of memory slot and peripherals
 446 as follows:
 447
 448  BKSZ    Description              RAM slot            Peripherals
 449  --------------------------------------------------------------------
 450  0b00   15MB RAM / 1MB Peri    00000000-00efffff    00f00000-00ffffff
 451  0b01   31MB RAM / 1MB Peri    00000000-01efffff    01f00000-01ffffff
 452  0b10   64MB RAM / 1MB Peri    00000000-03efffff    03f00000-03ffffff
 453  0b11  127MB RAM / 1MB Peri    00000000-07efffff    07f00000-07ffffff
 454
 455 Set BSKZ[1:0] to 0b01 for U-Boot.
 456 This mode is the most handy because EA[24] is always supported by the save pin
 457 mode of the system bus.  On the other hand, EA[25] is not supported for some
 458 newer SoCs.  Even if it is, EA[25] is not connected on most of the boards.
 459
 460 --
 461 Masahiro Yamada <yamada.masahiro@socionext.com>
 462 Oct. 2017