Return to README.AMIGA CVS log

Up to [UNIX Amiga Emulator] / uae / docs

uae-0.6.8

                             UAE-0.6.7.1
                            AMIGA version
                                   
                          by Samuel Devulder
                       [email protected]

                              Jan. 1997
                                   

INTRODUCTION
============

This the Amiga port of UAE v0.6.7.1. UAE is the Un*x Amiga Emulator
written by Bernd Schmidt. 

You should read the README file before this one to know more about uae.
(how to use it, command-line options, what is emulated, and so on...).

This port features many things. It is build with the help of ADE
(Amiga Development Enviroment): GCC, ixemul, ... Thus allowing an easy
port of the original unix version to the Amiga without a lot of
modifications. 


REQUIREMENTS
============

This version will work on any Amiga running at least AmigaOS v2.04 and
is programmed to use AmigaOS v3.0 facilities when available. UAE needs
roughly 10Mb of free ram to run on the Amiga. A fast processor is also
strongly recommended. 

Note that you can use UAE under VMM and that uae can run under uae !


FEATURES
========

The joystick can be used within the emulation, allowing you to play
games without destroying your numeric keypad with the '-J' option :-). 

The sound can be emulated in this version. But Amigas are too slow for
it to be really usefull. On my amiga, UAE produces one second of sound
every twenty seconds in Sanity's Interference demo. An amiga 20 times
faster as an A4000 would be nice. PowerPC Amiga will probably achieve
this one day.

The CPU emulation is speed up by using ASM code to compute flags
directly from the 680x0 SR/CCR register.

It supports all Amiga natives mode as well as cybergraphics mode
(rewritten in that version, so expects bugs in it; I'm waiting your
bug-reports and improvements :-). It can run on a automatically
selected custom screen, or on a user-selected screen, or on the
default public screen. It will dither the output when not enough
colors are available (unless you disable dithering), and eventually
use a grayscale palette if less that 8 colors are available. This will
give you the best graphic output according to your configuration. (use
"uae -h" to know how to selected the rendering style).

You can mount Amiga partitions using the -m option. Be sure to use unix 
convention when giving a path to UAE. For exemple do not do 

        CLI> uae -m boot:dh0:path -0 /disks/df0.adf 

but rather

        CLI> uae -m boot:/dh0/path -0 ../disks/df0.adf

This is not a bug, but an ixemul.library feature. You can access amiga
disks by specifying /dev/<device-name>[.device]/unit or /dev/df<num>
after -0. For example you can do "uae -0 /dev/df0" or "uae -0 
/dev/trackdisk.device/0". Under the file requester, select the DEV: 
assign to access amiga disk-devices.

You can reset the emulator by pressing CTRL-ALT-DEL in UAE's window. I
guess it reminds you something :^) You can enter debug mode by pressing
^C or ^D in the cli/shell window or by pressing the close-gadget of
UAE's window when used on a public screen.

The F12 key of the X11 version of uae is simulated by pressing
CTRL-SHIFT-ALT-F10 simultanemously. This toggles the mouse emulation
mode and is needed for some games or demos when you find that the
mouse does not work well under UAE.

You can toggle on/off the screen rendering to speed up the sound
processing by pressing CTRL-SHIFT-ALT-F9.

You can insert disks by pressing CTRL-LALT-F1, CTRL-LALT-F2,
CTRL-LALT-F3, or CTRL-LALT-F4. F1 corresponds to drive DF0, F2 to DF1,
and so on. Alternatively you can simply eject a disk by pressing
LSHIFT in addition of the above keys.

If UAE does not find a rom-file, it'll use the ROM located at address
$F80000 - $FFFFFF. Thus, you need not grab it and that will spare you
some disk space. You can disable this feature by creating the
environment variable "USE_UAE_ERSATZ", in which case UAE will try to
emulate rom calls using a pseudo kickstart.

*NEW*: In this release, UAE should supports Graffiti screens (uae
-H3), but I am not able to test it by myself as I don't have that
board. Please send me some feedback about it.

*NEW*: This release also features an AREXX port to control UAE from an
external gui (see section below). That port is used by the ARexx
script "UAEGUI.rexx". That script uses MUIREXX to provide a nice MUI
interface for UAE.


INCLUDED EXECUTABLE SETTINGS
============================

The included executable is compiled for MC68030. It has the following
settings in ./config.h:

        #define USE_POINTER
        #define CPU_LEVEL 0

AREXX PORT
==========

UAE provides an AREXX port through which you can set or retrieve
internal parameters or variables such as the state of the joystick
emulation or the framerate and so on. Is also implements a "feedback"
mecanism so that a GUI piloting UAE through the AREXX port can hear
about dynamical modification of UAE variables such as led states and
the like. The port name is "UAE". If that port already exists, UAE
will disable it's AREXX feature (that is to say if you have 2 copies
of UAE running on your system, only one will have an AREXX port. I
doubt anyone will try to run 2 UAE in the same time :-).

