<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+
+<!--Converted with LaTeX2HTML 2K.1beta (1.47)
+original version by: Nikos Drakos, CBLU, University of Leeds
+* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
+* with significant contributions from:
+ Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
- <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
- <TITLE>SDCC Compiler User Guide</TITLE>
- <LINK HREF="SDCCUdoc-1.html" REL=next>
+<TITLE>SDCC Compiler User Guide</TITLE>
+<META NAME="description" CONTENT="SDCC Compiler User Guide">
+<META NAME="keywords" CONTENT="SDCCUdoc">
+<META NAME="resource-type" CONTENT="document">
+<META NAME="distribution" CONTENT="global">
+
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
+<META NAME="Generator" CONTENT="LaTeX2HTML v2K.1beta">
+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+<LINK REL="STYLESHEET" HREF="SDCCUdoc.css">
</HEAD>
-<BODY>
-<A HREF="SDCCUdoc-1.html">Next</A>
-Previous
-Contents
-<HR>
-<H1>SDCC Compiler User Guide</H1>
-<H2>Sandeep Dutta (sandeep.dutta@usa.net)</H2>
+<BODY >
+<!--Navigation Panel-->
+<IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
+ SRC="file:/usr/share/latex2html/icons/nx_grp_g.png">
+<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
+ SRC="file:/usr/share/latex2html/icons/up_g.png">
+<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
+ SRC="file:/usr/share/latex2html/icons/prev_g.png">
+<BR>
+<BR>
+<BR>
+<!--End of Navigation Panel-->
+
<P>
-<H2><A NAME="toc1">1.</A> <A HREF="SDCCUdoc-1.html">Introduction</A></H2>
<P>
-<H2><A NAME="toc2">2.</A> <A HREF="SDCCUdoc-2.html">Installation </A></H2>
+<H1 ALIGN="CENTER">SDCC Compiler User Guide</H1>
+<BR>
+
+<H2><A NAME="SECTION00010000000000000000">
+Contents</A>
+</H2>
+<!--Table of Contents-->
<UL>
-<LI><A HREF="SDCCUdoc-2.html#ss2.1">2.1 Components of SDCC</A>
-<LI><A HREF="SDCCUdoc-2.html#ss2.2">2.2 Installation for Version <= 2.1.7</A>
-<LI><A HREF="SDCCUdoc-2.html#ss2.3">2.3 Installation for Version >= 2.1.8a</A>
+<LI><A NAME="tex2html119"
+ HREF="SDCCUdoc.html">1 Introduction</A>
+<UL>
+<LI><A NAME="tex2html120"
+ HREF="#SECTION00021000000000000000">1.1 About SDCC</A>
+<LI><A NAME="tex2html121"
+ HREF="#SECTION00022000000000000000">1.2 Open Source</A>
+<LI><A NAME="tex2html122"
+ HREF="#SECTION00023000000000000000">1.3 System Requirements</A>
+<LI><A NAME="tex2html123"
+ HREF="#SECTION00024000000000000000">1.4 Other Resources</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html124"
+ HREF="#SECTION00030000000000000000">2 Installation</A>
+<UL>
+<LI><A NAME="tex2html125"
+ HREF="#SECTION00031000000000000000">2.1 Linux/Unix Installation</A>
+<LI><A NAME="tex2html126"
+ HREF="#SECTION00032000000000000000">2.2 Windows Installation</A>
+<LI><A NAME="tex2html127"
+ HREF="#SECTION00033000000000000000">2.3 Testing out the SDCC Compiler</A>
+<LI><A NAME="tex2html128"
+ HREF="#SECTION00034000000000000000">2.4 Install Trouble-shooting</A>
+<LI><A NAME="tex2html129"
+ HREF="#SECTION00035000000000000000">2.5 Additional Information for Windows Users</A>
+<LI><A NAME="tex2html130"
+ HREF="#SECTION00036000000000000000">2.6 SDCC on Other Platforms</A>
+<LI><A NAME="tex2html131"
+ HREF="#SECTION00037000000000000000">2.7 Advanced Install Options</A>
+<LI><A NAME="tex2html132"
+ HREF="#SECTION00038000000000000000">2.8 Components of SDCC</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html133"
+ HREF="#SECTION00040000000000000000">3 Using SDCC</A>
+<UL>
+<LI><A NAME="tex2html134"
+ HREF="#SECTION00041000000000000000">3.1 Compiling</A>
+<LI><A NAME="tex2html135"
+ HREF="#SECTION00042000000000000000">3.2 Command Line Options</A>
+<LI><A NAME="tex2html136"
+ HREF="#SECTION00043000000000000000">3.3 MCS51 Storage Class Language Extensions</A>
+<LI><A NAME="tex2html137"
+ HREF="#SECTION00044000000000000000">3.4 Pointers</A>
+<LI><A NAME="tex2html138"
+ HREF="#SECTION00045000000000000000">3.5 Parameters & Local Variables</A>
+<LI><A NAME="tex2html139"
+ HREF="#SECTION00046000000000000000">3.6 Overlaying</A>
+<LI><A NAME="tex2html140"
+ HREF="#SECTION00047000000000000000">3.7 Critical Functions</A>
+<LI><A NAME="tex2html141"
+ HREF="#SECTION00048000000000000000">3.8 Absolute Addressing</A>
+<LI><A NAME="tex2html142"
+ HREF="#SECTION00049000000000000000">3.9 Interrupt Service Routines</A>
+<LI><A NAME="tex2html143"
+ HREF="#SECTION000410000000000000000">3.10 Startup Code</A>
+<LI><A NAME="tex2html144"
+ HREF="#SECTION000411000000000000000">3.11 Inline Assembler Code</A>
+<LI><A NAME="tex2html145"
+ HREF="#SECTION000412000000000000000">3.12 int(16 bit) and long (32 bit ) Support</A>
+<LI><A NAME="tex2html146"
+ HREF="#SECTION000413000000000000000">3.13 Floating Point Support</A>
+<LI><A NAME="tex2html147"
+ HREF="#SECTION000414000000000000000">3.14 MCS51 Memory Models</A>
+<LI><A NAME="tex2html148"
+ HREF="#SECTION000415000000000000000">3.15 Flat 24 bit Addressing Model</A>
+<LI><A NAME="tex2html149"
+ HREF="#SECTION000416000000000000000">3.16 Defines Created by the Compiler</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html150"
+ HREF="#SECTION00050000000000000000">4 SDCC Technical Data</A>
+<UL>
+<LI><A NAME="tex2html151"
+ HREF="#SECTION00051000000000000000">4.1 Optimizations</A>
+<LI><A NAME="tex2html152"
+ HREF="#SECTION00052000000000000000">4.2 Pragmas</A>
+<LI><A NAME="tex2html153"
+ HREF="#SECTION00053000000000000000">4.3 Library Routines</A>
+<LI><A NAME="tex2html154"
+ HREF="#SECTION00054000000000000000">4.4 Interfacing with Assembly Routines</A>
+<LI><A NAME="tex2html155"
+ HREF="#SECTION00055000000000000000">4.5 Global Registers used for Parameter Passing</A>
+<LI><A NAME="tex2html156"
+ HREF="#SECTION00056000000000000000">4.6 With -noregparms Option</A>
+<LI><A NAME="tex2html157"
+ HREF="#SECTION00057000000000000000">4.7 External Stack</A>
+<LI><A NAME="tex2html158"
+ HREF="#SECTION00058000000000000000">4.8 ANSI-Compliance</A>
+<LI><A NAME="tex2html159"
+ HREF="#SECTION00059000000000000000">4.9 Cyclomatic Complexity</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html160"
+ HREF="#SECTION00060000000000000000">5 TIPS</A>
+<LI><A NAME="tex2html161"
+ HREF="#SECTION00070000000000000000">6 Retargetting for other MCUs.</A>
+<LI><A NAME="tex2html162"
+ HREF="#SECTION00080000000000000000">7 SDCDB - Source Level Debugger</A>
+<UL>
+<LI><A NAME="tex2html163"
+ HREF="#SECTION00081000000000000000">7.1 Compiling for Debugging</A>
+<LI><A NAME="tex2html164"
+ HREF="#SECTION00082000000000000000">7.2 How the Debugger Works</A>
+<LI><A NAME="tex2html165"
+ HREF="#SECTION00083000000000000000">7.3 Starting the Debugger</A>
+<LI><A NAME="tex2html166"
+ HREF="#SECTION00084000000000000000">7.4 Command Line Options.</A>
+<LI><A NAME="tex2html167"
+ HREF="#SECTION00085000000000000000">7.5 Debugger Commands.</A>
+<LI><A NAME="tex2html168"
+ HREF="#SECTION00086000000000000000">7.6 Interfacing with XEmacs.</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html169"
+ HREF="#SECTION00090000000000000000">8 Other Processors</A>
+<UL>
+<LI><A NAME="tex2html170"
+ HREF="#SECTION00091000000000000000">8.1 The Z80 and gbz80 port</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html171"
+ HREF="#SECTION000100000000000000000">9 Support</A>
+<UL>
+<LI><A NAME="tex2html172"
+ HREF="#SECTION000101000000000000000">9.1 Reporting Bugs</A>
+<LI><A NAME="tex2html173"
+ HREF="#SECTION000102000000000000000">9.2 Acknowledgments</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html174"
+ HREF="#SECTION000110000000000000000">About this document ...</A>
+</UL>
+<!--End of Table of Contents-->
+
<P>
-<H2><A NAME="toc3">3.</A> <A HREF="SDCCUdoc-3.html">Compiling.</A></H2>
-<UL>
-<LI><A HREF="SDCCUdoc-3.html#ss3.1">3.1 Single Source file projects.</A>
-<LI><A HREF="SDCCUdoc-3.html#ss3.2">3.2 Projects with multiple source files.</A>
-<LI><A HREF="SDCCUdoc-3.html#ss3.3">3.3 Projects with additional libraries.</A>
+<H1><A NAME="SECTION00020000000000000000">
+1 Introduction</A>
+</H1>
+
<P>
-<H2><A NAME="toc4">4.</A> <A HREF="SDCCUdoc-4.html">Command Line options</A></H2>
+
+<H2><A NAME="SECTION00021000000000000000">
+1.1 About SDCC</A>
+</H2>
<P>
-<H2><A NAME="toc5">5.</A> <A HREF="SDCCUdoc-5.html">Language Extensions</A></H2>
+<B>SDCC</B> is a Free ware, retargettable, optimizing ANSI-C compiler
+by <B>Sandeep Dutta</B> designed for 8 bit Microprocessors. The
+current version targets Intel MCS51 based Microprocessors(8051,8052,
+etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51 variant. It
+can be retargetted for other microprocessors, support for PIC, AVR
+and 186 is under development. The entire source code for the compiler
+is distributed under GPL. SDCC uses ASXXXX & ASLINK, a Freeware,
+retargettable assembler & linker. SDCC has extensive language extensions
+suitable for utilizing various microcontrollers underlying hardware
+effectively. In addition to the MCU specific optimizations SDCC also
+does a host of standard optimizations like <I>global sub expression
+elimination, loop optimizations (loop invariant, strength reduction
+of induction variables and loop reversing), constant folding & propagation,
+copy propagation, dead code elimination and jumptables for 'switch'
+statements.</I> For the back-end SDCC uses a global register allocation
+scheme which should be well suited for other 8 bit MCUs. The peep
+hole optimizer uses a rule based substitution mechanism which is MCU
+independent. Supported data-types are <I>short (8 bits, 1 byte),
+char (8 bits, 1 byte), int (16 bits, 2 bytes ), long (32 bit, 4 bytes)
+& float (4 byte IEEE).</I> The compiler also allows <I>inline assembler
+code</I> to be embedded anywhere in a function. In addition routines
+developed in assembly can also be called. SDCC also provides an option
+to report the relative complexity of a function, these functions can
+then be further optimized, or hand coded in assembly if need be. SDCC
+also comes with a companion source level debugger SDCDB, the debugger
+currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
+The latest version can be downloaded from <B>http://sdcc.sourceforge.net/.</B>
-<UL>
-<LI><A HREF="SDCCUdoc-5.html#ss5.1">5.1 Storage Classes.</A>
<P>
-<H2><A NAME="toc6">6.</A> <A HREF="SDCCUdoc-6.html">Optimizations</A></H2>
-<UL>
-<LI><A HREF="SDCCUdoc-6.html#ss6.1">6.1 Sub-expression elimination</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.2">6.2 Dead-Code elimination.</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.3">6.3 Copy-Propagation:</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.4">6.4 Loop optimizations</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.5">6.5 Algebraic simplifications:</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.6">6.6 'switch' statements.</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.7">6.7 bit-shifting operations.</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.8">6.8 Highest Order Bit.</A>
-<LI><A HREF="SDCCUdoc-6.html#ss6.9">6.9 Peep-hole optimizer.</A>
+<H2><A NAME="SECTION00022000000000000000">
+1.2 Open Source</A>
+</H2>
+
+<P>
+All packages used in this compiler system are <I>opensource</I>(freeware);
+source code for all the sub-packages (asxxxx assembler/linker, pre-processor)
+are distributed with the package. This documentation is maintained
+using a freeware word processor (LYX).
+
+<P>
+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, 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, 59 Temple Place - Suite
+330, Boston, MA 02111-1307, USA. In other words, you are welcome to
+use, share and improve this program. You are forbidden to forbid anyone
+else to use, share and improve what you give them. Help stamp out
+software-hoarding!
+
+<P>
+
+<H2><A NAME="SECTION00023000000000000000">
+1.3 System Requirements</A>
+</H2>
+
+<P>
+What do you need before you start installation of SDCC? A computer,
+and a desire to compute. The preferred method of installation is to
+compile SDCC from source using GNU GCC and make. For Windows some
+pre-compiled binary distributions are available for your convenience.
+You should have some experience with command line tools and compiler
+use.
+
+<P>
+
+<H2><A NAME="SECTION00024000000000000000">
+1.4 Other Resources</A>
+</H2>
+
+<P>
+The SDCC home page at http://sdcc.sourceforge.net/ is a great
+place to find distribution sets. You can also find links to the user
+mailing lists that offer help or discuss SDCC with other SDCC users.
+Web links to other SDCC related sites can also be found here. This
+document can be found in the DOC directory of the source package as
+a text or HTML file. Some of the other tools(simulator and assembler)
+included with SDCC contain their own documentation and can be found
+in the source distribution. If you want the latest unreleased software,
+the complete source package is available directly by anonymous CVS
+on www.sourceforge.net.
+
+<P>
+
+<H1><A NAME="SECTION00030000000000000000">
+2 Installation</A>
+</H1>
+
+<P>
+
+<H2><A NAME="SECTION00031000000000000000">
+2.1 Linux/Unix Installation</A>
+</H2>
+
+<P>
+
+<OL>
+<LI>Download the source package, it will be named something like sdcc-2.x.x.tgz.
+</LI>
+<LI>Bring up a command line terminal, such as xterm.
+</LI>
+<LI>Unpack the file using a command like: tar -xzf sdcc-2.x.x.tgz, this
+will create a sub-directory called sdcc with all of the sources.
+</LI>
+<LI>Change directory into the main SDCC directory, for example type: ``cd
+sdcc''.
+</LI>
+<LI>Type ``./configure''. This configures the package for compilation
+on your system.
+</LI>
+<LI>Type ``make''. All of the source packages will compile, this can
+take a while.
+</LI>
+<LI>Type ``make install'' as root. This copies the binary executables
+to the install directories.
+</LI>
+</OL>
+
+<P>
+
+<H2><A NAME="SECTION00032000000000000000">
+2.2 Windows Installation</A>
+</H2>
+
+<P>
+For installation under Windows you first need to pick between a pre-compiled
+binary package, or installing the source package along with the Cygwin
+package. The binary package is the quickest to install, while the
+Cygwin package includes all of the open source power tools used to
+compile the complete SDCC source package in the Windows environment.
+If you are not familiar with the Unix command line environment, you
+may want to read the section on additional information for Windows
+users prior to your initial installation.
+
+<P>
+
+<H3><A NAME="SECTION00032100000000000000">
+2.2.1 Windows Install Using a Binary Package</A>
+</H3>
+
+<P>
+
+<OL>
+<LI>Download the binary package and unpack it using your favorite unpacking
+tool(gunzip, WinZip, etc). This should unpack to a group of sub-directories.
+An example directory structure after unpacking is: c:\usr\local\bin
+for the executables, c:\usr\local\share\sdcc\include
+and c:\usr\local\share\sdcc\lib
+for the include and libraries.
+</LI>
+<LI>Adjust your environment PATH to include the location of the bin directory.
+For example, make a setsdcc.bat file with the following: set PATH=c:\usr\local\bin;%PATH%
+</LI>
+<LI>When you compile with sdcc, you may need to specify the location of
+the lib and include folders. For example, sdcc -I c:\usr\local\share\sdcc\include
+-L c:\usr\local\share\sdcc\lib\small
+test.c
+</LI>
+</OL>
+
+<P>
+
+<H3><A NAME="SECTION00032200000000000000">
+2.2.2 Windows Install Using Cygwin</A>
+</H3>
+
+<P>
+
+<OL>
+<LI>Download and install the cygwin package from the redhat site<I>http://sources.redhat.com/cygwin/</I>.
+Currently, this involved downloading a small install program which
+then automates downloading and installing selected parts of the package(a
+large 80M byte sized dowload for the whole thing).
+</LI>
+<LI>Bring up a Unix/Bash command line terminal from the Cygwin menu.
+</LI>
+<LI>Follow the instructions in the preceding Linux/Unix installation section.
+</LI>
+</OL>
+
+<P>
+
+<H2><A NAME="SECTION00033000000000000000">
+2.3 Testing out the SDCC Compiler</A>
+</H2>
+
+<P>
+The first thing you should do after installing your SDCC compiler
+is to see if it runs. Type ``sdcc -version'' at the prompt, and
+the program should run and tell you the version. If it doesn't run,
+or gives a message about not finding sdcc program, then you need to
+check over your installation. Make sure that the sdcc bin directory
+is in your executable search path defined by the PATH environment
+setting(see the Trouble-shooting section for suggestions). Make sure
+that the sdcc program is in the bin folder, if not perhaps something
+did not install correctly.
+
+<P>
+SDCC binaries are commonly installed in a directory arrangement like
+this:
+
+<P>
+<TABLE CELLPADDING=3 BORDER="1">
+<TR><TD ALIGN="LEFT">/usr/local/bin</TD>
+<TD ALIGN="LEFT">Holds executables(sdcc, s51, aslink, ...)</TD>
+</TR>
+<TR><TD ALIGN="LEFT">/usr/local/share/sdcc/lib</TD>
+<TD ALIGN="LEFT">Holds common C libraries</TD>
+</TR>
+<TR><TD ALIGN="LEFT">/usr/local/share/sdcc/include</TD>
+<TD ALIGN="LEFT">Holds common C header files</TD>
+</TR>
+</TABLE>
+
+<P>
+Make sure the compiler works on a very simple example. Type in the
+following test.c program using your favorite editor:
+
+<P>
+<I>main()</I>
+<BR><I>{ int i;</I>
+<BR><I>i = 0;</I>
+<BR><I>i += 10;</I>
+<BR><I>}</I>
+<BR>
+<P>
+Compile this using the following command: ``sdcc -c test.c''.
+If all goes well, the compiler will generate a test.asm and test.rel
+file. Congratulations, you've just compiled your first program with
+SDCC. We used the -c option to tell SDCC not to link the generated
+code, just to keep things simple for this step.
+
+<P>
+The next step is to try it with the linker. Type in ``sdcc test.c''.
+If all goes well the compiler will link with the libraries and produce
+a test.ihx output file. If this step fails(no test.ihx, and the linker
+generates warnings), then the problem is most likely that sdcc cannot
+find the usr/local/share/sdcc/lib/small directory(see the Install
+trouble-shooting section for suggestions).
+
+<P>
+The final test is to ensure sdcc can use the standard header files
+and libraries. Edit test.c and change it to the following:
+
+<P>
+<I>#include <string.h></I>
+<BR><I>main()</I>
+<BR><I>{ char str1[10];</I>
+<BR><I>strcpy(str1, ``testing'');</I>
+<BR><I>}</I>
+
+<P>
+Compile this by typing: ``sdcc test.c''. This should generate
+a test.ihx output file, and it should give no warnings such as not
+finding the string.h file. If it cannot find the string.h file, then
+the problem is that sdcc cannot find the /usr/local/share/sdcc/include
+directory(see the Install trouble-shooting section for suggestions).
+
+<P>
+
+<H2><A NAME="SECTION00034000000000000000">
+2.4 Install Trouble-shooting</A>
+</H2>
+
+<P>
+
+<H3><A NAME="SECTION00034100000000000000">
+2.4.1 SDCC cannot find libraries or header files.</A>
+</H3>
+
+<P>
+The default installation assumes the libraries and header files are
+located at ``/usr/local/share/sdcc/lib'' and ``/usr/local/share/sdcc/include''.
+An alternative is to specify these locations as compiler options like
+this: sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include
+test.c
+
+<P>
+
+<H3><A NAME="SECTION00034200000000000000">
+2.4.2 SDCC does not compile correctly.</A>
+</H3>
+
+<P>
+A few things to try include starting from scratch by unpacking the
+.tgz source package again in an empty directory. If this doesn't work,
+you could try downloading a different version. If this doesn't work,
+you can re-direct the install messages by doing the following:
+
+<P>
+$./make > dump.txt 2>&1
+
+<P>
+After this you can examine the dump.txt files to locate the problem.
+Or these messages can be attached to an email that could be helpful
+when requesting help from the mailing list.
+
+<P>
+
+<H3><A NAME="SECTION00034300000000000000">
+2.4.3 What the ``./configure'' does</A>
+</H3>
+
+<P>
+The ``./configure'' command is a script that analyzes your system
+and performs some configuration to ensure the source package compiles
+on your system. It will take a few minutes to run, and will compile
+a few tests to determine what compiler features are installed.
+
+<P>
+
+<H3><A NAME="SECTION00034400000000000000">
+2.4.4 What the ``make'' does.</A>
+</H3>
+
+<P>
+This runs the GNU make tool, which automatically compiles all the
+source packages into the final installed binary executables.
+
<P>
-<H2><A NAME="toc7">7.</A> <A HREF="SDCCUdoc-7.html">Pointers</A></H2>
+
+<H3><A NAME="SECTION00034500000000000000">
+2.4.5 What the ``make install'' command does.</A>
+</H3>
+
+<P>
+This will install the compiler, other executables and libraries in
+to the appropriate system directories. The default is to copy the
+executables to /usr/local/bin and the libraries and header files to
+/usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
+
+<P>
+
+<H2><A NAME="SECTION00035000000000000000">
+2.5 Additional Information for Windows Users</A>
+</H2>
+
+<P>
+The standard method of installing on a Unix system involves compiling
+the source package. This is easily done under Unix, but under Windows
+it can be a more difficult process. The Cygwin is a large package
+to download, and the compilation runs considerably slower under Windows
+due to the overhead of the Cygwin tool set. An alternative is to install
+a pre-compiled Windows binary package. There are various trade-offs
+between each of these methods.
+
+<P>
+The Cygwin package allows a Windows user to run a Unix command line
+interface(bash shell) and also implements a Unix like file system
+on top of Windows. Included are many of the famous GNU software development
+tools which can augment the SDCC compiler.This is great if you have
+some experience with Unix command line tools and file system conventions,
+if not you may find it easier to start by installing a binary Windows
+package. The binary packages work with the Windows file system conventions.
+
+<P>
+
+<H3><A NAME="SECTION00035100000000000000">
+2.5.1 Getting started with Cygwin</A>
+</H3>
+
+<P>
+SDCC is typically distributed as a tarred/gzipped file(.tgz). This
+is a packed file similar to a .zip file. Cygwin includes the tools
+you will need to unpack the SDCC distribution(tar and gzip). To unpack
+it, simply follow the instructions under the Linux/Unix install section.
+Before you do this you need to learn how to start a cygwin shell and
+some of the basic commands used to move files, change directory, run
+commands and so on. The change directory command is ``cd'', the
+move command is ``mv''. To print the current working directory,
+type ``pwd''. To make a directory, use ``mkdir''.
+
+<P>
+There are some basic differences between Unix and Windows file systems
+you should understand. When you type in directory paths, Unix and
+the Cygwin bash prompt uses forward slashes '/' between directories
+while Windows traditionally uses '\' backward slashes.
+So when you work at the Cygwin bash prompt, you will need to use the
+forward '/' slashes. Unix does not have a concept of drive letters,
+such as ``c:``, instead all files systems attach and appear
+as directories.
+
+<P>
+
+<H3><A NAME="SECTION00035200000000000000">
+2.5.2 Running SDCC as Native Compiled Executables</A>
+</H3>
+
+<P>
+If you use the pre-compiled binaries, the install directories for
+the libraries and header files may need to be specified on the sdcc
+command line like this: sdcc -L c:\usr\local\sdcc\lib\small
+-I c:\usr\local\sdcc\include
+test.c if you are running outside of a Unix bash shell.
+
+<P>
+If you have successfully installed and compiled SDCC with the Cygwin
+package, it is possible to compile into native .exe files by using
+the additional makefiles included for this purpose. For example, with
+the Borland 32-bit compiler you would run make -f Makefile.bcc. A
+command line version of the Borland 32-bit compiler can be downloaded
+from the Inprise web site.
+
+<P>
+
+<H2><A NAME="SECTION00036000000000000000">
+2.6 SDCC on Other Platforms</A>
+</H2>
<P>
-<H2><A NAME="toc8">8.</A> <A HREF="SDCCUdoc-8.html">Parameters & Local Variables</A></H2>
<UL>
-<LI><A HREF="SDCCUdoc-8.html#ss8.1">8.1 Overlaying</A>
+<LI><B>FreeBSD and other non-GNU Unixes</B> - Make sure the GNU make
+is installed as the default make tool.
+</LI>
+<LI>SDCC has been ported to run under a variety of operating systems and
+processors. If you can run GNU GCC/make then chances are good SDCC
+can be compiled and run on your system.
+</LI>
+</UL>
+
+<P>
+
+<H2><A NAME="SECTION00037000000000000000">
+2.7 Advanced Install Options</A>
+</H2>
+
+<P>
+The ``configure'' command has several options. The most commonly
+used option is -prefix=<directory name>, where <directory name> is
+the final location for the sdcc executables and libraries, (default
+location is /usr/local). The installation process will create the
+following directory structure under the <directory name> specified.
+
+<P>
+bin/ - binary exectables (add to PATH environment variable)
+<BR> share/
+<BR> sdcc/include/ - include header files
+<BR> sdcc/lib/ -
+<BR> small/ - Object & library files for small
+model library
+<BR> large/ - Object & library files for large
+model library
+<BR> ds390/ - Object & library files forDS80C390
+library
+
+<P>
+The command
+
+<P>
+<B><U><FONT SIZE="+1">'./configure -prefix=/usr/local'' </FONT></U></B>
+<P>
+
+
+<P>
+will configure the compiler to be installed in directory /usr/local/bin.
+
+<P>
+
+<H2><A NAME="SECTION00038000000000000000">
+2.8 Components of SDCC</A>
+</H2>
+
+<P>
+SDCC is not just a compiler, but a collection of tools by various
+developers. These include linkers, assemblers, simulators and other
+components. Here is a summary of some of the components. Note that
+the included simulator and assembler have separate documentation which
+you can find in the source package in their respective directories.
+As SDCC grows to include support for other processors, other packages
+from various developers are included and may have their own sets of
+documentation.
+
+<P>
+You might want to look at the various executables which are installed
+in the bin directory. At the time of this writing, we find the following
+programs:
+
+<P>
+<B>sdcc</B> - The compiler.
+
+<P>
+<B>aslink</B> -The linker for 8051 type processors.
+
+<P>
+<B>asx8051</B> - The assembler for 8051 type processors.
+
+<P>
+<B>sdcpp</B> - The C preprocessor.
+
+<P>
+<B>sdcpd</B> - The source debugger.
+
+<P>
+<B>s51</B> - The ucSim 8051 simulator.
+
+<P>
+<B>linkz80, linkgbz80</B> - The Z80 and GameBoy Z80 linkers.
+
+<P>
+<B>as-z80, as-gbz80</B> - The Z80 and GameBoy Z80 assemblers.
+
+<P>
+<B>packihx</B> - A tool to pack Intel hex files.
+
+<P>
+As development for other processors proceeds, this list will expand
+to include executables to support processors like AVR, PIC, etc.
+
+<P>
+
+<H3><A NAME="SECTION00038100000000000000">
+2.8.1 cpp ( C-Preprocessor)</A>
+</H3>
+
+<P>
+The preprocessor is extracted into the directory <I>SDCCDIR/cpp</I>,
+it is a modified version of the GNU preprocessor. The C preprocessor
+is used to pull in #include sources, process #ifdef statements,
+#defines and so on.
+
+<P>
+
+<H3><A NAME="SECTION00038200000000000000">
+2.8.2 asxxxx & aslink ( The assembler and Linkage Editor)</A>
+</H3>
+
+<P>
+This is retargettable assembler & linkage editor, it was developed
+by Alan Baldwin, John Hartman created the version for 8051, and I
+(Sandeep) have some enhancements and bug fixes for it to work properly
+with the SDCC. This component is extracted into the directory <I>SDCCDIR/asxxxx.</I>
+
<P>
-<H2><A NAME="toc9">9.</A> <A HREF="SDCCUdoc-9.html">critical Functions.</A></H2>
+
+<H3><A NAME="SECTION00038300000000000000">
+2.8.3 SDCC - The compiler</A>
+</H3>
<P>
-<H2><A NAME="toc10">10.</A> <A HREF="SDCCUdoc-10.html">Absolute addressing.</A></H2>
+This is the actual compiler, it in turn uses the c-preprocessor and
+invokes the assembler and linkage editors. All files with the prefix
+<I>SDCC</I> are part of the compiler and are extracted into the the
+directory <I>SDCCDIR.</I>
<P>
-<H2><A NAME="toc11">11.</A> <A HREF="SDCCUdoc-11.html">Interrupt Service Routines</A></H2>
+
+<H3><A NAME="SECTION00038400000000000000">
+2.8.4 S51 - Simulator</A>
+</H3>
<P>
-<H2><A NAME="toc12">12.</A> <A HREF="SDCCUdoc-12.html">Startup Code</A></H2>
+s51 is a freeware, opensource simulator developed by Daniel Drotos
+<drdani@mazsola.iit.uni-miskolc.hu>. The executable is built as part
+of the build process, for more information visit Daniel's website
+at <http://mazsola.iit.uni-miskolc.hu/drdani/embedded/s51/>.
<P>
-<H2><A NAME="toc13">13.</A> <A HREF="SDCCUdoc-13.html">Inline assembler code.</A></H2>
+
+<H3><A NAME="SECTION00038500000000000000">
+2.8.5 SDCDB - Source Level Debugger</A>
+</H3>
<P>
-<H2><A NAME="toc14">14.</A> <A HREF="SDCCUdoc-14.html">int (16 bit) and long (32 bit ) support.</A></H2>
+SDCDB is the companion source level debugger . The current version
+of the debugger uses Daniel's Simulator S51, but can be easily changed
+to use other simulators.
<P>
-<H2><A NAME="toc15">15.</A> <A HREF="SDCCUdoc-15.html">Floating point support</A></H2>
+
+<H1><A NAME="SECTION00040000000000000000">
+3 Using SDCC</A>
+</H1>
<P>
-<H2><A NAME="toc16">16.</A> <A HREF="SDCCUdoc-16.html">Memory Models</A></H2>
+
+<H2><A NAME="SECTION00041000000000000000">
+3.1 Compiling</A>
+</H2>
<P>
-<H2><A NAME="toc17">17.</A> <A HREF="SDCCUdoc-17.html">Defines created by the compiler.</A></H2>
+
+<H3><A NAME="SECTION00041100000000000000">
+3.1.1 Single Source File Projects</A>
+</H3>
<P>
-<H2><A NAME="toc18">18.</A> <A HREF="SDCCUdoc-18.html">Pragmas</A></H2>
+For single source file 8051 projects the process is very simple. Compile
+your programs with the following command
<P>
-<H2><A NAME="toc19">19.</A> <A HREF="SDCCUdoc-19.html">Library routines.</A></H2>
+<FONT SIZE="-1">sdcc sourcefile.c</FONT>
+<P>
+
<P>
-<PRE>
-printf_small("my str %s, my int %d\n",(char _generic *)mystr,myint);
-
-</PRE>
+The above command will compile ,assemble and link your source file.
+Output files are as follows.
<P>
+
<UL>
-<LI><B>stdarg.h </B>- contains definition for the following macros to be used for
-variable parameter list, note that a function can have a variable parameter
-list if and only if it is 'reentrant'
-<P>va_list, va_start, va_arg, va_end.
+<LI><FONT SIZE="-1">sourcefile.asm - Assembler source file created by the
+compiler</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">sourcefile.lst - Assembler listing file created by
+the Assembler</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">sourcefile.rst - Assembler listing file updated with
+linkedit information , created by linkage editor</FONT>
+<P>
+
</LI>
-<LI><B>setjmp.h </B>- contains defintion for ANSI<B> setjmp </B>& <B>longjmp</B> routines. Note
-in this case setjmp & longjmp can be used between functions executing within
-the same register bank, if long jmp is executed from a function that is using
-a different register bank from the function issuing the setjmp function, the
-results may be unpredictable. The jump buffer requires 3 bytes of data (the
-stack pointer & a 16 byte return address), and can be placed in any address
-space.</LI>
-<LI><B>stdlib.h</B> - contains the following functions.
-<P>atoi, atol.
+<LI><FONT SIZE="-1">sourcefile.sym - symbol listing for the sourcefile,
+created by the assembler.</FONT>
+<P>
+
</LI>
-<LI><B>string.h </B>- contains the following functions.
-<P>strcpy, strncpy, strcat, strncat, strcmp, strncmp, strchr, strrchr, strspn,
-strcspn, strpbrk, strstr, strlen, strtok, memcpy, memcmp, memset.
+<LI><FONT SIZE="-1">sourcefile.rel - Object file created by the assembler,
+input to Linkage editor.</FONT>
+<P>
+
</LI>
-<LI><B>ctype.h</B> - contains the following routines.
-<P>iscntrl, isdigit, isgraph, islower, isupper, isprint, ispunct, isspace,
-isxdigit, isalnum, isalpha.
+<LI><FONT SIZE="-1">sourcefile.map - The memory map for the load module,
+created by the Linker.</FONT>
+<P>
+
</LI>
-<LI><B>malloc.h</B> - The malloc routines are developed by Dmitry S. Obukhov (dso@usa.net).
-These routines will allocate memory from the external ram. Here is a description
-on how to use them (as described by the author).
-<PRE>
-//Example:
- // #define DYNAMIC_MEMORY_SIZE 0x2000
- //
- .....
- // unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
-
- // unsigned char xdata * current_buffer;
- // .....
-
- // void main(void)
- // {
- // ...
- //
- init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
- //
- //Now it's possible to use malloc.
- // ...
- // current_buffer
- = malloc(0x100);
- //
-
-</PRE>
+<LI><FONT SIZE="-1">sourcefile.<ihx | s19> - The load module : ihx - Intel
+hex format (default ), s19 - Motorola S19 format when compiler option
+-out-fmt-s19 is used.</FONT>
+<P>
+
</LI>
-<LI><B>serial.h</B> - Serial IO routines are also developed by Dmitry S. Obukhov (dso@usa.net).
-These routines are interrupt driven with a 256 byte circular buffer, they also
-expect external ram to be present. Please see documentation in file SDCCDIR/sdcc51lib/serial.c
-. Note the header file "serial.h" MUST be included in the file containing the
-'main' function.</LI>
-<LI><B>ser.h </B>- Alternate serial routine provided by Wolfgang Esslinger <wolfgang@WiredMinds.com>
-these routines are more compact and faster. Please see documentation in file
-SDCCDIR/sdcc51lib/ser.c</LI>
-<LI><B>ser_ir.h </B>- Another alternate set of serial routines provided by Josef Wolf
-<jw@raven.inka.de> , these routines do not use the external ram.</LI>
-<LI><B>reg51.h</B> - contains register definitions for a standard 8051</LI>
-<LI><B>reg552.h </B>- contains register definitions for 80C552.</LI>
-<LI><B>float.h</B> - contains min, max and other floating point related stuff.</LI>
</UL>
-<P>All library routines are compiled as --model-small , they are all non-reentrant,
-if you plan to use the large model or want to make these routines reentrant,
-then they will have to be recompiled with the appropriate compiler option.
-<P>Have not had time to do the more involved routines like printf, will get
-to them shortly.
+
<P>
-<H2><A NAME="toc20">20.</A> <A HREF="SDCCUdoc-20.html">Interfacing with assembly routines.</A></H2>
-<UL>
-<LI><A HREF="SDCCUdoc-20.html#ss20.1">20.1 Global registers used for parameter passing.</A>
-<LI><A HREF="SDCCUdoc-20.html#ss20.2">20.2 With --noregparms option.</A>
+<H3><A NAME="SECTION00041200000000000000">
+3.1.2 Projects with Multiple Source Files</A>
+</H3>
+
+<P>
+SDCC can compile only ONE file at a time. Let us for example assume
+that you have a project containing the following files.
+
+<P>
+<FONT SIZE="-1">foo1.c ( contains some functions )</FONT>
<P>
-<H2><A NAME="toc21">21.</A> <A HREF="SDCCUdoc-21.html">External Stack.</A></H2>
+
+<P>
+<FONT SIZE="-1">foo2.c (contains some more functions)</FONT>
<P>
-<H2><A NAME="toc22">22.</A> <A HREF="SDCCUdoc-22.html">ANSI-Compliance.</A></H2>
+
+<P>
+<FONT SIZE="-1">foomain.c (contains more functions and the function
+main)</FONT>
<P>
-<H2><A NAME="toc23">23.</A> <A HREF="SDCCUdoc-23.html">Cyclomatic Complexity</A></H2>
+
<P>
-<H2><A NAME="toc24">24.</A> <A HREF="SDCCUdoc-24.html">TIPS</A></H2>
+The first two files will need to be compiled separately with the commands
<P>
-<H2><A NAME="toc25">25.</A> <A HREF="SDCCUdoc-25.html">Retargetting for other MCUs.</A></H2>
+<FONT SIZE="-1">sdcc -c foo1.c</FONT>
+<P>
+
+<P>
+<FONT SIZE="-1">sdcc -c foo2.c</FONT>
<P>
-<H2><A NAME="toc26">26.</A> <A HREF="SDCCUdoc-26.html">Reporting Bugs</A></H2>
+
<P>
-<H2><A NAME="toc27">27.</A> <A HREF="SDCCUdoc-27.html">SDCDB - Source level debugger.</A></H2>
+Then compile the source file containing main and link the other files
+together with the following command.
-<UL>
-<LI><A HREF="SDCCUdoc-27.html#ss27.1">27.1 Compiling for debugging.</A>
-<LI><A HREF="SDCCUdoc-27.html#ss27.2">27.2 How the debugger works.</A>
-<LI><A HREF="SDCCUdoc-27.html#ss27.3">27.3 Starting the debugger.</A>
-<LI><A HREF="SDCCUdoc-27.html#ss27.4">27.4 Command line options.</A>
-<LI><A HREF="SDCCUdoc-27.html#ss27.5">27.5 Debugger Commands.</A>
-<LI><A HREF="SDCCUdoc-27.html#ss27.6">27.6 Interfacing with XEmacs.</A>
<P>
-<H2><A NAME="toc28">28.</A> <A HREF="SDCCUdoc-28.html">Conclusion</A></H2>
+<FONT SIZE="-1">sdcc foomain.c foo1.rel foo2.rel</FONT>
+<P>
+
<P>
-<H2><A NAME="toc29">29.</A> <A HREF="SDCCUdoc-29.html">Acknowledgments</A></H2>
+Alternatively <I>foomain.c</I> can be separately compiled as well
-<HR>
-<A HREF="SDCCUdoc-1.html">Next</A>
-Previous
-Contents
+<P>
+<FONT SIZE="-1">sdcc -c foomain.c </FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">sdcc foomain.rel foo1.rel foo2.rel</FONT>
+<P>
+
+
+<P>
+The file containing the main function MUST be the FIRST file specified
+in the command line , since the linkage editor processes file in the
+order they are presented to it.
+
+<P>
+
+<H3><A NAME="SECTION00041300000000000000">
+3.1.3 Projects with Additional Libraries</A>
+</H3>
+
+<P>
+Some reusable routines may be compiled into a library, see the documentation
+for the assembler and linkage editor in the directory <I>SDCCDIR/asxxxx/asxhtm.htm</I>
+this describes how to create a <I>.lib</I> library file, the libraries
+created in this manner may be included using the command line, make
+sure you include the -L <library-path> option to tell the linker where
+to look for these files. Here is an example, assuming you have the
+source file <I>'foomain.c</I>' and a library <I>'foolib.lib'</I> in
+the directory <I>'mylib'</I>.
+
+<P>
+<FONT SIZE="-1">sdcc foomain.c foolib.lib -L mylib</FONT>
+<P>
+
+
+<P>
+Note here that <I>'mylib</I>' must be an absolute path name.
+
+<P>
+The view of the way the linkage editor processes the library files,
+it is recommended that you put each source routine in a separate file
+and combine them using the .lib file. For an example see the standard
+library file 'libsdcc.lib' in the directory SDCCDIR/sdcc51lib.
+
+<P>
+
+<H2><A NAME="SECTION00042000000000000000">
+3.2 Command Line Options</A>
+</H2>
+
+<P>
+
+<H3><A NAME="SECTION00042100000000000000">
+3.2.1 Processor Selection Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B>-mmcs51</B>]Generate code for the MCS51 (8051) family of processors.
+This is the default processor target.
+</LI>
+<LI>[<B>-mds390</B>]Generate code for the DS80C390 processor.
+</LI>
+<LI>[<B>-mz80</B>]Generate code for the Z80 family of processors.
+</LI>
+<LI>[<B>-mgbz80</B>]Generate code for the GameBoy Z80 processor.
+</LI>
+<LI>[<B>-mavr</B>]Generate code for the Atmel AVR processor(In development,
+not complete).
+</LI>
+<LI>[<B>-mpic14</B>]Generate code for the PIC 14-bit processors(In development,
+not complete).
+</LI>
+<LI>[<B>-mtlcs900h</B>]Generate code for the Toshiba TLCS-900H processor(In
+development, not complete).
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042200000000000000">
+3.2.2 Path, Lib and Define Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B><U>-I<path></U></B>] The additional location where the pre
+processor will look for <..h> or ``..h'' files.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-D<macro[=value]></FONT></U></B>]Command line definition
+of macros. Passed to the pre processor.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-lib-path(-L)</FONT></U></B>]<absolute path to additional
+libraries> This option is passed to the linkage editor, additional
+libraries search path. The path name must be absolute. Additional
+library files may be specified in the command line . See section Compiling
+programs for more details.
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042300000000000000">
+3.2.3 MCS51 Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B><FONT SIZE="+1">-model-large</FONT></B>]Generate code for Large model programs
+see section Memory Models for more details. If this option is used
+all source files in the project should be compiled with this option.
+In addition the standard library routines are compiled with small
+model , they will need to be recompiled.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-model-small</FONT></U></B>]Generate code for Small
+Model programs see section Memory Models for more details. This is
+the default model.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-model-flat24</FONT></U></B>]Generate code forDS80C390
+24-bit flat mode. See section Memory Models for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-stack-</FONT></U></B><B><I><U><FONT SIZE="+1">auto</FONT></U></I></B>]All
+functions in the source file will be compiled as <I>reentrant</I>,
+i.e. the parameters and local variables will be allocated on the stack.
+see section Parameters and Local Variables for more details. If this
+option is used all source files in the project should be compiled
+with this option.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-xstack</FONT></U></B>]Uses a pseudo stack in the first
+256 bytes in the external ram for allocating variables and passing
+parameters. See section on external stack for more details.
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042400000000000000">
+3.2.4 Optimization Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B><U><FONT SIZE="+1">-nogcse</FONT></U></B>]Will not do global subexpression
+elimination, this option may be used when the compiler creates undesirably
+large stack/data spaces to store compiler temporaries. A warning message
+will be generated when this happens and the compiler will indicate
+the number of extra bytes it allocated. It recommended that this option
+NOT be used , #pragma NOGCSE can be used to turn off global subexpression
+elimination for a given function only.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-noinvariant</FONT></U></B>]Will not do loop invariant
+optimizations, this may be turned off for reasons explained for the
+previous option . For more details of loop optimizations performed
+see section Loop Invariants.It recommended that this option NOT be
+used , #pragma NOINVARIANT can be used to turn off invariant optimizations
+for a given function only.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-noinduction</FONT></U></B>]Will not do loop induction
+optimizations, see section Strength reduction for more details.It
+recommended that this option NOT be used , #pragma NOINDUCTION can
+be used to turn off induction optimizations for given function only.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-nojtbound</FONT></U></B>] Will not generate boundary
+condition check when switch statements are implemented using jump-tables.
+See section Switch Statements for more details.It recommended that
+this option NOT be used , #pragma NOJTBOUND can be used to turn off
+boundary checking for jump tables for a given function only.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-noloopreverse</FONT></U></B>]Will not do loop reversal
+optimization
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-noregparms</FONT></U></B>]By default the first parameter
+is passed using global registers (DPL,DPH,B,ACC). This option will
+disable parameter passing using registers. NOTE: if your program uses
+the 16/32 bit support routines (for multiplication/division) these
+library routines will need to be recompiled with the -noregparms
+option as well.
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042500000000000000">
+3.2.5 DS390 Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B>-stack-auto</B>]See MCS51 section for description.
+</LI>
+<LI>[<B>-stack-10bit</B>]This option generates code for the 10 bit
+stack mode of the Dallas DS80C390 part. In this mode, the stack is
+located in the lower 1K of the internal RAM, which is mapped to 0x400000.
+Note that the support is incomplete, since it still uses a single
+byte as the stack pointer. This means that only the lower 256 bytes
+of the potential 1K stack space can actually be used. However, this
+does allow you to reclaim the precious 256 bytes of low RAM for use
+for the DATA and IDATA segments. The compiler will not generate any
+code to put the processor into 10 bit stack mode. It is important
+to ensure that the processor is in this mode before calling any re-entrant
+functions compiled with this option. In principle, this should work
+with the -stack-auto option, but that has not been tested. It is
+incompatible with the -xstack option. It also only makes sense if
+the processor is in 24 bit contiguous addressing mode (see the -model-flat24
+option).
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042600000000000000">
+3.2.6 Other Options</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>[<B><U><FONT SIZE="+1">-callee-saves</FONT></U></B>]<B><U><FONT SIZE="+1">function1[,function2][,function3]....</FONT></U></B>
+The compiler by default uses a caller saves convention for register
+saving across function calls, however this can cause unneccessary
+register pushing & popping when calling small functions from larger
+functions. This option can be used to switch the register saving convention
+for the function names specified. The compiler will not save registers
+when calling these functions, extra code will be generated at the
+entry & exit for these functions to save & restore the registers
+used by these functions, this can SUBSTANTIALLY reduce code & improve
+run time performance of the generated code. In future the compiler
+(with interprocedural analysis) will be able to determine the appropriate
+scheme to use for each function call. DO NOT use this option for built-in
+functions such as _muluint..., if this option is used for a library
+function the appropriate library function needs to be recompiled with
+the same option. If the project consists of multiple source files
+then all the source file should be compiled with the same -callee-saves
+option string. Also see Pragma Directive CALLEE-SAVES. .
+</LI>
+<LI>[<B><U>-debug</U></B>]When this option is used the compiler
+will generate debug information , that can be used with the SDCDB.
+The debug information is collected in a file with .cdb extension.
+For more information see documentation for SDCDB.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-regextend</FONT></U></B>] This option will cause the
+compiler to define pseudo registers , if this option is used, all
+source files in the project should be compiled with this option. See
+section Register Extension for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-compile-only</FONT></U></B><FONT SIZE="+1">(-c)</FONT>] will compile
+and assemble the source only, will not call the linkage editor.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-xram-loc</FONT></U></B><Value>]The start location of
+the external ram, default value is 0. The value entered can be in
+Hexadecimal or Decimal format .eg. -xram-loc 0x8000 or -xram-loc
+32768.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-code-loc</FONT></U></B><Value>]The start location of
+the code segment , default value 0. Note when this option is used
+the interrupt vector table is also relocated to the given address.
+The value entered can be in Hexadecimal or Decimal format .eg. -code-loc
+0x8000 or -code-loc 32768.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-stack-loc</FONT></U></B><Value>]The initial value of
+the stack pointer. The default value of the stack pointer is 0x07
+if only register bank 0 is used, if other register banks are used
+then the stack pointer is initialized to the location above the highest
+register bank used. eg. if register banks 1 & 2 are used the stack
+pointer will default to location 0x18. The value entered can be in
+Hexadecimal or Decimal format .eg. -stack-loc 0x20 or -stack-loc
+32. If all four register banks are used the stack will be placed after
+the data segment (equivalent to -stack-after-data)
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-stack-after-data</FONT></U></B>]This option will cause
+the stack to be located in the internal ram after the data segment.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-data-loc</FONT></U></B><Value>]The start location of
+the internal ram data segment, the default value is 0x30.The value
+entered can be in Hexadecimal or Decimal format .eg. -data-loc 0x20
+or -data-loc 32.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-idata-loc</FONT></U></B><Value>]The start location
+of the indirectly addressable internal ram, default value is 0x80.
+The value entered can be in Hexadecimal or Decimal format .eg. -idata-loc
+0x88 or -idata-loc 136.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-peep-file</FONT></U></B><filename>]This option can
+be used to use additional rules to be used by the peep hole optimizer.
+See section Peep Hole optimizations for details on how to write these
+rules.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-E</FONT></U></B>]Run only the C preprocessor. Preprocess
+all the C source files specified and output the results to standard
+output.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-M</FONT></U></B>]Tell the preprocessor to output a rule
+suitable for make describing the dependencies of each object file.
+For each source file, the preprocessor outputs one make-rule whose
+target is the object file name for that source file and whose dependencies
+are all the files `#include'd in it. This rule may be a single line
+or may be continued with `\'-newline if it is long.
+The list of rules is printed on standard output instead of the preprocessed
+C program. `-M' implies `-E'.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-C</FONT></U></B>]Tell the preprocessor not to discard
+comments. Used with the `-E' option.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-MM</FONT></U></B>]Like `-M' but the output mentions
+only the user header files included with `#include file"'.
+System header files included with `#include <file>' are omitted.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-Aquestion(answer)</FONT></U></B>]Assert the answer answer
+for question, in case it is tested with a preprocessor conditional
+such as `#if #question(answer)'. `-A-' disables the standard assertions
+that normally describe the target machine.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-Aquestion</FONT></U></B>](answer) Assert the answer
+answer for question, in case it is tested with a preprocessor conditional
+such as `#if #question(answer)'. `-A-' disables the standard assertions
+that normally describe the target machine.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-Umacro</FONT></U></B>]Undefine macro macro. `-U' options
+are evaluated after all `-D' options, but before any `-include' and
+`-imacros' options.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dM</FONT></U></B>]Tell the preprocessor to output only
+a list of the macro definitions that are in effect at the end of preprocessing.
+Used with the `-E' option.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dD</FONT></U></B>]Tell the preprocessor to pass all
+macro definitions into the output, in their proper sequence in the
+rest of the output.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dN</FONT></U></B>]Like `-dD' except that the macro arguments
+and contents are omitted. Only `#define name' is included in the
+output.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-S</FONT></U></B>]Stop after the stage of compilation
+proper; do not as- semble. The output is an assembler code file for
+the input file specified.
+</LI>
+<LI>[<B><U>-Wa_asmOption[,asmOption]</U></B>...]Pass the asmOption
+to the assembler.
+</LI>
+<LI>[<B><U>-Wl_linkOption[,linkOption]</U></B>].. Pass the
+linkOption to the linker.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-int-long-reent</FONT></U></B>] Integer (16 bit) and
+long (32 bit) libraries have been compiled as reentrant. Note by default
+these libraries are compiled as non-reentrant. See section Installation
+for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-cyclomatic</FONT></U></B>]This option will cause the
+compiler to generate an information message for each function in the
+source file. The message contains some <I>important</I> information
+about the function. The number of edges and nodes the compiler detected
+in the control flow graph of the function, and most importantly the
+<I>cyclomatic complexity</I> see section on Cyclomatic Complexity
+for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-float-reent</FONT></U></B>] Floating point library
+is compiled as reentrant.See section Installation for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-out-fmt-ihx</FONT></U></B>]The linker output (final
+object code) is in Intel Hex format. (This is the default option).
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-out-fmt-s19</FONT></U></B>]The linker output (final
+object code) is in Motorola S19 format.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-nooverlay</FONT></U></B>] The compiler will not overlay
+parameters and local variables of any function, see section Parameters
+and local variables for more details.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-main-return</FONT></U></B>]This option can be used
+when the code generated is called by a monitor program. The compiler
+will generate a 'ret' upon return from the 'main' function. The default
+option is to lock up i.e. generate a 'ljmp .' .
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-no-peep</FONT></U></B>] Disable peep-hole optimization.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-peep-asm</FONT></U></B>] Pass the inline assembler
+code through the peep hole optimizer. Can cause unexpected changes
+to inline assembler code , please go through the peephole optimizer
+rules defnied in file 'SDCCpeeph.def' before using this option.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-iram-size</FONT></U></B><Value>]Causes the linker to
+check if the interal ram usage is within limits of the given value.
+</LI>
+</UL>
+<P>
+
+<H3><A NAME="SECTION00042700000000000000">
+3.2.7 Intermediate Dump Options</A>
+</H3>
+
+<P>
+The following options are provided for the purpose of retargetting
+and debugging the compiler . These provided a means to dump the intermediate
+code (iCode) generated by the compiler in human readable form at various
+stages of the compilation process.
+
+<P>
+
+<UL>
+<LI>[<B><U><FONT SIZE="+1">-dumpraw</FONT></U></B>]. This option will cause the
+compiler to dump the intermediate code into a file of named <I><source
+filename>.dumpraw</I> just after the intermediate code has been generated
+for a function , i.e. before any optimizations are done. The basic
+blocks at this stage ordered in the depth first number, so they may
+not be in sequence of execution.
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumpgcse</FONT></U></B><FONT SIZE="+1">.</FONT>]Will create a dump
+if iCode, after global subexpression elimination, into a file named
+<I><source filename>.dumpgcse.</I>
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumpdeadcode</FONT></U></B>].Will create a dump if
+iCode, after deadcode elimination, into a file named <I><source
+filename>.dumpdeadcode.</I>
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumploop.</FONT></U></B>]Will create a dump if iCode,
+after loop optimizations, into a file named <I><source filename>.dumploop.</I>
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumprange.</FONT></U></B>]Will create a dump if iCode,
+after live range analysis, into a file named <I><source filename>.dumprange.</I>
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumpregassign.</FONT></U></B>]Will create a dump if
+iCode, after register assignment , into a file named <I><source
+filename>.dumprassgn.</I>
+</LI>
+<LI>[<B><U><FONT SIZE="+1">-dumpall.</FONT></U></B>]Will cause all the above mentioned
+dumps to be created.
+</LI>
+</UL>Note that the files created for the dump are appended to each time.
+So the files should be deleted manually , before each dump is created.
+
+<P>
+When reporting bugs, it can be helpful to include these dumps along
+with the portion of the code that is causing the problem.
+
+<P>
+
+<H2><A NAME="SECTION00043000000000000000">
+3.3 MCS51 Storage Class Language Extensions</A>
+</H2>
+
+<P>
+In addition to the ANSI storage classes SDCC allows the following
+MCS51 specific storage classes.
+
+<P>
+
+<H3><A NAME="SECTION00043100000000000000">
+3.3.1 xdata</A>
+</H3>
+
+<P>
+Variables declared with this storage class will be placed in the extern
+RAM. This is the <B>default</B> storage class for Large Memory model
+.
+
+<P>
+<FONT SIZE="-1">eg.</FONT> <I><FONT SIZE="-1">xdata unsigned char xduc;</FONT></I>
+<P>
+
+
+<P>
+
+<H3><A NAME="SECTION00043200000000000000">
+3.3.2 data</A>
+</H3>
+
+<P>
+This is the <B>default</B> storage class for Small Memory model.
+Variables declared with this storage class will be allocated in the
+internal RAM.
+
+<P>
+<FONT SIZE="-1">eg.</FONT> <I><FONT SIZE="-1">data int iramdata;</FONT></I>
+<P>
+
+
+<P>
+
+<H3><A NAME="SECTION00043300000000000000">
+3.3.3 idata</A>
+</H3>
+
+<P>
+Variables declared with this storage class will be allocated into
+the indirectly addressable portion of the internal ram of a 8051 .
+
+<P>
+<FONT SIZE="-1">eg.</FONT><I><FONT SIZE="-1">idata int idi;</FONT></I>
+<P>
+
+
+<P>
+
+<H3><A NAME="SECTION00043400000000000000">
+3.3.4 bit</A>
+</H3>
+
+<P>
+This is a data-type and a storage class specifier. When a variable
+is declared as a bit , it is allocated into the bit addressable memory
+of 8051.
+
+<P>
+eg.<I>bit iFlag;</I>
+
+<P>
+
+<H3><A NAME="SECTION00043500000000000000">
+3.3.5 sfr / sbit</A>
+</H3>
+
+<P>
+Like the bit keyword, <I>sfr / sbit</I> signifies both a data-type
+and storage class, they are used to describe the special function
+registers and special bit variables of a 8051.
+
+<P>
+eg.
+
+<P>
+<I>sfr at 0x80 P0;</I> /* <SMALL>SPECIAL FUNCTION REGISTER </SMALL>P0 <SMALL>AT
+LOCATION 0X80 </SMALL>*/
+
+<P>
+<I>sbit at 0xd7 CY; /*</I> <I>CY (C<SMALL>ARRY </SMALL>F<SMALL>LAG) </SMALL>*/</I>
+
+<P>
+
+<H2><A NAME="SECTION00044000000000000000">
+3.4 Pointers</A>
+</H2>
+
+<P>
+SDCC allows (via language extensions) pointers to explicitly point
+to any of the memory spaces of the 8051. In addition to the explicit
+pointers, the compiler also allows a <I>_generic</I> class of pointers
+which can be used to point to any of the memory spaces.
+
+<P>
+Pointer declaration examples.
+
+<P>
+<FONT SIZE="-1">/* pointer physically in xternal ram pointing to object
+in internal ram */ </FONT>
+<BR><FONT SIZE="-1">data unsigned char * xdata p;</FONT>
+<BR>
+<P>
+
+
+<P>
+<FONT SIZE="-1">/* pointer physically in code rom pointing to data in xdata
+space */ </FONT>
+<BR><FONT SIZE="-1">xdata unsigned char * code p;</FONT>
+<BR>
+<P>
+
+
+<P>
+<FONT SIZE="-1">/* pointer physically in code space pointing to data in
+code space */ </FONT>
+<BR><FONT SIZE="-1">code unsigned char * code p;</FONT>
+<BR>
+<BR><FONT SIZE="-1">/* the folowing is a generic pointer physically located
+in xdata space */</FONT>
+<BR><FONT SIZE="-1">char * xdata p;</FONT>
+<P>
+
+
+<P>
+Well you get the idea. For compatibility with the previous version
+of the compiler, the following syntax for pointer declaration is also
+supported. Note the above examples will be portable to other commercially
+available compilers.
+
+<P>
+<FONT SIZE="-1">unsigned char _xdata *ucxdp; /* pointer to data in external
+ram */ </FONT>
+<BR><FONT SIZE="-1">unsigned char _data *ucdp ; /* pointer to data in internal
+ram */ </FONT>
+<BR><FONT SIZE="-1">unsigned char _code *uccp ; /* pointer to data in R/O
+code space */</FONT>
+<BR><FONT SIZE="-1">unsigned char _idata *uccp; /* pointer to upper 128
+bytes of ram */</FONT>
+<P>
+
+
+<P>
+All unqualified pointers are treated as 3 - byte '_generic' pointers.
+These type of pointers can also to be explicitly declared.
+
+<P>
+<FONT SIZE="-1">unsigned char _generic *ucgp;</FONT>
+<P>
+
+
+<P>
+The highest order byte of the generic pointers contains the data space
+information. Assembler support routines are called whenever data is
+stored or retrieved using _generic pointers. These are useful for
+developing reusable library routines. Explicitly specifying the pointer
+type will generate the most efficient code. Pointers declared using
+a mixture of OLD/NEW style could have unpredictable results.
+
+<P>
+
+<H2><A NAME="SECTION00045000000000000000">
+3.5 Parameters & Local Variables</A>
+</H2>
+
+<P>
+Automatic (local) variables and parameters to functions can either
+be placed on the stack or in data-space. The default action of the
+compiler is to place these variables in the internal RAM ( for small
+model) or external RAM (for Large model). They can be placed on the
+stack either by using the <I>-stack-auto</I> compiler option or by
+using the 'reentrant' keyword in the function declaration.
+
+<P>
+<TT><FONT SIZE="-2">eg</FONT></TT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">unsigned short foo( short i) reentrant { </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+Note that when the parameters & local variables are declared in the
+internal/external ram the functions are non-reentrant. Since stack
+space on 8051 is limited the <I>'reentrant'</I> keyword or the <I>-stack-auto</I>
+option should be used sparingly. Note the reentrant keyword just means
+that the parameters & local variables will be allocated to the stack,
+it DOES NOT mean that the function is register bank independent.
+
+<P>
+When compiled with the default option (i.e. non-reentrant ), local
+variables can be assigned storage classes and absolute addresses.
+
+<P>
+<TT><FONT SIZE="-2">eg</FONT></TT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">unsigned short foo() { </FONT>
+<BR><FONT SIZE="-1"> xdata unsigned short i; </FONT>
+<BR><FONT SIZE="-1"> bit bvar; </FONT>
+<BR><FONT SIZE="-1"> data at 0x31 unsiged short j; </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+In the above example the variable <I>i</I> will be allocated in the
+external ram, <I>bvar</I> in bit addressable space and <I>j</I> in
+internal ram. When compiled with the <I>-stack-auto</I> or when a
+function is declared as <I>'reentrant'</I> local variables cannot
+be assigned storage classes or absolute addresses.
+
+<P>
+Parameters however are not allowed any storage class, (storage classes
+for parameters will be ignored), their allocation is governed by the
+memory model in use , and the reentrancy options.
+
+<P>
+
+<H2><A NAME="SECTION00046000000000000000">
+3.6 Overlaying</A>
+</H2>
+
+<P>
+For non-reentrant functions SDCC will try to reduce internal ram space
+usage by overlaying parameters and local variables of a function (if
+possible). Parameters and local variables of a function will be allocated
+to an overlayable segment if the function has <I>no other function
+calls and the function is non-reentrant and the memory model is small.</I>
+If an explicit storage class is specified for a local variable , it
+will NOT be overplayed.
+
+<P>
+Note that the compiler (not the linkage editor) makes the decision
+for overlaying the data items. Functions that are called from an interrupt
+service routine should be preceded by a #pragma NOOVERLAY if they
+are not reentrant Along the same lines the compiler does not do any
+processing with the inline assembler code so the compiler might incorrectly
+assign local variables and parameters of a function into the overlay
+segment if the only function call from a function is from inline assembler
+code, it is safe to use the #pragma NOOVERLAY for functions which
+call other functions using inline assembler code.
+
+<P>
+Parameters and Local variables of functions that contain 16 or 32
+bit multiplication or division will NOT be overlayed since these are
+implemented using external functions.
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">#pragma SAVE </FONT>
+<BR><FONT SIZE="-1">#pragma NOOVERLAY </FONT>
+<BR><FONT SIZE="-1">void set_error( unsigned short errcd) </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> P3 = errcd; </FONT>
+<BR><FONT SIZE="-1">} </FONT>
+<BR><FONT SIZE="-1">#pragma RESTORE </FONT>
+<BR><FONT SIZE="-1">void some_isr () interrupt 2 using 1 </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> ... </FONT>
+<BR><FONT SIZE="-1"> set_error(10); </FONT>
+<BR><FONT SIZE="-1"> ... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+In the above example the parameter <I>errcd</I> for the function <I>set_error</I>
+would be assigned to the overlayable segment (if the #pragma NOOVERLAY
+was not present) , this could cause unpredictable runtime behavior.
+The pragma NOOVERLAY ensures that the parameters and local variables
+for the function are NOT overlayed.
+
+<P>
+
+<H2><A NAME="SECTION00047000000000000000">
+3.7 Critical Functions</A>
+</H2>
+
+<P>
+A special keyword may be associated with a function declaring it as
+'<I>critical</I>'. SDCC will generate code to disable all interrupts
+upon entry to a critical function and enable them back before returning
+. Note that nesting critical functions may cause unpredictable results.
+
+<P>
+eg
+
+<P>
+<FONT SIZE="-1">int foo () critical </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+The critical attribute maybe used with other attributes like <I>reentrant.</I>
+
+<P>
+
+<H2><A NAME="SECTION00048000000000000000">
+3.8 Absolute Addressing</A>
+</H2>
+
+<P>
+Data items can be assigned an absolute address with the <I>at <address></I>
+keyword, in addition to a storage class.
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">xdata at 0x8000 unsigned char PORTA_8255 ;</FONT>
+<P>
+
+
+<P>
+In the above example the <I>PORTA_8255</I> will be allocated to the
+location 0x8000 of the external ram.
+
+<P>
+Note that is this feature is provided to give the programmer access
+to <I>memory mapped</I> devices attached to the controller. The compiler
+does not actually reserve any space for variables declared in this
+way (they are implemented with an equate in the assembler), thus it
+is left to the programmer to make sure there are no overlaps with
+other variables that are declared without the absolute address, the
+assembler listing file (.lst) and the linker output files (<filename>.rst)
+and (<filename>.map) are a good places to look for such overlaps.
+
+<P>
+Absolute address can be specified for variables in all storage classes.
+
+<P>
+<FONT SIZE="-1">eg.</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">bit at 0x02 bvar;</FONT>
+<P>
+
+
+<P>
+The above example will allocate the variable at offset 0x02 in the
+bit-addressable space. There is no real advantage to assigning absolute
+addresses to variables in this manner , unless you want strict control
+over all the variables allocated.
+
+<P>
+
+<H2><A NAME="SECTION00049000000000000000">
+3.9 Interrupt Service Routines</A>
+</H2>
+
+<P>
+SDCC allows interrupt service routines to be coded in C, with some
+extended keywords.
+
+<P>
+<FONT SIZE="-1">void timer_isr (void) interrupt 2 using 1 </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1">.. </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+The number following the 'interrupt' keyword is the interrupt number
+this routine will service. The compiler will insert a call to this
+routine in the interrupt vector table for the interrupt number specified.
+The 'using' keyword is used to tell the compiler to use the specified
+register bank (8051 specific) when generating code for this function.
+Note that when some function is called from an interrupt service routine
+it should be preceded by a #pragma NOOVERLAY (if it is not reentrant)
+. A special note here, int (16 bit) and long (32 bit) integer division,
+multiplication & modulus operations are implemented using external
+support routines developed in ANSI-C, if an interrupt service routine
+needs to do any of these operations then the support routines (as
+mentioned in a following section) will have to recompiled using the
+-stack-auto option and the source file will need to be compiled using
+the -int-long-rent compiler option.
+
+<P>
+If you have multiple source files in your project, interrupt service
+routines can be present in any of them, but a prototype of the isr
+MUST be present in the file that contains the function <I>'main'</I>.
+
+<P>
+Interrupt Numbers and the corresponding address & descriptions for
+the Standard 8051 are listed below. SDCC will automatically adjust
+the interrupt vector table to the maximum interrupt number specified.
+
+<P>
+<TABLE CELLPADDING=3 BORDER="1">
+<TR><TD ALIGN="CENTER">Interrupt #</TD>
+<TD ALIGN="CENTER">Description</TD>
+<TD ALIGN="CENTER">Vector Address</TD>
+</TR>
+<TR><TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">External 0</TD>
+<TD ALIGN="CENTER">0x0003</TD>
+</TR>
+<TR><TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">Timer 0</TD>
+<TD ALIGN="CENTER">0x000B</TD>
+</TR>
+<TR><TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">External 1</TD>
+<TD ALIGN="CENTER">0x0013</TD>
+</TR>
+<TR><TD ALIGN="CENTER">3</TD>
+<TD ALIGN="CENTER">Timer 1</TD>
+<TD ALIGN="CENTER">0x001B</TD>
+</TR>
+<TR><TD ALIGN="CENTER">4</TD>
+<TD ALIGN="CENTER">Serial</TD>
+<TD ALIGN="CENTER">0x0023</TD>
+</TR>
+</TABLE>
+
+<P>
+If the interrupt service routine is defined without a register bank
+or with register bank 0 (using 0), the compiler will save the registers
+used by itself on the stack (upon entry and restore them at exit),
+however if such an interrupt service routine calls another function
+then the entire register bank will be saved on the stack. This scheme
+may be advantageous for small interrupt service routines which have
+low register usage.
+
+<P>
+If the interrupt service routine is defined to be using a specific
+register bank then only ``a'',''b'' & ``dptr'' are save
+and restored, if such an interrupt service routine calls another function
+(using another register bank) then the entire register bank of the
+called function will be saved on the stack. This scheme is recommended
+for larger interrupt service routines.
+
+<P>
+Calling other functions from an interrupt service routine is not recommended
+avoid it if possible.
+
+<P>
+
+<H2><A NAME="SECTION000410000000000000000">
+3.10 Startup Code</A>
+</H2>
+
+<P>
+The compiler inserts a jump to the C routine <B>_sdcc__external__startup()</B>
+at the start of the CODE area. This routine can be found in the file
+<B>SDCCDIR/sdcc51lib/_startup.c</B>, by default this routine returns
+0, if this routine returns a non-zero value , the static & global
+variable initialization will be skipped and the function main will
+be invoked, other wise static & global variables will be initialized
+before the function main is invoked. You could add a <B>_sdcc__external__startup()</B>
+routine to your program to override the default if you needed to setup
+hardware or perform some other critical operation prior to static
+& global variable initialization.
+
+<P>
+
+<H2><A NAME="SECTION000411000000000000000">
+3.11 Inline Assembler Code</A>
+</H2>
+
+<P>
+SDCC allows the use of in-line assembler with a few restriction as
+regards labels. All labels defined within inline assembler code HAS
+TO BE of the <I>form nnnnn$</I> where nnnn is a number less than
+100 (which implies a limit of utmost 100 inline assembler labels <SMALL>PER
+FUNCTION)</SMALL>. It is strongly recommended that each assembly instruction
+(including labels) be placed in a separate line ( as the example shows).
+When the <B><U>-peep-asm</U></B> command line option is used,
+the inline assembler code will be passed through the peephole optimizer,
+this might cause some unexpected changes in the inline assembler code,
+please go throught the peephole optimizer rules defined in file 'SDCCpeeph.def'
+carefully before using this option.
+
+<P>
+<FONT SIZE="-1">eg</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">_asm </FONT>
+<BR><FONT SIZE="-1"> mov b,#10 </FONT>
+<BR><FONT SIZE="-1">00001$: </FONT>
+<BR><FONT SIZE="-1"> djnz b,00001$ </FONT>
+<BR><FONT SIZE="-1">_endasm ;</FONT>
+<P>
+
+
+<P>
+The inline assembler code can contain any valid code understood by
+the assembler (this includes any assembler directives and comment
+lines ) . The compiler does not do any validation of the code within
+the <I>_asm ... _endasm;</I> keyword pair.
+
+<P>
+Inline assembler code cannot reference any C-Labels however it can
+reference labels defined by the inline assembler.
+
+<P>
+<FONT SIZE="-1">eg</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">foo() { </FONT>
+<BR><FONT SIZE="-1">... /* some c code */ </FONT>
+<BR><FONT SIZE="-1">_asm </FONT>
+<BR><FONT SIZE="-1"> ; some assembler code </FONT>
+<BR><FONT SIZE="-1"> ljmp $0003 </FONT>
+<BR><FONT SIZE="-1">_endasm ; </FONT>
+<BR><FONT SIZE="-1">... /* some more c code */ </FONT>
+<BR><FONT SIZE="-1">clabel: /* inline assembler cannot reference this label
+*/ </FONT>
+<BR><FONT SIZE="-1">_asm </FONT>
+<BR><FONT SIZE="-1"> $0003: ;label (can be reference by inline assembler
+only) </FONT>
+<BR><FONT SIZE="-1">_endasm ; </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+In other words inline assembly code can access labels defined in inline
+assembly. The same goes the other way, ie. labels defines in inline
+assembly CANNOT be accessed by C statements.
+
+<P>
+
+<H2><A NAME="SECTION000412000000000000000">
+3.12 int(16 bit) and long (32 bit ) Support</A>
+</H2>
+
+<P>
+For signed & unsigned int (16 bit) and long (32 bit) variables, division,
+multiplication and modulus operations are implemented by support routines.
+These support routines are all developed in ANSI-C to facilitate porting
+to other MCUs. The following files contain the described routine,
+all of them can be found in the directory SDCCDIR/sdcc51lib
+
+<P>
+
+<UL>
+<LI><FONT SIZE="-1">_mulsint.c - signed 16 bit multiplication (calls _muluint)</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_muluint.c - unsigned 16 bit multiplication</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_divsint.c - signed 16 bit division (calls _divuint)</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_divuint.c - unsigned 16 bit division.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_modsint.c - signed 16 bit modulus (call _moduint)</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_moduint.c - unsigned 16 bit modulus.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_mulslong.c - signed 32 bit multiplication (calls
+_mululong)</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_mululong.c - unsigned32 bit multiplication.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_divslong.c - signed 32 division (calls _divulong)</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_divulong.c - unsigned 32 division.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_modslong.c - signed 32 bit modulus (calls _modulong).</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_modulong.c - unsigned 32 bit modulus.</FONT>
+<P>
+
+</LI>
+</UL>
+All these routines are compiled as non-reentrant and small model.
+Since they are compiled as non-reentrant, interrupt service routines
+should not do any of the above operations, if this unavoidable then
+the above routines will need to ne compiled with the -stack-auto
+option, after which the source program will have to be compiled with
+-int-long-rent option.
+
+<P>
+
+<H2><A NAME="SECTION000413000000000000000">
+3.13 Floating Point Support</A>
+</H2>
+
+<P>
+SDCC supports IEEE (single precision 4bytes) floating point numbers.The
+floating point support routines are derived from gcc's floatlib.c
+and consists of the following routines.
+
+<P>
+
+<UL>
+<LI><FONT SIZE="-1">_fsadd.c - add floating point numbers.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fssub.c - subtract floating point numbers</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fsdiv.c - divide floating point numbers</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fsmul.c - multiply floating point numbers</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2uchar.c - convert floating point to unsigned char</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2char.c - convert floating point to signed char.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2uint.c - convert floating point to unsigned int.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2int.c - convert floating point to signed int.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2ulong.c - convert floating point to unsigned long.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_fs2long.c - convert floating point to signed long.</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_uchar2fs.c - convert unsigned char to floating point</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_char2fs.c - convert char to floating point number</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_uint2fs.c - convert unsigned int to floating point</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_int2fs.c - convert int to floating point numbers</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_ulong2fs.c - convert unsigned long to floating point
+number</FONT>
+<P>
+
+</LI>
+<LI><FONT SIZE="-1">_long2fs.c - convert long to floating point number.</FONT>
+<P>
+
+</LI>
+</UL>
+Note if all these routines are used simultaneously the data space
+might overflow. For serious floating point usage it is strongly recommended
+that the Large model be used (in which case the floating point routines
+mentioned above will need to recompiled with the -model-Large option)
+
+<P>
+
+<H2><A NAME="SECTION000414000000000000000">
+3.14 MCS51 Memory Models</A>
+</H2>
+
+<P>
+SDCC allows two memory models for MCS51 code, small and large. Modules
+compiled with different memory models should never be combined together
+or the results would be unpredictable. The library routines supplied
+with the compiler are compiled as both small and large. The compiled
+library modules are contained in seperate directories as small and
+large so that you can link to either set. In general the use of the
+large model is discouraged.
+
+<P>
+When the large model is used all variables declared without a storage
+class will be allocated into the external ram, this includes all parameters
+and local variables (for non-reentrant functions). When the small
+model is used variables without storage class are allocated in the
+internal ram.
+
+<P>
+Judicious usage of the processor specific storage classes and the
+'reentrant' function type will yield much more efficient code, than
+using the large-model. Several optimizations are disabled when the
+program is compiled using the large model, it is therefore strongly
+recommdended that the small model be used unless absolutely required.
+
+<P>
+
+<H2><A NAME="SECTION000415000000000000000">
+3.15 Flat 24 bit Addressing Model</A>
+</H2>
+
+<P>
+This option generates code for the 24 bit contiguous addressing mode
+of the Dallas DS80C390 part. In this mode, up to four meg of external
+RAM or code space can be directly addressed. See the data sheets at
+www.dalsemi.com for further information on this part.
+
+<P>
+In older versions of the compiler, this option was used with the MCS51
+code generator (-mmcs51). Now, however, the '390 has it's own code
+generator, selected by the -mds390 switch. This code generator currently
+supports only the flat24 model, but the -model-flat24 switch is still
+required, in case later versions of the code generator support other
+models (such as the paged mode of the '390). The combination of -mmcs51
+and -model-flat24 is now depracated.
+
+<P>
+Note that the compiler does not generate any code to place the processor
+into24 bitmode (it defaults to 8051 compatible mode). Boot loader
+or similar code must ensure that the processor is in 24 bit contiguous
+addressing mode before calling the SDCC startup code.
+
+<P>
+Like the -model-large option, variables will by default be placed
+into the XDATA segment.
+
+<P>
+Segments may be placed anywhere in the 4 meg address space using the
+usual -*-loc options. Note that if any segments are located above
+64K, the -r flag must be passed to the linker to generate the proper
+segment relocations, and the Intel HEX output format must be used.
+The -r flag can be passed to the linker by using the option -Wl-r
+on the sdcc command line.
+
+<P>
+
+<H2><A NAME="SECTION000416000000000000000">
+3.16 Defines Created by the Compiler</A>
+</H2>
+
+<P>
+The compiler creates the following #defines .
+
+<P>
+
+<UL>
+<LI>SDCC - this Symbol is always defined.
+</LI>
+<LI>SDCC_STACK_AUTO - this symbol is defined when -stack-auto option
+is used.
+</LI>
+<LI>SDCC_MODEL_SMALL - when small model is used.
+</LI>
+<LI>SDCC_MODEL_LARGE - when -model-large is used.
+</LI>
+<LI>SDCC_USE_XSTACK - when -xstack option is used.
+</LI>
+</UL>
+
+<P>
+
+<H1><A NAME="SECTION00050000000000000000">
+4 SDCC Technical Data</A>
+</H1>
+
+<P>
+
+<H2><A NAME="SECTION00051000000000000000">
+4.1 Optimizations</A>
+</H2>
+
+<P>
+SDCC performs a a host of standard optimizations in addition to some
+MCU specific optimizations.
+
+<P>
+
+<H3><A NAME="SECTION00051100000000000000">
+4.1.1 Sub-expression Elimination</A>
+</H3>
+
+<P>
+The compiler does <I>local and global</I> common subexpression elimination.
+
+<P>
+<TT><FONT SIZE="-2">eg. </FONT></TT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">i = x + y + 1;</FONT>
+<BR>
+j <FONT SIZE="-1">= x + y;</FONT>
+<P>
+
+
+<P>
+will be translated to
+
+<P>
+<FONT SIZE="-1">iTemp = x + y </FONT>
+<BR><FONT SIZE="-1">i = iTemp + 1 </FONT>
+<BR><FONT SIZE="-1">j = iTemp</FONT>
+<P>
+
+
+<P>
+Some subexpressions are not as obvious as the above example.
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">a->b[i].c = 10; </FONT>
+<BR><FONT SIZE="-1">a->b[i].d = 11;</FONT>
+<P>
+
+
+<P>
+In this case the address arithmetic <I>a->b[i]</I> will be computed
+only once; the equivalent code in C would be.
+
+<P>
+<FONT SIZE="-1">iTemp = a->b[i]; </FONT>
+<BR><FONT SIZE="-1">iTemp.c = 10; </FONT>
+<BR><FONT SIZE="-1">iTemp.d = 11;</FONT>
+<P>
+
+
+<P>
+The compiler will try to keep these temporary variables in registers.
+
+<P>
+
+<H3><A NAME="SECTION00051200000000000000">
+4.1.2 Dead-Code Elimination</A>
+</H3>
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">int global; </FONT>
+<BR><FONT SIZE="-1">void f () { </FONT>
+<BR><FONT SIZE="-1"> int i; </FONT>
+<BR><FONT SIZE="-1"> i = 1; /* dead store */ </FONT>
+<BR><FONT SIZE="-1"> global = 1; /* dead store */ </FONT>
+<BR><FONT SIZE="-1"> global = 2; </FONT>
+<BR><FONT SIZE="-1"> return; </FONT>
+<BR><FONT SIZE="-1"> global = 3; /* unreachable */ </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+will be changed to
+
+<P>
+<FONT SIZE="-1">int global; void f () </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> global = 2; </FONT>
+<BR><FONT SIZE="-1"> return; </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+
+<H3><A NAME="SECTION00051300000000000000">
+4.1.3 Copy-Propagation</A>
+</H3>
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">int f() { </FONT>
+<BR><FONT SIZE="-1"> int i, j; </FONT>
+<BR><FONT SIZE="-1"> i = 10; </FONT>
+<BR><FONT SIZE="-1"> j = i; </FONT>
+<BR><FONT SIZE="-1"> return j; </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+will be changed to
+
+<P>
+<FONT SIZE="-1">int f() { </FONT>
+<BR><FONT SIZE="-1"> int i,j; </FONT>
+<BR><FONT SIZE="-1"> i = 10; </FONT>
+<BR><FONT SIZE="-1"> j = 10; </FONT>
+<BR><FONT SIZE="-1"> return 10; </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+Note: the dead stores created by this copy propagation will be eliminated
+by dead-code elimination .
+
+<P>
+
+<H3><A NAME="SECTION00051400000000000000">
+4.1.4 Loop Optimizations</A>
+</H3>
+
+<P>
+Two types of loop optimizations are done by SDCC loop invariant lifting
+and strength reduction of loop induction variables.In addition to
+the strength reduction the optimizer marks the induction variables
+and the register allocator tries to keep the induction variables in
+registers for the duration of the loop. Because of this preference
+of the register allocator , loop induction optimization causes an
+increase in register pressure, which may cause unwanted spilling of
+other temporary variables into the stack / data space . The compiler
+will generate a warning message when it is forced to allocate extra
+space either on the stack or data space. If this extra space allocation
+is undesirable then induction optimization can be eliminated either
+for the entire source file ( with -noinduction option) or for a given
+function only (#pragma NOINDUCTION).
+
+<P>
+
+<UL>
+<LI><B>Loop Invariant:</B>
+</LI>
+</UL>
+eg
+
+<P>
+<FONT SIZE="-1">for (i = 0 ; i < 100 ; i ++) </FONT>
+<BR><FONT SIZE="-1"> f += k + l;</FONT>
+<P>
+
+
+<P>
+changed to
+
+<P>
+<FONT SIZE="-1">itemp = k + l; </FONT>
+<BR><FONT SIZE="-1">for ( i = 0; i < 100; i++ ) f += itemp;</FONT>
+<P>
+
+
+<P>
+As mentioned previously some loop invariants are not as apparent,
+all static address computations are also moved out of the loop.
+
+<P>
+
+<UL>
+<LI><B>Strength Reduction :</B>
+</LI>
+</UL>
+This optimization substitutes an expression by a cheaper expression.
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">for (i=0;i < 100; i++) ar[i*5] = i*3;</FONT>
+<P>
+
+
+<P>
+changed to
+
+<P>
+<FONT SIZE="-1">itemp1 = 0; </FONT>
+<BR><FONT SIZE="-1">itemp2 = 0; </FONT>
+<BR><FONT SIZE="-1">for (i=0;i< 100;i++) { </FONT>
+<BR><FONT SIZE="-1"> ar[itemp1] = itemp2; </FONT>
+<BR><FONT SIZE="-1"> itemp1 += 5; </FONT>
+<BR><FONT SIZE="-1"> itemp2 += 3; </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+The more expensive multiplication is changed to a less expensive addition.
+
+<P>
+
+<H3><A NAME="SECTION00051500000000000000">
+4.1.5 Loop Reversing:</A>
+</H3>
+
+<P>
+This optimization is done to reduce the overhead of checking loop
+boundaries for every iteration. Some simple loops can be reversed
+and implemented using a ``decrement and jump if not zero'' instruction.
+SDCC checks for the following criterion to determine if a loop is
+reversible (note: more sophisticated compiers use data-dependency
+analysis to make this determination, SDCC uses a more simple minded
+analysis).
+
+<P>
+
+<UL>
+<LI>The 'for' loop is of the form
+<BR>``for ( <symbol> = <expression> ; <sym> [< | <=] <expression>
+; [<sym>++ | <sym> += 1])
+<BR> <for body>''
+</LI>
+<LI>The <for body> does not contain ``continue'' or 'break''.
+</LI>
+<LI>All goto's are contained within the loop.
+</LI>
+<LI>No function calls within the loop.
+</LI>
+<LI>The loop control variable <sym> is not assigned any value within the
+loop
+</LI>
+<LI>The loop control variable does NOT participate in any arithmetic operation
+within the loop.
+</LI>
+<LI>There are NO switch statements in the loop.
+</LI>
+</UL>
+Note djnz instruction can be used for 8-bit values ONLY, therefore
+it is advantageous to declare loop control symbols as either 'char'
+or 'short', ofcourse this may not be possible on all situations.
+
+<P>
+
+<H3><A NAME="SECTION00051600000000000000">
+4.1.6 Algebraic Simplifications</A>
+</H3>
+
+<P>
+SDCC does numerous algebraic simplifications, the following is a small
+sub-set of these optimizations.
+
+<P>
+<FONT SIZE="-1">eg</FONT> <I></I>
+<BR><FONT SIZE="-1">i = j + 0 ; /* changed to */ i = j; </FONT>
+<BR><FONT SIZE="-1">i /= 2; /* changed to */ i >>= 1; </FONT>
+<BR><FONT SIZE="-1">i = j - j ; /* changed to */ i = 0; </FONT>
+<BR><FONT SIZE="-1">i = j / 1 ; /* changed to */ i = j;</FONT>
+<P>
+
+
+<P>
+Note the subexpressions given above are generally introduced by macro
+expansions or as a result of copy/constant propagation.
+
+<P>
+
+<H3><A NAME="SECTION00051700000000000000">
+4.1.7 'switch' Statements</A>
+</H3>
+
+<P>
+SDCC changes switch statements to jump tables when the following conditions
+are true.
+
+<P>
+
+<UL>
+<LI>The case labels are in numerical sequence , the labels need not be
+in order, and the starting number need not be one or zero.
+</LI>
+</UL>
+eg
+
+<P>
+<FONT SIZE="-1">switch(i) { switch (i)
+{ </FONT>
+<BR><FONT SIZE="-1">case 4:... case 1: ...
+</FONT>
+<BR><FONT SIZE="-1">case 5:... case 2: ...
+</FONT>
+<BR><FONT SIZE="-1">case 3:... case 3: ...
+</FONT>
+<BR><FONT SIZE="-1">case 6:... case 4: ...
+</FONT>
+<BR><FONT SIZE="-1">} }</FONT>
+<P>
+
+
+<P>
+Both the above switch statements will be implemented using a jump-table.
+
+<P>
+
+<UL>
+<LI>The number of case labels is at least three, since it takes two conditional
+statements to handle the boundary conditions.
+</LI>
+<LI>The number of case labels is less than 84, since each label takes
+3 bytes and a jump-table can be utmost 256 bytes long.
+</LI>
+</UL>
+Switch statements which have gaps in the numeric sequence or those
+that have more that 84 case labels can be split into more than one
+switch statement for efficient code generation.
+
+<P>
+eg
+
+<P>
+<FONT SIZE="-1">switch (i) { </FONT>
+<BR><FONT SIZE="-1">case 1: ... </FONT>
+<BR><FONT SIZE="-1">case 2: ... </FONT>
+<BR><FONT SIZE="-1">case 3: ... </FONT>
+<BR><FONT SIZE="-1">case 4: ... </FONT>
+<BR><FONT SIZE="-1">case 9: ... </FONT>
+<BR><FONT SIZE="-1">case 10: ... </FONT>
+<BR><FONT SIZE="-1">case 11: ... </FONT>
+<BR><FONT SIZE="-1">case 12: ... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+If the above switch statement is broken down into two switch statements
+
+<P>
+<FONT SIZE="-1">switch (i) { </FONT>
+<BR><FONT SIZE="-1">case 1: ... </FONT>
+<BR><FONT SIZE="-1">case 2: ... </FONT>
+<BR><FONT SIZE="-1">case 3: ... </FONT>
+<BR><FONT SIZE="-1">case 4: ... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">switch (i) { </FONT>
+<BR><FONT SIZE="-1">case 9: ... </FONT>
+<BR><FONT SIZE="-1">case 10: ... </FONT>
+<BR><FONT SIZE="-1">case 11: ... </FONT>
+<BR><FONT SIZE="-1">case 12:... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+then both the switch statements will be implemented using jump-tables
+whereas the unmodified switch statement will not be .
+
+<P>
+
+<H3><A NAME="SECTION00051800000000000000">
+4.1.8 Bit-shifting Operations.</A>
+</H3>
+
+<P>
+Bit shifting is one of the most frequently used operation in embedded
+programming . SDCC tries to implement bit-shift operations in the
+most efficient way possible.
+
+<P>
+eg.
+
+<P>
+<FONT SIZE="-1">unsigned short i;</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">i>>= 4; </FONT>
+<BR><FONT SIZE="-1">..</FONT>
+<P>
+
+
+<P>
+generates the following code.
+
+<P>
+<FONT SIZE="-1">mov a,_i </FONT>
+<BR><FONT SIZE="-1">swap a </FONT>
+<BR><FONT SIZE="-1">anl a,#0x0f </FONT>
+<BR><FONT SIZE="-1">mov _i,a</FONT>
+<P>
+
+
+<P>
+In general SDCC will never setup a loop if the shift count is known.
+Another example
+
+<P>
+<FONT SIZE="-1">unsigned int i; </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">i >>= 9; </FONT>
+<BR><FONT SIZE="-1">...</FONT>
+<P>
+
+
+<P>
+will generate
+
+<P>
+<FONT SIZE="-1">mov a,(_i + 1) </FONT>
+<BR><FONT SIZE="-1">mov (_i + 1),#0x00 </FONT>
+<BR><FONT SIZE="-1">clr c </FONT>
+<BR><FONT SIZE="-1">rrc a </FONT>
+<BR><FONT SIZE="-1">mov _i,a</FONT>
+<P>
+
+
+<P>
+Note that SDCC stores numbers in <SMALL>LITTLE-ENDIAN</SMALL> format (i.e.
+lowest order first)
+
+<P>
+
+<H3><A NAME="SECTION00051900000000000000">
+4.1.9 Bit-rotation</A>
+</H3>
+
+<P>
+A special case of the bit-shift operation is bit rotation, SDCC recognizes
+the following expression to be a left bit-rotation.
+
+<P>
+<FONT SIZE="-1">unsigned char i; </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">i = ( ( i << 1) | ( i >>
+7)); </FONT>
+<BR><FONT SIZE="-1">...</FONT>
+<P>
+
+
+<P>
+will generate the following code.
+
+<P>
+<FONT SIZE="-1">mov a,_i </FONT>
+<BR><FONT SIZE="-1">rl a </FONT>
+<BR><FONT SIZE="-1">mov _i,a</FONT>
+<P>
+
+
+<P>
+SDCC uses pattern matching on the parse tree to determine this operation
+.Variations of this case will also be recognized as bit-rotation i.e
+<I>i = ((i >> 7) | (i <<
+1));</I> /* left-bit rotation */
+
+<P>
+
+<H3><A NAME="SECTION000511000000000000000">
+4.1.10 Highest Order Bit</A>
+</H3>
+
+<P>
+It is frequently required to obtain the highest order bit of an integral
+type (int,long,short or char types). SDCC recognizes the following
+expression to yield the highest order bit and generates optimized
+code for it.
+
+<P>
+<FONT SIZE="-1">eg </FONT>
+<BR><FONT SIZE="-1">unsigned int gint; </FONT>
+<BR><FONT SIZE="-1">foo () { </FONT>
+<BR><FONT SIZE="-1">unsigned char hob; </FONT>
+<BR><FONT SIZE="-1"> ... </FONT>
+<BR><FONT SIZE="-1"> hob = (gint >> 15) & 1; </FONT>
+<BR><FONT SIZE="-1"> .. </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+Will generate the following code.
+
+<P>
+<FONT SIZE="-1"> 61
+; hob.c 7 </FONT>
+<BR><FONT SIZE="-1"> 000A E5*01 62
+mov a,(_gint + 1) </FONT>
+<BR><FONT SIZE="-1"> 000C 33 63
+rlc a </FONT>
+<BR><FONT SIZE="-1"> 000D E4 64
+clr a </FONT>
+<BR><FONT SIZE="-1"> 000E 13 65
+rrc a </FONT>
+<BR><FONT SIZE="-1"> 000F F5*02 66
+mov _foo_hob_1_1,a</FONT>
+<P>
+
+
+<P>
+Variations of this case however will NOT be recognized . It is a standard
+C expression , so I heartily recommend this be the only way to get
+the highest order bit, (it is portable). Of course it will be recognized
+even if it is embedded in other expressions.
+
+<P>
+<FONT SIZE="-1">eg.</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">xyz = gint + ((gint >> 15) & 1);</FONT>
+<P>
+
+
+<P>
+will still be recognized.
+
+<P>
+
+<H3><A NAME="SECTION000511100000000000000">
+4.1.11 Peep-hole Optimizer</A>
+</H3>
+
+<P>
+The compiler uses a rule based , pattern matching and re-writing mechanism
+for peep-hole optimization . It is inspired by '<I>copt'</I> a peep-hole
+optimizer by Christopher W. Fraser (cwfraser@microsoft.com). A default
+set of rules are compiled into the compiler, additional rules may
+be added with the -peep-file <filename> option. The rule language
+is best illustrated with examples.
+
+<P>
+<FONT SIZE="-1">replace { </FONT>
+<BR><FONT SIZE="-1">mov %1,a </FONT>
+<BR><FONT SIZE="-1">mov a,%1 } by { mov %1,a }</FONT>
+<P>
+
+
+<P>
+The above rule will the following assembly sequence
+
+<P>
+<FONT SIZE="-1">mov r1,a </FONT>
+<BR><FONT SIZE="-1">mov a,r1</FONT>
+<P>
+
+
+<P>
+to
+
+<P>
+<FONT SIZE="-1">mov r1,a</FONT>
+<P>
+
+
+<P>
+Note: All occurrences of a '%n' ( pattern variable ) must denote
+the same string. With the above rule, the assembly sequence
+
+<P>
+<FONT SIZE="-1">mov r1,a </FONT>
+<BR><FONT SIZE="-1">mov a,r2</FONT>
+<P>
+
+
+<P>
+will remain unmodified. Other special case optimizations may be added
+by the user (via -peep-file option), eg. some variants of the 8051
+MCU allow only 'AJMP' and 'ACALL' , the following two rules will change
+all 'LJMP' & 'LCALL' to 'AJMP' & 'ACALL'.
+
+<P>
+<FONT SIZE="-1">replace { lcall %1 } by { acall %1 } </FONT>
+<BR><FONT SIZE="-1">replace { ljmp %1 } by { ajmp %1 }</FONT>
+<P>
+
+
+<P>
+The inline-assembler' code is also passed through the peep hole optimizer,
+thus the peephole optimizer can also be used as an assembly level
+macro expander. The rules themselves are MCU dependent whereas the
+rule language infra-structure is MCU independent. Peephole optimization
+rules for other MCU can be easily programmed using the rule language.
+
+<P>
+The syntax for a rule is as follows ,
+
+<P>
+<FONT SIZE="-1">rule := replace [ restart ] '{' <assembly sequence> '\n'
+</FONT>
+<BR><FONT SIZE="-1"> '}' by '{' '\n'
+</FONT>
+<BR><FONT SIZE="-1"> <assembly
+sequence> '\n' </FONT>
+<BR><FONT SIZE="-1"> '}' [if <functionName>
+] '\n' </FONT>
+<BR><FONT SIZE="-1"><assembly sequence> := assembly instruction (each instruction
+including labels must be on a separate line). </FONT>
+<P>
+
+
+<P>
+The optimizer will apply to the rules one by one from the top in the
+sequence of their appearance, it will terminate when all rules are
+exhausted. If the '<I>restart</I>' option is specified, then the optimizer
+will start matching the rules again from the top, this option for
+a rule is expensive (performance), it is intended to be used in situations
+where a transformation will trigger the same rule again. A good example
+of this the following rule.
+
+<P>
+<FONT SIZE="-1">replace restart { </FONT>
+<BR><FONT SIZE="-1">pop %1 </FONT>
+<BR><FONT SIZE="-1">push %1 } by { </FONT>
+<BR><FONT SIZE="-1">; nop </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+Note that the replace pattern cannot be a blank, but can be a comment
+line. Without the '<I>restart</I>' option only the inner most 'pop'
+'push' pair would be eliminated. i.e.
+
+<P>
+<FONT SIZE="-1">pop ar1 </FONT>
+<BR><FONT SIZE="-1">pop ar2 </FONT>
+<BR><FONT SIZE="-1">push ar2 </FONT>
+<BR><FONT SIZE="-1">push ar1</FONT>
+<P>
+
+
+<P>
+would result in
+
+<P>
+<FONT SIZE="-1">pop ar1 </FONT>
+<BR><FONT SIZE="-1">; nop </FONT>
+<BR><FONT SIZE="-1">push ar1</FONT>
+<P>
+
+
+<P>
+with the '<I>restart</I>' option the rule will be applied again to
+the resulting code and the all the '<I>pop' 'push'</I> pairs will
+be eliminated to yield
+
+<P>
+<FONT SIZE="-1">; nop </FONT>
+<BR><FONT SIZE="-1">; nop</FONT>
+<P>
+
+
+<P>
+A conditional function can be attached to a rule. Attaching rules
+are somewhat more involved, let me illustrate this with an example.
+
+<P>
+<FONT SIZE="-1">replace { </FONT>
+<BR><FONT SIZE="-1"> ljmp %5 </FONT>
+<BR><FONT SIZE="-1">%2:} by { </FONT>
+<BR><FONT SIZE="-1"> sjmp %5 </FONT>
+<BR><FONT SIZE="-1">%2:} if labelInRange</FONT>
+<P>
+
+
+<P>
+The optimizer does a look-up of a function name table defined in function
+'<I>callFuncByName'</I> in the source file <I>SDCCpeeph.c</I> , with
+the name <I>'labelInRange</I>', if it finds a corresponding entry
+the function is called. Note there can be no parameters specified
+for these functions, in this case the use of <I>'%5</I>' is crucial,
+since the function <I>labelInRange</I> expects to find the label in
+that particular variable (the hash table containing the variable bindings
+is passed as a parameter). If you want to code more such functions
+, take a close look at the function <I>labelInRange</I> and the calling
+mechanism in source file <I>SDCCpeeph.c</I>. I know this whole thing
+is a little kludgey , may be some day we will have some better means.
+If you are looking at this file, you will also see the default rules
+that are compiled into the compiler, you can your own rules in the
+default set there if you get tired of specifying the <I>-peep-file</I>
+option.
+
+<P>
+
+<H2><A NAME="SECTION00052000000000000000">
+4.2 Pragmas</A>
+</H2>
+
+<P>
+SDCC supports the following <I>#pragma</I> directives. This directives
+are applicable only at a function level.
+
+<P>
+
+<UL>
+<LI><B>SAVE</B> - this will save all the current options .
+</LI>
+<LI><B>RESTORE</B> - will restore the saved options from the last save.
+Note that SAVES & RESTOREs cannot be nested. SDCC uses the same buffer
+to save the options each time a SAVE is called.
+</LI>
+<LI><B>NOGCSE</B> - will stop global subexpression elimination.
+</LI>
+<LI><B>NOINDUCTION</B> - will stop loop induction optimizations .
+</LI>
+<LI><B>NOJTBOUND</B> - will not generate code for boundary value checking
+, when switch statements are turned into jump-tables.
+</LI>
+<LI><B>NOOVERLAY</B> - the compiler will not overlay the parameters
+and local variables of a function.
+</LI>
+<LI><B>NOLOOPREVERSE</B> - Will not do loop reversal optimization
+</LI>
+<LI><B>EXCLUDE NONE | {acc[,b[,dpl[,dph]]]</B> - The exclude
+pragma disables generation of pair of push/pop instruction in ISR
+function (using interrupt keyword). The directive should be placed
+immediately before the ISR function definition and it affects ALL
+ISR functions following it. To enable the normal register saving for
+ISR functions use ``#pragma EXCLUDE none''
+</LI>
+<LI><B>CALLEE-SAVES function1[,function2[,function3...]]</B>
+- The compiler by default uses a caller saves convention for register
+saving across function calls, however this can cause unneccessary
+register pushing & popping when calling small functions from larger
+functions. This option can be used to switch the register saving convention
+for the function names specified. The compiler will not save registers
+when calling these functions, extra code will be generated at the
+entry & exit for these functions to save & restore the registers
+used by these functions, this can SUBSTANTIALLY reduce code & improve
+run time performance of the generated code. In future the compiler
+(with interprocedural analysis) will be able to determine the appropriate
+scheme to use for each function call. If -callee-saves command line
+option is used, the function names specified in #pragma CALLEE-SAVES
+is appended to the list of functions specified inthe command line.
+</LI>
+</UL>
+The pragma's are intended to be used to turn-off certain optimizations
+which might cause the compiler to generate extra stack / data space
+to store compiler generated temporary variables. This usually happens
+in large functions. Pragma directives should be used as shown in the
+following example, they are used to control options & optimizations
+for a given function; pragmas should be placed <SMALL>BEFORE</SMALL> and/or
+<SMALL>AFTER</SMALL> a function, placing pragma's inside a function body
+could have unpredictable results.
+
+<P>
+<FONT SIZE="-2">eg</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-2">#pragma SAVE /* save the current settings */
+</FONT>
+<BR><FONT SIZE="-2">#pragma NOGCSE /* turnoff global subexpression elimination
+*/ </FONT>
+<BR><FONT SIZE="-2">#pragma NOINDUCTION /* turn off induction optimizations
+*/ </FONT>
+<BR><FONT SIZE="-2">int foo () </FONT>
+<BR><FONT SIZE="-2">{ </FONT>
+<BR><FONT SIZE="-2"> ... </FONT>
+<BR><FONT SIZE="-2"> /* large code */ </FONT>
+<BR><FONT SIZE="-2"> ... </FONT>
+<BR><FONT SIZE="-2">} </FONT>
+<BR><FONT SIZE="-2">#pragma RESTORE /* turn the optimizations back on
+*/</FONT>
+<P>
+
+
+<P>
+The compiler will generate a warning message when extra space is allocated.
+It is strongly recommended that the SAVE and RESTORE pragma's be used
+when changing options for a function.
+
+<P>
+
+<H2><A NAME="SECTION00053000000000000000">
+4.3 Library Routines</A>
+</H2>
+
+<P>
+The following library routines are provided for your convenience.
+
+<P>
+<B><FONT SIZE="+1">stdio.h</FONT></B> - Contains the following functions printf
+& sprintf these routines are developed by <I>Martijn van Balen
+<balen@natlab.research.philips.com>. </I>
+
+<P>
+<FONT SIZE="-2">%[flags][width][b|B|l|L]type</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-2"> flags: - left justify
+output in specified field width </FONT>
+<BR><FONT SIZE="-2"> + prefix
+output with +/- sign if output is signed type </FONT>
+<BR><FONT SIZE="-2"> space prefix output
+with a blank if it's a signed positive value </FONT>
+<BR><FONT SIZE="-2"> width: specifies
+minimum number of characters outputted for numbers </FONT>
+<BR><FONT SIZE="-2"> or
+strings. </FONT>
+<BR><FONT SIZE="-2"> -
+For numbers, spaces are added on the left when needed. </FONT>
+<BR><FONT SIZE="-2">
+If width starts with a zero character, zeroes and used </FONT>
+<BR><FONT SIZE="-2">
+instead of spaces. </FONT>
+<BR><FONT SIZE="-2"> -
+For strings, spaces are are added on the left or right (when </FONT>
+<BR><FONT SIZE="-2">
+flag '-' is used) when needed. </FONT>
+<BR><FONT SIZE="-2"> </FONT>
+<BR><FONT SIZE="-2"> b/B: byte argument
+(used by d, u, o, x, X) </FONT>
+<BR><FONT SIZE="-2"> l/L: long argument
+(used by d, u, o, x, X)</FONT>
+<BR><FONT SIZE="-2"> type: d decimal number
+</FONT>
+<BR><FONT SIZE="-2"> u unsigned
+decimal number </FONT>
+<BR><FONT SIZE="-2"> o unsigned
+octal number </FONT>
+<BR><FONT SIZE="-2"> x unsigned
+hexadecimal number (0-9, a-f) </FONT>
+<BR><FONT SIZE="-2"> X unsigned
+hexadecimal number (0-9, A-F) </FONT>
+<BR><FONT SIZE="-2"> c character
+</FONT>
+<BR><FONT SIZE="-2"> s string
+(generic pointer) </FONT>
+<BR><FONT SIZE="-2"> p generic
+pointer (I:data/idata, C:code, X:xdata, P:paged) </FONT>
+<BR><FONT SIZE="-2"> f float
+(still to be implemented)</FONT>
+<P>
+
+
+<P>
+Also contains a very simple version of printf (<B>printf_small</B>).
+This simplified version of printf supports only the following formats.
+
+<P>
+<U><FONT SIZE="-2">format output type argument-type</FONT></U>
+<BR><FONT SIZE="-2">%d decimal int </FONT>
+<BR><FONT SIZE="-2">%ld decimal long </FONT>
+<BR><FONT SIZE="-2">%hd decimal short/char </FONT>
+<BR><FONT SIZE="-2">%x hexadecimal int </FONT>
+<BR><FONT SIZE="-2">%lx hexadecimal long </FONT>
+<BR><FONT SIZE="-2">%hx hexadecimal short/char </FONT>
+<BR><FONT SIZE="-2">%o octal int </FONT>
+<BR><FONT SIZE="-2">%lo octal long </FONT>
+<BR><FONT SIZE="-2">%ho octal short/char
+</FONT>
+<BR><FONT SIZE="-2">%c character char/short </FONT>
+<BR><FONT SIZE="-2">%s character _generic pointer</FONT>
+<P>
+
+
+<P>
+The routine is <B>very stack intesive</B> , -stack-after-data parameter
+should be used when using this routine, the routine also takes about
+1K of code space .It also expects an external function named <I>putchar(char
+)</I> to be present (this can be changed). When using the %s format
+the string / pointer should be cast to a generic pointer. eg.
+
+<P>
+<FONT SIZE="-2">printf_small(``my str %s, my int %d\n'',(char
+_generic *)mystr,myint);</FONT>
+<P>
+
+
+<P>
+
+<UL>
+<LI><B><FONT SIZE="+1">stdarg.h</FONT></B> - contains definition for the following macros
+to be used for variable parameter list, note that a function can have
+a variable parameter list if and only if it is 'reentrant'
+
+<P>
+<FONT SIZE="-1">va_list, va_start, va_arg, va_end.</FONT>
+<P>
+
+
+<P>
+</LI>
+<LI><B><FONT SIZE="+1">setjmp.h</FONT></B> - contains defintion for ANSI <B>setjmp</B>
+& <B>longjmp</B> routines. Note in this case setjmp & longjmp
+can be used between functions executing within the same register bank,
+if long jmp is executed from a function that is using a different
+register bank from the function issuing the setjmp function, the results
+may be unpredictable. The jump buffer requires 3 bytes of data (the
+stack pointer & a 16 byte return address), and can be placed in any
+address space.
+</LI>
+<LI><B><FONT SIZE="+1">stdlib.h</FONT></B> - contains the following functions.
+
+<P>
+<FONT SIZE="-1">atoi, atol.</FONT>
+<P>
+
+
+<P>
+</LI>
+<LI><B><FONT SIZE="+1">string.h</FONT></B> - contains the following functions.
+
+<P>
+<FONT SIZE="-1">strcpy, strncpy, strcat, strncat, strcmp, strncmp,
+strchr, strrchr, strspn, strcspn, strpbrk, strstr, strlen, strtok,
+memcpy, memcmp, memset.</FONT>
+<P>
+
+
+<P>
+</LI>
+<LI><B><FONT SIZE="+1">ctype.h</FONT></B> - contains the following routines.
+
+<P>
+<FONT SIZE="-1">iscntrl, isdigit, isgraph, islower, isupper, isprint,
+ispunct, isspace, isxdigit, isalnum, isalpha.</FONT>
+<P>
+
+
+<P>
+</LI>
+<LI><B><FONT SIZE="+1">malloc.h</FONT></B> - The malloc routines are developed by Dmitry
+S. Obukhov (dso@usa.net). These routines will allocate memory from
+the external ram. Here is a description on how to use them (as described
+by the author).
+
+<P>
+<FONT SIZE="-2">//Example: </FONT>
+<BR><FONT SIZE="-2"> // #define DYNAMIC_MEMORY_SIZE 0x2000
+</FONT>
+<BR><FONT SIZE="-2"> // ..... </FONT>
+<BR><FONT SIZE="-2"> // unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
+</FONT>
+<BR><FONT SIZE="-2"> // unsigned char xdata * current_buffer;
+</FONT>
+<BR><FONT SIZE="-2"> // ..... </FONT>
+<BR><FONT SIZE="-2"> // void main(void) </FONT>
+<BR><FONT SIZE="-2"> // { </FONT>
+<BR><FONT SIZE="-2"> // ... </FONT>
+<BR><FONT SIZE="-2"> // init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
+</FONT>
+<BR><FONT SIZE="-2"> // //Now it's possible to use
+malloc. </FONT>
+<BR><FONT SIZE="-2"> // ... </FONT>
+<BR><FONT SIZE="-2"> // current_buffer = malloc(0x100);
+</FONT>
+<BR><FONT SIZE="-2"> //</FONT>
+<P>
+
+
+<P>
+</LI>
+<LI><B><FONT SIZE="+1">serial.h</FONT></B> - Serial IO routines are also developed by
+Dmitry S. Obukhov (dso@usa.net). These routines are interrupt driven
+with a 256 byte circular buffer, they also expect external ram to
+be present. Please see documentation in file SDCCDIR/sdcc51lib/serial.c
+. Note the header file ``serial.h'' MUST be included in the file
+containing the 'main' function.
+</LI>
+<LI><B><FONT SIZE="+1">ser.h</FONT></B> - Alternate serial routine provided by Wolfgang
+Esslinger <wolfgang@WiredMinds.com> these routines are more compact
+and faster. Please see documentation in file SDCCDIR/sdcc51lib/ser.c
+</LI>
+<LI><B><FONT SIZE="+1">ser_ir.h</FONT></B> - Another alternate set of serial routines
+provided by Josef Wolf <jw@raven.inka.de> , these routines do not
+use the external ram.
+</LI>
+<LI><B><FONT SIZE="+1">reg51.h</FONT></B> - contains register definitions for a standard
+8051
+</LI>
+<LI><B><FONT SIZE="+1">reg552.h</FONT></B> - contains register definitions for 80C552.
+</LI>
+<LI><B><FONT SIZE="+1">float.h</FONT></B> - contains min, max and other floating point
+related stuff.
+</LI>
+</UL>
+All library routines are compiled as -model-small , they are all
+non-reentrant, if you plan to use the large model or want to make
+these routines reentrant, then they will have to be recompiled with
+the appropriate compiler option.
+
+<P>
+Have not had time to do the more involved routines like printf, will
+get to them shortly.
+
+<P>
+
+<H2><A NAME="SECTION00054000000000000000">
+4.4 Interfacing with Assembly Routines</A>
+</H2>
+
+<P>
+
+<H2><A NAME="SECTION00055000000000000000">
+4.5 Global Registers used for Parameter Passing</A>
+</H2>
+
+<P>
+By default the compiler uses the global registers ``DPL,DPH,B,ACC''
+to pass the first parameter to a routine, the second parameter onwards
+is either allocated on the stack (for reentrant routines or -stack-auto
+is used) or in the internal / external ram (depending on the memory
+model).
+
+<P>
+
+<H3><A NAME="SECTION00055100000000000000">
+4.5.1 Assembler Routine(non-reentrant)</A>
+</H3>
+
+<P>
+In the following example the function <B>cfunc</B> calls an assembler
+routine <B>asm_func</B>, which takes two parameters.
+
+<P>
+<FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1"> </FONT>
+<BR><FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<BR><FONT SIZE="-2">int main() </FONT>
+<BR><FONT SIZE="-2">{ </FONT>
+<BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
+<BR><FONT SIZE="-2">}</FONT>
+<P>
+
+
+<P>
+The corresponding assembler function is:-
+
+<P>
+<FONT SIZE="-2"> .globl _asm_func_PARM_2 </FONT>
+<BR><FONT SIZE="-2"> .globl _asm_func </FONT>
+<BR><FONT SIZE="-2"> .area OSEG </FONT>
+<BR><FONT SIZE="-2">_asm_func_PARM_2: .ds 1 </FONT>
+<BR><FONT SIZE="-2"> .area CSEG </FONT>
+<BR><FONT SIZE="-2">_asm_func: </FONT>
+<BR><FONT SIZE="-2"> mov a,dpl </FONT>
+<BR><FONT SIZE="-2"> add a,_asm_func_PARM_2 </FONT>
+<BR><FONT SIZE="-2"> mov dpl,a </FONT>
+<BR><FONT SIZE="-2"> mov dpl,#0x00 </FONT>
+<BR><FONT SIZE="-2"> ret</FONT>
+<P>
+
+
+<P>
+Note here that the return values are placed in 'dpl' - One byte return
+value, 'dpl' LSB & 'dph' MSB for two byte values. 'dpl', 'dph' and
+'b' for three byte values (generic pointers) and 'dpl','dph','b' &
+'acc' for four byte values.
+
+<P>
+The parameter naming convention is <B>_<function_name>_PARM_<n>,</B>
+where n is the parameter number starting from 1, and counting from
+the left. The first parameter is passed in ``dpl'' for One bye
+parameter, ``dptr'' if two bytes, ``b,dptr'' for three bytes
+and ``acc,b,dptr'' for four bytes, the <TT><B><FONT SIZE="-1">varaible
+name for the second parameter will be _<function_name>_PARM_2.</FONT></B></TT>
+<P>
+
+
+<P>
+Assemble the assembler routine with the following command.
+
+<P>
+asx8051 -losg asmfunc.asm
+
+<P>
+Then compile and link the assembler routine to the C source file with
+the following command,
+
+<P>
+sdcc cfunc.c asmfunc.rel
+
+<P>
+
+<H3><A NAME="SECTION00055200000000000000">
+4.5.2 Assembler Routine(reentrant)</A>
+</H3>
+
+<P>
+In this case the second parameter onwards will be passed on the stack
+, the parameters are pushed from right to left i.e. after the call
+the left most parameter will be on the top of the stack. Here is an
+example.
+
+<P>
+<FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1"> </FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) reentrant
+</FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<BR><FONT SIZE="-2">int main() </FONT>
+<BR><FONT SIZE="-2">{ </FONT>
+<BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
+<BR><FONT SIZE="-2">}</FONT>
+<P>
+
+
+<P>
+The corresponding assembler routine is.
+
+<P>
+<FONT SIZE="-2"> .globl _asm_func </FONT>
+<BR><FONT SIZE="-2">_asm_func: </FONT>
+<BR><FONT SIZE="-2"> push _bp </FONT>
+<BR><FONT SIZE="-2"> mov _bp,sp </FONT>
+<BR><FONT SIZE="-2"> mov r2,dpl</FONT>
+<BR><FONT SIZE="-2"> mov a,_bp </FONT>
+<BR><FONT SIZE="-2"> clr c </FONT>
+<BR><FONT SIZE="-2"> add a,#0xfd </FONT>
+<BR><FONT SIZE="-2"> mov r0,a </FONT>
+<BR><FONT SIZE="-2"> add a,#0xfc</FONT>
+<BR><FONT SIZE="-2"> mov r1,a </FONT>
+<BR><FONT SIZE="-2"> mov a,@r0 </FONT>
+<BR><FONT SIZE="-2"> add a,r2</FONT>
+<BR><FONT SIZE="-2"> mov dpl,a </FONT>
+<BR><FONT SIZE="-2"> mov dph,#0x00 </FONT>
+<BR><FONT SIZE="-2"> mov sp,_bp </FONT>
+<BR><FONT SIZE="-2"> pop _bp </FONT>
+<BR><FONT SIZE="-2"> ret</FONT>
+<P>
+
+
+<P>
+The compiling and linking procedure remains the same, however note
+the extra entry & exit linkage required for the assembler code, _bp
+is the stack frame pointer and is used to compute the offset into
+the stack for parameters and local variables.
+
+<P>
+
+<H2><A NAME="SECTION00056000000000000000">
+4.6 With -noregparms Option</A>
+</H2>
+
+<P>
+When the source is compiled with -noregparms option , space is allocated
+for each of the parameters passed to a routine.
+
+<P>
+
+<H3><A NAME="SECTION00056100000000000000">
+4.6.1 Assembler Routine Non-reentrant</A>
+</H3>
+
+<P>
+In the following example the function <B>cfunc</B> calls an assembler
+routine <B>asm_func</B>, which takes two parameters.
+
+<P>
+<FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1"> </FONT>
+<BR><FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<BR><FONT SIZE="-2">int main() </FONT>
+<BR><FONT SIZE="-2">{ </FONT>
+<BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
+<BR><FONT SIZE="-2">}</FONT>
+<P>
+
+
+<P>
+The corresponding assembler function is:-
+
+<P>
+<FONT SIZE="-2"> .globl _asm_func_PARM_1 </FONT>
+<BR><FONT SIZE="-2"> .globl _asm_func_PARM_2 </FONT>
+<BR><FONT SIZE="-2"> .globl _asm_func </FONT>
+<BR><FONT SIZE="-2"> .area OSEG </FONT>
+<BR><FONT SIZE="-2">_asm_func_PARM_1: .ds 1 </FONT>
+<BR><FONT SIZE="-2">_asm_func_PARM_2: .ds 1 </FONT>
+<BR><FONT SIZE="-2"> .area CSEG </FONT>
+<BR><FONT SIZE="-2">_asm_func: </FONT>
+<BR><FONT SIZE="-2"> mov a,_asm_func_PARM_1 </FONT>
+<BR><FONT SIZE="-2"> add a,_asm_func_PARM_2 </FONT>
+<BR><FONT SIZE="-2"> mov dpl,a </FONT>
+<BR><FONT SIZE="-2"> mov dpl,#0x00 </FONT>
+<BR><FONT SIZE="-2"> ret</FONT>
+<P>
+
+
+<P>
+Note here that the return values are placed in 'dpl' - One byte return
+value, 'dpl' LSB & 'dph' MSB for two byte values. 'dpl', 'dph' and
+'b' for three byte values (generic pointers) and 'dpl','dph','b' &
+'acc' for four byte values.
+
+<P>
+The parameter naming convention is <B>_<function_name>_PARM_<n>,</B>
+where n is the parameter number starting from 1, and counting from
+the left. i.e. the <TT><B><FONT SIZE="-1">left-most parameter
+name will be _<function_name>_PARM_1.</FONT></B></TT>
+<P>
+
+
+<P>
+Assemble the assembler routine with the following command.
+
+<P>
+asx8051 -losg asmfunc.asm
+
+<P>
+Then compile and link the assembler routine to the C source file with
+the following command,
+
+<P>
+sdcc cfunc.c asmfunc.rel
+
+<P>
+
+<H3><A NAME="SECTION00056200000000000000">
+4.6.2 Assembler Routine(reentrant)</A>
+</H3>
+
+<P>
+In this case the parameters will be passed on the stack , the parameters
+are pushed from right to left i.e. after the call the left most parameter
+will be on the top of the stack. Here is an example.
+
+<P>
+<FONT SIZE="-1">extern int asm_func( unsigned short, unsigned short);</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1"> </FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">int c_func (unsigned short i, unsigned short j) reentrant
+</FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1"> return asm_func(i,j); </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<BR><FONT SIZE="-2">int main() </FONT>
+<BR><FONT SIZE="-2">{ </FONT>
+<BR><FONT SIZE="-2"> return c_func(10,9); </FONT>
+<BR><FONT SIZE="-2">}</FONT>
+<P>
+
+
+<P>
+The corresponding assembler routine is.
+
+<P>
+<FONT SIZE="-2"> .globl _asm_func </FONT>
+<BR><FONT SIZE="-2">_asm_func: </FONT>
+<BR><FONT SIZE="-2"> push _bp </FONT>
+<BR><FONT SIZE="-2"> mov _bp,sp </FONT>
+<BR><FONT SIZE="-2"> mov a,_bp </FONT>
+<BR><FONT SIZE="-2"> clr c </FONT>
+<BR><FONT SIZE="-2"> add a,#0xfd </FONT>
+<BR><FONT SIZE="-2"> mov r0,a </FONT>
+<BR><FONT SIZE="-2"> mov a,_bp </FONT>
+<BR><FONT SIZE="-2"> clr c </FONT>
+<BR><FONT SIZE="-2"> add a,#0xfc </FONT>
+<BR><FONT SIZE="-2"> mov r1,a </FONT>
+<BR><FONT SIZE="-2"> mov a,@r0 </FONT>
+<BR><FONT SIZE="-2"> add a,@r1 </FONT>
+<BR><FONT SIZE="-2"> mov dpl,a </FONT>
+<BR><FONT SIZE="-2"> mov dph,#0x00 </FONT>
+<BR><FONT SIZE="-2"> mov sp,_bp </FONT>
+<BR><FONT SIZE="-2"> pop _bp </FONT>
+<BR><FONT SIZE="-2"> ret</FONT>
+<P>
+
+
+<P>
+The compiling and linking procedure remains the same, however note
+the extra entry & exit linkage required for the assembler code, _bp
+is the stack frame pointer and is used to compute the offset into
+the stack for parameters and local variables.
+
+<P>
+
+<H2><A NAME="SECTION00057000000000000000">
+4.7 External Stack</A>
+</H2>
+
+<P>
+The external stack is located at the start of the external ram segment
+, and is 256 bytes in size. When -xstack option is used to compile
+the program, the parameters and local variables of all reentrant functions
+are allocated in this area. This option is provided for programs with
+large stack space requirements. When used with the -stack-auto option,
+all parameters and local variables are allocated on the external stack
+(note support libraries will need to be recompiled with the same options).
+
+<P>
+The compiler outputs the higher order address byte of the external
+ram segment into PORT P2, therefore when using the External Stack
+option, this port MAY NOT be used by the application program.
+
+<P>
+
+<H2><A NAME="SECTION00058000000000000000">
+4.8 ANSI-Compliance</A>
+</H2>
+
+<P>
+Deviations from the compliancy.
+
+<P>
+
+<OL>
+<LI>functions are not always reentrant.
+</LI>
+<LI>structures cannot be assigned values directly, cannot be passed as
+function parameters or assigned to each other and cannot be a return
+value from a function.
+
+<P>
+<FONT SIZE="-1">eg</FONT>
+<P>
+
+
+<P>
+</LI>
+</OL>
+<FONT SIZE="-1">struct s { ... }; </FONT>
+<BR><FONT SIZE="-1">struct s s1, s2; </FONT>
+<BR><FONT SIZE="-1">foo() </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">s1 = s2 ; /* is invalid in SDCC although allowed in ANSI
+*/ </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+<FONT SIZE="-1">struct s foo1 (struct s parms) /* is invalid in SDCC although
+allowed in ANSI */ </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1">struct s rets; </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">return rets;/* is invalid in SDCC although allowed in ANSI
+*/ </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+
+<OL>
+<LI>'long long' (64 bit integers) not supported.
+</LI>
+<LI>'double' precision floating point not supported.
+</LI>
+<LI>integral promotions are suppressed. What does this mean ? The compiler
+will not implicitly promote an integer expression to a higher order
+integer, exception is an assignment or parameter passing.
+</LI>
+<LI>No support for <I>setjmp</I> and <I>longjmp</I> (for now).
+</LI>
+<LI>Old K&R style function declarations are NOT allowed.
+</LI>
+</OL>
+<FONT SIZE="-1">foo( i,j) /* this old style of function declarations
+*/ </FONT>
+<BR><FONT SIZE="-1">int i,j; /* are valid in ANSI .. not valid in SDCC
+*/ </FONT>
+<BR><FONT SIZE="-1">{ </FONT>
+<BR><FONT SIZE="-1">... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+
+<OL>
+<LI>functions declared as pointers must be dereferenced during the call.
+
+<P>
+<FONT SIZE="-1">int (*foo)();</FONT>
+<P>
+
+
+<P>
+</LI>
+</OL>
+<FONT SIZE="-1"> ... </FONT>
+<BR><FONT SIZE="-1"> /* has to be called like this */ </FONT>
+<BR><FONT SIZE="-1"> (*foo)();/* ansi standard allows calls to be made
+like 'foo()' */</FONT>
+<P>
+
+
+<P>
+
+<H2><A NAME="SECTION00059000000000000000">
+4.9 Cyclomatic Complexity</A>
+</H2>
+
+<P>
+Cyclomatic complexity of a function is defined as the number of independent
+paths the program can take during execution of the function. This
+is an important number since it defines the number test cases you
+have to generate to validate the function . The accepted industry
+standard for complexity number is 10, if the cyclomatic complexity
+reported by SDCC exceeds 10 you should think about simplification
+of the function logic.
+
+<P>
+Note that the complexity level is not related to the number of lines
+of code in a function. Large functions can have low complexity, and
+small functions can have large complexity levels. SDCC uses the following
+formula to compute the complexity.
+
+<P>
+<FONT SIZE="-1">complexity = (number of edges in control flow graph) - </FONT>
+<BR><FONT SIZE="-1"> (number of nodes in control flow graph)
++ 2;</FONT>
+<P>
+
+
+<P>
+Having said that the industry standard is 10, you should be aware
+that in some cases it may unavoidable to have a complexity level of
+less than 10. For example if you have switch statement with more than
+10 case labels, each case label adds one to the complexity level.
+The complexity level is by no means an absolute measure of the algorithmic
+complexity of the function, it does however provide a good starting
+point for which functions you might look at for further optimization.
+
+<P>
+
+<H1><A NAME="SECTION00060000000000000000">
+5 TIPS</A>
+</H1>
+
+<P>
+Here are a few guide-lines that will help the compiler generate more
+efficient code, some of the tips are specific to this compiler others
+are generally good programming practice.
+
+<P>
+
+<UL>
+<LI>Use the smallest data type to represent your data-value. If it is
+known in advance that the value is going to be less than 256 then
+use a 'short' or 'char' instead of an 'int'.
+</LI>
+<LI>Use unsigned when it is known in advance that the value is not going
+to be negative. This helps especially if you are doing division or
+multiplication.
+</LI>
+<LI>NEVER jump into a LOOP.
+</LI>
+<LI>Declare the variables to be local whenever possible, especially loop
+control variables (induction).
+</LI>
+<LI>Since the compiler does not do implicit integral promotion, the programmer
+should do an explicit cast when integral promotion is required.
+</LI>
+<LI>Reducing the size of division , multiplication & modulus operations
+can reduce code size substantially. Take the following code for example.
+
+<P>
+<FONT SIZE="-1">foobar( unsigned int p1, unsigned char ch)</FONT>
+<BR><FONT SIZE="-1">{</FONT>
+<BR><FONT SIZE="-1"> unsigned char ch1 = p1 % ch ;</FONT>
+<BR><FONT SIZE="-1"> .... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+For the modulus operation the variable ch will be promoted to unsigned
+int first then the modulus operation will be performed (this will
+lead to a call to a support routine). If the code is changed to
+
+<P>
+<FONT SIZE="-1">foobar( unsigned int p1, unsigned char ch)</FONT>
+<BR><FONT SIZE="-1">{</FONT>
+<BR><FONT SIZE="-1"> unsigned char ch1 = (unsigned char)p1 % ch
+;</FONT>
+<BR><FONT SIZE="-1"> .... </FONT>
+<BR><FONT SIZE="-1">}</FONT>
+<P>
+
+
+<P>
+It would substantially reduce the code generated (future versions
+of the compiler will be smart enough to detect such optimization oppurtunities).
+
+<P>
+</LI>
+</UL>
+<B>Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)</B>
+
+<P>
+The 8051 family of micro controller have a minimum of 128 bytes of
+internal memory which is structured as follows
+
+<P>
+- Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7
+to R7
+
+<P>
+- Bytes 20-2F - 16 bytes to hold 128 bit variables and
+
+<P>
+- Bytes 30-7F - 60 bytes for general purpose use.
+
+<P>
+Normally the SDCC compiler will only utilise the first bank of registers,
+but it is possible to specify that other banks of registers should
+be used in interrupt routines. By default, the compiler will place
+the stack after the last bank of used registers, i.e. if the first
+2 banks of registers are used, it will position the base of the internal
+stack at address 16 (0X10). This implies that as the stack grows,
+it will use up the remaining register banks, and the 16 bytes used
+by the 128 bit variables, and 60 bytes for general purpose use.
+
+<P>
+By default, the compiler uses the 60 general purpose bytes to hold
+"near data". The compiler/optimiser may also declare
+some Local Variables in this area to hold local data.
+
+<P>
+If any of the 128 bit variables are used, or near data is being used
+then care needs to be taken to ensure that the stack does not grow
+so much that it starts to over write either your bit variables or
+"near data". There is no runtime checking to prevent
+this from happening.
+
+<P>
+The amount of stack being used is affected by the use of the "internal
+stack" to save registers before a subroutine call is made,
+- -stack-auto will declare parameters and local variables on the
+stack - the number of nested subroutines.
+
+<P>
+If you detect that the stack is over writing you data, then the following
+can be done. -xstack will cause an external stack to be used for
+saving registers and (if -stack-auto is being used) storing parameters
+and local variables. However this will produce more and code which
+will be slower to execute.
+
+<P>
+-stack-loc will allow you specify the start of the stack, i.e. you
+could start it after any data in the general purpose area. However
+this may waste the memory not used by the register banks and if the
+size of the "near data" increases, it may creep
+into the bottom of the stack.
+
+<P>
+-stack-after-data, similar to the -stack-loc, but it automatically
+places the stack after the end of the "near data".
+Again this could waste any spare register space.
+
+<P>
+-data-loc allows you to specify the start address of the near data.
+This could be used to move the "near data" further
+away from the stack giving it more room to grow. This will only work
+if no bit variables are being used and the stack can grow to use the
+bit variable space.
+
+<P>
+Conclusion.
+
+<P>
+If you find that the stack is over writing your bit variables or "near
+data" then the approach which best utilised the internal
+memory is to position the "near data" after the
+last bank of used registers or, if you use bit variables, after the
+last bit variable by using the -data-loc, e.g. if two register banks
+are being used and no data variables, -data-loc 16, and - use the
+-stack-after-data option.
+
+<P>
+If bit variables are being used, another method would be to try and
+squeeze the data area in the unused register banks if it will fit,
+and start the stack after the last bit variable.
+
+<P>
+
+<H1><A NAME="SECTION00070000000000000000">
+6 Retargetting for other MCUs.</A>
+</H1>
+
+<P>
+The issues for retargetting the compiler are far too numerous to be
+covered by this document. What follows is a brief description of each
+of the seven phases of the compiler and its MCU dependency.
+
+<P>
+
+<OL>
+<LI>Parsing the source and building the annotated parse tree. This phase
+is largely MCU independent (except for the language extensions). Syntax
+& semantic checks are also done in this phase , along with some initial
+optimizations like back patching labels and the pattern matching optimizations
+like bit-rotation etc.
+</LI>
+<LI>The second phase involves generating an intermediate code which can
+be easy manipulated during the later phases. This phase is entirely
+MCU independent. The intermediate code generation assumes the target
+machine has unlimited number of registers, and designates them with
+the name iTemp. The compiler can be made to dump a human readable
+form of the code generated by using the -dumpraw option.
+</LI>
+<LI>This phase does the bulk of the standard optimizations and is also
+MCU independent. This phase can be broken down into several sub-phases.
+
+<P>
+
+<UL>
+<LI>Break down intermediate code (iCode) into basic blocks.
+</LI>
+<LI>Do control flow & data flow analysis on the basic blocks.
+</LI>
+<LI>Do local common subexpression elimination, then global subexpression
+elimination
+</LI>
+<LI>dead code elimination
+</LI>
+<LI>loop optimizations
+</LI>
+<LI>if loop optimizations caused any changes then do 'global subexpression
+elimination' and 'dead code elimination' again.
+</LI>
+</UL>
+</LI>
+<LI>This phase determines the live-ranges; by live range I mean those
+iTemp variables defined by the compiler that still survive after all
+the optimizations. Live range analysis is essential for register allocation,
+since these computation determines which of these iTemps will be assigned
+to registers, and for how long.
+</LI>
+<LI>Phase five is register allocation. There are two parts to this process
+.
+
+<P>
+
+<OL>
+<LI>The first part I call 'register packing' (for lack of a better term)
+. In this case several MCU specific expression folding is done to
+reduce register pressure.
+</LI>
+<LI>The second part is more MCU independent and deals with allocating
+registers to the remaining live ranges. A lot of MCU specific code
+does creep into this phase because of the limited number of index
+registers available in the 8051.
+</LI>
+</OL>
+</LI>
+<LI>The Code generation phase is (unhappily), entirely MCU dependent and
+very little (if any at all) of this code can be reused for other MCU.
+However the scheme for allocating a homogenized assembler operand
+for each iCode operand may be reused.
+</LI>
+<LI>As mentioned in the optimization section the peep-hole optimizer is
+rule based system, which can reprogrammed for other MCUs.
+</LI>
+</OL>
+
+<P>
+
+<H1><A NAME="SECTION00080000000000000000">
+7 SDCDB - Source Level Debugger</A>
+</H1>
+
+<P>
+SDCC is distributed with a source level debugger. The debugger uses
+a command line interface, the command repertoire of the debugger has
+been kept as close to gdb ( the GNU debugger) as possible. The configuration
+and build process is part of the standard compiler installation, which
+also builds and installs the debugger in the target directory specified
+during configuration. The debugger allows you debug BOTH at the C
+source and at the ASM source level.
+
+<P>
+
+<H2><A NAME="SECTION00081000000000000000">
+7.1 Compiling for Debugging</A>
+</H2>
+
+<P>
+The <I>-debug</I> option must be specified for all files for which
+debug information is to be generated. The complier generates a <I>.cdb</I>
+file for each of these files. The linker updates the <I>.cdb</I> file
+with the address information. This .cdb is used by the debugger .
+
+<P>
+
+<H2><A NAME="SECTION00082000000000000000">
+7.2 How the Debugger Works</A>
+</H2>
+
+<P>
+When the <I>-debug</I> option is specified the compiler generates
+extra symbol information some of which are put into the the assembler
+source and some are put into the .cdb file, the linker updates the
+.cdb file with the address information for the symbols. The debugger
+reads the symbolic information generated by the compiler & the address
+information generated by the linker. It uses the SIMULATOR (Daniel's
+S51) to execute the program, the program execution is controlled by
+the debugger. When a command is issued for the debugger, it translates
+it into appropriate commands for the simulator .
+
+<P>
+
+<H2><A NAME="SECTION00083000000000000000">
+7.3 Starting the Debugger</A>
+</H2>
+
+<P>
+The debugger can be started using the following command line. (Assume
+the file you are debugging has
+
+<P>
+the file name foo).
+
+<P>
+>sdcdb foo
+
+<P>
+The debugger will look for the following files.
+
+<P>
+
+<OL>
+<LI>foo.c - the source file.
+</LI>
+<LI>foo.cdb - the debugger symbol information file.
+</LI>
+<LI>foo.ihx - the intel hex format object file.
+</LI>
+</OL>
+
+<P>
+
+<H2><A NAME="SECTION00084000000000000000">
+7.4 Command Line Options.</A>
+</H2>
+
+<P>
+
+<UL>
+<LI>-directory=<source file directory> this option can used to specify
+the directory search list. The debugger will look into the directory
+list specified for source , cdb & ihx files. The items in the directory
+list must be separated by ':' , e.g. if the source files can be in
+the directories /home/src1 and /home/src2, the -directory option
+should be -directory=/home/src1:/home/src2 . Note there can be no
+spaces in the option.
+</LI>
+<LI>-cd <directory> - change to the <directory>.
+</LI>
+<LI>-fullname - used by GUI front ends.
+</LI>
+<LI>-cpu <cpu-type> - this argument is passed to the simulator please
+see the simulator docs for details.
+</LI>
+<LI>-X <Clock frequency > this options is passed to the simulator please
+see simulator docs for details.
+</LI>
+<LI>-s <serial port file> passed to simulator see simulator docs for details.
+</LI>
+<LI>-S <serial in,out> passed to simulator see simulator docs for details.
+</LI>
+</UL>
+
+<P>
+
+<H2><A NAME="SECTION00085000000000000000">
+7.5 Debugger Commands.</A>
+</H2>
+
+<P>
+As mention earlier the command interface for the debugger has been
+deliberately kept as close the GNU debugger gdb , as possible, this
+will help int integration with existing graphical user interfaces
+(like ddd, xxgdb or xemacs) existing for the GNU debugger.
+
+<P>
+
+<H3><A NAME="SECTION00085100000000000000">
+7.5.1 break [line | file:line | function | file:function]</A>
+</H3>
+
+<P>
+Set breakpoint at specified line or function.
+
+<P>
+sdcdb>break 100
+<BR>
+sdcdb>break foo.c:100
+<BR>
+sdcdb>break funcfoo
+<BR>
+sdcdb>break foo.c:funcfoo
+
+<P>
+
+<H3><A NAME="SECTION00085200000000000000">
+7.5.2 clear [line | file:line | function | file:function ]</A>
+</H3>
+
+<P>
+Clear breakpoint at specified line or function.
+
+<P>
+sdcdb>clear 100
+<BR>
+sdcdb>clear foo.c:100
+<BR>
+sdcdb>clear funcfoo
+<BR>
+sdcdb>clear foo.c:funcfoo
+
+<P>
+
+<H3><A NAME="SECTION00085300000000000000">
+7.5.3 continue</A>
+</H3>
+
+<P>
+Continue program being debugged, after breakpoint.
+
+<P>
+
+<H3><A NAME="SECTION00085400000000000000">
+7.5.4 finish</A>
+</H3>
+
+<P>
+Execute till the end of the current function.
+
+<P>
+
+<H3><A NAME="SECTION00085500000000000000">
+7.5.5 delete [n]</A>
+</H3>
+
+<P>
+Delete breakpoint number 'n'. If used without any option clear ALL
+user defined break points.
+
+<P>
+
+<H3><A NAME="SECTION00085600000000000000">
+7.5.6 info [break | stack | frame | registers ]</A>
+</H3>
+
+<P>
+
+<UL>
+<LI>info break - list all breakpoints
+</LI>
+<LI>info stack - show the function call stack.
+</LI>
+<LI>info frame - show information about the current execution frame.
+</LI>
+<LI>info registers - show content of all registers.
+</LI>
+</UL>
+
+<P>
+
+<H3><A NAME="SECTION00085700000000000000">
+7.5.7 step</A>
+</H3>
+
+<P>
+Step program until it reaches a different source line.
+
+<P>
+
+<H3><A NAME="SECTION00085800000000000000">
+7.5.8 next</A>
+</H3>
+
+<P>
+Step program, proceeding through subroutine calls.
+
+<P>
+
+<H3><A NAME="SECTION00085900000000000000">
+7.5.9 run</A>
+</H3>
+
+<P>
+Start debugged program.
+
+<P>
+
+<H3><A NAME="SECTION000851000000000000000">
+7.5.10 ptype variable </A>
+</H3>
+
+<P>
+Print type information of the variable.
+
+<P>
+
+<H3><A NAME="SECTION000851100000000000000">
+7.5.11 print variable</A>
+</H3>
+
+<P>
+print value of variable.
+
+<P>
+
+<H3><A NAME="SECTION000851200000000000000">
+7.5.12 file filename</A>
+</H3>
+
+<P>
+load the given file name. Note this is an alternate method of loading
+file for debugging.
+
+<P>
+
+<H3><A NAME="SECTION000851300000000000000">
+7.5.13 frame</A>
+</H3>
+
+<P>
+print information about current frame.
+
+<P>
+
+<H3><A NAME="SECTION000851400000000000000">
+7.5.14 set srcmode</A>
+</H3>
+
+<P>
+Toggle between C source & assembly source.
+
+<P>
+
+<H3><A NAME="SECTION000851500000000000000">
+7.5.15 ! simulator command</A>
+</H3>
+
+<P>
+Send the string following '!' to the simulator, the simulator response
+is displayed. Note the debugger does not interpret the command being
+sent to the simulator, so if a command like 'go' is sent the debugger
+can loose its execution context and may display incorrect values.
+
+<P>
+
+<H3><A NAME="SECTION000851600000000000000">
+7.5.16 quit.</A>
+</H3>
+
+<P>
+"Watch me now. Iam going Down. My name is Bobby Brown"
+
+<P>
+
+<H2><A NAME="SECTION00086000000000000000">
+7.6 Interfacing with XEmacs.</A>
+</H2>
+
+<P>
+Two files are (in emacs lisp) are provided for the interfacing with
+XEmacs, <I>sdcdb.el</I> and <I>sdcdbsrc.el</I>. These two files can
+be found in the $(prefix)/bin directory after the installation is
+complete. These files need to be loaded into XEmacs for the interface
+to work, this can be done at XEmacs startup time by inserting the
+following into your <I>'.xemacs'</I> file (which can be found in your
+HOME directory) <I>(load-file sdcdbsrc.el)</I> [ .xemacs is a lisp
+file so the () around the command is REQUIRED), the files can also
+be loaded dynamically while XEmacs is running, set the environment
+variable <I>'EMACSLOADPATH'</I> to the installation bin directory
+[$(prefix)/bin], then enter the following command <I>ESC-x
+load-file sdcdbsrc .</I> To start the interface enter the following command
+<I>ESC-x sdcdbsrc</I> , you will prompted to enter the file name to
+be debugged.
+
+<P>
+The command line options that are passed to the simulator directly
+are bound to default values in the file <I>sdcdbsrc.el</I> the variables
+are listed below these values maybe changed as required.
+
+<P>
+
+<UL>
+<LI>sdcdbsrc-cpu-type '51
+</LI>
+<LI>sdcdbsrc-frequency '11059200
+</LI>
+<LI>sdcdbsrc-serial nil
+</LI>
+</UL>
+The following is a list of key mapping for the debugger interface.
+
+<P>
+
+<BR><FONT SIZE="-2">;; Current Listing :: </FONT>
+<BR><FONT SIZE="-2">;;key binding Comment
+</FONT>
+<BR><FONT SIZE="-2">;;-- ---- ----
+</FONT>
+<BR><FONT SIZE="-2">;; </FONT>
+<BR><FONT SIZE="-2">;; n sdcdb-next-from-src SDCDB
+next command </FONT>
+<BR><FONT SIZE="-2">;; b sdcdb-back-from-src SDCDB
+back command </FONT>
+<BR><FONT SIZE="-2">;; c sdcdb-cont-from-src SDCDB
+continue command</FONT>
+<BR><FONT SIZE="-2">;; s sdcdb-step-from-src SDCDB
+step command </FONT>
+<BR><FONT SIZE="-2">;; ? sdcdb-whatis-c-sexp SDCDB
+ptypecommand for data at </FONT>
+<BR><FONT SIZE="-2">;;
+buffer point </FONT>
+<BR><FONT SIZE="-2">;; x sdcdbsrc-delete SDCDB
+Delete all breakpoints if no arg </FONT>
+<BR><FONT SIZE="-2">;; given
+or delete arg (C-u arg x) </FONT>
+<BR><FONT SIZE="-2">;; m sdcdbsrc-frame SDCDB
+Display current frame if no arg, </FONT>
+<BR><FONT SIZE="-2">;; given
+or display frame arg </FONT>
+<BR><FONT SIZE="-2">;; buffer
+point </FONT>
+<BR><FONT SIZE="-2">;; ! sdcdbsrc-goto-sdcdb Goto
+the SDCDB output buffer </FONT>
+<BR><FONT SIZE="-2">;; p sdcdb-print-c-sexp SDCDB
+print command for data at </FONT>
+<BR><FONT SIZE="-2">;;
+buffer point </FONT>
+<BR><FONT SIZE="-2">;; g sdcdbsrc-goto-sdcdb Goto
+the SDCDB output buffer </FONT>
+<BR><FONT SIZE="-2">;; t sdcdbsrc-mode Toggles
+Sdcdbsrc mode (turns it off) </FONT>
+<BR><FONT SIZE="-2">;; </FONT>
+<BR><FONT SIZE="-2">;; C-c C-f sdcdb-finish-from-src SDCDB
+finish command </FONT>
+<BR><FONT SIZE="-2">;; </FONT>
+<BR><FONT SIZE="-2">;; C-x SPC sdcdb-break Set
+break for line with point </FONT>
+<BR><FONT SIZE="-2">;; ESC t sdcdbsrc-mode Toggle
+Sdcdbsrc mode </FONT>
+<BR><FONT SIZE="-2">;; ESC m sdcdbsrc-srcmode
+Toggle list mode </FONT>
+<BR><FONT SIZE="-2">;; </FONT>
+<BR>
+<P>
+
+
+<P>
+
+<H1><A NAME="SECTION00090000000000000000">
+8 Other Processors</A>
+</H1>
+
+<P>
+
+<H2><A NAME="SECTION00091000000000000000">
+8.1 The Z80 and gbz80 port</A>
+</H2>
+
+<P>
+SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like
+gbz80. The port is incomplete - long support is incomplete (mul, div
+and mod are unimplimented), and both float and bitfield support is
+missing, but apart from that the code generated is correct.
+
+<P>
+As always, the code is the authoritave reference - see z80/ralloc.c
+and z80/gen.c. The stack frame is similar to that generated by the
+IAR Z80 compiler. IX is used as the base pointer, HL is used as a
+temporary register, and BC and DE are available for holding varibles.
+IY is currently unusued. Return values are stored in HL. One bad side
+effect of using IX as the base pointer is that a functions stack frame
+is limited to 127 bytes - this will be fixed in a later version.
+
+<P>
+
+<H1><A NAME="SECTION000100000000000000000">
+9 Support</A>
+</H1>
+
+<P>
+SDCC has grown to be large project, the compiler alone (without the
+Assembler Package, Preprocessor) is about 40,000 lines of code (blank
+stripped). The open source nature of this project is a key to its
+continued growth and support. You gain the benefit and support of
+many active software developers and end users. Is SDCC perfect? No,
+that's why we need your help. The developers take pride in fixing
+reported bugs. You can help by reporting the bugs and helping other
+SDCC users. There are lots of ways to contribute, and we encourage
+you to take part in making SDCC a great software package.
+
+<P>
+
+<H2><A NAME="SECTION000101000000000000000">
+9.1 Reporting Bugs</A>
+</H2>
+
+<P>
+Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net'
+or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed ASAP. When
+reporting a bug, it is very useful to include a small test program
+which reproduces the problem. If you can isolate the problem by looking
+at the generated assembly code, this can be very helpful. Compiling
+your program with the -dumpall option can sometimes be useful in
+locating optimization problems.
+
+<P>
+
+<H2><A NAME="SECTION000102000000000000000">
+9.2 Acknowledgments</A>
+</H2>
+
+<P>
+Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code
+generator, Debugger, AVR port
+<BR>
+Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX
+& ASLINK.
+<BR>
+John Hartman (jhartman@compuserve.com) - Porting ASXXX & ASLINK for
+8051
+<BR>
+Dmitry S. Obukhov (dso@usa.net) - malloc & serial i/o routines.
+<BR>
+Daniel Drotos <drdani@mazsola.iit.uni-miskolc.hu> - for his Freeware
+simulator
+<BR>
+Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience
+and support.
+<BR>
+Unknown - for the GNU C - preprocessor.
+<BR>
+Michael Hope - The Z80 and Z80GB port, 186 development
+<BR>
+Kevin Vigor - The DS390 port.
+<BR>
+Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
+<BR>
+Scott Datallo - PIC port.
+<BR>(Thanks to all the other volunteer developers who have helped with
+coding, testing, web-page creation, distribution sets, etc. You know
+who you are :-)
+<BR>
+<P>
+This document initially written by Sandeep Dutta
+
+<P>
+All product names mentioned herein may be trademarks of their respective
+companies.
+
+<P>
+<A NAME="1284"></A>
+
+<H1><A NAME="SECTION000110000000000000000">
+About this document ...</A>
+</H1>
+ <STRONG>SDCC Compiler User Guide</STRONG><P>
+This document was generated using the
+<A HREF="http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 2K.1beta (1.47)
+<P>
+Copyright © 1993, 1994, 1995, 1996,
+<A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>,
+Computer Based Learning Unit, University of Leeds.
+<BR>
+Copyright © 1997, 1998, 1999,
+<A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>,
+Mathematics Department, Macquarie University, Sydney.
+<P>
+The command line arguments were: <BR>
+ <STRONG>latex2html</STRONG> <TT>-no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir72816uWRHo/lyx_tmpbuf7281E6F6dg/SDCCUdoc.tex</TT>
+<P>
+The translation was initiated by Karl Bongers on 2001-07-02<HR>
+<!--Navigation Panel-->
+<IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
+ SRC="file:/usr/share/latex2html/icons/nx_grp_g.png">
+<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
+ SRC="file:/usr/share/latex2html/icons/up_g.png">
+<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
+ SRC="file:/usr/share/latex2html/icons/prev_g.png">
+<BR>
+<!--End of Navigation Panel-->
+<ADDRESS>
+Karl Bongers
+2001-07-02
+</ADDRESS>
</BODY>
</HTML>
projects / fw / sdcc / blobdiff