--- uae/docs/README 2018/04/24 16:38:39 1.1.1.1 +++ uae/docs/README 2018/04/24 16:39:45 1.1.1.3 @@ -1,120 +1,100 @@ -This is version 0.6.4 of UAE, the Un*x Amiga Emulator. +This is version 0.7.5 of UAE, the Un*x Amiga Emulator. -#include +License +======= -Copyright 1995, 1996 Bernd Schmidt & contributors (see below). This program is -freeware. You may do whatever you want with it for personal use. -Permission is granted to redistribute this program free of charge, provided it -is distributed in the full archive with unmodified contents and no profit -beyond the price of the media on which it is distributed is made. Exception to -the last rule: It may be included on freeware/shareware collections on CD-ROM. -There are no warranties of any kind for this program. If you use this program, -you do so at your own risk. The authors are not responsible for any damages -that might result from using this program. +UAE is available under the terms of the GNU General Public License. See the +file COPYING that is included in the top level directory of this archive for +details. Overview ======== -UAE emulates the hardware of an A500 with 2MB chip and a variable amount of -fast memory. Up to 11.8MB RAM are supported. It works with all Kickstart ROM -versions, provided they are not compiled for the 68020. It supports some (one, -to be precise) ECS features apart from nearly all the functionality of an OCS -chipset. +An emulator is a program which enables you to run software for a machine +which has non-native hardware and a non-native operating system, on your +computer. UAE allows you to run most of the available Amiga software. It is a +software emulation, meaning that no extra or special hardware is needed to do +this. The hardware of an Amiga is emulated accurately, so that Amiga software +is tricked into thinking it is running on the real thing, with your computer's +display, keyboard, harddisk and mouse taking the parts of their emulated +counterparts. UAE was developed for Unixoid systems. Meanwhile, it has been ported to the -Mac, DOS, the BeBox, NextStep, the XFree86/OS2 environment and AA Amigas (it -can't quite run itself yet). The Mac and DOS versions are distributed with -binaries and a seperate README file that you should read after you have -finished this document. The other versions must be compiled from the source -code. - -What UAE does not (yet) emulate is software. To use UAE, you need a Kickstart -ROM image as well as any other software you want to run, e.g. a Workbench -disk. Both are copyrighted, and I can't include them. Don't ask me to send -them to you. -Since the PC floppy controller can't read Amiga disks (yes, that's a fact), -floppy access has to be emulated differently: Floppies are emulated by means -of disk files that contain a raw image of the floppy disk you want to emulate. -Read the section "tools" below for information how to create ROM images and -disk files. -You can also emulate a harddisk. UAE can mount native filesystems as -harddrives, so once you have booted it up, you can access all your files on -the harddisk. It is currently impossible to boot from the emulated harddisk. -I don't have a clue why. - -I am developing UAE using Linux. Only if you are running Linux can you be -reasonably sure that all versions of UAE will work for you. On other Unix -systems, you may encounter problems from time to time. I can make no -guarantees about the NextStep and BeBox versions, these are very recent ports -and will probably need some more time before they compile/run reliably. - -These are the requirements for getting the Unix version to run: - - X11, or SVGAlib if you are using Linux. - - an ANSI C compiler. GCC is _strongly_ recommended. - - Optionally, tcl7.4/tk4.0 - -Note: some Linux installations (usually Slackware) are broken. If you get -linker errors ("final link failed: bad value"), you need to upgrade the -binutils package that you can find on sunsite.unc.edu:/pub/Linux/GCC -Before installing anything from that directory, read the corresponding -release.* files. -You'll get better performance if you are using an ELF system. - -On Linux, 8MB are sufficient to run UAE, although startup will be much faster -if you have some additional memory. The DOS version also works with 8MB, but -startup is slow there too. I have not tried the other ports, it may well be -that other OS's are better at wasting memory. At least 16MB are recommended. +Mac, DOS, the BeBox, NextStep, the XFree86/OS2 environment and the Amigas (it +can run itself by now). You should have received several other files along +with this document with details on how to install and use the version for your +operating system. This section is just what it says: an overview. Please read _all_ of this -file, especially if you have problems. Please read also the file "FAQ" which -contains some Frequently Asked Questions (and even the answers!) +file, especially if you have problems. UAE has many, many features and +equally many configuration options. If you don't know about them, it's likely +that UAE doesn't work for you, or doesn't work as good as it could. + +Please read also the file "FAQ" which contains some Frequently Asked +Questions (and even the answers!) You should also look for a document +describing the specific port of UAE to the operating system you are using, +for example "BeOS/README" or "DOS/README". + +People have complained that the UAE documentation contains only "weird jargon". +Sorry about this. Despite what MessySoft and Tomato tell you, computer +programs aren't always easy to use. UAE does require some assistance from you, +and therefore you should at least understand a bit about computers. After all, +you are an Amiga fan, so you should know what a Workbench is, don't you think? -Installation -============ +Features +======== + +This version of UAE emulates: + +- An Amiga 500 Computer, with 68000 or 68020 CPU (68020 includes 68881 FPU) +- OCS Graphics Chipset, plus big blits from the ECS Chipset +- Up to 2MB Chip RAM and up to 8MB Fast RAM, or 8MB Chip RAM without Fast RAM. +- Up to 64MB Zorro III Fast RAM, independent of Chip RAM setting. +- Up to 1MB Slow RAM, for extended compatibility with problem software +- Up to 8MB of graphics card memory, usable by software that supports + Picasso 96 compatible graphics cards. +- 4 x 3.5" floppy disk drives (DF0:, DF1:, DF2: and DF3:) +- Hard-disk emulation +- Joystick support (with option of mapping joystick to numeric keypad) +- Mouse support +- Ability to run in various screen modes (for better display quality or + better speed) +- Full sound support, consisting of 4 x 8bit channels (mixed into one, so + output is mono for now). +- Beta parallel and serial port support +- some other things which don't work well enough to mention them here... + + +Requirements (IMPORTANT! READ THIS!)/Limitations +================================================ + +Not emulated: +- Sprite to playfield collisions (sprite to sprite collisions work) +- An MMU (part of 68030/040 CPUs except those that Commodore used). This means + you can't use virtual memory systems or real operating systems like Linux + or BSD. +- The AGA chipset (A4000/A1200). This chipset has enhanced capabilites for + up to 256 colors in all resolutions. +- Serial port emulation exists but doesn't work too well. + +Since the PC floppy controller can't read Amiga disks (yes, that's a fact), +floppy access has to be emulated differently: Floppies are emulated by means +of disk files that contain a raw image of the floppy disk you want to emulate. +A disk file is an image of the raw data on an Amiga floppy disk, it contains +901120 bytes (880K), which is the standard capacity of an Amiga disk. -To build UAE, first unpack it to an appropriate directory (e.g. /usr/src/uae -on a Linux system). After that, you will have to edit the file config.h to set -some configuration options. Then, you should give the command "configure". -This script will determine what type of system you are using. It will then -create an appropriate Makefile. Type "make" after that to build UAE. - -If you are running Linux, you can say "configure --without-x" as an -alternative. If you do this, UAE will be configured to use the SVGA library. -If you use SVGAlib, be warned that SVGAlib is not too stable and using it is -inherently a little dangerous, you might want to have a way to log in from a -remote terminal if things go horribly wrong. If you are very unfortunate, you -might lock up your machine otherwise. -Note that you must be root to run SVGAlib programs. Making UAE suid root is -_not_ a particularly good idea if you care about the security of your system. -If you have a BeBox, you should not run configure. Instead, compile UAE by -doing "make bebox". - -If you configure UAE for building the X11 version (which is the default if you -simply say "configure"), the configure script will try to find the program -"wish4.0" in the path. You can disable the UAE user-interface by passing the -"--disable-gui" option to configure. By default, the X11 version of UAE -tries to use a GUI written in Tcl. This requires Tk version 4.0. The SVGAlib -version uses a ncurses-based user interface. - -The compilation may take a while, especially for the cpu*.c files. There might -be some warnings, ignore these. It may also take a lot of memory. You should -have at least 8MB physical RAM to compile this, plus maybe 10MB swap and 9MB -filesystem space. - -After compilation, you'll need to install the ROM image. This must have a size -of exactly 512K (if you only have a 256K image of a 1.x Kickstart, that should -work, too) and should be an image of the addresses 0xF80000-0xFFFFFF on -your Amiga system. The file must be called kick.rom to be recognized. Please -read the next section on how to transfer files from your Amiga to your PC. - -You also need to install a disk image file. This must be called df0.adf (adf = -Amiga Disk File), and should be a raw image of the data on the floppy disk: -11x2x80 sectors == 901120 bytes. -Please try running UAE without a diskfile first. If everything went O.K., the -emulator should show the Kickstart logo (don't be too impatient, this will -take a while on slow machines). +To actually run the program, you'll need to install the ROM image from your +Amiga. You can't run UAE if you don't have this image. It is not included +because it is copyrighted software. Don't ask me to send you one. I won't. +If you don't have an Amiga and still want to use UAE, you'll have to buy an +Amiga or at least the system software (ROM + Workbench) first. +The Kickstart image can have a size of either 256K or 512K. It must be named +"kick.rom" by default. + +Read the section "tools" below for information how to create ROM images and +disk files. If you don't have a Kickstart file, you may still be able to boot some games and demos. The emulator includes some primitive bootstrap code that will try @@ -123,55 +103,90 @@ bootblock only uses the one or two Kicks the "replacement Kickstart", your program will boot. Don't expect too much, though. -If you are a daring person, you can edit custom.c before compiling and enable -the "EMULATE_AGA" define. UAE will then try to emulate some AGA features. I'd -like to hear feedback as to how well it works (expect it not to work at all -for a start). +You'll also need some other software to run - why else would you want to +emulate an Amiga? There are several ways to make the software accessible to +UAE, either with disk image files or with a harddisk emulation. You should +make an image of your Amiga's Workbench disk and install it as "df0.adf" +(adf = Amiga Disk File) when you use UAE for the first time. More about how +to create these files in the chapter "Transferring software" + +To use Picasso96 emulation, you need the Picasso96 libraries, which are also +not included. They can be obtained (e.g.) from Aminet. Invoking UAE ============ -After building the program, you should have an executable called "uae". You -can simply execute it, but you can also optionally give it one of the following -parameters: +First, read the system-specific documents for information how to set up UAE. +You should have an executable program called "uae". You can simply execute it, +but you can also optionally give it one or more of the following options: General options: -h : Give help on the options. + -A n : Set emulator accuracy to n. The default is n = 2, which means the + emulator will try to be as accurate as possible. This no longer + does much in this version, and I'll probably remove it. -f n : Sets the frame rate to 1/n. Only every nth screen will be drawn. -a : Add no expansion devices. This will disable fastmem and harddisk emulation, but some extremely badly-written games may need this. + (Kickstart 1.2 needs it, too) -l lang : Set the keyboard language. Currently, the following values can be used for lang: "us" for U.S. keyboard (default), "se" for swedish, - "fr" for french, "it" for italian or "de" for german keyboard. + "fr" for french, "it" for italian, "es" for spanish, or "de" for + german keyboard. + This setting only affects the X11 version. -0 file : Try to use file as diskfile for drive 0 instead of df0.adf. - -1 file, -2 file and -3 also exist for the other drives. + The options -1, -2 and -3 also exist for the other drives. -r file : Use file instead of kick.rom as Kickstart image. - -J : Use the numeric pad for joystick emulation (with 5 and 0 as fire - buttons). This will turn off real joystick support. It's no good - for action games, but may be useful for other games. - -x : General-purpose option. For the X version, it makes the X cursor - visible (recommended). For the SVGAlib version, it turns off - linear framebuffer support (sometimes, with -d 4, SVGAlib is - faster without linear framebuffer). - -o : Allow UAE to overwrite ~/.uaerc with the selected options. This is - only used by the text-based GUI in the SVGAlib and DOS versions. + -J xy : Specify how to emulate joystick port 0 (x) and 1 (y). Both x and y + can be one of the following characters: 0 = joystick 0, 1 = + joystick 1, M for mouse, and a, b or c stand for various keyboard + replacements (a is the numeric pad with '0' as fire button, b the + cursor keys with right control as fire button and c is T/F/H/B with + Alt as fire button. + The default is "-J M0" (mouse and joystick as usual) -G : Disable the user interface (if present). + -n specs: Set blitter emulation. "specs" is a string of characters. If it + contains a "3", the blitter will use 32 bit operations where that + seems profitable (note that this will cause bus errors on most + RISC machines). If you specify "i", all blits will finish + immediately, which can be nice for speed. To enable both options, + say "-n 3i" + -w n : Set CPU emulation speed to n. The default value is 4; higher values + will give the custom chip emulation a higher priority over the CPU, + but some programs crash if this is higher than 4. Setting it to 1 + is a good way to make the emulator run slower on machines which are + too fast. + -C specs: Controls how the CPU is emulated. The first letter must be '0' for + 68000 emulation, '1' for 68010, '2' for 68020 or '3' for + 68020 + 68881. It can be followed by a 'c', which enables a slower + but more compatible version of 68000 emulation, or by an 'a', which + enables a 24 bit address space for 68020 emulation. Normally you + don't want either; use the more compatible emulation if some game or + demo does not work. The 24 bit address space option appears to be + necessary for some Kickstart ROMs, so try that if things don't work + at all. -Emulating external devices (harddisk, printer, serial port): +Emulating external devices (harddisk, CD-ROM, printer, serial port): -M VOLUME:path -m VOLUME:path - mount the unix file system at path as an Amiga filesystem with + Mount the unix file system at "path" as an Amiga filesystem with volume name "VOLUME:". For example, "-M sound:/usr/amiga/modules" - If you use -M instead of -m, the volume will be read only. - See below. + If you use -M instead of -m, the volume will be read only. Use this + for mounting CD-ROMs. See below. + -W secs:heads:nr:file + Mount the hardfile "file" as an emulated harddisk, using a geometry + of "secs" sectors per track, "heads" surfaces and "nr" reserved + blocks. Can be abused to mount floppy images. See below. -p cmd : Enable printing. See below. - -I dev : Use "dev" as serial device (e.g. /dev/ttyS1 on Linux). Doesn't - really work yet, at least not for me. + -I dev : Use "dev" as serial device (e.g. /dev/ttyS1 on Linux). Sound options: - -S n : If your version of UAE supports sound, set the sound support level - with this option. + -S specs: If your version of UAE supports sound, this option allows you to + tell the emulator how to produce sound. The specs parameter is + made up as follows: + n:stereo:bits:frequency:minimum buffer size:maximum buffer size + You can use one of the following values for "n": n = 0: No proper sound emulation at all. May be incompatible (unlikely). This is the default. n = 1: Emulate the sound hardware, but don't output sound. May be @@ -180,38 +195,73 @@ Sound options: n = 3: Emulate the sound hardware _exactly_. I don't think you'll hear a difference. SIDmon modules will be emulated correctly, but painfully slow with this setting. - -b n : Use n bits for sound output (8 or 16) - -R n : Use n Hz to output sound. Common values are 22050 Hz or 44100 Hz. - -B n : Use a sound buffer of n bytes (use small values on fast machines) - Default is 8192. - + Unfortunately, this may also be needed to get some programs + to work (AIBB, for example). + Use either 's' or 'm' to set the "stereo" value. + For "bits", common values are 8 (low quality) or 16 (high quality). + For "frequency", common values are 22050 or 44100. The quality of + sound output increases with the frequency. + You can specify the minimum and maximum size of the sound buffer. + Smaller buffers reduce latency. + You don't need to specify all of the options, you can stop after + each subpart. Examples: "-S0" (sound off), "-S2:s" (sound on, + stereo), "-S3:m:16:44100" (complete emulation, mono, 16 bits, + 44100 Hz). + Note: high quality sound requires a lot of computing power, so try + with different settings if your machine is not fast enough. + Memory options: -s n : Emulate n*256K slow memory at 0xC00000. Some demos/games need this. -F n : Emulate n megabytes of fast memory as an expansion board. + -Z n : Emulate n megabytes of Zorro III fast memory as an expansion board. -c n : Emulate n*512K chip memory. The default is 2MB chipram. Some very - broken programs need "-c 1" to work properly. - -Debugging options: + broken programs need "-c 1" to work properly. The largest legal + value is "-c 16", which means 8MB chip memory. + -4 n : Usually, UAE uses a 24 bit address space when it emulates a 68000, + and a 32 bit address space when it emulates a 68020. If n is 1, + this option turns on a 24 bit address space in 68020 emulation. It + appears to be necessary for some Kickstart images. Careful: this + option has harmful side effects, and should be disabled by default. + +Debugging options (not interesting for most users): -D : Don't start the emulator at once, use the built-in debugger. -i : Print illegal memory accesses - -g : Emulate parts of the OS. This isn't very stable and not - recommended. Display options: - -d mode : Select a graphical resolution for UAE to run in. -H mode : Select a color mode to use. - -C : Correct the aspect. Normally, graphics will be only half as high - as they should be, this option draws every line twice to correct - this. It makes the emulation slower, though. - Proper emulation of interlace mode is impossible without this - option. + -O specs: Select a display mode, see below how the specs parameter is + interpreted. + -U n : Emulate a Picasso 96 compatible graphics card with n MB graphics + memory. -Resolutions: 0 (320x200); 1 (320x240); 2 (320x400); 3 (640x480); - 4 (800x600). Color modes: 0 (256 colors, default); 1 (32768 colors); 2 (65536 colors) 3 (256 colors, with dithering to improve color quality) 4 (16 colors, dithered); 5 (16 million colors) +About the "-O" display specs. These consist of the width and height of the +mode, plus optional modifiers. One valid option to pass to UAE would be +"-O 640:300:" which means use a display 640 pixels wide and 300 pixels high, +with no modifiers (nothing after the second ":"). You may specify the +following modifiers: + l: Tell UAE to omit drawing every second pixel horizontally (for "lores" + modes). Example: "-O 320:200:l" + x: Tell UAE to try to fit the image horizontally into the displayed + window. For example, if you have a mode that is 640 pixels wide, and the + displayed image is also 640 pixels wide, the picture may still be + partially invisible because it is displayed too wide to the left or to + the right. With the "x" modifier, UAE tries to prevent this. + You can also specify a capital "X", in that case, UAE tries to be + extremely clever when doing this. + y: The same thing in green, for fitting the image vertically into the + window. (Y also exists) + d: Draw every line twice. This allows interlace mode to be emulated nicely, + but of course you also need a display that is twice as high + c: Correct the aspect. This will omit certain lines of the display to make + it fit better into the screen. + +Whew. You'll probably have to experiment a little to get a feeling for it. + + UAE may choose to ignore and/or refuse some combinations of these two parameters. Some of these modes may also fail to work on your system. @@ -220,8 +270,6 @@ directory. Simply create ~/.uaerc and pu non-Unix systems, the file is called uae.rc and should be located in the current directory. -If you use SVGAlib, the only way to leave the program is pressing F12. - Choosing color and screen modes =============================== @@ -237,43 +285,54 @@ satisfying speed. Note that the ditherin 256 colors with dithering look better than 256 colors without, remember that UAE will be slower in that mode. -The low-resolution (320x???) modes should help some of the proud owners of new -P6 systems with a broken chipset and an exciting PCI performance of 4MB/s :-) - The recommended resolution is 800x600. In the lower resolution modes, some overscan pictures the Amiga tries to display may not fit entirely on the screen, others may be off-center and some graphical effects may look weird. For best results, use 800x600 with at least 32768 colors. +For speed, use 400x300 lores with 256 colors. + +_Don't_ use 24 bit or 32 bit screen modes, unless you absolutely have to. +These are way too slow to be usable. Harddisk emulation ================== -!! Careful: All of this has been rewritten for this version. There may be -bugs, please report any strange events. - -Using diskfiles is awkward. There are two ways how you can use larger amounts -of data with UAE. UAE can emulate more than one harddisk at one time, the -volumes will be named UAE0:, UAE1:, etc. UAE will boot from UAE0: if no -diskfile is found for floppy drive 0. - -a) Harddisk files. -You can create a (unformatted) harddisk file with +Since using diskfiles is awkward, it is necessary to emulate harddisks. There +are two ways how you can use large amounts of data with UAE: harddisk files +and mounted directories. + +1. Harddisk files + +Harddisk files are large files that contain the image of an Amiga filesystem. +They work much the same way as a disk file. You can simply create a large +empty file and tell UAE to use it as a hardfile, but you will need to format +it from the emulation before you can actually use it. +Under Unix, You can create a (unformatted) harddisk file with dd if=/dev/zero of=hardfile bs=512 count=16384 - -Currently, the size is fixed (8MB). +That will create an 8MB file. Other ports of UAE may come with a utility +called "makedisk" or other ways to create such a file. -The harddisk file is accessed by a resident ROM module that is built into the -emulator, called "hardfile.device". If it is present, this is always the first -harddisk device the emulator finds and will be named UAE0: - -If you are using Kickstart 1.3 or earlier, this can't currently be mounted at -boot time, and therefore you can't boot from it either. You will have to boot -either from a floppy disk image or from a filesystem (see below), and mount -the hardfile.device later. To do this, add the following to "DEVS:mountlist": +To tell the emulator that you want to use a certain file as a hardfile, use +the "-W" option, for example + uae -W 32:1:2:hardfile +The first three numbers are geometry information which tell the AmigaOS how +the file is organized. The first number (32) is the number of sectors per +track, the second number (1) is the number of heads or surfaces, the third +number (2) is the number of reserved blocks. If you use "normal" sizes +(powers of two, like 32MB), then you should be OK using the same numbers as +in the above example. Using different numbers can make sense if you transfer +the image of a real Amiga harddisk which uses a different geometry. The last +field of the argument to the "-W" option is the name of the harddisk file. + +If you are using Kickstart 1.3 or earlier, hardfiles can't currently be +mounted at boot time, and therefore you can't boot from it either. You will +have to boot either from a floppy disk image or from a filesystem (see below), +and mount the hardfile.device later. To do this, add the following to +"DEVS:mountlist": -UAE0: Device = hardfile.device +UAE0: Device = uaehf.device Unit = 0 Flags = 0 Surfaces = 1 @@ -286,59 +345,74 @@ UAE0: Device = hardfile.device BufMemType = 1 # +(You may need to adjust the values if you specified a different geometry, +and/or your hardfile has a different size than 8MB, and/or the hardfile is not +mounted as UAE0: because you mounted other harddisks before it.) + Then, type "mount UAE0:" (or put that command in your startup-sequence), and you should be able to access it. Don't forget to format it with the AmigaDOS format command: format drive uae0: name Mister_Willwink -b) Access native filesystems from the emulator. +b) Accessing native filesystems from the emulator This has some major advantages: - It has no problems with Kickstart 1.3 - It is more convenient. - - It is much faster. In fact, it can be dramatically faster even than a real - Amiga when reading directories. + - It is much faster. -However, it currently does not work on some ports. - -If you specify the -M or -m command line arguments, you can use files on your -Unix filesystem from the emulator. If you start UAE with +If you specify the -M or -m command line arguments, you your native filesystem +from the emulator. If you start UAE with uae -m sound:/usr/amiga/modules - + you can access all the files in /usr/amiga/modules by reading from the AmigaDOS volume "SOUND:". (DOS users: try "uae -m dh0:C:\" to mount your drive C:\ as DH0:) -If you want to execute files, they need to have the x permission bit set. -That can be done in Unix by "chmod +x file" or in AmigaDOS with -"protect file rwed". -You can mount up to 20 devices by giving this option multiple times. +You can mount up to 20 devices, either hardfiles or filesystems, by giving +either of these options multiple times. The volumes will be named UAE0:, +UAE1:, etc. UAE will boot from UAE0: if no diskfile is found for floppy +drive 0. +You can also use native filesystems to mount Amiga CD-ROMs, and you can +abuse the hardfile emulation to mount floppy disks: "uae -W 11:2:2:wb13.adf" +will mount the diskfile "wb13.adf". Tools / Transferring files ========================== -To transfer any software between an Amiga and another computer, you'll need -either a tool like CrossDOS or MessyFS on the Amiga that lets you read and -write PC formatted disks, or a serial null-modem cable. CrossDOS is part of -the newer Amiga operating systems; MessyFS is free software and can probably -be found on some old Fish disk. To transfer data over a null-modem cable it is -useful to use some sort of terminal software on both ends. I can't explain -here in every detail how to use terminal programs or CrossDOS. Please read the -appropriate documentation. Note: If you use a tool to read/write PC-formatted -disks on the Amiga, remember that most Amiga drives handle only DD disks, so -don't try to use HD floppies. +As you should know by now, you need to transfer files between your Amiga and +the machine you run UAE on. There are several ways how to do this. -In the "amiga" subdirectory you'll find two small Amiga programs that you can -use to transfer software from the Amiga to the PC. These are called transrom +- Using a null modem cable, and a terminal package running on each machine, + you can transfer the file(s) via Zmodem upload/download. 68000 equipped + Amigas can normally attain around 3000cps through the null modem cable, + using the standard Commodore serial.device. However, by using the device + replacement BaudBandit.device, anything up to 5500cps can be attained. + BaudBandit can be obtained from Aminet. A second alternative is to use + the BASIC program adfi.bas (included with UAE) to transfer a file from the + Amiga to the PC via the null modem cable. + +- If you're using CrossDOS on your Amiga, you can compress the disk or + kickstart image using LhA or similar PC compatible archiver and copy it to + a 720KB floppy disk. You can now take the disk over to the PC, copy the + compressed file to the UAE directory and uncompress it. + If you don't have CrossDOS on the Amiga, there is a similar freeware tool + called Msh, which can be found on Aminet or on Fish disk 382 or 327. + +In either case, you ought to read the documentation for the programs that +you use for the transfer. These programs can't be explained here. + +In the "amiga" subdirectory you'll find two small Amiga programs that will +help you to generate the necessary image files. These are called transrom and transdisk. Copy them to your Amiga and make them executable (by typing -"protect transrom rwed" and "protect transdisk rwed" in the Amiga shell +"protect transrom rwed" and "protect transdisk rwed" in the Amiga shell window). transrom will dump the contents of your Kickstart ROM, and transdisk will dump an image of a floppy in one of the drives. Both programs write to the -standard output, so you'll want to redirect that. Do +standard output (read: the screen), so you'll want to redirect that. Do transrom >ram:kick.rom @@ -347,12 +421,22 @@ to create a file called "kick.rom" in th transdisk >ram:df0.adf to create a file called "df0.adf" in the RAM disk. These files are pretty -big, 524288 bytes for the ROM image and 901120 bytes for a disk image. +big, 262144 or 524288 bytes for the ROM image and 901120 bytes for a disk +image. + +NEVER run either of these programs from the Workbench. Always open a Shell +or CLI window to do this. + transdisk understands the following arguments: -d device unit: Use this device instead of DF0: - -s n: Begin transfer at track n (default: 0) - -e n: End transfer at track n (default: 79) + -s n: Begin transfer at track n (default: 0) + -e n: End transfer at track n (default: 79) + -w file: don't read from the floppy, instead write the contents + of "file" to the floppy + -h: Treat the disk as high-density disk. HD images aren't + supported by UAE yet, though. Note that the resulting + file will be twice as big. So, to transfer the disk in drive DF1:, you'd give the command: @@ -373,51 +457,26 @@ transferring the next one with transdisk If you have all the files on your PC, you can do the following under Unix: cat df0_1.adf df0_2.adf df0_3.adf df0_4.adf >df0.adf or, under DOS: - COPY /B df0_1.adf df0_2.adf df0_3.adf df0_4.adf df0.adf + COPY /B df0_1.adf+df0_2.adf+df0_3.adf+df0_4.adf df0.adf I've been told there are the following tools for the Mac to join binaries: "ChunkJoiner 2.1.2" found under Info-Mac's directory or "JoinFiles 1.0.1" under Info-Mac's . The current transdisk can only read the standard AmigaDOS format. This means that most games that rely on some form of copy-protection cannot be -transferred. However, there are disks that are formatted in the normal 880K -format that transdisk can read, but don't have a filesystem ("NDOS" disks -in the Workbench). These will be transferred correctly. - -There's an easy way to use a null-modem cable without terminal software if -you use Linux. You can do - - transdisk >SER: - -on the Amiga to copy the data directly to the serial port. Before that, do - - cat /dev/ttyS1 >df0.adf - -on your Linux box to receive the data (it may be ttyS0 on your system, or -another number, depending on which serial port you are using). When the Amiga -is done transferring, hit ^C on the PC to interrupt the cat program. To make -this work, you need to use the same settings for the serial port on both -sides. This is done with the Preferences program on the Amiga (this is split -into several programs from Kickstart 2.0 upwards, you'll find a program called -"serial" in the Prefs directory of your Workbench disk). On the Linux side, -use the stty program. "man stty" will give you the manpage describing how to -use it. -To be on the safe side, set the speed to a low value (2400 baud). Turn off -Xon/Xoff, but enable RTS/CTS. -I use the following command myself: - - stty 19200 parenb -cstopb cread clocal crtscts -istrip -inlcr -icrnl -opost - -onlcr -parodd -isig -icanon -iexten raw cs8 = 2.0.7 and version 2.5k of the mount program, you can do - mount df0.adf /mnt -t affs -o loop -You'll need to enable support for the Amiga filesystem and the loop device -when configuring and compiling the kernel. +emulator if you want to transfer files from FFS disks. + + +Picasso 96 graphics card emulation +================================== + +To use this feature, you must select 68020 emulation with a 32 bit address +space. You also need a Kickstart 3.x ROM. + +To specify how much graphic memory you want to emulate, use the "-U" option, +e.g. "-U 4" for 4 megabytes. Then, you need the Picasso 96 software which +is not distributed with UAE (There will be a link to the Picasso 96 home page +on the UAE Web page soon). Version 1.31 or higher is recommended. +Install the Picasso software, and make sure you enable the "uaegfx" driver. +After that is complete, reboot, and you should be able to select the new +modes from the ScreenModes program. - The UAE_CONTROL program ======================= @@ -448,25 +517,11 @@ with Kick 2.0 and upwards. Copy these tw use for harddisk emulation. They should be self-explanatory. -Printing -======== - -With the "-p cmd" option, you can specify a command that will be run when the -emulator detects that the Amiga accesses the parallel port. Usually, you will -want to say "-p lpr" to pass the output over to lpd. It's unclear how this -will work on non-Unix systems, DOS users can try "-p LPT1:" or something like -this. -For best results, select the PostScript driver in the Amiga Preferences. This -is only available in newer Kickstarts. Printing is not going to work with -another printer driver. -None of this is guaranteed to work yet, and I have not tried any of this yet. - - Quick overview of the debugger commands ======================================= -If you use the X11 version, you can press ^C at any time to enter the built-in -MC68000 debugger. +Some (window-system based) ports of UAE have a built-in debugger. You can +press ^C at any time to enter this debugger. Each debugger command consists of a single letter and occasionally some parameters. @@ -479,41 +534,20 @@ t: Step one instructi z: Step through one instruction - useful for JSR, DBRA etc. f
: Step forward until PC ==
q: Quit the emulator. You don't want to use this command. - -(^C has no effect if UAE is compiled for SVGAlib - use F12 to exit) - - -Input devices -============= - -Mouse, keyboard and joystick can be used in a straightforward way. A couple of -keyboard languages are supported with the "-l" commandline option. If you have -a different keyboard, patches to make UAE work with it are appreciated. -The X version of the emulator will try to keep the Amiga mouse pointer at the -same location as the X mouse pointer. You can turn off this mode if it does -not work with your program by pressing F12. This is needed (for example) for -Lemmings and the Magnetic Scrolls adventures, which don't use sprite 0 as a -mouse pointer. Other versions (SVGAlib, DOS, possibly others) do not have this -problem. -If you use Linux and have the joystick driver kernel module, "configure" -should automatically enable support for it. UAE calibrates the joystick -automatically. Turn it a few times on startup to get the calibration done. +M: hunt for sound modules +S
: + save a sound module Sound ===== -If you define LINUX_SOUND in config.h, the emulator will use /dev/dsp to -output sound. You can pass parameters like frequency or number of bits to use -on the commandline; if you don't specify any, sane defaults will be used. If -graphics output is enabled while sound is output, the emulator will be much -too slow on most systems. The sound will not be continuous. Therefore, a hack -to turn off screen updates is provided: Press ScrollLock to disable graphics, -press it again to enable them (note: for X, you'll have to press it twice each -time). -The LINUX_SOUND_SLOW_MACHINE option will steal cycles from the CPU emulator. -The relative CPU speed will be reduced somewhat if this option is set. This may -lead to incompatibilities. +If your version of UAE supports sound, you can pass parameters like frequency +or number of bits to use on the commandline; if you don't specify any, sane +defaults will be used. If graphics output is enabled while sound is output, +the emulator will be much too slow on most systems. The sound will not be +continuous. Therefore, a hack to turn off screen updates is provided: Press +ScrollLock to disable graphics, press it again to enable them. The quality of the emulation depends on the setting of the "-S" commandline option. With "-S 3", all of the sound hardware is emulated; and some programs @@ -522,52 +556,39 @@ option. With "-S 3", all of the sound ha of the sound hardware, but doesn't actually output sound. "-S 0" completely turns off sound. -On other Unix systems, the AF sound system may be available. You can configure -UAE to use this, too, by changing some paths in the Makefile (I can't answer -any questions about this, I never saw/used it). +Pointers +======== -Speed -===== +There are a few sites in the Internet that contain helpful information about +UAE. + +The new "official" UAE page is located at -The Most Frequently Asked Question is: "Just how fast is it?", and this is -also the most difficult one to answer. The easy way to answer is "It depends", -but I'll try to do better. All timings I give here were measured on my -machine, a P90 (using SVGAlib, with all the x86 assembly options turned on). -The MC68000 emulation is more than twice as fast as a real A500. I measured -this by letting PowerPacker try to compress itself (it already was compressed). -It took UAE about 6 minutes, my A500 took about 15. If you set the frame rate -to a high value (i.e. leaving out many frames), the graphics speed does not -matter and you get about twice the speed of an A500. If you enable the smart -update method in config.h, and if it works for your program (it works for -almost all programs using the Workbench) you also get about the same speed at -full frame rate. -For games and demos, the CPU speed does not matter, but the average frame time -is important. UAE can calculate this automatically. The SVGAlib version gives -the number when you exit the emulator, to obtain the value with the X version -you need to interrupt it and type "c" in the debugger. A real A500 has a -constant frame time of 20ms (50 Hz). -If you have a game/demo that has lots of blitter activity, many copper/sprite -effects, dual playfields and scrolling, no one can help you. Fortunately, this -case is extremely rare. Normal games that have a number of blitter objects, -scrolling and maybe some sprites run at 1/3-1/4 the speed of an A500 in the -worst case, some run at 1/2 the speed. Lowering the frame rate helps -enormously here, and at 1/5 frame rate, about everything runs somewhere -between 50% and 100% the speed of an A500. -This still isn't the full story (I bet you start to see why the question is -hard to answer). A real A500 without fast memory gets slowed down to about -half its speed in Hires 16 color mode. More bitplanes also slow UAE down, but -not quite as much, so it can be several times faster than an A500 in that -mode. - - -Bugs / Unimplemented features -============================= - -The sprite emulation is incomplete and buggy. Sprite collisions are not -implemented yet. The serial port emulation doesn't seem to be useful yet. -Apart from that, UAE can do everything a real A500 can do (and more), but -there may still be one or two buglets that make some programs fail. +http://www.freiburg.linux.de/~uae + +thanks to Stefan Reinauer who is now maintaining it. + +There, you will find links to other UAE pages. One which is especially useful +is the "UAE Discussion Board" set up by Gustavo Goedert, the address is + +http://www.netrunner.com.br/dosuae/uaeboard/index.html + +Not quite as good as a newsgroup due to braindamaged reader software +(Ratscope), but still a blessing. + +There is supposedly a newsgroup named "alt.emulators.amiga", but I don't get +it here. +The newsgroup "comp.sys.amiga.emulations" appears to be a proper place to +discuss Amiga emulation, but, strictly speaking, it is _not_ the right place. +More appropriate places are "comp.emulators.misc", and, of course, Gustavo's +discussion board. + +Petter Schau has written another Amiga emulator named "Fellow". It's mostly +written in x86 assembly and only runs under DOS. It's quite compatible and +generally faster than UAE. The Fellow homepage is at + +http://www.geocities.com/SiliconValley/Peaks/5244/ Thanks & Acknowledgements @@ -587,71 +608,14 @@ Special thanks to: documentation - Fabio Ciucci gets the "Best bug reports" award for his help with the blitter line emulation and other problem areas. + - Michael C. Battilana and Cloanto Software, for all their support. + - Julian Eggebrecht of Factor 5, for providing several F5 games. -Ports -===== - -Apart from the "main" Unix version, several ports of UAE are ready/being -developed. - -Gustavo Goedert has ported UAE to DOS using the -DJGPP port of GCC. The binary is available on several ftp sites as well as on -my Web site. - -Ernesto Corvi has ported UAE to the Apple -Macintosh. He tells me it is available on Info-Mac, and that every Mac user -should know where that is. A link to the archive containing both PPC and 68k -binaries is on my Web page. (info-mac is mirrored by -sunsite.informatik.rwth-aachen.de) - -Christian Bauer has ported UAE to the -BeBox. - -Ian Stephenson has ported UAE to NextStep. - -Olaf 'Olsen' Barthel has ported UAE to the Amiga. This -port requires the AA chipset as well as Kickstart 3.0 or higher. CyberGraphX -is supported. Please read the file "amiga.c" for information. To compile it, -you need SAS/C and the 3.0 includes (they probably come with the compiler). - -Krister Bergman has ported UAE to the XFree86/OS2 -environment. This port can be obtained from Krister's WWW page: - - -Since I generally don't have the possibility to test or improve these ports, -it is a good idea to contact their respective authors if you have questions. - - -Pointers -======== - -There are a few sites in the Internet that contain helpful information about -UAE. - -I have set up a WEB page for UAE. You will find interim versions, Linux -binaries, diskfiles with Amiga software and other interesting stuff there. -The address is - -http://www-users.informatik.rwth-aachen.de/~crux/uae.html - -There, you will find links to other UAE pages. I'll add these links to this -document in the next version, but I don't have them here right now. - -I post announcements of new versions of UAE to the newsgroup -comp.emulators.misc. From time to time, I also upload new versions to the ftp -server sunsite.unc.edu. You will find them either in pub/Linux/Incoming or in -pub/Linux/system/Emulators. There are many sunsite mirrors throughout the -world, you should be able to find one near you. - +Authors/Maintainers +=================== -The author's address -==================== - -Before you contact me with a problem that you have, make sure you have read -_all_ of the above. Please read also the file "FAQ", which conains a lot of -helpful information. In the future, I will probably no longer respond to -questions that are already answered by any of these files. +My address is (please read the section "Before you send email" below): crux@pool.informatik.rwth-aachen.de @@ -664,16 +628,99 @@ Germany Email is more likely to be answered, and will definitely be answered much faster. Please avoid phonecalls if you can. +I won't distribute software, neither PD or commercial. Don't send me floppy +disks without at least asking first, you will not get them back. + +The following people have ported UAE to different platforms; you should +direct system-specific questions to them: + +DOS port: + Gustavo Goedert + Available: http://www.netrunner.com.br/dosuae + Sourecode: available on the above Web page, most of it included in the + main source (with some delay) + +Mac port: + Originally: Ernesto Corvi + Currently: Arnaud Blanchard + Available: http://www.pratique.fr/~jblancha/ + Sourcecode: extra package available. Bits and pieces in the main source, + but nothing you could get to compile. + +BeBox port: + Christian Bauer + Available: The main UAE web page (use the Unix sources) + Sourcecode: Included in the main source. Should compile OK. + Notes: Christian says he doesn't have much time to spend on UAE, so if + anyone is willing to help maintain this port, please speak up. + +NextStep port: + Ian Stephenson + Available: The main UAE web page (use the Unix sources) + Sourcecode: Included in the main source. Should compile OK. + Notes: Ian says he doesn't have much time to spend on UAE, so if + anyone is willing to help maintain this port, please speak up. + +Amiga port: + Originally: Olaf 'Olsen' Barthel + Currently: Samuel Devulder + Available: Not quite sure yet. Paul Liss' Web page has binaries. + Sourcecode: Included in the main source. Should compile OK. + +pOS port: + Samuel Devulder + Available: Not quite sure yet. + Sourcecode: Included in the main source. Should compile OK. + +XFree86/OS2 port: + Krister Bergman + Available: http://www.kuai.se/~bellman/html/xfreeapps.html + Sourcecode: nothing special, apparently the Unix stuff compiles cleanly (?) + +Win32 port: + Mathias Ortmann + Brian King + Available: http://www.informatik.tu-muenchen.de/~ortmann + http://www.codepoet.com/uae + Sourcecode: we're working on it + +Acorn RISC PC port: + Peter Teichmann + Available: http://www.wh1.tu-dresden.de/~sol/acorn.shtml + http://www.wh1.tu-dresden.de/~sol/acorne.shtml + Sourcecode: Some of it is included in the main source, but since Acorn's OS + apparently doesn't have decent file handling, you can't even + use the same source layout. Also needs lots of additional files. + +Since I generally don't have the possibility to test or improve these ports, +it is a good idea to contact their respective authors if you have questions. + + +Before you send email... +======================== + +Before you contact me with a problem that you have, make sure you have read +_all_ of the above. Please read also the file "FAQ", which contains a lot of +helpful information, and the README file for your specific system. + I can't answer _every_ question. If you have trouble understanding this README, either because you don't speak English very well or because you have -no clue at all about computers, please try to find someone near you who does -understand this file and who can translate/explain it for you. I simply can't -explain (for example) how to use terminal programs or CrossDOS because I don't -use either, and it would be much too time-consuming anyway. This file and the -file FAQ contains about every piece of information I can give you. I try to -help people who have questions, but sometimes it takes too much time. +no clue at all about computers, please try to find some friend of yours who +does understand this file and who can translate/explain it for you. I simply +can't explain (for example) how to use terminal programs or CrossDOS because +I don't use either, and it would be much too time-consuming anyway. This file +and the file FAQ contains about every piece of information I can give you. I +try to help people who have questions, but sometimes it takes too much time. + +Please don't ask for Kickstart ROM files or other copyrighted software. Don't +_send_ me stuff like this either. If you want to send me something else which +is big (>= 50K), ask me before or put it somewhere in Webspace. +If I get 3MB of screen shots or a core dump ("it doesn't work, it generates +this file"), I'm very likely to get extremely angry, I might complain to your +sysadmin, and you might lose your account. Think twice. -Please don't ask for Kickstart ROM files. +I'm also going to be extremely annoyed if you send email in HTML format. +Fight this disease! Oh, and another thing: If I promise to do things (like implement new features), and forget about them, pester me. That happens occasionally, it's