	$Id: README,v 1.2 2004/08/02 19:27:15 dbrown Exp $

DOCBoot -- A simple Linux bootloader for DiskOnChip

Author:
  Dan Brown <dan_brown@ieee.org>
DiskOnChip Millennium Plus and BIOS extension support:
  Kalev Lember <kalev@smartlink.ee>

-----------------------------------------------------------------------------

DOCBoot replaces the M-Systems BIOS driver on your DOC with a small boot stub
and your Linux kernel image.  It allows you to boot Linux directly without the
need for an (I)NFTL partition on your device.

DOCBoot is based on the first-stage Grub bootloader written by David
Woodhouse.  Instead of loading Grub, it loads a Linux kernel.

Like LILO and Grub, DOCBoot is a Linux bootloader.  It dispenses with many of
the amenities provided by other bootloaders, however.  Command line editing,
multiple image support, initrd loading, serial port support, fancy prompts and
menus, timeouts, and all kinds of error checking are not present.  Unlike Grub,
DOCBoot does not understand filesystems, nor can it load a kernel scattered
throughout the blocks of a filesystem like LILO.  Instead, DOCBoot reads your
kernel directly from a contiguous section of the DiskOnChip.

DOCBoot supports kernel versions 2.4.0-test3-pre3 or later.  Bad things may
happen if you try it with an earlier version.

At the moment, DOCBoot supports only the new INFTL-based DiskOnChip 2000 parts,
sometimes known as Alon or 2000TSOP, and DOC Millennium Plus 16 MB devices.
It might work on DOC Millenium, but I haven't tested this.

Support for the older (NFTL) DiskOnChip 2000 parts and DOC Millennium Plus 32 MB
is planned.

initrd support would be easy, though I imagine most people will simply use
jffs2 as their root filesystem.  Some minimal keyboard interaction
(possibly including commandline editing) would also be a nice addition.


Quick Start
-----------

For DOC 2000TSOP/Alon parts, no configuration is needed and the steps below
should work.  Otherwise, see the Configuration section.

 1. Get the diskonchip driver loaded.  (perhaps via "modprobe diskonchip")
 2. Ensure that your first BDK partition is large enough to hold your bzImage
    plus 1k.  If it currently holds the M-Systems BIOS code, it probably isn't.
    To resize that partition, and for the definition of a BDK partition, please
    refer to M-Systems' DOS-based utilities and associated documentation.
    (Hint: dformat /win:xxxx /bdkl0:x)
    You can also resize partitions with the docfdisk utility from the mtd util
    directory.
 2. Copy a kernel bzImage or vmlinuz into this directory.  Name it 'bzImage'.
 3. Edit the file 'cmdline' to taste.
 4. Generate the doc_spl image:
      make
 5. Assuming your first BDK partition is /dev/mtd1:
      flash_eraseall /dev/mtd1
      nandwrite -o /dev/mtd1 doc_spl
    DONT FORGET the -o flag to nandwrite!
 6. Reboot.  DOCBoot will run if no other drives (floppy, CD, HD, etc) are
    bootable.


How it works
------------

The DiskOnChip has a piece of code called the IPL stored in the first
eraseblock (if yours doesn't, the M-Systems tools can replace it).  When
powered on, the DOC loads the IPL into a small onboard RAM, which is mapped
into the address space assigned to the DOC.  The system BIOS scans this
address space and recognizes the IPL as a BIOS extension, so it runs it.

The IPL searches the DOC for the next stage, called the SPL.  The SPL is
identified with a special code in the out-of-band (OOB) area of the first
eraseblock of the SPL.  This allows the IPL to simply scan the device, rather
than understanding any kind of partitioning scheme.

The IPL loads 0x3000 bytes from the start of the SPL, and computes a checksum.
If the checksum is equal to 0x55, it then executes the SPL.

(Note:  The description above is valid for the Millenium and 2000TSOP parts.
Other variants behave slightly differently.)

The SPL in turn is responsible for loading the rest of the firmware from the 
DiskOnChip. Normally, this steals some memory for itself, and installs an
INT 13h (Disk BIOS) handler to emulate disk access.

We change this. Instead of installing an INT 13h handler, we install an
INT 18h (diskless boot) or INT 19h (bootstrap loader) handler. This is very
small, and is held entirely within the first 1024 bytes of the SPL with the
code which installs it. 

The INT 18h handler is called when no bootable device can be found by the BIOS.
The default handler (built into the BIOS) normally prints an error message and
prompts you to insert a bootable disk.

Using the INT 18h handler, DOCBoot will be called by the BIOS if all other boot
devices fail.  If you would rather have DOCBoot be the first (rather than last)
device to boot, configure DOCBoot as an INT 19h handler instead.  (See the
Configuration section).

When executed, our replacement interrupt handler loads the Linux kernel into
memory.  Adopting the same technique as the IPL, it finds your kernel by
scanning the DOC for a special signature in the OOB area.  This code marks
every block containing the kernel (this is very important, as it allows us to
skip over bad blocks).

As with any x86 Linux bootloader, DOCBoot loads a small section of the kernel
(the real mode setup code) into low memory (below the 1Mbyte mark) and the rest
into high memory.  It then sets up some variables to let the kernel find the
commandline (and a few other things), and jumps to the kernel setup code it just
loaded.  The rest is up to Linux.


Configuration
-------------

You can alter DOCB behaviour by uncommenting or modifying special #defines
at the end of doc_bootstub.h:

#define MILPLUS:        Uncomment this to enable DiskOnChip Millennium Plus
                        support and disable DOC 2000 / Millennium.

#define DOC_BIOS_HOOK:  Change this to either 0x18 to hook the Diskless Boot
                        Interrupt or to 0x19 the hook the Bootstrap Loader
                        Interrupt.

#define DOC_ADDRESS:    This is used to specify the memory address at which
                        the Diskonchip is located.  If this is undefined,
                        DOCBoot relies on the standard IPL to pass this
                        information in the DS register.  If your IPL doesn't
                        do this, or for some other reason you want to hard-
                        code the address, define this.

#define BIOS_EXTENSION: Uncomment this to make a standard PC BIOS extension
                        instead of the SPL image.  This is explained in more
                        detail below.


BIOS Extension Support
----------------------

Normally, the makefile uses the program 'makespl' to combine the DOCBoot
executable, your commandline information, and your kernel into a single file
which you can then write to your device.  This is appropriate when using the
standard M-Systems IPL.

In applications which use a custom BIOS, you may instead want to use DOCBoot as
a BIOS extension (loaded with your BIOS), rather than as a SPL (loaded by the
M-Systems IPL).

To do this you must (1) #define BIOS_EXTENSION in doc_bootstub.h, and
(2) run 'make bios' rather than 'make'.  This will produce two files:

'doc_spl' contains your kernel image in a form suitable for writing to your
device with nandwrite -o.  Unlike in the normal build method, this does not
contain DOCBoot itself.

'bios_ext' is a 1024-byte file containing DOCBoot and your commandline info,
formatted as a standard PC BIOS extension.  Merging this into your BIOS is up
to you.
