                            H8 Simulator

This is a simulator for a Heathkit H8 computer (1977), which runs in any
DOS compatible environment.

Currently the simulator implements:

  H8   Computer, CPU, Front panel, 64k memory.
  H9   "Glass teletype" terminal.
  H8-5 serial/cassette interface with I/O to PC files.
  H17  Floppy disk system with up to three drives. (**)
  PAM-8 and H17 ROM images pre-installed.

** The H17 disk system is optional. The H17 hardware (I/O ports and
   ROM) will not appear in the virtual H8 until at least one disk
   mount operation has been performed.

When operating, the simulator has three basic modes:

PANEL MODE:
  Non-function keys are directed to the virtual H8 front panel. This is
  normally used to enter commands to the H8's internal PAM-8 monitor
  program.

  Use the H8 in PANEL MODE exactly as you would from the physical
  H8 front panel.

  NOTE: The simulator starts in PANEL MODE.

  NOTE: There is no TTY cursor when running in PANEL mode (TTY output
        will still be displayed).

  NOTE: The simulator's input function does not support the multi-key
        functions of the H8, instead - use: 'R'=Reset  'M'=Force Monitor

TTY MODE:
  Non-function keys are directed to the virtual H9 terminal keyboard and
  appear as input data at the H8 console serial port.

  Use the H8 in TTY mode exactly as you would from the console terminal.

  NOTE: When the H8 front panel is displayed, the TTY window is restricted
        to 13 lines, however data that scrolls off the top is retained
        in the non-visible lines under the panel. You can switch off the
        panel display to view the entire 24 line screen.

DEBUG MODE:
  Provide direct access to the 8080 CPU and H8 memory.

See the online help for details on the commands available in each
mode.


There are three ways to load programs/data into the simulator:

 1) After mounting a tape image file (I=option or F5 panel mode command),
    you can use the PAM-8 LOAD [8] command to load data from the tape image.
    In this case, PAM-8 will know the starting address, so just hit GO [4]
    to launch to program. This method is the way you would load software
    from tape on the real H8.

 2) After mounting a disk image (R#=/W#= options or F5 panel mode command),
    you can boot the disk using PAM-8 commands:
    Press:  .   <- Activate REGISTER mode
            6   <- Select PC (must do, even if already displayed)
            /   <- Enter "Alter" mode to change value
          0 3 0 <- Set high byte to 030 ($18)
          0 0 0 <- Set low  byte to 000 ($00)
            /   <- Leave "Alter" mode, allowing Keypad commands
            4   <- Execute the program
    NOTE: This simulator has the original PAM-8 ROM installed, matching
          my real H8, however many H17 users changed the monitor to PAM8GO
          which allows you to boot just by pressing [4] after power-on.
          You can "replace" the PAM-8 ROM in the simulator with PAM8GO if
          you wish by specifying the command option: LR=PAM8GO
          This loads the PAM8GO.HEX file (supplied) into the ROM area.

 2) The L=file[.HEX] command line option allows you to load an Intel or
    Motorola hex format file directly into memory before the simulation
    starts.

    Since PAM-8 has no knowledge of this load method, you will have to
    manually set the starting address before launching the program.
        [Assuming the standard load address of 040 100 ($2040)]
    Press:  .   <- Activate REGISTER mode
            6   <- Select PC (must do, even if already displayed)
            /   <- Enter "Alter" mode to change value
          0 4 0 <- Set high byte to 040 ($20)
          1 0 0 <- Set low  byte to 100 ($40)
            /   <- Leave "Alter" mode, allowing Keypad commands
            4   <- Execute the program


If you wish to enter data on the H9 terminal after launching a program,
then you will need to enter one final keystroke:

       F2    <- Switch to TTY mode, allowing console input

Don't forget to press F2 again to return to PANEL mode if you need to
enter more PAM-8 functions.

Please execute H8 ? to view the available command line options and
other simulator help topics.

Note that if the simulator encounters something out of the ordinary,
it invokes the built-in 8080 debugger with a message indicating the
reason. Once you correct the problem, press ENTER to resume virtual
H8 execution.

UTILITIES:
----------
I have included the following utility files.

H8T.COM - H8 Translate/Transfer utility
  Allows you to easily and instantly translate files between any of the
  following types, and also to upload/download files of these types to/from
  a real H8 computer without having to translate them first:
   .H8T - H8 Tape image 
   .HEX - Intel/Motorola ASCII/HEX download format (used by my dev tools)
   .BIN - Raw binary image
  For more information, type H8T (with no operands).

SERIO.ASM - Console serial I/O "stub"
  This a small "stub" I wrote to perform interrupt driven serial I/O to the
  H8 console. Makes it very easy to port existing code into the H8. Provides
  a 64 byte  FIFO buffer on receive.
  + See source comments for more information.
  + SERIO.ASM is compatible with my 8085 cross assembler (www.dunfield.com)

COMPATIBILITY:
--------------
I have tested the virtual H8 on systems ranging from a 386/33 to a P3/733.
Note that the overhead of the H8's 500hz refresh interrupt causes
performance to degrade rapidly on slower machines (I do not recommend
lower than a 486).

I have also tested the program under DOS 5, DOS 6, Win98 and Win2000.

Please let me know if you encounter problems or "quirks".


EXAMPLE PROGRAMS:
-----------------
I've provided several of the original H8 tape software programs in the
form of .H8T (H8 Tape image) files, and a bootable HDOS disk image in
the file HDOS16.H8D. You can load and run this software as described
above.

NOTES on example programs:
--------------------------
- Most of them require H9 console input - Be sure to press F2 to switch
  to TTY mode after you launch the program.

- Some of the H8 tape programs require you to press SPACE before any
  output will be displayed (Make sure you are in TTY mode).

- Some of the H8 tools begin in a setup mode which requires you to
  press RETURN (ENTER) at the initial prompt in order to get the main
  program to start.

- Some of the programs disable the H8 display refresh; if the panel
  display stops updating and the program appears to be working, this is
  probably normal.

- If you use 'M' (0+#) to re-enter the monitor, or single-step a
  program which is using the display for their own output (H8DEMO for
  example), PAM-8 will re-enable it's display update - this will not
  get turned off again unless you restart the program, which means that
  the the program display will not resume correctly - this is also
  "normal" for the H8.

- EXBASIC appears to have a bug where the virtual H8 having a full 64k
  of memory causes it to get a "memory overflow" error. At the '.' prompt
  when EXBASIC starts, use the 'h' command to set the maximum memory to
  50393 or lower.

- The HASL8 assembler appears to have a bug, where it executes the $20
  (space) byte on the end of a character string. This causes the simulator
  to trap to the debugger. You can use the /I command line option to option
  force the simulator to ignore the bad instruction, in which case it will
  run this program exactly the same as a real H8.

- HDOS is NOT Y2K compatible - you must enter a year between 70 and 99
  at the Date prompt when it boots.

- If you mount the HDOS disk as READ ONLY, the both BASIC and EDIT will
  fail and halt the system with a "?02 FATAL SYSTEM ERROR"

Dave Dunfield

Dunfield Development Services (DDS) offers software and firmware
development services specializing in systems and embedded applications.
For more information, visit: http://www.dunfield.com
