NutEm/PC — A Nut Firmware Interpreter Built On ooREXX/Win

Install it

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

NutEm/PC 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 NutEm/PC to your flavor without console window.

Start ooNUfip.rx either by

• open a command window in the directory where you installed NutEm/PC 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 NutEm/PC 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.

NutEm/PC 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) induces a complete reset (MEMORY LOST) of HP41. With a PANAME ROM plugged one of '.,AKMTV' are also operatively, see Appendice ON of its manual.

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

Connectivity

Controls of this program

Keys: F1        - show this help file (if your PC affiliated suffix HTM 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 clipboard,
      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,
      Underscores in the button's caption denote which key will press it (see note 1).
Buttons: Same as role model.
System Menu: Underscored letters indicate which key will launch an option
      Quit w/o saving RAM      - ends NutEm/PC keeping RAM of previous session
      Reset Nut cycles counter - zeroes CPU counter
      Show program...          - displays user program (see note 2)
      Copy figure as displayed - copy display to clipboard
      Copy complete X-register - copy X-register full precision clipboard
      Paste number to X-register - use clipboard content as input (note 3)
      More details...          - same as F1
      About...                 - guess what...

Notes:

1. The buttons' caption change according the shift status and with it the acceleration keys. On HP41 shift and alpha is relevant, on Voyagers it is f-shift, g-shift, user mode.
2. This menu item is only available for Voyagers, to list programs on an HP41 use a printer.
3. 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.)

Besides the easy handling by keyboard or mouse the later offers two additional options:

• For the HP41 hit-n-hold is an important element of the man-machine-interface. For most keys (ON is one of the exeptions) keeping a key held down it first shows the function it will execute, and, if still held down for a moment, NULL will be displayed to indicate, you may release the key now with no further action than NULL disappearing.
  The Voyager models offer hit-n-hold for few keys only to allow a prolonged readout, e. g. 'View Mantissa' (Clr Pref) or MEM (storage status).
   
• {ON+key} is a gesture for rarely used features like changing the decimal separator on Voyagers or reset HP41 to factory-set. This option is available if the simulated machine is off, if the Ctrl key is held down, with a right mouse click (if reversed 'the other right') to the calculator's button in question. (Paname ROM is respected.)

About The ROMs

for HP41

within V41 and here and there, and if still not enough more here;

for the Voyagers

here and there, see also on this pen drive.

NutEm/PC uses ROMs in a "human readable" format as shown above, columns 1..4 address, column 5 blank or a colon, columns 6..8 command, address and command values in hex. If comments follow they may start minimum at colum 10, separated from commands by one or more blanks. So ZEN ROM decoder print-out will do.

The ROMs that come with NutEm/PC bundle are unchanged for HP41, patched for Voyagers to fix a stack-lift bug in HP-11C and -16C. In addition you may apply a pause patch to get – regardless the speed of your PC – a 1.2 seconds delay for PSE, MEM, and View Mant (by ClrPref). To do so replace the C=C-1 X in the delay loop by 1F0, an invalid opcode. Following an example for the HP11C, similar at different spots for the others.

original:                   patched:
0D11 046 C=0    X           0D11 046 C=0    X
0D12 21C PT=    2           0D12 21C PT=    2
0D13 210 LC     8           0D13 210 LC     8
0D14 266 C=C-1  X           0D14 1F0 ** loop patch **
0D15 3FB JNC    -01 0D14    0D15 3FB JNC    -01 0D14

The Time Chip Simulation

My reasoning is, when executed in a simulation Nut CPU commands all take different period of time due to their complexity and implementation, moreover the simulation runs on a multitasking system with its typical uncertainty. So it is quite impossible to have the simulated time chip in sync with the wall clock time of the host-PC. Consequently I use the virtual Nut CPU as time standard, 64 command cycles (word time) take 1/100th second, no matter how long this lasts. By that the very pernickety service ROM passes all tests and shows TIME IC OK after all. Neither test content nor addresses are stored within the time chip simulation, otherwise I could fake the test entirely by jumping to the wanted result at once.

Without service ROM, time and date of the host-PC are master, what makes SETIME and SETDATE of virtual HP41 useless.

Features, Constraints, Known Bugs

Features worth to mention:

Hit-n-hold — the important element of the user interface, functional when using the mouse to operate the calculator (if you prefer to handle by key board you probably like it speedy, hence no hit-n-hold at this),
{ON+key} available by Ctrl + right mouse button,
key captions changing with shift status,
fuzzy logic for pasting numbers,
41's beeper someway imitates the role model only but at least you are warned when typing the 24th character in alpha,
executing TIME CHIP test of service ROM 2A shows "TIME IC  OK" - hooray!
Time with SW (stop watch) and alarms — accurate to a fifths of a second (that is the pace maker's watch frequency at idle time),
HP41 with 82143A printer – translating 'synthetics' to human readable, eg. RCL M in place of RCL [ like the role model,
Voyager program listings shown with HP41 style mnemonics,
trace log shows display changes and read values of RDROM what simplifies to locate code sections,
in trace log POWOFF is shown correctly as two byte command,
modification of setup with ease using the text editor of your choice.

Constraints, missing, annoying:

The surface looks nasty — by design, to make it distinguishably different (nevertheless NutEm/PC is an emulator of the CPU-simulating kind),
no graphic on 82143A printer — use my oo82162A IL2IR bridge, works best with IL-enabled V41,
no HP-IL for now — instead use Emu41 or V41,
NutEm/PC 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:

Not all bugs are fixed, two showed only once and never again, so they could bite once more. Another one bites at fast scrolling (using the mouse wheel) a list of LIF disk dumps. I should implement a throttle to limit new requests for time-consuming evaluation of LIF disks.

So you are warned, do not use NutEm/PC for serious work, don't even think about it. I programmed it only to get some insight and nice trace logs, nothing else.

Manuals of the role models

HP41

HP-41CV Owner's Handbook and Programming Guide
HP-41CX Quick Reference Guide
In case you like to know more there is a torrent about almost all HP41.

Voyager

HP-10C Owner's Handbook
HP-11C Owner's Handbook and Problem Solving Guide (PDF, 11 MB)
HP-12C Financial Calculator User's Guide (PDF, 2.1 MB)
HP-15C Owner's Handbook (PDF, 6.5 MB)
HP-16C Computer Scientist Owner's Handbook (PDF, 2 MB)

The fine print

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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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

No Warranty

Choice of Law