Nonpareil - a calculator simulator
Copyright 1995, 2003, 2004, 2005, 2006 Eric L. Smith <eric@brouhaha.com>
$Id: README 1051 2006-10-31 06:25:09Z eric $

-----------------------------------------------------------------------------

News:

Release 0.78 fixes a build problem due to missing semicolons in
kmly.y (which only were noticed by certain versions of bison),
and eliminates the need for a X server to be available at build
time.

In this release, the following calculators are simulated:
	HP-35, HP-45, HP-55, HP-80
	HP-21, HP-25
	HP-31E, HP-33C, HP-34C, HP-37E, HP-38E, HP-38C
	HP-41CV, HP-41CX
	HP-11C, HP-12C, HP-15C, HP-16C

Many menu commands are not yet implemented.

Known bugs and deficiencies:

* The HP-41CX clock runs at very close to real time, but it does not
  currently initialize the calculator time and date from the host,
  nor track the host time and date.

* The HP 82143A printer paper advance button does not work correctly in
  program mode.

* The HP-55 simulation does not correctly support user registers
  .0 through .9.

* There may be problems with searches for labels in the HP-34C.

-----------------------------------------------------------------------------


Background:

Nonpareil is a microcode-level simulator for electronic calculators.
Currently it is able to simulate some of the HP calculators introduced
between 1972 and 1982.

The HP-35, the first of HP's classic series of handheld calculators,
was introduced in 1972 and described as the "Electronic Slide Rule".
The HP-35 was a non-programmable scientific, and was followed by the
HP-45 improved scientific calculator, the HP-65 scientific
programmable with card reader, the HP-55 scientific programmable with
stopwatch, and the HP-70 and HP-80 business calculators.  All of these
calculators used essentially the same processor, which was also used
in the HP 3380 Integrator, the HP 5830 and HP 5840 Gas Chromatographs,
and the HP 1722 Oscilliscope.

In the HP Classic series processor, unlike modern microprocessors,
various instructions were interpreted by various chips.  The core
processor consists of the C&T (control and timing), A&R (arithmetic
and registers) and the ROM or QUAD ROM chips.  Additions chips may be
present for data storage or program storage.  Since different
calculator models have different combinations of these chips, some
instructions are not available on all models.  For instance, the
"delayed select" instructions are probably not implemented in the
HP-35 and HP-80 which use single ROMs, and the "search for label"
instruction is only available in the HP-65.

The design of the processor and the instruction set are described in
detail in United States patents 3,863,060 and 4,001,569.

In 1975 HP introduced their second generation handheld calculators,
known internally as the Woodstock series.  These use an improved
processor architecture described in the article "Inside the New Pocket
Calculators" in the November 1975 issue of Hewlett-Packard Journal.
An online copy of this article is available from the Museum of HP
Calculators:
        http://www.hpmuseum.org/journals/woodb.htm

In 1978, HP introduced their third generation handheld calculators,
known internally as the Spice series.  These use essentially the same
processor architecture as the Woodstock series, with the addition of
an instruction to checksum a 1K region of ROM, used as part of a
self-test feature.

In 1979, HP introduced their first expandable scientific handheld
calculator, the HP-41C (Coconut).  It was the first calculator to use
the Nut processor architecture, which was also used in the Voyager series
(HP-11C, HP-12C, etc.) introduced in 1981.

-----------------------------------------------------------------------------

Nonpareil simulator:

Nonpareil uses the GTK+ 2.x toolkit and the Glib 2.x and libxml2 libraries.

Nonpareil uses a single command line argument to specify the KML file.
If no argument is found, nonpareil will try to find a file using the
concatentation of the name under which it was invoked and ".kml".
This allows you to (for instance) link nonpareil to "hp45" and have it
automatically try to use "hp45.kml".

Nonpareil attempts to run the simulation at the same nominal rate of
microinstruction execution as a real calculator, e.g., 3500
microinstructions per second for an HP-55.  The HP-55 used a crystal
oscillator, but most other models used an LC oscillator which was not
very accurate.  On a computer that is heavily loaded, the
microinstruction rate will be reduced, so the HP-55 timer mode (and the
undocumented HP-45 timer mode) will run slow.  Don't blame me if you try
to use it and burn your eggs.

