hpconv and hpdis version 1.4.0 
Copyright (C) 1999 by Eduardo M Kalinowski (ekalin@iname.com)


Building instructions
=====================

First, run "./configure". This script will do a series of tests to
determine some characteristics of your system, and generate a
"Makefile". You might want to review that file, mostly to add or
remove switches to the CXXFLAGS definition.

Then, to actually build the package, just run "make". After that, you
may copy the executables elsewhere, if you want. (There is no "make
install" at this time.) Running "make clean" will delete the file
created. Use "make distclean" to remove also the files that the
"configure" script created.

To build, you'll need a recent C++ compiler, which supports the latest
ANSI C++ specifications and the Standard Template Library. GNU C++
does.

NOTE: By default, the programs do not produce output, but this can be
changed with the "-v" command line options. However, if you define the
symbol NDEBUG while building, this command line option and all debug
information will not be compiled in. This will make the executables
slightly smaller and faster.


Using hpconv
============

Use "hpconv" to convert HP48 binary object files to HP49G format, and
vice-versa. The program will automatically detect whether the file you
want to convert is from the HP48 or HP49G.

If some address is not found in one of the table, you are prompted to
enter manually the new address. If you know the new address, enter it.
f not, just press ENTER to abort the conversion.

The general syntax is:

  hpconv [options] <files>

Options are zero or more of the following:

  --version   Prints a version information and exits successfully.

  --help      Prints a summary of the options and exits successfully.

  -8 file     Reads the HP48 entries from the specified file. If not
              present, the default is to read from the file
              "entry48.a" in the current directory.

  -9 file     Reads the HP49G entries from the specified file. If not
              present, the default is to read from the file
              "entry49.a" in the current directory.

  -p          Without this option, each file given in the command line
              is treated as a input file to convert, and the output
              files are named after the input files, with ".49" or
              ".48" appended (in case the file is from the HP48 or
              HP49G, respectively.)
              With this option, each pair of two files is treated as
              an input file name and a respective output filename.

  -v x        Sets the verbosity level to x (an integer.) The default
              level is 0, and in this level hpconv only produces
              output in case of errros. Greater numbers means greater
              amount of information (not always useful) output.
              Currently, levels one to four are supported. Levels
              above four are the same as for.
              NOTE: If you compiled hpconv with NDEBUG defined, this
              option will have no effect.


Conversion of code objects
--------------------------

hpconv will try to do some changes to code objects, but code objects
may not be reliably converted automatically in all cases. The
following program explains this kind of situation:

CODE
	GOSBVL	=SAVPTR
	D0=(5)	#00101		Set constrast to value 14
	LC(2)	14
	DAT0=C	B
	GOVLNG	=GETPTRLOOP
ENDCODE

The GOSBVL and GOVLNG instructions are likely to point to an address
in ROM, which might have changed, so the addresses after them are
always converted. However, the instructions that load D0 with an
address may or may not point to an address that should be changed if
necessary. In that case, the address of the constrast setting, #00101
may have changed, but no attempt will be made to convert the new
address. This is because you might as well load in D0 or D1 an address
that points to RAM or some other value. The same happens with the LA
and LC instructions. In that case, the value loaded is an arbitrary
value, but in some cases one might load an address in ROM in A or C,
as the following code demonstrates:

CODE
	C=DAT1	A
	CD1EX
	A=DAT1	A
	D1=C
	LC	=DOCSTR
	?A=C	A		Check if the object in level 1 is a string
	GOYES	String
	...
ENDCODE

Since no automatic converter can know what the author of the code
object intended, care should be taken when using converted code
objects.


Using hpdis
===========

Use "hpdis" to disassemble HP48 or HP49G binary objects to their
source code, in JAZZ or rplcomp syntax. The version of the file is
automatically detected and the correct entry table is loaded.

The general syntax is:

  hpdis [options] <files>

Options are zero or more of the following:

  --version   Prints a version information and exits successfully.

  --help      Prints a summary of the options and exits successfully.

  -8 file     Reads the HP48 entries from the specified file. If not
              present, the default is to read from the file
              "entry48.a" in the current directory.

  -9 file     Reads the HP49G entries from the specified file. If not
              present, the default is to read from the file
              "entry49.a" in the current directory.

  -h          Include in the decompiled file instructions to generate
              the binary download header (HPHP48-X).

  -i x        Uses x spaces at each indentation level. The default is
              two spaces, but you may use any value you like here.

  -p          Without this option, each file given in the command line
              is treated as a input file to convert, and the output
              files are named after the input files, with ".s"
              appended.

  -r          Outputs source code compatible with rplcomp. Without
              this option, the source code is only compatible with
              JAZZ. This option does not automatically include the
              binary download header in the file, you must use the -h
              option for that.

  -u          When this option is set, hpdis inserts before all
              unsupported entries the string "*** UNSUPPORTED ***", so
              that they can easily be located in the source code.

  -v x        Sets the verbosity level to x (an integer.) The default
              level is 0, and in this level hpconv only produces
              output in case of errros. Greater numbers means greater
              amount of information (not always useful) output.
              Currently, levels one to four are supported. Levels
              above four are the same as for.
              NOTE: If you compiled hpconv with NDEBUG defined, this
              option will have no effect.

If you specify "-" as a file, that means to read input from stdin. You
can similarly specify "-" as the output file (using the -p option) to
redirect output to stdout. If the input is from stdin and there is no
output filename, the output goes to stdout.


Library disassembly (when using RPLComp)
----------------------------------------

When using RPLComp, the process of creating an object requires several
steps and programs. When assembling libraries, not all the necessary
information comes from the source file. Specifically, the title,
message table and config objects must be specified in another file,
which hpdis does not create (the .mn file that makerom processes.) The
necessary information will be output in the source code as comments,
so that you can include them in the .mn file.

When using JAZZ, all necessary information is in the source file.


Errors
======

When hpconv or hpdis cannot disassemble an the file for any reason,
they stop processing that file, saying the reason for the error, but
continue processing any other files on the command line. The exit
status will be 1.

Below there are explanations of the errors that might happen:

Unexpected end of file
    This error means that the end of file was reached when the program
    was expecting more data. Generally this indicates that the file is
    corrupt because some error in the transmission happened.

Bad prologue in array
    This error indicates that the prologue an array (or linked array)
    contains was not found in the entry tables. This error should
    never happen, unless the entry tables are incomplete.

Unknown address
    This error happens during the conversion when some address is not
    found in the output entry table, and the user could not provide a
    new address for the entry manually.

Arbitrary precision numbers not supported on HP48
    The user tried to convert a HP49G file which contains the new
    HP49G arbitrary precision integers, real numbers or complex
    numbers. These objects are new to the HP49 and cannot be converted
    to the HP48, because there is no support for them.

Flash pointers not supported on HP48
    Similarly to the above, the flash pointers are a new kind of
    object on the HP49G, which cannot be converted to the HP48.

Library doesn't have a hash table
    While reading a library, the offset for the hash table is 0.
    Libraries without a hash table cannot be converted or
    disassembled. (Can they exist on an HP??)

Library doesn't have a link table
    Similar to the above, but the link table was not found.

Library command property field unsupported
    Currently, only libraries whose commands are flagged with the
    one-nibble property field '8' (a regular command) can be
    converted. The library you tried to convert contained commands
    with commands with other property fields.



Entry tables
============

Both "hpconv" and "hpdis" read the entry table in the format
recognized by SASM. (But only global labels are added, in case there
is some local label in your file.) More specifically, for a line to be
recognized, it must match the following sscanf patter: "=%s EQU #%lx".

The entry tables provided with the program are the most recent and
accurate I could find.


Miscellaneous information
=========================

    These programs were written by Eduardo M Kalinowski
(ekalin@iname.com). Visit my home page at http://move.to/hp48g for
newer version. Please send comments, bug reports, suggestions, etc to
the e-mail address above. Send flames to /dev/null.

    This program is distributed in the hope it will be useful, but
there is ABSOLUTELY NO WARRANTY. USE AT YOUR OWN RISK. Do a backup of
your calculator before trying running the programs converted.

    This program is distributed under the General Public License. You
should have received a copy of the license with this program in the
file "COPYING". If not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.




Local variables:
mode:text
End:
