		       emu3300 version 0.6 -- 2012/07/30

=========================================================================
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
=========================================================================

*) 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.

*) When a program is running, pressing the ESC key aborts it.  Sometimes
   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.  I'm not yet sure if this is an emulator bug or a bug in the
   Wang 3300 BASIC interpreter.

=========================================================================
Changes for version 0.6 (2012/07/30):
=========================================================================

*) created notes on how to build the emulator, as much for me as for
   anyone who wants to build it themselves.  It is "building.txt".

*) built the final binary using MSVC 2008 to reduce the probability of
   runtime library issues.

*) using latest libraries:
    libctb 0.16
    pixman 0.26.2
    cairo 1.12.2
    wxsvg 1.1.9
    wxWidgets 2.9.4

=========================================================================
Changes for version 0.6b (2012/04/15):
=========================================================================

*) the front panel window now restores its previous size at startup

*) tweaked the size and position of the labels and buttons on the front
   panel

*) added information to the "About" dialog box indicating all the
   libraries used by the emulator, and their version numbers

*) memory leak in wxSVG library was fixed

*) added icon resource to exe file.

*) the emulated ASR-33 doesn't print anything for characters
   0x00, 0x7F, and 0xFF.

*) added versioninfo resource to exe file so that if you view the .exe
   file properties, you'll get something useful.

*) a new file, "options.h", contains compile-time program options.
   now it is possible to disable the ability to associate a real serial
   port with a terminal if it isn't desired.

=========================================================================
Changes for version 0.6a (2012/03/31):
=========================================================================

*) the front panel drawing code was completely overhauled.  rather than
   using stock widgets, the front panel is now drawn using svg which is
   scaled to the current screen size.  While it is more faithful to the
   look of the real hardware, it is less efficient of screen real estate,
   and some of the labels are harder to read.  Oh, well.

*) all the code has had a Creative Commons "Zero" license.  Essentially
   it means it is put into the public domain and I have no claims on it.
   use the code in any way you see fit, and no attribution is necessary.

=========================================================================
Changes for version 0.5 (2012/02/04):
=========================================================================

*) this was just an official snapshot after a series of incremental changes
   for the unreleased 0.4 series.

=========================================================================
Changes for version 0.4 (late 2011, early 2012):
=========================================================================

*) It is now possible to associate a com port with a terminal, with
   selectable link settings.  This is controlled from the "System/Configure"
   menu on the window for the cpu front panel.  This dialog has a button
   like "Config Term #1" -- click it and you can turn on and off the
   association between a given terminal and a real serial port.

   The defaults are to use COM1, 110 bps, 8N2 (8 data bits, no parity,
   two stop bits).

   The emulator is using the ctb library
       https://iftools.com/opensource/ctb.en.php
   to provide cross-platform serial port access.

*) improved the appearance of the About dialog box

*) I'm now using a new library function (wxStopWatch) for measuring the
   real-time clock with greater accuracy.  The lib notes say that certain
   windows xp machine configurations might have problems with this function
   if they don't have a certain microsoft patch installed:
       http://support.microsoft.com/?id=896256

*) Using the latest wxwidgets library, version 2.9.3

*) some code clean-up

=========================================================================
Changes for version 0.3 (2007/12):
=========================================================================

*) 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 for version 0.2 (2007/11/18):
=========================================================================

*) 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.

=========================================================================
Changes for version 0.1 (2007/10/09):
=========================================================================

*) initial version
