This is version 0.5.0 of UAE, the Un*x Amiga Emulator.

1. <drivel.h>

Copyright 1995, 1996 Bernd Schmidt & contributors (see below). This program is
freeware.  You may do whatever you want with it for personal use.
Permission is granted to redistribute this program free of charge, provided it 
is distributed in the full archive with unmodified contents and no profit 
beyond the price of the media on which it is distributed is made. Exception: It
may be included on freeware/shareware collections on CD-ROM.
There are no warranties of any kind for this program. If you use this program,
you do so at your own risk. The authors are not responsible for any damages 
that might result from using this program.
This program is still in an early development stage. It contains bugs and is
not user-friendly. 

2. What you need to get it to work

  - a Un*x system with the X Window System, or, if you use Linux, SVGAlib.
    X is much more stable and not that much slower, so use X if possible.
    SVGAlib can get your system into an unusable state if it crashes. You
    have been warned.
  - A graphics card that lets you use a resolution of at least 800x600 in
    65536 colors. You can compile UAE for 256 color screens, but the colors
    will not be quite as good.
  - a ANSI C compiler. GCC is recommended.
  - Optionally, tcl7.4/tk4.0
  - A Kickstart ROM file. I've heard success reports with Kickstart 1.3, 2.0,
    3.0 and 3.1 from various people.
    There seem to exist special 68020+ versions of newer Kickstarts. These 
    will not work, neither will EPROM versions, and neither will ZKick files.
    Please do not ask me to send you one. The Kickstart is copyrighted, and I
    can't pass it around.
    This version of the emulator can boot some programs even without a
    Kickstart. See below for more information.

I've successfully tested UAE on the following systems:
  - Pentium-90, Linux 1.3.69; X11R6 (XFree86 3.1.1) / SVGAlib 1.2.9, GCC 2.7.2
  - HP Apollo, HP-UX, X11R5, GCC 2.6.0
  - Sun Sparcstation, Solaris, OpenWindows, GCC 2.6.1

Several people have successfully run previous versions on a variety of
systems, including a SGI Indy, Suns, a DEC Alpha and a m88k based Unix box.

3. Installation

Please note: I know that the installation procedure could be improved. I
always hate it if I have to change the Makefile or header files to install a
program. But this is the best I could come up with so far.

To build UAE, first unpack it to an appropriate directory (e.g. /usr/src/uae
on a Linux system). After that, you will have to edit the file config.h. There
are many configuration options, each with a comment describing the purpose. 
Please read everything carefully.
Unlike in previous versions, you should not need to edit the Makefile, but
you can: There are some additional options to play with there.
However, if X11 is installed in a different place on your system, you might
need to change the "/usr/X11R6/" bits to "/usr/X11R5" or whatever is
appropriate.
The Makefile knows about a variety of systems. Do "make linux" to compile for
the X Window System under Linux. Do "make svga" to use SVGAlib. There are
several other systems: Do just "make" to get a list. If nothing else works, 
try "make withgcc", and if that does not work because GCC is not installed, 
"make generic". When that fails, send me an email.
If you use SVGAlib, be warned that SVGAlib is not too stable and using it is 
inherently a little dangerous, you might want to have a way to log in from a 
remote terminal if things go horribly wrong. If you are very unfortunate, you 
might lock up your machine otherwise (I strongly recommend using X - it is
no longer much slower).

There is an experimental user-interface for X in this version. Currently, you
have to make a decision whether you want to try it or not. You can try it by
saying "make linux-gui" instead of "make linux" (users of other systems will
have to edit the Makefile by hand, sorry). This requires that you have
tcl7.4 and tk4.0 installed on your system.

The compilation may take a while, especially for the cpu*.c files. There might
be some warnings, ignore these. It may also take a lot of memory. You should 
have at least 8MB physical RAM to compile this, plus maybe 20MB swap and 9MB 
filesystem space.

After compilation, you'll need to install the ROM image. This must have a size
of exactly 512K and should be an image of the addresses 0xF80000-0xFFFFFF on
your Amiga system. The file must be called kick.rom to be recognized. Please
read the next section on how to transfer files from your Amiga to your PC.

You can also install a disk image file. This must be called df0.adf (adf = 
Amiga Disk File), and should be a raw image of the data on the floppy disk: 
11x2x80 sectors == 901120 bytes.
Please try running UAE without a diskfile first. If everything went O.K., the
emulator should show the Kickstart logo (don't be too impatient, this will
take a while on slow machines).

