
                             Retro Hackers' FAQ
                             ------------------

Installation options
--------------------

	1. Raw floppy (obsolete)

		'make rawfloppy'

		This is pretty awkward.. in order to include modules, etc,
		you have to insert them into the kernel.  It's a
		traditional, widely-used technique, though.  It could be
		useful when porting Retro to another architecture.

	2. DOS-format floppy
	
		'make floppy'

		A quick way to make a self-contained Retro disk.  You can
		fit all the source code and everything on one disk, with
		room to spare.

		I used the DOS format because it's a de-facto standard. 
		Every OS seems to support it.

	3. DOS hard disk partition
	
		Copy kernel.bin and bforth.fo to the root directory of your
		boot drive (usually C:).  Install the boot sector on your
		hard disk or a floppy (see under Boot Methods).

	4. Native retro filesystem (future)

		This way, Retro goes on its own partition, at least the
		"core" of Retro.  It could be a tiny partition, with most
		data stored in other places.

	Installation program (future)
	
		It'll be sort of like installing Linux.  Make a small
		partition for Retro (possibly using FIPS to split a DOS
		parition in two), then boot Retro from a floppy and run an
		install program.  It'll ask which drive & partition to
		install it on.  The actual copying will only take a few
		seconds.

		Once the persistent storage system is implemented, you'll be
		able to increase Retro's available storage space simply by
		telling it to use another partition or a file on another
		operating system's partition.  You won't have to worry about
		how big to make the root partition, how big to make /usr,
		etc.  Storage is storage.
		


Boot methods -- pros and cons
-----------------------------

	1. Floppy

		'make bootfloppy'  (to install boot sector only)

		Put the boot sector on the floppy.  The kernel and other
		files can be on your hard disk or the floppy, whichever is
		convenient.  Doing this won't corrupt a DOS filesystem on
		the floppy; you can still store things on it.

	    *** To load the kernel from the hard disk, edit 'options' and
		uncomment HDLOAD.

		Pros:
		  * Handy for playing with Retro on an extra computer
		  * Safe
		Cons:
		  * Slow and unreliable (not very noticeable with a small OS
		    like Retro)

	2. Hard disk
	
		You could install the bootsector in the master boot record
		(MBR), or install it in the boot block of a _primary_
		partition and set the partition's "active" flag.

		Pros:
		  * Professional :)
		  * Less susceptible to accidents
		Cons:
		  * Untested
		  * Not for beginners

	3. From DOS (future)

		You run a command like "load kernel.bin" from the DOS prompt
		(or from autoexec.bat).  Shouldn't be hard: just use LOADLIN
		or VLOAD, with a few changes to the loader or the kernel.

		Pros:
		  * Faster & easier than using a floppy
		  * Doesn't touch partition tables
		Cons:
		  * Requires you to have DOS installed
		  * In Win95, you have to be in DOS mode
		  * WinNT is too paranoid to allow it at all (right?)


Boot order
----------

	The BIOS loads the bootsector (boot.asm or dosboot.asm),
	which loads the kernel
	init.inc does everything needed to enter protected mode
	pmode.inc is where the 32-bit code starts
		initializes interrupts, keyboard, display, disks, etc.
		fires up Forth
	forth.inc contains the init, interpreter, and primitive words
	bforth.fo is the "bootstrap forth program"
		Anything you need can be loaded from here.  It's like
		/etc/rc in Unix or autoexec.bat in DOS.
	Finally, you get the "ok" prompt (or maybe not, depending on what
		was in bforth.fo)


Debugging methods
-----------------

	At boot time:
		jmp short $
		callproc print_hex, <value>
		callproc putc, 'x'

	In rForth:
		<address> md	(memory dump, 16 bytes/line)
		<address> mdw	(memory dump, 4 words/line)
		<anything you can think of, you can program it>

Calling conventions
-------------------

	Most routines use Forth conventions.  Instead of stack frames, Forth
	uses two stacks.  EBP isn't needed as a frame pointer, so it's used
	as the second stack pointer.

	A few routines use stack frames, like C or Algol.  EBP is used as
	the frame pointer.  This is very commonplace in most operating
	systems.  Since these type of routines always save & restore EBP,
	you can call them from Forth routines, no problem:
		callproc <c_routine>, <arg1>, <arg2>, ...
	Calling Forth routines is harder, because you have to change EBP
	back to the data-stack pointer.  I don't know how to do this, but I
	don't need to :)

	Some routines use registers for parameter passing... watch out for
	them :)  I try not to do that unless speed is critical.


Register usage
--------------

	You can use any registers you want, as long as you save them on the
	stack first, and restore them when you're done. (callee saves)


Memory layout
-------------

	See kernel/memory.inc.  It changes quite a bit.  Eventually
	everything will be dynamically allocated, when we implement better
	memory management.


Keyboard maps
-------------

	The keyconv program (under the util/ directory) converts Linux
	keymaps to Retro format.  Here's what you do:

		From the top Retro directory,
		cd keymaps
		dumpkeys > tmp
		../util/keyconv tmp kbd_XXX.map |less

		You can ignore most "Unknown keysym" errors".  You can also
		ignore errors like "F1 not allowed here" - they are caused
		by lines like this:
			string F1 = "\033[[A"

		cd ../kernel
		cp kbd_def.asm kbd_XXX.asm
		Edit kbd_XXX.asm (you'll see what to do)
		cd ..
		Edit options (add a "KBD=XXX" line for the new keymap)
		All set! Test it out...