If you want to use the undocumented timer mode of the HP-45, there are
comments in hp45.kml explaining the change necessary to that file.  On
a real HP-45 this feature was accessed by pressing RCL then the "right
half of the ENTER key".  The ENTER key actually covered two switches,
but the key was shaped so that it only pressed the left switch, and
the ROM was written so the right switch would provide the ENTER
function as well as allowing use of the timer mode.  It was possible
to either put a shim on the key, or to create a a phantom keystroke by
simultaneously pressing CHS, 7, and 8.  Nonpareil doesn't support multiple
key presses at all, so the KML change makes the simulator's ENTER
button produce the keycode for the right switch.

-----------------------------------------------------------------------------

Uasm microassembler:

Uasm requires a command line argument to specify the source code file
name, and optional arguments to specify object and listing file names.

The object file format is one word per line with the five digit octal
address, a colon and the instruction word in hexadecimal.

I personally prefer my assembly source code to be in all lower case,
so it doesn't look like it is shouting at me.  All the source code I
have typed in from patents is in lower case, but uasm is case
insensitive so if you prefer emphatic source code be my guest.

Uasm considers the keywords which are used to form instructions to be
reserved words, so they can't be used as labels.  HP's assembler was
more flexible in this regard; I had to change the label "go" in the
HP-55 source code to "go_".

Uasm does a better job of displaying the branch target addresses than
the HP assembler did.  It will actually show the correct target
address based on the delayed select instructions, unless the delay
instruction is in the last word of a page.  Uasm has a ".rom"
directive which can be used to provide the rom number.  This is
roughly equivalent to the origin directive in a typical assembler,
except that uasm always start assembling code at location 0 of the
selected ROM.

Because HP assembled each ROM separately, they were able to use the
same symbols in multiple ROMs.  uasm therefore has a separate name
space and keeps a separate symbol table for each ROM.

Uasm has a .symtab directive which causes the symbol table to be
printed to the listing file.  If the source file contains multiple
ROMs, each ROM should have its own .symtab directive.

The file "hp55.asm" when assembled with uasm will produce one warning,
which will be printed to standard out twice (once during each pass).
This warning can be ignored as it is the result of uasm being pickier
than the HP assembler about forms of the "go to" instruction.

-----------------------------------------------------------------------------

82143A Printer Notes:

Nonpareil can now simulate an 82143A printer, though the printer
support should be considered to be of pre-alpha quality.  The printer
output is shown in a window, and can be saved as a PNG file.  The
MAN/TRACE/NORM mode switch and PRINT and PAPER ADVANCE buttons are
shown in the printer window.  Do not use the PAPER ADVANCE button in
program mode, as it does not work correctly and will result in a
persistent "paper out" error.

Start up Nonpareil with the command "nonpareil 41cv".  On the
Configure menu, select "Load Module", and choose the module file
containing the printer firmware, normally "82143a.mod".  A "Printer"
window will appear.  If you execute "FS? 55" the display should show
"YES", indicating that the 41 recognizes the printer.

-----------------------------------------------------------------------------

Runtime dependencies:

			minimum		recommended
			version		version
			-------		-----------

    gtk			2.0		2.4.14
    gdk			2.0
    gdk-pixbuf
    glib				2.4.7
    libxml2				2.6.16
    libSDL				1.2.7
    libSDL_mixer			1.2.5

-----------------------------------------------------------------------------

Installation:

The file INSTALLATION provides instructions for configuring, building,
and installing Nonpareil.

-----------------------------------------------------------------------------

Credits:

Nonpareil was originally written by Eric Smith.  Any bugs in it are
my fault.

The full list of credits is getting long, so it is now in the file CREDITS.

-----------------------------------------------------------------------------

Ports:

David Hicks translated the earlier csim HP-45 simulator to Java:
        http://www.hpmuseum.org/simulate/sim45.htm

Jonathan Purvis ported csim to PalmOS:
        http://one-two-three-four-five.com/palm/csim/

Maciej Bartosiak ported the earlier nsim HP-41CV simulator to MacOS X:
	http://homepage.mac.com/mba/nsim/

-----------------------------------------------------------------------------

Notices:

Nonpareil is not an HP product, and is not endorsed or supported by HP.

Nonpareil is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 as
published by the Free Software Foundation.  Note that I am not
granting permission to redistribute or modify Nonpareil under the
terms of any later version of the General Public License.

Nonpareil is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program (in the file "COPYING"); if not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
MA 02111, USA.