If you don't have a Kickstart file, you may still be able to boot some games
and demos. The emulator includes code that will try to read and execute the
bootblock of the diskfile you are using, and if that bootblock only uses the
one or two Kickstart functions that are supported by the "replacement
Kickstart", your program will boot. Don't expect too much, though.

4. Invoking UAE

After building the program, you should have an executable called "uae". You
can simply execute it, but you can also optionally give it one of the following
parameters:

 -h      : Give help on the options.
 -d      : If UAE is not configured to use correct-aspect display by default, 
           this option will enable it.
 -f rate : Sets the frame rate
 -D      : Don't start the emulator at once, use the built-in debugger.
 -a      : Don't mount the harddisk file automatically. (Useful only for
           testing purposes)
 -x      : (X Windows only) Enable a slower, but more portable version of the
           drawing routines. If you need this switch, I'd like to hear about
	   it (it seems unlikely).
 -l lang : Set the keyboard language at run-time. Currently, only two values
           can be used for lang: "us" for U.S. keyboard (default), or "de" for
	   german keyboard.
 -s      : Emulate slow memory at 0xC00000. Some demos/games need this.
 -F      : Emulate fast memory as an expansion board.
 -S      : If you set the LINUX_SOUND option in config.h, you can turn off
           sound output with this switch.
 -M VOLUME:path
 -m VOLUME:path
           mount the unix file system at path as an Amiga filesystem with
	   volume name "VOLUME:". For example, "-M sound:/usr/amiga/modules"
	   If you use -M instead of -m, the volume will be read only.
	   See below.
 -0 file : Try to use file as diskfile for drive 0 instead of df0.adf.
           -1 file, -2 file and -3 also exist for the other drives.
 -r file : Use file instead of kick.rom as Kickstart image.
 -J      : Use the numeric pad for joystick emulation (with 5 as fire button).
           This will turn off real joystick support. It's no good for action
	   games, but may be useful for other games.

You can also put these options into a configuration file in your home
directory. Simply create ~/.uaerc and put some of these options in it. On
non-Unix systems, the file is called uae.rc and should be located in the
current directory.

If you use SVGAlib, the only way to leave the program is pressing F12.

5. Harddisk emulation

Using diskfiles is awkward. There are two ways how you can use larger amounts 
of data with UAE. 

a) Harddisk files.
You can create a harddisk file with

  dd if=/dev/zero of=hardfile bs=512 count=16384
  
Currently, the size is fixed (8MB). This might be configurable in future
versions.
The harddisk file is accessed by a resident ROM module that is built into the
emulator. It's called "uae.device", the DOS name for the harddisk is "uae0:".
You have to format it before use (from AmigaDOS).

I don't think I will support this in the future. If I get no emails from users
protesting "I put all my files on it" (I got some already, so it's going to
stay a while), I'll remove the code again, because you can

b) Access unix filesystems from the emulator.

This has some major advantages:
 - It also works with Kickstart 1.3.
 - It is more convenient.
 - It is much faster. In fact, it can be dramatically faster even than a real
   Amiga when reading directories.

However, it currently does not work on the BeBox or on the Mac.

If you specify the -M or -m command line arguments, you can use files on your
Unix filesystem from the emulator. If you start UAE with

  uae -m sound:/usr/amiga/modules

you can access all the files in /usr/amiga/modules by reading from the
AmigaDOS volume "SOUND:".
If you want to execute files, they need to have the x permission bit set.
That can be done in Unix by "chmod +x file" or in AmigaDOS with 
"protect file rwed".
In theory, you can specify this option multiple times. In practice, this
doesn't work with Kickstart 1.3 and was therefore turned off. This will get
fixed, I hope.

6. Tools

In the "amiga" subdirectory you'll find two small tools that you can use to
transfer software from the Amiga to the PC. These are called transrom and
transdisk. transrom will dump the contents of your Kickstart ROM, and
transdisk will dump an image of the floppy in drive DF0:. Both programs write
to the standard output, so you want to redirect that. Do

   transrom >ram:kick.rom
   
to create a file called "kick.rom" in the RAM disk, and

   transdisk >ram:df0.adf
   
to create a file called "df0.adf" in the RAM disk. These files are pretty
big, 524288 bytes for the ROM image and 901120 bytes for a disk image. If you
are short on RAM (less than 1.5MB) you may want to transfer those files 
directly to a serial link between the Amiga and your Un*x system (works
without a problem for me).
transdisk can take extra arguments: A device name and unit number. If you do

  transdisk >ram:df1.adf trackdisk 1

the program will read the data from drive 1, not drive 0.

