![[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.