This is version 0.3 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 C compiler. An _ANSI_ C compiler. What most workstation vendors ship
    is not a compiler, but a nightmare. Use GCC if it is available.
  - 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 don't ask me to send you one, I have not asked Commodore/Escom for
    permission yet, and until I do, I won't give any away.
    This version of the emulator can also boot some programs without a
    Kickstart. See below for more information.

I've successfully tested UAE on the following systems:
  - Pentium-90, Linux 1.3.45; 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.
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).

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:

 -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.
 -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. This is known to cause problems,
           there's a bug somewhere. But some demos expect to find this type
	   of memory, and they can occasionally be made to work with this
	   switch.
 -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.
       
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).

b) Access unix filesystems from the emulator.

This has some major advantages:
 - It doesn't crash the emulator if you are using 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.

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.

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.

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.

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: Not much to emulate here :-)
  - 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

Currently, the keyboard mapping used in the emulator is valid only for a
german keyboard. On other keyboards, some keys will be missing - sorry. If you
fix this for your national keyboard, I'd appreciate if you could send me a
patch. There are some beginnings of US keyboard support in the source.
The left and right mouse buttons are emulated. If you have a three button
mouse, the middle button will be the joystick button.
Mouse movement is reported to the emulated Amiga. In SVGAlib, you'll have no
problem positioning the mouse. In X Windows, the emulator defaults to a
special mode in which the mouse movement is adjusted so that sprite 0 and X
mouse pointer are located at the same position. If this should cause problems,
you can turn it off with F12.
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. If this causes any problems, let me know.

10. Sound

You probably noticed the LINUX_SOUND configuration option. If defined, this
will make the emulator use /dev/dsp to output sound with 16 bit, at a frequency
of 44100KHz. Your soundcard has to support this rate. If it does not, your
results will be unpredictable.
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) to play modules using a
Workbench player program if no other (Amiga) processes are active. 

11. Speed

A Pentium with about 500MHz would be nice... (*)
but even a Pentium-90 is not that bad, if you set the frame rate to a high
value, e.g. 9. 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.
Here's a small table of various systems (running random programs, all values 
may vary about +/-20 ). Configuration is in the format 
"display/#colors/frame rate/aspect". A real A500 has a fixed frame rate of
20ms.

Note: For SVGAlib, there is no big difference whether you use the right aspect
or not, so these figures have been omitted.

Configuration             i486   P90    HP
SVGAlib/256/5/n                !  50 !
SVGAlib/256/1/n                ! 100 !
SVGAlib/65536/5/n          130 !  60 !
SVGAlib/65536/1/n          300 ! 120 !
X, 256/5/n                     !     ! 
X, 65536/5/n                   !  60 !
X, 256/1/n                     !     !  
X, 65536/1/y                   ! 200 !

Systems:
i486: i486-DX2-66, VLB
P90: Pentium-90, PCI
HP: HP Apollo 9000/720

Summary: A Pentium-90 will be 5 times slower than a real A500 at full frame
rate. If you reduce the frame rate, it is only about 2-3 times slower.

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

12. Frequently Asked Questions

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.
   The odds are *very* low.

Q: I get lots of compilation errors. Why?
A: The most popular reason is a missing libg.sa in /usr/lib (Slackware bug).
   Do "cd /usr/lib; ln -s libc.sa libg.sa".
   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.

Q: How can I change diskfiles?
A: Wait for version 0.5.

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: 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.

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).

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.

Special thanks (in no particular order) to:
  - Jay Miner, Dale Luck, R.J. Mical and all the others who built the Amiga.
  - Felix Bardos, whose HRM I "borrowed".
  the contributors:
  - Alessandro Bissacco: X Windows mouse auto-calibration, battclock emulation
    and various bugfixes.
  - Hannu Rummukainen: Floppy write emulation.
  - Andre Beck: Made the X support much faster by using MIT-SHM extensions.
    (Not bad for a 10 minute hack, Andre!)
  - Ed Hanway: Wrote the unixfs.device. Improvements to the X support (cursor 
    blanking, etc.), lots of SGI compatibility fixes, run time options. He 
    also sent me a copy of his own (unfinished) Amiga emulator...
  - Ernesto Corvi: Mac port
  - Denis Sablic: Misc. bugfixes, "-S" runtime option.
  - Marcus Sundberg: Better transdisk, bugfixes, DEC Alpha diagnostics.
  
14. 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, although I've been getting quite a lot of it
recently. I can't make any guarantees about snailmail.

I have set up a WEB page for UAE. You might find interim versions, Linux
binaries, diskfiles with Amiga software and other interesting stuff there.
Then again, you might not. My quota isn't that big. The address is

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