$Id: README,v 1.9 2002/03/08 11:06:33 malekith Exp $

 * bsp - Braindamaged Script Processor for initrd
 *
 * this falls under GNU GPL v2.
 *
 * written in y2k,y2k++,y2k++++ by Michal Moskal <malekith@pld.org.pl>
 

Short description of "language" used for scripts:

in normal circumstances bsp behaves as if set -x
i.e. all commands executed are printed with `+ ' prepended.
if you don't want -x, prepend command with @ as in make
there are 2 builtins, both are not -x:
 # - comment
 > - echo
blank lines are ignored
typical script might look like:

------------------------cut
#
# typical script ;)
#

> Setting up disk modules
# word enclosed in '' gets passed to command as whole: 
# { "insmod", "ide", "x=y c x", 0 }
insmod ide.o 'x=y c x'
# same with ""
insmod scsi.o "foo=bar baz" "xx = uu"
# but if no space - no need
insmod baz.o abc=def
# fixed by Jan Rêkojarski <baggins@sith.mimuw.edu.pl>, this now works:
# { "insmod", "xxx.o", "abc=d e f", 0 }
insmod xxx.o abc="d e f"
# use of @
# this will look for `hehe' executable along {/usr,}/{s,}bin 
@hehe "you won't see me, won't you? this is stupid"
# wait a second
sleep 1
# or even a half
usleep 500000

> done!

# that's all
-------------------------cut

for latest version see ftp://ftp.pld.org.pl/people/malekith/
or PLD's CVS (for instructions how to get there, see http://www.pld.org.pl)

insmod is now builtin. it doesn't support any options, beside module options.
it looks for modules in preset directories, look at setup.h.
modpath builtin can be used to change this,
modpath /lib/modules/2.2.18
or sth. there can be only one custom modpath at a time.
note that insmod has some own quoting rules ...
.o is required.

echo builtin is also implemented.

> x y z == @echo "x y z" most of time.

in 0.2.0/pi raidstart builtin has been added, as it is stock raidstart
from raidtools, it should work as usual (I'm not sure, what does it 
mean, though... :)

in 0.2.1/delicatessen, mount and umount builtins has been added.
while umount works in quite regular fashion (directory or special
device should be passed), mount requires 3 arguments: device,
directory and filesystem. No switches are supported at the very moment.
For example, this could be used as script for system with root
on lvm:

---cut---
# warning, I havn't tested it ! :)

insmod /lib/lvm.o
mount none /proc proc
/bin/vgscan
/bin/vgchange -a y
umount /proc
insmod ext2.o

> Good luck :)

# eof
---cut---

However note, that you have to compile vg{scan,change} separately...
Also /proc and /dev is required on initrd.

In the same version pivot_root command has been added. However, to make
sure it is compiled correctly, use kernel-headers >= 2.4.
Also append, rm and mknod has been added.

0.2.2/arizona dream introduced few new commands needed to complete
2.4 style pivot_root boot. The most important probably is exec. It has to be
used in order to retain pid==1 for init. Other are: close_console and
reopen_console (needed to unmount oldroot), and freeramdisk (to free memory
allocated for initrd).  Since this version bsp looks for `bsprc' file in 
current directory and in /etc. Additionally, to retain backward compatibility
for a while, we also check /etc/startup.

In order to boot with pivot_root, and release initrd afterward one needs
two stage bootup. Second stage unmounts oldroot and releases ramdisk.
This can be done by init scripts, but 1) there is problem with lack of
freeramdisk utility, 2) why, if bsp can do it alone? :)

1st stage /etc/bsprc file, to be placed on initrd:

#v+
insmod /lib/ide-mod.o
insmod /lib/ide-probe-mod.o
insmod /lib/ide-disk.o
insmod /lib/ext2.o

mount -r /dev/hda1 /dest ext2
cd /dest
pivot_root /dest /dest/oldroot

> reexecuting self
@close_console
exec /sbin/bsp
#v-

On initrd we also need:
 * bsp as /sbin/init
 * empty /dest directory
 * /dev/hda1, /dev/console
 * kernel modules

On real root directory, we need:

Following /etc/bsprc file:

#v+
# stage2 bsp startup
@reopen_console
> Ok, in stage 2
umount /oldroot
freeramdisk /dev/ram0

> May the penguin be with you!

exec /sbin/init
#v-

and the following:
  * /sbin/bsp
  * empty /oldroot directory (we probably should use sth like 
    /var/lib/bsp/oldroot, this should be possibly without big problems)
  * /dev/ram0 and /dev/console (even if you are using devfs)

It is probably possible to tell kernel to mount devfs automagicly, not
to need any device files on initrd. However remember to unmount /oldroot/dev 
it before trying to umount /oldroot. You can also mount devfs again, after
pivot_root, and freeramdisk /dev/rd/0 then.

Notes:
  1. use root=/dev/ram0 in lilo
  2. after booting it is desirable to
        ln -sf /dev/ide/host0/bus0/target0/lun0/part1 /dev/root
     (since /dev/root points to /dev/rd/0, devfsd seems to be stupid :)

====
Builtins:


* append FILENAME STRING...

appends STRING... to FILENAME. It is created with 0600 mode.

* mknod NAME b|c MAJOR MINOR

make special device.

* rm FILENAME

remove file. behaves as rm -df -- i.e. doesn't complain if file does not 
exist, and removes (empty) directories.

* pivot_root NEW_ROOT PUT_OLD

see man 2 pivot_root

* mount DEVICE DIRECTORY FILESYSTEM
* umount DEVICE|DIRECTORY

go figure.

* usleep MSECS
* sleep SECS

Wait for MSECS milliseconds or SECS seconds.

* echo STRING...

Output string, same as > STRING.

* insmod MODULE

MODULE is absolute path or file in modpath.

* modpath PATH

set path (one directory!, no ':')

* raidstart WHATEVER...

Call raidstart, see man raidstart (this doesn't seem to work)

* cd DIR

change current working directory

* mkdir DIR

make directory

* exec COMMAND ARGS...

execute given command, without doing fork(), COMMAND is looked in SEARCH_PATH

* close_console

close file descriptors no 0, 1 and 2

* reopen_console

close file descriptors no 0, 1 and 2, and do open("/dev/console") 3 times.

* freeramdisk DEVICE

release memory used by ramdisk DEVICE. DEVICE is sth like /dev/ram0 or
/dev/rd/0.

TODO:
* set builtin, like this
  `set qe' or `set v'
  (q for quiet, v for verbose and e for i-don't-know-what)
* maybe lvm support, however building lvm tools with uClibc seems
  more reasonable...

Have fun.
 --malekith
