Emu48 - an HP48 emulator
    Copyright (C) 1995 Sebastien Carlier (sebc@cybera.anet.fr)
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.
 
     This program 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; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Emu48 - an HP48 emulator
========================

This is Emu48, another HP48 CPU emulator. This is Version 0.37
It's at least 25% faster than a real HP48GX on an Intel DX2-66,
and it's very small. Though I did nothing to allow that, Emu48
can emulate BOTH HP48G/GX and HP48S/SX. You've just to give it
the proper rom dump file.
Emu48 is now compatible with Emul48 rom and ram files, but it
will always write them in its own style.




NOTE (from x48 by Eddie C. Dost, from EM48 README by Paul Fox)
===================================

This emulator is capable of providing a faithful replication of the
HP48. In order to do so, it requires a copy of the ROM software
from YOUR calculator. In order to avoid breaking copyright laws,
and upsetting HP, you MUST BE THE PROUD OWNER OF AN HP48 before
running this program. Of course you can run this program without a
copy of the ROM software in order to write trivial machine code
programs but you will not be able to access any of the calculator
functionality.

Instructions on how to download a copy of the ROM are provided
later in this document.


CREDITS
=======

Thanks to all these friendly guys I met on the #hp48 channel on IRC :
    alonzo	(Alonzo Gariepy - helped a lot in optimizing Emu48)
    fin		(Mika Heiskanen - his Jazz is great)
    moyer	|
    BeeF	| helpful ideas, documentations, testing programs...
    hideki	|
and the others I might have forgotten.

Some parts of this README come from x48 README by Eddie C. Dost.


COMPILING THE SOURCES
=====================

Copy the proper makefile into the main directory and run 'make'.

Supported plateforms :
	Linux/svgalib
	MsDos/go32
        MsDos/PharLap
        Windows 95/NT



HOW TO DOWNLOAD A COPY OF THE ROM
=================================

The emulator works by executing an image of the HP48s ROM. In order
to run the emulator you must have a version of your ROM on the system.

**********************************************************************
* This includes the HIDDEN ROM. Please don't use DUMP programs, that *
* don't dump the HIDDEN ROM. The emulator won't run.                 *
**********************************************************************


To get a memory dump you need to do the following:


- Download the file 'romdump/ROMDump' to your HP.
 
- To capture a complete ROM, start kermit on your computer, set the
  line so it fits your HP, set the speed to 9600 baud and type
  'log session', then 'connect'.
 
- On a HP48 S/SX type '#0h #7FFFFh ROMDump',
  on a HP48 G/GX type '#0h #FFFFFh ROMDump'.
  This will take about 15 minutes on the S/SX, 30 minutes on the G/GX.
 
- When done, type the kermit-Escape (usually CTRL-\) followed
  by 'C' on your Computer. Say 'quit' to the kermit.
 
Your ROM should now be in the file 'session.log'.



Now you have a file containing lines like

#00000:2369B108DADF1008
...

This has to be converted to a binary ROM for x48.

Run the command: `dump2rom session.log`
This will convert your dump into a rom file readable by the emulator
called 'rom.dump'.

CHECK the file with the program 'checkrom'.
Type: `checkrom rom.dump`. It should say:

  ROM Version is HP48-A
  ROM CRC reads 0xcb76 (for Rev. A, will be different for other ROMs)
  IROM OK: ROM CRC test passed.

or

  ROM Version is HP48-R
  ROM CRC 1 reads 0xdfed (for Rev. R, will be different for other ROMs)
  ROM CRC 2 reads 0xf0b1 (                --- " ---                   )
  IROM OK: ROM CRC test passed.

If the test failed, something went wrong transfering the ROM. Don't
start thinking about the size or the nibbles in 'rom.dump'. That's
all correct. Do the Transfer again.

If you know how to do it, you could of course only transfer the
'broken' part of the dump, using e.g. '#60000h #60080h ROMDump'
and fix these lines in 'session.log'.


USING THE EMULATOR
==================

    * Press the RIGHT Control key to quit the emulator.
    * Press the RIGHT Alt key to quit the emulator WITHOUT SAVING its state.
    * If(When?) the emulator crashes, quit it with [RightCtrl], and run
              emu48 -W
      If it doesn't work, try using -WC instead of -W.
      If this fails, delete the file named 'saturn' and run emu48.


USING RAM CARDS
===============

To get a RAM card, just create files named 'port1' and 'port2' with
something like this :
        echo > port1
or	echo > port2

You can now create files named 'port2.1', 'port2.2'...'port2.31' to have
a card bigger than 128k in port 2.


KEYBOARD SUPPORT
================

 ON	= Esc
 A      = A, Insert             B       = B, Home
 C      = C, PageUp             D       = D, Delete
 E      = E, End                F       = F, PageDown
 G,MTH  = G                     H,PRG   = H
 I,CST  = I                     J,VAR   = J
 K,UP   = K, Up Arrow           L,NXT   = L
 M,'    = M, '                  N,STO   = N
 O,EVAL = O                     P,LEFT  = P, Left Arrow
 Q,DOWN = Q, Down Arrow         R,RIGHT= E, Right Arrow
 S,SIN  = S                     T,COS   = T
 U,TAN  = U                     V,SQRT  = V
 W,Y^X  = W                     X,1/X   = X
 ENTER  = ENTER                 Y,+/-   = Y
 Z,EEX  = Z                     DEL     = Keypad Del
 <=     = BackSpace             ALPHA   = Left Shift, Right Shift
 <~|    = Left Crtl             |~>     = Left Alt
 0      = 0, Keypad 0           1       = 1, Keypad 1
 2      = 2, Keypad 2           3       = 3, Keypad 3
 4      = 4, Keypad 4           5       = 5, Keypad 5
 6      = 6, Keypad 6           7       = 7, Keypad 7
 8      = 8, Keypad 8           9       = 9, Keypad 9
 .      = .                     SPC     = Space
 /      = /, Keypad /           *       = Keypad *
 -      = -, Keypad -           +       = Keypad +


TALKING TO THE OUTSIDE WORLD
============================

      * To load a kermit file from disk, name it as 'port1' in the directory
        in which the emulator is. Then run the emulator, type the following
        program and store it as 'GET1' :

	<< GROB 8 3 0100C0 #4017h SYSEVAL #56B6h SYSEVAL DROP NEWOB >>

        When you execute this program, it will put on the stack the content
        of the file you renamed as 'port1'.
        This works only for binary files.

      * Serial ports aren't emulated. Instead, the XMIT command will write
        its output to a file named 'wire'. You can use the 'SND.PRG' file
        along with the DEV library (download them 'GET1') to send an object
        on the stack to the file 'wire', which will be exactly like a kermit
        binary file. You must quit the emulator and rename 'wire' before
        sending another file, otherwise you'll only be able to recover the
        first file.


KNOWN BUGS
==========

Timer handling isn't really good. I'm fixing that.

I must also provide different keyboard mappings.

Someone told me Emu48 didn't display anything on his computer. This should
be checked.



ACCESS TO THE AUTHOR
====================

Please send any bug reports, context-diffs or suggestions to

sebc@cybera.anet.fr

Sebastien Carlier
10, Allee des bergeronnettes
35340 LIFFRE
FRANCE