Simulation of a HP21MX Minicomputer with a 7906 Disk
====================================================

7906.dsk - disk image with HP-IPL/OS and old-comp-style games and stuff
boot_7906.sim - script for setting up the simulation and booting the disk
mkdisk.zip - contains scripts and sources used to make this simulation, can
             also be used to make a 7900 version (requires hpiplos_main.zip)

This requires the SimH HP2100 simulator program, available from:
http://simh.trailing-edge.com/

If needed customized Windows and Linux binaries are at:
http://www.infionline.net/~wtnewton/oldcomp/hp2100mod.html
(these translate HP term codes to VT100, not required by the included
software unless TERMINAL used to set it to output HP terminal codes or
an ABS that uses HP codes is imported into the system. Don't have any.)

For best results put the simulator binary in a "path" directory so the full
path doesn't have to be specified in the startup command. Under Windows the
hp2100.exe file can be copied to the simulator directory (for Linux if the
hp2100 binary is in the current dir refer to as ./hp2100 in the run line).

To start the simulation, from a command prompt run: hp2100 boot_7906.sim

The simulation is set for upper-case input by default for convenience as
menu selections, confirms, HP-IPL/OS commands etc must be in uppercase.
If using the editor, press control-E in the simulator window and enter
set tty 7B then enter c to continue. The boot_7906.sim script can be
edited to make this the default setting.


Running the sim under Windows
-----------------------------
For easier running a batch file can be created, make a file named
say boot_7906.bat then right-click/edit, add the lines...

  @echo off
  hp2100.exe boot_7906.sim

...and save the file. The hp2100.exe binary must be copied into the sim
directory, placed in a "path" directory (like C:\WINDOWS), or specify the
path in the batch file.. as in: c:\somedir\hp2100.exe boot_7906.sim

Associate .sim to notepad for viewing and editing to change simulation
settings, also associate .sim to hp2100.exe to "run" .sim scripts, useful
for making copies for different setups and operating without having to
make batch files or opening a dos prompt window.

To use the FED/AEDIT editor or the LIFE demo and to avoid extra garbage
characters when running MSU BASIC, edit the boot_7906.sim file and uncomment
the lines near the beginning to set and start telnet. Should look like:

  ...
  set telnet 23
  ! start telnet localhost
  ...

The first time the sim
is run a firewall warning may pop up, tell it to unblock. Telnet might need
setting for proper operation, press control-] for the telnet prompt and enter
the following settings as needed (enter d to display the current settings):

  unset localecho          [if characters double, not needed with mine]
  unset delasbs            [make sure backspace is sent as ascii-8/ctrl-H]
  unset crlf               [send only CR when enter is pressed]
  set mode stream          [ensures every char is sent when key is pressed]
  set term ansi            [this setting doesn't seem to matter under XP]
  quit                     [must quit to save the settings]

The sim running in the sim window will halt, close the window then rerun
the boot_7906.sim script to enable the new settings.

When running BCS games in a command line telnet terminal press control-] and
enter set crlf to send CRLF line ends, avoids having to go to the sim prompt.
The HP-IPL/OS boot system is tolerent of CRLF line ends (has the !NOLF word)
but be sure to unset crlf before running BASIC games.

If desired, HyperTerminal can be used instead of the plain telnet program.
Run HyperTerminal, create a new connection set to TCP/IP to localhost port 23
and save to a settings file, for example telnet23. Find the new telnet23.ht
file and copy to the sim directory, edit boot_7906.sim and make the telnet
start line (for example): ! start telnet23.ht
After running select a vt100 terminal, if copy/pasting text etc set the
character and line delays... 10ms and 300ms should work OK when using the
SFS/EDIT build's CALOAD command. When running BASIC programs select a vt52
terminal to ignore garbage but this won't work with the editor life etc.
Make copies of the boot_7906.sim script and boot batch and edit them
accordingly to use either the plain telnet or HyperTerminal as needed.


