Linux Installation Bootdisk Hacking
===================================

Here is an outline of a procedure for adapting the RedHat (or similar)
installation boot disk so that BRLTTY can be used during the installation
process.

Note, however, that you need an already working Linux station to perform
this. A certain level of Linux expertise is also expected. Please read to
the end before doing anything.

First, BRLTTY must be compiled with all necessary options built-in. This
means:

- You must select a BRL_TARGET line in the MAkefile, you cannot use the
  dynamically linked driver modules (is this true?).

- You must specify the serial port to use in the Makefile, you will not
  be able to pass it as an argument.

- You should choose the appropriate braille translation table in the
  Makefile so that it will be compiled in. Only the compiled-in table
  will be available.

- BRLTTY must be statically linked (that is without any dependencies on 
  dynamic libraries). To do this, locate in the Makefile the definition 
  for LDFLAGS and make sure it says:

	LDFLAGS = -s -static

And then compile brltty. You should get an executable who's size is just
around 400K (depending on the driver). If you do:

	file brltty

it should say, among other things, "statically linked".

The Red Hat installation boot disk is a DOS disk that contains a boot
loader, a kernel, and an initial ramdisk (initrd.img). That initial
ramdisk is the initial root filesystem containing a bootstrap installation
program: /sbin/init. We'll just put brltty on that ramdisk image and make
sure it is started before anything else. However, because the statically
linked BRLTTY executable is so large (plus another program we'll need), we
will have to put the ramdisk image on a second floppy, because it won't
fit on the original single boot floppy (with the kernel). 

The boot sequence will need two floppies. The PC will boot using the first
one, wait at the SysLinux (the boot loader) prompt, then when you press
ENTER it will load the kernel.  Once the kernel is loaded, a prompt will
ask for a ramdisk. At this point you insert the second disk and press
ENTER. The ramdisk will be loaded and BRLTTY will (hopefully) come alive.

To modify the initial ramdisk, get the initrd.img file from the boot disk,
either from the original boot floppy using mcopy or from the boot image
(by mounting it with the loopback device). Then:

	mv initrd.img initrd.gz
	gunzip initrd.gz
	mount initrd /mnt -o loop

Then put your statically linked brltty on it:

	cp brltty /mnt/sbin

Then we must add some missing devices on the ramdisk's filesystem:

	cp -a /dev/vcsa0 /dev/tty0 /dev/ttyS1 /mnt/dev/
	(some of them might already be there)

Also you might add some files to /mnt/etc/brltty (such as the *hlp files,
without which the help screen will be unavailable).

The first program that runs when the kernel finishes booting is /sbin/init
(well it's /linuxrc in some cases but here it's just a symlink to
/sbin/init). On a normal system /sbin/init runs the startup scripts, but
since the installation bootdisk is a microscopic system, there are no
startup scripts and /sbin/init is actually the installation program itself
(or part of it).

What we need to do is rename the /sbin/init program and replace it with
our own, which will first start brltty and then start the installation
process. This special init program is included in this directory.

Compile it (statically linked, stripped) like this:

	gcc -o init -s -static init.c

Next, rename the installation program:

	mv /mnt/sbin/init /mnt/sbin/real_init

and replace it:

	cp init /mnt/sbin/init

Finally we can close the initial ramdisk image:

	umount /mnt
	gzip -9 initrd
	mv initrd.gz initrd.img

And hope that the resulting initrd.img file fits on a floppy (which it
should, for now). It probably doesn't fit on the original floppy.  But if
it does, copy it over the previous one and you're done. Otherwise, get a
second floppy and format it, and then put the initrd.img image on it:

	dd if=initrd.img of=/dev/fd0

Finally, go back to the first boot floppy. We must tell the boot loader
to get a ramdisk from a second floppy (instead of the initial ramdisk on
the same floppy). Edit the syslinux.cfg file. On the "append" lines,
replace "initrd=initrd.img" with:

	"root=/dev/fd0 load_ramdisk=1 prompt_ramdisk=1".

You can modify all "append" directives, or just the one you want to use,
or leave the originals there and make a new one for yourself with a new
label... 

At this point, you should be done and ready to boot!

Now for the pitfalls: At the beginning of the installation, and at every
boot into RedHAt, the system scans and tries to detect hardware. This
includes fooling around with the serial ports (and upsetting them) while
searching for a mouse.  This can completely confuse BRLTTY. If it is your
case, you may try to rename /dev/ttyS1 (substitute with the serial port
device you are using) to something like /dev/brldisp in the ramdisk.img
file. Redefine BRLTTY's serial port in the Makefile accordingly and
recompile. This will hopefully hide the device from the probing process
which should leave that serial port alone.

Also note that, on an installed Red Hat system, you may have to modify the
/etc/rc.d/init.d/kudzu script to add the --safe option to the invocation
of kudzu (or better yet just turn that "service" off) for the same reasons
as mentionned above.

TODO: 
The special init program may be improved to filter BRLTTY options out of
the kernel boot parameter string and pass them to BRLTTY. This might allow
for a generic bootdisk with dynamic driver loading (does dlopen() requires
/lib/ld-linux.so to work?).


-- 
Initial draft from Stphane Doyon <s.doyon@videotron.ca>
Additions from Nicolas Pitre <nico@cam.org>
Last revision: Apr 8, 2000
