Return to README.AMIGA CVS log

Up to [UNIX Amiga Emulator] / uae / docs

Annotation of uae/docs/README.AMIGA, revision 1.1

1.1     ! root        1:                              UAE-0.6.7.1
        !             2:                             AMIGA version
        !             3:                                    
        !             4:                           by Samuel Devulder
        !             5:                        [email protected]
        !             6: 
        !             7:                               Jan. 1997
        !             8:                                    
        !             9: 
        !            10: INTRODUCTION
        !            11: ============
        !            12: 
        !            13: This the Amiga port of UAE v0.6.7.1. UAE is the Un*x Amiga Emulator
        !            14: written by Bernd Schmidt. 
        !            15: 
        !            16: You should read the README file before this one to know more about uae.
        !            17: (how to use it, command-line options, what is emulated, and so on...).
        !            18: 
        !            19: This port features many things. It is build with the help of ADE
        !            20: (Amiga Development Enviroment): GCC, ixemul, ... Thus allowing an easy
        !            21: port of the original unix version to the Amiga without a lot of
        !            22: modifications. 
        !            23: 
        !            24: 
        !            25: REQUIREMENTS
        !            26: ============
        !            27: 
        !            28: This version will work on any Amiga running at least AmigaOS v2.04 and
        !            29: is programmed to use AmigaOS v3.0 facilities when available. UAE needs
        !            30: roughly 10Mb of free ram to run on the Amiga. A fast processor is also
        !            31: strongly recommended. 
        !            32: 
        !            33: Note that you can use UAE under VMM and that uae can run under uae !
        !            34: 
        !            35: 
        !            36: FEATURES
        !            37: ========
        !            38: 
        !            39: The joystick can be used within the emulation, allowing you to play
        !            40: games without destroying your numeric keypad with the '-J' option :-). 
        !            41: 
        !            42: The sound can be emulated in this version. But Amigas are too slow for
        !            43: it to be really usefull. On my amiga, UAE produces one second of sound
        !            44: every twenty seconds in Sanity's Interference demo. An amiga 20 times
        !            45: faster as an A4000 would be nice. PowerPC Amiga will probably achieve
        !            46: this one day.
        !            47: 
        !            48: The CPU emulation is speed up by using ASM code to compute flags
        !            49: directly from the 680x0 SR/CCR register.
        !            50: 
        !            51: It supports all Amiga natives mode as well as cybergraphics mode
        !            52: (rewritten in that version, so expects bugs in it; I'm waiting your
        !            53: bug-reports and improvements :-). It can run on a automatically
        !            54: selected custom screen, or on a user-selected screen, or on the
        !            55: default public screen. It will dither the output when not enough
        !            56: colors are available (unless you disable dithering), and eventually
        !            57: use a grayscale palette if less that 8 colors are available. This will
        !            58: give you the best graphic output according to your configuration. (use
        !            59: "uae -h" to know how to selected the rendering style).
        !            60: 
        !            61: You can mount Amiga partitions using the -m option. Be sure to use unix 
        !            62: convention when giving a path to UAE. For exemple do not do 
        !            63: 
        !            64:         CLI> uae -m boot:dh0:path -0 /disks/df0.adf 
        !            65: 
        !            66: but rather
        !            67: 
        !            68:         CLI> uae -m boot:/dh0/path -0 ../disks/df0.adf
        !            69: 
        !            70: This is not a bug, but an ixemul.library feature. You can access amiga
        !            71: disks by specifying /dev/<device-name>[.device]/unit or /dev/df<num>
        !            72: after -0. For example you can do "uae -0 /dev/df0" or "uae -0 
        !            73: /dev/trackdisk.device/0". Under the file requester, select the DEV: 
        !            74: assign to access amiga disk-devices.
        !            75: 
        !            76: You can reset the emulator by pressing CTRL-ALT-DEL in UAE's window. I
        !            77: guess it reminds you something :^) You can enter debug mode by pressing
        !            78: ^C or ^D in the cli/shell window or by pressing the close-gadget of
        !            79: UAE's window when used on a public screen.
        !            80: 
        !            81: The F12 key of the X11 version of uae is simulated by pressing
        !            82: CTRL-SHIFT-ALT-F10 simultanemously. This toggles the mouse emulation
        !            83: mode and is needed for some games or demos when you find that the
        !            84: mouse does not work well under UAE.
        !            85: 
        !            86: You can toggle on/off the screen rendering to speed up the sound
        !            87: processing by pressing CTRL-SHIFT-ALT-F9.
        !            88: 
        !            89: You can insert disks by pressing CTRL-LALT-F1, CTRL-LALT-F2,
        !            90: CTRL-LALT-F3, or CTRL-LALT-F4. F1 corresponds to drive DF0, F2 to DF1,
        !            91: and so on. Alternatively you can simply eject a disk by pressing
        !            92: LSHIFT in addition of the above keys.
        !            93: 
        !            94: If UAE does not find a rom-file, it'll use the ROM located at address
        !            95: $F80000 - $FFFFFF. Thus, you need not grab it and that will spare you
        !            96: some disk space. You can disable this feature by creating the
        !            97: environment variable "USE_UAE_ERSATZ", in which case UAE will try to
        !            98: emulate rom calls using a pseudo kickstart.
        !            99: 
        !           100: *NEW*: In this release, UAE should supports Graffiti screens (uae
        !           101: -H3), but I am not able to test it by myself as I don't have that
        !           102: board. Please send me some feedback about it.
        !           103: 
        !           104: *NEW*: This release also features an AREXX port to control UAE from an
        !           105: external gui (see section below). That port is used by the ARexx
        !           106: script "UAEGUI.rexx". That script uses MUIREXX to provide a nice MUI
        !           107: interface for UAE.
        !           108: 
        !           109: 
        !           110: INCLUDED EXECUTABLE SETTINGS
        !           111: ============================
        !           112: 
        !           113: The included executable is compiled for MC68030. It has the following
        !           114: settings in ./config.h:
        !           115: 
        !           116:         #define USE_POINTER
        !           117:         #define CPU_LEVEL 0
        !           118: 
        !           119: AREXX PORT
        !           120: ==========
        !           121: 
        !           122: UAE provides an AREXX port through which you can set or retrieve
        !           123: internal parameters or variables such as the state of the joystick
        !           124: emulation or the framerate and so on. Is also implements a "feedback"
        !           125: mecanism so that a GUI piloting UAE through the AREXX port can hear
        !           126: about dynamical modification of UAE variables such as led states and
        !           127: the like. The port name is "UAE". If that port already exists, UAE
        !           128: will disable it's AREXX feature (that is to say if you have 2 copies
        !           129: of UAE running on your system, only one will have an AREXX port. I
        !           130: doubt anyone will try to run 2 UAE in the same time :-).
        !           131: 
        !           132: The commands that need a string argument accepts quoted strings. If
        !           133: the string is not quoted then it is the following word that will be
        !           134: used. The quotes can be single (') or double ("). They must match (eg.
        !           135: if you begin with ('),then you must end your string with (') too).
        !           136: Within a string, you can use a backslash (\) to express escape
        !           137: sequences. For example, "This 'is' a \"string\"." represents the
        !           138: string (This 'is' a "string"). I hope you get it :-)
        !           139: 
        !           140: Here is a list of the available commands:
        !           141: 
        !           142:         * BYE
        !           143:         * QUIT
        !           144:                 This make the emulator exit.
        !           145: 
        !           146:         * RESET
        !           147:                 This makes a hard-reset of the emulator.
        !           148: 
        !           149:         * DEBUG
        !           150:                 This forces the emulator to enter in debugging mode.
        !           151: 
        !           152:         * EJECT <num>
        !           153:                 This will eject the disk in drive <num> (from 0 to 3).
        !           154: 
        !           155:         * INSERT <num> <filename>
        !           156:                 This will insert the filedisk <filename> in drive unit
        !           157:                 <num>. 
        !           158: 
        !           159:         * FRAMERATE <num>
        !           160:                 This sets the framerate to <num> (1 <= <num> <= 20).
        !           161:                 It is a way to overwrite the -f flag of UAE.
        !           162: 
        !           163:         * VERSION <arg>         (<arg> = NUM | AUTHOR | PORT | STRING)
        !           164:                 This places in the AREXX 'RESULT' variable some
        !           165:                 information about UAE's version. 
        !           166: 
        !           167:                 NUM returns a numerical value that is to be interpreted
        !           168:                 as UAEMAJOR*100 + UAEMINOR*10 + UAEURSAMINOR (ie. uae
        !           169:                 v0.6.4 will return "64").
        !           170: 
        !           171:                 AUTHOR returns the original author of UAE (ie. Bernd
        !           172:                 Schmidt). 
        !           173: 
        !           174:                 PORT returns the name of the port author (that's me!:-)
        !           175:                 
        !           176:                 STRINGS returns a summary string made with the above
        !           177:                 strings. 
        !           178: 
        !           179:         * DISPLAY <arg>         (<arg> = ON | OFF | TOGGLE)
        !           180:                 This will enable or disable the display rendering.
        !           181: 
        !           182:         * FAKEJOYSTICK <arg>    (<arg> = ON | OFF | TOGGLE)
        !           183:                 This will enable or disable the joystick emulation. It
        !           184:                 is a way to overwrite the -J flag from the command
        !           185:                 line. 
        !           186: 
        !           187:         * SOUND <arg>           (<arg> = ON | OFF | BEST)
        !           188:                 This sets the state of the sound emulation (see option
        !           189:                 '-S' on the command line). BEST is the same as using
        !           190:                 the -S3 switch on the commandline.
        !           191: 
        !           192:         * QUERY <var>
        !           193:                 This asks UAE's for its internal variables. That
        !           194:                 state is written in the arexx 'RESULT' variable. So
        !           195:                 don't forget to put 'OPTIONS RESULTS' in your arexx
        !           196:                 scripts. 
        !           197: 
        !           198:                 <var> can be one of the following:
        !           199: 
        !           200:                 * FAKEJOYSTICK => returns "1" if the joystick
        !           201:                   emulation is ON and "0" if it is OFF.
        !           202: 
        !           203:                 * DISPLAY => returns "1" if the display is not
        !           204:                   inhibited and "0" otherwise.
        !           205: 
        !           206:                 * FRAMERATE => returns the current framerate (see
        !           207:                   option -f).
        !           208: 
        !           209:                 * SOUND => returns "0" if the sound is not emulated
        !           210:                   (ie. uae -S0 was used). "1" is returned when the
        !           211:                   sound is OFF (think about uae -S1). "2" means the
        !           212:                   sound emulation is ON and "3" means it is the best
        !           213:                   sound-emulation that is used (uae -S3).
        !           214: 
        !           215:                 * NAME_DF0
        !           216:                 * NAME_DF1
        !           217:                 * NAME_DF2
        !           218:                 * NAME_DF3 => returns the name of the diskfile used in
        !           219:                   the indicated unit.
        !           220:                   
        !           221:                 * LED_DF0
        !           222:                 * LED_DF1
        !           223:                 * LED_DF2
        !           224:                 * LED_DF3 => returns "1" if the drive led is hilighted
        !           225:                   and "0" if the led is OFF.
        !           226: 
        !           227:                 * LED_POW => returns "1" if the powerled is ON and "0"
        !           228:                   otherwise. 
        !           229: 
        !           230:         * FEEDBACK <eventname> PORT|ADDRESS <portname>
        !           231:                                CMD_ON|CMD|CMD_OFF <cmd> 
        !           232:                 That command needs a special explanation:
        !           233: 
        !           234:                 <eventname> is the name of an internal UAE event. It
        !           235:                 can be any of:
        !           236:                    ON_EXIT (UAE is about to quit),
        !           237:                    LED_POW (the power led has changed),
        !           238:                    LED_DF0 (led of drive DF0 has changed),
        !           239:                    LED_DF1 (the same, but for DF1),
        !           240:                    LED_DF2 (well...),
        !           241:                    LED_DF3 (quess!),
        !           242:                    NAME_DF0 (name of filedisk df0 has changed),
        !           243:                    NAME_DF1 (obvious),
        !           244:                    NAME_DF2 (ditto),
        !           245:                    NAME_DF3 (...).
        !           246: 
        !           247:                 <portname> is the name of an AREXX port. It can be
        !           248:                 "COMMAND" in which case <cmd> is interpreted as DOS
        !           249:                 command. 
        !           250: 
        !           251:                 <cmd> is a string containing a command that UAE will
        !           252:                 send to <portname> when the event matching <eventname>
        !           253:                 occur.  
        !           254: 
        !           255:                 Each event has 2 available <cmd>. One is set by the
        !           256:                 CMD_ON keyword, the other by CMD_OFF. CMD_ON can be
        !           257:                 abreviated to CMD.
        !           258: 
        !           259:                 When the event is the name of a led (LED_POW, LED_DF0,
        !           260:                 ...), it is the <cmd> associated to CMD_ON that will be
        !           261:                 sent to <portname> if the led is hilighted. It is the
        !           262:                 <cmd> of the CMD_OFF argument that will be used if the
        !           263:                 led is dimmed. I think you need an example to make it
        !           264:                 clear (no pun intended :)
        !           265: 
        !           266:                 If you issue the command:
        !           267: 
        !           268:                         address UAE feedback LED_POW PORT COMMAND
        !           269:                         CMD_ON "list t:" CMD_OFF "list s:" 
        !           270: 
        !           271:                 Then UAE will issue "list t:" when the led is set to ON
        !           272:                 and "list s:" when it set to OFF. For example in
        !           273:                 UAEGUI.rexx you'll find: 
        !           274: 
        !           275:                         address UAE feedback LED_DF0 PORT UAEGUI,
        !           276:                          CMD_ON  "switch ID DF0 ATTRS 0x8042654b 1",
        !           277:                          CMD_OFF "switch ID DF0 ATTRS 0x8042654b 0"
        !           278: 
        !           279:                 That makes the gui led follow any state changements.
        !           280: 
        !           281:                 If <eventname> is not a name of a led (ON_EXIT,
        !           282:                 NAME_DF0, ...) then UAE will only use the CMD_ON
        !           283:                 command. For events like NAME_DF0, <cmd> can bear a
        !           284:                 '%s'. It'll be replaced by the name of the
        !           285:                 correponding filedisk. For example, the following code:
        !           286: 
        !           287:                         address UAE feedback NAME_DF0 PORT UAEGUI,
        !           288:                          CMD "popasl ID NDF0 CONTENT %s"
        !           289: 
        !           290:                 Will change the content of the popasl gadged
        !           291:                 automatically when the drivename is modified. 
        !           292: 
        !           293:                 The event ON_EXIT is used when uae is about to exit.
        !           294:                 You can use it to automatically close an external GUI
        !           295:                 when UAE ends:
        !           296:                 
        !           297:                         address UAE feedback ON_EXIT PORT UAEGUI,
        !           298:                          CMD "quit"
        !           299:                         /* sends "quit" to UAEGUI when UAE exits */
        !           300: 
        !           301: Note: I hope my explanation about the AREXX port is not too fuzzy. You
        !           302: can always have a look to UAEGUI.rexx to figure out how to use it.
        !           303: 
        !           304: 
        !           305: HOW TO (RE-)BUILD UAE
        !           306: =====================
        !           307: 
        !           308: If you wish to (re-)build uae, you need to have ADE/gcc correctly
        !           309: installed (see ftp://ftp.ninemoons.com/pub/ade/). Not all part of ADE
        !           310: are needed, but be sure to have gcc2.7.2.1, binutils, autoconf, awk, ...
        !           311: 
        !           312: Note: This version uses an amiga specific feature of gcc found in Kamil
        !           313: Iskra's version (http://student.uci.agh.edu.pl/~iskra/ade.html). Look at
        !           314: __attribute__((regparm(4))) in configure.in. This allows gcc to
        !           315: use registered arguments passing. It is only available since gcc2.7.2.1.
        !           316: If it fails with the snapshot you have, then you should comment the
        !           317: definition of REGPARM. Unfortunately that will make UAE run slower. 
        !           318: 
        !           319: The default Makefile provided is for a mc68030 microprocessor. If you
        !           320: wish to have a Makefile tuned for your CPU (and fpu), just type "sh -c
        !           321: configure". Note that you should use sh from the pdksh distribution (in 
        !           322: ADE) if you want a correct "config.cache" file (other shells produces a
        !           323: buggy "config.cache" file).
        !           324: 
        !           325: If you have deleted the file "configure", you can rebuild it from
        !           326: "configure.in". To do this, just type autoconf in a shell. Note that 
        !           327: autoconf 2.10 is required.
        !           328: 
        !           329: Once your Makefile is generated (if needed), you can modify the file
        !           330: "config.h" to suit your needs. You can also modify "src/md-amiga/ami-win.c"
        !           331: to allow the support of cybergfx modes (you'll need to obtain
        !           332: CGraphX-DevKit.lha from aminet then). I suggest you to define
        !           333: DONT_WANT_SOUND in "config.h". That will speed up the emulation (sound
        !           334: emulation slows down the speed by roughly 10%).
        !           335: 
        !           336: When you'll have configured uae correctly, type "make" in a shell. Then
        !           337: one hour and a half later you'll get the uae executable (it might be less
        !           338: if you have a *real fast* Amiga, but don't expect less that 15 minutes).
        !           339: I know it's slow, but Amigas are slow (even those with 68060 are not that
        !           340: fast, by today's standards ;-).  
        !           341: 
        !           342: To compile, 10Mb of free memory should be enough (I have 4Mb, but
        !           343: virtual memory helps in that case). The resulting directory size is
        !           344: roughtly 5.7Mb on my harddrive. Be sure to have a stack of at least
        !           345: 300Kb when compiling UAE and at least 32kb when UAE is running.
        !           346: 
        !           347: 
        !           348: REMARKS OR BUG-REPORTS
        !           349: ======================
        !           350: 
        !           351: You can send me your remarks and bug-report to:
        !           352: 
        !           353:                        [email protected]
        !           354: 
        !           355: 
        !           356: LAST NOTE
        !           357: =========
        !           358: 
        !           359: Why emulate an Amiga on an Amiga ? That can seem to be a foolish
        !           360: behaviour.. Actually it is not !
        !           361: 
        !           362: Many old games/demos refuse to work well if you are using a 68030+;
        !           363: even with degrader running. In that case, uae might be usefull.
        !           364: 
        !           365: UAE might also help graphic-board owners. With UAE, they can view all
        !           366: the demos with copper and blitter effects that fails to run on their
        !           367: graphics board. Or run programs like Deluxe-Paint or Brilliance that
        !           368: poke the hardware directly.
        !           369: 
        !           370: Using uae on a 68040+ Amiga will let you play games or demos on your
        !           371: workbench, in a perfect multitasking. And that is, believe me, quite
        !           372: amazing (even on my poor 68030 :-). Alternatively, UAE makes a 
        !           373: wonderfull screen-saver (a bit memory-hungry though).
        !           374: 
        !           375: The main advantage of uae, will be when PowerPC Amigas will come out.
        !           376: On these machines, I bet no old programs will run. Those machines will
        !           377: certainly include a 680x0 emulation powerfull enough to run DOS 
        !           378: programs, but certainly not sufficient to run old games. Thanks to UAE,
        !           379: backward compatibility will not be a problem anymore. UAE is definitely 
        !           380: a great program ! 

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