Running the sim under Linux
---------------------------
Ubuntu and probably most Linux systems do not set the current dir to where
the files are when running, so the directory must be set using shell scripts
if not executing directly from a command terminal. For best results use the
Konsole shell terminal to run the simulation, either with the VT100 setting,
or the VT420PC setting if patching MSU BASIC to use regular backspace rather
than the stock "_" correction character. If Konsole is not available then
the xterm terminal shell may be used but its capture option isn't as useful
as Konsole's "save session" option. Note - Konsole differs between KDE 3 and
KDE 4, in particular KDE 4's Konsole requires extra parameters to set the
working directory and tell it to not fork (the latter is required if the
startup script incudes additional post-run commands after the konsole call).

The following bash script should get you started...

#!/bin/bash
# change to current dir... (remove quotes for some systems)
workdir=`dirname "$0"`
cd "$workdir"
# uncomment next line to use xterm
xterm -e hp2100 boot_7906.sim
# comment above line and uncomment next line to use Konsole...
# konsole --workdir "$workdir" --keytab vt420pc -e hp2100 boot_7906.sim

Put this in a file named (say) boot7906.sh and make executeable.
Note - if copy/pasting, use dos2unix etc to convert to unix format.

This assumes hp2100 is in a path dir such as /usr/local/bin or ~/.local/bin
and that Konsole is installed and available. Note.. Konsole is KDE-based but
works fine in my Gnome-based Ubuntu system, on which I have many KDE apps
installed. If you don't want to use Konsole there are many other Linux terms
that can be used but they'd probably have to be tweaked to work well and there
are too many possibilities to document. Other terminals such as Gnome Terminal
can be made to work but may display garbage when running MSU BASIC or cause
backspace to not work in HP-IPL/OS unless certain settings are chosen.

To permit right-clicking and "running" .sim files the following bash
script might be useful, save as (say) hp2100sim in a path dir.

#!/bin/bash
# open a .sim file using hp2100
workdir=`dirname "$1"`
cd "$workdir"
scr_name=`basename "$1"`
konsole --workdir "$workdir" -e hp2100 "$scr_name"

Associate .sim files to hp2100sim to "run" in hp2100. If your Gnome doesn't
let you associate by extension and forces every text thing on one menu like
my Ubuntu does, get Rox Mime Editor... lets you define new types to associate
separately to only the things you want.

Generally for old-comp source files, especially IPL files for HP-IPL/OS, must
have CRLF line ends. Handy tools to have associated to all text files are
unix2dos and dos2unix from the sysutils package.


Included software
-----------------
The disk boots to a menu, press a (uppercase) key to run or display the
associated file. Included programs...

