This is a quick roadmap of where things are and how to get things done.
Please, please, PLEASE back up your disk before trying to run any of
this software!

0. Requirements

VSTa has a driver for the ST-506 "classic AT" hard disk interface.
This driver has also been verified with one and two disk IDE systems.
The disk geometry can be obtained via (1) the controller's "read
parameter" command, (2) the NVRAM/BIOS stored disk parameters, or
(3) by hand-entering the disk parameters.  Detailed instructions
are in the menu.lst file, discussed below.  The default is "read
parameter", which works fine in most cases.  Note that in pretty
much all modern IDE controllers, LBA addressing is used, which
skips much of the hassles previously associated with disk geometries.

Mike Larson has written a SCSI disk driver for the Adaptec 1542[bc]
interface.  IDE and SCSI appear to co-exist without problems.  Mike also
has provided support for CDROM filesystems and SCSI tape.

VSTa uses a FAT filesystem (FAT-12, FAT-16, and FAT-32 are supported,
along with VFAT "long filenames").  It is expected that you'll
already have set up such a filesystem, and you'll be expected to
load the VSTa files onto it using whatever OS got this filesystem
set up.  Examples below are for a DOS-like environment (DOS native,
or very likely a DOS window under Windows).

The console driver supports both MGA and CGA text screen locations.
It is not auto-detect.  The keyboard driver expects the AT scan
codes.  The floppy driver supports most common formats, although
I've only tested 1.2M/5.25" and 1.44M/3.5".  My smallest system
has 8M of RAM, and that seems to be plenty.  Systems with up to 256
Meg have been booted.  If you use the C compiler, you'll need a CPU
with a floating point unit.

The binaries distributed with VSTa include a port of the GNU C
compiler.  Self-hosted VSTa compiles are the method of choice.
But since you get precompiled versions of all the servers, commands,
and libraries you can skip self-hosted compiles if you just want
to play with the running system.  Or you can choose just to recompile
interesting parts.

Boot loading happens using the Multiboot standard.  The most common
Multiboot compliant boot loader is GRUB (GRand Unified Bootloader).
VSTa works with the Free Software Foundation's version of GRUB, which
is the recommended one.  You should go over to:

	http://www.gnu.org/software/grub/

and get the latest stable version.  GRUB can be written onto a floppy,
which can then be used to boot VSTa (i.e., boot GRUB off floppy, and then
use GRUB to bootload VSTa).  GRUB can also be installed onto hard disk,
but please note that this isn't necessary, and you can leave your hard
disk boot setup alone and still try VSTa.  More details follow below.

1. Loading the VSTa files onto your disk.

Create the directory /vsta on your FAT filesystem.  This should be
the first partition on whatever disk you happen to be using.  If
you don't have the DOS versions of gzip or tar, you can find them
in the same place you found vsta.tz and vsta_bin.tz.

	mkdir \vsta
	cd \vsta
	(Copy vsta.tz here)
	gzip -dv vsta.tz
	tar -xvf vsta.t
	del vsta.t

	You now have all the binaries and administrative files for VSTa.

	You can iterate on this in the obvious way to load other
	sets of VSTa distribution files.

Accounts are in /vsta/etc/passwd, with a parallel file /vsta/etc/shadow
holding the actual passwords, which are in the clear.  Feel free
to edit these files using a DOS editor; VSTa tries to accomodate
both DOS \r\n and UNIX \n conventions for line-oriented data.  The
format is described in src/lib/passwd.c, but should be familiar to
anyone who's messed with UN*X-like password files.  The group you
belong to in the passwd file causes you to get more abilities; see
/vsta/etc/group.  Finally, numeric format IDs are mapped to symbolic
courtesy of /vsta/etc/ids.  You can see how in src/lib/ids.c.

2. VSTa directory organization

All source files are stored under RCS.  The RCS storage resides inside
the RCS/ subdir in each source directory.  The binary directories, of
course, are not kept under RCS.

	The VSTa tree is organized under /vsta as:

	bin		Commands
	lib		Libraries
	etc		System-oriented text files
	doc		Documentation, such as it is
	doc/man		Some initial man pages, in roff format
	src/os		Kernel source
	src/os/make	Where kernel objects are compiled into
	src/os/kern	Portable kernel C source
	src/os/mach	Kernel i386 C, as well as assembly
	src/srv		All portable servers (filesystems, etc.)
	src/srv/mach	i386/ISA servers (disk, keyboard, etc.)
	src/bin		Command source
	src/lib		Library source
	src/bin/ports	Ports of other UN*X-ish utilities

If your tree includes the 68030 Amiga port, you will also see mach.ami
directories.  The mach.r4k subdirectory probably isn't present, but holds
code for a MIPS R4000 port of VSTa.  Both of these ports are in the
unsupported/historical category.

