XTender2 - ZX81/ZX80 emulator - BETA release 13A - June 2006 (c) 1998-2006 by Carlo Delhez Mail: xtender@delhez.demon.nl Site: http://www.delhez.demon.nl/ PLEASE READ THIS FIRST! You have obtained a BETA-release of XTender2. This BETA-release is NOT user-friendly. This BETA-release is NOT intended for regular users. This BETA-release is CRASH-prone. This BETA-release is for TESTING purposes only. If you wish to BETA-test XTender2, please continue reading, otherwise: just wait for the official release! Please check the XTender site (see above) to see if this BETA-release is still up-to-date. Otherwise, download a more recent copy! (It makes no sense to test an old BETA-release, does it?) Features: See "FEATURES.TXT" for an overview of XTender2 features. System Requirements: I recommend a PC running at 1 GHz, or better. If your PC is slower, XTender2 performance may be disappointing. Environment: XTender2 runs under MS/DOS. XTender2 also runs in a DOS-box under Windows. To get the best out of XTender2, I recommend to use full-screen mode only (press ALT-Enter to toggle between DOS-box & full-screen). Starting: To start XTender2, simpy type (or click): XT2 or XT2 [=config[.XT2]] [n%] [program[.ext]] Example: XT2=ZX80 100% invaders : run ZX80 invaders at real-time speed All arguments are optional. =config : define the (hardware-)configuration to be emulated n% : define relative speed (100% is real-time, circa 3.25 MHz) program : define a program to load The '=config' argument is a config-file (text file with extension .XT2) The config-file (config.XT2) must be located in the current directory, or in the directory containing XT2.EXE itself. If no 'config' is specified, the default config-file is assumed. See DEMO.XT2 for more info about configuration file options. See section on .XT2-files for more info. The default config-file is specified in XT2.CFG (a text file). XT2.CFG must be located in the same directory as XT2.EXE itself. See section on XT2.CFG-file for more info. The 'n%' argument defines emulation speed, in percentage of real-time. By default, the speed is not controlled (i.e. as fast as possible). See section on emulation speed for more info. The 'program' argument indicates what program to load at startup. An extension is optional. If no extension is given, the extension that is defined in the 'config.XT2' file will be used. If no 'program' is specified, no program will be loaded at startup. You may wish to redirect XT2 output to check the messages generated by the XT2 commandline parser and configuration file parser, e.g. XT2 =demo > demo.log XT2.CFG file: XTender2 needs the XT2.CFG file. It contains general XTender2 settings that do not depend on the hardware to be emulated. See XT2.CFG (text file) for info about options. .XT2-files: XTender2 is supplied with a number of configuration files (*.XT2, text files). The XT2-files supplied with XTender2 are: Demo.xt2 Demonstration configuration file ZX80.xt2 ZX80 with SAVE/LOAD patches for disk-access ZX80_Org.xt2 original ZX80 (SAVE/LOAD to virtual tape) ZX81.xt2 ZX81 with SAVE/LOAD patches for disk-access ZX81_1k.xt2 as ZX81, but only 1k RAM ZX81_32k.xt2 as ZX81, but 32k RAM with Oliger patch ZX81_56k.xt2 as ZX81, but full 48k+8k RAM ZX81_Org.xt2 original ZX81 (SAVE/LOAD to virtual tape!) TS1000.xt2 slow clone of ZX81, producing 60 Hz NTSC video Lambda.xt2 Lambda 8300, ZX81 upgrade (read file for details) PC8300.xt2 Chinese ZX81 with 16k RAM (read file for details) Aszmic.xt2 ASZMIC with 16k RAM H4th.xt2 Forth with 48k RAM (video problem - to be solved) Tree4th.xt2 Forth with 48k RAM (video problem - to be solved) Emulation Speed: By default, the speed is not controlled (i.e. as fast as possible). However, emulation speed can be set in the commandline, as a percentage of real-time. Emulation speed of 100% corresponds to circa 3.25 MHz. If emulation speed is set lower than 25%, it will be ignored. And obviously: maximum emulation speed will be limited by your PC. Emulation speed will be continuously monitored and adjusted. Since the processor load may vary from second to second, also the emulation speed may vary (slightly) from second to second. But on average the emulator will run near the requested speed. Keyboard: Keyboard mapping is similar to XTender(1). But keyboard handling is much-much-much improved! No more locking, multiple keypresses are possible, and full emulation of matrix errors! Most keys are mapped (including backspace, arrows, etc.). Use ALT-key for special Shifting (see XTender manual). Use ESC-key for Edit (Shift-1). Use Keypad-5 for Function (Shift-Newline). CTRL-keys are not supported. So: no reset, no help-screen, no inverse, no colours. Do NOT press (CTRL-)F1 for help. XTender2 supports QWERTY, AZERTY and QWERTZ keyboards. Define your keyboard via XT2.CFG Stopping: To stop XTender2, press F1. XTender2 will produce some debug-info, like this: *** ERROR: Aborted by F1 *** ----------------------------------------------------------------------------- PC = 0038 : 0D C2 45 00 E1 05 C8 CB D9 ED 4F FB E9 D1 C8 18 SP = 7FF0 : C8 C1 8B 02 3B 40 1C 21 FE FF 50 1C D1 04 00 3E HL = C1A7 : 28 29 0E 13 35 26 37 26 32 12 0E 00 00 00 00 32 AF = DD02 BC = 0F05 DE = C1C8 HL = C1A7 IX = 0281 AF'= 0101 BC'= 011F DE'= 1C2B HL'= 0000 IY = 4000 I = 1E R = 82 IM = 1 IFF1:2=0:0 NMI = 0 CSYNC = 0 executed 213449778 cycles in 0h:00'26" -> emulated clock is 8.012 MHz (247%) ----------------------------------------------------------------------------- Preliminary Abortion: In some cases (eg. HALT after DI) XTender2 may abort itself and generate a specific debug message. Please write-down this message if you wish to report a bug to me. Do NOT use XTender2 BETA to type long programs! P-files: ZX81-programs in P-files can be saved and loaded from ZX81 Basic. To do this, be sure you are using the ZX81 ROM with the patch handlers 'ZX81save' and 'ZX81load' installed ('ZX81.XT2' installs them for you.) ZX81-programs in P-files can also be loaded & auto-started from the DOS-prompt. To do this, be sure you are using a ZX81 ROM with the patch handler 'ZX81go' installed (the file 'ZX81.XT2' installs it for you.) Then you can type: XT2 program to boot a ZX81 and auto-start 'program.p'! Auto-start will only work if a proper patch-handler (like 'ZX81go' for the ZX81) is installed in the .XT2 file. In Windows, ZX81-programs can be auto-started simply by double-clicking a P-file in a files menu. To achieve this, you must associate P-files to XTender2 (an easy way to do this, is to double-click a P-file in a files menu, and then browse to XT2 to make the association.) An auto-stop feature in the 'ZX81load' patch handler allows you to stop a program directly after loading it from the ZX81. To achieve this, just type STOP (Shift-A) immediately behind the quoted filename: LOAD "FUNNY" STOP O-files: ZX80-programs in O-files can be saved and loaded from ZX80 Basic. To do this, be sure you are using the ZX80 ROM with the patch handlers 'ZX80save' and 'ZX80load' installed ('ZX80.XT2' installs them for you.) ZX80-programs in O-files must be loaded from the DOS-prompt. Be sure you are using a ZX80 ROM with the patch handler 'ZX80load' installed (the file 'ZX80.XT2' installs it for you.) Then you can type: XT2=ZX80 program After the ZX80 has started, type LOAD (key W) to load the program. ZX80 programs never auto-start. Type RUN (key R) to start a program. Note that ZX80 does not support filenames for LOAD and SAVE. If you SAVE a ZX80-program, the file ZX80SAVE.O will be created. Previous contents of this file will be overwritten. Virtual Tape Recorder: Some .XT2-files set-up unpatched systems that can use the virtual tape recorder to SAVE and LOAD code. The virtual tape recorder records and plays tape-data just like your old tape-recorder would. New recordings will always be appended at the end of the virtual tape. When playing, the tape-recorder will automatically rewind when the end of the tape has been reached (so it acts as a closed loop of tape.) Note that saving a new program does not change the position for loading (unlike real tape-recorders). To control the tape-recoder, use the following keys: F5 - PLAY the tape (arrow is shown) F6 - STOP the tape F8 - RECord new data (solid circle is shown) Example ( ZX81_Org.xt2 required ): - enter a small ZX81 program - type SAVE "NAME" and press newline - press F8 to start recording (circle appears) - watch the SAVE-bars on the screen - wait until SAVE is completed - press F6 to stop the tape recorder - type NEW to clear the program - type LOAD "" or LOAD "NAME" and press newline - press F5 to start playing (arrow appears) - watch the LOAD patterns on the screen - wait until LOAD is completed - the original program will be back now - press F6 to stop the tape recorder Note: the echoed patterns may look different from the ones you use(d) to see on your own TV, because the patterns shown depend on the implementation of sync-signal handling in the TV. The virtual tape recorder is still experimental. Therefore, virtual tape contents are lost when you exit the emulator. This will no longer be the case once I have fixed the virtual tape file-format. The virtual tape recorder has been tested successfully with ZX80, ZX81 and ASZMIC ROMs. On the ZX80, LOADing will blank the screen (no echo), but the program will be loaded successfully anyhow! Printer: Printer output is graphically in BMP-format. Printer-output is sent to LPRINTER.BMP. If the file LPRINTER.BMP already exists, it will be overwritten as soon as you begin to print. Use a graphics tool to view, zoom, print or convert. Printer output should work with all ROMs (only ZX81 tested so far). After having printed, you can press F4 to "tear-off paper": the file LPRINTER.BMP will be closed by XTender2, and can then be opened by another application (no need to quit XTender2 first). After pressing F4, be sure to rename or view printer output before you do any more printing: old printerfile contents will be lost as soon as you begin to print new stuff. Similarly: if you wish to get rid of previous printer output before printing new data, pressing F4 will do the trick. QZ Command Handling: To use QZ commands, be sure you are using the ZX81 ROM with the patch handlers 'ZX81save' and 'ZX81load' installed ('ZX81.XT2' installs them for you.) The QZ commands are meant to provide an interface to the 'outside world' from within the ZX81 (i.e. without using fancy GUIs). This is done via ZX81 LOAD and SAVE commands. QZ commands can be passed as the argument of a LOAD or SAVE command by using an asterisk '*' as the first character of the filename (within the quotes). Behind the asterisk, one or more QZ commands (possibly with parameters) may be typed. QZ commands are to be separated by (one or more) semicolons ';'. Currently, the following QZ commands are supported: ABOUT: show brief information about XT2 and about QZ commands. CD:: change to another directory on the current disk; accepts any on the current disk; use forward slashes; will not accept another disk name as part of . DIR: show a one-page directory; repeat it to get next page(s); currently, only P-files are listed. EXIT: quit XT2 immediately. MD:: create a directory on the current disk; accepts any on the current disk; use forward slashes; will not accept another disk name as part of . RD:: remove a directory on the current disk; accepts any on the current disk; use forward slashes; will not accept another disk name as part of . More commands will be added in future versions of XT2. Note that these commands are different from the commands that are offered by XTender. If there are no arguments to be typed behind the command, the trailing colon ':' can be omitted. If an unkown command is passed (or another error occurs), an error message will be printed. Some examples: SAVE "*" empty commandline - does nothing LOAD "*;ABOUT:;;" show some XT2/QZ information LOAD "*CD:../MYPROGS" move to the ..\MYPROGS directory SAVE "*DIR:" show one page of file-directory LOAD "*EXIT" quit XT2 immediately SAVE " STOP " quit XT2 (STOP typed as Shift-A) SAVE "*MD:TEMP" create a new directory named TEMP SAVE "*RD:TEMP" and remove it again LOAD "" show one page of file-directory LOAD "GAME" STOP load GAME.P and auto-stop it Note that LOAD "" is equal to LOAD "*DIR". It is not possible to type SAVE "" (forbidden by ZX81 ROM). Also note that XT2 is much less fussy about (semi)colons than XTender. Output of the commands is printed directly into the ZX81 display file, but without expanding it. If there is no free space in the display file (e.g. 1K ZX81), nothing will be shown. If there is not enough free space in the display file (e.g. after SCROLLing), only part of the information may be shown, or the information may look chaotic. Other Information: If you do not understand 'PCmask' and 'XSby' in the XT2-files, ignore these features. They are needed to support hi-res & other specific video features (ULA). Machinecode cannot be executed above the PCmask threshold address (unless you understand the implications of 'nop-logic'). This is not a bug, but a compatibility feature! XTender2 can handle video output of screens much larger than the original 24x32 of the ZX81, but it cannot show them completely due to a lack of space. So, in some cases (e.g. ASZMIC) parts of the screen may be invisibe. To view top and bottom parts of the TV-screen, use the following keys to scroll TV-screen vertically over your monitor: press ALT-keypad-8 to move the image up press ALT-keypad-2 to move the image down press ALT-keypad-5 to center the image vertically By scrolling, you can view an entire frame, including VSYNC (black). External patch handlers are .EXE files. You can run them from the command prompt, but they will merely inform you about what they are. Your Contribution: Please test anything that you find useful or interesting to be tested. And please report to me *anything* that doesn't seem to be OK. For example, I'm interested to hear from you about: - unable to use on some PC's and/or OS's; - bugs in the emulation of the ROM codes; - bugs while running (ZX81) programs; - *any* other problems! The more technical details you can give me, the better! If possible, tell me that "Z80 instruction code XX doesn't clear the carry-flag if the result is negative" instead of "Maniacs doesn't work". Nevertheless: all your remarks are highly appreciated !! Your efforts will be acknowledged at the official release of XTender2. Thank you! My Questions: - I havn't had the time to do any structural testing of ZX80, ZX81 programs in XTender2 - so please test all your favourite programs, and tell me the results. - Does printer output work with non-ZX81 ROMs? (not in ASZMIC, as it seems) - etc. Known Bugs: [ but hard to solve :-( ] - error(s) in ZX81 arithmetic routines (eg. COS, SIN) - TREE4TH and H4TH video - visible sync-signals in some hi-res screens - ... Thank you for evaluating XTender2 !! (end of file)