<html>
<head>
<title>hp48xgcc Manual</title>
<meta name="GENERATOR" content="Mozilla/2.01Gold (Win32)">
</head>
<body>
<base HREF="http://www.cris.com/~ramos/hp48/hp48xgcc.htm"><author>ramos@cris.com</author>
This is <i>the</i> HP48-xgcc all-in-one installation, user's, and reference
manual.
<h3>TABLE OF CONTENTS</h3>
<ul>
<li><a href="#copyright">Copyright, licensing, warranty</a></li>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#what">What is
it?</a></li>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#where">Where
is it?</a></li>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#install">Installation</a></li>
<ul>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#source">Source-code
Release (Generic UNIX)</a></li>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#bin">Binary Release
(Linux, Windows95)</a></li>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#binother">Binary
Release for other platforms</a></li>
</ul>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#using">Using
the cross-compiler</a></li>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#running">Running
compiled programs</a></li>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#caveats">Caveats</a></li>
<ul>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#main">main</a></li>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#unsigned">unsigned
vs. efficiency</a></li>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#datatypes">data
types and variables</a></li>
</ul>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#asm">Interfacing
with assembly language</a></li>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#ctorture">C-torture
failures</a></li>
<li><a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm#questions">If
you have questions...</a></li>
</ul>
<p>
<hr width="100%" ></p>
<h3><a name="copyright"></a>Copyright, licensing, warranty</h3>
<ul>
<p>Copyright (C) 1994, 95, 96 Alex T. Ramos. All rights reserved.
Licensed for use under the terms of the GNU Public License.</p>
</ul>
<ul>
<p>This is free software. There is NO warranty; not even for MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. You are allowed to make and redistribute
copies of this package, under certain terms and conditions. Please read
the enclosed COPYING and COPYING.LIB file for details. The author, <a href="http://www.cris.com/~ramos">Alex
T. Ramos</a>, may be reached by e-mail as <a href="mailto:ramos@cris.com">ramos@cris.com</a>
or ramos@engr.latech.edu.</p>
<p>Please note that CLASS, CLLD, and the LKV library were written by Lutz
Vieweg and are bound by a different licence. Please read the documentation
in the <b>class</b> directory within the package. Likewise, OBJDUMP was
written by Eddie C. Dost and has its own license terms. Eddie's contributions
to the compiler and libraries, however, are under the GNU licence.</p>
</ul>
<h3><a name="what"></a>What is it?</h3>
<ul>
<p>hp48xgcc is a C cross-compiler. It is a program that runs on your
workstation, and translates C code into objects that can be executed
on the HP48. It is based on (well, that's an understatement) the GNU C Compiler
(gcc), therefore it supports the complete C language and not just
a subset.</p>
</ul>
<h3><a name="where"></a>Where is it?</h3>
<ul>
<p>hp48xgcc, the package </p>
<ul>
<li><a href="ftp://ftp.cis.com/hp48g/uploads/hp48xgcc-1.0.0-win95.zip">Version
1.0.0 for Windows 95.</a></li>
<li><a href="hp48xgcc-patch1.0.1-win95.zip">Version 1.0.1 upgrade for Win95</a>.</li>
<li><a href="hp48xgcc-1.0.1-linux.zip">Version 1.0.1 for Linux</a></li>
<li>Version 1.0.1 source code</li>
<li><a href="http://www.cris.com/~ramos/hp48">Look here too</a>.</li>
</ul>
<p>Long File Name UNZIP for Windows 95 </p>
<ul>
<li><a href="http://www.itribe.net/virtunix/unzip.exe">unzip.exe</a></li>
</ul>
<p>GNU Make </p>
<ul>
<li>Win95: Get the complete <a href="ftp://ftp.cygnus.com/pub/gnu-win32/latest/x86/">CYGWIN32</a>
collection (read the <a href="http://www.cygnus.com/misc/gnu-win32">Project
Page</a>)</li>
<li>Unix: Get it from the <a href="http://wuarchive.wustl.edu/systems/gnu">GNU
directory at WU Archive</a></li>
</ul>
<p>gcc source code </p>
<ul>
<li><a href="http://wuarchive.wustl.edu/systems/gnu/gcc-2.7.2.tar.gz">gcc-2.7.2
from WU Archive</a>.</li>
</ul>
<p>This manual </p>
<ul>
<li>Click here for the <a href="http://www.cris.com/~ramos/hp48/hp48xgcc.htm">most
up-to-date version</a></li>
</ul>
</ul>
<h3><a name="install"></a>Installation</h3>
<ul>
<dl>
<h4><a name="source"></a>Source-code Release (Generic UNIX)</h4>
<ol>
<li>Before you start, make sure you have: Working C and C++ compilers,
GNU Make.</li>
<li>Get the hp48xgcc source code release (http://www.cris.com/~ramos/hp48)</li>
<li>Get the GCC source code (http://wuarchive.wustl.edu/systems/gnu/gcc-2.7.2.tar.gz)</li>
<li>Check if you really have GNU Make, by typing "make -v".
This is the most common cause of problems. If you don't have GNU Make
(this is most likely true if you're using a commercial Unix system), get
it from http://wuarchive.wustl.edu/systems/gnu.</li>
<li>Configure gcc-2.7.2: First create a symbolic link from gcc-2.7.2/config/saturn
to /?/saturn/gcc-target/config-saturn. Then run "./configure --target=saturn-local-hp48".
Finally, run "patch < /??/saturn/gcc-target/patches-2.7.2".</li>
<li>Edit the Makefile in /??/saturn so that GCC_SRC points to the
directory where you've extracted the GCC source code.</li>
<li>Run "make zip". This will create a file on /tmp, with a file
name like hp48xgcc-1.0.0-linux.zip.</li>
<li>Follow the instructions for Binary Release below.</li>
</ol>
<h4><a name="bin"></a>Binary Release (Linux, Windows95)</h4>
<ol>
<li>Before you start, make sure you have a file with a name like: hp48xgcc-1.0.0-ARCH.zip,
where ARCH matches your operating system (either win95 or linux).
There will be a pointer to the latest version for each system at: http://www.cris.com/~ramos/hp48.</li>
<li>If you're using Windows 95, you MUST get an unzip that understands
Long File Names. There's one at http://www.itribe.net/virtunix.</li>
<li>Extract the ZIP file starting from "/" or "C:\"
only. Don't get creative here.</li>
<li>Check if there is a file by the name /usr/lib/gcc-lib/saturn-local-hp48/2.7.2/crt0.o.
If it is there, you're done. If it is not there (which will be the case
if you've built from source code as described above, or if I forgot
to do the next step for you) then continue on to the next step.</li>
<li>Again, if crt0.o, and all the *.sl and *.slo files already exist, you
don't need to perform the next steps.</li>
<li>Make sure you have GNU Make. Unfortunatelly, if you're a Windows95
user this can take some work to accomplish (start at http://www.cygnus.com/gnu-win32).</li>
<li>cd /usr/saturn-local-hp48/lib-source and run <b>make install</b> (on
Unix) or <b>dos-make</b> (on Win95). This will create and install many
critical files, one of them being crt0.o</li>
</ol>
<h4><a name="binother"></a>Binary Release for other platforms</h4>
<ol>
<li>Obtain a machine with a fully licensed POSIX-compliant operating system
on it, including full documentation and C development package, and
ship it to the Author along with proof of ownership, and a cover letter
offering it for sale for US$ 1.00.</li>
<li>Smile :-)</li>
<li>Seriously, I have no way of producing binary releases for platfoms
other than Win95 and Linux. So don't ask. Don't be afraid of compiling
the source code release!</li>
</ol>
</dl>
</ul>
<h3><a name="using"></a>Using the cross-compiler </h3>
<ul>
<dl>
<p>Please keep mind that if you have never programmed in C on a Unix
system, you'll have a significant learning curve ahead of you. Otherwise,
this will be a snap:</p>
<p>First, make sure xgcc (or xgcc.exe, on Windows95) is installed in /usr/bin
(c:\usr\bin), and the compiler libraries are installed in /usr/lib/gcc-lib/saturn-local-hp48/2.x.x.
This is how everything comes out of the ZIP file, so if you haven't
mucked up the directory structure you should be ok. For convenience, you'll
want to add /usr/bin to your PATH permanently, by editing AUTOEXEC.BAT on
Win95, or .*shrc / .profile (which one exactly depends on your site) on
Unix.</p>
<p><b>xgcc</b> works almost exactly like the Unix <b>gcc,</b> except that
the output binary can only be executed on an HP48 handheld calculator.</p>
<p>The simplest usage case (compile "prog.c" into an executable
called "prog") is:
<br>xgcc prog.c -o prog</p>
<p>Most of the standard GCC options are supported (read the GCC manual),
the notable exceptions being "-g" and "-p", and some
others which don't make sense on the HP environment. It is highly recommended
that you <b>*always*</b> use the -O2 (maximum optimization) option,
or the executables might not fit in your HP. That's dash-oh-two, not "zero
two", by the way.</p>
<p>If your package was installed in some random directory other than /usr
(c:\usr), you'll have to use the -B option or the GCC_EXEC_PREFIX environment
variable (again, read the GCC manual). This option is usually a pain
in the neck to get to work right (should it point to the top, the parent,
the machine-specific directory, or the version-specific directory? when
does it require a final slash? I can never remember).</p>
<p>There are some examples that come with the package, they are in <b>/usr/saturn-local-hp48/samples</b>.
Run <i>make</i> there to compile all examples, and <i>make install</i> to
copy them all to the download directory. See below on how to run them.
Note that there are two <i>download</i> directories, one in the samples
directory, the other one up two levels.</p>
</dl>
</ul>
<h3><a name="running"></a>Running compiled programs on the HP48</h3>
<ul>
<dl>
<p>Before you start, you need to setup your HP with the shared C libraries
and the dynamic linker. There's not much setting up actually, you just
need to download them. They are in the <b>/usr/saturn-local-hp48/download</b>
directory. GCCLDD and libgcc.sl are <b>required</b>. The other libraries
are optional, and you'll know you need one if its name comes up on the
stack when you try to run a program that requires it.</p>
<p>Compiled programs have no further dependencies other than the linker
and the libraries listed above. Therefore, to run a C program in the
future, just download it to the HP, and start it either by name or from
the menu just like any user-written RPL program. Of course, you can
also invoke it from RPL programs, assign it to a key, etc.</p>
<p>When downloading, there are 2 common problems: One - the Unix kermit
file transfer defaults to ASCII mode, and you need to set it to binary
or else the download gets corrupted. And Two - some versions of Kermit
insist on mangling the filename beyond recognition (e.g. it might change
<b>libgcc.sl</b> to <b>LIBGCC.SLX</b>). If this happens, be sure to rename
the object once it's in the HP. The world is case-sensitive, so keep in
mind 'gccldd' is not the same as 'GCCLDD'. This is probably not an issue
with X-Modem. The correct name is GCCLDD all-caps, but all the libs
are lowercase.</p>
</dl>
</ul>
<h3><a name="caveats"></a>Caveats</h3>
<ul>
<h4><a name="main"></a>main</h4>
<ul>
<p>IN THIS VERSION, <b>argc </b>is always zero and <b>argv </b>is always
NULL. It will be fixed later. In the meantime, use the macro _STACK to
get to the HP's data stack. e.g.: _STACK(0) returns a pointer to the object
that is at the top of the stack. In keeping with the C spirit, no
bounds checking is made, and you can crash your HP by trying to access
stack levels that are not there.</p>
</ul>
<h4><a name="unsigned"></a>unsigned vs. efficiency</h4>
<ul>
<p>Unsigned comparison is faster & smaller than signed comparison on
the HP48. That's because the Saturn processor doesn't have signed arithmetic,
and it has to be emulated. </p>
<pre>short int i; for(i=0; i<1000; ++i) /* BAD */
unsigned short int i; for(i=0; i<1000; ++i) /* GOOD */
if (c >= 'A' && c <= 'Z') /* GOOD - chars are unsigned */
</pre>
<p>
<br>This performance problem only affects the inequality operators, since
all other arithmetic is indifferent to your perception of signedness.</p>
</ul>
<h4><a name="datatypes"></a>data types and variables</h4>
<ul>
<p>char 8 bits, short 16 bits, int 32 bits, long 32 bits, long long 64
bits, float 64 bits, double 64 bits, long double 128 bits, pointers 20-bits-stored-as-32-bits
Unimplemented features: long double, stdio, libc - Non-optimizing compilation
is not supported. Therefore you must always use the -O2 (dash-oh-two) flag.
- Global variables retain their values accross program executions!</p>
</ul>
</ul>
<h3><a name="asm"></a>Interfacing with assembly language </h3>
<ul>
<dl>
<p>This section might be out of date. Just to be safe, check the value
of PARM_ALLOC_ORDER in local-hp48.h before you depend on this: frame pointer:
D1 stack pointer: R1 struct value: D static chain: D0 function parameters:
B, R0, R2, R3, R4, then stack. function return value: C The current implementation
uses the "caller saves" convention - all functions are free to
clobber any registers they wish, EXCEPT the frame and stack pointers and
the P register. The P register must be restored to the value 7 before returning
to the "C" caller.</p>
</dl>
</ul>
<h3><a name="ctorture"></a>Expected c-torture failures </h3>
<ul>
<dl>
<p>This is for my own reference, as well as for anybody else who wants
to run the C-torture (v1.34) compiler test suite. 940409-1 (4) This one
is correct to fail. (Fails on all systems). 930326-1 (4) "Initializer
too complex" (gcc-2.6.x) (exit 1) "Initializer not computable
at load time" (gcc-2.7.0) (exit 1) This is correct, because this test
depends on byte pointers. On usual systems the value is: (&f + 2) -
(&f + 1), but for the HP48 with 4 bit addressing the value to compute
would be ((&f + 4) - (&f + 2)) / 2 initializer_constant_valid_p
() in c-typeck.c can only handle PLUS_EXPR and MINUS_EXPR, *NOT* EXACT_DIV_EXPR.
(Try substituting 'char' with 'int', and gcc will fail on any system).
Total: 8 expected failures.</p>
</dl>
</ul>
<h3><a name="questions"></a>If you have questions...</h3>
<ul>
<dl>
<p>...don't ask me! Programming is one of my hobbies, but Customer Service
IS NOT! The best place to get general help is on <a href="news://comp.sys.hp48">comp.sys.hp48</a>
and (maybe) <a href="news://comp.lang.c">comp.lang.c</a>. If you have
a focused, specific question that only I could possibly answer, ok,
I'll try. Bug reports are welcome too. My current (10/96) e-mail address
is <a href="mailto:ramos@cris.com">ramos@cris.com</a>.</p>
</dl>
</ul>
<p><!-- Concentric Network Corporation provides this web directory as
a service to its customers and is not responsible for its content. --></p>
</body>
</html>
<!-- Concentric Network Corporation provides this web directory as
a service to its customers and is not responsible for its content. -->
syntax highlighted by Code2HTML, v. 0.9.1