This is version 0.7.5b of DosUAE, the Dos port of UAE Please read this document the 'readme' and the 'faq' files thoroughly before attempting to run UAE. [INTRODUCTION] Welcome to UAE, the first fully functional Commodore Amiga emulator. This documentation has been written for the DOS version of UAE, and contains information on what UAE is all about, how to set it up, configure it, and use it to the fullest extent of its capabilities. [WHAT IS AN EMULATOR, AND WHAT EXACTLY IS UAE?] An emulator a program which enables you to run software from a machine which has non-native hardware and a non-native operating system, on your computer. UAE is a software emulator, and allows you to run most of the Amiga software that is available commercially, and in the public domain. No extra or special hardware is needed to do this, just the UAE package, and in the case of this version, an IBM Compatible PC running MS-DOS 5.0 or later. UAE emulates many of the hardware features found in a Commodore Amiga, so many in fact, that you can run most games and almost all applications that are available for the Amiga, without having to own one. UAE allows you to transfer software from an Amiga, and store it on your system where it can be accessed by the emulator. While running UAE, your machine will behave just like a real Amiga - you'll have a joystick, mouse, sound, a configurable display, and providing you have the software - the Amiga's native operating system. The important thing to remember is that UAE is a REAL emulator that behaves like a REAL Amiga. On an entry-level Pentium machine it operates at a very usable speed. UAE is an on-going project which has the support of many dedicated people and will get better as more contributions are made and more advances are reached in shaping the emulator. [CHANGES] þ New interface code form the original unix UAE version, i know some people wont like the change, but its easier for me to mantain the port if i can reuse as much code as possible. þ New keyboarb layout, READ THE DOCS FOR DETAILS. þ New DosUAE logo! Since i'm too lazy to make a real GUI the logo is to fool everyone into thinking i did something... ;) þ Joystick emulation bug fix. þ All unix uae075b features like all CPU's and PICASSO on a single binary, and other things, read the NEWS file... (be sure to set CPU to 68020 if you want to use PICASSO) þ No more GUS code, it was to buggy and out of date. [IMPORTANT HIGHLIGHTS USING THE DOSUAE VERSION] þ Hardfile support has changed, you now have to mount then, to include your standard hardfile be sure to include the following line in the 'uae.rc' file: -W 32:1:2:hardfile Look at the included 'uae.rc' file for an example. Or mount it in the User Interface. þ For Picasso support, use Picasso software version 1.31 or higher, be sure to use the 68020 or higher CPU option. þ Sound parameters syntax changed, as follow: The format for the "-S" sound spec parameter is as follows: -S enable:stereo:bits:freq:maxbuffer:minbuffer:adjust_frequency You do not need to give the full specs, you can terminate after every field. enable: Either 0 (no sound), 1 (emulated, but not output), 2 (emulated), or 3 (completely accurate emulation). The suggested value is 2. stereo: Either 's' (stereo) or 'm' (mono). bits: Number of bits to use for sound output, usually 8 or 16 freq: Frequency for sound output; usually 44100 or 22050 maxbuffer: Maximum buffer size for sound output minbuffer: Minimum buffer size for sound output adjust_frequency: Either 0 (not adjusted) or 1 (adjusted) þ The new virtual mount option is used with the -v and -V command line options similar to the -m and -M commands. Directories with amiga files will have an file named #uae.vfs with makes the control of the full amiga file names and attributes. There is mangle size suboption in the virtual mount option, this is the size of the base name of files while mangling the names in the virtual directories, this is because DOS has a maximum size in its path length (about 70 chars), and some people needs loots of subdirectories, seting this to 1 will make the virtual mount option create small file names, maximazing the number of subdirectories one could have, but as a counter effect it will create small and criptic file names... valid options are from 1 to 8, default is 8, the option is entered with an '*' after the mount point (thus you can have diferent mangle sizes for each mounted directory), examples: This will try to create small filenames: -v test:c:\vfs*1 This will create bigger filenames: -v work:c:\work*8 þ Joystick stuff: handle two joysticks, map the second joystick button, map both buttons pressed at same time into the third button, better calibration code þ implement -w command line parameter to set m68k_speed, use high values like 8 or even more for games, demos and to get better sound emulation and small values like 1 for cpu intensive aplications, large values can help on the sound emulation, default is 4. Note that if you use small values it also makes sence to disable the sound with -S 0, because the current sound emulation code consumes a lot of cpu time. þ Debugger can be used, use HOME+F2 to activate debugger, you can also use Ctrl+C if you get locked inside the debugger. The g debug comand leaves debugger. þ No more log files, if you want a log use 'uae > uae.log', only the last 100 messages are kept in memory. [SYSTEM REQUIREMENTS] In order to run UAE, you will need the following: þ An IBM Compatible computer with a 386 or faster CPU þ MS-DOS Version 5.00 or later þ 8 Megabytes of RAM þ A VGA compatible video þ A Mouse However, it is RECOMMENDED that you have the following setup, if you want to get the most from UAE: þ An IBM Compatible computer with a 100mhz 486 or faster Pentium CPU þ MS-DOS Version 5.00 or later þ 16 Megabytes of RAM þ A PCI VGA compatible video card which supports VESA BIOS extensions 2.0 þ Analog or digital joystick, connected to game port þ Soundblaster/GUS or compatible sound card UAE is a *very* CPU intensive program, which will benefit immensely from a fast CPU and plenty of RAM. The faster your computer is, the more you can enjoy what UAE has to offer in terms of fast emulation. Don't expect UAE to come to the party on a 386 with 256k VGA and 4MB RAM. [INSTALLING UAE] In the utils subdirectory, you will find two programs makedisk.exe and readdisk.exe. Makedisk.exe enables you to make a virtual hard disk file which UAE can use as a hard disk when emulating the Amiga. Alternatively, you can use it to create a blank diskette for use while the emulator is running. Readdisk.exe allows you to read an Amiga disk image file (.adf), and transfer the contents into a MS-DOS directory. A more precise look at how both of those programs work will be provided later in this document. In the amiga directory, you will find two Amiga executables which enable you to transfer the contents of an Amiga floppy disk into a disk image file, and also transfer a copy of the Amiga's Kickstart ROM into a file called kick.rom, which UAE uses to to emulate the Kickstart - an essential component if you want to run Workbench (the Amiga's native operating system). I will also explain those programs in greater depth later in this document. Once you've made sure you have all the files from the UAE DOS distribution, you can run UAE from a DOS prompt by just running the uae.exe executable. UAE provides an simple menu-driven front-end interface that allows you change and configure various aspects of it's operation to suit your emulation needs. What follows is a brief description of each of the menu features, and some suggested settings for people who may not have had experience with Amiga hardware and may feel somewhat unsure of how UAE should be configured. Also, consult the QSETUP.DOS file that comes with this distribution for a step-by-step guide to setting up UAE. [CONFIGURING UAE] After launching UAE, you will be presented with a configuration screen, containing a cursor driven menu. Here, you can configure UAE to how you want it to run on your system. The text on the right side of the menu indicates how UAE is presently configured, and as you change settings in the menus, the changes will be reflected here. [KEYBOARD COMMANDS] The following keyboard commands can be used while UAE is running: HOME + ESC Exit Emulator HOME + F1 Options Menu HOME + F2 Activate Debugger PrintScreen Dump a copy of the screen to a '.tga' file ScrollLock Disable/Enable graphics update Pause Disable/Enable sound update To insert and eject disks use the Options Menu (Home+F1). The Amiga has its own special keys the same way the MAC has it's own special key, and in the same way that newer PC's come with keyboards equipped with Windows keys. The left and right Amiga keys are used to carry out special functions such as accessing pull-down menus without the mouse, and other shortcuts. [MISC KEYBOARD MAPPINGS] The following keys are remaped in DosUAE: RightWindows PageUp Right Amiga key LeftWindows PageDown Left Amiga key Insert Amiga Help key F11 \ key [TROUBLESHOOTING/FREQUENTLY ASKED QUESTIONS] 1. What are the differences from DOS and the LINUX versions ? A) Some command line switches: -v VOL:dir mount a virtual directory called as AmigaDOS volume VOL:, this option supports full amiga file names and attributes -V VOL:dir like -v, but mount read-only -x Don't use linear framebuffer, even if available -p filename Use filename to save printer output (i.e. PRN:) -I device Name of the used serial device (i.e. AUX:) -w n Set M68K_SPEED, large values for games, small for cpu apps, default is 4. The format for the "-S" sound spec parameter is as follows: -S enable:stereo:bits:freq:maxbuffer:minbuffer:adjust_frequency You do not need to give the full specs, you can terminate after every field. enable: Either 0 (no sound), 1 (emulated, but not output), 2 (emulated), or 3 (completely accurate emulation). The suggested value is 2. stereo: Either 's' (stereo) or 'm' (mono). bits: Number of bits to use for sound output, usually 8 or 16 freq: Frequency for sound output; usually 44100 or 22050 maxbuffer: Maximum buffer size for sound output minbuffer: Minimum buffer size for sound output adjust_frequency: Either 0 (not adjusted) or 1 (adjusted) B) Currently DosUAE only support adf disks compressed with GZIP compressor. 2. What kind of software won't UAE run? Although UAE is at the stage where it emulates a lot of features found on a real Amiga, there are still some things that UAE simply cannot, at this point in time, run. Firstly, UAE lacks an MMU (Memory Management Unit), which means that software that requires one (Virtual memory utilities, Linux, etc.) will simply not work. An MMU may come along in a later version, but at this stage it is not supported. UAE is also incapable of running software that requires the AGA chipset (found in Amiga 1200 and Amiga 4000 systems), because none of it's features are supported. This too may come along in a later version of UAE, as experimental work is being done at present. There are a small number of applications for the Amiga that demand a 68020 CPU *and* a 68881 FPU to run properly (some raytracing applications being the main one to come to mind), so obviously you will have to use the 68020 version of UAE to use these. 3. What to do if I don't want to type in all command-line switches again and again ? Put the command line switches you use in the 'uae.rc' file. Note that the configuration is NOT automaticly saved in the 'uae.cfg' file anymore, it will be saved in the 'uae.rc' file if you use the '-o' command line option. 4. Do I have to name diskimages df0.adf ? No. Just specify your diskimage file after the parameter -0. This is for DF0:. For DF1: it's -1 and so on. 5. How can I use the diskimages available on the net ? Files with the extensions .gz or gz.bin are packed with GZip. Get it on ftp://oak.oakland.edu. Unpack the files with Gzip -d . 6. Why do some demos crash which are said to work in the compatibility list ? Try the -s 4 switch. Then you could look in the output of the emulator. If you don't know what to do with the information in it write me. 7. How can I get sound ? Enable it on the Text Interface Menu. 8. How can I squeeze the most speed out of UAE? Run the emulator in the lowest screen mode (320x200), set it to 256 colors, make sure aspect correction is disabled, and set the frame rate to every 3rd frame. Lastly, disable sound. It won't look very nice, but it will run as fast as your machine allows. 9. Why do the Workbench windows and fonts look warped? 320x200, 320x240 and 320x400 are not proportional modes. Try switching to 640x480 or 800x600 and enabling aspect correction (without aspect correction, UAE skips lines in the display - enabling it fixes this). 10. Why does UAE sometimes crash under Windows 95? UAE does things that Windows 95 sometimes dislikes. Sometimes you may be able to get it to work, other times you may not. It depends how you have it configured. It is recommended you quit Windows 95 and run it from a plain DOS prompt with disk-cache enabled. 11. I can't seem to get the 640x480 and 800x600 modes to work. These modes require that your video hardware has VBE support. You can either obtain UniVBE (part of the Display Doctor suite of programs) from Scitech (http://www.scitech.com), or possibly a VBE update driver from your video card distributor. 12. Wasn't this called the Unusable Amiga Emulator? Yes, but it seems hardly appropriate now. The name was really only meant for version 0.1, which couldn't even boot. 13. It still doesn't work. Why ? The diskimage or rom file could be corrupt. Your configuration might cause troubles. Try creating a boot disk with nothing more than the VESA and the mouse driver. 14. What should I do if I find a bug? If you find what you suspect may be a bug, please contact the author of the DOS UAE port. The more information you supply about problems you may be encountering, the more likely the problem can be solved. If possible, include a snapshot image of the screen where the problem took place. The authors details are at the end of this document. [HISTORY OF DOS UAE] Version 0.7.5b þ New interface code form the original unix UAE version, i know some people wont like the change, but its easier for me to mantain the port if i can reuse as much code as possible. þ New keyboarb layout, READ THE DOCS FOR DETAILS. þ New DosUAE logo! Since i'm too lazy to make a real GUI the logo is to fool everyone into thinking i did something... ;) þ Joystick emulation bug fix. þ All unix uae075b features like all CPU's and PICASSO on a single binary, and other things, read the NEWS file... (be sure to set CPU to 68020 if you want to use PICASSO) þ No more GUS code, it was to buggy and out of date. Version 0.6.9c þ Many beta features from pre-0.7.0 beta version (this is a beta version). þ Fixed virtual mount option bug (still needs testing). Version 0.6.9b þ Fixed joystick emulation bug (CTRL as fire). þ Fixed blank lines bug in the graphics code. þ Support for CLOANTO encrypt roms. þ Support for PICASSO96 emulation. Version 0.6.9 þ Found some missing vbe modes that got lost at 068c. þ Mystic (and maybe other cards) in hicolor fix. þ Interface clean up by Tim Gunn. þ Joystick stuff: handle two joysticks, map the second joystick button, map both buttons pressed at same time into the third button, better calibration code. þ Some bugfixes in the virtual mount option. þ New mangle size suboption in the virtual mount option, this is the size of the base name of files while mangling the names. þ Lateste serial patch from Stepan. þ New Sound Options, Stereo sound and Dynamic adjust Freqency. þ New GUS code from Michael Sontheimer. Still no stereo, dynamic adjust frequency or minimal sound buffer settings. þ Implement -w command line parameter to set m68k_speed. Version 0.6.8c þ New virtual mount option, with allows allows full amiga files names and attributes under plain DOS subdirectories, now there is no need to use the hardfile (thought this is still kind of beta :). þ New interface from Tim Gunn. þ New serial code from Stefan Reinauer, mighty work better now. þ New sound buffer scheme, now the emulator writes directly into the sound buffer, there are two sound buffer parameter, minimum and maximum (only works with SB for now, GUS works with the same last scheme). þ Bug fix in VESA code, that ignored svga granularity, emulator should be more compatible now. þ Bug fix in memory management, emulator should run more easyly under windows. þ Bug fix in disk ejecting. þ Bug fix in sprites missing. þ Bug fix in keyboard emulation with cause emulator to abort. Version 0.6.8b þ Now any sound rate can be used, not only the 22050 and 44100. þ Bug fix in the y centering routine. þ Changed a bit gfx code to work more like the old one. þ Bug fix in text interface, regarding diskimage handling. þ Bug fix that made emulator abort without telling why (now it tells :). Version 0.6.8 þ Rewriten all video and handlers code. þ Changed a bit the serial support for DOS, might work better now. Not tested. þ CapsLock LED works now. þ Debugger can be used, use HOME+F6 to activate debugger, you can also use Ctrl+C if you get locked inside the debugger. The g debug comand leaves debugger. þ No more log files, if you want a log use 'uae > uae.log', only the last 100 messages are kept in memory. Version 0.6.5 þ PRINT SCREEN Key saves a copy of the sreen to a targa image file (.tga). þ PAUSE Key switches sound on/off (emulator must start with sound on). þ INSERT Key is maped as the amiga HELP Key. þ Try to preserse case off files under Win95 with the mount directory option (untested since i don't have win95). þ Fake joystick now has the RIGHT CONTROL Key as the Fire, also. þ Graphics code changed a bit, might work on more cards. þ Ignore FPE exceptions. þ Support files compressed with gnu GZIP (has to have gzip/gunzip instaled). þ Fixed 16 colors modes. þ Sound Blaster bugfix by Michael Sontheimer & Peter Remmers. þ GUS Support by Michael Sontheimer, make sure to have the ULTRASND envirement variable correctly set. Version 0.6.4 þ Changes in the interface, disk changing now support directories, ability to skip user interface added in. þ Chaged the way FPU is compiled, hope it proves more stable. þ Cleaned up graphics code. Version 0.6.3 þ New graphics code, supports VBE 2.0 directly, as well as normal VGA and VGA mode X. þ New Sound Blaster code from Peter Remmers. þ Full feature Interface code from Tim Gunn. þ Preliminary serial support, not tested. Version 0.6.0 þ Optimized sound blaster code. þ Two sound buffer sizes, minumum and maximum. Version 0.5.4b þ Preliminary sound support. Only done for sound blaster 8 bits 22050 sample frequency. Only works with DMA 1 and IRQ either 5 or 7. þ Some empirical printer support debugging (since I don't have a printer). þ Lock variables used by interrupt handlers. Might increase stability of the emulator for machines with little memory. Version 0.5.4 þ Less Optimized version removed. þ Script flag forced off on the filesys support. þ Correct aspected ratio command line option added. Works with any resolution now. Version 0.5.3 þ Less Optimized version made. þ Disk Change/Eject implemented. þ CPU keyboard reset fixed. þ SVGA asm code optimized a bit. þ SVGA 640x480 mode implemented. þ Normal DOS slashes (/) are now supported in the filesys mount. þ Script and Exec flags are now forced on the filesys support. þ Printer support ported from unix code. Version 0.5.2 þ SVGA asm code remade. þ VGA low-res modes implemented. þ Joystick button bug fixed. þ Keyboard support finished (extended keys). þ Arbitrary size hardfile implemented. þ Makedisk redone to support arbritary size hardfile. Version 0.5.0 þ Linux Assembler code ported to DOS. þ SVGA asm code remade. þ Makedisk utility created (make hardfile and diskfiles). þ Mouse support redone (interrupt). Version 0.4.4 þ DPMI/EMS version implemented with DJGPP 2.0. þ SVGA asm code remade. þ SVGA Hicolor/64k mode implemented with libgrx 2.0. þ Joystick support implemented (pooling port 201H). þ 'Disable messages' command line option removed. þ Logging of messages into 'uae.log' file. þ Hardfile bug fixed. Version 0.4.1 þ First public realese. þ EMS only version implemented with DJGPP 1.12.maint4. þ No graphics mode implemented (Doh!). þ SVGA 800x600 256 and HiColor/32k modes implemented with libgrx. 1.03.maint1 (and some speed up hacks). þ Keyboard support implemented (interrupt). þ Mouse support implemented (pooling). þ Filesys fixed to work with DOS. þ Disable messages command line option implemented. [CONTRIBUTERS] Code contributers: þ Gustavo Goedert: Port, video code, sound code, filesystem code þ Peter Remmers: Sound Blaster sound code þ Tim Gunn: Interface code þ Michael Sontheimer: GUS sound code þ Tomi Hakala: Bugfixes in interface code Misc contributers: þ Nemo Pohle: rewritten 'readme.dos' for duae054b þ Henry Mantere: Qbasic program that helps transfering diskimages through a serial cable. þ Brett Eden: rewritten 'readme.dos' for duae064, betatesting þ Paolo Besser: rewritten 'readme.dos' from duae064 into italian þ Eduardo Motta Buhrnheim (aka MINGO): Some interesting VBE tips ;) þ Marco de Cesare: Betatesting and support Please fell free to make any contribution to DosUAE. All DosUAE users will be very gratefull. [INFORMATION] The DOS version of UAE has a Web site, at: http://www.hephaestus.org/uae/dosuae UAE also has it's own news board, at: http://www.hephaestus.org/uae/uaeboard If you use BBS in Germany try the following: Point Of No Return BBS 28k8: +49-6039-95934 ISDN: +49-6039-95935 [AUTHOR] The author of the DOS port of uae, Gustavo Goedert, can be contacted by email at: (but please use the UAEBoard first...) ggoedert@hephaestus.org Please read the FAQ and documentation carefully before posing questions to the authors. Do not send requests to any of the UAE contributors for disk images or Kickstart ROM files, as they will be ignored.