Nonpareil - a calculator simulator
Copyright 1995, 2003-2006, 2008 Eric Smith <[email protected]>
$Id$

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

News:

Release 0.78 adds support for the 22 and 27, and sound output for the
41 family.  A 15X model is provided, which is a 15C modified to have
more RAM available to the user.

Errors in the KML files that caused spurious decimal and comma
displays have been corrected.  Instead of separate KML, ROM, and image
files for each model, there is now a single .ncz file which is a zip
file containing those files.

In this release, the following calculators are simulated:

	Classic series:    35, 45, 55, 80
	Woodstock series:  21, 22, 25, 27
	Spice series:      31E, 33C, 34C, 37E, 38E, 38C
	Nut series:        41CV, 41CX
	Voyager series:    11C, 12C, 15C, 16C

	Modified Voyager:  15X

Many menu commands are not yet implemented.

Known bugs and deficiencies:

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

* The 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 82143A printer paper advance button does not work correctly in
  program mode.

* The 27 color scheme is wrong.

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


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.

Most of the Nonpareil package is distributed under the terms of the
Free Software Foundation's General Public License, version 2.
However, some of the associated files, particularly the ncd directory
tree and the .ncd and .obj files generated from files in that tree are
instead covered by a Creative Commons Attribution Sharealike 2.5
license.  See the accompanying file COPYING for more detailed
information.

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 NCZ 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 ".ncz".
This allows you to (for instance) link nonpareil to "45" and have it
automatically try to use "45.ncz".

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 a 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 55 timer mode (and the
undocumented 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 45, there are
comments in 45.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
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 "55.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:

Nonpareil depends on a number of libraries commonly available on Linux
systems.   The minimum recommended versions of these libraries are:

    gtk+, gdk, gdk-pixbuf	2.12.8
    glib			2.14.6
    libxml2			2.6.32
    SDL				1.2.13

Later versions of libraries will probably work.  Earlier versions
might work, but have not been tested.  The author will not offer any
assistance in using Nonpareil with earlier versions.

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

Installation:

The file INSTALL 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.