                      emu3300 version 0.3 -- 12/xx/07

Here are some quick notes on the emulator
=========================================================================
What is emulated:
    front panel
    TTY w/paper tape reader and punch

What is not emulated:
    cassette tape system

The front panel tries to follow the behavior described by the
3300 Reference Manual.  Namely:

There are three modes of operation.

    --- ENTER MODE ---

    Press the Enter button to start ENTER mode.

    Enter a byte of data by pressing the right combination of data buttons.

    Press one of the B/C/Z/A/S/M buttons to deposit that data value into
    the corresponding register.  The new value will show up on the lamps
    on the front panel.

    If you want to modify memory instead of a register, set the address
    you want to modify by entering the right value into the B and C
    registers.  Then enter the data value you want via the data buttons,
    and press the Core button.  This will deposit that value into the
    location in memory indicated by BC, and BC will be incremented by 1.
    Thus you can enter values into successive bytes without having to
    manually set BC for each address.

    One can also execute an arbitrary instruction directly from the
    front panel in ENTER mode using the ExQ button, but that won't
    be described here.

    The meaning of the Load button in Enter mode is not well described
    in the reference manual.  Instead, I have done somethign else useful.
    In Enter mode, pressing Load causes the tape bootstrap loader to be
    copied into memory at location 0000, saving the work of having to
    toggle it in manually.

    --- DISPLAY MODE ---

    Because the B/C/Z/A/S/M registers are always displayed directly on
    the lamps, this is really only useful for displaying memory values.
    Use the Enter mode to establish a BC value for the location you
    want to inspect.  

    Press the Display button to start DISPLAY mode.

    Press the Core button; the value at that given BC location will appear
    in the set of Memory lamps, and the BC value will be incremented by 1.
    Thus you can view successive locations by repeatedly pressing the
    Core button.  Note that because BC increments after the data is fetched,
    the BC value will be one count past the address corresponding to the
    location displayed in the Memory lamps.

    --- RUN MODE ---

    Press the Run button to start RUN mode.

    After getting a program loaded into memory, enter the correct starting
    address into the BC registers.

    Press the Run button; nothing happens yet.  Pressing the Go button
    causes the program to begin free running.  Instead, you can press
    the Step button to make the program step one instruction at a time.
    If the program is free running, pressing Step will stop the program.
    You can then press inspect or modify memory, or press Step again
    to single step, or press Go to start free running once again.

=========================================================================
Using the emulator

Because the emulator doesn't emulate the cassette tape, you can't follow
the boot process through to the point of loading BASIC.  I've done a
sloppy job of hacking the bootstrap process to get BASIC running, although
I'm not confident that things are really initialized exactly as they
should be.  The memory image at the point where BASIC is about to start
has been saved to a file called basic_28K.hex.  This can be loaded and
run directly, avoiding the bootstrap process.

Running hello.hex (a simple hello world program)

Intel .HEX files can be read into memory via the File menu on the
front panel window.  I've loosened the spec for what a HEX file should
look like such that I allow comments to be embedded in the .HEX file.
View "hello.hex" in your text editor, for example.

From the front panel File/Load Hex... menu, select hello.hex.  Then
press the Enter button to start ENTER mode.  Enter the value 01 (hex)
into the data buttons, and press the B register button.  This is because
the program begins at address 0100.  Then press the Run button to enter
RUN mode.  Next press the Go button.

You should see "HELLO WORLD!" appear on the tty window.

You can try loading echo.hex and run it too, also at BC=0100.  This
polls the TTY for any keystrokes and echos them back.

Running BASIC.

If a program is currently running, stop it by pressing the Step button.
From the front panel File/Load Hex... menu item, select the file named
basic_28K.hex.  Use the ENTER mode to establish BC=4200.  Enter the RUN
mode, and press the Go button.  You should see this:

3300 BASIC READY
:

Have fun.

=========================================================================
Running BASIC with two terminals.

1) start emulator
2) select system/configure from the front panel menu
3) select 2 terminals
4) hit OK
5) from File/Load Hex..., pick the file BASIC_60K_2term.hex
6) enter ENTER mode (hit Enter button)
7) select hex 0x42 with the data buttons
8) hit the "B" register button to set the B register value
   (that is, BC now equals 4200, the starting address of BASIC)
9) go to RUN mode (hit the Run mode button)
10) hit the Go command button

In Terminal 1 you should see
    3300 BASIC READY
    :

Terminal 2 doesn't do anything.  Put your mouse over Teriminal 2 and
hit the ESCape key.  You should also get the READY prompt there.

=========================================================================
Configuring BASIC to your liking

1) set up the system with the desired number of terminals and amount
   of RAM, via the System/Configure menu.  For now I'll assume you have
   chosen 64 KB of RAM.

We'll skip the multistep boot process and go the quickest route.