The current transdisk can only read the standard AmigaDOS format. You will 
not be able to transfer copy protected disks. Although the current emulator
version can handle a second type of disk file, and I have successfully
transferred and run a copy protected game (Turrican I) on the emulator, this
support is preliminary, and the disk file format for non-standard disk formats
will probably change in future versions. If you also have Turrican and want 
the program I used to transfer the disk, mail me.

If you transfer commercial software, you must not distribute the resulting
image files, since that would be a violation of copyright law. The Kickstart
ROM has to be considered commercial software. You may only use the Kickstart
from your own Amiga, and you may not distribute Kickstart ROM files.
Please read the license that came with your software for details.

If you have a disk image file, and you want to retrieve the files from it, you
can use the "readdisk" tool. It is automatically built by "make". If you have
a disk image of a disk called "Workbench1.3D" as df0.adf, and you do
   readdisk df0.adf
the whole directory structure of the disk image will be stored in a newly
created subdirectory called "Workbench1.3D". You can optionally give a second
parameter to specify a directory where to create the output other than the
current directory.
readdisk only understands about the OFS right now. FFS disks will be
cheerfully regarded as being unreadable. Use the unixfs.device from within the
emulator if you want to transfer files from FFS disks.

7. Quick overview of the debugger commands

If you use the X Windows version, you can press ^C at any time to enter the
built-in MC68000 debugger.
Each debugger command consists of a single letter and occasionally some
parameters.

g:                    Start execution at the current address. 
c:                    Dump state of the CIA and custom chips.
r:                    Dump state of the CPU
m <address> <lines>:  Memory dump starting at <address>
d <address> <lines>:  Disassembly starting at <address>
t:                    Step one instruction
z:                    Step through one instruction - useful for JSR, DBRA etc.
f <address>:          Step forward until PC == <address>
q:                    Quit the emulator. You don't want to use this command.

(^C has no effect if UAE is compiled for SVGAlib - use F12 to exit)

8. Current state of UAE

The following parts are already mostly complete:
  - MC68000 CPU: Almost done, some rare instructions are not emulated yet. 
    I'd like to make this a 68020 emulation, but I need more info than I have
    about the special registers (MMU etc.)
    Maybe it will one day run Linux/68k!
  - Blitter: If there's no bug, it ought to be complete.
  - Timers: I think these are fully working, too.
  - Copper: Timings okay for most resolutions, minor problems in 640x512 4 
    bitplane mode.
  - Floppy disk: Standard AmigaDOS disks seem to work O.K., some special
    formats can be made to work (not yet really supported).
  - Playfield (display) hardware: Normal cases are working, as well as
    dual playfields, EHB and HAM and interlace (interlace only with correct 
    aspect)
  - Mouse, Keyboard, Joystick: Mouse and joystick should be autocalibrating.
    Only DE and US are supported as keyboard languages.
  - Sprites: Still one or two bugs, but usually working.
  - Sound: Some support (Linux only). Not too useful right now. See below.

Not done:
  - "System control hardware": That's what the HRM calls sprite/playfield
    collisions/priorities. Only the most common priority settings are
    implemented.
  - Timing: It does not really behave like a real A500, but I don't think
    complete accuracy is necessary.

9. Input devices

Mouse, keyboard and joystick can be used in a straightforward way. Two
keyboard languages are supported right now: german and US keyboard. If you
have a different keyboard, patches to make UAE work with it are appreciated.
The X version of the emulator will try to keep the Amiga mouse pointer at the
same location as the X mouse pointer. You can turn off this mode if it does
not work with your program by pressing F12. This is needed (for example) for
Lemmings and the Magnetic Scrolls adventures, which don't use sprite 0 as a
mouse pointer. The SVGAlib version does not have this problem.
If you use Linux and have the joystick driver kernel module, you can configure
UAE to use it. The joystick should be autocalibrating. Turn it a few times on
startup to get the calibration done. 

10. Sound

