YAE: Yet another Apple II Emulator.

This is the source of the Apple ][/IIe emulator I have been writing.
I left the source untouched for over two years after I have released
it sometime in 1994.


1. System Requirement

The emulator runs on most UNIX's like OS. People have tried the previous
version on Sun, SGI, DECStations, IBM RS/6000, Linux and HP worstations.
The emulator requires X-Windows and the current version needs the
Shared Memory Extension (XShm). It can only use the local display.
Therefore setting DISPLAY to another machine or an X-terminal does not
work.

2. ROM Images.

The emulator needs ROM files APPLE2.ROM, APPLE2E.ROM and DISK.ROM.
By default the emulator runs in the IIe mode and it uses the APPLE2E.ROM
for the system monitor, AppleSoft and the 80 column firmware. YAE can
optionally be started in the II Plus mode and use the APPLE2.ROM.
The DISK.ROM contains the firmware for the disk II controler and must
be present. These ROM's contain copyright material of Apple Computer Inc.
and I am not distributing the ROM's with the source code. If you need
ROM images, you can download them from.

	ftp://ftp.apple.asimov.net/pub/apple_II/emulators/rom_images

The ROM files must be in the current working directory when YAE starts.

3. How to compiler YAE

There is a make file bundled with the source codes. The make file is
used in the SGI in my lab. You may need to edit the makefile but that
should be simple.

4. How to run YAE

In the current version, YAE can be start using the command.

	apple2 [-2e] [-2+] [diskimage]

The -2e and -2+ options set the machine type to enhanced IIe and
II Plus respectively. The default machine type is enhanced IIe.
The diskimage is mounted on slot 6 drive 1.


5. IIe emulation

When in the IIe mode, YAE, emulates an enhanced IIe with 128K RAM.
The current version is still buggy and I have difficulties in running
many software that uses 128K RAM. 

6. Disk

The emulator currently supports one disk drive in slot 6. It uses
DOS 3.3 sector order images (143K). Write protection is done using chmod. 
The emulator saves to images. However, if you do anything which would
corrupt a real disk on a real Apple (e.g. pressing RESET while writing),
you corrupt the disk image. You can use the F1 key to re-mount diskimage.

If you are really new to Apple II emulators and do not know where to
find disk images, check out the FTP site

	ftp://ftp.apple2.asimov.net/pub/apple_II

There are tonnes of classic Apple II games as well as other softwares.

7. Graphics

Text, low-res, hi-res, 80 column text, double low-res and double
hi-res with full colour support. In the text modes, normal, inverse,
flash characters and the alternate character set (MouseText) are supported.
Since this version uses the shared memory extension of X and thus the
emulator must use the local display. Further more, the current version only
work with 32 bit machines and 8-bit pseudo colour displays. This sounds
rather restrictive but the setting is quite common in the UNIX community.

If YAE crashes or exits abnormally, a shared memory segement will be left
in the memory and take up resources. You can use ipcs to check if this
is the case and then use ipcrm to remove those shared memory segments.

8. Keyboard

Since Apple ][ uses upper case, the cases are reversed in YAE.

Special keys.

Ctrl-Delete	Reset
LeftAlt:	Open Apple Key
LeftRight:	Close Apple Key
F1		Mount disk image in slot 6 drive 1
F2		Shut down YAE

9 JoyStick

The mouse is mapped to the Apple II Joystick. The PDL() function
returns the relative position of the mouse pointer to the upper
left corner of screen. The moue buttons 1 and 2 are mapped to
buttons 1 and 2 of the emulator.

10. Audio support

Audio emulation is supported on Sun and SGI workstations. You need
to link YAE with audio laudio.a on SGI.

11. Compiler

The emulator translates on the fly 6502 machine code into equivalent SPARC
and MIPS machine code. The dynamic comipler is not integrated basic
emulator source code yet.

12. Source Codes

The basic YAE is written entirely in C but with some assembly programming
is used in the dynamic compiler. I changed many source files into
ANSI-C with function prototypes. If you are using old Sun C compiler, 
you cannot compile the source. Try gcc instead.

The laster source of YAE is available via the YAE home page in

	http://quark.netfront.net:6502

13. Bugs & Comments
Please send bug reports or comments to me. My email address is 
ctkwan@cs.hku.hk

14. Acknowledgement

The emulator was derive from the an curses based text mode Apple II
emulator written by Ben Koning. Over the year, I have modified the
codes heavily and it is hard to locate Ben Koning's original codes.
The idea joystick emulation was borrowed from Peter Koch's Apple II
emulator. The 6502/65C02 emulator was written entired by me with
reference to emulators written by Ben Koning and Randy Frank.
Axel Bauer did a colour hi-res patch for the previous version of YAE
but I did not incorporate that in this version as I need speed and used.
XShm. 

The idea of doing dynamic re-compilation of 6502 machine was inspired
by Olin Shivers. He once told me about re-compilation of VAX binaries
on Alpha and I wondered if that could be done for the 6502 machine codes
in an Apple II emulator. Frederic Devernay pointed out a few problems 
and bugs in the dynamic re-compiler.

-------------------------------------------------------------------------------
Last modified by Doug Kwan 6/8/97
