Note: all my original references to 386BSD also refer to freeBSD and NetBSD
which in some ways are derived from 386BSD.  --julian@freebsd.org

This Boot code is different from the original boot code that came with
386BSD in that it uses the BIOS to load the kernel and to provide all i/o
services. The advantage ofthis is that the same boot code exactly, can run
on any device that is supported by the BIOS. (That's most of them)
This is important for the 'generic scsi' project because it means we can
write drivers for new scsi adapters without having to develop an new
set of boot blocks for each.

At this point you should read the first part of README.MACH... come back here
when you have done that:

In normal operation, when co-existing with other operating systems, the
following operations occur:

1/ the BIOS loads the first block of the disk (called the Master Boot Record
or MBR) and if it has the correct magic numbers, jumps into it:

2/ The MBR code, looks at the Partition table that is embedded within it,
to determine which is the partition to boot from.  If you install the
boot manager when FreeBSD is first installed, it will also give you a nice
menu for switching between operating systems.

3/ The MBR will load the first record of the selected partition and
if it has (the same) magic numbers, jumps into it. In 386bsd this is the
first stage boot, (or boot1) it is represented in /usr/mdec by
wdboot, asboot and sdboot. If the disk has been set up without DOS partitioning
then this block will be at block zero, and will have been loaded directly by
the BIOS. This is the usual case with floppies.

4/ Boot1 will look at block0 (which might be itself if there are no DOS
partitions) and will find the 386bsd partition,

Boot 1 also contains a compiled in DOS partition table
(in case it is at block 0), which contains a 386bsd partition starting
at 0. This ensures that the same code can work whether or not
boot1 is at block 0.

4A/ IF the NAMEBLOCK option is compiled into the bootcode, then the 
boot1 code will load and examine block1 (usually unused) and
look for a default boot string to use later (if the correct magic number
is present). If the option NAMEBLOCK_WRITEBACK is also defined, then
it will zero out that name after finding it, and write the block back,
having "used up" that name. The block may contain multiple different
boot strings which will be "used up" one after the other (one per boot)
They are set using the "nextboot" utility.

4B/ Using the information found in step 4, regarding the start position
of the BSD partition, boot1 will load the first 16 sectors of that partition,
to around 0x10000 (64k) and will jump into it at the appropriate entry point.
Since boot1 and boot2 were compiled together as one file and then split
later, boot1 knows the exact position within boot2 of the entry point.

5/ Boot2 asks the user for a boot device, partition and filename, and then
loads the MBR of the selected device. This may or may not be the device
which was originally used to boot the first MBR. The partition table
of the new MBR is searched for a 386bsd partition, and if one is found,
that is then in turn searched for the disklabel. This could all be on the
second disk at this point, if the user selected it. If the user makes no
actions then a default string will be used.

If the NAMEBLOCK option is used, then the default string may have been
loaded from block2. If none was found then a compiled in default will be used.

6/On finding the disklabel, on the disk the user spacified, boot2 can find
the correct unix partition within the 386bsd partition, and using cutdown
filesystem code, look for the file to boot (e.g., 386bsd).

7/ Boot2 loads this file starting at the location specified by the a.out header,
(see later) and leaps into it at the location specified in he header.

if the file does not exist or cannot be loaded, boot2 goes back to step 5.

386bsd is now running and will hopefully start vm etc. and get to multi-user
mode.

##########################################################################
During all these steps, all i/o is performed using the BIOS. This has a number
of side effects:

1/ Since BIOS disk calls are specified in terms of cylinder,head and sector,
and the BIOS read the disk information from either the CMOS or from some other
location which is un-available to us, we must use the cyl,head,sec information
that is given in the MBR, rather than the start address in the MBR, because
we cannot guarentee that we can corectly calculate C,H,S from the start address.

Therefore, the C,H,S information in the MBR must be as correct for this boot
to work as it would be for DOS to boot. For example, adaptec BIOS routines
assume a layout of 64 heads and 32 sectors giving 1MB per ficticious cylinder.
You must use these figures to calculate the correct values. Luckily, the DOS
fdisk program will do all this for you if you tell it to give you a DOS
partition, and you can change it to a 386BSD partition later. If you use 
no DOS partitioning, then the compiled in table in Boot1 will do just fine.

If you want to do it by hand remember that BIOS counts sectors starting at 1.
(cylinders and heads start at 0 (??))

2/ you cannot overwrite the bottom 4k of ram until you have finished ALL
bios calls, as BIOS uses this area as scratch memory.
This is no longer really a problem as we no-longer support loading the kernel
at location 0.

3/ Since BIOS runs in REAL mode, and Boot2 runs in protected mode,
Boot 2 switches back to real mode just before each BIOS call and then
back to protected mode on each return. Touch this at your peril.!

#########################################################################
In answering the prompt from Boot2:
you can, 
1/ leave it alone. It will boot the indicated file from the first 
partition of the first drive seen by the BIOS (C:)
If the NAMEBLOCK option is in use, the default name might be taken from block1
(2nd block) on that drive (the drive on which boot 1 was loaded).

2/ enter only "-s" to boot the default to single user mode

3/ enter only a filename (optionally with -s) to boot that kernel,

4/ enter a whole line of the form shown in the prompt. This allows you to
boot some other partition, possibly on the second drive, as root.


##########################################################################
In the case you have several drives the same type (all scsi or all IDE/ESDI),
	wd(0,a)xxx
will boot xxx from drive 0, a partition.
	wd(1,a)xxx
will boot xxx from drive 1, a partition.

similarly for sd and for higher drive numbers (if the BIOS supports them).

if you have one or more wd drives and one or more scsi drives, then you
MUST specify the BIOS drive number for booting the scsi drives:
	2:sd(0,a)xxx
will boot xxx from scsi drive 0, a partition, provided `2' is the correct
BIOS drive number for sd0.

otherwise the following will happen:

with wd0 and sd0, you specify sd1 or wd1 to indicate the 2nd drive.
it boots the kernel correctly, then tells the kernel to use sd1 as root.
you however may not have an sd1, and problems arise.

Whether sd or wd is specified to the kernel is read from the disklabel,
so ensure that all SCSI disks have type SCSI in their disklabel or the
boot code will assume they are ESDI or IDE. (Remember, because it is
working through the BIOS it has ho idea what kind of disk it is.

##########################################################################
Installing:
The makefile supplied has a target install which will create the
files wdboot,bootwd ,sdboot and bootsd in /usr/mdec.
BEWARE these will overwrite the existing wdboot and bootwd. (so back
them up)

there are also targets wd and sd which wil only do one of them

The commented out targets wd0 and sd0 are examples of how to 
load the new bootblocks, however,make sure you change the 
device type and label to suit your drive if you uncomment them.
(see 'man disklabel')

If you already have made partitions using the old bootblocks
these should install painlessly.

Before you do this ensure you have a booting floppy with correct
disktab and bootblock files on it so that if it doesn't work, you can
re-disklabel from the floppy.

$FreeBSD$