If you define LINUX_SOUND in config.h, the emulator will use /dev/dsp to 
output sound. It will try to set the output to 16bit/44100 Hz, but will fall
back to 8bit/22050Hz if the sound card does not support this (I hope so, at 
least. Can anyone try this?). If graphics output is enabled while sound is 
output, the emulator will be much too slow on all current systems. The
sound will not be continuous. Therefore, a hack to turn off screen updates is
provided: Press ScrollLock to disable graphics, press it again to enable them 
(note: for X, you'll have to press it twice each time).
The LINUX_SOUND_SLOW_MACHINE option will steal cycles from the CPU emulator.
The relative CPU speed will be reduced somewhat if this option is set. This may
lead to incompatibilities. The system should not be heavily loaded (no blitter
or disk activity) while sound is being played, or even this will be too slow.
Only a subset of the Amiga sound hardware is emulated. Attached channels are
not implemented, neither is CPU-driven output.

Currently, this implementation is good enough to play *Tracker modules and
some game title melodies. It is fast enough (on a P90, without the
LINUX_SOUND_SLOW_MACHINE option) to play modules using a Workbench player
program if no other (Amiga) processes are active. 

On other Unix systems, the AF sound system may be available. You can configure
UAE to use this, too, by changing some paths in the Makefile.

11. Speed

A Pentium with about 300MHz would be nice... (*)
but even a Pentium-90 is not that bad, if you set the frame rate to a high
value, e.g. 5. Animations will not be smooth if not all frames are drawn, but
the speed of the emulation will be considerably higher.
The speed of the emulation is not fixed. Programs that make heavy use of 
blitter, copper and disk DMA will run somewhat slower than programs that only
use the CPU. More bitplanes and sprites will also slow things down. The speed
also depends very much on configuration options.
UAE can calculate the average time it needs to finish one Amiga frame. Use the
'c' debugging command. If you use SVGAlib, the average frame rate will be
displayed when you exit UAE, provided the library doesn't mess up your
text-mode screen when you exit.

There used to be a table here with speed comparisons, but it was getting
constantly out of date. Short summary: A Pentium-90 will be 3-5 times slower 
than a real A500 at full frame rate. If you reduce the frame rate, it is only 
about 2 times slower. It can achieve full speed for sound output if graphics
are turned off (useful for module players).

(*) Try buying a 300MHz clock and a fire extinguisher :-)

12. Frequently Asked Questions, and Common Misunderstandings

Q: Will there be a Windows version?
A: I'll never write a non-commercial program for DOS/Windows again. I hate
   having to reboot after mistakes. 
   I included the DOS port because a) a DOS version can achieve similar
   speeds as the Linux/SVGA version b) it didn't messify too much of the code,
   and c) more people told me they would port it to DOS and I wanted to save
   them the effort. I don't think a Windows port will fit in as cleanly as the
   DOS port, nor do I think it can be efficient. If you want, you can try to 
   prove me wrong, but I will be very reluctant to include Windows code. The
   same goes for code to support a bazillion soundcards for DOS, or similar
   nightmares.

Q: I get lots of compilation errors. Why?
A: The most popular reason was a missing libg.sa in /usr/lib (Slackware bug).
   Do "cd /usr/lib; ln -s libc.sa libg.sa". That should no longer hurt with
   this version, though.   
   Another possibility is that you botched your system in an ELF upgrade.
   Check whether GCC, binutils, libc, ld.so, X11 etc. are all uptodate and 
   installed for the same binary format.
   Some people have been getting "unable to allocate space for program
   headers" from the linker. It appears to be a bug in binutils and/or GCC.
   Please upgrade to the latest files that you find on 
   sunsite.unc.edu:pub/Linux/GCC, but read the release_* files carefully.

Q: How can I change diskfiles?
A: Try using the linux-gui target when you build UAE. See above.

Q: Is it possible to read Amiga disks with a PC?
A: Ask that in comp.emulators.misc :-) The answer is: NO! Unless you invent
   and build some extra hardware yourself, which no one appears to have done
   yet.

Q: When it starts up, it says "Illegal instruction: 4e7b". Why?
A: That's normal, it's just the Kickstart CPU type test.

Q: When it starts up, it says "Illegal instruction: 00f8" (many times). Why?
A: That's because your Kickstart ROM was compiled for the 68020.

Q: While it compiles, it says "xxx illegals generated" or "16 mismatches".
   Is this a problem?
A: No. I can use this information to tell whether there is a problem, and
   there isn't.

Q: Why is there a blank area on the left side of the screen?
A: The Amiga can display graphics there, but usually doesn't because this
   would disable some sprites. The area is only used by some overscan demos.
   Normal screens are off-center. Please don't send me any more mail with "can
   you fix this one" subjects. The answer is: "Maybe. Aren't there any worse
   problems?".

Q: Benchmark program <foo> gives weird results.
A: Amiga programs run by the emulator think the Amiga timers can be used to
   measure real time. But in UAE, they only measure "emulation time". Sysinfo,
   for example, gives the same results on all machines. So don't run
   benchmarks to test the emulator speed.

Q: Wasn't this called the Unusable Amiga Emulator?
A: Yes. But no one thought the name was very fitting anymore, though. It was
   only really appropriate for v0.1, which couldn't even boot.

Q: Sometimes, after UAE exits, there is no autorepeat for the keys!
A: Do "xset r on" (happens only in X).

