[U-Boot] [PATCH 12/12] README: Add instructions for chain-loading U-Boot

[Simon Glass <sjg@chromium.org>]

Most Chromebooks support chain-loading U-Boot but instructions are
somewhat scattered. Add a README to hold this information within the
U-Boot tree. Also add the standard developer keys to simplify the
instructions, since they are small.

For now this only supports nyan-big.

Signed-off-by: Simon Glass <sjg@chromium.org>
---

 doc/README.chromium                          | 222 +++++++++++++++++++++++++++
 doc/chromium/devkeys/kernel.keyblock         | Bin 0 -> 1208 bytes
 doc/chromium/devkeys/kernel_data_key.vbprivk | Bin 0 -> 1199 bytes
 3 files changed, 222 insertions(+)
 create mode 100644 doc/README.chromium
 create mode 100644 doc/chromium/devkeys/kernel.keyblock
 create mode 100644 doc/chromium/devkeys/kernel_data_key.vbprivk

diff --git a/doc/README.chromium b/doc/README.chromium
new file mode 100644
index 0000000000..1dd111c65d
--- /dev/null
+++ b/doc/README.chromium
@@ -0,0 +1,222 @@
+Running U-Boot from coreboot on Chromebooks
+===========================================
+
+U-Boot can be used as a secondary boot loader in a few situations such as from
+UEFI and coreboot (see README.x86). Recent Chromebooks use coreboot even on
+ARM platforms to start up the machine.
+
+This document aims to provide a guide to booting U-Boot on a Chromebook. It
+is only a starting point, and there are many guides on the interwebs. But
+placing this information in the U-Boot tree should make it easier to find for
+those who use U-Boot habitually.
+
+Most of these platforms are supported by U-Boot natively, but it is risky to
+replace the ROM unless you have a servo board and cable to restore it with.
+
+
+For all of these the standard U-Boot build instructions apply. For example on
+ARM:
+
+   sudo apt install gcc-arm-linux-gnueabi
+   mkdir b
+   make O=b/nyan_big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all
+
+You can obtain the vbutil_kernel utility here:
+
+   https://drive.google.com/open?id=0B7WYZbZ9zd-3dHlVVXo4VXE2T0U
+
+
+Snow (Samsung ARM Chromebook)
+-----------------------------
+
+See here:
+
+https://www.chromium.org/chromium-os/firmware-porting-guide/using-nv-u-boot-on-the-samsung-arm-chromebook
+
+
+Nyan-big
+--------
+
+Compiled based on information here:
+https://lists.denx.de/pipermail/u-boot/2015-March/209530.html
+https://git.collabora.com/cgit/user/tomeu/u-boot.git/commit/?h=nyan-big
+https://lists.denx.de/pipermail/u-boot/2017-May/289491.html
+https://github.com/chromeos-nvidia-androidtv/gnu-linux-on-acer-chromebook-13#copy-data-to-the-sd-card
+
+1. Patch U-Boot
+
+Open include/configs/tegra124-common.h
+
+Change:
+
+#define CONFIG_SYS_TEXT_BASE	0x80110000
+
+to:
+
+#define CONFIG_SYS_TEXT_BASE	0x81000100
+
+
+2. Build U-Boot
+
+   mkdir b
+   make -j8 O=b/nyan-big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all
+
+
+3. Create a file called u-boot.its as follows:
+
+/dts-v1/;
+
+/ {
+	description = "U-Boot mainline";
+	#address-cells = <1>;
+
+	images {
+		kernel at 1 {
+			description = "U-Boot mainline";
+			type = "kernel_noload";
+			arch = "arm";
+			os = "linux";
+			data = /incbin/("./b/nyan-big/u-boot.bin");
+			compression = "none";
+			load = <0>;
+			entry = <0>;
+			hash at 2 {
+				algo = "sha1";
+			};
+		};
+
+		fdt at 1{
+			description = "tegra124-nyan-big.dtb";
+			data = /incbin/("./b/nyan-big/u-boot.dtb");
+			type = "flat_dt";
+			arch = "arm";
+			compression = "none";
+			hash at 1{
+				algo = "sha1";
+			};
+		};
+	};
+
+	configurations {
+		default = "config at 1";
+		config at 1 {
+			description = "Boot U-Boot";
+			kernel = "kernel at 1";
+			fdt = "fdt at 1";
+		};
+	};
+};
+
+
+Note that the device tree node is required, even though it is not actually
+used by U-Boot. This is because the Chromebook expects to pass it to the
+kernel, and crashes if it is not present.
+
+
+4. Build and sign an image
+
+   ./b/nyan-big/tools/mkimage -f u-boot.its u-boot-chromium.fit
+   vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \
+	--signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \
+	--version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
+	--bootloader dummy.txt --pack u-boot.kpart
+
+
+5. Prepare an SD card
+
+   DISK=/dev/sdc   # Replace with your actual SD card device
+   sudo cgpt create $DISK
+   sudo cgpt add -b 34 -s 32768 -P 1 -S 1 -t kernel $DISK
+   sudo cgpt add -b 32802 -s 2000000 -t rootfs $DISK
+   sudo gdisk $DISK   #
+
+
+6. Write U-Boot to the SD card
+
+   sudo dd if=u-boot.kpart of=/dev/sdc1; sync
+
+
+7. Start it up
+
+Reboot the device in dev mode. Make sure that you have USB booting enabled. To
+do this, login as root (via Ctrl-Alt-forward_arrow) and type
+'enable_dev_usb_boot'. You only need to do this once.
+
+Reboot the device with the SD card inserted. Press Clrl-U at the developer
+mode screen. It should show something like the following on the display:
+
+   U-Boot 2017.07-00637-g242eb42-dirty (May 22 2017 - 06:14:21 -0600)
+
+   Model: Acer Chromebook 13 CB5-311
+   Board: Google/NVIDIA Nyan-big, ID: 1
+
+   Net:   No ethernet found.
+   Hit any key to stop autoboot:  0
+   Tegra124 (Nyan-big) #
+
+
+8. Known problems
+
+On the serial console the word MMC is chopped at the start of the line:
+
+C:   sdhci at 700b0000: 2, sdhci at 700b0400: 1, sdhci at 700b0600: 0
+
+This is likely due to some problem with change-over of the serial driver
+during relocation (or perhaps updating the clock setup in board_init()).
+
+
+9. Notes
+
+To check that you copied the u-boot.its file correctly, use these commands.
+You should see that the data at 0x100 in u-boot-chromium.fit is the first few
+bytes of U-Boot:
+
+   hd u-boot-chromium.fit |head -20
+   ...
+   00000100  b8 00 00 ea 14 f0 9f e5  14 f0 9f e5 14 f0 9f e5  |................|
+
+   hd b/nyan-big/u-boot.bin |head
+   00000000  b8 00 00 ea 14 f0 9f e5  14 f0 9f e5 14 f0 9f e5  |................|
+
+
+The 'data' property of the FIT is set up to start at offset 0x100 bytes into
+the file. The change to CONFIG_SYS_TEXT_BASE is also an offset of 0x100 bytes
+from the load address. If this changes, you either need to modify U-Boot to be
+fully relocatable, or expect it to hang.
+
+
+Other notes
+===========
+
+flashrom
+--------
+
+   Used to make a backup of your firmware, or to replace it.
+
+   See: https://www.chromium.org/chromium-os/packages/cros-flashrom
+
+
+coreboot
+--------
+
+Coreboot itself is not designed to actually boot an OS. Instead, a program
+called Depthcharge is used. This originally came out of U-Boot and was then
+heavily hacked and modified such that is is almost unrecognisable. It does
+include a very small part of the U-Boot command-line interface but is not
+usable as a general-purpose boot loader.
+
+In addition, it has a very unusual design in that it does not do device init
+itself, but instead relies on coreboot. This is similar to (in U-Boot) having
+a SPI driver with an empty probe() method, relying on whatever was set up
+beforehand. It can be quite hard to figure out between these two code bases
+what settings are actually used. When chain-loading into U-Boot we must be
+careful to reinit anything that U-Boot expects. If not, some peripherals (or
+the whole machine) may not work. This makes the process of chainloading more
+complicated than it could be on some platforms.
+
+Finally, it supports only a subset of the U-Boot's FIT format. In particular
+it uses a fixed address to load the FIT and does not support load/exec
+addresses. This means that U-Boot must be able to boot from whatever
+address Depthcharge happens to use (it is the CONFIG_KERNEL_START setting
+in Depthcharge). In practice this means that the data in the kernel at 1 FIT node
+(see above) must start at the same address as U-Boot's CONFIG_SYS_TEXT_BASE.
diff --git a/doc/chromium/devkeys/kernel.keyblock b/doc/chromium/devkeys/kernel.keyblock
new file mode 100644
index 0000000000000000000000000000000000000000..9740be4e60070658d01e96c13acba8e726f68a59
GIT binary patch
literal 1208
zcmZ?v2=e!J^$%uZU|?Vb;vFnN0tgm>1V8{vS3qeGDD422WMF`avqSj`P?`g(4r(0O
zY><=#5T9mpaFo?;<IfE~b7uK$=~H)<jvTToS}LUYuR?YXb1Ki2UAED2GsL>quTPJ1
z>(Ke2mAdzM<e7q(jDEE}&U!MrMWX936wcpb_1vZDVsrQ0oRpdCZ+D%!c&&Nal2<Dm
zW#>yr_58T4rnsp(c+!WgqdkJV>YPu at g)hvz`magDHh1sz4KIGncd$uw9qpf%>5=KE
z6?A>OaYc9j^yRg8E@<CuOh0MAa*G@{N60b8V+zlXamI5UWn#^Cm?o(3bWw+S*5zBb
zZk5SAvDNvP+BRd+3eQ?KR}mJ0#}?jcb7FK}++@3Qn01OwwQ^^htkG`e3ED;1Cj<ux
z2wgbzsHm~PW}~{(oBi4$*G?zC+Hz&Zz0db;FN)u5>- at 4%BktA~cgfj@&UwB{zU3s-
zDziH0`k}uj(pLo+xood$O=RA6CFP-K`=n=gET_!b^*&-ApV^G-mwZGDr&O$Od#?ZT
zr-JXlTi5M74 at R!rn=pI&k~D_h)fYTl^Q#$E4tqR0o;YL9)5+~DoK}-U<hM3xiaxFX
zcW3?Ohe=1a-PV`l_#DD!buO;6@V<3SPj>T49 at c>B7EXz at mWOo-*Y50>Src>Tna{ih
zUXcd>Cr*%4)C`ze_E$eDJ&PgRLH+q&@n`Y#o at 75@omYE$!b_Vul_%YQMC`HOxb%Jc
z2c?At#%3F0-oEm?r@|9`!*}1BEFr^Xaq%qMA{JiMTx>iiWn-W9ul1%=s+N2`Juh9l
z*YuP?X78(tL*J4Q2!8yQR-iZS!=7q6F|~V->koX%vEdGS#D1@!dwt7PX}77Ftdm}u
zEj<-*+w+9WyBbdi6V}gc at -k;ClBDN8^0#A|w(G+2MOLf6A6|DL`_zfZ2@hPWy%YAY
z6IH#iNPlXUp1F!>CZAQVgW|W6m}T=HFek7?78ERS`*NSlTV!=R&#IK!O{Ww$6#eQp
z|C(@pyI)b9uyS!r&c)uMMWWq-785ci-0V&@NW2}`5OMeL2TkKUmXr3YKRe#^?bUh3
zOA9QR!h^ovWuN(&^ZMF(a?d}<6)iY6*RgF{Q;C~A>m^oIP4%>gt7F){ta*On$FsO@
z$<RYH`<Cma@n|J(nBh2?HDto7eWGg7<ux0AaAa)Tapmrf75;a>O at 6wtL%NE!@#qW_
z*^cDU^|Kb9_Fmt%+4a_vElUNe0<xao%I`lQJ9XnkkKn^k<@s1kR~^4$b|E*w<I1zW
z7j&nK>uz>iEy?#}&ELtZd3 at IHkC0xac9!?n`qQsBNXEFy&)%>@C}+9fj^*+~*+2Gq
zuVmTs)9lR6s}tAMy%auBf9m?3eJeLy(-7CccAqcXL-1PQ@!a-r9NTj;zhBb`s4H1J
zEsN(=_QsF*7RM`p)p8N!U;JIgOxpNa-A%rw-3xYfx4ygZB-8oW&v^BvCljsv)+d!a
zZBvhbJFRW=dm}?<z3TPRk4l@0)>_9-Iw-p8w<7z?RYx9OpV^#KWSMWOF!#ZYAGeEC
Tp7v_~RjJ<N@pAW}mg74Ct|TeM

