docs/README

This is the first attempt at a complete boot loader for Linux on Sparc.
Because of the lack of space on the bootblock, we have to do it in two
steps, the first step is a very simple loader based on Peter Zaitcev's
silo (we will call this the first stage loader) which should fit in 512B
and its sole purpose is to load a more complete bootstrap loader, herein
refered to as the second stage boot loader. The cool thing about the
second stage loader we implemented is that it makes use of the ext2
library (provided with the ext2fs tools) and some ufs code, and thus
allows the loader to access any file on a ext2 fs and ufs, uses silo.conf,
handles gunzipping and a lot of other things.  This is different from
Linux/i386 lilo which needs a map for each kernel. In silo we just keep
one map file for the second stage loader, we don't expect you to be
changing the second stage loader on your daily routine (you can do so, you
will just need to use a tool to reinstall the maps).

There are two distinct versions of the Sun EPROM, those before 2.0 ("old")
and those of 2.0 and later ("new"). Unfortunately these details are
visible at various points.  With old proms, the device is specified as
dev(X,Y,Z) [e.g. sd(0,3,1)] where dev is the device (normally sd), X is
the controller, Y is the unit number, and Z is the partition number. Note
that numbers start at 0, rather than Linux's convention of starting at 1,
so sd(0,3,1) is /dev/sda2.  Note also that many systems have the "first"
disk (sda) as unit 3.  With new proms, the device is specified in "open
boot prom" format, e.g. /iommu/sbus/espdma/esp/sd@1,0  is target 1, LUN 0
and /sbus/esp@0,800000/sd@3,0 is target 3, LUN 0.

Due to a bug in some (all??) v2 PROMs (what about v0??) all the files
which SILO can load must be below a magic boundary 1GB from the start of
the disk (not from start of the partition). The easiest way is to put your
/ filesystem completely inside first 1GB (and if you want to boot other OS
on the same harddisk, put their / partitions under that boundary as well).
Then just make sure you always leave the images you want to boot in those
partitions...

During the installation, SILO saves the original boot loader under a user
especified file name, so, when silo prompts for a kernel name it is
possible to load the original boot loader, either by adding it to your
silo.conf or by typing its path on your SILO command line.  Assuming the
original boot block is stored in boot/old.b on partition 4, it can be
accessed by having silo.conf containing:

	other = 1
		bootblock = 4/boot/old.b
		label=sunos

(old proms need "other = sd(0,3,0) bootblock = sd(0,3,3)/boot/old.b") or
by typing 1 bootblock=/boot/old.b on your SILO command line.

There is a magic image name `halt' that gets you back to the prom, and
`help' displays some help text.

   If you wan to uninstall SILO, restore the original blocks by running e.g.
	dd if=/boot/old.b of=/dev/sda bs=512 seek=1 count=15

1. Installation.

You need all the proper compilers and linkers for Linux/SPARC native ELF
compile, if you want to compile SILO yourself. But the standard
distribution comes with all the necessary binaries.

Under the boot, etc and sbin subdirs you will find all the programs
already compiled and ready to run on Linux/SPARC. Those three directories
should be probably copied to your /boot, /etc and /sbin on your root
partition to make things easy.  Then you just run /sbin/silo and if /boot
doesn't contain old.b file yet, your old loader (usually sunos or solaris)
will be copied there and silo will be installed. Bootblocks will be
installed after the label of the disk which contains your second.b and
silo.conf (both have to be on the same physical disk), e.g. if second.b is
on /dev/sda5 and silo.conf on /dev/sda1, bootblocks will be installed into
/dev/sda.  In case you are creating a new root file system (e.g. your
current root filesystem is nfs and you are setting up an ext2 root
filesystem in /mnt), then you should run silo after installing boot, etc
and sbin directories into /mnt/boot, /mnt/etc and /mnt/sbin with the -r
parameter, e.g.  /mnt/sbin/silo -r /mnt

The firts loader pumps you into the second one very quickly, printing
letters SILO after some actions are performed. If it prints only some of
these letters and then dies, it means some error happened, e.g. if it
prints SIL it means that it loaded a second stage loader, but with wrong
magic.  Then SILO prints a boot: prompt. If you give silo arguments on the
prom command line already, SILO will try to load it (image params). This
image can be either a full name (described later) or alias or label of
some image in case you have silo.conf.

Otherwise SILO refers to your silo.conf file, which is similar the iX86
lilo.conf with some additions and omissions (some are not needed, others
are not implemented).  To the boot: prompt, you can:

1) wait for the timeout (if any) to expire, which loads the "default"
2) press enter, which loads the "default"
3) type "halt" to get back to prom
4) type "help" to get some help
5) type an alias or label present in silo.conf
6) press TAB to list the label names and aliases in silo.conf
7) type the full path of the image to load

where the "default" is the image marked as default=image, or the first
one.  The last option is the only one if you have no silo.conf, and gives
you much more freedom at the expense of more typing.


The full image path name depend on the prom version, pre 2.0 being "old",
and 2.0 and later being "new".  Old ones have {promname} whereas later have
{prompath;}{partition_number}, i.e. new ones accept
   {prompath;}{partition_number}/kernelname {kernel-args}
or {prompath;}{partition_number}[beg-end] {args}
whereas old ones accept
   {promname}/kernelname {kernel-args}
or {promname}[beg-end]

{prompath;} and {promname} are optional, defaulting to the device specified
in the main section (before first image keyword) of silo.conf, or the boot
device if none.

