gsplus/src/INTERNALS.overview

KEGS Internals
--------------

The INTERNALS* files describe the internal structure of KEGS and how
it works.  It is meant to be useful to those who would attempt to
port KEGS to non-Unix platforms, or just want to know how KEGS works.

Documentation files:
--------------------

INTERNALS.overview:  Provides overview of KEGS's file structure


KEGS SOURCE FILES:
-----------------

adb.c:		ADB emulation routines.  This includes keyboard, mouse, and
		  joystick.
adb.h:		Defines for ADB routines.
clock.c:	Clock, BRAM, and some timing routines.
compile_time.c: Trick file to put the time you compiled in g_compile_time[].
defc.h:		Global defines included by all .c files.  Useful trick
		  to avoid complex multi-level include problems.
defs.h:		Global defines included by all .s files (assembly language).
defcomm.h:	Global defines included by all files (must be assembly and
		  C safe, such as #defines).
defs_instr.h:	C and assembly definitions for various addressing modes
		  and for some repeated instructions (like LDA, STA, etc).
dis.c:		Disassembler and debugger interface.  The debugger interface
		  is similar to the Apple // monitor, but has many
		  more commands.
disas.h:	Tables for disassembling 65816 instructions.  Not very
		  efficient, but it works.
engine_c.c:	C main instruction dispatch loop.
engine_s.s:	Assembly main instruction dispatch loop.
instable.h:	Instruction table.  It is C and assembly-safe through
		  the make_inst script.  make_inst turns instable.h into
		  8inst_c and 16inst_c, which are both valid C code.
iwm.c:		IWM routines for 5.25" and 3.5" disks.  See INTERNALS.iwm
iwm.h:		IWM defines
iwm_35_525.h:	File for reading and writing a disk byte, which is included
		  in iwm.c twice, once for 5.25" and again for 3.5".
		  Forcing out compile-time constants this way makes it
		  faster.
moremem.c:	Awful name--this file contains the page table change
		  routines (fixup_*) and io_read() and io_write() to
		  emulate all $C000 I/O accesses.
op_routs.h:	More macros for 65816 emulation.
protos.h:	Prototypes for all C functions.  Auto-generated through
		  the "cproto" program (not included).
protos_xdriver.h: Prototypes for functions in xdriver.c.
scc.c:		Serial chip emulation.
scc_driver.h:	Unix-specific socket routines, stubbed out if you're not
		  on Linux or HP-UX.
scc.h:		Defines for scc.c.
sim65816.c:	main() is here along with many other housekeeping
		  functions, such as events, and interrupts.
		  The main loop of KEGS is run_prog().
size_tab.h:	Used by assembly for a jump table (make_size script
		  turns it into 8size_s and 16size_s) and by both C and
		  assembly to get the size of instructions.
smartport.c:	Smartport emulation, emulates s7dx devices.
sound.c:	Sound emulation.  Builds sound samples, but does not
		  send sound to output device.
sound.h:	Header file for sound.c.
sound_driver.c:	Sound driver routines.  Takes samples generated by sound.c
		  and sends them to the correct output device.  Supports
		  HP Alib, HP /dev/audio, and Linux /dev/dsp currently.
superhires.h:	"macro" routine used by video.c so that I could write
		  one generic superhires routine, but then include it
		  multiple times to get optimized 320 vs 640 mode routines.
video.c:	Display routines.  Builds 8 bit video buffers in a
		  device independent way.  Functions here know nothing
		  about X windows.
xdriver.c:	X windows driver routines.  Takes buffers from video.c
		  and sends them on to X windows.  Get keypresses from
		  X and sends them to adb.c.

Porting Advice:
--------------

To a non-unix platform, disabling scc emulation would be a good start.
Just make sure you get the dummy stub routines in scc_driver.h.

If you don't have gettimeofday(), clock.c will need to modified with
whatever timer facilities are available.  A high-resolution clock works
best, but even a low-resolution clock will work.

Modify sound_driver.c to get it to compile, if necessary.  Always run with
"-audio 0" to turn audio off.  No routines in sound_driver.c will get
called if you run with -audio 0.

Replace xdriver.c with new routines for whatever platform you are porting to.
See INTERNALS.xdriver for more information.