
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.
defcomm.h:	Global defines included by all files (must be assembly and
		  C safe, such as #defines).
defs_instr.h:	Definitions for various addressing modes
		  and for some repeated instructions (like LDA, STA, etc).
debugger.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:	65816 emulation and helper routines
engine.h:	Actual 65816 inner loop, so it can be instantiated with and
		  without logging, and 8-bit and 16-bit accumulator.
instable.h:	Instruction table. 
iwm.c:		IWM routines for 5.25" and 3.5" disks.  See INTERNALS.iwm
iwm.h:		IWM defines
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_16ms().
size_c.h:	Used 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
		  /dev/audio, /dev/dsp, Linux PulseAudio, and Mac audio.
video.c:	Display routines.  Builds 32-bit video buffers in a
		  device independent way.  Functions here know nothing
		  about X windows or Macs.
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.
mockingboard.c:	Mockingboard A emulation (two 6522, two AY-8913 sound chips).
unshk.c:	Can open disk images in .sdk files
undeflate.c:	Zip routines, for selecting images insize .zip files, or
		  gzip compressed files.
woz.c:		Support for .woz images, Version 1 or Version 2.

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.

Useful IIgs information:
-----------------------

The Apple manuals (Hardware reference, Firmware Reference) are the most
useful.  But they leave a lot out, or have innaccuracies.

Some details on IIgs fast/slow mode and refresh information:
https://www.kansasfest.org/wp-content/uploads/2011-krue-fpi.pdf

