Amiga SPectrum emulator ======================= V0.75 ===== (c) Ian Greenway 1999,2000 Introduction: ------------- This is a Sinclair ZX Spectrum 48K/128K emulator for Amiga computers. ASp is a very easy program to use, but there are a couple of points to be aware of. Please read at least the "Requirements" section of this ReadMe. If you have used ASp before, take a look at the "Changes Since Last Version" section to aquaint yourself quickly. Features: --------- - System compliant, fully multitasking. - Font sensitive Gadtools GUI. - Small, easy to use, authentic emulation of a 48K/128K Sinclair Spectrum. - Comprehensive speed-regulated Z80 CPU emulation core which includes all undocumented instructions and most undocumented flag behaviour. - Genuine Spectrum-like display with support for BRIGHT and clean FLASH. - Stabilised stereo sound (48K and AY-3-8912) synched to CPU T-states. - Direct joystick support via normal Amiga gameport. See http://www.greew.freeserve.co.uk/ASp.html for latest info and updates. Changes Since Last Version: --------------------------- Significant (15-20%) speed increase for 68030 machines! Added rudimentary ARexx port. Added various types of joystick, including user-defined keys. Made Kempston joystick more compatible. Now adapts to correct T-States per frame for 48K and 128K modes. Changed the context of the 48K/128K hardware options for correctness. Audio build code optimised (again!) Added optional lower quality, but faster, audio build. Added BLANKPOINTER tooltype to blank the mouse pointer on System Screen. Multiple menu selections now work. It is now possible to load a Z80 file of exactly 49179 bytes. (Oops!) Various minor corrections and enhancements to emulation accuracy. Requirements: ------------- As an absolute minimum you need a 68020 and WB3.0 (V39). Native chipset, OCS/ECS/AGA, is required. Gfx cards not supported yet. About 800Kb fast ram, 100Kb chip ram. *IMPORTANT:* You absolutely NEED V41 or above of mmu.library by Thomas Richter, for which you will require a working MMU. NOTE! :- mmu.library V42 or better is recommended for extra speed. See General Info section. You also need the Spectrum128K ROM Image File (32Kb in size). If it was not in this archive, you can download it from various places on the internet, including the ASp support page. (See below). To get any sort of realistic performance you will need at least a very fast 68030. A 50MHz 68030 now runs BASIC at almost the speed of a real Spectrum. Faster machines will automatically regulate their speed so they run the same speed as a real Spectrum. Any spare CPU time is available for other tasks in the Amiga system. Installation: ------------- Just copy ASp and the ROM file to any directory you want. You can run ASp from the Shell or the Workbench. You do not need to install the entire of Thomas Richter's MuTools for ASp to work. It is sufficient to simply put "mmu.library" in LIBS:. It is well worth looking at the rest of the package though, as it is extremely comprehensive. How To Use: ----------- If no GUI appears, there has been some serious initialisation error. Check you have enough RAM and all system libraries installed. Note you need a full WB3.0+ (V39+) system. The GUI contains various (hopefully) self-explanatory gadgets and equivalent menu items: RUN / STOP / RESET: These start or stop the emulation. Reset will perform a power-on reset of the virtual Spectrum. LOAD / RELOAD / SAVE: These allow you to load or save the status of the emulation with "snapshot" files. Supported formats are .Z80 (loads all versions, saves V2+ type) and .SNA (also called Mirage, suitable only for 48K mode). ReLoad will instantly reset the emulation to the state it was after the last successful Load, without having to display the filerequester. INSERT / EJECT / REWIND: You can insert or eject a .TAP (tape) file in your virtual tape-deck. This is accessed when the Spectrum tries to LOAD from tape. Rewind will set the tape to its beginning without having to reselect it in a filerequester. Settings Menu: You can select some options which affect the behaviour of the emulation: Hardware: -128K mode: Selects between an emulation of a 48K or 128K Spectrum, including all CPU timings and hardware. Loading a snapshot will cause this menu item to change to reflect the current mode of operation. Note! Unlike earlier versions of ASp, this function has an IMMEDIATE effect - changing the mode of a running program is likely to cause the Spectrum to crash. -Always Reset to 128K: Normally, the Reset function will reset whatever machine type is selected by the "128K mode" option. With this item selected, Reset will always force the emulation to 128K mode. -Add AY chip to 48K model: A normal 48K Spectrum does not have an AY sound chip. If you select this mode, the AY chip will be available to the 48K Spectrum. Note that a 128K Spectrum in "48K mode" has an AY chip anyway. This option is only significant when "128K Mode" is deselected. Display Type: -AGA Custom CList: Select the faster, but less system-friendly AGA-only display. You cannot perform normal Amiga screen operations, but multitasking is maintained. -OCS System Screen: Select the slower 16-colour system screen option. You can drag and flip this display as with any other Amiga system screen. Joystick: Select your preferred joystick type. If you select Custom Keys then you can "Define..." the keys to use: -Define...: Creates a small window in which you can Change or Accept the current keys which correspond to Up, Down, Left, Right and Fire on the stick. Only keys which correspond to something useful on the Spectrum are accepted. Keys which translate to multiple (ie: shifted) keypresses will behave as if only the shift key were pressed. Sound: -Mono: ASp will only try to allocate one audio channel and mix all sounds into it. -Stereo ABC: ASp will try to allocate two audio chanels as a stereo pair. Any AY-chip sounds will be played as Left, Middle, Right for the A, B and C channels repsectively. 48K sound is played as middle. -Stereo ACB: As Stereo ABC, except channel C is played as middle and channel B is Right. -Sample Rates (Lo, Med, Hi): Adjusts the time required to build the audio output by changing the effective sample rate. It is reccommended to use "Hi" where possible as the quality in slower modes can be rather poor due to aliasing distortion. (May be improved in a later version.) Due to some mathematical limitations, the 128K mode "Hi" sample rate is marginally slower than in the 48K mode. -Quiet 48K beeps: A real 128K Spectrum will have the 48K "beeper" set just as loud as all the AY sound chip channels put together. This mode allows it to be quieter, the same as a single AY channel, as in previous versions. You can use any of the Amiga-key menu shortcuts as well as the menu items themselves, or the GUI buttons. In addition, the following keys are provided: F1 - Load F3 - Save F6 - ReLoad F10 - Reset Esc - Stop All the letter and number keys correspond to the equivalent key positions on a Spectrum. Cursors, backspace and several symbol keys are functional as shortcuts. The Alt keys represent Symbol Shift. All other combinations operate as a normal Spectrum. Eg: Shift-1 is EDIT, Shift-2 is CAPS, etc. Note, A1200 and some PC-adapter keyboards do not work well with multiple simultaneous keypresses. This is a limitation of the keyboard controller, not of ASp. Genral Info: ------------ The following information provides some details and extra information about the features of ASp. You do not need to read this to successfully use ASp, but there may be something here if you run into a problem. MMU.library: The MuTools archive and the mmu.library are by Thomas Richter. ASp only requires the "mmu.library" to be copied to your system "LIBS:" directory for it to actually work. For optimum system performance it may be necessary to perform a more thorough install of this comprehensive package. ASp requires at least V41 of mmu.library. There are new features in V42 which will significantly improve ASp's 128K paging performance, so you are reccommended to install the latest version. About the 128K Operation: The 128K memory paging is done via Thomas Richter's mmu.library. This means that ASp should work on any system 68020-68060 which has a fully working MMU. It does, however mean that systems without an MMU can no longer run ASp. Hopefully, a future version will drop back to 48K mode if no MMU is available, but for now, this one will not run. Use ASp V0.71b for a 48K-only emulation. If a program attempts to change the memory paging very often (several thousand times per second) ASp may slow down below "real" speed. As of V0.74 the paging speed has been improved by a factor of five with V41 of mmu.library. If you use V42 mmu.library, it is three times better again. ie: Fifteen times faster than previous ASp releases. (Figures relate to a 68060 CPU). The 128K Spectrum has a "shadow screen". This is emulated, but is not yet synchronised with display updates. Any programs switching between shadow and normal screens very rapidly may get flickering or glitching graphics. This is harmless, but can look untidy. As of V0.75, ASp will use the correct 128K CPU timings (70908 T states per frame, 3.5469MHz) in 128K mode, and the 48K timings (69888 T states per frame, 3.500MHz) when in 48K mode. Note that loading a snapshot which was saved in a particular mode will force ASp into that mode. All SNA files are regarded as 48K mode, the Z80 files have this info embedded in them. File Formats: ASp will load and save Z80 and SNA files. These are the most popular formats found for snapshots. The SNA, or Mirage, format is suitable only for 48K-type information. The Z80 loader will load any Z80 file, but will save Version 2 files in either 48K or 128K mode as appropriate. ASp will try to guess which format you wish to Save by examining your chosen file-extension (".z80" or ".sna") If it can't decide it will ask. When loading files, ASp auto-detects which format to use. In most cases it is advisable to use the Z80 file format as it is both more flexible and produces smaller filesizes. ASp does not yet directly support externally crunched data files, such as the PowerPacked files that ZXAM produces. You can use some third party transparent file decruncher utility to load such files if you wish. TAP files have only limited support at the moment. Only Loading is allowed, saving will have no effect. The TAP loader patches into the Spectrum's ROM and tries to catch any calls to load information from tape. This means that only programs which use the ROM routines will work with the TAP loader. Note: The SNA format supported here is the 48K one, not the extended 128K one. The TAP files are the type used by Gerton Lunter's Z80, not the Warejevo type. SLT files (extended Z80 files) will be loaded, but the additional level data will not be used. Display Options: The Amiga has some comprehensive display hardware which can be programmed to provide a video display that requires considerably less decode overheads than a conventional display for this application. Unfortunately it is very difficult, if not impossible, to persuade the Amiga OS to provide this level of display hardware flexibility. This means ASp "takes over" the display in this mode. For the purists who don't like the sound of that, there is a 100% system- friendly screen option. It requires up to 8 times longer to update the display so may cause a slowdown under some circumstances especially on slower machines. In most applications however, it is fine. Despite the AGA display being system "unfriendly", it is still entirely system compliant according to the official documentation. Neither multitasking nor interrupts are affected and all the rest of the program continues to operate in the normal system-friendly way. It is not advisable to run programs in the background that need prompt attention, or which themselves may take over the display hardware if you use the AGA Custom option. Neither mode supports border colour stripes. The border colour is updated once per displayed frame only. About the Sound: The basic model of emulation is for a 128K Spectrum. This includes the AY sound chip found in those machines. I believe the emulation of this chip to be the most accurate of any current Amiga emulator. Noise, tones, gating, enveloping and "4-bit-sample" mode all work correctly. In normal use the 3 AY channels are played as stereo left, centre and right, with the 48K sound mixed in as centre. In Mono mode all the sound, AY or otherwise, is mixed into one Amiga audio channel. Mono mode allows you to run ASp when the number of available audio channels is limited, or if you wish to run more than two copies at once. Mono also provides a very slightly faster sound build than stereo. In 48K mode, deselecting "Add AY chip to 48K model" will cause ASp to use a much faster audio build system which may be significant on slower machines. This also forces programs which auto-detect whether to use AY or 48K sound to use the latter. Remember that this only works for 48K mode - the AY chip is always available in 128K mode. The ASp code directly accesses the sound hardware. This is only done after correctly allocating the channel and interrupts in the system-approved way. This is the only way I can persuade it to work properly, it should cause no problems in a system compliant environment. About running multiple copies of ASp: As of V0.70 it is possible to run as many copies of ASp as you want, limited only by system memory. Every time you ask a copy to RUN the emulation, it will try to allocate audio channel(s). ASp will try to steal the channels even if they are in use by another program, but can still be blocked. So you have a theoretical maximum of four available audio channels allowing a maximum of four emulations running simulataneously (in mono mode). Of course, whether they will all run at top speed or with clean sound is another thing altogether. :-) A fast 68060 will usually manage three simultaneously. About the ToolTypes: You can add tooltypes to ASp's icon which will be read on startup. It doesn't matter whether it's started from the WB or CLI. LOADPATH is the directory the Load and Insert file requester will initially open at. Default is nothing, which is the directory from which ASp was run. SAVEPATH is the directory the Save file requester will initially use. Default is "RAM:". ROMFILE is the directory and filename of the ROM file you want to use. This file must be exactly 32768 bytes long. If it isn't a real ROM you will find strange things happen! Defaults to "PROGDIR:Spectrum128.rom". BLANKPOINTER, if present, will cause the mousepointer to disappear when the OCS System Screen is in use. About the ARexx Port: As of V0.75 ASp implements an ARexx port. Currently there is only a limited selection of commands. The port name is "ASP_0" for the first copy, "ASP_1" for the second, etc. A new copy will always create the lowest-numbered possible port name. "LOAD " Arguments: is an optional full file name of a snapshot to Load. If not specified, the Load File requester will be opened. Returns: OK if file loaded ok. ERROR if user cancelled filereqester. FAIL if could not load file for any reason. "POKE " Arguments: is a Spectrum address in the range 0-65535. is the byte value to put in that address. 0-255. You cannot overwrite ROM addresses with POKE. All changes take place immediately, even if the emulation is running. There is a (slight) potential for a race condition if the emulation is running which may cause the display to be incorrect. The internal data is always correct however, so no damage is done. Returns: OK if poked successfully. FAIL if addr or val out of range or contains invalid characters. "QUIT" Arguments: None. Attempts to quit ASp. Returns: OK if the Quit Requester was successfully displayed. FAIL if the emulation was running. "RELOAD" Arguments: None. Returns: OK if last file reloaded ok. ERROR if no ReLoad buffer available. (ie: Previous load failed.) "RESET" Arguments: None. Resets the emulation as if the Reset GUI button were pressed. Returns: OK. "RUN" Arguments: None. Behaves just like pressing the RUN gadget on the GUI. Returns: OK if emulation started ok. WARN if emulation was already running. FAIL if emulation could not be started. "SETPAGE " Arguments: to use for memory paging. The value will effectively be output to port $7FFD, with the exception that the current status of the "ignore further writes" bit is ignored and overwritten. This command will momentarily pause the emulation, if running. Bits: 0-3: RAM page number to map at $C000-$FFFF. 4: ROM select: 0=128K, 1=48K. 5: Further writes will be ignored until Reset. 6-7: Unused. Returns: OK if value written successfully. FAIL if value is not a valid number. "STOP" Arguments: None. Causes the running emulation to stop as if the GUI Stop button were pressed. Returns: OK if emulation stopped ok. WARN if emulation was not running. Other Stuff: ------------ This program is FREEWARE. You may freely redistribute the archive in its entirety, no files may be added, removed or modified. You may not redistribute it for profit. The copyright remains with the author. You use this program entirely at your own risk. No responsibility is accepted by the author for damages caused by using this program. No representations are made for fitness for purpose. You take sole responsibilty for the consequences of using this software. Contact and Support: -------------------- PLEASE email me with any comments, suggestions or problems you have, at.. iang@ukonline.co.uk There is support available on my website, where you can find the latest version, program information, the rom file, etc.. http://www.greew.freeserve.co.uk/ You may see me around on ArcNET IRC channels as "Laser". Feel free to talk to me about ASp. The World Of Spectrum maintains a huge database of information and files for use with Spectrum Emulators. Check out http://www.void.jump.org/ Thanks for trying ASp! Credits: -------- Various people have been very helpful during the creation of this program. Thanks and acknowledgments to them all (strictly alphabetical): Stephen "FBlit" Brookes Mac Buster Lee Cook David Cripps Martijn "void" van der Heide BKJ/Vulture Thomas "Thor" Richter Mario Sarno Gerard Sweeney Everyone on the Spectrum Emulator mailing list. ..and a load of other ppl who I've forgotten to mention.. ;-) Information from: A Z80 Workshop Manual - E.A. Parr MC68030 User's Manual - Motorola The "TechInfo.doc" from the "Z80" emulator - Gerton Lunter. The Spectrum Emulator FAQ - Phil Kendall. Various anonymous documents on the internet. And my trusty rubber-keyed Spectrum 48K, of course! --- NewIcon images by Lee Cook. Thanks Lee! The excellent mmu.library and MuTools by Thomas Richter. --- ASp has been written from scratch in 680x0 asm using HiSoft's Devpac 3.18. Some of the data structures have been created in TurboCalc2 and processed using programs I've compiled with VBCC. Total size of source and data files required to build ASp: Appx 1Mb. History: ======== V0.75: Change Z80 core to obtain 15-20% speed increase on 68030. Added simple ARexx port. Add more joystick types. Add user-defined "joy-keys" window. Change Kempston decode for compatibility. (Artur Chlebek) Add BLANKPOINTER tooltype. Fix multiple menu selections. (Luca Longone) Added variable audio sample rates. Added timing changes for 128K/48K modes. Add Quiet 48K option, default changed to Loud. Fix block IN and OUT flags and timings. Fixes Gryzor music. Corrected timings for ZX interrupts. Fixed loading of Z80 files of 49179 bytes. Optimised AY sound build again. Changed version string to correct format. (Luca Longone) V0.74: Much faster 128K bank switching. Add support for V42 mmu.library. Re-introduce 68030 speedups based on ASp V0.71b. Z80 loader will load the initial part of a SLT. F2 (ReLoad) changed to F6. (Grr!) Better error report on init failure. V0.73dß: Fix: Menus again! Forgot a MENUTOGGLE flag. V0.73cß: Internal development version. V0.73bß: Fix: Fixed NewLook menus rendering as black-on-black. Fix: If AGA wasn't available, the OCS display was broken! V0.73ß: Fix: 128K paging. Fix: Shadow screen swapping. Fix: Glaring major bug in TAP loader. Fix: Z80 loader bugs. Add: Z80 saver. Add: Auto-detect and option for SNA or Z80 save. Add: 48K-128K mode switch. Add: Menus. Add: Stereo sound. Add: About function. Enhance GUI appearance. Speed up sound building. V0.72ß: Prerelease 128K version. Add: 128K paging. Add: 128K file loading. Add: Lots of bugs. ;^) V0.71b: Experimental speedup. 5-15% depending. V0.71: Fix: Rewrote sound handling. No longer uses audio.device calls. Added ToolTypes: LOADPATH, SAVEPATH, ROMFILE. Added Reload and Rewind functions. Key shortcuts for Load, Save, Reload, Reset. System screen now *activates* input! Fixed "." on numeric pad. Test for AGA chipset. Filerequesters are a bit nicer. Inactive GUI buttons are ghosted. Some potential deadlocks removed. V0.70: Speeded up sound routines. Now all audio goes through audio.device! 100% system friendly. Allows running multiple copies at once. :) Add emulation of INI/OUTI/IND/OUTD. Generalised i/o port decoding. V0.69: Internal Test Version. Added AY-3-8912 sound emulation. V0.68: Beta Release only. Limited ".TAP" loading support. V0.67: Now has choice of Custom AGA Display or Native System Screen. GUI: Added STOP button and Display-Type cycle gadget. Can now Load/Save/Reset even if emulator is running. Now requires WB3.0 (V39) or above. Lee Cook contributed an alternative NewIcon. Thanks! V0.65-V0.66: Internal. V0.64: Interim bugfix release: Fixed a nasty enforcer hit in the .SNA loader! Oops! :-) Added facility to load ".Z80" files, versions 1, 2 & 3, 48K type only. V0.63: Added some error requestors. Fiddled around with parts of the source to aid future updates. V0.62B: Made emulation code more regular at minor cost in speed on '030. First public release.