2) Load the PARTGEN program via the File/Load Hex... menu, choosing
   the 02partgen.hex file.

3) If the last page of valid memory in the system is, say, 7F (32 KB),
   then reduce this by one: 7E.  Enter this into location 2F43.  This
   is referenced by PARTGEN in building the BASIC program image.

    3a) Hit the Enter mode button to get into ENTER mode
    3b) make sure the data buttons contain the value of the next to last
        page of memory (or the next to last page of memory you want BASIC
        to use), for example 7E.
    3c) select the B register button.
    3d) set the data buttons to hex 43
    3e) select the C register

4) Normally PARTGEN jumps back to the (presumed resident) TCLOAD program,
   but since that isn't in memory, we have to force PARTGEN to halt.
   Set location 05BA to 00.
   Set location 05BB to BB.
   This causes the program to halt when it is done.

5) set BC = 0000

6) select the Run mode, and press the Go button.

7) answer the questions that PARTGEN asks.

8) the front panel lamps will stop (with BC=05BA, otherwise something has
   gone wrong)

9) load BASIC from the File/Load Hex... menu, and choose 03TCXBASIC.HEX

10) if you want, save this preconfigured memory image to a file, via the
    File/Save Hex... menu item.

11) set BC=4200

12) set Run mode, then press Go

Later on you can reload that preconfigured memory image via File/Load Hex...,
then set BC=4200, Run, Go.

=========================================================================
Paper tape

From the TTY screen, select the menu item Display/Show papertape.
This causes a panel to appear at the top of the window.  From here you can
use the Browse button to "mount" a paper tape that is mapped to a normal
file.  There is presently a bug where the emulator won't let you create a
new empty file for punching.  Instead you have to manually create a zero-
length file and then you can punch to it.

While the reader seems to work, I haven't had reason to test the punch
much.

=========================================================================
Known problems.

When a program is running, pressing the ESC key aborts it.  Sometimes
(often) this causes the emulator to fire an assertion.  It has detected
the code trying to do an I/O operation to an address where there is no
device.  Thus, don't use this feature if you can avoid it.

The TTY "left arrow" key maps to 0x5F, which on modern keyboards maps
to the underscore character.  You can use this key to logically erase a
character that you entered, but it will show up as an underscore for now.

=========================================================================
Changes to version 0.3:

*) source code change: the wang logo is held in a compiled-in data
   structure, instead of coming from an external file.

*) fixed a bug in term3315_kbd: the IACK code was looking for the status
   code to be 0xB instead of 0xB0.

*) fixed a bug in term3315_kbd: AKI handling as a side effect was killing
   off the keyboard status callback.  that lead to a problem (the paper
   tape reader might queue up another character, yet CIOJ appears later
   and then wants to clear the status of the character just kicked off).
   AKIJ now clearst status, but doesn't notify the paper tape reader about
   it and lets either CIOJ or the eventual status timeout to do the job.

*) improvement in term3315_kbd: the manual says that they keyboard status is
   cleared back to 0x00 two bit times after the status changes to 0xB0.  This
   was causing problems in the emulator, and empirically changing this to 2.5
   bit times got rid of that problem.  However, another part of the spec
   mentions that the real timing is 1.5 bit times (13.5 ms); so I changed the
   delay to that and indeed the problem doesn't occur with that setting either.

*) improvement in term3315_kbd: the keyboard interrupt request was being
   cleared on CIOJ, but the manual actually never mentions this, so it has
   been removed.

=========================================================================
Changes to version 0.2:

*) added System/Configure ... menu to front panel UI.
   This allows specifying:
        whether the CPU speed should be regulated
        how much RAM is in the system
        how many TTYs are attached
        how many cassette drives are attached (though not yet emulated)

*) to reduce the burden of refreshing the display so often, the front panel
   lamps are updated at 30 Hz instead of 60 Hz.

*) when running in unregulated mode, the lamps are updated at 30 Hz of real
   time; when running in regulated mode, the lamps are updated at 30 Hz of
   simulated time

*) the lamps now model thermal lag (ie, they don't go from 0->100% in a
   single refresh interval).  I don't know if it is noticable, but it is
   also cheap to do, so I did it.

*) removed the page break indicator from the TTY paper, since they used
   continuous roll paper.

*) you can now create a new file to punch to, and it works (before you
   had to create a 0-length file)

*) the punch now interprets XOFF properly -- it was looking for 0x13,
   but it is sent with even parity, so it arrives as 0x93.

*) reenabled reporting of CPU stats on the frontpanel statusbar

*) slightly increased the period before the keyboard ready state auto-
   resets.  the manual says it resets after two bit periods, but I was
   seeing cases where the state was changing in the interrupt handler,
   causing problems.  By making it 2.5 bit periods, I don't see that
   probably anymore.