With old proms, you type prom paths as dev(X,Y,Z) [e.g. sd(0,3,1)].
With new proms, you type the open boot prom style strings such as
/iommu/sbus/espdma/esp/sd@1,0 terminated with a semicolon (;) to specify disk.
Then the partition can be specified, defaulting to the (optional) partition=Z
line in the main section in silo.conf. /dev/sda2 is "2".

For all proms, you specify a path to the image starting with a slash (/),
starting for the root of the specified partition.
Alternatively, you can load portions of physical disk by typing [B-E] instead
of /kernelname where B is the offset of the first 512 byte block to load,
and E is the last. Thus [1-16] will load 7680 bytes starting at offset 512.
On newer prome, if the partition number is omitted, it defaults to 0, i.e. the
whole device.

In all cases, kernel args are optional.

/sbin/silo will warn you if there are any problems, but you should ensure that:

you need to start either first, or third (usually whole disk), or any other
partition on cylinder 0 in your partition table.
It is highly recommended, that your first partition (sda1) starts on cylinder 0
(beginning of disk) and that third partition (sda3) is of type WHOLE_DISK and
spans the entire disk, as these are conbentions which are often assumed.
If you do not, you have to make sure that whenever you use fdisk to change a
partition which starts at 0 (which usually includes deleted partitions) to
something else, you must rerun /sbin/silo on that disk.
If you keep sda1 and sda3 startng at offset 0, you don't need to do that.

SILO from 0.6.5 up supports loading of Solaris kernels without using the
saved boot loader. Either put into your silo.conf something like
image = 4/kernel/unix
	label = solaris-single
	literal = "-s"
	solaris

(the name is relative to /platform/your_platform_name_here/ in case of
Solaris 2.5+), keyword solaris says that the kernel needs special handling
(otherwise it won't be loaded). On the command line, you can either type
somewhere between parameters a keyword solaris, or if the name is
/kernel/unix, you don't have to type anything. You should have your solaris
ufsboot in either /ufsboot or /platform/your_platform_name_here/ of the
partition you're booting solaris from.

SILO from 0.7.3 onwards supports a special syntax for conditionals in
silo.conf: instead of writing image keyword, you write e.g. image[sun4c,sun4m]
which means if the machine is sun4c or sun4m, that image will appear as is,
otherwise it will be hidden. There cannot be any spaces in the whole keyword
(ie. between "image", "[", the list of machines and trailing "]", machines
have to be separated by commas, the machine names should be either case of
sun4, sun4c, sun4d, sun4m, sun4e, sun4u.
Example:

image[sun4] = /boot/vmlinux-sun4.gz
	label = linux
image[sun4c,sun4d,sun4m] = /boot/vmlinux-sparc32.gz
	label = linux
image[sun4u] = /boot/vmlinux-sparc64.gz
	label = linux

To create a bootable floppy, you can use the romfs filesystem. It will allow
you to squeeze files on the floppy more than you achieve e.g. with ext2, and
you can use the dual sun4[cdm]/sun4u first stage bootblock.
You need to use genromfs-0.3 and higher. It can be obtained from
ftp://ftp.banki.hu/pub/linux/local/genromfs-0.3.tar.gz.
Firstly, you should populate the tree for the floppy in some directory. Lets
assume it is floppy/. Then copy the /boot/fd.b bootblock somewhere into the
floppy/ tree, e.g. to floppy/boot/fd.b. Then make sure you have the right
silo.conf in the tree as well, and do:

genromfs -d floppy/ -f /dev/ram -A 2048,/.. -a 512 -V 'My installation disk'
mount -t romfs /dev/ram /mnt
silo -r /mnt -F -i /boot/fd.b -b /boot/second.b -C /etc/silo.conf
umount /mnt
dd if=/dev/ram of=floppy.img bs=1440k count=1

and you're done. -i defaults to /boot/fd.b for romfs floppies, -b defaults
to /boot/second.b, -C to /etc/silo.conf. The -A 2048,/.. argument to romfs
is required so that you have enough space for the first stage loader and
-a 512 is required because of the internal implementation of romfs in
second stage loader (but even if that changes, it would be required at
least for /boot/second.b anyway).

To create a bootable flash image for JavaStation-NC or JavaStation-E equiped
with flash, populate flash/ directory with boot/ieee32.b, boot/second.b,
etc/silo.conf, boot/proll.img and boot/vmlinux.gz:

dd if=/dev/zero of=flash.img bs=1k count=1
genromfs -a 512 -f romfs.img -d flash/
cat romfs.img >> flash.img
rm -f romfs.img
losetup /dev/loop0 -o 1024 flash.img
mount -t romfs -o ro /dev/loop0 /mnt
silo -J flash.img -i /boot/ieee32.b -r /mnt
umount /mnt
losetup -d /dev/loop0
jsflash flash.img

2. License

	All the code is under GPL.

3. TODO

	* (DONE) Redo filesystem support so it is easier to plug in more
	* (All except ufs done) Add ls support for more filesystems
	* Fix ls so you can do "ls -l /some/file", since ls only works on
	  directories right now.
	* Someway to cache the filesystems, so we don't have to
	  open/read/close on every access to them.
	* NetBoot
	* More silo.conf keywords/commands
	* Sun4 support

4. Credits.

	Jakub Jelinek
	Donnie J. Barnes
	Mauricio Plaza
	Pete Zaitcev
	David S. Miller
	Miguel de Icaza
	Eddie C. Dost
	Andrew Tridgell
	Wernel Almesberger
	Adrian Rodrigues
	Mark Adler
	Piete Brooks
	Tom Dyas
	Martin Beran
	Ben Collins