![[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|
Return to README CVS log | Up to [UNIX Amiga Emulator] / uae / docs |
1.1 ! root 1: This is version 0.6.4 of UAE, the Un*x Amiga Emulator. ! 2: ! 3: #include <drivel.h> ! 4: ! 5: Copyright 1995, 1996 Bernd Schmidt & contributors (see below). This program is ! 6: freeware. You may do whatever you want with it for personal use. ! 7: Permission is granted to redistribute this program free of charge, provided it ! 8: is distributed in the full archive with unmodified contents and no profit ! 9: beyond the price of the media on which it is distributed is made. Exception to ! 10: the last rule: It may be included on freeware/shareware collections on CD-ROM. ! 11: There are no warranties of any kind for this program. If you use this program, ! 12: you do so at your own risk. The authors are not responsible for any damages ! 13: that might result from using this program. ! 14: ! 15: ! 16: Overview ! 17: ======== ! 18: ! 19: UAE emulates the hardware of an A500 with 2MB chip and a variable amount of ! 20: fast memory. Up to 11.8MB RAM are supported. It works with all Kickstart ROM ! 21: versions, provided they are not compiled for the 68020. It supports some (one, ! 22: to be precise) ECS features apart from nearly all the functionality of an OCS ! 23: chipset. ! 24: ! 25: UAE was developed for Unixoid systems. Meanwhile, it has been ported to the ! 26: Mac, DOS, the BeBox, NextStep, the XFree86/OS2 environment and AA Amigas (it ! 27: can't quite run itself yet). The Mac and DOS versions are distributed with ! 28: binaries and a seperate README file that you should read after you have ! 29: finished this document. The other versions must be compiled from the source ! 30: code. ! 31: ! 32: What UAE does not (yet) emulate is software. To use UAE, you need a Kickstart ! 33: ROM image as well as any other software you want to run, e.g. a Workbench ! 34: disk. Both are copyrighted, and I can't include them. Don't ask me to send ! 35: them to you. ! 36: Since the PC floppy controller can't read Amiga disks (yes, that's a fact), ! 37: floppy access has to be emulated differently: Floppies are emulated by means ! 38: of disk files that contain a raw image of the floppy disk you want to emulate. ! 39: Read the section "tools" below for information how to create ROM images and ! 40: disk files. ! 41: You can also emulate a harddisk. UAE can mount native filesystems as ! 42: harddrives, so once you have booted it up, you can access all your files on ! 43: the harddisk. It is currently impossible to boot from the emulated harddisk. ! 44: I don't have a clue why. ! 45: ! 46: I am developing UAE using Linux. Only if you are running Linux can you be ! 47: reasonably sure that all versions of UAE will work for you. On other Unix ! 48: systems, you may encounter problems from time to time. I can make no ! 49: guarantees about the NextStep and BeBox versions, these are very recent ports ! 50: and will probably need some more time before they compile/run reliably. ! 51: ! 52: These are the requirements for getting the Unix version to run: ! 53: - X11, or SVGAlib if you are using Linux. ! 54: - an ANSI C compiler. GCC is _strongly_ recommended. ! 55: - Optionally, tcl7.4/tk4.0 ! 56: ! 57: Note: some Linux installations (usually Slackware) are broken. If you get ! 58: linker errors ("final link failed: bad value"), you need to upgrade the ! 59: binutils package that you can find on sunsite.unc.edu:/pub/Linux/GCC ! 60: Before installing anything from that directory, read the corresponding ! 61: release.* files. ! 62: You'll get better performance if you are using an ELF system. ! 63: ! 64: On Linux, 8MB are sufficient to run UAE, although startup will be much faster ! 65: if you have some additional memory. The DOS version also works with 8MB, but ! 66: startup is slow there too. I have not tried the other ports, it may well be ! 67: that other OS's are better at wasting memory. At least 16MB are recommended. ! 68: ! 69: This section is just what it says: an overview. Please read _all_ of this ! 70: file, especially if you have problems. Please read also the file "FAQ" which ! 71: contains some Frequently Asked Questions (and even the answers!) ! 72: ! 73: ! 74: Installation ! 75: ============ ! 76: ! 77: To build UAE, first unpack it to an appropriate directory (e.g. /usr/src/uae ! 78: on a Linux system). After that, you will have to edit the file config.h to set ! 79: some configuration options. Then, you should give the command "configure". ! 80: This script will determine what type of system you are using. It will then ! 81: create an appropriate Makefile. Type "make" after that to build UAE. ! 82: ! 83: If you are running Linux, you can say "configure --without-x" as an ! 84: alternative. If you do this, UAE will be configured to use the SVGA library. ! 85: If you use SVGAlib, be warned that SVGAlib is not too stable and using it is ! 86: inherently a little dangerous, you might want to have a way to log in from a ! 87: remote terminal if things go horribly wrong. If you are very unfortunate, you ! 88: might lock up your machine otherwise. ! 89: Note that you must be root to run SVGAlib programs. Making UAE suid root is ! 90: _not_ a particularly good idea if you care about the security of your system. ! 91: If you have a BeBox, you should not run configure. Instead, compile UAE by ! 92: doing "make bebox". ! 93: ! 94: If you configure UAE for building the X11 version (which is the default if you ! 95: simply say "configure"), the configure script will try to find the program ! 96: "wish4.0" in the path. You can disable the UAE user-interface by passing the ! 97: "--disable-gui" option to configure. By default, the X11 version of UAE ! 98: tries to use a GUI written in Tcl. This requires Tk version 4.0. The SVGAlib ! 99: version uses a ncurses-based user interface. ! 100: ! 101: The compilation may take a while, especially for the cpu*.c files. There might ! 102: be some warnings, ignore these. It may also take a lot of memory. You should ! 103: have at least 8MB physical RAM to compile this, plus maybe 10MB swap and 9MB ! 104: filesystem space. ! 105: ! 106: After compilation, you'll need to install the ROM image. This must have a size ! 107: of exactly 512K (if you only have a 256K image of a 1.x Kickstart, that should ! 108: work, too) and should be an image of the addresses 0xF80000-0xFFFFFF on ! 109: your Amiga system. The file must be called kick.rom to be recognized. Please ! 110: read the next section on how to transfer files from your Amiga to your PC. ! 111: ! 112: You also need to install a disk image file. This must be called df0.adf (adf = ! 113: Amiga Disk File), and should be a raw image of the data on the floppy disk: ! 114: 11x2x80 sectors == 901120 bytes. ! 115: Please try running UAE without a diskfile first. If everything went O.K., the ! 116: emulator should show the Kickstart logo (don't be too impatient, this will ! 117: take a while on slow machines). ! 118: ! 119: If you don't have a Kickstart file, you may still be able to boot some games ! 120: and demos. The emulator includes some primitive bootstrap code that will try ! 121: to read and execute the bootblock of the diskfile you are using, and if that ! 122: bootblock only uses the one or two Kickstart functions that are supported by ! 123: the "replacement Kickstart", your program will boot. Don't expect too much, ! 124: though. ! 125: ! 126: If you are a daring person, you can edit custom.c before compiling and enable ! 127: the "EMULATE_AGA" define. UAE will then try to emulate some AGA features. I'd ! 128: like to hear feedback as to how well it works (expect it not to work at all ! 129: for a start). ! 130: ! 131: ! 132: Invoking UAE ! 133: ============ ! 134: ! 135: After building the program, you should have an executable called "uae". You ! 136: can simply execute it, but you can also optionally give it one of the following ! 137: parameters: ! 138: ! 139: General options: ! 140: -h : Give help on the options. ! 141: -f n : Sets the frame rate to 1/n. Only every nth screen will be drawn. ! 142: -a : Add no expansion devices. This will disable fastmem and harddisk ! 143: emulation, but some extremely badly-written games may need this. ! 144: -l lang : Set the keyboard language. Currently, the following values can be ! 145: used for lang: "us" for U.S. keyboard (default), "se" for swedish, ! 146: "fr" for french, "it" for italian or "de" for german keyboard. ! 147: -0 file : Try to use file as diskfile for drive 0 instead of df0.adf. ! 148: -1 file, -2 file and -3 also exist for the other drives. ! 149: -r file : Use file instead of kick.rom as Kickstart image. ! 150: -J : Use the numeric pad for joystick emulation (with 5 and 0 as fire ! 151: buttons). This will turn off real joystick support. It's no good ! 152: for action games, but may be useful for other games. ! 153: -x : General-purpose option. For the X version, it makes the X cursor ! 154: visible (recommended). For the SVGAlib version, it turns off ! 155: linear framebuffer support (sometimes, with -d 4, SVGAlib is ! 156: faster without linear framebuffer). ! 157: -o : Allow UAE to overwrite ~/.uaerc with the selected options. This is ! 158: only used by the text-based GUI in the SVGAlib and DOS versions. ! 159: -G : Disable the user interface (if present). ! 160: ! 161: Emulating external devices (harddisk, printer, serial port): ! 162: -M VOLUME:path ! 163: -m VOLUME:path ! 164: mount the unix file system at path as an Amiga filesystem with ! 165: volume name "VOLUME:". For example, "-M sound:/usr/amiga/modules" ! 166: If you use -M instead of -m, the volume will be read only. ! 167: See below. ! 168: -p cmd : Enable printing. See below. ! 169: -I dev : Use "dev" as serial device (e.g. /dev/ttyS1 on Linux). Doesn't ! 170: really work yet, at least not for me. ! 171: ! 172: Sound options: ! 173: -S n : If your version of UAE supports sound, set the sound support level ! 174: with this option. ! 175: n = 0: No proper sound emulation at all. May be incompatible ! 176: (unlikely). This is the default. ! 177: n = 1: Emulate the sound hardware, but don't output sound. May be ! 178: needed for compatibility, but can be much slower ! 179: n = 2: Emulate the sound hardware and output sound. Recommended. ! 180: n = 3: Emulate the sound hardware _exactly_. I don't think you'll ! 181: hear a difference. SIDmon modules will be emulated ! 182: correctly, but painfully slow with this setting. ! 183: -b n : Use n bits for sound output (8 or 16) ! 184: -R n : Use n Hz to output sound. Common values are 22050 Hz or 44100 Hz. ! 185: -B n : Use a sound buffer of n bytes (use small values on fast machines) ! 186: Default is 8192. ! 187: ! 188: Memory options: ! 189: -s n : Emulate n*256K slow memory at 0xC00000. Some demos/games need this. ! 190: -F n : Emulate n megabytes of fast memory as an expansion board. ! 191: -c n : Emulate n*512K chip memory. The default is 2MB chipram. Some very ! 192: broken programs need "-c 1" to work properly. ! 193: ! 194: Debugging options: ! 195: -D : Don't start the emulator at once, use the built-in debugger. ! 196: -i : Print illegal memory accesses ! 197: -g : Emulate parts of the OS. This isn't very stable and not ! 198: recommended. ! 199: ! 200: Display options: ! 201: -d mode : Select a graphical resolution for UAE to run in. ! 202: -H mode : Select a color mode to use. ! 203: -C : Correct the aspect. Normally, graphics will be only half as high ! 204: as they should be, this option draws every line twice to correct ! 205: this. It makes the emulation slower, though. ! 206: Proper emulation of interlace mode is impossible without this ! 207: option. ! 208: ! 209: Resolutions: 0 (320x200); 1 (320x240); 2 (320x400); 3 (640x480); ! 210: 4 (800x600). ! 211: Color modes: 0 (256 colors, default); 1 (32768 colors); 2 (65536 colors) ! 212: 3 (256 colors, with dithering to improve color quality) ! 213: 4 (16 colors, dithered); 5 (16 million colors) ! 214: ! 215: UAE may choose to ignore and/or refuse some combinations of these two ! 216: parameters. Some of these modes may also fail to work on your system. ! 217: ! 218: You can also put these options into a configuration file in your home ! 219: directory. Simply create ~/.uaerc and put some of these options in it. On ! 220: non-Unix systems, the file is called uae.rc and should be located in the ! 221: current directory. ! 222: ! 223: If you use SVGAlib, the only way to leave the program is pressing F12. ! 224: ! 225: ! 226: Choosing color and screen modes ! 227: =============================== ! 228: ! 229: As described in the previous paragraph, UAE can run in many different ! 230: resolutions and color modes. However, few of the color mode options are ! 231: available if you use the X11 version of UAE, since the X server determines ! 232: how many colors are available. If you are running a 256 color X server, you ! 233: can use "-H3" to tell UAE to dither the colors for better results. ! 234: ! 235: You will have to experiment which mode gives the best results for you at a ! 236: satisfying speed. Note that the dithering process consumes time, so even if ! 237: 256 colors with dithering look better than 256 colors without, remember that ! 238: UAE will be slower in that mode. ! 239: ! 240: The low-resolution (320x???) modes should help some of the proud owners of new ! 241: P6 systems with a broken chipset and an exciting PCI performance of 4MB/s :-) ! 242: ! 243: The recommended resolution is 800x600. In the lower resolution modes, some ! 244: overscan pictures the Amiga tries to display may not fit entirely on the ! 245: screen, others may be off-center and some graphical effects may look weird. ! 246: For best results, use 800x600 with at least 32768 colors. ! 247: ! 248: ! 249: Harddisk emulation ! 250: ================== ! 251: ! 252: !! Careful: All of this has been rewritten for this version. There may be ! 253: bugs, please report any strange events. ! 254: ! 255: Using diskfiles is awkward. There are two ways how you can use larger amounts ! 256: of data with UAE. UAE can emulate more than one harddisk at one time, the ! 257: volumes will be named UAE0:, UAE1:, etc. UAE will boot from UAE0: if no ! 258: diskfile is found for floppy drive 0. ! 259: ! 260: a) Harddisk files. ! 261: You can create a (unformatted) harddisk file with ! 262: ! 263: dd if=/dev/zero of=hardfile bs=512 count=16384 ! 264: ! 265: Currently, the size is fixed (8MB). ! 266: ! 267: The harddisk file is accessed by a resident ROM module that is built into the ! 268: emulator, called "hardfile.device". If it is present, this is always the first ! 269: harddisk device the emulator finds and will be named UAE0: ! 270: ! 271: If you are using Kickstart 1.3 or earlier, this can't currently be mounted at ! 272: boot time, and therefore you can't boot from it either. You will have to boot ! 273: either from a floppy disk image or from a filesystem (see below), and mount ! 274: the hardfile.device later. To do this, add the following to "DEVS:mountlist": ! 275: ! 276: UAE0: Device = hardfile.device ! 277: Unit = 0 ! 278: Flags = 0 ! 279: Surfaces = 1 ! 280: BlocksPerTrack = 32 ! 281: Reserved = 1 ! 282: Interleave = 0 ! 283: LowCyl = 0 ; HighCyl = 511 ! 284: Buffers = 5 ! 285: DosType = 0x444F5300 ! 286: BufMemType = 1 ! 287: # ! 288: ! 289: Then, type "mount UAE0:" (or put that command in your startup-sequence), and ! 290: you should be able to access it. Don't forget to format it with the AmigaDOS ! 291: format command: ! 292: ! 293: format drive uae0: name Mister_Willwink ! 294: ! 295: b) Access native filesystems from the emulator. ! 296: ! 297: This has some major advantages: ! 298: - It has no problems with Kickstart 1.3 ! 299: - It is more convenient. ! 300: - It is much faster. In fact, it can be dramatically faster even than a real ! 301: Amiga when reading directories. ! 302: ! 303: However, it currently does not work on some ports. ! 304: ! 305: If you specify the -M or -m command line arguments, you can use files on your ! 306: Unix filesystem from the emulator. If you start UAE with ! 307: ! 308: uae -m sound:/usr/amiga/modules ! 309: ! 310: you can access all the files in /usr/amiga/modules by reading from the ! 311: AmigaDOS volume "SOUND:". ! 312: (DOS users: try "uae -m dh0:C:\" to mount your drive C:\ as DH0:) ! 313: ! 314: If you want to execute files, they need to have the x permission bit set. ! 315: That can be done in Unix by "chmod +x file" or in AmigaDOS with ! 316: "protect file rwed". ! 317: You can mount up to 20 devices by giving this option multiple times. ! 318: ! 319: ! 320: Tools / Transferring files ! 321: ========================== ! 322: ! 323: To transfer any software between an Amiga and another computer, you'll need ! 324: either a tool like CrossDOS or MessyFS on the Amiga that lets you read and ! 325: write PC formatted disks, or a serial null-modem cable. CrossDOS is part of ! 326: the newer Amiga operating systems; MessyFS is free software and can probably ! 327: be found on some old Fish disk. To transfer data over a null-modem cable it is ! 328: useful to use some sort of terminal software on both ends. I can't explain ! 329: here in every detail how to use terminal programs or CrossDOS. Please read the ! 330: appropriate documentation. Note: If you use a tool to read/write PC-formatted ! 331: disks on the Amiga, remember that most Amiga drives handle only DD disks, so ! 332: don't try to use HD floppies. ! 333: ! 334: In the "amiga" subdirectory you'll find two small Amiga programs that you can ! 335: use to transfer software from the Amiga to the PC. These are called transrom ! 336: and transdisk. Copy them to your Amiga and make them executable (by typing ! 337: "protect transrom rwed" and "protect transdisk rwed" in the Amiga shell ! 338: window). ! 339: transrom will dump the contents of your Kickstart ROM, and transdisk will ! 340: dump an image of a floppy in one of the drives. Both programs write to the ! 341: standard output, so you'll want to redirect that. Do ! 342: ! 343: transrom >ram:kick.rom ! 344: ! 345: to create a file called "kick.rom" in the RAM disk, and ! 346: ! 347: transdisk >ram:df0.adf ! 348: ! 349: to create a file called "df0.adf" in the RAM disk. These files are pretty ! 350: big, 524288 bytes for the ROM image and 901120 bytes for a disk image. ! 351: transdisk understands the following arguments: ! 352: ! 353: -d device unit: Use this device instead of DF0: ! 354: -s n: Begin transfer at track n (default: 0) ! 355: -e n: End transfer at track n (default: 79) ! 356: ! 357: So, to transfer the disk in drive DF1:, you'd give the command: ! 358: ! 359: transdisk >ram:df1.adf -d trackdisk 1 ! 360: ! 361: If you don't have much RAM and can't fit all of a disk image in the RAM disk, ! 362: you can split up the transfer into multiple parts with the "-s" and "-e" ! 363: parameters. To transfer the disk in four parts, you'd use the following ! 364: commands: ! 365: ! 366: transdisk >ram:df0_1.adf -s 0 -e 19 ! 367: transdisk >ram:df0_2.adf -s 20 -e 39 ! 368: transdisk >ram:df0_3.adf -s 40 -e 59 ! 369: transdisk >ram:df0_4.adf -s 60 -e 79 ! 370: ! 371: Of course, you should save each of the four files to another place before ! 372: transferring the next one with transdisk to make space in your RAM disk. ! 373: If you have all the files on your PC, you can do the following under Unix: ! 374: cat df0_1.adf df0_2.adf df0_3.adf df0_4.adf >df0.adf ! 375: or, under DOS: ! 376: COPY /B df0_1.adf df0_2.adf df0_3.adf df0_4.adf df0.adf ! 377: I've been told there are the following tools for the Mac to join binaries: ! 378: "ChunkJoiner 2.1.2" found under Info-Mac's <disk> directory or ! 379: "JoinFiles 1.0.1" under Info-Mac's <text>. ! 380: ! 381: The current transdisk can only read the standard AmigaDOS format. This means ! 382: that most games that rely on some form of copy-protection cannot be ! 383: transferred. However, there are disks that are formatted in the normal 880K ! 384: format that transdisk can read, but don't have a filesystem ("NDOS" disks ! 385: in the Workbench). These will be transferred correctly. ! 386: ! 387: There's an easy way to use a null-modem cable without terminal software if ! 388: you use Linux. You can do ! 389: ! 390: transdisk >SER: <options> ! 391: ! 392: on the Amiga to copy the data directly to the serial port. Before that, do ! 393: ! 394: cat /dev/ttyS1 >df0.adf ! 395: ! 396: on your Linux box to receive the data (it may be ttyS0 on your system, or ! 397: another number, depending on which serial port you are using). When the Amiga ! 398: is done transferring, hit ^C on the PC to interrupt the cat program. To make ! 399: this work, you need to use the same settings for the serial port on both ! 400: sides. This is done with the Preferences program on the Amiga (this is split ! 401: into several programs from Kickstart 2.0 upwards, you'll find a program called ! 402: "serial" in the Prefs directory of your Workbench disk). On the Linux side, ! 403: use the stty program. "man stty" will give you the manpage describing how to ! 404: use it. ! 405: To be on the safe side, set the speed to a low value (2400 baud). Turn off ! 406: Xon/Xoff, but enable RTS/CTS. ! 407: I use the following command myself: ! 408: ! 409: stty 19200 parenb -cstopb cread clocal crtscts -istrip -inlcr -icrnl -opost ! 410: -onlcr -parodd -isig -icanon -iexten raw cs8 </dev/ttyS1 ! 411: ! 412: which is probably overkill, but you never know :) ! 413: This maps to 19200 baud, 8 bits, even parity, one stop bit, which you have to ! 414: set in the Amiga preferences. ! 415: ! 416: If you transfer commercial software, you must not distribute the resulting ! 417: image files, since that would be a violation of copyright law. The Kickstart ! 418: ROM has to be considered commercial software. You may only use the Kickstart ! 419: from your own Amiga, and you may not distribute Kickstart ROM files. ! 420: Please read the license that came with your software for details. ! 421: ! 422: If you have a disk image file, and you want to retrieve the files from it, you ! 423: can use the "readdisk" tool. It is automatically built by "make". If you have ! 424: a disk image of a disk called "Workbench1.3D" as df0.adf, and you do ! 425: readdisk df0.adf ! 426: the whole directory structure of the disk image will be stored in a newly ! 427: created subdirectory called "Workbench1.3D". You can optionally give a second ! 428: parameter to specify a directory where to create the output other than the ! 429: current directory. ! 430: readdisk only understands about the OFS right now. FFS disks will cheerfully ! 431: be regarded as being unreadable. Use the unixfs.device from within the ! 432: emulator if you want to transfer files from FFS disks. If you use Linux with ! 433: a kernel version >= 2.0.7 and version 2.5k of the mount program, you can do ! 434: mount df0.adf /mnt -t affs -o loop ! 435: You'll need to enable support for the Amiga filesystem and the loop device ! 436: when configuring and compiling the kernel. ! 437: ! 438: ! 439: ! 440: The UAE_CONTROL program ! 441: ======================= ! 442: ! 443: In the "amiga" subdirectory, you will find two programs, uae_control and ! 444: uaectrl that provide the same functionality as the X11 GUI. uaectrl is ! 445: shell-based and works with any Kickstart, while uae_control needs the ! 446: gadtools.library and a recent version of reqtools.library, so it only works ! 447: with Kick 2.0 and upwards. Copy these two programs to the directory that you ! 448: use for harddisk emulation. They should be self-explanatory. ! 449: ! 450: ! 451: Printing ! 452: ======== ! 453: ! 454: With the "-p cmd" option, you can specify a command that will be run when the ! 455: emulator detects that the Amiga accesses the parallel port. Usually, you will ! 456: want to say "-p lpr" to pass the output over to lpd. It's unclear how this ! 457: will work on non-Unix systems, DOS users can try "-p LPT1:" or something like ! 458: this. ! 459: For best results, select the PostScript driver in the Amiga Preferences. This ! 460: is only available in newer Kickstarts. Printing is not going to work with ! 461: another printer driver. ! 462: None of this is guaranteed to work yet, and I have not tried any of this yet. ! 463: ! 464: ! 465: Quick overview of the debugger commands ! 466: ======================================= ! 467: ! 468: If you use the X11 version, you can press ^C at any time to enter the built-in ! 469: MC68000 debugger. ! 470: Each debugger command consists of a single letter and occasionally some ! 471: parameters. ! 472: ! 473: g: Start execution at the current address. ! 474: c: Dump state of the CIA and custom chips. ! 475: r: Dump state of the CPU ! 476: m <address> <lines>: Memory dump starting at <address> ! 477: d <address> <lines>: Disassembly starting at <address> ! 478: t: Step one instruction ! 479: z: Step through one instruction - useful for JSR, DBRA etc. ! 480: f <address>: Step forward until PC == <address> ! 481: q: Quit the emulator. You don't want to use this command. ! 482: ! 483: (^C has no effect if UAE is compiled for SVGAlib - use F12 to exit) ! 484: ! 485: ! 486: Input devices ! 487: ============= ! 488: ! 489: Mouse, keyboard and joystick can be used in a straightforward way. A couple of ! 490: keyboard languages are supported with the "-l" commandline option. If you have ! 491: a different keyboard, patches to make UAE work with it are appreciated. ! 492: The X version of the emulator will try to keep the Amiga mouse pointer at the ! 493: same location as the X mouse pointer. You can turn off this mode if it does ! 494: not work with your program by pressing F12. This is needed (for example) for ! 495: Lemmings and the Magnetic Scrolls adventures, which don't use sprite 0 as a ! 496: mouse pointer. Other versions (SVGAlib, DOS, possibly others) do not have this ! 497: problem. ! 498: If you use Linux and have the joystick driver kernel module, "configure" ! 499: should automatically enable support for it. UAE calibrates the joystick ! 500: automatically. Turn it a few times on startup to get the calibration done. ! 501: ! 502: ! 503: Sound ! 504: ===== ! 505: ! 506: If you define LINUX_SOUND in config.h, the emulator will use /dev/dsp to ! 507: output sound. You can pass parameters like frequency or number of bits to use ! 508: on the commandline; if you don't specify any, sane defaults will be used. If ! 509: graphics output is enabled while sound is output, the emulator will be much ! 510: too slow on most systems. The sound will not be continuous. Therefore, a hack ! 511: to turn off screen updates is provided: Press ScrollLock to disable graphics, ! 512: press it again to enable them (note: for X, you'll have to press it twice each ! 513: time). ! 514: The LINUX_SOUND_SLOW_MACHINE option will steal cycles from the CPU emulator. ! 515: The relative CPU speed will be reduced somewhat if this option is set. This may ! 516: lead to incompatibilities. ! 517: ! 518: The quality of the emulation depends on the setting of the "-S" commandline ! 519: option. With "-S 3", all of the sound hardware is emulated; and some programs ! 520: (e.g. AIBB) won't run with other settings. "-S 2" should sound just as good as ! 521: "-S 3" and will be much faster for some programs. "-S 1" tries to emulate most ! 522: of the sound hardware, but doesn't actually output sound. "-S 0" completely ! 523: turns off sound. ! 524: ! 525: On other Unix systems, the AF sound system may be available. You can configure ! 526: UAE to use this, too, by changing some paths in the Makefile (I can't answer ! 527: any questions about this, I never saw/used it). ! 528: ! 529: ! 530: Speed ! 531: ===== ! 532: ! 533: The Most Frequently Asked Question is: "Just how fast is it?", and this is ! 534: also the most difficult one to answer. The easy way to answer is "It depends", ! 535: but I'll try to do better. All timings I give here were measured on my ! 536: machine, a P90 (using SVGAlib, with all the x86 assembly options turned on). ! 537: The MC68000 emulation is more than twice as fast as a real A500. I measured ! 538: this by letting PowerPacker try to compress itself (it already was compressed). ! 539: It took UAE about 6 minutes, my A500 took about 15. If you set the frame rate ! 540: to a high value (i.e. leaving out many frames), the graphics speed does not ! 541: matter and you get about twice the speed of an A500. If you enable the smart ! 542: update method in config.h, and if it works for your program (it works for ! 543: almost all programs using the Workbench) you also get about the same speed at ! 544: full frame rate. ! 545: For games and demos, the CPU speed does not matter, but the average frame time ! 546: is important. UAE can calculate this automatically. The SVGAlib version gives ! 547: the number when you exit the emulator, to obtain the value with the X version ! 548: you need to interrupt it and type "c" in the debugger. A real A500 has a ! 549: constant frame time of 20ms (50 Hz). ! 550: If you have a game/demo that has lots of blitter activity, many copper/sprite ! 551: effects, dual playfields and scrolling, no one can help you. Fortunately, this ! 552: case is extremely rare. Normal games that have a number of blitter objects, ! 553: scrolling and maybe some sprites run at 1/3-1/4 the speed of an A500 in the ! 554: worst case, some run at 1/2 the speed. Lowering the frame rate helps ! 555: enormously here, and at 1/5 frame rate, about everything runs somewhere ! 556: between 50% and 100% the speed of an A500. ! 557: This still isn't the full story (I bet you start to see why the question is ! 558: hard to answer). A real A500 without fast memory gets slowed down to about ! 559: half its speed in Hires 16 color mode. More bitplanes also slow UAE down, but ! 560: not quite as much, so it can be several times faster than an A500 in that ! 561: mode. ! 562: ! 563: ! 564: Bugs / Unimplemented features ! 565: ============================= ! 566: ! 567: The sprite emulation is incomplete and buggy. Sprite collisions are not ! 568: implemented yet. The serial port emulation doesn't seem to be useful yet. ! 569: Apart from that, UAE can do everything a real A500 can do (and more), but ! 570: there may still be one or two buglets that make some programs fail. ! 571: ! 572: ! 573: Thanks & Acknowledgements ! 574: ========================= ! 575: ! 576: Thanks to all who have written me so far with bugreports and success/failure ! 577: reports when trying to run the emulator on various hardware with different ! 578: Kickstart versions. A list of everyone who has contributed to the source code ! 579: can be found in the CREDITS file (this was getting too big to keep it here). ! 580: ! 581: Special thanks to: ! 582: - Jay Miner, Dale Luck, R.J. Mical and all the others who built the Amiga. ! 583: - Felix Bardos, whose HRM I "borrowed". ! 584: - Hetz Ben Hamo mailed Peter Kittel from Commodore asking for permission to ! 585: give Kick 1.3 away. Unfortunately, the response was negative :-( ! 586: - Bruno Coste, Ed Hanway, Alessandro Soldo and Marko Nippula provided ! 587: documentation ! 588: - Fabio Ciucci gets the "Best bug reports" award for his help with the ! 589: blitter line emulation and other problem areas. ! 590: ! 591: ! 592: Ports ! 593: ===== ! 594: ! 595: Apart from the "main" Unix version, several ports of UAE are ready/being ! 596: developed. ! 597: ! 598: Gustavo Goedert <[email protected]> has ported UAE to DOS using the ! 599: DJGPP port of GCC. The binary is available on several ftp sites as well as on ! 600: my Web site. ! 601: ! 602: Ernesto Corvi <[email protected]> has ported UAE to the Apple ! 603: Macintosh. He tells me it is available on Info-Mac, and that every Mac user ! 604: should know where that is. A link to the archive containing both PPC and 68k ! 605: binaries is on my Web page. (info-mac is mirrored by ! 606: sunsite.informatik.rwth-aachen.de) ! 607: ! 608: Christian Bauer <[email protected]> has ported UAE to the ! 609: BeBox. ! 610: ! 611: Ian Stephenson <[email protected]> has ported UAE to NextStep. ! 612: ! 613: Olaf 'Olsen' Barthel <[email protected]> has ported UAE to the Amiga. This ! 614: port requires the AA chipset as well as Kickstart 3.0 or higher. CyberGraphX ! 615: is supported. Please read the file "amiga.c" for information. To compile it, ! 616: you need SAS/C and the 3.0 includes (they probably come with the compiler). ! 617: ! 618: Krister Bergman <[email protected]> has ported UAE to the XFree86/OS2 ! 619: environment. This port can be obtained from Krister's WWW page: ! 620: <http://www.kuai.se/~bellman/html/xfreeapps.html> ! 621: ! 622: Since I generally don't have the possibility to test or improve these ports, ! 623: it is a good idea to contact their respective authors if you have questions. ! 624: ! 625: ! 626: Pointers ! 627: ======== ! 628: ! 629: There are a few sites in the Internet that contain helpful information about ! 630: UAE. ! 631: ! 632: I have set up a WEB page for UAE. You will find interim versions, Linux ! 633: binaries, diskfiles with Amiga software and other interesting stuff there. ! 634: The address is ! 635: ! 636: http://www-users.informatik.rwth-aachen.de/~crux/uae.html ! 637: ! 638: There, you will find links to other UAE pages. I'll add these links to this ! 639: document in the next version, but I don't have them here right now. ! 640: ! 641: I post announcements of new versions of UAE to the newsgroup ! 642: comp.emulators.misc. From time to time, I also upload new versions to the ftp ! 643: server sunsite.unc.edu. You will find them either in pub/Linux/Incoming or in ! 644: pub/Linux/system/Emulators. There are many sunsite mirrors throughout the ! 645: world, you should be able to find one near you. ! 646: ! 647: ! 648: The author's address ! 649: ==================== ! 650: ! 651: Before you contact me with a problem that you have, make sure you have read ! 652: _all_ of the above. Please read also the file "FAQ", which conains a lot of ! 653: helpful information. In the future, I will probably no longer respond to ! 654: questions that are already answered by any of these files. ! 655: ! 656: [email protected] ! 657: ! 658: or, via snailmail ! 659: ! 660: Bernd Schmidt ! 661: Schlossweiherstrasse 14 ! 662: 52072 Aachen ! 663: Germany ! 664: ! 665: Email is more likely to be answered, and will definitely be answered much ! 666: faster. Please avoid phonecalls if you can. ! 667: I can't answer _every_ question. If you have trouble understanding this ! 668: README, either because you don't speak English very well or because you have ! 669: no clue at all about computers, please try to find someone near you who does ! 670: understand this file and who can translate/explain it for you. I simply can't ! 671: explain (for example) how to use terminal programs or CrossDOS because I don't ! 672: use either, and it would be much too time-consuming anyway. This file and the ! 673: file FAQ contains about every piece of information I can give you. I try to ! 674: help people who have questions, but sometimes it takes too much time. ! 675: ! 676: Please don't ask for Kickstart ROM files. ! 677: ! 678: Oh, and another thing: If I promise to do things (like implement new ! 679: features), and forget about them, pester me. That happens occasionally, it's ! 680: a known bug in my brain. I'll have it replaced.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.