------------------------------------------------------------------------------- **** XTENDER ZX81 (TS1000) EMULATOR -- Preliminary Version 0.93 **** by Carlo Delhez, January 1993 ------------------------------------------------------------------------------- This file is in 80-column ASCII format. Use an ASCII editor to read the contents, import into your favourite word processor or copy directly to your printer (approximately 19 pages @ 60 lines/page). ------------------------------------------------------------------------------- !!! EXPECTED SOON !!! .... ZX81TAPE .... A utility to read ORIGINAL ZX81 TAPES directly into your PC, immediately suited for loading into XTender. Only a simple DIY interface will be needed. Write me if you're interested! CONTENTS - Introduction - Program Description - Registration - Compatibility - - Comparison - Starting XTender - Commandline Qualifiers - Screen Output - - Keyboard Facilities - Keyboard Compatibility - Keyboard Lock - - File Management - Printer Output - High Resolution - ZX81 64k Memory Map - - ROM and 8-16k Area - Stopping - Clock Frequency - Slowing Down - - Z80 Emulation - Writing Programs - Program Transportation - - Screen Saver - Other ZX81 Emulators - Warranty - About the Author - - ZX-91 - XTender Release History & Future - Final Notes - INTRODUCTION The Sinclair ZX81 (or Timex/Sinclair TS1000) is the second computer marketed by Sir Clive Sinclair in the early eighties. In 1980, he introduced his first computer and called it 'ZX80'. In those days, computers were far from the 'common good' they are nowadays and the ZX80 was a relatively cheap machine. It was offered for around 100 pounds (and was marketed as 'the worlds first complete personal computer for under 100 pounds'), while its closest competitor (the VIC20 from Commodore) was about three times as expensive. Although the ZX80 was quite a success (50,000 sold), it had some shortcomings, e.g. it could only do integer calculations (no floating point), the screen flashed at every keypress and went blank during execution of programs (this did increase speed but was not very 'ergonomic'). An upgraded version of the ZX80 appeared within a year. It had an 8k ROM (instead of the 4k of the ZX80), could do floating point mathematics and offered a choice between FAST operation with black screen (as on the ZX80) or SLOWer operation with normal screen. This updated version was called ZX81. It had a Z80A processor operating at 3.2 MHz, 1k RAM (yes! only 1024 bytes, but expandable to 48k), 32x24 text screen and 64x48 graphics resolution in black and white. Programs could be stored on tape and be retrieved at 300 baud. The first versions sold for 70 pounds (ready built) and 50 pounds (DIY kit); 50,000 ZX81s were purchased in the first 3 months after its release. Later computers from Sinclair include the ZX Spectrum (1982, Z80 based, 3.5 MHz, 16k ROM, 48k RAM, colour, sound, high resolution, a lot faster thanks to screen-hardware instead of -software, ASCII based character set and more expansion possibilities) and the QL (Quantum Leap, 1984, 68008 based, 8 MHz, 48k ROM, 128k RAM [upgradable to 68000, 24 MHz, 2M RAM], multitasking and !superb! operating system QDOS). Although the Spectrum was undoubtedly the most popular of all Sinclair machines, I think that many people using MS/DOS machines nowadays may have been introduced to the world of computers by way of their (late) ZX81. I hope these people will re-enjoy working with this simple yet very fine computer again. Run XTender and be my guest! PROGRAM DESCRIPTION XTender is - stated very accurately - a Z80 Emulator in a Sinclair ZX81 environment, written for MS/DOS compatible machines with a standard graphics adapter (Hercules, CGA, PCjr, EGA, MCGA or VGA). The Z80 Emulator is able to execute programs written in the Z80 machine code language. The ZX81 environment includes the original ZX81 ROM and additionally caters for `hardware compatibility' (such as keyboard reading, screen output control and redirecting of signals originally heading for devices such as tape and lineprinter). The Z80 Emulator and the ZX81 environment are joined in a single block of 8086 machine code, which - as a whole - shall be referred to as ZX81 Emulator, and is named XTender. XTender is written !entirely! in Assembly Language for best performance. The source comprises over 8,000 lines (with the numerous macros still unexpanded!). NOTE: XTender contains the original ZX81 ROM code. This code is copyright software. Therefore, XTender may ONLY be used by you if you own a ZX81 YOURSELF. In that case, you are IN PRINCIPLE able to LEGALLY transport the ROM code from your ZX81 to your PC. Any usage of XTender by people NOT owning a ZX81 is in conflict with copyright laws. REGISTRATION XTender is distributed on a ShareWare basis. You are allowed to make copies for other people, provided you copy ALL the files and do NOT make changes in any one of these files. Test XTender during a trial period of 21 days and then delete the files if you don't like to use the program. However, if you DO like to use XTender, please express your appreciation and support my efforts by becoming a REGISTERED user. You will then receive a laser-printed copy of this manual, you will be informed about new releases, and can update to a more recent version for a small fee to cover my costs. Additionally, you will receive LOADS of ZX81 software on MS/DOS disks. Over 200 programs are already available and the library is still growing! Interested in all those action games, utilities, educational programs, hi-resolution software and even scientific applications? Then: REGISTER NOW! Registration also includes conversion of your own ZX81 programs from tape to disk, free technical support by the author and the possibility to obtain a custom-made version of XTender to suit your specific hardware configuration. To become a registered XTender user, send a EuroCheque worth NLG 50 (Dutch Guilders) plus a note stating your name, address and the version number of this copy of XTender to me (address at the bottom of this document). The most recent version of XTender, the first TWO disks of the ZX81 program library (all on 3.5" DS/DD 3M-branded floppies) and a laserprinted copy of the manual will be dispatched you (sorry, no 5.25" disks). IMPORTANT: ^^^^^^^^^^ For cheques OTHER THAN EuroCheques, please ADD NLG 20 for additional cashing costs. Do NOT send cheques in a currency OTHER THAN Dutch Guilders. If you wish, you may also send CASH (banknotes) instead of a cheque. In case you send banknotes in a currency OTHER THAN Dutch Guilders, please use an acceptable rate of exchange and ADD the equivalent of NLG 10 for my exchange costs. COMPATIBILITY Since the original ZX81 ROM in Z80 code is included (with only a few minor changes, of no interest for ordinary use) almost complete software compatibility is guaranteed. Almost, since only some VERY specific software can obviously NOT be emulated: programs using either standard or non-standard input/output ports (e.g. the ear/mic-lines and lines connected to external hardware devices not available on the PC such as sound-generators or EPROM programmers; note however that the keyboard and printer input-lines are emulated correctly), and programs taking over the interrupt vector (e.g. ZX81 sprite programs) are NOT (yet) supported by XTender. Apart from these exceptional applications, ANY program running on the ZX81 should ALSO run on XTender. COMPARISON To name just a few advantages of XTender with respect to the ZX81: safe housing in a well-stabilized computer (none of the tricky business with wobbling RAM packs), full 64k RAM available (including POKEable ROM and 8-16k area), reliable and fast data-storage (no more tapes!), the ZX81 display file can be moved to any part of memory without a crash, machine code can also be executed in the top 32k of memory (on the ZX81 only the bottom 32k could be used), easy screen invert option, a SuperBreak facility, reset under keyboard control, etc. A disadvantage may be operation speed. On slow machines, the processor emulation might become quite dull. On fast machines, the speed becomes far too high for reasonable operation. Therefore, TWO versions of XTender are supplied: a speed optimized version for slow machines and a (slower) user-variable-speed version for fast machines. More about this in the section `Slowing Down.' STARTING XTENDER For running XTender, you need an MS/DOS machine with a standard graphics adapter (Hercules, CGA, PCjr, EGA, MCGA or VGA) and about 128k of free memory to store the program and the required work space. Note that you need MS/DOS version 2.0 or higher (or compatible). XTender refuses to start with lower version numbers. XTender is designed to be compatible with all processors from 8088 up to 80486 (and beyond!), including the NECs. As said earlier, two versions of XTender exist. These are called XTENDERF.COM and XTENDERS.COM. The first is the fastest version and should be used on slow machines. The second one is not speed-optimized, hence slower. However, this one has the possibility to slow emulation down considerably and should be used on (very) fast machines. The user must determine by experience which one works best on his machine. A rule of thumb: XTenderF is 50% faster than the fastest setting of XTenderS or the fastest setting of XTenderS is 30% slower than XTenderF To start the program, simply type XTENDERF (fast version) or XTENDERS (slow version) (whichever you prefer) at the DOS prompt. This will start XTender. First you will hear a beep and see a title page which displays some general information about XTender and its usage. In case of registered copies, the name of the owner also appears on this title page. Now press any key to start the actual ZX81 emulation. Depending on the speed of your computer, you will see some flashes and/or weird characters while the ZX81 performs a reset, but eventually the famous inverse-K-cursor should appear and XTender is ready for use. Xtender tries to determine what video card you have installed simply by looking at the current video mode in order to make a destinction between Hercules and non-Hercules. In Hercules, only a small portion of the display will be used, in all other cases, the ZX81 screen occupies almost the entire display. If you have CGA emulation on your Hercules card and want to use it with XTender, make sure you do NOT start XTender with video mode 7. Alternatively, you can force Hercules or CGA mode by the /e and /c qualifiers, respectively (see below). COMMANDLINE QUALIFIERS Instead of starting XTender as described in the previous section, you can also add qualifiers to the command in to order to influence the emulator's behaviour. Qualifiers are single-letter switch parameters preceeded by a forward slash '/', minus sign '-' or plus sign '+' (there is no effictive difference between these three characters). The qualifiers currently available are as follows: /? display help screen, briefly summarizing all qualifiers. /c force CGA screen mode; use this qualifier when XTender tries to use Hercules although you have a CGA (or higher) video card installed; this option may also be chosen when your video card can handle both CGA and Hercules, and you specifically want the CGA mode. /d:nnn set emulator delay factor; `nnn' is a decimal number in the range 0 through 128; this qualifier is equivalent to the ZX81 command `POKE 23,nnn' after XTenderS has been started; for more information, see section `Slowing Down'. /e force Hercules screen mode; use this qualifier when XTender tries to use CGA although you have a Hercules video card installed; this option may also be chosen when your video card can handle both CGA and Hercules, and you specifically want the Hercules mode. /h display help screen, briefly summarizing all qualifiers. /i force inverse video, i.e. white characters on black background, which seems more comfortable for the eyes in case of serious applications. Note that CTRL-F2 can be used to toggle screen colour once the emulator is started (see section 'Keyboard Compatibility'). /m skip ZX81 memory test; after a NEW or Reset, the ZX81 ROM performs two main actions: it tests the RAM memory and sets up the display file. Each of these takes about half the reset-time. On an emulator, the memory test is rather superfluous and can be omitted by this qualifier, thus reducing the reset-time by at least 50%. Note that the RAM memory is still cleared (zero-filled). /v:nnn select high byte of paragraph of start of video memory; this option should be used with great care and only when neither the /c nor the /e qualifier produces proper screen output. Random experiments with the value of nnn will cause a system crash. Upper- and lower-case letters are freely interchangable. Spaces inbetween successive qualifiers are optional. When the /? or /h qualifier is present, only the help screen will be displayed and XTender isn't actually started. Commands are interpreted left-to-right: later settings supersede earlier settings. When no qualifiers are given, XTender is started with the following default settings: IF video_mode=7 THEN XTENDERS /d:0 /e /v:176 ELSE XTENDERS /c /d:0 /v:184 END IF (and the same for XTENDERF), i.e. no delay factor and the standard video memory paragraphs (B000h and B800h for Hercules and CGA, respectively). Any qualifier given by the user supersedes these default settings. SCREEN OUTPUT XTender uses a PC timer interrupt to write the ZX81 screen regularly into the PC video memory. For the obvious reasons of speed, the pixel data is poked directly into the video RAM (instead of using the !VERY SLOW! PC INT's). This may not work properly on (very) old PC systems. The screen routine is differential, i.e. only those parts of the ZX81 screen that have changed since the last interrupt are updated on the PC screen. Before XTender starts emulating, it first determines the relative speed of your computer. It does this by running a `benchmark test' and the resulting benchmark is used to calculate the rate of screen update. For example, if the measured benchmark is 1000 (33 MHz 80386dx machine), the screen is updated at a rate of 100 Hz. Lower/higher benchmarks result in proportionally lower/higher screen update frequencies. As a result of this method, the performance of XTender is optimized automatically for ANY machine. I have tested XTender on an original PC (benchmark 50, screen update at 5 Hz) and the emulator (fast version) executed at a speed of 35% with respect to the real ZX81! You can see the measured benchmark and resulting screen update frequency by loading the program SYSINFO.P directly after having started XTender. This will provide you with all the information you need. The timer interrupt of the PC can be set to ONE frequency only. However, XTender actually needs three distinctively different frequencies: - 18.2 Hz to keep your PC's internal clock synchronized (you'd be cross with me if I hadn't done this!); - 50.0 Hz to update the ZX81 system variable FRAMES (for processor-speed-independent timing loops); - nnnn Hz to update the video RAM (nnnn is an arbitrary number determined by the measured benchmark). I have applied some clever `state of the art' programming techniques to make sure that all these frequencies are available from only one timer-interrupt! When you return to DOS, the timer frequency is set to 18.2 Hz again. KEYBOARD FACILTITIES A problem for many users may be the keyboard: the ZX81 works with tokens and single keypress entries (e.g. pressing just `P' gives the token `PRINT'). XTender solves this problem by providing a graphical help screen. Just press CTRL-F1 and the keyboard help screen will pop up. Press any key to return to the ZX81 screen. The help screen is a touched scanner image of the original ZX81 keyboard. As an example of keyboard operation, take a look at the A-key on the help screen. It contains the following symbols: - the letter A itself - the command NEW - the command STOP - the function ARCSIN (abbreviated ASN) - a gray block Pressing the A-key will produce one of these symbols, depending on the current setting of the cursor: cursor keypress effect ---------------------------------------------------- K A NEW K or L Shift-A STOP L A A F A or Shift-A ARCSIN G A inverse letter A G Shift-A gray block The K-cursor (Keyword) always appears at the beginning of a command line and after the THEN keyword; the L-cursor (Letter) appears elsewhere. The F- and G-cursors (Function and Graphics) can be activated by the user by pressing Shift-Enter (or keypad `5') and Shift-9, respectively. The default ZX81 screen colour is black characters on white background (unless you have used the /i qualifier). For games with a lot of graphics this may be nice, but for text handling, I find the inverse more comfortable for the eyes. Press CTRL-F2 to change the display from black on white to white on black and vice versa. Some ZX81 (machine coded) programs do not allow you to stop them using Break (Space). On XTender, programs can always be stopped using CTRL-ESC. This will actually cause a jump to an address in ROM where a RST 8 for error D is located, and hence the stack is cleared, the error message is displayed and you are back in Basic. Some programs crash the ZX81 if you try this, as they may have messed around with the system variables, Basic area, screen or even with the ROM code. If CTRL-ESC causes a ZX81 `hangup', press CTRL-ALT-ESC to recover. This restores the original ROM code and subsequently executes a RST 0. ANY program can safely be aborted using CTRL-ALT-ESC. Note that the PEEK value of address 23 is preserved (or should be!). On some computers, CTRL-ALT-ESC is already in use for system purposes; therefore, the keypress CTRL-SHIFT-ESC may be used as an alternative. In general, CTRL-ESC should only be used when the normal Break is disabled. If you use CTRL-ESC in the normal ZX81 editor, it will lock keyboard operation. Press CTRL-ESC once more to get proper key response again. In the CBI editor, CTRL-ESC merely produces a space character, i.e. does not lock the keyboard. In all cases, avoid using CTRL-ESC when CBI Trace is active. All the legal CTRL keypresses generate a modest beep when they are recognized by XTender; you can then release the key(s) and await the desired result. CTRL together with a key other than one of the above has the effect of SHIFT pressed together with that key. Finally, CTRL-C and CTRL-Break are hooked and have no drastic effect (CTRL-C produces Shift-C, i.e. a question mark). KEYBOARD COMPATIBILITY The ZX81 keyboard is totally different from the PC XT/AT keyboard. First of all, the ZX81 has only 40 keys. These are arranged according to the familiar QWERTY layout, yet - as you can imagine - 26 letter keys, 10 number keys, Shift, Space and NewLine (the ZX81 equivalent of Enter) already make a grand total of 39 keys. The remaining 40th key is a full stop (`.'). So: all other symbols are hidden as Shifted keys and (to make things even more complicated) in a non-PC-like fashion. The ZX81 works in UPPER CASE only, so in fact you have 39 Shift options (barring Shift itself, all keys can be Shifted, including Space and NewLine). Symbols are really scattered around the keyboard (can you imagine using Shift-`B' for `*' and Shift-`U' for `$' !?!) and you will really need the CTRL-F1 help facility (or your own ZX81 manual) and some patience for locating the symbols. For UNSHIFTED keys, XTender maps almost the entire PC keyboard onto the ZX81 keyboard. Not only the 40 basic ZX81 keys, but also things like the Cursor Keys, BackSpace and the Numeric Pad are mapped. For example, if you press `Cursor Left', XTender will convert this to Shift-`5', the ZX81 equivalent. This makes editting (and sometimes also playing games) less strenuous. The central key of the numeric pad (`5') generates Shift-Enter, i.e. toggles Function mode (a special cursor mode for obtaining functions tokens). More special keys: the square brackets (`[..]') become normal brackets (`(..)') and the single forward quote gives the standard ZX81 double quote. The ESC key generates Shift-1 (Edit), i.e. brings the current cursored BASIC line in the editor. Also for SHIFTED keys, the emulator helps you a little bit. Pressing any one of the Shift keys will always give you the ZX81-Shifted symbol (like Shift-`U' for `$'). BUT, if you press ALT instead of SHIFT, you will get the PC-Shifted symbol, so you can press Alt-`4' to get the Dollar $ign. Some non-trivial ALTernatives are listed below: ALT-`6' gives `**' (instead of `^') ALT-`7' gives `AND' (instead of `&') ALT-`[' gives `<=' (instead of `{') ALT-`]' gives `>=' (instead of `}') ALT-`'' gives `""' (instead of `"') Note again, how the single forward quote (`'') is converted to a ZX81 double quote (`"') whereas the PC double quote is converted to a ZX81 quadruple quote (`""'). XTender effectively doubles quotes. Finally, if CAPSLOCK is ON, the effect of Shift is INVERTED for ALL keys (not only the letter keys). So, pressing for example `B' with CAPSLOCK ON gives `*', and Shift-`B' gives `B'. Note that this can be nice for some games which use the keys 5 through 8 for steering and do not allow you to press Shift (so you cannot use the PC cursor keys). With CAPSLOCK ON you CAN use the arrow keys of the keyboard! KEYBOARD LOCK When you are a fast typist, the ZX81 may not always be able to keep track of your typing. In some cases, the PC keyboard seems locked altogether and the ZX81 does not respond anymore to the characters you are typing. Just hit CTRL-ESC !ONCE! to cure this. FILE MANAGEMENT Originally, the ZX81 did not have a Disk Operating System. Programs could be stored on tape only (at a rather dull rate of 300 baud, taking more than 7 minutes to save or load a 16k program). As an alternative, several diskdrive systems were introduced by various companies but none of these were very successful. People preferred to keep using tapes, and software was written to speed-up tape data communication to, say, 6,000 baud (20 seconds for 16k). This was quite acceptable and a single tape of 60 minutes could contain up to 2.5 M information. However, tapes are not a very reliable medium and the sequential storage of tapes obstructs quick access. As a solution, I used an RS232 interface to connect my ZX81 to a more modern Sinclair computer (the QL) which offers more advanced storage possibilities (diskdrives) and which is very well suited to act as a fileserver thanks to its multitasking capabilities (68000 processor). I wrote this fileserver myself, as well as the software needed on the ZX81 to do the communication with the QL. Data could now be exchanged at a rate of 9600 baud (13 seconds for 16k) and could be accessed in a quick and simple way. I called this serial communication system "QZ", which later served as an example for the Disk Operating System offered by my ZX81 emulator for the QL, "XTricator". Also in XTender, programs can be SAVEd and LOADed in a format which is directly compatible to QZ. To SAVE or LOAD a program, just type SAVE "" LOAD "" which are the equivalents of the original QZ commands SAVE:P:: LOAD:P:: The files are SAVEd to and LOADed from the default drive and path (these can be changed with the QZ commands USE: and CD:). The SAVEd programs appear as `.P' files on the default drive/path (`P' stands for Program; other filetypes supported by XTender are Basic, Code, Lines, Screen and Variables). LOADing a non-existing program will display the proper DOS error. If you SAVE a program which already existed, it will simply be overwritten without any user confirmation. Saving a file with a NAME of length zero results in the usual error F. Originally, QZ filenames were at most 12 characters long. On the PC, one is so unfortunate to be restricted to 8. So: only the first 8 characters of the SAVE/LOAD name will be used. Do NOT include INVERSE characters in the name, since these are used internally by the ZX81 to indicate the end of the filename. QZ file handling commands can be passed to XTender in a LOAD (or SAVE) statement. The first character of the SAVE/LOAD name must be an asterisk (`*') to indicate that one or more QZ commands follow (instead of the usual filename). The available commands, a short description and examples of each command are listed below: *BACK: - Step one level back in current directorypath; in fact equal to CD:..: but included for compatibility reasons. - Example: LOAD "*BACK:" *CD: - Change current directory to indicated pathname; note that the pathname ends with ':' (as in all other QZ commands), so you cannot use CD: to change the directory on a non- default drive; apply the command USE: first. The usual MS/DOS backslashes must be replaced by forward slashes. - Examples: LOAD "*CD:GAMES:" LOAD "*CD:/ZX81/ASM/TOOLS:" LOAD "*CD:..:" LOAD "*CD:/:" *DEL: - Deletes indicated file; the extension of the filename (i.e. the filetype) must be typed first, followed by a colon (':') and the main part of the name; the command is ended by a colon as well. The filetypes recognized by XTender are B, C, L, P, S and V. Note that only files in the current drive and path can be deleted. For deleting files on other drives or paths, use CD: and USE: first. DEL: is the same as REMOVE:. - Example: LOAD "*DEL:P:RUBBISH:" (deletes RUBBISH.P) *DIR: - Shows the ZX81 files on the current drive; all the specific ZX81 files (with extensions .B, .C, .L, .P, .S or .V) are listed, together with their length, date and time; note that the date is shown in the format "yy-mm-dd", not in the usual DOS format "mm-dd-yy"; the time is shown in 24-hour format. Subdirectories without extension are also shown. At the end of each page, press any key to see the next page or Q to stop the directory listing; at the top of each page you will see the current drive and pathname; the backslashes are replaced by forward slashes; at the end of the file list you will see the total number of files and the number of clusters left on the current device (depending on your drive's FAT, a cluster can hold 512 bytes, 1k, 2k, 4k etc.). - Example: LOAD "*DIR:" *KILL-XTR: - Stops the current XTender session, returns to DOS. - Example: LOAD "*KILL-XTR:" *LOAD: - Loads one of the special filetypes (not P-files!). The filetypes currently available are: * Basic 'B' - all the lines of the current Basic program are deleted and the the file is then inserted in the Basic area. The variables area remains unchanged. XTender does not check if there is sufficient memory available to insert the file. If not, a crash will result. If all is OK, error 'I' will be generated (data merged). - example: LOAD "*LOAD:B:SORTING:" * Code 'C' - the code file is loaded from disk to the specified address; XTender tries to load all the bytes from the file but stops after exceeding address 65535 - example: LOAD "*LOAD:C:CHARSET:8192:" * Lines 'L' - the lines in the file are merged with the current Basic program. If a line with a certain number already exists in the current program, it will be replaced by the new line with the same number. The variables area remains unchanged. XTender does not check if there is sufficient memory available to insert the lines. If not, a crash will result. If all is OK, error 'I' will be generated (data merged). - example: LOAD "*LOAD:L:PARTLY:" * Screen 'S' - the screen file is loaded from disk into the current ZX81 display file. It is assumed that the display file is fully expanded; otherwise: ZX81 crash! - example: LOAD "*LOAD:S:PICTURE:" * Variables 'V' - the variables area of the ZX81 is cleared, and then the file is inserted in this area. The Basic program remains unchanged. XTender does not check if there is sufficient memory available to insert the file. If not, a crash will result. If all is OK, error 'I' will be generated (data merged). - example: LOAD "*LOAD:V:GRAPHS:" *MAIN: - Go to root directory of current drive; in fact equal to CD:/: but included for compatibility reasons. - Example: LOAD "*MAIN:" *MD: - Makes new directory as indicated by pathname; note that the pathname ends with ':' (as in all other QZ commands), so you cannot use MD: to create a directory on a non- default drive; apply the command USE: first. The usual MS/DOS backslashes must be replaced by forward slashes. - Examples: LOAD "*MD:JUNK:" LOAD "*MD:/ZX81/GAMES/SHOOT:" LOAD "*MD:../LEVEL2:" *RD: - Removes directory as indicated by pathname; note that the pathname ends with ':' (as in all other QZ commands), so you cannot use RD: to remove a directory on a non- default drive; apply the command USE: first. The usual MS/DOS backslashes must be replaced by forward slashes. - Examples: LOAD "*RD:OLD-DATA:" LOAD "*RD:/ZX81/TAPE:" LOAD "*RD:../BACKUP:" *REMOVE: - Removes indicated file; the extension of the filename (i.e. the filetype) must be typed first, followed by a colon (':') and the main part of the name; the command is ended by a colon as well. The filetypes recognized by XTender are B, C, L, P, S and V. Note that only files in the current drive and path can be deleted. For deleting files on other drives or paths, use CD: and USE: first. REMOVE: is the same as DEL:. - Example: LOAD "*REMOVE:C:ZXASSEM:" (removes ZXASSEM.C) *ROOT: - Go to root directory of current drive; in fact equal to CD:/: but included for compatibility reasons. - Example: LOAD "*ROOT:" *SAVE: - Creates one of the special-type files (not P-files!). The filetypes currently available are: * Basic 'B' - all the lines of the current Basic programs are written to disk. System variables, Basic variables and screen are NOT written to disk; a B-file is a compact (hence fast) way for storing short programs on disk. - example: LOAD "*SAVE:B:QUICK:" * Code 'C' - the code block starting at the address determined by the first parameter and with a length determined by the second parameter is written to disk. The length must be larger than 0 and the calculated end address may not exceed address 65535. Please note that the second parameter does NOT represent the end address. - example: LOAD "*SAVE:C:CHARSET:7680:512:" (saves the contents of addresses 7680 through 8191) * Lines 'L' - those lines of the current basic program with a line number lying within the interval determined by the two parameters supplied are written to disk. The first line number must be smaller than or equal to the second line number. The second line number must be smaller than 10,000. The two line numbers need not actually exist in the current program. If no lines ly in the specified interval, a file of zero length is produced. - example: LOAD "*SAVE:L:ELEPHANT:1000:2000:" (saves all lines with numbers greater or equal to 1000 and less or equal to 2000) * Screen 'S' - the current ZX81 display file is written to disk. It is assumed that the display file is fully expanded; this means that the resulting S-file is always 793 bytes in length (namely 24*33+1). - example: LOAD "*SAVE:S:DISPLAY:" * Variables 'V' - the current contents of the ZX81 variables area are written to disk (including the delimiting CHR$(80)). Directly after a CLEAR (or similar) command, this area is empty and the file will have length 1. - example: LOAD "*SAVE:V:TAXES:" *SHOW: - Shows information about the current version of XTender plus a list of all QZ commands available. - Example: LOAD "*SHOW:" *USE: - Selects another drive as default drive. If you have only one physical floppy drive, which can be accessed logically as A: or B:, Xtender will always use the last logical setting of this drive to avoid the DOS message requesting to insert a disk (very few other programs I know also do this!). But note that this only works from DOS 3.2 onwards. A pathname cannot be included, use CD: instead. - Example: LOAD "*USE:D:" (selects drive D:) Please note the colon (`:') at the end of each command, acting as a separator. More than one command can be given in a single LOAD or SAVE by separating successive commands with a semi-colon (`;'). Only one asterisk is needed, e.g. LOAD "*USE:B:;CD:../GAMES:;DIR:" Any non-supported command after the `*' will display the erroneous text plus the message `ERROR IN QZ COMMAND', and stops with Error C (syntax error). PRINTER OUTPUT No printer driver is available as yet. This will be implemented in future versions. HIGH RESOLUTION Sir Clive Sinclair himself said that it could not be done. Still, in 1983, a first attempt to High Resolution on the ZX81 was presented when the High Resolution Toolkit by Richard Taylor was marketed. Later, companies like Software Farm produced several games in High Resolution. Taking a closer look at this `High Resolution', one can easily see that it is not real Hi-Res: for the 256 bit patterns which are possible for 8 successive pixels, at most 128 are available, i.e. more than half of the patterns cannot be used. The result of this Semi Hi-Res may, however, still be quite satisfactory. Hi-Res is detected by XTender by trapping an immediate change in value of register IX (used by the ZX81 as NMI server address). The term `immediate' means that only the instruction `LD IX,nn' (DDh.21h) is trapped. You could avoid the trap by using a sequence like `LD HL,nn \ PUSH HL \ POP IX'. However, all Hi-Res programmes tested use the (more obvious) immediate method. After the detection, XTender first tries to emulate the Semi Hi-Res by looking for the chacteristically shaped 6k display file in the bottom 16k of RAM and printing it to the PC screen appropriately. If it cannot locate this display file, normal resolution will be switched on. As fas as I know, only HRWP (Hi-Res Word Processor) does not function properly on XTender, but I'm working on that! ZX81 64K MEMORY MAP begin_address end_address description 0000h - 1FFFh original ZX81 8k-ROM area. 2000h - 3FFFh 8-16k area; on the ZX81 this area can only be used when additional hardware is fitted (e.g. 64k RAM pack or EPROM card); the standard ZX81 shadows its ROM in this area. 4000h - FFFFh 48k of RAM; at startup, the ZX81 allocates at most 16k of RAM to BASIC; the remaining 32k is kept free for data storage; more area can be allocated to BASIC by moving RAMtop (system variable at 4004h) upwards. 4000h - 407Ch system variables 407Dh - [400Ch]-1 BASIC program area [400Ch] - [4010h]-1 display file (text mode!) [4010h] - [4014h]-1 BASIC variables area [4014h] - [401Ch]-1 work space [401Ch] - [4004h]-1 free memory available for BASIC; this area is cleared by NEW; the machine code stack grows down from the top address of this area [4004h] - FFFFh free memory that cannot be used by BASIC and that is also not influenced by NEW, useful for resident utilities or RAMdisk; provided [4004h] is above 7FFFh, this area is also not altered by RST 0. Note: [addr] is the value obtained by PEEK(addr)+256*PEEK(addr+1), i.e. the usual Z80 double-peek with the low byte before the high byte. ROM AND 8-16K AREA On XTender, the ROM and 8-16k area are in fact also part of RAM, i.e. they are not POKE-protected. This can be nice for making slight changes in the ZX81 ROM or for using the 8-16k area for machine code utilities that can be loaded from disk. At startup, the 8-16k area contains a relocated version of the CORAL BASIC INTERPRETER (CBI version 7.0). You can start this program by typing RAND USR 8192 This should give 0/0 in line 22 and a black cursor in line 23. CBI may be useful for people with little ZX81 experience since it has both a full-entry decoder, full-screen editor and explains error messages on request. All usual ZX81 commands are available, as well as 46 new ones (including commands for PROCedures with two-way data exchange and structured loops). Naturally, CBI was written for the ZX81, but runs equally well on XTender. For details on this program, read the textfile supplied with this version of XTender. Two useful commands to enter when the black cursor appears are ERR MSGS ON (explains error messages) NOSTALGIC OFF (enable full screen editor) Note that you have to type the letters one-by-one, the spaces are optional. The sytem variables of CBI are stored at address 65400 onwards (corresponding to address 32730 in the original version). The CBI program ends at address 13522, so the part of memory from address 13523 up to 16383 is free for your own use. STOPPING There are three ways to end your XTender session. First, the QZ command 'KILL-XTR:' can be typed in a SAVE or LOAD statement, e.g.: LOAD "*KILL-XTR:" which will bring you back to DOS. As this requires quite a lot of typing, you can also use the quicker alternative LOAD " STOP " with STOP typed as a keyword (i.e. Shift-A) instead of the separate letters. Finally, for the very impatient: pressing CTRL-Break will end XTender as well! CLOCK FREQUENCY The effective clock frequency can be determined in several ways. First of all, you can RUN a (long) BASIC program which does not have any INPUT, INKEY$, RND, PAUSE or similar commands (i.e. execution time must be fully determinate and may not contain processor-independent loops). You can then compare the execution time on XTender to the time which this same program requires on a ZX81. The ZX81 runs at 3.2 MHz in FAST mode and at 0.8 MHz in SLOW mode. Supposing a program on XTender takes half the time the ZX81 would take to execute it in SLOW, the effective clock frequency is (0.8 MHz)/(0.5) = 1.6 MHz. Another way to find the clock frequency is to use a machinecode test loop, embracing a single instruction which is executed many (e.g. 65536) times. If you then count the number of frames needed (and subtract the number of frames needed for just the empty loop) you can get an idea of the clock frequency of that specific instruction, provided you know the number of T-cycles the Z80 would normally need for that same instruction. A very good estimate of the emulated processor speed can be obtained by LOADing the program CLCKFREQ. This program does some simple printing and plotting, but the final result is a reliable measure for the average speed of XTender and the effective (emulated) processor speed. SLOWING DOWN On fast machines the speed of the emulator (XTENDERS only!) can be reduced by POKEing address 23. The byte at this address is used as delay counter at each Z80 instruction. Default value is 0, which gives (practically) no delay. A higher value will quickly slow emulation down. The maximum value you may use is 128, which results in a factor 27 slowdown (i.e. 27 times slower than with value 0 poked); if your computer is so fast that even this is not sufficient, please write me to obtain an even slower version. Poking the values 129 through 255 responds just as poking 0, i.e. no delay. Example of SLOWDOWN on a 33 MHz 80386dx machine (benchmark 1000): version PEEK 23 Speed Z80 Frequency XTenderF -- 830% 6.6 MHz XTenderS 0 560% 4.4 MHz XTenderS 1 460% 3.7 MHz XTenderS 2 400% 3.2 MHz XTenderS 4 310% 2.5 MHz XTenderS 8 220% 1.8 MHz XTenderS 16 140% 1.1 MHz XTenderS 32 77% 0.62 MHz XTenderS 64 42% 0.33 MHz XTenderS 128 22% 0.17 MHz Please note again that the slowing down does NOT work with XTENDERF. Once you have determined which value of PEEK 23 suits your needs best, you can start XTenderS with the /d:nnn qualifier in order to set the delay factor to `nnn' without actually having to poke it into the ZX81 memory. Ofcourse, you can still alter this initial value during the session! Z80 EMULATION As far as I have been able to test, all Z80 instructions are emulated correctly: since the ZX81 ROM is the basis for XTender to function, the latter statement must be true. Also, many ZX81 programs have been tested on XTender and all of them turned out to work without any problem! (These programs include (commercially marketed) games and utilities in BASIC and in machine code!) Some brief remarks for Z80 freaks: * Register I points to the ZX81 character set. Default value is I=$1E which means that the character set starts at address $1E00 (last half K of ROM). If you want to change the characterset, first POKE the new set somewhere in memory (at an address which is a multiple of 512 bytes) and then alter register I accordingly (so: only even values for I are allowed). This will instantaneously change the display. The reversed sequence of this procedure will not work the way you would expect! I advise not to change the character set present in ROM. * The Subtract (N) flag of the Z80 flag-register (f) is NOT emulated. Many Z80 instructions alter this flag, but there is only one instruction which uses the result, viz. DAA. Since DAA is used only once in the ZX81 ROM (where it has been replaced by an equivalent non-standard Z80 instruction) and since proper emulation of the Subtract Flag reduces operation speed of XTender, I think this exclusion is a sensible decision. Note that, when XTender encounters a DAA instruction, it performs a `Decimal Adjust After Addition'. So, keep your fingers crossed! Programs using DAA : --- Reversi (only the machine coded version) --- MCTT (Machine Code Testing Tool) --- Frogger If you should know of other programs which use DAA, please tell me! * The IN instructions are all neglected, except for requests for port $FE, (the keyboard) and port $FB (the printer). Also, OUT instructions are neglected. Note, however, that the instructions IND, INDR, INI, INIR, OUTD, OTDR, OUTI and OTIR alter the registers BC and HL (and also (HL)'s) appropriately! * HALT waits for an interrupt. Interrupts are not emulated and therefore HALT is made equal to NOP. * Some instructions cannot be used for changing the ROM area (0-8k). These are: LD (HL),A LD (DE),A LD (HL),D LD (HL),E LDIR The reason for this is to protect the ROM against itself! The programmers of the ZX81 ROM have made use of the write-protection of the 0-8k area for simplifying their code (or is it a hitherto unknown bug of the ZX81 ROM ?). So, XTender (which has no write-protection in the ROM area) would alter its own code, which is (in general!) a bad thing to do. Therefore, the above instructions are emulated such that they have no effect in the first 8k of memory. Note that this also protects the ROM against a program like MCODER-2, which does the same kind of nasty things to the ZX81 ROM-area... WRITING PROGRAMS For the success of XTender and perhaps for a revival of the ZX81, I recommend authors of new programs (either in machine code or in BASIC) to write their software such that it will run on both XTender and on the ZX81. As an example, you could perform nice tricks with XTender by POKEing its ROM, but that is not possible on the ordinary ZX81, i.e. INCOMPATIBLE! Please avoid such tricks or - if they are absolutely necessary - clearly include a message telling on which machine(s) the program runs (ZX81, XTender, XTricator or the Atari ZX81 Emulator). I also advise to use processor independent delay loops where necessary (mostly games and editors). Basically, these look like this: REPEAT SET CLOCK BEGIN PERFORM ACTION END REPEAT READ CLOCK UNTIL CERTAIN TIMELIMIT EXCEEDED FOREVER Programs written this way are equally fast on every computer (unless the ACTION part takes more time than given by CERTAIN TIMELIMIT). In fact, several existing ZX81 programs were really written this way and are consequently not sped up by a fast emulator (only decelerated by a slow one...)! For reading and setting the clock, make use of the system variable Frames. Frames is a two-byte number, decrementing at 50 Hz. Please note that (1) Frames is decremented in SLOW mode ONLY on the ZX81; (2) Frames is decremented in FAST AND SLOW mode on XTender; Also in BASIC programs, use the value of Frames (e.g. by way of PAUSE) instead of some empty FOR-NEXT loop for delays. PROGRAM TRANSPORTATION Some trouble is caused by the fact that ZX81 programs were usually stored on tape instead of disk. Please write me for info on conversion! (Also see top of this document) SCREEN-SAVER XTender has a built-in screen-saver which will be activated when the ZX81 display remains unchanged AND no key is pressed during 3 minutes. When the screen saver is active, any keypress (including Shift etc.) will restore the ZX81 screen. Note that a change of the ZX81 display itself in the saved state will not restore the ZX81 screen! The screen-saver is always deactivated in Hi-Res modes. If you have another screen-saver memory-resident, it may or may not be superseded by the screen-saver of XTender (depending on how exactly that screen-saver was coded). OTHER ZX81 EMULATORS The PC is not the only computer for which a ZX81 emulator has been written. An equivalent ZX81 emulator has also been written for the SINCLAIR QL and for the ATARI ST computers. The emulator for the Sinclair QL is called XTricator and is written by myself. It is completely compatible to XTender as far as file formats are concerned. The development of XTricator was already started in 1989. I have no personal experience with the emulator written for the Atari, but it seems that programs running on that emulator can be LOADed directly into XTender/XTricator and RUN without problems. Note that the files with extension '81' on the Atari emulator are compatible to the 'P' files of XTender and XTricator. It seems that the Atari emulator has problems to LOAD files not SAVEd by the emulator itself (again, I have no personal experience). As far as I know, XTender/XTricator 'P' files cannot be converted to Atari '81' files because of this 'sensitivity'. It is ofcourse the virtue of XTender and XTricator that it DOES work the other way round! WARRANTY If you come across an original ZX81 program that doesn't work properly on XTender and also doesn't fall in any of the "incompatibility catagories" discussed in this manual, please send me a copy of the program on a 3.5" disk with a brief description regarding the failure. If XTender is to blame, I'll try to fix it as soon as possible and you will get your disk back with an updated version of XTender. ABOUT THE AUTHOR I was born in 1967 and bought my first computer (guess what, it was a ZX81!) in 1982. With no prior programming experience at all, I started writing simple Basic programs. After about one year, it appeared to me that Basic just couldn't solve the problems I devised. So, I turned to Z80 machine code (with obliging help of Toni Baker; that is, of her book). A whole new world of possibilities opened up before my very eyes. High-speed compact code and access to all system utilities at lowest level, what else does a programmer need? Many Z80 programs were born, and some of them were even published in international magazines. In 1987, I decided to buy a QL (during sales) and found this younger brother (sister?) just as interesting as the ZX81. It also gave me a good excuse for learning 68000 machine code. As I saw that less and less people were actually using the ZX81, I sought a way for elongating its existence. I thought that (amongst other things) a ZX81 emulator for the QL would be a good way to do so, and I started writing this program in the end of 1989. My present-day occupation as a Ph.D. student in Physics obliged me to buy an MS/DOS machine. In order to stay loyal to the absorbing machines made by Sinclair, I decided to write a ZX81 emulator for MS/DOS as well. The 8086-family is very similar to the Z80, so I did not really have to learn a new language, only a new OS. By now, in 1993, you can judge the result of my efforts. I sincerely hope that many (former) ZX81 users will take some time to leap back in history and (re)enjoy the overwhelming simplicity of the 64k, 8-bit, 3.2 MHz Z80, black & white computer with 64x44 graphics resolution, which introduced over a million people worldwide (including myself) to the wonderful world of computing... ZX-91 Andre Baune is the editor of a small, monthly magazine called ZX-91, intended for all the ZX81 users around the world. The magazine was first released in 1991, when the ZX81 celebrated its tenth aniversary. A quote from issue #1: "... I want to lift the spirit of the users and the believers in this marvelous little computer. I also want to reach the far away users and/or programmers. In this newsletter you will get print-out, pictures, and articles ..." No ZX81-user can consider not subscribing to this newsletter! Besides small programs and the latest news, it contains a large list of Sinclair/Timex supporters, users groups and dealers who can still provide you with ZX81 hardware and/or software. Over 250 copies of ZX-91 #1 have already been sent and more are being sent each month. To obtain the latest issue, or more information, send a note together with a self-addressed envelope plus IRC to: Andre Baune, 304 Scott, Chateauguay, Quebec, Canada J6J 4H5. And do me a favour, will you? Please mention where you got the information about ZX-91 from! XTENDER RELEASE HISTORY & FUTURE Version Date Remarks 0.07 October 1991 First documented pre-release. 0.64 June 1992 Available via SIMTEL20 fileserver, New Mexico, USA. 0.93 January 1993 Current version. < 1.00 Successive preliminary versions, likely to contain undocumented features and bugs. Use at your own risk or write me to become a registered XTender user. 1.00 February 1993 First official release. FINAL NOTES All rights of XTender and this manual reserved by law (copyright); Consequently: UNAUTHORIZED copying, hiring and lending prohibited (please refer to section "Registration" for more details). Just to keep the lawyers happy: ZX, ZX81 and QL are registered trademarks of Sinclair Research Limited. For more information on XTender, XTricator, QZ, ZX-Assembler-2, Coral Basic Interpreter or the ZX81 in general, do not hesitate to contact me at subjoined address in writing: Carlo Delhez, Emmastraat 3, 4651 BV Steenbergen, Netherlands. via E-Mail on Internet: tnndcarlo@cycl.phys.tue.nl (until May 1994) Thank you for reading the manual & for using XTender !! Any suggestions for the development of new, innovative PC software from scratch are welcomed (assembly language programming only!). ------------------------------------------------------------------------------ PLEASE READ THE FOLLOWING MESSAGE ONCE MORE !!! XTender contains the original ZX81 ROM code. This code is copyright software. Therefore, XTender may ONLY be used by you if you own a ZX81 YOURSELF. In that case, you are IN PRINCIPLE able to LEGALLY transport the ROM code from your ZX81 to your PC. Any usage of XTender by people NOT owning a ZX81 is in conflict with copyright laws. ------------------------------------------------------------------------------ <*** End of File ***>