--- uae/docs/README 2018/04/24 16:44:33 1.1.1.7 +++ uae/docs/README 2018/04/24 17:08:43 1.1.1.22 @@ -1,8 +1,7 @@ -This is version 0.8.7 of UAE, the Un*x Amiga Emulator. +This is version 0.8.22 of UAE, the UAE Amiga Emulator. -Versions numbered 0.8.x are beta versions, to be used for development only. -If you are only a user of UAE, you are better off using the latest 0.7.x -version or waiting for 0.9.0. +Versions numbered 0.8.x are considered beta versions, but they generally +tend to work better than the last "stable" release 0.7. License @@ -29,10 +28,10 @@ display, keyboard, harddisk and mouse ta counterparts. UAE was developed for Unixoid systems. Meanwhile, it has been ported to the -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. +Mac, DOS, Windows, 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. UAE has many, many features and @@ -85,8 +84,7 @@ Not emulated: 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 (someone tell me when - that's no longer true, I don't use it). +- 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 @@ -157,30 +155,52 @@ autoconfig=bool [default=yes] kbd_lang=lang [default=us] Set the keyboard language. Currently, the following values can be used: "us" for U.S. keyboard (default), "se" for swedish, "fr" for french, "it" for - italian, "es" for spanish, or "de" for german keyboard. + italian, "es" for spanish, "dk" for danish, or "de" for german keyboard. This setting only affects the X11 version. floppy0=file [default=df0.adf] Try to use the specified file as diskfile for drive 0 instead of df0.adf. The options floppy1, floppy2, and floppy3 also exist. kickstart_rom_file=file [default=kick.rom] Use the specified file instead of kick.rom as Kickstart image. + You can also use an 8k sized A1000 boot ROM. The emulator will detect it + by its small size and behave like an A1000. +kickstart_key_file=file [default=none] + For some strange licensing reasons, Cloanto had to encrypt the ROM images + they ship with the Amiga Forever package. This option lets you select the + key file; this is only necessary if you are using one of the ROMs from + Amiga Forever. joyport0=mode [default=mouse] Specify how to emulate joystick port 0. You can use "mouse", "joy0", or "joy1" to use the corresponding input devices of your machine, or you can - select several different keyboard replacements for a joystick: "kbd1" for - the numeric pad with '0' as fire button, "kbd2" for the cursor keys with - right control as fire button and c is T/F/H/B with Alt as fire button. + select several different keyboard replacements for a joystick: + "kbd1" for the numeric pad. '0' is the fire button. Three keys on the + numeric pad act as autofire toggle: '.' (or ',' depending on your + keyboard language), Enter and the division key. + "kbd2" for the cursor keys with right control key as fire button and the + right shift key as autofire toggle + "kbd3" for T/F/H/B with the left Alt key as fire button and the left Shift + key as autofire toggle. + The autofire toggle keys will turn on autofire (25 shots per second), it + will stay enabled until you hit the autofire toggle again. joyport1=mode [default=joy0] Like joyport0, but for the Amiga's joystick port 1. -use_gui=bool [default=yes] - Show a user-interface that enables changing these options at run-time. -32bit_blits=bool [default=no] - If enabled, the blitter emulation will use 32 bit operations where that - seems profitable (note that this will cause bus errors on most RISC - machines) +use_gui=state [default=yes] + If enabled, show a user-interface that enables changing these options at + run-time. Possible settings are "no", "yes" and "nowait". If "nowait" is + used, the GUI will be shown at program startup, but the emulator will also + start immediately without waiting for the user to change any of the + settings. immediate_blits=bool [default=no] If enabled, all blits will finish immediately, which can be nice for speed, but may cause incompatibilities. +collision_level=level [default=sprites] + This can have a value of "none", "sprites", "playfields", or "full". If + set to "sprites", the emulator will only compute collisions between sprites. + If set to "playfields", it will additionally compute collisions between + sprites and the background. This is much slower and used only rarely. When + "full" level is selected, collisions of the background with itself are also + computed. This is also used very rarely, and makes the emulator even slower. + Using "sprites" or "none" will almost always be enough. cpu_speed=speed [default=4] This can have a value of "real", "max", or an integer between 1 and 20. "real" will try to give the CPU emulation exactly as many cycles, relative @@ -189,6 +209,12 @@ cpu_speed=speed [default=4] specify a fixed relation between CPU and custom chip emulation, where lower values prioritize CPU emulation, while higher values prioritize custom chip emulation. +finegrain_cpu_speed=speed + Like cpu_speed, but only accepts numeric values. These numeric values are + equivalent to the ones given to cpu_speed multiplied by 512. This means + that "cpu_speed=2" and "finegrain_cpu_speed=1024" have the same effect. + Using this option you can give the CPU emulation a much higher priority by + using small values. cpu_type=type [default=68000] Controls which CPU is emulated. This can be "68000", "68010", "68020" or "68020/68881". In some cases, you may need to use "68ec020" or @@ -202,6 +228,10 @@ cpu_compatible=bool [default=no] If enabled, a slower but slightly more accurate variant of the CPU emulation will be used. This is needed for some types of copy protection, among other things. This is only meaningful for a CPU type of "68000". +nr_floppies=n [default=4] + The emulator will emulate this many external floppy drives. Some very old + games apparently have problems if this is larger than 1, but for all normal + programs the default is good enough. Emulating external devices (harddisk, CD-ROM, printer, serial port): filesystem=access,volume:path [default=no filesystems mounted] @@ -225,7 +255,14 @@ sound_output=type [default=none] slightly more accurate emulation that may be necessary in some cases, but can also be slower). sound_channels=type [default=mono] - Can be "mono" or "stereo". + Can be "mono", "stereo", or "mixed". If set to "stereo", the left and right + channels produce the same output as on a real Amiga - two of the four audio + channels are audible on the left, and the other two on the right. This is + exactly what you want, except if you're using headphones - having the sound + split so strictly can lead to a strange listening experience at times. This + is what "mixed" is trying to solve: it mixes the left channel with a low + volume into the right channel and vice versa. (This mixing operation loses + a bit of precision in the output). sound_bits=n [default varies across UAE versions on different OS types] Common values are 8 (low quality) or 16 (high quality) sound_frequency=n [default varies across UAE versions on different OS types] @@ -235,6 +272,17 @@ sound_min_buff=n sound_max_buff=n [default varies across UAE versions on different OS types] You can specify the minimum and maximum size of the sound buffer. Smaller buffers reduce latency. Usually only the minimum size is used. +sound_interpol=type [default none] + Normally, sound samples are output exactly as they are computed, without + any post-processing. This can generate errors in the sound output when the + output frequency isn't an even multiple of the input frequency. These + errors are usuable perceived as a high-frequency noise. + There are currently two types of interpolation available, both under + experimentation. You can use either "rh" or "crux" as value for this + option. Note that no interpolation is supported for 8 bit output; you need + to use 16 bit output to hear a difference. If you have any comments about + the effects of either method on audio quality, I'd be very interested to + hear them. Memory options: bogomem_size=n [default=0] @@ -256,7 +304,7 @@ gfx_height=n [default=300] gfx_lores=bool [default=no] Enable this option if you use a very small window width (320 to 400 pixels) to shrink the display horizontally. -gfx_linemode=type [default=none] +gfx_linemode=type [default=scanlines] The type can be none (every line is drawn once), "double" (every line is drawn twice), and "scanlines" (every line is drawn once, but the image is stretched vertically by inserting a black line every other line to simulate @@ -287,7 +335,7 @@ gfx_color_mode=mode [default=8bit] Color modes: 8bit (256 colors), 15bit (32768 colors), 16bit (65536 colors), 8bit_dithered (256 colors, with dithering to improve quality), 4bit_dithered (16 colors, dithered); 32bit (16 million colors) -gxfcard_size=n [default=0] +gfxcard_size=n [default=0] Emulate a Picasso 96 compatible graphics card with n MB graphics memory. This requires that you use set the CPU type to "68020" or higher, and that you do not use 24 bit addressing. @@ -483,7 +531,7 @@ If you don't have much RAM and can't fit you can split up the transfer into multiple parts with the "-s" and "-e" parameters. To transfer the disk in four parts, you'd use the following commands: - + transdisk >ram:df0_1.adf -s 0 -e 19 transdisk >ram:df0_2.adf -s 20 -e 39 transdisk >ram:df0_3.adf -s 40 -e 59 @@ -532,7 +580,7 @@ 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. +space (i.e. _not_ 68ec020). 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 @@ -543,6 +591,84 @@ After that is complete, reboot, and you modes from the ScreenModes program. +AHI sound card emulation +======================== + +In the "amiga" subdirectory of the UAE distribution, you will find a "Devs" +directory that contains the necessary files for AHI sound support. This is +at an early stage and will not work very well in this release. It is +included mainly in the hope that someone with a clue about AHI will pick up +this work and finish it properly. + + +Saving and restoring snapshots +============================== + +From version 0.8.17 onwards, the emulator has the capability to save the +current state of the emulation into a "snapshot" file that can be restored +later on. This functionality is available through the GUI on some ports. +It is mainly useful for computer games that either have no save game +feature, or whose save game feature does not work on UAE (often, games try +to save in a non-standard disk format, this can be tricky to emulate). + +There are several restrictions that apply to the save state feature: + + - It is at the moment experimental. It is not guaranteed that the + emulator can correctly restore every snapshot. It is not guaranteed + that future versions of the emulator will be able to restore snapshots + saved by this version. + - The state of the harddisk emulation cannot be saved. This makes it + essentially useless for applications, but remember it's designed for + games. Be careful with games that have been installed to the harddisk. + - Neither ROM contents nor floppy disk contents are saved right now. + + +UAE SCSI device +=============== + +To enable SCSI support, use --enable-scsi-device when running configure. +The emulator provides a uaescsi.device. This device only supports +direct SCSI, which is sufficient to run applications like MakeCD. The +device does not support reading or writing with the normal Exec commands, +so you cannot mount filesystems on it right now. + +The unit numbers of the uaescsi.device follow the Amiga SCSI +conventions: unit number "xyz" maps to the lun y of target z on bus +x. Wide SCSI busses can have targets with numbers larger than 9. In +this case the uaescsi.device pretends that there is another SCSI +bus. To avoid confusion, all available SCSI targets are listed +together with their unit number when starting UAE. Devices cannot be +added while the emulator is running. Reseting it is not sufficient +either for technical reasons. + +The implementation of the uaescsi.device uses cdrecord's libscg as +interface to the native SCSI system. The Linux implementation of this +library used to be included into UAE, but now the library as generated +by the cdrecord source package (ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/) +is used. As the library is not distributed seperately, you will have +to get the whole cdrecord sources, compile it and then make several +header and lib files available to the compiler if (and only if) building +UAE with SCSI support. The script "src/install_libscg" copies the files +required for the libscg in cdrecord 1.8.1. + +Using threads is strongly recommended, because some SCSI commands can +run for extended periods of time and would block the whole emulation +during this time without threads. Use --enable-threads when starting +configure. + +Depending on the hosts capabilities the uaescsi.device may be limited +compared to other Amiga SCSI devices. The Linux kernel by default only +allows 32KB of data per SCSI command and does not always perform SCSI +requests in parallel. + +Setting the chunk size in MakeCD to 30KB is already too much and +causes an IO error -4 (IOERR_BADLENGTH), because the setting is only +used as a guideline. You can work around this by setting the Tooltypes +BUFFER_CHUNK_XXX to 29. On a Pentium II 350MHz with Adaptec UW SCSI +controller on board on-the-fly copying was possible from a Philips +CDD2600 (SCSI) to a Yamaha CRW4416E (IDE) at 4x. + + The UAE_CONTROL program ======================= @@ -554,6 +680,15 @@ with Kick 2.0 and upwards. Copy these tw use for harddisk emulation. They should be self-explanatory. +The timehack +============ + +Another tool in the "amiga" subdirectory, timehack, synchronizes the +emulated Amiga's system time with the host's time every second. This +is useful when the emulation is not done in real-time or is suspended +completely. + + Quick overview of the debugger commands ======================================= @@ -604,17 +739,14 @@ UAE. The new "official" UAE page is located at -http://www.freiburg.linux.de/~uae + 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. + http://amiga.nvg.org/uaeboard There is supposedly a newsgroup named "alt.emulators.amiga", but I don't get it here. @@ -627,7 +759,12 @@ Petter Schau has written another Amiga e 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/ + http://www.geocities.com/SiliconValley/Peaks/5244/ + +The homepage of the Disk2FDI project, which allows you to read Amiga floppies +if you have two PC drives, is + + http://fast.emuunlim.com/disk2fdi/ Thanks & Acknowledgements @@ -652,26 +789,35 @@ Special thanks to: - Michael C. Battilana and Cloanto Software, for all their support. - Julian Eggebrecht of Factor 5, for providing several F5 games and a lot of valuable input. - Factor 5 has made Katakis, one of their classic Amiga games, freely + Factor 5 has made several of their classic Amiga games freely available for download. There are still some good people left in the world... - Jens Schönfeld, inventor of the Catweasel controller, donated one controller card. + - Jürgen Beck and Ralf Steines, maintainers of the Amiga emulation web + site "Back to the Roots" (http://www.back2roots.org) and everyone else + who spends time writing to software companies asking for permission to + distribute old Amiga games. + - all the software companies who allow distribution of their Amiga games on + sites like "Back to the Roots". Authors/Maintainers =================== -My address is (please read the section "Before you send email" below): +My email address is (please read the section "Before you send email" below): + +bernds@btinternet.com -crux@pool.informatik.rwth-aachen.de +(please do not put this into your Outlook addressbook; I get enough viruses +already) or, via snailmail Bernd Schmidt -Schlossweiherstrasse 14 -52072 Aachen -Germany +21 St Stephen's Place +Cambridge CB3 0JE +UK Email is more likely to be answered, and will definitely be answered much faster. Please avoid phonecalls if you can. @@ -719,6 +865,11 @@ pOS port: Available: Not quite sure yet. Sourcecode: Included in the main source. Should compile OK. +OS/2 port: + Pressenna Sockalingasamy + Available: ftp://hobbes.nmsu.edu/pub/os2/apps/emulator/uae2_0810_a1.zip + Sourcecode: working on including it + XFree86/OS2 port: Krister Bergman Available: http://www.kuai.se/~bellman/html/xfreeapps.html @@ -760,14 +911,8 @@ and the file FAQ contains about every pi 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. - -I'm also going to be extremely annoyed if you send email in HTML format. -Fight this disease! +_send_ me stuff like this either. Don't send large attachments, at least not +without asking first. 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