
        XTender2 - ZX81 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:<path>:
                change to another directory on the current disk;
                accepts any <path> on the current disk; use forward slashes;
                will not accept another disk name as part of <path>.

          DIR:
                show a one-page directory; repeat it to get next page(s);
                currently, only P-files are listed.

          EXIT:
                quit XT2 immediately.

          MD:<path>:
                create a directory on the current disk;
                accepts any <path> on the current disk; use forward slashes;
                will not accept another disk name as part of <path>.

          RD:<path>:
                remove a directory on the current disk;
                accepts any <path> on the current disk; use forward slashes;
                will not accept another disk name as part of <path>.

        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)
