README.altboot
1/// notes about altboot ///
2
3$NetBSD: README.altboot,v 1.11 2012/04/26 19:59:36 phx Exp $
4
5Altboot is a functional bridge to fill the gap between a NAS product
6custom bootloader and the NetBSD kernel startup environment. Altboot
7irons out and rectifies erroneously configured HW by product
8bootloaders and prepares a sane runtime, better suited for booting
9NetBSD kernels.
10
11- provides the foundation of a fast NetBSD porting cycle with functionalities
12 product bootloaders don't have.
13- facilitates a flexible and clean NetBSD implementation tailoured
14 to target HW in detail, minimizing bumpy adjustments and hacks in
15 locore asm and machdeps in very early kernel startup stage.
16- levels out differences among similar-but-not-the-same porting
17 targets to make it possible having common NetBSD kernels for them.
18- builds and hands a bootinfo list to the NetBSD kernel.
19
20Altboot is known working on at least these models:
21
22- KuroBox or LinkStation with a popular U-Boot as replacement of
23 the vendor's proprietary one
24
25 U-Boot 1.1.4 LiSt 2.1.0 (Sep 21 2006 - 00:22:56) LinkStation / KuroBox
26
27- Synology 101g+ with vendor custom PPCboot
28
29 PPCBoot 2.0.0 (Mar 1 2005 - 15:31:41)
30
31- Synology 106j, 207, 407e with vendor custom PPCboot
32
33 PPCBoot 2.0.0 (Jan 30 2007 - xx:xx:xx)
34
35- D-Link DSM-G600 with heavily restricted vendor custom U-Boot
36
37 U-Boot 0.2.0 (May 26 2005 - 19:38:32)
38
39- QNAP TS-101 (V200) with vendor custom U-Boot
40
41 U-Boot 1.1.2 (Aug 28 2005 - 13:37:25) QNAP System, Inc.
42
43- Iomega StorCenter with vendor custom U-Boot
44
45 U-Boot 1.0.0 (Sep 2 2005 - 14:49:11)
46
47- Allnet 6250 and compatible with restricted vendor custom PPCboot
48
49 PPCBoot 2.0.0-A9 (Feb 13 2006 - 14:56:11)
50
51- KURO-BOX/T4 vendor custom U-Boot
52
53 U-Boot 2009.06-BUFFALO-svn1376 (Jul 11 2009 - 04:11:01) KURO-NAS/T4
54
55The standard use of altboot is to invoke it with a short script from
56U-Boot/PPCboot, where the altboot.bin image is stored in an unoccupied 128KB
57section of the target's HW NOR flash. Combined with standard
58U-Boot/PPCboot functions, it is possible to boot a NetBSD kernel off
59it right after power-on, without the help of manual intervention. Note
60that the original U-Boot/PPCboot still remains useful and altboot works
61as a functional extension for them.
62
63In case the firmware was crippled by the vendor so that it only boots
64Linux U-Boot images (D-Link, Synology 2007), you can still use altboot by
65overwriting the Linux kernel with altboot.img.
66
67Altboot passes the following bootinfo records to the NetBSD/sandpoint
68kernel:
69- processor clock tick value driving MPC8241/8245.
70- serial console selection.
71- booted kernel filename and which device it was fetched from.
72- Ethernet MAC address, if target HW lacks SEEPROM to store a unit unique
73 value.
74- product family indication.
75- preloaded kernel module names (under development).
76
77When no arguments are given, altboot defaults to boot a kernel called
78"netbsd" from the root partition of the first disk in multiuser mode.
79
80Boot arguments may be passed in three ways:
81- On the command line, directly after the "go 0x1000000" command.
82- From the U-Boot "bootargs" environment variable, when started by "bootm".
83- By entering the interactive mode.
84
85The following boot arguments are recognized:
86- multi boot into multiuser
87- auto boot into multiuser
88- single boot into singleuser
89- ask ask for boot device
90- ddb drop into the kernel debugger
91- userconf change configured devices
92
93The following boot flags are recognized:
94- norm boot normally
95- quiet boot quietly
96- verb boot verbosely
97- silent boot silently
98- debug boot with debug output
99
100Additionally the special argument "altboot" is recognized, which replaces
101the actually running altboot program with the loaded binary file and
102restarts itself. Mainly useful for altboot testing.
103
104Multiple arguments may be specified at once, although not all combinations
105make sense. The format of an altboot command line is:
106
107 [[<bootargs> ...] <devicename>:[<bootfile>] ...]
108
109Multiple boot devices and/or paths may be specified, which are booted one
110after another until success. When no boot device is specified altboot tries
111to boot from all disk devices with a valid NetBSD disklabel, starting with
112unit 0.
113
114The following device names are supported:
115- tftp boot from TFTP (address retrieved by DHCP)
116- nfs boot from NFS (address retrieved by DHCP)
117- wd[N[P]] boot from disk N, partition P, defaults to wd0a
118- mem boot from memory
119
120For tftp and nfs the bootfile is determined by DHCP, when missing.
121For wd it defaults to "netbsd".
122For mem the bootfile is actually a hexadecimal address to load from and
123is mandatory.
124
125 ### ### ###
126