CHESS - a vintage Chess game written in ALGOL (BCS, with source)
31-ODD - a vintage number game written in assembler (BCS, with source)
REVERSIX - a new Reversi game written in FORTRAN (BCS, with source)
31KW MSU BASIC - patched for single-user, no init to preserve memory
TREK - a conversion of STTR1 (BASIC)
TTY TREK - a conversion of another version of TREK (BASIC)
OTH - a new Reversi game (BASIC)
MANDPLOT - a new program that plots the Mandelbrot set, HP21xx-style (BASIC)
HAMURABI - a conversion of a city/ruler game (BASIC)
WUMPUS - a numerical version of HUNT THE WUMPUS (BASIC)
GOLF - "TIES" GOLF simulation (BASIC)
BEASTI - eat organisms and avoid being eaten (BASIC)
GOMOKU - get five pieces in a row (BASIC)
LANDER - try to land a spacecraft (BASIC)
MAZE - a maze and monsters game (IPL)
LIFE - Conway's game of life (IPL, requires VT100/ANSI console)
1DCA - a one-dimensional "line" automata generator (IPL)
ECAL - an electronics calculator (IPL)
FED - a full-screen "array" editor (IPL, req's VT100/ANSI console)
SFS/EDIT - a non-menu build of HP-IPL/OS for programming stuff

Of all these, only CHESS and 31-ODD are unmodified vintage programs.
If mods were off-limits then I'd have very little to run! But of course
modifying and writing things to run with what I have or how I want is also
part of the old-comp experience. Most of the BASIC programs were converted
from HP2000 programs from the 2000dmp5-5-84iclContrib.tar.gz file. BEASTI
was converted from a HP2000 program found on an Access system, TTY TREK
was converted from a HP2000 program found on the hp2000family Yahoo group.

CHESS, 31-ODD and REVERSIX require CRLF enters to work normally, halt and
enter set tty autolf at the sim prompt to run these, when done halt and enter
set tty noautolf so BASIC will work properly. The HP-IPL/OS systems on this
disk can tolerate CRLF enters but text formatting effects can happen.
See the NOTES text file on the disk for more terminal-related notes.

Information about the 31KW version of MSU BASIC is at:
http://newton.freehostia.com/hp/msubasic.html

The main HP-IPL/OS archive and information is at:
http://www.infionline.net/~wtnewton/oldcomp/hp2100/

The latest HP-IPL/OS "testing" archive is at:
http://newton.freehostia.com/hpiplos_main_testing.zip

This system was built using the v1.60 testing version.


Running the disk image on Real Hardware
---------------------------------------
The HP-IPL/OS builds on the disk image contain IDE drivers for running as-is
on a real HP21MX and the controller at: http://newton.freehostia.com/hp/
This page also describes a simple pass-through PTR emulator. Alternative
disk interfaces are in the planning stages, perhaps something that will
emulate a 7906 drive using a 13037 controller card, but it's probably
going to be awhile. A more immediate enhancement to the present IDE
interface is being planned - adding a USB port to permit transferring
the disk image but it is unclear at the moment whether this will take
the form of a host interface to permit reading a USB thumbdrive etc,
or a slave port to simply permit copying the disk contents to/from a PC.
Using a host interface leaves open the possibility using the USB drive
as the storage medium in addition to or replacing the IDE disk. Either way
the interface electronics probably won't change beyond hanging a pre-canned
USB interface off of the unused port F pins and changing the 8052 code.

Presently I use a USB drive tray to copy the 7906 disk image file to
the IDE disk using the Linux dd utility, specifying the option to
swap the bytes (SimH stores words as low byte, high byte whereas the
IDE interface uses high byte, low byte). More information about the
process is in the ide_buildinfo.txt in the hpiplos_main.zip file,
which also contains plans for the PTR and IDE interface and a small
ABS program for booting the IDE disk.

Theoretically the disk will boot on a real 7906 drive, but the system does
not support spare tracks etc, the media should be perfect. Copying the disk
image to a real 7906 disk isn't exactly trivial but one way to do it would
be to boot a 7906-capable HP-IPL/OS build, attach the disk image to PTR
using a pass-through emulator, then use an IPL program that reads from
papertape, blocks 1KW at a time in the correct byte order and writes the
blocks to disk. For example, the following IPL code... (tested under sim)

OCTAL DEFINE DIRESTORE
;last 1KW block = octal (image file size / 2048 - 1)
"WARNING - WILL OVERWRITE DISK!" $PRINT CRLF
"JUST ENTER TO ABORT" $PRINT CRLF
"LAST 1KW BLOCK? " $PRINT $IN $LEN IFZ $DROP ELSE
 $VAL #0 SWAP +DO
  "READING..." $PRINT
  @BLK GET DUP 1777 ADD +DO
   INDEX MSWIN ROL ROL ROL ROL ROL ROL ROL ROL PUT
  +LOOP "WRITING BLOCK " $PRINT INDEX PNUM
  #0 INDEX SBLA @BLK GET W-1K
  <IDE " STATUS=" $PRINT PNUM CRLF
 +LOOP
ENDIF MSPAPER
END
CONSOLE

...load and run a 7906 build (such as hpos7906.abs) from PTR,
attach the above program to PTR and enter LOAD, use a directory listing
to determine the exact number of bytes in the image, divide by 2048,
subtract 1, and convert the number to octal (DECIMAL [number] OCTAL PNUM)
attach the disk image file to PTR, enter DIRESTORE, enter the octal
last block, wait many hours. Might want to capture the console output
in case status isn't 0 in any of the writes. If doing more than once
might want to build a faster USB-based PTR emulator!

Regardless of how it's done, unless the hardware slot configuration is
identical the system will need to be reconfigured, including possibly
all old-comp-style binaries included with the system. This information is
in the NOTES file, read it under simulation. Unless the system is used
to run another existing OS then it's probably much easier to set it up
to use the same slots used by the simulation, at least CLK=10 and TTY=11,
CONFIG can be used to change the other slots. If booting from disk and
the disk interface slot is different the system will hang with the default
boot build, in this case halt, put 1000xx in the switch register where
xx = the TTY console interface, store, put 70 in the P register, store,
preset, run - this should produce a prompt, enter CONFIG, set the slots
that are different, clear the switch register, press preset and enter: 2 RUN
If the disk menu comes up OK then exit to a prompt and DGEN to save.
The included SFS/EDIT and any other disk builds on the disk will also need
to be reconfigured and resaved using XDEL and XSAVE, but this is easier to
do if they don't autostart a disk menu.. just CONFIG then resave.


Using the BACI device
---------------------
There is no reason I can think of to use BACI with this particular sim, the
BACI drivers in the builds are mainly for running HP-IPL/OS on real hardware,
where the slow 2400 baud console is a tad too slow for editing. Also the LIFE
demo works over BACI but the stop function is coded to detect a keypress from
the TTY console.. RENAME TTYSCAN ~TTYSCAN and RENAME TTYGET ~TTYGET so LIFE
will read the stop signal from the switch register instead.

If necessary to use BACI under sim, control-E to halt and enter...
sim> attach baci [portnumber]
[listening message, start telnet localhost portnumber]
sim> d s 12211
sim> run 70
[HP-IPL/OS should appear on the telnet terminal]

On real hardware, if possible test with a normal TTY-style console first
to make sure it's working etc. To switch to a BACI console halt the machine,
select the switch register, clear existing bits, set bit 12 and set bits
6 to 11 to the baci slot, if TTY is different and needs reconfiguring put
the TTY slot in bits 0-5. Store, select P register, set to 70, store, preset,
run. System should start up over the BACI console. If needed CONFIG can be
used to set the other device slots. An alternative method of switching to
BACI on demand is drop to a prompt if not already there, CONFIG, enter until
it prompts for console (unless slots need changing) and type B for BACI.
To make the switch enter HLT 2 RUN, swap cables/terminals, press run.


Changes
-------

10/2/10 - Updated the boot build and SFS/EDIT build to HP-IPL/OS 1.60, now
          protects against corruption caused by dictionary overflow and has
          a new ERASE word that erases the last IPL package that was loaded.
          The boot build is the hpos6i.abs binary from the v1.60 archive,
          includes new dm2.ipl menu with HPBASIC support and a bug-fix
          (previous version could not use menu slot Z). SFS/EDIT build now
          includes SAVE word to fix page error encountered when rebuilding.
          Added TTY TREK game and MANDPLOT program, both made with MSU BASIC.
          Added SIOBCS.IPL package to the disk for using vintage HP compilers.
          Updated SUMMARY and DM2.IPL files to latest versions, edited NOTES.
          Updated build scripts in mkdisk.zip, removed redundant IPL files.

3/15/09 - Updated PRINT.IPL and SUMMARY files to fix typo/bug causing it
          to not work on real hardware. New driver now names the words
          with "LPT" (rather than PRN) for consistency, adds dedicated
          words for printing without involving MS.

12/4/08 - Added throttle setting to sim script.

9/14/08 - Updated the line editor in EDIT.IPL, now uses machine code for
          moving/rotating memory during insert/delete, has ?EDIT help word
          and other fixups. Updated SUMMARY and NOTES to reflect new version.

9/1/08  - Replaced lib2.ipl/a2l.ipl with new SFSLIB.IPL library system,
          updated SUMMARY and NOTES to describe. Added edit.ipl, it's not
          pretty (please fix:-) but it can edit variable-line-length text
          files such as a library file (the library system is sequential
          like a tape and only permits changing the last segment, and
          is usually way too big to edit with AEDIT).

8/20/08 - Added LANDER game, edited NOTES, updated SUMMARY.
          More fixups for DMENU/DM2.IPL...
           Displays the HP-IPL/OS version string in the title.
           Reprints main keypress prompt if invalid key pressed.
           No longer requires msupatch.ipl but prompts to use it if present.
           Load ABS function provides a way out if inadvertently selected.
           Text import now properly skips leader zeros.
          Boot system now 1.52A.

8/11/08 - Fixed a cosmetic bug in DMENU/DM2.IPL - if option 7 was used to
          save a non-basic binary it failed to do a CRLF, now it does (1.51P).

8/10/08 - Updated the SFS/EDIT build to v1.52 with the latest version of SFS,
          which now tests memory before buffering a DIRECTORY to prevent loss
          of files (nonexistent memory is read as all-zero, or an empty dir).
          Updated the editable SFS1.IPL and SFS2.IPL files to the new version.
          Added CONALT.IPL and BKFILE.IPL for dumping/restoring files via the
          console, not that useful under sim but very useful on real hardware
          (such as my machine) without PTP to export using other methods.
          Added A2L.IPL containing utilities for transferring multi-word apps
          from edited alt.mem. into the SFS library (LIB2.IPL), and back to
          alt.mem. for editing or further transfer. Added info to NOTES
          regarding using the library to hold utilities etc without having
          to keep them in the dictionary, especially handy when working on
          binaries since loading from the library doesn't affect alt.mem.

4/18/08 - added GOLF, BEASTI and GOMOKU games. Renamed the *-FILES files with
          ALGOL/FORTRAN/ASMB source to not list on the menu. Edited NOTES.

4/7/08  - the FED on the menu is now FED.IPL (renamed to $ FED), the "standard"
          version for the HP-IPL/OS archive. The latest "experimental" version
          is now in a separate AEDIT.IPL file, this is the one in the SFS/EDIT
          build, now version 1.51L. Has an extra control-F command for
          deleting an entire page of text after confirming.

4/6/08  - one word addition to FED/AEDIT's TRCAM word, fixing the code that's
          supposed to make sure there are only zeroes after the file's end.
          The editor doesn't care but it caused the MASAVE export utility
          to output extra zero bytes, which PC editors don't like. Updated
          $ FED, SFS/EDIT build now version 1.51K (which looks better anyway).

4/5/08  - fixed bug in LDFILE causing max-size edit files to fail, tweaked
          other stuff in AEDIT, added hidden control-F page delete function,
          cursor doesn't wiggle as much when moving (not really noticeable
          under sim but was a bit too amusing when running on real hardware).
          Updated $ FED, loaded into SFS/EDIT build, now version 1.51I.