literal 0
HcmV?d00001

diff --git a/doc/chromium/devkeys/kernel_data_key.vbprivk b/doc/chromium/devkeys/kernel_data_key.vbprivk
new file mode 100644
index 0000000000000000000000000000000000000000..8d392fb294c15edb09cbf1bf775a1d87d0d2bc2d
GIT binary patch
literal 1199
zcmV;g1W@|~000000000mf&`-i0RRGm0RaHZ)>JFM>_R88JaB<>;=<4p5K>c+*K#Y6
zBfBykhKVD49Fzsa)CSq;EL at ysOE}{Y1QbOkeMzXIn1*HkEIs5LcG}w7(`q+}qU9hF
zmOyI-0>uhn3C89i#sS7u2n!yxsXxhQf!Qn2+<m8)Z;N;{x7SiCL1{>7mXE~>8wQ9U
z`{=Njy=^@xg8tQRp;sQuLw>pujKym3l2d!KAtu}Sj9MF?9f7Ipq^5(`(aeh5ubE_Q
zor{Cff<)&!w4ZU%uN87_94<qQeNF-CaLif9y=5x!EQm&0XRoh{7MNaJJ-U<(WdocY
zc>W<0rE)sL#3J0v8=I%h%u{U-hAkZe0|5X50)hbmO}OfvNAK|kt9k7>9<xF(4n#EX
z@-c)m0wV3S-8VQvR3`v+_C|SHOF`!fC!-Y%*F}cu8x;7e8C_`^sKNWwXWJF_4=g{r
z?-`Yz6}F+*Y_PJc60_>4Lgd{xUqUtGK4q?vz$)#)+(E{Z$(32Fx}>GBiMA<A*dFz;
z-ujUdRo0#1r=0Tioqv`|daLQ049gH)XYd{KGlZ^g<h!R=n3*f{9jojCqAolTT>t3I
zP(>jx1Zmv at TM*V%HcWF29>M>tU|qZugy^KbX3EO1Rf_nB7n8qcq?hSOfdl$XGWP6x
z1G_Cdo9f(bVSfe4El`Q+5IsBsuw6bSanhmT0)c at 5_B?+TV+0D+Xz1BXf4s`IgaL68
zGfm+N=%<y;BUu@>f~v0MkTaDa8vXB%Ho;fkl--$c6bz0q;OAsBryc#7+*nCYR)Rz7
z+4syE^$9pk_J at zAK$g*gV!KIGX;$A#h5d3gAy%V%+E65j#tQ?K4dMeTJX+mz=LZ3O
z-8g|60)c at 5)9Z3S_L~EYtJy(EzHA47*URp|MH3!VHPYm26Y1FF^eA5I*wTk!+@~Sf
zGtSCjP#cH8afpy{Z{FK89Xzow8$q~Lp<Jl4a~nBnT%lK+F3k;bLf<OWPf^@8Toi^D
zxFU>mH+pQh{s9}P#qs~z)MHqI;cBnKJ-Zh_Ecv*l0)c at 5(H?83R3aF-a42AMm={y%
zcqM5{{82@)C<;4M)hSelEM%OAj921p6Tn$?W7sRP;-{D?7t`71bo$Q3cSk21MqtcP
z^>auL>GEQ#`ZG*dK!3btt1#-=foma1?~75hPP_sGchtt7=C^HcqY<-)M~n=(5AE}4
z{b`%Pvf<0|0)c==#@pe5`$V)hu-KfPe0K!9jo_~U;^DpMyatVD88X)IG>m^ZYZuGG
z<`3tkW$Q6NkMc%-B%T>W!>MuT(cD{KKNHb~lI+B+tm^;8a2--M&qXc{r+OwB*S<6q
z492_9!@4BE;-YNO=#A7+NCK;qLz>IQ{adyJ=lENpDaHW;fq)Jeya1zt+QP{D3cY`~
zf1wzENw_kDOK~+>QG4!=PSQfCY=T$!H1>j7>2-RK3XMh{p?9H7vz~^N7~ekofzZ5V
zqO*YTk8>}z#J~frB>GPU;}$7=|6|n(3cc55I<;QsBm6xG>SDs<O1p+y#go^(v`o*>
Nc%M>kp-Cb4AVU2jMyUV*

literal 0
HcmV?d00001

-- 
2.13.0.303.g4ebf302169-goog