ooNUfip — A Nut Firmware Interpreter Built On ooREXX/Win

Abstract:
ooNUfip copies the logics of a Nut CPU to interpret the firmware of HP41 and Voyager calculator models. It is the PC migration of my NutEm written in FORTRAN running since decades on "real iron" under VM/CMS. Today ooNUfip may still serve on PCs as a simple toy for tests without need to be compiled, just edit and run.

Reason for this update: two bugs fixed, (i) copy of X register on 16C in integer mode crashed, and (ii) a NOP directly after a skipped XQ effectuated a RTN as well.

Note: afore running this program read the QPL public license in section 7.

TOC:

A Brief Description
Prerequisites, Install and Run it
Connectivity
Controls of This Program
Features, Constraints, Known Bugs
Manuals of The Role Models
The Fine Print

A Brief Description

Once upon a time Hewlett-Packard sold pocket calculators based on a proprietary "Nut" CPU. This CPU worked in famous HP-41C/CV/CX and the "Voyager" series HP-10C, -11C, -12C, -15C, and -16C. With the time the firmware of these machines leaked out what resulted in emulators, simulations, virtual remakes. ooNUfip is a great grandchild of those, and in contrast to my NutEm on the mainframe I call it now a firmware interpreter.

The HP41 series is extensible by many plug in ROMs and devices. ROMs add more firmware or additional software or both and run at once in this program. Devices add some special hardware which needs to be simulated to work in a remake. Within ooNUfip only two devices are implemented currently, the Time Module (partly at least) and the HP-82143A printer (w/o graphic). Enough to play a bit.

Once triggered by a contribution in a PPC Journal (from a Grecian author IIRC, pieced in almost unintelligible English so the editor mocked about it, describing – what I assumed to grasp – how to simulate a calculator by rebuilding the limited set of CPU instructions instead of re-program the floods of functions from plug-in modules), I programmed about two decades ago (in FORTRAN and on a mainframe) a logical simulation of the Nut CPU. Now I ported it to ooREXX under Windows. The idea is to run the calculators' firmware in an facile to program interpreter that does not need to be compiled only to test a little add-on. So I hope it will be easier to simulate more devices.

Today the goal is not to be a better emulator than the well known but to have a toy that serves as a simple aid for testing. For some time now there exist other quite suitable simulations/emulators/virtual remakes of those HP calculators prolonging their time of use. Nonetheless I publish my ooNUfip firmware interpreter, may be someone else may find it practical too to do something with it.

Prerequisites, Install and Run it

To run ooNUfip you need (in brackets what I used for the development):

Windows (W7 Home Premium SP1),
Open Object REXX (V4.2.0), see oorexx of "Open Object Rexx",
ooDialog (V4.2.3), see ooDialog of "Open Object Rexx".

To run under ooNUfip any of the a. m. calculators you do need copies of its firmware (ROM). For your convenience I add following for a first try.

Voyagers:: 11C and 16C (virtual remakes of 12C and 15C are available from HP in here)
HP41: version GFF
HP41 add-on: Time, 82143A printer, The HP-41 Advantage Advanced Solutions Pac, and PPC ROM.

Note: I do know this files contain software which could still be protected by copyright. In the hope all authors may be proud to see their work still in use, I enclose it with my firmware interpreter. Please see also Acknowledgments in the Advantage manual and PPC ROM documentation.

Install it

There is no automated installation procedure. Unzip ooNUfip.ZIP to a directory named at will, a directory of its own or not, it's up to you.

Note: Keep the organization of subdirectories, 'HTML' at least, otherwise you have plenty to trim in the CFG files. If you move 'HTML' or its content you even have to modify the program or hit F1 is of little help.

First Run and Subsequent Runs

Open ooNUfip.CFG first using a text-only editor of your choice and if necessary adapt it to your installation. For further explanations see comments therein. In future do this step for modifications only. To have a distinct CFG file for a different model I suggest to file it with a new name you may use as option when starting ooNUfip.

ooNUfip is a console application which displays some information, warnings and trace output only on the console window. "Real" errors will be shown in a dialog in the middle of the screen. If not interested in those informations of minor importance, you may prepare one or several shortcut links which start ooNUfip to your flavor without console window.

Start ooNUfip.rx either by