3/27/08 - fixed more bugs in FEDUTIL.IPL.. updated CKARRAY to check only the
          first line to see if in array format (was failing on short files),
          stupid missing ENDIF in ALOAD causing indirect loop if not an array.
          Updated SFS/EDIT build to version 1.51G.

3/27/08 - version 1.51F - +IRQ renamed to !IRQ to enable interrupts in both
          the boot system and SFS/EDIT build. This is not required by the
          boot system but SFS (for a still unknown reason) requires interrupts
          be enabled (at least briefly) or buffer writes (and LDTXT) fail.
          Also minor bugfix to LDTXT in FEDUTIL.IPL and the SFS/EDIT build
          to add a missing $PRINT for the BUFFER BUSY error message string.
          All IPL code on the disk has been converted to editable form so
          LDTXT is no longer needed to convert/edit the included IPL code.
          The SFS.IPL file has been broken into SFS1.IPL and SFS2.IPL to
          permit editing (no actual code changes). MAGTAPE/MTEXTRA.IPL files
          have been removed, if magtape is needed import and optionally modify
          the hposmt6i.abs build from the ide dir of hpiplos_main.zip
          [or the stdedit.abs or sfsedit.abs builds from editbuilds.zip].
          Added BINPATCH.IPL for slot-patching BCS and other binaries.
          Edited NOTES, updated mkdisk.zip scripts to reflect changes.

3/22/08 - slight change to disk menu to avoid renaming files to no name,
          boot system now 1.51E, SFS/EDIT build not changed (but renamed).
          Edited NOTES, updated DM2.IPL, added mkdisk.zip file.

3/15/08 - initial 1.51D version of the 7906 disk simulation.


Have fun! If you have questions or comments let me know.
Terry Newton <wtn90125@yahoo.com>