Q: Would it be possible to speed it up by emulating the CPU native on, say,
   a 68k Mac?
A: I doubt it. UAE needs to be able to interrupt the CPU emulation anytime to
   perform tasks necessary for emulating the hardware.

Q: Emulating all the hardware is a bad idea. Why don't you just emulate the
   OS? After all, that's what makes the Amiga the Amiga.
A: Short answer: I disagree. 
   Long answer: The OS is half of what makes the Amiga the Amiga. It is a very
   nice OS, and there are some features that I miss in any other OS, but it is
   also severely lacking in terms of (for example) memory protection and
   filesystem performance. 
   The other thing that made the Amiga special back in the 1980s is the custom 
   chip architecture. If you look into old (1985) computer magazines, you will 
   find that the capabilites of the Amiga OS are only mentioned as a side
   note, because people were not aware that it was revolutionary for a home 
   computer. They were aware, though, that the Amiga could display 4096 colors 
   at the same time and that it had a blitter and a copper that could do all
   sorts of stuff, like bouncing balls for instance. And I think it was the
   superiority of the hardware that made the Amiga a success.
   I see UAE as a program that is similar to C64 emulators: it allows you to
   run some old games and other programs that you can't replace with better
   equivalents on the PC. As such, it can already be used to run non-action
   games (like Monkey Island or Bard's Tale) at a satisfactory speed. Faster
   CPUs will eventually make it possible to run action games, just like faster
   CPUs have made it possible to emulate a C64 at full speed on a PC. UAE is 
   not (primarily) meant for the Amiga PowerUser who is running high quality
   applications on his A4000 with a 68060 board, but for people like me who
   switched from an A500 to the PC a few years ago because they wanted to make
   money by developing software.
   Besides, emulating an OS is far more difficult IMHO. Especially if the
   platform you are emulating it on is completely different than the platform
   that is being emulated. You'd have to mess with endianness conversions and
   other nightmares. The AmigaOS wasn't designed with portability in mind 
   either.

Q: How can I transfer non-DOS disks that are used by many demos?
A: With transdisk. The fact that they are unreadable by AmigaDOS does not
   mean they are unreadble by transdisk. Only copy-protected disks can't be
   transferred that way.

13. Thanks & Acknowledgements

Thanks to all who have written me so far with bugreports and success/failure
reports when trying to run the emulator on various hardware with different
Kickstart versions. A list of everyone who has contributed to the source code
can be found in the CREDITS file (this was getting too big to keep it here).

Special thanks to:
  - Jay Miner, Dale Luck, R.J. Mical and all the others who built the Amiga.
  - Felix Bardos, whose HRM I "borrowed".
  - Hetz Ben Hamo mailed Peter Kittel from Commodore asking for permission to
    give Kick 1.3 away. Unfortunately, the response was negative :-(
  - Bruno Coste, Ed Hanway, Alessandro Soldo and Marko Nippula provided 
    documentation

14. Ports

Apart from the "main" Unix version, several ports of UAE are ready/being
developed.

Gustavo Goedert <ggoedert@music.pucrs.br> has ported UAE to DOS using the
DJGPP port of GCC. The binary is available on several ftp sites as well as on
my Web site. So far, only a 0.4.4 binary is available, but this does not
differ very much from 0.5.0.

Ernesto Corvi <macsupport@overnet.com.ar> has ported UAE to the PPC-Mac. He
tells me it is available on Info-Mac, and that every Mac user should know
where that is. A link is on my Web page.

Christian Bauer <bauec002@goofy.zdv.uni-mainz.de> has ported UAE to the 
BeBox. His patches are in the source, and this version should compile without
a problem.

Ian Stephenson <Ian.Stephenson@insignia.co.uk> has ported UAE to NextStep.
The source might compile, but you will probably have one or two problems.
Contact Ian if you can't wait for the next version.

Since I generally don't have the possibility to test or improve these ports,
it is a good idea to contact their respective authors if you have questions.

15. The author's address

crux@pool.informatik.rwth-aachen.de

or, via snailmail

Bernd Schmidt
Schlossweiherstrasse 14
52072 Aachen
Germany

I'll *try* to reply to everyone who sends me mail. Email has a near 100%
chance of being replied, unless your email address bounces.
Please read all of the manual, especially the FAQ section, before asking me
about problems.
I can't make any guarantees about snailmail.

I have set up a WEB page for UAE. You will find interim versions, Linux
binaries, diskfiles with Amiga software and other interesting stuff there.
The address is

http://www-users.informatik.rwth-aachen.de/~crux/uae.html