open a command window in the directory where you installed ooNUfip and enter (without quotes) "ooNUfip" or "REXX ooNUfip.rx", it depends on your choice of suffixes at installation of ooREXX,
start the windows explorer, navigate to the directory where you installed ooNUfip and double-klick ooNUfip.rx or right-click it and select open
(alas drag-n-drop of a CFG file to the REXX program does not work),
single-click a shortcut link you prepared before.

ooNUfip optionally takes one argument and/or several options (one at a time). More tailoring is done within an CFG file.

       [REXX] ooNUfip[.rx] [CFG-fileID] [ #KEY]

CFG-fileID: a file-ID or name of a CFG file ('.CFG' will be appended if missing), default is 'ooNUfip.cfg'.
KEY: Separated by ' #' (blank and "Gartenzaun", garden fence) one single designation representing a key that will be "held down at on time". Meaningful for the Voyagers are one of ',./*-+' (dot or comma to change the decimal separator, dash to get a reset, slash for a keyboard test, the rest for single or endless self-testing). 'BA' (back arrow) should provoke a MEMORY LOST with an HP41, alas... in a future version.

For subsequent runs you don't need to edit CFG files unless you like to change something.

Connectivity

This version of ooNUfip is not equipped with neither Virtual HP-IL nor access to the IR printer simulation. So for now there is no need to talk about connectivity.

Controls of this program

System Menu: Underscores indicate which letter typed will launch an option
      Quit w/o saving RAM      - ends ooNUfip preserving RAM of previous session
      Reset Nut cycles counter - zeroes CPU counter
      Show program...          - displays user program (see note 1)
      Copy figure as displayed - copy display as text to clipboard
      Copy complete X-register - copy X-register full precision to clipboard
                                  (see note 2)
      Paste number to X-register - use clipboard content as input (note 3)
      More details...          - same as F1
      About...                 - guess what...
Buttons: Same as role model. Underscores in the button's caption denote
          which key will press it (see note 4).
Keys: F1        - show this help file (if suffix HTM is affiliated with a browser),
      F2        - displays the About information,
      F10       - activate menu (HP41 only),
      Shift+F10 - (also Shift+M) activate menu (Voyagers only),
      Ctrl+C    - copy display to clipboard,
      Ctrl+X    - copy X-register full precision to clipboard (see note 2),
      Ctrl+V    - use clipboard content as input (see note 3),
      Backspace = Back Arrow,
      Pause     = Enter,
      End       = R/S,
      Return    - hit the selected button,
      Esc       - ends the program.

Notes:

This menu item is only available for Voyagers, to list HP41 programs use a printer.
On 16C in interger mode copy X full precision puts the internal representation of the X-register to the clipboard. This is a hex value although in DEC, OCT, and BIN mode. Word size is respected.
The number from clipboard is interpreted to detect thousand's separators, comma, sign and exponent. What may not belong to the figure will be missed silently. This fuzzy logic is not perfect, so use with caution. An HP41 in alpha mode will put it as text to the alpha register, characters will be uppercased. (A ZEN ROM may disturb this process.)
The buttons' caption change according the shift status and with it the acceleration keys. On HP41 shift and alpha is relevant, on Voyagers it's f-shift, g-shift, and user mode.

A Word About The ROMs

The used ROM format is "user readable", four digits address, next word three digits command, both values in hex, with a single colon or blank serving as word separator. If comments follow they must be separated by one or more blanks. So ZEN ROM decoder print-out will do.

Those for HP41 are unchanged, the Voyager ROMs are patched for two reasons, i) to fix a stack-lift bug in HP-11C, -15C, and -16C, ii) ooNUfip.rx does not offer the hit key and hold feature. Instead some functions display a result for 1.2 seconds only, not until the key is released. This pause is done by the firmware interpreter, not by the original calculator.

Features, Constraints, Known Bugs

