Home | History | Annotate | Line # | Download | only in altboot 
      1 /// notes about altboot ///
      2 
      3 $NetBSD: README.altboot,v 1.11 2012/04/26 19:59:36 phx Exp $
      4 
      5 Altboot is a functional bridge to fill the gap between a NAS product
      6 custom bootloader and the NetBSD kernel startup environment.  Altboot
      7 irons out and rectifies erroneously configured HW by product
      8 bootloaders and prepares a sane runtime, better suited for booting
      9 NetBSD 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 
     20 Altboot 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 
     55 The standard use of altboot is to invoke it with a short script from
     56 U-Boot/PPCboot, where the altboot.bin image is stored in an unoccupied 128KB
     57 section of the target's HW NOR flash.  Combined with standard
     58 U-Boot/PPCboot functions, it is possible to boot a NetBSD kernel off
     59 it right after power-on, without the help of manual intervention.  Note
     60 that the original U-Boot/PPCboot still remains useful and altboot works
     61 as a functional extension for them.
     62 
     63 In case the firmware was crippled by the vendor so that it only boots
     64 Linux U-Boot images (D-Link, Synology 2007), you can still use altboot by
     65 overwriting the Linux kernel with altboot.img.
     66 
     67 Altboot passes the following bootinfo records to the NetBSD/sandpoint
     68 kernel:
     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 
     77 When 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 
     80 Boot 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 
     85 The 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 
     93 The 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 
    100 Additionally the special argument "altboot" is recognized, which replaces
    101 the actually running altboot program with the loaded binary file and
    102 restarts itself. Mainly useful for altboot testing.
    103 
    104 Multiple arguments may be specified at once, although not all combinations
    105 make sense. The format of an altboot command line is:
    106 
    107   [[<bootargs> ...] <devicename>:[<bootfile>] ...]
    108 
    109 Multiple boot devices and/or paths may be specified, which are booted one
    110 after another until success. When no boot device is specified altboot tries
    111 to boot from all disk devices with a valid NetBSD disklabel, starting with
    112 unit 0.
    113 
    114 The 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 
    120 For tftp and nfs the bootfile is determined by DHCP, when missing.
    121 For wd it defaults to "netbsd".
    122 For mem the bootfile is actually a hexadecimal address to load from and
    123 is mandatory.
    124 
    125                              ### ### ###
    126