3. Booting the kernel, the first time

If you're already using GRUB (or some other comparable Multiboot
compliant loader), you can skip this.

Create a GRUB boot floppy using the direction provided with the GRUB
distribution.

Reboot your machine with this floppy in drive A (and your BIOS configured
to attempt booting from floppy), and you should end up at a GRUB interactive
prompt.  For a default installation, you could now enter:

	root= (hd0,0)
	kernel= /vsta/boot/vsta
	module= /vsta/boot/cons
	module= /vsta/boot/namer
	module= /vsta/boot/wd d0:readp
	module= /vsta/boot/dos -d //disk/wd:wd0_dos0 -n fs/root
	module= /vsta/boot/init
	boot

You should watch GRUB's messages as you enter these lines; it'll complain
if things are amiss.  After "boot", you should see VSTa boot up and run
off of your hard disk.  These commands load the boot modules off the
first IDE hard drive, from the /vsta/boot directory.  You may need to
adjust these commands; the file /vsta/boot/menu.lst documents how, under
the "VSTa boot" section.  Common reasons to need to adjust these strings
are that your display card uses MGA text mode, that you need to specify
your IDE parameters manually, or that you're using a SCSI disk.

Assuming you have successfully booted, and you're up for converting
to GRUB as your boot loader (it supports DOS, Windows, FreeBSD,
NetBSD, Linux, Hurd, OS/2, and VSTa), you should now refer to the
full instructions for setting your PC up to use GRUB as your
bootloader.

A snapshot of a known working GRUB distribution is available at:

	ftp://ftp.vsta.org/grub/

Please use the FSF version if at all possible, since GRUB is under
active development, and is receiving many useful bug fixes and
enhancements.

4. Kernel debugger

You have two options for kernel debugging.  As shipped, the on-screen
kernel debugger is selected.  If you want to have the kernel debugger
talk out the serial port, see src/os/mach/dbg*.c.  You will also have to
change the compilation options if you're using a display card at the MGA
text address.

You will enter the debugger if VSTa crashes, or if a boot server
task dies.  You can also type ^Z (control-Z) and you'll drop into
it.  A "q" will continue.  Since the console driver handles this,
it'll try to restore your screen after you come back from the
debugger.

Use the "pr" command to see the proc table, the "bt" command to see a
stack backtrace of the current process.  "dv" will dump virtual
addresses, and "dp" will dump physical.  You can look at the current
user process' address space by OR'ing in 0x80000000 to the user address.
"dv" will complain if you try to look at a non-existent address.  "di"
will disassemble at an address; symbols were put in during the kernel
build, so the output should be fairly comprehensible (if you know i386
assembly!)  The "=" will take expressions and print them in hex,
decimal, and symbolically.

"pr <num>" will dump out a particular process with more detail.  "vas
<addr>" will dump out a virtual address space struct; similarly for
"pset", "pview", "port", "ref" (portref).  "tf" will dump out the
current trapframe (from the last trip through trap()), or "tf <addr>"
will assume there's a trap frame at the given address, and dump it out
instead.

5. Multi-screens

By default four logins are launched for four virtual screens.  Use
ALT-F1, ALT-F2, ..., to switch between the screens.  See the
file /vsta/etc/inittab to launch more or less screens.  The first
screen (ALT-F1) also receives syslog output.

6. Building the system

	(Boot VSTa)
	cd /vsta
	sh -x mkall
	(watch the blinkin lights)
	(if all looks great:)
	sh -x mkall install

You can also cd to some particular server or command source directory
and "make" or "make install" just that piece.  This is probably the
best idea, since if something subtle gets hosed you'll have fewer
changes to undo in order to get a usable system again.

NOTE: some binaries (emacs, rc, gcc & friends) are in their own
distribution tar file.  They are probably not present in your source
tree unless you explicitly loaded them.  A lot of the stuff in
src/bin/ports is not part of the regular/formal "VSTa system build"
process.

7. Documentation

Regrettably, not much.  Use the "man" command to access the initial man
pages.  Hopefully more will show up, but at least the messaging
primitives are now documented.  You can list the available man entries
with "man 2 msg", and see msg_receive() documentation with "man
msg_receive" (or "man 2 msg_receive").

The /vsta/doc/man directory will show you which man pages exist.  There
are also some files in /vsta/doc (like this one), but nothing earth
shaking.  The C is pretty thoroughly commented, which'll help
programmers.  I'm not sure VSTa's ready for non-programmers, but you're
welcome to give it a try.

The file /vsta/doc/features.txt will tell you a bit about what's
being added from release to release.

8. More?

No doubt, but I can't think of what might help the most.  Stay in touch!
The best way to do that is to join the VSTa E-mail list.  Send to
vsta-request@vsta.org.

					Regards,
					Andy Valencia
					vandys@vsta.org