Features worth to mention: key captions changing with shift status,
fuzzy logic for pasting numbers,
HP41 with 82143A printer which shows 'synthetic' commands same as on 41's display, eg. RCL M in place of RCL [ like the role model,
Voyager programs displayed as user readable listings along with the well-known, annoying key codes,
41's beeper someway imitates the role model only but at least you are warned when typing the 24th character in alpha,
modification of setup with ease using the text editor of your choice.
Constraints, missing, annoying: hit key and hold is an important element of the user interface — currently missing,
no HP-IL for now — it is in the top 10 of my to do list,
the surface looks nasty — by design, to make it distinguishably different,
Time w/o SW and alarms — point 11 of my to do list,
no graphic on 82143A printer — use my oo82162A IL2IR bridge, works best with IL enabled V41,
ooNUfip is distinctly faster than the originals — albeit about 1600 times slower than the PC versions from HP (find 12C and 15C with others in this package).
Bugs: all known bugs are fixed, only two remain unknown: one inserted invalid code in a user program what made the complete RAM file useless. Another one filed RAM incomplete. Up to now those two errors showed only once.

So you are warned, do not use this firmware interpreter for serious work, don't even think about it. I programmed ooNUfip to get some insight and trace logs, nothing else.

Manuals of the role models

HP41: HP-41CV Owner's Handbook and Programming Guide,
HP-41CX Quick Reference Guide
Voyager: HP-10C, HP-11C, HP-12C, HP-15C, and HP-16C.

In case you like to know more there is a torrent about almost all HP41 (> 7 GB).

The fine print

(i) Do not use this program.
(ii) Any damage you cause with this program, intentional or by chance, is a violation of clause (i). Thus all consequences are completely at your own risk.
(iii) If you manage to improve this program you have to inform me as stipulated in following THE Q PUBLIC LICENSE (QPL).
(iv) In addition applies the QPL below:

THE Q PUBLIC LICENSE version 1.0

Everyone is permitted to copy and distribute this license document. The intent of this license is to establish freedom to share and change the software regulated by this license under the open source model.

This license applies to any software containing a notice placed by the copyright holder saying that it may be distributed under the terms of the Q Public License version 1.0. Such software is herein referred to as the Software. This license covers modification and distribution of the Software, use of third-party application programs based on the Software, and development of free software which uses the Software.

Granted Rights

You are granted the non-exclusive rights set forth in this license provided you agree to and comply with any and all conditions in this license. Whole or partial distribution of the Software, or software items that link with the Software, in any form signifies acceptance of this license.
You may copy and distribute the Software in unmodified form provided that the entire package, including - but not restricted to - copyright, trademark notices and disclaimers, as released by the initial developer of the Software, is distributed.
You may make modifications to the Software and distribute your modifications, in a form that is separate from the Software, such as patches. The following restrictions apply to modifications:
a. Modifications must not alter or remove any copyright notices in the Software.
b. When modifications to the Software are released under this license, a non-exclusive royalty-free right is granted to the initial developer of the Software to distribute your modification in future versions of the Software provided such versions remain available under these terms in addition to any other license(s) of the initial developer.
You may distribute machine-executable forms of the Software or machine-executable forms of modified versions of the Software, provided that you meet these restrictions:
a. You must include this license document in the distribution.
b. You must ensure that all recipients of the machine-executable forms are also able to receive the complete machine-readable source code to the distributed Software, including all modifications, without any charge beyond the costs of data transfer, and place prominent notices in the distribution explaining this.
c. You must ensure that all modifications included in the machine-executable forms are available under the terms of this license.
You may use the original or modified versions of the Software to compile, link and run application programs legally developed by you or by others.
You may develop application programs, reusable components and other software items that link with the original or modified versions of the Software. These items, when distributed, are subject to the following requirements:
a. You must ensure that all recipients of machine-executable forms of these items are also able to receive and use the complete machine-readable source code to the items without any charge beyond the costs of data transfer.
b. You must explicitly license all recipients of your items to use and re-distribute original and modified versions of the items in both machine-executable and source code forms. The recipients must be able to do so without any charges whatsoever, and they must be able to re-distribute to anyone they choose.
c. If the items are not available to the general public, and the initial developer of the Software requests a copy of the items, then you must supply one.

Limitations of Liability

In no event shall the initial developers or copyright holders be liable for any damages whatsoever, including - but not restricted to - lost revenue or profits or other direct, indirect, special, incidental or consequential damages, even if they have been advised of the possibility of such damages, except to the extent invariable law, if any, provides otherwise.

No Warranty

The Software and this license document are provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Choice of Law

This license is governed by the Laws of England (if not yet part of Spanish East Indies)