![[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.1.29! root 1: This is version 0.8.29 of UAE-core, the UAE Amiga Emulator. 1.1.1.5 root 2: 1.1.1.25 root 3: This package used to be the master copy of UAE; it has somewhat lagged in 1.1.1.26 root 4: development since. It is now intended to be a stable emulator core with a 5: focus on running old A500 games and demos. Certain extra features, such as 6: a JIT compiler, will not be added - other packages such as WinUAE or E-UAE 7: are available which include these patches. 1.1.1.5 root 8: 1.1 root 9: 1.1.1.3 root 10: License 11: ======= 1.1 root 12: 1.1.1.5 root 13: UAE is available under the terms of the GNU General Public License. This means 14: that it is free software: you are welcome to distribute copies of it and/or 15: modify it, under certain conditions. It also means that there is no warranty 16: for UAE. 17: See the file COPYING that is included in the top level directory of this 18: archive for details. 1.1 root 19: 20: 21: Overview 22: ======== 23: 1.1.1.2 root 24: An emulator is a program which enables you to run software for a machine 25: which has non-native hardware and a non-native operating system, on your 26: computer. UAE allows you to run most of the available Amiga software. It is a 27: software emulation, meaning that no extra or special hardware is needed to do 28: this. The hardware of an Amiga is emulated accurately, so that Amiga software 29: is tricked into thinking it is running on the real thing, with your computer's 30: display, keyboard, harddisk and mouse taking the parts of their emulated 31: counterparts. 1.1 root 32: 33: UAE was developed for Unixoid systems. Meanwhile, it has been ported to the 1.1.1.18 root 34: Mac, DOS, Windows, the BeBox, NextStep, the XFree86/OS2 environment and the 35: Amigas (it can run itself by now). You should have received several other 36: files along with this document with details on how to install and use the 37: version for your operating system. 1.1 root 38: 39: This section is just what it says: an overview. Please read _all_ of this 1.1.1.2 root 40: file, especially if you have problems. UAE has many, many features and 41: equally many configuration options. If you don't know about them, it's likely 42: that UAE doesn't work for you, or doesn't work as good as it could. 43: 44: Please read also the file "FAQ" which contains some Frequently Asked 1.1.1.3 root 45: Questions (and even the answers!) You should also look for a document 46: describing the specific port of UAE to the operating system you are using, 47: for example "BeOS/README" or "DOS/README". 1.1.1.2 root 48: 49: People have complained that the UAE documentation contains only "weird jargon". 50: Sorry about this. Despite what MessySoft and Tomato tell you, computer 51: programs aren't always easy to use. UAE does require some assistance from you, 52: and therefore you should at least understand a bit about computers. After all, 53: you are an Amiga fan, so you should know what a Workbench is, don't you think? 1.1 root 54: 55: 1.1.1.2 root 56: Features 57: ======== 58: 59: This version of UAE emulates: 1.1 root 60: 1.1.1.5 root 61: - A 68000, 68010 or 68020 CPU, optionally a 68881 FPU 1.1.1.2 root 62: - OCS Graphics Chipset, plus big blits from the ECS Chipset 1.1.1.5 root 63: - Up to 2MB Chip RAM and up to 8MB Fast RAM, or 8MB Chip RAM without Fast RAM 64: - Up to 64MB Zorro III Fast RAM, independent of Chip RAM setting (68020 only) 1.1.1.3 root 65: - Up to 1MB Slow RAM, for extended compatibility with problem software 66: - Up to 8MB of graphics card memory, usable by software that supports 1.1.1.5 root 67: Picasso 96 compatible graphics cards 68: - 4 x 3.5" floppy disk drives (DF0:, DF1:, DF2: and DF3:). It's not possible to 69: read Amiga disks, so these are emulated with disk files. 70: - A hard-disk: either a harddisk image file or part of the native filesystem 1.1.1.2 root 71: - Joystick support (with option of mapping joystick to numeric keypad) 72: - Mouse support 73: - Ability to run in various screen modes (for better display quality or 74: better speed) 1.1.1.5 root 75: - Full stereo sound support, consisting of 4 x 8bit channels 1.1.1.3 root 76: - Beta parallel and serial port support 1.1.1.2 root 77: - some other things which don't work well enough to mention them here... 78: 79: 80: Requirements (IMPORTANT! READ THIS!)/Limitations 81: ================================================ 82: 83: Not emulated: 1.1.1.3 root 84: - Sprite to playfield collisions (sprite to sprite collisions work) 85: - An MMU (part of 68030/040 CPUs except those that Commodore used). This means 1.1.1.2 root 86: you can't use virtual memory systems or real operating systems like Linux 87: or BSD. 1.1.1.11 root 88: - Serial port emulation exists but doesn't work too well. 1.1.1.2 root 89: 90: Since the PC floppy controller can't read Amiga disks (yes, that's a fact), 91: floppy access has to be emulated differently: Floppies are emulated by means 92: of disk files that contain a raw image of the floppy disk you want to emulate. 93: A disk file is an image of the raw data on an Amiga floppy disk, it contains 94: 901120 bytes (880K), which is the standard capacity of an Amiga disk. 95: 96: To actually run the program, you'll need to install the ROM image from your 97: Amiga. You can't run UAE if you don't have this image. It is not included 98: because it is copyrighted software. Don't ask me to send you one. I won't. 99: If you don't have an Amiga and still want to use UAE, you'll have to buy an 100: Amiga or at least the system software (ROM + Workbench) first. 101: The Kickstart image can have a size of either 256K or 512K. It must be named 102: "kick.rom" by default. 103: 104: Read the section "tools" below for information how to create ROM images and 105: disk files. 1.1 root 106: 107: If you don't have a Kickstart file, you may still be able to boot some games 108: and demos. The emulator includes some primitive bootstrap code that will try 109: to read and execute the bootblock of the diskfile you are using, and if that 110: bootblock only uses the one or two Kickstart functions that are supported by 111: the "replacement Kickstart", your program will boot. Don't expect too much, 112: though. 113: 1.1.1.2 root 114: You'll also need some other software to run - why else would you want to 115: emulate an Amiga? There are several ways to make the software accessible to 1.1.1.3 root 116: UAE, either with disk image files or with a harddisk emulation. You should 117: make an image of your Amiga's Workbench disk and install it as "df0.adf" 118: (adf = Amiga Disk File) when you use UAE for the first time. More about how 119: to create these files in the chapter "Transferring software" 120: 121: To use Picasso96 emulation, you need the Picasso96 libraries, which are also 122: not included. They can be obtained (e.g.) from Aminet. 1.1 root 123: 124: 125: Invoking UAE 126: ============ 127: 1.1.1.2 root 128: First, read the system-specific documents for information how to set up UAE. 129: You should have an executable program called "uae". You can simply execute it, 1.1.1.7 root 130: but you can also optionally give it one or more of the following parameters: 131: 132: -h : Print out a help text. 133: -f file : Load a configuration file 134: -s opt=val : Set the emulator's option "opt" to value "val". 135: 136: Configuration files consist of several lines of the form "opt=val", just as 137: with the "-s" parameter. You can use the following options with the "-s" 138: option, or in a config file. 139: [Here, "=n" means the option takes a number as value. "=bool" means the option 140: takes a value of either "yes" or "no" (or "true", "false", or abbreviations of 141: any of these). There are other classes as well.] 1.1 root 142: 143: General options: 1.1.1.7 root 144: accuracy=n [default=2] 145: Set emulator accuracy to n. The default is n = 2, which means the 146: emulator will try to be as accurate as possible. This no longer 147: does much in this version, and I'll probably remove it. 148: framerate=n [default=1] 149: Sets the frame rate to 1/n. Only every nth screen will be drawn. Using a 150: higher value can speed up the emulator, at the expense of graphics quality. 151: autoconfig=bool [default=yes] 152: If this is enabled, all expansion devices provided by the emulation will be 153: automounted. You should only disable this if you have a Kickstart ROM 154: earlier than 1.3 which can't cope with this. Some badly written games and 155: demos might also be incompatible with this. 156: kbd_lang=lang [default=us] 157: Set the keyboard language. Currently, the following values can be used: "us" 158: for U.S. keyboard (default), "se" for swedish, "fr" for french, "it" for 1.1.1.17 root 159: italian, "es" for spanish, "dk" for danish, or "de" for german keyboard. 1.1.1.7 root 160: This setting only affects the X11 version. 161: floppy0=file [default=df0.adf] 162: Try to use the specified file as diskfile for drive 0 instead of df0.adf. 163: The options floppy1, floppy2, and floppy3 also exist. 164: kickstart_rom_file=file [default=kick.rom] 165: Use the specified file instead of kick.rom as Kickstart image. 1.1.1.21 root 166: You can also use an 8k sized A1000 boot ROM. The emulator will detect it 167: by its small size and behave like an A1000. 1.1.1.17 root 168: kickstart_key_file=file [default=none] 169: For some strange licensing reasons, Cloanto had to encrypt the ROM images 170: they ship with the Amiga Forever package. This option lets you select the 171: key file; this is only necessary if you are using one of the ROMs from 172: Amiga Forever. 1.1.1.7 root 173: joyport0=mode [default=mouse] 174: Specify how to emulate joystick port 0. You can use "mouse", "joy0", or 175: "joy1" to use the corresponding input devices of your machine, or you can 1.1.1.14 root 176: select several different keyboard replacements for a joystick: 177: "kbd1" for the numeric pad. '0' is the fire button. Three keys on the 178: numeric pad act as autofire toggle: '.' (or ',' depending on your 179: keyboard language), Enter and the division key. 180: "kbd2" for the cursor keys with right control key as fire button and the 181: right shift key as autofire toggle 182: "kbd3" for T/F/H/B with the left Alt key as fire button and the left Shift 183: key as autofire toggle. 184: The autofire toggle keys will turn on autofire (25 shots per second), it 185: will stay enabled until you hit the autofire toggle again. 1.1.1.7 root 186: joyport1=mode [default=joy0] 187: Like joyport0, but for the Amiga's joystick port 1. 1.1.1.18 root 188: use_gui=state [default=yes] 189: If enabled, show a user-interface that enables changing these options at 190: run-time. Possible settings are "no", "yes" and "nowait". If "nowait" is 191: used, the GUI will be shown at program startup, but the emulator will also 192: start immediately without waiting for the user to change any of the 193: settings. 1.1.1.7 root 194: immediate_blits=bool [default=no] 195: If enabled, all blits will finish immediately, which can be nice for speed, 196: but may cause incompatibilities. 1.1.1.16 root 197: collision_level=level [default=sprites] 1.1.1.17 root 198: This can have a value of "none", "sprites", "playfields", or "full". If 199: set to "sprites", the emulator will only compute collisions between sprites. 200: If set to "playfields", it will additionally compute collisions between 201: sprites and the background. This is much slower and used only rarely. When 202: "full" level is selected, collisions of the background with itself are also 203: computed. This is also used very rarely, and makes the emulator even slower. 204: Using "sprites" or "none" will almost always be enough. 1.1.1.7 root 205: cpu_speed=speed [default=4] 206: This can have a value of "real", "max", or an integer between 1 and 20. 207: "real" will try to give the CPU emulation exactly as many cycles, relative 208: to the other chips, as on a real A500. "max" will try to give you the 209: maximum CPU emulation speed achievable on your machine. Numeric values 210: specify a fixed relation between CPU and custom chip emulation, where lower 211: values prioritize CPU emulation, while higher values prioritize custom chip 212: emulation. 1.1.1.16 root 213: finegrain_cpu_speed=speed 214: Like cpu_speed, but only accepts numeric values. These numeric values are 215: equivalent to the ones given to cpu_speed multiplied by 512. This means 216: that "cpu_speed=2" and "finegrain_cpu_speed=1024" have the same effect. 217: Using this option you can give the CPU emulation a much higher priority by 218: using small values. 1.1.1.7 root 219: cpu_type=type [default=68000] 220: Controls which CPU is emulated. This can be "68000", "68010", "68020" or 221: "68020/68881". In some cases, you may need to use "68ec020" or 222: "68ec020/68881" to emulate a crippled variant of the 68020 that has only a 223: 24 bit address bus. Some software, including some Kickstart versions, does 224: not work with a normal 68020 that has a 32 bit address bus. 225: Careful: using an "ec" variant has harmful side effects, and should be 226: disabled unless absolutely needed (you lose Z3 memory and Picasso 227: emulation). 228: cpu_compatible=bool [default=no] 229: If enabled, a slower but slightly more accurate variant of the CPU emulation 230: will be used. This is needed for some types of copy protection, among other 231: things. This is only meaningful for a CPU type of "68000". 1.1.1.14 root 232: nr_floppies=n [default=4] 233: The emulator will emulate this many external floppy drives. Some very old 234: games apparently have problems if this is larger than 1, but for all normal 235: programs the default is good enough. 1.1 root 236: 1.1.1.3 root 237: Emulating external devices (harddisk, CD-ROM, printer, serial port): 1.1.1.7 root 238: filesystem=access,volume:path [default=no filesystems mounted] 239: Mount the host's file system at "path" as an Amiga filesystem with volume 240: name "VOLUME:". "access" can be either "ro" (for readonly), or "rw" (for 241: read-write). If you want to mount a CD-ROM, you should use a readonly 242: mount. You can mount multiple file systems. 243: See below. 244: hardfile=access,secs,heads,reserved,bsize,file [default=no hardfiles mounted] 245: Mount the hardfile "file" as an emulated harddisk, using a geometry of 246: "secs" sectors per track, "heads" surfaces and "nr" reserved blocks. 247: Each sector should have "bsize" bytes. This can be abused to mount 248: floppy images. You can mount multiple hardfiles. 249: See below. 1.1 root 250: 251: Sound options: 1.1.1.7 root 252: sound_output=type [default=none] 253: The type of sound output can be "none" (no sound at all), "interrupts" 254: (emulated for the internal side effects that can be noticed by programs, 255: but no sound output), "normal" (emulated, and sound output), "exact" (a 256: slightly more accurate emulation that may be necessary in some cases, but 257: can also be slower). 258: sound_channels=type [default=mono] 1.1.1.16 root 259: Can be "mono", "stereo", or "mixed". If set to "stereo", the left and right 260: channels produce the same output as on a real Amiga - two of the four audio 261: channels are audible on the left, and the other two on the right. This is 262: exactly what you want, except if you're using headphones - having the sound 263: split so strictly can lead to a strange listening experience at times. This 264: is what "mixed" is trying to solve: it mixes the left channel with a low 265: volume into the right channel and vice versa. (This mixing operation loses 266: a bit of precision in the output). 1.1.1.7 root 267: sound_bits=n [default varies across UAE versions on different OS types] 268: Common values are 8 (low quality) or 16 (high quality) 269: sound_frequency=n [default varies across UAE versions on different OS types] 270: Common values are 22050 or 44100. The quality of sound output increases with 271: the frequency. 272: sound_min_buff=n 273: sound_max_buff=n [default varies across UAE versions on different OS types] 274: You can specify the minimum and maximum size of the sound buffer. 275: Smaller buffers reduce latency. Usually only the minimum size is used. 1.1.1.10 root 276: sound_interpol=type [default none] 277: Normally, sound samples are output exactly as they are computed, without 278: any post-processing. This can generate errors in the sound output when the 279: output frequency isn't an even multiple of the input frequency. These 280: errors are usuable perceived as a high-frequency noise. 281: There are currently two types of interpolation available, both under 282: experimentation. You can use either "rh" or "crux" as value for this 283: option. Note that no interpolation is supported for 8 bit output; you need 284: to use 16 bit output to hear a difference. If you have any comments about 285: the effects of either method on audio quality, I'd be very interested to 286: hear them. 1.1.1.3 root 287: 1.1 root 288: Memory options: 1.1.1.7 root 289: bogomem_size=n [default=0] 290: Emulate n*256K slow memory at 0xC00000. Some demos/games need this. 291: fastmem_size=n [default=0] 292: Emulate n megabytes of fast memory as an expansion board. 293: z3mem_size=n [default=0] 294: Emulate n megabytes of Zorro III fast memory as an expansion board. 295: chipmem_size=n [default=4] 296: Emulate n*512K chip memory. Some very broken programs need specific amounts 297: of chip mem to work properly. The largest valid value is 16, which means 8MB 298: chip memory. 299: 300: Display options: 301: gfx_width=n [default=800] 302: Use a window that is n pixels wide for displaying the Amiga screen. 303: gfx_height=n [default=300] 304: Use a window that is n pixels high for displaying the Amiga screen. 305: gfx_lores=bool [default=no] 306: Enable this option if you use a very small window width (320 to 400 pixels) 307: to shrink the display horizontally. 1.1.1.18 root 308: gfx_linemode=type [default=scanlines] 1.1.1.7 root 309: The type can be none (every line is drawn once), "double" (every line is 310: drawn twice), and "scanlines" (every line is drawn once, but the image is 311: stretched vertically by inserting a black line every other line to simulate 312: the display on an old monitor). 313: The "double" mode gives best results, but slows down the emulation quite a 314: lot. Don't use the "none" mode if you want a decent interlace emulation. 315: If you use "double" or "scanlines", your window needs to be twice as high 316: as when using the "none" mode. 317: gfx_correct_aspect=bool [default=none] 318: Try to fit the image into the specified window dimensions by leaving out 319: certain lines. Useful if you want to fit a 640x512 Amiga display in a 320: 640x480 window. 321: gfx_center_vertical=bool [default=no] 322: gfx_center_horizontal=bool [default=no] 323: If you use a smaller window than 800x300 (400x300 with "gfx_lores" option or 324: 800x600 with a gfx_linemode other than "none"), not all parts of the display 325: will fit on the screen. By enabling the necessary centering options, you can 326: ask the emulator to try and move the screen contents so that the relevant 327: parts are displayed. If you are unlucky, this can cause the contents to jump 328: around a bit in certain cases. 329: gfx_fullscreen_amiga=bool [default=no] 330: Enable if you want to use the full screen, not a window on the desktop, for 331: the Amiga display. Some ports (DOS, SVGAlib) always use fullscreen mode. 332: gfx_fullscreen_picasso=bool [default=no] 333: Like gfx_fullscreen_amiga, but for the Picasso graphics card display. 334: gfx_color_mode=mode [default=8bit] 335: Select a color mode to use. 336: Color modes: 8bit (256 colors), 15bit (32768 colors), 16bit (65536 colors), 337: 8bit_dithered (256 colors, with dithering to improve quality), 338: 4bit_dithered (16 colors, dithered); 32bit (16 million colors) 1.1.1.10 root 339: gfxcard_size=n [default=0] 1.1.1.7 root 340: Emulate a Picasso 96 compatible graphics card with n MB graphics memory. 341: This requires that you use set the CPU type to "68020" or higher, and that 342: you do not use 24 bit addressing. 1.1.1.3 root 343: 344: Debugging options (not interesting for most users): 1.1.1.7 root 345: use_debugger=bool [default=no] 346: If enabled, don't start the emulator at once, use the built-in debugger. 347: log_illegal_mem [default=no] 348: If enabled, print illegal memory accesses 1.1 root 349: 1.1.1.2 root 350: 351: Whew. You'll probably have to experiment a little to get a feeling for it. 1.1.1.3 root 352: 1.1.1.2 root 353: 1.1 root 354: You can also put these options into a configuration file in your home 355: directory. Simply create ~/.uaerc and put some of these options in it. On 356: non-Unix systems, the file is called uae.rc and should be located in the 357: current directory. 358: 359: 360: Choosing color and screen modes 361: =============================== 362: 363: As described in the previous paragraph, UAE can run in many different 364: resolutions and color modes. However, few of the color mode options are 365: available if you use the X11 version of UAE, since the X server determines 366: how many colors are available. If you are running a 256 color X server, you 367: can use "-H3" to tell UAE to dither the colors for better results. 368: 369: You will have to experiment which mode gives the best results for you at a 370: satisfying speed. Note that the dithering process consumes time, so even if 371: 256 colors with dithering look better than 256 colors without, remember that 372: UAE will be slower in that mode. 373: 374: The recommended resolution is 800x600. In the lower resolution modes, some 375: overscan pictures the Amiga tries to display may not fit entirely on the 376: screen, others may be off-center and some graphical effects may look weird. 377: For best results, use 800x600 with at least 32768 colors. 1.1.1.3 root 378: For speed, use 400x300 lores with 256 colors. 379: 380: _Don't_ use 24 bit or 32 bit screen modes, unless you absolutely have to. 381: These are way too slow to be usable. 1.1 root 382: 383: 384: Harddisk emulation 385: ================== 386: 1.1.1.3 root 387: Since using diskfiles is awkward, it is necessary to emulate harddisks. There 388: are two ways how you can use large amounts of data with UAE: harddisk files 389: and mounted directories. 390: 391: 1. Harddisk files 392: 393: Harddisk files are large files that contain the image of an Amiga filesystem. 394: They work much the same way as a disk file. You can simply create a large 395: empty file and tell UAE to use it as a hardfile, but you will need to format 396: it from the emulation before you can actually use it. 1.1 root 397: 1.1.1.3 root 398: Under Unix, You can create a (unformatted) harddisk file with 1.1 root 399: dd if=/dev/zero of=hardfile bs=512 count=16384 1.1.1.3 root 400: That will create an 8MB file. Other ports of UAE may come with a utility 401: called "makedisk" or other ways to create such a file. 1.1.1.2 root 402: 1.1.1.3 root 403: To tell the emulator that you want to use a certain file as a hardfile, use 404: the "-W" option, for example 405: uae -W 32:1:2:hardfile 406: The first three numbers are geometry information which tell the AmigaOS how 407: the file is organized. The first number (32) is the number of sectors per 408: track, the second number (1) is the number of heads or surfaces, the third 409: number (2) is the number of reserved blocks. If you use "normal" sizes 410: (powers of two, like 32MB), then you should be OK using the same numbers as 411: in the above example. Using different numbers can make sense if you transfer 412: the image of a real Amiga harddisk which uses a different geometry. The last 413: field of the argument to the "-W" option is the name of the harddisk file. 414: 415: If you are using Kickstart 1.3 or earlier, hardfiles can't currently be 416: mounted at boot time, and therefore you can't boot from it either. You will 417: have to boot either from a floppy disk image or from a filesystem (see below), 418: and mount the hardfile.device later. To do this, add the following to 419: "DEVS:mountlist": 1.1 root 420: 1.1.1.3 root 421: UAE0: Device = uaehf.device 1.1 root 422: Unit = 0 423: Flags = 0 424: Surfaces = 1 425: BlocksPerTrack = 32 426: Reserved = 1 427: Interleave = 0 428: LowCyl = 0 ; HighCyl = 511 429: Buffers = 5 430: DosType = 0x444F5300 431: BufMemType = 1 432: # 433: 1.1.1.3 root 434: (You may need to adjust the values if you specified a different geometry, 435: and/or your hardfile has a different size than 8MB, and/or the hardfile is not 436: mounted as UAE0: because you mounted other harddisks before it.) 437: 1.1 root 438: Then, type "mount UAE0:" (or put that command in your startup-sequence), and 439: you should be able to access it. Don't forget to format it with the AmigaDOS 440: format command: 441: 442: format drive uae0: name Mister_Willwink 443: 1.1.1.3 root 444: b) Accessing native filesystems from the emulator 1.1 root 445: 446: This has some major advantages: 447: - It has no problems with Kickstart 1.3 448: - It is more convenient. 1.1.1.3 root 449: - It is much faster. 1.1 root 450: 1.1.1.2 root 451: If you specify the -M or -m command line arguments, you your native filesystem 452: from the emulator. If you start UAE with 1.1 root 453: 454: uae -m sound:/usr/amiga/modules 1.1.1.2 root 455: 1.1 root 456: you can access all the files in /usr/amiga/modules by reading from the 457: AmigaDOS volume "SOUND:". 458: (DOS users: try "uae -m dh0:C:\" to mount your drive C:\ as DH0:) 459: 1.1.1.3 root 460: You can mount up to 20 devices, either hardfiles or filesystems, by giving 461: either of these options multiple times. The volumes will be named UAE0:, 462: UAE1:, etc. UAE will boot from UAE0: if no diskfile is found for floppy 463: drive 0. 464: You can also use native filesystems to mount Amiga CD-ROMs, and you can 465: abuse the hardfile emulation to mount floppy disks: "uae -W 11:2:2:wb13.adf" 466: will mount the diskfile "wb13.adf". 1.1 root 467: 468: 469: Tools / Transferring files 470: ========================== 471: 1.1.1.2 root 472: As you should know by now, you need to transfer files between your Amiga and 473: the machine you run UAE on. There are several ways how to do this. 474: 475: - Using a null modem cable, and a terminal package running on each machine, 476: you can transfer the file(s) via Zmodem upload/download. 68000 equipped 477: Amigas can normally attain around 3000cps through the null modem cable, 478: using the standard Commodore serial.device. However, by using the device 479: replacement BaudBandit.device, anything up to 5500cps can be attained. 480: BaudBandit can be obtained from Aminet. A second alternative is to use 481: the BASIC program adfi.bas (included with UAE) to transfer a file from the 482: Amiga to the PC via the null modem cable. 483: 484: - If you're using CrossDOS on your Amiga, you can compress the disk or 485: kickstart image using LhA or similar PC compatible archiver and copy it to 486: a 720KB floppy disk. You can now take the disk over to the PC, copy the 487: compressed file to the UAE directory and uncompress it. 488: If you don't have CrossDOS on the Amiga, there is a similar freeware tool 489: called Msh, which can be found on Aminet or on Fish disk 382 or 327. 490: 491: In either case, you ought to read the documentation for the programs that 492: you use for the transfer. These programs can't be explained here. 1.1 root 493: 1.1.1.2 root 494: In the "amiga" subdirectory you'll find two small Amiga programs that will 495: help you to generate the necessary image files. These are called transrom 1.1 root 496: and transdisk. Copy them to your Amiga and make them executable (by typing 1.1.1.2 root 497: "protect transrom rwed" and "protect transdisk rwed" in the Amiga shell 1.1 root 498: window). 499: transrom will dump the contents of your Kickstart ROM, and transdisk will 500: dump an image of a floppy in one of the drives. Both programs write to the 1.1.1.2 root 501: standard output (read: the screen), so you'll want to redirect that. Do 1.1 root 502: 503: transrom >ram:kick.rom 504: 505: to create a file called "kick.rom" in the RAM disk, and 506: 507: transdisk >ram:df0.adf 508: 509: to create a file called "df0.adf" in the RAM disk. These files are pretty 1.1.1.2 root 510: big, 262144 or 524288 bytes for the ROM image and 901120 bytes for a disk 511: image. 1.1.1.3 root 512: 513: NEVER run either of these programs from the Workbench. Always open a Shell 514: or CLI window to do this. 515: 1.1 root 516: transdisk understands the following arguments: 517: 518: -d device unit: Use this device instead of DF0: 1.1.1.2 root 519: -s n: Begin transfer at track n (default: 0) 520: -e n: End transfer at track n (default: 79) 521: -w file: don't read from the floppy, instead write the contents 522: of "file" to the floppy 523: -h: Treat the disk as high-density disk. HD images aren't 524: supported by UAE yet, though. Note that the resulting 525: file will be twice as big. 1.1 root 526: 527: So, to transfer the disk in drive DF1:, you'd give the command: 528: 529: transdisk >ram:df1.adf -d trackdisk 1 530: 531: If you don't have much RAM and can't fit all of a disk image in the RAM disk, 532: you can split up the transfer into multiple parts with the "-s" and "-e" 533: parameters. To transfer the disk in four parts, you'd use the following 534: commands: 1.1.1.16 root 535: 1.1 root 536: transdisk >ram:df0_1.adf -s 0 -e 19 537: transdisk >ram:df0_2.adf -s 20 -e 39 538: transdisk >ram:df0_3.adf -s 40 -e 59 539: transdisk >ram:df0_4.adf -s 60 -e 79 540: 541: Of course, you should save each of the four files to another place before 542: transferring the next one with transdisk to make space in your RAM disk. 543: If you have all the files on your PC, you can do the following under Unix: 544: cat df0_1.adf df0_2.adf df0_3.adf df0_4.adf >df0.adf 545: or, under DOS: 1.1.1.2 root 546: COPY /B df0_1.adf+df0_2.adf+df0_3.adf+df0_4.adf df0.adf 1.1 root 547: I've been told there are the following tools for the Mac to join binaries: 548: "ChunkJoiner 2.1.2" found under Info-Mac's <disk> directory or 549: "JoinFiles 1.0.1" under Info-Mac's <text>. 550: 551: The current transdisk can only read the standard AmigaDOS format. This means 552: that most games that rely on some form of copy-protection cannot be 1.1.1.2 root 553: transferred (more about disk formats in the file "FAQ") 1.1 root 554: 1.1.1.2 root 555: **************************************************************************** 1.1 root 556: If you transfer commercial software, you must not distribute the resulting 557: image files, since that would be a violation of copyright law. The Kickstart 558: ROM has to be considered commercial software. You may only use the Kickstart 559: from your own Amiga, and you may not distribute Kickstart ROM files. 560: Please read the license that came with your software for details. 1.1.1.2 root 561: **************************************************************************** 562: 563: 564: Retrieving files from a disk image 565: ================================== 1.1 root 566: 567: If you have a disk image file, and you want to retrieve the files from it, you 568: can use the "readdisk" tool. It is automatically built by "make". If you have 569: a disk image of a disk called "Workbench1.3D" as df0.adf, and you do 570: readdisk df0.adf 571: the whole directory structure of the disk image will be stored in a newly 572: created subdirectory called "Workbench1.3D". You can optionally give a second 573: parameter to specify a directory where to create the output other than the 574: current directory. 575: readdisk only understands about the OFS right now. FFS disks will cheerfully 576: be regarded as being unreadable. Use the unixfs.device from within the 1.1.1.2 root 577: emulator if you want to transfer files from FFS disks. 1.1 root 578: 579: 1.1.1.3 root 580: Picasso 96 graphics card emulation 581: ================================== 582: 583: To use this feature, you must select 68020 emulation with a 32 bit address 1.1.1.16 root 584: space (i.e. _not_ 68ec020). You also need a Kickstart 3.x ROM. 1.1.1.3 root 585: 586: To specify how much graphic memory you want to emulate, use the "-U" option, 587: e.g. "-U 4" for 4 megabytes. Then, you need the Picasso 96 software which 588: is not distributed with UAE (There will be a link to the Picasso 96 home page 589: on the UAE Web page soon). Version 1.31 or higher is recommended. 590: Install the Picasso software, and make sure you enable the "uaegfx" driver. 591: After that is complete, reboot, and you should be able to select the new 592: modes from the ScreenModes program. 593: 594: 1.1.1.22 root 595: AHI sound card emulation 596: ======================== 597: 598: In the "amiga" subdirectory of the UAE distribution, you will find a "Devs" 599: directory that contains the necessary files for AHI sound support. This is 600: at an early stage and will not work very well in this release. It is 601: included mainly in the hope that someone with a clue about AHI will pick up 602: this work and finish it properly. 603: 604: 1.1.1.17 root 605: Saving and restoring snapshots 606: ============================== 607: 608: From version 0.8.17 onwards, the emulator has the capability to save the 609: current state of the emulation into a "snapshot" file that can be restored 610: later on. This functionality is available through the GUI on some ports. 611: It is mainly useful for computer games that either have no save game 612: feature, or whose save game feature does not work on UAE (often, games try 613: to save in a non-standard disk format, this can be tricky to emulate). 614: 615: There are several restrictions that apply to the save state feature: 616: 617: - It is at the moment experimental. It is not guaranteed that the 618: emulator can correctly restore every snapshot. It is not guaranteed 619: that future versions of the emulator will be able to restore snapshots 620: saved by this version. 621: - The state of the harddisk emulation cannot be saved. This makes it 622: essentially useless for applications, but remember it's designed for 623: games. Be careful with games that have been installed to the harddisk. 624: - Neither ROM contents nor floppy disk contents are saved right now. 625: 626: 1.1.1.9 root 627: UAE SCSI device 628: =============== 629: 1.1.1.17 root 630: To enable SCSI support, use --enable-scsi-device when running configure. 1.1.1.9 root 631: The emulator provides a uaescsi.device. This device only supports 632: direct SCSI, which is sufficient to run applications like MakeCD. The 633: device does not support reading or writing with the normal Exec commands, 634: so you cannot mount filesystems on it right now. 635: 636: The unit numbers of the uaescsi.device follow the Amiga SCSI 637: conventions: unit number "xyz" maps to the lun y of target z on bus 638: x. Wide SCSI busses can have targets with numbers larger than 9. In 639: this case the uaescsi.device pretends that there is another SCSI 640: bus. To avoid confusion, all available SCSI targets are listed 641: together with their unit number when starting UAE. Devices cannot be 642: added while the emulator is running. Reseting it is not sufficient 643: either for technical reasons. 644: 645: The implementation of the uaescsi.device uses cdrecord's libscg as 1.1.1.13 root 646: interface to the native SCSI system. The Linux implementation of this 647: library used to be included into UAE, but now the library as generated 648: by the cdrecord source package (ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/) 649: is used. As the library is not distributed seperately, you will have 650: to get the whole cdrecord sources, compile it and then make several 651: header and lib files available to the compiler if (and only if) building 652: UAE with SCSI support. The script "src/install_libscg" copies the files 653: required for the libscg in cdrecord 1.8.1. 654: 655: Using threads is strongly recommended, because some SCSI commands can 656: run for extended periods of time and would block the whole emulation 657: during this time without threads. Use --enable-threads when starting 658: configure. 1.1.1.9 root 659: 660: Depending on the hosts capabilities the uaescsi.device may be limited 661: compared to other Amiga SCSI devices. The Linux kernel by default only 662: allows 32KB of data per SCSI command and does not always perform SCSI 663: requests in parallel. 664: 665: Setting the chunk size in MakeCD to 30KB is already too much and 666: causes an IO error -4 (IOERR_BADLENGTH), because the setting is only 667: used as a guideline. You can work around this by setting the Tooltypes 668: BUFFER_CHUNK_XXX to 29. On a Pentium II 350MHz with Adaptec UW SCSI 669: controller on board on-the-fly copying was possible from a Philips 670: CDD2600 (SCSI) to a Yamaha CRW4416E (IDE) at 4x. 671: 672: 1.1 root 673: The UAE_CONTROL program 674: ======================= 675: 676: In the "amiga" subdirectory, you will find two programs, uae_control and 677: uaectrl that provide the same functionality as the X11 GUI. uaectrl is 678: shell-based and works with any Kickstart, while uae_control needs the 679: gadtools.library and a recent version of reqtools.library, so it only works 680: with Kick 2.0 and upwards. Copy these two programs to the directory that you 681: use for harddisk emulation. They should be self-explanatory. 682: 683: 1.1.1.9 root 684: The timehack 685: ============ 686: 687: Another tool in the "amiga" subdirectory, timehack, synchronizes the 688: emulated Amiga's system time with the host's time every second. This 689: is useful when the emulation is not done in real-time or is suspended 690: completely. 691: 692: 1.1 root 693: Quick overview of the debugger commands 694: ======================================= 695: 1.1.1.2 root 696: Some (window-system based) ports of UAE have a built-in debugger. You can 697: press ^C at any time to enter this debugger. 1.1 root 698: Each debugger command consists of a single letter and occasionally some 699: parameters. 700: 1.1.1.23 root 701: g [<address>] Start execution at the current address or <address> 702: c Dump state of the CIA, disk drives and custom registers 703: r Dump state of the CPU 704: m <address> [<lines>] Memory dump starting at <address> 705: d <address> [<lines>] Disassembly starting at <address> 706: t [instructions] Step one or more instructions 707: z Step through one instruction - useful for JSR, DBRA etc 708: f Step forward until PC in RAM 709: f <address> Add/remove breakpoint 710: fi Step forward until PC points to RTS/RTD or RTE 711: fi <opcode> Step forward until PC points to <opcode> 712: fl List breakpoints 713: fd Remove all breakpoints 714: f <addr1> <addr2> Step forward until <addr1> <= PC <= <addr2> 715: e Dump contents of all custom registers 716: i Dump contents of interrupt and trap vectors 717: o <1|2|addr> [<lines>]View memory as Copper instructions 718: O Display bitplane offsets 719: O <plane> <offset> Offset a bitplane 720: H <count> Show PC history <count> instructions 721: M Search for *Tracker sound modules 722: C <value> Search for values like energy or lifes in games 723: W <address> <value> Write into Amiga memory 724: w <num> <address> <length> <R/W/RW> [<value>] 725: Add/remove memory watchpoints 726: wd Enable illegal access logger 727: S <file> <addr> <n> Save a block of Amiga memory 728: s <string>/<values> [<addr>] [<length>] 729: Search for string/bytes 730: T Show exec tasks and their PCs 731: h,? Show this help page 732: q Quit the emulator. You don't want to use this command. 1.1 root 733: 734: 735: Sound 736: ===== 737: 1.1.1.2 root 738: If your version of UAE supports sound, you can pass parameters like frequency 739: or number of bits to use on the commandline; if you don't specify any, sane 740: defaults will be used. If graphics output is enabled while sound is output, 741: the emulator will be much too slow on most systems. The sound will not be 742: continuous. Therefore, a hack to turn off screen updates is provided: Press 743: ScrollLock to disable graphics, press it again to enable them. 1.1 root 744: 745: The quality of the emulation depends on the setting of the "-S" commandline 746: option. With "-S 3", all of the sound hardware is emulated; and some programs 747: (e.g. AIBB) won't run with other settings. "-S 2" should sound just as good as 748: "-S 3" and will be much faster for some programs. "-S 1" tries to emulate most 749: of the sound hardware, but doesn't actually output sound. "-S 0" completely 750: turns off sound. 751: 752: 1.1.1.2 root 753: Pointers 754: ======== 1.1 root 755: 1.1.1.2 root 756: There are a few sites in the Internet that contain helpful information about 757: UAE. 758: 759: The new "official" UAE page is located at 760: 1.1.1.11 root 761: http://www.freiburg.linux.de/~uae 1.1.1.2 root 762: 763: thanks to Stefan Reinauer who is now maintaining it. 764: 765: There, you will find links to other UAE pages. One which is especially useful 766: is the "UAE Discussion Board" set up by Gustavo Goedert, the address is 767: 1.1.1.11 root 768: http://amiga.nvg.org/uaeboard 1.1.1.2 root 769: 1.1.1.3 root 770: There is supposedly a newsgroup named "alt.emulators.amiga", but I don't get 771: it here. 772: The newsgroup "comp.sys.amiga.emulations" appears to be a proper place to 773: discuss Amiga emulation, but, strictly speaking, it is _not_ the right place. 774: More appropriate places are "comp.emulators.misc", and, of course, Gustavo's 775: discussion board. 776: 777: Petter Schau has written another Amiga emulator named "Fellow". It's mostly 778: written in x86 assembly and only runs under DOS. It's quite compatible and 779: generally faster than UAE. The Fellow homepage is at 780: 1.1.1.11 root 781: http://www.geocities.com/SiliconValley/Peaks/5244/ 1.1 root 782: 1.1.1.18 root 783: The homepage of the Disk2FDI project, which allows you to read Amiga floppies 784: if you have two PC drives, is 785: 786: http://fast.emuunlim.com/disk2fdi/ 787: 1.1 root 788: 789: Thanks & Acknowledgements 790: ========================= 791: 792: Thanks to all who have written me so far with bugreports and success/failure 793: reports when trying to run the emulator on various hardware with different 794: Kickstart versions. A list of everyone who has contributed to the source code 795: can be found in the CREDITS file (this was getting too big to keep it here). 796: 797: Special thanks to: 798: - Jay Miner, Dale Luck, R.J. Mical and all the others who built the Amiga. 799: - Felix Bardos, whose HRM I "borrowed". 800: - Hetz Ben Hamo mailed Peter Kittel from Commodore asking for permission to 801: give Kick 1.3 away. Unfortunately, the response was negative :-( 1.1.1.5 root 802: - Stefan Reinauer, for hosting the UAE Web page after the RWTH decided it's 803: too dangerous to let students have their own Web pages. 804: - Bruno Coste, Ed Hanway, Alessandro Soldo and Marko Nippula provided useful 805: documentation about the Amiga 1.1 root 806: - Fabio Ciucci gets the "Best bug reports" award for his help with the 807: blitter line emulation and other problem areas. 1.1.1.3 root 808: - Michael C. Battilana and Cloanto Software, for all their support. 1.1.1.5 root 809: - Julian Eggebrecht of Factor 5, for providing several F5 games and a lot 810: of valuable input. 1.1.1.16 root 811: Factor 5 has made several of their classic Amiga games freely 1.1.1.5 root 812: available for download. There are still some good people left in the 813: world... 814: - Jens Sch�nfeld, inventor of the Catweasel controller, donated one 815: controller card. 1.1.1.18 root 816: - J�rgen Beck and Ralf Steines, maintainers of the Amiga emulation web 817: site "Back to the Roots" (http://www.back2roots.org) and everyone else 818: who spends time writing to software companies asking for permission to 819: distribute old Amiga games. 1.1.1.11 root 820: - all the software companies who allow distribution of their Amiga games on 821: sites like "Back to the Roots". 1.1 root 822: 823: 1.1.1.2 root 824: Authors/Maintainers 825: =================== 1.1 root 826: 1.1.1.22 root 827: My email address is (please read the section "Before you send email" below): 828: 1.1.1.23 root 829: [email protected] 1.1 root 830: 831: or, via snailmail 832: 833: Bernd Schmidt 1.1.1.23 root 834: Toelzer Strasse 27a 835: 81379 Muenchen 836: Germany 1.1 root 837: 838: Email is more likely to be answered, and will definitely be answered much 1.1.1.23 root 839: faster. 1.1.1.3 root 840: I won't distribute software, neither PD or commercial. Don't send me floppy 841: disks without at least asking first, you will not get them back. 1.1.1.2 root 842: 843: The following people have ported UAE to different platforms; you should 844: direct system-specific questions to them: 845: 846: DOS port: 1.1.1.3 root 847: Gustavo Goedert <[email protected]> 848: Available: http://www.netrunner.com.br/dosuae 849: Sourecode: available on the above Web page, most of it included in the 850: main source (with some delay) 1.1.1.2 root 851: 852: Mac port: 1.1.1.3 root 853: Originally: Ernesto Corvi <[email protected]> 854: Currently: Arnaud Blanchard <[email protected]> 855: Available: http://www.pratique.fr/~jblancha/ 856: Sourcecode: extra package available. Bits and pieces in the main source, 857: but nothing you could get to compile. 1.1.1.2 root 858: 859: BeBox port: 860: Christian Bauer <[email protected]> 861: Available: The main UAE web page (use the Unix sources) 1.1.1.3 root 862: Sourcecode: Included in the main source. Should compile OK. 863: Notes: Christian says he doesn't have much time to spend on UAE, so if 864: anyone is willing to help maintain this port, please speak up. 1.1.1.2 root 865: 866: NextStep port: 867: Ian Stephenson <[email protected]> 868: Available: The main UAE web page (use the Unix sources) 1.1.1.3 root 869: Sourcecode: Included in the main source. Should compile OK. 870: Notes: Ian says he doesn't have much time to spend on UAE, so if 871: anyone is willing to help maintain this port, please speak up. 1.1.1.2 root 872: 873: Amiga port: 874: Originally: Olaf 'Olsen' Barthel <[email protected]> 875: Currently: Samuel Devulder <[email protected]> 876: Available: Not quite sure yet. Paul Liss' Web page has binaries. 1.1.1.3 root 877: Sourcecode: Included in the main source. Should compile OK. 1.1.1.2 root 878: 1.1.1.3 root 879: pOS port: 880: Samuel Devulder <[email protected]> 881: Available: Not quite sure yet. 882: Sourcecode: Included in the main source. Should compile OK. 1.1.1.7 root 883: 1.1.1.13 root 884: OS/2 port: 885: Pressenna Sockalingasamy <[email protected]> 886: Available: ftp://hobbes.nmsu.edu/pub/os2/apps/emulator/uae2_0810_a1.zip 887: Sourcecode: working on including it 888: 1.1.1.2 root 889: XFree86/OS2 port: 890: Krister Bergman <[email protected]> 1.1.1.3 root 891: Available: http://www.kuai.se/~bellman/html/xfreeapps.html 892: Sourcecode: nothing special, apparently the Unix stuff compiles cleanly (?) 1.1.1.2 root 893: 1.1.1.3 root 894: Win32 port: 1.1.1.7 root 895: Originally: Mathias Ortmann <[email protected]> 896: Currently: Brian King <[email protected]> 897: Available: http://www.codepoet.com/uae 898: Sourcecode: bits merged into the main source, the rest available from the 899: URL above. Still trying to merge more of it... 1.1.1.3 root 900: 901: Acorn RISC PC port: 902: Peter Teichmann <[email protected]> 903: Available: http://www.wh1.tu-dresden.de/~sol/acorn.shtml 904: http://www.wh1.tu-dresden.de/~sol/acorne.shtml 905: Sourcecode: Some of it is included in the main source, but since Acorn's OS 906: apparently doesn't have decent file handling, you can't even 907: use the same source layout. Also needs lots of additional files. 908: 1.1.1.2 root 909: Since I generally don't have the possibility to test or improve these ports, 910: it is a good idea to contact their respective authors if you have questions. 911: 912: 1.1.1.3 root 913: Before you send email... 914: ======================== 1.1.1.2 root 915: 916: Before you contact me with a problem that you have, make sure you have read 917: _all_ of the above. Please read also the file "FAQ", which contains a lot of 1.1.1.3 root 918: helpful information, and the README file for your specific system. 1.1.1.2 root 919: 1.1 root 920: I can't answer _every_ question. If you have trouble understanding this 921: README, either because you don't speak English very well or because you have 1.1.1.2 root 922: no clue at all about computers, please try to find some friend of yours who 923: does understand this file and who can translate/explain it for you. I simply 924: can't explain (for example) how to use terminal programs or CrossDOS because 925: I don't use either, and it would be much too time-consuming anyway. This file 926: and the file FAQ contains about every piece of information I can give you. I 927: try to help people who have questions, but sometimes it takes too much time. 928: 929: Please don't ask for Kickstart ROM files or other copyrighted software. Don't 1.1.1.22 root 930: _send_ me stuff like this either. Don't send large attachments, at least not 931: without asking first. 1.1 root 932: 933: Oh, and another thing: If I promise to do things (like implement new 934: features), and forget about them, pester me. That happens occasionally, it's 935: 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.