The commands that need a string argument accepts quoted strings. If
the string is not quoted then it is the following word that will be
used. The quotes can be single (') or double ("). They must match (eg.
if you begin with ('),then you must end your string with (') too).
Within a string, you can use a backslash (\) to express escape
sequences. For example, "This 'is' a \"string\"." represents the
string (This 'is' a "string"). I hope you get it :-)

Here is a list of the available commands:

        * BYE
        * QUIT
                This make the emulator exit.

        * RESET
                This makes a hard-reset of the emulator.

        * DEBUG
                This forces the emulator to enter in debugging mode.

        * EJECT <num>
                This will eject the disk in drive <num> (from 0 to 3).

        * INSERT <num> <filename>
                This will insert the filedisk <filename> in drive unit
                <num>. 

        * FRAMERATE <num>
                This sets the framerate to <num> (1 <= <num> <= 20).
                It is a way to overwrite the -f flag of UAE.

        * VERSION <arg>         (<arg> = NUM | AUTHOR | PORT | STRING)
                This places in the AREXX 'RESULT' variable some
                information about UAE's version. 

                NUM returns a numerical value that is to be interpreted
                as UAEMAJOR*100 + UAEMINOR*10 + UAEURSAMINOR (ie. uae
                v0.6.4 will return "64").

                AUTHOR returns the original author of UAE (ie. Bernd
                Schmidt). 

                PORT returns the name of the port author (that's me!:-)
                
                STRINGS returns a summary string made with the above
                strings. 

        * DISPLAY <arg>         (<arg> = ON | OFF | TOGGLE)
                This will enable or disable the display rendering.

        * FAKEJOYSTICK <arg>    (<arg> = ON | OFF | TOGGLE)
                This will enable or disable the joystick emulation. It
                is a way to overwrite the -J flag from the command
                line. 

        * SOUND <arg>           (<arg> = ON | OFF | BEST)
                This sets the state of the sound emulation (see option
                '-S' on the command line). BEST is the same as using
                the -S3 switch on the commandline.

        * QUERY <var>
                This asks UAE's for its internal variables. That
                state is written in the arexx 'RESULT' variable. So
                don't forget to put 'OPTIONS RESULTS' in your arexx
                scripts. 

                <var> can be one of the following:

                * FAKEJOYSTICK => returns "1" if the joystick
                  emulation is ON and "0" if it is OFF.

                * DISPLAY => returns "1" if the display is not
                  inhibited and "0" otherwise.

                * FRAMERATE => returns the current framerate (see
                  option -f).

                * SOUND => returns "0" if the sound is not emulated
                  (ie. uae -S0 was used). "1" is returned when the
                  sound is OFF (think about uae -S1). "2" means the
                  sound emulation is ON and "3" means it is the best
                  sound-emulation that is used (uae -S3).

                * NAME_DF0
                * NAME_DF1
                * NAME_DF2
                * NAME_DF3 => returns the name of the diskfile used in
                  the indicated unit.
                  
                * LED_DF0
                * LED_DF1
                * LED_DF2
                * LED_DF3 => returns "1" if the drive led is hilighted
                  and "0" if the led is OFF.

                * LED_POW => returns "1" if the powerled is ON and "0"
                  otherwise. 

        * FEEDBACK <eventname> PORT|ADDRESS <portname>
                               CMD_ON|CMD|CMD_OFF <cmd> 
                That command needs a special explanation:

                <eventname> is the name of an internal UAE event. It
                can be any of:
                   ON_EXIT (UAE is about to quit),
                   LED_POW (the power led has changed),
                   LED_DF0 (led of drive DF0 has changed),
                   LED_DF1 (the same, but for DF1),
                   LED_DF2 (well...),
                   LED_DF3 (quess!),
                   NAME_DF0 (name of filedisk df0 has changed),
                   NAME_DF1 (obvious),
                   NAME_DF2 (ditto),
                   NAME_DF3 (...).

                <portname> is the name of an AREXX port. It can be
                "COMMAND" in which case <cmd> is interpreted as DOS
                command. 

                <cmd> is a string containing a command that UAE will
                send to <portname> when the event matching <eventname>
                occur.  

                Each event has 2 available <cmd>. One is set by the
                CMD_ON keyword, the other by CMD_OFF. CMD_ON can be
                abreviated to CMD.

                When the event is the name of a led (LED_POW, LED_DF0,
                ...), it is the <cmd> associated to CMD_ON that will be
                sent to <portname> if the led is hilighted. It is the
                <cmd> of the CMD_OFF argument that will be used if the
                led is dimmed. I think you need an example to make it
                clear (no pun intended :)

                If you issue the command:

                        address UAE feedback LED_POW PORT COMMAND
                        CMD_ON "list t:" CMD_OFF "list s:" 

                Then UAE will issue "list t:" when the led is set to ON
                and "list s:" when it set to OFF. For example in
                UAEGUI.rexx you'll find: 

                        address UAE feedback LED_DF0 PORT UAEGUI,
                         CMD_ON  "switch ID DF0 ATTRS 0x8042654b 1",
                         CMD_OFF "switch ID DF0 ATTRS 0x8042654b 0"

                That makes the gui led follow any state changements.

                If <eventname> is not a name of a led (ON_EXIT,
                NAME_DF0, ...) then UAE will only use the CMD_ON
                command. For events like NAME_DF0, <cmd> can bear a
                '%s'. It'll be replaced by the name of the
                correponding filedisk. For example, the following code:

                        address UAE feedback NAME_DF0 PORT UAEGUI,
                         CMD "popasl ID NDF0 CONTENT %s"

                Will change the content of the popasl gadged
                automatically when the drivename is modified. 

                The event ON_EXIT is used when uae is about to exit.
                You can use it to automatically close an external GUI
                when UAE ends:
                
                        address UAE feedback ON_EXIT PORT UAEGUI,
                         CMD "quit"
                        /* sends "quit" to UAEGUI when UAE exits */

Note: I hope my explanation about the AREXX port is not too fuzzy. You
can always have a look to UAEGUI.rexx to figure out how to use it.


HOW TO (RE-)BUILD UAE
=====================

If you wish to (re-)build uae, you need to have ADE/gcc correctly
installed (see ftp://ftp.ninemoons.com/pub/ade/). Not all part of ADE
are needed, but be sure to have gcc2.7.2.1, binutils, autoconf, awk, ...

Note: This version uses an amiga specific feature of gcc found in Kamil
Iskra's version (http://student.uci.agh.edu.pl/~iskra/ade.html). Look at
__attribute__((regparm(4))) in configure.in. This allows gcc to
use registered arguments passing. It is only available since gcc2.7.2.1.
If it fails with the snapshot you have, then you should comment the
definition of REGPARM. Unfortunately that will make UAE run slower. 

The default Makefile provided is for a mc68030 microprocessor. If you
wish to have a Makefile tuned for your CPU (and fpu), just type "sh -c
configure". Note that you should use sh from the pdksh distribution (in 
ADE) if you want a correct "config.cache" file (other shells produces a
buggy "config.cache" file).

If you have deleted the file "configure", you can rebuild it from
"configure.in". To do this, just type autoconf in a shell. Note that 
autoconf 2.10 is required.

Once your Makefile is generated (if needed), you can modify the file
"config.h" to suit your needs. You can also modify "src/md-amiga/ami-win.c"
to allow the support of cybergfx modes (you'll need to obtain
CGraphX-DevKit.lha from aminet then). I suggest you to define
DONT_WANT_SOUND in "config.h". That will speed up the emulation (sound
emulation slows down the speed by roughly 10%).

When you'll have configured uae correctly, type "make" in a shell. Then
one hour and a half later you'll get the uae executable (it might be less
if you have a *real fast* Amiga, but don't expect less that 15 minutes).
I know it's slow, but Amigas are slow (even those with 68060 are not that
fast, by today's standards ;-).  

To compile, 10Mb of free memory should be enough (I have 4Mb, but
virtual memory helps in that case). The resulting directory size is
roughtly 5.7Mb on my harddrive. Be sure to have a stack of at least
300Kb when compiling UAE and at least 32kb when UAE is running.


REMARKS OR BUG-REPORTS
======================

You can send me your remarks and bug-report to:

                       [email protected]


LAST NOTE
=========

Why emulate an Amiga on an Amiga ? That can seem to be a foolish
behaviour.. Actually it is not !

Many old games/demos refuse to work well if you are using a 68030+;
even with degrader running. In that case, uae might be usefull.

UAE might also help graphic-board owners. With UAE, they can view all
the demos with copper and blitter effects that fails to run on their
graphics board. Or run programs like Deluxe-Paint or Brilliance that
poke the hardware directly.

Using uae on a 68040+ Amiga will let you play games or demos on your
workbench, in a perfect multitasking. And that is, believe me, quite
amazing (even on my poor 68030 :-). Alternatively, UAE makes a 
wonderfull screen-saver (a bit memory-hungry though).

The main advantage of uae, will be when PowerPC Amigas will come out.
On these machines, I bet no old programs will run. Those machines will
certainly include a 680x0 emulation powerfull enough to run DOS 
programs, but certainly not sufficient to run old games. Thanks to UAE,
backward compatibility will not be a problem anymore. UAE is definitely 
a great program ! 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.