This is a snapshot of the bpmk development tree, containing the source
code for bpmk, its support libraries and some of the servers for the
operating system over bpmk.

Everything included is incomplete, the design and interface of the
kernel is the only thing that probably isn't going to change much in
the future.  Many parts of the software included has never been tested,
there may be features that don't work under any circumstances.

In addition to the kernel, some parts of the operating system being
implemented over bpmk are included, as well as a couple of small test
programs that can be used to benchmark and verify system behavior.

The idea behind the early release is to enable people (more
specifically, hackers) to see what bpmk ``looks like''.  Sometimes
I've run into interesting development projects and wished that they'd
release something, even if there are only a few things implemented.

For further information on the project, see the web pages at
"http://www.iki.fi/~will/bpmk/".

Feel free to contact me (will@iki.fi) for any reason (with emphasis
on the word reason).  If you fix something, you can send patches
relative to the latest snapshot (or an earlier one, but it might
not be easy to apply).  If you wish to implement something significant,
you should probably contact me first.


	Compiling and testing

Read INSTALL for instructions on compiling and installing.

To do something further, you'll need to have everything compiled and
installed on an IDE drive on a BSD ffs or Linux ext2fs partition.  I
haven't tested the latter myself, it may or may not work.  It's also a
good idea to strip the binaries if you really want to run them, since
they are read "whole" in many places.

This is a bit restrictive.  However, the kernel is still the high
priority part of the project, since it isn't quite finished, yet (I
guess I got carried away a bit with the user-level stuff).

I'm also not sure whether BSD disklabels other than those produced by
FreeBSD are understood.  The filesystem reader code also doesn't
follow symlinks, all paths must point to an actual file.

WARNING: Before trying to boot, remember that the entire system is
experimental.  It's probably safer than dd if=/dev/zero of=/dev/rwd0
at the moment, since nothing requests a write to the hard disk, but
that doesn't mean something can't flip a bit in the I/O requests
and...  You can feel moderately safe if your important information is
on SCSI-disks (or better yet, on another computer).

Assuming you have the kernel and server modules installed in a
directory called "boot" on some partition, your GRUB configuration
should look something like one of these:

# Installation on partition 'a' of the first slice on your
# first drive on your first controller.

title = bpmk on /dev/wd0a
root = hd(0,a)
kernel = /boot/bpmk
module = /boot/startup
module = /boot/wdc

# Installation on partition 'g' of the first slice on your
# first drive on your first controller.

title = bpmk on /dev/wd0g
root = hd(0,g)
kernel = /boot/bpmk -r0s1g
module = /boot/startup
module = /boot/wdc

# Installation on partition 'a' of the first slice on your
# first drive on your second controller, assuming that you have
# one disk on your first controller (GRUB uses your BIOS drives, which
# are sequentially numbered across controllers)

title = bpmk on /dev/wd2a
root = hd(1,a)
kernel = /boot/bpmk
module = /boot/startup
module = /boot/wdc -c1

Note: kernel options are passed to startup but options given to the
startup module aren't, while wdc gets options from its module
specification.  This is ridiculous and is likely to change.

The boot (don't boot yet, read further) should work as follows:

1. GRUB loads the kernel, startup and wdc into memory and starts the
kernel up.

2. The kernel maps startup as a runnable user level process with wdc
mapped into its address space.  Arguments are passed to startup.

3. startup creates a new process environment for wdc and runs it.

4. wdc probes for the controller and drives, reads the BIOS partition
table and any disklabels and registers itself with startup.

5. startup opens the root partition on the device, initializes the
filesystem reader and tries to read a file called /boot/bootrc from
it.

6. startup starts up programs specified in /boot/bootrc.

Assuming that you have compiled the programs included in the
test-subdirectory (you can compile them after compiling the other
parts of the system by entering the directory containing the program
and typing "make") and copied them into the "boot" directory, you
could write something like this in /boot/bootrc:

reg=console,pid : /boot/console
reg=unix,cons=0,pid : /boot/unix_emul

cons=0,pid,sync : /boot/signal
cons=0,pid,sync : /boot/rawtty
cons=0,pid,sync : /boot/forks
cons=0,pid,sync : /boot/rpctest

This would cause startup to start the specified servers and programs
in order, waiting for the programs to exit.

	Debugging

If you didn't change kernel/config.h or the CFLAGS (-O2 -g) used for
compiling bpmk, the resulting kernel should contain debugging
support.  If you have two computers that you can connect using a
null-modem cable, one of which is capable of running bpmk and the
other one capable of running gdb, debugging should be easy.

On the machine being used as a debugger, you need:

	- gdb configured for an i386-elf target (version 4.16 seems to
	  work)
	- The bpmk source tree
	- The kernel compiled from that source tree

On the test machine, you just need the exact same kernel that you
have in the debugger.  You can strip the kernel that is booted.

As an example, this is how I usually start debugging (the test machine
(not running anything, yet) has the cable in the first (and only,
since it is a notebook) serial port and the debugger machine (running
FreeBSD and X11) has its end in the second serial port):

(On the debugger)

Load bpmk into the debugger:
$ i386-elf-gdb bpmk

Pre-type commands (gdb's synchronization is rather simple and might
time out), not pressing enter after them:

In gdb: target remote /dev/cuaa1

In another xterm: stty </dev/cuaa1 9600

(On the test machine)

Boot GRUB, edit boot parameters, add -debug to the kernel command.

(On the debugger)

Press enter in the two xterms (gdb first).

(On the test machine)

Press b to boot.

The kernel boots and breaks to gdb, which can be used normally (eg. to
set breakpoints and continue execution).

XXX The options described here probably no longer work the way
they're supposed to.

The debugging options you can pass bpmk on the command line are:

	-debug

Start communicating with gdb as soon as the kernel is far enough in
the startup.  This is accomplished by manually executing a breakpoint.

	-cuaaX
	-comX

Where X is 0-3 (for cuaa) or 1-4 (for com) and indicates which serial
port should be used for debugging.  The default is cuaa0 (com1).

	-baudX

Set the baud rate used for communications (this time, it actually
works).  The default speed is 9600.

	-gdbtrap

Start debugging when a trap occurs that would otherwise cause a panic.

	-gdbkernel
	-gdbuser

Select whether you want to debug kernel or user code.  Debugging
user-level programs works, but if you're running several programs,
you should make sure you're debugging the right one.  The default
is to select for debugging whatever causes the first deadly trap.