![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to README.AMIGA CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [UNIX Amiga Emulator] / uae / docs|
Return to README.AMIGA CVS log | Up to [UNIX Amiga Emulator] / uae / docs |
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.