'''VSTa Roadmap'''
How to get started when you're staring at a blank screen (or a bunch of VSTa download files).
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!
=== 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. 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.
=== 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 rn 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.
=== 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.
=== 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.
=== 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.
=== 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.
=== 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.
=== 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.
=== 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@zendo.com.
Regards, Andy Valencia vandys@vsta.org