![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [UNIX Amiga Emulator] / uae / docs / AmigaOS|
Return to README CVS log | Up to [UNIX Amiga Emulator] / uae / docs / AmigaOS |
1.1 ! root 1: UAE-0.7.0 ! 2: AMIGA version ! 3: ! 4: by Samuel Devulder ! 5: ([email protected]) ! 6: ! 7: Dec. 1997 ! 8: ! 9: ! 10: INTRODUCTION ! 11: ============ ! 12: ! 13: This the Amiga port of UAE v0.7.0. 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: QUICKSTART ! 37: ========== ! 38: ! 39: To quickly try UAE, be sure to have a kick.rom file that comes form ! 40: a real A500, then insert a bootable disk in df0 that runs on a standard ! 41: A500 (a demo for example), and type in a shell: ! 42: ! 43: UAE -H2 -S2 -c2 -s2 -f2 -O320:256:XYl -0/dev/df0 ! 44: ! 45: Then you should see a screen-mode requester. Select the HAM6 (pal:320x256) ! 46: mode, then you should see the demo run in a HAM screen. ! 47: ! 48: The emulated amiga with that setup is a standard A500: 512kb chip, ! 49: 512kb slow fast, sound and full color display. ! 50: ! 51: NOTE: the sound may not work, depending on the internal setup used ! 52: during the compilation for the current executable. ! 53: ! 54: ! 55: FEATURES ! 56: ======== ! 57: ! 58: The joystick can be used within the emulation, allowing you to play ! 59: games without destroying your numeric keypad with the '-J' option :-). ! 60: ! 61: The sound can be emulated in this version. But Amigas are too slow for ! 62: it to be really usefull. On my amiga, UAE produces one second of sound ! 63: every twenty seconds in Sanity's Interference demo. Thus, An amiga which ! 64: is around 20 times faster as an A4000 would be nice. PowerPC Amiga will ! 65: probably achieve this one day. ! 66: ! 67: The CPU emulation is speed up by using ASM code to compute flags ! 68: directly from the 680x0 SR/CCR register. ! 69: ! 70: It supports all Amiga natives mode as well as cybergraphics mode ! 71: (rewritten in that version, so expects bugs in it; I'm waiting your ! 72: bug-reports and improvements :-). It can run on a automatically ! 73: selected custom screen (uae -H0), or on a user-selected screen (-H2), ! 74: or on the default public screen (-H1). It will dither the output when ! 75: not enough colors are available (unless you disable dithering), and ! 76: eventually use a grayscale palette if less that 8 colors are available. ! 77: This will give you the best graphic output according to your configuration. ! 78: (use "uae -h" to know how to selected the rendering style). ! 79: ! 80: In this release, UAE should supports Graffiti screens (uae -H3), but ! 81: I am not able to test it by myself as I don't have that board. Please ! 82: send me some feedback about it. ! 83: ! 84: Using the -H2 option, you can now select a HAM6 screen. In that mode, ! 85: UAE will give colorfull screens. Try it, it's really worth! (I need some ! 86: feedback and comments on the algorithm too :) ! 87: ! 88: *NEW* With the -T option, UAE will use a gray-scale palette. This can ! 89: be handy if you are low on colors (16 free colors for example). ! 90: ! 91: You can mount Amiga partitions using the -m option. Be sure to use unix ! 92: convention when giving a path to UAE. For exemple do not do ! 93: ! 94: CLI> uae -m boot:dh0:path -0 /disks/df0.adf ! 95: ! 96: but rather ! 97: ! 98: CLI> uae -m boot:/dh0/path -0 ../disks/df0.adf ! 99: ! 100: This is not a bug, but an ixemul.library feature. You can access amiga ! 101: disks by specifying /dev/<device-name>[.device]/unit or /dev/df<num> ! 102: after -0. For example you can do "uae -0 /dev/df0" or "uae -0 ! 103: /dev/trackdisk.device/0". Under the file requester, select the DEV: ! 104: assign to access amiga disk-devices. ! 105: ! 106: You can reset the emulator by pressing CTRL-ALT-DEL in UAE's window. I ! 107: guess it reminds you about something :^) You can enter debug mode by ! 108: pressing ^C or ^D in the cli/shell window or by pressing the close-gadget ! 109: of UAE's window when used on a public screen. ! 110: ! 111: The F12 key of the X11 version of uae is simulated by pressing ! 112: CTRL-SHIFT-ALT-F10 simultanemously. This toggles the mouse emulation ! 113: mode and is needed for some games or demos when you find that the ! 114: mouse does not work well under UAE (flickering mouse pointer). ! 115: ! 116: You can toggle on/off the screen rendering to speed up the sound ! 117: processing by pressing CTRL-SHIFT-ALT-F9. ! 118: ! 119: You can insert disks by pressing CTRL-LALT-F1, CTRL-LALT-F2, ! 120: CTRL-LALT-F3, or CTRL-LALT-F4. F1 corresponds to drive DF0, F2 to DF1, ! 121: and so on. Alternatively you can simply eject a disk by pressing ! 122: LSHIFT in addition of the above keys. ! 123: ! 124: If UAE does not find a rom-file, it'll use the ROM located at address ! 125: $F80000 - $FFFFFF. Thus, you need not grab it and that will spare you ! 126: some disk space. You can disable this feature by creating the ! 127: environment variable "USE_UAE_ERSATZ", in which case UAE will try to ! 128: emulate rom calls using a built'in pseudo kickstart. ! 129: ! 130: This release also features an AREXX port to control UAE from an ! 131: external gui (see section below). That port is used by the ARexx ! 132: script "UAEGUI.rexx". That script uses MUIREXX to provide a nice MUI ! 133: interface for UAE. ! 134: ! 135: If you define ENV:UAEIFF to a proper filename, UAE will save an IFF file ! 136: at every frame. For example if you: ! 137: setenv UAEIFF t:uae.%04d ! 138: UAE will create t:uae.0000, t:uae.0001, t:uae.0002, ... ! 139: If you forget the %d format specifier, uae will add ".%05d" to the ! 140: filename as a format. Using that feature, you can build IFF anims ! 141: to play demos on the workbench at full speed (I do it quite often :-). ! 142: ! 143: If you setenv AUDIONAME <filename>, then uae will put the sound-samples ! 144: into <filename>. Using that you can grab soundtracks very easily :-). ! 145: Notice that <filename> can have two "%d". The first one will be ! 146: replaced by the frequency (see the -R flag for UAE) and the second one ! 147: will be replaced by the buffer size (-B option for uae). In addition, ! 148: if ENV:AUDIONAME is not set and if you have the AUDIO: or AUD: handler ! 149: mounted on your system, then UAE will use that handler instead of ! 150: audio.device to play his samples. On one side, the AUD: device driver ! 151: is done by Martin Brenner and can be found on Aminet. On the other side, ! 152: AUDIO: is the AHI dos-driver and is supposed to be a bit better than ! 153: AUD: (especially if you have a DRACO) because it can work with more ! 154: soundcards than the simple paula-chipset. All those DOS drivers give the ! 155: advantage to simplify the audio programming quite a lot on the amiga (to ! 156: play one sample, one just have to send the data to it.. It can't be ! 157: easier). I encourage everyone to use any of those handlers (I thank Paul ! 158: Liss for pointing those drivers to me :-). ! 159: ! 160: *NEW*: If under uae you run "amiga/uae_rcli", then you'll be able to ! 161: run AmigaOS commands in UAE just by using the AREXX "uaeexe" command ! 162: or, even simpler, just by dropping the icon of the executable on ! 163: UAE's window on the workbench. ! 164: ! 165: ! 166: INCLUDED EXECUTABLE SETTINGS ! 167: ============================ ! 168: ! 169: The included executable is compiled for MC68030. It has the following ! 170: settings in ./config.h: ! 171: ! 172: #define USE_POINTER ! 173: #define CPU_LEVEL 0 ! 174: #undef DONT_WANT_SOUND ! 175: ! 176: Note: code compiled for MC68030 runs better on 68060 that if compiled ! 177: for MC68040. ! 178: ! 179: ! 180: AREXX PORT ! 181: ========== ! 182: ! 183: UAE provides an AREXX port through which you can set or retrieve ! 184: internal parameters or variables such as the state of the joystick ! 185: emulation or the framerate and so on. Is also implements a "feedback" ! 186: mecanism so that a GUI piloting UAE through the AREXX port can hear ! 187: about dynamical modification of UAE variables such as led states and ! 188: the like. The port name is "UAE". If that port already exists, UAE ! 189: will disable it's AREXX feature (that is to say if you have 2 copies ! 190: of UAE running on your system, only one will have an AREXX port. I ! 191: doubt anyone will try to run 2 UAE in the same time :-). ! 192: ! 193: The commands that need a string argument accepts quoted strings. If ! 194: the string is not quoted then it is the following word that will be ! 195: used. The quotes can be single (') or double ("). They must match (eg. ! 196: if you begin with ('),then you must end your string with (') too). ! 197: Within a string, you can use a backslash (\) to express escape ! 198: sequences. For example, "This 'is' a \"string\"." represents the ! 199: string (This 'is' a "string"). I hope you get it :-) ! 200: ! 201: Here is a list of the available commands: ! 202: ! 203: * BYE ! 204: * QUIT ! 205: This make the emulator exit. ! 206: ! 207: * RESET ! 208: This makes a hard-reset of the emulator. ! 209: ! 210: * DEBUG ! 211: This forces the emulator to enter in debugging mode. ! 212: ! 213: * EJECT <num> ! 214: This will eject the disk in drive <num> (from 0 to 3). ! 215: ! 216: * INSERT <num> <filename> ! 217: This will insert the filedisk <filename> in drive unit ! 218: <num>. ! 219: ! 220: * FRAMERATE <num> ! 221: This sets the framerate to <num> (1 <= <num> <= 20). ! 222: It is a way to overwrite the -f flag of UAE. ! 223: ! 224: * VERSION <arg> (<arg> = NUM | AUTHOR | PORT | STRING) ! 225: This places in the AREXX 'RESULT' variable some ! 226: information about UAE's version. ! 227: ! 228: NUM returns a numerical value that is to be interpreted ! 229: as UAEMAJOR*100 + UAEMINOR*10 + UAEURSAMINOR (ie. uae ! 230: v0.6.4 will return "64"). ! 231: ! 232: AUTHOR returns the original author of UAE (ie. Bernd ! 233: Schmidt). ! 234: ! 235: PORT returns the name of the port author (that's me!:-) ! 236: ! 237: STRINGS returns a summary string made with the above ! 238: strings. ! 239: ! 240: * DISPLAY <arg> (<arg> = ON | OFF | TOGGLE) ! 241: This will enable or disable the display rendering. ! 242: ! 243: * FAKEJOYSTICK <arg> (<arg> = ON | OFF | TOGGLE) ! 244: This will enable or disable the joystick emulation. It ! 245: is a way to overwrite the -J flag from the command ! 246: line. ! 247: ! 248: * SOUND <arg> (<arg> = ON | OFF | BEST) ! 249: This sets the state of the sound emulation (see option ! 250: '-S' on the command line). BEST is the same as using ! 251: the -S3 switch on the commandline. ! 252: ! 253: * QUERY <var> ! 254: This asks UAE's for its internal variables. That ! 255: state is written in the arexx 'RESULT' variable. So ! 256: don't forget to put 'OPTIONS RESULTS' in your arexx ! 257: scripts. ! 258: ! 259: <var> can be one of the following: ! 260: ! 261: * FAKEJOYSTICK => returns "1" if the joystick ! 262: emulation is ON and "0" if it is OFF. ! 263: ! 264: * DISPLAY => returns "1" if the display is not ! 265: inhibited and "0" otherwise. ! 266: ! 267: * FRAMERATE => returns the current framerate (see ! 268: option -f). ! 269: ! 270: * SOUND => returns "0" if the sound is not emulated ! 271: (ie. uae -S0 was used). "1" is returned when the ! 272: sound is OFF (think about uae -S1). "2" means the ! 273: sound emulation is ON and "3" means it is the best ! 274: sound-emulation that is used (uae -S3). ! 275: ! 276: * NAME_DF0 ! 277: * NAME_DF1 ! 278: * NAME_DF2 ! 279: * NAME_DF3 => returns the name of the diskfile used in ! 280: the indicated unit. ! 281: ! 282: * LED_DF0 ! 283: * LED_DF1 ! 284: * LED_DF2 ! 285: * LED_DF3 => returns "1" if the drive led is hilighted ! 286: and "0" if the led is OFF. ! 287: ! 288: * LED_POW => returns "1" if the powerled is ON and "0" ! 289: otherwise. ! 290: ! 291: * UAEEXE [run] <executable> <args> ! 292: This will make UAE lauch the <executable> provided ! 293: you've previouly starded uaeexe. If <executable> is ! 294: "QUIT", then the "uaeexe" process will exit(). Note that ! 295: you must use "run" in order to launch the executable as ! 296: an asynchronous command. ! 297: ! 298: * FEEDBACK <eventname> PORT|ADDRESS <portname> ! 299: CMD_ON|CMD|CMD_OFF <cmd> ! 300: That command needs a special explanation: ! 301: ! 302: <eventname> is the name of an internal UAE event. It ! 303: can be any of: ! 304: ON_EXIT (UAE is about to quit), ! 305: LED_POW (the power led has changed), ! 306: LED_DF0 (led of drive DF0 has changed), ! 307: LED_DF1 (the same, but for DF1), ! 308: LED_DF2 (well...), ! 309: LED_DF3 (guess!), ! 310: NAME_DF0 (name of filedisk df0 has changed), ! 311: NAME_DF1 (obvious), ! 312: NAME_DF2 (ditto), ! 313: NAME_DF3 (...). ! 314: ! 315: <portname> is the name of an AREXX port. It can be ! 316: "COMMAND" in which case <cmd> is interpreted as DOS ! 317: command. ! 318: ! 319: <cmd> is a string containing a command that UAE will ! 320: send to <portname> when the event matching <eventname> ! 321: occur. ! 322: ! 323: Each event has 2 available <cmd>s. One is set by the ! 324: CMD_ON keyword, the other by CMD_OFF. CMD_ON can be ! 325: abreviated to CMD. ! 326: ! 327: When the event is the name of a led (LED_POW, LED_DF0, ! 328: ...), it is the <cmd> associated to CMD_ON that will be ! 329: sent to <portname> if the led is hilighted. It is the ! 330: <cmd> of the CMD_OFF argument that will be used if the ! 331: led is dimmed. I think you need an example to make it ! 332: clear (no pun intended :) ! 333: ! 334: If you issue the command: ! 335: ! 336: address UAE feedback LED_POW PORT COMMAND ! 337: CMD_ON "list t:" CMD_OFF "list s:" ! 338: ! 339: Then UAE will issue "list t:" when the led is set to ON ! 340: and "list s:" when it set to OFF. Note: this feature ! 341: was not initially meant to transform UAE as a dir-like ! 342: programm :-) A more serious example can be found in ! 343: UAEGUI.rexx where you'll find something like: ! 344: ! 345: address UAE feedback LED_DF0 PORT UAEGUI, ! 346: CMD_ON "switch ID DF0 ATTRS 0x8042654b 1", ! 347: CMD_OFF "switch ID DF0 ATTRS 0x8042654b 0" ! 348: ! 349: That makes the gui led follow any state changements. ! 350: ! 351: If <eventname> is not a name of a led (ON_EXIT, ! 352: NAME_DF0, ...) then UAE will only use the CMD_ON ! 353: command. For events like NAME_DF0, <cmd> can bear a ! 354: '%s'. It'll be replaced by the name of the ! 355: correponding filedisk. For example, the following code: ! 356: ! 357: address UAE feedback NAME_DF0 PORT UAEGUI, ! 358: CMD "popasl ID NDF0 CONTENT %s" ! 359: ! 360: Will change the content of the popasl gadged whose ID ! 361: is NDF0 automatically when the drivename is modified. ! 362: ! 363: The event ON_EXIT is used when uae is about to exit. ! 364: You can use it to automatically close an external GUI ! 365: when UAE ends: ! 366: ! 367: address UAE feedback ON_EXIT PORT UAEGUI, ! 368: CMD "quit" ! 369: /* sends "quit" to UAEGUI when UAE exits */ ! 370: ! 371: Note: I hope my explanation about the ARexx port is not too fuzzy. ! 372: You can always have a look to UAEGUI.rexx to figure out how to use ! 373: it. The script UAEGUI.rexx needs MUIRexx v2.2 by Russ Leighton ! 374: <[email protected]>. MUIRexx can be found on Aminet and ! 375: allows quick programming of GUIs with MUI and ARexx. ! 376: ! 377: ! 378: HOW TO (RE-)BUILD UAE ! 379: ===================== ! 380: ! 381: If you wish to (re-)build uae, you need to have ADE/gcc correctly ! 382: installed (see ftp://ftp.ninemoons.com/pub/ade/). Not all part of ADE ! 383: are needed, but be sure to have gcc2.7.2.1, binutils, autoconf, awk, ... ! 384: *NEW* You can now try to compile uae with SAS/C (see below). ! 385: ! 386: Note: This version uses an amiga specific feature of gcc found in Kamil ! 387: Iskra's version (http://student.uci.agh.edu.pl/~iskra/ade.html). Look at ! 388: __attribute__((regparm(4))) in configure.in. This allows gcc to ! 389: use registered arguments passing. It is only available since gcc2.7.2.1. ! 390: If it fails with the snapshot you have, then you should comment the ! 391: definition of REGPARM in src/Makefile. Unfortunately that will make ! 392: UAE run slower. (97/11/05: Now regparm is a feature that exists ! 393: in recent ADE snapshots, so you won't need worry about it if you use ! 394: a recent snapshot). ! 395: ! 396: The default Makefile provided is for a MC68030 microprocessor. If you ! 397: wish to have a Makefile tuned for your CPU (and fpu), just type "sh -c ! 398: configure". Note that you should use sh from the pdksh distribution (in ! 399: ADE) if you want a correct "config.cache" file (other shells produces a ! 400: buggy "config.cache" file). ! 401: ! 402: If you have deleted the file "configure", you can rebuild it from ! 403: "configure.in". To do this, just type autoconf in a shell. Note that ! 404: autoconf 2.10 is required. ! 405: ! 406: Once your Makefile is generated (if needed), you can modify the file ! 407: "config.h" to suit your needs. You can also modify "src/md-amiga/ami-win.c" ! 408: to allow the support of cybergfx modes (you'll need to obtain ! 409: CGraphX-DevKit.lha from Aminet then). I suggest you to define ! 410: DONT_WANT_SOUND in "config.h". That will speed up the emulation (sound ! 411: emulation slows down the speed by roughly 10%). ! 412: ! 413: When you'll have configured uae correctly, type "make" in a shell. Then ! 414: one hour and a half later you'll get the uae executable (it might be less ! 415: if you have a *real fast* Amiga, but don't expect less that 15 minutes). ! 416: I know it's slow, but Amigas are slow (even those with 68060 are not that ! 417: fast, by today's standards ;-). ! 418: ! 419: To compile, 10Mb of free memory should be enough (I succeded with 4Mb, but ! 420: virtual memory helps in that case). The resulting directory size is ! 421: roughtly 5.7Mb on my harddrive. Be sure to have a stack of at least ! 422: 300Kb when compiling UAE and at least 32kb when UAE is running. ! 423: ! 424: NOTE: I had reports that gcc complains and fail to compile cpu_f?.s. ! 425: This is caused by a problem with perl and src/md-amiga/cpuopti. I don't ! 426: know where it comes from precisely as I never experienced that problem. ! 427: Anyway, to avoid this, you should uncomment the lines in the beginning of ! 428: src/md-amiga/cpuopti. Unfortunately, UAE will run slower as the asm files ! 429: won't have an extra optimisation pass. ! 430: ! 431: ! 432: COMPILING UAE WITH SAS/C ! 433: ======================== ! 434: ! 435: To compile UAE with SAS/C you'll need SAS/C V6.58 and a subpart of ADE. ! 436: That subpart must include ixemul, sh, make and perl to do the compilation ! 437: and at least sh-utils, cpp, perl, sed, autoconf to run the configure ! 438: script. Probably a few other package are needed, so if you want to be on ! 439: the safe side, you had rather had ADE completely installed. On my machine, ! 440: the subpart of ADE I use (gcc, g++, man, curses, termcap, ...) takes only ! 441: 14Mb on an XFH partition.. that's not much, but I've spent time to replace ! 442: duplicates with symbolic links. ! 443: ! 444: Once you have ADE properly installed, you must copy the file ! 445: "src/od-amiga/scc" to somewhere in your path (sc:c for example). You can ! 446: also do something like: ! 447: CLI> assign c: src/od-amiga add ! 448: or any other solution. The purpouse is to enable ADE's tools to find scc. ! 449: The file scc is a perl script that tries to emulate gcc behaviour using ! 450: SAS/C. [note to amiga-developpers: that script is tuned for UAE, but I ! 451: think it can be modified for other projects, let me know about it if you ! 452: intend enhance it]. Then, do: ! 453: CLI> setenv CC scc ! 454: to tell the configure script to use scc as the C compiler. Next, run the ! 455: configure script: ! 456: CLI> sh -c configure --enable-sound ! 457: The configure script will probably produce warnings, but they are not ! 458: important. Then, check src/Makefile to see if it fills your needs (you'll ! 459: probably have to replace -g with -O3 to have an optimised version of UAE, ! 460: and modify -m<cputype> with -m68060 if you have a 68060 cpu). Now, as the ! 461: last operation, type in ! 462: CLI> make ! 463: to build UAE and be patient! (it takes a while with optimisations enabled). ! 464: ! 465: Last note about SAS/C: Compiling UAE with SAS/C instead of gcc will ! 466: disable some nice features of UAE (native filesystems mounting, ! 467: average time per frame computation, ...) because SAS/C is not enough ! 468: POSIX compliant. ! 469: ! 470: ! 471: REMARKS OR BUG-REPORTS ! 472: ====================== ! 473: ! 474: You can send me your remarks and bug-report to: ! 475: ! 476: [email protected] ! 477: ! 478: ! 479: LAST NOTE ! 480: ========= ! 481: ! 482: Why emulate an Amiga on an Amiga ? That can seem to be a foolish ! 483: behaviour.. Actually it is not ! ! 484: ! 485: Many old games/demos refuse to work well if you are using a 68030+; ! 486: even with degrader running (ever tried to make ST4Amiga work on ! 487: anything greater than a 68000?). In that case, uae might be usefull. ! 488: ! 489: UAE might also help graphic-board owners. With UAE, they can view all ! 490: the demos with copper and blitter effects that fails to run on their ! 491: graphics board. Or run programs like Deluxe-Paint or Brilliance that ! 492: poke the hardware directly. ! 493: ! 494: Using uae on a 68040+ Amiga will let you play games or demos on your ! 495: workbench, in a perfect multitasking. And that is, believe me, quite ! 496: amazing (even on my poor 68030 :-). Alternatively, UAE makes a ! 497: wonderfull screen-saver (a bit memory-hungry though). ! 498: ! 499: The main advantage of uae, will be when PowerPC Amigas will come out. ! 500: On these machines, I bet no old programs will run. Those machines will ! 501: certainly include a 680x0 emulation powerfull enough to run DOS ! 502: programs, but certainly not sufficient to run old games. Thanks to UAE, ! 503: backward compatibility will not be a problem anymore. UAE is definitely ! 504: a great program !
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.