stand/altboot/README.altboot

/// notes about altboot ///

$NetBSD: README.altboot,v 1.4 2011/04/19 14:12:54 phx Exp $

Altboot is a functional bridge to fill the gap between a NAS product
custom bootloader and the NetBSD kernel startup environment.  Altboot
irons out and rectifies erroneously configured HW by product
bootloaders and prepares a sane runtime, better suited for booting
NetBSD kernels.

- provides the foundation of a fast NetBSD porting cycle with functionalities
  product bootloaders don't have.
- facilitates a flexible and clean NetBSD implementation tailoured
  to target HW in detail, minimizing bumpy adjustments and hacks in
  locore asm and machdeps in very early kernel startup stage.
- levels out differences among similar-but-not-the-same porting
  targets to make it possible having common NetBSD kernels for them.
- builds and hands a bootinfo list to the NetBSD kernel.

Altboot is known working on at least these models:

- KuroBox or LinkStation with a popular U-Boot as the replacement of
  vendor proprietary

   U-Boot 1.1.4 LiSt 2.1.0 (Sep 21 2006 - 00:22:56) LinkStation / KuroBox

- Synology 101g+ with vendor custom PPCboot

   PPCBoot 2.0.0 (Mar  1 2005 - 15:31:41)

- D-Link DSM-G600 with heavily restricted vendor custom U-Boot

   U-Boot 0.2.0 (May 26 2005 - 19:38:32)

- QNAP TS-101 (V200) with vendor custom U-Boot

   U-Boot 1.1.2 (Aug 28 2005 - 13:37:25) QNAP System, Inc.

The standard use of altboot is to invoke it with a short script from
U-Boot/PPCboot, where the altboot.bin image is stored in an unoccupied 128KB
section of the target's HW NOR flash.  Combined with standard
U-Boot/PPCboot functions, it is possible to boot a NetBSD kernel off
it right after power-on, without the help of manual intervention.  Note
that the original U-Boot/PPCboot still remains useful and altboot works
as a functional extension for them.

In case the firmware was crippled by the vendor so that it only boots
Linux U-Boot images (D-Link), you can still use altboot by uploading
altboot.img instead of the Linux kernel.

Altboot hands the following bootinfo records to the NetBSD/sandpoint
kernel.
- processor clock tick value driving MPC8241/8245.
- serial console selection.
- booted kernel filename and which device it was fetched from.
- Ethernet MAC address, if target HW lacks SEEPROM to store a unit unique
  value.
- product family indication.
- preloaded kernel module names (under development).

When no arguments are given, altboot defaults to boot a kernel called
"netbsd" from the root partition of the first disk in multiuser mode.

Boot arguments may be passed in three ways:
- On the command line, directly after the "go 0x1000000" command.
- From the U-Boot "bootargs" environment variable, when started by "bootm".
- By entering the interactive mode.

The following boot arguments are recognized:
- multi			boot into multiuser
- auto			boot into multiuser
- single		boot into singleuser
- ask			ask for boot device
- ddb			drop into the kernel debugger
- userconf		change configured devices

The following boot flags are recognized:
- norm			boot normally
- quiet			boot quietly
- verb			boot verbosely
- silent		boot silently
- debug			boot with debug output

Additionally the special argument "altboot" is recognized, which replaces
the actually running altboot program with the loaded binary file and
restarts itself. Mainly useful for altboot testing.

Multiple arguments may be specified at once, although not all combinations
make sense. The format of an altboot command line is:

  [[<bootargs> ...] <devicename>:[<bootfile>]]

The following device names are supported:
- tftp			boot from TFTP (address retrieved by DHCP)
- nfs			boot from NFS (address retrieved by DHCP)
- wd[N[P]]		boot from disk N, partition P, defaults to wd0a
- mem			boot from memory

For tftp and nfs the bootfile is determined by DHCP, when missing.
For wd it defaults to "netbsd".
For mem the bootfile is actually a hexadecimal address to load from and
is mandatory.

                             ### ### ###