
                               REGISTERS

                        ESP = return stack
                        ESI = data stack
                        EAX = top of data stack


                                 FILES

kern.asm        The kernel, containing these files:
tt.1            Text primitives for text mode
t8.1             ... for 8-bit *linear* video modes
tX.1             ... for 8-bit "X" video modes
t16.1            ... for 16-bit video modes (5:6:5 RGB)
g8.1            Graphics primitives (line, circle, etc.) for 8-bit modes
gX.1             ... and so on...
g16.1            ...
text.1          Text output (common to all text/video modes)
kb.1            Keyboard input  ** Keymaps are located here **
fd.1            Floppy disk
sub.1           Subroutines (fairly important stuff)
com.1           Forth compiler
dict.1          Forth dictionary  ** All words must be entered here **
math.1          Math words
tmp.1           Temporary location for new code until I organize it
demo.1          Useless demo routines
defs.h          Configuration (video mode, etc.)
mac.h           Assembler macros
boot.f          Forth code to be loaded when Retro starts

                               WORD LIST

DEMOS, TOOLS, MISC. (demos.1 ...)
        WORDS
        CHARMAP
        LINES
        COLORS
        a DUMP          Memory display (use i,k to scroll, ESC to exit)

TEXT (sub.1 t8.1)
        CLS             Clear screen
        HOME            Home cursor
        x y TC AT       Position cursor
        KEY c           Read a keystroke
        c EMIT          Print out a character
        a n TYPE                ... string
        n .                     ... number
        CR
        SPACE

GRAPHICS (t8.1 g8.1)
        n COLOR
        x y AT          Set position
        x y -AT         ..relative to current x,y
        h VLINE
        w HLINE
        w h BOX
        r CIRCLE
        r DISC          filled circle
        w h x y BLIT    copy one area of screen to another
DISKS (fd.1)
        cyl a READ      read a whole track into memory
        cyl a n READS
        cyl a WRITE
        cyl a n WRITES
        STOP            stop floppy motor
        SAVE            write kernel to disk
PORT I/O
        port I
        n port O
FILES (in early development)
        LS              list files
        CD              change directory
        a n SEARCH cyl n        Search directory for a filename,
                                return size/location
SOUND (in early development)
        FM              Tinny OPL/Adlib sound..
        FMV
        FMC


                               RATIONALE

(This describes the OS as planned.. it's not quite there yet)

The filesystem is crude but efficient for my purposes. I work with 
fairly small text files (source code) and with sound and graphics files 
ranging from 0 to 5 megs or so. In these cases it makes sense to load 
the whole file into memory, so I have not written any buffered file 
access methods like most operating systems have. Medium-large files are 
allocated in large blocks, typically cylinders or tracks, depending on 
the storage medium. Tiny files are stored together in archives to avoid 
waste. Files are never fragmented; if a file outgrows the space 
allocated to it, it moves to a larger free space. If free space becomes 
too fragmented, files are rearranged on disk.

Memory allocation is equally crude. Starting from the bottom you have 
fixed-size tables (IDT and such), DMA buffers (which must be below 16M), 
stacks, the kernel, and the heap growing upward from there. Most 
programs can satisfy their needs using the heap, releasing it when done. 
Memory can also be allocated from the top down if need be. At times I 
may run a few small background tasks, maybe a print spooler and TCP/IP 
stack. I run only one "major" program at a time, giving it full control 
of the computer; it can do more sophisticated memory management. The 
paging unit can be used, but on a single-user machine, why bother? Unix 
is a fine server platform and I'm not out to duplicate it.

I write programs in a mixture of Forth and Assembly. My compiler is a 
subroutine threaded Forth with a few easy optimizations. It's designed 
to be simple and interchangeable with assembly. I use the same register 
model as Chuck Moore's ColorForth. The return stack pointer is ESP, 
which should almost never be used for anything else. The data stack 
pointer is ESI, with TOS in EAX. EBX, ECX, EDX, EDI and EBP are 
available, so it's okay to whack them if it won't interfere with any 
calling routines. I take advantage of the FLAGS register when it's 
convenient. Boolean values are returned in the carry flag (0=true, 
1=false) rather than pushing 0 or -1 on the stack. Control structures 
are as in ColorForth.

Multitasking is used for TCP/IP and not much else. It's cooperative 
multitasking, so programs need to call PAUSE roughly every 10-100ms to 
cycle through the other tasks. KEY does this while it's waiting. Note 
that PAUSE doesn't save EBX, ECX, EDX, EDI or EBP. Preemptive 
multitasking can be implemented by keying the task switch off the timer 
interrupt, if you need hard realtime or better reliability.

Keyboard support is minimal. The keypad and function keys interfere with 
typing so I ignore them. They're there if I need them for a game or 
something. Same with the mouse.

